pikasTech-unidesk/.agents/skills/unidesk-code-queue/references/resources.md

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 单命令派单

标准入口：

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 路径。