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

说明：

适用读者：想体验 DeepSeek 官方 Agent 框架的开发者、想把 DeepSeek 接入飞书/Lark 的团队、想理解或开发 Agent 插件的开发者
环境要求：Windows / Linux / macOS 均可（Web UI 全平台可用，PTY 相关能力官方只支持 Linux/macOS）
更新时间：2026-08-20
结论速览：dsh 处于开发者预览阶段（v0.1.0-rc），安装只需一条命令，模型配置零门槛，飞书有三条成熟接入路线；"一切皆插件"是其架构核心——模型、工具、存储、Agent 循环、沙箱、审批、UI 全部可替换；但"像 OpenCode 一样内置免费模型"目前不可行——OpenCode Zen 的免费模型在 dsh 高频调用下必然触发 429 限流，正经任务建议用 OpenCode Go 或官方 DeepSeek API。

DeepSeek Harness 是什么
"一切皆插件"架构原理（核心章节）
- 2.1 Cordis 微内核：内核只做四件事
- 2.2 可替换的核心组件清单
- 2.3 插件树与 cordis.patch.yml
- 2.4 插件生命周期
- 2.5 插件体系 vs 普通 hooks 钩子
全栈安装
- 3.1 环境准备（Node.js 版本检查）
- 3.2 方式一：npx 一条命令启动（最快）
- 3.3 方式二：全局安装
- 3.4 方式三：源码编译（适合二次开发）
- 3.5 方式四：免安装绿色版
- 3.6 方式五：Python SDK（内置运行时）
- 3.7 国内网络加速
配置模型
- 4.1 获取 DeepSeek API Key
- 4.2 在 Web UI 中配置模型
- 4.3 内置供应商与自定义 OpenAI 兼容端点
- 4.4 settings.yaml 手写配置
- 4.5 环境变量
- 4.6 视觉模型配置
- 4.7 四种工作模式
- 4.8 权限级别
- 4.9 无头模式与命令行
配置飞书（Lark）
- 5.1 路线一：飞书智能伙伴平台（零代码）
- 5.2 路线二：dsh-lark 官方社区插件（推荐）
- 5.3 路线三：dsh-feishu-bridge（企业自建应用）
- 5.4 路线四：通用企业自建应用（lark_oapi 手搓）
- 5.5 四条路线对比
免费模型：能否像 OpenCode 一样白嫖
- 6.1 OpenCode Zen 的免费模型
- 6.2 实测：免费模型在 dsh 中的 429 限流
- 6.3 现实建议
dsh 与 OpenCode 选型对比
网上实用插件盘点
- 8.1 消息平台接入类
- 8.2 工具能力增强类
- 8.3 存储与记忆类
- 8.4 安全与审批类
- 8.5 集成与部署类
- 8.6 如何发现插件
插件开发实战：亲手写一个插件
- 9.1 项目骨架（manifest + 入口）
- 9.2 注册一个自定义工具
- 9.3 安装并验证
- 9.4 替换核心组件：自定义审批策略
- 9.5 发布与分享
当前存在的问题与风险

10.1 稳定性与兼容性
10.2 插件生态问题
10.3 安全风险
10.4 运行时问题
10.5 缓解措施清单

常见问题与已知限制
参考资料

1. DeepSeek Harness 是什么

DeepSeek Harness（简称 dsh）是 DeepSeek 官方于 2026 年 8 月 13 日随 DeepSeek V4-Pro 开源发布的自主 Agent 运行时框架（Agent Harness），采用 MIT 协议，当前版本 0.1.0-rc.6（开发者预览版，官方明确提示"将出现破坏性变更，请勿用于生产环境"）。

核心设计理念是"一切皆插件"（基于 Cordis 微内核架构）：模型、工具、会话存储、Agent 循环、沙箱、审批策略、UI 层全部可替换。官方文档的原话是：

自主编程代理 = 强大的模型 + 优秀的运行时（harness）。我们开源了运行时，让社区可以自由组合模型、工具与工作流。

与其他 Agent 工具的核心区别：

维度	DeepSeek Harness (dsh)	OpenCode / Claude Code / Codex CLI
定位	官方 Agent 运行时框架（可组合、可插拔）	开箱即用的编程 Agent 产品
插件体系	插件可替换核心组件（会话存储、沙箱、工具管线、子代理、UI）	插件主要是钩子（hooks）与工具（tools）
默认模型	DeepSeek V4 系列	各自绑定自家模型生态
状态	开发者预览，破坏性变更中	生产可用
开源协议	MIT	Apache-2.0（OpenCode）/ 专有（Claude Code、Codex）

一句话理解：OpenCode 是"装好就能用的成品车"，dsh 是"零件全部可换的官方底盘"。日常开发选前者，想深度定制 Agent 行为可以研究后者。

2. "一切皆插件"架构原理（核心章节）

2.1 Cordis 微内核：内核只做四件事

dsh 的"一切皆插件"不是营销话术，而是实打实的架构选择：它构建在 Cordis（MIT 协议的开源微内核框架）之上。Cordis 内核本身不包含任何 Agent 业务逻辑，只负责四件事：

内核职责	说明	类比
插件加载与生命周期	发现、安装、启用、停用、卸载插件，管理依赖顺序	操作系统的 init 系统
服务注册表（Context）	插件通过 Context 注册服务、获取其他插件提供的服务	操作系统的设备驱动接口
事件总线	插件之间通过事件解耦通信（如 `message.received`、`tool.executed`）	操作系统的中断/事件机制
配置管理	合并各插件的配置 schema，提供统一配置入口	操作系统的注册表

关键推论：既然内核不含业务逻辑，那么 dsh 的所有行为——能聊什么、能跑什么命令、能改什么文件、怎么审批、怎么存会话、长什么样——全部来自插件。这就是"一切皆插件"的字面含义：不是"功能通过插件扩展"，而是"功能本身就是插件"。

┌─────────────────────────────────────────────────────────┐
│                    Cordis 微内核                          │
│   插件加载 │ 服务注册表 │ 事件总线 │ 配置管理             │
└──────┬──────────┬──────────┬──────────┬─────────────────┘
       │          │          │          │
  ┌────▼───┐ ┌────▼────┐ ┌───▼────┐ ┌───▼───────┐
  │模型插件│ │工具插件 │ │存储插件│ │ UI 插件   │   ← 全部可替换
  │DeepSeek│ │bash     │ │SQLite  │ │Web UI    │
  │Anthropic││编辑器  │ │文件系统│ │TUI       │
  │Ollama  │ │MCP桥接  │ │内存    │ │Headless  │
  └────────┘ └─────────┘ └────────┘ └───────────┘

2.2 可替换的核心组件清单

这是 dsh 与"hooks 型"Agent 工具最本质的差异。以下每个组件都对应一个插件接口，你可以写插件替换掉默认实现：

组件	默认实现	替换它的意义	自定义示例
模型适配器	OpenAI 兼容客户端	接入任何模型/网关（Ollama、vLLM、one-api、自家推理服务）	写一个调用内部 RAG 网关的模型插件
工具管线	bash、str_replace_editor 等内置工具	增删 Agent 可用工具集，限定能力边界	只留 3 个白名单工具的安全模式
Agent 循环	默认的思考-行动-观察循环	改变 Agent 的决策策略（如增加自省、规划层）	实现"先写计划再执行"的 Plan-Act 循环
会话存储	本地文件（append-only）	把会话/轨迹接入团队知识库、数据库	写 SQLite/PostgreSQL 存储插件
沙箱	直接执行（宿主机）	把命令执行放进 Docker/虚拟机隔离	写 Docker 沙箱插件，工具命令全在容器里跑
审批策略	内置权限级别（ReadOnly/Workspace/Full）	自定义审批流（人工卡片审批、规则自动批准）	飞书卡片审批、高危命令必须人工确认
UI 层	Web UI	换皮肤、换交互形态、或完全无 UI	TUI 终端界面、VS Code 扩展
消息通道	无（本地 Web UI）	接入 IM 平台，让 Agent 进入聊天群	dsh-lark（飞书）、TG、Slack 插件

2.3 插件树与 cordis.patch.yml

dsh 的插件不是平铺的一堆脚本，而是按依赖关系组成一棵插件树。插件可以依赖其他插件（requires），也可以显式替换树上的某个节点（provides 同名服务时后者生效）。

当你想替换某个核心组件时，不需要改 dsh 源码——在 ~/.dsh/cordis.patch.yml 里声明"把节点 X 换成插件 Y"即可：

# ~/.dsh/cordis.patch.yml —— 插件树补丁
# 含义：把默认的 bash 工具替换为自定义安全版本
patch:
  - target: tool.bash            # 定位树上的节点
    replace: my-security-bash    # 换成这个插件提供的服务
  - target: storage.session
    replace: my-sqlite-storage

查看当前完整插件树（排查"插件装了但没生效"的神器）：

dsh --dump-config
# 输出：从内核到每个插件的完整树状结构，包含启停状态

2.4 插件生命周期

阶段	命令	说明
安装	`dsh plugin add <来源>`	支持 npm 包名、GitHub 地址、本地路径
启用/停用	`dsh plugin enable <名>` / `dsh plugin disable <名>`	不删除，可随时切换
查看	`dsh plugin list`	已安装插件清单与状态
卸载	`dsh plugin remove <名>`	删除插件（配置保留）

插件启动顺序由依赖关系决定：被依赖的插件先启动，依赖者后启动；启动失败不影响整个进程（内核会记录错误并继续）。

2.5 插件体系 vs 普通 hooks 钩子

维度	dsh（一切皆插件）	OpenCode / Claude Code（hooks）
扩展点	整个运行时组件都可替换	只能在预定义事件点挂钩子
替换核心	可以（存储、沙箱、审批、循环全可换）	不可以（内核是黑盒）
学习成本	高（要理解 Cordis 模型）	低（写个脚本挂上即可）
稳定性	预览期接口频繁变动	成熟稳定
适合场景	构建自己的 Agent 产品/实验台	日常给现成 Agent 加行为

通俗理解：hooks 是"在汽车的既有接口上加装设备"；dsh 的插件体系是"整车的每一个部件都是可拆卸的，你可以自己造发动机换上去"。前者安全省事，后者灵活强大但要求你懂车。

3. 全栈安装

3.1 环境准备（Node.js 版本检查）

dsh 本体是 Node.js（TypeScript）项目，官方要求 Node ^22.19 || >=24。注意：

Node 23（奇数版本）会直接启动失败，请使用 22.19+ 或 24+ 的 LTS/Current 版本
部分教程写"Node v18+ 即可"，但官方文档要求更严格，建议以官方要求为准
检查本机版本：

node -v
npm -v

如果没有 Node，去 nodejs.org 下载 LTS 安装包（Windows 用 .msi 一键安装，安装时勾选 "Add to PATH"）。

Windows 用户注意：官方说明 Web UI 全平台可用，但 PTY 相关能力（伪终端交互）官方只支持 Linux/macOS。Windows 上重度使用建议 WSL2，或使用下面 3.6 节的 Python SDK / 绿色版（官方打包运行时同样仅提供 Linux/macOS 版本）。

3.2 方式一：npx 一条命令启动（最快）

npx @deepseek-ai/dsh web

首次运行会自动下载并缓存 dsh，启动后浏览器访问：

http://127.0.0.1:3080

看到 Web UI 即安装成功。之后每次启动都执行同一条命令即可（npx 会优先使用缓存，速度很快）。

3.3 方式二：全局安装

适合需要固定版本、离线使用或频繁启动的场景：

npm install -g @deepseek-ai/dsh
dsh web

安装后可执行 dsh --help 查看所有子命令，dsh --version 查看版本。

3.4 方式三：源码编译（适合二次开发）

想改源码、贡献插件、或者验证最新 commit 时使用：

# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 安装 pnpm（若已有可跳过）
npm install -g pnpm

# 安装依赖并构建
pnpm install
pnpm run build

# 启动 Web UI
pnpm dsh web

源码方式可以 git pull 随时跟进最新开发版。

3.5 方式四：免安装绿色版

官方官网 deepseekagent.io 提供打包了 Node 运行时的绿色压缩包（Linux/macOS 版本），下载解压后直接运行，不需要预装 Node：

# 以 Linux x64 为例（具体文件名以官网为准）
tar -xzf deepseek-harness-*.tar.gz
cd deepseek-harness-*
./dsh web

适合服务器、CI 环境、或者不想动本机 Node 版本的用户。

3.6 方式五：Python SDK（内置运行时）

不需要 Node。dsh 官方提供 Python SDK（deepseek-harness-sdk），pip 安装时会自动捆绑 Node 运行时，Python 3.10+ 即可（官方支持 Linux x64/arm64、macOS 14+ arm64）：

pip install deepseek-harness-sdk

然后就可以在 Python 代码中直接驱动 Agent：

from deepseek_harness_sdk import DeepSeekHarness, ModelConfig

harness = DeepSeekHarness(
    model=ModelConfig(model_id="deepseek-v4-flash"),
)

response = harness.run("帮我写一个 Python 快速排序，并给出注释")
print(response)

SDK 还提供流式输出、轨迹（trajectory）读取、会话管理等高级 API，适合把 dsh 嵌入自有工具链。

3.7 国内网络加速

npm 默认源下载慢时，切换到国内镜像：

npm config set registry https://registry.npmmirror.com

pip 同理：

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

注意：dsh 本体是纯开源项目，官方 API 调用走 api.deepseek.com，国内直连即可，不需要代理。

4. 配置模型

4.1 获取 DeepSeek API Key

打开 platform.deepseek.com 注册登录
左侧菜单进入「API Keys」
点击「创建 API Key」，密钥只显示一次，请立即复制保存（关闭弹窗后无法再次查看，只能重建）
新用户一般有免费额度（以官网当前活动为准），日常使用按量计费，V4-Flash 价格很低

4.2 在 Web UI 中配置模型

启动 dsh web 后：

打开 http://127.0.0.1:3080
进入 Settings（设置）→ Models（模型）
找到 DeepSeek 卡片，粘贴 API Key，点击保存
无需重启，直接在左侧选择模型即可对话

配置说明：

API Key 属于只写（write-only）字段，保存后不会回显，实际存储在 ~/.dsh/.credentials.yaml（权限 0600）
默认提供两个官方模型：
- deepseek-v4-pro：旗舰模型，复杂推理、大型代码任务
- deepseek-v4-flash：快速经济模型，日常迭代首选
- 两者均支持 1M 上下文、256K 最大输出、high 推理强度

与 OpenCode 的对比：OpenCode 首次启动内置 OpenCode Zen 免费模型、无需任何 Key 即可开聊；dsh 必须配置模型供应商，这是两兄弟上手体验最大的差异，详见第 6 节。

4.3 内置供应商与自定义 OpenAI 兼容端点

Settings → Models 页面支持添加供应商：

内置目录：DeepSeek、Anthropic、OpenAI、AWS Bedrock、Azure、Google Vertex 等，点选后填入各自 API Key 即可
自定义供应商（Custom Provider）：任何 OpenAI 兼容的网关/中转/本地服务（Ollama、vLLM、one-api、new-api 等）都可以接入，需要配置：
- Provider ID：小写字母开头，创建后不可修改（永久标识）
- Base URL：如 https://api.example.com/v1
- 协议：OpenAI Chat Completions 兼容
- API Key：对应网关密钥
- 模型列表：可手动填写，或点击 "Fetch available models" 自动拉取

配置完成后回到聊天页即可切换模型。

4.4 settings.yaml 手写配置

进阶用户可以直接编辑 ~/.dsh/settings.yaml（配置目录可通过环境变量 DSH_HOME 修改）。示例——接入一个自定义 OpenAI 兼容网关：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://api.example.com/v1
      models:
        - id: model-name-here

字段含义：

apiKeyEnv：API Key 从环境变量 GATEWAY_API_KEY 读取（比明文写在 yaml 里安全）
api：协议类型，OpenAI 兼容即 openai-completions
baseURL：网关地址，必须以 /v1 结尾的兼容路径为准
models：该供应商暴露的模型 ID 列表

配置目录结构（~/.dsh/）：

~/.dsh/
├── profiles/          # 配置文件（standard、code、minimal、creator、headless、tui 等）
├── .credentials.yaml  # API Key（只写，0600）
├── settings.yaml      # 全局设置（供应商、模型、系统提示词等）
└── cordis.patch.yml   # 插件树补丁（高级：替换核心组件，见 2.3）

4.5 环境变量

常用环境变量（适合 CI / 无头模式 / 脚本化调用）：

export DEEPSEEK_API_KEY=sk-xxxxxx        # DeepSeek API Key
export DEEPSEEK_BASE_URL=https://api.deepseek.com  # 可替换为兼容网关
export DSH_MODEL=deepseek-v4-flash       # 默认模型
export DSH_SYSTEM_PROMPT="你是一名嵌入式 Linux 内核驱动专家"  # 默认系统提示词
export DSH_HOME=~/.dsh                   # 配置目录（默认 ~/.dsh）

4.6 视觉模型配置

默认模型只接受文本输入。若要使用多模态模型（如 GLM-4V、Qwen-VL 或中转站的多模态模型），需要在 settings.yaml 中显式声明输入类型：

llm-pi-ai:
  providers:
    my-gateway:
      api: openai-completions
      baseURL: https://api.example.com/v1
      models:
        - id: qwen-vl-max
          input: [text, image]   # 声明支持图像输入，UI 才会出现图片上传

4.7 四种工作模式

dsh 内置四个 Profile（配置文件），对应不同形态：

模式	说明	适用场景
Standard	标准模式，完整工具集与对话	日常使用
Code（PTC）	编程模式，重工具调用、少废话	写代码、跑命令
Minimal	仅 2 个工具（`bash` + `str_replace_editor`），最少依赖	限制 Agent 行为、最小攻击面
Creator	创意模式，宽松格式、长文输出	写作、方案设计

切换方式：Web UI 顶部 Profile 下拉选择；或启动时指定 dsh web --profile code。

4.8 权限级别

在 Web UI 中选择工作区（Workspace）后，可配置 Agent 的文件访问权限（安全由高到低）：

Read Only：只能读文件，不能写（最安全）
Workspace Write：只能在选定的工作目录内读写（日常推荐）
Full access：全盘可写（不推荐，风险自担）

重要提示：必须先选择工作区，输入框才会启用。这是一个刻意的安全设计——Agent 必须明确知道"战场"在哪里。

4.9 无头模式与命令行

适合脚本、CI、定时任务：

# 一次性执行任务（不启动 Web UI）
dsh --profile headless "帮我重构 src/utils.ts 中的重复代码"

# 查看完整插件树（调试插件加载问题）
dsh --dump-config

Web UI 常用参数：

dsh web --port 8080     # 改端口
dsh web --host 0.0.0.0  # 注意：官方 CLI 目前拒绝 --host 绑定，只监听本机

5. 配置飞书（Lark）

"在飞书里发一句话，本机 DeepSeek Harness 就开干"——目前有四条成熟路线，按推荐程度排序。

5.1 路线一：飞书智能伙伴平台（零代码）

如果只是想让飞书对话直接调用 DeepSeek 模型（不追求 Agent 工具调用），最快的方式是用飞书智能伙伴搭建平台（aily，https://aily.feishu.cn 或飞书内搜索"智能伙伴"）：

进入智能伙伴搭建平台，创建智能伙伴
选择「自定义模型」接入方式
填入：
- Base URL：https://api.deepseek.com
- API Key：你的 DeepSeek Key
- 模型名：deepseek-v4-flash（或 v4-pro）
配置指令（System Prompt），保存发布

优点：全程可视化、零代码、不需要服务器。缺点：调用的是模型 API 而非完整 Agent，不能执行工具（跑命令、改文件）。

5.2 路线二：dsh-lark 官方社区插件（推荐）

omdsh-dev/dsh-lark（npm 包名 dsh-lark-channel，BSD-3-Clause）是专为 dsh 打造的飞书接入插件，安装一条命令：

dsh plugin add github:omdsh-dev/dsh-lark

安装后按提示扫码创建飞书应用即完成授权，无需配置公网回调地址。功能特性：

私聊/群聊派任务：在飞书里 @机器人或私聊发需求，dsh 在本机执行
实时查看执行过程：推理过程与工具调用以原生"思考过程"形态展示
交互式卡片审批：Agent 提问、计划确认、工具执行审批都会弹出飞书卡片，点头/拒绝即可
多 Agent 同群协作：群内可指定不同 Agent 分工，互不干扰
无需公网 IP：插件通过长连接/扫码授权与飞书通信，个人电脑、内网机器都能用
每个会话独立 Agent：飞书会话与 dsh 会话一一对应，上下文隔离

使用流程：私聊机器人发"帮我写一个计算器"，机器人回复思考过程与执行进度，完成后把结果/文件回传群聊。

5.3 路线三：dsh-feishu-bridge（企业自建应用）

zhbdream/dsh-feishu-bridge 是另一个 dsh 飞书桥接插件（dsh-plugin），2026-08-14 发布，核心理念：

飞书发一句话，本机 DeepSeek Harness 就开干，执行结果回到飞书。

特点：

仅需企业自建应用：在 open.feishu.cn 创建企业自建应用即可，不需要企业认证、不需要付费版（组织内部使用）
长连接收事件：应用开启长连接（WebSocket）模式，无需公网 IP、无需反向隧道，内网机器直接可用
提供安全模型、兼容版本、配置详解、飞书权限等完整文档（仓库 docs/ 目录）

大致步骤：

open.feishu.cn 创建企业自建应用
开启「机器人」能力，订阅消息事件
应用级配置勾选必要权限（读消息、发消息、上传文件等）
将 App ID / App Secret 填入 bridge 配置并启动
在飞书里与机器人对话

5.4 路线四：通用企业自建应用（lark_oapi 手搓）

不依赖任何 dsh 插件，通用做法（适用于任何 OpenAI 兼容 Agent）：

创建应用：打开 open.feishu.cn → 创建企业自建应用
开启机器人能力：应用能力 → 机器人 → 启用
订阅事件：事件订阅 → 选择长连接模式（免公网 IP）→ 订阅 im.message.receive_v1（接收消息）
添加权限：im:message（读写消息）、im:message:send_as_bot（发消息）
写一个转发服务（Python 示例，使用官方 lark_oapi SDK）：

import openai
from lark_oapi.api.im.v1 import (
    CreateMessageRequest, CreateMessageRequestBody, ReplyMessageRequest,
)
from lark_oapi.ws import Client as WsClient

# DeepSeek 对话客户端（OpenAI 兼容）
client = openai.OpenAI(
    api_key="sk-xxxxxx",
    base_url="https://api.deepseek.com",
)

def on_message(data):
    text = data.message.content  # 收到的消息文本
    if not text or text.startswith("/"):
        return
    # 调用 DeepSeek
    resp = client.chat.completions.create(
        model="deepseek-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_handler=on_message)
ws_client.start()  # 长连接，无需公网回调

这条路线的扩展方向：在回调里把文本交给 dsh 的 Python SDK 执行（而非只调 Chat API），即可获得完整 Agent 能力。

5.5 四条路线对比

路线	成本	部署复杂度	能力	适用场景
智能伙伴平台（5.1）	零代码	最低	仅对话（无工具）	快速给团队加个 DeepSeek 问答助手
dsh-lark 插件（5.2）	免费开源	低（一条命令）	完整 Agent + 卡片审批 + 多 Agent	个人/小团队重度使用
dsh-feishu-bridge（5.3）	免费开源	中	完整 Agent	企业组织内部使用
通用 lark_oapi（5.4）	免费	高（写代码）	自定	深度定制、集成现有系统

6. 免费模型：能否像 OpenCode 一样白嫖

这是社区问得最多的问题，先说结论：

不能。 dsh 目前没有内置免费模型。把 OpenCode Zen 的免费模型强行配进 dsh，高频调用下必然触发 429 FreeUsageLimitError，实际不可用。

6.1 OpenCode Zen 的免费模型

OpenCode 的"开箱即用"体验来自其内置的 OpenCode Zen 网关，内置 5 个免费模型，无需任何 API Key：

免费模型	说明
`deepseek-v4-flash-free`	DeepSeek V4 Flash 免费档
`MiMo`	Xiaomi 开源模型免费档
`Big Pickle`	数学/推理向模型免费档
`Nemotron`	NVIDIA 开源模型免费档
`North Mini`	轻量模型免费档

这就是 OpenCode 零配置可用的原因（详见 Installer-01安装opencode（免费api模型）.md）。

6.2 实测：免费模型在 dsh 中的 429 限流

社区实测（GitHub 讨论 deepseek-ai/deepseek-harness issues/1455）：

把 OpenCode Zen 的免费端点（https://opencode.ai/zen 或类似地址）作为自定义供应商配进 dsh 后，首个请求可能成功，随后立即出现：

Error: FreeUsageLimitError: 429 Too Many Requests
OpenCode Zen free model usage limit exceeded

原因：免费档的限流策略按"每分钟请求数 + 每日总量"双重限制，而 Agent 工具调用是高频突发请求（一个任务动辄几十次模型调用），远高于普通聊天的消耗节奏，几乎必然撞限。
结论：免费模型只适合 OpenCode 的聊天式低频率使用；dsh 的 Agent 工作负载请勿依赖免费档。

6.3 现实建议

使用方式	推荐	成本
轻度体验 dsh（几十分钟）	官方 DeepSeek API 按量	几乎为零（V4-Flash 单价很低）
正经开发任务	官方 DeepSeek API / 企业网关	按 token 计费，Flash 很便宜
想要低成本+够用的 Agent	OpenCode Go 订阅	首月 $5 送 $60 额度
深度定制 Agent 运行时	dsh + 官方 API / 内部网关	按量

省钱小技巧：dsh 里把默认模型设为 deepseek-v4-flash（而非 v4-pro），日常任务成本可降低一个数量级；复杂任务再手动切 v4-pro。

7. dsh 与 OpenCode 选型对比

2026-08 最新的独立对比评测（myclaw.ai 中文版）结论：

日常开发：OpenCode 更成熟——75+ 模型供应商目录、终端/桌面/IDE 多形态、生产级插件生态、更完善的工作流
研究探索：dsh 胜在"高度可组合的运行时"——想研究 Agent 内部机制、替换核心组件、构建自己的 Agent 形态，dsh 是更好的实验台
模型支持：两者都能跑 DeepSeek 模型；OpenCode 通过 Zen 免费模型零配置上手，dsh 需要配置供应商
代码质量：目前没有权威的代码质量正面对比数据，选型主要看生态成熟度与定制需求

一句话：要"能干活"选 OpenCode，要"研究/定制 Agent 本体"选 dsh。两边都装也没问题——dsh 的配置目录独立，与 OpenCode 零冲突。

8. 网上实用插件盘点

dsh 发布仅一周，生态还在爆发式增长期（GitHub 上以 dsh-plugin / deepseek-harness 为关键词的插件仓库每天都在增加）。以下按类别盘点目前（2026-08）网上实用、可用的插件与集成方案，类别通用、示例为当时可查证者，搜索时用 GitHub topic dsh-plugin 可发现最新列表。

8.1 消息平台接入类（把 Agent 搬进 IM，最活跃的一类）

插件/方案	平台	安装/接入	亮点
`dsh-lark`（omdsh-dev/dsh-lark）	飞书	`dsh plugin add github:omdsh-dev/dsh-lark`	扫码即用、卡片审批、多 Agent、免公网 IP，见 5.2
`dsh-feishu-bridge`（zhbdream/dsh-feishu-bridge）	飞书	企业自建应用	企业内网使用、长连接免公网，见 5.3
TG 类插件	TG	社区多个 `dsh-plugin` 仓库	创建 Bot Token 即可接入，适合个人远程派活
钉钉/企微类插件	钉钉、企业微信	社区开发中（钉钉机器人 + 长连接）	国内企业办公场景，与飞书插件同构
Slack 类插件	Slack	社区开发中	海外团队使用

判断一个 IM 插件是否"能用"的要点：① 是否走长连接（免公网 IP）；② 是否支持卡片审批（不只是转发消息）；③ 是否声明了与当前 dsh 版本（v0.1.0-rc.x）的兼容版本。

8.2 工具能力增强类（决定 Agent 能干什么）

插件类型	作用	典型用法
MCP 客户端/桥接	把 MCP 服务器的工具暴露给 dsh（官方已内置 MCP 客户端能力，社区插件多为配置化封装）	挂数据库 MCP、浏览器 MCP、内部 API MCP
浏览器自动化	让 Agent 打开网页、填表单、截图	网页端测试、数据采集任务
网页搜索	给 Agent 联网检索能力（官方默认不含搜索工具）	查文档、查最新 API 用法
CI/CD 工具	暴露 git push / 触发流水线等动作	Agent 完成开发后自动提交并触发构建
内置工具扩展	在 bash/编辑器之外加专用工具（如文件批处理、串口调试）	嵌入式开发者常用：串口工具插件

8.3 存储与记忆类（决定 Agent 记不记得住）

插件类型	作用	适用场景
SQLite/PostgreSQL 会话存储	替换默认文件存储，会话可查询、可备份	团队共享会话、审计
向量记忆/长期记忆	跨会话记住项目偏好与结论	长周期项目、Agent 沉淀团队知识
轨迹导出	把 Trajectory 轨迹导出为 JSON/Markdown	复盘 Agent 行为、喂给评估工具

8.4 安全与审批类（决定 Agent 敢不敢乱动）

插件类型	作用	典型场景
卡片审批策略	高危操作弹卡片人工确认（dsh-lark 已内置）	删文件、改配置、执行未知命令
命令白名单	只允许 Agent 执行白名单命令	生产服务器、受限环境
Docker 沙箱	所有命令在容器内执行，宿主机零接触	恶意/不信任输入、公共演示环境
密钥保护	拦截对密钥文件/环境变量的读写	防止 Agent 把密钥写进代码或日志

8.5 集成与部署类（决定 Agent 好不好接入工作流）

插件/方案	作用
GitHub Actions 集成	CI 里跑无头模式（`dsh --profile headless`），定时执行 Agent 任务
定时任务调度	结合 cron / 系统计划任务，让 Agent 每日自动巡检、生成日报
Python SDK 封装	把 dsh 嵌入自有 Python 工具链（见 3.6），替代裸调 Chat API
配置管理	团队统一分发 settings.yaml / cordis.patch.yml，保证行为一致

8.6 如何发现插件

# 1. GitHub 按 topic 搜索
#    https://github.com/topics/dsh-plugin
#    https://github.com/search?q=dsh-plugin&type=repositories

# 2. npm 按前缀搜索（正式发布的插件都走 npm 分发）
npm search dsh-plugin
npm search deepseek-harness

# 3. 官方渠道
#    - 官方仓库 deepseek-ai/deepseek-harness 的 awesome 列表（若有）
#    - 官方 Discussions 区有人发布插件帖

选插件的检查清单：⭐ 星数与近期提交（避免停更）；📖 是否有 README 文档；🔧 是否声明兼容的 dsh 版本；🔒 是否说明权限与安全模型；🧪 是否有 issue 区可查已知问题。

9. 插件开发实战：亲手写一个插件

"一切皆插件"的最好理解方式是自己写一个。本节带你把一个最小插件从零跑通（TypeScript，Node 环境），全程约 15 分钟。

9.1 项目骨架（manifest + 入口）

mkdir my-dsh-plugin && cd my-dsh-plugin
npm init -y
npm install --save-dev @deepseek-ai/dsh-plugin-sdk   # 插件 SDK（类型定义与工具函数）

创建插件清单 plugin.json（声明插件身份与依赖）：

{
  "name": "my-hello-plugin",
  "version": "0.1.0",
  "description": "注册一个 say_hello 工具：把名字变成问候语",
  "author": "your-name",
  "license": "MIT",
  "main": "dist/index.js",
  "provides": ["tool.say_hello"],
  "requires": ["core.tool-registry"]
}

创建入口 src/index.ts——用 SDK 注册一个自定义工具：

import { definePlugin, ToolSchema } from "@deepseek-ai/dsh-plugin-sdk";

export default definePlugin({
  name: "my-hello-plugin",

  // 插件启动时注册工具
  async setup(ctx) {
    const tool: ToolSchema = {
      name: "say_hello",
      description: "把输入的名字变成一句问候语（示例工具）",
      parameters: {
        type: "object",
        properties: {
          name: { type: "string", description: "要问候的名字" },
        },
        required: ["name"],
      },
      // 工具被 Agent 调用时的执行逻辑
      async execute(args) {
        return { output: `你好，${args.name}！这是来自自定义插件的问候。` };
      },
    };

    ctx.registerTool(tool);
    ctx.logger.info("my-hello-plugin 已启动，say_hello 工具就绪");
  },
});

9.2 构建并安装到 dsh

# 构建（SDK 默认输出 dist/）
npx tsc

# 安装到 dsh：本地路径方式（开发期）
dsh plugin add ./my-dsh-plugin

# 查看是否加载成功
dsh plugin list          # 应显示 my-hello-plugin，状态 enabled
dsh --dump-config        # 插件树中应出现 tool.say_hello 节点

9.3 验证：让 Agent 调用自定义工具

启动 Web UI：

dsh web

在聊天框输入：

帮我用 say_hello 工具给"李工"打个招呼

预期行为：Agent 解析意图 → 调用 say_hello(name="李工") → 回复 你好，李工！这是来自自定义插件的问候。。在 Trajectory（轨迹）视图里可以看到完整的工具调用记录。

如果 Agent 没有主动调用工具，检查：① 插件是否在 dsh plugin list 中 enabled；② 工具 schema 是否正确（参数必填项缺失会静默失败）；③ 当前 Profile 是否启用了工具调用（Code 模式最积极）。

9.4 替换核心组件：自定义审批策略

工具插件是最简单的起点，真正体现"一切皆插件"的是替换核心组件。示例：替换默认审批策略，让删除类命令必须人工确认（通过 cordis.patch.yml 挂载）：

// src/approval.ts —— 自定义审批策略插件
import { definePlugin } from "@deepseek-ai/dsh-plugin-sdk";

export default definePlugin({
  name: "my-approval-policy",
  provides: ["policy.approval"],   // 覆盖默认审批服务

  async setup(ctx) {
    ctx.provide("policy.approval", {
      // 审批规则：包含危险关键词的命令 → 拒绝
      async check(command: string) {
        const dangerous = ["rm -rf", "git push --force", "DROP TABLE"];
        if (dangerous.some((d) => command.includes(d))) {
          return { approved: false, reason: "命中高危命令规则，已拦截" };
        }
        return { approved: true };
      },
    });
  },
});

挂载到 ~/.dsh/cordis.patch.yml：

# 把默认审批策略换成我们的
patch:
  - target: policy.approval
    replace: my-approval-policy

重启 dsh 后，Agent 执行 rm -rf 类命令会被直接拦截——你刚刚替换了 Agent 的一个"器官"。

9.5 发布与分享

# 1. 发布到 npm（插件市场的主要分发渠道）
npm publish

# 2. 或推到 GitHub，让别人一条命令安装
git push origin main
# 使用者：dsh plugin add github:your-name/my-dsh-plugin

# 3. 给插件加上 topic: dsh-plugin，方便被发现
#    GitHub 仓库 → Settings → Topics → 添加 dsh-plugin

发布前自查：README 写清①兼容的 dsh 版本②安装命令③配置项④权限与安全说明；声明 engines.node；不要硬编码密钥；插件即代码——发布到 npm 意味着任何安装你插件的人都信任你的代码，务必审查依赖。

10. 当前存在的问题与风险

dsh 发布仅一周（截至 2026-08-20），"一切皆插件"带来灵活性的同时，也带来了成体系的现实问题。以下是社区反馈 + 文档分析整理的问题清单，按严重程度排序。

10.1 稳定性与兼容性（最大风险）

问题	表现	影响
开发者预览，破坏性变更频繁	官方明确警告"将出现破坏性变更，请勿用于生产环境"；rc 版本号迭代快（rc.6 已出）	升级可能改配置文件格式、插件 API、会话格式
会话格式无兼容承诺	官方声明会话/轨迹格式不保证向后兼容	升级后旧会话可能读不了，需备份 `~/.dsh`
插件 API 不稳定	插件 SDK 与核心 API 同步变动，上周写的插件下周可能失效	插件生态碎片化，维护成本高
Node 版本要求苛刻	仅 `^22.19 \|\| >=24`，Node 23 直接失败	环境迁移成本，CI 镜像要专门配
Windows 支持弱	PTY 只支持 Linux/macOS；打包运行时也无 Windows 版	Windows 用户绕路 WSL2

10.2 插件生态问题

问题	表现	应对
插件质量参差	一周内涌现大量"半天写出来"的插件，无测试、无文档、无安全说明	用 8.6 的检查清单筛选，优先官方/高星仓库
版本漂移	插件声明兼容 v0.1.0-rc.3，但你的 dsh 已是 rc.6	安装前核对插件 README 的兼容版本说明
核心插件少	官方内置插件有限，大量能力（搜索、浏览器）依赖社区	关键能力自研或等官方路线图
维护者稀缺	多数插件是个人作者，停更风险高	关键路径插件考虑 fork 或自维护
发现机制弱	无官方插件市场/中心化索引，靠 GitHub topic 和 npm 搜索	关注官方 awesome 列表（如有）与 Discussions 置顶帖

10.3 安全风险（插件即代码）

这是"一切皆插件"最需要警惕的一面：

风险	场景	缓解
恶意/后门插件	安装了来历不明的插件，它在 `setup` 里悄悄上传你的代码或密钥	只装可信来源；安装前读源码；用 `dsh plugin list` 定期审计
权限放大	插件运行在 dsh 进程权限内，可绕过工作区权限级别读写任意文件	给 dsh 进程最小系统权限；敏感环境跑在容器里
供应链攻击	插件依赖链中的任意 npm 包被投毒	锁定依赖版本（package-lock）；CI 扫描依赖
密钥泄露	插件打印环境变量、把 `~/.dsh/.credentials.yaml` 内容带出	审计插件代码；监控外发流量
提示词注入	对话中混入恶意指令，诱导 Agent 执行危险操作（配合 10.4 的沙箱缺失更危险）	高危命令审批策略（9.4）、白名单工具集

10.4 运行时问题

问题	表现	状态
免费模型 429 限流	OpenCode Zen 免费档在 Agent 高频调用下必限流（见第 6 章）	无解，别用
Bash 工具空转（noop loop）	社区反馈 Agent 偶尔陷入"重复执行无效果命令"循环	issue 区跟踪中，用 Minimal Profile 或超时配置缓解
局域网访问受限	CLI 拒绝 `--host 0.0.0.0`，Web UI 只能本机访问	用飞书插件/反代/隧道，官方暂不支持
--dump-config 输出冗长	插件树大时输出很长，不利于脚本解析	配合 grep 使用
无内置联网搜索	默认工具集不含 web search，Agent 查资料能力缺失	等官方或装社区搜索插件

10.5 缓解措施清单（务实结论）

不要在生产环境依赖 dsh——等 1.0；当前适合个人研究、内部试点。
每次升级前备份 ~/.dsh（配置 + 会话），升级后先 dsh --dump-config 确认插件树正常。
插件只装可信来源，安装后通读 setup 代码；团队环境用版本锁定的配置分发。
高危操作上审批策略 + 白名单工具集，把"一切皆插件"的威力装进笼子。
Windows 用户直接 WSL2，别在原生 Windows 上折腾 PTY 相关能力。
模型用官方 API 或企业网关，别指望免费档跑 Agent 工作负载。
关注官方 issue/discussions 置顶：破坏性变更公告、已知 bug 列表、路线图都在那里。

11. 常见问题与已知限制

Q1：启动报错 MISSING_CREDENTIAL / UNKNOWN_MODEL？
A：没配 API Key，或模型 ID 与供应商不匹配。去 Settings → Models 配 Key；自定义模型确认 ID 与 settings.yaml 一致。

Q2：Node 23 启动失败？
A：官方要求 ^22.19 || >=24，奇数版本（23/25 等）不支持。用 nvm/n 切换版本，或改用绿色版/Python SDK。

Q3：想改端口 / 局域网访问？
A：dsh web --port 8080 可改端口；--host 0.0.0.0 目前被 CLI 拒绝，官方不支持局域网共享。局域网访问可用飞书插件或自行转发。

Q4：Windows 上 PTY 功能异常？
A：官方只支持 Linux/macOS 的 PTY。Windows 用户用 WSL2、或 Python SDK / 绿色版（官方打包运行时同样仅 Linux/macOS）。

Q5：--dump-config 是什么？
A：输出完整插件树，排查"插件装了但没生效"的神器。

Q6：会话记录在哪？
A：会话日志为 append-only（只追加），可在 Web UI 的 Trajectory（轨迹）视图回放每一步工具调用，也可在 ~/.dsh 下找到会话数据文件。

Q7：已知 Bug？
A：社区反馈过 Bash 工具空转（noop loop）问题，建议关注仓库 issue 区；预览版会话格式无兼容性承诺，升级前备份 ~/.dsh。

Q8：兼容 AGENTS.md / CLAUDE.md 吗？
A：兼容。dsh 会读取项目的 AGENTS.md 与 CLAUDE.md 作为上下文（与主流 Agent 生态对齐）；还支持 MCP 客户端，可直接挂 MCP 工具。

Q9：生产环境能用吗？
A：官方明确警告——开发者预览版，随时可能破坏性变更，不建议生产依赖。正式版（1.0）再考虑。

Q10：插件安装后不生效？
A：三步排查——dsh plugin list 看状态是否 enabled；dsh --dump-config 看插件树里是否出现该插件节点；看启动日志（插件 setup 抛错会被内核捕获但进程不退出，日志里有记录）。

Q11：想替换核心组件怎么下手？
A：先 dsh --dump-config 找到目标节点名，再写插件 provides 同名服务，最后在 cordis.patch.yml 里 target: <节点名> / replace: <插件名>，重启生效（完整示例见 9.4）。

12. 参考资料

DeepSeek Harness 官方仓库：GitHub - deepseek-ai/deepseek-harness: DeepSeek Harness: Everything is a Plugin. · GitHub
官方官网与绿色版下载：DeepSeek Harness | Agent, Plugins & Free API Credits
dsh 官方文档（含设置/供应商/模式）：DeepSeek Harness（dsh）官方 Agent 安装与使用指南 | DeepSeek Agent
Cordis 微内核框架：https://github.com/cordiverse/cordis
免费模型 429 讨论：OpenCode zen 免费模型（big-pickle）在 DSH 中必现 429 FreeUsageLimitError（附修复补丁） · deepseek-ai/deepseek-harness · Discussion #1455 · GitHub
dsh-lark 插件：GitHub - omdsh-dev/dsh-lark: Lark/Feishu IM bot channel for DeepSeek Harness | 飞书 DeepSeek Harness （DSH）插件 · GitHub
dsh-feishu-bridge：GitHub - zhbdream/dsh-feishu-bridge: 飞书 → 本机 DeepSeek Harness Agent 桥接（dsh-plugin） · GitHub
DeepSeek 开放平台（API Key）：DeepSeek
飞书开放平台：飞书开放平台
飞书智能伙伴搭建平台：豆包工作伙伴，创建你的专属工作伙伴
DeepSeek Harness vs OpenCode 对比：Unavailable - MyClaw
保姆级安装教程（wangruofeng007）：DeepSeek Harness 安装配置保姆教程 | 王若风的技术博客
dsh 部署指南（中文）：DeepSeek Harness 部署指南：从 npx 一键启动到 Python SDK 完整接入 - vibecoding患者 - 企业博客

本文基于 DeepSeek Harness v0.1.0-rc.6 与 2026-08 公开资料整理，产品处于快速迭代期，具体行为以官方文档与仓库最新版为准。

posted @ 2026-08-20 10:20 Jaosn_chen 阅读(1502) 评论(0) 收藏举报

刷新页面返回顶部

Jaosn_chen