docs: record agentrun lane observability
This commit is contained in:
Codex
@@ -113,7 +113,7 @@ bun scripts/cli.ts platform-infra observability trace \
|
||||
--full
|
||||
```
|
||||
|
||||
通过证据应能看到 `codex_app_server.starting`、`codex_app_server.started`、需要进程退出时的 `codex_app_server.exit`、`codex_stdio.thread_start.*` 或 `thread_resume.*`、`codex_stdio.turn_start.*`、`codex_stdio.tool_call.started|completed|failed`、`codex_stdio.turn_completed`，以及问题相关的 `idle_warning`、`idle_timeout`、`provider_stream_disconnected` 或 `missing_terminal_after_tool`。这些 span 应带 `runId`、`commandId`、`runnerJobId`、`runnerId`、`sessionId`、`backendProfile`、`sourceCommit`、`traceId`、`otel.trace_id` 和 `valuesPrinted=false`；缺少 `runnerJobId` 或没有 `agentrun-runner` service 时，先回 AgentRun runner-side instrumentation 排查。
|
||||
通过证据应能看到 `codex_app_server.starting`、`codex_app_server.started`、需要进程退出时的 `codex_app_server.exit`、`codex_stdio.thread_start.*` 或 `thread_resume.*`、`codex_stdio.turn_start.*`、`codex_stdio.tool_call.started|completed|failed`、`codex_stdio.turn_completed`，以及问题相关的 `idle_warning`、`idle_timeout`、`provider_stream_disconnected` 或 `missing_terminal_after_tool`。这些 span 应带 `runId`、`commandId`、`runnerJobId`、`runnerId`、`sessionId`、`backendProfile`、`sourceCommit`、`traceId`、`otel.trace_id` 和 `valuesPrinted=false`。若默认摘要或 grep 看不到 `runnerJobId`，先用当前 UniDesk CLI 执行 `platform-infra observability trace --grep runnerJobId --full` 复查摘要器输出，必要时用 `--raw` 只排查 Tempo/CLI 解析结构；只有 raw 或更新后的摘要仍缺 `runnerJobId`，或同一 trace 没有 `agentrun-runner` service，才回 AgentRun runner-side instrumentation 排查。
|
||||
|
||||
如果需要确认工具调用 started/completed 的归一化，canary 应要求一次只读 shell 工具调用。Codex notification 的 `item/started` + `status=inProgress` 应落为 `codex_stdio.tool_call.started`，不得和 completed 混在一起。长期规则见 `docs/reference/agentrun.md#agentrun--hwlab-otel-追踪口径`。
|
||||
|
||||
|
||||
@@ -145,7 +145,7 @@ AgentRun `v0.1` 的指挥官任务面已经按 AgentRun issue #105 完成真实
|
||||
|
||||
UniDesk 指挥官新任务入口固定使用 `bun scripts/cli.ts agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|steer|send` 资源原语。该入口是 render-only client：UniDesk 客户端保留 k8s 风格命令解析、human 表格、生命周期摘要、下一步命令、分页、`-o json|yaml` 稳定客户端 schema 和错误展示；AgentRun 服务端只提供稳定 RESTful API、鉴权和业务事实，不承载 UniDesk CLI 渲染。日常派单优先用 `agentrun create task --aipod Artificer --prompt-stdin` 或 `agentrun apply -f -` 的 quoted YAML/JSON heredoc/stdin 形式；已创建未运行任务用 `agentrun dispatch task/<taskId>` 派发；`--json-file`、`--prompt-file` 和 `--runner-json-file` 只是客户端输入来源，用于已审阅且可复用的受控文件。UniDesk 不实现 AgentRun queue 协议，也不把任务 double-write 回旧 Code Queue。
|
||||
|
||||
资源原语和旧兼容 group 的默认 transport 是直连 AgentRun REST API，配置来源是 UniDesk 自有 YAML `config/agentrun.yaml`。鉴权可以复用 `HWLAB_API_KEY` 的环境变量/固定文件发现风格，但不得依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 SSH official CLI；多一层转发会增加故障面，不能作为正式路径。`--raw` 只披露直连 AgentRun REST envelope 和必要的 `transport=direct-http`、`clientRole=render-only`、`configPath`、`baseUrl`、auth source/redacted metadata，不打印 token value。`agentrun control-plane ...` 和 `git-mirror ...` 仍属于 G14 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
|
||||
资源原语和旧兼容 group 的默认 transport 是直连 AgentRun REST API，配置来源是 UniDesk 自有 YAML `config/agentrun.yaml`。不带 `--node`/`--lane` 时按 YAML 的默认 manager `baseUrl` 访问；显式 `--node <node> --lane <lane>` 时按同一 YAML 选中 runtime lane，经 `lane-k8s-service-proxy` 进入 manager `internalBaseUrl`，并用 manager pod env 中声明的 API key metadata 发起请求；输出只披露 node/lane/namespace/baseUrl/auth env metadata 和 `valuesPrinted=false`，不得打印 key value。该模式用于 D601 `agentrun-v02` 等非默认 lane 的资源原语操作与证据采集，尤其是 `get/describe/events/logs/result`，不替代 `agentrun control-plane ...` 发布或运维控制。鉴权可以复用 `HWLAB_API_KEY` 的环境变量/固定文件发现风格，但不得依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 SSH official CLI；多一层转发会增加故障面，不能作为正式路径。`--raw` 只披露直连 AgentRun REST envelope 和必要的 `transport=direct-http`、`clientRole=render-only`、`configPath`、`baseUrl`、auth source/redacted metadata，不打印 token value。`agentrun control-plane ...` 和 `git-mirror ...` 仍属于 G14 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
|
||||
|
||||
AgentRun 公网 HTTPS 入口、FRP/Caddy edge、direct REST base URL 和鉴权来源都由 UniDesk `config/agentrun.yaml` 声明。YAML-only lane 不允许把这些部署选择写回 AgentRun source branch 的 `deploy/deploy.json`；AgentRun source repo 只保留应用代码、构建输入和 repo 内部实现文档。`bun scripts/cli.ts agentrun control-plane expose --confirm` 只负责按 UniDesk YAML 补 edge 侧 allow port 与 Caddy site，不在 AgentRun k3s 中创建 Ingress、NodePort、LoadBalancer、hostPort 或 HWLAB 转发层。
|
||||
|
||||
@@ -179,7 +179,7 @@ AgentRun runner-side instrumentation 必须从 manager 创建 runner Job 时传
|
||||
|
||||
codex app-server backend 的最小可追踪面包括 app-server lifecycle、thread、turn、tool、idle 和 provider stream 断开：`codex_app_server.starting`、`codex_app_server.started`、进程退出时的 `codex_app_server.exit`，以及 `codex_stdio.thread_start.*` / `codex_stdio.thread_resume.*`、`codex_stdio.turn_start.*`、`codex_stdio.tool_call.started|completed|failed`、`codex_stdio.turn_completed`、`codex_stdio.idle_warning`、`codex_stdio.idle_timeout`、`codex_stdio.provider_stream_disconnected` 和 `codex_stdio.missing_terminal_after_tool`。Codex notification 中 `item/started` 且 `status=inProgress`、`running` 或等价状态必须归一化为 `tool_call.started`，不得误报为 completed。
|
||||
|
||||
收口验证必须走 HWLAB Web dispatcher 等价原入口或同一 dispatcher 的 CLI，触发一条新 turn 并尽量包含一次只读工具调用；然后用 `bun scripts/cli.ts platform-infra observability trace --target <node> --trace-id <otelTraceId> --grep codex_stdio --full` 查询 Tempo。通过证据应显示 `services` 至少覆盖 `hwlab-cloud-api`、`agentrun-manager` 和 `agentrun-runner`，codex span 中 `runId`、`commandId`、`runnerJobId` 不缺失，`valuesPrinted=false`，且错误 span 与业务终态一致。旧 trace 不会因后续 instrumentation 修复自动回填；旧 trace 缺少 codex runner span 时，只能写成“当时未采集到该事件”，不能倒推出 AgentRun 或 codex-stdio 当时没有运行。
|
||||
收口验证必须走 HWLAB Web dispatcher 等价原入口或同一 dispatcher 的 CLI，触发一条新 turn 并尽量包含一次只读工具调用；然后用 `bun scripts/cli.ts platform-infra observability trace --target <node> --trace-id <otelTraceId> --grep codex_stdio --full` 查询 Tempo。通过证据应显示 `services` 至少覆盖 `hwlab-cloud-api`、`agentrun-manager` 和 `agentrun-runner`，codex span 中 `runId`、`commandId`、`runnerJobId` 不缺失，`valuesPrinted=false`，且错误 span 与业务终态一致。若已知 trace 的 runner span 在默认摘要里看不到 `runnerJobId`，先用当前 UniDesk CLI 执行 `platform-infra observability trace --grep runnerJobId --full` 区分摘要器遗漏和 instrumentation 缺口；只有 raw/更新后的摘要仍缺字段，或同一 trace 没有 `agentrun-runner` service，才归为 AgentRun runner-side instrumentation 问题。旧 trace 不会因后续 instrumentation 修复自动回填；旧 trace 缺少 codex runner span 时，只能写成“当时未采集到该事件”，不能倒推出 AgentRun 或 codex-stdio 当时没有运行。
|
||||
|
||||
## AgentRun / HWLAB 失败归因标准
|
||||
|
||||
|
||||
@@ -117,7 +117,7 @@ PipelineRun 失败或长时间未完成时，先按定点 `control-plane status
|
||||
- `schedule list|get|runs|run|retry-run|delete|upsert-pgdata-backup` 管理 backend-core 定时任务和运行历史。`schedule list`、`schedule get`、`schedule runs --limit N` 和 `schedule runs <scheduleId> --limit N` 是只读观察入口；`schedule run`、`schedule retry-run`、`schedule delete` 和 `schedule upsert-pgdata-backup` 会触发运行或写入配置，生产恢复时必须有明确授权。`schedule runs --limit N` 是全局历史视图，返回 `scope=global` 和 `scheduleId=null`；`schedule runs <scheduleId> --limit N` 是指定 schedule 历史视图，返回 `scope=schedule` 和对应 `scheduleId`。CLI 必须拒绝 `schedule runs 50` 这类纯数字位置参数，并提示使用 `schedule runs --limit 50`，避免把空数组误判成“没有历史 run”。`schedule run <id> --wait-ms N` 触发同一 schedule，并且即使 wait 超时也必须返回 `newRunId` 和 `observeCommand`；`schedule retry-run <failedRunId>` 只接受 failed run，从原 run 反查 `scheduleId` 后重触发同一 schedule，并输出 `originalRunId`、`scheduleId`、`newRunId` 和 `observeCommand`。当 backend-core 目标容器缺失或只观察到 verify-only 容器时，schedule/microservice 命令必须以非零退出并返回 `failureKind=target-stack-not-running`、`runnerDisposition=infra-blocked`、`readOnlyCommands` 和 `authorizationRequiredForRecovery`，不得把 Docker 的 `No such container` 当成成功的空历史。
|
||||
- `codex deploy <commitId>` 是旧 Code Queue 兼容部署入口，已禁用以防止维护通道直连 D601 部署 Code Queue；当前 dev 自动化只做 `ci run-dev-e2e` smoke，不提供 Code Queue CD，详细规则见 `docs/reference/codex-deploy.md`。
|
||||
- `agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|send` 是当前指挥官新任务和 AgentRun session 控制入口。UniDesk CLI 是 render-only client：客户端保留 k8s 风格命令解析、human 表格、生命周期摘要、下一步命令、分页、`-o json|yaml` 稳定客户端 schema 和错误展示；AgentRun 服务端只提供稳定 RESTful API、鉴权和业务事实，不承载 UniDesk CLI 渲染。日常查看用 `get tasks --queue commander`、`describe task/<taskId>`、`events run/<runId>`、`logs session/<sessionId>`、`result run/<runId> --command <commandId>`；日常写入用 `create task --aipod Artificer --prompt-stdin`、`apply -f -`、`dispatch task/<taskId>`、`send session/<sessionId>`、`ack/cancel task|session/<id>`。用户级 CLI 取消 `turn` 和 `steer` 路径；`send session/<sessionId>` 是唯一 session follow-up 写入口，AgentRun 服务端按 durable session/run/command 状态自动决定内部 `steer` 或新 `turn`，dry-run 必须真实返回这个 decision 且不写状态。兼容 group `queue|runs|commands|runner|sessions|aipod-specs` 也走同一 direct HTTP transport，`--raw` 只披露直连 AgentRun REST envelope。
|
||||
- `agentrun` 资源原语的默认 transport 是直连 AgentRun REST API，配置来源是 UniDesk 自有 YAML `config/agentrun.yaml`。鉴权可以复用 `HWLAB_API_KEY` 的环境变量/固定文件发现风格，但不得依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 SSH official CLI；多一层转发会增加故障面，不能作为正式路径。`agentrun control-plane ...` 和 `git-mirror ...` 仍属于 G14 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
|
||||
- `agentrun` 资源原语的默认 transport 是直连 AgentRun REST API，配置来源是 UniDesk 自有 YAML `config/agentrun.yaml`。不带 `--node`/`--lane` 时按 YAML 的默认 manager `baseUrl` 访问；显式 `--node <node> --lane <lane>` 时按同一 YAML 选中 runtime lane，经 `lane-k8s-service-proxy` 进入 manager `internalBaseUrl`，并用 manager pod env 中声明的 API key metadata 发起请求；输出只披露 node/lane/namespace/baseUrl/auth env metadata 和 `valuesPrinted=false`，不得打印 key value。该模式用于 D601 `agentrun-v02` 等非默认 lane 的资源原语操作与证据采集，尤其是 `get/describe/events/logs/result`，不替代 `agentrun control-plane ...` 发布或运维控制。鉴权可以复用 `HWLAB_API_KEY` 的环境变量/固定文件发现风格，但不得依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 SSH official CLI；多一层转发会增加故障面，不能作为正式路径。`agentrun control-plane ...` 和 `git-mirror ...` 仍属于 G14 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
|
||||
- `agentrun control-plane expose --dry-run|--confirm` 按 `config/agentrun.yaml` 维护 AgentRun 公网 HTTPS 入口，模式与 Sub2API 暴露一致：G14 AgentRun runtime 通过 frpc 出到 master `127.0.0.1:<remotePort>`，master Caddy 提供 `https://agentrun.74-48-78-17.nip.io/`。该命令只补 master `frps` allow port 和 Caddy vhost；G14 frpc Deployment/ConfigMap 必须由 AgentRun `deploy/deploy.json` + GitOps render 管理，不能在 UniDesk 侧手写 Kubernetes manifest。
|
||||
- `codex submit/enqueue`、`codex steer`、`codex resume`、`codex queue create`、`codex queue merge`、`codex move`、旧 Web 提交表单、旧队列管理和旧 workdir 管理是冻结的 legacy Code Queue 写入口。CLI 必须返回 `ok=false`、`frozen=true`、`degradedReason=legacy-code-queue-frozen` 和 AgentRun 替代命令；服务端旧 API 写入口必须返回 410。新任务、session follow-up、events/logs/result、ack 和 cancel 走 AgentRun 资源原语，其中 session follow-up 只用 `agentrun send session/<sessionId>`。
|
||||
- 旧 Code Queue 只保留历史归档、只读排障和残留任务停止。`codex task/tasks/output/read/unread/queues` 继续通过 backend-core 私有代理读取旧 PostgreSQL 历史；`codex interrupt|cancel <taskId>` 只用于停止旧运行面残留任务。旧 `steer-confirm` 只作为历史 trace confirmation 查询，不是新任务控制入口。
|
||||
|
||||
Reference in New Issue
Block a user