@huajiwuyan/hello 3.0.0

package/templates/codex/skills/references/functions/debug.md

@@ -0,0 +1,389 @@
+# ~debug 命令 - 系统化调试
+
+本模块定义系统化调试命令的执行规则，通过四阶段流程定位根因并修复问题。
+
+---
+
+## 命令说明
+
+```yaml
+命令: ~debug [<问题描述>]
+类型: 场景确认类（简化入口）
+功能: 系统化调试，四阶段流程定位根因并修复
+触发: 用户输入包含 ~debug
+```
+
+---
+
+## 执行模式适配
+
+> 📌 规则引用: 按 G4 路由架构及 G5 执行模式规则执行
+
+<mode_adaptation>
+~debug 模式适配规则:
+1. 本命令为场景确认类，采用简化入口（无轻量评估确认步骤）
+2. 用户输入 ~debug 后直接进入问题收集和调试流程
+3. 四阶段流程，每阶段完成后需用户确认
+4. 调试完成后输出调试日志并保持待命状态
+</mode_adaptation>
+
+---
+
+## 铁律约束（CRITICAL）
+
+```yaml
+无根因不修复:
+  规则: 未完成阶段1（根因调查），禁止提出修复方案
+  违反后果: 修复无效，问题复发，引入新bug
+
+单一假设:
+  规则: 阶段3每次只测试一个假设
+  违反后果: 无法确定哪个假设有效
+
+3次失败警告:
+  规则: 连续3次修复失败，必须停止并质疑架构
+  违反后果: 陷入无效循环
+```
+
+---
+
+## 执行流程
+
+### 步骤0: 问题收集
+
+```yaml
+执行内容:
+  - 解析用户输入的问题描述
+  - 如未提供描述，询问问题详情
+  - 记录初始症状
+
+输出格式:
+  🔵【HelloAGENTS】- ~debug 问题收集
+
+  **问题描述:** {用户描述}
+  **初始症状:** {错误信息/异常行为}
+
+  🔄 下一步: 开始根因调查
+```
+
+### 阶段1: 根因调查
+
+```yaml
+执行内容:
+  1. 仔细阅读错误信息
+     - 不跳过任何错误或警告
+     - 完整阅读堆栈跟踪
+     - 记录行号、文件路径、错误代码
+
+  2. 稳定复现
+     - 确定触发步骤
+     - 验证是否每次都能复现
+     - 不可复现则收集更多数据
+
+  3. 检查近期变更
+     - git diff、最近提交
+     - 新增依赖、配置变更
+     - 环境差异
+
+  4. 收集证据（多组件系统）
+     - 在每个组件边界添加诊断日志
+     - 记录数据进出
+     - 验证环境/配置传播
+     - 定位失败组件
+
+  5. 追踪数据流
+     - 定位错误值的来源
+     - 反向追踪调用链
+     - 直到找到根源
+
+输出格式:
+  ❓【HelloAGENTS】- ~debug 阶段1完成
+
+  **根因调查发现:**
+  - 错误信息: {关键错误}
+  - 复现步骤: {步骤列表}
+  - 近期变更: {相关变更}
+  - 数据流分析: {数据流向}
+  - 初步定位: {可能的根因位置}
+
+  选项: 继续下一阶段 / 回退重新分析 / 终止调试
+
+  🔄 下一步: 请选择
+```
+
+### 阶段2: 模式分析
+
+```yaml
+执行内容:
+  1. 查找工作示例
+     - 在代码库中定位类似的正常工作代码
+     - 对比工作代码和问题代码
+
+  2. 对比参考实现
+     - 如实现某模式，完整阅读参考实现
+     - 不跳读，逐行理解
+
+  3. 识别差异
+     - 列出工作代码和问题代码的所有差异
+     - 不假设"这个不重要"
+
+  4. 理解依赖
+     - 问题代码依赖哪些组件？
+     - 需要什么配置/环境？
+     - 有什么隐含假设？
+
+输出格式:
+  ❓【HelloAGENTS】- ~debug 阶段2完成
+
+  **模式分析结论:**
+  - 工作示例: {参考代码位置}
+  - 关键差异: {差异列表}
+  - 依赖分析: {依赖组件和配置}
+  - 可能原因: {基于差异的推断}
+
+  选项: 继续下一阶段 / 回退重新分析 / 终止调试
+
+  🔄 下一步: 请选择
+```
+
+### 阶段3: 假设测试
+
+```yaml
+执行内容:
+  1. 形成单一假设
+     - 明确陈述: "我认为 X 是根因，因为 Y"
+     - 记录假设
+
+  2. 最小化测试
+     - 做最小的改动来验证假设
+     - 一次只改一个变量
+
+  3. 验证结果
+     - 有效 → 进入阶段4
+     - 无效 → 形成新假设，返回步骤1
+
+  4. 不确定时
+     - 承认"我不理解 X"
+     - 不假装知道
+     - 请求帮助或进一步研究
+
+输出格式:
+  ❓【HelloAGENTS】- ~debug 阶段3完成
+
+  **假设验证结论:**
+  - 假设: {假设陈述}
+  - 测试方法: {验证步骤}
+  - 测试结果: {通过/失败}
+  - 结论: {确认根因/需要新假设}
+
+  选项: 继续下一阶段 / 形成新假设 / 终止调试
+
+  🔄 下一步: 请选择
+```
+
+### 阶段4: 实现修复
+
+```yaml
+执行内容:
+  1. 创建失败测试用例
+     - 最简单的复现测试
+     - 自动化测试（如有框架）
+     - 一次性脚本（如无框架）
+
+  2. 实施单一修复
+     - 针对已确认的根因
+     - 一次只改一处
+     - 不顺手"改进"其他代码
+
+  3. 验证修复
+     - 测试通过？
+     - 其他测试未破坏？
+     - 问题实际解决？
+
+  4. 修复失败处理
+     - 停止
+     - 计数: 已尝试几次修复？
+     - < 3次: 返回阶段1，用新信息重新分析
+     - ≥ 3次: 触发架构警告
+
+输出格式（成功）:
+  ✅【HelloAGENTS】- ~debug 完成
+
+  **根因:** {根因简述}
+  **修复:** {修复方案简述}
+  **验证:** 测试通过
+
+  📁 文件变更:
+    - helloagents/debug/YYYYMMDD_<issue>.md
+    - {修复涉及的文件列表}
+
+  🔄 下一步: 使用 ~test 验证 或 ~commit 提交
+```
+
+---
+
+## Red Flags 列表（CRITICAL）
+
+检测到以下思维模式时，必须停止并返回阶段1：
+
+```yaml
+危险信号:
+  - "先快速修一下，之后再调查"
+  - "试着改一下 X 看看行不行"
+  - "一次改多个地方，跑测试看看"
+  - "跳过测试，我手动验证"
+  - "大概是 X 的问题，让我修一下"
+  - "我不完全理解，但这样可能有用"
+  - "规范说要这样，但我换个方式"
+  - "问题是这些：[未调查就列出修复方案]"
+  - 未追踪数据流就提出解决方案
+  - "再试一次修复"（已失败 2+ 次时）
+  - 每次修复都在不同位置暴露新问题
+
+检测到时输出:
+  ⚠️【HelloAGENTS】- ~debug 危险信号
+
+  **检测到危险思维模式:**
+  {具体的危险信号}
+
+  **这意味着:** 你正在跳过系统化调试流程，可能导致无效修复。
+
+  🔄 下一步: 返回阶段1重新调查
+```
+
+---
+
+## 3次失败警告
+
+```yaml
+触发条件: 阶段4连续3次修复失败
+
+输出格式:
+  ⚠️【HelloAGENTS】- ~debug 架构警告
+
+  **连续3次修复失败**
+
+  这通常意味着:
+  - 每次修复都在不同位置暴露新问题
+  - 修复需要"大规模重构"才能实现
+  - 每次修复都在其他地方产生新症状
+
+  **问题可能不在代码，而在架构:**
+  - 这个模式从根本上是否合理？
+  - 我们是否在"惯性驱动"下坚持？
+  - 是否应该重构架构而非继续修复症状？
+
+  选项:
+    讨论架构: 暂停调试，分析架构问题
+    继续尝试: 再试一次修复（不推荐）
+    终止: 结束调试会话
+
+  🔄 下一步: 请选择
+```
+
+---
+
+## Supporting Techniques
+
+```yaml
+辅助技术文档（可选加载）:
+  references/functions/debug/root-cause-tracing.md:
+    用途: 从调用栈反向追踪，定位问题原始触发点
+    触发: 错误深埋在调用链中时
+    加载命令: "需要深入追踪根因"
+
+  references/functions/debug/defense-in-depth.md:
+    用途: 根因修复后，在多层添加验证防护
+    触发: 修复完成后的加固阶段
+    加载命令: "添加纵深防御"
+
+  references/functions/debug/condition-based-waiting.md:
+    用途: 用条件轮询替代固定超时
+    触发: 涉及时序/异步问题时
+    加载命令: "处理时序问题"
+```
+
+---
+
+## 调试日志持久化
+
+```yaml
+日志结构:
+  路径: helloagents/debug/YYYYMMDD_<issue>.md
+  目录创建: 首次写入时自动创建
+
+日志内容:
+  ## 问题描述
+  {用户输入 + 初始症状}
+
+  ## 阶段1: 根因调查
+  {调查发现}
+
+  ## 阶段2: 模式分析
+  {分析结论}
+
+  ## 阶段3: 假设测试
+  {假设与验证结果}
+
+  ## 阶段4: 实现修复
+  {修复方案与验证}
+
+  ## 结论
+  - 根因: {根因简述}
+  - 修复: {修复方案}
+  - 经验教训: {本次调试的收获}
+```
+
+---
+
+## CHANGELOG 更新
+
+```yaml
+调试成功完成时:
+  - 记录到 CHANGELOG.md "问题修复" 分类
+  - 格式: "- 修复 <issue>：<根因简述>"
+
+目录创建: 按 G1 "目录/文件自动创建规则" 执行
+```
+
+---
+
+## 用户选择处理
+
+### 场景: 阶段完成确认
+
+```yaml
+内容要素:
+  - 本阶段发现摘要
+  - 下一阶段预告
+
+选项:
+  继续下一阶段: 进入下一阶段
+  回退重新分析: 返回当前阶段重新执行
+  终止调试: 按 G6 状态重置协议执行
+```
+
+### 场景: 修复失败
+
+```yaml
+内容要素:
+  - 失败原因
+  - 已尝试次数
+
+选项:
+  返回阶段1: 用新信息重新调查
+  终止调试: 按 G6 状态重置协议执行
+```
+
+### 场景: 架构警告（3次失败）
+
+```yaml
+内容要素:
+  - 失败历史摘要
+  - 架构问题征兆
+
+选项:
+  讨论架构: 进入架构分析模式
+  继续尝试: 忽略警告继续（不推荐）
+  终止: 按 G6 状态重置协议执行
+```

package/templates/codex/skills/references/functions/exec.md

@@ -0,0 +1,153 @@
+# ~exec 命令 - 执行方案包
+
+本模块定义执行方案包命令的执行规则。
+
+---
+
+## 命令说明
+
+```yaml
+命令: ~exec [<方案包名称>]
+类型: 目标选择类
+功能: 按照执行流程执行 plan/ 目录中的方案包
+模式: STAGE_ENTRY_MODE = DIRECT
+```
+
+---
+
+## 执行模式适配
+
+> 📌 规则引用: 按 G4 路由架构及 G5 执行模式规则执行
+
+<mode_adaptation>
+~exec 模式适配规则:
+1. 本命令使用 DIRECT 入口模式，跳过评估和设计阶段
+2. 评估深度: 轻量评估（无评分追问）
+3. 默认保持 INTERACTIVE 工作流模式
+4. 直接从方案包进入开发实施阶段
+5. Overview 类型方案包需特殊处理（归档而非执行）
+6. develop 阶段自动按需调用子代理（按 G9/G10 规则）
+</mode_adaptation>
+
+---
+
+## 执行流程
+
+### 步骤1: 轻量评估
+
+```yaml
+设置状态变量:
+  - STAGE_ENTRY_MODE = DIRECT
+  - WORKFLOW_MODE = INTERACTIVE（保持默认）
+
+执行规则: 按 G4 "需求评估规则"执行（轻量评估），按G3场景内容规则（需求评估场景）输出
+```
+
+### 步骤2: 扫描方案包
+
+> 脚本路径、存在性检查、错误恢复规则见 references/rules/tools.md
+
+**脚本调用:** `list_packages.py`
+
+```yaml
+扫描范围: helloagents/plan/ 目录
+
+判断处理:
+  0个方案包: 按G3场景内容规则（错误场景）输出，流程终止
+  1个方案包: 自动选择，设置 CURRENT_PACKAGE
+  多个方案包:
+    - 如命令指定了方案包名称: 匹配并选择
+    - 如未指定: 按G3场景内容规则（确认场景）输出，等待用户选择
+
+验证方案包完整性:
+  检查必需文件:
+    - proposal.md（存在且非空）
+    - tasks.md（存在且至少1个任务项）
+  验证失败: 按G3场景内容规则（错误场景）输出，流程终止
+
+检查方案包类型:
+  读取: proposal.md 判断类型
+  implementation 类型: 继续执行开发实施阶段
+  overview 类型: 按 G6 "overview类型处理" 规则执行
+```
+
+> 📌 规则引用: 按 G6 "方案包类型" 规则执行
+
+### 步骤3: 开发实施
+
+```yaml
+执行规则: 读取并执行 references/stages/develop.md
+```
+
+### 步骤4: 后续操作
+
+```yaml
+执行规则: 按 G8 "流程级验收规则" 执行（验收内容详见 G8）
+
+遗留方案包扫描:
+  执行规则: 按 G6 "遗留方案包扫描" 执行
+  扫描时机: 流程即将结束时
+  显示条件: 检测到≥1个遗留方案包
+  详细规则: 参考 references/services/package.md "遗留方案包处理"
+
+完成后: 按G3场景内容规则（完成场景）输出执行命令结果（含验收报告）
+执行: 按 G6 状态重置协议执行
+```
+
+---
+
+## Overview 类型处理
+
+> 📌 规则引用: 按 references/services/package.md "Overview 类型方案包生命周期" 规则执行
+
+```yaml
+检测到 overview 类型方案包时:
+  按G3场景内容规则（确认场景）输出
+
+  内容要素: 方案包类型说明、操作选项（归档/查看/取消）
+
+  用户选择处理:
+    归档: 执行方案包迁移至 archive/
+    查看: 显示 proposal.md 内容，再次询问
+    取消: 按 G6 状态重置协议执行
+```
+
+---
+
+## 不确定性处理
+
+- plan/ 目录不存在 → 按G3场景内容规则（错误场景）输出，提示无方案包
+- 方案包验证失败 → 输出具体缺失项，建议修复或重新规划
+- 方案包类型无法识别 → 默认按 implementation 类型处理
+
+---
+
+## 用户选择处理
+
+### 场景: 方案包选择（多个方案包）
+
+```yaml
+内容要素:
+  - 方案包列表: plan/ 目录下的方案包清单（名称、创建时间、类型）
+  - 方案包摘要: 每个方案包的简要描述
+
+选项:
+  选择方案包N: 选择对应序号的方案包执行
+  取消: 按 G6 状态重置协议执行
+```
+
+### 场景: Overview类型方案包处理
+
+> 📌 规则引用: 按 references/services/package.md "用户选择处理 - Overview类型方案包处理" 执行
+
+### 场景: 流程级验收完成
+
+```yaml
+内容要素:
+  - 验收状态: 通过/部分通过/失败
+  - 交付物摘要: 方案包、代码变更、知识库状态
+  - 需求符合性: 已完成任务/未完成任务
+  - 问题汇总: 警告和信息性记录（如有）
+
+输出格式: 按G3场景内容规则（完成场景）输出
+```

package/templates/codex/skills/references/functions/help.md

@@ -0,0 +1,101 @@
+# ~help 命令 - 显示帮助
+
+本模块定义帮助命令的输出内容。
+
+---
+
+## 命令说明
+
+```yaml
+命令: ~help
+类型: 直接执行类
+功能: 显示帮助信息，无需确认或评估，直接输出帮助内容
+触发: 用户输入包含 ~help 或 ~?
+```
+
+---
+
+## 执行模式适配
+
+> 📌 规则引用: 按 G4 路由架构及 G5 执行模式规则执行
+
+<mode_adaptation>
+~help 模式适配规则:
+1. 本命令为直接执行类，无需用户确认
+2. 不受任何工作流模式影响
+3. 检测上下文后直接输出帮助内容
+4. 输出后保持待命状态，无状态变量设置
+</mode_adaptation>
+
+---
+
+## 执行流程
+
+### 步骤1: 上下文检测
+
+```yaml
+执行内容:
+  - 检测用户输入是否携带上下文（疑问、困惑、请求等）
+  - 如有上下文，准备简短回应用户的问题或情绪
+  - 根据上下文调整下一步建议的针对性
+
+目标: 友好引导，帮助用户快速上手
+```
+
+### 步骤2: 输出帮助信息
+
+```yaml
+执行内容:
+  - 如步骤1检测到上下文，先简短回应
+  - 按下方"输出模板"输出帮助内容
+  - 按G3场景内容规则（直接回答场景）格式化输出
+
+说明: 此命令为原子操作，无状态变量设置，输出后保持待命状态
+```
+
+---
+
+## 输出模板
+
+```
+💡【HelloAGENTS】- 使用帮助
+
+{如用户输入携带上下文，先简短回应}
+
+智能工作流系统，提供结构化任务流程。
+
+### 可用命令
+
+| 命令 | 功能 | 说明 |
+|------|------|------|
+| `~auto` | 全授权命令 | 根据复杂度自动选择模式执行 |
+| `~plan` | 执行到方案设计 | 仅轻量迭代/标准开发模式 |
+| `~exec` | 执行方案包 | 执行已有的方案包 |
+| `~init` | 初始化知识库 | 扫描代码库创建知识库 |
+| `~upgrade` | 升级知识库 | 升级知识库结构 |
+| `~clean` | 清理遗留方案包 | 清理未执行的方案包 |
+| `~commit` | Git 提交 | 智能生成提交信息并执行提交 |
+| `~test` | 运行测试 | 运行测试并分析结果 |
+| `~review` | 代码审查 | AI辅助代码审查 |
+| `~validate` | 验证知识库 | 验证知识库和方案包 |
+| `~rollback` | 智能回滚 | 回滚最近的变更 |
+| `~brain` | 头脑风暴 | 协作式设计，生成方案包 |
+| `~debug` | 系统化调试 | 四阶段根因定位与修复 |
+| `~help` | 显示帮助 | 显示此帮助信息 |
+
+### 工作流程
+
+需求评估 → 复杂度判定 → 对应模式执行
+- 微调模式: 直接执行 → 知识库(KB)同步
+- 轻量迭代: 项目分析 → 方案设计 → 开发实施 → 方案包归档
+- 标准开发: 项目分析 → 方案设计（含多方案对比）→ 开发实施 → 方案包归档
+- 头脑风暴: 协作探索 → 方案设计 → 方案包归档（可选执行）
+
+### 使用方式
+
+- 输入 `~命令` 执行特定功能
+- 直接描述需求，系统自动路由到合适的流程
+
+────
+🔄 下一步: {根据上下文提供针对性建议，无上下文时使用通用建议}
+```