@l2h/agent-telemetry

为 OpenCode、Kiro CLI 和 Kiro IDE 记录本地 JSONL 会话日志。日志仅保存在本机，不上传、不拦截工具调用。

安装

OpenCode

首次安装时，在 ~/.config/opencode/opencode.jsonc（或 opencode.json）的 plugin 数组中添加包名，然后重启 OpenCode：

{
  "plugin": ["@l2h/agent-telemetry"]
}

首次启动会将规则文件注册到 OpenCode 的 instructions；已有 instructions 保持不变。

规则一致性提醒：若 OpenCode 已安装的规则副本（~/.config/opencode/rules/GLOBAL_RULES.md）与包内 GLOBAL_RULES.md 不一致，启动时会在诊断日志（~/.l2h/agent-telemetry/diag/diag.log）记录一条 WARN 提醒，但不会自动覆盖，需要你手动同步替换该文件。

Kiro（CLI 与 IDE）

# 同时安装 Kiro IDE 与 CLI（默认）
npx --yes @l2h/agent-telemetry kiro-install

# 仅安装 IDE 或 CLI
npx --yes @l2h/agent-telemetry kiro-install --target ide
npx --yes @l2h/agent-telemetry kiro-install --target cli

Kiro IDE 安装后自动采集。Kiro CLI 需使用 kiro-cli --agent agent-telemetry 启动；如需设为默认 Agent，安装时追加 --set-default。

升级

OpenCode

OpenCode 会缓存已安装的插件版本，升级时需刷新缓存。以下两种方式二选一：

注意：opencode plugin @l2h/agent-telemetry --global --force 只更新配置，不会刷新插件版本，升级请用以下任一方式。

方式一：删除缓存后重启（推荐）

rm -rf ~/.cache/opencode/packages/@l2h/agent-telemetry \
       ~/.cache/opencode/packages/@l2h/agent-telemetry@latest

配置保持 @l2h/agent-telemetry（不带版本号）即可。缓存清空后，OpenCode 启动时会重新从 registry 拉取最新版本。

方式二：固定版本号

在 opencode.jsonc 的 plugin 数组写明具体版本：

{
  "plugin": ["@l2h/[email protected]"]
}

升级到新版本时，把版本号改为新发布版本即可。缓存目录会按版本号区分，版本变化时不会命中旧缓存。

Kiro

npx --yes @l2h/agent-telemetry kiro-install

安装器默认保护被手动修改过的规则、Hook 和运行时文件。确认要覆盖这些修改时，先备份自定义内容，再执行：

npx --yes @l2h/agent-telemetry kiro-install --force

规则一致性提醒：安装时若检测到 Kiro 现有全局规则（~/.kiro/steering/GLOBAL_RULES.md）与包内不一致，会交互询问「是否用包内规则覆盖？（y/N）」；非交互环境默认保留现有，需显式 --force 才覆盖。

配置

共享配置文件为 ~/.l2h/agent-telemetry/config.jsonc（支持注释）。优先级：环境变量 > 配置文件 > 默认值。

升级时共享配置会做幂等迁移（OpenCode 每次启动、kiro-install 时触发）：保留你改过的字段值、补新版本新增字段、删除旧/废弃字段（logRetentionDays/logDir 会自动迁移为 messagesRetentionDays/messagesDir），不会整体覆盖你的配置。

| 字段 | 环境变量 | 默认值 | 说明 | | --- | --- | --- | --- | | messagesRetentionDays | DEVKIT_MESSAGES_RETENTION_DAYS | 1 | 会话消息保留天数 | | boostInterval | DEVKIT_BOOST_INTERVAL | 0 | OpenCode 规则重申的周期兜底间隔；0=关闭周期提醒（默认，仅保留上下文变化 / compaction 完成后的强制重申），>0 时每 N 次模型交互重申一次 | | messagesDir | DEVKIT_MESSAGES_DIR | ~/.l2h/agent-telemetry/messages | 会话消息（遥测数据）存储目录 | | logLevel | DEVKIT_LOG_LEVEL | warn | 诊断日志最低级别：debug/info/warn/error | | captureUserContent | DEVKIT_CAPTURE_USER_CONTENT | true | 是否采集用户会话内容（用户输入/助手输出/系统上下文）；false 时仅保留统计元数据，脱敏落盘 | | diagLogMaxBytes | DEVKIT_DIAG_LOG_MAX_BYTES | 1048576 | 诊断日志轮转尺寸阈值（字节），超过则清空重写 |

可选环境变量：DEVKIT_CONFIG_DIR 指定共享配置目录（诊断日志 diag/ 随之迁移）；DEVKIT_KIRO_DIR 或 KIRO_HOME 指定 Kiro 根目录。

规则重申注入内容

OpenCode 侧重申（上下文变化 / compaction 完成 / boostInterval 周期命中）时，向模型上下文注入一段短而硬的指向性 nudge，而非重复 instructions 全文（后者已由 opencode 常驻加载，逐字重复信息量为零）。nudge 聚焦最高频被违反的硬约束：

• L2/L3 变更必须先输出规划并等待用户 Yes/Ok/确认 后方可动工，规划轮禁止写操作与状态变更。

日志

会话消息（遥测数据）路径：

~/.l2h/agent-telemetry/messages/<project>/<session>.jsonl

诊断日志路径：~/.l2h/agent-telemetry/diag/diag.log（与遥测数据分离，随保留期一并回收）。

每个用户轮次写入一行 JSON。字段按以下顺序输出；可选字段不存在时省略：

ts, tool, sessionID, project, pluginVersion, schemaVersion, turn,
modelInteractions, model, userInput, assistantMessages, systemContext

• turn 是会话内的用户输入轮次。
• modelInteractions：OpenCode 统计 system transform；Kiro CLI 统计当前 Prompt 后的 AssistantMessage；Kiro IDE 优先统计 Reasoning/Thinking 模型事件，缺失时按可见助手消息数回退。
• systemContext 仅在 OpenCode 的 system context 相对上一轮变化时写入。
• 日志包含完整用户输入和助手输出；请按团队数据规范决定是否启用及设置保留期。

卸载

OpenCode

从 plugin 数组移除 @l2h/agent-telemetry 并重启 OpenCode。若不再需要规则文件，也可手动删除 ~/.config/opencode/rules/GLOBAL_RULES.md。

Kiro

npx --yes @l2h/agent-telemetry kiro-uninstall

卸载只删除仍与安装记录一致的文件；手动修改过的 Kiro 集成、共享配置和遥测日志会保留。

详细说明

实现和兼容性说明见 docs/IMPLEMENTATION.md。

License

MIT