docs: 明确 provider profile 动态 slug 规则
This commit is contained in:
Codex
@@ -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-<profile>` 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 值。
|
||||
|
||||
@@ -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-<profile>` 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-<dynamic-lowercase-slug>`
|
||||
|
||||
不得授予 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 <profile>` 删除一个动态 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-<slug>`、`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-<slug>` 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，也不做用户级鉴权。 |
|
||||
|
||||
Reference in New Issue
Block a user