2026-04-16-22-12-00 - 建立项目修改需求工作流规范（含需求分析、实现方案、测试方案、经验记录、Gitea备份流程）

2026-04-16 22:13:17 +08:00
parent c55a55a27b
commit 915e169bd8
1 changed files with 195 additions and 0 deletions
--- a/.agents/skills/medical-report-dev-workflow/SKILL.md
+++ b/.agents/skills/medical-report-dev-workflow/SKILL.md
@@ -0,0 +1,195 @@
+---
+name: medical-report-dev-workflow
+description: 手术图文病历报告系统（Gemini-图文报告系统）的项目修改需求专用工作流。当用户提出任何与该项目相关的代码修改、功能开发、Bug 修复、性能优化、UI 调整、需求变更等任务时，必须严格按此工作流执行。不适用于纯问答、查询信息、或不涉及代码修改的任务。
+---
+
+# 手术图文病历报告系统 — 项目修改工作流
+
+> 本文档是 AI 编码代理执行项目修改需求时的强制性规范。任何涉及代码变更的任务必须按以下步骤逐一执行，严禁跳过或合并步骤。
+
+## 前置检查
+
+- **确认任务类型**：如果用户请求不涉及代码/配置/文件修改（如纯提问、查资料、解释概念），则无需使用此工作流。
+- **确认当前工作目录**：所有路径均相对于 `C:\Users\Administrator\Downloads\Gemini-图文报告系统-V1.2`（项目根目录）。
+
+---
+
+## Step 0：记录时间戳
+
+**任务开始后的第一件事**：获取当前时间并格式化为 `YYYY-MM-DD-HH-MM-SS`（如 `2026-04-16-21-30-00`）。
+
+- 将该时间戳保存到工作上下文中（如变量 `workflowTimestamp`）。
+- 所有后续文档的文件名必须以此时间戳结尾。
+
+---
+
+## Step 1：创建工程分析目录
+
+在**项目根目录**下创建文件夹：
+```
+.\工程分析\
+```
+
+如果该目录已存在，则无需重复创建。
+
+---
+
+## Step 2：需求分析
+
+1. 仔细阅读用户提出的需求，拆解成功能点与非功能点。
+2. 分析影响范围（修改哪些文件、是否有风险点）。
+3. 将分析结果写入文件：
+   ```
+   .\工程分析\需求分析-{workflowTimestamp}.md
+   ```
+4. 文档结构模板：
+   ```markdown
+   # 需求分析 — {workflowTimestamp}
+
+   ## 原始需求摘要
+   （用户原话或提炼后的核心诉求）
+
+   ## 需求拆解
+
+   ### 功能点
+   - 
+
+   ### 非功能点
+   - 
+
+   ## 影响范围预估
+
+   | 模块 | 影响程度 | 说明 |
+   |------|---------|------|
+   |      |         |      |
+
+   ## 待确认问题
+   （如有，列出需要用户确认的内容）
+   ```
+
+---
+
+## Step 3：实现方案
+
+1. 基于需求分析，设计详细的实现方案：
+   - 根因分析（如果是 Bug 修复）
+   - 修改文件清单
+   - 具体代码变更（含前后对比）
+   - 风险点与应对措施
+   - 回滚策略
+2. 将方案写入文件：
+   ```
+   .\工程分析\实现方案-{workflowTimestamp}.md
+   ```
+3. **必须停止执行，向用户展示实现方案文档内容，并请求人工审核确认。**
+   - 提示语："实现方案已完成，请审核 `.\工程分析\实现方案-{workflowTimestamp}.md`。确认无误后回复「确认」或提出修改意见，我将继续编写测试方案。"
+4. **在得到用户明确确认（如回复"确认"、"同意"、"OK"）之前，禁止进入下一步。**
+
+---
+
+## Step 4：测试方案
+
+1. 基于实现方案设计测试用例：
+   - 测试目标
+   - 测试环境
+   - 测试用例（步骤、操作、预期结果）
+   - 验收标准（勾选列表）
+   - 测试方式（手工/自动化）
+2. 将方案写入文件：
+   ```
+   .\工程分析\测试方案-{workflowTimestamp}.md
+   ```
+3. **必须停止执行，向用户展示测试方案文档内容，并请求人工审核确认。**
+   - 提示语："测试方案已完成，请审核 `.\工程分析\测试方案-{workflowTimestamp}.md`。确认无误后回复「确认」或提出修改意见，我将进入最终执行阶段。"
+4. **在得到用户明确确认之前，禁止进入下一步。**
+
+---
+
+## Step 5：执行修改
+
+### 5.1 执行前必读
+
+在动手修改任何代码之前，**必须阅读**：
+```
+.\工程分析\经验记录.md
+```
+
+将该文档中的关键经验教训纳入本次执行的注意事项中，防止重复犯错。
+
+### 5.2 执行修改
+
+1. 严格按照已审核通过的实现方案修改代码。
+2. 每次修改后应进行必要的验证（如 `npm run lint`、本地编译检查、关键路径手工验证）。
+3. 如果在执行过程中遇到**任何未在实现方案中预料到的问题**（包括修改范围扩大、发现新的 Bug、遇到环境异常、实现方案中的假设不成立等），必须：
+   - 先解决问题
+   - 然后在 `经验记录.md` 中记录
+
+### 5.3 更新经验记录
+
+执行完成后，检查本次过程中是否出现了值得记录的关键问题。如果有，在 `.\工程分析\经验记录.md` 中追加记录，使用**统一的四段式格式**：
+
+```markdown
+---
+
+## 记录 N：标题
+
+**A. 具体问题**
+（清晰描述现象）
+
+**B. 产生问题原因**
+（根因分析，可多条）
+
+**C. 解决问题方案**
+（具体修改了什么）
+
+**D. 后续如何避免问题**
+（可执行的建议）
+```
+
+如果 `经验记录.md` 不存在，则创建它，并在顶部加入 `# 经验记录` 标题。
+
+---
+
+## Step 6：Gitea 备份
+
+1. 在项目根目录执行以下 Git 操作：
+   ```bash
+   git add .\工程分析\
+   git commit -m "{workflowTimestamp} - {本次修改的简要描述}"
+   git push origin main
+   ```
+   - 简要描述应概括本次修改的核心内容（如 "修复路由切换后关键帧丢失问题"、"新增自动帧插入非阻塞优化" 等）。
+   - 如果只修改了工程分析文档而没有改代码（理论上不应发生），也应提交这些文档。
+2. 备份完成后，**必须向用户明确提醒**：
+   > "本次工作流相关文档已备份到 Gitea，commit 信息为：`{workflowTimestamp} - {简要描述}`。"
+
+---
+
+## 禁忌清单（严禁事项）
+
+- ❌ 严禁跳过实现方案审核直接进入代码修改。
+- ❌ 严禁跳过测试方案审核直接执行测试。
+- ❌ 严禁未阅读 `经验记录.md` 就动手改代码。
+- ❌ 严禁执行完成后不更新 `经验记录.md`（如有新问题）。
+- ❌ 严禁执行完成后不进行 Gitea 备份。
+- ❌ 严禁在需求分析、实现方案、测试方案文档中使用不明确的描述，应具体到文件路径和函数名。
+
+---
+
+## 快速参考：常用命令
+
+```bash
+# 类型检查
+npm run lint
+
+# 生产构建
+npm run build
+
+# 启动预览服务
+npm run preview -- --host 0.0.0.0
+
+# Git 备份
+git add .\工程分析\
+git commit -m "{timestamp} - {描述}"
+git push origin main
+```