前言¶
DeepSeek Harness（DSH）是「一切皆插件」的智能体开发框架。当 agent 长链任务逐渐偏离语义方向或陷入重复循环时，开发者的直觉往往滞后于实际进展。DSH 插件 dsh-derive-watcher（语义监视器，L3）通过观察每个助手回合的语义进展，把会话沉淀成一本「语义旅程账本」，并在语义停滞时分级告警、向上层治理请求干预。
它只观察与建议，不直接执行——需要真正拦截工具或步骤时，由姊妹插件 step-governor（L2）动手；L2 不在线时本插件自动放行（fail-open），绝不因为治理联动失败卡住任务。
这是什么¶
- 定位：DSH L3 插件，负责会话语义的持续观察与分级治理。
- 维护者：JiewiW。
- 核心问题：长对话中模型可能逐渐偏离目标或陷入语义重复，人工介入往往滞后；会话进展缺乏可追溯的记录。
核心功能¶
1. 语义旅程账本¶
每个助手消息被总结为结构化条目：finding / decision / dead-end / hypothesis / plan / fact。这些条目以 JSONL 与 Markdown 双镜像落盘到 ~/.dsh/storages/semantic-watcher/。每条写入都做长度守恒校验（写入字节数等于序列化字节数）并回读验证，校验失败只丢弃这一条、发事件告警，不会让账本静默损坏。
水位线记录每会话最后处理的消息，进程重启后自动幂等补扫，不永久漏账。
reasoning（思考块）与正式 text 分开观察、走独立账本：当模型长期只有思考没有正文产出时，以 reasoning 流为准，且思考内容绝不混入正式结论。
2. Flash 总结¶
条目由小模型异步总结产出。总结调用默认跟随触发消息的 provider/model，也可由 summaryProvider / summaryModel 显式指定。
队列上限 2 并发，单次 30 秒超时，畸形结果重试 1 次。队列溢出时丢最旧并记 gap。模型返回空数组算正常结果（只推进水位）；调用失败按「无可用模型路由 / 超时 / 草稿解析失败 / 空回复」分类落 gap，并作为独立原因出现在 timeline 上。
3. 新颖性判定¶
提供两种模式：
- 字符 3-gram MinHash 词法比对（Jaccard 阈值 0.8），再经 LLM schema 自检确认；
- embedding 余弦相似度（阈值 0.85），模型无 embedding 能力时自动回退。
4. 里程碑折叠¶
当账本条目超过阈值（recentN × 3）时，最旧一批交模型蒸馏成里程碑，原文移入归档。失败教训（dead-end）全量保留零丢失，未完成目标（open objectives）跨折叠保留。
5. 上下文注入（默认关闭）¶
在下一步前把「最近几条未完成目标（置顶）+ 里程碑 + 最近 N 条有推进意义的结论 + 最近几条死胡同」注入上下文。目标与死胡同默认各只取最近 3 条（injectionObjectiveLimit / injectionDeadEndLimit），更早的只报数量。
结论区只收 finding/decision/fact 等有进展的条目，计划类只在目标区展示，复读与已被取代的条目不注入。预算紧张时依次压正文、剔旧结论、收缩目标与死胡同、把摘要压成短句，最后实在放不下才降级为「最新要点」单行，不再整块跳过。水位落后时明确标注 latestSummarized:false。
6. 三级语义停滞响应¶
| 级别 | 触发 | 动作 |
|---|---|---|
| stall-1 | 连续若干步只有重复、没有新结论（或墙钟旁路：连续 3 个无正文/无产物步骤且跨度 ≥ 5 分钟） | 注入警示 |
| stall-2 | 重复继续累积 | 请求 L2 拒读类工具（denyToolCategory，默认关闭） |
| stall-3 | 进一步恶化 | 请求 L2 硬终止本步（rejectStep），并写交接账本与续跑种子（默认关闭） |
纯字面重复（措辞一模一样）只记账不升级，只有语义重复才推进停滞级别；真人发来新消息归零所有状态（系统/插件注入的消息不算）。
7. 生命周期管理¶
worker 每分钟心跳；会话结束或最后事件后 10 分钟无新事件，自动清理会话状态与心跳；归档按保留期定期清扫。
8. 静默中断识别与原窗口主动续跑（v0.3.0）¶
当回合被步级上限（blocked）、输出长度上限（max-tokens）或运行时错误（error）打断、且未形成面向用户的结论时，watcher 检测该「静默中断」并按设置决定是否在原窗口主动发送续跑指令（<silent-resume> 模板：先汇报结论与断点，再继续推进）。
动作模式四档（silentAbortAction，互斥穷尽）：
| 档位 | 行为 |
|---|---|
off |
完全不检测（连 detected 事件都不落） |
notify（默认） |
检测 + 落事件 + timeline 干预通道 + agent-notify 告警，不发消息（fail-safe：不会自动向会话发送任何内容） |
followup |
notify 全部动作 + 冷却到点后向原窗口 agent.followup() 发送续跑指令 |
goal-resume |
优先对 blocked/paused 的 goal 调 goals.resume()；无 goal 或 resume 抛错（含轮次用尽）回退 followup，仍不行回退 notify |
安全闸包括：冷却 G2（回合结束后等 cooldownMs，默认 15 秒；窗内出现新 turn 或真人消息即放弃，真人永远优先）、预算 G1（每会话自动续跑 ≤ maxAutoResumePerSession 默认 3 次，跨冷却不重置、真人接管才清零）、进展 G5（续跑新回合须达 progressMinSteps 默认 3 步或 ≥1 次工具调用）、错误码排除 D4（errorNoRetryCodes 默认 401/403/signed-out，命中只告警不重试）、goal 让位 G4（goal active+armed 时不介入）、服务降级 G6（agents/goals/agent-notify 缺失或抛错一律只落事件与告警，绝不抛穿主流程）。
9. 右侧栏干预时间线（timeline，v0.2.0）¶
DSH Web 右侧栏新增「语义监视」选项卡，把一次会话的治理痕迹合并成一条纵向时间线，统一归并五类来源并按时间倒序：
| source | 含义 |
|---|---|
intervention |
stall-2/3 的 L2 干预受理结果（deny-read / reject-step），醒目卡片 |
watcher-event |
其余 semantic-watcher/* 事件（stall、heartbeat、handoff-written 等） |
milestone |
里程碑折叠产出 |
gap |
总结跳过（无可用模型路由 / 超时 / 草稿解析失败 / 空回复，带原因徽标；无 grade 时显示「原因未知」） |
journey |
语义旅程条目（finding/decision/…，含重复标记） |
observation |
每步 reasoning/text/产物观察（默认折叠，可展开） |
干预卡片展示动作、所在 turn/step、是否被 step-governor 受理、TTL 与解除步（expiresAtStep），字段全部取自 L2 真实返回，缺失即省略。
宿主侧新增两个只读路由：
GET /plugins/derive-watcher/timeline/sessionsGET /plugins/derive-watcher/timeline?sessionId=<sid>&limit=<n>（limit默认 200、上限 1000；缺sessionId返 400、无账本返 404）
安装¶
dsh plugin --profile <你的profile> add github:JiewiW/dsh-derive-watcher#v0.3.1
零第三方运行时依赖。账本默认落在 ~/.dsh/storages/semantic-watcher/（设置项 storagePath 可改）。
设置¶
常用默认值：
| 键 | 默认 | 说明 |
|---|---|---|
enableJourney |
true |
旅程账本总开关 |
enableInjection |
false |
上下文注入总开关（首发默认关） |
enableStall2Deny / enableStall3Reject |
false / false |
stall-2/3 与 L2 的联动（首发默认关，L2 不在线时 fail-open） |
stall1Steps / stall2Steps / stall3Steps |
3 / 6 / 10 | 语义停滞分级阈值（保存时校验严格递增，倒挂拒绝） |
stallWatchSteps / stallWatchWindowSec |
3 / 300 | 墙钟旁路：连续无产出步骤数 K 与跨度 T（秒） |
injectionTokenBudget |
1200（允许 800–1500） | 注入 token 预算 |
recentN |
8 | 最近结论窗口，也是折叠阈值基准 |
injectionObjectiveLimit |
3（允许 1–10） | 目标区最多注入几条未完成目标（最近优先） |
injectionDeadEndLimit |
3（允许 1–10） | 死胡同区最多注入几条（最近优先） |
noveltyMode |
schema-selfcheck |
另可选 embedding / both / semantic-only |
lexicalThreshold |
0.8（允许 0.1–0.95） | 词法重复判定阈值 |
enableLexicalStallCount |
false |
词法重复计入停滞升级（改进①：code 派生 lexical-stall-2） |
lexicalStallSteps |
0（允许 0–50，0=关） | 独立词法复读警告阈值，>0 时连续 N 条词法重复发 lexical-stall 事件（仅提示，不升级） |
maxConcurrency |
1（上限 2） | 总结并发闸 |
sessionTtlMinutes |
10 | 会话无新事件后的存活时间 |
retentionDays / ledgerRetentionDays |
30 / 0 | 归档保留天数；主账本保留天数（0 = 不清主账本） |
escapeClosingTags |
true |
闭标签写入前转写、读取还原 |
联动约束：enableInjection 要求 enableJourney；enableStall2Deny / enableStall3Reject 要求 enableInjection。
事件¶
12 个事件（semantic-watcher/* 前缀）：
stall · intervention（v0.2.0 新增） · store-corruption · injection-skipped · execution-unavailable · lexical-repeat · lexical-stall（改进⑤ 新增） · summarizer-degraded · handoff-written · heartbeat · fold-milestone · retention-cleaned
intervention 只在 L2 调用成功返回时发出，必带 action（deny-read / reject-step）、accepted、code、level；ttlSteps / expiresAtStep / pending 仅在 L2 返回值真实存在时才写入。L2 调用失败仍走 execution-unavailable，不发 intervention。
适用场景与注意¶
- 适合谁：需要长期跟踪会话语义进展、希望对语义停滞进行分级治理的开发者。
- 权限：插件以当前 dsh 进程权限运行；安装前建议检查源码与许可证。
- 生态背景：DSH 社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。
短结尾¶
dsh-derive-watcher 通过语义旅程账本、flash 总结、新颖性判定、里程碑折叠、上下文注入、三级停滞响应与右侧栏干预时间线，为长链任务提供持续的语义观察与治理能力。需要治理联动时，应配合 L2 插件 step-governor 使用。更多细节与源码见 GitHub。
