故障排除

Ask 栏提示需要 Claude Code CLI¶

地图已打开，但无法提问。你可以：

• 安装 Claude Code CLI，登录，然后让 Claude 更新 floorplan 或运行 node floorplan/serve.mjs；
• 或在 Claude 应用中打开地图：让 Claude“将我的 floorplan 发布到 Claude 应用”。那里的回答只来自地图。

CLI 已安装但找不到¶

serve.mjs 会查找 PATH 和 ~/.local/bin 中的 claude。如果它位于其他位置：

node floorplan/serve.mjs --claude /path/to/claude

Codex：Ask 栏提示需要 Codex¶

地图的服务器会在 PATH 中查找 codex，在 Windows 上还会查找 Codex 桌面应用附带的 CLI。安装 Codex CLI，或让服务器指向你的版本：

node floorplan/serve.mjs --codex /path/to/codex

如果提示 Codex 未登录，请打开 Codex 应用（或运行 codex login）并用 ChatGPT 登录。更多内容见 Codex 中的 Floorplan。

Codex：地图未打开，或 Codex 打开后 Ask 停止工作¶

Codex 在沙盒中运行命令，而地图的服务器需要持续运行并访问网络。当 Codex 询问时，允许服务器在沙盒外运行，或在项目文件夹中自行运行 node floorplan/serve.mjs。

无法识别 node¶

安装 Node.js 18 或更高版本，然后启动新会话，以便 Claude Code 或 Codex 识别它。

Claude 或 Codex 总是要求运行 node 脚本¶

在 Claude Code 中，Floorplan 运行时会对自己的脚本预先授权，但在某些配置下仍可能会询问。请选择允许该项目始终运行这些脚本的选项。Codex 会根据你的审批设置来询问；允许该项目运行 Floorplan 的 node 脚本后，就不会再出现提示。

技能未显示¶

插件会在会话启动时加载，因此安装后请新建一个会话。检查它是否已安装并启用：

claude plugin list

类似“make me a floorplan”的普通请求无需斜杠命令即可使用。如果你确实想用斜杠命令，它是 /floorplan:floorplan。

在 Codex 中，查看应用中的 Plugins，或运行 codex plugin list，安装后开始新聊天。若要按名称调用，请输入 $floorplan。

地图看起来已过时¶

让 Claude 或 Codex“更新 floorplan”。如果标签页已打开，它会在更新完成后自动重新加载。

地图空白，或卡在“Laying out”¶

0.1.3 版之前创建的地图会从互联网加载其布局引擎，因此请检查网络连接或任何内容拦截器，或让 Claude“update the floorplan”。较新的地图已内置所有内容，可离线工作。

Ask 栏没有 Change 开关¶

Change 只出现在通过其服务器（node floorplan/serve.mjs）打开、且具备 Claude Code CLI 或 Codex 的 blueprint 中。真实代码的地图没有该开关：请让 Claude Code 或 Codex 更改代码，然后更新 floorplan。

对 blueprint 的更改失败，或者我不喜欢这个更改¶

如果更新后的计划在第二次尝试后仍未通过 Floorplan 的检查，则不会保存任何内容，地图保持原样；尝试更具体地说明请求。如果更改已生效但不是你想要的结果，请在其摘要中按 Undo，或请求再次更改。以前的版本保存在 floorplan/.cache/history/ 中。

缺少连接¶

Floorplan 通过阅读代码来找出大多数 Web 请求和导入，但并非全部能发现，例如只存在于设置中的地址请求。让 Claude 将缺失的连接添加到 floorplan；它会记录在 architecture.json 中，并会在每次更新后保留。

文件位于错误分区，或位于“Unassigned”下¶

让 Claude 移动它，或编辑 floorplan/architecture.json 中的 paths 模式，然后请求更新。

“floorplan/ 已存在于此且不是地图”¶

你的项目有自己的名为 floorplan 的文件夹，Floorplan 不会写入其中。请重命名你的文件夹，或者让 Claude 在其他位置构建地图；扫描和构建脚本支持 --out <folder>。

git status 显示 floorplan/ 下的文件¶

这些文件是在 Floorplan 开始忽略该文件夹之前提交的。取消跟踪它们，同时将文件保留在磁盘上：

git rm -r --cached floorplan

端口 4378 已被占用¶

无需任何操作。服务器会移到下一个可用端口，它打印的 URL 或 Claude 给你的 URL 就是正确的。

停止后台服务器¶

node floorplan/serve.mjs --stop

它也会在最后一个标签页关闭两小时后自行停止。

仍然卡住？¶

打开 issue，说明你询问的内容、发生的情况、你使用的是 Claude Code 还是 Codex，以及它显示的输出。请省略代码中任何私密内容。