ronds_ai 0.1.20 → 0.1.22

package/README.md

@@ -7,11 +7,12 @@
 
 ## Requirements
 
-- Node.js `>=16`
-- `git`
-- `unzip`
-
-`git` 主要用于读取仓库信息和用户邮箱；`unzip` 用于 `skills install` 解压技能包。
+- Node.js `>=16`
+- `git`
+- `unzip`
+
+`git` 主要用于读取仓库信息和用户邮箱；`unzip` 用于 `skills install` 解压技能包。
+可选的 `analyze` 命令单独要求 Node.js `>=20`，不会改变 `record` 等现有命令的 Node 版本要求。
 
 ## Install
 
@@ -169,9 +170,65 @@ 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`
+**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 结果行。
+
+### `analyze`
+
+从 Claude Code 的会话 transcript 增量生成 Langfuse 轨迹：
+
+```bash
+ronds_ai analyze claude
+```
+
+该命令用于 `Stop` 和 `SessionEnd` Hook，不是必选功能，也不会由 `hooks deploy` 自动安装。它会在 Langfuse 中记录：
+
+- 每个对话 Turn 的根 Span
+- 每次 Assistant 消息对应的 LLM Generation 和 Token usage
+- Tool 调用的输入、输出和时间
+- Skill 标签及可选的 Skill 注入内容
+- 一层 Subagent 的 Generation 和 Tool 轨迹
+
+行为与 Langfuse Claude Observability Plugin 一致，只采集 transcript 中的 `text`、`tool_use` 和 `tool_result`，不上传 `thinking` block。状态和日志保存在 `~/.ronds_ai/analyze/`。
+
+Langfuse 连接信息已内置，Trace 的 `userId` 使用当前操作系统用户名。可选配置：
+
+- `CC_LANGFUSE_DEBUG=true`：启用详细日志
+- `CC_LANGFUSE_MAX_CHARS=<正整数>`：单个文本字段的最大字符数，默认 `20000`
+- `CC_LANGFUSE_SKILL_TAGS=false`：关闭 `skill:<name>` 标签
+- `CC_LANGFUSE_CAPTURE_SKILL_CONTENT=true`：把 Skill 注入内容写入 Tool 输出
+
+用户需要自行把以下条目合并到 Claude Code 的 hooks 配置，并停用其他 Langfuse Claude 插件以避免重复上传：
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ronds_ai@latest analyze claude"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ronds_ai@latest analyze claude"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Node.js 低于 20 或安装时使用了 `--omit=optional` 时，只有 `analyze` 会返回明确错误；`record` 等其他命令仍可运行。Hook payload 或上传处理失败时，`analyze` 保持 fail-open 并把诊断信息写入本地日志。
+
+### `doctor`
 
 检查当前目录下的 hook 配置和最近错误日志，方便排查接入问题。
 
@@ -286,6 +343,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) {
@@ -61,9 +62,10 @@ const SUPPORTED_SOURCES = new Set(['claude', 'cursor', 'codex', 'hermes']);
 
 function printUsage() {
   process.stderr.write([
-    'Usage:',
-    '  ronds_ai record <tool>',
-    '  ronds_ai check record',
+    'Usage:',
+    '  ronds_ai record <tool>',
+    '  ronds_ai analyze claude',
+    '  ronds_ai check record',
     '  ronds_ai doctor <tool>',
     '  ronds_ai hooks deploy [--scope project|user] [--tool cursor|claude|codex]',
     '  ronds_ai hooks deploy hermes',
@@ -76,7 +78,8 @@ function printUsage() {
     '  hermes',
     '',
     'Examples:',
-    '  npx ronds_ai@latest record claude',
+    '  npx ronds_ai@latest record claude',
+    '  npx ronds_ai@latest analyze claude',
     '  npx ronds_ai@latest record cursor',
     '  npx ronds_ai@latest check record',
     '  npx ronds_ai@latest doctor claude',
@@ -260,10 +263,26 @@ 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;
 
-  if (command === 'record') {
+  maybeStartHooksAutoSync({ command, args });
+
+  if (command === 'record') {
     const [source] = args;
     const normalizedSource = String(source || '').trim().toLowerCase();
 
@@ -272,9 +291,21 @@ async function run() {
     }
 
     await runCodeRecord(normalizedSource);
-    return;
-  }
-
+    return;
+  }
+
+  if (command === 'analyze') {
+    const [source] = args;
+    if (String(source || '').trim().toLowerCase() !== 'claude') {
+      throw new Error(`Unsupported analyze tool: ${source || ''}`);
+    }
+
+    // 仅在 analyze 分支中加载 Node 20+ 的可选 Langfuse 依赖，避免影响旧版 record。
+    const { runClaudeAnalyze } = require('../lib/analyze_claude');
+    await runClaudeAnalyze();
+    return;
+  }
+
   if (command === 'doctor') {
     const [tool] = args;
     const normalizedTool = String(tool || '').trim().toLowerCase();
@@ -303,11 +334,22 @@ async function run() {
     return;
   }
 
+  if (command === 'internal') {
+    await runInternalCommand(args);
+    return;
+  }
+
   throw new Error(`Unsupported command: ${command || ''}`);
 }
 
-run().catch((error) => {
-  const [, , command, ...args] = process.argv;
+run().catch((error) => {
+  if (error && error.code === 'ANALYZE_PREFLIGHT') {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const [, , command, ...args] = process.argv;
   let savedPath = '';
 
   try {

package/lib/analyze_claude.js

@@ -0,0 +1,471 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { getAnalyzeConfig } = require('./analyze_config');
+const { emitTurn } = require('./analyze_langfuse');
+const {
+  createSessionState,
+  getNewTurnsFromTranscript,
+  getSubagentTranscriptsByToolUseId,
+  getTurnsToEmit,
+} = require('./analyze_transcript');
+
+const ANALYZE_DIR = path.join(os.homedir(), '.ronds_ai', 'analyze');
+const STATE_FILE = path.join(ANALYZE_DIR, 'langfuse_state.json');
+const LOCK_FILE = path.join(ANALYZE_DIR, 'langfuse_state.lock');
+const LOG_FILE = path.join(ANALYZE_DIR, 'langfuse_hook.log');
+const LOCK_TIMEOUT_MS = 2000;
+const STALE_LOCK_MS = 30000;
+const SHUTDOWN_TIMEOUT_MS = 5000;
+const STATE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_LOG_BYTES = 5_000_000;
+
+/**
+ * 表示 analyze 启动前即可确定的环境错误。
+ */
+class AnalyzePreflightError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AnalyzePreflightError';
+    this.code = 'ANALYZE_PREFLIGHT';
+  }
+}
+
+/**
+ * 检查 analyze 所需的 Node.js 主版本。
+ */
+function assertAnalyzeNodeVersion(version = process.versions.node) {
+  const major = Number(String(version || '').split('.')[0]);
+  if (!Number.isInteger(major) || major < 20) {
+    throw new AnalyzePreflightError(
+      `ronds_ai analyze requires Node.js 20 or newer; current version is ${version || 'unknown'}.`,
+    );
+  }
+}
+
+/**
+ * 懒加载 analyze 专用的可选 Langfuse 依赖。
+ */
+function loadLangfuseSdk() {
+  try {
+    const { NodeSDK } = require('@opentelemetry/sdk-node');
+    const { LangfuseSpanProcessor } = require('@langfuse/otel');
+    const tracing = require('@langfuse/tracing');
+    return {
+      NodeSDK,
+      LangfuseSpanProcessor,
+      startObservation: tracing.startObservation,
+      propagateAttributes: tracing.propagateAttributes,
+    };
+  } catch {
+    throw new AnalyzePreflightError(
+      'ronds_ai analyze dependencies are unavailable. Reinstall without omitting optional dependencies.',
+    );
+  }
+}
+
+/**
+ * 从 stdin 读取 Claude Code Hook JSON。
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+/**
+ * 从 Hook payload 中解析 session 和 transcript。
+ */
+function extractHookContext(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return null;
+  }
+  const sessionId = payload.sessionId
+    || payload.session_id
+    || (payload.session && payload.session.id);
+  const transcriptPath = payload.transcriptPath
+    || payload.transcript_path
+    || (payload.transcript && payload.transcript.path);
+  if (typeof sessionId !== 'string' || !sessionId
+    || typeof transcriptPath !== 'string' || !transcriptPath) {
+    return null;
+  }
+  const resolvedPath = path.resolve(transcriptPath);
+  if (!fs.existsSync(resolvedPath)) {
+    return null;
+  }
+  const hookEventName = payload.hook_event_name || payload.hookEventName || '';
+  return {
+    sessionId,
+    transcriptPath: resolvedPath,
+    flushDeferredAgentTurns: hookEventName === 'SessionEnd',
+  };
+}
+
+/**
+ * 构造稳定的会话状态键。
+ */
+function getSessionStateKey(sessionId, transcriptPath) {
+  return crypto
+    .createHash('sha256')
+    .update(`${sessionId}::${transcriptPath}`, 'utf8')
+    .digest('hex');
+}
+
+/**
+ * 轮转超出上限的 analyze 日志。
+ */
+function rotateLogIfNeeded() {
+  if (!fs.existsSync(LOG_FILE) || fs.statSync(LOG_FILE).size < MAX_LOG_BYTES) {
+    return;
+  }
+  for (let index = 3; index >= 1; index -= 1) {
+    const source = index === 1 ? LOG_FILE : `${LOG_FILE}.${index - 1}`;
+    const target = `${LOG_FILE}.${index}`;
+    if (!fs.existsSync(source)) {
+      continue;
+    }
+    if (fs.existsSync(target)) {
+      fs.unlinkSync(target);
+    }
+    fs.renameSync(source, target);
+  }
+}
+
+/**
+ * 从日志文本中移除固定连接凭据。
+ */
+function redactLogMessage(message, config) {
+  let result = String(message || '');
+  for (const value of [config.secretKey, config.publicKey]) {
+    if (typeof value === 'string' && value) {
+      result = result.split(value).join('[REDACTED]');
+    }
+  }
+  return result;
+}
+
+/**
+ * 写入不影响 Hook 的本地诊断日志。
+ */
+function writeAnalyzeLog(level, message, config) {
+  try {
+    fs.mkdirSync(ANALYZE_DIR, { recursive: true });
+    rotateLogIfNeeded();
+    const safeMessage = redactLogMessage(message, config);
+    fs.appendFileSync(
+      LOG_FILE,
+      `${new Date().toISOString()} [${level}] ${safeMessage}\n`,
+      'utf8',
+    );
+  } catch {
+    // 日志失败不能影响 Claude Code Hook。
+  }
+}
+
+/**
+ * 仅在调试选项开启时写入详细日志。
+ */
+function writeAnalyzeDebug(message, config) {
+  if (config.debug) {
+    writeAnalyzeLog('DEBUG', message, config);
+  }
+}
+
+/**
+ * 加载全局 analyze 状态。
+ */
+function loadState() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 清理过期状态并原子写入状态文件。
+ */
+function saveState(state) {
+  const cutoff = Date.now() - STATE_RETENTION_MS;
+  for (const [key, value] of Object.entries(state)) {
+    const updatedAt = value && Date.parse(value.updatedAt || value.updated || '');
+    if (Number.isFinite(updatedAt) && updatedAt < cutoff) {
+      delete state[key];
+    }
+  }
+  fs.mkdirSync(ANALYZE_DIR, { recursive: true });
+  const tempPath = `${STATE_FILE}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  fs.renameSync(tempPath, STATE_FILE);
+}
+
+/**
+ * 将会话状态转换为可序列化结构。
+ */
+function serializeSessionState(sessionState) {
+  return {
+    offset: sessionState.offset,
+    buffer: sessionState.buffer,
+    turnCount: sessionState.turnCount,
+    pendingAgentTurns: sessionState.pendingAgentTurns,
+    pendingTaskNotifications: sessionState.pendingTaskNotifications,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * 等待指定毫秒数，计时器不阻止进程退出。
+ */
+function delay(milliseconds) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, milliseconds);
+    timer.unref();
+  });
+}
+
+/**
+ * 判断已有锁是否超过安全保留时间。
+ */
+function isLockStale() {
+  try {
+    return Date.now() - fs.statSync(LOCK_FILE).mtimeMs > STALE_LOCK_MS;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 使用 wx 文件创建跨平台独占锁。
+ */
+async function acquireLock() {
+  fs.mkdirSync(ANALYZE_DIR, { recursive: true });
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  while (Date.now() <= deadline) {
+    try {
+      const descriptor = fs.openSync(LOCK_FILE, 'wx');
+      fs.writeFileSync(descriptor, `${process.pid}\n`, 'utf8');
+      return descriptor;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') {
+        throw error;
+      }
+      if (isLockStale()) {
+        try {
+          fs.unlinkSync(LOCK_FILE);
+          continue;
+        } catch {
+          // 其他进程可能刚刚释放或替换了锁，继续重试。
+        }
+      }
+      await delay(50);
+    }
+  }
+  return null;
+}
+
+/**
+ * 释放当前进程持有的 analyze 锁。
+ */
+function releaseLock(descriptor) {
+  if (descriptor == null) {
+    return;
+  }
+  try {
+    fs.closeSync(descriptor);
+  } catch {
+    // 继续尝试移除锁文件。
+  }
+  try {
+    fs.unlinkSync(LOCK_FILE);
+  } catch {
+    // 锁文件可能已被系统或其他恢复逻辑清理。
+  }
+}
+
+/**
+ * 为异步操作增加最大等待时间。
+ */
+function withTimeout(promise, timeoutMs, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    timer.unref();
+    Promise.resolve(promise).then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * 初始化短生命周期 Langfuse OpenTelemetry SDK。
+ */
+function createLangfuseRuntime(sdkModules, config) {
+  const processor = new sdkModules.LangfuseSpanProcessor({
+    publicKey: config.publicKey,
+    secretKey: config.secretKey,
+    baseUrl: config.baseUrl,
+    exportMode: 'immediate',
+    timeout: 5,
+  });
+  const sdk = new sdkModules.NodeSDK({
+    spanProcessors: [processor],
+  });
+  sdk.start();
+  return {
+    sdk,
+    api: {
+      startObservation: sdkModules.startObservation,
+      propagateAttributes: sdkModules.propagateAttributes,
+    },
+  };
+}
+
+/**
+ * 在持锁状态下处理一次 Hook payload。
+ */
+async function processHookContext(context, config, sdkModules) {
+  const lock = await acquireLock();
+  if (lock == null) {
+    writeAnalyzeLog('INFO', 'analyze lock timeout; hook skipped', config);
+    return;
+  }
+
+  try {
+    const state = loadState();
+    const stateKey = getSessionStateKey(context.sessionId, context.transcriptPath);
+    const sessionState = createSessionState(state[stateKey]);
+    const subagents = getSubagentTranscriptsByToolUseId(context.transcriptPath);
+    writeAnalyzeDebug(
+      `discovered ${Object.keys(subagents).length} subagent transcript(s)`,
+      config,
+    );
+    const parsed = getNewTurnsFromTranscript(
+      context.transcriptPath,
+      sessionState,
+      subagents,
+      context.flushDeferredAgentTurns,
+    );
+    const turns = getTurnsToEmit(
+      parsed.turns,
+      parsed.sessionState,
+      context.flushDeferredAgentTurns,
+    );
+
+    if (turns.length === 0) {
+      state[stateKey] = serializeSessionState(parsed.sessionState);
+      saveState(state);
+      writeAnalyzeDebug(
+        `no new turn for session ${context.sessionId}`,
+        config,
+      );
+      return;
+    }
+
+    const runtime = createLangfuseRuntime(sdkModules, config);
+    try {
+      for (let index = 0; index < turns.length; index += 1) {
+        emitTurn(
+          runtime.api,
+          context.sessionId,
+          parsed.sessionState.turnCount + index + 1,
+          turns[index],
+          context.transcriptPath,
+          subagents,
+          config,
+        );
+      }
+      await withTimeout(
+        runtime.sdk.shutdown(),
+        SHUTDOWN_TIMEOUT_MS,
+        'Langfuse shutdown',
+      );
+    } catch (error) {
+      try {
+        await withTimeout(runtime.sdk.shutdown(), 1000, 'Langfuse cleanup');
+      } catch {
+        // 原始错误优先，清理错误不覆盖它。
+      }
+      throw error;
+    }
+
+    parsed.sessionState.turnCount += turns.length;
+    state[stateKey] = serializeSessionState(parsed.sessionState);
+    saveState(state);
+    writeAnalyzeLog(
+      'INFO',
+      `processed ${turns.length} turn(s) for session ${context.sessionId}`,
+      config,
+    );
+  } finally {
+    releaseLock(lock);
+  }
+}
+
+/**
+ * 执行 Claude Code analyze Hook 命令。
+ */
+async function runClaudeAnalyze() {
+  assertAnalyzeNodeVersion();
+  const sdkModules = loadLangfuseSdk();
+  const config = getAnalyzeConfig();
+  writeAnalyzeDebug('analyze hook started', config);
+  const raw = await readStdin();
+  writeAnalyzeDebug(`stdin received ${raw.length} chars`, config);
+  if (!raw.trim()) {
+    return;
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch (error) {
+    writeAnalyzeLog('INFO', `invalid hook payload: ${error.message}`, config);
+    return;
+  }
+  writeAnalyzeDebug(
+    `payload top-level keys: ${Object.keys(payload).sort().join(', ')}`,
+    config,
+  );
+  const context = extractHookContext(payload);
+  if (!context) {
+    writeAnalyzeLog('INFO', 'hook payload has no usable session or transcript', config);
+    return;
+  }
+
+  try {
+    await processHookContext(context, config, sdkModules);
+  } catch (error) {
+    const detail = error instanceof Error ? error.stack || error.message : String(error);
+    writeAnalyzeLog('INFO', `analyze hook failed: ${detail}`, config);
+  }
+}
+
+module.exports = {
+  ANALYZE_DIR,
+  AnalyzePreflightError,
+  assertAnalyzeNodeVersion,
+  extractHookContext,
+  getSessionStateKey,
+  processHookContext,
+  redactLogMessage,
+  runClaudeAnalyze,
+};