Reasonbook

Reasonbook — 跨会话留存的决策记录

Reasonbook（前身为 CMOS）是 Agent 为项目维护的记录：做出了哪些决定、为何做出这些决定、学到了什么， 以及还有哪些工作未完成。下一个会话可以根据这份记录继续工作，即使使用的是另一个工具。 由你做决定；Agent 负责记录。无需注册仪表板账号。

查看实际演示，观看 Claude Code 和 Codex 中 75 秒的录制运行回放，并阅读它会发送和存储哪些内容。

在 Claude Code 中安装

安装一次插件，即可用于你的所有项目：

claude plugin marketplace add kneelinghorse/reasonbook
claude plugin install reasonbook@reasonbook

要从 cmos@cmos 升级？刷新市场列表前先卸载它，运行 claude plugin uninstall cmos@cmos --scope user（或原先使用的 project 或 local 作用域）， 然后安装 reasonbook@reasonbook。若要本地安装，请在对应项目中运行命令。如果市场列表已刷新，而卸载时提示“not found”，请按经过测试的恢复步骤操作。 迁移现有记录前，请先升级所有客户端。

要测试候选版本，请将 kneelinghorse/reasonbook 替换为此检出版本的绝对路径。安装后，请启动新的 Claude Code 会话。该插件提供 MCP 服务、钩子和命令；首次冷启动会话可能会提示 Reasonbook 正在安装，并在下一个会话中加载记录。使用 /reasonbook:init 创建新记录，使用 /reasonbook:start 读取记录，使用 /reasonbook:close-out 完成工作，使用 /reasonbook:plan 制定计划， 使用 /reasonbook:build 执行。插件安装说明。 其他工具请参阅运行环境适配器和覆盖范围指南。

三步获取项目摘要

需要 Node.js 20 或更高版本。

1. 安装固定版本的 CLI：

   npm install -g @aquex/[email protected]
   

   确保全局 npm bin 目录已加入 PATH。如果已全局安装旧版软件包，请先运行 npm uninstall -g @aquex/cmos-mcp。第 4 版仅提供 reasonbook 命令；请更新使用旧命令的脚本和 MCP 配置。

2. 在要跟踪的项目文件夹中，启动一个 Ledger：

   cd /absolute/path/to/your/project
   reasonbook init --level ledger
   

3. 查看第一份摘要：

   reasonbook review --format=context
   

摘要会列出项目名称，并展示项目的决策、经验和待办工作。新建的 Ledger 内容为空。Planner 会添加后续步骤；Builder 会添加 sprint 和任务。

Codex 插件

开发者插件 reasonbook 提供服务器、七项技能和五个生命周期钩子。 面向对话的 reasonbook-chat 提供相同的服务器和六项不同的聊天技能， 不含钩子。插件加载、安装和项目调用已在捆绑的 Codex CLI 和 app-server 中验证。ChatGPT Work 尚未验证；这不是面向 ChatGPT 网页版或手机端的托管插件。

安装开发者插件：

codex plugin marketplace add kneelinghorse/reasonbook
codex plugin add reasonbook@reasonbook

如果插件以旧名称安装，请先将其移除，因为两个插件都以相同的服务器响应：codex plugin remove cmos@cmos，聊天插件则使用 codex plugin remove cmos-chat@cmos。

对于聊天工作流，请改为安装 reasonbook-chat@reasonbook：

codex plugin add reasonbook-chat@reasonbook

进行本地开发时，请将市场仓库替换为此检出版本的绝对路径。两个插件可以同时启用：Codex 会加载一个名为 rbook 的服务器，并且两组技能都会显示。构建时选择开发者插件；进行设置、了解进展、回忆信息、提出决策、记录笔记和讨论后续步骤时，选择聊天插件。

需要 Node.js 20 或更高版本。插件会将对应确切版本的 Reasonbook 安装到 ~/.config/rbook/plugins，并为现有安装提供旧版配置回退。首次安装时，Reasonbook 会显示安装中消息并连接；安装完成后，请启动新会话以加载项目工具。开发者插件的钩子共用该运行时。 开发者插件会请求转发受支持的设置，包括 RBOOK_CONFIG_DIR； 可移植聊天插件使用从宿主继承的环境。请使用绝对路径， 因为空的或相对的共享根目录会被拒绝。环境转发取决于 客户端的插件加载器。如果加载器不转发某项设置， 请使用默认根目录或配置手动服务器。请参阅运行环境指南。

在 Codex CLI 中，运行 /hooks 并审核一次开发者插件的五条命令。如果桌面应用没有提供此审核， 请使用与其 Codex 主目录相同的捆绑 Codex CLI。如果桌面应用尚未加载插件，请在安装后重启应用。钩子定义发生更改时，需要再次审核。聊天插件无需审核钩子。

在替换 CMOS 3.3.0 适配器之前，只从项目 .codex/hooks.json 和任何用户级 ~/.codex/hooks.json 中移除 CMOS 条目；保留无关钩子。也请移除其他已导入的 CMOS 钩子注册。只保留一个 MCP 服务响应：移除重复的手动条目，或者有意保留该条目，并在 ~/.config/cmos-mcp/config.json 中设置 "pluginServer": "off"（使用自定义配置根目录时，则在该根目录下设置）。

Reasonbook 会使用每次受支持的 Codex 调用提供的工作文件夹，因此项目中的对话可以调用 rbook_review()，无需指定路径。在该文件夹之外，请从 rbook_project(action="list") 中选择一个已注册地址，并将其作为 projectRoot 传入，例如 rbook_review(projectRoot="rbook://you/project")。未知或有歧义的地址会被拒绝； 仅限本地的项目需要提供其文件夹。工具提示会保守地包含遥测删除操作， 因此 Codex Auto 模式仍可能要求批准任何 Reasonbook 工具。

提出一项决策，然后批准它

需要你批准某项选择时，Agent 会在回复末尾给出一行具体提议：

将记录：采用每周回顾，因为这样既能让阅读清单保持实用，又不需要每天维护。

启用开发者钩子并将其关联到该对话后，Stop 钩子会将这项提议保留为草稿。你可以在下一条回复中批准、拒绝、提问或修改措辞。Agent 会使用返回的 P<n> ID 记录已批准的草稿；草稿还不是决策。可在项目文件夹中查看草稿：

reasonbook drafts list

reasonbook-chat 会在对话中请求批准并直接记录，同时在上下文中保留你观察到的原话。Reasonbook 无法独立验证这类批准，因此不会声称仅通过聊天记录的批准已经过钩子验证。若你已明确批准了完全相同的措辞，就算已批准，Agent 无需再次询问。

方法

• 一个项目、一份决策、经验、约束和后续步骤记录。
• 从这份记录开始；受支持的钩子会自动将其载入会话。
• 有意记录决策及其理由。决策变更时，将旧决策标记为已取代。
• 明确标示到期和取代情况；冲刺结束时，记录默认仍保持有效。
• 将记录与项目放在一起，这样即使更换工具也能保留记录。

方法完整介绍了五条原则、Reasonbook 在各个层级的功能，以及如何向上调整层级；入门模板包含各层级开始时使用的文件。

哪些数据会离开你的机器

记录保存在项目的 SQLite 文件中。使用已存储的用户专属密钥或旧版环境凭据时，显式关闭会话和冲刺会尝试在后台上传整个文件，包括待处理和已拒绝的提议。对于已注册的项目，MCP 工具写入操作还会在静默 5 分钟或持续写入 30 分钟后安排上传；若没有上传租约或失败退避机制阻止上传，下一次轮询会在 60 秒内启动上传。传输时间另计。请参阅可选功能：托管式控制面板中的时序和失败详情。RBOOK_CHECKPOINT_SYNC=off 会停止自动上传以及手动执行 rbook_db(action="backfill") 的上传。其他请求的网络操作和共享记录交换仍可用。退出登录后，项目密钥仍然有效，因此只要此开关未关闭，手动回填仍可使用项目密钥上传。进程退出时隐式执行的关闭操作不会上传。通过 reasonbook.ai 共享的项目会持续上传整个文件，直到共享记录交由控制面板的仲裁者副本管理；之后只发送共享记录的变更，直至将其移回。完整的网络和数据披露。

技术参考

它是什么

Reasonbook 是协议 + 客户端。它在你的机器上本地运行，在 rbook/db/rbook.sqlite 下管理 SQLite 数据库，并通过 MCP 提供 15 个类型化工具。Claude Code 和 Codex 已验证可用（请参阅适配器指南）；其他 MCP 客户端（例如 Claude Desktop、Cursor、Zed、VS Code 和 Windsurf）尚未测试。

开箱即可使用：

• 带有可审计状态转换的冲刺和任务状态机
• 用于记录决策、经验、约束和后续步骤的会话捕获功能
• 可跨冲刺汇总的战略上下文，并支持 FTS5 检索
• 跨决策、经验、任务和会话的全文搜索
• 按需创建数据库快照；冲刺结束时尝试备份；恢复或删除含所选行的快照前必须备份
• 按项目存储凭据，并支持设备码身份验证（RFC 8628）

reasonbook.ai 上的控制面板是可选的。你可以一直独立运行 Reasonbook；注册账号后即可启用控制面板上传（SQLite → Postgres 镜像）、项目注册表（rbook://you/* 地址）和跨项目消息传递。即使不注册，其他所有工具仍可在本地使用。

安装

推荐全局安装此版本。这样服务器会从磁盘启动，启动时无需查询注册表：

npm install -g @aquex/[email protected]

如果已全局安装旧版软件包，请先运行 npm uninstall -g @aquex/cmos-mcp。4 版仅提供 reasonbook 命令；请更新使用旧命令的脚本和 MCP 配置。

也可以使用 npx 按需运行。请固定版本并优先使用本地缓存：未固定版本的 npx -y 可能会在每次启动时重新查询软件包。

npx --prefer-offline -y @aquex/[email protected]

语义（向量）搜索为可选功能。不开启时，检索仅基于关键词，安装包约为 45 MB，而非约 306 MB。若要在检索中加入向量项，请在 Reasonbook 旁安装 @xenova/transformers。rbook_db(action="health") 会报告该功能是否已启用。

需要 Node.js 20 或更高版本。

配置 MCP 客户端

Claude Code 和 Codex 已通过验证；其他配置块遵循各客户端自己的 MCP 配置，尚未在 Reasonbook 中测试。以下每个示例都通过 npx 运行固定版本，并优先使用本地缓存；要升级，请更改版本。使用全局安装时，请将 "command": "reasonbook" 作为命令，并删除 npx 参数（示例中出现的 --project-root 请保留）。

Claude Code

claude mcp add-json rbook '{"command":"npx","args":["--prefer-offline","-y","@aquex/[email protected]"]}'

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS），或 Windows/Linux 上的对应文件：

{
  "mcpServers": {
    "rbook": {
      "command": "npx",
      "args": [
        "--prefer-offline",
        "-y",
        "@aquex/[email protected]",
        "--project-root",
        "/absolute/path/to/your/project"
      ]
    }
  }
}

预计 Claude Desktop 启动服务器时不会提供项目上下文（在 macOS 上，会从 / 启动且不带工作区根目录；此行为尚未在 Reasonbook 中测试），因此请在配置中指定项目名称。--project-root 仅适用于此服务器条目，并且只对没有项目上下文的调用生效：没有 projectRoot、没有工作区根目录，且工作目录为 /、你的主目录或服务器的安装目录。若客户端从其他任何文件夹启动服务器，则应改为传递 projectRoot。

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "rbook": {
      "command": "npx",
      "args": ["--prefer-offline", "-y", "@aquex/[email protected]"]
    }
  }
}

Zed

{
  "context_servers": {
    "rbook": {
      "command": "npx",
      "args": ["--prefer-offline", "-y", "@aquex/[email protected]"]
    }
  }
}

VS Code（Claude 扩展）

在集成终端中使用上面的 Claude Code 命令，或通过 Claude 面板中的 /mcp 添加服务器。扩展和 CLI 共用 MCP 配置；更改配置后请开启新对话。扩展不会将 claude 添加到终端 PATH，因此使用终端方式需要独立的 Claude CLI。 VS Code 中的 Claude Code

Windsurf

{
  "mcpServers": {
    "rbook": {
      "command": "npx",
      "args": ["--prefer-offline", "-y", "@aquex/[email protected]"]
    }
  }
}

首次调用

项目工具适用于包含 Reasonbook 数据库的文件夹，因此新项目应先运行 init：

rbook_project(action="init", projectRoot="/absolute/path/to/your/project")

init 会创建 rbook/db/rbook.sqlite、种子文件、一个 AGENTS.md，以及一个会在项目根目录导入该文件的 CLAUDE.md（若任一文件已存在，则保留原文件）。在不含该数据库的文件夹中，读写项目的工具会拒绝执行并提示运行 init；注册表和登录操作不需要项目。

接着运行一次 rbook_agent_onboard：对于新项目，它会引导完成首次会话设置。之后每次开启新会话时，都先查看会话摘要：

Run rbook_review to see the project state.

rbook_review 会返回共享会话摘要：项目身份、当前冲刺、未完成工作和近期决策。其本地文本核心上限为 4,000 个字符；追加的项目组合上下文和外围 MCP 响应不计入此上限。

完整的操作指南——安装 → 配置 → init → 首次冲刺／任务／会话循环——见 docs/getting-started.md。

工具接口

Reasonbook 提供 15 个整合工具。其中 12 个使用 action 参数选择操作；rbook_agent_onboard、rbook_status 和 rbook_review 不需要 action。TOOL_REFERENCE.md 为每个操作列出一张参数表，说明具体调用适用哪些参数。

工具	用途
rbook_review	会话摘要：身份、冲刺、工作、决策、其他项目的动态
rbook_agent_onboard	冷启动载荷：身份、当前冲刺、任务、决策、建议
rbook_status	诊断快照：rbook_address、dashboard_url、auth_tier、同步时间戳
rbook_mission	任务 — 创建、更新、查询和关联依赖项
rbook_mission_transition	任务状态机 — 开始、完成、阻塞、解除阻塞、放弃、延期
rbook_sprint	冲刺 — CRUD、收尾、回顾和跨冲刺分析
rbook_session	工作会话（可选）— 开始、记录见解、完成、列出、搜索
rbook_context	主上下文/项目上下文 — 查看、更新、精简、生成快照和搜索
rbook_decisions	战略决策 — 记录、显示、列出、搜索、更新、审查时效性
rbook_learnings	跨领域经验 — 列出、搜索、显示、更新和重新确认
rbook_db	数据库操作 — 健康检查、快照/恢复、回填和清理上下文快照
rbook_project	项目 — 初始化、注册、列出、验证；共享、邀请、加入、成员管理、同步
rbook_auth	仪表板凭证生命周期 — 设备码登录、轮换、撤销
rbook_message	跨项目消息（需要托管式仪表板）
rbook_feedback	Agent 反馈渠道 — 列出、分流、解决、归档

请参阅 TOOL_REFERENCE.md，了解每项操作的精确参数参考 — 该文档在每次构建时根据工具定义生成，因此始终与发布的接口保持一致。

分享项目记录

所有者可以与编辑者共享项目。每个人都保留完整的本地副本，在本地工作，并通过 reasonbook.ai 交换更改（reasonbook.ai 会保存项目的仲裁副本并在仪表板上显示），也可以通过 SSH 直接与所有者的副本交换，或手动传递数据包。冲突的字段值会一直显示，直到有人解决冲突。

共享已在实测配置中得到验证：由一人操作两个账户，分别在两台机器上使用，可通过 reasonbook.ai 共享，也可通过 SSH 以所有者／成员的星形结构共享。与第二个人协作的体验及隐私体验仍未经验证。编辑者的记录会成为所有者 Agent 的本地项目内容，不会受到外部来源隔离；请只邀请你信任其记录内容的人。

通过 reasonbook.ai 共享时，每个人都在自己的机器上登录。所有者的 Agent 共享项目，所有者在仪表板上与编辑者共享，编辑者则从项目页面向自己的 Agent 提供加入语句。所有者的副本可以通过 rbook_project(action="move", to="owner") 或 reasonbook move --to owner 将项目移回，然后通过 SSH 让成员的副本同步到最新状态；成员再通过 reasonbook sync --confirm-owner 确认转移。此流程已在一名成员参与的情况下进行实测，转移由 rbook_project 发起。一台机器上，一个共享项目只能有一个活动副本。

请从共享步骤和信任边界开始。通过 SSH 共享无需仪表板账户。在运行钩子的情况下，系统会在会话开始和结束时自动交换；对于服务器已通过已保存的路由打开的共享项目，还会每五分钟自动交换一次。RBOOK_SHARED_SYNC=off 可停止这些自动交换；显式同步和数据包命令仍可使用。

可选：托管式仪表板

仪表板是独立服务。在 reasonbook.ai 注册即可解锁：

• 仪表板镜像 — 上传整个 SQLite 文件的快照，供仪表板显示。
• 项目注册表 — 可在不同机器间访问的 rbook://you/project-name URI。
• 消息 — 在你自己的项目之间使用 rbook_message(action="send") 发送消息。
• 共享 — 与编辑者共享项目记录，编辑者可从项目页面加入；仪表板会保留记录的权威副本，并显示记录、成员，以及每位成员创建和移动内容的动态。请参阅共享项目记录。

要连接：

export RBOOK_DASHBOARD_URL=https://reasonbook.ai

然后从你的 Agent 运行 rbook_auth(action="login_init")。它会返回一次性 userCode 和 verificationUri——在浏览器中打开该 URL 并粘贴代码，然后运行 rbook_auth(action="login_complete", deviceCode=...) 完成登录。凭据会以原子方式保存到 ~/.config/rbook/credentials.json（模式为 0600）。

RBOOK_DASHBOARD_URL 默认值为 https://reasonbook.ai。如果没有仪表板凭据，仪表板操作会返回结构化的 DASHBOARD_NOT_CONFIGURED 错误，并指出 rbook_auth(action="login_init")。本地工具和直接共享记录交换不需要仪表板。

如果存有用户级仪表板密钥或旧版环境凭据，显式调用 rbook_session(action="complete") 和 rbook_sprint(action="complete") 会尝试在后台上传，并且可能会先注册项目。对于已注册的项目，实际写入其存储的 MCP 工具调用也会安排上传。静默 5 分钟后，或持续写入 30 分钟后，上传即到期；若没有上传租约或失败退避机制阻止，则会在接下来的 60 秒内开始上传。运行中的服务必须已打开该项目。短暂进程尚未完成的上传会留待下一个服务处理。每次上传都会发送整个 SQLite 文件的一致快照，包括待处理、已拒绝和已过期的提案。传输时间另计，并发服务会为每个项目共用一个上传租约。

上传结果和失败信息会显示在 rbook_status 和 rbook_review 中。HTTP 401、402 或 403 会暂停自动重试，直到显式关闭操作成功。上传失败不会导致本地写入或关闭操作失败。进程退出时隐式执行的关闭操作不会上传。在服务环境中设置 RBOOK_CHECKPOINT_SYNC=off，即可禁用自动上传和手动补传；这不会禁用显式同步、消息、登录或共享记录交换。退出登录会撤销用户级密钥，但项目密钥仍可用于已请求的仪表板调用。请参阅 SECURITY.md。

项目解析

Reasonbook 绝不会对你未指定的项目执行操作。每次工具调用都会按以下顺序选择一个项目；如果无法使用该项目，则拒绝调用，而不会回退到其他选项：

1. 调用中的 projectRoot 参数：项目文件夹或精确注册的 rbook://owner/project 地址。地址发现会读取已存储的身份信息，但不会修复这些信息；如果没有匹配项、存在重复匹配项，或注册的身份信息无法读取，则拒绝调用。
2. 对于受支持的 Codex 请求，使用其对话工作文件夹。如果提供的文件夹无效，则拒绝调用，而不会回退到服务端的文件夹。
3. MCP 客户端公布的工作区根目录：选择其中第一个位于 Reasonbook 项目内的根目录。
4. 工作目录，或其上方最近的 Reasonbook 项目文件夹——即包含 rbook/db/ 的文件夹；名为 rbook 的普通文件夹不算（搜索不会超出你的主目录）。
5. 仅当服务端完全没有项目上下文时——没有 projectRoot、没有根目录，且工作目录为 /、你的主目录或服务端安装目录（例如，客户端在没有项目文件夹的情况下启动服务端）：才使用该服务端配置中的 --project-root <dir> 参数，然后再使用通过 rbook_project(action="register", projectRoot="...", setAsDefault=true) 设置的注册表默认项目。
6. 否则拒绝调用。在非 Reasonbook 项目文件夹中，写入操作会提示使用 rbook_project(action="init")，读取操作则会返回 "No Reasonbook project in ''"。

rbook_project(action="list") 会列出已存储的 ID、地址和文件夹。init、register 和 unregister 需要文件夹；地址不会转换为文件系统路径。

每个成功的响应都会指出所用项目（其数据中包含 projectRoot 和 resolvedBy），并且当项目来自工作区根目录、--project-root 或注册表默认项目时，也会在文本中说明。3.2.0 之前设置的注册表默认项目，在重新运行 setAsDefault 之前不会生效；如果存在此类项目，服务端、rbook_message(action="whoami") 和 rbook_review 都会说明这一点。

将工作从中央规划文件夹移出

如果你在一个 Reasonbook 项目中收集了多个工作事项，当其中某项工作需要独立的项目文件夹时，请使用 spin-out。它会复制选定的任务、它们关联的决策、经验和后续步骤，以及你指定的任何其他记录 ID。源项目会保留为可读历史，并附上指向新项目的链接。

请先创建目标文件夹。源项目必须已注册，且两个存储必须具有不同的项目标识。必须同时指定两个根目录；此命令不会使用当前项目或注册表默认值。省略 --apply 可预览所选内容和映射：

reasonbook spin-out --from /work/projects --to /work/new-product --sprint sprint-12

# Or select missions, with additional decisions, learnings and next steps by ID:
reasonbook spin-out --from /work/projects --to /work/new-product \
  --missions product-plan,product-prototype \
  --decisions 41,42 --learnings 17 --next-steps 23,24

# Apply the same reviewed selection:
reasonbook spin-out --from /work/projects --to /work/new-product \
  --missions product-plan,product-prototype \
  --decisions 41,42 --learnings 17 --next-steps 23,24 --apply

选择 --sprint 或 --missions。如果目标目录中没有 Reasonbook，预览会报告需要初始化；--apply 会进行初始化，并在复制前备份数据库。复制的工作会保留其状态，但在目标项目中不会分配冲刺。准备就绪后，将其分配到目标冲刺。源项目中状态为 Queued、Blocked 和 Deferred 的任务会变为 Dropped；Completed 和已为 Dropped 的任务会保留原状态。源项目中的决策和经验会归档，后续步骤会标记为 dropped。默认列表和检索结果会省略这些已转移的源记录。冲刺历史会保留原有计数，并通过目标指针标识已转移内容。不会自动关闭任何冲刺。

使用现有的 show 操作读取源项目或已复制的决策、经验或任务，并显式指定 projectRoot；结果会包含 spunOutTo 或 spinOutOrigin，以及可读地址。对于历史后续步骤，请使用 rbook_context(action="next_steps", nextStepAction="list", nextStepIds=[23], projectRoot="/work/projects")。 显式 ID 会包含已移动或已丢弃的记录；显式指定 nextStepStatus 仍会筛选这些记录。普通后续步骤列表仍只显示未完成的工作。没有冲刺的目标后续步骤在闲置 42 天后会被标记为空闲。CLI 不会立即上传任一存储：两者都将在下一次成功的 MCP 写入后，按照常规上传计划进入上传流程，并受已配置的上传控制约束。

中断后，请使用完全相同的命令重试。经验证已完成的操作会原样返回。如果目标副本提交后源记录发生了变化，将拒绝最终的源标记，并保留两个存储供检查。如果已预留的重试缺少已提交的目标回执，命令也会拒绝执行：它无法区分复制前发生的崩溃与此前复制凭据被删除的情况。请保留两个根目录和补救说明中提到的操作 ID，检查其账本和写入前快照，并在重试前解决或恢复冲突状态。不要删除预留记录来强制重新复制；重试绝不会静默覆盖已复制的工作。

环境变量

# Optional — connects to the hosted dashboard. Defaults to https://reasonbook.ai
# when unset; treat empty string as unset.
RBOOK_DASHBOARD_URL=https://reasonbook.ai

# Optional — the directory the server reads its own .env from. It does NOT select a project:
# use the projectRoot parameter, or --project-root in a server's config.
RBOOK_PROJECT_ROOT=/path/to/your/project

# Optional — override the credential + registry directory. Default: ~/.config/rbook
RBOOK_CONFIG_DIR=/custom/path

# Snapshot retention (default shown)
RBOOK_MAX_SNAPSHOTS=50

# Optional — disable background uploads after writes and explicit completion calls.
# Shared-store propagation and explicitly requested network actions remain available.
RBOOK_CHECKPOINT_SYNC=off

# Optional — disable shared-record exchanges started by hooks and the server timer.
# Explicit reasonbook sync and bundle commands remain available.
RBOOK_SHARED_SYNC=off

# Optional — turn off starting a share or a join through reasonbook.ai on this machine
# (off, false, 0 or no, in any case). On by default; a project already shared through the
# dashboard syncs either way.
RBOOK_DASHBOARD_SHARING=off

错误响应结构

每个工具都会返回统一的封装：

{
  "success": false,
  "error": {
    "code": "MISSION_NOT_FOUND",
    "message": "Mission 's99-m01' not found",
    "suggestion": "Use rbook_mission(action=\"list\") to see available missions"
  }
}

code 可供机器读取，message 面向用户，suggestion 提供具体的下一步操作。验证错误包含 validValues（string[]）。状态错误可能包含 currentState：通常在相关任务、会话或冲刺状态可用时，它是一个状态字符串；只有在 SESSION_ALREADY_ACTIVE 错误中，它才是一个对象 { id, type, title, startedAt, captureCount }。读取它之前，请先根据 code 进行分支处理。

安全性

• 仅追加式审计。 会话事件和任务转换均为仅追加行。上下文快照会保留其行、ID 和事件，但 rbook_db(action="prune_snapshots") 可以清空 Reasonbook 自行写入副本的内容。
• 凭据原子写入。 credentials.json 通过临时文件加重命名的方式写入，权限为 0600。
• 数据库快照。 rbook_db(action="snapshot") 会按需复制数据库。rbook_sprint(action="complete") 会尝试在关闭前后创建快照；快照失败只会发出警告，不会阻止完成。对非空选择应用 rbook_db(action="prune_snapshots") 需要备份，而 rbook_db(action="restore") 会先将实时数据库复制到 rbook/db/snapshots/pre-restore/。RBOOK_MAX_SNAPSHOTS 限制保留的快照数量：创建新快照时会删除超出限制的最旧快照，包括自动创建的快照。其他操作都不会预先创建快照，也没有软删除保护机制——rbook_db(action="purge") 会从仪表板镜像中删除此项目的数据；如果项目正通过 reasonbook.ai 共享，则会拒绝执行。请参阅 SECURITY.md。
• 仅在支持的地方提供试运行。 rbook_context(action="condense") 接受 dryRun，可在不提交更改的情况下预览。这并非修改类工具的通用属性。Backfill 旧版事件重放试运行功能已停用，调用时会拒绝执行并返回 LEGACY_SYNC_RETIRED。

已知限制

• 只有在所有活跃副本都报告支持后，共享记录才会切换到协议 2；rbook_review 会列出阻止切换的副本。在切换之前，ID 声明按现有时钟顺序处理。切换之后，首次计入的接受操作会确定声明的位置；切换前的声明优先于之后的声明；一旦副本持有所有位置靠前的声明数据，已接受的 ID 就不可更改。可预测的 ID 仍可能被抢先声明；恢复会按时钟顺序处理此前尚未判定的事务。必须将已消失的副本搁置，才能停止其阻碍切换。在 reasonbook.ai 上，其所有者页面需要由主机部署搁置功能，才能提供该操作。
• 切换到协议 2 后，旧版读取方只能接收每个流中首次出现协议 2 更改的完整事务之前的内容。加入、后继副本以及计划迁移到旧版或未报告版本的读取方都会被拒绝。**降级可能会在本地重命名 ID：**旧副本仍会发送自己的写入，但不会接收边界之后的内容；旧版权威副本会保留成员的协议 2 写入。继续共享工作前，请升级所有副本。只有当切换记录位于已采纳的权威前缀中时，恢复才会保留该切换。
• 已注册且配置了仪表板凭据的项目，会在服务器运行期间于写入和显式关闭后上传快照；手动执行 rbook_db(action="backfill") 会立即请求上传整个文件。共享记录交换使用各自的钩子、计时器和 RBOOK_SHARED_SYNC 控制项。
• SQLite 是事实来源；仪表板保存所有者上传的镜像。共享副本通过 reasonbook sync，经由 reasonbook.ai、SSH 或捆绑包交换记录。
• 在 reasonbook.ai 上，将项目迁回的测试使用了一名成员，并关闭了自动同步：在该副本自迁移后尚未与仪表板同步的情况下，所有者副本通过 SSH 将成员副本追赶到最新状态。启用自动同步后，成员副本很可能会先同步。以下情况尚未测试：成员副本先与仪表板同步，随后仪表板要求通过 SSH 或捆绑包与所有者副本同步；以及所有者的机器无法通过 SSH 访问的成员副本。仪表板的活动动态默认每页显示 50 条，最多 100 条；决策页面每页显示 20 条决策；更早的条目位于后续页面。
• 通过 reasonbook.ai 共享的项目由成员的 Agent 进行更改；仪表板页面显示记录。仲裁器库支持从幸存副本恢复，并可在迁回后保留成员／账户绑定并重新共享。这些功能需要部署仪表板对应的路由、存储的历史记录和所有者控制项。在此之前，丢失的托管副本仍会导致托管共享停止；通过旧版主机重新共享也无法安全地恢复其成员。每位成员都会保留自己的本地副本。
• 通过 reasonbook.ai 共享时，会列出并拒绝所有者的其他副本，只要这些副本曾写入、成功交换过记录或保留了 SSH 路由，其中包括已观察到或已路由的前所有者副本。仪表板路由行、已切断的副本以及此文件夹的旧身份不计入其中。在直接权威副本上，reasonbook set-aside --replica <id> 会预览某个已消失副本所持的截止位置和最近一次交换记录；添加 --yes 可记录该副本。此人的其他副本仍是成员。角色变更、移除和重新加入都会保留该切断状态；之后的写入会继续隔离，等待该成员自行重新处理；恢复过程不会等待该副本。对于托管项目，仲裁器库提供仅供仪表板使用的 setAside 操作；若副本在过去 7 天内曾联系，操作需要明确确认。reasonbook.ai 必须部署此操作，其所有者页面才能提供该功能。仪表板负责仲裁时，拒绝本地管理操作。
• 如果记录包含搁置副本，则计划交接或仪表板共享目标必须报告库版本为 4.5.0 或更高。版本报告未知也会被拒绝；共享会在上传前进行检查。**由 4.5.0 之前的二进制文件运行的 reasonbook recover 可能会撤销搁置状态。**使用恢复副本前，请先升级。旧版 rbook_db(action="clone") 和 rbook_db(action="pull") 操作会以 LEGACY_SYNC_RETIRED 拒绝；这些操作值会保留到 5.0.0。

文档

• 文档主页 — 介绍项目、安装方式、各个级别以及更多资料的阅读位置。
• 交接演示 — 75 秒的录制运行回放，并附有文字记录。
• 信任 — 哪些内容会离开你的设备、钩子会读取什么，以及如何关闭各个部分。
• 隐私 — 数据收集、仪表板可见性、保留期限和移除方式。
• 方法 — 五条准则、三个级别以及如何提升级别。
• 开始使用 — 客户端配置和可选的 Builder 演练。
• Harness 覆盖范围 — 原生适配器、MCP 提示词，以及不使用钩子时的备用方案。
• 工具参考 — 每个工具、操作和参数（根据工具定义生成）。
• 更新日志 — 发行说明和工具接口变更。

开发

git clone https://github.com/kneelinghorse/reasonbook
cd reasonbook
npm install
npm run build
npm test

开发需要 Node.js 20.17 或更新版本（lint-staged 16.4）；已发布的包可在 Node.js 20 或更新版本上运行。

提交前钩子通过 husky/lint-staged 运行 lint 和格式化检查。此公开仓库是代码镜像；发布验证和 npm 发布均在私有源代码库中进行。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。