1. 项目概述：你的本地AI编程效率分析专家

如果你和我一样，每天都在和Claude Code、Codex这类AI编程助手打交道，那你肯定也遇到过这样的困惑：今天到底用AI写了多少代码？哪些会话是高效的，哪些是在原地打转？明天开站会时，我该怎么清晰地汇报进度？过去一周的AI编程时间都花在了哪里？这些问题，以前只能靠模糊的感觉和零散的记忆来回答，直到我遇到了 vibe-log-cli 。

简单来说，vibe-log-cli 是一个开源的命令行工具，它就像一个专为开发者打造的“AI编程行为分析仪”。它能深度分析你在Claude Code和Codex中的所有会话记录，然后生成一份详尽的效率报告，或者给你一个即时的“今日站会”摘要。最核心的亮点是，这一切分析过程都可以 100%在你的本地机器上完成 ，通过你本地的AI编程工具（ACP）进行，你的代码和对话数据无需离开你的电脑。它还有一个非常酷的“状态栏教练”功能，能在你写提示词时实时给出策略性建议，帮你写出更好的提示，从而获得更高质量的代码。

我最初是被它的“本地分析”特性吸引的。作为开发者，我们对代码和项目细节的隐私性有天然的敏感度。vibe-log-cli 承诺所有分析都在本地运行，这彻底打消了我的数据安全顾虑。使用一段时间后，我发现它不仅仅是“安全”，更是“实用”。它把我散落在各处的AI编程会话变成了可量化、可复盘的结构化数据，让我能真正看清自己的AI协作模式，并持续优化。接下来，我将从设计思路、核心功能、实操配置到深度使用技巧，为你完整拆解这个提升AI编程生产力的利器。

2. 核心功能深度解析与设计哲学

vibe-log-cli 的设计哲学非常明确： 赋能开发者，而非监控开发者 。它不追求大而全的数据面板，而是聚焦于几个能直接提升日常开发效率的痛点场景。它的三大核心功能构成了一个从即时反馈到深度复盘的工作流闭环。

2.1 今日站会：两分钟搞定每日进度同步

这是v0.7.x版本引入的杀手级功能，也是我目前使用频率最高的。想象一下，每天站会前，你不再需要手忙脚乱地回忆昨天做了什么，只需在终端里输入一条命令，就能获得一份清晰的摘要。

它是如何工作的？ 工具会扫描你指定时间段内（默认是过去24小时）在Claude Code和Codex中的所有会话。它并非简单罗列对话记录，而是通过本地AI模型（调用你的Claude Code）对这些会话进行智能分析，提取出关键信息，并组织成标准的站会汇报格式：

• 已完成的工作 ：总结你通过AI助手完成的主要任务或模块。
• 关键进展/成果 ：突出显示重要的功能实现、问题解决或决策点。
• 接下来的计划 ：基于最近的对话上下文，推测或总结你下一步可能要做的事情。

实操心得 ：这个功能的准确性高度依赖于你与AI对话的“质量”。如果你在会话中清晰地描述了任务背景、目标和当前进度，那么生成的站会摘要就会非常精准。我习惯在开始一个复杂任务前，先用一两句话向AI说明“我们接下来要做什么，为什么做，以及当前的上下文”，这不仅能帮助AI，也无形中为vibe-log的分析提供了优质素材。

2.2 本地生产力报告生成：你的私人AI编程复盘工具

如果说“今日站会”是速效药，那么“本地报告”就是你的长期健康档案。这个功能允许你选择任意时间范围（如过去一周、一个月）和特定项目，生成一份完整的HTML格式生产力报告。

报告里有什么？ 根据官方示例，报告内容极其丰富，远不止时间统计。它会分析你的会话模式，例如：

• 会话时长与分布 ：你在不同项目、不同时间段投入的AI编程时间。
• 提示词质量趋势 ：你的提问方式是否在改进？是否越来越能引导AI给出精准答案？
• 任务切换频率 ：你是否在多个任务间频繁跳转，这可能意味着注意力分散。
• 代码生成与重构模式 ：AI是更多地用于生成新代码，还是协助重构和调试？

本地化的意义 ： 所有上述分析，都是通过你本地的Claude Code SDK完成的。这意味着，分析模型的能力上限就是你本地AI助手的能力上限，同时也保证了最敏感的项目代码、内部API地址、业务逻辑等绝不会被上传到任何第三方服务器。报告生成后，就是一个静态HTML文件，你可以用浏览器打开，随时查看，也方便存档。

2.3 Claude Code 状态栏教练：实时提示词优化顾问

这是最具互动性的功能。安装后，它会在你的Claude Code状态栏中嵌入一个“教练”。每当你提交一个提示词（Prompt）时，这个教练会在后台瞬间进行本地分析，并给出评分和具体的改进建议。

教练的三种人格 ：

1. Gordon（戈登） ：风格犀利、直接，专注于商业目标和交付压力。他会说类似“周五前不交付你就被炒了！”这样的话来制造紧迫感，适合需要外部驱动力的人。
2. Vibe-Log ：支持性但同样具有推动力的高级开发伙伴。他会帮你检查MVP清单，比如“认证功能工作正常 ✓ | 可以发布了！”，更侧重于协作和鼓励。
3. Custom（自定义） ：你可以定义自己的教练风格和关注点。

为什么这个功能有价值？ 我们常常陷入与AI的低效对话循环：问题描述模糊 -> AI回答笼统 -> 继续追问 -> 依然跑偏。状态栏教练在你按下回车键的瞬间，就从“任务清晰度”、“上下文完整性”、“可操作性”等维度评估你的提示词，并给出像“添加更多背景信息，大厨！”或“这个需求不够具体，请拆分成更小的步骤”这样的即时反馈。长期使用，能显著提升你与AI沟通的“提示词工程”能力。

3. 从零开始：完整安装与配置指南

理论说得再多，不如动手一试。vibe-log-cli的安装和初始配置非常顺畅，以下是基于我多次实践总结的详细步骤和注意事项。

3.1 环境准备与基础安装

首先，确保你的系统满足基本要求：

• Node.js ：版本需在16以上。建议使用LTS版本以获得最佳稳定性。可以通过 node -v 命令检查。
• Claude Code 或 Codex ：你至少需要安装并正常使用其中一款AI编程工具。这是vibe-log分析的数据源。
• 网络连接 ：首次安装和后续的可选云同步功能需要网络。

安装过程简单到只需一行命令：

npx vibe-log-cli@latest

运行这条命令后，工具会自动开始安装流程。 npx 会下载并执行最新版本的vibe-log-cli，你无需在本地进行全局安装（ npm install -g ）。

注意事项 ：如果你在公司的网络环境下，且存在严格的防火墙或代理设置，可能会遇到 npx 下载包失败的情况。此时可以尝试配置npm的代理，或者直接克隆GitHub仓库到本地进行构建和运行（后文贡献部分会提到）。

3.2 首次运行与交互式配置

第一次运行上述命令后，你会进入一个交互式的终端用户界面。这里会引导你完成核心配置：

1. 选择主要功能 ：界面会列出“生成报告”、“配置状态栏教练”、“设置云同步”等选项。对于新手，我建议按以下顺序操作：

   • 先选择 “配置状态栏教练” ，体验最直接的交互功能。
   • 然后尝试 “生成今日站会摘要” ，快速获得价值反馈。
   • 最后再考虑是否配置云同步。

2. 配置状态栏教练 ：

   • 选择此选项后，CLI会首先 自动备份你现有的Claude Code状态栏配置 。这是一个非常贴心的设计，意味着零风险，卸载即可恢复原状。
   • 接着，选择你喜欢的教练人格（Gordon, Vibe-Log, 或自定义）。
   • 工具会自动完成Claude Code的钩子（hook）注入。完成后，重启你的Claude Code，你就会在状态栏看到教练的反馈了。

3. （可选）配置云同步 ：

   • 如果你希望获得跨时间维度的趋势分析和更漂亮的在线仪表盘，可以选择配置云同步。
   • 流程：选择云同步 -> 通过GitHub账号授权 -> 选择自动同步的钩子（如SessionStart, PreCompact）。
   • 关键隐私说明 ：即使在云同步模式下，vibe-log也会在上传前执行严格的“上下文保留脱敏”处理。所有代码块会被替换为 [CODE_BLOCK_1: javascript] 这样的标记，API密钥、文件路径、URL、邮箱等敏感信息都会被移除或替换为占位符。上传的只是对话的模式、结构和你的提问方式，用于分析你的“提示词习惯”而非“代码内容”。

3.3 验证安装与初步测试

配置完成后，可以通过几个简单步骤验证是否一切正常：

1. 测试状态栏教练 ：打开Claude Code，在输入框里随便写一个提示词，比如“帮我写一个Python函数”。提交后，留意状态栏（通常在窗口底部）是否在几秒内出现了评分和简短建议（例如 “🟢 78/100”）。
2. 测试本地报告 ：在终端中，再次运行 npx vibe-log-cli@latest ，选择生成报告，时间范围选“今天”或“昨天”，项目可以全选。观察终端是否启动本地分析进程，并最终在当前目录生成一个 vibe-log-report-*.html 文件。用浏览器打开它，检查内容。
3. 检查数据源 ：如果工具提示“未找到会话”，请确认你指定的AI编程工具（Claude Code/Codex）确实在默认路径安装，并且近期有过使用记录，产生了会话日志。

4. 核心工作流程与高级使用技巧

掌握了基础安装，我们来深入看看vibe-log-cli在日常开发中是如何无缝融入的，以及一些能让你用得更顺手的高级技巧。

4.1 无缝集成的工作流

一个理想的使用vibe-log-cli的工作流是这样的：

早晨，开始工作前 ：

1. 打开终端，运行 npx vibe-log-cli@latest 。
2. 选择“生成今日站会”，快速回顾昨天下午到今天早晨的AI编程进展，理清思路。
3. 报告生成后，花一分钟浏览，明确今天要延续或开启的重点任务。

编码过程中 ：

1. 在Claude Code中正常与AI协作。
2. 每次提交提示词后，瞥一眼状态栏的教练反馈。如果分数偏低，仔细读一下建议，思考如何在下一次交互中改进提问方式。例如，教练提示“缺少上下文”，你下次就可以先简要说明这个函数属于哪个模块，要解决什么问题。

下午或下班前 ：

1. 可能再次生成一次站会报告，梳理下午的成果，为第二天做准备。
2. 或者，针对某个刚完成的复杂功能（涉及多次AI会话），单独为这个项目生成一份详细报告，复盘整个思考和解法过程。

周五下午 ：

1. 运行vibe-log-cli，选择生成“本周”的完整生产力报告。
2. 花15分钟阅读HTML报告，回顾一周的AI协作效率：哪个项目耗时最多？提示词质量是否有提升？有没有陷入某个问题的死循环？这为下一周的工作计划和技能提升提供了数据支撑。

4.2 高级技巧与个性化配置

1. 精准控制报告范围 ：

   • 默认情况下，报告会涵盖所有检测到的会话。但你可以在生成报告时，通过交互式菜单选择特定的“项目”或“文件夹”。vibe-log-cli 通常会根据会话发生的目录路径来识别项目。确保你的工作是在清晰的项目目录内进行，这样报告才能正确归类。
   • 对于超长会话（超过1万条消息），vibe-log-cli v0.7.x 引入了智能截断机制以保证性能，同时保留时间数据。但为了分析质量，建议在开发中适时使用Claude Code的“压缩上下文”功能，这也会触发 PreCompact 钩子，将完整会话同步给vibe-log。

2. 自定义你的教练 ：

   • 如果你不满足于Gordon或Vibe-Log的人格，可以选择“自定义”教练。这通常需要你提供一个描述教练性格和目标的提示词模板。例如，你可以创建一个专注于“代码简洁性和性能”的教练，或者一个“特别关注测试覆盖率”的教练。
   • 自定义教练的配置可能涉及编辑配置文件（通常位于 ~/.vibe-log/config.json ）。高级用户可以在这里微调分析提示词，让教练更贴合你的个人编码哲学。

3. 利用云同步进行长期追踪 ：

   • 如果你启用了云同步并选择了自动同步钩子（如 SessionStart 和 PreCompact ），那么你的脱敏会话数据会在后台静默同步到vibe-log云端。
   • 登录 vibe-log.dev 仪表板，你可以看到跨周、跨月的趋势图。比如，你可以发现自己在周三上午的提示词效率最高，或者看到随着时间推移，你的“会话平均解决效率”在稳步提升。这些宏观洞察是本地报告难以提供的。

4. 调试与排查 ：

   • 如果遇到任何异常，比如状态栏不更新、报告生成失败，可以启用调试模式：

     VIBELOG_DEBUG=1 npx vibe-log-cli [command]
     

   • 这会在终端输出详细的日志，帮助你定位问题是出在会话数据读取、本地AI分析调用，还是网络同步环节。

5. 隐私、安全与架构可信度剖析

对于一个需要接触开发会话数据的工具，安全与隐私是绝对不能妥协的底线。vibe-log-cli 在这方面做得相当透明和扎实，这也是我决定深度使用并推荐它的重要原因。

5.1 本地优先架构

这是其安全模型的基石。核心分析功能（站会生成、报告生成、状态栏教练分析）完全在本地运行，依赖的是你本机已安装的Claude Code SDK。这意味着：

• 数据不出境 ：你的原始对话记录、生成的代码、引用的内部文件路径，从未离开你的计算机内存和磁盘。
• 分析能力内化 ：分析质量取决于你本地AI模型的能力，不依赖可能不稳定或受限制的云端分析API。
• 离线可用 ：在没有网络的环境下，你依然可以使用所有核心功能。

5.2 透明的云同步脱敏策略

对于选择云同步的用户，vibe-log采用了业界称为“上下文保留脱敏”的技术。这不是简单的关键字过滤，而是一个更智能的过程：

1. 结构化解析 ：工具会解析每条消息，识别出其中的不同元素（文本、代码块、路径、URL等）。
2. 模式替换 ：
   • 将整个代码块替换为 [CODE_BLOCK_N: language] 的标签，只保留编程语言类型。
   • 使用正则表达式和模式匹配，将疑似API密钥、令牌、数据库连接字符串、电子邮件、服务器IP/域名等替换为 [CREDENTIAL_N] 、 [DATABASE_URL] 、 [EMAIL_N] 等通用占位符。
   • 将具体的文件路径替换为 [PATH_N] 。
3. 保留逻辑 ：对话的脉络、你提出的问题、AI给出的解释性文字、任务描述的框架都被完整保留。

这样处理后上传的数据，足以分析“开发者如何提问”、“会话的流程结构”、“时间花费模式”，但 完全无法还原任何一行具体的业务代码或敏感配置 。你甚至可以在CLI中预览脱敏后的数据再决定是否同步。

5.3 开源与构建透明性

项目在GitHub上完全开源，采用MIT许可证。这允许任何人审查其源代码，尤其是核心的 message-sanitizer-v2.ts （消息脱敏器）和所有数据流逻辑。此外，其发布流程也极具可信度：

• 自动化构建 ：通过GitHub Actions工作流发布，无人为干预环节。
• NPM来源证明 ：发布的包附带了npm的来源证明，可以验证该包确实是由该项目的GitHub仓库构建而来，而非来自第三方。
• 源码映射 ：发布的包中包含Source Map文件，意味着即使代码经过编译，你也可以映射回原始TypeScript源码进行调试或审查。
• 完整性校验 ：提供SHA256校验和，供下载者验证文件完整性。

你可以按照项目README中的“验证我们的包”部分的步骤，亲自完成上述验证，这种程度的透明度在开源工具中并不多见。

6. 常见问题排查与实战经验分享

即使设计得再完善，在实际部署和使用中总会遇到一些环境或配置上的“坑”。下面是我和社区中遇到的一些典型问题及其解决方案。

6.1 会话查找失败问题

问题现象 ：运行CLI后，提示“未找到会话”或列表为空。

• 检查数据源 ：首先确认你选择的分析对象（Claude Code 或 Codex）已正确安装且是你日常使用的工具。vibe-log-cli 通过读取这些工具的默认日志或数据目录来获取会话。
• 确认使用记录 ：工具只分析已产生的会话。确保你近期确实使用过目标AI编程助手进行过对话。
• 手动指定路径（高级） ：在某些自定义安装或非标准配置下，可能需要通过环境变量或配置文件手动指定会话数据的存储路径。这需要查阅对应AI编程工具的文档，了解其数据存放位置。

6.2 状态栏教练不显示或无反应

问题现象 ：Claude Code状态栏没有出现vibe-log的评分和反馈。

• 重启Claude Code ：安装或更新状态栏钩子后，必须完全关闭并重新启动Claude Code，新的钩子才能生效。
• 检查安装日志 ：回顾运行配置命令时的终端输出，确认钩子安装是否报告成功，以及备份文件（如 claude-code-statusline-backup.json ）是否已创建。
• 验证钩子文件 ：前往Claude Code的配置目录（通常在 ~/.config/ClaudeCode/ 或类似位置），检查 hooks.json 或相关配置文件，看其中是否包含了vibe-log-cli的钩子命令。
• 权限问题 ：确保运行CLI的用户有权限向Claude Code的配置目录写入文件。

6.3 本地分析过程缓慢或卡住

问题现象 ：生成报告时，进度条长时间不动，或终端似乎卡在“正在通过本地AI分析...”阶段。

• 会话量过大 ：如果你选择分析一个非常长的时间范围（如整个月），且会话数量极多，本地AI模型处理可能需要较长时间。可以尝试先分析较短的时间范围（如一天）进行测试。
• 本地AI资源占用 ：Claude Code本地模型推理会消耗CPU/GPU和内存。确保你的电脑有足够的资源，并关闭其他占用大量资源的程序。
• 检查网络（仅限首次/模型加载） ：虽然分析在本地，但Claude Code SDK首次加载或更新模型时可能需要网络。确保网络通畅。
• 启用调试模式 ：使用 VIBELOG_DEBUG=1 前缀运行命令，查看日志卡在哪一步，是数据读取、预处理还是模型调用环节。

6.4 云同步认证失败

问题现象 ：在CLI中选择云同步功能时，GitHub OAuth认证失败或无法完成。

• 浏览器拦截 ：认证流程会打开默认浏览器。检查浏览器是否拦截了弹出窗口，或者是否有插件阻止了OAuth跳转。
• 网络代理 ：如果你身处需要代理的网络环境，请确保你的系统代理设置正确，并且命令行工具（如终端）能继承这些代理设置。有时需要单独为npm或Node.js配置代理。
• 清除本地认证缓存 ：按照Troubleshooting指南，尝试在CLI中退出登录，并清除相关的本地cookie或token文件（通常位于 ~/.vibe-log/ 目录下），然后重新认证。

6.5 报告内容感觉不够准确或泛泛而谈

问题现象 ：生成的站会摘要或报告内容比较空洞，没有切中要害。

• 提升对话质量 ：这是根本原因。vibe-log的分析基于你的会话文本。尝试在与AI协作时，使用更结构化、目标更明确的对话：
  • 提供上下文 ：开始新任务时，先简要说明项目背景、当前文件、想要实现的功能。
  • 分解任务 ：将大问题拆解成一系列小步骤，逐步与AI确认。
  • 明确指令 ：使用“请用Python编写一个函数，输入X，输出Y，需要处理Z异常”而不是“帮我写个处理X的函数”。
• 检查数据脱敏影响 ：如果你使用了云同步，并怀疑脱敏过程过度影响了分析，可以在本地生成报告进行对比。本地报告使用的是原始数据（不脱敏），理论上分析会更精准。对比两者差异，可以帮助你理解脱敏的边界。

7. 进阶玩法：从使用者到贡献者

vibe-log-cli 是一个活跃的开源项目，这意味着你不仅可以用它，还可以参与改进它。这对于希望深入理解其工作原理或需要特定定制的开发者来说，是一个很好的机会。

7.1 本地开发与构建

如果你想修复某个bug或尝试添加新功能，可以轻松搭建本地开发环境：

# 1. 克隆仓库
git clone https://github.com/vibe-log/vibe-log-cli.git
cd vibe-log-cli

# 2. 安装依赖
npm install

# 3. 运行测试（确保你的改动没有破坏现有功能）
npm test

# 4. 在开发模式下运行CLI
npm run dev -- [command]  # 例如: npm run dev -- send

# 5. 构建生产版本
npm run build

构建后的输出在 dist/ 目录下，你可以直接运行 node dist/index.js 来测试构建结果。

7.2 潜在的贡献方向

浏览项目的GitHub Issues页面，你可以找到许多待解决的问题和功能建议，例如：

• 支持更多编辑器/IDE ：官方路线图中提到了对Cursor、VS Code的支持。如果你熟悉这些编辑器的扩展开发，可以参与贡献。
• 增强分析维度 ：例如，增加对“调试会话”与“生成会话”的区分，分析AI在重构任务中的效率等。
• 改进报告可视化 ：当前的HTML报告是功能性的，但在交互性和图表美观度上有很大提升空间。
• 本地化/国际化 ：为CLI界面和报告增加多语言支持。
• 修复特定环境下的Bug ：比如在Windows某些特定版本下的路径问题，或与某个Claude Code版本的兼容性问题。

7.3 社区与支持

遇到问题时，除了自己调试，也可以寻求社区帮助：

• GitHub Issues ：这是报告Bug和请求新功能的官方渠道。在提交Issue前，最好先搜索一下是否已有类似问题。
• 项目讨论区 ：一些非Bug类的讨论，如使用技巧、最佳实践分享，可能更适合在GitHub Discussions（如果项目开启）或相关社区进行。
• 阅读源码 ：很多时候，问题答案就在源码中。由于其代码可读性很好（未压缩且带Source Map），通过阅读相关模块的源码，你不仅能解决问题，还能更深刻地理解工具的行为逻辑。

从我个人的使用体验来看，vibe-log-cli 填补了AI辅助开发领域的一个关键空白： 可观测性 。它让我们从凭感觉使用AI，转向了用数据驱动来优化与AI的协作。它的本地优先设计和强大的隐私保护机制，让它能毫无负担地融入任何严肃的开发环境。无论是想快速准备站会，还是深度复盘提升提示词技巧，抑或是单纯想量化自己的AI编程投入，这个工具都提供了一个可靠、安全且高效的解决方案。