diff --git a/AGENTS.md b/AGENTS.md index 06dd6d6..f3e850d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 服务的目标、缺口和增强计划。 diff --git a/docs/reference/spec-v01-agentrun-mgr.md b/docs/reference/spec-v01-agentrun-mgr.md index 92b5a34..77a1dab 100644 --- a/docs/reference/spec-v01-agentrun-mgr.md +++ b/docs/reference/spec-v01-agentrun-mgr.md @@ -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= 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 diff --git a/docs/reference/spec-v01-cli.md b/docs/reference/spec-v01-cli.md index f1e2826..386caad 100644 --- a/docs/reference/spec-v01-cli.md +++ b/docs/reference/spec-v01-cli.md @@ -49,6 +49,10 @@ CLI 官方 TypeScript 入口固定为 `scripts/agentrun-cli.ts`。在 G14 非交 ./scripts/agentrun runner jobs --run-id [--command-id ] ./scripts/agentrun runner job-status [runnerJobId] --run-id ./scripts/agentrun secrets codex render --dry-run [--profile codex|deepseek|minimax-m3] [--codex-home ] +./scripts/agentrun provider-profiles list +./scripts/agentrun provider-profiles show +./scripts/agentrun provider-profiles set-key --key-stdin +./scripts/agentrun provider-profiles validate [--wait] [--timeout-ms ] ./scripts/agentrun backends list ./scripts/agentrun server start [--port ] [--host ] [--foreground] ./scripts/agentrun server status [--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` 手动验收。 | diff --git a/docs/reference/spec-v01-hwlab-manual-dispatch.md b/docs/reference/spec-v01-hwlab-manual-dispatch.md index 4a5c09c..73dc0de 100644 --- a/docs/reference/spec-v01-hwlab-manual-dispatch.md +++ b/docs/reference/spec-v01-hwlab-manual-dispatch.md @@ -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 自己完成。 diff --git a/docs/reference/spec-v01-provider-profile-management.md b/docs/reference/spec-v01-provider-profile-management.md new file mode 100644 index 0000000..f16792b --- /dev/null +++ b/docs/reference/spec-v01-provider-profile-management.md @@ -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": "", + "config": { + "model": "", + "baseUrl": "" + }, + "delegatedBy": { + "system": "hwlab-v02", + "userId": "", + "username": "", + "requestId": "" + }, + "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 验证。 | diff --git a/docs/reference/spec-v01-secret-distribution.md b/docs/reference/spec-v01-secret-distribution.md index dc1003a..4f470b7 100644 --- a/docs/reference/spec-v01-secret-distribution.md +++ b/docs/reference/spec-v01-secret-distribution.md @@ -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`。示例形态： diff --git a/docs/reference/spec-v01-services.md b/docs/reference/spec-v01-services.md index dbf7dfe..7a48795 100644 --- a/docs/reference/spec-v01-services.md +++ b/docs/reference/spec-v01-services.md @@ -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` |