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 上實測。其他版本未進行跨平臺驗證。