鲸鱼娘桥接增强 HarveyZed/clawd-whale-girl

Clawd on Desk × DSH 增强包 + 鲸鱼娘主题

一个仓库两件配套的东西：dsh-clawd-extras（Clawd on Desk 的 DeepSeek Harness 桥接增强版）和鲸鱼娘主题（桌宠皮肤，素材来自 vlln/whale-girl，MIT）。

官方 bridge 只上报会话状态和权限审批。这个插件把 DSH 有、Clawd 也收、但官方没接的信号补齐。

仓库内容

| 路径 | 内容 |
| lib/ cordis.patch.yml package.json | 宿主半边：事件映射、上报、余额轮询 |
| client.js | 浏览器半边：设置页的配置表单 |
| themes/whale-girl/ | 鲸鱼娘主题（素材源 + 可直接导入的 zip） |
| params.example.json | 可热改的参数示例 |
| test/ | 27 项单测（18 项原样 + 9 项 SSH 主机传输：发现与 nonce 正负用例、端到端、审批往返、身份三态、fail closed、override 排他），另有 live-probe.mjs 在线诊断反向隧道 |
| LICENSE | MIT（主题美术另见文末署名） |

设计要点

巧思：拿虚拟会话当余额告警灯

Clawd 没有余额这个概念。它的配额环是给订阅制 agent 的限流百分比用的（字段名还是白名单），DeepSeek 按量付费对不上，所以“把余额显示到桌宠上”这条路本身不通。

换个做法：不显示数字，用状态动画当灯。插件造一个虚拟会话 deepseek-harness:balance-guard-，余额低于阈值推到 notification，低于一半推到 error，充值回来让它收场；HUD 行标题写金额，数字也就有了。

有个坑：这个会话不能是 headless——Clawd 合并主状态时会跳过 headless 会话，动画根本不会播。

妥协：三处绕不开的限制，各自怎么处理

| 限制 | 处理 |
| Clawd 对 DSH 有 sequence fence（按 session_id 记水位），两个上报者会互顶序号、双双丢事件，所以不能与官方 bridge 并存 | fork 官方那份，原有行为逐字保留、只加映射。新增映射时开始/结束必须成对——漏了 compaction/end 会让状态永久卡在 sweeping |
| request/context 会写进会话日志，但不会送达插件的 session/event 监听器 | 上下文窗口用可配置兜底 contextWindowFallback，真收到事件时覆盖 |
| DSH 的 bundle/patch 只在进程启动时 compose，宿主 HMR 又排除 node_modules（插件正是从 profiles/web/node_modules/... 解析），改配置必重启 | 插件自己盯 params.json：每 3 秒看 mtime，改了就地生效，并顺手触发一次余额轮询 |

排查时两处别误判：debug.log 第一行是启动横幅 dsh-clawd-extras v starting，版本直接读自 package.json（不另设常量，发布只改 manifest）；重启 dsh web 后会出现一条 post dropped (204): SessionStart——该会话在 Clawd 侧仍算 active，重启后补发的 SessionStart 被 fence 判为 active-session-restart 回 204，紧随其后的 UserPromptSubmit / PreToolUse 照常送达，不是故障。

补了什么

F1–F5 是全文和源码注释通用的索引（F 只是 feature 的流水号，没有别的含义）。配置表、代码注释里写「（F3）」就是指向下表的这一行。

| 编号 | 能力 | DSH 侧来源 | Clawd 侧落点 |
| F1 | 上下文用量 | tokenMeter.measure().surfaceTokens + 上下文窗口 | context_usage，HUD 显示百分比 |
| F2 | 等待审批 | approval/asked / approval/decided | notification 状态 |
| F3 | 子代理 / 团队 | subagent/descriptor、team/、delegationDepth > 0 | juggling 状态 |
| F4 | 上下文压缩 | compaction/start → sweeping；compaction/end → idle | sweeping 状态 |
| F5 | 余额告警 | credentials → GET /user/balance | 独立虚拟会话，按阈值分档 |
| F6 | 远程 DSH（SSH 主机） | ~/.claude/hooks/clawd-remote.json（Clawd 部署时写入的身份文件） | 走 x-clawd-routing-nonce 打到反向转发的 remotePort，会话归到该主机名下 |

状态 FIFO、阻塞式审批气泡、SessionStart/SessionEnd 映射从官方 bridge 原样保留。

F6：远端 DSH 怎么找到桌面端

Clawd 的「SSH 主机」模式是在远端开反向转发
ssh -R 127.0.0.1::127.0.0.1:，远端的一切请求都落到桌面端的
src/remote-ssh-ingress.js。那个 ingress 只接受 GET/POST /state 与 POST /permission，且必须带该 profile 的 x-clawd-routing-nonce（32 位小写 hex），否则一律 404。

官方 bridge 的 client 既不带这个头、也只在本地找 ~/.clawd/runtime.json，所以在 SSH 主机模式下它永远探测不到桌面端（日志里只有 clawd-unavailable）。本插件把传输分成两条，发现时二选一：

| 模式 | 判定 | 目标 |
| ssh-remote | 能读到并校验通过 clawd-remote.json（CLAWD_REMOTE_IDENTITY_PATH 为其排他覆盖） | 只打 identity.remotePort，每次探测/上报都盖 nonce；不做端口扫描（该模式下只有这一个端点可达，扫别的只会产出 404） |
| local | 所有候选都没有身份文件，且 Clawd 没有把本机标记成受管远端 | 上游行为不变：runtime.json 优先，再扫 23333-23337 |

身份文件每次发现都重读，不跨传输变更缓存：桌面端重新部署（换 nonce 或换端口）后，下一次上报失败即自愈。身份解析分成三态，因为「没有文件」和「文件不可用」意思相反：

| 状态 | 判定 | 行为 |
| absent | 所有候选路径都不存在，且没有受管远端标记 | 走本地扫描（上游行为） |
| invalid | 文件存在但读不出 / 不是 JSON / 字段不合法，或没有文件但带受管远端标记 | fail closed：报 clawd-unavailable，绝不扫端口 |
| valid | 校验通过 | 打 identity.remotePort + nonce |

受管远端标记沿用 Clawd 自己的判据（hooks/server-config.js 的 isSshSecureMode）：CLAWD_SSH_REMOTE=1 或 clawd-ssh-secure-v1（可用 CLAWD_SSH_SECURE_MARKER_PATH 覆盖）。这条是有意为之——半成品身份一旦回落扫描，这台远端上要是同时开着 Clawd 桌面端，另一台机器的状态乃至审批请求就会被投过去。

身份候选按顺序解析，其中 CLAWD_REMOTE_IDENTITY_PATH 排他：设了它就只认它，不再尝试默认位置（与 Clawd 的 resolveRemoteIdentityPath 一致）。默认顺序是 ~/.claude/hooks/clawd-remote.json （Clawd 部署 hook 时写入的那个），再到 ~/.clawd/clawd-remote.json——后者是本插件的兜底候选， Clawd 自身不认这个路径。任一候选存在但不可用就立刻判 invalid 并停止，既不看后面的候选、也不扫端口；这就是上面 fail closed 的实现方式。受管标记的查找位置不跟随 identity 覆盖（Clawd 的标记路径同样不跟随），挪 identity 不会把"这机器是受管远端"的证据一起挪走。

验证范围：F6 传输已在 Linux（Ubuntu 26.04）+ DSH 0.1.2-rc.1 + 真实 Clawd 桌面端上端到端跑通（探针通过、连上后上报零拒绝、F1 上下文取到真值、F5 余额轮询成功、F2 审批三次完整往返、F3 子代理→juggling、F4 压缩→sweeping 且正常收场）。F6 不依赖任何 DSH 版本相关面——它只用 Clawd 侧的 identity 文件与 ingress 的 nonce 契约，所以在 0.1.2-rc.1 上跑通意味着更旧的版本预期同样可用（含 Clawd 契约表里的 0.1.1-rc.2 / 0.1.0-rc.6），前提是该版本能正常加载插件并投递 session/ 事件（F1–F5 的事件面差异仍在）。

安装

git clone https://github.com/HarveyZed/clawd-whale-girl.git
cd clawd-whale-girl
dsh plugin --profile web remove @dsh-external/dsh-clawd-bridge # 同一会话不能有两个上报者
dsh plugin --profile web add "$PWD"
重启 dsh web —— bundle 只在启动时 compose

依赖零安装（只用 Node 标准库 + DSH 自带服务），克隆下来直接 add。

远端（Clawd SSH 主机）不需要额外配置：插件靠 Clawd 部署时写入的 clawd-remote.json 自动认出该模式（F6）。排查入口——桌面端"没反应"时先在远端跑：

node test/live-probe.mjs

它会区分三种长得一样的故障：nothing is listening on 127.0.0.1:＝桌面端的 SSH 主机会话没连着（反向转发没建）；404 from the Clawd ingress＝nonce 过期（桌面端重新配对过该主机）； OK＝通。

主题：把 themes/whale-girl/ 复制进 Clawd 用户主题目录（Windows：%APPDATA%\clawd-on-desk\themes\），或在「设置 → 主题 → 导入主题 zip」里选 themes/whale-girl.zip。

若 Clawd 能看到全局 dsh CLI，它的启动同步可能把官方 bridge 装回来。稳妥做法：把 Clawd prefs 里 agents["deepseek-harness"].integrationInstalled 置 false（enabled 保持 true，事件照收）。

配置

启动层写在 cordis.patch.yml 的 config，可被 params.json 覆盖（后者运行中 3 秒热生效）。

| 键 | 默认 | 说明 |
| contextUsage | true | 上报上下文用量（F1） |
| contextWindowFallback | 1000000 | 收不到 request/context 时的窗口，换模型要手改 |
| approvalNotification | true | approval/asked 切 notification（F2），不影响审批气泡 |
| subagentJuggling | true | 子代理/团队切 juggling（F3） |
| compactionSweeping | true | 压缩切 sweeping，结束回 idle（F4） |
| permissionBubble | true | 是否接管普通审批；关掉＝完全交还 DSH 原生弹窗 |
| permissionTimeoutMs | 600000 | 等待审批决定的上限；超时按无决定交还 DSH，不伪造 deny |
| debugLogPath | 包目录 debug.log | 采样日志路径。不写＝用默认；显式空字符串＝关闭 |
| paramsPath | 包目录 params.json | 热改参数文件。不写＝用默认；显式空字符串＝只读启动层 |
| paramsPollMs | 3000 | 参数文件检查间隔（最小 100） |

| balance. | 默认 | 说明 |
| enabled | true | 余额轮询与告警总开关 |
| threshold | 20 | 低于它 notification，低于一半 error |
| currency | CNY | 取哪个币种；找不到退回第一个 |
| apiKeyEnv | DEEPSEEK_API_KEY | 凭据引用名，经 DSH credentials 解析（key 不下发浏览器、不写日志） |
| baseUrl / endpoint | https://api.deepseek.com / /user/balance | 余额接口 |
| refreshMs | 300000 | 轮询间隔（最小 60000） |
| firstRetryMs | 15000 | 首次轮询失败后的重试间隔；凭据就绪后立刻补一次 |
| mode | flash | flash＝跨档显示 flashMs 后收场；sticky＝低于阈值期间持续显示 |
| flashMs | 12000 | flash 模式的显示时长 |
| remindEveryMs | 1800000 | 仍低于阈值时每隔多久再闪一次（0＝关） |

设置页与活参数

- 设置页：设置 → 内置插件 → 「Clawd 扩展」，字段同配置表，保存后立即生效并写回 params.json。
- 活参数：直接改 params.json（可从 params.example.json 复制），每 3 秒生效，不用重启；改动会写进调试日志。

已知缺陷

当前不足，都不在本仓库的修复计划内。

| 缺陷 | 影响 | 归属 |
| Clawd 没有余额字段或接口 | 余额只能借状态动画表达，做不出独立余额牌 | 需上游改 Clawd |
| DSH 没有 worktree 事件 | carrying 无法映射 | DSH 事件面 |
| DSH 只有「新增子代理」事件，没有「结束」事件 | 父会话会一直 juggling，直到下一次工具事件覆盖 | DSH 事件面 |
| 兼容性验证不完备 | 插件本体（F1–F5）只在 Windows x64 + DSH 0.1.6-alpha.2 上跑过（F4 的 compaction/end 修正是用真实会话日志重放确认的）；远端那台（Linux + 0.1.2-rc.1）已实测 F1–F6：F2 审批三次完整往返（远端触发 → 桌宠 notification → 气泡 Allow → 决定回传 DSH）、F3 子代理会话（headless=0，juggling 后以 SessionEnd 收场）、F4 压缩（PreCompact → PostCompact，13 秒内退出 sweeping，未卡住）。其他 DSH 版本未验证，Clawd Doctor 可能提示未安装（其契约表不含 0.1.6-alpha.2） | 缺跨平台、跨版本的真实端到端环境 |
| 子代理会话的每个事件都被标成 SubagentStart | 只要会话是子代理，映射就短路成 juggling——实测一个子代理会话 5 秒内产生 157 条同名上报，Clawd 侧日志随之膨胀，且该会话自己的工具失败等事件不会表现为 error。画面不受影响：Clawd 的 subagent tracker 对「无 id 的重复启动」是幂等的，juggling 档位仍按 1 个子代理计 | 本仓库未改 |
| 设置页文案仅中文 | DSH 支持多语言，这里 label 是硬编码 | 本仓库未接 locale |

未验证部分我的推测

以下是读代码推的，没有实测支撑，当线索用别当结论。

- macOS / Linux：宿主半边只用 Node 标准库（http / fs / path / url）加全局 fetch，没有原生模块、没有 Windows API、没有 shell 调用，包目录靠 fileURLToPath 定位而不是 %APPDATA%，所以我倾向于能直接跑。不确定的是两处外部约定：Clawd 用 os.homedir() 拼 ~/.clawd/runtime.json，三平台路径一致，但 Clawd 自己的 DSH 集成也是 Windows 优先做的；用户主题目录各平台不同，themes/ 得放到对应位置。余额是纯 HTTPS，与平台无关。
- 更早的 DSH 版本：插件没有版本门禁（官方 bridge 那份契约表被绕开了），所以旧版本不会报错也不会拒绝加载，最可能的表现是静默失效——事件名对不上，映射不触发，桌宠就是不动。compaction/、subagent/、team/ 属于较晚加入的事件，早于它们的版本上 F3、F4 大概率完全不工作；F1、F2、F5 依赖的 tokenMeter、approval/*、credentials 服务也可能缺失或改名，同样是「没反应」而不是崩溃。
- 将来的 DSH 版本：同样的静默风险。事件重命名、webServer.register 或设置页 slot 的 API 变动，都不会在安装时报错。排查入口：宿主半边的 debug.log 会记下 post dropped (204) / post rejected:，设置页打不开则说明浏览器半边没加载上。

路线图

计划要做的事。

| 事项 | 说明 |
| 补齐鲸鱼娘素材 | 上游每张精灵图只有 2–3 帧，补帧只能靠插值，会牺牲现在「与原图逐像素一致」的锐度——要做就先做运动补偿原型，并用开发侧的验收脚本（逐帧比对上游 RMSE + 运动可见性检查）确认没有变软；sweeping 保持借用 thinking（「?」与 working 的灯泡可区分，上游没有清扫素材） |
| 主题尚未用上的插槽 | 主题卡片缺 preview 图；idleAnimations（用户可自选待机姿势）与 sleepSequence: full（打哈欠 → 打盹 → 倒下 → 睡着，需要 4 个额外状态与 timings.collapseDuration）都未启用 |
| 上下文窗口取真值 | 用 sessionQuery.observeSession() 的 contextPressure 投影替代兜底常量（需先验证该 API 的 lease 释放与取值形状） |

许可

- 插件代码 MIT（宿主半边 fork 自 Clawd 官方 bridge，MIT）。
- themes/whale-girl/ 角色美术来自 vlln/whale-girl（MIT, Copyright (c) 2026 Sam Gao），属社区二创，再分发请保留署名。