# FDE 作品集仓库，要展示 Agent 在哪里失败

> 单次正确率 80% 的 Agent，连对三次只有 51%，基于真实失败的评测胜过精美演示。

原文: https://fdetimes.net/zh/guides/fde-portfolio-repo-agent-evals-readme/

假设你的 Agent 在 80% 的运行中给出正确答案。听起来不错，直到你算一下它连续三次都答对的概率：0.8 × 0.8 × 0.8 = 51.2%。

所以，前线部署工程师（FDE）的作品集仓库不能止步于一个跑得漂亮的演示。演示只是一次尝试。值得拿出手的仓库，必须说明 Agent 在哪里失败、失败得有多频繁，以及你如何处理每一次失败。本文的度量方法参考了 Anthropic、OpenAI 和 Hamel Husain 关于 AI 系统评测的建议。

培训机构 FDE Academy 的博客上有一篇指南说得很直白：一个真正部署过、并写成案例分析的项目，分量超过八个精美的演示。

这是建议，不是定律，但道理不难理解：在真实数据上跑通的系统，比八个在干净数据上运行的原型更能体现能力。

下面分五步讲如何搭建这样的仓库。文中代码是**精简示意**：调用模型的函数留空，方便你接入自己使用的 SDK。

## 第 1 步：什么样的问题才够“企业级”？

同一篇 FDE Academy 指南建议：选一个贴近现实的企业场景，只做最小可行产品（MVP），不追求完整愿景，并使用真实或接近真实的脏数据。最后这个条件，正是 FDE 作品集和课程作业的分水岭。

设想一家分销公司通过邮件接收供应商发票。有的是歪着打印再扫描的 PDF；币种有的写“VND”，有的写“đ”；有的税号缺了几位。MVP 只做一件事：Agent 读取发票，与采购订单比对，返回“匹配”、附原因的“不匹配”，或“需人工审核”。

```
invoice-agent/
  agent/loop.py        # 核心循环
  agent/tools.py       # 工具及其描述
  data/raw/            # 脏发票
  logs/                # 每次运行一个 JSONL 文件
  evals/cases.jsonl    # 用例集
  evals/test_basic.py  # pytest 风格的断言
  README.md
```

（注释依次为：核心循环；工具及其描述；脏发票；每次运行一个 JSONL 文件；用例集；pytest 风格的断言。）

**检查：**你能用一句话说清 MVP 的范围。如果这句话里“和”字超过两次，就继续删减。

## 第 2 步：为什么核心循环必须五分钟内读懂？

Anthropic 在《Building effective agents》中建议，先找最简单的方案，只在确实需要时才增加复杂度。它还提醒，框架往往会叠加抽象层，掩盖底层的提示词和响应。对作品集来说，这是硬伤：评审打开仓库却找不到提示词，就无从判断你的思路。

```python
# agent/loop.py — 精简示意
def run(invoice_text, po, call_model, tools, log):
    messages = [system_prompt(), user_msg(invoice_text, po)]
    for step in range(8):                  # 限制步数上限
        reply = call_model(messages, tools)
        log.write(step, messages, reply)   # 记录一切
        if reply.tool_call is None:
            return parse_verdict(reply)
        result = tools[reply.tool_call.name](**reply.tool_call.args)
        messages += [reply, tool_result(result)]
    return {"verdict": "needs_review", "reason": "步数用尽"}
```

（注释分别标注步数上限和记录一切；兜底返回的原因是“步数用尽”。）

真正值得下功夫的是工具。Anthropic 称之为 Agent 与计算机的接口（agent-computer interface），建议精心设计：把工具文档写充分，并做测试。落到这个仓库，每个工具的 docstring 都应写明输入格式、何时返回空值，并附一个示例。

```python
def lookup_po(po_number: str) -> dict:
    """按 PO 编号查询采购订单。
    po_number：'PO-' 加 6 位数字，例如 'PO-004512'。
    未找到时返回 {}；不要猜测相近的编号。"""
```

（docstring 的意思是：按 PO 编号查询采购订单；格式为 'PO-' 加六位数字，例如 'PO-004512'；未找到时返回 &#123;&#125;，且不要猜测相近的编号。）

**检查：**把 `loop.py` 交给一个从没看过仓库的人。读五分钟后，对方能讲清 Agent 在做什么。

## 第 3 步：先记日志，再写评测

OpenAI 的《Evaluation best practices》建议在开发阶段记录一切，日后再从日志中挖掘评测用例。Hamel Husain 在《Your AI Product Needs Evals》中更进一步，主张清除查看数据的一切障碍。如果查看一次运行要打开三个文件、滚动到手酸，你很快就不会再看了。

最省事的做法是每次运行写一行 JSONL，包含输入、每次工具调用和最终结论。再写一个小脚本，把每次运行以易读的形式打印到终端。

在 `data/raw/` 上把 Agent 跑 20-30 次，逐条阅读。你很可能会发现没预料到的失败，比如 Agent 把“1.200.000”（越南写法，用点作千位分隔符）读成一百二十万，还是读成 1.2。

**检查：**你手上有一份亲自记录的真实失败清单，每条都附有对应日志文件的路径。

## 第 4 步：评测从失败出发，而不是从理论出发

Anthropic 对评测的定义很简洁：给 AI 系统一个输入，再用评分逻辑处理其输出，衡量是否成功。在它看来，从真实失败中提取 20-50 个简单任务，就已经是不错的起点。第 3 步的失败清单，就是评测集的原材料。

```json
{"id": "c07", "invoice": "data/raw/inv_07.pdf", "po": "PO-004512", "expect": "mismatch", "must_mention": "quantity"}
```

Husain 建议第一层用快速、低成本的断言，也就是你在 pytest 里本来就会写的那种。代码能检查的，交给代码；只有代码查不了的，才让模型来评分。

```python
# evals/test_basic.py — 示意
@pytest.mark.parametrize("case", load_cases("evals/cases.jsonl"))
def test_verdict(case):
    out = run_case(case)
    assert out["verdict"] == case["expect"]
    assert case["must_mention"] in out["reason"]
```

```bash
pytest evals/ -q
```

据 Anthropic 介绍，Agent 评测通常组合三类评分器：基于代码的、基于模型的和人工的。对作品集仓库而言，代码这一层要扎实。再加一个基于模型的评分器，判断 Agent 给出的理由是否成立，并在 README 中写清哪些部分是人工评分的。

OpenAI 把这种做法称为评测驱动开发（eval-driven development）：尽早评测，经常评测，为每个阶段编写测试。

**要点:** Agent 答对一次还谈不上可信；每次都答对，才是客户需要的。

放在 README 最上方的数字应该是 pass^k。Anthropic 区分了 pass@k 和 pass^k：pass^k 是 k 次尝试全部成功的概率。本文开头的计算，正是单次正确率 80% 的 Agent 在各次运行相互独立时的 pass^3：51.2%。

设想一位会计每天用这个 Agent 三次。某一天三次全对的概率只比一半略高，也就是说，大约每隔一天就会碰上一次错误。

用例集还小的时候，解读这个数字要谨慎。只有 20 个用例时，一个用例结果翻转，pass^k 就会变动 5 个百分点；k 越小，单次运行的运气越容易让数字显得好看。

实践中，每个用例至少跑三次，再把整套评测重跑一遍，看数字是否波动，并且始终在结果旁注明用例数量和 k 值。

评测的最后一步最常被跳过。Anthropic 强调，不阅读多次尝试的运行记录和分数，就无法知道评分器打分是否准确。随机挑十个判为“通过”的运行，重新读一遍。过于宽松的评分器，比能力弱的 Agent 更危险。

**检查：**`pytest` 能跑完整套用例，但不必全部通过。用例来自真实失败，部分保持红色很正常，这些红色用例就是你的待办清单。README 应写明通过数与总数，并附一张按失败类别统计的 pass^3 表格。

## 第 5 步：为不运行代码的人准备 README 和视频

GitHub Docs 列出了 README 应回答的问题，第一个就是项目做什么。对 FDE 仓库来说，README 应该读起来像一篇简短的案例分析。

内容应包括：假想客户的问题，MVP 范围以及你刻意舍弃的部分，含 pass^k 的评测结果，仍未解决的三个失败，以及如果再给两周你会如何处理。

“遗留失败”这一节值得用心写。它让读者看到，你能衡量自己的系统，也能坦诚面对它的局限。

3 分钟视频要做给经理看，而不是给工程师看。一种分配方式：30 秒讲清问题，90 秒用 `data/raw/` 里一张真实的脏发票运行 Agent，45 秒打开评测结果并读出 pass^k，最后 15 秒讲一个尚未修复的失败。不要录自己敲代码的画面。

## 常见错误

最常见的错误，是还没弄清需求就选了重量级框架，结果提示词被埋在五层类下面。其次是用自己生成的干净数据，评测一片绿，却什么也证明不了。第三是只报告最好的一次运行，而不报告 pass^k。

## 这项能力如何迁移到客户项目？

这五步不只适用于作品集，也是你在客户部署中必需的习惯，而仓库就是你最先练习的地方。

简历上别写笼统的“开发了 AI Agent”，而是写一句带数字的话，例如“基于真实失败构建了 40 个评测用例，将 pass^3 从 X 提升到 Y”，其中 X 和 Y 来自你自己的仓库。如果岗位描述提到“evaluation”或“reliability”，投递时附上这个仓库的链接。

让仓库提前回答每个客户迟早会问的问题：Agent 在哪里失败，失败得有多频繁？

**本周动手试试:**

- 选一个企业场景，只用一句话描述 MVP，并收集 10 个脏数据文件作为输入
- 在这些数据上把 Agent 跑 20 次，阅读日志，把发现的每个失败写成一个 pytest 测试
- 每个用例跑 3 次，在 README 中记录 pass^3，以及 3 个尚未修复的失败

## 信源

- [Building effective agents](https://www.anthropic.com/research/building-effective-agents)

- [Demystifying evals for AI agents](https://anthropic.com/engineering/demystifying-evals-for-ai-agents)

- [Your AI Product Needs Evals](https://hamel.dev/blog/posts/evals/)

- [Evaluation best practices (OpenAI API docs)](https://developers.openai.com/api/docs/guides/evaluation-best-practices)

- [How to build a forward deployed engineer portfolio](https://fde.academy/blog/how-to-build-a-forward-deployed-engineer-portfolio)

- [About READMEs - GitHub Docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)
