mcpField
A
adr-index

adr-index

github.com/ruvnet开发80.0k737 次安装今天更新
代码仓库

关于 adr-index

adr-index 是将代码库中的 ADR 文档及其关系写入存储的技能，适用于初始化 ADR 跟踪或使图数据与文件保持同步。它识别 Ruflo monorepo 中的两种 ADR 格式，并支持试运行和语义搜索。

主要功能

  1. 01扫描 ADR 文件
  2. 02解析两种 ADR 格式
  3. 03写入 ADR 与关系边
  4. 04刷新记录而不重复边
  5. 05汇总状态与悬空引用
  6. 06支持试运行和 JSON 输出

适用场景

  1. 01从其他项目导入 ADR
  2. 02修复 AgentDB 图与文件不同步
  3. 03为现有代码库初始化 ADR 跟踪
  4. 04按主题语义搜索已导入 ADR

MCP 相关

该技能使用 MCP memory_search 在 adr-patterns 命名空间中进行语义搜索；导入脚本负责持久化 ADR 记录和关系。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ruvnet/ruflo --skill adr-index

安装后在 Claude Code 中输入/adr-index确认已加载。

详细介绍

ADR 索引

将 */docs/adr/ 或 */docs/adrs/ 下的每个 ADR 持久化到 adr-patterns 命名空间，并将每条关系（supersedes / amends / related / depends-on）持久化到 adr-edges。支持 Ruflo monorepo 中的两种 ADR 格式：

  • v3-style：标题为 # ADR-097: Title，并包含 **Status**: Proposed 行
  • plugin-style：YAML frontmatter（id: ADR-NNNN、status: Proposed）

实现位于 scripts/import.mjs（一次 Bash 调用），而非数十次逐条 ADR 的 MCP 工具调用——功能效果相同，但速度明显更快，支持双格式，并能避免将 issue 编号误判为 ADR。

使用时机

  • 从其他项目导入 ADR 后
  • AgentDB 图与磁盘上的 ADR 文件不同步时
  • 在现有代码库中初始化 ADR 跟踪

步骤

  1. 运行导入器：

    node plugins/ruflo-adr/scripts/import.mjs

    可选环境变量：

    • IMPORT_FORMAT=json — 输出 JSON，而非 Markdown
    • IMPORT_DRY_RUN=1 — 解析并汇总，跳过持久化
    • ADR_ROOT=/path — 扫描其他根目录（默认为：cwd）

  2. 检查摘要 — ADR 总数、已存储数量、按状态分类的明细、边数量、悬空引用、状态不匹配。

  3. 验证图完整性（可选，但建议）——使用同级 adr-verify 技能，该技能运行 scripts/verify.mjs，遇到循环时以状态码 1 退出。

  4. 通过 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-index 只会添加或 upsert。如果 ADR 文件被删除（或某个仍存在的文件中删除了关系行），它写入的记录会永久保留——adr-verify 也无法检测到，因为孤立记录没有悬空引用，也不会形成循环。请使用同级 adr-reindex 技能来协调已删除的记录（issue #2666）。

交叉引用

  • adr-create — 生成此技能处理的 ADR 文件
  • adr-review — 基于 adr-patterns 执行合规性检查
  • adr-verify（同级技能）— 运行 scripts/verify.mjs，用于图完整性门禁
  • adr-reindex（同级技能）— 对已删除的 ADR 文件执行删除后重建协调（此技能只能添加，不能删除）

评论

支持 Markdown