ronds_ai 0.1.7 → 0.1.9

package/README.md

@@ -0,0 +1,289 @@
+# 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 错误日志

package/bin/ronds_ai.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 const { runCodeRecord, saveCliError } = require('../lib/code_record');
+const { runCheckRecord } = require('../lib/check_record');
 const { runDoctor } = require('../lib/doctor');
 const { deployHooks } = require('../lib/hooks_deploy');
-const { runSkillsInstall } = require('../lib/skills_install');
 
 const SUPPORTED_SOURCES = new Set(['claude', 'cursor']);
 
@@ -11,6 +11,7 @@ function printUsage() {
   process.stderr.write([
     'Usage:',
     '  ronds_ai record <tool>',
+    '  ronds_ai check record',
     '  ronds_ai doctor <tool>',
     '  ronds_ai hooks deploy',
     '  ronds_ai skills install <name> [--tool claude,codex,cursor] [--scope project|global] [--project-dir <path>] [--force]',
@@ -23,6 +24,7 @@ function printUsage() {
     'Examples:',
     '  npx ronds_ai@latest record claude',
     '  npx ronds_ai@latest record cursor',
+    '  npx ronds_ai@latest check record',
     '  npx ronds_ai@latest doctor claude',
     '  npx ronds_ai@latest doctor cursor',
     '  npx ronds_ai@latest hooks deploy',
@@ -44,6 +46,21 @@ async function runHooksCommand(args) {
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }
 
+async function runCheckCommand(args) {
+  const [target] = args;
+
+  if (target !== 'record') {
+    throw new Error('Unsupported check command');
+  }
+
+  const result = runCheckRecord(process.cwd());
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+}
+
 function parseSkillsInstallArgs(args) {
   const options = {
     tool: '',
@@ -113,6 +130,7 @@ function parseSkillsInstallArgs(args) {
 }
 
 async function runSkillsCommand(args) {
+  const { runSkillsInstall } = require('../lib/skills_install');
   const [action, ...rest] = args;
 
   if (action !== 'install') {
@@ -152,6 +170,11 @@ async function run() {
     return;
   }
 
+  if (command === 'check') {
+    await runCheckCommand(args);
+    return;
+  }
+
   if (command === 'hooks') {
     await runHooksCommand(args);
     return;

package/lib/check_record.js

@@ -0,0 +1,106 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const ENVIRONMENT_VARIABLE_NAME = process.env.ENVIRONMENT_VARIABLE_NAME || 'MCP_TRACKER_WORKER_ID';
+const MINIMUM_NODE_MAJOR = 16;
+
+function readGitUserEmail(baseDir) {
+  try {
+    return execFileSync('git', ['config', 'user.email'], {
+      cwd: baseDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+      .trim()
+      .replace(/^["'“”]+/, '')
+      .replace(/["'“”]+$/, '');
+  } catch {
+    return '';
+  }
+}
+
+function getProfileFilePath() {
+  return path.join(os.homedir(), '.profile');
+}
+
+function getCurrentWorkerId() {
+  const envValue = String(process.env[ENVIRONMENT_VARIABLE_NAME] || '').trim();
+  if (envValue) {
+    return {
+      name: ENVIRONMENT_VARIABLE_NAME,
+      value: envValue,
+      source: 'env',
+    };
+  }
+
+  const profileFile = getProfileFilePath();
+  if (!fs.existsSync(profileFile)) {
+    return {
+      name: ENVIRONMENT_VARIABLE_NAME,
+      value: '',
+      source: '',
+    };
+  }
+
+  const lines = fs.readFileSync(profileFile, 'utf8').split('\n');
+  const prefix = `export ${ENVIRONMENT_VARIABLE_NAME}=`;
+
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index].trim();
+    if (!line.startsWith(prefix)) {
+      continue;
+    }
+
+    const value = line
+      .slice(prefix.length)
+      .trim()
+      .replace(/^"/, '')
+      .replace(/"$/, '');
+
+    return {
+      name: ENVIRONMENT_VARIABLE_NAME,
+      value,
+      source: 'profile',
+    };
+  }
+
+  return {
+    name: ENVIRONMENT_VARIABLE_NAME,
+    value: '',
+    source: '',
+  };
+}
+
+function parseNodeMajor(version) {
+  const normalized = String(version || '').trim();
+  const match = normalized.match(/^v?(\d+)/);
+  return match ? Number(match[1]) : 0;
+}
+
+function runCheckRecord(targetDir = process.cwd()) {
+  const baseDir = path.resolve(targetDir);
+  const nodeVersion = process.version;
+  const nodeMajor = parseNodeMajor(nodeVersion);
+  const gitUserEmail = readGitUserEmail(baseDir);
+  const worker = getCurrentWorkerId();
+  const nodeSatisfied = nodeMajor >= MINIMUM_NODE_MAJOR;
+
+  return {
+    ok: nodeSatisfied,
+    targetDir: baseDir,
+    node: {
+      version: nodeVersion,
+      requirement: `>=${MINIMUM_NODE_MAJOR}`,
+      satisfied: nodeSatisfied,
+    },
+    gitUserEmail,
+    workerId: worker,
+    profileFile: getProfileFilePath(),
+  };
+}
+
+module.exports = {
+  runCheckRecord,
+};

package/lib/skills_install.js

@@ -10,10 +10,68 @@ const { promptForScope, promptForTools } = require('./skills_prompt');
 const SKILL_DOWNLOAD_BASE_URL = 'https://aihub.ronds.com/api/api/v1/skills/download';
 const MAX_REDIRECTS = 5;
 
-function streamToFile(url, destinationPath, redirectCount = 0) {
+function parseJson(raw, label) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${label} is not valid JSON: ${detail}`);
+  }
+}
+
+function loadDownloadConfig() {
+  const token = String(process.env.SKILL_DOWNLOAD_TOKEN || '').trim();
+  const extraHeaders = process.env.SKILL_DOWNLOAD_HEADERS
+    ? parseJson(process.env.SKILL_DOWNLOAD_HEADERS, 'SKILL_DOWNLOAD_HEADERS')
+    : {};
+
+  const headers = {
+    ...extraHeaders,
+  };
+
+  if (token) {
+    headers.authorization = `Bearer ${token}`;
+  }
+
+  return { headers };
+}
+
+function copyDirectoryRecursive(sourceDir, destinationDir) {
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  fs.mkdirSync(destinationDir, { recursive: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destinationPath = path.join(destinationDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectoryRecursive(sourcePath, destinationPath);
+      continue;
+    }
+
+    if (entry.isSymbolicLink()) {
+      const targetPath = fs.readlinkSync(sourcePath);
+      fs.symlinkSync(targetPath, destinationPath);
+      continue;
+    }
+
+    fs.copyFileSync(sourcePath, destinationPath);
+  }
+}
+
+function copyDirectory(sourceDir, destinationDir) {
+  if (typeof fs.cpSync === 'function') {
+    fs.cpSync(sourceDir, destinationDir, { recursive: true });
+    return;
+  }
+
+  copyDirectoryRecursive(sourceDir, destinationDir);
+}
+
+function streamToFile(url, destinationPath, config, redirectCount = 0) {
   return new Promise((resolve, reject) => {
     const transport = String(url).startsWith('http://') ? http : https;
-    const request = transport.get(url, (response) => {
+    const request = transport.get(url, { headers: config.headers }, (response) => {
       if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
         response.resume();
         if (redirectCount >= MAX_REDIRECTS) {
@@ -22,7 +80,7 @@ function streamToFile(url, destinationPath, redirectCount = 0) {
         }
 
         const nextUrl = new URL(response.headers.location, url).toString();
-        streamToFile(nextUrl, destinationPath, redirectCount + 1).then(resolve, reject);
+        streamToFile(nextUrl, destinationPath, config, redirectCount + 1).then(resolve, reject);
         return;
       }
 
@@ -51,7 +109,7 @@ function streamToFile(url, destinationPath, redirectCount = 0) {
 async function downloadSkillArchive(name, workingDir) {
   const archivePath = path.join(workingDir, `${name}.zip`);
   const url = `${SKILL_DOWNLOAD_BASE_URL}/${encodeURIComponent(name)}`;
-  await streamToFile(url, archivePath);
+  await streamToFile(url, archivePath, loadDownloadConfig());
   return {
     url,
     archivePath,
@@ -98,7 +156,7 @@ function copySkill(sourceDir, destinationDir, force) {
   }
 
   fs.mkdirSync(path.dirname(destinationDir), { recursive: true });
-  fs.cpSync(sourceDir, destinationDir, { recursive: true });
+  copyDirectory(sourceDir, destinationDir);
 }
 
 async function resolveInstallOptions(options) {

package/lib/skills_prompt.js

@@ -1,4 +1,4 @@
-const readline = require('readline/promises');
+const readline = require('readline');
 
 const TOOL_CHOICES = ['claude', 'codex', 'cursor'];
 const SCOPE_CHOICES = ['project', 'global'];
@@ -42,7 +42,9 @@ async function promptForTools() {
     ].join('\n'));
     process.stderr.write('\n');
 
-    const answer = await rl.question('> ');
+    const answer = await new Promise((resolve) => {
+      rl.question('> ', resolve);
+    });
     return normalizeChoiceInput(answer);
   } finally {
     rl.close();
@@ -64,7 +66,9 @@ async function promptForScope() {
     ].join('\n'));
     process.stderr.write('\n');
 
-    const answer = String(await rl.question('> ')).trim().toLowerCase();
+    const answer = String(await new Promise((resolve) => {
+      rl.question('> ', resolve);
+    })).trim().toLowerCase();
     if (answer === '1') {
       return 'project';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ronds_ai",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "CLI for reporting AI code edit events.",
   "bin": {
     "ronds_ai": "bin/ronds_ai.js"
@@ -9,5 +9,8 @@
     "bin",
     "lib"
   ],
+  "engines": {
+    "node": ">=16"
+  },
   "license": "MIT"
 }