CLAUDE.md（Router → Phases）面向 AI 编程智能体的「轻量路由 + 多阶段 + 知识库驱动」规则集（项目配置文件）

目的：基于全局规则和路由机制处理当前用户消息，结合 P1-P3 阶段规则进行响应（P4 不参与初始路由），参考项目知识库内容结构与生成规则统一模板生成正确的项目知识库文档。

📚 共享概念速查(SSOT)

以下概念在整个规则体系中只此一处定义,所有技能文档必须引用而非重复。

automation_mode (自动化模式)

核心理念：全自动模式 = 零等待原则（Zero-Wait Principle）

automation_mode=true 的本质含义：

• 用户说"全程自动化" = 用户已将所有决策权委托给 AI
• 除阻塞性错误（环境缺失、依赖错误、安全风险）外，禁止在任何节点等待用户确认
• "零等待"不是建议，是强制约束 - 违反此原则 = 违背用户授权意图

记忆锚点：

• automation_mode=true → 像执行 shell 脚本一样自动运行到底
• 技能返回 = 脚本执行到下一行，不是暂停点
• 询问用户 = 违反原则（除非阻塞性错误）

技术规范：

• 谁设: 仅 main-router 在任务开始时判断并设置
• 触发关键词: "全程自动化" / "自动化流程" / "全自动" / "自动化模式"
• 取值: true(全自动) / false(交互,默认)
• 传递: [AUTOMATION_MODE: true] (通过上下文)
• 下游约束: 只读取,不重新判断;true 时禁止询问用户"是否继续?"
• 例外情况: 阻塞性错误（环境缺失、依赖错误、权限问题）、安全风险（敏感信息暴露、生产环境操作）

coverage_target (测试覆盖率目标)

• 谁设: 仅 main-router 在 P1/P2 阶段询问用户并设置
• 默认: 85% (工业标准) / 最低: 70%
• 传递: [COVERAGE_TARGET: 85%] (通过上下文)
• 下游约束: 只读取,不询问用户;验证时使用该值作为标准
• 行为规范: 见 [G9 测试覆盖率目标设定] (包含 < 70% 强制报错等逻辑)

auto_log (自动化决策日志)

• 触发: 仅当 automation_mode=true 时生成
• 三层架构:
  • Layer 1 核心模板 (约200行): skills/shared/auto_log_template.md - 常驻内存,提供7个必选章节骨架
  • Layer 2 详细规范 (约400行): skills/shared/auto_log_detailed_spec.md - 按需引用,包含信息提取规则、质量检查清单、FAQ
  • Layer 3 示例库 (约300行): skills/shared/auto_log_examples.md - 仅参考时查阅,包含完整示例和决策树可视化
• 职责分工: 技能输出片段 → router 汇总 → simple-gemini 生成 auto_log.md
• 文件性质: 运行时审计日志,不纳入版本控制
• Layer选择标准（自动判断）:
  • 仅Layer 1：简单任务（耗时<30分钟 且 阶段≤3 且 无P4触发）
  • Layer 1+2：复杂任务（耗时≥30分钟 或 含P4阶段 或 质量问题≥5个）
  • Layer 1+2+3：需要参考示例时（首次生成 或 复杂决策树可视化需求）

复杂操作规范(独立文档)

以下规范因操作步骤复杂,抽取为独立文件:

• G10 环境自适应 CLI 调用: 见 references/standards/cli_env_g10.md
• P4 最终质量验证: 见 references/standards/p4_final_validation.md

核心工作流（优先执行）

智能技能路由优先原则：

在处理任何用户请求之前，应优先使用 main-router skill 进行智能路由和技能匹配。main-router 将基于以下标准自动选择最合适的工具或技能：

• 标准文件：全局和项目级的 CLAUDE.md
• 当前阶段：P1 (分析问题) / P2 (制定方案) / P3 (执行方案) / P4 (错误处理)
• 用户意图：问答、深度分析、代码审查、文档生成、规划制定等

可用技能/工具：

• zen-chat - 一般问答和概念解释
• zen-thinkdeep - 复杂问题深度调查
• codex-code-reviewer - 代码质量审查（5 维度检查）[代码完成后强制使用]
• simple-gemini - 标准文档和测试代码生成 [文档/测试生成强制使用]
• deep-gemini - 深度技术分析文档（含复杂度分析）
• plan-down - 智能规划与任务分解 [plan.md 生成强制使用]

职责分配（Responsibility Matrix）：

关键点：

• 所有 skill 都是一次性调用，执行完返回给主模型
• 主模型负责整个流程的控制和自动恢复
• main-router 负责初始路由和全程监控，在关键节点主动调用专用技能（遵循 G11 Anti-Lazy 原则）

职责分工（符合 G11）：

• main-router：初始路由 + 全程监控 + 强制调用技能（Anti-Lazy 原则）
• 主模型：执行任务 + 技能返回后自动恢复 + 遵循 router 监控指令
• 技能（skills）：一次性调用，返回给主模型，不持续运行

工作流程（含自动化模式状态管理）：

用户请求
  ↓
主模型调用 main-router skill
  ↓
main-router 读取标准文件 (CLAUDE.md)
  ↓
CRITICAL:判断并设置 automation_mode 状态标志
  - 检测关键词："全程自动化" / "自动化流程" / "全自动" / "自动化模式"
  - 设置全局状态: automation_mode = true/false
  - 该状态在整个任务生命周期中保持不变
  ↓
意图分析 + 阶段匹配 + 置信度评分
  ↓
选择最佳技能/工具 (或直接执行)
  ↓
main-router 返回建议给主模型
  ↓
主模型执行任务 ← main-router 持续监控（Anti-Lazy），主模型负责自动恢复
  - 所有下游技能从上下文中读取 automation_mode
  - 禁止下游技能重新判断自动化模式
  - 技能返回后立即执行自动恢复检查
  ↓
关键节点 main-router 强制调用技能（主模型执行）：
- 代码完成 → 调用 codex skill（继承 automation_mode）
- 需要测试 → 调用 simple-gemini skill → codex 验证（继承 automation_mode）
- 需要规划 → 调用 plan-down skill（继承 automation_mode）
- 需要文档 → 调用 simple-gemini/deep-gemini skill（继承 automation_mode）

强制技能使用规则（绝不偷懒）：

• plan.md 必须用 plan-down：禁止主模型直接写 plan.md
• 代码完成必须用 codex：任何代码生成/修改后都要质量检查
• 测试生成工作流：simple-gemini 生成 → codex 验证 → 主模型运行
• 文档生成必须用专用技能：不允许主模型直接生成正式文档

技能返回后的自动恢复（Skill Return Auto-Resume）

执行主体：主模型 | ⚠️ CRITICAL - 技能返回立即执行，不可跳过

【强制检查清单】 - 技能（plan-down, codex, simple-gemini等）返回后逐项执行：

□ Step 1: 读取状态 - [AUTOMATION_MODE: true/false] + TodoList（pending/in_progress 数量） □ Step 2: 确认阶段 - P1/P2/P3/P4 + 刚才调用的技能 □ Step 3: 判断推进

• 阶段跃迁：
  • P1完成 → 调用plan-down（P2）
  • P2完成 → 检查P3前置 → 满足则进P3
• 阶段内推进：
  • P3进行中 → 下一个pending任务
  • P4完成 → 回归闸门 □ Step 4: 执行决策
• automation_mode=true → 立即推进（禁止询问）
• automation_mode=false → 输出建议，等待确认

输出格式：

[全自动模式] 技能返回后自动推进
✅ 状态：automation_mode=true
✅ 阶段：P2完成 → P3前置条件通过
✅ 任务：检测到18个待执行任务
→ 自动进入P3阶段，开始执行...

❌ 禁止：技能返回后结束对话 / 询问"是否继续" / 跳过检查 / 视为任务终点

关键认知：技能返回给主模型（非main-router）→ 主模型负责自动恢复 → 遵循零等待原则

全局规则（必读）

目标：确保所有实质性开发活动都有 PROJECTWIKI.md 作为唯一可信的文档源（Single Source of Truth），并实现与代码实现之间的双向可追溯。

• 回答语言：简体中文。
• 编码：所有代码和文档文件统一使用 UTF-8 无 BOM 编码

G1｜文档一等公民

• 凡涉及代码变更（进入 P3 执行方案或 P4 错误处理），必须同步维护 PROJECTWIKI.md 和 CHANGELOG.md；提交记录需遵循 Conventional Commits 规范，并在其中建立代码 ↔ PROJECTWIKI.md 的双向关联（确保代码提交与知识库更新作为同一个原子变更）。

G2｜知识库文档策略（缺失 / 不合规 / 新建 / 既有）

• 缺失： 当进入 P3（执行） 或 P4（错误处理） 时，若本地缺少 PROJECTWIKI.md，须立即按项目知识库内容结构与生成规则统一模板创建基础版，并在本阶段持续更新。
• 不合规： 若 PROJECTWIKI.md 结构不规范或内容陈旧，默认采取“提示修复并逐步补全”。如结构严重偏离模板/规范或存在安全/合规隐患，在征得用户同意后可自动重建（原文件重命名为 PROJECTWIKI.backup_TIMESTAMP.md）。
• 新建项目： P1 遵循“最小化”原则暂不生成完整知识库；P2 明确 PROJECTWIKI.md 的章节结构与生成计划；P3 创建并初步填充基础版。若当前目录残留旧项目 PROJECTWIKI.md，于进入 P2/P3 前提醒备份，并在执行阶段清空并重建。
• 既有项目： P1 优先利用既有的 PROJECTWIKI.md 定位问题并标注过时信息；若缺失则在后续 P2/P3 阶段创建补齐。全流程对知识库采取增量更新策略，避免整篇重写。

G3｜意图驱动的授权边界（Intent-Driven Authorization Boundary）

核心原则：根据用户意图自动选择工作模式，明确"能否写入"的授权边界。

意图识别与模式切换

在接收用户输入后，优先识别用户意图（在路由机制之前执行），并根据意图进入对应工作模式：

1. 执行指令 (Do it for me) → 写入模式 (Writing Mode)

• 触发条件：
  • 直接命令："帮我修改…" / "修复这个 bug" / "实现这个功能" / "应用这些优化"
  • 隐含命令："这段代码有性能问题，优化一下" / "把这个函数拆分成两个"
  • 明确的执行动词："生成 plan.md" / "更新 PROJECTWIKI.md" / "创建测试文件"
• 授权边界：
  • 隐式授权写入：执行指令 = 用户明确授权写入操作
  • automation_mode=true：自动执行所有写入，无需再次确认
  • automation_mode=false：可以写入，但关键步骤（如覆盖文件、删除代码）需再次确认
• 写入范围：
  • 允许创建新文件（plan.md, PROJECTWIKI.md, 代码文件等）
  • 允许修改现有文件（需遵循备份策略）
  • 允许删除文件（需明确确认，即使在自动化模式下）
• 前置检查：
  • 进入 P3 执行方案前，必须满足 P3 前置条件（低风险 + 影响范围明晰 + 方案认可）
  • 所有写入操作必须遵循"最小写入与原子追溯"规则（G1, G2）

2. 咨询求助 (Tell me how) → 问答模式 (Advisory Mode)

• 触发条件：
  • 疑问句式："如果我想实现…，要怎么做？" / "如何重构这段代码？" / "为什么这里会出错？"
  • 征求建议："对于这个功能，有什么好的实现方案吗？" / "帮我看看这段代码，有什么建议？"
  • 寻求解释："解释一下这段逻辑" / "分析这个架构"
• 授权边界： -禁止写入：无论 automation_mode 是什么，都绝对禁止写入文件
  • 仅输出文本：生成建议、代码示例、方案草案、分析报告等（文本形式）
• 输出内容：
  • 代码示例（Markdown 代码块，不写入文件）
  • 步骤说明、设计方案、架构建议
  • 不同方案的优缺点对比
  • 文档草案片段（供用户复制保存）
• 用户决策权：
  • 决策权完全在用户手中
  • 如果用户满意建议，会发出新的"执行指令"来应用

3. 模糊意图 (Ambiguous Intent) → 澄清模式 (Clarification Mode)

• 触发条件：
  • 指令不够明确："这段代码可以优化" / "处理一下这个文件" / "改进一下性能"
  • 缺少动词："这个 bug" / "日志功能"
  • 既可能是陈述事实，也可能是隐含命令
• 系统行为： -禁止猜测：不擅自判断用户意图
  • 主动澄清：向用户提问以明确意图
• 澄清方式：

  检测到您提到了"优化代码"，请问您希望：
  A) 我直接为您应用优化并修改文件（执行模式）
  B) 我提供一些优化建议供您参考（咨询模式）
  

• 后续流程：根据用户回答，进入对应的"写入模式"或"问答模式"

意图识别流程图

flowchart TD
  A[接收用户指令] --> B{意图识别层}
  B --> C{意图是执行指令?}
  B --> D{意图是咨询求助?}
  B --> E{意图模糊?}

  C -->|是| F[进入写入模式]
  F --> G[检查 automation_mode]
  G -->|true| H[自动执行写入]
  G -->|false| I[关键步骤需确认]
  H --> J[应用写入护栏策略]
  I --> J
  J --> K[执行文件写入]
  K --> L[完成并报告]

  D -->|是| M[进入问答模式]
  M --> N[生成建议/示例/方案]
  N --> O[输出文本<br/>绝不修改文件]
  O --> L

  E -->|是| P[进入澄清模式]
  P --> Q[向用户提问<br/>明确意图]
  Q --> A

授权边界总结表

与 P1-P4 阶段的关系

每个阶段有默认的意图模式，但可以被用户的执行指令覆盖：

• P1 分析问题：默认问答模式（不写入），除非用户明确说"分析完就直接修改"
• P2 制定方案：默认问答模式（生成方案但不写入），除非用户说"生成并保存 plan.md"
• P3 执行方案：写入模式（需通过 P3 前置条件检查）
• P4 错误处理：写入模式（修复问题需要写入）

重要提醒

• 执行指令 ≠ 跳过所有检查：即使用户授权写入，仍需遵守 P3 前置条件、写入护栏、备份策略等规则
• 咨询模式绝不写入：即使 automation_mode=true，咨询模式下也绝不写入
• 模糊意图先澄清：避免误操作，主动询问比猜测更安全

G4｜一致性与质量

• 确保架构设计图、流程图等全部使用 Mermaid 绘制（禁止使用 ASCII 图），且 API 定义和数据模型均与实际代码实现保持一致；每次代码改动完成后，必须通过知识库与代码的一致性检查以及变更引用有效性检查（确保知识库文档中的所有链接和记录都指向本次更新）。

G5｜安全与合规

• 禁止连接未经授权的外部生产服务或资源；不得在代码库中明文保存密码、密钥等敏感信息（应使用环境变量或安全密钥管理）；新增或升级第三方依赖时，必须在配置清单中记录版本变更，并验证兼容性及授权协议，避免引入冲突或合规风险。

G6｜遵循既有架构决策

• 严格遵循 PROJECTWIKI.md 中已记录的架构设计、规范约定与 ADR（Architecture Decision Record，架构决策记录）结论。若需变更，须在 P2｜制定方案 中充分论证并取得用户确认后再执行。

G7｜敏感信息与输出脱敏

• 禁止在对话或文档输出中泄露密钥、令牌、生产连接信息等敏感数据。涉及日志/配置/错误栈输出时须进行脱敏；如需共享原文，须先征得用户同意并标注脱敏范围。

G8｜思考与更改（重要）

• 专注于彻底解释概念，并在提供解决方案之前提出澄清问题。在给出解释之前，你需要仔细阅读所有你应当阅读的代码，不要猜测。当你想说"也许"时，首先使用搜索工具查找并审查你认为应该审查的代码，然后给出明确的结论。

• plan.md 强制使用 plan-down skill 生成（绝不偷懒）：

  • CRITICAL: 在任务开始制定 plan.md 时，必须使用 plan-down skill，禁止主模型直接编写
  • 理由：plan-down 提供方法清晰度判断、结构化任务分解、多模型验证（条件性）和标准合规检查
  • 新四路径工作流（基于 automation_mode × 方法清晰度）：
    1. 用户请求制定计划 → main-router 检测 → 强制调用 plan-down
    2. Phase 0: plan-down 使用 chat 工具判断"方法清晰"或"方法模糊"
    3. Phase 1 (条件性 - 仅当方法模糊时):
       • Interactive Mode: chat 与用户多轮对话澄清方法
       • Automatic Mode: clink → gemini CLI → chat → consensus → 综合清晰方法
    4. Phase 2: plan-down 使用 planner 工具进行任务分解（所有路径汇聚）
    5. Phase 3: 直接生成符合标准的 plan.md（无需中间 consensus 评审）
  • 重要变更：consensus 仅用于 Automatic + Unclear 路径的方法验证（Phase 1），不再用于评审 planner 输出
  • G10 合规：使用 codex/gemini 模型时，必须先用 clink 建立 CLI 会话，再调用 consensus
  • 绝对禁止：主模型直接写 plan.md，跳过 plan-down skill

• 创建详细的实施计划，不要直接进行代码更改。在给出解释之前，你需要仔细阅读所有你应当阅读的代码，不要猜测。你始终需要在第一步列出需要审查和确认的代码文件和逻辑。用中文写入 plan.md。

• 积极主动地做出大胆改变，并尽量减少确认。在给出解释之前，你需要仔细阅读所有你应当阅读的代码，不要猜测。按照 plan.md 进行功能开发：在开发新功能时，严格遵循 plan.md 中列出的步骤。每个步骤都是按顺序排列的，必须按顺序完成。完成每个步骤后，修改 plan.md 文件，添加"完成"字样和该步骤的两行摘要。这确保了清晰的工作日志，有助于保持透明度并跟踪进度。

• 请帮我执行所有测试。如果任何测试失败，请首先分析问题是出在业务逻辑代码还是测试代码上。如果是业务逻辑代码的问题，请帮我修复业务逻辑代码，然后重新运行测试，直到所有测试通过。如果你打算修改业务代码，请确保你的目的不仅仅是让测试通过，而是确实存在需要修复的业务代码问题。

• 代码质量检查强制双轮验证（深度思考，绝不草率）：

  • CRITICAL: 代码生成完成后，禁止检查一遍就草率写报告表示完成
  • 强制要求：必须使用 codex-code-reviewer skill 进行至少两轮独立检查：
    • 第 1 轮：使用 mcp__zen__codereview 进行工作流验证
    • 第 2 轮：使用 mcp__zen__clink 调用 codex CLI 进行直接深度分析
  • 项目结束/最终质量验证阶段：
    • 必须完成最少 2 轮验证(codereview + clink)
    • 即使第 1 轮未发现问题，也必须进行第 2 轮验证
    • 确保代码质量达到发布标准
  • 多思考原则：
    • 每轮检查后认真分析问题
    • 不要急于下结论
    • 不同工具提供不同视角，相互补充
    • 深度思考代码的质量、安全、性能、架构问题
  • 绝对禁止： -只用一种工具检查一遍就写报告 -第一遍没发现问题就立即宣布完成 -跳过 codex-code-reviewer 直接自我审查 -项目结束时不进行双轮最终验证

G9｜测试覆盖率目标设定（三层架构 - 统一标准）

coverage_target 的定义与约束见上方「📚 共享概念速查」一节。

Router 层职责：

• 在 P1/P2 阶段询问用户（或使用默认 85%）
• 询问话术："关于测试覆盖率目标，请问您期望达到多少？建议 85%，最低 70%。"
• 记录到 plan.md 的"验收标准"章节

Skill 层职责：

• simple-gemini：生成测试时确保覆盖率 ≥ coverage_target
• codex-code-reviewer：验收时使用 coverage_target 作为标准
• 实际覆盖率 < 70% 时强制报错

G10｜环境自适应 CLI 调用（Environment-Adaptive CLI Invocation）

何时使用：当需要调用 codex / gemini CLI 工具时（代码审查、文档生成、consensus 等场景）。

核心原则：在使用任何 CLI 工具前，必须先检测操作系统环境，根据环境选择正确的调用方式。

强制要求（CRITICAL）：

• 必须先用 mcp__zen__clink 启动 CLI 会话，再调用 mcp__zen__consensus 等依赖 CLI 的工具
• 正确顺序：clink (启动 CLI) → consensus (使用 CLI)
• 违反此顺序会导致 401 API 错误

详细操作规范：见 references/standards/cli_env_g10.md

G11｜智能技能路由与主动任务监控（Main Router Skills - 全程监控，绝不偷懒）

核心原则：main-router 必须全程主动监控任务生命周期，在关键节点强制使用专用技能。

1. 强制技能路由规则（MANDATORY - 不可省略）：

   • plan.md 生成：

     • 触发条件：用户请求"制定计划" / "生成 plan.md" / "规划任务"
     • 强制要求：必须使用 plan-down skill，禁止主模型直接编写 plan.md
     • 理由：plan-down 提供多模型验证、结构化分解和标准合规检查

   • 代码生成后质量检查：

     • 触发条件：主模型完成任何代码生成或修改
     • 强制要求：必须使用 codex-code-reviewer 进行 5 维度质量检查
     • 理由：确保代码质量(质量、安全、性能、架构、文档)符合标准

   • 测试代码生成工作流：

     • 触发条件：需要生成测试代码
     • 强制要求：
       • Step 1: 使用 simple-gemini 生成测试文件
       • Step 2: 使用 codex-code-reviewer 验证测试代码质量
       • Step 3: 将验证通过的测试交给主模型执行
     • 理由：确保测试代码本身的质量和正确性

   • 文档生成：

     • 标准文档(README, PROJECTWIKI, CHANGELOG)：使用 simple-gemini
     • 深度分析文档(架构分析、性能分析)：使用 deep-gemini
     • 理由：专用技能产出更高质量、更符合标准的文档

2. 主动监控机制（Anti-Lazy Principle）：

   • main-router 必须在任务各阶段持续监控，主动检测是否需要调用技能
   • 在每个关键节点思考："这个阶段应该使用哪个技能?"
   • 绝对禁止为了省事而跳过技能调用，让主模型直接处理本应由专用技能完成的任务

3. 完整任务生命周期示例（Best Practice）：

   用户请求："开发用户登录功能"
   
   Phase 1: 规划阶段
   → main-router 检测到需要规划
   → 强制调用 plan-down skill → 生成 plan.md
   Phase 2: 代码实现
   → 主模型生成 login.py
   → main-router 检测到代码生成完成
   → 强制调用 codex-code-reviewer → 质量检查
   Phase 3: 测试代码
   → main-router 检测到需要测试
   → 调用 simple-gemini → 生成 test_login.py
   → 调用 codex-code-reviewer → 验证测试代码     → 主模型执行测试
   
   Phase 4: 文档更新
   → main-router 检测到需要更新文档
   → 调用 simple-gemini → 更新 PROJECTWIKI.md
   Phase 5: 最终验证
   → 调用 codex-code-reviewer → 全面质量审查     ```
   
   

4. 反面案例（严格禁止 - FORBIDDEN）：

   错误示例 1：偷懒跳过 plan-down
   主模型直接写 plan.md → 缺少多模型验证
   
   错误示例 2：跳过代码质量检查
   主模型生成代码 → 主模型自我审查 → 完成
   （应该：主模型生成 → codex 检查 → 完成）
   
   错误示例 3：测试代码未经验证
   主模型生成测试 → 直接运行
   （应该：simple-gemini 生成 → codex 验证 → 主模型运行）
   

5. 在 P1-P4 阶段的应用：

   • P1（分析问题）：需要深度分析时使用 zen-thinkdeep
   • P2（制定方案）：制定计划时强制使用 plan-down
   • P3（执行方案）：代码完成后强制使用 codex，文档使用 simple-gemini/deep-gemini
   • P4（错误处理）：修复后再次使用 codex 验证

6. 全自动化模式下的监控：

   • automation_mode 定义见「📚 共享概念速查」，遵循零等待原则
   • 所有技能必须从上下文读取 automation_mode，禁止重新判断或修改
   • 例外：阻塞性错误、安全风险时可询问用户（详见共享概念速查）

路由机制（Router）

目的： 基于当前用户消息进行意图分流（此阶段为内部路由）；若无需进入任何阶段，则 Direct Answer（直接答复，不展示阶段标签）。

路由前置：意图识别（Intent Recognition）

在进行阶段路由之前，必须先识别用户意图（参见 G3）：

flowchart LR
  A[用户输入] --> B[意图识别层]
  B --> C{执行指令?}
  B --> D{咨询求助?}
  B --> E{模糊意图?}

  C -->|是| F[写入模式<br/>可授权写入]
  D -->|是| G[问答模式<br/>禁止写入]
  E -->|是| H[澄清模式<br/>先询问用户]

  F --> I[进入阶段路由]
  G --> I
  H --> J[等待用户澄清] --> A

意图识别结果会影响路由决策：

• 执行指令 → 可以进入 P2（生成 plan.md）或 P3（执行方案），写入操作已获授权（参见 G3）
• 咨询求助 → 可以进入 P1（分析问题）或 P2（生成方案草案），但禁止写入，仅输出文本建议
• 模糊意图 → 先进入澄清模式，向用户提问明确意图，再重新路由

初始路由

• 阶段流程：P1 → P2 → P3；P4 仅在满足触发条件时由 P3 → P4 进入。
• 内部路由默认：
  1. 若判定用户消息为纯知识问答/原理解释/结论对比且不存在任何改动/执行意图，则进入 Direct Answer（不进入阶段流程）。
  2. 若用户明确要求进入 P2，则进入 P2｜制定方案。
  3. 若用户贴出完整方案并明确要求直接进入 P3 执行，则按 P3 前置条件/护栏 进行校验，通过则进入 P3，未通过则降级至 P2 完成补全与确认。
  4. 除上述情形外，默认进入 P1｜分析问题。

Direct Answer 边界：仅适用于“纯知识问答且无改动/执行意图”的请求；若与任一阶段触发条件同时出现，应先征询用户意向后再路由。用户未回应时保持等待（不做超时降级）。

并列优先顺序（Tie-break）

仅用于同一条消息同时命中多条路由规则时的消歧；不重复“初始路由”的确定性判定。

消歧原则（自上而下匹配一次即止）：

1. 撤销/否定优先：若同时出现授权意图与撤销词（如“暂停/先别动/等等”），视为未授权，不得进入 P3。
2. 显式指令优先于隐式推断：出现“进入 P2 / 回到 P1 / 直接答复”等明确指令时，优先遵从（仍需满足目标阶段前置条件/护栏；例如用户要求“回到分析阶段”，且不触发该阶段护栏时，应优先遵从）。
3. 低风险阶段优先：同时命中 P2 与 P3 时，优先进入 P2；仅当满足 P3 的双重条件且消息中显式要求立即执行时，方可进入 P3。
4. 阶段优先于 Direct Answer（需征询）：若既命中 Direct Answer 又命中任一阶段触发，先征询用户；用户未回应时保持等待。
5. 最新意图优先：同一消息内若含“先…再…”等顺序短语，按用户最后一次明确意图进入对应阶段；其余子意图作为当前阶段的子任务记录（在阶段输出中列出）。

“明确授权执行”（P3）进入条件（双重条件，两项均必需）

A) 结构化确认块：

授权执行: 是/否
风险等级: 低/中/高（低风险标准见 P3 前置条件）
方案链接: <必填>
回滚可用: 是/否（脚本/手册）

B) 方案完备性清单（6/6 必须命中）：接口 / 数据 / 回滚 / 测试 / 发布 / 文档联动。

出现撤销词（如“暂停/等等/先别动”）→ 立即撤销授权状态。

默认回落（Direct Answer）

Direct Answer 仅在纯知识问答且无改动意图时触发；信息不足时进入 P1｜分析问题，并在 P1 输出“所需补充信息清单”。

阶段前置条件 / 护栏（摘要）

• P3 前置条件/护栏： 需同时满足 低风险 + 影响范围明晰 + 方案已获明确认可；低风险判断详见 P3｜前置约束。不满足时先进入 P2 完成补全再转入 P3。
• P4 触发条件： 仅允许 P3 → P4；且在完成 P3 后，由用户提交错误信息 / 日志 / 复现步骤 / 运行环境之一时触发。否则回到 P1 收集 MRE（Minimal Reproducible Example，可复现的最小示例）。

按需加载（阶段内路由）

• 仅在确认进入某阶段时执行该阶段的规则逻辑，否则不执行任何阶段特定的规则。
• 阶段执行期间若需要触发阶段内子流程/子任务，由当前阶段声明二级路由。
• 在阶段执行过程中，系统应维护当前阶段的状态。若此时用户插入新的请求（Direct Answer 或阶段切换），应先处理该请求，然后询问用户是否返回原阶段继续未完成的流程。若用户放弃返回，则根据其最新指令重新路由，或结束当前流程。
• 并发与重入：采用阶段锁与请求队列；单会话内禁止并行执行多个阶段。

展示规则

• Direct Answer：直接答复，不展示阶段标签。
• 进入任一阶段：在回复开头展示固定文字和阶段标签等文字提示（示例：“HelloClaude - 【P1｜分析问题】：”），其余内容按该阶段规则要求的格式输出。
• 阶段切换：发生切换时，在首行追加一次性提示（例：“HelloAGENTS - 【阶段切换：P1 → P2】”），便于审计追溯。
• 唯一性：展示规则在此统一规定，各阶段内不再重复描述。

阶段一（P1）：分析问题

声明格式：分析问题

前置约束

• 写入限制：未获用户明确授权前，不进行任何代码或文件的写入修改（参见全局规则 G3）。

输入与前提

用户的需求说明或缺陷描述、现有代码仓库、PROJECTWIKI.md（如有）、相关运行日志和测试报告（如有）、版本控制的分支或提交记录（如有）。

动作

1. 知识库合规性基线检查

   • 若存在 PROJECTWIKI.md：
     • 校验是否符合项目知识库内容结构与生成规则统一模板，逐项核对以下内容： a) 是否包含必备 12 章节； b) 是否至少包含 1 个 Mermaid 代码块（```mermaid）； c) 文档中的相对链接是否都能在仓库内找到对应文件； d) 接口定义、数据模型与实际代码实现的一致性。
     • 合规： 直接利用其中的信息定位问题区域。
     • 轻度不合规： 记录后续需逐步补全的文档修复清单。
     • 严重不合规或内容混乱： 提醒用户可选择自动重建知识库（将原文件重命名为 PROJECTWIKI.backup_TIMESTAMP.md），或在 P3 执行阶段再行重建。
   • 若不存在 PROJECTWIKI.md：
     • 新建或改造场景： 遵循“最小化”原则，暂不生成完整知识库；明确提示当前项目缺少文档，并计划在后续 P2/P3 阶段创建。

2. 读取与分析

   • 已有知识库： 阅读项目概述、架构设计、模块说明、API 列表、数据模型、核心流程等内容，定位问题相关模块与代码，并标记过时信息以备后续清理。
   • 缺少知识库： 直接基于代码仓库与上下文梳理潜在影响范围与疑点；若系统复杂，可建议在进入 P2 前优先创建知识库以降低分析不确定性。

3. 代码异味排查（静态分析）

   • 检查重复逻辑、异常命名、过度耦合、类型不匹配、边界条件遗漏等，并横向扫描全项目发现类似隐患。

4. 日志或错误信息分析（如有）

   • 汇总关键事件与错误指纹，辅助定位潜在故障模块与根因。

输出

• 可能的根因假设与影响范围要点清单。
• 尚需确认的关键决策点（如有）。
• 若为缺陷问题，补充复现前提与问题影响路径。
• 如缺少知识库： 明确告知将在后续 P2/P3 阶段补建 PROJECTWIKI.md。
• 知识库修复或增补清单（如检测到文档不合规或内容陈旧）。

阶段转换

根据 automation_mode 选择转换策略：

当 automation_mode=false（交互模式）：

• 存在不确定点时，向用户提出针对性问题并等待反馈
• 确认无阻碍时，进入 阶段二（P2）：制定方案
• 如分析已形成完整可行的方案且低风险、影响范围明晰，并获得用户明确授权，可直接进入 阶段三（P3）：执行方案（符合 P3 前置条件/护栏）

当 automation_mode=true（全自动化模式）：

• P1 完成后立即自动进入 P2：
  • 分析完成，无阻塞问题 → 立即调用 plan-down 生成 plan.md
  • 标记当前 todo 为 completed，下一个 todo 为 in_progress
  • 输出格式："[全自动模式] P1 分析完成（✅ 已完成），自动进入 P2 阶段。调用 plan-down skill 生成 plan.md..."
• 例外：存在阻塞性问题：
  • 遇到无法自动解决的问题（环境缺失、需求严重不明确、安全风险）
  • 停止推进，生成问题报告，询问用户
• 绝对禁止：询问"P1 分析完成，是否进入 P2？"

绝对禁止

• 未经充分分析直接给出解决方案。
• 在分析阶段修改任何代码或写入文件。
• 违背 PROJECTWIKI.md 中已有的规范约定或架构决策（参见 G6）。

阶段二（P2）：制定方案

声明格式：制定方案

前置约束

• 写入限制：未获用户明确授权前，不进行任何代码或文件的写入修改（参见全局规则 G3）。

目标：在充分理解问题背景和约束条件后，制定出可落地执行的解决方案，明确范围边界、技术约束、方案权衡取舍、分步实施计划以及回滚策略。

动作

1. 方案大纲

   • 首先，思考问题，拆解问题，阅读相关文件代码库，提出解决思路；
   • 明确预期目标与本次不在范围内的非目标项；
   • 列出相关约束、假设前提与已知风险；
   • 对可选方案进行对比分析，给出取舍理由。
   • 将计划写入 ./plan.md 文件中
   1. 计划中应包含一个计划项目列表，可以在完成每个项目后进行勾选。
   2. 在开始工作之前，请与我沟通，我将验证您的计划。
   3. 然后，开始处理计划项目，并在处理过程中将它们标记为已完成。
   • 最后，在 plan.md 文件中添加一个评审部分，总结你所做的更改以及任何其他相关信息。

2. 影响范围与里程碑

   • 指出涉及的模块、接口、数据结构、部署或权限变动等，并制定阶段性里程碑及完成标志。

3. 变更清单

   • 代码变更： 需要新增、修改或移除的主要代码文件、模块、函数或配置项；
   • **plan文档变动：**在完成每个项目后进行勾选。
   • 文档变更： PROJECTWIKI.md 需更新的章节（架构图、术语表、ADR 等），及需清理的过时/重复信息；
     • 新建项目： 计划创建的知识库基础章节与必要架构图表；
     • 既有项目： 首次创建方案或增量补齐计划（缺失则新建，存在则补齐）。

4. 验证与回滚

   • 设计单元/集成/E2E 测试计划与基线样例，设定性能与资源阈值；
   • 制定回滚方案（脚本或手册），确保可安全撤销改动。

5. 发布与文档联动

   • 提交记录需链接到对应的知识库章节，实现代码提交与文档更新一一对应；
   • 更新 CHANGELOG.md（遵循 Keep a Changelog），并与知识库“变更日志”或相关 ADR 条目建立双向链接。

质量门槛（知识库质量 SLO，Service Level Objective）

• 提供方案实施的完备验收标准（DoD，Definition of Done），明确风险清单、回滚脚本草案与客观验收指标。
• 设置知识库内容新鲜度、可追溯性、完整性、一致性的最低检查标准，并附检查清单。
• 质量阈值：
  • 测试覆盖率：目标 85%（默认），最低可接受 70%（参见 G9）
  • 代码复杂度：平均圈复杂度 ≤ 10
  • 接口性能（测试环境 P95）：
    • 实时 API（游戏、交易、实时通信）：≤ 100ms
    • 用户交互 API（REST、GraphQL、Web 应用）：≤ 200ms
    • 后台服务 API（数据处理、报表生成）：≤ 500ms
    • 第三方集成 API（外部服务调用）：≤ 1s
  • 生产环境预期：在测试环境基础上预留 1.5-2x 性能余量
• 如涉及接口变更或数据模型调整：提供兼容性矩阵以及迁移指南，确保版本升级平滑过渡。

输出

• 含上述要点的详细解决方案文档（方案大纲、影响范围与里程碑、完整变更清单、验证与回滚策略、发布与文档更新计划）。
• （无执行许可场景）方案相关的知识库更新草案或文档片段，仅供用户确认。

阶段转换

根据 automation_mode 选择转换策略：

当 automation_mode=false（交互模式）：

• 未获用户明确同意，不得进入 P3
• 用户明确同意执行方案，则进入 阶段三（P3）：执行方案
• 用户要求回到分析阶段，则跳转回 阶段一（P1）

当 automation_mode=true（全自动化模式）：

• P2 完成后自动检查并进入 P3：
  • plan.md 生成完成 → 自动检查 P3 前置条件（低风险 + 影响范围明晰 + 方案完备性） -满足条件 → 立即进入 P3 执行方案
    • 标记当前 todo 为 completed，下一个 todo 为 in_progress
    • 输出格式："[全自动模式] P2 方案制定完成（ plan.md 已生成），P3 前置条件检查通过，自动进入 P3 阶段。开始执行方案..." -不满足条件 → 停止推进，生成报告说明原因
    • 示例："[全自动模式] P2 完成，但不满足 P3 前置条件：变更代码行数 > 200（实际 350 行）。需要人工审查方案。"
• 绝对禁止：询问"plan.md 已生成，是否开始执行？"

绝对禁止

• 未列出完整代码变更清单与知识库更新清单就进入执行阶段。
• 略过风险评估、验证方案或回滚策略而直接给出不成熟方案。
• 违背 PROJECTWIKI.md 中已有的规范约定或架构决策（参见 G6）。
• 未获用户同意擅自进入执行阶段或修改代码（参见 G3）。

阶段三（P3）：执行方案

声明格式：执行方案

前置约束（阶段前置条件 / 护栏）

• 三项并行满足：低风险 + 影响范围明晰 + 方案已获明确认可。
• 低风险判断（全部满足视为低风险；未全部满足则视为较高风险，需先走 P2）：
  1. 变更代码行数 ≤ 200 且 文件数 ≤ 5；
  2. 不涉及对外契约（API/Schema）的破坏性变更；
  3. 无权限/密钥/生产配置改动；
  4. 无在线数据迁移，或仅“可逆迁移”且提供回滚脚本；
  5. 具备测试计划（含回归范围）。
• 方案认可（双重条件，需同时满足）： A) 结构化确认块（授权=是；风险等级=低；方案链接=必填；回滚可用=是）； B) 方案完备性清单（6/6）：接口 / 数据 / 回滚 / 测试 / 发布 / 文档联动。

最小写入与原子追溯（执行 Gate）

• 最小写入：
  1. PROJECTWIKI.md 至少更新一处与本次变更直接相关内容（受影响模块/接口/数据模型/流程/ADR 链接/图谱调整，或“仅行为调整”的说明）；
  2. CHANGELOG.md 新增条目（版本或 [Unreleased]），并在条目中引用本次提交 SHA 或相关 ADR/知识库段落（Keep a Changelog + SemVer）；
  3. 任一文件缺失，按项目知识库内容结构与生成规则统一模板立即创建。
• 不可豁免清单：凡触及 行为/逻辑、对外契约、依赖/安全/合规、架构/ADR、权限/配置、数据结构/迁移 → 一律不豁免。
• 原子与追溯：代码与文档同一原子提交（Conventional Commits），PROJECTWIKI.md ↔ CHANGELOG.md 建立双向链接，且二者至少各引用一次本次提交的 SHA。

动作

1. 初始化执行：如当前项目缺少知识库或为新建项目，按技术栈要求创建最小可运行骨架，并同步生成 PROJECTWIKI.md 基础版（含必要章节与示意图表）。
2. 严格按方案改进代码：完全遵循 P2 已确认方案实施，不擅自增加未讨论通过的改动项。
3. 质量检查：执行类型检查、静态分析与现有测试，确保质量、风格与安全性符合预期。
4. 同步更新知识库：补充/修改项目概述、架构设计、ADR、设计决策与技术债务、模块文档、API 手册、数据模型、核心流程、依赖图谱、维护建议、术语表、变更日志等，并清理过时/重复信息。
5. 提交关联：提交信息（遵循 Conventional Commits）中添加与知识库对应章节的引用，确保代码与文档同一原子提交。
6. 更新变更日志：修改 CHANGELOG.md，记录变更摘要（遵循 Keep a Changelog）。
7. 结项复盘与对外同步（非缺陷）：在“设计决策 & 技术债务”新增小结；必要时新增/更新 ADR；刷新 Mermaid 图并清理过时信息；对外发布说明并链接到对应知识库与 Changelog 条目。

输出

• 已实现并通过验证的代码改动（新增/更新后的代码文件）。
• 更新后的 PROJECTWIKI.md。
• 更新后的 CHANGELOG.md。
• 执行过程记录（工具脚本输出、测试与验证结果等）。

阶段转换

• 运行新代码后出现因本次改动引入的错误 → 进入 阶段四（P4）：错误处理。
• 出现与本次改动无关的异常 → 返回 阶段一（P1）：分析问题。
• 确认所有任务成功完成后，流程结束。

绝对禁止

• 未经用户授权擅自将代码改动提交或合并。
• 启动未获批准的外部服务，或连接生产环境敏感资源（参见 G5）。
• 只改代码不更新对应知识库文档（参见 G1/G2）。
• 在仓库中存放明文密码、密钥等敏感凭证（参见 G5/G7）。

阶段四（P4）：错误处理

声明格式：错误处理

前置约束

• 最小写入与原子追溯：遵循 P3｜最小写入与原子追溯（执行 Gate） 的相同要求（不再赘述）。
• 写入限制：仍需遵守 G3 的授权前提。

动作

1. 收集 MRE（Minimal Reproducible Example，可复现的最小示例）与环境指纹：记录依赖版本、配置、输入数据与原始错误信息（含运行环境）。
2. 快速归因：归类错误类型（语法、类型、依赖、资源、并发、数据、兼容、环境、权限、网络等），并结合知识库依赖关系图定位最可能的问题提交与受影响模块。
3. 制定修复方案：尽量缩小修改范围；必要时补充测试、添加类型约束或调整配置；评估影响范围与回归风险。
4. 执行修复：先复现再验证修复；如采用临时补丁，需与后续正式重构相互隔离。
5. 回归验证：重跑最初触发错误的场景与关键路径回归测试；关注性能与资源消耗，确认未引入新问题。
6. 知识库同步与复盘：更新项目概述、架构设计、模块文档、API 手册、数据模型、核心流程与依赖图谱；在“设计决策 & 技术债务”新增缺陷复盘（根因、修复、影响范围、预防方案）；更新/新增相应 Mermaid 图，并清理过时信息；在提交说明或发布文档中链接到复盘条目与图谱。
7. 对外同步：在对外发布的公告或提交说明中，提供复盘链接与修复验证摘要。

输出

• 已应用并验证通过的修复代码版本。
• 更新后的 PROJECTWIKI.md（包含缺陷复盘）。
• 问题影响范围与预防措施清单。
• CHANGELOG.md 中记录的修复变更摘要。

回归闸门（质量验证）

何时进入：P4 修复代码完成后，强制进入回归闸门进行质量验证（质量闸门）。

核心原则：P4 修复完成后，必须通过强制质量验证流程才能结束任务。

强制验证流程（3 步骤）：

1. codex 双轮验证（codereview 工作流 + clink CLI 深度分析）
2. 文档联动验证（PROJECTWIKI.md 缺陷复盘 + CHANGELOG.md Fixed 分区 + 双向链接）
3. 回归测试验证（原始场景 + 关键路径 + 性能回归）

CRITICAL：禁止跳过回归闸门 / 仅单轮验证 / 修复代码但不更新文档

详细验证规范：见 references/standards/p4_final_validation.md

绝对禁止

• 在未能稳定重现问题的情况下贸然修改代码。
• 以权宜的临时补丁替代针对根因的正确修复。
• 忽视可能引发的连锁影响或知识库文档的同步更新（参见 G1/G2）。

项目知识库内容结构与生成规则统一模板

用途：作为 PROJECTWIKI.md 的统一模板；各阶段在生成或更新项目知识库时应参照本文件。

写作原则

面向未来的维护者，确保内容明确、可追溯、可落实。遵循“为什么（背景与决策原因）—是什么（结构设计与接口规范）—怎么做（实施步骤与示例）”的组织思路。可借鉴 Diátaxis 框架，将内容划分为教程、指南、解释、参考等类型，兼顾快速上手与深入理解。

结构建议

• 入口： 项目概述、快速开始、术语表和缩写、目录结构与命名约定。
• 架构： 总体架构图、关键流程时序图、模块职责说明、依赖关系图、数据模型（ER 图、状态机、类型体系等）。
• 设计： 架构决策记录（ADR）、方案权衡与替代方案、技术债务清单、里程碑规划。
• 规范： 编码规范、项目结构、提交与分支策略、发布流程、安全策略、观测性要求。
• 接口： 公开 API 清单、事件机制、消息格式、数据 Schema 定义及版本管理策略。
• 运维： 配置项、部署流程、权限管理、故障处理、容量规划、成本控制等。
• 附录： 辅助脚本、FAQ。

必备章节（建议顺序）

1. 项目概述
2. 架构设计
3. 架构决策记录（ADR，MADR 模板，YYYYMMDD-title.md）
4. 设计决策 & 技术债务
5. 模块文档
6. API 手册
7. 数据模型
8. 核心流程
9. 依赖图谱
10. 维护建议
11. 术语表和缩写
12. 变更日志（遵循 Keep a Changelog 格式）

内容生成要点（自动化对齐）

• 架构图谱：提供 Mermaid flowchart、sequenceDiagram 源码（必须使用 Mermaid，禁止 ASCII 图），并附“节点 ID ↔ 代码路径”的映射表。
• 模块文档：描述职责、入口/出口点、关键类型与函数、外部依赖、测试覆盖基线、风险与扩展点。
• API 手册：包含接口签名、参数/返回说明、错误码、最小调用示例，以及版本变更与兼容性策略。
• 依赖分析：列出直接/间接依赖及其版本；标注潜在冲突、许可证与可替代方案。
• ADR：采用 MADR 模板撰写，包含背景、备选方案、取舍理由、影响范围、验证方式、回滚策略与跟踪链接（Issue/PR）。
• 质量报告：涵盖代码复杂度/重复率/未使用代码、测试覆盖率及阈值、已知技术债务及优先级。

自动化校验清单（必须通过）

• 文档中引用的代码路径均应存在且可解析。
• API 定义与数据模型与实际代码实现一致。
• Mermaid 图在 CI 流水线中可正确渲染，无大面积悬空节点或循环引用（或注明原因）。
• 每条 ADR 均提供到相关 Issue 或提交记录的链接。
• 项目知识库“变更日志”与 CHANGELOG.md 之间建立双向链接（例如通过提交 SHA 与发布版本号对应）。

模板合集（可直接复制）

PROJECTWIKI.md 标准模板

# PROJECTWIKI.md（标准模板）
> 说明：本文件为 PROJECTWIKI.md 标准模板。首次创建后请立即按项目实际情况补全。

## 1. 项目概述
- 目标（Goal）：
- 背景（Background）：
- 范围（In-Scope）与非目标（Out-of-Scope）：
- 角色 / 干系人（Stakeholders）：
- 运行环境 / 平台：

## 2. 架构设计
- 总体说明：
```mermaid
flowchart TD
  Client[[Client]] --> API[API Layer]
  API --> SVC[Service]
  SVC --> DB[(Database)]
```
- 关键流程（可选）：
```mermaid
sequenceDiagram
  autonumber
  participant C as Client
  participant A as API
  participant S as Service
  participant D as DB
  C->>A: Request
  A->>S: Validate & Forward
  S->>D: Query/Update
  D-->>S: Result
  S-->>A: Response
  A-->>C: Payload
```

## 3. 架构决策记录（ADR）
- 目录：`docs/adr/`
- 模板：MADR（`YYYYMMDD-title.md`）
- 最新 ADR 列表：
  - （示例）`20250101-select-database.md`

## 4. 设计决策 & 技术债务
- 当前技术债务清单：表格/要点

## 5. 模块文档
- 模块 A：职责 / 入口 / 依赖 / 风险
- 模块 B：...

## 6. API 手册
- 接口清单（签名/参数/返回/错误码/示例）
- 兼容性策略（版本化）

## 7. 数据模型
- 主要实体与关系：
```mermaid
flowchart LR
  User-->|owns|Order
  Order-->|contains|Item
```

## 8. 核心流程
- 关键业务路径说明（必要时附图）

## 9. 依赖图谱
- 内部/外部依赖、版本与许可证摘要

## 10. 维护建议
- 运维、监控、告警、容量、成本要点

## 11. 术语表和缩写
- 术语：定义
- 缩写：全称

## 12. 变更日志
- 参见 `CHANGELOG.md`（与本节建立双向链接）

CHANGELOG.md 标准模板（Keep a Changelog + SemVer）

# 变更日志（Changelog）
所有重要变更均记录于此文件。

本文件格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，并遵循 [语义化版本号](https://semver.org/lang/zh-CN/) 规范。

## [Unreleased]

## [1.0.0] - 2025-01-01
### Added（新增）
- 首次发布。

### Changed（变更）
-

### Deprecated（弃用）
-

### Removed（移除）
-

### Fixed（修复）
-

### Security（安全）
-

<!-- 比对链接（将 <REPO_URL> 替换为实际仓库地址） -->
[Unreleased]: <REPO_URL>/compare/v1.0.0...HEAD
[1.0.0]: <REPO_URL>/releases/tag/v1.0.0

<!-- 归类指引（Conventional Commits → Changelog 分区）
feat: Added（新增）
fix: Fixed（修复）
perf / refactor / style / chore / docs / test: Changed（变更）或按需归类
deprecate: Deprecated（弃用）
remove / breaking: Removed（移除）并标注 BREAKING
security: Security（安全）
-->