Skip to content

事件 Schema ​

schemaVersion 当前为 1;新增字段只增不改,破坏性变更升版本并提供迁移命令。

字段 ​

字段类型必填说明
schemaVersionnumber是固定 1
eventIdstring是sha256: 前缀的稳定 ID
occurredAtstring是本地时区 ISO 时间
agentstring是适配器 id:trae / claude / cursor / codex / copilot / manual / rule(规则上报)
sessionIdstring是Agent 会话 id;规则通道按 --session、已知环境变量或日期兜底
toolUseIdstring否工具调用 id;缺失时按 2 秒窗口去重
projectstring否工作区路径
skillstring是技能名
skillVersionstring否技能真源版本
skillSourcestring是toolkit-first-party / toolkit-third-party / unmanaged / unknown
managedBystring是toolkit / external / unknown
triggerPromptstring否触发词,截断 200 字;规则通道由反查补齐
skillArgsstring否技能参数,截断 500 字;规则通道由反查补齐
outcomestring否success / failure / unknown;规则通道由反查补齐
durationMsnumber否工具调用耗时;规则通道由反查补齐
originAdapterstring是采集来源:trae-hooks / claude-hooks / transcript / manual / rule 等
toolkitVersionstring是写入时的 toolkit 版本

示例 ​

json
{
  "schemaVersion": 1,
  "eventId": "sha256:9f2c…",
  "occurredAt": "2026-11-06T10:12:33.123+08:00",
  "agent": "trae",
  "sessionId": "9b4c1f17-4cdb-444e-a372-77405e91b4b9",
  "toolUseId": "call_abc123",
  "project": "d:/Work/Dev-Space/fxri/0001.base/toolkit",
  "skill": "fxri-plan-task",
  "skillVersion": "1.9.16",
  "skillSource": "toolkit-first-party",
  "managedBy": "toolkit",
  "originAdapter": "trae-hooks",
  "toolkitVersion": "1.16.0"
}

去重键 ​

  • 首选:agent + sessionId + toolUseId 生成 eventId。
  • 跨适配器:sessionId + toolUseId 二次去重,只保留首条。
  • 规则通道:toolUseId 为 rule:<批次ID>:<批次内序号>,同一技能调用几次就生成几条,不互相去重。
  • 缺少 toolUseId:sessionId + skill + 2 秒窗口。

机器可读 schema 见 skill-usage-event.v1.json。

兼容策略 ​

  • 新增可选字段不升 schemaVersion。
  • 删除字段、改变字段含义或类型时升 schemaVersion,并提供 usage data import 迁移说明。
  • 统计与上传消费方须忽略未知字段,不因新增字段失败。

MIT 开源协议