---

📖 目录

• 它解决什么问题
• 它长什么样
• 30 秒上手
• 功能一览
• 判定规则
• 配置
• 安全边界
• 零 token
• 它是怎么接进去的
• 架构与状态机
• 接口与 Schema
• 示例
• 二次开发
• 常见问题
• 文档
• 术语表
• 路线图
• 贡献
• 许可

---

🎯 它解决什么问题

痛点	以前的处境	有了鲸察
工具调用跑着没动静	界面只说「运行中」，分不清是慢、死了，还是在等你点审批	快照 + 事件流给出判定与理由（慢 / 挂起 / 卡住 / 没有输出 / 等待审批 / 错误风暴）
想停掉某个跑飞的调用	只能停整个轮次，别的活一起陪葬	按 callId 强停单个调用，或「停掉卡住的」「停止所有轮次」（带二次确认）
出问题想复盘	没有现场	每次调用一条事件（工具、参数摘要、耗时、结果、错误分类）→ events.jsonl
不想被插件吃 token	工具一注册就占上下文	默认 toolEnabled: false，模型完全看不到它，0 token

🖼️ 它长什么样

浅色	深色

• 胶囊：状态点 + 判定文字（有在途调用时显示「pwsh 1m33s」）；拖动可移动，位置自动记住；
• 面板：判定（含事件循环延迟与调用计数）/ 在途调用（每条带 ⛔ 强停）/ 最近告警 / 设置，四段可折叠；
• 灯色：按调用时长分级 —— 不超过黄灯秒是绿、不超过红灯秒是黄、超过就是红（呼吸动画）；
• 深色与浅色：胶囊、面板、色板共用同一个基底色派生，字色跟着底色走，不会出现「深底白字」。

🚀 30 秒上手

# 官方通道（装完需要重启 dsh）
dsh plugin --profile web add github:QTATQ233/dsh-jingcha

# 自检（零依赖，不需要 dsh 在跑）
node test/verify.mjs          # 121 项
node test/verify-client.mjs   #  90 项（挂件，DOM 桩）

不想走插件通道？仓库里也有 tools/install.ps1：建 junction + 改 profile manifest，改前自动备份、可整体回滚。 安装/卸载/分享前的安全检查见 docs/SHARING.md。

✨ 功能一览

• 监察：在 tools/pre-execute、tools/execute、tools/result 三层只读观察，记录耗时、结果字节、错误分类；
• 判定：慢 / 挂起 / 卡住 / 静默（有 agent 在跑却没有输出）/ 等待审批 / 错误风暴 / 内存泄漏预警 / 插件自身报错；
• 强停：融合一个属于鲸察的 AbortController（上游取消语义不变），并且在 pre-execute 就登记 —— 所以嵌套子调用（父 id 加 :ptc: 序号）也能停；停不掉时返回人话原因，绝不错杀父调用；
• 挂件：可拖动、按调用时长分级变色、异常右侧弹提示、悬停省略号看全文（不闪烁）、五宫格复位、 深浅色统一、隐藏后原位置可找回、Ctrl+Shift+J 快捷键；
• 接口：status / kill / stop / settings 四个端点，只监听回环 + Host 白名单 + 拒跨站来源 + 变更类只收 POST JSON；
• 落盘：status.json（原子替换的快照）+ events.jsonl（追加式事件流，超 8MB 自动轮转）。

🧭 判定规则

判定	触发条件（默认阈值）	建议动作
慢	单次调用超过 30s（slowCallMs）	看看是不是正常的长任务
挂起	在途超过 2min（hangCallMs）	关注，可能要停
卡住	在途超过 5min（stuckCallMs）且期间没有产出	点「停掉卡住的」
没有输出	有 agent 在跑但 90s 内没有流式帧 / 会话事件 / 工具结果	检查模型侧
等待审批	pre-execute 卡在审批超过 20s	去界面点确认，别误判成卡死
错误风暴	连续 3 次失败（errorStormCount）	停手，先看错误分类
内存泄漏预警	RSS 连续 5 个心跳递增，且增幅超过 10%（memoryLeakWindow / memoryLeakGrowth）	确认是不是真泄漏；长任务本身在涨就调大窗口或阈值
插件自身报错	鲸察自己抛异常	报告 bug（它保证不反过来搞坏工具调用）

⚙️ 配置

全部在 cordis.patch.yml（每项都有中文注释）：

键	默认	说明
dataDir	%DSH_HOME%\data\dsh-jingcha	数据目录（status.json / events.jsonl / widget-settings.json）
displayName	鲸察	控制台前缀与报告标题
toolEnabled	false	是否注册模型可见的查询工具（打开后每请求多约 176 token）
slowCallMs / hangCallMs / stuckCallMs	30s / 2min / 5min	慢 / 挂起 / 卡住
silenceMs	90s	「没有输出」判定
approvalWarnMs	20s	等待审批提示
autoKillAfterMs	0（关）	自动强停阈值；同时要求没有产出，避免误杀慢任务
memoryLeakWindow / memoryLeakGrowth	5 / 0.1	内存泄漏预警：连续多少个心跳递增、增幅超过多少才算
previewArgs / redactPreviews	true / true	是否记录参数摘要 / 是否对 token、password 一类片段打码
apiToken	空	设了就要求 x-jingcha-token 头（多用户机器建议设）

🔒 安全边界

• 四个接口统一过栅栏：只认回环地址、Host 必须在 127.0.0.1 / localhost / ::1 白名单（挡 DNS rebinding）、 拒绝带 Origin 或 Sec-Fetch-Site: cross-site 的请求、变更类接口只接受 POST + application/json （挡 img 标签一发即杀与跨站表单）、可选 apiToken；
• 插件不联网、无第三方依赖、不做动态执行；客户端全程 textContent（无 XSS 面）；
• events.jsonl / status.json 含工具参数摘要（默认截断 120 字符并对敏感片段打码），分享前先看一眼，或用 previewArgs: false 关掉；
• 残余风险：回环等于「本机全体」，同机其它账号/进程仍可访问 —— 多用户环境请设 apiToken。
• 观测数据本身是敏感的：events.jsonl / status.json 含参数摘要（≤120 字、默认脱敏），分享前先看一眼，或用 previewArgs: false 关掉；
• 脱敏默认会把 --password x、token=…、Bearer … 这类片段遮成 [已脱敏]，过脱敏是故意的（-p 8080 也会被遮），要放松就改 redactPatterns；
• 0.4.3 独立安全审查（运行时 + 工具链两路）结论：无严重/高危；已修脱敏覆盖、采样越界、token 常量时间比较、发布自检同源降级等问题（见 CHANGELOG）。

细节见 SECURITY.md。

🪙 零 token

默认不注册任何模型可见的工具（status.json 里 extras.tool 为 null），事件流与挂件都不进模型上下文 —— 不花一分钱 token。 如果你希望会话里能直接问「现在卡在哪」，再把 toolEnabled 打开（代价：每请求多约 176 token 的工具说明 + 每次查询约 0.5k token 的报告）。

🧩 它是怎么接进去的

lib/core.js    纯逻辑：判定、统计、状态机（零依赖，可单测）
lib/index.js   宿主接线：工具流水线观察、融合强停信号、HTTP 路由、心跳
lib/sink.js    落盘：status.json 原子写 + events.jsonl 追加与轮转
lib/client.js  浏览器挂件（单文件 bundle，零 require）

• 强停原理：在 pre-execute 给一次调用装上属于鲸察的 AbortController 并替换 exec.signal，DSH 派发时会把 「上游 callerSignal」与「我们的信号」融合 —— 因此上游取消照旧、我们也能主动掐断；调用结束再还原并摘掉登记；
• 挂件灯色按调用时长在客户端即时计算（不等宿主），判定状态另走一路；
• 规格与验收清单：lib/WIDGET-SPEC.md。

🛠️ 二次开发

docs/EXTENDING.md 给了五类改动的最小清单（加判定规则 / 加路由 / 加面板分区 / 加设置项 / 换语言换配色）， 通常只需要动 2 到 6 处；三条必踩的坑也写在里面（例如轮询里不要重建交互控件）。

❓ 常见问题

• 停不下来？ 忽略 exec.signal 的同进程死循环无法硬杀（插件只能中止信号），但 pwsh 之类的子进程会被真的杀掉； 嵌套调用若只有父调用在跑，插件会明确拒绝，而不是误杀父调用；
• 会不会反过来搞坏工具调用？ 所有监控路径都包在 safe() 里，异常自己吞掉并计入 pluginErrors，不影响工具结果；
• 数据长多大？ events.jsonl 超 8MB 自动轮转保留一份（约 16MB 上限），status.json 始终只有一份快照；
• 要重启吗？ 宿主侧代码改动需要重启 dsh；只改挂件（lib/client.js）刷新页面即可。

🏗️ 架构与状态机

数据流、五个状态之间的迁移条件、13 种 reason kind 的严重度与去处，以及"为什么这么设计"的六条取舍， 都画在 docs/ARCHITECTURE.md（含两张 Mermaid 图：组件数据流 + 判定状态机）。

• 优先级：stalled > erroring > degraded > busy / ok —— 一个卡住的调用不会被一堆小告警淹没；
• 强停原理：pre-execute 就装上自己的 AbortController 并替换 exec.signal，DSH 派发时与 callerSignal 融合， 上游取消照旧、我们也能主动掐断；调用结束还原；
• 只读优先：所有监控路径包在 safe() 里，异常只记账，绝不改写工具结果与取消语义。

🔌 接口与 Schema

产物	文件	用途
OpenAPI 3.1	docs/openapi.yaml	四个本机接口的完整契约（含准入规则、错误码、全部响应字段）
Config JSON Schema	docs/config.schema.json	cordis.patch.yml 里 config: 的 28 个字段：类型 / 默认值 / 取值范围 / 说明

接口速览（全部要求回环 + Host 白名单；变更类要 POST + application/json）：

GET  /api/jingcha/status      # 实时判定 + 在途调用 + 最近告警（与 status.json 同源）
POST /api/jingcha/kill        # { "callId": "..." } 或 { "scope": "stalled|all" }
POST /api/jingcha/stop        # 停掉所有在跑的轮次
GET  /api/jingcha/settings    # 读挂件设置（含默认值）
POST /api/jingcha/settings    # 写挂件设置（字段白名单 + 数值夹紧后落盘）

🧪 示例

examples/ 里四个零依赖脚本，直接 node 跑：

脚本	用途
01-read-status.mjs	读快照打印判定；状态不是 ok/busy 时退出码 1（可挂定时任务 / CI）
02-watch-http.mjs	每 2 秒拉一次接口，只在判定变差时打印
03-kill-runaway.mjs	列出在途调用并强停指定 / 最久的那个；默认 dry-run
04-custom-verdict.mjs	直接用 lib/core.js 造一条判定（演示可扩展性）

📔 术语表

判定 / 状态 / 理由 / 告警 / 在途 / 卡住 / 静默 / 融合信号 / 嵌套子调用 / pts … 全部中英对照见 docs/GLOSSARY.md。

🗺️ 路线图

ROADMAP.md：0.5（判定规则可编排 / 会话维度过滤 / 停后取证）· 0.6（i18n / 配置校验 / 指标导出）· 1.0（契约单一化 / 静默失败可观测）。 明确不做：自动改工具调用、默认联网上报、硬杀同进程死循环、默认把观测塞进模型上下文。

📚 文档

文件	内容
docs/SHARING.md	装给别人 / 卸载 / 分享前的安全检查
docs/EXTENDING.md	加判定规则 / 路由 / 面板分区 / 设置项的最小改动清单
docs/PUBLISHING.md	维护者发布流程（复制脱敏 + 隐私自检 + 推送）
lib/WIDGET-SPEC.md	挂件规格与验收清单
docs/ARCHITECTURE.md	架构数据流 + 判定状态机（Mermaid）
docs/GLOSSARY.md	术语表（中英对照）
docs/openapi.yaml	接口的 OpenAPI 3.1 契约
docs/config.schema.json	配置的 JSON Schema
examples/	四个可直接运行的零依赖示例
ROADMAP.md	路线图与「明确不做」
CODE_OF_CONDUCT.md	贡献者公约
CHANGELOG.md	版本记录

🤝 贡献

见 CONTRIBUTING.md。简单说：提交前保证三套自检全绿、隐私自检「通过」， 并且守住三条铁律（只观察不改写 / 设置项两端同步 / 轮询里不重建交互控件）。Issue 与 PR 都欢迎。

📄 许可

MIT —— 见 LICENSE。参与前请先读 CODE_OF_CONDUCT.md。

---

⭐ Star History

📣 分享