一、它是什么

dsh_setup 是 DeepSeek Harness 的外层引导器，不是 dsh 官方产物，也不修改 dsh 任何代码。它的定位是：

在官方两条路径（npx 发布包 / pnpm 源码构建）之上，补一个"环境→模式→端口→Key→健康"的收口层，让你永远只需要敲一条命令。

官方两条路径 vs 本工具

# 官方 npm 快速体验
npx @deepseek-ai/dsh web

# 官方源码构建
git clone https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness && pnpm install && pnpm run build && pnpm dsh web

# 本工具（一条命令覆盖以上两种）
bash dsh_setup.sh

二、部署流程

2.1 前置条件

平台 必需 推荐 说明
macOS Node.js ≥ 22.19 nvm + 终端 原生体验最佳
Linux Node.js ≥ 22.19 nvm 同 macOS 逻辑
Windows WSL2 或 Git Bash WSL2 WSL2 下体验与 macOS 一致

Node.js 版本要求：官方 engine 锁定 >=22.19.0 或 >=24。低于此版本脚本会直接报错退出。
pnpm：源码模式需要 >=11.7.0，脚本会自动通过 corepack enable 或 npm i -g pnpm 安装。
Git：源码克隆模式需要 >=2.26，npm 模式非必需。

2.2 下载

# 方式1: 直接下载两个文件
curl -O https://your-domain/dsh_setup.sh
curl -O https://your-domain/dsh_setup.bat

# 方式2: 克隆本仓库
git clone <repo-url> dsh-setup
cd dsh-setup

2.3 Windows 额外一步

:: 安装 WSL2（管理员 CMD 或 PowerShell）
wsl --install
:: 重启后，进入项目目录双击 dsh_setup.bat 即可

.bat 文件会自动按以下优先级分流：

  1. 有 WSL2 → 转发到 WSL 内执行 bash dsh_setup.sh（最佳路径）
  2. 有 Git Bash → 用 C:\Program Files\Git\bin\bash.exe 执行
  3. 都没有 → 打印三种方案指引后退出

三、启动流程

3.1 八步全自动

Step 1/8  检测 Node.js (>=22.19 或 >=24)
           │
           ├─ 已装且达标 → ✅ 继续
           └─ 未达标 ─┬─ DSH_AUTO_INSTALL_NODE=1 → nvm install 24
                      └─ 未设 → 打印安装命令 → 退出

Step 2/8  检测 pnpm (>=11.7)
           │
           ├─ 已有 → ✅
           └─ 缺失 → corepack enable → 失败则 npm i -g pnpm

Step 3/8  检测 Git (>=2.26)
           │
           └─ 缺失 → 仅警告（npm 模式可继续）

Step 4/8  判定运行模式
           │
           ├─ DSH_USE_NPM=1          → npm 模式
           ├─ cwd 含 pnpm-workspace.yaml + packages/core → 源码模式
           ├─ DSH_CLONE=1           → 克隆到 ~/.dsh-src/ → 源码模式
           └─ 其他                   → npm 模式

Step 5/8  检测端口 (DSH_PORT 默认 3080)
           │
           └─ 占用 → 自动 +1，连续 10 个被占则报错退出

Step 6/8  启动 + 等待就绪 (最多 60s)
           │
           ├─ 源码模式: pnpm install(可选) → pnpm run build → pnpm dsh web
           ├─ npm 模式:  npx --yes @deepseek-ai/dsh[@version] web
           └─ curl /health 或 / → 200 后打开浏览器

Step 7/8  健康检查 & 日志诊断 (DSH_HEALTH_CHECK=1 时)
           │
           ├─ curl /health → 失败则 WARN
           └─ 扫描日志 6 类关键字 → 输出"人话"翻译

Step 8/8  API Key 引导
           │
           ├─ 已有 ~/.dsh/.credentials.yaml → 校验权限 600 → 跳过
           └─ 不存在 → 终端静默收 Key → 格式校验 → 写文件 600

3.2 真实启动输出（Mac mini 实测）

===> Step 1/8 — 检测 Node.js
[ OK ]  Node.js v26.5.0 (>= 22.19.0 ✓)

===> Step 2/8 — 检测 pnpm
[INFO]  尝试 corepack enable 启用 pnpm...
[ OK ]  pnpm 已通过 corepack 启用

===> Step 3/8 — 检测 Git
[ OK ]  Git 2.50.1 (>= 2.26.0 ✓)

===> Step 4/8 — 判定运行模式
[INFO]  未检测到源码 → npm 模式 (npx @deepseek-ai/dsh web)

===> Step 5/8 — 检测端口 3080
[ OK ]  使用端口: 3080

===> Step 6/8 — 启动 DeepSeek Harness
[INFO]  使用最新 rc 版本
[INFO]  启动: npx --yes @deepseek-ai/dsh web --port 3080
[INFO]  等待 dsh 在端口 3080 就绪 (最多 60s)...
[ OK ]  dsh 已就绪 (3s)
[ OK ]  已打开浏览器 → http://127.0.0.1:3080

===> Step 7/8 — 健康检查 & 日志诊断
[ OK ]  健康检查接口响应正常
[ OK ]  日志未见明显异常

===> Step 8/8 — DeepSeek API Key 引导
[ OK ]  凭据已存在: /Users/ms/.dsh/.credentials.yaml (跳过)

✅ DeepSeek Harness 启动完成
   URL:     http://127.0.0.1:3080
   PID:     99050
   Log:     /tmp/dsh_3080.log
   停止:    kill $(cat /tmp/dsh_3080.pid)

3.3 典型场景速查

场景 命令
最简启动（推荐） bash dsh_setup.sh
源码目录快速重启 DSH_SKIP_DEPS=1 bash dsh_setup.sh
锁版本（稳定用） DSH_PIN_VERSION=0.1.0-rc.6 bash dsh_setup.sh
全自动首次安装 DSH_AUTO_INSTALL_NODE=1 DSH_CLONE=1 bash dsh_setup.sh
强制 npm 模式 DSH_USE_NPM=1 bash dsh_setup.sh
指定端口 DSH_PORT=4000 bash dsh_setup.sh
关闭健康检查 DSH_HEALTH_CHECK=0 bash dsh_setup.sh
Windows 用户 双击 dsh_setup.bat 或在 CMD 中 dsh_setup.bat

3.4 环境变量速查

变量 默认 作用 风险
DSH_PORT 3080 Web UI 端口 无
DSH_USE_NPM 0 强制 npm 模式（即使 cwd 是源码） 无
DSH_SKIP_DEPS 0 跳过 install + build（快速重启） 代码改了不生效
DSH_PIN_VERSION （空） 锁 npm 版本号，如 0.1.0-rc.6 需手动跟随更新
DSH_AUTO_INSTALL_NODE 0 自动 nvm 装 Node 24 改 ~/.nvm
DSH_CLONE 0 自动 clone 官方仓库到 ~/.dsh-src/ 首次拉几百 MB
DSH_HEALTH_CHECK 1 启动后自动健康检查 + 日志诊断 无

⚠️ 三个"自动改系统"的开关（DSH_AUTO_INSTALL_NODE / DSH_CLONE）默认全部关闭，避免脚本擅自修改用户环境。按需开启。

四、与官方的差别（14 维对照）

维度 官方 npx dsh web 官方源码 pnpm dsh web dsh_setup.sh v9
Node 校验 报错才知 报错才知 启动前精确校验 ≥22.19
pnpm 安装 不涉及 用户自装 corepack→npm 兜底
Git 检测 不涉及 不涉及 检测版本 + 缺失警告
模式选择 手动 手动 cwd 自动判定（源码/npm/clone）
端口冲突 EADDRINUSE 崩溃 同左 自动 +1 避让，连续 10 个才报错
Key 录入 Web UI 手填 同左 终端静默收 + 格式校验（sk- 前缀 + 长度≥20）
凭据存储 ~/.dsh/.credentials.yaml 同左 同左 + 目录 700 + 文件 600 + 权限自动修正
健康检查 无 无 curl /health + 6 类日志关键字人话翻译
版本锁定 追 latest rc 跟 git DSH_PIN_VERSION 可锁任意 rc
自动更新 npx 每次拉新 rc 不更新 非源码模式同 npx；源码模式跟 git pull
Windows 裸跑易踩坑 更难 .bat → WSL2 桥接 / Git Bash 兜底
停止服务 手找 pid 同左 pid 文件 + 一行 kill / taskkill
输出可读 终端日志堆砌 同左 分步 [OK]/[INFO]/[WARN]/[ERR] 中文标签
学习成本 看 README 看 README + 装依赖 一条命令，零决策

五、好处总结

  1. 零决策启动：一条命令覆盖"体验"和"二开"两种路径，脚本自动判定
  2. 环境自检：Node/pnpm/git 版本不对立刻报错并给安装命令，不浪费时间
  3. 端口自治：3080 被占自动让位，不崩不卡
  4. Key 安全收口：终端静默输入 + 目录 700 + 文件 600 + 格式校验 + 重复写入防护 + 权限自动修正
  5. 健康可观测：启动后自动 curl + 扫日志，白屏前就告诉你哪里炸了（6 类错误人话翻译）
  6. 跨平台统一：macOS/Linux/WSL2 一份 bash 逻辑，Windows 用户零学习成本
  7. 不入侵 dsh：不改官方代码、不 fork、不锁版本，纯粹外层引导，官方更新无感知

六、安全说明

6.1 存储机制

项目 值
存储位置 ~/.dsh/.credentials.yaml
目录权限 700（仅 owner 可进入）
文件权限 600（仅 owner 可读写）
内容格式 api_key: "sk-..." 明文
Key 校验 必须以 sk- 开头，长度 ≥ 20 位
权限修正 已有文件权限非 600 时自动 chmod 600

6.2 安全等级

场景 是否安全 说明
单机自用 + 600 权限 ✅ 合理 等同 SSH 私钥保护级别
Time Machine 备份 ⚠️ 需排除 脚本会检测并提示 tmutil addexclusion -p ~/.dsh
iCloud / Dropbox 同步 ⚠️ 不建议 明文进云端快照
多用户同一台 Mac ✅ 安全 600 防其他 Unix 用户读
同用户态恶意程序 ❌ 无法防 浏览器插件 / 来路 npx 包可读（单机模型边界）
Windows NTFS ⚠️ 模拟 Git Bash 的 chmod 是模拟，dsh 读文件不校验 Unix 位，不影响使用

6.3 与官方的关系

dsh 官方自己也把 Key 写进 ~/.dsh/.credentials.yaml，本脚本只是提供了"终端入口版"的同等写入——不冲突、更新不丢 Key。npm 包更新不会动 ~/.dsh/ 下的用户数据。

6.4 安全边界声明

chmod 600 防的是"其他用户/进程读文件"，不防"已经以你身份运行的恶意程序"。这是单机单用户模型的天然边界，不是 yaml 的缺陷。追求更高安全请用 macOS Keychain + 环境变量注入（需自行写 Cordis 插件）。

七、适用人群

人群 推荐用法 推荐配置
Agent 应用开发者 改 Cordis 插件后快速重启 源码目录 + DSH_SKIP_DEPS=1
快速体验者 不想装 pnpm/git，只想看 UI 默认 npm 模式
内容 / 教程作者 结构化输出方便截图贴文 默认即可
Windows 团队 和 Mac 同事同套流程 WSL2 + dsh_setup.bat
CI / CD 验证 起 headless 前哨做自动化测试 DSH_USE_NPM=1 DSH_SKIP_DEPS=1

八、已知限制

  1. 不自动装 Node 本体：DSH_AUTO_INSTALL_NODE 默认关，避免脚本擅自改用户系统
  2. 不自动 clone 仓库：DSH_CLONE 默认关，避免未经同意拉取几百 MB
  3. rc 包升级可能破坏 schema：开发者预览期 .credentials.yaml 格式可能变，建议 DSH_PIN_VERSION 锁版
  4. NTFS 下 chmod 是模拟：Git Bash 中不提供真实 DAC 权限，但 dsh（Node 程序）读 yaml 不校验 Unix 位，不影响使用
  5. 裸 Windows 不推荐：rc 版部分 Cordis 插件依赖 POSIX PTY，WSL2 / Linux VM 才稳
  6. 健康检查是启发式：curl /health + 日志关键字匹配，不能覆盖所有错误类型

九、停止服务

# macOS / Linux / WSL2
kill $(cat /tmp/dsh_3080.pid)

# Windows (Git Bash)
taskkill //PID $(cat /tmp/dsh_3080.pid) //F

# Windows (CMD / PowerShell)
taskkill /PID <pid> /F

端口号随 DSH_PORT 变化，如指定了 4000，则 pid 文件为 /tmp/dsh_4000.pid。

十、版本迭代记录

版本 核心变更
v1.0 基础 npx @deepseek-ai/dsh web 包装
v3.0 依赖自动检测与安装
v5.0 Node/pnpm/git 环境检测 + 源码/npm 模式自动判定
v6.0 三个可选开关（AutoInstallNode / Clone / PinVersion）默认关闭
v7.0 启动后自动 curl 健康检查 + 6 类日志错误人话翻译
v8.0 目录 700 + 文件 600 + Key 格式校验 + Time Machine 排除提示
v9.0 跨平台：平台探测 + Windows .bat 入口（WSL2 转发 / Git Bash 兜底）

License

MIT

# dsp开发
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

Ox Alpha 模型火爆全网，完全免费使用，开发者狂喜，附使用教程

avatar DeepSeek技术社区
cover

DeepSeek涨价你换了吗：不算价格账，算算迁移工程这本账

avatar DeepSeek技术社区

1M 上下文 0.10 入场:5 模型长文档屠夫榜

本文针对2026年Q3长文档处理场景，对比分析了5款支持1M上下文的AI模型（DeepSeek-V4-Flash、Kimi-K2.5、GLM-5.1、Qwen3.6-Max-Preview、Claude-Sonnet-4-6）在成本、性能和适用场景上的表现。文章通过实际案例（21万字合同处理）展示了1M上下文直灌相比传统RAG切片方案的成本优势（从50美元降至0.02美元），详细介绍了各模型的定价

avatar DeepSeek技术社区