1. 项目概述AI编码助手日志的“黑匣子”解读器如果你和我一样日常开发中重度依赖Claude Code、OpenAI Codex或者Gemini CLI这类命令行AI编码助手那你肯定遇到过这个场景助手告诉你“我刚刚修改了30个文件分布在6个目录里”然后你心里一紧赶紧去翻看Git diff。但问题是这30个文件到底是怎么被改的AI在写代码时到底“想”了什么它调用了哪些工具有没有执行一些危险的shell命令最关键的是这波操作花了多少token值不值那个价钱传统的做法是去翻找这些工具生成的原始日志文件它们通常是以JSONL格式散落在用户目录的各个角落比如~/.claude/projects/或~/.codex/sessions/。面对这些结构复杂、嵌套深的原始数据排查效率极低更别提在Claude、Codex、Gemini几个工具间来回切换体验堪称灾难。clicodelog 就是为了解决这个痛点而生的。它是一个完全本地的Web应用核心功能就一个把你所有AI编码助手的会话日志用一种清晰、统一、可交互的方式呈现出来。你可以把它理解为一个专为AI编码日志设计的“仪表盘”或“黑匣子解读器”。它不发送任何数据到云端所有操作都在你的本地机器上完成读取的是工具本身生成的日志然后同步到自己的./data/目录做备份和索引。简单来说有了clicodelog你就能透视思考过程完整看到AI的“内心独白”thinking blocks、决策链和工具调用记录。审计代码变更清晰地追踪每一次文件读取、编辑和命令执行在合并代码前做到心中有数。优化成本开销直观对比不同会话的token消耗输入、输出、缓存识别低效或陷入循环的会话。统一管理界面在一个地方管理Claude、Codex、Gemini的日志告别来回切换和格式不统一的烦恼。无论你是想深入理解AI助手的工作模式严格审计其生成的代码还是单纯想优化自己的token使用效率clicodelog都能提供一个不可或缺的观察窗口。接下来我会带你从设计思路到实操细节完整拆解这个工具。2. 核心设计思路与架构解析clicodelog的设计非常务实它没有尝试去修改或拦截AI助手的运行过程而是选择做一个“事后诸葛亮”——一个专注、高效的日志分析器和可视化器。这个定位决定了其架构的几个关键特点。2.1 数据源驱动的插件化架构项目的核心是一个数据源Source管理系统。在app.py中SOURCES字典定义了所有支持的AI工具。每个数据源需要三个关键信息name: 工具的显示名称。source_dir: 该工具在本地存储原始日志的根目录路径。data_subdir: clicodelog内部用于备份和索引该工具日志的子目录名称。SOURCES { claude-code: { name: Claude Code, source_dir: Path.home() / .claude / projects, data_subdir: claude-code }, # ... 其他源 }这种设计的好处是高度解耦。添加对新工具的支持理论上只需要在SOURCES字典里新增一个条目并实现对应的日志解析器Parser。解析器的职责是将不同工具特有的JSONL或JSON格式转换成clicodelog内部统一的会话Session和项目Project数据结构。为什么选择这种架构因为AI编码助手的日志格式差异很大。Claude Code按项目目录组织Codex按日期目录组织Gemini CLI则用哈希值区分项目。一个统一的抽象层可以屏蔽这些差异为前端提供一致的API。这比写一个能解析所有格式的“超级解析器”要清晰、可维护得多。2.2 本地优先与数据同步策略“Nothing leaves your machine”是项目的核心承诺之一。这意味着所有计算和渲染都发生在你的浏览器和本地Python服务中。为了实现这一点clicodelog采用了“源目录读取 本地备份”的双层数据策略。源目录是只读的参考。clicodelog启动时或手动同步时从这里读取最新日志。./data/目录是可写的缓存和备份。它将源目录的数据结构包括目录层级原样复制过来并在此基础之上构建索引方便快速查询。同步机制详解启动同步每次运行clicodelog命令都会自动触发一次全量同步确保本地备份是最新的。定时同步后台每小时自动同步一次这是一个平衡点既不会过于频繁消耗IO又能保证数据相对新鲜。手动同步前端提供“ Sync”按钮可以随时对当前查看的数据源进行强制刷新。这种策略既保证了数据的实时性通过同步又将可能频繁的读取操作与AI工具本身的日志目录隔离开避免了潜在的干扰。同时./data/目录的存在也使得即使原始日志被清理你仍然可以查阅历史记录。2.3 前后端分离与轻量级技术栈前端是一个单页应用SPA后端是一个简单的Flask应用。两者通过一组清晰的RESTful API通信。这种选择非常契合工具类项目的需求Flask后端足够轻量启动快专注于提供数据API如/api/projects,/api/sync和静态文件服务。它不需要复杂的ORM因为数据就是文件系统上的JSON。纯前端渲染所有会话内容的解析、对话树的渲染、代码高亮、差异对比都在浏览器端完成。这大大减轻了后端压力并且能提供更流畅的交互体验。比如切换会话时无需重新加载页面。技术选型的考量没有选择更重的Django或异步框架如FastAPI是因为这个工具的数据流并不复杂也没有高并发需求。Flask的简洁性使得代码更易于理解和修改这对于一个旨在让开发者自己可能想定制化的工具来说是一个重要优势。前端同样没有使用React/Vue等框架而是原生JS保持了极致的轻量和可控性。3. 详细功能拆解与实操指南了解了整体架构我们深入看看clicodelog具体能做什么以及怎么用它来提升你的日常开发效率。3.1 会话浏览与思维链追溯这是clicodelog最核心的价值。打开界面左侧是项目列表右侧是主内容区。选择一个项目后你会看到该项目的所有会话列表。关键信息呈现会话概览每个会话卡片会显示开始时间、使用的模型如claude-3-5-sonnet-20241022、总token消耗以及一个简短的摘要通常是AI的第一条思考或用户的第一条指令。完整对话流点击进入会话你会看到一个类似聊天界面的视图。这里完整还原了AI与“环境”的交互过程而不仅仅是用户和AI的对话。这包括用户消息你输入的指令。AI思考(thinking): 这是最宝贵的部分以灰色或折叠块的形式展示点开可以看到AI在回复前进行的内部推理。这对于理解其代码决策逻辑至关重要。工具调用(tool_calls): 详细列出AI调用了哪些函数参数是什么。例如read_file,write_file,run_command等。run_command会高亮显示提醒你注意AI执行了哪些Shell命令。工具调用结果(tool_results): 显示工具执行的输出比如读取的文件内容、命令执行的结果。实操心得如何高效审查我个人的习惯是在让AI执行大规模重构或修改关键文件后一定会用clicodelog过一遍。我会重点关注顺序扫描思考块看AI是否理解了需求的本质它的分步计划是否合理。检查文件读写通过write_file调用快速定位所有被修改的文件并直接查看前后差异clicodelog通常会用diff视图展示。警惕run_command这是最高风险操作。我会逐一检查AI执行了哪些命令特别是涉及rm、chmod、git reset等具有破坏性的命令确保其意图和参数是正确的。3.2 多源统一管理与切换clicodelog在顶部提供了一个数据源下拉选择框。你可以随时在Claude Code、OpenAI Codex和Gemini CLI之间无缝切换。界面布局和交互逻辑完全一致这消除了因工具不同带来的认知负担。背后的实现当你切换数据源时前端会调用/api/sources/source_id接口后端会设置当前活跃的源。此后所有关于项目、会话的请求都会自动带上?sourcesource_id参数后端根据这个参数去读取对应./data/子目录下的数据。注意事项首次打开一个数据源时如果本地./data/目录下没有对应的备份可能需要等待同步完成或手动点击同步。不同工具的信息密度和格式不同。例如Claude的思考块可能非常详细而Codex的可能更简洁。需要在心理上适应这种差异。3.3 Token成本分析与会话统计在会话列表和会话详情页clicodelog都会醒目地展示token使用情况通常包括Input Tokens: 输入给模型的token数。Output Tokens: 模型输出的token数。Cached Tokens(如果支持): 从缓存中读取的token数这部分可能不收费或收费更低。如何利用这些数据成本归因将一个具体的开发任务如“重构用户认证模块”与token消耗挂钩帮助你评估使用AI助手的性价比。识别低效模式如果你发现某个会话的token数异常高比如输出token是输入token的数十倍点进去看看。很可能AI陷入了“长篇大论”的解释或者在一个循环里反复尝试。这提示你下次可能需要更精确的指令或设置更严格的输出长度限制。对比模型效率如果你同时在用Claude和Codex完成类似任务可以横向对比两者的token消耗作为选择模型的参考之一。3.4 数据导出与本地备份管理每个会话详情页都有一个“ Export”按钮可以将当前会话的完整内容包括思考过程和工具调用导出为一个格式化的.txt文件。这对于存档、分享给同事讨论或者作为提示工程Prompt Engineering的案例分析材料非常有用。关于./data/目录的管理 这个目录是clicodelog自动创建的它完整镜像了源数据的结构。你需要知道它是纯备份删除这里的文件不会影响原始的AI工具日志。下次同步时会重新生成。可以手动清理如果你需要释放磁盘空间可以安全地删除整个./data/目录或其中的子目录。clicodelog重启时会重新同步。注意权限确保运行clicodelog的用户对该目录有读写权限。4. 从安装到进阶使用的完整流程4.1 环境准备与安装clicodelog需要Python 3.7。我强烈推荐使用uv来安装它是新一代的Python包管理器和安装器速度极快能创建独立的工具环境避免污染你的全局Python。# 1. 安装 uv (如果尚未安装) curl -LsSf https://astral.sh/uv/install.sh | sh # 安装后可能需要重启终端或 source ~/.bashrc (或 ~/.zshrc) # 2. 使用 uv 安装 clicodelog uv tool install clicodeloguv tool install会创建一个独立的、可全局运行的clicodelog命令。这是最干净的方式。备选方案# 使用 pip 全局安装 (可能需注意权限) pip install clicodelog # 或者从源码安装便于调试和贡献 git clone https://github.com/monk1337/clicodelog.git cd clicodelog uv tool install -e . # 使用 uv 以可编辑模式安装 # 或 pip install -e .4.2 基础使用与配置安装成功后使用极其简单# 直接运行使用默认端口(6126)和主机(127.0.0.1) clicodelog首次运行会执行以下操作检查端口6126是否被占用如果占用则尝试终止该进程。开始从所有已配置的数据源~/.claude/projects/,~/.codex/sessions/,~/.gemini/tmp/同步数据到./data/。启动Flask服务器并在浏览器中打开或提示你访问http://localhost:6126。常用命令行选项clicodelog --port 8080 # 指定运行端口 clicodelog --host 0.0.0.0 # 绑定到所有网络接口允许同一网络内其他设备访问 clicodelog --no-sync # 跳过启动时的自动同步快速启动查看已有数据 clicodelog --debug # 启用调试模式输出更多日志注意--host 0.0.0.0在某些场景下很有用比如你想在本地虚拟机或容器里运行服务从宿主机访问。但在公司或公共网络环境下使用需谨慎避免服务暴露。4.3 界面操作详解启动后你会看到一个简洁的Web界面。选择数据源左上角的下拉菜单在Claude Code、OpenAI Codex、Gemini CLI之间切换。浏览项目左侧边栏会列出当前数据源下的所有“项目”。对于Claude Code项目对应实际的项目目录对于Codex项目是根据工作目录cwd自动分组的结果。查看会话点击一个项目右侧会列出该项目下的所有会话按时间倒序排列。点击任意会话即可在详情区查看完整内容。主题切换界面右上角通常有太阳/月亮图标用于切换亮色/暗色主题。手动同步在数据源下拉菜单附近或有单独的同步按钮点击可强制刷新当前数据源的日志。4.4 高级技巧与自定义定期自动启动如果你每天都用可以把它设为开机启动或终端启动项。例如在~/.zshrc或~/.bashrc里添加一个别名让它以后台方式运行alias start-clicodelogclicodelog --host 127.0.0.1 --port 6126 /tmp/clicodelog.log 21 这样打开终端输入start-clicodelog即可。数据清理策略./data/目录会随着时间增长。你可以写一个简单的cron任务定期清理旧数据。例如保留最近30天的数据# 在crontab中添加每周日凌晨3点执行 0 3 * * 0 find /path/to/your/clicodelog/data -type f -name *.json -mtime 30 -delete请务必根据你的实际路径和需求调整。支持新的AI工具这是clicodelog扩展性最好的体现。假设一个新的AI编码工具“FooAI”将其日志存在~/.fooai/logs/下格式为每行一个JSON对象。你需要做两件事在app.py的SOURCES字典中添加一个新条目。在代码中实现或修改一个解析函数能够读取~/.fooai/logs/下的文件并将其转换为与现有Project和Session结构兼容的格式。这通常需要你研究一下FooAI的日志格式样本。5. 常见问题排查与实战经验即使工具设计得再完善在实际使用中也可能遇到一些小问题。下面是我在长期使用中总结的一些常见情况和解决方法。5.1 启动与同步问题问题启动时提示“Address already in use”或端口被占用。原因端口6126已被其他进程使用。clicodelog虽然会尝试自动结束占用端口的进程但可能权限不足。解决使用clicodelog --port 另一个端口指定新端口。或者手动找出并结束占用6126端口的进程# Linux/macOS lsof -ti:6126 | xargs kill -9 # 如果不知道哪个进程先查看 lsof -i:6126问题同步失败日志显示“Permission denied”或找不到目录。原因clicodelog没有读取AI工具日志目录的权限或者该目录不存在。解决确认你使用的AI工具如Claude Code已经成功运行过并生成了日志目录。检查目录路径是否正确是否有读取权限。可以手动ls -la ~/.claude/projects/看看。如果目录不存在可能是AI工具还未产生任何会话日志。先使用AI工具执行一次简单的操作。问题界面空白或无法加载项目列表。原因可能是前端资源加载失败或后端API没有正确返回数据。解决打开浏览器的开发者工具F12查看“网络”(Network)标签页确认所有JS/CSS文件是否成功加载状态码200。查看“控制台”(Console)标签页是否有JavaScript错误。检查后端日志。在启动clicodelog的命令行窗口或者如果你重定向了日志查看日志文件确认是否有Python异常抛出。5.2 数据解析与显示问题问题某些会话的思考块或工具调用显示为“Raw Data”或格式错乱。原因AI工具的日志格式可能发生了更新而clicodelog的解析器没有及时适配。不同版本的工具其JSON结构可能有细微差别。解决这是一个开源项目你可以到GitHub仓库的Issues页面查看是否有类似问题或提交一个新的Issue。如果你有Python能力可以尝试自己修复。关键是在app.py中找到对应数据源的解析逻辑根据新的日志格式调整代码。通常需要处理的是JSON字段路径的变化或新增的字段。问题Token统计数字不准确或缺失。原因并非所有AI工具或所有模型版本都在日志中提供完整的token计数信息。有些可能只提供总数有些可能不提供缓存token数。解决这是数据源的限制。clicodelog只是信息的呈现者。可以将其视为一个参考值。如果某个工具的token统计对你至关重要可能需要向该工具的开发者反馈建议他们在日志中增加更详细的信息。5.3 性能与使用技巧问题数据量很大时界面加载或切换比较慢。原因clicodelog在首次同步或加载包含大量会话的项目时需要读取和解析很多JSON文件。前端在渲染超长的思考块或文件差异时也可能有压力。解决利用搜索/过滤如果界面提供了搜索功能尽量使用它来定位特定会话而不是滚动浏览成百上千条记录。定期清理旧数据如前所述可以设置定时任务清理./data/里过旧的会话备份。分而治之对于特别庞大的项目考虑在AI工具中将其拆分为逻辑上更独立的子项目这样日志也会被分开存储和查看。实战经验将clicodelog集成到工作流中我个人的工作流是这样的开发中让AI助手执行一个复杂任务后不急着看代码先打开clicodelog快速浏览其思考过程和修改摘要对改动范围有个整体把握。代码审查前在运行测试或提交PR前用clicodelog做一次“AI操作审计”重点检查run_command和关键文件的write_file差异确保没有意外更改。提示词优化如果一次会话消耗了异常多的token但效果不佳我会把整个会话导出分析AI在哪里陷入了困惑或产生了冗余输出从而优化我下一次的提示词。知识沉淀将一些成功的、展示了精妙问题解决思路的会话导出存档作为团队内部的“最佳实践”案例。clicodelog本质上是一个增强你“观察力”的工具。它不会替你写代码但能让你更清晰地看到AI是如何工作的从而建立更有效的协作关系。从最初的“黑盒”到现在的“灰盒”这种透明度的提升对于安全、可控、高效地使用AI编码助手来说是至关重要的一步。