dsh-service

English

面向自托管 DSH Web 的服务控制与运维插件。提供安全重启、版本管理与一键升级、健康诊断、模型用量统计、备份管理、任务通知和 Linux 文件权限维护。

功能

设置页「服务控制」面板包含八个顶部标签：概览、通知、健康诊断、模型统计、额度查询、备份维护、技能、重启；重启、额度查询与技能标签还可在设置页左侧标签列底部开启快捷入口（默认关闭）。

插件同时出现在「插件 → 插件配置」，提供六个默认开启的宿主级开关：模型统计、额度查询、备份维护、任务通知、技能管理、/healthz 探活端点。关闭后不仅隐藏对应界面，也会停止相关轮询/订阅并由宿主拒绝对应能力；概览、健康诊断与重启固定保留。设置写入 DSH settings，六项均为热生效：关闭或重新开启都无需刷新页面或重启 DSH Web。已在途的统计刷新、额度请求或备份操作允许完成；额度重新开启时保留既有缓存、TTL 与退避状态，因此可立即恢复界面和调用，但不保证立刻重新请求上游。

版本与更新

• 显示当前 DSH 和插件版本，版本号链接到 GitHub Releases
• 自动检查 npm registry 的正式版和预览版；有新版本时右侧「小三角 + 有新版本」状态文本可点击展开/收起，行内展示当前/最新版本与正式版/预览版双 tag，版本号分别带 npmjs 与 npmmirror 链接（部分网络会被 npmjs.com 拦截，npmmirror 作为镜像入口）
• 一键升级插件，升级后自动重启；未检测到进程管理器（如在 Windows 终端手动启动）时，升级前先确认后果，安装完成后保持运行并提示手动重启

安全重启

• 重启前检测活跃 Agent、后台任务和终端，展示清单并要求显式确认
• 对话中输入 /restart 也可触发，检测到运行中工作时自动拒绝
• 重启后自动探测新进程并刷新页面，60 秒未恢复时提供手动刷新
• 疑似终端手动启动时，重启确认流程会提示「退出后不会自动拉起」，健康诊断中以黄色行内警示标注
• 可在「重启」标签开启「设置页左列显示入口」开关（默认关闭），开启后在设置页左侧标签列底部显示「重启」快捷入口，与「重启」标签共用同一套确认流程

健康诊断

• 显示运行时间、内存、会话数、活跃 Agent 和后台任务
• 「进程与运行环境」卡显示平台、架构和 Node 版本
• 完整诊断检查会话存储、工作区注册表、备份目录、tar 可用性、文件权限、运行环境和 Node 运行时版本；手动启动环境以黄色行内警示标注重启无保障（不触发健康提醒横幅、服务控制提醒和标签 ⚠），未识别环境与空备份为信息级提示（不算警告），均可通过 DSH_SERVICE_RUNTIME_ENV 显式声明
• 没有备份属于信息级提示，不算警告，也不点亮健康诊断标签的 ⚠
• 文件权限深检与修复：检查 Agent 是否能读写 DSH_HOME 和工作区，修复需两段式确认

模型统计

• 近 7 天输入/输出/缓存 token 堆叠柱图，蓝/橙/青图例
• 按项目筛选，鼠标悬停显示精确数值
• 模型明细为横向堆叠柱形图（沿用主图图例配色），列表头部右侧提供「今日 / 近 7 天 / 累计」切换标签（默认近 7 天）：今日只聚合当天，近 7 天按主图同窗口排序，累计覆盖索引内全部日期（受会话持久化留存范围限制）；每行附「x次 · 缓存命中 x% · 输入 xM token · 输出 xM token」明细
• 提供方未上报 token 用量的模型步骤不纳入统计
• 最近 24 小时模型/工具报错统计，默认折叠

额度查询

• 独立的「额度查询」标签：以卡片分区展示已适配的供应商，每个窗口显示百分比、独立进度条，重置时间单独一行；卡片头部更新时间旁有刷新图标，点击即强制重拉该供应商（不受轮询间隔限制）；未适配的不占位置，统一收进底部「手动适配」行选择类型启用，卡片脚部可随时切换适配类型、回退自动识别或停用查询
• 对话输入框内一枚额度圆环，跟随当前会话所选模型的供应商，显示最紧预算窗口的已用百分比（<80% 绿色、≥80% 黄色）；点击弹出面板——头部标明供应商，各窗口带独立进度条与已用百分比、重置时间单独一行；手机等窄屏上面板自动切换为视口居中的浮层（完整可见、超高时内部滚动），旋转或拖宽窗口即时切回圆环上方锚定
• 可在「额度查询」标签开启「设置页左列显示入口」开关（默认关闭），开启后在设置页左侧标签列底部显示「额度查询」快捷入口（与「重启」入口同模式）
• 内置适配：OpenCode Go（{baseURL}/usage）、智谱 GLM Coding Plan / zai-coding-cn（官方监控端点 quota/limit，含 5 小时滚动 Token、每周 Token、MCP 月度配额三个窗口，5 小时窗口空闲时与官网一致地不显示重置时间）、OpenRouter（credits 已用%）、Kimi/Moonshot 与 硅基流动（人民币余额）；原生报「剩余百分比」的方言会自动把面板头部切换为「剩余」并把预警阈值反向；上游瞬时网络错误自动重试，智谱双域候选链自动切换；供应商与适配类型的对应关系保存在 DSH_HOME/dsh-service-quota.json，已知服务商按 baseURL 自动识别适配（如 opencode.ai、bigmodel.cn），无需手选；未适配或已停用的供应商不会被发起任何上游请求，停用可在卡片脚部选「停用查询」或在配置文件写 "<provider>": null（两者等价）。智谱的重置卡暂无 API Key 可查的接口，可在「额度查询」标签内点各供应商卡片的「添加重置卡」填写名称与到期时间（可精确到分钟），可连续添加多条、每条独立移除；圆环面板同步显示（数据存入同一配置文件），过期自动标注
• 防风控节律由宿主统一控制：成功结果缓存 60 秒（多标签共享）、失败指数退避（30 秒起 ×2、封顶 15 分钟）、上游超时 15 秒；面板可把自动查询调成仅手动 / 1 / 2 / 5 / 10 分钟（默认仅手动），页面不可见时自动暂停
• API key 只在宿主进程内解析使用，浏览器只会收到归一化后的百分比数字；数据走插件自有 loopback RPC，不在 webServer 上暴露任何路由

备份管理

• 创建会话、配置和插件 profile 清单的 .tar.gz 归档
• 导出：下载备份到浏览器
• 恢复：解压覆盖到对应路径，两段式确认后自动重启
• 导入：选择 .tar.gz 文件上传到备份目录
• 删除需两段式确认，备份不限份数，不自动清理

技能管理

• 「技能」标签按自动加载 / 仅手动调用 / 完全停用三区展示全部本地技能（项目 .dsh、项目 .agents、用户 ~/.dsh/skills、$DSH_AGENTS_HOME 与 $DSH_BUNDLED_SKILL_DIR 根，一层深度），支持名称过滤与来源徽标；同名遮蔽（低 rank 优先）与被遮蔽副本均有标注，内置目录只读展示；同一物理目录被多条规则命中时只计一次
• 每条目双开关直接改写 SKILL.md frontmatter：disable-model-invocation 控制「对模型可见」，user-invocable 控制「可被 / 调用」；开关采用两段式点击确认，改动约 200ms 内热生效，活跃会话下一步自动收到目录更新提示；往返切换不会在文件中累积残留
• 带 camelCase 旧版调用键（如 disableModelInvocation）的条目会被官方解析器整条剔除：面板给出 ⚠ 提示，两段式确认后按语义换算修复为规范键
• ✨「AI 补全说明」：从已配置模型中任选一个（记住上次选择），宿主用固定模板调用该模型生成简体中文的描述与用法草稿；草稿以新旧对照预览，显式确认后保存为「AI 注释」。注释只存在插件的侧车索引 DSH_HOME/dsh-service-skills-index.json 里、绝不改写 SKILL.md，仅在技能标签页该条目下方单独展示（带移除按钮）；正文变更后注释自动标记过期，重新补全即可刷新
• 一键批量补全：自动圈出未注释或正文有变的技能（含只读目录，跳过无效与被遮蔽副本），先展示候选数/预计发送量与可展开的逐条跳过清单，确认后顺序执行并显示进度，单条失败不影响批次，可随时取消（取消会立即中断在途模型调用）；全程零文件改动，也绝不自动发起任何模型调用
• 批量任务在宿主后台持续运行：切换标签、关闭设置面板甚至刷新页面都不会中断；回到技能页自动恢复进度与取消按钮，批量进行中「技能」标签标题实时显示 ⟳已完成/总数 角标，运行中重复生成计划会被明确拒绝

任务通知

• 通知设置位于服务控制顶部的「通知」标签：会话完成一轮任务、或需要你授权/审阅计划/选择答案时发送浏览器通知
• 点击系统通知弹窗会聚焦到 DSH 页面并关闭该通知
• 三档开关条：总开关、任务结束通知、授权与提问通知，各自独立控制
• 对话栏内铃铛图标快速切换总开关
• 各开关在页面刷新后保持

外部探活

• GET / HEAD /healthz 返回空的 HTTP 200，其他方法返回 405
• 适合 Uptime Kuma、Docker、Kubernetes 等外部监控

安装

从 npm 安装（推荐）

dsh plugin --profile web add @gehennawu/dsh-service

从 GitHub 安装

dsh plugin --profile web add github:gehennawu/dsh-service

安装或更新后重启 DSH Web：

dsh web

打开 DSH Web 设置页，进入 服务控制。

本地开发安装

dsh plugin --profile web add link:/path/to/dsh-service

自动重启配置

插件只发送退出信号，不负责重新启动进程。没有进程管理器时，点击重启会直接停止 DSH Web。

插件会用被动信号（环境变量、/.dockerenv、/proc/1/cgroup、终端 TTY）判断当前是否由进程管理器拉起：检测到 Docker/systemd/pm2/supervisord/Kubernetes 时照常自动重启；都没有且 stdin/stdout 是交互终端时视为「疑似手动启动」，健康诊断会以黄色警示标注，一键升级改为「不自动退出 + 提示手动重启」。启发式无法覆盖输出重定向、NSSM/WinSW 等场景，可用环境变量 DSH_SERVICE_RUNTIME_ENV=managed|manual 显式声明。

Docker Compose

services:
  dsh:
    restart: unless-stopped

systemd

[Service]
ExecStart=/usr/local/bin/dsh web --host 127.0.0.1
Restart=on-failure
RestartSec=2

pm2

pm2 start "dsh web --host 127.0.0.1" --name dsh-web

平台支持

直接在终端运行（PowerShell/CMD/bash）时，面板会标注「疑似终端手动启动」，一键升级不再自动退出进程。

运行要求：Node.js >=22，DSH Web 能加载 Host 和 Client 两半插件。检查更新需要访问 registry.npmjs.org；网络失败不影响其他功能。

安全设计

• 浏览器端不能传入 URL、包名、命令或文件路径
• 更新检查只访问固定的 npm registry 地址
• RPC channel 仅接受 loopback 调用
• 模型用量索引不保存消息、Prompt、Tool 参数或凭据
• 破坏性操作（重启、删除、修复权限）均需两段式确认

许可证

MIT