2026-04-17-22-53-01 - 新建项目修改工作流Skill并创建统一经验记录

.agents/skills/medical-report-dev-workflow/SKILL.md

@@ -1,48 +1,57 @@
 ---
 name: medical-report-dev-workflow
-description: 手术图文病历报告系统（Gemini-图文报告系统）的项目修改需求专用工作流。当用户提出任何与该项目相关的代码修改、功能开发、Bug 修复、性能优化、UI 调整、需求变更等任务时，必须严格按此工作流执行。不适用于纯问答、查询信息、或不涉及代码修改的任务。
+description: |
+  手术图文病历报告系统（Gemini-图文报告系统）的强制性项目修改工作流。
+  当用户提出任何与该项目相关的代码修改、功能开发、Bug 修复、性能优化、UI 调整、
+  需求变更等任务时，**必须严格按此工作流逐步执行，严禁跳过或合并步骤**。
+  不适用于纯问答、查询信息、阅读文档或不涉及代码/文件修改的任务。
 ---
 
-# 手术图文病历报告系统 — 项目修改工作流
+# 手术图文病历报告系统 — 项目修改工作流（v2.0）
 
-> 本文档是 AI 编码代理执行项目修改需求时的强制性规范。任何涉及代码变更的任务必须按以下步骤逐一执行，严禁跳过或合并步骤。
+> 本文档是 AI 编码代理执行项目修改需求时的**强制性规范**。任何涉及代码变更的任务必须按以下 7 个步骤逐一执行，每一步有明确的停止/确认点，严禁跳过。
+
+---
 
 ## 前置检查
 
-- **确认任务类型**：如果用户请求不涉及代码/配置/文件修改（如纯提问、查资料、解释概念），则无需使用此工作流。
-- **确认当前工作目录**：所有路径均相对于 `C:\Users\Administrator\Downloads\Gemini-图文报告系统-V1.2`（项目根目录）。
+- **确认任务类型**：如果用户请求不涉及代码/配置/文件修改（如纯提问、查资料、解释概念），则**不启用**此工作流。
+- **确认当前工作目录**：所有路径均相对于项目根目录 `C:\Users\Administrator\Downloads\Gemini-图文报告系统-V1.2`。
 
 ---
 
 ## Step 0：记录时间戳
 
-**任务开始后的第一件事**：获取当前时间并格式化为 `YYYY-MM-DD-HH-MM-SS`（如 `2026-04-16-21-30-00`）。
+**任务开始后的第一件事**：获取当前系统时间并格式化为 `YYYY-MM-DD-HH-MM-SS`（示例：`2026-04-17-22-53-01`）。
 
-- 将该时间戳保存到工作上下文中（如变量 `workflowTimestamp`）。
-- 所有后续文档的文件名必须以此时间戳结尾。
+- 将该时间戳保存到工作上下文中（变量名建议：`workflowTimestamp`）。
+- **所有后续产出的文档文件名必须以此时间戳结尾**。
 
 ---
 
-## Step 1：创建工程分析目录
+## Step 1：工程分析目录
 
-在**项目根目录**下创建文件夹：
-```
-.\工程分析\
-```
-
-如果该目录已存在，则无需重复创建。
+1. 检查并确认项目根目录下存在文件夹：
+   ```
+   .\工程分析\
+   ```
+2. 若不存在，则立即创建。
+3. 同时检查该目录下是否存在 `经验记录.md`；若不存在，创建一个空文件并在顶部写入 `# 经验记录`。
 
 ---
 
-## Step 2：需求分析
+## Step 2：需求分析文档
 
-1. 仔细阅读用户提出的需求，拆解成功能点与非功能点。
-2. 分析影响范围（修改哪些文件、是否有风险点）。
-3. 将分析结果写入文件：
+1. 仔细阅读用户提出的原始需求，将其拆解为：
+   - **功能点**：具体要实现什么
+   - **非功能点**：性能、兼容性、向后兼容、安全性等要求
+   - **影响范围**：预估需要修改的模块/文件及影响程度
+   - **待确认问题**：如有需求模糊之处，列出请用户澄清
+2. 将分析结果写入文件：
    ```
    .\工程分析\需求分析-{workflowTimestamp}.md
    ```
-4. 文档结构模板：
+3. 文档模板：
    ```markdown
    # 需求分析 — {workflowTimestamp}
 
@@ -52,12 +61,13 @@ description: 手术图文病历报告系统（Gemini-图文报告系统）的项
    ## 需求拆解
 
    ### 功能点
-   - 
+   - F1：...
+   - F2：...
 
    ### 非功能点
    - 
 
-   ## 影响范围预估
+   ## 影响范围
 
    | 模块 | 影响程度 | 说明 |
    |------|---------|------|
@@ -69,43 +79,45 @@ description: 手术图文病历报告系统（Gemini-图文报告系统）的项
 
 ---
 
-## Step 3：实现方案
+## Step 3：实现方案文档
 
 1. 基于需求分析，设计详细的实现方案：
-   - 根因分析（如果是 Bug 修复）
-   - 修改文件清单
-   - 具体代码变更（含前后对比）
-   - 风险点与应对措施
-   - 回滚策略
+   - **根因分析**（如果是 Bug 修复，必须说明根因）
+   - **修改文件清单**（精确到文件路径）
+   - **具体代码变更**（含关键代码的前后对比或伪代码）
+   - **风险点与应对措施**
+   - **回滚策略**
 2. 将方案写入文件：
    ```
    .\工程分析\实现方案-{workflowTimestamp}.md
    ```
-3. **必须停止执行，向用户展示实现方案文档内容，并请求人工审核确认。**
-   - 提示语："实现方案已完成，请审核 `.\工程分析\实现方案-{workflowTimestamp}.md`。确认无误后回复「确认」或提出修改意见，我将继续编写测试方案。"
-4. **在得到用户明确确认（如回复"确认"、"同意"、"OK"）之前，禁止进入下一步。**
+3. **🛑 强制停止点**：向用户展示实现方案文档内容，并请求人工审核确认。
+   - 标准提示语：
+     > 实现方案已完成，请审核 `.\工程分析\实现方案-{workflowTimestamp}.md`。确认无误后回复「确认」或提出修改意见，我将继续编写测试方案。
+   - **在得到用户明确确认（如回复"确认"、"同意"、"OK"）之前，禁止进入下一步。**
 
 ---
 
-## Step 4：测试方案
+## Step 4：测试方案文档
 
-1. 基于实现方案设计测试用例：
-   - 测试目标
-   - 测试环境
-   - 测试用例（步骤、操作、预期结果）
-   - 验收标准（勾选列表）
-   - 测试方式（手工/自动化）
+1. 基于已审核通过的实现方案，设计测试方案：
+   - **测试目标**
+   - **测试环境**
+   - **测试用例**（步骤、操作、预期结果，以表格形式呈现）
+   - **验收标准**（勾选列表 `\- [ ]` 形式）
+   - **测试方式**（手工 / 自动化，本项目目前无自动化测试框架，通常为手工验证）
 2. 将方案写入文件：
    ```
    .\工程分析\测试方案-{workflowTimestamp}.md
    ```
-3. **必须停止执行，向用户展示测试方案文档内容，并请求人工审核确认。**
-   - 提示语："测试方案已完成，请审核 `.\工程分析\测试方案-{workflowTimestamp}.md`。确认无误后回复「确认」或提出修改意见，我将进入最终执行阶段。"
-4. **在得到用户明确确认之前，禁止进入下一步。**
+3. **🛑 强制停止点**：向用户展示测试方案文档内容，并请求人工审核确认。
+   - 标准提示语：
+     > 测试方案已完成，请审核 `.\工程分析\测试方案-{workflowTimestamp}.md`。确认无误后回复「确认」或提出修改意见，我将进入最终执行阶段。
+   - **在得到用户明确确认之前，禁止进入下一步。**
 
 ---
 
-## Step 5：执行修改
+## Step 5：执行修改 & 经验记录
 
 ### 5.1 执行前必读
 
@@ -114,72 +126,94 @@ description: 手术图文病历报告系统（Gemini-图文报告系统）的项
 .\工程分析\经验记录.md
 ```
 
-将该文档中的关键经验教训纳入本次执行的注意事项中，防止重复犯错。
+- 将该文档中的关键经验教训纳入本次执行的注意事项。
+- 尤其关注与本次修改相关的历史踩坑点，防止重复犯错。
 
 ### 5.2 执行修改
 
 1. 严格按照已审核通过的实现方案修改代码。
-2. 每次修改后应进行必要的验证（如 `npm run lint`、本地编译检查、关键路径手工验证）。
-3. 如果在执行过程中遇到**任何未在实现方案中预料到的问题**（包括修改范围扩大、发现新的 Bug、遇到环境异常、实现方案中的假设不成立等），必须：
+2. 每次修改后应进行必要的验证（如 `npm run lint`、本地编译检查）。
+3. 如果在执行过程中遇到**任何未在实现方案中预料到的问题**（包括修改范围扩大、发现新的 Bug、环境异常、方案假设不成立等），必须：
    - 先解决问题
-   - 然后在 `经验记录.md` 中记录
+   - 然后将问题及解决方案记录到 `经验记录.md` 中（见 5.3）
 
 ### 5.3 更新经验记录
 
-执行完成后，检查本次过程中是否出现了值得记录的关键问题。如果有，在 `.\工程分析\经验记录.md` 中追加记录，使用**统一的四段式格式**：
+执行完成后，检查本次过程中是否出现了值得记录的关键问题。如果有，在 `.\工程分析\经验记录.md` 中**追加**记录，使用**统一的四段式格式**：
 
 ```markdown
 ---
 
-## 记录 N：标题
+## 记录 N：标题（简短概括）
 
 **A. 具体问题**
-（清晰描述现象）
+（清晰描述现象，包括复现步骤）
 
 **B. 产生问题原因**
-（根因分析，可多条）
+（根因分析，可多条，避免表面归因）
 
 **C. 解决问题方案**
-（具体修改了什么）
+（具体修改了哪些文件、哪些代码、什么逻辑）
 
 **D. 后续如何避免问题**
-（可执行的建议）
+（可执行的建议，供未来需求参考）
 ```
 
-如果 `经验记录.md` 不存在，则创建它，并在顶部加入 `# 经验记录` 标题。
+- 记录编号按顺序递增（如记录 1、记录 2……）。
+- 如果 `经验记录.md` 原本为空或不存在，创建后顶部加 `# 经验记录`，然后写入第一条记录。
 
 ---
 
 ## Step 6：Gitea 备份
 
-1. 在项目根目录执行以下 Git 操作：
-   ```bash
-   git add .\工程分析\
-   git commit -m "{workflowTimestamp} - {本次修改的简要描述}"
-   git push origin main
-   ```
-   - 简要描述应概括本次修改的核心内容（如 "修复路由切换后关键帧丢失问题"、"新增自动帧插入非阻塞优化" 等）。
-   - 如果只修改了工程分析文档而没有改代码（理论上不应发生），也应提交这些文档。
-2. 备份完成后，**必须向用户明确提醒**：
-   > "本次工作流相关文档已备份到 Gitea，commit 信息为：`{workflowTimestamp} - {简要描述}`。"
+### 6.1 首次备份（仓库未初始化时）
+
+如果项目根目录下**没有 `.git` 目录**或没有配置 remote，执行：
+```bash
+git init
+git checkout -b main
+git add README.md
+# 若 README.md 不存在，先创建：echo "# Medical Sur Report" > README.md
+git commit -m "first commit"
+git remote add origin http://192.168.31.5:5002/admin/Mdeical_Sur_Report.git
+git push -u origin main
+```
+
+### 6.2 日常备份（已有仓库时）
+
+执行以下 Git 操作，将本次工作流产出的文档（工程分析目录）备份到 Gitea：
+```bash
+git add .\工程分析\
+git commit -m "{workflowTimestamp} - {本次修改的简要描述}"
+git push origin main
+```
+
+- **简要描述**应概括本次修改的核心内容（如 "修复路由切换后关键帧丢失问题"、"新增自动帧插入非阻塞优化" 等），控制在 50 字以内。
+- 如果同时修改了源代码，也应将源码变更一并 `git add` 并提交。
+
+### 6.3 备份完成提醒
+
+备份完成后，**必须向用户明确提醒**：
+> 本次工作流相关文档（及代码修改）已备份到 Gitea，commit 信息为：`{workflowTimestamp} - {简要描述}`。
 
 ---
 
 ## 禁忌清单（严禁事项）
 
-- ❌ 严禁跳过实现方案审核直接进入代码修改。
-- ❌ 严禁跳过测试方案审核直接执行测试。
-- ❌ 严禁未阅读 `经验记录.md` 就动手改代码。
-- ❌ 严禁执行完成后不更新 `经验记录.md`（如有新问题）。
-- ❌ 严禁执行完成后不进行 Gitea 备份。
-- ❌ 严禁在需求分析、实现方案、测试方案文档中使用不明确的描述，应具体到文件路径和函数名。
+- ❌ **严禁跳过实现方案审核直接进入代码修改。**
+- ❌ **严禁跳过测试方案审核直接执行测试或部署。**
+- ❌ **严禁未阅读 `经验记录.md` 就动手改代码。**
+- ❌ **严禁执行完成后不更新 `经验记录.md`（如有新问题）。**
+- ❌ **严禁执行完成后不进行 Gitea 备份。**
+- ❌ **严禁在需求分析、实现方案、测试方案文档中使用不明确的描述**，应具体到文件路径、函数名、CSS 类名。
+- ❌ **严禁在 Step 3 / Step 4 的用户确认阶段擅自推进**，必须等待用户明确回复。
 
 ---
 
 ## 快速参考：常用命令
 
 ```bash
-# 类型检查
+# 类型检查（修改后必须执行）
 npm run lint
 
 # 生产构建
@@ -188,7 +222,7 @@ npm run build
 # 启动预览服务
 npm run preview -- --host 0.0.0.0
 
-# Git 备份
+# Gitea 日常备份
 git add .\工程分析\
 git commit -m "{timestamp} - {描述}"
 git push origin main