核心用法
codesession-cli（命令 cs）是一款面向 AI Agent 开发者的本地会话追踪工具。通过在任务起始执行 cs start、每次 LLM 调用后执行 cs log-ai、任务结束时执行 cs end，实现对单次会话的完整成本核算。工具自动关联 Git 变更与提交记录，生成结构化 JSON 输出供 Agent 解析，并可通过 cs dashboard 启动本地 Web 仪表盘进行可视化分析。
v2.0.0 版本新增 Alerts 告警面板、Insights 洞察页与「Start Fresh」数据重置功能，支持按日/总会话/单会话设置成本阈值，触发浏览器通知与音效告警。
显著优点
1. Agent 原生设计：--json 模式全命令支持，输出包含 schemaVersion 与标准化错误对象，便于程序化集成；--agent 字段支持多 Agent 系统的成本归因。
2. 自动成本计算：内置 Anthropic、OpenAI、Google 等 17+ 主流模型的定价表，按 token 自动换算费用，避免人工计算误差。
3. 无侵入式追踪：--json 模式下 cs start 立即退出，不驻留进程，通过 Git 元数据在 cs end 时回溯文件变更，适配容器化与短暂生命周期的 Agent 环境。
4. 可视化仪表盘：基于 SQLite 本地存储启动的 Web UI 提供 KPI 概览、模型级成本细分、文件热点热力图与活动日历，无需外部 SaaS。
5. 预算管控：支持多层预算阈值与 alarm 模式，可在成本失控前主动拦截。
潜在缺点与局限性
- 本地单用户架构：数据存储于
~/.codesession/sessions.db，无原生多用户协作或云端同步机制，团队共享需自行解决文件同步或数据库导出。 - Node.js 原生依赖：安装需 C/C++ 构建工具链（node-gyp 编译 SQLite），在部分精简容器（如 Alpine 最小镜像）中需额外安装
build-base。 - Git 强依赖：文件变更检测基于 Git 状态，对未初始化的仓库或非 Git 项目（如纯数据科学 notebook 目录）无法自动追踪文件维度。
- 模型定价滞后：内置价格表需随供应商调价手动更新，若使用
cs pricing set自定义后未及时维护，可能导致成本估算偏差。
适合人群
- 使用 Claude、GPT-4 等 API 构建多步骤 Agent 的开发者
- 需要向客户或管理层汇报 AI 项目实际 token 成本的技术负责人
- 在本地/私有环境运行、无法使用云端可观测性 SaaS 的企业团队
- 进行 A/B 测试或多 Agent 协作、需精细化成本归因的工程师
常规风险
| 风险项 | 说明 |
|--------|------|
| 数据持久化 | SQLite 文件损坏或误删会导致历史会话丢失，建议定期 `cs export --format json` 备份 |
| 预算绕过 | CLI 仅提供软告警，不强制阻断 API 调用，高成本模型误配仍可能超额 |
| 版本兼容性 | JSON schema 可能随 major 版本升级变更，长期自动化流程需校验 `schemaVersion` |
| 隐私合规 | 会话描述与代码文件路径存储于本地磁盘，共享设备需注意敏感信息泄露 |