pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010204-backend-profile.md

PJ2026-010204 后端Profile

修改历史

版本	对应 commit id	更新日期	变更说明

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-010204 后端Profile需求规格

1. 文档控制

字段	内容
编号	PJ2026-010204
短名	后端Profile
层级	L2 课题
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0102 Agent编排
规格治理索引	规格治理

本文采用 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装配。
• run、command、event 和 terminal status authority 归 AgentRun核心。
• HWLAB 用户鉴权、管理页表单和业务授权归 用户管理 与 客户端。
• 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核心、Runtime装配

后端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装配、AgentRun核心

后端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装配、AgentRun发布Lane

后端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管理	客户端、用户管理、Runtime装配

后端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核心、HWLAB接入

后端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。