Whiteboard

一个桌面应用，编码 agent 和人在这块同样的画布上干活。agent 通过 MCP 接入——一条共享的 whiteboard mcp 启动命令同时服务 Claude Code、Codex、Cursor、Pi 和 OpenCode——然后把它做过的事画出来：时序图、实体关系图、C4 软件地图、调用栈差异、代码窥视，以及从它自己的轨迹里摘出来的引文。这块画布不是自由涂鸦，而是一份由有类型的块组成的文档，一共十四种；每种块都能携带一个写成 head/path#L10-L24 的源码锚点，而每个锚点都会对着这次审查所钉住的那几次提交做校验，于是在时序图上点一个方框，就能在随仓库一起 vendored 的 Code OSS 编辑器里打开它来自的那个文件，语言服务和快捷键都是现成的。一个用 Rust 写的、理解语法的语义化 diff 查看器把噪音收掉——新增的大函数被概括成伪代码，测试与文档改动被折叠隐藏——而一次审查可以分享到另一台机器。这个仓库只有六个星期大：2026-08-18 建立，575 次提交，2,400 个星，十六个 release，MIT。

谁做的仓库挂在 devdotfast 组织下，提交记录被一个账号主导：575 次提交里 292 次是 thesiti92 写的，样本里几乎每一条 pull request 也出自他；其后是 ketan0 的 128 次（116 次署名 Ketan Agrawal，另有 12 次挂在报告中单独列出的第二个账号上）、Sidharth Menon 的 55 次、Milan Bhandari 的 35 次。贡献者列表里有十一个账号，其中两个是机器人。侦察报告没有提供所有者的任何资料——没有显示名、注册时间或仓库数——所以这里除提交记录之外不做任何断言。

1. 01

   六个星期、一次导入、一次改名，和一条预览通道

   仓库建于 2026-08-18，二十六分钟之后的最早一次提交标题是 Import Review Desktop——命名的历史就是从这里开始的。按月拆开，这个分布对一个年轻项目来说也算失衡：八月 56 次，九月 519 次。贡献者列表里有十一个账号，其中一个主导：thesiti92 写了 292 次，接着是 ketan0 的 128 次——116 次署名 Ketan Agrawal，另有 12 次挂在报告单独列出的第二个账号上——Sidharth Menon 55 次、Milan Bhandari 35 次、dependabot 32 次、一个 GitHub Actions 机器人 18 次，还有一个 detail-app[bot] 11 次。125 次提交带共同作者尾注，其中 64 条写的是模型名：Claude Opus 5.5 (1M context) 35 次、Claude Opus 5.5 14 次、Claude Fable 5.1 11 次、Claude Opus 5 (1M context) 4 次。同样这六个星期里放着十六个 release 和二十个 tag。release 标题至今留着改名的痕迹：仓库出现当天的 review-desktop-v0.0.23、2026-09-26 的 「Review Desktop 0.1.3」、以及 2026-09-28 的 「Whiteboard 0.1.5」——第一个用现在这个名字发布的版本。旁边并排跑着带日期和构建号的预览 tag，从 v0.0.34-preview.20260924.56 到 v0.1.6-preview.20260929.79：这是一条真的在发东西的通道，而不是一条等待中的版本线。

2. 02

   画布上不是方框和箭头，是十四种有类型的块

   块的定义放在 packages/review/src/review-api/blocks/，一种块一个文件，一共十四种：sequence、flow_diagram、database_lens、software_map、code、code_peek、call_stack_diff、trace_quote、markdown、callout、divider、image、section、tutorial。每种旁边都有一份 JSON 夹具放在 fixtures/blocks/ 下，另有一个共用的 definition.ts、一个 2,375 字节的 index.ts，以及负责发放身份的 ids.ts。所以这是一套词汇表固定的文档格式，而不是一块可以随便画的板子。sequence 块背后是 sequence-steps.ts；软件地图是一个 C4 模型，其上是 28 KB 的 c4-projection.ts、83 KB 的 c4-layout-geometry.ts、c4-node-measurement.ts 与 c4-edge-label-geometry.ts，底下是 ELK 布局，渲染则是 104 KB 的 SoftwareMap.tsx；database_lens 就是实体关系图，带一个 36 KB 的渲染器、一份 4.3 KB 的 schema 和自己的 store。section 是唯一会嵌套的那种：pull request 820 记录说，它的 schema 为了让 section 嵌套块不得不动用 $ref。负责画的那一半在 packages/review/app/src 里，diagrams.tsx 36 KB、trace-document.tsx 36 KB、flow-graph.tsx 23 KB、blocks.tsx 12 KB——而 README 把整套形状的理由写清楚了：点开一张时序图、一张实体关系图，或一条从 agent 轨迹里摘出的引文，就能直接跳到它底下的代码，快捷键和语言服务都来自那个 vendored 的编辑器。

3. 03

   锚点是一条关于某次提交的断言，而重新钉钉会把它淹掉

   每个指向代码的块都带一个源码锚点，而这个锚点才是这套格式真正吃重的地方。2026-09-30 之前 agent 写的是一个对象：{file, start: {side, line}, end: {side, line}, pins?}。pull request 821 把它换成了 agent 早就会为 markdown 链接写的那种字符串：head/path#L10-L24、base/path#L7，以及区间跨侧时用 GitHub 的 diff 锚点形式 diff/path#L84-R90。宿主把它们解析成和以前一样的选取对象，所以存储和画布都没变，而对象形式对测试、教程和更早的调用方仍然接受。字符串没法携带 pins，于是带锚点的块改用块级的 pins，markdown 块本来就是这样。锚点在写入时就会对着这次审查钉住的那几次提交做校验。pull request 822 讲的是这些钉子移动之后会发生什么：重新钉钉会对每一个保留下来的区间报警，哪怕它的文件在新提交上与旧提交逐字节相同，于是一次 rebase 到更新的 main 上，把三次审查里的全部 31 个锚点都报了出来，而那些文件 main 一个都没碰过——真正的改动和噪音读起来一模一样。现在宿主会先问清旧新两次提交之间两侧各自改了哪些文件（通过一个由 local-vcs 支撑的 filesChangedBetween provider），只对这些文件里的锚点报警；而在新钉子上校验不通过的区间，照旧一律上报。值得注意的是锚点的写入形态换了，而存储、画布与读取这三处都没有变——作者在 pull request 821 里特地写明了这一点，并且把对象形式保留给测试、教程与更早的调用方。

4. 04

   一个用字符数来衡量的 agent 接口

   面向 agent 的那一面是一份工具目录，而它的体积被当成一个设计变量，pull request 里直接用字符数把代价写出来。pull request 819：session_upload 的 map 这一种上传，把整个软件地图模型的 schema 都背了进去，约占每个 agent 都要加载的 253k 字符工具定义里的 196k；因为软件地图默认关闭、并且预计会以另一种形式回来，面向 agent 的工具现在只提供图片与轨迹上传，目录因此降到约 58k 字符，而宿主仍然接受地图上传。pull request 820：session_edit 对外发布的 schema 把每一种块都摊开写，还得为嵌套的 section 动用 $ref——25,424 字符，超过整个目录的一半——于是 agent 现在看到的 content 是一个「自己声明类型的开放对象」，每种块的字段挪进工具描述里一行一条；宿主仍然解析完整的 editSchema，所以接受什么、存什么完全没变，而 publishedEditSchema 与 editSchema 由同一个函数生成，两者不可能各走各的。客户端不再校验形状之后，宿主的报错就成了唯一反馈，所以块和插入内容改为按类型判别，报错会点名出问题的那种块。pull request 823：commandId 与 leaseId 原本声明成 z.uuid()，zod 会把它发布成 format 加一段 250 字符的 pattern，19 处副本，约占全部工具 schema 文本的五分之一，可宿主只把它们当键用；现在改成 z.string().min(1)，而上传 id 仍然是 UUID，因为那是 agent 自己编的。pull request 821 把 session_lens_edit 从 4,501 字符压到 3,077。仍在开放的 pull request 825 走得更远：提议删掉那些读代码的工具——session_diff、session_file、session_source、session_tree、session_commits——理由是 agent 只能从持有这个仓库的机器上够到 Whiteboard，而在那台机器上 git 或 jj 读的是同一批提交。这些工具原本约束的行为，改由 packages/review/instructions/ 下四个指令文件承担：authoring.md 3,490 字节、trace-archaeology.md 4,551 字节、scratchpad.md 3,330 字节、file-lenses.md 1,150 字节。

5. 05

   社区回合：一次包冲突、一个换行符 bug、一份 roadmap

   样本里三条外部 bug 报告有两条是打包与渲染故障，两条都在当天得到回应。issue 802，来自 LeFelps：从签名过的 pacman 仓库安装会中断，因为包里带了 /usr/bin/review，而这个路径归 archlinux-contrib 所有。维护者二十九分钟后回了：「oh just saw you put up a pr nice! its just an alias right now, the main cli moved to whiteboard so feel free to axe it on your machine」——随后 pull request 806 把 review 和 review-preview 两个别名一次性从 Arch、RPM 和 DEB 里摘掉，理由是这个名字已经退役、可能在别处也撞车，并补了一句「glad we renamed lol」。Arch 仓库的检查现在会先装 archlinux-contrib，再在 Whiteboard 安装和卸载之后核验它那个 review 脚本的归属与内容。issue 805，来自 mhebert-inkbit，带了一整套复现步骤：在 Windows 上 core.autocrlf=true 时，工作区文件被拿去和 LF 的 blob 原样比对，于是 Markdown 这类纯文本文件显示成每一行都改了——notes.md 200 行里改了 200 行。根因在那个 Rust 写的 diff 查看器里，而它是独立项目——diffr，以 @dev.fast/diffr 的形式钉进来——0.1.8 通过 Git 的 clean filter 读取工作区文件修掉了它；同一个文件在 0.1.7 上量到 200 行改动，在 0.1.8 上是一行。样本里还有两条更小的外部贡献：issue 796，说混合的看板加 diff 视图里查找很慢、会把界面卡住；以及 KappaShilaff 的 pull request 794，把面板分隔条的抓取区域从 10px 加宽到 26px 而不动布局。同一个星期里项目还发布了 roadmap：pull request 811 加了顶层 ROADMAP.md，813 把它链到 README 顶部导航，随后作为 wiki 页面发布，并留下一条评论说明通知已勾掉、并链到了 issue 745。

6. 06

   把性能写成数字，把「删掉」当成习惯

   这个仓库把性能当作需要测量并写下来的东西，pull request 里就带着数字。pull request 799：ELK，也就是 elkjs/lib/elk.bundled.js 的 1.4 MB，约占 2.5 MB 画布包的整整一半，而 c4-layout-geometry.ts 在模块加载时就构造了一个实例，于是每次打开画布都要为一个可能根本不存在的图付钱；新增的 src/elk.ts 暴露一个 loadElk()，只动态导入一次并缓存一个共享实例，在 Chromium 里量到没有流程图或软件地图的审查，每次打开画布从 130 ms 降到 50 ms。pull request 809：在一个带代码窥视的画布上查找，会每敲一个键就把所有窥视搜一遍，而每次窥视搜索都会重算结构化 diff，其中 utf16Column 每个字符都分配一个 TextEncoder——在一次 profile 里，526 ms 的窥视搜索有大约 480 ms 花在这里；现在打字停顿 150 ms 之后才搜窥视，被取代的搜索根本不启动。那条打字 journey 从 5,970 ms、渲染进程阻塞 5,493 ms，降到约 515 ms、阻塞 100 ms。pull request 797：Electron 会带上约 220 个 Chromium 界面翻译目录——macOS 上 Electron Framework.framework 里 48.8 MB 的 *.lproj，其他平台上则是 locales/*.pak——而这个界面只有英文，于是往一个本来就存在的构建过滤器里加了三条排除规则。pull request 814：把 diff 侧栏拖过它 250px 的最小宽度之后，它会折成一条 44px 的窄条，上面只留已读圆环、一个放大镜、每个 lens 名字的头五个字母（Uncategorized 读作 n/a）和一个文件图标。pull request 808 值得读两遍：约 250 个测试、109 个文件里大约 4.4k 行被当作「变更探测型、同义反复或重复」删掉，只留下针对仓库身份、UI 状态存储、传输边界和 vendor 完整性的源码扫描不变量守卫，上游 Code OSS 的测试一行未动；而 373 字节的 AGENTS.md 明确要求：碰到这种测试不要顺手更新，要删掉。pull request 800 走的是相反方向：bug 报告里的轨迹附件被整个删掉，因为没有任何一份报告能走到它。