@@ -138,22 +138,22 @@ Baidu Netdisk 在 UniDesk 语境中按纯后端服务管理：不得暴露百度
- OpenCode 远程执行：`minimax-m2.7` 走 OpenCode JSON event port 时，本地和远程命令都必须显式执行 `opencode run ...` ；远程 Docker exec 不得退化成 `exec run ...` ，否则会在目标容器内变成 `bash: exec: run: not found` 。OpenCode JSON stream 的终态判定以“当前进程退出码 + 当前 attempt 的最终 assistant response”为准：`exit=0` 且当前 attempt 产生非空最终回复时，即使上游没有发 `step_finish` 事件，也应视为正常 terminal；非零退出、无当前最终回复或传输关闭才进入 retry。每个 attempt 的 `finalResponse` 必须只来自当前 OpenCode/Codex turn，禁止在当前 turn 未产出最终回复时回退复用 task 上一次 `finalResponse` ，否则会把旧任务内容误判为本轮完成。
- 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>` 。`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 必须自动重新调度。
- 队列语义：`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`； `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 的状态，不能错误推进下一个任务或永久卡住。主 server 侧重建必须走 `server rebuild code-queue` ，该 job 受 `.state/locks/server-compose.lock` 串行化约束，并且必须在 build 后执行 no-deps force-recreate 与 post-up health validation；禁止在 job 中先手工 `docker rm` 再依赖后续命令补救，因为中断窗口会让容器消失并触发 frontend `direct microservice proxy failed` 。重启后出现 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 验证。
- 内存优化过程与防回归：主 server 内存预算很小，Code Queue 的内存治理必须按“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 内完成；性能面板出现十几秒级 `code_queue_direct_proxy` 或 `core_proxy` 慢操作时，必须优先按后端查询形态和前后端通信策略定位，不能把问题归因于 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 状态跨设备可见。
- Trace/实时输出热路径防回归：Code Queue 的 `appendOutput` 、output archive append、`publishTaskEvent` 、SSE `/api/events` 、任务列表、overview、task meta 和 `/health` 都属于热路径，必须保持 O(1) 或明确小常数上界；这些路径不得同步调用完整 transcript 构建器、`taskFullOutput` 、output archive 全量读取、Codex session/log 文件解析、完整 `task_json` 物化或任何会随历史输出长度增长的统计。输出追加时必须增量维护轻量持久化指标，至少包括 `stepCount` 、`llmStepCount` 、`outputMaxSeq` 或等价字段；列表、overview、meta、SSE 事件和 `/health` 只能读取这些指标或小体积 SQL 聚合。完整 Trace、`trace-summary` 、`trace-steps` 、`trace-step` 、transcript/output 详情允许在显式详情请求中解析归档，但必须分页或有界、使用短 TTL 或容量受限缓存，并在 archive append 后失效。若 frontend 性能面板出现 Code Queue direct proxy 502、`/api/tasks/overview` /trace 接口成批超时，或容器内 `/health` 在 active output 持续追加时也卡住，优先按 Bun event-loop starvation/backpressure 排查，而不是先改 React 渲染；修复必须证明热路径不再随 output/archive 历史线性增长。
- 完成判定：app-server `turn/completed` 的 `turn.status=completed|interrupted|failed` 只代表 Codex turn 已结束；即使 `completed` 也必须把原始任务、当前 attempt 的 assistant 最终回复、command/file-change 事件、stderr tail 和 current attempt events 组成 execution record 交给 judge 判断是否真的完成。MiniMax judge 之前和之后都必须保留少量协议级硬门禁：明确用户 interrupt 判为 fail；当前 attempt `terminalStatus=failed|null` 、传输在终态前关闭、或当前 attempt 最终回复为空时判为 retry；这些门禁只保护“本轮 turn 是否可被验收”的事实，不得发明业务实现要求。协议门禁通过后，配置了 `UNIDESK_CODE_QUEUE_MINIMAX_API_KEY` 且 MiniMax 可用时，MiniMax `MiniMax-M2.7` 对业务是否 `complete|retry|fail` 的判定是权威结果；当且仅当 MiniMax LLM 调用失效（未配置、额度/限流/网络/超时不可用、JSON 去噪与 repair 全部耗尽、或返回超预算反馈且修复耗尽）时，才允许启用非 LLM/fallback 判断。MiniMax 返回必须先做 JSON 去噪，支持去除 Markdown fence、`json` 标签和从夹杂文本中提取平衡 JSON object；如果去噪后仍无法解析，服务必须把解析错误和上一轮去噪前原始回答反馈给 MiniMax 做 JSON repair 重试，重试次数由 `UNIDESK_CODE_QUEUE_MINIMAX_JUDGE_REPAIR_ATTEMPTS` 控制，默认 `2` ，耗尽后才进入 fallback，并在 fallback 原因中保留 MiniMax 失败信息 。
- 完成判定：app-server `turn/completed` 的 `turn.status=completed|interrupted|failed` 只代表 Codex turn 已结束；即使 `completed` 也必须把原始任务、当前 attempt 的 assistant 最终回复、command/file-change 事件、stderr tail 和 current attempt events 组成 execution record 交给 judge 判断是否真的完成。MiniMax judge 输入必须做有界压缩，保留终态、最终回复、关键错误/命令/部署证据和摘要计数，避免长 transcript 让 MiniMax 请求超时；默认 `UNIDESK_CODE_QUEUE_MINIMAX_JUDGE_TIMEOUT_MS=90000` 。MiniMax judge 之前和之后都必须保留少量协议级硬门禁：明确用户 interrupt 判为 fail；当前 attempt `terminalStatus=failed|null` 、传输在终态前关闭、或当前 attempt 最终回复为空时判为 retry；这些门禁只保护“本轮 turn 是否可被验收”的事实，不得发明业务实现要求。协议门禁通过后，配置了 `UNIDESK_CODE_QUEUE_MINIMAX_API_KEY` 且 MiniMax 可用时，MiniMax `MiniMax-M2.7` 对业务是否 `complete|retry|fail` 的判定是权威结果；当且仅当 MiniMax LLM 调用失效（未配置、额度/限流/网络/超时不可用、JSON 去噪与 repair 全部耗尽、或返回超预算反馈且修复耗尽）时，才允许启用非 LLM/fallback 判断。MiniMax 返回必须先做 JSON 去噪，支持去除 Markdown fence、`json` 标签和从夹杂文本中提取平衡 JSON object；如果去噪后仍无法解析，服务必须把解析错误和上一轮去噪前原始回答反馈给 MiniMax 做 JSON repair 重试，重试次数由 `UNIDESK_CODE_QUEUE_MINIMAX_JUDGE_REPAIR_ATTEMPTS` 控制，默认 `2` ，耗尽后才进入 fallback，并在 fallback 原因、task JSON、attempt summary 和 TraceView 中保留 MiniMax 失败阶段、是否超时、耗时、prompt/payload 大小、HTTP 状态、错误名和响应预览 。
- Judge 权威边界：MiniMax 成功返回可解析、预算内的 judge JSON 后，Code Queue 不得用旧 attempt 的 429/exceeded retry limit 证据、历史 output 字符串、面向特定任务的正则或 `hardCompletionBlockers` /`retryRequiredReasons` 覆盖一次协议有效的完成判定；尤其不能因为 attempt 1 的限流中断仍在历史输出里，就禁止 MiniMax 把 attempt 2 的正常完成判为 `complete` 。允许的本地 safety override 必须限定为协议事实和系统交付纪律：用户显式打断、当前 attempt 未正常终止、当前 attempt 没有最终 assistant response、最终回复停在并发文件确认而非交付、或 runtime/UI/service 变更承认未部署验证。所有 override 都必须写入 `_safetyOverride` 、生成紧凑 continuation prompt，并由自测或 judge probe 覆盖；不得把业务猜测伪装成本地硬门禁。
- Retry/推进语义：`retry` 不是新开一个独立任务或完全新 session；只要已有 `codexThreadId` ，服务必须 `thread/resume` 原 thread 并 append 一个继续执行 prompt。continuation/judge feedback prompt 只应携带本轮缺口、恢复原因、验收要求和有界原始任务摘要，禁止重新注入完整引用上下文、历史 transcript 或长 JSON；服务重启恢复类 feedback 尤其必须保持短 prompt，依赖现有 thread 上文继续。超长 prompt 必须在 prompt 合成源头解决：每个 feedback/recovery/judge 生成器都要从结构化字段选择必要信息、去重合并缺口并提供按需查询入口，禁止先合成超长 prompt 再在末端用 substring/safePreview 一刀切硬截断；硬截断会静默丢失验收信息，风险高于长 prompt 本身。若 MiniMax `continuePrompt` 超出预算，必须要求 MiniMax 基于原始 judge 输入重新合成紧凑反馈，repair 耗尽后才可进入 fallback；不得把已生成的长 prompt 截尾后发送给 Codex。若 MiniMax 成功返回了预算内 `continuePrompt` ，必须原样使用该反馈，不得再用 71-Freq、`period_sum/mpu_read_num` 、`mpu_read_num` 、历史限流中断等字符串识别把它覆盖成“简洁原始需求 continuation”。只有 judge 判定 `complete` 后，队列 worker 才把当前任务标为成功并推进下一个 queued/retry_wait 任务。非 LLM/fallback 判定产生的 `retry` 最多累计 `3` 次；达到上限后当前任务必须转为 `failed` 并记录原因，worker 继续推进后续 queued/retry_wait 任务，避免 fallback safety override 或硬编码判断造成无限循环。
- Judge 探针：`GET|POST /api/judge/probe` 使用同一套 judge 逻辑跑内置 synthetic execution records，覆盖正常完成、正常结束但只给计划、未上线/未部署的服务或 WebUI 改动、传输中断和用户打断等样本，返回 `hits` 、`total` 、`hitRate` 、每例 `expected` 与 `decision` ；该接口不得回显 MiniMax API key。
- Judge 探针与复现 ： `GET|POST /api/judge/probe` 使用同一套 judge 逻辑跑内置 synthetic execution records，覆盖正常完成、正常结束但只给计划、未上线/未部署的服务或 WebUI 改动、传输中断和用户打断等样本，返回 `hits` 、`total` 、`hitRate` 、每例 `expected` 与 `decision` ；该接口不得回显 MiniMax API key。真实任务排障必须优先使用 `codex judge <taskId> --attempt N` 或 `/api/tasks/{id}/judge?attempt=N` ，响应要包含 attempt 窗口、promptChars/payloadBytes、stored judge 对比、MiniMax 失败阶段和是否因历史 per-attempt events 缺失而降级为 retained events 重建。
- 模型选择：默认 Codex 模型是 `gpt-5.5` ，内置模型队列包含 `gpt-5.5` 、`gpt-5.4-mini` 、`gpt-5.4` ； `gpt-5.5` 的默认 reasoning effort 必须是 `xhigh` ，可通过 `CODE_QUEUE_MODEL_REASONING_EFFORTS` 追加或覆盖模型级默认值；每个入队任务可通过前端模型下拉菜单或 API 覆盖 `model` 、`cwd` 、`reasoningEffort` 和 `maxAttempts` ， `maxAttempts` 上限为 `99` 。Judge 判定 `retry` 或非用户取消类 `fail` 时必须继续已有 `codexThreadId` ，不能新建 session；重试间隔使用指数退避，从 `1s` 开始，最大 `10min` 。MiniMax 不可用而进入 fallback/non-LLM 判定时，当前 attempt 的 429、Too Many Requests、exceeded retry limit、overloaded、stream disconnected 等服务/限流错误应判定为 `retry` ，不能当作完成；MiniMax 可用时，这些内容只能作为当前 attempt 的 factual evidence 提供给 MiniMax，不能通过硬编码覆盖 MiniMax 结果。
- 状态与日志：`main-server` 默认工作目录为容器内 `/root/unidesk` ，该路径映射主 server 的 `~/unidesk` ；同时保留 `/workspace` 映射以兼容历史任务。非主 server Provider 的任务默认工作目录为 `/home/ubuntu` ，任务 JSON、列表、Trace 摘要和 CLI 查询都必须显示 `providerId` 与最终 `cwd` `readAt` /未读状态、attempt、judge、`promptHistory` 、active session 元数据、控制状态和 ClaudeQQ 通知 outbox 一律以主 PostgreSQL 为权威，分别写入 `unidesk_code_queue_tasks` 、`unidesk_code_queue_queues` 与 `unidesk_code_queue_notifications` ； `DATABASE_URL` 是必需配置，服务不得在 PostgreSQL 缺失或不可用时进入文件存储模式。`.state/code-queue/state.json` 不再作为任务或 queue 状态存储，不得重新引入本地 JSON fallback；服务启动必须以 PostgreSQL 为唯一来源恢复队列，并把 running/judging 任务恢复为 retry_wait。主 server 内存很少，Code Queue 必须把“内存是稀缺资源”作为核心设计约束：历史任务列表、详情、统计和只读 Trace 查询优先从 PostgreSQL 直读，进程内只保留当前 running/judging、queued、retry_wait 等调度必需热任务，不得把全部历史 task JSON 长期缓存到 Bun 堆；需要短期热缓存时必须有严格上限、可裁剪、可从 PostgreSQL 和 append-only 输出归档重建。WebUI 不得用 browser `localStorage` 、`sessionStorage` 或 IndexedDB 持久化 task/queue/readAt/unread 等业务状态；浏览器只能保留临时 UI 内存缓存，刷新后必须重新从后端读取 PostgreSQL 权威数据。Codex CLI-like output/Trace 的完整记录可以使用 append-only 文件作为日志型归档，但任务状态、未读状态和列表摘要不得依赖这些文件作为权威来源；`/api/tasks/<id>/transcript` 与 `/api/tasks/<id>/output` 必须能分页重建完整历史，不得因为热状态裁剪而丢失早期 trace。热 task JSON 只保留可配置窗口以保证 `/health` 、`/api/tasks` 和 PostgreSQL flush 不被长任务拖死；主 server 为 Code Queue 放宽到 600M 容器预算后仍默认 `CODE_QUEUE_IN_MEMORY_OUTPUT_RECORDS=10` 、`CODE_QUEUE_IN_MEMORY_EVENT_RECORDS=10` ，启动时必须在 PostgreSQL 查询侧裁剪 hot output/events，并只 flush dirty task，禁止启动后无条件重写全量历史 task JSON；更高预算才允许调大热窗口。WebUI 必须支持多 queue 查看、显式创建 queue、提交时下拉选择 queue、提交时下拉选择执行 Provider，并支持把已创建且非 active 的任务移动到其他 queue； `CODE_QUEUE_MAX_ACTIVE_QUEUES` 仅作为显式配置的全局 active slot 上限，`0` 表示不按 queue 数量限流，内存不足时由 cgroup memory pressure 阻止新 run 并在任务响应中暴露 `QUEUED(MEM LIMIT)` 。Code Queue 镜像必须内置 Playwright Chromium 浏览器与系统依赖，并使用 `bun --smol` 运行后端，保证队列任务能直接执行公网 frontend Playwright 回归且主进程内存可控，不得只在宿主机临时安装。日志写入 UniDesk `logs/{YYYYMMDD}/{startStamp}_{YYYYMMDD}_{HH}_code-queue.jsonl` ，按小时切片并按日志族默认保留 `1GiB` ； `logs_*.sqlite` 只能作为短暂缓冲，必须由 Code Queue 周期性导出为 `logs/{YYYYMMDD}/{startStamp}_{YYYYMMDD}_{HH}_codex-app-server.jsonl` ，导出后删除/压缩已导出的 SQLite 行，避免重新形成 `logs_2.sqlite` 大文件；`/logs` 端点返回最近结构化日志。`/health` 的 `queue.storage.primary` 必须恒为 `postgres` ，并通过 `queue.storage.postgresReady` 、`queue.devReady` 和 `/api/dev-ready` 暴露 PostgreSQL 可用性、develop-ready 自检、必需工具、Docker socket、`docker compose` 、默认工作目录、Codex config 状态和 `/root/.ssh` 共享 SSH key 状态。Codex CLI-like 输出可能很大，服务必须节流状态持久化，禁止对每个 output delta 同步重写完整 state 导致 `/health` 和控制 API 卡死；容器 healthcheck 必须使用带超时的 HTTP 探针，不能留下堆积的无超时探针进程。
- 状态与日志：`main-server` 默认工作目录为容器内 `/root/unidesk` ，该路径映射主 server 的 `~/unidesk` ；同时保留 `/workspace` 映射以兼容历史任务。非主 server Provider 的任务默认工作目录为 `/home/ubuntu` ，任务 JSON、列表、Trace 摘要和 CLI 查询都必须显示 `providerId` 、 `executionMode` 与最终 `cwd` 。 `executionMode=default` 沿用主 server 本机 Codex 或远程执行容器 Codex； `executionMode=windows-native` 只允许非主 server WSL Provider、Codex 模型和 `/mnt/<drive>` 工作目录，Code Queue 仍会启动远程执行容器，但容器只运行 stdio relay，经 WSL bridge 调用 Windows 宿主原生 `codex app-server --listen stdio://` ，避免公网/main-server 到 Provider 的临时断连直接杀死 Windows Codex 进程 。Code Queue 的任务、queue、`readAt` /未读状态、attempt、judge、`promptHistory` 、active session 元数据、控制状态和 ClaudeQQ 通知 outbox 一律以主 PostgreSQL 为权威，分别写入 `unidesk_code_queue_tasks` 、`unidesk_code_queue_queues` 与 `unidesk_code_queue_notifications` ； `DATABASE_URL` 是必需配置，服务不得在 PostgreSQL 缺失或不可用时进入文件存储模式。`.state/code-queue/state.json` 不再作为任务或 queue 状态存储，不得重新引入本地 JSON fallback；服务启动必须以 PostgreSQL 为唯一来源恢复队列，并把 running/judging 任务恢复为 retry_wait。主 server 内存很少，Code Queue 必须把“内存是稀缺资源”作为核心设计约束：历史任务列表、详情、统计和只读 Trace 查询优先从 PostgreSQL 直读，进程内只保留当前 running/judging、queued、retry_wait 等调度必需热任务，不得把全部历史 task JSON 长期缓存到 Bun 堆；需要短期热缓存时必须有严格上限、可裁剪、可从 PostgreSQL 和 append-only 输出归档重建。WebUI 不得用 browser `localStorage` 、`sessionStorage` 或 IndexedDB 持久化 task/queue/readAt/unread 等业务状态；浏览器只能保留临时 UI 内存缓存，刷新后必须重新从后端读取 PostgreSQL 权威数据。Codex CLI-like output/Trace 的完整记录可以使用 append-only 文件作为日志型归档，但任务状态、未读状态和列表摘要不得依赖这些文件作为权威来源；`/api/tasks/<id>/transcript` 与 `/api/tasks/<id>/output` 必须能分页重建完整历史，不得因为热状态裁剪而丢失早期 trace。热 task JSON 只保留可配置窗口以保证 `/health` 、`/api/tasks` 和 PostgreSQL flush 不被长任务拖死；主 server 为 Code Queue 放宽到 600M 容器预算后仍默认 `CODE_QUEUE_IN_MEMORY_OUTPUT_RECORDS=10` 、`CODE_QUEUE_IN_MEMORY_EVENT_RECORDS=10` ，启动时必须在 PostgreSQL 查询侧裁剪 hot output/events，并只 flush dirty task，禁止启动后无条件重写全量历史 task JSON；更高预算才允许调大热窗口。WebUI 必须支持多 queue 查看、显式创建 queue、提交时下拉选择 queue、提交时下拉选择执行 Provider 和执行模式 ，并支持把已创建且非 active 的任务移动到其他 queue； `CODE_QUEUE_MAX_ACTIVE_QUEUES` 仅作为显式配置的全局 active slot 上限，`0` 表示不按 queue 数量限流，内存不足时由 cgroup memory pressure 阻止新 run 并在任务响应中暴露 `QUEUED(MEM LIMIT)` 。Code Queue 镜像必须内置 Playwright Chromium 浏览器与系统依赖，并使用 `bun --smol` 运行后端，保证队列任务能直接执行公网 frontend Playwright 回归且主进程内存可控，不得只在宿主机临时安装。日志写入 UniDesk `logs/{YYYYMMDD}/{startStamp}_{YYYYMMDD}_{HH}_code-queue.jsonl` ，按小时切片并按日志族默认保留 `1GiB` ； `logs_*.sqlite` 只能作为短暂缓冲，必须由 Code Queue 周期性导出为 `logs/{YYYYMMDD}/{startStamp}_{YYYYMMDD}_{HH}_codex-app-server.jsonl` ，导出后删除/压缩已导出的 SQLite 行，避免重新形成 `logs_2.sqlite` 大文件；`/logs` 端点返回最近结构化日志。`/health` 的 `queue.storage.primary` 必须恒为 `postgres` ，并通过 `queue.storage.postgresReady` 、`queue.devReady` 和 `/api/dev-ready` 暴露 PostgreSQL 可用性、develop-ready 自检、必需工具、Docker socket、`docker compose` 、默认工作目录、Codex config 状态和 `/root/.ssh` 共享 SSH key 状态。Codex CLI-like 输出可能很大，服务必须节流状态持久化，禁止对每个 output delta 同步重写完整 state 导致 `/health` 和控制 API 卡死；容器 healthcheck 必须使用带超时的 HTTP 探针，不能留下堆积的无超时探针进程。
- ClaudeQQ 通知：Code Queue 可通过 backend-core 的 `claudeqq` 用户服务代理调用 `POST /api/push/text` ，在每个任务进入 `succeeded` 、`failed` 或 `canceled` 终态后向配置目标发送最终 response，并附带 task id、queue、状态、模型、attempt、当前 running/queued/retry_wait 数和任务总耗时；当所有 queue 进入 `0 running / 0 queued` 空闲态时，必须单独发送一次空闲提醒。通知由 `CODE_QUEUE_NOTIFY_CLAUDEQQ_ENABLED` 控制，目标由 `CODE_QUEUE_NOTIFY_CLAUDEQQ_TARGET_TYPE=private|group` 、`CODE_QUEUE_NOTIFY_CLAUDEQQ_USER_ID` 、`CODE_QUEUE_NOTIFY_CLAUDEQQ_GROUP_ID` 配置，默认私聊 `645275593` ；代理基址、最终 response 最大字符数、单次超时和发送尝试次数分别由 `CODE_QUEUE_NOTIFY_CLAUDEQQ_BASE_URL` 、`CODE_QUEUE_NOTIFY_CLAUDEQQ_MAX_RESPONSE_CHARS` 、`CODE_QUEUE_NOTIFY_CLAUDEQQ_TIMEOUT_MS` 和 `CODE_QUEUE_NOTIFY_CLAUDEQQ_SEND_ATTEMPTS` 配置。任务终态和队列空闲通知必须先写入 PostgreSQL outbox 表 `unidesk_code_queue_notifications` 再异步发送；不得使用 `.state/code-queue/claudeqq-notifications.json` 、`CODE_QUEUE_NOTIFY_CLAUDEQQ_OUTBOX_PATH` 或任何本地 JSON 作为通知权威存储。发送失败、NapCat 离线、代理 502 或容器重启时不能丢通知，必须按 `CODE_QUEUE_NOTIFY_CLAUDEQQ_RETRY_INTERVAL_MS` 指数退避重试并跨进程/容器重启保留。`/health` 的 `queue.notifications.claudeqq` 必须暴露非敏感配置、目标配置状态和 PostgreSQL outbox 统计；`GET /api/notifications/claudeqq` 返回 outbox 明细，`POST /api/notifications/claudeqq/drain` 手动触发发送，`POST /api/notifications/claudeqq/backfill` 可按 `since` 补入某次故障窗口内已终态任务，确保 QQ/NapCat 超时或离线不会让任务完成通知永久丢失。
- OA 接入：Code Queue 后端通过 `OA_EVENT_FLOW_BASE_URL=http://oa-event-flow:4255` 发布每个 TraceView 可见执行行的 `trace-step-created` 、幂等种子/乱序校正用 `trace-stats-snapshot` 、`task-updated` 和 queue 事件；服务启动或手动 backfill 时必须用相同 `eventId` 幂等回放历史 TraceView 可见执行行，避免历史任务停留在旧 STEP 统计口径。前端通过 `oa-event-flow` 的 `service:code-queue` tag stream 更新 STEP 和 Trace Summary， `STEP` 表示 TraceView 可见执行行数 ，工具调用数必须由 `readCount+editCount+runCount` 展示，不能复用 `stepCount` 。
- OA 接入：Code Queue 后端通过 `OA_EVENT_FLOW_BASE_URL=http://oa-event-flow:4255` 发布每个 TraceView 可见执行行的 `trace-step-created` 、幂等种子/乱序校正用 `trace-stats-snapshot` 、`task-updated` 和 queue 事件；服务启动或手动 backfill 时必须用相同 `eventId` 幂等回放历史 TraceView 可见执行行，避免历史任务停留在旧 STEP 统计口径。前端通过 `oa-event-flow` 的 `service:code-queue` tag stream 更新 STEP 和 Trace Summary， `STEP` 表示 TraceView 可见且非 system 的执行行数；system 行可保留在任务原始输出/数据库中，但默认不展示、不计入 STEP ，工具调用数必须由 `readCount+editCount+runCount` 展示，不能复用 `stepCount` 。
- 代理路径：只允许 `/health` 、`/logs` 和 `/api/` 前缀；允许方法为 `GET` 、`HEAD` 、`POST` 、`DELETE` 、`PATCH` 。Code Queue 只在 Compose 内网暴露 `4222/tcp` ，不得映射或开放到公网。
- UniDesk 前端：`用户服务 / Code Queue` React 页面负责展示队列卡片、任务 ID、复制任务 ID、引用按钮、任务耗时、默认模型、模型下拉、执行 Provider 下拉、Provider 对应默认工作目录、显式入队份数、引用任务 ID、清空输入、创建成功提示、MiniMax judge 状态、Codex CLI-like 输出流、attempt 终态、追加 prompt、打断和手动重试控件；整个 agent loop 消息流统一命名为专有名词 `Trace` ， `Trace` 包含 assistant message、user prompt、system event 和 tool call； `src/components/frontend/src/trace.tsx` 的 Trace 公共组件、统一 Trace item 接口和 codex/opencode port 适配层；连续 read/edit/run 工具调用只是在 Trace 内折叠为可展开工具调用组，汇总格式至少包含 `xx read, xx edit, xx run` ，并展示读取文件、编辑文件、运行命令和耗时摘要；最近 3 个工具调用保持展开，工具调用内容不得自动换行且必须在工具调用块内部横向滚动，工具调用组展开后不得再增加额外左侧缩进；message 与 prompt 必须自动换行，普通 message 不显示左侧项目符号缩进且永不折叠；点击队列卡片引用按钮必须自动把该任务 ID 写入提交表单的引用任务 ID 输入框；引用任务 ID 创建新任务时必须自动注入 `bun scripts/cli.ts codex task <taskId>` 的提示，让 Codex 读取初始 prompt、最后消息和工具摘要后继续；连续执行同一 prompt 应使用 `入队份数` 一次性生成多条队列任务，而不是依赖快速连点按钮；左侧 queue/session 卡片的 `QUEUED` 状态必须显示原因，例如 `QUEUED(PREV TASK)` 、`QUEUED(MEM LIMIT)` 、`QUEUED(ACTIVE LIMIT)` ；原始任务 JSON 只能通过显式 `查看原始JSON` 打开。
- UniDesk 前端：`用户服务 / Code Queue` React 页面负责展示队列卡片、任务 ID、复制任务 ID、引用按钮、任务耗时、默认模型、模型下拉、执行 Provider 下拉、执行模式下拉、 Provider/模式 对应默认工作目录、显式入队份数、引用任务 ID、清空输入、创建成功提示、MiniMax judge 状态、Codex CLI-like 输出流、attempt 终态、追加 prompt、打断和手动重试控件；选择 `windows-native` 时应优先切到支持 Windows 原生 Codex 的非主 server Provider，并把工作目录提示切到 `/mnt/<drive>` 默认路径； 整个 agent loop 消息流统一命名为专有名词 `Trace` ， `Trace` 包含 assistant message、user prompt、system event 和 tool call； `src/components/frontend/src/trace.tsx` 的 Trace 公共组件、统一 Trace item 接口和 codex/opencode port 适配层；连续 read/edit/run 工具调用只是在 Trace 内折叠为可展开工具调用组，汇总格式至少包含 `xx read, xx edit, xx run` ，并展示读取文件、编辑文件、运行命令和耗时摘要；最近 3 个工具调用保持展开，工具调用内容不得自动换行且必须在工具调用块内部横向滚动，工具调用组展开后不得再增加额外左侧缩进；message 与 prompt 必须自动换行，普通 message 不显示左侧项目符号缩进且永不折叠；点击队列卡片引用按钮必须自动把该任务 ID 写入提交表单的引用任务 ID 输入框；引用任务 ID 创建新任务时必须自动注入 `bun scripts/cli.ts codex task <taskId>` 的提示，让 Codex 读取初始 prompt、最后消息和工具摘要后继续；连续执行同一 prompt 应使用 `入队份数` 一次性生成多条队列任务，而不是依赖快速连点按钮；左侧 queue/session 卡片的 `QUEUED` 状态必须显示原因，例如 `QUEUED(PREV TASK)` 、`QUEUED(MEM LIMIT)` 、`QUEUED(ACTIVE LIMIT)` ；原始任务 JSON 只能通过显式 `查看原始JSON` 打开。
## D601 User Services
Codex