Cavan-Ou/dsh-observation-journal

dsh-observation-journal

DeepSeek Harness 的零侵入运行事实遥测：每个会话自动写一张成绩单。

MIT
DSH
dsh-plugin

纯观察者插件（零工具注册、零 LLM 调用、零 agent 介入）。session 结束时自动把任务 / 模型档位 / 工具 / 失败 / 时长 / 状态写入人机共读的观测卡，附自动更新的统计区。

为什么需要它

失败有记录者（dsh-fail-logger），成功和运行事实没有。这是它的姊妹篇：记录发生了什么——不是"怎么解决"、不是"该记住什么"。无工具、无注入、无检索。harness 被动写，人/项目读。

它不是什么（边界说破）：
| 插件 | 记录 | 注入回 agent？ | 消费端 |
|---|---|---|---|
| 本插件 | 运行事实（遥测）| 永不 | 人/项目文件 |
| dsh-task-planner | 解决方案（"怎么解决"）| 是（recall）| agent 规划 |
| dsh-mneme / dsh-memento / dsh-memory | agent 记忆 | 是（检索）| agent 上下文 |
| dsh-fail-logger | 失败 | 经 skill | agent 技能加载 |

60 秒验证

dsh plugin --profile headless add    # 或复制仓库作本地 bundle
dsh --profile headless "跑任意小任务"
cat ~/.dsh/observations.md                     # 出现一行记录 + 统计区

输出长什么样

观测卡就是 UI。机器维护区段（人工编辑不受影响）+ 自动统计块：

| time | sid | task | model | dur | turns | tools | calls | fail | status |
|---|---|---|---|---|---|---|---|---|---|
| 2026-08-14T21:42 | abe96e0f | 阅读 specs/s11-1.md 任务书 | deepseek-v4-pro(max) | 1242 | 1 | read:80,bash:12,edit:9,todo_write:4 | 106 | 0 | completed |
| 2026-08-15T03:04 | 9c1f3a | run any small task | deepseek-v4-flash(max) | 25 | 1 | bash:4,grep:2,glob:1 | 7 | 0 | completed |

- 会话总数: 2
- 失败率: 0.0%（0/113）
- top 工具: read:80,bash:12,edit:9,todo_write:4,grep:2
- 平均时长(秒) 按模型: deepseek-v4-flash(max): 25, deepseek-v4-pro(max): 1242

raw sidecar（obsFile + '.jsonl'，追加写）：全保真——todo 规划轨迹（≤5）、工具全量计数、失败工具、完整模型 id、任务描述全文、归一化 task_hash。v2 LLM 洞察的素材，与主卡 TTL 解耦。

配置（patch config: 字段，全可选）

| 键 | 默认 | 说明 |
|---|---|---|
| obsFile | $DSH_HOME/observations.md | 主卡路径（可指项目级观测卡）|
| maxRows | 200 | 主卡最多保留行数（raw 不受限）|
| marker | OBS-JOURNAL | 区段 marker id，[A-Za-z0-9-] |
| redact | [] | 额外脱敏正则（叠加内置密钥表）|
| flushMs | 300 | turn/end 尾随防抖 |

环境变量：OBS_FILE（覆盖 obsFile）、OBS_REPLAY=（回放测试模式）。

可靠性

- 一行一 session，不做有损合并
- 任务标题转义 \| 与换行；密钥脱敏（fail-logger 同款表）
- 跨进程写锁 + 陈旧锁回收；dispose 兜底落盘无 turn/end 的会话
- 真实会话日志实测：5 个真实 .zstd 样本（含 2000+ 事件的 Pro 长提炼会话）14/14 回放用例，逐字段与独立重算交叉核对；21 会话全量回放验证人工区字节级不变

开发

node --check lib/index.js
node --test tests/test.mjs   # 需要 python3 + zstandard

License

MIT