CLI 参考

以本机 ageval --help 为准。TTY 下命令打短 recap（不含 digest / sha256）；管道仍是 JSON。ageval run --json 强制完整文档。

ageval tasks <dataset>
ageval prepare <dataset> [--allow-prepare]
ageval lock <dataset> --task <id>
ageval lock <dataset> --task <id> --probe
ageval run <dataset> --task <id>
ageval run <dataset> --task <id> --probe
ageval run <dataset>                         # 整份 dataset
ageval run official/demo@0.1.0 --dir tmp --task <id>
ageval run <dataset> --max-concurrent-tasks 2
ageval run <dataset> -k 5                    # Always-k（每题 k 次）
ageval run <dataset> --task <id> --resume <attempt_id>
ageval checkpoints <dataset> --run <attempt_id>
ageval replay <dataset> --run <attempt_id> [--evaluate]
ageval run <dataset> --task <id> --fork <attempt_id> --checkpoint <seq> --model <model_id>
ageval run <dataset> --resume-suite <suite_run_id> --task <id> -k 5
ageval run <dataset> --resume-suite <suite_run_id> --retry-errors
ageval results regrade <dataset> --run <attempt_id>
ageval campaign <dataset> --task <id> ...
ageval status <suite_run_id> --dataset <dataset>
ageval cancel <suite_run_id> --dataset <dataset>
ageval executors -v
ageval plugin install <path|ref>
ageval plugin list
ageval plugin uninstall <plugin_id>
ageval agent install <path|ref>
ageval agent list
ageval agent uninstall <agent_id>
ageval evidence --help
ageval view <dataset|directory|id@version> [--dev] [--open /jobs/<id>]
# Harbor 任务目录或任务集：view 直接打开它和其中的 .ageval/suite-runs。
# run / lock 读取这棵树时仍要写 --layout harbor。
ageval jobs delete --local <dataset> --job <id> --yes
# Registry / 结果（需 login）
ageval publish <dataset> --org <org> [--draft] [--public] [--replace]
ageval publish --repo github:org/repo@v1.0.0 [--public]
ageval release <dataset_id> [--public] [--replace]
ageval registry list|show|set-visibility|delete|org-create|org-list|org-add-member|org-set-role|org-transfer|org-remove-member …
ageval results upload-suite <dataset|id@version> --suite-run <8-hex>
ageval results analyze <dataset> (--run <id> | --suite-run <id>) [--analyzer stats|hack|review]
ageval results upload|attach-agent|request|inbox|decide|share|unshare|set-visibility|delete …
ageval results share-snapshot <dataset> --suite-run <id> [--run <run_id>] [--live]
ageval results sync-snapshot <dataset> --suite-run <id> [--heartbeat]
ageval results revoke-snapshot <token-or-url>

路径 = dataset 根（含 ageval.yaml）。run / lock / view / upload-suite 也可是 Hub ref（id@version）或钉版 git 源（github:org/repo@<tag|sha>、https://…@<tag|sha>，可选 #<subdir> 选择仓库内一个 Dataset）；分支引用会被拒绝，https URL 也不能内嵌 userinfo。--dir 只配合 Hub ref。tasks / campaign 仍是本地目录。publish --repo <git ref> 只把源注册到 Hub，不上传文件。run / lock 会先执行数据集准备（按 sha256 校验下载声明的 assets）；声明了 prepare 脚本时需要 --allow-prepare。--agent 与 --profiles 互斥。--model 须配合 --agent。ageval agent install 还会安装包声明的非 contrib 插件。删除类命令须显式 --yes；同 identity 覆盖须显式 --replace（默认 409）。AGEVAL_REGISTRY_URL / --registry-url 覆盖 Registry 源；省略则连公开 Hub（https://ageval.zjureal.com）。

results analyze 读一次已经落盘的运行（--run）或一份 suite（--suite-run），写入 analysis/<analyzer>/report.json。suite 还会写 analysis/<analyzer>/summary.json。默认 analyzer 是 stats。hack 和 review 可以调用现成的 openai-http 或 anthropic-http Agent：加上 --agent 和 --model（该包没有 model 时必填）。--base-url 覆盖该绑定，且必须是 http(s) URL。这里的 --model 不是 ageval run --model，也不是 results upload-suite --model。分析不改变 PASS，不改 evaluation/checks.json，Hub 也不上传这些文件。

share-snapshot 打印 {hub}/s/{token}，不改这份 suite 的公开或私有，也不会把它放上榜。sync-snapshot 用来更新 live 链接。详见 Hub。

--layout harbor 下，内置 run 把 instruction.md 全文交给角色 solver，只调用一次。角色 id 固定为 solver。绑定来自路径根上的 profiles.yaml、--profiles 或 --agent（solver 或 *）。三处都没有这份绑定时，锁定失败（missing_binding）。--oracle 在 environment 阶段执行 solution/solve.sh，不再把 instruction.md 交给 Agent。

`ageval run` 常用选项

选项	含义
`--task <id>`	只跑该成员；省略 = 整份 dataset 跑完。`--layout harbor` 下可重复
`--layout harbor`	直接读未改过的 Harbor 任务目录，或一叠任务目录的父目录。省略则仍是 ageval 包。单个 Harbor 任务不能再写 `--task`。`registry.json` 索引会被拒绝
`--oracle`	仅配合 `--layout harbor`：跑 `solution/solve.sh`，不再调用 Agent。省略时不使用 `solution/`
`--max-concurrent-tasks N`	并行上限；只加速，不改 k / PASS
`--n-attempts` / `-k N`	Always-k：每题 N 次独立运行（默认 1）；只写在 CLI / job 上
`--resume <attempt_id>`	原地继续这一次尚未封存的 Attempt。必须配一个 `--task`。`result.json` 已存在、锁定摘要不一致、或环境仍在跑这次 Attempt 时 exit 2，不写 `result.json`
`--resume-suite <suite_run_id>`	继续已有 suite：跳过已以 PASS / FAIL / ERROR 结束的槽位。活动日志与本次 suite、task、attempt index 匹配的未结束槽位原地继续；没有匹配日志则新开一次 Attempt。重算 pass@k / pass^k
`--retry-errors`	配合 `--resume-suite`：重跑本次过滤里的 ERROR 格。PASS / FAIL 仍跳过。新的一次运行；旧行进 `previous[]`
`--replace-slot`	配合 `--resume-suite --task`：重跑那一行；新的一次运行；旧行进 `previous[]`
`--attempt-index N`	Always-k 要换的格（默认 0）。只与 `--replace-slot` 一起用
`--keep-workspace`	清理后保留环境工作根（默认删除）。不保留 `activity.jsonl` 或 `checkpoints/`。
`--keep-recovery-state` / `--no-keep-recovery-state`	`result.json` 和 `trajectory.jsonl` 都写出之后，保留或删除 `activity.jsonl`、`checkpoints/` 与 `replay-input.json`。默认删除。中断的 Attempt 始终保留这些文件，`--resume` 不依赖这个开关。未显式指定时回退到 `AGEVAL_KEEP_RECOVERY_STATE`。与 `--keep-workspace` 独立
`--keep-vendor-raw`	封存后保留 vendor raw 与中间调用事件文件；默认丢掉。`task-artifacts/` 两种情况下都保留。与 `--keep-workspace` 独立
`--dir <path>`	只配合 Hub ref：在 `<path>/<dataset_id>/` 找包；已匹配则复用
`--agent`	绑定 `ageval.agent/1` Agent 包（`pi`、`org/name@version` 或本地路径）；与 `--profiles` 互斥
`--fork <attempt_id>`	从该次 Attempt 保留的检查点新开一次 Attempt。必须配合 `--checkpoint` 和 `--model`。与 `--resume` 互斥。拒绝 `--agent` 和 `--profiles`

ageval replay <dataset> --run <attempt_id> 在新环境里重新执行保留的终端动作，不调用求解模型。--evaluate 给新产物打分。不带这个开关时，完成不是 PASS 或 FAIL。源 Attempt 不变。默认 pass@k 不计入这次子 Attempt。 | --checkpoint <seq> | 要分叉的活动序号。该切点必须是 solver 封存前已完成的 run 阶段快照 | | --model | 改这次 run 已绑角色的 model.id；须配合 --agent。--fork 时它只改续跑模型，不换 harness，也不要求 --agent。不是 results upload-suite --model。results analyze --model 是另一条参数，同样必须配合 --agent | | --set / --profiles | 覆盖项 / 换一份配置文件 | | --probe | 只做可行性：按绑定 / environment 打印 plan + readiness。不 invoke Agent、不写入镜像、不改 lock digest。选中路径不满足则 exit 1。 | | --json | stdout 打完整结果文档。TTY 默认是短 recap（整份跑完时含 summary 路径与 ageval view / upload-suite）；管道默认仍是 JSON。 |

`status` / `cancel`

命令	含义
`ageval status <run_id\|suite_run_id>`	进度记录；整份跑完时可加 `--dataset` 读 `progress.json`
`ageval cancel <run_id\|suite_…>`	一次运行或整份 job；整份跑完时可加 `--dataset` 写 `cancel.requested`

`--set`

格式：<JSON Pointer>=<JSON 值>，可重复。

指针	含义
`/parameters/seed`	业务 seed 等
`/parameters/harbor_oracle`	仅 `--layout harbor`：与 `--oracle` 相同
`/parameters/active_profile`	切换 profile
`/agent_profiles/<role>/model`	嵌套 model 对象
`/agent_profiles/<role>/model/id`	模型 id
`/agent_profiles/<role>/model/api`	`chat` 或 `responses`
`/agent_profiles/<role>/model/timeout`	单次 HTTP 时钟
`/agent_profiles/<role>/model/watchdog`	中止时钟
`/agent_profiles/<role>/model/reasoning/effort`	思考档位。省略表示不发送。`max` 是 pin 里的最高档
`/agent_profiles/<role>/executor`	executor id
`/agent_profiles/<role>/api_key`	环境变量名
`/agent_profiles/<role>/base_url`	字面 URL 或环境变量名
`/agent_profiles/<role>/options/<key>`	job binding 覆盖（含 `entry`、插件 `agent` 等；ACP 仍拒绝 `command` / engine 键）
`limits.*`	三个阶段计时器、`agent_invocations` 与 `agent_concurrency`（不可覆盖 — 见下）

Intent limits.* 不能经 --set 覆盖。其它指针在 lock 阶段失败。

细节：src/ageval/cli/README.md · skill ageval-cli。

ageval run 常用选项

status / cancel

--set

本页目录

`ageval run` 常用选项

`status` / `cancel`

`--set`