UnvibeCode 使用边界指南:200 万 Token 限制、它不能替代什么、如何正确解读报告
UnvibeCode 使用边界指南:200 万 Token 限制、它不能替代什么、如何正确解读报告
UnvibeCode 是一款将复杂代码库逆向拆解为业务工作流、关联代码与风险发现的代码库分析工具。但要想用好它,先要弄清三件事:200 万 Token 的规模限制、它不能替代的工作,以及报告的正确解读方式。这篇使用边界指南用最简单直白的话讲清楚这三点,帮你避免误判分析结果、错误引用报告结论。
一、先搞懂 UnvibeCode 到底在做什么
一句话概括:UnvibeCode 把仓库"逆向工程"化——读源码、重建业务实际在做什么,并输出带证据的报告,而不是逐文件帮你读代码。
它的分析分三步进行:
- 本地映射仓库:读取受支持的源文件(Python、JavaScript、TypeScript、Go 等),建立文件、符号、导入与调用之间的静态关系图;
- 重建业务工作流:把结构化的代码上下文送入托管服务,将入口点、决策、状态变化与结果串成完整的工作流;
- 风险审查:对照代码,找出可能影响客户、权限或数据一致性的失败路径,并附上可独立核实的证据。
⚠️ 关键点:UnvibeCode 描述的是源码中的静态连接关系,不是对应用真实运行过程的录屏。这一点直接决定了后面"如何解读报告"的边界。
完整原理可参考 docs/HOW_IT_WORKS.md。
二、200 万 Token 限制:哪些仓库能拿到完整分析
这是最容易被误解的一条使用边界。UnvibeCode 按"估算源码 Token 数"区分处理方式:
| 仓库规模 | 你会得到的输出 |
|---|---|
| ≤ 约 200 万 Token | 完整 4 项输出:Business Workflow Map、Connected Code Map、Business Risk Findings、Complete Repository Context |
| > 约 200 万 Token | 仅 2 项输出:Connected Code Map 和 Complete Repository Context,不会启动更深层的工作流与风险审查 |
为什么这样设计?是为了防止超大仓库进入漫长的托管分析,同时仍能产出有用的代码图和 LLM 上下文输出。
⚠️ 重点提醒:如果你的报告里只有"Connected Code + LLM Context"两项,不代表仓库没有问题,只代表审查没有进入更深阶段。输出缺失 ≠ 无风险发现(no findings),这是两条完全不同的结论。详见 docs/LIMITATIONS.md。
💡 实用建议:审查大型 monorepo 前先评估规模;超限时优先用 Connected Code Map 下载聚焦上下文,或分模块处理,别指望一次拿到全量工作流。
三、它不能替代什么:5 件事 UnvibeCode 做不了
UnvibeCode 支持的是代码理解、工作流审查、基于证据的工程调查,它不是全能的质检关卡。它不能替代:
- 🚫 测试:单元、集成、端到端、负载、渗透测试都不包括
- 🚫 工程师人工代码审查(由熟悉系统的人完成)
- 🚫 安全、隐私、法律与合规评估
- 🚫 生产监控与事故调查
- 🚫 与产品负责人确认业务需求是否如此
换句话说:UnvibeCode 告诉你"代码做了什么、哪里可能坏",但"它该不该这样"和"它线上真的坏了吗",仍然需要运行时验证和责任人判断。任何报告中的场景,在被当作确认的生产缺陷之前,都必须对照应用预期行为和运行环境进行验证。
四、如何正确解读报告:四步阅读法
打开结果目录中的 00_unvibecode_results.html,按以下顺序阅读(完整说明见 docs/OUTPUTS.md):
第 1 步:Business Workflows —— 理解系统做什么
选择工作流区域,逐条看"它做什么、产出什么、谁依赖它、由哪些代码支撑"。先用这个视图把产品行为连到实现上,再去看单个文件。
第 2 步:Connected Code —— 定位行为在哪
交互式地图展示文件与符号之间的静态关系。悬停文件可预览关联代码,点击文件可为 AI 助手下载聚焦上下文(三档预算:Narrow 约 30K / Optimal 约 45K / Wider 约 75K tokens,Optimal 是推荐起点)。
第 3 步:Risk Findings —— 发现可能坏的地方
每条发现按"触发条件 → 代码行为 → 业务后果 → 该改什么 → 验收检查"的链条阅读。解读时记住两条边界规则:
- 证据标准:被发布的风险发现必须连接到受影响的工作流和支撑代码证据,以便独立调查验证;
- 无发现 ≠ 安全:一次完成但没有被接受发现的审查,不能证明每条路径都是安全的。这个结论只在"已完成的审查范围"内成立,部分或跳过的阶段不能当作全仓库结论。
第 4 步:LLM Context —— 把分析带得再远一点
下载规范化仓库 ZIP 交给其他 AI 助手继续分析。注意 30K/45K/75K 只是上下文预算,不是对下载内容 Token 数的承诺,下载后请先检查实际大小。
五、解读报告前的快速核对清单
在把报告当作结论引用或分享之前,过一遍这个清单:
- [ ] 检查终端与报告状态:是否有阶段被跳过、失败或未完成?
- [ ] 仓库是否超过 200 万 Token?若是,报告只有 2 项输出属正常
- [ ] 缺失的工作流/风险输出 ≠ "无风险发现",两种说法不能混用
- [ ] 每条发现在"已完成审查范围"内解读,不放大为全仓库结论
- [ ] 风险发现先对照运行环境验证,再决定是否改动
- [ ] 报告文件(HTML、ZIP、
_support/等伴随目录)保持在一起,移动单个文件会打断链接
常见边界相关问题(如"只有 Connected Code 和 LLM Context 两项可用""某个报告页签空白")都有对应排查步骤,见 docs/TROUBLESHOOTING.md。
六、相关文档路径速查
| 文档 | 解决的问题 |
|---|---|
| docs/LIMITATIONS.md | 200 万 Token 限制、不能替代清单、证据与覆盖范围 |
| docs/HOW_IT_WORKS.md | 分析三阶段、报告阅读顺序、大仓库行为 |
| docs/OUTPUTS.md | 四项输出对应的文件与用法细节 |
| docs/TROUBLESHOOTING.md | 安装问题、报告打不开、输出缺失排查 |
| docs/QUICKSTART.md | 两条命令完成安装与仓库审查 |
一句话总结:UnvibeCode 是代码库的"X 光片"——它告诉你结构在哪里、哪里可能异常,但最终诊断必须由测试、人工审查和产品负责人共同给出。先懂边界、再用工具,报告才能真正帮你把业务逻辑看穿。


