文档目录
系统
架构
组成、Desk 与 Daemon 的分工、插件和数据放在哪、连接与授权、断线与重启。
组成
每个平台(Windows x64、Linux x64)一个可执行文件 ail,编译成单文件,目标机不用另装运行时。它有三种用法:
| 用法 | 是什么 | 在哪运行 |
|---|---|---|
ail desk |
Agent Desk | 你选的一台电脑,每个用户一个 |
ail daemon |
Client Daemon | 每台 Client 一个 |
| 其余子命令 | 命令行 | 每台 Client |
主路径是:浏览器 ↔ Desk(HTTP 与 WebSocket)↔ Daemon(WebSocket)↔ 适配进程(ACP,标准输入输出)↔ Harness。
Desk 与 Daemon 的分工
| Desk | Daemon |
|---|---|
| 界面的宿主 | 向 Desk 的出站长连接 |
| 数据库 | 承载 Worker |
| 引擎:流转、队列、叫醒、Router 合同、报告 | 非交互 Shell 与交互式控制台 |
| 鉴权与授权 | 本机插件目录里的一切:检出、同步、worktree、收尾动作 |
| 报告的文件 | 界面插件的构建 |
- Daemon 主动连 Desk。 Client 可能在 NAT 后面、可能不在线;Desk 的地址是固定的。
- Desk 不检出任何仓库。 插件都在某台 Client 的插件目录里;Desk 要用其中的内容时,向那台的 Daemon 要。Desk 所在的电脑因此不需要 Git,也不需要仓库的凭据。
- 引擎在 Desk,仓库上的动作在 Daemon。 引擎要在某个仓库上做的每件事,都是发给那台 Daemon 的一个有名字的请求,返回结构化结果;引擎不拼 shell 文本。
- Daemon 没有自己的业务状态。 它只留连接凭据和重连会话用的存档。
插件放在哪
每台 Client 的 Daemon 启动时指定一个插件目录。目录是平铺的:
<插件目录>/
main/ 主仓
official/ 官方默认插件
<repo id>/ 其余每个 Repo 一个目录
.worktrees/<名称>/<repo id>/ 任务的 worktree
.scratch/<运行 id>/ 运行的草稿目录
放主仓和官方默认插件的那台 Client 叫主仓 Client;角色、工作流、界面在那里改完就生效,不用先推送。一个 Repo 检出在一台 Client 上,默认是主仓 Client,也可以放到另一台。格式见插件。
数据在哪
| 数据 | 真源 |
|---|---|
| Repo 的登记、角色、工作流、Harness 定义、界面源码、Journal | Git 里的文件 |
| 工作副本、worktree、任务记录 | 各 Repo 的 Git 仓库 |
| Client、配对、授权规则 | Desk 的数据库 |
| 会话、轮次、排队的消息、运行与流水、报告及回答 | Desk 的数据库 |
| Harness 的登录凭据 | Harness 自己。aiL 不读不写 |
数据库是内置的 SQLite。页面上的对话历史只来自它,从不靠 Harness 重放。
连接、归属与授权
- 配对。 Desk 签发一次性的配对码,绑定 Client 的 id,有期限。Client 用它登记,拿到自己的凭据和 Desk 的公钥身份。
- 连接。 Daemon 向 Desk 发起 WebSocket。握手是双向的:Desk 先用自己的 Ed25519 私钥对质询签名,Daemon 核对出这是自己配对的那个 Desk 之后才出示凭据。两边都查心跳,15 秒没有对方的心跳就关掉连接,Daemon 退避重连。
- 归属。 一个 Client 只属于一个 Desk,别的 Desk 控制不了它。
- 主体。 向 Desk 发请求的有三种:拥有者(不带凭据的请求)、
client:<id>(凭 Client 的凭据)、session:<id>(凭会话令牌)。 - 授权。 规则集中在 Desk,默认拒绝,按 Client 写:哪台 Client,对哪些目标 Client,可以做什么。动作有三种:
powershell、bash、session。被拒的请求返回AUTHZ_DENIED,写明主体、目标和动作。
Desk 没有登录:不带凭据的请求就是拥有者。它只应该监听在你自己的私有网络上(例如 Tailscale 的 Tailnet),不要暴露到公网。
aiL 不做防攻击设计:使用者是你本人。上面这些保证的是归属清楚、授权不被无意绕开。
断线与重启
一轮只在 Desk、Daemon 和它们之间的连接都在的时候算数。少了哪一样,这一轮就记为失败,之后接着做:
| 发生了什么 | 结果 |
|---|---|
| 连接断了(网络断、Daemon 退出或升级) | 那台 Client 上正在进行的轮次记为失败,错误码 DAEMON_DISCONNECTED。Daemon 结束正在跑的适配进程,退避重连 |
| Desk 重启 | 启动时把还标着进行中的轮次记为失败,错误码 DESK_RESTARTED |
失败的那一轮里 Agent 已经做了的事还在。工作流里的一轮因为这两种原因失败时,引擎等那台 Client 连上后请 Worker 从中断处继续,不打扰任何人。
一个会话连续 30 分钟没有轮次时,Desk 请 Daemon 结束它的适配进程。下一条消息到来时重连原会话,上下文还在。