bulls-cows 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 命令获取变更文件，合并去重后按以下规则过滤：
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 注释块的格式对齐（不改变语义）
仅在用户明确要求时：
- 对分析结果不准确的部分进行修正
- 调整注释格式或内容
相关资源
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。该文件仅供用户参考，不影响技能执行流程。