【插件教程】AI Cost Monitor 插件使用说明

Ulanzi

一、插件介绍
AI Cost Monitor 是一款隐私优先的AI花费监控插件，通过开源项目 codeburn 直接从AI工具的本地会话文件中读取花费数据，无需任何API密钥，所有数据处理均在本地完成。
主要功能

功能	说明
总览监控	监控所有AI平台的总花费（Total）
Aider	监控Aider AI编程助手的花费
Antigravity	监控Antigravity AI的花费
Claude	监控Anthropic Claude的花费
Codex	监控OpenAI Codex的花费
Continue	监控Continue开源AI编程的花费
Copilot	监控GitHub Copilot的花费
Cursor	监控Cursor编辑器的花费
Gemini	监控Google Gemini的花费
Supermaven	监控Supermaven AI的花费
Windsurf	监控Windsurf编辑器的花费

核心特性

• 本地数据读取：通过codeburn从AI工具的本地会话文件中直接读取花费，无需任何API密钥，数据不上传云端。
• 消费限额进度条：可设置消费上限（美元），按键以进度条+颜色直观显示花费比例，支持四级颜色预警。
• 自动刷新：默认每15分钟自动刷新数据，按下按键可立即手动刷新，数据时效性高。
  

二、安装插件系统要求

项目	要求
操作系统	macOS 10.15 (Catalina) 或更高
Ulanzi Studio	3.0.11 或更高版本
Node.js	系统 Node.js 22 或更高版本

重要提示：插件需要系统安装Node.js 22+才能运行codeburn进行花费计算。插件会自动在系统路径中查找合适的Node.js版本。
前置条件：若系统未安装Node.js 22+，请先访问https://nodejs.org/下载LTS版本（推荐v22.x）。安装后，在终端执行node --version确认版本。

三、配置与使用
第一步：添加动作到按键

• 在Ulanzi Studio主编辑界面，找到右侧**「动作列表」**。
• 展开**「AI Cost」**分类。
• 将**「AI Cost Monitor」**动作拖拽到任意按键上。
• 按键会立即显示加载中状态（显示…和平台名称）。
  

第二步：选择AI平台

• 选中已配置的按键，右侧显示属性面板。
• 在**「平台」**下拉菜单中，选择你要监控的AI平台：
  
  • Total (all platforms) — 所有平台花费合计
  • Claude — Anthropic Claude花费
  • Cursor — Cursor编辑器花费
  • Gemini — Google Gemini花费
  • Copilot — GitHub Copilot花费
  • ...以及其他支持的平台
    
• 选择后配置自动保存，按键图标会立即更新。
  

第三步：选择时间范围

选项	说明	使用场景
Today	今天的花费	日常监控每日开支
Last 7 days	最近7天累计	周度花费回顾
This month	本月累计	月度预算管理
Last 30 days	最近30天累计	月度趋势分析
All time	全部历史花费	总投入评估

第四步：设置消费限额（可选）在属性面板中找到**「上限（美元，0 = 不限）」**输入框，输入你的消费预算（美元）。设为0则表示不限制（默认值）。
设置限额后的视觉效果：当设置了消费上限后，按键会从默认的纯色显示模式切换为进度条模式。
四级颜色预警机制：

花费比例	颜色	含义
0% ~ 59%	绿色 #3ecf6b	安全 — 预算消耗正常
60% ~ 84%	黄色 #e3b341	注意 — 已消耗超过六成
85% ~ 94%	橙色 #e8893c	警告 — 接近预算上限
95% ~ 100%	红色 #e3434c	危险 — 预算即将耗尽

第五步：日常使用

操作	效果
单击按键	立即刷新数据（按键先显示加载状态，然后更新为最新花费）
自动刷新	每15分钟自动刷新一次（无需操作）
查看时间	按键底部显示“5m ago”（5分钟前），每60秒自动更新
错误状态点击	按键显示⚠️警告时，点击会自动在浏览器打开设置指南

四、按键图标说明
4.1 正常显示模式（无消费限额）按键显示平台Logo、平台名称、时间范围、花费金额和数据获取时间。顶部为品牌色条纹，背景为深黑色(#1a1a1e)。
4.2 限额进度条模式（设置了消费上限）按键顶部显示进度条（绿/黄/橙/红），背景为深黑色加轨道色(#2c2c33)。花费金额显示为白色，其他元素与正常模式一致。
4.3 加载中状态按键顶部为品牌色条纹，中央显示灰色省略号(…)和平台名称，表示数据正在加载。
4.4 配置错误状态按键顶部为黄色警告条纹，中央显示黄色⚠️警告图标和“Setup”文字，下方显示“Click for guide”。出现此状态时，按下按键会在浏览器中打开设置指南页面。
4.5 无数据状态按键顶部为品牌色条纹，显示平台Logo和名称，但花费金额处显示灰色破折号(—)和“no data”文字。表示该平台在本地没有找到会话文件。
4.6 过期数据标记当数据获取出错但仍有之前缓存的旧数据时，按键右上角会显示黄色圆点标记，表示当前显示的是过期数据。

五、多按键配置示例
以下是一个推荐的多按键布局方案，将所有AI平台花费放在同一页面：

按键位置	平台	时间范围	限额（美元）	说明
第1键	Total	Today	20	今日总花费监控
第2键	Claude	Today	10	今日Claude花费
第3键	Cursor	Today	5	今日Cursor花费
第4键	Gemini	Today	5	今日Gemini花费
第5键	Copilot	Today	0	今日Copilot花费（不限）
第6键	Total	This month	200	本月总花费预算
第7键	Total	Last 30 days	0	近30天花费趋势
第8键	Total	All time	0	历史总投入

提示：所有按键共享同一时间范围的数据缓存，多个按键使用相同时间范围时不会重复运行codeburn，不会额外消耗系统资源。

六、常见问题排查

6.1 按键显示 Setup警告可能原因：系统未安装Node.js 22或更高版本；codeburn CLI文件缺失或损坏；codeburn执行超时（超过120秒）。
解决方法：在终端运行node --version确认版本≥22；若版本过低，前往https://nodejs.org/下载安装最新LTS版本；安装后重启Ulanzi Studio；点击按键会自动打开设置指南。
6.2 按键显示“—”和“no data”可能原因：所选AI平台在本地没有会话文件；尚未使用过该AI工具。
解决方法：确认你已在本地使用过该AI工具；尝试更换时间范围为“All time”查看是否有历史数据。
6.3 花费金额显示“<$0.01”说明：这是正常行为。当花费大于0但小于$0.005时，显示<$0.01，说明该平台有少量使用记录但花费极低。
6.4 数据长时间不更新可能原因：codeburn执行异常但未报错；定时器未正常启动。
解决方法：按下按键手动触发刷新；观察按键是否先显示加载状态再更新数据；若手动刷新无反应，尝试重启Ulanzi Studio。
6.5 按键上显示黄色圆点说明：这表示当前显示的是过期数据（Stale Data）。触发原因是最近一次codeburn执行失败，但之前成功获取的数据仍然缓存可用。按下按键可尝试手动刷新，若成功则圆点消失。
6.6 切换时间范围后加载很慢说明：这是正常行为。时间范围越长（如“All time”），codeburn需要扫描的会话文件越多，首次加载可能需要数十秒。后续刷新会利用缓存，速度会显著提升。
6.7 如何同时监控多个平台？方法：为每个平台分别创建按键。将AI Cost Monitor动作多次拖拽到不同按键上，为每个按键在属性面板中选择不同的平台。所有按键可以共享同一时间范围。

七、隐私与安全

AI Cost Monitor插件高度重视你的隐私，所有数据处理均在本地完成：

方面	说明
数据来源	花费数据通过codeburn从AI工具的本地会话文件中读取
网络传输	插件本身不进行任何网络请求，不上传任何数据
API密钥	无需任何API密钥，不访问任何在线API
数据存储	数据仅在内存中缓存，不写入磁盘文件
开源依赖	花费计算引擎codeburn为MIT开源项目，可审计

隐私承诺：你的AI工具使用记录和花费数据永远不会离开你的电脑。

八、获取更多帮助

• 设置指南：按键显示⚠️警告时，点击按键自动打开
• GitHub仓库：https://github.com/narlei/ulanzideck-ai-cost
• codeburn项目：花费计算引擎（MIT开源）
• 问题反馈：在插件GitHub仓库中提交Issue