# 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。