1. 项目概述一个能区分“你”与“AI”的贡献日历作为一名长期与AI结对编程的开发者我发现自己越来越依赖Claude Code这类工具。它不仅是代码补全助手更能在后台以“子代理”模式自主运行处理一些我发起的、但无需我实时监督的任务比如发布npm包、更新文档、运行测试套件。久而久之一个问题浮现出来我的GitHub贡献日历上那些绿油油的小方格有多少真正代表了我的“亲手”劳动又有多少是AI在我离线时默默完成的“幽灵工作”为了看清这个模糊地带我动手构建了cc-calendar。它是一个纯终端工具能读取你的Claude Code会话日志并生成一个GitHub风格的贡献日历视图。但它的核心创新在于双重视角用青色Cyan方块代表“你”的交互式会话时间用黄色Yellow方块代表AI自主运行的“子代理”会话时间。更关键的是它引入了“幽灵日”的概念——那些你本人会话时间为零但AI却仍在辛勤工作的日子这些日子会被高亮显示。当你运行npx cc-calendar看到自己的时间被如此清晰地解构那种感觉非常直观甚至有些震撼。它不再是一个笼统的“活跃度”指标而是一份关于人机协作模式的精细诊断报告。2. 核心需求与设计思路拆解2.1 从聚合数据到时空洞察为什么需要可视化在开发cc-calendar之前我已经有了cc-agent-load工具。它能输出一个汇总数据比如“过去30天AI工作时间占总开发时间的65%”。这个数字很有用但它是一个静态的、聚合的视角。它无法回答一些更动态的问题模式识别AI是在我睡觉时规律性工作还是随机爆发协作密度我和AI是紧密的“乒乓式”协作我一下AI一下还是我设定好方向后AI进行长时间的“马拉松式”自主任务工作负载转移我是否成功地将一些重复性、流程性的工作完全移交给了AI从而解放了自己的时间GitHub贡献日历的格式几乎是所有开发者本能理解的“语言”。它天然地表达了时间序列和强度梯度。将“人时”与“AI时”映射到这个熟悉的界面上所有上述问题的答案都变得一目了然。这就是cc-calendar最根本的设计动机将抽象的时间占比数据还原到具体的日历坐标中以获得时空层面的协作洞察。2.2 数据源定义如何区分“你”和“AI”要绘制这样一张日历首先必须严格定义数据源和计算逻辑。Claude Code的会话日志通常位于~/.claude/projects/目录下是原始金矿。cc-agent-load工具的作用就是解析这些日志并按照日期进行聚合输出结构化的JSON数据。其核心数据模型如下main(交互式会话小时数): 这代表“你”的时间。更准确地说是你与AI共同处于一个活跃对话上下文中的时间。无论你是正在输入问题还是在阅读、思考AI的回复只要会话窗口是打开的、活跃的这段时间就被计入main。它衡量的是你的“在场”和“参与”。sub(自主子代理会话小时数): 这代表“AI”的时间。当AI以后台任务的形式运行例如执行你发出的“编写测试并运行”、“发布这个版本到npm”等指令而你无需保持会话窗口打开或进行任何交互时这段时间被计入sub。它衡量的是AI的“自主执行”能力。Ghost Day(幽灵日): 这是一个派生指标其逻辑定义为main 0 sub 0。即在某一自然日内你的交互式会话时间为零但AI的子代理会话时间大于零。这一天就被标记为“幽灵日”是可视化中需要重点高亮的部分。这个定义清晰地将“协作”与“委托”区分开来为可视化提供了坚实的数据基础。2.3 技术选型与架构原则极简与零依赖在技术实现上我确立了几个核心原则零依赖工具本身不引入任何第三方npm包。这确保了极致的轻量化和免安装体验通过npx直接运行也避免了依赖冲突和供应链安全风险。纯Node.js环境仅要求Node.js 18利用其原生的文件系统fs、路径path和日期处理能力。这使得工具在任何现代开发环境中都能开箱即用。管道化设计cc-calendar被设计为数据流水线的一环。它不直接解析原始日志而是消费cc-agent-load --json命令产出的、已经清洗和聚合好的JSON数据。这种“单一职责”和“管道过滤”的Unix哲学让每个工具都小巧、专注且易于组合。终端原生渲染输出完全针对终端优化使用Unicode块状字符░▒▓█来模拟GitHub的色块并通过ANSI转义码实现颜色和高亮。这保证了在任何支持颜色的终端中都能获得一致的视觉体验无需启动浏览器或GUI应用。3. 核心实现细节与终端渲染技巧3.1 日历布局算法从日期到二维矩阵终端是线性的但日历是二维的。如何将一年的日期巧妙地映射到终端屏幕上是第一个挑战。我采用了与GitHub类似的布局一个26行 x 7列的矩阵。实现逻辑如下确定时间范围默认渲染最近365天的数据约52周。为了对齐周视图实际计算会找到最近的一个星期日的日期作为日历的起点。构建日期映射初始化一个二维数组weeks[26][7]每个元素对应一个具体的日期。通过从起始日期开始逐日遍历将日期对象填充到对应的“周索引”和“星期几索引”位置。没有数据的日期未来日期或起始日期之前填充为null。数据填充遍历聚合好的JSON数据根据日期键如”2026-02-10″找到矩阵中对应的位置填入该日期的{ main, sub }数据对象。幽灵日标记在填充数据的同时根据main 0 sub 0的条件为对应的日期位置打上isGhostDay: true的标记。这个矩阵就是我们在内存中构建的“数字日历”后续的渲染都基于此。3.2 强度分级与字符映射GitHub的贡献日历用颜色深浅表示贡献度。在黑白终端中我们用字符的“密度”来模拟这种渐变。cc-calendar定义了四级强度强度等级小时数范围 (main 或 sub)对应字符视觉密度无0░最稀疏轻 0 1▒较稀疏中 1 4▓较密集重 4█最密集字符选择的考量选用的░▒▓█是一组在大多数终端字体中都能正确显示、且密度递增效果明显的Unicode块元素字符。它们比单纯用#、等字符更能形成直观的梯度感。渲染时对于每一天我们需要并排显示两个字符左边代表main你右边代表subAI。因此每一天在终端上实际对应两个紧邻的色块形成对比。3.3 ANSI 转义码实现颜色与高亮这是让日历变得直观的关键。我们使用ANSI转义码来为字符着色青色 (You)使用\x1b[36m前景色 cyan来渲染代表main时间的字符。黄色 (AI)使用\x1b[33m前景色 yellow来渲染代表sub时间的字符。幽灵日高亮对于被标记为Ghost Day的日期我们不仅渲染AI的黄色色块还会为这个日期单元格两个字符添加一个亮黄色背景\x1b[103m使其在日历中“脱颖而出”。重置在每个颜色指令后必须紧跟\x1b[0m来重置样式防止颜色污染后续输出。一个具体的渲染函数片段可能如下function renderBlock(hours, isGhost false) { let block ‘░’; if (hours 4) block ‘█’; else if (hours 1) block ‘▓’; else if (hours 0) block ‘▒’; let colorCode ‘\x1b[36m’; // Cyan for ‘You’ // … 逻辑判断如果是AI的块则 colorCode ‘\x1b[33m’; let output colorCode block ‘\x1b[0m’; if (isGhost) { output ‘\x1b[103m’ output ‘\x1b[0m’; // 添加亮黄背景 } return output; }3.4 统计信息的计算与展示日历下方附带的统计面板是量化洞察的核心。其计算完全基于我们已有的数据矩阵活跃日总数main 0 || sub 0的天数。双方活跃日main 0 sub 0的天数。这代表紧密协作的日子。仅你活跃日main 0 sub 0的天数。在我的数据中为0这很有趣。幽灵日如前所述main 0 sub 0的天数。总小时数分别对main和sub的所有值求和。幽灵日占比幽灵日天数 / 活跃日总数 * 100%。这个比例直观地反映了工作被“托管”出去的程度。这些统计数字与上方的可视化日历相互印证让你既能从宏观上把握比例又能从微观上追溯具体某一天的协作模式。4. 从安装到解读完整使用指南4.1 环境准备与快速启动使用cc-calendar的前提是你在使用Claude Code并生成了会话日志同时拥有Node.js环境。步骤1验证数据源首先确保你的cc-agent-load工具能正常工作。在终端运行npx cc-agent-load --json如果能看到按日期分组的JSON输出说明数据源就绪。如果报错可能需要检查~/.claude/projects/目录是否存在及是否有读取权限。步骤2运行日历工具数据就绪后生成日历就只需一行命令npx cc-calendar工具会自动调用cc-agent-load --json获取数据进行处理然后将彩色日历渲染到你的终端。为了获得最佳视觉效果请确保你的终端支持真彩色或至少256色。4.2 解读你的第一份AI协作日历面对生成的日历你可以按以下步骤解读整体扫视先不看图例快速浏览整个日历。黄色和青色区域的分布是怎样的是均匀混合还是各有聚集识别幽灵日寻找那些背景高亮的黄色方块即“幽灵日”。它们集中在哪些时间段是周末还是工作日的晚上这直接反映了你委托AI进行异步工作的时间规律。分析协作模式“乒乓模式”如果很多日期上青色和黄色方块都是中等或深色例如▓▓说明那天你和AI进行了高频的交互与接力。“发射后不管”模式如果常见模式是“一个青色方块后跟着一连串黄色方块尤其是幽灵日”说明你的典型工作流是启动一个任务交互式然后交由AI长时间运行自己则转向其他工作或休息。关注统计面板“幽灵日占比”这个数字是关键。如果像我的83%这样极高说明你的工作流高度依赖AI的自主性。如果很低则说明你更多地将其用作实时助手。“仅你活跃日”为0这像我自己一样意味着没有AI辅助的“纯手工”编码日几乎不存在了。这值得思考是效率的提升还是产生了新的依赖小时数对比比较“Your hours”和“AI hours”。AI的时间比你多很多是正常现象因为它可以并行、不间断地运行任务。4.3 高级用法与定制基础命令已经足够强大但你可以通过一些方式获得更多洞察指定日期范围cc-calendar支持--since和--until参数来查看特定时段。例如想回顾上一个项目冲刺期npx cc-calendar --since 2024-03-01 --until 2024-03-15原始数据输出如果你想把数据用于其他分析工具如导入电子表格可以使用--json参数它会输出原始的、结构化的日历数据而不是渲染后的图形。npx cc-calendar --json my_calendar_data.json结合其他工具cc-calendar是cc-toolkit套件的一员。你可以将它的输出与其他工具联动用cc-ghost-log查看在“幽灵日”里AI具体提交了哪些Git commit了解其工作产出。用cc-session-stats从会话级别分析平均时长、常用指令等与日历的宏观视图互补。注意工具读取的是本地日志文件所有数据都不会离开你的机器。这是分析个人工作效率的绝佳方式无需担心隐私问题。但同时请妥善保管你的日志文件因为它们包含了你的工作习惯和可能的代码片段。5. 深度分析40个“幽灵日”揭示了什么在我的案例中cc-calendar揭示了一个惊人的事实在48个活跃日里有40天是“幽灵日”占比高达83%。这远不是一个需要“修复”的问题而是我工作流设计的预期结果。让我们深入拆解这背后的模式和含义。5.1 “幽灵日”的典型工作流场景这些高亮的黄色方块背后是AI在无人值守状态下完成的具体工作。典型场景包括自动化发布流水线我在下午写好了代码运行测试然后执行claude: 请将版本号从1.2.3升级到1.2.4更新CHANGELOG.md并发布到npm registry。指令。之后我关闭电脑下班。AI会依次完成修改package.json、编写变更日志、运行npm publish、并在成功后向我的通信软件发送通知。整个过程可能持续20分钟但这段时间完全计入subAI时间而我的main时间为零——一个完美的“幽灵日”事件。文档与静态站点生成我的个人博客基于GitHub Pages。我可能会在会话中告诉AI“这是新文章的草稿请将其转换为Markdown插入图片链接优化SEO元标签然后提交并推送到gh-pages分支。” AI会处理格式转换、链接检查、提交和推送。如果这个过程在夜间进行就又创造了一个“幽灵日”。批量数据处理与报告处理大型数据集时我会启动一个AI子代理来运行清洗脚本、生成可视化图表并保存结果。这个任务可能运行数小时期间我可以完全离线。这些场景的共同点是任务目标明确、流程可预测、结果易于验证。我将它们“委托”出去换取自己时间的自由。5.2 协作模式的演变从助手到合作伙伴“0个‘仅你活跃日’”这个统计数字或许比“40个幽灵日”更值得玩味。它意味着在我的开发活动中没有AI参与的“纯手工”环节已经消失了。这标志着我与AI协作模式的根本性转变过去AI作为助手我写大部分代码AI负责补全、建议、解释。工作以“我”为主AI为辅。贡献日历上可能大部分是青色夹杂少量黄色。现在AI作为合作伙伴工作拆分为“决策与设计”我的交互时间和“执行与实现”AI的自主时间。我更多地扮演产品经理、架构师和评审者的角色而将编码、测试、文档、部署等执行层任务大规模委托。因此日历上黄色占据了主导。这种模式并非没有代价。它要求我更精确地定义任务更严格地设置验收条件并建立可靠的监控和回滚机制。但回报是显著的我可以同时推进多个项目将精力集中于更高价值的创造性工作并实现了某种程度的“数字分身”让项目在24小时内持续进展。5.3 工具带来的反思与优化可视化不仅仅是为了炫酷它驱动了行为改变和流程优化识别低效委托通过查看日历我发现某些“幽灵日”的AI工作时间异常长深黄色█。回溯日志发现是因为任务定义模糊导致AI在尝试不同方案或陷入循环。这促使我优化指令提供更明确的上下文和约束条件。平衡协作节奏如果连续多天都是“幽灵日”而没有“双方活跃日”可能意味着我过于“放手”失去了对项目细节的掌控。日历提醒我需要安排交互式会话来进行代码审查和方向校准。评估工具投资回报率高昂的AI使用成本是否物有所值cc-calendar提供的量化数据AI小时数是评估其产出价值的基础。我可以清晰地看到在AI重度工作的日子里产出了多少个npm版本、多少篇博客文章、多少行测试代码。6. 常见问题与实战排错指南在实际使用和分享cc-calendar的过程中我遇到并收集了一些典型问题。这里提供一个速查指南。6.1 安装与运行问题问题现象可能原因解决方案运行npx cc-calendar报错Command not found1. Node.js未安装或版本过低。2. npm全局缓存或网络问题。1. 运行node --version检查需 ≥18。使用nvm管理Node版本。2. 尝试npx --yes cc-calendarlatest强制使用最新版。运行后无输出或提示No session data found1. Claude Code未产生日志。2. 日志路径不匹配。3.cc-agent-load工具本身故障。1. 确认你正在使用Claude Code并有过会话。2. 检查默认日志路径~/.claude/projects/是否存在及有文件。3. 先单独运行npx cc-agent-load看是否有文本输出。日历显示乱码或颜色异常1. 终端不支持Unicode或ANSI颜色。2. 终端颜色主题导致对比度低。1. 在Mac/Linux下使用iTerm2, Terminal, 或Windows Terminal。确保终端编码为UTF-8。2. 尝试在命令前加FORCE_COLOR3 npx cc-calendar强制启用颜色。统计数字看起来不对小时数过低日志时间格式解析错误或过滤了某些会话类型。cc-agent-load默认可能只统计“编程”相关项目。查看其文档确认是否有--all-projects之类的参数来包含所有会话。6.2 数据与解读疑问疑问解释与建议“幽灵日”的AI工作时间是我电脑开机的时间吗不一定。sub时间特指Claude Code子代理进程活跃的时间。你的电脑可能开机但AI未运行或者AI在远程服务器上运行如果你配置了远程会话。它衡量的是AI任务的实际执行时长。为什么我交互了很长时间但main时间很少cc-agent-load可能将会话中的“空闲时间”长时间无操作排除在计算之外或者只计算了活跃的“编码”会话。这取决于其具体的会话切分和过滤算法。需要查阅cc-agent-load的计时逻辑。我能用这个工具分析其他AI编码工具吗cc-calendar目前紧密依赖Claude Code的日志格式和cc-agent-load的数据接口。要适配其他工具如Cursor、Windsurf需要编写对应的日志解析器并将其输出转换为cc-agent-load --json相同的格式。这是一个高级定制方向。这个工具安全吗会上传我的数据吗工具完全在本地运行通过npx下载的代码会在沙盒中执行不会将你的日志数据发送到任何远程服务器。你可以审查其源代码在npm包或GitHub仓库中来确认。6.3 高级排查与调试如果遇到复杂问题可以开启调试模式逐步定位检查原始数据首先确保源头数据正确。运行npx cc-agent-load --json data.json然后打开data.json文件检查是否有你预期日期的数据以及main和sub的值是否合理。手动模拟测试你可以创建一个简单的测试JSON文件来验证cc-calendar的渲染逻辑{“byDate”: {“2024-04-01”: {“main”: 2.5, “sub”: 0}, “2024-04-02”: {“main”: 1, “sub”: 5}}}将其保存为test.json然后通过管道传递给工具如果工具支持标准输入或修改工具代码临时读取此文件。审查源码逻辑由于是开源工具最直接的方式是克隆cc-calendar的GitHub仓库在本地运行并添加console.log语句查看内部的数据处理、矩阵构建和渲染逻辑在哪里与你的预期不符。实操心得最常被忽略的问题是终端环境。一些轻量级或旧的终端模拟器对ANSI颜色和Unicode字符的支持不完整。如果你在Windows的旧版CMD中运行几乎肯定会遇到显示问题。强烈推荐使用Windows Terminal、macOS Terminal或iTerm2、Linux下的Gnome Terminal等现代终端它们能提供最佳的可视化效果。7. 开源生态与扩展可能性cc-calendar并非一个孤立的工具它是我构建的cc-toolkit开源工具集中的一个可视化组件。这个工具集的目标是提供一套完整的“Claude Code运维与洞察”套件。7.1 相关工具链介绍cc-agent-load(数据基石)这是所有分析的基础。它负责解析原始的、杂乱的Claude Code项目日志进行会话分割、类型识别交互式 vs. 子代理、时长计算并输出结构化的聚合数据。没有它cc-calendar就无从谈起。cc-ghost-log(产出追溯)这是“幽灵日”概念的延伸。当你从日历上发现一个高亮的幽灵日时自然会问“那天AI到底做了什么”cc-ghost-log通过扫描Git仓库的提交历史并与AI会话日志时间戳关联可以列出在幽灵日期间由AI代理创建的所有Git提交让你对AI的产出一目了然。cc-session-stats(会话级洞察)与日历的“天级”视图互补这个工具提供“会话级”的统计数据例如平均会话时长、最常用指令TOP 10、子代理任务的成功率、不同项目的时间分布等。它帮助你优化与AI交互的微观技巧。cc-health-check(安全与配置检查)这是一个重要的辅助工具。当你高度依赖AI自主运行时一个错误配置可能导致意料之外的行为例如向错误的分支推送代码。cc-health-check会运行一系列诊断检查你的Claude Code环境、Git配置、API密钥权限等给出安全评分和修复建议。7.2 潜在的扩展方向现有的工具只是一个起点社区可以在此基础上构建更强大的洞察系统Web可视化仪表盘将cc-calendar的数据通过一个本地Web服务器渲染成真正的、可交互的SVG或Canvas图表。用户可以点击每个方块查看那天的详细会话列表和AI执行的具体命令。集成时间追踪工具将AI工作时间sub导出为csv或与Toggl、Clockify等时间追踪工具兼容的格式让你能把“AI工时”正式纳入项目管理和客户计费体系。自定义告警规则例如当“幽灵日”连续超过N天时发送通知“你是否太久没亲自看代码了”或者当AI单日工作时间超过某个阈值时提醒“有个任务可能卡住了需要检查”。多AI代理支持未来开发者可能同时使用Claude Code、Cursor、Devin等多种AI编码工具。可以开发一个统一的元数据层聚合来自不同工具的日志生成一个统一的“人机协作贡献日历”比较不同工具的使用模式和效率。开源的力量在于协作。我提供了这个可视化的“透镜”和基础工具集希望它能激发更多开发者审视并优化自己的人机协作模式并共同构建更丰富的生态系统。你的使用场景和需求可能就是下一个重要扩展功能的起点。