Whiteboard 完全指南：让 AI Agent 在可视化工作区里讲清楚代码
当 AI 编码 Agent 能一次生成数百行代码，真正稀缺的往往不是“写出来”，而是让人快速理解：它为什么这样设计、改动影响了什么、哪些决定是 Agent 自己做的。Whiteboard 选择了一个很具体的切入点：把架构图、语义 Diff、Agent 决策记录和本地代码放进同一个桌面工作区。
Whiteboard 解决的不是“画图”
Whiteboard 是一个 MIT 许可证的开源桌面应用，面向 macOS、Windows 和 Linux。它可以连接 Claude Code、Codex 等编码 Agent，让 Agent 把工作结果绘制到应用内的画布上。这里的重点不是替代 Mermaid 或普通白板，而是把可视化内容和真实代码关联起来。
例如，Agent 审查当前分支时，可以在 Whiteboard 中展示序列图、实体关系图，或引用自己的运行轨迹。点击这些可视化内容后，用户可以跳到对应代码；反过来浏览代码时，则可以使用 VS Code 提供的快捷键和 LSP 能力。这样，架构讨论不再停留在一张脱离仓库的图片上。
三个值得关注的设计
1. 从图直接回到代码
传统设计工具擅长表达“应该是什么样”，但很难持续回答“它对应哪几行代码”。Whiteboard 将图、Agent trace 和代码导航放在同一条路径里，适合审查 API 变化、理解遥测改动，或在接手陌生仓库时建立整体认识。
一个实用的提问方式是先限定审查范围，再要求 Agent 输出设计依据：
请审查当前分支相对于 main 的改动。 先在 Whiteboard 中展示主要模块、调用顺序和数据流， 再列出每个重要决定对应的代码位置，以及可能的副作用。
这里的关键是要求“决定”和“代码位置”同时出现。只有图没有证据，仍然容易变成漂亮但无法验证的总结。
2. AST 感知的语义 Diff
Whiteboard 内置了用 Rust 编写的语义 Diff 查看器。它不是简单地按文本行展示变化，而是尝试突出与代码结构相关的改动：大型新增函数可以折叠成伪代码，测试和文档变化也可以隐藏或收起。项目还提供基于 WASM 的插件机制，用于调整这类视图。
这对 Agent 生成的提交尤其有用。普通 Diff 可能被格式化、测试快照和生成文件淹没；语义视图则更适合先回答“行为改变了吗”，再深入查看实现细节。
3. Decision log
Agent 的运行结果通常只留下最终 Diff，但真正影响维护成本的，可能是它中途做过的取舍：为什么选择某个 API？为什么绕开已有抽象？哪些需求是明确的，哪些只是模型自行补全的？
Whiteboard 试图把这些决策和 Agent trace 链接起来，让人能够回看需求、实现方式和自主决定。它并不能替人做设计评审，但能缩短从“结果不对”追溯到“决定在哪里发生”的路径。
一次实际工作流
安装应用并打开后，在欢迎界面连接 Claude Code、Codex 或其他编码 Agent。接着可以按下面的顺序使用：
- 让 Agent 先对当前分支做架构审查，而不是立即修改文件。
- 要求它用序列图或模块图解释调用关系，并链接到相关代码。
- 在语义 Diff 中隐藏测试和文档噪声，先检查核心行为变化。
- 对不理解的地方在画布中高亮，再把问题交回 Agent，让它重新绘制说明。
- 最后回到普通代码浏览和测试流程，确认图上的判断与实际运行结果一致。
这种流程适合大型重构、跨模块 API 变更和接手 AI 生成代码。它把 Agent 的第一稿当作可审查的设计材料，而不是直接当作最终答案。
目前的边界
Whiteboard 仍然更像审查和理解工具，而不是完整 IDE。当前不能直接在 Whiteboard 中编辑文件；跨多个仓库工作也还不够完善。共享审查结果后，后续更新不会自动同步给其他人，需要重新分享。此外，团队托管产品只是规划方向，项目当前强调本地运行和始终可自托管。
隐私方面，项目说明应用运行在本地 checkout 上；匿名遥测不包含代码、Diff、Whiteboard 文本、提示词或模型输出，并提供隐私说明、遥测参考和关闭遥测的选项。对敏感仓库来说，仍应在组织策略允许的范围内连接 Agent，并自行检查遥测配置。
结语
AI 编码的瓶颈正在从“能不能生成代码”转向“人能不能理解并验证生成结果”。Whiteboard 的价值不在于再做一个画布，而在于把架构图、语义 Diff、决策记录和代码导航连接起来。它尤其适合那些已经使用 Claude Code 或 Codex、却发现纯终端输出难以进行设计评审的团队。
如果你想试用，建议从一个真实的分支审查开始，而不是先画一张空白架构图：让 Agent 解释已有改动，再逐项检查图上的结论是否能回到代码和测试。这个顺序更能检验 Whiteboard 是否真正减少了理解成本。