---
tags: [AI, 工程化, 项目模板]
阶段: 08-Agent与工程化
难度: ★★★
created: 2026-10-18
related: "[[Agent工作流与编排]], [[成本-延迟-质量权衡]], [[模型评估矩阵]], [[Harness与Loop工程]]"
---

# 端到端项目模板

## 定义

**端到端项目模板**（end-to-end project template）指把模型能力转换为可交付系统的一组固定结构：六层的职责边界、一份可直接复制的仓库布局、一组带类型校验的配置契约、一个带停止条件与预算上限的执行循环、一套离线与在线评估入口，以及部署、观测、回滚的最低要求。

逐个术语给出定义。

| 术语 | 含义 |
|---|---|
| 用户故事 | 以「角色—动作—目的」描述的一项功能，可拆为可测的验收条件 |
| 验收标准 | 判定该项功能通过的客观条件，取值可来自指标阈值或样例通过与否 |
| 失败定义 | 明确列出哪些输出算失败，包括拒答错误、超时、无引用、引用与答案不一致 |
| SLO | 服务级目标，如「95% 的请求在 8 秒内返回」，是发布门槛而非努力方向 |
| trace id | 一次请求的全局标识，贯穿接口层、编排层、模型层、工具层与观测层 |
| 黄金集 | 带标注的离线评测集，用于每次改动后的回归判定 |
| 预算上限 | 单次请求允许消耗的最大金额，达到即终止循环并降级 |
| 回滚 | 把镜像与配置恢复到上一个通过验收的版本，且不依赖数据迁移 |
| 限流 | 按令牌桶或滑动窗口限制单位时间的请求数，保护下游与成本 |
| 人工审批 | 高风险动作执行前必须由人确认的检查点 |

六个层的名称与职责：接口层负责协议、鉴权与限流；编排层负责循环、状态与停止条件；模型层负责模型适配、重试与超时；工具层负责工具注册、参数校验与执行；数据层负责索引、文档版本与检索；观测层负责日志、指标、追踪与告警。

## 为什么重要

一个能演示的系统与一个能交付的系统之间，差的是可重复、可度量、可回滚这三件事，而不是模型能力。

没有评估就无法判断改动是改进还是退化。提示词改一个字、检索多取两条、温度从 0 调到 0.2，这些改动在少量样例上表现为随机波动，只有固定黄金集与阈值才能给出判定。没有评估时，团队的决策依据是「看起来更好了」，这类判断在小样本上不可靠：3 条用例全部通过时，真实成功率的 95% 置信区间下界约为 0.44（见第 1 节的 Wilson 区间），即完全无法排除「一半以上请求失败」的情形。

没有 trace id 就无法定位单次失败。用户报告「答错了」，日志里只有一条最终回答时，无法判断错在检索没召回、工具参数非法、模型忽略引用还是超时降级。把每次循环的步骤、工具调用、token 数与成本写入结构化日志，并共享同一个 trace id，才能把一次失败还原为一条可复现的调用链。

没有预算上限时，一次循环可能耗尽整月配额。循环的上界是最大步数与单步最大 token 的乘积，若两者都没有约束，一次异常输入可以触发数十次模型调用。预算上限把成本从「事后统计」变成「运行期硬约束」。

没有回滚时，一次坏发布就是事故。回滚的前提是镜像带版本标签、配置独立于镜像、数据层变更向后兼容；三者缺一，回滚时间就从分钟级变成小时级。

在本库中的位置：本篇承接 [[Agent工作流与编排]] 的循环语义、[[MCP协议]] 的工具契约与 [[Harness与Loop工程]] 的执行边界，把 [[模型推理优化]] 与 [[分布式训练与部署]] 的部署约束落成一份可执行的清单，并用 [[成本-延迟-质量权衡]] 的三角关系确定参数取值，用 [[模型评估矩阵]] 选定评测维度。它要回答的问题是：一个人或一个小团队，从零开始交付一个 Agent 系统时，哪些结构必须先建、每个结构的验收条件是什么、哪些错误是可以在流程上被消除的。

## 原理与推导

### 1 需求与验收：从用户故事到可测指标

用户故事写成一句话：作为 `角色`，我要 `动作`，以便 `目的`。每条故事拆出 2 至 4 条验收条件，每条条件必须是可判定的，即给定一个输入，能输出通过或不通过。

文档问答 Agent 的验收表如下。

| 编号 | 验收条件 | 指标 | 阈值 | 判定方式 |
|---|---|---|---|---|
| A1 | 答案包含正确要点 | 要点命中率 | 不低于 0.90 | 黄金集 200 条，人工标注要点 |
| A2 | 答案给出可核对的引用 | 引用正确率 | 不低于 0.90 | 引用 doc id 属于标注集合 |
| A3 | 无依据时拒答 | 拒答正确率 | 不低于 0.85 | 30 条无答案样本应为拒答 |
| A4 | 端到端延迟 | P95 | 低于 8 秒 | 压测 1000 次请求 |
| A5 | 单次成本 | 均值 | 低于 0.005 美元 | 日志中的成本字段 |
| A6 | 失败可定位 | trace 完整率 | 100% | 抽查 100 条日志，字段齐全 |

失败定义必须显式列出，否则验收会退化为「看起来对」：答案缺少标注要点、引用 id 不在检索结果内、引用与答案矛盾、超过 8 秒、触发预算上限后未降级、返回空字符串、把用户输入原样复述。以上任一项出现即计为失败，从成功率中扣除。

成功率是二项比例，小样本必须给区间。设 $n$ 条用例中通过 $k$ 条，$\hat p=k/n$，Wilson 区间的中心与半宽为

$$
c=\frac{\hat p+z^2/(2n)}{1+z^2/n},\qquad
h=\frac{z\sqrt{\hat p(1-\hat p)/n+z^2/(4n^2)}}{1+z^2/n},
$$

区间为 $[c-h,\ c+h]$，$z=1.96$ 对应 95% 置信水平。代入两种样本量：

- $n=3$、$k=3$：$\hat p=1$，区间 $[0.438,\ 1.000]$。全部通过仍无法排除四成以上的失败率。
- $n=200$、$k=182$：$\hat p=0.91$，区间 $[0.870,\ 0.950]$。半宽约 4 个百分点。

由此得到样本量的下限：要在 $\pm5$ 个百分点内判断成功率，$n$ 需要 150 至 400 条；要分辨 2 个百分点的差异，$n$ 需要上千条。黄金集取 200 条是成本与分辨率的折中点。

### 2 架构分层与依赖方向

分层的作用是把变更隔离开。提示词改动只触及编排层，模型更换只触及模型层，工具新增只触及工具层，索引重建只触及数据层。任何跨层的直接调用都会破坏这一性质。

| 层 | 职责 | 输入 | 输出 | 典型失败 |
|---|---|---|---|---|
| 接口层 | 协议、鉴权、限流、幂等 | HTTP 请求、身份 | 规范化请求、trace id | 重复提交、未限流导致下游过载 |
| 编排层 | 循环、状态机、停止条件、预算 | 规范化请求 | 最终答案或降级结果 | 死循环、超预算、状态丢失 |
| 模型层 | 提供方适配、重试、超时、用量统计 | 消息列表、工具描述 | 文本或工具调用、用量 | 重试风暴、超时未传递 |
| 工具层 | 注册、参数校验、权限、执行 | 工具名、参数 | 结构化结果或错误码 | 参数未校验、异常吞掉 |
| 数据层 | 索引、文档版本、检索 | 查询、过滤条件 | 片段与 doc id | 版本错配、召回为空 |
| 观测层 | 日志、指标、追踪、告警 | 各层事件 | 可检索的记录与告警 | 缺 trace id、采样不全 |

依赖方向单向向下：接口层依赖编排层，编排层依赖模型层与工具层，工具层依赖数据层，观测层被所有层调用但不反向依赖任何业务层。反向依赖的后果是测试困难：若工具层直接读配置并调用接口层，则工具无法在评测脚本中单独实例化。

```mermaid
flowchart TB
    subgraph API[接口层]
        A1[HTTP 路由] --> A2[鉴权与限流]
    end
    subgraph ORC[编排层]
        B1[agent loop] --> B2[停止条件与预算]
        B2 --> B3[提示词组装]
    end
    subgraph MOD[模型层]
        C1[provider 适配] --> C2[重试与超时]
    end
    subgraph TOOL[工具层]
        D1[工具注册表] --> D2[参数校验]
        D2 --> D3[search_docs]
        D2 --> D4[read_doc]
    end
    subgraph DATA[数据层]
        E1[向量索引] --> E2[文档版本]
    end
    subgraph OBS[观测层]
        F1[结构化日志] --> F2[指标与追踪]
        F2 --> F3[告警]
    end
    A2 --> B1
    B1 --> C1
    B1 --> D1
    D3 --> E1
    D4 --> E1
    B2 --> F1
    C2 --> F1
    D2 --> F1
```

### 3 仓库布局与配置契约

布局按层切分目录，而不是按文件类型切分。按层切分时，新增一个工具只需要改 `tools/`，新增一个指标只需要改 `obs/`；按类型切分（`models/`、`utils/`、`services/`）会把同一条调用链拆散在四个目录里。

配置遵循三层覆盖：`configs/default.yaml` 提供全部默认值，`configs/{env}.yaml` 覆盖环境差异，环境变量覆盖密钥与运行期参数。优先级为 环境变量 > 环境配置 > 默认配置。启动时用带类型的 schema 校验，失败即退出，并把非敏感字段打印为摘要写入启动日志。

配置项分四类，取值必须显式声明。

| 类别 | 配置项 | 取值示例 | 说明 |
|---|---|---|---|
| 模型 | `model.id`、`model.temperature`、`model.max_output_tokens` | `qwen3-32b-instruct`、`0.0`、`800` | 温度取 0 保证可复现 |
| 循环 | `agent.max_steps`、`agent.budget_usd` | `6`、`0.02` | 两者共同构成成本上界 |
| 工具 | `tools.timeout_s`、`tools.allow_write` | `3`、`false` | 写操作默认关闭 |
| 观测 | `obs.log_level`、`obs.sample_rate` | `info`、`1.0` | 首版全量采样 |

密钥三条规则：不入库、不写进镜像、不打印。代码只从环境变量读取，`.env.example` 只保留键名与占位值，CI 用 `gitleaks` 一类工具扫描提交内容。

### 4 Agent 循环的五条不变量

循环是系统中最容易出错的部分，因为它的状态分布在多轮之间。以下五条不变量必须在实现中显式保证，任一条缺失都会产生难以复现的故障。

1. 每轮有唯一标识。`trace_id` 在一次请求内不变，`step` 从 1 递增。没有 step 时，日志无法排序，也无法判断是否死循环。
2. 工具参数先校验后执行。模型产出的参数是待验证的输入，类型、枚举、必填字段、取值范围都要检查；校验失败作为工具结果回填，让模型自行修正。
3. 每步累计成本，超预算立即终止。累计值 $C_t=\sum_{i=1}^{t}(n_i^{\text{in}}p_{\text{in}}+n_i^{\text{out}}p_{\text{out}})$，$p$ 为单位 token 价格。终止后返回降级结果并标记 `stop=budget`。
4. 终止条件完备。至少包含：最终答案、步数上限、预算上限、墙钟超时、不可恢复错误。缺少任一条都可能挂死。
5. 工具输出按数据对待。工具返回的文本可能含指令性语句，这些语句不具有指令效力，不得进入系统提示，也不得改变权限判定。

循环的伪代码如下，停止原因的取值是有限的枚举，便于统计。

```text
输入：question, 预算 B, 步数上限 S
trace := 新标识(); messages := [系统提示, 用户消息]; spent := 0
for step in 1..S:
    out := 模型层.complete(messages, 工具描述)
    spent += 计价(out.用量)
    写日志(trace, step, 模型, out.类型, spent)
    if spent > B:        return 降级("预算耗尽", stop=budget)
    if out 是最终答案:    return 答案(out, stop=final)
    result := 工具层.call(out.名称, out.参数)
    写日志(trace, step, 工具, result.是否成功, result.错误码)
    messages += 工具消息(result)
return 降级("步数上限", stop=max_steps)
```

停止原因的分布本身就是指标：`budget` 与 `max_steps` 占比上升，说明提示词或工具设计有问题，而不是模型能力不足。

### 5 工具注册与契约

工具是模型与外部世界的唯一通道，其契约必须包含名称、描述、参数模式、权限与超时。注册表的作用是让契约成为代码的一部分，而不是散落在提示词里。

| 字段 | 要求 | 缺失后果 |
|---|---|---|
| `name` | 全局唯一，动词开头 | 模型无法稳定选择工具 |
| `description` | 说明何时使用、返回什么、失败的返回形态 | 模型误用或重复调用 |
| `input_schema` | 根节点为 `object`，逐字段声明类型与枚举 | 参数类型错误进入执行阶段 |
| `timeout_s` | 必须小于循环的单步预算 | 单次工具卡死拖垮整个请求 |
| `allow_write` | 写操作默认关闭，需显式开启并进入审批 | 越权修改数据 |

描述文本是模型选择工具的唯一依据，必须写清「什么时候用这个工具」而非「这个工具是什么」。只写「检索文档」时，模型容易在已有答案的情况下重复检索；写成「当需要核对外部事实或用户询问文档内容时调用，返回文档 id 与片段，无结果时返回空列表」，调用行为会明显稳定。

### 6 数据与提示词版本管理

提示词是代码，必须有版本号、变更记录与回滚能力。实现方式是把提示词放在 `prompts/` 下，文件名为 `名字.v版本.md`，`prompts/manifest.json` 记录当前生效版本与内容哈希；启动时校验哈希，不匹配则拒绝启动。

版本信息必须进入每条日志与每次评测结果：`model_id`、`prompt_version`、`dataset_version`、`config_hash`。缺少任一项时，两次评测的差异无法归因，回滚也无法确定回到哪个组合。

数据侧同理：文档入库时记录 `doc_id`、`source_id`、`updated_at` 与内容哈希；索引带版本号，检索结果返回索引版本。文档更新后重建索引时，旧版本保留一个周期，使正在进行的请求不受影响。

### 7 评估：离线集、在线指标与回归测试

评估分三层，用途不同，不可互相替代。

| 层 | 数据 | 指标 | 频率 | 用途 |
|---|---|---|---|---|
| 离线黄金集 | 200 条带标注 | 要点命中、引用正确、拒答正确 | 每次提交 | 判定改动是否退化 |
| 离线压力 | 1000 条合成请求 | P50、P95、错误率、单请求成本 | 每次发布 | 判定容量与成本 |
| 在线 | 真实流量 | 成功率、兜底率、点踩率、P95 | 持续 | 判定真实表现 |

回归判定用相对阈值而非绝对阈值，因为基线会随模型与数据变化而移动。

| 检查 | 通过条件 | 失败处理 |
|---|---|---|
| 要点命中率 | 不低于基线 −1 个百分点 | 阻止合并 |
| 引用正确率 | 不低于 0.90 | 阻止合并 |
| P95 延迟 | 不高于基线 × 1.15 | 阻止发布 |
| 单请求成本 | 不高于基线 × 1.10 | 阻止发布 |
| 单元测试 | 全部通过，含预算终止与注册表用例 | 阻止合并 |

评测脚本本身也要测试：用一组已知答案的假数据跑通评测入口，确认指标计算正确。评测脚本出错的表现通常是「分数突然变高」，这类错误比模型退化更难发现。

### 8 部署：容器、健康检查、限流、回滚

部署单元的粒度是镜像加配置。镜像不带密钥、不带数据，配置通过环境变量注入。

健康检查分两个端点。`/healthz` 只检查进程存活，返回 200 即通过，用于容器重启判定；`/readyz` 检查依赖可用性（模型端点可达、索引可读），不通过时从负载均衡摘除但不重启容器。两者混用会导致依赖抖动时容器被反复重启。

限流用令牌桶。桶容量 $b$、补充速率 $r$（每秒），当前令牌数

$$
\text{tok}_{t+\Delta t}=\min\bigl(b,\ \text{tok}_t+r\,\Delta t\bigr),
$$

请求到达时若 $\text{tok}\ge1$ 则扣减并放行，否则返回 429 并带 `Retry-After`。取值由容量决定：文档问答 Agent 的日均 1 万请求折合平均 0.116 QPS，峰值按 5 倍计为 0.58 QPS，故取 $r=2$、$b=10$ 留出余量。

灰度与回滚流程固定为三步。

| 阶段 | 流量 | 观察窗口 | 通过条件 | 失败动作 |
|---|---|---|---|---|
| 金丝雀 | 5% | 30 分钟 | 错误率不高于基线 +1pp，P95 不高于 8 秒 | 立即回滚 |
| 分批 | 25% | 2 小时 | 成本不高于预算，兜底率不高于 5%（告警线为 8%，见第 9 节） | 回滚并保留现场 |
| 全量 | 100% | 24 小时 | 全部 SLO 满足 | 回滚 |

回滚操作只允许两个动作：把镜像标签指回上一个版本，把配置版本指回上一个版本。因此数据层变更必须向后兼容至少一个版本，例如新增字段而非改名。

### 9 观测：日志、追踪、告警

日志是结构化 JSON，一行一个事件，字段固定。

| 字段 | 类型 | 说明 |
|---|---|---|
| `ts` | ISO 8601 | 事件时间，毫秒精度 |
| `trace_id` | 字符串 | 请求级唯一标识 |
| `step` | 整数 | 循环轮次，从 1 开始 |
| `event` | 枚举 | `model`、`tool`、`stop`、`error` |
| `tool` | 字符串 | 工具名，仅 `event=tool` 时有值 |
| `tokens_in`、`tokens_out` | 整数 | 本次调用的用量 |
| `cost_usd` | 浮点 | 累计成本，保留 6 位 |
| `latency_ms` | 整数 | 本次调用的耗时 |
| `status` | 枚举 | `ok`、`invalid_args`、`timeout`、`denied` |

告警阈值必须能在事故前触发，因此取相对基线与绝对上限的组合。

| 告警 | 条件 | 级别 | 处置 |
|---|---|---|---|
| 错误率上升 | 5 分钟内 5xx 比例超过 5% | P1 | 检查模型端点与索引，必要时回滚 |
| 延迟劣化 | P95 超过 10 秒持续 10 分钟 | P2 | 检查检索延迟与模型排队 |
| 成本异常 | 单请求成本超过 0.5 美元，或日预算消耗超过 80% | P2 | 检查循环步数与输入长度 |
| 兜底率上升 | 人工兜底率超过 8% 持续 1 小时 | P2 | 抽样检查失败样本 |
| 质量下降 | 每日 1% 抽样人工评分低于 3.5/5 | P2 | 复核提示词与索引版本 |

### 10 安全：权限、输入过滤、人工审批

权限按最小必要授予。工具分只读与可写两类，可写工具默认关闭；模型端点使用独立的密钥与配额，避免与其他服务共享；数据层对文档做来源级权限过滤，检索时在索引侧过滤而非在结果侧过滤，避免越权内容进入上下文。

输入过滤与输出校验分工明确：输入侧限制长度、块数与字符集，识别明显的注入模式；输出侧校验引用必须来自本次检索结果，答案中的数字与日期必须能在引用片段中找到依据。

| 风险 | 控制 | 检查点 |
|---|---|---|
| 越权读取文档 | 索引侧按来源过滤 | 检索返回前 |
| 提示注入 | 工具输出按数据处理，不进入系统提示 | 消息组装时 |
| 越权写操作 | 写工具默认关闭，需审批 | 工具执行前 |
| 密钥泄漏 | 只从环境变量读取，提交扫描 | CI |
| 数据外泄 | 输入中的敏感字段脱敏后再送模型 | 编排层入模前 |
| 成本攻击 | 单请求预算上限与租户级配额 | 每步累加时 |

人工审批适用于三类动作：写外部系统、发送对外内容、金额或权限变更。审批不是把请求阻塞在循环里，而是把动作转为待办并返回中间状态，由人确认后从检查点继续。

### 11 成本预算与容量

单请求成本由调用次数与 token 数决定。文档问答 Agent 每次请求 3 次模型调用，输入合计约 4200 token、输出合计约 450 token，按输入 0.5 美元/百万 token、输出 1.5 美元/百万 token 计：

$$
C=4200\times\frac{0.5}{10^{6}}+450\times\frac{1.5}{10^{6}}=0.0021+0.000675\approx0.0028\ \text{美元}.
$$

按日均 1 万请求、每月 30 天，月成本结构如下。

| 项目 | 用量 | 单价 | 月成本（美元） | 占比 |
|---|---|---|---|---|
| 模型调用 | 30 万次请求 | 0.0028 美元/次 | 833 | 13.4% |
| 人工兜底 | 9000 次（3%） | 0.60 美元/次 | 5400 | 86.6% |
| 索引重建 | 4 次 | 0.30 美元/次 | 1.2 | 0.02% |
| 日志与追踪存储 | 约 2.4 GB | 按量 | 1 | 0.02% |
| 合计 | | | 6235 | 100% |

这张表改变优化顺序：模型成本只占一成，兜底成本占八成以上，因此降低兜底率是最大的成本杠杆，而不是压缩 token。兜底率从 3% 降到 2% 每月节省 1800 美元，而把输入 token 压缩 30% 只节省 250 美元。同时可加缓存：相同问题命中缓存时直接返回，按 35% 命中率可再省约 291 美元。

容量按峰值而非均值规划。QPS 峰值 0.58 时，单实例（4 并发、单请求 4.2 秒）可承载约 0.95 QPS，故两实例即可满足并留出故障余量。

### 12 里程碑与交付清单

| 里程碑 | 交付物 | 验收 | 人日 |
|---|---|---|---|
| M0 需求与验收 | 用户故事、验收表、失败定义 | 验收条件全部可判定 | 3 |
| M1 骨架与工具 | 六层目录、注册表、循环、预算 | 单请求 trace 完整，预算可终止 | 5 |
| M2 评估与基线 | 黄金集 200 条、评测脚本、基线记录 | 基线可复现，区间已计算 | 4 |
| M3 部署与观测 | 镜像、健康检查、限流、告警 | 金丝雀通过，告警可触发 | 4 |
| M4 灰度与交付 | 运行手册、回滚演练、交接文档 | 回滚演练在 5 分钟内完成 | 3 |

交付清单：可构建的镜像与版本标签、配置 schema 与样例、黄金集与评测报告、告警规则与运行手册、回滚演练记录、成本预算表、已知限制清单。缺任一项即视为未交付，因为缺项会在事故时暴露为不可操作。

## 关键直觉

> [!tip] 模板的作用是把「一次成功的演示」转换为「可重复的流程」：凡是不能被日志记录、不能被黄金集复现、不能在一分钟内回滚的环节，都不算已交付。这一判断与第 2 节的分层、第 4 节的不变量、第 7 节的回归门槛是同一件事的三个侧面：分层保证变更可隔离，不变量保证运行可终止，回归门槛保证改动可判定。三者的共同前提是同一份结构化日志与同一套版本标识，因此观测层不是附属设施，而是其他五项能力的证据来源。

## 例子与代码

### 例 1：可直接复制的仓库布局

```text
docqa-agent/
├── README.md
├── pyproject.toml
├── Makefile                      # make eval / make serve / make gate
├── Dockerfile
├── .env.example                  # 只有键名与占位值
├── configs/
│   ├── default.yaml              # 全部默认值
│   ├── staging.yaml
│   ├── prod.yaml
│   └── schema.py                 # 启动时校验，失败即退出
├── prompts/
│   ├── system.v3.md
│   └── manifest.json             # 当前版本与内容哈希
├── src/docqa/
│   ├── api.py                    # 接口层：路由、鉴权、限流、幂等
│   ├── orchestrator.py           # 编排层：循环、停止条件、预算
│   ├── models.py                 # 模型层：适配、重试、超时、用量
│   ├── tools/
│   │   ├── registry.py           # 注册表、参数校验、权限
│   │   └── docs.py               # search_docs / read_doc / cite
│   ├── data/
│   │   ├── index.py              # 向量索引与文档版本
│   │   └── ingest.py             # 入库、切分、去重
│   ├── obs/
│   │   ├── logging.py            # 结构化日志与 trace id
│   │   └── metrics.py            # 指标、告警阈值
│   └── eval/
│       ├── run_eval.py           # 离线评测入口
│       ├── gate.py               # 与基线比较，输出通过或拒绝
│       ├── goldenset.jsonl       # 200 条标注
│       └── judge.py              # 要点匹配与引用校验
├── tests/
│   ├── test_registry.py          # 参数校验、重复注册
│   ├── test_loop_budget.py       # 预算终止、步数终止
│   └── test_eval_metrics.py      # 指标计算正确性
└── ops/
    ├── alerts.yaml
    └── runbook.md                # 回滚、降级、扩容的具体命令
```

布局有两条规则：一条调用链上的代码跨不多于两个目录；测试文件与被测模块同名。前一条保证改动范围可预测，后一条保证新增模块时测试位置无需讨论。

### 例 2：可运行的骨架（工具注册、循环、评测入口）

下面的脚本是上述布局的最小实现，纯 Python、无第三方依赖，直接运行会打印一条完整 trace 与一次离线评测结果。它把注册表、参数校验、循环、预算、日志与评测串成一条链路，替换其中的 `ScriptedModel` 即为真实模型调用。

```python
# docqa_skeleton.py —— 纯 Python 3.10+，无第三方依赖，直接可运行
# 覆盖：工具注册与参数校验、带 trace id 与预算上限的 agent loop、离线评测入口
from __future__ import annotations

import json
import time
import uuid
from dataclasses import dataclass
from typing import Any, Callable

PRICE_IN, PRICE_OUT = 0.5 / 1e6, 1.5 / 1e6          # 美元/token
MAX_STEPS, BUDGET_USD = 6, 0.02
QUIET = False

DOCS = {
    "D1": "退款政策：签收后 7 天内可无理由退货，退货运费由买家承担。",
    "D2": "发票：订单完成后 48 小时内可申请电子发票，逾期需走人工补开。",
    "D3": "保修：整机保修 12 个月，电池保修 6 个月，人为损坏不在保修范围。",
}


@dataclass
class ToolSpec:
    name: str
    description: str
    schema: dict
    fn: Callable[..., Any]


@dataclass
class ToolResult:
    ok: bool
    content: Any = None
    error: str | None = None


class ToolRegistry:
    def __init__(self) -> None:
        self._tools: dict[str, ToolSpec] = {}

    def register(self, spec: ToolSpec) -> None:
        if spec.name in self._tools:
            raise ValueError(f"工具重复注册: {spec.name}")
        self._tools[spec.name] = spec

    def describe(self) -> list[dict]:
        return [{"name": t.name, "description": t.description,
                 "input_schema": t.schema} for t in self._tools.values()]

    def call(self, name: str, args: dict) -> ToolResult:
        spec = self._tools.get(name)
        if spec is None:
            return ToolResult(False, None, f"未知工具 {name}")
        err = validate(spec.schema, args)
        if err:
            return ToolResult(False, None, err)
        try:
            return ToolResult(True, spec.fn(**args))
        except Exception as exc:                      # 工具异常必须回填，不得中断循环
            return ToolResult(False, None, f"{type(exc).__name__}: {exc}")


def validate(schema: dict, args: dict) -> str | None:
    """最小 JSON Schema 校验：required、type、enum。真实项目用 jsonschema 库。"""
    py = {"string": str, "integer": int, "number": (int, float),
          "boolean": bool, "array": list, "object": dict}
    for key in schema.get("required", []):
        if key not in args:
            return f"缺少必填字段 {key}"
    for key, spec in schema.get("properties", {}).items():
        if key not in args:
            continue
        if spec.get("type") in py and not isinstance(args[key], py[spec["type"]]):
            return f"{key} 类型应为 {spec['type']}"
        if "enum" in spec and args[key] not in spec["enum"]:
            return f"{key} 不在枚举 {spec['enum']} 内"
    return None


def search_docs(query: str, top_k: int) -> list[dict]:
    """按字符重合度打分的检索替身；真实项目替换为向量索引。"""
    scored = [(sum(ch in text for ch in set(query)), doc_id)
              for doc_id, text in DOCS.items()]
    scored = [pair for pair in scored if pair[0] > 0]
    scored.sort(reverse=True)
    return [{"doc_id": doc_id, "snippet": DOCS[doc_id][:24]}
            for _, doc_id in scored[:top_k]]


REGISTRY = ToolRegistry()
REGISTRY.register(ToolSpec(
    "search_docs", "按关键词检索文档，返回文档 id 与片段",
    {"type": "object", "required": ["query", "top_k"],
     "properties": {"query": {"type": "string"},
                    "top_k": {"type": "integer", "enum": [1, 3, 5]}}},
    search_docs))
REGISTRY.register(ToolSpec(
    "read_doc", "读取指定文档的全文",
    {"type": "object", "required": ["doc_id"],
     "properties": {"doc_id": {"type": "string"}}},
    lambda doc_id: DOCS[doc_id]))
REGISTRY.register(ToolSpec(
    "cite", "生成引用标记，只允许引用已读取的文档",
    {"type": "object", "required": ["doc_id"],
     "properties": {"doc_id": {"type": "string"}}},
    lambda doc_id: f"[doc:{doc_id}]"))


class ScriptedModel:
    """离线替身：按固定策略发工具调用，用于在没有 API 时验证循环、预算与日志。"""

    def complete(self, messages: list[dict], tools: list[dict]) -> dict:
        tool_msgs = [m for m in messages if m["role"] == "tool"]
        question = next(m["content"] for m in messages if m["role"] == "user")
        if not tool_msgs:
            return {"kind": "tool_call", "name": "search_docs",
                    "arguments": {"query": question, "top_k": 3}, "usage": (520, 36)}
        last = tool_msgs[-1]
        if last["name"] == "search_docs":
            if not last["payload"]:
                return {"kind": "final", "text": "检索无结果，无法回答。",
                        "usage": (700, 20)}
            return {"kind": "tool_call", "name": "read_doc",
                    "arguments": {"doc_id": last["payload"][0]["doc_id"]},
                    "usage": (640, 30)}
        if last["name"] == "read_doc":
            return {"kind": "tool_call", "name": "cite",
                    "arguments": {"doc_id": last["arguments"]["doc_id"]},
                    "usage": (760, 28)}
        text = next(m["payload"] for m in reversed(tool_msgs)
                    if m["name"] == "read_doc")
        return {"kind": "final", "text": f"依据文档：{text} 引用 {last['payload']}",
                "usage": (980, 120)}


def cost(usage: tuple[int, int]) -> float:
    return usage[0] * PRICE_IN + usage[1] * PRICE_OUT


def log(**fields: Any) -> None:
    if not QUIET:
        print(json.dumps(fields, ensure_ascii=False))


def run_agent(question: str, model: ScriptedModel, registry: ToolRegistry,
              max_steps: int = MAX_STEPS, budget: float = BUDGET_USD) -> dict:
    trace_id = uuid.uuid4().hex[:12]
    messages = [{"role": "system", "content": "只依据检索结果回答，必须给出引用。"},
                {"role": "user", "content": question}]
    spent, t0 = 0.0, time.perf_counter()
    for step in range(1, max_steps + 1):
        out = model.complete(messages, registry.describe())
        spent += cost(out["usage"])
        log(trace_id=trace_id, step=step, event="model", kind=out["kind"],
            tokens=sum(out["usage"]), cost_usd=round(spent, 6))
        if spent > budget:
            log(trace_id=trace_id, step=step, event="stop", reason="budget_exceeded")
            return {"trace_id": trace_id, "answer": "预算已耗尽，转人工。",
                    "stop": "budget", "cost": spent, "steps": step,
                    "ms": round((time.perf_counter() - t0) * 1000)}
        if out["kind"] == "final":
            log(trace_id=trace_id, step=step, event="stop", reason="final")
            return {"trace_id": trace_id, "answer": out["text"], "stop": "final",
                    "cost": spent, "steps": step,
                    "ms": round((time.perf_counter() - t0) * 1000)}
        res = registry.call(out["name"], out["arguments"])
        log(trace_id=trace_id, step=step, event="tool", tool=out["name"],
            ok=res.ok, error=res.error)
        messages.append({"role": "tool", "name": out["name"],
                         "arguments": out["arguments"],
                         "payload": res.content if res.ok else res.error})
    return {"trace_id": trace_id, "answer": "步数上限，转人工。", "stop": "max_steps",
            "cost": spent, "steps": max_steps,
            "ms": round((time.perf_counter() - t0) * 1000)}


CASES = [
    {"q": "退货的运费由谁承担", "doc": "D1", "must": "买家"},
    {"q": "订单完成后多久能申请发票", "doc": "D2", "must": "48"},
    {"q": "电池保修多久", "doc": "D3", "must": "6 个月"},
]


def wilson(k: int, n: int, z: float = 1.96) -> tuple[float, float]:
    p = k / n
    d = 1 + z * z / n
    c = (p + z * z / (2 * n)) / d
    h = z * (p * (1 - p) / n + z * z / (4 * n * n)) ** 0.5 / d
    return c - h, c + h


def run_eval(cases: list[dict]) -> None:
    global QUIET
    QUIET = True                                 # 评测时只看汇总，不打印逐步日志
    model, passed, costs = ScriptedModel(), 0, []
    for c in cases:
        r = run_agent(c["q"], model, REGISTRY)
        answer_ok = c["must"] in r["answer"]
        cite_ok = f"[doc:{c['doc']}]" in r["answer"]
        passed += answer_ok and cite_ok
        costs.append(r["cost"])
        print(f"  用例 {c['q'][:8]}  answer_ok={answer_ok}  cite_ok={cite_ok}  "
              f"stop={r['stop']}  cost=${r['cost']:.6f}")
    lo, hi = wilson(passed, len(cases))
    print(f"\n成功率 {passed}/{len(cases)} = {passed/len(cases):.3f}  "
          f"95% Wilson 区间 [{lo:.3f}, {hi:.3f}]  "
          f"单请求均价 ${sum(costs)/len(costs):.5f}")


if __name__ == "__main__":
    print("== 单个请求的完整 trace ==")
    run_agent("退货的运费由谁承担", ScriptedModel(), REGISTRY)
    print("\n== 离线集回归 ==")
    run_eval(CASES)
```

在做什么：`ToolRegistry` 把工具的名称、描述、参数模式与实现绑在一处，`describe()` 生成的列表就是要发给模型的工具声明；`run_agent` 是第 4 节的循环，`spent` 每步累加并在超预算时立即返回，返回体带 `stop` 字段；`run_eval` 遍历黄金集，按「要点命中且引用正确」判定通过，并给出 Wilson 区间。

为什么这样写：把检索、读取、引用拆成三个工具，而不是一个「回答问题」的工具，是为了让每一步都可核验。`cite` 只能引用 `read_doc` 读过的文档，把「引用必须来自检索结果」这条规则实现为工具约束，而不是提示词里的要求。

去掉会怎样：删掉参数校验后，模型偶发的 `top_k: "3"` 会以字符串形式传入，`[:top_k]` 抛 `TypeError`，若异常未被捕获则整个请求失败；删掉预算判断后，一个循环异常的样本会连续调用直到步数上限，成本上升约 2.5 倍；删掉 `stop` 字段后，日志无法区分「正常回答」与「降级回答」，兜底率无法统计。

运行输出如下。

```text
== 单个请求的完整 trace ==
{"trace_id": "722fa1edced8", "step": 1, "event": "model", "kind": "tool_call", "tokens": 556, "cost_usd": 0.000314}
{"trace_id": "722fa1edced8", "step": 1, "event": "tool", "tool": "search_docs", "ok": true, "error": null}
{"trace_id": "722fa1edced8", "step": 2, "event": "model", "kind": "tool_call", "tokens": 670, "cost_usd": 0.000679}
{"trace_id": "722fa1edced8", "step": 2, "event": "tool", "tool": "read_doc", "ok": true, "error": null}
{"trace_id": "722fa1edced8", "step": 3, "event": "model", "kind": "tool_call", "tokens": 788, "cost_usd": 0.001101}
{"trace_id": "722fa1edced8", "step": 3, "event": "tool", "tool": "cite", "ok": true, "error": null}
{"trace_id": "722fa1edced8", "step": 4, "event": "model", "kind": "final", "tokens": 1100, "cost_usd": 0.001771}
{"trace_id": "722fa1edced8", "step": 4, "event": "stop", "reason": "final"}

== 离线集回归 ==
  用例 退货的运费由谁承  answer_ok=True  cite_ok=True  stop=final  cost=$0.001771
  用例 订单完成后多久能  answer_ok=True  cite_ok=True  stop=final  cost=$0.001771
  用例 电池保修多久  answer_ok=True  cite_ok=True  stop=final  cost=$0.001771

成功率 3/3 = 1.000  95% Wilson 区间 [0.438, 1.000]  单请求均价 $0.00177
```

读法有三条。第一，trace 的 8 行共享同一个 `trace_id`（该值每次运行随机生成，故与上文示例不同），`step` 单调递增，`cost_usd` 为累计值，任何一次失败都能定位到具体步与具体工具。第二，单请求最终成本 0.00177 美元，与第 11 节按 3 次调用估算的量级一致，说明成本模型可用。第三，3 条用例全部通过但区间下界只有 0.438，这正是第 1 节结论的直接证据：样本量不足时「全过」不构成发布依据，这也是第 7 节要求黄金集 200 条的原因。

### 例 3：配置分层与密钥注入

```yaml
# configs/default.yaml —— 全部默认值，不含任何密钥
app:
  name: docqa
  env: dev
model:
  provider: openai-compatible
  base_url: ${DOCQA_BASE_URL}
  id: qwen3-32b-instruct
  temperature: 0.0
  max_output_tokens: 800
  timeout_s: 20
  max_retries: 2
agent:
  max_steps: 6
  budget_usd: 0.02

# configs/prod.yaml —— 只覆盖环境差异
app:
  env: prod
agent:
  max_steps: 5          # 生产收紧一步，压缩尾延迟
  budget_usd: 0.015
obs:
  log_level: info
  sample_rate: 1.0
```

```python
# configs/schema.py —— 启动时校验，失败即退出
from pydantic import BaseModel, Field

class AgentCfg(BaseModel):
    max_steps: int = Field(ge=1, le=12)
    budget_usd: float = Field(gt=0, le=0.2)

class ModelCfg(BaseModel):
    id: str
    temperature: float = Field(ge=0.0, le=2.0)
    timeout_s: int = Field(ge=1, le=120)

class Cfg(BaseModel):
    agent: AgentCfg
    model: ModelCfg
```

在做什么：`default.yaml` 给出可运行的全部默认值，`prod.yaml` 只写差异，密钥以 `${VAR}` 形式引用并由启动时的环境变量替换。

为什么这样做：默认值全量存在时，新增配置项不会导致老环境启动失败；环境文件只写差异时，环境之间的漂移可被 diff 直接看出。

去掉会怎样：把密钥直接写进 `prod.yaml` 并提交，密钥进入 git 历史，轮换成本高于重写配置；没有 `schema.py` 时，`max_steps: 60` 这类笔误不会被发现，单请求成本上限被放大十倍。

### 例 4：容器与健康检查

```dockerfile
FROM python:3.12-slim AS builder
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install --no-cache-dir uv && uv sync --frozen --no-dev

FROM python:3.12-slim AS runtime
ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY src ./src
COPY prompts ./prompts
COPY configs ./configs
ENV PATH="/app/.venv/bin:$PATH"
RUN useradd -m app && chown -R app:app /app
USER app
EXPOSE 8080
HEALTHCHECK --interval=15s --timeout=3s --retries=3 \
  CMD python -c "import urllib.request as u; u.urlopen('http://127.0.0.1:8080/readyz', timeout=2)"
CMD ["uvicorn", "docqa.api:app", "--host", "0.0.0.0", "--port", "8080"]
```

在做什么：两阶段构建把编译依赖留在 builder，运行镜像只带虚拟环境与源码；`USER app` 去掉 root；`HEALTHCHECK` 打 `/readyz` 而非 `/healthz`。

为什么这样做：镜像不带密钥与数据，回滚时只需换标签；非 root 运行限制容器逃逸后的影响面。

去掉会怎样：单阶段构建把编译器与缓存带进镜像，体积增至三倍，冷启动变慢；用 `/healthz` 做健康检查时，索引短暂不可读会触发容器重启，形成重启循环。

### 例 5：CI 中的合并门槛

```yaml
name: ci
on: [pull_request]
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv sync --frozen
      - run: uv run ruff check src tests
      - run: uv run pytest -q
      - run: uv run python -m docqa.eval.run_eval --config configs/default.yaml --out current.json
      - run: uv run python -m docqa.eval.gate --baseline baseline.json --current current.json
      - run: uv run gitleaks detect --no-git -v
```

在做什么：依次执行静态检查、单元测试、离线评测、与基线比较、密钥扫描。

为什么这样做：评测与基线比较放在 CI 中，使「退化」在合并前被发现，而不是在发布后由用户报告。

去掉会怎样：没有 `gate` 步骤时，评测只作为报告存在，退化不影响合并；没有密钥扫描时，本地调试用的密钥容易随提交进入历史。

## 易错点

> [!warning] 以下六条均可在仓库、日志或发布记录中直接检查。
> 1. 无评估直接上线：改动只经过人工试用。检验方法是在 CI 中查找评测步骤与基线文件，缺一即视为无评估；小样本的「全部通过」不构成证据，3 条用例的 95% 区间下界为 0.438。
> 2. 密钥入库：密钥写在 `configs/*.yaml`、`.env` 或 notebook 中并提交。检验方法是对全历史执行密钥扫描；一旦进入历史，必须轮换而非删除。
> 3. 无回滚方案：镜像使用 `latest` 标签，或数据层变更不可逆（字段改名、类型变更）。检验方法是做一次回滚演练，记录耗时；超过 5 分钟即不合格。
> 4. 日志不含 trace id：只有最终答案与总耗时，无法定位失败步骤。检验方法是随机抽 20 条日志，看能否从其中一条还原出完整的工具调用序列。
> 5. 成本无上限：循环没有最大步数或预算判断，输入长度未截断。检验方法是构造一个会反复调用工具的输入，观察是否在有界步数内终止并返回降级结果。
> 6. 把 demo 当产品：缺少鉴权、限流、健康检查与告警，异常时无降级路径。检验方法是按第 12 节的交付清单逐项打勾，缺项即未交付。

## 关联笔记

- 前置 [[Agent工作流与编排]]：给出循环、状态与多步编排的语义，本篇把这些语义固化为五条不变量与停止条件枚举。
- 前置 [[MCP协议]]：工具描述与调用的协议层规范，本篇的工具契约与之一致，可直接映射为 MCP 的 `tools/list` 与 `tools/call`。
- 对照 [[成本-延迟-质量权衡]]：本篇第 11 节的成本表与第 8 节的限流取值，来自该篇的三角权衡方法。
- 对照 [[模型评估矩阵]]：本篇第 7 节的离线、在线与回归三层评估，具体指标定义与基准选择参照该篇。
- 后续 [[Harness与Loop工程]]：把本篇的循环骨架扩展为可插拔的运行时，处理并发、恢复与上下文预算。

## 达标检测

- [ ] 写出文档问答 Agent 的六条验收条件与失败定义，说明每条如何判定，并解释为什么失败定义必须显式列出。
- [ ] 用 Wilson 公式计算 $n=3,k=3$ 与 $n=200,k=182$ 的 95% 区间，说明黄金集为何取 200 条而不是 20 条。
- [ ] 画出六层架构图并标注依赖方向，指出把数据访问写进接口层会导致哪两类测试无法进行。
- [ ] 运行例 2 的脚本，把 `BUDGET_USD` 改为 0.001 与 0.02 各跑一次，比较 `stop` 字段与返回内容，解释降级路径的差异。
- [ ] 在例 2 中新增一个 `list_sources` 工具，要求参数校验覆盖枚举与必填字段，并补一条单测验证非法参数被拒绝。
- [ ] 按第 11 节的成本结构，计算兜底率从 3% 降到 2% 的月度节省，并说明为什么优化顺序应先降兜底率而非压缩 token。
- [ ] 列出回滚演练的五个步骤与每步的预期耗时，给出总耗时不超过 5 分钟的配置前提。

## 参考来源

- Chip Huyen, *Designing Machine Learning Systems*, O'Reilly, 2022 —— 对应第 7 节的三层评估、第 9 节的监控指标与第 12 节的交付清单。
- Anthropic, "Building effective agents", 2024 —— 对应第 4 节的循环不变量、第 5 节的工具描述写法，以及「先用最简单方案」的设计取向。
- Model Context Protocol 规范（modelcontextprotocol.io） —— 对应第 5 节的工具声明与调用契约，以及本篇工具表与 `tools/list`、`tools/call` 的映射。
- Google, "Rules of Machine Learning" —— 对应第 7 节「先建评估再做优化」的顺序，以及第 12 节分阶段交付的节奏。
- Hugging Face Transformers 官方文档（`GenerationConfig` 中 `max_new_tokens`、`temperature` 等字段的语义） —— 对应例 3 的模型配置项与例 4 中推理服务的启动参数。
