# 安装、操作与排错

[English](usage.md) | 中文

## 选择发行形态

- 需要完整本地工作台：安装 **Oh-DSH Desktop**。
- 只需要浏览器交互：安装 **Oh-DSH Web**，不携带 Electron。
- 纯终端交互：安装 **Oh-DSH TUI**，不携带 Electron 或浏览器 UI。

Release 提供完整版、Web-only 与 TUI-only 三种形态；命令行安装器默认先安装
TUI，其他 surface 可以按需指定。

## 使用 install.sh 安装

仓库根目录的 `install.sh` 可以在不克隆仓库的情况下，在 macOS 与 Linux 安装
最新稳定 Release。它需要 `curl` 和 `tar`（macOS desktop 包还需要 `ditto` 或
`unzip`），web/tui 的用户级安装不需要 root。

```sh
curl -fsSL \
  https://raw.githubusercontent.com/hust-open-atom-club/oh-dsh/main/install.sh \
  | bash
```

Windows 使用对应的 `install.ps1`，安装相同的 surface（desktop 通过 NSIS
安装器的静默模式完成）。它需要 PowerShell 5.1+ 和 `tar`，两者都内置于
Windows 10 1803+：

```powershell
irm https://raw.githubusercontent.com/hust-open-atom-club/oh-dsh/main/install.ps1 | iex
```

两个脚本接受相同的选项；PowerShell 使用 `-Surface`、`-Version`、`-Dest`、
`-BinDir`、`-Force`、`-Uninstall` 参数，对应小写旗标。

Surface 矩阵与默认位置：

| Surface | macOS (arm64/x64) | Linux (x64) | Windows (x64) |
| --- | --- | --- | --- |
| desktop | `Oh-DSH Desktop.app` 安装到 `/Applications` 并刷新 Launch Services，同时在 `~/.local/bin` 注册 `ohdsh desktop` | AppImage 安装到 `~/.local/bin/oh-dsh-desktop`，同时在 `~/.local/bin` 注册 `ohdsh desktop` | 静默运行 NSIS 安装器（用户级），同时注册 `ohdsh desktop` |
| web | 载荷在 `~/.local/share/oh-dsh/web`，并在 `~/.local/bin` 创建调度式 `ohdsh` 启动器 | 同左 | 载荷在 `%LOCALAPPDATA%\oh-dsh\web`，并在 `%LOCALAPPDATA%\oh-dsh\bin` 创建 `ohdsh.cmd`（自动加入用户 PATH） |
| tui（默认） | 载荷在 `~/.local/share/oh-dsh/tui`，并在 `~/.local/bin` 创建调度式 `ohdsh` 启动器 | 同左 | 载荷在 `%LOCALAPPDATA%\oh-dsh\tui`，并在 `%LOCALAPPDATA%\oh-dsh\bin` 创建 `ohdsh.cmd`（自动加入用户 PATH） |

只有 desktop 会创建桌面应用入口；web 和 tui 不会注册 Launch Services，
也不会生成 `.app` 包；desktop 安装也会注册统一的 `ohdsh` dispatcher。

web 与 tui 的载荷各自只携带自己 surface 的依赖，因此两者可以并行安装：
共享的 `ohdsh` 启动器记录每个 surface 的载荷位置，把 `ohdsh web` 与
`ohdsh tui` 路由到对应的安装。卸载其中一个 surface 不影响另一个继续使用。

选项：

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `--surface` | `tui` | `desktop`、`web` 或 `tui`，每个 surface 只安装自己的文件与启动器 |
| `--version` | 最新稳定版 | 固定 Release 标签，如 `v0.1.8`。预发布不会被自动选中，只有在显式固定时才会安装 |
| `--local` | 关闭 | 安装本仓库 `pnpm run dist:<surface>` 构建到 `release/` 的产物，而不是下载 Release。版本取自仓库的 `package.json`；重装同版本重建产物时配合 `--force` |
| `--local-root` | 脚本所在目录 | 让 `--local` 指向另一个仓库检出 |
| `--dest` | 见上表 | 目标目录 |
| `--bin-dir` | `~/.local/bin` | `ohdsh` 启动器目录 |
| `--repo` | `hust-open-atom-club/oh-dsh` | 从其他 fork 安装 |
| `--force` | 关闭 | 已安装相同版本时强制重装 |
| `--uninstall` | 关闭 | 卸载对应 surface |
| `--os`、`--arch` | 自动检测 | 覆盖目标选择（`darwin`/`linux`、`arm64`/`x64`） |

等价的环境变量：`OH_DSH_SURFACE`、`OH_DSH_VERSION`、`OH_DSH_INSTALL_DIR`、
`OH_DSH_BIN_DIR`、`OH_DSH_REPO`、`OH_DSH_OS`、`OH_DSH_ARCH`
（`OH_DSH_LOCAL=1` 等价 `--local`）；命令行选项优先于环境变量。

要测试自己正在改的分支，先构建对应表面，再直接从检出安装——不需要发布
Release，也没有网络往返：

```sh
pnpm run dist:tui && sh install.sh --local --surface tui --force
pnpm run dist:web && sh install.sh --local --surface web --force
pnpm run dist:mac && sh install.sh --local --surface desktop --force
```

`GH_TOKEN`/`GITHUB_TOKEN` 用于 GitHub API 鉴权（在限流时有用），
`OH_DSH_API_BASE`/`OH_DSH_DOWNLOAD_BASE` 可为测试覆盖端点地址。

升级、校验与卸载行为：

- 安装器读取 GitHub 为每个 Release 资产发布的 SHA-256 摘要，并在改动旧
  安装之前完成校验。下载失败、摘要不匹配或解压中断都会保持原安装可用并
  报告错误；未完成的暂存文件会被清理。
- 重复执行且版本不变时为无操作，除非传入 `--force`。新版本会原子替换载荷
  并刷新 `ohdsh` 启动器。
- 升级采用原地替换：新安装验证通过后，旧的应用包、AppImage 或载荷会连同
  残留的暂存目录与升级前备份一起删除，每个 surface 只保留一份 Oh-DSH
  安装。
- 在 macOS 上，desktop 会刷新 Launch Services 并清退残留的
  `Oh-DSH-Desktop.app`，只显示一个应用入口。未公证构建仍可能需要下文的
  右键 **打开** 首次放行。
- 卸载使用 `sh install.sh --uninstall --surface <name>`（Windows 用
  `install.ps1 -Uninstall`），并沿用安装时的目标目录覆盖。

## 启动时自动更新检查

每个 surface 在每次启动时检查一次是否有更新的稳定 Release：

- **TUI** 在第一帧之前打印一行提示，例如
  `Oh-DSH 0.1.8 -> 0.2.0 is available. Run "ohdsh update" to upgrade.`
- **Web** 在监听地址之后打印同样的提示。
- **Desktop** 通过更新窗口检查，发现新版本时弹出系统通知，点击即可打开
  更新窗口。desktop 仍通过自带的校验更新器安装更新，而不是 shell 安装器。

`ohdsh update`（或 `ohdsh update web` / `ohdsh update tui`）在 macOS、
Linux 与 Windows 上升级已打包的 web/tui 发行版：它重新运行对应平台的
安装脚本，走与全新安装相同的校验与原子替换流程。安装来源采用 Codex
式的推断——依据运行路径、载荷内的安装标记以及 `launcher.env` 记录的
目标位置——绝不依赖构建时注入的标记，并会还原安装时的
`--dest`/`--bin-dir`，让更新落在当初安装的位置。位于安装器不认识的
路径上的安装会被拒绝并给出指引。在源码检出中执行时会提示改用 git。

更新只基于 Release：所有 surface 都用 semver 与已发布的稳定 GitHub
Release 比较；不存在 commit 级或滚动更新通道。

更新检查使用公开的 GitHub API，最多阻塞启动约 1.5 秒，离线时静默失败。
设置 `OH_DSH_UPDATE_CHECK=0` 可在所有 surface 上关闭检查。`ohdsh update`
优先使用打包在包内 `lib/oh-dsh/install.sh`（或 `install.ps1`）的安装
脚本，仅当包内没有时才通过 TLS 从仓库 `main` 分支下载；
`OH_DSH_INSTALL_SCRIPT_URL` 可将下载指向镜像或本地副本以便测试。在
Windows 上，更新会在当前进程退出后以分离方式执行，因为运行中的载荷
无法在执行时被替换。

## 安装完整版

### macOS

1. 从最新 Release 下载 DMG。
2. 将 **Oh-DSH Desktop** 拖入 Applications。
3. 未公证的测试构建首次运行时，在 Finder 中右键应用并选择“打开”。

如确认文件来自项目 Release，但仍被 quarantine 阻止，可对实际下载文件执行：

```sh
xattr -d com.apple.quarantine ~/Downloads/Oh-DSH-Desktop-*.dmg
```

安装统一命令：

```sh
sudo ln -sf \
  "/Applications/Oh-DSH Desktop.app/Contents/Resources/bin/ohdsh" \
  /usr/local/bin/ohdsh
```

### Linux

AppImage：

```sh
chmod +x Oh-DSH-Desktop-*.AppImage
./Oh-DSH-Desktop-*.AppImage
```

deb：

```sh
sudo apt install ./Oh-DSH-Desktop-*.deb
```

### Windows

运行 Release 中的 Windows 安装器并启动 **Oh-DSH Desktop**。统一 CLI 位于应用
资源目录的 `bin\ohdsh.cmd`，可以将该目录加入 `PATH`。

未签名安装器可能触发 Windows SmartScreen。确认文件来自项目 Release 后，选择
“更多信息”再选择“仍要运行”；安装过程可能请求管理员授权。

窗口标题栏、菜单栏与工具条合并为一行；点击该行左角的菜单名即可打开应用菜单。

关闭窗口会将 Oh-DSH Desktop 最小化到系统托盘而不是退出：点击托盘图标可恢复
窗口，通过托盘（或应用）菜单中的 **退出 Oh-DSH Desktop** 退出应用。macOS 与
Linux 保持原有的关闭行为。

### Desktop 在线更新

在应用菜单中选择 **Oh-DSH Desktop -> 检查更新…**。更新窗口只检查
`hust-open-atom-club/oh-dsh` 的 stable GitHub Release，不需要 GitHub 登录或
token。

- macOS、Windows 和 Linux AppImage 在下载并校验后可选择立即重启安装，或在
  下次退出时安装。
- `.deb` 会下载并打开系统的软件包安装器，不会绕过系统权限执行 `sudo`、`apt`
  或 `dpkg`。
- 更新器会使用系统代理设置；当配置的代理无法连接时，更新器会绕过代理直连
  重试一次，并在本次会话内保持直连。离线、代理认证、404、磁盘不足、校验失败、
  取消和重试都会在窗口中显示可恢复状态。校验失败时不会替换现有安装。
- 更新只替换应用程序，现有 DSH 数据、工作区设置、会话、已安装插件和 marketplace
  receipts 保留在原有数据目录中。

仅限签名的打包 Desktop 可自动更新。首次带更新器的 Release 之前安装的版本仍需
手动安装一次；本地开发构建和缺少当前平台安装包的 Release 会提供官方 Release
页面作为回退。

### DSH 运行时更新（与应用更新解耦）

同一个更新窗口还会列出 DSH 运行时版本。运行时更新以独立的
`oh-dsh-runtime-<dshVersion>-<platform>-<arch>.tar.gz` Release 资产发布，
因此新的 DSH 版本无需重装 Oh-DSH Desktop 即可应用。

- **Check Runtime** 查找为本平台发布的最新运行时包；**Update Runtime**
  下载后先校验发布的 SHA-256，暂存到 `~/.ohdsh/runtimes/<version>/`，
  并在激活前用 `dsh --version` 做冒烟检查。
- 激活会写入指针 `~/.ohdsh/runtimes/current.json` 并只重启 Harness 进程，
  应用本身保持运行。
- **Use Bundled Runtime** 删除指针并让 Harness 回到随应用内置的运行时。
  任何校验失败都不会改变当前生效的运行时。

## 安装 Web-only

```sh
tar -xzf oh-dsh-web-*.tar.gz
cd oh-dsh-web-*/
./bin/ohdsh web
```

Windows：

```bat
bin\ohdsh.cmd web
```

常用选项：

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `--host` | `127.0.0.1` | 监听地址 |
| `--port` | `3080` | 监听端口；`0` 使用随机端口 |
| `--data` | `~/.ohdsh` | 三端共享的 Oh-DSH 数据根目录 |
| `--no-open` | 关闭 | 不自动打开浏览器 |
| `--trusted-host` | 无 | 增加可信 authority，可重复 |

等价环境变量包括 `DSH_OH_WEB_HOST`、`DSH_OH_WEB_PORT`、
`DSH_OH_WEB_HOME` 和 `DSH_OH_WEB_OPEN`。`OH_DSH_HOME` 可以统一覆盖
Desktop、Web 和 TUI 的数据根目录。按 `Ctrl+C` 优雅退出。

不要在未配置访问边界时直接监听 `0.0.0.0`。对局域网开放时，应同时配置
`--trusted-host`，并由可信反向代理提供鉴权和 TLS。

## 安装 TUI-only

```sh
tar -xzf oh-dsh-tui-*.tar.gz
cd oh-dsh-tui-*/
./bin/ohdsh tui
```

Windows 使用 `bin\ohdsh.cmd tui`。TUI 需要真实交互终端；默认从当前终端位置
inline 启动，与 Codex 风格一致；需要 alternate screen 时显式传入
`--fullscreen`。

## 统一启动命令

```sh
ohdsh desktop
ohdsh gui
ohdsh web
ohdsh tui
```

- `desktop` 启动已安装应用；源码仓库中回退到 Electron 开发入口。
- `gui` 是 `desktop` 的启动别名。
- `web` 启动 HTTP 服务并打印访问地址。
- `tui` 初始化独立 Profile，并在当前终端中附着运行上游 renderer。

TUI 常用选项：

| 选项 | 默认值 | 说明 |
| --- | --- | --- |
| `--cwd` | 当前目录 | Workspace |
| `--data` | `~/.ohdsh` | 三端共享的 Oh-DSH 数据根目录 |
| `--resume` | 新会话 | 恢复指定 Session id |
| `--lang` | 上游设置 | `zh` 或 `en` |
| `--preset` | `standard` | 初始 Agent preset |
| `--inline` | 开启 | 保留终端 scrollback，不使用 alternate screen |

### Agent preset

Desktop、Web 和 TUI 使用同一份 Agent preset 名册。随发行版提供的
`liangshen`（梁神模式）会让主 Agent 与子 Agent 首轮都保持 Minimal 双工具，
首次工具调用后开放完整工具目录，压缩后重新锚定。Web/Desktop 在设置页的
Agent preset 中选择；TUI 可以在空白会话中输入：

```text
/preset liangshen
```

也可以在启动时指定 TUI preset：`ohdsh tui --preset liangshen`。已经产生对话的
会话遵循 blank-only 规则，选择会保存为下一次新会话的默认值。

## 图片输入

Desktop、Web 和 TUI 使用 DSH 原生的多模态输入。把 PNG、JPEG、WebP 或 GIF 复制后
粘贴到消息输入框（macOS 按 `⌘V`，Windows/Linux 按 `Ctrl+V`），或使用附件按钮：
缩略图、删除、拖放、大小限制和提交全部由 DSH 原生 attachment rail 负责。具备原生
图像理解能力的模型（如 DeepSeek V4 Flash）会直接消费这些附件，无需额外的视觉
桥接、附加模型或单独的 API Key。

原先为纯文本模型描述图片的内置 `@oh-dsh/vision` 桥接插件，已随原生多模态模型线
一并移除。它的 `oh-dsh-vision` 设置命名空间与 `ZHIPUAI_API_KEY`/`VISION_API_KEY`
凭据不再被读取。TUI 没有图形化缩略图，直接在消息中提供 Workspace 内的图片路径或
HTTP(S) URL，即可使用同样的原生图片输入。

## 上下文洞察

Desktop 和 Web 内置
[dsh-context](https://github.com/bowenliang123/dsh-context)（固定版本
`v0.41.0`）插件。它提供 Context 面板，展示上下文容量、余量、组成、历史、事件与
消息统计，并提供 `/context` 命令在会话内快速查看当前上下文组成。该插件只做只读
洞察：通过 DSH 自身驱动的 projection 观察会话，不会改动对话内容。

面板与 composer 原生的 context ring 并存，两者展示同一份容量事实。TUI 不内置该
插件——它围绕交互式面板构建，上游维护者也不面向 TUI 适配。

Oh-DSH 通过子模块固定版本，随自身发行节奏升级，不会自动跟随 npm latest。

## 订阅账号 OAuth 登录

Desktop 和 Web 内置上游 [dsh-auth](https://github.com/ccch1mneyyy/dsh-auth)
host 插件（固定在 dsh-TUI 子模块内；TUI 通过其 renderer 加载同一包）。它注册
订阅账号 LLM 路由——ChatGPT/Codex、Claude Pro/Max 与 SuperGrok——并提供
`/auth` 命令完成登录、查看状态与退出。交互式登录流程走各面已有的问答 UI；
在没有交互面的环境中，命令会给出指引并拒绝，而不是假定存在浏览器。凭据保存
在既有的 Oh-DSH 数据目录中。

## Desktop 操作

### 对话输入历史

焦点位于主对话输入框时，在第一行开头按 `ArrowUp` 可取回上一条已提交消息；在
最后一行末尾按 `ArrowDown` 可向后浏览，并最终恢复开始浏览前的草稿。多行输入中，
未处于这两个边界的方向键仍保持原有的光标移动行为。

历史按当前会话隔离，只包含已确认的用户文本消息，仅在本次应用运行期间保存在内存
中。输入框最多保留最近 100 条记录；在容量允许时，浏览到最早记录会按需加载更早的
会话消息。

| 操作 | macOS 快捷键 |
| --- | --- |
| 切换左侧栏 | `⌘B` |
| 切换底部 Terminal | `⌘J` |
| 切换右侧栏 | `⌥⌘B` |
| 打开 Review | `⌃⇧G` |
| 打开 Browser | `⌘T` |
| 打开 Files | `⌘P` |
| 新建 Side chat | `⌥⌘S` |
| 退出侧栏专注模式 | `Esc` |

设置页支持中英文、模型、权限、Agent preset、插件配置和 Oh-DSH 皮肤。
设置弹窗会覆盖并虚化所有工作区和侧栏内容。“关于”分区列出当前构建的版本
信息：Oh-DSH 本身、固定的上游 DeepSeek Harness 运行时、内置插件和关键依赖。
Desktop 端在同一分区即可完成整个更新流程——检查更新、带实时进度的下载和
安装，无需离开页面；检查时若无法访问 GitHub，更新器会通过发布镜像重试
一次。Web 端只展示版本信息，不显示更新卡片。

Web 与 Desktop 可在设置页选择皮肤。TUI 输入 `/theme` 可选择相同的 Deep
Current、Jade Circuit、Porcelain 和 Ember Dusk；选择立即生效并在重启后保留。
皮肤激活期间，外观设置只更新“原始外观”使用的回退值；如需退出皮肤，请在
皮肤列表中选择“原始外观”。

## 插件市场

Desktop、Web 与 TUI 共用同一个插件市场：三端都能检索插件、准备
candidate、隔离预览、应用、启用、更新和卸载。Desktop 与 Web 使用侧栏
市场界面；TUI 在聊天中输入 `/plugins` 打开终端市场（也可按 `Ctrl+M`）。

插件目录会标注每个插件的生效界面。安装本身在所需预览沙箱可用时才会成功；
如果插件声明只支持 Web / Desktop，在 TUI 中安装后不会在 TUI 生效，卡片和
详情会明确显示这一点。Linux x64 的构建脚本使用随运行时提供的 Landlock
启动器。如果没有写入受限的进程沙箱，用户可以单独、明确地接受不安全构建；
Agent 无法授权这种模式。

推荐流程：

1. 在未安装分类中选择插件。
2. 检查来源、commit、权限和风险等级。
3. 创建 candidate 并在隔离 Profile 中预览。
4. 效果不合适时选择放弃，当前桌面不发生变化。
5. 确认后应用；需要时再单独启用。
6. 更新失败时恢复 previous。

Agent 可以通过对话发起同样的安装操作，但仍需要经过预览、风险确认和应用，
不会直接修改当前 Profile。

## 从源码启动与打包

```sh
git submodule update --init --recursive
pnpm install
pnpm run build:dsh
pnpm run build
pnpm run stage:dsh
export PATH="$PWD/bin:$PATH"

ohdsh desktop
ohdsh web --port 3080
ohdsh tui
```

开发阶段也可以使用仓库根目录的 Makefile；它只会为当前界面暂存所需的包，
因此比完整 staging 更快：

```sh
make build
make tui ARGS="--inline --lang en"
make web ARGS="--port 3080"
make desktop
```

`make tui` 和 `make web` 不会暂存 Desktop 或其它交互形态的包；Oh-DSH 也会禁用
上游 TUI 的后台自动更新检查，pinned runtime 由 Oh-DSH 发布流程统一更新；面向
完整共享 runtime 的发布流程仍使用 `pnpm run stage:dsh`。Make 默认使用
`~/.ohdsh`，也可以通过 `OH_DSH_HOME` 覆盖以运行隔离实例。

打包命令：

```sh
pnpm run dist:mac       # macOS full distribution
pnpm run dist:linux     # Linux full distribution
pnpm run dist:win       # Windows full distribution
pnpm run dist:web       # Web-only lightweight distribution
pnpm run dist:tui       # TUI-only terminal distribution
```

发布工作流在 GitHub Actions 的 macOS 签名/公证凭据和 Windows Authenticode
凭据齐全时生成正式签名包。缺少任一组凭据时，工作流会明确警告并降级生成 macOS
ad-hoc 签名包或 Windows 未签名安装器，而不会阻止 Web、TUI 和 Desktop 打包。
降级产物仅支持上文所述的手动安装，不能视为支持自动更新。启用正式签名需要配置
`MACOS_CSC_LINK`、`MACOS_CSC_KEY_PASSWORD`、`APPLE_ID`、
`APPLE_APP_SPECIFIC_PASSWORD`、`APPLE_TEAM_ID`、`WINDOWS_CSC_LINK` 和
`WINDOWS_CSC_KEY_PASSWORD`。安装包、内嵌或外置 blockmap、`latest*.yml` 元数据
仍会被严格校验，缺失时停止发布。可从 Actions 手动运行 Release workflow 做四平台
打包检查；手动运行只上传 workflow artifacts，不创建 GitHub Release。

## 数据与排错

Desktop、Web 和 TUI 默认共同使用 `~/.ohdsh`，且不会加载 `~/.dsh` 中的
全局插件配置。三端分别使用 `profiles/desktop`、`profiles/web` 和
`profiles/tui`，但共享会话、凭据、皮肤和插件缓存；Electron 自身的数据
位于 `~/.ohdsh/desktop`。可用 `OH_DSH_HOME` 全局覆盖，也可用 Web/TUI 的
`--data` 临时隔离。DeepSeek API key 可以在 Models 设置中配置，或写入
`~/.ohdsh/.env`。

首次使用共享目录时，Desktop 会从系统应用数据目录中的旧
`Oh-DSH-Desktop` 状态导入会话、凭据、插件与界面设置；Web 会导入旧
`~/.oh-dsh-web/dsh`、根级皮肤与侧栏偏好，以及当前数据目录下的 `dsh/`。
迁移只复制共享目录中缺失的数据，并保留旧目录用于回滚；已存在的新状态
不会被覆盖。

同一时间只有一个 Oh-DSH 前端持有共享数据根的写入权。其他前端可以以
只读模式启动并查看历史，但不能在持有者运行期间写入活跃会话。

排查顺序：

1. 运行 `ohdsh --help` 确认 CLI 来源。
2. 运行 `ohdsh web --help` 检查参数。
3. 运行 `ohdsh tui --help`，再用 `ohdsh tui --inline` 排除终端全屏兼容问题。
4. 使用随机端口验证：`ohdsh web --port 0 --no-open`。
5. 检查 Profile 是否同时安装并启用了所需插件。
6. Desktop 启动失败时，从终端运行应用内 `bin/ohdsh desktop` 获取日志。

架构与上游关系见[设计与插件边界](./design.md)。