DeepSeek Harness（dsh）安装使用实战指南：全栈安装、模型配置、飞书接入与免费模型可行性

1. 从零跑通 dsh 到底卡在哪DeepSeek Harness简称 dsh是 DeepSeek 官方开源的自主 Agent 运行时框架采用 MIT 协议当前处于 v0.1.0-rc 开发者预览阶段。它能做什么简单说它把模型 工具 会话存储 沙箱 审批 UI全部拆成可替换的插件让你自己组装一个编程 Agent。适合谁想研究 Agent 内部机制、想把 DeepSeek 接进飞书、想给团队搭一个可定制 Agent 底盘的开发者。但真从零跑通坑比想象中多。我见过最多的三类卡点一是 Node 版本不对Node 23 直接启动失败二是模型配置写错MISSING_CREDENTIAL或UNKNOWN_MODEL报错三是飞书接入时不知道选哪条路线公网回调、长连接、企业自建应用绕晕。这篇就按环境准备 → 全栈安装 → 模型配置 → 飞书接入 → 免费模型可行性的顺序把每一步的可复制配置和验证动作写清楚配一份能直接抄的config.toml骨架和统一 Key/API 通道示例。先说结论dsh 安装本身一条命令模型配置零门槛飞书有三到四条成熟路线但像 OpenCode 一样内置免费模型目前不可行高频 Agent 调用必然触发 429 限流正经任务建议走官方 API 或统一网关。2. 前置TaoToken 统一 Key 与 API 通道在配 dsh 之前先把模型通道理顺。dsh 支持任何 OpenAI 兼容端点所以你可以用 TaoToken 作为统一入口一个 Key 管多个模型省得在 dsh 里来回切供应商。TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api操作路径很直接登录后进控制台在 API Keys 页面创建一个 Key复制保存只显示一次。然后在 dsh 里把它当成一个自定义 OpenAI 兼容供应商填进去即可。这样做的好处是dsh 的settings.yaml里只维护一个baseURL和一个apiKeyEnv换模型只改models列表不用动其他配置。注意Key 属于只写字段dsh 保存后不会回显实际存在~/.dsh/.credentials.yaml权限 0600。建议用环境变量注入别明文写进 yaml。如果你只是想先验证模型能不能通可以先用模型对话页面测一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期跑编码任务或 Agent 的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite3. 全栈安装五种方式与可复制配置3.1 环境准备dsh 本体是 Node.jsTypeScript项目官方要求 Node^22.19 || 24。Node 23 这种奇数版本会直接启动失败别踩。检查本机版本node -v npm -v没有 Node 就去 nodejs.org 下 LTS 安装包Windows 用.msi一键装记得勾 Add to PATH。Windows 用户注意Web UI 全平台可用但 PTY 相关能力官方只支持 Linux/macOS重度使用建议 WSL2。3.2 方式一npx 一条命令启动最快npx deepseek-ai/dsh web首次运行自动下载缓存启动后浏览器访问http://127.0.0.1:3080看到 Web UI 即成功。3.3 方式二全局安装npm install -g deepseek-ai/dsh dsh web装完dsh --help看子命令dsh --version看版本。3.4 方式三源码编译二次开发git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness npm install -g pnpm pnpm install pnpm run build pnpm dsh web3.5 方式四免安装绿色版官方提供打包了 Node 运行时的绿色压缩包Linux/macOS解压直接跑tar -xzf deepseek-harness-*.tar.gz cd deepseek-harness-* ./dsh web3.6 方式五Python SDK内置运行时不想装 Node 就用 Python SDKpip 安装时自动捆绑 Node 运行时Python 3.10 即可pip install deepseek-harness-sdkfrom deepseek_harness_sdk import DeepSeekHarness, ModelConfig harness DeepSeekHarness( modelModelConfig(model_iddeepseek-v4-flash), ) response harness.run(帮我写一个 Python 快速排序并给出注释) print(response)3.7 国内网络加速npm config set registry https://registry.npmmirror.com pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/dsh 本体是纯开源项目官方 API 走api.deepseek.com国内直连即可。4. 模型配置config.toml 骨架与 settings.yaml4.1 获取 Key在 DeepSeek 开放平台注册登录进「API Keys」创建密钥只显示一次立即复制。新用户一般有免费额度日常按量计费V4-Flash 单价很低。4.2 Web UI 配置启动dsh web后打开http://127.0.0.1:3080进 Settings → Models找到 DeepSeek 卡片粘贴 Key 保存无需重启即可选模型对话。默认两个模型deepseek-v4-pro旗舰和deepseek-v4-flash快速经济均支持 1M 上下文、256K 最大输出。4.3 自定义 OpenAI 兼容端点接 TaoTokenSettings → Models 支持添加供应商。选 Custom Provider填字段值Provider IDtaotoken小写字母开头创建后不可改Base URLhttps://taotoken.net/api协议OpenAI Chat Completions 兼容API Key你的 TaoToken Key模型列表手动填或点 Fetch available models 拉取4.4 settings.yaml 手写配置进阶用户直接编辑~/.dsh/settings.yaml配置目录可用DSH_HOME改。下面是一份可复制的骨架把 TaoToken 作为统一通道llm-pi-ai: providers: taotoken: apiKeyEnv: TAOTOKEN_API_KEY api: openai-completions baseURL: https://taotoken.net/api models: - id: deepseek-v4-flash - id: deepseek-v4-pro字段含义apiKeyEnv从环境变量读 Key比明文安全api协议类型OpenAI 兼容即openai-completionsbaseURL网关地址models该供应商暴露的模型 ID 列表。4.5 环境变量适合 CI / 无头模式 / 脚本化调用export TAOTOKEN_API_KEYsk-xxxxxx export DEEPSEEK_BASE_URLhttps://taotoken.net/api export DSH_MODELdeepseek-v4-flash export DSH_SYSTEM_PROMPT你是一名嵌入式 Linux 内核驱动专家 export DSH_HOME~/.dsh4.6 视觉模型配置默认模型只接受文本。要用多模态模型需在 settings.yaml 显式声明输入类型llm-pi-ai: providers: taotoken: api: openai-completions baseURL: https://taotoken.net/api models: - id: qwen-vl-max input: [text, image]声明后 UI 才会出现图片上传入口。4.7 四种工作模式与权限级别dsh 内置四个 ProfileStandard日常、Code/PTC编程重工具调用、Minimal仅 bash str_replace_editor 两个工具、Creator长文输出。切换用 Web UI 顶部下拉或dsh web --profile code。权限级别从高到低Read Only只读、Workspace Write工作区内读写日常推荐、Full access全盘可写不推荐。必须先选工作区输入框才启用这是刻意的安全设计。4.8 无头模式dsh --profile headless 帮我重构 src/utils.ts 中的重复代码 dsh --dump-config--dump-config输出完整插件树是排查插件装了没生效的神器。5. 飞书接入四条路线与验证回执5.1 路线一飞书智能伙伴平台零代码只想让飞书对话调 DeepSeek 模型、不追求工具调用用飞书智能伙伴搭建平台最快创建智能伙伴 → 选「自定义模型」→ 填 Base URLhttps://taotoken.net/api、API Key、模型名deepseek-v4-flash→ 配 System Prompt → 发布。全程可视化但只能对话不能跑命令改文件。5.2 路线二dsh-lark 插件推荐专为 dsh 打造的飞书接入插件一条命令dsh plugin add github:omdsh-dev/dsh-lark安装后按提示扫码创建飞书应用即完成授权无需公网回调。功能私聊/群聊派任务、实时查看执行过程、交互式卡片审批、多 Agent 同群协作、每个会话独立 Agent。5.3 路线三dsh-feishu-bridge企业自建应用dsh plugin add github:zhbdream/dsh-feishu-bridge在 open.feishu.cn 创建企业自建应用开启机器人能力订阅im.message.receive_v1用长连接模式免公网 IP把 App ID / App Secret 填入 bridge 配置启动。5.4 路线四通用 lark_oapi 手搓不依赖插件用官方 SDK 写转发服务import openai from lark_oapi.api.im.v1 import CreateMessageRequestBody, ReplyMessageRequest from lark_oapi.ws import Client as WsClient client openai.OpenAI( api_keysk-xxxxxx, base_urlhttps://taotoken.net/api, ) def on_message(data): text data.message.content if not text or text.startswith(/): return resp client.chat.completions.create( modeldeepseek-v4-flash, messages[{role: user, content: text}], ) answer resp.choices[0].message.content reply ReplyMessageRequest.builder() \ .message_id(data.message.message_id) \ .request_body(CreateMessageRequestBody.builder() .msg_type(text) .content(f{{text:{answer}}}) .build()) \ .build() ws_client.im.v1.message.reply(reply) ws_client WsClient(app_id, app_secret, event_handleron_message) ws_client.start()扩展方向在回调里把文本交给 dsh 的 Python SDK 执行即可获得完整 Agent 能力。5.5 四条路线对比路线成本部署复杂度能力适用场景智能伙伴平台零代码最低仅对话快速加问答助手dsh-lark 插件免费开源低完整 Agent 卡片审批个人/小团队dsh-feishu-bridge免费开源中完整 Agent企业内网通用 lark_oapi免费高自定深度定制6. 验证请求与成功结果配置完别急着用按这三步验证。第一步启动自检dsh --dump-config输出里应能看到你配置的供应商节点和插件树确认没有MISSING_CREDENTIAL。第二步模型连通性测试。启动 Web UI选好工作区发一句用一句话说明你当前使用的模型 ID能正常回复即通道打通。如果报UNKNOWN_MODEL检查settings.yaml里的models列表和实际请求的模型 ID 是否一致。第三步飞书消息回执。在飞书里私聊机器人发帮我写一个计算器机器人应回复思考过程与执行进度完成后把结果回传。看到卡片审批弹出、点同意后继续执行说明整条链路通了。7. 免费模型可行性为什么 429 必现社区问得最多的是能不能像 OpenCode 一样白嫖免费模型。结论不能。OpenCode 内置 OpenCode Zen 网关有 5 个免费模型deepseek-v4-flash-free、MiMo、Big Pickle、Nemotron、North Mini无需 Key 即可开聊。但把这类免费端点配进 dsh 后首个请求可能成功随后立即报Error: FreeUsageLimitError: 429 Too Many Requests OpenCode Zen free model usage limit exceeded原因是免费档按每分钟请求数 每日总量双重限流而 Agent 工具调用是高频突发请求一个任务动辄几十次模型调用远高于普通聊天节奏几乎必然撞限。免费模型只适合聊天式低频使用dsh 的 Agent 工作负载别依赖它。现实建议轻度体验用官方 API 按量V4-Flash 单价很低正经开发用官方 API 或统一网关省钱技巧是把默认模型设为deepseek-v4-flash复杂任务再手动切v4-pro成本可降一个数量级。8. 本篇常见错排查启动报 MISSING_CREDENTIAL / UNKNOWN_MODEL没配 Key或模型 ID 与供应商不匹配。去 Settings → Models 配 Key自定义模型确认 ID 与 settings.yaml 一致。Node 23 启动失败官方要求^22.19 || 24奇数版本不支持。用 nvm/n 切换或改用绿色版/Python SDK。想改端口 / 局域网访问dsh web --port 8080可改端口--host 0.0.0.0目前被 CLI 拒绝官方不支持局域网共享可用飞书插件或自行转发。Windows 上 PTY 异常官方只支持 Linux/macOS 的 PTYWindows 用户用 WSL2 或 Python SDK。插件装了不生效三步排查——dsh plugin list看状态是否 enableddsh --dump-config看插件树里是否出现该节点看启动日志插件 setup 抛错会被内核捕获但进程不退出。Bash 工具空转noop loop社区反馈 Agent 偶尔陷入重复执行无效果命令的循环用 Minimal Profile 或超时配置缓解关注仓库 issue 区。会话记录在哪会话日志为 append-only可在 Web UI 的 Trajectory 视图回放每一步工具调用数据文件在~/.dsh下。兼容 AGENTS.md / CLAUDE.md 吗兼容dsh 会读取项目里的这两个文件作为上下文还支持 MCP 客户端挂 MCP 工具。生产环境能用吗官方明确警告开发者预览版随时可能破坏性变更不建议生产依赖等 1.0。9. 下一步按场景选入口排障和接入相关的先去把 Key 和文档过一遍API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。只想先验证模型通不通的用模型对话页面最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。长期跑编码任务或 Agent 的看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。Claude Code 相关接入参考https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后一句实操经验每次升级 dsh 前先备份~/.dsh配置 会话升级后先dsh --dump-config确认插件树正常再动别的。预览期接口变动快这一步能省你不少回滚时间。