@xmoon76/dsh-pi-tui 0.3.5 → 0.4.0-alpha.1

package/README.en.md

@@ -10,12 +10,24 @@ 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.
 
 ```sh
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@next
 dsh --profile pi-tui
 ```
 
 ![dsh-pi-tui](docs/dsh-pi-tui.png)
 
+## DSH compatibility and source validation
+
+The published package declares the lower-bound-only DSH peer contract `>=0.1.2-alpha.2`. Source validation does not change that contract or vendor DSH into this repository.
+
+When the target DSH version is not yet available from npm, validate against the official checkout pinned by commit SHA:
+
+```sh
+pnpm compat:dsh:source -- --dsh-dir "$HOME/project/deepseek-harness"
+```
+
+CI uses Source Mode for `next` and npm Mode for `main` and every tag. The source lane validates the complete official DSH tarball family, TUI presets, and the old-runtime boundary; the published `pi2dsh` ecosystem check is explicitly marked skipped until a compatible published combination exists. See [`docs/dsh-compatibility.md`](docs/dsh-compatibility.md) for the full workflow.
+
 ## Features
 
 ### Conversation and tools
@@ -31,6 +43,7 @@ dsh --profile pi-tui
 * Plan Review
 * Todo / Goal status
 * Human-readable terminal window titles
+* Bounded long-session windows with stable paging and live-follow position
 * No duplicate ghost Tool Cards after compaction / pruning
 
 `Ctrl+O` controls Tool and System details — and in fullscreen Focus it bulk-expands the recent Thought roots or collapses them all. `Alt+T` controls Thinking separately.
@@ -135,6 +148,8 @@ 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.
+
 Resolvable relative paths are canonicalized before submission.
 
 Clipboard images can be added with `Ctrl+V` and persisted through the DSH Attachment service.
@@ -168,132 +183,25 @@ Slash Commands registered by other plugins through `ctx.commands` are discovered
 
 ### Footer customization
 
-The status line is a **composable surface** — no plugin or shell needed
-for the common cases.
-
-`/settings` → Status line (or the `footer` key in the `dsh-pi-tui`
-settings document) selects the preset:
-
-| Value | Meaning |
-|---|---|
-| `default` (legacy `full`) | the classic two-row footer (status + stats) |
-| `compact` | the status row only (stats line hidden) |
-| `custom` | a versioned `footerLayout` (see below) |
-| `command` | a user-configured command renders the status surface (see below) |
-
-The first three values are selectable in the `/settings` panel; `command`
-is NOT in the panel — it can only be enabled through the USER-layer
-settings document (`footer: "command"` + `footerCommand`). The `/settings`
-Status line row offers exactly `default / compact / custom`.
-
-`/footer` is a hierarchical interactive configurator: pick a row first
-(Row Selector), then edit that row's items — `↑/↓` walks every item of
-the row in order (Left/Right are visual grouping only), `←/→` moves an
-item across sides, `Space` removes it, `A` opens a searchable Add Picker
-(filtered by label / id / description, with the highlighted item's
-description below), `M` enters Move Mode to reorder, and `Enter` opens
-the Item Editor (Style candidates previewed with the item's real render;
-semantic tones; Advanced edits prefix / suffix / importance with a
-one-keystroke Reset). The preview is composed by the real footer engine
-and — with the contextual help — pinned to the top of the panel; it never
-scrolls away at any terminal size. `S` on the Row Selector saves
-(persisted); `Esc` walks back page by page and closes on the first page
-without touching the active layout. Usable before any session exists.
-
-The Add Picker also offers `+ Create Custom Text` for user-defined static text items. Their text, default semantic tone, display name, and deletion are editable; definitions are read and persisted only from the USER layer. The definition tone is separate from the placement Tone, and the item can otherwise be shown/hidden, moved, and reordered like any other footer item.
-
-`footerLayout` is a nested settings object (schemaVersion 1, 1–2 rows,
-left/right zones, a separator, finite formatters, semantic tones,
-prefix/suffix, importance). The `/footer` configurator builds it
-interactively; the YAML shape is:
+`/footer` is the interactive Footer editor. You can combine builtin status items, change their side and order, choose a Style and Tone, edit Prefix/Suffix and Importance, and create your own Footer items.
 
-```yaml
-footer: custom
-footerLayout:
-  schemaVersion: 1
-  rows:
-    - left:
-        - id: agent-preset
-          format: compact
-        - id: model
-        - id: project
-        - id: context
-          format: full
-        - id: cache-hit
-        - id: token-usage
-          format: io
-        - id: performance
-          format: speed
-        - id: version
-          format: tui
-      right:
-        - id: focus-mode
-      separator:
-        text: " │ "
-        tone: textDim
-```
+Four item sources are supported:
 
-Builtin format choices are finite and use the existing `format` field (no
-second style schema): Model `badge` / `plain` / `compact`; Permission preset
-`badge` / `plain` / `compact`; Plan state `badge` / `plain`; Working directory
-`short` / `basename` / `full`; Git branch `plain` / `label`; Context `bar` /
-`percent` / `full`; Token usage `io` / `total` / `compact`; Cache hit `full` /
-`compact`; Performance `full` / `speed` / `latency` measures average time
-to first token; Turns/steps `both` / `turns` / `steps`; Version keeps `tui` / `dsh` /
-`both`. Omitting `format` continues to use each item's legacy default.
-
-Builtin item ids: `agent-preset`, `model`, `reasoning`,
-`permission-preset`, `sandbox-mode`, `approval-policy`, `plan-state`,
-`focus-mode`, `focused-seat`, `view-scope`, `cwd`, `project`,
-`git-branch`, `run-state`, `queue`, `tasks`, `agents`, `todo`,
-`context`, `cache-hit`, `token-usage`, `performance`, `turns-steps`,
-`stats-line`, `version`, `ext:*` (the legacy extension segments).
-An invalid `footerLayout` warns once and falls back to the default — the
-TUI always starts.
-
-`footer: command` hands the Status Surface to a user-configured command
-(Claude/Kimi style): the current status snapshot is serialized to JSON on
-the command's stdin (schemaVersion 1 — no secrets, no credentials, no
-prompts), and the command's stdout (sanitized: SGR colors and OSC 8
-hyperlinks only) renders the status surface. The Host's instruction
-surface (e.g. the Ctrl+C exit hint) always survives on top.
+- **Builtin Item** — Model, Context, Token, Tasks, Git branch, and other built-in status facts;
+- **Custom Text** — a user-created static text item;
+- **Custom Command Item** — a user-created dynamic command output that can be composed with other items;
+- **Extension Item** — a Footer item contributed by a plugin through the Stable Extension API.
 
-```yaml
-footer: command
-footerCommand:
-  schemaVersion: 1
-  command: "~/.config/dsh/statusline.sh"
-  timeoutMs: 300        # default 300, max 1000
-  refreshIntervalMs: 1000  # min 1000
-  maxRows: 1            # 1..2
-```
+On narrow terminals, builtins with compact forms shorten before lower-importance content is dropped. Runtime compaction never rewrites the Style you saved.
+
+A `/footer` Custom Command Item is different from `footer: command`: the former is one dynamic item that can sit next to Model, Context, and other items; the latter hands the whole Footer status surface to one user command.
 
-**Security:** the command is executed ONLY when it lives in the USER
-layer of your settings document. A repository/project-supplied
-`footerCommand` is never executed — command mode is disabled and the
-native layout applies. The command refreshes periodically according to
-`refreshIntervalMs` and renders at most two rows; failures (empty output,
-non-zero exit, timeout) fall back to the native layout automatically.
-
-### Extension footer items
-
-Plugins can contribute **configurable footer items** through the Stable
-extension API (`@xmoon76/dsh-pi-tui/extensions`): register a
-`FooterItemContribution` on the `chrome.footer.item` slot — a label and a
-plain-data `segment` (styled spans; the host strips any terminal control
-sequence, plugins never style the terminal). Users show/hide, reorder and
-zone-place the item in `/footer` exactly like a builtin item. Feature-detect
-the `slot.chrome.footer.item` capability before registering (it is
-advertised before any surface exists). The item's config identity is the
-canonical key `ext:<owner>/<id>` where the owner is the plugin's stable
-name — **stable across HMR**: a layout referencing an unloaded plugin's
-item keeps the reference and recovers automatically when the plugin
-reloads. An npm-scoped plugin name (`@scope/name`) is legal: its `/` is
-percent-encoded via `encodeURIComponent` in the key
-(`ext:%40scope%2Fname/<id>`); the id itself must
-not contain `/`. The legacy `chrome.footer.status` slot is unchanged: its
-segments aggregate into the single `ext:*` item. Full author guide:
-[docs/extension-api.md](docs/extension-api.md).
+For the full `/footer` workflow, Custom Text / Command items, YAML reference, security model, and troubleshooting, see:
+
+- [Footer customization guide](docs/footer-customization.md)
+- [Extension API for plugin authors](docs/extension-api.md)
+
+`/statusline` is an alias of `/footer`.
 
 ## Common keys
 
@@ -310,6 +218,7 @@ segments aggregate into the single `ext:*` item. Full author guide:
 | `Ctrl+T`      | Toggle the todo panel                               |
 | `Ctrl+R`      | Search input history                                |
 | `Ctrl+F`      | Search Transcript                                   |
+| `Ctrl+End`    | Jump to the latest Transcript output in fullscreen  |
 | `Ctrl+O`      | Expand / collapse Tool and System details; in fullscreen Focus, bulk-toggle the Thought roots |
 | `Alt+T`       | Expand / collapse Thinking                          |
 | `Ctrl+G`      | Edit current input in `$VISUAL`/`$EDITOR`           |
@@ -399,14 +308,52 @@ dsh-pi-tui:
 * DeepSeek Harness
 * Node.js `^22.19.0 || >=24`
 
-The project currently follows the DeepSeek Harness `0.1.1-rc.x` release line.
+### DSH/TUI version pairing (important)
+
+| TUI package line | Matching DSH line | Notes |
+|---|---|---|
+| `0.4.0-alpha.1` (`@next`) | `>=0.1.2-alpha.2` | Current prerelease; each release validates its concrete DSH family |
+| `0.3.x` (`@0.3`) | `0.1.1-rc.2` | Legacy runtime line |
+
+Do not mix the two 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. For the current `0.4.0-alpha.1`, install
+DSH first and then add the TUI to a profile:
+
+```sh
+npm install -g @deepseek-ai/dsh@0.1.2-alpha.3
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@next
+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 declared 0.4 support range is `>=0.1.2-alpha.2`; 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:
+Using a dedicated `pi-tui` profile is recommended. Once a stable 0.4 release
+exists, use the matching stable TUI channel (`@latest`); use `@next` for the
+prerelease channel:
 
 ```sh
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@next
 dsh --profile pi-tui
 ```
 
@@ -416,6 +363,15 @@ Resume an existing Session:
 dsh --profile pi-tui --session <session-id>
 ```
 
+### Source Mode (validation only)
+
+Source Mode is only for `next` CI and local compatibility validation. 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
@@ -630,6 +586,7 @@ Contributor-oriented repository structure and development rules are documented i
 | [docs/concurrency.md](docs/concurrency.md)             | Session concurrency               |
 | [docs/failure-model.md](docs/failure-model.md)         | Async failure / cancellation      |
 | [docs/perf-baseline.md](docs/perf-baseline.md)         | Performance baseline              |
+| [docs/local-development.md](docs/local-development.md) | Local development and worktree policy |
 | [docs/extension-api.md](docs/extension-api.md)         | Extension API                     |
 | [AGENTS.md](AGENTS.md)                                 | Contributor operating manual      |
 

package/README.md

@@ -10,12 +10,24 @@
 `dsh-pi-tui` 作为独立的 dsh bundle 安装到 profile 中，提供流式对话、工具调用、会话管理、Subagent、历史搜索、Shell、审批与设置等终端交互。模型、工具、Session、权限、Skills、Plan、Goal、Subagent 等运行时能力仍由 DeepSeek Harness 提供。
 
 ```sh
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@next
 dsh --profile pi-tui
 ```
 
 ![dsh-pi-tui](docs/dsh-pi-tui.png)
 
+## DSH 兼容性与源码验证
+
+发布包通过 `package.json` peer contract 使用 DSH `>=0.1.2-alpha.2`；源码验证不会修改这个发布契约，也不会把 DSH vendor 进本仓库。
+
+当目标 DSH 版本尚未发布到 npm 时，可以用固定 commit 的官方源码包做本地验证：
+
+```sh
+pnpm compat:dsh:source -- --dsh-dir "$HOME/project/deepseek-harness"
+```
+
+CI 中 `next` 使用 Source Mode，`main` 和所有 tag 使用 npm Mode。源码 lane 会验证完整的官方 DSH tarball family、TUI 预设和旧 runtime 边界；依赖已发布 `pi2dsh` 的生态检查会明确标记为 skipped。详细流程见 [`docs/dsh-compatibility.md`](docs/dsh-compatibility.md)。
+
 ## 功能
 
 ### 对话与工具
@@ -31,6 +43,7 @@ dsh --profile pi-tui
 * Plan Review
 * Todo / Goal 状态展示
 * 可读的终端窗口标题
+* 长会话按有界窗口浏览，并保留翻页与实时跟随位置
 * Compaction / prune 后不会出现重复的幽灵 Tool Card
 
 `Ctrl+O` 控制工具和系统详情;在全屏 Focus 下它整体展开最近几个 Thought root,或全部收起。`Alt+T` 单独控制 Thinking。
@@ -135,6 +148,8 @@ Shell 卡片默认只显示有限的输出预览，`Ctrl+O` 可以展开完整
 @"path with spaces/file.ts"
 ```
 
+`/image <path>` 也支持文件与目录补全；带空格、引号或 Windows 分隔符的路径会保留输入方言，目录可以继续展开。
+
 能够解析的相对路径会在提交时转换为明确的文件路径。
 
 支持通过 `Ctrl+V` 添加剪贴板图片，并使用 DSH Attachment 能力保存到 Session。
@@ -167,117 +182,25 @@ TUI 使用 DSH 提供的模型和设置服务。
 
 ### Footer 自定义
 
-状态行是一个**可组合表面**——常见场景无需插件或 shell。
+`/footer` 提供交互式 Footer 编辑器。你可以组合内置状态条目，调整左右位置、顺序、Style、Tone、Prefix/Suffix 和 Importance，也可以创建自己的 Footer 条目。
 
-`/settings` → Status line(或 `dsh-pi-tui` 设置文档中的 `footer` 键)
-选择预设:
+支持四类条目：
 
-| 值 | 含义 |
-|---|---|
-| `default`(旧名 `full`) | 经典两行 Footer(状态 + 统计) |
-| `compact` | 仅状态行(隐藏统计行) |
-| `custom` | 版本化 `footerLayout`(见下) |
-| `command` | 用户配置的命令渲染状态表面(见下) |
+- **Builtin Item**：Model、Context、Token、Tasks、Git branch 等内置状态；
+- **Custom Text**：用户创建的固定文本；
+- **Custom Command Item**：用户创建的动态命令输出，可和其他条目一起排列；
+- **Extension Item**：插件通过 Stable Extension API 提供的 Footer 条目。
 
-前三个值可在 `/settings` 面板选择;`command` **不在面板中**——它只能
-通过 USER 层设置文档(`footer: "command"` + `footerCommand`)启用,
-`/settings` 的 Status line 行只有 `default / compact / custom` 三个选项。
+在窄终端中，支持 compact 的内置条目会先自动缩短；空间仍不足时再按 Importance 隐藏低优先级内容。运行时 compact 不会修改你保存的 Style。
 
-`/footer` 是层级式交互配置器:先选行(Row Selector),再编辑该行的
-条目——`↑/↓` 在整行条目间顺序移动(Left/Right 只是视觉分组),
-`←/→` 左右换侧,`Space` 移除,`A` 打开可搜索的 Add Picker(按
-label / id / 描述过滤,选中项下方显示描述),`M` 进入 Move Mode
-排序,`Enter` 打开 Item Editor(Style 候选以条目的真实渲染作示例;
-Tone 语义色;Advanced 编辑 prefix / suffix / importance 并可一键
-Reset)。预览由真实 Footer 引擎合成,与 contextual help 一起固定在
-面板顶部,任何终端尺寸下都不会随列表滚动消失。Row Selector 页 `S`
-保存(持久化),`Esc` 逐页返回、在首页关闭且不影响当前生效布局。
-无会话时也可使用。
+`/footer` 的 Custom Command Item 和 `footer: command` 是两种不同能力：前者只是一个可以与 Model、Context 等混排的动态条目；后者把整个 Footer 状态表面交给一个用户命令。
 
-Add Picker 的末尾还可以选择 `+ Create Custom Text`,创建用户自定义的静态文本条目。创建后可编辑文本、默认语义色、显示名称,也可以删除;条目定义只从 USER 层读取并持久化。定义 Tone 与布局中的放置 Tone 分开,条目仍可在 `/footer` 中显示/隐藏、移动和排序。
+完整的 `/footer` 使用方法、Custom Text / Command、YAML 配置、安全模型和排错说明见：
 
-`footerLayout` 是嵌套设置对象(schemaVersion 1,1–2 行,左/右区域,
-分隔符,有限 formatter,语义 tone,prefix/suffix,importance)。
-`/footer` 配置器可交互地构建它;YAML 形状如下:
+- [Footer 自定义完整指南](docs/footer-customization.md)
+- [Extension API（插件作者）](docs/extension-api.md)
 
-```yaml
-footer: custom
-footerLayout:
-  schemaVersion: 1
-  rows:
-    - left:
-        - id: agent-preset
-          format: compact
-        - id: model
-        - id: project
-        - id: context
-          format: full
-        - id: cache-hit
-        - id: token-usage
-          format: io
-        - id: performance
-          format: speed
-        - id: version
-          format: tui
-      right:
-        - id: focus-mode
-      separator:
-        text: " │ "
-        tone: textDim
-```
-
-内置 format 是有限集合,继续使用现有的 `format` 字段(不新增第二套
-style schema):Model 为 `badge` / `plain` / `compact`;Permission preset
-为 `badge` / `plain` / `compact`;Plan state 为 `badge` / `plain`;Working
-directory 为 `short` / `basename` / `full`;Git branch 为 `plain` / `label`;
-Context 为 `bar` / `percent` / `full`;Token usage 为 `io` / `total` /
-`compact`;Cache hit 为 `full` / `compact`;Performance 为 `full` / `speed` /
-`latency`(平均首 token 时间);Turns/steps 为 `both` / `turns` / `steps`;
-Version 保留 `tui` / `dsh` / `both`。省略 `format` 时仍使用各条目的旧默认值。
-
-内置条目 id:`agent-preset`、`model`、`reasoning`、
-`permission-preset`、`sandbox-mode`、`approval-policy`、`plan-state`、
-`focus-mode`、`focused-seat`、`view-scope`、`cwd`、`project`、
-`git-branch`、`run-state`、`queue`、`tasks`、`agents`、`todo`、
-`context`、`cache-hit`、`token-usage`、`performance`、`turns-steps`、
-`stats-line`、`version`、`ext:*`(旧扩展段)。非法的 `footerLayout`
-会警告一次并回退到默认布局——TUI 始终能启动。
-
-`footer: command` 把状态表面交给用户配置的命令(Claude/Kimi 风格):
-当前状态快照以 JSON 序列化到命令的 stdin(schemaVersion 1——不含
-secret、凭据、提示词),命令的 stdout(经过净化:仅保留 SGR 颜色与
-OSC 8 超链接)渲染状态表面。Host 的指令表面(如 Ctrl+C 退出提示)
-始终叠加在最上层。
-
-```yaml
-footer: command
-footerCommand:
-  schemaVersion: 1
-  command: "~/.config/dsh/statusline.sh"
-  timeoutMs: 300        # 默认 300,最大 1000
-  refreshIntervalMs: 1000  # 最小 1000
-  maxRows: 1            # 1..2
-```
-
-**安全:** 只有当命令位于你的设置文档的 USER 层时才会被执行。
-仓库/项目提供的 `footerCommand` 永远不会被执行——命令模式被禁用并
-回退到原生布局。命令按 `refreshIntervalMs` 周期刷新,每次最多输出 2 行;失败(空输出、非零退出、超时)自动回退到原生布局。
-
-### 扩展 Footer 条目
-
-插件可以通过 Stable 扩展 API(`@xmoon76/dsh-pi-tui/extensions`)贡献
-**可配置的 Footer 条目**:在 `chrome.footer.item` 槽位注册一个
-`FooterItemContribution`——包含 label 与纯数据 `segment`(带样式的
-span;Host 会剥离任何终端控制序列,插件永远不能直接给终端上样式)。
-用户可在 `/footer` 中像内置条目一样开关、排序、左右放置。注册前请
-先 feature-detect `slot.chrome.footer.item` 能力(该能力在任何 surface
-存在之前就已声明)。条目的配置身份是规范键 `ext:<owner>/<id>`,其中
-owner 是插件的稳定名称——**跨 HMR 稳定**:引用已卸载插件条目的布局
-保留引用,插件重载后自动恢复。npm scoped 插件名(`@scope/name`)合法:
-其 `/` 在键中按 `encodeURIComponent` 百分号编码(`ext:%40scope%2Fname/<id>`);
-id 本身不得包含 `/`。旧的 `chrome.footer.status` 槽位不变:
-其 segment 聚合为单一的 `ext:*` 条目。完整作者指南:
-[docs/extension-api.md](docs/extension-api.md)。
+`/statusline` 是 `/footer` 的别名。
 
 ## 常用按键
 
@@ -294,6 +217,7 @@ id 本身不得包含 `/`。旧的 `chrome.footer.status` 槽位不变:
 | `Ctrl+T`      | 切换 Todo 面板              |
 | `Ctrl+R`      | 搜索输入历史                 |
 | `Ctrl+F`      | 搜索 Transcript          |
+| `Ctrl+End`    | 全屏时跳到最新 Transcript 输出 |
 | `Ctrl+O`      | 展开 / 折叠工具和系统详情;全屏 Focus 下整体切换 Thought root |
 | `Alt+T`       | 展开 / 折叠 Thinking       |
 | `Ctrl+G`      | 使用 `$VISUAL`/`$EDITOR` 编辑输入 |
@@ -373,14 +297,49 @@ dsh-pi-tui:
 * DeepSeek Harness
 * Node.js `^22.19.0 || >=24`
 
-项目当前跟随 DeepSeek Harness `0.1.1-rc.x` 版本线开发。
+### DSH 与 TUI 版本对应（重要）
+
+| TUI 包版本 | 对应 DSH 版本 | 说明 |
+|---|---|---|
+| `0.4.0-alpha.1`（`@next`） | `>=0.1.2-alpha.2` | 当前预发布线；按每个发布版本的具体 DSH family 验证 |
+| `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。`0.4.0-alpha.1` 的推荐安装顺序如下（先装 DSH，再把
+TUI 装入 profile）：
+
+```sh
+npm install -g @deepseek-ai/dsh@0.1.2-alpha.3
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@next
+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-alpha.2`；每个发布版本都会验证具体的
+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：
+推荐使用单独的 `pi-tui` profile。稳定版发布后，使用与 DSH 版本匹配的
+TUI channel（稳定版用 `@latest`，预发布版用 `@next`）：
 
 ```sh
-dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@next
 dsh --profile pi-tui
 ```
 
@@ -390,6 +349,15 @@ dsh --profile pi-tui
 dsh --profile pi-tui --session <session-id>
 ```
 
+### Source Mode（仅验证）
+
+Source Mode 只用于 `next` 的 CI 和本地兼容性验证，不是发布或用户安装方式。它从 `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。
 
 ### 更新
@@ -606,6 +574,7 @@ packages/pi-tui/AGENTS.md
 | [docs/concurrency.md](docs/concurrency.md)             | Session 并发                   |
 | [docs/failure-model.md](docs/failure-model.md)         | Async failure / cancellation |
 | [docs/perf-baseline.md](docs/perf-baseline.md)         | 性能基线                         |
+| [docs/local-development.md](docs/local-development.md) | 本地开发环境与 worktree 约定       |
 | [docs/extension-api.md](docs/extension-api.md)         | Extension API                |
 | [AGENTS.md](AGENTS.md)                                 | Contributor operating manual |
 

package/cordis.patch.yml

@@ -42,24 +42,23 @@
     - id: authorization
       name: '@deepseek-ai/dsh-authorization'
 
-    # The agent-preset roster. The SHIPPED root is an assembly fact of this
-    # bundle: the four presets (standard/code/minimal/cordis) travel with the
-    # package under config/agent-presets and carry `system` trust. The
-    # expression reads the root from the startup service, so it resolves only
-    # after `tuiStartup` exists — the web bundle's `webserver` row pattern
-    # (no `!!js` at boot time, no HMR race). The writable root is
-    # `dsh-agent-presets`' own default (`includeUserRoot`):
-    # `$DSH_HOME/.agent-presets`, where a person authors their own presets.
+    # Consume DSH 0.1.2's official shipped presets directly. The upstream
+    # service defaults includeShippedRoot/includeUserRoot to true, so this
+    # bundle deliberately owns no duplicate standard/ptc/minimal/cordis root.
+    # The legacy persisted id `code` is normalized at the data boundary to
+    # `ptc`; it is not another preset row.
     - id: agent-presets
       name: '@deepseek-ai/dsh-agent-presets'
-      inject: [tuiStartup]
       config:
         default: standard
-        roots:
-          - path: !!js ctx.tuiStartup.shippedPresetRoot
-            trust: system
 
-    # Host-plane TypeScript runtime: the `code` preset's `tool-presentation`
+    # The official standard preset enables per-session subagent model
+    # selection. Its tool-subagent row requires this Host service when it
+    # mounts; without the row the default standard composition throws.
+    - id: subagent-model-selection-settings
+      name: '@deepseek-ai/dsh-tool-subagent/model-selection-settings'
+
+    # Host-plane TypeScript runtime: the `ptc` preset's `tool-presentation`
     # row waits for `codeRuntime` and fails the preset at mount without it
     # (same host row the web bundle inserts).
     - id: code-runtime
@@ -85,10 +84,12 @@
 #
 # Rows that STAY on the host plane (not listed): `tools` (registry), `shell-env`
 # (publishes the DSH env the model's shell sees), `subagent` + its spawn/fork
-# backends (process singletons), `tool-subagent-report` (host singleton), the
-# goal/jobs/compaction services and their commands, `permission`, `approval`,
-# `sandbox*`, `fs-observation-policy`, `spill*`, `timeout-policy`,
-# `repeat-tool-reminder`, `session-*`, `token-meter`.
+# backends (process singletons), `tool-subagent-report` (host singleton),
+# `subagent-model-selection-settings`, the goal/jobs/compaction services and
+# their host infrastructure, `permission`, `approval`, `sandbox*`,
+# `fs-observation-policy`, `spill*`, `timeout-policy`, `repeat-tool-reminder`,
+# `session-*`, `token-meter`. `command-goal` is disabled below and reintroduced
+# only by presets that own that command in their scoped composition.
 
 - id: tool-bash
   disabled: true
@@ -114,6 +115,9 @@
 - id: tool-skill
   disabled: true
 
+- id: command-goal
+  disabled: true
+
 - id: tool-goal
   disabled: true
 

package/dist/builtins.mjs

@@ -1,5 +1,5 @@
+import { H as PI_TUI_EXTENSIONS_SERVICE, L as dshVersion } from "./src-syk6h8J9.mjs";
 import { TUI_STARTUP_SERVICE } from "./startup.mjs";
-import { I as dshVersion, V as PI_TUI_EXTENSIONS_SERVICE } from "./src-B93JMbsv.mjs";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/builtins.ts

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-syk6h8J9.mjs";
 import "./startup.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-B93JMbsv.mjs";
 export { API_VERSION, PI_TUI_EXTENSIONS_SERVICE, apply, describeKey, inject, name };