@huajiwuyan/hello 3.0.0

package/templates/claude/skills/references/functions/upgrade.md

@@ -0,0 +1,371 @@
+# ~upgrade 命令 - 升级知识库
+
+本模块定义 AI 驱动的知识库升级流程。
+
+---
+
+## 命令说明
+
+```yaml
+命令: ~upgrade
+类型: 场景确认类
+功能: 智能升级知识库结构至最新框架标准
+特点: AI 分析内容语义，动态匹配模板，支持任意源格式
+```
+
+---
+
+## 执行模式适配
+
+> 📌 规则引用: 按 G4 路由架构及 G5 执行模式规则执行
+
+<mode_adaptation>
+~upgrade 模式适配规则:
+1. 本命令为独立工具命令，不受 WORKFLOW_MODE 影响
+2. KB_CREATE_MODE=0 时需用户确认后执行
+3. 升级前强制备份，确保可恢复
+4. AI 负责内容分析，脚本负责文件操作
+</mode_adaptation>
+
+---
+
+## 设计原则
+
+```yaml
+职责分离:
+  AI 负责:
+    - 读取模板理解目标结构
+    - 分析源文件内容语义
+    - 识别内容类型（项目概述、需求、方案、技术设计等）
+    - 决定源内容到模板章节的映射关系
+    - 按模板格式生成目标内容
+
+  脚本负责:
+    - 扫描目录列出文件（--scan）
+    - 创建标准目录结构（--init）
+    - 备份现有知识库（--backup）
+    - 按 AI 生成的计划写入文件（--write）
+
+关键约束:
+  - 脚本不做任何内容分析和格式转换
+  - 模板文件是唯一权威来源（SSOT）
+  - AI 通过读取模板动态理解目标格式
+```
+
+---
+
+## 执行流程
+
+### 步骤1: 知识库开关检查
+
+<kb_switch_analysis>
+知识库开关检查推理过程:
+1. 读取 KB_CREATE_MODE 当前值
+2. 若为 0 (OFF)，提示用户确认是否继续
+3. 若为 1/2/3，直接继续执行
+</kb_switch_analysis>
+
+```yaml
+IF KB_CREATE_MODE = 0 (OFF):
+  按 G3 场景内容规则（确认）输出
+
+  用户选择处理:
+    继续执行: 继续执行下方流程
+    取消: 按 G7 状态重置协议执行，流程终止
+
+ELSE (开关=1/2/3):
+  直接继续执行下方流程（无需额外确认）
+```
+
+### 步骤2: 准备
+
+```yaml
+步骤2.1 - 读取模板文件:
+  读取以下模板文件，理解目标结构和格式:
+    - assets/templates/INDEX.md
+    - assets/templates/context.md
+    - assets/templates/CHANGELOG.md
+    - assets/templates/modules/_index.md
+    - assets/templates/archive/_index.md
+    - assets/templates/plan/proposal.md
+    - assets/templates/plan/tasks.md
+
+步骤2.2 - 扫描知识库:
+  脚本调用: upgradewiki.py --scan
+  获取: 知识库目录结构和文件列表（JSON格式）
+```
+
+### 步骤3: AI 内容分析
+
+<upgrade_content_analysis>
+AI 内容分析推理过程:
+
+1. 读取源文件内容
+   - 对扫描结果中的每个 Markdown 文件，读取其内容
+   - 跳过明显的非知识库文件（如 .gitignore、node_modules 等）
+
+2. 识别内容类型
+   - 项目概述类：项目介绍、背景、目标、技术栈
+   - 需求类：功能需求、业务需求、用户故事
+   - 方案类：设计方案、架构方案、技术方案
+   - 技术设计类：详细设计、接口设计、数据模型
+   - 变更记录类：更新日志、版本记录
+   - 模块文档类：功能模块说明、API文档
+   - 方案包类：符合 YYYYMMDDHHMM_feature 命名的目录
+
+3. 分析映射关系
+   - 将识别的内容类型映射到目标模板的对应章节
+   - 处理内容合并（多个源文件 → 一个目标文件）
+   - 处理内容拆分（一个源文件 → 多个目标文件）
+
+4. 生成升级计划
+   - 列出所有需要的操作（创建、合并、重命名、删除）
+   - 标注每个操作的源内容和目标位置
+   - 评估风险和注意事项
+</upgrade_content_analysis>
+
+### 步骤4: 用户确认
+
+```yaml
+展示升级计划:
+  按 G3 场景内容规则（确认）输出
+
+  内容要素:
+    - 源文件分析结果（识别到的内容类型）
+    - 升级计划（操作列表）
+    - 注意事项（需要人工确认的内容）
+
+  选项:
+    执行升级: 继续执行步骤5
+    查看详情: 展示更多细节后再确认
+    取消: 按 G7 状态重置协议执行
+```
+
+### 步骤5: 执行升级
+
+```yaml
+步骤5.1 - 备份:
+  脚本调用: upgradewiki.py --backup
+  确保: 备份成功后再继续
+
+步骤5.2 - 创建目录结构:
+  脚本调用: upgradewiki.py --init
+  创建: modules/, archive/, plan/ 目录
+
+步骤5.3 - AI 生成目标内容:
+  根据升级计划，AI 执行以下操作:
+    - 读取源文件内容
+    - 按模板格式重新组织内容
+    - 填充模板占位符
+    - 生成目标文件内容
+
+步骤5.4 - 写入文件:
+  方式A - 直接使用 Write 工具:
+    AI 使用 Write 工具直接写入每个目标文件
+
+  方式B - 批量写入（大量文件时）:
+    1. AI 生成操作计划 JSON 文件
+    2. 脚本调用: upgradewiki.py --write plan.json
+    3. 检查执行结果
+
+步骤5.5 - 清理（可选）:
+  用户确认后，删除已迁移的源文件
+
+步骤5.6 - 升级后验收:
+  按 G9 命令级验收标准（~upgrade）执行
+
+  验收项:
+    - 知识库结构符合目标版本 (阻断性)
+    - 核心文件完整 (阻断性): INDEX.md, context.md 存在且非空
+    - 内容无丢失 (警告性): 对比源文件和目标文件内容
+
+  验收方式:
+    调用 ~validate 仅知识库模式，检查验收结果
+
+  验收失败处理:
+    阻断性失败:
+      - 按 G3 场景内容规则（警告）输出
+      - 建议用户从备份恢复
+    警告性失败:
+      - 记录到升级报告
+      - 提示用户检查相关内容
+
+  完成后: 按 G3 场景内容规则（完成）输出升级结果（含验收报告）
+  执行: 按 G7 状态重置协议执行
+```
+
+---
+
+## 安全约束
+
+> 📌 规则引用: 按 G2 EHRB 检测规则执行
+
+```yaml
+强制约束:
+  - 仅操作 helloagents/ 目录
+  - 执行前必须备份
+  - 冲突时不覆盖（报错并请求用户决策）
+  - 不删除未识别的文件（保留原位置）
+
+备份机制:
+  位置: 项目根目录/helloagents_backup_{YYYYMMDDHHMMSS}/
+  内容: 完整的 helloagents/ 目录副本
+  用途: 升级失败时可手动恢复
+```
+
+---
+
+## 内容映射规则
+
+> AI 应根据以下指导原则进行内容映射，而非硬编码规则。
+
+### 映射指导
+
+```yaml
+项目信息 → context.md:
+  识别特征: 项目名称、项目介绍、技术栈、团队信息、开发规范
+  模板位置: 对应 context.md 模板的各章节
+
+变更记录 → CHANGELOG.md:
+  识别特征: 版本号、日期、变更内容、更新日志
+  模板位置: 对应 CHANGELOG.md 模板格式
+
+模块文档 → modules/:
+  识别特征: 功能模块说明、API文档、组件文档
+  模板位置: 按模块创建独立文件
+
+方案包 → plan/ 或 archive/:
+  识别特征: YYYYMMDDHHMM_feature 命名格式
+  文件映射:
+    - why.md + how.md → proposal.md
+    - task.md → tasks.md
+  位置判断:
+    - 未完成的方案包 → plan/
+    - 已完成的方案包 → archive/YYYY-MM/
+```
+
+### 目录结构映射
+
+```yaml
+常见旧结构:
+  wiki/ → modules/
+  history/ → archive/
+  project.md → context.md
+
+判断依据:
+  - 目录内容类型（文档类 vs 归档类）
+  - 文件命名模式
+  - 内容语义分析
+```
+
+---
+
+## 不确定性处理
+
+- 源文件格式无法识别 → 保留原位置，标注"需人工处理"
+- 内容映射冲突 → 请求用户决策
+- 备份失败 → 中止升级，提示用户检查磁盘空间
+
+---
+
+## 脚本参考
+
+> 📌 规则引用: 脚本路径、存在性检查、错误恢复规则见 references/rules/tools.md
+
+### 脚本命令
+
+```yaml
+扫描目录:
+  命令: upgradewiki.py --scan
+  输出: JSON 格式的文件列表和目录结构
+  用途: 获取知识库当前状态
+
+创建目录:
+  命令: upgradewiki.py --init
+  输出: 创建结果（created/existed 列表）
+  用途: 初始化标准目录结构
+
+备份知识库:
+  命令: upgradewiki.py --backup
+  输出: 备份结果（成功/失败，备份路径）
+  用途: 升级前备份
+
+批量写入:
+  命令: upgradewiki.py --write <plan.json>
+  输入: JSON 格式的操作计划
+  输出: 执行结果（成功的操作/错误列表）
+  用途: 批量执行文件操作
+```
+
+### 写入计划格式
+
+```json
+{
+  "operations": [
+    {"action": "write", "path": "context.md", "content": "..."},
+    {"action": "rename", "from": "old.md", "to": "new.md"},
+    {"action": "delete", "path": "obsolete.md"},
+    {"action": "mkdir", "path": "subdir"}
+  ]
+}
+```
+
+---
+
+## 用户选择处理
+
+> 本章节定义 ~upgrade 命令需要用户确认的场景，供 G3 输出格式统一提取。
+
+### 场景: 知识库开关确认（KB_CREATE_MODE=0）
+
+```yaml
+内容要素:
+  - 当前开关状态: KB_CREATE_MODE = 0 (OFF)
+  - 行为说明: 知识库操作已关闭，~upgrade 将忽略开关强制执行
+
+选项:
+  继续执行: 忽略开关，继续升级知识库
+  取消: 按 G7 状态重置协议执行
+```
+
+### 场景: 升级计划确认
+
+```yaml
+内容要素:
+  - 源文件分析: 识别到的文件及其内容类型
+  - 升级计划: 需要执行的操作列表
+  - 注意事项: AI 无法自动处理的内容（需人工确认）
+
+选项:
+  执行升级: 备份后执行升级
+  查看详情: 展示具体的内容映射关系
+  取消: 按 G7 状态重置协议执行
+```
+
+### 场景: 升级后验收完成
+
+```yaml
+内容要素:
+  - 验收状态: 通过/部分通过/失败
+  - 结构验收: 目录结构和核心文件状态
+  - 内容验收: 内容迁移完整性
+  - 问题汇总: 警告和建议（如有）
+  - 备份路径: 可用于恢复的备份位置
+
+输出格式: 按 G3 场景内容规则（完成）输出
+```
+
+### 场景: 升级验收失败
+
+```yaml
+内容要素:
+  - 验收结果: 失败项列表
+  - 问题详情: 各失败项的具体问题描述
+  - 备份路径: 可用于恢复的备份位置
+  - 恢复建议: 如何使用备份恢复
+
+选项:
+  从备份恢复: 使用备份恢复到升级前状态
+  忽略继续: 接受当前状态（仅警告性失败时可用）
+  手动修复: 用户手动处理问题
+```

package/templates/claude/skills/references/functions/validate.md

@@ -0,0 +1,147 @@
+# ~validate 命令 - 验证知识库
+
+本模块定义知识库和方案包验证的执行规则。
+
+---
+
+## 命令说明
+
+```yaml
+命令: ~validate
+类型: 范围选择类
+功能: 验证知识库和方案包质量，必须选择验证范围（全部/仅知识库/仅方案包），只读操作
+```
+
+---
+
+## 执行模式适配
+
+> 📌 规则引用: 按 G4 路由架构及 G5 执行模式规则执行
+
+<mode_adaptation>
+~validate 模式适配规则:
+1. 本命令为独立工具命令，不受 WORKFLOW_MODE 影响
+2. 为只读操作，不修改任何文件
+3. 无参数时需用户选择验证范围
+4. 发现问题时提供修复方案选项
+</mode_adaptation>
+
+---
+
+## 执行流程
+
+> 📌 规则引用: 脚本路径、存在性检查、错误恢复规则见 references/rules/tools.md
+
+### 步骤1: 确定验证范围
+
+```yaml
+执行内容:
+  - 无参数时询问用户选择
+  - 支持: 全部/仅知识库/仅方案包
+
+按 G3 场景内容规则（确认）输出，见"用户选择处理 - 验证范围选择"
+```
+
+### 步骤2: 验证知识库（如在范围内）
+
+<validation_analysis>
+验证分析推理过程:
+1. 检查核心文件存在性和完整性
+2. 对比文档与代码的接口/数据模型一致性
+3. 扫描空文件、死链、格式问题
+4. 检测敏感信息泄露风险
+5. 按严重程度分级问题（Critical/Warning/Info）
+</validation_analysis>
+
+```yaml
+验证内容:
+  完整性: 核心文件存在性、模块覆盖率
+  一致性: 文档与代码的接口/数据模型对比
+  章节完整性:
+    - modules/{模块}.md: 职责、行为规范、依赖关系（必须）；接口定义（可选）
+    - context.md: 基本信息、技术上下文、项目概述、开发约定、当前约束（必须）；技术债务（可选）
+    - proposal.md: 元信息、需求、方案（必须）；技术设计、核心场景、技术决策（可选）
+  质量: 空文件、死链、格式问题
+  安全: 敏感信息扫描
+```
+
+### 步骤3: 验证方案包（如在范围内）
+
+<package_validation_analysis>
+方案包验证推理过程:
+1. 检查 proposal.md + tasks.md 存在性
+2. 验证目录命名和任务状态符号
+3. 评估描述清晰度和任务粒度
+</package_validation_analysis>
+
+```yaml
+脚本调用: validate_package.py [<package-name>]
+参数:
+  package-name: 可选，指定方案包名称；不指定则验证所有
+输出: JSON 格式的验证结果
+
+验证内容:
+  完整性: proposal.md + tasks.md 存在且非空
+  结构: 目录命名、任务状态符号
+  质量: 描述清晰度、任务粒度
+```
+
+### 步骤4: 生成报告与后续操作
+
+```yaml
+报告内容:
+  - 按严重程度分级（Critical/Warning/Info）
+  - 提供修复建议
+
+有问题时:
+  按 G3 场景内容规则（确认）输出，见"用户选择处理 - 验证问题处理"
+  [等待用户响应]
+  用户选择后按对应选项处理
+
+目录/文件创建: 按 G1 "目录/文件自动创建规则" 执行
+
+完成后: 按 G7 状态重置协议执行
+```
+
+---
+
+## 不确定性处理
+
+- 知识库不存在 → 提示执行 ~init
+- 方案包格式不识别 → 标注"未知格式"
+- 一致性检查无法确定 → 标注"需人工确认"
+
+---
+
+## 用户选择处理
+
+> 本章节定义 ~validate 命令需要用户确认的场景，供 G3 输出格式统一提取。
+
+### 场景: 验证范围选择
+
+```yaml
+内容要素:
+  - 可验证项: 知识库状态、方案包状态
+  - 范围说明: 各选项的验证内容说明
+
+选项:
+  全部: 验证知识库和方案包
+  仅知识库: 只验证知识库完整性和一致性
+  仅方案包: 只验证方案包结构和质量
+  取消: 按 G7 状态重置协议执行
+```
+
+### 场景: 验证问题处理
+
+```yaml
+内容要素:
+  - 验证报告: 按严重程度分级的问题列表（Critical/Warning/Info）
+  - 问题摘要: 问题数量和类型统计
+  - 修复建议: 各问题的建议修复方式
+
+选项:
+  自动修复: 修复格式问题（需 KB_CREATE_MODE≠0）
+  生成修复方案: 创建修复方案包
+  仅记录: 保存验证报告（需 KB_CREATE_MODE≠0）
+  跳过: 不执行操作，按 G7 状态重置协议执行
+```