1. 检查 Node.js#

DSH 要求：

1
Node.js ^22.19.0 或 >=24.0.0

先检查当前版本：

1
node -v
2
npm -v
3
which node

如果尚未安装 Node.js，在 macOS 上可以使用 Homebrew：

1
brew install node

如果已经通过 Homebrew 安装了旧版本：

1
brew upgrade node
2
brew cleanup node

再次确认：

1
node -v

本文验证时使用的是 v26.7.0。Node 23 不在 DSH 支持范围内，不要忽略这一点。

2. 准备 DeepSeek API Key#

前往 DeepSeek 开放平台创建 API Key。安装过程中不要把密钥写进项目仓库，也不要直接贴进公开日志。

可以先临时导出：

1
export DEEPSEEK_API_KEY="你的 API Key"

稍后会把它保存到 DSH 自己的配置目录，并限制文件权限。

3. 处理 npm 镜像#

如果本机 npm 使用第三方镜像，安装 @deepseek-ai/* 包时可能遇到 403、包不存在或下载中断。

本文所有核心安装命令都显式使用 npm 官方源：

1
https://registry.npmjs.org/

不需要永久修改全局 npm 配置。

1. 安装固定版本#

1
npm install -g @deepseek-ai/dsh@0.1.1-rc.2 \
2
  --registry https://registry.npmjs.org/

验证：

1
which dsh
2
dsh --version

预期输出：

1
/opt/homebrew/bin/dsh
2
0.1.1-rc.2

2. 初始化 Web profile#

执行一次配置导出即可初始化 ~/.dsh/profiles/web，无需先常驻启动服务器：

1
dsh web --dump-default-config > /tmp/dsh-default-config.yml

检查目录：

1
ls -la ~/.dsh/profiles/web

正常情况下会看到：

1
cordis.patch.yml
2
cordis.yml
3
package.json
4
pnpm-workspace.yaml

3. 保存 API Key#

1
umask 077
2
printf 'DEEPSEEK_API_KEY=%s\n' "$DEEPSEEK_API_KEY" > ~/.dsh/.env
3
chmod 600 ~/.dsh/.env

验证权限：

1
ls -l ~/.dsh/.env

文件权限应为 -rw-------。

DSH 也支持托管凭据文件 ~/.dsh/.credentials.yaml。无论采用哪种方式，都不要把密钥写进工作区的 .env 后提交到 Git。

1. 允许受信任插件执行构建脚本#

部分 Git 插件带有 prepare 脚本。pnpm 默认会阻止执行，并报：

1
ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED

编辑：

1
~/.dsh/profiles/web/pnpm-workspace.yaml

写入以下完整内容：

1
packages:
2
  - .
3

4
nodeLinker: hoisted
5
autoInstallPeers: false
6

7
allowBuilds:
8
  dsh-better-sidebar: true
9
  dsh-at-file: true
10
  dsh-open-in-vscode: true
11
  dsh-notification: true
12
  dsh-usage-stats: true
13
  dsh-memento: true
14

15
onlyBuiltDependencies:
16
  - dsh-better-sidebar
17
  - dsh-at-file
18
  - dsh-open-in-vscode
19
  - dsh-notification
20
  - dsh-usage-stats
21
  - dsh-memento

只为明确审查并准备安装的包开放脚本，不要使用全局的”允许全部脚本”设置。

2. 逐个安装并验证#

不要一次粘贴六条命令后离开。每安装一个插件，都执行一次 --dump-config。这样如果组合树损坏，可以准确知道最后一个变更是什么。

1
dsh plugin --profile web add \
2
  "github:omdsh-dev/DSH-better-sidebar#d9b8f15d9eab018742f97d67e54b2398504894cd"
3

4
dsh web --dump-config | grep -i better-sidebar

1
dsh plugin --profile web add \
2
  "github:FSMargoo/dsh-at-file#c37b0ed9e8bf3585bf9f272462dcf01886efe2a3"
3

4
dsh web --dump-config | grep -i dsh-at-file

1
dsh plugin --profile web add \
2
  "github:omdsh-dev/dsh-open-in-vscode#8aed144abdc158a332aa73bce42fc217d962f751"
3

4
dsh web --dump-config | grep -i open-in-vscode

1
dsh plugin --profile web add \
2
  "github:omdsh-dev/dsh-notification#ddec603395a223deb46c75b74274c41849c6a131"
3

4
dsh web --dump-config | grep -i dsh-notification

1
dsh plugin --profile web add \
2
  "github:Ychris12138/dsh-usage-stats#7c88a445b73f78af7df6082fd671d22a293acb6d"
3

4
dsh web --dump-config | grep -i usage-stats

1
dsh plugin --profile web add \
2
  "github:PerryLink/dsh-memento#ee198efd71dc60f5cd1cd2019e20c63028d2d182"
3

4
dsh web --dump-config | grep -i memento

3. 检查最终组合#

1
dsh plugin --profile web list
2
dsh web --dump-config > /tmp/dsh-web-config.yml

检查 bundle 列表：

1
python3 - <<'PY'
2
import json
3
from pathlib import Path
4

5
profile = Path.home() / ".dsh/profiles/web/package.json"
6
bundles = json.loads(profile.read_text())["dsh"]["profile"]["bundles"]
7
for bundle in bundles:
8
    print(bundle)
9
PY

最终应包含：

1
@deepseek-ai/dsh-base
2
@deepseek-ai/dsh-web-app
3
dsh-better-sidebar
4
dsh-at-file
5
dsh-open-in-vscode
6
dsh-notification
7
@ychris12138/dsh-usage-stats
8
dsh-memento

1. 启动 Web 工作台#

1
dsh web

默认地址：

1
http://127.0.0.1:3080

如果不希望自动打开浏览器：

1
dsh web --no-open

端口被占用时：

1
dsh web --port 3081

默认只监听 127.0.0.1，不会向局域网暴露。不要为了手机访问直接改成 0.0.0.0；远程访问应额外配置认证和 HTTPS。

2. 第一次创建工作区#

打开页面后：

1. 选择一个真实 Git 仓库作为 workspace；
2. 选择 DeepSeek provider 和模型；
3. 日常编码优先选择 Standard 或 PTC；
4. 先执行一个只读任务验证工具链。

例如：

1
列出当前仓库前 10 个文件，并说明项目使用的语言和构建工具。不要修改文件。

确认文件读取和工具调用正常后，再让 Agent 修改代码。

3. 使用 @file#

在输入框输入 @，搜索并选择工作区文件，然后继续描述任务：

1
@src/app.ts 分析这个入口的错误处理路径，只分析，不修改。

明确引用文件比只写模糊文件名更可靠，也能减少 Agent 在大仓库里无目的搜索。

4. 使用侧栏#

Better Sidebar 提供文件、编辑器、终端、Git 和子代理视图。

建议分工：

• 小范围查看和快速编辑留在 Web 工作台；
• 复杂 diff、重构和手工审查通过 Open in VS Code / Cursor 打开；
• Git 推送、删除分支等高风险操作仍由人确认。

不要再叠加第二套侧栏或 web-ui-all。多个插件争用相同 UI slot 是最常见的页面异常来源之一。

5. 使用记忆#

Memento 不应被当成”自动保存所有聊天”的黑箱。只保存稳定、可复用的信息，例如：

• 个人编码偏好；
• 项目的长期约定；
• 经验证的构建和测试命令；
• 需要跨会话保留的架构决策。

不要保存：

• API Key、Token 和密码；
• 临时任务进度；
• 未验证的技术推断；
• 很快会过期的日志内容。

首次使用时先保存一条无敏感信息的偏好，然后新建会话验证能否召回。

6. 查看用量与通知#

用量统计插件用于观察：

• 输入、输出和缓存 Token；
• 会话成本；
• Provider 余额或配额；
• 不同模型的使用差异。

通知插件需要浏览器授予通知权限。可以启动一个短任务，切到其他窗口，确认任务完成后是否收到通知。

7. 使用 TUI#

在终端运行：

1
dsh --profile dsh-tui

恢复会话：

1
dsh --profile dsh-tui --resume

Web 和 TUI 可以共享 DSH 的基础配置与会话目录，但拥有独立的 profile 组合。不要为了”配置统一”把两个 bundle 合并。

8. 停止服务#

前台运行时按：

1
Ctrl+C

如果此前把 Web 服务放到后台，先找到进程：

1
pgrep -af "dsh.*web"

确认 PID 后再结束对应进程，不要使用模糊的 killall node，否则会误杀其他 Node 服务。

1. 版本#

1
node -v
2
npm -v
3
dsh --version

2. 配置树#

1
dsh web --dump-config > /tmp/dsh-web-config.yml
2
dsh --profile dsh-tui --dump-config > /tmp/dsh-tui-config.yml

两个命令都必须以退出码 0 结束。

3. HTTP 服务#

启动 Web 后执行：

1
curl -sS -o /dev/null \
2
  -w 'HTTP %{http_code}\n' \
3
  http://127.0.0.1:3080/

预期：

1
HTTP 200

4. 功能#

• @file 能搜索并引用工作区文件；
• 侧栏能打开文件、Git 和终端；
• Open in VS Code / Cursor 能打开当前 workspace；
• 任务完成后能收到浏览器通知；
• Usage Stats 能显示用量；
• Memento 能保存并跨会话召回一条已批准记忆；
• TUI 能独立启动，Web profile 中没有 TUI bundle。

只有这些路径都走通，安装才算真正完成。

1. npm 返回 403#

使用 npm 官方源重试：

1
npm install -g @deepseek-ai/dsh@0.1.1-rc.2 \
2
  --registry https://registry.npmjs.org/

2. Git 插件拒绝执行 prepare#

错误：

1
ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED

把错误信息中给出的准确包名加入：

1
~/.dsh/profiles/web/pnpm-workspace.yaml

的 allowBuilds 和 onlyBuiltDependencies，然后重新执行安装命令。不要允许未知包运行安装脚本。

3. Web 启动时报 duplicate loader entry id#

根因通常是同一插件同时存在于：

• package.json 的 dsh.profile.bundles；
• cordis.patch.yml 的手工 insert。

先检查：

1
dsh web --dump-config
2
cat ~/.dsh/profiles/web/package.json
3
cat ~/.dsh/profiles/web/cordis.patch.yml

社区插件应保留在 bundle 中，并删除 patch 里重复的 insert。如果 patch 中有该插件的自定义配置，可以只保留按 id 覆盖的配置，不再 insert。

4. 删除插件后仍无法启动#

dsh plugin remove 只删除依赖，不一定清理手工 patch。

1
dsh plugin --profile web remove <package>

随后检查并删除 cordis.patch.yml 中对应的手工挂载。

5. 不要直接删除整个 ~/.dsh#

会话和配置都位于 ~/.dsh。Web profile 损坏时，应只重建 profile：

1
mv ~/.dsh/profiles/web \
2
  ~/.dsh/profiles/web.backup.$(date +%Y%m%d-%H%M%S)
3

4
dsh web --dump-default-config > /tmp/dsh-default-config.yml

这样可以保留 ~/.dsh/sessions 中的会话记录。

更新前备份#

1
cp ~/.dsh/profiles/web/package.json \
2
  ~/.dsh/profiles/web/package.json.backup
3

4
cp ~/.dsh/profiles/web/cordis.patch.yml \
5
  ~/.dsh/profiles/web/cordis.patch.yml.backup
6

7
dsh web --dump-config > ~/.dsh/web-config.backup.yml

更新原则#

1. 先阅读 DSH changelog；
2. 一次只更新核心或一个插件；
3. 每次更新后运行 --dump-config；
4. 不要让 Git 插件长期跟随 #main；
5. 核心 rc 变化后，先确认插件兼容性再升级。

本文使用的插件命令已经固定到具体提交。需要升级时，应先在插件仓库确认兼容版本，再替换提交哈希。

卸载插件#

1
dsh plugin --profile web remove <package>
2
dsh web --dump-config

卸载 DSH#

1
npm uninstall -g @deepseek-ai/dsh

该命令不会自动删除 ~/.dsh。确认不再需要会话和配置后，再手动归档或删除该目录。