使用手册

本手册覆盖从零启动 DeepSeek Harness（dsh）到日常使用与排障。 一键命令见 快速启动；产品细节以 官方文档 为准。

1. 产品概述

DeepSeek Harness（dsh） 是 DeepSeek 开源的 Agent Harness。 最常见的上手方式是启动本地 Web UI，在浏览器里选择工作区、配置模型并对话。

本 onboarding 站点额外提供「团队预置版」能力：把统一的 API Key 与 API 端点写到用户本机 ~/.dsh，减少每人手工配置。

2. 环境要求

  • Node.js：^22.19.0 或 >=24.0.0（官方 engines；Node 23 不在范围内）
  • npm / npx：随 Node 安装
  • 网络：首次 npx 需能访问 npm registry；运行时需能访问你配置的模型端点
  • 操作系统：Windows 10+（PowerShell 5.1+）、macOS、主流 Linux
一键脚本会尝试自动安装 Node，但在企业锁定环境 / 无管理员权限时可能失败，此时请按 IT 流程安装 Node 后重跑命令。

3. 安装与启动

3.1 推荐：一键脚本

打开 快速启动，复制对应系统命令。

  • Windows：irm <site>/scripts/bootstrap.ps1 | iex
  • macOS / Linux：curl -fsSL <site>/scripts/bootstrap.sh | bash

脚本流程：检测 Node →（可选）安装 Node → 写入凭据 → npx -y @deepseek-ai/dsh web。

3.2 仅检查 / 只配置

# macOS / Linux
curl -fsSL <site>/scripts/bootstrap.sh | bash -s -- --check-only
curl -fsSL <site>/scripts/bootstrap.sh | bash -s -- --no-launch

# Windows（先下载再带参数）
irm <site>/scripts/bootstrap.ps1 -OutFile bootstrap.ps1
.\bootstrap.ps1 -CheckOnly
.\bootstrap.ps1 -NoLaunch

3.3 官方最小命令（自备 Key）

npx @deepseek-ai/dsh web

然后在 Web UI「设置 → 模型」中填写 API Key。若使用自定义网关，还需配置 Base URL。

4. 凭据与端点

一键脚本默认写入（可用环境变量 DSH_HOME 改根目录）：

  • ~/.dsh/.credentials.yaml → DEEPSEEK_API_KEY: …
  • ~/.dsh/.env → DEEPSEEK_BASE_URL=…（同时会写入 API Key 作为后备层）

解析优先级（概念上）：进程环境变量 > .credentials.yaml > 用户/项目 .env。详情见官方 credentials 文档。

4.1 管理员如何改预置值

  1. 编辑本站点 config/defaults.json 的 apiKey / baseURL
  2. 同步修改 scripts/bootstrap.ps1 与 scripts/bootstrap.sh 顶部的内置默认值（在无法拉取 JSON 时兜底）
  3. 重新部署静态文件
安全提示：把真实 Key 放进公开站点意味着任何打开页面或下载脚本的人都能拿到它。 只适合可轮换、可限流、可吊销的团队共享 Key；生产密钥请改用每人自助申请或短时下发。

4.2 用户覆盖预置值

# 环境变量
export DSH_ONBOARD_API_KEY='sk-xxx'
export DSH_ONBOARD_BASE_URL='https://your-endpoint/v1'
curl -fsSL <site>/scripts/bootstrap.sh | bash

# 或参数
./bootstrap.sh --api-key 'sk-xxx' --base-url 'https://your-endpoint/v1'
.\bootstrap.ps1 -ApiKey 'sk-xxx' -BaseURL 'https://your-endpoint/v1'

5. 启动后使用

  1. 终端出现监听地址后，浏览器打开 http://127.0.0.1:3080（以实际输出为准）。
  2. 在 Web UI 中添加并选中工作区（项目目录）。未选中工作区时输入框不可用。
  3. 打开 设置 → 模型 确认 DeepSeek 路由可用。预置 Key 已写入时通常无需再填。
  4. 新建会话，发送任务，例如：「总结这个仓库的主要包结构」。

更完整的 UI 说明见官方 Web UI 指南 与 模型配置指南。

6. 日常操作

再次启动

npx -y @deepseek-ai/dsh web

凭据已在 ~/.dsh 时不必重复跑 onboarding 脚本。

更换 Key / 端点

  • 重跑一键脚本（会更新同名键），或
  • 直接编辑 ~/.dsh/.credentials.yaml / ~/.dsh/.env，或
  • 在 Web UI 设置页写入新密钥

清理

# 仅删除凭据（保留其他 dsh 数据）
rm ~/.dsh/.credentials.yaml   # Windows: 删除 %USERPROFILE%\.dsh\.credentials.yaml

# 删除整个 dsh 用户目录（会话、设置等一并消失）
rm -rf ~/.dsh

7. 部署本站点

dsh-onboarding/ 是纯静态资源，可部署到 Nginx、GitHub Pages、对象存储静态网站、内网文件服务等。

  1. 填写 config/defaults.json 与两个 bootstrap 脚本中的 Key / 端点
  2. 将整个 dsh-onboarding 目录上传到 HTTPS 站点（推荐 HTTPS，便于剪贴板 API）
  3. 确保以下路径可直接访问：
    • /index.html
    • /config/defaults.json
    • /scripts/bootstrap.sh
    • /scripts/bootstrap.ps1
  4. 给 bootstrap.sh 配正确的 Content-Type（text/plain 或 application/x-sh 均可）；避免被下载成错误编码
  5. 本地预览示例：
cd dsh-onboarding
# Python
python -m http.server 4173
# 或 Node
npx --yes serve -p 4173
# 打开 http://127.0.0.1:4173

8. FAQ / 排障

Q: 提示占位 API Key？

管理员还没把 sk-REPLACE_WITH_YOUR_KEY 换成真实值。改 defaults.json 与脚本后重新部署。

Q: Windows 报执行策略错误？

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Q: 安装了 Node 仍提示找不到？

当前终端 PATH 未刷新。关闭终端重开，或重新登录系统后再执行。

Q: npx 很慢或失败？

  • 检查是否能访问 npm registry；可配置企业镜像
  • 尝试 npm config get registry 并按公司要求切换
  • 使用 npx -y @deepseek-ai/dsh web 查看完整报错

Q: 浏览器打开了但无法对话？

  • 是否已选择工作区
  • 模型设置里 Key 是否有效、端点是否可达
  • 公司代理是否拦截 localhost 或模型域名

Q: 如何确认脚本写入成功？

# macOS / Linux
cat ~/.dsh/.credentials.yaml
cat ~/.dsh/.env

# Windows PowerShell
Get-Content $HOME\.dsh\.credentials.yaml
Get-Content $HOME\.dsh\.env

Q: 可以离线安装吗？

本方案依赖 npx 在线拉包。完全离线需要预先缓存 npm 包或改用内网 registry / 源码构建，不在当前一键脚本范围内。