dsh-plugin-manager-123twtd

@dsh/plugin-manager

独立于旧 component-hub 的 DSH 插件管理器 —— 以 Profile 事务和 Loader 真实验证为核心的插件控制面。

这是什么

DeepSeek Harness（DSH）是一个以 Profile 为中心、通过 Cordis patch 合成配置树的 Agent 运行时。 插件以 npm 包形式安装，通过 dsh.profile.bundles 声明，由 cordis.patch.yml 控制启用/禁用。

本插件为 DSH 提供插件生命周期控制面：

• 清单：读取 Profile bundles，区分官方 / 社区 / 未知来源，区分 installed / enabled 状态
• 冲突引擎（7 类）：显式声明、重复 Service Provider、路由、命令、端口、重复插件 ID、缺失依赖、Node 版本不兼容
• 事务：toggle / install / uninstall 全程快照 → 校验 → 失败回滚，不靠正则匹配 YAML
• 分层验证：syntax（node --check）→ config（dump-config）→ loader（真实 dsh 启动），三层逐级加深
• 任务持久化：job 状态落盘 jobs.json，进程重启后前端轮询不再 404
• 发现市场：离线快照 + 手动录入 + 一键安装事务

它独立于旧 component-hub，不导入旧项目代码，也不把组件市场 UI 当作管理器。

目录结构

dsh-plugin-manager/
├── manager.js              # 核心管理器：清单、冲突、事务、分层验证、HTTP API
├── client/
│   └── client.js           # 设置页 UI：tab 布局、冲突确认、异步进度、响应式
├── cordis.patch.yml        # 本插件的 patch 声明
├── test.mjs                # 30 个测试（单元 + 分层验证 + E2E + 更新）
├── tests/render/           # 渲染数据测试与夹具
├── docs/
│   └── PLUGIN-MANAGER-PRD.md   # 产品需求文档（7 态模型、冲突引擎、事务流程）
├── .github/                # Issue/PR 模板 + CI workflow
├── CONTRIBUTING.md         # 贡献指南
├── CODE_OF_CONDUCT.md      # 行为准则
├── CHANGELOG.md            # 变更日志
├── LICENSE                 # MIT
└── package.json

快速开始

前置要求

• Node.js >= 22
• DSH（DeepSeek Harness）运行时
• pnpm（通过 corepack 或独立安装）

安装

本插件通过 DSH Profile 的 bundles 机制加载，不需要单独全局安装：

# 在 DSH 项目根目录
pnpm add github:123twtd/dsh-plugin-manager
# 然后在 package.json 的 dsh.profile.bundles 加入 @dsh/plugin-manager

运行测试

git clone https://github.com/123twtd/dsh-plugin-manager.git
cd dsh-plugin-manager
pnpm install   # 安装 yaml 依赖
node --test test.mjs

DSH 插件生态

DeepSeek Harness 的核心理念是 Everything is a Plugin：模型、工具、沙箱、会话存储、UI，甚至 agent loop 本身都是插件。 社区插件通过 dsh plugin --profile <p> add <spec> 安装，spec 支持 npm 包名、github:owner/repo、tarball 等。

DSH 插件按来源分四类：

按架构角色分类：Core Service、Provider、Runtime Plugin、Client Plugin、Full-stack Plugin、Bundle、Workflow、Theme/UI、Skill Pack。

社区插件示例

以下是 DSH 生态中具有代表性的社区插件（星标与许可证来源于上游仓库，仅供参考）：

更完整的社区插件目录参见 （13k+ stars，收录 659+ 插件）。

插件状态模型

discovered → installed → enabled → active → verified
                ↓           ↓        ↓
             failed    quarantined

• discovered：已发现（在市场或 node_modules 中）
• installed：依赖已安装到 node_modules
• enabled：已加入 Profile bundles 且未被 patch 禁用
• active：Loader 已成功激活（本版本以 verifyProfile 的 loader 层为证据基础）
• verified：通过分层验证（syntax → config → loader）
• failed：安装、配置或启动失败
• quarantined：存在风险或冲突，被隔离

安装不等于启用，启用不等于运行，运行不等于验证通过。

核心 API

HTTP 接口

事务流程

所有变更操作执行标准事务：

读取状态 → 生成计划 → 展示影响 → 创建快照 → 修改 Profile
→ dump-config 校验 → 分层验证 → 成功提交 / 失败回滚

没有完整事务结果不得显示"成功"。

冲突引擎（7 类）

低风险显式冲突可作为自动禁用候选；官方核心和核心 Service 不会自动关闭。

检查更新与更新事务

已装插件支持一键联网检查新版本，有更新时可一键执行更新事务。

检查更新（check-update）

• npm 包：查询 registry.npmjs.org/<pkg>/latest 的 dist-tags
• github 包：查询 GitHub API 的 latest release；无 release 则取最新 tag
• 离线/网络异常：返回 hasUpdate: false + error，不抛错，前端展示降级提示
• 无版本号：返回 error 说明无法比较

返回结构：{ packageName, hasUpdate, current, latest, source, error? }

更新事务（update）

复用 install 的事务结构：

快照 → pnpm update <package> → dump-config 校验 → 分层验证 → 失败回滚

• 不覆盖用户配置：bundles / patch / pins / market 状态全部保留，update 只换代码
• 官方核心受保护：@deepseek-ai/* 不能通过本接口更新，用 dsh 自身的升级流程
• 返回版本变化：{ version: { before, after } }，让用户看到实际从哪个版本升到哪个版本
• 异步 job：和 install/uninstall 一样走 startUpdate，前端轮询进度

重启选项

install / update / uninstall 成功后，变更需重启 Harness 才完全生效。插件管理器不能直接杀掉宿主进程，设计为：

• 重启横幅：任务成功后顶部出现持久横幅（非 3 秒 toast），带三个选项：
  • 现在重启：调用 POST /dsh-plugin-manager/restart，尝试 dsh --restart
  • 以后自动重启：记忆偏好到 localStorage，下次任务成功后自动调重启接口
  • 稍后手动：关闭横幅，用户自行重启
• 自动重启不可用时降级：dsh 版本不支持 --restart 时返回 available: false，前端提示用户手动重启
• 更新管理器自身：横幅变橙色醒目提示"重启期间本设置页会短暂中断"

相关项目

DSH 生态中已有若干围绕"配置 / 快照 / 回滚 / 插件管理"的社区插件，本节诚实说明差异，便于使用者选择。

选择建议：

• 想要轻量快照/回滚：用 DSH Plugin Guard
• 想要崩溃恢复/undo-redo：用 DSH Undo Savepoint
• 想要配置迁移/同步：用 DSH Config Manager
• 想要完整的插件生命周期控制面（冲突分析 + 事务 + 市场 + 验证）：用本插件

开发指南

技术分层

plugin-manager-core    状态模型、Manifest、依赖图、冲突、事务、策略
plugin-manager-dsh     DSH Bundle、Profile、Loader、dsh plugin 集成
plugin-manager-ui      列表、详情、计划、冲突、进度、结果

如何开发 DSH 插件

1. 创建 npm 包，package.json 中声明 dsh.bundle.patch 指向你的 cordis.patch.yml
2. 在 dsh-market.json 中声明 services / resources / conflicts / dependencies
3. 用 pnpm pack 或发布到 GitHub 后，通过 spec 归一化机制安装

// package.json
{
  "name": "my-dsh-plugin",
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" }
  }
}

// dsh-market.json
{
  "services": { "provides": ["my-feature"] },
  "resources": { "commands": ["my-cmd"] },
  "conflicts": ["other-plugin"],
  "dependencies": ["@dsh/some-core"]
}

测试

30 个测试覆盖：

• 17 个原有测试：清单读取、状态判断、冲突检测、事务回滚、monorepo 降级、市场归一化
• 5 个功能测试：重复插件 ID、缺失依赖、版本不兼容、job 持久化恢复、smoke check
• 3 个验证测试：verifyProfile 语法层捕获错误、verifyProfile 合法插件通过、E2E 真实 pnpm install/uninstall
• 5 个更新测试：checkUpdate 缺失包/无版本号/npm registry 查询、updatePlugin 拒绝核心组件/拒绝缺失包

node --test test.mjs

开发阶段

贡献

欢迎提交 Issue 和 Pull Request。请先阅读 CONTRIBUTING.md。

行为准则

本项目遵循 Contributor Covenant 行为准则。

变更日志

详见 CHANGELOG.md。

许可证

MIT © 2026 123twtd