ai agent

README.zh-CN.md

@@ -152,6 +152,35 @@
 * `RA3 Mod XML: Show cache report`（显示缓存报告）
 * `RA3 Mod XML: Find unreferenced assets…`（查找未引用的资产…）
 * `RA3 Mod XML: Find unreferenced assets of this type`（查找此类型的未引用资产）
+* `RA3 Mod XML: Enable AI Agent access…`（启用 AI Agent 访问…）
+* `RA3 Mod XML: Install Agent Skill…`（安装 Agent Skill…）
+* `RA3 Mod XML: Export AI Agent index snapshot`（导出 AI Agent 索引快照）
+
+## AI Agent 访问
+
+扩展可以通过本地只读 MCP（Model Context Protocol）Server，把语义索引提供给 AI Agent 使用。该功能可选，不会修改 `PATH`，也不会注册全局命令。
+
+运行：
+
+`RA3 Mod XML: Enable AI Agent access…`
+
+该命令会：
+
+1. 为当前项目导出稳定的索引快照；
+2. 在 `~/.ra3modxml/` 下创建稳定 launcher；
+3. 在 VS Code 运行期间启动本地只读查询服务；
+4. 让用户选择：
+   * 安装 `ra3-mod-xml` Agent Skill 到 `~/.agents/skills/`（也可选择 Claude Code 或项目级目录）；
+   * 写入 Claude Desktop / Cursor 的 MCP 配置；
+   * 复制通用 MCP 配置。
+
+MCP Server 在扩展运行时优先查询内存中的实时索引；扩展关闭后回退到最近一次导出的快照。暴露的工具包括资产定义查询、语义引用查询、**正向引用边**（`get_asset_references`：该资产用了哪些资产、通过哪个元素/属性、写在 XML 的哪一行）、文件是否有效 include、`$DEFINE` 查询以及 Include source 解析。
+
+`get_asset_references` 会沿 `inheritFrom` 祖先链遍历，并用 `definedIn` 标出条目实际写在哪个祖先的文件里，因此"这个单位自己没有 `WeaponSetUpdate`，但它继承的基础单位有"可以在一次调用里回答。它受 `depth`（默认 1，上限 3）、`targetTypes` 与 `maxEdges` 三重限制，并在截断时显式报告，而不是静默丢弃结果。
+
+Endpoint 按项目存放（`~/.ra3modxml/endpoints/<project>.json`），因此多个 VS Code 窗口可以同时启用 AI Agent 访问而不互相覆盖，客户端也不会被静默地用另一个项目的数据回答。
+
+完整设计与进度见 `docs/ai-agent-integration-plan.md`。
 
 ## 环境要求