文档目录
使用
插件
主仓、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 合同和界面保留上一次成功生成的版本。