循环诊断器 Hubert-hwk/dsh-loop-doctor

dsh-loop-doctor

针对 DeepSeek Harness（dsh）的自诊断插件家族：基于 harness 自身的 SessionEvent 日志做确定性弯路（detour）检测，产出可人工复核、带回放验证的优化建议，并积累"已采纳修复"沉淀——让 harness 读自己的日志，告诉操作者浪费在哪里。

先观察、后建议、再写入，写操作置于人工复核之后。

四个包

| 包 | 层面 | 作用 |
| @hubert-hwk/dsh-loop-doctor-detector | 观察 | 把 session/event 流折叠成 DetourSignal（重试风暴、工具误用、上下文抖动、提示词膨胀、效果空转）——纯确定性规则，不调用 LLM。 |
| @hubert-hwk/dsh-loop-doctor-advisor | 建议 | 通过修复模式表把信号映射为 Suggestion，并针对真实日志做回放验证（replay-verified 与 simulated 绝不混同）。 |
| @hubert-hwk/dsh-loop-doctor-apply | 写入 | 唯一的持久化决策：人工复核台账、窄口径自动应用闸门（默认关闭）、可热重载的"已采纳修复"沉淀。 |
| @hubert-hwk/dsh-loop-doctor-tool | 模型面 | loop_doctor_diagnose 工具：agent 按需诊断自己的会话。 |

自优化闭环

session log ──▶ detector ──▶ signal ──▶ advisor ──▶ suggestion + replay
│ │
│ ▼
│ apply: ledger (human)
│ │
▼ ▼
tool: loop_doctor_diagnose accepted-fix sediment
│
advisor reload ◀──────────┘
(next match injects the validated fix)

安全基线

- 规则先于 LLM。 检测路径确定性执行，不经过任何模型调用。
- 置信度上限 0.9。 规则引擎从不声称"确定"；专家标注模式显式标记为未验证。
- replay-verified ≠ simulated。 只有基于真实日志、可量化节省的回放模拟才算 replay-verified；仅按策略上限估算的记作 simulated，且永不驱动自动应用。
- 写入后置于人审。 本家族唯一的写操作是它自己的台账与沉淀文件；自动应用默认关闭，仅限 replay-verified 且达到置信度上限的修复。
- 两层诚实。 keyless 快照证明真实循环里的 pipeline；"真实模型自然弯路"的涌现性证明需要带 key 的运行，文档中作为配方说明，绝不声称已验证。

快速开始

本仓库

pnpm install
pnpm run typecheck # 对整个家族做 tsc 检查
pnpm test # vitest —— 四个包共 140 个测试

端到端 keyless 证明位于 examples/headless-agent/loop-doctor.cordis.snapshot.yml（三次真实弯路、两次自诊断、快照内观察到 auto-apply 与 reload 闭环），需在完整 deepseek-harness 检出并应用本分支后运行；回放夹具约束见 Agent Note。

从 npm 安装

pnpm add @hubert-hwk/dsh-loop-doctor-detector \
@hubert-hwk/dsh-loop-doctor-advisor \
@hubert-hwk/dsh-loop-doctor-apply \
@hubert-hwk/dsh-loop-doctor-tool

在 DeepSeek Harness 中使用

四个包设计为 dsh 主机的插件：把安装好的包接入你的 dsh 插件配置。若要在 harness 源码检出中运行，把 packages/loop-doctor/ 复制进 harness 工作区，并把包名改回上游的 @hubert-hwk/dsh-loop-doctor-（或直接使用上游 feat/loop-doctor 分支）。

与上游的关系

本家族是作为对 deepseek-ai/deepseek-harness 的上游贡献而编写的（分支 feat/loop-doctor，基于官方 master）。上游目前不接受外部 PR（见其 CONTRIBUTING.md），因此本仓库作为该工作的公开社区展示主页：

- 面向上游设计：目录结构、门禁均与 harness 单体仓库对齐，未来上游重新开放贡献时可直接 rebase 上去。包以社区作用域 @hubert-hwk/ 发布（@deepseek-ai/ npm 作用域归官方组织所有）；在 harness 内部它们使用上游包名 @hubert-hwk/dsh-loop-doctor-。
- Agent Note 随附：.agents/notes/implemented/feature/2026-08-19-loop-doctor-self-diagnosis.zh.md。

社区

- 到 DeepSeek Harness GitHub Discussions 讨论 / 点赞（分类：Show Your Plugins!）。
- 本仓库已打上 dsh-plugin topic，便于 harness 社区发现。

许可

MIT