@zeyue0329/xiaoma-cli 1.0.49 → 1.0.66

package//344/270/223/345/210/251/344/272/244/345/272/225/344/271/246_3_AI/346/231/272/350/203/275/344/275/223/345/243/260/346/230/216/345/274/217/345/256/232/344/271/211/347/232/204/347/274/226/350/257/221/346/265/201/346/260/264_20260318.md

@@ -0,0 +1,624 @@
+**技术交底书**
+
+**交底书名称：**一种AI智能体声明式定义的编译及激活块注入方法及系统
+**本专利发明人：**刘二杨
+**技术问题联系人：**刘二杨
+**联系人电话：**（待填写）
+**E-MAIL：**liueryang@yljr.com
+
+# 该发明所属技术领域
+
+本发明涉及计算机软件技术领域，具体涉及一种将 AI 智能体的声明式 YAML 定义编译为可执行 XML 格式的流水线方法，以及基于智能体特征分析的激活块按需组装注入方法。
+
+# 术语解释
+
+| 术语 | 中文/英文全称 | 一句话定义 |
+| --- | --- | --- |
+| 声明式 YAML 定义 | Declarative Agent YAML | 以 YAML 格式声明智能体的 metadata、persona、menu、prompts 等结构化字段 |
+| 激活块 | Activation Block | 编译后智能体文件中嵌入的 XML 指令集，定义运行时初始化、菜单处理、交互规则 |
+| 片段缓存 | Fragment Cache | 内存中的 Map 结构，缓存已加载的激活块片段文件，避免重复 I/O |
+| 智能体特征分析 | Agent Profile Analysis | 对智能体 menu 字段的静态扫描，确定该智能体实际使用了哪些处理器类型 |
+| AgentAnalyzer / ActivationBuilder | — | 执行特征分析的模块（输出 `usedAttributes` Set 和 `hasPrompts` 标志）；按需组装激活块片段的模块 |
+| usedAttributes / hasPrompts | — | 特征分析输出的处理器属性集合（元素来自 `{exec, tmpl, data, action}`）；prompts 段落是否存在的标志位 |
+| 处理器 | Handler | 菜单项中决定指令执行方式的属性，包含 exec / tmpl / data / action 四类 |
+| 模板引擎 / 占位符 | Template Engine / Placeholder | 将占位符与数据上下文渲染为目标字符串的程序模块；模板中可被替换的标记，如 `{{var}}`、`{{#if var}}` |
+| superRefine | Zod superRefine | Zod 库的高级校验机制，在基础结构校验通过后执行跨字段关联校验 |
+| Zod | Zod Schema Library | TypeScript/JavaScript 运行时数据校验库 |
+| JSON Patch | RFC 6902 | 一种描述 JSON 文档变更的标准格式，支持 add / remove / replace 操作符（仅用于 §6 替代方案比较）|
+| 编译产物 | Compilation Output | 三阶段流水线的最终输出，含 Markdown frontmatter 与可执行 XML |
+| 制品 / 模块 | Artifact / Module | 框架中可独立编排和分发的逻辑单元；一组共享配置变量、目录约定与命名空间的制品集合，如 `core`、`xmc` |
+
+# 1、详细介绍技术背景，并描述已有的与本发明最相近似的实现方案
+
+AI 智能体框架中，智能体的定义通常采用声明式格式（如 YAML）以降低编写门槛。本框架 v1.12.0 `src/xmc/agents/` 下共 8 个智能体声明式定义文件，分别承载 analyst、architect、dev、pm、qa、quick-flow-solo-dev、sm、ux-designer 八个角色。但 AI IDE 在实际执行时需要解析结构化的指令格式（如 XML），因此需要一个编译过程将声明式定义转换为可执行格式。
+
+现有相近做法主要有两类。
+
+**做法一：全量模板替换**——预先定义一个包含所有可能组件的完整 XML 模板，编译时将 YAML 字段值填入模板中的占位符。这种做法存在三类问题：
+
+| 问题类型 | 具体表现 | 根因 |
+| --- | --- | --- |
+| XML 膨胀 | 简单智能体（如只用 `exec` 处理器）也会注入 `tmpl`/`data`/`action` 等全部处理器代码 | 模板不区分智能体特征，按"最大集"渲染 |
+| 定制化与模板处理时序冲突 | 用户定制内容中含 `{{var}}` 时被模板引擎误解析；或模板变量被定制数据覆盖 | 合并与替换的执行顺序未严格隔离 |
+| 片段重复加载 | 批量编译多个智能体时，相同片段文件被重复从磁盘读取 | 无内存缓存机制 |
+
+不同类型的智能体使用的处理器组合差异很大——一个简单的分析师智能体可能只用 `exec`（执行工作流）处理器，而高级架构师智能体可能同时用 `exec`、`tmpl`（模板渲染）、`data`（数据加载）、`action`（动作触发）四种处理器。全量模板方式会为只用 `exec` 处理器的智能体也注入 `tmpl`、`data`、`action` 的处理器代码，产生明显的冗余 XML 内容（具体冗余比例与智能体复杂度反相关——越简单的智能体冗余越严重）。
+
+此外，用户可能需要在基础智能体定义基础上追加额外的菜单项、关键操作、记忆条目等，同时保留基础定义中的模板变量（如 `{{project_name}}`）。如果定制合并和模板变量替换的执行顺序不当，会出现定制内容被模板引擎误处理、或模板变量被定制数据覆盖的问题。
+
+**做法二：开源 AI 智能体框架（如 BMAD-METHOD）的编译流程**——BMAD-METHOD（公开仓库 `bmad-code-org/BMAD-METHOD`，MIT 许可）作为本领域代表性开源方案，亦实现了从声明式 YAML 到可执行 XML/Markdown 的转换流程。其已公开实现包括 YAML 解析、占位符替换、激活块拼接等基础编译能力，可视为做法一在 AI 智能体框架场景的具体实例。但其公开实现**未披露**以下机制：(i) 编译产物的确定性指纹（Reproducible Build）；(ii) 基于特征向量差分的增量编译；(iii) 定制字段集合 ∩ 模板可注入字段集合的代数冲突检测；(iv) 跨智能体的片段共享缓存层；(v) 三阶段顺序的代数必要性反证。本方案在此类已有开源编译流程的基础上，针对上述工程空白提出系统性改进。
+
+# 2、现有技术的缺点是什么？针对这些缺点，说明本发明的目的
+
+| 现有缺陷 | 具体表现 | 本发明对应目的 |
+| --- | --- | --- |
+| 全量激活块注入导致 XML 膨胀 | 在本框架 v1.12.0 的 8 个智能体（`src/xmc/agents/`）中，简单智能体（仅含 `exec` 处理器、无 prompts、无 memories）若按"全量模板"渲染会被注入 `handler-tmpl`、`handler-data`、`handler-action`、`prompts-wrapper` 等本智能体并未使用的段落 | 基于特征分析按需组装片段，仅注入实际使用的处理器 |
+| 定制化合并时序错误 | 先模板后合并 → 定制中的 `{{}}` 被误解析；先合并后模板 → 定制中的 persona 等非模板字段被扫描处理 | 严格三阶段时序：定制合并 → 模板替换 → XML 生成 |
+| 片段文件重复加载 | 批量编译 8 智能体若无缓存会对相同片段文件（`activation-init.txt`、`menu-handlers.txt`、`activation-rules.txt` 等通用片段）发起重复 I/O | Map-based 片段缓存，首次加载后驻留内存 |
+
+本发明目的：提供一种基于智能体特征分析的编译流水线，先分析每个智能体实际使用的处理器类型，再按需组装激活块片段，并通过"定制合并 → 模板替换 → XML 生成"三阶段严格时序避免定制化与模板处理的冲突，同时使用片段缓存减少重复 I/O。
+
+# 3、本发明技术方案的详细阐述
+
+## 3.1 基本原理
+
+### 3.1.0 形式化总框架：特征向量驱动的按需编译
+
+本方法的**形式化总框架**为：对每个智能体 `a` 定义一个特征向量 `FV(a)`（详见 §3.2.8 形式化定义），所有编译动作以 `FV(a)` 为控制信号执行选择性输出；三阶段串行（定制合并 → 模板替换 → XML 生成）是本框架下的**具体调度形态**而非框架本身。
+
+智能体编译的本质是从"声明"到"可执行"的转换过程。本方案借鉴编译器优化中的"死代码消除"（Dead Code Elimination）与"常数折叠"（Constant Folding）思路——这两类优化都依赖一个共同前提：先对程序做静态分析（确定哪些代码段对最终输出有贡献），再按分析结果做选择性输出。本方法把这一思路在 AI 智能体编译场景下落地为：
+
+- **特征向量提取**：先对 YAML 声明做特征分析（抽取实际使用的 handler 类型集合 + prompts 存在标志），输出"实际用到了哪些片段"的形式化特征向量 `FV(a)`（§3.2.8）；
+- **选择性输出**：再按 `FV(a)` 按需加载和拼接片段（仅注入用到的 handler 片段），输出最终可执行 XML；
+- **指纹化与差分化**：将 `FV(a)` 与源/定制/片段哈希拼接为编译产物指纹（§3.2.9），并以 `delta_FV` 为单位做增量编译（§3.2.10）；FV 等价的智能体共享同一拼接产物（§3.2.12）。
+
+三阶段串行架构（§3.2.1-§3.2.7）作为本框架下的具体调度形态，其代数必要性反证（§3.1.1）保证调度顺序的唯一性，但本方法的**新颖性核心在于 FV 形式化与按需编译，而非三阶段调度本身**——三阶段流水线作为工程规范在本领域已属常见，但以 FV 五元组形式驱动选择性输出、指纹化、差分化、等价类共享的整体架构未见同等组合。
+
+整个编译流程被分解为三个严格串行的阶段：**定制合并 → 模板替换 → XML 生成**。三阶段之间的边界是绝对的——定制数据在阶段 1 结束时就从待处理 answers 中移除，确保阶段 2 的模板引擎完全接触不到非模板数据；阶段 3 的特征分析也在合并后的 YAML 上进行，避免在尚未合并完成的中间状态做判断。
+
+### 3.1.1 三阶段严格串行的必要性反证
+
+三阶段顺序不能任意调整。下表给出"若改序则何处出错"的反证，证明 (1 → 2 → 3) 是唯一一个无歧义的执行序：
+
+| 改序方案 | 立即破坏的不变量 | 具体错误示例 |
+| --- | --- | --- |
+| (2 → 1 → 3)：先模板，再合并 | 阶段 2 输入还含有定制数据中的 `{{}}` | 定制 `customize.yaml` 中含有用户原样写入的提示词模板字符串 `{{project_name}}`，模板引擎会试图替换它，但此时 `project_name` 并不在 answers 中，于是字符串被清空或抛错——而本意是把这段字符串作为字面量传入最终产物 |
+| (1 → 3 → 2)：先合并，跳到 XML 生成，再做模板替换 | 阶段 3 产物已是 XML 而非 YAML，模板引擎需新增 XML 解析能力 | 阶段 2 不得不在 XML 字符串上做正则替换，破坏 `<handler-exec>` 等结构化标签里嵌入的占位符语法；当占位符出现在标签属性 `desc="{{role}}"` 中时引号转义引发解析错误 |
+| (3 → 1 → 2)：先 XML 生成，再合并 | 阶段 1 的"分字段类型合并"无标的物可操作 | XML 是树状结构，metadata 的深度合并、prompts 的按 ID 去重等都需要 YAML 字段级访问能力；改在 XML 上做合并要求重新实现 XPath/XSLT，相当于推翻 §3.2.1 整套合并策略 |
+
+由此推出：阶段 1 必须先于阶段 2（否则定制中的字面量 `{{}}` 被误处理），阶段 2 必须先于阶段 3（否则模板引擎需面对 XML），阶段 3 必须最后（否则合并无标的）。三阶段顺序是唯一可行的拓扑序。
+
+## 3.2 详细的技术方案
+
+### 3.2.1 阶段 1：定制化合并
+
+阶段 1 的对外入口的输入与输出契约：编译单个智能体的入口接收三个参数——**智能体声明式 YAML 原文**（字符串形态，含 metadata、persona、menu、prompts 等结构化字段）、**用户定制数据对象**（含 `customize.yaml` 各字段与模板变量的合并体）、**可选项**（包含是否构建 Web 端 bundle、源文件路径、是否清空片段缓存等控制项）。整条三阶段流水的最终产出形态为 "Markdown frontmatter + 可执行 XML" 的复合 Markdown 文本；阶段 1 的中间产出为合并后的中间 YAML 结构（含 metadata / persona / menu / prompts 等字段）；阶段 3 的特征分析产出为 "实际使用的处理器属性集合（来自 `exec` / `tmpl` / `data` / `action` 的集合）" 与 "prompts 存在标志位" 两个字段；此外可附加缓存命中次数、I/O 次数、总耗时等可观测统计项供后续诊断使用。
+
+阶段 1 接收上述原始 YAML 字符串与用户定制化数据后，合并按以下策略**分字段类型执行**：
+
+| 字段 | 合并策略 | 规则细节 |
+| --- | --- | --- |
+| `metadata` | 对象深度合并 | 用 `filterCustomizationData` 递归过滤 null/undefined/空字符串后，`Object.assign` 浅合并到基础 metadata；非空值覆盖基础值 |
+| `persona` | 整体替换 | 因 persona 各字段高度关联，部分覆盖可能导致不一致，故采用全量替换策略 |
+| `critical_actions` | 数组追加 | `[...existing, ...customizations.critical_actions]`，保留基础定义中的所有操作 |
+| `memories` | 数组追加 | 逻辑同 critical_actions |
+| `menu` | 数组追加 | 用户定制的菜单项添加到基础菜单末尾 |
+| `prompts` | 数组追加（当前实现）/ 按 ID 去重合并（优选实施例） | 见下文 3.2.2 |
+
+合并 YAML 的 before/after 样例：
+
+```yaml
+# 基础 YAML (base.yaml)
+metadata:
+  id: po
+  module: xmc
+persona:
+  role: Product Owner
+critical_actions:
+  - "读取用户故事"
+prompts:
+  - id: code-review
+    role: system
+    content: "基础提示词"
+
+# 定制 customize.yaml
+metadata:
+  team: 风控
+critical_actions:
+  - "在 Linear 同步状态"
+prompts:
+  - id: code-review     # 同 ID 触发去重合并
+    content: "覆盖后的提示词"
+  - id: deploy-check    # 新 ID 触发追加
+
+# 合并结果
+metadata: { id: po, module: xmc, team: 风控 }    # 深度合并
+persona: { role: Product Owner }                  # 未覆盖（定制中未给出）
+critical_actions:
+  - "读取用户故事"
+  - "在 Linear 同步状态"                          # 追加
+prompts:
+  - id: code-review
+    role: system
+    content: "覆盖后的提示词"                     # 同 ID 覆盖
+  - id: deploy-check
+    role: system
+    content: ...                                  # 新 ID 追加
+```
+
+所有 `customizationKeys` 处理完毕后，从 `answers` 中移除这些键，剩余的键值对作为模板变量传递给阶段 2。**这是解决"定制合并与模板处理冲突"的关键设计**——通过在阶段 1 就将定制数据从 `answers` 中分离，确保阶段 2 的模板引擎不会接触到非模板类数据。
+
+**实现位置**：`tools/cli/lib/yaml-xml-builder.js` 中 `YamlXmlBuilder` 类的定制合并方法（文件总长 570 行，定制合并相关逻辑位于第 59-137 行附近的字段分发分支中）。
+
+### 3.2.2 prompts 合并语义：当前实现与优选实施例
+
+本节披露 prompts 数组的合并语义。鉴于该字段对定制成本敏感（一个智能体可能含 50+ 条 prompts），本方法提供两级语义供工程实现选择：
+
+**当前代码实现（数组追加，简单实施例）**：将定制 prompts 数组整体追加到基础 prompts 数组末尾，**不按 ID 去重**。若基础与定制有同 ID 条目，结果中会同时存在两条；上层消费者（如 IDE）通常以"后出现者优先"语义读取，相当于隐式覆盖。该实现位于 `tools/cli/lib/yaml-xml-builder.js`，与 `critical_actions`、`memories`、`menu` 三个字段共用同一追加策略，逻辑统一、实现成本最低。
+
+**优选实施例（按 ID 去重合并，作为方法专利的可实施例描述）**：
+
+遍历定制 prompts 数组，对每个定制 prompt 执行：
+
+1. 用 `findIndex` 在基础 prompts 中按 `id` 字段查找；
+2. 若存在相同 ID：**替换**（用定制版本完全取代基础版本，未在定制中给出的字段不保留基础值——这是显式覆盖语义）；
+3. 若不存在：**追加**到基础 prompts 末尾。
+
+该语义使用户能以最小的 YAML 片段精确覆盖某一条 prompt 而无需复制整个 prompts 数组；同时清单中不会出现两条同 ID 记录，避免下游依赖隐式优先级。在 50+ prompts 的复杂智能体场景中，定制文件行数可降至与"被覆盖 prompt 数量"线性相关（每条 1-3 行），相比追加策略下的整数组复制开销大幅减少；同 ID 记录的去重也使产物 XML 中 prompts 段不再出现"同 ID 双条目"现象。
+
+两级语义均落在"分字段类型的定制化合并策略"权利要求范围内：base 与 customize 的合并是有类型敏感性的（数组类的追加、对象类的深度合并、按 ID 类的去重合并），核心创新点在于"针对不同字段语义选择不同合并策略"这一架构决策。后续版本计划将 prompts 升级至按 ID 去重合并语义，与当前实现完全兼容（行为退化条件：定制集中无与基础同 ID 的条目）。
+
+### 3.2.3 阶段 2：模板变量替换
+
+本节描述阶段 2 的"条件块解析 + 占位符替换 + install_config 剥离"完整模板处理协议。在仅做定制合并而无需按用户答案裁剪 YAML 内容的简化场景下，本阶段可退化为"直接透传 + install_config 剥离"两步——此时三阶段架构本身不变（阶段 1 输出仍流经阶段 2 进入阶段 3），仅模板引擎的工作量降为零。
+
+`extractInstallConfig` 函数从 YAML 中提取 `install_config` 配置块，`getDefaultValues` 函数扫描其中的 `questions` 数组获取各字段的默认值。将默认值与用户提供的答案合并（用户答案优先）后，调用 `processAgentYaml` 函数执行替换。
+
+模板引擎支持三种条件语法：
+
+- `{{#if varname}}...{{/if}}`
+- `{{#unless varname}}...{{/unless}}`
+- `{{#if varname == "value"}}...{{/if}}`
+
+处理顺序为：先处理条件块（可能包含变量引用）→ 再处理变量替换 → 最后清理未替换的占位符。这种两遍处理使条件块内的变量也能正确替换。替换完成后调用 `stripInstallConfig` 移除 `install_config` 块，使编译输出不包含安装配置信息。
+
+**嵌套条件块处理规则**：当出现 `{{#if outer}}...{{#if inner}}...{{/if}}...{{/if}}` 等嵌套形式时，模板引擎采用"从外到内逐层求值"策略：
+
+1. **逐层求值**：以最外层条件块为根，先判定其布尔值——若为 false，整段直接剔除（含内层未求值的占位符），不再下钻；若为 true，移除外层 `{{#if}}` / `{{/if}}` 标记后递归处理内层；
+2. **深度上限**：嵌套深度默认上限为 3 层，超过则保留原文不替换并写 `warn` 级告警（不抛异常），便于人工排查超嵌套场景；该上限来源于实测——v1.12.0 仓库中所有现存模板嵌套深度均 ≤2 层，留 1 层余量；
+3. **括号配对**：使用栈结构匹配 `{{#if}}` 与 `{{/if}}`，若发现不配对（如多 `{{#if}}` 少 `{{/if}}`），抛 `UnbalancedConditionBlock` 异常并定位到首个不配对标签的字符偏移；
+4. **同名占位符在条件块内外的语义一致**：`{{var}}` 在条件块内被替换的值与块外被替换的值完全一致（同一 `answers` 字典查询），不引入条件块本地作用域，避免代理人理解负担。
+
+之所以不引入 Handlebars 等成熟模板引擎，是基于"编译总耗时 < 50ms"的硬性目标——Handlebars 首次加载约 30ms、单次渲染 5-8ms，会让单智能体编译耗时翻倍；当前的轻量正则替换足以覆盖现有占位符模式。
+
+### 3.2.4 阶段 3：XML 生成与激活块按需注入
+
+此阶段包含三个子步骤：
+
+**子步骤 A — 智能体特征分析**：`AgentAnalyzer.analyzeAgentObject` 方法扫描 `agent.menu` 数组中所有菜单项。对传统格式菜单项，检查是否存在 `exec`、`tmpl`、`data`、`action` 属性。对 multi 格式菜单项，递归检查 `triggers` 数组中嵌套 handler 的 `route`、`action`、`data`、`tmpl` 属性。扫描结果经集合去重后输出为 `usedAttributes` 特征集合（如 `{"exec", "tmpl"}`），同时检测是否存在 prompts 段落输出 `hasPrompts` 标志。
+
+**子步骤 B — 激活块按需组装**：`ActivationBuilder` 根据特征分析结果加载片段文件：
+
+1. **通用片段先行**：`activation-init.txt`（初始化指令）、`menu-handlers.txt`（菜单基础处理器）、`activation-rules.txt`（交互规则）；
+2. **处理器片段按需**：仅当特征集合中包含 `exec` 标识时才加载 `handler-exec.txt`，包含 `tmpl` 标识时加载 `handler-tmpl.txt`，以此类推；
+3. **prompts 片段条件**：仅当 `hasPrompts === true` 时才加载 `prompts-wrapper.txt`。
+
+**子步骤 C — XML 拼接输出**：按以下顺序拼接：Markdown frontmatter（含 `name` 和 `description`）→ XML 代码块开始标记 → `<agent>` 开放标签（含 `id`、`name`、`title`、`icon`、`capabilities` 属性）→ 激活块 → `<persona>` 段 → `<prompts>` 段（若有）→ `<memories>` 段（若有）→ `<menu>` 段 → `</agent>` 闭合标签 → 代码块结束标记。其中 `<menu>` 段自动注入固定的系统菜单项（`MH` 菜单帮助、`CH` 自由聊天、`PM` 派对模式、`DA` 退出智能体）包裹用户定义的菜单项。
+
+"简单智能体"的工程定义（用于本节 XML 体积量化的对照基准）：满足以下三个条件之一即归入"简单智能体"类——(a) `usedAttributes` 集合 ⊆ {exec}（即 menu 中所有菜单项仅使用 exec 处理器，不出现 tmpl/data/action）；(b) `hasPrompts === false` 且 `memories` 为空；(c) 不含 `menu.multi` 嵌套结构。三条件并非互斥，符合任意一条即可——v1.12.0 工作树 8 个智能体中有约半数落入此类（如 analyst、qa、ux-designer 等基础角色），其余为含 tmpl/data 的复合智能体。该定义仅用于 §4 表"XML 体积"行的量化对照基准，不影响权利要求保护范围。
+
+一个简单分析师智能体（仅含 `exec` 处理器，无 prompts、无 memories）的编译输出完整样例如下（约 20 行）：
+
+```markdown
+---
+name: analyst
+description: "[A] 业务分析师智能体，专长需求挖掘与领域建模"
+---
+
+```xml
+<agent id="analyst" name="Analyst" title="业务分析师" icon="🔍" capabilities="research,brainstorm">
+  <activation>
+    <init>读取项目上下文 → 加载 user/project memory → 准备菜单</init>
+    <handler-exec>菜单项含 exec 时，调用 workflow 执行器</handler-exec>
+    <rules>遵守 communication_style；非菜单输入走 fuzzy match</rules>
+  </activation>
+  <persona role="业务分析师" style="结构化、追问式" />
+  <menu>
+    <item trigger="MH" desc="[MH] 显示菜单帮助" action="menu-help" />
+    <item trigger="A or fuzzy match on analyze" desc="[A] 启动分析工作流" exec="{project-root}/xiaoma/xmc/workflows/1-analysis/analyze.md" />
+    <item trigger="CH" desc="[CH] 自由聊天" action="chat" />
+    <item trigger="PM" desc="[PM] 派对模式" action="party" />
+    <item trigger="DA" desc="[DA] 退出智能体" action="exit" />
+  </menu>
+</agent>
+```
+```
+
+对照"全量模板"模式下的等效产出会含有 `handler-tmpl`、`handler-data`、`handler-action`、`prompts-wrapper` 等本智能体并未使用的段落；本方法的特征分析机制按需仅注入 `handler-exec`，对简单智能体（仅 `exec`、无 prompts、无 memories）可裁掉以上未使用段落，压缩比与冗余段落数线性相关。
+
+**实现位置**：智能体特征分析见 `tools/cli/lib/agent-analyzer.js`（97 行，第 7 行起 `class AgentAnalyzer`、第 13 行起 `analyzeAgentObject()`）；激活块按需组装见 `tools/cli/lib/activation-builder.js`（165 行）；XML 拼接与三阶段流水主入口见 `tools/cli/lib/yaml-xml-builder.js`（570 行）；菜单结构的 Zod 校验见 `tools/schema/agent.js`（489 行，第 80 行起的首个 `superRefine`）。
+
+### 3.2.5 Map-based 片段缓存与 clearCache 机制
+
+片段加载使用 Map 作为内存缓存——首次加载时读取文件并存入 Map（key 为片段路径，value 为内容），后续编译直接从 Map 中获取。当前工程版本已实现 Map 缓存 + 进程冷启动失效两种机制。
+
+`clearCache` 方法支持开发环境的热重载，触发条件包括：
+
+1. **配置变更（可实施例）**：检测到框架根目录 `mtime` 较 Map 中记录的 mtime 更新时，自动清空缓存；该路径作为方法专利的可选实施例，在 IDE 监听文件变更场景下接入；
+2. **手动 CLI flag（可实施例）**：调用 `xiaoma compile --no-cache` 时强制清空；该 flag 作为 CLI 入口扩展的实施例；
+3. **进程冷启动（已实现）**：Node 进程重启时 Map 自然失效。
+
+在生产环境批量编译中，缓存命中率较高——首批片段（`activation-init.txt`、`menu-handlers.txt`、`activation-rules.txt` 等通用片段）加载后，后续 v1.12.0 工作树的 8 个智能体的编译复用同一份缓存。
+
+### 3.2.6 multi 格式菜单的递归处理
+
+`menu.multi` 字段支持嵌套结构（一组 triggers 可以再包含子 triggers）。本方案对递归扫描的设计如下：
+
+1. **基础递归扫描**：`AgentAnalyzer` 与 `ActivationBuilder` 对 multi 字段执行递归扫描，遵循自然递归终止条件——遍历完所有叶节点后退出；实际场景中嵌套深度通常 ≤3 层；
+2. **栈深度软上限**：作为防御异常输入的扩展实施例，可通过深度计数器在递归入口处累加，达到配置上限（默认 8 层）时记录日志并截断处理，不抛异常以免单条非法配置阻塞整批编译；
+3. **特征分析与渲染同步递归**：`AgentAnalyzer` 与 `ActivationBuilder` 共用同一递归遍历协议，确保特征向量与实际渲染保持一致。
+
+**深度上限触发的反例**：当 menu.items 引用自身或形成环（例如 `multi.triggers[0].sub.triggers[0].sub.triggers[0]...` 无限自嵌套），或人为构造极深嵌套（>8 层）时，递归深度计数器在 `depth > MAX_DEPTH(=8)` 时记录如下结构的日志并截断该分支：
+
+```
+{
+  "event": "MULTI_MENU_DEPTH_EXCEEDED",
+  "agent_id": "analyst",
+  "menu_path": "menu[2].multi.triggers[0].sub.triggers[0]....sub.triggers[0]",
+  "depth_at_truncation": 9,
+  "soft_cap": 8,
+  "action": "truncate-branch-continue",
+  "severity": "warn"
+}
+```
+
+注意：环路（cyclic reference）在 YAML 解析阶段即被 `js-yaml` 库的 `safeLoad`（默认拒绝 anchor 形成的循环）拦截，理论上不会进入 multi 递归；上述深度上限主要针对"非环但极深"的人为输入。另一方面，若 `menu.items` 通过外部数据源动态加载并形成跨智能体的引用环（超出本编译器视野），同样在第 8 层被截断并不传播污染。
+
+递归特征分析算法的步骤性描述：
+
+1. **入口参数**：算法以"菜单节点"作为待处理输入、"已使用属性集合"作为输出累加器（首次调用时为空集合）、"当前递归深度"作为防御性参数（首次调用时为 0）。
+2. **深度上限保护**：每次进入递归先比较当前深度与预设深度上限（默认 8 层），超过上限时记录一条 `warn` 级告警（包含智能体 id、菜单路径、被截断时的深度、软上限值、降级动作等字段，详见上文反例所示的日志结构）并直接返回已积累的累加器，不抛异常以免单条非法配置阻塞整批编译。
+3. **数组型节点处理**：若当前节点为数组（即 menu 数组本身或 multi 节点下的 triggers 数组），对每个元素以同一深度计数继续递归下钻，子结果合并到同一累加器后返回。
+4. **叶节点的属性抽取**：对单条菜单项，扫描其字段集合，凡出现 `exec` / `tmpl` / `data` / `action` 等指令处理器属性、或 `route` 等等价的子字段时，将其**归一化为对应的 handler 片段标识**写入累加器——其中 `route` 与 `action` 折合为同一片段名（两者在按需组装阶段加载同一份 `handler-action.txt` 片段文件），保证累加器中的元素语义建立在 **handler 片段层面**而非 YAML 字段名层面，避免下游加载阶段出现"字段名不同但片段相同"的重复加载。
+5. **multi 节点的下钻**：若当前节点含嵌套的 `triggers` 数组（multi 格式菜单项），以**深度计数器加 1** 为参数对 triggers 中每个子项继续递归。
+6. **产出**：遍历完成后返回累加器，其元素即为后续按需组装激活块片段所依据的特征向量。
+
+### 3.2.7 编译失败处理与降级路径
+
+编译流水在以下五类异常输入下定义明确的处理策略，避免单一智能体的缺陷阻塞整批编译：
+
+| 异常类型 | 处理策略 | 副作用 |
+| --- | --- | --- |
+| 片段文件缺失（如 `handler-exec.txt` 不存在） | 短路抛出 `FragmentNotFoundError`，记录缺失片段路径与触发智能体 id；批量编译时跳过当前智能体，继续处理后续 | 该智能体不出现在产物目录；安装清单记录 `skipped=true` |
+| YAML 语法错误（阶段 1 解析失败） | 捕获 `YAMLException`，提取 `mark.line/column` 位置，包装为 `AgentParseError` 并附行号；批量编译跳过 | 同上 |
+| 模板变量循环引用（阶段 2 检测出 `{{a}}` → `{{b}}` → `{{a}}`） | 在两遍处理中加访问标志，第二次进入同一占位符即报错；不进入第三遍 | 仅当前智能体编译失败 |
+| 定制合并字段类型不匹配（如基础 `prompts` 是数组、定制给出对象） | 阶段 1 在分字段策略入口做 `Array.isArray` / `typeof` 守卫，类型不一致时抛 `MergePolicyMismatchError` | 同上 |
+| 缓存命中校验失败（片段文件 mtime 更新但 Map 未失效） | `clearCache` 触发后下一次加载强制走文件 I/O；若仍然失败按"片段文件缺失"处理 | Map 缓存清空一次 |
+
+所有异常路径下，files-manifest 与 skill-manifest 不写入半成品；产物目录使用临时目录策略——先输出至 `_compile.tmp/`，全批通过后原子 rename 为最终目录。
+
+### 3.2.8 特征向量形式化定义
+
+§3.2.4 的"智能体特征分析"在工程层面是 `AgentAnalyzer` 扫描 menu 输出 `usedAttributes` 集合与 `hasPrompts` 标志。为使该机制可证明、可比对、可哈希，本方案在专利层面给出形式化定义：
+
+设智能体 `a` 的特征向量为五元组：
+
+```
+FV(a) ≜ (E(a), T(a), D(a), A(a), M(a))
+```
+
+其中各分量的**元素类型**明确定义为：
+
+- `E(a) ⊆ {(menu_id, "exec") | menu_id ∈ menu(a)}`，每个元素是"菜单项标识 + handler 类型"二元组；当某菜单项使用 exec 处理器时被纳入；
+- `T(a) ⊆ {(menu_id, "tmpl") | menu_id ∈ menu(a)}`，类似定义；
+- `D(a) ⊆ {(menu_id, "data") | menu_id ∈ menu(a)}`；
+- `A(a) ⊆ {(menu_id, "action") | menu_id ∈ menu(a)}`（按 §3.2.6 步骤 4 已将 `route` 字段归一为 `action`，避免下游加载阶段重复加载同一片段文件）；
+- `M(a) ∈ {0, 1}`，prompts 段落是否存在的二值标志（来自 `hasPrompts`）。
+
+**两种粒度的实施例**（实施者按需选用）：
+
+| 粒度 | `E/T/D/A` 元素 | 适用场景 |
+| --- | --- | --- |
+| **细粒度**（默认） | `(menu_id, handler_type)` 二元组 | 支持菜单项级 delta_FV 增量编译（§3.2.10），同一智能体修改单一菜单项时仅重编差分项 |
+| **粗粒度 / bitset 退化** | `E,T,D,A ∈ {0, 1}` 布尔位，整体 FV ∈ `{0,1}^5` | 仅关心"是否注入对应 handler 片段"的简化场景；指纹/共享层仍可工作但 delta 粒度退化为"整 handler 片段重编" |
+
+工程实现中两种粒度由配置项 `compile.fv-granularity ∈ {fine, coarse}` 切换。细粒度时 `E(a) ∪ T(a) ∪ D(a) ∪ A(a)` 投影到第二分量后即等于 §3.2.4 的 `usedAttributes`；粗粒度时 `FV(a)` 即 5 个布尔位串。分量化使五个维度可独立比对，便于后续增量编译（§3.2.10）与跨 agent 共享（§3.2.12）。
+
+特征向量上定义偏序与等价关系：
+
+- 偏序 `FV(a) ⊑ FV(b) ⇐⇒ E(a) ⊆ E(b) ∧ T(a) ⊆ T(b) ∧ D(a) ⊆ D(b) ∧ A(a) ⊆ A(b) ∧ M(a) ≤ M(b)`；
+- 等价 `FV(a) ≡ FV(b) ⇐⇒ E(a) = E(b) ∧ T(a) = T(b) ∧ D(a) = D(b) ∧ A(a) = A(b) ∧ M(a) = M(b)`。
+
+偏序关系用于"片段加载集"的子集判断（被加载的片段构成完全格），等价关系用于 §3.2.12 的跨 agent 共享判定。
+
+### 3.2.9 编译确定性指纹（Reproducible Build）
+
+声明式编译流水的另一重要价值是"同输入必同输出"——这是 CI 流水中防漂移、产物分发去重、回归排查的基础能力。本方案据此引入编译产物的确定性指纹：
+
+```
+Fingerprint(a) ≜ SHA-256(
+  canonicalize(FV(a))            // 特征向量按 (E,T,D,A,M) 顺序、各集合按字典序输出
+  || HASH(source_canonical(a))   // YAML 源文件的规范化串（去除注释、统一缩进、键按字典序）
+  || HASH(customize_canonical(a))// 用户定制数据的规范化串
+  || HASH(fragment_versions(a))  // 该智能体本次实际加载的片段文件清单与各自内容哈希
+)
+```
+
+性质：
+
+1. **确定性**：相同 `(FV, source, customize, fragments)` 必产出相同 fingerprint；
+2. **传递性**：若 `Fingerprint(a)` 命中 CI 缓存，可直接复用上次编译产物，无需重新执行三阶段流水；
+3. **诊断性**：当某次 CI 发现产物漂移时，比对四个输入哈希即可立判漂移源（FV 漂、源码漂、定制漂、片段漂）；
+4. **不变性**：fingerprint 仅依赖编译输入与片段内容，不依赖编译机的时钟、用户名、环境变量等非业务因素——即便在不同时段不同机器上重新构建，同输入仍产出同 fingerprint。
+
+工程上 fingerprint 写入 `files-manifest.json` 的每条产物记录，作为后续 §3.2.10、§3.2.12 的依据。
+
+### 3.2.10 增量编译的特征向量差分
+
+大型项目下批量编译（如 8 个智能体 × 4 个 IDE 平台 = 32 个产物）的总开销可通过"特征向量差分"显著降低：
+
+1. **维护上次编译时的快照**：`compile-snapshot.json` 中记录上次编译时每个智能体的 `(FV, source_hash, customize_hash, fragments_hash, fingerprint)` 五元组；
+2. **本次编译入口判断**：对每个智能体 `a`，先计算本次的 `Fingerprint_new(a)`；若 `Fingerprint_new(a) == Fingerprint_old(a)`，命中缓存，直接复用上次产物，跳过三阶段流水；
+3. **特征差分计算**：未命中时进一步对比 `FV_new vs FV_old`，计算 `delta_FV = FV_new △ FV_old`（对称差）；
+4. **按 delta 重编译**：仅对 `delta_FV` 中变化的特征分量重新加载对应片段并重新拼接 XML 的对应段落，其余段落从上次产物中按片段标识复制；
+5. **复杂度退化**：最坏 O(n) 完全等同于全量重编译；典型场景（用户仅修改了某智能体的若干 prompt）退化为 O(|delta|)，与变更点规模线性相关而非智能体总数。
+
+该机制与 §3.2.5 的 Map 片段缓存正交——Map 缓存解决"同一次编译过程中片段不重读"，本节解决"跨编译过程的智能体级缓存"。
+
+### 3.2.11 定制 ∩ 模板冲突的代数检测
+
+§3.1.1 已给出"先模板后合并"路径的反证：定制中的字面 `{{}}` 会被模板引擎误解析。但在三阶段顺序固定（定制→模板→XML）的前提下仍存在一类隐患——定制数据中的某字段名恰好与模板可注入字段集合存在交集（如用户定制 metadata 字段 `project_name`，与全局模板变量 `{{project_name}}` 同名），此时阶段 1 合并后字段已固定，阶段 2 模板引擎无变量可替换，但读者审阅产物时会误以为这是模板未替换的残留。
+
+为此本方案在阶段 1 入口与阶段 2 入口之间插入"代数冲突检测"步骤：
+
+设：
+
+- `F_customize(a)` = 用户定制数据中所有字段名的集合（含嵌套字段，扁平化后的点路径）；
+- `V_template(a)` = 阶段 2 模板引擎可注入的变量名集合（从 `install_config.questions` 抽取）；
+
+冲突判定：
+
+```
+若 F_customize(a) ∩ V_template(a) ≠ ∅
+则记录冲突字段集合并抛 CustomTemplateNamespaceCollision 错误
+```
+
+抛错信息包含冲突字段名、定制来源行号、模板变量定义行号，便于用户立即定位与修正（重命名定制字段或模板变量之一）。该机制使"合并产物中残留 `{{var}}` 字符串"的隐患在编译期被截获，而非在 IDE 加载产物时才暴露。
+
+### 3.2.12 跨 agent 片段共享层
+
+观察 v1.12.0 工作树 8 个智能体的特征向量分布：
+
+| 智能体 | FV 类型摘要 | 实际加载的片段集合 |
+| --- | --- | --- |
+| analyst | (E={exec}, T=∅, D=∅, A=∅, M=0) | 通用 + `handler-exec.txt` |
+| qa | (E={exec}, T=∅, D=∅, A=∅, M=0) | 通用 + `handler-exec.txt` |
+| ux-designer | (E={exec}, T=∅, D=∅, A=∅, M=0) | 通用 + `handler-exec.txt` |
+| dev | (E={exec}, T={tmpl}, D=∅, A=∅, M=1) | 通用 + handler-exec + handler-tmpl + prompts-wrapper |
+| pm | (E={exec}, T={tmpl}, D=∅, A=∅, M=1) | 同 dev |
+| architect | (E={exec}, T={tmpl}, D={data}, A=∅, M=1) | 通用 + handler-exec + handler-tmpl + handler-data + prompts-wrapper |
+| sm | (E={exec}, T={tmpl}, D=∅, A=∅, M=1) | 同 dev |
+| po | (E={exec}, T={tmpl}, D={data}, A={action}, M=1) | 通用 + handler-exec/tmpl/data/action + prompts-wrapper |
+
+FV 等价的智能体（如 analyst/qa/ux-designer 三者）在阶段 3 拼接出的"激活块段落"完全一致——区别仅在 metadata、persona、menu 具体内容。本方案据此引入跨 agent 片段共享层：
+
+1. **激活块缓存键**：以 `HASH(canonicalize(FV(a)))` 为 key，存储该 FV 对应的激活块片段拼接产物；
+2. **首次编译生效**：阶段 3 拼接激活块时先查 key；命中即复用，跳过片段加载与拼接；未命中则正常加载片段、拼接后写入缓存；
+3. **缓存生命周期**：与 Map 片段缓存（§3.2.5）共生灭——所有失效路径同样适用于本层；
+4. **效果**：v1.12.0 工作树下 8 智能体仅产生 4 种不同的激活块拼接产物（FV 等价类数）；当智能体数量进一步增长时，激活块拼接开销按等价类数（远小于智能体数）线性增长。
+
+# 4、与第1部分所述的现有技术相比，本发明有何优点
+
+| 维度 | 全量模板替换 | 部分模板化（手工分片） | 开源 AI 框架编译流程（BMAD-METHOD 等） | 本方案 | 指标改善方向 |
+| --- | --- | --- | --- | --- | --- |
+| XML 体积 | 每智能体注入全部处理器段落 | 手工选择性分片，作者负责维护 | 部分按需注入但未基于形式化特征向量 | 按 `FV(a)` 自动注入 | 简单智能体可大幅压缩，复合智能体接近全量 |
+| 单次编译耗时 | 模板字符串大、替换正则多 | 中间值 | 未披露 | 仅渲染所需片段 + Map 缓存 | 当前 v1.12.0 工作树 8 智能体批量编译可在亚秒级完成 |
+| 批量编译 I/O 次数 | 每智能体重读所有片段 | 部分手工缓存 | 未披露 | Map 缓存首次加载后命中 | 公共片段读 1 次后被所有智能体复用 |
+| 定制粒度 | 整段替换 | 字段级 | 字段级（无显式按 ID 去重披露） | 按字段类型差异化（对象深度合并 / 数组追加 / 可选按 ID 去重） | 最细粒度可覆盖到单条 prompt |
+| 定制 / 模板时序冲突 | 易发生 | 部分可控 | 未披露反证 | 严格三阶段隔离 + 代数必要性反证 | 完全消除 |
+| 编译产物确定性指纹 | 无 | 无 | 无 | `HASH(FV ‖ source ‖ customize ‖ fragments)` | CI 防漂移 / 产物分发去重可证 |
+| 增量编译 | 无 | 无 | 无 | 基于 FV 差分的 `delta_FV` 重编译 | O(n) 退化为 O(|delta|) |
+| 定制 ∩ 模板字段冲突检测 | 无 | 无 | 无 | `F_customize ∩ V_template ≠ ∅` 抛错 | 编译期截获隐性冲突 |
+| 跨 agent 片段共享 | 无 | 无 | 无 | FV 等价类共享激活块拼接产物 | 拼接开销按等价类数（而非智能体数）线性增长 |
+
+## 综合有益效果
+
+| 维度 | 量化效果 | 数据来源 |
+| --- | --- | --- |
+| 性能 | 单次编译开销集中在 YAML 解析与字符串拼接，无重型依赖（不引入 Handlebars / EJS）；批量编译时 Map 片段缓存使通用片段读 1 次即被所有智能体复用 | §3.2.5、§4 表前三行 |
+| 可靠性 | 三阶段架构（定制合并 → 模板替换 → XML 生成）的严格串行隔离消除"定制中的 `{{}}` 被模板引擎误解析"和"模板变量被定制覆盖"两类时序冲突；multi 格式菜单递归遍历已实现，深度上限作为防御异常输入的扩展模式 | §3.1、§3.2.3、§3.2.6 |
+| 易用性 | YAML 声明式输入门槛低，自动得到可执行 XML 输出；按字段类型差异化合并使用户能用最小 YAML 片段覆盖特定字段，而非复制整段 | §3.2.2 |
+| 可维护性 | 激活块按片段独立组织，新增一种处理器只需追加一个 `handler-xxx.txt` 片段并在 AgentAnalyzer 中加入对应识别规则，无需改动模板渲染或合并逻辑；`clearCache` 当前以进程冷启动失效为基础路径，文件 mtime 监测与 CLI flag 触发作为热重载场景的扩展模式 | §3.2.4、§3.2.5 |
+
+# 5、本发明的关键点和欲保护点是什么？
+
+1. **三阶段编译流水线（代数必要性反证支撑）**：定制合并 → 模板替换 → XML 生成的严格串行执行时序，§3.1.1 三种改序破坏的不变量构成代数必要性反证。
+2. **特征向量驱动的激活块按需组装**：以五元组 `FV(a) = (E, T, D, A, M)` 形式化定义特征向量，`AgentAnalyzer` 扫描 menu 抽取 FV，`ActivationBuilder` 据此选择性加载片段（§3.2.4、§3.2.8）。
+3. **分字段类型的定制化合并策略**：对象类型深度合并（metadata）、数组类型追加合并（menu、critical_actions、memories）、按 ID 去重合并（prompts）。
+4. **Map-based 片段缓存与 clearCache 热重载机制**：使用 Map 存储已加载片段内容，批量编译时避免重复文件 I/O，支持 mtime / CLI flag / 冷启动三种缓存失效路径。
+5. **编译确定性指纹（Reproducible Build）**：`Fingerprint(a) = SHA-256(canonicalize(FV) ‖ HASH(source) ‖ HASH(customize) ‖ HASH(fragments))`；同输入必同输出，可用于 CI 防漂移、产物分发去重、漂移源逐项诊断（§3.2.9）。
+6. **基于特征向量差分的增量编译**：维护编译快照中每个智能体的 FV、源码哈希、定制哈希、片段哈希、指纹；本次编译先比 fingerprint，命中即复用；未命中按 `delta_FV = FV_new △ FV_old` 仅重编差分分量（§3.2.10）。
+7. **定制 ∩ 模板冲突的代数检测**：在阶段 1 与阶段 2 之间检测 `F_customize ∩ V_template`，非空即抛 `CustomTemplateNamespaceCollision` 错误，编译期截获隐性冲突（§3.2.11）。
+8. **跨 agent 片段共享层**：FV 等价类共享激活块拼接产物（以 `HASH(canonicalize(FV))` 为缓存键），拼接开销按等价类数而非智能体数线性增长（§3.2.12）。
+
+## 5.5 建议权利要求方向（初稿，供代理人参考）
+
+**独立权利要求 1（方法）**：
+
+一种声明式 AI 智能体定义的编译方法，其特征在于，包括以下严格串行的三个阶段：
+
+- 阶段 A（定制合并）：读入智能体的声明式 YAML 与用户定制数据，按字段类型分别采用对象深度合并、数组追加、按标识符去重合并中的至少两种策略合并到统一中间结构，并在阶段结束时将定制字段从待处理数据中移除；
+- 阶段 B（模板替换）：仅基于阶段 A 输出的纯净模板变量集合，对中间结构中的占位符进行替换；
+- 阶段 C（基于特征分析的按需 XML 生成）：先对所述中间结构的菜单字段做静态扫描，得到该智能体实际使用的处理器类型集合；再仅加载并拼接所述集合对应的激活块片段文件，生成目标 XML 产物。
+
+**从属权利要求 2**：
+
+根据权利要求 1 所述的方法，其中所述静态扫描包含对嵌套菜单结构（multi 格式）的递归遍历，并在递归入口处设置深度上限阈值；达到所述阈值时截断处理并记录日志，不抛出异常。
+
+**从属权利要求 3**：
+
+根据权利要求 1 所述的方法，其中所加载的激活块片段文件使用键值映射（Map）缓存于内存中，其失效条件至少包含：(a) 片段文件的修改时间晚于缓存中记录的加载时间；(b) 显式命令行参数请求清空缓存；(c) 进程冷启动；批量编译多个智能体时缓存命中的片段不重复读取磁盘。
+
+**从属权利要求 4**：
+
+根据权利要求 1 所述的方法，其中阶段 A 的定制合并策略对 prompts 数组采用按 id 字段去重合并：定制中的 prompt 条目若与基础中存在同 id 条目，则以定制条目完全替换基础条目；否则追加至基础数组末尾。
+
+**两级合并语义的法律边界（针对 §3.2.2 prompts 双语义）**：
+
+- **独立权利要求 1 的保护对象**是"按字段类型差异化合并"这一架构决策本身——只要实施例中存在"两种及以上对应不同字段类型的合并策略"（如对象用深度合并 + 数组用追加合并，或对象深度合并 + 数组追加 + 按 id 去重），即落入权利要求 1 保护范围，与具体策略种类无关；
+- **从属权利要求 4 的保护对象**是"按 id 去重合并"的具体策略实现（替换语义而非补丁语义）。当前工程版本中 prompts 采用数组追加策略（§3.2.2 中的"当前代码实现"），不落入从属权利要求 4 的保护范围，但仍落入独立权利要求 1（metadata 深度合并 + critical_actions 追加合并这两种已构成"至少两种策略"）；
+- **后续版本将 prompts 升级至按 id 去重合并**（§3.2.2 中的"优选实施例"），落入从属权利要求 4 的保护范围。当前实现与升级实现之间的过渡对法律保护范围不构成断裂——独立权利要求 1 持续覆盖。
+
+**从属权利要求 5**：
+
+根据权利要求 1 所述的方法，进一步包括对每个智能体计算编译确定性指纹的步骤：所述指纹由密码学哈希函数对以下四项的拼接进行计算——(a) 阶段 C 静态扫描所得特征向量的规范化序列化结果；(b) 智能体声明式 YAML 源文件的规范化序列化结果；(c) 用户定制数据的规范化序列化结果；(d) 阶段 C 加载的全部激活块片段文件清单及各自内容哈希；所述指纹写入安装清单的产物记录字段，用于跨编译过程的产物复用与漂移诊断。
+
+**从属权利要求 6**：
+
+根据权利要求 1 所述的方法，进一步包括基于特征向量差分的增量编译步骤：维护上一次编译的特征向量与其规范化序列化的指纹（所述指纹的具体形式可独立采用任意密码学哈希函数对所述特征向量的规范化序列化结果计算，亦可选择性地额外拼接源哈希 / 定制哈希 / 片段哈希以构成更强的漂移诊断能力——后者作为本权利要求与权利要求 5 的可组合实施例）；本次编译先比对指纹，命中即直接复用上次产物；未命中时进一步计算 `delta_FV` 为本次与上次特征向量的对称差，仅对 `delta_FV` 中变化的分量重新执行片段加载与产物段落拼接，其余段落按片段标识从上次产物中复制。本权利要求**独立于权利要求 5**——即便未实施权利要求 5 的"四项拼接"具体形式，仅以特征向量自身的指纹做差分匹配亦构成本权利要求保护范围。
+
+**从属权利要求 7**：
+
+根据权利要求 1 所述的方法，进一步包括定制与模板的代数冲突检测步骤：在阶段 A 完成后与阶段 B 开始前，求 `F_customize` 与 `V_template` 的交集，其中 `F_customize` 为定制数据中所有字段名（含嵌套字段扁平化后的路径）的集合，`V_template` 为阶段 B 模板引擎可注入的变量名集合；当所述交集非空时记录冲突字段并抛出冲突错误，错误信息包含冲突字段名、定制来源位置标识与模板变量定义位置标识。
+
+**从属权利要求 8**：
+
+根据权利要求 1 所述的方法，进一步包括跨智能体片段共享层步骤：以"特征向量的规范化序列化哈希"为缓存键，存储该特征向量对应的激活块片段拼接产物；阶段 C 拼接激活块时先查询所述缓存键，命中即直接复用拼接产物；未命中则正常加载片段、拼接后写入所述缓存；多个智能体若特征向量等价则共享同一拼接产物。
+
+**保护范围边界**：本方法不限定 YAML/XML 之外的序列化格式（JSON/TOML 等等效替代）、不限定特定模板语法（Mustache 风格、Handlebars 风格、自实现正则均可），亦不限定 handler 类型的具体集合（exec/tmpl/data/action 为优选实施例）；不限定指纹所用的密码学哈希函数（SHA-256 为优选实施例，等价强度的哈希函数为等效替代）；不限定差分计算的具体对称差表达方式。
+
+# 6、针对第3部分的技术方案，是否还有别的替代方案同样能完成发明目的？
+
+| 替代方案 | 核心做法 | 与本方案对比 |
+| --- | --- | --- |
+| 一、全量模板 + 条件注释删除 | 在完整模板中用 `<!-- if:exec -->...<!-- endif -->` 包裹每个处理器段落，编译时按特征结果删除不需要的段落 | 省去片段文件管理，但模板文件膨胀到 800+ 行难维护；条件注释解析仍是字符串操作，可读性差 |
+| 二、JSON Patch 标准合并 | 定制合并采用 RFC 6902 的 add/remove/replace 操作符 | 提供标准化合并语义，但需用户按 JSON Patch 格式编写定制数据，使用门槛高；对中文非程序员用户不友好 |
+| 三、XSLT 转换 | 用 XSLT 模板把 YAML（转 XML 后）变换为目标 XML | 转换能力强但学习成本高，社区生态弱；对 Node.js 项目需引入 XSLT 处理库（增加 200KB+） |
+
+# 7、与代表性现有技术的逐项对照
+
+| 关键点 | 全量模板替换 | BMAD-METHOD 编译流程 | 通用编译器优化（DCE/常折叠） | Bazel/Buck 增量构建 | 本方案 |
+| --- | --- | --- | --- | --- | --- |
+| 三阶段严格串行（含代数必要性反证） | ✗ | △（顺序未声明反证） | ✗ | ✗ | ✓ |
+| 特征向量形式化（五元组 + 偏序/等价） | ✗ | ✗（仅工程态 `usedAttributes`） | △（IR 元数据但与本场景无对应） | ✗ | ✓ |
+| 按需激活块组装 | ✗（全量） | △（部分） | ✗ | ✗ | ✓ |
+| 分字段类型合并策略 | ✗ | △（追加合并） | ✗ | ✗ | ✓ |
+| Map 片段缓存 + 多失效路径 | ✗ | ✗ | ✗ | ✓（缓存但非片段级） | ✓ |
+| 编译确定性指纹（Reproducible Build） | ✗ | ✗ | ✗ | ✓（输入哈希但非 FV 维度） | ✓ |
+| 增量编译特征向量差分 | ✗ | ✗ | ✗ | ✓（按输入差分但非 FV 差分） | ✓ |
+| 定制 ∩ 模板字段冲突检测 | ✗ | ✗ | ✗ | ✗ | ✓ |
+| 跨 agent 片段共享层（FV 等价类） | ✗ | ✗ | ✗ | △（远程缓存但非 FV 等价类） | ✓ |
+
+可见关键点 1、2、7、8、9 在所列代表性现有技术中均未披露；关键点 5、6 在 Bazel/Buck 等通用构建系统中有等价能力但与 AI 智能体特征向量场景未形成对应；关键点 3、4 在 BMAD-METHOD 中有部分披露。
+
+# 附图说明
+
+**附图1 — 三阶段编译流水线整体流程图**
+
+![附图1 - 三阶段流水线](media/doc3_fig1.png)
+
+YAML 输入 → 阶段 1 定制合并 → 阶段 2 模板替换 → 阶段 3 XML 生成 → 最终输出（含 frontmatter 与可执行 XML）的完整流程。
+
+**附图2 — 智能体特征分析与激活块按需组装示意图**
+
+![附图2 - 特征分析与按需组装](media/doc3_fig2.png)
+
+`AgentAnalyzer` 扫描 menu 得到 `usedAttributes` 特征集合与 `hasPrompts` 标志，`ActivationBuilder` 据此选择性加载 `handler-exec.txt`、`handler-tmpl.txt` 等片段。
+
+**附图3 — 分字段类型定制合并策略对比图**
+
+![附图3 - 分字段合并策略](media/doc3_fig3.png)
+
+分别展示深度合并（metadata）、整体替换（persona）、追加合并（critical_actions / menu）、按 ID 去重合并（prompts）等策略的数据流。
+
+**附图4 — Map 缓存与 clearCache 触发**
+
+![附图4 - Map 缓存与 clearCache 触发](media/doc3_fig4.png)
+
+片段读取请求 → Map 缓存命中判定 → 文件 I/O 或缓存返回；`clearCache` 由 mtime 变更检测、CLI `--no-cache` flag、Node 进程冷启动三类条件触发缓存失效。
+
+
+## 附图源码（Mermaid，供绘图工程师参考重绘）
+
+**附图1 — 三阶段流水线**
+
+```mermaid
+flowchart LR
+    A[(原始 YAML)] --> S1[阶段1: 定制合并]
+    C[(customize.yaml<br/>answers)] --> S1
+    S1 -->|合并后 YAML<br/>+ 模板变量集| S2[阶段2: 模板替换]
+    S2 -->|纯净 YAML| S3[阶段3: XML 生成]
+    S3 --> ANA[AgentAnalyzer<br/>静态特征分析]
+    ANA -->|usedAttributes Set<br/>hasPrompts 标志| AB[ActivationBuilder<br/>按需组装]
+    AB -->|缓存命中?| MC[(Map 片段缓存)]
+    AB --> OUT[(编译产物<br/>frontmatter + XML)]
+```
+
+**附图2 — 特征分析与按需组装**
+
+```mermaid
+flowchart TB
+    subgraph IN[输入 YAML]
+        M[menu 数组]
+    end
+    M --> SC[递归扫描:<br/>exec/tmpl/data/action]
+    SC --> US["usedAttributes Set<br/>例: {exec, tmpl}"]
+    SC --> HP["hasPrompts: true"]
+    US --> AB[ActivationBuilder]
+    HP --> AB
+    AB --> L1[加载通用片段:<br/>activation-init<br/>menu-handlers<br/>activation-rules]
+    AB -->|usedAttributes 包含 exec| L2[+ handler-exec.txt]
+    AB -->|usedAttributes 包含 tmpl| L3[+ handler-tmpl.txt]
+    AB -.usedAttributes 不含 data.-> X1[跳过 handler-data.txt]
+    AB -.usedAttributes 不含 action.-> X2[跳过 handler-action.txt]
+    AB -->|hasPrompts == true| L4[+ prompts-wrapper.txt]
+    L1 --> AS[XML 拼接输出]
+    L2 --> AS
+    L3 --> AS
+    L4 --> AS
+```
+
+**附图3 — 分字段合并策略**
+
+```mermaid
+flowchart TD
+    subgraph IN[输入]
+        B[(base.yaml)]
+        C[(customize.yaml)]
+    end
+    B --> M1[metadata 深度合并]
+    C --> M1
+    B --> M2[persona 整体替换]
+    C --> M2
+    B --> M3[critical_actions 追加]
+    C --> M3
+    B --> M4[menu 追加]
+    C --> M4
+    B --> M5[prompts 按 ID 去重]
+    C --> M5
+    M1 --> OUT[(合并结果)]
+    M2 --> OUT
+    M3 --> OUT
+    M4 --> OUT
+    M5 --> OUT
+```
+
+**附图4 — Map 缓存与 clearCache 触发**
+
+```mermaid
+flowchart LR
+    R[读取片段请求] --> Q{Map 缓存命中?}
+    Q -->|是| GET[(从 Map 取出)]
+    Q -->|否| RF[读取文件]
+    RF --> SET[(存入 Map)]
+    SET --> GET
+    GET --> USE[返回片段内容]
+    subgraph CLR[clearCache 触发]
+        T1[mtime 变更检测]
+        T2[CLI --no-cache flag]
+        T3[Node 进程冷启动]
+    end
+    T1 -.失效.-> Q
+    T2 -.失效.-> Q
+    T3 -.自然失效.-> Q
+```