1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
# 使用与配置
派发、收结果和对话的示例见 [agent 使用说明](../src/guide.md)。所有命令支持全局选项 `--json`;各命令的参数见 `axiopera <命令> --help`。
## 任务与工作目录
子 agent 在调用方的工作目录中运行,可用 `--cwd` 另行指定。Axiopera 不为任务建立独立的工作副本:同时修改同一仓库的任务,由主 agent 各建一个 Git worktree,再用 `--cwd` 指定。
主 agent 负责检查子 agent 的改动、提交和合并分支。子 agent 的权限由 `--tier` 指定,默认 `work`。各档位在不同 backend 上的具体行为见[权限](backends.md#权限)。
空闲后用 `axiopera send <task> --tier full "继续执行"` 在原会话中改档续接。AGY 进出 read 档需要新建任务。子 agent 只能修改自己直接派发的任务;降低父任务档位前,先降低超出新档位的子任务档位。
任务 ID 全局唯一,`--name` 指定的别名在同一个调用方下唯一。主 agent 为第 0 层,最多派发到第 2 层,只统计 Axiopera 任务。宿主内置子 agent 归属于所在的 Axiopera 任务,它再派发的任务继续受该任务树的深度和权限限制。子任务的档位不能高于父任务。内置子 agent 的收件隔离见[后端文档](backends.md#会话与消息)。
子 agent 用 `ask` 提问后可以继续工作。若这一轮结束时仍有未回答的问题,任务进入 `waiting`;回答送入所属任务的主会话,在执行中插入或在空闲时开启下一轮。原生子会话的提问也按所属任务路由,可用 `answers` 查询回答。兄弟任务通过 `tell` 留言,父节点收到抄送。接收方空闲时,留言等到下一轮开始才送入,不会单独开启一轮。
`spawn`、`send`、`reply` 接受位置参数、`-f FILE` 或单独的 `-`。后两种分别读取 UTF-8 文件和标准输入,保留原始换行。三种来源只能选一种,内容不能为空。
## 结果与接管
`wait` 阻塞到有新消息,列出后退出,不取走任何内容;`inbox` 取走已有消息,没有新消息时直接返回。`watch` 每有新消息就输出一行摘要,一直运行到被停止,同样不取走;子 agent 的 `watch` 在子任务都结束、消息都取走 1 分钟后自行退出。每轮结果经 `inbox`、`result` 或宿主推送交付后,再次 `result` 只返回文件路径。需要重新查看正文时用 `result <task> --turn N --force`。
`watch --status` 跟踪调用方正在执行和排队的任务,每 2 秒检查一次,输出有变化的状态和进度,包括监听期间新增的任务及已跟踪任务的结束状态。没有执行或排队的任务时以退出码 0 结束,未收取的消息不影响退出。停止监听不会取消任务。Codex 的后台显示见[宿主通知](backends.md#宿主通知)。
回复长度有上限。等你裁决的审批请求总是先给,其余消息按先后取,一次回复放不下的整条留到下一次 `inbox`,回复末尾注明还剩几条。单条结果超长时只保留末尾,并注明显示的字符数、总字符数和完整文件路径;过长的提问、留言和审批请求给开头和结尾,并注明全文路径。`status` 查看任务状态和所用模型、推理强度,运行中的任务附带进度:第几轮、本轮已用时间、工具调用次数,以及最近一次调用和距今时间;一轮结束后进程仍在等后台工作时,注明上一轮结束了多久;没有新消息时,`inbox` 和 `wait` 超时也列出这些进度。`inbox` 和推送交付的每轮结果、`log` 中的轮次结束行同样注明该轮结束时的模型和推理强度,`top` 在任务详情的标题中显示,窗口放不下任务状态时先省去。会话启动、子 agent 报告之前,显示的是请求值(`--model`、`--effort` 或配置),未指定则不显示。`log` 查看事件摘要,每个事件一行,包括子 agent 每段话的开头,换行显示为 `↵`,命令等自由文本截到 200 个字符并注明省略了多少。加上 `--json` 可以读取完整任务字段和事件字段,包括改动文件列表及后端上报的用量。
`detach <task>` 将任务交给人接管,并打印工作目录和原生 resume 命令。接管前要等任务执行及后台工作结束,或先 `cancel`。Axiopera 发现原生会话文件被其他进程修改时,也会将任务标为 detached。
`cancel` 停止任务及其子任务当前的执行,保留会话和未交付输入。`cancelled`、`failed` 和 `interrupted` 任务都可以用 `send` 继续,回答未解决的问题也会续接任务。继续父任务不会自动启动已取消的子任务,需要分别续接。脱管的任务通过原生 CLI 接管。
退出码见 [guide](../src/guide.md)。带消息的输出总以 0 退出:宿主对非零退出的输出截得更短,Windows 上的 Codex 还把所有非零退出码报成 1。
## 人工查看
在另一个终端运行 `axiopera top`,每秒刷新,每个任务固定一行,子任务缩进在上级下面。会话组按最近一次派发任务(含子任务)的时间从新到旧排列,组内顶层任务和同级子任务也从新到旧,子任务紧跟父任务;状态变化和新输出不触发重排。默认列表与 `--all` 使用相同顺序,停在首条任务时跟随新任务;向下选阅后保留当前选中项及其屏幕位置(列表边界处会调整),向上回到首条任务或按 Home 恢复跟随。任务按会话分组,单会话也显示组名,选到会话首条任务时带出组名。组名前列出这组任务所在的项目,即工作目录所在 Git 仓库的目录名,worktree 算作它的主仓库,不在仓库里的用工作目录名;终端派发的任务归在 `user` 下,识别不到会话的 agent 也会落在这里(见[指定调用方](#指定调用方))。每行依次是名称、ID、状态和子 agent 最近说的一段话,没有名称的任务在名称处显示 ID;agent 调用命令时用的是 ID,可以据此对上任务。说的话合成一行显示,之后提出的未回答提问优先显示,事件里已没有它说的话时显示最近一轮结果的第一行。状态 `approval` 表示有待裁决的审批,`stalled` 表示运行中长时间没有动静。颜色只用于状态和话里的 markdown 格式,格式同详情。默认只列出未停止或 1 小时内有变化的任务,`--all` 列出全部。窗口放不下时显示连续的一段,随选择滚动,底部注明可见行的位置。
上下方向键或 `j`、`k` 选择任务,选中的行反色显示,到达窗口边缘时滚动。PageUp/PageDown 按一屏移动,Home/End 到首末任务;回车或右方向键在同一个终端打开它的详情,Esc、`q`、左方向键或退格返回列表。在列表中按 `q` 退出,Ctrl-C 随时退出。详情中,上下方向键或 `j`、`k` 按行滚动,PageUp/PageDown 按屏翻页,Home 到开头,End 到末尾。默认跟随最新输出;向上翻后停在阅读位置,底部显示 `paused`,回到末尾后恢复 `live` 跟随。审批和回答仍用命令完成,`top` 里不能操作。标准输入不是终端时,例如没有 ConPTY 的 mintty,`top` 不响应按键,只能用 Ctrl-C 退出;列表放不下时优先显示待处理、运行中、出错的任务,同级优先显示新任务,连同上级一起显示。
`axiopera top <task>` 直接打开一个任务的详情,`<task>` 是 ID,没有重名时也可以用名称,返回后是列表。详情第一行是名称、ID、agent、状态和本轮进展;下面列出等你处理的事,`needs` 待裁决的审批,`asks` 未回答的提问,停下的任务列出错误 `error` 或停止原因 `why`。再往下是对话,排版参照 Codex:派发时的任务文本以 `›` 开头,首轮开始前追加的消息并在其中,之后发给子 agent 的消息同样以 `›` 开头;子 agent 说的每段话以 `•` 开头,段与段之间空一行,最新的在最下面;从第二轮起,每轮开头有一行分隔,注明轮次和距今多久,下面是开启这一轮的消息。消息由 daemon 完整保存;0.2.2 及更早的 daemon 不保存消息,那时的轮次只有分隔行。每轮最后一段话就是这轮的结果,完整取自结果文件,结果为空时保留原话;没有发言记录的旧任务也显示最近一轮结果。其他段落是 daemon 记录的,每段只记前 500 个字符,超出的部分截去,末尾标 `…`。话里的 markdown 不显示标记,用格式表示:粗体、斜体、标题、列表、引用、代码块和行内代码;表格按列对齐,放不下时照原样折行。链接显示文字,网址和与文字不同的文件路径在后面括号注明。工具调用挂在前一段话下面,每次一行。daemon 每次只记前 400 个字符;一行按窗口宽度截断,两种截断末尾都标 `…`。常见工具名统一成动词,命令都显示为 `Run` 加命令,Codex 在外面包的 PowerShell 调用已去掉。链接和工具调用里,任务目录下的路径写成相对路径。子任务不在详情里,在列表中看。详情可翻阅当前保留的最近 300 条消息、工具调用和轮次记录,以及任务文本;标题和待处理事项固定,只有对话滚动;待处理事项超过半屏时,放不下的排在对话前面一起滚动,固定部分末尾注明还有几项。不能读取按键的终端保留最新几段,超屏时注明省略内容。输出不是终端时只打印一屏,其中任务文本完整,只取最近 20 段话和其间的工具调用。
`top` 只读取数据目录,不连接 daemon:不会启动 daemon,不取走消息,不标记结果已交付,也不写请求日志。daemon 异常退出后,任务停留在退出前的状态,下次启动时才改为 interrupted。
其他命令中,`status --all` 和 `log` 同样不改变交付状态。`result` 会把该轮标为已交付,主 agent 之后只拿到文件路径。`inbox` 取走调用方的消息:在 Claude Code、Codex、Grok、AGY 的命令工具或它们启动的 shell 中,调用方是该会话;在独立终端中是 `user`,即你本人。识别不到会话的 agent 要用 `--caller` 指明会话,见[指定调用方](#指定调用方)。
## 指定调用方
调用方身份决定任务名称的作用范围、`status` 列出的任务和 `inbox` 取走的消息。Axiopera 从 Claude Code、Codex、Grok、AGY 注入命令环境的会话变量识别调用方,经 ssh、`docker exec`、WSL 等调用另一处的 Axiopera 时,这些变量通常传不过去,agent 会被当成终端前的你(`user`):与终端共用收件箱,审批时也像你一样不必先读全文。这时用全局选项 `--caller <名称>:<会话 ID>` 指明会话,每条命令带同一个值,变量在宿主一侧展开:
```sh
ssh 主机 axiopera --caller "claude:$CLAUDE_CODE_SESSION_ID" spawn codex --cwd /srv/app - < task.md
ssh 主机 axiopera --caller "claude:$CLAUDE_CODE_SESSION_ID" wait # 后台运行
ssh 主机 axiopera --caller "claude:$CLAUDE_CODE_SESSION_ID" inbox
```
四家的会话 ID 分别在 `CLAUDE_CODE_SESSION_ID`、`CODEX_THREAD_ID`、`GROK_SESSION_ID`、`ANTIGRAVITY_CONVERSATION_ID` 中。`--caller claude:<ID>` 与在命令前设置 `CLAUDE_CODE_SESSION_ID=<ID>` 是同一个调用方,此前这样派发的任务可以接着操作。其他 agent 同样要用自己的名称和会话 ID 指明会话,没有会话 ID 时生成一个随机值并一直沿用。取值规则及子 agent 中的限制见[身份与 IPC](design.md#身份与-ipc)。
Axiopera 不负责连接、认证和文件同步。`--cwd`、`-f` 和结果中的路径都按运行 Axiopera 的一侧解释。Windows 的 Git Bash 会把传给 `wsl.exe` 等原生程序、以 `/` 开头的参数改写成 Windows 路径,这时设置 `MSYS_NO_PATHCONV=1`。子 agent 使用该侧调用命令的环境,非交互 ssh 的 PATH 可能找不到 agent CLI,这时在[配置](#配置)中指定 `path`。ssh 断开后 daemon 和任务继续运行,前提是系统不在登出时结束用户进程,例如 systemd-logind 未启用 `KillUserProcesses`。跨机器时各宿主怎样收到结果,见[宿主通知](backends.md#宿主通知)。
## 配置
数据目录默认为 `~/.axiopera/`,环境变量 `AXIOPERA_HOME` 可以覆盖它。配置文件是该目录下的 `config.toml`,所有字段均可省略。以下三项是默认值:
```toml
concurrency = 50
stall_minutes = 10
approval_timeout_minutes = 2
```
`concurrency` 是同时运行的顶层任务上限,所有会话共用,嵌套任务不计入。它用于防止失控派发:达到上限时新的 `spawn` 直接报错,不排队;已有任务经 `send` 或 `reply` 开始的新一轮不受限制。
每次启动子 agent 时开始计时。2 分钟仍未见发言或工具活动,任务标为 `stalled` 并通知调用方一次,子任务继续运行。启动握手和首轮确认都算在这段时间内。收到发言或工具活动后清除标记,此后连续 `stall_minutes` 分钟没有活动才再次提醒,默认 10 分钟,最小 1 分钟。`stall_minutes` 为 1 时,首次提醒也在 1 分钟后。
`spawn --timeout` 在每次启动执行达到时限后中断任务及仍在执行的子任务,状态为 `interrupted`;用 `send` 在原生会话中续接,新一次执行重新计时。手动 `cancel` 后同样可以续接。
每个 backend 可以设置默认模型和可执行文件路径。例如:
```toml
[agents.claude]
model = "haiku"
# path = "/absolute/path/to/claude"
```
同样支持 `[agents.codex]`、`[agents.grok]`、`[agents.agy]`。`--model` 覆盖默认模型。`path` 必须指向真实可执行文件;Windows 上应使用 `.exe`。省略时按[后端的路径查找规则](backends.md#可执行文件与配置继承)定位。
AGY 新任务默认沿用终端 `/model` 保存的模型和强度。`--model` 或 `[agents.agy].model` 选中同一模型时保留终端强度,选中其他模型时使用该模型自己的默认强度。`--effort` 始终优先。续接已有任务沿用任务自身的选择。
`axiopera models <agent>` 查询模型 ID 和支持的推理强度。别名有解析结果时显示为 `别名 → 具体模型 ID`;重复名称省略,说明保留在 `--json`。首行写明不带 `--model` 派发时使用的模型:有 Axiopera 配置时是配置值,否则是原生 CLI 按用户自己的设置选出的模型和推理强度。列表中的 `account default` 是 Claude 的账户默认入口,`backend default` 是 Codex 目录的默认,二者不一定是派发所用的模型。Grok 的默认模型可能在查询之后变化,任务实际所用以 `status` 和每轮结果为准。`--cwd` 指定工作目录,默认当前目录。
查询沿用后端的目录发现和缓存,最多等待 20 秒。模型 ID 可直接用于 `spawn --model`,列表中的推理强度可用于 `--effort`。参数仍按原样传给后端。后端明确报告模型或推理强度无效时,错误后附查询结果;自动查询最多等待 5 秒,失败或返回空列表时附查询命令。认证、权限、额度和网络错误保持原报错。
daemon 启动时读取配置。修改后运行 `axiopera daemon stop`,下一次调用会重新启动。未知配置项会报错。
## Skill 与 Codex 插件
skill 让 agent 在派发任务前先运行 `axiopera guide --host <宿主>`,效果与在项目说明中写明这一点相同。`--host` 只输出该宿主取结果的方式,不带时输出全部宿主的。
运行 `axiopera skill install <宿主>`,将程序内置的 [`SKILL.md`](../plugins/axiopera/skills/axiopera/SKILL.md) 离线写入下表目录,新开会话即可使用:
| agent | 宿主参数 | 安装位置 |
|---|---|---|
| Claude Code | `claude` | `~/.claude/skills/axiopera/` |
| Codex | `codex` | `~/.agents/skills/axiopera/` |
| Grok | `grok` | `~/.grok/skills/axiopera/` |
| Antigravity CLI | `agy` | `~/.gemini/config/skills/axiopera/` |
`~` 取 Windows 的 `USERPROFILE`,其他平台取 `HOME`。命令使用表中的固定位置;自定义 skill 目录可手动复制文件。Grok 默认也读取 Claude Code 和 Codex 的上述位置,已有一份时可直接使用。
`axiopera skill install all` 依次安装到全部三个目录,逐项输出结果;某一项失败后继续处理其余项,最终返回非零退出码。
重复安装时,内容相同则跳过;内容不同则提示加 `--force` 确认覆盖,也适用于 `all`。命令只写 `SKILL.md`,输出文件路径。`--json` 在单宿主时输出对象,`all` 时输出数组;每项包含 `host`,成功时带 `path` 和 `changed`,失败时带 `error`。删除安装目录即卸载。
每个会话的上下文都会列出 skill 的名称和描述,约占一行。
Codex 插件包含同一个 skill,另带 hook,让宿主在一轮进行中也能得知子任务的消息。装了插件就不必再复制 skill。插件不包含 `axiopera` 程序。
- 安装:`codex plugin marketplace add Victor-Quqi/Axiopera`,再 `codex plugin add axiopera@axiopera`。
- 卸载:`codex plugin remove axiopera@axiopera`,再 `codex plugin marketplace remove axiopera`。
hook 信任后才运行。桌面端在插件页信任;TUI 启动时发现新的或改动过的 hook 会弹出确认,也可以在 `/hooks` 中信任。hook 定义改动后需重新信任;Codex 0.164 起,插件中任何文件改动都需重新信任,包括升级插件。工具调用之后,如果有新的结果、提问或审批请求,hook 列出每条的一行摘要,提醒宿主运行 `inbox`;一轮结束时仍未取走的,由门铃在本轮结束后提醒。
装了插件后,Codex 每个会话都会启动一个 `axiopera mcp --codex-hooks` 进程。hook 只查询已在运行的 daemon,不会启动它;没有相关任务时立即返回。实测进程启动不到 0.1 秒,每次 hook 调用不到 1 毫秒。删除 `axiopera` 程序前先卸载插件,否则 Codex 无法启动这个进程。卸载不会结束已打开会话中的这个进程,需要时手动结束。
Codex 卸载插件后会留下以下内容,运行 `axiopera plugin cleanup` 清除:
- `config.toml` 中 hook 的信任记录 `[hooks.state."axiopera@<来源>:codex/hooks.json:…"]`。如果保留,重装定义相同的插件时会直接沿用旧的信任。
- `.hook-trust/` 下插件内容的基线(Codex 0.164 起)。Codex 用它核对旧版本写下的信任记录。
- 空目录 `plugins/cache/axiopera`。
数据目录取 `CODEX_HOME`,未设置时为 `~/.codex`。插件仍装着时,清理命令不做任何处理。配置通过 Codex 自己的配置接口修改。
## daemon 与清理
CLI 按需启动 daemon。没有运行中的 agent 和客户端连接时,daemon 空闲 10 分钟后退出。主会话退出不会取消已派发的任务。
`axiopera daemon status` 查看 daemon,`daemon stop` 在没有运行任务时停止它。`daemon stop --force` 会中断正在运行的任务,之后可用 `send` 续接。升级二进制前先停止 daemon。
Axiopera 自动删除 30 天未活动且已停止的任务,以及请求日志 `daemon/requests.jsonl` 和 daemon 日志 `daemon/daemon.log` 中 30 天前的行。`axiopera gc` 立即删除所有已停止的任务和请求日志,`--days N` 保留最近 N 天有活动的。运行中或即将开始运行的任务,以及仍有子任务的父任务,都不会被删除;收到兄弟任务的留言也算一次活动。任务删除后不能再对它 `send`、`result` 或 `log`。
`daemon.log` 在启动及每 24 小时裁剪旧记录,并按 4 MiB 轮转;可选的 `protocol.log` 按 16 MiB 轮转,各保留一个 `.log.1` 备份。超过单文件上限的诊断行截断并注明。任务事件、输入和结果不按容量截断,随任务一起清理。
卸载前先停止 daemon。通过 Cargo 安装的执行 `cargo uninstall axiopera`;通过 Release 压缩包安装的删除可执行文件。数据目录按需删除,原生 agent 的会话仍由各自 CLI 管理。