mirrors/pikasTech-agentrun
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7b3c0ea584fde4731c946595a84eba65661a2607
pikasTech-agentrun/docs/reference/spec-v01-services.md
T
Codex 8e64a3974a docs: add provider profile management spec
2026-06-05 15:48:30 +08:00

22 KiB
Raw Blame History

v0.1 服务总体规格

本文是 AgentRun v0.1 服务总览和取舍规格。它定义 v0.1 lane 中哪些组件必须保留，哪些只作为 deferred 方向，以及单服务规格的后续拆分边界。

docs/reference/spec-v01-*.md 是 v0.1 服务、CLI、CI/CD 和系统能力的权威出处。代码开发和测试编写必须先对齐对应 spec，再修改实现或测试。

在系统中的职责划分

AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。v0.1 先完成最小纵向闭环；下一阶段 UniDesk Code Queue 的队列产品能力直接吸收到 AgentRun Queue，不做 adapter 过渡、双写或旧 API/UI/CLI 兼容层。HWLAB 现有 Code Agent 路径仍按 canary 节奏接入，不由 Queue 吸收规格替代 HWLAB 业务路由。

  • agentrun-mgr 是公共 RESTful API 和 durable facts authority，负责 run、command、event、runner、backend、lease 的持久状态和鉴权前置边界。
  • agentrun-runner 是短生命周期 per-run 或 per-attempt 执行者，必须从 manager claim run，并把 event、heartbeat 和 terminal status 写回 manager。
  • 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。
  • Provider Profile 管理是 agentrun-mgr 的服务端委托能力，负责 profile status、API Key 写入、Secret/config 更新和 canary 验证；HWLAB 只把已鉴权管理动作委托给 AgentRun，AgentRun 不做 HWLAB 用户鉴权。权威规格见 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。
  • Scheduler 是后续自动派发能力；v0.1 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。

HWLAB 手动调度服务目标

v0.1 面向 HWLAB v0.2 的下一阶段目标是通过手动调度 API 提供 canary Code Agent 执行服务，而不是先实现自动 scheduler。HWLAB hwlab-cloud-api 作为业务 dispatcher，完成用户/session/device 权限判断后，显式调用 AgentRun REST API 创建 run、提交 command、启动 runner Job，并把 AgentRun events/terminal status 转换回 HWLAB result/trace。完整目标、非目标、缺口和增强计划见 spec-v01-hwlab-manual-dispatch.md。

该目标要求优先补齐四类能力：SessionRef 持久化、Git-only ResourceBundleRef materialization、durable cancel、trace/result 元语。上述四项已进入 v0.1 最小实现；自动 scheduler、跨 backend 自动路由和独立 UI 仍然 deferred，不能成为 HWLAB canary 的前置条件。

语言与协议选型

AgentRun v0.1 的自研组件优先使用 Bun + TypeScript 实现：agentrun-mgr、agentrun-runner、backend adapter、Codex backend、AgentRun CLI 和后续 scheduler 都属于该边界。官方 TypeScript CLI 入口固定为 scripts/agentrun-cli.ts，入口只做参数解析和路由，复杂逻辑拆到 scripts/src/ 与 src/；G14/CI/人工非交互命令使用 ./scripts/agentrun launcher 启动同一入口。Postgres、Kubernetes、Tekton、Argo CD、YAML manifest 和 shell 级容器启动命令属于外部运行面或部署面，不受“必须 TypeScript 实现”的约束。

backendProfile=codex、backendProfile=deepseek 与 backendProfile=minimax-m3 的 v0.1 协议固定为同一个 Codex CLI app-server JSON-RPC over stdio backend kind：runner/backend adapter 启动受控 codex app-server --listen stdio:// 子进程，经 stdin/stdout 发送换行分隔 JSON-RPC，请求顺序至少覆盖 initialize、thread/start 或 thread/resume、turn/start。backendProfile 只选择 profile/config/SecretRef；backendKind、protocol 和进程生命周期仍是 codex-app-server-stdio。直接调用 Responses HTTP、OpenAI SDK、codex exec 一次性输出或文本 fallback 只能作为诊断/自测试辅助，不能作为 Codex backend 综合联调通过证据。

实现参考必须优先读取并吸收两个成熟代码路径：UniDesk Code Queue 的 Bun/TS src/components/microservices/code-queue/src/code-agent/codex.ts 与 common.ts，以及 HWLAB v0.2 的 internal/cloud/codex-stdio-session.mjs、scripts/code-agent-chat-smoke.mjs、docs/reference/spec-v02-deepseek-proxy.md、docs/reference/code-agent-chat-readiness.md。AgentRun 复用的是 stdio JSON-RPC、session/turn 生命周期、trace、redaction、Secret projection、profile overlay、DeepSeek/Moon Bridge 分层诊断和 failureKind 经验，不复制 UniDesk/HWLAB 的环境专用路径、业务 prompt、bridge host、namespace 或明文凭据。

Backend Profile 边界

v0.1 需要支持三个可手动选择的 backend profile，但不引入完整多 backend 调度：

backendProfile backendKind v0.1 处理 SecretRef 说明
codex codex-app-server-stdio 保留，P0 agentrun-v01-provider-codex 现有 GPT/Codex profile，必须保持默认行为不回归。
deepseek codex-app-server-stdio 新增，P0 agentrun-v01-provider-deepseek DeepSeek-compatible Codex profile；通过 profile 专属 auth.json/config.toml 或等价 SecretRef 配置上游、模型和 base URL。
minimax-m3 codex-app-server-stdio 新增，P0 agentrun-v01-provider-minimax-m3 MiniMax-M3 OpenAI-compatible Codex profile；沿 DeepSeek 相同路径由 auth.json/config.toml 配置上游、模型和 base URL。

完整多 backend 路由仍然 deferred。v0.1 只允许 manager/runner 按 run 中的 backendProfile 显式选择 codex、deepseek 或 minimax-m3，并在 capability 中报告三者共享同一个 protocol=codex-app-server-jsonrpc-stdio 与 transport=stdio。旧 MiniMax/OpenCode 直连路线废弃，不进入 AgentRun Queue 首版，也不作为 fallback 或 judge backend。

codex、deepseek 与 minimax-m3 之间不得隐式 fallback：缺少 deepseek 或 minimax-m3 SecretRef 时必须失败为 secret-unavailable，不能改用 codex Secret；任一 profile 运行失败也不能重试到另一个 profile。同一轮发布的综合联调必须证明 codex -> deepseek -> minimax-m3 -> codex 的切换不会污染彼此的 SecretRef、CODEX_HOME、模型或 upstream 配置。

内部架构

v0.1 的最小链路如下：

UniDesk or HWLAB client
-> agentrun-mgr REST API
-> durable run / command / event store
-> manual runner start
-> agentrun-runner
-> one backend adapter
-> normalized events / terminal status
-> agentrun-mgr

Runner inbound API 只允许本地或私有诊断，不作为业务客户端入口。业务客户端只能调用 agentrun-mgr。

并行开发边界

v0.1 默认会由多个 agent 并行实现 manager、runner、backend、Secret、Postgres、CLI 和 CI/CD。架构必须主动降低并行冲突，而不是把所有组件都写进同一个入口文件、总表或巨型测试文件。

并行开发的长期规则：

  • 组件实现按目录分层：manager 写入 src/mgr/**，runner 写入 src/runner/**，backend 写入 src/backend/**，CLI 写入 scripts/src/**，部署写入 deploy/**。跨组件共享类型和工具只放 src/common/**，且变更必须保持小而稳定。
  • 自测试采用可发现 case 模型：src/selftest/run.ts 只负责发现和调度，公共 fixture 放 src/selftest/harness.ts，组件测试放 src/selftest/cases/*.ts。新增组件自测试应优先新增 case 文件，不应反复修改总入口。
  • 长期文档状态归属到对应 spec：组件实现状态优先维护在 spec-v01-agentrun-mgr.md、spec-v01-agentrun-runner.md、spec-v01-backend-codex.md 等组件 spec 中；spec-v01-services.md 只保留总览和跨组件边界，避免成为并行改动热点。
  • 对并行冲突的处理优先优化模块边界：如果多个 PR 反复冲突在同一文件或同一段状态表，应拆出可独立追加的模块、case、manifest、helper 或 spec 子项；只有确认边界已经合理后，才做普通冲突解析。
  • 共享 API 合同要先稳定再并行扩展：RunRecord、CommandRecord、ExecutionPolicy、SecretRef、FailureKind 等跨组件类型改动必须兼顾 manager、runner、backend、CLI、self-test 和 GitOps render，不得为单个组件引入临时字段绕开合同。
  • 过程性合并、冲突解析和临时验证证据进入 PR/issue；长期参考文档只记录稳定的并行开发原则、边界和判断标准。

服务总表

对象 类型 v0.1 处理 说明 后续单独 spec
agentrun-mgr 长驻服务 保留，P0 公共 RESTful API、durable facts、idempotency、runner claim、event append 和 status authority。 spec-v01-agentrun-mgr.md
agentrun-runner 短生命周期执行入口 保留，P0 per-run/per-attempt executor；claim run、poll command、调用 backend、写回 events/status。 spec-v01-agentrun-runner.md
Backend adapter 执行适配层 保留，P0 统一 backend capability、event normalization、error mapping 和 credential boundary。 spec-v01-backend-adapter.md
Codex stdio backend profiles 具体 Agent backend 保留，P0 v0.1 使用一个真实 Codex app-server stdio backend kind，必须支持 codex、deepseek 与 minimax-m3 三个 profile；完整多 backend 路由仍 deferred。 spec-v01-backend-codex.md
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
Observability 最小事件/日志合同 保留，P1 子项 作为 manager/runner 的 event、terminal status、failureKind、logPath 和 redaction 最小合同，不拆独立观测系统。 并入 spec-v01-agentrun-mgr.md、spec-v01-agentrun-runner.md
agentrun-scheduler 长驻调度器 Deferred M1-M3 稳定后再实现自动 pending scan、capacity selection 和 runner Job 创建。 spec-v01-scheduler.md

v0.1.1 Session state 持久化

v0.1 的 P1 SessionRef 持久化 已从「metadata-only」升级为「per-session RWO PVC 直接挂载」：

  • agentrun-mgr：负责 session 创建时同步创建 PVC（POST /api/v1/sessions）、删 PVC（DELETE /api/v1/sessions/:id/storage）、runner 上报摘要（POST /api/v1/sessions/:id/storage/refresh）、GC 循环、运行前 PVC 存在性检查。
  • agentrun-runner：Job manifest 渲染 agentrun-sessions PVC volume，把 PVC 直接挂到 ${CODEX_HOME}/<codex_rollout_subdir>，env 透传 PVC name / namespace / mount path / codex rollout subdir。
  • codex-app-server-stdio backend：在 initialize 之后 emit codex-rollout-storage-mounted 事件；AGENTRUN_SESSION_PVC_NAME 已设 + thread/resume 返回 no rollout found 时升级为 session-store-evicted。
  • 接受方（HWLAB Cloud Web Workbench）：收到 session-store-evicted 时走 reset UX，不写入 fake 续接。

Manager SA RBAC 增量：persistentvolumeclaims: [create, get, list, watch, delete]。Runner SA 不需新增 PVC 相关权限（挂载走 Pod spec）。PVC storage class / size / 命名规则由 env 收敛（AGENTRUN_SESSION_STORAGE_CLASS、AGENTRUN_SESSION_STORAGE_SIZE）。

禁止路径：fake app-server mock 通过；强制重发同 sessionId 同 threadId 蒙混；thread/resume:no rollout found 改写为 thread/start + replacement threadId（PR #78 已否决）；idleTimeoutMs 拉成永驻当成本特性；runner Job 启动后再做 copy/restore（撤掉的路径，禁止复活）。 | AgentRun Queue | 系统能力 | 新增，P0 规格 | 直接吸收 UniDesk Code Queue 的队列能力；第一版只做 RESTful API、CLI 和轻量轮询，不做 Event/OA/integrations，不迁移历史数据。 | spec-v01-queue.md | | 多 backend 路由 | 系统能力 | Deferred | v0.1 不做跨 backend kind 的自动路由和调度；仅支持同一 Codex stdio backend kind 下的 codex/deepseek/minimax-m3 profile 手动选择。旧 MiniMax/OpenCode 直连路线不进入 Queue 首版。 | 后续版本 spec | | UI | 前端 | Deferred | v0.1 不要求独立 UI；UniDesk/HWLAB canary 可通过 CLI/API 验证。 | 后续版本 spec | | judge/retry 自动化 | 系统能力 | Deferred | v0.1 只定义基础 terminal 和 failure visibility，不实现复杂 judge。 | 后续版本 spec |

API 接口说明

Manager 公共 API 的 v0.1 初始范围：

POST /api/v1/runs
GET  /api/v1/runs/:runId
GET  /api/v1/runs/:runId/events?afterSeq=0&limit=100
POST /api/v1/runs/:runId/commands
GET  /api/v1/runs/:runId/commands/:commandId
POST /api/v1/runs/:runId/runner-jobs
GET  /api/v1/backends

Runner 到 manager 的私有 API 的 v0.1 初始范围：

POST  /api/v1/runners/register
POST  /api/v1/runs/:runId/claim
PATCH /api/v1/runs/:runId/lease
GET   /api/v1/runs/:runId/commands?afterSeq=0&limit=20
POST  /api/v1/runs/:runId/events
PATCH /api/v1/runs/:runId/status
POST  /api/v1/commands/:commandId/ack

v0.1 禁止用 SSE、WebSocket、long-polling 或长同步 turn 请求替代 durable resource 模型。客户端通过分页轮询观察进度。

Run Schema 和 Tenant 边界

v0.1 不实现复杂 tenant policy engine，但每个 run 必须显式承载租户边界字段，避免后续 UniDesk/HWLAB canary 接入时无法追责或隔离。

Run create 的最小字段合同：

字段 v0.1 规则
tenantId 必填，例如 unidesk、hwlab；只做 allowlist/schema 校验。
projectId 必填，例如 pikasTech/unidesk、pikasTech/HWLAB。
workspaceRef 必填，描述 source/worktree/workspace，不由 runner 猜测。
providerId 必填，例如 G14、D601；只表示目标 provider，不直接授予权限。
backendProfile 必填，v0.1 allowlist 为 codex、deepseek 与 minimax-m3；三者共享 codex-app-server-stdio backend kind。
executionPolicy 必填或由 manager 显式写入默认值，至少包含 sandbox、approval、timeout、network 和 secret scope。
traceSink 字段必须存在；可以为 null 或显式 sink，表示标准事件是否需要镜像给 tenant。

Manager 负责校验、保存和返回这些字段；runner 只能消费已保存的 run policy，不能自行扩大 workspace、network 或 secret scope。executionPolicy.secretScope 只能引用装配 SPEC 和 spec-v01-secret-distribution.md 定义的 SecretRef 或 credential source，不能携带 provider/tool credential 明文。HWLAB live device mutation、UniDesk production deploy、GitHub issue/PR 写入等业务授权仍由 tenant 自己的入口判定，AgentRun 不把这些业务规则内建成通用门禁。

最小 Observability 合同

v0.1 不拆出独立观测规格文件，也不建设通用日志平台。可观察性只作为 run 生命周期的一部分：

  • events 必须 append-only，并按 seq 分页读取。
  • 每个 run 必须最终写出 terminal_status 或明确的 non-terminal status。
  • runner 启动失败、backend 失败、policy/schema 失败必须写入结构化 failureKind。
  • CLI 启动本地 process 或 Kubernetes Job 时必须返回 logPath 或 Kubernetes job/pod identity。
  • event 和日志不得打印 Secret/token 值；只能记录 SecretRef、credential source 或 redacted marker。
  • redaction 规则只覆盖明显 credential、token、Authorization header 和 URL credential；复杂审计、集中 trace、metrics dashboard 推迟到后续版本。

MVP 分期

阶段 目标 验收重点
M0 契约骨架 Run/Command/Event/Runner/Backend 资源模型和状态机可读。
M1 最小 runner + 一个 backend 一个 turn 经过真实 backend，assistant/output/error/terminal events 被归一化。
M2 manager + runner claim run create/query durable，claim 拒绝双 owner，events append-only。
M3 手动 dispatch CLI CLI 快速返回 runner process/job identity、log path 和轮询命令。
M4 HWLAB 手动调度 canary HWLAB 通过 REST API 显式启动 runner Job，并能轮询 result/trace 到终态。
M5 自动 scheduler Deferred；pending 自动派发、capacity selection 和 stale lease recovery 进入后续实现。

测试规格

T1 最小 Run 生命周期

阅读 AGENTS.md、本文和 spec-v01-cicd.md，然后使用 AgentRun CLI 手动测试创建 run、为该 run 启动 runner、轮询 events 并观察 terminal status。确认每个 CLI 命令都返回 JSON，包含 id 和后续命令，并且不会在单个请求中等待完整模型 turn。

T2 Command 与 Event 轮询

阅读 AGENTS.md、本文和 spec-v01-cicd.md，然后创建 run command，并轮询 command status 与 run events。确认 command state 可见，event pagination 使用 afterSeq，重复轮询不会产生重复 event。

T3 日志与失败可见性

阅读 AGENTS.md、本文和 spec-v01-cicd.md，然后用一个故意无效的 backend profile 启动本地服务或 runner。确认 CLI 返回结构化失败，输出 log path，并且日志文件包含足够定位失败原因的信息。

规格的实现情况

规格项 状态 说明
v0.1 服务总体规格 已定义 本文定义服务总览和取舍表。
文档治理规格 已定义 见 spec-v01-documentation-governance.md。
CI/CD lane 规格 已定义 见 spec-v01-cicd.md。
Postgres durable store 规格 已定义 见 spec-v01-postgres.md。
Secret 分发规格 已定义 见 spec-v01-secret-distribution.md。
RuntimeAssembly 规格 已定义 见 spec-v01-runtime-assembly.md。
AgentRun Queue 规格 已定义 见 spec-v01-queue.md。
HWLAB 手动调度接入规格 已定义 见 spec-v01-hwlab-manual-dispatch.md。
两层验证规格 已定义 见 spec-v01-validation.md。
agentrun-mgr 服务规格 已定义 见 spec-v01-agentrun-mgr.md。
agentrun-runner 服务规格 已定义 见 spec-v01-agentrun-runner.md。
Backend adapter 规格 已定义 见 spec-v01-backend-adapter.md。
Codex backend 规格 已定义 见 spec-v01-backend-codex.md。
AgentRun CLI 规格 已定义 见 spec-v01-cli.md。
Scheduler deferred 规格 已定义 见 spec-v01-scheduler.md。
agentrun-mgr 实现 已实现/已通过主闭环 已有 REST API、Postgres durable store、migration ledger、runner claim/lease/report、health/readiness 和 self-test memory 模式；真实 agentrun-v01 runtime 已通过 Postgres/GitOps/readiness 和 run lifecycle 主闭环。
agentrun-runner 实现 已实现/已通过主闭环 host process runner 与 Kubernetes Job 共用 runOnce，runner 通过 manager API claim/poll/report，不直连 Postgres；真实 Kubernetes Job 已完成 Codex turn。
codex profile 已实现/已通过主闭环 Codex app-server stdio backend 已有协议、失败分类、脱敏和 fake self-test；真实 Codex provider turn 已通过 RESTful API 与 CLI 主闭环。
deepseek profile 已实现/已通过主闭环 DeepSeek 已作为同一 Codex stdio backend kind 的 profile/config/SecretRef 选择进入 v0.1；自测试覆盖 registry、runner Secret 选择、fake stdio turn 和无 fallback，真实 agentrun-v01 已通过 codex -> deepseek -> codex 切换联调。
minimax-m3 profile 已实现/待真实主闭环 MiniMax-M3 已作为同一 Codex stdio backend kind 的 profile/config/SecretRef 选择进入 v0.1；自测试覆盖 registry、runner Secret 选择、fake stdio turn 和无 fallback，真实 agentrun-v01 仍需用 AgentRun CLI 手动验收。
自动 scheduler Deferred 不作为 v0.1 第一阶段验收目标。
Reference in New Issue View Git Blame Copy Permalink