1. 项目概述一个专为Claude用户打造的年度数据可视化与分享工具又到年底了对于深度使用AI工具的朋友们来说回顾过去一年的使用数据总是件有趣的事。你可能会好奇自己在Claude上到底花了多少“脑细胞”或者说Token是哪个模型用得最多每个月的使用量有什么波动更重要的是如何把这些数据以一种酷炫、直观的方式分享到社交平台和朋友们一起交流讨论这就是我今天要聊的ClaudeTokenShare项目。它本质上是一个基于Next.js构建的Web应用核心功能就是帮你从Anthropic的官方API里安全地拉取你2025年全年的Claude使用数据然后通过一个设计精美的仪表盘展示出来最后还能一键生成图文并茂的总结直接分享到X原Twitter上。整个流程从授权、获取数据到发布完全在浏览器端完成你的API密钥不会被服务器留存设计上考虑到了隐私和安全。我自己作为一个从Claude 2时代就开始重度使用的开发者一直想有个工具能把我散落在各次对话中的Token消耗汇总起来看看自己的“AI算力投资”到底用在了哪里。市面上的年度总结工具不少但专门针对Claude、并且深度集成社交分享的这还是头一个。它特别适合那些经常用Claude进行编程、写作、头脑风暴的创作者、开发者和产品经理不仅能满足数据复盘的好奇心还能生成一张足够有“晒点”的年度总结卡片。2. 核心功能与设计思路拆解2.1 解决的核心痛点从数据孤岛到可视化社交资产在接触这个项目之前想要统计Claude的年度Token使用情况基本只有两条路一是手动翻阅Anthropic控制台那并不直观的账单页面自己用Excel做表二是尝试调用Anthropic的API然后写脚本处理JSON数据并生成图表。这两条路对普通用户来说门槛都不低更别提生成一个适合社交传播的视觉化总结了。ClaudeTokenShare的设计思路非常清晰就是打通“数据获取 - 可视化 - 社交分享”这个完整链路把原本专业、繁琐的操作变成三次点击就能完成的事情。它的核心价值在于降低技术门槛用户无需了解Anthropic API的调用细节、分页逻辑或数据聚合方法。只需一个Admin API Key剩下的交给应用。提升数据可读性将原始的、冰冷的JSON数据转化为带有色彩区分、趋势折线、占比饼图的交互式仪表盘一眼就能看懂全貌。创造分享动机通过预设精美的分享模板和与X平台的无缝集成将个人数据转化为可传播的社交内容满足了用户的展示与交流需求。这个设计背后反映了一个趋势AI工具的使用正从纯粹的“生产力消耗”转变为一种值得记录和分享的“数字生活体验”。你的Token使用画像某种程度上也反映了你的工作重点、学习领域甚至创作风格。2.2 技术栈选型背后的考量项目选用了Next.js 16 TypeScript Tailwind CSS这套当前前端领域非常主流且高效的组合这不是偶然。Next.js 16 (App Router)这是关键选择。项目需要处理敏感的API密钥Claude Admin Key和OAuth流程X登录。Next.js的App Router提供了完善的Server Component和Server Action支持意味着所有涉及密钥和第三方认证的逻辑都可以、且必须运行在服务器端。这从根本上杜绝了API密钥泄露到客户端浏览器的风险。同时Next.js内置的API路由简化了后端接口的开发让整个应用可以保持在一个项目内部署和维护更简单。TypeScript对于需要与多个外部APIAnthropic API, X API打交道的项目类型安全至关重要。TypeScript能在编码阶段就发现接口字段不匹配、参数类型错误等问题极大地提升了开发效率和代码可靠性尤其是在处理复杂的嵌套JSON响应时。Tailwind CSS项目需要快速构建一个美观、响应式的仪表盘界面。Tailwind的实用类Utility-First范式非常适合这种场景开发者可以高效地实现设计稿并且保持样式的一致性。从截图看其生成的图表和卡片组件在视觉上非常专业。Docker提供Docker Compose配置是为了实现“开箱即用”。对于想自行部署的用户比如想在内部团队分享Docker化封装了Node环境、依赖安装和构建过程用户只需要配置好.env文件一条docker-compose up命令就能获得一个完整可运行的环境极大降低了部署复杂度。这套技术栈的选择体现了开发者对全栈开发效率、应用安全性和用户体验三者的平衡。3. 核心模块解析与实操要点3.1 安全第一双令牌流与无状态设计这是整个项目架构中最值得称道的部分。它巧妙地设计了两条独立的、安全的令牌Token流分别处理Claude数据获取和X账号授权。1. Claude API密钥的“阅后即焚”模式用户在前端页面输入自己的Claude Admin API Key形如sk-ant-admin-...。这个密钥不会被发送到项目自己的数据库进行存储。通常的流程是前端通过安全的HTTPS POST请求将密钥发送到Next.js的一个Server Action或API路由。服务器端接收到密钥后立即用它向Anthropic的API发起请求获取该用户的用量数据。数据获取成功后服务器将用量数据返回给前端进行展示而Claude API Key在这个短暂的服务器内存中存在后即被丢弃。会话Session中只保存获取到的用量结果绝不保存密钥本身。实操心得在自行实现类似功能时务必确保API密钥只存在于服务器端的内存或短暂的环境变量中绝不写入日志、数据库或任何持久化存储。Next.js的Server Action是实现此模式的理想场所。2. X账号的OAuth 2.0授权流这是标准的、安全的第三方授权方式。项目使用twitter-api-v2这个优秀的库来简化流程。前端触发用户点击“Connect with X”前端引导用户跳转到X的官方授权页面。用户授权用户在X的页面上输入账号密码并授权给此应用。回调与令牌交换授权成功后X会将用户重定向回本项目指定的回调地址如/api/auth/x/callback并附带一个临时的code。服务器端用这个code加上预先配置的X_CLIENT_SECRET去X服务器交换得到长期的access_token和refresh_token。安全存储获取到的access_token会被加密后存储在HTTP-Only、Secure的Cookie中通过iron-session库管理。这意味着令牌对客户端的JavaScript不可见能有效防御XSS攻击。当用户点击“分享到X”时服务器端从Cookie中解密出令牌并用它来代表用户发帖。这种“前端无密钥后端不存密”的设计最大程度地保护了用户两大核心平台AI服务和社交平台的账户安全。3.2 数据获取与聚合逻辑项目聚焦于“2025年度回顾”这意味着它需要从Anthropic API中筛选出特定时间范围的数据。Anthropic的用量API通常会返回按时间排序的详细记录。核心步骤推测构造请求使用Claude Admin API Key向Anthropic的用量端点例如/v1/usage发起请求。请求参数中需要指定时间范围start_date2025-01-01和end_date2025-12-31。由于数据量可能很大需要处理分页limit和after参数。数据聚合API返回的可能是每条消息或每个会话的Token消耗记录。服务器端需要对这些记录进行聚合计算按模型聚合累加claude-3-5-sonnet-20241022、claude-3-opus-20240229等不同模型的输入Token、输出Token总数。按时间聚合按月份分组计算每个月的总Token消耗用于生成月度趋势图。总计计算算出2025年全年的总输入、输出及合计Token数。前端展示将聚合后的结构化数据传递给前端组件由图表库从截图看可能是Recharts或类似库渲染出饼图、柱状图、折线图等。注意事项Anthropic的用量API可能有速率限制。在实现时要做好错误重试和友好提示。对于使用量极大的用户一次性拉取全年数据可能超时可以考虑分批次请求或提供“仅统计最近半年”的选项。3.3 社交分享的定制化与实现分享功能是项目的画龙点睛之笔。它不仅仅是调用X的API发一段文字。模板系统项目提供了多种预设的推文模板从截图“Choose a template”可知。例如“作为一名开发者2025年我在Claude上消耗了{X}个Token其中{Y}%用于代码生成”这类模板让不擅长文案的用户也能快速生成有趣的分享内容。用户也可以完全自定义文本。图文生成分享的关键在于那张信息图。前端图表组件在用户点击“分享”时很可能通过html2canvas或vercel/ogOpen Graph这类库将当前的仪表盘视图或一个特制的总结视图渲染成一张PNG图片。媒体上传与发帖服务器端在收到发帖请求后执行以下操作将生成的图片数据转换为二进制流。调用X API的media/upload端点上传图片获得一个media_id。调用tweets端点创建推文参数中除了text用户定制的文案还会带上media.media_ids从而发布一条带图的推文。这个流程实现了真正的“一键分享”用户体验非常流畅。4. 从零开始部署与配置实战如果你想在自己的服务器上部署一个实例或者想深入了解其运行机制以下是详细的步骤和避坑指南。4.1 环境准备与依赖安装方案一使用Docker部署推荐最省心这是项目作者首推的方式能完美复现开发环境。# 1. 克隆项目代码 git clone https://github.com/jleboube/Claude-Token-EOY-Review.git cd Claude-Token-EOY-Review # 2. 复制环境变量模板文件 cp .env.example .env此时你的项目根目录下会有一个.env文件。接下来是配置的关键。方案二本地开发环境运行如果你打算进行二次开发建议在本地运行。# 1. 克隆项目后安装Node.js依赖 npm install # 或使用 yarn/pnpm # 2. 同样复制并配置.env文件 cp .env.example .env # 3. 启动开发服务器 npm run dev应用将在http://localhost:3000启动。开发模式下文件更改会热重载。4.2 核心环境变量配置详解.env文件的配置是整个项目能否运行的核心。你需要准备以下几组密钥1. X OAuth 凭证 (X_CLIENT_ID,X_CLIENT_SECRET)这是为了让你的应用实例能独立使用“用X账号登录”功能。如果你只是本地测试且不需要“分享到X”功能可以暂时跳过。但若需要完整功能必须申请。步骤访问 developer.x.com 使用你的X账号登录。进入“Developer Portal”创建一个新项目Project和一个关联的应用App。在应用的设置页面找到“User authentication settings”点击“Set up”。按下表配置配置项填写值说明App permissionsRead and write因为需要发帖所以需要写权限。Type of AppWeb App, Automated App or Bot选择此类型。Callback URL / Redirect URIhttp://localhost:3000/api/auth/x/callback本地开发环境地址。如果是线上部署则改为https://你的域名/api/auth/x/callback。Website URLhttp://localhost:3000你的应用主页地址。保存后回到应用主页的“Keys and tokens”标签页。在“OAuth 2.0 Client ID and Client Secret”部分你会看到Client ID和Client Secret。将它们分别填入.env文件的X_CLIENT_ID和X_CLIENT_SECRET。2. 会话加密密钥 (SESSION_SECRET)用于加密存储在用户浏览器Cookie中的会话信息如X的access_token。必须是一个长且随机的字符串。生成命令在终端执行openssl rand -base64 32将输出的一长串随机字符作为SESSION_SECRET的值。3. 应用公开URL (NEXT_PUBLIC_APP_URL)告知应用自身的公开访问地址用于构建正确的OAuth回调地址等。本地开发设置为http://localhost:3000生产环境设置为https://你的真实域名.com最终你的.env文件应类似如下# .env 文件示例 X_CLIENT_ID你的_client_id_字符串 X_CLIENT_SECRET你的_client_secret_字符串 SESSION_SECRET由openssl生成的32位随机base64字符串 NEXT_PUBLIC_APP_URLhttp://localhost:30004.3 构建与运行Docker方式# 在项目根目录执行以下命令构建并启动容器 docker-compose up --build # 如果是最新的docker版本命令可能是 docker compose up --build首次运行会花费一些时间下载镜像和构建。成功后控制台会输出应用运行的端口根据docker-compose.yml可能是47391。在浏览器访问http://localhost:47391即可。本地运行方式配置好.env后直接运行npm run dev访问http://localhost:3000。4.4 首次使用流程演示假设你已经成功部署并打开了应用。连接X账号点击首页的“Connect with X”按钮。页面会跳转到X的官方授权页询问你是否授权给此应用。点击“授权”。成功后你会被带回应用界面会显示你的X头像和用户名表示连接成功。避坑提示如果这一步失败99%的原因是.env中的NEXT_PUBLIC_APP_URL或X开发者后台的Callback URL配置错误两者必须完全一致包括http和https。输入Claude密钥在输入框内粘贴你的Claude Admin API Key。这个密钥可以在 Anthropic控制台 的Settings - API Keys部分找到。注意必须是Admin Key以sk-ant-admin-开头普通API Key可能没有权限调用用量接口。安全提醒再次强调这个页面是安全的。密钥被直接发送到你的应用服务器进行处理不会在别处存储。你可以通过浏览器的开发者工具“网络Network”标签查看确认请求是发送到你自己的服务器地址。查看数据仪表盘点击提交后应用会开始获取数据。稍等片刻一个完整的年度数据仪表盘就会呈现出来。你可以看到总Token数、各模型使用占比的饼图、月度消耗趋势的折线图等。可以花点时间探索一下这些数据看看哪个模型是你的“主力”。生成并分享在仪表盘下方找到分享区域。选择一个喜欢的模板或者自己编辑推文内容。点击“Preview”可以预览分享卡片的效果。确认无误后点击“Post to X”。如果一切顺利几秒后你就可以在自己的X时间线上看到这条带图的年度总结推文了。5. 常见问题与故障排查实录在实际部署和使用过程中你可能会遇到一些问题。以下是我在测试中遇到的情况及解决方法。5.1 OAuth授权失败问题问题现象点击“Connect with X”后跳转到X页面提示“Invalid redirect_URI”或“Client authentication failed”。排查步骤1检查Callback URL一致性这是最常见的问题。请像对待程序代码一样逐字符核对以下两处是否完全一致X开发者后台你应用的“Callback URI / Redirect URI”字段。你.env文件中NEXT_PUBLIC_APP_URL变量值加上固定的后缀/api/auth/x/callback。本地开发应为http://localhost:3000/api/auth/x/callback(注意是http不是https)。生产环境应为https://yourdomain.com/api/auth/x/callback。常见错误多了或少了斜杠/http和https混用域名后面带了端口号而另一边没带。排查步骤2检查应用权限和类型确保在X后台的“User authentication settings”中“App permissions”至少设置为“Read and write”“Type of App”选择了“Web App, Automated App or Bot”。如果之前是“Read only”需要重新生成Client Secret。排查步骤3重置Client Secret如果怀疑密钥泄露或配置混乱可以在X后台“Keys and tokens”页面找到“Regenerate”按钮重新生成Client Secret。注意重新生成后旧的Secret立即失效必须同步更新.env文件中的X_CLIENT_SECRET值。5.2 Claude API密钥无效或无权访问问题现象输入Claude API Key后页面长时间加载然后报错或提示“Failed to fetch usage data”。原因1使用了错误的Key类型确保你使用的是Admin API Key(以sk-ant-admin-开头)而不是普通的sk-ant-开头的Key。普通Key通常没有调用组织级用量API的权限。解决登录Anthropic控制台在“Settings” - “API Keys”中创建或复制一个Admin Key。原因2Key已过期或额度用完检查Anthropic账户的额度和Key的有效期。解决在Anthropic控制台查看Key状态或更换一个新的有效Key。原因3网络问题或API服务暂时不可用你的服务器可能无法访问Anthropic的API端点api.anthropic.com。解决在服务器上尝试用curl命令测试连通性curl -v https://api.anthropic.com。如果是国内服务器需要考虑网络环境问题。5.3 分享到X时发帖失败问题现象点击“Post to X”后提示分享失败。排查步骤1检查OAuth权限发帖需要“Read and write”权限。如果当初授权时只申请了“Read”权限则无法发帖。解决需要用户在你的应用中断开X连接同时你需要在X开发者后台将应用权限更新为“Read and write”。然后让用户重新授权。对于已授权的用户他们可能需要先在X账号的“设置和隐私”-“安全和账号访问”-“应用和会话”中撤销你应用的访问权限然后重新连接。排查步骤2检查推文内容格式X API对推文有字符数限制目前是280字符并且可能对某些字符或链接有特殊处理。解决在自定义推文时不要超过长度限制。可以尝试先用一个简单的纯文本如“Test”测试发帖功能是否正常以排除内容本身的问题。排查步骤3图片上传失败分享功能需要上传生成的图片。图片可能过大或格式不被支持。解决检查前端生成图片的代码确保图片尺寸和文件大小在合理范围内例如不超过5MB。可以尝试在服务器端日志中查找来自X API的错误响应。5.4 Docker容器运行异常问题现象docker-compose up后容器不断重启或退出日志显示端口冲突或依赖错误。原因1端口被占用默认的47391端口可能已被其他程序占用。解决修改项目根目录下的docker-compose.yml文件将ports映射中的主机端口如47391:3000改为其他空闲端口例如8080:3000。原因2.env文件未正确挂载或读取Docker容器内找不到.env文件导致启动时关键环境变量缺失。解决确保docker-compose.yml中有关env_file或.env的配置正确。通常项目配置会使用env_file: .env。检查.env文件是否存在于项目根目录并且Docker有权限读取。原因3Node版本或依赖构建失败可能在构建镜像时npm install或npm run build阶段出错。解决查看Docker构建日志 (docker-compose up --build的输出)寻找具体的错误信息如某个npm包安装失败。可能是网络问题可以尝试更换npm源或重试。5.5 数据展示不完整或图表错误问题现象仪表盘上的图表显示异常比如饼图比例不对或月度数据缺失。原因1Anthropic API返回的数据格式有变化API的响应结构可能随版本更新而改变导致前端数据解析失败。解决打开浏览器的开发者工具F12进入“网络Network”标签查看获取用量数据的那个API请求的响应。对比实际返回的JSON结构与前端代码中预期的结构是否一致。这可能需要开发者调整数据聚合的逻辑代码。原因2时区处理问题如果服务器和用户处于不同时区在按“月份”聚合数据时可能会出现偏差例如将某个月最后一天的数据归到了下个月。解决在服务器端处理日期时应统一使用UTC时间或明确指定时区进行日期截断如使用dayjs或date-fns库确保数据分组准确。这个项目提供了一个非常棒的思路和实现范本将个人AI使用数据变得可感知、可分享。它的安全设计值得借鉴尤其是处理敏感API密钥的方式。如果你是一个Claude的重度用户不妨部署来玩一玩看看你的2025年AI足迹。对于开发者而言它的代码结构也是学习Next.js全栈开发、OAuth集成和第三方API调用的优秀案例。我在部署过程中最大的体会是细节决定成败尤其是.env配置和OAuth回调地址必须像对待密码一样仔细核对。