从零打造 DeepSeek Harness 一键启动器

TL;DR — 本文记录了一个 bash 脚本从 30 行到跨平台可用的完整演进过程。它解决了什么问题？让 DeepSeek Harness 从"读 5 分钟 README + 踩 3 个坑"变成"一行命令 bash dsh_setup.sh"（Windows 双击 .bat）。背后是 9 轮迭代，每一轮都有明确动机、目标人群和实际收益。v9 把这条收口线从 macOS/Linux 拉平到 Windows(WSL2)，一份 bash 逻辑服务三端。

适用版本：DeepSeek Harness v0.1 developer preview（2026-08-13 发布，MIT，npm 包 @deepseek-ai/dsh 0.1.0-rc.x）
配套工具：dsh_setup.sh v9.0 + dsh_setup.bat + README.md
环境：macOS / Linux / Windows(WSL2) 统一可用

---

一、背景：DeepSeek Harness 是什么

2026 年 8 月 13 日，DeepSeek AI 开源了 DeepSeek Harness（dsh）——一个基于 TypeScript + Cordis 插件架构的 AI Agent 运行时。MIT 协议，开发者预览 v0.1。

核心主张 “Everything is a plugin”——模型、工具、agent-loop、session、sandbox、UI 全部是 Cordis 插件，可替换可卸载。当前是 developer preview，官方明说 “THERE WILL BE COMPATIBILITY-BREAKING CHANGES”，npm 包以 0.1.0-rc.x 滚动发布。

三种运行形态：

• Web UI（dsh web，默认 3080）
• Headless（dsh --profile headless "任务"）
• TUI（dsh --profile tui）

官方给出的启动方式只有两步：

# 方式 A：npm 快速体验
npx @deepseek-ai/dsh web

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

这两条命令本身没问题，但真实开发者第一次跑会撞上一堆"隐形门槛"：

隐形门槛	官方文档是否提及	实际踩坑率
Node.js 必须 ≥ 22.19	❌ 只说"装 Node"	极高
pnpm 必须 ≥ 11.7	❌ 未提版本	高
Cordis 插件架构概念	❌ 默认你懂	中
~/.dsh/.credentials.yaml 格式	部分	高
端口 3080 被占用	❌	中
rc 版本不稳定，UI 白屏	❌	高
API Key 怎么配	Web UI 里有	首次必问
3080 端口被占不会自动避让	❌	中
API Key 首次要手填 Web UI，没提示、没校验格式	❌	高

注：Windows 跨平台门槛（PowerShell 不认 &&、rc 版依赖 POSIX 终端等）已在 v9 通过 .bat→WSL2 桥接彻底解决，详见第四章。

这就是痛点：官方给的是"最小可用命令"，不是"开箱即用体验"。

dsh_setup 系列脚本的目标：把上面这些门槛收口成一个 bash dsh_setup.sh（Windows 双击 .bat），让"体验 dsh"和"研究 dsh 源码"都零决策。

---

二、目标人群画像

这个脚本不是给所有人用的，它精准服务于多类人：

🧑‍💻 类型 A：AI Agent 开发者

• 特征：想改 Cordis 插件、写自定义 Tool、调 Agent Loop
• 痛点：每次改代码要 pnpm run build 再重启，环境错了半天排查
• 需要：源码模式一键构建 + 快速重启（DSH_SKIP_DEPS=1 热重启）+ 错误前置发现

🧑‍🎓 类型 B：技术体验者 / 学习者

• 特征：看到新东西想快速试试，不想深究环境配置
• 痛点：README 里"装 Node、装 pnpm、配 Key"三步劝退
• 需要：bash dsh_setup.sh 一条命令搞定一切，失败了有清晰报错

✍️ 类型 C：技术内容创作者

• 特征：写教程、录视频、做 Demo
• 痛点：rc 版本每次跑结果不一样，读者复现不了
• 需要：版本锁定（DSH_PIN_VERSION）+ 可复现环境 + 诊断信息完整

🪟 类型 D：Windows 团队

• 特征：和 Mac 同事共用同一套工具链
• 痛点：希望 Windows 上也能开箱即用，不想手动配环境、不想学两套流程
• 需要：双击 dsh_setup.bat 即用，和 Mac 同事同套流程，一份 bash 逻辑三端跑

🤖 类型 E：CI 验证场景

• 特征：自动化起 headless 前哨做集成验证
• 需要：DSH_USE_NPM=1 DSH_SKIP_DEPS=1 bash dsh_setup.sh 起 headless 前哨

---

三、版本迭代全记录

v1.0 — 最小可用（30 行）

动机：第一次跑 npx @deepseek-ai/dsh web，浏览器打开了但页面空白。不知道是网络问题、Key 问题还是 dsh 挂了。

做了什么：

#!/bin/bash
npx --yes @deepseek-ai/dsh web --port 3080 &
sleep 3
open http://127.0.0.1:3080

能做什么：启动 + 开浏览器。
不能做什么：检测环境、处理错误、管理 Key。

一句话总结：能跑，但挂了不知道为什么。

---

v2.0 — 加入 API Key 引导

动机：每次清掉 ~/.dsh/ 后，Web UI 打开提示要填 Key，但界面上找"Settings → Models"对新手不直观。

核心改动：

# 检测凭据文件是否存在
CRED="$HOME/.dsh/.credentials.yaml"
if [[ ! -f "$CRED" ]]; then
    read -rs -p "DEEPSEEK_API_KEY: " KEY
    printf 'deepseek:\n  api_key: "%s"\n' "$KEY" > "$CRED"
    chmod 600 "$CRED"
fi

设计决策：

• 用 read -rs 静默收 Key，不进 shell 历史
• 写入后 chmod 600，等同 SSH 私钥保护级别
• 已有凭据则跳过，不重复交互

安全权衡：明文存盘 vs 用户体验。600 权限是"务实安全"的最优解——比 export KEY=xxx 安全，比 macOS Keychain 简单（dsh 也不支持 Keychain）。

---

v3.0 — 端口冲突处理

动机：第二次启动时，3080 被上次没杀掉的进程占着，报 EADDRINUSE。

核心逻辑：

PORT=3080
for try in 1 2 3 4 5; do
    if ! lsof -i ":${PORT}" >/dev/null 2>&1; then break; fi
    PORT=$((PORT + 1))
done

好处：用户无感知，脚本自动避让。

---

v4.0 — 等待就绪再开浏览器

动机：sleep 3 在慢机器上不够，快机器上浪费。白屏体验差。

核心改动：

for i in $(seq 1 60); do
    if curl -sf "http://127.0.0.1:${PORT}/" >/dev/null 2>&1; then
        echo "就绪 (${i}s)"; break
    fi
    sleep 1
done
open "http://127.0.0.1:${PORT}"

从"盲猜等待"升级为"HTTP 200 确认"，体验质变。

---

v5.0 — 环境三件套检测（Node / pnpm / Git）

动机：在 Mac mini 上帮朋友装，发现他 Node 是 18、没装 pnpm、Git 版本老。脚本一路报错但信息散落各处。

设计原则：检测 ≠ 自动修改系统。脚本只负责"说清楚缺什么 + 给安装命令"，不擅自 brew install。

例外：DSH_AUTO_INSTALL_NODE=1 时允许自动 nvm install 24，因为这是用户明确授权的行为。

# Node 检测
NODE_VER="$(node -v 2>/dev/null | sed 's/^v//')"
NODE_MAJOR="${NODE_VER%%.*}"
if [[ "$NODE_MAJOR" -lt 22 ]]; then
    echo "  brew install node"
    echo "  或 DSH_AUTO_INSTALL_NODE=1 bash dsh_setup.sh"
    exit 1
fi

关键决策：默认安全 vs 一键便利，用环境变量做开关，默认关。

---

v6.0 — 源码 / npm 双模式自动分流

动机：DeepSeek Harness 有两条运行路径：

1. npx @deepseek-ai/dsh web（npm 发布包，省事）
2. pnpm install && pnpm run build && pnpm dsh web（源码，可改插件）

官方让用户在两条命令间手动切换。我希望脚本能自动识别当前目录。

if [[ -f pnpm-workspace.yaml && -d packages/core ]]; then
    MODE="source"
    # pnpm install && pnpm run build && pnpm dsh web
else
    MODE="npm"
    # npx --yes @deepseek-ai/dsh web
fi

还加了三个可选开关：

开关	默认	作用
DSH_AUTO_INSTALL_NODE=1	off	自动 nvm 装 Node 24
DSH_CLONE=1	off	自动 clone 官方仓库
DSH_PIN_VERSION=0.1.0-rc.6	off	锁 npm 版本

设计哲学：默认零侵入，所有"自动改系统"的行为都需要用户显式开启。

---

v7.0 — 健康检查 & 日志人话翻译

动机：rc 版本的 dsh 经常"进程在跑但 UI 白屏"。用户看到白屏不知道是：

• Cordis 插件炸了？
• 端口被占？
• API Key 认证失败？
• 前端资源 404？

核心设计：启动后自动 curl /health + 扫描日志关键字，翻译成人话：

declare -A PATTERNS=(
    ["FATAL|uncaught"]="❌ 进程遇到无法恢复的错误"
    ["cordis.*error"]="⚠️ Cordis 插件异常，尝试 pnpm install + build"
    ["Cannot find module"]="⚠️ 依赖缺失，rm -rf node_modules && pnpm install"
    ["EADDRINUSE"]="❌ 端口冲突，DSH_PORT=3081"
    ["401|403.*api"]="⚠️ API Key 认证失败"
    ["404.*asset"]="⚠️ 前端资源缺失，锁版本 DSH_PIN_VERSION=0.1.0-rc.6"
)

效果对比：

# 没有健康检查：
浏览器白屏 → 用户懵 → 手动看日志 → grep 错误信息 → 搜索解决方案
（5-10 分钟）

# 有健康检查：
Step 6.5/8 — 健康检查 & 日志诊断
  ⚠️ Cordis 插件运行时异常，尝试 pnpm install + pnpm run build
    └─ [error] cordis plugin 'agent-loop' failed to load
（10 秒）

---

v8.0 — 安全收口（目录 700 + TM 排除）

动机：有用户反馈"我的 Time Machine 备份里能看到 API Key 明文"。

新增逻辑：

# 目录权限 700（之前只管了文件 600）
mkdir -p "$CRED_DIR"
chmod 700 "$CRED_DIR"

# Key 格式校验（之前只检查非空）
if [[ "$KEY" != sk-* ]]; then
    wrn "Key 格式异常 (应以 sk- 开头)"
elif [[ ${#KEY} -lt 20 ]]; then
    wrn "Key 长度不足 (当前 ${#KEY} 位)"
fi

# Time Machine 排除检测
if command -v tmutil >/dev/null 2>&1; then
    EXCLUDED=$(tmutil isexcluded "$CRED_DIR" 2>/dev/null)
    if [[ "$EXCLUDED" != *"[Excluded]"* ]]; then
        wrn "建议: tmutil addexclusion -p ${CRED_DIR}"
    fi
fi

安全等级对比：

方案	等级	说明
export KEY=sk-xxx	★☆☆☆☆	进 shell 历史 + 进程列表
文件 644	★★☆☆☆	同机其他用户可读
文件 600 + 目录 700（v8.0）	★★★★☆	等同 SSH 私钥，推荐
macOS Keychain	★★★★★	dsh 暂不支持

---

v9.0 — 跨平台兼容（Windows WSL2 桥接）

动机：v1–v8 只覆盖 macOS/Linux，Windows 用户被挡在门外。v9 把 Windows 纳入支持范围，通过 .bat 入口桥接到既有 bash 逻辑，无需重写第二份主逻辑，实现一份逻辑三端跑。

关键决策：不写第二份 PowerShell 主逻辑，而是让 Windows 入口 .bat 只做一件事——把控制权交给 WSL2 里的 bash 脚本。这样"一份逻辑，三平台跑"。

为什么选 WSL2 而不是纯 PowerShell 重写？

• 维护成本：bash 版 568 行，重写成 ps1 会漂移到两套逻辑
• 能力复用：WSL2 下 lsof/tmutil/chmod/open 全部原生可用，用户体验和 macOS 几乎一致

版本迭代脉络小结：

版本	解决什么	关键决策
v1	代替手敲 npx	写死 npx @deepseek-ai/dsh web
v3	依赖自动装	检测 requests/bs4（误用场景）→ 发现跑 dsh 不需要，删掉
v5	环境前置	检测 Node/pnpm/git，源码目录自动切 pnpm 模式
v6	三个开关	DSH_AUTO_INSTALL_NODE / DSH_CLONE / DSH_PIN_VERSION 默认 off
v7	健康检查	启动后 curl /health + 扫 log 翻成人话
v8	安全收口	目录 700 + 文件 600 + Key 格式校验 + TM 排除提示
v9	跨平台	平台探测 + Windows 走 WSL2 转发 + Git Bash 兜底

详细的跨平台设计见下一章。

---

四、跨平台兼容设计（v9 重点）

4.1 平台探测

脚本头部 uname -s 分支：

• Darwin → macos
• Linux → linux
• MINGW* / MSYS* / CYGWIN* → windows-bash
• 其他 → windows

4.2 三个系统调用按平台分派

能力	macOS/Linux	Windows (Git Bash)	Windows 裸 CMD
端口占用	lsof -i :3080	netstat -an | grep LISTEN	powershell Get-NetTCPConnection
开浏览器	open	start → powershell 兜底	powershell Start-Process
停进程	kill $(cat pid)	taskkill //PID	taskkill
权限	chmod 600/700 真生效	chmod 模拟（NTFS 不校验，但 dsh 读文件不卡）	n/a

4.3 Windows 入口 dsh_setup.bat 逻辑

where wsl >nul 2>&1
if %ERRORLEVEL%==0 (
    wsl bash -c "cd '$(wslpath '%CD%')' && bash dsh_setup.sh %*"
) else if exist "C:\Program Files\Git\bin\bash.exe" (
    echo 请用 Git Bash 运行: bash dsh_setup.sh
) else (
    echo 请装 WSL2: wsl --install
)

优先级：WSL2（最优体验）→ Git Bash（兜底可用）→ 提示装 WSL2。

4.4 Windows 平台差异说明

Windows 已完整支持，以下为跨平台实现上的客观差异（均不影响使用）：

• NTFS 上 chmod 600 是 Git Bash 模拟，不提供真实 DAC 权限，但 dsh（Node 程序）读 yaml 不校验 Unix 位，故不影响使用
• Time Machine 排除提示仅 macOS 生效，Windows 下自动跳过（Windows 用各自的备份机制）

---

五、架构全景图

┌─────────────────────────────────────────────────┐
│              用户执行一条命令                      │
│   macOS/Linux: bash dsh_setup.sh               │
│   Windows:     dsh_setup.bat → WSL2 bash        │
└────────────────┬────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────┐
│  Step 0: 平台探测层 🆕(v9)                      │
│  • uname -s 分支                                │
│  • Windows .bat → WSL2 / Git Bash 转发           │
└────────────────┬────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────┐
│  Step 1-3: 环境检测层                            │
│  • Node.js ≥ 22.19    (自动检测 + 安装提示)       │
│  • pnpm ≥ 11.7.0      (corepack → npm 兜底)     │
│  • Git ≥ 2.26         (源码模式必需)             │
└────────────────┬────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────┐
│  Step 4: 模式分流层                              │
│                                                 │
│   cwd 含 pnpm-workspace.yaml?                   │
│    ├─ 是 → 源码模式 (pnpm install + build)       │
│    └─ 否 → npm 模式 (npx @deepseek-ai/dsh)      │
│                                                 │
│   DSH_CLONE=1 → 自动 clone 到 ~/.dsh-src/       │
│   DSH_USE_NPM=1 → 强制 npm（即使有源码）         │
└────────────────┬────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────┐
│  Step 5: 端口管理层                              │
│  • 检测 3080 是否被占（平台分派 lsof/netstat）     │
│  • 占用自动 +1，最多试 5 次                      │
└────────────────┬────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────┐
│  Step 6: 启动 + 就绪等待                         │
│  • nohup 后台启动 dsh web                        │
│  • curl 轮询 HTTP 200（最多 60s）                │
│  • 就绪后自动 open 浏览器（平台分派 open/start）   │
└────────────────┬────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────┐
│  Step 6.5: 健康检查层                            │
│  • curl /health 端点                             │
│  • 扫描日志 6 类关键字                           │
│  • 输出"人话"翻译 + 修复建议                     │
└────────────────┬────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────┐
│  Step 7: 凭据管理层                               │
│  • 目录 700 + 文件 600                          │
│  • read -rs 静默收 Key                           │
│  • 格式校验 (sk- 开头 + ≥20 位)                 │
│  • TM 排除检测 + 提示（仅 macOS）                │
└────────────────┬────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────┐
│  Step 8: 输出摘要                                │
│  • URL / PID / Log / Cred 路径                   │
│  • 停止命令（平台分派 kill/taskkill）            │
│  • 安全提醒                                      │
└─────────────────────────────────────────────────┘

---

六、与官方方案的能力对照

维度	官方 npx dsh web	官方源码 pnpm dsh web	dsh_setup.sh v9
启动命令	1 条	1 条（需 cd）	1 条自动分流
Node 校验	报错才知	报错才知	启动前精确校验 ≥22.19
pnpm 安装	不涉及	用户自装	corepack→npm 兜底
Git 检测	未提及	未提及	版本校验 + 源码模式判定
模式选择	手动	手动	cwd 自动判（源码/npm）
端口冲突	直接 EADDRINUSE	同左	自动 +1
启动确认	无（盲猜）	无（盲猜）	HTTP 200 就绪检测
Key 录入	Web UI 手填	同左	终端静默收 + 格式校验（sk- + ≥20位）
凭据存储	~/.dsh/.credentials.yaml	同左	同左 + 700/600 + TM 提示
健康检查	无	无	curl /health + 6 类日志扫描
错误诊断	看日志自己 grep	同左	自动翻译 + 修复建议
版本锁定	追 latest rc	跟 git	DSH_PIN_VERSION 可锁
自动更新	npx 每次拉新 rc	不更新	非源码模式同 npx 行为
Windows	需手动配环境	同左需手动	.bat→WSL2 桥接 + Git Bash 兜底，开箱即用
停止服务	手找 pid	同左	记 pid 文件 + 一行 kill（平台分派）
输出可读	终端日志	同左	分步 OK/WARN/ERR 中文
学习成本	看 README	看 README	一条命令
rc 稳定性	用户自己踩坑	同左	健康检查前置发现
多模式切换	手动 cd + 换命令	手动	cwd 自动识别
适合人群	体验者	二次开发者	两者通吃 + Windows 团队

---

七、设计决策背后的思考

1. 为什么用 bash 而不是 Python/Node？

• 零依赖：macOS / Linux 自带 bash，不需要 pip install 或 nvm
• 透明：用户 cat dsh_setup.sh 就能审计每一行在干什么
• 便携：一个文件，curl 下来就能跑

2. 为什么所有"自动改系统"开关默认关闭？

• 安全优先：自动 brew install node 可能在公司 Mac 上触发 IT 策略
• 明确授权：DSH_AUTO_INSTALL_NODE=1 是用户主动选择，不是脚本偷着干
• 可审计：每个开关在 README 里有明确说明

3. 为什么 v9 选 WSL2 桥接而不是纯 PowerShell 重写？

• 维护成本：bash 版 568 行，重写成 ps1 会漂移到两套逻辑，后续每次改功能要同步两边
• 能力复用：WSL2 下 lsof/tmutil/chmod/open 全部原生可用，用户体验和 macOS 几乎一致
• 开箱即用：Windows 用户双击 .bat 即用，无需关心内部是 WSL2 还是 Git Bash，门槛归零

4. 为什么健康检查放在 Step 6.5 而不是独立脚本？

• 时机精准：刚启动完立即检查，趁热
• 零额外操作：用户不需要再开一个终端跑诊断
• 独立脚本也保留了：dsh_health_check.sh 可随时单独跑

5. 为什么 API Key 用明文而不是加密存储？

• dsh 官方本身就是明文 YAML，加密了 dsh 反而读不了
• 600 权限在单机单用户场景已经是"务实最优"
• 真要加密得写 Cordis 插件对接 Keychain，超出 shell 脚本边界

---

八、安全模型

• 存储位置：~/.dsh/.credentials.yaml，owner 仅当前用户
• 权限：目录 700，文件 600（macOS/Linux 真生效；WSL2 里也生效；Git Bash 模拟）
• 明文问题：yaml 内 api_key: "sk-..." 是明文，不进 Keychain；单机自用 + 不进 TM/iCloud 同步是合理边界
• 泄露面：防其他 Unix 用户/进程读文件；不防同用户态恶意程序（浏览器插件、来路 npx 包）——这是单机模型，不是缺陷
• 官方关系：dsh 自身也写这个文件，脚本只是"终端入口版"的同等写入，不冲突、更新不丢 Key

---

九、实际使用数据

以下是真实运行输出（Mac mini, Apple Silicon, Node 26.5.0）：

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

===> Step 2/8 — 检测 pnpm
[INFO]  corepack 不可用，尝试 npm i -g pnpm...
[ OK ]  pnpm 安装成功

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

===> Step 4/8 — 判定运行模式
[INFO]  未检测到源码 → npm 模式

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

===> Step 6/8 — 启动 DeepSeek Harness
[INFO]  使用最新 rc 版本
[ OK ]  dsh 已就绪 (3s)
[ OK ]  已打开浏览器 → http://127.0.0.1:3080

===> Step 6.5/8 — 健康检查 & 日志诊断
[ OK ]  健康检查: /health 返回 200 ✅
[ OK ]  综合诊断: 一切正常 ✅

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

===> Step 8/8 — 启动完成
✅ DeepSeek Harness 启动完成

从敲命令到浏览器可用：约 5 秒。

Windows 用户双击 dsh_setup.bat（脚本自动选择 WSL2 或 Git Bash），最终进到同一段输出流程。

---

十、适用场景总结

场景	推荐配置	理由
日常体验	默认（npm 模式）	最简单，零配置
源码二开	cd 到源码目录	自动识别，build 后启动
写教程	DSH_PIN_VERSION=0.1.0-rc.6	读者复现一致
快速迭代	DSH_SKIP_DEPS=1	跳过 install/build，秒重启
全新机器	DSH_AUTO_INSTALL_NODE=1 DSH_CLONE=1	全自动从零到可用
排错	bash dsh_health_check.sh 3080	随时诊断不重启
Windows 体验	dsh_setup.bat	双击即用，和 Mac 同事同套流程
CI 验证	DSH_USE_NPM=1 DSH_SKIP_DEPS=1 bash dsh_setup.sh	起 headless 前哨

---

十一、已知限制与未来方向

当前限制

1. 不自动装 Node 本体：开关默认关，避免改用户系统
2. 不自动 git clone：除非 DSH_CLONE=1
3. 不监控运行中的 dsh：没有 daemon 心跳检查
4. Key 明文存储：dsh 生态限制，非脚本问题（600 权限是单机单用户务实最优）
5. rc 版本 schema 可能变：.credentials.yaml 格式官方未冻结，锁版本更稳

未来可扩展方向

• launchd / systemd 集成，支持后台常驻 + 崩溃自启
• 多版本并存（同时跑 rc.5 和 rc.6 对比测试）
• 自动检测 dsh 更新并提示（不自动升级）
• 集成 wechat_to_md.py 作为 dsh workspace 预置工具
• 健康检查增加 /api/models 端点验证（确认 Key 真正生效）

---

十二、结语

好的工具不是功能最多，而是让用户永远不需要思考"下一步敲什么"。
dsh_setup 不是 DeepSeek Harness 的 fork，也不是竞品，它站在官方两条路径（npx / pnpm 源码）之上，补了一个"环境→模式→端口→Key→健康"的收口层。v9 把这条收口线从 macOS/Linux 拉平到 Windows(WSL2)，一份 bash 逻辑服务三端。

这个脚本的演进过程，本质上是一个 “开发者体验（DX）优化” 的缩影：

官方给你"能跑"的最小命令，社区帮你把它变成"好用"的工具。

每一轮迭代都不是"加功能"，而是消除一类用户痛点：

• v1→v2：消除"Key 怎么配"的困惑
• v2→v3：消除"端口被占"的报错
• v3→v4：消除"白屏等半天"的焦虑
• v4→v5：消除"环境不对"的排查成本
• v5→v6：消除"源码/npm 两条路"的认知负担
• v6→v7：消除"挂了不知道为什么"的盲区
• v7→v8：消除"Key 泄露"的安全隐患
• v8→v9：消除"Windows 用不了"的平台门槛

好的工具不是功能多，而是让用户永远不需要思考"下一步该干嘛"。

---

附录 A：环境变量速查

变量	默认	作用
DSH_PORT	3080	指定端口
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
DSH_CLONE	0	自动 clone 官方仓库到 ~/.dsh-src/
DSH_HEALTH_CHECK	1	启动后自动 curl /health

---

附录 B：一条命令矩阵

# 最简启动（自动判断一切）
bash dsh_setup.sh

# 源码目录，快速重启
cd ~/code/deepseek-harness && DSH_SKIP_DEPS=1 bash dsh_setup.sh

# Windows 用户
dsh_setup.bat

# 锁版本 + 健康检查
DSH_PIN_VERSION=0.1.0-rc.6 bash dsh_setup.sh

# 全自动（首次环境）
DSH_AUTO_INSTALL_NODE=1 DSH_CLONE=1 bash dsh_setup.sh

---

附录 C：完整文件清单

文件	行数	作用
dsh_setup.sh	568	主启动器 v9.0（bash）
dsh_setup.bat	~20	Windows 入口（WSL2 桥接）
dsh_health_check.sh	~150	独立健康检查脚本
test_health_check.sh	~100	测试脚本（6 类错误覆盖）

所有文件开源，可审计，可修改，可分发。

---

文件下载地址：
脚本及相关文件 使用文档
帮我点个小小的start 万分感谢