ronds_ai 0.1.20 → 0.1.21

package/README.md

@@ -286,6 +286,30 @@ hooks_auto_accept: true
 - `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 对应的技能目录。

package/bin/ronds_ai.js

@@ -11,6 +11,7 @@ const {
 } = require('../lib/check_record');
 const { runDoctor } = require('../lib/doctor');
 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) {
@@ -260,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();
@@ -303,6 +320,11 @@ async function run() {
     return;
   }
 
+  if (command === 'internal') {
+    await runInternalCommand(args);
+    return;
+  }
+
   throw new Error(`Unsupported command: ${command || ''}`);
 }
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ronds_ai",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "CLI for reporting AI code edit events.",
   "bin": {
     "ronds_ai": "bin/ronds_ai.js"