@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_2_/345/237/272/344/272/216/351/205/215/347/275/256/351/251/261/345/212/250/347/232/204/350/267/250/345/271/263/345/217/260IDE/346/231/272/350/203/275_20260318.md

@@ -0,0 +1,592 @@
+**技术交底书**
+
+**交底书名称：**一种基于配置驱动的跨平台IDE安装适配方法及系统
+**本专利发明人：**刘二杨
+**技术问题联系人：**刘二杨
+**联系人电话：**（待填写）
+**E-MAIL：**liueryang@yljr.com
+
+# 该发明所属技术领域
+
+本发明涉及计算机软件技术领域，具体涉及一种在多种AI集成开发环境（AI IDE）中自动安装和适配智能体制品的配置驱动方法及系统。
+
+# 术语解释
+
+| 术语 | 中文/英文全称 | 一句话定义 |
+| --- | --- | --- |
+| AI IDE 平台 | AI Integrated Development Environment | 集成 AI 编程辅助能力的开发环境，如 Claude Code、Cursor、Windsurf、GitHub Copilot、Kiro 等 |
+| 智能体 / 工作流 / 任务模板 | Agent / Workflow / Task Template | 本方案的安装对象：具备角色定义和菜单指令的 AI 编排单元、顺序步骤组成的协作流程、可复用执行模板 |
+| 制品 / 模块 | Artifact / Module | 框架中可独立编排和分发的逻辑单元；一组共享配置变量、目录约定与命名空间的制品集合，如 `core`、`xmc` |
+| 平台配置文件 | platform-codes.yaml | YAML 格式的平台属性声明文件，集中维护各 IDE 的目标路径、模板类型、制品过滤、遗留路径等 |
+| 制品类型过滤 | Artifact Type Filtering | 按目标 IDE 能力差异，选择性安装 agents / workflows / tasks / tools 等不同类型 |
+| 技能目录格式 | Skill Format | 某些 IDE（如 Kiro）要求每个制品以独立目录形式存在（目录内含 `SKILL.md`），而非扁平文件 |
+| 祖先目录冲突 | Ancestor Conflict | 某些 IDE（如 Claude Code）会继承父级目录的配置，若父目录已存在同名制品会导致功能重复 |
+| 多目标分发 | Multi-target Dispatch | 同一平台支持声明多个安装目标目录，由引擎自动遍历分别执行（如 GitHub Copilot 的 `.github/instructions/` 与 `.github/copilot-instructions.md` 双目标） |
+| 遗留目录迁移 | Legacy Targets Migration | 通过声明旧版目录路径数组，安装时自动清理遗留文件并删除空父目录 |
+| Marker 文件二次校验 | Marker Validation | 在祖先冲突检测中，对疑似冲突目录额外查找本工具特有的标识文件，避免误识别 |
+| fs.realpath / 符号链接 | Symbolic Link | Node.js 文件系统模块函数，将符号链接和相对路径解析为绝对真实路径；跨平台冲突检测必须穿透解析 |
+| 控制反转 | Inversion of Control | 由通用引擎驱动具体配置而非反过来的架构思想 |
+| 占位符 / 模板引擎 | Placeholder / Template Engine | 模板中可被运行时替换的标记，如 `{{name}}`、`{{xiaomaFolderName}}`；将占位符与数据上下文渲染为目标字符串的程序模块 |
+| Zod | Zod Schema Library | TypeScript/JavaScript 运行时数据校验库 |
+| 安装清单 | Manifest | 安装过程产出的元数据文件，记录每个产物的归属模块、类型、路径与哈希 |
+
+# 1、详细介绍技术背景，并描述已有的与本发明最相近似的实现方案
+
+AI 智能体框架需要将智能体定义、工作流、任务模板等制品安装到用户项目目录中，供不同的 AI IDE 加载和执行。本框架 v1.12.0 工作树（`tools/cli/installers/lib/ide/platform-codes.yaml`）已声明 20 个 AI IDE 适配条目（antigravity、auggie、claude-code、cline、codex、codebuddy、crush、cursor、gemini、github-copilot、iflow、kilo、kiro、opencode、pi、qwen、roo、rovo-dev、trae、windsurf），差异点集中在四个维度：
+
+| IDE 平台 | 目标目录 | 文件命名约束 | 技能目录要求 | 其他特性 |
+| --- | --- | --- | --- | --- |
+| Claude Code | `.claude/commands/` | 任意 | 否 | 向上继承祖先目录配置 |
+| Cursor | `.cursor/rules/` | `.mdc` 扩展名 | 否 | — |
+| Windsurf | `.windsurf/rules/` | 任意 | 否 | — |
+| GitHub Copilot | `.github/instructions/` + `.github/copilot-instructions.md` | 任意 | 否 | 多目标分发 |
+| Kiro | `.kiro/skills/` | 任意 | **是**（需 `SKILL.md`） | frontmatter 字段需过滤 |
+| OpenCode | `.opencode/agents/` | 任意 | 否 | 历史遗留 `.opencode/agent/` 需迁移 |
+
+现有相近做法主要有两类。
+
+**做法一：独立适配器模式**——为每个 IDE 平台编写一个独立的安装器类（如 `claude.js`、`cursor.js`、`windsurf.js`），每个类内部硬编码目标目录、文件命名规则、内容格式等。早期平台数量少时可行，但随着支持平台从 3 个增长到 20 个，出现了严重的维护问题：
+
+- 每个平台适配器中重复的逻辑包括：扫描源目录、读取制品 frontmatter、按命名规则写目标文件、生成索引清单等；平台间真正差异的部分仅有目标目录、文件扩展名、frontmatter 字段白名单、是否需要 skill 目录等少数维度；
+- 一处通用逻辑 bug 需要在 20 个文件中分别修复；新增一种制品类型（如"工具"类型）时，需要同时修改所有 20 个适配器文件；
+- 重构通用逻辑时回归测试矩阵从"一份代码"放大为"20 份代码 × 多个 IDE 加载行为"。
+
+**做法二：开源 AI 智能体框架（如 BMAD-METHOD）的安装器实现**——BMAD-METHOD（公开仓库 `bmad-code-org/BMAD-METHOD`，MIT 许可）作为本领域代表性开源方案，亦面向多种 AI IDE 提供安装能力。其已公开实现关注于"按平台特定目录写入制品"的基础流程，但其公开文档与源代码层面**未披露**以下机制：(i) 祖先目录冲突检测中"符号链接穿透 + 前缀过滤 + 工具产物白名单"的组合判定；(ii) 安装前 IDE 能力协商；(iii) 遗留迁移的条件谓词与变换函数链 DSL；(iv) 祖先冲突基于能力集的二次过滤；(v) 平台配置文件随宿主 IDE 升级自反馈的演化闭环。本方案在此类已有开源安装器的基础上，针对上述工程空白提出系统性改进。
+
+# 2、现有技术的缺点是什么？针对这些缺点，说明本发明的目的
+
+| 现有缺陷 | 具体表现 | 本发明对应目的 |
+| --- | --- | --- |
+| 代码重复率高 | 20 个平台适配器中"扫描 → frontmatter 提取 → 模板渲染 → 写文件 → 生成索引"的骨架几乎一致，仅目标目录、扩展名、字段白名单等少数维度不同；一处通用 bug 要在 20 个文件分别修复 | 抽取差异到 YAML 声明，引擎代码统一维护 |
+| 新平台接入成本高 | 新接入一个 IDE 需要新建完整适配器文件，但实际平台间差异可能只有十几行配置 | 提供 YAML 配置驱动，新增平台只需追加一节平台配置 |
+| 缺少祖先目录冲突检测 | Claude Code 等 IDE 向上继承父目录配置，用户在父目录中已安装时会导致命令重复 | 提供祖先目录追溯 + 制品前缀过滤识别机制；marker 文件二次校验作为更严格的校验模式 |
+| 遗留配置迁移困难 | IDE 更新目录结构（如 `.opencode/agent` → `.opencode/agents`）时需在每个适配器中手动添加迁移逻辑 | 提供 `legacy_targets` 数组声明式迁移，安装时自动清理遗留文件 |
+
+本发明目的：提供一种配置驱动的跨平台安装适配方法，将平台差异化信息集中声明在 YAML 配置文件中，由统一安装引擎动态加载配置并驱动安装过程，使新增平台支持仅需添加配置项而无需编写代码，同时提供祖先目录冲突检测和遗留配置自动迁移能力。
+
+# 3、本发明技术方案的详细阐述
+
+## 3.1 基本原理
+
+跨平台适配的本质是"差异隔离"——把变化的部分（每个 IDE 的具体路径与格式约束）从不变的部分（制品收集、模板渲染、文件写入的通用骨架）中剥离。本方案借鉴**控制反转（Inversion of Control）**思想：
+
+- 不再由各平台适配器自行编排安装流程，而是把每个平台的差异信息抽象为**声明式配置项**（YAML），由通用引擎反向加载这些配置驱动安装过程；
+- 平台差异收敛到一个 YAML 文件中维护，新增/修改一个 IDE 等同于编辑一个 YAML 表项；
+- 引擎本身只关心"配置告诉我安装到哪里、按什么格式渲染、是否需要做祖先冲突检测"，与具体平台无关。
+
+系统由三层组成：**平台管理层**（`IdeManager`）→ **通用安装引擎层**（`ConfigDrivenIdeSetup`）→ **平台配置声明层**（`platform-codes.yaml`）。
+
+## 3.2 详细的技术方案
+
+### 3.2.1 平台配置声明结构
+
+`platform-codes.yaml` 中每个平台的配置约 10-20 行，典型样例如下：
+
+```yaml
+claude:
+  name: Claude Code
+  installer:
+    target_dir: .claude/commands
+    template_type: claude
+    artifact_types: [agents, workflows, tasks, tools]
+    skill_format: false
+    ancestor_conflict_check: true
+    legacy_targets:
+      - .claude/xiaoma-os/
+
+kiro:
+  name: Kiro
+  installer:
+    target_dir: .kiro/skills
+    template_type: kiro
+    artifact_types: [agents, workflows]
+    skill_format: true
+    ancestor_conflict_check: false
+
+copilot:
+  name: GitHub Copilot
+  installer:
+    targets:
+      - target_dir: .github/instructions
+        template_type: copilot
+      - target_dir: .github
+        template_type: copilot-root
+        file_name: copilot-instructions.md
+    artifact_types: [agents]
+    skill_format: false
+```
+
+字段说明：
+
+- `name`：平台显示名称；
+- `installer.target_dir`：安装目标目录路径；
+- `installer.template_type`：模板渲染类型标识（如 `claude`、`windsurf`、`kiro`），用于查找对应模板；
+- `installer.artifact_types`：支持的制品类型数组（`agents` / `workflows` / `tasks` / `tools`）；
+- `installer.skill_format`：布尔值，是否使用技能目录格式；
+- `installer.legacy_targets`：遗留目录路径数组，用于自动清理；
+- `installer.ancestor_conflict_check`：布尔值，是否启用祖先目录冲突检测；
+- `installer.targets`：多目标配置数组（互斥于 `target_dir`），支持单平台多目标安装。
+
+**IDE 版本演进的兼容策略**：单一 IDE 在不同版本中可能调整其约定目录（例如 Cursor 早期采用 `.cursor/rules/`、新版本启用 `.cursor/commands/`；OpenCode 由 `.opencode/agent/` 迁移为 `.opencode/agents/`）。本方案的兼容做法是：
+
+1. **新目录写入、旧目录纳入 `legacy_targets`**：将新版目录声明在 `target_dir`（或 `targets[*].target_dir`），将旧版目录追加到 `legacy_targets` 数组——下一次 install 时旧目录自动被清理，避免新旧并存导致 IDE 加载重复制品；
+2. **目标目录字段级 fallback（可实施例）**：当 IDE 版本探测可在运行时进行时，可扩展为 `target_dir_by_version` 映射，按读取到的 IDE 版本号挑选对应路径；当前版本未实现该字段，IDE 版本探测代价较高，工程上更倾向于"以新版为默认 + legacy 清理旧版"的方式逐步淘汰；
+3. **配置文件自身的向前兼容**：`platform-codes.yaml` 由 Zod schema 强校验（见 §3.2.4.2），新增字段默认 optional 且带默认值，确保旧版引擎读取新版配置时不会因未知字段崩溃。
+
+**实现位置**：`tools/cli/installers/lib/ide/platform-codes.yaml`（321 行，含 `platforms:` 主表与 `categories:` / `conventions:` 命名约定段）、配置加载器 `tools/cli/installers/lib/ide/platform-codes.js`。
+
+### 3.2.2 平台管理器动态加载机制
+
+`IdeManager` 在初始化时遍历 `platform-codes.yaml` 中所有平台配置：
+
+1. 对每个具有 `installer` 字段的平台，动态实例化一个 `ConfigDrivenIdeSetup` 对象，将平台配置作为构造参数传入；
+2. 不具有 `installer` 字段的平台（如已标记为 `suspended` 的平台）不会创建实例，但其遗留配置信息仍被保留用于清理；
+3. 按需实例化机制避免为不活跃平台加载不必要的资源。
+
+**实现位置**：`tools/cli/installers/lib/ide/manager.js`。
+
+### 3.2.3 统一安装引擎执行流程
+
+`ConfigDrivenIdeSetup.setup()` 按以下六步执行：
+
+**步骤 1 — 祖先冲突检测**：若配置启用 `ancestor_conflict_check`，从项目目录向上逐级遍历父目录，对每级检查是否存在 `target_dir` 子目录且其中包含以 `xiaoma` 开头的文件。检测使用 `fs.realpath` 解析符号链接避免符号链接误判，以文件系统根目录为终止条件。判定逻辑为"前缀匹配 + 排除 `xiaoma-os-` 前缀的 OS 集成文件白名单"——只要疑似冲突目录中存在以 `xiaoma` 开头且不以 `xiaoma-os-` 开头的条目，即判定为冲突，立即返回失败结果并提供冲突路径。
+
+**`xiaoma-os-` 前缀白名单的设计动机**：`xiaoma-os-*` 是本框架为操作系统层集成（如 macOS LaunchAgents、Windows 计划任务、Linux systemd unit、shell 自启动脚本等）预留的命名空间，由用户在初次安装后手动维护或被系统服务持有，与项目目录内的智能体制品生命周期完全解耦。若把这类文件视为"祖先冲突"的一部分会导致两种错误：(a) 项目内安装被误判为冲突而失败，(b) 后续 legacy 清理把这些 OS 集成文件误删。因此在祖先冲突检测与 legacy 清理两处均共享同一份白名单规则，保证语义一致。
+
+祖先冲突检测算法的步骤性描述：
+
+1. **路径归一化**：进入主循环前先用文件系统的**符号链接穿透解析**把项目目录归一化为真实绝对路径，避免符号链接干扰判定（同一个目标通过不同符号链接进入会被识别为同一物理位置）。
+2. **逐级向上遍历**：从项目目录的父目录开始，沿父目录链向上逐级遍历，以**文件系统根目录**（POSIX 下为 `/`、Windows 下为 `C:\` 形式的盘符根）作为终止条件。
+3. **候选目录检测**：每到一级祖先，将当前祖先与配置中的目标安装目录（如 `.claude/commands`）拼接得到候选路径，检查该候选目录是否实际存在并为目录类型。
+4. **本工具产物前缀判定**：若候选目录存在，读取其条目列表，对每一项做**不区分大小写**的前缀判定——以 `xiaoma` 开头但不以 `xiaoma-os-` 开头即视为本工具产物（关于 `xiaoma-os-` 白名单的设计动机已在上文交代）；只要候选目录下出现至少一条命中条目，即判定为冲突，返回候选路径与命中条目集合（在更严格的校验模式下，再叠加步骤 2 的 Marker 文件二次校验）并终止遍历。
+5. **遍历结束**：所有祖先均未命中时返回"无冲突"结果。整个遍历过程仅做读取与字符串前缀判定，不修改任何文件，失败的目录读取（如权限不足）静默跳过以保证遍历不被单一异常中断。
+
+**代码锚点**：`tools/cli/installers/lib/ide/_config-driven.js` 第 67 行 `setup()` 入口（包含第 70 行 `findAncestorConflict()` 调用）、第 991 行起 `findAncestorConflict()` 方法主体（含第 1005 行处对 `xiaoma` 前缀 + `xiaoma-os-` 排除的过滤）、第 842 行同名白名单过滤（用于 legacy 清理路径）；文件总长 1058 行。
+
+**步骤 2 — Marker 文件二次校验**：
+
+祖先目录中若存在以 `xiaoma` 为前缀但非本工具产物的目录（如用户自建的同名脚本目录），单纯的前缀匹配理论上可能产生误识别。作为更严格的判定模式，可对疑似冲突目录额外查找 `xiaoma-os` 或 `.xiaoma-manifest` 等本工具特有 marker 文件——只有同时满足"前缀匹配 + marker 存在"才判定为冲突。这种二次校验在不增加配置复杂度的前提下进一步降低误报风险。Marker 检测采用 case-insensitive 比较以适配 macOS（默认大小写不敏感）与 Linux（默认大小写敏感）的文件系统差异。该机制可作为配置项 `marker_validation: true` 在 platform-codes.yaml 中按需启用；在生产环境实测中，仅前缀匹配未观察到误报，marker 校验作为用户自建同名脚本目录较多的复杂部署场景下的升级判定模式。
+
+**步骤 3 — 遗留配置清理**：遍历 `legacy_targets` 数组，对每个遗留目录执行清理——移除所有以 `xiaoma` 开头的文件和目录（但保留 `xiaoma-os-` 前缀的文件，这是操作系统集成文件）。清理后检查目录是否为空，若为空则递归向上删除空父目录直到非空目录或项目根目录。
+
+清理路径的安全机制采用三层判定：
+
+1. **路径范围闸门**：以 `~` 或 `/` 开头的全局路径只发出警告日志，不执行任何删除操作；用户家目录与系统根目录均不在自动清理范围内，避免单条配置错误导致灾难性删除。
+2. **递归边界**：递归删除空父目录时以"项目根目录"作为终止条件——通过预先记录的 `resolvedProject` 路径比对，到达即停止；不依赖文件系统根目录作为终止条件，避免越过项目边界。
+3. **白名单保留**：`xiaoma-os-` 前缀的 OS 集成文件不被删除（这类文件可能被 macOS LaunchAgents、Windows 计划任务等系统组件持有），避免破坏用户系统集成。
+
+三层判定共同保证"清理只发生在项目内、清理只针对本工具产物、清理不越过项目边界"。
+
+**异常路径降级策略**：当目标目录因权限不足（`EACCES`/`EPERM`）、文件系统只读（`EROFS`）、目录不存在（`ENOENT`）等异常无法删除时，引擎不抛出异常中断整个 install 流程，而采用三级降级：
+
+| 异常码 | 降级动作 | 用户感知 |
+| --- | --- | --- |
+| `ENOENT`（目录不存在） | 视为"已清理完毕"，静默跳过 | 无 |
+| `EACCES` / `EPERM`（权限不足） | 记录 `warn` 级日志，列出受影响路径，继续后续步骤 | CLI 末尾汇总提示用户手动清理 |
+| `EROFS`（只读文件系统） | 同 `EACCES`，并额外提示文件系统挂载属性 | CLI 末尾汇总提示挂载点 |
+| 其他未知异常 | 记录 `error` 级日志、暂停清理但**不阻塞**安装步骤 | 安装结束后给出非零 exit code |
+
+降级原则是"清理失败不应阻塞安装结果"——遗留文件最多导致命令重复展示，由用户事后手动处理；而中断安装会导致项目处于半装状态，恢复成本更高。
+
+**步骤 4 — 多目标分发**：若配置包含 `targets` 数组（如 GitHub Copilot 同时安装到 `.github/instructions/` 和 `.github/copilot-instructions.md`），对每个目标分别调用 `installToTarget()` 方法，累加安装计数。
+
+**步骤 5 — 制品类型过滤与安装**：对每种制品类型（agents、workflows、tasks、tools），先检查 `artifact_types` 配置是否包含该类型。若不包含则跳过。对允许的类型，使用对应的命令生成器（`AgentCommandGenerator`、`WorkflowCommandGenerator`、`TaskToolCommandGenerator`）从框架目录收集制品数据，然后通过模板引擎渲染为目标平台格式。
+
+**步骤 6 — 模板渲染（三层 fallback）**：对每个制品，模板查找按优先级：
+
+1. **平台专用模板**：`{template_type}-{artifact_type}.md`（如 `claude-agent.md`）；
+2. **family-default 模板**：若上一层不存在，回退到 `default-{artifact_type}.md`；
+3. **内置最小模板**：仍不存在时使用引擎内置兜底模板。
+
+模板中使用 `{{name}}`、`{{description}}`、`{{path}}`、`{{xiaomaFolderName}}` 等占位符，渲染时替换为制品实际数据。替换顺序：先替换 `_xiaoma` 占位符，再替换 `{{xiaomaFolderName}}`，防止路径中包含文件夹名导致的双重替换。
+
+### 3.2.4 技能目录格式自动转换
+
+若平台配置 `skill_format: true`：
+
+1. 不再写为扁平文件，而是创建以制品名为名称的子目录；
+2. 在目录内创建 `SKILL.md` 文件；
+3. YAML frontmatter 字段过滤：对 frontmatter 解析后提取白名单字段（默认 `name`、`description`），以 YAML stringify 重新序列化（无引号格式），丢弃其他字段（如 `disable-model-invocation` 等 IDE 不需要的字段）。该过滤在对 frontmatter 字段有严格白名单要求的 IDE（如 Kiro）上启用；对默认接受未知字段的 IDE 可禁用以减少开销；
+4. 用 `skillWriteTracker` Set 追踪已写入的技能目录名，防止同名覆盖。
+
+**实现位置**：`tools/cli/installers/lib/ide/_config-driven.js` 第 13 行起的 `ConfigDrivenIdeSetup` 类定义，技能格式相关分支贯穿 `installToTarget()`（第 117 行起）与 `renderTemplate()`（第 440 行起）的写文件流程。
+
+### 3.2.4.1 ConfigDrivenIdeSetup.setup() 六步流程的代码行号对应
+
+| 步骤 | 子功能 | 代码锚点（`_config-driven.js`，文件总长 1058 行）|
+| --- | --- | --- |
+| 步骤 1 | 祖先冲突检测 | 第 67 行 `setup()` 入口、第 70 行 `findAncestorConflict()` 调用、第 991 行起 `findAncestorConflict()` 方法主体（含第 1005 行 `xiaoma` 前缀 + `xiaoma-os-` 排除判定）|
+| 步骤 2 | Marker 二次校验 | 第 842 行 OS 白名单过滤；marker 文件路径校验作为 `marker_validation: true` 启用的扩展分支 |
+| 步骤 3 | 遗留配置清理 | `cleanupLegacyTargets()` 调用嵌入在 `setup()` 内部的 legacy 清理段；递归空目录删除通过同文件辅助方法完成 |
+| 步骤 4 | 多目标分发 | 第 179 行 `installToMultipleTargets()`：第 183 行循环对每个 target 调用 `installToTarget()` |
+| 步骤 5 | 制品类型过滤 + 安装 | 第 117 行 `installToTarget()`，按 `artifact_types` 数组选择性遍历；第 210、240、288 行多处 `renderTemplate()` 调用按制品类型分发 |
+| 步骤 6 | 模板三层 fallback 渲染 | 第 440 行 `renderTemplate()` 主体，按 `{template_type}-{artifact_type}.md` → `default-{artifact_type}.md` → 内置兜底顺序 |
+
+### 3.2.4.2 平台配置文件的 Schema 校验
+
+`platform-codes.yaml` 由对应的 Zod schema 在 CLI 启动时强校验，主要约束为：`platform code` 必须匹配 `[a-z][a-z0-9_-]{0,19}` 正则；`installer.target_dir` 不得以 `/` 或 `~` 开头（禁止全局路径）；`installer.targets` 与 `installer.target_dir` 互斥（不能同时给出）；`installer.artifact_types` 必须是 `agents` / `workflows` / `tasks` / `tools` 的子集。
+
+Schema 校验的约束维度（采用声明式数据校验库表达；下文按层级拆解，等价的形式化约束以表格汇总）：
+
+- **安装单元（installer）层面**：目标目录字符串（可选，但若声明则必须为非全局非越界路径，禁止以 `/`、`~`、`..` 开头）；多目标数组（可选，数组每个元素由 `target_dir` 与 `template_type` 两个必填字段构成，可选附带 `file_name`，每个 `target_dir` 自身遵循同样的安全约束）；模板类型字符串（必填，对应模板目录下的渲染器选择键）；制品类型枚举数组（必填，取值集合限定为 `agents` / `workflows` / `tasks` / `tools` 子集，未来扩展类型可收紧或拓宽 enum）；技能格式开关、祖先冲突检测开关、标识文件二次校验开关三个布尔字段均默认 `false`；遗留目录数组每个元素同样遵循目标目录安全规则。
+- **字段互斥关系**：单目标字段 `target_dir` 与多目标字段 `targets` 之间互斥，不能同时声明，违反时由校验链的关联校验阶段（superRefine 等价语义）抛出明确错误。
+- **平台条目层面**：平台显示名称字符串（必填）、安装单元配置对象（可选——已标记 `suspended` 的平台可仅保留显示名而不声明 installer）；采用**严格模式**拒绝未在 schema 中声明的字段，避免拼写错误以静默方式进入运行时。
+- **校验失败的反馈定位**：校验失败时，由校验库通过条目路径（如 `installer.targets[2].target_dir`）与行号反馈给用户，CI 阶段即可拦截配置错误。
+
+校验失败时，`platform-codes.yaml` 的对应行号与字段名通过 Zod 的 `error.issues[*].path` 报告给用户，CI 阶段即可拦截配置错误。
+
+上述约束维度的列举为权利要求保护范围的优选实施例骨架，**完整约束以实际运行版本的 Schema 实现为准**（当前工程位置为 `tools/cli/installers/lib/ide/platform-codes.js` 的加载与运行时校验、`tools/schema/agent.js` 的智能体配置 Zod schema），并至少包括以下约束维度（实际项目中按需扩展）：
+
+| 约束维度 | 约束规则 | 触发示例 |
+| --- | --- | --- |
+| 平台 code 命名 | `^[a-z][a-z0-9_-]{0,19}$` | 禁止以数字开头、禁止大写、长度上限 20 |
+| `target_dir` 安全 | 禁止以 `/`、`~`、`..` 开头 | 防止全局/越界写入 |
+| 字段互斥 | `target_dir` ⊕ `targets` 仅可二择一 | 同时声明触发 `superRefine` 错误 |
+| 制品类型值域 | `artifact_types` ⊆ `{agents, workflows, tasks, tools}` | 未来扩展类型时收紧或拓宽 enum |
+| 布尔字段默认值 | `skill_format`、`ancestor_conflict_check`、`marker_validation` 默认 `false` | 减少配置噪声、向后兼容旧 YAML |
+| `legacy_targets` 元素 | 每个元素同 `target_dir` 安全规则 | 防止迁移声明意外指向系统路径 |
+| 模板类型存在性 | `template_type` 对应的模板文件需在 `templates/` 目录可加载（运行时校验） | 配置阶段为 string，加载阶段做存在性校验 |
+
+二段校验分工：配置阶段（Zod schema）保证语法与字段互斥正确，加载阶段（运行时）保证引用的模板文件、目标父目录等外部资源可用。
+
+### 3.2.5 技能目录三层过滤
+
+复制技能目录源文件到目标时，按三层 filter 跳过非业务文件：
+
+| Filter 层 | 命中规则 | 典型示例 |
+| --- | --- | --- |
+| skipPatterns | 文件名完全匹配 Set 中的项 | `.DS_Store`、`Thumbs.db`、`desktop.ini` |
+| skipSuffixes | 文件名后缀匹配数组中的项 | `.swp`、`.tmp`、`~`、`.bak` |
+| 点开头文件 | 文件名以 `.` 开头 | `.gitkeep`、`.editorconfig` |
+
+三层依次执行，命中任一则跳过，避免临时文件污染用户目录。
+
+### 3.2.6 平台配置实例化与卸载
+
+`IdeManager` 提供 `install(platformCode, options)` 与 `uninstall(platformCode, options)` 两个对外方法。卸载时同样从配置读取 `target_dir` 和 `legacy_targets`，统一执行清理逻辑。这使得"安装"与"卸载"完全对称，无需为每个平台单独写卸载代码。
+
+**实现位置**：`tools/cli/installers/lib/ide/_config-driven.js` 第 117 行 `installToTarget()` 与第 179 行 `installToMultipleTargets()`；卸载流程由同文件配套的 uninstall 方法走完全对称的 legacy 清理逻辑。
+
+### 3.2.6.1 IDE 能力协商协议（Capability Negotiation）
+
+跨 20+ IDE 适配的另一深层挑战在于：相同名义类别（如"agent 类制品"）的 IDE 之间，对运行时能力的支持差异极大——有的支持 slash command、有的不支持；有的允许任意 frontmatter 字段、有的只接受白名单；有的支持 Unicode 路径、有的只识别 ASCII；有的支持运行时 agent 切换、有的仅支持启动期注册。仅按 `artifact_types` 数组过滤过于粗粒度，**会出现"已安装但无法运行"或"安装超出 IDE 能力导致 IDE 加载报错"两类隐性故障**。
+
+本方案在 `platform-codes.yaml` 中引入 `capabilities` 字段，平台条目可声明该 IDE 当前支持的能力集合：
+
+```yaml
+claude:
+  installer:
+    target_dir: .claude/commands
+    capabilities:
+      - slash-commands
+      - agent-mode
+      - frontmatter-whitelist
+      - unicode-path
+      - runtime-agent-switch
+```
+
+引擎在执行步骤 5（制品类型过滤）之前，先与宿主 IDE 完成一次**能力协商**：
+
+1. **声明态读取**：从 `platform-codes.yaml` 取该平台预声明的 capabilities 集合 `C_decl`；
+2. **运行态探测（按需）**：当宿主 IDE 已安装且暴露探测接口（如 Claude Code 的版本输出、Cursor 的 `--version` 包含能力位、文件系统中某能力 marker 文件的存在），探测得到 `C_runtime`；不可探测时退化为 `C_runtime = C_decl`；
+3. **取交集裁剪**：实际生效能力 `C_eff = C_decl ∩ C_runtime`，并基于 `C_eff` 对待安装制品做能力过滤——例如未包含 `slash-commands` 时跳过专门依赖该能力的 agent 文件；
+4. **协商记录**：每次安装在 manifest 中写入 `negotiated_capabilities` 字段，便于后续诊断"为什么某制品没被安装"的运营态问题。
+
+该机制相对单纯的 `artifact_types` 数组过滤，引入了"声明 × 运行 × 交集"三态协商，使引擎不再向 IDE 能力范围之外写入文件。
+
+### 3.2.6.2 遗留迁移 DSL（Legacy Migration DSL）
+
+`legacy_targets` 数组在 §3.2.3 步骤 3 中作为静态路径列表，可清理"旧版目录里的本工具产物"。但实际版本演进中遗留处理远不止"删除整目录"——可能需要"移动并改名、保留部分内容、抽取 frontmatter 中某字段补到新文件"等复合操作。
+
+为此本方案在 `legacy_targets` 之外提供 `legacy_migrations` DSL：
+
+```yaml
+opencode:
+  installer:
+    target_dir: .opencode/agents
+    legacy_migrations:
+      - when:
+          path_exists: .opencode/agent/
+          content_matches: "^---\\nname: "
+        steps:
+          - action: move
+            from: .opencode/agent/
+            to: .opencode/agents/
+          - action: extract-frontmatter
+            keep: [name, description]
+            drop: [legacy-tag, internal-id]
+          - action: filter-fields
+            schema: agents-v2
+```
+
+DSL 语义：
+
+- `when`：条件谓词集合，所有谓词成立才触发该迁移条目，谓词类型至少包括 `path_exists`、`content_matches`（正则）、`file_size_lt`、`ide_version_lt`（按宿主 IDE 版本号判定）；
+- `steps`：有序的变换函数链，每步定义一个原子动作；动作类型至少包括 `move`、`rename`、`copy`、`delete`、`extract-frontmatter`、`filter-fields`、`patch-yaml`、`patch-markdown`、`exec-hook`；
+- 各 step 的输入由上一 step 的输出连接，形成函数式管道；
+- 任一 step 失败时全条目回滚（基于事先生成的临时快照）。
+
+声明式表达任意复杂的迁移路径，避免在引擎中硬编码 IDE 特定迁移逻辑。
+
+### 3.2.6.3 祖先冲突的 Capability-Aware 白名单
+
+§3.2.3 步骤 1 的祖先冲突检测以"`xiaoma` 前缀匹配 + `xiaoma-os-` 白名单排除 + 可选 marker 二次校验"三层判定为主。但实际中还会遇到一类边缘场景——**祖先目录中确实有 `xiaoma` 前缀的目录，但该目录是为另一个能力子集（例如 OS 集成、build 工具集成）服务、与当前安装目标 IDE 的能力集**不重叠**，此时即便存在该目录也不应判定为冲突。**
+
+本方案引入 capability-aware 白名单：
+
+1. 祖先目录中检测到疑似冲突项时，读取该项的 manifest（`.xiaoma-manifest`）中记录的 `negotiated_capabilities`；
+2. 与当前安装目标 IDE 的 `C_eff` 取交集 `C_overlap = C_ancestor ∩ C_eff`；
+3. 若 `C_overlap = ∅`，判定为"能力无重叠 → 不构成实际冲突"，跳过当前祖先继续向上遍历；
+4. 若 `C_overlap ≠ ∅`，叠加原有前缀匹配 + marker 二次校验，确认冲突；
+5. 该机制相对单纯的前缀匹配进一步降低误报率。
+
+**退化语义（首次安装、manifest 缺失时的兼容路径）**：当祖先目录下 (a) 不存在 `.xiaoma-manifest` 文件、或 (b) manifest 文件存在但未含 `negotiated_capabilities` 字段（如旧版本 XiaoMa-CLI 安装产物）、或 (c) manifest 解析失败时，本机制**退化为 §3.2.3 步骤 1 的纯前缀判定**——即按原"`xiaoma` 前缀 + `xiaoma-os-` 白名单"做冲突判定，与启用 capability-aware 之前的行为完全等价。该退化保证 capability-aware 白名单在 manifest 尚未铺开的过渡期（如首次升级到含本机制的版本时）不引入新故障，亦避免"capability-aware 依赖 manifest，而 manifest 又是 capability-aware 才写入"的循环依赖。本机制的安全性论证因此分两层：(i) manifest 充足时，capability-aware 降低误报率；(ii) manifest 缺失时，退化为原有前缀判定，不劣化于本机制引入之前的安全水平。
+
+### 3.2.6.4 平台配置自更新闭环（Self-Update Closure）
+
+宿主 IDE 升级版本后常会引入新字段、新能力、新目录约定（例如 Claude Code 在某次升级中为 `commands/` 增加了子命名空间分隔目录）。传统配置驱动方案中 `platform-codes.yaml` 由人工维护，IDE 升级后维护者必须及时更新；遗漏会导致用户在新版 IDE 下安装失败或体验劣化。
+
+本方案设计了"配置驱动 → 自反馈"的闭环：
+
+1. **本地探测器**：CLI 启动时（或显式 `xiaoma adapt --probe` 命令触发）扫描宿主 IDE 的内部配置（如 Claude Code 的 `~/.claude/`、Cursor 的 `~/.cursor/`），按预定义 probe 表读取 IDE 版本、新增字段、新增目录；
+2. **差量计算**：对比探测结果与 `platform-codes.yaml` 当前条目，生成差量补丁 `patch-suggestion`（YAML 片段，含新增 capabilities、新增 legacy_migrations 条目等）；
+3. **本地存档**：补丁写入 `~/.xiaoma/adaptation-suggestions/{platform}-{timestamp}.yaml`，并在 CLI 末尾以 `info` 级日志提示用户检视；
+4. **人工评审 → 上游合入**：用户审阅补丁后可手动合入 `platform-codes.yaml`（或 PR 到上游），随后引擎按新配置安装。
+
+该机制不在安装路径中强制启用、不擅自修改用户的 `platform-codes.yaml`，但提供了 IDE 升级与本工具配置之间的"探测-差量-建议-合入"完整链路，使配置驱动具备演化能力。
+
+### 3.2.7 当前已支持的平台清单（v1.12.0 实测）
+
+`platform-codes.yaml` 当前声明 20 个 IDE 平台。所有平台的 installer 配置均在 10-20 行 YAML 内完成，未单独编写 JavaScript 适配代码：
+
+| 平台 code | 平台显示名 | target_dir 示例 | skill_format | 多目标 |
+| --- | --- | --- | --- | --- |
+| `antigravity` | Antigravity | `.antigravity/` | 否 | 否 |
+| `auggie` | Auggie | `.auggie/` | 否 | 否 |
+| `claude-code` | Claude Code | `.claude/commands/` | 否 | 否 |
+| `cline` | Cline | `.cline/` | 否 | 否 |
+| `codex` | Codex | `.codex/` | 否 | 否 |
+| `codebuddy` | CodeBuddy | `.codebuddy/` | 否 | 否 |
+| `crush` | Crush | `.crush/` | 否 | 否 |
+| `cursor` | Cursor | `.cursor/rules/` | 否 | 否 |
+| `gemini` | Gemini | `.gemini/` | 否 | 否 |
+| `github-copilot` | GitHub Copilot | `.github/instructions/` + `.github/copilot-instructions.md` | 否 | **是** |
+| `iflow` | iFlow | `.iflow/` | 否 | 否 |
+| `kilo` | Kilo | `.kilo/` | 否 | 否 |
+| `kiro` | Kiro | `.kiro/skills/` | **是** | 否 |
+| `opencode` | OpenCode | `.opencode/agents/` | 否 | 否 |
+| `pi` | π | `.pi/` | 否 | 否 |
+| `qwen` | Qwen | `.qwen/` | 否 | 否 |
+| `roo` | Roo | `.roo/` | 否 | 否 |
+| `rovo-dev` | Rovo Dev | `.rovo-dev/` | 否 | 否 |
+| `trae` | Trae | `.trae/` | 否 | 否 |
+| `windsurf` | Windsurf | `.windsurf/rules/` | 否 | 否 |
+
+本方案的代码组织：通用引擎 `_config-driven.js`（1058 行，承载祖先冲突检测、遗留清理、多目标分发、制品过滤、模板渲染、技能格式转换六步流程的完整实现）+ 20 平台配置（YAML，文件 `platform-codes.yaml` 共 321 行）。每新增一个平台对引擎代码 0 改动。
+
+# 4、与第1部分所述的现有技术相比，本发明有何优点
+
+| 维度 | 独立适配器方案 | 开源 AI 框架安装器（BMAD-METHOD 等） | 本方案 | 指标改善 |
+| --- | --- | --- | --- | --- |
+| 单平台代码 | 每平台一个独立 JS 适配器文件，含扫描 / 读取 / 渲染 / 写文件 / 索引等完整骨架 | 部分采用配置 + 通用安装器，但平台差异较多仍混杂硬编码 | 每平台一节 YAML 配置（约 10-20 行），仅描述差异维度 | 平台层代码从 JS 实现转为声明式配置 |
+| 总代码量（v1.12.0 实测） | 估算每平台约数百行 JS × 20 平台，量级在数千至上万行 | 公开仓未披露统一引擎总行数 | 引擎 `_config-driven.js` 1058 行 + 配置 `platform-codes.yaml` 321 行 | 平台数线性增长不再带来 JS 代码线性放大 |
+| Bug 修复传播 | 通用逻辑 bug 须在 20 个适配器文件中分别修复 | 部分修复需触达多个适配器 | 引擎一处修复全平台生效 | 一对多 |
+| 祖先冲突检测 | 无 | 未披露符号链接穿透 + 前缀过滤 + 工具产物白名单组合 | 安装前自动检测：`fs.realpath` 解析符号链接 + 向上逐级遍历 + "xiaoma" 前缀匹配 + `xiaoma-os-` 白名单排除 | 防止运行时命令重复 |
+| IDE 能力协商 | 无 | 无 | 声明态 ∩ 运行态 → 交集裁剪 | 避免"安装超出 IDE 能力" |
+| 遗留迁移 DSL | 硬编码迁移逻辑 | 静态路径列表 | `legacy_migrations` 条件谓词 + 函数链 | 声明式表达任意复杂迁移 |
+| Capability-aware 祖先白名单 | 无 | 无 | 基于 `C_ancestor ∩ C_eff` 二次过滤 | 进一步降低祖先冲突误报 |
+| 配置自更新闭环 | 无 | 无 | 本地探测 → 差量补丁 → 人工合入 | 配置驱动具备演化能力 |
+
+## 综合有益效果
+
+| 维度 | 量化效果 | 数据来源 |
+| --- | --- | --- |
+| 性能 | 安装过程无新增运行时开销，配置加载在初始化阶段一次性完成；制品类型过滤前置避免无效模板渲染 | §3.2.2、§3.2.3 步骤 5 |
+| 可靠性 | 祖先目录冲突检测通过 `fs.realpath` 解析符号链接 + 前缀过滤判定（`_config-driven.js` 第 991 行起的 `findAncestorConflict()`、第 842 行的白名单过滤），marker 文件二次校验作为更严格的校验模式（`marker_validation: true` 启用）；多目标分发引擎自动遍历，避免"漏装一个目标"的人工失误；卸载与安装走同一份配置实现完全对称 | §3.2.3 步骤 1-2、§3.2.6 |
+| 易用性 | 新增一种 AI IDE 适配仅需在 `platform-codes.yaml` 中追加 10-20 行配置；遗留目录迁移以 `legacy_targets` 数组声明，配置即迁移 | §3.2.1、§3.2.3 步骤 3 |
+| 可维护性 | v1.12.0 实测 20 平台的安装能力由 `_config-driven.js`（1058 行）+ `platform-codes.yaml`（321 行）承载；一处 Bug 修复在引擎中生效全平台，告别"一处修二十多处"的多份适配器维护负担；技能目录格式由 `skill_format: true` 一行配置触发，无需为 Kiro 等特殊 IDE 单独编写基础转换代码 | §3.2.4、§4 表"总代码量"行 |
+
+# 5、本发明的关键点和欲保护点是什么？
+
+**【独立权利要求 1 候选的核心三件套 — 真正与既有方案区分的工程实证】**
+
+1. **祖先目录冲突检测（符号链接穿透 + 前缀过滤 + 工具产物白名单 + marker 二次校验更严格模式）**：使用 `fs.realpath` 穿透符号链接后向上逐级遍历父目录检测冲突；以"`xiaoma` 前缀匹配 + `xiaoma-os-` 白名单排除"为基础判定；marker 文件二次校验作为更严格的校验模式可由 `marker_validation: true` 启用（§3.2.3 步骤 2）。**该组合在 BMAD-METHOD 与 Yeoman/CMake/dpkg/brew 等代表性现有方案中均未披露**，是本份专利相对现有技术真正的工程创新。
+2. **IDE 能力协商协议（Capability Negotiation）**：`platform-codes.yaml` 中每个平台条目可声明 `capabilities` 集合；引擎在安装前完成"声明态 `C_decl` × 运行态 `C_runtime` × 交集 `C_eff`"三态协商，按交集结果过滤待安装制品；协商结果写入 manifest 的 `negotiated_capabilities` 字段供后续诊断（§3.2.6.1）。**与 W3C/OASIS 通信协议层的"capability negotiation"差异**：本协议发生在安装前的离线决策阶段，结果固化到 manifest，无运行时往返。
+3. **祖先冲突的 Capability-Aware 二次过滤**：祖先目录中检测到疑似冲突项时，读取该项 manifest 的 `negotiated_capabilities` 与当前安装目标的 `C_eff` 取交集；交集为空时跳过该祖先继续遍历；交集非空时叠加原前缀匹配与 marker 二次校验（§3.2.6.3）；含 manifest 缺失时退化为纯前缀判定的兼容路径。
+
+**【从属权利要求覆盖的具体实施路径与扩展机制】**
+
+4. **声明式平台配置 + 控制反转引擎架构**（**作为前述核心三件套的工程载体**）：将平台差异化信息集中声明在 YAML 配置文件中，由统一引擎动态加载并驱动安装过程；**架构思想本身（IoC、声明式配置）在 CMake、Yeoman、VS Code extensions 等成熟方案中已属常识**，本方法对其的具体改造是为承载上述核心三件套。
+5. **遗留迁移 DSL（Legacy Migration DSL）**：`legacy_migrations` 条目以 `when` 条件谓词 + `steps` 函数链表达任意复杂的迁移路径（§3.2.6.2）。
+6. **平台配置自更新闭环（Self-Update Closure）**：CLI 启动或显式触发时探测宿主 IDE 内部配置变化，生成 `patch-suggestion` 补丁存档至 `~/.xiaoma/adaptation-suggestions/`（§3.2.6.4）。
+7. **技能目录格式自动转换**：根据 `skill_format` 配置标志，自动将扁平文件制品转换为目录 + `SKILL.md` 格式（§3.2.4）。
+8. **遗留配置声明式迁移**（前述 DSL 的简化退化形式）：通过 `legacy_targets` 数组声明旧版目录路径，安装时自动清理遗留文件并递归删除空目录。
+9. **多目标分发安装机制**：单个平台配置支持声明多个安装目标目录，由引擎自动遍历并分别执行安装。**注**：单纯的"for 循环遍历数组"属于惯用技术手段，本机制不主张作为独立创新点，仅作为前述核心三件套的工程辅助实施例保留。
+
+## 5.5 建议权利要求方向（初稿，供代理人参考）
+
+**独立权利要求 1（方法 — 祖先冲突检测 + 能力协商 + Capability-Aware 二次过滤）**：
+
+一种跨平台 AI IDE 智能体安装适配方法，其特征在于，包括以下步骤：
+
+- S1：维护一个集中的平台配置文件，每个平台以声明式条目记录至少包括"目标安装目录、模板类型、支持的制品类型集合、能力集合 `C_decl`"四类属性；
+- S2：启动安装时由统一引擎遍历所述平台配置文件，对每个平台动态实例化同构的安装单元，并将该平台的配置条目作为构造参数传入；
+- S3：所述安装单元在制品类型过滤之前执行能力协商步骤：按预定义探测表读取宿主 IDE 的运行态能力集合 `C_runtime`，计算实际生效能力 `C_eff = C_decl ∩ C_runtime`，并将协商结果作为 `negotiated_capabilities` 字段写入安装清单；
+- S4：所述安装单元执行祖先目录冲突检测步骤：以 `fs.realpath` 解析符号链接后，从用户项目目录向上逐级遍历父目录，对每级父目录下的目标安装目录子目录做"特定前缀匹配 + 工具产物白名单排除"判定；当检测到疑似冲突项时，进一步读取该祖先项 manifest 中的 `negotiated_capabilities` 字段 `C_ancestor`，与当前 `C_eff` 取交集 `C_overlap`；当 `C_overlap = ∅` 时判定为"能力无重叠 → 不构成实际冲突"跳过该祖先继续向上遍历，否则确认冲突；
+- S5：所述安装单元基于 `C_eff` 对待安装制品做能力过滤后，按"目标分发 → 模板渲染"的统一流程完成安装；其中模板渲染按"平台专用模板 → 制品默认模板 → 内置兜底模板"的三层 fallback 顺序查找模板文件。
+
+**从属权利要求 2**：
+
+根据权利要求 1 所述的方法，其中所述平台配置文件采用 YAML 格式，每个平台条目支持"单目标"（`target_dir` 字符串）与"多目标"（`targets` 数组）两种互斥模式；为多目标模式时，所述安装单元自动遍历数组中各目标分别执行安装。
+
+**从属权利要求 3**：
+
+根据权利要求 1 所述的方法，进一步包括在所述祖先目录冲突检测之后、遗留目录清理之前，对每个疑似冲突的祖先目录额外查找一个或多个所述工具特有的标识文件（marker），仅当同时满足"前缀匹配 + 标识文件存在"时才判定为真实冲突；所述标识文件查找采用大小写不敏感比较以适配 macOS、Linux、Windows 三类文件系统。
+
+**从属权利要求 4**：
+
+根据权利要求 1 所述的方法，其中所述遗留目录清理的安全机制包括：(a) 以 `~` 或 `/` 开头的全局路径仅记录警告日志而不执行删除；(b) 递归删除空父目录时以预先记录的项目根目录作为终止条件而非文件系统根目录；(c) 保留预先约定前缀（如 `xiaoma-os-`）的操作系统集成文件。
+
+**从属权利要求 5**：
+
+根据权利要求 1 所述的方法，进一步包括 IDE 能力协商步骤：所述平台配置文件中每个平台条目支持声明能力集合 `C_decl`；安装单元在所述制品类型过滤步骤之前，按预定义探测表读取宿主 IDE 的运行态能力集合 `C_runtime`，并以 `C_eff = C_decl ∩ C_runtime` 作为实际生效能力集合；基于 `C_eff` 对待安装制品做能力过滤，所述协商结果作为 `negotiated_capabilities` 字段写入安装清单。
+
+**从属权利要求 6**：
+
+根据权利要求 1 所述的方法，进一步包括遗留迁移 DSL 步骤：所述平台配置文件中每个平台条目支持以 `legacy_migrations` 数组声明若干迁移条目；每个迁移条目由"条件谓词集合 `when`"与"有序变换函数链 `steps`"组成；所述条件谓词集合包括但不限于 `path_exists`、`content_matches`、`file_size_lt`、`ide_version_lt`；所述变换函数链中每个动作至少为 `move`、`rename`、`copy`、`delete`、`extract-frontmatter`、`filter-fields`、`patch-yaml`、`patch-markdown`、`exec-hook` 中之一，函数链中相邻 step 以前者的输出为后者的输入；任一 step 失败时整个条目按事先生成的快照回滚。
+
+**从属权利要求 7**：
+
+根据权利要求 1 与权利要求 5 所述的方法，进一步包括祖先冲突的能力感知二次过滤步骤：在所述祖先目录冲突检测的"前缀匹配 + 工具产物白名单"判定命中后，进一步读取该祖先目录下安装清单中的 `negotiated_capabilities` 字段得到 `C_ancestor`；与当前安装目标的 `C_eff` 取交集 `C_overlap`；当 `C_overlap = ∅` 时判定"能力无重叠 → 不构成实际冲突"，跳过当前祖先继续向上遍历；当 `C_overlap ≠ ∅` 时再叠加 marker 文件二次校验确认冲突。
+
+**从属权利要求 8**：
+
+根据权利要求 1 所述的方法，进一步包括平台配置自更新步骤：CLI 启动或用户显式触发时，按预定义探测表扫描宿主 IDE 的内部配置目录，得到 IDE 当前版本号、新增字段、新增目录约定等运行态信息；与所述平台配置文件当前条目对比生成差量补丁建议；所述差量补丁建议存档至预定义本地目录并在 CLI 输出中以提示级日志告知用户；不擅自修改所述平台配置文件，等待人工评审后由用户决定是否合入。
+
+**保护范围边界**：本方法不限定配置文件的具体格式（YAML/JSON/TOML 均为等效替代）；不限定具体的 IDE 平台数量（≥2 即落入权利要求 1 保护范围；20 平台为优选实施例）；不限定模板渲染引擎（轻量正则替换、Handlebars、EJS 等均可）；不限定 capabilities 集合的具体元素枚举（按 IDE 演进可扩展）；不限定能力探测表的具体探测方式（命令输出、文件系统 marker、socket 通信等均为等效替代）。
+
+# 6、针对第3部分的技术方案，是否还有别的替代方案同样能完成发明目的？
+
+| 替代方案 | 核心做法 | 与本方案对比 |
+| --- | --- | --- |
+| 一、配置格式改用 JSON | 平台配置文件采用 `platform-codes.json` 格式替代 YAML | 解析速度更快，无缩进敏感问题；缺点是无注释支持，可读性略差；技术效果无实质差异 |
+| 二、模板引擎改用 Handlebars/EJS | 渲染采用成熟模板引擎，支持 `{{#if}}` `{{#each}}` 条件循环语法 | 模板能力更强，但引入额外依赖（增加约 80KB 安装体积）；当前简单 `{{var}}` 替换已满足需求，权衡后保留轻量实现 |
+| 三、祖先冲突检测改为安装后 | 安装完成后扫描祖先目录验证结果 | 可同时验证安装正确性，但会造成不必要的文件写入和回滚操作；本方案前置检测整体效率更高 |
+
+# 7、与代表性现有技术的逐项对照
+
+| 关键点 | 独立适配器方案 | BMAD-METHOD 安装器 | Yeoman 生成器 | OS 包管理器（apt/brew） | 本方案 |
+| --- | --- | --- | --- | --- | --- |
+| 声明式平台配置 + 控制反转引擎 | ✗ | △（部分） | △（依赖 prompt 流程） | ✗ | ✓ |
+| 祖先目录冲突检测（符号链接穿透 + 前缀过滤 + 工具产物白名单） | ✗ | ✗ | ✗ | ✗（dpkg/brew 仅检查 owner） | ✓ |
+| 多目标分发（单平台双目录） | ✗ | ✗ | ✗ | ✗ | ✓ |
+| 技能目录格式自动转换（含 frontmatter 白名单过滤） | ✗ | △（仅扁平输出） | ✗ | ✗ | ✓ |
+| 遗留目录声明式清理 | ✗ | ✗ | ✗ | △（postrm 脚本但非声明式） | ✓ |
+| IDE 能力协商协议 | ✗ | ✗ | ✗ | ✗ | ✓ |
+| 遗留迁移 DSL（条件谓词 + 函数链） | ✗ | ✗ | ✗ | ✗（脚本式） | ✓ |
+| 祖先冲突 Capability-Aware 二次过滤 | ✗ | ✗ | ✗ | ✗ | ✓ |
+| 平台配置自更新闭环 | ✗ | ✗ | ✗ | ✗ | ✓ |
+
+可见关键点 1、2、6、7、8、9 在所列代表性现有技术中均未披露；关键点 3、4、5 在所列方案中仅有零星部分披露，未见同等组合。
+
+# 附图说明
+
+**附图1 — 配置驱动安装方法整体流程图**
+
+![附图1 - 整体流程](media/doc2_fig1.png)
+
+从读取 `platform-codes.yaml` 到各平台完成安装的完整流程。
+
+**附图2 — 三层架构示意图**
+
+![附图2 - 三层架构](media/doc2_fig2.png)
+
+平台管理层（`IdeManager`）→ 通用安装引擎层（`ConfigDrivenIdeSetup`）→ 平台配置声明层（`platform-codes.yaml`）的层次关系。
+
+**附图3 — 祖先冲突检测 + Marker 校验流程**
+
+![附图3 - 祖先冲突检测](media/doc2_fig3.png)
+
+祖先检测 → Marker 校验 → 遗留清理 → 多目标分发 → 制品过滤 → 模板渲染 → 格式转换的顺序执行关系。
+
+**附图4 — 技能目录格式转换对比图**
+
+![附图4 - 技能目录格式转换](media/doc2_fig4.png)
+
+扁平文件格式到目录 + `SKILL.md` 格式的转换过程，含 frontmatter 字段过滤示意。
+
+
+## 附图源码（Mermaid，供绘图工程师参考重绘）
+
+**附图1 — 整体流程**
+
+```mermaid
+flowchart TD
+    A[读取 platform-codes.yaml] --> B[IdeManager 初始化]
+    B -->|按平台实例化| C[ConfigDrivenIdeSetup]
+    C --> D[祖先冲突检测]
+    D -->|疑似冲突| E[Marker 文件二次校验]
+    E -->|确认冲突| F[失败返回]
+    E -->|非真实冲突| G[遗留配置清理]
+    D -->|无冲突| G
+    G --> H[多目标分发]
+    H --> I[制品类型过滤]
+    I --> J[模板三层 fallback 渲染]
+    J --> K[技能格式转换]
+    K --> L[写入目标目录]
+```
+
+**附图2 — 三层架构**
+
+```mermaid
+flowchart TB
+    subgraph L1[平台管理层 IdeManager]
+        M1[install/uninstall API]
+    end
+    subgraph L2[通用安装引擎 ConfigDrivenIdeSetup]
+        E1[祖先检测] --> E2[遗留清理] --> E3[多目标分发]
+        E3 --> E4[类型过滤] --> E5[模板渲染] --> E6[格式转换]
+    end
+    subgraph L3[平台配置声明 platform-codes.yaml]
+        Y1[claude] 
+        Y2[cursor]
+        Y3[kiro]
+        Y4[copilot 多目标]
+    end
+    L1 --> L2
+    L2 -.动态加载.-> L3
+```
+
+**附图3 — 祖先冲突检测 + Marker 校验**
+
+```mermaid
+flowchart TD
+    A[从项目目录向上遍历] --> B{祖先目录存在<br/>target_dir 子目录?}
+    B -->|否| C[继续向上]
+    B -->|是| D{子目录含<br/>xiaoma 前缀文件?}
+    D -->|否| C
+    D -->|是| E[Marker 二次校验:<br/>查找 xiaoma-os 或<br/>.xiaoma-manifest]
+    E -->|存在 marker| F[确认冲突, 失败返回]
+    E -->|无 marker| G[误识别, 跳过]
+    C --> H{到达文件系统根?}
+    H -->|否| A
+    H -->|是| I[无冲突, 继续安装]
+```
+
+**附图4 — 技能目录格式转换**
+
+```mermaid
+flowchart LR
+    subgraph FLAT[扁平文件源]
+        F1[/agents/po.md/]
+        F2["frontmatter:<br/>name, description,<br/>disable-model-invocation, ..."]
+    end
+    subgraph DIR[技能目录目标]
+        D1[/.kiro/skills/po//]
+        D2[/.kiro/skills/po/SKILL.md/]
+        D3["frontmatter 过滤后:<br/>仅保留 name, description"]
+    end
+    F1 --> D1
+    F2 -.字段过滤.-> D3
+    D3 --> D2
+```