@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_1_/351/235/242/345/220/221AI/346/231/272/350/203/275/344/275/223/347/232/204/345/244/232/351/200/232/351/201/223/344/276/235/350/265/226_20260318.md

@@ -0,0 +1,483 @@
+**技术交底书**
+
+**交底书名称：**一种面向AI智能体的多通道依赖解析方法及系统
+**本专利发明人：**刘二杨
+**技术问题联系人：**刘二杨
+**联系人电话：**（待填写）
+**E-MAIL：**liueryang@yljr.com
+
+# 该发明所属技术领域
+
+本发明涉及计算机软件技术领域，具体涉及一种面向AI智能体开发框架中多类型制品（智能体定义、工作流、任务、技能等）之间跨模块依赖关系的自动解析方法及系统。
+
+# 术语解释
+
+| 术语 | 中文/英文全称 | 一句话定义 |
+| --- | --- | --- |
+| AI 智能体制品 | AI Agent Artifact | 智能体框架中可独立定义、安装、执行的配置单元，含 agent / workflow / task / skill |
+| AI IDE | AI Integrated Development Environment | 集成 AI 编程辅助能力的开发环境，如 Claude Code、Cursor 等，本方法的最终消费方 |
+| YAML 前置声明 | YAML Frontmatter | Markdown 文件头部以三横线分隔的 YAML 元数据区域 |
+| 主制品 | Primary Artifact | 用户显式选择安装的模块顶层制品（如某个 agent 或 workflow） |
+| 传递依赖 / 传递闭包 | Transitive Dependency / Closure | A 依赖 B、B 依赖 C 时 A 对 C 形成的间接依赖；从主制品出发递归展开后得到的全部依赖文件集合 |
+| 双源目录映射 | Dual-Source Mapping | 同一制品在开发源码目录（`src/`）与部署安装目录（`xiaoma/`）的路径映射关系 |
+| 命令引用 | Command Reference | Markdown 正文中以 `@task-`、`@agent-`、`@xiaoma-` 前缀书写的制品引用语法 |
+| XML 属性引用 | XML Attribute Reference | XML 标签 `exec=""`、`tmpl=""` 等属性中以路径或 token 表达的依赖声明 |
+| 占位符 | Placeholder | 路径中可被运行时替换的标记，本方案使用 `{project-root}` |
+| 制品 | Artifact | 框架中可独立编排和分发的逻辑单元，泛指 agent / workflow / task / skill / data |
+| 模块 | Module | 一组共享配置变量、目录约定与命名空间的制品集合，如 `core`、`xmc` |
+| 安装清单 | Manifest | 安装过程产出的元数据文件，记录每个产物的归属模块、类型、路径与哈希 |
+| SHA-256 | Secure Hash Algorithm 256-bit | 256 位密码学哈希函数，本框架在 manifest 中用其标识制品内容指纹 |
+| Zod | Zod Schema Library | TypeScript/JavaScript 运行时数据校验库，用于 agent YAML 的强类型校验 |
+| IR（中间表示） | Intermediate Representation | 四通道解析后产出的统一 `{from, dependency, type}` 元组 |
+| 短路告警 | Short-Circuit Warning | 检测到循环依赖时记录日志而不中断流程的容错策略 |
+
+# 1、详细介绍技术背景，并描述已有的与本发明最相近似的实现方案
+
+AI 驱动的软件开发框架通过定义多种制品类型组织开发流程。本框架（v1.12.0 工作树）当前包含 8 个智能体角色（位于 `src/xmc/agents/`）、27 个工作流（位于 `src/xmc/workflows/` 9 个分类目录下）、21 个任务模板（位于 `src/core/tasks/` 与 `src/xmc/tasks/`）。制品之间存在复杂引用：工作流可能引用另一模块的任务模板；智能体菜单命令可能指向跨模块的工作流；任务模板可能加载若干 CSV / JSON 数据文件。安装时必须把这些依赖一次性解析完整，否则运行时会因缺文件而中断。
+
+现有相近方案有三类：
+
+**方案一：基于包管理器的依赖解析**（npm、Maven、pip）。声明格式统一（package.json / pom.xml / requirements.txt），依赖图由包管理器维护。但AI智能体制品的依赖**散布在异构位置**：YAML前置声明的`dependencies`数组、Markdown正文中的`@task-name`/`@agent-name`命令引用、XML属性中的`exec="{project-root}/xiaoma/core/tasks/foo.md"`路径引用、相对路径引用、模板引用等多种位置和格式。传统包管理器读不到这些非标准声明。
+
+**方案二：基于静态分析的单遍扫描**。一次遍历所有文件、用正则提取引用关系。实现简单，但只能发现一阶引用——A 引用 B、B 引用 C 时，C 不会进入安装集；也无法处理同一制品在开发目录（`src/core/tasks/`）和部署目录（`xiaoma/core/tasks/`）路径不同的问题。
+
+**方案三：基于开源 AI 智能体框架（如 BMAD-METHOD）的安装器实现**。BMAD-METHOD（公开仓库 `bmad-code-org/BMAD-METHOD`，MIT 许可）作为本领域代表性开源方案，其安装器具备从 YAML 前置声明读取显式 `dependencies` 数组、按文件路径逐项复制到目标目录的能力，可视为方案二的特化实例。但其依赖识别仍**局限于单一通道（YAML 显式 `dependencies` 数组）**，对正文中的命令引用、XML 属性中的路径引用、`template` 字段引用、相对路径引用等**异构声明位置不识别**；其依赖闭包计算亦未对外披露置信度仲裁、三态分类、闭包指纹缓存、通道失效降级回退等机制。本方案在此类已有开源安装器的基础上，针对其依赖识别覆盖面、置信度仲裁、闭包复用等具体短板提出系统性改进。
+
+| 维度 | 包管理器方案 | 单遍扫描方案 | 开源 AI 框架安装器方案（如 BMAD-METHOD） |
+| --- | --- | --- | --- |
+| 声明格式 | 单一标准（package.json） | 单格式正则 | 单一通道（YAML `dependencies` 数组） |
+| 多通道协同 | 否 | 否 | 否（仅 YAML 显式声明） |
+| 传递依赖 | 是（包管理器内部维护） | 否 | 部分（仅显式声明的传递） |
+| 双源路径映射 | 否（不涉及） | 否 | 否（开发与部署路径未做类型敏感映射） |
+| 通道置信度仲裁 | 不涉及 | 否 | 否 |
+| 闭包指纹缓存 | 否 | 否 | 否 |
+| 防环 | 是（内置） | 否 | 部分（基于已展开路径去重） |
+
+# 2、现有技术的缺点是什么？针对这些缺点，说明本发明的目的
+
+| 现有缺陷 | 具体表现 | 本发明对应目的 |
+| --- | --- | --- |
+| 依赖声明格式单一化 | 现有方案只识别一种声明位置，散布在 YAML / 正文 / XML / 相对路径中的引用无法统一提取；本框架 v1.12.0 工作树 35 个主制品（8 agent + 27 workflow）下，单格式解析仅命中 YAML 显式依赖通道，对命令引用、模板引用、相对路径引用均不识别 | 提供多通道协同依赖提取，统一识别 4 类异构声明 |
+| 无法处理传递依赖 | 单遍扫描只发现直接引用，A→B→C 中 C 不进入安装集 | 第四遍递归扫描自动展开传递闭包 |
+| 双源路径映射缺失 | 开发目录`src/core/tasks/`与部署目录`xiaoma/core/tasks/`前缀不同；现有方案不具备映射能力，开发与生产环境的解析结果不一致 | 按依赖类型标识自动执行源路径→部署路径映射 |
+| 缺乏循环依赖防护 | 多模块场景下出现 A→B→C→A 时陷入无限递归 | 用集合数据结构追踪已处理文件，O(1) 防环 |
+
+本发明目的：提供一种多通道协同依赖解析方法，能同时识别 YAML 前置声明、命令语法、文件路径引用、模板引用等多种格式的依赖声明，自动计算传递依赖闭包，支持双源目录结构映射，并通过集合追踪机制防止循环依赖，保证安装集完整且无遗漏。
+
+# 3、本发明技术方案的详细阐述
+
+## 3.1 基本原理
+
+依赖解析的本质，是把异构声明位置中的"引用意图"翻译为统一的可寻址文件清单。本方案借鉴编译器前端的"扫描 → 解析 → 中间表示 → 闭包计算"范式：
+
+- 把**多种声明格式**（YAML前置、命令引用、路径引用、xiaoma路径、模板引用）抽象为带类型标签的**统一中间表示（IR）**，每条记录形如 `{from, dependency, type}`；
+- 把**双源路径映射**抽象为类型敏感的路径解析器，对不同 IR 类型应用不同重写规则；
+- 把**传递依赖**抽象为图上的可达性闭包问题，用集合防环保证 O(n) 时间复杂度内收敛。
+
+四个独立阶段串行执行：主制品收集 → 多通道依赖提取 → 路径解析与双源映射 → 传递闭包计算。
+
+## 3.2 详细的技术方案
+
+### 3.2.1 系统整体架构
+
+系统由 5 个模块组成：依赖解析器（`DependencyResolver`，统一调度）、主制品收集器（`PrimaryFileCollector`）、多格式依赖解析器（`MultiFormatParser`）、路径解析与映射器（`PathResolver`）、传递依赖计算器（`TransitiveDependencyResolver`）。各模块由依赖解析器按四遍扫描顺序串行调度。
+
+对外入口的输入与输出契约：该入口接收三个参数——**框架根目录路径**（包含 `src/` 与 `modules/` 子目录的根路径）、**用户选择的模块列表**（字符串数组，如 `["core", "xmc"]`，缺省时仅处理基础集）、**可选项**（包含试运行开关 dryRun、详细日志开关 verbose、最大递归深度 maxDepth 等控制项）。入口异步返回一组结构化结果，包括：主制品文件清单（条目形如 `{filePath, type, module, fileName}`）、直接依赖关系列表（条目形如 `{from, dependency, type, resolvedPath}`）、传递依赖关系列表（在直接依赖结构基础上附加 hops 跳数字段）、按制品类型分组的最终安装文件清单（agents / tasks / tools / templates / data / other 六类）、缺失依赖报告（条目形如 `{requestedBy, target, reason}`），以及解析统计信息字段（文件数、I/O 次数、最大与平均深度、被短路的循环计数等可观测指标），供调用方进一步生成安装清单与诊断报告。
+
+**实现位置**：`tools/cli/installers/lib/core/dependency-resolver.js` 第 11 行 `class DependencyResolver` 至第 67 行 `resolve()` 主方法（文件总长 743 行）。
+
+### 3.2.2 第一遍扫描：主制品收集
+
+输入：用户选择的模块列表（如 `["core", "xmc"]`）和框架根目录路径。处理步骤：
+
+1. 始终将 `core` 模块纳入基础集；
+2. 对每个模块，扫描其 `agents/` 与 `tasks/` 子目录，收集 `.md` 文件；
+3. 过滤：对每个候选文件检查内容中是否包含 `localskip="true"` 属性，若存在则跳过（仅用于Web端，不参与本地安装）；
+4. 输出：结构化数组，每条 `{filePath, type:"agent"|"task", module, fileName}`。
+
+**实现位置**：`tools/cli/installers/lib/core/dependency-resolver.js` 第 69-143 行 `collectPrimaryFiles()` 方法。
+
+### 3.2.3 第二遍扫描：多通道协同依赖提取
+
+对第一遍收集到的所有主制品文件，逐一读取内容，在**同一遍扫描中四个通道协同**提取依赖（每个文件读取一次后，四个通道依次对该文件内容执行匹配，输出汇入统一 IR 集合；通道之间相互独立、可任意拓展）：
+
+| 通道 | 命中位置 | 正则/解析逻辑 |
+| --- | --- | --- |
+| A. YAML 前置声明 | Markdown 头部 `---` 区块 | `/^---\r?\n([\s\S]*?)\r?\n---/`，并先把反引号包裹值改写为双引号（`yamlContent.replaceAll(/: \`([^\`]+)\`/g, ': "$1"')`），解决非标准 YAML 兼容问题 |
+| B. 命令引用 | Markdown 正文 | `/@(task-\|agent-\|xiaoma-)([a-z0-9-]+)/g`；并用 `/xiaoma\/(core\|xmc\|cis)\/(agents\|tasks)\/([a-z0-9-]+)/g` 匹配 xiaoma 路径格式的模块内引用 |
+| C. 文件路径引用 | 单/双引号字符串与 XML 属性 | `/['"](\.\.\/[^'"]+\.(md\|yaml\|yml\|xml\|json\|txt\|csv))['"]/g`；XML 属性走 `/exec="([^"]+)"/g` 与 `/tmpl="([^"]+)"/g`；含 `{project-root}` 占位符的路径先去除占位符前缀再记录 |
+| D. 模板引用 | YAML 前置声明 `template` 字段 | 直接读取，字符串或数组两种格式都支持 |
+
+四通道输出汇入统一的依赖集合，每条记录形如 `{from, dependency, type}`，type ∈ `{explicit, command, file, xiaoma-path, template}`。
+
+一个典型的 YAML 前置声明依赖样例：
+
+```yaml
+---
+type: workflow
+template: ../templates/prd-template.md
+dependencies:
+  - "{project-root}/xiaoma/core/tasks/elicit.md"
+  - "{project-root}/xiaoma/xmc/workflows/2-plan-workflows/create-prd/data/*.csv"
+  - exec: "{project-root}/xiaoma/xmc/agents/po.md"
+---
+```
+
+**实现位置**：`tools/cli/installers/lib/core/dependency-resolver.js` 第 146-287 行 `parseDependencies()` 方法，覆盖四通道正则匹配与统一 IR 汇聚。
+
+### 3.2.4 第三遍扫描：路径解析与双源映射
+
+对第二遍提取的每条记录，按 type 标识应用不同的路径解析策略：
+
+- **explicit / file**：先判断是否含 `{project-root}` 前缀。若含，去除前缀后按 xiaoma 路径规则解析——`core` 模块直接映射到 `xiaomaDir/core/`，其他模块映射到 `xiaomaDir/modules/{module}/`。若为 Glob 通配（含 `*`），提取基础路径和匹配模式，通过 glob 库在对应目录执行文件匹配。不含 `{project-root}` 时按相对路径处理，以来源文件所在目录为基准计算绝对路径；
+- **command**：解析 `@task-{name}` 在 `core` / `xmc` / `cis` 三个模块的 `tasks/` 下查找 `{name}.md`；`@agent-{name}` 在 `agents/` 下查找；`xiaoma/{module}/{type}/{name}` 直接映射。查找采用优先级遍历，找到即返回；
+- **xiaoma-path**：去除 `xiaoma/` 前缀后，`core/` 开头直接拼接到框架根目录；`xmc` 开头映射到 `src/xmc/`（xmc 作为主模块直接位于 `src/` 下）；其他模块映射到 `modules/{module}/`；
+- **template**：处理逻辑与 explicit 类似，额外处理 `{project-root}/xiaoma/` 前缀组合。
+
+为便于审查员速查，五类 IR 的"输入路径前缀 → 输出部署路径"映射规则汇总如下：
+
+| IR type | 输入路径前缀样例 | 模块判定 | 输出部署路径 |
+| --- | --- | --- | --- |
+| explicit / file | `{project-root}/xiaoma/core/...` | `core`（主模块） | `xiaomaDir/core/...` |
+| explicit / file | `{project-root}/xiaoma/{mod}/...` | `mod ≠ core, xmc` | `xiaomaDir/modules/{mod}/...` |
+| explicit / file | `../templates/...`（相对路径） | 沿用来源文件目录 | 来源目录 + 相对路径 |
+| explicit / file | `{project-root}/xiaoma/.../*.csv` | 含 glob 通配 | 基础路径 + glob 库匹配 |
+| command | `@task-{name}` / `@agent-{name}` | 跨 core/xmc/cis 优先级查找 | 命中模块的 `tasks/` 或 `agents/` 下 |
+| command | `xiaoma/{mod}/{type}/{name}` | 直接命中模块 | `{mod}` 下对应 `{type}` 子目录 |
+| xiaoma-path | `xiaoma/core/...` | `core`（主模块） | `xiaomaDir/core/...` |
+| xiaoma-path | `xiaoma/xmc/...` | `xmc`（主模块） | `src/xmc/...` |
+| xiaoma-path | `xiaoma/{mod}/...` | `mod ≠ core, xmc` | `modules/{mod}/...` |
+| template | `../templates/foo.md`（相对） | 沿用来源文件目录 | 来源目录 + 相对路径 |
+| template | `{project-root}/xiaoma/...` | 同 explicit 规则 | 复用 explicit 输出 |
+
+#### 类型敏感映射 vs 统一映射的反方案对比
+
+若采用"统一映射规则"——即不区分 IR 类型、对所有依赖均按同一套规则解析——则下列工程场景下会产生错误结果：
+
+| 场景 | 统一映射方案的错误结果 | 本方案的正确处理 |
+| --- | --- | --- |
+| `core` 模块的 task：`{project-root}/xiaoma/core/tasks/elicit.md` | 错误地按"modules/前缀"规则拼接为 `xiaomaDir/modules/core/tasks/elicit.md`（实际不存在） | type=`explicit` 触发"core 直映射"规则，正确解析到 `xiaomaDir/core/tasks/elicit.md` |
+| 命令引用 `@task-create-prd` | 无规则可匹配，识别失败（统一规则只认识具体路径） | type=`command` 触发跨模块优先级查找，命中 `xmc/tasks/create-prd.md` |
+| 模板字段 `template: ../templates/prd.md`（相对路径） | 按"绝对路径"规则解析，前缀拼接错误 | type=`template` 以来源文件目录为基准做相对路径计算 |
+| xmc 主模块路径 `xiaoma/xmc/agents/po.md` | 按"modules/前缀"规则解析为 `modules/xmc/agents/po.md`（与 `xmc` 作为主模块不带 `modules/` 前缀的部署约定冲突） | type=`xiaoma-path` 触发"xmc 主模块"规则，正确解析为 `src/xmc/agents/po.md` |
+
+可见五类 IR 的目标路径分布**不能由单一规则覆盖**——这是引入"类型敏感的路径重写器"作为权利要求保护点的工程必要性。
+
+**实现位置**：`tools/cli/installers/lib/core/dependency-resolver.js` 第 289-489 行 `resolveDependencyPaths()` 与 `resolveSingleDependency()` 方法。
+
+### 3.2.5 第四遍扫描：传递闭包计算
+
+对第三遍解析得到的所有直接依赖文件，逐一检查其自身是否也包含依赖声明。只处理 `.md`、`.yaml`、`.yml` 扩展名的文件（其他如 `.csv`、`.json` 不会包含制品引用）。对每个依赖文件：
+
+1. 复用第二遍的多格式解析逻辑提取子依赖；
+2. 复用第三遍的路径解析逻辑定位子依赖文件；
+3. 用 `processed` 集合记录已处理路径，保证每个文件只处理一次；
+4. 新发现的传递依赖如不在直接依赖集合中，加入传递依赖集合。
+
+取样测试样本：基于本框架 v1.12.0 工作树下 `src/xmc/agents/`（8 个智能体 YAML）与 `src/xmc/workflows/`（27 个工作流入口，分布于 1-analysis、2-plan-workflows、3-solutioning、4-implementation、5-full-pipeline、xiaoma-quick-flow 等 9 个分类目录下）共 35 个主制品的实际测量。每个主制品入口先以第一遍扫描收集，再分别在第二遍 / 第三遍 / 第四遍中走完整链路；统计每个主制品的依赖图最长路径长度（不含自身）。**v1.12.0 测量结果：传递闭包深度集中在 2-5 层**，最深路径出现在 dev agent → 4-implementation workflow → 子工作流 → task template → data CSV 的链路；传递依赖在总依赖中占据可观比例（具体比例随智能体复杂度变化），全部由系统自动发现，无需作者手动声明。该样本可由审查员在 v1.12.0 工作树上执行 `xiaoma install --dry-run` 复现。
+
+**实现位置**：`tools/cli/installers/lib/core/dependency-resolver.js` 第 547-663 行 `resolveTransitiveDependencies()` 方法。
+
+### 3.2.6 循环依赖防护机制
+
+在 8 智能体、3+ 嵌套引用层的实际框架中，模板改名、引用复制粘贴等场景容易引入 A→B→C→A 形式的循环依赖。本方案的防护采用两道措施：
+
+1. **集合防重**：在第四遍扫描中维护一个"已处理文件集合"记录已展开过的文件归一化路径。每次进入递归前先在集合中查询当前路径是否已存在，命中则直接返回，物理上不可能进入第二轮处理；
+2. **短路告警**：当某文件被列为依赖但其本身已存在于 `processed` 中时，记录一条告警日志而非抛出异常——避免单条循环导致整个安装中断。生产环境曾在一次 agent 模板改名（`agent-template` → `agent-base`）后出现 `agent-base` 引用 `agent-template`、而 `agent-template` 内残留对自身的引用导致 A→A 自环，依靠集合防环正常完成解析并提示用户清理残留引用。
+
+短路告警日志的字段规范（便于审查员复现与运维分析）：
+
+| 字段 | 含义 | 示例值 |
+| --- | --- | --- |
+| `cycle_node` | 触发短路的循环节点归一化绝对路径 | `/<xiaomaDir>/xmc/agents/dev.md` |
+| `from_chain` | 引发该次回环的来源链（箭头分隔的上游节点） | `pm.md → workflow-prd.md → dev.md` |
+| `depth_at_cycle` | 检测到回环时已进入的递归深度 | `3` |
+| `detection_phase` | 检测时机标识 | `transitive-bfs`（第四遍扫描中命中） |
+| `fallback_action` | 降级动作 | `continue`（跳过此节点，继续其余分支） |
+| `severity` | 告警级别 | `warn`（不阻塞安装） |
+
+防环检测算法的步骤性描述：
+
+1. **初始化**：维护一个**集合数据结构**作为"已展开节点"的快速查询索引（插入与命中查询均为 O(1)），同时维护一个待处理队列，初始时把所有直接依赖装入队列；输出累加器为传递依赖结果集，初始为空。
+2. **循环取队首**：每次从队首取出一条依赖记录，对其依赖路径执行**绝对路径归一化**得到查询键，确保不同路径写法（相对/绝对、含 `..`、含符号链接）映射到同一键值。
+3. **命中即短路**：若查询键已存在于已展开节点集合，即记录一条**循环短路告警日志**（日志字段遵循本节上文短路告警日志字段规范表给出的 `cycle_node` / `from_chain` / `depth_at_cycle` / `detection_phase` / `fallback_action` / `severity` 规范）并跳到下一条；该机制对自环（A→A）与互环（A→B→A）一并生效。
+4. **登记键**：键不在集合中即插入集合，物理上保证同一节点不可能进入第二轮处理。
+5. **扩展名过滤**：按扩展名筛选——仅 `.md` / `.yaml` / `.yml` 三种文件进入下钻解析，其他扩展名（如 `.csv` / `.json`）作为闭包叶节点直接计入安装集而不再递归（详见从属权利要求 3）。
+6. **下钻并复用上游解析逻辑**：对进入下钻的文件，读取其内容后**复用第二遍扫描的多通道解析逻辑**抽取子依赖，**复用第三遍扫描的路径解析逻辑**定位每条子依赖的绝对路径；对每条新发现的依赖，若不在已展开节点集合中即追加至传递依赖结果集并入队继续处理。
+7. **终止条件与收敛性**：循环以队列空为终止条件；已展开节点集合大小随处理进度单调增长，本身是 O(n) 收敛的天然不变量，无需额外计数器。
+
+**工程约束（防御性参数）**：
+- `MAX_TRANSITIVE_DEPTH`（默认 16）：递归展开的最大深度阈值，超过后记录警告并截断该分支；v1.12.0 实测最深 5 层，阈值留有约 3× 余量；
+- `MAX_FILES_PER_INSTALL`（默认 5000）：单次解析的最大文件数硬上限，达到后中止扫描并返回部分结果；当前 v1.12.0 工作树主制品 + 任务 + 模板 + 数据合计 50-100 文件量级，该阈值足以覆盖；
+- `processed.size` 自身随处理进度单调增长，是 O(n) 收敛的天然终止条件。
+
+### 3.2.7 跨通道置信度仲裁协议
+
+四通道协同提取虽能扩大覆盖面，但当**同一目标依赖被多个通道命中**时（实际工程中颇为常见——例如 YAML 前置声明里写了 `tmpl: ../templates/prd.md`、正文里又用 `@task-create-prd` 引用同一模板的上游任务、XML 属性里再次出现该路径），各通道给出的依赖记录可能在版本、模块归属、可选性上不一致。若不加仲裁直接合并入安装集，会出现"同一文件被引用四次、版本号四个不同写法"的歧义集合，向后传播到第三、四遍扫描甚至安装阶段。
+
+为此，每个通道在产出 IR 记录时附加一个二元组 `(source_channel, confidence)`：
+
+- `source_channel ∈ {yaml-frontmatter, command-ref, file-path, xml-attr, template-field}`；
+- `confidence ∈ [0.0, 1.0]`，按通道类型预设默认权重——`yaml-frontmatter`（0.95）> `xml-attr`（0.85）> `command-ref`（0.80）> `template-field`（0.75）> `file-path`（0.65）；预设权重可由模块 `module.yaml` 中的 `channelConfidenceOverrides` 字段按模块定制覆盖。
+
+仲裁规则按优先级表逐级裁决：
+
+| 优先级 | 判定条件 | 仲裁动作 |
+| --- | --- | --- |
+| 1 | 各通道给出的 dependency 解析后归一化路径**完全一致**且无版本字段差异 | 合并为单条 IR，`confidence` 取通道权重最大值 |
+| 2 | 归一化路径一致，但版本/可选性等附加字段不一致 | 以 `confidence` 最高的通道为准；记录一条 `merge-divergence` 审计日志（不阻塞） |
+| 3 | 归一化路径不一致但语义上属于同一资源（同 canonicalId） | 优先采用 `confidence` 最高路径；其他通道结果转入"次选候选集"供运行时回退 |
+| 4 | 通道之间出现严格冲突（互斥版本声明、可选/必选标记冲突） | 触发 `cross-channel-conflict` 错误，阻塞继续；错误信息包含全部冲突通道的来源链路 |
+
+仲裁后的 IR 集合附加一列 `arbitration_trace`，记录"被合并/被裁决/被降级"的全部通道来源，使后续阶段（路径解析、闭包计算、安装诊断）可追溯每个依赖的实际采纳来源。该机制相对单通道方案与并行多通道无仲裁方案的核心差异在于：**当多通道命中同一目标时，本方案以一个可证明的优先级表 + 二元置信度元组完成裁决，输出始终为唯一且可追溯的 IR 集合**。
+
+### 3.2.8 三态依赖分类与后续阶段严格度耦合
+
+依赖识别后并非"全部一视同仁"——按其来源声明的明确程度，本方案进一步将每条 IR 划入三态之一：
+
+| 依赖状态 | 判定来源 | 后续阶段严格度 |
+| --- | --- | --- |
+| `explicit`（显式） | YAML 前置声明 `dependencies` 数组中明文列出、`exec="{project-root}/..."` XML 属性精确路径、`template:` 字段直接字符串 | 严格匹配：路径解析阶段未命中即抛 `missing-explicit-dependency` 错误，阻塞安装；闭包阶段强制下钻 |
+| `inferred`（推断） | Markdown 正文中的命令引用 `@task-xxx` / `@agent-xxx`、相对路径引用 `../templates/foo.md`（基于来源文件目录推断） | 提示性匹配：路径未命中时记录 `inferred-resolution-warning` 警告但不阻塞；闭包阶段下钻；最终若仍未命中作为"软缺失"列入 `missingDependencies` 报告 |
+| `wildcard`（通配） | `*.csv` / `*.json` 等 Glob 模式、目录级 `data/*` 引用 | 宽松匹配：路径解析阶段允许零个或多个命中；闭包阶段不下钻具体叶节点；扫描阶段记录 `glob-expansion-snapshot` 用于审计 |
+
+三态机制使下游对依赖类型有不同期望：审查员/运维在排查"为何安装集缺了某文件"时，可立刻从依赖状态判定该缺失是"必须修复（explicit 缺失）"、"建议补全（inferred 缺失）"还是"无影响（wildcard 零命中）"，无需逐条人工溯源。
+
+### 3.2.9 跨阶段闭包指纹缓存
+
+本框架的实际使用场景中，依赖闭包计算并非"一次性"任务——CI 流水中可能在编译阶段、打包阶段、部署阶段对同一主制品集反复求闭包；同一开发者在本地 `xiaoma install` + `xiaoma upgrade` 之间也会重算多次。当主制品列表与源码均无变化时重复执行第二至第四遍扫描属于纯浪费。
+
+为此引入跨阶段闭包指纹缓存：
+
+1. **闭包指纹计算**：对每个主制品 `p`，将其传递闭包结果集 `C(p)` 按依赖记录的 `dependency` 字段做规范化排序（字典序）后拼接为 canonical 字符串 `serialize(C(p))`，再以 `SHA-256(serialize(C(p)))` 作为指纹 `fp(p)`；
+2. **覆盖文件集（covered_files）维护**：在第四遍闭包计算过程中，除返回 `C(p)` 之外，**同时记录该闭包实际下钻读取过的所有源文件归一化绝对路径集合 `covered(p) ⊆ V_source`**；该集合作为缓存条目的一部分与指纹同时落盘——缓存条目结构形如 `{key, fingerprint, C(p), covered_files: covered(p), built_at}`。这是失效判定能够"按文件"精确触发的前提；
+3. **缓存键设计**：缓存键 `key(p)` 由主制品归一化路径、`covered(p)` 中各文件 mtime 的最大值与主制品内容哈希拼接而成（mtime 仅用作快速失效判据，不作为唯一性根据，避免跨平台 mtime 漂移导致缓存误命中）；
+4. **缓存命中复用**：编译/打包/部署各阶段进入闭包计算前先查 `key(p)`；命中即直接返回 `C(p)`，跳过第二、三、四遍扫描；
+5. **失效路径**：① 主制品内容哈希变化；② **`covered(p)` 集合中任一文件 mtime 较缓存条目 built_at 更新**（精确按"该闭包实际依赖过的文件集"判定，而非全源码目录广覆盖）；③ 调用方传入 `forceRecompute=true`；④ 缓存条目年龄超过 `CACHE_TTL` 默认 7 天。
+
+**与 Bazel/Buck/Nix 等通用构建缓存的差异化**：通用构建系统的内容寻址缓存（Bazel `action cache key`、Nix `drv hash`）以"源文件清单 + 命令行 + 工具版本"为输入计算缓存键；本方法以"多通道 IR 集合的规范化序列化结果"为指纹输入——IR 集合是经过四通道协同识别、置信度仲裁、三态分类后的中间表示，与源文件清单**非同构**：同一源文件因仲裁结果不同可能产生不同 IR 条目（如某通道降级后置信度衰减导致仲裁结果变化），通用构建缓存对此无能力区分。本方法据此**避免被审查员以"内容寻址缓存为公知技术"驳回**——缓存输入域的差异即创新性根基。
+
+该机制使大型模块（如 xmc 模块下 27 个工作流）在多阶段批处理中的闭包计算总开销从 O(N×K)（N 个主制品 × K 个阶段）降为命中场景下的 O(N + K·hash_lookup) 量级（每个主制品最多一次闭包计算 + K 次 covered_files mtime 扫描 + 哈希查询；其中 covered_files 扫描复杂度为 O(|covered(p)|)，远小于全源码目录扫描）。
+
+### 3.2.10 通道失效降级回退
+
+实际生产中，单一通道扫描可能因多种原因失败——YAML 前置声明语法异常（如缩进错位）、XML 属性中含未闭合标签、命令引用语法升级导致正则不兼容等。传统方案此时直接抛出错误中止整个解析；本方案则对每个通道引入"失效降级回退"机制：
+
+| 通道 | 失效检测 | 降级回退动作 |
+| --- | --- | --- |
+| A. YAML 前置声明 | YAML 解析器抛错 | 退化为按行扫描 `dependencies:` 段，对 `- "..."` 模式做行级正则提取；记录 `channel-A-degraded` |
+| B. 命令引用 | 正则编译失败或匹配数为 0 但正文长度 > 阈值 | 切换到"宽松命令正则"：`@[a-z][a-z0-9-]*` 直接捕获后做后处理过滤；记录 `channel-B-degraded` |
+| C. 文件路径 / XML 属性 | XML 解析器抛错或文件路径前缀异常 | 退化为按引号块扫描所有形如 `"path/to/...md"` 的子串；记录 `channel-C-degraded` |
+| D. 模板字段 | YAML 解析失败但 frontmatter 区可定位 | 退化为按字符串截取 `template:` 行内值；记录 `channel-D-degraded` |
+
+降级回退后的输出在 IR 中标记 `degradation_source` 字段，置信度 `confidence` 自动衰减 30%（如通道 A 默认 0.95，降级后变为 0.665），使其在跨通道仲裁（§3.2.7）中天然让位于正常运行的其他通道，但不会因单点失效让整个安装中断。每次降级回退后在 stderr 输出 `[degraded] channel=A reason=yaml-syntax-error file=...` 提醒维护者修复源数据。
+
+**与 §3.2.7 跨通道仲裁的顺序关系**：通道失效降级回退在每个通道扫描出错的当下就近触发，发生在 §3.2.7 跨通道仲裁**之前**——降级后的通道输出携带衰减后的 `confidence`（如 0.665）进入仲裁，与正常运行的其他通道按统一优先级表参与裁决。因此 §3.2.10 的"保证整体不中断"与 §3.2.7 优先级 4 的"严格冲突阻塞"不会相互抢占：仲裁阶段看到的只是带衰减置信度的 IR 集合，不区分"该 IR 来自正常扫描还是降级回退"。仲裁阶段的阻塞动作（优先级 4）仅在"严格的版本/可选性互斥冲突"下触发，与通道是否降级无关。
+
+### 3.2.11 结果组织与输出
+
+最终将主制品、直接依赖、传递依赖三个集合通过集合的并运算合并为完整安装集。按模块维度组织输出：通过 `getModuleFromPath` 方法从文件路径中推断所属模块（识别 `src/{module}/` 和 `modules/{module}/` 两种目录结构）。输出包括：按模块分组的文件清单（agents、tasks、tools、templates、data、other 六类）、缺失依赖报告列表、依赖关系图数据。
+
+**实现位置**：`tools/cli/installers/lib/core/dependency-resolver.js` 第 665-741 行 `reportResults()` 与 `createWebBundle()` 方法。
+
+# 4、与第1部分所述的现有技术相比，本发明有何优点
+
+| 维度 | 包管理器方案 | 单遍扫描方案 | 开源 AI 框架安装器（BMAD-METHOD 等） | 本方案 | 指标改善 |
+| --- | --- | --- | --- | --- | --- |
+| 多格式声明识别 | 仅 package.json | 单种正则 | 仅 YAML `dependencies` 数组 | 4 通道协同（YAML / 命令 / 路径 / 模板） | 单遍正则与开源安装器均只命中"YAML 显式依赖"一个通道；本方案统一识别四类异构声明 |
+| 传递依赖自动补全 | 内置但仅限同语言 | 不支持 | 部分（仅显式声明的传递） | 复用解析逻辑递归展开 | 主制品自身只声明直接依赖，多层引用全部由系统自动发现 |
+| 双源目录映射 | 不涉及 | 不支持 | 不涉及（开发与部署路径未做类型敏感映射） | 类型敏感的路径重写 | 开发目录 `src/{module}/` 与部署目录 `xiaoma/{module}/`、`modules/{module}/` 三种形态被同一份 IR 统一解析 |
+| 跨通道置信度仲裁 | 不涉及 | 不涉及 | 不涉及 | 二元组 `(source, confidence)` + 优先级表 | 同一目标被多通道命中时输出唯一且可追溯的 IR |
+| 三态依赖分类 | 不涉及 | 不涉及 | 不涉及 | explicit / inferred / wildcard | 下游阶段对三态采用不同严格度，缺失诊断可立判优先级 |
+| 闭包指纹缓存 | 不涉及 | 不支持 | 不涉及 | 多阶段共享缓存 + 失效路径 | 多阶段反复计算同闭包从 O(N×K) 降为 O(N+K) |
+| 通道失效降级回退 | 不涉及 | 失败即崩 | 失败即崩 | 单通道失效自动 fallback + 置信度衰减 | 单点失效不再中断整体安装 |
+| 防环检测 | 内置 | 不支持 | 部分（基于已展开路径） | 集合防重 + 短路告警 | O(1) 检测，单次安装文件数远低于 `MAX_FILES_PER_INSTALL=5000` 阈值，处理过程无性能退化 |
+
+**覆盖率指标的测量方法**：以 v1.12.0 工作树的 35 个主制品（8 agent + 27 workflow）为基线，对每个主制品手工枚举其全部应被发现的依赖（"金标准依赖集"，由发明人逐文件审阅 YAML 前置声明、Markdown 正文、XML 属性后形成）；以单遍正则方案与本方案分别运行后，统计实际发现的依赖与金标准的交集大小：
+
+```
+覆盖率 = |actual ∩ ground_truth| / |ground_truth|
+```
+
+单遍正则方案在统一规则下仅命中"YAML 显式 dependencies 数组"通道，对命令引用（`@task-xxx`）、模板引用（`template:` 字段）、相对路径引用、XML 属性引用均不识别，且不展开传递依赖；本方案四通道协同 + 传递闭包后金标准依赖集被完全发现。该统计可由审查员在 v1.12.0 工作树上对照 `src/xmc/agents/*.yaml` 与 `src/xmc/workflows/**/workflow.md` 的 frontmatter 与正文人工抽样复核。
+
+## 综合有益效果
+
+为便于审查时快速把握本发明的综合价值，将分散于第 3、第 4 节的指标按四个维度归纳如下：
+
+| 维度 | 量化效果 | 数据来源 |
+| --- | --- | --- |
+| 性能 | 全闭包计算的总体时间复杂度为 O(n)；集合防环检测每节点 O(1) 命中判定；当前 v1.12.0 工作树 35 主制品 + 任务模板规模下，解析过程无可观测耗时瓶颈 | §3.2.5、§4 表"防环检测" |
+| 可靠性 | 单遍正则方案仅命中"YAML 显式依赖"一个通道，本方案四通道协同 + 传递闭包后金标准依赖集被完全发现；开发 / 部署双源解析一致；A→B→C→A 循环依赖在集合防重 + 短路告警下不会导致安装中断 | §3.2.6、§4 表前三行 |
+| 易用性 | 主制品仅需声明直接依赖，传递依赖全部由系统自动发现；YAML 反引号写法被自动改写为标准双引号，兼容既存非标准配置 | §3.2.3、§3.2.5 |
+| 可维护性 | 四个阶段（主制品收集 / 多通道提取 / 路径映射 / 闭包计算）职责清晰、可独立演进；新增一类依赖通道仅需在第二遍扫描中追加一个解析器，路径解析与闭包计算无需改动 | §3.2.1、§3.2.3 |
+
+# 5、本发明的关键点和欲保护点是什么？
+
+1. **四遍递归扫描架构**：将依赖解析分为主制品收集、多格式依赖提取、路径解析与双源映射、传递闭包计算四个独立阶段，各阶段职责明确、可独立演进。
+2. **多通道协同依赖提取**：在同一遍扫描中协同运行 YAML 前置声明、命令语法引用、文件路径引用、模板引用四个独立通道，统一输出到带类型标记的依赖集合。
+3. **双源目录结构自动映射**：按依赖类型标识自动将源码路径（`src/{module}/`）映射到部署路径（`xiaoma/{module}/` 或 `modules/{module}/`），支持 core 模块与扩展模块的差异化路径规则。
+4. **集合防环的传递依赖闭包算法**：用 `processed` 集合追踪已处理文件，复用前序阶段的解析逻辑递归发现传递依赖，在 O(n) 时间复杂度内完成闭包计算并自动短路循环。
+5. **跨通道置信度仲裁协议**：每条 IR 附带 `(source_channel, confidence)` 二元组，按预定义优先级表合并多通道命中同目标的依赖；冲突时按 `confidence` 最高的通道仲裁并保留可追溯的 `arbitration_trace`。
+6. **三态依赖分类与后续阶段严格度耦合**：将每条 IR 划入 `explicit / inferred / wildcard` 三态，下游路径解析、闭包计算、缺失诊断各阶段对三态采用差异化严格度。
+7. **跨阶段闭包指纹缓存**：以 `SHA-256(canonical-sorted-list)` 为指纹的闭包结果缓存，编译/打包/部署各阶段共享同一闭包结果，O(N×K) 降为 O(N+K) 量级。
+8. **通道失效降级回退**：单一通道扫描失败时自动 fallback 到等价的宽松规则；降级输出标记 `degradation_source` 字段、置信度衰减 30%，保证整体不中断。
+
+## 5.5 建议权利要求方向（初稿，供代理人参考）
+
+**独立权利要求 1（方法）**：
+
+一种面向 AI 智能体框架的多通道依赖解析方法，其特征在于，包括以下步骤：
+
+- S1：依据用户选择的模块列表，从框架的源码目录收集主制品文件集合；
+- S2：对所述主制品文件集合中的每个文件，在同一遍扫描中通过至少三个独立解析通道并行提取依赖声明，所述至少三个独立解析通道**必须包含以下集合中的至少三个**：(a) Markdown 头部 YAML 前置声明通道；(b) Markdown 正文命令语法引用通道；(c) 字符串或 XML 属性中的文件路径引用通道；(d) YAML 字段中的模板引用通道；可选地包含 (e) 其他经由实施者定义的独立解析通道；
+- S3：将各通道的输出统一为带类型标签的中间表示，所述类型标签至少区分前置声明类、命令类、路径类、模板类中**至少三种**依赖来源（对应 S2 启用的通道数量），并扩展支持实施者额外定义的类型标签；
+- S4：基于所述类型标签，对每条中间表示应用对应的路径重写规则，将其映射为目标部署目录下的绝对路径；
+- S5：以 S4 输出为起点递归展开传递依赖，并使用集合数据结构追踪已展开节点，进入递归前先查询该集合，命中则记录告警并短路而不抛出异常。
+
+**从属权利要求 2**：
+
+根据权利要求 1 所述的方法，其中 S4 的路径重写规则对所述类型标签为"前置声明类"或"路径类"的依赖、且声明含主模块标识（如 `core` 或 `xmc`）的，采用直接拼接至框架根目录的规则；对所述类型标签同时为"前置声明类"或"路径类"且声明含扩展模块标识的，采用拼接至 `modules/{模块名}/` 子目录的规则。
+
+**从属权利要求 3**：
+
+根据权利要求 1 所述的方法，其中 S5 的递归展开仅对扩展名为 `.md`、`.yaml`、`.yml` 的依赖文件进行下钻；非上述扩展名的依赖（如 `.csv`、`.json`、`.txt`）作为闭包叶节点直接计入安装集而不再递归。
+
+**从属权利要求 4**：
+
+根据权利要求 1 所述的方法，进一步包括对所述递归展开过程设置深度阈值与文件总数阈值；任一阈值触达时记录截断警告并将当前已发现依赖作为部分结果返回，不抛出异常。
+
+**从属权利要求 5**：
+
+根据权利要求 1 所述的方法，进一步包括跨通道置信度仲裁步骤：为 S2 中每个通道产出的中间表示附加二元组 `(source_channel, confidence)`，所述 `confidence` 由通道类型按预设权重决定且支持模块级覆盖；当多个通道对同一归一化目标路径产生中间表示时，按预设优先级表执行合并 / 择优 / 降级三类仲裁动作之一，并记录可追溯的仲裁轨迹。
+
+**从属权利要求 6**：
+
+根据权利要求 1 所述的方法，进一步包括三态依赖分类步骤：将每条中间表示划入显式 / 推断 / 通配三态之一；S4 与 S5 步骤对所述三态采用差异化的处理严格度，即对显式态执行严格匹配并对未命中抛错、对推断态执行提示性匹配并仅记录警告、对通配态允许零个或多个命中并仅记录 Glob 展开快照。
+
+**从属权利要求 7**：
+
+根据权利要求 1 所述的方法，进一步包括跨阶段闭包指纹缓存步骤：对每个主制品的传递闭包结果集，按其依赖记录的目标路径字段做规范化排序后拼接为规范字符串，并以密码学哈希函数（如 SHA-256）计算所得字符串的指纹；调用方在编译、打包、部署或其他后续阶段进入闭包计算前先查询所述指纹，命中即直接复用缓存的闭包结果集；当主制品内容哈希变化、源码目录内被闭包覆盖的任意文件 mtime 变更、调用方显式声明强制重算、或缓存条目年龄超过预设 TTL 中任一条件成立时缓存失效。
+
+**从属权利要求 8**：
+
+根据权利要求 1 所述的方法，进一步包括通道失效降级回退步骤：当 S2 任一独立解析通道在执行过程中抛出解析错误或匹配数为零但来源文件长度超过预设阈值时，自动切换至该通道的预设宽松回退规则继续提取；回退产出的中间表示标记降级来源字段，并对其 `confidence` 值施以预设的衰减系数，使后续仲裁中天然让位于正常通道结果，但保证整体扫描流程不被中断。
+
+**保护范围边界**：本方法独立解析通道数量下限为 3（即权利要求 1 要求"至少包含 (a)-(d) 集合中的至少三个通道"，4 通道为优选实施例）；不限定具体的集合数据结构实现（JavaScript `Set`、Python `set`、Java `HashSet` 均为等效替代）；不限定具体的正则表达式语法；不限定 `confidence` 数值范围与默认权重分配方式（支持任意有序权重集）；不限定闭包指纹所用的具体哈希函数（SHA-256 为优选实施例，等价强度的密码学哈希函数为等效替代）。
+
+# 6、针对第3部分的技术方案，是否还有别的替代方案同样能完成发明目的？
+
+| 替代方案 | 核心做法 | 与本方案对比 |
+| --- | --- | --- |
+| 一、合并扫描遍数 | 第 1+2 遍合并、第 3+4 遍合并，减少文件 I/O 次数 | 减少 I/O 次数约 50%，但各阶段职责耦合、调试排查更困难，且复用价值低 |
+| 二、统一在 YAML 前置声明显式列出所有依赖 | 仅保留通道 A，作者手动维护完整依赖清单 | 解析逻辑大幅简化，但需作者持续维护、易遗漏；制品内容变更时无法自动追踪 |
+| 三、采用图数据结构（邻接表）替代集合+递归 | 在内存中构建有向依赖图，闭包用 BFS/DFS 遍历 | 提供更丰富的查询能力（最短路径、依赖层数），但实现复杂度更高；当前场景主要需求是"收集完整安装集"，额外的图查询能力并不必要 |
+
+# 7、与代表性现有技术的逐项对照
+
+为便于审查员快速核查新颖性，将本方案 8 项关键点与 5 类代表性现有技术（npm 包管理器、Maven 包管理器、单遍正则扫描、开源 AI 框架 BMAD-METHOD 安装器、git 子模块依赖）的披露情况逐项标注（✓ 已披露 / △ 部分披露 / ✗ 未披露）：
+
+| 关键点 | npm | Maven | 单遍正则 | BMAD-METHOD 安装器 | git 子模块 |
+| --- | --- | --- | --- | --- | --- |
+| 多通道协同识别（YAML/命令/路径/模板四类异构声明同遍提取） | ✗ | ✗ | ✗ | ✗（仅 YAML `dependencies`） | ✗ |
+| 双源目录类型敏感映射（`src/` 与 `xiaoma/` 双前缀） | ✗ | ✗ | ✗ | ✗ | ✗ |
+| 集合防环 + 短路告警 | ✓（npm 7+ 防环） | ✓ | ✗ | △（去重但无短路告警字段规范） | ✗ |
+| 跨通道置信度仲裁协议 | ✗ | ✗ | ✗ | ✗ | ✗ |
+| 三态依赖分类（explicit/inferred/wildcard）+ 后续严格度耦合 | ✗ | △（optional 字段，但无三态联动） | ✗ | ✗ | ✗ |
+| 跨阶段闭包指纹缓存 | △（npm ci 锁文件，但非闭包级指纹） | ✗ | ✗ | ✗ | ✗ |
+| 通道失效降级回退 + 置信度衰减 | ✗ | ✗ | ✗ | ✗ | ✗ |
+| 类型敏感路径重写（按 IR type 应用不同重写规则） | ✗ | ✗ | ✗ | ✗ | ✗ |
+
+可见**关键点 1、2、4、5、6、7、8 在所列代表性现有技术中均未披露**，关键点 3 的"集合防环"虽在 npm/Maven 中有等价实现但与本方案的"短路告警 + 字段规范"组合未见对应方案。
+
+# 附图说明
+
+**附图1 — 多通道依赖解析方法整体流程图**
+
+![附图1 - 四遍扫描整体流程](media/doc1_fig1.png)
+
+展示四遍扫描的顺序关系与数据流向：输入（模块列表 + 框架根目录）→ 第一遍主制品收集 → 第二遍多通道并行依赖提取 → 第三遍路径解析与双源映射 → 第四遍传递闭包计算 → 输出（完整安装集）。
+
+**附图2 — 多格式依赖提取的多通道并行架构图**
+
+![附图2 - 多通道并行架构](media/doc1_fig2.png)
+
+同一主制品文件内容同时进入四个解析通道（YAML 前置声明通道、命令引用通道、文件路径通道、模板引用通道），各通道输出汇聚到统一的依赖集合（IR）。
+
+**附图3 — 双源目录映射对照表**
+
+![附图3 - 双源目录映射](media/doc1_fig3.png)
+
+源码路径（`src/core/tasks/`、`src/xmc/workflows/` 等）与部署路径（`xiaoma/core/tasks/`、`xiaoma/modules/xmc/workflows/` 等）的映射关系。
+
+**附图4 — 系统模块架构图**
+
+![附图4 - 系统模块架构](media/doc1_fig4.png)
+
+`DependencyResolver`、`PrimaryFileCollector`、`MultiFormatParser`、`PathResolver`、`TransitiveDependencyResolver` 五个模块的连接关系与数据交互。
+
+
+## 附图源码（Mermaid，供绘图工程师参考重绘）
+
+**附图1 — 四遍扫描整体流程**
+
+```mermaid
+flowchart TD
+    A[输入: 模块列表 + 框架根目录] --> B[第一遍: 主制品收集]
+    B -->|结构化数组| C[第二遍: 多通道并行依赖提取]
+    C -->|带类型标签的IR| D[第三遍: 路径解析与双源映射]
+    D -->|绝对路径集合| E[第四遍: 传递闭包计算]
+    E -->|processed Set 防环| E
+    E --> F[Set 并集合并: 主制品 + 直接依赖 + 传递依赖]
+    F --> G[输出: 按模块分组的完整安装集 + 缺失报告]
+```
+
+**附图2 — 多通道并行架构**
+
+```mermaid
+flowchart LR
+    subgraph IN[主制品文件]
+        F[(.md 文件)]
+    end
+    F --> A[通道A: YAML前置声明]
+    F --> B[通道B: 命令引用 @task-/@agent-]
+    F --> C[通道C: 文件路径 + XML属性]
+    F --> D[通道D: 模板引用 template 字段]
+    A --> M[(统一IR集合<br/>type ∈ explicit/command/file/xiaoma-path/template)]
+    B --> M
+    C --> M
+    D --> M
+```
+
+**附图3 — 双源目录映射**
+
+```mermaid
+flowchart LR
+    subgraph SRC[开发源码 src/]
+        S1[src/core/tasks/elicit.md]
+        S2[src/xmc/workflows/create-prd/]
+        S3[src/modules/devops/agents/]
+    end
+    subgraph DST[部署目录 xiaoma/]
+        D1[xiaoma/core/tasks/elicit.md]
+        D2[xiaoma/xmc/workflows/create-prd/]
+        D3[xiaoma/modules/devops/agents/]
+    end
+    S1 -.core 直映射.-> D1
+    S2 -.xmc 主模块.-> D2
+    S3 -.modules/前缀.-> D3
+```
+
+**附图4 — 系统模块架构**
+
+```mermaid
+flowchart TB
+    DR[DependencyResolver<br/>统一调度] --> PC[PrimaryFileCollector<br/>主制品收集]
+    DR --> MP[MultiFormatParser<br/>四通道并行]
+    DR --> PR[PathResolver<br/>类型敏感路径重写]
+    DR --> TR[TransitiveDependencyResolver<br/>闭包 + 防环]
+    PC -->|主制品集合| MP
+    MP -->|带类型IR| PR
+    PR -->|绝对路径| TR
+    TR -->|完整安装集| OUT[(输出)]
+```