文档目录

使用

插件

主仓、Repo 的登记、官方默认插件;种子、同步,以及改动怎样生效。

不换可执行文件就能改的东西都在插件里:Repo 的登记、角色、工作流、Harness 定义、提示词、界面。插件是插件目录里的 Git 仓库。

三种插件

插件 id 是什么
主仓 main 全局入口:登记其余所有插件,放 Journal,也放你自己的内容
官方默认插件 official 系统自带的一套角色、工作流、Harness 定义、提示词、Router 合同的规则和基础界面。全局只有这一套
Repo 插件 登记时定 一个要在里面干活的 Git 仓库

主仓

main/
  ail.yaml               格式的版本
  AGENTS.md              给派到主仓的 Worker 的说明
  repos/<repo id>.md     每个 Repo 一份登记
  journal/<年>-<月>.md   Journal
  skills/<名>/SKILL.md   你自己的做事方法,可以没有

一个符合这个格式的 Git 仓库就是全部的入口。在一个新装的系统里把它的链接填进「主仓」,Daemon 克隆它,再照登记把每个仓库克隆下来。

Repo 的登记

主仓的 repos/<repo id>.md,一个 Repo 一份:

---
schema: 1
id: billing
name: Billing
description: 账单服务与它的管理页面
git: git@example.com:team/billing.git
aliases: [bill]
intents: {disable: [upgrade]}
---

给 Router 和 Worker 的补充说明,可空。
字段 必填 含义
id 是 小写字母、数字、连字符;也是插件目录下的目录名
name 是 名字
description 是 一句话:这个仓库是什么、什么事该派给它。Router 靠它选 Repo
git 否 Git 链接。不写就是只在本地的仓库
aliases 否 别名
meta 否 它归属的 Meta 仓的 id
intents、roles 否 {only: […]} 或 {disable: […]}:这个仓库只接受、或不接受哪些意图和角色
archived 否 true:不再出现在项目表里,不能派发

接入一个 Repo 最少只要 Git 链接、名字和描述:

ail repo add --git git@example.com:team/billing.git --name Billing --description "账单服务与它的管理页面"

所有 Repo 平铺,没有嵌套。Meta 仓与关联仓的关系只写在关联仓的 meta 上。

官方默认插件

official/
  workflows.yaml         意图、工作流、被调用的角色、几个上限
  roles.yaml             每个角色的绑定
  harnesses.yaml         Harness 定义
  roles/<角色>.md        角色说明
  frames/                第一条消息的框架
  prompts/               全局提示词与共同原则
  router/contract.md     Router 合同的规则
  ui/shell/              基础界面

roles.yaml 把每个角色绑到一台 Client 上的一个 Harness:

schema: 1
default_client: studio-pc
roles:
  router:   {harness: codex, model: <模型>, thinking: medium}
  execute:  {harness: codex, model: <模型>, thinking: xhigh}
  media:    {client: media-pc, harness: antigravity, model: <模型>}

一个角色的绑定是四项:在哪台 Client 上启动、用哪个 Harness、哪个模型、多大的思考强度。model 和 thinking 写这个 Harness 在 ACP 里列出的选项;值对不对在建会话时核对,不对就失败。

种子

官方默认插件随可执行文件带一份,叫种子。插件目录里没有它时,Daemon 建一个本地 Git 仓库,把种子提交在 seed 分支上,再从它分出 main。你和 Agent 的改动提交在 main 上。

换了新版可执行文件后,Daemon 把新种子提交到 seed,再合并进 main。有冲突或有未提交的改动时不合并,在 Config 页写明,由你或派去的 Agent 合并。这样升级不会盖掉你改过的角色、工作流和界面,新版自带的改动也到得了你手里。

同步

ail plugin sync 或 Config 页的同步按钮:主仓能快进就快进;照登记克隆缺的仓库,快进能快进的。不强推、不丢改动;一个仓库失败不影响别的。

改动怎样生效

改了什么 怎样生效
Repo 的登记 校验;Router 合同重新注册;新登记的 Repo 自动拉取
workflows.yaml、roles.yaml 校验;下一次派发、下一步照新的做;Router 合同重新注册
harnesses.yaml 校验;下一次建会话照新的做
角色说明、框架、提示词 下一个启动的 Worker 的第一条消息照新的渲染
界面插件的源码 Daemon 重新构建,打开着的页面收到通知,刷新后是新版

不用重启。已经启动的 Worker 不受影响:它的角色说明在它的第一条消息里。

文件格式不对时,要用到它的动作立即失败,报错写明哪个文件、哪里不对。Router 合同和界面保留上一次成功生成的版本。