README、运行手册与交付检查表

一份好的 README 能让别人运行项目，运行手册则帮助出问题时处理项目。两者面对的场景不同。下面分别列出需要说明的内容，并建议实际走一遍命令，而不只检查文档是否写得完整。

1. README

至少包含：

  1. 产品解决什么问题；
  2. 支持与非目标场景；
  3. 架构图；
  4. 环境与依赖；
  5. 配置变量；
  6. 本地运行；
  7. 工具和权限；
  8. 测试与 Eval；
  9. 部署；
  10. 数据和日志；
  11. 扩展 Skill/Tool；
  12. 已知限制。

提供一条从 clone 到完成最小任务的 happy path。

2. Runbook

运维手册按症状组织：

  • 模型 provider 异常；
  • 工具错误率升高；
  • queue 积压；
  • session 无法恢复；
  • 成本异常；
  • trace 缺失；
  • 权限确认卡住；
  • 外部副作用状态未知；
  • 部署回滚。

每项包含检测、影响、诊断命令、缓解、恢复验证和升级联系人。

3. 配置

  • .env.example 只列名称和说明；
  • 密钥从 secrets manager 注入；
  • startup 时验证必填配置；
  • 环境差异显式化；
  • prompt/Skill/Tool schema 有版本；
  • 配置变更进入审计；
  • 默认值偏向低权限和低预算。

4. 交付检查表

功能

  • 目标任务端到端成功
  • 部分失败可解释
  • 取消和恢复有效
  • 产物可下载/访问

可靠性

  • 最大步数、超时、重试
  • 幂等与副作用验证
  • 固定 Eval 和回归
  • Trace、metrics、logs

权限与数据

  • 最小工具权限
  • 高影响动作确认
  • 敏感字段脱敏
  • 数据保留/删除

文档与运维

  • README
  • Runbook
  • 配置说明
  • 部署与回滚
  • 已知限制

5. Definition of Done

交付不是“模型返回了一次好答案”，而是另一个人能按照文档启动系统，完成规定任务，看到证据，理解失败，并在出现问题时恢复或回滚。

让运行手册接住“结果未知”

在手册里单独写一项：“提交超时，但不知道外部动作是否成功。”第一步查业务系统中的动作记录，第二步核对幂等标识，第三步才决定重试或人工处理。不要把所有超时都写成“重新运行命令”。

Pydantic AI 的持久执行文档区分了已记录步骤的重放与执行中的调用重试；实际引擎覆盖哪些工具也不同。交付时需要写清自己采用的引擎和持久化位置，不能只写“支持自动恢复”。

请另一位使用者在干净环境完成一次启动，再模拟进程退出后恢复。记录使用的版本、停止位置、恢复结果和仍需人工操作的地方。这比一份只含启动截图的 README 更能说明系统可维护。

本节的核验依据

2026-10-25 查阅。下面的链接支持本节的机制说明；练习场景和选型建议是本教程的教学设计。