Whiteboard JSON Review API完整参考：从create到edit命令的开发者手册
【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboard
Whiteboard 是一个面向深思熟虑的软件设计的开源画布（canvas），它的核心是一套JSON Review API：用一条create命令就能建好 Review 文档，再用五种edit编辑操作（insert / update / move / remove / replace）持续改写。这套 API 同时服务于桌面端画布、whiteboard api命令行与 MCP 适配器，是 AI Agent 自动写作评审文档的关键入口。本文带你从 0 到 1 走通它。
🧭 30 秒认识 Whiteboard Review API
整套 API 挂在/reviews-api路由下，桌面应用与无头模式（whiteboard server start）共享同一个本地 JSON 存储review-api.db，并统一使用 token 认证 + 有界 JSON 请求读取器。核心机制可以概括为三点：
- 一条命令一个版本：所有写操作都走
POST /commands，每个被接受的编辑立即保存为一个带标题和时间戳的版本； - 幂等重试：请求携带
commandId（可省略，由服务端分配），丢失响应后用相同commandId重试只会拿回第一次的结果，绝不会写两遍； - 租约式编辑：通过
review_activity_begin获取 3 分钟有效期的编辑租约（lease），避免多个 Agent 互相覆盖。
完整路由表见官方参考：packages/review/src/review-api/README.md
🚀 两种调用方式：whiteboard api与whiteboard mcp
所有工具都是薄 HTTP 客户端，工具目录直接来自服务端，因此永远不会与服务端"漂移"。常用形态：
whiteboard api tools—— 列出服务端当前发布的全部工具名与输入 Schema；whiteboard api <tool-name> '<json>'—— 直接调用一个工具，例如whiteboard api review_get '{"reviewId":"…","full":true}'；whiteboard api <tool-name> -—— 从 stdin 读入 JSON；whiteboard mcp—— 以 stdio 方式暴露 MCP 适配器（需要桌面端或whiteboard server start正在运行）。
解析与委托逻辑位于 packages/review/src/review-api/agent-cli.ts。
📦 create 命令详解：三种方式建好第一个 Review
create是 JSON Review API 的起点，它支持三种目标（target），可按需选择：
| 方式 | 参数 | 适用场景 |
|---|---|---|
| worktree 目标 | {kind:"worktree", repositoryId, base?} | 评审已保存的工作文件（含未提交、未跟踪文件），base缺省为仓库默认分支 |
| commits 目标 | {kind:"commits", repositoryId, head, base?} | 固定到不可变 commit，适合归档式评审；给父 commit 可评审单个提交的改动 |
| GitHub PR | pullRequestUrl（可单独使用） | 服务端自动拉取 PR 到已注册的 checkout，钉住 PR head 与 diff base，标题默认取 PR 标题 |
最小示例：
{ "commandId": "8575b264-9ef4-46c9-af3c-8185545aeebd", "operation": { "type": "create", "title": "My change", "target": { "kind": "worktree", "repositoryId": "repo-1" } } }几个高频要点：
- 返回值自带上下文：结果携带
review字段（含已解析 commit 的 target、origin 的 PR、仓库名与路径），diff 前无需再读一次； - PR 复用：对同一 PR 重复
create会返回已存在的评审并报告headMoved，可用reuseExisting:false强制新建； - 后台写作：设
open:false可不在桌面端弹出新评审，实现纯后台创作； - scratchpad：
kind:"scratchpad"指向唯一的草稿板，插入的内容置顶（最新在上）。
工具描述原文：packages/review/src/review-api/authoring-tools.ts
✏️ edit 命令详解：五种编辑操作一览
edit接收{reviewId, edit}，其中edit是五选一的操作：
| 操作 | 参数 | 行为 |
|---|---|---|
insert | content, parentId?, afterId? | 插入新块；缺省追加到文档根 |
update | targetId, changes | 字段级补丁，保留未给出的字段，null删除可选字段 |
move | targetId, parentId?, afterId? | 移动块到新位置 |
remove | targetId | 删除块（删除流程图节点会连带删除其边） |
replace | targetId, content | 保留外层 ID、子节点换新 ID 的整体替换 |
典型 insert 请求：
{ "operation": { "type": "edit", "reviewId": "<create 返回的 ID>", "edit": { "type": "insert", "content": { "type": "markdown", "markdown": "# Summary\n\nWhat changed." } } } }必须知道的规则：
- 位置缺省即追加（scratchpad 上则是置顶）；
- 图元有边界：序列图的
step、流程图的flow_node/flow_edge必须以所属图为父级，不能跨图移动；新flow_node可携带link:{from|to}一次性带上边； - 写小写勤：有读者在看时，一次只写一个段落，画布会"边写边画"；整图则一次插入，画布一次性快速描画；
- 结果即地址：insert / replace 的返回会给出目标块 ID 及其一级子节点，新组件无需再读就能继续编辑；
- 无版本号参数：后到的同字段编辑获胜，冲突而非合并。
每个被接受的编辑还会在版本上留下lastEdit元数据（类型、落点、所属块），用于画布的落笔动画。
🧱 块内容参考：14 种 building block
文档是一棵由 Markdown 和自包含组件构成的树，服务端会直接给对象分配 ID。全部 14 种块类型注册在 packages/review/src/review-api/blocks/index.ts：
| 类型 | 用途 | 一句话说明 |
|---|---|---|
markdown | 正文 | 安全 Markdown；仓库文件链接须用review-source:head/path#L10-L24形式 |
code | 代码片段 | language+text，可选caption |
section | 分节 | 必须有children（不是blocks），标题自动生成锚点 |
callout | 提示框 | 醒目的说明性容器 |
tutorial | 教程 | 带步骤的教学结构 |
flow_diagram | 流程图 | nodes+edges数组，节点 key 唯一 |
sequence | 时序图 | actors映射 +steps消息数组 |
call_stack_diff | 调用栈对比 | base与head两个帧数组，各自可为空 |
database_lens | 数据库视角 | actors/stores/collections/fields+ 用例操作 |
code_peek | 源码窥视 | 钉住文件与 1 基行号区间 |
software_map | 软件地图 | 引用已上传的 map 资源 |
trace_quote | 追踪引用 | 引用已上传的 trace 资源 |
image | 图片 | 引用已上传的图片资源 |
divider | 分隔线 | 视觉分隔 |
Markdown 中的源码链接是 JSON Review API 的特色：label（base侧同理），路径相对仓库且需 URL 编码，无效路径或行号会在保存前被拒绝。
🔄 配套命令与工具速查
写文档之外，API 还提供一整套辅助命令（均为POST /commands的 operation 或独立 GET 路由）：
- 生命周期：
rename改标题、set_target换目标（保留内容）、repin换源钉、restore恢复历史版本、attention标记已读/可逆弃置、delete永久删除； - 读取：
review_list列表、review_get可读文本大纲（targetId精确读一个组件、full:true读全文、format:"json"拿原始数据）、review_history版本列表、review_diff变更文件摘要或纯文本 patch（每行带 base/head 行号，正好用于生成review-source链接）； - 源文件访问：
review_source（精确行区间）、review_file（整文件）、review_tree（目录）、review_commits（提交列表）； - 资源：
review_upload上传图片 / trace / map（内容不可变，复用 ID 要求内容一致）； - 租约：
review_activity_begin/review_activity_update/review_activity_end三段式管理写作会话，lenses与document两种 scope 可被不同会话同时持有。
🗺️ 一条典型的自动化写作流水线
把上面的能力串起来，一个 Agent 的完整工作流是：
review_register_repository—— 注册本地 Git 仓库；review_resolve_pins—— 把分支/标签解析为不可变 commit ID（worktree 目标可跳过）；review_create—— 建评审，拿到reviewId；review_activity_begin—— 获取编辑租约，记下leaseId；review_edit× N —— 小步插入内容，长停顿用review_activity_update续期；review_activity_end—— 结束会话，读者即可视为"完成"。
💡 记忆口诀：create 定目标，lease 保安全，edit 写小步，commandId 保幂等。
⚠️ 新手最容易踩的 5 个坑
- 字段名写错：section 要
children不是blocks；markdown 块要markdown不是text； - 忘了租约：另一会话持有租约时你的写入会得到 HTTP 409，先
begin再写； - 重试方式不对：响应丢失后必须用相同的
commandId和输入重试，而不是重新生成； - 图元跨图移动：
flow_node/step不能脱离所属图，删除节点会连带删边； - 源码链接不校验：
review-source:链接的行号必须是真实存在的范围，写错会被保存前拒绝。
📚 延伸阅读
- API 路由与存储全解：packages/review/src/review-api/README.md
- 工具定义与 Schema：packages/review/src/review-api/authoring-tools.ts
- 块类型注册表：packages/review/src/review-api/blocks/index.ts
- CLI 适配层：packages/review/src/review-api/agent-cli.ts
- 创作指导文档：packages/review/instructions/authoring.md
- 仓库说明：README.md
掌握 create 与 edit 这两个核心命令后，你就拥有了用 JSON Review API 驱动 Whiteboard 画布的完整能力——从注册仓库到逐段落笔，整个流程都可脚本化、可重试、可协作。
【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboard
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
