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

name, description

name

description

unidesk-agentrun

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。

高频入口

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 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

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

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；session 控制、HWLAB Code Agent 整合、trace/output 分页、judge、中断/取消见 references/sessions.md；旧队列归档见 references/legacy.md。

P0 边界

• Artificer create task 必须显式提供唯一中文短标题：
  • 标题为单行 2 到 80 字符，并至少包含一个中文汉字；
  • HWLAB、CI/CD 等专有名和空格可以保留；
  • describe/events/logs/result 优先使用标题的完全匹配查询；
  • 标题重复时 CLI 必须报歧义，不得猜测；内部 ID 仅用于深度下钻和机器身份。
• AgentRun 与调用方之间的契约版本、源码/镜像版本和 commitId 对齐只能产生非阻塞 warning；可安全归一化的请求继续 admission/dispatch，不得因版本或契约漂移阻止用户任务、session、run、command 或 runner。
• 新写入口不要用 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。
• 查历史 codex tasks/unread/output/trace：读 references/legacy.md。
• 需要 judge、取消、中断、Dev Ready 或 PR preflight：读 references/sessions.md。