dsh-analytics

English | 中文

面向 DeepSeek Harness 的 Agent FinOps / token 分析：从会话事件采集用量写入本地 SQLite 账本，用时间感知的定价表（绝不硬编码进逻辑）计费，并通过服务、agent 工具与 JSON API 路由查询。

这是设计中的 v1 范围：总览 + 会话下钻 + 成本引擎 + 缓存分析，并按 dsh-plugin 生态的 bundle 打包方式发布（带 dsh.bundle 的 npm 包 → cordis.patch.yml）。

安装

dsh plugin --profile web add dsh-analytics

从 git 安装（需要 prepare 构建授权）：

dsh plugin --profile web add github:you/dsh-analytics#<sha>

从本地检出安装：

dsh plugin --profile web add /path/to/dsh-analytics

本地开发时挂载源码 overlay：

dsh --profile web --patch ./cordis.yml

配置

插件行的 config（形状见 cordis.yml）：

| Key | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | dbPath | string | —（必填） | SQLite 数据库文件；缺失的目录会自动创建。 | | currency | string | — | 摘要中优先排序的首选币种（每行自带币种）。 | | peakHours | [startHour, endHour][] | [[1,4],[6,10]] | UTC 半开区间高峰窗口；其余小时为低谷。 | | pricing | PricingRow[] | 随附 DeepSeek V4 表 | 替换随附默认值的定价行。 | | pricingFile | string（绝对路径） | — | PricingRow[] 的 JSON 文件；与 pricing 互斥。 | | budget.daily | number | — | 以 budget.currency 计的每日支出上限（UTC 日）。 | | budget.monthly | number | — | 每月上限；总览还会预测月末支出。 | | budget.currency | string | currency 或 USD | 限额计量币种。 | | tools | boolean | true | 注册 analytics_query agent 工具。 | | web | boolean | true | 在存在 ctx.webServer 时注册 /api/analytics/* JSON 路由。 |

定价：表是数据，不是代码

成本通过把每个请求与定价行匹配来计算：

interface PricingRow {
  provider: string          // request/header config provider
  model: string             // request/header config model
  region?: string           // optional discriminator
  priceType: 'peak' | 'off-peak' | 'flat'
  inputType: 'cache_hit' | 'cache_miss' | 'cache_write' | 'output'
  pricePerMillion: number   // per 1M tokens, in `currency`
  currency: string
  effectiveFrom: string     // ISO 8601, inclusive
  effectiveTo?: string      // ISO 8601, exclusive
}

匹配使用 model + timestamp + cache hit/miss + input/output，因此 T 时刻的请求始终按 T 时刻生效的行计费——之后改价永远不会改写历史。没有专用行时 cache_write 回退到 cache_miss。匹配行中 effectiveFrom 最新者胜出。

随附默认值遵循 DeepSeek V4 公告：2026-08-16T16:00:00Z 之前为统一费率，之后为高峰/低谷费率（低谷 = 高峰的 50%）。它们只是种子数据——提供 pricing 或 pricingFile 即可拥有整张表。无配置时仅在表为空时播种默认值，因此不带定价配置的重启绝不会覆盖已记录的价格。

采集内容

插件监听 session/event，并在启动时通过 ctx.sessionQuery 回放持久会话（未挂载该 seam 时仅实时）：

• assistant/message 用量 → 每个 (session, seq) 一行请求记录（去重、回放安全）
• request/header → provider / model / reasoning effort，用于定价
• tool/call + tool/result → 带错误标志的工具调用记录
• 会话头 → created-at、cwd、parent，用于分组

存储是本地 SQLite 数据库（dsh_analytics_requests、dsh_analytics_tool_calls、dsh_analytics_sessions、dsh_analytics_pricing）。数据不出本机；插件绝不调用 provider API。

服务：ctx.analytics

所有读取都是分离快照；服务绝不触碰会话存储或 agent loop：

await ctx.analytics.overview({ start, end })   // totals, cost, cache, reasoning, trend, byModel, bySession, budget
await ctx.analytics.session(sessionId)          // request rows, turn waterfall, tools, cache
await ctx.analytics.sessions({ start, end })    // per-session summaries
await ctx.analytics.models({ start, end })      // per-provider/model summaries
await ctx.analytics.tools({ start, end })       // per-tool calls/errors + step-attributed cost
await ctx.analytics.pricing()                   // the pricing table in force
await ctx.analytics.budget()                    // spend vs configured limits + projection

工具成本是步骤级归因：一次模型调用的成本在该步骤调用的所有工具间均摊，因此含多个工具的一步共享成本（绝不重复计算）。

Agent 工具：analytics_query

模型可以查询同样的数字：

analytics_query(query="overview", range_hours=24)
analytics_query(query="session", session_id="session-1")
analytics_query(query="models" | "sessions" | "tools" | "pricing" | "budget", range_hours=24)

range_hours 限制截止当前的时间窗口（0 = 全部时间，默认 24）。

Web API

挂载 ctx.webServer 时，只读 JSON 路由注册在 /api/analytics/overview|sessions|models|tools|pricing|budget（带可选 ?hours= 查询参数）与 /api/analytics/session/<sessionId>。它们是未来仪表盘页面的数据源。

浏览器仪表盘

同样的路由驱动一个由插件在 /analytics 提供的自包含仪表盘（在浏览器打开 harness web 服务器 URL，或在挂载 ctx.webServer 的 headless profile 中打开 http://127.0.0.1:<port>/analytics）。它是打包在包内（web/）的零构建原生 JS 应用：

• 总览 — KPI 卡片（成本、token、缓存命中率、reasoning 占比）、token/成本趋势、构成、按模型成本、会话、预算
• 会话 — 带下钻的列表：轮次瀑布、累积上下文图、工具、缓存
• Token 流 / 模型 / 成本 / 定价 — 分桶趋势、按模型聚合、按工具步骤归因、生效中的定价表

范围选择器（6h/24h/7d/30d/全部）作用于每个页面；harness 客户端内的 shell 导航集成是后续工作（harness 客户端目前没有空闲插件页槽）。

外壳内入口（web profile）

包还附带一个浏览器客户端 bundle（dsh.client → exports["./client"]，按 harness module-loader 契约构建）。在 web profile 中注册两个入口：

• 侧栏底部 Settings 旁的一个 Token Analytics 操作，打开全屏应用内面板，提供与 /analytics 相同的六个页面（Overview / Sessions / Token Flow / Models / Cost / Pricing，带范围选择器与刷新）；
• 会话头中的一个按会话 Analytics 操作，打开任务成本浮层（成本、token、缓存命中率、轮次瀑布、工具归因，以及完整仪表盘链接）。

两者读取同一组只读 JSON 路由，因此需要挂载插件的 host 侧（及其 web 路由）。无需 harness 客户端 shell 变更：侧栏入口使用 shell 现有的 sidebar.footer.action 槽位。

开发

pnpm install
pnpm test
pnpm lint
pnpm build
pnpm doctor

路线图

• harness 客户端 shell 内的 Analytics 入口（左栏集成；客户端目前没有空闲插件页槽，因此仪表盘暂位于 /analytics）
• Skill / 子 agent ROI 与 reasoning-effort 效率
• 基于预算信号的成本异常告警

许可证

MIT