Rhizome MCP

编码 Agent 在任务中途崩溃时，任务会自动释放。

rhizome-mcp 通过 MCP 为自主编码 Agent 提供可防崩溃的任务协调机制：认领是可续期、会过期的租约，in_progress 状态由系统推导——绝不存储；如果一次尝试中断，其检查点会交给下一个接手工作的会话。一个静态 Go 二进制文件，每个项目一个 SQLite 数据库。无需守护进程、账户或云服务。

它可同时与不同产品的 Agent 协作——Claude Code、Codex、GitHub Copilot、VS Code，以及任何其他兼容 MCP 的客户端——让它们共享统一、持久的项目工作视图。

根据真实服务输出录制，使用 demo/record.sh 完成——没有任何预先安排。

缘由 · 对比 · 快速开始 · 监控项目 · MCP 接口 · 文档

为什么

AI 编码 Agent 会并发工作、受上下文限制，也可能被中断。TODO.md 或单个聊天上下文都无法应对这些情况。rhizome-mcp 正是围绕这些故障模式构建的：

• 崩溃安全的认领。 问题通过可续期租约以原子方式认领。in_progress 从来不是存储的状态，而是根据活跃租约推导得出，因此消失的 Agent 不会永远锁住问题。租约过期后，问题会重新变为可认领状态。部分唯一索引在数据库层面保证每个问题最多只有一次活跃尝试。

• 按契约节省令牌。 精简的列表投影（100 个问题的页面保持在 64 KB 以内，并由集成测试强制验证）、在 SQL 层排除自由文本正文的图节点、仅返回片段的搜索、通过事件 ID 进行增量同步，以及有界的单次调用工作上下文包。

• 持久的项目记忆。 包含后续步骤的检查点、可被替代的决策记录、只追加的事件历史，以及跨问题、评论、决策和笔记的 FTS5 全文搜索。新会话可从最后一个检查点恢复，而不必重新推导状态。

• 规划和依赖关系图。 经过循环检查的 blocks 关系、史诗、突出显示可认领的入口点，以及原子批量规划（在一个全有或全无的事务中最多处理 50 个问题、100 个关系和 20 个决策）。

• 审查工作流。 审查请求会固定确切的问题版本和事件位置；从结构上杜绝了批准已更改的代码——过期请求只能被替代并重新固定。

  观看过期审批遭拒

  

• 资源预留。 认领可以原子地预留文件、目录、glob 模式或逻辑资源（端口、迁移时段、部署名额）；发生重叠时，认领会快速失败并指出持有者及其租约到期时间，而不是等两个 Agent 之后发生冲突。

  观看资源预留冲突如何使认领原子地失败

  

• 贯穿始终的并发纪律。 变更采用乐观版本控制，幂等键可安全重放，错误代码稳定且可供机器操作。

• 无需服务端即可供人观察。 rhizome-mcp board 会打印实时租约、阻塞项和审查队列，也可以写出独立的 HTML 快照；CLI 会以表格、JSON 或 Mermaid 的形式读取所有内容。

此仓库通过自身提供的服务跟踪自己的待办事项——工作由 rhizome-mcp 自身进行选择、认领、记录检查点和审查（AGENTS.md）。

适用场景： 多个 Agent 会话（或多个 Agent 产品）长期协作处理同一个代码仓库，且你需要交接、并行工作以及在崩溃或上下文受限后恢复。

不适用场景： 你需要带有身份验证、权限管理和 Web 界面的托管式多用户跟踪工具——本工具的设计目标是供单个开发者在本地使用。

对比

比较 Agent 任务跟踪器时，应关注故障情况下的保障，而非功能列表——在这一类别中，本地优先的 SQLite 存储和 MCP 支持是基本要求。

出现问题时	rhizome-mcp	beads	Kata	Guild
崩溃后任务会自动释放	是 — 租约会过期	否	否	否
存储层可防止重复认领	是	原子认领	原子认领	原子认领
不可能出现过期的审核批准	是 — 固定版本	否	否	否
响应大小受经过测试的契约约束	是 — ≤ 64 KiB / 100 个问题	否	否	否
中断的尝试可由另一个会话恢复	是 — 检查点	否	否	仅记录说明

包含来源、固定版本及坦诚的“适合选择 X 的情况”建议的完整对比：rhizome-mcp 对比。

快速开始

安装并运行

选择符合你工作流的方式：

通过 npm 零安装试用

无需单独安装二进制文件或 Go 工具链，即可立即试用 rhizome-mcp：

npx rhizome-mcp serve

适用于任何 MCP 客户端。平台支持情况请参阅 packages/npm/README.md。非常适合快速评估。

Claude Code 插件

/plugin marketplace add Odrin/rhizome-mcp
/plugin install rhizome-mcp@rhizome

注册 MCP 服务（通过 npx，无需安装二进制文件），并添加 rhizome-task-workflow 和 rhizome-execution-plan 技能。每个要跟踪的代码库仍需在其根目录中运行一次 npx rhizome-mcp init。

VS Code

从 Marketplace 或 Open VSX 安装 Rhizome MCP（odrin.rhizome-mcp）。该扩展捆绑了平台二进制文件，会自动注册 MCP 服务，并在命令面板中添加 Rhizome: Initialize Project。无需终端，也无需编辑 mcp.json。详情：docs/10-vscode-extension.md。

如果你更喜欢使用独立二进制文件和纯 mcp.json 配置项，请安装下方的二进制文件，然后使用此一键链接：添加到 VS Code。

原生二进制安装程序

下载并安装适用于你平台的发布版二进制文件。安装程序会验证校验和，默认安装到 ~/.local/bin：

curl -fsSL https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/Odrin/rhizome-mcp/main/scripts/install.ps1 | iex

官方 MCP Registry

对于使用该 Registry 的客户端，可通过官方 MCP Registry 使用 rhizome-mcp。它在 Model Context Protocol registry 中的名称为 io.github.Odrin/rhizome-mcp。

初始化并连接

在仓库中初始化跟踪：

rhizome-mcp init

然后在 MCP 客户端中注册该服务。常见客户端的自动化设置：

rhizome-mcp connect claude    # Claude Code
rhizome-mcp connect codex     # Codex
rhizome-mcp connect vscode    # VS Code (if using standalone binary instead of extension)
rhizome-mcp connect json      # Template for any other client

使用 --print 可进行试运行。connect 会发现项目的实际根目录（与 serve 一样，从当前目录向上查找），并通过 --project-root 固定该路径，因此无论 MCP 客户端之后从哪个子目录启动服务，写入的配置都能正常工作。四种目标（claude、codex、vscode、json）对此行为一致。适用于任何 MCP 客户端、与 connect 自身服务键一致的手动配置方式：

{
  "mcpServers": {
    "rhizome-mcp": {
      "command": "/absolute/path/to/rhizome-mcp",
      "args": ["serve", "--project-root", "/absolute/path/to/your/repository"]
    }
  }
}

或者通过 npx 使用，完全无需安装二进制文件：

{
  "mcpServers": {
    "rhizome-mcp": {
      "command": "npx",
      "args": ["-y", "rhizome-mcp", "serve", "--project-root", "/absolute/path/to/your/repository"]
    }
  }
}

connect 会检测自身是否通过 npx rhizome-mcp 包装器运行，并自动生成这种 npx 形式，而不是使用包装器解析出的二进制文件路径；后者位于 npx 缓存中，缓存被清除或版本升级后就会失效。默认情况下，配置中写入的是解析后的绝对路径，该路径因机器而异，不适合提交并在不同机器间共享；如果要生成依赖 PATH 的可移植配置，且确实打算共享该配置，请传入 connect TARGET --command，以生成不带路径的 rhizome-mcp 命令名。使用该配置的每台机器都必须将 rhizome-mcp 加入 PATH。

默认传输方式为 Stdio；协议输出写入 stdout，日志写入 stderr。

完成后，连接的 Agent 会使用仓库绝对路径调用 open_project，保留其 project_ref，并在之后调用项目范围的工具时传入该引用。完整工作流请参阅Agent 工作流指南。返回的元数据会链接到 rhizome://guides/agent-workflow、rhizome://guides/issue-lifecycle 和 rhizome://guides/multi-agent-handoff 资源；仓库中的 Agent 可以从 .github/skills/ 加载 rhizome-task-workflow 技能。

安装 Agent 工作流技能

对于支持开放的 Agent Skills 格式的 Agent，可使用通过 npm 分发的 skills CLI 安装 rhizome-task-workflow：

npx skills add Odrin/rhizome-mcp --skill rhizome-task-workflow

在项目中运行该命令可进行项目范围的安装；添加 --global 可让该技能在各个项目中使用。该技能会教会兼容的 Agent 如何选择、认领、创建检查点、移交和完成 Rhizome 工作。它与 MCP 服务互为补充；不会安装 rhizome-mcp 二进制文件，也不会配置 MCP 连接。

监控项目

rhizome-mcp board                        # status counts, active leases, blockers, review queue
rhizome-mcp board --serve                # interactive local board UI at a loopback URL
rhizome-mcp board --output board.html    # self-contained HTML snapshot with the planning graph
rhizome-mcp issue list --status ready
rhizome-mcp graph ISSUE-42 --format mermaid
rhizome-mcp doctor --full

状态看板会报告有效租约数量、阻塞问题及其原因、待处理的审查请求，以及项目范围的规划图。规划图会从节点预算中排除已结束的工作（已完成、已取消），因此入口节点数量始终反映可认领的工作。当图因 100 个节点的预算而被截断时，看板会标明其已截断，并在表格和 JSON 格式中报告保留的节点数量。

可选：本地 HTTP 传输

rhizome-mcp serve --http-address 127.0.0.1:0

绑定的端点会记录到 stderr；Streamable HTTP 端点为 http://127.0.0.1:<port>/mcp。该传输仅限环回地址，不需要身份验证，并严格校验 Host/Origin，且将外层请求正文大小限制为 1 MiB。使用现代 MCP 2026-07-28 的客户端会调用 server/discover，然后发送带有协议元数据的直接请求；使用旧版 2025-11-25 的客户端仍可使用 initialize 和 notifications/initialized，无需依赖持久传输会话。如果需要持久的审计归属信息，请通过 create_agent_session 创建明确的 agent_session_handle，将其传递给相关的变更工具，并稍后通过 end_agent_session 结束该会话；传输关闭不会结束该会话。

工作原理

init 会在仓库中只写入一个文件：

{
  "version": 1,
  "project_id": "01J..."
}

该文件存储为 .agent-tracker.json。SQLite 数据库位于仓库之外的平台应用数据目录中，并通过 project_id 确定：

<application-data>/rhizome-mcp/projects/<project-id>/tasks.db

使用 --data-root PATH 为任何命令指定明确的数据根目录。没有其他操作会访问你的仓库，数据库也绝不会提交到 Git。

设计原则： issue 绝不能永久卡在 in_progress 状态。有效状态由存储的状态以及是否存在有效的租约尝试共同决定；如果 Agent 消失且租约过期，该尝试就会变为 expired，并且当 issue 的存储状态允许时，issue 会再次可用。

核心约束（有意如此设计）： 使用 Go、SQLite（modernc.org/sqlite，纯 Go，无需 CGO）、以 stdio 作为主要传输方式、每个项目使用一个数据库、没有托管或经过身份验证的 Web UI（提供仅限 loopback 的本地状态看板）、无需身份验证、CLI 精简。延期功能列于 docs/06。

CLI 参考

命令	用途
init	创建 .agent-tracker.json 和项目数据库
serve [--http-address ADDR] [--profile full|agent|read-only|migration] [--toolsets GROUP[,GROUP...]] [--project-root PATH]	运行 MCP 服务（stdio；使用 --http-address 启用本地 HTTP；使用 --profile 将公布的工具目录限定为指定配置，或使用 --toolsets 从能力组组合配置；使用 --project-root 服务于工作目录之外的项目）
connect TARGET [--print] [--command]	将服务注册到 MCP 客户端（claude、codex、vscode、json）
board [--output PATH] [--serve [--http-address ADDR]]	状态看板：计数、租约、阻塞项、审核队列；可选 HTML 快照；--serve 会运行临时 HTTP 服务
issue list / issue show ISSUE-ID	查看带筛选条件的 issue
search QUERY	在 issue、评论、决策和备注中进行全文搜索
graph ISSUE-ID	以表格、JSON 或 Mermaid 格式显示依赖关系图
project info / project export / project import	项目元数据；逻辑 JSON 导出；逻辑 JSON 导入（使用 `--input PATH
backup --output PATH	进行 WAL 安全的在线备份
doctor [--full]	检查完整性、架构和不变量
maintenance release-attempt / rebuild-search-index / normalize-issue-timestamps --backup PATH	管理性恢复；时间戳标准化需要新的、经过验证的备份

不带参数运行 rhizome-mcp 可查看完整用法；运行 rhizome-mcp version 可查看构建信息。

MCP 工具面

该服务提供 44 个工具，覆盖完整生命周期：项目发现、包含标签和关联关系的问题 CRUD、归档/取消归档可见性转换、规划和依赖关系图、批量计划验证/应用、评论和决策、工作尝试的认领/续期/检查点/完成（支持可选的原子资源预留）、工作上下文组装、审查请求、全文搜索、增量变更、逻辑项目导出/导入，以及包含门禁证据和诊断的工作流策略管理。完整契约包括 MCP 工具注解矩阵以及 full/agent/read-only/migration 暴露配置矩阵，详见 docs/03-mcp-tools.md。

默认情况下，serve 会公布完整的 full 工具目录。传入 --profile agent|read-only|migration（或设置 RHIZOME_TOOL_PROFILE）可缩小范围，例如，对于不应看到任何修改型工具的客户端，可使用 serve --profile read-only。如果没有合适的命名配置，可传入 --toolsets（或设置 RHIZOME_TOOLSETS），并提供以逗号分隔的能力组列表，以公布指定组以及始终启用的 core 工具对（open_project、get_project）；例如 serve --toolsets issues,planning。这两个标志不能同时使用。配置和工具集用于控制暴露范围和提示词大小，并非授权边界：无论客户端在 tools/list 中能看到什么，每个工具都会执行自身的服务端验证。完整的环境变量集合和优先级（包括已弃用的无前缀备用名称）请参阅 docs/04-storage-runtime.md §17.1。

文档

docs/ 下的模块化文件是规范的权威版本；SPEC.md 是索引。Agent 应只加载与当前任务相关的章节（AGENT_BRIEF.md 说明了具体方法）。

1. 产品目标和范围
2. 领域模型
3. MCP 工具
4. 存储和运行时
5. 实施要求
6. 延期功能和非目标
7. 逻辑交换格式
8. 本地 HTTP 传输契约
9. 审查工作流契约
10. VS Code 扩展
11. 项目路由契约
12. 资源预留
13. 状态看板

面向用户的指南（快速入门、工作流、CLI）位于 site/，并通过 GitHub Pages 发布。发布历史见 CHANGELOG。

开发

构建和测试（不使用 CGO，也不依赖外部服务）：

CGO_ENABLED=0 go build -o rhizome-mcp .
go test ./...
go test -tags=integration ./...

集成标签会运行真实进程的 MCP 冒烟测试和工作流测试：这些测试会构建临时服务二进制文件，为每个测试初始化全新的仓库和 SQLite 数据根目录，并通过 stdio 或 HTTP 与 serve 通信。除了单进程冒烟测试外，测试套件还会在共享的 SQLite 数据根目录上测试跨进程场景——并发认领和更新版本竞争、非正常进程终止与重启，以及服务器写入期间进行备份——以发现单进程测试在结构上无法发现的缺陷。大多数测试位于专门的 integration 包中；需要访问未导出的 package-main 内部内容的测试则保留在仓库根目录。

对于每次推送和面向 main 的拉取请求，CI 都会在 Ubuntu、macOS 和 Windows 上运行 go vet、所有非竞态检测的单元测试和集成测试，以及 npm 启动器测试。Linux 还会运行现有的模糊测试预算，另有一个覆盖率作业负责执行单元测试和集成测试的覆盖率阈值。并行运行的 Linux Race smoke 作业会使用竞态检测器，显式选择运行认领、预留、事务准入、项目路由器和 HTTP 生命周期测试；测试选择维护在 .github/workflows/ci.yml 中。

完整竞态检测 每天 02:17 UTC 针对最新的 main 运行完整的单元测试和集成测试竞态检测套件。GitHub 可能会延迟计划运行。也可以在 Actions 选项卡中使用 Run workflow 手动启动，并选择一个分支，包括合并前的功能分支。工作流会记录受测提交，保留 JSON 测试日志 14 天，并使用独立于常规 CI 和竞态冒烟测试的缓存。夜间测试和冒烟测试使用 -count=1，以确保成功的缓存测试结果不会跳过实际执行。

完整竞态检测不是 PR 门禁：PR 通过只能确认选定的竞态检测已通过，而不代表完整竞态检测套件已通过。该选择范围之外的竞态回归可能在合并后、下一次计划运行时才被发现；请监控夜间运行失败，并及时修复或回滚。要在本地进行完整竞态检测验证（需要 CGO 和 C 编译器）：

go test -race -count=1 ./...
go test -race -count=1 -tags=integration -run '^TestIntegration' ./...

只要集成测试框架启用了竞态检测，它就会使用 -race 构建真实的服务子进程。

发布流程（.github/workflows/release.yml）会为 linux/amd64、linux/arm64、darwin/amd64、darwin/arm64 和 windows/amd64 发布不依赖 CGO 的二进制文件及 SHA-256 校验和；发布的二进制文件会嵌入版本、提交和构建时间戳（本地构建会报告 git VCS 信息或 dev，而 VERSION 环境变量会覆盖二者）。

发布验证步骤记录在 CONTRIBUTING.md 中。

本仓库在 rhizome-mcp 中跟踪自身的待办事项：工作通过 MCP 服务进行选择、认领和完成，持久化的选择则记录为决策。Markdown 仅用于编写规范，不记录任务状态。请参阅 AGENTS.md 和 CONTRIBUTING.md。

许可证

Apache-2.0。安全策略：SECURITY.md。