GitHub 今日推荐｜floorplan：AI 读代码自动画交互式架构地图
一句话看懂
项目地址：github.com/haydenschmi...
floorplan 让 Claude 或 Codex 扫描代码库并生成可交互的架构地图，点击卡片查看文件、请求路径和近期修改。零依赖、Node 18+ 即可运行，内置健康检查发现五类 AI 生成代码的常见安全错误。
它解决什么问题
用 AI 写代码的开发者往往不读代码，直到出问题才回头找。传统架构图需要手动绘制，更新麻烦，很快过期。多仓库项目里前端调用后端端点时，手工追踪请求路径容易出错。
floorplan 用 AI 自动读取代码，生成交互式地图。地图按部分、文件、端点分层，点击卡片显示导入关系、HTTP 调用和最近修改原因。健康检查扫描五类常见安全配置错误：浏览器暴露密钥、Supabase 表无 RLS、Firebase 开放规则、可伪造 Stripe webhook、无认证端点。每次 AI 修改代码后更新地图，绿色高亮显示所有更改及理由。
核心概念速览
Floorplan 指代码库的可视化地图，显示部分（sections）、文件和端点。插件生成的交互式 HTML 文件就是 floorplan，可在浏览器中打开并点击探索。
Health check 指检查代码中常见安全配置错误的扫描脚本。插件运行时自动执行五类检查，识别密钥暴露、权限配置缺失等问题，并生成修复建议。检查不存储或显示密钥实际值，仅标记位置。
Blueprint 指尚未实现的系统计划图。从 PRD 或规格文档生成，在地图中用虚线标记预期架构。蓝图不是可执行代码，仅为架构预览。
Recent work 指最近修改的代码部分。地图中绿色高亮显示 AI 刚更改的卡片及原因，用于审查 AI 修改后的影响范围。
项目支持 12+ 编程语言和 20+ 框架，但主要针对 JavaScript，其他语言为 lighter support。地图服务器仅接受本机连接，生成的 floorplan 文件夹自动忽略 git 提交。
架构拆解
插件分为六个核心模块，按扫描、描述、解析、匹配、构建、展示的顺序工作。
extract.mjs 基于正则表达式提取各语言的导入、导出、路由和 HTTP 调用。针对不同语言编写独立的模式匹配逻辑。
resolve.mjs 解析导入说明符到文件系统路径或外部包名。处理相对路径、别名和 Node.js 模块解析规则。
routes.mjs 组合路由定义和挂载点，匹配前端调用与后端端点。处理嵌套路由和中间件，生成完整路径。
health.mjs 执行五类安全检查并生成修复建议。扫描代码中的密钥、权限配置和认证逻辑。
viewer.html 地图的前端交互界面主模板。渲染节点、边和层次结构，处理点击和展开逻辑。
扫描代码库文件时，scan.mjs 遍历文件并调用 extract.mjs 提取导入、路由、调用。describe.mjs 让 Claude 或 Codex 为每个文件生成纯英文描述。resolve.mjs 将导入说明符映射到实际文件。routes.mjs 连接前端调用与后端路由。build.mjs 生成节点、边和层次结构 JSON 并运行 health.mjs 安全检查。open.mjs 启动本地服务器并在浏览器中打开 viewer.html。
关键实现走读
extract.mjs 中的 extractCalls 函数从源码字面量提取 HTTP 调用和主机。
javascript
function extractCalls(src, at, { skip } = {}) {
const calls = [];
const hosts = [];
const lines = src.split('\n');
let offset = 0;
for (let i = 0; i < lines.length; i++) {
const line = flattenTemplates(lines[i]);
const lineStart = offset;
offset += lines[i].length + 1;
if (line.length > 500 || NAV_CONTEXT.test(line)) continue;
if (skip && skip.test(line)) continue;
const assigned = ASSIGN.exec(line)?.[1];
const use = assigned ? variableUse(lines, i, assigned) : null;
if (!HTTP_CONTEXT.test(line) && !use) continue;
const method = (METHOD_CALL.exec(line)?.[1] || METHOD_OPT.exec(line)?.[1] || use?.method || '').toUpperCase() || null;
for (const m of line.matchAll(STR_LITERAL)) {
const n = normalizeCallLiteral(m[2]);
if (!n) continue;
const lineNo = at(lineStart);
if (n.host && !IGNORED_HOST.test(n.host) &&!n.host.includes('${') && !n.host.includes('{')) hosts.push({ host: n.host, line: lineNo });
if (n.path && !n.host) calls.push({ path: n.path, method, line: lineNo });
}
}
return { calls, hosts };
}做了什么： 逐行扫描源码，用正则匹配字符串字面量中的 HTTP 路径和主机名。跳过过长行和导航上下文，提取变量赋值和使用位置，识别 HTTP 方法（GET、POST 等）。过滤忽略主机和模板变量，返回调用列表和主机列表。
为什么这样写： HTTP 调用通常写在字符串字面量中，通过正则匹配比解析 AST 更快且覆盖多种写法。跟踪变量赋值和使用位置能识别 const url = '/api/users'; fetch(url) 这种间接调用。跳过过长行和导航上下文减少误报，模板变量过滤避免动态生成的路径干扰匹配。
没有它会怎样： 无法匹配前端调用与后端端点，地图只显示文件间导入关系，丢失请求追踪能力。间接调用和嵌套在中间件中的路由不会被发现。
routes.mjs 中的 resolveRoutes 函数跨文件组合嵌套路由挂载。
javascript
export function resolveRoutes(files) {
const mountsTo = new Map();
for (const f of files) for (const mount of TEST_FILE.test(f.path) ? [] : f.mounts || []) {
const t = mountTarget(f, mount);
if (!t) continue;
if (!mountsTo.has(t.file)) mountsTo.set(t.file, []);
mountsTo.get(t.file).push({ from: f.path, v: t.v, prefix: mount.prefix, mw: mount.mw || [] });
}
const outerPrefixes = (file, v, seen = new Set()) => {
const ms = (mountsTo.get(file) || []).filter((m) => v == null || m.v === '*' || m.v === v);
if (!ms.length || seen.has(file)) return [''];
const next = new Set(seen).add(file);
const out = [];
for (const m of ms) for (const p of m.from === file ? [''] : outerPrefixes(m.from, null, next)) out.push(joinPath(p, m.prefix));
return [...new Set(out)];
};做了什么： 构建挂载关系映射表，记录每个文件被哪些文件以什么前缀挂载。递归查找外层前缀，处理嵌套挂载链，拼接完整路径。用 seen 集合防止循环引用，过滤测试文件。
为什么这样写： Express、Koa 等框架允许多层路由嵌套，app.use('/api', userRouter) 挂载后，userRouter.get('/profile') 的完整路径是 /api/profile。递归处理多层嵌套，去重避免重复路径。防止循环引用避免死循环，过滤测试文件减少干扰。
没有它会怎样： 嵌套路由只显示局部路径，前端调用 /api/users 无法匹配后端的 router.get('/users')。多仓库项目中跨仓库请求追踪失效，地图丢失核心价值。
动手上手
插件需要在 Claude Code 或 Codex 环境中安装使用。
从插件市场安装：
bash
claude plugin marketplace add haydenschmitty/floorplan
claude plugin install floorplan@floorplan在代码库根目录对 Claude 说：
kotlin
Make me a floorplan of this app.Claude 扫描代码后会在浏览器中打开地图。点击卡片查看文件细节，点击边查看导入或调用关系。健康检查结果显示在右侧面板，点击问题条目跳转到对应文件行号。
修改代码后更新地图：
sql
Update the floorplan.绿色高亮显示最近修改的文件和端点，Recent work 面板列出更改原因。
从 PRD 生成蓝图：
css
I want to build an app that does X. Show me a blueprint.Claude 生成虚线标记的计划图，显示预期架构。
应用场景
新成员加入项目时，打开地图从屏幕视图向下探索到文件和端点，快速了解代码组织和关键路径。地图质量取决于 AI 对代码的理解准确度，复杂业务逻辑可能需要人工补充说明。
AI 修改代码后审查影响范围，更新地图后 Recent work 面板高亮显示所有更改。需在 Claude Code 或 Codex 会话中使用，其他 IDE 或命令行工具不支持。
从 PRD 规划未实现系统，分享文档后请求蓝图，获得虚线标记的计划图。蓝图不是可执行代码，仅为架构预览，不能直接生成实现。
项目交付后快速生成架构图供文档或演示，地图导出为 HTML 文件可分享给团队。地图仅显示代码结构，不包含业务流程图或数据流图。
故障排查时定位特定业务流程（如 checkout）涉及的文件和调用链，点击边追踪请求路径。健康检查发现的五类问题不等同于完整安全审计，仅覆盖 AI 生成代码的常见错误。
独立分析
floorplan 适合用 AI 构建应用且不读代码的开发者。README 明确写道"For builders: understand the app you made, in your own words, without reading the code"，目标用户是依赖 AI 生成代码、希望快速把握全局的开发者。区别于 Archify 在于面向理解已有应用而非绘制演示图，对比表显示 Floorplan 回答"How does the app I built actually work"，Archify 回答"How do I show this clearly"。
与 Understand Anything 的区别在于粒度和场景。Understand Anything 生成函数级知识图谱，适合深入研究算法实现；Floorplan 聚焦文件和端点级地图，加跨仓库请求追踪，适合快速理解 Web 应用结构。
传统架构图工具需手动绘制，更新滞后。floorplan 由 AI 自动读取代码生成并保持更新，适合迭代频繁的项目。但生成的地图质量依赖 AI 对代码的理解准确度，复杂业务逻辑可能出现误报或漏报。
健康检查的五类问题覆盖 AI 生成代码的常见安全错误，但不等同于完整安全审计。检查不存储或显示密钥实际值，仅标记位置，适合快速发现配置错误，不能替代专业安全工具。
局限与风险
需 Claude 或 Codex API 访问权限，依赖外部 AI 服务。API 限额、网络中断或服务不可用时插件无法工作。
主要支持 JavaScript 项目，其他语言为 lighter support。Python、Go 等语言的导入解析和路由匹配可能不准确，需手动验证。
健康检查仅为检查非审计，Health 不存储或显示密钥实际值。五类问题覆盖常见配置错误，但无法发现逻辑漏洞、注入攻击或复杂权限绕过。
复杂多仓库布局可能需要额外配置。插件支持跨仓库请求追踪，但需在所有仓库中安装并手动指定关联关系。
地图质量取决于 AI 对代码的理解准确度。动态生成的路由、反射调用和复杂继承关系可能被遗漏或误判。生成的 floorplan 文件夹自动忽略 git 提交，团队成员需各自生成地图，无法共享统一版本。
结论卡片
floorplan 适合 AI 辅助编程的单体或少量关联仓库团队，需快速理解代码结构者。零依赖设计降低使用门槛，交互式地图和健康检查覆盖 AI 生成代码的常见问题。
不适合不使用 Claude/Codex、非 JavaScript 主栈、需完整安全审计的项目。其他语言支持有限，健康检查不能替代专业安全工具。
零依赖工具，适合 AI 时代快速架构可视化。当前版本 0.6.1，创建于 2026 年 10 月 27 日，Star 1716，当日新增 876。
项目地址：github.com/haydenschmi...
原文地址：tools.wflynn.cn/aitools/git...
关注公众号「YourTools」，每天推送 GitHub 趋势与开源工具速报：
