1. 项目概述一个为Claude Code量身打造的成本追踪与工作流管理工具如果你和我一样日常重度依赖Anthropic的Claude Code进行编程和问题解决那你一定对那个“黑盒子”般的成本消耗感到过焦虑。每次敲下回车看着代码助手飞速生成回复心里总会嘀咕“这又花了多少钱”、“今天是不是用超了”。更麻烦的是当你在一个项目上断断续续工作好几天想把所有相关的对话、成本、以及解决问题的关键思路整理成一份可追溯的“工作日志”时你会发现这几乎是个不可能完成的任务——对话记录散落在各处成本数据深埋在JSON文件里上下文切换的成本高得惊人。这就是我开发Ledger的初衷。它不是一个简单的“记账”工具而是一个集成了终端仪表盘、Web可视化界面和智能Slash命令的一体化工作流增强套件。它的核心使命很明确让你在享受Claude Code强大生产力的同时对成本消耗了如指掌并能将零散的“工作会话”结构化、资产化。你不再需要手动翻找日志文件也不用在多个工具间来回切换。从启动一个编码任务到过程中记录关键节点再到最终复盘总结Ledger提供了一套完整的、与你的开发环境深度集成的解决方案。无论你是独立开发者还是团队的技术负责人它都能帮助你建立更透明、更高效、也更经济的AI辅助编程习惯。2. 核心设计思路无侵入、全自动、可扩展的成本与工作流追踪在设计Ledger之初我就定下了几个不可妥协的原则这些原则直接决定了它的技术架构和用户体验。2.1 无侵入式数据采集直接解析本地日志零配置启动第一个也是最重要的原则是绝对的无侵入性。我不希望用户为了使用Ledger还得去申请和管理Anthropic的API密钥或者在Claude Code里进行复杂的配置。这既增加了使用门槛也带来了额外的安全风险。解决方案我深入研究了Claude Code的本地存储机制。发现它会在用户目录下通常是~/.claude/projects/以JSON Lines.jsonl格式忠实记录每一次对话的完整信息包括使用的模型、输入的提示词Prompt、生成的回复、消耗的Token数量以及Anthropic官方计算出的成本。这简直是一个宝藏Ledger的核心引擎ledger-core模块其首要任务就是实时监控并解析这些JSONL文件。这个过程是完全自动化的。安装Ledger后你只需要在终端运行ledger命令它就会自动定位到你的Claude Code日志目录解析所有历史对话并立即生成一份成本报告。你不需要告诉它你的API Key也不需要配置任何网络代理。所有计算都在本地完成你的对话数据永远不会离开你的电脑。这种设计在保障隐私和安全的同时实现了“开箱即用”的极致体验。2.2 会话Session概念将离散对话串联为有意义的“工作单元”单纯记录单次对话的成本是远远不够的。在实际开发中我们解决一个功能Feature、修复一个BugBug或进行一次探索Explore往往由多次来回的对话组成。这些对话在时间上可能是分散的但在逻辑上属于同一个“工作单元”。为此我引入了“会话”Session这个核心概念。一个Session代表一个完整的工作目标比如“实现用户登录模块”或“排查首页加载缓慢的问题”。它由一个Markdown文件定义存储在项目根目录的./sessions/文件夹下。这个文件采用“YAML Frontmatter Markdown内容”的结构--- id: feature-auth-login-20240415 type: feature goal: 实现基于JWT的用户登录与鉴权中间件 started_at: 2024-04-15T10:30:00Z ended_at: 2024-04-15T12:15:00Z duration_minutes: 105 total_cost: 0.87 conversation_ids: [“conv_abc123”, “conv_def456”] tags: [“authentication”, “express”, “jwt”] --- # 进度记录 - 10:30 开始。向Claude Code描述了需求需要一个Express中间件用于验证JWT并提取用户信息。 - 11:15 完成了 authMiddleware.js 的初版Claude提供了完整的代码和单元测试示例。 - 11:45 遇到了一个关于Token刷新逻辑的问题进行了约30分钟的调试对话。 - 12:15 功能完成代码已提交git commit: a1b2c3d。 # 提取的教训AI自动总结 1. JWT密钥应通过环境变量注入绝不可硬编码。 2. 在中间件中需要妥善处理Token过期和无效的多种情况返回清晰的401状态码。 3. ...通过Slash命令如/project:session-start你可以轻松创建并关联一个Session。此后所有在这个Session期间与Claude Code的对话其ID都会被自动记录到该Session文件中。session-update命令让你可以随时插入带时间戳和当前Git状态的进度笔记。当工作完成时session-end命令会帮你计算总耗时、总成本并尝试让AI从对话历史中自动提取关键教训和总结。这样做的巨大好处你的项目不再只有一堆源代码和零散的AI对话。你拥有了一个结构化的“项目日志”清晰地记录了每个功能或Bug是如何在AI辅助下完成的花了多少时间和成本遇到了哪些坑学到了什么。这对于个人复盘、团队知识沉淀乃至项目成本核算都有着不可估量的价值。2.3 三层交互界面适配不同场景的使用习惯不同开发者有不同的工作习惯。有人喜欢待在终端里有人偏爱华丽的图表还有人希望信息能直接集成到Shell提示符中。为了满足所有人Ledger提供了三种交互界面命令行界面CLI与终端用户界面TUI这是为“终端原住民”准备的。ledger命令快速输出报告ledger tui则启动一个交互式的终端仪表盘使用方向键和Vim式快捷键浏览会话、查看成本趋势信息密度高响应迅速。Web图形化仪表盘运行ledger open或npm run dev一个基于React和Recharts构建的现代化仪表盘会在浏览器中打开默认http://localhost:4200。这里有用颜色区分的成本趋势图、按类型分类的会话饼图、详细的表格列表所有数据一目了然非常适合做周期性回顾和分享。Shell状态集成ledger status -s命令会输出一个极简格式的成本摘要如[$0.42]。你可以将它集成到你的Zsh或Bash提示符PS1中。这样你的终端提示符随时显示着本次登录会话中消耗的Claude Code成本形成一种温和的“成本意识”提醒。这三种界面共享同一个后端数据API确保了数据的一致性。你可以根据当下场景自由选择最顺手的方式。3. 核心模块解析与实操部署理解了设计思路我们来看看如何把它用起来。Ledger的架构清晰部署简单但其中几个核心模块的配合值得深入了解一下。3.1 数据流引擎从原始日志到可读洞察整个系统的数据流始于~/.claude/projects/目录下的.jsonl文件。每个文件对应Claude Code中的一个项目。Ledger的parser模块会读取这些文件逐行解析JSON对象。一个典型的对话记录对象包含如下关键字段{ “id”: “conv_xyz789”, “model”: “claude-3-opus-20240229”, “input_tokens”: 150, “output_tokens”: 450, “cost_usd”: 0.012, “created_at”: “2024-04-15T10:31:22Z”, “prompt”: “帮我写一个Express JWT验证中间件...”, “response_preview”: “以下是实现代码...” }解析器会按时间排序并按conversation_id进行聚合计算出每个对话的总成本、总Token数。同时它会去./sessions/目录下扫描所有的Markdown Session文件通过YAML Frontmatter中的conversation_ids字段将对话与会话关联起来。这样我们就得到了两个维度的数据原始的对话流水和聚合后的工作会话。3.2 后端API提供统一的数据服务解析后的数据通过一个轻量级的Express服务器server/server.ts暴露为RESTful API。这是整个系统的中枢无论是TUI还是Web前端都通过调用这些API来获取数据。核心API端点包括GET /api/summary: 获取全局摘要如今日总成本、本月总成本、平均会话成本等。GET /api/conversations: 获取对话列表支持分页、按时间过滤。GET /api/sessions: 获取所有工作会话的列表和详情。GET /api/status: 获取当前活跃会话的状态用于Shell提示符集成。GET /api/analytics: 获取用于图表展示的分析数据如按日成本趋势、按会话类型分布。这个后端的设计非常简洁它不做复杂的数据处理主要职责是读取、聚合和提供数据。所有复杂的业务逻辑如成本预测、教训提取都放在CLI命令或Slash命令中实现。3.3 前端与TUI数据的不同呈现方式Web前端是一个典型的Vite React TypeScript应用。它使用Recharts来绘制所有图表用TanStack Table来构建可排序、可过滤的会话表格。UI设计追求清晰明了重点是通过颜色红色代表成本高绿色代表成本低和图表让数据自己说话。TUI终端用户界面则是用Ink库构建的。Ink允许你在终端中用React的方式来构建UI组件。Ledger的TUI模拟了一个多面板的仪表盘左侧是会话列表右侧是选中会话的详细信息和成本走势图。它完全通过键盘操作非常适合不想离开终端的用户。实操部署步骤全局安装打开你的终端运行npm install -g rezaiyan/ledger。这会将ledger命令行工具安装到你的系统路径。在项目中初始化进入你的项目根目录运行npm init -y如果还没有package.json然后运行npm install rezaiyan/ledger --save-dev。这会在本地安装Slash命令所需的依赖。创建命令目录在你的项目根目录下创建一个commands/文件夹。这是Claude Code寻找Slash命令的标准位置。链接Slash命令你可以从Ledger的GitHub仓库复制预定义的命令文件如session-start.md,session-update.md到你的commands/目录。更简单的方法是在项目目录下运行ledger init如果该命令可用它会帮你完成初始化和示例文件的创建。验证安装运行ledger。如果一切正常你会看到一份从你本地Claude日志中生成的成本报告。运行ledger open则会启动Web服务器并打开仪表盘。注意首次运行时Ledger需要读取和分析你所有的历史对话日志如果对话量很大这可能需要几秒钟时间。请耐心等待。同时请确保你的Claude Code确实将日志保存在默认路径如果你的环境特殊可以使用--dir全局参数指定自定义的日志目录。4. Slash命令工作流详解与Claude Code深度协作Slash命令是Ledger与Claude Code工作流深度融合的“魔法棒”。它们不是普通的脚本而是遵循Claude Code规范的、用自然语言编写的指令文件。当你在Claude Code的聊天框中输入/project:session-start时Claude Code会读取commands/session-start.md文件的内容并将其作为系统指令来执行。4.1 核心命令拆解与使用场景让我们深入看看几个最关键的Slash命令是如何工作的/project:session-start [type] [goal]这是开始一项新工作的起点。当你输入/project:session-start feature “添加用户个人资料页面”时Claude Code会执行session-start.md中的指令。指令会让Claude Code分析你过去所有type为feature的会话的历史成本数据计算出一个平均成本和可能的成本范围。然后Claude Code会向你展示一个提示“根据历史数据类似的‘功能开发’会话平均成本约为 $1.20。本次会话的目标是‘添加用户个人资料页面’。建议你规划好实现步骤控制对话轮次以管理成本。是否确认开始”你确认后Ledger会在./sessions/目录下创建一个新的Markdown文件记录开始时间、类型、目标并等待后续对话的关联。/project:session-update [note]这是你工作过程中的“检查点”。比如在实现过程中完成了一个关键函数你可以输入/project:session-update 完成了UserProfile组件的核心状态逻辑与API集成。命令会找到当前活跃的Session文件。在Markdown内容部分追加一行带时间戳的笔记例如- [2024-04-15 11:20] 完成了UserProfile组件的核心状态逻辑与API集成。一个非常实用的细节它还会自动执行git status --short并将结果附加到笔记中这样你就知道在记录这个进度点时代码仓库的状态是怎样的例如有哪些文件被修改了。这为后续复盘提供了极其宝贵的上下文。/project:session-end工作完成时使用此命令优雅地关闭会话。它会计算会话从开始到结束的总时长。聚合该会话关联的所有对话的总成本。执行“教训提取”这是一个亮点功能。它会将本次会话中的所有对话记录Prompt和Response发送给Claude模型注意这里需要Claude API权限因为它超出了本地日志的范围请求模型从对话历史中总结出2-3条最关键的技术教训、决策点或最佳实践并自动写入Session文件的“教训”部分。最后它会提示你为整个会话写一个简短的人工总结。4.2 高级命令数据分析与复盘/project:session-review [N]这是你的“效率教练”。运行/project:session-review 10它会分析你最近10个已完成的工作会话。它会计算你在不同会话类型feature, bug, refactor上的平均成本、平均时长。识别出哪些会话的成本显著高于同类平均值“异常高耗会话”。尝试分析高耗会话的对话内容找出可能的原因是需求不明确导致来回沟通是探索性任务本身开销大还是遇到了特别棘手的技术难题生成一份简洁的报告帮助你反思和优化与AI协作的模式。/project:session-check在长时间的工作会话中随时运行此命令。它会对比你当前会话已产生的成本和历史上同类型会话的平均成本给你一个实时的“预算提醒”。比如“当前会话成本为 $0.65同类会话平均成本为 $0.90。进度正常。”4.3 实操心得与配置技巧会话类型Type的选择很重要我强烈建议你坚持使用feature、bug、refactor、explore、research这些预定义类型。这不仅仅是为了分类好看更是为了后续基于类型的数据分析。session-review和成本预测功能都严重依赖于类型的准确性。other类型应作为真正的“其他”用途的兜底。目标Goal描述要具体在session-start时花30秒写一个清晰、具体的目标。例如“修复用户登录后页面跳转404的错误”就比“修复一个Bug”好得多。具体的目标不仅能帮你聚焦也让后续的“教训提取”和复盘更有价值。善用session-update不要只在最后才记录。每完成一个小的里程碑或者每次与Claude进行了一次重要的、有决策性质的对话后都习惯性地用session-update记录一下。这些带有时间戳和Git状态的笔记在你一周后回顾“这个功能当时为什么这么设计”时会是救命稻草。自定义你的命令commands/目录下的.md文件是完全开放的。你可以根据自己团队的工作流修改这些指令。例如你可以在session-end的指令中加入自动生成Jira ticket评论或者将总结发送到团队Slack频道的逻辑。5. 常见问题排查与性能优化即使设计得再完善在实际使用中也可能遇到一些小问题。下面是我在开发和长期使用中遇到的一些典型情况及解决方法。5.1 数据读取与权限问题问题运行ledger命令后无输出或提示“未找到对话日志”。排查步骤1确认日志路径。Claude Code的日志默认在~/.claude/projects/。你可以通过ls -la ~/.claude/projects/检查该目录是否存在及是否有.jsonl文件。如果Claude Code被安装在非标准位置或使用了自定义配置日志路径可能不同。解决方案使用--dir参数手动指定路径ledger --dir /path/to/your/claude/logs。排查步骤2检查文件权限。确保运行Ledger的用户有读取~/.claude/projects/目录及其下文件的权限。解决方案可以尝试修改目录权限需谨慎chmod 755 ~/.claude/projects/。更好的做法是确保你用安装Claude Code的同一个用户账户运行Ledger。问题Web仪表盘ledger open无法启动或访问失败。排查步骤1端口冲突。默认端口是4200可能被其他应用如另一个前端开发服务器占用。解决方案使用--port参数指定另一个端口例如ledger open --port 4201。排查步骤2防火墙或安全软件阻止。某些系统防火墙或安全软件可能会阻止本地服务器。解决方案检查本地防火墙设置确保允许localhost环回地址上的连接。对于macOS可以暂时禁用防火墙测试对于Windows检查Windows Defender防火墙入站规则。5.2 Slash命令执行失败问题在Claude Code中输入/project:session-start无反应或提示“命令未找到”。排查步骤1确认命令目录。Claude Code只在当前项目根目录下的commands/文件夹中寻找Slash命令。请确保你的session-start.md等文件位于your-project-root/commands/下而不是其他子目录或全局位置。排查步骤2检查命令文件格式。Slash命令文件是纯文本的.md文件但其内容需要符合Claude Code的特定指令格式。最简单的办法是从Ledger项目的Git仓库中直接复制原版文件避免自己编写时格式错误。排查步骤3Claude Code版本。确保你使用的是支持自定义项目级Slash命令的Claude Code版本。如果版本太旧可能不支持此功能。问题session-end命令中的“教训提取”功能失效。原因这个功能需要调用Claude的API来分析整个对话历史并生成总结。它超出了本地日志文件的范围。解决方案你需要确保在运行该命令的环境中已经配置了有效的ANTHROPIC_API_KEY环境变量。你可以在Anthropic的官网上申请API密钥。如果没有配置session-end仍然会工作但会自动跳过“教训提取”这一步仅完成时长和成本计算。5.3 性能与数据量管理问题随着对话日志越来越多超过数万条ledger命令运行变慢。原因每次运行Ledger都需要读取并解析所有的JSONL文件。当文件非常大时I/O和解析会成为瓶颈。优化方案1增量解析与缓存。这是我计划在后续版本中加入的功能。目前你可以考虑以下手动优化优化方案2定期归档旧日志。Claude Code的日志是按项目存储的。对于已经完结的、很久不用的老项目你可以将其对应的.jsonl文件从~/.claude/projects/目录移走备份到其他位置。Ledger只会读取当前目录下的文件。优化方案3使用--dir指向一个经过筛选的日志子集。你可以写一个简单的脚本定期将你关心的、近期活跃的项目的日志复制到一个单独的目录然后让Ledger指向这个目录。问题Web仪表盘在显示大量会话时变得卡顿。原因前端一次性加载了过多的会话数据比如超过1000个进行渲染和图表绘制。解决方案后端API已经支持分页和过滤。你可以修改前端代码或等我后续更新默认只加载最近30天或最近100个会话的数据。对于历史数据的查看可以通过筛选器按时间范围或类型进行查询。5.4 自定义与扩展问题我想跟踪除了成本以外的其他指标比如“对话轮次”或“解决的问题数量”。扩展思路Ledger的架构是模块化的。你可以修改parser模块在解析JSONL时提取你关心的新字段例如通过分析对话轮次。在后端API的响应数据结构中添加新的字段。在前端或TUI的界面上增加新的展示组件。修改Slash命令的指令在Session的YAML Frontmatter中记录你的自定义指标。问题我想将数据导出到其他系统如Notion、Google Sheets做进一步分析。解决方案Ledger的后端API (/api/sessions,/api/conversations) 返回的是标准的JSON数据。你可以很容易地写一个Python脚本或Node.js脚本定期调用这些API例如curl http://localhost:4200/api/sessions然后将数据转换并推送到你想要的任何地方。这为团队级的成本监控和分析打开了大门。最后一个我个人的深刻体会是工具的价值在于改变习惯。Ledger最大的作用不是事后告诉你花了多少钱而是在你工作的每一个环节——开始前、进行中、结束后——通过轻量的提示和结构化的记录帮助你建立起一种更理性、更高效的与AI协作的节奏。它让原本隐形的成本变得可见让零散的思考变得有迹可循。当你养成了为每个小任务创建Session、定期Update、认真End的习惯后你会发现你不仅更好地控制了预算也收获了一份宝贵的、属于你自己的AI辅助编程知识库。