一句话定位

把 DeepSeek Harness 的会话事件聚合成年/月/周/日报告，展示成本、工具健康、危险命令、协作模式，并给出只读的改进建议；所有报告都由本地确定性代码生成，0 额外模型 token。

核心能力

• 多周期报告：日报、24 小时滚动、周报、月报、年报，以及任意起止时间的自定义报告
• 成本估算：按官方峰谷价（北京 9-12、14-18 高峰，谷时 2:1）分段计算，含峰谷占比与「挪到谷时约省多少」提示
• 工具调用健康度：按工具族统计失败率，高频工具（≥30 次）标出健康级别与最不稳定项
• 危险命令分级：红级（删库 / rm -rf / fork 炸弹 / dd 写设备 / 关机重启 / 格式化）和黄级（force push / 硬重置 / 777 / curl|sh），只匹配命令首行，引号段剥离防误报
• 密钥扫描：6 类常见密钥模式的存在性检测，只标记有无，不保存命中原文
• 重试风暴识别：同一命令连续重复 ≥3 次视为重试风暴，附带错误摘要
• 协作复盘：观察人机协作模式（需求漂移 / 迟到约束 / 上下文碎片化），最多 3 条，样本不足不展示
• IMPROVE 建议：跨会话的只读改进建议（Repeated Tool Failure / Retry Workflow Waste / Peak Cost Opportunity），带证据和 VERIFY 基线→目标
• 会话钻取：按费用排序的 Top 20 会话，含模型 token 归因
• 实时计费：进行中会话 30 秒刷新 token 与费用，右上角峰谷徽标 + 双模型价目表
• 历史趋势：多周期曲线（成本 / 会话 / 缓存命中 / 夜间活跃），进行中周期标 LIVE，不与完整周期混比
• Provider 余额：DeepSeek 官方余额查询，API key 只在本机服务端使用，缓存 60 秒
• 三视图导出：Web / HTML / PDF / PNG 主报告 / PNG 会话轨迹，导出全程本地
• 报告历史：每次生成的报告保存到 whale 域，可在面板历史列表复用

技术实现

• 语言: TypeScript（服务端 + React 客户端），TSX 单文件浏览器 bundle
• 关键依赖: @deepseek-ai/cordis（宿主插件装配）、@deepseek-ai/dsh-tools（注册聊天工具）、@deepseek-ai/dsh-session-query（会话查询）、@deepseek-ai/dsh-storage-domain（whale 域持久化）、zod（schema 校验）
• 架构模式: cordis 三件套双端插件 —— 宿主 half src/index.ts 注入 tools + sessionQuery + storageDomain，注册 whale_report 聊天工具与 /whale/api HTTP 路由；客户端 half src/client/index.tsx 通过 window.__ModuleLoader__ 注册 React 面板，优先接入 better-sidebar（registerTab），无 sidebar 时悬浮球抽屉兜底
• 入口文件: 宿主端 src/index.ts（导出 name="whale-report-core"、inject=["tools","sessionQuery","storageDomain"]、apply），客户端 src/client/index.tsx（导出 name="whale-report-client"、apply）；npm 包提供 lib/index.js（宿主）+ lib/client.js（浏览器）双入口

适用场景

DSH 长期用户想了解自己的 Agent 到底干了什么、花了多少、有什么可改进的。比如想知道这周哪些 session 最贵、深夜跑的任务占多少成本、哪些工具频繁失败、有没有误删风险的操作。报告是数据新闻官式的，数字先说、事实直陈，不做主观评价；改进建议是只读的，不自动改任何 skill 或工作流。

前置依赖与兼容性

安装方式

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

配置项

本插件没有 DSH 域内的 Config 配置项 —— 所有行为由确定性规则 + 用户聊天时的工具参数控制；上述环境变量和主题仅在用户希望覆盖默认值时设置。

常见问题

Q: 装好后能立刻出第一份报告吗？

A: 能，但首次打开面板或调用聊天工具时会先读取本机会话日志并建索引（src/tools.ts:206-226）；启动 3 秒后会后台预热全部会话，再次生成报告 0.1-0.3 秒返回（src/tools.ts:206-226，README.md:189-191）。

Q: 数据来源是自己的还是云端？

A: 完全本地，只读。插件通过 ctx.sessionQuery 读取本机 DSH 会话存档，不写回任何会话历史，卸载即净（src/index.ts:26-34，README.md:206）。

Q: 报告里的费用是怎么算的？准吗？

A: 按官方峰谷价（北京 9-12/14-18 高峰、空闲 2:1）从 DeepSeek 定价页实时抓取，6 小时缓存，抓不到自动回退内置价；这是估算口径，以平台账单为准（src/pricing.ts:22-232，README.md:251）。

Q: 报告生成会调用模型吗？

A: 不会。所有统计、洞察、IMPROVE 建议都是本地确定性规则，生成报告 mode=local，input/output/cache/total token 全为 0；任何视图都不会因为打开报告而额外消耗模型额度（src/tools.ts:320-327，README.md:147）。

Q: 某个会话日志坏了会影响整份报告吗？

A: 不会。损坏会话被跳过并标记为 corrupt-log 或 read-failed，跳过数计入 partial 数据，markdown/HTML/面板三处都有 DATA PARTIAL 提示，被跳过会话不计入 sessions/subagentSessions 也不进 Improve 证据（src/tools.ts:182-198，README.md:117）。

Q: 卸载插件后数据会留下吗？

A: 不在 DSH 主数据里留下。插件把报告历史放在自己的 whale 域（reports / session_index / period_stats 三张表），卸载插件会随域一起清除；主会话历史插件从不动（src/state.ts:83-91，src/index.ts:31-33）。

Q: 报告支持哪几种周期？

A: 日报（今天 0:00 起）、24 小时滚动、周报（本周一 0:00 起）、月报（本月 1 日起）、年报（本年 1 月 1 日起）、自定义任意 from/to（ISO 格式）。自然周期 key 用 day- / 24h- / wk- / mo- / yr- 前缀隔离，互不串扰（src/report.ts:36-80，README.md:162-170）。

Q: 报告能导成什么格式？

A: 面板 Web 视图（含 IMPROVE 区）、HTML 可打印页、PDF（浏览器打印）、PNG 主图（不含 IMPROVE 区）、PNG 会话轨迹图（仅会话轨迹与会话索引）；导出全程本地完成（README.md:174-178，docs/ARCHITECTURE.md）。

上手难度

入门 — 安装后直接打开面板或对话里说"给我一份周报"就能用；要改高级行为只需调整三个环境变量。

已知问题与限制

• 报告提供 Session ID 复制，但尚未实现"一键跳回原会话"（待官方 client API 明确），README.md:250
• 费用按官方峰谷价分段估算，最终以平台账单为准，README.md:251
• IMPROVE 引擎为只读建议：v0.5 只落 DETECTED / DISMISSED 与 VERIFY 计划，Apply / self-healing 未实现（路线图下一步），README.md:252
• Repeated User Correction 标记为 EXPERIMENTAL：保守阈值 + 首条消息过滤（首条用户消息不计入纠正），README.md:252
• PNG 主报告导出暂不含 IMPROVE 区（HTML / PDF / markdown / 面板已含），README.md:253
• 损坏会话的跳过数计入 partial，但错误原文与堆栈永不写入报告（fault isolation 设计），src/tools.ts:182-198
• 协作复盘在周/月/年报才易触发（样本门槛：会话 ≥5 且用户消息 ≥30），日报/24h 多数不展示，src/collaboration.ts:22-24
• 插件版本号 0.4.0，REPORT_SEM=6 / INDEX_VERSION=14，旧报告在结构变更时会自动重建，src/state.ts:11 / src/tools.ts:103

深迹 · DeepTrace

Your Agent, in numbers.

把 DSH 的 session、token、cost、tool call、风险与异常，
转成可以真正读懂的 Agent 报告。

---

Why DeepTrace

Agent 跑完之后，真正难回答的问题不是"它做了什么"，而是：

• 哪些 session 最贵？
• 为什么突然开始 retry？
• 哪些操作值得注意？
• 夜里到底跑了多少？
• 是哪次任务把成本拉高的？
• 这周有什么值得改的？

DeepTrace 不是 log viewer，也不是普通 dashboard——它把会话事件日志聚合成报告，让这些问题有答案。

The loop

一次报告，走完整个闭环；IMPROVE 的输出带 VERIFY 基线 → 目标，为后续自动回验（Apply / self-healing）预留。

Product

_{DeepTrace overview — hero, provider balance, cost, findings and the whale note.}

_{The full DeepTrace report — findings, collaboration review, activity, resources, risks and session trace.}

What it measures

Deterministic insights

DeepTrace 的统计与洞察不是让另一个 AI 随机点评你的数据。它基于：

• session event logs
• deterministic aggregation
• explicit rules
• reproducible report generation

10 条确定性 Finding 规则：深夜消耗、峰谷时段成本、重试风暴、缓存命中率变化、致命级操作、需留意操作、会话碎片化、疑似密钥、费用趋势、工具健康。每条都带阈值、归因与估算口径。

IMPROVE 引擎（v0.5）：Finding 回答"发生了什么"，Improve 回答"值不值得改、怎么改"。4 条确定性规则：

每条建议都带 evidence（metrics / affectedSessions / 置信度）与 verificationPlan（目标指标、基线 → 目标、窗口），排序 severity → score → occurrences → category；同一目标跨周期 id 稳定。全部本地确定性规则，0 额外 LLM token；Apply / self-healing 为后续版本预留（v0.5 只落 DETECTED / DISMISSED）。

协作复盘（COLLABORATION REVIEW）：观察人机协作模式——需求漂移 / 迟到约束 / 上下文碎片化，最多 3 条，样本不足不展示；语气是"找摩擦、给可尝试的优化"，不评价人格、不把技术 retry 归因为沟通问题。

鲸鱼娘的 Whale Note 也建立在同一套确定性触发规则上（src/whale-notes.ts，表情与文案同源）。

同一份数据 → 同一份结论。

报告本身由本地确定性代码生成——REPORT GENERATION · 0 TOKENS · LOCAL DETERMINISTIC，生成报告不消耗模型调用。

Privacy / read-only

• 只读：绝不改写任何 session 历史；统计排除 DeepTrace 自身的 whale/* 事件
• 不自动执行：修复建议只输出方案与命令模板，需要你亲自确认
• Secret Scan 不重印：只记录模式标签、时间与来源，报告与导出里都不出现 secret 原文
• 危险命令只存首行：引号段剥离，防止 grep 模式被误报
• 纠正信号只存类别与计数：Repeated User Correction 的匹配基于归一化白名单（去引号、数字、路径），绝不保存用户原句
• 损坏日志不泄错误：fault isolation 只披露会话 id 与粗分类原因（corrupt-log / read-failed），错误消息 / 堆栈从不进报告
• 本机围栏：API 只服务本机 loopback + 同源标记

Reports

自然周期与滚动 24h 的区别：周/月/年按日历对齐（周一、1 号、1 月 1 日），"24h" 则是任意时刻起算的滚动窗口。周期 key 前缀隔离（day- / 24h- / wk- / mo- / yr-），对比基线互不串扰。

Export

• Web report：面板内完整报告视图（含 IMPROVE 区与 DATA PARTIAL 提示）
• PNG 图片：canvas 按面板同款视觉绘制主报告（报告头 / 鲸评 / Findings / 活跃 / 模型工具 / 风险），不含会话轨迹、索引与 IMPROVE 区
• 会话轨迹：单独导出的 PNG，仅含会话轨迹 + 会话索引（追查专用）
• HTML：独立可打印 HTML 页，含 02 / IMPROVE 章节（severity 色标 + 证据 + VERIFY 行）与 DATA PARTIAL 横幅
• PDF：直接打印面板报告（A4 排版），浏览器打印对话框另存为 PDF——与面板逐像素一致

鲸鱼娘与页面形象在导出中使用真实素材（与面板显示一致）。

Installation

需要 DSH（DeepSeek Harness，web 端）环境。两种安装方式，注意区分：

① 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 工具与实时计费都需要通过方式 ① 注册；方式 ② 适合直接 import 报告引擎 / 用 CLI 生成报告的场景。

两个入口：

• 面板（主入口）：装了 better-sidebar 时在 "+" 菜单里打开「深迹」Tab；未装时右下角悬浮按钮兜底
• 对话：直接说"给我一份周报"——whale_report 工具输出 markdown 报告

数据走官方接缝（ctx.sessionQuery + storage domain），卸载即净。

立即体验（不用装插件）

pnpm install && pnpm build
pnpm report                  # 周报（最近 7 天）
pnpm report -- --daily       # 或 --monthly / --yearly / --all
pnpm report -- --from 2026-08-01 --to 2026-08-14   # 自定义区间

CLI 直接读本机会话存档（~/.dsh/sessions/*/session.jsonl.zstd），与插件共用同一个报告引擎。

Architecture

DSH session events
        ↓
aggregation / pricing / safety
（损坏会话跳过 → partial，缺失 ≠ 0）
        ↓
deterministic findings + improve rules
        ↓
DeepTrace report（DATA PARTIAL 披露 + VERIFY-ready 建议）
        ↓
Web / HTML / PDF / PNG

细节（数据流、存储结构、兼容性策略）见 docs/ARCHITECTURE.md。

Development

pnpm install
pnpm link-dsh   # 软链本地 harness 闭包（typecheck 需要）
pnpm typecheck
pnpm test       # 183 个单测：引擎 / 洞察 / Improve 规则 / fault isolation / 峰谷计价 / 导出
pnpm build      # tsc + tsdown（客户端单文件 bundle）

Status & limitations

当前边界，如实说明：

• 会话跳转：报告提供 Session ID 复制，尚未实现"一键跳回原会话"（待官方 client API 明确）
• 费用为估算：按官方峰谷价分段估算，以平台账单为准
• IMPROVE 为只读建议：v0.5 只落 DETECTED / DISMISSED 与 VERIFY 计划，Apply / self-healing 未实现（路线图下一步）；Repeated User Correction 标记 EXPERIMENTAL（保守阈值 + 首条消息过滤）
• PNG 主报告导出暂不含 IMPROVE 区（HTML / PDF / markdown / 面板已含）

License

MIT

---

Friends

• dsh-tianshu-tui — 超好看的 DSH 终端界面（TUI）
• DSH-better-sidebar — 很实用的 DSH 侧边栏工作台

---

DeepTrace is built to make Agent behavior inspectable, measurable, and easier to improve.

_{…and yes, the whale is watching. She reads every report first.}