AI 接手一个项目之前，先给它一张可验证的上下文包

我最近把 Doramagic 的一个内部工具单独整理成了公开仓库：

https://github.com/tangweigang-jpg/doramagic-ai-context-pack-benchmark

它解决的不是“让 AI 多读一点代码”，而是另一个更具体的问题：在 AI 接手一个 repo 之前，先把哪些信息能说、哪些信息不能说、哪些判断需要证据、哪些风险必须先停下来，编译成一组可检查的上下文资产。

这个项目的边界很窄，也正因为窄才有用。它不安装目标项目，不模拟运行，不声称验证业务正确性。Repomix 只负责把源码打包；Doramagic 负责上层的 schema、渲染、验证和面向使用者的契约。

我把它理解成“安装前的 AI 交接包”，不是“项目万能总结器”。

它会为一个项目生成这些东西：

- `CLAIM_GRAPH.json`：把主张和证据拆开，避免把 README 里的愿望当事实。
- `EVIDENCE_INDEX.json`：保留证据片段和源路径，方便回查。
- `CAPABILITY_CONTRACT.json`：把可用能力写成受证据约束的内部契约。
- `AI_CONTEXT_PACK.md`：给宿主 AI 读取的上下文包。
- `CONTINUE_CHECK.md`：继续前判断卡，回答“现在该不该继续”。
- `PROMPT_PREVIEW.md`：安装前先试一次的消费端提示词。
- `HOST_CONSUMPTION_REPORT.json`：检查宿主 AI 是否拿到了足够结构。
- `validation_report.json` 和 `human_ai_consistency_report.json`：做 schema、证据和 Human Manual 一致性检查。

这里有一个关键取舍：压缩噪声，不压缩会影响判断的上下文。

很多 repo 摘要工具会把问题做成“更短的概述”。但 AI 真正容易出错的地方，往往不是上下文太长，而是上下文没有结构：边界不清、证据没挂钩、风险卡缺失、提示词没有可复用入口。结果就是 AI 很快给出方案，但方案跨过了它不该跨的线。

所以这个 benchmark 的输出里保留了任务路由、角色/Skill 索引、prompt recipe、证据片段、边界说明、风险卡和 Continue Check。它不是为了显得完整，而是为了让下游 AI 少做“看起来合理但没证据”的跳跃。

这次公开发布前我做了几项硬检查：

- 创建前确认目标 GitHub repo 不存在，避免覆盖旧项目。
- 扫描 staging 目录，排除真实 API key、PAT、PEM private key 和 `.env`。
- 排除 runtime artifacts、私有操作状态、缓存和本地环境文件。
- Python 单元/语法检查通过，AI Context Pack 部分 41 个测试通过。

我觉得这个方向对 AI 工程会越来越重要。以后不是把更多文件塞进上下文窗口，而是先定义“什么事实可以被消费、什么结论需要证据、什么操作必须先停”。上下文工程如果没有验证层，很容易变成更贵的复制粘贴。

项目地址：
https://github.com/tangweigang-jpg/doramagic-ai-context-pack-benchmark

标签：
AI Agent, 上下文工程, Developer Tools, Doramagic, Repomix, Evidence Graph, Prompt Engineering, AI 工程