# 实验 9-3：基于失败轨迹优化系统 Prompt

本实验使用航空客服的“过度转接”案例，演示一条受控的 Prompt 学习链路：先评测运行轨迹，再把失败整理为结构化诊断，随后由 Coding Agent 生成最小补丁，最后用边界集与旧任务保留集决定待验证版本是否可以灰度发布。

这与一次性人工提示工程的关键差别，不在于“让模型改写 Prompt”，而在于每个补丁都能回答三个问题：它由哪些失败案例触发、作用于哪条规则、为什么没有破坏旧行为。

## 实验流程

`evaluate.py` 运行保留集与边界集。`learning_signal.py` 将每条轨迹拆成规则遵从、任务解决和合规变通三个维度，并保留来源 case ID。`coding_agent.py` 读取结构化报告，对 Prompt 做精确的 `old_str → new_str` 编辑。`release_gate.py` 生成待验证 manifest，并执行四项发布检查：补丁非空、来源可追溯、保留集不退化、边界集确有改善。

待验证补丁只写入 `runtime/system_prompt_working.txt`，不会覆盖 `prompts/system_prompt.txt`。门槛通过时，实验只返回 `release_to_canary`，表示允许灰度；未通过则返回 `reject_candidate`。

```text
失败轨迹 → 三维诊断 → 最小 Prompt diff → 待验证 manifest
                                         ↓
                         边界集改善 + 保留集不退化
                                         ↓
                              灰度发布或拒绝提案
```

## 运行

完整实验需要一个 OpenAI 兼容的模型接口：

```bash
# 从仓库根目录开始：使用共享的第 8 章环境
uv sync --locked --python 3.12 --extra ch8
# Apple Silicon macOS 需要 macOS 14+（锁文件中的 bitsandbytes wheel 要求）；
# 更早的 macOS 请使用下方单项目兼容路径。

# 切换目录前先激活环境：
# macOS/Linux:
source .venv/bin/activate
# Windows PowerShell: .\.venv\Scripts\Activate.ps1
# Windows cmd: .venv\Scripts\activate.bat

# 未安装 uv 时可用 pip 兜底：
# python -m pip install -e ".[ch8]"

cd chapter8/prompt-auto-optimization

# 迁移期间仍支持单项目兼容路径：
# python -m pip install -r requirements.txt

cp env.example .env
export OPENAI_API_KEY=your_api_key_here
python demo.py --quick --model gpt-5.6
python demo.py --model gpt-5.6 --output output/run.json
```

以上两条命令会真实调用客服 Agent、LLM Judge 和 Coding Agent，并非 dry-run；`--quick` 只是减少评测案例数量。`python demo.py --dry-run` 仅检查模型配置和用例选择，不生成补丁，也不能作为实验结果。

离线可以检查参数、诊断逻辑和发布门槛：

```bash
# 在仓库根目录安装包含 pytest 的测试环境：
uv sync --locked --python 3.12 --extra ch8 --extra dev

# 未安装 uv 时可用 pip 测试环境兜底：
# python -m pip install -e ".[ch8,dev]"

source .venv/bin/activate
cd chapter8/prompt-auto-optimization

python demo.py --dry-run
python -m pytest tests
```

项目也保留人工调优版 `prompts/system_prompt_manual.txt` 作为对照。完整实验比较初始版、自动提案版和人工版在两组任务上的表现；具体准确率会随被测模型变化，是否发布则始终由显式门槛决定，而不是由 Coding Agent 自己决定。

### 正文验收运行（2026-07-30）

正文的正式入口会强制使用完整的 5 条保留任务和 5 条边界任务，不接受 `--quick` 作为验收：

```bash
python run_experiment_9_3.py \
  --provider ark \
  --model doubao-seed-1-6-flash-250615 \
  --rounds 3
```

机器可读证据位于 `validation/real_20260729T171101Z/evidence.json`，SHA-256 为
`491b54ca5e10ea3b3154c014a44039e9520ae61880e4d46e7f667fa0aa2c4106`；
`validation/latest.json` 指向同一内容。证据保存了 73 次无凭据原始 API 请求/响应、三份 Prompt 的逐例轨迹、Judge 理由、精确 `old_str → new_str` 编辑、来源 case ID、待验证 manifest、发布检查、Token 用量和耗时。

本次真实结果如下：

| Prompt | 保留集 | 过度转接边界集 |
| --- | ---: | ---: |
| 初始 Prompt | 5/5 | 0/5 |
| 自动提案 | 5/5 | 2/5 |
| 人工一次性调优 | 5/5 | 4/5 |

自动提案满足“补丁非空且可审计、来源可追溯、边界集改善、保留集不退化”，因此结果是
`release_to_canary`，不是覆盖稳定 Prompt 或直接全量发布。自动提案虽通过正文门槛，但仍明显弱于人工对照；证据没有把 2/5 描述成边界问题已全部解决。

ARK 回执合计 73,456 个输入 Token、7,313 个输出 Token、80,769 个 Token。该接口没有返回货币费用字段，所以证据中的美元成本保持 `null`，没有用未固定的价目表猜算。

## 文件说明

| 文件 | 作用 |
| --- | --- |
| `airline_env.py` | 工具调用环境与保留/边界案例 |
| `evaluate.py` | 运行 Agent，输出轨迹结果与处理判定 |
| `learning_signal.py` | 从失败轨迹生成三维诊断和来源证据 |
| `coding_agent.py` | 生成并应用可审计的最小 Prompt 编辑 |
| `release_gate.py` | 待验证 manifest、回归门槛和发布决定 |
| `demo.py` | 串联完整闭环并输出对照结果 |
| `tests/` | 离线验证诊断、补丁应用、工具空值处理、接受和拒绝路径 |
| `run_experiment_9_3.py` | 强制完整三组真实验收并保存原始回执与 `acceptance` |

本实验使用无外部副作用的航空客服沙盒，以便三份 Prompt 在完全相同的状态和任务上重复执行。它完成了正文规定的实验对照，但不等同于生产航空系统验收；接入生产时仍须把规则遵从连接到正式政策与订单真值，并扩充专家校准和安全留出集。