Skip to content

新增跨会话用量统计接口 /v1/usage/stats - #209

Merged
xiaozhou26 merged 3 commits into
mainfrom
feat/usage-stats
Nov 15, 2026
Merged

xiaozhou26 merged 3 commits into
mainfrom
feat/usage-stats

Conversation

@xiaozhou26

Copy link
Copy Markdown
Collaborator

Closes #208

内容

  • /v1/health 增加 capabilities.usage_stats。
  • 新增 GET /v1/usage/stats?days=N&tz=IANA:汇总所有工作区会话最近 N 天(默认 371,范围 1–1100)的用量,按 tz 分日(默认进程本地时区,非法时区返回 400)。返回总量、按天明细(含各模型)、按模型明细(含费用)、活跃天数、当前与最长连续活跃天数、最常用模型、最长会话。字段说明见 docs/liveagent-backend.md。

统计口径

  • input 即请求的完整输入,已包含缓存读写;cacheRead、cacheWrite 是其中的部分,total = input + output。与 kn /usage 卡片、usage.updated 一致。
  • 每条带 usage 的回复计一个 turn,按 SentAt 分日;缺 SentAt 时取之前最近一条有时间的消息,再退到会话创建/更新时间。
  • 子代理转录单独保存为会话,只统计这些会话里的回复,不再加父会话的 SubUsage,避免重复;只有旧版本没有子代理转录时才用 SubUsage。子代理用量计入父会话。
  • 分支与历史复制会原样拷贝消息:按消息 id 去重,先创建的会话计入。
  • 没有逐条 usage 的旧会话,按元数据合计计入最后活动那天,不计 turn。
  • 费用:kn /usage 卡片的计价逻辑抽到 config.UsageCost 共用;订阅计费的 provider 不计价;没有任何可计价用量时为 null。

性能与并发

  • 按会话文件缓存解析结果(键为路径 + 大小 + 修改时间),只保留数字,逐行读取。
  • 不获取会话锁和目录文件锁,不会阻塞正在运行的回合。会话文件总是整体改名替换,读到的是完整的旧文件或新文件。
  • Windows 上以 FILE_SHARE_DELETE 打开会话文件,统计读取期间回合保存(改名覆盖)不会失败。

测试

  • go test ./internal/session ./internal/backend:跨时区分日、days 范围、缺 SentAt 的时间回退、连续天数、子代理不重复计、SubUsage 回退、分支去重、旧会话、缓存失效、HTTP 参数校验、费用 number/null、订阅 provider 不计价。
  • TestUsageStatsReaderDoesNotBlockSaves 仅在 Windows 上运行(本地 macOS 跳过);GOOS=windows go vet 与 go test -c 通过。
  • go run ./cmd/k-brain-vet ./...(UI 锁分析)通过。
  • 用合成会话数据手动运行后端验证过返回内容。

已知限制

  • 没有落成消息的模型调用(压缩、审阅、失败请求)计入会话元数据合计,但不在逐条统计里,因此统计值可能略低于会话合计。
  • 运行中的子代理在转录保存(结束)后才计入。

GET /v1/usage/stats?days=N&tz=IANA 汇总所有工作区会话的 token 用量:按天、按模型、
总计、连续天数、最长会话与费用;/v1/health 增加 capabilities.usage_stats: 1。

- input 沿用 ai.Usage.PromptTokens(含缓存读写),cacheRead/cacheWrite 为其子集,
  total = input + output,与 UsageSummary 和 /usage 卡片一致。
- 回复按 sent_at 分日,缺失时取前一条消息时间,再退回会话创建时间;消息无用量的旧会话
  把元数据合计记在最后活动日。
- 子代理转录会话与父会话 SubUsage 只计一次;分支/复制的同 id 回复去重。
- 每个会话文件的用量条目按路径、大小、修改时间缓存,统计不获取会话锁。
- 费用逻辑抽到 config.UsageCost,kn 的 /usage 卡片与后端共用。
用量统计不持有会话锁读取会话文件。Windows 上 os.Open 不带 FILE_SHARE_DELETE,
统计读取期间回合保存会话的改名替换会失败(Access is denied)。改用 openShared
以 FILE_SHARE_READ|FILE_SHARE_WRITE|FILE_SHARE_DELETE 打开(做法同
permissions/readfile_windows.go),其他平台仍是 os.Open;补充 Windows 上持有
读取句柄时保存仍成功的测试。
Windows 上只要有句柄开着会话文件,MoveFileEx 替换就会失败,带 FILE_SHARE_DELETE
也一样,上一版的测试在 Windows CI 上因此失败。

- 用量统计以共享方式打开会话文件,从同一句柄取大小与修改时间后一次读完原始字节
  并立即关闭,再从内存解析;句柄只在读文件的那一下开着。
- 新增 renameRetry(同 permissions/store.go):会话文件替换与 SetCWD 的会话目录移动
  (及回滚)在 Windows 上重试约四秒,也能等过杀毒软件、索引服务对新文件的短暂占用。
- Windows 测试改为:持有共享句柄时在 goroutine 里保存,约 100ms 后关闭句柄,断言保存
  成功且下一次统计看到新的总量。
@xiaozhou26
xiaozhou26 merged commit 66a0e3f into main Nov 15, 2026
23 checks passed
@xiaozhou26
xiaozhou26 deleted the feat/usage-stats branch November 15, 2026 13:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

新增跨会话 token 用量统计接口

1 participant