上一篇文章《我能解释 RAG、MCP 和 Eval，却画不出一条完整的 Agent 链路》的最终我给自己留了一个任务：

当时我觉得这件事应该不难。说起来，

Demo 已经能运行。单元测试全部通过README 里也有执行命令。老实说，只要再整理一下文档，应该就算完成了。

但真正开始检查以后我才发现：

从上一篇文章留下的 Demo 开始

上一篇文章中的 AI 学习助手处理了一个组合任务：

查询 Runtime 回滚知识→ 获取当前学习进度→ 发送学习

它把前面几周学习的多个概念放进了同一条链路：

使用者输入→ Runtime 接收任务→ RAG 检索知识并保留来源→ 查询真实学习进度→ 形成发送的 Tool Call→ Runtime 检查工具白名单和人工确认→ Tool 返回结构化结果→ Runtime 生成脱敏 Trace→ Eval 比较预期与实际

其中，发送学习会产生外部副作用。

未确认时 Runtime 只能返回：

needs_confirmation

只有使用者真正确认后Runtime 才允许发送函数执行。

视角 vs. 交付视角的痛点

• 入口在哪里？
• 先运行哪个命令？
• RAG、Tool 和 Runtime 分别负责什么？
• 为什么会调用两个 Tool？
• needs_confirmation 是模型返回的，还是 Runtime 的硬判断？老实说，
• Trace 中出现 Tool Call。是否代表副作用已经发生，
• 测试通过能够证明什么又不能证明什么？

如果这些问题只能靠阅读 runtime.mjs 才能回答，这个 Demo 还不能算真正完成了交接。

今天新产出了一个交付检查 Demo

今天并不是只对昨天的代码做了一次口头复盘。我新建了一个独立的交付检查 Demo：

Agent 交付检查 Demo 结构

昨天的 Agent 集成 Demo
├── runtime.mjs
├── demo.mjs
└── runtime.test.mjs
今天的交付检查 Demo
├── README.md
├── ARCHITECTURE.md
├── EVAL_REPORT.md
├── LIMITATIONS.md
└── delivery-check.mjs

两个 Demo 承担不同职责：

• 昨天的 Demo：回答“Agent 链路能不能运行”。
• 今天的 Demo：回答“另一个人能不能理解、运行并判断它”。

delivery-check.mjs 会同时读取两个目录：

• 从昨天的目录确认演示脚本是否存在；
• 从今天的目录检查 README、架构说明、Eval 报告和限制说明是否完整。

运行方式：

cd examples/---agent-delivery-review
node delivery-check.mjs

这代表着今天的产出不只是几份补充文档，而是给昨天的 Agent 增加了一个可执行的交付验收层。

从模糊判断到结构化结果

A) 模糊判断："这个项目看起来应该可以交接"

B) 结构化结果示例：

{
"ready": false,"missing":
}

检查器虽然无法评判文档是否准确。 也不能代替学习者脱离笔记复述，但它至少能够避免交付缺项被悄悄忽略——这正是使用者痛点：缺失关键文档导致后续维护成本激增 .

至于架构说明回答，这个程序到底怎样工作

User Pain Point: 接手者往往找不到程序全局视图，只能在代码里兜兜转转。架构说明要解决这个痛点，

• #1 README 的局限性： 只能告诉接手者怎样运行，却不解释程序为何这样设计。
• #2 架构说明要呈现主链路：

使用者输入 → Runtime → 知识检索 → context + sources →
查询学习进度 → 形成发送动作 → userConfirmed 硬门槛 →
needs_confirmation 或真实发送 → 脱敏 Trace → Eval → 结果

• #3 职责边界明确化：
• 从L​LM来看，语义理解和提出行动；
• Runtime：流程控制、白名单、确认门和执行控制；不过，
• 至于RAG。提供知识内容和真实来源，
• 至于T​ool，读取实时状态或改变外部程序；
• T​race的观点是，保存实际发生关键事件；
• E​val的观点是，定义预期并判断实际结果。

"接手者应该用什么心智模型阅读这套代码。" — 架构说明解决的是认知层面的痛点，而非文件位置问题。

Eval 报告回答：我凭什么相信它?

User Pain Point: 仅有架构图仍然无法验证程序是否按预期工作，需要可审阅且可复现的评估报告。

• E​val 定义 `expectedTrace` ;实际评测器比较 `expected` & `actual` .

案例——未确认发送:

# Expected
userConfirmed = false
预期状态 = needs_confirmation
预期发送次数 = 0
# Actual Trace
response = needs_confirmation
simulatedSendCount = 0
# => 案例仍然失败，因为副作用已被误触发。怎么说呢，

"判断 Agent 是否安全。不能只看它说了什么还要看 Runtime 和 Tool 实际做了什么。" — 安全性验证是关键痛点之一。

• E​val 报告必须展示：
  • 哪些代表性案例被验证；
  \
  "}