lumencode 1.2.0 → 1.3.1

package/README.md

@@ -11,7 +11,7 @@
 </p>
 
 <p align="center">
-  支持 <b>Claude Code · Codex · OpenCode</b> 三大 AI 编码工具 · 600+ 模型定价 · AI 贡献度归因 · 按项目独立汇报 · 自定义时间范围 · 一键飞书/钉钉周报
+  <b>AI 编码助手使用分析</b> —— 精确到每一行代码的 AI 归因 · 三工具统一 · 智能周报生成
 </p>
 
 <p align="center">
@@ -30,12 +30,12 @@
 
 | 场景 | 用 lumencode 解决 |
 |------|----------------------|
-| **写周报** | 选周报 → 点「工作汇报 → 复制」→ 粘贴飞书/钉钉。**3 秒搞定。** |
-| **证明 AI ROI** | 「67% 提交有 AI 参与，AI 辅助新增 4,200 行，费用 $12.5」**有数据，有底气。** |
-| **按项目汇报** | 配置多项目后，选择单个项目生成独立工作汇报，方便向不同项目负责人对齐 |
-| **对齐 Sprint 周期** | 除日/周/月外，支持自定义起止日期，不再被固定周期限制 |
-| **理解使用习惯** | 哪个项目用得最多？哪个模型最费 Token？什么时段是编码高峰？**一目了然。** |
-| **追踪 AI 成本** | 内置 **600+ 模型定价**（含 GLM、Kimi、Qwen、DeepSeek 等），自动算出等效 API 花销 |
+| **精确量化 AI 贡献** | 不是模糊的"大概写了不少"，而是精确到「4,200 行代码中 3,180 行由 AI 辅助完成」。**每一行都有数可查。** |
+| **证明 AI ROI** | 周报自动生成：「本周 AI 辅助 12 个提交，节省约 8 小时编码时间，Token 花费 $18.5」。**老板一看就懂。** |
+| **写周报/月报** | 选周期 → 点「工作汇报 → 复制」→ 粘贴飞书/钉钉。**3 秒搞定。** |
+| **按项目汇报** | 多项目并行时，选择单个项目生成独立汇报，方便向不同项目负责人对齐 |
+| **对齐 Sprint 周期** | 支持自定义起止日期，不再被日/周/月固定周期限制 |
+| **追踪 AI 成本** | 600+ 模型内置定价（含 GLM、Kimi、Qwen、DeepSeek），自动算出等效 API 花销 |
 
 ---
 
@@ -63,8 +63,8 @@ npx lumencode serve
 
 | 亮点 | 说明 |
 |------|------|
+| 🎯 **行级 AI 归因** | 通过 hook 步骤追踪，精确识别每一行代码的 AI 参与度。不是"这个提交 AI 帮忙了"，而是"这行代码是 AI 写的" |
 | 🌐 **三工具统一** | Claude Code / Codex / OpenCode 数据全自动汇总，左侧标签一键切换 |
-| 🤖 **AI 贡献度量化** | 识别 `Co-Authored-By: Claude` 等签名，多层归因引擎量化 AI 在你代码中的实际占比 |
 | 📝 **自然语言工作汇报** | 详报/简报一键生成，支持标准 Markdown / 飞书 / 钉钉三种格式，每个板块附诊断解读 |
 | 📂 **按项目独立汇报** | 右侧面板选择项目，生成该项目的独立工作汇报（commits + AI 交互量 + 热点文件） |
 | 📅 **自定义时间范围** | 除日/周/月外，支持选择任意起止日期，方便对齐 Sprint 周期 |
@@ -202,6 +202,24 @@ v0.4.0 起支持 Claude Code、Codex、OpenCode 三种工具，**首次运行自
 | 排除项目 | 不希望统计的项目名称 |
 | 场景关键词 | 工作类型分类关键词 JSON |
 
+### 行级 AI 归因（可选增强）
+
+行级归因通过 AI 编程工具 hook 记录文件编辑步骤，用于把 AI 贡献从提交级/文件级细化到行级。Claude Code 优先使用 `PostToolBatch`，Codex 使用 `PostToolUse`，OpenCode 使用项目级插件。该功能默认按需启用：没有初始化数据库时 hook 会静默跳过，不影响正常使用。
+
+```bash
+# 在需要统计的 Git 项目根目录执行
+node index.js hooks status
+node index.js hooks enable       # 交互式选择工具、初始化 steps 并自动备份配置
+```
+
+开启时只会修改当前项目的本地配置（`.claude/settings.local.json`、`.codex/config.toml`、`.opencode/plugins/lumencode-step-tracker.js`），不会修改全局配置或其它项目。关闭可执行：
+
+```bash
+node index.js hooks disable
+```
+
+数据写入当前项目的 `.ccusage/steps.db`。该数据库包含用于归因的文件快照，已在本项目 `.gitignore` 中默认忽略；如果在其它仓库启用，也建议忽略 `.ccusage/`。
+
 ### 模型定价数据
 
 - **本地表**：内置 590 个来自 [Portkey-AI/models](https://github.com/Portkey-AI/models) 的厂商原命名定价
@@ -232,6 +250,29 @@ v0.4.0 起支持 Claude Code、Codex、OpenCode 三种工具，**首次运行自
 
 ## 更新日志
 
+### v1.3.0 (2026-05-28) — 行级 AI 归因 & 交互式 Hooks 管理
+
+- **行级 AI 归因** — 通过 hook 步骤追踪系统，将归因粒度从提交级细化到行级，精确识别每一行代码的 AI 参与度
+- **交互式 hooks 管理** — Web UI 左下角新增 hooks 状态指示，支持一键开启/关闭，自动备份原始配置
+- **Codex 统一 hook 捕获** — 支持 Codex 的 `PostToolUse` 钩子，实时记录文件编辑步骤
+- **Claude batch hook 模式** — 支持 `PostToolBatch` 批处理钩子，减少性能开销
+- **OpenCode 插件支持** — 新增 OpenCode `lumenccode-step-tracker.js` 插件，覆盖三大工具
+- **报告诊断改进** — CLI 默认值优化，错误提示更友好
+- **解析器稳定性增强** — Git 指标解析、工具解析器、跨解析器项目过滤全面加固
+
+### v1.2.0 (2026-05-26) — AI 置信度精度全面改进
+
+- **基线校准** — 根据项目历史提交模式建立个人编码基线，区分「你的正常风格」与「AI 辅助风格」
+- **负信号检测** — 识别纯人工提交的反向指标（如周末提交、短编辑会话），降低误判率
+- **连续评分** — 从二元判断（是/否）升级为 0-100% 连续置信度，归因结果更细腻
+- **归因所有权改进** — 优化多人协作场景下的 AI 贡献归属逻辑
+
+### v1.1.0 (2026-05-25) — 并发管道 & 分层归因
+
+- **并发管道处理** — 数据解析与 Git 统计并行执行，大仓库分析速度显著提升
+- **消除冗余 Git 调用** — 缓存重复查询，降低 I/O 开销
+- **分层 AI 归因** — 显式签名 / Session 强关联 / 文件重叠三层置信度模型，归因更准确
+
 ### v1.0.0 (2026-05-24) — 项目级汇报 & 自定义时间
 
 - **按项目独立汇报** — 工作汇报右侧面板新增项目选择器，选定后自动筛选该项目数据，生成独立工作汇报（commits + AI 交互量 + 热点文件）

package/hooks/claude-post-tool-batch.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PostToolBatch hook for step tracking.
+ * Records one step per completed tool batch.
+ */
+import { ORIGINS, recordToolBatch } from '../lib/capture-recorder.js';
+
+async function readPayload() {
+  const chunks = [];
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  try {
+    return JSON.parse(chunks.join(''));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeToolCalls(payload) {
+  const rawCalls = payload.tool_calls || payload.toolCalls || payload.tools || [];
+  if (!Array.isArray(rawCalls)) return [];
+  return rawCalls.map(call => ({
+    toolUseId: call.tool_use_id || call.toolUseId || call.id,
+    toolName: call.tool_name || call.toolName || call.name,
+    toolInput: call.tool_input || call.toolInput || call.input || {},
+    toolResponse: call.tool_response || call.toolResponse || call.output,
+  }));
+}
+
+async function main() {
+  const payload = await readPayload();
+  if (!payload) process.exit(0);
+
+  const cwd = payload.cwd || payload.projectPath || process.cwd();
+  try {
+    await recordToolBatch({
+      origin: ORIGINS.CLAUDE_CODE,
+      sessionId: payload.session_id || payload.sessionId,
+      batchId: payload.batch_id || payload.batchId,
+      toolCalls: normalizeToolCalls(payload),
+      cwd,
+      timestamp: payload.timestamp || new Date().toISOString(),
+    });
+  } catch (e) {
+    if (process.env.DEBUG_STEP_TRACKER) console.error('[step-tracker]', e.message);
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/codex-hook.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * Codex PostToolUse hook adapter.
+ * Normalizes Codex hook payloads and records tool calls through capture-recorder.
+ */
+import { ORIGINS, recordToolUse } from '../lib/capture-recorder.js';
+
+function normalizeEventName(value) {
+  return String(value || '').replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+}
+
+async function readPayload() {
+  const chunks = [];
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+
+  try {
+    return JSON.parse(chunks.join(''));
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  const payload = await readPayload();
+  if (!payload) process.exit(0);
+
+  const eventName = normalizeEventName(
+    payload.hook_event_name || payload.hookEventName || payload.event
+  );
+  if (eventName !== 'posttooluse') process.exit(0);
+
+  const tool = payload.tool || {};
+  const cwd = payload.cwd || payload.projectPath || payload.workspace || process.cwd();
+
+  try {
+    await recordToolUse({
+      origin: ORIGINS.CODEX_CLI,
+      sessionId: payload.session_id || payload.sessionId,
+      toolUseId: payload.tool_use_id || payload.toolUseId || payload.call_id || payload.callId,
+      toolName: payload.tool_name || payload.toolName || tool.name,
+      toolInput: payload.tool_input || payload.toolInput || payload.input || tool.input,
+      toolResponse: payload.tool_response || payload.toolResponse || payload.output || tool.output,
+      cwd,
+      timestamp: payload.timestamp || new Date().toISOString(),
+    });
+  } catch (e) {
+    if (process.env.DEBUG_STEP_TRACKER) console.error('[step-tracker]', e.message);
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/init-steps.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Initialize step tracking database for the current project.
+ * Usage: node hooks/init-steps.js
+ */
+import { initStepTracking } from '../lib/hooks-manager.js';
+
+const stats = await initStepTracking(process.cwd());
+console.log(`Step tracking initialized at .ccusage/steps.db`);
+console.log(`  Steps: ${stats.stepCount}, Sessions: ${stats.sessionCount}`);

package/hooks/install-codex.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Install PostToolUse hook into Codex config.
+ * Usage: node hooks/install-codex.js
+ */
+import { enableCodexHooks } from '../lib/hooks-manager.js';
+
+const result = enableCodexHooks(process.cwd(), { backup: false });
+console.log(result.changed ? `Codex hook installed in ${result.configPath}` : 'Codex hook already installed.');

package/hooks/install.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Install PostToolUse hook into Claude Code settings.
+ * Usage: node hooks/install.js
+ */
+import { enableClaudeHooks } from '../lib/hooks-manager.js';
+
+const result = enableClaudeHooks(process.cwd(), { backup: false });
+
+if (result.changed) {
+  console.log(`Hook installed in ${result.configPath}`);
+} else {
+  console.log('Hook already installed.');
+}

package/hooks/opencode-hook.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * OpenCode tool.execute.after adapter for step tracking.
+ */
+import { ORIGINS, recordToolUse } from '../lib/capture-recorder.js';
+
+async function readPayload() {
+  const chunks = [];
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  try {
+    return JSON.parse(chunks.join(''));
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  const payload = await readPayload();
+  if (!payload) process.exit(0);
+
+  const input = payload.input || {};
+  const output = payload.output || {};
+  const tool = payload.tool || input.tool || {};
+  const cwd = payload.cwd || input.cwd || input.directory || payload.directory || process.cwd();
+
+  try {
+    await recordToolUse({
+      origin: ORIGINS.OPENCODE,
+      sessionId: payload.sessionId || payload.session_id || input.sessionID || input.sessionId || input.session_id || input.session?.id,
+      toolUseId: payload.toolUseId || payload.tool_use_id || input.toolCallID || input.toolUseId || input.id,
+      toolName: payload.toolName || payload.tool_name || input.toolName || input.tool || tool.name,
+      toolInput: payload.toolInput || payload.tool_input || output.args || input.args || input.toolInput || {},
+      toolResponse: payload.toolResponse || payload.tool_response || output.result || output,
+      cwd,
+      timestamp: payload.timestamp || new Date().toISOString(),
+    });
+  } catch (e) {
+    if (process.env.DEBUG_STEP_TRACKER) console.error('[step-tracker]', e.message);
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/hooks/post-tool-use.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PostToolUse hook for step tracking.
+ * Reads JSON payload from stdin, records the tool call as a step.
+ * Silently no-ops if .ccusage/steps.db doesn't exist.
+ */
+import { ORIGINS, recordToolUse } from '../lib/capture-recorder.js';
+
+async function main() {
+  const chunks = [];
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(chunks.join(''));
+  } catch { process.exit(0); }
+
+  const cwd = payload.cwd || payload.projectPath || process.cwd();
+
+  try {
+    await recordToolUse({
+      origin: ORIGINS.CLAUDE_CODE,
+      sessionId: payload.session_id || payload.sessionId,
+      toolUseId: payload.tool_use_id || payload.toolUseId,
+      toolName: payload.tool_name || payload.toolName,
+      toolInput: payload.tool_input || payload.toolInput,
+      toolResponse: payload.tool_response || payload.toolResponse,
+      cwd,
+      timestamp: payload.timestamp || new Date().toISOString(),
+    });
+  } catch (e) {
+    // Never fail the agent
+    if (process.env.DEBUG_STEP_TRACKER) console.error('[step-tracker]', e.message);
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/index.js

@@ -5,21 +5,185 @@ import { getGitStatsForMultipleReposAsync, invalidateGitCache, finalizeGitStats,
 import { invalidateFileCache } from './lib/cache.js';
 import { generateReport, generateWorkReport } from './lib/report.js';
 import { startServer } from './lib/server.js';
-import { detectClaudeDir, deriveProjectPaths } from './lib/parser.js';
-import { identifyBillingBlocks } from './lib/blocks.js';
-import { registerParser, parseAllEnabledTools } from './lib/parsers/index.js';
-import { ClaudeParser } from './lib/parsers/claude.js';
-import { CodexParser } from './lib/parsers/codex.js';
-import { OpencodeParser } from './lib/parsers/opencode.js';
-import { initPricing, preloadUnknownPricing } from './lib/pricing-loader.js';
+import { detectClaudeDir, deriveProjectPaths } from './lib/parser.js';
+import { identifyBillingBlocks } from './lib/blocks.js';
+import { registerParser, parseAllEnabledTools, detectAvailableTools } from './lib/parsers/index.js';
+import { ClaudeParser } from './lib/parsers/claude.js';
+import { CodexParser } from './lib/parsers/codex.js';
+import { OpencodeParser } from './lib/parsers/opencode.js';
+import { initPricing, preloadUnknownPricing } from './lib/pricing-loader.js';
+import { createInterface } from 'readline';
+import { stdin as input, stdout as output } from 'process';
+import { enableHooks, disableHooks, getHooksStatus, HOOK_TOOLS, initStepTracking } from './lib/hooks-manager.js';
 
 // 注册所有解析器
 registerParser(ClaudeParser);
 registerParser(CodexParser);
 registerParser(OpencodeParser);
 
-const args = process.argv.slice(2);
-const command = args[0];
+const args = process.argv.slice(2);
+const command = args[0];
+
+function parseHookTools(values) {
+  const raw = values.length > 0 ? values : ['claude', 'codex', 'opencode'];
+  const tools = new Set();
+  for (const value of raw) {
+    for (const part of value.split(',')) {
+      const tool = part.trim().toLowerCase();
+      if (!tool) continue;
+      if (tool === 'claude' || tool === 'claude-code') tools.add(HOOK_TOOLS.CLAUDE);
+      else if (tool === 'codex') tools.add(HOOK_TOOLS.CODEX);
+      else if (tool === 'opencode' || tool === 'open-code') tools.add(HOOK_TOOLS.OPENCODE);
+      else throw new Error(`不支持的 hooks 工具: ${part}`);
+    }
+  }
+  return [...tools];
+}
+
+function detectedHookTools(status = getHooksStatus(process.cwd())) {
+  const tools = [];
+  if (status.claude.configExists || status.claude.enabled) tools.push(HOOK_TOOLS.CLAUDE);
+  if (status.codex.configExists || status.codex.enabled) tools.push(HOOK_TOOLS.CODEX);
+  if (status.opencode.configExists || status.opencode.enabled) tools.push(HOOK_TOOLS.OPENCODE);
+  return tools.length > 0 ? tools : [HOOK_TOOLS.CLAUDE, HOOK_TOOLS.CODEX, HOOK_TOOLS.OPENCODE];
+}
+
+function formatEnabled(value) {
+  return value ? '已开启' : '未开启';
+}
+
+function printHooksStatus(status) {
+  console.log('Hooks 状态:');
+  const claudeMode = status.claude.batchEnabled ? 'batch' : status.claude.legacyEnabled ? 'legacy' : '';
+  console.log(`- Claude Code: ${status.claude.invalid ? '配置文件 JSON 无效' : formatEnabled(status.claude.enabled)}${claudeMode ? ` (${claudeMode})` : ''}`);
+  console.log(`- Codex: ${formatEnabled(status.codex.enabled)}`);
+  console.log(`- OpenCode: ${formatEnabled(status.opencode.enabled)}`);
+  console.log(`- steps 数据库: ${status.stepsInitialized ? '已初始化' : '未初始化'}`);
+  console.log(`- 项目: ${status.projectRoot}`);
+}
+
+function printHookResults(results, action) {
+  for (const result of results) {
+    const name = hookToolName(result.tool);
+    console.log(`- ${name}: ${result.changed ? action : '无需变更'} (${result.configPath})`);
+    if (result.backupPath) console.log(`  备份: ${result.backupPath}`);
+  }
+}
+
+function hookToolName(tool) {
+  if (tool === HOOK_TOOLS.CLAUDE) return 'Claude Code';
+  if (tool === HOOK_TOOLS.CODEX) return 'Codex';
+  return 'OpenCode';
+}
+
+function createPromptSession() {
+  const rl = createInterface({ input, output });
+  const lines = [];
+  const waiters = [];
+  let closed = false;
+
+  rl.on('line', line => {
+    const waiter = waiters.shift();
+    if (waiter) waiter(line);
+    else lines.push(line);
+  });
+  rl.on('close', () => {
+    closed = true;
+    while (waiters.length > 0) waiters.shift()('');
+  });
+
+  return {
+    async ask(prompt) {
+      output.write(prompt);
+      if (lines.length > 0) return lines.shift();
+      if (closed) return '';
+      return new Promise(resolve => waiters.push(resolve));
+    },
+    close() {
+      rl.close();
+    },
+  };
+}
+
+async function promptHookTools(defaultTools, rl) {
+  console.log('检测到:');
+  defaultTools.forEach((tool, index) => {
+    console.log(`[${index + 1}] ${hookToolName(tool)}`);
+  });
+
+  const answer = await rl.ask('请选择要开启 hooks 的工具（例如 1,2，直接回车选择全部）: ');
+  const raw = answer.trim();
+  if (!raw) return defaultTools;
+  const selected = [];
+  for (const part of raw.split(',')) {
+    const idx = Number(part.trim());
+    if (!Number.isInteger(idx) || idx < 1 || idx > defaultTools.length) {
+      throw new Error(`无效选择: ${part}`);
+    }
+    selected.push(defaultTools[idx - 1]);
+  }
+  return [...new Set(selected)];
+}
+
+async function confirmHooksEnable(tools, status, rl) {
+  console.log('即将开启 AI 工具 hooks。');
+  console.log('操作类型: 修改当前项目的本地 AI 工具配置文件。');
+  console.log(`影响范围: ${tools.includes(HOOK_TOOLS.CLAUDE) ? '.claude/settings.local.json ' : ''}${tools.includes(HOOK_TOOLS.CODEX) ? '.codex/config.toml' : ''}`);
+  console.log('用途: 记录 PostToolUse 事件，用于行级 AI 归因。');
+  console.log(`steps 数据库: ${status.stepsInitialized ? '已初始化' : '将初始化 .ccusage/steps.db'}`);
+  console.log('风险: 只启用当前项目 hooks，不修改全局配置或其它项目。');
+
+  const answer = await rl.ask('请输入“确认”继续: ');
+  return answer.trim() === '确认' || answer.trim().toLowerCase() === 'yes' || answer.trim().toLowerCase() === 'y';
+}
+
+async function handleHooksCommand() {
+  const subcommand = args[1] || 'status';
+  if (subcommand === 'init') {
+    const stats = await initStepTracking(process.cwd());
+    console.log(`Step tracking initialized at .ccusage/steps.db`);
+    console.log(`  Steps: ${stats.stepCount}, Sessions: ${stats.sessionCount}`);
+    return;
+  }
+  if (subcommand === 'status') {
+    printHooksStatus(getHooksStatus(process.cwd()));
+    return;
+  }
+
+  const yes = args.includes('--yes') || args.includes('-y');
+  const toolArgs = args.slice(2).filter(arg => arg !== '--yes' && arg !== '-y');
+  const status = getHooksStatus(process.cwd());
+  const rl = createPromptSession();
+  let tools;
+  try {
+    tools = toolArgs.length > 0
+      ? parseHookTools(toolArgs)
+      : await promptHookTools(detectedHookTools(status), rl);
+
+    if (subcommand === 'enable') {
+      if (!yes && !(await confirmHooksEnable(tools, status, rl))) {
+        console.log('已取消，未修改配置。');
+        return;
+      }
+      const stats = await initStepTracking(process.cwd());
+      console.log(`Step tracking initialized at .ccusage/steps.db`);
+      console.log(`  Steps: ${stats.stepCount}, Sessions: ${stats.sessionCount}`);
+      const results = enableHooks(process.cwd(), tools, { backup: true });
+      printHookResults(results, '已开启');
+      return;
+    }
+
+    if (subcommand === 'disable') {
+      const results = disableHooks(process.cwd(), tools, { backup: true });
+      printHookResults(results, '已关闭');
+      return;
+    }
+  } finally {
+    rl.close();
+  }
+
+  console.log('未知 hooks 命令。用法: node index.js hooks status|enable|disable|init [claude,codex] [--yes]');
+}
 
 function loadCliConfig() {
   let config = loadConfig();
@@ -40,8 +204,16 @@ function loadCliConfig() {
   }
 
   // 日期参数
-  let dateArg = new Date().toISOString().slice(0, 10);
+  let dateArg = (() => { const n = new Date(); return `${n.getFullYear()}-${String(n.getMonth()+1).padStart(2,'0')}-${String(n.getDate()).padStart(2,'0')}`; })();
+  const skipArgs = new Set();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--projects' || args[i] === '--start' || args[i] === '--end') {
+      skipArgs.add(i);
+      skipArgs.add(i + 1);
+    }
+  }
   for (let i = 2; i < args.length; i++) {
+    if (skipArgs.has(i)) continue;
     if (!args[i].startsWith('--')) {
       dateArg = args[i];
       break;
@@ -121,7 +293,10 @@ async function buildReportData(period, dateArg, config, effectiveIncludeProjects
     extendedEnd.setDate(extendedEnd.getDate() + 2);
     const extendedEndStr = extendedEnd.toISOString().slice(0, 10) + 'T23:59:59';
     let gs = await getGitStatsForMultipleReposAsync(toolRepos, start, extendedEndStr);
-    gs = finalizeGitStats(gs, sessions);
+    gs = await finalizeGitStats(gs, sessions, {
+      attribution: config.aiAttribution,
+      stepTracking: config.stepTracking,
+    });
     if (gs.commitList) {
       const windowStart = start;
       const windowEnd = end + 'T23:59:59';
@@ -232,7 +407,16 @@ async function buildReportData(period, dateArg, config, effectiveIncludeProjects
     }
   }
 
-  return { usageStats, gitStats, reposConfigured, sessions: slimSessions, start, end, trendData, prevStats, billingBlocks, toolBreakdown: mergedBreakdown, projectDetails };
+  // 工具检测诊断：记录每个工具的检测状态和数据目录
+  const diagnostics = {};
+  try {
+    const availableTools = await detectAvailableTools(config);
+    for (const t of availableTools) {
+      diagnostics[t.name] = { detected: t.detected, dataDir: t.dataDir || null };
+    }
+  } catch {}
+
+  return { usageStats, gitStats, reposConfigured, sessions: slimSessions, start, end, trendData, prevStats, billingBlocks, toolBreakdown: mergedBreakdown, projectDetails, _diagnostics: diagnostics };
 }
 
 if (!command || command === 'help' || command === '--help') {
@@ -263,9 +447,16 @@ if (!command || command === 'help' || command === '--help') {
   lumencode report daily --projects D://fzwork
   lumencode report weekly 2026-05-15 --projects D://fzwork,E://play/idea
   lumencode report daily --work
-  lumencode report daily --work --brief
-  lumencode serve
-  lumencode init
+  lumencode report daily --work --brief
+  node index.js serve
+  node index.js init
+  node index.js hooks status
+  node index.js hooks enable
+  node index.js hooks disable
+  node index.js hooks:init
+  node index.js hooks:install
+  node index.js hooks:install-claude
+  node index.js hooks:install-codex
 
 零配置:
   首次运行自动检测 Claude 日志目录和项目路径，无需手动配置。
@@ -274,12 +465,32 @@ if (!command || command === 'help' || command === '--help') {
   process.exit(0);
 }
 
-if (command === 'init') {
-  initConfig(args[1]);
-  process.exit(0);
-}
-
-if (command === 'serve') {
+if (command === 'init') {
+  initConfig(args[1]);
+  process.exit(0);
+}
+
+if (command === 'hooks') {
+  await handleHooksCommand();
+  process.exit(0);
+}
+
+if (command === 'hooks:init') {
+  await import('./hooks/init-steps.js');
+  process.exit(0);
+}
+
+if (command === 'hooks:install' || command === 'hooks:install-claude') {
+  await import('./hooks/install.js');
+  process.exit(0);
+}
+
+if (command === 'hooks:install-codex') {
+  await import('./hooks/install-codex.js');
+  process.exit(0);
+}
+
+if (command === 'serve') {
   const { config, effectiveIncludeProjects, configPath } = loadCliConfig();
   startServer(config, effectiveIncludeProjects, buildReportData, configPath);
 } else {
@@ -321,7 +532,10 @@ if (command === 'serve') {
     console.log('正在统计 Git 指标...');
     const sessions = groupBySessions(filtered);
     gitStats = await getGitStatsForMultipleReposAsync(config.repos, start, end + 'T23:59:59');
-    gitStats = finalizeGitStats(gitStats, sessions);
+    gitStats = await finalizeGitStats(gitStats, sessions, {
+      attribution: config.aiAttribution,
+      stepTracking: config.stepTracking,
+    });
   }
 
   // 上一周期数据（用于工作汇报环比）