插件冲突管家（P2M）

English | 中文

DSH 冲突管家（P2M）：自动拦截会让 DSH 闪退的同名服务注册、版本漂移、补丁覆盖冲突，按用时排序并隔离肇事插件；同时统一管理插件启停、动态维护优先级。

仓库与包标识沿用 DSH-P2M / dsh-p2m（技术标识不变）；P2M 为本插件对外昵称。

---

它解决什么

插件装多了以后的三类痛点：

痛点	P2M 的做法
没有统一管理	一处登记/启停/隔离/恢复所有插件，决策写入唯一的 guard 文件，跨重启生效
冲突只能被动熔断	检测（启动崩溃归因 / 运行期自动禁用 / 静态补丁扫描）→ 按优先级裁决 → 留痕、可回滚
没有优先级概念	恒定 DSH > P2M > 其他；其他插件按累计使用时长实时排序：B 用得比 C 久，维护顺序就是 DSH > P2M > B > C > …

补充能力（v1 含）：下载后"真实开启前先试跑"——新插件启用前在子进程里试运行一次；会崩就弹窗给两个选项：「取消开启」/「无视风险继续使用」。

优先级机制

tier 0  DSH 本体      （name 以 @deepseek-ai/ 开头，或配置的 coreEntryIds）
tier 1  P2M 自身      （entry id: p2m，自杀免疫：guard 里出现自己会被自动移除）
tier 2  其他插件       （按 usage.json 累计使用毫秒降序 = 维护优先级）

铁律：任何决策永不禁用 tier0/tier1；同层冲突牺牲"用时短者"。

动态示例（对应需求）：台账 B=12h, C=5h, D=2h → 顺序 DSH → P2M → B → C → D；B 继续用、C 停用使 D=3h > C=5h 变 C=5h,D=3h → 顺序变为 DSH → P2M → B → D → C。

工作原理（一页速览）

• DSH 插件 = Cordis loader entry：每个插件是 npm 包，cordis.patch.yml 声明挂载行。
• 配置按层合并，--patch 覆盖层（guard 文件）最后生效，禁用心最强。
• P2M 用 loader 热管理 API（create/update/remove）做运行期调度；root 树的 write() 是 no-op，所以每次决策双写：guard（持久，重启有效）+ 运行时热更新（即时生效）。
• 详细设计（冲突分类矩阵、guard 协议、数据格式、边界）见 DESIGN.md。

安装

环境要求：DSH（dsh CLI 全局安装）、Node ≥ 18。

方式 A：官方插件 CLI（仓库公开后可用）

dsh plugin --profile web add github:GiantAxeint/DSH-P2M

方式 B：本地 link（开发/未发布时）

1. 把本仓库放到任意目录（如 E:\DeepseekHome\Plugin\DSH-P2M）。
2. 编辑 profile 的 package.json（Windows 示例：%USERPROFILE%\.dsh\profiles\web\package.json）：
   • dependencies 增加："dsh-p2m": "link:E:/DeepseekHome/Plugin/DSH-P2M"
   • dsh.profile.bundles 数组开头插入 "dsh-p2m"（保证它最先加载，体现 DSH > P2M 顺序）。
3. 在 profile 目录执行 pnpm install（DSH 用 pnpm workspace）。
4. 重启 DSH（推荐用下方的 v2 启动器）。

P2M 的 entry id 固定为 p2m，请勿改动（guard 自愈机制依赖它）。

升级启动器（推荐，接管并升级 dsh-safe）

仓库内 launcher/dsh-safe.mjs 是 v2 启动器：纯启动监督（崩溃时只做紧急隔离），canonical guard 迁移到 <DSH_HOME>/p2m/plugin-guard.yml 并与 P2M 共用锁/备份协议，崩溃事件写入同一份 incidents.jsonl。把该文件复制覆盖你原来的 dsh-safe.mjs 即可（旧文件会先备份）。Windows 一键脚本：

scripts\install-safe.cmd

使用

P2M 启动后自动工作；状态与数据落在 <DSH_HOME>/p2m/（默认 ~/.dsh/p2m/）：

文件	内容
plugin-guard.yml	唯一 guard（被禁插件的持久名单，启动时以 --patch 注入）
usage.json	每插件累计使用时长台账（采样口径 30s，可配）
incidents.jsonl	冲突/隔离/恢复/弹窗决策的追加流水（append-only）
state.json	p2m 自身状态（boot 计数、快照等）

启动日志：boot #N

每次 DSH 启动加载 P2M 时，日志里会出现一行（N 为数字，例如 boot #11）：

[p2m] boot #11 | guard=<...> | autoIsolate=true

• #N 不是等级或阶段，而是本机累计第 N 次成功执行 boot 例程——计数器存于 state.json#bootCount，每次 boot +1、只增不减（崩溃后的重启、进程内重复加载也会 +1，因此它≈“启动次数”，不精确等于进程数）。
• 每次 boot 做的事与 N 无关，完全一样：读 state → 自杀免疫（guard 若含 p2m 自身/核心条目则移除）→ 记一版依赖解析快照（E2）→ 跑 peer 版本体检 preflight（E3）→ 静态扫描全补丁层（E4）→ 打印本行。
• 排查时怎么用：N 连续递增 = P2M 每次启动都在正常工作；若两次启动间 N 不变，说明那次 P2M 根本没被加载（被禁用/未启用）；事故发生时可用 N 对齐 incidents.jsonl 的时间线（例如「第 11 次启动崩」→ 看该次 boot 前后的流水）。
• 清零重计：删掉 state.json 中的 bootCount 字段或整个文件即可（P2M 自动重建，不影响 guard/usage/incidents）。

日志显示规则（级别与配色）

P2M 日志分为三级，规则如下：

级别	前缀	配色	何时出现
info	无	无色	正常动作：boot、隔离、启用、对账决策等
提示类	[WARNING]	黄色	未中断 DSH 启动、但需关注的问题：resolve drift、preflight peer 越界、静态扫描冲突、self-heal、loader 不可用等
中断/异常类	[ERROR]	红色	已中断或内部异常：protected 条目被自动禁用、p2m 内部错误等

• 每条 [WARNING] / [ERROR] 之后都附带一行缩进的英文 hint:——说明应检查的具体文件、路径或冲突细节（如 ~/.dsh/p2m/incidents.jsonl、profile package.json、guard 文件）。
• 从属细节行（如具体 bundle 的 declared/resolved 对比、fix 命令）缩进显示、不重复前缀。
• 配色自适应：stderr 非 TTY（日志重定向/管道）或设置了 NO_COLOR 时自动退化为无色文本，避免日志文件残留 ANSI 转义码；需强制颜色时配置 logColor: 'always'（或 'never' 关闭）。

示例（preflight 发现问题时）：

[WARNING] [p2m] preflight: 2 peer violation(s) — 建议先按下方 fix 命令钉版本，再重启 DSH
    @foo/bar peer @deepseek-ai/dsh-settings: declared ^0.1.1-rc.2, resolved 0.1.2-rc.1 | fix: pnpm add @deepseek-ai/dsh-settings@^0.1.1-rc.2
    hint: Check the peer ranges declared in <profile>/package.json against the resolved versions above, then run the fix command (pnpm add ...) inside the profile before restarting DSH.

launcher（DSH-safe.cmd → dsh-safe.mjs）输出遵循同一套规则。

ctx.p2m API（运行期可调）

方法	作用
list()	按优先级输出排序列表（含 tier / usageMs / running / disabled）
status()	当前配置与 guard 状态
usage() / incidents(n)	台账 / 最近 n 条流水
scanConflicts()	立即做一轮静态+运行期冲突扫描（只报告）
enable(id) / disable(id)	恢复/禁用（恢复前会走试用门禁；protected 不可禁用）
trial(id)	手动子进程试跑一次，返回 verdict（ok/crash/timeout/unsupported）
preflight()	跑一轮 peer 版本体检（E3），返回 findings + summary
reconcile() / sample()	手动触发对账 / 采样

试用门禁（下载即试跑）

• 开启新插件/恢复被隔离插件前，先在子进程里 import+apply 试跑一次。
• 试跑失败（crash/timeout/无法判定）→ 桌面弹窗：取消开启（默认，安全）/ 无视风险继续使用（记 incident；若仍崩溃，冷却期内自动隔离，避免弹窗风暴）。
• 配置 autoGateRisk:false 关闭门禁，或 ui:'none' 关闭弹窗（一律默认取消）。

配置（挂载行 config 给入）

key	默认	说明
sampleIntervalMs	30000	使用时长采样间隔
autoIsolate	true	运行期自动隔离（false=只报告）
autoGateRisk	true	试用门禁开关
ui	'auto'	弹窗模式：auto/desktop/none
popupCooldownMs	120000	同一插件弹窗冷却
trialTimeoutMs	15000	试跑子进程超时
coreNamePrefixes	['@deepseek-ai/']	DSH 本体识别前缀
coreEntryIds	[]	DSH 本体额外 entry id
knownCoreServices	['sessionPersistence']	C7 引擎核心默认服务名单快照（置 [] 关闭该告警）
preflightOnBoot	true	E3：boot 时跑 peer 版本体检（只报告）
scanBootLayers	true	E4：boot 静态扫描全补丁层（自动发现）
patchLayers	[]	scanConflicts() 额外扫描的补丁文件（缺省自动发现）
logColor	'auto'	日志配色：auto（TTY 且无 NO_COLOR 才着色）/ always / never

冲突类型速查

类	含义	处理
C1 启动崩溃	启动失败命中 failed to … loader entry	dsh-safe v2 紧急隔离 + incident
C2 运行期自动禁用	loader 把某 entry 置 disabled 未持久化	试跑判定：冲突→隔离；自崩→弹窗
C3 同 id 配置互踩	多层补丁对同一 id 给不同配置（含「出厂禁用被 profile 覆盖」形态）	报告 + 二选一建议（需人工）
C4/C5 重复 id / 同名模块	结构性重复	报告（需人工）
C6 自杀/越权	guard 出现 p2m/core	自愈移除 + incident
C7 同名服务注册	不同插件会注册同一 cordis 服务（或撞引擎核心默认服务，如 sessionPersistence）	启动前预检报告 + 二选一建议
版本漂移（preflight）	peer 声明区间 vs 实际解析版本越界（典型：本地缺失爬升到全局 CLI 旧版）	启动前体检报告 + 钉版本命令（DSH_P2M_PREFLIGHT=block 可拒启）

解析漂移（E2）：每次对账记录各插件 require.resolve 实际落点与版本，漂移写 resolve-drift incident 并持久化进 state.json#lastResolve。

测试

零依赖单测（node:test）：

node --test test/*.test.mjs   # 74 个用例：guard/ledger/priority/conflicts/policy/yaml/trial/C7/preflight/resolve

目录结构

DSH-P2M/
├─ lib/            P2M 本体（ESM，零运行时依赖）
│  ├─ index.js     入口：ctx.p2m 服务、采样、对账、门禁
│  ├─ guard.js     guard 唯一写者（锁+备份+迁移）
│  ├─ yaml-min.js  自带 loader 补丁方言 YAML 解析器
│  ├─ ledger.js    使用时长台账（纯函数 tick）
│  ├─ priority.js  分层与动态排序
│  ├─ conflicts.js 冲突检测（静态+运行期+C7 服务注册预检）
│  ├─ policy.js    裁决引擎
│  ├─ preflight.js 启动前 peer 版本体检（E3，零依赖 semver 子集）
│  ├─ trial.js     子进程试跑（R5）
│  └─ dialog.js    崩溃风险双按钮弹窗（R5）
├─ launcher/       dsh-safe v2 纯启动监督器（复制覆盖旧版）
├─ test/           单测 + 试跑夹具
└─ DESIGN.md       完整设计与边界（必读）

安全与边界（诚实声明）

• P2M 零运行时依赖（连 yaml 解析都自带），自己不会制造依赖冲突。
• 涉及 DSH 本体与自身的决策永远只报告、不自动禁用；guard 出现自身会自愈。
• 试跑能捕获 import/apply 级崩溃；把整个进程炸掉级别的硬崩溃由 dsh-safe 启动熔断兜底。
• 官方 dsh plugin add 是"下载即重启"流，p2m 无法在重启前介入该流（由 v2 启动器熔断+incident 接管）；热挂载/手动恢复等 p2m 可控入口已全部接入试用门禁。

版本与改进记录（2026-09-06）

版本	内容
v0.1.3（E1）	C7 同名服务注册预检（含一跳依赖包溯源 + known-core 二选一告警）
v0.1.4（E2）	解析路径留痕：resolve 快照 + 漂移 incident
v0.1.5（E3）	启动前 peer 版本体检（p2m boot + launcher 内嵌，DSH_P2M_PREFLIGHT=block 可拒启）
v0.1.6（E4）	profile 层覆盖感知：出厂禁用被覆盖 → 二选一建议；C4 误报修正；boot 静态扫描全补丁层
v0.1.6（E5）	本文档体系同步（DESIGN §14 / 速查表 / AGENTS 心法 / 复盘 HTML）
v0.1.7	日志分级与显示规则：提示类 [WARNING] 黄色 / 中断及内部异常类 [ERROR] 红色，尾部附全英文 hint: 检查指引（含 launcher 同步）；preflight 提示文案优化；logColor 配置

完整背景与逐项说明见 docs/incident-2026-09-06.html（冲突事件复盘）与 DESIGN.md。

License

MIT © 2026 Erius (GiantAxeint)