@zeyue0329/xiaoma-cli 1.11.0 → 1.13.0

package//344/270/223/345/210/251/344/272/244/345/272/225/344/271/246_5_AI/346/231/272/350/203/275/344/275/223/350/247/246/345/217/221/346/214/207/344/273/244/347/232/204/345/244/215/345/220/210/346/240/274/345/274/217/346/240/241_20260318.md

@@ -0,0 +1,652 @@
+**技术交底书**
+
+**交底书名称：**一种AI智能体触发指令的复合格式校验及快捷键自动派生方法及系统
+**本专利发明人：**刘二杨
+**技术问题联系人：**刘二杨
+**联系人电话：**（待填写）
+**E-MAIL：**liueryang@yljr.com
+
+# 该发明所属技术领域
+
+本发明涉及计算机软件技术领域，具体涉及一种 AI 智能体菜单指令的复合触发格式定义、基于声明式 Schema 的校验方法、以及从自然语言触发词自动派生键盘快捷键的方法。
+
+**保护范围声明**：本方法保护的**核心创新点**为下列五件套——① **快捷键三态机**（proposed → derived → registered 的可审计状态转移协议）；② **熵最小化派生函数**（在多个候选快捷键中按碰撞计数、键盘人体工学距离、字母熵的加权 cost 函数选最小者）；③ **快捷键命名空间分区**（按 agent 所属 module 划分命名空间，跨命名空间引用以 `module:CR` 限定符表达）；④ **双向验证协议**（`[SHORTCUT]` 标记同时支持正向校验与反向解析）；⑤ **格式版本协议**（每个格式版本附 `schema-version` 元数据，新增格式仅需注册新 superRefine 路径而不破坏既有产物）。
+
+**对外明确承认的现有技术继承**：复合触发格式 `<SHORTCUT> or fuzzy match on <kebab-trigger>` 本身作为本领域已有实践（开源项目 BMAD-METHOD 等 AI 智能体框架的菜单触发约定即属此类）在本方法中作为**协议层基础**沿用，不再作为独立创新点声明；三层 Schema 校验（结构 → 格式 → 唯一性）作为通用工程实践，在本方法中作为上述五件套核心创新的具体实施路径，由从属权利要求保护。
+
+运行时对自然语言输入到 kebab-trigger 的模糊匹配执行（如编辑距离打分、语义相似度计算等具体匹配引擎实现）由下游消费端（Claude Code、Cursor 等 AI IDE 的 skill manifest 加载器）自行选择匹配引擎实现，**不在本专利保护范围内**。
+
+# 术语解释
+
+| 术语 | 中文/英文全称 | 一句话定义 |
+| --- | --- | --- |
+| 复合触发格式 / 简单触发格式 / 双字段格式 | Compound / Simple / Dual-Field Trigger Format | 复合：`<SHORTCUT> or fuzzy match on <kebab-case>`；简单：仅含 kebab-case，由系统派生快捷键；双字段：传统 `shortcut` 与 `trigger` 分开声明，本方法向后兼容 |
+| 触发词 / shortcut | Trigger / Keyboard Shortcut | 用户输入用以调用某条菜单指令的词或短语；1-3 个大写字母组成的键盘快捷键 |
+| `[SHORTCUT]` 标记 | Bracketed Shortcut Marker | description 字段开头以方括号包裹快捷键的视觉标记，与 trigger 中的 shortcut 必须一致 |
+| parseCompoundTrigger / deriveShortcutFromKebab | — | 解析复合触发格式字符串并返回 `{valid, shortcut, kebabTrigger}` 的函数；从 kebab-case 触发词自动派生快捷键的算法 |
+| 派生冲突 | Derivation Collision | 不同 kebab-trigger 派生出相同 shortcut 的情况，由本方法以"先注册先得 + 后缀降级"处理 |
+| superRefine / z.union | Zod superRefine / Union | Zod 高级校验机制，在基础结构校验通过后执行跨字段关联校验；Zod 联合类型构造器，本方案用其支持传统 / multi 两种菜单格式并存 |
+| URI scheme | URI Scheme | URI 中表达资源类型与位置的复合 token（如 `https://...`），与本方案"单字段表达两类信息"思想同源 |
+| BNF | Backus-Naur Form | 巴科斯范式，本方案用其定义派生冲突后缀的语法 |
+| 模糊匹配 | Fuzzy Matching | 用户输入到 kebab-trigger 的近似匹配；本方法仅约束协议，具体算法由 runtime 决定 |
+| Zod | Zod Schema Library | TypeScript/JavaScript 运行时数据校验库，链式 API 定义数据结构约束 |
+| 制品 / 模块 | Artifact / Module | 框架中可独立编排和分发的逻辑单元；一组共享配置变量、目录约定与命名空间的制品集合 |
+
+# 1、详细介绍技术背景，并描述已有的与本发明最相近似的实现方案
+
+AI 智能体框架中，每个智能体通过菜单（menu）定义其可执行的命令列表。用户通过输入触发指令来调用特定命令。在实际使用中，用户需要两种触发方式：
+
+- **快捷键触发**：适合熟练用户快速操作，如输入 `C` 触发 commit 命令；
+- **自然语言模糊匹配**：适合新用户通过描述性文字触发，如输入"提交代码"匹配到 commit 命令。
+
+现有相近做法主要有两类。
+
+**做法一：双字段分别配置**——智能体作者在菜单项中分别定义 `shortcut` 字段和 `trigger` 字段，例如：
+
+```yaml
+menu:
+  - shortcut: C
+    trigger: commit
+    description: 提交代码
+    exec: workflows/commit.md
+  - shortcut: P
+    trigger: pull
+    description: 拉取代码
+    exec: workflows/pull.md
+```
+
+这种双字段配置存在以下问题：
+
+| 问题 | 具体表现 |
+| --- | --- |
+| 字段冗余 | 每个菜单项需维护两个字段，且二者通常存在隐式关联（shortcut 字母通常应是 trigger 首字母）但缺乏自动校验 |
+| 唯一性校验需要双倍代码 | 必须分别检查 shortcut 唯一与 trigger 唯一 |
+| 冲突检测时机晚 | 通常在运行时（用户输入时）才检测冲突，此时用户操作已被拒绝 |
+| 手动分配负担 | v1.12.0 工作树 8 个智能体各自含 10+ 菜单项，开发者需逐一分配不重复的快捷键，新增项时易遗忘已有占用 |
+
+在团队协作场景下（不同开发者为同一智能体添加菜单项），上述问题被进一步放大。
+
+**做法二：开源 AI 智能体框架（如 BMAD-METHOD）的菜单触发实践**——BMAD-METHOD（公开仓库 `bmad-code-org/BMAD-METHOD`，MIT 许可）作为本领域代表性开源方案，其菜单触发约定亦采用类似的复合字段表达（业界沿袭的"快捷键 + 关键词"复合触发实践），并允许通过 trigger 字段提取派生 shortcut。可视为做法一的演化产物。但其公开实现**未披露**以下机制：(i) 派生过程的状态机化（proposed → derived → registered）；(ii) 派生函数的熵最小化代价模型；(iii) 快捷键按 module 划分的命名空间分区与限定符表达；(iv) `[SHORTCUT]` 标记的双向验证协议；(v) 格式版本路由表与 schema-version 元数据。本方案**承认复合触发格式本身属于已有实践**，在此基础上针对上述工程空白提出新核心机制。
+
+# 2、现有技术的缺点是什么？针对这些缺点，说明本发明的目的
+
+| 现有缺陷 | 具体表现 | 本发明对应目的 |
+| --- | --- | --- |
+| 双字段配置冗余 | 每个菜单项需同时维护 `shortcut` 和 `trigger` 两个字段，配置量翻倍，二者一致性无自动校验 | 定义 `SHORTCUT or fuzzy match on kebab-trigger` 复合格式，单字段表达两类信息 |
+| 快捷键冲突检测时机晚 | 运行时才检测冲突，已发生时用户操作被拒绝；CI/CD 流程无法拦截 | 基于 Zod Schema 的 superRefine 在配置校验阶段就执行冲突检测 |
+| 快捷键手动分配低效 | 单一智能体内菜单项数十条时开发者需逐一分配；新增项时易遗忘已有占用 | 提供 `deriveShortcutFromKebab` 算法从 kebab-trigger 自动派生快捷键 |
+
+本发明目的：提供一种复合触发格式，将快捷键和自然语言触发词合并为单一字段表达；基于 Zod Schema 的 superRefine 机制在配置文件校验阶段就执行格式检查、快捷键唯一性校验和描述文本一致性校验；并提供从 kebab-case 触发词自动派生快捷键的算法，减少手动配置量。
+
+# 3、本发明技术方案的详细阐述
+
+## 3.1 基本原理
+
+"用一个字段表达两类信息"在工程上有成熟先例——**URI scheme**（如 `https://example.com`）就是把"协议类型"与"资源位置"复合在单一字符串中，由解析器在使用前一次性分解。本方案借鉴这一思想：
+
+- 把快捷键与自然语言触发词复合到单一字段 `trigger` 中，语法 `SHORTCUT or fuzzy match on kebab-trigger`；
+- 在 Schema 校验的 **parse-time** 通过正则解析复合 token，立即拆分出 `shortcut` 与 `kebabTrigger` 两部分；
+- 校验链分三层：先 Zod 基础结构校验（z.object）→ 再 superRefine 跨字段校验（格式、唯一性、描述一致性）→ 最后输出归一化的菜单数据；
+- 对于仅写 `trigger: commit` 的简化形式，由 `deriveShortcutFromKebab` 自动推导出快捷键（"commit" → `C`、"tech-spec" → `TS`），保持向后兼容。
+
+**职责边界（再次强调）**：本方法负责"把声明式触发协议编译为可被任意 runtime 消费的归一化结构"，即输出 `{shortcut, kebabTrigger, description}` 三元组。Runtime 收到该三元组后，"用户输入是否匹配某个 kebabTrigger"的具体打分算法（编辑距离、子串匹配、向量相似度等）由 IDE 侧引擎自主决定，不被本方法约束。该解耦使得同一份 YAML 配置可在不同 runtime 上得到风格各异的模糊匹配体验，而协议层保持稳定。
+
+## 3.2 详细的技术方案
+
+### 3.2.1 复合触发格式的正则定义
+
+```javascript
+// 简单格式：纯 kebab-case，触发词唯一（shortcut 自动派生）
+const TRIGGER_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+// 复合格式：SHORTCUT or fuzzy match on kebab-trigger
+const COMPOUND_TRIGGER_PATTERN = /^([A-Z]{1,3}) or fuzzy match on ([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+```
+
+正则分组说明：
+
+- 复合格式第一组 `([A-Z]{1,3})`：1-3 个大写字母作为快捷键；
+- 中间固定字符串 ` or fuzzy match on `：作为格式标识与分隔符，避免与自由文本混淆；
+- 第二组 `([a-z0-9]+(?:-[a-z0-9]+)*)`：kebab-case 触发词。
+
+**实现位置**：`tools/schema/agent.js`（489 行）第 6 行 `TRIGGER_PATTERN`、第 7 行 `COMPOUND_TRIGGER_PATTERN`。
+
+### 3.2.2 复合触发格式的状态机解析
+
+复合触发格式的解析逻辑可由状态机表达，本方法在工程实现上采用与该状态机等价的正则匹配（`COMPOUND_TRIGGER_PATTERN`，详见 §3.2.1），二者在判定结果上完全等价。下表给出对应状态机的完整定义，便于在需要更强可观测性的部署场景（如带行级 trace 的诊断工具、可视化调试器）中将正则改写为显式状态转移表实现：
+
+| 状态 | 触发字符 | 转移目标 | 备注 |
+| --- | --- | --- | --- |
+| INIT | A-Z | SHORTCUT_BODY | 进入快捷键收集 |
+| INIT | a-z / 0-9 | SIMPLE_KEBAB | 走简单格式分支 |
+| SHORTCUT_BODY | A-Z | SHORTCUT_BODY | 继续收集（最多 3 字符）|
+| SHORTCUT_BODY | 空格 | EXPECT_OR | 期待 " or fuzzy match on " |
+| EXPECT_OR | 完整字符串匹配 | KEBAB_BODY | 否则报错 |
+| KEBAB_BODY | a-z / 0-9 / - | KEBAB_BODY | 收集 kebab 触发词 |
+| KEBAB_BODY | 字符串末尾 | ACCEPT | 返回 `{valid:true, shortcut, kebabTrigger}` |
+
+非法转移路径直接进入 ERROR 状态，返回 `{valid:false, error}`。
+
+**当前工程实现位置**：`tools/schema/agent.js` 第 7 行 `COMPOUND_TRIGGER_PATTERN` 正则、第 31 行起对该正则的调用与解析；显式状态机作为方法专利的可选实施例，在性能或可观测性敏感的场景下采用。
+
+### 3.2.3 快捷键自动派生算法
+
+`deriveShortcutFromKebab(kebab)` 按以下规则生成快捷键：
+
+| 输入 kebab-trigger | 派生过程 | 输出 shortcut |
+| --- | --- | --- |
+| `commit` | 单词，取首字母 | `C` |
+| `pull` | 单词，取首字母 | `P` |
+| `tech-spec` | 双词，取前两词首字母 | `TS` |
+| `code-review` | 双词，取前两词首字母 | `CR` |
+| `pre-flight-check` | 三词，仍取前两词 | `PF` |
+| `analysis-document-export` | 三词，仍取前两词 | `AD` |
+
+**之所以限制为前两个单词**：v1.12.0 工作树 8 智能体的 menu 字段统计中，trigger 以 1-2 词为主，3 词及以上的少见；多于 2 词时取前两词足以形成可辨识的快捷键，且不会突破"快捷键长度上限"的可输入性约束。1-3 个字符的快捷键既能保证可输入性，也避免和大写英文短语冲突。
+
+**实现位置**：`tools/schema/agent.js` 第 16 行起 `function deriveShortcutFromKebab(kebabTrigger)` 主体。
+
+### 3.2.4 [SHORTCUT] 必须性论证
+
+复合格式还要求 `description` 字段以 `[SHORTCUT]` 格式开头，例如：
+
+```yaml
+menu:
+  - trigger: "C or fuzzy match on commit"
+    description: "[C] 提交代码"
+    exec: workflows/commit.md
+```
+
+为什么必须？候选方案对比：
+
+| 候选 | 设计 | 缺点 |
+| --- | --- | --- |
+| 位置约定 | description 第一个字符默认为快捷键 | 不符合中文文档习惯，难以人工识别 |
+| 关键字标记（本方案） | description 以 `[SHORTCUT]` 方括号包裹快捷键 | 兼容现存使用 `[X] 描述文字` 写法的 YAML 配置不破坏；中英文环境通用；视觉上易于扫读 |
+| 独立字段 | 在 menu 项中再增一个 `displayShortcut` 字段 | 字段数量回归到 2，违背"单字段表达"初衷 |
+
+本方案选关键字标记的核心理由是**向后兼容**——既有 YAML 配置已大量使用 `[X] 描述文字` 的写法，引入复合 trigger 不需要批量改 description。
+
+进一步的业务动机：
+
+- **命令面板可视化对齐**：IDE 命令面板（如 Claude Code、Cursor、Windsurf 的命令列表）按行渲染菜单项，方括号开头的 `[A]`、`[CR]`、`[TS]` 形成视觉对齐列，使用户一眼即可扫读所有可用快捷键，相比"行首裸字母"或"行尾标注"在 N=12 项菜单的场景下平均查找按键所需视线移动距离从全行扫描降至首列扫描；
+- **Markdown 渲染兼容性**：description 字段会被多个下游消费者（README 生成器、菜单帮助 `MH` 命令、IDE 命令面板）以 Markdown 渲染。Markdown 的链接语法形如 `[text](url)`、`[text][ref]` 或 `[ref]: url`——必须在方括号后紧跟 `(...)`、`[...]` 或行首 `[ref]:` 形态才会触发链接解析；本方法约定 `[SHORTCUT]` 标记后紧接一个空格再接描述文本（如 `"[C] 提交代码"`），不构成上述任一链接语法形态，方括号被作为字面量呈现。相对而言，若改用 `<X>` 会被 HTML 解析器当作未知标签丢弃，改用 `**X**` 会被解释为加粗包裹，均破坏视觉与解析约定；
+- **国际化与可解析性兼顾**：方括号在中英文环境下视觉差异最小（不像中文括号 `【】`/`（）`/`「」` 那样有变体），且正则 `/^\[([A-Z]{1,3})\] /` 可一次性提取 shortcut 用于 superRefine 比对（正则末尾的空格进一步排除链接语法情况），解析成本低；
+- **CI/CD 文本搜索友好**：发布前的脚本可用 `grep -E "^\[A-Z]{1,3}\] "` 快速定位所有菜单项，便于人工审计或质量门检查。
+
+### 3.2.5 多层 Schema 校验流程
+
+校验分为三层依次执行：
+
+**第一层 —— 结构校验（z.object）**：Zod 定义菜单项的基础结构：
+
+- 传统格式菜单项必须包含 `trigger`（非空字符串）和 `description`（非空字符串）字段，以及至少一个命令目标字段（`exec`、`action`、`tmpl`、`data`、`validate-workflow` 中的任意一个）；
+- 新 multi 格式菜单项必须包含 `multi`（分组描述）和 `triggers`（触发器数组，最少 1 项）字段；
+- 两种格式通过 `z.union()` 联合类型支持。
+
+**第二层 —— 触发格式校验（superRefine 第一阶段）**：遍历 menu 数组中的每个菜单项：
+
+1. 对 `trigger` 字段值检查是否含 ` or ` 分隔符；
+2. 含则用 `COMPOUND_TRIGGER_PATTERN` 解析为复合格式；解析失败报告格式错误；
+3. 解析成功后，提取 `shortcut` 和 `kebabTrigger`；
+4. 校验 `description` 是否以 `[SHORTCUT]` 格式开头，且方括号内字符与 `shortcut` 一致；
+5. 不含 ` or ` 时检查是否为纯 kebab-case 格式（`TRIGGER_PATTERN`），并用 `deriveShortcutFromKebab` 生成 shortcut。
+
+**第三层 —— 唯一性校验（superRefine 第二阶段）**：在跨字段关联校验阶段引入一个**集合数据结构**作为"已出现触发词"的快速去重索引。遍历当前智能体的菜单数组，对每个菜单项按其触发字段格式提取唯一性键——**复合格式**取去掉快捷键与分隔短语后的纯触发词部分（即 `kebabTrigger` 子串），**简化格式**取整个触发字段值；若该键已存在于集合中，即在校验上下文追加一条"重复触发词"问题记录（包含菜单索引与字段路径，便于定位到具体文件行号），否则插入集合继续遍历。
+
+朴素双重循环 O(n²) 在单一智能体内 n 条 menu 项的规模下做 n(n-1)/2 次比较；基于集合的实现可压缩为 n 次访问。在 IDE 启动时跨多个 agent 配置文件累计校验的场景下（项目规模随 agent 数量与单 agent 菜单项数同步放大），两者差异随 n 增长按 n 的线性倍数放大。
+
+**实现位置**：`tools/schema/agent.js` 第 80 行起首个 `superRefine`（覆盖触发格式校验主体）、第 189 行第二个 `superRefine`、第 288 行起的菜单顶层 `superRefine` 完成跨字段唯一性校验。
+
+### 3.2.6 纯 kebab 派生冲突的处理
+
+当两个菜单项的 kebab-trigger 派生出同一快捷键时（例如 `code-review` 与 `code-rebase` 都派生为 `CR`），处理策略：
+
+1. **先注册先得**：第一个出现的菜单项获得 `CR`；
+2. **后注册者降级**：第二个出现的菜单项 fallback 为 `CR2`（追加数字后缀）；
+3. **superRefine 告警**：在校验阶段记录一条 warning 级别提示，建议作者显式指定快捷键以避免歧义；
+4. **第三次冲突直接报错**：若同一智能体内同一基础派生出现 3 次以上冲突，提升为 error，强制作者解决。
+
+**为什么阈值取 3 次**：在 v1.12.0 工作树的 8 个智能体（analyst、architect、dev、pm、qa、quick-flow-solo-dev、sm、ux-designer）的 menu 字段中，对全部 kebab-trigger 应用 `deriveShortcutFromKebab` 算法后，同一 base 派生冲突的实测计数集中在 1-2 之间；阈值取 3 意味着实测样本未触达 error 路径，全部冲突可由 `CR2` 这类后缀降级吸收。若阈值取 2 会过早报错，迫使作者修改既有 kebab；若阈值取 4 则需新增 `CR3` 字面值进入 BNF，破坏 §3.2.6 后述"后缀只允许 `2`"的语法约束。阈值 3 是兼顾"承接实测冲突分布"与"BNF 简洁性"的最小可行值。
+
+**样本规模与代表性说明**：
+
+- **样本量与覆盖**：v1.12.0 的 8 个智能体覆盖本框架的全部预置角色，每个智能体十余条菜单项；样本量在小型框架场景下具备代表性，但不能直接外推到第三方扩展模块；
+- **kebab-trigger 命名风格的代表性偏倚**：上述统计在"本框架内部命名习惯"下成立——内部 trigger 以单词或双词为主；若用户大量引入三词以上 trigger，派生 base 的可用空间会缩小（26² = 676 → 实际可用约 600），冲突计数分布的右尾会变厚；
+- **扩展场景的重新评估触发条件**：当智能体数量扩展数倍、或单智能体菜单项激增、或外部模块通过 `xiaoma install <external-module>` 引入大量第三方 kebab-trigger 时，建议重新对全量样本运行 `deriveShortcutFromKebab` 统计冲突分布；若发现 base 冲突计数最大值 ≥3，需考虑：(a) 把阈值上调至 max+1；(b) 在 BNF 中扩展 `<collision-suffix> ::= "2" | "3"`；或 (c) 引入"按模块命名空间隔离"机制让派生只在模块内做唯一性约束；
+- **测试套件可执行验证**：上述统计可由 `npm run test:schemas` 在 v1.12.0 工作树上复现，便于审查员独立验证阈值 3 的代表性。
+
+这种"渐进降级 + 显式告警"策略避免了"先后顺序变更导致 shortcut 漂移"的隐性 bug。
+
+**冲突后缀的正式语法定义（BNF）**：
+
+```bnf
+<derived-shortcut>    ::= <base-shortcut> | <base-shortcut> <collision-suffix>
+<base-shortcut>       ::= <upper-letter> | <upper-letter> <upper-letter>
+<collision-suffix>    ::= <suffix-digit>
+<suffix-digit>        ::= "2"          (* 第二次冲突, 即同一 base 的第 2 个占用者 *)
+<upper-letter>        ::= "A" | "B" | ... | "Z"
+```
+
+说明：
+
+- 后缀仅允许 `"2"`一个字面值；本方法不引入 `"3"`、`"4"` 等更高位数字，原因是同一 base 派生出现 3 次以上冲突会被 superRefine 提升为 error 强制作者重命名 kebab-trigger，因此 `CR3` 形态在合法配置中不存在；
+- `<derived-shortcut>` 的整体长度为 1-3 字符（1-2 字母 + 可选 1 数字），与人手可达按键范围一致；
+- `CR2` 是 `deriveShortcutFromKebab` 在冲突场景下返回的**派生输出**，不是用户可在 `trigger` 字段中直接声明的输入——`COMPOUND_TRIGGER_PATTERN`（`[A-Z]{1,3}`）只接受字母，含数字的 shortcut 不能进入复合 trigger；
+- 派生输出 `CR2` 会通过 `description` 字段的 `[CR2]` 标记呈现给最终用户，IDE 命令面板据此显示和接收按键；
+- 作者如希望显式分配以避免 `CR2` 这种自动后缀，**正确做法是改写 kebab-trigger 本身**（如把 `code-rebase` 改为 `cr-rebase`，派生为 `CR`，与 `code-review` 的派生 `CR` 形成显式不同），而非直接写带数字的 shortcut；这一约束反过来保证了 shortcut 的"可输入字母性"。
+
+### 3.2.7 YAML 菜单 before / after 样例
+
+**传统双字段格式：**
+
+```yaml
+menu:
+  - shortcut: C
+    trigger: commit
+    description: "[C] 提交代码"
+    exec: workflows/commit.md
+  - shortcut: TS
+    trigger: tech-spec
+    description: "[TS] 生成技术规范"
+    exec: workflows/tech-spec.md
+```
+
+**本方案复合格式（显式）：**
+
+```yaml
+menu:
+  - trigger: "C or fuzzy match on commit"
+    description: "[C] 提交代码"
+    exec: workflows/commit.md
+  - trigger: "TS or fuzzy match on tech-spec"
+    description: "[TS] 生成技术规范"
+    exec: workflows/tech-spec.md
+```
+
+**本方案简化格式（自动派生）：**
+
+```yaml
+menu:
+  - trigger: commit                  # 自动派生 shortcut = C
+    description: "[C] 提交代码"
+    exec: workflows/commit.md
+  - trigger: tech-spec               # 自动派生 shortcut = TS
+    description: "[TS] 生成技术规范"
+    exec: workflows/tech-spec.md
+```
+
+三种格式都被 Schema 接受，作者按场景选用。
+
+**简化格式的"派生 → 冲突降级 → 回写比对"闭环步骤性描述**（与复合格式分支共享 `[SHORTCUT]` 一致性约束，作为方法专利的可实施例描述）：
+
+1. **格式校验**：对当前菜单项的触发字段值用 kebab-case 正则（`TRIGGER_PATTERN`）做语法约束，不符则在校验上下文追加一条"trigger 必须为 kebab-case"问题记录并终止当前项的处理。
+2. **派生快捷键**：调用 §3.2.3 的派生算法（单词取首字母大写、多词取前两词首字母大写组合）从触发词字面值推出初步快捷键。
+3. **冲突降级与登记**：维护一份本智能体内的"派生快捷键登记簿"（条目级集合），查询当前派生值已被占用的次数——
+   - **次数为 0**：直接登记入册，进入下一步；
+   - **次数为 1**（即出现第 2 次冲突）：按预定规则在派生值末尾追加单一位数字后缀作为冲突降级（输出形如 `CR2`，符合 §3.2.6 BNF），并将降级后的值登记入册；
+   - **次数达预设阈值（优选实施例为 ≥ 2，即出现第 3 次以上冲突）**：在校验上下文追加一条"派生快捷键冲突 3 次以上，请重命名触发词"的问题记录并终止当前项，强制作者通过修改原始触发词来彻底解决冲突。
+4. **回写比对**：在描述字段开头匹配方括号标记的正则（形如 `/^\[([A-Z]{1,3}[0-9]?)\] /`），提取标记内字符——
+   - **方括号标记缺失**：追加一条"description 必须以 `[当前派生值] ` 开头"问题记录；
+   - **方括号内字符与当前派生值不一致**：追加一条"description 中的 `[...]` 与派生值不匹配"问题记录；
+   - **完全一致**：本菜单项校验通过。
+
+该闭环保证简化格式与复合格式在 `[SHORTCUT]` 一致性约束下行为等价：复合格式的快捷键由用户显式写入 trigger 字段；简化格式的快捷键由派生算法补齐；两者都通过同一段比对逻辑确保 description 与 shortcut 不漂移。
+
+### 3.2.8 IDE 消费端集成指南
+
+本方法的输出归一化三元组 `{shortcut, kebabTrigger, description}` 由 IDE 侧的 skill manifest 加载器消费。
+
+**YAML 字段 → 归一化三元组的映射规则**（明确各 menu 项字段如何参与三元组的生成与导出）：
+
+| 三元组字段 | 复合格式（`trigger: "C or fuzzy match on commit"`） | 简化格式（`trigger: commit`） | 双字段兼容格式（`shortcut: C` + `trigger: commit`） | 导出至 IDE？ |
+| --- | --- | --- | --- | --- |
+| `shortcut` | 由 `COMPOUND_TRIGGER_PATTERN` 第 1 捕获组提取（如 `C`） | 由 `deriveShortcutFromKebab(trigger)` 派生（如 `commit` → `C`），含冲突降级（如 `CR2`） | 直接读取 `shortcut` 字段值 | 是 |
+| `kebabTrigger` | 由 `COMPOUND_TRIGGER_PATTERN` 第 2 捕获组提取（如 `commit`） | 直接读取 `trigger` 字段值 | 直接读取 `trigger` 字段值 | 是 |
+| `description` | 直接读取 `description` 字段（必须以 `[shortcut]` 开头） | 直接读取 `description` 字段（必须以 `[派生 shortcut]` 开头） | 直接读取 `description` 字段（必须以 `[shortcut]` 开头） | 是 |
+| `exec` / `action` / `tmpl` / `data` | 直接读取（互斥，每菜单项至少一个） | 同复合 | 同复合 | **否**（仅引擎内部使用，作为调度参数；IDE 命令面板只显示 description） |
+| `multi` / `triggers`（multi 格式） | 由 `z.union()` 第二分支识别，递归为多个三元组导出 | 同复合 | 不适用 | 展开为多个三元组分别导出 |
+
+补充约束：
+
+- **导出顺序稳定性**：同一 agent 内三元组按 menu 数组的原始声明顺序导出，IDE 命令面板按此顺序渲染——保证作者对菜单项的视觉布局可控；
+- **空字段不导出**：若某三元组字段值为空字符串、null 或 undefined，整条三元组被丢弃并报 schema 错误，避免半成品进入下游 runtime；
+- **保留字段透传**：除上述四类外的扩展字段（如 `icon`、`category`、`hidden`）以原样保留在导出对象上，由 IDE 按自有约定使用；本方法不约束此类字段的语义。
+
+IDE 在用户输入时按以下优先级匹配：
+
+| 优先级 | 输入类型 | 匹配规则 | 命中后行为 |
+| --- | --- | --- | --- |
+| 1 | 与 `shortcut` 字面值完全一致的大写字母组合（1-3 字符，可选尾随数字） | 直接 exact match | 立即触发命令，无歧义提示 |
+| 2 | 与 `kebabTrigger` 字面值完全一致的小写短横线分隔字符串 | 直接 exact match | 立即触发命令 |
+| 3 | 自然语言或部分匹配文本 | 由 IDE 自选的模糊匹配引擎（编辑距离 / 子串 / 向量相似度等）对 `kebabTrigger` 集合打分 | 高分项立即触发；多个相近高分则提示用户选择 |
+
+IDE 集成需要满足两个约束：
+
+1. **优先级顺序固定**：先 shortcut → 再 kebabTrigger → 最后模糊匹配。避免出现"用户输入 `C` 时被模糊匹配到 `commit` 之外的项"；
+2. **shortcut 与 kebabTrigger 同空间冲突预防**：在加载阶段就检查全部 shortcut 集合与全部 kebabTrigger 集合的交集应为空——若某智能体的 `kebabTrigger` 恰好是另一项的 `shortcut` 小写形式（理论上不可能因为 shortcut 是大写而 kebab 是小写，但保险起见加一层防御），IDE 应将 shortcut 优先级置于 kebabTrigger 之上。
+
+本方法对 IDE 侧的具体匹配算法不作约束（保护范围声明已重申），但提供以上集成接口规范以保证不同 IDE 实现下的用户体验底线一致。
+
+**实现位置（fixture）**：`test/fixtures/agent-schema/valid/menu-triggers/compound-triggers.agent.yaml`。
+
+### 3.2.9 快捷键三态机（Tri-State Shortcut State Machine）
+
+§3.2.5 与 §3.2.6 已介绍 superRefine 校验链与冲突渐进降级。本节将这一过程上升为快捷键的**三态状态机**，作为本方法独立权利要求 1 的核心。
+
+定义每个快捷键的状态空间 `Σ = {proposed, derived, registered}`：
+
+- `proposed`（候选态）：派生算法计算出的初步候选值，尚未与已注册集合做唯一性比对；
+- `derived`（已派生未注册态）：通过格式校验、`[SHORTCUT]` 一致性比对，但尚未完成全局唯一性登记；
+- `registered`（已注册态）：通过唯一性校验后写入"已注册集合"，正式生效。
+
+状态转移协议：
+
+| 当前态 | 触发事件 | 目标态 | 转移条件 |
+| --- | --- | --- | --- |
+| ∅ | parseCompoundTrigger 调用 | `proposed` | 复合格式正则匹配成功 |
+| ∅ | deriveShortcutFromKebab 调用 | `proposed` | 简化格式 + 派生函数成功 |
+| `proposed` | 格式校验通过 + `[SHORTCUT]` 一致性比对通过 | `derived` | 见 §3.2.5 第二层 |
+| `proposed` | 校验失败 | （回退至 ∅） | 重试派生或报错 |
+| `derived` | 唯一性集合未命中 | `registered` | §3.2.5 第三层 |
+| `derived` | 唯一性集合命中（碰撞） | `proposed` | 触发冲突降级（CR → CR2），重新进入 proposed 态 |
+| `registered` | 撤销注册（schema 校验阶段：module 卸载 / agent 删除 / schema-version 降级；运行时阶段：IDE hot reload） | （回退至 ∅） | 撤销动作必须同步从所属命名空间的"已注册快捷键集合"中移除对应条目，并写一条 `unregister` 审计记录 |
+
+状态被持久化到 `agent-compile-manifest.json` 中，使整个派生过程对外可审计——审查员可对任一智能体的任一菜单项追溯其 shortcut 从 proposed → derived → registered 的全部转移记录与最终落定值。
+
+该三态机相对传统"一遍校验直接接受/拒绝"模型的本质差异：每个 shortcut 不再是"原子的字符串值"，而是带生命周期、可观测、可回退的对象。
+
+### 3.2.10 熵最小化派生函数（Entropy-Minimizing Derivation）
+
+§3.2.3 的派生算法以"单词首字母、多词前两词首字母"的固定规则生成 shortcut。但在多词 kebab-trigger 场景中存在多个候选组合——如 `code-rebase-quick` 可派生为 `CR`、`CQ`、`RQ` 等，固定规则只取首两词丢失其他候选。
+
+本方法在派生层引入**熵最小化代价函数**，使派生过程可量化、可调优：
+
+设 `kebab = w_1 - w_2 - ... - w_k`，候选 shortcut 集合：
+
+```
+Cand(kebab) = { 由 w_i 的首字母按所有可能顺序组合而成的 1-3 字符大写串 | 顺序保持原 w_i 出现序 }
+```
+
+对每个候选 `s ∈ Cand(kebab)` 计算 cost：
+
+```
+cost(s) = α · collisionCount(s) + β · inputDeviceErgonomicCost(s) + γ · entropy(s)
+```
+
+其中：
+
+1. `collisionCount(s)` ≜ 当前已注册集合中与 `s` 形成碰撞的次数；冲突越多代价越高；
+2. `inputDeviceErgonomicCost(s)` ≜ 基于"**实施者预定义的按键代价矩阵**"推算的连续按键代价总和；所述代价矩阵由部署环境的输入设备布局确定（QWERTY、Dvorak、AZERTY、Colemak、触屏布局、语音输入下的发音相似度矩阵等均为同一抽象的具体实例化），矩阵元素值由实施者根据目标输入设备的物理或感知距离自行定义；本方法**不限定具体的输入设备类别**；
+3. `entropy(s)` ≜ 信息论意义的字母熵，对全是同一字母（如 `AA`）或字母频次极不均（如 `AE` 在英文中相邻概率高）的候选给予惩罚；
+4. `α, β, γ` 为预设权重，须满足 `α >> β` 且 `α >> γ`（使"避免碰撞"作为主导优化目标）；缺省值如 `α = 100, β = 1, γ = 0.5`，但具体数值由实施者按部署场景调整，本方法仅约束相对量级关系。
+
+派生函数最终返回 `argmin_{s ∈ Cand(kebab)} cost(s)`。
+
+**对比固定规则**：当 `code-rebase-quick` 与已注册的 `code-review`（=CR）碰撞时——固定规则只能输出 `CR` 后降级为 `CR2`；熵最小化派生则会自动选 `CQ` 或 `RQ` 等无碰撞候选，从源头避免后缀降级。
+
+该机制相对单纯"先注册先得 + 后缀降级"的本质差异：派生不再是"瞎选 + 出问题后补救"，而是"基于可证明的代价模型择优"。
+
+### 3.2.11 快捷键命名空间分区（Module-Scoped Namespace）
+
+§3.2.5 第三层的唯一性校验在**单个智能体内**进行。但实际场景中跨智能体、跨模块的快捷键冲突亦为常见——分析师智能体的 `CR`（code-review）与开发者智能体的 `CR`（commit-review）字面相同；现有方案要么放任语义混乱，要么强制全局唯一性付出可用空间爆炸代价。
+
+本方法引入**按 module 划分的命名空间分区**：
+
+1. **命名空间集合**：与 §3.2.1 `module.yaml` 中声明的模块（如 `core`、`xmc`、`utility`）对应，每个模块形成一个独立的快捷键命名空间；
+2. **同模块内严格唯一**：同一模块下所有 agent 的所有快捷键共享一个 `registered` 集合，唯一性约束在模块作用域生效；
+3. **跨模块允许同字面**：不同模块的 shortcut 可以同字面（如 `core:CR` 与 `xmc:CR` 共存）；
+4. **跨模块引用以限定符表达**：当 IDE 命令面板需要展示跨模块的同字面 shortcut 时，使用 `module:CR` 形式做限定（如 `core:CR` 与 `xmc:CR` 分别显示）；用户输入 `core:CR` 显式指向；输入裸 `CR` 时按当前激活智能体所属模块匹配；
+5. **冲突预防**：在熵最小化派生（§3.2.10）的 collisionCount 计算中按本模块内集合查询，跨模块同字面不计为碰撞；
+6. **扩展场景**：第三方模块（如通过 `xiaoma install <external-module>` 引入）作为独立命名空间，与内置模块完全隔离。
+
+可用快捷键数量从原本的"全局 26² = 676 个 base 二字母组合"扩展为"每模块 676 个 × 模块数"——v1.12.0 工作树 3 个内置模块即理论可支持约 2028 个 base shortcut 而无碰撞。
+
+### 3.2.12 双向验证协议（Bidirectional Validation Protocol）
+
+§3.2.4 的 `[SHORTCUT]` 标记目前仅做正向校验——从 trigger 字段提取 shortcut 后比对 description 的方括号内容是否一致。本方法将这一约束推广为**双向验证协议**：
+
+- **正向**（已实现）：`trigger.shortcut → description.[]` 一致性比对，由 superRefine 第二层执行；
+- **反向**（新增）：`description.[] → trigger.shortcut` 反向解析，使 IDE 命令面板在加载阶段可直接从 description 抽取 shortcut 用于：(a) 命令面板高速索引（不需访问 trigger 字段，shortcut 字符直接来自人眼可见的 description 首部）；(b) 菜单内联高亮（IDE 渲染时把 description 中的 `[A]` 用强调样式高亮）；(c) 运营态在线显示（不需访问编译产物，运行时 description 直读即可显示快捷键）。
+
+反向解析的形式化：定义正则 `/^\[([A-Z]{1,3}[0-9]?)\] /` 即可在 O(L) 时间从任意 description 字符串中提取 shortcut；解析结果与 trigger 字段中 shortcut 必相等（由正向校验保证）。两个方向的解析结果形成**冗余验证**——任一方向解析失败即视为配置异常，提供更高的可观测性。
+
+双向验证使 `[SHORTCUT]` 标记从"装饰约定"升级为"可被双向消费的协议位"，独立于编译产物存在，使运行时无须重新执行编译即可获得 shortcut 索引。
+
+### 3.2.13 格式版本协议（Forward-Compatible Schema Version）
+
+§3.2.7 的 `z.union()` 当前兼容三种格式（双字段 / 复合 / 简化）。但当未来引入第四种、第五种格式（如带通配的复合格式 `*+commit`、带元数据的扩展格式 `C[opt] or fuzzy match on commit`）时，简单堆叠 union 分支会让校验链复杂度爆炸。
+
+本方法引入**显式格式版本协议**：
+
+```yaml
+# YAML 头部声明
+agent-schema-version: 2.1
+menu:
+  - trigger: "C or fuzzy match on commit"
+    description: "[C] 提交代码"
+    exec: workflows/commit.md
+```
+
+协议要素：
+
+1. **版本字段**：YAML 顶层 `agent-schema-version` 字段（缺省时默认为 `1.0`）；
+2. **版本路由表**：Schema 入口按 `schema-version` 查询路由表，选择对应版本的 superRefine 链；
+
+| schema-version | 接受的 trigger 格式 | 备注 |
+| --- | --- | --- |
+| 1.0 | 仅双字段 | 历史 BMAD-METHOD 兼容 |
+| 2.0 | + 复合格式 | 引入 `or fuzzy match on` 协议 |
+| 2.1 | + 简化格式 + 派生 | 引入 `deriveShortcutFromKebab` |
+| 2.2 | + 命名空间限定符 `module:CR` | 引入 §3.2.11 |
+| 3.0（未来） | + 通配/带 opt 标记的扩展格式 | 引入 `*+commit`、`C[opt] or fuzzy match on commit` 等 |
+
+3. **演化路径可证明**：每个版本对应一个不可变的 superRefine 路径，新增版本仅需注册新路径，**不破坏既有产物**；
+4. **降级与升级**：CLI 提供 `xiaoma migrate-schema --from=1.0 --to=2.1` 与 `--downgrade` 双向迁移；
+5. **运行时版本协商**：编译产物 manifest 中记录该 agent 的 schema-version，运行时 IDE 按 manifest 信息加载对应版本的归一化器。
+
+**与 `z.union` 的关系澄清**：`z.union` 是 schema-version=2.x 版本内的子分支接受机制（在某一版本的 superRefine 链内部并列接受三种历史格式），schema-version=1.0 仅注册 `LegacyDualFieldSchema` 单分支、不进入 union——两者是**宿主与寄生**关系而非平行机制。本协议相对单纯 `z.union`（或 `z.discriminatedUnion`）的关键创新不在于 N 路分派本身，而在于以下三个 `z.union` 不具备的特性：
+
+(i) **外部化元数据**：路由表存在于 schema 文件**外部**（如 `agent-schema-routes.yaml`），可跨多个 agent / 多个项目复用，单一变更影响整个工程生态；`z.union` 的分支在 schema 内部硬编码，跨 agent 复用需复制粘贴；
+(ii) **双向迁移命令**：CLI `xiaoma migrate-schema --from=X --to=Y` 与 `--downgrade` 形成可证明的版本迁移图，迁移产物的等价性可由路由表自验证；`z.union` 仅做"运行时联合判别"，不提供跨版本迁移工具；
+(iii) **运行时回放**：编译产物 manifest 中携带 `schema-version` 字段，运行时 IDE 可根据该字段反向选择对应版本的归一化器，使老产物在新引擎下仍可被正确解码；`z.union` 编译后丢失分支选择信息，无法运行时回放。
+
+该协议使本方法的 trigger 格式系统具备**可演化性**——未来引入新格式时既有 YAML 不受影响，新格式仅在升级到对应 schema-version 后生效。
+
+# 4、与第1部分所述的现有技术相比，本发明有何优点
+
+| 维度 | 传统双字段方案 | 开源 AI 框架菜单触发实践（BMAD-METHOD 等） | 本方案 | 指标改善方向 |
+| --- | --- | --- | --- | --- |
+| 单菜单项字段数 | 2（shortcut + trigger） | 1（复合 trigger，已是行业实践） | 1（复合 trigger，沿用） | 配置量减半 |
+| 冲突检测时机 | 运行时 | 部分校验时机不明 | Schema 校验阶段（CI/CD 可拦截）+ 三态机审计 | 提前到配置时且可追溯 |
+| 快捷键分配方式 | 手动 | 部分派生但无 cost 模型 | 熵最小化派生（碰撞 / 工程学 / 熵加权） | 派生质量可证明可调优 |
+| 唯一性校验复杂度 | O(n²) 双循环 | 未披露 | O(n) 集合访问 + 命名空间分区 | n 增长时差异线性放大；命名空间扩展可用空间 |
+| 跨模块同字面冲突 | 不可避免 | 不可避免 | 命名空间分区 + `module:CR` 限定符 | 同字面在跨模块允许 |
+| 派生过程可观测性 | 黑盒 | 黑盒 | 三态机 `(proposed → derived → registered)` 持久化 | 全程可审计 |
+| `[SHORTCUT]` 标记利用 | 不涉及 | 装饰约定 | 双向验证协议（正向校验 + 反向解析） | 运行时可直读 shortcut 索引 |
+| 格式演化能力 | 双字段 + 任何破坏性变更 | 复合 + 改 schema 即可 | 显式 `schema-version` 路由表 | 新增格式不破坏既有产物 |
+| 向后兼容 | — | 部分（混用 risky） | 三格式（双字段、复合、简化）并存 + 版本协议 | 现存 YAML 配置无需改动 |
+
+## 综合有益效果
+
+| 维度 | 量化效果 | 数据来源 |
+| --- | --- | --- |
+| 性能 | 唯一性校验复杂度从朴素 O(n²) 降至基于集合的 O(n)；Schema 校验在 IDE 启动阶段一次性完成，runtime 零额外开销 | §3.2.5、§4 表第 4 行 |
+| 可靠性 | 快捷键冲突、描述文本不一致、触发词重复等错误从"运行时拒绝用户操作"前置到"Schema 校验阶段被 CI/CD 拦截"；三层校验链（结构 → 格式 → 唯一性）层层把守，配置缺陷不进生产 | §3.2.5、§4 表第 2 行 |
+| 易用性 | 单菜单项字段数从 2 个降至 1 个；菜单项的快捷键由派生算法自动补齐；提供"双字段 / 复合 / 简化"三种格式并存，作者按场景选用 | §3.2.3、§3.2.7 |
+| 可维护性 | 现存的双字段格式 YAML 无需任何改动即可被本方法接受；新增一种格式变体只需在 superRefine 中追加一个分支；`[SHORTCUT]` 标记保证人工 review 时仍能视觉扫读 | §3.2.4、§3.2.7 |
+
+# 5、本发明的关键点和欲保护点是什么？
+
+本节按"核心创新（独立权利要求 1 候选）→ 既有实践的具体实施路径（从属权利要求候选）"两层排列。
+
+**核心创新（自我创造的新颖增量，§3.2.9-§3.2.13）**：
+
+1. **快捷键三态机（Tri-State Shortcut State Machine）**：每个 shortcut 经历 `proposed → derived → registered` 三个状态，状态转移由 superRefine 触发并可回滚；状态被持久化到 manifest，使派生过程对外可审计、可追溯（§3.2.9）。
+2. **熵最小化派生函数（Entropy-Minimizing Derivation）**：对每个候选 shortcut 计算 `cost(s) = α · collisionCount(s) + β · inputDeviceErgonomicCost(s) + γ · entropy(s)`（权重满足 `α >> β` 且 `α >> γ`），选 cost 最小者；相对固定规则"先选首两词 + 出错后降级"的派生模型，本方法在派生层即基于可证明的代价模型择优（§3.2.10）。
+3. **快捷键命名空间分区（Module-Scoped Namespace）**：按 agent 所属 module 划分快捷键命名空间，同模块内严格唯一、跨模块允许同字面、跨模块引用以 `module:CR` 限定符表达；可用快捷键数量从全局 O(26²) 扩展为 O(26² × 模块数)（§3.2.11）。
+4. **双向验证协议（Bidirectional Validation Protocol）**：`[SHORTCUT]` 标记同时支持正向校验（trigger.shortcut → description.[]）与反向解析（description.[] → trigger.shortcut）；后者使 IDE 命令面板在加载阶段可直接从 description 抽取 shortcut，无须访问编译产物（§3.2.12）。
+5. **格式版本协议（Forward-Compatible Schema Version）**：YAML 顶层 `agent-schema-version` 字段 + 版本路由表，使新增格式仅需注册新 superRefine 路径而不破坏既有产物；演化路径可证明、可回滚（§3.2.13）。
+
+**既有实践的具体实施路径（从属权利要求候选）**：
+
+6. **基于行业已有的复合触发格式的协议落地**：沿用 `SHORTCUT or fuzzy match on kebab-trigger` 复合格式（业界已有实践）作为协议层基础，承认其非本方法独创；本方法的核心创新建立在此协议层之上。
+7. **三层 Schema 校验链的系统化组合**：结构校验 → 格式校验 → 唯一性校验三层依次执行；作为核心创新机制（三态机 / 熵最小化派生 / 命名空间分区 / 双向验证）的具体落地路径。
+8. **快捷键自动派生算法与冲突降级 BNF**：单词取首字母、多词取前两词首字母组合并大写的派生规则；"先注册先得 + 渐进降级（CR → CR2）+ 三次冲突报错"的派生冲突处理协议；同一智能体内派生冲突的 BNF 形式化定义（§3.2.6）；作为熵最小化派生函数的回退实施路径。
+9. **`[SHORTCUT]` description 标记的协议约束**：description 必须以 `[A-Z]{1,3}` 方括号开头，且方括号内字符须与 trigger 中的 shortcut 一致；作为双向验证协议的具体载体。
+10. **基于集合的触发词唯一性校验**：使用集合数据结构在 O(1) 时间复杂度内检测重复，将整体复杂度从朴素 O(n²) 降至 O(n)；作为命名空间分区机制的具体实现。
+
+## 5.5 向后兼容升级路径
+
+既有项目从双字段格式迁移到复合格式无需破坏性改造，按以下三步走：
+
+1. **阶段 1 — 共存运行**：项目中现存 YAML 保持双字段（`shortcut: C` + `trigger: commit`），新增菜单项可任选三种格式之一；Schema 的 `z.union()` 联合类型同时接受三种输入。
+2. **阶段 2 — 自动迁移脚本**：提供 `xiaoma migrate-triggers --from=dual --to=compound` 命令行子命令，遍历项目下所有 `.agent.yaml`，将每个 `{shortcut: X, trigger: Y}` 改写为 `trigger: "X or fuzzy match on Y"`，并在 description 前补齐 `[X] ` 标记（若缺失）。脚本输出 diff 供作者审阅后再写入。
+3. **阶段 3 — 双字段格式弃用**：在阶段 2 完成后的下一个大版本中，从 Schema 的 `z.union()` 中移除 `LegacyDualFieldSchema` 分支，仅保留复合与简化两种格式；CI/CD 将在弃用版本上拦截旧格式输入。
+
+整个迁移路径不要求作者一次性改完所有现存 YAML——双字段格式与复合格式可在同一智能体内并存数个版本周期。
+
+## 5.6 建议权利要求方向（初稿，供代理人参考）
+
+**独立权利要求 1（方法 — 三态机 + 熵最小化派生 + 命名空间分区）**：
+
+一种 AI 智能体快捷键的派生与登记方法，其特征在于，包括以下步骤：
+
+- S1：维护每个 AI 智能体所属模块对应的快捷键命名空间，每个命名空间持有独立的"已注册快捷键集合"；不同模块的命名空间相互独立，跨命名空间引用时使用"模块标识符 + 冒号 + 快捷键"的限定符形式表达；
+- S2：对所述智能体菜单项中以小写短横线分隔字符串形态声明的触发词，由派生函数枚举其候选快捷键集合 `Cand`；所述候选集合由触发词各单词首字母按声明顺序组合而成的若干 1-3 字符大写串构成；
+- S3：对所述候选集合中每个候选 `s`，按预设权重的代价函数 `cost(s) = α · collisionCount(s) + β · inputDeviceErgonomicCost(s) + γ · entropy(s)` 计算代价，其中 `collisionCount` 在本命名空间的"已注册快捷键集合"内查询，`inputDeviceErgonomicCost` 由"实施者预定义的按键代价矩阵"推算（所述矩阵由部署环境的输入设备布局决定，本方法不限定具体输入设备类别），`entropy` 由字母频次熵推算；权重系数满足 `α >> β` 且 `α >> γ`，使避免碰撞作为主导优化目标；选取代价最小者作为初步候选并置入"候选态"；
+- S4：所述初步候选经格式校验、描述字段一致性校验后转入"已派生态"；再经唯一性校验后写入本命名空间的"已注册快捷键集合"，转入"已注册态"；上述三态及其转移事件被持久化到编译产物的清单中，使派生过程可外部审计；
+- S5：当 S4 唯一性校验命中已注册集合中相同字面快捷键时，回退至"候选态"并触发冲突降级——按预设规则在候选末尾追加数字后缀，或重新进入 S3 取代价次小者；预设阈值次数内仍冲突则报告校验错误。
+
+**从属权利要求 2（基于已有复合触发格式的协议落地）**：
+
+根据权利要求 1 所述的方法，其中所述快捷键的来源除 S2 的派生路径外，还支持从复合触发字段直接提取——所述复合触发字段使用业界已有的"大写字母短串 + 固定分隔短语 + 小写短横线分隔字符串"复合格式（例如形如 `<SHORTCUT> or fuzzy match on <kebab-trigger>` 的字面表达），由 S2 之前的格式校验步骤拆分出快捷键子串与触发词子串后，将所述快捷键子串作为 S4 中的"已派生态"候选直接送入唯一性校验，跳过 S2 与 S3。
+
+**从属权利要求 3（三层 Schema 校验链）**：
+
+根据权利要求 1 所述的方法，进一步包括三层校验链：(a) 第一层为基础结构校验，确认触发字段与描述字段格式正确且至少存在一个命令目标字段；(b) 第二层为格式校验与描述字段一致性校验；(c) 第三层为本命名空间内的唯一性校验；三层校验在 Schema 校验阶段一次性执行，使配置错误在 CI/CD 阶段即被拦截。
+
+**从属权利要求 4（双向验证协议）**：
+
+根据权利要求 1 所述的方法，进一步包括：所述描述字段以"方括号包裹的快捷键标记"开头，方括号后紧接一个空格再接描述文本；该方括号标记同时支持正向校验（快捷键 → 描述字段方括号内容一致性比对）与反向解析（从描述字段按预定义正则反向抽取快捷键用于运行时索引、菜单高亮、命令面板展示）；正向与反向两条解析路径形成冗余验证，任一方向解析失败即视为配置异常。
+
+**从属权利要求 5（格式版本协议）**：
+
+根据权利要求 1 所述的方法，其中 YAML 顶层包含 `agent-schema-version` 字段（缺省时默认为预设基础版本）；Schema 入口按所述 schema-version 查询预设版本路由表，选择对应版本的 superRefine 校验链与归一化器；新增 trigger 格式版本仅需在所述路由表中追加新分支，不破坏既有 agent 产物；编译产物清单中记录该 agent 的 schema-version，运行时按清单信息加载对应版本的归一化器。
+
+**从属权利要求 6（向后兼容三种格式）**：
+
+根据权利要求 1 与权利要求 2 所述的方法，进一步包括对所述触发字段支持的语法格式做向后兼容设计：除复合格式外，同时接受传统的"快捷键字段与触发词字段分立声明"的双字段格式与仅含小写短横线分隔字符串的简化格式；所述基础结构校验通过联合类型同时接受上述三种输入形式。
+
+**从属权利要求 7（基于集合的唯一性校验复杂度）**：
+
+根据权利要求 1 所述的方法，其中 S1 中"已注册快捷键集合"采用集合数据结构，使 S4 的唯一性校验复杂度为 O(1) / 单次查询、O(n) / 全部菜单项；相比朴素的两两比对 O(n²) 复杂度，在 n 增长时差异按 n 线性放大。
+
+**从属权利要求 8（裸快捷键输入的命名空间消解规则）**：
+
+根据权利要求 1 所述的方法，进一步包括运行时输入消解步骤：当用户输入仅含快捷键字面值（如 `CR`）而未包含模块限定符前缀（即未采用 `<module>:<shortcut>` 形态）时，按当前激活智能体所属模块的"已注册快捷键集合"查询命中项；若该命名空间内未命中，则按预设的模块优先级回退表（如 `xmc > core > utility > <external-modules>`）依次查询其他命名空间；当用户输入含模块限定符前缀时，直接定向查询所述模块对应的命名空间，不进行回退。所述运行时消解规则确保跨命名空间同字面快捷键在用户使用时具有可预期的优先级语义。
+
+**保护范围边界**：本方法不约束下游消费端（IDE 等）对所述归一化三元组中 `kebabTrigger` 字段的具体模糊匹配算法实现，包括但不限于编辑距离打分、子串前缀匹配、词向量相似度等；这些匹配算法的具体实现由下游 runtime 自行决定，不在本方法保护范围内。同时**承认复合触发格式本身（如 `SHORTCUT or fuzzy match on kebab-trigger` 字面语法）为本领域已有实践，不在独立权利要求 1 的核心保护范围**——独立权利要求 1 以"三态机 + 熵最小化派生 + 命名空间分区"为核心，复合格式作为从属权利要求 2 的具体载体之一。代价函数的权重系数仅约束相对量级关系（`α >> β` 且 `α >> γ`），不限定具体取值；`inputDeviceErgonomicCost` 所依据的按键代价矩阵由实施者按目标输入设备布局自行定义，**不限定具体的输入设备类别**（QWERTY、Dvorak、AZERTY、Colemak、触屏、语音输入等均为等效替代）；字母频次熵的具体实现可按部署场景调整。从属权利要求 8 的模块优先级回退表的具体顺序由实施者按部署场景预设，本方法仅约束"含限定符直接定向 / 不含限定符按当前模块优先且按预设表回退"的判定框架。
+
+# 6、针对第3部分的技术方案，是否还有别的替代方案同样能完成发明目的？
+
+| 替代方案 | 核心做法 | 与本方案对比 |
+| --- | --- | --- |
+| 一、复合触发格式改用 JSON 对象 | `{"shortcut": "C", "fuzzy": "commit"}` 替代字符串 | 字段含义明确无需正则解析；缺点是配置量没有减少（仍是两个字段），YAML 中嵌套对象的可读性不如单行字符串 |
+| 二、IDE 风格自动选择算法 | 派生时若快捷键冲突，自动选择备选字母（类似 Intellij Action 分配） | 避免手动配置；但自动选择的快捷键可能与触发词语义无关（`commit` 可能被分配为 `O` 而非 `C`），降低记忆友好性 |
+| 三、独立 shortcut 字段 + 强约束 | 保留 `shortcut` 与 `trigger` 双字段，但在 Schema 强约束 shortcut 必须等于 trigger 首字母 | 兼容历史 YAML，但回到了双字段配置，且强约束反而限制作者灵活性 |
+
+# 7、与代表性现有技术的逐项对照
+
+| 关键点 | 双字段配置 | BMAD-METHOD 复合 trigger | Theia Slash Commands | Windsurf Command | IntelliJ Keymap | 本方法 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 复合触发格式语法（快捷键 + 关键词单字段） | ✗ | ✓（已有实践） | ✗ | ✗ | ✗ | 沿用为基础协议（不主张独创） |
+| 三层 Schema 校验链 | ✗ | △（基础校验未细分三层） | ✗ | ✗ | ✗ | ✓ 作为从属权利要求 |
+| 派生算法（kebab → shortcut） | ✗ | △（部分派生） | ✗ | ✗ | ✗ | ✓ 作为从属权利要求 |
+| `[SHORTCUT]` 标记一致性 | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ 作为从属权利要求 |
+| 快捷键三态机（proposed → derived → registered） | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ 独立权利要求核心 |
+| 熵最小化派生（cost 函数 + 键盘人体工学） | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ 独立权利要求核心 |
+| 命名空间分区 + `module:CR` 限定符 | ✗ | ✗ | ✗ | ✗ | △（按 plugin scope） | ✓ 独立权利要求核心 |
+| 双向验证协议（正向 + 反向） | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ 作为从属权利要求 |
+| 格式版本路由表（`schema-version`） | ✗ | ✗ | ✗ | ✗ | △（按 IDE 版本但非声明式路由） | ✓ 作为从属权利要求 |
+
+可见关键点"快捷键三态机 / 熵最小化派生 / 命名空间分区"（独立权利要求 1 核心三件套）在所列代表性现有技术中均未披露；其余从属权利要求中的"复合触发格式 / 三层校验 / 派生算法 / [SHORTCUT] 标记 / 格式版本"在 BMAD-METHOD 等开源方案中有零星部分披露，未形成本方法的系统组合。
+
+# 附图说明
+
+**附图1 — 复合触发格式解析状态机**
+
+![附图1 - 复合格式解析状态机](media/doc5_fig1.png)
+
+输入触发字符串 → 判断是否包含 ` or fuzzy match on ` → 复合格式解析（COMPOUND_TRIGGER_PATTERN）或纯 kebab-case 解析（TRIGGER_PATTERN）→ 输出 `{shortcut, kebabTrigger}` 的状态转移。
+
+**附图2 — 多层 Schema 校验流程图**
+
+![附图2 - 多层 Schema 校验](media/doc5_fig2.png)
+
+第一层 z.object 结构校验 → 第二层复合/简单格式判定与 COMPOUND_TRIGGER_PATTERN 解析及 [SHORTCUT] description 一致性比对 → 第三层 seenTriggers 集合的唯一性校验，依次执行。
+
+**附图3 — 快捷键自动派生示例**
+
+![附图3 - 快捷键自动派生示例](media/doc5_fig3.png)
+
+不同 kebab-trigger 输入（commit、pull、tech-spec、code-review、pre-flight-check、analysis-document-export 等）对应的派生快捷键输出（C、P、TS、CR、PF、AD 等）。
+
+
+## 附图源码（Mermaid，供绘图工程师参考重绘）
+
+**附图1 — 复合格式解析状态机**
+
+```mermaid
+stateDiagram-v2
+    [*] --> INIT
+    INIT --> SHORTCUT_BODY: A-Z
+    INIT --> SIMPLE_KEBAB: a-z/0-9
+    SHORTCUT_BODY --> SHORTCUT_BODY: A-Z (最多3字符)
+    SHORTCUT_BODY --> EXPECT_OR: 空格
+    EXPECT_OR --> KEBAB_BODY: " or fuzzy match on "
+    EXPECT_OR --> ERROR: 不匹配
+    KEBAB_BODY --> KEBAB_BODY: a-z/0-9/-
+    KEBAB_BODY --> ACCEPT_COMPOUND: 字符串末尾
+    SIMPLE_KEBAB --> SIMPLE_KEBAB: a-z/0-9/-
+    SIMPLE_KEBAB --> ACCEPT_SIMPLE: 字符串末尾
+    ACCEPT_COMPOUND --> [*]
+    ACCEPT_SIMPLE --> [*]: 自动派生 shortcut
+    ERROR --> [*]
+```
+
+**附图2 — 多层 Schema 校验**
+
+```mermaid
+flowchart TD
+    A[(YAML 菜单项)] --> L1[第一层: z.object 结构校验]
+    L1 -->|fail| F1[结构错误]
+    L1 -->|pass| L2A[第二层a: 复合/简单格式判定]
+    L2A --> L2B[第二层b: COMPOUND_TRIGGER_PATTERN 解析]
+    L2B -->|fail| F2[格式错误]
+    L2B -->|pass| L2C[第二层c: [SHORTCUT] description 一致性]
+    L2C -->|不匹配| F3[描述不一致错误]
+    L2C -->|pass| L3[第三层: seenTriggers Set 唯一性]
+    L3 -->|重复| F4[重复触发词错误]
+    L3 -->|pass| OK[校验通过]
+```
+
+**附图3 — 快捷键自动派生示例**
+
+```mermaid
+flowchart LR
+    subgraph IN[输入 kebab-trigger]
+        K1[commit]
+        K2[pull]
+        K3[tech-spec]
+        K4[code-review]
+        K5[pre-flight-check]
+        K6[analysis-document-export]
+    end
+    K1 -.单词,首字母.-> S1[C]
+    K2 -.单词,首字母.-> S2[P]
+    K3 -.双词,前两词首字母.-> S3[TS]
+    K4 -.双词,前两词首字母.-> S4[CR]
+    K5 -.三词,仅取前两词.-> S5[PF]
+    K6 -.三词,仅取前两词.-> S6[AD]
+```