Skip to content

第 2 章 Chapter Outline:Agent、Harness 与运行环境

本文件是章节写作蓝图。四层划分是本书的工作模型;任何可归因事实都必须保留来源编号,任何设计案例都必须说明它是教学假设。

章节契约

读者完成后的能力: 能将一次 Agent 任务的模型、决策、编排和环境责任分开,针对失败先提出可观察证据,而不是仅凭最终文本归因;能把记录缺失、候选拒绝、运行环境阻塞、验证拒绝和验证接受分开处理,并用最小 Attempt Trace 将同一次尝试的证据关联起来。

前置知识: 已阅读第 1 章,了解“模型提议、工具执行、验证接受”是不同事实;具备基本的进程、文件权限和函数错误概念。

章节边界: 只建立责任坐标与初步诊断步骤。不在本章设计 Prompt 分层、工具协议、Sandbox 规则、工作流状态机或评估指标的完整实现。

小节蓝图

1. 同一个任务为何会在不同环境中得出不同结果

  • 读者问题: 模型给出相同的修改建议,为何一次写入失败、另一次又可能在测试阶段失败?
  • 叙述任务: 用只读仓库和可写测试环境的假设场景区分“建议”“执行权限”“目标验证”。
  • 证据边界: 场景是本书原创的设计演练,不代表真实日志、产品行为或因果统计。
  • 计划工件: 两环境的观察对照表。
  • 验证: 读者能指出仅凭模型回答无法判断权限、写入或测试状态。
  • 过渡: 需要一张责任图来安排诊断顺序。

2. 模型、Agent、Harness 与运行环境:本书的四层工作模型

  • 读者问题: 这些词在本书中分别解决什么问题?
  • 叙述任务: 给出每层的输入、输出、可见证据和不应承担的责任。
  • 证据边界: REF-001 支持 Harness 的工作范围;REF-003 支持规划、记忆、工具的系统概览;四层表本身是本书扩展。
  • 计划工件: 责任边界表。
  • 验证: 每一层均能映射到一个故障问题和一个证据来源。
  • 过渡: 将表映射到可观察的请求—执行—反馈流。

3. 让边界成为接口:从请求到观察的错误传播路径

  • 读者问题: 哪些信号应跨层返回,才能不把失败藏在自然语言总结里?
  • 叙述任务: 解读 chapter-02-agent-harness-runtime.mmd:候选、执行请求、环境结果、验证结果和事件记录各自含义。
  • 证据边界: 图是本书的抽象接口模型;不描述特定框架的真实内部结构。
  • 计划工件: Mermaid 四层责任与反馈图。
  • 验证: 图中关键箭头都有正文解释,且没有从“模型候选”直接指向“任务完成”。
  • 过渡: 图示使故障可以按证据而非直觉分类。

4. 故障归因:先找证据,再找责任

  • 读者问题: 如何在不确定时避免错误重试或错误授权?
  • 叙述任务: 给出“模型候选不成立、Agent 决策不当、Harness 编排缺口、运行环境拒绝”四类假设及检查顺序;补充“未证实、候选拒绝、运行环境阻塞、验证拒绝、验证接受”的最小结论词表。
  • 证据边界: 归因表是本书的诊断建议,不承诺覆盖所有故障。
  • 计划工件: 故障归因表、“假设—证据—行动”诊断卡、最小排查流程和结论状态表。
  • 验证: 每类故障都有一个“不能据此断定”的提醒;读者能为一个失败写出最小证据和当前不应执行的动作,并能将记录缺失标为未证实,避免伪因果、无效重试和无证据结论。
  • 过渡: 引向各层之间的最小接口契约。

5. 最小接口清单:分层不等于分散责任

  • 读者问题: 小型系统也需要四个独立服务吗?
  • 叙述任务: 说明同一进程可实现多层,但仍应以“问题—工件—判定”显式表达候选、决策、请求、观察、验证与证据;补入以 attempt_id、请求关联和最小顺序关系避免错误拼接证据的 Attempt Trace,再给出从纯内存模拟器到真实受控适配器的渐进增强边界。
  • 证据边界: 是本书设计建议;不产生可运行代码或产品兼容性承诺。
  • 计划工件: 问题—工件—判定表、Attempt Trace 关系表、输入—输出—失败—证据四列表与增强顺序。
  • 验证: 清单中每项都有明确责任、最小工件、判定条件或升级方向;Attempt Trace 不被写成产品格式或通用追踪标准,渐进步骤不被写成通用成熟度模型。
  • 过渡: 第 3、5、10、11、12 与 17 章将分别实现这些边界。

章节工件状态

  1. 已完成:Technical Review,确认来源观点与本书工作模型分开。
  2. 已完成:Mermaid 渲染与 Diagram Review;仅有源文件不计为图示审查完成的规则已通过实际渲染满足。
  3. 已完成:Example Implementation,使用纯内存运行边界示例并定义可执行验证命令;不将教学模拟器描述为真实环境。
  4. 已完成:Fact Check、Language Editing 与 Final Review;最终状态由 .ai/progress.md.context/CURRENT_STATE.md 汇总。

Outline 完成检查

  • [x] 每个小节包含读者问题、证据边界、工件、验证和过渡。
  • [x] 明确了与第 1、3、5、10、11、12、17 章的边界。
  • [x] 计划图示和案例均不冒充为真实产品或运行记录。
  • [x] 没有以详细实现代替后续章节的职责。
  • [x] 结论状态表明确为本书诊断词表,未被表述为产品状态机或统一行业标准。

从同一套 Markdown 书稿生成。