先看结果：GitHub - AnHuoZhe/project-analyzer: project-analyzer · GitHub | 读完这篇文章你就能理解：为什么大部分 Agent 项目的 README 看不出来问题，但一跑就崩。
我踩的坑
三个月前我开始系统性地看 GitHub 上的 Agent 项目。每天打开 trending，全是各种 Agent 框架、Agent 工具、Agent 工作流。看 README 一个比一个厉害------"下一代 Agent 编排""企业级多 Agent 协作""生产就绪的 AI 工作流"。
然后我真的去跑了几个。
第一个项目，跑了三天之后发现它在悄悄地丢用户偏好------不是 bug，是架构设计问题。它的记忆系统把用户偏好存在对话历史里，对话一长就被截断了。
第二个项目更离谱。工具调用看起来很正常，但有一次给了 Agent 一个写文件的权限，它直接把整个项目目录清了。不是幻觉，是工具描述写得太模糊------"删除不需要的文件"------Agent 判断所有文件都不需要。
这两个问题，都不是代码审查能看出来的。 代码写得挺规范，变量命名没问题，测试覆盖率也高。问题出在 Agent 架构设计上------上下文怎么管、记忆怎么存、工具权限怎么设。
我就想：有没有一套框架，能让我拿到一个 Agent 项目之后，不靠猜，系统性地判断它靠不靠谱？
找了一圈，没有。
市面上的方案为什么不够
代码审查工具（SonarQube、CodeRabbit）看的是代码质量------复杂度、安全漏洞、命名规范。但 Agent 的好坏不在代码行数。一个 500 行但上下文管理设计合理的 Agent，远比一个 5000 行但上下文天天爆炸的 Agent 靠谱。
论文和学术评估（SWE-Bench、GAIA）看的是 Agent 的任务完成能力。但那是打分，不是拆解------它告诉你这个 Agent 得了 67 分，不告诉你为什么丢的那 33 分是因为上下文工程有问题是记忆系统拉胯。
我需要的是架构体检------不只看"跑得怎么样"，还要看"设计得怎么样"。
我做了什么
基于李博杰《深入理解 AI Agent》里梳理出来的工程实践（第 2/3/4/6/9/10 章），我搭了三套分析框架。拿到一个 GitHub 项目之后，先判断它是什么类型，再选对应的框架组合。
代码
Agent 项目 → 六维度 + 架构裂隙 + 矛盾分析
有代码非 Agent → 架构裂隙 + 矛盾分析
纯内容 → 矛盾分析为什么要分三种？因为不是所有项目都适合用 Agent 框架去套。
我之前犯过一个错。看到什么项目都往六维度里塞，结果分析一个 CLI 工具的时候，硬给它套"记忆系统"和"工具调用"------人家根本没有 Agent 循环，套这些就是生搬硬套。后来我定了一个铁律：非 Agent 项目不做六维度分析。
下面展开三个框架。
六维度评估
这是 Agent 项目的核心分析。六个维度，每个下面还有子分类：
上下文工程（7 个子类）：系统提示词怎么组织的？技能文件什么时候加载？上下文太长怎么办？有没有做 KV Cache 友好的设计？
这是我最看重的一个维度。李博杰的原话------"上下文质量决定 Agent 能力上限，中等模型加精良上下文，效果超过顶级模型加信息匮乏。"
我第一次意识到这个维度的重要性，是分析 forge（一个 Agent 代码审查工具）的时候。它有一个特别漂亮的设计：子 Agent 审查时，不继承主对话的上下文。每个子 Agent 从零开始，只拿到审查任务和代码，不被主对话里的讨论带偏。这就是上下文隔离------LLM 的统计本性决定了，上下文里出现的任何模式都会抬高后续输出的相关权重，不管它对不对。
记忆系统（5 个子类 + 三层评估）：用户偏好存哪了？跨会话能记住吗？存的是纯文本还是结构化数据？
三层递进：基础回忆（记住用户说过什么）→ 多会话检索（跨时间跨主题查找）→ 主动服务（在用户开口之前就知道他需要什么）。大部分项目卡在第一层。
工具调用（五分类）：感知工具（read_file）、执行工具（write_file）、协作工具（spawn_subagent）、事件触发（set_timer）、用户沟通（ask_clarification）。后两类大部分项目都缺失。
还有个容易被忽略的点：工具描述应该写"什么时候用"而不是"能做什么"。边界条件比能力描述更重要------大多数调用失败不是因为不知道能做什么，而是不知道不能做什么。
可靠性（5 个子类）：崩了怎么降级？多 Agent 场景下一个出错会不会连锁崩？
多 Agent 的错误级联放大是我见过最隐蔽的坑。一个子 Agent 输出了一个小错误→被第二个 Agent 当正确信息引用→因为"被引用过"获得更高可信度→后面的 Agent 直接当事实用。
解法不是让每个 Agent 更聪明，是引入独立视角------第二个 Agent 不看第一个的思考过程，只看原始证据。或者更狠的：引入确定性外部验证（单元测试、编译器），这些不受幻觉影响，是天然的断链器。
成本控制（4 个子类）：token 怎么省的？有没有用缓存？小任务切小模型吗？
Agent 成本的非线性增长是最容易被低估的。第 n 轮的输入 = 前 n-1 轮全部累计。不是简单乘 n，是累加。KV Cache 复用能降 30-60% 的输入成本------前提是静态前缀稳定。
评估（7 个子类）：怎么知道自己改好了？有测试集吗？指标用对了吗？
一个关键区分：Pass@k 和 Pass^k 不能混用。Pass@k 是 k 次至少一次成功（测能力天花板），Pass^k 是 k 次全部成功（测稳定性）。很多人拿 Pass@k 当产品稳定性指标用，完全搞反了。
架构裂隙分析
不对代码做行级审查，从五个切口捅进去找设计层面的裂缝：数据流、失败模式、状态切换、分层检查、运维隐患。
这个框架不只用于 Agent 项目。一个 CLI 工具、一个桌面应用、甚至一个静态网站生成器，都能用裂隙分析找到设计问题。
矛盾分析
跳出项目本身，追问它为什么会出现。什么客观矛盾催生了它？为什么是现在而不是更早或更晚？
这是历史唯物主义视角------任何项目都是某个矛盾的解决方案。理解矛盾才能判断它的天花板在哪。
两个关键设计决策
为什么输出 Word 而不是 Markdown？
一开始我写的是 Markdown 报告。但六维度分析每篇都上万字，Markdown 的表格和层级在长文里阅读体验很差------尤其是交叉点分析，涉及六个维度的两两对比，纯文本根本看不清谁对应谁。
Word 能做原生表格、能分页、能设字体字号。排版规范很简单：正文楷体 12pt，标题黑体加粗，每章换页。最重要的------写文档前强制跑 validate_output.py 校验文件名和格式，避免手动检查漏掉。
代价是：没有网页版 dashboard，不能在浏览器里直接看。这点我写在 README 的局限性里了。
为什么批量分析用子 Agent 隔离上下文？
最早做批量分析的时候，主对话直接参与每个项目的分析。效果是：分析第 1 个项目质量很高，分析第 10 个的时候已经明显退化。不是模型不行，是上下文被撑爆了------每次回复都带着前面 9 个项目的完整内容，单次调用从 5 万 token 涨到 39 万。
改成了子 Agent 隔离模式：每批 3 个并行派发，每个子 Agent 只拿自己那个项目的信息，分析完生成 Word 文档然后退出。主对话只做派发和确认，不碰具体分析。
这和 forge 的上下文隔离是一个道理------"隔离优于压缩"。大体积的中间信息根本不进主上下文，用完即弃。
实战效果
分析过的项目里，印象最深的是 ag-kit。它是一个 Agent 技能系统，表面看和普通的 Agent 框架差不多。但六维度分析挖出来了两个东西：
- 它的上下文工程做了渐进式披露------技能文件不一次性全量加载，而是按需注入。这部分设计对标的是 Claude Code 的 SKILL.md 机制。
- 它的工具调用缺了事件触发和用户沟通两类------这意味着它只能做"Agent 主动干活"的场景，做不了"外部事件来了被动响应"的场景。
第二点是 README 上完全看不出来的。README 只会说"支持多种工具"，不会说"缺了哪几种"。
这个东西的局限
我得诚实地说：
不是自动化工具。 需要聊天界面配合，不能当 CI 插件跑。分析一个项目大概要 5-10 分钟的人工交互（确认类型、选择框架、审阅输出）。
分析质量取决于源码深度。 只读 README 不读源码 = 浅分析。目前对 Agent 项目的分析会拉取 README、目录结构、关键源文件，但不是每个项目都深度拆。
六维度框架只对 Agent 项目准。 非 Agent 项目硬套会大量出现"不适用"，浪费 token 还误导结论。
输出只有 Word 格式。 暂时没有网页 dashboard、没有 JSON API。
这个项目教会我的
写这个分析器的过程，其实是自己在消化李博杰那本书的过程。每分析一个项目，就对照书里的框架验证一遍------这个项目在上下文工程上做对了什么、在可靠性上漏了什么。
最大的感受：Agent 工程和传统软件工程有一个根本区别。 传统软件的质量判定是确定性的------测试过了就是过了。Agent 的质量判定是概率性的------同一个输入可能出不同结果，同一个设计在不同场景下表现完全不同。
这意味着 Agent 项目的评估不能只靠"跑测试"。必须看架构------看它在设计层面做了哪些取舍、这些取舍在什么场景下会翻车。
这也是为什么我坚持做矛盾分析。一个项目不是因为"代码写得好"才有生命力，是因为它解决了某个客观矛盾。找到那个矛盾，就知道它的天花板在哪。
如果你也在看 Agent 项目，欢迎用这个框架试试。拿到一个项目之后，先别看 star 数，先用六维度扫一遍------上下文怎么管的、记忆怎么存的、工具权限怎么设的。你会发现 80% 的 README 里的"生产就绪"，连这三个基础问题都经不起追问。
仓库地址：GitHub - AnHuoZhe/project-analyzer: project-analyzer · GitHub