yy-frontend-change-log

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

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。该文件仅供用户参考，不影响技能执行流程。