tokencast

tokencast

LLM Agent 工作流的执行前成本估算。在运行任何 Agent 任务之前获取成本估算，然后让 tokencast 根据实际数据进行学习，随着时间推移提高准确性。

可作为 Claude Code 插件（推荐——一条命令即可完成所有配置）使用，也可作为供 Cursor、VS Code + Copilot 和 Windsurf 使用的 MCP 服务。

---

安装

Claude Code（推荐）

将 tokencast 安装为 Claude Code 插件——只需两条命令，即可安装 MCP 服务、校准钩子和估算技能：

/plugin marketplace add krulewis/tokencast
/plugin install tokencast@tokencast

第一条命令会注册 tokencast 市场。第二条命令会从中安装插件。

**前置条件：**MCP 服务需要安装 uv 才能运行。 安装命令：curl -LsSf https://astral.sh/uv/install.sh | sh

安装内容包括：

• MCP 服务（estimate_cost、get_calibration_status、get_cost_history、report_session、report_step_cost）
• 校准钩子（在会话结束时自动学习、会话中途发出成本警告、跟踪 Agent 时间线）
• SKILL.md（在计划生成后自动触发估算算法）

校准数据存储在 ~/.tokencast/calibration/ 中（所有项目共享，卸载后仍会保留）。

安装范围选项：--scope user（推荐——为所有项目全局安装）或 --scope project（仅针对当前项目安装）。

其他 IDE（MCP 服务）

安装软件包：

pip install tokencast

也可以使用 uvx（无需安装——直接从 PyPI 运行）：

uvx tokencast

配置 IDE——将以下配置片段中的 /path/to/your/project 替换为项目的实际路径。

Cursor

在项目根目录中创建或更新 .cursor/mcp.json：

{
  "mcpServers": {
    "tokencast": {
      "command": "tokencast-mcp",
      "args": [
        "--calibration-dir", "/path/to/your/project/calibration",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

VS Code + GitHub Copilot

在项目根目录中创建或更新 .vscode/mcp.json：

{
  "servers": {
    "tokencast": {
      "type": "stdio",
      "command": "tokencast-mcp",
      "args": [
        "--calibration-dir", "/path/to/your/project/calibration",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

Windsurf

将以下内容添加到 Windsurf MCP 配置中：

{
  "mcpServers": {
    "tokencast": {
      "command": "tokencast-mcp",
      "args": [
        "--calibration-dir", "/path/to/your/project/calibration",
        "--project-dir", "/path/to/your/project"
      ]
    }
  }
}

完整配置示例请参见 docs/ide-configs/。

可用工具

配置完成后，tokencast 会在 IDE 中提供五个 MCP 工具：

工具	功能
estimate_cost	在运行计划任务前估算 API 成本
get_calibration_status	检查估算是否经过良好校准
get_cost_history	查看过往估算值与实际值
report_session	在会话结束时报告实际成本，以改进校准效果
report_step_cost	记录会话中单个流水线步骤的成本

示例——开始工作前进行估算：

Estimate the cost for: size=M, files=8, complexity=high

示例——完成后报告实际成本：

Report session cost: actual_cost=4.20

---

遥测

tokencast 包含可选择退出的匿名使用情况遥测。默认开启——除非你明确将其禁用，否则会收集数据。

**收集的内容：**会话数、平均准确率、已校准因子数、客户端名称、框架、工具名称、软件包版本。**不会收集的内容：**项目名称、文件路径、费用金额或任何个人数据。

禁用方法：

• 调用 disable_telemetry MCP 工具（永久选择退出，并创建 ~/.tokencast/no-telemetry）
• 向 MCP 服务命令传入 --no-telemetry
• 在环境中设置 TOKENCAST_TELEMETRY=0

优先级（从高到低）：

1. TOKENCAST_TELEMETRY=0 → 始终禁用
2. TOKENCAST_TELEMETRY=1 → 始终启用（覆盖 --no-telemetry 和 no-telemetry 文件）
3. ~/.tokencast/no-telemetry 文件存在 → 禁用
4. 默认（无标志、无环境变量）→ 启用

如需删除你的安装 ID：rm ~/.tokencast/install_id。

数据会发送至 PostHog（美国区域）。系统会在本地生成一个随机 UUID 作为你的安装 ID，其中不包含个人信息。详情请参阅 wiki。

---

MCP 服务标志

标志	默认值	说明
--calibration-dir PATH	~/.tokencast/calibration	校准数据的存储位置
--project-dir PATH	None	用于文件测量的项目根目录
--no-telemetry	Off	禁用匿名使用情况遥测（默认开启）
--version		打印版本并退出

---

Claude Code 技能（旧版）

Claude Code 插件（推荐）可通过一条命令提供所有功能。只有在你更喜欢不使用插件系统的 SKILL.md 工作流时，才使用此方式。

如果你使用 Claude Code，并且更喜欢基于技能（SKILL.md）的工作流，可以将 tokencast 安装为 Claude Code 技能：

# Clone the repo (anywhere — it doesn't need to live inside your project)
git clone https://github.com/krulewis/tokencast.git

# Install into your project (quote paths with spaces)
bash tokencast/scripts/install-hooks.sh "/path/to/your-project"

**路径中包含空格：**务必将项目路径用引号括起来。否则，安装脚本在 /Volumes/Macintosh HD2/... 这样的路径下会失败。

此操作会完成以下三件事：

1. 将技能符号链接到 <project>/.claude/skills/tokencast/
2. 添加一个 Stop 钩子，以便在会话结束时自动学习
3. 添加一个 PostToolUse 钩子，在规划 Agent 之后提示进行估算

SKILL.md 工作流仅适用于 Claude Code。MCP 服务适用于任何兼容 MCP 的客户端，也是推荐给新用户的方式。

---

工作原理

1. 从对话中的计划推断规模、文件数量和复杂度
2. 读取定价和 token 启发式规则的参考文件
3. 加载已学习的校准因子（如果存在）
4. 使用活动分解计算每个步骤的 token 估算值
5. 应用复杂度乘数、上下文累积 (K+1)/2 和缓存率
6. 划分为乐观／预期／悲观区间
7. 如果范围包含 PR 审查循环，则使用 N 个审查周期中的几何衰减计算循环成本
8. 对预期区间应用校准修正
9. 记录估算值，以便之后与实际值进行比较

输出示例：

## tokencast estimate

Change: size=M, files=5, complexity=medium
Calibration: 1.12x from 8 prior runs

| Step                  | Model  | Optimistic | Expected | Pessimistic |
|-----------------------|--------|------------|----------|-------------|
| Research Agent        | Sonnet | $0.60      | $1.17    | $4.47       |
| Architect Agent       | Opus   | $0.67      | $1.18    | $3.97       |
| ...                   | ...    | ...        | ...      | ...         |
| TOTAL                 |        | $3.37      | $6.26    | $22.64      |

---

置信区间

区间	缓存命中率	乘数	含义
乐观	60%	0.6x	最佳情况——专注的 Agent 工作
预期	50%	1.0x	典型运行
悲观	30%	3.0x	包含返工循环、调试和重试

---

校准

报告实际值后，校准会全自动进行：

• **0-2 次会话：**不应用修正。“正在收集数据”状态。
• **3-10 次会话：**通过实际值/预期值比率的截尾均值应用全局修正系数（trim_fraction=0.1）。
• **10 次及以上会话：**使用带近期加权的 EWMA。每个尺寸类别有 3 个及以上样本后，其专属系数便会启用。
• **异常值过滤：**实际值/预期值比率大于 3.0x 或小于 0.2x 的会话会从校准中排除。

校准数据位于 ~/.tokencast/calibration/（已加入 gitignore，仅限每位用户本地使用）。

---

Python API

from tokencast import estimate_cost, report_session, report_step_cost
from tokencast import get_calibration_status, get_cost_history

# Estimate before running a task
result = estimate_cost(
    {"size": "M", "files": 5, "complexity": "medium"},
    calibration_dir="./calibration",
)

# Report actuals at session end
report_session({"actual_cost": 4.20}, calibration_dir="./calibration")

# Check calibration health
status = get_calibration_status({}, calibration_dir="./calibration")

# Browse history
history = get_cost_history({"window": "30d"}, calibration_dir="./calibration")

# Report a single step's cost
report_step_cost(
    {"step_name": "Research Agent", "cost": 0.85},
    calibration_dir="./calibration",
)

---

手动调用（技能模式）

在安装了 SKILL.md 的 Claude Code 中，你可以显式调用：

/tokencast size=L files=12 complexity=high
/tokencast steps=implement,test,qa
/tokencast review_cycles=3
/tokencast review_cycles=0

---

文件

SKILL.md                        — Skill definition (auto-trigger, algorithm)
references/pricing.md           — Model prices, cache rates, step→model map
references/heuristics.md        — Token budgets, pipeline decompositions, multipliers
references/examples.md          — Worked examples with arithmetic
references/calibration-algorithm.md — Detailed calibration algorithm reference
docs/ide-configs/               — Per-IDE MCP config examples
src/tokencast/                  — Core estimation engine (Python package)
src/tokencast_mcp/              — MCP server (Python package)
scripts/
  install-hooks.sh              — One-time project setup (skill mode)
  disable.sh                    — Remove from project (skill mode)
  tokencast-learn.sh            — Stop hook: auto-captures actuals (skill mode)
  tokencast-track.sh            — PostToolUse hook: nudges estimation after plans
  sum-session-tokens.py         — Parses session JSONL for actual costs
  update-factors.py             — Computes calibration factors from history
calibration/                    — Per-user local data (gitignored)
  history.jsonl                 — Estimate vs actual records
  factors.json                  — Learned correction factors
  active-estimate.json          — Transient marker for current estimate

---

限制

• 流水线步骤名称反映的是默认工作流——请将你自己的步骤映射到最接近的默认步骤。公式与流水线无关（参见 references/heuristics.md）
• 启发式规则假设源文件通常为 150-300 行
• 校准需要至少完成 3 次会话后才会启用修正
• 定价数据已内置；请查看 references/pricing.md 中的 last_updated
• 多会话任务只会记录包含估算结果的会话

---

许可证

MIT