Deepseek harness 安装配置保姆教程

如果你最近在技术圈刷到过 DeepSeek 开源的那个命令行工具，大概会被它的两个反差击中：一边是 8 月 13 日开源后一天之内冲到五万多 star 的热度，另一边是 README 只有一千七百来字、没有截图、没有功能列表、连「这到底是个啥」都没写清楚，全文只甩下一句话——Everything is a Plugin。这个项目叫 deepseek-harness，命令行简称 dsh。它不是一个普通的聊天客户端，而是一套把模型、工具、插件、Agent 预设全部挂在同一个运行时上的可编程脚手架。也正因为「一切皆插件」，它的安装与配置路径比一般工具要多几条岔路：有人只想尝个鲜，有人要天天用，有人要跟进主干代码，有人还要接国产模型的 Coding Plan。这篇文章就按「先装得上、再用得顺、最后配得全」的顺序，把 macOS 上的完整流程拆成可复制粘贴的步骤。本段先解决安装与环境确认，再讲首次进入 Web UI 的三件事，最后把四种模型模式的取舍讲透，让你在真正开始对话前，心里已经有一张清晰的地图。

dsh --version 返回 0.1.1-rc.2：先确认你的环境到底装上了没

很多新手装完工具后的第一个坏习惯，是直接去跑核心功能，跑不通再回头怀疑人生。对于 dsh 这类要拉起本地服务、还要在运行时挂载插件的命令行工具，第一件事永远是确认「装上了没、装的是哪个版本」。官方的验证方式非常朴素，就是一条版本查询命令。当前版本号返回的是 0.1.1-rc.2，注意这个号里带着 rc 后缀，意思是 release candidate，即候选发布版，说明项目还处在快速迭代期，接口和默认行为都可能变。你在自己的机器上跑出来如果不是这个号，不必惊慌：要么你装的时候官方已经发了更新的 rc，要么你装的是更早的快照，只要能正常打印出版本字符串，就说明可执行文件已经进了 PATH，命令解析链路是通的。

dsh --version
# 0.1.1-rc.2

这条命令看着简单，但它能帮你排除掉一大类问题。 dsh 装不上的典型症状是终端直接报 command not found，这通常意味着三种情况之一：全局安装没有成功、npm 的全局 bin 目录没进 PATH、或者你用 nvm 之类的版本管理器切换了 Node 版本导致全局包落在另一套目录里。遇到 command not found，先用 npm root -g 和 npm bin -g（新版 npm 用 npm prefix -g）确认全局目录在哪，再看这个目录是否在 echo $PATH 的输出里。这是所有 Node 命令行工具的通病，不是 dsh 独有的坑，提前知道能省半小时排查。

在动手之前，值得先把 dsh 的定位讲清楚，因为它决定了后面所有配置逻辑。这个项目 8 月 13 日由 DeepSeek 开源，一天之内 star 数突破五万多，但 README 极其克制，一千七百来字，没有一张截图，没有罗列功能，最核心的表述就是那句 Everything is a Plugin。这句话不是营销口号，而是它的架构事实：模型提供方是插件，工具是插件，连你自定义的 Agent 预设也是插件。官方在源码里对「创造模式」的描述非常直白——把它当成有 Shell 的会话，因为 cordis_mount 会在活的运行时上执行模型写的 JavaScript。理解这一点，你后面看到「模型供应商可以任意加」「模式可以切换」「第三方还能装侧边栏插件」就不会觉得散乱，它们全都是同一套插件机制的不同切面。

所以本节的结论很明确：装完先跑 dsh --version，看到版本号再往下走。这一步的成本不到十秒，却能把你从「功能不通」的迷雾里直接拉出来。确认环境可用之后，我们再选安装路线。官方给了三条路：npx 临时运行、npm 全局安装、源码构建。三条路对应三类人，下面逐一展开。

npx @deepseek-ai/dsh web：不落盘的临时尝鲜路线

官方在文档里把 npx 方式标注为「临时运行」，并且是官方推荐的第一种方式。它的最大特点是不落盘——你不需要提前全局安装，npx 会自行去 npm 仓库拉取包并执行。对于只想看看这个工具长什么样、不打算长期使用的同学，这是成本最低的路径。

# 方式一：临时运行（官方推荐）
npx @deepseek-ai/dsh web

执行这条命令后，安装过程会停下来让你确认一次，终端会问你类似「是否继续」的问题，输入 y 回车即可。这一步是 npm 生态的标准行为，因为你是在临时下载并执行一个远程包，npm 需要你明确授权。确认之后，包会被拉下来并直接启动，你会看到终端开始输出日志，最终启动一个本地服务，监听地址是 http://127.0.0.1:3080。把这串地址复制到浏览器打开，就能进入 Web UI 开始体验。

这里有三个工程细节值得展开。第一，127.0.0.1 而不是 localhost 的写法，意味着服务只绑定在本机回环地址上，局域网内其他设备默认访问不到，这对个人开发环境来说是安全的默认值；如果你确实需要从手机或其他机器访问，得自己确认绑定配置，而不是直接把地址改成 0.0.0.0 就完事，那会把你的 API Key 暴露给同网段所有人。第二，3080 这个端口是被硬编码的默认值，如果你本机已经跑了别的服务占了 3080，启动就会失败或行为异常，这时要么先停掉占用进程，要么在命令里指定其他端口（具体参数以 dsh web --help 的实时输出为准，因为 rc 版本参数可能变动）。第三，npx 的缓存行为：npx 会把下载的包放进 npm 的缓存目录，所以第二次执行通常会快一些，但每次仍可能去检查版本。这意味着如果你哪天发现行为不一致，很可能是缓存里换了新版本，这时候用 npx @deepseek-ai/dsh --version 对比一下实际拉到的是哪个版本，能解释大部分「昨天还好好的」类问题。

用 npx 还有一个隐性代价：它每次都要经过一次解析与拉取流程，启动速度不如全局安装稳定，而且在网络受限的环境下容易卡住或失败。所以官方的定位很准确——「适合尝鲜的同学」。一旦你确定要经常用它，就该切到全局安装。

npm install -g @deepseek-ai/dsh 全局安装后的 dsh web 日常用法

如果你打算把 dsh 当作日常工具，全局安装是唯一合理的选择。它和 npx 的本质区别在于：包被真正装进你的全局 node_modules，并在全局 bin 目录里生成一个稳定的 dsh 可执行入口。此后再启动，不再有每次拉取的开销，也不依赖 npm 的临时缓存，启动路径固定、行为可预期。

# 方式二：全局安装后可直接用 dsh web
npm install -g @deepseek-ai/dsh
dsh web # 拉起 Web UI，默认 3080 端口

装完之后，后续每次使用只需要执行 dsh web 即可拉起 Web UI，默认还是 3080 端口。这条命令的好处是它把「安装」和「运行」彻底解耦：安装是一次性的，运行是高频的，你日常只需要记住 dsh web 这一条。前面提到的 dsh --version 验证，在全局安装场景下尤其有意义，因为全局包会被 Node 版本切换、权限问题、镜像源问题影响，而版本号是最快的健康检查。

全局安装有两个常见坑，这里提前讲清楚。第一个是权限问题：如果你用系统自带的 Node 安装，全局目录可能在 /usr/local 这类需要 sudo 的位置，直接 npm install -g 会报 EACCES。正确的做法不是无脑加 sudo（那会把文件属主搞乱，后续升级各种诡异报错），而是改用 nvm 或 fnm 管理 Node，让全局目录落在你的用户目录下。第二个是镜像源问题：国内网络下如果安装卡住，可以临时切到国内镜像再装，装完切回官方源即可，但要注意镜像可能同步滞后，rc 版本尤其容易落后一两个小版本，这也是为什么装完必须用 dsh --version 核对。为了让你一眼看清两条路线的取舍，下面这张表把关键维度对齐。

一句话结论：尝鲜走 npx，长期用走全局安装。两者最终都落在同一个 Web UI 上，端口和交互完全一致，区别只在启动方式与稳定性。而如果你是那种「必须跟进主干、想第一时间试新插件机制」的人，还有第三条路——源码构建。

从源码构建：clone、pnpm install、pnpm run build、pnpm dsh web 四步走

官方给出的第三种方式是通过源码一键安装。之所以要提供这条路，是因为 dsh 的插件机制本身是开放的：你想自己写插件、想改运行时行为、想验证某个还没发版的新特性，就必须拿到源码自己构建。它的步骤是标准的前端 monorepo 流程，一共四步，每一步都不能少。

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

把这四步拆开看。第一步 git clone，仓库地址是 https://github.com/deepseek-ai/deepseek-harness.git，这条地址建议直接收藏，因为后续你查插件机制、看模式源码、提交 issue 都要回到这里。第二步 cd 进入仓库目录，这步没有技术含量但极其重要，后面的 pnpm 命令都必须在仓库根目录执行。第三步 pnpm install，注意这里是 pnpm 而不是 npm，项目用的是 pnpm 作为包管理器，如果你本机没装 pnpm，需要先通过 corepack 或 npm 全局装一个；用 npm install 去装一个 pnpm 项目，很容易因为依赖提升方式不同而产生「装上了但构建报错」的疑难杂症，这是最常见的源码构建坑之一。第四步 pnpm run build，这一步把 TypeScript 源码编译成可运行产物，是整个流程里最耗时的环节，构建中途报错通常是因为 Node 版本过低或缺了系统级依赖，先看报错的第一行而不是最后一行，第一行往往才是根因。第五步 pnpm dsh web，注意这里不是直接敲 dsh，而是通过 pnpm 转发到仓库本地的 dsh 入口，这样启动的是你刚构建出来的这份代码，而不是全局安装的那个版本。

源码构建路线适合三类人：想给 dsh 写插件的开发者、想调试运行时挂载行为的研究者、以及需要锁定某个 commit 做内部部署的团队。它的代价是维护成本高——每次拉取上游更新后都要重新 install 和 build，依赖也可能随之变化。所以如果你的目标只是「用起来」，全局安装足够；只有当你需要「改它」或者「看它怎么跑」的时候，源码路线才值得。三条安装路线的适用场景，可以简单记成一句：尝鲜 npx、日常全局、改造源码。装好之后，真正的重头戏才开始——首次进入 Web UI。

首次进入 Web UI：API Key、界面语言、工作区三件事的顺序

假设你已经在终端看到了本地服务启动的日志，现在在浏览器里输入 http://127.0.0.1:3080 打开页面。第一次进来，界面会引导你完成三件事，顺序很重要：先填 API Key，再切界面语言，最后添加工作区。顺序错了不会不能做，但会让你在英文界面里多绕几圈。

第一步是按引导输入 deepseek API key。没有 Key 的同学需要先去官网生成，地址是 platform.deepseek.com/api_keys。这里的关键认知是：harness 本身不提供模型能力，它只是一个编排层，所有推理都通过你配置的提供方和 Key 转发出去。所以 Key 的有效性直接决定了后面能不能对话。填 Key 的时候注意，输入框通常只显示一次或做掩码处理，粘贴时确认没有把首尾空格带进去，这类「Key 明明是对的却报鉴权失败」的问题，九成是复制时多带了空白字符或者漏了字符。

第二步是切换界面语言（可选）。如果你看英文界面不顺手，点击左下角的 「Settings」 页面，把语言切换到中文即可。这步是可选的，但对入门读者强烈建议先做，因为后面添加工作区、选模型、配提供方都要在设置页里来回跳，用母语操作能显著降低理解成本。切换语言只影响 UI 文案，不影响任何运行时行为，随时可以切回去。

第三步是添加工作区。所谓工作区，本质上就是「添加一个项目」，你需要选择一个本地的项目目录。这一步对应的工程语义是：dsh 会在这个目录范围内执行文件读写、终端命令和插件挂载，所以目录选择决定了模型能碰到哪些文件。入门阶段建议选一个专门的测试目录或者一个独立的 git 仓库，不要一上来就把整个用户主目录或者包含敏感配置的目录丢进去，因为运行时具备 Shell 能力和改文件能力，范围给得越宽，误操作的影响面越大。选好目录之后，还需要再选择模型。到这里，配置的最小闭环才算完成，你可以进入对话界面测试连通性了。

把这三步串起来，其实就是一条最小可用路径：填 Key → 切中文 → 加工作区并选模型。前两步在设置页一次搞定，第三步每次开新项目都可能重来一次，所以后面我们还会回头讲模型配置的完整玩法。现在先把模型选择的岔路口讲清楚。

flash 还是 pro：工作区里选模型时的取舍

添加工作区之后，界面会让你选择模型，素材里明确给到的两个档位是 flash 和 pro。官方对选择的建议非常克制，只有一句「看你的任务」，并没有在文档里列出这两档的具体参数。这一点必须诚实说明：本文不虚构任何未给出的参数，比如上下文长度、每 token 价格、每分钟限流这些数字，素材里没有，就不编。你能依赖的判断依据是档位的通用语义：flash 偏向轻量与快速，pro 偏向更强能力与更高成本。

基于这个语义，给入门读者的实用建议是这样：如果你在做的是改一个小 bug、写一段独立函数、解释一段代码、跑一次简单问答，用 flash 就够了，响应快、试错成本低，适合把流程先跑通。如果你面对的是跨多个文件的仓库级改动、需要理解较大代码库结构的任务、或者对结果质量要求更高的场景，再切到 pro。这个取舍逻辑和大多数双档位模型一致：先确定任务复杂度，再决定档位，而不是默认永远用最强的那个。因为 harness 是一个会连续调用工具、多轮往返的执行器，单次对话可能触发很多次模型调用，档位选高会让整个任务的消耗被放大。

需要提醒的是，模型选择并不是一次性的。它可以在工作区层面调整，也可以在后来的模型配置页里接入更多提供方之后，从官方预设的 deepseek 之外，选到 GLM、通义千问、小米、火山方舟等模型。也就是说，flash 与 pro 是你在「官方预设」里最先遇到的岔路，而整套模型配置体系远比这两个选项丰富。这个完整的配置体系，是本教程第 2 部分的重头戏，这里先埋个伏笔：官方预设模型只要 Key 有效，添加后会自动拉取模型列表，不用你手填一堆参数。

标准 / PTC / 极简 / 创造：四种模型模式分别适合谁

选完模型，还有一个更深一层的选择：模型配置里的模式。素材给出的官方建议是「新手默认标准模式即可」，同时列出了四种模式的定位。这四种模式不是模型档位，而是模型能够调用哪些工具、以什么方式调用工具的运行时配置。理解它们，你就理解了 dsh 为什么敢说「Everything is a Plugin」——连「模型怎么用工具」这件事本身都是可配置的插件组合。

1️⃣ 标准模式：定位是「正常写代码、改仓库」。这是四平八稳的默认档，工具集完整、行为符合大多数人的直觉，适合作为日常主力。新手无脑选它，先建立对工具调用节奏的手感。

2️⃣ PTC 模式：PTC 是 Programmatic Tool Calling 的缩写，这是四种模式里机制最特别的一种，也是最值得展开讲的。它的核心变化是：模型不再一来一回地点工具，而是写一段 TypeScript，通过 Code Mode SDK 一次组合多步，系统用 run_code 执行。把它翻译成工程语言就是——传统工具调用是「模型说调 A，系统执行 A，把结果还给模型，模型再说调 B」，每一次工具调用都是一次完整的模型往返；而 PTC 把这一串往返压缩成一段代码，模型先在脑子里编排好步骤，写成 TypeScript，交给运行时一次性执行。素材里给了一个非常具体的量化描述：五次往返可以收成一次。这意味着在需要连续操作多个工具的复杂任务里，PTC 能显著减少往返开销，把「一步里串很多工具」变成现实。

但请注意 PTC 的隐含前提：既然模型要写 TypeScript 并交给 run_code 执行，那么这个能力天然比标准模式更强、也更需要信任边界。它适合的是那种你已经清楚任务步骤、希望模型高效批量执行的场景，比如「读取三个配置文件、比对差异、按规则改两个文件、再跑一次校验」这种典型的流水线式操作。越是固定的重复流程，PTC 的收益越明显。

3️⃣ 极简模式：素材的描述只有八个字——「只要终端 + 改文件」。它只留两样东西：持久 bash，以及按绝对路径改文件的 str_replace_editor。这是一种刻意做减法的模式，把工具面收窄到最小集合，适合轻量任务或者你只想给模型一个能敲命令、能改指定文件的最小环境。关于它的细节，下一节单独展开。

4️⃣ 创造模式：定位是「做自己的 Agent 预设」。它拥有标准模式的全套能力，再加上改 Harness 自己的能力：检查运行时、试插件、写新的 Agent preset。自定义预设会落到 ~/.dsh/.agent-presets/ 目录下。素材里对它的源码注释引述得非常直白：把它当成有 Shell 的会话，因为 cordis_mount 会在活的运行时上执行模型写的 JavaScript。这句话不是修辞，而是安全提示——创造模式意味着模型可以修改正在运行的运行时、可以挂载自己写的插件，能力强到需要你明确知道自己在做什么。它是给插件作者和 Agent 预设开发者准备的，不是日常写代码的默认选项。

为了让你一次性把这四种模式的差异看清，下面用一张表对齐它们的关键特征。

看完这张表，四种模式的选择逻辑就清楚了：不确定就标准，流程固定想提速就 PTC，只想敲命令改文件就极简，要动运行时和插件就创造。注意模式之间不是能力递进的简单排序，而是面向不同任务形态的剪裁——极简是减法，PTC 是换范式，创造是加权限。这也是「Everything is a Plugin」在模型层的体现：同一套运行时，通过换装不同的工具插件集合，得到完全不同的工作方式。素材里出现的那个第三方插件 DSH-better-sidebar，则是这个理念在 UI 层的延伸——它拓展了右侧栏加底部面板的双工作台，后面配置部分会讲怎么装。

极简模式只留持久 bash 与 str_replace_editor 两样东西

单独把极简模式拎出来讲，是因为它的设计哲学和另外三种模式完全不同。标准模式追求「什么都能做」，PTC 追求「做得更快」，创造模式追求「能力最强」，而极简模式追求的是最小可用的工具面。素材里对它的描述非常精确：只留两样，持久 bash 和按绝对路径改文件的 str_replace_editor。

先看 持久 bash。关键词是「持久」——这意味着它是一个持续存在的终端会话，而不是每条命令开一个新 shell。持久会话的好处是状态可以延续：你 cd 到一个目录之后，后续命令还在那个目录；你 export 的环境变量，后续命令还能读到；你后台起的进程，还在那里跑。对于需要连续操作同一个环境的任务，这比每次都从干净 shell 开始要自然得多。它也意味着模型可以像人一样在终端里「接着上一步继续做」。

再看 str_replace_editor。它的关键定语是按绝对路径改文件。这透露了两个重要信息：第一，它的核心操作是替换式的精准编辑，而不是整文件重写，这对改代码是更安全的方式，改动范围可控、diff 清晰；第二，它要求使用绝对路径，而不是相对路径，这一点新手容易踩坑——如果你习惯性给相对路径，可能会遇到找不到文件或改错位置的问题，尤其在持久 bash 的工作目录和编辑器的路径解析基准不一致时，绝对路径能消除这类歧义。用绝对路径是这套工具最省心的用法，不要图省事写相对路径。

为什么要有极简模式？因为它把「模型能做的事」压缩到最低限度，带来的直接收益是行为更可预测、上下文占用更少、误操作面更小。当你只是想让模型在某个目录里敲几条命令、顺手改一个文件，用完整工具集反而是一种干扰。极简模式本质上是给这类轻量场景准备的一把手术刀，而不是一把瑞士军刀。它的存在也再次印证了四种模式的关系——它们不是同一件事的不同强度，而是针对不同任务裁剪出来的不同工具组合。

讲到这里，你已经完成了从「装没装上」到「进 Web UI」再到「选模型、选模式」的完整入门链条。最小闭环是这样：跑 dsh --version 确认版本为 0.1.1-rc.2，用 npx 或 npm install -g 装上，浏览器打开 http://127.0.0.1:3080，填 deepseek API Key，左下角 Settings 切中文，添加工作区目录，在 flash 与 pro 之间按任务取舍，最后在标准、PTC、极简、创造四种模式里挑一个开始。这条链路走通，说明你的环境、Key、目录权限、运行时挂载都没问题，可以进入下一阶段的正式配置了。而在你按上述步骤操作的过程中，很可能已经注意到模型供应商那一栏看起来远不止 deepseek 一个选项——GLM CodePlan、阿里 qwen-token-plan-cn、小米 xiaomi 这些预设提供方，以及火山方舟这类需要自定义协议的供应商，都在等着被接进来。它们怎么配、Key 从哪来、协议怎么选、模型列表怎么拉，正是本教程第 2 部分要解决的模型配置全流程。

上一段我们把 dsh 从 npm 全局安装一路带到 Web UI 跑起来，并完成了工作区添加与四种模式的选择。这一段接着往下走：先把「创造模式」和它落盘的自定义预设目录讲透，再回到对话界面做一次连通性验证，然后把三家官方预设供应商、两家实测模型、火山方舟自定义接入逐个打通，最后补上桌面客户端与第三方插件，收尾给一份可执行的运维清单。

创造模式与 ~/.dsh/.agent-presets/：自定义 Agent 预设落盘在哪

先把四种模式的关系捋清楚，不然后面配模型时会不知道自己在给谁配。标准模式是默认档，能力边界就是「正常写代码、改仓库」：读写文件、跑命令、看结果、再接着改，这是一条常规的 Agent 闭环。往上走的第一层是 PTC 模式，全称 Programmatic Tool Calling。它和标准模式的差别不在工具数量，而在调用形态——标准模式是模型一来一回地点工具，一次往返只推进一小步；PTC 模式下模型不再逐次点工具，而是直接写一段 TypeScript，通过 Code Mode SDK 把多步组合在一起，由系统用 run_code 去执行。素材里的说法很直观：五次往返可以收成一次。对于「先搜文件、再改三处、再跑测试、再根据报错回改」这种链式任务，PTC 的收益非常明显。

第二层是极简模式，它做的是减法而不是加法：只留两样东西——一个持久 bash，以及按绝对路径改文件的 str_replace_editor。工具面被砍到最小，模型能动用的「手」变少了，但可控性反而更高，适合你只想让它在一个受控目录里做小步修改的场景。

第三层就是本节的主角：创造模式。它不是「极简模式的对立面」，而是在标准模式的全套能力之上，再叠加一层改 Harness 自己的能力。这句话要拆开读：标准模式能做的事它全都能做；在此之外，它还能检查运行时、试插件、写新的 Agent preset。也就是说，模型不只是这个工具的使用者，它同时拿到了这个工具的改装权。

自定义预设的落盘位置是固定的：~/.dsh/.agent-presets/。你在创造模式里让 dsh 生成的 Agent 预设，最终都会写进这个目录。理解这一点很重要，因为它意味着预设是文件形态的可版本化资产，而不是锁在某个 UI 状态里的黑盒配置。你可以给它做 git 管理、可以备份、可以在换机器时直接拷过去、也可以在出问题时直接删掉某个目录回到干净状态。

这里必须把风险点讲在前面。cordis_mount 会在活的运行时上执行模型写的 JavaScript。素材的原文表述是「把它当成有 Shell 的会话」，建议你直接把这句话当成安全原则来用。这句话包含两层含义：第一，创造模式给出的能力等价于一个带 Shell 的会话，模型能触达的范围远超「改改代码」；第二，cordis_mount 执行的是活运行时上的 JavaScript，不是沙箱里的静态配置——它是真的在当前进程里跑起来。所以给创造模式配 Key 之前，先想清楚三件事：

• 目录边界：工作区指向哪个项目目录，创造模式的活动半径就大概率在那一带。别随手把它指向家目录或整个磁盘根目录。
• 凭据边界：创造模式能看到的 API Key、环境变量，等于它有权使用。生产环境的凭证不要和试玩环境混在一起。
• 回滚成本：预设落在 ~/.dsh/.agent-presets/，好处是删掉即可复原；但它在活运行时里执行过的动作（比如改过的文件、跑过的命令）不一定能靠删预设回滚。养成先在干净项目上试的习惯。

把四种模式拉成一张表对比，选型时对着看就够了：

一个很常见的实践路径是这样的：先用极简模式在一个干净的小项目上确认基础链路没问题，切标准模式跑通一两个真实任务建立信任，再视任务形态决定要不要上 PTC 模式省往返，等这些都跑顺了、心里有数了，最后才打开创造模式去写自己的 preset。顺序反过来，等于在没摸清工具边界的情况下先把改装权交出去，出问题时会很难定位是哪一环。

装完先跑一句提示词：对话测试验证连通性

工作区加好、模型选好之后，不要直接丢一个真实项目任务进去。正确做法是回到对话界面，先发一句最简单的提示词，做一次连通性验证。这一步的价值在于把问题域切开：如果一句简单提示词就报错，那是 Key、协议、网络或供应商配置的问题，和你的项目代码毫无关系；如果这一步通了，后面再出错，排查范围就自动缩小到工作区或具体任务上。

连通性验证建议按下面的顺序做，每一步都只消耗极小的成本：

1. 先确认服务在跑：浏览器访问 http://127.0.0.1:3080 能打开界面，说明本地服务正常。顺手在终端跑一次版本查询，确认 CLI 装到位。
2. 发一句纯文本提示词：比如让它简单打个招呼、或描述一下当前选中的模型，不涉及文件读写。这一步验证的是 API Key 到模型的链路。
3. 发一句涉及一次工具调用的提示词：比如让它列出当前工作区根目录的文件。这一步验证的是工作区挂载与工具执行链路。
4. 观察返回：能正常返回内容，说明 KKey 有效、协议匹配、供应商配置正确；如果卡在加载或直接报鉴权错误，回到供应商配置页检查 Key 与协议类型。

第二条命令可以直接用：

# 确认 CLI 已正确安装，并查看当前版本
dsh --version
# 0.1.1-rc.2

# 确认本地 Web 服务可访问（返回 200 即服务正常）
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080

注意版本号 0.1.1-rc.2 是 rc（release candidate）预发布版本。这个信息对运维有意义：预发布版本的功能可能随版本快速变化，遇到行为不一致时，第一件事是确认双方版本号是否一致，而不是急着改配置。

官方预设供应商：zai-coding-cn、qwen-token-plan-cn、xiaomi 怎么加

连通之后就可以正式配模型了。dsh 的模型配置入口路径是统一的，先把这条路记熟，后面三种预设、一种自定义都走同一条主干，只是中间选的「提供方」不同：

「设置」→「模型」→「添加提供方」→「提供方」选择对应标识 → 填写 API-KEY → 保存

三家官方预设供应商的标识分别是：

• GLM CodePlan：提供方选择 zai-coding-cn，填入 API-KEY 保存即可。
• 阿里千问个人 tokenplan：提供方选择 qwen-token-plan-cn，填入 API-KEY 保存即可。
• 小米个人 API-Key：提供方选择 xiaomi，填入 API-KEY 保存即可。

这三家有一个共同的关键行为：这类官方预设好的模型列表不需要手动配置。只要 API Key 有效、添加配置成功，模型列表会自动拉取。这一点和后面火山方舟的自定义接入形成鲜明对照——预设供应商你只需要给一个 Key，剩下的交给 dsh；自定义供应商你得自己填协议、填地址、手动把模型挑出来。

为什么预设能自动拉取而自定义要手动？本质区别在元信息是否已知。预设供应商的协议类型、接入地址、模型清单，dsh 侧已经内建；你提供的 API Key 只是最后一块拼图，拼上之后它就能去拉清单。自定义场景下，协议和地址都要你手填，模型清单也只有发起一次真实的列表请求才知道，所以必须多一步「获取可用模型」的交互来确认配置是否正确。

这里给一个运维层面的小建议：三家供应商不要一次性全配。先配一家、测通、确认可用，再配下一家。原因很简单——如果同时配三家然后出错，你面对的是一个多变量问题，很难判断是 Key 的问题、供应商服务的问题，还是本地网络的问题。逐个引入变量，是排障成本最低的做法。

GLM-5.2 与 Qwen3.8-Max-Preview 实测：预设模型回首页直接选

预设供应商配好之后，使用路径非常短：回到首页，在模型列表里选择对应模型直接使用。不需要再做任何模型层面的手动配置。

素材中给出的实测结论有两条，可以直接作为选型参考：

• GLM 的 Coding Plan 中的 GLM-5.2 模型，测试正常。
• 阿里千问的 Coding Plan 中的 Qwen3.8-Max-Preview 模型，测试正常。阿里 Coding Plan 的 API Key 获取地址为 platform.qianwenai.com/home/api-keys。
• 此外，小米的 API Key 也可以正常使用。

把这三条放在一起看，能得到一个对新手很有用的结论：官方预设的接入路径是经过验证的、稳定的主路径。你不需要研究协议细节、不需要手写地址、不需要挨个挑模型，只要拿到有效 API Key，填进去，回首页选模型，就能跑。对于「我只想赶紧用起来」的需求，这条路径就是最优解。

反过来说，什么时候才需要走自定义？答案是：当你要接的供应商不在官方预设列表里时。比如火山方舟这类需要自己指定接入地址的场景，就必须走下一节的流程。所以判断标准很清晰——先在预设列表里找，找不到再自定义。切忌在预设已经支持的情况下硬走自定义，那等于主动给自己增加两个可能出错的字段。

另外提醒一个容易被忽略的点：Coding Plan 类型的 Key 和按量付费的 API Key 在语义上是不一样的。素材里把这两类分开表述——按量付费的 API Key 配置了 deepseek、xiaomi 作为模型供应商；通过 Coding Plan 的 API Key 以标准模板配置了阿里千问、智谱；又通过 Coding Plan 的 API Key 以自定义方式配置了火山引擎。这个分类本身就是一条运维线索：先确认你手上的 Key 属于哪一类，再去对应的路径里配，能省掉很多「为什么填了 Key 却拉不到模型」的困惑。

火山方舟自定义接入：openai-completions / openai-responses 协议与获取可用模型

现在走自定义路径。以火山方舟的 Coding Plan 为例，它不在官方预设列表里，所以要自己填协议和地址。火山方舟的配置说明文档地址是 console.volcengine.com/ark/region:。整个流程的关键字段有四个，逐个说清楚：

1. 协议选择：选兼容 OpenAI 接口协议的工具，也就是 openai-completions 或者 openai-responses。选哪一个取决于你打算用的模型走哪种接口形态。
2. API 地址：填 ark.cn-beijing.volces.com/api/coding/… 这个 coding 接入地址。
3. API Key：填入你自己的火山方舟 Key。
4. 模型选择：点「获取可用模型」，从拉回来的列表里勾选。

「获取可用模型」这一步是整个自定义流程的验证锚点：如果能拉取到模型列表，说明配置正确。这句话的分量很重——它把「协议对不对、地址对不对、Key 有没有权限」这三个问题一次性回答了。如果点下去拉不到任何模型，不用怀疑模型本身，问题一定在这三个字段里。所以正确的排障顺序是：先确认协议选的是 OpenAI 兼容，再核对地址拼写，最后确认 Key 的权限范围。

接下来是这个流程里最容易踩的坑：火山的这个模型列表有 100 多个。素材里的吐槽非常真实——「选择你常用的几个就行，不然列表太大了没法看」，并且明确指出「官方应该加个反选功能，不然像这种模型列表比较多的一个个点太蛋疼了」。这句话在教程里值得单独拎出来当工程经验讲：

• 不要在拉到大列表后全选。100 多个模型全部加进来，后续模型选择列表会长到无法使用。
• 先想清楚要哪几个再动手选。常见的做法是先确定本次任务用哪个模型，只勾那一个，等真有第二个需求时再回来加。
• 期待反选功能：素材明确提到当前缺少反选能力，如果你也遇到同样的痛点，这是可以向项目反馈的改进点。在反选功能出现之前，控制首次选择的数量就是最务实的策略。

选完之后，删掉没用的模型，再点击「创建提供方」。这个「先精简再创建」的顺序不能反——创建之后再去清理，等于多做一遍无用功。创建完成后，选一个火山的模型测试一下，正常即可。

把预设路径和自定义路径放在一起对比，两者的差异就一目了然了：

还有一个流程上的细节值得固化下来：素材里说的是「选一个火山的模型测试一下，正常即可」。这句「测试一下」就是整个自定义接入的最后一道闸门。很多人配完直接开干，结果第一个真实任务失败，反而分不清是接入没配好还是任务本身难。配置完成后先用一条轻量请求验证，这条纪律在预设路径和自定义路径上都成立。

不想开浏览器标签页？DSH Desktop 自动拉起本地 dsh web

前面所有操作都建立在「浏览器里开着一个标签页」这个前提上。如果你不想一直挂着标签页，或者本机没有 Node 环境，社区已经有现成的替代方案：基于 DeepSeek Harness 构建的开源桌面客户端 DSH Desktop，目前已经有将近 2 万颗 star，官网地址是 www.dshdesktop.cn。

它解决的问题很具体：让 dsh 脱离浏览器、以原生窗口直接运行。功能上有三个对日常使用帮助最大的点：

• 多窗口：可以同时开多个窗口跑不同工作区或不同任务，不用在浏览器标签之间来回切。
• 系统托盘常驻：关掉窗口不等于停掉服务，托盘里随时唤回。
• 自动拉起本地服务：启动时会自动拉起 dsh web 本地服务。这意味着你完全不需要手动执行前面那些 CLI 命令。

安装方式对新手极其友好：官网提供打包好的安装包，Mac 和 Windows 都支持一键安装，开箱即用，装完直接打开就能用。注意这里有一个使用路径的切换——如果你走 DSH Desktop，就不需要先在终端里手动 dsh web 了，客户端会把本地服务拉起来，你直接面对界面即可。

那什么时候该选浏览器、什么时候该选桌面客户端？可以这样判断：

• 临时尝鲜、想先看看这东西长什么样：用浏览器方式就够了，npx 临时运行不需要全局安装。
• 本机有 Node 环境、习惯命令行、想要最贴近源码的控制感：用 npm install -g @deepseek-ai/dsh 全局装，然后 dsh web。
• 没有 Node 环境、或者不想一直开着浏览器标签页、想要多窗口与托盘常驻：直接用 DSH Desktop，一键安装包解决问题。

把三种运行方式放一起看会更清楚：npx 临时运行适合一次性试用；全局安装 + dsh web 适合需要频繁使用的开发者；DSH Desktop 适合希望脱离浏览器、开箱即用的用户。三条路径最终都指向同一个本地服务，只是入口不同。

2026 年 9 月再看 DSH-better-sidebar：插件式扩展侧边栏与底部面板

DSH Desktop 解决的是「在哪里用」的问题，第三方插件解决的是「界面上有什么」的问题。这里要说的插件是 DSH-better-sidebar，它做的事情是拓展右侧栏 + 底部面板双工作台，GitHub 项目地址是 github.com/omdsh-dev/D…。它的安装方式极简，一行命令：

# 安装 DSH-better-sidebar 插件
curl -fsSL https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.sh | bash

安装完成后有两个动作必须做，缺一个都看不到效果：

1. 重启 DSH。插件是运行时加载的，不重启不会生效。
2. 硬刷新浏览器：Cmd/Ctrl+Shift+R。普通刷新可能命中缓存，导致界面还是旧的，必须硬刷新。

做完这两步，即可看到侧边栏。「重启 + 硬刷新」这个组合看起来像是一个小技巧，但它其实是插件式架构的通用规律：服务端要重新加载插件，客户端要丢掉缓存重新取资源，两边都刷新才算完整生效。以后装任何 dsh 插件，都可以沿用这套动作。

这个插件值得在 2026 年 9 月再拿出来说的原因，是它印证了整个项目最核心的那句宣言——Everything is a Plugin。回看全文会发现这条原则贯穿始终：

• 能力层：四种模式本质上就是不同的能力组合，极简模式只留两样，创造模式叠加改 Harness 自身的能力。
• 模型层：官方预设供应商（zai-coding-cn、qwen-token-plan-cn、xiaomi）走标准模板，火山方舟走自定义协议，两种路径并存，模型配置同样非常灵活。
• 界面层：DSH-better-sidebar 用一行 curl 往侧边栏和底部面板里塞新工作台。

放到 2026 年 9 月这个时间点看，插件生态的意义在于：核心仓库可以保持很薄，能力由插件长出来。前面提到最初 README 只有一千七百来字，没有截图、没有功能列表，只甩出一句 Everything is a Plugin——当时看起来什么都没说，现在回头看，它说的其实是整个项目的扩展模型。不过运维视角下也要保持清醒：插件能力越强，安装脚本的来源可信度就越重要。像上面这种 curl | bash 的安装方式，执行前至少应该确认来源是官方或社区公认的项目地址，别随手复制来路不明的脚本。

总结与最佳实践

把这一整篇压缩成一份可以照着做的清单。按顺序执行，遇到问题按条目回溯即可。

1. 选安装方式：临时尝鲜用 npx @deepseek-ai/dsh web（过程会让你确认，输入 y）；常用则全局安装 npm install -g @deepseek-ai/dsh，之后直接 dsh web，默认端口 3080；也可以走源码一键安装（clone → cd → pnpm install → pnpm run build → pnpm dsh web）。
2. 确认装成功：执行 dsh --version，看到类似 0.1.1-rc.2 的输出即正常。注意 rc 标识意味着预发布版本，排障时先核对版本号。
3. 打开界面并完成三件初始配置：浏览器访问 http://127.0.0.1:3080；按引导输入 deepseek API key（官网 platform.deepseek.com/api_keys 生成）；可选在左下角「Settings」把界面语言切成中文。
4. 添加工作区并选模型：添加一个项目目录作为工作区，然后选 flash 还是 pro 看任务而定。
5. 模型模式按需升级：新手先用标准模式；需要把多次往返合并为一次代码执行时上 PTC 模式；要做受控目录内的小步精修用极简模式；要写自己的 Agent preset 才开创造模式。
6. 创造模式的安全纪律：自定义预设落在 ~/.dsh/.agent-presets/；牢记 cordis_mount 会在活的运行时上执行模型写的 JavaScript，把它当成有 Shell 的会话来对待，工作区别指向家目录或磁盘根目录。
7. 配置前先做连通性验证：回到对话界面发一句简单提示词，通了再上真实任务，把配置问题和任务问题彻底分开。
8. 优先走官方预设：统一路径是「设置 → 模型 → 添加提供方 → 选择提供方 → 填 API-KEY 保存」。三家标识分别是 zai-coding-cn（GLM CodePlan）、qwen-token-plan-cn（阿里千问个人 tokenplan）、xiaomi（小米个人 API-Key）；API Key 有效添加配置后模型列表会自动拉取。
9. 预设配好后回首页直接选：GLM-5.2（GLM Coding Plan）与 Qwen3.8-Max-Preview（阿里千问 Coding Plan）均实测正常，小米 API Key 同样可正常使用。
10. 预设找不到再走自定义：以火山方舟为例，协议选兼容 OpenAI 接口协议的 openai-completions 或 openai-responses，API 地址填 ark.cn-beijing.volces.com/api/coding/…，填入 Key 后点「获取可用模型」——能拉到列表就说明配置正确。
11. 处理大模型列表：火山有 100 多个模型，只挑常用的几个，避免列表过大无法查看；当前无反选功能，控制首次选择数量是最务实的策略；先删掉没用的模型，再点「创建提供方」，最后选一个模型测试，正常即可。
12. 不想开浏览器标签页就用桌面客户端：DSH Desktop（约 2 万 star，www.dshdesktop.cn）支持 Mac/Windows 一键安装，多窗口 + 系统托盘常驻，启动时自动拉起 dsh web 本地服务，无需手动执行 CLI 命令。
13. 按需装插件并刷新到位：DSH-better-sidebar 一行 curl 安装后，重启 DSH 并 Cmd/Ctrl+Shift+R 硬刷新，即可看到侧边栏与底部面板双工作台。
14. 配置总量参考：走到这里，一共可配置 5 个模型供应商——按量付费 API Key 配置 deepseek、xiaomi；Coding Plan API Key 通过标准模板配置阿里千问、智谱；Coding Plan API Key 通过自定义配置火山引擎。

• 核心心智模型：Everything is a Plugin。能力、模型、界面三层都通过「预设 + 插件」的方式扩展，理解这一点，后面遇到任何新供应商或新插件，都能快速找到对应的接入路径。
• 排障口诀：界面打不开 → 看服务是否在 3080；一句提示词就报错 → 查 Key 与协议；拉不到模型 → 查协议、地址、Key 权限；装完插件没反应 → 重启 + 硬刷新。
• 安全底线：创造模式与插件安装这两件事都需要额外谨慎，前者涉及活运行时执行模型代码，后者涉及执行第三方安装脚本，来源可信度必须自己把关。

到此，从安装、初始配置、模型接入，到桌面客户端与插件扩展，整条链路就完整了。回看开头那个「README 只有一千七百来字、没有功能列表」的项目，它把复杂度从文档转移到了扩展机制上，而这份清单要做的，就是替你把这条扩展路径按顺序走一遍。接下来就是把它接到你自己的工作区上，开始干活。