docs: add provider profile management spec

2026-06-05 15:48:30 +08:00
parent 2ebb51eed7
commit 8e64a3974a
7 changed files with 208 additions and 0 deletions
@@ -55,6 +55,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓
 - `docs/reference/spec-v01-cicd.md`：v0.1 分支、source worktree、git mirror、env reuse、namespace、GitOps、registry、CI/CD 和发布验收规格。
 - `docs/reference/spec-v01-postgres.md`：v0.1 Postgres durable store、schema migration 和 SecretRef 规格。
 - `docs/reference/spec-v01-secret-distribution.md`：v0.1 Code Agent provider credential 和运行时 Secret 分发规格。
+- `docs/reference/spec-v01-provider-profile-management.md`：v0.1 provider profile 管理 API、HWLAB 委托信任边界、API Key 写入、Secret/config 更新和 canary 规格。
 - `docs/reference/spec-v01-runtime-assembly.md`：v0.1 runner/backend 启动前的装配 SPEC，覆盖 BackendImageRef、ProfileRef、SessionRef、Git-only ResourceBundleRef、resource-scoped `toolAliases`/`promptRefs`/`skillRefs` 和 tool credential SecretRef scope。
 - `docs/reference/spec-v01-queue.md`：v0.1 AgentRun Queue 直接吸收 UniDesk Code Queue 的 RESTful API、CLI、数据模型、Session 边界和验收规格。
 - `docs/reference/spec-v01-hwlab-manual-dispatch.md`：v0.1 通过手动调度 API 为 HWLAB v0.2 提供 canary Code Agent 服务的目标、缺口和增强计划。
@@ -7,6 +7,7 @@
 - 提供 Manager 公共 API：创建和查询 run、提交 command、分页读取 events、查询 backend capability。
 - 提供手动调度 API：为已创建的 run/command 显式创建 Kubernetes runner Job，并快速返回 job identity、attempt 和轮询入口。
 - 提供 Runner 私有 API：runner register、claim run、lease heartbeat、poll commands、append events、ack command、上报 status。
+- 提供 Provider Profile 管理 API：服务端查询 profile 状态、写入 API Key、更新 Secret/config 和触发 canary；具体合同见 [spec-v01-provider-profile-management.md](spec-v01-provider-profile-management.md)。
 - 校验并持久化 `tenantId`、`projectId`、`workspaceRef`、`providerId`、`backendProfile`、`executionPolicy` 和 `traceSink`。
 - 执行最小 tenant policy boundary：只做 schema、allowlist、idempotency、secret scope 和 executionPolicy 范围检查；不内建 UniDesk/HWLAB 的业务授权。
 - 使用 Postgres 保存 runs、commands、events、runners、backends、leases 和 migration ledger。
@@ -50,12 +51,19 @@ GET  /api/v1/sessions/:sessionId/output?afterSeq=0&limit=100&runId=<runId>
 POST /api/v1/sessions/:sessionId/read
 POST /api/v1/sessions/:sessionId/control
 GET  /api/v1/backends
+GET  /api/v1/provider-profiles
+GET  /api/v1/provider-profiles/:profile
+PUT  /api/v1/provider-profiles/:profile/credential
+POST /api/v1/provider-profiles/:profile/validate
+GET  /api/v1/provider-profiles/:profile/validations/:validationId
 ```

 Session API 是异步 subagent 的轻量控制面。`state=default` 必须只返回 running 和 unread session；`state=all` 才返回历史 read session。command/run 进入 terminal 后，所属 session 的 projection 必须进入 `executionState=terminal` 并 bump version，使未读 reader 在 `ps/default` 中看到它；`POST /read` 写入 reader cursor 后，该 session 不再出现在该 reader 的默认列表中。`trace/output` 只分页读取所属 run 的 events，不代理 Queue summary；`control action=cancel` 取消 active command 或 active run。

 面向 HWLAB v0.2 canary 的手动调度 API 目标见 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)。`runner-jobs` 只显式启动当前 run/command 的 runner Job，不扫描 pending queue，不等待完整模型 turn；自动 scheduler 仍是 deferred 能力。后续 durable cancel API 必须与同一 run/command 状态机衔接，不能让 HWLAB 直接删除 Kubernetes Job 作为正式取消语义。

+Provider Profile 管理 API 是服务端委托面，不是浏览器用户 API。HWLAB `hwlab-cloud-api` 完成自身鉴权和授权后调用这些接口；AgentRun 只校验调用来源、profile allowlist、SecretRef scope、payload schema 和 redaction，不读取或判断 HWLAB Web session、用户角色或 OpenFGA relation。
+
 Runner 私有 API 的 `v0.1` 范围：

 ```http
@@ -49,6 +49,10 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
 ./scripts/agentrun runner jobs --run-id <runId> [--command-id <commandId>]
 ./scripts/agentrun runner job-status [runnerJobId] --run-id <runId>
 ./scripts/agentrun secrets codex render --dry-run [--profile codex|deepseek|minimax-m3] [--codex-home <dir>]
+./scripts/agentrun provider-profiles list
+./scripts/agentrun provider-profiles show <profile>
+./scripts/agentrun provider-profiles set-key <profile> --key-stdin
+./scripts/agentrun provider-profiles validate <profile> [--wait] [--timeout-ms <ms>]
 ./scripts/agentrun backends list
 ./scripts/agentrun server start [--port <port>] [--host <host>] [--foreground]
 ./scripts/agentrun server status [--port <port>]
@@ -85,6 +89,7 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
 - `server logs` 必须返回有界日志尾部、bytes、truncated 和 logPath；找不到日志文件时也必须返回非空 JSON。
 - `server stop` 必须按 pidFile 与端口进程清理本地 manager，并返回 before/after 状态；不得要求人工用 `ps/kill/ss` 组合命令清理常见临时服务。
 - `secrets codex render --dry-run` 返回 Codex stdio profile Secret 创建计划、输入文件 bytes/hash、SecretRef、manifest 摘要和 apply 命令形状；`--profile codex` 默认 Secret name 为 `agentrun-v01-provider-codex`，`--profile deepseek` 默认 Secret name 为 `agentrun-v01-provider-deepseek`，`--profile minimax-m3` 默认 Secret name 为 `agentrun-v01-provider-minimax-m3`；它不得输出 Secret value 或执行 Kubernetes 写操作。
+- `provider-profiles` 命令族调用 manager REST 管理 API，覆盖 profile status、API Key 写入和 canary 验证。`set-key --key-stdin` 从 stdin 读取 API Key，响应只显示 SecretRef、resourceVersion、hash 后缀和 failureKind；不得输出 key、Codex auth/config 或 Secret data。
 - `backends list` 必须显示 `codex`、`deepseek` 与 `minimax-m3` profile 的 backendKind、protocol、transport、command、requiredSecretKeys 和状态；不得因为某个 provider Secret 尚未配置就隐藏 capability。
 - `queue dispatch` 是 Q2 的受控手动调度入口，只对单个 task 显式创建 attempt 和 Core run/command/runner job；不得伪装成自动 scheduler。
 - `queue refresh` 只根据 Queue task 中保存的 Core run/command 引用回写 Queue attempt 状态，不读取 Core trace 反推 commander 或统计。
@@ -124,6 +129,10 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交

 阅读本文、[spec-v01-backend-codex.md](spec-v01-backend-codex.md) 和 [spec-v01-validation.md](spec-v01-validation.md)，然后用正式 CLI 分别创建 `backendProfile=codex`、`backendProfile=deepseek` 与 `backendProfile=minimax-m3` 的 run，按 `codex -> deepseek -> minimax-m3 -> codex` 顺序执行真实 runner。确认 CLI 输出非空 JSON，backend_status 显示正确 profile/backendKind/protocol，缺失对应 profile SecretRef 时返回 `secret-unavailable`，不会 fallback 到 `codex` 或其他 profile。

+### T5.1 Provider profile 管理 CLI
+
+阅读本文和 [spec-v01-provider-profile-management.md](spec-v01-provider-profile-management.md)，然后用 `./scripts/agentrun provider-profiles list`、`set-key deepseek --key-stdin` 和 `validate deepseek --wait` 验证 profile 管理闭环。确认 CLI 调 manager REST，不直连 Postgres，不读取 Kubernetes Secret value；输出包含 validationId/runId/commandId/jobName/resourceVersion/hash 后缀，且不包含 API Key、Codex auth/config 或 Secret data。
+
 ### T6 Queue 与 Session CLI 分层

 阅读本文和 [spec-v01-queue.md](spec-v01-queue.md)，然后用正式 CLI 创建一个 Queue task，轮询 `queue list/show/stats/commander/read`，再使用 `queue show` 返回的 `sessionPath` 调用 `sessions output/trace`。确认 Queue 命令只返回 summary/stats/read/sessionPath，不代理 output/trace；Session 命令能查询输出和 trace。最终交互验收必须使用真实 runtime，不使用 mock，不写自动交互脚本。
@@ -144,4 +153,5 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交
 | Session CLI | 已实现/Q3 | 已提供 `sessions ps/show/turn/steer/cancel/trace/output/read`；默认 ps 只显示 running/unread，terminal 后自动 unread，read cursor 由 CLI 标记。 |
 | CLI 测试规格 | 已定义/已验证主闭环 | 综合联调见 [spec-v01-validation.md](spec-v01-validation.md)；每次发布仍按手动交互验收复跑。 |
 | `deepseek` profile CLI | 已实现/已通过主闭环 | `secrets codex render --profile deepseek`、`backends list`、`runner start --backend`、`runner job` 和 JSON 错误可见性已实现；真实 CLI/RESTful 联调已通过 `codex -> deepseek -> codex` 切换主闭环。 |
+| Provider profile 管理 CLI | 目标状态 | 需要实现 `provider-profiles list/show/set-key/validate`，用于 HWLAB 委托和 operator 验收。 |
 | `minimax-m3` profile CLI | 已实现/待真实主闭环 | `secrets codex render --profile minimax-m3`、`backends list`、`runner start --backend`、`runner job`、`sessions turn --profile minimax-m3|M3` 和 JSON 错误可见性已实现；真实 CLI/RESTful 联调需要按 `codex -> deepseek -> minimax-m3 -> codex` 手动验收。 |
@@ -6,6 +6,7 @@

 - HWLAB `hwlab-cloud-api` 是业务 dispatcher：继续负责用户登录、session owner、device-pod 授权、Workbench `/v1/agent/chat` 合同、result/trace/cancel 对外接口和业务权限判断。
 - AgentRun `agentrun-mgr` 是执行事实 authority：负责 run、command、event、runner job、backend profile、SecretRef、terminal status 和手动调度 API。
+- Provider profile API Key 管理由 HWLAB Cloud API 鉴权后委托 AgentRun manager；AgentRun 信任 HWLAB 后端服务端调用，不实现 HWLAB 用户鉴权。完整合同见 [spec-v01-provider-profile-management.md](spec-v01-provider-profile-management.md)。
 - `agentrun-runner` 是手动启动的执行者：从 manager claim run、poll command、调用 backend adapter、append events、ack command、上报 command terminal，并在同一 runner Job 生命周期内继续等待同 run 的后续 command；run terminal 只由显式 run cancel 或 runner 级不可恢复失败产生。
 - HWLAB 不直接写 AgentRun Postgres、不读取 AgentRun Secret、不直接创建 Kubernetes Job；所有跨服务操作只走 AgentRun RESTful API。
 - AgentRun 不内建 HWLAB device-pod/gateway 业务授权；涉及硬件、用户授权或 device lease 的判断仍由 HWLAB 自己完成。
@@ -0,0 +1,184 @@
+# v0.1 Provider Profile 管理规格
+
+本文是 AgentRun `v0.1` provider profile 管理能力的长期规格。实施跟踪见 [pikasTech/agentrun#28](https://github.com/pikasTech/agentrun/issues/28)，HWLAB v0.2 WebUI 配置入口见 [pikasTech/HWLAB#917](https://github.com/pikasTech/HWLAB/issues/917)。
+
+## 设计目标
+
+- 由 `agentrun-mgr` 提供 provider profile 状态查询、API Key 写入、Secret/config 更新和 canary 验证 REST API。
+- AgentRun 后端直接信任来自 HWLAB `hwlab-cloud-api` 的服务端委托调用，不实现浏览器用户登录、Web session、HWLAB 用户角色或 OpenFGA 判断。
+- 浏览器和 HWLAB Cloud Web 不直接访问 AgentRun，也不把原始 API Key 传入 run/session/command payload。
+- AgentRun 只返回脱敏状态：profile、SecretRef、resourceVersion、hash 后缀、validation result、run/command/job identity 和 failureKind。
+- provider profile 仍通过现有 `backendProfile`、`executionPolicy.secretScope.providerCredentials[]`、profile-scoped SecretRef 和 writable `CODEX_HOME` 装配到 runner。
+
+## 职责边界
+
+| 组件 | 职责 |
+| --- | --- |
+| `agentrun-mgr` | provider profile 管理 API、Secret/config 写入、状态查询、canary 创建、validation 状态聚合和脱敏审计。 |
+| `agentrun-runner` | 按既有 `backendProfile`/SecretRef 装配 runtime，执行 canary run，不读取管理 API 的用户上下文。 |
+| HWLAB `hwlab-cloud-api` | 用户鉴权、业务授权、Web/CLI 同源 API、审计 actor、调用 AgentRun 管理 API。 |
+| HWLAB `hwlab-cloud-web` | “管理”页面和 API Key 表单；不直接调用 AgentRun。 |
+
+AgentRun 不承担 HWLAB 用户鉴权。它只做机器层 contract 校验：调用来源、tenant/project/profile allowlist、SecretRef scope、payload schema、redaction 和幂等性。AgentRun 不判断某个 HWLAB 用户是否能配置 API Key，也不保存 HWLAB Web session、API key 或 OpenFGA decision。
+
+## Profile 列表
+
+`v0.1` 可管理 profile 固定为：
+
+| profile | backendKind | 默认 SecretRef | 说明 |
+| --- | --- | --- | --- |
+| `codex` | `codex-app-server-stdio` | `agentrun-v01/agentrun-v01-provider-codex` | Codex API profile。 |
+| `deepseek` | `codex-app-server-stdio` | `agentrun-v01/agentrun-v01-provider-deepseek` | DeepSeek profile，经 HWLAB Moon Bridge 到 DeepSeek 官方 upstream。 |
+| `minimax-m3` | `codex-app-server-stdio` | `agentrun-v01/agentrun-v01-provider-minimax-m3` | MiniMax-M3 profile。 |
+
+profile 管理 API 不得允许任意 profile name、任意 namespace 或任意 Secret name。新增 profile 必须先更新本规格、backend capability allowlist、SecretRef 规则、CLI 和验证规格。
+
+## REST API
+
+Provider profile 管理 API 属于 `agentrun-mgr` 公共 REST API 的服务端委托面：
+
+```http
+GET  /api/v1/provider-profiles
+GET  /api/v1/provider-profiles/:profile
+PUT  /api/v1/provider-profiles/:profile/credential
+POST /api/v1/provider-profiles/:profile/validate
+GET  /api/v1/provider-profiles/:profile/validations/:validationId
+```
+
+所有成功和失败响应都必须是 JSON。失败响应至少包含 `failureKind`、`message` 和 `requestId`。所有响应不得包含 API Key 原文、Codex `auth.json` 明文、Codex `config.toml` 明文、base64 Secret data、Authorization header、Kubernetes token 或 provider request header。
+
+### `GET /api/v1/provider-profiles`
+
+返回所有允许 profile 的脱敏状态。字段至少包含：
+
+- `profile`
+- `backendKind`
+- `configured`
+- `secretRef.namespace/name/keys`
+- `resourceVersion`
+- `keyHashSuffix` 或 `credentialHashSuffix`
+- `configHashSuffix`
+- `updatedAt`
+- `lastValidation.status/failureKind/message/runId/commandId/jobName`
+
+Secret 缺失时仍要返回 profile capability，并把状态标为 `configured=false` 或 `failureKind=secret-unavailable`；不得因为 Secret 未配置而隐藏 profile。
+
+### `PUT /api/v1/provider-profiles/:profile/credential`
+
+请求体由 HWLAB 后端或受控 CLI 发送，最小形态：
+
+```json
+{
+  "apiKey": "<write-only>",
+  "config": {
+    "model": "<optional>",
+    "baseUrl": "<optional>"
+  },
+  "delegatedBy": {
+    "system": "hwlab-v02",
+    "userId": "<hwlab-user-id>",
+    "username": "<hwlab-username>",
+    "requestId": "<hwlab-request-id>"
+  },
+  "reason": "hwlab-provider-management"
+}
+```
+
+规则：
+
+- `apiKey` 只在本次 request 内用于生成 Secret data，不能落入 Postgres、event、trace、日志或响应。
+- Manager 写入 profile 对应 Kubernetes Secret 的 `auth.json` 和 `config.toml`，并返回新的 `resourceVersion` 与不可逆 hash 后缀。
+- Manager 可记录 `delegatedBy` 的脱敏审计信息，但不把它作为用户鉴权依据。
+- 非 HWLAB 委托调用可以用于 operator CLI，但也必须走同一 schema 和 redaction。
+- 非法 profile、非法 baseUrl、SecretRef scope 越界、Kubernetes 写入失败和 config render 失败必须结构化失败。
+
+### `POST /api/v1/provider-profiles/:profile/validate`
+
+触发一个真实 canary。它必须通过 AgentRun 自身 run/command/runner-job 路径执行，不得只做静态 Secret 读取、mock provider 或直接 curl provider 作为通过证据。响应短返回：
+
+```json
+{
+  "validationId": "val_...",
+  "profile": "deepseek",
+  "runId": "run_...",
+  "commandId": "cmd_...",
+  "jobName": "agentrun-v01-runner-...",
+  "status": "running",
+  "pollUrl": "/api/v1/provider-profiles/deepseek/validations/val_..."
+}
+```
+
+`GET /validations/:validationId` 聚合 command result、runner job status、events 和 provider failureKind，返回 `running|completed|failed|cancelled`。成功时必须能证明当前 `backendProfile`、SecretRef、CODEX_HOME、provider status 和 assistant reply；失败时必须保留 provider/secret/runner failureKind。
+
+## DeepSeek 配置规则
+
+`deepseek` profile 的 Codex config 必须指向 HWLAB v0.2 Moon Bridge，而不是 hyue：
+
+```text
+baseUrl: http://hwlab-deepseek-proxy.hwlab-v02.svc.cluster.local:4000/v1
+expected request path: /v1/responses
+upstream: DeepSeek 官方 API
+```
+
+AgentRun 不直接拥有 DeepSeek 官方 upstream URL 的业务路由；它只把 Codex app-server 请求送到 HWLAB Moon Bridge。若 HWLAB bridge 需要独立 upstream Secret 或 rollout，AgentRun 管理 API 必须在响应中返回 `requiresExternalBridgeUpdate=true` 或由 HWLAB 委托请求显式声明 bridge 同步已完成。AgentRun 不得把 `deepseek` 配置改到 `hyueapi.com`，也不得因 DeepSeek 失败 fallback 到 `codex`。
+
+## Secret 与 RBAC
+
+Manager ServiceAccount 需要最小 Secret 管理权限，只允许 `get`、`patch`、`update` 受控 profile Secret 名称：
+
+- `agentrun-v01-provider-codex`
+- `agentrun-v01-provider-deepseek`
+- `agentrun-v01-provider-minimax-m3`
+
+不得授予 Manager 枚举或更新 namespace 内任意 Secret 的宽权限。状态查询只读取上述 Secret metadata 和 key presence/hash，不返回 Secret value。
+
+Secret 写入后，runner Job 仍按 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 通过 SecretRef projection 装配；run/command payload 中不出现 API Key。
+
+## CLI
+
+AgentRun CLI 提供 operator 和综合联调入口：
+
+```bash
+./scripts/agentrun provider-profiles list
+./scripts/agentrun provider-profiles show deepseek
+./scripts/agentrun provider-profiles set-key deepseek --key-stdin
+./scripts/agentrun provider-profiles validate deepseek --wait --timeout-ms 120000
+```
+
+CLI 必须调用 manager REST API，不直连 Postgres，不读取 Kubernetes Secret value。`set-key --key-stdin` 从 stdin 读入 API Key，默认输出只包含 SecretRef、resourceVersion、hash 后缀、failureKind 和下一步验证命令。
+
+## 审计与脱敏
+
+Manager 审计事件允许记录：profile、action、delegatedBy.system、delegatedBy.userId、requestId、SecretRef、old/new hash 后缀、resourceVersion、validationId、runId、commandId、jobName、failureKind。禁止记录：API Key 原文、Secret data、Codex auth/config 明文、Authorization header、provider request header/body、Kubernetes token。
+
+## 验收规格
+
+### T1 profile 状态
+
+阅读本文和 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)，调用 `GET /api/v1/provider-profiles` 或 `./scripts/agentrun provider-profiles list`。确认 `codex`、`deepseek`、`minimax-m3` 全部可见，缺 Secret 时显示 `configured=false` 或 `secret-unavailable`，不隐藏 capability，不输出 Secret value。
+
+### T2 DeepSeek 写入
+
+用 `./scripts/agentrun provider-profiles set-key deepseek --key-stdin` 写入测试 key。确认输出只有 resourceVersion/hash 后缀和 redacted SecretRef；Postgres、event、trace、日志和 CLI 输出不含完整 key。
+
+### T3 DeepSeek canary
+
+用 `./scripts/agentrun provider-profiles validate deepseek --wait` 触发真实 runner canary。通过证据必须包含 validationId、runId、commandId、jobName、backendProfile=deepseek、SecretRef=`agentrun-v01-provider-deepseek`、terminal completed 和非空 assistant reply。
+
+### T4 HWLAB 委托
+
+通过 HWLAB v0.2 Cloud API `/v1/admin/provider-profiles/deepseek/credential` 和 `/validate` 调用本 API，确认 AgentRun 不要求 HWLAB 用户凭据，不读取 Web session，不返回用户权限判断；但会记录 `delegatedBy.system=hwlab-v02` 和 requestId 的脱敏审计。
+
+### T5 redaction
+
+检查 manager 日志、AgentRun events、CLI 输出和 validation result，确认不包含 API Key 原文、Codex `auth.json`、`config.toml`、Secret data 或 Authorization header。
+
+## 实现状态
+
+| 能力 | 状态 | 说明 |
+| --- | --- | --- |
+| Provider profile 管理规格 | 已定义 | 本文为 AgentRun `v0.1` profile 管理权威规格。 |
+| REST 管理 API | 目标状态 | 需要实现 `/api/v1/provider-profiles*`。 |
+| CLI 管理入口 | 目标状态 | 需要实现 `provider-profiles ...` 命令族。 |
+| DeepSeek Secret 写入 | 目标状态 | 需要按受控 SecretRef 更新 `auth.json`/`config.toml`，并保持 Moon Bridge 官方链路。 |
+| Provider canary | 目标状态 | 需要通过真实 run/command/runner-job 验证。 |
@@ -66,6 +66,8 @@

 Secret 创建和轮换必须通过 Kubernetes 密钥管理完成。`deploy/deploy.json` 只写 SecretRef 名称、key 和 mount intent；`v0.1-gitops` rendered manifests 只引用 Secret，不包含 Secret data。

+Provider API Key 的 Web 配置由 [spec-v01-provider-profile-management.md](spec-v01-provider-profile-management.md) 定义：HWLAB Cloud API 鉴权后委托 AgentRun manager 更新受控 profile Secret/config。该路径仍只写 Kubernetes Secret data，不把 API Key 写入 Git、GitOps、Postgres、event、trace、日志或 CLI 输出。
+
 ## Run secretScope 合同

 Run 的 `executionPolicy.secretScope` 只能包含引用，不包含值。provider credential 使用 `providerCredentials[]`；GitHub PR、UniDesk SSH passthrough 等 agent shell/tool 授权使用装配 SPEC 定义的 `toolCredentials[]`，不得混入 `transientEnv`。示例形态：
@@ -13,6 +13,7 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。`
 - Backend adapter 隐藏具体 Agent 工具协议，`v0.1` 使用一个真实 Codex stdio backend kind 形成闭环，并在该 kind 下支持 `codex`、`deepseek` 与 `minimax-m3` profile；其他 backend kind 不进入第一波实现。
 - AgentRun CLI 是受控操作入口，负责创建 run、提交 command、轮询 events、手动启动 runner 和查看 backend capability；CLI 不等待完整模型 turn。
 - RuntimeAssembly 是 runner/backend 启动前的装配 SPEC，负责把 backend image、profile credential、session、Git-only resource bundle 和 tool credential scope 统一成受控 Job 输入；装配权威规格见 [spec-v01-runtime-assembly.md](spec-v01-runtime-assembly.md)。
+- Provider Profile 管理是 `agentrun-mgr` 的服务端委托能力，负责 profile status、API Key 写入、Secret/config 更新和 canary 验证；HWLAB 只把已鉴权管理动作委托给 AgentRun，AgentRun 不做 HWLAB 用户鉴权。权威规格见 [spec-v01-provider-profile-management.md](spec-v01-provider-profile-management.md)。
 - AgentRun Queue 是吸收 UniDesk Code Queue 的任务队列层，负责 task、attempt、retry、judge、summary、stats、read cursor 和 commander 聚合；Queue 查询只返回 Session 引用，输出和 trace 进入 Session API/CLI。权威规格见 [spec-v01-queue.md](spec-v01-queue.md)。
 - Scheduler 是后续自动派发能力；`v0.1` 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。

@@ -85,6 +86,7 @@ Runner inbound API 只允许本地或私有诊断，不作为业务客户端入
 | AgentRun CLI | CLI/Job 工具 | 保留，P0 | JSON 输出、短返回、run/command/event/runner/backend 操作入口。 | `spec-v01-cli.md` |
 | Postgres durable store | 稳定外部服务 | 保留，P0 | 使用 `agentrun-v01-postgres` 保存 runs、commands、events、runners、backends、leases 和 migration ledger；不使用 file/sqlite 作为 v0.1 durable store。 | `spec-v01-postgres.md` |
 | Secret distribution | 系统能力 | 保留，P0 | Provider credential 只通过 Kubernetes SecretRef、ServiceAccount/RBAC 和 runner env/file projection 分发；Codex 测试凭据使用 `~/.codex/auth.json` 与 `~/.codex/config.toml` 生成 Secret projection；source、GitOps、logs 和 events 不保存明文。 | `spec-v01-secret-distribution.md` |
+| Provider Profile 管理 | 系统能力 | 保留，P0 规格 | 服务端查询/更新 provider profile Secret/config 并触发 canary；信任 HWLAB 后端委托，不实现用户鉴权。 | `spec-v01-provider-profile-management.md` |
 | RuntimeAssembly | 系统能力 | 保留，P0 规格 | runner/backend 启动前的装配 SPEC：`BackendImageRef`、`ProfileRef`、`SessionRef`、Git-only `ResourceBundleRef` 和 tool credential SecretRef scope；ProfileRef、SessionRef、ResourceBundleRef 和 GitHub tool credential env projection 已具备 v0.1 最小实现。 | `spec-v01-runtime-assembly.md` |
 | HWLAB 手动调度接入 | canary 集成目标 | 保留，P0 规格 | HWLAB `hwlab-cloud-api` 显式创建 run/command 并调用 runner Job API；AgentRun 提供 durable facts、events、cancel、bundle 和 session 能力。 | `spec-v01-hwlab-manual-dispatch.md` |
 | Tenant policy boundary | Run schema 合同 | 保留，P0 | 作为 `Run` 的必填字段和最小校验存在，不做独立 policy engine；tenant 的业务授权仍由 UniDesk/HWLAB 判定。 | 并入 `spec-v01-agentrun-mgr.md` |