ronds_ai 0.1.22 → 0.1.24

package/README.md

@@ -7,12 +7,12 @@
 
 ## Requirements
 
-- Node.js `>=16`
-- `git`
-- `unzip`
-
-`git` 主要用于读取仓库信息和用户邮箱；`unzip` 用于 `skills install` 解压技能包。
-可选的 `analyze` 命令单独要求 Node.js `>=20`，不会改变 `record` 等现有命令的 Node 版本要求。
+- Node.js `>=16`
+- `git`
+- `unzip`
+
+`git` 主要用于读取仓库信息和用户邮箱；`unzip` 用于 `skills install` 解压技能包。
+可选的 `analyze` 命令单独要求 Node.js `>=20`，不会改变 `record` 等现有命令的 Node 版本要求。
 
 ## Install
 
@@ -170,65 +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 结果行。
-
-### `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`
+**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` 自动安装（project 或 user scope，未用 `--tool` 排除 claude 时）。它会在 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` 优先使用当前项目的 `git user.email`，读取不到时回退到当前操作系统用户名。可选配置：
+
+- `CC_LANGFUSE_DEBUG=true`：启用详细日志
+- `CC_LANGFUSE_MAX_CHARS=<正整数>`：单个文本字段的最大字符数，默认 `20000`
+- `CC_LANGFUSE_SKILL_TAGS=false`：关闭 `skill:<name>` 标签
+- `CC_LANGFUSE_CAPTURE_SKILL_CONTENT=true`：把 Skill 注入内容写入 Tool 输出
+
+`hooks deploy` 会自动把以下条目写入 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 配置和最近错误日志，方便排查接入问题。
 
@@ -297,14 +297,14 @@ npx ronds_ai@latest hooks deploy --scope user
 默认 scope 为 `project`（项目级部署），行为：
 
 - 写入或更新 `.cursor/hooks.json`
-- 写入或更新 `.claude/settings.json`
+- 写入或更新 `.claude/settings.json`（`PostToolUse` 的 `record claude` 采集 hook，以及 `Stop`、`SessionEnd` 的 `analyze claude` Langfuse 轨迹 hook；Node 低于 20 时跳过 analyze 并在输出 `analyze` 字段说明原因）
 - 清理项目内旧版 Cursor、Claude、Codex hook 脚本
 - 跳过 Codex 项目级配置部署，并在输出中说明原因
 
 `--scope user`（用户级部署），行为：
 
 - 写入或更新用户级 Cursor hook 配置
-- 写入或更新用户级 Claude hook 配置
+- 写入或更新用户级 Claude hook 配置（同上：`record claude` 采集 hook + `analyze 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 脚本文件
 
@@ -342,6 +342,7 @@ hooks_auto_accept: true
 - `updatedFiles`
 - `removedFiles`
 - `skipped`: 被跳过的工具及原因（仅在 project scope 下出现）
+- `analyze`: Claude Langfuse 轨迹 hook 的安装状态（`installed`、`events`、`command`；未安装时包含 `reason`）
 
 ### Hooks Auto Sync（自动后台同步）
 
@@ -364,6 +365,7 @@ RONDS_AI_DISABLE_HOOKS_AUTO_SYNC=1
 注意：
 
 - auto-sync 只维护**用户级** hooks，不影响项目级配置
+- auto-sync 会同步维护用户级 Claude 的 `analyze claude` Langfuse 轨迹 hook
 - 后台同步失败时，错误记录到 `~/.ronds_ai/hooks_auto_sync_error.log`，不污染当前命令输出
 - 首次安装 hooks 仍建议执行 `ronds_ai hooks deploy --scope user`
 

package/lib/analyze_claude.js

@@ -102,11 +102,20 @@ function extractHookContext(payload) {
     return null;
   }
   const hookEventName = payload.hook_event_name || payload.hookEventName || '';
-  return {
+  const context = {
     sessionId,
     transcriptPath: resolvedPath,
     flushDeferredAgentTurns: hookEventName === 'SessionEnd',
   };
+  const projectDir = [
+    payload.cwd,
+    payload.workspace && payload.workspace.current_dir,
+    payload.workspace && payload.workspace.project_dir,
+  ].find((value) => typeof value === 'string' && value.trim());
+  if (projectDir) {
+    context.projectDir = path.resolve(projectDir);
+  }
+  return context;
 }
 
 /**
@@ -426,10 +435,7 @@ async function processHookContext(context, config, sdkModules) {
 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;
   }
@@ -438,18 +444,23 @@ async function runClaudeAnalyze() {
   try {
     payload = JSON.parse(raw);
   } catch (error) {
+    const config = getAnalyzeConfig();
     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) {
+    const config = getAnalyzeConfig();
     writeAnalyzeLog('INFO', 'hook payload has no usable session or transcript', config);
     return;
   }
+  const config = getAnalyzeConfig(context.projectDir);
+  writeAnalyzeDebug('analyze hook started', config);
+  writeAnalyzeDebug(`stdin received ${raw.length} chars`, config);
+  writeAnalyzeDebug(
+    `payload top-level keys: ${Object.keys(payload).sort().join(', ')}`,
+    config,
+  );
 
   try {
     await processHookContext(context, config, sdkModules);

package/lib/analyze_config.js

@@ -1,4 +1,5 @@
 const os = require('os');
+const { runGit } = require('./git');
 
 // Langfuse 连接信息按产品要求从当前 Claude 配置写入源码。
 const LANGFUSE_PUBLIC_KEY = 'pk-lf-default-001';
@@ -46,15 +47,32 @@ function resolveSystemUsername() {
   return process.env.USERNAME || process.env.USER || 'unknown';
 }
 
+/**
+ * 读取当前项目的 Git 邮箱，与 record 上报的 git.user.email 保持一致。
+ */
+function resolveGitUserEmail(projectDir) {
+  const workingDirectory = typeof projectDir === 'string' && projectDir.trim()
+    ? projectDir.trim()
+    : process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  return runGit(workingDirectory, ['config', 'user.email'], false).toLowerCase();
+}
+
+/**
+ * 解析 Langfuse 用户标识，优先使用 Git 邮箱并保留系统用户名兜底。
+ */
+function resolveAnalyzeUserId(projectDir) {
+  return resolveGitUserEmail(projectDir) || resolveSystemUsername();
+}
+
 /**
  * 返回 analyze 命令使用的固定 Langfuse 配置。
  */
-function getAnalyzeConfig() {
+function getAnalyzeConfig(projectDir) {
   return {
     publicKey: LANGFUSE_PUBLIC_KEY,
     secretKey: LANGFUSE_SECRET_KEY,
     baseUrl: LANGFUSE_BASE_URL,
-    userId: resolveSystemUsername(),
+    userId: resolveAnalyzeUserId(projectDir),
     debug: readBooleanOption('CC_LANGFUSE_DEBUG', false),
     maxChars: readPositiveIntegerOption('CC_LANGFUSE_MAX_CHARS', 20000),
     skillTags: readBooleanOption('CC_LANGFUSE_SKILL_TAGS', true),
@@ -64,5 +82,7 @@ function getAnalyzeConfig() {
 
 module.exports = {
   getAnalyzeConfig,
+  resolveAnalyzeUserId,
+  resolveGitUserEmail,
   resolveSystemUsername,
 };

package/lib/hooks_auto_sync.js

@@ -19,7 +19,8 @@ const { spawn } = require('child_process');
 // ---------------------------------------------------------------------------
 
 /** 当前 hooks schema 版本。当用户级 hooks deploy 输出发生变化时 +1。 */
-const HOOKS_SCHEMA_VERSION = 1;
+// v2: 用户级 Claude settings 新增 Stop/SessionEnd analyze hook。
+const HOOKS_SCHEMA_VERSION = 2;
 
 /** sentinel 有效时长：24 小时 */
 const HOOKS_AUTO_SYNC_CHECK_TTL_MS = 24 * 60 * 60 * 1000;

package/lib/hooks_deploy.js

@@ -6,6 +6,8 @@ const yaml = require('js-yaml');
 
 const CURSOR_COMMAND = 'npx ronds_ai@latest record cursor';
 const CLAUDE_COMMAND = 'npx ronds_ai@latest record claude';
+const CLAUDE_ANALYZE_COMMAND = 'npx ronds_ai@latest analyze claude';
+const CLAUDE_ANALYZE_EVENTS = ['Stop', 'SessionEnd'];
 const CODEX_COMMAND = 'npx ronds_ai@latest record codex';
 const CURSOR_OLD_COMMAND = 'node .cursor/hooks/cursor_hook_request.cjs';
 const CURSOR_OLD_JS_COMMAND = 'node .cursor/hooks/cursor_hook_request.js';
@@ -216,6 +218,77 @@ function removeClaudeHookFromConfig(config) {
   return next;
 }
 
+/**
+ * 解析 Node.js 主版本号，解析失败返回 0。
+ * @param {string} version - Node.js 版本字符串
+ * @returns {number}
+ */
+function getNodeMajorVersion(version = process.versions.node) {
+  const major = Number(String(version || '').replace(/^v/i, '').split('.')[0]);
+  return Number.isInteger(major) ? major : 0;
+}
+
+/**
+ * 从单个 Claude hook 事件数组中抽离本工具管理的 analyze 命令。
+ * 保留用户在该事件下的其他 entry；analyze 所在 entry 的其余命令会合并到结果中。
+ *
+ * @param {Array} entries - hooks[event] 数组
+ * @returns {{ keepEntries: Array, desiredHooks: Array }}
+ */
+function splitClaudeAnalyzeEntries(entries) {
+  const keepEntries = [];
+  const desiredHooks = [];
+
+  for (const entry of entries) {
+    if (!isPlainObject(entry)) {
+      keepEntries.push(entry);
+      continue;
+    }
+
+    const existingHooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+    const containsAnalyze = existingHooks.some(
+      (hook) => isPlainObject(hook) && hook.type === 'command' && hook.command === CLAUDE_ANALYZE_COMMAND,
+    );
+
+    if (!containsAnalyze) {
+      keepEntries.push(entry);
+      continue;
+    }
+
+    for (const hook of existingHooks) {
+      if (!(isPlainObject(hook) && hook.type === 'command' && hook.command === CLAUDE_ANALYZE_COMMAND)) {
+        desiredHooks.push(hook);
+      }
+    }
+  }
+
+  return { keepEntries, desiredHooks };
+}
+
+/**
+ * 在 Claude settings 中确保 Stop/SessionEnd 的 analyze hook 条目。
+ * 只管理命令完全等于 CLAUDE_ANALYZE_COMMAND 的 hook，保留用户自定义条目。
+ */
+function ensureClaudeAnalyzeHooks(config) {
+  const next = isPlainObject(config) ? { ...config } : {};
+  const hooks = isPlainObject(next.hooks) ? { ...next.hooks } : {};
+
+  for (const eventName of CLAUDE_ANALYZE_EVENTS) {
+    const entries = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
+    const { keepEntries, desiredHooks } = splitClaudeAnalyzeEntries(entries);
+
+    desiredHooks.push({
+      type: 'command',
+      command: CLAUDE_ANALYZE_COMMAND,
+    });
+
+    hooks[eventName] = keepEntries.concat([{ hooks: desiredHooks }]);
+  }
+
+  next.hooks = hooks;
+  return next;
+}
+
 function ensureCodexHooksFeatureFlag(toml) {
   const newline = toml.includes('\r\n') ? '\r\n' : '\n';
   const desiredLine = `hooks = true${newline}`;
@@ -511,9 +584,28 @@ function deployCursorHook(cursorPath, result) {
   recordWriteResult(cursorPath, cursorResult.exists, changed, result);
 }
 
-function deployClaudeSettings(claudeSettingsPath, result) {
+/**
+ * 判断本次部署是否写入 Claude analyze hook。
+ * 不满足条件时把原因写入 result.analyze.reason 并返回 false。
+ */
+function shouldDeployClaudeAnalyze(result) {
+  const nodeMajor = getNodeMajorVersion();
+  if (nodeMajor < 20) {
+    result.analyze.reason = `analyze requires Node.js 20 or newer; current is ${process.versions.node || 'unknown'}`;
+    return false;
+  }
+
+  return true;
+}
+
+function deployClaudeSettings(claudeSettingsPath, result, analyzeDeployed) {
   const claudeSettingsResult = readJsonFile(claudeSettingsPath, {});
-  const nextClaudeSettings = ensureClaudeSettings(claudeSettingsResult.data);
+  let nextClaudeSettings = ensureClaudeSettings(claudeSettingsResult.data);
+
+  if (analyzeDeployed) {
+    nextClaudeSettings = ensureClaudeAnalyzeHooks(nextClaudeSettings);
+  }
+
   const changed = writeJsonFile(claudeSettingsPath, nextClaudeSettings);
   recordWriteResult(claudeSettingsPath, claudeSettingsResult.exists, changed, result);
 }
@@ -574,6 +666,12 @@ function deployHooks(targetDir = process.cwd(), options = {}) {
     updatedFiles: [],
     createdFiles: [],
     skipped: [],
+    analyze: {
+      tool: 'claude',
+      installed: false,
+      events: [],
+      command: CLAUDE_ANALYZE_COMMAND,
+    },
   };
 
   cleanupLegacyHookScripts(paths.configRoot, result, options.tool);
@@ -585,9 +683,15 @@ function deployHooks(targetDir = process.cwd(), options = {}) {
   }
 
   if (!options.tool || options.tool === 'claude') {
-    deployClaudeSettings(paths.claudeSettingsPath, result);
+    const analyzeDeployed = shouldDeployClaudeAnalyze(result);
+    deployClaudeSettings(paths.claudeSettingsPath, result, analyzeDeployed);
+    if (analyzeDeployed) {
+      result.analyze.installed = true;
+      result.analyze.events = [...CLAUDE_ANALYZE_EVENTS];
+    }
   } else {
     result.skipped.push({ tool: 'claude', reason: 'Skipped by --tool filter' });
+    result.analyze.reason = 'Skipped by --tool filter';
   }
 
   if (options.tool && options.tool !== 'codex') {
@@ -683,4 +787,6 @@ function deployHermesHook() {
 module.exports = {
   deployHooks,
   deployHermesHook,
+  ensureClaudeAnalyzeHooks,
+  getNodeMajorVersion,
 };

package/package.json

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