From f86bee456376500b15ad0a99e5a8f1b246c17811 Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 8 Jun 2026 10:33:18 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=98=8E=E7=A1=AE=20provider=20profile?= =?UTF-8?q?=20=E5=8A=A8=E6=80=81=20slug=20=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/spec-v01-agentrun-mgr.md | 4 ++-- .../spec-v01-provider-profile-management.md | 24 +++++++++++++------ 2 files changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/reference/spec-v01-agentrun-mgr.md b/docs/reference/spec-v01-agentrun-mgr.md index c44e15c..04d931e 100644 --- a/docs/reference/spec-v01-agentrun-mgr.md +++ b/docs/reference/spec-v01-agentrun-mgr.md @@ -125,7 +125,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB | `projectId` | 必填，例如 `pikasTech/unidesk`、`pikasTech/HWLAB`。 | | `workspaceRef` | 必填，描述 source/worktree/workspace，不由 runner 猜测。 | | `providerId` | 必填，例如 `G14`、`D601`；只表示目标 provider，不直接授予业务权限。 | -| `backendProfile` | 必填，`v0.1` allowlist 为 `codex`、`deepseek` 与 `minimax-m3`；三者共享 Codex stdio backend kind。 | +| `backendProfile` | 必填，必须是小写 slug；`codex`、`deepseek`、`minimax-m3`、`dsflash-go` 是内建 profile，动态 slug 通过 `agentrun-v01-provider-` SecretRef 生效。当前这些 profile 共享 Codex stdio backend kind。 | | `executionPolicy` | 必填或由 manager 显式补齐默认值，至少包含 sandbox、approval、timeout、network 和 secretScope。 | | `traceSink` | 字段必须存在；可以为 `null` 或显式 sink。 | @@ -135,7 +135,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB `v0.1` 不实现独立 policy engine。Manager 只做基础边界收敛： -- 校验 tenant/project/provider/backendProfile 是否在 `v0.1` 允许集合内；当前 backendProfile 允许 `codex`、`deepseek` 与 `minimax-m3`。 +- 校验 tenant/project/provider/backendProfile 是否符合 `v0.1` 允许范围；当前 backendProfile 允许内建 profile 和符合小写 slug 规则的动态 profile，动态 profile 必须有匹配 provider credential SecretRef，不能 fallback 到其他 profile。 - 校验 workspaceRef 形态存在且与 tenant 请求一致；不替 tenant 判断某个 repo 操作是否业务授权。 - 校验 executionPolicy 不扩大 sandbox、network、approval、timeout 和 secretScope。 - 校验 secretScope 只引用 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md) 中允许的 SecretRef，且存在与 `backendProfile` 同名的 provider credential；manager 只校验引用形态，不读取 Secret 值。 diff --git a/docs/reference/spec-v01-provider-profile-management.md b/docs/reference/spec-v01-provider-profile-management.md index dbaec7c..6a27170 100644 --- a/docs/reference/spec-v01-provider-profile-management.md +++ b/docs/reference/spec-v01-provider-profile-management.md @@ -23,15 +23,16 @@ AgentRun 不承担 HWLAB 用户鉴权。它只做机器层 contract 校验：调 ## Profile 列表 -`v0.1` 可管理 profile 固定为： +`v0.1` 可管理 profile 分为内建 profile 与动态 profile slug。内建 profile 是无需 Secret 也必须出现在列表中的稳定能力；动态 profile 是管理员通过 HWLAB Cloud API / HWLAB CLI 或 AgentRun CLI 写入受控 Secret 后立即可见、可配置、可验证的 profile，不需要为每个新 slug 修改 AgentRun 或 HWLAB 服务代码。 | 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。 | +| `dsflash-go` | `codex-app-server-stdio` | `agentrun-v01/agentrun-v01-provider-dsflash-go` | DeepSeek V4 Flash profile，经 HWLAB Moon Bridge 到 OpenCode Zen Go upstream。 | -profile 管理 API 不得允许任意 profile name、任意 namespace 或任意 Secret name。新增 profile 必须先更新本规格、backend capability allowlist、SecretRef 规则、CLI 和验证规格。 +动态 profile slug 必须匹配小写 slug 规则 `^[a-z0-9][a-z0-9-]{0,63}$`，并固定映射到同 namespace 内 `agentrun-v01-provider-` SecretRef，required keys 仍为 `auth.json` 与 `config.toml`。profile 管理 API 不得允许任意 namespace、任意 Secret name、`runtime-default` 或不符合 slug 规则的 profile。新增普通 OpenAI/Codex-compatible provider profile 时，管理员应优先通过 `provider-profiles set-config` / `set-key` / `validate` 创建动态 slug；只有需要新的 backend kind、特殊装配规则、额外 Secret key、租户策略或产品级固定友好名时，才更新本规格、内建 capability、CLI 示例和验证规格。 ## REST API @@ -52,7 +53,7 @@ GET /api/v1/provider-profiles/:profile/validations/:validationId ### `GET /api/v1/provider-profiles` -返回所有允许 profile 的脱敏状态。字段至少包含： +返回所有内建 profile 与已存在动态 profile 的脱敏状态。动态 profile 通过受控 Secret 的 name、label 或 annotation 发现；删除动态 profile 的最后一个 Secret 后，它不再出现在 collection list 中。字段至少包含： - `profile` - `backendKind` @@ -139,13 +140,15 @@ AgentRun 不直接拥有 DeepSeek 官方 upstream URL 的业务路由；它只 ## Secret 与 RBAC -Manager ServiceAccount 需要最小 Secret 管理权限，只允许 `get`、`patch`、`update` 受控 profile Secret 名称： +Manager ServiceAccount 需要最小 Secret 管理权限，只允许 `get`、`list`、`create`、`replace`、`delete`、`patch` 受控 provider profile Secret： - `agentrun-v01-provider-codex` - `agentrun-v01-provider-deepseek` - `agentrun-v01-provider-minimax-m3` +- `agentrun-v01-provider-dsflash-go` +- `agentrun-v01-provider-` -不得授予 Manager 枚举或更新 namespace 内任意 Secret 的宽权限。状态查询只读取上述 Secret metadata 和 key presence/hash，不返回 Secret value。 +不得授予 Manager 更新 namespace 内任意 Secret 的宽权限；动态 Secret 必须受 `agentrun-v01-provider-` 前缀、profile label/annotation 和 slug 校验约束。状态查询只读取受控 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。 @@ -163,6 +166,8 @@ AgentRun CLI 提供 operator 和综合联调入口： ./scripts/agentrun provider-profiles set-key deepseek --key-stdin ./scripts/agentrun provider-profiles set-config deepseek --config-stdin ./scripts/agentrun provider-profiles validate deepseek --wait --timeout-ms 120000 +./scripts/agentrun provider-profiles set-config my-provider --config-stdin +./scripts/agentrun provider-profiles set-key my-provider --key-stdin ``` CLI 必须调用 manager REST API，不直连 Postgres，不读取 Kubernetes Secret value。`set-key --key-stdin` 从 stdin 读入 API Key，默认输出只包含 SecretRef、resourceVersion、hash 后缀、failureKind 和下一步验证命令。 @@ -175,7 +180,7 @@ Manager 审计事件允许记录：profile、action、delegatedBy.system、deleg ### 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。 +阅读本文和 [spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)，调用 `GET /api/v1/provider-profiles` 或 `./scripts/agentrun provider-profiles list`。确认 `codex`、`deepseek`、`minimax-m3`、`dsflash-go` 等内建 profile 全部可见，缺 Secret 时显示 `configured=false` 或 `secret-unavailable`，不隐藏 capability；已创建的动态 slug 也会列出；所有输出都不得包含 Secret value。 ### T2 DeepSeek 写入 @@ -197,13 +202,18 @@ Manager 审计事件允许记录：profile、action、delegatedBy.system、deleg 用 `./scripts/agentrun provider-profiles remove ` 删除一个动态 slug，再删除一个内建 profile。确认动态 slug 从 collection list 消失；内建 profile 仍留在 list 中但 `configured=false`；CLI/日志/响应不输出 Secret value。 +### T7 动态 profile 无代码变更 + +用 HWLAB CLI 或 AgentRun CLI 对一个临时动态 slug 执行 `set-config`、`set-key`、`list`、`remove`。通过证据必须显示 profile SecretRef 为 `agentrun-v01-provider-`、`configured=true` 只在 `auth.json` 和 `config.toml` 同时存在时成立、删除后 collection list 不再包含该 slug，并且整个过程没有 AgentRun/HWLAB service code change、PR、PipelineRun 或 rollout 作为前置条件。 + ## 实现状态 | 能力 | 状态 | 说明 | | --- | --- | --- | | Provider profile 管理规格 | 已定义/已落地 | 本文为 AgentRun `v0.1` profile 管理权威规格。 | | REST 管理 API | 已实现 | `agentrun-mgr` 提供 `/api/v1/provider-profiles*`，覆盖 list/show/remove/set-key/validate/validation。 | -| CLI 管理入口 | 已实现 | `./scripts/agentrun provider-profiles list/show/remove/set-key/validate` 调用 manager REST API，不直连 Secret value。 | +| 动态 profile slug | 已实现 | 小写 slug 通过 `agentrun-v01-provider-` SecretRef 动态生效；普通 provider API Key/config 轮换不需要为每个新 slug 修改服务代码或触发专门 CI/CD。 | +| CLI 管理入口 | 已实现 | `./scripts/agentrun provider-profiles list/show/remove/set-key/set-config/validate` 调用 manager REST API，不直连 Secret value。 | | DeepSeek Secret 写入 | 已实现/需硬化 | 已按受控 SecretRef 更新 `auth.json`/`config.toml` 并保持 HWLAB Moon Bridge 官方链路；后续必须去除 credential update 产生 `last-applied-configuration` 注解的副作用。 | | Provider canary | 已实现 | canary 通过真实 run/command/runner-job 路径执行，并返回 validationId、runId、commandId、jobName 和 terminal status。 | | HWLAB 委托信任边界 | 已验证 | HWLAB v0.2 通过 Cloud API 委托调用本 API；AgentRun 不读取 HWLAB Web session，也不做用户级鉴权。 |