diff --git a/AGENTS.md b/AGENTS.md index 36e5592..f8d2bd6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 权威和过程材料承载规则。 diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index 93085ba..aca9cfd 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -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 diff --git a/docs/reference/spec-v01-agentrun-mgr.md b/docs/reference/spec-v01-agentrun-mgr.md index cd7ed16..b99c65a 100644 --- a/docs/reference/spec-v01-agentrun-mgr.md +++ b/docs/reference/spec-v01-agentrun-mgr.md @@ -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 或内存状态只能用于自测试。 diff --git a/docs/reference/spec-v01-agentrun-runner.md b/docs/reference/spec-v01-agentrun-runner.md index f5be9b1..7db51bc 100644 --- a/docs/reference/spec-v01-agentrun-runner.md +++ b/docs/reference/spec-v01-agentrun-runner.md @@ -15,6 +15,8 @@ `v0.1` 默认 runner 形态是 `agentrun-v01` namespace 中的短生命周期 Job，Job 名称建议使用 `agentrun-v01-runner--`。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。 diff --git a/docs/reference/spec-v01-backend-adapter.md b/docs/reference/spec-v01-backend-adapter.md index 05b4b66..b43ae62 100644 --- a/docs/reference/spec-v01-backend-adapter.md +++ b/docs/reference/spec-v01-backend-adapter.md @@ -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 类型至少包括： diff --git a/docs/reference/spec-v01-backend-codex.md b/docs/reference/spec-v01-backend-codex.md index 6477f80..a883064 100644 --- a/docs/reference/spec-v01-backend-codex.md +++ b/docs/reference/spec-v01-backend-codex.md @@ -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 环境中的以下两个文件： diff --git a/docs/reference/spec-v01-cicd.md b/docs/reference/spec-v01-cicd.md index 73b7f93..5b6632d 100644 --- a/docs/reference/spec-v01-cicd.md +++ b/docs/reference/spec-v01-cicd.md @@ -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` 发布真相按以下顺序判断： diff --git a/docs/reference/spec-v01-cli.md b/docs/reference/spec-v01-cli.md index 02bfd98..dd7b468 100644 --- a/docs/reference/spec-v01-cli.md +++ b/docs/reference/spec-v01-cli.md @@ -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 后续命令观察。 ## 初始命令族 diff --git a/docs/reference/spec-v01-services.md b/docs/reference/spec-v01-services.md index 048f56b..9afd9dd 100644 --- a/docs/reference/spec-v01-services.md +++ b/docs/reference/spec-v01-services.md @@ -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` 的最小链路如下： diff --git a/docs/reference/spec-v01-validation.md b/docs/reference/spec-v01-validation.md index a134560..7624b09 100644 --- a/docs/reference/spec-v01-validation.md +++ b/docs/reference/spec-v01-validation.md @@ -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。