从提示词工程到上下文工程，再到 Harness Engineering：AI Agent 如何真正走向可用（V4 手册版）

这版是可直接落地的手册版：你不需要再从概念推到执行，直接按清单推进即可。目标是两件事：先把系统跑稳，再去追求“更聪明”。

一、先建立共同认知（60秒版）

• Prompt Engineering：让模型“按你的要求说话和做事”
• Context Engineering：让模型“在当前任务中知道该知道的信息”
• Harness Engineering：让系统“在真实环境里稳定执行、可恢复、可审计”

实战优先级：先 Harness，后 Context，再精修 Prompt。因为生产事故主要死在“跑不完”，不是“说得不够漂亮”。

二、故障分类表（先定位再修复）

遇到问题时，先把故障归到一类：

• A类：意图故障（误解任务、输出格式错）→ 修 Prompt
• B类：信息故障（缺上下文、信息过期、召回错）→ 修 Context
• C类：执行故障（超时、工具报错、权限/会话失效）→ 修 Harness
• D类：运营故障（成本高、成功率低、不可审计）→ 修指标与治理

规则：不先定类，不允许改代码和提示词。

三、最小可用 Harness 架构（MVP）

• 任务编排器：状态机（INIT → RUNNING → WAIT_HUMAN → RESUME → DONE/FAIL）
• 工具网关：白名单、参数校验、超时和重试策略
• 身份网关：授权有效性探针、过期预警、统一续期入口
• 事件总线：每一步都发事件（开始/成功/失败/接管）
• 观测层：trace_id + step_id + error_code + latency

只要这五块齐了，系统就从“脚本自动化”升级为“工程系统”。

四、上线前检查清单（可直接照抄）

1）稳定性

• 关键步骤是否设置超时？
• 重试是否指数退避？是否幂等？
• 失败后是否能从中间步骤恢复而非全链路重跑？

2）安全性

• 工具是否最小权限开放？
• 高风险动作是否有人工确认门？
• 敏感参数是否脱敏日志？

3）可观测性

• 每次任务是否有唯一 task_id？
• 能否回放最近 10 次失败链路？
• 是否有失败根因分布图（Top N）？

4）可运营性

• 是否有人工接管SOP？
• 是否定义成功率、P95时延、单任务成本？
• 是否每周固定复盘并关掉高频故障？

五、指标体系（你只盯这 6 个）

• Task Success Rate：任务成功率（主指标）
• Step Recovery Rate：步骤级恢复率（韧性）
• Human Handoff Rate：人工接管率（自动化覆盖）
• MTTR：平均恢复时长（可维护性）
• P95 Latency：95分位耗时（体验）
• Cost / Task：单任务成本（商业可持续）

目标趋势：成功率↑、恢复率↑、接管率↓、MTTR↓、成本↓。

六、每周复盘模板（直接可用）

本周失败 Top3：

• 故障1：类型（A/B/C/D）｜触发条件｜影响范围｜根因
• 故障2：类型（A/B/C/D）｜触发条件｜影响范围｜根因
• 故障3：类型（A/B/C/D）｜触发条件｜影响范围｜根因

修复动作：

• 已完成：xxx（附指标变化）
• 进行中：xxx（预计完成时间）
• 下周计划：只做 2 件“最影响成功率”的事

七、最后给 tk 的实战建议

当你带团队推进 Agent 项目，直接用这条原则：先把失败系统化，再把成功规模化。不要在“提示词微调”里过度投入，先把 Harness 打牢，系统会自然进入正循环。

这是 V4。后续我会继续迭代成 V5（附架构图 + 真实故障案例剖析 + 决策树）。