用途
ADR Index 用于构建或重建 ADR（架构决策记录）索引与依赖图。它把仓库中的 ADR 文件持久化到 adr-patterns 命名空间，并把 ADR 之间的关系（supersedes / amends / related / depends-on）写入 adr-edges 命名空间。
主要能力
- 扫描 */docs/adr/ 或 */docs/adrs/ 下的所有 ADR。
- 同时支持 Ruflo monorepo 中存在的两种 ADR 格式：
- v3 风格：# ADR-097: Title 标题 + Status: Proposed 行
- 插件风格：YAML frontmatter（id: ADR-NNNN, status: Proposed）
- 实现位于 scripts/import.mjs，只需一次 Bash 调用，而不是数十次逐 ADR 的 MCP 工具调用；行为等效但明显更快，且能识别双格式。
- 对 issue 编号具备防误判能力。
使用方式
运行导入器：
node plugins/ruflo-adr/scripts/import.mjs
可选环境变量：
- IMPORT_FORMAT=json — 输出 JSON 而非 markdown
- IMPORT_DRY_RUN=1 — 仅解析并汇总，跳过持久化
- ADR_ROOT=/path — 扫描其他根目录（默认：cwd）
随后检查汇总信息：ADR 总数、已存储数量、按状态分布、边数量、悬空引用、状态不匹配。
可选但推荐：通过同系列的 adr-verify 技能验证图完整性，它运行 scripts/verify.mjs，遇到环时以退出码 1 结束。
语义搜索：针对已填充的命名空间使用 mcp__plugin_ruflo-core_ruflo__memory_search：
memory_search --query "federation budget" --namespace adr-patterns
存储结构
adr-patterns 命名空间，键为 <ADR-id>::<basename>，值为文本：
<title> — <first paragraph of Context>
file: <relative path>
status: <Proposed|Accepted|Superseded|...>
date: <ISO date>
tags: <comma-separated>
adr-edges 命名空间，确定性键为 <relation>:<FROM>-><TO>，值为：
{ "from": "ADR-097", "to": "ADR-086", "relation": "related", "capturedAt": "<ISO>" }
ADR 记录与关系边均以显式 upsert 语义存储。重新运行 adr-index 会就地刷新已变更的元数据，不会为未变更的语义边创建重复副本。
防误判保护
ADR 正文中的 #1697 / commit abc123 / PR 1234 等引用会在正则提取前被剥离，避免被误读为 ADR-1697 等。详见 scripts/import.mjs 中的 extractAdrRefs()。
适用场景
- 从其他项目导入 ADR 之后
- AgentDB 图与磁盘上的 ADR 文件不同步时
- 在既有代码库上引导 ADR 跟踪
限制
adr-index 只会新增/更新（upsert）。如果某个 ADR 文件被删除（或某个关系行从仍存在的文件中被移除），它写入的行会永久保留——adr-verify 也无法发现，因为孤儿记录既没有悬空引用，也不构成环。要协调删除，请使用同系列的 adr-reindex 技能（issue #2666）。
交叉引用
- adr-create — 生成本技能所消费的 ADR 文件
- adr-review — 基于 adr-patterns 运行合规检查
- adr-verify（同系列技能）— 运行 scripts/verify.mjs 进行图完整性门禁
- adr-reindex（同系列技能）— 针对已删除 ADR 文件的 drop-and-rebuild 协调（本技能只能新增，不能删除）