@deepseek-harness-tui/dsh-tui 0.13.0 → 0.14.0

package/guide/dsh-tui-guide/codex-backend.md

@@ -0,0 +1,257 @@
+# Codex 原生后端（实验性）
+
+[文档索引](README.md) · [English](codex-backend.en.md) · [多后端架构](agent-backend-design.md)
+
+dsh-TUI 可以作为你本机 Codex 的前端：界面不变，会话由 `codex app-server` 驱动，
+而不是由 DSH 智能体或一个通用 OpenAI API 适配器驱动。Codex 自己加载配置、登录、
+`AGENTS.md`、skills、hooks 与 MCP；thread 与官方 CLI 共用，不需要迁移历史。
+`dsh-tui migrate codex` 是另一件事：它把历史导入 **DSH**，不是打开原生 Codex thread。
+
+> 本文描述当前开发分支，不表示已发布。协议验证基线为 **codex-cli 0.160.1**，最低
+> **0.144.0**；其他版本可能有 drift 提示，最低版本并不保证每项进阶接口都可用。
+> 控制面、会话生命周期与进阶能力按实际能力声明提供。协议/假 app-server 回归与
+> 无凭据离线检查不等于真实 ChatGPT 登录、真实模型回合或真实 TTY 验证；本轮这些
+> 真实路径未运行。已验证范围单列于文末，实施与实测记录见[施工日志](codex-backend-progress.md)。
+
+## 安装与启动
+
+先按[安装说明](getting-started.md)安装 dsh-TUI，再安装你自己的 Codex：
+
+```sh
+npm install -g @openai/codex@0.160.1
+codex --version
+dsh-tui --backend codex
+```
+
+- dsh-TUI 不捆绑 Codex 二进制，也不要求安装 `@openai/codex-sdk`。
+- 默认从 `PATH` 找 Codex；`CODEX_EXECUTABLE` 可指定可执行文件。Windows 的 npm
+  安装会解析到真正的 `codex.exe`，不要把启动包装脚本当成二进制。
+- 启动页「内核」或会话里的 `/kernel` 也能选择 Codex；选择会被记住。一个进程只用
+  一个后端，切换需要重启，不能在回合进行中切换。也可在 dsh-tui 配置行写
+  `backend: codex`，或设置 `DSH_TUI_BACKEND=codex`；显式启动选项优先于记住的选择。
+- 仍使用你的 `$CODEX_HOME`（默认 `~/.codex`）和官方配置。dsh-TUI **不写
+  `~/.codex/config.toml`**；自己的模型、effort、权限等选择保存在
+  `~/.dsh-tui/backends/codex/prefs.json`，按 thread 请求应用。
+- 后端标识/标题显示 Codex。品牌档 `auto`（默认）时整套换薰衣草紫：CODEX 大标题、
+  "Build anything with Codex" 标语与 `codex-lavender`/`codex-paper` 双主题（黑白基底 +
+  紫色点缀，随终端深浅自动落位）；`/theme` 手选或 `dsh-tui.brand` 固定档不被覆盖。
+  立绘槽固定淡紫恶魔精灵（`assets/codex-girl/`，Kitty/Sixel 真图渲染；点击切换
+  「按下红色按钮」变体几秒后自动回落；协议不可用时回落字符画）。
+
+恢复官方或 dsh-TUI 建立的 thread：
+
+```sh
+dsh-tui --backend codex --resume <thread-id>
+dsh-tui --backend codex --resume   # 本机 dsh-TUI 最近使用的 Codex thread
+codex resume <thread-id>           # 换回官方前端（先退出占用它的进程）
+```
+
+恢复失败会明确报错，不会悄悄另开新会话。恢复默认沿用 thread 原来的工作目录。官方
+选择器可能按当前目录与默认 provider 过滤；看不到时改看全部目录/provider，或直接用 id。
+同一 thread 不能同时被两个 Codex 写进程打开。官方前端退出后，后台 app-server 仍可能
+保留写入锁；使用原生凭据恢复时，dsh-TUI 会尝试通过官方 `app-server proxy` 重连该服务
+中已经加载的**空闲** thread，沿用后台服务自身的配置与登录，并恢复原来的历史和目录。
+退出 dsh-TUI 会断开代理连接，后台服务继续运行。
+
+进行中的回合或审批、托管订阅令牌以及显式 `/channel` 连接仍保留占用保护；后两者使用
+独立 app-server，不会把凭据注入共享后台服务。后台服务未运行、代理不可用或未持有目标
+thread 时，恢复保留原来的错误，不会启动后台服务或另开新会话。仍提示“已有活动写入者”
+时，先在持有该会话的前端结束操作；不要删除锁文件或终止不属于你的进程。
+
+## 登录与凭据
+
+### 选用顺序
+
+1. **激活的 `/channel` 渠道连接**：使用该渠道的 Responses API 与 key，不注入订阅令牌。
+2. **dsh-auth 的 `openai-codex` ChatGPT 订阅登录**：仅在确定是第一方 OpenAI 路由时，
+   以官方 `chatgptAuthTokens` 外部托管模式交给 app-server。传给 Codex 的令牌仅在
+   内存中，不写 Codex 的 `auth.json`，刷新由 app-server 反向请求。
+3. **你已有的原生 Codex 凭据**：由 Codex 自己读取 `$CODEX_HOME` 的凭据文件/钥匙串、
+   环境变量与 provider 配置。dsh-TUI 不复制、更改或重新解释它们。
+4. 都没有时仍可打开界面，但模型调用前需要 `/login`。
+
+订阅令牌不会发给中转站：自定义 `model_provider`、被改写的 provider base URL、
+指向非官方主机的 `OPENAI_BASE_URL` 或无法读取的配置都会阻止注入；环境原样交给 Codex。非第一方
+路由应使用自己的 provider 凭据或渠道 key。读取账户状态只显示凭据来源、订阅类型
+与主机，不显示邮箱或 key。
+
+### `/login` 的三种方式
+
+| 方式 | 用途与存储 |
+| --- | --- |
+| 内置 ChatGPT OAuth | 使用标准 profile 的 dsh-auth 登录向导；没有该 OAuth 服务时不显示这项。凭据由 dsh-auth 管理，给 Codex 的外部令牌不落到 Codex 凭据文件 |
+| Codex 设备码 | 按界面给出的验证链接与一次性代码在浏览器完成登录；由 Codex 自己管理原生登录存储，可在界面取消等待 |
+| OpenAI API key | 在保密输入框填写；**会写入你自己的 Codex 凭据存储**，不是临时内存 key。想使用中转 key 应在 `/channel` 配置，不要用这项冒充第一方登录 |
+
+登录是否成功以服务端结果为准，不能把 `account/login/start` 的即时应答当成成功。
+刷新或托管令牌失败会提示 `/login` 并停止注入；**不会调用 `account/logout`，不会
+删除你已有的原生 Codex 登录**。`/logout` 只调用宿主 OAuth 服务，移除对应
+`openai-codex` 的 dsh-auth 存储；不会删除渠道 key、其他 provider 或原生登录。
+现有 app-server 可能仍缓存已载入的托管令牌，**需要正常重启 dsh-TUI 后停止使用**；
+登出不会自动中断会话、重连或修改官方配置。需要管理原生登录时，在自己的外部终端
+使用官方 Codex。
+
+在第三方客户端使用 ChatGPT 订阅令牌受 OpenAI 条款约束；外部托管是官方 app-server
+接口，不代表本项目保证所有订阅/工作区都允许第三方前端。没有真实账号验证的登录
+路径不能视为已验证；有顾虑可使用 API key。不要把凭据或账户信息贴进 issue、日志或文档。
+
+## 中转渠道：`/channel`
+
+渠道只支持 **OpenAI 兼容 Responses API**（`wireApi: responses`），不支持把
+Chat Completions 端点当作 Responses 使用。通过 `/channel` 选择/新建渠道、设置连接
+和模型 exact 映射；也可从当前 Codex provider 设置导入（可读取对应环境 key 时）。
+模型名映射是精确替换，不是 Claude 的模型 tier。
+
+- 元数据在 `~/.dsh-tui/backends/codex/channels.json`，文件只存 `tokenRef`；key 在
+  DSH 凭据库，不写进该 JSON。不要把 key 塞进 `env` 或 URL。
+- base URL 只接受 HTTPS；HTTP 仅限 `localhost` 和 `127.0.0.1`。拒绝用户名/密码、
+  查询参数、fragment，以及 `sk-`、`key=`、长随机串等像凭据的路径段。
+- provider 定义通过 `codex app-server -c ...` 的进程参数传递，key 只在子进程环境。
+  **端点主机名和非敏感 provider 参数可能被本机其他用户在进程列表看到**；环境
+  也不是防管理员的秘密存储。只使用可信的本机与端点。
+- 激活的连接不完整、缺 key 或 URL 不安全时会拒绝启动，不会偷偷退回订阅登录。
+- 渠道登录与 ChatGPT 登录不要混用；激活连接时 `/login` 会提示先处理渠道。切换
+  连接会按界面提示重启，以新的 provider/凭据环境恢复当前 thread，不中断正在进行的
+  回合；只改模型映射的档案切换可不重启。不要在运行中改连接。
+
+## 模型、思考强度、Plan 与权限
+
+`/model` 列出 Codex 报告的模型与渠道映射；`/effort` 只给出当前模型实际支持的档位，
+不是每个模型都有 `xhigh`。选择模型时会处理不兼容的 effort；默认 effort 交给模型。
+空闲时设置立即更新，运行中的改动用于下一回合，不改变已开始的推理。
+
+**协作模式和权限是两个正交维度**。`/permission` 复用现有选择器：
+
+| 项 | 审批与沙箱 |
+| --- | --- |
+| Read Only / 只读（`read-only`） | 按需审批、只读沙箱 |
+| Default / 默认（`auto`） | 按需审批、工作区可写沙箱 |
+| Full Access / 完全访问（`full-access`） | 不询问、无文件沙箱；仅在明确选择时进入 |
+| Plan（`plan`） | 规划协作模式；保留已有权限档，不以 Plan 替代沙箱 |
+
+- **`Shift+Tab` 只开/关 Plan**，退出回到进入前的权限档，不循环到 Full Access。
+- `/plan` 切到 Plan；`/plan <任务>` 切换后立刻提交任务。选择一个具体权限档会回到
+  Default 协作模式。Plan 不等于“所有工具都被禁止”，安全边界仍由 Codex 权限决定。
+- 默认来源按字段为：dsh-TUI 中明确选过的值 > 用户 Codex 配置 > 未设置时的
+  `auto`。读取配置失败时不拿 `auto` 覆盖未知配置。
+- 计划完成后会出现实施确认：实施、清上下文后实施、留在规划/反馈继续。清上下文
+  的路径以新 thread 继续，原 thread 保留；批准计划不会暗中打开 Full Access。
+- 命令、文件改动、网络/权限请求由 Codex 给出的选项驱动；允许本次、会话内允许、
+  记住规则等选项只在服务端支持时出现。问卷与 MCP 表单共用现有面板，保密答案掩码。
+
+## 日常命令与输入
+
+| 入口 | 行为 |
+| --- | --- |
+| 工作时 `Enter` / `Tab` / `Ctrl+Enter` | 插话（steer）/ 排队下一回合 / 打断并立即发送；不可 steer 时退为排队 |
+| `Esc` / `Ctrl+C` | 按当前焦点关闭面板或中断；取消提问也会中断相应回合，避免挂起 |
+| `/review` | 审查未提交改动，结果 inline 展示；需要空闲，消耗模型用量 |
+| `/review base <branch>` / `/review commit <sha>` | 按分支基线或提交审查；其他参数作为自定义审查说明 |
+| `/diff` | 最近回合的聚合 diff；没有时尝试相对远端的 Git diff，再无内容则提示 |
+| `/<skill-name> [参数]` | 使用 Codex 发现且启用的 skill；补全随 skills 变化刷新，本地同名命令优先 |
+| `/init` | 提交 Codex 的 AGENTS.md 初始化提示，不走 DSH 的模板生成器；这是模型回合，仍需审批/用量 |
+| `/mcp` | 查看 Codex MCP 服务器状态与工具数，支持 reconnect，不提供运行时 toggle |
+| `/usage` | 服务端额度窗口、使用百分比、重置时间与 credits；中转站可能不提供 |
+| `/status`、`/context`、`/compact` | 状态、上下文原始读数、Codex 压缩；没有分类明细时不会编造 |
+| `/new`、`/clear`、`/export` | 新 thread、仅清视图、导出当前转录；`/clear` **不重置上下文** |
+| `!cmd` / `!!cmd` | dsh-TUI 的本地 shell / 把输出作为后续消息带入上下文；不是直接照搬官方 `!` 的持久化语义 |
+
+文件工具卡显示真实 hunk 行号；命令卡在运行中显示有界实时输出尾部。按 `Ctrl+O`
+展开详情。历史中的官方 `userShell` 回合也会显示为终端卡。
+
+### 上下文与额度的读法
+
+上下文条使用官方 12,000-token 基线公式（`T` 是最近一次 `last.totalTokens`，不是
+全会话累计计费用量；`W` 是模型窗口）：
+
+```text
+effective = max(0, W - 12000)
+used      = max(0, T - 12000)
+占用比例   = used / effective       # effective > 0 时
+剩余比例   = 1 - 占用比例
+```
+
+显示会处理未知/无效窗口；`/context` 明细保留原始 `T / W`。账本 tokens、订阅额度
+与上下文占用是不同量，不能相互代替。Codex 转录通常不保存完整计费用量，恢复历史
+不会凭空重建先前所有 tokens/费用；等待新的用量通知更新。
+
+## 会话生命周期
+
+- `/resume` 打开原生 thread 浏览器，按项目分组，也可看全部项目。`Enter` 恢复、
+  `Ctrl+R` 改名、`Ctrl+D` **归档**；确认和完成提示都说明记录保留，不物理删除。
+  当前使用中、其他终端占用或内部 worker 活动的 thread 不能归档。目录最多列出
+  最近 500 条普通 thread，临时 fork 与子 thread 不混进主列表。
+- `/rename` 改官方 thread 标题；`/color` 只保存会话强调色，不改全局主题。
+- `/fork` 创建可恢复副本，不自动切换；双击 `Esc` 或 `/rewind` 的对话回退在
+  所选提问之前创建副本并继续，提问回到输入框、原 thread 保留。首条提问回退会
+  得到空 thread。**不支持文件回退或对话+文件回退**，Git 工作树不会随对话恢复。
+- 恢复先回放最近 20 个完整回合，再接 live；加载更早消息使用预取的完整分页，
+  不拿省略工具项的 summary 当全转录。预取尚未就绪时可再试一次，连续失败会提示。
+  运行中的恢复会去重重发审批；历史没有的完整用量不伪造。
+
+## 图片
+
+粘贴图片或 `@` 引用 PNG/JPEG/GIF/WebP 文件随消息发送。每张最多 **20 MiB**、
+每边最多 **2048** 像素、最多 **2048 × 2048** 像素；每条最多 **20 张**、合计
+**50 MiB**。暂存层按能力限制校验，发送前再次读图检查；超限按提示缩小图片，
+不要假设 Codex 自动处理了未成功发送的附件。
+
+输入发成 data URL 随 thread 持久化，不依赖会被清理的剪贴板临时路径。恢复会显示
+持久化的输入图片；历史 localImage 文件丢失则显示不可用占位，不自动下载远端图片。
+Codex 的 imageView/已完成 imageGeneration 也会显示图片：生成结果优先读
+`savedPath`，没有路径才读内嵌结果。真实模型看图与生成图像尚未在本轮验证。
+
+## 子代理与后台任务
+
+- `/agents` 或 `Ctrl+A` 打开子代理面板。子 thread 文本、工具与用量进入其卡片/
+  详情，不混进主对话；详情按需分页读取，可中断自己会话下正在工作的子代理。
+- 可给子代理发消息，但采用 **parent-mediated**：由父模型通过 Codex 的
+  `send_input` 转达，不是直接操纵子代理 inbox。发送回执表示已发起（issued），
+  不保证子代理已读或已执行；跨父会话的详情/中断会被拒绝。
+- `/jobs` 显示 Codex unified-exec 留下的后台终端，可用现有任务停止控件结束。
+  回合开始/结束刷新名册，发现存活终端后约每 **2 秒**轮询；这是实验接口，缺方法
+  时能力关闭并提示，不假装后台进程已完成。
+- 输出是本会话已观察到的**最后 64 KiB**尾部，不是任意历史输出文件读取。恢复
+  时未观察到输出可以显示无输出；完整名册查询证明消失后才结算。没有原生退出码
+  时完成卡的摘要注明 **exit unknown**，不能据此声称 exit 0 或命令成功。
+- 中断主模型回合与停止后台终端是不同动作；需要终止任务时用任务停止控件。
+
+## 目标、旁问与 hooks
+
+| 入口 | 行为 |
+| --- | --- |
+| `/goal` | 当前目标、状态、tokens/时间预算；数值来自 Codex 服务端 |
+| `/goal <目标>`、`/goal edit <目标>` | 创建或替换原生目标 |
+| `/goal --budget 50k <目标>` | 设置 token 预算（也接受 50000、1.5m） |
+| `/goal pause`、`/goal resume`、`/goal clear` | 暂停、继续、清除目标；不复制 DSH 的自动轮次循环 |
+| `/btw <问题>`、`/recap` | 临时 fork 的旁问/回顾，一次模型调用，不写主 thread 或持久会话列表 |
+| hooks | hookPrompt 作为注入消息；开始/完成/失败以通知呈现，沿用 Codex 配置而非 DSH `/hooks` 管理器 |
+
+目标遇 usageLimited/budgetLimited 会显示阻塞与原因；不支持目标接口的版本不会
+声明该能力。`/btw`/`/recap` 以只读沙箱、禁止审批提升运行，要求仅回答并拒绝
+工具/审批请求；取消会中断临时回合并卸载 fork。它们仍消耗模型额度，不是免费本地
+摘要。临时 fork 的创建/非持久行为已离线检查，真实旁问模型结果未在本轮验证。
+
+## 限制与排障
+
+- `/skills`、`/hooks` 是 DSH 管理入口，不等于 Codex 自己的技能/钩子管理。Codex
+  skills 用菜单中的 `/<skill-name>`；不要把不支持的本地命令当成可透传给模型。
+- DSH 的 preset、provider、工作区首页、迁移管理与 `/tree` 等不是 Codex 能力。
+  不支持的命令会被标不可用，不会静默执行。
+- 本期不增加官方所有 slash 别名，也不实现 Codex 的语音、apps/plugins 管理、
+  worktree/daemon、宠物、memories、远程控制或物理删除。主题/宠物继续用 dsh-TUI
+  现有设置，不为“原生兼容”改配色。
+- `/doctor` 可核对二进制版本/路径、drift、Codex home、凭据来源、provider 主机、
+  沙箱问题与协议未知项。Linux 缺 bubblewrap 时按提示安装并保留需要的沙箱，不要
+  仅为消除报错就选 Full Access。操作系统沙箱行为由官方 Codex 决定。
+- 401/登录失败：检查当前渠道和路由后 `/login`；额度超限看 `/usage`；窗口超限
+  先 `/compact`；“active writer”先退出另一终端的会话。
+- app-server 退出会提示重连；重连失败后会话保留为只读，不假装消息已送达。
+- bug 报告只带版本、平台、最短步骤和脱敏诊断。会话导出、原始 ANSI/debug 日志
+  可能包含正文、文件路径与机密，不应直接公开。
+
+## 本轮验证范围
+
+- 真实官方 0.160.1 app-server 在隔离 home 下 9 项离线检查通过：握手/隔离 home、新建 thread、模型列表、零上下文读数、权限与 Plan 正交、改名持久化、临时 fork、完整页恢复、归档。没有模型回合，不收费，不写用户的 ~/.codex/config.toml。
+- 协议/映射、控制面、生命周期与进阶接口用假 app-server 和脱敏 fixture 回归；归档/普通删除的真实无头浏览器与宿主 OAuth-only 登出也有聚焦回归。它们验证接线、状态与安全边界，不等于真实服务端已经接受所有账号/模型请求。
+- 本轮未运行：真实 ChatGPT OAuth/设备码/API-key 登录、带凭据模型回合、真实图片/子代理/后台终端/goal/旁问回合，以及真实 TTY 的 inline/fullscreen/窄终端操作。凭据缺失或没有交互终端时不把跳过写为通过；详细结果见施工日志。

package/guide/dsh-tui-guide/configuration.en.md

@@ -70,8 +70,12 @@ A complete common override looks like this:
 | `sidePanel.splitEnabled` | `true` (boolean) | Master switch of the split layout: on, `Ctrl+B` and `/panel` open the side column next to the chat; off, neither splits and `/jobs` & co. keep their full-screen panels. Applies immediately |
 | `sidePanel.open` | `false` (boolean) | Whether a session opens with the sidebar already expanded; off by default, so the upgrade leaves the layout as it was. An in-session `Ctrl+B` / `/panel toggle` is not written back here. Applies immediately |
 | `sidePanel.ratio` | `0.68` (number, 0.1–0.95) | Chat column as a fraction of the content width; while the panel has focus, `+`/`-` nudge it live for the current session (not written back). Applies immediately |
-| `sidePanel.panels` | `todo,jobs,agents` (comma-separated text) | Enabled panel ids and their order (built-ins: `todo` `info` `trajectory` `jobs` `agents` `workspace` `companion`); a well-formed id no panel claims yet stays in the tab bar for a plugin to register later, a malformed entry is refused. The `⤢` on the right edge of the bar blows the active panel up to full screen (drawn only for panels that declare a fullscreen form). Applies immediately |
- | `companion.skin` | `deepy` | Skin of the companion-panel pet: `deepy` (default, the deepy whale kit), `whaleGirl` (the whale-girl sticker pack, 22 animations incl. interaction reactions) or `whale` (the splash's layered pixel whale); the panel itself is enabled by adding `companion` to `sidePanel.panels`. Applies immediately |
+| `sidePanel.panels` | `todo,jobs,agents,info,trajectory,workspace,btw,companion` (comma-separated text) | All eight built-in panels are enabled by default; this controls their ids and order. A well-formed id no panel claims yet stays in the tab bar for a plugin to register later; a malformed entry is refused. The `⤢` on the right edge of the bar blows the active panel up to full screen (drawn only for panels that declare a fullscreen form). Applies immediately |
+ | `companion.skin` | `deepy` | Skin of the companion-panel pet: `deepy` (default, the deepy whale kit), `whaleGirl` (the whale-girl sticker pack, 22 animations incl. interaction reactions) or `whale` (the splash's layered pixel whale); the panel is enabled by default and can be changed in `sidePanel.panels`. Applies immediately |
+| `btw.contextTurns` | `4` (number, 1–8) | Completed Q/A pairs a `/btw` follow-up carries; older pairs stay in the thread and panel but are not sent. Applies immediately |
+| `btw.contextBudget` | `24000` (number, 1000–200000) | Character budget for the recent Q/A pairs a `/btw` follow-up carries; the oldest pairs drop first. Applies immediately |
+| `codeFrameStyle` | `light` | Frame of fenced code blocks in replies: `light` is a top label plus a left rail and costs no extra rows; `full` closes the box. Very narrow terminals always use a plain fence. Applies immediately |
+| `turnUsageRow` | `false` (boolean) | Show a right-aligned usage row at the end of each turn (tokens in/out, cache, duration, retries); `/tokens`, `/status` and the footer hover report the same numbers either way |
 | `modes` | built-in trio | Shift+Tab session-mode cycle (plan/sandbox/approval atom bundles); defaults to default → plan → full-access |
 | `activity` | `true` | Show the live activity row |
 | `activityFrames` | `moon8` | Activity animation preset; `/activity` changes it at runtime. A legacy saved value of `claude` is read as `moon8`, and the picker no longer offers that legacy preset |
@@ -80,6 +84,7 @@ A complete common override looks like this:
 | `terminalImages` | `true` | Allow previews in supported terminals; `false` keeps text metadata and skips image probing and preview decoding. Restart to apply changes |
 | `preset` | roster default `standard` | Agent preset for new sessions; explicit configuration wins over persisted preference |
 | `sessionId` | unset | Session to resume, normally injected by the Windows `--resume` launcher |
+| `backend` | unset (the backend `/kernel` remembers, else `dsh`) | Session backend: `dsh`, or the experimental `claude` / `codex` (case-insensitive; an unknown value means `dsh`). The profile row reads `DSH_TUI_BACKEND`, which `dsh-tui --backend <id>` sets. See [Claude backend](claude-backend.en.md) |
 
 ### Precedence and force-off
 
@@ -256,6 +261,8 @@ for the complete field reference.
 | `DSH_TUI_DISABLE_TERMINAL_IMAGES` | Set to `1` to force Kitty/Sixel probing, preview reads/decoding, and terminal image rendering off, overriding config and /settings; text metadata remains visible |
 | `DSH_TUI_IMAGE_PROTOCOL` | `auto` (default), `kitty`, `sixel`, or `none`; override protocol selection without bypassing the preview preference, disable switch, non-fullscreen, accessibility or multiplexer guards |
 | `DSH_TUI_RESUME_SESSION` | Resume a session at startup, normally set by a launcher |
+| `DSH_TUI_BACKEND` | Session backend (`dsh` / `claude`), normally set by `dsh-tui --backend` |
+| `DSH_TUI_CLAUDE_PERMISSION_MODE` | Start permission mode of the Claude backend (`default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions`); wins over the mode `/permission` remembered |
 | `DSH_TUI_WORKSPACE_TARGET` | Workspace path or URI resolved at startup, normally set by `dsh-tui <target>` |
 | `DSH_TUI_SESSION_ROOT` | Override the JSONL session root; profile default `$DSH_HOME/sessions`, bare `cordis.yml` default `~/.dsh-tui/sessions` |
 | `DSH_PERMISSION_MODE` | Override non-Windows sandbox policy, such as `workspace-write` or `danger-full-access` |

package/guide/dsh-tui-guide/configuration.md

@@ -67,8 +67,12 @@ Config；旧版仍使用 `~/.dsh/settings.yaml`。不要把旧文件路径当成
 | `sidePanel.splitEnabled` | `true`（布尔） | 分栏总开关：开启时 `Ctrl+B` 与 `/panel` 在聊天右侧展开侧栏；关闭时两者都不再分栏，`/jobs` 等仍走整屏面板。立即生效 |
 | `sidePanel.open` | `false`（布尔） | 启动时侧栏是否已展开；默认关闭，升级后布局与原来一致。会话内的 `Ctrl+B` / `/panel toggle` 不写回这里。立即生效 |
 | `sidePanel.ratio` | `0.68`（数值，0.1–0.95） | 聊天列占内容宽度的比例；侧栏有焦点时 `+`/`-` 在当前会话内实时微调（不写回）。立即生效 |
-| `sidePanel.panels` | `todo,jobs,agents`（逗号分隔文本） | 启用的面板 id 与顺序（内置：`todo` `info` `trajectory` `jobs` `agents` `workspace` `companion`）；格式合法但暂无面板认领的 id 会留在标签栏等插件注册，格式非法的条目被拒绝。面板栏右端的 `⤢` 把当前面板放大成整屏（只对声明了整屏形态的面板出现）。立即生效 |
- | `companion.skin` | `deepy` | 宠物面板的皮肤：`deepy`（默认，deepy 小鲸鱼素材包）、`whaleGirl`（鲸娘表情包，22 个动画含互动反应）或 `whale`（与开屏同款分层像素鲸鱼）；面板需在 `sidePanel.panels` 加入 `companion` 启用。立即生效 |
+| `sidePanel.panels` | `todo,jobs,agents,info,trajectory,workspace,btw,companion`（逗号分隔文本） | 默认启用全部 8 个内置面板；这里控制面板 id 与顺序。格式合法但暂无面板认领的 id 会留在标签栏等插件注册，格式非法的条目被拒绝。面板栏右端的 `⤢` 把当前面板放大成整屏（只对声明了整屏形态的面板出现）。立即生效 |
+ | `companion.skin` | `deepy` | 宠物面板的皮肤：`deepy`（默认，deepy 小鲸鱼素材包）、`whaleGirl`（鲸娘表情包，22 个动画含互动反应）或 `whale`（与开屏同款分层像素鲸鱼）；面板默认启用，可在 `sidePanel.panels` 调整。立即生效 |
+| `btw.contextTurns` | `4`（数值，1–8） | `/btw` 追问时带上的最近已完成问答组数；更早的组不进请求，线程和面板里仍保留。立即生效 |
+| `btw.contextBudget` | `24000`（数值，1000–200000） | `/btw` 追问携带的最近问答总字符数上限，超出时从最旧的一组开始丢。立即生效 |
+| `codeFrameStyle` | `light` | 回复里代码块的边框：`light` 只有顶部标签和左侧竖线，不多占行；`full` 是封闭的框。终端太窄时总是用纯文本 fence。立即生效 |
+| `turnUsageRow` | `false`（布尔） | 每回合末尾显示一行右对齐的用量（输入/输出、缓存、耗时、重试）；关闭时 `/tokens`、`/status` 和底栏悬停照样能看到这些数字 |
 | `modes` | 内置三档 | Shift+Tab 会话模式循环（plan/sandbox/approval 原子组合）；缺省为 默认 → 计划 → 完全访问 |
 | `activity` | `true` | 是否显示实时工作状态行 |
 | `activityFrames` | `moon8` | 工作状态动画预设；也可通过 `/activity` 修改。旧配置值 `claude` 读取时映射为 `moon8`，选择器不再显示该旧预设 |
@@ -77,6 +81,7 @@ Config；旧版仍使用 `~/.dsh/settings.yaml`。不要把旧文件路径当成
 | `terminalImages` | `true` | 允许在支持的终端预览图片；`false` 保留文字信息，跳过图片探测与预览解码。修改后重启生效 |
 | `preset` | 名册默认 `standard` | 新会话 Agent preset；显式配置优先于持久化偏好 |
 | `sessionId` | 未设置 | 要恢复的会话 ID，通常由 Windows `--resume` 启动器注入 |
+| `backend` | 未设置（`/kernel` 记住的选择，否则 `dsh`） | 会话后端：`dsh`，或实验性的 `claude` / `codex`（不区分大小写，未知值按 `dsh`）。profile 行读取 `DSH_TUI_BACKEND`，`dsh-tui --backend <id>` 会设置它。见 [Claude 后端](claude-backend.md) |
 
 ### 优先级与强制关闭
 
@@ -229,6 +234,8 @@ Profile 模式不再使用旧的 `DSH_TUI_COMPACT_RATIO`、`DSH_TUI_COMPACT_RETA
 | `DSH_TUI_DISABLE_TERMINAL_IMAGES` | 设为 `1` 时强制关闭 Kitty/Sixel 探测、预览读取/解码与终端图片渲染，优先于 config 和 /settings；保留文字信息 |
 | `DSH_TUI_IMAGE_PROTOCOL` | `auto`（默认）、`kitty`、`sixel` 或 `none`；覆盖协议选择，但不绕过图片预览偏好、禁用开关、非全屏、无障碍和多路复用器限制 |
 | `DSH_TUI_RESUME_SESSION` | 启动时恢复指定会话，通常由启动器设置 |
+| `DSH_TUI_BACKEND` | 会话后端（`dsh` / `claude`），通常由 `dsh-tui --backend` 设置 |
+| `DSH_TUI_CLAUDE_PERMISSION_MODE` | Claude 后端的起始权限模式（`default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions`），优先于 `/permission` 记住的选择 |
 | `DSH_TUI_WORKSPACE_TARGET` | 启动时解析的工作区路径或 URI，通常由 `dsh-tui <目标>` 设置 |
 | `DSH_TUI_SESSION_ROOT` | 覆盖 JSONL 会话根目录；profile 默认 `$DSH_HOME/sessions`，裸 `cordis.yml` 默认 `~/.dsh-tui/sessions` |
 | `DSH_PERMISSION_MODE` | 非 Windows 平台覆盖 sandbox policy，例如 `workspace-write` 或 `danger-full-access` |