docs: add DeepSeek Harness integration guides

mateclaw-server/src/main/resources/docs/en/deepseek-harness.md

@@ -0,0 +1,202 @@
+---
+title: DeepSeek Harness Integration
+description: Install DeepSeek Harness and configure it as a digital employee runtime in MateClaw.
+head:
+  - - meta
+    - name: keywords
+      content: DeepSeek Harness,DSH,digital employee,Agent runtime,JSON-RPC,Cordis
+---
+
+# DeepSeek Harness Integration
+
+This guide connects the official DeepSeek Harness (DSH) to MateClaw and creates a digital employee powered by the DSH runtime.
+
+In MateClaw, DSH is an **employee runtime**, not an MCP tool and not a regular plugin. MCP supplies tools; DSH owns the external Agent process, the ReAct loop, and the event stream that MateClaw projects into the conversation UI.
+
+## Architecture
+
+```text
+MateClaw Chat / SSE
+        |
+        v
+DSH Runtime Provider
+        |
+        v  JSON-RPC over stdin/stdout
+dsh-jsonrpc-agent
+        |
+        v
+DeepSeek API + Cordis composition
+```
+
+MateClaw remains responsible for employees, sessions, permissions, workspaces, message persistence, and UI projection. DSH runs the turn. MateClaw injects the API key from the DeepSeek provider configuration into the DSH child process. Never put secrets in `runtimeConfig`, employee prompts, or the repository.
+
+## Prerequisites
+
+- macOS, Linux, or Windows (commands below use macOS / Linux syntax)
+- JDK 21
+- A running MateClaw backend and frontend
+- A DeepSeek API key
+- A built DSH JSON-RPC agent
+- The Cordis configuration from the DSH checkout
+
+Check the runtime files:
+
+```bash
+"$DSH_JSONRPC_AGENT" --help
+test -x "$DSH_JSONRPC_AGENT"
+test -f "$DSH_CORDIS_CONFIG"
+```
+
+## Install DSH
+
+Follow the [official DeepSeek Harness repository](https://github.com/deepseek-ai/deepseek-harness) for the current build instructions. The build must provide these two paths:
+
+```text
+<dsh-root>/dist-exe/dsh-jsonrpc-agent-pkg-<platform>
+<dsh-root>/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml
+```
+
+Keep the DSH binary outside the MateClaw source tree. Configure its location with environment variables.
+
+## Configure the IDEA backend
+
+Open **Run | Edit Configurations...** in IDEA, select the MateClaw Spring Boot configuration, and add these variables under **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
+```
+
+Example:
+
+```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` must be readable and writable by the backend process. Use absolute paths in the IDEA run configuration. Restart the backend after changing them; Spring Boot does not hot-reload process environment variables.
+
+## Configure the DeepSeek provider
+
+1. Sign in to MateClaw.
+2. Open **Settings → Models**.
+3. Configure and enable the **DeepSeek** provider.
+4. Enter the DeepSeek API key and base URL.
+5. Confirm that at least one enabled DeepSeek chat model exists.
+
+The default DSH model is `deepseek-v4-flash`. If the employee has no explicit model, MateClaw uses the global model name and injects credentials from the `deepseek` provider. A custom model must be usable by the DeepSeek provider route in DSH.
+
+## Create a DSH digital employee
+
+Open **Digital Employees → New**:
+
+1. Enter the employee name, role, and goal.
+2. Select **DSH / DeepSeek Harness** as the runtime.
+3. Set a workspace; when blank, `DSH_CWD` is used.
+4. Use a JSON object for `runtimeConfig`, for example:
+
+```json
+{
+  "mode": "qa",
+  "workspace": "default",
+  "policy": "read-only"
+}
+```
+
+5. Save the employee and open its chat.
+
+Runtime configuration describes employee policy only. Do not put `DEEPSEEK_API_KEY`, cookies, bearer tokens, or sensitive local paths in it.
+
+## Verification checklist
+
+Send this message in the DSH employee conversation:
+
+```text
+Reply with exactly: DSH_RUNTIME_OK
+```
+
+Success means:
+
+- The employee header shows `DSH Harness`.
+- Thinking state and text deltas appear in the chat.
+- The log contains `provider=deepseek` and `apiKeyConfigured=true`.
+- The log contains a `turn/end` event with `kind=completed`.
+- The UI does not show “no output for this run”.
+- The same conversation is not used to start two different DSH live sessions.
+
+Do not reuse a completed test `conversationId` for a new DSH live session. DSH detects a mismatch between the persisted session log and the new live session and reports `id collision`. Use **New conversation** for every fresh runtime test.
+
+## Logs and diagnostics
+
+The backend log is commonly located at:
+
+```text
+logs/mateclaw.log
+```
+
+Search for the runtime signals:
+
+```bash
+rg "\[DSH\]|MISSING_CREDENTIAL|EMPTY_RESPONSE|id collision" logs/mateclaw.log
+```
+
+The admin-only diagnostics endpoint is:
+
+```http
+GET /api/v1/admin/agent-runtime/dsh/diagnostics
+```
+
+It returns command, executable, Cordis, and capability status without returning the API key.
+
+## Troubleshooting
+
+### `MISSING_CREDENTIAL`
+
+Check that:
+
+1. The DeepSeek provider is enabled under Settings → Models.
+2. The API key was saved successfully.
+3. The employee uses DSH rather than configuring the DSH binary as an MCP command.
+4. The backend was restarted with the updated IDEA configuration.
+
+`apiKeyConfigured=false` in the log means the credential did not reach the DSH child process.
+
+### `EMPTY_RESPONSE`
+
+Check model availability and the base URL. Verify with a short fixed prompt before adding tools or skills.
+
+### `dsh.command_unavailable`
+
+`DSH_JSONRPC_AGENT` must point to an executable file:
+
+```bash
+chmod +x /absolute/path/to/dsh-jsonrpc-agent-pkg-macos-arm64
+```
+
+### `dsh.cordis_missing`
+
+`DSH_CORDIS_CONFIG` must point to the actual `cordis.yml`, not only the package directory. If a package directory is provided, MateClaw also checks its `runtime/cordis.yml` child path.
+
+### The answer appears twice
+
+Use the latest backend version. DSH emits text deltas followed by a final assistant snapshot. MateClaw must project the deltas only and must not append the snapshot again.
+
+## MCP, plugins, and DSH
+
+| Mechanism | Best for | Replaces DSH? |
+|-----------|----------|--------------|
+| MCP | File, GitHub, database, and other tools | No |
+| Plugin | Extending MateClaw tools, models, channels, or memory | No |
+| DSH employee runtime | Hosting the DeepSeek Harness Agent loop and process | It is the employee runtime, not a tool |
+
+The recommended composition is: **DSH as the employee runtime, MCP as the tool layer, and MateClaw as the governance and visualization layer**.
+
+## Security recommendations
+
+- Store API keys only in MateClaw provider configuration or a controlled environment.
+- Give DSH a dedicated workspace instead of the whole user home directory.
+- Start with a read-only policy and the smallest possible tool set.
+- Never commit `.sessions/`, logs, or local credential configuration.
+- In production, restrict the DSH child process filesystem, network, and credential access.

mateclaw-server/src/main/resources/docs/zh/deepseek-harness.md

@@ -0,0 +1,202 @@
+---
+title: DeepSeek Harness 接入
+description: 在 MateClaw 中安装 DeepSeek Harness，并把它配置为数字员工运行时。
+head:
+  - - meta
+    - name: keywords
+      content: DeepSeek Harness,DSH,数字员工,Agent runtime,JSON-RPC,Cordis
+---
+
+# 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 官方仓库](https://github.com/deepseek-ai/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"
+}
+```
+
+5. 保存员工并进入聊天。
+
+运行时配置只描述员工级策略。不要在其中写 `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 子进程的文件、网络和凭证访问范围。