# 安装与使用

dsh-houdini 是官方 DeepSeek Harness Desktop 的插件。当前 **0.1.6** 发行包面向 **Windows x64**，支持 **DSH 0.2.1-rc.3 / 0.2.1-rc.5**，首选 rc.5。精确范围与验证边界由[兼容清单](../dsh-runtime-compatibility.json)维护。Houdini 侧支持 21.0 和 22.0，实测构建为 21.0.440 和 22.0.368。产品使用同一份 DSH 原生会话，不另启动 Qt 聊天窗口或私有 DSH Host。

## 普通安装

标准发行单元是包含Houdini和媒体资源的完整插件包，[npm](https://www.npmjs.com/package/dsh-houdini)与[GitHub Release](https://github.com/eee1723/dsh-houdini/releases)分发同一个`.tgz`。在Desktop原生「插件 → 添加插件」中填写下方包名和版本即可安装，普通用户无需npm账号或另装Node：

```text
dsh-houdini@0.1.6
```

如果提示“未找到相关插件”，先检查对话框右侧的“安装源”。新发布版本可能尚未同步到“中国大陆镜像源”，可切换为npm官方源后重新查询；自定义官方源地址为`https://registry.npmjs.org/`。也可使用下方GitHub完整包地址，它不依赖镜像中的包版本记录。镜像查询失败不代表官方源没有发布该版本。

仅填写`dsh-houdini`会安装npm当前latest版本。需要使用GitHub来源时，也可在同一输入框粘贴完整地址：

```text
https://github.com/eee1723/dsh-houdini/releases/download/v0.1.6/dsh-houdini-0.1.6.tgz
```

GitHub发布页同时提供SHA256校验文件。仓库首页、历史独立工作台包和GitHub自动生成的Source code ZIP不适用于这条标准插件安装路径；源码push、tag或Draft本身不等于包已公开可用。

1. 安装受支持的官方 DSH Desktop，并确认其 DSH 宿主版本符合上方精确兼容范围。
2. 打开Desktop原生「插件 → 添加插件」，在「包名或地址」填写上述包名或完整地址并点击「安装」。也可下载完整`.tgz`并填入其本地绝对路径，无须解压后寻找`Install.cmd`。
3. 安装完成后启用插件。当前宿主的新装插件默认停用，可在安装结果中选择「立即启用」，或在插件列表启用 `dsh-houdini`；安装成功本身不表示 Houdini 模式已经加载。
4. 在 DSH 原生模型设置中完成供应商或账户配置，为当前对话选择可用主模型。插件复用这些设置。
5. 新建或选择 Houdini 模式的对话，在工程菜单选择 Houdini 安装，新建场景或打开已有 HIP；已经加载兼容组件的工程也可直接选择绑定。

插件在真正新开 Houdini 前自动准备本端组件，包括登记菜单所需的 Package、检查已确认的旧入口并取得安装回执；准备失败会显示实际原因，不继续新开一个未准备好的窗口。日后普通启动的 Houdini 也通过该 Package 加载菜单。需要单独准备或修复组件时，可使用 Houdini 模式工程菜单的「安装 / 更新 Houdini 组件」。

普通安装反馈只说明安装或更新结果，以及已打开的Houdini是否需要保存并重开；入口迁移、备份和保留项继续写入安装详情，不作为日常使用提示。真正阻止安装的冲突或失败仍显示实际原因。组件已安装不代表当前窗口已加载或工程已连接。

地址安装由官方宿主的插件管理器下载和验证。完整包包含媒体工具及对应源码，下载时需要等待；网络受限时可下载同一版本的完整包后本地安装。失败时保留实际错误，不使用历史独立工作台入口补装。已验证范围和剩余环境差异见[发行交接](handoff.md#h-01-标准插件发布与用户加载)。

已经打开且没有加载组件、或仍加载旧版组件的 Houdini，须先保存，再重新打开对应窗口；磁盘安装不能替换进程内已经加载的 Python 模块。组件准备不关闭其他 Houdini，不重启 Desktop。发现进程或 HIP 路径不证明该窗口已经连接。Desktop 未安装、版本不兼容或插件未启用时，菜单显示实际接入原因。

## 从旧版升级与菜单接入排查

升级按「官方 Desktop 安装并启用完整插件包 → Houdini 模式安装 / 更新组件 → 保存并重开对应 Houdini → Open Workspace」的顺序进行，不先清空旧目录。已在 Desktop 安装标准插件时，等待当前任务结束，在原生插件页卸载旧插件，再添加发布页提供的新版完整包地址（或本地包）并启用，按宿主提示重新打开 Desktop。这里不需要先移除 Houdini 连接组件或删除历史；不以检查同版本号或旧独立工作台的更新按钮代替安装。

菜单提示「DSH Desktop 接入结果尚未确认」时，表示在等待时间内未能确认插件通道的结果，不证明场景操作已经失败或需要重发。先打开官方 Desktop，在「插件 → 添加插件」用完整包的本地绝对路径安装，并在安装结果选择「立即启用」；已有条目则核对其来源及启用状态。随后确认新对话能选择 Houdini 模式，再准备本端组件并重开 Houdini。Houdini 菜单已经出现，只说明该窗口加载过菜单代码，不能代替 Desktop 插件已启用的检查。

早期开发可能只在 `web` profile 登记源码链接；官方 Desktop 的 `desktop` profile 是另一份插件安装配置。旧网页入口可用、源码构建成功或执行 `Install.cmd`，均不表示官方 Desktop 已安装插件。沿其原生管理入口安装，不复制 profile、改会话、搬密钥或手工给官方配置打补丁。两端准备完成后仍无法接入时，保留实际错误及其发生入口，再核对正在使用的 Desktop、插件启用情况和该 Houdini 的已加载版本，避免反复重发场景操作。

选择文件夹时若报 `workspace/create` 的 `active Service "workspaceController" is unavailable`，表示官方工作区服务尚未上线，路径访问检查还没有开始。应检查服务初始化原因，而不是反复换目录或提升管理员权限。旧私有 Host 曾允许会话头的创建目录与日志实际位置不一致；官方持久化读取会拒绝此类记录，进而阻断工作区服务。存量历史恢复须与插件安装分开：先明确异常记录、原始来源和对历史可见性的影响，再在 Desktop 正常退出后执行经用户确认、保留原值且可回滚的处理。安装器不自动改写会话头或搬动日志，不能通过清空历史或重新加入核心补丁来掩盖不一致。

## 旧版入口迁移与数据保留

首次新开 Houdini 或显式更新组件时，安装器检查目标目录中的旧入口。仅对能确认来自历史 dsh-houdini 安装器的 Package、启动桩、菜单和独立工作台快捷方式执行停用，保留原始字节备份和可恢复报告；复制、改名后的纯插件 Package 也在检查范围内。自定义 Shelf、混有其他代码的启动脚本和无法确认的快捷方式保持原样，安装详情提示需要核对的内容。同名 Package 若无法确认归属，准备会停止并给出具体报告，不要求用户盲删目录。

旧运行包、缓存、密钥、会话、附件和 HIP 都保留。入口迁移不合并两套历史，不改写会话头或搬动日志；已有旧记录的处置范围见[宿主与历史交接](handoff.md#h-06-官方dsh共存与插件边界)。不要通过清空旧 runtime、账户目录或历史来解决入口冲突。运行中的旧 Houdini 仍须保存后重开。

安装器只部署自身 helper 和 Package。helper 默认位于 `%LOCALAPPDATA%/DSH-Houdini`，不安装 DSH/Node，不修改官方 Desktop 安装、其他插件、profile、会话或账户。目标优先采用显式 `-PackagesDir` 和已有登记；没有已登记目标时，依次使用 `HOUDINI_PACKAGE_DIR`、`HOUDINI_USER_PREF_DIR` 或系统 Documents 中的 Houdini 21.0/22.0 偏好目录。`HOUDINI_PACKAGE_DIR` 可用分号列出多个绝对目录；已有自定义登记在升级时继续保留。

支持人员可在完整插件资源目录使用[安装器](../installer/install.ps1)的高级预览与恢复入口。预览不写文件；恢复只处理报告记载的入口，校验备份和安装后文件摘要，遇到用户后改的文件就停止并保留它：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File installer/install.ps1 -MigrationPreview
powershell -NoProfile -ExecutionPolicy Bypass -File installer/install.ps1 -RollbackMigration '报告绝对路径' -MigrationPreview
powershell -NoProfile -ExecutionPolicy Bypass -File installer/install.ps1 -RollbackMigration '报告绝对路径'
```

自定义组件根可追加 `-Root`。恢复迁移会重新启用报告中的原入口，应按明确的恢复目的使用；组件版本选择和已加载状态仍以本端版本信息及重开后的实际连接为准。

## 工作区使用

从 Desktop 选择 Houdini 模式，在对话目标控件中选择已登记工程；也可选已发现的 Houdini 安装，新建或打开现有 HIP。打开其他文件默认使用新进程，不隐式清空已有工程。启动成功、HIP 加载完成、Bridge 连接和任务绑定分别以实际回执确认。

在 Houdini 选择 DSH-Houdini → Open Workspace，菜单取得当前工程身份，启动/确认本端 Bridge，再唤起同一 Desktop 并定位或创建 Houdini 对话。已有明确目标优先；发生歧义才选择。GUI 主线程不等待网络或进程探测。

未保存场景使用插件专属临时工作目录，不自动保存 HIP。已有对话切换目标保留其原生工作区与历史；Save As 只更新真实 HIP 事实，原项目内的文件目录可由原生 cd 跟随，跨项目文件权限仍沿 DSH 公开机制处理。工程输出锚定实际 $HIP 与明确目的地，不修改会话创建目录来扩大权限。

只有当前选中的 Houdini 对话显示领域交互控件。其他模式没有工程面板；历史执行卡片仍可读取，已经提交的后台执行不因切换界面而取消。多工程、节点修改权限与恢复合同见[工程选择](multi-instance.md)。

在官方Windows Desktop的Houdini模式中可点击「置顶」，便于一边对话一边操作Houdini；空对话显示在输入工具行，已有对话显示在页头。Houdini对话之间切换保留本次使用中的选择，切回其他模式恢复进入前的窗口层级。若无法准确识别本Desktop窗口，按钮会说明原因，不按窗口标题或当前前台窗口猜测。

## Connection & Support（连接与维护）

Houdini 工程菜单提供「插件更新…」。仅在有适合当前 DSH 的正式更新时显示提醒，可选更新可忽略；普通使用不弹窗。详情说明更新内容和下一步，版本信息与查询错误折叠显示。查询失败保留上次已确认结果并标明时间，不把断网写成不兼容。当前通过发布页查看更新方法，安装仍使用 Desktop 原生插件管理；不会自动关闭任务或重启应用。已有 0.1.1～0.1.3 不包含这条检查，需要先按下方方法完成首次更新。

Houdini 组件提示按当前窗口实际加载与安装情况显示：「请先安装 Houdini 组件」说明尚未确认新组件就绪；「保存后重开此 Houdini」只在同一安装位置的新组件已经准备好时出现。连接正常但有组件更新时可以继续当前工作。不同安装位置、无法确认的旧组件和连接中断不承诺重开即可解决。

Desktop 的应用和账户更新由官方管理；Node 侧插件沿官方插件管理更新。当前验证的 Desktop 0.2.1-rc.3 插件页对第三方插件要求先卸载再安装新版；npm 包名与 GitHub Release 安装链接都遵守这个界面合同，发布到 npm 本身不会增加一键更新。更新插件不需要执行下述「移除本机组件」。

也可先正常退出Desktop，再用它自带的官方CLI直接安装新版，无须先卸载：`<Desktop安装目录>/resources/runtime/cli/bin/dsh.cmd plugin --profile desktop add dsh-houdini@0.1.6`。原来通过GitHub地址安装的用户可通过这一命令迁移为npm包名来源；同一入口仍接受完整tgz路径和正式地址。它经原生管理器替换依赖并继续使用原profile，不自行编辑配置或依赖目录。已在独立Desktop profile核对0.1.1 → 0.1.2的覆盖安装及既有对话/配置保持；其他用户组合仍按实际环境确认。完成后重新打开Desktop；Houdini按实际组件提示保存并重开。包名分发不等于运行中的热更新。

Houdini 中手动选择 **DSH-Houdini → Connection & Support...** 才会打开「连接与维护」窗口，正常启动和打开工作区不弹出它。窗口默认提供打开 Desktop 工作区、重新连接和连接诊断；「更多维护选项」中才显示切换已安装组件版本、移除本机组件与当前加载位置。重复打开会复用同一窗口，不阻塞 Houdini 编辑。版本信息与维护只作用于本端 Bridge/helper，不下载 Desktop 插件更新。已加载版本以当次 Bridge 执行合同为准，不能只查看磁盘文件或包版本。

修复当前 Bridge 必须等待其执行队列空闲，不终止其他 Houdini、不重启 Desktop、不重放未确认代码。Package/菜单变更按提示重开对应 Houdini；本端更新不改变原 HIP 和节点内容。

Desktop无法连接时，可在此窗口选择「连接诊断…」，生成并查看本端接入报告，或打开已有诊断ZIP；保存位置由用户选择。完整会话报告仍在Desktop标题栏的「报告问题」中导出。两种报告的数据范围和分享方式见[故障报告](support-reports.md)。

## 教程视频与转录设置

普通用户只需先在DSH配好主聊天模型。第一次分析有讲解的教程时，在任意模式的「设置 → 教程视频」选择地址来源、实际接口协议和准确转录模型，确认并发与速率后直接保存，无须先发起一次模型对话。在 Houdini 对话中让 Agent 协助分析时，也可通过 `video_configure` 保存同一份设置；确定性配置不依赖 LLM。ASR与STT是同一语音转文字能力，不需要配两套，TTS也不是解析教程的前置要求。

已有DSH提供方可明确复用其API地址和凭据引用；独立官方、中转或本机服务则保存为教程用途端点，不需要添加一个假聊天模型。协议按实际文件接口选择，不按厂商或模型名称猜测。支持OpenAI兼容文件转录、千问音频Chat与DashScope同步音频；实时流与异步云任务需要专用适配器，不能仅换URL或模型ID。已有本机兼容服务可使用无密钥模式；本机地址不证明它的后端绝不联网。

密钥只在状态页的「安全录入或更换密钥」输入，通过DSH原生凭据接口保存；不要发进聊天、提问答案或脚本。Agent只看到是否已配置。新网络origin不会自动继承旧服务的key；聊天OAuth或订阅也不等于语音API授权。页面展示当前配置与缺项，实际识别能力以获授权的一个短片试转录为准。默认并发2、每秒1次，本机可先1；试段明确只提交1片，这些限制不能替代总费用/上传范围授权。

FFmpeg/ffprobe随完整插件包交付，普通用户不用安装到PATH。普通Python自动来自已选安装的静态信息或发现的Houdini安装；只解析教程不必先连接场景。缺少图片能力时由Agent引导使用DSH原生模型选择，不能把转录文本冒充完整画面分析。若用户需要部署本地推理模型，应在明确硬件和资源下载后使用独立环境，不把CUDA/推理依赖安装进Houdini Python，也不默启宿主的可选听写bundle。

正式插件媒体资源位于 runtime/video，包含FFmpeg/ffprobe、所需运行库、许可及媒体库对应源码；各版随包SOURCE-NOTICE说明附带归档和精确来源引用。构建使用现有受控媒体构建/暂存入口，不从用户系统 PATH 猜测另一套默认工具。源码开发可以显式指定经过验证的 FFmpeg/ffprobe；缺失资源时返回实际依赖原因，不宣称离线功能已就绪。方法与验证见[开发规范](development.md)及[媒体契约](../skills/houdini-video-tutorial/references/video-processing.md)。

## ChatGPT / Codex 订阅（可选）

当前选择社区插件 [dsh-codex-subscription](https://github.com/WSL043/dsh-codex-subscription)，固定版本 **3.1.8**。它由独立作者维护，不随Houdini发行包捆绑，可用于Houdini和其他模式；Houdini连接组件不管理其账户，也不读取或迁移其他订阅插件的授权。

在官方Desktop原生插件管理中添加 **dsh-codex-subscription@3.1.8**，按页面提示安装、启用或重开。随后打开「设置 → Codex 订阅」，由用户亲自完成ChatGPT授权，再从DSH原生模型菜单选择账户实际可用的模型。插件安装、账户连接和模型目录可见分别不代表一次真实推理已经成功；型号、额度和功能以账户及服务端返回为准。

该插件的联网搜索、生图、其他模型扩展和可选工具由它自己的设置控制；只开启实际需要的能力，不把生成图片当作真实Houdini工程验收。订阅OAuth不等于转录API授权。宿主兼容检查和安装由官方插件管理负责，不为它设置版本豁免、修改共享依赖或升级Desktop。未完成的实际账户验收见[交接](handoff.md#h-06-官方dsh共存与插件边界)。

## 网络与代理

当前官方Windows Desktop的Node Host依据启动时的显式代理环境工作；它没有继承Windows系统代理、PAC或WPAD的完整合同。浏览器或Desktop更新器能够联网，不证明模型请求、转录子进程也能使用同一代理。使用代理时，按官方DSH方式在启动前配置HTTP_PROXY/HTTPS_PROXY/NO_PROXY并正常重开Desktop；具体值由所用代理服务提供。PAC地址不能直接充当HTTPS_PROXY。

插件不会读取系统代理后暗中修改整个Host、其他模式或用户环境。系统代理自动接入作为宿主公共网络能力处理，限制与上游方案见[DSH适配](dsh-update-compatibility.md#网络与窗口等宿主能力)。

## 指定图片模型

Houdini 模式通过 image_models 发现当前可用路由，再以 image_generate 使用实际模型和参考文件。使用 DSH 原生凭据与附件；生成图片及其目的地不证明语义判断已经完成。输出角色与文件边界见[工程文件](project-files.md)。

## 显式源码开发安装

```powershell
npm install
npm run build
npm run runtime:prepare
npm run docs:check
```

官方宿主准备器仅用于隔离开发验证。开发/测试必须显式使用临时 DSH_HOME、profile、依赖缓存和浏览器数据；不要把未验证的 checkout 安装进用户正在使用的 Desktop。源码 Houdini Package 可用 python houdini/install.py --print 预览或安装；该命令不改 DSH profile。

具体职责、替代方案比较和宿主共存纪律见[开发维护](development.md#插件职责与方案选择)。受支持版本与公开接口见[DSH 适配](dsh-update-compatibility.md)，未完成验收只维护于[交接](handoff.md)。

## 卸载与保留数据

需要完整卸载时，先在已安装 helper 的 Houdini 中打开 **DSH-Houdini → Connection & Support... → 更多维护选项**，选择「移除本机组件…」并确认，再到 Desktop 原生插件管理停用或卸载 `dsh-houdini`。本机组件解除登记后，当前窗口与 Bridge 继续运行，下次启动不再加载菜单；若继续从仍启用插件的 Desktop 新开 Houdini，组件会按正常流程重新准备。无需寻找卸载脚本或清空目录。

高级维护可使用完整插件或已安装 helper 中的 [installer/uninstall.ps1](../installer/uninstall.ps1)，提供只读预览和按报告恢复。卸载不结束正在运行的 Houdini，不删除 HIP、会话、附件、恢复材料或 helper 版本目录，不修改官方 Desktop 安装。保留的旧私有入口不会因卸载新插件而自动重新启用。

## 正式发行与受管安装合同

发布构建器打包标准插件及 Houdini/媒体资源，不再生成包含私有 DSH、Node、账户配置和 Qt 工作台的运行组合。安装完成不等于旧 Houdini 进程已加载。正式发布与源码构建分开，完整验证范围见[DSH 兼容](dsh-update-compatibility.md#正式发行单元与发布门)。