文档目录
系统
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 客户端:
- 对权限请求一律批准;
- 对运行中的提问一律拒绝,Worker 要问你的事写在报告里;
- 不提供 ACP 的文件与终端能力,Harness 用自己的工具读写文件、跑命令。
各 Harness 自己要的无人值守设置写在它的定义里(mode、启动参数)。
差异怎样处理
| 差异 | 怎样处理 |
|---|---|
| 系统提示词只有部分 Harness 支持 | 放在第一条消息里 |
| 会话级 MCP 不是每家都接 | 不进契约,系统工具都是 ail 命令行 |
| 用量有的不报 | 用量只是可选的统计,不参与调度 |
| 额度用尽没有统一的信号 | 用一份文本规则表识别,命中就按退避间隔重试 |
| shell 工具等多久各不相同,最短的只等 10 秒 | 每个 ail 子命令最多等 8 秒,做不完的转成后台的操作 |
| 自带的后台与定时工具 | 不用它们,由引擎叫醒 |
| 模型与思考强度的选项各家不同 | 照 ACP 的类别设置,角色绑定里写各家列出的选项 |
这些处理方式都不需要按 Harness 分支。