入门指南¶

更喜欢看视频？演示视频 涵盖了安装 Floorplan 和浏览已完成的代码地图。

Floorplan 可在 Claude Code 和 Codex 中使用。制作和使用地图的方式在两者中相同；只有安装方式不同。本指南展示的是 Claude Code 的用法，Codex 中的 Floorplan 包含 Codex 的步骤。

你需要什么¶

• Claude Code（Claude 桌面应用中的 Code 选项卡，或终端中的 Claude Code CLI），或 Codex（应用或 CLI，已使用 ChatGPT 登录）。
• Node.js 18 或更高版本。 Floorplan 的脚本在其上运行。用 node --version 检查。
• 使用 Claude Code 时，建议安装 Claude Code CLI，即使你主要使用桌面应用。有了它，地图的 Ask 栏在回答问题时可以读取你的实际代码。Codex 无需额外操作：其应用已包含 Ask 栏所需的功能。

安装¶

在 Codex 中，打开 Plugins → Add a marketplace，输入 haydenschmitty/floorplan，然后安装 Floorplan。详细信息见 Codex 中的 Floorplan。

在 Claude Code 中，在任意终端运行一次以下命令：

claude plugin marketplace add haydenschmitty/floorplan
claude plugin install floorplan@floorplan

第一条命令将此仓库添加为插件源。第二条命令为你的所有项目安装 Floorplan。桌面应用和 CLI 共享同一设置，因此两者中都会显示。

之后开启一个新的会话。插件会在会话开始时加载。

在 Claude 桌面应用中，你也可以通过提示框旁的 + 按钮浏览插件（Add plugins，或 Plugins → Browse plugins）。它会列出你已添加的插件市场中的插件。

制作你的第一张地图¶

1. 打开你的项目。 在 Claude 桌面应用的 Code 选项卡中，在发送第一条消息之前，从提示框下方的行中选择项目文件夹。在 Codex 应用中，打开项目文件夹。在终端中，从项目文件夹运行 claude 或 codex。

如果你的应用分布在多个仓库中（例如 web/ 和 api/ 并排），请打开包含所有这些仓库的文件夹。Floorplan 会将它们一起映射，并连接它们之间的请求。

1. 提出请求：

为这个应用制作一份 floorplan。

在 Claude Code 中，你还可以从 / 菜单中选择 floorplan，或输入 /floorplan:floorplan。在 Codex 中，输入 $floorplan。

1. 让它工作。 过程如下：
2. 扫描会列出每个文件、导入、端点和 Web 请求。这只需几秒钟，不消耗 Token。
3. Claude 或 Codex 会阅读你的 README 文件、配置文件和入口点，然后确定应用的主要部分及各自的用途。
4. 它会为每个文件和端点编写一个通俗英文名称和一行描述。在 Claude Code 中，超过约 150 个文件的项目会由并行 helpers 拆分处理。
5. 地图会被构建并检查：连接、Health 问题和屏幕。

一个小型应用需要几分钟，大型应用则更久。系统可能会要求你允许它运行 Floorplan 的脚本（node …）；请允许。Codex 还会要求在其沙箱之外启动地图的服务器，这样地图才能持续运行，且其 Ask 栏才能访问 Codex。

1. 四处看看。 地图会自动打开，出现在应用的浏览器窗格或你的 Web 浏览器中。首次运行时，会有一分钟的 Start here 导览。回复会概括你的应用是如何组合在一起的，并指出 Health 检查发现的任何严重问题。

有关你可以在图上执行的所有操作，请参阅使用地图。

保持更新¶

在你或你的 AI 修改了代码之后：

更新 floorplan。

Floorplan 会重新扫描并与上次的地图进行比较。移动过的文件会保留描述，删除的文件会消失，只有新增的或用途发生变化的部分会被重写。已在浏览器中打开的地图会自动重新加载，刚刚更改过的卡片在 Recent work 下亮起绿色。

规划尚未构建的内容¶

以上内容都是关于 Floorplan 的主要工作：映射已存在的代码。它还有第二个用途，适用于还没有代码的情况：根据 PRD、规格说明或你想构建的内容的描述，绘制应用的蓝图。打开你打算在其中构建的文件夹（空文件夹也可以），分享文档，然后提出请求：

这是我的 PRD。请为我们需要构建的内容制作一份 floorplan。

你会得到一份蓝图：同样形式的地图，包含应用所需的每个部分、文件、端点和屏幕、它们如何连接，以及它们依赖的外部服务。其卡片带有虚线轮廓，以便你看出这是一份计划。回复会说明 Claude 或 Codex 选择的技术栈、它所做的假设，以及你的 PRD 中悬而未决的问题。

在地图上：

• Review 会列出计划仍需决定的事项，例如任何人都可以使用的端点或悬而未决的问题。Resolve on the map 可解决其中一项：如果是问题，你只需输入答案。
• 将 Ask 栏切换到 Change 来调整计划（“也规划一下退款”）。地图会重新绘制，并高亮显示更改的部分，Undo 可将其还原。
• 每个部分都有 Build this with Claude（或 Codex），这是一个现成的请求，只构建该部分。

一旦代码就位，让 Claude 或 Codex “把真实代码映射出来”，蓝图就会变成普通地图。其工作原理请参阅蓝图。

自行打开地图¶

地图是你项目中的一个文件夹。任选其一：

node floorplan/serve.mjs

会在 http://127.0.0.1:4378 提供服务，Ask 栏可用；或者双击 floorplan/index.html，除提问外一切功能正常。

当系统为你打开地图时，服务器会在后台运行，并在你关闭最后一个标签页两小时后自动停止。若要提前停止：

node floorplan/serve.mjs --stop

更新插件¶

Codex 用户请参阅更新或移除。

在 Claude Code 中，从 GitHub 安装的插件不会自动更新，除非你开启该功能。要获取最新版本：

claude plugin update floorplan@floorplan

或者开启自动更新：在 Claude Code 会话中运行 /plugin，打开 Marketplaces，然后选择 Enable auto-update。无论采用哪种方式，更新都会在下一个会话中生效。具体更改请参阅更新日志。

卸载¶

claude plugin uninstall floorplan@floorplan

在 Codex 中，参见更新或卸载。然后，从任何你使用过它的项目中删除 floorplan/ 文件夹（如果你用过 Claude Code，也请删除 CLAUDE.local.md 中的 Floorplan 部分）。