河洛序
会员
知己录 Harness

DSH 安装、首次配置与社区插件

从空文件夹启动 DSH，完成第一个只读任务。配合操作示例、图解和检查点，完成第一次练习，再逐步排查使用中的问题。

入门整理更新：2026-10-13DSH 专栏

信息层级：【有据可查】= 附官方文档或可信来源链接；【社区共识】= 社区用户普遍经验，未经官方确认；【待考察/推测】= 推测或暂未能核实，请谨慎对待。

额外提醒：dsh 目前处于 developer preview，官方 README 原话是 "THERE WILL BE COMPATIBILITY-BREAKING CHANGES"（会有破坏兼容性的变更），并要求运行前阅读 SAFETY.md。【有据可查】本文的命令和配置路径可能很快过时。

1. dsh 是什么？30 秒回顾

  • 【有据可查】DeepSeek 开源的 Agent Harness，MIT 协议，基于 Cordis 插件框架，"一切皆插件"。仓库：https://github.com/deepseek-ai/deepseek-harness
  • 【有据可查】由多个 profile（配置档） 组成：web、headless、sdk、sdk-minimal、acp；desktop 名称保留给 Electron 桌面版。来源：CLI README
图 1

【有据可查】架构说明见 Architecture。

2. 下载与启动

2.1 方式一：npm 一行启动（推荐新手）【有据可查】

# 前提：已安装 Node.js（https://nodejs.org/）
npx @deepseek-ai/dsh web
  • 默认在 http://127.0.0.1:3080 打开 Web UI；加 --no-open 不自动打开浏览器；SSH 远程启动时只打印地址。
  • 运行目录 = 默认工作区根目录。建议先 cd 到一个测试项目再启动。

2.2 方式二：源码运行（进阶）【有据可查】

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

2.3 方式三：桌面版

  • 【有据可查】官网介绍页称可"作为桌面应用运行或通过代码启动 Web UI"（https://www.deepseek.com/en/harness/），仓库中有 desktop 应用目录。
  • 【待考察/推测】桌面版安装包的具体下载入口与平台支持未核实，请以官网为准。另有第三方 Electron 封装插件（见第 5 节），非官方。

2.4 其它启动方式速查【有据可查】

命令 用途
dsh web 启动 Web 界面
dsh --profile headless "run the tests" 一次性任务，打印结果后退出（成功 0 / 失败 1），适合脚本/CI
dsh --profile acp 通过 ACP 供编辑器/自动化客户端调用
dsh --profile sdk JSON-RPC 供 SDK 调用
dsh --profile <名字> --from-default-profile <模板> 基于模板新建自定义 profile
dsh plugin --profile <名字> ... 管理该 profile 的插件（转发给 pnpm）

3. 首次配置：三步走【有据可查】

来源：Web UI 指南、模型配置指南

图 2
  1. 配模型：打开 Settings → Models，填入 DeepSeek 开放平台 的 API Key 保存，无需重启。
    • Key 是"只写"的：页面保存后只拿到脱敏描述；Key 存在 $DSH_HOME/.credentials.yaml。
  2. 选工作区：未选工作区时输入框不可用。
  3. 跑任务：官方示例 "Summarize this repository and identify its main packages."；按当前权限策略，需要审批的操作会先询问你。

其它厂商（anthropic、openai、moonshotai(Kimi)、zai(GLM) 等）与自定义网关的配置，见DSH 添加模型：协议、地址、密钥与模型 ID。注意：官方文档写明 Codex 这类 OAuth 登录的提供方暂不支持在此添加。【有据可查】

4. 安全配置：先把沙箱理解清楚

【有据可查】来源：Process Sandbox、Config Catalog

模式 含义 建议
read-only 只读（策略插件的缺省值，不保证新会话默认如此） 新手、看代码、问问题；先核对实际会话
workspace-write 可写工作区；具体范围以执行后端为准 日常开发；先确认当前预设是否已经启用
danger-full-access 不限制文件效果 仅在你完全理解后果、且在隔离环境中使用
  • 沙箱由插件组合实现：dsh-sandbox（契约）+ dsh-sandbox-local（Linux bwrap/Landlock、macOS Seatbelt、Windows ACL）+ dsh-bash-sandbox / dsh-pwsh-sandbox（消费者）+ dsh-sandbox-policy（策略）。
  • 找不到可用后端时 fail-closed（报 SANDBOX_UNAVAILABLE，不会偷偷放行）。
  • Linux 新手注意【待考察/推测】：若系统缺 bwrap（bubblewrap）或内核不支持 Landlock，可能遇到沙箱不可用报错，此时应安装依赖而不是直接切到 danger-full-access。

5. 社区插件：怎么挑？（可靠性 > 功能）

5.1 插件从哪里找？

  • 【有据可查】官方 README 建议插件作者给仓库加 GitHub topic dsh-plugin 以便发现。
  • 【有据可查（页面存在）/ 待考察（是否官方）】第三方目录站 https://deepseek-plugin.org/ 自称收录上万个插件、每日更新；未确认其与 DeepSeek 官方的关系，星标数据也请自行到 GitHub 核对。
  • 【待考察】其它社区站点如 dshkit.dev、deepseek-harness.help 等，未确认维护方。

5.2 评估框架：三问三查

图 3
维度 具体检查项 红旗信号
可靠性 作者是否为知名组织/实名开发者；源码是否公开可读；需要哪些权限（文件、网络、Shell、凭据） 要求你提供与功能无关的 API Key；代码混淆；安装脚本下载二进制
长期维护 最近一次提交时间；issue 是否有人回复；是否跟进 dsh 新版本 只有一次提交；README 与 dsh 当前命令对不上
兼容性 声明支持的 dsh 版本；是否替换核心服务（如 ctx.shell、ctx.fs、ctx.sandbox）；与其它插件是否提供相同服务 两个插件都想接管同一能力（如两个记忆插件、两个路由插件）

【社区共识】dsh 的核心设计是"能力缝（seam）"——同一能力由一个提供方负责。文档说明"文件系统和子进程提供方共享同一执行世界"，换掉一个可能牵动 Bash、PTY、LSP。【有据可查：Architecture】因此同类插件只装一个是最简单的兼容性原则。

5.3 社区可见的插件类型（只做分类，不做背书）

以下信息来自第三方目录站 deepseek-plugin.org 的首页展示，尚未逐个安装验证，全部标注【待考察】：

类别 目录站上可见的例子 选择时的注意点
长期记忆 Hindsight（vectorize-io）、MemOS 本地插件（MemTensor）、agentscope-ai 的记忆套件 同时只装一个记忆插件；留意数据存在本地还是云端
知识库/RAG dsh-weknora（标注为 Tencent） 留意文档上传到哪里
桌面封装 deepseek-harness-desktop（anywhere-labs，第三方 Electron 封装） 非官方；会带更新检查，关注其更新来源
模型路由 dsh-routing-suite 会改变模型/推理模式选择，可能与你手动配置冲突
工作流/MCP 桥接 ouroboros 的 dsh-plugin（通过 uvx 启动 Python） 会额外拉起外部进程与依赖
第三方应用集成 Reactive Resume 的 dsh-plugin 会读写你在该应用中的数据

5.4 建议的"最小可靠组合"【待考察/推测】

  1. 先只用官方内置（dsh-base 自带模型、工具、沙箱、审批），跑一周。
  2. 真有痛点再加 一个 插件，并建一个独立 profile 试装： 
    dsh --profile trial --from-default-profile web
dsh plugin --profile trial add <包名>
    （命令语法依据官方 CLI README 与第三方教程整理，add 子命令细节请以 dsh plugin --help 为准。）
  3. 每次 dsh 大版本更新后，先在试验 profile 里确认插件仍工作。

6. 常见报错速查【有据可查：来自官方模型配置指南】

报错 原因 处理
MISSING_CREDENTIAL 没存 Key 或环境变量没设置 在 Models 页保存 Key，或设置 apiKeyEnv 指向的环境变量
UNKNOWN_MODEL 模型 ID 不在配置里 选已配置模型或手动添加
拉取模型列表 401 Key 错 检查 Key；不支持 GET /models 的端点就手动填
网关拒绝所有请求 请求格式与 OpenAI 不同 设置 compat.supportsDeveloperRole: false、compat.maxTokensField: max_tokens
SANDBOX_UNAVAILABLE 没有可用沙箱后端 安装/启用系统沙箱依赖，不要图省事直接关沙箱

7. 本篇无法核实/需谨慎的点

  • 桌面版官方下载入口与平台支持。
  • deepseek-plugin.org、dshkit.dev、deepseek-harness.help 等站点的维护方及数据准确性。
  • 所有社区插件的质量、维护状态、兼容性——尚未实测。
  • dsh plugin ... add 的完整语法在不同版本可能不同。

小白练习：把本文流程逐项走通

练习目标：从空文件夹启动 DSH，完成第一个只读任务。

上文已介绍概念、配置和操作示例。下面侧重第一次实际操作时的顺序、检查点和结果核对；需要查具体参数时回到对应小节。命令逐条输入，看到上一条的结果后再继续。

  1. 在文件管理器新建一个练习项目文件夹，放入一份不含隐私的文本。打开终端，使用 cd 进入这个文件夹。

  2. 单独运行 node --version，确认 Node 已安装；再运行原文的 npx 启动命令。遇到下载确认时核对包名。

  3. 终端出现 127.0.0.1 地址后，用浏览器打开该地址。终端窗口需要保持运行；关闭窗口会使页面无法连接。

  4. 打开 Settings，再进入 Models，添加自己的 API Key 并保存。随后选择一个可用模型；不要把网页登录密码填入 Key 栏。

  5. 使用 Choose workspace 选择刚才的练习目录。在当前会话确认权限模式，再请求只读取文件并总结。看到与原文相符的摘要后，首次配置才算完成。

  6. 需要插件时创建独立试验 profile，逐个安装。安装成功还要检查当前版本的配置转储与实际会话；仅出现插件名字不能证明插件可用。

首次任务前确认有效权限

【有据可查】官方权限预设表目前包括 workspace-write + ask 和 danger-full-access + never；read-only 是沙箱策略插件的缺省值，实际新会话还取决于组合配置及 defaultPreset。原来的配模型、选工作区、跑任务三步仍分别执行。

【操作补充】选好工作区后，先查看当前会话 Permissions 和实际文件策略。只读练习要确认已经限制写入，再发送仓库摘要任务；以后允许编辑时重新核对范围和审批策略。若界面只有预设名称，按当前版本的官方说明核对它对应的两个值。

核对来源：DeepSeek 官方：沙箱策略插件说明；DeepSeek 官方：Permission Presets。

继续浏览知己录 返回顶部 ↑
教程图解100%
教程图解
灵犀台