ronds_ai 0.1.19 → 0.1.21

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
@@ -251,6 +286,30 @@ Codex 推荐使用 `--scope user`，因为项目级 `.codex` 配置在未被用
 - `removedFiles`
 - `skipped`: 被跳过的工具及原因（仅在 project scope 下出现）
 
+### Hooks Auto Sync（自动后台同步）
+
+CLI 会**自动在后台检查并更新用户级 hooks 配置**，无需用户每次手动执行 `hooks deploy --scope user`。
+
+工作方式：
+
+1. 运行任意 CLI 命令时，进行轻量检查（多数情况下只读取一次 sentinel 文件的修改时间）
+2. 如果距离上次检查超过 24 小时，判断 hooks schema 版本是否落后
+3. 版本落后时，后台启动子进程自动执行 `hooks deploy --scope user` 和 `deploy hermes`
+4. 当前命令不等待后台同步完成，也不受后台同步失败的影响
+5. `record` 高频路径使用 sentinel fast path，额外成本约等于一次文件 stat
+
+可通过环境变量禁用：
+
+```bash
+RONDS_AI_DISABLE_HOOKS_AUTO_SYNC=1
+```
+
+注意：
+
+- auto-sync 只维护**用户级** hooks，不影响项目级配置
+- 后台同步失败时，错误记录到 `~/.ronds_ai/hooks_auto_sync_error.log`，不污染当前命令输出
+- 首次安装 hooks 仍建议执行 `ronds_ai hooks deploy --scope user`
+
 ### `skills install`
 
 下载一个技能包并安装到 Claude / Codex / Cursor 对应的技能目录。
@@ -334,11 +393,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,8 @@ 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 { maybeStartHooksAutoSync, runHooksAutoSync } = require('../lib/hooks_auto_sync');
 const { promptForText, promptYesNo } = require('../lib/skills_prompt');
 
 function writeWorkerSummary(result) {
@@ -57,7 +58,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 +67,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 +94,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`);
@@ -251,9 +261,25 @@ async function runSkillsCommand(args) {
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }
 
+/**
+ * 内部命令分发。当前只支持 hooks auto-sync。
+ */
+async function runInternalCommand(args) {
+  const [subcommand, ...subargs] = args;
+
+  if (subcommand === 'hooks' && subargs[0] === 'auto-sync') {
+    runHooksAutoSync();
+    return;
+  }
+
+  throw new Error('Unsupported internal command');
+}
+
 async function run() {
   const [, , command, ...args] = process.argv;
 
+  maybeStartHooksAutoSync({ command, args });
+
   if (command === 'record') {
     const [source] = args;
     const normalizedSource = String(source || '').trim().toLowerCase();
@@ -294,6 +320,11 @@ async function run() {
     return;
   }
 
+  if (command === 'internal') {
+    await runInternalCommand(args);
+    return;
+  }
+
   throw new Error(`Unsupported command: ${command || ''}`);
 }
 

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_auto_sync.js

@@ -0,0 +1,397 @@
+/**
+ * hooks_auto_sync.js
+ *
+ * 用户级 Hooks 自动同步模块。
+ *
+ * 提供轻量的前台检查（maybeStartHooksAutoSync）和后端子进程同步（runHooksAutoSync），
+ * 让 CLI 命令能无感自动维护用户级 hooks 配置（Claude/Cursor/Hermes/Codex）。
+ *
+ * 快速路径：sentinel 文件 mtime + TTL，避免高频命令（如 record）反复读取状态 JSON。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+// ---------------------------------------------------------------------------
+// 常量
+// ---------------------------------------------------------------------------
+
+/** 当前 hooks schema 版本。当用户级 hooks deploy 输出发生变化时 +1。 */
+const HOOKS_SCHEMA_VERSION = 1;
+
+/** sentinel 有效时长：24 小时 */
+const HOOKS_AUTO_SYNC_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** lock 文件视为 stale 的超时时长：10 分钟 */
+const STALE_LOCK_TIMEOUT_MS = 10 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// 路径解析
+// ---------------------------------------------------------------------------
+
+function getAutoSyncDir() {
+  return path.join(os.homedir(), '.ronds_ai');
+}
+
+function getStateFilePath() {
+  return path.join(getAutoSyncDir(), 'hooks_state.json');
+}
+
+function getSentinelFilePath() {
+  return path.join(getAutoSyncDir(), 'hooks_auto_sync_sentinel');
+}
+
+function getLockFilePath() {
+  return path.join(getAutoSyncDir(), 'hooks_auto_sync.lock');
+}
+
+function getErrorLogPath() {
+  return path.join(getAutoSyncDir(), 'hooks_auto_sync_error.log');
+}
+
+function ensureAutoSyncDir() {
+  const dir = getAutoSyncDir();
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// ---------------------------------------------------------------------------
+// Sentinel fast path（步骤 3）
+// ---------------------------------------------------------------------------
+
+/**
+ * 快速跳过检查——sentinel 文件存在且 mtime 在 TTL 内。
+ * @param {number} now - Date.now()
+ * @returns {boolean}
+ */
+function shouldFastSkipAutoSync(now) {
+  try {
+    const stat = fs.statSync(getSentinelFilePath());
+    return now - stat.mtimeMs < HOOKS_AUTO_SYNC_CHECK_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 更新 sentinel 文件的 mtime。
+ * 文件不存在则创建空文件。
+ * @param {number} now - Date.now()
+ */
+function touchAutoSyncSentinel(now) {
+  ensureAutoSyncDir();
+  const sentinelPath = getSentinelFilePath();
+  const atime = Math.floor(now / 1000);
+  const mtime = Math.floor(now / 1000);
+  try {
+    fs.utimesSync(sentinelPath, atime, mtime);
+  } catch {
+    // 文件不存在，创建空文件
+    fs.writeFileSync(sentinelPath, '');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 状态文件读写（步骤 4）
+// ---------------------------------------------------------------------------
+
+/**
+ * 读取 hooks_state.json。
+ * 文件不存在、内容为空、JSON 解析失败或顶层非对象时返回空对象。
+ * @returns {object}
+ */
+function readHooksAutoSyncState() {
+  try {
+    const content = fs.readFileSync(getStateFilePath(), 'utf-8');
+    if (!content.trim()) return {};
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 写入 hooks_state.json。
+ * @param {{ schemaVersion?: number, lastCheckedAt?: number, lastSyncedAt?: number }} state
+ */
+function writeHooksAutoSyncState(state) {
+  ensureAutoSyncDir();
+  const data = {
+    schemaVersion: Number(state.schemaVersion) || 0,
+    lastCheckedAt: Number(state.lastCheckedAt) || 0,
+    lastSyncedAt: Number(state.lastSyncedAt) || 0,
+  };
+  fs.writeFileSync(getStateFilePath(), JSON.stringify(data, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// 命令过滤逻辑（步骤 5）
+// ---------------------------------------------------------------------------
+
+/**
+ * 判断当前命令是否应完全跳过 auto-sync。
+ * @param {string} command - 命令名称
+ * @returns {boolean}
+ */
+function shouldSkipHooksAutoSync(command) {
+  if (process.env.RONDS_AI_DISABLE_HOOKS_AUTO_SYNC === '1') return true;
+  if (command === 'hooks' || command === 'internal') return true;
+  if (!command) return true;
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// TTL 与版本判断（步骤 6）
+// ---------------------------------------------------------------------------
+
+/**
+ * 根据状态和当前时间判断是否需要调度后台同步。
+ *
+ * @param {object} state - 从状态文件读取的状态
+ * @param {number} now - Date.now()
+ * @returns {'skip' | 'update-timestamp' | 'schedule'}
+ */
+function shouldScheduleHooksAutoSync(state, now) {
+  const lastCheckedAt = Number(state.lastCheckedAt || 0);
+
+  // 仍在 TTL 窗口内，跳过
+  if (now - lastCheckedAt < HOOKS_AUTO_SYNC_CHECK_TTL_MS) {
+    return 'skip';
+  }
+
+  const schemaVersion = Number(state.schemaVersion || 0);
+
+  // 版本已是最新，仅更新时间戳
+  if (schemaVersion >= HOOKS_SCHEMA_VERSION) {
+    return 'update-timestamp';
+  }
+
+  // 版本落后，需要调度同步
+  return 'schedule';
+}
+
+// ---------------------------------------------------------------------------
+// 后台进程启动（步骤 7）
+// ---------------------------------------------------------------------------
+
+/**
+ * 启动后台子进程执行用户级 hooks deploy。
+ * 使用 process.execPath + require.resolve 确保：
+ *   - Windows 上不需 shell，detach 可靠
+ *   - 与当前进程使用相同的 Node 版本
+ *   - 指向本地已安装的代码（版本一致）
+ */
+function spawnHooksAutoSyncProcess() {
+  try {
+    const cliEntry = require.resolve('../bin/ronds_ai.js');
+    const child = spawn(process.execPath, [cliEntry, 'internal', 'hooks', 'auto-sync'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.on('error', saveHooksAutoSyncError);
+    child.unref();
+  } catch (error) {
+    saveHooksAutoSyncError(error);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// maybeStartHooksAutoSync（步骤 8）
+// ---------------------------------------------------------------------------
+
+/**
+ * 轻量前台检查函数。
+ *
+ * 所有 CLI 命令在分发前均可调用此函数，它会在绝大多数调用中快速返回。
+ *
+ * @param {{ command: string, args?: string[] }} params
+ */
+function maybeStartHooksAutoSync({ command, args } = {}) {
+  try {
+    if (shouldSkipHooksAutoSync(command)) return;
+
+    const now = Date.now();
+    if (shouldFastSkipAutoSync(now)) return;
+
+    const state = readHooksAutoSyncState();
+    const decision = shouldScheduleHooksAutoSync(state, now);
+
+    if (decision === 'skip') {
+      touchAutoSyncSentinel(now);
+      return;
+    }
+
+    if (decision === 'update-timestamp') {
+      writeHooksAutoSyncState({
+        schemaVersion: Number(state.schemaVersion || 0),
+        lastCheckedAt: now,
+        lastSyncedAt: Number(state.lastSyncedAt || 0),
+      });
+      touchAutoSyncSentinel(now);
+      return;
+    }
+
+    // decision === 'schedule'
+    touchAutoSyncSentinel(now);
+    spawnHooksAutoSyncProcess();
+  } catch (error) {
+    saveHooksAutoSyncError(error);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lock 文件管理（步骤 9）
+// ---------------------------------------------------------------------------
+
+/**
+ * 获取 auto-sync 全局锁。
+ * 使用原子创建（'wx'）防止并发。
+ *
+ * @returns {number | null} lock 文件描述符，获取失败返回 null
+ */
+function acquireHooksAutoSyncLock() {
+  const lockPath = getLockFilePath();
+  ensureAutoSyncDir();
+
+  // 首次尝试创建
+  try {
+    const fd = fs.openSync(lockPath, 'wx');
+    fs.writeSync(fd, JSON.stringify({ pid: process.pid, time: Date.now() }) + '\n');
+    return fd;
+  } catch (err) {
+    if (err.code !== 'EEXIST') return null;
+  }
+
+  // 文件已存在，检查是否 stale
+  try {
+    const stat = fs.statSync(lockPath);
+    if (Date.now() - stat.mtimeMs > STALE_LOCK_TIMEOUT_MS) {
+      fs.unlinkSync(lockPath);
+      // 重试一次
+      try {
+        const fd = fs.openSync(lockPath, 'wx');
+        fs.writeSync(fd, JSON.stringify({ pid: process.pid, time: Date.now() }) + '\n');
+        return fd;
+      } catch {
+        return null;
+      }
+    }
+  } catch {
+    // stat 失败，尝试直接创建
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      return fd;
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 释放 auto-sync 全局锁。
+ * @param {number} fd - 文件描述符
+ */
+function releaseHooksAutoSyncLock(fd) {
+  try {
+    fs.closeSync(fd);
+  } catch {
+    // 忽略关闭失败
+  }
+  try {
+    fs.unlinkSync(getLockFilePath());
+  } catch {
+    // 忽略删除失败
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 后台同步函数 runHooksAutoSync（步骤 10）
+// ---------------------------------------------------------------------------
+
+/**
+ * 执行用户级 hooks auto-sync。
+ *
+ * 此函数由后台子进程（ronds_ai internal hooks auto-sync）调用。
+ * 不向 stdout 输出，错误写入本地日志文件。
+ */
+function runHooksAutoSync() {
+  const lock = acquireHooksAutoSyncLock();
+  if (!lock) return; // 已有进程在同步
+
+  const now = Date.now();
+
+  try {
+    const { deployHooks, deployHermesHook } = require('./hooks_deploy');
+
+    deployHooks(os.homedir(), { scope: 'user' });
+    deployHermesHook();
+
+    writeHooksAutoSyncState({
+      schemaVersion: HOOKS_SCHEMA_VERSION,
+      lastCheckedAt: now,
+      lastSyncedAt: now,
+    });
+    touchAutoSyncSentinel(now);
+  } catch (error) {
+    saveHooksAutoSyncError(error);
+  } finally {
+    releaseHooksAutoSyncLock(lock);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 错误记录
+// ---------------------------------------------------------------------------
+
+/**
+ * 将 auto-sync 错误写入本地日志文件。
+ * @param {Error | string} error
+ */
+function saveHooksAutoSyncError(error) {
+  try {
+    ensureAutoSyncDir();
+    const timestamp = new Date().toISOString();
+    const message = error instanceof Error ? error.stack || error.message : String(error);
+    const entry = [
+      `--- ${timestamp} ---`,
+      `HOOKS_SCHEMA_VERSION=${HOOKS_SCHEMA_VERSION}`,
+      `node=${process.version}`,
+      `platform=${process.platform}`,
+      `error=${message}`,
+      '',
+    ].join('\n');
+
+    fs.appendFileSync(getErrorLogPath(), entry, 'utf-8');
+  } catch {
+    // 错误记录失败时不做任何事，避免连锁异常
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 导出
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  HOOKS_SCHEMA_VERSION,
+  maybeStartHooksAutoSync,
+  runHooksAutoSync,
+
+  // 以下为测试和内部使用导出的函数
+  shouldSkipHooksAutoSync,
+  shouldFastSkipAutoSync,
+  shouldScheduleHooksAutoSync,
+  touchAutoSyncSentinel,
+  readHooksAutoSyncState,
+  writeHooksAutoSyncState,
+  acquireHooksAutoSyncLock,
+  releaseHooksAutoSyncLock,
+};

package/lib/hooks_deploy.js

@@ -2,6 +2,7 @@
 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';
@@ -604,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.19",
+  "version": "0.1.21",
   "description": "CLI for reporting AI code edit events.",
   "bin": {
     "ronds_ai": "bin/ronds_ai.js"
@@ -13,7 +13,8 @@
     "node": ">=16"
   },
   "dependencies": {
-    "comment-json": "^4.2.5"
+    "comment-json": "^4.2.5",
+    "js-yaml": "^5.1.0"
   },
   "license": "MIT"
 }