第一章：从模型到 Harness，补齐基本概念

1.1 模型提出动作，宿主执行动作

模型收到消息，生成文字或结构化工具调用。它可能提出读取 hello.txt，但提出动作并不等于拥有本地文件句柄。真正拿到路径、打开文件、捕获错误并返回结果的是宿主程序。我们把围绕模型的这套运行环境称为 Harness。

一个简单聊天应用可以只有“输入 → 请求模型 → 展示回答”。编程代理多了一条回路：“模型提出动作 → 宿主执行 → 返回结果 → 模型继续”。当任务涉及多个文件、需要审批、执行时间较长或者进程可能重启时，这条回路就需要明确的状态和协议。

模型是否聪明与宿主是否可靠，是两个不同维度。一个能力很强的模型也可能收到过期上下文；一个调度正确的宿主也可能接到不合适的修改建议。研究工程时，应分别检查信息是否真实、权限是否满足、操作是否执行、验收是否成立。

1.2 四个容易混淆的词

消息是协议中的一项内容，可能来自用户、助手或工具。请求是一次模型通信。会话是跨多个请求持续存在的工作记录。轮次是某个框架定义的执行单元，它不一定等于一条消息，也不一定只有一次模型请求。

不同项目对 turn 和 step 的用法不完全相同。DeepSeek Harness 的文档与实现把 step 放在 turn 之内，一个 step 连接一次模型请求及其工具；Pi 的底层循环也有 turn 事件，但不能不经核对就把它映射为其他项目的 turn。比较时应先说明“边界何时打开，何时关闭”，再翻译名词。

对初学者，异步可以先理解成“操作还没完成，程序已经拿到一个以后取得结果的方式”。网络响应、工具进度与取消信号因此可以交错出现。异步不自动代表并行：一个程序完全可以依次等待三个异步读取。

1.3 五个必须回答的问题

一个可用的代理运行环境至少需要说明：输入如何进入、上下文如何形成、工具如何执行、结果如何保存，以及任务如何结束。它们分别关系到队列、模型视图、执行器、日志与验收。

例如，同一时刻来了第二条用户输入，系统可以拒绝、排队、插入下一步或取消当前工作。选择没有唯一答案，但必须明确；否则两个循环可能同时修改同一份状态。Pi 的 Agent.prompt() 会拒绝在已有活动运行时启动第二次 prompt，并提示使用其他输入路径，提供了一个具体例子。Pi · agent.ts L371–385

1.4 学习时先观察状态

当界面停住，不要只问“模型是不是卡了”。它可能正在等待网络，也可能在等工具退出、等用户审批、排队保存日志，或者已经停止但前端没有同步。先区分这些状态，再找对应的日志与句柄，通常比直接更换提示词有效。

阅读练习：画出“读取一个文件并解释内容”的消息序列，标出哪一步必须访问真实文件。再把“文件不存在”加入流程。答案应允许工具返回错误，模型根据错误重新选择，而不是假设一遇错误就一定结束整个会话。