前言¶
在 DSH（DeepSeek Harness）裏跑 Agent，會話結束後往往只剩一堆事件日誌。翻日誌能知道「做了什麼」，卻很難快速回答：哪些 session 最貴、爲什麼突然 retry、夜裏跑了多少、這周有什麼值得改。
常見做法是開 log viewer 或自建 dashboard，前者要人工篩，後者往往還要再調模型做「點評」，結論不穩定、也額外花 token。dsh-whale-report（深跡 DeepTrace）走另一條路：只讀本地 session event logs，用確定性聚合和顯式規則生成日報、週報、月報、年報或自定義區間報告，生成報告本身不消耗模型調用。
下面介紹這個插件的定位、能力與安裝用法。
這是什麼¶
dsh-whale-report 是 DSH 生態下的記憶類插件，維護者爲 SenmuuuuW，GitHub 倉庫 SenmuuuuW/dsh-whale-report（約 28 stars）。npm 包名 dsh-whale-report，當前版本 0.5.2，MIT 許可證。
一句話定位：Your Agent, in numbers——把 DSH 的 session、token、cost、tool call、風險與異常，轉成可讀的 Agent 報告。它不是 log viewer，也不是普通 dashboard；核心是確定性洞察與協作覆盤，只讀、不改寫歷史。
報告能回答什麼¶
一次報告按 SEE → NOTICE → TRACE → IMPROVE 走完閉環：
- SEE：總覽成本、調用、模型與異常
- NOTICE：10 條 Finding 規則 + Whale Note 標出值得看的問題
- TRACE：Session Drilldown 追到具體會話
- IMPROVE（v0.5）：只讀建議 + 證據 + VERIFY 計劃，爲後續自動回驗預留
支持的預設週期如下：
| 預設 | 區間 | 口徑 |
|---|---|---|
| 日報 | 今天 0:00 → 現在 | 自然日（Asia/Shanghai） |
| 24h | 過去滾動 24 小時 | 滾動窗口 |
| 週報 | 本週一 0:00 → 現在 | 自然周 |
| 月報 | 本月 1 日 0:00 → 現在 | 自然月 |
| 年報 | 本年 1 月 1 日 0:00 → 現在 | 自然年 |
| 自定義 | 任意 from / to | 顯式區間 |
核心能力¶
計量與成本¶
報告覆蓋費用、token、會話活躍度、工具調用、風險信號等維度，要點如下：
- Cost：按 DeepSeek 官方峯谷價分段計算（2026-08-17 起高峯 9–12 / 14–18 爲谷時 2 倍；定價頁即時抓取、6h 緩存、內置價兜底），按模型與會話分賬，帶峯谷佔比與「挪到谷時約省 ¥X」估算
- Live session：進行中會話 30s 刷新即時計費，右上角顯示峯/谷徽標
- Tokens：input / output / cache read / reasoning，按模型拆分
- Activity：小時級熱力圖（GitHub contribution 風格），含峯值時段、夜貓指數
- Tool calls & Tool health：調用明細與高頻工具（≥30 次）失敗率分級
- Retry bursts：同一命令連續重複 ≥3 次，附錯誤摘要樣本
- Dangerous operations：紅級（不可逆破壞）/ 黃級（需留意），僅匹配命令首行
- Secret scan：6 類常見密鑰模式存在性檢測，只報有無、不存原文
- Baseline & Trends：較上週期對比、多週期趨勢曲線；進行中週期標記 LIVE
- Provider balance：DeepSeek 平臺即時餘額（key 僅在本機服務端使用）
v0.5.0 起 usage accounting 口徑：total = input(miss) + cacheRead(hit) + output，reasoning 只作 output breakdown；費用 = miss×輸入價 + hit×緩存價 + output×輸出價。
確定性洞察，零額外 LLM token¶
統計與洞察不由另一個 AI 隨機點評，而基於 session event logs、確定性聚合、顯式規則與可復現的報告生成。同一份數據 → 同一份結論；報告生成標註爲 REPORT GENERATION · 0 TOKENS · LOCAL DETERMINISTIC。
10 條 Finding 規則：深夜消耗、峯谷時段成本、重試風暴、緩存命中率變化、致命級操作、需留意操作、會話碎片化、疑似密鑰、費用趨勢、工具健康。每條帶閾值、歸因與估算口徑。
4 條 IMPROVE 規則（v0.5，只讀、不自動改配置）：
| 規則 | 觸發條件（摘要） |
|---|---|
| Repeated Tool Failure | 工具失敗跨 ≥3 會話、失敗率 ≥8%、單一錯誤碼佔失敗 ≥40% |
| Retry / Workflow Waste | 同一歸一化命令在 ≥2 會話重複重試且伴隨失敗 |
| Repeated User Correction（EXPERIMENTAL） | 同類糾正跨 ≥2 會話（第 2+ 條用戶消息統計） |
| Peak Cost Opportunity | 高峯佔 ≥50% 且 ≥¥3，且有夜間批量負載證據 |
每條建議帶 evidence（metrics / affectedSessions / 置信度）與 verificationPlan（基線 → 目標、窗口）。v0.5 只落 DETECTED / DISMISSED；Apply / self-healing 爲後續版本預留。
另有 協作覆盤（COLLABORATION REVIEW）：觀察需求漂移、遲到約束、上下文碎片化，最多 3 條，樣本不足不展示。
只讀與安全邊界¶
- 絕不改寫 session 歷史；統計排除 DeepTrace 自身的
whale/*事件 - 修復建議只輸出方案與命令模板，需人工確認
- Secret Scan、危險命令、用戶糾正信號均不保存原文
- 損壞日誌優先只讀 salvage，無法恢復時僅披露會話 id 與粗分類原因
- API 只服務本機 loopback
導出¶
- Web 報告面板（含 IMPROVE 與 DATA PARTIAL 提示）
- PNG 主報告（不含會話軌跡與 IMPROVE 區）
- 會話軌跡單獨 PNG
- HTML（含 IMPROVE 章節）
- PDF（瀏覽器打印面板報告）
安裝與啓用¶
需要 DSH web 端環境。v0.5.0 針對 DSH 0.1.1-rc.2 驗證（peer 範圍 >=0.1.1-rc.2 <0.2.0）；升級 dsh 後重啓 web 實例即可。Node 要求 ^22.19.0 || >=24.0.0。
推薦：DSH 插件安裝（註冊進 dsh web，完整功能）：
dsh plugin --profile web add "github:SenmuuuuW/dsh-whale-report"
安裝後重啓 dsh web 使宿主代碼生效；客戶端 bundle 隨插件自動更新。
備選：npm 包安裝（僅依賴，不自動註冊插件）：
npm install dsh-whale-report
npm install 不會自動註冊爲 DSH 插件；Web UI、whale_report 工具與即時計費需用上面的插件安裝方式。npm 方式適合直接 import 報告引擎或用 CLI 生成報告。
插件以當前 dsh 進程權限運行，安裝前建議閱讀源碼與 MIT 許可證，確認只讀邊界符合你的安全要求。
典型用法¶
面板與對話¶
兩個入口：
- 面板：裝了 better-sidebar 時在「+」菜單打開「深跡」Tab；未裝時右下角懸浮按鈕兜底
- 對話：直接說「給我一份週報」——
whale_report工具輸出 markdown 報告
數據走官方接縫（ctx.sessionQuery + storage domain），卸載即淨。
CLI 本地體驗（無需裝插件）¶
克隆倉庫後可用 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 上跑 Agent、需要定期覆盤成本、工具健康、風險信號與協作摩擦的開發者；希望報告可復現、不額外花 LLM token 的團隊。
當前邊界（README 如實說明）：
- 會話跳轉：報告提供 Session ID 複製，尚未實現一鍵跳回原會話
- 費用爲估算：按官方峯谷價分段，以平臺賬單爲準
- IMPROVE 爲只讀建議：Apply / self-healing / 自動 Verify 閉環未實現
- PNG 主報告導出暫不含 IMPROVE 區（HTML / PDF / markdown / 面板已含）
DSH 社區目錄 SkillHub 是獨立站點，與 DeepSeek / 幻方無官方從屬關係；插件遵循 DSH「一切皆插件」的生態思路，非官方應用商店分發。
結尾¶
dsh-whale-report 把 Agent 行爲變成可檢視、可度量、可改進的數字報告：確定性規則替代隨機點評，只讀邊界保護歷史數據，六類週期覆蓋從日報到自定義區間。若你已在 DSH 上積累大量會話，值得裝一份做定期覆盤。
- 目錄頁：https://www.skillhub.cn/plugins/SenmuuuuW/dsh-whale-report
- GitHub：https://github.com/SenmuuuuW/dsh-whale-report
