Skip to content

使用情况配置 ​

usage 段只读全局层 ~/.toolkitrc.json;项目层与本地层误写只告警、不生效。

为什么只允许全局层 ​

技能使用情况会在本机持续写文件。若允许项目层配置,克隆一个仓库就可能被动开启采集。因此 usage 只认全局层;项目层 / 本地层出现同名段时,toolkit 在 stderr 告警并忽略。

完整示例 ​

json
{
  "usage": {
    "enabled": false,
    "channel": "hook",
    "agents": { "trae": false, "claude": false },
    "sources": { "firstParty": false, "thirdParty": false, "unmanaged": false },
    "skills": { "mode": "none", "include": [], "exclude": [] },
    "capture": { "triggerPrompt": false, "skillArgs": false, "outcome": false },
    "storage": {
      "dir": "",
      "rotation": "monthly",
      "retentionDays": 180,
      "maxFileBytes": 8388608
    },
    "upload": {
      "enabled": false,
      "protocol": "webhook",
      "endpoint": "",
      "headers": {},
      "allowInsecure": false,
      "batchSize": 100
    }
  }
}

字段说明 ​

字段类型默认说明
enabledbooleanfalse总开关;关闭时 Hook 与规则上报都不写入
channelstringhook采集通道:rule(全局规则上报)/ hook(Agent Hook);只认一条,未写按 hook 兼容存量配置
agentsobject{}Agent 开关,键为适配器 id(trae / claude / cursor / codex / copilot),未出现即关闭
sources.firstPartybooleanfalsetoolkit 一方技能(fxri-*)
sources.thirdPartybooleanfalsetoolkit 分发的第三方技能
sources.unmanagedbooleanfalseAgent 目录里存在、但不由 toolkit 管理的技能
skills.modestringnonenone / all / include / exclude;include 空列表等同 none
skills.includestring[][]include 模式的白名单
skills.excludestring[][]exclude 模式的黑名单
capture.triggerPromptbooleanfalse采集触发词;开启后截断 200 字并脱敏
capture.skillArgsbooleanfalse采集技能参数;开启后截断 500 字并脱敏
capture.outcomebooleanfalse采集执行结果与耗时
storage.dirstring空数据目录;空串用默认 ~/.toolkit/usage
storage.rotationstringmonthlymonthly / size / none
storage.retentionDaysnumber180usage data purge 的默认保留期
storage.maxFileBytesnumber8388608size 轮转的单文件上限
upload.enabledbooleanfalse上传总开关;默认关闭
upload.protocolstringwebhookwebhook / otlp-http / file
upload.endpointstring空上传端点或导出路径
upload.headersobject{}附加请求头
upload.allowInsecurebooleanfalse允许非 localhost 的 HTTP 端点
upload.batchSizenumber100单批事件数

数据目录优先级 ​

--dir > FX_TOOLKIT_USAGE_DIR > storage.dir > ~/.toolkit/usage。

相对路径按 process.cwd() 解析;~ 展开为当前用户家目录。

过滤顺序 ​

总开关 → 通道 → Agent 开关 → 来源开关 → 技能模式 → 字段开关。任一步不通过就不落盘;字段开关只影响对应字段,不影响事件本身的写入。

  • 通道只决定「哪条路径能写」:rule 时 Hook 不写入、hook 时规则上报不写入,避免同一调用被记两次。
  • 规则上报(usage record)只统计 toolkit 管理的技能,且 Agent 维度按 rule 放行、不受 agents 开关限制;sources.unmanaged 对规则路径不生效。
  • 两者切换用 toolkit usage config channel rule|hook,不会自动清理另一侧配置。

上报与消费(规则通道) ​

  • usage record 只把批次写入 <数据目录>/state/queue/<批次>.json,随后派生后台 worker 消费;任何 usage 命令启动时也会顺带消费积压队列。
  • 消费时先写基础事件(技能名、次数、会话、时间),再按 capture.* 与反查结果补触发词、参数、结果、耗时;反查不到就留空,不伪造。
  • capture.* 只决定「允许采集哪些字段」,实际有没有值取决于会话记录能否反查;各 Agent 的可读条件与补救方式见 字段可得性。
  • 队列条目处理完即删;事件按 eventId 去重,worker 重复拉起不会重复计数。

相关页面 ​

MIT 开源协议