docs: resolve HWLAB runtime by node lane
This commit is contained in:
lyon
@@ -7,14 +7,14 @@
|
||||
- 源码入口是 `internal/agent/agentrun-dispatch.mjs`。
|
||||
- `createHwlabAgentRunDispatchAssembly()` 生成 AgentRun `POST /api/v1/runs`、`POST /api/v1/runs/:runId/commands` 和 `POST /api/v1/runs/:runId/runner-jobs` 三段 payload。
|
||||
- `dispatchHwlabAgentRun()` 使用同一 assembly 顺序调用 AgentRun manager；调用方可以注入 `fetchImpl` 做合同测试或接入真实 manager。
|
||||
- 默认 manager URL 是 `http://agentrun-mgr.agentrun-v01.svc.cluster.local:8080`，默认 namespace 是 `agentrun-v01`，默认 providerId 是 `G14`，默认 workspace branch 是 `v0.2`。
|
||||
- 默认 manager URL 是 `http://agentrun-mgr.agentrun-v01.svc.cluster.local:8080`，默认 namespace 是 `agentrun-v01`；`providerId`、workspace branch 和 runtime URL 必须由当前 issue/CLI 明确的 node + lane 装配传入，没有明确目标时才从受控 lane 配置解析。禁止把 `G14`、`v0.2` 或 D601 legacy 写成 AgentRun dispatch 的全局默认。
|
||||
- 人工和 agent 触发 HWLAB Code Agent 任务时，优先使用已成型的 `hwlab-cli client agent session create/send/result/trace`、Workbench 同路径 API 或 CaseRun 封装入口；只有在修 adapter/dispatcher/合同测试时才手写 AgentRun payload。排查 provider、API key、session 或 trace 问题时，先用这些 CLI 原入口确认 runtime config、SecretRef、session、trace 和 result，再定位具体组件，不把问题绕成 generic provider API、runner shell、直连 Cloud API 或临时脚本路径。
|
||||
|
||||
## 会话和执行边界
|
||||
|
||||
- HWLAB `conversationId` / `sessionId` / `threadId` 是用户可见业务会话 authority；AgentRun `runId` / `commandId` / `runnerJobId` 是执行尝试 identity；AgentRun `SessionRef` 和 per-session PVC 承载 backend/profile 的续接状态。不要把新建 AgentRun run/job 等同于新建 HWLAB session，也不要把复用 workspace selection 当作 session state。
|
||||
- AgentRun `type=steer` command 是作用在既有 target trace/target command 上的控制命令，不创建新的 HWLAB session，也不改变业务 `conversationId/sessionId/threadId`。HWLAB closeout 和 UI 展示必须同时保留 target command identity 与 `steerCommandId`，并从原 target trace 观察 `agentrun:steer:accepted` / `agentrun:steer:command-created`。steer command 创建成功只证明短连接控制动作已被 AgentRun 接收；目标 turn 后续 terminal 状态按原 command/result 判定。
|
||||
- HWLAB adapter 调 AgentRun 时必须固定使用 AgentRun policy 边界字段：`tenantId=hwlab`、`projectId=pikasTech/HWLAB`、`providerId=G14`。HWLAB Workbench 的 project/workspace 标识只能作为 `metadata.hwlabProjectId`、`metadata.hwlabWorkspaceId` 或 `workspaceRef` 子字段保存，不能写入 AgentRun `projectId`。如果运行面出现 `tenant-policy-denied`、project mismatch 或 workspace project 污染，临时处理是修 adapter 的字段归一化并重放最小真实请求，不放宽 AgentRun tenant policy。
|
||||
- HWLAB adapter 调 AgentRun 时必须固定使用 AgentRun policy 边界字段：`tenantId=hwlab`、`projectId=pikasTech/HWLAB`，并把当前 node/lane 解析出的 provider identity 写入 `providerId`。HWLAB Workbench 的 project/workspace 标识只能作为 `metadata.hwlabProjectId`、`metadata.hwlabWorkspaceId` 或 `workspaceRef` 子字段保存，不能写入 AgentRun `projectId`。如果运行面出现 `tenant-policy-denied`、project mismatch 或 workspace project 污染，临时处理是修 adapter 的字段归一化并重放最小真实请求，不放宽 AgentRun tenant policy。
|
||||
- 显式 HWLAB session 是用户可见 provider profile authority。`client agent session create --provider-profile <profile>` 建立 session 的 `providerProfile`，Cloud API 在 dispatch 时映射为 AgentRun `backendProfile`；后续 `client agent send --session-id <sessionId>` 在未显式传 `--provider-profile` 时继承该 session 的 `providerProfile`。workspace 只记录当前已选 session 和展示 seed，不能作为 child agent profile 继承来源，也不得用旧 workspace 状态覆盖显式 session。
|
||||
- 同一 HWLAB session 的 resume 判定看同一个 `sessionId`、`threadId`、`providerProfile/backendProfile`、AgentRun `SessionRef` 和 PVC，而不是只看是否复用了同一个 AgentRun `runId` 或 runner Job。runner pod 被删、Job 被重建或 lease 失效后的临时恢复可以创建 replacement run/job，但只有在复用同一 `SessionRef`/PVC/thread、没有拼接历史 prompt 且 assistant 能看到前序上下文时，才算 session 持久化恢复证据；它不替代 runner reuse window 内复用同一 run/runner 的长期目标。
|
||||
|
||||
@@ -51,11 +51,11 @@ Provider profile slug 与配置是 AgentRun profile 管理数据，不是 Cloud
|
||||
## ResourceBundle
|
||||
|
||||
- AgentRun run 必须使用 `ResourceBundleRef.kind="gitbundle"`，默认 repo 是 `http://git-mirror-http.devops-infra.svc.cluster.local/pikasTech/HWLAB.git`。
|
||||
- `commitId` 必须是完整 40 字符小写 SHA，不接受 branch、tag、`HEAD` 或短 SHA；`workspaceRef` 只描述目标 repo/branch，默认 branch 是 `v0.2`，实际 checkout 身份以 `resourceBundleRef.repoUrl + commitId` 为准。
|
||||
- `commitId` 必须是完整 40 字符小写 SHA，不接受 branch、tag、`HEAD` 或短 SHA；`workspaceRef` 只描述目标 repo/branch，branch 必须由当前 node/lane 装配显式给出，实际 checkout 身份以 `resourceBundleRef.repoUrl + commitId` 为准。
|
||||
- 默认 `bundles[]` 只有两项：`{ name: "hwlab-tools", subpath: "tools", target_path: "tools" }` 和 `{ name: "hwlab-agent-skills", subpath: "skills", target_path: ".agents/skills" }`。不得再发送 `toolAliases`、`skillRefs`、`workspaceFiles`、`subdir` 或 `sparsePaths`。
|
||||
- repo 自身必须提供 extensionless 工具入口，例如 `tools/hwpod`、`tools/hwpod-ctl`、`tools/hwpod-compiler`、`tools/unidesk-ssh` 和 `tools/hwlab-code-agent`；AgentRun 只把 materialized `tools/` 加入 PATH，不再生成 alias wrapper。
|
||||
- HWPOD 快速阶段没有独立 lease 控制命令；标准 `hwpod` surface 只提交 HWPOD intent，经 compiler 生成 node-ops。Agent 不得新增 gateway shell 或其他 fallback 来绕过 `hwpod -> hwpod-compiler -> /v1/hwpod-node-ops -> hwpod-node`。
|
||||
- 默认 `promptRefs` 指向 `internal/agent/prompts/hwlab-v02-runtime.md`，`inject=thread-start` 且 `required=true`。该 prompt 只在 AgentRun/Codex stdio 新 thread 首轮注入；后续 turn 必须依赖原生 `thread/resume`，不得在 command payload 中拼接历史、旧 skill 列表或长业务 prompt。
|
||||
- 默认 `promptRefs` 必须由当前 node/lane 装配选择对应 runtime prompt；v0.2 可使用 `internal/agent/prompts/hwlab-v02-runtime.md`，v0.3 或后续 lane 不得隐式回落到 v0.2 prompt。runtime prompt 只在 AgentRun/Codex stdio 新 thread 首轮注入；后续 turn 必须依赖原生 `thread/resume`，不得在 command payload 中拼接历史、旧 skill 列表或长业务 prompt。
|
||||
- skills 由 `skills/` subtree 作为整体复制到 `.agents/skills`。HWLAB 不再依赖 `/app/skills`、hostPath、默认 Codex skill registry、ConfigMap、workspace seed files、`workspaceFiles` 或用户长 prompt 作为 AgentRun runner 的 skill 注入 fallback。
|
||||
- AgentRun runtime image 已预装 `gh`，结合 `tool=github` 注入的 `GH_TOKEN` 即可访问 HWLAB/UniDesk PR 与 issue；不得把 GitHub token 放入 prompt 或 `transientEnv`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user