dsh-recency-guard
Verifieddsh-recency-guard · v0.17.0 · MIT · Web UI
Crash-recovery guard for DeepSeek Harness: records third-party/experimental plugin install & update recency, backs up their config, and after a crash auto-disables the most-recently-updated plugin(s) so the profile boots again, then restores stable config
Install
dsh plugin add dsh-recency-guard Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
dsh-recency-guard
DeepSeek Harness 的插件崩溃恢复守护:记录第三方 / 实验性插件的安装与更新时序并备份配置; 崩溃后的下一次启动之前,把最近更新的嫌疑插件挡在门外;稳定启动后,再把非首要嫌疑放回来。
版本基线(2026-11-11,北京时间):0.17.0。版本四锚点(
package.json/ 本 README /docs/agents//dsh-plugin.json)一致。 测试分四层,当前 84/84 全绿(Core 42 / Host 10 / Client 24 / Contract 8)。
它解决什么问题
在 DSH 里安装或更新一个第三方 / 实验性插件后,宿主可能直接退出:
dsh: fatal uncaught exception: Error: ...
崩溃发生在插件加载阶段,插件自己已经来不及运行 —— 它的恢复逻辑、工具、面板都不可达。 手动流程是:禁用所有插件 → 重启 → 逐个加回 → 每次重启验证。慢,而且容易再踩一次。
本插件把这件事自动化成三步:
| 步骤 | 手动做法 | 本插件 |
|---|---|---|
| 记录 | 靠记忆 | 安装 / 更新事件写进 journal.jsonl(崩溃也不丢) |
| 拦截 | 手动改配置 | 崩溃瞬间同步写决策文件;Loader 在 import 嫌疑插件之前求值守护行 |
| 恢复 | 逐个加回 | 稳定启动后恢复非首要嫌疑;首要嫌疑留给你确认 |
它不做什么:不修复宿主自身缺陷、不处理依赖版本不兼容、不阻止 entry 级 apply 抛错
(那是宿主的自隔离 warning,不是进程崩溃)。见下文「诚实边界」。
安装
npm(推荐)
dsh plugin --profile <profile名> add dsh-recency-guard
安装后重启 dsh。启动时本插件会自动:
- 在 profile 的
cordis.patch.yml中为每个第三方插件写入守护行; - 开始记录安装 / 更新事件与配置备份。
锁定版本:
dsh plugin --profile <profile名> add [email protected]
版本对应:本 README 描述本仓库 0.17.0 源码。npm 上实际可安装的版本以
npm view dsh-recency-guard version为准;若latest落后于本文版本,请按下面的源码方式安装, 或等待对应版本发布。发布顺序见docs/agents/conventions.md§6。
插件市场
投稿材料已按 awesome-dsh-plugin contributing.md
备好(docs/market-submission.md):一个条目文件、category: security。
上架后可在 dsh 的 Plugins → Discover 或 dsh-market 中搜索 recency-guard 安装。
当前状态:材料已备、PR 未提交 —— 本文不声称已在市场中可搜到。
手动 / 本地源码(开发)
git clone https://github.com/xuanyuanchumo/dsh-recency-guard.git
cd dsh-recency-guard
npm install
npm run build # 必跑:dsh plugin add file: 只拷贝 files 声明的产物,不执行构建
dsh plugin --profile <profile名> add file:/绝对路径/dsh-recency-guard
开发期反复改代码时用 link:(Windows 落 Junction),改完 npm run build 重启即生效:
dsh plugin --profile <profile名> add link:/绝对路径/dsh-recency-guard
安装顺序
本插件必须排在被守护插件之前,才能在启动阶段完成守护行安装。确认 profile 的 package.json:
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"dsh-recency-guard",
"dsh-你的插件"
]
}
}
三分钟上手
重启 dsh 后打开面板:侧栏图标「插件守护」→ 中央面板。首屏三块:生命周期、崩溃决策、能力清单。
用工具看状态(会话里让模型调用,或直接看命令窗口):
{ "action": "status" }输出包含崩溃次数、嫌疑排名(全量)、自动关闭名单、声明式冲突(每条带
文件:行号与声明原文)、上次隔离后仍治不了的unresolved、隔离分区与量化指标; 不可判定的指标显示原因,不显示 0。看磁盘事实:
<profile>/.recency-guard/projects/<分区键>/下的journal.jsonl/state.json/decision.json是全部真相,面板只是它们的投影。想验证拦截:不要在主 profile 做。用独立沙箱 profile 装一个故意抛异常的插件, 启动 → 崩溃 → 再启动,观察决策文件与日志。步骤见
docs/agents/verification.md§5.3。
能力表
每条能力的代码位置与验证入口都可点击核对。能力清单本身是投影,真相在注册处 (工具注册、路由注册、事件发射),由契约测试双向比对。
面板与图谱
管理面板
- 数据面:
GET /recency-guard/api/snapshot。自适应轮询:内容稳定时 5s→10s→15s 退避,内容变化/用户操作立即回 5s,绝对边界 [3s, 30s];暂停按钮按下后不再发请求 (画面停在暂停时刻,而不是继续跳)。 - 卡片:稳定性 / 阶段 / 崩溃率 / 崩溃压力 / CUSUM 变点、预防性预警(启动频率控制带、
配置变更 CUSUM;只预警不行动,不可判定显示原因)、崩溃决策与因子分解、
声明式冲突(每条带
文件:行号与声明原文)、未解决冲突(上次隔离后仍治不了的部分, 与「现在有冲突」分开显示)、量化指标(不可判定显示原因)、能力清单与缺口、项目隔离、归档、事件流。 - 可空契约:宿主在跨分区只读视图会发
null/ 整段省略的字段,由snapshot-view.ts的PanelSnapshotView显式放宽, 渲染层诚实降级,不把面板整块打进错误边界(契约测试panel-snapshot-nullability.test.ts守护)。 - 折叠记忆:折叠态存
localStorage的recency-guard-collapsed,读取失败退化为全展开,不抛异常。 - 动作:恢复非嫌疑插件、重新启用某个插件、归档重置 —— 都携带快照的
revision; 过期返回 409 且动作不执行,面板提示重读后再决定。 - 滚动:面板自己滚(
height:100% + min-height:0 + overflow-y:auto),页面不被撑高。 - 真机视觉验收:卡片标题单行;数据流 4 步完整;面板已无渲染崩溃 ——
此前
intervals.cv=null会让整块白屏,现由客户端可空视图 + 契约测试钉住(见上)。
可交互图谱
- 缩放:
Ctrl/⌘ + 滚轮(指针为锚),或工具栏+/-;普通滚轮滚面板,不吞手势。 - 默认 fit-all:首帧优先铺满全图;内容多时文字会偏小,可点工具栏「放大视图」。 22 节点规模下首帧会自动放大到可读比例。
- 放大视图:高度按像素(不是
vh),窗口变化不挤压图形;收起后保留缩放, 不把用户视角打回默认。 - 平移 / 拖拽:拖画布平移;拖节点做用户叠加层位移,数据轮询不会重置它。
- 选择:单击节点高亮上下游;双击节点居中;点击边看边详情(可与节点详情互斥收起)。
- 搜索:输入定位;
Enter在匹配项间循环并显示第 n / m 个。 - 图例:按着色口径自动跟色(改配色图例跟着变),形状通道同样入图例。
- 小地图:显示全图范围与当前视口,可点击 / 拖拽跳转。
- 键盘:方向键在节点/边之间二维导航,
+/-/0缩放与复位,Esc一次清空全部观察态,Enter循环搜索结果(以GuardGraph.tsx的aria-keyshortcuts为准)。 - 轮询不重置视口:fit 只跑一次(有守卫),数据刷新不会把用户缩放打回默认。
本文不贴截图:仓库的
screenshots.json目前只声明了市场图标, 没有面板 / 图谱截图。宁可写清交互,也不放一张不存在的图。
工具:recency_guard
execute 返回规范 JSON(业务数据摊平在顶层),人读文本由 output.render 投影,
命令窗口另接 presentCall / presentResult / presentationMeta 三条卡片通道。
| action | 参数 | 行为 |
|---|---|---|
status |
— | 崩溃状态、嫌疑排名(全量)、自动关闭、声明式冲突(带出处)、未解决冲突、指标、工作区 / 分区归因 |
history |
limit?=40 |
安装 / 更新 / 崩溃 / 恢复事件时间线 |
recover |
— | 按确定性冲突与依赖联动做贪心最小隔离;未命中声明时退回「按最近更新关闭」;残余 unresolved 上屏 |
restore |
— | 重新启用非首要嫌疑,首要嫌疑保持关闭 |
reenable |
bundle |
手动重新启用指定插件 |
backups |
— | 配置备份清单(含版本时间线) |
archive |
reason? |
归档当前产物并重置(先写审计行,再执行) |
archives |
— | 历史归档清单(带 manifest 摘要) |
所有写 action 在执行之前先落一条审计行(kind: note + 结构化 audit{actor,action,justification});
审计写失败不阻塞动作。读 action 不写日志。
CLI 逃生通道
宿主起不来时,面板、工具、路由全都不可达 —— 这时用零依赖的 rescue CLI 直接读磁盘。
默认只读;写操作必须显式 --yes,且是两阶段、可精确回插的。
只读命令(默认绝不写盘)
node bin/rescue.mjs status --profile-dir "<profile目录>" [--project <key|label>]
node bin/rescue.mjs history --profile-dir "<profile目录>" [--limit 40]
node bin/rescue.mjs decision --profile-dir "<profile目录>"
node bin/rescue.mjs archives --profile-dir "<profile目录>"
node bin/rescue.mjs rescues --profile-dir "<profile目录>"
可写命令(崩溃救火,默认 dry-run)
# 1) 先看计划:把 decision.json 的 disable 名单(或 --bundle)从 profile bundles 摘掉
node bin/rescue.mjs apply --profile-dir "<profile目录>" [--bundle a,b] [--reason "事故说明"]
# 2) 确认后真正落盘
node bin/rescue.mjs apply --profile-dir "<profile目录>" --yes
# 3) 回插:默认取最新一条可回插记录;中断后用 --resume
node bin/rescue.mjs restore --profile-dir "<profile目录>" [--id <uuid>] [--resume] --yes
- 两阶段:先写
prepared记录(含beforeHash/afterHash/ 每个 bundle 的原 index), 再原子改 profile 的package.json,最后标applied;记录在<profile>/.recency-guard/rescue/<uuid>.json。 - 中断恢复:
restore --resume读prepared记录,用哈希判定第二步是否已生效 ——afterHash相符 ⇒ 按已生效回插;beforeHash相符 ⇒ 第 2 步没发生,记录作废、不动 profile。 回插按原 index 升序执行,不会互相挤位。 - 拒绝而不是硬改:现场哈希不符 / 记录被篡改 ⇒ 退出码
3,不覆盖。 - 退出码:
0正常;1参数错误;2发现未恢复的崩溃状态;3拒绝(现场已变)。 - npm 安装后也可用 bin 名:
recency-guard-rescue status --profile-dir ...。
Windows 示例:
node bin/rescue.mjs status --profile-dir "%USERPROFILE%\.dsh\profiles\desktop"
诚实边界
概率性判定(会观察、可能不立刻行动)
- 第二条崩溃通道(残留 bootMarker + 该 pid 已不在)是概率性证据:
人为强杀也会产生同样形状。因此第 1 轮只观察,同一头号嫌疑累计到
confirmRounds(默认 2)才动手; 唯一嫌疑走确定性证据,第 1 轮即行动。 - 幻影「另一个实例」已单独归类为
self-reload(同 pid 热重载),不按并发实例处理。
写安全与对账(真机竞态修复)
- journal 是 append-only:崩溃路径同步追加、绝不整文件回写;行数裁剪只在异步、
加锁的安全时机做。并发写不会再用旧快照覆盖
crash-detected(此前真机约 1/9 复现)。 - 以决策文件为真相补账:哨兵在场且决策文件有非空
disable时,state 缺失的autoDisabled/ 被清零的crashSeq会在下次启动补回;无哨兵 / 非崩溃决策 / 空名单 一律不补(不猜)。 - 清零是 CAS:干净启动只归零「本轮启动后没被崩溃改过」的计数,晚到的异步写
不会抹掉崩溃路径刚写下的
crashSeq。 - 降级可查:启动编排的分区索引提交 / 变更记录 / 官方实验观测失败,都会落一条
journal
note并带degraded: true—— 不只写 logger,重启后仍可查。
研究边界(避免误读)
- 预防性预警只预警、不行动:启动频率 EWMA 与配置变更 CUSUM 只进观测面
(面板/
status),不被任何关闭决策读取;样本不足 ⇒defined:false+ 原因,不填 0。loadTime是「启动频率(次/分钟)」的代理,不是真实加载耗时 —— 面板会原样显示代理说明。 - 共现信号只判定、不加权:
mayWeightByCooccurrence只在满足研究 09 §4.3 的条件时给出「可加权」判定, 默认决策权重仍为 0;面板显示判定与理由,不把共现当成已生效权重。
明确不拦 / 不修的
- entry 级
apply抛错:宿主只 warning 并自隔离该 entry,进程不崩 —— 不属于本插件的拦截面。 真崩溃来自进程级未捕获异常 / rejection。评估守护能力时别用 entry 级失败当夹具。 - 官方组件:
@deepseek-ai/*永远不是嫌疑;官方实验包(@deepseek-ai/dsh-experimental-*) 只观测、绝不自动关闭(关官方组件等于卸宿主半边)。 - 宿主自身缺陷 / 依赖版本不兼容:本插件不修,也不假装能修。按
docs/agents/update-guide.md的紧急流程处理。 - 指标不可判定时为
null,不是 0:没有真实崩溃样本时,贝叶斯后验、预防性预警不编数字; 研究文档里的「Top-1 命中率提升 ≥5%」「预警提前量 ≥1 轮」两条效果判据尚未声称达成 (机制已就位,效果待真机样本)。 - 跨分区只读视图:
GET /snapshot?partition=<key>的运行时字段(stage / metrics / markov) 如实降级为null/idle,不替别的分区编造状态;revision恒为null。 - 声明式冲突只在有声明时产生:插件没写
dshCompat/dsh-plugin.json、版本范围不可判定、 对手不在场 ⇒ 不产生 finding(不猜)。conflicts空数组 = 扫过且没有,不是没扫。 unresolved不静默:受保护组件(官方 / 本插件)/ 无候选 / 配额不足导致治不了的冲突会单独上屏; 不会用 recency 嫌疑人顶替确定性目标来「装作解决」。maxAutoDisable是整组上限:依赖联动可能一次关一组;整组放不进配额则一个都不动 (不让依赖者半关着在下一次启动时再崩一次)。- rescue 写模式不是自动的:默认 dry-run,不带
--yes绝不写;两阶段 + 哈希校验, 现场已变时退出码3拒绝而不是硬改 profile。
配置
在 profile 的 cordis.patch.yml 中:
- id: recency-guard
name: dsh-recency-guard
config:
enabled: true # 总开关;false 时只记录,绝不自动关闭
includeExperimental: true # 实验性 / beta 命名是否算嫌疑
maxAutoDisable: 2 # 单次恢复最多停用几个(整组上限,含依赖联动)
autoRestore: true # 稳定后自动恢复非首要嫌疑
confirmRounds: 2 # 概率性证据的行动阈值(唯一嫌疑不受限)
versionedBackups: true # 更新时写带版本的时间线备份
backupRetain: 5 # 每插件保留几份
backupRoot: '' # 备份自定义目录(环境变量 RECENCY_GUARD_BACKUP_ROOT 优先)
| 配置 | 默认 | 说明 |
|---|---|---|
enabled |
true |
总开关。关闭后只记录,永不自动禁用 |
includeExperimental |
true |
实验性 / beta 命名的包是否算嫌疑 |
maxAutoDisable |
2 |
单次恢复最多停用数,整组上限(依赖联动可能一次关多个;整组放不进则不动) |
autoRestore |
true |
稳定启动后自动恢复非首要嫌疑 |
confirmRounds |
2 |
多嫌疑时同一头号嫌疑连续 N 轮才自动关闭(唯一嫌疑第 1 轮行动) |
versionedBackups |
true |
写「带版本的时间线备份」,可逐版对账 |
backupRetain |
5 |
每个插件保留的备份份数(超出删最旧) |
backupRoot |
'' |
自定义备份目录;RECENCY_GUARD_BACKUP_ROOT 优先 |
兼容范围
| 项 | 范围 | 依据 |
|---|---|---|
| dsh 宿主 | >=0.2.1-rc.5 <0.2.2-0 || >=0.2.2-rc.1 <0.2.3-0 || >=0.2.3-rc.1 <0.3.0-0 |
package.json 的 engines.dsh |
| 开发 / 测试代际 | 0.2.2-rc.1 |
devDependencies 与 peerDependencies 对齐 |
@deepseek-ai/cordis |
>=4.0.5 <5.0.0 |
宿主实际 4.1.0;旧 ~4.0.5 会被兼容闸门整体拒绝 |
| 官方包 | 全部 peerDependencies + optional: true |
缺 dsh-tools / schemastery 时降级加载,不 require 崩 |
| 社区 manifest | draft v0.15(dsh-plugin.json) |
与 dsh 安装契约(package.json)并存,不是替换 |
| Node | 开发与测试环境 v24.14.0;package.json 未声明 engines.node |
不声称未验证的 Node 版本 |
| 平台 | Windows 真机实测(桌面端 dsh) | Linux / macOS 未做真机崩溃注入验证 —— 未声称 |
预发布分支为什么要写显式
||:node-semver 只允许「范围里某个比较符与该版本的major.minor.patch元组一致、且自身带预发布标签」时才放行预发布版本。 写成>=0.2.1-rc.5 <0.3.0-0会静默排除0.2.2-rc.1,用户安装直接撞ERESOLVE。
数据文件
全部在 profile 目录下,按工作区分区(项目 A 的崩溃不影响项目 B):
<profile>/.recency-guard/
├── current.json # 指针:当前分区键(守护行表达式经它搭桥)
├── partitions.json # 分区索引:项目 → 分区键
├── rescue/<uuid>.json # 两阶段 rescue 记录(profile 级;apply/restore 用)
└── projects/<分区键>/
├── journal.jsonl # 只追加:install / update / crash-detected / disable / restore / note
├── snapshot.json # 上次观测到的 { 插件名: 版本 }
├── state.json # 崩溃计数、自动关闭 / 已恢复名单
├── decision.json # 本轮要拦截的插件 + unresolved 残余(守护行表达式读 disable)
├── crashed # 崩溃哨兵(非零退出码时写下)
├── observation-*.json # 观测快照(指标数据源)
├── archive/ # 历史归档(搬走 + 留档)
└── backups/ # 关闭前备份的配置(versionedBackups 时带版本)
开发与测试
npm install
npm run build # esbuild 双产物:dist/index.js(宿主)+ dist/client.js(客户端)
npx tsc --noEmit # 类型
npm run lint # 类型 + 未使用符号
npm test # 分层运行器:Core 42 / Host 10 / Client 24 / Contract 8 = 84
npm run extract-runtime # Host 层测试前置(runtime/ 缺失时先解出)
- 当前基线:
npm test84/84 通过、npx tsc --noEmit0 错误(2026-11-11 实测)。 - 验证顺序固定:build → typecheck → lint → test,全部零错误才算完成。
- 文档体系与写码纪律见
docs/agents/; 发布 / 升级 / 热重载见docs/agents/update-guide.md。
版本记录
| 版本 | 一句话 |
|---|---|
| 0.17.0(2026-11-11) | 技术栈清理与研究闭环:预防性预警(RQ3)接入生产且只预警不行动、面板自适应刷新、状态文件 schema 版本(未知版本保留现场)、变异 72 突变体 / 0 未归因 + 无直接测试 14→2 + rescue/宿主宽度跨实现对拍;技术债状态见 docs/agents/tech-debt.md |
| 0.16.0(2026-11-11) | 确定性冲突证据(4 类 finding + 出处)、贪心最小隔离与依赖联动、可写两阶段 rescue、常态路径锁卫生、PanelSnapshotView 可空契约;新增社区 manifest dsh-plugin.json,README 面向用户重构,版本四锚点统一 |
| 0.15.0 | 架构重构:host/ + client/ + shared/ 分层,client→host 越界与值依赖环写成契约测试 |
| 0.14.0 | 误伤反馈闭环、贝叶斯风险并行读数、预防性健康指标(EWMA / CUSUM)、自动化变异测试 |
| 0.13.0 | 决策因子快照、决策与展示排序口径统一、可选 peer 惰性解析(修安装即崩)、图谱结构洞察 |
| 0.12.1 | 崩溃信号第二条通道:哨兵盲区(SIGKILL / 断电)与 self-reload 判别 |
| 0.12.0 | 命令窗口显示接线、动作路由乐观并发(409)、L4 审计线、依赖代际对齐 |
| 0.11.x | 数据面安全(动作路由方法守卫)、跨分区只读快照、图谱交互补齐(边 / 小地图 / 触屏) |
| 0.10.0 | 马尔可夫转移矩阵、休哈特控制带、诊断投影与反馈入口 |
| 0.9.0 | 恢复置信分级(confirmRounds)、两阶段提交、离线 rescue CLI |
| 0.8.0 | 备份增强(版本时间线)、官方实验插件只观测、事件驱动变更检测 |
| 0.7.0 | 崩溃级修复(守护行 YAML 写入管线)、可交互图谱、可观测性白盒化 |
| 0.3–0.6 | 能力闭环双向比对、生命周期状态机、量化指标、多项目隔离、面板与图谱基础 |
长设计论证(为什么这样决策、数学模型、踩过的坑)已迁到
docs/agents/design.md,不再堆在 README。
许可
MIT。见 LICENSE。