ccch1mneyyy/dsh-TUI / guide/dsh-tui-guide
dsh-tui-guide
UnverifiedUse when the user asks about dsh-tui itself (usage, shortcuts, config, themes, migration, VS Code). Load before answering; skip for normal coding tasks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.3 KB |
| claude-backend.en.md | markdown | 14.5 KB |
| claude-backend.md | markdown | 13.2 KB |
| cli.en.md | markdown | 9.0 KB |
| cli.md | markdown | 8.4 KB |
| codex-backend.en.md | markdown | 23.3 KB |
| codex-backend.md | markdown | 20.7 KB |
| configuration.en.md | markdown | 43.0 KB |
| configuration.md | markdown | 39.4 KB |
| getting-started.en.md | markdown | 30.9 KB |
| getting-started.md | markdown | 28.9 KB |
| interaction.en.md | markdown | 75.1 KB |
| interaction.md | markdown | 68.8 KB |
| migrate.en.md | markdown | 10.5 KB |
| migrate.md | markdown | 9.5 KB |
| plugins.en.md | markdown | 16.8 KB |
| plugins.md | markdown | 14.5 KB |
| themes.en.md | markdown | 10.3 KB |
| themes.md | markdown | 10.0 KB |
| user-guide.en.md | markdown | 80.9 KB |
| user-guide.md | markdown | 75.0 KB |
| vscode.en.md | markdown | 13.8 KB |
| vscode.md | markdown | 12.6 KB |
getting-started.md
View on GitHub# 安装与快速开始
[文档索引](README.md) · [English](getting-started.en.md)
## 前置条件
- Node.js `^22.19 || >=24`。CI 使用 Node 24。
- 官方 DeepSeek Harness CLI:`@deepseek-ai/dsh`。
- `pnpm` **10 或更高**(CI 使用 11)。`dsh plugin` 把 profile 内的包安装
交给 pnpm;pnpm 9 的传递依赖提升行为不同,会让 `dsh-working-activity`
解析不到,表现为启动后立刻退出且几乎无报错(issue #60,见下方常见问题)。
- 支持交互输入的终端 TTY。`dsh-tui` 不支持把 stdout 重定向后启动。
- `deepseek-official` 模型路由需要 `DEEPSEEK_API_KEY`;DSH 0.2.0-rc.1+ 的标准 profile 也可通过 `/auth login deepseek-account` 登录独立的 DeepSeek 账号路由。其他支持的账号可用 `/provider` 或 `/auth` 登录。自定义兼容端点还可设置 `DEEPSEEK_BASE_URL`。
macOS/Linux:
```sh
export DEEPSEEK_API_KEY='your-key'
```
PowerShell:
```powershell
$env:DEEPSEEK_API_KEY = 'your-key'
```
不要把真实密钥提交到仓库。也可以什么都不设:**首次启动的引导第一步**可以直接
`登录订阅账号(OAuth)`(含 DeepSeek 账号浏览器授权)或 `添加模型提供方(API key)`,
写入 DSH 凭据库(`$DSH_HOME/.credentials.yaml`,默认 `~/.dsh/.credentials.yaml`),
并把接入进来的模型选一个作为默认——环境变量只是「你也可以这样做」的那条路。
## 安装
最快路径(全局安装后自带 `dsh-tui` 直达命令):
```sh
# 官方 CLI + 本插件
npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui
# pnpm 未安装时任选一种方式(首次启动自动初始化 profile 时需要)
npm install -g pnpm
# 或:corepack enable pnpm
# 启动:首次运行自动执行 dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@<版本>
dsh-tui
```
手工分步(等价):
```sh
npm install -g @deepseek-ai/dsh
# pnpm 未安装时任选一种方式
npm install -g pnpm
# 或:corepack enable pnpm
dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui
dsh --profile dsh-tui # 或 dsh-tui
```
从仓库检出运行时,也可以执行:
```sh
sh install.sh
```
`install.sh` 只封装 profile 插件命令并检查 `dsh`、`pnpm` 是否可用;它不会
复制源码,也不需要本地构建。
## 从旧包迁移
早期版本使用无 scope 包 `dsh-cc-tui` 和 `cc-tui` profile:
- 环境变量前缀为 `CC_TUI_*`/`DSH_CC_*`。
- 数据目录为 `~/.dsh-cc`。
新版本统一为组织包 `@deepseek-harness-tui/dsh-tui` 与 `dsh-tui` profile。
执行以下命令创建新 profile:
```sh
dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui
dsh --profile dsh-tui
```
新版本只使用 `DSH_TUI_*` 环境变量与 `~/.dsh-tui` 数据目录,旧名不再被读取,
也不自动迁移数据。首次启动后,请把旧数据目录(`~/.dsh-cc` 等)中的主题、
配置与历史文件自行复制到 `~/.dsh-tui`。
确认新 profile 正常后:
- 旧的 `$DSH_HOME/profiles/cc-tui` 与旧数据目录残留可按需删除。
- 不要把旧包和新包同时添加到同一个 profile。
## 安装命令做了什么
首次执行 `dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui` 时,
官方 CLI 会:
1. 在 `$DSH_HOME/profiles/dsh-tui/` 初始化 profile。未设置 `DSH_HOME` 时,
默认根目录通常是 `~/.dsh`。
2. 让 profile 的第一层 bundle 使用 `@deepseek-ai/dsh-base`。
3. 在 profile 内通过 pnpm 安装 `@deepseek-harness-tui/dsh-tui`。
4. 读取包内 `dsh.bundle.patch` 元数据,将 `cordis.patch.yml` 追加为组合层。
启动时的主要顺序是:
```text
dsh-base -> 其他 bundle -> @deepseek-harness-tui/dsh-tui patch -> 用户 profile patch
```
- base 提供 Agent、模型、会话、文件、Shell、策略和注册表等服务。
- 本插件的 patch 覆盖或插入 TUI、Agent preset 名册、SQLite 会话持久化与
工作状态行。
`dsh-working-activity` 已经是本包依赖,并由 `dsh-tui` 的 patch 自动插入。
不要对同一个 profile 再单独执行 `add dsh-working-activity`,否则可能出现重复行。
## 启动
```sh
dsh --profile dsh-tui
```
命令从当前目录启动,因此 Agent 的默认工作区也是当前目录。进入目标项目目录后再
启动即可。
DSH 0.2.1 起,Agent 可以把会话切到别的目录(`working_directory` 工具或 Git
worktree)。状态栏、Git 分支、`@` 补全和 `!` 命令会跟随这个目录,`/resume` 后
也一样;会话仍登记在启动时的项目下。
Windows 仓库检出还提供:
```bat
dsh-tui.cmd
dsh-tui.cmd --resume
```
- `--resume` 会读取 `%USERPROFILE%\.dsh-tui\resume.txt`,恢复 TUI 最近选择的
会话。
- 设置 `DSH_TUI_WORKSPACE` 可以覆盖批处理启动器采用的工作目录。
## CLI 子命令
`dsh-tui help`(或 `dst help`)打印完整用法,`dst` 别名接受相同命令:
| 命令 | 作用 |
| --- | --- |
| `dsh-tui update` | 一次对齐整套(profile 的 TUI、全局 dsh 引擎、全局启动器)并校验,不进入 TUI、不重启;与 TUI 内 `/update` 同一决策 |
| `dsh-tui doctor` | 环境检查:dsh/pnpm、profile 安装与版本对齐、API key 是否设置(只报状态不读值)、配置文件存在性;与 TUI 内 `/doctor` 会话诊断互补 |
| `dsh-tui safe` | 安全模式:只读诊断、插件清单与修复指引(`safe --rescue` 还会创建/校验干净的救援 profile) |
| `dsh-tui version` | 显示启动器与 profile 版本(`--version`/`-v` 等价) |
| `dsh-tui help` | 显示用法(`--help`/`-h` 等价) |
`help`/`version` 在 dsh 缺失或 profile 未初始化时也能用;其余参数原样转发给
`dsh --profile dsh-tui`。
## 安全模式(`dsh-tui safe`)
dsh 意外结束时,安全模式提供只读的环境诊断、profile 插件清单与修复指引。
- **两个入口**:手动运行 `dsh-tui safe`;或 dsh 非零退出后按提示进入。
- 提示仅出现在交互终端;脚本/管道只加一行提示、退出码不变。
- 只覆盖最终 dsh 子进程的非零退出码,不含启动挂起(启动失败按退出码 1)。
- **只读边界**:诊断/清单/指引不改状态。两个例外:
- 重试正常启动;若 `~/.dsh-tui/resume.txt` 里有指针则一并带上
(`DSH_TUI_RESUME_SESSION`),崩溃后重试会回到当时所在会话而不是新空会话。
- 创建/复用救援 profile,只写 `$DSH_HOME/profiles/dsh-tui-safe/`。
注:每次 dsh 启动仍会写 `$DSH_HOME/profiles/node_modules` 回退链接与
pnpm 全局 store(非安全模式引入)。
- **救援 profile 必须干净,证不出就拒绝**。逐条校验,任一不成立即拒绝:
- 候选目录已存在,但不是可识别的 profile。
- 既有 profile 的根 manifest 声明了第三方插件。
- `$DSH_HOME/cordis.patch.yml`(home 层)**存在即拒绝**。
- `dsh-tui-safe/cordis.patch.yml`(profile 层)**有条目即拒绝**;dsh 默认
生成的「注释 + `[]`」不算条目。
删除/重建救援 profile 前会**按名字与形态核对顶层条目**,发现别的名字或
形态不符就拒绝并列出,**不会静默删你的文件**。
- **非交互**:`dsh-tui safe --rescue` 跑同一套门禁与创建/复用,只报结论
(就绪退出 0,拒绝退出 1)。
- **旧全局启动器**:profile 副本不可读或过旧时,先升级:
`npm install -g --legacy-peer-deps @deepseek-harness-tui/dsh-tui@<版本>`。
- **修复命令需自行执行**(安全模式只列出):
- `dsh plugin --profile dsh-tui remove <第三方插件>` 逐个移除可疑插件;
- `dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@<版本>`
重装对齐;
- `dsh-tui doctor` 环境诊断。
## 在 VS Code / Herdr / 任意终端中运行
- **VS Code**:可在集成终端直接运行,或用已上架 Marketplace 的 companion 扩展
`dsh-tui-vscode`(真实终端会话、会话历史、指定会话恢复、IDE 选区通道)。
见 [VS Code 使用指南](vscode.md)。
- **Herdr**:直接在 [Herdr](https://herdr.dev) 窗格中运行 `dsh-tui`,无需额外
配置;dsh-TUI 经 Herdr 本地集成 API 报告 `idle` / `working` / `blocked`
(问卷与工具审批记为 `blocked`),在 Herdr 之外不做任何事。
- **任意终端**:dsh-TUI 经 pty 用
[OSC 7501(Program Status Protocol)](https://www.superlogical.com/rex/docs/build/program-status)
报告 `idle` / `working` / `blocked` / `done` / `error`,实现了该协议的终端或
agent 收件箱可据此显示会话在做什么、何时需要你介入。未实现的终端会忽略该
序列,因此无需配置;设 `DSH_TUI_PROGRAM_STATUS=0` 可关闭报告。
## 更新到最新版本
项目迭代很快。一次 `/update`(或 `dsh-tui update`)会把**同一套互相兼容的版本**
对齐到三层并校验;TUI 内的 `/update` 校验后自动重启并恢复会话,`dsh-tui update`
只对齐、不进入 TUI、不重启:
1. **Profile 里的 TUI**:`dsh plugin --profile dsh-tui update @deepseek-harness-tui/dsh-tui@<version>`。
2. **全局 `dsh` 引擎**:目标版本 = 目标 TUI 的 `dsh-app-boot` peer 范围里
registry 上已发布的最高版本;用检测到的包管理器装进**同一个全局前缀**
(npm `--prefix` / `pnpm add -g`)。pnpm 只在能证明「所属安装组只含 `dsh`」时
自动安装:单包 `pnpm add -g` 会替换整组并移除同组其他命令,所以多成员组、
共享 store 或无法确定所属 home 的安装保持原样,只打印 `pnpm list -g --depth 0`
的检查与保留指引。
3. **全局 `dsh-tui` 启动器**:npm 布局逐文件原子替换(`bin/dsh-tui.js` 与
`package.json` 各一次 rename,两次之间失败就只换了前一个文件),pnpm 布局仅在
确认组内只有启动器时走 `pnpm add -g`,多成员组或无法确定的组保持原样(细节见下)。
执行顺序固定为 TUI → 引擎 → 启动器:TUI 安装失败时引擎原样未动,旧组合通常仍
可启动(超时或取消可能留下半装的 profile,见下文「更新安装的有界等待」,失败
文案会给恢复命令);引擎失败但当前组合仍在新 TUI 的范围内时继续重启,并打印
引擎修复命令;引擎步骤根本无法自动执行(pnpm 组不唯一、前缀不可写、安装形态
无法识别、registry 查不到等)时,更新仍继续(当前引擎在范围内),但会把
原因(有手工命令时一并)写入转录,`dsh-tui update` 以非零退出,不再静默当作整套成功;
**启动器对齐通常为 best effort;但引擎已推进后若启动器对齐失败,会拒绝重启**,
并打印手工修复命令:npm 同前缀里的旧启动器可能让新引擎加载不到更新后的 profile。
引擎未推进时,启动器失败仍只警告,不阻止重启。**永不降级**:引擎或启动器比目标
新时保持原样,并在启动期与 `/update` 时提示漂移。
有两种拒绝:预检发现「TUI 要升级,而当前引擎不在新 TUI 的 peer 范围内」时,
不拆树、不重启——官方插件管理器用**当前运行**的 dsh 校验新 TUI,而引擎步骤
排在 TUI 之后。若当前引擎**低于**该范围但可自动安装,拒绝文案给出「先升级引擎,
再重新 /update」的命令;若当前引擎**高于**该范围(比目标 TUI 验证过的更新),
不降级、也不安装未验证组合,文案只提示等声明支持它的 dsh-tui 发布后重新
`/update`,不打印安装命令;若预检通过、TUI 已升级之后引擎步骤才失败
(版本未前进,或旧引擎已不可用),则保留新 TUI、拒绝重启。
「旧引擎仍可用」必须由真实启动探测证明(在独立进程里启动 `bin.dsh` 入口且
`--version` 退出 0,或 `dsh --version` 能跑);入口文件存在、manifest 可读都不算。
pnpm 升级后若共享 runtime 回退链接仍指向保留的旧 store,仅当新入口属于同一
pnpm home、版本等于目标且启动探测通过时才刷新:POSIX 用原子 rename,Windows
先造暂存 junction、挪开旧链接再换位,失败恢复旧链接,恢复也失败则保留 backup
供人工核对。默认启动仍按 profile 链接和 PATH 两处校验;直接或委托 DSH 启动的
pnpm 安装则从原 home 重新定位所属单包组,校验目标 manifest 与实际 JS 入口报告的
版本,不让另一套 PATH 引擎否决。npm 就地升级以目标 manifest 与 PATH 启动探测为准;
若 profile 显式安装了宿主,上述快捷验证不启用,仍保留 profile-local 校验。
不改 profile 自己的依赖、普通目录或其他安装的链接。指向另一安装(例如旧 npx 缓存)的链接不会被无条件改写,更新计划也不再
把它当作当前引擎的来源。
预检拒绝会把当前版本、目标范围与下一步(命令可执行时附手工命令)写入会话转录;
若安装后引擎步骤才失败(TUI 已拆),同一份信息写入终端 stderr(`dsh-tui update`
也写 stderr),toast 只留一句短提示。拒绝还会按原因给出下一步:当前引擎不在
范围内但可升级时先升级引擎再重新 `/update`;高于范围时等 TUI 适配(不降级、
不打印安装命令);registry 查询
失败(离线/镜像不可达)是重试项,网络恢复后重新 `/update`;范围要求的 dsh 尚未
发布是等待项,发布后再 `/update`,不会打印一个装不上的命令;
`DSH_TUI_UPDATE_ENGINE=0` 关闭了自动安装,去掉开关或按命令手工装;全局安装无法
识别、不可写或 pnpm 组不唯一,按命令修复安装。若 TUI 已是最新、registry 上有更新
的 dsh 但超出该 TUI 声明的 peer 范围,`/update` 会明确说明「等 dsh-tui 适配」,
不会静默停在验证线,也不会安装未验证的引擎。
pnpm 轮换全局安装组后,直接 DSH 启动路径会重新解析并探测实际 JS 入口,保留原来的
`--profile`、`--patch` 等宿主参数;无法证明入口可启动时拒绝重启并打印修复命令,
不会继续执行已删除的旧组路径。
手动兜底(拒绝文案在命令可执行时给出对应布局的那一条;高于范围时只提示等 TUI
适配、不降级;版本尚未发布时只提示等待):
```sh
# 只对齐 TUI
dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@latest
# 对齐引擎
npm install -g @deepseek-ai/dsh@0.2.2-rc.5
# 或(pnpm 全局布局;先确认 dsh 所在全局组只有它自己,
# 否则单包安装会替换整组并移除同组其他命令)
pnpm add -g @deepseek-ai/dsh@0.2.2-rc.5
# 对齐全局启动器
npm install -g --legacy-peer-deps @deepseek-harness-tui/dsh-tui@latest
# 或(确认 pnpm 全局组内只有本包时;刚发布的版本见下面「pnpm 延迟」一条)
pnpm add -g --config.auto-install-peers=false @deepseek-harness-tui/dsh-tui@latest
```
通过全局 `dsh-tui` 命令启动时,Launcher 会在 `/update` 成功后自动对齐,且只操作
可证明的全局安装:npm 布局逐文件原子替换(`bin/dsh-tui.js` 与 `package.json` 各
一次 rename,两次之间失败就只换了前一个文件,启动器步骤按失败报告;引擎已推进时
拒绝重启,未推进时仍可重启),并且需要匹配的全局 bin 链接或 shim——项目内 npm/npx 安装不会被覆写。
pnpm 布局仅在确认组内只有启动器时走 `pnpm add -g`,不穿过 store 的符号链接。
pnpm 11+ 把一起安装的包隔离成组;重建多成员组可能丢失其他工具的必需 peer,
即使它们的直接版本没有变化,因此多成员组或无法确定的组保持原样,只打印检查与
保留依赖的指引,不自动重装;无法判定安装形态时同样保持原样、只留启动期提示。
旧启动器只有版本标记时,`dsh-tui` 与 `dst` 的 PATH 查找若落到不同安装,会跳过
自动对齐;pnpm 的逻辑组或 shim 归属优先于继承的 `PNPM_HOME`,共享 store 所在
目录不算归属证据。可证明安全的对齐步骤失败时会打印对应布局的手工命令。
逃生开关:`DSH_TUI_UPDATE_ENGINE=0` 跳过引擎自动安装(钉死引擎时,若新 TUI
不再支持当前引擎,升级仍会被拒绝);`DSH_TUI_UPDATE_LAUNCHER=0` 跳过启动器
对齐;`DSH_TUI_DSH_PM=npm|pnpm` 覆盖包管理器判定(诊断异常前缀用)。
- 不带 `@latest` 时 pnpm 会按 profile `package.json` 里已记录的版本范围
(如 `^0.1.4`)就地解析,可能停留在旧的主线上——这是"重复执行安装命令
但版本没变"的常见原因。
- 修复"版本不一致"时,优先使用拒绝/失败文案里的**精确版本**命令(例如
`npm install -g @deepseek-harness-tui/dsh-tui@0.8.3`);日常主动升级才
使用 `@latest`——`@latest` 可能比 profile 里的版本更新,装上反而继续不一致。
- pnpm 11+ 的全局安装是分组的:单包 `pnpm add -g` 会替换整组并移除同组其他
工具。`/update` 不会重建多成员组;只按直接版本重装全部成员也可能丢失其
自动安装的 peer。先运行 `pnpm list -g --depth 0` 检查组,手工修复前保留
全部成员及其已安装的 peer;若只重装启动器,使用独立的全局前缀。不要对
多成员组套用上面的单包命令,也不要使用 `pnpm update -g --latest`
(它会把整组都升到 latest)。
- pnpm 全局对齐的两个前提:`PNPM_HOME` 没导出也能对齐——从 shim 所在目录
(`<PNPM_HOME>` 或 `<PNPM_HOME>/bin`)反推,并核对组内确实有本包;
启动器单成员组安装**不解析 peer**——`@deepseek-ai/*` 全部由 profile 在运行时提供,
pnpm 的 peer 自动安装会顺着它们彼此的 peer 范围撞上**未发布的稳定线**,必然以
`ERR_PNPM_NO_MATCHING_VERSION` 失败,所以启动器的对齐与上面那条启动器手工命令
都带 `--config.auto-install-peers=false`(npm 那侧对应的开关是
`--legacy-peer-deps`,两者同口径)。
- pnpm ≥11 默认不装发布不足 24 小时的版本(`minimumReleaseAge`)。`/update` 与
`dsh-tui update` 对引擎与启动器这两步会临时放开该窗口
(`PNPM_CONFIG_MINIMUM_RELEASE_AGE=0`);手工执行上面那两条 `pnpm add -g` 时
同样要加这个前缀,否则刚发布的版本会装不上。
- 确认生效:启动横幅右上角显示当前版本(`✦ dsh-TUI vX.Y.Z`),重启后的
`DSH_TUI_UPDATED_FROM` / `DSH_TUI_UPDATED_DSH_FROM` 校验也会检查各层是否
真的前进。
- 用户覆盖层 `cordis.patch.yml` 在更新中原样保留。
- 会话数据的存放位置可能随版本变化(如 0.3.7 起 `/resume` 改用与 dsh web
共享的 JSONL 会话库),跨大版本更新后旧会话不在列表属预期,原数据不会被删除。
### pnpm 安装脚本拦截与异平台原生包
若 `dsh plugin` 安装时报 `ERR_PNPM_IGNORED_BUILDS`(pnpm ≥11 默认阻止带
安装脚本的依赖,如 `@google/genai`、`protobufjs`——这些脚本运行时不需要,
忽略即可),在 profile 的 `pnpm-workspace.yaml` 里加入:
```yaml
allowBuilds:
'@google/genai': false
protobufjs: false
```
`/update` 与 `dsh-tui update` 会自动写入这份配置,无需手工处理。
更新时还会维护 `ignoredOptionalDependencies`(忽略异平台原生包:`@img/sharp-*`
与 Claude SDK 的 `@anthropic-ai/claude-agent-sdk-*`):
- sharp 与 Claude SDK 都以全平台可选依赖分发,不处理时 pnpm 的 update 路径会
把各平台二进制一起解析/下载(实测 sharp 约 200MB;Claude SDK 单个包解包约
230MB,0.15 → 0.16 的一次更新多下 7 个异平台包,约 1.6GB)。
- 名单每次更新按当前平台重算:当前平台的原生包与无平台归属的 wasm 回退包
保留,异平台的整段跳过(pnpm 在解析阶段就不取它们,lockfile 里也不再出现)。
- SDK 本身不会被更新装进 profile:只有在内核选择器里选中该后端才安装,安装前
也按当前机器重算名单,只装本平台对应的那个包。不用的后端一直不占空间。
- 把 profile 搬到别的平台或 musl 容器后,在那台机器上跑一次更新或内核安装
即可刷新。
- 老 profile 的 lockfile 里仍写着全平台条目,第一次更新会照旧下载一遍,之后
才被忽略。
- 块内不属于这两张平台表的条目(`fsevents`、自己写的 `@img/sharp-wasm32`
豁免)原样保留;需要 pnpm 支持该键,不认识的版本不会因此报错,只失去这项
收益。
## Profile 配置
用户覆盖文件位于:
```text
$DSH_HOME/profiles/dsh-tui/cordis.patch.yml
```
配置一个节点时,`config` 块是整段替换,不是逐字段深合并。复制示例时需要保留
仍然有效的字段。完整说明见[配置参考](configuration.md)。
仓库根目录的 `cordis.yml` 是裸组合示例;正常的 npm/profile 安装以
`cordis.patch.yml` 为准,不需要把根配置复制到 profile。
## 从源码开发
```sh
git clone --recurse-submodules https://github.com/ccch1mneyyy/dsh-TUI.git
cd dsh-TUI
pnpm install --frozen-lockfile
pnpm build
pnpm smoke
```
本仓库只有一个子模块,且安装必需:
- `vendor/dsh-std`:`pnpm-workspace.yaml` 把 `vendor/dsh-std/packages/*` 列为
workspace 包。
TUI Profile(插件准入与私有协议定义)在 `tui-profile/`,是**普通文件**(不再是
子模块),随本仓库代码一起检出与修订,供契约检查使用。
漏掉 `--recurse-submodules` 会让这些目录为空,
`pnpm install --frozen-lockfile` 直接失败。已经克隆过的检出补一条:
```sh
git submodule update --init --recursive
```
`pnpm build` 会清理忽略入库的 `lib/`,把 `src/` 编译到 `lib/types/`,再运行
构建门禁。
- **Git URL 安装不受支持**(workspace 依赖/子模块/pnpm ≥11 prepare 白名单
三重阻断)。
- 发布 workflow 也会在打包前显式执行干净编译和包面验证。
真实测试当前源码时,首次使用或正式模型/密钥配置变化后运行:
```sh
pnpm dev:copy-config
```
以后每次修改源码后,一条命令构建、打包、隔离安装并启动:
```sh
pnpm dev
```
`pnpm dev` 默认保留完整 install/build/pack 检查。显式本地快速迭代可设置
`DSH_TUI_DEV_FAST=1`,例如 `DSH_TUI_DEV_FAST=1 pnpm dev -- --no-launch`。
缓存未命中时执行 frozen install、`compile`、不重复 `prepare` 的打包与隔离安装。
只有源码/配置与编译加载器内容、Node/pnpm/npm/dsh 版本、编译与 vendor 产物、tarball 和已安装包/profile 均匹配时,
才跳过这四步。若替换 pnpm/npm/dsh 而报告版本不变,须先运行一次普通(非 fast)开发流程。内部文档链接(如 `CLAUDE.md -> AGENTS.md`)参与指纹;树外、被排除、
悬空或循环链接以及不可读输入会禁用复用并打印原因。工作开始前即作废旧成功标记,
失败不写新标记。脚本输出阶段耗时与命中状态。发布前仍须正常执行 `pnpm build`
和聚焦回归;快速模式不改变发布门禁。
`pnpm dev:copy-config` 只复制 `~/.dsh/settings.yaml` 与
`~/.dsh/.credentials.yaml`。Unix 上文件权限设为 `0600`;Windows 使用系统管理的
文件 ACL。
`pnpm dev` 使用独立的 `HOME`、`DSH_HOME` 和会话目录,不覆盖正式
`~/.dsh/profiles/dsh-tui`、`~/.dsh-tui` 或正式会话。默认测试目录:
- Unix:`$XDG_CACHE_HOME/dsh-tui-dev`(未设置时为 `~/.cache/dsh-tui-dev`)。
- Windows:`%LOCALAPPDATA%\dsh-tui-dev`。
- 可通过 `DSH_TUI_DEV_ROOT` 覆盖。
不启动 TUI、只验证构建、打包和安装流程时运行:
```sh
pnpm dev:test
```
CI 还会运行三条渲染回归:
```sh
node --import tsx/esm scripts/repro-askpanel.tsx
node --import tsx/esm scripts/verify-askpanel-layout.tsx
node --import tsx/esm scripts/repro-toolcards.tsx
```
`pnpm tui` 调用的 `scripts/run.ts` 直接组合 DeepSeek Harness 源码 patch,默认
假设包位于 Harness monorepo 的 `packages/*` 布局中;独立 checkout 需要另外
设置 `DSH_TUI_DEV_WORKSPACE` 指向 Harness 根目录。只测试本仓库当前源码时,
优先使用上述 `pnpm dev`,它会走与用户安装一致的 profile 路径。
## 常见问题
### Git URL 安装报错
Git URL(如 `https://github.com/ccch1mneyyy/dsh-TUI`)安装不受支持,报以下错误码:
- `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`
- `ERR_PNPM_WORKSPACE_PKG_NOT_FOUND`
三重阻断:
- 源 manifest 的 `@dsh-std/*` 是 workspace 依赖(git tarball 原样保留,
profile 内无法解析)。
- `vendor/dsh-std` 是 git 子模块(依赖抓取不带子模块内容,编译必败)。
- pnpm ≥11 默认拒绝 git 依赖执行 `prepare` 构建脚本。
请安装 registry 包:
```sh
dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui
```
### `dsh-tui requires an interactive terminal`
stdout 不是 TTY。请直接在终端中启动,不要把主进程输出管道到文件或其他命令。
如果 dsh-tui 只是装在某个 profile 里、而实际由 Web / Tauri / GUI 等非终端
宿主启动 DSH,dsh-tui 会检测到 stdout 不是 TTY 且并非由 `dsh-tui` launcher
启动,自动跳过 TUI 前端(不报错、不影响宿主启动)。
只有显式执行 `dsh-tui`(含 standalone 便携版)却没有 TTY 时,才会报上面的
错误。
### 找不到 `dsh` 或 `pnpm`
确认全局 npm bin 目录在 `PATH` 中,并重新打开终端。`install.sh` 会在安装前
检查这两个命令。
### 启动后立刻退回 shell,几乎没有报错(pnpm 9)
pnpm 9 安装的 profile 里,传递依赖 `dsh-working-activity` 不会被提升到
loader 可解析的位置,模块解析失败导致整棵插件树被回收,TUI 打印 resume
提示后直接退出(issue #60)。升级 pnpm 到 10+ 后重装即可:
```sh
npm install -g pnpm@latest
dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@latest
```
### 模型启动失败或提示没有凭证
若使用 `deepseek-official`,确认启动 `dsh` 的同一个 Shell 中存在 `DEEPSEEK_API_KEY`;
自定义端点同时检查 `DEEPSEEK_BASE_URL`。若使用 `deepseek-account` 或订阅模型,
用 `/auth status` 检查登录状态,必要时重新运行 `/auth login <provider>`。
### 浏览器能访问、dsh-tui 连不上自建 HTTPS 端点(自签证书 / 私有 CA)
内网自建的 LLM token 服务器常用 Caddy、mkcert、Step CA 等签发 HTTPS 证书,这类根证书不在 Node.js 内置的 Mozilla CA 列表里。于是浏览器和系统级 `curl` 都能正常访问,dsh-tui 切到该 provider 后却在 TLS 握手阶段失败,报 `self-signed certificate in certificate chain` 或 `UNABLE_TO_VERIFY_LEAF_SIGNATURE`。
原因是 dsh-tui 的 HTTP 请求跑在 Node.js 的 TLS 层上,而 Node.js 只信任两样东西:编译时打包的 Mozilla CA bundle,以及环境变量 `NODE_EXTRA_CA_CERTS` 指向的 PEM 文件(与内置列表合并)。macOS Keychain 里的「信任」设置对 Node.js 进程无效——Node 不调用系统的 Security.framework,浏览器和 `curl` 用的信任链跟它无关。
解决办法是把根证书导出成 PEM,在启动 dsh-tui 之前设置该变量:
```sh
export NODE_EXTRA_CA_CERTS=/path/to/your-ca-root.pem
dsh-tui
```
注意 `NODE_EXTRA_CA_CERTS` 属于 DSH 启动器的 bootstrap 保护变量:任何 `.env` 文件(项目目录的 `.env` 与 `~/.dsh/.env` 都算)都不允许设置它,写进去会在启动时直接报错退出并提示改用 `export`,只能由启动 dsh 的那个 Shell 环境继承。同组受保护的证书 / TLS 变量还有 `SSL_CERT_FILE`、`SSL_CERT_DIR`、`NODE_TLS_REJECT_UNAUTHORIZED` 等。
### 工作状态行重复
检查 profile 是否曾单独添加 `dsh-working-activity`。保留本包 patch 自动插入的
`working-activity` 行,移除重复 bundle 配置。
### TUI 显示错位或终端退出后状态异常
先运行 `/doctor`,记录终端类型和模式,再参考[交互文档](interaction.md)与
[架构文档](architecture.md)。渲染问题可使用 `DSH_TUI_RENDER_LOG` 采集原始帧,
但日志可能包含会话可见内容,应妥善处理。
### 在 Orca 终端里会话内的 git 全部失败(`unable to parse command-line config`)
Orca 会给 agent 终端注入 git 的索引配置协议 `GIT_CONFIG_COUNT` + `GIT_CONFIG_KEY_n` +
`GIT_CONFIG_VALUE_n`(用来关闭凭据管理器的弹窗)。引擎在派生子进程时按**变量名**剔除
凭据形状的变量(`/KEY|PASSWORD|SECRET|TOKEN/i`),于是 `GIT_CONFIG_KEY_n` 被删,
`GIT_CONFIG_COUNT` 与 `GIT_CONFIG_VALUE_n` 留下;git 只拿到残缺的三元组,任何命令都
直接 `fatal: unable to parse command-line config`(exit 128)。
根因在引擎包的 `scrubbedParentEnv()`,与 dsh-tui 无关(issue #1811)。规避办法是在启动
dsh-tui 前去掉 `GIT_CONFIG_COUNT`——没有它时 git 会忽略孤立的 `KEY`/`VALUE`:
```sh
env -u GIT_CONFIG_COUNT dsh-tui
```
代价是失去 Orca 对凭据弹窗的抑制;需要非交互凭据时改用 `GIT_TERMINAL_PROMPT=0`。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |