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 | 当前已发布稳定版；最低与精确验证目标均为 0.2.1-rc.2 family | | 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。中间的 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 线。完整的历史兼容矩阵和 fallback 命令见兼容性文档；要查看 @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 <session-id>

功能

对话与工具

• 流式 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 打开当前 profile 的全屏 Plugin Manager：目录固定为 TUI & Extensions / Official DSH / Third-party / Experimental（实验组最后），窄屏单栏、宽屏双栏，可搜索、筛选、查看来源与状态，并从官方目录执行安装、启用/禁用与删除；结果以 Host 实际返回的版本、重启要求和错误为准。正在提供当前界面的 dsh-pi-tui 只读且不可从自身界面禁用或移除。/settings 的顶级 Plugins 分类原地打开同一页面，返回时保留 Settings 的分类、滚动与选择。

Experimental 组的 14 个官方 rc.2 实验包在 Detail 中给出固定的终端可用面与限制/风险说明（Web-only、Host-only、B04 的 WEB_ONLY/Host 行未挂载（Owner 已接受）、B13/B14 的已验证 one-shot/provider 边界等），这些说明只随精确官方包身份出现，不随启用状态伪装成 Host 能力通过；升级指引按 Host 事实区分「随 DSH 发行升级」「profile 包先 Remove 再显式 Install」「官方 on-demand 目标」和「当前 TUI 由外部管理」，不提供原地更新、版本选择器或静默重装。

Subagent 按完整 lineage 显示，包括嵌套创建的 descendant：

main
├─ subagent A
│  └─ subagent B
└─ subagent C

浏览器会区分：

• continuable
• one-shot
• running / inactive
• nested descendant
• Job Registry 跟踪的 Job（含运行中的前台 shell）

Footer ↓ 打开的 Quick 窗口默认不占行，只在编辑器最后一个可视行按 ↓ 时展开到 Footer 之下：↑↓ / PgUp / PgDn 选择，Enter 用真实任务身份打开既有详情，↑（首行）或 Esc 返回编辑器并保留草稿；列表末尾的 “Open Task Center” 行进入完整 Task Center。

完整 Task Center 额外提供 A 切换 Active / Tracked、/ 搜索、Tab / Shift+Tab 双向切换类型、S（确认后）停止所选任务以及 R 刷新 / 重试。Quick 窗口只消费上述导航键，其余输入一律 no-op，不会进入搜索、停止确认或任务管理状态，因此 Esc 始终一层关闭。

已经结束的 one-shot Subagent 仍可以打开并查看持久化 Transcript。

对于当前 Session 的直接 continuable Child，可以进入交互式 Viewer，并直接向该 Subagent 发送后续消息（走 DSH 官方 subagents.prompt() 人类输入通道——按顺序排队为 Child 自己的下一个 turn，并保留 user 来源）。Child 使用自己的 Transcript、Draft 和运行状态，不会修改主 Session 的输入。

更深层的 nested Subagent 默认以只读方式查看。

官方 Subagent 模型选择（DSH subagent-model-selection 设置）可在 /settings 中开关并维护 allowlist：开启后新建 Session 的官方 subagent 工具可以按调用 选择子 Agent 的 provider/model（受 allowlist 限制）。设置在 Session 组合时采样， 不会改写已在运行的 Session 的工具。

Shell

编辑器支持两种 Shell 模式：

! git status

在宿主（Host）环境执行命令，并把输出提交到当前 Session。

!! git status

同样在宿主环境执行，但输出不进入模型上下文（仅卡片展示）。

! / !! 是独立的编辑器模式，而不是普通文本前缀。进入 Shell 模式后 Prompt 和补全行为会同步切换。

Shell 卡片默认只显示有限的输出预览，Ctrl+O 可以展开完整保留内容——全屏 Focus 除外:那里 Ctrl+O 负责 Thought root 的整体开关,Shell 卡片保持折叠。

Git 提交署名（可选）

开启后，dsh-pi-tui 会指示 Agent 在创建 Git 提交时加上官方项目署名：

Co-Authored-By: @xmoon76/dsh-pi-tui <[email protected]>

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

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

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

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

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

模型与运行设置

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

常用入口：

/model
/settings
/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 / Display 的真实事实：主题的 source-qualified 原始值与友好名称、 Icon style、Transcript display 的运行时当前值与持久偏好、Thinking detail 的当前运行 态，以及每个条目的配置来源 Scope 与 backend 就绪状态；R 重新读取、C 复制所选行的 原始值；浏览、选择与复制本身都不写入配置。

其中**「Configured theme」和「Transcript display」两行可以直接修改**：在 L1 设置行按 Right 或 Enter，或点击 [Change…] / 可见的 Detail 内容，即可在同一 L2 详情中打开 候选选择；当前值与 Runtime / Persisted 事实留在同一详情事实区，并与候选列表独立滚动。Up/Down/Home/End 移动候选，PgUp/PgDn 和事实区上的滚轮只滚动详情事实，候选区滚轮独立滚动候选； 选择期间可按 C 复制仍未更改的原始值，但仅当动作栏实际绘出 c copy，它不会提交候选。 Enter 或点击 [Confirm] 明确确认，Left/Esc/Backspace 或 [Cancel] 取消并直接回到 L1，零写入。L2 浏览/已结算时，Enter 可重新打开可写行的选择；pending 写入时不触发新选择。若当前候选身份已滚出可见区域，第一次 Enter 只将其重新显示，之后才能确认； 44×8 短屏在长身份需要空间时先省略可选的 Choose value 标题；若仍不足，再将事实区压到只保留旧 Value 的一行。只有完整身份、Confirm 与 Enter confirm 同屏可见时才能确认，超过剩余容量仍拒绝写入。只有实际绘制出来的 按钮与候选行可以点击。确认后走既有的串行整文档写入路径落盘，再从权威来源重读目标字段核对： 详情里分别显示运行态（Runtime，如当前 palette）与持久偏好（Persisted），并显示 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 与 Thinking detail 仍是只读行。旧的完整设置编辑器仍然可用：Other settings → Open existing settings… 会先关闭工作区并恢复原界面，再打开原有编辑器，Theme、Plugin Manager、键位、权限与扩展设置的写入路径全部不变。

/settings 的 Other settings 里新增 Web Search / Fetch：选择后先关闭工作区，再打开原有编辑器 的 Web 段并定位到第一项。段内可切换搜索 Provider（Messages，官方默认，或独立计费的 DeepSeek Search API）、Fetch Provider（HTTP，官方默认，或 DeepSeek Fetch API），设置 Search API 结果数（1–50，快选 5/10/20/50）、Share Original Question（官方默认为开启；每次新的 Search API 调用附带最多 128 字符的触发人类问题 ori_question，不发送完整历史或系统提示词）与 API endpoint base（必须显式确认 https 地址；凭据与查询会发往该地址）。两套 API 都是独立的 opt-in 收费 provider：登录或普通 Messages 套餐不保证覆盖其费用，默认的 Messages/HTTP 组合也不会调用收费 API。Web 配置是 base profile 所有的设置，不是 Bxx Optional Bundle；安装或启用任何其他 Bundle 都不会改变这两个 provider。 [current] 只在官方写入与权威回读一致后移动，失败显示 Not saved；选择对下一次搜索/获取生效， 运行中的操作不会被追溯切换。DeepSeek API key 只显示是否配置与来源层，配置/清除复用现有遮蔽 /login DEEPSEEK_API_KEY / /logout DEEPSEEK_API_KEY（先关闭设置界面再执行）。Esc 从 Web 段返回 同一 Web Search / Fetch 行；从 Open existing settings… 进入的旧路径仍返回会话。Remote 后端显示 不可用，不发任何 Host 命名空间。

/settings 中的 Icon style 可切换 TUI 结构图标的风格:Emoji(默认, 彩色)、Symbols(紧凑的单格终端符号)、Minimal(隐藏装饰性图标,只 保留状态/交互标记);切换立即生效并持久化。

/settings 中的 Terminal progress 控制原生终端状态上报,共四档: 9;4+7501(默认,同时上报 OSC 9;4 进度条与 OSC 7501 语义状态)、 9;4(只保留进度条兼容协议)、7501(只上报语义状态:运行中 / 等待审批 / 等待回答 / 完成 / 出错)、Off(清除并停止上报)。切换立即生效;完成与出错 只在一次真实运行的最后一个 turn 结果被证实后上报,中断或取消会回到空闲。 旧的 On 配置读作默认双协议。

终端兼容性说明:不认识 OSC 7501 的终端会直接忽略它——目前 Ghostty 的 GUI 只显示 OSC 9;4 进度条、不显示 7501 语义状态,这是预期行为,不代表上报失败。 在 tmux 等终端复用器里,未知 OSC 可能不会被转发到外层终端(本功能有意不实现 tmux 的 DCS passthrough,也不修改复用器设置);需要跨复用器保留状态时请直接 使用支持它的外层终端。此外,OSC 7501 的语义状态只作用于当前 Main Agent。

本项目的 Remote(实验性、自有 Host 组合)同样上报这套状态:Host 侧由本扩展自带的 私有状态流提供,并与 Direct 共用同一份区间判定。未安装本项目 Host 扩展的第三方 DSH Host 不支持这套上报(它没有对应的事件源)。

其他插件注册到 ctx.commands 的 Slash Command 也会被自动发现。

Footer 自定义

/footer 提供交互式 Footer 编辑器。你可以组合内置状态条目，调整左右位置、顺序、Style、Tone、Prefix/Suffix 和 Importance，也可以创建自己的 Footer 条目。

支持四类条目：

• Builtin Item：Model、Context、Token、Tasks、Git branch 等内置状态；
• Custom Text：用户创建的固定文本；
• Custom Command Item：用户创建的动态命令输出，可和其他条目一起排列；
• Extension Item：插件通过 Stable Extension API 提供的 Footer 条目。

在窄终端中，支持 compact 的内置条目会先自动缩短；空间仍不足时再按 Importance 隐藏低优先级内容。运行时 compact 不会修改你保存的 Style。

/footer 的 Custom Command Item 和 footer: command 是两种不同能力：前者只是一个可以与 Model、Context 等混排的动态条目；后者把整个 Footer 状态表面交给一个用户命令。

完整的 /footer 使用方法、Custom Text / Command、YAML 配置、安全模型和排错说明见：

• Footer 自定义完整指南
• Extension API（插件作者）

/statusline 是 /footer 的别名。

常用按键

| 按键 | 功能 | | ------------- | ---------------------- | | Enter | 提交输入 | | Ctrl+Enter | 与 Enter 的忙碌行为相反(默认 steer,busyEnter=steer 时入队) | | Shift+Enter | 换行 | | Esc | 取消当前交互 / 中断运行 | | Esc Esc | 空闲时打开 Rewind | | Ctrl+C | 键盘退出确认;首次清空草稿 | | Ctrl+D | 空草稿时键盘退出确认;有内容时向前删除 | | Ctrl+S | Steer:把队列消息和草稿一起发送到正在运行的回合 | | Ctrl+T | 切换 Todo 面板 | | Ctrl+R | 搜索输入历史 | | Ctrl+F | 搜索 Transcript | | Ctrl+End | 全屏时跳到最新 Transcript 输出；离开 live tail 时底部显示可点击的 ↓ Latest | | Ctrl+O | 展开 / 折叠工具和系统详情；普通与全屏非 Focus 下展开/收起超长用户 Prompt；全屏 Focus 下整体切换 Thought root（超长用户 Prompt 用点击/搜索展开） | | Alt+T | 展开 / 折叠 Thinking | | Ctrl+G | 使用 $VISUAL/$EDITOR 编辑输入 | | Ctrl+V | 粘贴图片 | | Tab | 补全斜杠命令与文件路径 | | @ | 文件补全 | | ! | 进入 Shell 模式（结果进 Session） | | !! | 进入 Session 排除的 Shell 模式 |

完整按键和命令以 TUI 中的 /help 为准。表中的快捷键是默认值;用户自定义后,以 /help 和 /keybindings 显示的生效键位为准。

自定义快捷键

Host 快捷键是语义 action(app.*),通过 context-aware keymap 解析—— UI(页脚提示、/help、/keybindings)始终显示生效的按键,因此 改键后所有提示自动更新。配置入口是 TUI 里的 /keybindings 面板 (写入 tui-app 插件的 profile 配置的 keybindings 字段——DSH 0.1.7 起 TUI 偏好保存在 profile-owned Config,不再使用旧 dsh-pi-tui settings 命名空间);保存后用 /keybindings reload 应用(显式 reload——配置变更后执行 reload 即生效,无需重启)。字段形状:

keybindings:
  app.input.steer: ctrl+s          # 单个按键
  app.permission.cycle: [shift+tab, ctrl+shift+p]   # 多个按键
  app.history.search: ctrl+r
  app.transcript.toggleThinking: false   # 禁用该 action 的按键
  leader: ctrl+x                    # M6:leader 序列
  bindings:
    app.tasks.open: <leader>t

• 普通可打印键永远不能绑定到 Host action(会吞掉输入);坏配置只是 警告,绝不会导致启动失败(fail-soft)。
• 任何用户声明都会替换该 action 的内置默认键:app.input.steer: ctrl+x 让 Ctrl+X steer、Ctrl+S 不再 steer;仅 leader 的 app.todo.toggle: <leader>t 让 Leader T 成为唯一切换触发(Ctrl+T 失效);['ctrl+z', '<leader>s'] 同时保留两个用户触发;false 移除该 action 的全部触发。若 effective editor-owned submit key 会在 leader machine 之前消费某个 completion(例如 <leader>enter),该死序列会被 拒绝而不会被展示。
• DSH_PI_TUI_SAFE_KEYBINDINGS=1 忽略所有用户覆盖(仅使用内置默认)。Safe mode 开启时整个 /keybindings 编辑器只读,避免保存只会在关闭 safe mode 后才发现的 冲突配置。
• 编辑器中未自定义 action 且仍然 effective 的默认按键可选择。Add shortcut 会把 这些仍生效的默认键与新键一起写入;已被 shadow 的 definition default 仅作参考,替换 或删除一个仍生效的默认键会保留其余 sibling。action 已有用户声明后,仍按上文规则 替换内置按键集合。
• /help 仍是按键优先的只读帮助;/keybindings 是按 action 优先的 可编辑 Keyboard Shortcuts Editor:按类别分组,搜索 action ID/描述/当前键和 默认键,并标记 customized、conflict、Unbound、Disabled 和 fixed 状态。 独立的 Leader key 行还可设置全局 leader key。
• /settings 只有一个 Keyboard shortcuts 入口,打开与 /keybindings 相同的 编辑器和持久化控制器。
• 录制器读取真实终端按键,通过 parseKey 规范化为 KeyId;保存前会拒绝 无法匹配、吞输入、终端歧义或已知冲突的按键。普通录制器按 Esc 立即取消; Host interrupt action 的 direct recorder 使用短暂双击窗口:一次 Esc 取消, 两次 Esc press event 才录入物理 Escape。repeat/release 不算第二次,不再有单字母 快捷方式;物理 Escape 保留给 Host 生命周期路径。
• 条件 affordance 会在编辑器中单独标注(例如空编辑器任务浏览器的 Down (conditional)),不会伪装成普通已配置快捷键。
• /keybindings conflicts 列出冲突(同键 + 作用域重叠 + 同优先级——绝不 静默 last-write-wins);/keybindings reload 重新读取设置(fail-soft:坏配置会 被诊断并跳过,读取异常才会给出错误提示——都不会崩溃,keymap 保留 last-known-good 配置);/keybindings reset 通过 settings 服务清除覆盖,并 立即重建运行中的 keymap。
• 子代理查看器按 action id 阻止父级 action,因此改键后的父级快捷键 在查看器内依然被阻止。
• 条件 affordance 是累加的:绑定 app.tasks.open: ctrl+x 是增加 一个触发——空编辑器的 ↓ 任务浏览器仍然有效;只有 false 才会 移除某 action 的全部触发。

从源码运行

git clone https://github.com/XMoon/dsh-pi-tui
cd dsh-pi-tui

pnpm install
pnpm build

使用 file: 安装：

dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@file:$PWD

file: 会在安装时复制当前构建结果。修改源码后需要重新 build 并重新 add。

持续开发可以使用 link:：

dsh plugin --profile pi-tui-dev -- add @xmoon76/dsh-pi-tui@link:$PWD
dsh --profile pi-tui-dev

之后重新执行：

pnpm build

即可让开发 Profile 使用新的构建结果。

DeepSeek Harness 集成

dsh-pi-tui 只实现终端交互层。

以下能力由 DeepSeek Harness 提供：

• Agent Loop
• LLM / Provider
• Session Persistence
• Tools
• Skills
• Approval
• Permission Presets
• Plan Mode
• Goal
• Jobs
• Subagents
• Credentials
• Settings

因此 TUI 不需要维护独立的模型配置、Session 格式或 Agent Runtime。

它可以和其他 DSH Surface 使用同一套运行时数据：

dsh --profile web
dsh --profile headless
dsh --profile pi-tui

Extension API

除作为 TUI 使用外，dsh-pi-tui 还提供版本化的 Extension API，供其他 Cordis / DSH 插件扩展终端界面。

目前分为三个入口：

| Entry | 用途 | 稳定性 | | ----------------------------------------- | ------------ | -------- | | @xmoon76/dsh-pi-tui/extensions | 常规扩展 | Stable | | @xmoon76/dsh-pi-tui/extensions/advanced | 高级交互能力 | Advanced | | @xmoon76/dsh-pi-tui/extensions/unstable | Low-level 能力 | Unstable |

可扩展的内容包括：

• Header / Footer
• Input Widget
• Slash Command
• Theme
• Setting
• Autocomplete
• Keybinding
• Message Renderer
• Tool Renderer
• Overlay
• Interactive UI
• Editor Control
• Replacement Editor

插件只需要依赖公开入口，不需要 import TuiApp、TuiMainScreen 等内部实现。

简单示例：

import {
  PI_TUI_EXTENSIONS_SERVICE,
  type PiTuiExtensionService,
} from '@xmoon76/dsh-pi-tui/extensions'

export const name = 'my-plugin'
export const inject = ['tuiStartup', PI_TUI_EXTENSIONS_SERVICE]

export function apply(ctx: Context): void {
  const service = ctx.get(
    PI_TUI_EXTENSIONS_SERVICE,
  ) as PiTuiExtensionService

  if (!service.api().capabilities.has('slot.chrome.header.badge')) {
    return
  }

  service.register(
    'chrome.header.badge',
    {
      id: 'my-badge',
      order: 100,
    },
    {
      text: 'my-plugin',
      tone: 'info',
    },
  )
}

详细文档：

• Extension API
• Extension tiers
• Advanced API
• Unstable API
• Plugin authoring
• Capability matrix

开发

pnpm install
pnpm build
pnpm typecheck
pnpm test

测试包括 Pi TUI fork、自身 TUI 行为以及 Extension API 的 fixture / smoke test。

终端渲染和输入路由使用 @xterm/headless 做自动化验证，因此大部分 UI 测试不依赖真实 TTY 或模型连接。

性能基线：

node --expose-gc scripts/bench.mts

项目日常开发使用单独的 pi-tui-dev Profile 进行自测：

dsh plugin --profile pi-tui-dev -- add @xmoon76/dsh-pi-tui@link:$PWD
dsh --profile pi-tui-dev

DSH 兼容性与验证

以下内容仅介绍 DSH 兼容性与 CI 验证细节；普通用户无需了解即可安装 TUI。

npm 模式（当前 next）

当前兼容列车线是 npm 模式：以本 checkout 的 package.json 声明、 lockfile 解析的已发布 dsh-v0.2.0-rc.2 family 为精确验证目标（运行时 peer floor 同为 >=0.2.0-rc.2）。隔离的 npm 驱动从公共 registry 安装该精确 family，并跑完整 build/test/package 路径：

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。

项目结构

仓库根目录是发布到 npm 的 @xmoon76/dsh-pi-tui bundle。

Pi TUI fork 位于：

packages/pi-tui/

它作为内部依赖参与构建，并随根 package 一起打包，不单独要求用户安装。

具体的 upstream 来源、版本和本地差异以：

packages/pi-tui/package.json
packages/pi-tui/AGENTS.md

为准。

贡献者相关的仓库结构和开发约定见 AGENTS.md。

文档

| 文档 | 内容 | | ------------------------------------------------------ | ---------------------------- | | docs/README.md | 文档索引 | | docs/architecture.md | 架构和模块职责 | | docs/input-history.md | 输入历史 | | docs/surface-decisions.md | TUI 交互设计决策 | | docs/concurrency.md | Session 并发 | | docs/failure-model.md | Async failure / cancellation | | docs/perf-baseline.md | 性能基线 | | docs/local-development.md | 本地开发环境与 worktree 约定 | | docs/extension-api.md | Extension API | | AGENTS.md | Contributor operating manual |

Changelog

中文：

CHANGELOG.md

English:

CHANGELOG.en.md

License

MIT