Codex
141 lines
11 KiB
Markdown
141 lines
11 KiB
Markdown
# PJ2026-010204 后端Profile
|
||
|
||
## 修改历史
|
||
|
||
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|
||
| --- | --- | --- | --- |
|
||
|
||
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
|
||
|
||
## 正文
|
||
|
||
## PJ2026-010204 后端Profile需求规格
|
||
|
||
## 1. 文档控制
|
||
|
||
| 字段 | 内容 |
|
||
| --- | --- |
|
||
| 编号 | PJ2026-010204 |
|
||
| 短名 | 后端Profile |
|
||
| 层级 | L2 课题 |
|
||
| 状态 | 已生效 |
|
||
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
|
||
| 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) |
|
||
| 规格治理索引 | [规格治理](spec-governance.md) |
|
||
|
||
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 backend adapter、Codex stdio backend、provider profile、profile 管理和 redaction/failureKind 的稳定使命、范围、术语、系统边界、内部分工和原子需求。
|
||
|
||
## 2. 目的和范围
|
||
|
||
### 2.1 目的
|
||
|
||
后端Profile负责把 AgentRun runner 与具体 Code Agent provider 隔离开来，使 `codex`、`deepseek`、`minimax-m3`、`dsflash-go` 和动态 Codex-compatible profile 能通过同一 backend adapter、同一 Codex app-server stdio 协议和同一 redaction/failureKind 语义执行。
|
||
|
||
### 2.2 范围内
|
||
|
||
- Backend adapter 合同：profile resolution、prepare、startTurn、interrupt、finalize 和 redact。
|
||
- Codex CLI app-server JSON-RPC over stdio backend kind，包括 thread start/resume、turn start/steer/interrupt 和 normalized events。
|
||
- `codex`、`deepseek`、`minimax-m3`、`dsflash-go` profile 的 SecretRef、config、model catalog、CODEX_HOME 隔离和切换不污染。
|
||
- Provider profile 管理 API：list/show/delete/config/credential/validate 和 canary 聚合。
|
||
- provider/auth/backend/protocol/timeout/cancel 错误到 failureKind 的映射，以及 credential redaction。
|
||
|
||
### 2.3 范围外
|
||
|
||
- provider credential 的 SecretRef 投影和 runtime home 装配归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。
|
||
- run、command、event 和 terminal status authority 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)。
|
||
- HWLAB 用户鉴权、管理页表单和业务授权归 [用户管理](PJ2026-0105-user-management.md) 与 [客户端](PJ2026-0104-client.md)。
|
||
- DeepSeek、MiniMax 或其他 provider 的外部 upstream 可用性不由 AgentRun 伪装成功；失败只能结构化归因。
|
||
- 旧 MiniMax/OpenCode 直连路线不作为 fallback、judge backend 或 Queue 首版能力。
|
||
|
||
## 3. 术语表
|
||
|
||
| 术语 | 定义 |
|
||
| --- | --- |
|
||
| Backend adapter | runner 与具体 Code Agent 工具之间的适配层，负责协议调用、事件归一化、失败映射和 redaction。 |
|
||
| backendProfile | run 中选择的 provider/profile slug，例如 `codex`、`deepseek`、`minimax-m3`、`dsflash-go` 或动态 slug。 |
|
||
| backendKind | backend 协议实现类型；`v0.1` 固定使用 `codex-app-server-stdio`。 |
|
||
| Codex stdio backend | 通过 `codex app-server --listen stdio://` 执行 JSON-RPC over stdio turn 的 backend kind。 |
|
||
| client request | Codex app-server stdio 协议中由 app-server 发给 runner client、需要显式响应的 JSON-RPC 请求。 |
|
||
| Provider Profile 管理 | Manager 提供的服务端委托 API，用于 profile 状态查询、API key/config 写入和 canary 验证。 |
|
||
| profile isolation | 不同 profile 的 SecretRef、CODEX_HOME、model、model catalog 和 upstream 配置互不污染。 |
|
||
| model-catalog | `dsflash-go` 等 profile 使用的模型目录文件，用于声明模型元数据和上下文能力。 |
|
||
|
||
## 4. 系统边界和接口
|
||
|
||
本规格把后端Profile作为 AgentRun 的 provider/backend 适配系统看待；本章只描述输入、输出和责任边界。
|
||
|
||
| 边界项 | 内容 |
|
||
| --- | --- |
|
||
| 外部使用者 | AgentRun runner、AgentRun核心、Runtime装配、HWLAB provider 管理入口、CLI 和平台运维。 |
|
||
| 外部输入 | backendProfile、ProfileRef、SecretRef projection、command payload、SessionRef/threadId、initialPrompt、skill summary 和 provider profile 管理请求。 |
|
||
| 受控资源 | backend adapter、Codex app-server stdio 子进程、profile capability、provider profile Secret/config、canary run 和 redaction policy。 |
|
||
| 外部输出 | normalized events、assistant message、tool call、command output、terminal status、failureKind、backend capability、profile status 和 validation result。 |
|
||
| 用户接口 | `GET /api/v1/backends`、Provider Profile 管理 API、AgentRun CLI provider/backends 命令和 HWLAB 委托管理 API。 |
|
||
| 系统边界 | 后端Profile负责 provider 协议和 profile 管理合同；不保存 Secret value，不判断 HWLAB 用户权限，不扩大 executionPolicy，不用另一个 profile 隐式 fallback。 |
|
||
|
||
## 5. 内部分工与规格索引
|
||
|
||
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| PJ2026-01020401 | Adapter合同 | 本规格 6.1 | resolve/prepare/start/interrupt/finalize/redact 和事件归一化 | AgentRun Core、RuntimeAssembly | Runner、Result envelope |
|
||
| PJ2026-01020402 | Codex协议 | 本规格 6.2 | Codex app-server stdio JSON-RPC、thread/turn/steer/interrupt | Adapter合同、ProfileRef | 真实 provider turn |
|
||
| PJ2026-01020403 | Profile隔离 | 本规格 6.3 | codex/deepseek/minimax-m3/dsflash-go/dynamic profile capability 和隔离 | Secret投影、Runtime home | Backend adapter、验证模型 |
|
||
| PJ2026-01020404 | Profile管理 | 本规格 6.4 | provider profile status、config/key 写入、delete 和 canary validation | HWLAB 后端委托、Kubernetes Secret | 客户端管理页、CLI |
|
||
| PJ2026-01020405 | 失败脱敏 | 本规格 6.5 | provider/auth/backend/protocol failureKind 和 redaction | Backend adapter、SecretRef | Core result、HWLAB 接入 |
|
||
|
||
## 6. 原子需求
|
||
|
||
### 6.1 AR-BACKEND-REQ-001 Backend Adapter 合同
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| AR-BACKEND-REQ-001 | Adapter合同 | PJ2026-01020401 Adapter合同 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |
|
||
|
||
后端Profile应提供稳定 Backend adapter 合同，使 runner 能按 `backendProfile` 解析 capability，准备 execution context，启动 turn，尝试 interrupt，归一化终态，并对输出做 redaction。
|
||
|
||
Adapter 输入必须来自 manager 持久化后的 run/command 和 RuntimeAssembly Secret projection，不得从 CLI 参数、临时环境变量或 Git 文件读取 provider credential 明文。unknown profile 必须结构化失败，不得静默映射到默认 `codex`。
|
||
|
||
### 6.2 AR-BACKEND-REQ-002 Codex Stdio Backend
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| AR-BACKEND-REQ-002 | Codex协议 | PJ2026-01020402 Codex协议 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md) |
|
||
|
||
后端Profile应以 Codex CLI app-server JSON-RPC over stdio 作为 `v0.1` 第一真实 backend kind，按 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`、`turn/steer` 和 `turn/interrupt` 处理真实 Code Agent turn。
|
||
|
||
直接 Responses HTTP、OpenAI SDK wrapper、`codex exec` 一次性输出、fake provider、固定文本回复或本地 shell 模拟不能作为正式 backend 实现或综合联调通过证据。裸 HTTP 或 `codex exec --json` 只能作为 provider/upstream 诊断辅助。
|
||
|
||
Codex stdio backend 必须把 app-server 发来的 JSON-RPC client request 当作一等协议处理，不能只等待 notification。request id 可以是数字或字符串；approval、tool input、elicitation 和未知 client request 都必须得到结构化响应，并追加可审计 trace event。忽略 client request 会让真实 assistant partial output 卡在等待状态，不能被包装成 completed。
|
||
|
||
命令执行 trace 必须由 backend/result 层做有界裁剪和摘要，保留 command bytes、output bytes、truncated 标记、stderr 摘要和可展开入口。前端、CLI 或 prompt 不应要求 Code Agent 默认给 shell 命令加 `head`、`grep` 或管道来避免输出过长；输出裁剪属于 trace/result 表达职责，不是工具调用完成条件。
|
||
|
||
### 6.3 AR-BACKEND-REQ-003 Profile 隔离与切换
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| AR-BACKEND-REQ-003 | Profile隔离 | PJ2026-01020403 Profile隔离 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) |
|
||
|
||
后端Profile应支持 `codex`、`deepseek`、`minimax-m3`、`dsflash-go` 和符合规则的动态 Codex-compatible profile，并保证它们共享协议但隔离 SecretRef、CODEX_HOME、model、model catalog 和 upstream 配置。
|
||
|
||
任一 profile 的 SecretRef 缺失、config 缺失或 provider 失败都不得 fallback 到另一个 profile。`dsflash-go` 必须携带 profile-scoped `model-catalog.json`；缺少 model catalog 时应在 provider 调用前结构化失败。
|
||
|
||
### 6.4 AR-BACKEND-REQ-004 Provider Profile 管理
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| AR-BACKEND-REQ-004 | Profile管理 | PJ2026-01020404 Profile管理 | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |
|
||
|
||
后端Profile应由 `agentrun-mgr` 提供 provider profile 状态查询、config/API key 写入、Secret/config 更新、删除和 canary 验证 API，使 HWLAB 后端能在完成自身鉴权后委托 AgentRun 更新受控 profile。
|
||
|
||
AgentRun 不承担 HWLAB 用户鉴权，不保存浏览器 session、用户角色或 OpenFGA decision。管理 API 只校验调用来源、profile allowlist、SecretRef scope、payload schema、redaction 和幂等性；响应只返回 profile、SecretRef、hash 后缀、validation result、run/command/job identity 和 failureKind。
|
||
|
||
### 6.5 AR-BACKEND-REQ-005 FailureKind 与 Redaction
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| AR-BACKEND-REQ-005 | 失败脱敏 | PJ2026-01020405 失败脱敏 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md) |
|
||
|
||
后端Profile应把 provider auth failure、provider unavailable、backend protocol error、thread resume failure、timeout、cancel 和 unsupported capability 映射为 AgentRun 可消费的 failureKind。
|
||
|
||
event、trace、日志、health、diagnostics、CLI 输出和 provider profile 响应不得打印 API key、Authorization header、DSN password、token、URL credential、Codex `auth.json`、Codex `config.toml` 或 Secret value。可以输出 request id、HTTP status 分类、SecretRef、profile、backendKind、protocol 和 redacted details。
|