Codex
110 lines
6.5 KiB
Markdown
110 lines
6.5 KiB
Markdown
# AgentRun 资源原语
|
||
|
||
新 Code Queue 工作统一使用 AgentRun 资源原语：
|
||
|
||
- `agentrun create|apply`：创建 task 或应用 AipodSpec manifest；
|
||
- `agentrun get|describe`：有界读取列表和详情；
|
||
- `agentrun describe task/<taskId> --input -o json`：读取可重建 task 输入、AipodSpec identity、资源引用和脱敏 provenance；
|
||
- `agentrun describe aipodspec/<name>`：读取同构、有界且 SecretRef-only 的 AipodSpec 摘要；
|
||
- `agentrun events|logs|result`：渐进披露运行证据；
|
||
- `agentrun get attempts --task <taskId>`：读取同一 task 的不可变 attempt 历史；
|
||
- `agentrun retry task/<taskId> --idempotency-key <key> --reason <text> [--dry-run]`：对终态失败 task 创建下一次 attempt；
|
||
- `agentrun dispatch|ack|cancel`：控制生命周期。
|
||
|
||
## Artificer Target 单命令派单
|
||
|
||
标准入口：
|
||
|
||
```bash
|
||
bun scripts/cli.ts agentrun create task \
|
||
--aipod Artificer \
|
||
--target <Target> \
|
||
--target-workspace <absolute-task-worktree> \
|
||
--repo <owner/repo> \
|
||
--ref <branch> \
|
||
--mdtodo-id <R6.3> \
|
||
--prompt-stdin \
|
||
--dry-run
|
||
```
|
||
|
||
- 先用同一命令保留 `--dry-run` 查看完整计划；
|
||
- dry-run 与 live 都必须先经 owning YAML 选中的 Target `trans` 重入；
|
||
- preflight 必须验证：
|
||
- task worktree 是 Git 根目录且 clean；
|
||
- origin 与 `--repo` 一致；
|
||
- current branch 与 `--ref` 一致；
|
||
- HEAD 与 origin 远端 ref commit 一致；
|
||
- preflight 输出必须披露：
|
||
- Target route、repo/ref、projectId、HEAD/remote 关系；
|
||
- 合法的 `workspaceRef.kind/path`；
|
||
- 从 AipodSpec 继承的默认 resource bundle；
|
||
- session identity；
|
||
- provider/tool SecretRef 的对象、key 与 presence；
|
||
- preflight 失败固定 `mutation=false`，不得创建 task；
|
||
- live 在 submit 成功后自动 dispatch，不要求用户再运行第二条命令；
|
||
- 未显式传 `--idempotency-key` 时，由 Target/repo/ref/MDTODO/verified commit 派生稳定键；
|
||
- 幂等重试遇到已有 running 或 terminal task 时，返回既有 attempt/run/session，不重复 dispatch；
|
||
- 最终输出必须包含 task、attempt、run、command、runner 和 session identity。
|
||
- Target live 的默认 human、`-o json` 和 `-o yaml` 使用同一份有界投影：
|
||
- 保留 task、attempt、run、command、runner、session 的 identity 与 state；
|
||
- 保留自动派单决策、Target/MDTODO 摘要、Aipod 与 SecretRef presence 摘要；
|
||
- `Next` 使用本次派单的具体 identity，并继承 Target 与 lane；
|
||
- 不展开完整 task、prompt、payload 或 Aipod 对象；
|
||
- 需要完整服务端对象时显式使用 `--raw`。
|
||
|
||
Artificer 内部执行边界：
|
||
|
||
- primary workspace 只承载默认 UniDesk bundle、`tools/trans` 和 required skills；
|
||
- 任务源码操作全部使用 `trans <Target>:<targetWorkspace>`；
|
||
- `targetWorkspace` 必须是任务专属 worktree；
|
||
- runner 本地结果不得替代 Target 原入口证据；
|
||
- `unidesk-trans`、runner tools bundle、`unidesk-ssh` SecretRef 和 endpoint presence 必须同时存在；
|
||
- Secret 值不得进入 prompt、task、日志或报告。
|
||
|
||
`agentrun events` 是高频渐进披露入口：
|
||
|
||
- 默认 human、`-o json` 和 `-o yaml` 最多返回 20 条同构事件摘要，并用一条 lookahead 披露 `hasMore` 与 `nextAfterSeq`；
|
||
- tool call 只展示 identity、seq/type/status、commandId、工具、命令首行、exit/duration、output bytes/hash、truncation 与 `outputOmitted`；
|
||
- 默认不得展开 stdout、stderr、skill 正文或完整 payload，也不得通过提高全局 stdout 阈值掩盖 dump；
|
||
- 单事件有界详情使用 `--detail-seq <seq>`：
|
||
- human、JSON 和 YAML 使用同一 `EventDetail` 投影；
|
||
- 固定读取同一 run 的 durable event，并校验返回 seq 完全一致；
|
||
- 投影保留 identity、correlation、phase-specific evidence、count/bytes/hash/omitted；
|
||
- durable `resolutionAuthority` 保持原事实或显式脱敏，基于其他字段的非权威判断只进入独立 inference 字段；
|
||
- 标准 Git URL 移除 userinfo、query 和 fragment，SCP-like 与未知 remote 只披露不可逆 fingerprint；
|
||
- credential value 和 URL credential 固定脱敏，`valuesPrinted=false`；
|
||
- `--detail-seq` 与 `--after-seq`、`--limit`、`--full`、`--raw` 互斥，并在请求 manager 前 fail closed；
|
||
- 完整事件继续使用显式 `--full`、`--raw`，或按 `afterSeq=item.seq-1 --limit 1 --full` 下钻；
|
||
- 该 CLI 只渲染 AgentRun durable facts，不删除事件、不按正文去重，也不改变 Kafka/SSE 事件链。
|
||
|
||
AipodSpec describe 必须遵守以下边界：
|
||
|
||
- 默认 human、`-o json` 和 `-o yaml` 从同一摘要投影渲染；
|
||
- 摘要至少包含：
|
||
- identity/hash 与 lane/profile/provider；
|
||
- workspaceRef 与主 resource bundle source identity；
|
||
- bundle/required skill/credential 引用计数；
|
||
- 脱敏 provenance；
|
||
- credential 只保留 SecretRef 名称、namespace、keys 和安全 projection 字段，固定 `valuesPrinted=false`；
|
||
- 默认输出必须保留 `--full -o json` 与 `--raw` 语义化下钻，禁止读取临时 dump 再二次裁剪；
|
||
- 显式完整路径继续返回服务端完整对象，禁止提高全局 stdout 阈值掩盖默认输出缺陷。
|
||
|
||
task 输入下钻必须遵守以下边界：
|
||
|
||
- 默认 `describe task/<taskId>` 的 `Next` 必须给出 `--input -o json` 语义化命令；
|
||
- `--input` 只读取现有 task durable fact，不创建、复制、retry 或 dispatch task；
|
||
- 输出固定为 task create 字段、AipodSpec identity、bundle/SecretRef 和脱敏 provenance，credential 只保留 SecretRef 并声明 `valuesPrinted=false`；
|
||
- `--input` 与 `--full`、`--raw` 互斥，非法组合必须在请求服务端前返回带修正路径的 `validation-failed`；
|
||
- 完整服务端资源继续使用显式 `--full -o json` 或 `--raw`，禁止提高全局 stdout 阈值来掩盖大输出。
|
||
|
||
retry 必须遵守以下边界：
|
||
|
||
- task identity 不变，每次执行使用新的 attempt、run、command 和 runner Job identity；
|
||
- 同一幂等键返回同一 retry 结果，不重复创建 attempt；
|
||
- 只允许 Queue 已处于 `failed` 或 `blocked`，其他终态与非终态 fail closed；
|
||
- `--dry-run` 由服务端完成与真实 retry 相同的校验，但零写入；
|
||
- retry 不主动刷新 Core 终态。若 Queue 摘要仍是非终态，先通过正式 `get task` 或 `get attempts` 刷新权威状态，再重试；
|
||
- 禁止复制或重置 task，禁止在 UniDesk 增加 scheduler、backoff、judge、projector 或直接 runner 编排。
|
||
|
||
不要在 legacy `codex` 下增加新的 mutation 路径。
|