文档目录

系统

Worker 契约

每个 Harness 会话都是同一个 Worker:定义、操作、一轮、身份与无人值守。

Worker 是系统在某个 Client 上经 ACP 启动的一个 Harness 会话。引擎、界面和 Router 只经这份契约和它打交道。Router、工作流步骤的作者与评审者、被调用的角色、你直接开的会话,都是 Worker:它们的差别在引擎给的第一条消息和报告的去向,不在契约里。

契约只收五个目标 Harness(claude、codex、dsh、pi、antigravity)都具备并且实测过的能力。

Harness 定义

每个 Harness 一条定义,是数据,放在官方默认插件的 harnesses.yaml 里。Daemon 和引擎里都没有按 Harness 名字的分支。增加一个 Harness 就是增加一条定义,前提是它装得进这份契约。

字段 含义
id 名字
command 启动适配进程的命令行
env 追加给适配进程的环境变量,可空
mode 可选。建会话后把 ACP 类别为 mode 的配置项设成这个值
requires 给人看的前提:这台 Client 上要先装好、登录好什么
harnesses:
- id: claude
  command: [npx, -y, --package=@agentclientprotocol/claude-agent-acp@0.108.0, --, claude-agent-acp]
  mode: bypassPermissions
  requires: Node;已登录的 Claude Code
- id: antigravity
  command: [agy, acp, --stdio, --dangerously-skip-permissions]
  requires: 已登录的 agy

某台 Client 上能用哪些 Harness,看定义里命令的第一项在那台电脑上解析得到与否。启动失败原样报错,不换别的 Harness 顶替。

操作

操作 做什么
建会话 照定义启动适配进程,建立 ACP 会话,依次设模式、模型、思考强度。请求的值不在 Harness 列出的选项里就失败,不替换成别的值
发消息 一轮:文字加可选的图片。会话忙时消息在 Desk 排队,这一轮结束后按先后送出
取消 这一轮以「已取消」结束,会话可以接着用
关闭 结束适配进程整棵进程树
续聊 适配进程不在了,下一条消息到来时重连原会话:上下文还在,模式、模型和思考强度还是原来的。重连不上时这一轮失败,不换成一个新会话

建会话要几秒到十几秒,所以发起方不等:Desk 记下会话就答复会话 id,这期间发给它的消息排队,建好后按先后送出。

一轮

一轮只由 Desk 送出的一条消息引起,到 Harness 答完为止。进行中,Daemon 把 ACP 的更新归成四种事件转给 Desk:文字片段、思考片段、工具调用、状态。保证的只有两点:顺序不乱;文字片段连起来就是这一轮的回复全文。不保证逐字流式和工具明细,Harness 给什么,会话页就显示什么。

一轮以结果或失败结束。失败之后会话还能用:下一条消息照「续聊」接上。引擎的流转只看回复全文里的报告块和失败的错误原文。

有的 Harness 会在两轮之间自己起一轮(后台命令结束、定时器到点)。这不在契约内:Worker 不靠 Harness 自己醒,要等的事由引擎叫醒。

提示词

角色说明、全局提示词和请求都放在会话的第一条消息里。不用 ACP 的 systemPrompt:不是每个 Harness 都支持。

会话身份与系统工具面

Daemon 启动适配进程时,把三个身份变量放进它的环境:AIL_DESK_URL、AIL_SESSION_ID、AIL_SESSION_AUTH,并把 ail 所在的目录放到 PATH 最前面。Agent 在自带的 shell 工具里直接敲 ail <子命令>,Desk 凭会话令牌认出是哪个会话。

系统给 Agent 的工具只有这一种形态。跨端 Shell、推报告、worktree、调用别的角色,都是 ail 的子命令,见命令行。aiL 不往 Harness 的配置里写任何东西,也不注入 MCP:不是它启动的原生会话里既没有这些变量,也看不到任何变化。

无人值守

Worker 没有人看着。Daemon 作为 ACP 客户端:

各 Harness 自己要的无人值守设置写在它的定义里(mode、启动参数)。

差异怎样处理

差异 怎样处理
系统提示词只有部分 Harness 支持 放在第一条消息里
会话级 MCP 不是每家都接 不进契约,系统工具都是 ail 命令行
用量有的不报 用量只是可选的统计,不参与调度
额度用尽没有统一的信号 用一份文本规则表识别,命中就按退避间隔重试
shell 工具等多久各不相同,最短的只等 10 秒 每个 ail 子命令最多等 8 秒,做不完的转成后台的操作
自带的后台与定时工具 不用它们,由引擎叫醒
模型与思考强度的选项各家不同 照 ACP 的类别设置,角色绑定里写各家列出的选项

这些处理方式都不需要按 Harness 分支。