核心用法
codesession-cli 是一款面向 AI Agent 开发者的会话成本追踪工具，通过 cs 命令行实现全生命周期管理。核心工作流为：
1. 启动追踪：cs start "任务描述" --json --close-stale 创建会话，JSON 模式立即退出，会话保持激活状态
2. 记录 AI 调用：cs log-ai 自动计算成本（支持 17+ 内置模型），支持 --agent 标记多 Agent 归属
3. 状态监控：cs status --json 实时获取成本、token、时长等数据
4. 结束归档：cs end -n "完成备注" --json 自动扫描 Git 变更与提交记录
5. 可视化分析：cs dashboard 启动本地 Web 服务（默认 3737 端口），提供 KPI、成本趋势、模型对比、文件热点等维度分析
显著优点
- 结构化优先：所有命令支持
--json，专为 Agent 自动化设计，输出包含 schemaVersion 便于版本兼容 - 智能成本计算：内置 Anthropic、OpenAI、Google 等主流厂商定价表，token 输入自动换算费用，支持自定义模型定价
- 零侵入追踪：无需修改代码，通过 Git 根目录自动关联会话，支持并发多会话
- 多 Agent 支持：v1.9.1 新增
--agent标记，适合复杂工作流中的成本归因与 A/B 测试 - 本地数据主权：SQLite 存储于
~/.codesession/，无云端依赖
潜在缺点与局限
- 构建依赖重：需 Node.js 18+ 及原生编译工具（Python、C++ 工具链），Windows 环境配置繁琐
- 模型覆盖有限：仅 17 个内置模型，新模型需手动定价或硬编码成本
- 无实时协作：数据本地存储，团队共享需自行导出 CSV/JSON
- 预算告警弱：仅建议性提示（如 $5 阈值），无硬性拦截机制
- 仪表盘单用户：本地服务无认证，多用户场景存在数据泄露风险
适合人群
- 个人开发者与小型团队，需量化 AI 辅助编程的真实成本
- 多 Agent 系统架构师，需精细化成本归因与效能分析
- 预算敏感型项目，需控制单次会话支出上限
常规风险
- 隐私：会话元数据与代码文件路径本地存储，需确保
~/.codesession/目录权限控制 - 数据丢失：SQLite 单文件无备份机制，建议定期
cs export归档 - 版本兼容性：JSON schema 可能演进，生产环境应校验
schemaVersion字段 - 误用风险：
--close-stale强制清理可能意外终止有效会话，建议在确定性崩溃恢复场景使用