@huajiwuyan/hello 3.0.0

package/templates/codex/skills/references/stages/develop.md

@@ -0,0 +1,520 @@
+# 开发实施模块
+
+本模块定义开发实施阶段的详细执行规则，执行方案包中的任务清单。
+
+**核心职责:** 执行 tasks.md 中的任务清单，通过子代理完成代码修改和知识库同步。
+
+---
+
+## 模块入口
+
+### 触发条件
+
+```yaml
+前置条件:
+  NATURAL入口: 方案设计阶段完成（选择方案后自动流转）
+  DIRECT入口: 用户执行 ~exec 命令
+
+加载时机:
+  NATURAL: 方案设计完成后流转
+  DIRECT: ~exec 命令触发
+
+特点: 执行方案包中的任务清单，修改代码，同步知识库
+```
+
+### 状态设置
+
+```yaml
+设置时机: 本模块被加载时
+设置内容:
+  - CURRENT_STAGE = DEVELOP
+  - STAGE_ENTRY_MODE = NATURAL（从方案设计流转）或 DIRECT（~exec命令）
+```
+
+---
+
+## 执行模式适配
+
+<mode_adaptation>
+
+### 模式行为
+
+```yaml
+读取状态变量: WORKFLOW_MODE, STAGE_ENTRY_MODE
+
+# === 入口方式判定 ===
+
+STAGE_ENTRY_MODE = NATURAL（从方案设计流转）:
+  方案包来源: 读取 CREATED_PACKAGE 变量
+  单个方案包: 直接执行
+
+STAGE_ENTRY_MODE = DIRECT（~exec命令直接进入）:
+  方案包来源: 扫描 plan/ 目录
+  单个方案包: 自动选择
+  多个方案包: 按G3场景内容规则（确认场景）输出，等待用户选择
+
+# === 执行模式 ===
+
+"交互模式"（INTERACTIVE，默认）:
+  执行下方"执行流程"步骤1-15
+  质量问题: 询问用户决定
+  完成后: 按G3场景内容规则（完成场景）输出执行结果
+  **STOP HERE. Do NOT start new tasks until user confirms.**
+
+"全授权模式"（AUTO_FULL，~auto命令）:
+  静默执行下方"执行流程"步骤1-15（不输出中间状态）
+  质量问题: 在总结中列出（不询问）
+  完成后: 按G3场景内容规则（完成场景）输出全授权命令结果（整体总结）
+  执行: 按 G6 状态重置协议执行
+
+"执行命令入口"（~exec，STAGE_ENTRY_MODE=DIRECT）:
+  执行下方"执行流程"步骤1-15
+  完成后: 按G3场景内容规则（完成场景）输出执行命令结果
+  执行: 按 G6 状态重置协议执行
+```
+
+### 方案包选择逻辑（~exec入口）
+
+```yaml
+步骤1 - 扫描plan/目录
+
+步骤2 - 判断数量:
+  0个方案包: 按G3场景内容规则（错误场景）输出，流程终止
+  1个方案包: 自动选择，设置CURRENT_PACKAGE，继续执行
+  多个方案包: 按G3场景内容规则（确认场景）输出方案包选择清单，等待用户选择
+
+步骤3 - 验证方案包完整性:
+  缺失文件: 按G3场景内容规则（错误场景）输出，流程终止
+```
+
+### 阶段流转
+
+```yaml
+执行阶段完成后:
+  步骤1: 执行步骤15遗留方案包扫描（如有遗留方案包则显示提示）
+  步骤2: 执行流程级验收
+    验收规则: 按 G8 "流程级验收规则" 执行
+    验收内容: 交付物验收 + 需求符合性 + 问题汇总
+  步骤3: 输出完成结果
+    输出: 按G3场景内容规则（完成场景）输出
+    内容: 验收报告 + 变更摘要 + 遗留方案包提示（如有）
+  步骤4: 输出进度快照（按 attention.md 规范）
+  步骤5: 状态重置
+    执行: 按 G6 状态重置协议执行
+
+注意: 如果是从 auto.md 调用，流程级验收由 auto.md 步骤7统一执行
+```
+
+</mode_adaptation>
+
+---
+
+## 执行流程
+
+**重要:** 所有文件操作遵循静默执行规范（不输出文件内容、diff、代码片段）
+
+### 步骤1: 确定待执行方案包
+
+> 脚本路径、存在性检查、错误恢复规则见 references/rules/tools.md
+
+**脚本:** `list_packages.py`
+
+```yaml
+全授权命令（WORKFLOW_MODE=AUTO_FULL）:
+  - 读取 CREATED_PACKAGE 变量（方案设计阶段设置的方案包路径）
+  - 检查该方案包是否存在且完整
+    - 存在且完整 → 使用该方案包，设置 CURRENT_PACKAGE = CREATED_PACKAGE
+    - 不存在或不完整 → 按G3场景内容规则（错误场景）输出并停止
+  - 忽略 plan/ 中的其他遗留方案包
+
+交互确认模式/执行命令（STAGE_ENTRY_MODE=DIRECT）:
+  - 扫描 plan/ 目录下所有方案包
+  - 不存在方案包 → 按G3场景内容规则（错误场景）输出并停止
+  - 方案包不完整 → 按G3场景内容规则（错误场景）输出并停止
+  - 单个完整方案包 → 设置 CURRENT_PACKAGE，继续执行
+  - 多个方案包 → 列出清单，等待用户选择
+    - 用户输入有效序号(1-N) → 设置 CURRENT_PACKAGE，继续执行
+    - 用户输入取消/拒绝 → 按G3场景内容规则（取消场景）输出，流程终止
+    - 无效输入 → 再次询问
+```
+
+### 步骤2: 检查方案包类型（CRITICAL）
+
+按 G6 "方案包类型" 规则执行。
+
+```yaml
+读取 CURRENT_PACKAGE/proposal.md 判断方案包类型
+
+IF 类型 = overview（概述文档）:
+  说明: overview类型方案包无执行任务，直接归档
+  交互确认模式:
+    按G3场景内容规则（确认场景）输出
+
+    用户选择处理:
+      归档: 跳过步骤3-13，直接执行步骤14，状态标记为 "overview"
+      查看: 显示 proposal.md 内容，再次询问
+      取消: 按 G6 状态重置协议执行，流程终止
+
+  全授权命令（WORKFLOW_MODE=AUTO_FULL）:
+    静默执行归档，在完成总结中标注 "概述文档，已归档"
+
+ELSE (类型 = implementation):
+  继续执行步骤3
+```
+
+### 步骤3: 知识库开关检查（CRITICAL）
+
+按 G1 "KB开关检查规则" 和 "KB_SKIPPED 变量生命周期" 执行。
+
+```yaml
+KB_SKIPPED 状态来源:
+  STAGE_ENTRY_MODE = NATURAL（从方案设计流转）:
+    - 由 analyze.md 步骤1 已设置，本阶段直接使用
+  STAGE_ENTRY_MODE = DIRECT（~exec命令直接进入）:
+    - 本阶段首次设置 KB_SKIPPED
+    - 按 G1 "KB开关检查规则" 判定
+
+后续步骤影响:
+  KB_SKIPPED = true: 跳过步骤4，步骤10、12标记跳过
+  步骤11（CHANGELOG）始终执行，按 G1 "目录/文件自动创建规则" 处理
+```
+
+### 步骤4: 检查知识库状态并处理
+
+```yaml
+前置条件: KB_SKIPPED = false
+执行: 按 G1 "KB开关检查规则" 处理知识库状态
+```
+
+### 步骤5: 读取知识库并获取项目上下文
+
+```yaml
+执行方式:
+  - KB_SKIPPED = false: 从知识库读取（INDEX.md, context.md, modules/）
+  - KB_SKIPPED = true 或知识库不足: 直接扫描代码库
+```
+
+### 步骤6: 读取当前方案包
+
+```yaml
+读取: plan/YYYYMMDDHHMM_{feature}/tasks.md 和 proposal.md
+提取: tasks.md 元数据和任务列表
+```
+
+### 步骤7: 按任务清单执行代码改动
+
+> 📌 规则引用: 子代理调用按 G9 "子代理编排 - DEVELOP" + G10 "跨CLI兼容规则" 执行
+
+```yaml
+执行规则:
+  - 严格按 tasks.md 逐项执行
+
+任务成功处理:
+  - 每个任务执行成功后，立即将状态从 [ ] 更新为 [√]
+  - 更新进度快照（见下方"进度快照更新"）
+
+任务跳过处理(状态更新为 [-]):
+  - 任务依赖的前置任务失败
+  - 任务条件不满足
+  - 任务已被其他任务的实现覆盖
+
+任务失败处理(状态更新为 [X]):
+  - 记录错误信息（用于迁移前添加备注）
+  - 保留错误信息在 tasks.md 中（帮助后续避免重复错误）
+  - 继续执行后续任务
+  - 所有任务完成后，如存在失败:
+    - 交互确认模式/执行命令: 列出失败清单，询问用户决定
+      - 用户选择继续 → 继续后续步骤
+      - 用户选择终止 → 输出"已终止执行"，流程终止
+    - 全授权命令（WORKFLOW_MODE=AUTO_FULL）: 在总结中列出失败任务，清除WORKFLOW_MODE（重置为INTERACTIVE）
+
+代码编辑技巧:
+  - 大文件处理(≥2000行): 内容搜索定位 → 文件读取(offset,limit) → 文件编辑精确修改
+  - 每次文件编辑只修改单个函数/类
+```
+
+**进度快照更新（CRITICAL）:**
+
+```yaml
+# 按 G10 注意力控制规则 + attention.md 执行
+
+更新时机: 每次状态变更后（任务完成/失败/跳过）
+
+更新内容:
+  1. 更新 tasks.md 中对应任务的状态符号
+  2. 更新 tasks.md 的 LIVE_STATUS 区域
+  3. 追加执行日志（最近5条）
+
+LIVE_STATUS 区域格式（在 tasks.md 中）:
+  <!-- LIVE_STATUS_BEGIN -->
+  状态: running | 进度: {完成数}/{总数} ({百分比}%) | 更新: {HH:MM:SS}
+  当前: {正在执行的任务描述}
+  <!-- LIVE_STATUS_END -->
+
+目的: 外部监控可通过 tail -f 或 VS Code 实时查看进度
+```
+
+### 步骤8: 代码安全检查
+
+> 按 G2 EHRB 检测规则执行安全检查
+
+```yaml
+检查内容:
+  - 不安全模式（eval、exec、SQL拼接等）
+  - 敏感信息硬编码（对应 G2 敏感数据/PII数据关键词）
+  - EHRB 风险规避（按 G2 关键词检测 + 语义分析）
+
+检测到 EHRB 时: 按 G2 EHRB 处理流程执行
+```
+
+### 步骤9: 测试执行与验证
+
+> 测试分级按 G8 验收分级定义执行
+
+```yaml
+测试策略:
+  原则: 从具体到广泛
+  流程: 先测试修改的代码 → 逐步扩展到更广泛的测试
+  来源: tasks.md定义的测试任务 或 项目已有测试套件
+
+测试失败处理规则（严格执行）:
+  ⛔ 阻断性测试（核心功能）:
+    - 失败必须立即停止执行
+    - 按G3场景内容规则（警告场景）输出
+    - 禁止自动跳过
+
+    用户选择处理:
+      修复: 分析错误原因，修复代码
+      跳过: 跳过该测试，继续执行
+      终止: 终止当前流程
+
+  ⚠️ 警告性测试（重要功能）:
+    - 失败时在总结中标注
+    - 继续执行后续步骤
+
+  ℹ️ 信息性测试（次要功能）:
+    - 失败时在总结中记录
+    - 继续执行后续步骤
+
+代码格式化:
+  原则: 确保代码格式良好
+  迭代: 最多3次修复格式问题
+
+禁止行为:
+  - 不修复无关的错误或失效的测试
+  - 不向没有测试的代码库添加测试
+  - 不向没有格式化器的代码库添加格式化器
+```
+
+### 步骤10: 同步更新知识库
+
+> 📌 规则引用: syncer 子代理调用按 G9 "子代理编排 - DEVELOP" + G10 "跨CLI兼容规则" 执行
+
+```yaml
+前置检查: IF KB_SKIPPED = true → 跳过此步骤，标注"⚠️ 知识库同步已跳过"
+
+重要: 必须在步骤14迁移方案包前完成方案包内容读取
+
+同步内容:
+  必须同步: modules/{模块名}.md（职责、接口、行为规范）、modules/_index.md
+  按需同步: context.md（技术栈变化时）、INDEX.md（结构重大变化时）
+同步原则: 代码是唯一真实来源，最小变更，术语与代码一致
+```
+
+### 步骤11: 更新 CHANGELOG.md（始终执行）
+
+```yaml
+执行条件: 始终执行（不受 KB_SKIPPED 影响）
+原因: 开发实施阶段有方案包和代码变更，必须记录到CHANGELOG
+
+目录/文件创建: 按 G1 "目录/文件自动创建规则" 执行
+  - KB_CREATE_MODE = 0 时: 仅创建 helloagents/ 和 CHANGELOG.md（不创建完整知识库）
+  - KB_CREATE_MODE = 1/2/3 时: 正常创建
+
+格式规范:
+  记录格式: ## [X.Y.Z] - YYYY-MM-DD → ### 分类 → - **[模块名]**: 描述 + 方案链接 + 决策引用
+  分类: 新增/修复/变更/移除
+  方案链接: 使用相对路径指向 archive/ 中的方案包
+版本号管理:
+  获取优先级: 用户指定 > 主模块解析 > Git标签 > CHANGELOG递增
+  自动递增: 破坏性→Major+1, 新功能→Minor+1, 修复→Patch+1
+
+与微调模式的区别:
+  开发实施阶段: 始终记录CHANGELOG（有方案包，必须有变更记录）
+  微调模式: KB_CREATE_MODE=0 且目录不存在时可跳过（见 tweak.md 步骤1）
+```
+
+### 步骤12: 一致性审计
+
+```yaml
+前置检查: IF KB_SKIPPED = true → 跳过此步骤，标注"⚠️ 一致性审计已跳过"
+```
+
+**审计时机:** 执行阶段完成知识库操作后立即执行
+
+**审计内容:**
+1. **完整性**: 文档涵盖所有模块，必备文件和图表齐全
+2. **一致性**: API/数据模型与代码一致，无遗漏、重复、死链
+
+<truth_priority_rules>
+
+**真实性优先级（冲突解决机制）:**
+```
+1. 代码是执行真实性的唯一来源 (Ground Truth)
+   → 运行时行为、API签名、数据结构以代码为准
+
+2. 默认修正方向: 修正知识库以符合代码
+   → 发现不一致时，必须更新文档以反映代码的客观事实
+
+3. 例外（修正代码）:
+   - 知识库是最近创建的方案包（刚设计好的方案）
+   - 代码有明显错误（Bug）
+   - 错误信息指向代码问题
+
+4. 存疑时: 双向验证，优先信任最近的代码变更
+
+5. 微调模式例外: 微调模式不执行完整一致性审计（KB_SKIPPED=true时跳过）
+   → 微调是轻量级操作，由 CHANGELOG 记录变更，不强制同步知识库
+   → 如需完整一致性保证，可在后续执行 ~validate 手动验证
+```
+
+</truth_priority_rules>
+
+### 步骤13: 代码质量分析（可选）
+
+```yaml
+执行内容: 分析代码文件，识别质量问题
+
+如发现问题:
+  交互确认模式:
+    - 按G3场景内容规则（确认场景）输出优化建议
+    - 用户确认 → 执行优化、更新文档、重测
+    - 用户拒绝 → 跳过优化，继续后续步骤
+  全授权命令/执行命令（WORKFLOW_MODE=AUTO_FULL 或 STAGE_ENTRY_MODE=DIRECT）:
+    - 在总结中列出建议（不执行）
+
+提交关联: 如需提交，按项目规范执行
+```
+
+### 步骤14: 迁移已执行方案包至archive/
+
+> 按 references/services/package.md "方案包生命周期管理" 中的迁移规则执行
+> 脚本路径、存在性检查、错误恢复规则见 references/rules/tools.md
+
+**脚本:** `migrate_package.py <package-name>`
+
+⚠️ **CRITICAL - 强制执行规则:**
+
+**不可跳过:** 此步骤为本阶段结束的原子性操作
+
+**目录/文件创建:** 按 G1 "目录/文件自动创建规则" 执行。
+
+**脚本执行报告处理:**
+
+```yaml
+解析 migrate_package.py 输出:
+  success=true:
+    - 迁移完成，继续步骤15
+
+  success=false:
+    - 执行: 按 references/rules/tools.md "脚本执行报告机制 - AI降级接手流程" 处理
+    - 步骤1: 质量检查 completed 列表中已完成的步骤
+      - 验证方案包存在: 确认源路径
+      - 创建归档目录: 确认 archive/YYYY-MM/ 存在
+      - 更新 tasks.md 状态: 检查 @status 行
+      - 移动方案包: 确认目标路径存在且源已删除
+      - 更新 _index.md: 检查索引记录
+    - 步骤2: 发现问题则修复
+    - 步骤3: 按 pending 列表继续完成（参考 templates.md "AI接手时的文件创建指南"）
+```
+
+**执行规则:**
+
+1. 更新tasks.md任务状态和备注:
+   - 所有任务更新为实际执行结果（按 G6 任务状态符号）
+   - 非[√]状态任务下方添加备注（格式: `> 备注: {原因}`）
+   - 如有多个失败/跳过任务，可在末尾添加执行总结章节
+
+2. 迁移至历史记录目录:
+   - 将方案包目录从 plan/ 移动到 archive/YYYY-MM/ 下
+   - YYYY-MM 从方案包目录名提取（如 202501161430_feature → 2025-01）
+   - 迁移后完整路径: archive/YYYY-MM/YYYYMMDDHHMM_feature/
+   - 迁移操作会自动删除 plan/ 下的源目录
+   - 同名冲突处理: 强制覆盖 archive/ 中的旧方案包
+
+3. 更新归档索引: `archive/_index.md`
+
+**警告:** 此操作将导致 plan/ 下的源文件路径失效，请确保步骤10已完成内容读取
+
+### 步骤15: 遗留方案包扫描
+
+```yaml
+执行规则: 按 G6 "遗留方案包扫描" 执行
+
+扫描时机: 方案包迁移完成后
+扫描范围: plan/ 目录，排除本次执行的方案包（CURRENT_PACKAGE）
+显示条件: 检测到≥1个遗留方案包
+显示位置: 底部操作栏（📦 遗留方案包）
+
+详细规则: 参考 references/services/package.md "遗留方案包处理"
+```
+
+---
+
+## 用户选择处理
+
+> 本章节定义开发实施阶段需要用户确认的场景，供 G3 输出格式统一提取。
+
+### 场景: 方案包选择（~exec入口，多个方案包）
+
+```yaml
+内容要素:
+  - 方案包列表: plan/ 目录下的方案包清单（名称、创建时间、类型）
+  - 方案包摘要: 每个方案包的简要描述
+
+选项:
+  选择方案包N: 选择对应序号的方案包执行
+  取消: 按 G6 状态重置协议执行
+```
+
+### 场景: Overview类型方案包处理
+
+按 references/services/package.md "用户选择处理 - Overview类型方案包处理" 执行。
+
+### 场景: 任务执行失败
+
+```yaml
+内容要素:
+  - 失败任务列表: 执行失败的任务清单
+  - 错误信息: 每个失败任务的错误原因
+
+选项:
+  继续: 继续执行后续步骤
+  终止: 输出"已终止执行"，流程终止
+```
+
+### 场景: 阻断性测试失败
+
+```yaml
+内容要素:
+  - 失败测试: 失败的测试名称
+  - 错误信息: 错误信息摘要
+  - 影响范围: 受影响的功能范围
+
+选项:
+  修复: 分析错误原因，修复代码
+  跳过: 跳过该测试，继续执行
+  终止: 终止当前流程
+```
+
+### 场景: 代码质量问题
+
+```yaml
+内容要素:
+  - 优化建议: 代码质量问题列表
+  - 影响范围: 涉及的文件和模块
+
+选项:
+  执行优化: 执行优化、更新文档、重测
+  跳过优化: 跳过优化，继续后续步骤
+```