DeepSeek Harness 插件：Clawd 增强桥接与鲸鱼娘主题

前言¶

DeepSeek Harness (DSH) 的官方 Bridge 仅上报会话状态和权限审批。Clawd on Desk 作为桌面端智能体，接收了更多信号（如上下文用量、压缩状态、子代理信息），但 DSH 无法直接消费这些信号。这个插件 fork 了官方 bridge，补齐了这些缺失的映射，并增加了余额告警功能。

核心功能¶

该插件将 Clawd 端的信号映射到 DSH 可识别的单元，并通过桌宠进行可视化展示。主要功能包括：

F1 上下文用量：优先读取 DSH 内部的 contextPressure 投影（包含真实窗口与提示侧占用），回退到 request/context 事件和 contextWindowFallback。HUD 上显示百分比。
F2 等待审批：监听 approval/asked 和 approval/decided 事件，将其映射到 notification 状态，不影响 DSH 原生的审批气泡。
F3 子代理 / 团队：监听 subagent/descriptor、team/* 及 delegationDepth > 0，将状态映射为 juggling。
F4 上下文压缩：监听 compaction/start（状态变为 sweeping）和 compaction/end（状态变回 idle）。
F5 余额告警：通过 DeepSeek API 轮询余额，由于 Clawd 没有余额字段，插件会创建一个虚拟会话（deepseek-harness:balance-guard-<启动秒>）来通过状态动画表达余额。低于阈值推 notification，低于一半推 error。
F6 远程 DSH (SSH 模式)：支持通过 SSH 主机反向隧道连接。依赖 Clawd 部署时写入的 clawd-remote.json 和头部 x-clawd-routing-nonce 进行身份校验。

安装与启用¶

安装过程依赖 DSH 的插件管理器。由于 Clawd 对 DSH 有 session_id 水位锁（sequence fence），同一会话不能有两个上报者，因此必须先移除官方 bridge。

克隆仓库：

    git clone https://github.com/HarveyZed/clawd-whale-girl.git
    cd clawd-whale-girl

移除官方 bridge 并添加本插件（bundle 只在启动时 compose，添加后需重启 dsh web）：

    dsh plugin --profile web remove @dsh-external/dsh-clawd-bridge
    dsh plugin --profile web add "$PWD"

重启 DSH Web 服务。

该插件依赖零安装（仅使用 Node 标准库和 DSH 自带服务），克隆后即可使用。

配置¶

配置分为启动层（cordis.patch.yml）和运行层（params.json）。运行层配置支持 3 秒热加载，修改 params.json 后无需重启。

参数说明¶

params.json 中的主要配置项：

{
  "contextUsage": true,
  "contextWindowFallback": 1000000,
  "approvalNotification": true,
  "subagentJuggling": true,
  "compactionSweeping": true,
  "permissionBubble": true,
  "permissionTimeoutMs": 600000,
  "debugLogPath": "debug.log",
  "paramsPollMs": 3000,
  "balance": {
    "enabled": true,
    "threshold": 20,
    "currency": "CNY",
    "apiKeyEnv": "DEEPSEEK_API_KEY",
    "baseUrl": "https://api.deepseek.com",
    "endpoint": "/user/balance",
    "refreshMs": 300000,
    "firstRetryMs": 15000,
    "mode": "flash",
    "flashMs": 12000,
    "remindEveryMs": 1800000
  }
}

设置页与活参数¶

DSH 的设置页（内置插件 → Clawd 扩展）保存的配置会写入 params.json。直接修改 params.json（可参考 params.example.json）也能在 3 秒内生效。

主题与外观¶

插件包含一套鲸鱼娘桌宠主题，素材来自 vlln/whale-girl（MIT）。

安装方式：
1. 将 themes/whale-girl/ 目录复制到 Clawd 用户主题目录（Windows 为 %APPDATA%\clawd-on-desk\themes\）。
2. 或在「设置 → 主题 → 导入主题 zip」中选择 themes/whale-girl.zip。

远程 DSH (SSH) 模式详解¶

在 SSH 主机模式下，桌面端通过反向隧道暴露服务端点。本插件会自动读取身份文件（~/.claude/hooks/clawd-remote.json 或 ~/.clawd/clawd-remote.json）进行身份解析。

身份解析三态¶

身份解析逻辑决定了传输模式：

状态	判定条件	行为
absent	所有候选路径不存在，且无受管远端标记	走本地扫描（上游行为）
invalid	文件存在但不可用，或无文件但有受管远端标记	Fail closed：报 `clawd-unavailable`，不扫端口
valid	校验通过	打 `identity.remotePort` + nonce，直接连接

受管远端标记¶

若环境变量 CLAWD_SSH_REMOTE=1 或文件 clawd-ssh-secure-v1 存在，则判定为受管远端。这防止了插件在非预期的环境（如同时运行桌面端 Clawd）中误扫端口。

排查工具¶

若 SSH 模式不工作，可在远端运行诊断脚本：

node test/live-probe.mjs

输出 nothing is listening 表示反向隧道未建立；输出 404 表示 nonce 过期；输出 OK 表示连接正常。

已知限制¶

与官方 Bridge 不兼容：必须先移除 @dsh-external/dsh-clawd-bridge。
余额显示：Clawd 没有余额字段，余额只能通过虚拟会话的状态动画表达，无法显示具体数字。
DSH 事件面缺失：DSH 没有 worktree 事件导致 carrying 无法映射；DSH 只有新增子代理事件，没有结束事件，导致子代理会话会一直保持 juggling 状态，直到被新事件覆盖。
验证范围：插件本体在 Windows + DSH 0.2.0-rc.2 上实测；远端在 Linux + DSH 0.1.2-rc.1 上实测。其他版本未进行跨平台验证。