ronds_ai 0.1.18 → 0.1.20

package/README.md

@@ -2,7 +2,7 @@
 
 `ronds_ai` 是一个命令行工具，主要用于两类事情：
 
-- 接收 Claude / Cursor 的 hook 事件，整理成统一的代码变更事件并上报
+- 接收 Claude / Cursor / Hermes / Codex 的 hook 事件，整理成统一的代码变更事件并上报
 - 帮助项目写入对应的 hook 配置，以及安装 Skills 到 Claude / Codex / Cursor
 
 ## Requirements
@@ -97,7 +97,7 @@ npx ronds_ai@latest check record --no-prompt
 
 ### `record`
 
-从标准输入读取 Claude、Codex 或 Cursor 的 hook payload，转换为统一事件后发送到服务端。
+从标准输入读取 Claude、Codex、Cursor 或 Hermes 的 hook payload，转换为统一事件后发送到服务端。
 
 ```bash
 ronds_ai record <tool>
@@ -108,6 +108,7 @@ ronds_ai record <tool>
 - `claude`
 - `codex`
 - `cursor`
+- `hermes`
 
 示例：
 
@@ -115,9 +116,10 @@ ronds_ai record <tool>
 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 的 hook 配置调用。
+这个命令通常不是手工执行，而是被 Claude / Codex / Cursor 或 Hermes 的 hook 配置调用。
 
 行为说明：
 
@@ -151,6 +153,7 @@ npx ronds_ai@latest record cursor
 - Claude: `PostToolUse`
 - Codex: `PostToolUse`（`apply_patch` 编辑后采集）
 - Cursor: `afterFileEdit`
+- **Hermes**: `post_tool_call`
 
 其中 Claude 仅处理这些工具产生的事件：
 
@@ -166,6 +169,8 @@ Codex 输出示例：
 {"continue":true,"hookSpecificOutput":{"hookEventName":"PostToolUse"}}
 ```
 
+**Hermes** 使用 [Shell hooks](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks#shell-hooks)，通过 `~/.hermes/config.yaml` 中的 `hooks.post_tool_call` 配置监听 `write_file` 和 `patch` 工具的调用。Hermes Shell hook 不要求特定 stdout 格式，成功/失败信息直接输出 JSON 结果行。
+
 ### `doctor`
 
 检查当前目录下的 hook 配置和最近错误日志，方便排查接入问题。
@@ -179,6 +184,7 @@ ronds_ai doctor <tool>
 - `claude`
 - `codex`
 - `cursor`
+- `hermes`
 
 示例：
 
@@ -186,6 +192,7 @@ ronds_ai doctor <tool>
 npx ronds_ai@latest doctor claude
 npx ronds_ai@latest doctor codex
 npx ronds_ai@latest doctor cursor
+npx ronds_ai@latest doctor hermes
 ```
 
 输出内容包括：
@@ -210,6 +217,11 @@ Cursor 会检查：
 
 - `.cursor/hooks.json`
 
+Hermes 会检查：
+
+- `~/.hermes/config.yaml` 是否存在
+- 该文件中是否有 `hooks.post_tool_call` 下 `matcher: "write_file|patch"` 的 hook 条目
+
 ### `hooks deploy`
 
 在当前项目目录或用户目录生成/更新 Claude / Codex / Cursor 的 hook 配置。
@@ -241,6 +253,29 @@ npx ronds_ai@latest hooks deploy --scope user
 
 Codex 推荐使用 `--scope user`，因为项目级 `.codex` 配置在未被用户显式信任的项目中会被 Codex 忽略。
 
+#### Hermes Shell Hook 部署
+
+```bash
+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` 的效果：
+
+```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
@@ -334,11 +369,13 @@ https://aihub.ronds.com/api/api/v1/ai-code-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`
+- `record` 和 `doctor` 目前支持 `claude`、`codex`、`cursor`、`hermes`
+- `hooks deploy` 支持 `claude`、`codex`、`cursor`、`hermes`（hermes 为独立子命令）
 - `skills install` 支持 `claude`、`codex`、`cursor`
 - 不支持的命令或参数会直接报错，并把错误写入 CLI 错误日志
 

package/bin/ronds_ai.js

@@ -10,7 +10,7 @@ const {
   savePersistentWorkerId,
 } = require('../lib/check_record');
 const { runDoctor } = require('../lib/doctor');
-const { deployHooks } = require('../lib/hooks_deploy');
+const { deployHooks, deployHermesHook } = require('../lib/hooks_deploy');
 const { promptForText, promptYesNo } = require('../lib/skills_prompt');
 
 function writeWorkerSummary(result) {
@@ -57,7 +57,7 @@ function stripCheckFlags(args) {
   return args.filter((value) => value !== '--no-prompt');
 }
 
-const SUPPORTED_SOURCES = new Set(['claude', 'cursor', 'codex']);
+const SUPPORTED_SOURCES = new Set(['claude', 'cursor', 'codex', 'hermes']);
 
 function printUsage() {
   process.stderr.write([
@@ -66,12 +66,14 @@ function printUsage() {
     '  ronds_ai check record',
     '  ronds_ai doctor <tool>',
     '  ronds_ai hooks deploy [--scope project|user] [--tool cursor|claude|codex]',
+    '  ronds_ai hooks deploy hermes',
     '  ronds_ai skills install <name> [--tool claude,codex,cursor] [--scope project|global] [--project-dir <path>] [--force]',
     '',
     'Supported tools:',
     '  claude',
     '  cursor',
     '  codex',
+    '  hermes',
     '',
     'Examples:',
     '  npx ronds_ai@latest record claude',
@@ -91,6 +93,13 @@ function printUsage() {
 }
 
 async function runHooksCommand(args) {
+  // Hermes deploy 走独立路径（YAML 格式、用户级配置，与现有 JSON 部署不同）
+  if (args[0] === 'deploy' && args[1] === 'hermes') {
+    const result = deployHermesHook();
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
   const options = parseHooksDeployArgs(args);
   const result = deployHooks(process.cwd(), options);
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/lib/code_record.js

@@ -14,6 +14,8 @@ const CLAUDE_SUPPORTED_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
 const CURSOR_SUPPORTED_HOOK_EVENT = 'afterFileEdit';
 const CODEX_SUPPORTED_HOOK_EVENT = 'PostToolUse';
 const CODEX_SUPPORTED_TOOL = 'apply_patch';
+const HERMES_SUPPORTED_HOOK_EVENT = 'post_tool_call';
+const HERMES_SUPPORTED_TOOLS = new Set(['write_file', 'patch']);
 
 // 构造 Codex PostToolUse hook 要求的标准输出，避免 stdout 出现 schema 之外的字段。
 function buildCodexPostToolUseOutput() {
@@ -207,6 +209,31 @@ function resolveClaudeAbsoluteFilePath(filePath, payload) {
   return path.resolve(process.cwd(), rawPath);
 }
 
+function resolveHermesAbsoluteFilePath(filePath, payload) {
+  const rawPath = String(filePath || '').trim();
+  if (!rawPath) {
+    return '';
+  }
+
+  if (path.isAbsolute(rawPath)) {
+    return path.normalize(rawPath);
+  }
+
+  const candidateBases = [
+    payload.cwd,
+    process.cwd(),
+  ].filter(Boolean);
+
+  for (const base of candidateBases) {
+    const candidate = path.resolve(base, rawPath);
+    if (fs.existsSync(candidate) || fs.existsSync(path.dirname(candidate))) {
+      return candidate;
+    }
+  }
+
+  return path.resolve(process.cwd(), rawPath);
+}
+
 function resolveCursorAbsoluteFilePath(filePath, payload) {
   const rawPath = String(filePath || '').trim();
   if (!rawPath) {
@@ -562,6 +589,73 @@ function buildCodexEvents(payload, source) {
   return buildCodexApplyPatchEvents(payload, source, parseApplyPatchFiles(patchText));
 }
 
+function buildHermesEvents(payload, source) {
+  const hookEvent = payload.hook_event_name || payload.hookEvent;
+  const toolName = payload.tool_name || payload.toolName;
+
+  if (hookEvent !== HERMES_SUPPORTED_HOOK_EVENT || !HERMES_SUPPORTED_TOOLS.has(toolName)) {
+    return [];
+  }
+
+  const toolInput = payload.tool_input || payload.toolInput || {};
+
+  // write_file — 全量写入，等价于 Claude 的 Write
+  if (toolName === 'write_file') {
+    const absoluteFilePath = resolveHermesAbsoluteFilePath(toolInput.path, payload);
+    const { repoRoot, git, repoRelativePath } = getGitInfo(absoluteFilePath);
+    const workerId = resolveWorkerId(repoRoot);
+    const changeInfo = buildWriteChange(toolInput);
+
+    return [{
+      event_id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      source,
+      worker_id: workerId,
+      git,
+      file: {
+        path: repoRelativePath || String(toolInput.path || ''),
+        operation: changeInfo.operation,
+      },
+      changes: changeInfo.changes,
+    }];
+  }
+
+  // patch — 分两种子模式
+  if (toolName === 'patch') {
+    // replace 模式 — 锚定替换，等价于 Claude 的 Edit
+    if (toolInput.mode !== 'patch') {
+      const absoluteFilePath = resolveHermesAbsoluteFilePath(toolInput.path, payload);
+      const { repoRoot, git, repoRelativePath } = getGitInfo(absoluteFilePath);
+      const workerId = resolveWorkerId(repoRoot);
+      const changeInfo = buildEditChange(toolInput);
+
+      return [{
+        event_id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        source,
+        worker_id: workerId,
+        git,
+        file: {
+          path: repoRelativePath || String(toolInput.path || ''),
+          operation: changeInfo.operation,
+        },
+        changes: changeInfo.changes,
+      }];
+    }
+
+    // patch 模式 — V4A 多文件补丁，等价于 Codex 的 apply_patch
+    const patchText = toolInput.patch || '';
+    if (!patchText) {
+      return [];
+    }
+
+    const patchFiles = parseApplyPatchFiles(patchText);
+    return buildCodexApplyPatchEvents(payload, source, patchFiles);
+  }
+
+  return [];
+}
+
 function loadRequestConfig() {
   const url = process.env.HOOK_REPORT_URL || process.env.CHANGE_REPORT_URL || DEFAULT_HOOK_REPORT_URL;
   const timeoutMs = Number(process.env.HOOK_REPORT_TIMEOUT_MS || DEFAULT_TIMEOUT_MS);
@@ -714,6 +808,10 @@ function buildEvents(payload, source) {
     return buildCodexEvents(payload, source);
   }
 
+  if (source === 'hermes') {
+    return buildHermesEvents(payload, source);
+  }
+
   const singleEvent = buildEvent(payload, source);
   return singleEvent ? [singleEvent] : [];
 }

package/lib/doctor.js

@@ -2,8 +2,9 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { runGit } = require('./git');
+const yaml = require('js-yaml');
 
-const SUPPORTED_TOOLS = new Set(['claude', 'codex', 'cursor']);
+const SUPPORTED_TOOLS = new Set(['claude', 'codex', 'cursor', 'hermes']);
 
 function getFailedEventDir() {
   return path.join(os.homedir(), '.ronds_ai', 'failed-events');
@@ -24,6 +25,35 @@ function readRecentLogs(tool) {
 }
 
 function getConfigChecks(tool, baseDir) {
+  if (tool === 'hermes') {
+    const hermesConfig = path.join(os.homedir(), '.hermes', 'config.yaml');
+    let hookEntryFound = false;
+
+    if (fs.existsSync(hermesConfig)) {
+      try {
+        const raw = fs.readFileSync(hermesConfig, 'utf8');
+        const parsed = yaml.load(raw) || {};
+        const postToolCall = parsed.hooks && parsed.hooks.post_tool_call;
+        if (Array.isArray(postToolCall)) {
+          hookEntryFound = postToolCall.some((entry) =>
+            entry && entry.matcher === 'write_file|patch'
+          );
+        }
+      } catch {
+        // 解析失败，不做深度校验
+      }
+    }
+
+    return [
+      {
+        label: '~/.hermes/config.yaml',
+        path: hermesConfig,
+        exists: fs.existsSync(hermesConfig),
+        hookEntryFound,
+      },
+    ];
+  }
+
   if (tool === 'cursor') {
     return [
       {

package/lib/hooks_deploy.js

@@ -1,6 +1,8 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const commentJson = require('comment-json');
+const yaml = require('js-yaml');
 
 const CURSOR_COMMAND = 'npx ronds_ai@latest record cursor';
 const CLAUDE_COMMAND = 'npx ronds_ai@latest record claude';
@@ -42,7 +44,10 @@ function readJsonFile(filePath, fallback) {
 
   let data;
   try {
-    data = JSON.parse(raw);
+    // comment-json 容忍 JSONC 注释和尾随逗号。~/.claude/settings.json 等
+    // Claude/Cursor 配置文件官方支持 JSONC，必须容忍用户加的注释。
+    // 注意：写回时仍用 JSON.stringify，原文件中的注释会被丢弃。
+    data = commentJson.parse(raw);
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     throw new Error(`Invalid JSON in ${filePath}: ${detail}`);
@@ -424,19 +429,19 @@ function generateRondsHookBlocks(newline) {
   ].join(newline);
 }
 
-function ensureCodexRequirementsToml(reqPath) {
-  const exists = fs.existsSync(reqPath);
-  let content = exists ? fs.readFileSync(reqPath, 'utf8') : '';
-  if (content.charCodeAt(0) === 0xFEFF) {
-    content = content.slice(1);
-  }
-  const newline = content.includes('\r\n') ? '\r\n' : '\n';
+function ensureCodexRequirementsToml(reqPath) {
+  const exists = fs.existsSync(reqPath);
+  let content = exists ? fs.readFileSync(reqPath, 'utf8') : '';
+  if (content.charCodeAt(0) === 0xFEFF) {
+    content = content.slice(1);
+  }
+  const newline = content.includes('\r\n') ? '\r\n' : '\n';
 
   content = ensureCodexHooksFeatureFlag(content);
   content = ensureCodexManagedDir(content, reqPath);
   content = removeRondsBlocksFromToml(content);
-  content = content.replace(/[\t ]*\r?\n*$/, newline);
-  content += generateRondsHookBlocks(newline);
+  content = content.replace(/[\t ]*\r?\n*$/, newline);
+  content += generateRondsHookBlocks(newline);
 
   const changed = writeTextFileIfChanged(reqPath, content);
   return { exists, changed };
@@ -527,16 +532,16 @@ function cleanupClaudeLocalSettings(localCandidates, result) {
   }
 }
 
-// 将系统级 Codex requirements.toml 的权限错误转换成面向用户的部署提示。
-function wrapCodexPermissionError(error, codexRequirementsPath) {
-  const code = isPlainObject(error) ? error.code : '';
+// 将系统级 Codex requirements.toml 的权限错误转换成面向用户的部署提示。
+function wrapCodexPermissionError(error, codexRequirementsPath) {
+  const code = isPlainObject(error) ? error.code : '';
   if (code !== 'EACCES' && code !== 'EPERM') {
     return error;
   }
 
-  const wrapped = new Error(
-    `Codex 部署需要管理员/root 权限，无法写入 ${codexRequirementsPath}。请以管理员身份重新运行 hooks deploy --scope user。`,
-  );
+  const wrapped = new Error(
+    `Codex 部署需要管理员/root 权限，无法写入 ${codexRequirementsPath}。请以管理员身份重新运行 hooks deploy --scope user。`,
+  );
   wrapped.cause = error;
   wrapped.code = code;
   return wrapped;
@@ -600,6 +605,82 @@ function deployHooks(targetDir = process.cwd(), options = {}) {
   return result;
 }
 
+const HERMES_CONFIG_PATH = path.join(os.homedir(), '.hermes', 'config.yaml');
+const HERMES_MATCHER = 'write_file|patch';
+const HERMES_COMMAND = 'npx ronds_ai@latest record hermes';
+
+function isHermesHookEntry(entry) {
+  return isPlainObject(entry)
+    && entry.matcher === HERMES_MATCHER
+    && entry.command === HERMES_COMMAND;
+}
+
+function deployHermesHook() {
+  const exists = fs.existsSync(HERMES_CONFIG_PATH);
+  let config = {};
+
+  if (exists) {
+    const raw = fs.readFileSync(HERMES_CONFIG_PATH, 'utf8');
+    if (raw.trim()) {
+      config = yaml.load(raw) || {};
+    }
+  }
+
+  if (!isPlainObject(config)) {
+    config = {};
+  }
+
+  const result = {
+    tool: 'hermes',
+    configPath: HERMES_CONFIG_PATH,
+    created: !exists,
+    updated: false,
+    details: [],
+  };
+
+  // 确保 hooks.post_tool_call 存在
+  const hooks = isPlainObject(config.hooks) ? { ...config.hooks } : {};
+  const postToolCall = Array.isArray(hooks.post_tool_call) ? hooks.post_tool_call.slice() : [];
+
+  // 检查是否已有我们的条目
+  const existingEntry = postToolCall.find(isHermesHookEntry);
+
+  if (!existingEntry) {
+    // 移除旧的 ronds 条目（如有），再插入新条目
+    const filtered = postToolCall.filter((entry) => !isHermesHookEntry(entry));
+    filtered.push({
+      matcher: HERMES_MATCHER,
+      command: HERMES_COMMAND,
+      timeout: 30,
+    });
+    hooks.post_tool_call = filtered;
+    result.details.push('Added Hermes shell hook entry for write_file|patch');
+    result.updated = true;
+  }
+
+  config.hooks = hooks;
+
+  // 如果 hooks_auto_accept 未设置，添加它（首次运行跳过交互确认）
+  if (config.hooks_auto_accept === undefined) {
+    config.hooks_auto_accept = true;
+    result.details.push('Set hooks_auto_accept: true');
+    result.updated = true;
+  }
+
+  if (result.updated || result.created) {
+    const yamlContent = yaml.dump(config, {
+      lineWidth: -1,
+      noRefs: true,
+      sortKeys: false,
+    });
+    ensureDir(path.dirname(HERMES_CONFIG_PATH));
+    fs.writeFileSync(HERMES_CONFIG_PATH, yamlContent, 'utf8');
+  }
+
+  return result;
+}
+
 module.exports = {
   deployHooks,
+  deployHermesHook,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ronds_ai",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "CLI for reporting AI code edit events.",
   "bin": {
     "ronds_ai": "bin/ronds_ai.js"
@@ -12,5 +12,9 @@
   "engines": {
     "node": ">=16"
   },
+  "dependencies": {
+    "comment-json": "^4.2.5",
+    "js-yaml": "^5.1.0"
+  },
   "license": "MIT"
 }