Codesession

# Session Cost Tracking (codesession-cli)

跟踪代理会话成本、文件更改和 git 提交。强制执行预算限制，并通过完整的 Web 仪表板提供详细的会话分析。

**最新版本：v2.0.0** - 警报仪表板、重新开始、洞察页面、警报模式。

📦 [npm](https://www.npmjs.com/package/codesession-cli) • ⭐ [GitHub](https://github.com/brian-mwirigi/codesession-cli) • 📝 [Changelog](https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md)

## 安装

```bash # 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` 在浏览器中查看会话数据

## 命令

### 开始跟踪 ```bash # 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 调用后） ```bash # 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` 成本根据可配置的定价表（17+ 个内置模型）自动计算。使用 `cs pricing list --json` 查看已知模型。如果模型未知，请手动提供 `-c <cost>`。

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

### 检查当前状态 ```bash cs status --json ``` 返回包含当前会话成本、Token、已更改文件、持续时间的 JSON。所有 JSON 响应都包含 `schemaVersion` 和 `codesessionVersion` 字段。

### 结束会话并获取摘要 ```bash cs end -n "completion notes" --json ``` 结束时，codesession 会自动扫描 git 以查找自会话开始以来所有已更改的文件和提交——即使使用了 `--json` 模式（也不需要实时监视器）。

### Web 仪表板 ```bash 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 ```

仪表板显示： - **概览** — KPI、每日成本/Token 趋势、支出预测、成本速率 - **会话** — 可搜索/可排序的表格，包含时间线、文件、提交、AI 调用、笔记的每会话详情 - **模型** — 每个模型和每个提供商的成本细分、Token 比率、使用情况图表 - **洞察** — 文件热点、活动热力图、项目细分、定价表 - **警报** — 设置每日/总计/每次会话成本阈值，并带有警报模式（声音 + 浏览器通知） - **重新开始** — 从侧边栏重置所有会话数据

### 查看会话详情 ```bash cs show --json --files --commits ```

### 查看历史统计 ```bash cs stats --json ```

### 导出会话 ```bash cs export --format json --limit 10 cs export --format csv ```

### 添加笔记/注释 ```bash cs note "Starting refactor phase" cs note "Tests passing, moving to cleanup" ``` 带时间戳的注释会出现在 `cs show --json` 的 `annotations` 下。

### 恢复过期会话 ```bash cs recover --max-age 12 ``` 自动结束所有超过 12 小时的活跃会话。

## 代理工作流

代理应**务必**在每个命令上使用 `--json` 以获得结构化、可解析的输出。

1. 任务开始时：`cs start "Fix authentication bug" --json --close-stale` 2. 添加上下文笔记：`cs note "analyzing auth flow" --json` 3. 每次 AI 调用后：`cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent "Bug Fixer" --json` 4. 检查支出：`cs status --json` — 读取 `aiCost` 字段 5. 任务结束时：`cs end -n "Fixed the auth bug, added tests" --json` 6. 查看过去的会话：`cs dashboard`

**提示：** 使用 `--agent` 标志来标识您代理的工作，这在多代理系统中特别有用，因为不同的代理处理不同的任务（例如，“Code Review Bot”、“Test Writer”、“Documentation Agent”）。

## 定价

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

```bash # 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 <cost>`。

## 预算感知

如果用户设置了预算或者您检测到高额支出： - 在执行昂贵操作前检查 `cs status --json` - 如果 `aiCost` 在单个会话中超过 5.00 美元，请警告用户 - 如果成本不断上升，建议使用更便宜的模型

## 重要事项

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

## 更新检查

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

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

如果安装的版本落后，请通知用户： > "codesession-cli update available: v1.9.4 -> v2.0.0. Run `npm install -g codesession-cli` to update."

不要因更新而阻塞工作流 —— 仅通知并继续。

## JSON 输出

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