ronds_ai

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

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

Requirements

• Node.js >=16
• git
• unzip

git 主要用于读取仓库信息和用户邮箱；unzip 用于 skills install 解压技能包。

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 的 hook payload，转换为统一事件后发送到服务端。

ronds_ai record <tool>

支持的 tool：

• claude
• codex
• cursor

示例：

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

这个命令通常不是手工执行，而是被 Claude / Codex / Cursor 的 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

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

• Write
• Edit
• MultiEdit

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

Codex 输出示例：

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

doctor

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

ronds_ai doctor <tool>

支持的 tool：

• claude
• codex
• cursor

示例：

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

输出内容包括：

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

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

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
• 清理项目内旧版 Cursor、Claude、Codex hook 脚本
• 跳过 Codex 项目级配置部署，并在输出中说明原因

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

• 写入或更新用户级 Cursor hook 配置
• 写入或更新用户级 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 忽略。

输出是一个 JSON，包含：

• scope: 本次部署的 scope
• targetDir: 命令执行时的项目目录
• configRoot: 实际写入配置的根目录
• createdFiles
• updatedFiles
• removedFiles
• skipped: 被跳过的工具及原因（仅在 project scope 下出现）

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：

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

Error Logs

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

~/.ronds_ai/failed-events

常见文件名格式：

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

Notes

• record 和 doctor 目前支持 claude、codex 与 cursor
• skills install 支持 claude、codex、cursor
• 不支持的命令或参数会直接报错，并把错误写入 CLI 错误日志