为什么选择 Tailscale#

如果只需要暴露某个服务，反向代理或 frp 也可以考虑；frp 并非只能映射一个端口。我选择 Tailscale，主要是希望云服务器继续使用目标内网 IP 和原域名，尽量少改现有程序。

Subnet Router（子网路由器）允许一台加入 Tailscale 的设备，转发发往指定网段或单个地址的流量。目标 API 服务器本身无需安装 Tailscale。

这次只需要一个目标，所以宣告 10.20.30.40/32，不用把整个 10.0.0.0/8 都带进来。/32 表示单个 IPv4 地址；能否访问它，还要经过路由审批、客户端设置和访问策略检查。参考 Tailscale 子网路由文档。

OpenWrt 作为子网路由器连接云服务器与内网 API 的架构示意。

图中为脱敏后的架构示意，公网侧地址仅用于占位。其中“CGNAT”是场景示意，本文未独立验证其成因；“接受路由后可直接访问”“开启 Accept Routes 即可复用”省略了后台审批和访问策略条件，完整要求见第四节。实际请求路径可以理解为：

1
云服务器上的程序
2
  → 云服务器的 Tailscale 接口
3
  → OpenWrt 路由器
4
  → 原有内网路径
5
  → API 服务

网络条件允许时，节点之间直接通信；无法直连时，Tailscale 会尝试通过中继传输。协调服务负责节点发现与连接协调，业务流量不一定经过它。

先分开测试路由器和云服务器#

排错时，先确认失败发生在哪一段。

在路由器上，用目标域名发起请求，同时指定它连接到目标 IP：

1
curl --resolve aiapi.example.com:443:10.20.30.40 \
2
  --connect-timeout 5 --max-time 15 \
3
  https://aiapi.example.com/

这比直接访问 https://10.20.30.40/ 再添加 Host 请求头更合适：URL 里的域名同时用于 HTTPS 的 SNI 和证书主机名检查，--resolve 只替换这次请求的解析结果。参考 curl 的 --resolve 说明。

如果路由器可以访问，云服务器不行，再查隧道、路由和转发；如果路由器也不通，先处理原有网络或服务问题。

坑一：软件包选用了当前固件不可用的防火墙后端#

这次最有价值的一条线索来自日志：

1
logread | grep tailscale

当时出现了：

1
firewallmode="nft-forced"
2
health(warnable=router): error: create table: get table: get tables: netlink receive: invalid argument

这条日志说明，Tailscale 没能正常建立所需的防火墙规则。于是就出现了一个容易误判的状态：节点在线，转发却不通。

问题出在 nftables 后端建立规则的环节。不过，仅凭这条日志，还无法判断具体是内核能力、模块缺失，还是其他兼容问题。能够确定的是：当时被强制选择的 nftables 后端没有正常工作，切换到该固件可用的 iptables 后端后，相关规则恢复。

这次采用的修复是：

1
uci set tailscale.settings.fw_mode='iptables'
2
uci commit tailscale
3
/etc/init.d/tailscale restart

这项 UCI 配置依赖软件包的启动脚本支持。OpenWrt 的相关软件包启动脚本会读取 fw_mode，再传给 Tailscale；自己的固件是否相同，应查看本机脚本：

1
grep -nE 'fw_mode|TS_DEBUG_FIREWALL_MODE' /etc/init.d/tailscale

不能把这次修复概括成“Tailscale 一律默认 nftables，所有 OpenWrt 都要改 iptables”。后端选择受到版本、软件包和启动环境影响；以本机日志为准。参考 Tailscale 防火墙模式文档。

对于这次使用 iptables 的环境，重启后检查：

1
iptables -S | grep -E 'ts-input|ts-forward'

随后，规则中出现了 ts-input、ts-forward 及对应跳转。如果当前系统本来就在用 nftables，单凭 iptables 查不到这些链，并不能判定故障，应查看对应的 nftables 规则。

坑二：后台显示有路由，本机却没有目标明细#

路由器侧处理好以后，云服务器仍然不通。继续查客户端的策略路由：

1
ip rule show
2
ip route show table 52
3
ip route get 10.20.30.40

table 52 是这次 Linux 环境中 Tailscale 使用的路由表；它适合作为排错线索，不是所有平台通用的接口。

当时服务器还在使用另一台机器作为 Exit Node，表里能看到默认路由，却缺少目标 10.20.30.40/32 的明细。这里要留意：目标解析成私有地址，不代表客户端就已收到那条子网路由；一条指向 tailscale0 的默认路由，也不能证明选中了目标子网路由器。

重新应用客户端设置后，访问恢复了。但那次操作同时重设了多个参数，无法据此确定究竟是哪一项起了作用。

尤其不能据此得出“Exit Node 会覆盖所有子网路由，必须加 --exit-node-allow-lan-access”的结论。这个开关用于在使用 Exit Node 时保留客户端本地网络的访问，不是接受远端子网路由的开关。参考 Exit Node 的本地网络访问说明。

遇到类似现象，先依次核对路由宣告、后台审批、客户端 --accept-routes 和访问策略，再结合 ip rule 与路由表分析。如果环境还需要保留原有 Exit Node，应记录并保留原设置，避免排错时顺手改变服务器的默认出口。

处理这类问题时，不建议一上来就使用 tailscale up --reset，或添加开机硬补 table 52 的脚本。前者会重置未列出的偏好，后者可能掩盖路由没有正常安装的问题。应先让 Tailscale 自身的配置和路由状态保持一致。

把调用放回原来的程序#

网络、域名解析和 TLS 都正常后，就可以把调用接回原来的程序。下面是 OpenAI 兼容接口的 curl 示例，模型名、路径和凭据以实际服务为准；API 自身的认证仍然需要保留：

1
curl https://aiapi.example.com/v1/chat/completions \
2
  -H "Authorization: Bearer $API_KEY" \
3
  -H "Content-Type: application/json" \
4
  -d '{
5
    "model": "your-model",
6
    "messages": [{"role": "user", "content": "你好"}]
7
  }'

这里的 $API_KEY 从运行环境读取，不要把真实令牌写进文章、截图或可公开的脚本。

1. 打开插件入口#

启动 DeepSeek Harness，在主界面左上方点击 “插件”，进入插件安装界面。

2. 输入安装地址#

在安装入口输入：

1
github:NielaoGanBu/dsh-purge-plus

图 1：在“添加插件”窗口输入仓库地址，点击“安装”。

填写时保留开头的 github:，使用上面的完整安装标识，不要只复制仓库名称。

确认地址后点击 “安装”，等待安装完成。

3. 启用插件#

安装完成后，在插件列表中找到刚刚安装的插件，将其启用。

别漏掉下一步：安装并启用后，还需要进入插件设置执行一次“应用”。

4. 点击“应用”#

按下面的路径操作：

1. 打开 Harness 的 设置，在左侧选择 Purge。
2. 向下滚动到页面底部，找到“应用”“还原”“卸载”这一组按钮。
3. 点击 “应用”。

按照我的实际安装流程，不需要手动修改配置，直接点击即可。

安装和启用是把插件加进 Harness，“应用”才会执行它所需的本地调整，所以不要在启用后就直接跳到测试。

图 2：进入设置中的 Purge 页面，点击箭头所指的“应用”按钮。

随后软件会提示重启，按照提示重启 Harness。

5. 新建对话#

重启后，新建一个对话，再开始使用。建议先用新对话观察效果，避免沿用原有对话中的上下文。

到这里，安装流程就完成了：

安装插件 → 启用 → 点击“应用” → 重启 → 新建对话。

偶尔问问题、查资料#

选 Free，$0。Free 有有限的 Grok 对话和 Cursor agent 请求，够日常偶尔用。如果你经常碰到额度上限，再升到 Plus。

在 Cursor 里写作业、做课设#

选 Plus，$8/月（年付折合 $7/月）。要注意 Plus 档的 Cursor 只能用 Grok 模型。如果你的课程或习惯必须用 Claude、GPT，就只能上 Premium，而且这些模型还要按 API 价另外付费。

重度写代码，或要用云端 agent 和自动化#

选 Premium，$30/月（年付折合 $25/月）。额度是 Plus 的 4 倍，云端 agent、自动化和 Bugbot 代码审查也只在 Premium 及以上档位才有。

做内容、常用 X、要视频生成或 Grok Bot#

选 Premium。Plus 没有视频生成和 Grok Bot，X 方面也只有蓝标、更少广告、创作者工具和高级分析；完整的 X Premium+ 权益要到 Premium 才有。

图 1：新学生按用法选档

一个小建议：先按月付用一两个周期，看看自己每周的额度消耗，再考虑要不要转年付。Plus 年付每月只省 $1，意义不大；Premium 年付每月省 $5。

1. 填写基本信息#

可以给这枚 Key 起一个容易辨认的名称，例如 DSH。

图 4：创建令牌的基本设置。本例表单选择“一个月”，新建数量为 1。

第一次创建时，重点看以下几项：

“无限额度”不等于账号可以无限使用。 它只是取消这枚令牌自身的额外限额，实际调用仍取决于账户剩余额度。

2. 核对访问限制并提交#

继续向下查看“访问限制”：

• 模型限制列表：留空表示不额外限定这枚令牌可使用的模型，实际可调用范围仍受平台与账号权限约束。需要限制用途时，再选择指定模型。
• IP 白名单：留空表示不设置该项限制；若填写，需要确保包含 DSH 发出请求时的出口 IP。

图 5：访问限制与提交入口。填好后点击右下角“提交”。

提交成功后，在令牌列表找到刚创建的条目，确认状态为“已启用”。

3. 复制完整 API Key#

找到对应令牌的“密钥”列，点击密钥右侧的复制图标。页面较窄时，这一列可能需要横向滚动才能看到。

图 6：复制入口。截图使用已有令牌示范，密钥保持脱敏。

请使用复制按钮获取完整 Key，不能把页面上带星号的显示文本当成 Key。保存和使用时，不要把它放进公开文章、截图或代码仓库。

1. 添加自定义模型 API#

打开 DSH，进入 “设置 → 模型”，点击 “添加模型提供商”，选择 “自定义模型 API”。DSH 官方提供商指南说明了该入口和模型添加流程：模型接入指南。

按下面的对照表填写：

图 7：DSH 配置对照示意图，非客户端实拍截图。

DSH 的 Base URL 要填写到 /v1，不要填写完整的 /v1/chat/completions。 学校首页给出的是根域名和完整请求示例；DSH 的 Chat Completions 适配器在 Base URL 后拼接请求路径，所以这里使用 https://aiapi.usst.edu.cn/v1。地址格式与协议选择依据 DSH 官方模型设置说明。

API Key 输入框只填密钥本身，不要填网站登录密码，也不要加 Bearer 前缀、引号或 API_KEY=。

2. 添加模型并保存#

可以先点击 “获取可用模型”，勾选要用的模型，再点击 “添加所选”。如果列表获取失败，可以按学校“模型广场”显示的准确名称手动添加。

本文用 DeepSeek-V4-Flash 举例：本次在学校“模型广场”中核对到了这一模型 ID。模型 ID 应保持大小写及拼写一致。其他模型的可用性，以平台当前显示和实际请求结果为准。

当前路由说明（2026-10-08）：目前该网站的 DeepSeek 模型均路由到 deepseekv41 处理。 接入 DSH 时仍填写平台对外提供的模型 ID，本文使用 DeepSeek-V4-Flash；deepseekv41 表示后端处理路由。

图 8：学校模型广场中的 DeepSeek-V4-Flash。

添加至少一个模型后，点击保存或应用。上下文长度、最大输出长度、图片输入等可选能力，应依据目标模型说明配置。

3. 回到会话，发出第一条消息#

回到 DSH 会话输入区，在模型选择器中选中刚配置的 “上海理工大学 AI”提供商和 DeepSeek-V4-Flash。若尚未选择工作区，先按界面提示选择一个工作区。

可以先发送一条简单消息：

1
你好，请用一句话介绍一下你能帮助我做什么。

收到正常回复，就说明这次 DSH 文本请求已经连通。准备让它处理项目文件时，再在测试工作区确认工具调用是否正常。

第一步：安装并打开 DSH#

运行官网提供的安装包，按提示完成安装，然后从开始菜单或安装目录打开 DeepSeek Harness。打开设置页的“通用”分区，记下当前版本，便于对照本文的实测记录。

第二步：接入模型#

首次启动时，可以按欢迎页提示通过浏览器登录 DeepSeek 账号，也可以选择 API Key 配置入口，填入密钥后“保存并继续”。若暂时跳过，可稍后在设置中完成配置。账号登录、官方 API Key 和第三方接口的详细步骤见 2.3。

账号登录后若出现额度、用途等引导，按页面提示完成；提供“跳过”选项时，可以暂时跳过。这些页面可能随版本和账号状态变化。完成引导后，仍需在输入区核对当前选中的模型。

第三步：添加工作区并新建会话#

如果侧边栏已经有默认工作区，可以直接打开；为了复现下面的练习，也可以使用“添加工作区”，选择已经创建的 D:\dsh-demo 文件夹，再打开一个新会话。工作区决定任务主要围绕哪个本地目录展开；仅在对话里提到一个路径，不等于已经切换工作区。

在输入区的模型选择器中确认提供商和模型。先发送“请用一句话介绍你自己”，收到正常回复后，再进行文件操作。正常回复只说明模型调用成功，下一步还需检验本地工具是否正常工作。

第四步：让它读取文件并保存结果#

在练习文件夹中创建 notes.txt，写入几条便于核对的内容，例如：

1
本周完成了 DSH 桌面端安装。
2
已经配置好模型，并收到了一次正常回复。
3
下一步学习工作区中的文件读写。

然后在会话中发送：

读取当前工作区的 notes.txt，把内容整理成三条 Markdown 列表，保存到同目录的 summary.md。保留 notes.txt 的原文，完成后告诉我结果文件的路径。

保持默认权限设置；若出现读写文件的批准提示，核对目标路径和操作后再批准。权限模式与沙箱范围的说明见 2.2。

第五步：核对是否完成#

在资源管理器中打开练习文件夹，检查 summary.md 是否存在、内容是否对应原文，并确认 notes.txt 未被修改。会话里也应能看到读取和写入文件的工具记录。以实际文件和工具结果作为完成依据，不能只看模型回复“已完成”。

完成这一步，就验证了模型接入、工作区选择和文件读写三条基本链路。若聊天失败，先按 2.3 核对接入方式、密钥和模型；若聊天正常但文件操作失败，先查工作区与 2.2 的权限设置，再进入第三节排错。

2026-10-03 补充人工确认： 本机已完成登录、收到正常中文回复，并完成工作区内的文件任务，结果文件为 D:\dsh-work\tmp\dsh-practice\summary.md。本次使用已有练习目录，上文的 D:\dsh-demo 则是供读者参考的示例路径；操作时以实际打开的工作区为准。这次检查补充了桌面操作记录，未重新测试安装程序或所有模型接入方式。

1.1 三个核心概念#

配置合成顺序如下，后者覆盖前者：各 bundle 的 patch → profile 用户层 cordis.patch.yml → home 级 $DSH_HOME\cordis.patch.yml → 命令行 --patch。

注意：home 级 patch 的优先级高于 profile 级 patch。如果两处覆盖了同一个条目，最终会采用 home 级的配置。因此，排查配置未生效时，也要检查 home 目录里的 cordis.patch.yml。同一 id 出现多次时，最后一次写入生效；patch 条目的排列顺序不等同于插件的加载顺序。

另一条关键规则是：patch 会整块替换目标插件的 config，不会深度合并其中的字段。即使只修改一个键，也要在覆盖项中保留其他仍需使用的键；未写出的字段会回到默认值。示例见 3.2。

1.2 安装目录与用户数据目录#

以下是本机目录示例。D:\harness 是本文使用的安装位置；%DSH_HOME% 表示 DSH 实际采用的数据目录，没有自定义时通常为 %USERPROFILE%\.dsh。PowerShell 中读取环境变量使用 $env:DSH_HOME，请按自己的安装路径替换示例。

1
D:\harness\                          # 安装根目录
2
├─ DeepSeek Harness.exe
3
├─ version                           # Electron 版本（本机 44.0.0）
4
└─ resources\
5
   ├─ app.asar                       # 应用代码，注意：这是【文件】不是目录
6
   └─ runtime\
7
      ├─ cli\bin\dsh.cmd             # CLI 入口（排错主力）
8
      ├─ pnpm\                       # 内置 pnpm
9
      ├─ primary-runtime\            # 内置 node/python 运行时
10
      └─ versions.json               # node 24.18.1 / pnpm 11.7.0
11

12
%USERPROFILE%\.dsh\                  # 默认 DSH_HOME（未自定义时）
13
├─ profiles\{desktop,web,...}\       # 各运行面的 package.json + cordis.patch.yml + node_modules
14
├─ sessions\<工作区>\<会话id>\session.v4.jsonl.zstd   # 会话日志
15
├─ skills\                           # 技能目录
16
├─ storages\                         # 存储域（workspace.json 等）
17
├─ attachments\  cache\  dsh-runtimes\
18
└─ .credentials.yaml                 # 凭据

DSH_HOME 的解析优先级为：显式路径 > 环境变量 $DSH_HOME > ~/.dsh，空白的环境变量值会被忽略。会话、技能和日志目录的位置取决于实际采用的数据目录，排错前应先确认其路径。

使用这些路径时，还需注意：

• app.asar 是文件。在普通 PowerShell 或独立 Node.js 中，不能把 app.asar\dsh\... 当作常规目录访问。4.4 提供仅读取指定文件的最小脚本，以及保存、运行和查阅版本对应 README 的步骤。
• desktop profile 由 Electron 应用独占，CLI 不能直接启动它，详见 3.10。
• 内置 Node.js 不在 PATH 中。需要从命令行运行脚本时，使用绝对路径 %DSH_HOME%\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe。

1.3 CLI 入口#

1
$dsh = 'D:\harness\resources\runtime\cli\bin\dsh.cmd'
2
& $dsh --version           # 0.2.0-rc.2
3
& $dsh --help

1
dsh [--profile] <name> [options] [app-args...]
2
  --profile <name>               启动 $DSH_HOME/profiles 下的某个运行面
3
  --from-default-profile <name>  用官方模板创建一个新 profile
4
  --patch <path>                 追加一层覆盖（可重复）
5
  --dump-config                  打印合成后的完整配置树并退出
6
  --dump-config-schema           只打印 schema，不挂载插件
7
  --dump-default-config          打印不含用户层的配置树
8
dsh plugin --profile <name> <pnpm-args...>    # 直接对 profile 执行 pnpm 操作

桌面应用通常通过双击 exe 启动，底层使用 desktop profile。CLI 可以提供更完整的配置诊断信息，但 desktop 有 Electron 独占限制；需要复现桌面配置时，先按 3.10 创建诊断副本。后文中的 <profile名> 是占位符，执行时应换成实际可由 CLI 使用的名称。

2.1 界面速览#

• 侧边栏：底部是固定的设置（Settings）入口。会话列表默认按“最近更新”排序，也可切换为手动排序。展开的工作区默认显示 5 条空闲会话；运行中的会话始终显示，不计入这 5 条的显示数量。
• 会话行：悬停操作区或 ... 菜单提供置顶（pin）、重命名（rename）、分叉（fork）和归档（archive）。Fork 会从源会话最后一个已完成轮次处创建新会话，标题自动递增。
• 输入区：Enter 按当前投递模式发送，Ctrl+Enter 按另一种模式发送；忙碌时可选择“排队”或“插话”，本机使用 steer 插话模式。Shift+Enter 换行；/ 打开命令菜单，Tab 确认，Esc 退出。点击模型选择控件可打开模型列表。
• 停止当前轮次：连按两次 Esc，默认间隔不超过 500 ms。这是内置固定快捷键，不能修改绑定。
• 设置页：由各功能包注册的分区组成，常见分区包括通用、模型、插件、插件清单、Web search、会话日志、子智能体、Agent 循环和账户。通用分区可查看当前发布版本。

常用快捷键（Windows 桌面端）：

Mod 在 Windows 上表示 Ctrl。可自定义的快捷键保存在 Electron 用户数据目录下的 keybindings.json；停止当前轮次的双 Esc 例外。

2.2 权限与沙箱：按任务选择模式#

DSH 把“沙箱范围”和“审批策略”打包成预设。本文版本的随附配置提供三种预设，人工确认的中文名称为“仅可查看”（read-only）、“工作区内修改”（workspace-write）和“完全权限”（danger-full-access）。插件字段说明里的默认表只列后两项，不等于随附配置的实际选项。

日常先通过界面操作：

1. 在当前会话输入 /permission，查看可用选项并切换当前会话的权限。输入区的权限控件也用于当前会话。
2. 需要改变以后新建会话的默认值时，再到“设置 → 通用”中的默认权限设置调整。本机人工确认：修改默认值后，当前会话保持原权限，新会话采用新默认值。
3. 本次练习中，“仅可查看”下请求写文件出现了提权提示；切换到“工作区内修改”后，文件成功生成。出现提权提示时，先核对操作和目标路径，再决定是否批准。

需要用 YAML 固定预设时，先备份将要修改的 cordis.patch.yml，再核对同一个目标 profile 的合成配置。按 4.1 的方法运行 --dump-config，定位 id: permission，读取当前完整的 config.presets 和 defaultPreset。desktop 不能直接由 CLI dump，需按 3.10 建立诊断副本；不能把 web 的权限配置当作桌面端当前配置。

patch 会整块替换 config，因此即使只调整 defaultPreset，也必须在覆盖项中保留自己的完整预设表及其他仍需使用的字段。优先在界面调整新会话默认值（见上面的步骤 2）；只有明确需要固定 YAML 时，才把核对后的覆盖项写入 %DSH_HOME%\profiles\<profile>\cordis.patch.yml。

下面只演示将新会话默认值设为“工作区内修改”。 本机原默认值为“完全权限”，照抄此段会改变默认值；它不是保留当前设置的模板。预设名称、沙箱与审批策略均应以自己的 dump 为准，再有意识地决定需要修改哪些值：

1
- id: permission
2
  name: '@deepseek-ai/dsh-permission-presets'
3
  config:
4
    presets:
5
      read-only:
6
        sandbox: read-only
7
        approval: ask
8
      workspace-write:
9
        sandbox: workspace-write
10
        approval: ask
11
      danger-full-access:
12
        sandbox: danger-full-access
13
        approval: never
14
    defaultPreset: workspace-write

本文版本中，三种沙箱模式的主要行为如下：

还需区分以下三点：

1. 这些模式主要约束文件影响。 官方说明不提供网络限制；进程可见性因后端而异，文件读取也会受到具体后端与系统权限的影响，不能概括为“全部不受限制”。选择 read-only 后，仍需考虑命令会读取哪些数据。
2. 修改默认预设只影响新会话。 defaultPreset 在创建会话时读取并记录，之后修改默认设置不会改变已有会话的权限。要修改当前会话，使用 /permission；不带参数时可查看当前值与可选项。
3. 审批策略只有 ask 和 never 两个值。 授权仅对本次调用有效，没有“始终允许”选项。never 会拒绝所有审批请求：需要审批的操作会被拒绝，模型也不会申请提权。无人值守时，需确认任务能在已有权限内完成。

Windows 上的沙箱通过受限令牌和 Low 完整性标签实现：子进程使用 WRITE_RESTRICTED 令牌，写入与删除受限，临时目录也会替换为按会话或工作区隔离的私有目录。本机观察到以下现象：

• 受限模式下某些 CIM 类命令（如 Get-ComputerInfo）不可用；
• read-only 下 PowerShell 使用 ConstrainedLanguage 模式，Add-Type、部分 .NET 静态调用、COM 和反射会失败；
• 受限进程通过管道捕获孙进程输出（stdio: 'pipe'）时会报 EPERM，继承或忽略 stdio 时则正常。

调用被拒后如何处理？ 拒绝信息会包含 [sandbox: file access denied under <mode> mode] 标记和提权提示。允许的升级路径为：read-only → workspace-write 或 danger-full-access；workspace-write → danger-full-access。应在这些路径内选择满足操作所需的最低权限，保持命令与参数不变，重试一次，不能更换命令。

本机测试时使用了 danger-full-access 默认预设，命令直接以宿主权限执行。日常在项目内修改文件，可以先选择 workspace-write；任务确实需要越界写入时，再核对目标路径和当前审批策略。

2.3 模型接入与思考强度#

DSH 可以同时接入多个模型提供商。初次使用时，先通过下面的一种方式完成配置，再按需添加其他提供商。界面字段以当前版本为准，完整说明见官方模型接入指南。

1
- id: agent-default-model
2
  name: '@deepseek-ai/dsh-agent-default-model'
3
  config:
4
    provider: mygateway
5
    model: some-model

1
- id: llm-pi-ai
2
  name: '@deepseek-ai/dsh-llm-pi-ai'
3
  config:
4
    providers:
5
      mygateway:
6
        apiKeyEnv: MY_GATEWAY_API_KEY
7
        api: openai-completions
8
        baseURL: https://your-gateway.example.com/v1
9
        reasoning: 'off'
10
        models:
11
          - id: some-model
12
            name: Some-Model
13
            contextWindow: 262144
14
            reasoningEfforts:
15
              off: none
16
              low: low
17
              high: high
18
              max: xhigh

1
启动时的环境变量  >  %DSH_HOME%\.credentials.yaml  >  调用目录\.env  >  %DSH_HOME%\.env

2.4 指令文件：AGENTS.md / CLAUDE.md#

DSH 会将指令文件注入上下文，加载规则如下：

• 默认按 AGENTS.md、CLAUDE.md、AGENTS.local.md、CLAUDE.local.md 的顺序加载同目录内所有存在的候选文件；内容不同的 AGENTS.md 与 CLAUDE.md 都会加载，并非二选一；
• 加载范围包括用户全局文件 %DSH_HOME%\AGENTS.md，以及从项目根目录到当前工作目录的祖先链上的同名文件；
• 项目根目录是从当前工作目录（cwd）向上找到的第一个含 .git 的目录；找不到时，使用 cwd；
• 同目录内的文件按去除空白后的内容判重，跨目录不合并。默认预算为 65536 字节，超出时优先丢弃作用范围较广的指令。

指令刷新依赖文件访问与步骤检查，没有独立的文件监听器。 在外部编辑器中修改 AGENTS.md 后，需要等到相关文件读写、会话恢复时的状态核对，或下一次步骤开始前的检查（pre-step），更新才会被发现。通过 bash 修改目录中的其他文件，也不会自动触发嵌套指令发现。需要及时应用新指令时，可以让 DSH 读取对应文件。

实践建议：跨项目通用的要求写入用户全局文件，项目特有的要求写入仓库根目录文件。本机分别配置了全局和工作区指令；两者可有部分重叠，但作用范围不同。

2.5 长会话与上下文#

会话以仅追加的事件日志保存，模型看到的历史根据日志还原。因此：

• 压缩（compaction）会遮蔽部分历史，使其不再直接进入模型上下文，但不会删除原始日志；回放仍可重现相同状态。
• 自动压缩阈值按以下参数计算：窗口 W、输出上限 O、余量 B（默认 65536 tokens），阈值为 floor(min(W × 0.8, W − O − B))；逐字保留的近期历史默认为 W − O 的 16%。
• 溢出兜底：提供方确认”上下文溢出”后，会先压缩再重试该请求一次。
• 手动压缩使用 /compact。命令不会作为普通聊天轮次进入模型历史，但生成摘要时会发起辅助模型请求，消耗 token；若仅裁剪工具结果就已足够，则可能跳过摘要请求。完成后会显示减少的历史项数量与预计节省的 token。此命令只在会话空闲时可用，忙碌时会显示提示；压缩期间发送的消息会排队，结束后再处理。

会话还有一套用于异常恢复的检查点机制：模型请求前、顶层工具执行前、每个 pre-step 都会写检查点。如果中途崩溃，恢复时：

• 有 tool/call 但没有结果的调用 → 标记为 TOOL_OUTCOME_UNKNOWN（结果未知）；
• 尚无启动记录的工具调用 → 标记为 TOOL_NOT_STARTED（尚未开始）。

这两种调用都不会自动重试。只读或幂等操作可以直接重跑；可能产生副作用的操作，必须先核对外部状态。应用崩溃或断电后，应先检查命令是否已经产生结果，再决定是否重跑。

2.6 会话与工作区管理#

• 会话归档：本文版本提供归档操作。若会话仍有进行中的轮次、子代理、后台任务或定时提醒，归档会被拒绝，并提示“停止并归档”。
• 移除工作区不会删除数据：文件夹、文件和会话历史都会保留，相关会话进入未分组（Ungrouped）列表。重新添加同一目录会创建新的工作区记录，旧会话不会自动归入其中。
• 用 @path 引用文件：在输入开头或空格后输入 @ 可触发补全；带空格的路径写为 @"my file.txt"。选中候选只会添加引用，不会读取文件内容；模型仍需调用文件工具才能看到内容。
• 附件：图片会在消息被接受前校验并规范化，支持 PNG、JPEG、WebP 和 GIF；任一图片不合法，整条消息都会失败。其他文件按原始字节保存，模型只收到文件位置提示。本文版本不会自动清理已存储的附件，长期使用时需留意存储占用。
• 导出会话：在会话头部的“更多操作”中选择“下载 Session 日志”，或在会话中输入 /export。两种方式都会将**整个会话树（会话本体、子会话和附件）**打包为 ZIP，由浏览器下载，文件名形如 dsh-session-<id>.zip。/export 不接受参数，因此不能使用 /export <路径>，也不会直接写入 Host 磁盘。

2.7 扩展：技能 / 插件 / MCP / 定时任务#

技能向模型提供操作说明，插件向运行时注册能力。先看两者的区别，再选择需要的扩展方式：

3.0 先确定检查顺序#

先检查配置与组装，再检查运行行为。

遇到“安装并重启后功能仍未出现”，先确认相关 bundle 是否参与组装。一个实用的排查顺序是：

1
配置是否被读到 → bundle 是否被跳过 → 插件是否激活 → 实际行为是否正确
2
  合成配置         跳过报告          启动/运行日志       请求体与对照实验

用证据区分症状与根因。

一次搜索插件排查中，我先后将 bundle 的提供方绑定（pin）复制到用户层、为搜索提供方增加输出截断，并向 node_modules 手动放入宿主包。复盘发现，输出截断修正了一处实现问题，但插件未生效的主要原因是升级后的版本预检。复制 pin 并未解决版本预检问题，手动放入的包还可能被包管理器清理。

这个案例说明，组装问题和实现缺陷可能同时存在。修改前先读宿主诊断，可以避免把两类问题混在一起。

3.1 症状：插件已安装并重启，仍不生效#

首先检查：bundle 是否被版本预检跳过。

组装时，DSH 会将每个 bundle 声明的 @deepseek-ai/dsh* 依赖兼容范围（peerDependencies）与运行时版本进行 semver 比较，预发布号也参与比较。不匹配时，整个 bundle 会被跳过：其插件条目不会插入，随附 patch 也不生效。GUI 中可能没有明显报错，但诊断输出和启动控制台会记录跳过信息。

诊断：

1
& $dsh --profile <profile名> --dump-config *> dump.txt
2
Select-String -Path dump.txt -Pattern 'skipping profile bundle'

如果看到 skipping profile bundle ...，继续核对被跳过的包和未满足的 peer 范围。合成配置中出现了插件条目，也不代表该插件已成功激活。

两个关键细节：

• 运行时版本以 @deepseek-ai/dsh-app-boot 的 version 为准，不能以其他清单文件中的版本代替；
• 兼容声明需使用匹配当前预发布版本的精确版本或版本范围。~0.2.0、^0.2.0 都不匹配 0.2.0-rc.2，编写兼容声明时应特别核对预发布号。

按以下优先级处理：

① 优先更新兼容的插件版本。 检查插件发布的兼容声明，选择覆盖当前运行时的版本。若你是插件作者，应先验证实现兼容，再修正 peer 范围，例如使用精确的 0.2.0-rc.2 或包含该预发布版本的范围。仅修改声明不能修复代码不兼容。

② 通过“版本豁免”授权指定版本。 用于兼容性测试的豁免记录保存在 profile 目录的 compatibility.json 中，将 包名@版本 精确映射到允许的 DSH 运行时版本列表：

1
# 查看当前运行时版本与已有授权
2
& $dsh plugin --profile desktop version-exemptions
3

4
# 授权（会先打印风险警告；必须显式带上 --accept-risk）
5
& $dsh plugin --profile desktop allow-version <包名@版本> --dsh-version <运行时版本> --accept-risk
6

7
# 撤销
8
& $dsh plugin --profile desktop revoke-version <包名@版本> --dsh-version <运行时版本>

三点要注意：

• 授权只适用于指定的插件版本与运行时版本组合。 插件或 DSH 升级后，原授权不再覆盖新的组合，需要重新授权。
• 授权在下一次组合时生效。 支持在线重新组合的 profile 会挂载插件并返回 applied；仅支持启动期组装的 profile 会返回 restart-required。
• 版本豁免只改变预检判定，不能证明实际兼容。 peer 不匹配说明兼容声明未覆盖当前运行时，继续加载可能导致崩溃或数据丢失。授权命令会先显示风险警告，应在明确了解兼容性风险后使用。

兼容性拒绝的错误码为 incompatible-version，记录中会包含每个被拒包的 name、version、runtimeVersion 和未满足的 peers。可据此核对并修正插件的兼容声明。

这次云端记录只查看了版本豁免机制，没有授予豁免。上文授权命令是操作说明，不能作为本次已执行或已验证兼容的证据。

3.2 症状：patch 写了，配置没变#

依次检查以下四项：

① 覆盖目标的 id 不存在。 覆盖已有条目的前提是该 id 已存在于某个 bundle 的默认层。否则 DSH 会打印 patch: entry ... not found 并跳过该项，不会因此终止启动。需要新增条目时，应使用 insert:：

1
# 覆盖既有行：要求这个 id 已在某个 bundle 的默认层里存在
2
- id: ui-chat
3
  name: '@deepseek-ai/dsh-client-ui-chat'
4
  config:
5
    transcriptView: compact
6

7
# 新增行：id 不在任何默认层里时，必须用 insert
8
- insert:
9
    - id: my-hook
10
      name: '@deepseek-ai/dsh-hooks-claude-code'
11
      config: { }

② 覆盖时遗漏了仍需保留的键。 patch 条目会整块替换 config，不会深度合并。修改一个字段时，需一并保留其他仍需使用的字段，否则它们会回到默认值。

③ 相关 bundle 被跳过了。 先按 3.1 处理 bundle 的兼容性问题；只向用户层补充提供方绑定（pin），不能代替完整组装。

④ 文件为空或只有注释。 cordis.patch.yml 不允许为空，空文件或纯注释文件会导致启动失败。如果不需要这一层提供覆盖项，应写入空 YAML 数组 []，不要清空文件。

遇到 entry not found 时，先确认提供原条目的 bundle 是否参与组装，再判断是否真的需要新增条目；不要直接把旧覆盖改成 insert:。

3.3 症状：修改配置或代码后，无法判断是否需要重启#

启用热重载（HMR）后，DSH 会监视 profile 的补丁层，cordis.patch.yml 的修改通常可在不重启应用的情况下生效。具体仍取决于改动类型和插件的响应方式：

HMR 监视 profile manifest，以及 profile 级和 home 级两份用户 patch 文件。配置文件写入默认有约 2 秒的稳定窗口，因此连续快速编辑可能合并为一次更新。通过插件管理器执行操作时，不需要等待文件事件。

不要把“纯 insert 才能热挂载”或某次接口返回的 supported: false 当作所有桌面版本的规则。官方共享插件管理器区分配置重新组合与已安装包版本替换：前者取决于 HMR，后者仍需重启。以本次操作返回的 applied、restart-required、警告与实际激活情况判断；需要重启时先保存结果，完全退出应用后重新打开。

3.4 症状：Hook 完全不执行，退出码是 3221225794 / 0xC0000142#

本机曾因 Windows 子进程环境问题遇到 Hook 启动失败。相同退出码也可能由其他原因引起，应先对照运行环境。DSH 自带的桥接插件可读取并执行现有 Claude Code hooks.json 中的配置，示例如下：

1
- name: '@deepseek-ai/dsh-hooks-claude-code'
2
  config:
3
    configPath: ./.claude/hooks.json          # hooks.json，或含 hooks 键的 settings 文件
4
    pluginRoot: ./.claude/plugins/my-plugin   # 用于替换命令里的 ${CLAUDE_PLUGIN_ROOT}
5
    projectDir: .                             # 用于替换 ${CLAUDE_PROJECT_DIR}，并设同名环境变量

Electron 宿主会在子进程的 PATH 开头加入 <安装目录>\resources\runtime\bin。目录中的 node（无扩展名）和 node.cmd 是转发启动命令的 shim，内容大致如下：

1
set ELECTRON_RUN_AS_NODE=1
2
"%DSH_DESKTOP_NODE_EXECUTABLE%" --expose-internals %*

本机故障中，DSH_DESKTOP_NODE_EXECUTABLE 只在前述子进程环境中设置。Hook 进程继承了修改后的 PATH，却没有该变量，于是 Hook 命令中的裸 node 命中了 shim，但启动所需的变量为空，导致进程启动失败。手动运行同一脚本时退出码为 0，在 DSH 中则返回 0xC0000142（STATUS_DLL_INIT_FAILED），且 stderr 为空。

本案例的修复：将 Hook 命令中的裸 node 替换为可用 node.exe 的绝对路径。

本机通过以下对照步骤定位了问题：

1. 手动运行 Hook 脚本，确认脚本本身能够正常执行；
2. 尽量复现 DSH 的命令参数（argv）、工作目录（cwd）和环境变量，再运行一次，同时提供 stdin 并收集 stdout，对照执行结果；
3. 每次只改变一项条件，例如路径中的正反斜杠、cwd 或 SystemRoot，逐项对照，定位影响执行的因素。

排查 Hook 时，还需注意以下规则：

• Hook 配置作用于整个进程，且仅在启动时读取一次。 修改 hooks.json 后，需要重启 DSH 才能生效，不支持热更新。
• Hook 在会话工作区目录中执行；脚本中的相对路径以工作区为基准，不是 DSH 的启动目录。
• 退出码 0 表示脚本正常退出，桥接会解析该事件支持的 stdout 或 JSON；退出码 2 表示阻塞结果，效果取决于事件。UserPromptSubmit 会阻塞提示词提交，PreToolUse 会在工具执行前拦截，PostToolUse 只能影响已执行工具的结果与反馈，不能撤销工具动作；Stop 的阻塞会强制模型再执行一步，SubagentStop 仅作观测。其他非零退出码记为非阻塞失败。排查时需同时核对事件名、退出码与输出。
• 本文版本中，桥接传入的 transcript_path 始终为空字符串：默认会话日志经过 Zstandard 压缩，Hook 脚本无法直接读取，持久化层也未暴露产物路径。
• 本文查阅的该版本文档未说明上述 Windows shim 问题，因此这部分结论来自本机对照实验。

3.5 症状：HTTP 状态码为 200，功能仍不正常#

检查响应体是否包含业务错误。 本机曾遇到火山搜索端点鉴权失败却返回 HTTP 200 的情况：响应体实际包含错误信息，插件因缺少预期的结果字段，将其转述为“没有搜索结果”。

处理时可直接向端点发送请求，查看原始响应。本机故障中，插件只提示缺少结果字段，原始响应则明确包含 invalid_api_key。

当状态码与客户端表现不一致时，应同时记录 HTTP 状态和业务错误字段，再判断请求是否成功。

3.6 症状：切换模型或思考强度后，看不出变化#

按以下顺序检查：

1. 强度值是否在目标网关与模型的支持范围内（本机网关的取值见 2.3）；
2. 核对 DSH 实际请求中的字段，可查看适配器调试输出或网关请求记录。直接用 curl 请求网关只能验证网关能力，不能代替对 DSH 请求的检查；
3. 切换模型与强度只对下一次请求生效，正在执行的步骤保留启动时的设置；
4. 确认修改的是当前会话的选择，还是新会话的默认值；已有会话仍保留各自记录的选择。

不同模型对思考强度的响应可能不同，输出长度也不能直接证明参数是否生效。可使用相同提示词、只改变强度做 A/B 对照，记录 token 数与输出长度作为辅助指标；主要证据仍是 DSH 实际请求中的字段。

3.7 症状：搜索正常返回，结果却来自其他提供方#

一种典型情况是：插件通过 bundle 自带的 patch，将搜索提供方绑定到自己的实现。一旦 bundle 被版本预检跳过（见 3.1），绑定也会失效，搜索便回落到内置提供方。此时可能没有明显报错，也能返回结果，但结果来源已发生变化。

这一版本内置搜索提供方的实现，也有助于理解报错来源：DSH 内置的 DeepSeek 搜索提供方走的是 Anthropic 兼容的 Messages API，一次搜索要消耗一个完整的模型轮次（本文所查阅实现没有使用独立的公开检索端点）。它只从结构化的 web_search_tool_result 块里取结果，缺这个块时直接抛错而不是降级，错误码是 WEB_PROVIDER_ERROR（凭据缺失则是 WEB_PROVIDER_CREDENTIAL_MISSING）。需要直接调用独立检索 API 时，可以接入对应的 provider。

要判断实际调用了哪个搜索提供方，可结合以下三类证据：

1. 用相同输入做 A/B 对照：同一查询词分别经 DSH 实际调用链路和目标 API 直连请求，比对结果的 URL 集合；
2. 对照结果格式：不同实现可能带有独特标记，例如某个实现每条结果均包含 标题 — 摘要 (ISO 时间)，另一个只包含标题和链接；
3. 核对配置与跳过报告：运行 --dump-config，检查合成配置及 skipping profile bundle 报告。

本机用这套方法核对了实际调用：DSH 返回的 8 条中文来源，与直连目标 API 的结果 URL 完全重合，交集为 8/8；此前使用内置提供方时，交集为 0/8。

同一次排查也留下了一个教训：第一次对照用了不同查询词，因而不能根据结果差异判断提供方是否正确。A/B 对照应使用相同输入，并尽量控制请求时间与其他参数。

3.8 症状：命令被拒，提示 [sandbox: file access denied under ...]#

该标记表示调用被沙箱拒绝。先核对当前权限模式，以及命令实际涉及的路径：

• read-only：不允许常规文件写入；需要写入时，通过 /permission 切换到 workspace-write。
• workspace-write：可能是在写工作区之外的路径。
• 需要临时扩大权限时，在允许的升级路径内选择满足操作所需的最低权限，保持命令与参数不变，重试一次。允许的路径为 read-only → workspace-write 或 danger-full-access、workspace-write → danger-full-access，不能同时更换命令。

以下现象也可能来自沙箱限制：受限模式下，Get-ComputerInfo 等 CIM 命令不可用，因为授权列表中没有 Authenticated Users；read-only 下 PowerShell 使用 ConstrainedLanguage，Add-Type、反射和部分 .NET 静态调用会失败。确认任务确实需要这些能力后，再按权限流程选择合适模式。

本机排查还发现，受限模式涉及的 Windows 完整性标签和 ACL 条目可能在 DSH 退出后继续保留，工作区改名后也要检查残留权限。它与 danger-full-access 绕过隔离是两个不同问题；遇到退出后仍无法写入的情况，应检查目录权限，而不是只调整会话预设。

3.9 症状：MODULE_NOT_FOUND / 路径不存在#

先用 Test-Path 核对实际文件位置。两处容易混淆的情况是：

• app.asar 是文件，在普通文件系统工具中，不能把 app.asar\dsh\... 当作目录路径；
• 文档、旧笔记甚至运行环境提示里的”检出位置”都可能过期。

1
Test-Path 'D:\harness\resources\app.asar'        # True：文件存在
2
Test-Path 'D:\harness\resources\app.asar\dsh'    # False：它不是目录

3.10 症状：CLI 报 profile is managed exclusively by the Electron application#

desktop profile 归 Electron 应用管，CLI 会拒绝直接启动和配置 dump；npm 安装的 CLI 也不能管理它的插件。Desktop 内置 CLI 可在应用完全退出后管理已初始化的 desktop 插件。想从命令行查看相似配置，下面是本机采用的诊断副本方法，并非官方提供的 Desktop 启动入口：

1. 在 %DSH_HOME%\profiles\ 下新建目录，名字以 _ 开头；
2. 复制 desktop 的 package.json 和 cordis.patch.yml；
3. 若用 junction 引用原 node_modules，只做配置诊断，不在副本中执行包安装、更新或卸载；共享依赖会影响原 profile；
4. 用完先解除 junction 再删目录。

创建和清理诊断副本时，本机发现两项注意事项：

• JSON 序列化与文件编码要分开考虑。 ConvertTo-Json 负责生成文本，BOM 是否出现取决于写入方式和 PowerShell 版本。本机曾因带 BOM 的 package.json 遇到 Unexpected token；保存时应明确使用 UTF-8 无 BOM。
• 清理前核对 junction 的实际目标；先移除链接本身，再删除诊断目录，避免误处理被引用的依赖。

3.11 症状：抓不到网页 / 提示非公网 IP#

本地代理启用 fake-ip 后，域名可能解析为 198.18.x.x 等保留地址。工具层的 SSRF 校验会将其判定为非公网 IP 并拒绝请求。此时 web_fetch 失败，并不表示网络连接本身不可用。

先检查代理的 DNS 模式和域名解析结果，再用正确配置代理的 curl.exe 或其他可用通道验证连通性。若确认是 fake-ip 导致，应优先为相关域名调整代理解析规则，使工具获得真实公网地址。

排查时，应区分工具层拒绝请求与网络连接失败；两者可能表现相似，但处理方式不同。

3.12 症状：重启应用中断了当前会话#

重启承载当前会话的进程会中断任务。先保存结果与验证步骤，再按实际运行环境操作。

3.13 症状：DSH 启动失败，或启动后缺少功能#

这两种情况的检查重点不同，需要分别处理。

① 应用启动失败。 本机此类失败的退出码为 1。DSH 会打印错误摘要，并将完整诊断写入 $DSH_HOME\logs\startup-<时间戳>-<uuid>.log：

1
Get-ChildItem "$env:USERPROFILE\.dsh\logs" | Sort-Object LastWriteTime -Descending |
2
  Select-Object -First 3 Name, Length, LastWriteTime

阅读和分享启动诊断时，注意以下两点：

• 报告开头会提示：原始诊断可能包含插件错误中的配置或凭据值，分享前需检查。发到群聊或 issue 前，应先查看并处理敏感内容。
• 先找失败条目和原因，再判断影响范围。 已启用的必需条目激活失败会终止启动；普通条目失败通常只产生警告。具体必需 id、错误分类与处理规则见官方启动与重载失败说明，本文不复制完整清单。仓库主分支可能更新；核对本机版本时，按 4.4 读取 @deepseek-ai/dsh-app-boot/README.zh.md，同时查看“启动应用”和“启动与重载失败”两节。

② 应用正常启动，但缺少功能。 先检查是否有 bundle 被跳过，见 3.1。启动控制台只会打印一次跳过列表，排查时应保留并回看这份输出。

桌面端致命错误会提供恢复选项。选择禁用第三方插件并备份 profile patch 的恢复操作后，才会将 profile 的 cordis.patch.yml 改名为 cordis.patch.yml.bak-<时间戳> 并保留；不是每次致命错误都会自动改名，home 级 patch 也不会被修改。发现”配置消失了”时，核对是否执行过恢复操作，并查找同目录备份。

3.14 症状：依赖清单里有插件，运行时却没有对应能力#

检查安装、组装和激活三层状态。 dependencies 中有包，说明 profile 声明了依赖；dsh.profile.bundles 决定哪些组合包参与配置；实际激活记录和工具调用才说明能力可用。

检查时，先核对实际 profile 的 package.json 中这两份清单，再看合成配置、跳过报告和启动日志。官方 CLI 文档说明，插件增删与更新成功后会按包的 bundle 元数据同步列表；手动改文件或跨版本升级后仍需核对实际结果。

界面插件需要分别核对三项证据：

1. 宿主激活： 相关条目已在运行时激活。
2. 客户端注入： 所需模块已进入客户端资源。
3. 界面验收： 组件实际显示，交互和对应功能正常。

云端“依赖仍在、工具未恢复”的具体记录见附录 A.4；验收界面插件时，应完成上述三步。

4.1 三个配置诊断命令：先定位条目，再判断是否生效#

先把配置输出与诊断信息分开保存。 下面沿用 1.3 的 CLI 变量 $dsh，web 只是目标 profile 示例；排查哪个 profile，就使用它的名字。检查桌面配置时，先按 3.10 创建诊断副本，再把 $profile 改成副本名：

1
$profile = 'web'
2
& $dsh --profile $profile --dump-config 1> .\dsh-effective.yml 2> .\dsh-diagnostics.txt
3
$dumpExitCode = $LASTEXITCODE
4
"dump exit code: $dumpExitCode"
5

6
# 示例：定位权限条目的行号，并显示附近内容
7
Select-String -LiteralPath .\dsh-effective.yml -Pattern 'id:\s*permission\s*$' -Context 3,30
8

9
# 查看跳过报告与错误原因；没有匹配结果时，仍应阅读完整诊断文件
10
Select-String -LiteralPath .\dsh-diagnostics.txt -Pattern 'skipping profile bundle|incompatible|error' -Context 2,8

Select-String 给出的上下文只是定位窗口，不代表条目已经显示完整。用编辑器打开 dsh-effective.yml，从匹配行读到这个 YAML 条目结束，重点核对：

1. 条目是否存在。 按准确 id 搜索；不知道 id 时先搜包名。没有匹配项，再查目标 bundle 是否在 profile 的 dsh.profile.bundles 中，以及 stderr 是否说明它被跳过。
2. 值是否符合预期。 查看该条目的 name、disabled 和整个 config。权限条目要同时读取 presets 与 defaultPreset；其他插件则核对具体字段、文件路径与模型 ID。需要查默认值时，再对同一个 profile 单独运行 --dump-default-config，定位同一条目进行对照。
3. 运行时是否真的启用。 合成配置中有条目，仍需回看兼容性拒绝报告、启动日志与一次真实调用。dump 的 disabled 字段也不能单独证明 Loader 已激活它。

三个命令会输出诊断后退出，不启动应用。准备阶段仍可能创建缺失的 profile 文件；schema 导出还会导入模块。因此，使用前应确认目标 profile 与目录权限，不能将这些命令视为完全只读。

使用前还需注意：

• --dump-config 打印的是合成配置，不是实际激活的插件清单。被 Loader 拒绝激活的插件条目仍可能出现在其中，但组合阶段被跳过的 bundle 不会提供条目。判断 bundle 是否被跳过，需查看 skippedBundles 对应的 stderr 报告，区分“条目未激活”和“组合包未参与配置”。
• --dump-config-schema 导入模块时会执行模块顶层代码，也可能留下模块句柄；应对可信的 profile 使用。
• 三个 dump 参数互斥，均不接受应用参数；--dump-default-config 不能与 --patch 同时使用。

本机曾在退出码为 1 时得到可解析的 schema JSON，但这不足以证明输出完整。官方说明允许返回部分输出并以 1 退出。应检查根节点的 x-cordis.complete、diagnostics，以及条目的 partial、unsupported、error 状态。有效 JSON 可用于诊断，complete: true 也不保证应用能够成功启动。

4.2 用独立 profile 做端到端验证#

可以使用独立的测试运行面，验证插件是否能够正确组装并调用：

1
# 1) 从官方模板初始化测试运行面，输出配置后退出，不启动任务
2
& $dsh --profile _probe --from-default-profile headless --dump-config
3

4
# 2) 用插件命令把目标组合包及其依赖安装到测试运行面
5
# 将 <目标组合包> 换成真实包名；本步骤不复用 desktop 的 node_modules
6
& $dsh plugin --profile _probe add <目标组合包>
7

8
# 3) 跑一个真实任务
9
& $dsh --profile _probe "用 web_search 查一下 xxx，把来源 URL 列出来"

headless profile 的第一个参数是任务字符串，不是子命令；缺少任务时会报用法错误。--from-default-profile 仅用于目标目录尚不存在时，初始化后重试需去掉该参数。上述测试可验证普通 headless 宿主中的插件组装与调用，但可能受 home 级 patch 和共享凭据影响，也不能单独证明 Electron 宿主兼容性。

云端独立实例的检查记录见附录 A.7。

只复制配置文件也未必复刻了原 profile 的依赖解析环境，应核对目标 bundle 能否在副本中解析。上面的 headless 示例安装插件后，还应检查目标包是否进入该 profile 的 dsh.profile.bundles，并完成最后一步真实任务；需要验证界面组件时，再到实际宿主检查界面。

4.3 解压会话日志：注意多帧 Zstandard#

会话日志文件为 session.v4.jsonl.zstd。在本文样本中，直接对整个文件调用 zstdDecompressSync 只解出了首帧，输出仅有 192 个字符，容易被误判为日志为空。

日志由多个独立的 Zstandard 帧拼接而成：首帧只包含 header，后续持久化批次继续追加新帧。如果只解出首帧，很容易误判日志内容不完整。

1
// 保存为 check-zstd.mjs，使用实际用于解压的 Node.js 运行
2
import * as zlib from 'node:zlib';
3
console.log(process.version, typeof zlib.zstdDecompressSync);

1
// dump-session.mjs —— 用法: node dump-session.mjs <session.v4.jsonl.zstd>
2
import fs from 'node:fs';
3
import zlib from 'node:zlib';
4

5
const buf = fs.readFileSync(process.argv[2]);
6
const chunks = [];
7
let offset = 0;
8

9
while (offset < buf.length) {
10
  const result = zlib.zstdDecompressSync(buf.subarray(offset), { info: true });
11
  const consumed = result.engine.bytesWritten;
12
  if (!Number.isInteger(consumed) || consumed <= 0) {
13
    throw new Error('无法确定当前帧消耗的输入字节数，停止解压');
14
  }
15
  chunks.push(result.buffer);
16
  offset += consumed;
17
}
18

19
const text = Buffer.concat(chunks).toString('utf8');
20
const lines = text.split('\n').filter((line) => line.trim());
21
console.log(`帧数=${chunks.length} 字符=${text.length} 行数=${lines.length}`);
22
lines.slice(0, 3).forEach((line) => console.log(line.slice(0, 200)));

1
[对照] 整块解压 -> 192 chars
2
帧数=1215  字符=4603787  行数=2164
3
行类型分布：session / permission/preset / model/selection / turn/start /
4
           hook/invoked / hook/result / tool/call / tool/result / step/end ...

4.4 读 app.asar 里的官方代码与文档#

app.asar 是应用归档。下面的最小脚本按头部目录和文件偏移读取一个指定文件，无需解包整份应用。先将代码保存为 UTF-8 文件 asar-cat.mjs；它只处理普通文件，不展开目录，也不跟随归档内的链接。

1
// asar-cat.mjs —— 用法: node asar-cat.mjs <app.asar> </dsh/package.json>
2
import fs from 'node:fs';
3
import path from 'node:path';
4

5
const [asarPath, target] = process.argv.slice(2);
6
const buf = fs.readFileSync(asarPath);
7

8
// ASAR 头部使用带长度的 Pickle 格式；文件数据区位于完整头部之后。
9
const headerSize = buf.readUInt32LE(4);
10
const jsonSize = buf.readUInt32LE(12);
11
const header = JSON.parse(buf.subarray(16, 16 + jsonSize).toString('utf8'));
12
const segments = target.split('/').filter(Boolean);
13

14
let entry = header;
15
for (const segment of segments) entry = entry?.files?.[segment];
16
if (!entry || entry.files || entry.link) {
17
  throw new Error('目标不是普通文件：' + target);
18
}
19

20
if (entry.unpacked) {
21
  process.stdout.write(fs.readFileSync(path.join(asarPath + '.unpacked', ...segments)));
22
} else {
23
  const start = 8 + headerSize + Number(entry.offset);
24
  process.stdout.write(buf.subarray(start, start + Number(entry.size)));
25
}

在保存脚本的目录中打开 PowerShell，再执行：

1
# 按实际 DSH_HOME 定位内置 Node.js，无需额外安装 Node
2
$dshData = if ([string]::IsNullOrWhiteSpace($env:DSH_HOME)) {
3
  Join-Path $env:USERPROFILE '.dsh'
4
} else {
5
  $env:DSH_HOME
6
}
7
$nodeExe = Join-Path $dshData 'dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe'
8
$asar = 'D:\harness\resources\app.asar'  # 改成自己的安装路径
9

10
# 先读运行时 package.json，核对版本与包含的包
11
& $nodeExe .\asar-cat.mjs $asar '/dsh/package.json'
12

13
# 再读本机版本的启动文档
14
& $nodeExe .\asar-cat.mjs $asar '/dsh/node_modules/@deepseek-ai/dsh-app-boot/README.zh.md'

第二条命令会把 README 输出到终端。需要保存时，在命令末尾加 > .\app-boot-README.zh.md，再用编辑器查找“启动应用”和“启动与重载失败”。查其他插件时，替换最后一个参数中的包名与文件名即可。

本文所用 Windows 安装包的运行时版本为 0.2.0-rc.2，上述两个归档内路径均已核对可读取。若其他版本提示“目标不是普通文件”，先核对包名和目录是否变化；若 Node 路径不存在，先在资源管理器中核对实际数据目录。脚本只读取安装包，不改动应用文件。

归档内容有两类常见用途：

• 核对插件接口：同一安装版本中，官方同类插件的 lib/index.js 可用于检查真实接口与调用方式；
• 查阅官方说明：对应包附带的 README.zh.md 可用于核对配置项。对某个配置项含义有疑问时，可先读取该安装版本归档中的 README。

4.5 插件开发中的离线验证#

插件开发时，可先进行离线验证：

1. 从 app.asar 提取官方同类插件的实现，用于核对接口约定；
2. 使用真实的 schemastery、模拟宿主包和 registerHooks，在测试环境中挂载插件；
3. 检查 Config 解析、apply() 执行及最终请求的字段与结构。

这样可在不重启 DSH 的情况下检查接口连接与请求构造。仍需端到端验证的部分，再按 4.2 使用独立测试 profile 检查。

5.1 日常修改：保留配置来源与恢复记录#

常用覆盖配置保存在 %DSH_HOME%\profiles\<profile>\cordis.patch.yml，但 home 级 patch、profile manifest 与插件依赖也会影响结果。修改时可以遵循四个步骤：

1. 备份涉及的文件。修改前保存带时间戳的 patch 与 manifest 副本，或确认已有可用的版本记录，便于恢复原配置。
2. 一次验证一类改动。配置与插件代码分开修改，记录预期行为，再用诊断输出和实际调用核对结果。
3. 区分禁用、卸载与版本回退。临时停止功能可先禁用插件；完整撤销安装时，应核对 package.json 的 dependencies、dsh.profile.bundles 和对应用户 patch，并通过插件管理页或包管理器同步依赖。手动创建的 junction 单独解除，避免直接删除共享依赖目录。需要回到旧版本时，恢复先前版本与配置，再按加载边界重启。
4. 核对异常恢复备份：在原生致命错误弹窗中选择禁用第三方插件并备份 profile patch 的恢复操作后，会将 profile 的 cordis.patch.yml 改名为同目录的 cordis.patch.yml.bak-<时间戳>；不是报错后自动发生。发现配置变化时，对照这份备份、手动备份与启动日志，再决定是否恢复。

5.2 跨版本升级：备份之后逐项验收#

升级前既要保存回退材料，也要记录恢复步骤；备份存在与回滚已经验证是两件事。云端升级记录见附录 A.2。

升级时可以沿用以下检查顺序：

1. 记录基线并保存备份。 确认实际安装位置、数据目录和运行入口；备份涉及的配置、锁文件及依赖版本，并记录服务的启动方式。升级可能改动会话存储时，也应先保存相关数据。
2. 在空闲时逐步隔离第三方扩展。 禁用工具插件可能影响当前任务，先保存任务结果，并记录原 bundle 顺序与对应 patch。基础运行正常后，再逐项恢复扩展。
3. 让副本覆盖需要验证的环境。 核对依赖解析、配置组装和临时实例启动；随后完成认证、真实消息与目标工具调用。单次 dump 成功或 HTTP 响应，只覆盖其中一部分。
4. 重启后核对实际进程。 对照新进程的启动时间、启动日志和版本，再检查模型、工具及界面。若出现异常，按事先记录的版本与配置恢复，并重新验证；不能用安装命令成功代替验收。

A.1 安装位置、服务数据目录与凭据来源#

Debian 云端记录：先分清安装位置与服务的数据目录。 这台服务器使用全局 npm 安装，代码位于 /usr/lib/node_modules/@deepseek-ai/dsh，使用系统 Node.js；Windows 桌面端则使用应用归档和自带运行环境。云端路径不能直接替换进本文的 PowerShell 命令。

在 Linux 上，DSH_HOME 未设置时仍需按默认 ~/.dsh 查找，不能把空环境变量直接拼成 /profiles/web/…。systemd 服务采用的用户、主目录和环境还可能与当前 SSH shell 不同，应先确认正在运行的服务实际使用哪份配置。本文标注为 Bash 的命令仅用于 Linux shell；Windows 读者使用对应的 PowerShell 写法。

Debian 云端记录：查不到凭据文件中的条目，不等于功能没有配置。 材料中的一次语音功能排查，最初只查看 .credentials.yaml，随后才确认相关配置来自 systemd 的 EnvironmentFile 和插件读取的配置文件。排查时应沿服务实际启动环境和该插件的凭据规则追踪，再用一次真实调用验证；不要把桌面模型适配器的查找顺序套到所有第三方插件上。记录配置来源与变量名即可，不必打印密钥值。

A.2 升级兼容、残留 patch 与回退材料#

Debian 云端记录：优先寻找兼容的新插件版本。 升级时，dsh-audio-kit@0.2.2 声明的 @deepseek-ai/dsh-tools 范围为 ^0.1.6-alpha.2，未覆盖 0.2.0-rc.2；dshmarket@1.65.1 也因旧 peer 范围被拒绝。材料随后记录，dshmarket@1.66.6 的声明已包含 ^0.2.0-rc.1。因此，应先检查插件是否发布了兼容版本，再考虑测试用豁免；直接手改已安装包的 peer 声明会在后续安装时被覆盖，也不会修复实际代码不兼容。

Debian 云端记录：先查 bundle，再决定是否新增条目。 升级前临时移除了第三方 bundle，但保留了用户 patch；隔离诊断因此打印 patch: entry "meow-memory" not found。材料记录，恢复对应 bundle 后该警告消失。这个案例中缺少的是提供原始条目的组合包，应先恢复其组装来源；不能一看到 entry not found 就把旧覆盖改成 insert:，否则可能引入重复条目。

Debian 云端记录： 这次升级前保存了约 518 MB 的安装目录备份，以及 profile 的 manifest、patch、生成配置和锁文件，并记录旧版本、新版本、CLI 入口指向与备份位置。它证明准备了回退材料，不等于已经演练并验证回滚成功。

A.3 从服务外部核对重启#

Debian 云端记录：服务重启可能同时终止发起操作的智能体。 如果当前 DSH 会话和命令进程都属于 dsh.service，停止服务时，它们可能一起收到终止信号。systemd 默认的 KillMode=control-group 会在停止阶段终止该单元中的剩余进程；nohup 或 setsid 本身不会把进程移出服务的控制组。该行为见 systemd v252 的进程终止说明。

材料记录了两种容易混淆的结果：一次重启命令被 SIGTERM 中断，后续步骤未完成；另一次工具结果显示“未知”，但外部 journal 中已有对应的 Stop/Start 记录。因此，工具回复不能单独证明服务重启成功或失败，应从独立 SSH 会话或外部管理终端核对服务状态。

以下为 Linux 上的查询命令；若服务名不同，请替换 dsh：

1
systemctl show dsh -p ActiveState -p SubState -p MainPID -p ExecMainStartTimestamp --no-pager
2
journalctl -u dsh -n 30 --no-pager -o short-iso

核对新进程的启动时间、启动日志和版本信息，再验证模型与目标工具。安装目录已更新、端口已监听，都不能单独证明新代码已加载或功能恢复。查询历史日志时，--since 应包含完整日期和时间；只写时分秒可能落到另一天。若需要从 DSH 所在服务内部安排重启，应让外部管理终端或独立服务单元承接操作，先保存结果与回退信息。

A.4 依赖仍在，但 bundle 与工具尚未恢复#

Debian 云端记录： 升级后，4 个第三方包仍在依赖清单中，但 dsh.profile.bundles 只保留了 @deepseek-ai/dsh-base 和 @deepseek-ai/dsh-web-app。它们是升级前被临时禁用的 bundle，不能因安装状态仍在就认定已经恢复。

检查时，先核对实际 profile 的 package.json 中这两份清单，再看合成配置、跳过报告和启动日志。当前官方 CLI 文档说明，插件增删与更新成功后会按包的 bundle 元数据同步列表。因此，这个现场不能泛化为“CLI 永远只装依赖、从不更新 bundle”；不同版本和修改入口应以实际清单及运行结果为准。

材料还记录，禁用这些 bundle 后，当前会话少了 8 个记忆工具和 5 个音频工具；后来在恢复 bundle 并重启后重新核对。它没有单独验证“只加回 bundle、不重启”能否恢复当前会话的工具列表。桌面端人工确认的插件启停结果见 2.7，不能据此替代云端验证。

材料只提供了宿主激活与客户端注入两层的部分记录，尚未完成界面验收；不能用脚本已注入代替界面可用性检查。

A.5 诊断或 npm 查询报 EACCES#

环境：Debian 云端。

先看失败的路径与操作。 云端记录中，--dump-config 和 dsh web --help 都曾在准备阶段尝试写入 /root/.dsh/profiles/web/cordis.yml，并因权限受限失败。另一次 npm view 则因无法访问 /root/.npm/_cacache 失败。这些错误分别指向 profile 写权限和 npm 缓存权限，不能直接归为插件加载失败。

对 profile 路径，应核对运行用户、目录所有权、挂载方式与当前沙箱限制；对 npm 缓存，可以指定当前用户可写的临时缓存再查询。材料使用过下面的 Bash 写法：

1
npm_config_cache=/tmp/npm-cache-upg npm view @deepseek-ai/dsh version

该命令查询 registry 中的版本，不会更新正在运行的服务。诊断和帮助命令也未必完全只读；不要只因命令名是 --help 就排除准备阶段的文件写入。

A.6 真实消息报提示词变量缺失#

Debian 云端记录： 升级后的会话出现了以下报错：

1
prompt variable "{{model}}" has no value for this assembly (section "deployment:persona-prefix")

这条信息说明，提示词组装所需的 model 变量没有获得值。排查时应先根据 deployment:persona-prefix 找到对应模板与配置来源，再核对当前模型选择、变量提供方和插件的版本兼容情况；必要时在独立 profile 中减少相关扩展，观察是否仍能复现。

材料没有通过隔离实验确定具体责任插件，也没有验证通用修复方案。因此，不能据此断言重新安装某个插件一定有效。服务启动成功与一次真实消息成功，是两个需要分别验证的步骤。

A.7 独立 Web 实例的验证范围#

Debian 云端记录：隔离检查只证明已检查的阶段。 使用独立 DSH_HOME 和临时端口测试时，材料记录 --dump-config 退出码为 0、合成配置有 296 个条目，临时 Web 实例约 6 秒后返回 HTTP 401。这说明配置输出成功、HTTP 服务已有响应；401 只表明请求未通过认证，不能证明模型调用或第三方工具成功。

A.8 多帧日志与旧格式文件#

Debian 云端记录：检查运行时能力，再判断日志是否完整。 材料中的另一个压缩样本大小为 334492 字节，整块解压只得到约 193 个字符；逐帧处理记录了 210 帧、约 106 万字符。这与本文 Windows 样本的统计是两组独立记录，不能互相替代。

材料还记录，同一会话目录可能同时留有 session.v3.jsonl.zstd 和 session.v4.jsonl.zstd。读取时应核对实际文件、header 和事件内容，不要只根据文件名判断会话是否已经迁移，也不要因为短输出就删除日志。

2.1 确认 Node 环境与 DSH 版本#

以下操作在服务器宿主机的 SSH 终端中完成。先查看现有 Node 环境和 DSH 可用版本：

1
node -v
2
npm -v
3
npm view @deepseek-ai/dsh dist-tags

选定 DSH 版本后，查询它要求的 Node 版本：

1
DSH_VERSION='替换为目标版本号'
2
npm view "@deepseek-ai/dsh@$DSH_VERSION" engines --json

如果尚未安装 Node，按 Node 官方安装说明 安装满足要求的版本。使用下载镜像时，核对版本、架构和安装位置。

2.2 安装并确认入口路径#

1
sudo npm install -g "@deepseek-ai/dsh@$DSH_VERSION" \
2
  --no-audit --no-fund
3

4
command -v node
5
command -v dsh
6
npm root -g
7
dsh --version
8
dsh web --help

安装耗时取决于服务器资源和网络。官方 registry 无法访问时，可以用 --registry 指定可用镜像；出现 ETARGET 时，先检查包名、版本号，以及该 registry 是否已收录目标版本。

如果希望在后台安装并持续查看日志，可以使用：

1
# 将引号内的版本号替换为已经确认存在的版本。
2
sudo sh -c 'nohup nice -n 10 ionice -c3 npm install -g \
3
  "@deepseek-ai/dsh@替换为目标版本号" --no-audit --no-fund \
4
  > /var/log/dsh-npm-install.log 2>&1 &'
5
tail -f /var/log/dsh-npm-install.log

按 Ctrl+C 会退出日志跟踪，后台安装仍会继续。安装完成后，用 dsh --version 确认结果，并记录 command -v dsh 返回的入口路径，后续创建服务时会用到。

3.1 创建运行用户与工作区#

下面使用专门的 dsh 用户，家目录为 /var/lib/dsh，工作区为 /srv/dsh-workspace。如果已有运行用户，沿用它，并同步调整后续路径。

1
id dsh >/dev/null 2>&1 || sudo useradd \
2
  --system --user-group --create-home --home-dir /var/lib/dsh dsh
3
sudo mkdir -p /srv/dsh-workspace /var/lib/dsh/.dsh
4
sudo chown dsh:dsh /srv/dsh-workspace /var/lib/dsh /var/lib/dsh/.dsh

工作区可以替换为自己的项目目录，运行用户需要具备相应的读写权限。

3.2 创建服务#

先通过 dsh web --help 确认当前版本支持下列参数，再创建服务。这里用 DSH_BIN 填入实际安装入口：

1
DSH_BIN="$(command -v dsh)"
2
test -n "$DSH_BIN" || { echo '未找到 dsh，请先完成安装'; exit 1; }
3

4
sudo tee /etc/systemd/system/dsh.service > /dev/null <<EOF
5
[Unit]
6
Description=DeepSeek Harness Web
7
After=network-online.target
8
Wants=network-online.target
9

10
[Service]
11
Type=simple
12
User=dsh
13
Group=dsh
14
WorkingDirectory=/srv/dsh-workspace
15
Environment=HOME=/var/lib/dsh
16
Environment=DSH_HOME=/var/lib/dsh/.dsh
17
Environment=PATH=/usr/local/bin:/usr/bin:/bin
18
Environment=NO_COLOR=1
19
ExecStart=$DSH_BIN web --host 127.0.0.1 --port 3080 --trusted-host dsh.example.com --no-open
20
Restart=on-failure
21
RestartSec=5
22
StandardOutput=journal
23
StandardError=journal
24

25
[Install]
26
WantedBy=multi-user.target
27
EOF
28

29
sudo systemctl daemon-reload
30
sudo systemctl enable --now dsh

将 dsh.example.com 替换为实际域名。如果 Node 通过 nvm 等用户级工具安装，还要核对目录权限和 PATH，因为 systemd 不会自动加载交互式 shell 配置。

我的实例另设了 MemoryHigh=1536M、MemoryMax=2G。这是该机器的服务资源上限，设置时应给系统和反代留出内存，不能当作 DSH 的最低配置要求。

3.3 检查服务状态#

1
sudo systemctl status dsh --no-pager
2
sudo ss -lntp | grep ':3080'
3
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/

确认状态为 active (running)，并且监听地址为 127.0.0.1:3080。本文版本启用了 DSH 自带认证，未登录访问首页返回 401 属于预期行为。至此可以确认服务已启动，模型调用和浏览器连接留到后面验证。

4.1 写入环境文件#

将 YOUR_API_KEY 换成实际密钥。下面的命令会覆盖环境文件；公开代码或截图时保留占位值。

1
sudo mkdir -p /etc/dsh
2
sudo tee /etc/dsh/env > /dev/null <<'EOF'
3
DEEPSEEK_API_KEY=YOUR_API_KEY
4
EOF
5
sudo chown root:root /etc/dsh/env
6
sudo chmod 600 /etc/dsh/env

文件由 root 拥有，权限为 600。系统级 systemd 读取后将变量传给服务进程，DSH 的运行用户无需直接读取它。

4.2 通过 drop-in 注入#

1
sudo mkdir -p /etc/systemd/system/dsh.service.d
2
sudo tee /etc/systemd/system/dsh.service.d/api-key.conf > /dev/null <<'EOF'
3
[Service]
4
EnvironmentFile=-/etc/dsh/env
5
EOF
6

7
sudo systemctl daemon-reload
8
sudo systemctl restart dsh
9
sudo systemctl status dsh --no-pager

这里沿用实例中的 EnvironmentFile=-/etc/dsh/env。路径前的 - 表示文件缺失时仍允许服务启动，所以还要检查变量是否真正进入进程。

环境文件修改后需要重启 DSH；daemon-reload 只重新加载服务配置，不会更新已运行进程的环境。

4.3 验证注入结果，不显示密钥#

1
PID=$(systemctl show -p MainPID --value dsh)
2
if [ "$PID" -gt 0 ]; then
3
  sudo cat "/proc/$PID/environ" \
4
    | tr '\0' '\n' \
5
    | grep -c '^DEEPSEEK_API_KEY=.'
6
else
7
  echo 'DSH 未运行，请先检查服务日志'
8
fi

输出 1，表示进程环境中存在非空的 DEEPSEEK_API_KEY。密钥是否有效、所选模型是否可用，还要通过实际回复验证。

这里用 sudo cat 读取进程环境，再统计匹配数量。若直接使用 sudo tr ... < /proc/$PID/environ，重定向会先由当前 shell 执行，普通用户可能在 sudo 生效前就遇到权限不足。

使用自定义供应商时，还需配置对应的凭据引用、模型和接口地址；DEEPSEEK_API_KEY 只覆盖使用这一凭据名的配置。

5.1 添加 DNS 记录#

以 dsh.example.com 为例，在 example.com 的 DNS 管理页面添加：

截图中的 xxx.<ip>.com 是原始标注，实际应理解为自己的域名，例如 dsh.example.com。服务器 IP 填入“记录值”，无需拼进域名。首次调试可以先直接解析到服务器，减少 CDN 回源配置带来的影响。

5.2 在 1Panel 创建反向代理网站#

进入“网站 → 网站 → 创建网站”，绑定实际域名，将反代目标设为 http://127.0.0.1:3080。随后在 HTTPS 配置中申请或选择证书，并启用 HTTPS。

上图展示创建入口，上游、证书和自定义配置在对应站点中设置。云安全组及主机防火墙应放行网站端口，DSH 的 3080 端口继续只监听回环地址。

检查并重载 OpenResty#

先用 docker ps 找出本站使用的 OpenResty 容器，将容器名填入 ORESTY：

1
sudo docker ps --format '{{.Names}}'
2
ORESTY='替换为实际 OpenResty 容器名'
3
sudo docker exec "$ORESTY" /usr/local/openresty/nginx/sbin/nginx -t

配置检查通过后，再执行重载：

1
sudo docker exec "$ORESTY" /usr/local/openresty/nginx/sbin/nginx -s reload

7.1 配置 Basic Auth#

为了给公网入口增加用户名和密码验证，我在反代中配置了 Basic Auth。浏览器访问时会显示：

Basic Auth 位于反代外层，DSH 的 token/cookie 属于内层认证。第 8 节通过 sync.sh 自动提供内层凭据，两层配合完成登录。

下面使用 openssl passwd -5 生成 SHA-256 crypt 密码记录：

1
DIR=/opt/1panel/www/sites/dsh.example.com
2
read -rp '用户名: ' AUTH_USER
3
read -rsp '密码: ' AUTH_PASSWORD; echo
4
AUTH_HASH=$(printf '%s' "$AUTH_PASSWORD" | openssl passwd -5 -stdin)
5
printf '%s:%s\n' "$AUTH_USER" "$AUTH_HASH" \
6
  | sudo tee "$DIR/htpasswd" > /dev/null
7
unset AUTH_PASSWORD AUTH_HASH

密码文件应放在无法通过网站直接下载的位置，并设置为 OpenResty 运行用户可读。接着在 location / 中加入：

1
auth_basic "DSH";
2
auth_basic_user_file /www/sites/dsh.example.com/htpasswd;

本文宿主机路径为 /opt/1panel/...，容器内对应路径为 /www/...。请根据自己的挂载关系填写 auth_basic_user_file。

密码工具的参数应按对应工具理解。例如，OpenSSL 的 -5 指 SHA-256 crypt；传统 DES crypt 的 8 位密码限制不适用于 apr1。Apache 密码工具文档

完成第 8 节的自动登录配置后，再检查 WebSocket。如果页面正常、WS 却返回 401，应核对 WS 入口的外层认证。sync.sh 只提供 DSH 内层凭据，独立的 WS location 也需要有效的外层访问控制。

7.2 WebSocket 通行证：一次认证绕过与修复#

我的实例为 /api/remote.mux 配置了精确匹配的 location：普通页面使用 Basic Auth，WS 入口则检查静态 dshgate cookie，通过后再注入 DSH 会话 cookie。因此，dshgate 本身也是访问凭据，持有它就能建立新连接。

检查时发现，发放通行证的 Set-Cookie 指令带有 always。匿名请求虽然收到 401，响应仍发出了 dshgate；仅带这个值的 WS 握手随后得到 101，绕过了 Basic Auth。

修复时，我去掉了这条 Set-Cookie 的 always，保留 HSTS 的 always，并同时轮换通行证的发放值和比较值。下面只列相关配置行，部署时需合并到实际 location：

1
# location / 内；继续保留 auth_basic 和 auth_basic_user_file
2
add_header Strict-Transport-Security "max-age=31536000" always;
3
add_header Set-Cookie "dshgate=NEW_RANDOM_VALUE; Path=/; HttpOnly; Secure; SameSite=Lax";
4

5
# location = /api/remote.mux 内；与上面使用同一个新值
6
if ($cookie_dshgate != "NEW_RANDOM_VALUE") { return 401; }

不带 always 的 add_header 只对文档规定的状态码生效，其中不包含 401。错误页、内部跳转和响应头继承也应结合站点配置检查。Nginx 响应头文档

另外，$remote_user 非空不代表密码验证成功。它读取的是 Basic 请求头中解析出的用户名，错误密码或不存在的用户也可能让它有值，不能据此发放通行证。Nginx 变量源码 · Basic 头解析源码

修复后的验证结果如下：

• 在实际站点中，匿名、用户不存在和密码错误的请求均返回 401，且不再下发通行证；WS 使用空值、错误值或旧值也都被拒绝。
• 在同镜像隔离环境中，正确 Basic 凭据得到 200 和新通行证；新通行证通过模拟 mux 的校验，进入内容阶段后返回 404。这个测试验证了门禁逻辑，没有建立真实 DSH WebSocket。
• 最后，我刷新已登录页面，确认新建立的 remote.mux 返回 101，并能收到模型回复，完成实际站点的合法访问验证。

静态通行证与 Basic Auth 密码相互独立，改密码时也应轮换通行证。会话 cookie 的浏览器属性不代表服务器端有效期；轮换只影响新握手，已有 WS 长连接仍可能由旧 worker 继续持有。本次重载保留了这些连接，没有强制中断会话。

重载是否生效，应结合日志和请求行为判断。本次通过新 worker 启动、旧通行证被拒绝确认了变化。nginx -T 适合检查磁盘配置和 include 链，不能读取运行中 worker 的配置；reload 命令返回 0，也只说明信号已送达。Nginx 命令行文档

8.1 启动 token 与会话 cookie#

启动 token 随进程启动变化，用于兑换 cookie；cookie 的签名密钥会持久保存。本地凭据提供方将其存于 $DSH_HOME/.credentials.yaml。

只要签名密钥、authority（规范化域名和端口）及有效期符合要求，既有 cookie 就能跨重启继续使用。 脚本用于首次兑换和周期刷新，重启后同步一次也是我的日常操作习惯。

默认 cookieMaxAgeDays 为 30 天，脚本在 20 天时刷新。调整有效期后，应同步缩短刷新周期。凭据删除或更换后，DSH 在下一次激活时加载新密钥，原有签名随之失效，需要重新兑换。DSH 浏览器认证设计

8.2 准备目录与 include#

以下继续使用 dsh.example.com。将它换成自己的域名，并核对宿主机与容器的挂载路径：

1
sudo install -d -m 755 /usr/local/lib/dsh-auth
2
sudo install -d -m 700 /var/lib/dsh-auth
3

4
# 站点已在 1Panel 中创建后执行；已有文件时 touch 不会清空其内容。
5
sudo mkdir -p /opt/1panel/www/sites/dsh.example.com/proxy
6
sudo touch /opt/1panel/www/sites/dsh.example.com/proxy/dsh-auth.inc

在实际转发请求的 location 中，加载容器内对应的文件：

1
include /www/sites/dsh.example.com/proxy/dsh-auth.inc;

如果 /api/remote.mux 使用独立 location，也要加载这条 include，并保留 Host 和 WebSocket 转发参数。占位文件必须在配置检查前存在，否则 Nginx 无法读取它。

自动注入会让反代请求携带有效的 DSH 凭据。因此，普通页面应保留 Basic Auth；采用通行证的 WS 入口，应只接受成功认证后发出的有效通行证。

8.3 服务器现用脚本#

下面是服务器现用脚本，将域名和容器名统一改为示例值。使用前，把 dsh.example.com、your-openresty-container 及相关路径换成自己的配置。

该版本从 MainPID 对应日志中取 token，以成功状态文件的修改时间判断是否刷新。配置检查或重载命令失败时，会尝试恢复上一版 include，并返回非零退出码。

服务器上已验证未到刷新周期时的正常跳过；兑换、写入、回滚和失败重试在隔离环境完成测试，本次没有强制改写生产 cookie。

将代码保存为 /usr/local/lib/dsh-auth/sync.sh，以 root 运行：

1
#!/usr/bin/env bash
2
# 用当前 dsh 进程的启动 token 换一个浏览器会话 cookie，注入给 OpenResty。
3
# dsh 重启或 cookie 快到期时自动刷新；平时空转退出。
4
#
5
# 2026-10-01 加固：
6
#   1) token 按 dsh.service 当前 MainPID 过滤（journalctl _PID=），不再依赖日志行数窗口；
7
#   2) 写文件/找容器/兑换 cookie/nginx -t/reload 任一步失败都非零退出，且不打印成功；
8
#   3) TOKEN_FILE 只在 nginx -t 与 reload 都成功后才写，失败后下次执行必然重试；
9
#   4) 刷新判定改用 TOKEN_FILE 的 mtime（= 上次成功时间），不看 include 的 mtime，
10
#      避免「失败后 include 变新 → 下次被跳过」；
11
#   5) 替换 include 前保留上一版到 $BACKUP，nginx -t / reload 失败时恢复并报告结果。
12
set -uo pipefail
13

14
# 以下路径均可用环境变量覆盖，仅用于隔离测试/换站点；默认值即本站生产值。
15
DOMAIN="${DSH_AUTH_DOMAIN:-dsh.example.com}"
16
DSH_URL="${DSH_AUTH_DSH_URL:-http://127.0.0.1:3080}"
17
INCLUDE="${DSH_AUTH_INCLUDE:-/opt/1panel/www/sites/dsh.example.com/proxy/dsh-auth.inc}"
18
BACKUP="${DSH_AUTH_BACKUP:-/var/lib/dsh-auth/dsh-auth.inc.prev}"
19
TOKEN_FILE="${DSH_AUTH_TOKEN_FILE:-/var/lib/dsh-auth/token}"
20
SERVICE="${DSH_AUTH_SERVICE:-dsh.service}"
21
ORESTY="${DSH_AUTH_ORESTY:-your-openresty-container}"
22
NGINX_BIN=/usr/local/openresty/nginx/sbin/nginx
23
REFRESH_DAYS=20
24

25
fail() { echo "sync.sh: $*" >&2; exit 1; }
26

27
# 1) 取「当前 dsh 进程」的启动 token
28
MAIN_PID="$(systemctl show -p MainPID --value "$SERVICE" 2>/dev/null)"
29
case "$MAIN_PID" in
30
  '' | 0)   fail "$SERVICE 未运行或没有主进程（MainPID=${MAIN_PID:-空}）" ;;
31
  *[!0-9]*) fail "无法解析 $SERVICE 的 MainPID：$MAIN_PID" ;;
32
esac
33
TOKEN="$(journalctl -u "$SERVICE" _PID="$MAIN_PID" --no-pager 2>/dev/null \
34
  | grep -o 'token=[A-Za-z0-9_-]\+' | tail -1 | cut -d= -f2)"
35
[ -n "$TOKEN" ] || fail "未在 $SERVICE 当前进程（PID $MAIN_PID）的日志里找到启动 token"
36

37
# 2) 是否需要刷新：以「上次成功同步时间」（TOKEN_FILE 的 mtime）为准
38
NEED=1
39
if [ -f "$TOKEN_FILE" ] && [ -f "$INCLUDE" ] && [ "$(cat "$TOKEN_FILE")" = "$TOKEN" ]; then
40
  AGE=$(( ( $(date +%s) - $(stat -c %Y "$TOKEN_FILE") ) / 86400 ))
41
  [ "$AGE" -lt "$REFRESH_DAYS" ] && NEED=0
42
fi
43
[ "$NEED" = 1 ] || exit 0
44

45
# 3) 用启动 token 换浏览器会话 cookie
46
COOKIE="$(curl -si -H "Host: $DOMAIN" "$DSH_URL/?token=$TOKEN" \
47
  | grep -i '^set-cookie:' | head -1 \
48
  | sed -E 's/^[Ss]et-[Cc]ookie:[[:space:]]*([^;]+).*/\1/' | tr -d '\r')"
49
[ -n "$COOKIE" ] || fail "换取 cookie 失败（token 可能已过期，或 $DSH_URL 不可达）"
50

51
# 4) 写新 include（先保留上一版）
52
printf 'proxy_set_header Cookie "%s";\n' "$COOKIE" > "$INCLUDE.tmp" \
53
  || fail "写入 $INCLUDE.tmp 失败，未改动 $INCLUDE"
54
HAVE_BACKUP=0
55
if [ -f "$INCLUDE" ]; then
56
  cp -p "$INCLUDE" "$BACKUP" || fail "备份 $INCLUDE 到 $BACKUP 失败，未改动 $INCLUDE"
57
  HAVE_BACKUP=1
58
else
59
  echo "sync.sh: 注意：$INCLUDE 原先不存在，本次首次写入，无上一版可回滚" >&2
60
fi
61
mv "$INCLUDE.tmp" "$INCLUDE" || fail "替换 $INCLUDE 失败"
62

63
rollback() {
64
  if [ "$HAVE_BACKUP" = 1 ]; then
65
    if cp -p "$BACKUP" "$INCLUDE"; then
66
      echo "sync.sh: $1；已恢复上一版 include（$BACKUP）" >&2
67
    else
68
      echo "sync.sh: $1；恢复失败！请手工把 $BACKUP 复制回 $INCLUDE" >&2
69
    fi
70
  else
71
    echo "sync.sh: $1；无上一版可恢复，请人工检查 $INCLUDE" >&2
72
  fi
73
}
74

75
# 5) 固定容器 + 配置检查 + 重载
76
docker inspect -f '{{.State.Running}}' "$ORESTY" 2>/dev/null | grep -qx true \
77
  || { rollback "OpenResty 容器 $ORESTY 不存在或未运行，未 reload"; exit 1; }
78
docker exec "$ORESTY" "$NGINX_BIN" -t >/dev/null 2>&1 \
79
  || { rollback "nginx -t 失败，未 reload"; exit 1; }
80
docker exec "$ORESTY" "$NGINX_BIN" -s reload >/dev/null 2>&1 \
81
  || { rollback "nginx -s reload 失败"; exit 1; }
82

83
# 6) 全部成功后才提交成功状态
84
printf '%s' "$TOKEN" > "$TOKEN_FILE" \
85
  || fail "写入 $TOKEN_FILE 失败（配置已生效，下次执行会重新兑换）"
86

87
echo "已同步 $DOMAIN 的 cookie"
88
exit 0