Floorplan 在 Codex 中的完整实践：插件安装、$floorplan 绘图与只读 Ask 问答-北京尧图网络

【免费下载链接】floorplanSee how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.项目地址https://gitcode.com/gh_mirrors/floorplan/floorplan点击查看免费下载本文以 Floorplan 的 Codex 指南为主线讲清楚三件事如何在 Codex 应用中完成安装、如何用$floorplan生成并更新代码地图、以及地图上的 Ask 栏是怎样通过codex exec在你自己的 ChatGPT 登录态下以只读沙箱回答问题的。读完后你能独立完成安装、按需切换推理引擎、定位 CLI 路径并清楚它与 Claude Code 版本的差异所在。同一个技能两套宿主Floorplan 在 Codex 中的工作方式与在 Claude Code 中完全一致同一份 skill、同一套脚本、同一张地图差别只在于宿主如何加载插件、以及 Ask 栏调用哪个 CLI。整个过程不需要配置任何 API Key使用的是你已经登录的 ChatGPT 账号。这一点在仓库结构里可以直接看出来Claude Code 的清单放在.claude-plugin/Codex 的清单放在.codex-plugin/两者version与description保持一致发布测试tests/release.test.mjs正是校验这种一致性而真正被两个宿主共用的技能定义只有一份位于 skills/floorplan/SKILL.md。Codex 侧的入口描述则由 skills/floorplan/agents/openai.yaml 提供它声明了展示名、一句话说明和默认提示词。前置条件Codex桌面应用或 CLI 均可需要已用 ChatGPT 账号登录。Node.js 18 或更高版本。Floorplan 的所有脚本都是零依赖的普通 Node.js 程序package.json中的engines字段即声明18见 package.json。用一条命令确认 Node 版本node --version与 Claude Code 相比Codex 侧不需要额外安装 CLI 才能让 Ask 栏工作——Codex 应用本身已经包含 Ask 栏所依赖的能力。只有在你想手动指定可执行文件、或在服务器等场景下单独启动地图服务时才需要关心codex命令本身是否在 PATH 上。安装应用内图形界面或命令行在 Codex 应用内安装无需终端打开Plugins选择Add a marketplace。Source填入haydenschmitty/floorplanGit ref留空点击Add marketplace。在列表中找到Floorplan点安装。新建一个会话插件在会话启动时加载。用 Codex CLI 安装codex plugin marketplace add haydenschmitty/floorplan codex plugin add floorplanfloorplan第一条命令把这个仓库注册为插件市场第二条把floorplanfloorplan安装到你的环境。应用与 CLI 共享插件目录所以在其中一侧安装另一侧也能直接使用。从仓库视角看marketplace add读取的是 .agents/plugins/marketplace.json其中把本仓库声明为一个单插件市场插件源指向./并设置了installed/authentication策略而plugin add读取的是 .codex-plugin/plugin.json它声明skills: ./skills/并带有requires_local_executor: true——这正是 Floorplan 需要在你的机器上执行node脚本的原因。该文件里还有interface.defaultPrompt三个默认提示词Draw a floorplan of this codebase、Update the floorplan with what we just changed、Show me how the frontend talks to the backend因此你在 Codex 的输入框里可以直接看到推荐话术。画出第一张地图在 Codex 中打开你的项目文件夹然后用自然语言提问即可Draw a floorplan of this codebase想按名字调用技能输入$floorplan。之后的流程与 Claude Code 完全相同Codex 扫描代码为每个部分、文件和 Web 请求写名字与说明构建地图并打开它。之后说update the floorplan它只重新读取发生变化的部分。Codex 是如何被识别出来的地图需要记住是谁画的这样 Ask 栏和Fix with …提示词才能叫对名字。识别逻辑在 skills/floorplan/scripts/lib/agent.mjsconst DETECT { claude: () false, // the default codex: (env) !!(env.CODEX_THREAD_ID || env.CODEX_SESSION_ID), };优先级是--agent name参数 →FLOORPLAN_AGENT环境变量 → 环境变量探测 → 默认claude。传入无法识别的值时会被忽略并回落到探测结果这一行为在 tests/agents.test.mjs 中有明确断言例如detectAgent({ agent: gpt }, { CODEX_THREAD_ID: abc })仍返回codex。识别结果写入graph.json的meta.agent构建日志会打印AGENT Codex: questions on the map run through Codex见 skills/floorplan/scripts/build.mjs。打开的地图页面随后根据它决定按钮文案skills/floorplan/assets/viewer.html 中当服务器引擎或地图构建者被判定为 codex 时界面使用{ id: codex, name: Codex, app: Codex }登录提示也改成打开 Codex 应用或运行codex login后重试。沙箱与地图服务器Codex 打开地图时会要求把地图的服务器放到沙箱之外运行。原因有两层服务必须在命令结束后继续存活而 Ask 栏又需要访问网络才能连到 Codex。如果你不想授权可以在项目目录里自行启动node floorplan/serve.mjs服务只监听127.0.0.1默认端口 4378并在启动后打印实际 URL。它还会校验请求的Host头必须是自己机器的名字并给每个会话生成随机 token——即使网页发起 DNS 重绑定把域名指向127.0.0.1也拿不到/api/*的访问权实现见 skills/floorplan/assets/serve.mjs。Ask 栏在你自己的机器上运行 Codex地图上的 Ask 栏会在你本机运行codex exec进入 Codex 的read-only沙箱工作目录是你的项目文件夹使用的是你的 ChatGPT 登录态。它阅读地图和源码来作答且无法修改任何文件。这些运行不会写入你的 Codex 历史追问时服务会把最近几轮问答一起带上。这些描述在源码里逐条可以对应上。codexRunskills/floorplan/assets/serve.mjs构造的参数是const args [...cli.args, exec, --json, --sandbox, read-only, --skip-git-repo-check, --ephemeral, --output-schema, mode.file, -C, root]; if (model) args.push(--model, model); args.push(-);逐项解释参数作用带来的实际约束exec非交互式执行一次请求一次提问一次进程--json输出 JSONL 事件流服务按行解析转成进度与最终答案--sandbox read-only只读沙箱确认是 CLI 层面强制的只读而非提示词约束--skip-git-repo-check跳过 git 仓库校验非 git 目录也能用--ephemeral不落盘为历史会话不污染 Codex 历史记录--output-schema file用文件指定输出结构Codex 从文件读取 schema-C root指定工作目录固定为地图所在的项目根-从标准输入读提示词请求内容经 stdin 送入结构化输出为什么要改写一次--output-schema指向.cache/下的 JSON 文件由load()在启动与每次重建地图时写出。关键在于OpenAI 的结构化输出要求对象里每个属性都在required中且不允许额外属性。因此serve.mjs在写盘前会递归地收紧 schemafunction strict(s) { if (s?.type object s.properties) return { ...s, properties: Object.fromEntries(Object.entries(s.properties).map(([k, v]) [k, strict(v)])), required: Object.keys(s.properties), additionalProperties: false }; if (s?.type array) return { ...s, items: strict(s.items) }; return s; }可选列表在这里一律变成必填但可以为空——这正是可选的列表就返回空数组的实际含义。测试 tests/ask.test.mjs 会遍历整份 schema断言每个 object 都满足additionalProperties: false且required与properties的键集合一致并确认steps、followups都在必填之列。也因为 Codex 是从文件读 schema的引擎ENGINES.codex里带有schemaFile: true标记skills/floorplan/assets/serve.mjs写盘逻辑据此只在 Codex 引擎下执行。追问如何保持上下文由于--ephemeral让每次运行彼此独立服务用一个内存表convos维护对话每轮结束后保存{ q, a }其中问题截断到 500 字符、答案截断到 1500 字符只保留最近 4 轮convos.set(session, [...turns, { q: question.slice(0, 500), a: String(a.answer || ).slice(0, 1500) }].slice(-4));下一轮把这段内容以Earlier in this conversation:的形式拼进提示词。测试同时验证了两点首轮提示词里不含该段第二轮才出现传入一个不认识的 session 会开启全新对话而不是复用旧上下文。会话 ID 是 16 位十六进制随机串。引擎选择与 CLI 定位服务端使用哪一个引擎遵循如下顺序skills/floorplan/assets/serve.mjs--engine claude|codex或环境变量FLOORPLAN_ENGINE否则用构建这张地图的那个 agent读graph.json的meta.agent都不匹配则默认claude随后按顺序尝试定位 CLI第一个找到的胜出——但显式指定--engine时不再回退找不到就直接报cli_missing。在地图由 Claude 构建、但机器上只装了 Codex 的场景里回退机制让 Ask 栏依然可用而想强制走某个引擎时显式指定就是硬性约束。强制指定 Codexnode floorplan/serve.mjs --engine codexCLI 的查找范围codex在 PATH 上which/where以及在 Windows 上 Codex 桌面应用自带的 CLI——它位于版本化目录%LOCALAPPDATA%\OpenAI\Codex\bin\version\codex.exe下代码会按修改时间倒序取最新的一个codexApp()。如果你的 Codex 装在别处node floorplan/serve.mjs --codex /path/to/codex模型方面--model name或环境变量FLOORPLAN_MODEL会决定调用哪个模型不指定时由你的 Codex 设置决定。一个容易被忽略的细节子进程环境清理服务器本身可能是从 Codex 会话内部启动的。如果原样把环境变量传给子进程CLI 会误以为自己被嵌套在另一个会话里。服务因此在派生子进程前会剥掉一批变量skills/floorplan/assets/serve.mjsfor (const k of Object.keys(env)) if (/^CLAUDE_?CODE_(SESSION|ENTRYPOINT|CHILD|MESSAGING|HOST|SDK)|^CLAUDECODE$|^CODEX_(THREAD_ID|SESSION_ID|TOOL_CALL_ID|CI$|SANDBOX)/.test(k)) delete env[k];注意CODEX_THREAD_ID、CODEX_SESSION_ID、CODEX_SANDBOX都在清理列表中——识别地图作者用它们回答问题时不带它们。出错时用户看到什么failCode()会把错误归类为三种登录相关not logged in、401、sign in等→not_logged_in额度相关429、rate limit→rate_limited其余 →cli_error。界面据此给出对应提示Codex 的登录提示是打开 Codex 应用或运行codex login。测试用一个提示词里含SIGNED-OUT的假 CLI 复现了未登录路径断言事件类型为failure且 code 为not_logged_in并确认此时不会产出answer。和 Claude Code 的三处差异一、不写任何笔记文件在 Claude Code 中Floorplan 会在CLAUDE.local.md里维护一小段带标记的说明指向地图与query.mjs的几个查询命令。这段逻辑在 skills/floorplan/scripts/lib/claudemd.mjs 中块由!-- floorplan:start --与!-- floorplan:end --包裹只重写自己的块其余内容不动并把该文件加入仓库本地的.git/info/exclude而非.gitignore因此不会影响已跟踪文件。Codex 没有等价的个人、不提交的笔记文件——AGENTS.md是与团队共享的。所以 Codex 下 Floorplan 不碰你的项目笔记。测试对此有双重断言用--agent codex构建后CLAUDE.local.md和AGENTS.md都不存在而用--agent claude构建后CLAUDE.local.md中能看到/floorplan/query.mjs的引用。二、没有 Claude app 这条发布路径把地图发布到 Claude app 是 Claude 的特性。在 Codex 中地图就是在你的浏览器里打开由你本机的服务提供。对应的离线替代方案是导出node floorplan/serve.mjs --export [file] [--include flows,notes,recent,health]默认只带flows与notes导出的单文件 HTML 会去掉 Ask 栏、本机路径与 git remote 信息见 skills/floorplan/assets/serve.mjs。这在你需要把地图发给别人看时最实用。三、修复提示词改成对着 Codex 说Health 面板里现成的修复提示词在 Codex 版本中是给你粘贴进 Codex 的蓝图上的Build this with Codex同理。工具栏的Change开关同样让 Codex 在只读沙箱中运行Codex 返回更新后的计划由地图服务器负责保存。这条链路的实现值得展开因为它展示了只读的 agent 也能改计划是怎么做到的。changePlan()skills/floorplan/assets/serve.mjs先把请求交给runAgent再把返回的完整plan.json与architecture.json交给applyChange()先做快照保留最近 20 份用于 Undo写盘然后用技能自带的脚本校验并重绘——plan.mjsbuild.mjs --check最后build.mjs --no-claude-md。若检查不通过例如有规划文件落在任何节点的 glob 之外快照会被回滚并把问题回喂给模型重试一次。整个过程有并发保护changing为真时再次提交会返回busy。只有声明了structured: true的引擎才会出现 Change 开关因为整条链路依赖 CLI 严格遵守 schema。更新、移除与本地副本更新在应用内打开Plugins找到 Floorplan 市场选择Upgrade或在终端执行codex plugin marketplace upgrade floorplan codex plugin add floorplanfloorplan移除codex plugin remove floorplanfloorplan codex plugin marketplace remove floorplan地图本身不受影响——它们留在各项目的floorplan/目录里直到你主动删除。试用本地工作副本把 Codex 指向本地克隆而不是远端仓库codex plugin marketplace add /path/to/floorplan codex plugin add floorplanfloorplan这里有一个与 Claude Code 的重要差异当添加本地插件时Codex 会把插件复制进自己的缓存Claude Code 则是直接从文件夹运行。这意味着你改完插件后必须重新执行codex plugin add floorplanfloorplan并开启新会话改动才会生效。安装后的缓存路径形如~/.codex/plugins/cache/floorplan/floorplan/version见 docs/is-it-safe.md可用codex plugin list查看当前版本。如果你在开发 Floorplan 本身--agent claude|codex在build.mjs上与--engine claude|codex在serve.mjs上可以让你从任意环境模拟任一宿主的产物这一点在 docs/development.md 中有说明。命令速查目的命令添加插件市场codex plugin marketplace add haydenschmitty/floorplan安装插件codex plugin add floorplanfloorplan升级市场codex plugin marketplace upgrade floorplan移除插件codex plugin remove floorplanfloorplan移除市场codex plugin marketplace remove floorplan自行启动地图服务node floorplan/serve.mjs强制走 Codex 作答node floorplan/serve.mjs --engine codex指定 Codex 可执行文件node floorplan/serve.mjs --codex /path/to/codex指定模型node floorplan/serve.mjs --model name停止后台服务node floorplan/serve.mjs --stop导出可分享副本node floorplan/serve.mjs --export [file]查看安装情况codex plugin listserve.mjs还接受--port默认 4378端口被占用时会自动往后试到 20、--no-open不自动打开浏览器与--idle-exit 分钟最后一个标签页关闭后多久退出后台启动时open.mjs用的是 120 分钟。常见问题定位Ask 栏提示需要 Codex服务在 PATH 中找不到codex且Windows 上也没找到桌面应用自带的 CLI。安装 Codex CLI或用--codex /path/to/codex指定路径。提示未登录打开 Codex 应用或在终端运行codex login后用 ChatGPT 账号登录然后重新提问。地图没打开或 Ask 在 Codex 打开地图后失效Codex 在沙箱中执行命令而地图服务需要持续运行并访问网络。在 Codex 询问时允许服务在沙箱外运行或自己在项目目录里执行node floorplan/serve.mjs。node不被识别安装 Node.js 18然后重启会话让 Codex 重新读取 PATH。Change 开关不出现它只出现在蓝图从 PRD 规划出来的地图上且必须通过node floorplan/serve.mjs打开、并且可用的引擎支持结构化输出。真实代码的地图没有 Change——先让 Codex 改代码再更新地图。更多排障条目见 docs/troubleshooting.md安全性说明与可自行校验的安装指纹见 docs/is-it-safe.md地图上每个按钮与面板的用法见 docs/using-the-map.md地图是如何从扫描到渲染的见 docs/how-it-works.md。赞分享【免费下载链接】floorplanSee how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.项目地址https://gitcode.com/gh_mirrors/floorplan/floorplan点击查看免费下载相关推荐Floorplan用 Claude Code 或 Codex 为代码库生成可交互的「平面图」——从安装到源码级的完整指南Floorplan用 Claude Code 或 Codex 为代码库生成可交互的「平面图」——从安装到源码级的完整指南导读 Floorplan 是一个零Floorplan 技能实战用 architecture.json 与描述文件为代码库绘制可交互地图Floorplan 技能实战用 architecture.json 与描述文件为代码库绘制可交互地图 Floorplan 是一个面向 Claude Codenext-ai-draw-io 内置 Floorplan 户型家具图元库45 种 mxgraph 图形在 AI 绘图中的接入与使用next ai draw io 内置 Floorplan 户型家具图元库45 种 mxgraph 图形在 AI 绘图中的接入与使用本指南以 floorpla人工智能AI 应用MCP 服务前端后端桌面应用上一篇如何用Nova3D搭建机器人训练环境从文本提示词到仿真农场采摘的完整实战下一篇Monid快速上手教程5分钟让你的AI Agent接上网页搜索与数据工具从Deno环境到真实调用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Floorplan 在 Codex 中的完整实践：插件安装、$floorplan 绘图与只读 Ask 问答

相关推荐

Proton-GE 实战：非Steam游戏在Lutris上跑起来的3种接入方式

USB2.0 电路设计核心关键点（源自 USB2.0 官方规范文档）

Scala Array操作：从定长数组到ArrayBuffer的完整指南

更多资讯

手写LR(1)编译器：从DFA到三地址码的可调试实现

无线传感器网络路由协议对比：LEACH、LEACH-C与TS-I-LEACH

Docker容器化CPLEX：Java求解器环境部署与避坑指南

Ventoy启动主题定制：从grub2配置到多镜像菜单优化

社交媒体成瘾机制与合规设计解析

锂电池基础科学：从理论能量密度到界面与离子输运

今日更新

PLFM_RADAR：从被动告警到主动感知的微服务健康监控系统

SPI隔离设计实战：MAX14431BAEE+与STM32F407工业级应用

数字隔离器如何根治SPI通信地环路干扰：MAX14431与TM4C129实战

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？