dsh-agent-preflight

一句话：重启前的保险丝——在任何「把当前实例换成新实例」的不可逆动作之前，先真的加载一次新组合，加载不起来就拦住（fail-closed）。

为什么值得用：坏组合一旦被装上，代价是服务整体不可用（web 起不来 → 守护熔断 → 只能靠兜底冷启动）。本插件把「验证」提前到「替换」之前，并且失败不 kill 旧 web——旧实例可能有毛病，但新实例是没验证过的，两害相权取旧。它还会在试运行就绪后再多等一个稳定窗口才判 PASS：webserver 先 listen（约 2.6s 即 HTTP ready），而插件 loader 的 apply 抛错可能发生在之后（约 8s 才 exit code=1）——就绪即杀会把必崩组合误判 PASS。

能力

本插件不注册任何工具，它对外的能力是一个 cordis 服务：

消费方（谁在用）：

检查项（checks 的 8 个键）：

full 模式默认 probeExistingFirst: true：先探活现有实例端口，HTTP 2xx/401/403 = 当前组合可加载的活证据 → 直接 PASS（毫秒级，不 spawn 重复实例）。仅当现有实例不健康时才走完整试运行。组合变更场景（挂载/启停/改配置后）应传 false 强制完整试运行。

快速开始

1) 装依赖（自研插件家园 self-plugins/，在目标 profile 的 package.json 加 link 依赖）：

"dsh-agent-preflight": "link:<工作区>/self-plugins/dsh-agent-preflight"

2) 构建：

cd self-plugins/dsh-agent-preflight && npm install && npm run build && npm test

3) 挂组合（提供服务的这一侧——典型是 watch profile，与 sentinel / guardian 同侧）：

- id: agent-preflight
  name: dsh-agent-preflight
  config:
    profile: web
    targetPort: 3080

4) 30 秒验证（本插件没有工具可调，验证走「消费者触发 + 读轨迹」这条路）：

# ① 核心逻辑自证：24 例离线测试全过
cd self-plugins/dsh-agent-preflight && npm test

# ② 触发一次真实预检（任选其一的消费者）：
#    - 重启/热重载时由 sentinel 门控自动触发
#    - 或在 plugin-manager 侧调用工具 preflight_check（它直调同一核心）
# 然后读判定：
tail -2 "$DSH_HOME/preflight-trace.jsonl"     # 期望：出现 verdict 行，verdict=PASS/FAIL

配置

（键名与 src/index.ts 的 Config schema 一致；默认值取自源码）

落盘与自证（出问题时先看这里）

每次预检落一行 JSONL 到 <DSH_HOME>/preflight-trace.jsonl（DSH_HOME 缺省 ~/.dsh）：

一条命令答五问：

tail -3 "$DSH_HOME/preflight-trace.jsonl"
# ① 跑的是哪个构建  → build = "<version>@<core 模块 mtime ms>"；builds[] = 自建 + 试运行目标 bin（版本读不到时退化为 unknown@mtime——版本会说谎，mtime 不会）
# ② 谁发起          → caller（调用栈首个非本插件帧；全自有帧则 unknown）+ pid（预检在 watch 与 web 两侧都跑，pid 区分进程）
# ③ 断在哪一段     → phase 枚举；失败时看 error 的断点分类（「组合加载抛错」还是「全程无输出的卡死」）
# ④ 结果质量       → verdict / failedChecks[] / shortcut（现有实例健康短路 = 没真试运行）
# ⑤ 耗时与预算     → durationMs（trialRun/* = 试运行实耗；verdict = 全程）对比 preflightReadyMs / trialHardMaxMs

两个「已调用预检」标记不要混淆：

观测纪律：轨迹写盘失败一律吞错返回 false，绝不影响预检结论（日志失败不改变判定，也不抛）。

生效判据与回退

生效判据（三选一，按可靠性排序）：

1. tail -1 "$DSH_HOME/preflight-trace.jsonl" 里 build 的 mtime 等于 lib/index.js（或 lib/core.js）的 mtime ⇒ 进程在跑当前构建；
2. 生态级：plugin_boot_status（dsh-plugin-bootreport）返回的 liveNow 含本插件 ⇒ 同上；
3. 行为级：消费方能拿到 ctx.preflight 服务并返回 PreflightResult（sentinel 门控跑通，或 preflight_check 工具返回结论）⇒ 服务已挂载。

注意：重新构建 ≠ 生效——产物 mtime 新只证明「构建过」，进程启动时间晚于产物 mtime 才算「在跑它」。提供服务的这一侧（watch）没有 hasUnverifiedBuilds() 类兜底，构建完必须重启该进程才生效。

回退（三档）：

• 源码级：git -C self-plugins/dsh-agent-preflight revert <commit> → npm run build → npm test → 预检 → 重启；
• 组合级：在服务侧 profile 给 agent-preflight 行加 disabled: true（或移除该行）→ 重启该 profile；
• 运行期：无需回退（无持久业务状态；preflight-trace.jsonl 可随时删除）。

测试

npm test        # = node --test "tests/*.test.mjs"（跑 lib/ 产物，需先 npm run build）

24 例离线测试全部通过（# pass 24 / # fail 0）：

无网络依赖、无真实外部服务依赖：测试链路由注入式配置 + 临时目录驱动，不 spawn 真 web（真试运行在生产路径上由消费方触发）。

设计要点

• fail-closed 的语义：预检失败 ⇒ 不替换。旧实例可能有毛病，但至少是已经在跑的；新实例没验证过。这是免疫层的全部意义——误判失败的代价（一次多余的重启）远小于误放行的代价（服务不可用 + 守护熔断）。
• 「就绪」不等于「加载完」：listen 发生在 loader apply 之前。preflightGraceMs 是为此刻意保留的跨层不变量——改试运行判定逻辑时不得省掉就绪后的存活确认窗口，否则必崩组合会被放行。
• 「超时」不等于「卡死」：负载下启动可能很慢但仍在推进。trialProgressWindowMs 用「窗口内有输出」区分慢启动与真卡死，trialHardMaxMs 作为不可突破的兜底——判死必须有硬上限，判活必须有推进证据，两者缺一都会误判。
• 判据单一真源（D1）：检查逻辑全部在 core.ts（模块级导出、零 ctx 依赖），服务壳与 preflight_check 工具共用。禁止在消费方复制一份判据——两处各自维护「什么算通过」必然漂移。
• 观测不反噬：轨迹写入是纯副作用，失败不影响判定，也不抛。排障时若轨迹缺失，先怀疑 DSH_HOME 不可写，而不是怀疑预检本身。

安全与边界（重要）

• 本插件只回答「能不能动」，不执行「动」：不监听哨兵、不 kill、不拉起 web。那些是 dsh-agent-sentinel（重启）与 dsh-agent-guardian（保活拉起）的职责。
• 不是沙箱、不是安全边界：它防的是「组合装载失败」这类工程损坏，不防恶意代码、不防越权操作（能力 ≠ 沙箱）。
• 不是组合语义校验器：只验证「能否加载」，不判断「这套组合是不是我想要的」。
• 试运行会 spawn 一个完整 web（同 profile / 凭据 / DSH_HOME）。实现会给它打标记让副作用型插件让位；即便如此，凭据敏感的部署应先在隔离环境验证。
• 不受 Windows 文件沙箱约束：试运行子进程与调用方同权限运行。

相关文档

License

MIT © jonah791

本插件属于我的数字生命爱丽丝（alice-digital-life）的 DSH 自研插件生态——50 个插件按生命/认知/感知/行动/通信/治理/呈现七层组织。