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

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

@@ -0,0 +1,297 @@
+# Native Codex backend (experimental)
+
+[Documentation index](README.md) · [中文](codex-backend.md) · [Agent backends](agent-backend-design.md)
+
+dsh-TUI can be a frontend for your local Codex: the same interface, with sessions driven by
+`codex app-server`, not the DSH Agent or a generic OpenAI API adapter. Codex loads its own
+configuration, login, `AGENTS.md`, skills, hooks and MCP servers. Threads are shared with the
+official CLI, with no history migration required. `dsh-tui migrate codex` is different: it
+imports history into **DSH**, rather than opening a native Codex thread.
+
+> This guide describes the development branch, not a released version. The protocol
+> validation baseline is **codex-cli 0.160.1**; the minimum is **0.144.0**. Other versions
+> may show a drift warning; the minimum does not guarantee every advanced API. Controls,
+> lifecycle and advanced features follow the capabilities actually declared by the backend.
+> Protocol/fake-app-server regressions and credential-free offline checks do not prove real
+> ChatGPT login, live model turns or real-TTY behavior; those were not run in this round.
+> The verified scope is listed at the end, with implementation/live evidence in the
+> [progress log](codex-backend-progress.md) (Chinese).
+
+## Install and start
+
+Install dsh-TUI using the [installation guide](getting-started.en.md), then install your own Codex:
+
+```sh
+npm install -g @openai/codex@0.160.1
+codex --version
+dsh-tui --backend codex
+```
+
+- dsh-TUI neither bundles the Codex binary nor requires `@openai/codex-sdk`.
+- Codex is discovered on `PATH`; set `CODEX_EXECUTABLE` to choose an executable. On Windows,
+  npm installations resolve to the real `codex.exe`, not just the launcher wrapper.
+- Select Codex through the launchpad kernel entry or `/kernel` to remember the choice. One
+  process uses one backend; switching restarts it and is unavailable during a turn. You
+  can also set `backend: codex` on the dsh-tui configuration row or use
+  `DSH_TUI_BACKEND=codex`. Explicit launch choices take precedence over the remembered one.
+- Your `$CODEX_HOME` (default `~/.codex`) and official configuration still apply. dsh-TUI
+  **does not write `~/.codex/config.toml`**. Its model, effort and permission choices live
+  in `~/.dsh-tui/backends/codex/prefs.json` and apply through per-thread requests.
+- Backend identification/title displays Codex. With the brand setting on `auto` (the
+  default) the whole look goes lavender: the CODEX title, the "Build anything with Codex"
+  tagline and the `codex-lavender`/`codex-paper` theme pair (monochrome base with lavender
+  accents, following your terminal's lightness). A manual `/theme` pick or a pinned
+  `dsh-tui.brand` value is never overridden. The portrait slot shows the lavender demon
+  sprite (`assets/codex-girl/`, rendered as a real image via Kitty/Sixel; a click swaps in
+  the red-button variant for a few seconds, with a character-art fallback when the terminal
+  cannot show images).
+
+Resume a thread created by the official client or dsh-TUI:
+
+```sh
+dsh-tui --backend codex --resume <thread-id>
+dsh-tui --backend codex --resume   # last Codex thread used by this dsh-TUI installation
+codex resume <thread-id>           # return to the official frontend; release its writer first
+```
+
+Failed resume reports an error; it does not silently create a new conversation. Resume
+uses the thread’s recorded working directory by default. The official selector may filter
+by directory and default provider; select all directories/providers or use the id directly.
+Two Codex writers cannot open the same thread concurrently. After an official frontend
+exits, its background app-server may retain the writer lock. When resuming with native
+credentials, dsh-TUI tries the official `app-server proxy` to rejoin that server's already
+loaded **idle** thread, using the background server's configuration and login while
+restoring the original history and working directory. Exiting dsh-TUI disconnects its
+proxy; the background server keeps running.
+
+Running turns, pending approvals, managed subscription tokens and explicit `/channel`
+connections retain the occupancy protection. The latter two use private app-server
+processes and never inject credentials into the shared background server. If the server
+is not running, its proxy is unavailable or it does not hold the target thread, resume
+keeps the original error without starting a daemon or creating a replacement conversation.
+If an “active writer” error remains, finish the operation in the frontend holding that
+thread; do not delete locks or terminate someone else's process.
+
+## Login and credentials
+
+### Selection order
+
+1. **The active `/channel` connection**: use its Responses API endpoint and key; do not
+   inject subscription tokens.
+2. **dsh-auth `openai-codex` ChatGPT subscription login**: only on a confirmed first-party
+   OpenAI route, through the official externally managed `chatgptAuthTokens` mode. Tokens
+   passed to Codex stay in memory, not Codex `auth.json`; app-server requests refreshes.
+3. **Your native Codex credentials**: Codex reads its own `$CODEX_HOME` credential file or
+   keychain, environment variables and provider configuration. dsh-TUI does not copy,
+   change or reinterpret them.
+4. With no credentials you can still open the UI, but need `/login` before a model call.
+
+Subscription tokens are not sent to relays. Custom `model_provider`, overridden provider
+base URLs, a non-official `OPENAI_BASE_URL`, or unreadable configuration prevent injection; the environment
+is handed to Codex unchanged. Non-first-party routes should use their own provider
+credentials or a channel key. Account status shows only credential source, subscription
+type and host, not an email address or key.
+
+### The three `/login` methods
+
+| Method | Purpose and storage |
+| --- | --- |
+| Built-in ChatGPT OAuth | Uses the standard profile’s dsh-auth login wizard; omitted if that OAuth service is absent. dsh-auth manages credentials; the external token passed to Codex is not written to Codex’s credential file |
+| Codex device code | Follow the displayed verification link and one-time code in a browser. Codex manages native login storage; cancel the wait in the UI if needed |
+| OpenAI API key | Enter it in a masked field. **It is written to your own Codex credential store**, not kept as a temporary in-memory key. Put relay keys in `/channel` instead of treating them as first-party login |
+
+Success follows the server’s login result, not the immediate `account/login/start` reply.
+Failed refresh or managed-token login prompts for `/login` and stops injection. It **does
+not call `account/logout` or delete your existing native Codex login**. `/logout` delegates
+only to the host OAuth service to remove the matching `openai-codex` dsh-auth credential.
+It does not remove channel keys, other providers or native login. The running app-server
+may retain an already-loaded managed token: **restart dsh-TUI normally to stop using it**.
+Logout does not interrupt, reconnect or modify official configuration. Manage native
+login with the official Codex client in your own external terminal.
+
+Using ChatGPT subscription tokens in third-party clients is subject to OpenAI’s terms.
+External token management is an official app-server interface, not a project guarantee
+that every subscription/workspace allows third-party frontends. Login paths without a real
+account check remain unverified; use an API key if concerned. Never post credentials or
+account information in issues, logs or documentation.
+
+## Relay channels: `/channel`
+
+Channels support an **OpenAI-compatible Responses API** (`wireApi: responses`), not Chat
+Completions endpoints. Use `/channel` to select/create a profile, configure a connection
+and exact model-name mappings. Import from the current Codex provider settings is available
+when its environment key can be read. Mappings are exact replacements, not Claude model tiers.
+
+- Metadata lives in `~/.dsh-tui/backends/codex/channels.json`; it contains only a `tokenRef`.
+  The key is stored in the DSH credential store, not that JSON. Do not put keys in `env` or URLs.
+- Base URLs must use HTTPS; HTTP is allowed only for `localhost` and `127.0.0.1`. Usernames/
+  passwords, query strings, fragments and credential-looking path segments such as `sk-`,
+  `key=` or long random strings are rejected.
+- Provider definitions use `codex app-server -c ...` process arguments. Keys only enter the
+  child environment. **The endpoint hostname and non-secret provider arguments may be
+  visible to other local users in process listings.** Environment variables are not secret
+  from administrators either. Use trusted machines and endpoints.
+- An incomplete active connection, missing key or unsafe URL refuses startup instead of
+  silently falling back to subscription login.
+- Do not mix relay and ChatGPT login. `/login` asks you to address an active channel first.
+  A connection change follows the UI restart flow, resuming the thread with the new
+  provider/credential environment without interrupting an active turn. Mapping-only
+  profile switches may avoid restart. Do not change connections during an active turn.
+
+## Models, reasoning effort, Plan and permissions
+
+`/model` lists Codex’s models and channel mappings. `/effort` offers only the current model’s
+actual supported levels; not every model has `xhigh`. Model switching handles incompatible
+effort levels; default effort is delegated to the model. Idle changes apply immediately;
+changes during a turn apply to the next one, not to reasoning already in progress.
+
+**Collaboration mode and permissions are orthogonal.** `/permission` reuses the existing picker:
+
+| Option | Approval and sandbox |
+| --- | --- |
+| Read Only (`read-only`) | On-request approvals, read-only sandbox |
+| Default (`auto`) | On-request approvals, workspace-write sandbox |
+| Full Access (`full-access`) | No approval prompts or file sandbox; requires an explicit selection |
+| Plan (`plan`) | Planning collaboration mode; keeps the underlying permission preset rather than replacing its sandbox |
+
+- **`Shift+Tab` only toggles Plan**, returning to the previous permission preset when leaving
+  it. It does not cycle into Full Access.
+- `/plan` enters Plan; `/plan <task>` enters it and submits the task. Choosing an explicit
+  permission preset returns to Default collaboration. Plan does not mean all tools are
+  forbidden: the actual security boundary remains Codex’s permission policy.
+- Defaults resolve per field: an explicit dsh-TUI choice > your Codex configuration >
+  `auto` when unset. An unreadable configuration is not overwritten with `auto`.
+- Completed plans offer implementation, implementation with cleared context, or staying
+  in Plan/continuing with feedback. Clearing context continues in a new thread, preserving
+  the original. Plan approval does not silently enable Full Access.
+- Command, file, network and permission approvals use server-provided choices. Allow-once,
+  session allowance or remembered rules appear only when supported. Questions and MCP forms
+  share the existing panel, with secret answers masked.
+
+## Daily commands and input
+
+| Entry | Behavior |
+| --- | --- |
+| `Enter` / `Tab` / `Ctrl+Enter` while working | Steer / queue a follow-up / interrupt and send now; non-steerable turns fall back to follow-up |
+| `Esc` / `Ctrl+C` | Dismiss the focused panel or interrupt. Cancelling a model question also interrupts its turn rather than leaving it hung |
+| `/review` | Review uncommitted changes inline; requires idle state and consumes model usage |
+| `/review base <branch>` / `/review commit <sha>` | Review against a branch or commit; other arguments are custom review instructions |
+| `/diff` | Latest turn’s aggregated diff; otherwise try Git diff against the remote, then show an empty-state notice |
+| `/<skill-name> [arguments]` | Invoke a discovered, enabled Codex skill; completion updates as skills change. Local commands take precedence on name collisions |
+| `/init` | Submit Codex’s AGENTS.md initialization prompt, not the DSH template generator; a model turn with normal approvals/usage |
+| `/mcp` | Codex MCP status and tool counts, with reconnect but no runtime toggle |
+| `/usage` | Server-reported quota windows, utilization, reset times and credits; relays may not provide them |
+| `/status`, `/context`, `/compact` | Status, raw context readings, Codex compaction; unavailable category details are not invented |
+| `/new`, `/clear`, `/export` | New thread, clear the view only, export the current transcript. `/clear` **does not reset context** |
+| `!cmd` / `!!cmd` | dsh-TUI’s local shell / include output in a follow-up, not a verbatim copy of the official `!` persistence semantics |
+
+File cards use real hunk line numbers. Running command cards show a bounded live output
+tail; use `Ctrl+O` for details. Official `userShell` turns in history appear as terminal cards.
+
+### Reading context and quota
+
+The context bar follows the official 12,000-token baseline (`T` is the most recent
+`last.totalTokens`, not cumulative billed tokens; `W` is the model window):
+
+```text
+effective = max(0, W - 12000)
+used      = max(0, T - 12000)
+used share = used / effective       # when effective > 0
+remaining share = 1 - used share
+```
+
+Display handles unknown/invalid windows; `/context` keeps the raw `T / W` reading. Token
+ledger totals, subscription quota and context occupancy are different quantities. Codex
+transcripts do not normally retain full billed usage, so resuming history does not invent
+past tokens/cost. Fresh usage notifications update the readings.
+
+## Session lifecycle
+
+- `/resume` opens the native-thread browser, grouped by project, with all-project browsing.
+  `Enter` resumes, `Ctrl+R` renames and `Ctrl+D` **archives**. Confirmation and completion
+  say the transcript is retained, not physically deleted. Current, occupied or active-worker
+  threads cannot be archived. The catalog lists up to 500 recent ordinary threads, excluding
+  ephemeral forks and child threads from the main list.
+- `/rename` changes the official thread title; `/color` stores a session accent, not a global theme.
+- `/fork` creates a resumable copy without switching. Double `Esc` or `/rewind` conversation
+  rewind creates a copy before the selected question, returns the question to the composer
+  and preserves the original. Rewinding the first question creates an empty thread. **File-only
+  and conversation+files rewind are unsupported**; the Git working tree does not revert.
+- Resume replays the newest 20 full turns before live continuation. Load older messages uses
+  prefetched full-item pages, not tool-omitting summaries. Retry when prefetch is still pending;
+  repeated failure reports a notice. Active resume deduplicates redelivered approvals and
+  never invents usage absent from history.
+
+## Images
+
+Paste images or mention PNG/JPEG/GIF/WebP files with `@`. Limits: **20 MiB per image**,
+**2048 pixels per side**, **2048 × 2048 pixels**, **20 images per message**, and **50 MiB
+per message**. Staging checks the capability limits; sending rereads and checks the image.
+Resize rejected images as prompted rather than assuming an unsent attachment was handled.
+
+Inputs are data URLs persisted with the thread, not disposable clipboard paths. Resume
+shows persisted input images; missing historical localImage files show unavailable
+placeholders without automatically downloading remote images. Codex imageView and completed
+imageGeneration results also display images: `savedPath` takes precedence over embedded data.
+Real model vision and image generation were not tested in this round.
+
+## Subagents and background tasks
+
+- `/agents` or `Ctrl+A` opens the subagent panel. Child text, tools and usage stay in its
+  card/details, not the parent transcript. Details load paginated history on demand; you can
+  interrupt active subagents belonging to the current session.
+- Messaging is **parent-mediated**: the parent model relays it through Codex `send_input`,
+  not a direct child-inbox operation. A receipt means issued, not necessarily read or
+  executed. Cross-parent history/control access is refused.
+- `/jobs` shows unified-exec background terminals with the existing stop controls. Inventory
+  refreshes at turn boundaries and polls about every **2 seconds** while terminals remain
+  live. This is experimental: unsupported methods disable the capability with a notice.
+- Output is the **last 64 KiB observed by this session**, not arbitrary historical output
+  file access. A resumed terminal may have no observed output. Only a complete inventory
+  establishes disappearance. Without a native exit code, completion summaries explicitly say
+  **exit unknown**; they do not imply exit 0 or success.
+- Interrupting the model turn and stopping a background terminal are separate actions.
+
+## Goals, side queries and hooks
+
+| Entry | Behavior |
+| --- | --- |
+| `/goal` | Current goal, phase, token/time budget; values come from Codex |
+| `/goal <objective>`, `/goal edit <objective>` | Set or replace a native goal |
+| `/goal --budget 50k <objective>` | Token budget, also accepting 50000 or 1.5m |
+| `/goal pause`, `/goal resume`, `/goal clear` | Pause, resume or clear; no duplicate DSH round loop |
+| `/btw <question>`, `/recap` | One model call on an ephemeral fork, without writing the parent thread or persistent session list |
+| Hooks | hookPrompt as injected input; start/completion/failure notices, using Codex configuration rather than the DSH `/hooks` manager |
+
+usageLimited/budgetLimited goals show a blocked state and reason. Unsupported goal APIs
+do not expose the capability. `/btw`/`/recap` use a read-only sandbox with no approval
+escalation, request answer-only behavior and reject tool/approval requests. Cancellation
+interrupts the temporary turn and unsubscribes the fork. They consume model quota, not
+free local summaries. Ephemeral fork creation/non-persistence was checked offline; actual
+side-query model answers were not tested in this round.
+
+## Limitations and troubleshooting
+
+- `/skills` and `/hooks` are DSH management entries, not Codex skill/hook management. Invoke
+  Codex skills as `/<skill-name>` from completion; unavailable local commands are not model passthrough.
+- DSH presets, providers, workspace home, migration management and `/tree` are not Codex
+  capabilities. Unsupported commands are marked unavailable rather than silently executed.
+- This scope does not add every official slash alias, voice, apps/plugins management,
+  worktree/daemon, pets, memories, remote control or physical deletion. Theme/companion
+  choices remain dsh-TUI settings; native compatibility does not replace the palette.
+- `/doctor` reports executable/version, drift, Codex home, credential source, provider host,
+  sandbox issues and unknown protocol items. If Linux lacks bubblewrap, install it as
+  prompted and keep the needed sandbox; do not choose Full Access merely to hide an error.
+  Operating-system sandbox behavior belongs to official Codex.
+- 401/login failure: check the channel/route, then `/login`. Quota limits: `/usage`. Context
+  limits: `/compact`. “Active writer”: exit that session in the other terminal first.
+- An app-server exit triggers reconnection notices; failed reconnection leaves a read-only
+  session rather than pretending inputs were delivered.
+- Bug reports should include versions, platform, minimal steps and redacted diagnostics
+  only. Exports and raw ANSI/debug logs may contain text, paths or secrets; do not publish them raw.
+
+## Verification in this round
+
+- The real official 0.160.1 app-server passed nine offline checks under an isolated home: handshake/home isolation, thread creation, model listing, zero-context reading, orthogonal permission/Plan settings, persistent rename, ephemeral fork, full-page resume and archive. There was no model turn or charge and no write to user ~/.codex/config.toml.
+- Protocol/mapping, controls, lifecycle and advanced interfaces use fake-app-server and redacted-fixture regressions. Focused tests also drive the real headless browser for archive/default-delete semantics and the production channel for host OAuth-only logout. They prove wiring, state and boundaries, not acceptance of every real account/model request.
+- Not run in this round: real ChatGPT OAuth/device-code/API-key login, credentialed model turns, real vision/subagent/background-terminal/goal/side-query turns, or real-TTY inline/fullscreen/narrow-terminal interaction. Missing credentials or an interactive terminal are recorded as unverified, not passed; see the progress log for exact results.

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

@@ -67,6 +67,15 @@ A complete common override looks like this:
 | `splashFont` | `daily` | Big-text face on the header splash: `daily` rotates by local date (the default), any other value is a face id (`bold` / `square` / `bevel` / `wide` / `dot` / `stencil` / `classic` / `slab`) pinning that one; an unknown value falls back to `daily`. Also editable through `/settings` |
 | `whaleGirl` | `false` | Swap the header's pixel whale for the maid: real raster FIRST (Kitty/Sixel); falls back to the character-art maid without them |
 | `minimal` | `false` | Minimal UI (极简界面): reduce header decoration and colors. **A display switch only** — a different thing from the kernel's `minimal` agent preset under `preset` below (that one decides which tools the model can use) |
+| `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,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 |
@@ -75,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
 
@@ -142,7 +152,7 @@ preset registry: `@deepseek-ai/dsh-agent-preset-registry` on 0.1.7, or
 | --- | --- | --- |
 | `standard` | Standard (default) | Editing, shell, search, skills, planning, goals, subagents, and workflows |
 | `ptc` (0.1.2) / `code` (legacy 0.1.1) | PTC | Standard plus the PTC SDK presentation for composing operations in TypeScript; both names resolve compatibly across versions |
-| `minimal` | Minimal | Kernel agent preset: a single persistent-shell tool (bash on POSIX, pwsh on Windows), with no compaction, no plan mode and no runtime context. `str_replace_editor` has been opt-in since 0.1.3-alpha.2, so this preset does not include it |
+| `minimal` | Minimal | Kernel agent preset: a single persistent-shell tool (bash on POSIX, pwsh on Windows), with no compaction, no plan mode and no runtime context. `str_replace_editor` has been opt-in since 0.1.3-alpha.2, so this preset does not include it. The cost is stated up front: no compaction and no tool-result pruning (a long session can hit the context limit, oversized tool output stays in full), and `/compact` plus the questionnaire are unavailable — Help and `/` completion mark the entry, and entering/resuming the preset says so once |
 | `cordis` | Creation | Standard plus runtime inspection and plugin-experimentation tools |
 | `liangshen` | Liangshen mode | Minimal's minimal tool surface first for root and delegated agents, the full catalog after the first tool call, and a fresh anchor after compaction |
 
@@ -251,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` |