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

package/README.md

@@ -25,12 +25,15 @@
 ## Highlights
 
 - **Pixel whale pet** — three startup intros, click to wake; freezes after the first task.
+- **Launchpad and first-run guide** — every launch lands on a landing page with a **real input box** (big text + whale + quick actions, dropping whole blocks on short/narrow terminals); the first run walks a four-step wizard (API key / language+theme / model+workspace / shortcuts), re-runnable with `/setup`.
 - **Terminal-native UI** — streaming Markdown, tool cards, `/` and `@` completion, `#L12-14` ranges, history search, zh/en UI.
 - **Images** — Kitty/Sixel thumbnails, centered preview with zoom and pan, paste-time fitting, text fallback.
 - **Mermaid diagrams** — ````mermaid ```` fences drawn as Unicode diagrams.
 - **LaTeX math** — `$…$` and `$$…$$` formulas as Unicode text, fractions and limits stacked in display blocks; `mathRendering: image` typesets block and one-row inline formulas as terminal images on graphics terminals.
 - **Timeline rail** — every turn clickable; timeline / scrollbar / hidden gutter.
+- **Side panel** — `Ctrl+B` splits the chat with a panel column once the terminal is wide enough; all eight built-in panels are enabled by default. Narrow terminals and inline mode keep full-screen panels.
 - **Live state** — activity animation, context bar, TPS, cache hit rate, effort, tokens, session cost estimate (main + subagents), Git and session metadata.
+  Context-bar fill follows backend occupancy; colors estimate content composition. Compaction clears obsolete estimates, and missing composition displays a single used block.
 - **One session manager** — `/resume` `/home` `/agentview` `/bg` `⌸`.
 - **Session workflow** — `/new` `/compact` `/export` `/btw`, model hot-switch, fork, rewind, vim, fullscreen draft editor.
 - **IDE selection channel** — a VS Code selection lands in the prompt.
@@ -53,6 +56,9 @@ Keys and commands: [Interaction and commands](docs/interaction.en.md). Everythin
 
 ## Featured & Listed
 
+Among the community plugins recommended by the **official lead of DeepSeek
+Harness**, dsh-TUI is the first.
+
 Featured by the **DeepSeek Harness official WeChat account**, listed in the
 [dshfind](https://dshfind.com/en/plugins/ccch1mneyyy/dsh-TUI) plugin
 directory, and ranked **#7 on [GitHub Trending](https://trendshift.io/repositories/146168)
@@ -166,11 +172,86 @@ Full guide: [Session migration](docs/migrate.en.md).
 
 **VS Code**: use the integrated terminal or the `dsh-tui-vscode` extension. See [VS Code guide](docs/vscode.en.md). **Herdr**: run `dsh-tui` in a [Herdr](https://herdr.dev) pane; `idle` / `working` / `blocked` are reported through its local integration API.
 
+### Experimental: Claude backend
+
+dsh-TUI can also run its session on Claude: the same interface, driving the
+Claude Code CLI through the Claude Agent SDK. Your project's `CLAUDE.md`,
+settings, hooks, MCP servers and plugins load as the CLI loads them.
+
+```sh
+# once, in the dsh-tui profile directory (the SDK is an optional dependency)
+cd ~/.dsh/profiles/dsh-tui && pnpm add @anthropic-ai/claude-agent-sdk@0.3.287
+dsh-tui --backend claude     # or pick Claude in /kernel; that choice is remembered
+```
+
+The easiest install: open the kernel picker (the launchpad "Kernel" entry or
+`/kernel`) and press Enter on the dim Claude row — the wizard locates the
+profile directory and installs the pinned SDK for you; the command above is
+its manual equivalent.
+
+- **Sign-in**: a `/channel` relay profile, your dsh-auth `anthropic` sign-in
+  (`/login`), `ANTHROPIC_API_KEY` or cloud-provider variables, or an existing
+  `claude login`, in that order. A `claude` on `PATH` is used when present,
+  otherwise the SDK's bundled binary.
+- **Works**: streaming, tool cards, approvals and questions, `/model`,
+  `/effort`, Claude's permission modes (`/permission`, `Shift+Tab`),
+  `/compact`, `/context`, `/mcp`, `/resume`, `/fork`, double-`Esc` rewind,
+  subagents, background jobs, images, `/btw`, and the USD cost Claude reports.
+- **Not available**: DSH-only commands such as `/tree`, `/preset`,
+  `/provider`, `/workspace`, `/agentview` and `/bg`. One process runs one
+  backend; `/kernel` switches by restarting into a new session.
+
+Details and known limitations: [Claude backend](docs/claude-backend.en.md).
+
+### Experimental: native Codex backend
+
+Run your own Codex through `codex app-server`, sharing its configuration,
+login, instructions, skills, hooks, MCP and native threads:
+
+```sh
+npm install -g @openai/codex@0.160.1
+dsh-tui --backend codex
+dsh-tui --backend codex --resume <thread-id>
+```
+
+Protocol baseline **0.160.1**, minimum **0.144.0**; other versions may show
+drift. `CODEX_EXECUTABLE` selects a binary; `/kernel` remembers the backend.
+`codex resume <id>` can open the same thread after the other writer exits.
+This is not `migrate codex`, which imports history into DSH.
+With native credentials, a writer conflict for an idle thread retained by the
+official background server triggers a reconnection to that server. Managed
+subscription credentials and `/channel` connections use private app-server processes.
+
+Streaming/tool cards, approvals, questions, steer/queue/interrupt, model and
+effort controls, Plan, `/review`, `/diff`, `/usage`, `/init`, skills and MCP
+share the existing UI. **Shift+Tab only toggles Plan**, keeping its underlying
+permission preset; Full Access requires an explicit choice. Existing Codex
+settings are respected, not overwritten with defaults. `/login` offers
+ChatGPT OAuth, a device code or an API key (the last writes to Codex’s own
+credential store). Relay `/channel` connections take precedence; managed
+subscription tokens are only injected on first-party routes. dsh-TUI does
+not write `~/.codex/config.toml` or log out your native Codex account.
+
+TPS includes hidden reasoning time and excludes tool execution time. Live
+text estimates are corrected when Codex reports output token usage.
+
+Native browsing/archive, fork/conversation rewind, paged history, images,
+subagents, polled background terminals, goals and `/btw`/`/recap` use the
+existing surfaces. `/logout` removes only the matching dsh-auth credential;
+already-loaded managed tokens require a normal restart, not native logout.
+The real 0.160.1 app-server passed nine credential-free offline checks and eight
+daemon-resume checks, with no model turn or charge; real subscription login, credentialed model calls
+and real-TTY interaction were not run. Only Codex identification/title
+changes automatically, not palette or companion.
+Using ChatGPT subscription tokens in third-party clients is subject to
+OpenAI’s terms. Full instructions and current boundaries:
+[Codex backend](docs/codex-backend.en.md).
+
 ## Keybindings & Mouse
 
-`Enter` send · `Tab` complete · `Ctrl+Enter` interrupt and send · `Alt+Up` recall the last message · `Esc` dismiss, double-`Esc` rewinds · `Ctrl+O` details · `Ctrl+R` history · `Ctrl+V` paste · `Ctrl+Shift+E` fullscreen draft editor · `?` shortcuts · `←` background the session.
+`Enter` send · `Tab` complete · `Ctrl+Enter` interrupt and send · `Alt+Up` recall the last message · `Esc` dismiss, double-`Esc` rewinds · `Ctrl+B` side panel · `Ctrl+O` details · `Ctrl+R` history (`↑`/`↓` and `Ctrl+R` are scoped to the current project) · `Ctrl+V` paste · `Ctrl+Shift+E` fullscreen draft editor · `?` shortcuts · `←` open the session manager (DSH backgrounds the current session first).
 
-While the model is working: `Enter` steers, `Tab` queues a follow-up, `Ctrl+Enter` interrupts and sends.
+While the model is working: `Enter` steers, `Tab` queues a follow-up, `Ctrl+Enter` interrupts and sends. Input that names a command is still a command — with or without arguments — so `/model` or `/new` reach their own gate (and the `/` overlay sinks the commands that affect the running conversation) instead of silently becoming an interruption; only text that is not a command — and a direct skill gesture such as `/skill-name …` — steers.
 
 On native Windows, fragmented Win32 input records are reassembled across short input delays instead of appearing as numeric protocol text. The platform check only reports that this machine might run the private mode (win32-input-mode); a bare `ESC[` fragment is held only after one record has actually been decoded, while a fragment whose own shape is already record-specific holds on its own (which is how even the first record can survive a split). Windows terminals that never enter the mode (mintty, GitBash) therefore keep the classic VT path: a lone `Esc` keeps its normal response time, and a letter typed after a timed-out `ESC[` is not swallowed.
 
@@ -186,9 +267,13 @@ The window is bounded like the record hold (about a second, never extended by la
 
 Inside that window, with a query of the matching response type outstanding, same-shaped literal input can still be claimed as a reply; to type it, wait for the window to close (about a second), or avoid that shape while a query is outstanding.
 
+Fragmented SGR mouse reports no longer land in the prompt as text: an incomplete report header is held until the rest arrives, and a report that completes is handled as a mouse event. The hold is armed only while mouse reporting is actually active (fullscreen, with mouse tracking enabled); inline sessions and terminals that never enable tracking keep the existing behavior. The claim window is bounded from first capture (at most 1 second; 64 bytes max), and a continuation arriving inside it is still claimed rather than replayed. Release has no timer: once a parse call sees either bound exceeded, it replays the held bytes as ordinary keys in arrival order — literal input can be delayed, but is never dropped.
+
 Mouse (fullscreen): drag to select and copy, double/triple click to select a word or line, click tool cards, timeline ticks and `[Image #N]` previews.
 
-**Pasting**: native and bracketed paste keeps ordinary text and newlines, and never submits itself on arrival. On Windows terminals that deliver a paste as win32-input-mode key records, the residue is stripped at the entry point (a multi-line paste no longer leaves stray `_`) and pasted CRLF collapses to a single newline; genuine underscores and bracketed-paste text are untouched.
+File paths in prose can open the file-action menu; automatic detection does not extract a path from inside a slash-delimited token such as `working/idle/needs-input` or a date such as `2024/01/15`.
+
+**Pasting**: native and bracketed paste keeps ordinary text and newlines, and never submits itself on arrival. On Windows terminals that deliver a paste as win32-input-mode key records, a record stream leaked into the payload is decoded back into the characters its `Uc` field encodes — newlines included — so the composer's line count matches what was pasted; only records with no character meaning are stripped (a multi-line paste no longer leaves stray `_`), and a complete record is always consumed before an ESC-less tail, so no payload character is deleted along with an orphan escape. Pasted CRLF collapses to a single newline; genuine underscores and bracketed-paste text are untouched.
 
 **Dropped files**: a native Windows desktop drop (Windows Terminal / OpenConsole) arrives as an OSC 8 hyperlink; the parser restores its `file://` URI to a decoded local path before paste hygiene runs, so the `]8;id=…;` parameter bytes never reach the draft. Image paths enter the existing image staging pipeline; other files are inserted as a referenceable path (a path containing whitespace arrives in the composer's quoted `"…"` single-token form). Only `file://` URIs are restored, and it is fail-closed: a remote authority/UNC, a payload carrying several distinct URIs, or a URI that carries several tokens is refused and stays literal text rather than guessed.
 
@@ -196,11 +281,17 @@ Full reference: [Interaction and commands](docs/interaction.en.md).
 
 ## Built-in Commands
 
-`/resume` · `/home` · `/agentview` · `/bg` · `⌸` open the same session manager: workspace rail, live state, filter, ★ pins. Also `/model` `/new` `/compact` `/export` `/btw` `/tree` `/fork` `/rewind` `/settings` `/status` `/cost` `/jobs` `/skills` `/mcp` `/provider` `/auth` `/login` `/update`.
+`/resume` · `/home` · `/agentview` · `/bg` · `⌸` open the same session manager: workspace rail, live state, filter, ★ pins. Also `/model` `/new` `/compact` `/export` `/btw` `/tree` `/fork` `/rewind` `/settings` `/setup` `/status` `/cost` `/jobs` `/skills` `/mcp` `/provider` `/auth` `/login` `/update`.
+
+In `/provider`'s model list, focus a model and press `Tab` to edit its context window, max output tokens, reasoning efforts, and image input capability.
 
 The session manager paints the last successful list immediately while it checks the persistence store for changes. Titles that require a deeper log scan appear first with a fallback name and update in place when recovery finishes.
+Removing a workspace registration keeps its sessions accessible under a "History only" directory in the rail.
+History-only directories offer edit and new-session actions; rename and remove are available for registered workspaces.
 
-**Background sessions**: `/bg` or `←` on an empty prompt; `Esc` returns. They run in this process and stop when the TUI exits. Logs survive.
+**Background jobs**: card headers open the focused task panel. Click the card body or use `Ctrl+O` to toggle the command between its first statement and full script. Commands and output use separate colored edges with `❯` (`>` on Windows) and `≡` on their first rows; output always stays at the latest two visible rows. `/jobs` and the side panel keep the full output scrollable, while `e` toggles the focused command. Consecutive blank script lines collapse to one.
+
+**Background sessions**: On the DSH backend, `/bg` or `←` on an empty prompt backgrounds the current session and opens the session manager; `Esc` returns to it. Background sessions run in this process and stop when the TUI exits. Logs survive. On Claude/Codex, those entries open the session manager without backgrounding the session.
 
 Full commands: [Interaction and commands](docs/interaction.en.md).
 
@@ -226,8 +317,9 @@ Runtime path, module boundaries, performance notes and persistence locations: [A
 - `Ctrl+V` needs platform clipboard tools; unsupported bitmap formats are rejected.
 - A dropped file is restored from its OSC 8 `file://` URI alone: multi-file drops, non-Windows terminal drop encodings and terminator-less truncated frames are not covered, and the hyperlink's own display name is never used.
 - A background session lives inside this process and stops when the TUI exits.
-- `/thinking` is not persisted; `/compact` is unavailable under the kernel's `minimal` agent preset (极简模式, one persistent-shell tool) — a different thing from the `/settings → Minimal UI` (极简界面) display switch; `/update` needs a `dsh --profile` launch and is refused while a turn is running.
+- `/thinking` is not persisted; the kernel `minimal` agent preset (极简模式, one persistent-shell tool) mounts no compaction and does not prune tool results — a long session can hit the context limit, oversized tool output stays in the context in full, and `/compact` plus the questionnaire are unavailable under it (Help and `/` completion mark the entry, and entering the preset says so once); that is a different thing from the `/settings → Minimal UI` (极简界面) display switch; `/update` needs a `dsh --profile` launch and is refused while a turn is running.
 - The status-bar `≈¥` and `/cost` are session estimates that include subagent usage (priced per each agent's model × peak/idle × cache components); unofficial or unlisted models show tokens only and are marked unpriced. **The platform bill is authoritative.**
+- Fragmented SGR mouse reports are covered at the mechanism level with controlled fixture comparisons; the reporter environments (macOS → SSH, WSL2 with `dsh web`) have not been re-tested.
 
 Full list: [Architecture and limitations → Known limitations](docs/architecture.en.md#known-limitations).
 
@@ -251,7 +343,7 @@ questionnaire, or tool-card changes also need the matching regression scripts.
 
 ## Plugin Ecosystem
 
-Plugin development: [admission & development guide](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md) · [plugin-template](https://github.com/dsh-tui-ecosystem/plugin-template) · [dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem). Reference implementation: `dsh-working-activity`.
+Plugin development: [admission & development guide](tui-profile/docs/plugin-admission-and-development.md) · [plugin-template](https://github.com/dsh-tui-ecosystem/plugin-template) · [dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem). Reference implementation: `dsh-working-activity`.
 
 Seam grading and API notes: [Plugin development](docs/plugins.en.md). The organization maintains the listing only; it does not endorse community plugins.
 
@@ -261,7 +353,7 @@ Seam grading and API notes: [Plugin development](docs/plugins.en.md). The organi
 - **Use** — [Keys and commands](docs/interaction.en.md) · [User guide](docs/user-guide.en.md) · [Themes](docs/themes.en.md)
 - **Configure** — [Configuration](docs/configuration.en.md)
 - **Internals** — [Architecture and limitations](docs/architecture.en.md) · [Session mounting](docs/session-mount-runtime.en.md)
-- **Plugins** — [Admission and development](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md) · [Seams](docs/plugins.en.md)
+- **Plugins** — [Admission and development](tui-profile/docs/plugin-admission-and-development.md) · [Seams](docs/plugins.en.md)
 - **Contribute** — [Contributing](docs/contributing.en.md) · [Roadmap](docs/roadmap.en.md) · [Community](docs/community-management.en.md)
 
 Everything, bilingual: [docs/README.md](docs/README.md).
@@ -310,6 +402,30 @@ Community, related projects, and companion tools built by friends:
 
 [![Star History](https://raw.githubusercontent.com/ccch1mneyyy/dsh-TUI/bot-star-history/assets/star-history/star-history.png)](https://star-history.com/#ccch1mneyyy/dsh-TUI&Date)
 
+---
+
+## Maintainers
+
+<table>
+  <tbody>
+    <tr>
+      <td align="center" width="150"><a href="https://github.com/ccch1mneyyy"><img src="https://github.com/ccch1mneyyy.png?size=160" width="96" height="96" alt="ccch1mneyyy"></a><br><a href="https://github.com/ccch1mneyyy"><b>ccch1mneyyy</b></a><br><sub>Core development &amp; maintenance</sub></td>
+      <td align="center" width="150"><a href="https://github.com/CikeSeven"><img src="https://github.com/CikeSeven.png?size=160" width="96" height="96" alt="CikeSeven"></a><br><a href="https://github.com/CikeSeven"><b>CikeSeven</b></a><br><sub>Performance &amp; stability</sub></td>
+      <td align="center" width="150"><a href="https://github.com/T-Auto"><img src="https://github.com/T-Auto.png?size=160" width="96" height="96" alt="T-Auto"></a><br><a href="https://github.com/T-Auto"><b>T-Auto</b></a><br><sub>Architecture &amp; ecosystem adaptation</sub></td>
+      <td align="center" width="150"><a href="https://github.com/AdamPlatin123"><img src="https://github.com/AdamPlatin123.png?size=160" width="96" height="96" alt="AdamPlatin123"></a><br><a href="https://github.com/AdamPlatin123"><b>AdamPlatin123</b></a><br><sub>Security &amp; interaction</sub></td>
+      <td align="center" width="150"><a href="https://github.com/Nagi-ovo"><img src="https://github.com/Nagi-ovo.png?size=160" width="96" height="96" alt="Nagi-ovo"></a><br><a href="https://github.com/Nagi-ovo"><b>Nagi-ovo</b></a><br><sub>Test infrastructure &amp; terminal rendering</sub></td>
+    </tr>
+  </tbody>
+</table>
+
+※ In no particular order
+
+---
+
+## Contributors
+
+[![Contributors](https://contrib.rocks/image?repo=ccch1mneyyy/dsh-TUI)](https://github.com/ccch1mneyyy/dsh-TUI)
+
 ## License
 
 [MIT](LICENSE)

package/assets/deepy/README.md

@@ -0,0 +1,60 @@
+# Deepy 小鲸鱼 · 终端版素材包
+
+这套小鲸鱼动画是给终端页面用的。鲸鱼本体全程不移动、不变形，只换表情、尾巴姿态和旁边的小道具。每一帧都是 42×30 的整像素画面，用半块字符 `▀`／`▄` 显示时正好占 **42 列 × 15 行**。
+
+## 目录
+
+| 文件 | 说明 |
+|---|---|
+| `frames.json` | 全部 20 个动画的逐帧像素数据和每帧时长，接进你自己的终端程序时用它 |
+| `play.py` | Python 播放器，不需要装任何依赖，需要支持 24 位真彩色的终端 |
+| `play.mjs` | Node 播放器，也可以当模块用：`import { loadWhale, renderFrame } from './play.mjs'` |
+| `gif/` | 每个动画一个 GIF，8 倍放大，透明背景 |
+| `sheets/` | 1 倍大小的精灵表，所有帧从左到右横向排列（每帧 42×30） |
+| `png/` | 每个动画第一帧的 8 倍放大静态图 |
+
+## 快速试一下
+
+```bash
+python3 play.py --list        # 列出所有动画
+python3 play.py thinking      # 循环播放一个动画，按 Ctrl-C 退出
+python3 play.py --all         # 20 个动画轮流播放
+node play.mjs happy --once    # 用 Node 播一次
+```
+
+## frames.json 格式
+
+```json
+{
+  "size": [42, 30],
+  "palette": { "K": "#142660", "B": "#4E6FFF", "...": "..." },
+  "animations": [
+    { "key": "idle", "title": "待机", "state": "idle", "trigger": "无任务",
+      "frames": [ { "dur": 900, "rows": ["....", "... 共 30 行，每行 42 个字符"] } ] }
+  ]
+}
+```
+
+- `rows` 里每个字符代表一个像素，对应 `palette` 里的颜色；`.` 表示透明。
+- 每次取上下相邻的两行像素，合成一行字符：上面的像素作前景色、下面的作背景色，画成 `▀`；如果一半是透明的，就只画 `▀` 或 `▄`，另一半保持终端背景。播放器里的 `renderFrame()` 就是这样做的，可以直接复用。
+- `dur` 是这一帧停留的毫秒数，帧和帧之间不做插值，直接切换。
+
+## 状态对应
+
+| 动画 key | 适合放在 |
+|---|---|
+| idle / idle-look / idle-spout / swim | 空闲待机（后三个可以随机插播） |
+| thinking | 刚提交问题、模型在思考 |
+| typing | 正在调用工具、写代码 |
+| music | 1 个子代理，或 2 个会话同时在跑 |
+| building | 3 个以上会话同时在跑 |
+| conducting | 2 个以上子代理 |
+| compacting | 上下文压缩、清理 |
+| carrying | 新建工作树或分支 |
+| notification | 需要你确认或授权 |
+| error | 工具调用失败 |
+| happy | 任务完成 |
+| sleeping / waking | 长时间没有操作 / 重新有操作 |
+| poke-left / poke-right / tickle / drag | 被点击、连点、拖拽时的互动反应 |
+
+Deepy 是非官方的粉丝作品，和 DeepSeek、Anthropic 都没有关系。