前言¶
在 DSH 里跑智能体时，界面往往只显示「运行中」，很难区分是任务本身慢、进程挂起、卡在审批，还是已经进入错误风暴。想停掉某一个跑飞的工具调用，又常常只能停整轮，其它正常进行中的调用会一起被终止。DeepSeek Harness 采用「一切皆插件」的扩展方式；社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系。下面介绍维护者 QTATQ233 发布的 鲸察（dsh-jingcha）：在运行时只读观察工具流水线，给出判定与理由，支持按 callId 强制停止，并在 Web 控制台右下角提供红绿灯状态挂件，默认不向模型注册工具，占用 0 model token。
这是什么¶
鲸察 是分类为「工作流」的 DSH 插件，仓库地址 github.com/QTATQ233/dsh-jingcha。当前 package 版本为 0.5.1，许可证 MIT，运行时 零 npm 依赖，要求 Node ≥ 18。
它解决三类问题：工具调用长时间无反馈时缺少可操作的诊断；需要精确终止单个调用而非整轮；事后复盘缺少结构化现场。监察数据写入本机目录（默认 %DSH_HOME%\data\dsh-jingcha），不联网、不动态执行第三方代码。
核心功能¶
监察与判定¶
插件在 tools/pre-execute、tools/execute、tools/result 三层做只读观察，记录耗时、结果字节与错误分类。内置判定包括：慢、挂起、卡住、静默（有 agent 在跑却无输出）、等待审批、错误风暴、内存泄漏预警、插件自身报错。0.5.0 起判定规则可编排：内置 8 条可通过 disabledRules 按 id 停用，第三方可用 monitor.registerRule({ id, evaluate }) 注册。
默认阈值（可在配置中修改）如下：
| 判定 | 默认条件 |
|---|---|
| 慢 | 单次调用超过 30s（slowCallMs） |
| 挂起 | 在途超过 2min（hangCallMs） |
| 卡住 | 在途超过 5min（stuckCallMs）且期间没有产出 |
| 没有输出 | 有 agent 在跑但 90s 内没有流式帧 / 会话事件 / 工具结果（silenceMs） |
| 等待审批 | pre-execute 卡在审批超过 20s（approvalWarnMs） |
| 错误风暴 | 连续 3 次失败（errorStormCount） |
| 内存泄漏预警 | RSS 连续 5 个心跳递增且增幅超过 10% |
状态优先级为：stalled > erroring > degraded > busy / ok，避免次要告警淹没「卡住」类问题。
按调用强制停止¶
在 pre-execute 阶段为每次调用登记属于鲸察的 AbortController 并替换 exec.signal，与 DSH 上游 callerSignal 融合，上游取消语义不变，插件也可主动掐断。嵌套子调用（父 id 加 :ptc: 序号）同样可登记。面板中每条在途调用带强停按钮；还支持「停掉卡住的」「停止所有轮次」（带二次确认）。强停成功会写入 kill.forensics 事件，便于在 events.jsonl 中复盘。
挂件与本地 API¶
Web 端注入可拖动「胶囊」：按调用时长分级变色（绿 / 黄 / 红），悬停可看全文，快捷键 Ctrl+Shift+J。详情面板含判定、在途调用、最近告警、设置与时间线等可折叠区块。四个 HTTP 端点（status / kill / stop / settings）仅监听回环地址，Host 白名单，拒绝跨站来源；变更类只接受 POST JSON。可选 apiToken 要求请求头 x-jingcha-token。
落盘与零 token¶
status.json：原子替换的快照。events.jsonl：追加式事件流，超过 8MB 自动轮转（约 16MB 上限）。- 默认
toolEnabled: false，模型上下文看不到插件工具；若打开，README 说明每请求约多 176 token 工具说明，每次查询约 0.5k token 报告。
安装与启用¶
官方通道安装后需 重启 dsh：
dsh plugin --profile web add github:QTATQ233/dsh-jingcha
仓库还提供 tools/install.ps1（junction + 修改 profile manifest，改前自动备份、可整体回滚）。安装、卸载或分享数据前可参考仓库 docs/SHARING.md。
不启动 dsh 也可做仓库自检：
node test/verify.mjs # 179 项
node test/verify-client.mjs # 111 项（挂件，DOM 桩）
配置要点¶
配置集中在 cordis.patch.yml（项旁有中文注释）。常用键：
| 键 | 默认 | 说明 |
|---|---|---|
dataDir |
%DSH_HOME%\data\dsh-jingcha |
数据目录 |
displayName |
鲸察 | 控制台前缀与报告标题 |
toolEnabled |
false | 是否向模型注册查询工具 |
slowCallMs / hangCallMs / stuckCallMs |
30s / 2min / 5min | 慢 / 挂起 / 卡住 |
autoKillAfterMs |
0（关） | 自动强停；同时要求没有产出 |
previewArgs / redactPreviews |
true / true | 参数摘要与敏感片段打码 |
apiToken |
空 | 多用户机器建议设置 |
典型用法¶
- 安装并重启 dsh 后，打开 Web 控制台，右下角应出现状态胶囊；有在途工具调用时会显示类似「pwsh 1m33s」的摘要。
- 若判定为「等待审批」，到界面完成确认，避免误判为卡死。
- 若判定为「卡住」或单次调用异常偏长，打开面板查看在途列表，对目标
callId点强停，或批量「停掉卡住的」。 - 需要复盘时读取
dataDir下的events.jsonl；分享前注意其中可能含工具参数摘要（默认截断并脱敏，仍建议人工过目，或设previewArgs: false）。
挂件支持 ?session= 会话维度过滤；0.5.0 起面板含约 5 分钟迷你时间线。
适用场景与注意¶
适合：本地或单机 Web profile 下长时间跑工具链、需要可视化「慢 / 挂 / 卡 / 无输出 / 审批 / 错误风暴」并精确止损的开发者。
注意：
- 插件以 当前 dsh 进程权限 运行；安装前应自行审阅源码与 MIT 许可证，勿在未检查的情况下信任第三方插件。
- 回环 API 对本机其它进程/账号仍可能可达，共享机器请设
apiToken。 - 忽略
exec.signal的同进程死循环无法靠信号硬杀；嵌套场景若只有父调用在跑，插件会拒绝误杀父调用。 - 监控路径包在
safe()中，插件异常只记入pluginErrors，不改写工具结果。
架构、状态机、接口 Schema 见仓库 docs/ARCHITECTURE.md 与 SECURITY.md。
结尾¶
鲸察把 DSH 运行时的工具调用、事件循环与错误模式做成可读的判定与可操作的强停，默认 0 token 观测，适合作为工作流侧的「运行时体检」插件。目录页：skillhub.cn/plugins/QTATQ233/dsh-jingcha；源码与文档：github.com/QTATQ233/dsh-jingcha。
