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:<remotePort>:127.0.0.1:<appPort>，远端的一切请求都落到桌面端的 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:<port>＝桌面端的 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），属社区二创，再分发请保留署名。