yy-frontend-change-log

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

描述

为前端项目文件（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 命令获取变更文件，合并去重后按以下规则过滤：
```
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 句）。
变更记录：本次追加的时间戳与改动摘要。

示例：

✅ 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 注释块的格式对齐（不改变语义）

仅在用户明确要求时：

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

用户参考（非执行指令）

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

yy-frontend-change-log