@@ -146,12 +146,12 @@ Baidu Netdisk 在 UniDesk 语境中按纯后端服务管理：不得暴露百度
- Direct path ban： `code-queue` 不得再登记 `http://code-queue:4222` 、`http://host.docker.internal:4222` 、NodePort 或 provider-gateway `microservice.http` 作为业务代理目标；frontend 也不得使用旧 `/api/code-queue-direct` 兼容别名作为 Code Queue 页面数据源。provider-gateway 只允许用于维护 D601/D518、部署 adapter、部署 v3s/k8s 节点或诊断节点本机容器。
- 实例语义：D601 是默认 active/single-writer 实例，`CODE_QUEUE_INSTANCE_ID=D601` 且 `CODE_QUEUE_SCHEDULER_ENABLED=true` ； `CODE_QUEUE_INSTANCE_ID=D518` 、`CODE_QUEUE_SCHEDULER_ENABLED=false` 和 `CODE_QUEUE_STARTUP_OA_BACKFILL_ENABLED=false` ，避免两个实例同时消费同一 PostgreSQL 队列或重复回放 OA 统计。D601 active 也默认关闭 `CODE_QUEUE_STARTUP_OA_BACKFILL_ENABLED` ；历史 OA Trace/STEP 回填必须通过显式 `/api/oa/backfill` 运维动作触发，不能在每次 Pod 重启时自动批量发布旧事件。
- 部署引用：Code Queue 镜像仍复用 `src/components/microservices/code-queue/Dockerfile` ， `src/components/microservices/v3sctl-adapter/v3s/code-queue.k8s.yaml` ， `config.json` 对外记录 v3s manifest `src/components/microservices/v3sctl-adapter/v3s/code-queue.v3s.json` ；主 server 根目录 `docker-compose.yml` 不包含 `code-queue` service，旧 D601 direct Compose 文件只作为迁移/本地诊断参考，不是正式运行入口。
- 主服务依赖映射：Code Queue 仍以主 PostgreSQL 为权威数据库，`DATABASE_URL` 必须指向主 server 受限端口映射； `OA_EVENT_FLOW_BASE_URL` 必须指向主 server OA Event Flow 受限端口映射； D601 active 实例的 `CODE_QUEUE_NOTIFY_CLAUDEQQ_BASE_URL` 直接使用本机 ClaudeQQ 映射 `http://host.docker.internal:3290` 。这些端口映射只服务受控节点运行时，必须用防火墙或等价策略限制来源，不得成为浏览器或任意公网客户端入口。
- 主服务依赖映射：Code Queue 仍以主 PostgreSQL 为权威数据库，但 D601 k3s Pod 不能依赖公网直连 `74.48.78.17:15432/4255` 。Pod 内 `DATABASE_URL` 和 `OA_EVENT_FLOW_BASE_URL` 必须指向集群内 `d601-tcp-egress-gateway` Service，再由该 gateway 通过 D601 provider-gateway egress proxy 的 HTTP CONNECT 转发到主 PostgreSQL 和 OA Event Flow；新增 TCP 依赖时扩展 `TCP_EGRESS_ROUTES` ，不得在业务容器里新增一次性公网直连或 ad hoc 隧道。 D601 active 实例的 `CODE_QUEUE_NOTIFY_CLAUDEQQ_BASE_URL` 直接使用本机 ClaudeQQ 映射 `http://host.docker.internal:3290` 。这些端口映射只服务受控节点运行时，必须用防火墙或等价策略限制来源，不得成为浏览器或任意公网客户端入口。
- K8s 探针与启动维护：Kubernetes liveness/startup probe 必须使用轻量 `/live` ，readiness 和用户服务健康使用 `/health` ； `/health` 不得执行全量任务聚合、历史回填或长事务索引维护，历史任务总览应由 `/api/tasks/overview` 读取 PostgreSQL。启动时允许后台执行队列元数据 flush、通知 outbox 读取、任务表索引维护和 overview warmup，但这些维护不得阻塞 Bun server、readiness endpoint 或 frontend overview；通知表索引和大批量 OA backfill 不得作为默认启动副作用。
- MiniMax/OpenCode 并发：`minimax-m2.7` 通过 OpenCode JSON 事件端口运行；每个 Code Queue task 必须使用独立的 OpenCode XDG data/config/cache/state 目录，禁止多队列并发任务共享同一个 OpenCode SQLite/WAL 状态目录，否则并发 smoke 会触发 `PRAGMA journal_mode = WAL` 之类的数据库锁或初始化错误。用于验证 v3s/k8s 链路的 MiniMax smoke 以“至少 4 个任务、分布到 2 个 queue、至少 2 个终态成功”为链路验收线；剩余失败如果是 OpenCode 最终回复捕获、业务任务判定或模型限流，应作为 Code Queue 执行可靠性问题单独排查，不能反推 v3s 代理链路失败。
- 默认出网代理：D601 active Code Queue Pod 必须默认把 `HTTP_PROXY` 、`HTTPS_PROXY` 和 `ALL_PROXY` 注入给 Codex/OpenCode、`git` 、`curl` 、`npm` 等任务子进程；当前唯一上游是 D601 provider-gateway egress HTTP CONNECT 代理，并通过 Kubernetes `Service d601-provider-egress-proxy` 暴露给 `unidesk` namespace 内的 Pod。该 Service 的 EndpointSlice 指向 D601 provider-gateway 私有 Docker network endpoint， `http://d601-provider-egress-proxy.unidesk.svc.cluster.local:18789` ， `127.0.0.1` ，不得开放公网；如 provider-gateway 容器 IP 变化，必须同步刷新 EndpointSlice 并用 Code Queue `/health.egressProxy.connected=true` 验证。这里的 provider-gateway 只承担出网代理，不承担 Code Queue 业务 HTTP 代理；业务访问仍只能走 Kubernetes API service proxy。k3s/k8s 原生 egress gateway、service mesh 或 CNI egress policy 只作为后续网络层增强方向，当前交付态不引入第二套出网控制面。远程开发/执行容器不得只依赖这些环境变量，必须在容器网络层用 TUN 默认路由和 OUTPUT 防火墙强制外网流量只能经 master TUN 出口。
- 出网代理无 fallback 纪律：Code Queue 的运行时配置只允许一个默认出网路径，即 provider-gateway egress proxy；不得在代码中同时保留 Code Queue 自建 WebSocket proxy、临时 shell proxy、D601 本地直连公网、主 server direct HTTP proxy 等隐式分支。任何新增网络 fallback 都必须先进入本参考文档并配套 `/health` 可见状态，否则视为残留旧路径。
- 上线纪律：Code Queue 相关的前端或后端改进必须在同一任务内正式上线并验证公网 frontend 或 live API，不能只停留在源码、构建产物或“后续再上线”。修改 Code Queue 自身时不得等待当前 Code Queue task 结束、等待 queue idle 或等待 `0 running` 后才重启；应通过 v3s 控制面或 D601/D518 维护入口做 build-first 替换 ，并用 v3s adapter、Code Queue live API 或公网 frontend 证明任务和队列仍可读可继续。
- 上线纪律：Code Queue 相关的前端或后端改进必须在同一任务内正式上线并验证公网 frontend 或 live API，不能只停留在源码、构建产物或“后续再上线”。修改 Code Queue 自身时不得等待当前 Code Queue task 结束、等待 queue idle 或等待 `0 running` 后才重启；D601 active 实例的正式后端部署入口是 `bun scripts/cli.ts codex deploy <commitId>` ，它按已 push 的 remote commit 做 build-first 镜像替换、k3s image import、manifest apply、rollout 和健康验证 ，并用 v3s adapter、Code Queue live API 或公网 frontend 证明任务和队列仍可读可继续。
- 更名与灾备恢复：旧版 Codex 队列服务名只允许作为兼容诊断和一次性迁移来源；`code-queue-backend` 容器自身 `/health` 正常但 `microservice health code-queue` 返回 provider 直连错误时，优先判定为 backend-core 仍加载旧 `MICROSERVICES_JSON` 或 adapter manifest 未刷新，必须刷新 `.state/docker-compose.env` 、重建/替换 `backend-core` 与 `v3sctl-adapter` ，随后用 `microservice list` 验证 `code-queue` 的 `runtime.orchestrator=v3sctl` 、`backend.proxyMode=v3sctl-adapter-http` 和无业务容器直连摘要。
- Codex 认证：容器只从 D601 的 `/home/ubuntu/.codex/config.toml` 同步 Codex provider 配置到 D601 `.state/code-queue/codex-home` ，并通过 D601 `.state/code-queue-d601.env` 透传 `OPENAI_API_KEY` 、`CRS_OAI_KEY` 等 provider 所需变量；这些 provider 环境变量不得写入仓库，必须由 D601 Compose env-file 注入，确保容器重建和重启后不会丢失认证。新增 provider 的 `env_key` 时必须增加同类运行时透传和 Compose env 持久化，禁止把 Codex 或 MiniMax 密钥写入仓库文件。Code Queue 容器必须只读挂载 D601 host 的 SSH 目录到 `/root/.ssh` （默认 `/home/ubuntu/.ssh` ），让容器内 `git push` 、`ssh -T git@github.com` 与 host 使用同一套 GitHub SSH key/known_hosts；不得把私钥复制进镜像或仓库。
- Develop-ready 镜像：Code Queue 镜像必须在启动前预装 UniDesk/Pipeline 调试所需工具，至少包含 `codex` 、`bun` 、`node` 、`npm` /`npx` 、`git` 、`rg` 、`curl` 、`python3` /`pip3` 、`docker` 、`docker compose` 、`docker-compose` 、`jq` 、`ssh` 、`rsync` 、`make` 、`gcc` /`g++` 、`iptables` 、`tar` 、`gzip` 和 `unzip` ；不得依赖 Codex 任务运行时再 `apt-get install` 这些基础环境。
@@ -162,7 +162,7 @@ Baidu Netdisk 在 UniDesk 语境中按纯后端服务管理：不得暴露百度
- Codex 控制：服务内部启动 `codex app-server --listen stdio://` ，用 JSON-RPC 调用 `thread/start` 、`turn/start` 、`turn/steer` 和 `turn/interrupt` ，并监听 `turn/completed` 、assistant delta、reasoning delta、command output delta、file diff delta 等通知生成前端可轮询的 transcript。
- 用户输入持久化：任务初始 prompt 以 `basePrompt/displayPrompt` 作为结构化来源，运行中追加的 `turn/steer` prompt 必须写入 `promptHistory` ； `Submitted prompt` 和 `Steer prompt` ，不能只依赖有 600 条上限的 raw output，否则长任务输出增长后会丢失关键人工指令。
- 队列语义：`POST /api/tasks` 或 `/api/tasks/batch` 入队，服务始终只运行一个 Codex turn；当前任务真正终止后才推进下一个任务。`GET /api/tasks` 与 `GET /api/tasks/{id}` 返回队列、attempt、judge 和输出；`GET /api/tasks/{id}/summary` 返回按任务 ID 查询的结构化摘要，包括初始 prompt、最后 assistant message、工具调用摘要、attempt、judge、错误和耗时；CLI 入口是 `bun scripts/cli.ts codex task <taskId>` 。`GET|POST /api/tasks/{id}/judge?attempt=N` 与 CLI `bun scripts/cli.ts codex judge <taskId> --attempt N` 用于单步复现指定 attempt 的 judge，必须复用真实队列 worker 的上下文构建、prompt 压缩、MiniMax 调用、JSON 去噪/repair 和 fallback 路径；`dryRun=1` /`--dry-run` 只输出 prompt/payload 和重建诊断，不调用 MiniMax。`POST /api/tasks/{id}/steer` 向运行中 turn 推入 prompt； `POST /api/tasks/{id}/interrupt` 或 `DELETE /api/tasks/{id}` 打断/取消；`POST /api/tasks/{id}/retry` 手动重试。队列 worker 必须隔离单个 task 的异常，不能因为某个 app-server、judge 异常或 judge 判定 `fail` 让后续 queued 任务停止；`fail` 只把当前任务标为 failed，随后必须继续扫描并推进下一个 queued/retry_wait 任务。当存在 queued/retry_wait 且 worker 空闲时，watchdog 必须自动重新调度。
- 稳定性与重启恢复：Code Queue 的第一目标是长期稳定可用；部署修复或运维排障时不得因为担心容器重启会打断任务而拒绝重启、重建或替换 `code-queue-backend` `promptHistory` 、running/judging/retry_wait 任务和 active session 元数据必须从 PostgreSQL 恢复，并在已有 `codexThreadId` 可用时用 `thread/resume` 和 continuation prompt 无缝继续当前任务；如果原 app-server turn 已丢失，也必须把当前任务恢复到可 retry/continue 的状态，不能错误推进下一个任务或永久卡住。D601 侧重建必须走 `src/components/microservices/code-queue/docker-compose.d601.yml` ，并且必须在 build 后执行 force-recreate 与 post-up health validation；禁止先 手工 `docker rm ` 再依赖后续命令补救，因为中断窗口会让 Pod/容器消失并触发 frontend/core 用户服务代理失败。重启后出现 active task 丢失、手动 steer/interrupt 记录丢失、running 任务卡死、误判完成、跳过当前任务、容器消失或阻塞队列，均属于 Code Queue 的 P0 核心缺陷，必须先修复并补充 restart-recovery 验收，不能把“避免重启”作为交付策略。
- 稳定性与重启恢复：Code Queue 的第一目标是长期稳定可用；部署修复或运维排障时不得因为担心容器重启会打断任务而拒绝重启、重建或替换 active Pod 。容器重启、服务进程重启和镜像替换后，队列、`promptHistory` 、running/judging/retry_wait 任务和 active session 元数据必须从 PostgreSQL 恢复，并在已有 `codexThreadId` 可用时用 `thread/resume` 和 continuation prompt 无缝继续当前任务；如果原 app-server turn 已丢失，也必须把当前任务恢复到可 retry/continue 的状态，不能错误推进下一个任务或永久卡住。D601 侧重建必须走 `bun scripts/cli.ts codex deploy <commitId>` ；禁止先手工 `docker rm` 或只 手工 `docker compose up ` 再依赖后续命令补救，因为中断窗口会让 Pod/容器消失并触发 frontend/core 用户服务代理失败。重启后出现 active task 丢失、手动 steer/interrupt 记录丢失、running 任务卡死、误判完成、跳过当前任务、容器消失或阻塞队列，均属于 Code Queue 的 P0 核心缺陷，必须先修复并补充 restart-recovery 验收，不能把“避免重启”作为交付策略。
- 调度与 active run slot： `CODE_QUEUE_MAX_ACTIVE_QUEUES` 只限制真实 active run slot，不能把 retry backoff、等待内存下降或等待前序任务的 `processingQueues` 计入 active slot，否则设置全局 active slot 上限时，一个空等队列会把其他 runnable queue 永久饿死。多个 queue 同时等待 active slot 时必须显式维护 FIFO waiter 队列，避免某个长 retry/backoff 队列刚释放 slot 就立刻重抢，导致更早进入等待的 `retry_wait` 任务长期饥饿；`/health` 必须同时暴露真实 `activeQueueIds` 、`activeRunSlotCount` 、等待中的 `processingQueueIds` 和 active slot waiters，排障时以 active run slot 与 waiter 顺序判断是否真的有任务在跑、谁应下一个启动。restart-recovery 后的 `retry_wait` 任务若缺失 `codexThreadId` /OpenCode session id，不得无限拒绝 retry；必须用紧凑 recovery prompt 和原始任务摘要重新开一个 agent thread/session，让任务继续推进并在 Trace 中留下 recovery 证据。任何修改 scheduler、retry backoff、queue move、manual retry、shutdown recovery 或内存等待逻辑时，都必须保留“空等 processor 不占 active run slot”、“等待者 FIFO 不饥饿”和“缺失 thread/session 可恢复”的自测或 live 验证。
- 内存优化过程与防回归：Code Queue 已迁移到 D601，但内存治理仍必须按“PostgreSQL 权威源优先、进程热状态最小化、容器硬上限兜底”的顺序设计。长期可复用的优化路径是：先确认任务、queue、readAt、promptHistory、active session 和通知 outbox 均可从 PostgreSQL 恢复；再把历史任务列表、详情、统计、Trace/output 和 `/health` 的只读查询改为 PostgreSQL 直读或聚合查询；随后只把 `queued` 、`running` 、`judging` 、`retry_wait` 等调度必需任务载入 Bun 堆，并在 PostgreSQL 查询侧裁剪 hot `output` /`events` ；最后用 dirty-only flush、append-only 输出归档、Codex SQLite 小批量导出、`bun --smol` 、`mem_limit=600m` 、`memswap_limit=1536m` 、`NODE_OPTIONS=--max-old-space-size=768` 和 cgroup memory watchdog 作为运行时防线。PostgreSQL 到进程的单次读取足够快，不能为了减少 SQL 查询把全部历史 `task_json` 、Trace、output 或统计摘要常驻内存；任何新增缓存都必须有默认较小的环境变量上限、明确淘汰策略、可从 PostgreSQL 或 append-only 归档重建，且不得影响重启恢复。新增或修改 `/api/tasks` 、overview、stats、summary、transcript、output、trace、health、flush、scheduler 和通知路径时，禁止在常规请求中调用会物化全量历史任务 JSON 的代码，禁止启动后无条件重写全量历史 task JSON，禁止用未设上限的 `Map` /数组保存历史 output/event/Trace， `CODE_QUEUE_MAX_ACTIVE_QUEUES=0` 表示不按 queue 数量设置全局排队上限；如显式设置为正数，必须同时说明内存预算并补充内存压测验收。memory watchdog 必须以 cgroup working set 为主要判断，且在 swap 仍有余量时不得提前杀掉唯一 active run；否则 TypeScript/Playwright 这类短时高内存验证会被错误中断并让 retry 队列反复震荡。
- 列表/详情延迟优化原则：Code Queue 控制面交互的长期目标是常规历史规模下首屏、`GET /api/tasks/overview` 、`POST /api/tasks/<id>/read` 和分页加载均在 1s 内完成；性能面板出现十几秒级 `core_proxy` 或 Code Queue 用户服务代理慢操作时，必须优先按后端查询形态和前后端通信策略定位，不能把问题归因于 React 渲染后只改 UI。后端优化顺序是：先为 queue、status、updated/created 时间、readAt/terminal unread 和常用筛选条件补齐 PostgreSQL 索引；再用 SQL `COUNT` 、`GROUP BY` 、条件聚合和分页 ID 查询生成 queue/status/stats/unread 摘要；随后按 ID 轻量加载当前页、selected、active 和 unread priority task，禁止为了列表或已读操作解析完整 Trace、output archive、Codex transcript 或物化全量历史 `task_json` 。`read` /`read-all` 这类 mutation 必须是 SQL-only 更新并返回最小 patch/queue 计数，不能触发 overview 全量重算或重载所有任务；启动 warm 只能预热小体积聚合和索引路径，不得把历史任务作为常驻缓存。允许 frontend/backend 代理使用秒级、严格有界、mutation 自动失效的 overview micro-cache 来吸收重复刷新，但 cache 只能作为抖动保护，不能替代数据库索引、聚合查询和分页披露，也不能让 stale readAt/queue/status 状态跨设备可见。
Codex