文档目录

系统

架构

组成、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、收尾动作
报告的文件 界面插件的构建

插件放在哪

每台 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 没有登录:不带凭据的请求就是拥有者。它只应该监听在你自己的私有网络上(例如 Tailscale 的 Tailnet),不要暴露到公网。

aiL 不做防攻击设计:使用者是你本人。上面这些保证的是归属清楚、授权不被无意绕开。

断线与重启

一轮只在 Desk、Daemon 和它们之间的连接都在的时候算数。少了哪一样,这一轮就记为失败,之后接着做:

发生了什么 结果
连接断了(网络断、Daemon 退出或升级) 那台 Client 上正在进行的轮次记为失败,错误码 DAEMON_DISCONNECTED。Daemon 结束正在跑的适配进程,退避重连
Desk 重启 启动时把还标着进行中的轮次记为失败,错误码 DESK_RESTARTED

失败的那一轮里 Agent 已经做了的事还在。工作流里的一轮因为这两种原因失败时,引擎等那台 Client 连上后请 Worker 从中断处继续,不打扰任何人。

一个会话连续 30 分钟没有轮次时,Desk 请 Daemon 结束它的适配进程。下一条消息到来时重连原会话,上下文还在。