pikasTech-unidesk/.agents/skills/unidesk-agentrun/SKILL.md

---
name: unidesk-agentrun
description: UniDesk AgentRun-backed Code Queue CLI — Skill(cli-spec)。legacy `codex` 子命令只保留历史只读和残留停止；新任务提交、Aipod/Artificer 派单、session follow-up、events/logs/result、attempts/retry、ack/cancel、dispatch、run/command/runner 状态 drill-down 和 HWLAB Code Agent/CaseRun follow-up 必须使用 `agentrun get|describe|events|logs|result|retry|ack|cancel|dispatch|create|apply|send` 资源原语。用户提到 codex、Code Queue、submit、send、resume、retry、tasks、unread、code-queue、aipod、Artificer、HWLAB Code Agent 时使用。
---

# UniDesk AgentRun CLI

新任务、Aipod/Artificer 派单、session follow-up、events/logs/result、attempts/retry、ack/cancel、dispatch 和 run/command/runner drill-down 走 AgentRun 资源原语。legacy `codex` 只保留历史只读、未读积压和残留任务停止。

`--mdtodo-id` 是尚未退役的 AgentRun 兼容字段，不是任务权威；任务登记与遗留文件迁移统一遵循 `$unidesk-tasktree`。

## P0：turn 只允许无活动超时

- `config/agentrun.yaml` 中
  `client.sessionPolicy.executionPolicy.timeoutMs`
  表示无 notification、assistant delta、tool 状态或 command output
  的连续空闲预算，默认 `600000` 毫秒。
- 每次有效活动都必须从活动时刻重置空闲截止时间。
- 禁止将该字段实现或描述为 turn/session 总时长 hard-timeout；
  HTTP、observer 和 runner lease 的等待超时不得把仍有活动的业务 turn
  写成 timeout 终态。

## 高频入口

```bash
bun scripts/cli.ts agentrun get tasks --limit 20
bun scripts/cli.ts agentrun describe "修复 HWLAB 的 cicd"
bun scripts/cli.ts agentrun describe task/<taskId> --input -o json
bun scripts/cli.ts agentrun describe aipodspec/<name>
bun scripts/cli.ts agentrun events "修复 HWLAB 的 cicd" --after-seq 0 --expect 10 --timeout 120s --limit 20
bun scripts/cli.ts agentrun events run/<runId> --detail-seq <seq> -o json
bun scripts/cli.ts agentrun events run/<runId> --aggregate reuse --native-development -o json
bun scripts/cli.ts agentrun logs "修复 HWLAB 的 cicd" --tail 120
bun scripts/cli.ts agentrun result "修复 HWLAB 的 cicd"
bun scripts/cli.ts agentrun get attempts --task <taskId>
bun scripts/cli.ts agentrun retry task/<taskId> --idempotency-key <key> --reason <text> --dry-run
bun scripts/cli.ts agentrun send <session> --prompt-stdin
bun scripts/cli.ts agentrun create task \
  --aipod Artificer \
  --title "修复 HWLAB 的 cicd" \
  --target <Target> \
  --target-workspace <absolute-task-worktree> \
  --repo <owner/repo> \
  --ref <branch> \
  --mdtodo-id <R6.3> \
  --prompt-stdin
```

AgentRun L1 native manager 只使用 YAML-first 生命周期：

```bash
bun scripts/cli.ts agentrun native-development manager start
bun scripts/cli.ts agentrun native-development manager status
bun scripts/cli.ts agentrun native-development manager logs
bun scripts/cli.ts agentrun native-development manager restart
bun scripts/cli.ts agentrun result run/<runId> --command <commandId> --native-development
```

- 配置唯一来源是 `config/agentrun.yaml#nativeDevelopment.manager`；
- 固定 workspace、port、state、store、Kafka、runner、Kubernetes transport
  和 SecretRef 不得由命令行或临时环境变量覆盖；
- host-native manager 使用 YAML 声明的 `kubeconfig` 与
  `kubectlCommand` 创建 Kubernetes Job；集群部署未声明
  `kubectlCommand` 时继续使用既有 in-cluster HTTPS transport；
- Workbench L1 直连 AgentRun L1 manager，不依赖 AgentRun L2 rollout
  或固定 HTTPS 公共入口完成内部业务回归；
- Workbench smoke 必须通过产品 `--over-api` 路径提交，并只从
  `hwlab.event.v1` 的 Kafka retention replay 与 live SSE 判断进展和终态；
- Workbench 多轮复用验收使用
  `agentrun events run/<runId> --aggregate reuse`：
  - CLI 自动读取全部有界 event page，不得逐页人工查询后拼接；
  - 一个 session 只允许一个 run 和一个 runner Job；
  - 首个 turn 只允许一次 source fetch 和 resource bundle materialization；
  - 后续每个 turn 必须各有一个 `codex-app-server:reused` 和
    `thread/resume:completed`；
  - command created、backend turn started、command terminal 和 terminal status
    的数量必须一致；
  - 该摘要只用于执行复用诊断，不替代 Workbench Kafka/SSE 产品终态权威；
- AgentRun L1 CLI 问题按即时修复规则处理：
  - 适用于 manager、资源原语和 Workbench `--over-api` CLI；
  - 问题范围包括 parser、lifecycle、窄查询、输出预算、错误码和可见性；
  - 立即在当前任务内修改并做最小闭环，不等待独立授权；
  - 不改用裸 REST、原生工具或临时 dump 绕过；
  - 通用边界见 `docs/reference/dev-environment.md#l1-受控-cli-即时修复`。
- `runner-dispatch-*` 表示 manager 装配、观察或创建 Job 的阶段；
- `runner-startup-*` 表示 Job 已创建后的 runner 启动和 backend 连接阶段；
- Pod `Running` 但 runner 未 claim 时仍未进入 provider 调用，不能归因给 provider；
- 固定 HTTPS 公共入口未就绪时单独登记公共服务面问题，禁止修改
  Workbench 到 AgentRun L1 的内部连接绕过该问题。

HWLAB Agent Observer 分页快照验收使用目标 node/lane HWLAB workspace 内的 typed CLI：

```bash
export HWLAB_RUNTIME_WEB_URL=<selected-public-origin>
export HWLAB_RUNTIME_ENDPOINT_LOCKED=1
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent-observer list --page 1 --page-size 25 --timeout-ms 30000
bun tools/hwlab-cli/bin/hwlab-cli.ts client agent-observer list --page 2 --page-size 25 --search <中文任务标题>
```

- `HWLAB_API_KEY` 必须从选中 node/lane 的受控 sourceRef 加载；
- 列表 authority 固定为 `agentrun-manager-durable-store`：
  - `page`、`pageSize`、`total`、`totalPages` 和 `hasNextPage` 必须可见；
  - `items` 直接来自 AgentRun durable run、最新 command 和最新 runner job；
  - `taskId`、中文标题、workspace、lane、Agent/Profile、attempt、runner 和错误字段不得依赖 Kafka 历史 envelope 猜测；
  - `total` 只表示 owning YAML 选中 manager 的 durable run 总数：
    - 不得用旧 Kafka retention replay 的去重投影数作为预期总数；
    - 不得把其他 lane 的历史投影混入当前 release 列表；
- Web 首屏先读取同一分页快照，再连接 `hwlab.event.v1` live 流；
- Kafka retention replay 只用于显式事件历史下钻，不得阻塞列表首屏；
- 验收 Artificer 时使用中文标题搜索，并确认对应 `sessionId` 使用 `sess_artificer_` 前缀；
- `--limit` 只保留为旧 `--page-size` 别名，不再表示 Kafka replay 扫描上限；
- 禁止用无限 SSE 的 `client request GET /v1/agent-observer/events` 代替有界分页查询。

资源命令的 Target 规则：

- 未传 `--target`、`--node` 或 `--lane` 时，使用 `config/agentrun.yaml#controlPlane.default`；
- `client.transport=target-trans` 使当前 CLI 通过选中 Target 的 k3s service proxy 请求 manager；
- Artificer target task 只额外通过 `trans <Target>:<targetWorkspace>` 执行目录存在性探测，不在 Target 上重跑 UniDesk CLI；
- 代码不得补 Target 路径默认值；
- 主机 direct HTTP auth 只保留独立诊断；
- Secret 固定读取 `/root/.unidesk/.env/agentrun.env`，不得回退到 worktree 或旧 `/root/.config/hwlab-*` 路径。

AipodSpec/Artificer、task manifest 和 queue 渐进披露见 [references/resources.md](references/resources.md)；session 控制、HWLAB Code Agent 整合、trace/output 分页、judge、中断/取消见 [references/sessions.md](references/sessions.md)；旧队列归档见 [references/legacy.md](references/legacy.md)。

## P0 边界

- Artificer `create task` 必须显式提供唯一中文短标题：
  - 标题为单行 2 到 80 字符，并至少包含一个中文汉字；
  - `HWLAB`、`CI/CD` 等专有名和空格可以保留；
  - `describe/events/logs/result` 优先使用标题的完全匹配查询；
  - 标题重复时 CLI 必须报歧义，不得猜测；内部 ID 仅用于深度下钻和机器身份。
- AgentRun 非核心校验不得阻塞核心业务：
  - schema、capability、契约版本、源码/镜像版本、`commitId` 和 provenance 一致性漂移只能产生结构化 warning；
  - warning 固定携带 `blocking=false`、校验范围、脱敏差异摘要和继续使用的权威事实；
  - 可安全归一化的请求继续 admission、dispatch 和 runner 执行，不得把用户 task、session、run、command 或 runner 写成 `schema-invalid`、failed 或 blocked；
  - 可读 provenance 的 hash、schemaVersion、source、assembly、commit、tree 和 origin 差异全部降级为 warning；
  - session workspace 声明与冻结 provenance 漂移时，继续使用冻结 provenance 和现有 workspace，不重新物化、不覆盖用户状态、不增加第二执行路径；
  - 身份、权限、Secret、目标 workspace 所有权、破坏性操作边界和实际执行前提仍然阻塞；workspace 无法归属、Git 对象不存在、目录不可用、workspace 不可写或核心凭据失败不得降级。
- 新写入口不要用 `codex submit/steer/resume`；这些 legacy mutation 已冻结。
- Artificer 的 runner primary workspace 与任务 Target 必须分开判定：
  - runner primary workspace 只装配默认 UniDesk resource bundle、`tools/trans`、skill 和轻量准备；
  - 待修改源码只来自派单上下文中的显式 `targetWorkspace`；
  - admission 只校验绝对路径、存在性和目录类型，不读取 Git 状态，也不因 dirty、ahead、behind 或已有 diff 产生 warning/blocker；
  - 现场探测、Git、编辑、验证和运行面观察必须使用 `trans <Target>:<targetWorkspace>`；
  - 不得把 runner 本地结果、默认 bundle 的 Git 状态或容器内同名路径当作 Target 验收；
  - `unidesk-trans` required skill、runner tools bundle、`unidesk-ssh` SecretRef 和 endpoint presence 缺一项即归为装配失败；
  - Secret 输出只显示对象、key、presence/fingerprint 与 `valuesPrinted=false`。
- 默认输出保持低噪声表格/摘要；机器消费显式 `-o json|yaml` 或 `--raw`。
- 主代理观察 active run 时默认使用单次长轮询：
  - `--after-seq` 是可继续拉取的增量游标；
  - `--expect <N>` 是等待条件；
  - `--timeout <duration>` 默认 `120s`，达到 `expect` 或目标 run/command 终态时提前返回；
  - timeout 到期返回当前事件，即使 0 条也明确披露 `timedOut`、`observed` 和 `nextAfterSeq`；
  - `--limit` 只控制输出预算，不得承担等待条件；
  - CLI 只发起一个 manager-held 请求，禁止本地高频短轮询或忙轮询。
- 读取 task 的可重建输入：
  - 使用 `agentrun describe task/<taskId> --input -o json`；
  - 该入口只投影 task create 字段、AipodSpec identity、资源引用和脱敏 provenance；
  - 不打印 Secret value；
  - `--input` 与 `--full`、`--raw` 互斥，非法组合必须在请求服务端前返回 `validation-failed`。
- 读取 AipodSpec：
  - 默认 `describe aipodspec/<name>` 的 human、JSON 和 YAML 使用同一有界摘要；
  - 摘要至少包含：
    - identity/hash 与 runtime；
    - workspace 与主 resource bundle source identity；
    - 引用计数和脱敏 provenance；
  - credential 只显示 SecretRef 并固定 `valuesPrinted=false`；
  - 完整服务端对象只通过显式 `--full -o json` 或 `--raw` 下钻。
- Session follow-up 使用 `agentrun send`，由服务端决定内部 steer vs turn。
- Session follow-up 的默认 text、显式 JSON 和 YAML 使用同一有界投影：
  - dry-run 直接展示 `decision`、`reuseRun`、`createRunner`、session/run/command/runner identity、`mutation=false` 和语义化 `Next`；
  - live 失败保留 manager 返回的 typed failure、资源 identity、`mutation` / `partialWrite` 与只读下钻命令；
  - CLI 不补做 retry、cleanup、runner 调度或 session 状态机，partial write 时禁止盲目重发。
- 终态失败重试只使用 `agentrun retry task/<taskId>`：保持同一 task，新增不可变 attempt；先用 `--dry-run` 完成服务端全校验，再以同一幂等键执行真实重试。
- retry 只接受 Queue 已处于 `failed` 或 `blocked`；`completed`、`cancelled` 和其他状态必须 fail closed。不得复制 task、重置 task、引入本地 scheduler/backoff/judge 或直接创建 runner Job 来模拟重试。
- HWLAB Code Agent/CaseRun follow-up 也优先落到 AgentRun resource primitive，不绕过队列状态。

## 何时读取 reference

- 创建/应用 AgentRun task 或 AipodSpec：读 [references/resources.md](references/resources.md)。
- 查历史 `codex tasks/unread/output/trace`：读 [references/legacy.md](references/legacy.md)。
- 需要 judge、取消、中断、Dev Ready 或 PR preflight：读 [references/sessions.md](references/sessions.md)。