【免费下载链接】floorplan
See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.
🗺️ 还没写一行代码，系统架构图就已经画好了？这正是 Floorplan 的 Blueprint（蓝图） 能力：把一份 PRD 或需求描述交给 Claude 或 Codex，它就能生成一张可视化的系统架构地图——包含每一个规划中的文件、接口、页面和外部服务，以及它们之间的连接关系。本文带你完整走一遍 Floorplan Blueprint 从 PRD 到架构蓝图的实战流程。
什么是 Floorplan Blueprint？
先快速认识一下 Floorplan：它是一个开源的代码库可视化工具，能把你的项目画成一张"交互式、大白话的地图"，每个模块、文件和 HTTP 接口都有人类可读的名字和一句话描述。
而 Blueprint 是它的"反向用法"：
| 普通 Floorplan 地图 | Blueprint 蓝图 | |
|---|---|---|
| 输入 | 已经写好的代码 | 一份 PRD / 规格文档 / 需求描述 |
| 输出 | 代码结构地图 | 规划中的系统架构地图 |
| 卡片样式 | 实线边框 | 虚线边框 + Blueprint 标签 |
| 健康检查 | Health 问题列表 | 设计评审（Review） |
简单说：代码是扫描出来的，蓝图画是规划出来的。蓝图会替你回答"要做这个系统，到底需要哪些零件、它们怎么连、还有什么是 PRD 没想清楚的"。
从 PRD 到蓝图：4 步实战流程
整个流程由脚本（机械工作）和 AI（判断与表达）分工完成，完整说明见 docs/how-it-works.md。核心步骤如下：
第 1 步：准备 PRD，发起请求
打开你要建项目的文件夹（空目录也可以），把 PRD 交给 Claude Code 或 Codex：
Here's my PRD. Make me a floorplan of what we'd need to build.
如果 PRD 只在聊天里，Floorplan 会先把它存成 docs/prd.md 再引用它。只有当 PRD 在根本问题上含糊时（谁在用、Web 还是移动端、要不要登录、是否涉及钱），它才会问你 2–3 个问题，否则直接做决定并记录为"假设"。
第 2 步：AI 写出 plan.json（规划细节）
AI 会阅读 references/blueprint.md 和 references/schema.md，然后在项目根目录生成：
floorplan/plan.json：规划中的每一个文件和接口——每个页面调用哪些接口、每个部分用到哪些外部服务和数据、每个接口谁有权访问（public/signed-in/team/webhook/internal），以及 AI 的假设清单和 PRD 遗留的开放问题；floorplan/architecture.json：系统的模块划分、外部服务节点（Stripe、数据库、邮件服务等）、1–3 条核心业务流（flows）和一条新手导览（tour）。
一个经验值：小产品通常规划 15–60 个文件、10–40 个接口，规划粒度到"文件 + 接口"，而不是画几个模糊的大盒子。
第 3 步：plan.mjs 转换 + 构建地图
plan.mjs 会把 plan.json 转换成与真实代码扫描（scan.mjs）完全相同格式的扫描数据，后面的构建、页面视图、导览、问答全部照常工作：
node floorplan/scripts/plan.mjs <root>
node floorplan/scripts/build.mjs <root>
build.mjs 会校验 AI 写的一切并指名道姓地报出问题（"did you mean …"、未归属的文件、模糊的 glob），修到干净为止。完成后用 open.mjs 打开地图。
第 4 步：审阅蓝图
打开地图后你会看到：
- 虚线边框的卡片 + Blueprint 标签，一眼看出这是"规划"而非"现状"；
- Review（设计评审）：列出计划里还没想清楚的事——对所有人开放却能改数据的接口、没定访问权限的接口、每个开放问题（并指出它影响哪些部分）、没有任何东西连接的孤立文件；
- Build this with Claude / Codex：每个模块都有一键按钮，生成"只构建这个模块"的现成请求，规划确认后可以直接开工。
完整示例：遛狗预约应用 "Pawprint"
仓库里就有一个端到端示例，可以直接对照着看。
输入：tests/fixtures/blueprint/docs/prd.md——一份简短 PRD：主人浏览遛狗师并预约支付、遛狗师查看日程并标记完成、提前一晚邮件提醒、Stripe 收款。PRD 只留了一个开放问题："取消政策还没定"。
AI 的产出：
-
plan.json——21 个规划文件、11 个接口。亮点包括：
- 选定的技术栈：Next.js 网站（主人端 + 遛狗师端）、Node.js + Express 服务端、Postgres、Stripe、Postmark；
- 记录了两条假设：主人和遛狗师共用一套登录、遛狗师端是响应式网站而非原生 App；
- 登录接口标注了
publicBecause："登录必须在任何人登录前就能用；同一账号连续输错 5 次锁定 15 分钟"——设计评审就不会再追问"为什么登录是公开的"； - PRD 没定的取消政策被原样放进
questions，并指向受影响的接口POST /api/bookings/:id/cancel。
-
architecture.json——9 个模块（客户网站、遛狗师 App、主服务器、提醒任务、数据库、Stripe、Postmark…），外加一条"预约遛狗"的核心流：主人选时段付款 → 服务器锁定时段 → 调 Stripe 扣款 → Stripe 回调 webhook → 预约确认。
蓝图还能"边聊边改"：Change 模式
这是 Blueprint 最实用的一点：规划不是一次性的，可以在地图上直接迭代。
地图顶部的 Ask 栏有 Ask / Change 切换开关：
- Ask：基于
plan.json和 PRD 回答问题（此时还没有代码可读）； - Change：直接提修改需求，比如 "also plan out refunds"（把退款也规划进来）或 "drop the admin page"。
Change 的工作机制（由 tests/blueprint-change.test.mjs 完整覆盖）：
- AI 以只读身份返回完整的、更新后的
plan.json+architecture.json； - 地图服务器用
plan.mjs和build.mjs校验——如果检查不通过（比如新接口指向了不存在的文件、新文件不属于任何模块），问题会打回让 AI 修一次； - 通过后自动保存、重绘地图，新增/变更的卡片高亮显示，并支持一键 Undo 回滚；
- 设计评审里的每一条都有 Resolve on the map 按钮：对于开放问题，你只需要在 "My answer:" 后面填上答案，AI 就会把答案吸收进规划。
测试里那个经典的"加退款"变更：新增 api/src/routes/refunds.ts 文件和 POST /api/refunds 接口、让"My walks"页面调用它——三处改动全部高亮，还能撤销恢复原样。
代码写完之后：蓝图一键变真实地图
蓝图不是"一次性图纸"。当你照着 Build this with Claude / Codex 把代码逐步建起来后：
- 代码存在了，让它"map the real code now"，
refresh.mjs --from-code会把地图从plan.json切换为扫描真实代码，蓝图卡片从虚线变实线； - 原
plan.json保留在原处，随时可查当初是怎么规划的。
也就是说，Blueprint 覆盖的是"想清楚 → 画出来 → 建出来"的完整前半程，而普通 Floorplan 负责后半程的持续更新。
相关资料速查
| 内容 | 路径 |
|---|---|
| 蓝图功能说明（Skill 入口） | skills/floorplan/SKILL.md |
| Blueprint 规划指南 | skills/floorplan/references/blueprint.md |
| architecture.json 格式 | skills/floorplan/references/schema.md |
| plan.json 校验脚本 | skills/floorplan/scripts/plan.mjs |
| 新手指南（含蓝图章节） | docs/getting-started.md |
| 原理：蓝图如何生成与变更 | docs/how-it-works.md |
| 蓝图在地图上的交互 | docs/using-the-map.md |
| Pawprint 示例 PRD | tests/fixtures/blueprint/docs/prd.md |
| Pawprint 示例 plan / architecture | tests/fixtures/blueprint/floorplan/plan.json · architecture.json |
| Change 模式测试 | tests/blueprint-change.test.mjs |
💡 小提醒：
floorplan/目录自带.gitignore，地图文件不会被提交进 git——蓝图和地图都是项目里的"本地私人图纸"。
【免费下载链接】floorplan
See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
