前言¶
使用 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
