从任务到证据
English | 中文
一次业务任务，怎样穿过模型、工具、权限和会话
先不看包目录。沿一条代表性执行路径观察输入如何变成动作、结果和可复查证据，再回到代码定位每一层。
用户提交目标与当前材料。
Agent 组装模型与工具，受策略约束执行。
结果和过程进入会话日志，由界面与 SDK 重建。
先看一个代表性任务
设想一位业务负责人要求：“检查这个仓库的登录流程，找出一个可能造成重复提交的风险，说明证据；如果需要改代码，先给出修改范围并等待批准。”这不是仓库中的固定演示脚本，而是用来解释现有运行机制的代表性输入。
任务的真正产物不只是一段回答。它还包括本次会话采用的 Agent 组装、模型看见的消息、工具调用与审批、文件变更、检查结果，以及这些事实在会话中的顺序。
Step 1：会话获得一套 Agent 组装
Host 创建 Agent 时先确定会话采用的 preset。Preset 把模型、系统提示词、工具和相关插件挂进这个 Agent 的作用域；同一进程中的其他会话可以采用不同组装。未知、损坏或无法挂载的 preset 会在创建阶段失败，不会留下一个只装了一半能力的 Agent。
这一步对业务方的意义是“同一平台、按任务配能力”。代码审查 Agent 可以拥有仓库、Shell 和 LSP；只读知识助手可以不获得写入工具；高风险后台任务可以只暴露经过审批的领域动作。机制由 Agent preset 注册表 和 会话作用域承载。
Step 2：模型请求从会话事实重建
Agent loop（智能体循环）打开一个轮次和步骤，把用户消息写入会话，再从已组装的系统提示词、工具 schema 与 deriveMessages() 生成模型请求。模型收到的历史不是另一份隐藏聊天缓存，而是从有序会话事件表层重建；新的模型可见输入也必须先有对应会话事件。
模型以流式内容返回时，增量和最终消息继续写入同一日志。失败、重试、token 用量和请求目标也有自己的事件，因此刷新页面或换一个消费界面不需要猜测模型当时看见了什么。主路径位于 Agent loop 和 会话事件实现。
Step 3：工具调用先经过治理流水线
模型要求读文件、运行命令或调用领域工具时，执行不会直接跳到实现函数。工具注册表先物化参数，再依次运行 pre-execute、单调 guard、审批决策、实际执行、post-execute、结果收尾与不可变结果通知。任何 guard 可以把调用收紧为拒绝，但不能把之前的拒绝重新放宽。
需要审批的调用只有在审批服务返回一次性允许时才执行。没有答复方、答复异常或会话策略为 never 时，调用默认拒绝；委派给 subagent 的会话固定使用 never，避免无人观察的子任务通过弹窗扩大权限。完整语义见 工具执行流水线、工具注册表和审批服务。
Step 4：结果进入日志，再被界面重建
工具开始、结束、失败与可见结果进入会话事件日志；Web 客户端把这些事件折叠成用户消息、assistant 消息、工具卡片、重试提示和运行状态。工具还可以声明 generic、terminal 或 diff 等呈现意图，让同一领域动作在 transcript（文本记录）中拥有合适的视觉形式。
会话持久化提供程序把日志写入存储后，后续进程可以重新加载；调用方也可以通过 Web、CLI（命令行界面）、ACP（Agent Client Protocol）、TypeScript SDK 或 Python SDK 驱动同一运行主干。客户端投影位于 Web 运行时，持久化入口位于 会话持久化。
哪些位置会高声失败
| 位置 | 可见信号 | 业务含义 |
|---|---|---|
| Agent 组装 | preset 不存在、损坏或发布到错误作用域 | 任务不会带着缺失能力继续运行 |
| 模型请求 | 提供方、模型、凭据或输入内容不受支持 | 请求在网络前或适配器层失败并留下诊断 |
| 工具决策 | 参数无效、策略拒绝或审批不可用 | 动作不执行，拒绝原因进入工具结果 |
| 执行提供方 | 沙箱不可用、进程失败或超时 | 失败属于本次工具调用，不伪装成成功文本 |
| 会话恢复 | 格式版本、必需事件或持久化内容无效 | 加载被拒绝，不用猜测旧数据的含义 |
把 Harness 看成一条“组装—决策—执行—记录—呈现”流水线
LLM 决定下一步意图；插件决定它拥有什么能力；工具流水线决定动作能否执行；提供方完成实际工作；会话日志保存事实；界面和协议把同一事实投影给不同使用者。
证据状态：除特别标注外，本页基于当前源码已确认。代表性任务用于解释机制，不是现成业务模板或效果承诺。