docs: fix v0.1 implementation stack
This commit is contained in:
Codex
@@ -39,6 +39,12 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓
|
||||
- P0: AgentRun CLI 和服务开发必须遵循 UniDesk `cli-spec` 原则：默认 JSON 输出、禁止空输出伪成功、禁止长阻塞 CLI、日志可见、配置显式校验、稳定跨服务边界优先使用 RESTful API。
|
||||
- P0: 一旦新增 CLI，入口文件必须保持轻量，具体实现拆入 `scripts/src/`；长任务必须快速返回，并提供 status/log/event 轮询。
|
||||
|
||||
## Critical v0.1 Implementation Stack Rule
|
||||
|
||||
- P0: AgentRun `v0.1` 自研 runtime、CLI、manager、runner、backend adapter、Codex backend 和后续 scheduler 的优先实现语言是 Bun + TypeScript；官方 CLI 入口是 `bun scripts/agentrun-cli.ts`，复杂逻辑拆入 `scripts/src/` 和 `src/`。
|
||||
- P0: `backendProfile=codex` 必须通过 Codex CLI app-server stdio 协议执行，启动受控 `codex app-server --listen stdio://`，使用 JSON-RPC 方法 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`；不得在 `v0.1` 把 Codex backend 实现为直接 Responses HTTP 代理、文本 fallback 或 fake provider。
|
||||
- P0: 实现 Codex backend 前必须参考 UniDesk Code Queue 的 `src/components/microservices/code-queue/src/code-agent/codex.ts`、`common.ts`，以及 HWLAB 的 `internal/cloud/codex-stdio-session.mjs`、`scripts/code-agent-chat-smoke.mjs`；复用协议、redaction、trace、failure 分类和 Secret projection 经验，不复制环境专用路径或明文密钥。
|
||||
|
||||
## 长期参考文档
|
||||
|
||||
- `docs/reference/spec-v01-documentation-governance.md`：v0.1 文档治理、唯一入口、spec 权威和过程材料承载规则。
|
||||
|
||||
@@ -47,6 +47,14 @@ Manager 是稳定 API 和审计点。Runner 是执行者，不应成为业务客
|
||||
|
||||
Backend adapter 隐藏具体工具协议。Codex stdio JSON-RPC、OpenCode JSON events、Claude Code、host-native process 和 Windows-native execution 可以使用不同内部协议，但 AgentRun 公共 API 必须保持稳定且与 backend 无关。
|
||||
|
||||
## v0.1 实现技术栈
|
||||
|
||||
AgentRun `v0.1` 自研 runtime 优先使用 Bun + TypeScript：manager、runner、backend adapter、Codex backend、CLI 和后续 scheduler 都按这一技术栈实现。`scripts/agentrun-cli.ts` 是官方 CLI 入口；复杂 CLI 逻辑进入 `scripts/src/`，服务和 runner 逻辑进入 `src/`。YAML manifest、Tekton/Argo CD 配置、Postgres 和 Kubernetes 仍按各自原生生态管理。
|
||||
|
||||
Codex backend 固定采用 Codex CLI app-server JSON-RPC over stdio。实现必须启动受控 `codex app-server --listen stdio://`，执行 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`，并把 stdout/stderr、notification、tool lifecycle、assistant output 和 terminal/error 状态归一化为 AgentRun events。直接 Responses HTTP、OpenAI SDK wrapper、`codex exec` 一次性输出或文本 fallback 不能作为 `v0.1` Codex backend 的正式执行路径。
|
||||
|
||||
实现参考优先级：UniDesk Code Queue 的 `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`。AgentRun 复用其协议、trace、redaction、Secret projection 和 failure 分类经验，但不复制 tenant 业务规则、环境专用路径或密钥材料。
|
||||
|
||||
## MVP 顺序
|
||||
|
||||
AgentRun 必须按纵向切片推进，不要一开始大规模并行开发。
|
||||
@@ -74,7 +82,7 @@ AgentRun 必须按纵向切片推进，不要一开始大规模并行开发。
|
||||
- terminal status 被写出；
|
||||
- interrupt 至少有 durable cancellation 路径，backend 支持时再传播到真实进程中断。
|
||||
|
||||
第一个 backend 应选择能证明真实 Agent 原语的最窄实现。如果 Codex 摩擦过大，可以短暂用 controlled process backend 证明 contract shape，但 MVP 必须尽快回到一个真实 Agent backend，否则不能认为上层已验证。
|
||||
第一个 backend 固定选择 Codex app-server stdio，用最窄实现证明真实 Agent 原语。如果 Codex 上游或凭据短暂不可用，可以用 controlled process 或 fake app-server 做自测试，但不能替代综合联调，也不能据此宣称 `v0.1` backend 通过。
|
||||
|
||||
### M2: Manager 加 Runner Claim
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
|
||||
## 内部架构
|
||||
|
||||
`agentrun-mgr` 运行在 `agentrun-v01` namespace，长驻 Deployment/Service 名称使用 `agentrun-mgr`。服务实现可以按语言和框架演进，但必须保持以下边界：
|
||||
`agentrun-mgr` 运行在 `agentrun-v01` namespace，长驻 Deployment/Service 名称使用 `agentrun-mgr`。`v0.1` 自研服务实现优先使用 Bun + TypeScript；具体 HTTP 框架不是规格边界，但源码必须保持可被 Bun 运行、测试和打包。服务必须保持以下边界：
|
||||
|
||||
- HTTP JSON API 是稳定跨服务边界；不使用 SSE、WebSocket、long-polling 或长同步 `turn` 请求作为 `v0.1` 必备能力。
|
||||
- Postgres adapter 是唯一 durable store adapter；file、sqlite、JSONL 或内存状态只能用于自测试。
|
||||
|
||||
@@ -15,6 +15,8 @@
|
||||
|
||||
`v0.1` 默认 runner 形态是 `agentrun-v01` namespace 中的短生命周期 Job，Job 名称建议使用 `agentrun-v01-runner-<runId>-<attempt>`。MVP 允许 CLI 启动受控本地 process，但该 process 仍必须通过 manager API claim/report。
|
||||
|
||||
Runner 自研代码优先使用 Bun + TypeScript。Kubernetes Job 和 CLI 启动的 host process 必须进入同一套 TS runner 模块，避免一套 Job 逻辑和一套本地调试逻辑分叉；容器镜像可以直接运行 TS 入口或运行由同一源码构建出的 JS artifact。
|
||||
|
||||
Runner 启动参数必须显式包含：
|
||||
|
||||
- manager API base URL。
|
||||
|
||||
@@ -13,7 +13,7 @@ Backend adapter 是 runner 与具体 Code Agent 工具之间的适配层。它
|
||||
|
||||
## Adapter 合同
|
||||
|
||||
第一版可以把 adapter 实现为 runner 进程内模块，不要求独立 Deployment。无论实现形态如何，对 runner 的逻辑合同必须稳定：
|
||||
第一版可以把 adapter 实现为 runner 进程内 Bun/TypeScript 模块，不要求独立 Deployment。无论实现形态如何，对 runner 的逻辑合同必须稳定：
|
||||
|
||||
```text
|
||||
resolveProfile(profile) -> capability
|
||||
@@ -26,6 +26,8 @@ redact(value) -> redacted value
|
||||
|
||||
Adapter 输入必须来自 manager 保存的 run/command 和 Kubernetes Secret projection；不得从 CLI 参数、临时环境变量或 Git 文件读取 provider credential 明文。
|
||||
|
||||
`v0.1` 的第一真实 adapter 是 Codex adapter。它必须走 Codex CLI app-server JSON-RPC over stdio；adapter 合同把 Codex 的 thread、turn、notification、tool lifecycle 和 stderr/exit 信息归一化为 AgentRun 标准 events。
|
||||
|
||||
## 标准事件
|
||||
|
||||
Adapter 输出给 runner 的 event 类型至少包括：
|
||||
|
||||
@@ -10,6 +10,29 @@ Codex backend 是 AgentRun `v0.1` 的第一真实 Code Agent backend 候选。
|
||||
- 把 Codex 输出归一化为 AgentRun 标准 events 和 terminal status。
|
||||
- 将 provider/auth/protocol/timeout/cancel 错误映射为 [spec-v01-backend-adapter.md](spec-v01-backend-adapter.md) 定义的 failureKind。
|
||||
|
||||
## 协议选型与实现参考
|
||||
|
||||
`v0.1` Codex backend 的协议固定为 Codex CLI app-server JSON-RPC over stdio。Backend adapter 必须启动受控子进程：
|
||||
|
||||
```bash
|
||||
codex app-server --listen stdio://
|
||||
```
|
||||
|
||||
Adapter 通过 stdin 写入换行分隔 JSON-RPC 请求，通过 stdout 逐行读取 JSON-RPC response 和 notification，stderr 只作为有界诊断日志。最小请求序列是 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`；response 中必须提取 thread/turn identity，notification 和后续输出必须归一化为 `backend_status`、`assistant_message`、`tool_call`、`command_output`、`error` 和 `terminal_status` events。
|
||||
|
||||
不得把以下路径作为 `v0.1` Codex backend 的正式实现或综合联调通过证据：直接 Responses HTTP 代理、OpenAI SDK wrapper、`codex exec` 一次性命令输出、fake provider、固定文本回复、只读 shortcut 或本地 shell 模拟。裸 HTTP 或 `codex exec --json` 可以作为 provider/upstream 诊断，但最终通过必须来自 app-server stdio turn。
|
||||
|
||||
实现必须参考成熟代码：
|
||||
|
||||
| 参考 | 需要吸收的经验 |
|
||||
| --- | --- |
|
||||
| UniDesk `src/components/microservices/code-queue/src/code-agent/codex.ts` | Bun/TS 中 spawn `codex app-server --listen stdio://`、JSON-RPC request/response、thread start/resume、turn start、stderr 有界采集、exit/failure 分类。 |
|
||||
| UniDesk `src/components/microservices/code-queue/src/code-agent/common.ts` | backend port/capability、model/profile 边界、文本 input shape、Git/proxy env 处理和 provider 端口归一化。 |
|
||||
| HWLAB `internal/cloud/codex-stdio-session.mjs` | long-lived stdio session readiness、Codex home/workspace/protocol gate、child env redaction、trace recorder、cancel/timeout/failure kind。 |
|
||||
| HWLAB `scripts/code-agent-chat-smoke.mjs` | fake app-server 自测试方式、`thread/start` + `turn/start` 调用顺序、session reuse、tool trace 和 Secret 不泄露断言。 |
|
||||
|
||||
这些参考用于协议和质量标准，不复制 UniDesk/HWLAB 的业务 prompt、硬件路径、tenant policy、hostPath Secret 做法或任何明文密钥。
|
||||
|
||||
## 测试凭据来源
|
||||
|
||||
`v0.1` 综合联调用的 Codex 测试凭据源固定为 operator 环境中的以下两个文件：
|
||||
|
||||
@@ -32,6 +32,19 @@
|
||||
|
||||
公网入口暂不作为 `v0.1` 必备规格。若后续需要 UniDesk/HWLAB 跨服务入口，必须在本仓库新增受审查的 ingress/FRP/edge spec，不得临时固化 NodePort、host port、pod IP 或一次性 port-forward。
|
||||
|
||||
## Bun + TypeScript CI 边界
|
||||
|
||||
`v0.1` 自研代码的 CI/CD 工具链以 Bun + TypeScript 为准。Tekton task 必须在受控容器内安装或使用固定 Bun 运行时，执行依赖安装、类型检查、自测试和镜像构建；不得把 master server、G14 固定 source workspace 或手工 host shell 作为构建机。
|
||||
|
||||
CI 的最小检查应覆盖：
|
||||
|
||||
- `bun install` 或等价 frozen lockfile 安装。
|
||||
- TypeScript 类型检查。
|
||||
- Bun/TS 单元自测试，包括 manager schema、adapter mock、Codex fake app-server stdio client 和 CLI JSON 输出。
|
||||
- `deploy/deploy.json` 与 GitOps render 只读校验。
|
||||
|
||||
容器镜像可以直接运行 TS 入口，也可以运行同一 source commit 构建出的 JS artifact；无论选择哪种形式，artifact catalog 必须记录完整 source commit 和 image digest。CI/CD 仍然只允许纯 Tekton + Argo CD，不因 Bun 工具链引入自定义 runner、长期 poller 或源分支生成物提交。
|
||||
|
||||
## 真相源
|
||||
|
||||
`v0.1` 发布真相按以下顺序判断：
|
||||
|
||||
@@ -19,7 +19,7 @@ scripts/agentrun-cli.ts
|
||||
scripts/src/*.ts
|
||||
```
|
||||
|
||||
入口文件只负责参数解析和路由，具体实现拆到 `scripts/src/`。CLI 命令默认输出 JSON；任何命令无 stdout 都是失败。单次 CLI 调用必须在 60 秒内返回，长时间模型 turn 通过 status/events 后续命令观察。
|
||||
CLI 官方运行方式固定为 Bun + TypeScript：`bun scripts/agentrun-cli.ts ...`。`node`、`tsx` 或 shell wrapper 只能作为本地开发辅助，不能成为 `v0.1` 用户文档、CI/CD 或综合联调的权威入口。入口文件只负责参数解析和路由，具体实现拆到 `scripts/src/`。CLI 命令默认输出 JSON；任何命令无 stdout 都是失败。单次 CLI 调用必须在 60 秒内返回，长时间模型 turn 通过 status/events 后续命令观察。
|
||||
|
||||
## 初始命令族
|
||||
|
||||
|
||||
@@ -14,6 +14,14 @@ AgentRun 是面向 UniDesk 与 HWLAB 的共享 Code Agent 执行基础设施。`
|
||||
- AgentRun CLI 是受控操作入口，负责创建 run、提交 command、轮询 events、手动启动 runner 和查看 backend capability；CLI 不等待完整模型 turn。
|
||||
- Scheduler 是后续自动派发能力；`v0.1` 可以保留规格和状态字段，但不把自动调度作为第一阶段验收目标。
|
||||
|
||||
## 语言与协议选型
|
||||
|
||||
AgentRun `v0.1` 的自研组件优先使用 Bun + TypeScript 实现：`agentrun-mgr`、`agentrun-runner`、backend adapter、Codex backend、AgentRun CLI 和后续 scheduler 都属于该边界。官方 CLI 入口固定为 `bun scripts/agentrun-cli.ts`，入口只做参数解析和路由，复杂逻辑拆到 `scripts/src/` 与 `src/`。Postgres、Kubernetes、Tekton、Argo CD、YAML manifest 和 shell 级容器启动命令属于外部运行面或部署面，不受“必须 TypeScript 实现”的约束。
|
||||
|
||||
`backendProfile=codex` 的 `v0.1` 协议固定为 Codex CLI app-server JSON-RPC over stdio：runner/backend adapter 启动受控 `codex app-server --listen stdio://` 子进程，经 stdin/stdout 发送换行分隔 JSON-RPC，请求顺序至少覆盖 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`。直接调用 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`。AgentRun 复用的是 stdio JSON-RPC、session/turn 生命周期、trace、redaction、Secret projection 和 failureKind 经验，不复制 UniDesk/HWLAB 的环境专用路径、业务 prompt 或明文凭据。
|
||||
|
||||
## 内部架构
|
||||
|
||||
`v0.1` 的最小链路如下：
|
||||
|
||||
@@ -24,6 +24,8 @@
|
||||
- Postgres adapter：migration、事务、run/command/event round-trip、重启后可查询。
|
||||
- Secret 分发：SecretRef schema、missing secret failure、redaction。
|
||||
|
||||
自测试应使用 Bun + TypeScript 运行，Codex 相关自测试可以使用 fake app-server JSON-RPC client 模拟 `initialize`、`thread/start`、`thread/resume`、`turn/start`、assistant 输出、协议错误、timeout 和 transport close。
|
||||
|
||||
自测试输出可以是 Tekton TaskRun result、JUnit、tap、JSON summary 或普通日志，但不得回写 source branch，也不得伪装成综合联调通过。
|
||||
|
||||
## 综合联调
|
||||
@@ -39,7 +41,7 @@
|
||||
- 真实 `agentrun-v01-postgres` StatefulSet、PVC、Service 和 migration ledger。
|
||||
- 真实 Kubernetes SecretRef 注入 Postgres DSN 和 Code Agent provider credential；Codex 测试凭据必须来自 `~/.codex/auth.json` 与 `~/.codex/config.toml` 的 Kubernetes Secret projection。
|
||||
- 真实 `agentrun-mgr`、runner Job 或受控 runner process、真实 backend adapter。
|
||||
- 至少一个真实 Code Agent provider turn；如果 provider credential SecretRef 缺失，综合联调必须标记 blocked，不能降级为 mock pass。
|
||||
- 至少一个真实 Code Agent provider turn；Codex backend 必须通过 `codex app-server --listen stdio://` 的 JSON-RPC stdio turn 完成，mock、fixture、source-only、dry-run、fake provider、直接 Responses HTTP 或 `codex exec` 一次性输出不能作为通过证据。如果 provider credential SecretRef 缺失，综合联调必须标记 blocked，不能降级为 mock pass。
|
||||
|
||||
综合联调最小闭环：
|
||||
|
||||
@@ -58,7 +60,7 @@ CLI 交互联调验证正式操作入口是否能支撑人工使用和自动脚
|
||||
|
||||
CLI 交互联调必须满足：
|
||||
|
||||
- 使用 `bun scripts/agentrun-cli.ts` 或后续固定 CLI 入口完成 create run、create command、start runner、show command 和 events polling。
|
||||
- 使用 `bun scripts/agentrun-cli.ts` 完成 create run、create command、start runner、show command 和 events polling。
|
||||
- 每个 CLI 调用默认输出 JSON，stdout 不为空，且 60 秒内返回；长时间模型 turn 必须通过后续 status/events 命令观察。
|
||||
- 创建类命令必须返回 `runId`、`commandId`、status、job/process identity、logPath 和下一步 poll command；查询类命令必须返回当前 state、terminal_status、failureKind 和 event cursor。
|
||||
- CLI 输出、日志摘要和错误信息必须保留可观测性，不能只返回成功/失败布尔值；错误必须能区分 missing SecretRef、provider auth failure、runner lease conflict、backend failure 和 infra failure。
|
||||
|
||||
Reference in New Issue
Block a user