文档目录
工作
工作流与引擎
意图、工作流与运行;报告块怎样驱动流转;叫醒、评审关口、收尾、worktree、地图与 Journal。
引擎是 Desk 里照工作流推进运行的那部分代码。确定的事都由它做:流转、叫醒、收尾、照地图派任务。模型只产出判断和内容。
意图、工作流、步骤
- 意图:你这句话要什么。Router 只按意图分类。
- 工作流:意图绑定的一串步骤。
- 步骤:一个角色做一件事。它有三个参数:
review(评审关口,作者报告 ready 后由这个角色评审,通过了这一步才被接受)、archive(这一步完成任务,被接受后引擎合入改动、归档任务记录)、chat(对话,你在会话页里直接和这个 Worker 谈)。
官方默认插件的 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 分钟(默认)没有任何事件,看板把它标为可能停住。
评审关口
- 评审者每一轮把评审写进任务目录的
reviews/,作者逐条回复。 verdict为pass:这一步被接受,引擎收尾。verdict为changes:作者修改后再报告ready,进入下一轮。- 到了轮数上限(默认 3 轮)仍是
changes时,引擎不再送评,请作者把没谈拢的每一条做成 Review Report 交你拍板。
收尾
一步被接受之后,这些事由引擎做,不占 Worker 的轮次:
- 这一步完成任务时,合入任务的改动;
- 归档任务记录;
- 提交并推送任务目录,只提交这个任务的路径;
- 记一条 Journal;
- 开始下一步,或结束运行。
引擎做不了其中某一件时停在那里,发消息请作者处理。
改动
多个 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、组织与看板
- Journal 是你的历史:每一步被接受时引擎记一条。它是主仓里的文件,按月一份。
- 工作流组织:一个不由别的运行触发的运行,加上它直接或间接触发的全部运行。报告按组织归集。
- 看板:每个运行一张卡片,按组排:需要你、直接沟通、进行中、待归档、已结束。同一个组织的卡片连成一棵树。