Whiteboard JSON Review API完整参考从create到edit命令的开发者手册【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboardWhiteboard 是一个面向深思熟虑的软件设计的开源画布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—— 列出服务端当前发布的全部工具名与输入 Schemawhiteboard api tool-name json—— 直接调用一个工具例如whiteboard api review_get {reviewId:…,full:true}whiteboard api tool-name -—— 从 stdin 读入 JSONwhiteboard mcp—— 以 stdio 方式暴露 MCP 适配器需要桌面端或whiteboard server start正在运行。解析与委托逻辑位于 packages/review/src/review-api/agent-cli.ts。 create 命令详解三种方式建好第一个 Reviewcreate是 JSON Review API 的起点它支持三种目标target可按需选择方式参数适用场景worktree 目标{kind:worktree, repositoryId, base?}评审已保存的工作文件含未提交、未跟踪文件base缺省为仓库默认分支commits 目标{kind:commits, repositoryId, head, base?}固定到不可变 commit适合归档式评审给父 commit 可评审单个提交的改动GitHub PRpullRequestUrl可单独使用服务端自动拉取 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可不在桌面端弹出新评审实现纯后台创作scratchpadkind:scratchpad指向唯一的草稿板插入的内容置顶最新在上。工具描述原文packages/review/src/review-api/authoring-tools.ts✏️ edit 命令详解五种编辑操作一览edit接收{reviewId, edit}其中edit是五选一的操作操作参数行为insertcontent, parentId?, afterId?插入新块缺省追加到文档根updatetargetId, changes字段级补丁保留未给出的字段null删除可选字段movetargetId, parentId?, afterId?移动块到新位置removetargetId删除块删除流程图节点会连带删除其边replacetargetId, 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代码片段languagetext可选captionsection分节必须有children不是blocks标题自动生成锚点callout提示框醒目的说明性容器tutorial教程带步骤的教学结构flow_diagram流程图nodesedges数组节点 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 的特色labelbase侧同理路径相对仓库且需 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 IDworktree 目标可跳过review_create—— 建评审拿到reviewIdreview_activity_begin—— 获取编辑租约记下leaseIdreview_edit× N —— 小步插入内容长停顿用review_activity_update续期review_activity_end—— 结束会话读者即可视为完成。 记忆口诀create 定目标lease 保安全edit 写小步commandId 保幂等。⚠️ 新手最容易踩的 5 个坑字段名写错section 要children不是blocksmarkdown 块要markdown不是text忘了租约另一会话持有租约时你的写入会得到 HTTP 409先begin再写重试方式不对响应丢失后必须用相同的commandId和输入重试而不是重新生成图元跨图移动flow_node/step不能脱离所属图删除节点会连带删边源码链接不校验review-source:链接的行号必须是真实存在的范围写错会被保存前拒绝。 延伸阅读API 路由与存储全解packages/review/src/review-api/README.md工具定义与 Schemapackages/review/src/review-api/authoring-tools.ts块类型注册表packages/review/src/review-api/blocks/index.tsCLI 适配层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），仅供参考