Floorplan 是什么:让 Agent 把代码画成可点的地图

Floorplan 是一个给 Claude Code 和 Codex 用的插件:让 Agent 读完你的代码,画出一张可以点开、可以提问的交互地图。每个模块、文件、接口都有一句大白话名字,前端请求连到哪个后端接口也画出来。截至 2026-11-09,最新版 0.6.3(2026-11-02 发布),MIT 许可证,GitHub 3,275 星。
它是什么
作者 Hayden Schmitty 的出发点很直接:你用 AI 做出了一个能跑的应用,但被问到「用户结账时到底发生了什么」「改这张表会坏什么」,自己答不上来。Floorplan 就是补这张没人画过的图。它先用不依赖第三方包的 Node 脚本扫描文件、import、路由和网页请求,再由 Claude 或 Codex 给每个部分起名、写描述,最后生成一个 floorplan/index.html。
| 仓库 | github.com/haydenschmitty/floorplan |
|---|---|
| 作者 | Hayden Schmitty |
| 许可证 | MIT |
| 热度 | GitHub 3,275 星(GitHub API,2026-11-09 15:04 北京时间);仓库创建于 2026-10-27 |
| 运行要求 | Node.js 18+,Claude Code 或 Codex;推荐装 Claude Code CLI,地图里的提问栏才能读真实代码 |
| 最新版本 | 0.6.3(发布于 2026-11-02 20:07,北京时间) |
| 语言支持 | TypeScript、JavaScript、Python、Go、Rust、Java、Kotlin、Scala,外加 Vue、Svelte、Astro 文件 |
解决什么问题
读别人的代码,或者读 Agent 昨天替你写的代码,最费劲的是先搞清全貌。Floorplan 给的是一张分层的图:
- 逐级放大:从整个应用,双击进入某个模块、一组文件、单个文件和它的接口,每一层都显示「被谁用」和「用了谁」。
- 跨仓库连线:前端发的每个网页请求,会匹配到后端回答它的接口,前后端分在两个仓库也行。官方列出的接口框架包括 Express、Fastify、Hono、Next.js、Flask、FastAPI、Django、Gin、Axum、Spring 等。
- 从页面出发:挑一个你熟悉的页面,看它背后的模块、请求、服务端代码、数据和外部服务。
- 向地图提问:「退款怎么到用户卡上?」得到一段回答,加一张只含相关节点的小地图和分步讲解。
- Recent work:Agent 刚改过的卡片亮成绿色,附一句这次改动和你的要求有什么关系。
官方 README 还和 Archify、Understand Anything 做了对比:Floorplan 面向「用 AI 做应用、不读代码」的人,Archify 偏画给别人看的图,Understand Anything 偏逐函数研究大型代码库。
怎么用
安装(Claude Code,桌面版的 Code 页或命令行都行):
claude plugin marketplace add haydenschmitty/floorplan
claude plugin install floorplan@floorplan
Codex 的话,在应用里打开 Plugins → Add a marketplace,Source 填 haydenschmitty/floorplan 后安装;也可以在终端运行:
codex plugin marketplace add haydenschmitty/floorplan
codex plugin add floorplan@floorplan
装完要新开一个会话,插件才会加载。然后:
- 用 Agent 打开项目。前后端分在
web/和api/两个目录的,打开包含两者的上层文件夹。 - 输入「Make me a floorplan of this app.」;Claude Code 里也可以选
/floorplan:floorplan,Codex 里输入$floorplan。 - 过程中会请你放行 Floorplan 自己的
node …脚本,允许即可。小应用几分钟,大应用更久;超过约 150 个文件时,Claude Code 会拆给并行的助手。 - 地图自动打开,第一次会跑一段一分钟的「Start here」导览。
之后常用的几句话:
Update the floorplan.
Fix the important issues from the floorplan's Health check
Add a flow showing how a new user signs up
Rewrite the floorplan for developers
Export the floorplan so I can send it to the team
想手动开地图,运行 node floorplan/serve.mjs,在 http://127.0.0.1:4378 访问,提问栏可用;直接双击 floorplan/index.html 也能看,只是不能提问。没有代码、只有 PRD 的时候,把文档给 Agent 并说「Here's my PRD. Make me a floorplan of what we'd need to build.」,会得到一张虚线卡片的蓝图,并列出方案里还没定的问题。
装之前先看的几件事
- 它写了什么:只写项目里的
floorplan/文件夹,该文件夹自带 git 忽略;Claude Code 里你同意的话,还会在CLAUDE.local.md加一小段,让之后的会话知道地图在哪。不改你的代码、.gitignore和CLAUDE.md。 - 网络:地图服务只监听
127.0.0.1,接口要带只有地图页拿得到的令牌;地图页不从网上加载任何东西。唯一的外发请求是你主动在地图里填邮箱加入 Floorplan Cloud 等候名单。 - 代码会不会出本机:和平时用 Claude Code、Codex 一样,Agent 读文件通过你自己的账号发给 Anthropic 或 OpenAI;Floorplan 本身不发。提问栏用
claude -p(限读文件)或codex exec --sandbox read-only回答。 - 免询问的命令:Claude Code 里它预先放行一类命令,即
node运行自己固定列出的 8 个脚本,其他命令照常按你的权限设置询问。 - 核对安装副本:每个版本带
CHECKSUMS.txt,克隆对应标签后用node tools/checksums.mjs --check <安装目录>对比;仓库里有一个供应链测试,每次提交检查有没有新增钩子、依赖或外发请求。 - 起名不合心意:直接说「rename 'Main server' to 'Shop API' on the floorplan」,或改
floorplan/architecture.json,你的改动在更新时保留。
它的价值在“改完之后”:让 Agent 动手前后各看一眼地图,就知道这一轮到底碰了哪几块。
适合谁,不适合谁
适合:靠 Agent 做出应用、但自己没细读过代码的人;要带新人入门的小团队;想在 Agent 改完之后快速看清影响范围的人。
不适合 / 请改道:要给文档或分享会画一张精致流程图,用 Archify 这类画图工具更对口;要研究一个大型代码库的每个函数,可以看 Understand Anything。Health 检查官方明说是检查而不是审计,上线前的安全评审别拿它顶替。站内写过同样讲「让 Agent 读懂代码库」的 Graphify,Graphify 偏知识图谱和查询,Floorplan 偏给人看的交互地图,可以放在一起比较。
最后
挑一个你最近让 Agent 改过的项目,装上 Floorplan,对它说「Make me a floorplan of this app.」,先看 Health 面板里有没有你没留意的密钥或没加登录的接口。