Merge pull request #131 from openqj/feat-readme-update

docs: README 对齐生产现状（main 93c25a9，补 PR #130 自适应分栏）
2026-10-29 10:48:52 +08:00
commit e7f7edf5c2
@@ -1,14 +1,65 @@
-# Codex app-server（无 GUI 版，照搬开源核心）
+# Codex app-server（无 GUI 版，照搬开源核心 + 自建云端控制面）

-目标：不做桌面 UI、不重写 agent 循环，把 Codex 开源能给到的全部
-原样接过来，做成一个可以被任何客户端（pi agent、你自己的 App、
-脚本）调用的 app-server。
+目标分两层，不要混成一层：
+
+1. **不重写 agent 循环**：把 Codex 开源能给到的全部原样接过来，
+   做成一个可以被任何客户端（pi agent、你自己的 App、脚本）
+   调用的 app-server。
+2. **自建控制面**：在官方 agent 之上加一层常驻服务——项目、
+   任务队列、worker 池、评审与合并、权限与配额、成本与记忆、
+   网页命令台——让多任务、多用户、远程派发能真正跑起来，
+   而不是只停在本地单机演示。
+
+## 项目现状（2026-10-29，main `93c25a9`，PR #130 已合并部署）
+
+旧版 README 只写到本地 host 层，云端还写着“演示、不是真实
+云服务”——那句话已经过期。本轮更新以生产现状为准：
+
+- **生产已上线**：控制面跑在常驻主机上，Postgres 为后端，
+  公网入口 `https://api.diante.me`，命令台
+  `https://api.diante.me/console`（`GET /health` 可查
+  `backend=postgres`、`worker_ok` 与当前 commit）。
+- **命令台是 React 版**：源码在 `cloud/console-react/`（Vite +
+  React 19 + TypeScript），构建产物是单文件 `cloud/console.html`，
+  只改 `src` 再 `npm run build:console`，产物绝不手改。
+  当前视觉是一页式 GitHub 风格（PR #129）+ 按宽度自适应分栏
+  （PR #130）：细顶栏 + 6 张数据卡片 + 派发、任务、对话、项目、
+  环境、Workers、技能、自动化、分诊、管理区、API Key 全部铺在
+  一页；窄屏 <900px 一栏堆叠，中屏 900–1399px 两栏（左：任务
+  列表 + 项目，右：其余），宽屏 ≥1400px 三栏（左 310px、中弹性、
+  右 330px），页面最大宽 1560px，盒子按内容高度不拉伸。
+  此前 Muse 风格四栏固定布局已被它取代，不要再按旧截图改。
+- **执行层是 Docker + gVisor**：生产任务走 Docker 执行器，
+  生产 autoscaler 起的 worker 带 `--docker-runtime runsc`；内层 codex 沙箱在生产容器里仍是
+  `danger-full-access`（见下“诚实边界”），隔离靠外层容器 +
+  租户目录 + egress 白名单，不是双层沙箱。
+- **模型走中转网关**：生产默认模型已改为 `gpt-5.6-terra`
+  （原 `gpt-6.1-sol` 在 2026-10-27 实测持续 503；
+  价目表与 `/models` 优先级列表未动，terra 成本进 unpriced）。
+  系统 key 与中转站是设计本身，不做 OpenAI 官方账号对接，
+  也不做 per-user 中转 key。
+- **已落地的控制面能力**：OAuth 真实登录（GitHub/Google）、
+  项目 RBAC 与 API key 管理、任务队列与 worker 心跳、自动扩容
+  （协调员保护）、租户配额与 USD 上限、成本统计、自动记忆、
+  网页搜索 MCP（SearXNG 路）、任务继续消息持久化、子任务
+  默认模型/强度、计划模式、followup 与 fork、评审队列与
+  PR/CI 门。细节与 API 见 `cloud/README.md` 与 `docs/`。
+- **仍未证明 / 暂搁置的**：40 人并行（2026-10-29 用户令先绕过，
+  串行分波次或 18 人规模代替，40 人仍记未证明）；第二台主机的
+  真跨机 HA（现有 HA 验证是同主机双进程模拟）；G10 断点
+  provider 修法只在 PR #127，未合并、未部署。

 ## 一句话架构

 ```
-你的客户端 / pi agent
-      │  stdio JSON-RPC（或 unix / ws，见 start.sh）
+浏览器 / 客户端 / GitHub webhook
+      │  HTTPS + X-API-Key（OAuth 登录、webhook 靠签名）
+      ▼
+cloud/server.py（控制面，默认 127.0.0.1:8765，生产经 nginx + TLS）
+      │  项目 / 任务 / 队列 / 权限 / 配额 / 成本 / 记忆 / 评审
+      ▼
+cloud/worker.py + autoscaler（worker 池，local / docker 执行器）
+      │  调 host.py：dispatch / run / goal / review / merge
      ▼
 client.py ──► codex app-server（官方二进制，codex-core 原样）
      │  thread/start · turn/start · 事件流 · 审批请求
@@ -16,12 +67,12 @@ client.py ──► codex app-server（官方二进制，codex-core 原样）
 agent 循环 + 沙箱 + 工具 + MCP + skills + 线程持久化
 ```

-本仓库自己写的只有宿主层：`client.py`（协议客户端）、
-`run_parallel.py`（多 thread 编排）、`start.sh`、`config.example.toml`。
+本仓库自己写的有三层：`client.py`（协议客户端）、`host.py`
+（本地宿主编排）、`cloud/`（云端控制面 + worker + 命令台）。
 agent 循环、沙箱、工具执行、上下文压缩、线程存储，全部是官方
 codex 二进制里的，不是我复刻的简化版。

-实测版本：本机 `codex-cli 0.164.0-alpha.9`，协议定义就是从它
+实测版本：`codex-cli 0.164.0-alpha.9`，协议定义就是从它
 导出的，见 `protocol/`。

 ## 目录
@@ -29,6 +80,21 @@ codex 二进制里的，不是我复刻的简化版。
 - `start.sh`：启动官方 app-server，支持 stdio / unix / ws 三种传输。
 - `client.py`：零依赖 Python 客户端，演示完整链路。
 - `run_parallel.py`：宿主层多 agent 编排（见下文“子代理”）。
+- `host.py`：本地宿主编排（dispatch / review / merge / goal /
+  automations / daemon / health，见下文“宿主编排”）。
+- `cloud/`：云端控制面（`server.py` 控制面、`worker.py` worker、
+  `autoscaler.py` 自动扩容、`console.html` 命令台产物、
+  `console-react/` 命令台源码、`sub2api.py` 中转网关、
+  `websearch_mcp.py` 网页搜索 MCP、`db.py` SQLite/Postgres
+  双后端）。控制面本身零第三方依赖，只用 Python 标准库。
+- `cloud/console-react/`：命令台源码。改页面只改 `src`，
+  再 `npm run build:console` 生成 `cloud/console.html`。
+- `deploy/`：主机部署与运维脚本（`deploy.py` + `host_deploy.sh`，
+  tar 与 git 直拉两种模式；`deploy/README.md` 为准）。
+- `docs/`：架构与专题文档（云端架构、自动记忆、网页搜索 MCP、
+  线程生命周期等）。`cloud/README.md` 里仍写着“本地演示、
+  不是真实云服务”的旧诚实边界已过期，以本 README 顶部的
+  生产现状为准。
 - `config.example.toml`：沙箱、审批、MCP、features 的配置示例。
 - `protocol/`：`codex app-server generate-json-schema` 原样导出的
  协议 schema（v1 + v2），客户端的方法名和字段以它为准。
@@ -121,6 +187,58 @@ python3 run_parallel.py --jobs examples/jobs.json
 事后逐个 review diff 再合并，冲突仍需人工处理——
 core 里没有自动解决冲突的调度器。

+## 云端控制面（cloud/，生产已跑，不再是演示）
+
+本地 `host.py` 只管一台机器上的任务；多用户、远程派发、
+排队、配额、评审门要靠 `cloud/`。它不是 host.py 的包装，
+而是控制面只负责“谁可以派、派给谁、状态在哪、结果通知谁”，
+执行仍走 worker 调 `host.py`，agent 逻辑不重写。
+
+```bash
+python3 -m cloud.server          # 默认 127.0.0.1:8765，生产经 nginx + TLS 对外
+# 除 GET /health、/webhooks/*、/oauth/* 外，所有端点都要 X-API-Key 请求头
+# 任务实时链路：GET /tasks/{id}/trace（快照）与 GET /tasks/{id}/trace/stream（SSE）
+# 命令台：GET /console（每次现读 cloud/console.html，无需重启）
+```
+
+- **任务状态机**：`queued → running → completed / failed /
+  interrupted / merged / merge-failed`；`merged` 只由
+  `POST /tasks/{id}/merge` 同步状态，不执行合并本身（合并仍由
+  host.py merge 执行，成功后再调本接口；仅 completed 可改
+  merged，重复调用 409，越权 403）。
+- **worker 与扩容**：worker 心跳注册（`POST /workers/heartbeat`），
+  autoscaler 按队列扩缩；2026-10-29 已修协调员槽位泄漏
+  （PR #118：协调员完成不清 `_running` 曾导致容量门静默拦单，
+  40 人轮与 18 人轮的“认领停滞”都是它）与缩容误杀协调员
+  （PR #117）。长 goal 任务异常退出不再一律判 failed，
+  无结论的非 0 退出记 interrupted，断点在盘上可 `goal-resume` 续跑。
+- **权限、配额、成本**：项目 RBAC、API key 只存 sha256 哈希
+  （明文只返回一次）、租户月度 USD 上限与建任务/分支/重试
+  准入、按任务与按项目/按日的成本（实际与估算分开）、
+  每 key 每分钟限流（环境变量可调，窗口与上限见部署 env，
+  不要把生产调的值当成代码默认值写进文档）。
+- **记忆与搜索**：跨线程记忆与项目 KB（按项目隔离）、自动记忆
+  （生产默认账号已开，worker 每轮读库）、网页搜索 MCP
+  （Perplexity → Exa → Tavily → Brave → SearXNG → DuckDuckGo
+  自动回退；Docker 任务容器不继承 worker 环境，搜索 env 须经
+  worker 的 extra_env 透传，见 PR #114）。
+- **继续、计划、followup、fork**：继续消息已持久化进会话历史
+  （PR #126，此前失败任务只落任务记录、不进历史，网页重载后
+  看不到助手回复）；建任务可带 `plan`（只读沙箱，不能与
+  `approval=full` 或 goal 同用）；`POST /tasks/{id}/followups`
+  （queued 排队不打断当前轮，direct 立即进链路且跑完当前轮后
+  优先于排队执行）；`POST /tasks/{id}/fork`（仅终态任务可分支，
+  继承 executor/模型/强度/权限/计划，goal 字段置空）。
+- **模型与网关**：子任务默认模型/强度（`child_model` /
+  `child_effort`，PR #121）；模型路由走 sub2api 中转网关，
+  断点命令的 model provider 须透传（PR #127 未合并，见顶部）。
+- **部署**：`deploy/deploy.py`（tar 默认，`--source git` 走主机
+  直拉 GitHub；产物唯一命名 + 三道 sha/commit 门 + 换目录
+  代替原地解包，health 须 `ok=true` 且 `backend=postgres` 且
+  commit 对上才算成功；主干推送不自动部署生产，见
+  `deploy/README.md`）。部署前先确认无人同时在推，并发部署
+  会撞目录换位；部署完须核 4 个 unit 全 active。
+
 ## 宿主编排（host.py，无 GUI，对齐 ChatGPT / Codex 桌面版宿主）

 ChatGPT / Codex 桌面版作为宿主，本质不是再写一个 agent，而是
@@ -170,14 +288,17 @@ turn 可以真正并发（不是轮流排队）。
 | 多机器 state 冲突 | 锁只防同一台机器，多机器共享 state 文件会静默覆盖 | 部分修：state 加 version/last_writer/updated_at，保存时磁盘版本比加载时新就记 STATE-CONFLICT 日志并合并保留双方任务，不静默丢；真多机同步仍需中心服务（见下“没对齐”） |
 | 合并时提交缓存文件 | merge 的 git add -A 会把 __pycache__/*.pyc 也提交进主仓，下次合并被 .pyc 改动挡住 | 已修：merge 前清 worktree 的 __pycache__/*.pyc，主仓的 .pyc 改动先还原；单测覆盖 pyc 不入库 |
 | 守护进程 + 健康检查 + 自动恢复 | host.py 跑完就退出，不常驻；state 坏了静默当空 state；中断任务一直停在 running | 已修：daemon（双 fork 到 PID 1，循环 recover + run-due）、health（不跑模型，查二进制/配置/state/server/daemon）、restore-state（坏了从 .bak 恢复并留底）、recover（超过阈值的 running 标 interrupted，可用 run 续跑，不自动重跑模型回合） |
-| GitHub PR / CI 一条线 | 本地 merge 完就完，没有 PR、没有 CI 门 | 已修（代码 + 本地可测部分）：github-workflow 生成 .github/workflows/host-verify.yml（checkout + python + unittest，幂等）；pr（push 分支 + gh pr create，成功后 pr_url/pr_number 写回任务记录）；pr-checks（解析 gh pr checks，all_pass 仅全 pass 为真，空 checks 不算过）；pr-merge（先查 checks，未全过拒绝且不调 merge，全过才 gh pr merge --merge 并标 merged，不动本地主分支）。gh 调用走 run_gh()，单测用假 gh。**真实 PR 本轮没跑**：本仓没有 git remote，gh 未登录，见下“GitHub PR/CI 的外部条件”。 |
+| GitHub PR / CI 一条线 | 本地 merge 完就完，没有 PR、没有 CI 门 | 已修（代码 + 本地可测部分）：github-workflow 生成 .github/workflows/host-verify.yml（checkout + python + unittest，幂等）；pr（push 分支 + gh pr create，成功后 pr_url/pr_number 写回任务记录）；pr-checks（解析 gh pr checks，all_pass 仅全 pass 为真，空 checks 不算过）；pr-merge（先查 checks，未全过拒绝且不调 merge，全过才 gh pr merge --merge 并标 merged，不动本地主分支）。gh 调用走 run_gh()，单测用假 gh。本仓的真实 PR 链路现已走通，见下“GitHub PR/CI”一节。 |
 | 边界：cwd、沙箱、审批、模型 | dispatch / turn 参数里定，见 `config.example.toml` | 已实测 |
 | 任务登记 | `host-state.json`：task -> thread/worktree/状态/diff；agent 状态本身仍在 CODEX_HOME，不另存第二份 | 已实测 |

 **没对齐的部分（诚实说，不是偷工）：**

- 云端派发、推送通知、Slack / GitHub 触发：那是 ChatGPT 托管服务，
-  开源里没有。`run-due` 要靠你自己的 cron 定时调，才等于“定时自动化”。
+- 云端派发、推送、GitHub 触发：本地 host 层仍没有，`run-due`
+  要靠你自己的 cron 定时调，才等于“定时自动化”；但云端控制面
+  层已经有了（见上文“云端控制面”）：队列派发、webhook 入站、
+  PR/CI 门、推送订阅与分发。Slack 触发未对真实 Slack 服务器
+  实测，不要把它写成已验证。
 - GUI 的 inline 评论、side-by-side diff、点按钮批准：无 GUI 版
  本来就不要这层，评审就是 git diff 文本 + merge/discard 命令。
 - Computer Use：另一条管线，不在宿主编排里。
@@ -189,10 +310,10 @@ turn 可以真正并发（不是轮流排队）。
  （gap2 实测拦下了一次 -X ours 丢 mul2 的情况）；依赖任务
  现在从依赖分支建 worktree，依赖先合、依赖任务后合时不再
  重复加同一段。
- 多机器同步：state 现在有 version 和冲突日志，不会静默丢
-  任务，但两台机器共享一个 state 文件仍不是 ChatGPT 云端
-  那种中心同步——要真多机，得另起一个中心 state 服务，
-  这不在本地 host 的范围里。
+- 多机器同步：本地 host-state 仍是单机文件（有 version 和
+  冲突日志，不会静默丢任务），真多机同步要走云端控制面
+  的中心数据库（Postgres），不在本地 host 的范围里；
+  同主机双进程模拟过的 HA 不等于第二台主机仍存活。
 - 守护进程的边界：daemon 本身也活不过 VM 平台回收（和
  微信桥 serve 一样，回收后要重拉），所以 VM 上更稳的定时
  仍是 Muse cron 定时调 run-due/health，而不是只靠 daemon
@@ -232,37 +353,36 @@ python3 host.py daemon-stop
  `python3 host.py automations --add --name <名> --task "<任务>" --repo <仓> --interval 86400`
  登记自动化，再确认模型 key 已走环境变量提供，才让定时去调
  `python3 host.py run-due`；未到期的自动化 run-due 时不重复派发。
- 云端控制面演示另起一端（不跑模型回合）：
+- 云端控制面另起一端（生产上 worker 会跑真实模型回合，
+  不再是“演示、不跑模型”）：
  `python3 -m cloud.server`（默认 127.0.0.1:8765），
  除 `GET /health`、`/webhooks/*`、`/oauth/*` 外都要 `X-API-Key` 请求头。
  任务实时链路：`GET /tasks/{id}/trace`（已结束任务的快照）与
  `GET /tasks/{id}/trace/stream`（运行中任务的 SSE：先 snapshot 再逐条
  entry，终态发 done 关流；命令台详情的链路区用 fetch 流式读它，
  EventSource 不能带 X-API-Key 头故不用）。
-  新业务链路：建任务可带 `plan`（计划模式：只读沙箱，执行器传
-  `--sandbox read-only`；不能与 `approval=full` 或 goal 同用）；
-  `POST /tasks/{id}/followups`（body/mode，mode 为 queued 或
-  direct；仅 queued/running 的非 goal 任务可接）与
-  `GET /tasks/{id}/followups`（按创建时间排序）——排队不打断当前
-  轮、跑完按序再跑一轮，直接发送立即进链路（phase=followup-direct）
-  且跑完当前轮后优先于排队执行；`POST /tasks/{id}/fork`
-  （message 必填；仅终态任务可分支，继承 executor/模型/强度/
-  权限/计划，goal 字段置空，首轮失败不自动重试、不重复分叉）。
+  新业务链路见上文“云端控制面”：`plan`、`followups`
+  （queued/direct）、`fork`，以及继续消息持久化。

-## GitHub PR/CI 的外部条件（真实 PR 仍缺这两样）
+## GitHub PR/CI：本仓已走通，旧“无远端、无登录”已过期

-PR/CI 这条线本轮只做了代码和本地可测部分，真实 PR 没有跑，
-原因如实写在这里，不是没做完就含糊过去：
+旧版这里写着“本仓没有 git remote、gh 未登录、真实 PR 没跑”——
+那是 2026-10-25 左右的快照，现已过期。本仓现为
+`github.com/openqj/codex-app-server`，PR → CI（host-verify）
+→ `--merge` 合并 → `deploy.py` git 模式部署已是常规链路
+（例如 #124 React 命令台、#125 Muse 风格、#126 继续消息持久化、
+#128 一页式排版、#129 GitHub 风格、#130 自适应分栏，均经此链路上线生产）。
+不要再拿旧段落去推断本仓的 PR 能力。

- **仓库远端**：本仓（codex-app-server）目前没有 git remote
-  origin，`git remote -v` 为空。pr 命令会先查 remote，没有就
-  明确报错，不静默失败。以后给仓库加 remote 再跑：
-  `git remote add origin <url>`。
- **gh 登录**：本机有 `gh`，但 `gh auth status` 显示未登录。
-  不要在本轮登录，也不要把 PAT 写进任何文件、state、日志或
-  聊天记录；以后用户给 PAT 时走 Secure Vault，再跑
-  `gh auth login`。没有登录时 pr/pr-checks/pr-merge 会把 gh
-  的错误原文打印出来，不编造 PR URL。
+但要分清两条线：
+
+- **本仓的发布链路**：分支 → PR → CI 全过 → 合并进 main →
+  git 模式部署到生产主机，部署须验 health 与 commit 一致。
+- **host.py 的 pr/pr-checks/pr-merge**：那是给任意目标仓库用的
+  本地命令，仍要求目标仓有 remote 且运行机器上 `gh` 已登录；
+  没有登录时它会把 gh 的错误原文打印出来，不编造 PR URL。
+  不要把 PAT 写进任何文件、state、日志或聊天记录；需要登录时
+  走 Secure Vault。
 - **流程（远端和登录齐了之后）**：
  1. `host.py github-workflow` 生成 CI workflow（已生成的文件
     要提交进仓库，GitHub Actions 才会跑它）；
@@ -280,12 +400,36 @@ PR/CI 这条线本轮只做了代码和本地可测部分，真实 PR 没有跑
 ## 开源没给到的（别指望照搬）

 - 模型本身、ChatGPT 登录、计费、Codex Cloud 云端沙箱。
- GitHub / Slack 等渠道的托管派发。
- 桌面版的 diff 评审 UI、多线程看板、通知。
+- GitHub / Slack 等渠道的托管派发：云端层已有 webhook 入站、
+  推送订阅与自动 PR，但 Slack 触发未对真实服务器实测，
+  托管派发不等于 ChatGPT 托管服务。
+- 桌面版的 inline 评论、side-by-side diff、点按钮批准：
+  命令台有评审队列与对话时间线，但评审仍是 git diff 文本 +
+  merge/discard 命令，不是桌面版评审 UI。
 - Computer Use（屏幕操作）是另一条管线，不在 CLI 中间层里；
  本版 features 里虽然有 `computer_use` 开关，但那不是
  “复制 app-server 就自动得到一个桌面操作 agent”。

+## 诚实边界（2026-10-29，更新 README 时仍成立的）
+
+- **内层沙箱**：Docker 容器嵌套 pidns 下 bwrap 的 fresh proc
+  mount 被内核拒绝（宿主级 + 带 userns 的 AppArmor profile
+  才能跑通 workspace-write），所以生产是 Docker 隔离 +
+  容器内 danger-full-access，不是双层沙箱；宿主级 workspace-write
+  下 agent 只能写自己 worktree，但 `/tmp` 不隔离，写 /tmp 会落到
+  宿主 /tmp 上。
+- **并行规模**：18 人并行已探过，40 人并行未证明且已暂搁置；
+  需要 40 人规模时走串行分波次或拆小批次，不要把 18 人的通过
+  写成 40 人的通过。
+- **HA**：多机 HA 0→4 的跨机部分是同主机双进程模拟验证，
+  真“杀一台主机仍存活”需要第二台 VPS；VM 会被平台定时回收，
+  不能作 HA 节点。
+- **未合并的在途工作**：G10 断点 provider（PR #127）只推了 PR，
+  未合并、未部署；不要在 README 里把它写成已上线。
+- **密钥**：API key、OAuth secret、中转 key 只走环境变量或
+  Secure Vault，绝不写进仓库、state、日志或聊天记录；
+  key 明文只在签发时返回一次。
+
 ## 安全

 - 常驻服务不要用 `danger-full-access`，也不要把