From 64ee0fddad10a7f48260484d75b71fcb758e1238 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 9 Jun 2026 13:38:22 +0000 Subject: [PATCH] docs: record HWLAB CaseRun gitbundle closeout rules --- docs/reference/agentrun.md | 6 ++++++ docs/reference/hwlab.md | 4 ++++ 2 files changed, 10 insertions(+) diff --git a/docs/reference/agentrun.md b/docs/reference/agentrun.md index 622a1e71..a43b41ac 100644 --- a/docs/reference/agentrun.md +++ b/docs/reference/agentrun.md @@ -109,6 +109,8 @@ AgentRun `v0.1` 的指挥官任务面已经按 AgentRun issue #105 完成真实 UniDesk 指挥官新任务入口固定使用 `bun scripts/cli.ts agentrun v01 queue|sessions`。该入口是 G14 `/root/agentrun-v01` 中官方 `./scripts/agentrun --manager-url auto` CLI 的直接 bridge；本地 `--json-file`、`--prompt-file`、`--runner-json-file` 和 `--prompt-stdin` 只会被 materialize 到 G14 临时文件后传给官方 CLI，不在 UniDesk 内实现 AgentRun queue 协议，也不把任务 double-write 回旧 Code Queue。 +AgentRun Queue 任务如果需要调用 UniDesk 维护桥，例如 `trans` / `unidesk-ssh`，runner 环境必须显式具备对应 endpoint、auth 和短连接超时配置。缺少这些运行时环境导致远端 `trans` 超时，应归为 AgentRun runner environment 问题并在 `pikasTech/agentrun` 追踪；主线 HWLAB/CaseRun 验证可以继续使用已知可用的直接 `trans` 或原入口 CLI，不应被 Queue 子任务环境缺口阻塞。 + 旧 UniDesk Code Queue 只保留历史归档、只读排障和残留旧任务停止入口。`codex submit/enqueue`、`codex steer`、`codex resume`、`codex queue create/merge`、`codex move`、旧 Web 提交表单、旧队列管理和旧 workdir 管理都必须返回冻结状态或禁用；`codex task/tasks/output/read/unread/queues` 可继续读取历史，`codex interrupt|cancel` 只用于停止残留旧任务。旧 Code Queue history 不迁移到 AgentRun，也不提供 adapter、legacy mode、fallback 或双写路径。 ## AgentRun / HWLAB 协同职责边界 @@ -125,6 +127,8 @@ HWLAB 负责自身产品和接入层，包括用户鉴权、Cloud Web/CLI 对外 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 CaseRun 需要专用 skill 时，skill 必须通过 AgentRun `gitbundle` resource bundle 装配给 Code Agent，subject repo 只作为待修改源码来源，不能携带 `.agents/skills` 副本。收口证据应同时包含正向装配和负向隔离：AgentRun trace 或 CaseRun 归档显示 `resource-bundle-materialized`、`resourceBundlePolicy` 和 `.agents/skills//SKILL.md` 读取；subject repo diff 或 artifact 中没有新增 `.agents/skills`。若 runner 已按 `gitbundle` 装配但 HWLAB case 仍把 skill 复制进 subject repo，应归为 HWLAB CaseRun 接入层问题；若 HWLAB 已按契约请求而 runner 未物化 skill，则归为 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 失败归因标准 @@ -137,6 +141,8 @@ Codex app-server/provider 返回 tool-call 参数 JSON 错误时，AgentRun 应 诊断入口只能补足同一路径上的可见性，不能形成第二套执行路径。用于复现 provider failure 的自测、fake app-server mode 或 debug command 必须调用真实 backend adapter 分类逻辑，并在完成修复后作为自测或 SPEC 合同保留；不得保留并行诊断镜像、独立执行镜像或只服务某个 issue 的替代 runtime。 +AgentRun `command-result` / result API 的 `finalResponse` 必须来自当前 command 的最新终态 assistant 输出，不能在长 trace、steer 或多 command 查询后回退到过期响应。发现 result API 与 raw events、trace rows 或 terminal command 序列不一致时，关闭 HWLAB/CaseRun 问题不能只引用 `command-result.finalResponse`；应以 AgentRun terminal status、当前 command id、raw event/trace 中最后 assistant 输出和硬件证据共同判定，并把 stale result 作为 AgentRun 可见性/结果契约问题追踪。 + ## 中文规则 AgentRun 仓库内容默认中文。AgentRun 长期文档、过程文档、issue 标题与正文、PR 标题与正文、PR 评论、review 说明和交付总结都必须使用中文。代码标识符、API path、命令名、配置键、日志字段、协议字段和不可避免的外部专有名词可以保留英文，但解释性文字必须使用中文。 diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 21056835..8e6ee99d 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -125,6 +125,10 @@ profile 配置后的最小真实验收是通过同一 HWLAB v0.2 Cloud API/Web d CaseRun 的 prompt 组装、tools-only resource bundle、skill/reference 读取边界、trace 归档和 case registry 证据形态属于 HWLAB 仓库内 `docs/reference/spec-hwpod-harness.md` 的权威范围；UniDesk 指挥侧只负责按目标 lane 重新读取 HWLAB `AGENTS.md`、使用 `G14:/root/hwlab-v02` 原入口验证，并在关闭 issue 时记录 runId、traceId、provider profile、registry commit 和负向检索摘要。不要在 UniDesk reference 里复写 CaseRun prompt 细则或 `.agents/skills` 装配实现，避免与 HWLAB runtime lane 真相分叉。 +CaseRun skill 交付边界按 `docs/reference/agentrun.md#agentrun--hwlab-协同职责边界` 判定：专用 skill 通过 AgentRun `gitbundle` 装配给 Code Agent，subject repo 不能携带 `.agents/skills` 副本。关闭要求涉及 skill 的 case 时，除 runId、traceId、provider profile 和 registry commit 外，还应记录 `resourceBundlePolicy`、实际装配的 skill 名、AgentRun/CaseRun 归档中的 skill 读取证据，以及 subject repo diff 或 artifact 中没有新增 `.agents/skills` 的负向检索结果。 + +CaseRun `summary.md`、`result.json` 和 registry aggregate 是阅读索引，不是替代原始执行证据的判定器。若 summary 中的 build/download/UART 字段与 AgentRun trace、HWPOD command output、Keil job、下载日志或 UART 输出不一致，应先用原始 trace rows、terminal command id、硬件命令输出和串口证据收口当前用户问题，同时把 summary/aggregate 语义缺口提到拥有该契约的仓库继续修复。D601 硬件 case 的 UART 证据必须来自当前 run 的串口输出；`serial-monitor` 服务或 Windows wrapper 不可用时，应先恢复或登记基础设施问题，不能把串口不可见误判为 subject 源码失败。 + ## D601 Legacy HWLAB DEV CD Wrapper 以下 UniDesk wrapper 是旧 D601 DEV CD 指挥入口，只用于显式 legacy 诊断和迁移对照。当前 HWLAB 发布、GitOps 和运行面收敛必须优先按 G14 active runtime lane 与 HWLAB repo-owned 规则执行；不要把下面的 D601 wrapper 当作当前 HWLAB release truth。