前言¶

DeepSeek Harness（DSH）把 Agent Loop、工具、Session、权限等运行时能力做成可插拔的 bundle，但日常开发往往仍需要一个在终端里就能完成对话、审批和会话管理的界面。Web 或 headless profile 能跑通流程，却不一定适合长时间盯着 Transcript、切换 Session、或一边改代码一边跟 Agent 交互。

dsh-pi-tui 是 XMoon 维护的第三方客户端插件，基于 vendored fork 的 Pi TUI，作为独立 bundle 装进 profile，专门承担终端交互层。模型、工具、Session 持久化、Skills、Plan、Goal、Subagent 等能力仍由 DSH 提供；TUI 负责流式展示、按键、Slash Command 和状态行。下面介绍它的定位、核心能力与安装用法。

这是什么¶

@xmoon76/dsh-pi-tui（社区目录名 xmoon/dsh-pi-tui）是 MIT 许可的 npm 包，当前版本 0.3.4。README 将其定位为「基于 Pi TUI 的 DeepSeek Harness 终端前端」——安装包内已包含运行所需的 Pi TUI fork，用户无需单独安装内部 TUI package。

插件分类为「客户端」。GitHub 仓库 XMoon/dsh-pi-tui 约 11 stars。它与 DeepSeek / 幻方无官方从属关系；社区目录 SkillHub 是独立的插件收录站点，DSH 生态遵循「一切皆插件」的思路，目录站并不等同于官方应用商店。

对话、Focus 与工具展示¶

TUI 侧覆盖日常对话所需的可视化与交互：

1. 流式 Markdown 输出，Thinking 可折叠（Alt+T），Tool Call 以卡片展示运行状态。
2. Tool / System 详情默认折叠，Ctrl+O 展开；全屏 Focus 下 Ctrl+O 改为整体切换最近几个 Thought root。
3. Transcript 全文搜索（Ctrl+F），长会话历史可折叠。
4. 状态区显示 Context、Token、模型与运行状态；支持 Approval、ask_user_question、Plan Review、Todo / Goal 展示。

Focus Mode 用 /focus 进入：运行中的 Thinking、Tool Call 和中间回复会聚合为一个实时更新的 Thought 区块。需要看过程时可展开；关闭 Focus 后恢复普通 Transcript。Focus 只改变界面投影，不修改 Session 里保存的事件。

Session 与输入历史¶

插件对接 DSH 持久化 Session，支持新建与恢复、切换、重命名、Fork、Rewind、Session lineage、Transcript 导出。常用 Slash Command：

/sessions
/fork
/rewind

空闲且编辑器为空时，连按两次 Esc 也可打开 Rewind。Rewind 会从选中的历史 User Turn 创建新的 Child Session，并把对应 Prompt 放回编辑器；原 Session 不会被修改。

输入历史用 Ctrl+R 搜索，范围可选 Current session、Current directory、All directories。结果含 Prompt、工作目录、时间和 Session 信息；选中后只恢复到编辑器，不会立即发送。↑ / ↓ 仍用于浏览最近输入。

Subagent、Shell 与文件引用¶

/tasks 打开当前 Session 的任务浏览器。Subagent 按完整 lineage 树形展示（含嵌套 descendant），并区分 continuable、one-shot、running / inactive、嵌套 descendant、后台 Job。已结束的 one-shot Subagent 仍可查看持久化 Transcript。对当前 Session 的直接 continuable Child，可进入交互式 Viewer 并继续发消息；更深层 nested Subagent 默认只读。

Shell 有两种编辑器模式（! / !! 是模式切换，不是普通文本前缀）：

! git status

执行本地命令，输出进入当前 Session。

!! git status

仅在本地执行，输出不进入模型上下文。

输入 @ 可搜索并补全工作区文件，例如 @src/index.ts 或 @"path with spaces/file.ts"；可解析的相对路径在提交时会转为明确文件路径。Ctrl+V 可粘贴剪贴板图片，通过 DSH Attachment 保存到 Session。

设置、Footer 与快捷键¶

模型与运行设置沿用 DSH 服务，常用入口包括 /model、/settings、/login、/permission、/plan、/goal、/compact、/footer、/statusline。其他插件注册到 ctx.commands 的 Slash Command 会被自动发现。/settings 里可切换 Icon style（Emoji / Symbols / Minimal）。

Footer 是可组合的状态表面。/settings 的 Status line 或设置文档中的 footer 键可选 default（旧名 full）、compact、custom；command 模式只能通过 USER 层设置文档启用。/footer 提供交互式配置器；footerLayout 支持左右区域、分隔符和多种内置条目 id。footer: command 时，状态快照以 JSON 写入用户命令 stdin，stdout 经净化后渲染；仅 USER 层配置的命令会执行，仓库/项目层提供的 footerCommand 不会执行。

常用按键摘要（完整表见 TUI 内 /help）：

快捷键可在 dsh-pi-tui 设置命名空间里按语义 action（app.*）覆盖，改完后执行 /keybindings reload 即生效。环境变量 DSH_PI_TUI_SAFE_KEYBINDINGS=1 可忽略全部用户覆盖。

Extension API¶

除作为终端前端使用外，包还提供版本化 Extension API，供其他 Cordis / DSH 插件扩展界面。公开入口包括：

可扩展 Header / Footer、Input Widget、Slash Command、Theme、Message / Tool Renderer、Overlay 等。插件只需依赖公开入口，不必 import 内部 TuiApp 实现。Stable API 还支持通过 chrome.footer.item 槽位贡献可配置的 Footer 条目。

安装与启用¶

环境要求：

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

项目当前跟随 DeepSeek Harness 0.1.1-rc.x 版本线开发。推荐使用单独的 pi-tui profile 安装并启动：

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

恢复已有 Session：

dsh --profile pi-tui --session <session-id>

更新、列出、卸载：

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

经过上面的步骤，TUI 可与同一套运行时数据下的其他 Surface 并存，例如 dsh --profile web、dsh --profile headless、dsh --profile pi-tui。

适用场景与注意¶

适合需要在终端长时间使用 DSH、且希望流式 Transcript、Session 管理、Subagent 浏览和 Shell 集成都留在同一界面的开发者。若你主要用 Web UI 或脚本化 headless，不必强制换 TUI；但若要在 pi-tui profile 里获得完整交互，这个 bundle 是 README 推荐的终端前端方案。

安装前请注意：插件以当前 dsh 进程权限运行，Shell 模式（!）会把命令输出提交到 Session；footer: command 仅在 USER 层设置下执行用户配置的脚本。安装前应阅读源码与 MIT 许可证，确认符合你的安全与合规要求。SkillHub 目录页与 GitHub 仓库是同一插件的两个入口，安装命令以 README 中的 dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui 为准，不要凭仓库名自行拼接 github:owner/repo 形式。

dsh-pi-tui 把 Pi TUI 的终端体验接到 DSH 运行时上：交互在 TUI，能力在 Harness。需要进一步了解架构、Extension API 或性能基线，可查阅仓库 docs/ 目录与 Extension API 文档。

• 社区目录：https://www.skillhub.cn/plugins/XMoon/dsh-pi-tui
• GitHub：https://github.com/XMoon/dsh-pi-tui