Harness:把模型放进可复用的执行边界
拆开模型接口、工具注册、会话、权限、状态和反馈,解释运行时如何影响任务可靠性。
同一个模型放进不同系统,可能有完全不同的任务表现:一个系统丢失工具错误、没有文件版本和恢复点;另一个提供清晰工具契约、可验证状态和受控重试。Harness 指组织这些运行条件的外围系统。它不是让模型变聪明的魔法,而是降低信息丢失、错误执行和不可恢复状态造成的失败。
最小运行时的六个职责
模型接口负责协议适配、流式拼装、停止原因和用量;工具注册表保存工具名、schema、执行函数、权限及副作用说明;会话管理隔离用户、任务与上下文;状态层维护检查点、调用结果和恢复位置;权限层根据可信身份及批准决定动作是否可执行;反馈层把结果、错误和验收信息变成下一次可用观察。
这些职责可以在一个小服务中实现,不必一开始就拆成多个平台。接口边界却必须清楚:模型不能通过传入一个 permission=true 获得写权限,工具也不应偷偷直接修改会话状态。把模型、提示、工具 schema 和运行时配置记录为版本,才能解释一次运行与另一次有何差别。
长任务需要跨会话连续性
上下文窗口有限,压缩会丢细节,进程也可能中断。长期任务应保存目标、验收项、已完成变更、当前证据、剩余工作和环境版本,让新会话能重新核验并继续。长运行 Agent 的官方实践讨论了初始化与增量工作的分工;具体文件格式和提示只是实现选择,不应当成普遍最佳答案。
恢复前需要验证工作区实际状态与记录一致。检查点写着“测试通过”但代码已经变化,就必须重新检查相关测试。外部网页、工具返回与技能文件都可能是不可信输入,不能因为被保存下来就升为系统指令。运行时提供隔离工作区、文件范围和网络权限,可以减少模型误操作的影响,但不能声称沙箱保证所有逻辑正确。
重复调用、幂等与崩溃窗口
call_id 可以关联请求与结果,并帮助检测重放。相同会话、相同 ID 和相同参数重复出现时,可返回已保存结果;同 ID 不同参数应报冲突。去重前仍要检查当前权限,避免旧结果跨权限泄露。副作用操作还需要服务端幂等键与结果查询,单进程字典只防住本进程内已记录的重复调用。
假设工具执行成功后进程在写记录前崩溃,内存去重无法知道成功。若业务要求可靠恢复,就要设计持久记录与外部协议,明确至少一次、至多一次和业务幂等的边界。持久执行文档也要求正确安排副作用;不能把框架 checkpoint 当作跨系统 exactly-once 承诺。
运行:注册表、权限与重放
保存为 harness.py,执行 python harness.py。求和是真实本地执行,去重记录仅存在内存,没有部署远程服务。
"""单进程注册表、权限与重复调用防护,不声称分布式 exactly-once。"""
class Harness:
def __init__(self):
self.tools = {'add': lambda args: sum(args)}
self.completed = {}
def call(self, session, call_id, name, args, permissions):
if name not in permissions or name not in self.tools:
raise PermissionError(name)
if not isinstance(args, list) or any(type(v) is not int for v in args):
raise ValueError('integer list required')
key = (session, call_id)
signature = (name, tuple(args))
if key in self.completed:
old_signature, value = self.completed[key]
if old_signature != signature:
raise ValueError('call id conflict')
return value, 'replayed'
value = self.tools[name](args)
self.completed[key] = (signature, value)
return value, 'executed'
if __name__ == '__main__':
runtime = Harness()
print(runtime.call('s1', 'c1', 'add', [2, 3], {'add'}))
print(runtime.call('s1', 'c1', 'add', [2, 3], {'add'}))
try:
runtime.call('s1', 'c2', 'add', [1], set())
except PermissionError:
print('denied')实际运行输出:
(5, 'executed')
(5, 'replayed')
denied同一个 c1 第一次 executed,第二次 replayed;c2 没有 add 权限,直接 denied。把第二次参数改为 [2,4] 会触发 call id conflict。生产实现还需持久化、并发锁定、超时、审计与会话授权;本例不具备分布式一致性。
逐项情境追问与故障定位
以下为机制分析与手算情境。可先遮住回答独立判断,再核对输入、失败位置和选择条件;它们不代表真实模型、远端服务或设备实验记录。
工具注册:模型提出未注册delete_all,能动态找同名函数执行吗?
运行时只允许注册工具,schema、权限、副作用说明与执行器绑定。显式注册维护成本较高但收紧能力边界。测试未知名和合法名错误参数均在执行前拒绝,不能把模型文本交给eval或任意导入。
模型接口:模型切换后工具参数流片段被当完整JSON执行,如何定位?
适配器应拼完整调用并保留停止原因/ID,再做schema验证。统一接口减少上层差异但不能丢供应商事件语义。固定分片、截断、拒绝样本逐事件回放,检查工具只在完成信号后执行一次。
会话:两个用户用了相同call_id,返回了另一人的缓存结果,怎么办?
去重键需包含可信会话/主体范围,查询重放前还要检查当前权限。共享缓存节约成本但权限边界更难。用u1/c1与u2/c1分别请求,确认独立结果且不泄露,不能把call_id当全球唯一可信凭据。
权限:工具参数permission=true能越过运行时,怎样修?
权限从认证主体和批准上下文派生,模型字段不是授权来源。集中权限层便于审计,但工具内部资源级校验仍必要。构造无权主体带true参数的请求,断言执行函数未被调用,不能只修改提示词要求模型自觉。
状态:checkpoint写测试通过,文件后来变了,还可直接续写吗?
状态应携带代码/工具/配置版本,恢复前核工作区实际哈希和前提。复用检查点节约时间但陈旧证据必须失效。修改被测文件后恢复,确认相关验收重新运行,而不是把历史完成标志当当前事实。
反馈:工具错误只写日志没回注,Agent为什么一直重复?
反馈层应把错误分类、调用ID和验收结果变成下一轮观察,日志不是模型输入。结构化反馈利于恢复,但外部内容必须保持不可信身份。固定一次参数错误,检查下一轮可见具体字段错误且不能通过反馈提升权限。
运行边界:内存去重通过两次调用测试,能承诺exactly-once吗?
不能覆盖执行成功但记录前崩溃、并发竞争和重启丢字典。单进程缓存简便,可靠副作用需持久化与服务端幂等/查询。注入成功后崩溃窗口,核恢复是否对账;明确至少一次、至多一次与业务幂等的范围。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
模型能力不变时运行时怎样改变任务成功率?
参考思路与常见误区
清晰工具契约、正确反馈、权限边界、可恢复状态和验收器能减少执行错误及信息丢失。收益需在相同任务下实测,不能声称运行时自动弥补全部模型能力。
常见误区:失败只可能因为模型不够强。
工具注册表除函数名还应保存什么?
参考思路与常见误区
参数 schema、执行入口、权限、副作用、超时或重试契约与版本等。这样运行时可在执行前验证并决定恢复方式,而不是动态执行模型提供的任意代码。
常见误区:一个名称到函数映射就覆盖全部运行边界。
同 call_id 不同参数应直接复用结果吗?
参考思路与常见误区
不应,应报冲突并调查适配或重放错误。去重键需包含会话范围并核对调用签名,当前权限也要先检查,避免结果跨范围泄露。
常见误区:只要 ID 一样就无条件返回缓存。
内存去重为何不保证崩溃后不重复?
参考思路与常见误区
进程退出会丢记录,工具成功到记录写入之间也有窗口。可靠副作用需要持久化与服务端幂等或对账,不能靠本地字典保证分布式 exactly-once。
常见误区:单进程重放测试通过就宣称跨系统事务安全。
新会话接续长任务需要哪些材料?
参考思路与常见误区
目标与验收项、已完成动作及证据、剩余事项、当前环境和版本、恢复边界。重新核对工作区与记录一致,不能只依靠压缩后的聊天摘要。
常见误区:一句之前都做好了就足以恢复。