Crewforth 新增无模型仓库结构扫描

接手陌生仓库时，让 AI 先读一遍代码已经很常见。麻烦在于：每次探索都要花时间和 tokens，AI 画出的调用关系，也未必能分清哪些来自代码、哪些只是推测。

Crewforth 3.2.0 新增的 Crew Map，尝试先用确定性扫描建立项目结构，再让模型补充说明。它值得关注的地方，是让地图上的关系能够追溯到具体代码行。不过，这张地图能证明什么、漏掉什么，仍然需要划清边界。

先把结构查清楚，再让模型解释

Crewforth 是面向 Claude Code 的 MIT 开源工具包，包含 14 个专职 agent、40 项 skills、13 个 /crew-… 命令，以及拦截破坏性操作、提交审批和密钥泄露的 hooks。Crew Map 是其中负责理解仓库的一部分。

它的第一步不调用模型，也不运行项目，而是读取清单和源码，生成 .crewforth/crew-map.json。支持范围包括 Node/TypeScript、Python、Go、.NET、Java 和 Kotlin，其他技术栈暂时不会被映射。

扫描结果记录模块接触的数据库、缓存、队列、外部 API，以及模块提供和调用的端点。模块、连线、问题发现都带有 file:line，方便直接回到代码核查。

地图先记录文件能证明的结构，模型随后负责解释。

扫描具有确定性：相同文件树产生完全相同的字节。把 --check 放进 CI，地图过期就会导致构建失败。这比依赖新人记得更新架构文档更容易执行，但团队仍要安排地图更新流程。

作者还说明，配置值只用于辨认资源类型，例如 Postgres URL 或 Redis host，不会把密钥复制到地图里。这里描述的是地图文件的处理方式，不能据此推断整个工具链的安全性。

有引用的 AI 说明，能保证到哪一步

/crew-map 会先扫描，再让模型补充模块用途、项目概览、分层、业务领域和新人导览。

每个模块的用途最多两句话；分层限定为 ui、api、service、data、infra、tool、library；领域可以是 billing、auth、search；导览最多八站。

这些内容必须引用扫描器已经读过的行。crew-map.sh --validate 会拒绝无引用、越界引用、非法分层、写成整句话的领域，以及指向不存在模块或重复访问模块的导览。手工修改扫描器字段也会被拒绝。重新扫描时，仍然成立的说明会保留，其余丢弃。

这套约束能减少凭空补结构的空间，但验证引用合法，不等于验证解释正确。引用行是否足以支持「这个模块负责结算」，仍需要人判断。

README 也会进入读取范围。作者在一个真实项目中发现，十个模块里有四个没有其他可用于描述用途的信息。这是一个具体观察，并不足以代表一般仓库，却提醒我们：模块文档依然会影响 AI 对项目的理解。

地图怎么用于接手项目，哪些地方看不到

Studio 是本地面板，通过 npx crewforth studio 启动，按 p 打开 Map。它只读取已有 JSON，不会自己重新扫描。

模块按层排列，卡片展示名称、业务领域、最多三项技术信息和外部服务。文件证明的连线显示为实线，推断关系显示为虚线，模型提出的关系另有标记。搜索会淡化不匹配项，底部导览则按顺序带新人阅读。

检查面板提供入口、目录和文件数量，可以复制 file:line，也能把问题发现复制成 crew 任务。前后端分仓时，Compare with 可以拿一个项目的调用去匹配另一个项目的端点。负责拆解模糊需求的 crew-planner 也会读取地图，让任务规划使用同一份结构信息。

局限同样明确：连接来自 imports、项目引用和 HTTP 调用等文件证据，运行时决定的连接可能漏掉。因此，图上没有连线，不能直接认定没有依赖。

扫描器包含十条缺口规则，其中五条有引用行作为证据，另外五条根据「没找到」作判断，例如某端点没有调用者。后五条在误报率测量完成前默认隐藏，只显示数量，也允许主动查看。

同版本还加入了只读手机查看链接：同一 Wi-Fi 扫码访问，无需 ssh 或隧道，八小时失效、可撤销，transcripts 默认隐藏。新增的 crew-docs-agent 负责 README、指南、发布说明和商店文案；法律与隐私文本使用 critical tier，并交给 crew-privacy-agent 审计。这些属于协作能力，不能作为地图准确率的证据。

我的判断

我认可它把扫描事实、推断关系和模型建议分开展示。与每次都让 AI 自由探索仓库相比，固定产物加代码位置，更方便复核，也更容易让多人围绕同一张图讨论。

但原文没有给出扫描耗时、tokens 节省比例、关系识别准确率，也没有提供与普通 AI 探索的对照实验。「更快、更省、更可信」目前主要是设计上的理由，不能当成已经量化的效果。

静态地图也替代不了运行时证据。动态路由、依赖注入或配置决定的调用，可能需要继续查源码和实际运行情况。扫描免费，模型生成说明仍消耗 Claude Code 会话的 tokens。

此外，shell gate 会解释它拦下的 git reset --hard、git clean -f、git push --force、rm -r 原本会丢弃、覆盖或删除什么。这个反馈有助于理解操作后果，但原文没有展开其完整覆盖范围。

能拿来做什么

• 接手受支持的仓库时，可以先生成地图，再沿模块入口和 file:line 核对关键路径，把它作为阅读代码的导航。

初始化新项目或接入已有仓库，原文给出的命令是：

npx crewforth init      # or: npx crewforth adopt, for an existing repo

注意注释中的 adopt，它对应已有仓库。

• 在 Claude Code 中生成结构和说明后，运行 npx crewforth studio 查看地图；对关键业务模块，重点检查模型引用的代码是否真的支撑描述。

/crew-map

注意这个命令同时触发扫描和模型说明，后者会消耗 tokens。

• 前端与 Node 后端分仓时，可以用 Compare with 辅助核对请求和端点；发现未匹配项后，继续检查网关、代理和运行时配置。
• 团队决定维护地图后，可以在 CI 接入 --check 检测过期产物；对默认隐藏的缺口规则，先人工评估误报，再考虑是否用于日常排查。