前言¶
在 DeepSeek Harness（dsh）里跑一条复杂对话时，主 agent 会派出多个 subagent，工具调用和模型回复交错进行。事后若要判断「卡在哪一步、是谁先出问题、subagent 交回了什么」，往往只能翻日志或会话记录，难以把主从关系和时间顺序放在一张图上对照。
dsh-stuck-monitor 是社区维护者 jwang513 提供的被动记录插件：它不干预 agent 行为，只订阅 dsh 事件流，按时间汇总主 agent 与各 subagent 的动作，在 Web 界面的「会话复盘」标签里回放，并对可规则化的失败与卡住点做标记；需要时再按需生成 AI 前因后果复盘。
这是什么¶
一句话来说：被动 dsh 记录器——在同一时间线上重放主 agent 与全部 subagent，标出卡住位置，并可按需写入 AI 因果复盘。
- 维护者：jwang513
- 仓库：github.com/jwang513/dsh-stuck-monitor
- 社区目录：skillhub.cn/plugins/jwang513/dsh-stuck-monitor
- 许可证：MIT（见仓库 README）
- package.json 版本：0.5.0
插件只记录，不提醒、不纠正、不拦截 agent。
在哪里查看复盘¶
打开任意会话，在标题下方视图栏选择 对话 / 轨迹 / 会话复盘，点 会话复盘。显示的是当前会话；会话进行中大约每 5 秒刷新一次。
会话总览页¶
- 整体复盘（AI）：发生了什么、最终结果、问题从哪一步开始、前因后果、各 subagent 的作用。
- 时间线：主 agent 与每个 subagent 各一条泳道；色块表示一段工作，红点为问题、黄点为外部阻拦、灰色斜纹为探查区段，虚线表示派出 subagent；可点 subagent 名字或色块进入其页面。
- 参与者：按「在主 agent 哪一段被派出」分组；含运行状态、问题数、是否已复盘。
- 主 agent 的经过：分段列表，展开可见各时间点事件；「派出 / 收到结果」旁可跳转到对应 subagent。
subagent 页¶
从参与者列表进入；若在 subagent 自己的会话里打开该标签，会直接显示此页。
- 来龙去脉：派出时刻与主 agent 段、完整任务、结束方式与时间、交回内容及对应主 agent 段（可点击跳转）。
- 它自己的复盘（AI）
- 它自己的时间线：竖线为时间点（模型回复或工具调用），红色表示出错或有问题；空白处拖动可框选时间段，下方「经过」仅显示该区间。
- 经过：各事件的时间、内容、参数、结果或报错原文。
导出 Markdown：总览页导出整个会话（含全部 subagent）；subagent 页只导出该 subagent；已生成的 AI 复盘会一并导出。文件名形如 replay_2026-11-05_140200_session.md。
自动标出的问题类型¶
标记只针对「确实失败或卡住」，不评价工作方式是否像偷懒。分三类。
红点：问题（agent 自身失败或卡住）¶
| 问题 | 判断方式 |
|---|---|
| 原地重复 | 同一调用连续 3 次以上，参数相同且返回结果也相同（结果在变如轮询状态，不算） |
| 来回打转 | 2–4 个调用组成循环重复 3 轮以上，每轮结果相同（如改代码→跑测试且结果在变，不算） |
| 同一错误反复出现 | 同一工具同类错误 3 次以上（行号、路径不同仍算同类） |
| 输出撞上限 | 模型回复写到一半因 max-tokens 截断 |
| 没有正常结束 | subagent 以出错或拒绝执行结束 |
黄点：外部阻拦¶
| 情况 | 判断方式 |
|---|---|
| 操作被拒绝 | 报错含 approval / rejected / denied / permission 等 |
| 模型请求失败 | 网络、限流或服务端错误 |
| 被取消 | 用户手动停止或上级 agent 取消 |
灰色斜纹：工作方式记录（非问题）¶
| 记录 | 判断方式 |
|---|---|
| 探查 | 连续 15 次以上只读调用（read、grep、glob、search、ls、web_* 等） |
| 长思考 | 单次回复推理超过 8000 tokens（真正撑爆由「输出撞上限」标出） |
是否合理需结合任务判断；AI 复盘会结合任务上下文说明。
AI 复盘¶
- 每个 subagent 可单独生成复盘；整体复盘会复用已生成的 subagent 复盘，未生成的用压缩后的经过，避免长会话超出模型输入上限，且只为选定部分付费。
- 仅点击按钮时生成，不会自动调用模型。
- 默认使用当前对话所用模型；可在配置中指定其他模型。调用走 dsh 自有模型服务（与会话标题自动生成同路径）。
- 结果保存在本地；会话有新进展时，复盘卡片会提示「可重新生成」。
环境与安装¶
要求 Node.js 24 或以上；README 注明在 dsh 0.2.1-rc.5 上开发与测试。
先停止正在运行的 dsh，在 dsh 项目目录执行：
npx dsh plugin --profile web add https://github.com/jwang513/dsh-stuck-monitor
npx dsh web
将 --profile web 换成你实际使用的 profile 名。若已安装，重启 npx dsh web 即可。
配置¶
在 ~/.dsh/profiles/<profile>/cordis.patch.yml 末尾追加（Windows 上 ~ 为 C:\Users\<用户名>）：
- id: stuck-monitor
name: 'dsh-stuck-monitor'
config:
outputDir: '' # 记录目录，留空表示 ~/.dsh/stuck-monitor
aiProvider: '' # AI 复盘用的模型；留空表示用对话本身的模型
aiModel: ''
aiMaxTokens: 6000
repeatThreshold: 3 # 下面这些是问题判断的阈值
cycleMinRepeats: 2
repeatedErrorThreshold: 3
readOnlyStretch: 15
reasoningWarnTokens: 8000
记录文件位置¶
默认在 ~/.dsh/stuck-monitor/sessions/（可通过 outputDir 修改）。每次对话约三个文件：
<id>.session.json：完整事件流、分段与问题<id>.meta.json：列表摘要<id>.ai.json：AI 复盘（生成后才有；整体与各 subagent 复盘均在此）
安全与原理简述¶
面板数据接口 /stuck-monitor/session、/stuck-monitor/analyze 使用 dsh 登录与来源校验：无 dsh 链接 token 返回 401，跨站请求返回 403。
插件主要监听 agent/pre-step、agent/request、agent/assistant-stream、tools/pre-execute / tools/post-execute、agent/request-error、subagent/start / subagent/end、agent/turn-stopping 等事件；lib/index.js 汇总并约每 5 秒写盘，lib/detect.js 实现问题规则，lib/analyze.js 负责 AI 复盘，client/client.js 提供「会话复盘」标签与 Markdown 导出。
适用场景与注意¶
适合需要事后对照主从 agent 时间线、定位重复调用或权限类卡点的 dsh 用户与智能体开发者。问题检测基于行为模式，语义上「偏离任务」需依赖 AI 复盘；思考内容每轮仅保留首尾各约 400 字，正文最多约 1500 字；写盘间隔约 5 秒，崩溃前最后几秒可能丢失；插件安装前已结束的会话无记录；用户以 /skill名 直接调用的 skill 不计入工具调用，但用户原话会出现在时间线。
插件以当前 dsh 进程权限运行，安装前请自行审阅源码与 MIT 许可证。
结尾¶
dsh-stuck-monitor 把一次对话里主 agent 与全部 subagent 的动作收到同一时间线，用规则标出可识别的卡住点，并在需要时用 AI 写清前因后果，适合作为 DSH 生态中的被动观测与复盘工具。
- 目录页：https://www.skillhub.cn/plugins/jwang513/dsh-stuck-monitor
- GitHub：https://github.com/jwang513/dsh-stuck-monitor
