DSH 安装使用手册

1. 安装约 7 分钟 · 勿中断

   sh

   # 必须锁定版本号，不要安装最新版
   npm install -g @deepseek-ai/dsh@0.1.5-rc.1

   共引入约 523 个包，属正常现象；完成后核对 dsh --version（见 §2.1）。

2. 安装插件无需 dsh web 运行中

   sh

   dsh plugin --profile web add "github:caoyiwei850/dsh-ssh-ops#6fdd0c33869dd9824860eb6295574736b8360634"
   dsh plugin --profile web add "github:lycheelink/dsh-skill-manager.git#f3703dca136bab14032dd5e1ae7d5754bbef7e1a"
   dsh plugin --profile web add "@lycheelink/dsh-workbench"

   插件清单与选择建议见 §5.3；--profile web 的位置有讲究（见 §5.2）。

3. 启动在目标工作区目录

   sh

   cd ~/your-project
   dsh web

4. 打开界面复制完整地址

   text

   dsh web: http://127.0.0.1:3080/?token=xxxxxxxxxx

   必须复制包含 ?token= 的完整地址在浏览器打开；手动输入 127.0.0.1:3080 将返回 401（见 §3.2）。

安装与使用五条守则：

1. 安装时须显式指定版本号 0.1.5-rc.1。当前版本迭代频繁且不稳定，请勿安装默认最新版（见 §2.1）；
2. 使用启动日志中打印的、带 ?token= 的完整地址访问，勿自行拼接地址（见 §3.2）；
3. 安装或卸载插件后须重启 dsh web，仅刷新浏览器不起作用；
4. 插件安装后须以命令验证其已加载，不能仅以安装无报错为准（见 §5.5）；
5. 安装插件须锁定版本：npm 包指定精确版本号，GitHub 包附 # 加 commit 哈希。软件处于 0.1.x 预览阶段，版本间兼容性无法保证。

1.1Node.js 版本

版本检查：

node -v     # 需 v22.19+ 或 v24+
npm -v

版本不符请先升级 Node（建议使用 nvm 或官方安装包）。

1.2网络要求

安装过程需联网访问 npm 与 GitHub。建议预先配置 npm 镜像源，否则可能因网络延迟导致安装缓慢或超时。

1.3安装前检查清单

2.1全局安装（推荐）

npm install -g @deepseek-ai/dsh@0.1.5-rc.1

安装成功时，终端末尾输出类似 added 523 packages in 7m。首次安装约需数分钟，耗时较长属正常现象，期间请勿中断。

安装完成后请核对版本号，确认实际安装版本为 0.1.5-rc.1：

dsh --version
# 预期输出：0.1.5-rc.1
# 若版本不符，说明未锁定，请重新执行安装命令

2.2临时体验（不想装进系统）

npx @deepseek-ai/dsh@0.1.5-rc.1 web

该方式按需下载，不写入全局环境，仅适合临时试用：每次执行均需联网解析，且后续插件安装命令较长。如需长期使用，建议采用 §2.1 的全局安装方式（同样须指定版本号）。

2.3卸载

npm uninstall -g @deepseek-ai/dsh

3.1启动

cd ~/your-project      # 该目录即默认工作区
dsh web                # 默认地址 http://127.0.0.1:3080，并自动打开浏览器

常用参数：

3.2必须使用启动日志输出的地址访问

启动后，终端会打印类似如下一行：

dsh web: http://127.0.0.1:3080/?token=EXE40B9n8zI6Aq4QwWsvwyXlrCYzsuUaxSySblgtLHY

请复制该完整地址在浏览器中打开。 若直接输入 http://127.0.0.1:3080，将返回 401 — dsh web authentication required; reopen the URL printed by dsh web.。要点：

• 该 token 在首次访问时兑换为浏览器 Cookie，有效期 30 天；
• Cookie 与「地址 + 端口」绑定。若更换端口或使用其他域名/IP 访问，将再次返回 401，此时重新复制启动日志中的地址即可；
• 每次重启 dsh web 都会签发新的 token，原有地址随之失效；
• 使用 --no-open 时不会自动打开浏览器，需手动复制地址。

3.3首次使用的三步配置

1. 内测声明：首次打开会弹出内测声明，点击「继续」即可；
2. 填 API Key：于 Settings → Models 的 DeepSeek 卡片中填入 Key（前往 platform.deepseek.com 创建），保存后立即生效，无需重启；
3. 选工作区：在首页 Choose workspace 中选定一个目录，方可开始对话。

如需使用其他模型服务，可在 Settings → Models 中添加自定义提供方，支持任意 OpenAI 兼容接口。

4.1工作区

• 启动时的当前目录即为默认工作区，亦可在界面中随时切换；
• 切换项目时，建议在对应目录下启动 dsh web。

4.2数据都存在哪

可通过设置 DSH_HOME 环境变量，将整个数据目录迁移至其他路径：

export DSH_HOME=/path/to/your/dsh-home

4.3关闭与重启

• 关闭：在运行 dsh web 的终端中按 Ctrl + C；
• 重启：安装或卸载插件后必须重启方可生效（仅刷新浏览器无效）。

5.1安装规则

1. 锁定版本：npm 包指定精确版本（如 dsh-at-file@0.6.3），GitHub 包附 commit 哈希；
2. 安装完成后须重启 dsh web；
3. 安装后须验证（§5.5）。命令执行无报错并不等同于插件已生效。

5.2常用命令

5.3推荐插件

推荐安装（低风险）

按需安装

运维类

5.4批量安装

可将待安装插件写入清单文件 ~/dsh-plugins.list（以 # 开头的行视为注释）：

dsh-plugin-check@0.1.0
dsh-at-file@0.6.3
dsh-session-health@0.6.0
dsh-knowledge-base@0.1.5
github:omdsh-dev/dsh-paste-input#cc02be15

使用以下命令批量安装：

while read -r p; do
  [ -z "$p" ] && continue
  case "$p" in \#*) continue;; esac
  echo "→ $p"
  dsh plugin --profile web add "$p" </dev/null
done < ~/dsh-plugins.list

全部安装完成后，统一重启一次 dsh web，再按 §5.5 验证。

5.5验证插件真的生效

建议通过以下三个层面逐级验证：

# 1) 依赖层：包是否进入依赖清单
cat ~/.dsh/profiles/web/package.json

# 2) 装配层（最关键）：是否进入最终加载树
dsh --profile web --dump-config | grep -n "dsh-knowledge-base"

# 3) 功能层：于 Web UI 中人工确认
#    知识库 → 侧边栏出现入口；@ 文件 → 输入框可检索到文件；粘贴 → Ctrl+V 可贴入图片

6.1前置：装好技能管理器

dsh plugin --profile web add "github:lycheelink/dsh-skill-manager.git#f3703dca136bab14032dd5e1ae7d5754bbef7e1a"

安装完成后须重启 dsh web（所有插件均须重启，见 §5.1）。重启后进入 设置 → 技能管理，即可查看当前已加载的技能列表。

6.2准备技能 ZIP

技能仓库大多托管于 GitHub 之外的平台，而插件内置的「GitHub 技能市场」仅支持 github.com 源，因此安装 GitCode 上的技能须采用 ZIP 方式。

GitCode 网页支持将技能目录直接导出为 ZIP，无需手动打包：

1. 浏览器打开技能目录页，例如 https://gitcode.com/Ascend-SACT/ling/tree/main/skills/model-oob-perf-optimize/；
2. 点击右上角的「下载当前目录」按钮（位于「下载 zip」左侧）；
3. 下载得到 ling-main-skills-model-oob-perf-optimize.zip，无需解压或修改目录结构即可用于安装（经实测无需登录，匿名亦可下载）。

该压缩包解压后的目录结构如下（外层额外嵌套两级路径，不影响安装）：

ling-main-skills-model-oob-perf-optimize/     ← GitCode 自动加的外层：仓库-分支-路径
└── skills/
    └── model-oob-perf-optimize/              ← 插件就装这一层
        ├── SKILL.md                          ← 技能入口，缺了它装不上
        ├── README.md
        ├── asset/  design/  references/
        ├── scripts/  sdd/  system_validation/
        └── test/

为何此结构可被正确识别：插件以「包含 SKILL.md 的目录」作为技能根目录进行定位，外层嵌套层级无关紧要，技能名称取该目录名。经实测，将 GitCode 下载的原包直接导入后，技能名正确解析为 model-oob-perf-optimize，897 个文件完整落盘，asset、design、references、scripts、sdd、system_validation、test 等子目录均完整保留。

备选方案：页面未提供下载按钮时

部分页面可能不提供该按钮，此时可通过命令行获取（以 ling 仓库为例）：

# 浅克隆并稀疏检出，仅获取该技能目录
git clone --depth 1 --filter=blob:none --sparse https://gitcode.com/Ascend-SACT/ling.git
cd ling
git sparse-checkout set skills/model-oob-perf-optimize

# 进入 skills/ 打包，确保 ZIP 根目录下即为技能目录
cd skills && zip -r model-oob-perf-optimize.zip model-oob-perf-optimize

Windows 环境请使用以下命令替代：

Compress-Archive -Path model-oob-perf-optimize -DestinationPath model-oob-perf-optimize.zip

6.3在页面里安装

1. 于 DSH 页面进入 设置 → 技能管理；
2. 在 ZIP 安装 区块点击「选择 ZIP 文件…」；
3. 选中刚下载的 ling-main-skills-model-oob-perf-optimize.zip，等待按钮状态变为「已安装」；
4. 列表中随即出现 model-oob-perf-optimize，状态为「已启用」。

技能文件保存于 ~/.dsh/skills/model-oob-perf-optimize/，DSH 会自动识别，无需重启（仅插件需要重启）。

6.4日常管理

6.5注意事项

• 重复安装不会覆盖：同名技能已存在时，安装将被跳过并提示冲突，内容不会更新。如需升级，须先删除 ~/.dsh/skills/<技能名>/，再重新安装。
• GitHub 技能市场不支持 GitCode 源：该功能仅按 github.com 地址拉取，填入 GitCode 仓库坐标将无法检索到内容。来自 GitCode / Gitee 等平台的技能一律采用上述 ZIP 方式安装。

- insert:
    - id: mcp-eval-suite
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: eval-suite
        transport: streamable-http
        url: http://127.0.0.1:8900/mcp
        failOnStartupError: false

• 新条目须以 insert: 包裹，否则会报 patch: entry not found；
• 修改后重启 dsh web；
• 接入后工具名称形如 mcp__<server>__<tool>。

8.1原生模块被拦截（ERR_PNPM_IGNORED_BUILDS）

安装含原生模块的插件（如 dsh-better-sidebar）时可能出现，处理方法如下：

cat >> ~/.dsh/profiles/web/pnpm-workspace.yaml <<'EOF'

allowBuilds:
  node-pty: true
EOF

# 随后重新执行安装命令
dsh plugin --profile web add dsh-better-sidebar@0.18.1

8.2「暂时无法保存确认状态，请重试。」

该报错出现在点击内测声明弹窗「继续」时（与 API Key 保存无关）。多数情况下状态已成功写入，刷新页面即可。按以下顺序排查：

cat ~/.dsh/settings.yaml

• 服务仅监听 127.0.0.1，外部无法访问；
• 访问需提供启动 token（§3.2）；
• 但该 token 为单一共享值，无用户名/密码，亦无操作审计。

需重点保护的文件：

备份（node_modules 无需备份，重装即可恢复）：

tar czf ~/dsh-backup-$(date +%Y%m%d).tar.gz \
  ~/.dsh/.credentials.yaml \
  ~/.dsh/profiles/web/cordis.patch.yml \
  ~/.dsh/profiles/web/package.json

命令速查

dsh --version                                   # 查看版本
dsh web                                         # 启动（默认 3080）
dsh web --port 3081 --no-open                   # 换端口且不自动打开浏览器
dsh plugin --profile web add <包>@<版本>          # 安装插件
dsh plugin --profile web remove <包>             # 卸载插件
dsh plugin --profile web list                    # 查看已安装插件
dsh --profile web --dump-config                  # 查看最终加载内容