From 5ae67445698c7393cc06d75afe2199212bdfc018 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 15 Jul 2026 07:19:36 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20WebTerm=20?= =?UTF-8?q?=E6=8C=81=E4=B9=85=20Session=20=E5=88=9B=E5=BB=BA=E8=B7=AF?= =?UTF-8?q?=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/webterm.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/reference/webterm.md b/docs/reference/webterm.md index 7c0e6870..8d07be1f 100644 --- a/docs/reference/webterm.md +++ b/docs/reference/webterm.md @@ -22,3 +22,22 @@ - `browserOutputPolicy.maxFramesPerSecond` 是每个浏览器连接、每个终端的最大输出消息频率； - `browserOutputPolicy.maxFrameBytes` 是单条聚合输出消息的字节上限； - 后端必须按终端独立排队，小数据在频率窗口内合并，积压数据按窗口顺序发送，禁止用字节阈值绕过频率上限。 +- 持久 Codex Session 创建： + - 适用于本地 provider 的 `mycx` 与 `oncx` runtime 自动恢复标签； + - 新建必须直接调用原生 `codex app-server`，按顺序完成 `initialize`、`initialized`、`thread/start` 与 `thread/name/set`； + - `thread/start` 必须显式传入 `ephemeral=false`，并以返回的 thread ID 作为后续恢复 Session ID； + - 禁止通过附带 `--profile` 的 `mycx` 或 `oncx` 包装器启动 app-server，当前 Codex 只允许 profile 用于 runtime 命令； + - `mycx` 创建沿用默认 Codex home，`oncx` 创建必须沿用包装器声明的 `CODEX_HOME`、`CODEX_SQLITE_HOME` 和凭据环境清理规则； + - Webterm 运行在使用 `/usr/local/bin/host-shell` 的容器中时，app-server 必须通过宿主 namespace 执行原生 Codex； + - 容器与宿主工作目录分层： + - 容器进程工作目录必须使用容器内存在的目录； + - 目标工作目录只通过 `thread/start.cwd` 传给宿主 Codex； + - 禁止把仅宿主存在的路径直接作为容器 `spawn.cwd`； + - 只有 `thread/name/set` 成功后才能把 Session ID 写入 runtime 数据域，再通过 `mycx|oncx resume ` 启动终端； + - 恢复 prompt 必须作为 CLI 参数传入，禁止在 xterm 中模拟键盘输入； + - runtime 记录与 YAML 预置恢复标签必须共存，runtime 数据域不得改变 owning YAML 的预置定义。 +- 持久 Session 最小验收： + - 先执行目标的受控 `status`，确认 provider 健康和 runtime 数据域正确； + - 再从真实浏览器加号入口创建一个持久 Session，关闭标签后从恢复列表重新打开； + - 创建与恢复后的 Session ID 相同、标签为 runtime 自动恢复且终端进入 running，才判定端到端合同成立； + - 单元测试只验证 app-server 消息顺序、模式环境和宿主 namespace 启动参数，不能替代真实浏览器验收。