gehennawu/dsh-service

English

🛠️ dsh-service

DeepSeek Harness (DSH) Web 服务控制与运维插件
DeepSeek Harness (DSH) Web 的服务控制与运维插件。

Version
License: MIT
DSH Compatibility
Cordis
Platform
PRs Welcome
Awesome DSH Plugin

功能 •
架构 •
安装 •
自动重启配置 •
平台支持 •
安全设计 •
常见问题 FAQ •
参与贡献 •
许可证

DSH Web 服务控制与运维插件：安全重启、版本管理与一键升级、健康诊断、模型用量统计、额度查询、备份管理、任务通知、技能管理、会话管理与 Linux 文件权限维护。

概览

📑 目录

- 🚀 功能
- 版本与更新 · 安全重启 · 健康诊断 · 模型统计
- 额度查询 · 备份管理 · 技能管理 · 子代理模型
- 任务通知 · 会话管理 · 移动端适配 · 模型厂家图标 · 右栏文件编辑 · 外部探活
- 🏗️ 架构
- ⚡ 安装 · 🔄 自动重启配置 · 🖥️ 平台支持
- 🔒 安全设计 · ❓ 常见问题 FAQ · 🤝 参与贡献 · 📄 许可证

🚀 功能

设置页「服务控制」面板六页导航：概览 · 模型统计 · 额度查询 · 健康诊断 · 维护 · 配置；其中「维护」聚合 会话管理 · 技能 · 子代理 · 备份维护 · 重启 五个子页，「配置」聚合 功能开关 · 任务通知 · 设置栏标签 三个子页。重启、额度查询、会话管理可另行开启设置页左列快捷入口（默认关闭；技能与子代理的左列入口已撤销）。

「插件 → 插件配置」提供十二个宿主级开关：健康诊断、模型统计、额度查询、备份维护、任务通知、技能管理、子代理模型、会话管理、移动端适配、模型厂家图标、右栏文件编辑、/healthz 探活（除移动端适配外默认开启）。全部热生效：关闭即隐藏界面、停止轮询并让宿主拒绝对应能力；概览与重启固定保留。

插件配置

概览

- 状态摘要（error → warning → info → normal 聚合，带状态点）→ 可行动项（仅在存在时）→ 版本与运行环境 → 指标格 → 近期报错（仅非空时渲染，默认折叠）
- 状态聚合规则：健康/诊断/备份/统计/额度/重启任一失败即 error；权限异常、非咨询性诊断警告为 warning；可更新、尚无备份为 info（额度窗口高占用只在额度查询页内以进度条呈现；疑似终端手动启动属常驻环境事实，也只在健康诊断检查项与重启/升级确认中呈现——两者都不再进概览提醒）

维护与配置聚合页

维护页

配置页

- 「维护」集中会话管理、技能、子代理、备份维护与重启；记住最近使用的子页，关闭对应功能后自动回退到仍可用的项目
- 「配置」集中功能开关、任务通知与设置栏标签；开关按功能组展示并热生效，任务通知关闭时保留入口但显示置灰状态，设置栏标签支持对设置弹窗左侧全部导航标签进行手动排序（拖拽/上下箭头换位）与显隐管理，配置持久化到服务端统一配置文件 $DSH_HOME/dsh-service-config.json（多设备同步、启动自动拉取，本地缓存兜底），即时生效（服务控制面板永久锁定显示防锁死）；额度卡的排序与显隐走同一份配置（quotaCards 区块，进入额度页时拉取）
- 插件统一配置文件：各功能的轻量偏好收敛在 $DSH_HOME/dsh-service-config.json 单一文件（原子写入、0600），按功能分区块隔离——修改或清除某一区块绝不影响其他区块；大缓存（使用统计索引等）与加密凭据不在此文件内

版本与更新

- 显示当前 DSH 与插件版本，链接 GitHub Releases
- 自动检查 npm 正式版 + 预览版（latest / next 双 tag）；有新版本时行内展开对比，版本号附 npmjs 与 npmmirror 双链接
- 一键升级，完成后自动重启；未检测到进程管理器时先确认后果，保持运行并提示手动重启
- 升级落地但进程尚未重启期间（手动启动环境尤为常见），版本行改示「已安装 X，重启后生效」并收起升级按钮，重开面板或刷新页面状态依旧；重启进程后恢复常态

安全重启

安全重启

- 重启前检测活跃 Agent、后台任务与终端，展示清单并要求显式确认
- 对话输入 /restart 也可触发；检测到运行中工作时自动拒绝
- 重启后自动探测新进程并刷新页面，60 秒未恢复提供手动刷新；对话里用 /restart 触发的重启同样自动刷新（页面加载时记下进程身份，重连后比对 instanceId，新进程上线即刷新）
- 可开启「设置页左列显示入口」（默认关闭），与「维护 → 重启」子页共用同一确认流程
- 疑似终端手动启动时提示「退出后不会自动拉起」，健康诊断以黄色警示标注

健康诊断

健康诊断

- 运行时间、内存、会话数、活跃 Agent 与后台任务；「进程与运行环境」卡显示平台、架构与 Node 版本
- 完整诊断：会话存储、工作区注册表、备份目录、tar 可用性、文件权限、运行环境与 Node 版本——两行检查清单（检查名+状态点 / 详情），异常行局部淡染强调、正常行低对比
- 插件健康检查：只检查异常（官方插件页已有完整清单与开关，这里不做重复清单）——插件失败或依赖未就绪时检查项报错/警告，刚启动的 pending/loading 有短暂宽限；已释放或未知状态显式标为信息级，不误报为警告。检查清单下方列出异常插件（名称、已脱敏且限长的错误、缺失依赖）；失败插件可两段式确认后重新加载（只作用于宿主已确认失败的条目）；手动停用的插件（无论内置还是自定义）一律不算异常
- 插件兼容性：对照 DSH alpha 版本已移除/变更的接口（客户端供应商、SQLite 持久化后端、聊天/统计条样式哈希、弃用属性）扫描每个启用插件——命中即提示「可能不兼容」并给出具体原因（如「声明了已移除的客户端供应商 @deepseek-ai/dsh-client-runtime」）。分级判定：代码真实 require/import 才报「可能不兼容」；仅在 manifest 声明、代码未引用的供应商降为灰色「仅声明残留」（官方加载器对缺失供应商静默跳过，实际无害，提示作者清理即可）；退役槽位（如 settings.plugin.item）等为双版本兼容保留或仅展示位变动的接口降为蓝色「已退役接口」提示，不影响插件运行亦不触发黄色警告。升级 alpha 前或刚升级后看一眼就知道第三方插件有没有跟上；纯本地扫描、结果缓存、零网络
- 文件权限深检与修复（两段式确认）收敛在默认折叠的「权限与修复」区（有异常时按钮显示计数）
- 疑似手动启动 → 黄色警示「重启无保障」；无备份属信息级提示，不点亮 ⚠

模型统计

模型统计

- 近 7 天输入 / 输出 / 缓存 token 堆叠柱图，按项目筛选、悬停显示精确值；图例与刷新统一收进统计区头部行，图表带可访问的文本摘要
- 模型明细横条，列表头部「今日 / 近 7 天 / 累计」切换
- 最近 24 小时模型 / 工具报错统计（默认折叠、仅非空渲染）
- 提供方未上报 token 用量的步骤不纳入统计
- 单个会话无法读取、迁移或解析时继续统计其他会话，显示全项目成功/跳过数量与可展开的会话 ID、错误类别及安全摘要；失败会话有旧缓存时保留并标明过期，首次失败不计入，下次刷新重试。只有服务不可用、列表读取或索引写入失败等全局错误才让整次刷新失败

额度查询

- 供应商卡片保留既有窗口展示（标签+百分比 / 独立进度条 / 重置倒计时）；高级配置（凭据填写、类型切换、手动重置录入）默认折叠，按卡展开

额度查询

- 卡片分区展示各供应商：窗口百分比、独立进度条、重置时间；支持强制刷新与官网用量页链接
- 卡片排序与显隐：额度页「调整排序与显隐」展开管理列表，可拖拽或点 ↑↓ 调整卡片顺序，开关可隐藏不常用卡片（隐藏只影响展示，不影响查询与轮询）；配置与设置栏标签同源，写入服务端统一配置文件 $DSH_HOME/dsh-service-config.json 的 quotaCards 区块（多设备同步、本地缓存兜底，区块间互不影响）
- 对话输入框额度圆环：跟随当前会话模型所属供应商，显示最紧预算窗口用量（/package.json；拒绝越界路径、链接、特殊文件、未知内容、损坏归档与非法 profile 清单
- 恢复预检：先生成 5 分钟有效的一次性计划，展示会话整体替换、配置覆盖/移除和 profile manifest 覆盖清单；最终确认前再次校验归档 SHA-256 与当前目标指纹，发生漂移则拒绝执行
- 恢复提交使用事务日志和回滚目录：会话整体替换，配置按快照精确替换，profile 只更新 package.json 并保留 node_modules/凭据/附件；成功后托管环境自动重启，手动启动环境提示用户手动重启

技能管理

技能管理

- 按 自动加载 / 仅手动调用 / 完全停用 三区展示本地技能；同名遮蔽与被遮蔽副本均有标注，内置目录只读
- 条目默认全部折叠成一行（名称 + 来源/只读/已注释徽标）；顶部按钮对当前可见条目一键「全部展开 / 全部折叠」，点单条名称行可独立开合；无效条目的 ⚠ 与一键修复折叠态也保留
- 双开关直接改写 SKILL.md frontmatter（disable-model-invocation / user-invocable），约 200ms 热生效
- 带 camelCase 旧版键的条目会被官方解析器剔除：⚠ 提示 + 一键修复
- ✨ AI 补全说明：选模型生成描述草稿（跟随界面语言），确认后存入插件侧车索引——绝不改写 SKILL.md；支持一键批量补全（宿主后台运行、可取消）。已注释技能会在计划中单列，经「确认强制补全」二次确认后才会被覆盖（不再是一旦注释就永远无法再次补全）；补全日志时间按本机时区显示

子代理模型

子代理模型

- 三种模式：初始（不干预）/ 跟随主模型（取主对话最近一次实际使用的 provider/model）/ 自定义（固定到所选模型）
- 派生请求自带 provider/model 时始终优先，绝不覆盖预设钉死
- 自定义模式可选思考等级：仅当所选的 exact provider/model 由适配器声明了可选等级时才显示下拉；留空表示「使用目标模型默认」，由适配器在请求时物化默认值
- 该字段来自适配器 metadata（reasoning.efforts[].id），等级 ID 对宿主不透明；无等级声明的模型禁用下拉并提示
- inherit / follow / 功能开关关闭 均不注入任何 provider、model 或思考等级；显式指定 provider/model 的子代理不受影响
- 模式切换保留配置：已保存的自定义模型（含思考等级）与回退列表在三种模式间切换时不会被清除——模式只决定是否生效，切回「自定义」无需重新选择（供应商/模型已不在运行时清单时自动回落到清单首项）
- 进入无位移：本页以最近一次成功读取的配置作为首帧缓存，进入即直接落在真实模式上，不会先显示「初始」再跳到「自定义」；首次安装或换浏览器（无缓存）时先显示一行「读取配置…」
- 回退模型（按顺序）：跟随与自定义模式都可配置回退列表——第一路由不可用时（渠道已卸载、额度查询判定其不可服务）依次尝试后续模型；全部不可用则回落原生继承，不让派生失败。回退条目与主路由同一道白名单校验，思考等级逐条可选
- 对话页可见性：输入框下方常驻一行本会话子代理实际使用的模型，如 子代理：cpa/gpt-5.6-luna (xhigh) · opencode-go/deepseek-v4-flash (max)——含回退命中、显式路由与继承来源，可直接核对自定义路由是否生效。行挂官方 conversation.composer.dock 槽位，独占官方统计行的下一行、不与统计胶囊/上下文圆环同行挤占；20s 刷新，不依赖回合数据（会话发生 compaction 折叠工具调用也照常显示），由宿主派发记录兜底，任何视图都能看到；可在 维护 → 子代理 页用独立开关关闭。记录存宿主内存（页面刷新不丢、进程重启即清），官方「指派子代理模型」开关关闭与否都不影响本功能
- 配置存 $DSH_HOME/dsh-service-subagent-route.json（原子写入、0600），可一键重置

任务通知

任务通知

- 主会话完成一轮任务、或会话需要授权 / 审阅计划 / 回答问题时发送浏览器通知；子代理完成任务不发送完成通知；点击通知聚焦页面
- 子代理触发授权 / 审阅计划 / 回答问题时仍发送浏览器通知
- 四档独立开关：总开关、任务完成、授权与提问、输入框铃铛显隐
- 对话栏铃铛一键开关总通知；所有开关刷新后保持

会话管理

会话管理

- 查看：统一列表展示会话（运行中 / 冷会话 / 已归档），行内标状态徽章、工作区、事件数、文件体积；列表支持按创建时间正/倒序、按标题排序或按项目分区显示（每个工作区一个分区头：路径 + 会话数，同项目内最新在前；分区默认折叠，点击分区头展开 / 收起）；默认停在「仅归档」视图，全部 / 仅归档 / 已删除三个筛选各自首次按需向宿主拉取对应子集并缓存（模块级缓存：切换筛选零请求、关掉面板再打开秒显缓存 + 后台静默刷新一次保鲜，页面刷新才清零），「刷新」按钮可强制重拉当前视图；普通列表提供「批量选择」按钮，进入后可直接点击整条会话（无需精确点复选框）进行选择 / 取消选择，也可一键全选 / 取消全选当前筛选结果，选中行以左侧品牌色标记而不改变背景；工具栏按资格显示可执行数量并支持批量导出 / 归档 / 删除（切换筛选、搜索或进入详情会自动退出批量态）；文件体积不随列表下发、行内按需懒加载（模块级 + 宿主进程内存双层缓存：刷新浏览器 / 重开面板直接复用，删除时失效）；进详情记住列表滚动位置，返回列表原地不动（沿用官方面板滚动容器，详情期间切筛选 / 改搜索则放弃恢复）；详情按事件卡片分页浏览（宿主单槽位快照缓存：翻页/重进详情零重复读取，live 会话 30 秒内保鲜），正文按官方 Markdown 富文本渲染（复用平台官方渲染器 MarkdownText，与聊天界面观感一致：代码块/列表/表格/数学公式、默认拒原始 HTML 与危险链接；老版本 DSH 未提供该渲染器时自动回落纯文本），连续系统事件与工具消息各自默认折叠为计数块（工具消息 = tool/call、tool/result 等 tool/ 事件，以及通篇只有工具调用的 assistant 消息——这类消息占真实长会话的多数，工具参数不会再铺满详情页），点击折叠行展开明细、再点收起；搜索命中落在折叠块内时该块自动展开并保持命中高亮
- 子代理识别：派生的子代理会话行内标「子代理」徽章（判定取自官方会话头字段：origin=subagent 产品分类为准，delegationDepth 派生深度兜底老日志；仅 parentSession 的普通 fork 血统不算子代理）；搜索行「仅子代理」复选框聚焦（与「仅搜归档」同行同款控件；正交于全部 / 仅归档叠加过滤，已删除视图不显示、切换视图时状态保留），批量选择态提供「选中子代理」一键把当前可见的子代理会话并入选择集（不清既有选择；视图里没有子代理行时该按钮隐藏），配合批量归档 / 删除快速清理；老版本插件宿主不下发该标志时列表照常，勾选筛选会明示「宿主较旧、未携带子代理标志」而非留一份无解释的空列表
- 导出：一键或批量下载官方完整 ZIP（每个会话一个 ZIP，含子代理与附件），复用官方导出链路，宿主不自己拼包
- 归档与恢复：单项或批量归档非运行中会话，归档后从官方侧栏隐藏；DSH ≥0.1.6 宿主支持单项或批量恢复（取消归档），老版本 DSH 保持单向归档提示
- 内容搜索：对话全文语义搜索（大小写不敏感、空白灵活），跨会话命中列表（匹配文本高亮；多命中显示 seq 位置芯片、可一键直达）→ 命中窗口视图：打开即以命中 seq 为中心展示上下文窗口（命中前后各 15 条事件；命中行标「命中」徽章高亮、自动滚动定位并闪烁 2 秒），支持上一个 / 下一个命中翻跳与导航条 seq 芯片直达（参考 dsh-session-kb 的 Locate 交互）；窗口可继续加载后续事件；可限定仅搜归档区
- 删除：仅已归档会话可删除，且执行前再次拒绝运行中的会话；两段式确认先展示会话 id / 标题 / 工作区 / 文件体积，删除记录先原子落盘、再移除日志目录；已删除记录在「已删除」筛选下可见，支持单条清除或批量多选 / 全选清除（两段式确认，永久从记录中移除）；删除成功后即时同步官方侧（补发官方会话移除事件、清掉归档集合里的死 id），官方侧栏与「已归档会话」设置页无需刷新浏览器即反映最新状态
- 入口：「维护」页子标签「会话管理」（默认开），设置页左列入口可选（默认关）
- 删除记录存 $DSH_HOME/dsh-service-sessions-deleted.json（原子写入、0600，仅标题/时间，不含内容、不可恢复）

移动端适配

移动端适配

- 默认关闭；仅在视口 480px）加在模型名前面；手机上（≤480px，官方把名称收成图标的形态）替换掉官方那枚通用图标
- 没适配的渠道保持官方默认图标不变（宽屏不加、手机照旧显示官方图标），不会出现空缺或错图
- 覆盖 pi-ai 内置 40 个 provider 中的 38 个（ant-ling、radius 无对应品牌图形，走默认图标），并补充 ollama、vLLM、LM Studio、Perplexity、Cohere、火山引擎、豆包、混元、元宝、阶跃、商汤、百川、零一万物、Fal、Replicate、Midjourney 等常用渠道，共 62 张图形 / 76 条渠道映射；区域与计费变体（如 xiaomi-token-plan-、qwen-token-plan-）共用同一品牌图形
- 自定义渠道名按前缀/别名自动识别：opencode-goo → opencode、openrouter-f → openrouter、zai-coding-cn → 智谱、xiaomi-token-plan-cn → 小米、command-goat → Command Code 等；识别不到的（如 cpa 这类没有公开品牌图形的中转）自动回落官方默认图标
- CLIProxyAPI 图标按需出现：手绘的「内凹菱形 + 镜像漩涡」品牌标只在你在余额查询里把某个渠道手动适配成 CLIProxyAPI 后才显示在模型按钮上（渠道名不限，叫 cpa 还是自定义名都一样）；撤销适配立即回落官方默认图标
- 余额查询的渠道卡片同样带图标：已适配卡片的渠道名前显示同一套厂家小图标（14px；彩色档原样上品牌色、单色档跟随主题文字色）。CPA 的「手动适配才显示」门在这里同样生效——卡片区正是你做适配的地方，适配后立即出现
- 浅色 / 深色都清晰：品牌色对浅底与深底两侧对比度都达标才保留原色，否则自动改用跟随主题文字色的单色版——不会出现深色模式下「黑图标糊在黑底上」或浅色模式下近乎隐形
- 零运行期网络请求：图标在构建期内联进客户端产物，离线可用、不影响 CSP，也不向第三方暴露你的渠道名称
- 图标尺寸与输入框旁的额度圆环一致（生成期把每个图标的 viewBox 收紧到真实绘制范围并正方形化，所以各品牌「看起来一样大」，不会有的满格有的缩成一团）
- 开关在 插件 → 插件配置 → 交互（默认开，热生效）
- 图标来自 MIT 许可的 LobeHub Icons（版本钉死 @1.95.0）；小米图标取自 CC0 的 Simple Icons 纯 mi 标（LobeHub 那份是「Xiaomi / MIMO」两行文字组合标，15px 下糊成一团）。品牌图形版权归各厂商，正式对外使用前请查阅对应厂商的品牌条款
- 全部图标可在一页里查看：图标目录——62 张图形、76 条渠道映射、匹配规则与深浅色对照；离线单文件，与构建期内联进客户端的数据同源生成

右栏文件编辑

- 官方右侧栏的文件预览头部右上角多一个「编辑」按钮（紧邻渲染器名），点一下就进编辑模式：等宽编辑器，带脏标记、Ctrl/Cmd + S 保存、「重新加载」「撤销保存」，以及一键「预览」返回官方渲染器
- 另外两条等价入口：原来的渲染器下拉里选「编辑」，以及右键标签 → ⋯ 菜单 →「编辑」（后者走官方菜单座、不做任何 DOM 注入，是头部按钮失效时的兜底路径）；处于编辑档位时头部按钮自动收起，不会重复
- 不改变官方渲染器的默认地位：.md、.js 等官方有专属渲染器的后缀默认仍是官方预览（Markdown / 代码…）；只有官方没有专属渲染器、本来落到「纯文本」的后缀（如 .txt、.log、.conf）才默认进编辑器。官方预览未挂载（旧版 DSH）时整块静默不出现
- 写盘走会话自己的文件服务与沙箱策略：浏览器只送 dsh-resource://file/session// 资源地址，会话与工作区根由宿主解析，不接受自由路径；保存携带读取时的版本号，磁盘已被 Agent 或其他窗口改过就拒绝覆盖，由你选「重新加载（丢弃修改）」或「用我的内容覆盖」；只读沙箱会话只能预览
- 保存不中断输入：保存期间仍可继续编辑，响应只确认本次提交的内容，后续输入保留为「未保存」；状态区分「保存中 / 未保存 / 已保存」。冲突出现后仍可修改，覆盖保存使用编辑器里的最新草稿
- 离开前保护草稿：通过编辑器自己的「预览」「重新加载」按钮离开或重读时，若有未保存内容先显示内联确认，可取消继续编辑；「撤销保存」也先确认，且保留版本守卫，不静默覆盖磁盘上的新改动
- 单文件上限 2 MiB（超过只读）；会话未激活或沙箱策略服务不可用时不可编辑（仍可使用官方预览）
- 首版不做：语法高亮、多光标、查找替换（插件半没有打包器，借不到编辑器组件），关闭标签不弹未保存确认
- 开关在 插件 → 插件配置 → 交互（默认开，热生效）

外部探活

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

🏗️ 架构

插件是 Cordis 双半结构：Host 端（index.js） 承担一切能力与数据访问，Client 端（client.js） 只在浏览器渲染界面；两侧经 Typert JSON-RPC 通信，通道为单层绝对路径 /dsh-service，authority 一律 loopback。

flowchart TB
subgraph Client["🌐 Client 浏览器端 (client.js)"]
UI["设置页「服务控制」面板（六页导航 + 快捷入口）额度圆环 · 通知铃铛 · 移动端适配"]
end

subgraph Host["⚙️ Host 服务端 (index.js)"]
RPC["Loopback RPC · /dsh-serviceversion / check-update / restart / quota / skills / backup"]
SPAWN["受控 spawnchmod / chown / npm 升级"]
end

subgraph DSH["🚀 DSH 核心运行时（只读消费）"]
CORE["agents · jobs · terminals · sessionssessionQuery · skills · credentials"]
WEB["webServer 路由GET/HEAD /healthz"]
end

subgraph OS["💾 宿主机与外部"]
PM["进程管理器Docker / systemd / pm2"]
FS["$DSH_HOME配置 / 备份 / 凭据 / 技能索引"]
REG["npm registry"]
QUOTA["上游额度 API"]
end

UI -- "Typert JSON-RPC（loopback）" --> RPC
RPC --> CORE
RPC --> SPAWN
RPC --> REG
RPC --> QUOTA
RPC -- "process.exit(42)" --> PM
SPAWN --> FS
MON["外部监控Uptime Kuma / Docker / K8s"] -- "GET /healthz" --> WEB

关键契约：

- 仅 loopback：能力只经 /dsh-service loopback channel 暴露；webServer 路由只返回不含信息量的状态码
- 重启 = process.exit(42)：插件只发退出信号，由外层进程管理器拉起；没有管理器时重启无保障
- 零输入拼接：浏览器侧不接受 URL / 包名 / 命令 / 路径，命令全部走宿主侧白名单
- 凭据不出宿主：API key 只在宿主进程内解析，浏览器只收到归一化窗口数据

⚡ 安装

| 方式 | 命令 |
| --- | --- |
| npm（推荐） | dsh plugin --profile web add @gehennawu/dsh-service |
| GitHub | dsh plugin --profile web add github:gehennawu/dsh-service |
| 本地开发 | dsh plugin --profile web add link:/path/to/dsh-service |

安装或更新后重启 DSH Web：

dsh web

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

🔄 自动重启配置

插件只发送退出信号，不负责拉起进程；没有进程管理器时重启会直接停止 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

🖥️ 平台支持

| 环境 | 插件功能 | 重启后自动拉起 | 验证状态 |
| --- | --- | --- | --- |
| Linux + Docker Compose | 支持 | 配置 restart policy 后支持 | 已验证 |
| Linux + systemd / pm2 | 预期支持 | 由进程管理器负责 | 未单独验证 |
| macOS / Windows + pm2 等 | 代码未限制 | 由进程管理器负责 | 未验证 |
| 直接运行 dsh web | 支持 | 不支持 | 预期行为 |
运行要求：Node.js >=22，DSH Web 能加载 Host 与 Client 两半插件。更新检查需访问 registry.npmjs.org；网络失败不影响其他功能。

DSH 适配口径：已适配 DSH 0.1.6-alpha.2——会话格式 V3（system/message 入史、旧 PTC 词汇更名，详情视图自动归档系统事件）、sessionPersistence handle 化（用量增量、标题缓存、诊断计数全部按新公共面 list/open/read/close 走）、官方右栏替代详情列（移动端右缘手势直接驱动 ctx.layout.openRightbar/closeRightbar）、官方 turn-process 对象化（子代理回合认领双形态兼容）、移动端底行触发钮双哈希兼容、子代理回合尾模型行 list 槽位自适应兼容、新插件管理页 plugins.bundle.config 槽位注入、会话详情打开接入 uiWorkspace 降级链路。旧版 DSH（>=0.1.1-rc.2）保持兼容：新旧两套 persistence/布局 seam 按运行时能力探测双形态走，旧宿主上针对新结构的适配项天然不生效（纯展示，无功能损失）。注意：升级后以 V3 格式写入的会话日志无法被旧版 DSH 读取——备份不可跨版本降级恢复。版本卡常驻显示「适配 DSH 0.1.1-rc.2 ~ 0.1.6-alpha.2」，越界运行版本（≥0.1.6-alpha.3）标红警示。

🔒 安全设计

| 领域 | 边界 |
| --- | --- |
| 输入 | 浏览器不能传入 URL、包名、命令或文件路径。唯一例外：右栏文件编辑只接受 dsh-resource://file/session// 资源地址（逐段解码、拒绝其他形态），会话与工作区根一律宿主侧解析，写盘再经会话沙箱策略围栏 |
| 网络 | 更新检查只访问固定 npm registry 地址 |
| RPC | 仅接受 loopback 调用，数据不出本机 |
| 数据 | 用量索引不保存消息、Prompt、工具参数或凭据；API key 只在宿主进程内使用 |
| 操作 | 破坏性操作（重启、删除、修复权限）均需两段式确认 |
| 凭据 | 写入 DSH 凭据库（$DSH_HOME/.credentials.yaml），只发往固定端点 |

❓ 常见问题 FAQ

重启后没有自动起来？

插件只发送退出信号，重新拉起由进程管理器负责（见「自动重启配置」）。面板标注「疑似手动启动」时，直接运行 dsh web 的终端进程会被退出；请改用 Docker Compose / systemd / pm2 托管。

健康诊断里的黄色「重启无保障」警告是什么？

这是「疑似终端手动启动」的检测结果，说明当前没有检测到进程管理器。若实际由 NSSM/WinSW 或输出重定向等场景托管，可用 DSH_SERVICE_RUNTIME_ENV=managed 显式声明消除。

额度卡片显示「凭据未配置」？

点击卡片上的内联表单写入凭据：普通适配填 API key，CLIProxyAPI 填管理密钥（不是代理 key），小米 Token Plan 填控制台 Cookie。写入 DSH 凭据库后自动强制刷新；被进程环境变量遮蔽时宿主会拒绝写入，需改环境变量本身。

Command Code 卡片显示「凭据被上游拒绝」？

推理面和额度面共用同一把 key（user_ 前缀，Studio 的 API keys 页生成）。卡片显示该错误说明 key 被上游判为无效：到 commandcode.ai 的 Studio 重新生成或复制 key，点卡片「填写 API 密钥」粘贴即可。若渠道 baseURL 指向的是自建中转而非 api.commandcode.ai，额度面仍固定查官方账号面——中转 key 查不到官方额度。

小米卡片显示「凭据被上游拒绝」？

网页登录态过期了。重新登录 platform.xiaomimimo.com，从任意 /api/v1/tokenPlan/ 请求复制 Cookie: 头，点卡片「填写控制台 Cookie」重新粘贴。

StepFun Step Plan 卡片显示「凭据未配置」？

Step Plan 订阅没有 API-key 形态的查询接口，需要网页登录态令牌。登录 platform.stepfun.com，按 F12 打开开发者工具 → Application → Cookies → platform.stepfun.com，复制 Oasis-Token 的完整值（形如 xxx...yyy，两个小圆点分隔是令牌格式本身的一部分，不要拆分），点卡片「填写控制台令牌（Oasis-Token）」粘贴即可；Oasis-Webid 由宿主从令牌自动派生，无需手填。

StepFun Step Plan 卡片显示「凭据被上游拒绝」？

令牌过期了（官方常见报错 oasis-token is embezzled 即令牌与 web_id 不匹配）。重新登录 platform.stepfun.com 后从 Cookies 复制新的 Oasis-Token 完整值再粘贴；从控制台复制时若自带 Oasis-Token= 或 Cookie:  前缀会被自动剥离，不影响。

恢复备份会怎样？
先做完整性检查并展示恢复预检计划，再由用户最终确认。提交前宿主会复检备份 SHA-256、当前目标指纹与运行中工作；任何变化都会中止，不会部分覆盖或重启。提交成功后会话目录整体替换，允许的配置文件按快照精确替换，profile 只覆盖 package.json（node_modules、凭据、附件不动）。受 Docker/systemd/pm2 等托管时自动重启；疑似终端手动启动时显示手动重启指引。删除备份同样需要两段式确认。

技能开关为什么置灰不可点？

该技能来自内置（bundled）只读目录。只有 project- 与 user- 来源的技能支持双向开关。

保存技能开关提示「技能文件刚刚发生变化」？

并发保护生效：SKILL.md 刚被外部编辑器改动（版本比对失败）。点击「刷新」获取最新状态后重试即可。

更新检查失败会影响其他功能吗？

不会。更新检查只是访问 npm registry 的只读请求，失败静默忽略，其余功能不受影响。

🤝 参与贡献

欢迎提交 Issue 与 Pull Request。开发路线与技术约定见仓库内 AGENTS.md；发布规范见 AGENTS.md「发布」一节。

📄 许可证

MIT