Cavan-Ou/dsh-observation-journal

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

纯观察者插件（零工具注册、零 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。机器维护区段（人工编辑不受影响）+ 自动统计块：

<!-- OBS-JOURNAL:BEGIN -->
| 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 |
<!-- OBS-JOURNAL:END -->

<!-- OBS-JOURNAL:STATS -->
- 会话总数: 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
<!-- OBS-JOURNAL:STATS:END -->

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.jsonl>（回放测试模式）。

可靠性

• 一行一 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