mcpField
A
adr-reindex

adr-reindex

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

关于 adr-reindex

adr-reindex 用于清除记忆命名空间中的过期 ADR 记录，并根据磁盘上的 ADR 文件重建数据。它处理只添加或更新记录的索引留下的已删除源文件记录，并在重建后核对数量。

主要功能

  1. 01清除 ADR 记忆命名空间
  2. 02从磁盘重建记录
  3. 03支持 JSON 输出和试运行
  4. 04核对重建后的记录数
  5. 05可配置 ADR 根目录

适用场景

  1. 01删除 ADR 文件后
  2. 02移除 ADR 关系后
  3. 03定期协调 ADR 记录

安装

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

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

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

详细介绍

ADR 重建索引

adr-index 只会添加或更新行——没有删除行的方式。删除一个 ADR 文件（或从保留的文件中删除一条关系行）后，adr-index 曾为其写入的行会在今后每次运行 adr-index 后永久保留，而且不会有悬空引用或循环指向它。随后，adr-verify 会将生成的图认证为健康，因为没有入边或出边的孤立行不会触发它的任何检查。参见 issue #2666。

这与过时问题（ADR 已更改，但存储的记录未更新）是不同的故障模式——解决收敛问题是 adr-index 的工作。这里的问题是清理——事实来源（ADR 文件）已不存在，因此对应的派生缓存行也必须删除。唯一可靠的清理方式是删除两个命名空间，再根据当前磁盘上的实际内容重新构建。

适用场景

  • 删除 ADR 文件后（或从文件中移除一条关系行后）
  • 定期作为计划对账任务运行（adr-verify 无法捕获 adr-reindex 能捕获的问题——见下文）
  • 如果 adr-verify 显示的 ADR 数量高于 find docs/adr -name '*.md' | wc -l

步骤

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

可选环境变量：

  • REINDEX_FORMAT=json — 输出 JSON，而非 Markdown
  • REINDEX_DRY_RUN=1 — 报告将执行的操作，不清理或写入任何内容
  • ADR_ROOT=/path — 扫描根目录以及底层 memory purge/memory store 子进程运行时所在的根目录（必须与上次运行 adr-index 时使用的根目录一致，否则会对账错误仓库的命名空间）

执行内容

  1. 清理 — 通过 memory purge --namespace <ns> --force 硬删除 adr-patterns 和 adr-edges 中的所有行（这是 CLI 实际执行的 DELETE FROM memory_entries，而不是 memory delete 的软删除标记；软删除标记仍会阻止使用相同键重新存储，见下文“为何不使用 adr-index + memory delete”）。
  2. 重建 — 重新扫描当前磁盘上的所有 ADR（使用与 adr-index 相同的双格式解析器），并重新存储。
  3. 后置条件 — 重新列出 adr-patterns，并断言其数量等于刚才扫描的 ADR 文件数量。这比 adr-index 的“存储 N 条，0 个错误”统计更严格：如果并发的 memory.db 写入程序覆盖了清理操作（见注意事项），存储循环仍会将每次调用报告为成功——只有重新统计才能发现这一点。

如果后置条件未通过，则以非零状态码退出。

为何不使用 adr-index + memory delete

memory delete 是软删除（UPDATE ... SET status='deleted'）——该行仍占据 UNIQUE(namespace, key) 槽位，因此之后使用相同键进行非 upsert 的 memory store 仍会失败。memory cleanup 只会根据存留时间/TTL/质量清理条目，不会检查“源文件是否仍然存在”——它没有孤立条目的概念。这两种方式都无法让图恢复干净；只有真正按命名空间执行 DELETE FROM 才行，而 memory purge（以及此技能）正是这样做的。

注意事项

  • 不可逆。 此操作会清理整个命名空间，而不是差异内容——在这里始终安全，因为步骤 2 会立即根据当前磁盘上的真实内容重建；但不要在此流程之外直接对 adr-patterns/adr-edges 调用 memory purge。
  • #2621（尚未解决）： 清理操作受到锁保护，可防止同一 memory.db 上的第二个并发清理/删除操作，但无法防止所有写入程序——在 sql.js 后备路径上，处于读取-修改-写入周期中的守护进程或 MCP 服务仍可能随后刷回旧数据，从而恢复刚刚清理的内容。设置后置条件检查的目的正是发现这一问题；如果检查失败，请重新运行此技能。
  • 指向本次根目录中从未扫描过的 ADR 的跨仓库 related/depends-on 边（这是合法的兄弟仓库引用，并非孤立引用）会在重建时与 adr-edges 中的其他内容一并删除——只有在同一次运行中为兄弟仓库的 ADR 建立索引后，这些边才会恢复。这与 adr-verify 文档中提到的“悬空引用的常见原因：兄弟仓库”这一注意事项一致；并非此技能引入了新的数据偏差。

交叉引用

  • adr-index — 收敛（添加/更新）；此技能负责清理（移除已不存在的内容）
  • adr-verify — 回读完整性检查；重新索引后运行，以确认 adrCount 与磁盘上的数量一致
  • scripts/reindex.mjs — 实现
  • ADR-0002（docs/adrs/）— 此技能的决策记录

评论

支持 Markdown