NokorinNishikino/kidai-plugin-remote

🛟 Kidai Plugin Remote · 纪代插件远程管理器

DSH 坏了也能用的插件管理器 —— 查看 · 启停 · 启动 · 隔离运行 · 快照 · 回滚

简体中文 · English

✨ 为什么用？

DeepSeek Harness（DSH）的插件生态越来越丰富，但启动失败往往来自插件本身：
损坏的 bundle 列表、缺失的依赖、自引用 file:./node_modules/... 依赖……一旦 DSH
起不来，DSH 自己也救不了自己。Kidai Plugin Remote 就是为这种时刻准备的
外部救援与日常管理工具——它在 DSH 之外运行，DSH 挂掉也能用。

- 🛟 先救援 —— 启动失败给出「退出码 + 日志 + 崩溃转储 + 冲突分析 + 修复提示」；
一键回滚到最近良好快照，或隔离运行纯原生基线进行分析
- 📋 与纪代市场同源 —— 插件列表用与市场完全相同的方式组合
（bundle 层 → profile 补丁 → home 补丁 → 桌面壳层），所见即 DSH 所载
- 🧊 隔离仅一次有效 —— 本次运行禁用全部第三方插件；退出自动恢复原配置，
即使管理器被杀，内部守护也会在下次启动时恢复
- 💾 快照与回滚 —— 每次启动 / 配置变更保留一版待确认快照，下次成功运行转为
「已验证」；离线回滚配置 + 第三方插件目录
- 🧩 插件管理 —— 孤儿扫描 / 装载 / 残留清理 / 卸载 + 入口校验（对齐市场 Hub 1.3.4）
- 🎨 8 套主题 —— 暗色 / 浅色 / DS 蓝 / 灰绿 / 紫罗兰 / 青 / 珊瑚 / 玫瑰，服务器端记忆
- 🧲 四种启动方式 —— 正常 / 隔离 / 预检分析 / 失败报告；成功自动最小化

无需理解任何技术细节 —— 打开即用；开发者也能享受完整的组合诊断。

🚀 快速开始

方式 A — 零依赖桌面客户端（推荐分发）

使用配套仓库 kidai-plugin-remote-client
的 Kidai Plugin Remote Client.exe：下载解压、双击即用。不需要 Node、不需要浏览器。

方式 B — 经典启动

install.cmd                        # 一键安装：检查 Node、装入内部守护、创建桌面快捷方式
启动 Kidai Plugin Remote.cmd       # 直接启动（浏览器独立窗口）

源码直接跑：

node server.js                     # 打开管理器 http://127.0.0.1:4877
node scripts/self-check.mjs        # 只读自检（不启动 DSH、不改配置）

环境要求：本机 Node.js ≥ 20（不需要 DSH 本体）。

📖 使用指南

1. 启动管理器 —— 双击 启动 Kidai Plugin Remote.cmd（浏览器独立窗口），
或用 Client 版 exe（原生窗口）
2. 查看插件 —— 「已安装插件」页：原生/第三方徽标、启停状态、版本、路径、
安装时间；支持排序 / 筛选 / 宽窄视图
3. 启停插件 —— 行内开关切换：写入 $DSH_HOME/cordis.patch.yml（与市场
同一套写入），重启 DSH 生效；DSH 运行中 HMR 即时生效
4. 启动 DSH —— 右侧「▶ 启动 DSH Desktop」；建议先「🔍 启动前预检分析」
提前发现高危问题（未解析 bundle、补丁损坏、重复条目等）
5. 隔离运行 —— DSH 起不来时用「🧊 隔离运行」：本次启动禁用全部第三方插件，
跑纯原生基线分析；退出自动恢复原配置
6. 快照与回滚 —— 每次启动/变更前自动留快照；出问题到「快照与回滚」页，
选「已验证」快照一键回滚（配置 + 第三方插件目录），重启 DSH 即回到变更前
7. 故障报告 —— 启动失败自动弹出诊断报告：退出码、日志线索、冲突分析、
每条附修复建议；也可「复制报告」保存

🔗 生态

| 仓库 | 职责 | 运行位置 |
|---|---|---|
| kidai-plugin-remote（你在这里） | 查看 / 启停 / 启动 / 隔离 / 回滚 | DSH 之外（独立程序） |
| kidai-plugin-remote-client | 同一管理器，原生窗口，零依赖 | DSH 之外（独立程序） |
| kidai-snapshot-guard | 快照、待确认→已验证、隔离自动恢复 | DSH 内部（插件） |

三者共享同一个快照存储（$DSH_HOME/.kidai-snapshots）与守护目录
（$DSH_HOME/guard/）——在任意一端给快照加备注，另一端都能看到。

📸 技术细节

- 读取 — $DSH_HOME → profile manifest dsh.profile.bundles → 双锚点解析
（先 DSH 安装、后 profile）→ 按启动顺序应用补丁层（include 插件的精确算法，
!!js 只解析不评估）→ 真实 loader 条目树。
- 写入 — 启停只写 home 级 cordis.patch.yml（与市场完全一致）；隔离额外写
桌面私有 plugin-management/state.json，退出或下次启动时自动还原。
- 启动 — spawn DSH Desktop.exe（自动发现或 DSH_DESKTOP_DIR）；成功判定用
桌面端自己的 health-commit；失败证据来自退出码、%APPDATA%\DSH Desktop\logs、
crash-evidence、profile-selection、plugin-install-recovery。
- CLI 校验 — dsh --dump-config 走桌面自带的 CLI 引导
（resources\app.asar\lib\desktop-cli.js，用 ELECTRON_RUN_AS_NODE=1 以
DSH Desktop.exe --expose-internals 运行，零下载）；仅当该引导缺失时才回退到
系统 Node（≥ 22）跑 app.asar.unpacked 里的旧式 bin.js。
- Desktop 2.x 归档布局 — 安装识别只要求「可执行文件 + resources」，不再要求
app.asar.unpacked\package.json（2.x 不再提供）；桌面自身的 cordis.patch.yml、
以及归档内的核心 bundle（@deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app …）
都由内置的 asar 读取器解析，因此不会再把「装在 app.asar 里」误报成依赖缺失。
- 运行态判定 — tasklist 被沙箱/权限拒绝时，改用单实例 lockfile 的独占占用探测
（DSH Desktop 运行期间一直持有该文件；它的 mtime 只在启动时写一次，不能当新鲜度用）。
- 韧性 — 任何单个损坏的 bundle（manifest 损坏、目录缺失、补丁损坏）都会被
跳过并报告，绝不致命：管理器、客户端、界面都能继续工作。

kidai-plugin-remote/
├── server.js                # HTTP + API（127.0.0.1:4877）
├── lib/                     # dsh-env · patches · profile · inventory · conflicts · plugin-mgmt · snapshots · launcher
├── public/                  # 单页 UI（无构建步骤）+ 8 套主题
├── vendor/yaml/             # 内置 yaml 2.9.0（完全离线）
├── scripts/                 # self-check · test-* · install-guard · install-shortcut · build-exe
├── install.cmd              # 一键安装
├── 启动 Kidai Plugin Remote.cmd
└── build/                   # exe 构建产物

📄 License

MIT