悬浮面板坞 ChisaAlter/dsh-pad

dsh-pad

简体中文 · English

DeepSeek Harness（dsh）的悬浮面板插件。面板由 AI 在对话里生成：比如「做一个观察这台服务器性能的面板」「做一个面板显示我的 DeepSeek API 余额」。

- 悬浮球与自由窗口：收起时是一颗可拖动的圆形悬浮球（和展开后的收起按钮同位置、同尺寸，颜色跟随主题；两者共用同一枚四瓣星花），可以放在应用里任意位置，靠近窗口四边会自动吸附；点开是面板窗口。窗口拖标题栏可以放到任意位置，拖左边缘调宽度，拖上、下边缘调高度（位置和尺寸都记在浏览器里）。贴住右边缘时，宽屏下仍会给对话区让出位置，右侧面板和回合导航条不会被盖住。
- AI 生成：模型通过 pad_ 工具创建和修改面板。面板是跑在沙箱 iframe 里的 HTML / CSS / JS，颜色跟随 dsh 的亮色 / 暗色主题。
- 自由分区：卡片可以拖到另一张卡片的上 / 下 / 左 / 右边缘，在那个位置分出新区域，并且可以继续嵌套——例如左边上下两张、右边一张独立大卡。拖到卡片中间交换位置，拖到面板坞空白处拆成整行。左右分栏的分隔条可以拖动调比例，一行最多 3 张，上下可以叠任意多张。
- 自动检查更新：启动后在后台查 GitHub 最新 Release（默认每 6 小时）；只有检测到新版本时坞顶才出现下载图标，点开即可更新，重启 dsh 生效。开发目录安装只提示、不覆盖源码。
- 两种取数方式
- 直接数据源：在本机跑 shell 命令，或者从本机请求 HTTP 接口，按秒级间隔刷新，不消耗 token。适合服务器性能、套餐余额这类接口数据。
- AI 刷新：按间隔在后台跑一轮 agent，让它重新取数后提交。适合只能靠搜索、读网页、多步推理才拿得到的数据。
- 面板内模型：面板里的按钮可以调用 dsh.run(prompt)，用这张面板自己的模型跑一次并把结果显示在卡片里；也支持 AI 刷新用同一模型。
- 建好就跑：数据源不设「允许运行」这一步——面板建好或改好后立刻开始取数，用户不需要在卡片上点任何按钮。也就是说模型写进面板的命令会直接在本机执行，和所有能跑命令的工具一样，请只在信任当前对话的前提下使用。密钥用 {{env:NAME}} 引用，只在宿主侧解析，不会发到浏览器。

面板长什么样

面板不是一页报告，是一张 200–400px 的卡片：一个数字、几行数据、一条趋势。为了让它每次都是这样，插件在三处下了手：

- 面板 kit：沙箱 iframe 里预置了一组 pad- 类（.pad-metric / .pad-item / .pad-meter / .pad-status / .pad-spark …）和 dsh.ui.metric / dsh.ui.list 之类的生成器。颜色全部走 --pad- 令牌，亮色 / 暗色自动跟随，面板不需要（也不应该）写死颜色。
- 版式手册：pad_guide 把五种版式——单值 + 趋势、排行 / 分布、状态板、额度环、动态列表——和四套完整的 html + script 配方交给模型，写面板之前先选版式、再写代码。
- 排版检查：pad_create / pad_update 会跑一遍确定性的 lint。文字墙、长段落、把 JSON 贴到卡片上、只有文字没有可视元素，直接退回重写；写死颜色、全大写 + 加字距的标签、脚本不处理取数失败，作为警告报给模型。

卡片里的一切仍然由模型写的 HTML / CSS / JS 决定，kit 只是它的起点；lint 拦的是「读不出信息」的排版，不是某种审美。

面板 kit 的四种版式（亮色 / 暗色）

面板模型参考了 ChisaBot 的两种面板：沙箱 HTML 自定义面板，以及机器人定时刷新的实时面板。

截图

dsh-pad 悬浮面板窗口

在对话里说要什么面板，模型就用 pad_ 工具把卡片建出来。三张示例面板分别是：服务器性能（命令数据源，每 3 秒刷新）、最新 Release（HTTP 数据源，解析 GitHub 的 Atom feed）、AI 今日简报（AI 刷新）。

自由分区：左边上下两张，右边一张

把卡片拖到另一张卡片的上 / 下 / 左 / 右边缘，就在那个位置分出新区域，并且可以继续嵌套——这里左边上下两张、右边一张大卡；分隔条拖动调比例，一行最多 3 张。

收起后是一颗悬浮球，可以拖到窗口任意位置，靠近四边自动吸附，点一下重新展开。

暗色主题

卡片颜色跟着 dsh 的亮色 / 暗色主题走，iframe 里的 CSS 变量会同步切换。

安装

需要 dsh ≥ 0.2.1-rc.2，用 Web 界面（dsh web）或鲸屿桌面端。

插件以 bundle 方式登记（写进 profile 的 dsh.profile.bundles）。不要把本仓库 cordis.patch.yml 的内容手抄进 profile 的 cordis.patch.yml：那里没有对应的模块解析，启动时整个应用会起不来。

先自检：lib/ 是否齐全、profile 里有没有残留
node scripts/doctor.mjs

从本地目录（开发时）
dsh plugin --profile web add /path/to/dsh-pad

从 GitHub 安装（仓库里带着构建好的 lib/，不需要跑构建脚本）

dsh plugin --profile web add github:ChisaAlter/dsh-pad#v0.4.5

lib/index.js 和 lib/client.js 是唯一的运行入口。本仓库把它们提交进 git，就是为了让 GitHub 安装不依赖构建脚本（pnpm 默认会拒绝执行依赖的构建脚本）。改了源码，先在插件目录跑 npm install && npm run build，再安装。

装好后重启 dsh web / 鲸屿。卸载：dsh plugin --profile web remove dsh-pad。

更新

插件启动后会在后台检查 GitHub Release（默认每 6 小时一次，启动约 7 秒后第一次）。有新版本时：

1. 面板坞顶部出现下载图标（没有新版本时不显示）；
2. 点开，看到当前版本和新版本，点「更新」；
3. 插件先下载并校验完整的 lib/index.js、lib/client.js、package.json 和 cordis.patch.yml，备份到 .dsh-pad-update-backup/，记录更新事务后再替换；
4. 重启 dsh web / 鲸屿后生效。更新中断时，加载入口会先完成已记录的事务；暂存文件损坏会阻止插件加载，避免用上混合版本。

事务恢复从 0.4.5 的更新器开始生效。旧版更新器首次升级到 0.4.5 时仍沿用旧流程，建议关闭应用后安装完整版本。

如果当前是开发目录链接安装（插件目录里有 .git/），自动更新只提示新版本，不会覆盖源码；请在插件目录执行 git pull && npm run build。更新面板里的「重新检查」可以立即查一次；关闭后台检查设 updateCheck: false。

装坏了怎么恢复

装上之后如果鲸屿或 dsh web 起不来：

1. 打开 $DSH_HOME/profiles/web/package.json，从 dsh.profile.bundles 里删掉 "dsh-pad"，并从 dependencies 里删掉 "dsh-pad"。
2. 打开 $DSH_HOME/profiles/web/cordis.patch.yml，删掉任何 insert 了 dsh-pad 的条目（正常情况下这里不该出现它）。
3. 删掉 $DSH_HOME/profiles/web/node_modules/dsh-pad（它只是一个链接）。
4. 重新启动。
5. 再装之前先跑 node scripts/doctor.mjs，它会直接指出是 lib/ 缺失、链接缺失，还是 profile 补丁被手写了。

使用

直接在对话里说想要什么面板：

做一个观察这台服务器性能的面板：CPU、内存、磁盘、负载，每 3 秒刷新

做一个面板显示我的 DeepSeek API 余额，key 在环境变量 DEEPSEEK_API_KEY 里

做一个面板盯着 deepseek-ai/deepseek-harness 的最新 release，每 6 小时让 AI 更新一次

面板坞顶部的 ＋ 会把一段「用 pad_create 创建自定义面板」的提示词插入当前对话输入框（不会自动发送），接着写你的需求再发送即可。新面板出现时，面板坞会自动展开并高亮这张卡片。

每张卡片的 ⋯ 菜单里有：「让 AI 修改…」（把修改请求填进输入框）、撤销上次修改、面板模型、删除。点卡片标题可以折叠；折叠后的面板不再轮询。

每张卡片左上角的 六点握把 可以拖到另一张卡片上：落在左 / 右边缘会分成左右两栏，落在上 / 下边缘会分成上下两区，落在中间会交换两张卡片的位置。分区可以继续嵌套——例如先把三张卡片排成一行，再把中间那张拖到左边卡片的底边，就得到「左边上下两张 + 右边独立一张」。
text
┌──────────────┬──────────────┐
│ CPU 趋势 │ │ ├──────────────┤ 网络流量 │ │ 内存 │ │ └──────────────┴──────────────┘

把卡片拖到面板坞空白处会拆成整行、排到底部。左右分栏的竖分隔条可以拖动调整相邻两栏的宽度比例；新面板单独成行，排在底部。

每张卡片底部有一条细横条：上下拖动可以调整面板高度，双击恢复自动高度；高度按面板记在浏览器里（localStorage），重启后仍然有效。

面板坞本身：拖标题栏可以放到屏幕任意位置（位置记在浏览器里），拖左边缘调宽度，拖上边缘或下边缘调整整体高度（面板列表在内部滚动，双击边缘恢复自动高度，高度也记在浏览器里）。点顶部的收起按钮，面板坞会变成一颗悬浮球，球停在收起按钮原来的位置；展开和收起时星花固定在按钮位置，球面和面板交叉淡入淡出。展开后长按这颗星花可以拖动整个面板窗口，短按仍是收起。球跟随主题、可以用鼠标拖到任意位置，靠近窗口四边会自动吸附，点击重新展开。顶部的 ＋ 用来创建新面板。

examples/ 下有三份完整的面板定义（服务器性能、DeepSeek 余额、GitHub release），可以当作模型输出的参考。

面板是怎么工作的

数据流：模型写面板定义，宿主轮询数据源，浏览器渲染卡片

一张面板的定义： jsonc { "title": "服务器性能", "icon": "🖥️", "html": "…", "css": "…", "script": "…", "height": "auto", // 或固定像素
"sources": [ // 直接数据源，可以为空
{ "id": "host", "kind": "command", "command": "…", "parse": "json", "intervalSec": 3 }, { "id": "bal", "kind": "http", "url": "https://api.deepseek.com/user/balance",
"headers": { "Authorization": "Bearer {{env:DEEPSEEK_API_KEY}}" }, "parse": "json", "intervalSec": 600 }
],
"model": { "provider": "magpie", "model": "codex/gpt-6.1-sol" }, // 可选：这张面板用的模型
"agent": { "instruction": "…", "everyMinutes": 360 } // 可选：AI 刷新
}

- 直接数据源在展开的卡片或放大视图可见时轮询；所有客户端都关闭、或面板坞收起后停止轮询。命令与 HTTP 输出上限 512KB，默认超时 10 秒；解析后的 JSON 最多 64 层、100,000 个节点。
- 重启后先显示上次的数值：每个数据源最近一次成功读数、以及最近 20 个点写在 $DSH_HOME/dsh-pad/readings.json（10 秒合并写一次，单条 JSON 超过 16KB 不缓存，单个数据源的历史最多留 128KB，数据源改过之后旧读数自动作废）。面板坞一展开就先拿它渲染，趋势图也直接有历史，第一次轮询回来再接着往后画；这个文件只是缓存，删掉只会让面板重新等第一次读数。
- 密钥：{{env:NAME}} 先从 dsh 凭据服务里解析，没有再读宿主进程的环境变量。错误信息里出现的密钥值会被替换成 **。带密钥引用、自定义敏感头或请求体的 HTTP 请求只跟随同 origin 重定向；跨 origin 时返回错误，请直接配置可信目标网址。
- AI 刷新：后台智能体默认使用 dsh 的默认模型和默认智能体预设（有 web_fetch / web_search 等工具），另外只多两个工具：pad_submit_data 和 pad_report_failure。面板可以带顶层 model（{ provider, model, reasoningEffort? }）单独指定模型；不写就跟随全局默认。这个模型同时用于面板里的 dsh.run。卡片 ⋯ 菜单里的「面板模型」可以直接切换。它只看得到 instruction 和上一次提交的数据。单轮最长 5 分钟（可配置），失败后过一段时间重试，原因会显示在卡片上。
- 面板脚本在 sandbox="allow-scripts" 的 iframe 里运行：不和 dsh 同源，CSP 是 default-src 'none'，没有网络，拿不到 cookie 和存储，也访问不到父页面。唯一的出口是 window.dsh：

| API | 说明 |
| dsh.onData(fn) | 有数据时立即调用，之后每次更新再调用。data = { sources: { [id]: { ok, value, error, at } }, agent: { value, at } \| null } |
| dsh.history(id) | 该数据源最近 120 次成功读数（页面打开期间累积；重启后先带上上次缓存的最近 20 个点），画趋势用 |
| dsh.refresh() / dsh.openUrl(url) / dsh.ask(text) | 立即刷新 / 新标签打开链接 / 把一句话填进对话输入框 |
| dsh.run(prompt, { system? }) | 用这张面板的模型跑一次，返回 { ok, text?, error? }；纯文本生成，没有工具和网络，适合按钮处理当前数据 |
| dsh.state.get(k) / dsh.state.set(k, v) | 按面板保存的小量 UI 状态 |
| dsh.fmt. | bytes percent number ago time duration |
| dsh.chart. | sparkline bar ring，返回 SVG / HTML 字符串 |
| dsh.tone(x) / dsh.escape(s) | 按阈值给出 ok / warn / danger 颜色 / HTML 转义 |

dsh.run 只做一次纯文本生成：prompt 最长 2.4 万字，结果最多 3.2 万字，默认 120 秒超时、2048 输出 token；模型来自面板顶层 model，没有就跟随全局默认。它不会调用工具；要联网取数，先用直接数据源或 AI 刷新把数据放进面板，再交给 dsh.run 处理。dsh.ask 仍然是把话交给主对话，不是面板模型。

主题变量：--pad-fg --pad-fg-2 --pad-fg-3 --pad-bg --pad-bg-2 --pad-border --pad-accent --pad-ok --pad-warn --pad-danger --pad-font --pad-mono --pad-radius。

给模型的编写手册在 src/host/guide.ts：短版作为 pad_create 的工具说明常驻，完整版（版式、kit、配方、dsh API）由 pad_guide 按需返回。

模型可用的工具

| 工具 | 作用 |
| pad_list / pad_get | 列出面板 / 读完整定义和最新数据 |
| pad_guide | 版式手册：五种版式、kit 类名、完整配方、dsh API、取数方式 |
| pad_test_source | 试跑一个数据源，先看清输出格式再写脚本 |
| pad_create / pad_update | 新建 / 修改（只传要改的字段），返回排版检查结果和首次读数 |
| pad_models | 列出可用于面板的 provider / 模型 / 推理强度，以及全局默认模型 |
| pad_refresh | 立即刷新，并返回读数，修好面板后用来验证 |
| pad_delete | 删除 |

配置

在 $DSH_HOME/profiles/web/cordis.patch.yml 里覆盖（patch 会替换整个 config，写全需要的键）：

- id: dsh-pad
name: dsh-pad
config:
minIntervalSec: 2

| 键 | 默认 | 说明 |
| dataFile | $DSH_HOME/dsh-pad/panels.json | 面板存储位置 |
| minIntervalSec | 2 | 直接数据源最短刷新间隔（秒） |
| agentRefresh | true | 是否允许 AI 刷新的面板 |
| minAgentMinutes | 15 | AI 刷新最短间隔（分钟） |
| agentTimeoutSec | 300 | 单轮 AI 刷新的最长时间 |
| agentConcurrency | 1 | 同时进行的 AI 刷新数量 |
| agentRetryMinutes | 15 | AI 刷新失败后的重试间隔 |
| interactiveModel | true | 是否允许面板按钮通过 dsh.run 调用面板模型 |
| runTimeoutSec | 120 | 一次 dsh.run 的最长时间（秒） |
| runMaxTokens | 2048 | 一次 dsh.run 最多生成多少 token |
| runConcurrency | 2 | 同一张面板同时进行的 dsh.run 数量 |
| updateCheck | true | 后台检查 GitHub 最新 Release |
| updateCheckHours | 6 | 自动检查间隔（小时，1–168） |

数据与已知限制

- 面板存在 $DSH_HOME/dsh-pad/panels.json；每个数据源最近一次成功读数和最近 20 个点存在同目录的 readings.json（只为重启后立刻有画面和趋势，可随时删除）；悬浮球位置、窗口位置 / 宽度 / 高度、嵌套分区和分隔比例按浏览器存在 localStorage。
- 每次 AI 刷新都是一个独立的 dsh 会话，工作目录是 $DSH_HOME/dsh-pad/refresh。dsh 目前不提供删除会话的接口，所以这些会话日志会留在 $DSH_HOME/sessions/ 下对应这个目录的子目录里（每轮大约十几 KB）。它们不会出现在侧栏，需要清理时手动删除即可。
- 后台刷新的智能体没有人在线审批，所以需要审批的工具调用（比如 workspace-write 模式下的 shell 命令）会被拒绝。AI 刷新适合用 web_fetch / web_search 取数；本机命令请用直接数据源。
- 在 dsh 0.2.1-rc.2 的 Web 界面（dsh web）与鲸屿桌面端上验证过：安装后宿主半激活、9 个 pad_ 工具注册、六个 /api/dsh-pad. 路由可用，客户端面板坞在无头 Chrome 中渲染无异常。dsh 的插件 API 还在快速变化。悬浮坞挂在 dsh 的 shell.overlay 槽位；宽屏让位是给外框（data-titlebar-density）加 padding-right，右侧面板因此一起左移、不会被坞盖住；回合导航条则在 @container 里按对话宽度（≥ 800px）重新显示。dsh 以后改掉这些属性或类名，最坏也只是退化成纯悬浮、导航条按 dsh 自己的规则隐藏，不会坏。

开发

npm install
npm run build # lib/index.js（宿主半）+ lib/client.js（浏览器半，dsh 的闭包模块格式）
npm run watch
npm run typecheck
npm test
npm run doctor # 安装前后自检：lib/、exports、profile 登记与残留补丁

src/
index.ts 宿主插件入口：配置、存储、调度、路由、工具 host/ store.ts 面板存储（JSON 文件、撤销、布局位置） sources.ts 命令 / HTTP 数据源执行、密钥填充与脱敏 hub.ts 按订阅轮询，向浏览器推送 SSE agent-refresh.ts 后台 AI 刷新 models.ts 模型目录与选择校验 run.ts 面板内 dsh.run 的一次性模型调用 update.ts 检查 GitHub Release，按点击下载替换 lib/ tools.ts pad_ 工具 lint.ts 排版检查：文字墙 / 长段落 / 贴 JSON / 没有可视元素 guide.ts 给模型的编写指南与版式手册（pad_guide） routes.ts /api/dsh-pad.{panels,stream,action,models,run,update}（经 dsh Connection 认证） client/ index.ts 浏览器插件入口：shell.overlay 悬浮坞 + 输入框桥接 Dock.tsx 悬浮球 / 面板窗口 / 卡片拖放 PanelCard.tsx 卡片 PanelFrame.tsx 沙箱 iframe layout.ts 嵌套分区树（上下 / 左右分栏、拖放插入、迁移旧布局） frame-runtime.ts iframe 内的 window.dsh（含 dsh.ui 生成器） pad-client.ts SSE 连接、历史、布局 shared/ types.ts 两半共用的类型 validate.ts 面板定义校验 kit.ts 面板 kit：预置 CSS 与可视元素清单（iframe 与 lint 共用） examples/ 面板定义示例 tests/ 单元测试（vitest）

致谢

感谢 Linux.do（L 站）社区的支持、讨论和反馈，也感谢 DeepSeek Harness 与 ChisaBot 在面板形态上的启发。

面板的设计约束参考了两处：版式与视觉方向取自 TheInternetDesigns 上收集的界面风格，反「AI 味」的硬性规则（不做 eyebrow、不用追踪大写标签、不堆文字、不编数据、状态不用 emoji）取自 Nutlope/hallmark 的 Floor。

许可

MIT