# my-dpsk-harness-tui 安装与升级

本项目是 dsh profile bundle，不是独立的 dsh 实现；同时提供 `dpsk` 启动器。bundle 由 dsh profile 加载，启动器则调用系统 PATH 中的官方 `dsh`。

全局安装 tarball 只用于安装 `dpsk` 启动器；它不会单独提供 dsh runtime。

## 全局安装启动器
全局安装本地 tarball 时，包内的 dsh 宿主 peer 依赖已标记为 optional，npm 11 可以继续完成依赖解析，不会因该 peer 图在 Arborist 中触发 `null.children` 崩溃。

```sh
# 先把 GitHub Release 中的 my-dpsk-harness-tui-0.5.0.tgz 下载到当前目录，再安装
npm install --global ./my-dpsk-harness-tui-0.5.0.tgz
```

随后安装官方 dsh（若尚未安装），再运行启动器：

```sh
npm install --global @deepseek-ai/dsh@0.2.0-rc.2
dpsk
```

如果只安装了 `my-dpsk-harness-tui` 而没有官方 `dsh`，运行 `dpsk` 时出现 `dsh is not recognized` 是预期错误；请先安装上面的官方 dsh。插件实际运行仍推荐使用下方的 `dsh plugin ... add`，由 tui profile 提供宿主依赖。

## 兼容性

| 项目 | 要求 |
|---|---|
| Node.js | `^22.19.0` 或 `>=24.0.0` |
| pnpm | `11.7.0` 或兼容的 pnpm 11 |
| dsh | `0.2.0-rc.2` / `0.2.1-rc.2` |
| 终端 | 支持 truecolor；Nerd Font 可获得完整图标显示 |

当前 dsh 仍处于 developer preview，升级 dsh 可能包含兼容性破坏变更。本项目当前同时适配 `0.2.0-rc.2` 与 `0.2.1-rc.2`；下面的 `0.2.0-rc.2` 命令也可按需替换为 `0.2.1-rc.2`。首次安装仍建议固定 dsh 版本和插件 release tag。

## 首选：安装 GitHub Release 资产

发布者会在 GitHub Release 中提供由 `pnpm pack` 生成的 tarball：

```sh
# 没有 pnpm 时，任选其一：
npm install --global pnpm@11.7.0
# 或：corepack enable

npx --yes @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile tui add \
  https://github.com/mytianyi0712/my-dpsk-harness-tui/releases/download/v0.5.0/my-dpsk-harness-tui-0.5.0.tgz
```

tarball 已经包含构建后的 `lib/`，安装时不需要在用户机器上编译项目，也不会执行 Git 依赖的 `prepare` 构建流程。

## 直接从 GitHub tag 安装

Release 尚未创建或需要安装某个提交时，可以直接安装 Git 仓库。Git 依赖包含 `prepare` 构建脚本；pnpm 11 默认会阻止依赖构建脚本，因此必须显式允许本项目构建：

```sh
npx --yes @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile tui add \
  --allow-build=my-dpsk-harness-tui \
  github:mytianyi0712/my-dpsk-harness-tui#v0.5.0
```

不要省略 `--allow-build=my-dpsk-harness-tui`。如果 pnpm 已打印了 `allowBuilds` 建议，也可以按提示将该精确包名写入 `~/.config/pnpm/rc` 或 profile 的 `pnpm-workspace.yaml` 后重试。

固定 tag 比直接使用 `#main` 安全、可复现；开发测试才使用：

```sh
npx --yes @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile tui add \
  --allow-build=my-dpsk-harness-tui \
  github:mytianyi0712/my-dpsk-harness-tui#main
```

## 启动

如果使用 `npx`：

```sh
npx --yes @deepseek-ai/dsh@0.2.0-rc.2 --profile tui
npx --yes @deepseek-ai/dsh@0.2.0-rc.2 --profile tui --resume <session-id>
```

也可以安装 dsh launcher 后直接使用 `dsh`：

```sh
npm install --global @deepseek-ai/dsh@0.2.0-rc.2
dsh --profile tui
```

或者使用本项目自带的 `dpsk` 启动器（它只从系统 PATH 中查找官方 `dsh`，不通过 npx 下载或缓存 dsh）。用 `dsh plugin add` 安装 tgz 后，`dpsk` 会出现在 profile 的 `.bin` 目录。正常启动不迁移配置、不自动升级；首次尚无 tui profile 时会静默安装当前启动器包（可用 `DPSK_NO_BOOTSTRAP=1` 跳过）。从 GitHub 获取新版本并做适配：

```sh
# 把 profile 的 .bin 目录加入 PATH（一次性）后：
export PATH="$HOME/.dsh/profiles/tui/node_modules/.bin:$PATH"   # Git Bash / zsh
dpsk
dpsk --resume <session-id>
dpsk check
dpsk update
dpsk sessions            # 会话库里各格式的数量
dpsk sessions migrate    # 旧构建的 v0 会话转成当前可读的 v4（原文件保留）

# Windows PowerShell（一次性）：
$env:PATH = "$HOME\.dsh\profiles\tui\node_modules\.bin;$env:PATH"
dpsk
```

### 渲染器路径（默认）

终端交给独立的 OpenTUI 渲染器子进程；pi-tui 渲染基座已随 0.5.0 退出删除，没有回退
路径。渲染器是 Bun 编译的单文件产物，用户不需要安装 Bun：

```sh
dpsk                              # 渲染器界面（默认路径）
dpsk renderer install            # 只下载并校验当前平台产物
dpsk renderer path              # 打印缓存路径
dpsk renderer check             # 本地哈希与随包 SHA256SUMS.json 比对
DSH_RENDERER_PATH=/path/to/dpsk-renderer-win32-x64.exe dpsk   # 显式指定产物
```

启动时自动确保产物在缓存里并把路径写入 `DSH_RENDERER_PATH`；取不到产物时报告并以
非零码退出。`DSH_RENDERER_PATH` 可显式指定产物路径（测试与开发构建用）。

### 守护进程与开机启动

`dpsk` 默认连接本地 headless core；未运行时先启动 core，再在终端里启动 TUI 外壳。

```sh
dpsk daemon status
dpsk daemon start
dpsk daemon stop
dpsk daemon restart
dpsk daemon logs
```

/exit、Ctrl+C 和关闭终端只 detach TUI，后台任务继续；/shutdown 才会彻底结束 core。
设置页的开机启动核心会在 Windows 注册 HKCU Run、在 macOS 写 LaunchAgent、在 Linux 写 XDG autostart。
设置 DPSK_EMBEDDED=1 可退回旧的内嵌单进程模式。

### 新版界面

```sh
dpsk check          # 先把 tui profile 同步到全局包（同版本内容漂移只有 check 会覆盖）
dpsk                # 渲染器界面（默认路径）
```

进入后应当看到顶部 `dpsk host: my-dpsk-harness-tui 0.5.0` 与 `会话:` / `会话列表:` 行，
底部状态行形如 `status: idle · cliproxy/mimo-v2.6-pro · max · workspace-write · standard`。
键位：`ctrl+p` 命令面板、`ctrl+x` leader（`n` 新会话 / `l` 会话列表 / `m` 模型 /
`t` 主题 / `c` 压缩 / `s` 设置 / `q` 退出）、`ctrl+t` 循环思考强度、`↑`/`↓` composer 历史、
生成中直接回车排队插话、`/` 斜杠补全、`@` 路径补全。设置页里可以改供应商表单
（含 `[ 探测上游模型 ]` 与 `[ 编辑模型 ]` 两个入口）。

`dpsk` 启动却仍是旧界面，通常是 profile 里还留着 0.4.0 的旧包 `dsh-omp-tui` 把新包整体
遮住（`dsh --profile tui --dump-config` 里仍出现 `dsh-omp-tui` 即此因，见下方「从 0.4.x
升级到 0.5.0」）。缓存里的渲染器产物是 0.4.x 时代的旧二进制时，`dpsk renderer install`
按当前版本号重新下载并校验。

启动器下载产物时**先比字节数再比 SHA-256**，两者都过才落盘并置可执行位；缓存目录
`~/.dsh/dpsk/renderer/<version>-<platform>/`。取不到产物时 `dpsk` 报告并以非零码退出
（pi-tui 渲染基座已删除，没有回退路径），不会 spawn 不存在的路径。渲染器接管 TTY 后，
dsh 的 stdout / stderr 改道追加写入 `$DSH_HOME/logs/tui-<pid>.log`。渲染器崩溃或被 kill
时宿主在子进程退出后补发终端恢复序列并打印报告；正常退出走渲染器自己的 `destroy()`，
宿主不补发。

验证 profile 已组合成功：

```sh
dsh --profile tui --dump-config
```

输出中应包含 `my-dpsk-harness-tui` bundle，以及 `my-dpsk-harness-tui/startup`、`my-dpsk-harness-tui/prompt`、`my-dpsk-harness-tui/session-title`、`my-dpsk-harness-tui/session-persistence`、`my-dpsk-harness-tui/wechat` 和 `my-dpsk-harness-tui` 行。

## 配置模型

官方 DeepSeek API：

```sh
# Git Bash / zsh
export DEEPSEEK_API_KEY='your-key'

# PowerShell
$env:DEEPSEEK_API_KEY = 'your-key'
```

本地 OpenAI-compatible 网关：

```sh
# Git Bash / zsh
export DEEPSEEK_BASE_URL='http://10.0.0.1:3000/v1'

# PowerShell
$env:DEEPSEEK_BASE_URL = 'http://10.0.0.1:3000/v1'
```

`cordis.patch.yml` 当前默认 agent 为 `deepseek-official/deepseek-v4-flash`。启动后可以用 `/model` 选择并持久化 provider、model 和 reasoning effort。

## 升级

推荐用新的 release tarball 明确切换版本：

```sh
dsh plugin --profile tui add \
  https://github.com/mytianyi0712/my-dpsk-harness-tui/releases/download/v0.5.0/my-dpsk-harness-tui-0.5.0.tgz
```

若当前依赖跟踪的是 `main`，可以更新 Git 依赖：

```sh
dsh plugin --profile tui update my-dpsk-harness-tui
```

升级后重新检查：

```sh
dsh --profile tui --dump-config
dsh --profile tui
```

### 从 0.4.x 升级到 0.5.0

0.5.0 改了包名、启动器名与 settings 命名空间，升级时注意四件事：

1. **启动器要重装才有 `dpsk` 命令**：全局安装的新包提供 `dpsk`，旧的 `omdsh` 不会自动消失，也不会被新包更新。

   ```sh
   npm uninstall --global dsh-omp-tui
   npm install --global ./my-dpsk-harness-tui-0.5.0.tgz
   dpsk --help          # 确认命令存在
   ```

   如果旧全局包当初是用 `npm link`（或安装目录软链）装的，npm **不会**为改名后的 bin 重新生成 shim：链接目录里的 `package.json` 已经写着 `bin: { dpsk }`，PATH 里却仍然只有指向 `scripts/omdsh.js`（改名后已不存在）的旧 shim。此时先删掉那个链接本身（Windows 用 `cmd /c rmdir "<npm 全局 node_modules 下的链接名>"`——只删链接，不碰它指向的目录；**不要**用递归删除，那会顺着链接删进你的源码目录），再装 tarball，并手工删除残留的 `omdsh` / `omdsh.cmd` / `omdsh.ps1`。

2. **旧包必须从 profile 里摘干净，不只是目录让位**：`dsh-omp-tui` 与 `my-dpsk-harness-tui` 注册**同一个 `tui` 服务**和同一个 session-title provider。两份包同时留在 profile 里时，先加载的旧包赢，新包的条目整体报 `2 entries did not activate`——用户看到的现象是「新包根本没装上」（旧界面，或什么都没有）。`dpsk` 启动、`dpsk check`、`dpsk update` 现在都会自动把旧包从 profile `package.json` 的 `dsh.profile.bundles` 与 `dependencies`/`devDependencies` 里摘掉，并把 `node_modules/dsh-omp-tui` 重命名为 `dsh-omp-tui.dpsk-legacy-<时间戳>`（内容保留，确认无异常后可自行删除）。也可手工：

   ```sh
   dsh plugin --profile tui rm dsh-omp-tui
   ```

3. **settings 自动迁移**：首次激活时把 `tui` 行的值写入 `dpsk-tui`，`session-title-llm-tui` 行的值写入 `dpsk-session-title`，并在启动后打印迁移报告。新命名空间已有值的字段不会被旧值覆盖，重启后不再写入。

4. **验证真的装好了**：

   ```sh
   dsh --profile tui --dump-config | Select-String dsh-omp-tui   # 应无输出
   dpsk check                                                     # 全局与 profile 源包哈希一致
   dpsk                                                           # 不应打印 entries did not activate
   ```

## 卸载

```sh
dsh plugin --profile tui remove my-dpsk-harness-tui
```

这会从 profile 依赖和 `dsh.profile.bundles` 中同时移除该 bundle，不会删除已有 session 数据。

## 本地开发安装

```sh
git clone https://github.com/mytianyi0712/my-dpsk-harness-tui.git
cd my-dpsk-harness-tui
pnpm install
pnpm run check
pnpm run prepare

# dsh 会把相对路径按调用目录解析；link 适合持续开发
npx --yes @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile tui add link:.
```

修改源码后运行 `pnpm run prepare`，link profile 会立即使用新的 `lib/`。需要模拟发布拷贝时使用：

```sh
npx --yes @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile tui add file:.
```

## 微信桥（WeChat iLink）

本 bundle 同时安装微信桥服务。启动后使用：

```sh
/wechat-login      # 扫码登录
/wechat-pair <码>  # 批准微信配对码
/wechat-status     # 查看桥状态
/wechat-notify on  # 终端任务也推送微信
```

微信里以 `@dsh` 开头的消息为远程命令，仅限微信侧调用；这些命令不会出现在本地
`/help`、命令补全菜单中，也无法在本地以 `/dsh-*` 形式执行。`@dsh chat` 会切换为
实时分段接收模型文本的 chat 模式（无进度汇报）；`@dsh work` 会切换为任务完成后接收结果
及配置进度汇报的 work 模式。切换后，所有普通微信消息持续使用所选模式。状态目录为
`~/.dsh/wechat-ilink/`（可用 `DSH_WECHAT_ILINK_STATE` 覆盖）。

## 常见问题

### `pnpm: command not found`

安装 `pnpm@11.7.0`，然后确认 `pnpm --version` 输出为 pnpm 11。

### Git 安装被阻止，提示 `allowBuilds`

重新运行安装命令，并保留：

```sh
--allow-build=my-dpsk-harness-tui
```

Git 安装会从源码执行 `prepare`，这是 pnpm 的供应链保护行为，不是 dsh 运行时错误。

### API 请求失败

确认 `DEEPSEEK_API_KEY` 或 `DEEPSEEK_BASE_URL` 在启动 dsh 的同一个 shell 中可见；本地网关还必须提供兼容 `/v1` 的接口。

### 图标显示为方框

安装并启用 Nerd Font，然后重启终端。布局和功能不依赖 Nerd Font，但图标会回退为方框或普通字符。

### Windows 路径

PowerShell 使用上面的 `$env:...` 语法；Git Bash 可直接运行 `npx`、`pnpm` 和 dsh 命令。路径包含空格时用引号包住完整路径。