helloagents 1.0.0

package/Claude/Skills/CN/skills/helloagents/develop/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: develop
+description: 开发实施阶段详细规则；进入开发实施时读取；包含执行流程、代码规范、一致性审计、方案包迁移
+---
+
+# 开发实施 - 详细规则
+
+**目标:** 按方案包中任务清单执行代码改动，同步更新知识库，迁移到 history/
+
+**前提:** `plan/` 目录中存在待执行的方案包
+
+**备份保护:** 执行前建议创建 Git 备份分支或手动备份代码目录
+
+---
+
+## 强制前置检查
+
+<p3_entry_gate>
+**说明：** 即使路由判定进入开发实施，此检查仍会验证合法性（双重保险）
+
+**开发实施的唯一合法条件（满足任一即可）：**
+
+```yaml
+条件A - 方案设计完成后确认:
+  验证方法: 会话历史中上一条AI输出为方案设计完成 且 当前用户输入为明确确认
+
+条件B - 全授权命令:
+  验证方法: MODE_FULL_AUTH状态=true
+
+条件C - 执行命令:
+  验证方法: MODE_EXECUTION状态=true
+```
+
+**验证失败处理：**
+```
+IF 不满足任何条件:
+  输出: "❌ 路由错误: 进入开发实施需满足前置条件。当前条件不满足，已重新路由。"
+  执行: 将当前用户消息按路由优先级重新判定
+  终止: 开发实施流程
+```
+</p3_entry_gate>
+
+---
+
+## 执行步骤
+
+**重要:** 所有文件操作遵循G5静默执行规范
+
+### 步骤1: 确定待执行方案包
+
+```yaml
+全授权命令(MODE_FULL_AUTH=true):
+  - 读取CREATED_PACKAGE变量（方案设计阶段设置的方案包路径）
+  - 检查该方案包是否存在且完整
+    - 存在且完整 → 使用该方案包，设置CURRENT_PACKAGE = CREATED_PACKAGE
+    - 不存在或不完整 → 按G6.2输出错误格式并停止
+  - 忽略plan/中的其他遗留方案包
+
+交互确认模式/执行命令(MODE_EXECUTION=true):
+  - 扫描plan/目录下所有方案包
+  - 不存在方案包 → 按G6.2输出错误格式并停止
+  - 方案包不完整 → 按G6.2输出错误格式并停止
+  - 单个完整方案包 → 设置CURRENT_PACKAGE，继续执行
+  - 多个方案包 → 列出清单，等待用户选择
+    - 用户输入有效序号(1-N) → 设置CURRENT_PACKAGE，继续执行
+    - 用户输入取消/拒绝 → 按G6.2输出取消格式，流程终止
+    - 无效输入 → 再次询问
+
+异常输出示例:
+  方案包不存在:
+    ```
+    ❌【HelloAGENTS】- 执行错误
+
+    错误: 未找到可执行的方案包
+    - 原因: plan/目录为空或不存在
+
+    ────
+    🔄 下一步: 请先使用 ~plan 命令创建方案，或进入方案设计阶段
+    ```
+
+  方案包不完整:
+    ```
+    ❌【HelloAGENTS】- 执行错误
+
+    错误: 方案包不完整
+    - 方案包: [方案包名称]
+    - 缺失文件: [why.md/how.md/task.md]
+
+    ────
+    🔄 下一步: 请补充缺失文件或重新创建方案包
+    ```
+```
+
+### 步骤2: 检查知识库状态并处理
+
+执行方式:
+- 按 G10 快速决策树判定
+- 如需创建/重建知识库 → 读取 `kb` Skill执行完整流程
+
+### 步骤3: 读取知识库并获取项目上下文
+
+执行方式:
+- 按 G10 快速流程执行（先检查知识库 → 不足则扫描代码库）
+- 如需详细规则 → 读取 `kb` Skill
+
+### 步骤4: 读取当前方案包
+
+读取 `plan/YYYYMMDDHHMM_<feature>/task.md` 和 `why.md`
+
+### 步骤5: 按任务清单执行代码改动
+
+```yaml
+执行规则:
+  - 严格按 task.md 逐项执行
+
+任务成功处理:
+  - 每个任务执行成功后，立即将状态从 [ ] 更新为 [√]
+
+任务跳过处理(状态更新为 [-]):
+  - 任务依赖的前置任务失败
+  - 任务条件不满足
+  - 任务已被其他任务的实现覆盖
+
+任务失败处理(状态更新为 [X]):
+  - 记录错误信息（用于迁移前添加备注）
+  - 继续执行后续任务
+  - 所有任务完成后，如存在失败:
+    - 交互确认模式/执行命令: 列出失败清单，询问用户决定
+      - 用户选择继续 → 继续后续步骤
+      - 用户选择终止 → 输出"已终止开发实施"，流程终止
+    - 全授权命令: 在总结中列出失败任务，清除MODE_FULL_AUTH状态
+
+代码编辑技巧:
+  - 大文件处理(≥2000行): Grep定位 → Read(offset,limit) → Edit精确修改
+  - 每次Edit只修改单个函数/类
+```
+
+### 步骤6: 代码安全检查
+
+检查内容:
+- 不安全模式（eval、exec、SQL拼接等）
+- 敏感信息硬编码
+- EHRB风险规避
+
+### 步骤7: 质量检查与测试
+
+```yaml
+测试执行: 运行task.md中定义的测试任务，或项目已有测试套件
+
+测试失败处理规则（严格执行）:
+  ⛔ 阻断性测试（核心功能）:
+    - 失败必须立即停止执行
+    - 输出关键错误格式
+    - 等待用户明确决策（修复/跳过/终止）
+    - 禁止自动跳过
+
+  ⚠️ 警告性测试（重要功能）:
+    - 失败时在总结中标注
+    - 继续执行后续步骤
+
+  ℹ️ 信息性测试（次要功能）:
+    - 失败时在总结中记录
+    - 继续执行后续步骤
+```
+
+**⛔阻断性测试失败输出格式:**
+```
+❌【HelloAGENTS】- 阻断性测试失败
+
+⛔ 核心功能测试失败，必须处理后才能继续:
+- 失败测试: [测试名称]
+- 错误信息: [错误摘要]
+
+[1] 修复后重试 - 尝试修复问题后重新测试
+[2] 跳过继续 - 风险自负，忽略此错误继续执行
+[3] 终止执行 - 停止开发实施
+
+────
+🔄 下一步: 请输入序号选择
+```
+
+### 步骤8: 同步更新知识库
+
+**重要:** 必须在步骤12迁移方案包前完成方案包内容读取
+
+执行方式: 读取 `kb` Skill执行完整知识库同步规则
+
+### 步骤9: 更新 CHANGELOG.md
+
+按G7版本管理规则确定版本号
+
+### 步骤10: 一致性审计
+
+<consistency_audit>
+**审计时机:** P3阶段完成知识库操作后立即执行
+
+**审计内容:**
+1. **完整性**: 文档涵盖所有模块，必备文件和图表齐全
+2. **一致性**: API/数据模型与代码一致，无遗漏、重复、死链
+
+**真实性优先级（冲突解决机制）:**
+```
+1. 代码是执行真实性的唯一来源 (Ground Truth)
+   → 运行时行为、API签名、数据结构以代码为准
+
+2. 默认修正方向: 修正知识库以符合代码
+   → 发现不一致时，必须更新文档以反映代码的客观事实
+
+3. 例外（修正代码）:
+   - 知识库是最近P2/P3方案包（刚设计好的方案）
+   - 代码有明显错误（Bug）
+   - 错误信息指向代码问题
+
+4. 存疑时: 双向验证，优先信任最近的代码变更
+```
+</consistency_audit>
+
+### 步骤11: 代码质量检查（可选）
+
+```yaml
+执行内容: 分析代码文件，识别质量问题
+
+如发现问题:
+  交互确认模式:
+    - 输出优化建议询问格式
+    - 用户确认 → 执行优化、更新文档、重测
+    - 用户拒绝 → 跳过优化，继续后续步骤
+  全授权命令/执行命令:
+    - 在总结中列出建议（不执行）
+
+提交关联: 如需提交，按项目规范执行
+```
+
+**代码质量优化建议询问格式:**
+```
+❓【HelloAGENTS】- 代码质量
+
+发现以下可优化项:
+1. [优化建议1] - [影响范围/文件]
+2. [优化建议2] - [影响范围/文件]
+
+[1] 执行优化 - 应用上述优化建议
+[2] 跳过 - 保持现状，继续后续步骤
+
+────
+🔄 下一步: 请输入序号选择
+```
+
+### 步骤12: 迁移已执行方案包至history/
+
+<plan_migration>
+
+⚠️ **CRITICAL - 强制执行规则:**
+
+**不可跳过:** 此步骤为本阶段结束的原子性操作
+
+**执行规则:**
+
+1. 更新task.md任务状态和备注:
+   - 所有任务更新为实际执行结果（[√]/[X]/[-]/[?]）
+   - 非[√]状态任务下方添加备注（格式: `> 备注: [原因]`）
+   - 如有多个失败/跳过任务，可在末尾添加执行总结章节
+
+2. 迁移至历史记录目录:
+   - 将方案包目录从 plan/ 移动到 history/YYYY-MM/ 下
+   - YYYY-MM 从方案包目录名提取（如 202511201200_xxx → 2025-11）
+   - 迁移后完整路径: history/YYYY-MM/YYYYMMDDHHMM_<feature>/
+   - 迁移操作会自动删除 plan/ 下的源目录
+   - 同名冲突处理: 强制覆盖 history/ 中的旧方案包
+
+3. 更新历史记录索引: `history/index.md`
+
+**警告:** 此操作将导致 plan/ 下的源文件路径失效，请确保步骤8已完成内容读取
+**不可跳过:** 此步骤为本阶段结束的原子性操作
+</plan_migration>
+
+---
+
+## 代码规范要求
+
+<code_standards>
+**适用范围:** P3阶段的所有代码改动
+
+**规范要求:**
+- **文件顶部注释:** 导入语句前，项目现有注释风格，1-3句话说明模块用途
+- **所有代码注释:** 必须用{OUTPUT_LANGUAGE}生成
+- **代码风格:** 遵循项目现有命名约定和格式规范
+</code_standards>
+
+---
+
+## 开发实施 输出格式
+
+⚠️ **CRITICAL - 强制要求:**
+- ALWAYS使用G6.1统一输出格式
+- NEVER使用自由文本替代规范格式
+- 输出前MUST验证格式完整性
+
+### 等待用户选择方案包时（步骤1多方案包）
+
+```
+❓【HelloAGENTS】- 开发实施
+
+检测到多个方案包，请选择执行目标:
+
+[1] YYYYMMDDHHMM_<feature1> - [概要描述]
+[2] YYYYMMDDHHMM_<feature2> - [概要描述]
+[3] YYYYMMDDHHMM_<feature3> - [概要描述]
+
+────
+🔄 下一步: 请输入方案包序号(1/2/3)
+```
+
+### 阶段完成时
+
+严格调用 G6.1 统一输出格式，填充以下数据：
+
+1. **阶段名称:** `开发实施`
+2. **阶段具体内容(≤5条要点):**
+   - 📚 知识库状态
+   - ✅ 执行结果: 任务数量和状态统计
+   - 🔍 质量验证: 一致性审计、测试结果
+   - 💡 代码质量优化建议（如有）
+   - 📦 迁移信息: 已迁移至 `history/YYYY-MM/YYYYMMDDHHMM_<feature>/`
+3. **文件变更清单:**
+   ```
+   📁 变更:
+     - {代码文件}
+     - {知识库文件}
+     - helloagents/CHANGELOG.md
+     - helloagents/history/index.md
+     ...
+   ```
+4. **下一步建议:** "请确认实施结果是否符合预期?"
+5. **遗留方案提醒:** 按G11扫描 plan/ 目录，如有遗留方案包则显示
+
+---
+
+## 阶段转换规则
+
+```yaml
+完成所有动作后:
+  交互确认模式: 输出总结 → 开发实施结束
+  全授权命令: 输出整体总结 → 流程结束
+  执行命令: 输出整体总结 → 流程结束
+  变量清理: CURRENT_PACKAGE将在遗留方案扫描时自动清理(按G11规则)
+
+异常情况（测试失败/用户提出问题）:
+  交互确认模式: 在输出中标注，等待用户决定
+  全授权命令/执行命令: 在总结中标注测试失败，流程正常结束
+  后续用户消息按路由优先级处理
+```

package/Claude/Skills/CN/skills/helloagents/kb/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: kb
+description: 知识库管理完整规则；~init命令或知识库缺失时读取；包含创建、同步、审计、上下文获取规则
+---
+
+# 知识库管理 - 完整规则
+
+## 知识库架构
+
+**文件结构:**
+```plaintext
+helloagents/              # HelloAGENTS 工作空间（SSOT）
+├── CHANGELOG.md          # 版本历史（Keep a Changelog）
+├── project.md            # 技术约定
+├── wiki/                 # 核心文档
+│   ├── overview.md       # 项目概述
+│   ├── arch.md           # 架构设计
+│   ├── api.md            # API 手册
+│   ├── data.md           # 数据模型
+│   └── modules/<module>.md
+├── plan/                 # 变更工作区
+│   └── YYYYMMDDHHMM_<feature>/
+│       ├── why.md        # 变更提案
+│       ├── how.md        # 技术设计
+│       └── task.md       # 任务清单
+└── history/              # 已完成变更归档
+    ├── index.md
+    └── YYYY-MM/YYYYMMDDHHMM_<feature>/
+```
+
+**路径约定:**
+- 本规则集中 `plan/`、`wiki/`、`history/` 均指 `helloagents/` 下的完整路径
+- 所有知识库文件必须在 `helloagents/` 目录下创建
+
+---
+
+## 核心术语详解
+
+- **SSOT** (Single Source of Truth): 唯一真实来源（知识层面），指知识库
+  - *注意:* 当SSOT与代码冲突时，SSOT视为"过时"，需依据代码（执行事实）进行更新
+- **知识库**: 项目文档完整集合 (`CHANGELOG.md`, `project.md`, `wiki/*`)
+- **EHRB** (Extreme High-Risk Behavior): 极度高风险行为
+- **ADR** (Architecture Decision Record): 架构决策记录
+- **MRE** (Minimal Reproducible Example): 最小可复现示例
+- **方案包**: 完整方案单元
+  - **目录结构**: `YYYYMMDDHHMM_<feature>/`
+  - **必需文件**: `why.md` + `how.md` + `task.md`
+  - **完整性检查**: 必需文件存在、非空、task.md至少1个任务项
+
+---
+
+## 质量检查维度
+
+1. **完整性**: 必需文件和章节是否存在
+2. **格式**: Mermaid图表/Markdown格式是否正确
+3. **一致性**: API签名/数据模型与代码是否一致
+4. **安全**: 是否包含敏感信息（密钥/PII）
+
+**问题分级:**
+- **轻度**（可继续）: 缺失非关键文件、格式不规范、描述过时
+- **重度**（需处理）: 核心文件缺失、内容严重脱节(>30%)、存在敏感信息
+
+---
+
+## 项目上下文获取策略
+
+<context_acquisition_rules>
+**步骤1: 先检查知识库（如存在）**
+- 核心文件: `project.md`, `wiki/overview.md`, `wiki/arch.md`
+- 按需选择: `wiki/modules/<module>.md`, `wiki/api.md`, `wiki/data.md`
+
+**步骤2: 知识库不存在/信息不足 → 全面扫描代码库**
+- 使用 Glob 获取文件结构
+- 使用 Grep 搜索关键信息
+- 获取: 架构、技术栈、模块结构、技术约束
+</context_acquisition_rules>
+
+---
+
+## 知识库同步规则
+
+<kb_sync_rules>
+**触发时机:** 代码变更后，必须立即同步更新知识库
+
+**步骤1 - 模块规范更新:**
+- 读取当前方案包 `plan/YYYYMMDDHHMM_<feature>/why.md` 的 **核心场景** 章节（在迁移前读取）
+- 提取需求和场景（需求需标注所属模块）
+- 更新 `wiki/modules/<module>.md` 的 **规范** 章节
+  - 不存在 → 追加
+  - 已存在 → 更新
+
+**步骤2 - 按变更类型更新:**
+- API变更 → 更新 `wiki/api.md`
+- 数据模型变更 → 更新 `wiki/data.md`
+- 架构变更/新增模块 → 更新 `wiki/arch.md`
+- 模块索引变更 → 更新 `wiki/overview.md`
+- 技术约定变更 → 更新 `project.md`
+
+**步骤3 - ADR维护（如包含架构决策）:**
+- 提取 ADR 信息（在迁移前从 `plan/YYYYMMDDHHMM_<feature>/how.md` 的 **架构决策 ADR** 章节读取）
+- 在 `wiki/arch.md` 的 **重大架构决策** 表格中追加
+- 链接到 `history/YYYY-MM/YYYYMMDDHHMM_<feature>/how.md#adr-xxx`
+- **注意:** 此时写入的 history/ 链接为预计算路径
+
+**步骤4 - 清理:**
+- 删除过时信息、废弃API、已删除模块
+
+**步骤5 - 缺陷复盘（修复场景专属）:**
+- 在模块文档中添加"已知问题"或"注意事项"
+- 记录根因、修复方案、预防措施
+</kb_sync_rules>
+
+---
+
+## 知识库缺失处理
+
+<kb_missing_handler>
+**STEP 1: 检查核心文件是否存在**
+- `CHANGELOG.md`, `project.md`, `wiki/*.md`
+
+**STEP 2: 知识库不存在**
+按阶段处理:
+```yaml
+需求分析阶段:
+  - 只标记问题，不创建知识库
+  - 在总结中提示"知识库缺失，建议先执行 ~init 命令"
+
+方案设计/开发实施阶段:
+  - 全面扫描代码库并创建完整知识库:
+    - 根目录: CHANGELOG.md, project.md
+    - wiki/: overview.md, arch.md, api.md, data.md
+    - wiki/modules/: <module>.md（每个模块）
+    - 大型项目（按G4判定）分批处理（每批≤20个模块）
+```
+
+**STEP 3: 知识库存在**
+```yaml
+执行质量前置检查:
+  重度问题 → 全面扫描并重建（方案设计/开发实施阶段）
+  轻度问题 → 继续流程
+```
+</kb_missing_handler>
+
+---
+
+## 遗留方案处理
+
+### 用户选择迁移流程
+
+<legacy_plan_migration>
+**适用场景:** 用户响应"确认迁移"后的批量处理流程
+
+**步骤1 - 用户选择迁移范围:**
+
+列出所有遗留方案包，询问用户选择:
+```
+检测到 X 个遗留方案包，请选择迁移方式:
+- 输入"全部" → 迁移所有遗留方案包
+- 输入方案包序号（如 1, 1,3, 1-3）→ 迁移指定方案包
+- 输入"取消" → 保留所有遗留方案包
+
+方案包清单:
+[1] 202511201300_logout
+[2] 202511201400_profile
+[3] 202511201500_settings
+```
+
+**用户响应处理:**
+- "全部" → 迁移所有
+- 单个序号（如 1）→ 迁移第1个
+- 多个序号（如 1,3）→ 迁移指定的
+- 序号范围（如 1-3）→ 迁移第1到第3个
+- "取消" → 保留所有
+- 其他输入 → 再次询问
+
+**步骤2 - 逐个迁移选定的方案包:**
+
+```yaml
+for each 选定的方案包:
+  1. 更新任务状态: 所有任务状态更新为 [-]
+     顶部添加: > **状态:** 未执行（用户清理）
+
+  2. 迁移至历史记录目录:
+     - 从 plan/ 移动到 history/YYYY-MM/
+     - YYYY-MM 从方案包目录名提取
+     - 同名冲突: 强制覆盖
+
+  3. 更新历史记录索引: history/index.md（标注"未执行"）
+```
+
+**步骤3 - 输出迁移摘要:**
+```
+✅ 已迁移 X 个方案包至 history/:
+  - 202511201300_logout → history/2025-11/202511201300_logout/
+  - 202511201500_settings → history/2025-11/202511201500_settings/
+📦 剩余 Y 个方案包保留在 plan/:
+  - 202511201400_profile
+```
+</legacy_plan_migration>
+
+### 遗留方案扫描与提醒机制
+
+<legacy_plan_scan>
+**触发时机:**
+- 方案包创建后: 方案设计完成、规划命令完成、轻量迭代完成
+- 方案包迁移后: 开发实施完成、执行命令完成、全授权命令完成
+
+**扫描逻辑:**
+1. 扫描 plan/ 目录下所有方案包目录
+2. 排除本次已执行的方案包（读取CURRENT_PACKAGE变量）
+3. 清除CURRENT_PACKAGE变量
+4. 剩余方案包即为遗留方案
+
+**输出位置:** 自动注入到 G6.1 输出格式的末尾插槽中
+
+**输出格式:**
+```
+📦 plan/遗留方案: 检测到 X 个遗留方案包([列表])，是否需要迁移至历史记录?
+```
+
+列表格式: YYYYMMDDHHMM_<feature>（每个一行，最多5个，超过显示"...等X个"）
+
+**用户响应:**
+- 确认迁移 → 执行批量迁移流程
+- 拒绝/忽略 → 保留在 plan/ 目录
+</legacy_plan_scan>
+
+---
+
+## ~init / ~wiki 命令完成总结格式
+
+严格遵循G6.1统一输出格式:
+
+```
+✅【HelloAGENTS】- 知识库命令完成
+
+- 📚 知识库状态: [已创建/已更新/已重建]
+- 📊 操作摘要: 扫描X模块, 创建/更新Y文档
+- 🔍 质量检查: [检查结果，如有问题]
+
+────
+📁 变更:
+  - {知识库文件}
+  - helloagents/CHANGELOG.md
+  - helloagents/project.md
+  ...
+
+🔄 下一步: 知识库操作已完成，可进行其他任务
+```