ronds_ai

v0.1.29

Published

7 days ago

CLI for reporting AI code edit events.

0High
0Medium
0Low

giming

ronds_ai

ronds_ai 是一个命令行工具，主要用于两类事情：

接收 Claude / Cursor / Hermes / Codex 的 hook 事件，整理成统一的代码变更事件并上报
帮助项目写入对应的 hook 配置，以及安装 Skills 到 Claude / Codex / Cursor

Requirements

Node.js >=16
git
unzip

git 主要用于读取仓库信息和用户邮箱；unzip 用于 skills install 解压技能包。可选的 analyze 命令单独要求 Node.js >=20，不会改变 record 等现有命令的 Node 版本要求。

Install

按一次性执行使用：

npx ronds_ai@latest <command>

或全局安装：

npm install -g ronds_ai
ronds_ai <command>

Commands

`check record`

检查 record 命令运行所需的基础环境。

ronds_ai check record

示例：

npx ronds_ai@latest check record

当前会检查并输出：

当前 Node 版本
Node 是否满足 >=16
当前目录下读取到的 git user.email
当前 MCP_TRACKER_WORKER_ID 的来源和取值
~/.profile 路径

输出 JSON 后，命令还会继续在终端里显示当前 MCP_TRACKER_WORKER_ID，并询问是否要修改。如果选择修改：

Windows：写入用户级持久环境变量，新的终端可直接读取
Linux：写入 ~/.profile，新的 shell 可读取

如果不想进入交互流程，可加上：

ronds_ai check record --no-prompt

或：

npx ronds_ai@latest check record --no-prompt

交互式修改后，命令会再次显示更新后的 MCP_TRACKER_WORKER_ID。

输出是一个 JSON，例如：

{
  "ok": true,
  "targetDir": "/path/to/project",
  "node": {
    "version": "v20.19.0",
    "requirement": ">=16",
    "satisfied": true
  },
  "gitUserEmail": "[email protected]",
  "workerId": {
    "name": "MCP_TRACKER_WORKER_ID",
    "value": "worker-123",
    "source": "env"
  },
  "profileFile": "/Users/you/.profile"
}

如果 Node 版本不满足要求，命令会返回非 0 退出码。

`record`

从标准输入读取 Claude、Codex、Cursor 或 Hermes 的 hook payload，转换为统一事件后发送到服务端。

ronds_ai record <tool>

支持的 tool：

claude
codex
cursor
hermes

示例：

npx ronds_ai@latest record claude
npx ronds_ai@latest record codex
npx ronds_ai@latest record cursor
npx ronds_ai@latest record hermes

这个命令通常不是手工执行，而是被 Claude / Codex / Cursor 或 Hermes 的 hook 配置调用。

行为说明：

从 stdin 读取一段 JSON
根据来源提取文件路径、变更内容、增删行数、仓库信息、worker_id
组装事件后通过 HTTP POST 上报
Claude / Cursor 成功时输出一行 JSON
Claude / Cursor 失败时会把事件写入本地失败日志，并输出保存位置
Codex 作为 PostToolUse hook 调用时，标准输出固定为 Codex hook command output schema，避免触发 invalid post-tool-use JSON output

成功输出示例：

{"status":"sent","event_id":"...","response_status":200}

dry-run 输出示例：

{"status":"dry-run","event_id":"...","response_status":0}

失败保存输出示例：

{"status":"saved","event_id":"...","saved_path":"/Users/you/.ronds_ai/failed-events/20260409-claude-error.jsonl"}

目前支持的 hook 事件：

Claude: PostToolUse
Codex: PostToolUse（apply_patch 编辑后采集）
Cursor: afterFileEdit
Hermes: post_tool_call

其中 Claude 仅处理这些工具产生的事件：

Write
Edit
MultiEdit

Codex 使用 PostToolUse hook，在 apply_patch 执行后直接解析本次补丁内容并生成变更事件；失败事件同样写入 ~/.ronds_ai/failed-events。

Codex 输出示例：

{"continue":true,"hookSpecificOutput":{"hookEventName":"PostToolUse"}}

Hermes 使用 Shell hooks，通过 ~/.hermes/config.yaml 中的 hooks.post_tool_call 配置监听 write_file 和 patch 工具的调用。Hermes Shell hook 不要求特定 stdout 格式，成功/失败信息直接输出 JSON 结果行。

`analyze`

从 Claude Code 的会话 transcript 生成一次性会话摘要：

ronds_ai analyze claude

该命令仅用于 SessionEnd Hook，会由 hooks deploy 自动安装（project 或 user scope，未用 --tool 排除 claude 时）。它只上报：

会话起止时间与有效用户轮数
Skill 名称及调用次数
首轮输入的最多 150 个字符预览
repo、branch、worker_id 和 Git 身份

扫描采用流式 JSONL 读取，内存不会随 transcript 大小增长，不上传逐轮内容或代码。

每次 Hook 调用仅生成一条会话级结构化快照；网络失败时写入有界队列，后续 Hook 最多补发少量旧快照。内部部署仅保留用户、会话、项目目录等必要定位字段。

运行期间只写一个轻量 active 标记，结束时一次性转换为 ~/.ronds_ai/analyze/ 下的待补传 spool。网络失败不会影响 Hook 主流程，并按 5、15、60 分钟退避补传；平台按 diagnostic_event_id 幂等去重。可选配置：

ANALYZE_DIAGNOSTICS_URL：覆盖诊断事件上报地址
ANALYZE_DIAGNOSTICS_TOKEN：诊断入口的 Bearer Token
ANALYZE_DIAGNOSTICS_TIMEOUT_MS：单次补传超时，默认 400

会话入口地址默认为本机 API，也可按部署环境覆盖：

AI_USAGE_SESSIONS_URL：会话摘要 API 地址

hooks deploy 会自动把以下条目写入 Claude Code 的 hooks 配置：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx ronds_ai@latest analyze claude"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx ronds_ai@latest analyze claude"
          }
        ]
      }
    ]
  }
}

Node.js 低于 20 或安装时使用了 --omit=optional 时，只有 analyze 会返回明确错误；record 等其他命令仍可运行。Hook payload 或上传处理失败时，analyze 保持 fail-open 并把诊断信息写入本地日志。

`doctor`

检查当前目录下的 hook 配置和最近错误日志，方便排查接入问题。

ronds_ai doctor <tool>

支持的 tool：

analyze
claude
codex
cursor
hermes

示例：

npx ronds_ai@latest doctor analyze
npx ronds_ai@latest doctor claude
npx ronds_ai@latest doctor codex
npx ronds_ai@latest doctor cursor
npx ronds_ai@latest doctor hermes

输出内容包括：

当前检查的工具类型
当前目标目录
当前目录下的 git user.email
关键配置文件是否存在
今天的最近错误日志内容

doctor analyze 还会检查 Node.js 版本、用户级 SessionEnd Hook、工号和 Git 用户身份，以及本地待补传会话数量。它只做只读探测，不会发送会话数据。

Claude 会检查：

.claude/settings.json
.claude/settings.local.json

Codex 会检查：

Windows: C:\ProgramData\OpenAI\Codex\requirements.toml
Linux / macOS: /etc/codex/requirements.toml

Cursor 会检查：

.cursor/hooks.json

Hermes 会检查：

~/.hermes/config.yaml 是否存在
该文件中是否有 hooks.post_tool_call 下 matcher: "write_file|patch" 的 hook 条目

`hooks deploy`

在当前项目目录或用户目录生成/更新 Claude / Codex / Cursor 的 hook 配置。

ronds_ai hooks deploy [--scope project|user]

示例：

npx ronds_ai@latest hooks deploy
npx ronds_ai@latest hooks deploy --scope user

默认 scope 为 project（项目级部署），行为：

写入或更新 .cursor/hooks.json
写入或更新 .claude/settings.json（PostToolUse 的 record claude 采集 hook，以及 SessionEnd 的 analyze claude 会话摘要 hook）
清理项目内旧版 Cursor、Claude、Codex hook 脚本
跳过 Codex 项目级配置部署，并在输出中说明原因

--scope user（用户级部署），行为：

写入或更新用户级 Cursor hook 配置
写入或更新用户级 Claude hook 配置（同上：record claude 采集 hook + analyze claude 会话摘要 hook）
写入或更新系统级 requirements.toml（Windows: C:\ProgramData\OpenAI\Codex\requirements.toml，Linux / macOS: /etc/codex/requirements.toml），包含 [features] hooks = true、[hooks] 托管目录配置以及 PostToolUse 的 apply_patch hook
清理用户目录中的旧版 hook 脚本文件

Codex 推荐使用 --scope user，因为项目级 .codex 配置在未被用户显式信任的项目中会被 Codex 忽略。

Hermes Shell Hook 部署

ronds_ai hooks deploy hermes

生成或更新 ~/.hermes/config.yaml，添加 hooks.post_tool_call 条目（监听 write_file 和 patch 工具的调用）并设置 hooks_auto_accept: true。

因为 Hermes 的 Shell hook 配置独立于 Claude / Codex / Cursor（YAML 格式、用户级目录），所以走单独的子命令路径，不与其他工具混用。

执行后 ~/.hermes/config.yaml 的效果：

hooks:
  post_tool_call:
    - matcher: write_file|patch
      command: npx ronds_ai@latest record hermes
      timeout: 30
hooks_auto_accept: true

也可手动复制以上内容到 ~/.hermes/config.yaml。

输出是一个 JSON，包含：

scope: 本次部署的 scope
targetDir: 命令执行时的项目目录
configRoot: 实际写入配置的根目录
createdFiles
updatedFiles
removedFiles
skipped: 被跳过的工具及原因（仅在 project scope 下出现）
analyze: Claude 会话摘要 hook 的安装状态（installed、events、command）

Hooks Auto Sync（自动后台同步）

CLI 会自动在后台检查并更新用户级 hooks 配置，无需用户每次手动执行 hooks deploy --scope user。

工作方式：

运行任意 CLI 命令时，进行轻量检查（多数情况下只读取一次 sentinel 文件的修改时间）
如果距离上次检查超过 24 小时，判断 hooks schema 版本是否落后
版本落后时，后台启动子进程自动执行 hooks deploy --scope user 和 deploy hermes
当前命令不等待后台同步完成，也不受后台同步失败的影响
record 高频路径使用 sentinel fast path，额外成本约等于一次文件 stat

可通过环境变量禁用：

RONDS_AI_DISABLE_HOOKS_AUTO_SYNC=1

注意：

auto-sync 只维护用户级 hooks，不影响项目级配置
auto-sync 会同步维护用户级 Claude 的 analyze claude 会话摘要 hook
后台同步失败时，错误记录到 ~/.ronds_ai/hooks_auto_sync_error.log，不污染当前命令输出
首次安装 hooks 仍建议执行 ronds_ai hooks deploy --scope user

`skills install`

下载一个技能包并安装到 Claude / Codex / Cursor 对应的技能目录。

ronds_ai skills install <name> [--tool claude,codex,cursor] [--scope project|global] [--project-dir <path>] [--force]

示例：

npx ronds_ai@latest skills install demo-skill
npx ronds_ai@latest skills install demo-skill --tool claude --scope global
npx ronds_ai@latest skills install demo-skill --tool codex,cursor --scope project

参数说明：

name: 要安装的 skill 名称
--tool: 目标工具，可传 claude、codex、cursor，多个值用逗号分隔
--scope: 安装范围，可选 project 或 global
--project-dir: 当 scope=project 时指定项目目录；默认是当前目录
--force: 目标目录已存在时覆盖

如果没有传 --tool 或 --scope，CLI 会进入交互式提示。

安装目录规则：

claude + project: <project>/.claude/skills/<name>
claude + global: ~/.claude/skills/<name>
codex + project: <project>/.agents/skills/<name>
codex + global: ~/.agents/skills/<name>
cursor + project: <project>/.agents/skills/<name>
cursor + global: ~/.agents/skills/<name>

输出是一个 JSON，包含：

安装的 skill 名称
安装范围
项目目录
下载地址
实际安装到的目标路径列表

Environment Variables

`record` 相关

HOOK_REPORT_URL: 上报地址
CHANGE_REPORT_URL: 上报地址，作为 HOOK_REPORT_URL 的备用读取项
HOOK_REPORT_TIMEOUT_MS: 请求超时时间，默认 10000
HOOK_REPORT_TOKEN: 如果设置，会以 Authorization: Bearer <token> 发送
HOOK_REPORT_HEADERS: 额外请求头，要求是 JSON 字符串
HOOK_REQUEST_DRY_RUN=1: 不发请求。Claude / Cursor 会把事件打印到标准输出；Codex 仍输出合法的 PostToolUse hook command output schema

默认上报地址：

https://aihub.ronds.com/api/api/v1/ai-code-events

`worker_id` 解析顺序

record 在构建事件时，会按下面顺序寻找 worker_id：

process.cwd()/.ai_config/config.json 中的 worker_id
Git 仓库根目录下 .ai_config/config.json 中的 worker_id
环境变量 MCP_TRACKER_WORKER_ID
环境变量 WORKER_ID
当前系统用户名

Error Logs

命令运行失败或上报失败时，会把信息保存到：

~/.ronds_ai/failed-events

常见文件名格式：

YYYYMMDD-claude-error.jsonl
YYYYMMDD-codex-error.jsonl
YYYYMMDD-cursor-error.jsonl
YYYYMMDD-hermes-error.jsonl
YYYYMMDD-cli-error.jsonl

Notes

record 和 doctor 目前支持 claude、codex、cursor、hermes
hooks deploy 支持 claude、codex、cursor、hermes（hermes 为独立子命令）
skills install 支持 claude、codex、cursor
不支持的命令或参数会直接报错，并把错误写入 CLI 错误日志

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ronds_ai

Requirements

Install

Commands

check record

record

analyze

doctor

hooks deploy

Hermes Shell Hook 部署

Hooks Auto Sync（自动后台同步）

skills install

Environment Variables

record 相关

worker_id 解析顺序

Error Logs

Notes

`check record`

`record`

`analyze`

`doctor`

`hooks deploy`

`skills install`

`record` 相关

`worker_id` 解析顺序