CostHQ

核心用法

costhq 是一款面向 AI Agent 工作流的会话成本追踪工具，通过本地 SQLite 数据库存储数据，提供完整的成本透明化方案。核心工作流遵循三步：

1. 启动会话：cs start "任务描述" --json --close-stale 创建追踪会话
2. 记录 AI 调用：每次 API 调用后执行 cs log-ai -p <provider> -m <model> --prompt-tokens <n> --completion-tokens <n> --json，支持 Anthropic、OpenAI、Google 等 17+ 内置模型自动计价
3. 结束会话：cs end -n "完成备注" --json 自动生成 Git 变更统计与成本汇总

工具提供 Web 仪表盘（cs dashboard），涵盖 KPI 概览、模型成本分析、文件热点图、多 Agent 成本归因等高级功能。支持 --agent 标签实现多 Agent 系统成本拆分，适合复杂 AI 流水线。

显著优点

• Agent 原生设计：所有命令支持 --json 结构化输出，专为程序化 Agent 交互优化
• 零外部依赖：数据本地存储（~/.CostHQ/sessions.db），无需云服务
• 精细成本追踪：内置 17+ 模型定价表，支持自动计算与自定义覆盖
• Git 深度集成：自动检测会话期间的文件变更与提交记录
• 预算管控：支持日/总会话/单会话三级预算阈值与告警
• 多 Agent 支持：--agent 标签实现成本归因，便于 A/B 测试与团队分摊

潜在局限

• 构建依赖：需 Node.js 18+ 及 C/C++ 工具链编译 SQLite 原生模块，Windows 环境配置较复杂
• 仅支持 Git 项目：会话作用域绑定 Git 根目录，非 Git 目录无法正常使用
• 本地单用户：无多用户协作或云端同步能力
• 仪表盘端口固定：默认 3737，冲突时需手动指定
• Pro 功能描述模糊："unlocked Pro architecture" 具体能力边界未明确

适合人群

• 高频使用 AI API（Claude、GPT-4o 等）的开发者与团队
• 需要精细化成本归因的多 Agent AI 系统架构师
• 追求数据主权、拒绝云服务的隐私敏感用户
• 需向客户/管理层汇报 AI 支出的咨询公司或企业技术负责人

常规风险

• 数据丢失风险：本地 SQLite 无自动备份，误删 ~/.CostHQ/ 即丢失历史
• 会话泄露：--close-stale 参数使用不当可能导致异常会话残留
• 定价漂移：内置模型价格非实时同步，供应商调价后需手动更新
• JSON 模式陷阱：--json 模式下进程立即退出，开发者易误以为会话未创建
• 版本兼容性：schemaVersion 字段提示存在破坏性变更可能，需关注升级

核心用法

costhq 是一款专为AI编程代理设计的会话成本追踪工具，通过CLI命令实现全生命周期管理：

1. 会话启动：cs start "任务描述" --json --close-stale 创建追踪会话，自动清理崩溃遗留的活跃会话
2. 成本记录：cs log-ai 支持17+内置模型（Anthropic/OpenAI/Google等）的自动计费，也可手动指定成本；新增 --agent 参数实现多代理系统的成本归因
3. 实时监控：cs status --json 返回结构化数据，包含当前成本、token用量、文件变更数
4. 会话收尾：cs end -n "完成备注" --json 自动扫描git变更与提交记录
5. 可视化分析：cs dashboard 启动本地Web服务（默认3737端口），提供KPI概览、成本趋势、模型对比、文件热点等多维度分析

显著优点

• 代理原生设计：所有命令支持 --json 结构化输出，专为自动化工作流优化
• 精细化成本归因：多代理场景下可通过 --agent "Agent Name" 区分不同代理的成本贡献
• 智能预算管控：支持日限额/总会话限额/单会话限额三级告警，超标时触发声音+浏览器通知
• 零外部数据泄露：数据本地存储于 ~/.CostHQ/sessions.db，符合GDPR数据最小化原则
• Pro功能全解锁：v3.0.3版本已解锁全部高级功能，含控制台UI与完整仪表板

潜在局限与风险

| 维度 | 说明 |

|------|------|

| **来源可信度** | 作者brian-mwirigi为个人开发者（T3级），无知名组织背书 |

| **外部依赖** | 需全局安装npm包 `costhq`，该包未在本次扫描范围内，存在供应链风险 |

| **构建复杂度** | 依赖C/C++工具链编译嵌入式SQLite，Windows/macOS/Linux均需额外安装构建工具 |

| **数据安全** | 本地SQLite无加密，共享环境或设备丢失可能导致会话元数据泄露 |

| **误操作风险** | 仪表板"Start Fresh"功能可一键清空所有记录，无二次确认机制 |

| **版本兼容** | JSON响应包含 `schemaVersion` 字段，需代理端实现版本兼容性检查 |

适合人群

• 多步骤AI开发任务：需要追踪长周期会话成本的开发者
• 多代理系统架构师：需要按代理维度拆分成本的团队
• 预算敏感场景：企业/个人开发者需要硬预算上限控制
• 成本优化分析：需要可视化报表识别高频消费模型与文件热点

常规风险提示

1. 安装前建议通过 npm view costhq 和 npm pack 审查包源代码
2. 优先使用 nvm 隔离环境，避免全局安装带来的权限风险
3. 敏感项目建议定期 cs export 备份，防范误重置或数据丢失
4. 关注 schemaVersion 变化，及时适配JSON结构变更