服务生命周期管理 elmaxid/dsh-manage

dsh-manage

从命令行安装和管理 DeepSeek Harness (dsh)。控制 DSH Web 服务器的生命周期——安装、启动、停止、更新、查询状态——幂等且稳健。

适合在开发岗位上复制部署，并针对用户 node24 tree 中隔离的 DSH 安装进行操作。

命令

| 命令 | 作用 |
| install | 在 node24 tree 中全局安装 @deepseek-ai/dsh |
| plugins-install [profile] | 在 profile 中安装经认证的插件栈（开发/安全/运维）——默认 web；安装前运行保护门禁 |
| plugins-remove <包名> [profile] [--yes] | 移除包，强制保护门禁（检测到影响时自动备份，需明确确认） |
| service-install | 安装 systemd watchdog（dsh.service，Restart=always）——需要 root |
| session-backup {scan,create,list,verify,restore,prune,repair} | 会话备份：分类风险，创建/恢复可验证快照，按保留策略修剪，修复含孤立事件的会话 |
| start | 若 Web 服务器尚未监听则启动（幂等） |
| stop | 停止监听端口的进程 |
| update | 干净地 uninstall + install 最新版本，并保持运行 |
| status | 显示是否有进程监听端口、pidfile 是否过期，并提示是否有更新 |
| version | 显示已安装版本 |
| check-update | 对比已安装版本与 npm 上最新发布版本 |
| --version, -V | 管理脚本自身的版本（非 dsh 版本）——见 CHANGELOG |

dsh-manage start
dsh-manage status
dsh-manage version
dsh-manage check-update
dsh-manage update
dsh-manage stop

新岗位，从零到可编码

dsh-manage install # Node 引导（若缺失）+ @deepseek-ai/dsh dsh-manage plugins-install # 约 19 个经认证的插件栈（profile 'web'） dsh-manage service-install # systemd watchdog，让 dsh 始终在线

三步，每步幂等，仅在上一步失败时可重新执行——无需从头重试全部。

⚠️ 在 plugins-install 之后立即运行 service-install，不要拖延：安装时执行的 ExecStartPre 会修复 pnpm 的一个已知回归（@deepseek-ai/{dsh-tools,cosmokit,dsh-fs} 的 shadowing），该回归可能在安装插件栈后立即破坏 tool runtime plugins —— 已在真实副本上确认，见 CHANGELOG。还没装 service-install 时，如果这个 bug 出现，就得手动修（把那 3 个文件夹从 $DSH_HOME/profiles/<profile>/node_modules/@deepseek-ai/ 下
rm -rf 掉，再重启）。

在已经手动装过 dsh 的机器上安装

如果目标服务器已经在别的路径装好了 dsh/node（比如系统包在 /usr/bin，而不是 node24 那套隔离目录树），就在每条命令之前把 DSH_NODE 指向那个真实路径，让 dsh-manage 接管已有安装，而不是另起一套并行的：

export DSH_NODE=/usr/bin # o donde vivan los binarios node/dsh reales
dsh-manage plugins-install
dsh-manage service-install

plugins-install 在已经手动装过插件的 profile 上跑是安全的：合并时永远不会覆盖已有依赖，只补上 manifest 里缺的部分。service-install 则会直接覆盖已有的 /etc/systemd/system/dsh.service，不问你一声—— 如果你本来就有自己的那份（不是 dsh-manage 创建的），先手动备份（cp /etc/systemd/system/dsh.service /etc/systemd/system/dsh.service.bak）。

check-update 和 status

check-update 查 npm registry，告诉你有没有更新的版本：

instalada: 0.1.1-rc.2
ultima: 0.1.1-rc.3
hay actualizacion disponible (0.1.1-rc.2 -> 0.1.1-rc.3)
corre: dsh-manage update

- 没网，或者 npm 不响应 → 报告查不了（脚本不会挂）。
- status 里会带一句更新提示，已经是最新版或者没网时就不吭声。

plugins-install：经过认证的插件栈

往指定 profile（默认 web）里装那套约 19 个社区插件，每一个都在真实机器上逐个评估过 —— 启动干净、id 不冲突、没有没翻译的中文用户文案。完整列表和每个插件的评估细节在 docs/PLUGIN-HOMOLOGATION.md；命令实际读取的源头是 plugins/manifest.json。

dsh-manage plugins-install # profile 'web' (default)
dsh-manage plugins-install headless # otro profile

它按顺序做这些事：

1. 检查 dsh 是否已经装好（没装就停下，建议先跑 install）。
2. 如果 pnpm 没有，就用 corepack 准备好（node24 自带，但第一次用到之前不会激活）。
3. 合并，绝不覆盖：如果 profile 里已经有 package.json / pnpm-workspace.yaml，而且插件是手动装的，就原样保留 —— manifest 只补缺的部分。跑两次也没事（已验证：重装已存在的插件不会重复）。
4. 复制 manifest 里的 .patch（pnpm patch 已经应用过，带版本管理），不覆盖你自己用同名文件改过的那份。
5. pnpm install --allow-scripts + pnpm approve-builds，只针对那些真正需要它的原生插件（cpu-features、ssh2、node-pty —— 来自 dsh-ssh 和 dsh-better-sidebar）。better-sqlite3 用官方预构建，永远不会批准编译。
6. 重启 dsh（如果 dsh.service 存在就通过 systemctl，否则通过 stop+start），并验证真实启动：端口在监听 + 在日志里 grep duplicate/failed to load/EADDRINUSE —— 不只是命令以代码 0 退出。

包含三个翻译补丁（见 plugins/patches/）：两个插件带有固定的中文用户消息，没有英文替代（dsh-restart-recover、dsh-secret-guard）—— 在进入 manifest 之前翻译成了英文，与 dsh-plugin-verify 的 bugfix 用同一个 pnpm patch 机制。

有意排除在 stack 之外：dsh-doublecheck（与这个 DSH 构建不兼容 —— 精确的 peer-version 无法解析，永远无法激活）和 dsh-chat-recovery（已评估但未达到可验证的完整安装）。项目 MCP（engram、code-review-graph 等）也不进入：它因岗位而异，通过单独编辑 profile 的 cordis.patch.yml 来添加。

service-install：systemd 看门狗

写入并激活 dsh.service（Restart=always，进程死亡后 3 秒自动重启）外加一个防御性的 ExecStartPre，在每次启动时修复已知的 pnpm 回归，且永不导致启动失败。需要 root。

sudo dsh-manage service-install

一旦激活，使用 systemctl {status,stop,restart} dsh.service 而不是 dsh-manage {start,stop} —— 两个机制管理同一个端口，不要混用。

session-backup：会话备份

一些插件（dsh-swarm-panel 和其他 event-writers）在加载时在 harness 中注册自己的事件类型。如果卸载它们，使用过这些事件的会话将无法加载（SessionFormatUnsupportedError）。这个项目真实发生过。

dsh-manage session-backup scan # ¿qué sesiones están en riesgo?
dsh-manage session-backup create --only-at-risk --label pre-cambios
dsh-manage session-backup list
dsh-manage session-backup verify --from latest
dsh-manage session-backup restore --from latest --session <id> # requiere DSH detenido
dsh-manage session-backup prune --keep 10 --yes # nunca borra la unica copia de una sesion broken
dsh-manage session-backup repair --session <id> --mark-ignorable --yes # requiere DSH detenido

| 类别 | 含义 |
| ok | 只有 first-party 类型。不受安装/卸载插件影响。 |
| at-risk | 有来自已安装插件的类型。今天能加载；卸载它就会坏。 |
| broken | 有已安装插件都不声明的类型。已无法加载。 |

scan、create、list 和 verify 从不写入 sessions/ 下。快照存放在 $DSH_HOME/session-backups/（sessions/ 的兄弟目录），带有 MANIFEST.json、CHECKSUMS.sha256 和 vocabulary.json —— 用 sha256sum -c 就能校验，不需要这个脚本。

restore 和 repair 是仅有的两个会写入 sessions/ 的操作。 两者都要求 DSH 已停止（校验两次：开始时一次，发布前一次），都会先做隐式备份，并且以原子方式写入（临时文件 + mv -T）。

- restore --from <snapshot> [--session <id>] [--force] [--to-new-id]
恢复某个快照中的一个或全部产物。要覆盖已存在且内容不同的目标，必须加 --force。--to-new-id 会恢复为新会话，并重写 header 里的 id。
- prune --keep N | --older-than DIAS --yes 删除旧快照，保护粒度是单个会话：绝不删除某个 broken 会话的唯一副本，即使另一个待删快照也包含该会话。
- repair --session <id> --mark-ignorable --yes [--types t1,t2] 把孤儿事件标记为 ignorable:true，就地修改，绝不碰 header。必须始终带 --session（从不批量操作）。如果源产物的尾部已损坏（写入被中断），它会中止且不发布任何内容 —— 修复会重写整个文件，只发布可恢复的片段，等于永久丢掉尾部且毫无提示。

⚠️ repair 是无需重装插件就能恢复的途径。 repair 直接写进 JSONL 的 ignorable:true 标志（就地修改，不经过 Session.append()），harness 打开会话时的读取路径确实会尊重它 —— 已对照已安装的 harness 0.1.1-rc.2 中真实的 KNOWN_SESSION_EVENT_TYPES 和 decodeStorageRecord 验证过，不会因未展开的 chunk 行产生误报。harness 0.1.1-rc.2 唯一会丢弃的，是实时传给 Session.append() 的 ignorable 标志（插件仍在运行时）—— 这不影响 repair，因为它从不调用 append()。

ℹ️ 不动日志的替代方案： patches/harness-known-session-event-types.sh 把插件的类型（目前是 swarm/progress）声明到已安装 harness 的 KNOWN_SESSION_EVENT_TYPES 里：所有受影响的会话都能重新加载，未来的会话也不会再损坏。幂等，带备份和校验。每次升级 harness 都会丢失 —— 每次升级后都要重新执行（并重启 dsh 使其生效）。

⚠️ 如果你用 cp 手动恢复日志（不走 restore），先停掉 DSH（systemctl stop dsh.service）。运行中的进程持有以 append 模式打开的文件描述符：在底层替换文件会让恢复静默失效。

plugins-remove：移除插件而不盲目弄坏会话

dsh-manage plugins-remove <paquete> [profile] [--yes]

在运行 pnpm remove 之前，它会跑与 plugins-install 相同的保护门禁（只读）：如果要移除的包会写入事件会话正在使用某个已有会话时，自动创建备份（session-backup create --only-at-risk，触发条件 plugins-remove），并要求显式确认——如果没有传 --yes 且没有 TTY，就直接中止，什么都不动。没有检测到影响，就直接移除。

只有当被改动的 profile 是 web 时才重启 dsh.service（这是真实服务唯一提供的 profile）——从测试 profile 里移除永远不会重启生产环境。正是缺少这项功能，才导致了最初那起催生整个 session-backup 的事故：一个插件被卸载时没有任何提示，弄坏了真实会话。

要求

- Linux，带 ss（iproute2）和 npm。
- 以拥有 DSH 进程的用户身份运行（通常是 root）：PID 检测用 ss -ltnp，它只会暴露你有权限访问的 socket 的 pid。
- 完整流程（plugins-install）：需要 git、node，以及 带 pyyaml 的 python3（或者让 install 帮你 bootstrap——node 由 dsh-manage install 通过 corepack 带上；python3/pyyaml 由辅助脚本 plugins/merge-pnpm-workspace.py 使用）。如果你想要 systemd watchdog，还需要 systemctl（systemd）和 root 权限。

安装

一行命令（推荐用于开发机）

把整个仓库克隆到 ~/.dsh-manage，并把 /usr/local/bin/dsh-manage 留作指向克隆内脚本的 symlink。必须用完整仓库：plugins-install/service-install 命令会按相对脚本的路径解析 plugins/manifest.json 和补丁——单独一个 dsh-manage.sh（旁边没有 plugins/ 文件夹）装不了它们。

curl -fsSL https://raw.githubusercontent.com/elmaxid/dsh-manage/main/install.sh | bash

安装器会先显示计划，安装前要求确认。幂等：如果克隆已存在，就用 git pull 更新，而不是重新克隆。选项：

| Flag | 作用 |
| -y, --yes | 不要求确认 |
| -v, --verbose | 详细显示每一步 |
| --prefix <dir> | 可执行 symlink 的目录（默认 /usr/local/bin） |
| --clone-dir <dir> | 克隆仓库的目录（默认 ~/.dsh-manage） |
| --ref <git-ref> | 要拉取的版本/branch/tag（默认 main） |
| --no-color | 关闭颜色 |

silencioso para automatizar
curl -fsSL https://raw.githubusercontent.com/elmaxid/dsh-manage/main/install.sh | bash -s -- -y

inspeccionar antes de ejecutar (más seguro)
curl -fsSL https://raw.githubusercontent.com/elmaxid/dsh-manage/main/install.sh -o install.sh
less install.sh
bash install.sh

安装器不安装 DSH 本身，只装管理器。之后你运行 dsh-manage install 来安装 @deepseek-ai/dsh。

手动

你需要完整仓库（不只是脚本），plugins-install / service-install 才能找到 plugins/。克隆并建立软链接：

git clone https://github.com/elmaxid/dsh-manage.git ~/.dsh-manage
sudo ln -sf ~/.dsh-manage/dsh-manage.sh /usr/local/bin/dsh-manage

也可以直接从克隆目录运行：./dsh-manage.sh <comando>。

配置

所有配置都有合理的默认值，可用环境变量覆盖：

| 变量 | 默认值 | 说明 |
| DSH_NODE | $HOME/.local/dsh-node/node24/bin | node/npm/dsh 二进制文件所在目录 |
| DSH_MANAGE_HOME | $HOME/dsh-test | 本脚本的工作目录、日志和 pidfile 目录 |
| DSH_HOME | $HOME/.dsh | dsh 二进制的真实配置（profiles、cordis.patch.yml）—— 不要和 DSH_MANAGE_HOME 混淆 |
| DSH_BACKUP_ROOT | $DSH_HOME/session-backups | 会话快照的根目录 |
| DSH_PORT | 3080 | DSH 监听的端口 |
| DSH_START_TIMEOUT | 180 | 等待端口就绪的秒数 |
| DSH_ALLOW_SCRIPTS | dsh 原生 addons 列表 | npm 允许运行脚本的包 |
| DSH_PKG | @deepseek-ai/dsh | 要安装的 npm 包名 |
| DSH_NPM_CACHE | $DSH_MANAGE_HOME/.npm-cache | 查询版本用的 npm 缓存 |
| DSH_NODE_VERSION | v24.19.0 | 缺失时下载的 Node 版本 |
| DSH_MANIFEST | 脚本同目录下的 plugins/manifest.json | 要安装的插件栈 manifest |
| DSH_PNPM_VERSION | 11.22.0 | 通过 corepack 准备的 pnpm 版本 |
| DSH_SERVICE_USER | 当前用户 | 运行 systemd unit 的用户 |

⚠️ DSH_HOME vs DSH_MANAGE_HOME：这两个变量故意分开。
DSH_HOME 和 dsh 二进制内部用来定位 profiles/ 的是同一个； plugins-install 和 service-install 需要它和真实 dsh 的一致，否则插件会装到真实进程永远读不到的地方（这里踩过的真实 bug——见 CHANGELOG）。
如果你从 DSH 智能体会话里运行 dsh-manage，harness 已经在环境中为你导出了 DSH_HOME=~/.dsh——保持原样，这就是正确的值。
DSH_MANAGE_HOME 是另一回事：只是本脚本的工作/日志/pid 目录，和 dsh 的真实配置无关。

用另一个工作目录和端口的示例：

DSH_MANAGE_HOME=/srv/dsh-manage DSH_PORT=3100 dsh-manage start

工作原理

- 端口才是权威，不是 pidfile。port_pid() 用 ss 读取谁在 DSH_PORT 上监听。光靠 pidfile 并不能证明 DSH 正在运行：重启或崩溃之后，PID 可能被另一个进程复用。pidfile 只是额外的清理手段。
- 隔离安装：npm install -g --prefix 限定在 node24 的 tree 内，按命令覆盖用户在 ~/.npmrc 里固定的 prefix（它指向系统自带的 Node，对 dsh 来说太旧，而且和另一个服务共用）。这样就不会动到共享配置。
- Node 引导：如果 $DSH_NODE/node 不存在（新机器，还没装 Node），install 会按设备架构（x86_64/aarch64）从 nodejs.org 下载官方 tarball，解压到 $DSH_PREFIX，然后再安装 dsh —— 不需要 nvm/fnm，也不需要预装 Node。幂等：如果已经有可执行的 node，就什么都不做。
- 原生 addon：koffi、node-pty 等自带 addon，npm 的脚本守卫会拦截，除非用 --allow-scripts 显式放行。
- 干净升级：update 显式执行 uninstall + install，而不是原地升级，因为 dsh 是快速迭代的 RC（预期会有 breaking change），原地升级可能留下孤儿文件。

开发

make check # bash -n + shellcheck (si está instalado)
make test # batería de tests con bats-core

CI 在每次 push 时运行 bash -n、shellcheck 和 bats 测试套件。

版本

dsh-manage --version 显示脚本自身的版本（与 dsh 本身的版本不同，见 dsh-manage version）。变更历史见 CHANGELOG.md。

许可证

MIT