jonah791/dsh-agent-plugin-manager ↗★ 1

dsh-agent-plugin-manager

插件管理器:插件档案库(清单/用途/工具/配置认知,含 14 工具)+ 生命周期管理(创建/挂载/启停/卸载/配置/彻底退役)+ 档案漂移审计(plugin_audit:自述 vs 档案事实)+ 规范自检(plugin_spec_check:九项机械判据)+ 上游更新检查与 MCP 专项体检,host 工具面 + 官方设置页「插件管理」tab。

套件
dsh-agent-plugin-manager
相容性
待驗證
Harness 依賴範圍
>=0.1.0-rc.6
Cordis 依賴範圍
^4.0.1
版本
0.3.0
授權
MIT
最近更新
2026年11月12日

安裝

此插件尚未提供可驗證的 bundle,或相容性檢查未通過。請先閱讀倉庫說明。 閱讀完整 README ↗

配置

Config schema(src/index.ts,默认值逐字取自源码):

项默认说明
dshHomeprocess.env.DSH_HOME ?? ''DSH 主目录——哨兵、事件日志、预检记录、失败报告的落点
selfPluginsDir'' → ${dshHome}/self-plugins自研插件根(档案库扫描源)
profilesDir'' → ${dshHome}/profilesprofile 根(cordis.patch.yml + package.json 落点)
bin'' → require.resolve('@deepseek-ai/dsh/lib/bin.js')试运行预检入口
mainSessionId''哨兵里的唤醒目标;留空 = 追踪最新活跃主体会话(delegationDepth === 0 且最后事件时间最大者)——推荐留空
defaultWorkspace'' → process.cwd()工作区(写入哨兵 + 闸门 workspace 比对)
registryFile''死配置:声明与默认值存在,全仓库无读取点(见「未支持项」)
installTimeoutMs600000pnpm 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.mjs43纯决策逻辑:档案过滤、插件名校验、loader 快照映射、活跃会话挑选、列表渲染、脚手架生成(含空描述/无 dsh- 前缀的保守占位)、工具发现(匹配分档 · 空 query 概览 · 2 个尸体样本 · 渲染层截断且数据层保真)、预检逐项读数(preflightCheckLines:全绿必须逐项列出 · 先红后绿 · 截断标原长 · 空值显式披露 · 工具必须接同一份纯函数且 PASS 分支拼 note)
test/preflight-gate.test.mjs14重启闸门:decidePreflightGate 四条判据(未调用 / 预检未过 / 记录不可读 / 时间早于进程启动)+ 调用者提取与比对文案
test/registry.test.mjs14档案库:parsePatchRows(行解析)、extractTools、isBuilt、patchInsert/patchSetDisabled/patchSetConfig/patchRemove 行编辑、packageAddLinkDep/packageRemoveDep、buildRegistry 对账
tests/registry-deps.test.mjs5第三方盘点(§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.mjs4第三方生命周期拦截(§5.23):拒绝文案含名/pin/profile + 两条指路(改 pin、dsh plugin add/remove)+ §5.23 依据;bundle=false 时不编造 bundle 说明;五个动作(挂载/卸载/启动/停用/配置)动词各异
tests/event-log.test.mjs4事件日志薄壳:行格式、尸体测试(不可写路径 → 返回 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)、codeload tarball、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 个插件按生命/认知/感知/行动/通信/治理/呈现七层组织。