# Yy Frontend Change Log

> 分析前端项目文件的业务职责、数据流、交互关系和组件逻辑，生成结构化业务说明与改动记录。 当用户需要变更日志、改动记录、业务说明、代码交接文档、组件逻辑梳理或组件文档化时触发。 不用于审核代码质量、修改组件实现，也不用于后端代码或添加普通行内注释。

- Skill: `bulls-cows/yy-frontend-change-log` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-frontend-change-log`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-frontend-change-log/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-frontend-change-log

---


# yy-frontend-change-log

## 描述

为前端项目文件（Vue2/Vue3/React/JS/TS/样式/文档/测试）生成结构化业务说明和变更记录，将注释块追加到文件顶部并保留历史记录。支持组件级逻辑分析、数据流梳理和改动追踪。

## 使用场景

- 用户需要变更日志、改动记录或业务说明
- 用户需要代码交接文档或组件文档化
- 用户需要组件逻辑梳理或页面逻辑整理
- 提交代码前或代码审查前需要整理文件说明
- 新人接手项目时需要了解前端文件业务逻辑

不应触发：

- 审核前端代码质量或修改组件实现
- 为后端代码生成说明
- 为纯函数添加普通行内注释

## 核心原则

**仅追加注释，不修改业务逻辑、原有代码结构或 `import` 语句。** 这一原则贯穿所有步骤，尤其是步骤 5 注入注释时——绝不能因注入注释而改变文件的运行行为。

## 指令

### 步骤 1. 识别文件类型

根据文件语法特征识别项目类型，用于决定注释注入位置和业务分析策略：

- **Vue3**：`.vue` 文件使用 `<script setup>` 或 Composition API
- **Vue2**：`.vue` 文件使用 Options API
- **React**：导入 `react` 或使用 JSX/TSX 语法
- **JS/TS 纯脚本**：`.js`、`.ts` 文件，无框架特征
- **样式文件**：`.css`、`.scss`、`.less`
- **文档/测试文件**：`.md`、`.txt`、`.test.*`、`.spec.*`

无法识别时，根据扩展名推断默认处理方式。

### 步骤 2. 获取分析目标

**决策分支**：

- **用户指定文件或目录**：优先使用用户指定范围，递归收集匹配类型的文件。
- **用户未指定范围**：使用 git 命令获取变更文件，合并去重后按以下规则过滤：

  ```bash
  git diff --name-only HEAD
  git diff --cached --name-only
  ```

**默认处理的文件类型**：

| 类别           | 扩展名 / 文件名                                |
| -------------- | ---------------------------------------------- |
| 源代码文件     | `.ts`、`.js`、`.vue`、`.jsx`、`.tsx`           |
| 依赖与脚本声明 | `package.json` 等                              |
| 文档文件       | `.md`、`.txt`                                  |
| 样式文件       | `.css`、`.scss`、`.less`                       |
| 测试文件       | `.test.ts`、`.test.js`、`.spec.ts`、`.spec.js` |

**默认不处理的文件（仅在用户明确授权时放行）**：

| 类别           | 典型文件                                                                                       |
| -------------- | ---------------------------------------------------------------------------------------------- |
| 构建与工具配置 | `vite.config.ts`、`vue.config.js`、`webpack.config.js`、`tsconfig.json`、`eslint.config.js` 等 |
| 环境配置       | `.env`、`.env.test`、`.env.production`、`.env.local` 等                                        |
| 凭证与私钥     | `credentials.json`、`secrets.*`、`*.key`、`*.pem` 等                                           |

**异常降级**：

- **项目无 git**：提示用户手动指定文件范围，或使用当前目录下所有匹配文件。
- **git diff 失败**：跳过 diff 分析，仅基于文件当前内容生成业务说明。
- **文件为空或仅含模板代码**：标记为"初始文件"，生成简略说明。
- **无匹配文件**：回复"当前没有需要分析的变更文件。"并终止。

### 步骤 3. 分析文件业务结构

对每个目标文件执行结构化业务分析。详细的分析工作流、基础分析项、扩展逻辑梳理项和通用规则详见 `resources/analysis-workflow.md`。

识别为具体框架类型后，按对应框架专属规则执行分析：

- **Vue2 专属规则**：详见 `resources/vue2-rules.md`
- **Vue3 专属规则**：详见 `resources/vue3-rules.md`
- **React 专属规则**：详见 `resources/react-rules.md`

**Reference 加载时机**：仅在需要执行对应分析时才读取 reference 文件——如果目标文件全部为 Vue3，则无需读取 `vue2-rules.md` 和 `react-rules.md`；如果用户仅需要变更记录而非逻辑梳理，则无需读取 `output-template.md`。

**决策分支**：

- **组件超过 200 行**：注释块中的业务说明仅保留核心职责和数据流（一行概述），详细逻辑放入逻辑梳理输出。
- **用户需求侧重变更记录**：业务说明精简到 1-2 句概述。
- **用户需求侧重逻辑梳理**：按完整分析项展开。

**业务说明更新规则**：

- 每次执行时**重新分析并更新业务说明部分**，使其始终反映代码当前状态。
- 变更记录部分不受影响，仅追加不修改。

### 步骤 4. 提取改动摘要

**决策分支**：

- **已有文件（有 diff 记录）**：执行 git diff，提取变更摘要。
- **新建文件（git status 为 `??` 或 `A`）**：跳过 diff，直接生成完整业务说明 + 变更记录 `feat(<scope>): 初始创建`。

### 步骤 5. 生成注释块并注入

**生成时间戳前**，先执行 `date "+%Y-%m-%d %H:%M:%S"` 获取当前真实本地时间。AI 不具备系统时钟感知能力，不得自行推算或猜测时间。

按文件类型生成 JSDoc 注释块并注入文件头部。详细的注释格式、注入位置、改动类型分类、Scope 推断规则和历史记录合并规则详见 `resources/annotation-format.md`。

**合并规则**：当同一小时内对同一文件执行多次时，变更记录合并到同一条，时间戳更新为最新一次执行时间，取类型优先级更高的前缀。

### 步骤 6. 输出结果

对每个目标文件输出：

- **文件路径**：相对路径。
- **项目类型**：Vue3 / Vue2 / React / JS / TS / 样式 / 文档。
- **注入位置**：文件顶部 / `<script>` 内部顶部。
- **业务摘要**：职责（1 句）。
- **变更记录**：本次追加的时间戳与改动摘要。

示例：

```text
✅ src/views/User/index.vue
   项目类型: Vue3
   注入位置: <script setup> 内部顶部
   职责: 用户管理页面，支持列表展示、搜索和编辑
   变更记录: 2025-01-15 14:32:07 | feat(user): 新增搜索过滤功能
```

当用户需求侧重逻辑梳理（而非变更记录）时，按 `resources/output-template.md` 的结构输出分析结果。图表仅在依赖关系或状态流转较复杂时生成（Mermaid 语法仅用于流程图、时序图和状态图），简单场景用列表即可。

## 安全边界

**禁止主动执行**：

- 执行 git commit / git push
- 修改 `.vue` 的 `<template>` / `<style>` 部分
- 覆盖或替换已有变更记录（仅允许追加）
- 修改文件顶部已有的非格式注释内容（如 `@param`、`//` 行注释等）

**允许覆盖更新**（仅限注释块内部）：

- 业务说明部分：每次执行时重新分析并覆盖，确保反映代码当前状态
- 已有 JSDoc 注释块的格式对齐（不改变语义）

**仅在用户明确要求时**：

- 对分析结果不准确的部分进行修正
- 调整注释格式或内容

## 相关资源

- `resources/analysis-workflow.md` - 逻辑梳理工作流、基础分析项与通用规则
- `resources/vue2-rules.md` - Vue2 专属分析规则
- `resources/vue3-rules.md` - Vue3 专属分析规则
- `resources/react-rules.md` - React 专属分析规则
- `resources/annotation-format.md` - 注释格式、注入位置与历史记录合并规则
- `resources/output-template.md` - 逻辑梳理输出模板

## 用户参考（非执行指令）

本技能可集成到 AI 编码助手中，在提交代码前自动为变更文件生成业务说明和变更记录。集成方式详见 `resources/ai-integration.md`。该文件仅供用户参考，不影响技能执行流程。