docs: fix v0.1 implementation stack

2026-05-29 10:35:33 +08:00
parent f896439940
commit 4b33e67484
10 changed files with 70 additions and 6 deletions
@@ -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` 的最小链路如下：