开发 Floorplan¶

仓库布局¶

.claude-plugin/
  plugin.json          the plugin: name, version, author
  marketplace.json     this repo as its own one-plugin marketplace
  icon.png
.codex-plugin/
  plugin.json          the same plugin for Codex (same skill, same version)
  icon.png
.agents/plugins/
  marketplace.json     this repo as a Codex marketplace
skills/floorplan/
  SKILL.md             the workflow Claude and Codex follow
  agents/openai.yaml   how Codex lists the skill
  references/          formats and style guides Claude reads while working
    schema.md                architecture.json and recent-work.json
    choosing-boundaries.md   how to carve a codebase into a good map
    writing-descriptions.md  plain-language names and descriptions
    blueprint.md             plan.json, for a map planned from a PRD
  scripts/             Node.js, no dependencies; Claude runs these
    status.mjs     is there a map, and how stale is it (runs when the skill loads)
    scan.mjs       repos, files, imports, endpoints, requests → .cache/scan.json
    plan.mjs       a blueprint's plan.json → the same .cache/scan.json
    build.mjs      validate, assign files, connect, Health, screens → graph.json + index.html
    describe.mjs   worksheets for Claude to name and describe files and endpoints
    refresh.mjs    incremental update: re-scan, carry over, flag changes, rebuild
    recent.mjs     facts for marking recent work
    open.mjs       start or reuse the map's server, and open the browser
    lib/           extraction, import resolution, route matching, Health, screens, which agent is running, helpers
  assets/
    viewer.html    the map (template the build fills in)
    ui/            viewer extensions: Theme button, blueprints, glossary, Health, recent work, screens, tour, waitlist card
    graph-query.js shared map lookups (viewer, query.mjs, Ask instructions)
    serve.mjs      copied into each project's floorplan/ folder; answers through Claude Code or Codex
    query-cli.mjs  becomes floorplan/query.mjs
    logo.png, favicon.png
    vendor/        bundled layout engine (elkjs) and fonts, with their licenses
tests/                 regression tests and the sample projects they map
tools/checksums.mjs    writes CHECKSUMS.txt for a release, and checks an installed copy against it
CHECKSUMS.txt          SHA-256 of every file the plugin runs from, as of the last release
docs/                  these guides

尝试你的工作副本¶

从你的本地文件夹安装，而不是 GitHub：

claude plugin marketplace add /path/to/floorplan
claude plugin install floorplan@floorplan

从本地文件夹安装的插件会直接运行，因此编辑会在下一个会话中生效，无需更新步骤。

要在 Codex 中试用，请参阅 尝试工作副本。Codex 在你添加本地插件时会复制一份，因此每次修改后需要重新运行 codex plugin add floorplan@floorplan。在 build.mjs 上使用 --agent claude|codex（或 FLOORPLAN_AGENT），在 serve.mjs 上使用 --engine claude|codex，你可以从任何地方试用任一智能体的地图。

这些脚本也可以独立运行，这是开发它们最快的方式：

node skills/floorplan/scripts/scan.mjs /path/to/project
node skills/floorplan/scripts/build.mjs /path/to/project
node skills/floorplan/scripts/open.mjs /path/to/project

build.mjs 需要项目中的 floorplan/architecture.json，所以先运行一次该技能，或手动编写一个小文件（schema）。

测试¶

npm test

测试使用 Node 内置的测试运行器，因此无需安装任何东西（npm test 等同于 node --test）。GitHub 会在每次推送和拉取请求时，在 Linux 和 Windows 上使用 Node 18、20 和 22 运行它们，并在 macOS 上每周和按需运行（Actions → macOS → Run workflow），因为其 macOS 机器通常都很忙。

示例项目由 helpers.mjs（shopApp()）写入临时文件夹，或从 tests/fixtures/ 复制。任何看起来像机密的内容都在运行时组装，因此提交中永远不会有看起来真实的密钥。

当你修复 Floorplan 检测中的错误时，添加一个展示该问题的示例，并确认在没有你的修复时测试会失败。

扩展查看器¶

skills/floorplan/assets/ui/ 中的文件会按名称顺序内联到每个地图中。它们仅通过 window.Floorplan 与查看器通信，后者提供：

• 图和查找；
• 导航（go、open、reveal、showBoard、playFlow）；
• addHeaderButton 和 addPanelSection('overview' | 'item', fn)；
• modal、toast、store；
• 事件（on('ready' | 'render' | 'panel' | 'technical')）；
• exported，在导出的副本中设置：其中任何需要 Claude、Codex 或地图服务器的内容都应省略。

20-health.js 和 25-recent.js 是不错的示例。

添加智能体¶

有两个列表，一个智能体可以只出现在其中一个，也可以同时出现在两个：

• 构建地图的智能体，位于 scripts/lib/agent.mjs：在 DETECT 中添加一个条目，通过它为每条命令设置的变量来识别它。地图会记录它，因此地图的提示词会指出正确的智能体。
• 回答问题的智能体，位于 assets/serve.mjs：在 ENGINES 中添加一个条目，包含其名称、获取方式、find（其 CLI 所在位置，以及 --<name> <path> 覆盖参数）和 run（参数以及如何将其输出解析为进度和答案）。

引擎必须以 CLI 强制执行的方式保持只读，而不仅仅是因为提示词要求；如果无法做到，请在文档中明确说明。仅当 CLI 能按 schema 给出答案时才设置 structured: true，因为从地图修改蓝图依赖于此；没有它，地图不提供变更功能。绝不要从页面或已保存的设置中获取要运行的命令。向 tests/fixtures/fake-cli/ 添加一个替身 CLI，并添加类似 ask.test.mjs 的测试。

指南¶

• 无依赖。 脚本必须能在任何支持 Node 18+ 的环境中运行，无需安装任何东西。
• 通俗语言优先。 地图向人们展示的任何内容都应让应用的所有者（而不仅仅是其工程师）能看懂。
• 绝不存储或打印机密值。 Health 发现项会记录机密所在位置和脱敏提示，绝不记录机密本身。
• 保持示例通用。 代码注释、文档和提示词不得描述任何真实的私有项目。

维护¶

分支与提交¶

• main 始终是可发布的。每个更改都通过自己的分支到达它，并带有合并提交（git merge --no-ff），以便每次更改在历史中都能作为一个整体阅读。
• 按分支的用途命名，有 issue 号时加上 issue 号：
• fix/4-fastapi-annotated-guards
• feat/codex-support
• docs/…、chore/…

使用 GitHub 的 创建分支 按钮从 issue 创建的分支（2-reaching-outside-repo）也没问题。 - 提交信息以祈使语气的简短摘要开头（例如“Bundle the layout engine”），正文说明原因。 - 当提交或合并信息中包含 Fixes #N 时，该提交到达 main 后会自动关闭对应 issue。 - Refs #N 用于链接但不关闭。 - 贡献者的拉取请求保留其提交和作者身份。 使用合并提交（“Merge pull request #N from user/branch”）进行合并，并通过保留两条条目来解决 CHANGELOG.md 冲突。 - 合并后删除分支。

版本与变更日志¶

• 版本遵循语义化版本控制。在 1.0 之前：
• 补丁版本（0.1.x）用于修复和小改进；
• 次要版本（0.x.0）用于新功能，或任何改变人们安装或运行方式的内容。
• 只有当版本变化时用户才会收到更新，所以请及时发布修复，而不要把它们留在 main 上。
• 用户会注意到的每项更改，都在 CHANGELOG.md 顶部的 ## Unreleased 下添加一行：
• 使用通俗语言；
• 注明报告或修复者，例如“Reported by @name in #1, fixed by @name in #3”。

发布¶

1. 在最新的 main 上运行测试并检查清单，包括官方插件目录的要求：

   npm test
   claude plugin validate . --profile directory
   

2. 提升 .claude-plugin/plugin.json 和 .codex-plugin/plugin.json 中的 version，以及 README.md 中的版本徽章。
3. 将 CHANGELOG.md 中的 ## Unreleased 重命名为 ## X.Y.Z (YYYY-MM-DD)。
4. 在版本升级后写入发布的指纹：

   node tools/checksums.mjs
   

5. 以 Floorplan X.Y.Z: <one-line headline> 提交并推送 main。
6. 打标签并推送标签。这还会检查 plugin.json 与市场条目是否一致：

   claude plugin tag . -m "Floorplan %s" --push
   

7. 在 GitHub 上，从标签（floorplan--vX.Y.Z）发布一个版本，标题为 Floorplan X.Y.Z，并将该版本的变更日志部分作为其说明。
8. 回复该发布修复的每个 issue 和拉取请求：说明更改内容、版本以及如何获取（claude plugin update floorplan@floorplan）。

问题与拉取请求¶

• 在几天内回复新 issue，即使只是说您已看到。
• 为每个 issue 添加标签（bug、enhancement、question）。
• 接手时将自己指派给该 issue。
• 询问问题的具体形态，绝不要索取私有代码、机密或私有地图的截图。
• 感谢贡献者，并在变更日志和发布说明中为他们署名。
• 关闭 issue 时，在评论中注明包含该修复的发布版本。
• 安全报告通过 SECURITY.md 私下提交。在修复发布之前，不要在公开 issue 中讨论。