jonah791/dsh-agent-plugin-manager ↗★ 1
dsh-agent-plugin-manager
插件管理器:插件档案库(清单/用途/工具/配置认知,含 14 工具)+ 生命周期管理(创建/挂载/启停/卸载/配置/彻底退役)+ 档案漂移审计(plugin_audit:自述 vs 档案事实)+ 规范自检(plugin_spec_check:九项机械判据)+ 上游更新检查与 MCP 专项体检,host 工具面 + 官方设置页「插件管理」tab。
安装
此插件尚未提供可验证的 bundle,或兼容性检查未通过。请先阅读仓库说明。 阅读完整 README ↗
说明文档
阅读完整 README ↗配置
Config schema(src/index.ts,默认值逐字取自源码):
| 项 | 默认 | 说明 |
|---|---|---|
dshHome | process.env.DSH_HOME ?? '' | DSH 主目录——哨兵、事件日志、预检记录、失败报告的落点 |
selfPluginsDir | '' → ${dshHome}/self-plugins | 自研插件根(档案库扫描源) |
profilesDir | '' → ${dshHome}/profiles | profile 根(cordis.patch.yml + package.json 落点) |
bin | '' → require.resolve('@deepseek-ai/dsh/lib/bin.js') | 试运行预检入口 |
mainSessionId | '' | 哨兵里的唤醒目标;留空 = 追踪最新活跃主体会话(delegationDepth === 0 且最后事件时间最大者)——推荐留空 |
defaultWorkspace | '' → process.cwd() | 工作区(写入哨兵 + 闸门 workspace 比对) |
registryFile | '' | 死配置:声明与默认值存在,全仓库无读取点(见「未支持项」) |
installTimeoutMs | 600000 | pnpm install 超时(超时 → kill + 标 [timeout] + 回滚) |
⑤ 耗时与预算 → 未落盘(缺口):事件行只有 ISO 时刻,无 durationMs;installTimeoutMs=600000 是配置预算、不是实测值
**行为级验证**(无需读文件):`plugin_list` 能返回分组列表 ⇒ 档案库活着;`preflight_check {mode:'quick'}` 后 `.preflight-invoked.json` 的 `atMs` **前进** ⇒ 「我的调用真的落了盘」(改动前后各读一次,前进为准)。
隐私与容错:事件日志与证据行走 `appendLineSafe`(**吞错返回 bool,绝不抛**)——写盘失败不阻断挂载/启停/重启这类主流程。
## 生效判据与回退
**生效判据**(三选一,按可靠性排序):
1. **行为级(最直接)**:本会话工具列表里 14 个工具齐(含 `tool_find`/`preflight_check`/`daemon_restart`);`plugin_inspect dsh-agent-plugin-manager` 返回 `status: mounted`、`version: 0.3.0`。
2. **证据级**:调 `preflight_check {mode:'quick'}` 前后各 `cat` 一次 `${DSH_HOME}/.preflight-invoked.json`,`atMs` **前进** ⇒ 当前进程在跑本插件(不是「文件里有过记录」)。
3. **进程级**:`self-plugins/dsh-agent-plugin-manager/lib/index.js` 的 mtime **≤** web 进程启动时刻,且 `src/` 不新于 `lib/`(源码改了没构建 = 跑的还是旧产物)。
> ⚠ **重新构建 ≠ 生效**:产物 mtime 新只证明「构建过」,**进程启动时间晚于产物 mtime 才算「在跑它」**(AGENTS §5.11 §6)。本插件自己就用这个口径:`hasUnverifiedBuilds()` 发现任一 `self-plugins/*/lib/index.js` **或 profile 的 `cordis.patch.yml` / `package.json`** 比本进程启动晚 → 强制**完整试运行**(约数十秒);毫秒级返回 = 短路(走了「现有实例健康」),数十秒 = 真试运行。
> 📌 **2026-10-19 扩面(`agent-preset/invalid` 事故驱动)**:候选加入**组合面文件**——「只改 patch/preset 声明、不重建任何插件」的那种形状原先会走短路,**新 preset 行从未被试运行验证过**。刻意**不含** `cordis.yml`:它由启动过程自己物化写出(实测写入晚于进程启动)⇒ 纳入即恒假阳性。
> 📌 **试运行预设探针(同日新增)**:预检试运行实例(`DSH_PREFLIGHT_TRIAL=1`)里,本插件在 apply 后问一次 `agentPresets.list()`,把结果以一行 `[preflight-preset-probe] {json}` 打到 stdout,供 `dsh-agent-preflight` 的 `presets` 判据解析。**为什么**:预设激活失败**不影响 web 启动**,只在**新建会话**时抛 `agent-preset/invalid`——「能启动」≠「能建会话」。短路/quick 模式下 `preflight_check` 会把**本进程**的注册表诊断作为 `livePresetProbe` 传下去(来源标注「当前进程组合」)。
> ℹ️ 探针**首次真实运行**即抓出一处真缺陷:`worker-base` 预设四行缺必填 config ⇒ 该预设整体 broken(任何用它的新建会话必报 `agent-preset/invalid`)。已修;详见 `dsh-agent-preflight/docs/semantic.md` 验收 A18/A19。
>
> 另注意:`npm test` 脚本**不含构建步骤**,改完源码务必先 `npm run build`——`tests/*.test.mjs` 是从 `../lib/*.js` 导入的。
>
> 日志旁证(`dsh-agent-plugin-manager 就绪`、闸门证据行的 logger 副本)走宿主 logger,**不落盘**;持久证据只有上面那张表里的文件。
**回退**(三档):
- **源码级**:`git -C self-plugins/dsh-agent-plugin-manager revert `(或 `git checkout -- src/` 丢弃未提交改动)→ `npm run build` → `preflight_check` → 重启;
- **组合级**:profile patch 给 `agent-plugin-manager` 行加 `disabled: true`(或删除该行)→ 该行工具全部消失、档案库不再可查(**注意**:`preflight_check`/`daemon_restart` 也随之消失,重启闸门失效——此时只剩纪律兜底);
- **运行期**:单次操作**失败即已自动回滚**(patch + `package.json` 都还原自 `.bak-`,且**不写哨兵**),手工回退用最新的 `cordis.patch.yml.bak-*` + `package.json.bak-*` 覆盖回去。本插件自身**无持久业务状态**,事件日志/预检记录可随时删除,删掉不影响功能。
回退后用同一套判据复验(工具面数量 / `atMs` 是否仍前进 / `versions` 是否退回)。
## 测试
```bash
npm run build && npm test # test = node --test "tests/*.test.mjs" "test/*.test.mjs"
215 例离线测试,全部 pass(实跑 2026-10-19:# tests 215 / # pass 215 / # fail 0 —— 15 个 tests/ 文件 187 例 + 2 个 test/ 文件 28 例,逐文件复算与总数相等)。测试从 ../lib/*.js 导入(与运行时同源),所以脚本本身不含 tsc——改源码后必须先 npm run build,否则跑的是旧产物(假绿陷阱)。
下表列契约性代表文件(逐文件例数以 npm test 实跑输出为准):
| 文件 | 例数 | 覆盖 |
|---|---|---|
tests/ops-logic.test.mjs | 43 | 纯决策逻辑:档案过滤、插件名校验、loader 快照映射、活跃会话挑选、列表渲染、脚手架生成(含空描述/无 dsh- 前缀的保守占位)、工具发现(匹配分档 · 空 query 概览 · 2 个尸体样本 · 渲染层截断且数据层保真)、预检逐项读数(preflightCheckLines:全绿必须逐项列出 · 先红后绿 · 截断标原长 · 空值显式披露 · 工具必须接同一份纯函数且 PASS 分支拼 note) |
test/preflight-gate.test.mjs | 14 | 重启闸门:decidePreflightGate 四条判据(未调用 / 预检未过 / 记录不可读 / 时间早于进程启动)+ 调用者提取与比对文案 |
test/registry.test.mjs | 14 | 档案库:parsePatchRows(行解析)、extractTools、isBuilt、patchInsert/patchSetDisabled/patchSetConfig/patchRemove 行编辑、packageAddLinkDep/packageRemoveDep、buildRegistry 对账 |
tests/registry-deps.test.mjs | 5 | 第三方盘点(§5.23):classifyDependency 七档(自研 link / 本地 link / 官方 / git pin / tarball / registry / file:)、redactSpec 脱敏(pin 保留)、scanThirdParty 夹具(git-pin 带 dsh.profile.bundles ⇒ bundle=true 且 mounted;registry 未安装 ⇒ unmounted、版本留空)、尸体测试(profiles 路径不存在 → 空列表不抛) |
tests/third-party-refusal.test.mjs | 4 | 第三方生命周期拦截(§5.23):拒绝文案含名/pin/profile + 两条指路(改 pin、dsh plugin add/remove)+ §5.23 依据;bundle=false 时不编造 bundle 说明;五个动作(挂载/卸载/启动/停用/配置)动词各异 |
tests/event-log.test.mjs | 4 | 事件日志薄壳:行格式、尸体测试(不可写路径 → 返回 false 且不抛) |
其余文件(2026-10-19 实测例数):mcp-check 21 · update-check 16 · scaffold-peer 15 · mcp-io 14 · update-io 11 · inflight-subagents 10 · inflight-session-dirs 10 · drift 13 · purge-logic 8 · redact-config 7 · patch-js-tag 6 ⇒ 合计 131;上表 84 ⇒ 131 + 84 = 215 ✓
无需网络、无需真实外部依赖(pnpm、dsh bin、真实 profile 在测试中都不触碰;临时目录用 mkdtempSync)。
未覆盖(诚实声明):挂载/卸载/启停/daemon_restart 的端到端路径(真改 profile → 真预检 → 真回滚 → 真写哨兵)没有自动化测试——那会触发真实重启;registry.ts 的官方 bundles 分支仍无夹具(第三方四形态已覆盖,见上表)。对应缺口见 docs/semantic.md §10 U4/U6。
设计要点
- 不变量 I1 改前必备份:每次
cordis.patch.yml/package.json修改先落.bak-;目录里没有对应.bak-*的写入即视为不合规。 - 不变量 I2 预检失败必回滚且不写哨兵:
preflight().pass === false→ 还原全部已改文件并返回ok:false,triggerReload不得被调用。组合永远回不到坏状态,进程也永远不会带着坏组合重启——这是本插件最核心的约束。 - 不变量 I3 挂载状态以 loader 为权威:
plugin_list的status与ctx.loader.entries()一致(alignWithLoader);静态快照(data/system-state.json)只作补充。历史事故:陈旧快照把已归一的插件仍标mounted。 - 不变量 I4 重启走进程级闸门:
daemon_restart的判据是「本 web 进程启动后是否调用过preflight_check且最近一次pass === true」——不比对 sessionId(设计如此,§5.11 §3);.preflight-invoked.json不可读/坏 JSON 时 fail-closed 拒绝。sessionId字段是历史遗留,真实调用者记在caller,门控不用它做判断,只作证据留痕。 - 不变量 I5 卸载保留数据:
plugin_unmount只移除 patch 行与 link 依赖,不删插件目录。 - 第三方按「安装形态」枚举,不按某一种形态写死(§5.23,2026-09-14 修):第三方档认五种落点——
link:(本地 clone)、git pin(github:owner/repo#ref)、codeloadtarball、registry 版本号、file:;档案额外带bundle(列在 profile 的dsh.profile.bundles⇒ 自述式挂载,不由 patch 行挂)与spec(含 pin,升级/回退唯一指纹,落盘前经redactSpec脱敏)。 历史缺陷:原实现是if (!spec.startsWith('link:')) continue——只认本地 clone 形态,于是github:…#commit这种依赖整条被跳过;主人新装的第三方插件在plugin_list --source third-party里查无此人(实测返回空)。教训:盘点器跟着「包管理器形态」演化,而不是跟着某次实现的假设。 - 第三方不走本工具的生命周期(§5.23):
plugin_mount/plugin_unmount/plugin_start/plugin_stop/plugin_configure对第三方一律显式拒绝,并给出指路(改 profile 依赖 pin 或官方dsh plugin --profile add/remove)。 理由:本工具的生命周期原语是「写link:依赖 + 插 patch 行」——只对自研成立;第三方是 profile 依赖 + 包自带dsh.bundle.patch(自述式挂载),用自研路径操作它会写出错误的依赖形态与多余 patch 行。 教训:「工具能看见某资源」≠「工具的操作语义对它有定义」——可见性补完必须立刻问一句「那我的写操作对它意味着什么」。 - 不变量 I6 只读面永不抛:
plugin_list/plugin_inspect对坏包、缺失目录逐目录try/catch跳过并继续;loadSystemState/loadOfficialCatalog读不到返回{}/[]。 pnpm install --package-import-method=copy:copy 导入方式绕开 Windows 上 link/rename 的 EPERM(spawn(..., { shell: true }))。- 预检本体零重复实现:
profile.ts:preflight()是dsh-agent-preflight的runPreflightCore薄封装,预算preflightReadyMs = 90000(为 48 插件组合实测约 40s 留 2.25x 余量)。 - 并行实例协调的判据:
.plugin-manager-events.log由event-log.ts:appendLineSafe写入(吞错返回 bool)——事件行失败绝不阻断主流程,但它是「另一个我是否正在部署」的唯一线索。 - 反定位(本文不管什么):不管进程生命周期(kill/spawn/保活归
dsh-agent-guardian/dsh-agent-sentinel,本插件只写哨兵);不管预检实现(归dsh-agent-preflight);不管语义文档注册(归dsh-semantic-docs);不是沙箱、不是权限边界;不是 npm 包管理器。
未支持项 / 已知缺口(不吹):
| 项 | 状态 |
|---|---|
registryFile 配置项 | 死配置——声明 + 默认值存在,全仓库无读取点 |
自证轨迹的 build 字段(五问①) | 缺——事件日志无「跑的是哪个构建」自报,只能靠 mtime 对照 |
| 自证轨迹的耗时字段(五问⑤) | 缺——事件行只有 ISO 时刻,无 durationMs/预算字段 |
| 端到端自动化测试 | 缺——真改 profile → 真预检 → 真回滚链路无夹具 |
| 调用者鉴权 | 无——有权限的调用方即可操作;保护来自备份 + 回滚 + 预检门控 + 上层裁决包 |
plugin_unmount 名称 | 与 plugin_remove 同义(工具名如此,描述里已注明);数据目录不含在内 |
相关文档
| 文档 | 内容 |
|---|---|
docs/semantic.md | 权威契约:定位与反定位、术语表、概念模型与 6 条不变量、契约(配置实际使用列 + 10 工具 + 调用点清单)、边界与信任、与既有机制的关系、可证伪验收清单(A1–A9)、实现关系、实践修订记录、未决问题 U1–U5 |
| alice-digital-life | 本插件所属生态的中心索引(全部自研插件) |
技能 plugin-workflow | 插件全生命周期编排(检查 → 升级 → 测试 → 命名 → 发布 → 回退) |
技能 plugin-maintainability / dsh-plugin-development | 机制自证与可维护性工程、DSH 插件开发方法论 |
License
MIT © jonah791
本插件属于我的数字生命爱丽丝(alice-digital-life)的 DSH 自研插件生态——50 个插件按生命/认知/感知/行动/通信/治理/呈现七层组织。