简体中文 · English · 返回 README

# 安装、操作与排错 ## 选择发行形态 - 需要完整本地工作台：安装 **Oh-DSH Desktop**。 - 只需要浏览器交互：安装 **Oh-DSH Web**，不携带 Electron。 - 纯终端交互：安装 **Oh-DSH TUI**，不携带 Electron 或浏览器 UI。完整版已经包含三种形态，因此安装一次后可以使用 `desktop`、`web` 和 `tui`。 ## 安装完整版 ### 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`。 ## 安装 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` | `~/.oh-dsh-web` | Web 可写数据根目录 | | `--no-open` | 关闭 | 不自动打开浏览器 | | `--trusted-host` | 无 | 增加可信 authority，可重复 | 等价环境变量包括 `DSH_OH_WEB_HOST`、`DSH_OH_WEB_PORT`、 `DSH_OH_WEB_HOME` 和 `DSH_OH_WEB_OPEN`。按 `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 需要真实交互终端；默认使用 alternate screen，全屏选择、滚动和复制由上游 `dsh-TUI` 处理。 ## 统一启动命令 ```sh ohdsh desktop ohdsh web ohdsh tui ``` - `desktop` 启动已安装应用；源码仓库中回退到 Electron 开发入口。 - `web` 启动 HTTP 服务并打印访问地址。 - `tui` 初始化独立 Profile，并在当前终端中附着运行上游 renderer。 TUI 常用选项： | 选项 | 默认值 | 说明 | | --- | --- | --- | | `--cwd` | 当前目录 | Workspace | | `--data` | `~/.ohdsh` | Oh-DSH TUI Profile、会话和配置目录 | | `--resume` | 新会话 | 恢复指定 Session id | | `--lang` | 上游设置 | `zh` 或 `en` | | `--preset` | `standard` | 初始 Agent preset | | `--inline` | 关闭 | 保留终端 scrollback，不使用 alternate screen | ## Desktop 操作 | 操作 | macOS 快捷键 | | --- | --- | | 切换左侧栏 | `⌘B` | | 切换底部 Terminal | `⌘J` | | 切换右侧栏 | `⌥⌘B` | | 打开 Review | `⌃⇧G` | | 打开 Browser | `⌘T` | | 打开 Files | `⌘P` | | 新建 Side chat | `⌥⌘S` | | 退出侧栏专注模式 | `Esc` | 设置页支持中英文、模型、权限、Agent preset、插件配置和 Oh-DSH 皮肤。设置弹窗会覆盖并虚化所有工作区和侧栏内容。 Web 与 Desktop 可在设置页选择皮肤。TUI 输入 `/theme` 可选择相同的 Deep Current、Jade Circuit、Porcelain 和 Ember Dusk；选择立即生效并在重启后保留。 ## 插件市场推荐流程： 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 ``` 打包命令： ```sh pnpm run dist:mac # macOS 完整版 pnpm run dist:linux # Linux 完整版 pnpm run dist:win # Windows 完整版 pnpm run dist:web # Web-only 轻量版 pnpm run dist:tui # TUI-only 终端版 ``` ## 数据与排错 Desktop 保留既有内部数据目录，以保证更名升级兼容。Web 默认数据目录是 `~/.oh-dsh-web`，TUI 使用独立的 `~/.ohdsh`，不会加载 `~/.dsh` 中的全局插件配置。DeepSeek API key 可以在 Models 设置中配置，也可以放入对应 DSH 数据目录的 `.env`。排查顺序： 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)。