MateClaw

中文

English

中文

English

Appearance

DeepSeek Harness 接入 ​

本文说明如何把官方 DeepSeek Harness（简称 DSH）接入 MateClaw，并在员工页面创建一个由 DSH 驱动的数字员工。

DSH 在 MateClaw 中是员工运行时，不是 MCP 工具，也不是普通插件。MCP 负责为员工提供工具；DSH 负责启动外部 Agent 进程、运行 ReAct 循环并把思考、工具和文本事件流回 MateClaw。

架构 ​

text
MateClaw Chat / SSE
        |
        v
DSH Runtime Provider
        |
        v  JSON-RPC over stdin/stdout
dsh-jsonrpc-agent
        |
        v
DeepSeek API + Cordis composition

MateClaw 仍然负责员工、会话、权限、工作空间、消息持久化和 UI 投影。DSH 只负责运行时回合。API Key 由 MateClaw 的 DeepSeek 提供商配置注入到 DSH 子进程，不要把密钥写进 runtimeConfig、员工提示词或仓库文件。

前置条件 ​

  • macOS、Linux 或 Windows（本文命令以 macOS / Linux 为例）
  • JDK 21
  • 已启动的 MateClaw 后端和前端
  • DeepSeek API Key
  • 已构建的 DSH JSON-RPC Agent
  • DSH 仓库中的 Cordis 配置文件

确认 DSH 可执行文件：

bash
"$DSH_JSONRPC_AGENT" --help
test -x "$DSH_JSONRPC_AGENT"
test -f "$DSH_CORDIS_CONFIG"

安装 DSH ​

请以 DeepSeek Harness 官方仓库 的安装说明为准构建运行时。构建完成后，需要得到两个路径：

text
<dsh-root>/dist-exe/dsh-jsonrpc-agent-pkg-<platform>
<dsh-root>/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml

不要把 DSH 二进制复制到 MateClaw 的源码仓库。推荐放在独立目录，并通过环境变量告诉 MateClaw 位置。

在 IDEA 中配置后端 ​

打开 IDEA 的 Run | Edit Configurations...，选择 MateClaw 的 Spring Boot 配置，在 Environment variables 中增加：

text
DSH_JSONRPC_AGENT=/absolute/path/to/dsh-jsonrpc-agent-pkg-macos-arm64
DSH_CORDIS_CONFIG=/absolute/path/to/cordis.yml
DSH_CWD=/absolute/path/to/mateclaw-workspace

示例：

text
DSH_JSONRPC_AGENT=/opt/deepseek-harness/dist-exe/dsh-jsonrpc-agent-pkg-macos-arm64
DSH_CORDIS_CONFIG=/opt/deepseek-harness/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml
DSH_CWD=/var/lib/mateclaw/workspace

DSH_CWD 必须是后端进程可读写的目录。IDEA 启动配置中的路径必须是绝对路径；修改后需要重启后端，Spring Boot 不会热加载环境变量。

配置 DeepSeek 提供商 ​

  1. 登录 MateClaw。
  2. 打开 设置 → 模型。
  3. 配置并启用 DeepSeek 提供商。
  4. 填入 DeepSeek API Key 和 Base URL。
  5. 确认至少有一个启用的 DeepSeek chat 模型。

DSH 默认模型是 deepseek-v4-flash。如果员工没有绑定具体模型，MateClaw 会使用全局默认模型名，并从 deepseek 提供商注入凭证。自定义模型时，模型必须能由 DeepSeek Harness 的 DeepSeek provider route 使用。

创建 DSH 数字员工 ​

在 数字员工 → 新建 中：

  1. 填写员工名称、角色和目标。
  2. 将运行时选择为 DSH / DeepSeek Harness。
  3. 配置工作空间；留空时使用 DSH_CWD。
  4. runtimeConfig 使用 JSON 对象，例如：
json
{
  "mode": "qa",
  "workspace": "default",
  "policy": "read-only"
}
  1. 保存员工并进入聊天。

运行时配置只描述员工级策略。不要在其中写 DEEPSEEK_API_KEY、Cookie、Bearer Token 或本机敏感路径。

验证清单 ​

在 DSH 员工会话中发送：

text
请只回复：DSH_RUNTIME_OK

成功标准：

  • 员工标题显示 DSH Harness。
  • 输入框发送后能看到思考状态和文本流。
  • 日志出现 provider=deepseek 和 apiKeyConfigured=true。
  • 日志出现 turn/end 且 kind=completed。
  • 页面不会显示“本次没有输出”。
  • 同一个会话不会被并发启动两个 DSH live session。

不要复用已经完成过的测试 conversationId 创建新的 DSH live session。DSH 会检测到磁盘上的 session 日志与新的 live session 不一致，并返回 id collision。请使用“新对话”创建新的会话。

日志与诊断 ​

后端日志通常位于：

text
logs/mateclaw.log

重点搜索：

bash
rg "\[DSH\]|MISSING_CREDENTIAL|EMPTY_RESPONSE|id collision" logs/mateclaw.log

安全诊断接口：

http
GET /api/v1/admin/agent-runtime/dsh/diagnostics

它只返回命令、可执行文件、Cordis 文件和能力状态，不返回 API Key。

常见问题 ​

MISSING_CREDENTIAL ​

检查：

  1. 设置 → 模型中的 DeepSeek 提供商是否已启用。
  2. API Key 是否保存成功。
  3. 员工是否使用 DSH，而不是把 DSH 二进制配置成 MCP command。
  4. 后端是否使用了修改后的 IDEA 配置并完成重启。

日志中的 apiKeyConfigured=false 表示凭证没有进入 DSH 子进程。

EMPTY_RESPONSE ​

检查模型是否可用、Base URL 是否正确，以及该模型是否支持当前请求。先使用固定短消息验证，再逐步增加工具或技能。

dsh.command_unavailable ​

DSH_JSONRPC_AGENT 必须指向真实可执行文件。检查文件权限：

bash
chmod +x /absolute/path/to/dsh-jsonrpc-agent-pkg-macos-arm64

dsh.cordis_missing ​

DSH_CORDIS_CONFIG 必须指向实际存在的 cordis.yml，不是 DSH 包目录。若传入包目录，MateClaw 会尝试解析其下的 runtime/cordis.yml。

页面显示重复回答 ​

确保使用最新后端版本。DSH 会同时发送增量文本事件和最终消息快照，MateClaw 只应投影增量文本，不能把快照再次追加到回答中。

MCP、插件和 DSH 的边界 ​

机制适合做什么是否替代 DSH
MCP提供文件、GitHub、数据库等工具否
插件扩展 MateClaw 的工具、模型、渠道或记忆能力否
DSH 员工运行时承载 DeepSeek Harness 的 Agent 循环和外部进程是员工运行时，不是工具

推荐组合是：DSH 作为员工运行时，MCP 作为工具层，MateClaw 作为治理和可视化层。

安全建议 ​

  • API Key 只放在 MateClaw 模型提供商配置或受控环境变量中。
  • DSH 工作空间使用专用目录，不要直接指向整个用户主目录。
  • 初次接入使用只读策略和最小工具集。
  • 不要把 .sessions/、日志或配置文件提交到 Git。
  • 生产环境中限制 DSH 子进程的文件、网络和凭证访问范围。