Skip to content

Agent 接入 ​

采集有两条通道,由 usage.channel 二选一:规则(默认,AI 每批工具调用后按全局规则执行 usage record, 不依赖任何 Agent 配置)与 Hook(Agent 命中事件时启动短进程,读 stdin、写一行记录后退出,无常驻进程、无轮询)。同一时刻只启用一条,避免同一调用被记两次。

两条通道怎么选 ​

对比项规则(channel=rule)Hook(channel=hook)
启用toolkit usage setup init --yes --preset recommended --channel rule,再把 toolkit rule compose --module usage 的输出复制进 Agent 全局规则toolkit usage setup init --yes --preset recommended --channel hook(或 usage setup hooks install + toolkit config set usage.enabled true)
依赖只需 Agent 能执行 CLI;与 Agent 配置、IDE 开关、沙箱策略无关依赖各 Agent 的 Hook 配置与执行环境;部分 Agent 还需 IDE 侧启用或桥接插件
自动性由 AI 按规则主动触发(我们自己发起的钩子),每批工具调用后合并一次;按调用次数逐条记录由 Agent 事件被动触发,可采集触发词、参数与结果,也能识别未托管技能
明细字段规则只传技能名;触发词 / 参数 / 结果 / 耗时由工具异步反查会话记录补齐来自 Hook 载荷,随事件一并到达
关闭删除全局规则段,或 toolkit usage config channel hook 切走toolkit usage setup hooks remove / toolkit usage setup uninstall
限制依赖 AI 遵守规则;反查依赖会话记录可读,读不到时字段留空但计数不受影响任一环节(配置、IDE 开关、沙箱)失效都会静默无记录,需 usage setup hooks status / usage data doctor 排查

字段可得性 ​

字段Hook 通道规则通道
技能名、次数、时间、会话必有必有(入队即落)
触发词 / 参数必有(来自 Hook 载荷)反查会话记录可得;读不到则留空
结果 / 耗时结果尽力推断,耗时随载荷同上一行,反查不到留空

规则通道的明细来自「反查」,能不能读到取决于各 Agent 的会话记录形态:

Agent会话记录位置可读条件
Claude Code<CLAUDE_CONFIG_DIR 或 ~/.claude>/projects/<项目>/<sessionId>.jsonl可直接读;CLAUDE_CONFIG_DIR 可改写根目录
DeepSeek Harness~/.dsh/sessions/<项目>/session-<id>/session.v4.jsonl.zstd会话为 v4 事件流,当前反查尚未适配,字段留空(与 Node 版本、是否安装 zstd 无关)
Trae会话正文存于 IDE 内部,本地只有 memory/ 摘要暂不可读,明细字段留空

反查是增强项:会话文件缺失、压缩格式变化、字段结构变更都只丢字段,不影响技能名与次数(基础统计一定成功)。

拿不到明细时的补救 ​

  1. 手工补录:toolkit usage log --skill <名称> --session <id> --prompt "…" --args "…" --outcome success; 批量场景用 usage data import 导入会话文件。
  2. 改用 Hook 通道:该 Agent 的 Hook 可用时,toolkit usage config channel hook + usage setup hooks install 可取得触发词与参数。

两种方式都不影响已有记录;补齐后只对之后的事件生效。⚠️ dsh 的会话是 v4 事件流,当前解析器尚未适配,升级 Node 或安装 zstd 都不会让明细出现——该适配属后续能力。

切换通道不会自动清理另一侧:切到 rule 后应 usage setup hooks remove,切到 hook 后应删掉规则段(usage config channel 切换时会提示)。

Hook 支持矩阵 ​

Agent状态配置路径能力
Trae已验证(需在 IDE 内启用)~/.trae-cn/hooks.json(回退 ~/.trae/hooks.json)PostToolUse / UserPromptSubmit
DeepSeek Harness已接入,需实测~/.dsh/hooks.json + 各 profile 的 cordis.patch.ymlPostToolUse / UserPromptSubmit
Claude Code已接入,需实测~/.claude/settings.json(CLAUDE_CONFIG_DIR 可改写)PostToolUse / UserPromptSubmit
Cursor已接入,需实测~/.cursor/hooks.jsonPostToolUse
Codex CLI已接入,需实测$CODEX_HOME/hooks.json(缺省 ~/.codex/hooks.json)PostToolUse
GitHub Copilot CLI已接入,需实测$COPILOT_HOME/hooks.json(缺省 ~/.copilot/hooks.json)PostToolUse

「需实测」表示配置路径与载荷字段按公开资料实现,尚未在真实环境验证;接入后先用 usage setup hooks status 与 usage data doctor 核对。

未列出的 Agent 可用规则通道、usage data import 或 usage log 补录:

bash
toolkit usage record --skill fxri-plan-task --skill fxri-plan-review   # 规则通道批量上报(静默)
toolkit usage data import --type transcript --file ~/.claude/projects/xxx.jsonl
toolkit usage log --skill fxri-plan-task --session manual-1 --prompt "归档任务"

安装与启用是两步 ​

bash
toolkit usage setup hooks install --agent trae   # 只写 Hook 配置
toolkit config set usage.enabled true            # 才打开采集总开关

未开启总开关时,Hook 即使被调用也直接退出,不写文件。usage setup hooks install 支持 --dry-run 预览,写前打印预览并确认,写前自动备份原配置;配置无法解析时不覆盖。 usage setup hooks install / usage setup hooks remove / usage setup uninstall 在 CI、脚本等无终端环境 需显式加 --yes,否则按无交互退出码提示非交互用法(见退出码)。

usage setup hooks install 只处理本机已检测到的 Agent:Trae 看 ~/.trae-cn 或 ~/.trae,DeepSeek Harness 看 ~/.dsh, Claude Code 看 CLAUDE_CONFIG_DIR 或 ~/.claude,Cursor 看 ~/.cursor,Codex 看 CODEX_HOME 或 ~/.codex, Copilot 看 COPILOT_HOME 或 ~/.copilot。显式 --agent 但本机未检测到时告警跳过,全部跳过时以非 0 退出,不会凭空创建配置; 工具卸载后残留的 Hook 用 usage setup hooks remove / usage setup uninstall 清理,这两个命令不要求 Agent 仍在本机。

Trae:还需在 IDE 内启用 ​

写完 ~/.trae-cn/hooks.json 并不等于 Trae 会执行它,还需在 IDE 侧登记启用:

  1. 打开 设置 > Hooks,配置类型选「全局」;
  2. 在「已配置的 Hooks」处点「创建」(已存在配置文件时用齿轮图标打开),在安全警示面板点「启用」;
  3. 「运行方式」选「本地自动运行」——沙箱方式可能拦截 Hook 写数据目录;
  4. 启用后重启 Trae 或开新会话才会重新加载,历史会话不补录。

验证方式:在 Trae 的「输出」面板查看 Agent Hooks 通道日志,并执行 toolkit usage setup hooks status 确认「最近触发」出现时间。

DeepSeek Harness:需装桥接插件 ​

dsh 不直接读 hooks.json,要经 Claude Code 兼容层桥接插件才生效,分两步:

  1. toolkit usage setup hooks install --agent dsh:写 ~/.dsh/hooks.json, 并在每个已存在的 profile(~/.dsh/profiles/<name>/cordis.patch.yml)写入 # >>> toolkit usage hooks 标记块, 把插件条目的 configPath 指向该文件;
  2. 安装桥接插件(只需一次):先完全退出桌面版(含托盘),再执行 dsh plugin --profile desktop add @dsh-cc/hooks-claude-code@0.9.2,装完重新打开应用。
    • 官方 @deepseek-ai/dsh-hooks-claude-code(0.0.1-rc.5)的 peer 依赖停在 0.0.1,与 dsh 0.2.x 不兼容,会被版本校验拒绝; 社区版 0.9.2 的 peer 下限是 0.2.0-rc.2,与 0.2.1-rc.3 匹配。升级 dsh 后若被拒绝,改选与运行时 peer 范围相符的版本。
    • ⚠️ 不要用桌面版「添加插件」:它只接受声明 dsh.bundle 的组合包,桥接插件会被拒绝。
    • usage setup hooks install 会把已安装的桥接包写进 cordis.patch.yml(官方版优先),无需手改插件名。

usage setup hooks status --agent dsh 会在插件缺失或标记块缺失时提示。桥接插件把 tool_response 扁平化为文本, outcome 字段恒为 unknown(Trae 等原生 Hook 会按返回体推断成功与否),其余字段正常。

profile 级提示(桥接条目 / 插件缺失)只在 Hook 已安装时出现;使用 rule 通道时无需处理这些提示。

⚠️ 运行沙箱限制:dsh 的 Hook 进程受运行时文件沙箱约束,可能无法写家目录下的统计库, 表现为 usage data doctor / usage setup hooks status 报 Access to the path ... is denied 或始终「暂无记录」。此时 Hook 通道不可用, 改用规则通道(toolkit usage config channel rule + 复制 技能使用情况规则),不依赖任何 Agent 配置。

重复执行 toolkit usage setup init 会沿用历史选择:已配置时默认「保持当前配置(只重装 Hook)」,选择「自定义」则逐项回填现有值。升级后修复 Hook 路径时优先用「保持当前配置」。

启用、关闭与卸载 ​

目的命令影响
只写 Hook 配置toolkit usage setup hooks install --agent <id>写各 Agent 的 Hook 文件,不打开采集
打开采集toolkit config set usage.enabled true事件开始落盘
只关采集toolkit config set usage.enabled falseHook 保留,事件不再写入
只删 Hooktoolkit usage setup hooks remove --agent <id>只移除本包条目,保留其它 Hook 与数据
停用并移除 Hooktoolkit usage setup uninstall --agent <id>关闭总开关并删本包 Hook,数据保留;加 --purge 删数据

usage setup hooks status 以本地时间显示最近触发时间与最近状态;usage setup uninstall 支持 --dry-run 预演。 Hook 错误写入数据目录的 hook-errors.log,只保留最近 200 行。

规则通道不用 Hook:执行 toolkit usage config channel rule 后,按 技能使用情况规则 把规则段复制进 Agent 全局规则即可; usage setup hooks status / usage data doctor 会在「通道与 Hook 实际状态不一致」时告警。

工具侧若另有 Hook 开关,需要一并处理,否则命令侧删了配置、工具侧仍按旧配置调用:

  • Trae:在 设置 > Hooks 停用或删除该全局 Hook;只跑 usage setup hooks remove 不在 IDE 里停用时,Trae 仍会调用。
  • DeepSeek Harness:usage setup hooks remove --agent dsh 会删 ~/.dsh/hooks.json 的本包命令并移除各 profile 的标记块(文件恢复为 []); 桥接插件不自动卸载,可在 设置 → Plugins 卸载, 或退出桌面版后 dsh plugin --profile desktop remove @deepseek-ai/dsh-hooks-claude-code。
  • Claude Code:无独立开关,Hook 随 settings.json 生效; 关闭用 usage setup hooks remove --agent claude(或手工删掉其中的 hooks 段),重启后不再调用。
  • Cursor / Codex CLI / GitHub Copilot CLI:配置即刻写入各自 hooks.json, 关闭用 usage setup hooks remove 后重启工具或开新会话;工具自带 Hook 管理界面时以其界面为准。

彻底清理顺序:先在工具侧停用或删除 Hook(如有独立开关)→ usage setup hooks remove 或 usage setup uninstall → 需要时 usage setup uninstall --purge 删除事件。

触发词如何关联 ​

UserPromptSubmit 到达时把 prompt 写入 state/sessions/<hash>.json;同会话后续 PostToolUse 读取作为触发词。缓存 24 小时过期, 避免读到陈旧会话。只有 capture.triggerPrompt 开启时才缓存。

补录与去重 ​

  • record --skill a --skill a --skill b 是规则通道的批量上报入口:入队后立即返回、退出码恒 0,同一技能传几次就记几次;只统计 toolkit 管理且命中 usage 配置的技能,未命中的静默忽略。
  • 队列由后台 worker 或下一次 usage 命令消费;usage show 的「队列」行显示积压条数,正常情况下应长期为 0。
  • usage data import --type transcript 支持 Claude JSONL 与通用 JSON / JSONL,从 tool_use 块提取工具调用,并把最近一次用户消息作为触发词。
  • log 用于没有 Hook 的 Agent;manual 属于用户显式补录,不受 Agent 开关限制。
  • 同一调用被两个适配器捕获时,按 (sessionId, toolUseId) 只保留首条;usage data dedupe 可清理历史重复,usage data doctor 会报告跨适配器重复组数。

注意 ​

  • Hook 命令写入当前 Node 与 CLI 的归一化绝对路径(realpath 解析后的稳定目标),不依赖 PATH;fnm / nvm 等版本管理器的会话级临时软链不会写进配置。
  • Hook 命令按平台生成:Windows 经 powershell -NoProfile -Command "& '…'" 包装(Agent 在 Windows 上经 PowerShell 执行), macOS / Linux 用单引号直接拼接;路径含空格或单引号时按各自 shell 规则转义。
  • 旧版「两个双引号串并列」的命令在 Windows 上会被 PowerShell 当成表达式而执行失败; usage setup hooks status 与 usage data doctor 会标记形态过期,重跑 usage setup hooks install 即替换为新形态。
  • usage setup hooks status 会显式提示「已配置但尚未执行过」; usage setup hooks status 与 usage data doctor 还会校验命令里的 Node / CLI 路径是否存在,失效时提示重跑 usage setup hooks install。
  • 旧版本安装的 Hook 仍指向 telemetry 命令,升级后不再生效; usage setup hooks status 与 usage data doctor 会提示,重跑 usage setup hooks install 即替换为新命令。
  • transcript 的时间以导入时刻为准,不还原原始会话时间。

MIT 开源协议