Merge remote-tracking branch 'origin/master' into fix/web-probe-memory-guard

2026-07-13 07:47:04 +00:00
parent 4b39c9ce41 5ea7c0bf60
commit 11b1f3d647
24 changed files with 1581 additions and 37 deletions
@@ -216,7 +216,45 @@ AgentRun 的产品边界、REST resource/API 语义、run/command/event/session/

 AgentRun 指挥官任务面已经按 AgentRun issue #105 完成真实运行面验收，可作为新任务派发、commander queue 观察、events/logs/result、steer/send、ack 和 cancel 的 AgentRun 侧标准路径。长期能力规格以 UniDesk OA 的 [队列会话](../../project-management/PJ2026-01/specs/PJ2026-010203-queue-session.md) 和 [AgentRun核心](../../project-management/PJ2026-01/specs/PJ2026-010201-agentrun-core.md) 为准；UniDesk 只记录该路径以 NC01 `agentrun-v02` 运行面和 YAML profile 为准。

-UniDesk 指挥官新任务入口固定使用 `bun scripts/cli.ts agentrun get|describe|events|logs|result|retry|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。
+UniDesk 指挥官新任务入口固定使用 `bun scripts/cli.ts agentrun get|describe|events|logs|result|retry|ack|cancel|dispatch|create|apply|send` 资源原语：
+
+- UniDesk 客户端负责：
+  - k8s 风格命令解析；
+  - human 表格、生命周期摘要和下一步命令；
+  - 分页、`-o json|yaml` 稳定 schema 和错误展示；
+- AgentRun 服务端只提供 RESTful API、鉴权和业务事实；
+- 通用 task manifest 继续使用 `agentrun apply -f -`；
+- Artificer Target 派单使用单命令：
+
+```bash
+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 与 live 都先经 Target `trans` 重入并执行 source/worktree/Aipod/SecretRef 预检；
+- live 的 submit 成功后自动 dispatch；
+- 幂等重试不得重复创建 attempt 或重复 dispatch；
+- UniDesk 不实现 AgentRun queue 协议，也不把 task double-write 回旧 Code Queue。
+
+Artificer Target preflight 必须在 task 创建前完成：
+
+- `targetWorkspace` 是任务专属 Git worktree 根目录；
+- worktree 必须 clean；
+- origin 与 `--repo` 一致；
+- current branch 与 `--ref` 一致；
+- HEAD 与 origin 远端 ref commit 一致；
+- AipodSpec 渲染出的 `workspaceRef` 只允许 `kind/path`；
+- 默认 UniDesk resource bundle 保持继承，不把私有目标 repo 改成 runner primary bundle；
+- 输出包含 projectId、session identity、SecretRef presence 和 HEAD/remote 关系；
+- 失败固定 `mutation=false`，且不创建 task；
+- 成功返回 task、attempt、run、command、runner 和 session identity。

 Queue 终态失败重试使用正式资源入口：

@@ -235,18 +273,33 @@ retry 保持 task identity 不变，服务端为每次执行保留不可变 atte

 使用 lane-scoped AipodSpec 派单前，必须通过 `get/describe aipodspec`、render 输出或首个 runner job 摘要确认 `backendProfile`、provider credential SecretRef、tool credential SecretRef 和 bundle/workspaceRef 都存在于选中 lane 的 YAML 事实中。NC01/nc01-v02 的 Artificer 默认装配应从 lane YAML 绑定真实存在的 provider credential 和 tool credential：GitHub PR token 用 `tool=github`、`purpose=github-pr`、Secret key/projection env `GH_TOKEN`；UniDesk 透传 token 用 `tool=unidesk-ssh`、`purpose=ssh-passthrough`、Secret key/projection env `UNIDESK_SSH_CLIENT_TOKEN`。`tool=github-ssh`、`sub2api` 或其他 legacy tool credential 只有在 YAML 明确声明完整 SecretRef、keys 和 projection 时才允许渲染。若 runner Pod 出现 `FailedMount`，且缺失对象是渲染出的 SecretRef，应归为 AipodSpec/YAML 绑定问题并修正受控配置；不得在 runtime namespace 手工创建 legacy Secret 或把其他 lane 的 Secret 复制过去。AipodSpec render 的默认输出也应是 bounded summary/table/drill-down；完整 render JSON 只在显式 `--full`、`--raw`、`-o json` 或机器消费路径展开，残余 dump 问题继续归 [#862](https://github.com/pikasTech/unidesk/issues/862) 跟踪。

-资源原语和旧兼容 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。该模式用于 NC01 `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 ...` 仍属于 NC01 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
+AgentRun 资源原语的默认执行路径由 UniDesk `config/agentrun.yaml` 唯一控制：
+
+- `client.transport=target-trans` 时：
+  - 外层 CLI 从 `controlPlane.default` 或显式 `--target` / `--node` / `--lane` 解析 Target；
+  - 外层通过 `trans <Target>:<unideskWorkspace>` 重入目标节点；
+  - marker、可执行文件和 CLI 相对路径来自 `client.targetExecution`；
+  - Target 内部按选中 lane 使用 `lane-k8s-service-proxy` 进入 manager `internalBaseUrl`；
+- `controlPlane.nodes.<Target>.unideskWorkspace` 是 Target 上的 UniDesk 受控入口；
+- 代码不得补主机名、绝对路径或第二条 transport 默认值；
+- dry-run 也必须走同一 Target 重入路径，不能读取调用端同名目录冒充 Target 证据；
+- 输出只披露 Target/lane/namespace、SecretRef、presence/fingerprint 和 `valuesPrinted=false`；
+- 旧兼容 group 的 direct HTTP 只保留独立诊断，不是 Artificer 派单路径；
+- `agentrun control-plane ...` 和 `git-mirror ...` 仍属于 source/runtime 运维控制路径。

 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 转发层。

 AgentRun Queue 任务调用 UniDesk 维护桥时，长期契约以 UniDesk OA 的 [Runtime装配](../../project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md) 和 [YAML运维](../../project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md) 为准：

 - workspace 与 tool target 边界：
-  - 待修改源码只来自 task 的 primary workspace；
-  - 用户明确授权的 `trans <route> ...` 远端范围属于 `unidesk-ssh` tool target，不属于旁路 source workspace；
+  - runner primary workspace 只承载默认 UniDesk resource bundle、工具、skill 和轻量准备；
+  - 待修改源码只来自派单上下文中的 Target task worktree；
+  - 现场探测、Git、编辑、验证和运行面观察都使用 `trans <Target>:<targetWorkspace>`；
+  - runner 本地执行不得冒充 Target 原入口证据；
  - runner 的 `tran` 必须委派 primary UniDesk workspace 中的共享 `scripts/tran`，不得在 AgentRun 维护第二套 Windows、host 或 k3s route parser。
 - credential 与 endpoint：
  - 调用方通过 `executionPolicy.secretScope.toolCredentials[].tool=unidesk-ssh` 请求 `UNIDESK_SSH_CLIENT_TOKEN` SecretRef；
+  - AipodSpec 必须同时 required `unidesk-trans`，并装配包含 `tools/trans` 的 runner tools bundle；
  - 非敏感 endpoint 由 runner-job `transientEnv` 显式提供，或由 manager 受控默认值自动补齐；
  - UniDesk bridge 提交 Queue payload 时不得在 prompt、payload 或 `transientEnv` 中携带 token，也不得使用 HWLAB runtime Web 入口冒充 UniDesk frontend。
 - 失败归因：
@@ -220,9 +220,23 @@ PipelineRun 失败或长时间未完成时，先按定点 `control-plane status
 - `ci install|install-status|status|run|publish-backend-core|publish-user-service|run-dev-e2e|logs` 管理 D601 原生 k3s 上的 Tekton CI。`install` 默认创建 `.state/jobs` 异步 job 并立即返回，`install-status <jobId|latest>` 读取阶段化 progress 和 bounded log tail；只有现场同步调试才显式加 `--wait`。`run` 手动创建每 commit 检查和 Code Queue 只读性能门禁；`publish-backend-core` 与 `publish-user-service` 从 pushed Git commit 构建并发布 `127.0.0.1:5000/unidesk/<service>:<commit>` commit-pinned artifacts，输出 `artifactSummary`（含 `serviceId`、`sourceCommit`、`sourceRepo`、`dockerfile`、`imageRef`、`tag`、`digest`、`digestRef`），但不部署生产；`run-dev-e2e` 的 Git 控制 runner、短 launcher、host fetch 边界、临时 smoke namespace 和 no-CD 规则只在 `docs/reference/dev-ci-runner.md` 定义；Tekton CI 通用规则见 `docs/reference/ci.md`。
 - `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 get|describe|events|logs|result|ack|cancel|dispatch|create|apply|send` 是当前 AgentRun 资源入口：
+  - 日常查看使用 `get`、`describe`、`events`、`logs` 和 `result`；
+  - session follow-up 只使用 `send session/<sessionId>`；
+  - Artificer Target 派单使用 `create task --aipod Artificer`；
+  - 同一命令必须提供 `--target`、`--target-workspace`、`--repo`、`--ref`、`--mdtodo-id` 和 prompt；
+  - Target 模式在 submit 后自动 dispatch，并返回 task/run/session/attempt identity；
+  - 用户级 `turn` 和 `steer` 已取消；
+  - 兼容 group 只保留独立诊断。
 - `agentrun explain session-policy --node <node> --lane <lane>`、`agentrun send session/<id> --node <node> --lane <lane> --dry-run` 和 `agentrun aipod-specs render <name> --node <node> --lane <lane>` 必须使用同一套目标 lane YAML 解析。非默认 lane 的短命令形态和 `--json-stdin -o json` 形态都应显示目标 `backendProfile`、`providerId`、`workspaceRef`、executionPolicy、provider credential SecretRef 和 tool credential SecretRef 摘要；Secret 输出只显示对象名、key 名、presence/fingerprint、projection 和 `valuesPrinted=false`。如果默认 human 输出触发 `/tmp/unidesk-cli-output` dump，应先把命令收敛为 summary/table/drill-down；机器完整输出留给显式 `--full`、`--raw`、`-o json` 或等价机器消费参数。`aipod-specs render` 的残余默认 dump 归 [#862](https://github.com/pikasTech/unidesk/issues/862) 跟踪。
- `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` 资源原语 transport 来自 `config/agentrun.yaml`：
+  - `client.transport=target-trans` 时，外层先经选中 Target 的 `trans` 重入；
+  - marker、Target UniDesk 工作区和 CLI 路径全部来自 YAML；
+  - Target 内部再经 `lane-k8s-service-proxy` 访问 manager；
+  - dry-run 也必须走相同 Target 路径；
+  - 代码不得补主机、绝对路径或第二条 transport 默认值；
+  - 输出只披露 route、SecretRef、presence/fingerprint 和 `valuesPrinted=false`；
+  - `agentrun control-plane ...` 与 `git-mirror ...` 仍属于 source/runtime 运维控制路径。
 - `agentrun control-plane secret-sync --node <node> --lane <lane> --dry-run` 是 YAML SecretRef 配置维护的有界预检入口：
  - 默认文本、`-o json` 和 `-o yaml` 由同一个 compact payload 渲染；
  - payload 展示 YAML Secret ID、目标 Secret/key、source presence/fingerprint、activation fence identity/status 和关联资源 identity；