前言¶
使用 DeepSeek Harness（DSH）跑智能体任务时，经常需要确认一些基本运行事实：这个会话执行了什么任务、使用了哪个 model tier、调用了哪些工具、发生了几次失败、运行了多久、最终状态是什么。
这些信息如果只散落在会话过程中，事后核对会比较麻烦。dsh-observation-journal 的做法是：在会话结束后，把这些运行事实写入一份人类可读的 journal，并自动维护统计区块。
这是什么¶
dsh-observation-journal 是一个 DSH 纯观察者插件。资料中明确写出它的边界：
- zero tools registered
- zero LLM calls
- zero agent involvement
它记录的是运行事实，包括：
- task
- model tier
- tools
- failures
- duration
- status
它不把记录注入 agent，也不参与 agent 规划或记忆召回。
仓库地址：
https://github.com/Cavan-Ou/dsh-observation-journal
许可证：
MIT
package.json 中声明的版本和运行环境为：
{
"version": "0.1.0",
"engines": {
"node": ">=20"
}
}
核心功能¶
会话结束后写入 journal¶
会话结束后，插件将单次会话的运行事实写入人类可读 journal。资料说明会话卡为 10-column rows，一个 session 一行，不做有损合并。
任务标题会进行转义：
- 转义
| - 转义换行
同时会基于内置 secret table 做 secrets redaction。
自动维护 marker 区块和 stats 区块¶
journal 中会维护两类区块：
- 带 marker 的 journal 区块
- auto-stats 区块
资料说明 marker section 可保留人工编辑内容。也就是说，自动写入区域和人工编辑区域可以分离。
生成 append-only raw sidecar¶
除 journal 外，插件还会生成 append-only raw sidecar。路径为：
obsFile + '.jsonl'
raw sidecar 中包含：
- todo planning trace（≤5）
- 完整工具计数
- 失败工具
- 完整 model id
- 完整 task 描述
- normalized task_hash
资料将其描述为 v2 material for LLM insight，并且 TTL-decoupled from the card。
写入可靠性¶
资料中列出的可靠性机制包括：
- 跨进程写锁
- stale lock reclaim
- dispose fallback 会 flush 没有 turn/end 的 sessions
安装与启用¶
先添加插件，再运行一个 DSH headless 任务，最后查看 journal。资料给出的安装命令使用占位参数：
dsh plugin --profile headless add <repo-or-pkg>
也可以将该仓库复制为 local bundle 使用。
接下来运行一个小型任务：
dsh --profile headless "run any small task"
然后查看默认观测文件：
cat ~/.dsh/observations.md
如果文件中出现了 journal row 和 stats section，说明插件已经写入运行事实。
配置项¶
以下配置项在资料中被列为可选：
obsFilemaxRowsmarkerredactflushMs
其中：
obsFile：journal 文件路径；raw sidecar 使用obsFile + '.jsonl'marker：journal 区块 markerredact：redaction 相关配置；资料说明任务标题会基于内置 secret table 做 secrets redaction
对于 maxRows 和 flushMs 的默认值与细节语义，已核实资料中没有给出，这里不展开。
环境变量¶
资料中确认了两个环境变量：
OBS_FILE：覆盖obsFileOBS_REPLAY=<session.jsonl>：用于重放真实 session 事件，适用于 test/CI mode
验证与测试¶
资料中声明已经使用真实 session logs 做过验证：
- 14/14 replay tests
- 5 个真实
.zstdfixtures - 其中一个为 2000+ event Pro long-synthesis session
- 21-session full replay 验证 human sections byte-identical
本地开发时可以运行：
node --check lib/index.js
node --test tests/test.mjs
其中 node --test tests/test.mjs 需要：
python3 + zstandard
适用场景与注意¶
适合以下场景：
- 需要给 DSH 会话留下可核对的运行记录
- 需要在一个人类可读文件中查看每次会话的任务、模型、工具、失败和状态
- 希望保留人工编辑区域，同时让自动统计区独立维护
- 需要在 test/CI 中重放真实 session 事件
需要注意的边界：
- 它不是 agent memory 插件
- 不注册工具
- 不调用 LLM
- 不注入 agent
- 不参与 agent 决策或召回
安装前仍建议检查源码与许可证。当前资料确认许可证为 MIT，package.json 要求：
node >=20
由于插件以当前 dsh 进程权限运行，启用前请确认你对该插件的来源、代码和写入路径有基本把握。
结尾¶
dsh-observation-journal 的价值在于把 DSH 会话的运行事实从临时过程里抽出来，写成一行一会话、可人工编辑、可统计、可重放的文件。它不改变 agent 行为，只留下可核对的记录。
本文资料未提供社区目录页 URL。GitHub 仓库地址为：
https://github.com/Cavan-Ou/dsh-observation-journal
