文档目录

工作

工作流与引擎

意图、工作流与运行;报告块怎样驱动流转;叫醒、评审关口、收尾、worktree、地图与 Journal。

引擎是 Desk 里照工作流推进运行的那部分代码。确定的事都由它做:流转、叫醒、收尾、照地图派任务。模型只产出判断和内容。

意图、工作流、步骤

官方默认插件的 workflows.yaml 定义了这些意图:

意图 用于 步骤
implement 改出仓库内容:功能、修复、重构、文档、配置 execute,由 execute-review 评审,完成任务
implement-frontend 涉及展示、交互或界面的改动 execute-frontend,由 execute-review 评审,完成任务
plan 先交付可评审的方案 plan,由 plan-review 评审
assist 查询核对、记录、按仓库现有做法执行的操作 assistant
research 分析、调研、方案比较 research
learn 学习和复习,你直接和 teacher 对话 teacher(对话)
new-project 从零新建项目或仓库 new-project
architect 规划要拆成很多任务的大事,负责到验收 architect,由 architect-review 评审,完成任务
prototype 试验可行性或性能,交付带证据的结论 prototype,完成任务
upgrade 审视 aiL 的运行和设计,经你批准后改进插件 upgrader

引擎每次用到时读这些文件,不缓存:改了文件,下一次派发、下一步就照新的做。

运行

一次派发就是一个运行,id 形如 r261121-010214-3fa9。每一步的作者在它的角色绑定的 Client 上启动;带评审关口的步骤第一次送评时启动评审者。Client、Harness、模型和思考强度都取角色的绑定,派发时不能指定。

启动一个 Worker 前,引擎核对三件事:角色绑定的 Client 在线,那台上有这个 Harness,派发者有到那台的授权。不满足就不启动,报错写明差什么,不换别的顶替。

报告块

步骤的作者和评审者每轮的最终消息末尾带一个报告块,引擎只按它流转:

```ail-report
{"state": "ready", "summary": "不超过 100 字的结果", "evidence": ["验证依据"]}
```
状态 去向
ready 这一步里它能做的都做完了。有评审关口就送评审;被接受后引擎收尾,然后开始下一步或结束运行
waiting 在等你回答:它已经推了一份 Review Report,回答直接进它的队列
blocked 运行保持打开,通知 Router
dropped 不做了:任务记录归档为放弃,运行结束
progress 这一轮结束了,工作还在继续。不通知任何人

报告无效,或者推进不了工作流时,引擎请这个 Worker 修正一次,仍不行就通知 Router。结束运行的报告必须带 debrief:给你看的执行报告。

叫醒

Worker 不靠 Harness 自己醒。要等一件事(一条长命令、一次部署)时,它把命令脱离到后台,报告 progress 并写 wake_after_s(10 到 3600 秒)。时刻到了,引擎给它发一条消息:看输出,没完就再报告 progress,完了就接着做。

待发的叫醒记在数据库里,Desk 重启后照原定的时刻发。一轮开始后连续 60 分钟(默认)没有任何事件,看板把它标为可能停住。

评审关口

收尾

一步被接受之后,这些事由引擎做,不占 Worker 的轮次:

  1. 这一步完成任务时,合入任务的改动;
  2. 归档任务记录;
  3. 提交并推送任务目录,只提交这个任务的路径;
  4. 记一条 Journal;
  5. 开始下一步,或结束运行。

引擎做不了其中某一件时停在那里,发消息请作者处理。

改动

多个 Worker 同时改一个仓库:主检出只前进、不切走分支;改动各在自己的 worktree 里做,做完 rebase 合入。

命令 做什么
ail worktree start <名称> 建 worktree,分支 task/<名称>,从目标分支最新的提交建出
ail worktree finish <路径> rebase 到目标分支最新的提交上,推送,快进主检出,删掉 worktree 和分支
ail worktree drop <路径> 删掉 worktree 和它的分支
ail worktree leftovers 盘点留下的 worktree

合入方式在 start 时定下:push(默认,推送到上游)、local(只在本地合入)、manual(仓库有自己的上线步骤,引擎不替作者合入)。

地图

一件要拆成很多任务的大事,由架构师规划成地图:探索图先回答没验证过的问题,执行图把事做出来。引擎照依赖派出就绪的任务,同时在做的不超过并行上限(默认 3 个)。地图上的任务受阻时不找你:引擎把报告交给架构师,由它回复。

被调用的角色

Worker 可以把读大量材料、看听媒体文件、做报告页面的活交给被调用的角色(官方默认是 brief、media、reporter)。ail call <角色> "<要它做什么>" 立即返回一个编号,做完后引擎把结果送回调用者。

Journal、组织与看板