@xmoon76/dsh-pi-tui

dsh-pi-tui

English | 简体中文

基于 Pi TUI 的 DeepSeek Harness 终端前端。

dsh-pi-tui 作为独立的 dsh bundle 安装到 profile 中，提供流式对话、工具调用、会话管理、Subagent、历史搜索、Shell、审批与设置等终端交互。模型、工具、Session、权限、Skills、Plan、Goal、Subagent 等运行时能力仍由 DeepSeek Harness 提供。

安装到 DSH Profile

Stable / latest

稳定版是普通用户的推荐渠道。请先安装 DSH，再将 TUI 添加到 pi-tui profile：

npm install -g --allow-scripts=@deepseek-ai/dsh-subprocess-local,koffi,node-pty @deepseek-ai/dsh@latest
dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@latest
dsh --profile pi-tui

Next / npm 线（验证）

预览安装使用 DSH 的 alpha channel 与 TUI 的 next channel；安装 DSH 时需要显式允许其原生安装脚本：

npm install -g --allow-scripts=@deepseek-ai/dsh-subprocess-local,koffi,node-pty @deepseek-ai/dsh@alpha
dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@next
dsh --profile pi-tui

这两个 channel 今天不构成可安装的兼容 pair。 它们只是通道指针：当前 @deepseek-ai/dsh@alpha 指向 0.2.1-alpha.5，而 @xmoon76/dsh-pi-tui@next 仍指向 0.5.2-rc.1（peer floor >=0.2.0-rc.2，npm semver 不接受不同 major.minor.patch tuple 的 prerelease）。请以下方版本对应表和 兼容性指南 的通用匹配原则为准；稳定版 0.5.3 发布在 @latest 而不是 @next，因此这两个移动 channel 上没有可安装的兼容组合。 本 checkout 的精确验证请使用 pnpm compat:dsh:npm。

隔离的 npm 驱动仍按本 checkout 声明的精确 DSH 版本运行，并执行完整的 build/test/package 路径：

pnpm compat:dsh:npm

具体的稳定版最低版本、next 兼容范围和回退路径见兼容性指南。

环境要求

• DeepSeek Harness
• Node.js ^22.19.0 || >=24

DSH 与 TUI 版本对应（重要）

TUI 包版本	对应的官方 DSH tags	说明
0.5.3（stable / @latest）	dsh-v0.2.1-rc.2、dsh-v0.2.1-rc.3	当前已发布稳定版；peer floor 仍是 0.2.1-rc.2，本仓库当前 checkout 的精确验证目标已前移到 0.2.1-rc.3
0.5.1（stable，历史）	dsh-v0.2.0-rc.2	上一稳定版；最低与精确验证目标均为 0.2.0-rc.2 family
0.5.2-rc.1（next 通道预览，已发布）	dsh-v0.2.0-rc.2	上一轮 next 预览：已发布到 npm next 通道（2026-10-17）；整套 peer floor 仍是 >=0.2.0-rc.2，不覆盖 0.2.1-rc.2
dsh-v0.2.1-rc.1（无配对 TUI）	无	该中间版本没有本矩阵宣称兼容的已发布 TUI；不要为它复用 0.5.3
0.5.0（stable，历史）	dsh-v0.1.7-rc.2、dsh-v0.2.0-rc.1	上一稳定版；最低 0.1.7-rc.2，精确验证目标 0.2.0-rc.1
0.4.9（stable，历史）	dsh-v0.1.7-rc.2	上一稳定版；0.1.7-rc.2 runtime 的兼容 TUI
0.4.8（stable，历史）	dsh-v0.1.7-rc.1	上一稳定版；0.1.7-rc.1 runtime 的兼容 TUI
0.4.6（stable，历史）	dsh-v0.1.5-rc.1、dsh-v0.1.5-rc.2	上一稳定版；0.1.5 runtime 的兼容 TUI
0.4.7-alpha.2（next，历史）	dsh-v0.1.6-alpha.2	上一条 next 线；0.1.6-alpha.2 runtime 的兼容 TUI

不要把稳定线与 @next 预发布线混装。0.5.3 是当前已发布稳定版：它的最低 DSH 版本（peer floor）仍是 0.2.1-rc.2 family，而已发布的 0.5.3 与后续的 0.2.1-rc.3 也已实测配对（官方 preset assembly 在 rc.3 下通过）；本仓库当前 checkout 的精确验证目标前移到 0.2.1-rc.3，这不改变 0.5.3 已发布包的身份与 floor。中间的 dsh-v0.2.1-rc.1 没有配对 TUI，0.5.2-rc.1 是上一轮已发布到 npm next 通道的 预览身份（配对 0.2.0-rc.2；它不覆盖 0.2.1-rc.2，因此新的稳定线使用 0.5.3 身份）。上一稳定版 0.5.1 继续配对 0.2.0-rc.2：它把整个 DSH peer floor 提升到 >=0.2.0-rc.2（Question 生命周期消费 rc.2 才发布的公开契约）。更早的 0.5.0 保持 >=0.1.7-rc.2 floor 不变（精确验证目标 0.2.0-rc.1）；旧 runtime 会在正常的 不兼容边界以非零状态失败，请按上表安装配对的 TUI 线。上方的版本对应表是已发布 线的摘要；通用版本匹配原则与回退/诊断流程见兼容性指南；要查看 @next 的最新集成 状态，请看 next 分支 README。

新的 Agent preset 使用当前 roster 中选定的 id。DSH 允许合法的自定义 code preset；只要当前 roster 存在它，显式输入和持久化状态都会保留 code。 DSH V3 migration 负责历史 session header/selection 的 code -> ptc 转换； 当前 projection 会原样保留合法的自定义 code。省略请求的 legacy settings default 不再做任何别名映射：当前 roster 没有声明就是无效偏好。

Profile management

更新已安装的 TUI：

dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui

查看已安装插件：

dsh plugin --profile pi-tui -- list

卸载：

dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui

恢复已有 Session：

dsh --profile pi-tui --session 

功能

对话与工具

• 流式 Markdown 输出
• Thinking 折叠与展开
• Tool Call 卡片及运行状态
• Tool / System 详情折叠
• Transcript 全文搜索
• 长会话历史折叠
• Context、Token、模型和运行状态显示
• Approval 与 ask_user_question 交互
• Plan Review
• Todo / Goal 状态展示
• 可读的终端窗口标题
• 长会话按有界窗口浏览，并保留翻页与实时跟随位置
• 超长用户 Prompt 默认折叠为 head + marker + tail；普通与全屏非 Focus 下 Ctrl+O 展开、收回
• Compaction / prune 后不会出现重复的幽灵 Tool Card

Ctrl+O 控制工具和系统详情，并在普通模式与全屏非 Focus 下展开/收起超长用户 Prompt;全屏 Focus 下它整体展开最近几个 Thought root 或全部收起，超长用户 Prompt 改用点击提示行（或搜索命中）展开、Ctrl+O 收回。Alt+T 单独控制 Thinking。

Conversation display

/display 在三种展示预设间切换：full（默认）是普通 Transcript 展示；focus 将当前回合的 Thinking、Tool Call 和中间回复聚合为一个实时更新的 Thought 区块；compact 把连续的过程折叠为带 Header + Think: / Action: 预览的 Activity 段，会话与 assistant 的中间输出仍按时间顺序可见，注入的 notice / relay / recall 改为独立呈现（相邻的环境类注入合并为可展开的 Context 簇），展开用鼠标点击或 Ctrl+O。/settings 的 Display 行提供同一组取值并持久化；/focus 仍作为兼容命令保留。

需要查看过程时可以展开，关闭 Focus 后恢复普通 Transcript 展示。全屏 Focus 中可以按 Thought root 批量展开/收起,也可以单独点击卡片;切换或缩放时会保留 viewport。展示预设只影响界面投影，不修改 Session 中保存的事件。

沟通策略

/settings 提供两个独立的沟通设置。Progress updates 控制 Agent 工作时的中途更新节奏：milestones（默认）只在完整的阶段结束、方向实质变化或需要用户输入时简短汇报，不为「刚发现一个局部结论」而打断；frequent 在较长的多步工作中持续带用户跟进；off 完全不做过程叙述。Response style 控制可见回复的密度：default 不附加表达指导，concise 紧凑且结果优先，explanatory 补充原理、架构与取舍。两项切换都在下一次提示词组装时生效，无需重启 Agent，并跨会话保存。Focus 是展示能力而非第三个偏好：进入 Focus 时进度更新节只是暂时失效（不生成只含进度的中间消息），保存的节奏偏好不变，Response style 在 Focus 下仍然生效。

Session

支持 DSH 持久化 Session，包括：

• 新建和恢复 Session
• Session 切换
• 重命名
• Fork
• Rewind
• Session lineage
• /export — 完整 Session 归档(含子代理与附件),保存到 Client 本地目录
• /transcript — 可读 Markdown 对话记录,保存到 Client 本地目录

使用：

/sessions
/fork
/rewind
/export
/transcript

空闲且编辑器为空时也可以快速按两次 Esc 打开 Rewind。

Rewind 会从选中的历史 User Turn 创建新的 Child Session，并把对应 Prompt 放回编辑器。原 Session 不会被修改。

输入历史

Ctrl+R 打开输入历史搜索。

支持三个范围：

• Current session
• Current directory
• All directories

历史结果包含 Prompt、工作目录、时间和 Session 信息。选中历史后只恢复到编辑器，不会立即发送。

普通的 ↑ / ↓ 仍用于快速浏览最近输入。

Subagent 与 Task Center

/tasks 打开完整 Task Center，显示当前 Session 中仍由 Job Registry / Subagent catalog 跟踪的工作；Footer 的 ↓（仅在光标位于编辑器最后一个可视行时）打开按需的 Quick 窗口，它默认不占行、出现在整个 Footer 之下。选中 Job 后进入全屏 Job 工作区：顶部一行显示 Job 身份、主题状态与大写状态及 [GAP]/[ERROR]/[SETTLED] 事实，下面是真实进度/说明、命令摘要与 Output/Command 阅读标签。Output 是官方非消耗式的实时输出预览（可滚动、可搜索，并明确标注为保留尾部而非完整历史），Command 页可阅读并按原文复制 shell 命令。工作区不会消耗模型的 job_output 游标，也不写入会话历史。

Task Center 的 ACTIVE / TRACKED 是展示范围：ACTIVE 只显示当前活动项，TRACKED 显示当前跟踪源（Job Registry / Subagent catalog）仍列出的全部项；TRACKED 不是 Session 执行历史。DSH 0.1.7 会在普通前台 bash / pwsh 执行期间临时注册 Job，使其可以在 Task Center 中观察和停止；如果命令在前台等待内完成，DSH 会移除该临时记录，最终结果仍保留在 Transcript 的 tool card 中。显式 run_in_background: true 或被提升为后台的 Job 在完成后，只要 Job Registry 继续保留其记录，就仍可在 TRACKED 中查看。

/plugins 是 /settings → Plugins 的深链：两者使用同一个 Settings 全屏 lease 与同一个 Plugin Manager 页面，不再有独立的插件全屏界面，也不会新建或切换 Session。目录固定为 TUI & Extensions / Official DSH / Third-party / Experimental（实验组最后），可搜索、筛选、查看来源与状态，并从官方目录执行安装、启用/禁用与删除；结果以 Host 实际返回的版本、重启要求和错误为准。≥120 列且能留出至少 6 行真实业务正文时同屏显示 类别 | 插件列表 | 详情；76–119 列按键盘焦点显示 类别 | 列表 或 列表 | 详情（列表 | 详情 同样要求至少 6 行真实业务正文，不足则退化为单栏），

默认 **关闭**。支持三种模式：

```text
off            不添加署名指引（默认）
product        官方 Co-Authored-By 署名
product-model  官方署名 + Assisted-By: 
/

这是 Agent 指引（prompt policy），不是仓库级强制：dsh-pi-tui 不会安装 Git 钩子、不改写任何 git commit 命令、也不探测仓库。product-model 的 provider/model 由 DSH 官方模型选择直接注入（切换模型后下一次请求生效）。

边界说明：

• ! / !! 用户 Shell 和你自己终端里的手动提交完全不受影响；
• 不安装任何 prepare-commit-msg 钩子，不修改已有钩子；
• 使用 minimal preset 时不生效：该 preset 的 persona 是完整 system prompt （complete: true），会替换掉其它全部 section；既有的 TUI 指引（Progress updates、 Response style、Focus）在该 preset 下同样是这种既有行为；
• 不需要 GitHub 凭证/API；不修改 Author/Committer 身份；
• 模型理论上可能忽略或写错指引——这是有意的取舍：用低侵入的指引替代一整套 Git 生命周期子系统。

文件引用与图片

输入 @ 可以搜索和补全工作区文件：

@src/index.ts
@"path with spaces/file.ts"

/attach 是统一的 Client-local 图片/文件入口；/image 保持图片专用兼容语义。两者都支持文件与目录补全；带空格、引号或 Windows 分隔符的路径会保留输入方言，目录可以继续展开。

能够解析的相对路径会在提交时转换为明确的文件路径。

支持通过 Ctrl+V 添加剪贴板图片，并使用 DSH Attachment 能力保存到 Session。

模型与运行设置

TUI 使用 DSH 提供的模型和设置服务。

常用入口：

/model
/settings
/status
/login
/permission
/plan
/goal
/compact
/footer
/statusline

模型切换、Reasoning Effort、权限 Preset、Plan 和 Goal 都沿用 DSH 对应的运行时语义。/model 的候选完全来自 Host 的模型目录：rc.2 的 deepseek-flash 以精确 (provider, model) 身份出现（显示名 DeepSeek-V4.1-Flash 不当作 ID），选择后写回官方 Session/global 默认；部署覆盖目录不再提供该 ID 时不会凭空显示。

/settings 打开一个真正的全屏工作区，三栏 / 两栏 / 单栏只是同一套 分类 → 设置行 → 详情 三层的投影：宽屏同时显示三栏，中屏按当前层显示 分类 + 设置行 或 设置行 + 详情，窄屏只显示当前层。所有宽度上 Right 只前进一层， Left 返回一层（在最外层无效）；Enter 遵循相同层级，Esc/Backspace 逐级返回， 最外层关闭工作区。Tab/Shift+Tab 不承担导航，底部操作栏始终固定在最后一行。多栏编辑态仍 保留 [Details] 焦点标识；只有标题会占掉唯一内容行时才让位。 它展示 Appearance / Conversation 的真实事实：主题的 source-qualified 原始值与友好名称、 Icon style、Transcript display 的运行时当前值与持久偏好、Thinking detail 的当前运行 态，以及每个条目的配置来源 Scope 与 backend 就绪状态；R 重新读取；浏览与选择本身都不写入配置。 普通配置详情只保留查看：它没有内置复制动作，也没有替代的复制入口。About 的 c/C 只 复制 About 自己的事实（运行时、Session 身份、统计、性能与 Context），不会复制配置页字段。

About 的复制入口只留在键盘上：选中一事实按 c 复制该事实的精确原始值（动作栏只在它真的 画在屏幕上时提示 c copy fact），按 C 把整份 About 报告复制到剪贴板；正文里最多只有 一个 Copy All [C]，每条事实后面不再有 Copy [C] 按钮，点击普通事实也不会复制。 Shift+C 在分类栏焦点下同样可用。复制仍只证明已交给本地剪贴板交付路径，不写入任何配置。

/status 是 /settings 的真实别名：同一 handler、同一初始 About 焦点与同一套读取；无 Session 时两者都不创建会话、不读统计。/footer 与它的别名 /statusline 直接打开同一个 Settings 全屏工作区的 Appearance → Configure footer layout 页；裸 /keybindings 同样直接打开 Input & Terminal → Keyboard shortcuts 页。两者共用唯一 Settings lease、唯一底栏和原有 的 Footer / Keybinding 保存权威，不再打开第二个 overlay。关闭这两个编辑页会直接回到所属设置行的 Rows 列表（不经过中间的 Detail 面板），下一次返回键即到分类栏。在两个页面的根状态（Footer 行选择器、 键盘快捷键在搜索为空时的列表）按 ← 与 Esc 一样返回来源设置行，底栏会显示 ← Back；Footer 有未保存修改时 ← 先打开 Save/Discard/Keep 确认，进入行编辑器后 ← 仍是切换左右分区， 搜索框非空时 ← 仍只移动光标。 Settings 的一级分类是固定的 About / Models / Account / Agent / Appearance / Conversation / Input & Terminal / Tools / Plugins， 并且只在扩展设置注册表确实有设置行时才在末尾追加 Extensions；/settings （以及 /status）默认落在 About。Extensions 的增删与同一 id 重新注册都会先作废旧帧的 键盘与鼠标授权，重绘完成前只有 Esc 还能安全返回。

Extensions 是真实配置分类而不是过渡入口：Rows 每次只显示一个注册 owner 的实时设置； 组序按该 owner 在注册表全局 order ASC, id ASC 流中首次出现的顺序，组内保持注册表原顺序。 至少两组时 Tab / Shift+Tab 循环切换组（落在目标组第一行），↑↓、Home/End、翻页与滚轮 只移动组内设置；只有一组时保留原有区域焦点键。标题栏先显示 [i/N] 再显示组名，窄屏先截断 组名而不是位置；Rows 面栏按宽度退化为 Rows (m) · 组名 → Rows (m) · i/N → Rows (m)。 每行进入原生 Detail/Choice：Owner 与 ID 显示原始值，未注册候选值的设置只读，当前值不在候选里 会明确说明而不会自动选中；只有显式 Confirm 才经 SettingsRegistry.applyDetailed 写入运行中的 扩展，accepted 后回读一致才 Verified，插件拒绝显示 Not saved 并把健康错误只记在发起调用 的 owner 上，被更新版本取代或已卸载则如实报告而不伪装成插件拒绝。扩展设置只作用于运行中的 插件，不写 TUI 设置文档或 Host profile；同一 id 的 HMR 重注册会作废旧确认/重试/结算。Models 是原位页：列出 Host 的 provider 目录、API key 是否已配置（只是存在性， 不是连通性测试）与 DeepSeek Account 入口；可查看 provider 事实、在遮蔽输入中写入/清除 API key、 完成 Add Provider 草稿向导，以及发起 provider-native 登录（页面内持续显示 URL、提示与取消）。 Account 是独立的 DeepSeek Account 页：显示 Host 的登录状态、浏览器授权 URL 与 SSH 隧道提示、 以及各自独立的 Profile / 充值钱包 / 赠送钱包状态（失败不伪造为 0），可显式取消当前 attempt、刷新， 并在二次确认后 sign out；关闭页面不会取消已经开始的浏览器登录。/login 与 /logout 现在只解析目标并 打开对应页面（/login 打开 Models、已知 route 进详情、已知/新 ref 进 API Key Reference、新 route 预填 Add Provider、deepseek-account 进 Account；/logout 打开已存凭据列表或单一清除确认），最终 写入/清除必须在页面里明确确认。Account 授权与普通 provider flow 分开：Account 只通过官方 PlatformAccount 与 Host 的 loopback /oauth/callback 登录，不会被当作普通 credential record 清除。

其中 Theme、Transcript display、Icon style、Transcript detail、Thinking detail、Progress updates、Response style 七行，以及 Tools 里的 Visual tools 开关，都可以直接修改：在 L1 设置行按 Right 或 Enter，或点击 [Change…] / 可见的 Detail 内容，即可在同一 L2 详情中打开 候选选择；当前值与 Runtime / Persisted 事实留在同一详情事实区，并与候选列表独立滚动。Up/Down/Home/End 移动候选，PgUp/PgDn 和事实区上的滚轮只滚动详情事实，候选区滚轮独立滚动候选； 选择期间的复制键不复制任何内容，也不会提交候选。 Enter 或点击 [Confirm] 明确确认，Left/Esc/Backspace 或 [Cancel] 取消并直接回到 L1，零写入。L2 浏览/已结算时，Enter 可重新打开可写行的选择；pending 写入时不触发新选择。若当前候选身份已滚出可见区域，第一次 Enter 只将其重新显示，之后才能确认； 44×8 短屏在长身份需要空间时先省略可选的 Choose value 标题；若仍不足，再将事实区压到只保留旧 Value 的一行。只有完整身份、Confirm 与 Enter confirm 同屏可见时才能确认，超过剩余容量仍拒绝写入。只有实际绘制出来的 按钮与候选行可以点击。确认后走既有的串行整文档写入路径落盘，再从权威来源重读目标字段核对： 详情把两类事实分开显示：以运行态为主的行（Icon style、Transcript display、Progress updates、 Response style、Git attribution、Home/End keys、Mouse wheel lines、Notifications、 Notification method、Terminal progress）用 Value 呈现已生效的运行值、另用 Persisted 呈现存储值； 主事实是持久值的只有 Configured theme、Tools 下的 Visual tools、Submit while busy 与 Fullscreen，它们因此额外画出 Runtime 行（如当前 palette、下一次忙时提交策略、当前 transcript 模式）。 [current] 是另一件事：Configured theme 与 Transcript display 按持久偏好标记，Icon style、 Progress updates、Response style 按实时值标记；Tools 下的 Visual tools 单独一类，它的候选项 [current] 反映 Host 配置值（state.enabled），运行态注册是否生效另由 Runtime 行表达。 两类行都会显示 Saving… / Verified / Not saved · 原因 / Commit accepted · verification unavailable / Outcome unknown · 原因，只有写入完成、backend ready 且权威回读一致才显示 Verified； 被拒绝的写入会先重读权威：仍停留在请求起点值才报 Not saved，出现第三个值、已是目标值或无法读取 则如实报 Outcome unknown；写返回成功但权威可读地不一致同样按失败显示，而不是 "verification unavailable"。backend 不 ready 时主题不会被应用或写入；显示预设可以先在本机生效， 此时会明确说明未能保存，而不是假装保存成功。插件主题在确认时再次按 source-qualified 身份解析， 已卸载的插件主题标记为 unavailable 并拒绝确认，不会退化成同名文件主题。这三类写入器互不混同： Icon style、Progress updates、Response style 先作用于各自的实时 owner（图标调色板；Agent 提示词实际读取的同一份 progress/response state 对象），再经唯一串行整文档写入落盘；Transcript detail（与 Ctrl+O 同一份开关）与 Thinking detail（与 Alt+T 同一份开关）是纯运行态， 没有持久字段，详情里明确写 not applicable — runtime-only，其 Verified 只代表运行态已生效。 三者的 [current] 标记实时生效值（先应用后落盘），Persisted 另行显示文档里的原始存储值 （未声明显示 not set，文档不可读显示 unknown）；归一化后的回退值永远不会伪装成已保存值。 Configured theme 与 `Tra