dsh-pad
DeepSeek Harness 插件：悬浮面板坞，面板由 AI 在对话里生成并自由分区；支持本机/HTTP 数据源、AI 刷新、面板内 dsh.run 模型调用
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:ChisaAlter/dsh-pad#d8e3458f5f454f1e7fe88805fd303dc283ff0b67Pad 以 dsh-pad 发布，当前版本为 0.4.5。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
简体中文 · English
DeepSeek Harness（dsh）的悬浮面板插件。面板由 AI 在对话里生成：比如「做一个观察这台服务器性能的面板」「做一个面板显示我的 DeepSeek API 余额」。
pad_* 工具创建和修改面板。面板是跑在沙箱 iframe 里的 HTML / CSS / JS，颜色跟随 dsh 的亮色 / 暗色主题。dsh.run(prompt)，用这张面板自己的模型跑一次并把结果显示在卡片里；也支持 AI 刷新用同一模型。{{env:NAME}} 引用，只在宿主侧解析，不会发到浏览器。面板不是一页报告，是一张 200–400px 的卡片：一个数字、几行数据、一条趋势。为了让它每次都是这样，插件在三处下了手：
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 拦的是「读不出信息」的排版，不是某种审美。
面板模型参考了 ChisaBot 的两种面板：沙箱 HTML 自定义面板，以及机器人定时刷新的实时面板。
在对话里说要什么面板，模型就用 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 秒后第一次）。有新版本时：
lib/index.js、lib/client.js、package.json 和 cordis.patch.yml，备份到 .dsh-pad-update-backup/，记录更新事务后再替换；dsh web / 鲸屿后生效。更新中断时，加载入口会先完成已记录的事务；暂存文件损坏会阻止插件加载，避免使用混合版本。事务恢复从 0.4.5 的更新器开始生效。旧版更新器首次升级到 0.4.5 时仍沿用旧流程，建议关闭应用后安装完整版本。
如果当前是开发目录链接安装（插件目录里有 .git/），自动更新只提示新版本，不会覆盖源码；请在插件目录执行 git pull && npm run build。更新面板里的「重新检查」可以立即查一次；关闭后台检查设 updateCheck: false。
装上之后如果鲸屿或 dsh web 起不来：
$DSH_HOME/profiles/web/package.json，从 dsh.profile.bundles 里删掉 "dsh-pad"，并从 dependencies 里删掉 "dsh-pad"。$DSH_HOME/profiles/web/cordis.patch.yml，删掉任何 insert 了 dsh-pad 的条目（正常情况下这里不该出现它）。$DSH_HOME/profiles/web/node_modules/dsh-pad（它只是一个链接）。node scripts/doctor.mjs，它会直接指出是 lib/ 缺失、链接缺失，还是 profile 补丁被手写了。直接在对话里说想要什么面板：
做一个观察这台服务器性能的面板：CPU、内存、磁盘、负载，每 3 秒刷新
做一个面板显示我的 DeepSeek API 余额，key 在环境变量 DEEPSEEK_API_KEY 里
做一个面板盯着 deepseek-ai/deepseek-harness 的最新 release，每 6 小时让 AI 更新一次
面板坞顶部的 ＋ 会把一段「用 pad_create 创建自定义面板」的提示词插入当前对话输入框（不会自动发送），接着写你的需求再发送即可。新面板出现时，面板坞会自动展开并高亮这张卡片。
每张卡片的 ⋯ 菜单里有：「让 AI 修改…」（把修改请求填进输入框）、撤销上次修改、面板模型、删除。点卡片标题可以折叠；折叠后的面板不再轮询。
每张卡片左上角的 六点握把 可以拖到另一张卡片上：落在左 / 右边缘会分成左右两栏，落在上 / 下边缘会分成上下两区，落在中间会交换两张卡片的位置。分区可以继续嵌套——例如先把三张卡片排成一行，再把中间那张拖到左边卡片的底边，就得到「左边上下两张 + 右边独立一张」。
┌──────────────┬──────────────┐
│ CPU 趋势 │ │
├──────────────┤ 网络流量 │
│ 内存 │ │
└──────────────┴──────────────┘
把卡片拖到面板坞空白处会拆成整行、排到底部。左右分栏的竖分隔条可以拖动调整相邻两栏的宽度比例；新面板单独成行，排在底部。
每张卡片底部有一条细横条：上下拖动可以调整面板高度，双击恢复自动高度；高度按面板记在浏览器里（localStorage），重启后仍然有效。
面板坞本身：拖标题栏可以放到屏幕任意位置（位置记在浏览器里），拖左边缘调宽度，拖上边缘或下边缘调整整体高度（面板列表在内部滚动，双击边缘恢复自动高度，高度也记在浏览器里）。点顶部的收起按钮，面板坞会变成一颗悬浮球，球停在收起按钮原来的位置；展开和收起时星花固定在按钮位置，球面和面板交叉淡入淡出。展开后长按这颗星花可以拖动整个面板窗口，短按仍是收起。球跟随主题、可以用鼠标拖到任意位置，靠近窗口四边会自动吸附，点击重新展开。顶部的 ＋ 用来创建新面板。
examples/ 下有三份完整的面板定义（服务器性能、DeepSeek 余额、GitHub release），可以当作模型输出的参考。
一张面板的定义：
{
"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 刷新
}
$DSH_HOME/dsh-pad/readings.json（10 秒合并写一次，单条 JSON 超过 16KB 不缓存，单个数据源的历史最多留 128KB，数据源改过之后旧读数自动作废）。面板坞一展开就先拿它渲染，趋势图也直接有历史，第一次轮询回来再接着往后画；这个文件只是缓存，删掉只会让面板重新等第一次读数。{{env:NAME}} 先从 dsh 凭据服务里解析，没有再读宿主进程的环境变量。错误信息里出现的密钥值会被替换成 ***。带密钥引用、自定义敏感头或请求体的 HTTP 请求只跟随同 origin 重定向；跨 origin 时返回错误，请直接配置可信目标网址。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。$DSH_HOME/dsh-pad/refresh。dsh 目前不提供删除会话的接口，所以这些会话日志会留在 $DSH_HOME/sessions/ 下对应这个目录的子目录里（每轮大约十几 KB）。它们不会出现在侧栏，需要清理时手动删除即可。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