docs: 收敛 HWLAB provider profile 试机规则

AGENTS.md

@@ -90,6 +90,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - P0: `HWLAB_API_KEY` 已在 master server 和 G14 固化，统一来源路径都是 `/root/.config/hwlab-v02/master-server-admin-api-key.env`；处理 HWLAB CLI、Code Agent、HWPOD、trace/result、Web 等价 CLI 或 v0.2 验收前，必须先从当前执行 host 的该文件加载或确认 key，禁止先把问题定性为缺少 API key。
 - P0: master server 和 G14 的 `~/.bashrc` 会加载该固定文件，并通过 `BASH_ENV=$HOME/.bashenv` 让从交互 shell 派生的非交互 bash 也能读取 `HWLAB_API_KEY`；若当前进程没有继承环境，先显式 `source ~/.bashrc` 或确认该固定文件，不得改走别名、token、cookie 或临时 fallback。
 - P0: 查询 key 时只能输出 `HWLAB_API_KEY=present/missing`、source path 或 redacted prefix；禁止在 stdout、issue、trace、日志、AGENTS 或 docs 中打印完整 key。G14/HWLAB runtime 中环境变量缺失不代表 key 不存在，应先通过同一固定来源注入再继续排查。
+- P0: HWLAB v0.2 Code Agent provider profile 的 `config.toml` 与完整 Codex `auth.json` 提交、Secret 证据和真实试机验收规则统一见 `docs/reference/hwlab.md#code-agent-provider-profile-配置与验收`；AGENTS.md 只保留索引，不重复凭证语义。
 
 ## Critical AgentRun Worktree Rule
 

docs/reference/agentrun.md

@@ -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、tool alias 或业务授权的 issue，必须用 HWLAB 的 Web dispatcher 原入口，或调用同一 dispatcher 的 CLI 验证。若消费侧 Web dispatcher 没有把 `toolCredentials`、`toolAliases` 或 transient env 传给 AgentRun，应归为 HWLAB 接入层问题；若 dispatcher 已正确请求但 AgentRun runner 没有装配，应归为 AgentRun 执行基础设施问题。
 
+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 失败归因标准
 
 HWLAB 通过 AgentRun 执行 Code Agent turn 时，失败归因必须以 AgentRun backend adapter 的结构化 failure kind 为准。AgentRun 负责把 provider、thread、runner、bundle 和 command lifecycle 的失败分类成稳定语义；HWLAB 负责原样消费并映射到用户可读分类。不得为了让 UI 或 issue 收口看起来更顺，把 AgentRun/provider 错误改写成 device-pod、gateway、Cloud API endpoint 或前端渲染问题。

docs/reference/cli.md

@@ -260,6 +260,8 @@ CLI 会在 Host route、workspace route、k3s 控制面脚本和 pod route 的 s
 
 HWLAB `hwlab-cli client agent` 端到端验证经 UniDesk `trans`/`tran`/`ssh` 进入 G14 时，也按短连接 submit-and-poll 执行：在目标 workspace 和锁定 runtime env 下先 `agent send` 提交 turn，避免在可能超过 60 秒的路径上使用 `--wait` 长挂；随后多次短查询 `agent result <traceId>`、`agent trace <traceId> --render web` 或 `agent inspect --trace-id <traceId>` 取证。关闭 context-loss、AgentRun 复用或多轮会话类 issue 时，证据至少应记录 `conversationId`、`sessionId`、`threadId`、`traceId`、`runId`、`commandId` 和关键 event label。需要验证“第二轮继承第一轮上下文”时，显式传入同一 conversation/session/thread 标识，不能依赖旧 Cloud Web workspace 历史或人工印象；`--no-workspace` 这类绕过恢复的实验只可作为定位证据，不能替代默认入口验收。
 
+HWLAB Code Agent provider profile 的 `config.toml`、完整 Codex `auth.json` 写入、Secret 证据和真实 profile 试机规则统一见 `docs/reference/hwlab.md#code-agent-provider-profile-配置与验收`。本 CLI 参考只规定 `trans` 短连接和 submit-and-poll 边界，不重复维护 provider profile 凭证语义。
+
 HWLAB Cloud Web Workbench 或 Code Agent 装配类 issue 的 CLI 验证必须贴近 Web 路径：优先使用会调用同一 Cloud API/Web dispatcher 的正式 `hwlab-cli client agent` 或等价 UniDesk 高层 CLI，再从 trace/inspect/result 中确认 runner job 的 `toolCredentials`、`toolAliases`、`transientEnv`、`runId` 和 `commandId`。直接调用 AgentRun manager、手写 `dispatchHwlabAgentRun()` 或临时 runner job 只可作为基础设施 canary；它不能替代 Web Workbench 原入口验收，也不能作为关闭 Web issue 的唯一证据。若缺少这种同路径 CLI，先补 CLI 可见性和 submit-and-poll 入口，再继续修复或关闭 issue。
 
 `trans D518` 应表现为登录 D518 WSL 的 shell；`trans D518 hostname` 应像 `ssh D518 hostname` 一样只输出远端命令结果并返回远端 exit code。Provider ID 前的目标选择由 UniDesk 节点清单决定，`-p`、`-i`、`-l`、`-o` 等传统 ssh 传输参数由 provider-gateway 部署配置统一管理，CLI 会兼容性消费这些参数但不会覆盖节点侧维护桥配置。指挥官、CI 预检和其他非交互流程不要依赖 ssh-like 自由拼接；单进程标准写法是 `trans D601 argv true`，多行 shell 逻辑标准写法是 quoted heredoc 单步调用 `trans D601 script <<'SCRIPT'`。

docs/reference/g14.md

@@ -84,6 +84,8 @@ For HWLAB user-feedback, CLI, Cloud Web, AgentRun, device-pod, public API, or ru
 
 For Cloud Web Workbench and Code Agent issues, the closeout validation must use the same dispatch entry as the browser flow, or a CLI command that calls that same Cloud Web/Cloud API dispatcher path. A hand-written `dispatchHwlabAgentRun()` canary, direct AgentRun manager command, or runner job created outside the Web dispatcher is only infrastructure evidence; it cannot prove that the browser path requested the correct `toolCredentials`, `toolAliases`, transient env, conversation/session/thread binding, or runtime lane. If no CLI can exercise the Web-equivalent path, improve the CLI first and keep the issue open until the Web-equivalent CLI or browser trace proves the deployed behavior.
 
+Provider profile configuration and credential write rules for Code Agent are owned by `docs/reference/hwlab.md#code-agent-provider-profile-配置与验收`. This G14 reference only defines runtime lane and closeout evidence; do not duplicate profile Secret, `config.toml`, `auth.json` or CLI credential semantics here.
+
 For Cloud Web Workbench Code Agent response or trace-rendering bugs, the minimum Web-equivalent CLI proof is a fresh `hwlab-cli client agent send --wait` against the deployed public Web origin, followed by `hwlab-cli client agent trace <traceId> --render web` against the same origin. The submit proof must show the browser dispatcher family, normally `POST /v1/agent/chat`, result polling through `/v1/agent/chat/result/<traceId>`, `continuation.webEquivalent=true`, `shortConnection=true`, and explicit `sessionId` / `conversationId` / `threadId` binding when those values affect the bug. The result proof must show the final assistant text from `assistantText` or `reply.content`; placeholder status text, result summaries, terminal status messages, and AgentRun completion boilerplate are not acceptable substitutes for the assistant final response.
 
 For persisted final-response display regressions, a fresh turn alone is not enough when the user report identifies an existing conversation, session, or trace. Re-read the original record on the deployed `v0.2` runtime with locked lane env and the correct `projectId`; the default session list project may differ from the affected Workbench project. The minimum proof is `client session list --project-id <projectId> --limit <N> --full`, `client session inspect <conversationId> --full`, and `client agent result <traceId> --full`. Passing evidence must show that list and inspect surface the same latest agent `traceId` as `lastTraceId`, the latest agent text matches the terminal result `reply.content` or equivalent final assistant text, and known fallback text such as `Code Agent 仍在处理，可以继续 steer 或等待 trace 完成。` is absent from list, inspect, and result output. When the repair is lazy-on-read, run the read path again or capture the exposed repair source/updated marker so the evidence proves persisted conversation state was repaired, not merely synthesized for one response. `client agent trace <traceId> --render web` remains required for trace-rendering bugs; for persisted conversation-display bugs it is supporting evidence unless it returns rendered assistant rows from the same original trace.

docs/reference/hwlab.md

@@ -102,6 +102,26 @@ DeepSeek profile 应优先使用成熟 Responses/Anthropic 协议桥接方案，
 
 HWLAB 与 AgentRun 协同修复必须按 `docs/reference/agentrun.md` 的职责边界执行：AgentRun 拥有的共享执行、trace/result、backend event、runner 和 CLI 能力缺失时改 AgentRun；HWLAB 拥有的鉴权、Cloud Web/CLI 对外 API、adapter 消费、业务和前端问题改 HWLAB。不得用一侧的观测、fallback 或兼容逻辑迁就另一侧未实现或未修复的能力。
 
+### Code Agent Provider Profile 配置与验收
+
+本小节是 UniDesk 指挥侧对 HWLAB v0.2 Code Agent provider profile 配置、凭证写入和真实验收的唯一长期出处。G14 节点参考、CLI 参考和 `hwlab-code-agent` skill 只交叉引用这里；AgentRun 内部 Secret 物化和 backend adapter 设计仍以 AgentRun 仓库自身为准。
+
+HWLAB v0.2 provider profile 必须通过已部署的 HWLAB Cloud API/CLI 管理，正式入口是 `hwlab-cli client provider-profiles`。不要把手工 patch `agentrun-v01` Secret、直接调用 AgentRun manager 或临时 runner job 当作正式配置路径或关闭证据；这些只可作为基础设施定位证据。标准执行面是 `G14:/root/hwlab-v02`，调用前锁定 `HWLAB_RUNTIME_NAMESPACE=hwlab-v02`、`HWLAB_RUNTIME_WEB_URL=http://74.48.78.17:19666` 和 `HWLAB_RUNTIME_ENDPOINT_LOCKED=1`，`HWLAB_API_KEY` 从 `/root/.config/hwlab-v02/master-server-admin-api-key.env` 加载。
+
+`config.toml` 和 Codex `auth.json` 是两个独立输入。`set-config <profile> --config-stdin` 写入 profile 的 Codex 配置文本；`set-auth-json <profile> --auth-json-stdin` 写入完整 Codex auth JSON object，并在 AgentRun runtime Secret 中作为 `auth.json` key 保留。`set-key --key-stdin` 只用于单值 API key profile；当输入本来就是 Codex `auth.json` 时，不得再把它压扁、拆成单个 key、改走 legacy API-key-only 路径或保留旧断言阻塞提交。遇到 CLI 不支持完整 auth JSON、输出不可见或缺少 hash/keyPresence 等证据时，先补 HWLAB CLI/API 和 AgentRun provider-profile 能力，再继续试机。
+
+标准命令形态如下，文件名可按实际 profile 替换：
+
+```bash
+bun tools/hwlab-cli/bin/hwlab-cli.ts client provider-profiles set-config <profile> --config-stdin --no-session < config.toml
+bun tools/hwlab-cli/bin/hwlab-cli.ts client provider-profiles set-auth-json <profile> --auth-json-stdin --no-session < auth.json
+bun tools/hwlab-cli/bin/hwlab-cli.ts client provider-profiles list --no-session
+```
+
+AgentRun `v0.1` 运行面物化对象是 `agentrun-v01` namespace 中的 `agentrun-v01-provider-<profile>` Secret，稳定 key 是 `config.toml` 和 `auth.json`。文档、issue、trace 和 CLI 输出只能记录 profile 名、SecretRef、key 是否存在、字节数、redacted hash/hash suffix、resourceVersion 和验证结果；不得记录 Secret value、完整 `auth.json`、provider token、完整 API key 或可复用凭据命令。
+
+profile 配置后的最小真实验收是通过同一 HWLAB v0.2 Cloud API/Web dispatcher 路径创建 Code Agent session 并完成一轮真实 turn：`client agent session create --provider-profile <profile>`，再 `client agent send --session-id <sessionId> --provider-profile <profile>`，最后用 `client agent result <traceId>` 和 `client agent trace <traceId> --render web` 确认终端状态和最终 assistant 文本。只看到 Secret 存在、AgentRun canary 通过、PipelineRun 成功或源码测试通过，都不能替代这一真实入口验收。当前 HY 凭据对的稳定 profile 名是 `hy`；复测时使用同一标准入口，不在任何长期文档或 issue 中记录凭据内容。
+
 ## D601 Legacy HWLAB DEV CD Wrapper
 
 以下 UniDesk wrapper 是旧 D601 DEV CD 指挥入口，只用于显式 legacy 诊断和迁移对照。当前 G14 DEV/PROD 发布、GitOps 和运行面收敛必须优先按 G14 `/root/hwlab` 与 HWLAB repo-owned 规则执行；不要把下面的 D601 wrapper 当作当前 HWLAB release truth。