--- name: unidesk-code-queue description: UniDesk AgentRun-backed Code Queue CLI — Skill(cli-spec)。legacy `codex` 子命令只保留历史只读和残留停止；新任务提交、Aipod/Artificer 派单、session follow-up、events/logs/result、ack/cancel、dispatch、run/command/runner 状态 drill-down 和 HWLAB Code Agent/CaseRun follow-up 必须使用 `agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|send` 资源原语。用户提到 codex、Code Queue、submit、send、resume、tasks、unread、code-queue、aipod、Artificer、HWLAB Code Agent 时使用。 --- # UniDesk Code Queue / AgentRun CLI 旧 Code Queue 已冻结新任务和写入口。`bun scripts/cli.ts codex ...` 现在只作为历史归档、只读排障和残留任务停止入口；新的指挥官派单、Aipod/Artificer 执行、events/logs/result、ack/cancel、dispatch、session follow-up 必须走 AgentRun 资源原语，并按 cli-spec 渐进披露。UniDesk 是 render-only client：默认输出是低噪声 human 表格/摘要，脚本读取显式使用 `-o json|yaml` 的稳定客户端 schema，`--raw` 只用于查看直连 AgentRun REST envelope。 **固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts agentrun ...` --- ## 新任务入口 ```bash # 查看 AgentRun 指挥官队列 bun scripts/cli.ts agentrun get tasks --queue commander --limit 20 bun scripts/cli.ts agentrun get tasks --queue commander -o wide # 查看一个 task/run/command/runnerjob/session 生命周期 bun scripts/cli.ts agentrun describe task/ bun scripts/cli.ts agentrun events run/ --after-seq --limit 100 bun scripts/cli.ts agentrun logs session/ --tail 100 bun scripts/cli.ts agentrun result run/ --command bun scripts/cli.ts agentrun describe command/ --run bun scripts/cli.ts agentrun describe runnerjob/ --run # 查看 / 渲染 AipodSpec（Artificer 是默认分布式开发 agent） bun scripts/cli.ts agentrun get aipodspecs bun scripts/cli.ts agentrun describe aipodspec/Artificer bun scripts/cli.ts agentrun aipod-specs render Artificer --prompt-stdin # AipodSpec apply/delete 仍由客户端资源原语发起，服务端只返回 REST 业务事实 bun scripts/cli.ts agentrun aipod-specs apply --yaml-stdin --dry-run # 提交 AgentRun task manifest bun scripts/cli.ts agentrun apply -f - --dry-run <<'YAML' kind: Task spec: tenantId: unidesk projectId: example queue: commander title: 任务标题 payload: prompt: 任务说明 YAML # 用 AipodSpec 提交，优先用于新任务和 Artificer bun scripts/cli.ts agentrun create task --aipod Artificer \ --prompt-stdin --idempotency-key # 查看/控制 AgentRun session bun scripts/cli.ts agentrun logs session/ --tail 100 bun scripts/cli.ts agentrun ack session/ bun scripts/cli.ts agentrun dispatch task/ bun scripts/cli.ts agentrun send session/ --aipod Artificer --prompt-stdin bun scripts/cli.ts agentrun cancel session/ --reason --dry-run bun scripts/cli.ts agentrun cancel command/ --run --reason --dry-run ``` 日常 task manifest 优先使用 YAML heredoc：`agentrun apply -f -`；单 prompt 派单优先 `agentrun create task --aipod Artificer --prompt-stdin`；同 session 续跑只使用 `agentrun send session/`。UniDesk 客户端按 `config/agentrun.yaml` 直连 AgentRun REST API，不经过 HWLAB runtime、SSH official CLI 或旧 bridge wrapper；`send` 是唯一用户级 session follow-up 写入口，服务端按 durable session/run/command 状态自动决定内部 `steer` 或新 `turn`，旧 CLI `turn/steer` 路径不保留兼容。`--json-file`、`--prompt-file` 和 `--runner-json-file` 只是客户端输入来源，用于已审阅且可复用的受控文件。它不是旧 Code Queue adapter，不双写，也不迁移旧历史。 `AipodSpec` 是 AgentRun v0.1 的声明式 agent 装配：模型 profile、gitbundle、skills/tools、SecretRef 和 tool credential 都从 YAML 规格渲染。`Artificer` 默认用于 UniDesk 分布式开发任务，使用 `sub2api` provider、`gpt-5.5`、`reasoningEffort=xhigh`，并通过 SecretRef 注入 GitHub PR token、GitHub SSH 和 UniDesk SSH 透传能力。更新规格时使用 `agentrun aipod-specs apply --yaml-stdin --dry-run` 先看计划，确认后再去掉 `--dry-run`；不得把 API key、SSH key 或 token 写入 prompt、payload、YAML 或 issue。 AgentRun task payload 需要 runner 内使用 UniDesk SSH 透传时，只通过 `executionPolicy.secretScope.toolCredentials[].tool=unidesk-ssh` 请求 `agentrun-v01-tool-unidesk-ssh/UNIDESK_SSH_CLIENT_TOKEN` SecretRef；不要把 token 写入 prompt、payload 或 `transientEnv`。非敏感 endpoint 使用 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL`，可由 runner-job `transientEnv` 显式提供；G14 `agentrun-v01` manager 也会在缺省时按受控默认值自动补齐，并在 trace 中只显示 env name/count/hash 与 `valuesPrinted=false`。 ## Queue 渐进披露 AgentRun queue 生命周期不是一个单独的 `queue lifecycle` 命令，而是一组资源原语的渐进披露组合： 1. 默认总览用 `get tasks --queue commander --limit 20`，只看 task state、queue/lane、run/cmd/rjob/session ref、age 和 attention。 2. 单任务用 `describe task/`，读取 `latestAttempt.runId`、`commandId`、`runnerJobId`、`sessionId/sessionPath` 和少量 `Next:`。 3. Run 级状态用 `events run/` 和 `result run/ --command `，判断 terminalClassification、failureKind、provider interruption、timeoutBudget 和 recoveryActions。 4. Command 级状态用 `describe command/ --run ` 和 `result command/ --run `，确认 command state、ack、terminal status 和结果摘要；确认为单个 active command 卡住时，用 `cancel command/ --run --reason ` 清理该 command，保留同一个 session 后再用 `send session/` 续跑。 5. Runner job 只读状态用 `describe runnerjob/ --run `，确认 env image reuse、jobName、namespace、phase、exitCode、retention 和 `valuesPrinted=false`。不要为了这些字段手动调用 `trans G14:k3s kubectl ...`。 6. Session trace/output 只在 `describe task` 或 result 里有实际 `sessionId` 时使用 `logs|ack|send|cancel session/`；`sessionRef=null` 时不要猜 session 命令。用户级 follow-up 一律使用 `send session/`，不要回到旧 `turn/steer` 或 `sessions ...` 兼容路径。 7. 已创建但尚未运行的 task 使用 `dispatch task/` 派发，不再退回旧 bridge `queue dispatch`。 默认视图必须低噪声且不是 JSON envelope，`-o json|yaml` 才输出稳定机器结构，`--raw` 才保留直连 AgentRun REST envelope；命令返回里的下一步应优先是 `bun scripts/cli.ts agentrun ...` 资源原语，不得把人工 k8s 查询作为日常下一步。 ## HWLAB Code Agent 入口整合 HWLAB Code Agent / CaseRun follow-up 的日常派单也归入 AgentRun 资源原语：新任务用 `create task --aipod Artificer` 或包含 HWLAB gitbundle 的 `apply -f -`；运行中纠偏用 `send session/ --aipod Artificer`。需要验证 HWLAB Web/Cloud API 原入口时，仍按 `$hwlab-code-agent` 使用 G14 `/root/hwlab-v02` 的 `hwlab-cli client agent ...` 拉取同一 trace/result/inspect；不要回到旧 `codex submit/resume/steer`。 排查 HWLAB v0.3 / D601 Code Agent trace 时，HWLAB `client agent result|trace|inspect` 仍是跨层事实锚点：它会暴露 AgentRun namespace、runId、commandId、jobName 和 providerProfile。若 `bun scripts/cli.ts agentrun events|result run/` 在默认 direct-http 面返回 `run not found`，不要据此判定 run 已丢失；先核对该 run 是否属于 D601 `agentrun-v02` 或其他非默认 lane，并继续用 HWLAB trace/result 或对应 `agentrun control-plane ... --node --lane ` 查询运行面。Codex provider config 的 context/auto-compact 修复属于 AgentRun lane Secret `sourceRef` 问题，应回到 UniDesk `config/agentrun.yaml` 的 `secrets[].sourceRef`、`.state/secrets/agentrun/*config.toml` 和 `agentrun control-plane secret-sync|restart` 收敛，不要在 prompt、HWLAB adapter 或 Kubernetes Secret 里手补。 --- ## 本地 Codex Trace 采集 `bun scripts/cli.ts codex trace ...` 是本机 Codex 运行痕迹的只读诊断入口，默认扫描 `~/.codex`，也可以用 `--root ` 指向其他 Codex home 或已拷贝的 trace 目录。它不提交新任务、不续跑 session，也不恢复旧 Code Queue 写入口。 ```bash bun scripts/cli.ts codex trace list [--root ~/.codex] [--limit 30] bun scripts/cli.ts codex trace active [--root ~/.codex] bun scripts/cli.ts codex trace grep --session --pattern 'playwright|auth-login-failed' [--since ISO] bun scripts/cli.ts codex trace grep --session --messages --pattern 'Playwright|web-probe' bun scripts/cli.ts codex trace grep --session --failed-only [--tool exec_command] bun scripts/cli.ts codex trace grep --pattern 'playwright|auth-login-failed' [--file sessions/...jsonl] [--since ISO] bun scripts/cli.ts codex trace collect [--root ~/.codex] [--output .state/codex-trace/] [--limit 30] bun scripts/cli.ts codex trace show --session [--root ~/.codex] [--tail-bytes 12000] ``` 默认只收集 `sessions/*.jsonl`、`history.jsonl`、`shell_snapshots`、`*.log` 和 trace 命名文本；`auth.json`、`config.toml`、sqlite、cache、`.tmp`、generated images、plugins 和 skills 默认跳过。`active` 从 `/proc` 找正在被 Codex 进程打开的 session JSONL，不依赖外部 `lsof`，并输出可复制的 `SESSION-ID`。`grep/show` 优先用 `--session ` 定位，避免复制长 JSONL 路径；session id 支持完整 UUID、短前缀和文件名片段，歧义时会提示候选。`grep` 默认只扫 active/recent session，并用 `rg`/raw-line prefilter 先定位候选行再解析 JSONL；需要全量文件域时显式加 `--all-files`，需要跳过 raw 预筛、逐行深度解析 decoded 字段时显式加 `--deep`。排查对话脉络优先 `--messages --pattern ...`，排查工具链优先 `--tools --tool `，只看失败调用用 `--failed-only [--tool ]` 且可以不带 pattern。默认输出优先 message 和 tool-call input；tool output 默认折叠，只给失败状态、错误摘要和对应输入，不打印整段 transcript；需要查看命中输出片段时显式加 `--include-output` 或 `-o wide`。它优先用于排查 `playwright`、`auth-login-failed`、`UNIDESK_*HINT` 等高噪声 trace。默认输出是类似 k8s 的简洁 text/table；脚本消费时显式加 `-o json|yaml|name|wide`。需要本地审阅敏感/数据库文件时必须显式加 `--include-sensitive` 或 `--include-sqlite`；`collect` 只复制有界文件并写 manifest，不压缩、不上传、不删除源文件。 --- ## 冻结的旧写入口 以下命令必须返回 `ok=false`、`frozen=true`、`degradedReason=legacy-code-queue-frozen`，并提示 AgentRun 替代命令： ```bash bun scripts/cli.ts codex submit ... bun scripts/cli.ts codex enqueue ... bun scripts/cli.ts codex steer ... bun scripts/cli.ts codex resume ... bun scripts/cli.ts codex queue create bun scripts/cli.ts codex queue merge --into bun scripts/cli.ts codex move --queue ``` 不要用兼容开关、legacy mode、adapter、双写或 fallback 绕开冻结边界。 --- ## 历史任务视图 ### Commander（低噪声轮询） ```bash bun scripts/cli.ts codex tasks --view commander [--limit N] ``` 返回旧 Code Queue 历史/残留任务的有界 action map：active runners 计数、少量 active item、queued/retry_wait 计数、terminal-unread 总数、关键风险计数、分类计数和 drill-down 命令。新任务队列状态用 `agentrun get tasks --queue commander`。 ### Supervisor（分区视图） ```bash bun scripts/cli.ts codex tasks --view supervisor \ [--status succeeded|running|queued|failed|canceled|judging|retry_wait] \ [--unread] [--limit N] [--before-id id] ``` 返回 `activeRunning`、`running`、`completedUnread`、`recentCompleted`、`queued` 分区。状态 alias：`completed|successful → succeeded`、`cancelled → canceled`、`pending → queued`。 ### 单任务 ```bash bun scripts/cli.ts codex task [--detail|--full] [--trace] ``` --- ## 未读积压 ```bash # 摘要 bun scripts/cli.ts codex unread [--queue id] [--repo owner/name] [--issue N] # 详细列表 bun scripts/cli.ts codex unread list [--view full] [--limit N] # 标记已读 bun scripts/cli.ts codex unread mark-read --confirm [--queue id] ``` `mark-read` 必须 `--confirm`，单任务审阅优先用 `codex read `。 --- ## Trace / Output 分页 ```bash # 逻辑 trace（分页） bun scripts/cli.ts codex task --trace \ [--tail|--from-start|--after-seq N|--before-seq N] [--limit N] [--full] # 原始 output（分页补取） bun scripts/cli.ts codex output \ [--tail|--from-start|--after-seq N|--before-seq N] [--limit N] [--full-text] ``` --- ## 标记已读 ```bash bun scripts/cli.ts codex read ``` 标记单个终态任务已读，同时返回任务身份、终态 attempt 摘要和最终 response。 --- ## Judge（复现评判） ```bash bun scripts/cli.ts codex judge --attempt N [--dry-run] [--include-prompt] ``` 按指定 attempt 单步复现 judge，诊断入口。 --- ## 中断/取消 ```bash bun scripts/cli.ts codex interrupt bun scripts/cli.ts codex cancel ``` 仅用于停止旧 Code Queue 残留任务；新 AgentRun session 使用 `bun scripts/cli.ts agentrun cancel session/`，单个卡住 command 使用 `bun scripts/cli.ts agentrun cancel command/ --run `。 --- ## 旧队列归档 ```bash bun scripts/cli.ts codex queues [--full|--all] [--limit N] [--page N] ``` 只读查看旧队列摘要。旧 queue create/merge 和 move 已冻结。 --- ## Dev Ready / PR Preflight ```bash bun scripts/cli.ts codex dev-ready bun scripts/cli.ts codex pr-preflight [--remote] [--push-dry-run ...] [--pr-create-dry-run ...] [--issue N] [--full|--raw] ``` ---