@xmoon76/dsh-pi-tui 0.4.0 → 0.4.3-alpha.2

package/README.en.md

@@ -9,24 +9,99 @@ A Pi-style terminal frontend for [DeepSeek Harness](https://github.com/deepseek-
 
 `dsh-pi-tui` is installed as an independent dsh bundle inside a profile. It provides terminal interaction for streaming conversations, tool calls, session management, subagents, history search, shell commands, approvals, and settings. Models, tools, Sessions, permissions, Skills, Plan, Goal, and Subagent runtime behavior are still provided by DeepSeek Harness.
 
+![dsh-pi-tui](docs/dsh-pi-tui.png)
+
+## Install into a DSH profile
+
+### Stable / latest
+
+Stable releases are recommended for ordinary users. Install DSH first, then add
+the TUI to the `pi-tui` profile:
+
 ```sh
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@next
+npm install -g @deepseek-ai/dsh@0.1.2-rc.1
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@latest
 dsh --profile pi-tui
 ```
 
-![dsh-pi-tui](docs/dsh-pi-tui.png)
+### Next / npm line (validation)
+
+The current `next` line targets the published npm release `dsh-v0.1.3-alpha.2`.
+Use the isolated npm driver (installs the exact DSH version declared by this
+checkout and exercises the full build/test/package path):
+
+```sh
+pnpm compat:dsh:npm
+```
+
+The startup notice on an old runtime suggests the exact npm upgrade:
+
+```sh
+npm install -g @deepseek-ai/dsh@0.1.3-alpha.2
+```
+
+### Requirements
+
+* DeepSeek Harness
+* Node.js `^22.19.0 || >=24`
+
+### DSH/TUI version pairing (important)
+
+| TUI package line | Matching DSH line | Notes |
+|---|---|---|
+| `0.4.1` (published `@latest`) | `>=0.1.2-rc.1` | Historical stable; validated against the rc.1 family |
+| Current `next` npm line (this checkout; version `0.4.3-alpha.2`) | `>=0.1.3-alpha.2` | Published npm alpha.2 target; validated against the exact 0.1.3-alpha.2 family |
+| `0.3.x` (`@0.3`) | `0.1.1-rc.2` | Legacy runtime line |
+
+Do not mix the stable and `next` lines. The published 0.4.1 stable line
+still uses the 0.1.2-rc.1 family; if you keep a legacy DSH runtime, use the 0.3
+compatibility line below. This `next` checkout declares the published
+`0.1.3-alpha.2` npm floor, and older runtimes fail at the normal
+incompatible-runtime boundary. The startup row's compatibility notice is
+best-effort rather than a Loader startup-order guarantee; the suggested upgrade
+target is a published npm version.
+
+```sh
+npm install -g @deepseek-ai/dsh@0.1.1-rc.2
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@0.3
+dsh --profile pi-tui
+```
+
+The published `0.4.1` stable line declares `>=0.1.2-rc.1`; this checkout's
+`next` npm line declares `>=0.1.3-alpha.2`. `npm install -g` is only for
+installing a published DSH; to install dsh-pi-tui into a DSH profile, you must
+use the `dsh plugin` command.
 
-## DSH compatibility and source validation
+New agent sessions use the official roster's selected preset id. A custom DSH
+preset literally named `code` is valid and remains `code` when it exists in the
+current roster. Old persisted `code` defaults/session values fall back to `ptc`
+only after the roster proves that no custom `code` preset exists.
+
+### Profile management
+
+Update the installed TUI:
+
+```sh
+dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui
+```
 
-The published package declares the lower-bound-only DSH peer contract `>=0.1.2-rc.1`. Source validation does not change that contract or vendor DSH into this repository.
+List installed plugins:
 
-When the target DSH version is not yet available from npm, validate against the official checkout pinned by commit SHA:
+```sh
+dsh plugin --profile pi-tui -- list
+```
+
+Remove the plugin:
 
 ```sh
-pnpm compat:dsh:source -- --dsh-dir "$HOME/project/deepseek-harness"
+dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui
 ```
 
-CI follows the tracked `test/compat/dsh-mode.json` policy for pushes to `next` and pull requests targeting `next`; `main` and every tag use npm Mode. Both `next` lanes use `test/compat/dsh-source.json` for the current validated DSH target; Source Mode validates the complete official DSH tarball family, TUI presets, and the old-runtime boundary, while npm Mode runs the frozen registry lane. The published `pi2dsh` ecosystem check is explicitly marked skipped for an unpublished source family. See [`docs/dsh-compatibility.md`](docs/dsh-compatibility.md) for the full workflow.
+Resume an existing Session:
+
+```sh
+dsh --profile pi-tui --session <session-id>
+```
 
 ## Features
 
@@ -94,7 +169,8 @@ Regular `↑` / `↓` history recall is still available for recent input.
 
 ### Subagents and background tasks
 
-`/tasks` opens the task browser for the current Session.
+`/tasks` opens the full Task Center for all background work in the current
+Session; the Footer's `↓` opens the lightweight Quick Tasks view for running work.
 
 Subagents are shown using their complete lineage, including nested descendants:
 
@@ -113,6 +189,12 @@ The browser distinguishes:
 * nested descendants
 * background Jobs
 
+The two views share the same runtime state: `A` toggles Active / All scope,
+`Tab` changes type filters, `/` enters search, `S` stops the selected task after
+confirmation, and `N` / `Shift+N` moves between running tasks. In Quick Tasks,
+`T` or the bottom “View all” row opens the full Task Center, and `Esc` returns
+one layer at a time.
+
 Completed one-shot Subagents remain available for persisted Transcript inspection.
 
 A direct `continuable` Child can be opened in an interactive viewer and sent follow-up messages directly (through DSH's official `subagents.prompt()` human channel — queued in order as the Child's own next turn, with user provenance). The Child has its own Transcript, Draft, and runtime state, without modifying the main Session input.
@@ -155,7 +237,7 @@ Typing `@` opens workspace file search and completion:
 @"path with spaces/file.ts"
 ```
 
-`/image <path>` also completes files and directories; paths with spaces, quotes, or Windows separators preserve the input dialect, and directories can be expanded further.
+`/attach <path>` is the unified Client-local image/file intake; `/image <path>` keeps its image-only compatibility semantics. Both complete files and directories; paths with spaces, quotes, or Windows separators preserve the input dialect, and directories can be expanded further.
 
 Resolvable relative paths are canonicalized before submission.
 
@@ -219,8 +301,8 @@ For the full `/footer` workflow, Custom Text / Command items, YAML reference, se
 | `Shift+Enter` | Insert newline                                      |
 | `Esc`         | Cancel current interaction / interrupt running work |
 | `Esc Esc`     | Open Rewind while idle                              |
-| `Ctrl+C`      | Interrupt / clear current input                     |
-| `Ctrl+D`      | Quit the TUI (like `/exit`)                         |
+| `Ctrl+C`      | Keyboard exit confirmation; clears the draft first |
+| `Ctrl+D`      | Keyboard exit confirmation when empty; forward-delete with draft text |
 | `Ctrl+S`      | Steer queued messages and the draft into the running turn |
 | `Ctrl+T`      | Toggle the todo panel                               |
 | `Ctrl+R`      | Search input history                                |
@@ -308,102 +390,6 @@ dsh-pi-tui:
   works; only `false` removes every trigger of an action.
 
 
-## Installation
-
-### Requirements
-
-* DeepSeek Harness
-* Node.js `^22.19.0 || >=24`
-
-### DSH/TUI version pairing (important)
-
-| TUI package line | Matching DSH line | Notes |
-|---|---|---|
-| `0.4.0` (`@latest`) | `>=0.1.2-rc.1` | Current stable; validated against the rc.1 family |
-| `0.4.x-alpha` (`@next`) | `>=0.1.2-rc.1` | Subsequent prerelease; each release validates its concrete DSH family |
-| `0.4.0-alpha.2` (published) | `>=0.1.2-alpha.4` | Previous 0.4 prerelease; its releases validated the alpha.4/alpha.5 family |
-| `0.4.0-alpha.1` (published) | `>=0.1.2-alpha.2` | Earlier 0.4 prerelease; accepts the alpha.2/alpha.3 runtime |
-| `0.3.x` (`@0.3`) | `0.1.1-rc.2` | Legacy runtime line |
-
-Do not mix the lines: DSH 0.1.1 is outside the 0.4 peer window and the
-normal incompatible-runtime boundary will fail. The startup row prints upgrade
-and rollback guidance when concurrent Loader ordering allows it, but that
-friendly notice is best-effort rather than a startup-order guarantee. If you
-keep DSH 0.1.1, use the 0.3 TUI line; if you keep the alpha.2/alpha.3
-baseline, use `@xmoon76/dsh-pi-tui@0.4.0-alpha.1`; if you keep the
-alpha.4/alpha.5 baseline, use `@xmoon76/dsh-pi-tui@0.4.0-alpha.2`. For the
-current 0.4 stable release, install the matching DSH first and then add the
-TUI to a profile:
-
-```sh
-npm install -g @deepseek-ai/dsh@0.1.2-rc.1
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@latest
-dsh --profile pi-tui
-```
-
-If you need to keep the legacy DSH runtime:
-
-```sh
-npm install -g @deepseek-ai/dsh@0.1.1-rc.2
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@0.3
-dsh --profile pi-tui
-```
-
-The current 0.4 line declares `>=0.1.2-rc.1`; each release validates
-its concrete DSH family. Running only `npm install -g @xmoon76/dsh-pi-tui` does
-not install the plugin into a DSH profile; the `dsh plugin` command is still
-required.
-
-New agent sessions use the official roster's selected preset id. A custom DSH
-preset literally named `code` is valid and remains `code` when it exists in the
-current roster. Old persisted `code` defaults/session values fall back to `ptc`
-only after the roster proves that no custom `code` preset exists.
-
-### npm
-
-Using a dedicated `pi-tui` profile is recommended. Use the TUI channel that
-matches your DSH line: `@latest` for stable releases, `@next` for prereleases:
-
-```sh
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@latest
-dsh --profile pi-tui
-```
-
-Resume an existing Session:
-
-```sh
-dsh --profile pi-tui --session <session-id>
-```
-
-### Source Mode (validation only)
-
-Source Mode is the validation-only distribution selected by the tracked policy for `next` CI and available for local compatibility checks. It reads the full commit pin in `test/compat/dsh-source.json`, builds the official DSH tarball family, installs it through temporary pnpm overrides, and removes the temporary state afterward. Do not write DSH source paths, `file:` dependencies, or workspace symlinks into a published package.
-
-```sh
-pnpm compat:dsh:source -- --dsh-dir "$HOME/project/deepseek-harness"
-pnpm compat:dsh:npm
-```
-
-The published package already contains the Pi TUI fork required at runtime. No separate internal TUI package needs to be installed.
-
-### Update
-
-```sh
-dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui
-```
-
-List installed plugins:
-
-```sh
-dsh plugin --profile pi-tui -- list
-```
-
-Remove:
-
-```sh
-dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui
-```
-
 ## Running from source
 
 ```sh
@@ -566,6 +552,37 @@ dsh plugin --profile pi-tui-dev -- add @xmoon76/dsh-pi-tui@link:$PWD
 dsh --profile pi-tui-dev
 ```
 
+## DSH compatibility and validation
+
+This section contains DSH compatibility and CI validation details only; ordinary users do not need them to install the TUI.
+
+### npm mode (current `next`)
+
+The current `next` line is npm mode: it targets the published
+`dsh-v0.1.3-alpha.2` family declared by this checkout's `package.json` and
+resolved by its frozen lockfile. The isolated npm driver installs that exact
+family from the public registry and exercises the TUI build/test/package path:
+
+```sh
+pnpm compat:dsh:npm
+```
+
+### Source Mode (validation only)
+
+Source Mode is the validation-only distribution for an unpublished DSH
+checkout, available for local compatibility checks and explicit
+source-boundary work. It reads the full commit pin in
+`test/compat/dsh-source.json`, builds the official DSH tarball family, installs
+it through temporary pnpm overrides, and removes the temporary state afterward.
+Do not write DSH source paths, `file:` dependencies, or workspace symlinks into
+a published package.
+
+The published package already contains the Pi TUI fork required at runtime. No separate internal TUI package needs to be installed.
+
+### CI validation policy
+
+CI follows the tracked `test/compat/dsh-mode.json` policy for pushes to `next` and pull requests targeting `next`; `main` and every tag use npm Mode. Source Mode reads the source target from `test/compat/dsh-source.json` and validates the complete official DSH tarball family, TUI presets, and the old-runtime boundary; npm Mode uses the DSH version declared by the checkout's `package.json` and frozen lockfile to run the registry lane. The published `pi2dsh` ecosystem check is explicitly marked skipped for an unpublished source family. See [`docs/dsh-compatibility.md`](docs/dsh-compatibility.md) for the full workflow.
+
 ## Repository layout
 
 The repository root is the npm package published as `@xmoon76/dsh-pi-tui`.

package/README.md

@@ -9,24 +9,96 @@
 
 `dsh-pi-tui` 作为独立的 dsh bundle 安装到 profile 中，提供流式对话、工具调用、会话管理、Subagent、历史搜索、Shell、审批与设置等终端交互。模型、工具、Session、权限、Skills、Plan、Goal、Subagent 等运行时能力仍由 DeepSeek Harness 提供。
 
+![dsh-pi-tui](docs/dsh-pi-tui.png)
+
+## 安装到 DSH Profile
+
+### Stable / latest
+
+稳定版是普通用户的推荐渠道。请先安装 DSH，再将 TUI 添加到 `pi-tui` profile：
+
 ```sh
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@next
+npm install -g @deepseek-ai/dsh@0.1.2-rc.1
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@latest
 dsh --profile pi-tui
 ```
 
-![dsh-pi-tui](docs/dsh-pi-tui.png)
+### Next / npm 线（验证）
+
+当前 `next` 线以已发布的 npm 版本 `dsh-v0.1.3-alpha.2` 为兼容目标。使用
+隔离的 npm 驱动验证（安装 checkout 声明的精确 DSH 版本并跑完整
+build/test/package 路径）：
+
+```sh
+pnpm compat:dsh:npm
+```
+
+旧 runtime 的启动提示会给出精确的 npm 升级命令：
+
+```sh
+npm install -g @deepseek-ai/dsh@0.1.3-alpha.2
+```
+
+### 环境要求
+
+* DeepSeek Harness
+* Node.js `^22.19.0 || >=24`
+
+### DSH 与 TUI 版本对应（重要）
+
+| TUI 包版本 | 对应 DSH 版本 | 说明 |
+|---|---|---|
+| `0.4.1`（已发布 `@latest`） | `>=0.1.2-rc.1` | 历史稳定版；按 0.1.2-rc.1 family 验证 |
+| 当前 `next` npm 线（本 checkout；版本 `0.4.3-alpha.2`） | `>=0.1.3-alpha.2` | 已发布的 npm alpha.2 目标；按精确 0.1.3-alpha.2 family 验证 |
+| `0.3.x`（`@0.3`） | `0.1.1-rc.2` | 旧运行时兼容线 |
+
+不要把稳定线与 `next` 线混装。已发布的 0.4.1 稳定线仍按
+0.1.2-rc.1 family 使用；保留旧 DSH 时请使用下方的 0.3 兼容线。当前
+`next` checkout 的 peer floor 是 `>=0.1.3-alpha.2`，旧 runtime 会在正常的
+不兼容边界以非零状态失败。启动行的兼容提示是 best-effort，不是 Loader
+启动顺序保证；它建议的升级目标是已发布的 npm 版本。
+
+```sh
+npm install -g @deepseek-ai/dsh@0.1.1-rc.2
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@0.3
+dsh --profile pi-tui
+```
+
+已发布的 `0.4.1` 稳定线声明支持范围是 `>=0.1.2-rc.1`；本 checkout 的
+`next` npm 线则声明 `>=0.1.3-alpha.2`。`npm install -g` 仅用于
+安装已发布的 DSH；要将 dsh-pi-tui 安装进 DSH profile，必须使用
+`dsh plugin` 命令。
 
-## DSH 兼容性与源码验证
+新的 Agent preset 使用当前 roster 中选定的 id。DSH 允许合法的自定义
+`code` preset；只要当前 roster 存在它，显式输入和持久化状态都会保留 `code`。
+旧数据中省略请求的 `code` default/session 值只有在确认 roster 不含 `code` 后
+才会回退到 `ptc`。
+
+### Profile management
+
+更新已安装的 TUI：
+
+```sh
+dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui
+```
 
-发布包通过 `package.json` peer contract 使用 DSH `>=0.1.2-rc.1`；源码验证不会修改这个发布契约，也不会把 DSH vendor 进本仓库。
+查看已安装插件：
 
-当目标 DSH 版本尚未发布到 npm 时，可以用固定 commit 的官方源码包做本地验证：
+```sh
+dsh plugin --profile pi-tui -- list
+```
+
+卸载：
 
 ```sh
-pnpm compat:dsh:source -- --dsh-dir "$HOME/project/deepseek-harness"
+dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui
 ```
 
-CI 对 push 到 `next` 以及目标为 `next` 的 PR 遵循跟踪的 `test/compat/dsh-mode.json` 策略；`main` 和所有 tag 使用 npm Mode。`next` 的两种 lane 都从 `test/compat/dsh-source.json` 读取当前 validated DSH target；Source Mode 会验证完整的官方 DSH tarball family、TUI 预设和旧 runtime 边界，npm Mode 则运行冻结的 registry lane。对于尚未发布的 source family，已发布 `pi2dsh` 的生态检查会明确标记为 skipped。详细流程见 [`docs/dsh-compatibility.md`](docs/dsh-compatibility.md)。
+恢复已有 Session：
+
+```sh
+dsh --profile pi-tui --session <session-id>
+```
 
 ## 功能
 
@@ -155,7 +227,7 @@ Shell 卡片默认只显示有限的输出预览，`Ctrl+O` 可以展开完整
 @"path with spaces/file.ts"
 ```
 
-`/image <path>` 也支持文件与目录补全；带空格、引号或 Windows 分隔符的路径会保留输入方言，目录可以继续展开。
+`/attach <path>` 是统一的 Client-local 图片/文件入口；`/image <path>` 保持图片专用兼容语义。两者都支持文件与目录补全；带空格、引号或 Windows 分隔符的路径会保留输入方言，目录可以继续展开。
 
 能够解析的相对路径会在提交时转换为明确的文件路径。
 
@@ -218,8 +290,8 @@ TUI 使用 DSH 提供的模型和设置服务。
 | `Shift+Enter` | 换行                     |
 | `Esc`         | 取消当前交互 / 中断运行          |
 | `Esc Esc`     | 空闲时打开 Rewind           |
-| `Ctrl+C`      | 中断 / 清空当前输入            |
-| `Ctrl+D`      | 退出 TUI(等同 `/exit`)    |
+| `Ctrl+C`      | 键盘退出确认;首次清空草稿       |
+| `Ctrl+D`      | 空草稿时键盘退出确认;有内容时向前删除 |
 | `Ctrl+S`      | Steer:把队列消息和草稿一起发送到正在运行的回合 |
 | `Ctrl+T`      | 切换 Todo 面板              |
 | `Ctrl+R`      | 搜索输入历史                 |
@@ -297,99 +369,6 @@ dsh-pi-tui:
   移除某 action 的全部触发。
 
 
-## 安装
-
-### 环境要求
-
-* DeepSeek Harness
-* Node.js `^22.19.0 || >=24`
-
-### DSH 与 TUI 版本对应（重要）
-
-| TUI 包版本 | 对应 DSH 版本 | 说明 |
-|---|---|---|
-| `0.4.0`（`@latest`） | `>=0.1.2-rc.1` | 当前稳定版；按 0.1.2-rc.1 family 验证 |
-| `0.4.x-alpha`（`@next`） | `>=0.1.2-rc.1` | 后续预发布线；按每个发布版本的具体 DSH family 验证 |
-| `0.4.0-alpha.2`（已发布） | `>=0.1.2-alpha.4` | 上一条 0.4 预发布线；其发布版本按 alpha.4/alpha.5 family 验证 |
-| `0.4.0-alpha.1`（已发布） | `>=0.1.2-alpha.2` | 更早的 0.4 预发布线；接受 alpha.2/alpha.3 运行时 |
-| `0.3.x`（`@0.3`） | `0.1.1-rc.2` | 旧运行时兼容线 |
-
-不要把两条线混装：DSH 0.1.1 不在 0.4 的 peer 支持范围内，运行时会在
-正常的不兼容边界以非零状态失败。启动行会在 Loader 并发挂载顺序允许时打印
-升级和回退提示，但该友好提示是 best-effort，不是启动顺序保证；保留 DSH
-0.1.1 时请使用 0.3，保留 alpha.2/alpha.3 时请使用
-`@xmoon76/dsh-pi-tui@0.4.0-alpha.1`，保留 alpha.4/alpha.5 时请使用
-`@xmoon76/dsh-pi-tui@0.4.0-alpha.2`。当前 0.4 稳定版的推荐安装顺序如下
-（先装 DSH，再把 TUI 装入 profile）：
-
-```sh
-npm install -g @deepseek-ai/dsh@0.1.2-rc.1
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@latest
-dsh --profile pi-tui
-```
-
-如果需要保留旧 DSH：
-
-```sh
-npm install -g @deepseek-ai/dsh@0.1.1-rc.2
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@0.3
-dsh --profile pi-tui
-```
-
-`0.4` 当前线的声明支持范围是 `>=0.1.2-rc.1`；每个发布版本都会验证
-具体的 DSH family。仅执行 `npm install -g @xmoon76/dsh-pi-tui` 不会把插件安装进
-DSH profile，实际使用仍应执行上面的 `dsh plugin` 命令。
-
-新的 Agent preset 使用当前 roster 中选定的 id。DSH 允许合法的自定义
-`code` preset；只要当前 roster 存在它，显式输入和持久化状态都会保留 `code`。
-旧数据中省略请求的 `code` default/session 值只有在确认 roster 不含 `code` 后
-才会回退到 `ptc`。
-
-### npm
-
-推荐使用单独的 `pi-tui` profile。使用与 DSH 版本匹配的
-TUI channel（稳定版用 `@latest`，预发布版用 `@next`）：
-
-```sh
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@latest
-dsh --profile pi-tui
-```
-
-恢复已有 Session：
-
-```sh
-dsh --profile pi-tui --session <session-id>
-```
-
-### Source Mode（仅验证）
-
-Source Mode 是 `next` CI 按跟踪策略选用的、并可用于本地兼容性检查的验证专用 distribution。它从 `test/compat/dsh-source.json` 的完整 commit SHA 构建官方 DSH tarball family，通过临时 pnpm overrides 安装，并在完成后清理临时状态。不要把 DSH 源码路径、`file:` 依赖或 workspace symlink 写入发布 package。
-
-```sh
-pnpm compat:dsh:source -- --dsh-dir "$HOME/project/deepseek-harness"
-pnpm compat:dsh:npm
-```
-
-安装包已经包含运行所需的 Pi TUI fork，不需要额外安装内部的 TUI package。
-
-### 更新
-
-```sh
-dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui
-```
-
-查看已安装插件：
-
-```sh
-dsh plugin --profile pi-tui -- list
-```
-
-卸载：
-
-```sh
-dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui
-```
-
 ## 从源码运行
 
 ```sh
@@ -552,6 +531,34 @@ dsh plugin --profile pi-tui-dev -- add @xmoon76/dsh-pi-tui@link:$PWD
 dsh --profile pi-tui-dev
 ```
 
+## DSH 兼容性与验证
+
+以下内容仅介绍 DSH 兼容性与 CI 验证细节；普通用户无需了解即可安装 TUI。
+
+### npm 模式（当前 `next`）
+
+当前 `next` 线是 npm 模式：以本 checkout 的 `package.json` 声明、冻结
+lockfile 解析的已发布 `dsh-v0.1.3-alpha.2` family 为兼容目标。隔离的 npm
+驱动从公共 registry 安装该精确 family，并跑完整 build/test/package 路径：
+
+```sh
+pnpm compat:dsh:npm
+```
+
+### Source Mode（仅验证）
+
+Source Mode 是面向未发布 DSH checkout 的验证专用 distribution，用于本地
+兼容性检查与显式的 source 边界工作。它从 `test/compat/dsh-source.json` 的
+完整 commit SHA 构建官方 DSH tarball family，通过临时 pnpm overrides 安装，
+并在完成后清理临时状态。不要把 DSH 源码路径、`file:` 依赖或 workspace
+symlink 写入发布 package。
+
+安装包已经包含运行所需的 Pi TUI fork，不需要额外安装内部的 TUI package。
+
+### CI 验证策略
+
+CI 对 push 到 `next` 以及目标为 `next` 的 PR 遵循跟踪的 `test/compat/dsh-mode.json` 策略；`main` 和所有 tag 使用 npm Mode。Source Mode 从 `test/compat/dsh-source.json` 读取 source target 并验证完整的官方 DSH tarball family、TUI 预设和旧 runtime 边界；npm Mode 则使用 checkout 的 `package.json`/冻结 lockfile 中声明的 DSH 版本运行 registry lane。对于尚未发布的 source family，已发布 `pi2dsh` 的生态检查会明确标记为 skipped。详细流程见 [`docs/dsh-compatibility.md`](docs/dsh-compatibility.md)。
+
 ## 项目结构
 
 仓库根目录是发布到 npm 的 `@xmoon76/dsh-pi-tui` bundle。

package/cordis.patch.yml

@@ -110,9 +110,6 @@
 - id: tool-fs-search
   disabled: true
 
-- id: tool-str-replace-editor
-  disabled: true
-
 - id: skill-filesystem
   disabled: true
 

package/dist/builtins.mjs

@@ -1,4 +1,4 @@
-import { H as PI_TUI_EXTENSIONS_SERVICE, L as dshVersion } from "./src-zkySYmLZ.mjs";
+import { I as dshVersion, V as PI_TUI_EXTENSIONS_SERVICE } from "./src-BL4AomX5.mjs";
 import { TUI_STARTUP_SERVICE } from "./startup.mjs";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";

package/dist/extensions.mjs

@@ -1,3 +1,3 @@
-import { B as inject, H as PI_TUI_EXTENSIONS_SERVICE, U as API_VERSION, V as name, W as describeKey, z as apply } from "./src-zkySYmLZ.mjs";
+import { B as name, H as API_VERSION, R as apply, U as describeKey, V as PI_TUI_EXTENSIONS_SERVICE, z as inject } from "./src-BL4AomX5.mjs";
 import "./startup.mjs";
 export { API_VERSION, PI_TUI_EXTENSIONS_SERVICE, apply, describeKey, inject, name };

package/dist/index.d.mts

@@ -86,36 +86,6 @@ interface DraftImageStoreLike {
   values(): readonly DraftImage[];
 }
 //#endregion
-//#region src/diag.d.ts
-interface Diag {
-  debug(message: string, fields?: Record<string, unknown>): void;
-  info(message: string, fields?: Record<string, unknown>): void;
-  warn(message: string, fields?: Record<string, unknown>): void;
-  error(message: string, fields?: Record<string, unknown>): void;
-  /** Release the file handle, if one is open. */
-  dispose(): void;
-}
-//#endregion
-//#region src/tui-app.d.ts
-/** The compaction lifecycle phase the working row advertises: idle (no
- * compaction), summarizing (compaction/start seen, the summary is being
- * generated), or applying (the summary landed, the compacted surface is
- * being committed). Derived by the runner from compaction/start →
- * compaction/summary → compaction/end (foldCompactionEvent). */
-type CompactionPhase = 'idle' | 'summarizing' | 'applying';
-/** One queued inbox row for the queue pane (mirrors the agent Inbox's lists). */
-interface QueueItem {
-  /** The pending message id (agent inbox identity). */
-  id: string;
-  /** The message text, single-line display form. */
-  text: string;
-  /** next-turn followup vs next-step steer. */
-  mode: 'followup' | 'steer';
-  /** Plugin notice (e.g. a background-job completion): NOT steerable — it
-   * renders with its own marker and the hint drops the steer verbs. */
-  notice?: boolean;
-}
-//#endregion
 //#region src/skill-catalog.d.ts
 /**
  * The standing-scope skill catalog adapter: the SINGLE narrow seam between
@@ -153,6 +123,36 @@ interface HumanSkillCatalog {
   readonly complete: boolean;
 }
 //#endregion
+//#region src/diag.d.ts
+interface Diag {
+  debug(message: string, fields?: Record<string, unknown>): void;
+  info(message: string, fields?: Record<string, unknown>): void;
+  warn(message: string, fields?: Record<string, unknown>): void;
+  error(message: string, fields?: Record<string, unknown>): void;
+  /** Release the file handle, if one is open. */
+  dispose(): void;
+}
+//#endregion
+//#region src/tui-app.d.ts
+/** The compaction lifecycle phase the working row advertises: idle (no
+ * compaction), summarizing (compaction/start seen, the summary is being
+ * generated), or applying (the summary landed, the compacted surface is
+ * being committed). Derived by the runner from compaction/start →
+ * compaction/summary → compaction/end (foldCompactionEvent). */
+type CompactionPhase = 'idle' | 'summarizing' | 'applying';
+/** One queued inbox row for the queue pane (mirrors the agent Inbox's lists). */
+interface QueueItem {
+  /** The pending message id (agent inbox identity). */
+  id: string;
+  /** The message text, single-line display form. */
+  text: string;
+  /** next-turn followup vs next-step steer. */
+  mode: 'followup' | 'steer';
+  /** Plugin notice (e.g. a background-job completion): NOT steerable — it
+   * renders with its own marker and the hint drops the steer verbs. */
+  notice?: boolean;
+}
+//#endregion
 //#region src/surface-catalog.d.ts
 /** One effective command's discovery metadata (the official descriptor's
  * display fields; never a handler or a definition). */
@@ -584,17 +584,6 @@ declare function runningProfile(argv?: readonly string[], fallback?: string): st
  * @returns the resume command line, or undefined without a session.
  */
 declare function resumeCommand(profile: string, sessionId: string): string | undefined;
-/**
- * A launch-time open-lock refusal: the requested session is held by another
- * live dsh process (or its lock cannot be verified). Unlike a stale/missing
- * session id, this is NOT recoverable by falling back to a fresh session —
- * the user asked for a specific session and must resolve the holder first.
- * Thrown from the resume path and re-thrown past the resume catch so the
- * runner exits with the refusal as the error message.
- */
-declare class SessionLockRefusedError extends Error {
-  constructor(message: string);
-}
 /** One fold of a compaction lifecycle event over the runner's in-flight
  * compaction state. Pure (the firehose applies the returned surface
  * effects): dsh-compaction is not a peer, so the event is read
@@ -762,4 +751,4 @@ declare function recomposeBlank(ctx: Context, agent: {
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { AgentComposition, CompactionFold, CompactionSettleSurface, Config, HOST_COMMAND_CATALOG, InitialCatalogResolution, InterruptAgentLike, InterruptWriterLike, LOCAL_COMMANDS, PendingSubagentCall, QueueFoldResult, QueueInboxMessage, QueueNoticeSource, RecomposableSession, RecomposeOutcome, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, SessionLockRefusedError, ViewerOpenToken, apply, busyAfterTurnBoundary, commandRejectsImages, compactingFromLog, composeAgent, contextRefreshKind, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, interruptAgent, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, normalizeSkillInvocation, recomposeBlank, recordedPreset, resolveInitialCatalog, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure, teardownViewerForSessionSwap, viewerActionCapability };
+export { AgentComposition, CompactionFold, CompactionSettleSurface, Config, HOST_COMMAND_CATALOG, InitialCatalogResolution, InterruptAgentLike, InterruptWriterLike, LOCAL_COMMANDS, PendingSubagentCall, QueueFoldResult, QueueInboxMessage, QueueNoticeSource, RecomposableSession, RecomposeOutcome, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, ViewerOpenToken, apply, busyAfterTurnBoundary, commandRejectsImages, compactingFromLog, composeAgent, contextRefreshKind, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, interruptAgent, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, normalizeSkillInvocation, recomposeBlank, recordedPreset, resolveInitialCatalog, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure, teardownViewerForSessionSwap, viewerActionCapability };