ai agent

2026-09-10 17:03:10 +02:00
parent 90dc18a167
commit 3a3d70efeb
27 changed files with 4973 additions and 3 deletions
@@ -0,0 +1,773 @@
+# RA3 Mod XML AI Agent 接入计划与进度追踪
+
+> 状态：实施中  
+> 创建时间：2026-09-09  
+> 目标：让 AI Agent / 其他工具能够方便、可靠地使用 RA3 Mod XML 扩展构建的语义索引。
+
+---
+
+## 进度追踪
+
+| 阶段 | 内容 | 状态 |
+|---|---|---|
+| Phase 0 | 计划与进度文件 | ✅ 完成 |
+| Phase 1 | 外部快照格式与导出命令 | ✅ 完成 |
+| Phase 2 | 查询核心与 CLI | ✅ 完成 |
+| Phase 3 | MCP Server | ✅ 完成（基础 stdio MCP） |
+| Phase 4 | MCP 配置助手 / 稳定 launcher | ✅ 完成（launcher + 启用命令 + Claude/Cursor 配置写入 + 复制配置） |
+| Phase 5 | Agent Skill 安装器 | ✅ 完成（默认安装 + 多位置选择 + 安装记录 + 卸载/同步函数） |
+| Phase 6 | Live 查询与快照合并策略 | ✅ 完成（本地只读 HTTP live server + endpoint 文件 + MCP 在线优先/离线兜底 + final 索引静默 5 秒自动快照） |
+| Phase 7 | 测试、文档、发布 | 🟡 部分完成（README + 计划文档已更新；全部 31 个 test/*.test.mjs 逐个直接运行通过；已用直接 esbuild CLI 验证 dist 构建与 MCP smoke test；`node --test` 受沙箱限制，尚未 VSIX 打包/发布） |
+
+### 二期进度（2026-09-10）
+
+| 阶段 | 内容 | 状态 |
+|---|---|---|
+| 二期 A1 | live 响应携带 `projectDir`，MCP 侧校验 | ✅ 完成 |
+| 二期 A2 | endpoint 按项目分文件（保留全局兜底） | ✅ 完成 |
+| 二期 A3 | live server 支持 `?project=` 路由（不再只看活动编辑器） | ✅ 完成 |
+| 二期 A4 | 关闭窗口只清理自己写的 endpoint | ✅ 完成 |
+| 二期 A5 | `processId` 存活校验 | ✅ 完成 |
+| 二期 A6 | live 失败负缓存 | ✅ 完成 |
+| 二期 A7 | `snapshotBaseName` 改为 sha1 前缀 + 可读 slug | ✅ 完成 |
+| 二期 B1 | Skill 适用范围段落（正/负信号 + `get_status` 探针） | ✅ 完成 |
+| 二期 C1 | `get_asset_references`：有界、带 provenance 的正向引用查询 | ✅ 完成 |
+| 二期 C2 | 本地 HTTP `/get_asset_references` 与 MCP 工具接入 | ✅ 完成 |
+| 二期 C3 | 二期测试与文档 | ✅ 完成（264/264 测试通过） |
+
+---
+
+## 1. 背景与目标
+
+当前 RA3 Mod XML 扩展已经能构建大型项目的语义索引，包括：
+
+- asset 定义：`type / id / file / line / origin / stream`
+- `$DEFINE`
+- `<Include>` / `xi:include` 关系
+- 语义引用和反向引用
+- manifest 资产
+- `.w3x` art 资产
+
+这些能力目前主要服务于 VS Code 编辑器内部。  
+本计划的目标是：
+
+1. 让 AI Agent、脚本和其他工具能够方便、可靠地使用该索引；
+2. 不需要用户注册全局 CLI / 修改 PATH；
+3. 安装/更新扩展后能通过一次性设置完成接入；
+4. 在用户持续编辑代码时，索引查询仍然足够实时且不会造成磁盘写放大；
+5. 为 AI Agent 提供工具 + 引导 Skill，让它知道何时、如何调用索引。
+
+---
+
+## 2. 核心设计决策
+
+### 2.1 不采用“全局 CLI + PATH”作为主入口
+
+CLI 可以作为高级/调试工具保留，但不是默认路径。
+
+### 2.2 以 MCP Server 作为 AI Agent 主接口
+
+MCP Server 使用本地 stdio 启动，通过绝对路径配置即可，不需要 PATH。
+
+### 2.3 内存索引为主，磁盘快照为辅
+
+- 实时查询尽量走 VS Code 扩展内存中的 `ModIndex`；
+- 磁盘只保存低频、合并后的“当前稳定快照”作为离线兜底；
+- 避免用户连续编辑保存时产生大量磁盘 IO。
+
+### 2.4 Agent Skill 是可选增强层
+
+MCP 注册解决“工具可用”，Skill 解决“Agent 知道怎么用好工具”。  
+Skill 不作为启用 MCP 的强制条件。
+
+### 2.5 所有查询结果都携带索引状态
+
+外部接口必须返回：索引是否存在、是否正在构建、是否完整、是否 stale、数据版本/时间。
+
+---
+
+## 3. 目标架构
+
+```text
+VS Code 扩展
+   │
+   ├── 内存 ModIndex
+   │       │
+   │       ├── 本地只读查询服务（可选，热数据）
+   │       └── 低频快照导出（冷数据）
+   │
+   ├── MCP 配置助手
+   │       └── 写入 AI 客户端配置 + 稳定 launcher
+   │
+   └── Agent Skill 安装器
+           └── 安装到 ~/.agents/skills 等位置
+
+AI Agent / 外部工具
+   │
+   ├── MCP Server（推荐）
+   │       ├── 扩展在线 → 查询内存/本地服务
+   │       └── 扩展离线 → 读取最近稳定快照
+   │
+   ├── CLI（可选）
+   └── HTTP/JSON-RPC（可选）
+```
+
+---
+
+## 4. 组件设计
+
+### 4.1 外部快照格式
+
+定义一份稳定、公开的快照 schema，不直接暴露内部 workspaceStorage 缓存。
+
+```json
+{
+  "schemaVersion": 1,
+  "project": "D:/Mods/CoronaMod/mods/mods/corona",
+  "generatedAt": "...",
+  "buildId": 128,
+  "phase": "art",
+  "complete": true,
+  "stale": false,
+  "stats": {
+    "assetCount": 38304,
+    "referenceCount": 97862,
+    "defineCount": 240,
+    "streamCount": 12
+  },
+  "assets": [
+    {
+      "type": "GameObject",
+      "id": "...",
+      "file": "Data/...",
+      "line": 10,
+      "origin": "project",
+      "stream": "static",
+      "viaInstance": false
+    }
+  ],
+  "defines": [],
+  "references": [],
+  "includeGraph": [],
+  "sourceCandidates": []
+}
+```
+
+生成方式：
+
+- 从 `ModIndex` 导出；
+- 使用数组而不是 JS Map；
+- 原子写入：`temp + rename`；
+- 同一项目只维护 `current` 快照，不保留每次历史版本；
+- 可选维护 `previous` 用于构建期间回退。
+
+### 4.2 MCP Server
+
+MCP Server 不直接持有完整索引，而是作为查询代理：
+
+1. 扩展在线时，转发到 VS Code 扩展的本地只读查询服务；
+2. 扩展离线时，读取最近一次稳定快照；
+3. 所有工具返回结果时附带索引状态。
+
+建议 MCP 工具集：
+
+```text
+get_status()
+list_projects()
+find_asset(id, type?)
+find_references(id, type?)
+list_assets_by_type(type, prefix?, limit?)
+get_definition(type, id)
+resolve_include(source)
+is_file_active(path)
+find_define(name)
+get_usage_guide()
+```
+
+### 4.3 稳定 launcher 与 MCP 配置助手
+
+扩展安装路径会随版本变化，所以不能直接写死在 MCP 配置里。
+
+稳定入口：
+
+```text
+~/.ra3modxml/
+  ra3-mod-xml-mcp.cmd
+  projects.json
+  snapshots/
+    current.json.gz
+    meta.json
+  skill-install.json
+```
+
+MCP 配置示例：
+
+```json
+{
+  "mcpServers": {
+    "ra3-mod-xml": {
+      "command": "C:\\Users\\lanyi\\.ra3modxml\\ra3-mod-xml-mcp.cmd",
+      "args": ["--project", "D:\\Mods\\CoronaMod\\mods\\mods\\corona"]
+    }
+  }
+}
+```
+
+扩展每次激活/升级时刷新 launcher 内容，指向当前扩展安装目录。  
+这样 MCP 配置只需要写一次，升级不断。
+
+### 4.4 Agent Skill
+
+默认安装：
+
+```text
+~/.agents/skills/ra3-mod-xml/
+├── SKILL.md
+└── references/
+    └── query-guide.md
+```
+
+Skill 内容原则：
+
+- 只描述功能本身；
+- 说明“什么情况下该用这个 Skill”以及“怎么用”；
+- 不引用各个工作区里的具体文档，例如 `docs/codebase-navigation-guide.md`，避免注意力噪音；
+- 保持通用，不绑定某个 mod。
+
+Skill 内容建议包括：
+
+- 索引覆盖范围和状态含义；
+- MCP 工具用途；
+- 推荐查询工作流：
+  - 从 ID 找定义 → `find_asset`
+  - 找所有引用 → `find_references`
+  - 确认文件是否 active → `is_file_active`
+  - 追继承链 → `find_references` + `find_asset`
+  - 找未引用资产 → `unreferenced`
+- 使用规则：
+  - 优先查询索引，而不是全项目 `rg`；
+  - 查询尽量带 type，避免同名不同类型混淆；
+  - 不要把整个索引快照读进上下文；
+  - 如果索引状态不是 ready/stale，应查询状态或重试。
+
+### 4.5 索引状态与一致性
+
+定义索引状态：
+
+| 状态 | 含义 |
+|---|---|
+| `no_index` | 从未构建 |
+| `building` | 正在构建/重建 |
+| `ready_xml` | XML phase 已发布，art 未完成 |
+| `ready` | 完整 final 索引 |
+| `stale` | 构建期间有文件变化 |
+| `error` | 构建失败但保留 last good |
+
+查询接口支持两种模式：
+
+- 默认 / eventual：有可用快照就返回，同时附带 `stale/incomplete` 标记；
+- 严格 / consistent：调用方传 `wait_for_index=true` / `allow_stale=false`，等待新 final 索引或超时。
+
+### 4.6 持久化策略
+
+- 热数据：内存 `ModIndex`；
+- 实时查询：本地查询服务 / MCP 转发；
+- 冷数据：低频快照，例如：
+  - 用户手动导出；
+  - 索引稳定一段时间后自动写一次；
+  - 扩展退出前写一次（尽力而为）；
+- 不每次 rebuild 都写全量快照。
+
+### 4.7 用户交互流程
+
+安装/更新扩展后：
+
+1. 首次索引完成；
+2. 如果尚未启用且未被用户忽略，弹出提示：
+
+```text
+RA3 Mod XML 索引已就绪。
+是否让 AI Agent 使用索引查询能力？
+```
+
+3. 用户点击“启用”；
+4. 扩展默认注册 MCP Server；
+5. 同时询问/默认勾选：
+
+```text
+[✓] 同时安装 RA3 Mod XML Agent Skill（推荐）
+```
+
+6. 写入 MCP 配置；
+7. 安装 Skill 到 `~/.agents/skills/ra3-mod-xml/`；
+8. 提供“安装到其他位置”或“手动操作指南”。
+
+### 4.8 安全设计
+
+- 本地查询服务只监听 `127.0.0.1`；
+- 使用随机 token；
+- MCP Server 默认只读，不提供文件修改/命令执行工具；
+- 写 MCP 配置前必须用户同意；
+- Skill 安装目录记录 managed marker，避免覆盖用户自定义内容。
+
+---
+
+## 5. 实施阶段
+
+### Phase 1：外部快照格式与导出命令
+
+- 新增 `src/agent/snapshot.ts`
+- 新增命令：`ra3modxml.exportIndexSnapshot`
+- 定义 `schemaVersion`
+- 从 `ModIndex` 生成可序列化快照
+- 原子写入 `~/.ra3modxml/snapshots/current.json.gz`
+- 输出状态元数据
+
+### Phase 2：查询核心与 CLI
+
+- 复用纯 TS `indexer` 模块；
+- 新增 `src/agent/query.ts`：
+  - `findAsset`
+  - `findReferences`
+  - `isFileActive`
+  - `listAssetsByType`
+  - `getStatus`
+- 新增 CLI 入口（可选）：
+  - 不注册 PATH；
+  - 通过绝对路径调用；
+  - 供脚本/调试使用。
+
+### Phase 3：MCP Server
+
+- 新增 `src/agent/mcpServer.ts`
+- 支持 stdio 协议；
+- 启动时读取连接信息/快照；
+- 提供前述 MCP 工具；
+- 每个响应带索引状态。
+
+### Phase 4：MCP 配置助手
+
+- 新增 `src/agent/setup.ts`
+- 创建稳定 launcher；
+- 检测/写入常见客户端配置：
+  - Claude Desktop
+  - Cursor
+  - Codex
+  - 通用 JSON
+- 提供“复制 MCP 配置”；
+- 提供手动操作指南。
+
+### Phase 5：Agent Skill 安装器
+
+- 新增 `src/agent/skill.ts`
+- 生成 `SKILL.md` + `references/query-guide.md`
+- 默认安装到 `~/.agents/skills/ra3-mod-xml/`
+- 可选安装到：
+  - `~/.claude/skills/ra3-mod-xml/`
+  - 项目 `.agents/skills/`
+  - 项目 `.claude/skills/`
+  - 自定义位置
+- 记录已安装位置，扩展升级时自动同步；
+- 不覆盖用户自定义内容。
+
+### Phase 6：Live 查询与快照合并
+
+- 在扩展内启动本地只读查询服务；
+- MCP Server 在线时优先转发到扩展；
+- 离线时读取 `current.json.gz`；
+- 实现快照 quiet-period 合并写入，避免频繁全量落盘；
+- 实现状态机：`no_index / building / ready_xml / ready / stale / error`。
+
+### Phase 7：测试、文档、发布
+
+- 测试快照导出/导入一致性；
+- 测试 MCP 工具查询；
+- 测试 Skill 安装/更新/卸载；
+- 测试持续编辑场景下的状态与 stale 行为；
+- 更新 README / docs；
+- 发布新版本。
+
+---
+
+## 6. 预估文件改动
+
+### 新增文件
+
+```text
+src/agent/
+  types.ts
+  snapshot.ts
+  query.ts
+  mcpServer.ts
+  setup.ts
+  skill.ts
+  localServer.ts
+  launcher.ts
+
+docs/
+  ai-agent-integration-plan.md
+```
+
+### 修改文件
+
+```text
+package.json                 # commands / configuration
+src/extension.ts             # 注册命令、设置、初始化
+src/workspace.ts             # 暴露 index status / snapshot 发布钩子
+src/features/agentSetup.ts   # 用户引导 UI（或并入 agent/setup.ts）
+```
+
+---
+
+## 7. 验收标准
+
+1. 用户安装/更新扩展并完成一次索引后，可以看到“启用 AI Agent 访问”的引导。
+2. 用户点击启用后，不需要手动配置 PATH，不需要手动查找 workspaceStorage。
+3. 常见 AI 客户端能通过 MCP 调用索引工具。
+4. Agent 能正确回答：
+   - “某 asset 定义在哪个文件？”
+   - “谁引用了这个 asset？”
+   - “这个 XML 文件是否真的被 Include？”
+5. 查询接口在无索引/索引更新中不会返回误导性空结果。
+6. 用户连续编辑保存时，不会因为频繁快照写入而产生明显卡顿或磁盘膨胀。
+7. Skill 安装后，Agent 知道优先使用 MCP 查询，而不是全文 grep。
+8. 扩展升级后，MCP 配置仍然有效，Skill 能自动同步到已安装位置。
+
+---
+---
+
+# 第二部分：二期计划（讨论结论 + 实施）
+
+> 讨论时间：2026-09-10
+> 主题：Skill 的项目识别边界、正向/间接引用查询的取舍、MCP 与 localhost 架构现状
+
+---
+
+## 8. 讨论结论一：谁来判定"这是不是一个红警 3 模组项目"
+
+### 问题
+
+Skill 需要说明"何时应该被使用"和"适用范围"。这要求 Agent 能理解什么是
+"红警 3 模组项目里的 XML"，同时避免把无关项目误判为 RA3 模组。
+
+问题在于：这个判断应该由扩展/Skill 自己解释（甚至给出推断规则），还是应该
+由项目开发者在自己的项目文档 / `AGENTS.md` 里声明？
+
+### 结论：分层，且 Skill 不做复杂推断
+
+| 层 | 职责 | 理由 |
+|---|---|---|
+| **Skill** | 说明能力覆盖范围 + 少量正/负信号 + 便宜的探测方式 | Skill 是用户全局的，会在**所有**对话里加载，必须简短且能自我限制 |
+| **项目开发者**（`AGENTS.md` / README / 项目标记） | 声明"这个仓库是什么项目、要不要用这些工具" | 只有项目自己知道自己是什么，这是每个仓库的局部事实 |
+| **MCP 工具自身** | 用响应证明自己是否可用 | `get_status` 是最便宜的判定，不应靠读文档猜 |
+
+### 为什么不把判断规则写进 Skill
+
+- Skill 在 `~/.agents/skills/` 下全局生效；如果写一堆判定规则，会在与 RA3
+  无关的项目里制造"要不要用这个工具"的注意力噪音。
+- 规则永远不完备。真实反例：
+  - 目录里有 `Schemas/xsd/CnC3Types.xsd` → 可能只是 SDK 本身，不是 mod；
+  - 只有一堆从 SDK 抄来的 `.xsd` → 是"RA3 相关"，但没有 mod 数据；
+  - `CnC3Types.xsd` 里的 `CnC3` 指 **C&C3**（命令与征服 3 / 凯恩之怒），
+    所以"存在 CnC3Types.xsd" **不等于** "是 RA3 模组"；
+  - 有 `Data/Mod.xml` / `*.babproj` / `Data/additionalmaps/mapmetadata_*.xml`
+    → 基本可确认是 **SAGE / BinaryAssetBuilder** 系项目（RA3 只是其中之一）。
+- 一旦误判，Agent 会拿 RA3 的索引数据去回答另一个项目的问题，比不使用更糟。
+
+### 落地方案
+
+**Skill 侧**（`src/agent/skill.ts` 的 `SKILL_MD`）新增 applicability 段落：
+
+- 正向信号（任一命中即可尝试）：
+  `Data/Mod.xml`；`Data/additionalmaps/mapmetadata_*.xml`；`*.babproj`；
+  XML 根为 `<AssetDeclaration>`；使用 `<Includes><Include source="DATA:…"/></Includes>`。
+- 明确否定：无关仓库、仅含拷贝 `.xsd` 的项目、通用 XML 配置、构建脚本、
+  非 SAGE 游戏项目。
+- 便宜的探针：不确定时先调 `get_status`；它返回索引归属的 `projectDir`。
+  如果与当前工作区根不一致，或状态是 `no_index`，就**停止使用索引工具**，
+  改为直接读文件。
+
+这样即使误触发，成本也只是一次 `get_status`，不会污染后续推理。
+
+**项目开发者侧**：在项目根 `AGENTS.md` 写一句即可，例如：
+
+```markdown
+## RA3 Mod tooling
+This repository is a Red Alert 3 mod (SAGE XML). When locating asset
+definitions or references, prefer the `ra3-mod-xml` MCP tools
+(`find_asset`, `find_references`, `is_file_active`) over full-text search.
+```
+
+扩展**不自动**往用户仓库写标记文件（如 `.agents/ra3-mod-xml-project.json`）
+作为二期内容；若将来提供，必须显式确认。
+
+---
+
+## 9. 讨论结论二：要不要提供"某个 Asset 直接/间接引用的所有 Asset"
+
+### 场景
+
+用户要求 Agent"查阅或修改雅典娜炮的武器"。Agent 需要：
+
+1. 找到雅典娜炮的 GameObject；
+2. 读源码，发现 `<FireWeaponUpdate />` / `<WeaponSetUpdate />` 等子元素，
+   在这些子元素里找到武器引用；
+3. 若 `<CreateObjectDie />` 引用了临时物体，还要去读临时物体的 GameObject，
+   在它的 `FireWeaponUpdate` 里找武器；
+4. 若雅典娜炮只有 `FireWeaponUpdate`、`WeaponSetUpdate` 在
+   `inheritFrom` 的 `BaseCannon` 上，还要读 `BaseCannon` 并综合判断。
+
+评估问题：
+
+- 是否有必要提供"某个 Asset 直接或间接引用的所有 Asset"？
+- 只给精炼 asset 列表，Agent 不知道是哪个子元素导致的引用，有用吗？
+- 若同时提供上下文，磁盘/内存/性能允许吗？内容长度会不会反而比直接读源码更贵？
+- 相对直接读源码未必有显著提升，反而增加注意力噪音？
+- 间接引用会不会多项式/指数爆炸？
+
+### 先指出当前实现的真实缺口
+
+现在的索引只有**反向**引用（谁引用了我），没有**正向**查询（我引用了谁）。
+`find_references(AthenaCannon)` 返回的是"谁引用了雅典娜炮"，而不是"雅典娜炮
+用了哪些武器"。所以上述 Agent 工作流**目前完全无法用工具完成**，只能读源码。
+
+因此问题不是"要不要锦上添花"，而是这里确实缺一个基础能力。
+
+### 结论：不提供"所有可达 Asset 的扁平闭包"，改提供"有界 + 带 provenance 的边列表"
+
+**不采用扁平静态闭包的理由：**
+
+1. **丢失 provenance，Agent 仍然要读源码。** 到底是 `FireWeaponUpdate` 的武器、
+   `WeaponSetUpdate` 的武器、`CreateObjectDie` 临时物体的武器，还是
+   `inheritFrom` 继承来的武器？这决定了 Agent 改哪个文件、加不加
+   `xai:joinAction`。丢掉上下文，列表基本没用。
+2. **尺寸会失控。** 一个 GameObject 的可达闭包可能是
+   `Weapon → Projectile → Warhead → DamageNugget → FX → Particle → Texture`、
+   `Model → Mesh → Material → Texture`、`AttributeModifier`、`Upgrade`、`Command`、
+   `Button`……Corona 规模下单个单位几百到上千节点完全可能。200 条边就是几万
+   token，**比直接读 3 个小 XML 文件贵得多**。
+3. **注意力噪音。** 列表里 80% 是与当前问题无关的 Texture / FX 时，推理质量下降。
+4. **"间接"的诱惑会持续膨胀。** 一旦提供无界闭包，Agent 会习惯性调用它，
+   然后被淹没。
+
+**但以下特性确实值得工具化：**
+
+- 多跳遍历是**纯机械**的，正是工具该做的事；
+- `inheritFrom` 链 + `xai:joinAction` 语义很微妙，Agent 手推容易错；
+- 每跳都 read 一个文件，Corona 下成本和 token 都很高；
+- 工具可以做到**确定性、不遗漏**（按 XSD 判定"哪些属性是引用"，
+  而不是靠 Agent 逐个注意）。
+
+**设计要点（二期实现遵循）：**
+
+- 返回**边列表**而不是节点集合。每条边携带：
+  - `from`（effective asset）、`to`（解析出的定义位置）、
+  - `via.kind`（`attribute` / `content` / `inheritFrom`）、
+  - `via.element`、`via.parent`、`via.attribute`，
+  - `source.file` / `source.line`（XML 实际所在位置），
+  - `definedIn`（当该边来自 `inheritFrom` 祖先的 XML 时，标明真正写它的资产）。
+- **默认 `depth: 1`，硬上限 3。** Agent 拿到直接引用后自己决定是否对某个具体
+  节点递归，比一次性 dump 闭包更省 token、更有针对性。
+- **`targetTypes` 过滤**是抑制噪音最有效的手段。雅典娜炮场景就是
+  `targetTypes: ["WeaponTemplate"]`（可选再带 `GameObject` 给 `CreateObjectDie`），
+  返回可能只有 3–10 条边。
+- **`inheritFrom` 不消耗 depth**：继承是资产自身定义的一部分，不是运行时引用。
+  因此在同一 depth 内递归遍历继承链（链长上限 8），并把 `definedIn` 标出来。
+- **截断时返回 `omittedByTargetType` 摘要**，让 Agent 知道被砍掉了什么形状的数据，
+  可以精确下钻，而不是无脑重试或放弃。
+- **不提供"合并后的有效值"**：`joinAction` 的 Replace/Remove/merge 语义算错的风险
+  太高，一期不做。
+
+**关于爆炸和成本：**
+
+- 算法上不是指数：带 visited-set 的 BFS 是 `O(V+E)`。真正的风险是**语义宽度**，
+  不是复杂度，因此用 `depth` + `targetTypes` + `maxEdges` 三重限制。
+- **只做 live 查询**（VS Code 打开时可用）。要拿元素上下文，最干净的做法是按需
+  解析定义所在文件的 DOM，而不是往 records 缓存里塞元素名/属性名 —— Corona 有
+  ~98k 条引用记录，再塞 5 个字符串字段会让常驻内存明显膨胀，为一个默认 `depth=1`
+  的功能付出这个成本不划算。
+- 离线快照路径明确返回"需要 live index"，而不是静默返回空结果。
+
+---
+
+## 10. 讨论结论三：MCP / localhost 的实际架构与多窗口缺陷
+
+### 当前架构（事实）
+
+```text
+AI 客户端
+   │  stdio (JSON-RPC, MCP)
+   ▼
+dist/agent/mcpServer.js          ← 由 AI 客户端启动，参数 --project <dir>
+   │  HTTP (127.0.0.1:临时端口, Bearer token)
+   ▼
+VS Code 扩展进程内的 localServer  ← 仅在"启用 AI Agent 访问"后启动
+   │
+   ├─ 在线 → ws.activeIndex() 实时内存索引
+   └─ 离线 → ~/.ra3modxml/snapshots/project-<hash>.json.gz
+```
+
+- **AI 客户端不需要知道端口。** MCP Server 自己读
+  `~/.ra3modxml/endpoint.json` 拿 `url` + `token` 再 `fetch`。localhost 层是
+  纯实现细节。
+- **端口**：`server.listen(port ?? 0, "127.0.0.1")`，即由操作系统分配临时端口，
+  不会冲突；当前未传 `port`，所以永远是临时端口。
+- **鉴权**：`Authorization: Bearer <token>`，token 为启动时随机生成；绑定
+  `127.0.0.1`，局域网访问不到。
+- **降级**：live 查询失败（endpoint 不存在 / 连接被拒 / 超时 1.5s）时回退到快照。
+
+### 多项目 / 多 VSCode 窗口的真实缺陷
+
+`endpoint.json` 是**全局唯一**的一个文件，所有 VSCode 窗口都往它写入：
+
+1. **最后启用的窗口覆盖前面所有窗口。** 两个窗口都启用了 Agent 访问时，
+   只有后启动的那个能被 MCP Server 找到。
+2. **可能串项目（严重）。** 假设窗口 B 覆盖了 endpoint，而某个 MCP Server 是用
+   `--project 窗口A` 启动的，它的 `tryLiveQuery` 会打到**窗口 B** 的 server，
+   拿到窗口 B 的索引数据，而返回值里没有任何东西能暴露这个不一致。
+   这比 `no_index` 危险得多 —— 会静默给出错误答案。
+3. **关闭任意窗口都会 `clearEndpoint()`**，把还开着的其他窗口的 live 通道一起断掉。
+4. **同一窗口内多项目也不稳。** live server 用
+   `getIndex: () => ws.activeIndex()`，而 `activeIndex()` 跟着**当前活动编辑器**走。
+   用户切到另一个项目的文件，live 查询就会静默换项目；而 `endpoint.json` 里的
+   `projectDir` 只在启动时写一次，之后不更新。
+5. `processId` 虽然写进了 endpoint，但**从未被校验**；VSCode 崩溃后残留的 endpoint
+   只能靠连接失败兜底。
+6. 离线快照路径是**正确**的 —— `snapshotPathForProject()` 按项目路径做 hash，
+   多项目互不干扰。问题只在 live 层。
+
+### 修复方案（二期 A，按性价比排序）
+
+1. **live 响应必须带 `projectDir`，MCP 侧必须校验它和 `--project` 一致**，
+   不一致就直接走快照。这是最小的正确性补丁，最先做。
+2. **endpoint 按项目存**：`~/.ra3modxml/endpoints/<project-hash>.json`，
+   MCP Server 按 `--project` 找对应的那个；同时保留 `endpoint.json` 作为
+   "最近"的兼容入口。
+3. **live server 支持 `?project=` 路由**，而不是只认 `activeIndex()`。
+   扩展侧加 `indexForProject(projectDir)`，一个窗口的一个 server 就能服务它
+   所有已索引项目，也就不怕用户切编辑器。
+4. **关闭时只清自己的那一条**，不无条件删全局 endpoint。
+5. **校验 `processId` 是否存活**，不存活就当 endpoint 失效。
+6. `tryLiveQuery` 失败后做几秒的"live 不可用"负缓存，避免每次调用都试一次。
+7. `snapshotBaseName` 换成 sha1 前缀 + 可读 slug（与 `diskCacheKey` 一致的做法），
+   降低碰撞概率。
+
+---
+
+## 11. 二期实施清单
+
+### 二期 A：多窗口 / 多项目正确性
+
+- `src/agent/snapshot.ts`：新增 `projectHash()`；`snapshotBaseName()` 改为
+  `<slug>-<sha1-12>`。
+- `src/agent/endpoint.ts`：新增
+  `endpointPathForProject()` / `writeEndpointForProject()` /
+  `readEndpointForProject()` / `clearEndpointForProject()` / `isProcessAlive()`。
+- `src/workspace.ts`：新增 `indexForProject(projectDir)`。
+- `src/agent/liveQuery.ts`：`liveStatus()` 在没有索引时回落到请求的 `projectDir`。
+- `src/agent/localServer.ts`：`getIndex(projectDir?)` 路由、异步 handler、
+  `/projects` 端点、所有响应携带 `index.projectDir`。
+- `src/agent/mcpServer.ts`：按项目读 endpoint、校验 `projectDir` 与 `processId`、
+  `?project=` 透传、live 失败负缓存、响应 `projectDir` 二次校验。
+- `src/extension.ts`：启动时按项目写 endpoint、关闭时只清自己写过的那些。
+
+### 二期 B：Skill 适用范围
+
+- `src/agent/skill.ts`：`SKILL_MD` 增加 applicability 段落（正向信号、明确否定、
+  `get_status` 探针）；保持"不引用工作区文档"的原则。
+
+### 二期 C：`get_asset_references`
+
+- `src/agent/forwardRefs.ts`（新增）：DOM-based、有界、带 provenance 的正向引用遍历。
+- `src/agent/localServer.ts`：新增 `GET /get_asset_references`。
+- `src/agent/mcpServer.ts`：新增 `get_asset_references` 工具（live-only，
+  离线时返回明确的"需要 live index"说明）。
+- `src/extension.ts`：为 live server 提供 `loadFile()`（读文本 + 解析 + LineMap）。
+
+### 二期 D：测试
+
+- `test/agentEndpoint.test.mjs`：按项目 endpoint、进程存活、清理隔离。
+- `test/agentLocalServer.test.mjs`：`?project=` 路由、`projectDir` 校验、
+  `/get_asset_references`。
+- `test/agentForwardRefs.test.mjs`：直接引用、继承链、`CreateObjectDie` 内容引用、
+  `targetTypes` 过滤、`maxEdges` 截断、`depth` 上限。
+- `test/agentSkill.test.mjs`：Skill 文本包含 applicability 段落且不含工作区文档引用。
+- `test/agentMcpRouting.test.mjs`：live URL 固定 `project`、跨项目响应拒绝。
+
+---
+
+## 12. 二期实施结果
+
+全部完成，`npx tsc --noEmit` 通过，`test/*.test.mjs` 共 **264/264** 通过。
+
+### 新增 / 修改文件
+
+```text
+新增：
+  src/agent/forwardRefs.ts          有界、带 provenance 的正向引用遍历
+  test/agentForwardRefs.test.mjs
+  test/agentMcpRouting.test.mjs
+
+修改：
+  src/agent/endpoint.ts             按项目 endpoint + isProcessAlive()
+  src/agent/snapshot.ts             projectHash() / projectSlug() / snapshotBaseName()
+  src/agent/liveQuery.ts            liveStatus() 回落请求的 projectDir
+  src/agent/localServer.ts          异步 handler、?project= 路由、/projects、/get_asset_references
+  src/agent/mcpServer.ts            按项目 endpoint、projectDir 校验、负缓存、get_asset_references
+  src/agent/skill.ts                applicability 段落 + get_asset_references 用法
+  src/workspace.ts                  新增 indexForProject()
+  src/extension.ts                  按项目写/清 endpoint、loadFile、endpoint 刷新
+  test/agentEndpoint.test.mjs
+  test/agentLocalServer.test.mjs
+  test/agentSkill.test.mjs
+```
+
+### 关键行为
+
+**多窗口 / 多项目**
+
+- `~/.ra3modxml/endpoints/<slug>-<sha1-12>.json` 一项目一文件；MCP Server 先读自己项目的
+  文件，读不到才退回全局 `endpoint.json`，且仅在 `projectDir` 匹配时使用。
+- 每个 live 请求带 `?project=`；server 用 `ModWorkspace.indexForProject()` 路由，
+  不再依赖"当前活动编辑器"。
+- MCP 侧对响应里的 `index.projectDir` 做二次校验，不匹配就拒答并提示重新启用，
+  而不是给一个看起来合理但属于别的项目的答案。
+- 关闭窗口只删除本窗口写过的 endpoint 文件。
+- `processId` 不存活时 endpoint 视为失效。
+- live 连接失败后有 5 秒负缓存，避免每次工具调用都探一次。
+
+**Skill**
+
+- 新增 `When this skill applies` 段落：正向信号（`Data/Mod.xml`、
+  `mapmetadata_*.xml`、`*.babproj`、`<AssetDeclaration>`、
+  `uri:ea.com:eala:asset`）、明确否定规则（无关仓库、仅含拷贝 `.xsd` 的项目）、
+  以及 `CnC3Types.xsd` 属于 C&C3 而非 RA3 的反例。
+- 规定用 `get_status` 做便宜探针：状态为 `no_index` 或 `projectDir` 不匹配时
+  停止使用索引工具，改为直接读文件。
+- 仍然不引用任何工作区文档（有测试断言）。
+
+**`get_asset_references`（正向引用）**
+
+- 返回**边**：`from` / `to` / `via{kind,element,parent,attribute}` /
+  `source{file,line,character}` / `definedIn` / `value`。
+- `depth` 默认 1、上限 3；`inheritFrom` 不消耗 depth，祖先 XML 在同层遍历，
+  用 `definedIn` 标出真正写这条边的资产（解决"雅典娜炮自己没有 WeaponSetUpdate，
+  但 BaseCannon 有"的场景）。
+- `targetTypes` 按 XSD 可赋值性过滤，但 `inheritFrom` 边始终保留，因为
+  它解释了其余边写在哪里。
+- `maxEdges` 截断时返回 `truncated` + `omittedByTargetType`（只统计因上限被丢弃的边，
+  已被 `targetTypes` 过滤的不计入）。
+- 只走 live 路径；不可用时返回明确的错误说明，而不是空结果。
+
+### 已知限制
+
+- `get_asset_references` 不计算 `xai:joinAction`（`Replace`/`Remove`）合并后的
+  有效值，需要调用方自行确认。
+- 只有 live 路径支持正向引用；离线快照路径明确返回"需要 live index"。
+- `snapshotBaseName` 改为 `<slug>-<sha1-12>`，旧的 `project-<hash>.json.gz`
+  快照文件不会被自动清理（该功能尚未发布，无兼容负担）。
+- 本沙箱禁止 spawn 子进程，因此 `node --test` 与 `npm run build` 无法直接运行；
+  验证方式为：逐个 `node test/*.test.mjs`、直接调用 esbuild CLI 构建 dist、
+  用管道驱动 `dist/agent/mcpServer.js` 做端到端 smoke test。
+
+