Skip to main content
K

dsh-butler-panel

kira905/dsh-butler-panel

大管家的可视化面板:在 DSH 侧边栏看今天该看什么(结论 / 待处理 / 资产 / 流水 / 健康),只读为主;另带 P5 写入守门人(可挂可摘)。

Install

dsh plugin --profile web add github:kira905/dsh-butler-panel

README

dsh-butler-panel · 大管家面板

这是什么

一页看清"今天该看什么"的面板:在 DeepSeek Harness 的侧边栏挂一个「大管家」,把看板在途卡、重启后被打断的会话、最近的变更流水、记忆条数、健康水位、待处理告警,拼成一块首屏。 它原本是一个长期自动运维的管家身上天天被打开的那一屏,现在把这一屏单独拿出来开源。

它解决什么

程序自己跑起来之后,真正的麻烦不是"跑得慢",是没人知道它此刻在干什么、卡在哪、要不要人接手。 这块面板的取舍就三条:

  1. 只读优先:绝大多数卡片只是把权威状态照原样读出来,判定一律不在这里算——面板自己算一套,就会和命令行查出两个答案。
  2. 缺数据就说缺:读不到就显示「不可探测」并写原因,绝不用 0 冒充"没有数据"。
  3. 能关:每个模块都有开关,关掉就是真关(改动带"谁改的、为什么")。

一条命令跑起来

先确认你的 DSH 能装上插件(需要 pnpm),然后:

npm i @kira905/dsh-butler-panel
# 或者装进某个 profile 后重启 dsh,侧边栏底部会多一个「大管家」入口

装完先设一个变量告诉它你的大管家在哪(见下一节)——不设也能起来,但大部分卡片会显示「不可探测」。

它不附带什么(先看清楚,省得装完失望)

  1. 它自己要读的那套工具目录。本仓只有面板本身;看板判据、告警判定、日报生成器、角色与人设、通知通道都在别处。没有那套目录,面板能启动、但只剩空壳。
  2. 调度内核(定时、锁、放行矩阵)。那是另一个包 @kira905/dsh-butler-engine。
  3. 任何"喊到人"的通道:企业微信、微信、语音播报这类绑定具体账号与私人日程的,不随开源发布。
  4. 视觉回归的基线图。仓里留下采集与比对脚本,但一张图都没带——那些截图是面板当天的真实画面,印着主线名、本机路径、会话 id。你自己跑一次就有了。

所以你装到的是一块仪表盘,不是一个会自己上班的管家。

接上你自己的大管家

面板找库分四路,前命中即用:

路来源说明
①BUTLER_ROOT / DSH_BUTLER_LIB_DIR(还认 BUTLER_LIB_DIR)你显式指了就以你指的为准(BUTLER_ROOT = 你的大管家工具目录,即 <工作区>/tools/dsh-butler),优先级最高
②<工作区>/tools/dsh-butler/lib工作区约定位置(DSH_WORKSPACE 不设时 = <用户主目录>/DSH)
③已安装的 @kira905/dsh-butler-engine 包依次试包内 lib/ → src/dsh-butler/lib/ → src/lib/ → jobs/lib/。定位包根按「显式 env DSH_BUTLER_ENGINE_ROOT → Node 模块解析 → 全局 npm 前缀」三档走
④都落空占位 + 一行可照做的指引(见下)

为什么要第 ③ 路:不是每台机器都有「大管家工具目录」——那本来是自己工作区里的东西。 但 @kira905/dsh-butler-engine 是能装的包,装上就有同一批库。于是最省事的接法变成:

npm i -g @kira905/dsh-butler-engine

环境变量仍然有用(放在最前面,压过包):

变量含义不设时
BUTLER_ROOT大管家工具根(即 <工作区>/tools/dsh-butler)<工作区>/tools/dsh-butler
DSH_WORKSPACEDSH 工作区根(tools/ 与 docs/ 所在那层)<用户主目录>/DSH
DSH_HOME / BUTLER_DSH_HOMEDSH 数据根(会话、看板账本、状态文件)~/.dsh
DSH_BUTLER_LIB_DIR只覆盖"共享库目录"这一项跟随 BUTLER_ROOT
DSH_BUTLER_ENGINE_ROOT直接点名 engine 包根(装了但找不到时的逃生口)自动探测
# 例:工具目录放在你自己的某个工作区下
$env:DSH_WORKSPACE = '<你的工作区>'

接不上会怎样:面板不会崩。缺的那几段退化成「不可探测」,并在控制台留一行告诉你怎么补:

[butler-panel] 缺 store.mjs:装 npm i -g @kira905/dsh-butler-engine@^0.5.0,或设 BUTLER_ROOT=<你的大管家工具目录>,或设 DSH_WORKSPACE=<你的 DSH 工作区(tools/ 与 docs/ 所在那层)>

(那行里的版本号是读装在盘上的包得来的,不是写死的;包完全没装时就不带版本号。) 这样设计是因为插件是整棵加载的 —— 任一模块顶层 import 失败会把整个插件树拖死、 连带 dsh web 起不来,那比"少显示一段"严重得多。

它挂在哪里

  • 宿主侧(exports["."] → lib/index.js):起 HTTP 端点 GET /api/dsh-butler/state, 按 ?parts= 分片返回;面板从不调用大模型,建议文案只从已有报告里读。
  • 浏览器侧(exports["./client"] → lib/client.js):在侧边栏底部区渲染那块面板。
  • 声明在 cordis.patch.yml(dsh.bundle.patch),装包后由宿主自动挂载。

P5 写入守门人(可选,默认跟随配置)

面板另带一道写入前闸:fs/write-intent + fs/edit-intent + tools/pre-execute 三个前置钩子, 按"一次性凭证"判定这次写入是否被授权,写前备份、写后审计、违规可回滚。

诚实边界(别当成安全边界用):

  • 它只覆盖 DSH 的 write / edit 工具。pwsh 里手写文件、或 node fs.writeFileSync 完全绕过。
  • 它是防手滑 + 事后可追,不防本机恶意进程。
  • 守门人挂不上时策略是 fail-open + 告警(拦死比放过一次更糟)——但必须让你知道"它不在岗"。

视觉回归(自己采基线)

_test/visual-baseline/ 里是五个脚本,不含任何图片:

脚本干什么
static-render.mjs离线把面板渲染成固定样例的静态页(不需要真宿主)
visual-baseline-capture.mjs连真宿主抓整页(需要 bsk 浏览器工具)
visual-diff.mjs两张图做像素差
allow-list-lint.mjs校验"允许差异清单"与逐色对账
proof-red.mjs反向证明:故意改坏一处,判据必须变红
node _test/visual-baseline/static-render.mjs --out .tmp\baseline --theme dark

static-render.mjs 默认按仓库布局找 lib/client.js;要渲别的版本用 --butler <path>。 生态面板那半默认找相邻目录的 dsh-ecosystem-panel,也可以用 --eco <path> 指定。

环境要求

  • Node ≥ 18.17(用到顶层 await 与 node: 前缀导入)
  • DeepSeek Harness ≥ 0.1.1-rc.1
  • 浏览器侧依赖 dsh-host-adapter-client:本包用 npm alias 声明成依赖 (npm:@kira905/dsh-host-adapter-client),装包时会一起带上。

许可

AGPL-3.0-only。见 LICENSE。

Related plugins