会话成本追踪 (codesession-cli)

追踪智能体会话成本、文件变更和 git 提交。强制执行预算限制，并通过完整的网络仪表板提供详细的会话分析。

最新版本：v2.5.1-cs run <命令>将所有步骤封装在一个命令中（会话 + 代理 + 运行 + 成本摘要）。cs today用于多项目上下文。仪表板帮助标签、Codex定价、安全修复。

📦npm• ⭐GitHub• 📝更新日志

安装

# 1. Install the CLI globally from npm
npm install -g codesession-cli

# 2. Install the OpenClaw skill
clawhub install codesession

安装后，cs命令将在全局范围内可用。OpenClaw 智能体将自动使用它来追踪会话。

要求：Node.js 18+ 和 C/C++ 构建工具（用于编译内嵌的 SQLite 模块）。

操作系统	安装构建工具
Ubuntu/Debian	sudo apt-get install -y build-essential python3
macOS	xcode-select --install
Windows	npm install -g windows-build-tools或者安装 Visual Studio Build Tools
Alpine	apk add build-base python3

数据本地存储于~/.codesession/sessions.db。

使用时机

• 始终在多步骤任务开始时启动跟踪会话
• 始终在每次进行API调用后记录AI使用情况
• 始终任务完成时结束会话
• 在执行高成本操作前检查预算
• 使用cs dashboard在浏览器中查看会话数据

命令

开始跟踪

# Agent mode (always use --json for structured output):
cs start "task description" --json --close-stale

# Resume if a session was left open (e.g. after a crash):
cs start "task description" --json --resume

# Human/interactive mode (stays running with live file watcher):
cs start "task description"

代理模式与交互模式对比：使用--json参数时，会在数据库中创建会话，打印JSON数据，然后进程立即退出——会话保持“活动”状态，并在您运行cs end时跟踪git变更。不使用--json参数时，进程将持续运行，并启用实时文件监视器和git提交轮询器，直到您按下Ctrl+C或在另一个终端中运行cs end。

记录AI使用情况（每次API调用后）

# With granular tokens (cost auto-calculated from built-in pricing):
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json

# With agent name tracking (NEW in v1.9.1):
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent "Code Review Bot" --json

# With manual cost:
cs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json

# With all fields:
cs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent "Research Agent" --json

提供商：anthropic、openai、google、mistral、deepseek费用根据可配置的定价表自动计算（包含21种以上内置模型，包括Codex）。使用cs pricing list --json查看已知模型。如果模型未知，请手动提供-c <成本>。

代理名称（可选）：使用--agent "代理名称"来追踪哪个代理执行了工作。非常适合多代理系统、A/B测试和成本归因。代理名称会显示在仪表板中，可用于按代理筛选/分析成本。

检查当前状态

cs status --json

返回包含当前会话成本、令牌数、更改的文件、持续时间的JSON。所有JSON响应都包含schemaVersion和codesessionVersion字段。

结束会话并获取摘要

cs end -n "completion notes" --json

结束时，codesession会自动扫描git，查找自会话开始以来所有更改的文件和提交的记录——即使使用了--json使用了模式（无需实时监控）。

Web 仪表板

cs dashboard
# Opens http://localhost:3737 with full analytics UI

cs dashboard --port 4000       # custom port
cs dashboard --no-open         # don't auto-open browser

仪表板显示：

• 概览— 关键绩效指标、每日成本/令牌趋势、支出预测、成本变化率
• 会话— 可搜索/排序的表格，包含时间线、文件、提交、AI调用、笔记的每会话详情
• 模型— 按模型和提供商划分的成本明细、令牌比例、使用量图表
• 洞察— 文件热点、活动热力图、项目分解、定价表
• 警报— 设置每日/总计/每会话成本阈值，并启用警报模式（声音 + 浏览器通知）
• 重新开始— 从侧边栏重置所有会话数据

查看会话详情

cs show --json --files --commits

查看历史统计

cs stats --json

导出会话

cs export --format json --limit 10
cs export --format csv

添加笔记 / 批注

cs note "Starting refactor phase"
cs note "Tests passing, moving to cleanup"

带时间戳的批注出现在cs show --json在注释.

恢复过期会话

cs recover --max-age 12

自动结束任何超过12小时的活跃会话。

代理工作流程

代理应始终使用--json参数执行每条命令，以获得结构化、可解析的输出。

1. 任务开始时：cs start "修复认证错误" --json --close-stale
2. 添加上下文说明：cs note "分析认证流程" --json
3. 每次AI调用后：cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent "错误修复器" --json
4. 检查花费：cs status --json-- 读取aiCost字段
5. 任务结束时：cs end -n "修复了认证错误，添加了测试" --json
6. 回顾过往会话：cs dashboard

提示：使用--agent标志来标识您代理的工作，这在多代理系统中尤其有用，不同的代理处理不同的任务（例如："代码审查机器人"、"测试编写器"、"文档代理"）。

定价

定价是可配置的。运行cs pricing list以查看所有已知模型的价格。覆盖或添加模型：

# Plain model key
cs pricing set my-model 5.00 15.00

# Provider-namespaced key (avoids collisions)
cs pricing set gpt-4o 2.50 10.00 --provider openai

如果模型不在定价表中，您必须在记录时提供-c <成本>。

代理模式 & cs run (v2.5.0)

跟踪任何代理运行的最快方式：

cs run python my_agent.py
# or: cs run --name "fix auth" node agent.js

这会启动一个会话，启动代理，运行您的命令，然后结束会话并打印成本摘要。无需额外的终端，也无需导出环境变量。

如果您更喜欢手动控制，可以在一个终端中启动代理并设置环境变量：

cs proxy --session "my task"   # auto-starts a session too
# then in your agent shell:
export ANTHROPIC_BASE_URL=http://127.0.0.1:3739
export OPENAI_BASE_URL=http://127.0.0.1:3739/v1

代理绑定到127.0.0.1仅此而已。它从不存储提示文本或API密钥——只有令牌计数会被写入会话。

预算意识

如果用户设置了预算，或者您检测到高额支出：

• 检查cs status --json在执行高成本操作之前
• 如果aiCost在单次会话中超过$5.00，则警告用户
• 如果成本持续上升，建议使用更便宜的模型

重要提示

• 使用--close-stale在cs start时，以避免因先前崩溃导致的“session_active”错误
• 如果cs未安装，则跳过会话跟踪——不要阻碍用户的任务
• 始终使用--json对于每条命令——代理必须使用结构化输出
• 使用--json,cs start创建会话并退出（无需长期运行的进程）
• 会话的作用域由git 根目录决定——从子目录运行仍会匹配仓库级别的会话
• 在--json模式下出现错误时，退出代码始终为1且响应包含{ "error": { "code": "...", "message": "..." } }
• 检查schemaVersion在 JSON 响应中，以检测重大变更

更新检查

定期检查 CLI 是否为最新版本（例如在会话开始时或每天一次）：

# Compare installed version to latest on npm:
cs --version          # installed version
npm view codesession-cli version  # latest on npm

如果安装的版本落后，则通知用户：

"codesession-cli 有可用更新：v1.9.4 -> v2.0.0。请运行npm install -g codesession-cli以进行更新。"

不要因更新而阻塞工作流程——只需通知并继续执行。

JSON 输出

所有命令均支持--json选项，以提供机器可读的输出格式。当您需要以编程方式解析会话数据时，请使用此选项。