前言¶

DeepSeek Harness（以下簡稱 dsh）是 DeepSeek 開源的 Agent 運行時，核心理念是「一切皆插件」：模型適配、工具、會話日誌、界面都可以按插件裝卸。日常用它跑任務之後，會話事件會落在本機日誌裏。日誌本身能回答「剛纔做了什麼」，但很難直接回答另一類問題：哪些會話最貴、爲什麼突然開始重試、夜裏到底跑了多少、是哪一次任務把成本拉高的。

dsh-whale-report 就是爲這類問題準備的社區插件。它從會話事件日誌裏聚合出日報、週報、月報、年報或任意區間報告，定位是隻讀的用量與覆盤工具，不改寫任何歷史會話。社區插件目錄把它歸在「工具與能力」，產品名是「深跡 · DeepTrace」，目錄簡介裏也叫「鯨魚記事本」。需要說明的是：DeepSeek Harness 官方倉庫在 deepseek-ai/deepseek-harness；本文介紹的插件來自社區維護者 SenmuuuuW，收錄在獨立站點 DeepSeek Harness 插件庫，該目錄與 DeepSeek / 幻方沒有官方從屬關係，不能當成官方應用商店。

當前倉庫版本爲 0.4.0，主要語言是 TypeScript，許可證爲 MIT。GitHub 倉庫頁面截至 2026-08-17 顯示 20 star；社區目錄頁仍顯示 9 star，以後者爲目錄快照，星標以倉庫頁面爲準。

這是什麼¶

一句話定位：dsh-whale-report 讀取 dsh 的會話事件日誌，用本地確定性代碼生成可復算的用量報告。

它要解決的不是「把日誌再展示一遍」，而是把 session、token、費用、工具調用、風險信號聚合成一份能對照的報告。維護者在 README 裏寫得很明確：統計和洞察不靠再調一個模型來點評你的數據，而是基於會話事件、確定性聚合和顯式規則；同一份輸入應對應同一份結論。報告生成本身標註爲本地確定性路徑，不消耗模型 token。

數據走官方接縫（ctx.sessionQuery 與獨立 storage domain）。卸載插件後，裝配圖裏的掛載會摘除；統計還會排除插件自身的 whale/* 事件，避免把「生成報告」記進用量裏。

核心功能¶

倉庫 README 與架構說明把能力拆成幾塊，下面按已經交叉覈對過的內容說明。

報告週期¶

面板和聊天工具共用同一套預設：

自然週期和滾動 24h 是分開的。周、月、年按日曆對齊；24h 從任意時刻往回滾 24 小時。週期 key 帶 day- / 24h- / wk- / mo- / yr- 前綴，上一週期的對比基線不會串到另一種口徑上。

統計口徑¶

報告會彙總這些已經寫進 README 的指標：

1. 費用：按 DeepSeek 官方定價頁取即時價，緩存 6 小時，抓取失敗則用內置價兜底；按模型和按會話分賬。0.4.0 起還能從請求頭裏識別 provider（例如 opencode-go 訂閱流量），模型鍵帶 provider 前綴，識別不到時回退官方 DeepSeek 價。
2. Token：input / output / cache read / reasoning，按模型拆開。
3. 會話：會話數、回合數、事件數、活躍天數、最忙日。
4. 活躍分佈：24 小時分佈、半小時分佈、按天序列；另有夜貓指數（0–6 點事件佔比）。
5. 工具調用：總量和明細，按工具族歸類。
6. 重試風暴：同一命令連續重複不少於 3 次，並附錯誤摘要樣本。
7. 危險操作：紅級（不可逆破壞）和黃級（需留意）分開；只匹配命令首行，並剝離引號段，降低 heredoc 或源碼文件名誤報。
8. 密鑰掃描：6 類常見密鑰模式的存在性檢測，只報有無，不把原文寫進報告或導出。
9. 會話鑽取：按費用排序的會話軌跡，含成本、重試、危險信號和模型 token 歸因；可複製 Session ID。
10. 對比基線：每個週期自動落庫，報告帶「較上週期」的漲跌（費用、會話、緩存命中率等）。
11. 平臺餘額：模型平臺即時餘額，DeepSeek 已實現；密鑰只在本機服務端讀取，不進瀏覽器、不進報告、不進導出。

確定性洞察¶

洞察引擎當前是 8 條規則，不是模型自由發揮。README 列出的類別是：深夜消耗、重試風暴、緩存命中率變化、致命級操作、需留意操作、會話碎片化、疑似密鑰、費用趨勢。每條都帶閾值、歸因和估算口徑。

另外還有一塊「協作覆盤」（Collaboration Review）：觀察人機協作裏的需求漂移、遲到約束、上下文碎片化，最多 3 條；樣本不足就不展示。文檔強調語氣是找摩擦、給可嘗試的優化，不評價人格，也不把技術 retry 歸因爲溝通問題。

面板上的 Whale Note（鯨評）和表情狀態，走的是同一套確定性觸發規則，源碼在 src/whale-notes.ts。

只讀與導出¶

隱私邊界是這條插件反覆強調的一點：

• 只讀，不改寫任何 session 歷史。
• 修復建議只輸出方案和命令模板，不自動執行。
• Secret Scan 只記錄模式標籤、時間和來源，報告與導出裏都不出現 secret 原文。
• HTTP API 只服務本機 loopback，並帶同源標記。

導出有幾條路徑：面板內的完整報告視圖、主報告 PNG、單獨的會話軌跡 PNG、可打印 HTML，以及用瀏覽器打印對話框另存 PDF（A4 排版，與面板同源）。主報告 PNG 不含會話軌跡和索引；軌跡圖是追查用的另一份導出。

安裝與啓用¶

插件聲明的客戶端平臺是 web，需要已經能跑 dsh web 的環境。package.json 裏的 Node 約束是 ^22.19.0 || >=24.0.0，和 DeepSeek Harness 官方開發文檔的要求一致。

社區目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端裏運行即可：

dsh plugin add github:SenmuuuuW/dsh-whale-report

倉庫 README 針對 web profile 寫的是更完整的一條（插件本身只注入 web 端）：

dsh plugin --profile web add "github:SenmuuuuW/dsh-whale-report"
# 重啓 dsh web 使宿主代碼生效；客戶端 bundle 隨插件自動更新

目錄頁和倉庫都提醒：如需可復現安裝，應固定 commit 哈希，不要只釘倉庫名。寫法是在 GitHub 源後面加上哈希，例如：

dsh plugin add github:SenmuuuuW/dsh-whale-report#<commit>

把 <commit> 換成倉庫裏實際的提交哈希。第一次從 GitHub 安裝時，dsh 可能會提示允許構建腳本（allowBuilds），按終端提示確認後再重試即可。

裝好之後有兩個入口：

1. 面板（主入口）：如果同時裝了 DSH-better-sidebar，在「+」菜單裏打開「深跡」Tab；沒裝側邊欄時，右下角會有懸浮按鈕兜底。
2. 對話：直接說「給我一份週報」，Agent 會調用 whale_report 工具，輸出 markdown 報告。

典型用法¶

在對話裏要一份報告¶

whale_report 的預設枚舉是 daily、24h、weekly、monthly、yearly、custom。自定義區間需要 ISO 日期，例如 2026-08-01。工具描述裏寫明：用戶說「給我一份週報」「這個月我幹了啥」「年報」時就該調用它；拿到結果後把 markdown 原文交給用戶，不要編數字。

自定義區間的參數形態如下：

• preset：custom
• from：起始時間，例如 2026-08-01
• to：結束時間，例如 2026-08-14；缺省爲當前時刻
• to 必須晚於 from，否則工具會報區間無效

CHANGELOG 0.4.0 還記了一件實現細節：whale_report 不再向會話日誌寫入 whale/report 自定義事件。原因是核心 harness 不識別插件事件，寫入會導致舊版本拒絕加載整段會話歷史。報告數據改由插件自己的週期統計表持久化。

不裝插件，先用 CLI 看本機日誌¶

倉庫提供了一條免安裝路徑，直接讀本機會話存檔 ~/.dsh/sessions/*/session.jsonl.zstd，和插件共用同一套報告引擎：

pnpm install && pnpm build
pnpm report                  # 週報（最近 7 天）
pnpm report -- --daily       # 或 --monthly / --yearly / --all
pnpm report -- --from 2026-08-01 --to 2026-08-14

適合想先確認本機是否已有足夠會話日誌、再決定是否掛進 dsh web 的情況。

面板裏看完整報告¶

README 把一次閱讀路徑寫成三步：先看總覽（成本、調用、模型、異常），再看 Findings 和 Whale Note 指出的問題，最後用 Session Drilldown 追到具體會話。概覽對同一預設有約 5 分鐘的新鮮度窗口，過期會原地重算；自定義區間每次重新生成，不復用緩存。

適用場景與注意事項¶

比較適合這幾類用法：

1. 自己長期跑 dsh web，想按自然日 / 自然周覈對 token 和費用。
2. 需要把「重試風暴、危險命令、疑似密鑰」從日誌裏抽成條目，而不是再翻一遍 jsonl。
3. 團隊內部做協作覆盤時，只想看需求漂移、遲到約束這類摩擦信號，不想讓另一個模型對工作方式做人格評價。

當前倉庫自己列出的邊界也要看清楚：

• 報告可以複製 Session ID，但還不能一鍵跳回原會話，要等官方 client API 明確。
• 歷史對比目前是「較上一週期」，沒有跨多個週期的趨勢曲線。
• 費用是按官方定價頁估算的，最終以平臺賬單爲準。
• 客戶端平臺是 web；終端 TUI 場景不在這份插件的聲明範圍裏。
• 架構文檔仍有部分段落標註與 v0.2.x 同步，閱讀源碼時以 package.json 的 0.4.0 和 CHANGELOG 爲準。例如預算護欄已在 0.2.0 整條移除，不要按更早的介紹去找每週預算設置。

安裝前還有一條社區目錄和官方生態都會強調的約束：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。它能讀取你的會話日誌，餘額探測還會在本機服務端讀取憑證文件。安裝前應檢查源代碼倉庫和許可證；不信任的來源不要裝，需要可復現環境時固定 commit。工具審批並不能把第三方插件放進沙箱。

小結¶

dsh-whale-report 做的事情比較剋制：把已經發生的會話事件聚合成可復算的報告，告訴你錢花在哪、時間去哪、哪些命令值得回看。它不是日誌瀏覽器，也不會改寫歷史。對已經在用 DeepSeek Harness web 端、並且開始在意用量和風險信號的人，可以按目錄頁的命令裝上，先要一份週報看看本機數據是否對得上。

目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-whale-report/

GitHub：https://github.com/SenmuuuuW/dsh-whale-report