ronds_ai 0.1.9 → 0.1.10

package/README.md

@@ -1,289 +1,303 @@
-# ronds_ai
-
-`ronds_ai` 是一个命令行工具，主要用于两类事情：
-
-- 接收 Claude / Cursor 的 hook 事件，整理成统一的代码变更事件并上报
-- 帮助项目写入对应的 hook 配置，以及安装 Skills 到 Claude / Codex / Cursor
-
-## Requirements
-
-- Node.js `>=16`
-- `git`
-- `unzip`
-
-`git` 主要用于读取仓库信息和用户邮箱；`unzip` 用于 `skills install` 解压技能包。
-
-## Install
-
-按一次性执行使用：
-
-```bash
-npx ronds_ai@latest <command>
-```
-
-或全局安装：
-
-```bash
-npm install -g ronds_ai
-ronds_ai <command>
-```
-
-## Commands
-
-### `check record`
-
-检查 `record` 命令运行所需的基础环境。
-
-```bash
-ronds_ai check record
-```
-
-示例：
-
-```bash
-npx ronds_ai@latest check record
-```
-
-当前会检查并输出：
-
-- 当前 Node 版本
-- Node 是否满足 `>=16`
-- 当前目录下读取到的 `git user.email`
-- 当前 `worker_id` 配置来源和取值
-- `~/.profile` 路径
-
-输出是一个 JSON，例如：
-
-```json
-{
-  "ok": true,
-  "targetDir": "/path/to/project",
-  "node": {
-    "version": "v20.19.0",
-    "requirement": ">=16",
-    "satisfied": true
-  },
-  "gitUserEmail": "name@example.com",
-  "workerId": {
-    "name": "MCP_TRACKER_WORKER_ID",
-    "value": "worker-123",
-    "source": "env"
-  },
-  "profileFile": "/Users/you/.profile"
-}
-```
-
-如果 Node 版本不满足要求，命令会返回非 0 退出码。
-
-### `record`
-
-从标准输入读取 Claude 或 Cursor 的 hook payload，转换为统一事件后发送到服务端。
-
-```bash
-ronds_ai record <tool>
-```
-
-支持的 `tool`：
-
-- `claude`
-- `cursor`
-
-示例：
-
-```bash
-npx ronds_ai@latest record claude
-npx ronds_ai@latest record cursor
-```
-
-这个命令通常不是手工执行，而是被 Claude / Cursor 的 hook 配置调用。
-
-行为说明：
-
-- 从 `stdin` 读取一段 JSON
-- 根据来源提取文件路径、变更内容、增删行数、仓库信息、worker_id
-- 组装事件后通过 HTTP POST 上报
-- 成功时输出一行 JSON
-- 失败时会把事件写入本地失败日志，并输出保存位置
-
-成功输出示例：
-
-```json
-{"status":"sent","event_id":"...","response_status":200}
-```
-
-`dry-run` 输出示例：
-
-```json
-{"status":"dry-run","event_id":"...","response_status":0}
-```
-
-失败保存输出示例：
-
-```json
-{"status":"saved","event_id":"...","saved_path":"/Users/you/.ronds_ai/failed-events/20260409-claude-error.jsonl"}
-```
-
-目前支持的 hook 事件：
-
-- Claude: `PostToolUse`
-- Cursor: `afterFileEdit`
-
-其中 Claude 仅处理这些工具产生的事件：
-
-- `Write`
-- `Edit`
-- `MultiEdit`
-
-### `doctor`
-
-检查当前目录下的 hook 配置和最近错误日志，方便排查接入问题。
-
-```bash
-ronds_ai doctor <tool>
-```
-
-支持的 `tool`：
-
-- `claude`
-- `cursor`
-
-示例：
-
-```bash
-npx ronds_ai@latest doctor claude
-npx ronds_ai@latest doctor cursor
-```
-
-输出内容包括：
-
-- 当前检查的工具类型
-- 当前目标目录
-- 当前目录下的 `git user.email`
-- 关键配置文件是否存在
-- 今天的最近错误日志内容
-
-Claude 会检查：
-
-- `.claude/settings.json`
-- `.claude/settings.local.json`
-
-Cursor 会检查：
-
-- `.cursor/hooks.json`
-
-### `hooks deploy`
-
-在当前项目目录生成或更新 Claude / Cursor 的 hook 配置。
-
-```bash
-ronds_ai hooks deploy
-```
-
-示例：
-
-```bash
-npx ronds_ai@latest hooks deploy
-```
-
-这个命令会做的事情：
-
-- 在 `.cursor/hooks.json` 中确保存在 `npx ronds_ai@latest record cursor`
-- 在 `.claude/settings.json` 中确保存在 `npx ronds_ai@latest record claude`
-- 清理旧版 hook 脚本文件
-- 如果存在 `.claude/settings.local.json`，会移除其中由本工具管理的旧 hook，避免重复触发
-
-输出是一个 JSON，对应本次操作中：
-
-- `createdFiles`
-- `updatedFiles`
-- `removedFiles`
-
-### `skills install`
-
-下载一个技能包并安装到 Claude / Codex / Cursor 对应的技能目录。
-
-```bash
-ronds_ai skills install <name> [--tool claude,codex,cursor] [--scope project|global] [--project-dir <path>] [--force]
-```
-
-示例：
-
-```bash
-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`: 不发请求，只把事件打印到标准输出
-
-默认上报地址：
-
-```text
-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
-
-命令运行失败或上报失败时，会把信息保存到：
-
-```text
-~/.ronds_ai/failed-events
-```
-
-常见文件名格式：
-
-- `YYYYMMDD-claude-error.jsonl`
-- `YYYYMMDD-cursor-error.jsonl`
-- `YYYYMMDD-cli-error.jsonl`
-
-## Notes
-
-- `record` 和 `doctor` 目前只支持 `claude` 与 `cursor`
-- `skills install` 支持 `claude`、`codex`、`cursor`
-- 不支持的命令或参数会直接报错，并把错误写入 CLI 错误日志
+# ronds_ai
+
+`ronds_ai` 是一个命令行工具，主要用于两类事情：
+
+- 接收 Claude / Cursor 的 hook 事件，整理成统一的代码变更事件并上报
+- 帮助项目写入对应的 hook 配置，以及安装 Skills 到 Claude / Codex / Cursor
+
+## Requirements
+
+- Node.js `>=16`
+- `git`
+- `unzip`
+
+`git` 主要用于读取仓库信息和用户邮箱；`unzip` 用于 `skills install` 解压技能包。
+
+## Install
+
+按一次性执行使用：
+
+```bash
+npx ronds_ai@latest <command>
+```
+
+或全局安装：
+
+```bash
+npm install -g ronds_ai
+ronds_ai <command>
+```
+
+## Commands
+
+### `check record`
+
+检查 `record` 命令运行所需的基础环境。
+
+```bash
+ronds_ai check record
+```
+
+示例：
+
+```bash
+npx ronds_ai@latest check record
+```
+
+当前会检查并输出：
+
+- 当前 Node 版本
+- Node 是否满足 `>=16`
+- 当前目录下读取到的 `git user.email`
+- 当前 `worker_id` 配置来源和取值
+- `~/.profile` 路径
+
+输出是一个 JSON，例如：
+
+```json
+{
+  "ok": true,
+  "targetDir": "/path/to/project",
+  "node": {
+    "version": "v20.19.0",
+    "requirement": ">=16",
+    "satisfied": true
+  },
+  "gitUserEmail": "name@example.com",
+  "workerId": {
+    "name": "MCP_TRACKER_WORKER_ID",
+    "value": "worker-123",
+    "source": "env"
+  },
+  "profileFile": "/Users/you/.profile"
+}
+```
+
+如果 Node 版本不满足要求，命令会返回非 0 退出码。
+
+### `record`
+
+从标准输入读取 Claude、Codex 或 Cursor 的 hook payload，转换为统一事件后发送到服务端。
+
+```bash
+ronds_ai record <tool>
+```
+
+支持的 `tool`：
+
+- `claude`
+- `codex`
+- `cursor`
+
+示例：
+
+```bash
+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 上报
+- 成功时输出一行 JSON
+- 失败时会把事件写入本地失败日志，并输出保存位置
+
+成功输出示例：
+
+```json
+{"status":"sent","event_id":"...","response_status":200}
+```
+
+`dry-run` 输出示例：
+
+```json
+{"status":"dry-run","event_id":"...","response_status":0}
+```
+
+失败保存输出示例：
+
+```json
+{"status":"saved","event_id":"...","saved_path":"/Users/you/.ronds_ai/failed-events/20260409-claude-error.jsonl"}
+```
+
+目前支持的 hook 事件：
+
+- Claude: `PostToolUse`
+- Codex: `UserPromptSubmit` + `Stop`（两阶段处理）
+- Cursor: `afterFileEdit`
+
+其中 Claude 仅处理这些工具产生的事件：
+
+- `Write`
+- `Edit`
+- `MultiEdit`
+
+Codex 使用 `UserPromptSubmit` 和 `Stop` 两个 hook 阶段：前者保存当前 turn 的快照，后者基于快照计算变更事件；失败事件同样写入 `~/.ronds_ai/failed-events`。
+
+### `doctor`
+
+检查当前目录下的 hook 配置和最近错误日志，方便排查接入问题。
+
+```bash
+ronds_ai doctor <tool>
+```
+
+支持的 `tool`：
+
+- `claude`
+- `codex`
+- `cursor`
+
+示例：
+
+```bash
+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 会检查：
+
+- `.codex/hooks.json`
+
+Cursor 会检查：
+
+- `.cursor/hooks.json`
+
+### `hooks deploy`
+
+在当前项目目录生成或更新 Claude / Codex / Cursor 的 hook 配置。
+
+```bash
+ronds_ai hooks deploy
+```
+
+示例：
+
+```bash
+npx ronds_ai@latest hooks deploy
+```
+
+这个命令会做的事情：
+
+- 在 `.cursor/hooks.json` 中确保存在 `npx ronds_ai@latest record cursor`
+- 在 `.claude/settings.json` 中确保存在 `npx ronds_ai@latest record claude`
+- 在 `.codex/hooks.json` 中确保存在 `npx ronds_ai@latest record codex`（`UserPromptSubmit` + `Stop` 两个 hook）
+- 清理旧版 hook 脚本文件
+- 如果存在 `.claude/settings.local.json`，会移除其中由本工具管理的旧 hook，避免重复触发
+- 所有工具的失败事件统一写入 `~/.ronds_ai/failed-events`
+
+输出是一个 JSON，对应本次操作中：
+
+- `createdFiles`
+- `updatedFiles`
+- `removedFiles`
+
+### `skills install`
+
+下载一个技能包并安装到 Claude / Codex / Cursor 对应的技能目录。
+
+```bash
+ronds_ai skills install <name> [--tool claude,codex,cursor] [--scope project|global] [--project-dir <path>] [--force]
+```
+
+示例：
+
+```bash
+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`: 不发请求，只把事件打印到标准输出
+
+默认上报地址：
+
+```text
+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
+
+命令运行失败或上报失败时，会把信息保存到：
+
+```text
+~/.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 错误日志