Coding Agent 接手陌生仓库前：repo2skill 的确定性预检

本文更新于 2026-07-26，内容对应 repo2skill v0.4.0。

把一个陌生仓库交给 Coding Agent，真正影响开工效率的往往不是“它能不能总结 README”，而是几个更具体的问题：

源码从哪里开始读？
仓库里真实存在的 build、test、lint 命令是什么？
修改某个 workspace package 后，应该验证哪些直接消费者？
哪些环境变量可以知道名字，但绝不能读取真实值？
哪些命令只能展示给人看，不能替用户直接执行？

repo2skill 把自己定位为一个确定性 preflight context compiler：读取本地仓库或公开 GitHub 仓库中的明确证据，生成 Coding Agent 开工前需要的项目地图、命令、边界和验证上下文。

Repository evidence
  → repo2skill.json
  → project-map.md
  → AGENTS.md
  → SKILL.md
  → maintenance-profile.md
  → quickstart.windows.md / quickstart.macos.md / quickstart.linux.md
  → report.html

为什么强调“确定性”

通用仓库摘要擅长回答“这个项目大概做什么”。repo2skill 更关心能否从仓库文件中证明一条结论：

包管理器来自 lockfile、workspace 配置和 package.json。
命令来自真实存在的 scripts，而不是根据技术栈猜测。
入口来自包元数据、源码结构和配置文件。
workspace 依赖来自 dependency 字段和明确的包名关系。
环境变量只收集允许的名称和安全元数据，不读取真实 secret。

所有 JSON、Markdown 和 HTML 导出器消费同一个结构化分析对象。事实携带来源和置信度；缺少证据的结论会被省略，而不是用“通常可以运行 npm test”一类泛化建议补齐。

当前如何运行

截至本文更新日期，项目声明的 npm 包名是 @haodehaode378/repo2skill，但该 scoped 包尚未公开发布。因此当前文章只提供源码运行方式：

git clone https://github.com/haodehaode378/repo2skill.git
cd repo2skill
npm install

# 分析仓库内置 fixture
npm run dev -- ./tests/fixtures/analysis-target --out ./out

# 分析公开 GitHub 仓库
npm run dev -- https://github.com/tinylibs/tinybench --no-cache --out ./out-tinybench

不要使用：

npx repo2skill ...

npm 上的无作用域 repo2skill 是另一个项目，并非本文介绍的 haodehaode378/repo2skill。只有 scoped 包实际发布后，才应使用仓库 README 中预留的 npx @haodehaode378/repo2skill ... 方式。

v0.4.0：从单仓库摘要走向 Monorepo Intelligence

v0.4.0 的重点是 Workspace Package Operational Graph。它不追求函数调用图，而是为 Agent 建立“修改一个包会影响谁、应该运行什么”的操作关系。

发现真实 workspace package

repo2skill 可以从这些来源发现 package：

pnpm-workspace.yaml
package.json 中数组或对象形式的 workspaces
常见的 apps/*、packages/* 目录

分析过程会处理 glob 排除、Windows 路径规范化和稳定排序，并跳过生成目录、缓存目录及缺少 package.json 的伪 package。

收集包级事实

对每个 package，v0.4.0 会收集：

包名、路径、项目类型和包管理器信息
scripts 与可以由这些 scripts 生成的命令
源码入口和 package 发布入口
配置文件与重要目录
安全的环境变量名称线索
支撑每条结论的来源证据

建立直接依赖和消费者

假设 workspace 中存在三个包：

apps/web       @acme/web
packages/ui    @acme/ui
packages/core  @acme/core

如果 web 依赖 ui，ui 以 peer dependency 依赖 core，生成的操作图会保留依赖类型：

graph LR
  WEB["@acme/web"] -->|"dependency"| UI["@acme/ui"]
  UI -->|"peerDependency"| CORE["@acme/core"]

每个 package 都会记录直接依赖与直接消费者。Agent 修改 @acme/core 时，不只知道 core 自己有哪些测试，也能看到哪些上游包值得补充验证。

生成包管理器感知的命令

命令只从各包真实存在的 scripts 生成：

pnpm --filter @acme/core test
npm run build --workspace @acme/core
yarn workspace @acme/core typecheck

repo2skill 只生成和展示这些命令，不会执行目标仓库的脚本。

聚焦一个 workspace package

使用 --package <name-or-path> 可以只分析一个包：

# 按 package 名称
npm run dev -- . --package @acme/core --out ./out-core

# 按仓库相对路径
npm run dev -- . --package packages/core --summary-only

聚焦结果仍会保留必要的根仓库上下文、当前包、直接依赖和直接消费者，同时过滤无关 package 的入口、命令、配置和环境变量线索。

找不到目标、名称有歧义，或者在单包仓库中错误使用 --package 时，CLI 会返回明确错误。

生成产物

文件	v0.4.0 中的用途
`repo2skill.json`	统一结构化事实、workspace packages、内部边、命令和聚焦状态
`project-map.md`	package 表、入口、命令、消费者和小型 Mermaid 图
`AGENTS.md`	修改前阅读位置、根级与包级验证、消费者检查
`SKILL.md`	package references、入口角色、scoped commands 和聚焦上下文
`maintenance-profile.md`	package 清单与基于直接消费者数量的影响提示
`quickstart.*.md`	Windows、macOS、Linux 对应的根级和包级命令
`report.html`	无运行时网络依赖的自包含 workspace 报告

与其强调“输出了多少份文件”，更重要的是这些产物不会各说各话：它们共享同一份分析结果，只针对不同消费场景组织信息。

常用模式

# 只打印摘要，不写产物
npm run dev -- . --summary-only

# 只做只读风险提示
npm run dev -- https://github.com/example/repo --no-cache --audit-only

# 选择输出格式
npm run dev -- . --format json --out ./out-json
npm run dev -- . --format md --out ./out-md
npm run dev -- . --format all --out ./out-all

它不做什么

repo2skill 当前的信任边界很明确：

只深度支持 Node.js / TypeScript 仓库。
输入限本地仓库和公开 GitHub 仓库，不包含私有仓库鉴权。
不运行目标仓库的 install、build、test、deploy、publish、migration 或 lifecycle scripts。
不自动安装目标仓库依赖。
不读取真实 .env secret 内容。
不提供完整 sandbox、恶意软件检测或依赖漏洞扫描。
v0.4.0 的图只到 package 直接关系，不包含函数、类、symbol、import 或 call-level graph。
生成的 AGENTS.md、SKILL.md 和候选命令仍需要人工审阅。

与知识图谱工具的区别

repo2skill 是开工前的确定性预检，不是代码知识图谱。它不会生成 LLM 架构摘要、函数调用图、向量搜索、Dashboard 或 Guided Tour。

如果需要深入探索代码符号和调用关系，可以把它和知识图谱工具组合使用：repo2skill 先提供可审计的开工事实，知识图谱再补充更广的结构理解。

仓库地址：https://github.com/haodehaode378/repo2skill

对 Coding Agent 来说，真正有价值的上下文不是越多越好，而是每条信息都知道从哪里来、可以相信到什么程度，以及下一步该验证什么。