fskulimo/scaffld

# Scaffld [](https://github.com/fskulimo/scaffld/actions/workflows/ci.yml) [](LICENSE) **了解数据如何在任何代码库中流转。** 粘贴一个 GitHub URL，Scaffld 将克隆代码仓库，追踪数据在其中如何移动（从何处进入、经历了什么转换、最终去向何处），并绘制出一幅可供探索和导出的交互式架构图。 每个节点都携带了代码中真实的模块或类名。 它与众不同的两点在于： - **图表是确定性的。** 它是根据代码的 AST 计算出来的，而不是由模型生成的。每次针对同一个 commit 都会产生完全相同的图表。无需任何账号或 API key 即可获得完整的图表。 - **专为与 Claude 配合而设计。** 连接你自己的 Claude，面板上的每个标签和描述都会被重写为通俗易懂的英文。这是推荐的配置方式。请参阅[连接你的 Claude](#connect-your-claude)。

## 安装与运行 **一条命令**（发布到 npm 后即可使用），无需克隆，无需配置： ``` npx @fskulimo/scaffld # open the app in your browser npx @fskulimo/scaffld mwaskom/seaborn # open and analyze a repo straight away ``` **从源码构建**（当前可用）： ``` git clone https://github.com/fskulimo/scaffld.git cd scaffld npm install npm start # builds once, serves the app, opens your browser # 或者直接指定一个 repo：npm start psf/requests ``` Scaffld 运行在一个本地端口上（默认为 `8799`，可通过 `--port` 修改）。它会自动打开你的浏览器，并可通过 Ctrl+C 停止运行。过往的分析记录会被缓存在 `~/.scaffld/` 目录下。 如果你已经安装并登录了 [Claude Code](https://www.anthropic.com/claude-code)，Scaffld 会自动检测到它，并使用你的 Claude 来生成标签。即使没有它，你依然可以获得完整的确定性图表。 ## 工作原理 ``` paste github URL │ ▼ ┌─ server/analyze · deterministic ───────────────────────────────┐ │ fetch.ts shallow git clone (public + private via gh auth) │ │ scan.ts walk source → tree-sitter AST (py/js/ts/java/go/cpp)│ │ kinds.ts imports → role signals (db/cache/queue/api/storage) │ │ flow.ts ⇒ a complete GraphData: real names, files, edges │ └───────────────────────────────┬────────────────────────────────┘ │ readability pass (auto, uses your Claude) ▼ ┌─ server/ai · your own Claude ───────────────────────────────────┐ │ enrich.ts rewrites node/edge *labels & descriptions* only, │ │ never the nodes or edges. Provider unreachable, or │ │ enrichment off? ⇒ the deterministic labels stand. │ └───────────────────────────────┬────────────────────────────────┘ ▼ ┌─ src (React Flow) ──────────────────────────────────────────────┐ │ typed color-coded nodes · grouped layers · labeled data-flow │ │ edges · overview + per-node detail panels · Mermaid + PNG export│ └──────────────────────────────────────────────────────────────────┘ ``` AST 层是事实来源。tree-sitter 会找出真实的文件和符号，角色规则会对它们进行分类（例如，`redis` 导入会变成 Cache 节点）。AI 层只是在这个固定的结构之上重写人类可读的文本。它无法凭空捏造、添加或删除任何节点或边。 ## 连接你的 Claude Scaffld 的设计初衷就是与 Claude 配合使用。确定性引擎绘制出精确的映射图；而你的 Claude 负责使其变得*易于阅读*，将原始的符号名称转化为通俗的英文标签以及针对各个组件的描述（例如“在多次请求之间记住你的身份”）。 好消息是：如果你已经在使用 [Claude Code](https://www.anthropic.com/claude-code)，那么无需任何设置。Scaffld 会自动检测到你本地的 `claude` CLI 并直接使用它，走你自己的账号和订阅计划，没有任何额外成本。它会在启动时打印一行提示，让你随时知晓该功能已激活。 | `SCAFFLD_AI` | Provider | 费用 | | --- | --- | --- | | _(未设置)_ / `claude-code` | 你本地的无头 `claude` CLI（共享你的 Claude 订阅额度） | $0 | | `api` | `@anthropic-ai/sdk`（需要你自己的 `ANTHROPIC_API_KEY`） | 按量计费 | 你可以通过 `SCAFFLD_ENRICH` 保持控制：未设置 = 自动（当 Claude 可用时开启），`on` = 强制开启，`off` = 永不开启。增强功能会将简短的代码片段发送到**你自己的** Anthropic 账号，并且它只会重写标签，绝不会修改图结构。如果 Provider 无法访问，Scaffld 会静默保留确定性的标签。所有选项均在 [`.env.example`](.env.example) 中有详细记录。 目前 Claude 是唯一受支持的模型。我们正在努力使 AI 层实现与具体模型无关，以便你能够接入其他 Provider；Provider 接口（[`server/ai/provider.ts`](server/ai/provider.ts)）已经作为扩展点预留好了，欢迎广大开发者贡献代码。 ## 安全与隐私 - **绝不执行仓库代码。** 代码仅由 tree-sitter 进行解析，绝不在本地运行。 - **克隆过程无法被劫持。** 目标地址是根据严格校验过的 `owner/name`（仅限 github.com）重新构建的，并且 `git` 运行时使用的是参数数组，不经过 shell。 - **默认本地运行。** 服务器绑定到 `127.0.0.1`。克隆属于浅克隆，存放在临时目录中，并在分析完成后被删除。 - **除了 `git clone` 本身之外，没有任何数据会离开你的机器**，除非你连接了你的 Claude。如果连接了，简短的标签片段会发送到你自己的账号，这一行为会在启动时予以告知，且可通过 `SCAFFLD_ENRICH=off` 将其关闭。 完整详情以及如何报告漏洞，请参阅：[`SECURITY.md`](SECURITY.md)。 ## 语言支持 Python · JavaScript/JSX · TypeScript/TSX · Java · Go · C/C++（基于 tree-sitter WASM 语法规则）。 ## 开发 ``` npm run dev:all # API + web, hot reload npm test # vitest: schema, coerce, mermaid, url-parse, analyzer npm run typecheck # tsc (app + server) npm run lint # eslint npm run test:e2e # playwright (mocks /api in-browser) ``` 欢迎贡献代码，请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE) © Filip Skulimowski ## 传承 重现了 Mariana Antaya 在 Emergent 演示集锦中的 **archmap** 工具（一个 AST + Claude 的仓库可视化工具），并基于本地优先的工具链从零开始重新构建。本地优先、可检查、可重建。无第三方应用，无遥测数据。

标签：Claude, CVE检测, GNU通用公共许可证, MITM代理, Node.js, SOC Prime, 云安全监控, 代码可视化, 开发工具, 架构图, 特征检测, 自动化攻击, 静态分析