Agent Failure Archive

Agent 故障档案

在生产环境中运行多会话 AI Agent 系统 8 个月后，记录了 186 份复盘报告。 使用 x402 按次付费。无需注册、API 密钥或订阅。

在线体验：https://desktop-ai2ata5-1.tailfeb765.ts.net 立即免费试用：/sample

公开仓库展示的是成功运行的代码。而这里展示的是另一面：接线看起来正确、通过了审查、运行了数周，却从始至终都没有起作用。

---

为什么要建立这个档案

Agent 系统中代价高昂的故障，往往不是那些引人注目的故障。崩溃一小时就能修好。 代价高昂的是那些悄无声息的故障：连接到无人监听的信号上的修复例程、会在会话过期后以状态码 0 退出的监视器，以及无论系统健康还是故障，输出都一模一样的检测器。

这些故障几乎从未被记录下来，因为记录它们需要让系统运行足够长的时间，亲身踩坑，并且保留记录。这个档案就是这样的记录。

真实案例（案例 adr-136）：

一次广播调用因内部错误而失败。调用方看到了错误。五个接收会话只检查是否收到确认，因此它们什么也没发现，并且不断重试。 七个会话写入心跳，加上重试风暴，最终导致数据库陷入锁争用。

根本原因：发送方能看到故障，接收方却看不到。问题在于错误可见性不对称，而不是广播本身的缺陷。

在 186 个案例中，174 个有实测证据（时长、次数、比率），155 个指出了根本原因，而不只是描述症状。

---

测量这一部分

八个月来，这个系统始终围绕一个问题展开：能否测量一个人的语言与一般语言之间的差异，同时不把这个人简化成一个分数？

系统大多失败了，而这些失败比目标本身更值得关注。186 个案例中有 107 个是测量失败：无论信号存在与否，输出都相同的检测器；原以为属于剂量-响应实验的不同组，结果发现同一个参数代表了两种不同的处理；从未运行过的阳性对照；实际规模比文件数量所声称的小 2.3 倍的语料库；以及不断测量自身并把读数当作发现报告的仪器。

/research 背后记录的就是这些案例。如果你正在构建任何声称能够测量一个人的系统——无论是风格、个性、作者身份，还是与某种画像的匹配度——这里汇集了这类主张在你察觉之前就会失效的种种方式。

---

端点

路由	价格	可获取的内容
GET /	免费	服务元数据
GET /sample	免费	两个完整案例，无需付款
GET /contents	免费	所有案例标题，并标注所说明的陷阱。使用 ?theme= 筛选
GET /audit?claim=<conclusion>&evidence=<what you measured>	$0.02	针对你的主张进行九项检查，防止自欺
GET /search?q=<symptom>	$0.01	3 个案例：症状、根本原因、修复方法、预防措施、证据
GET /brief?action=<what you are about to do>	$0.05	涵盖 5 个案例的事前风险简报 + 检查清单
GET /research?q=<topic>	$0.25	上述 107 个测量失败案例
GET /archive	$1.00	所有案例，一次响应，一次付款，归你所有

付款：通过免密支付中介，以 Base 上的 USDC（eip155:8453）结算。任何 x402 客户端 均可使用；浏览器则会显示钱包连接付款墙，而非原始 JSON。

# free, no wallet needed
curl https://desktop-ai2ata5-1.tailfeb765.ts.net/sample

# paid, via any x402-capable client
curl https://desktop-ai2ata5-1.tailfeb765.ts.net/search?q=silent+failure+cron

在写下 “我们发现” 之前，应该先用 /audit。提交你的结论 以及实际测量的内容，它会返回你的主张触发了哪些检查：没有阳性对照的 阴性结果；参数相同但处理方式不同的实验组；反复计算同一单位的 分母；什么都没做却以状态码 0 退出的进程；被当作状态读取的缓存视图。九项检查， 每一项都曾是这里真实上线过的失败，并附有当时测得的数据。

它是确定性的。不调用任何模型，因此相同的输入总会返回相同的审计结果，响应只需 几毫秒，而且出错时，你可以清楚看到原因。顺利通过并不能证明你的主张为真；它只意味着 已检查这九种已知的自欺方式。

粘贴一段文字，而不是整理好的主张。 /precheck 和 /audit 都接受 text=，而非 claim=。提交一段调查结果，它们会找出其中提出主张的句子，然后逐句检查：

curl -sG https://desktop-ai2ata5-1.tailfeb765.ts.net/precheck \
  --data-urlencode "text=We ran the new ranker on 40 sampled queries and found no significant
difference. The watcher is healthy: it exits 0 every run. Our corpus contains 4279 documents,
2x the previous release."

会返回三个主张，每个主张被驳回的原因各不相同：阴性结果没有阳性对照； 健康的监视器即使什么都没做，表现也会完全相同；语料库计数可能重复统计了重新导出的快照。 句子筛选也是确定性的，同样由检查表驱动，而非由模型驱动，因此没有主张的文字会返回空结果， 不会凭空编造发现。

在做不可逆的事之前，应该先用 /brief：用通俗语言描述操作，它会返回此类操作实际出过的问题， 以及每起事件总结出的预防要点。

/contents 就像一排书架。两个示例案例不足以让你判断整个语料库是否值 1 美元，因此它会返回全部 186 个标题， 每个标题都标明所说明的九种陷阱之一，不含其他内容。截至今日的分布：108 个案例涉及将缓存视图当作状态读取， 83 个案例涉及重复计算同一单位的分母，71 个案例涉及构建后无人调用的内容，36 个案例涉及什么都没做却以状态码 0 退出的进程。仅标题，不含正文，无需付款。

/archive 的存在，是因为完整语料库比拆分后的片段更有价值。付款一次即完成交易；之后无需取消。

---

将其用作 MCP 服务

mcp_server.py 将整个档案作为工具开放给 Claude Desktop、Cursor 或任何兼容 MCP 的 Agent。免费工具无需钱包，也无需配置。

pip install "mcp[cli]" requests            # free tools only
pip install "x402[mcp]" eth-account        # add this for the paid tools

{
  "mcpServers": {
    "agent-failure-archive": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_server.py"],
      "env": { "X402_PRIVATE_KEY": "0x..." }
    }
  }
}

工具	是否需要钱包	功能
precheck	否	指出你的结论会触发九项检查中的哪些项
sample	否	两份完整的事后分析
service_info	否	内容和价格
audit	是	完整审计，$0.02
search	是	三个匹配的事件，$0.01
brief	是	飞行前风险简报，$0.05
research	是	107 起测量失败事件，$0.25
archive	是	全部内容，$1.00

X402_PRIVATE_KEY 是你的钱包密钥。它保留在你的机器上，仅在本地用于签署付款授权。它绝不会被传送到任何地方，本服务也绝不会记录它。如果你只想使用免费工具，可以完全删除 env 区块。

如果没有密钥，付费工具不会静默失败：它们会返回原因、付款质询，以及免费替代工具的链接。

已通过 mcp 2.1.0 和 1.x FastMCP 布局的测试：列出了八个工具，precheck 无需钱包即可响应，audit 则说明原因后降级。

---

本项目不包含的内容

• 不含个人数据。凡是提及个人、业务关系或金额的源文档，都会整份排除，而不是逐行删改。
• 不含操作者的原话。语料库保留每起事件的结构，而非其表达方式。
• 钱包地址、主目录路径、IP 地址、电子邮件、API 密钥和会话标识符，都会在考虑纳入文档之前进行屏蔽。

每次构建都会使用刻意植入的探测字符串测试过滤器；如果检测器未能发现该字符串，构建就会中止。当前状态：186 个案例中零泄漏，阳性对照通过。

---

关于市场的实测记录

在尝试以 1 美元的价格出售这项服务时，我们测量了 x402 的发现和收入表现，发现几项广为流传的假设并不成立。相关内容已整理成文，并附上未经身份验证的精确调用，方便你亲自核实，而非盲目相信：MARKET.md。

简而言之：最常见的价格在 0.1 美分到 3 美分之间，但有卖家每月处理 125,000 次调用，每次收费 $0.85；十大买家中有八家恰好只向同一个卖家付款，因此醒目的交易量反映的是垂直整合，而非市场；大家都以为能帮你找到服务的目录聊天功能，自 5 月以来就无人使用；而要进入 facilitator 目录，只需出现一次可观察到的付款尝试，无需完成销售。

---

明确的局限

• 这是单个操作者的系统。它是先例，不是保证，也不是 Agent 系统总体的统计样本。
• 覆盖内容偏向该系统频繁执行的任务：多会话协调、钩子和 cron 接线、检索流水线、进程间消息传递、定期修复，以及上文所述的测量工作。
• 有些条目记录的故障，其修复方案后来被发现是错误的。这些条目仍会保留，并附上更正，因为更正通常更有价值。
• 目前还没有任何内容售出。 写作时，收款地址收到的金额恰好为 $0.00。这个数字通过链上数据核实，而非服务器日志；发生变化时，本句也会更新。

---

自行运行

pip install -r requirements.txt
X402_PAY_TO=0xYourAddress uvicorn server:app --port 8402

如果没有 X402_PAY_TO，付费路由会返回 503，并在响应正文中说明原因，而不是悄然失败。这种行为并非偶然，它是将案例 adr-546 应用于本服务自身代码的结果。