切换 AgentRun 资源装配到 gitbundle
This commit is contained in:
Codex Agent
@@ -50,19 +50,19 @@ Provider profile slug 与配置是 AgentRun profile 管理数据，不是 Cloud
|
||||
|
||||
## ResourceBundle
|
||||
|
||||
- AgentRun run 必须使用 Git-only `resourceBundleRef`，默认 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` 为准。
|
||||
- 默认 `toolAliases` 会把 `tools/hwpod-cli.ts` 暴露为 `hwpod`，把 `tools/hwpod-ctl.ts` 暴露为 `hwpod-ctl`，并把 `tools/unidesk-ssh.mjs` 暴露为 runner shell 内的 `unidesk-ssh` 命令。HWPOD inspect、workspace、Keil build/download、reset 和 UART/debug-probe 操作必须优先走 `hwpod`；`unidesk-ssh` 只用于 UniDesk passthrough 任务，不能替代 HWPOD 标准路径。
|
||||
- HWPOD 快速阶段没有独立 lease 控制命令；标准 `hwpod` surface 只提交 HWPOD intent，经 compiler 生成 node-ops。Agent 不得新增 gateway shell 或其他 fallback 来绕过 `hwpod-cli -> hwpod-compiler-cli -> /v1/hwpod-node-ops -> hwpod-node`。
|
||||
- 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` 为准。
|
||||
- 默认 `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。
|
||||
- 默认 `skillRefs` 指向 `skills/hwpod-cli/SKILL.md`、`skills/hwpod-ctl/SKILL.md` 和 `skills/hwlab-agent-runtime/SKILL.md`，都为 `required=true`，由 AgentRun 聚合到当前 workspace `.agents/skills/<name>/SKILL.md`。HWLAB 不再依赖 `/app/skills`、hostPath、默认 Codex skill registry、ConfigMap 或用户长 prompt 作为 skill 注入 fallback。
|
||||
- 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`。
|
||||
|
||||
## 验收
|
||||
|
||||
- 源码合同测试：`node --test internal/agent/agentrun-dispatch.test.mjs`。
|
||||
- 语法检查：`node --check internal/agent/agentrun-dispatch.mjs && node --check internal/agent/agentrun-dispatch.test.mjs`。
|
||||
- 合同必须证明 `UNIDESK_SSH_CLIENT_TOKEN` 不出现在 `transientEnv`，GitHub/UniDesk SSH 能力都通过 AgentRun `toolCredentials` SecretRef 装配，且 runner resource bundle 默认暴露 `hwpod`、`unidesk-ssh`、`promptRefs` 和 `skillRefs`。
|
||||
- 合同必须证明 `UNIDESK_SSH_CLIENT_TOKEN` 不出现在 `transientEnv`，GitHub/UniDesk SSH 能力都通过 AgentRun `toolCredentials` SecretRef 装配，且 runner resource bundle 默认使用 `kind="gitbundle"`，trace 暴露 `bundles`、`tools`、`promptRefs` 和 `skillDirs`。
|
||||
- 真实 CLI 验收必须使用目标 profile 显式创建 session，例如 `--provider-profile dsflash-go`，再发送至少一个不传 `--provider-profile` 的 turn，证明 send 继承 session profile；不得因为某个 provider 失败自动切换 profile 并把结果记为原 profile 通过。
|
||||
- Nested profile 继承验收必须覆盖 runner env：父 AgentRun result/trace 显示目标 `backendProfile`，child `spawn` 输出 `resolvedProviderProfile=<profile>`、`profileSource=env`、`parentTraceId=<outerTraceId>`，child trace/result 使用同一个 profile/model/backend。缺少任意字段时先修可见性，不新增旧 fallback、旧门禁或兼容分支。
|
||||
|
||||
@@ -266,7 +266,7 @@ CaseRun 的 case registry repo 与 subject repo 必须分离。标准 registry r
|
||||
|
||||
agent-task CaseRun 的 evidence 必须至少记录：subject repo 本地路径、subject commit、隔离 worktree、任务 prompt 来源、Code Agent session/trace/provider/model、agent 产生的 workspace diff、验证动作和验证结果。compile-only smoke 的 evidence 不得伪造或补写 agent provenance。
|
||||
|
||||
Agent compile-only 阶段必须走 HWLAB Code Agent / AgentRun 的成熟入口：CaseRun 负责生成 prompt/context、创建或调用显式 Code Agent session，并通过 `case run start/status/result/logs` 轮询终态；prompt 必须要求 agent 在自己的 AgentRun workspace 内使用标准 `hwpod` / `hwpod-ctl` 执行 compile-only 验证，例如 `hwpod-ctl spec validate`、`hwpod inspect` 和 `hwpod build`。CaseRun 可以保留 runner 后置 compile 作为收尾或对照证据，但 evidence 必须把 agent trace 中的 HWPOD commandExecution 与 runner 后置 `hwpod-cli build` 分开记录，不得把 runner 直接编译伪装成 agent 编译。
|
||||
Agent compile-only 阶段必须走 HWLAB Code Agent / AgentRun 的成熟入口：CaseRun 负责生成 prompt/context、创建或调用显式 Code Agent session，并通过 `case run start/status/result/logs` 轮询终态；prompt 必须要求 agent 在自己的 AgentRun workspace 内使用 gitbundle 装配出的标准 `hwpod` / `hwpod-ctl` 工具执行 compile-only 验证。CaseRun 可以保留 runner 后置 compile 作为收尾或对照证据，但 evidence 必须把 agent trace 中的 HWPOD commandExecution 与 runner 后置 `hwpod-cli build` 分开记录，不得把 runner 直接编译伪装成 agent 编译。
|
||||
|
||||
CaseRun 是强化学习 Harness 的最小执行单元，但它本身不是完整 epoch。完整 epoch 还需要样本选择、策略生成、奖励/评价、批量调度、跨 run 归因和自动训练闭环；第一阶段只要求一个 `caseId` 能从 case registry repo 进入真实 HWPOD 编译闭环，并把可审计产物稳定落盘。
|
||||
|
||||
@@ -276,7 +276,7 @@ CaseRun 是强化学习 Harness 的最小执行单元，但它本身不是完整
|
||||
|
||||
`case run` 在当前版本只负责编排流程和记录原始证据，不做 evidence 自动评价、自动打分或门禁判断。流程是：prepare 先在 subject repo 本地 checkout 下创建 `.worktree/caserun-<runId>` 隔离 worktree并写入 run-local spec，然后生成 Code Agent prompt/context，创建或调用 HWLAB Code Agent session，把 isolated worktree、run-local HWPOD spec、任务目标和约束交给 Code Agent；agent 阶段结束或超时后，CaseRun 记录 agent identity、terminal result 里已有的终态字段、trace lookup hint、subject worktree 的 `git status` / `git diff --stat` / `git diff --binary`，再按 case 定义执行 runner 后置 `hwpod-cli build` 和 `cmd.run` Keil 异步 job-status 查询，最后把原始证据和可读归档写入 case registry repo 的 `runs/<caseId>/<runId>/`。固定归档包括 `evidence.json`、`summary.md`、`run.json`、`result.json`、`agent-prompt.md`、`agent-diff.patch`、run-local `.hwlab/hwpod-spec.yaml`、worker stdout/stderr、`artifact-manifest.json`，以及 `agent-messages.json`、`agent-trace.md`、`agent-transcript.md` 和 `final-response.md`。`agent-trace.md` / `agent-transcript.md` 必须包含 trace lookup hint、renderer 标识和 subject diff 区块；如果归档了完整 rendered rows，其语义必须来自共享 Web/CLI trace renderer，不能由 CaseRun 自行发明。`final-response.md` 在 terminal result 存在权威 finalResponse 时保存正文，不存在时显式记录 `finalResponse=null`、terminal/error rows 和缺失原因。下载不作为 compile-only CaseRun 的隐式步骤；后续需要下载时，应作为独立 action 显式加入 case 定义和流程记录。
|
||||
|
||||
CaseRun 下发给 AgentRun 的 workspace 必须带 run-local spec 和当前 source tree 中的 HWPOD 工具种子：`tools/hwpod-cli.ts`、`tools/hwpod-ctl.ts`、`tools/hwpod-compiler-cli.ts`、`tools/src/hwpod-harness-lib.ts`、相关合同/endpoint resolver，以及 `.agents/skills/hwpod-cli|hwpod-ctl|hwlab-agent-runtime/SKILL.md`。这不是把 prompt 写成答案，而是保证 Code Agent 看到的 `hwpod` 能力、help、别名和 `cmd.run` 组合语义与当前 `v0.2` 源码一致；不得只发送 `.hwlab/hwpod-spec.yaml` 后依赖运行面预装旧工具或旧 skill 缓存。若 agent 报告标准 `hwpod` 命令缺失或 help 明显过时，优先修 CaseRun workspace seed 或 HWPOD CLI/skill 装配，不新增 hwpod-node 专用 op，也不把业务动作旁路到 shell 脚本。
|
||||
CaseRun 下发给 HWLAB Code Agent 的请求不得再携带 ad hoc `workspaceFiles` 或 source tree 工具种子；当前工具和 skills 必须由 AgentRun `ResourceBundleRef.kind="gitbundle"` 装配，固定把 repo `tools/` 复制到 workspace `tools/`，把 repo `skills/` 复制到 workspace `.agents/skills`。这不是把 prompt 写成答案，而是保证 Code Agent 看到的 `hwpod` 能力、help、wrapper 和 `cmd.run` 组合语义与当前 `v0.2` 源码一致。若 agent 报告标准 `hwpod` 命令缺失或 help 明显过时，优先修 gitbundle runtime assembly 或 HWPOD CLI/skill 装配，不新增 hwpod-node 专用 op，也不把业务动作旁路到 shell 脚本。
|
||||
|
||||
CaseRun 的 trace 处理必须遵循 [spec-v02-code-agent-trace.md](spec-v02-code-agent-trace.md) 的组合优先原则：CaseRun 只负责稳定返回和归档 `traceId`、`sessionId`、`conversationId`、`threadId`、AgentRun 执行线索以及 `traceLookup.commands.*`，完整 trace/result/session 读取继续使用已有 `hwlab-cli client agent trace/result/inspect`。CaseRun 不应在自身内部再实现一套 `/v1/agent/chat/trace/{traceId}` 查询器、row renderer、session 反查或 final response 归因逻辑；如果已有 agent CLI 的 trace 可见性不足，先改进 `client agent trace/result/inspect`，再让 CaseRun 输出新的 ID 或 hint。归档中的 `agent-trace.json` 可以是 `lookupOnly=true` 的 identity manifest，表示“用这些 ID 调既有 CLI 查完整 trace”，不能伪装成完整 trace dump。
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ Code Agent 第一版 skill 来源分为两类：预装 skill 读取镜像内只
|
||||
## 在系统中的职责划分
|
||||
|
||||
- 证明当前 lane 中 skills bundle 随 source commit 发布，并为 live-build inventory 和 M4/M5 agent-loop 验收提供 health metadata。
|
||||
- 与 `hwlab-cloud-api` 注入给 AgentRun v0.1 的 `skillRefs` 和 skills commit/version readiness 对齐。
|
||||
- 与 `hwlab-cloud-api` 注入给 AgentRun v0.1 的 `kind="gitbundle"` skills subtree 和 skills commit/version readiness 对齐。
|
||||
- 预装 skill 只由镜像内 `/app/skills` 提供，不保存用户数据，不保存 Secret，不执行用户代码。
|
||||
- 用户上传 skill 由 `hwlab-cloud-api` 管理，普通文件直接落到 PVC `/data/user-skills`，本服务不承载上传、预览或用户数据持久化 API。
|
||||
|
||||
@@ -33,10 +33,10 @@ Code Agent 第一版 skill 来源分为两类：预装 skill 读取镜像内只
|
||||
|
||||
## Code Agent 发现路径
|
||||
|
||||
- HWLAB 旧自有发现路径只作为历史兼容线索；当前 AgentRun 装配以 `ResourceBundleRef.skillRefs` 为权威，详见 [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md)。
|
||||
- HWLAB 旧自有发现路径只作为历史线索；当前 AgentRun 装配以 `ResourceBundleRef.kind="gitbundle"` 和 `bundles[]` 为权威，详见 [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md)。
|
||||
- Codex 原生发现路径：Codex 会从工作区 `.agents/skills` 等标准位置加载 skill；因此 `hwlab-cloud-api` 必须准备 `/workspace/hwlab/.agents/skills` symlink 聚合目录，让 Codex 原生机制也能看到 `/app/skills` 与 `/data/user-skills` 中的 skill。
|
||||
- 两条发现路径都必须保留来源信息；同名 skill 不能因为 HWLAB 侧去重而消失。
|
||||
- AgentRun 装配发现路径：HWLAB v0.2 通过 AgentRun `ResourceBundleRef.skillRefs` 把 repo 内 `skills/hwpod-cli/SKILL.md`、`skills/hwpod-ctl/SKILL.md` 和 `skills/hwlab-agent-runtime/SKILL.md` 装配到 runner 工作区 `.agents/skills`。`GET /v1/skills` 必须额外返回 `agentRunAssembly` 摘要，包含 `skillRefs`、`promptRefs`、`toolAliases`、资源 bundle repo/branch/commit 和 `.agents/skills` 运行时装配目录；Cloud Web skills 面板必须展示该摘要，不能只展示 `/app/skills` 与 `/data/user-skills` 的静态列表。
|
||||
- AgentRun 装配发现路径：HWLAB v0.2 通过 AgentRun `ResourceBundleRef.kind="gitbundle"` 把 repo 内 `skills/` subtree 整体装配到 runner 工作区 `.agents/skills`。`GET /v1/skills` 必须额外返回 `agentRunAssembly` 摘要，包含 `bundles`、`promptRefs`、资源 bundle repo/branch/commit 和 `.agents/skills` 运行时装配目录；Cloud Web skills 面板必须展示该摘要，不能只展示 `/app/skills` 与 `/data/user-skills` 的静态列表。
|
||||
- MiniMax-M3 runner 引导必须说明工具调用 JSON、BusyBox/GNU 工具差异和 GitHub CLI 读 issue/PR 的低噪声用法，降低无效 tool-call arguments 与命令兼容性摩擦。
|
||||
|
||||
## API 接口说明
|
||||
|
||||
Reference in New Issue
Block a user