agent-coordinator-cli 0.2.0

# agent-coordinator-cli


`ac` 命令：把一个**有界任务**派给你自己选的 ACP harness（opencode / codebuddy / mimo / gemini …），
终端里实时看正文与工具调用，跑完留下可复查的审计记录。

## 安装


```bash
cargo install agent-coordinator-cli    # 二进制名是 ac
```

harness 由你自己装、自己登录（本工具不碰凭据）。

> 若机器上已有别的 `ac`（例如 Apple Container 的 CLI），把本工具的 bin 目录放到 PATH 前面，
> 或用 `cargo install --bin ac --root <DIR>` 装到独立前缀。

## 命令


```bash
ac run --workspace <DIR> --task <TEXT> --harness <COMMAND> [选项]
ac presets
```

`ac --help` 看全部选项。

## 一次最小运行


```bash
ac run --workspace "D:/work/ws" \
  --task "只回复两个字：收到" \
  --harness codebuddy --arg --acp \
  --minutes 3 --json
```

- `--workspace` 必须是**绝对路径**；harness 的工作目录钉在这里，工具也只能碰它。
- `--harness` 是可执行文件，**不经 shell**；它自己的参数用 `--arg` 一个个给。
- `--json` 让事件一行一条 JSON，最后再打一份结果对象，方便脚本消费。

## 常见场景


### 换一个 harness


只改启动参数，别的一个字不动：

```bash
# mimo 要显式指定模型；它的默认模型在部分账号下会静默空跑

ac run --workspace "D:/work/ws" --task "只回复两个字：收到" \
  --harness mimo --arg acp --model <MODEL_ID>

# 不知道各家怎么启动？让工具自己报

ac presets
ac presets --json
```

### 需要人点同意


```bash
ac run ... --approval ask
```

工具要动手时终端会停下来问：`y` 本次允许、`a` 本会话内都允许、`n` 拒绝。
`--approval deny` 则一律拒绝（只读任务用）。

### 续上一轮


```bash
# 用 .ac-runs/index.jsonl 里最近一条带 session_id 的记录

ac run ... --resume last

# 或者指定 id（上一轮结尾会打印「会话：…」）

ac run ... --resume ses_abc123
```

harness 不支持续会话时会**报错退出**，不会偷偷开一个新会话。

### 给它一套工具


```bash
ac run ... --mcp node --mcp-arg "./tools.js" --mcp-arg mcp --mcp-name notes
```

### 卡住时


```bash
ac run ... --timeout-secs 90     # 覆盖默认时长；超时会把 harness 及其子进程一起收掉
```

## 输出与退出码


默认（人读）：正文流式输出，工具调用/审批/用量各一行摘要，结尾给 run id 和会话 id。

`--json`（机器读）：事件一行一条；最后一份是结果对象：

```json
{
  "ok": true,
  "run_id": "run-1792752356071-cad142",
  "harness_id": "mimo",
  "harness_version": "0.1.15",
  "session_id": "ses_ffe5e97a...",
  "usage": { "tokens": 25664, "minutes": 0.25 },
  "artifacts": [],
  "events": 6
}
```

| 退出码 | 含义 |
|---|---|
| `0` | 成功（有正文或工具调用） |
| `1` | 运行失败（超时、崩了、空跑、审批被拒后无产出…） |
| `2` | 用法错误（缺参数、未知参数、`--resume last` 找不到可续会话） |

失败时 `error.code` 会说明原因（`empty_run` / `timeout` / `harness_unavailable` …）——
**不会把空跑报成成功**。

## 运行记录


每次运行在 `<workspace>/.ac-runs/<run_id>/` 下留两个文件：

- `run.json`：目标长度、harness 版本、是否成功、失败码、用量；
- `events.jsonl`：全量事件，一行一条。

不存任务原文。记录可以直接拿来做成本/成功率统计，或喂给面板。

## 相关 crate


- [`agent-coordinator-core`](https://crates.io/crates/agent-coordinator-core)：契约与运行记录（要嵌入自己的程序用这个）；
- [`agent-coordinator-acp`](https://crates.io/crates/agent-coordinator-acp)：ACP 运行时。

## 许可


MIT OR Apache-2.0。