docs: record agentrun gitbundle ref authority

2026-06-08 07:20:28 +00:00
parent 10abbc0467
commit 25bee7b3cd
2 changed files with 3 additions and 0 deletions
@@ -97,6 +97,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - P0: `pikasTech/agentrun` 是新的共享 Agent 执行基础设施仓库，不是现有 Code Queue 的就地替换；`v0.1` source truth 是 G14 节点固定 source worktree `G14:/root/agentrun-v01`，固定使用 `v0.1` 分支和 `origin git@github.com:pikasTech/agentrun.git`。
 - P0: AgentRun `v0.1` 开发必须先预检 `G14:/root/agentrun-v01` 的路径、分支、remote 和 clean 状态，再在 `/root/agentrun-v01/.worktree/{pr_branch}` 创建独立 worktree 修改；不要把固定 source worktree、UniDesk、HWLAB、D601 或临时 clone 当作 AgentRun scratch 区。
 - P0: AgentRun 废弃旧 `dev/prod` 运行口径；`v0.1` 固定部署目标是 `G14:k3s` 上的 `agentrun-v01` namespace，后续按 `v0.1`、`v0.2`、`v0.3` lane 滚动。
+- P0: HWLAB 到 AgentRun 的 `gitbundle` 资源装配必须以 repo URL + workspace ref 为 checkout authority，HWLAB 默认通过 G14 git mirror 拉取 `v0.2`；cloud-api、CI/CD 或 rollout 注入的旧 commit 只能作为 requested hint，不得重新成为默认物化来源，细则见 `docs/reference/agentrun.md`。
 - P0: 所有 AgentRun k3s 操作必须使用 route 语法 `G14:k3s`，UniDesk 侧只维护 AgentRun 的开发和部署运维约束，细则见 `docs/reference/agentrun.md`。
 - P0: AgentRun 的文档、issue、PR、review 和交付说明一律中文；代码标识符、API path、配置键、命令和必要英文专有名词可保留英文，解释性文字必须中文。

@@ -115,6 +115,8 @@ HWLAB 负责自身产品和接入层，包括用户鉴权、Cloud Web/CLI 对外

 直接通过 AgentRun manager、`dispatchHwlabAgentRun()` 或手写 runner job 发起的 canary 只能证明 AgentRun 基础设施和凭据投影本身可用，不能证明 HWLAB Cloud Web/Cloud API 的产品入口已经正确请求这些能力。涉及 Cloud Web Workbench、用户会话、conversation/session/thread、AgentRun runtime assembly 或业务授权的 issue，必须用 HWLAB 的 Web dispatcher 原入口，或调用同一 dispatcher 的 CLI 验证。当前 HWLAB v0.2 到 AgentRun 的资源装配权威是 HWLAB `docs/reference/agentrun-code-agent-dispatch.md` 和 AgentRun `docs/reference/spec-v01-runtime-assembly.md`：`ResourceBundleRef.kind="gitbundle"` 通过 `bundles[]` 装配 `tools/` 和 `.agents/skills`，旧 `toolAliases` / `skillRefs` / `workspaceFiles` 不再是有效接入口。若消费侧 Web dispatcher 没有按该契约传递 `gitbundle`、tool credential 或 transient env，应归为 HWLAB 接入层问题；若 dispatcher 已正确请求但 AgentRun runner 没有装配，应归为 AgentRun 执行基础设施问题。

+HWLAB 的 `gitbundle` checkout authority 是 repo URL + workspace ref，而不是 cloud-api artifact revision。默认路径必须通过 G14 git mirror 拉取 HWLAB `v0.2` ref，AgentRun runner 物化后记录实际 commit；cloud-api、CI/CD 或 rollout 注入的 `commitId` 只可作为 requested hint 或显式 pin 的输入，不得作为默认 materialization 来源。关闭相关 issue 时，证据必须同时显示 `repoUrl`、`requestedRef`、actual `commitId`，以及 `bundles/tools/promptRefs/skillDirs` 摘要；若 actual `commitId` 仍等于旧 cloud-api rollout commit 且不是显式 pin，应继续归为 AgentRun bundle 物化问题。
+
 HWLAB Code Agent provider profile 的 `config.toml`、完整 Codex `auth.json` 提交、Secret 证据和真实 profile 试机规则统一见 `docs/reference/hwlab.md#code-agent-provider-profile-配置与验收`。本 AgentRun 参考只维护 AgentRun 仓库、运行面、CI/CD 和跨仓库职责边界，不重复维护 HWLAB profile 凭证语义。

 ## AgentRun / HWLAB 失败归因标准