Oh My DSH.文档GitHub ↗
文档导航

DOCUMENTATION OMD 0.2.1-alpha.1.omd.0.5.2

本页目录

安装与使用排障#

文档目录 · 首次使用 · 安装与升级 · 反馈 Bug

先找到具体症状，再沿对应步骤处理。保留第一次失败的完整错误；重复安装或删除数据通常会让定位更困难。

先确认是否装到了正在使用的环境#

  1. 核对来源和版本。 本项目的仓库是 gulagala001/oh-my-dsh，插件包名为 trisoul_x。宿主版本与插件版本分别查看；左上角「关于 Oh My DSH」中的“当前版本”才代表正在运行的插件，“最新版本”只是发布信息。
  2. 核对运行方式。 桌面版在应用内安装，属于 desktop profile；Web 安装到启动命令使用的 profile。两者不会自动共享插件安装状态。
  3. 核对数据位置。 沿用实际 DSH_HOME。Web 默认是用户目录的 .dsh；本仓库源码 pnpm start 默认是仓库下的 data/dsh/，profile 为 trisoul-x，端口为 3083。
  4. 完整重启后做一次操作。 等任务结束，桌面完整退出再打开，Web 按原方式重启服务。新建会话选择 Oh My DSH，使用已配置模型发一条消息；升级用户再检查一个旧会话与原主题。没有模型凭据时，只能确认安装和界面，不能认为对话已验证。

安装来源怎么核对#

复制首页安装命令中的完整 GitHub 来源，或使用本仓库 Release 的发行包。安装页面的展示名称不等于包名；本仓库 package.json 的 name 为 trisoul_x，repository.url 指向 gulagala001/oh-my-dsh。

如果安装日志中的包名、仓库或宿主版本与上述配对不符，先记录实际来源与版本，核对后再继续，避免对错误的安装目标反复更新。

按症状处理#

现象 检查与恢复
找不到 pnpm，或 Node 版本不满足要求 Web／源码按运行要求准备 Node 和 pnpm；桌面使用内置运行时，在应用内安装插件。不要用全局 Node 升级替换桌面内置宿主。
安装报“不兼容 DSH” 记录宿主实际版本与目标插件版本，按版本配对更新。不要单独把一个组件改成 latest 或绕过宿主兼容检查。
需要批准安装脚本 在 DSH「插件」页面查看具体包与原因，按宿主提供的入口处理。批准后重新检查安装结果；提示消失不等于组件已经可用。
离线检查提示缺少 node_modules 或清单损坏 普通源码压缩包没有离线依赖。在同系统、同架构的有网机按离线准备步骤生成完整目录，再整体压缩、复制和解压；不要只复制插件源码或手工修改清单。
已装好，但看不到 OMD 入口 检查是否安装到当前 profile、是否启用，并完整重启。新建会话选择 Oh My DSH；已有会话保留原 preset。
已更新，但“当前版本”仍旧 安装到磁盘和运行中的版本可能不同。桌面完整退出应用后重开，Web 重启原服务；仅刷新页面不能替换后端。
桌面提示服务已更新、界面版本不同 等任务结束，使用「重启应用与 Host」或完整退出后重开。桌面缓存启动模块信息，不以反复刷新页面替代重启。
找不到原会话或模型配置 先核对 DSH_HOME 与 profile，参照Web 转桌面迁移。不要在空白环境重新录入配置来掩盖目录不一致。
旧会话显示“历史加载失败” 按旧会话恢复说明保留原日志，核对修复版本及迁移诊断。不要删除记录或手动改事件序号。
全局背景提示被其他窗口更新 点击“读取最新版本”比较内容，再选择保留草稿继续合并或使用最新内容；读取不会覆盖草稿，合并后需再次保存。旧版没有此入口时，先复制草稿再重新打开设置。设置说明。
保存自定义路径时继续输入，结果被还原 更新至本版后，保存响应会保留后续输入；仍需再次保存这些新修改。旧版请等待本次保存结束后再编辑。本版说明。
推荐插件操作报错 保留具体错误，在宿主「插件」页核对当前状态。安装脚本、兼容性和网络错误应分别处理；重试前确认是否已经安装，避免覆盖另一处刚完成的操作。
电脑操作的某个组件报错 在「设置 → Oh My DSH → 基础组件」查看对应组件的错误并按需准备；其他组件正常不代表该组件正常，单项失败也不代表整个插件不可用。平台要求。

需求理解插件安装报 ERR_PNPM_MISSING_TARBALL_INTEGRITY#

这表示包管理器缺少远程压缩包的完整性记录。OMD 0.1.7-rc.2.16 已将该插件改为先按固定 SHA-256 校验发行包，再通过原生插件管理器安装本地包；安装包保留在 OMD 数据目录的 recommended-packages/，供后续重装使用，备份数据时一并保留。

仍使用旧版时，可从插件 Release下载 omd-prompt-optimizer-0.1.0.tgz，对照同页的校验文件核对后，放在固定目录，通过当前 profile 的原生插件管理器安装本地包。不要关闭完整性校验或删除整个 profile。若错误指向其他已安装依赖，需单独核对该依赖的锁文件与来源。

该插件原作者为啃轮胎的西狐（WestFox-AwA），gulagala001 负责 OMD 适配；保留 BSD-3-Clause 许可与署名，非上游官方发行版。

无法启动、白屏或大量 waiting for service#

“等待服务”通常是后续症状。优先找第一个 failed to import 或启动异常，保留异常类型、cause、包路径和堆栈，而不仅是弹窗最后几行。

  • 桌面版： 查看错误弹窗给出的 Diagnostic report 路径并保留该次日志。若提供“禁用第三方插件、备份 profile patch 后重启”，可用它隔离启用配置；它不会重建依赖目录，未恢复时不要重复点击来代替诊断。
  • Web 版： 保留实际启动终端的第一处错误。若能打开插件管理器，先停用发生问题的插件，再按原方式重启并测试原生会话。
  • 源码版： 核对使用的是预期 checkout，依赖已安装且执行过 pnpm build。本版 pnpm start 会把旧源码目录的 link: 更新为当前目录；已有发行包来源保持不变。旧版换目录继续使用原数据时，先停服，再通过宿主插件命令链接到实际源码目录。

停用后恢复只能说明与该插件或其组合有关，仍需完整错误定位。若宿主在加载插件前就失败，OMD 界面中的修复入口也无法执行。不要直接删除整个 .dsh，也不要把其他机器的 node_modules 覆盖进去；涉及重建时，先按备份步骤保留实际数据及原配置。

离线搬运与本地安装#

Release 的 .tgz 是插件发行包，不包含全部依赖和运行环境。离线搬运不能跨系统、跨架构使用；例如 Windows x64 应在另一台 Windows x64 电脑上准备。

pnpm install 生成的依赖包含链接结构、平台包和可能需要执行安装脚本的组件。压缩工具遗漏隐藏目录、未保留链接，或准备机与目标机系统／架构不同，都可能造成导入失败。宿主本地安装也可能仍需下载依赖。

不要直接压缩默认 pnpm install 后的目录。Windows 依赖目录可能包含仍指向准备机绝对路径的 junction，换盘符后即使 .pnpm 和包目录都在，也可能无法导入。

准备可搬运的离线目录#

本版包含 scripts/prepare-offline.mjs 和 scripts/check-offline.mjs。在可联网、与目标机器平台和架构相同的电脑上下载本版源码，准备目录后再搬运。

在与目标机同系统、同架构的有网机上，准备上述开发源码、Node.js ≥22.19（建议 Node.js 24）与 pnpm 11.23.0。在源码根目录运行，输出目录必须是源码目录外尚不存在的新目录：

powershell
pnpm install --frozen-lockfile
if ($LASTEXITCODE -ne 0) { throw '安装依赖失败' }
node scripts/prepare-offline.mjs 'C:\omd-offline'
if ($LASTEXITCODE -ne 0) { throw '离线准备失败' }

macOS／Linux 同样运行 node scripts/prepare-offline.mjs /绝对路径/omd-offline。脚本只取实际发行文件，在隔离目录重新安装无符号链接的依赖布局、构建并检查 OMD 入口、Sharp 和 CodeGraph 平台包；不会搬运准备机的配置、凭据和会话，也不会改动原安装。检查失败时不产出完成目录。

  1. 完整压缩输出目录（包含 node_modules），搬到离线机并解压到固定位置，例如 D:\omd-offline。不要把目录中的文件拆散，也不要覆盖 DSH 自己的 node_modules。
  2. Windows 离线机在解压目录运行 check-offline.cmd（PowerShell 中为 .\check-offline.cmd），使用随包运行时，无需另外安装 Node。其他系统有 Node.js ≥22.19 时运行 node scripts/check-offline.mjs。检查会报告失效链接、平台不匹配和完整导入异常；不需要在离线机重新安装依赖或构建。
  3. 桌面版在应用内「插件 → 安装 → 本地」填写 link:D:\omd-offline（按实际绝对路径替换），链接整个目录，不安装 .tgz 或 file: 包。目录需要保留；日后移动目录后应重新安装到新位置。沿用原 desktop profile，不使用 CLI 修改桌面 profile。
  4. 确认 DSH 宿主与离线目录 offline-manifest.json 中的 hostVersion 配对，完整退出 DSH 后重开，验证新会话和工具调用。Web 用户沿用实际 DSH_HOME 与原 profile，通过宿主 CLI 添加 link:/解压目录绝对路径，必要时使用 --offline。

离线目录准备和入口检查不等于所有功能完成验收。模型服务仍须可达；浏览器、Python、.NET 与桌面控制等按需组件需另外准备。自动回归覆盖目录搬运、禁止依赖下载时的原生安装、任务工具执行和重启恢复；具体目标电脑，尤其 Windows 10 的桌面应用，仍需按上面步骤实测。

仍失败时，保留离线检查输出、准备机和目标机的系统／架构、DSH 与 OMD 版本，以及 Host／诊断日志中第一处导入异常。不能只凭包目录存在判断依赖完整，也不要删除 .dsh、配置或会话。

反馈问题时提供什么#

使用 Bug 模板，一次提供以下信息：

  • 系统与架构、桌面／Web／源码、DSH 版本和 OMD 当前版本。
  • 安装来源、profile 名称；数据目录是否自定义即可，不必公开用户名或私人路径。
  • 最短复现步骤、预期结果与实际结果；从哪个版本开始、是否每次发生。
  • 第一处完整错误及相关日志片段，必要时附截图；已经试过的恢复方法及结果。

对外提交前遮盖 API Key、登录 token、凭据和私人会话内容。不要上传整个数据目录或 .credentials.yaml。无法取得的信息写“未知”，不要猜测。