ronds_ai 0.1.13 → 0.1.17

package/README.md

@@ -1,4 +1,4 @@
-# ronds_ai
+# ronds_ai
 
 `ronds_ai` 是一个命令行工具，主要用于两类事情：
 
@@ -121,11 +121,12 @@ npx ronds_ai@latest record cursor
 
 行为说明：
 
-- 从 `stdin` 读取一段 JSON
-- 根据来源提取文件路径、变更内容、增删行数、仓库信息、worker_id
-- 组装事件后通过 HTTP POST 上报
-- 成功时输出一行 JSON
-- 失败时会把事件写入本地失败日志，并输出保存位置
+- 从 `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`
 
 成功输出示例：
 
@@ -148,7 +149,7 @@ npx ronds_ai@latest record cursor
 目前支持的 hook 事件：
 
 - Claude: `PostToolUse`
-- Codex: `UserPromptSubmit` + `Stop`（两阶段处理）
+- Codex: `PostToolUse`（`apply_patch` 编辑后采集）
 - Cursor: `afterFileEdit`
 
 其中 Claude 仅处理这些工具产生的事件：
@@ -157,7 +158,13 @@ npx ronds_ai@latest record cursor
 - `Edit`
 - `MultiEdit`
 
-Codex 使用 `UserPromptSubmit` 和 `Stop` 两个 hook 阶段：前者保存当前 turn 的快照，后者基于快照计算变更事件；失败事件同样写入 `~/.ronds_ai/failed-events`。
+Codex 使用 `PostToolUse` hook，在 `apply_patch` 执行后直接解析本次补丁内容并生成变更事件；失败事件同样写入 `~/.ronds_ai/failed-events`。
+
+Codex 输出示例：
+
+```json
+{"continue":true,"suppressOutput":true,"hookSpecificOutput":{"hookEventName":"PostToolUse"}}
+```
 
 ### `doctor`
 
@@ -196,7 +203,8 @@ Claude 会检查：
 
 Codex 会检查：
 
-- `.codex/hooks.json`
+- Windows: `C:\ProgramData\OpenAI\Codex\requirements.toml`
+- Linux / macOS: `/etc/codex/requirements.toml`
 
 Cursor 会检查：
 
@@ -204,33 +212,44 @@ Cursor 会检查：
 
 ### `hooks deploy`
 
-在当前项目目录生成或更新 Claude / Codex / Cursor 的 hook 配置。
+在当前项目目录或用户目录生成/更新 Claude / Codex / Cursor 的 hook 配置。
 
 ```bash
-ronds_ai hooks deploy
+ronds_ai hooks deploy [--scope project|user]
 ```
 
 示例：
 
 ```bash
 npx ronds_ai@latest hooks deploy
+npx ronds_ai@latest hooks deploy --scope user
 ```
 
-这个命令会做的事情：
+默认 scope 为 `project`（项目级部署），行为：
 
-- 在 `.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）
-- 在 `.codex/config.toml` 中确保存在 `[features] codex_hooks = true`，启用 Codex hooks
-- 清理旧版 hook 脚本文件
-- 如果存在 `.claude/settings.local.json`，会移除其中由本工具管理的旧 hook，避免重复触发
-- 所有工具的失败事件统一写入 `~/.ronds_ai/failed-events`
+- 写入或更新 `.cursor/hooks.json`
+- 写入或更新 `.claude/settings.json`
+- 清理项目内旧版 Cursor、Claude、Codex hook 脚本
+- 跳过 Codex 项目级配置部署，并在输出中说明原因
 
-输出是一个 JSON，对应本次操作中：
+`--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`
 
@@ -284,7 +303,7 @@ npx ronds_ai@latest skills install demo-skill --tool codex,cursor --scope projec
 - `HOOK_REPORT_TIMEOUT_MS`: 请求超时时间，默认 `10000`
 - `HOOK_REPORT_TOKEN`: 如果设置，会以 `Authorization: Bearer <token>` 发送
 - `HOOK_REPORT_HEADERS`: 额外请求头，要求是 JSON 字符串
-- `HOOK_REQUEST_DRY_RUN=1`: 不发请求，只把事件打印到标准输出
+- `HOOK_REQUEST_DRY_RUN=1`: 不发请求。Claude / Cursor 会把事件打印到标准输出；Codex 仍输出合法的 PostToolUse hook command output schema
 
 默认上报地址：
 
@@ -322,3 +341,4 @@ https://aihub.ronds.com/api/api/v1/ai-code-events
 - `record` 和 `doctor` 目前支持 `claude`、`codex` 与 `cursor`
 - `skills install` 支持 `claude`、`codex`、`cursor`
 - 不支持的命令或参数会直接报错，并把错误写入 CLI 错误日志
+

package/bin/ronds_ai.js

@@ -65,7 +65,7 @@ function printUsage() {
     '  ronds_ai record <tool>',
     '  ronds_ai check record',
     '  ronds_ai doctor <tool>',
-    '  ronds_ai hooks deploy',
+    '  ronds_ai hooks deploy [--scope project|user] [--tool cursor|claude|codex]',
     '  ronds_ai skills install <name> [--tool claude,codex,cursor] [--scope project|global] [--project-dir <path>] [--force]',
     '',
     'Supported tools:',
@@ -80,6 +80,9 @@ function printUsage() {
     '  npx ronds_ai@latest doctor claude',
     '  npx ronds_ai@latest doctor cursor',
     '  npx ronds_ai@latest hooks deploy',
+  '  npx ronds_ai@latest hooks deploy --scope user',
+    '  npx ronds_ai@latest hooks deploy --tool cursor',
+    '  npx ronds_ai@latest hooks deploy --tool claude --scope user',
     '  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',
@@ -88,13 +91,8 @@ function printUsage() {
 }
 
 async function runHooksCommand(args) {
-  const [action] = args;
-
-  if (action !== 'deploy') {
-    throw new Error('Unsupported hooks command');
-  }
-
-  const result = deployHooks(process.cwd());
+  const options = parseHooksDeployArgs(args);
+  const result = deployHooks(process.cwd(), options);
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }
 
@@ -186,6 +184,60 @@ function parseSkillsInstallArgs(args) {
   };
 }
 
+function parseHooksDeployArgs(args) {
+  const [action, ...rest] = args;
+  if (action !== 'deploy') {
+    throw new Error('Unsupported hooks command');
+  }
+
+  const options = {
+    scope: 'project',
+    tool: '',
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const value = rest[index];
+
+    if (value === '--scope') {
+      index += 1;
+      options.scope = rest[index] || '';
+      continue;
+    }
+
+    if (value.startsWith('--scope=')) {
+      options.scope = value.slice('--scope='.length);
+      continue;
+    }
+
+    if (value === '--tool') {
+      index += 1;
+      options.tool = rest[index] || '';
+      continue;
+    }
+
+    if (value.startsWith('--tool=')) {
+      options.tool = value.slice('--tool='.length);
+      continue;
+    }
+
+    throw new Error(`Unsupported option: ${value}`);
+  }
+
+  if (!['project', 'user'].includes(options.scope)) {
+    throw new Error(`Unsupported hooks deploy scope: ${options.scope}`);
+  }
+
+  if (options.tool) {
+    const normalizedTool = options.tool.trim().toLowerCase();
+    if (!SUPPORTED_SOURCES.has(normalizedTool)) {
+      throw new Error(`Unsupported hooks deploy tool: ${options.tool}`);
+    }
+    options.tool = normalizedTool;
+  }
+
+  return options;
+}
+
 async function runSkillsCommand(args) {
   const { runSkillsInstall } = require('../lib/skills_install');
   const [action, ...rest] = args;