Whiteboard的Software Map实战：为代码库绘制可交互的C4架构图

Whiteboard的Software Map实战为代码库绘制可交互的C4架构图【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboardWhiteboard 是一款开源的桌面协作画布应用其中的Software Map软件地图功能可以让 AI 代理为你的代码库自动绘制可交互的 C4 架构图——从系统、容器到代码元素层层展开点击任意节点即可直达源码并直观标注本次变更中新增、修改与删除的部分。什么是 Software Map传统架构文档最大的痛点是画完就过期。Whiteboard 的 Software Map 把架构模型与代码库绑定在一起图中的每个节点都通过coverage字段关联到具体文件甚至行号图随代码变化而更新天然保持最新。它严格遵循 C4 架构模型的经典分层并向下延伸到代码层面C4 层级含义示例Person用户、外部角色前端用户Software System软件系统订单服务Container容器/进程Checkout API、WorkerData Store数据存储orders 表、对象存储Component组件订单仓储、履约队列Code Element具体代码元素某个类、函数带行号范围完整的元素类型定义可以查看 software-map-model.ts每个节点还支持added/modified/removed等变更状态标记。三步生成你的软件地图第一步安装并连接 AI 代理下载 Whiteboard 桌面应用在欢迎页面连接 Claude Code、Codex 等编码代理。如果想直接阅读源码可执行git clone https://gitcode.com/gh_mirrors/whiteboard36/whiteboard第二步让代理审查你的分支用一句话告诉它你的目标例如review 当前分支对比 main用 Whiteboard 展示这次改动涉及的系统结构。第三步在画布中打开结果代理会在画布中输出一篇审阅文章Software Map 以卡片形式内嵌其中可点击展开为全屏视图。软件地图的交互玩法Software Map 不是静态图片而是一个可操作的架构图画布渲染核心见 SoftwareMap.tsx 与 c4-projection.ts层层展开地图初始只显示根级系统与人员点击节点逐层展开容器、组件直到定位到代码跳转源码选中某个代码节点会打开侧边 CodePeek 检查器直接定位到对应文件与行编辑器能力快捷键、LSP开箱即用全屏浏览右上角控制可切换内嵌/全屏两种模式复用同一渲染器只改变可用空间键盘导航支持键盘聚焦与热键操作详见 hotkeys-tab.tsx。看懂地图背后的数据结构想手动微调或理解代理生成了什么可以查看仓库自带的教程示例 software-map.json——一个订单服务的完整 C4 模型配套的可运行样本在 tutorial/sample-service。结构上只有三个顶层键people参与的人员/外部角色systems系统及其嵌套的containers→componentsrelationships节点间的有向关系分两种——call代码调用可定位到调用点与semantic语义关系如创建订单每条关系可带标签和说明。配套教程数据还包括 document.json 与 trace.json完整还原一次代理审阅产出。Head/Base 对比一眼看清这次改了什么这是 Software Map 最实用的能力审阅会同时生成 head 与 base 两份地图快照写入.bundle/software-map目录head-map.json/base-map.json。对比能力由这些模块支撑software-map-diff-counts.ts统计各层级新增/变更节点数software-map-topology-diff.ts检测拓扑变化比如新增了一条依赖边。在画布上本次 PR 修改过的节点会带变更标记配合只看变更过滤评审时能迅速抓住结构层面的变化。新手常见问题问图是谁画的我能改吗图由 AI 代理基于代码库分析生成如果你对某处不满意高亮选中后交给代理它会按你的要求在画布上重绘。问数据存在哪里安全吗Whiteboard 运行在本地代码库之上所有地图数据落盘在本地审阅目录匿名遥测不包含你的代码与文字内容详见 docs/privacy.md。问它和 PlantUML 这类工具的区别PlantUML 输出静态图片Software Map 输出的是与代码双向绑定的交互模型——节点能展开、能跳到源码、能感知 diff是活的架构图。掌握 Software Map 后架构评审不再是翻文档而是在一张活的 C4 地图上与 AI 一起对话——这正契合 Whiteboard 的理念理解才是新的瓶颈。【免费下载链接】whiteboardopen-source canvas for thoughtful software design项目地址: https://gitcode.com/gh_mirrors/whiteboard36/whiteboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考