geekyfoxlab/dshm

dshm —— DeepSeek Harness 的版本与插件管理器

npm version
License: MIT
Node: >=20

一个坏插件就能让 DeepSeek Harness 完全无法启动。dshm 让 DSH 本体永远起得来。

DSH（DeepSeek Harness）迭代很快，第三方插件常常跟不上。
而 DSH 的启动是 fail-loud 的：只要装载树里有任何一个条目未处于 ACTIVE
（包括 PENDING），整个进程就会退出。于是日常会变成：你装了个插件，第二天 DSH 就再也打不开了。

dshm 解决这件事，外加版本管理的三个痛点：

1. 插件加载失败不会拖垮本体 —— 启动前预检 + 可回滚的隔离注入（quarantine）
2. 多个 DSH 版本互不干扰 —— 一个版本一个运行域，结构性防污染
3. 启动不用你操心端口 —— 自动选空闲端口，多开不撞车
4. 起了的进程管得住 —— list / status / stop，不用再 ps + kill

为什么用它而不是自己折腾：DSH 的 --patch 通道、运行域配对、插件级联隔离
这些细节极易踩坑（一个坏插件会级联拖垮健康插件）。dshm 把这些坑一次性填平，
并做到零第三方运行时依赖、零侵入官方包。

配套阅读：ARCHITECTURE.md（架构图与设计思路）、COMPATIBILITY.md（兼容性与升级指引）。

安装

要求：Node.js ≥ 20（无需任何第三方运行时依赖）。

npm install -g dshm

装好后直接用 dshm 命令（也可从源码运行 dshm）：

dshm --version    # → 0.1.0
dshm --help

推荐的最小流程：

1. 看有哪些版本可用
dshm versions

2. 装一个版本（会创建配对的运行域）
dshm install 0.1.2-rc.1

3. 建一个档位（引用未安装的版本会被拒绝）
dshm slot create latest -v 0.1.2-rc.1

4. 先预检：只看报告，默认不改动任何文件
dshm preflight --profile web --dsh-version 0.1.2-rc.1

5. 按档位启动（端口自动选择，不需要写 --port）
dshm start latest

它解决了什么问题

| 痛点 | dshm 的做法 |
|---|---|
| 坏插件让 DSH 起不来 | preflight 预检 + quarantine/nuclear 隔离，先让本体起得来 |
| 多个版本互相污染 | 运行域路径只由版本号推导，结构性防污染 |
| 装多个版本要手管端口 | start 自动从 3080 起选空闲端口，多开不撞车 |
| 起了进程管不住 | --detach + list/status/stop，进程登记可回收 |
| 装失败留垃圾、装得慢没反馈 | 原子安装 + 失败自愈 + 进度提示 |

反馈与问题

- 报 bug / 提需求：GitHub Issues
- 社群：见仓库首页公告（用于问题反馈与讨论）

⚠️ 先读这一条：隔离能救什么、不能救什么

最容易被误解的一句承诺：

quarantine / nuclear 能救的是「激活级」故障，不能救「装配级」故障。
也就是说 —— 「跑了 quarantine 就一定能起来」是错的。

DSH 启动分两个阶段，隔离只在第二阶段有效：

| 阶段 | 何时 | 隔离能否修复 | 例子 |
|---|---|---|---|
| 装配级 | 读 profile 清单与各 bundle 补丁文件时 | ❌ 不能 | bundle 缺 dsh.bundle、补丁文件不存在、包不可解析 |
| 激活级 | 施加补丁层、装载插件树时 | ✅ 能 | 插件抛错、依赖缺失、服务未就绪 |

原因：官方在 loadProfile() 里读每一个 bundle 的补丁文件，
这一步发生在任何补丁被应用之前 —— dshm 产出的 disabled 行根本没机会执行。

实测（真实 DSH + 真实坏插件）：

装配级故障 + 注入 disabled:true  → 报错完全不变，退出码仍为 1  ❌
激活级故障 + 注入 disabled:true  → 退出码 0，该行真实被禁        ✅

遇到装配级故障时，dshm 如实上报「隔离无法修复」，并给出
dsh plugin --profile  remove  指引 —— 不假装能修。

命令一览

| 命令 | 作用 |
|---|---|
| versions（别名 ls） | 列出本地已安装与远程可用的 DSH 版本 |
| install  | 安装一个 DSH 版本到独立目录，并创建配对运行域 |
| remove  | 卸载版本（被档位引用时拒绝，--force 强制） |
| use  | 设置默认档位 |
| slots / slot create\|set\|remove | 运行档位的增删改查 |
| start [档位] | 按档位启动 DSH（端口自动选择；--detach 后台运行；其后参数原样透传给 DSH） |
| list | 列出当前由 dshm 启动、仍在运行的 DSH 进程（档位/版本/PID/运行域） |
| status  | 查询某档位进程的运行状态（已退出/未登记如实报告，退出码 3） |
| stop  | 停止某档位对应的运行中进程（SIGTERM → 宽限 → SIGKILL 回收） |
| preflight | 启动前插件预检（只报告，默认不改动任何文件；--execute 运行期验证） |
| quarantine | 按忽略模式生成隔离产物 |
| doctor | 环境体检：安装完整性、配对一致性、插件健康度 |

参数透传

只有 dshm start 有透传区。 档位名之后的参数会被原样交给 DSH，
管理器不解析、不改写：

dshm start latest --patch ./x.yml --resume abc
dshm start latest -- -h     # 把 -h 交给 DSH，而不是 dshm

端口：不写也会自动选，写了就优先

--port 不是必要参数。 启动服务型入口时，管理器会自动从默认端口
3080 起选择一个空闲端口并注入，因此你日常那个占着 3080 的 DSH
不影响第二个档位启动：

dshm start latest              # 端口自动选（3080 被占则 3081、3082…顺延）
dshm start latest --dry-run    # 预演：打印最终选定的端口
dshm start latest -- --port 3092   # 显式指定端口

| 情况 | 行为 |
|---|---|
| 不写端口 | 自动从 3080 起找第一个空闲端口并注入；无需知晓 3080 是否被占用 |
| 显式写端口 | 优先使用你给的端口，不会被替换成别的端口 |
| 显式端口不可用 | 明确报错（退出码 4），并提示换端口 —— 不会静默改端口 |
| 非服务型启动 | 不注入端口参数（例如 --version / --help 这类纯查询，不会被变成常驻服务） |

⚠️ 为什么显式端口不可用时宁可报错、也不偷偷换一个：
若静默换端口，你会按原来的端口去访问却连不上，且失败原因难以归因。
显式端口是你明确表达的意图，管理器不会替你改掉它。

--port 必须写在档位名之后（透传区），因为它属于 DSH 原生参数。
写在档位名之前会被当成管理器自身选项而报用法错误。

进程生命周期：--detach / list / status / stop

start 缺省前台阻塞运行；加 --detach 则脱离当前终端、后台运行并立即返回。
无论前台还是后台，启动的进程都会被登记到 state/running.json，无需借助 ps/kill
即可定位与回收：

dshm start latest --detach    # 后台启动，返回 PID 并登记
dshm list                     # 列出仍在运行的进程（档位/版本/PID/运行域）
dshm status latest            # 查某档位进程详情（运行中给详情，已退出如实报告）
dshm stop latest              # 停止：SIGTERM → 宽限 2s → SIGKILL 兜底回收

要点：

- 只列仍存活的进程：list/status 会实时校验 PID 存活（kill(pid, 0)），
已退出的登记会被自然过滤，绝不把僵尸记录误报为运行中。
- 停止是「礼貌 + 兜底」：stop 先发 SIGTERM 等待优雅退出，宽限期后仍未退出
再 SIGKILL 强制回收，成功后从登记中清除。
- 如实报告不存在：status/stop 对已退出或从未登记的档位如实报告，并以退出码 3
表示「目标不存在」，绝不误报成功。

⚠️ list 语义变更：dshm list 现在不是 versions 的别名，而是独立的
「列举运行中的进程」命令。要列出版本，请用 dshm versions 或其保留别名
dshm ls（ls 与 versions 完全等价）。旧脚本里若用 dshm list 列版本，
请改为 dshm ls 或 dshm versions。

退出码

| 码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 一般错误 |
| 2 | 用法错误 |
| 3 | 目标不存在 |
| 4 | 状态冲突 |
| 5 | 体检发现问题 |
| 6 | 运行域污染 |

忽略模式

| 模式 | 行为 |
|---|---|
| strict | 不隔离。有任何插件问题就拒绝启动 —— 适合开发插件时排查问题 |
| quarantine（默认） | 只隔离坏掉的插件，保留其余 |
| nuclear | 隔离一切非本体条目，最大化「起得来」的概率 |

忽略模式的下限，是「保证 DSH 本体可启动」。
第三方插件是否可用不在保证范围内 —— 这是刻意的取舍：
先让 harness 能起来，再谈插件好不好用。

dshm start latest --ignore-mode nuclear

级联：为什么隔离一个不够

隔离提供 service 的插件 A，会让健康的下游插件 B 永远处于 PENDING ——
而 DSH 把 PENDING 也算作失败，于是本体照样起不来。

所以 dshm 的终止条件不是「隔离了几个插件」，而是
「本体真的能启动了」：

隔离 A 一个     → B 永远 PENDING → 本体仍失败（exit=1）
隔离 A + B      → 本体启动成功（exit=0）✅

多版本：一个运行域一个版本

铁律：一个 DSH_HOME ↔ 恰好一个 DSH 版本。

DSH 官方有一个回退农场 $DSH_HOME/profiles/node_modules/。
若两个版本共用一个运行域，后启动的版本会静默把自己的包写进去 ——
另一个版本下次启动就会加载到错误版本的 core。

dshm 从结构上消除这个问题：运行域路径只由版本号推导，
调用方无法传入任意路径：

~/.dsh-manager/
├── versions/0.1.2-rc.1/     ← 安装
├── versions/0.1.5-rc.2/
└── homes/0.1.2-rc.1/        ← 运行域，与版本一一配对
└── profiles/web/

⚠️ 注意 dshm 的运行域（~/.dsh-manager/homes//）与 DSH 自身的
用户目录（~/.dsh/）不是同一个位置。用 --home 或
DSH_MANAGER_HOME 可指定管理器根目录。

用 doctor 可随时校验配对关系：

dshm doctor

环境体检

dshm doctor

三项检查：

1. 安装完整性 —— 版本目录、清单、入口是否齐全
2. 配对一致性 —— 运行域是否指向其配对版本（跨版本污染检测）
3. 插件健康度 —— 逐个插件的可解析性与严重度分级

doctor 同时支持回退条目的两种形态：符号链接形态与
代理目录形态（官方打包发行时写入的形态）。

设计约束：零侵入

dshm 不修改任何官方包，不写用户的 profile 文件，只通过官方
--patch 通道注入：

bundle 自带补丁 → profile.patches → home 层补丁 → --patch 覆盖层（最高优先级）

为什么选 --patch 作为主通道：两条通道对「文件缺失」的语义不对称 ——

| 通道 | 文件缺失时 |
|---|---|
| home 层 $DSH_HOME/cordis.patch.yml | 静默忽略 |
| --patch  | 抛错 |

用 --patch 意味着不传参数就天然等于「无隔离」，
不需要造空文件，也不会留下半写坏状态。

隔离产物缺省使用静态 disabled: true，一旦写入就必然生效 ——
即使用户不经 dshm、自己手工启动 DSH 也同样有效。
!!js 运行时守卫是可选项，因为它依赖环境变量：变量没设就会静默失效。

当前状态

- 全仓测试：npm test 全绿（当前 450 条，随变更增长，以实际输出为准）
- 零第三方运行时依赖：仅用 Node 内置模块
- 能力契约：6 个 spec（版本、档位、启动、预检、隔离、体检）均有独立回归覆盖

已知边界与升级指引见 COMPATIBILITY.md。