一句话定位

这是给 DeepSeek Harness (DSH) 准备的一套终端原生交互界面（终端里的"客户端"），通过 ACP 协议与 agent 通讯，把流式推理、工具调用、Skills、多图 prompt 和持久会话都画进终端。它本身是 DSH 生态的 terminal surface 插件，推荐装到 tui profile 后用 dsh --profile tui 启动。

核心能力

• 实时呈现 agent 时间线：流式推理、回复、工具参数与结果、subagent 生命周期，以及本回合 token 与 cache 用量
• 读取 ACP agent 自身声明的模型、权限、认证方式、可用命令，与内置命令合并到一个可搜索、可滚动的 / 斜杠菜单
• 多图 prompt：从文件、剪贴板或粘贴暂存最多 8 张图片，发送时以可编辑的 [image n] chip 内联在草稿里
• 终端友好的 Markdown 渲染：标题、列表、引用、代码块、行内代码、强调、删除线、链接、图片，并保留 CJK/Latin 混排
• 高密度工具视图：长结果默认只保留末四行可点击展开，状态（进行中/成功/失败）一目了然
• 长会话控制：回合中可排队 follow-up，也能立即 steer 当前回合；持久 JSONL 会话通过 /new、/resume 和 --session-id 管理
• 跨平台输入：readline 编辑、上下文快捷键、macOS 的物理 ⌘/⌥、Linux/Windows 的 ctrl 组合键统一手感
• 终端原生界面：明暗主题、窄屏自适应、鼠标选择、原生/tmux/OSC 52 剪贴板，支持 kitty graphics protocol 的图片预览与可选的 /liang 像素宠物

技术实现

• 语言: TypeScript / Node.js（npm 端的 Cordis client 树）+ Rust / ratatui（终端绘制与状态机）
• 关键依赖: @deepseek-ai/cordis（Cordis 插件容器）、@openma/deepseek-harness-acp（运行时携带的 ACP 客户端，作为 agent 端点）、agent-client-protocol Rust crate（与 agent 通信）、ratatui + tui-markdown（终端渲染）
• 架构模式: 双进程 Cordis 架构。Host 进程在自己的 Base Cordis 树挂 ACP plugin，再由它启动独立的 TUI Client 子进程；两棵树只通过子进程的标准 stdin/stdout 上的 ACP 协议通信，Client 进程的 fd 3/4 仅承载用户 TTY（Unix）或带随机 token 的 loopback TCP（Windows）。插件通过 Cordis service（tuiTheme、tuiSlots、tuiCommands、tuiOverlay、acpSessionConfig/Plan/Stats）扩展；主题与视图能力协商后走 _dsh/cordis/* 与 _dsh/cordis/tui/* 扩展点
• 入口文件: npm/bin/dsh-tui.js（CLI shim）、npm/lib/index.js（dsh-tui-shell Cordis 插件，负责 spawn Rust painter 并 mux ACP + compositor）、src/main.rs（Rust 入口）

适用场景

想在终端而不是浏览器里使用 DeepSeek Harness 的用户，特别是依赖 tmux/ssh、需要快速键鼠操作、想脚本化调用或不喜欢开浏览器窗口的开发者。它也适合做 demo：单独跑 --demo 不需要配置 API key 就能浏览 UI 体验；带 --demo-skin 还能换上内置的 ember 配色包看主题切换效果。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:openma-ai/deepseek-harness-tui

配置项

本插件无需额外配置。/auth、/model、/agent、/effort、/plan、/permission、/theme、/keys、/help、/image、/clip、/liang、/new、/resume、!cmd 等行为由 agent 自身能力、运行时状态或运行时命令直接驱动。

下列环境变量只在开发与排障时使用，普通用户无需关心：

常见问题

Q: 装好后还需要额外配置吗？

A: 不需要。安装命令会自动创建 profile 并把 TUI、ACP 依赖一并装上，直接 dsh --profile tui 就能用；只有调试本地 Rust 编译产物时才需要 DSH_TUI_BIN 环境变量。

Q: 没装 DSH Harness 也能跑吗？

A: 可以。独立入口 dsh-tui 可以 --agent dsh-acp 或 --agent dsh --agent-arg --profile --agent-arg acp 接任意支持 ACP 协议的 agent；--demo 模式不需要任何 agent 或 API key 就能看 UI。

Q: 支持哪些操作系统？

A: macOS（arm64 / x64）、Linux（arm64 / x64）、Windows（x64）。Linux x64 包从 0.2.x 起改为静态 musl 链接，能直接在老发行版（如 Ubuntu 20.04）上跑，不需要 glibc 兼容层。

Q: 不支持 DSH 私有扩展的 ACP agent 也能用吗？

A: 可以。当 agent 在 initialize 的 _meta.dsh.cordis 里没声明该扩展时，TUI 只走标准 ACP（prompt、session、auth、update），不会出现兼容性问题。

Q: 输入框旁边的小难梁宠物不显示怎么办？

A: 只有 Ghostty、Kitty、WezTerm 等支持 kitty graphics protocol 的终端才会显示 RGBA 像素精灵；其他终端退回半块字符鲸鱼，且宽度低于 60 列时会自动隐藏。主界面功能不受影响。

Q: 怎么卸载？

A: 通过 dsh plugin --profile tui remove @openma/deepseek-harness-tui 即可，会同时撤销 profile 里的 TUI bundle 与配套的 ACP/Host rows。

Q: 报 spawn dsh-acp ENOENT 怎么办？

A: 没找到默认 agent 二进制。可以装 DSH 官方 ACP 客户端（dsh-acp），或者用 --agent 显式指向另一个 ACP server，例如 --agent <其它 ACP 命令>。

Q: 安装包提示 no native binary for ... 怎么办？

A: 当前安装版本没覆盖你的平台（darwin-arm64/x64、linux-arm64/x64、win32-x64 之外）。确认装的是最新版，或在本地跑 scripts/build-npm.sh 自己编译打包。

上手难度

入门 — 安装一行命令即可使用，进阶用户再去读 docs/plugins.md 写客户端插件扩展主题、插槽、命令等。

已知问题与限制

• 对话时间线插槽（conversation.chat）尚未开放；当前插件只能贡献 chrome.right、conversation.input.dock、conversation.composer.dock，ACP session/update 仍是 transcript 唯一真源，插件节点不能替换 composer 或伪装成会话事件
• "完全插件化"仍是目标架构，form 控件、更多 shell/conversation slot、运行时诊断面板与独立的 ViewPreset 仍在迁移路线图上，详见 docs/migration.md
• 第三方插件严格被限制只能拿到 tuiTheme/tuiSlots/tuiCommands/tuiOverlay/ACP session services 这些语义 API；TTY、raw mode、ratatui、kitty 转义、绝对行列坐标与 JSON-RPC 方法表不对插件开放，强行通过运行时直接读 stdin 或 ratatui 状态的写法会被新版本破坏
• 输入框旁的 /liang 像素宠物只在支持 kitty graphics protocol 的终端上以 RGBA 像素显示，其他终端退回半块字符鲸鱼；终端宽度低于 60 列时直接隐藏（README.md:312-314）
• 安装包如果提示 no native binary for ...，是因为该平台不在打包矩阵内（darwin-arm64/x64、linux-arm64/x64、win32-x64），需要本地用 scripts/build-npm.sh 自编译，或换装匹配平台的包

DeepSeek Harness TUI

在终端里运行 DeepSeek Harness：流式推理、工具调用、Skills、多图 prompt 与持久会话。

中文 · English

---

简洁且强悍的DSH-TUI

• Rust/ratatui 编写的高性能程序界面.
• 100% 基于Deepseek Harness官方AI能力.

dsh-tui 是终端原生 ACP client，也是一套运行在 Cordis client 树上的 可扩展终端。它在 Rust/ratatui 界面里呈现流式推理、工具调用、subagent、token 用量和持久化会话。推荐 profile 路径把 ACP plugin 挂在 dsh Base Host 树上，并 启动独立 TUI Client 进程；standalone 入口也可 spawn 或接入任意 ACP agent。长期目标 不是把功能不断焊进 TUI 本体，而是让主题、视图、命令和交互都由插件组合，最终 让 Creator 能检查、创建、运行、诊断并迭代自己的终端能力。

快速开始

推荐：作为 dsh 的 TUI surface plugin

需要 Node.js 18+。安装官方 DeepSeek Harness， 再把 TUI 直接装进 tui profile：

npm install -g @deepseek-ai/dsh
dsh plugin --profile tui add martty@latest
dsh --profile tui

dsh plugin ... add 是推荐的安装与升级入口：它会自动创建 profile、安装 TUI 及其 ACP 依赖，不需要全局安装 dsh-tui，也不需要另装 pnpm。 旧包名 @openma/deepseek-harness-tui 会继续发布相同版本，已有安装无需立即迁移。

从旧包名迁移

martty 是新的推荐包名。从 0.2.13 开始，martty 和 @openma/deepseek-harness-tui 由同一条 CI 以相同版本、相同产物发布； 旧包名作为兼容别名保留。如需切换，只替换 tui profile 中的包规格：

dsh plugin --profile tui remove @openma/deepseek-harness-tui
dsh plugin --profile tui add martty@latest

迁移不改变 dsh-tui / dsb 命令、tui profile 名或运行方式，也不需要 迁移配置和会话数据。不想立即切换时，继续使用旧包名即可。

这是给 AI agent 阅读的安装说明：docs/agent-setup.md

TUI 把 ACP 声明为自身运行时依赖。若目标 profile 已通过标准 ACP bundle 装过另一 版本，包管理器可以保留两份依赖，但 TUI bundle 会停用该 surface 的旧 transport/provider 行，并只挂载从 TUI 自身依赖图解析出的 ACP plugin；因此受支持的 profile 组合不会同时启动两套 ACP，也不要求用户先手工整理已有 ACP profile。

Standalone：接任意 ACP agent

dsh-tui --agent dsh-acp
dsh-tui --agent dsh --agent-arg --profile --agent-arg acp

本地 checkout（需已 cargo build --release 或 scripts/build-npm.sh，并把二进制放到 npm/vendor/<platform>/，或设置 DSH_TUI_BIN）：

DSH_TUI_BIN=$(pwd)/target/release/dsh-tui dsh-tui --agent dsh-acp

第三方能力是 client 树上的普通 Cordis 插件：声明所需 service，在 apply 中 注册贡献，并随 fiber 卸载自动撤销。当前已经开放主题、根级右栏、本地命令、 slider overlay、当前 ACP Session 配置事务和包内 Host/Client RPC；完整契约见 插件 API，完整方向见 完全插件化与自进化。--demo-skin 只挂载 gallery 包 ember，不代表主题逻辑写进了本体。

先看 Demo

Demo 不需要 runtime 或 API key：

npm install --global martty
dsh-tui --demo

dsh-tui 是主命令；dsb 保留为兼容别名。

核心能力

• 完整的 agent 时间线：实时呈现推理、回复、工具参数与结果、plugin 上下文、 subagent 生命周期和 token/cache 指标；最新消息下方持续显示阶段、耗时与队列深度。
• ACP 能力原生接入：读取 agent 广告的模型、composition、权限、认证方式和 可用命令；skills 与内置命令共享可搜索、可滚动的斜杠菜单。
• 多图 prompt：从文件、剪贴板或粘贴操作暂存最多 8 张图片，图片以可编辑的 [image n] chip 内联在草稿中，并支持名称、尺寸、大小和类型预览。
• 终端友好的 Markdown：渲染标题、列表、引用、代码块、行内代码、强调、 删除线、链接和图片标记，同时保留 CJK/Latin 混排与软换行样式。
• 高密度工具视图：工具调用清晰呈现进行中、成功和失败状态；长输出默认保留 末四行，点击后在对话内完整展开，滚轮始终滚动整个对话。
• 适合长对话的控制：回合中可排队 follow-up，或立即 steer 当前回合；持久化 JSONL 会话通过 /new、/resume 和 --session-id 管理，workspace 模式信息也会缓存。
• 跨平台输入体验：readline 编辑、上下文快捷键，以及 macOS 的物理 ⌘/⌥ 修复和 Linux/Windows 的 ctrl 组合键，让常用移动与删除在不同终端保持一致。
• 终端原生界面：深浅主题、窄屏布局、鼠标选择/工具交互、原生/tmux/OSC 52 剪贴板，以及支持 kitty graphics protocol 的图片预览和可选 /liang 像素宠物。

完全插件化与自进化

目标是让 TUI 成为一个小内核加一组可组合插件，而不是一个不断积累特判的终端 应用。内核只负责 ACP 会话、TTY 所有权、输入调度、布局约束和语义节点绘制； 产品能力通过 Cordis service、slot 和插件生命周期进入 client 树。

• 一个生命周期： 静态包与 Creator 生成的动态包都走 Cordis Loader、fiber、 inject 和 disposer。挂载后立即生效，停止或切换后完整撤销，不另造一套“动态 插件”运行时。
• 一个插件可以贡献多个表面： 同一包可同时注册 theme、slot、command 和 overlay，并让它们共享状态或通过包内 Host/Client RPC 联动。核心不为 Liang、 effort 或某个具体插件增加分支。
• 只开放语义能力： 插件提交 TuiNode 和 slider、form 等通用交互语义，由 Rust renderer 适配终端。插件拿不到 TTY、raw mode、Ratatui、kitty 转义或绝对 坐标；替换 renderer 不应改变插件 ABI。
• 动态预览与持久组合分开： define/run 负责即时预览，stop/update/rollback 负责运行期生命周期；确认后的 Package 可以持久化。AgentPreset 继续只组合 agent 侧能力，未来由独立的 ViewPreset 组合 client/UI 插件。两者可以一起选择， 但分别存储、分别切换。
• Creator 闭环： Creator 先 inspect 当前 Host/Client 的真实 service、slot、 token 和 schema，再生成 code.host、code.client 或两者，运行后观察装载错误和 渲染错误，继续修复、更新、回滚或保存。这才是“自进化”，不是让模型直接操作 终端底层。

当前完成度

现在已经落地的是 ACP client 分层，以及同一条动态 Package 生命周期上的这些原语：

• tuiTheme 与 /theme 单选 Plugin 席位；
• tuiSlots、chrome.right 和 schema 校验后的 TuiNode；
• 生命周期归属的本地 slash command 与原生 slider overlay；
• 从标准 ACP configOptions 投影出的当前 Session 配置目录和事务；
• Client inspect/run、Package stop/start/retract，以及包内 Host/Client RPC；
• 只在 Creator preset 中可见、但不依赖 ACP 注入的 TUI 开发 skill。

这些能力同时服务静态插件与动态 code.client，不是为某个 demo 单独开的通道。 仍在迁移的是更多 shell/conversation slot、form 等其他通用输入组件、完整的运行期 诊断和 ViewPreset。因此“完全插件化”仍是目标架构；逐阶段状态以 迁移计划 为准。

与 Web 插件平台对照

Web 今天的插件面更广、实现也更成熟。TUI 要对齐的是 Cordis 的组合方式、生命周期 和 Creator 创造闭环，而不是把 React 或浏览器 DOM 搬进终端。

运行架构

主路径 dsh --profile tui 在 Host 进程的 Base Cordis 树挂 ACP plugin，再启动 独立进程中的 Node Cordis Client 树：tui-theme 提供主题目录， tui-cordis-client-runner 承接 dsh-tool-cordis 的 Client inspect/run， acp-client 接 Host 的标准 stdin/stdout，dsh-tui-shell 启动 Rust painter 并做消息分流。 两棵 Cordis 树位于不同进程，只讲 ACP。Standalone dsh-tui 才按参数 spawn/attach 任意 ACP agent。 Rust painter 不是第三棵 Cordis 树，它只占 TTY、处理输入并绘制声明式状态。

两棵 Cordis 树不会同步 plugin id、inject 或 fiber。标准 ACP 继续承载会话、 prompt、认证、配置与 session/update；自进化所需的 Client 能力发现、动态 Package 运行和包内 RPC 则使用协商后的 ACP 扩展。目标扩展统一放在 _dsh/cordis/* 命名空间，并通过 initialize 的 _meta.dsh.cordis 声明能力；不支持该扩展的 ACP agent 仍可作为普通 agent 使用。

Creator 的教学能力是 TUI 包内部导出的独立 Host overlay；ACP 是 TUI 的运行时 依赖。用户只需安装 TUI；bundle 把 ACP plugin 和 Creator overlay 挂到 Base Host tree， runner 只启动 TUI Client 进程。Creator 会在上游 cordis preset 的 standing scope 上增加 tui-plugin-development skill；不复制 preset、不改上游文件，也不靠 ACP 发现或注入 skill。Web 和 TUI 因此使用同一个 Creator preset。 ACP 与 Creator overlay 都不会挂进 Client tree；完整 Harness 只在 Host 进程启动一次。

Host↔TUI Client 的 ACP 使用 Client 子进程的标准 stdin/stdout。Client 进程的 fd 3/4 只继承用户 TTY 并映射为 Rust 的 stdin/stdout；Rust 自己的 fd 3/4 才是 Node↔painter compositor 通道。

Unix 上 Node 与 Rust 使用 fd 3/4，Windows 使用带随机 token 的 loopback TCP。 这条私有 compositor 通道只投影主题和 TuiNode 等语义绘制状态，不是插件 API， 也不承载 agent 业务。Cordis 通用 inspect/run/lifecycle 使用 _dsh/cordis/*； 主题、槽位、命令和 overlay 等 painter 能力使用其子域 _dsh/cordis/tui/*。 这些都是带下划线前缀的 ACP Extension Request/Notification，不进入 prompt 或历史。

常用交互

界面内使用 /help 查看命令，使用 /keys 查看完整快捷键。

输入框宠物：/liang 🤫

/liang 会在输入框右侧显示小难梁：空闲时安静思考，回合运行时敲小终端。 Ghostty、Kitty 和 WezTerm 等支持 kitty graphics protocol 的终端会显示 RGBA 像素精灵；其他终端退回半块字符鲸鱼。宽度低于 60 列时自动隐藏。

可用 /liang on、/liang off 显式控制。

从源码构建

需要 Rust stable 和 Node.js 18+：

make rust-test
node --test scripts/package-native.test.mjs
bash scripts/build-npm.sh

make rust-build / make rust-test / bash scripts/build-npm.sh 统一经过 scripts/cargo-guard.sh：本仓库 target 超过 20 GiB，或磁盘余量低于 10 GiB 时会先执行 scoped cargo clean。 make rust-cache-status 只读查看，make rust-cache-prune 显式清理；阈值可通过 RUST_CACHE_MAX_GIB / RUST_DISK_MIN_GIB 覆盖。

真实开发 profile 统一用 make tui-test 启动。它先重编 target/debug/dsh-tui，再设置 DSH_TUI_BIN 启动 tui-test，避免 Node HMR 已更新而 Rust painter 仍是旧进程映像。

本地脚本只编译当前平台，并将 tarball 写入 dist/。GitHub Actions 工作流 Package and publish npm 会分别构建以下目录，再汇总为一个 npm 包：

npm/vendor/darwin-arm64/dsh-tui
npm/vendor/darwin-x64/dsh-tui
npm/vendor/linux-x64/dsh-tui
npm/vendor/win32-x64/dsh-tui.exe

推送与 npm/package.json 和 Cargo.toml 版本一致的 tag（例如 v0.1.0） 会通过 npm Trusted Publishing（OIDC）发布到 latest，随后创建带 tarball 的 GitHub Release。版本不一致时 CI 会在发布前失败。

故障排查

• no native binary for ...：当前安装包不包含你的平台。确认安装的是 最新版本，并查看上方支持矩阵。
• spawn dsh-acp ENOENT：安装 dsh-acp，或用 --agent <cmd> 指向其它 ACP server。
• 像素宠物不显示：终端可能不支持 kitty graphics protocol；主界面功能 不受影响。

项目结构

• src/：TUI 状态机、绘制、协议、runtime 生命周期和会话目录。
• npm/：Cordis client boot、ACP/compositor mux、CLI shim 与原生二进制。
• scripts/：本地构建、跨平台打包校验、协议集成测试与资源生成。
• assets/：截图、主题资源和可选宠物精灵。
• docs/：分层架构、插件 API、TuiNode schema、迁移计划与 AI agent 安装说明（索引）。

Agent 通信是 stdio 上的 ACP；Node 与 Rust 之间另有私有 compositor 通道。 实现细节可从 src/acp.rs、npm/lib/boot.js 和 npm/lib/mux.js 开始阅读。插件不要依赖这些传输细节；扩展点见 docs/plugins.md。

License

MIT。本项目与 DeepSeek、xAI 无关联； grok-build 是交互设计参考， DeepSeek Harness 是运行底座。