🎓 DSH 插件运行时验证方法论：无 API Key 验证 waterfall 行为（实证 74 事件/12 waterfall）

[qing3a]

背景：雷达的运行时验证空白

awesome-dsh-plugins 雷达显示：286 个插件里只有 5 个做过运行时测试，0 个通过。静态检查只能证明"插件能加载"，证明不了"插件在真实 agent 循环里不破坏行为"——尤其是 waterfall 事件监听器（tools/execute、approval/request、fs/write-intent）必须正确透传 next()，否则静默吞掉下游默认行为，这类错误只在运行时暴露。

传统做法需要真实 LLM API key + token 成本。这里分享一个零成本、可复制的方案：用 DSH 仓库自带的 mock-llm 服务器，无 key 验证插件在完整 agent 循环里的行为。

方案：mock-llm + headless profile + 审计 dump

mock-llm（脚本化返回 tool_call_success）
   ↓ 要求模型调用 bash 工具
DSH headless profile（真实 agent 循环，你的插件挂监听）
   ↓ 走完完整 waterfall 链
DSH_EVENT_AUDIT_DUMP 导出事件审计快照

三步核心命令（完整步骤见下文 + dsh-event-auditor 仓库）：

1. 启动 mock-llm（让第一个请求返回"调用 bash 工具"，第二个正常回复）：

pnpm run mock:llm --port 8000 --api-key mock-key \
  --sequence tool_call_success,success --repeat-last \
  --tool-name bash --tool-arguments '{"command":"ls"}'

2. 跑 headless agent（指向 mock-llm，导出审计）：

DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1 \
DEEPSEEK_API_KEY=mock-key \
DSH_EVENT_AUDIT_DUMP=/tmp/audit.json \
pnpm dsh --profile headless "run the bash tool once and report"

3. 分析快照：byMode 同时含 emit + waterfall、waterfall 链完整出现、agent 正常跑完（mock response recovered）= 通过。

实证结果（dsh-event-auditor，2026-08-14）

74 事件 / 12 waterfall 全部捕获，完整 agent 生命周期：

session/created → agent/created → agent/session-start → inbox/inserted → agent/status → inbox/claimed
→ system-prompt/assemble(wf) → agent/pre-step(wf) → agent/request(wf) → llm/stream(wf)
→ tools/pre-execute(wf) → tools/execute(wf) → tools/post-execute(wf) → tools/result

关键安全证明：agent 完整跑完了工具调用循环——所有 waterfall 监听器都正确透传了 next()，零副作用。这应该是雷达里第一个完整的运行时验证案例。

插件作者要避开的坑（全部实测踩过）

1. sparse clone 一次加全：packages vendor native apps website patches scripts docs——缺 vendor/ 会报 Cannot find package '@deepseek-ai/cordis'（cordis 全家在 vendor/）
2. 三层构建缺一不可：build:lib:host + build:lib:client + web-frontend dist
3. 可选服务用 ctx.inject 动态注入：ctx.get('webServer') 未注入时直接抛错；inject: ['webServer'] 会阻塞 headless 加载
4. npm rc 与 master API 漂移：如 ctx.httpServer(rc) vs ctx.webServer(master)——以实际运行版本 lib/types/ 为准
5. mock:llm 不要多传 --：pnpm run mock:llm -- --port 会把 -- 当位置参数
6. git push 被墙时：gh api Contents API 逐文件上传（见 push-via-api.mjs）

完整方法论

仓库：github.com/qing3a/dsh-event-auditor（dsh-event-auditor 本身就是一个事件审计面板插件，含完整设计文档与验证记录）。

欢迎其他插件作者用本方案验证自己的插件，并把结果贴回来——一起把雷达的"运行时 0 通过"变成过去式。💪

[qing3a]

更正上一条自荐中的包名：插件已发布到 npm，scope 从 @dsh-external 改为 @qing3a（个人 scope，发布权归 qing3a）。

npm 包（可直接安装）

• @qing3a/dsh-event-auditor — 事件流审计面板（settings 热改 + /audit 命令 + headless dump）
• @qing3a/dsh-tray — Windows 系统托盘插件（trayicon exe 宿主，无 native 编译）
• @qing3a/dsh-plugin-verify — 验证 CLI：一条命令跑本方法论（mock-llm + waterfall 7/7 判定）

安装：dsh plugin --profile web add @qing3a/<包名> ｜ 验证：npx dsh-plugin-verify <插件> --repo <DSH checkout>

运行验证成果（2026-08-14）

插件	结果	证据
dsh-security-scan	✅ 通过（7/7 waterfall）	报告 · issue
dsh-balance	✅ 通过（7/7 waterfall）	报告 · issue
dsh-sentinel	❌ headless 加载失败（webServer 必选注入）	issue

两个 ✅ 插件已收录进 Verified DSH Plugins 目录（判定站：只收录通过运行时验证的插件）。