Appearance
Agent token 量级与预算取值建议（2026 下半年）
观测日 2026-09-24｜本机实测 + 官方价目表交叉核对｜面向本仓库（sjtu-agent）的取值建议 证据分级：[实测] 本机数据/本次测量；[官方] 厂商官方页面；[外部] 第三方实测或社区报告；[建议] 我的取值主张 配套材料：各模型窗口与价格对照（本站）｜各家上下文管理实作、外部实测消耗（原始调研记录，留在仓库内、未上文档站）
0. 先给结论
- 单次调用的上下文量级是按「十万」计的：本机 3,076 次真实调用实测 —— 中位 28.9 万 tokens、p90 58.1 万、p99 69.2 万、峰值 71.4 万 [实测]。也就是说 1M 窗口不是"用不满的余量"，而是被稳定用到 30%~70%。
- 但每次新增输入只有中位 282 tokens（占上下文 0.04%）[实测]：成本结构不是"聊得多"，而是同一条稳定前缀被反复重发，因此缓存命中率才是真正的成本开关，不是上下文长度本身。
- harness 固定开销 ~2.6 万 tokens/次（DSH，其中工具 schema 约 2.2 万）[实测]；本仓库 sjtu-agent 实测 ~1.74 万（系统提示 1.28 万字符 + 76 个工具 schema 3.78 万字符，按实测 2.9 字符/token 折算）[实测]。
- 窗口与折叠阈值别按老经验拍：2026 各家实现普遍落在窗口的 80%~95% 才压缩（Claude Code 1M 模型 ~967K、Codex 实际等到可用窗口 94.74%、dsh
thresholdRatio=0.8）[外部]。本仓库当前SESSION_QUALITY_BUDGET = 256_000，在 1M 窗口下只用了 25%，远早于外部同类实现——而"太早折叠"正是"限制窗口太小容易截断"的另一种形态。 - 不要信框架自带的 cost 字段：本机账本把
deepseek-flash按 V4-Pro 价目计价，比官方 Flash 价恒定高 6.67× [实测]（见 §4）。自己按官方价目表算。
1. 本机实测：一次 agent 调用到底多大
数据源：~/.dsh/dsh-usage/usage-ledger.json（8 天日账）+ ~/.dsh/sessions/**/session.v3.jsonl（30 份会话、3,076 次带用量的模型调用、24 份含调用）。这是本机真实负载，不是基准测试。
| 指标（每次模型调用） | min | p50 | p90 | p99 | max | 均值 |
|---|---|---|---|---|---|---|
| 上下文总量（input + cacheRead） | 5,790 | 288,761 | 581,409 | 691,842 | 714,318 | 312,219 |
| 其中未命中缓存的新增输入 | 21 | 282 | 2,168 | 15,063 | 305,487 | 1,358 |
| 输出 tokens | 41 | 497 | 1,680 | 5,724 | 88,226 | 862 |
| 其中思考 tokens | 0 | 71 | 765 | 4,104 | 83,056 | 344 |
| 指标（每次会话 / 工具结果） | 数值 |
|---|---|
| 每会话模型调用次数 | p50 41，p90 426，max 667 |
| 会话首次调用上下文（≈ harness 固定开销 + 首条用户消息） | p50 25,630，p90 27,327，max 27,402 |
| 单条工具结果字符数 | p50 448，p90 4,239，p99 22,635，max 51,486 |
| 缓存命中占上下文比例（总量口径） | 99.6% |
| 思考占输出比例（总量口径） | 39.9% |
固定开销分解（字符 → token 按实测 2.9 字符/token）
| 组成 | DSH（本机运行时） | sjtu-agent（本仓库） |
|---|---|---|
| 系统提示词 | p50 11,493 字符 ≈ 4.0K tokens | 12,812 字符 ≈ 4.4K tokens |
| 工具 schema | p50 63,604 字符 ≈ 21.9K tokens | 37,768 字符（76 个工具）≈ 13.0K tokens |
| 合计固定开销 | ≈ 25.6K tokens | ≈ 17.4K tokens |
| 最贵的单个工具 schema | — | add_mcp_server 1,579 字符、create_skill 1,208、configure_canvas_monitor 1,207 |
对照外部：54 工具时 schema 占每次请求 83.1%、真实对话仅 0.6%（hermes #67273）[外部]；一句 "hello" → 22,300 tokens 的 prompt（qwen-code #6097）[外部]。本机 25.6K 与该量级一致。
2. 上下文是怎么涨上去的（以及折叠发生在哪里）
跨会话聚合的中位上下文（按会话内 step）：
| step | 1 | 5 | 10 | 20 | 30 | 40 | 60 |
|---|---|---|---|---|---|---|---|
| 中位上下文 | 27.3K | 60.7K | 111.1K | 144.6K | 284.5K | 320.1K | 303.2K |
| 最大上下文 | 704K | 710K | 714K | 651K | 662K | 677K | 460K |
- 前 30 步近似线性：约 +8.9K tokens/步（每次工具调用 + 结果 + 助手消息）[实测]；外部同口径是 +1,719/+1,838 tokens/步（TraceLab，Claude Code + Codex）[外部]，本机明显更高（本机工具结果 p90 4.2K 字符）。
- 曲线在第 16、44~45、59~60 步出现回落（如 405.3K → 270.6K），即折叠/压缩事件：幅度约 −130K tokens [实测]。
- 结论：折叠阈值决定"多久折一次"。本仓库 256K 预算会在 step 8~10 附近首次触发（中位 111K 时尚不触发，20 步 145K，30 步 285K → 触发点落在 step 25~30 之间），而外部实现要到 800K+。
3. 成本：官方价目 vs 账本价
按官方价目（DeepSeek V4.1-Flash：输入 $0.15/1M、缓存命中 $0.003/1M、输出 $0.60/1M，谷时）[官方]，本机 8 天负载：
| 口径 | 计算 | 结果 |
|---|---|---|
| 实际计费口径（含缓存） | 新增输入 2.75M×$0.15 + 缓存 890.7M×$0.003 + 输出 2.35M×$0.60 | ≈ $4.49 / 8 天 |
| 反事实：无缓存（每次重发全量上下文） | 893.4M×$0.15 + 2.35M×$0.60 | ≈ $135.4 / 8 天 |
| 账本自报 | 账本 cost 字段合计 | $30.17 |
两个结论：
- 缓存带来 ~30× 的成本差（$4.49 vs $135.4）[实测+官方]。保持稳定前缀（会话中不换模型、不增删工具、易变内容后置）不是优化技巧，是成本前提。
- 账本自报 $30.17 与官方价核算的 $4.49 差 6.7 倍：逐日比对显示账本按 V4-Pro 价目计价（V4-Pro 缓存读 $0.022/1M vs Flash $0.003/1M），8 天比值恒为 6.67×、与官方 V4-Pro 价核算比为 1.03~1.52× [实测+官方]。用框架自带的 cost 字段做决策会系统性高估（或低估）成本。
4. 与外部证据对齐
| 指标 | 本机实测 | 外部 2026 数据 | 一致性 |
|---|---|---|---|
| 单次调用上下文 | p50 289K | TraceLab 中位单步 119K 缓存前缀；Copilot 生产 ≈125K/次调用 [外部] | 同量级（10 万~30 万），本机偏高 |
| 新增输入占比 | 0.04%（282/289K） | 输出仅占总量 0.34%，输入:输出 ≈ 294:1 [外部] | 一致 |
| 缓存命中 | 99.6% | TraceLab 全局 95.7%；Copilot 轮内 90% / 跨轮 55%；同模型跨 harness 1.5%~70% [外部] | 本机偏高（短会话+严格稳定前缀） |
| 增长 | +8.9K tokens/步（前 30 步） | +1,719/+1,838 tokens/步 [外部] | 本机更高 |
| 思考占输出 | 39.9% | Codex 40.8%；Opus 5.5 单答案 98.4% [外部] | 一致 |
| harness 固定开销 | 25.6K tokens/次 | 22.3K（"hello" prompt）、schema 占 83.1% [外部] | 一致 |
| 压缩触发点 | 本仓库 256K（25% 窗口） | Claude Code ~967K（1M）、Codex 94.74%、dsh 0.8×窗口、OpenCode 窗口−20K−buffer [外部] | 本仓库明显偏早 |
5. 对 sjtu-agent 的取值建议
| # | 项目 | 现状 | 建议 | 状态 |
|---|---|---|---|---|
| 1 | 折叠预算 SESSION_QUALITY_BUDGET | 原为 256_000 写死（且模块 docstring 写 64K，不一致） | 按后端 + 模型的窗口取一半：官方 DeepSeek/Anthropic 1M → 500K；致远一号 deepseek-chat 512k → 256K、qwen 256k → 128K（官方指南数据，不是 1M）；其它网关窗口未公开 → 128K 窗口 → 64K；可用 SJTU_CONTEXT_WINDOW / SJTU_CONTEXT_BUDGET 显式声明 | ✅ 已落地（agent/context.py：model_context_window(model, base_url) / context_budget() / is_campus_gateway()；runner.py 从 SDK 客户端读 base_url 后传入） |
| 2 | 输出上限 | Anthropic 路径写死 max_tokens=4096（OpenAI 路径已不设上限） | 自适应：min(厂商上限, 窗口 − 已用 prompt − 余量)，不低于 1024。DeepSeek-V4.1-Flash 上限 393,216（384K，思考与正文共享该配额）；Claude/GPT-6 128K、Gemini 65,536、Qwen/Kimi 131,072；认不出的模型保守 8192。SJTU_MAX_OUTPUT_TOKENS 可覆盖 | ✅ 已落地（agent/runner.py::_max_output_tokens(base_url, model, prompt_tokens=…) + _provider_output_cap()；后端拒绝时自动降档重试 2 次） |
| 3 | 工具 schema 开销 | 76 个工具 / 37.8K 字符 ≈ 13K tokens（占固定开销 75%） | 按意图分组懒加载（邮件/Canvas/食堂/提醒各自成组）；精简描述 | ⬜ 待办（会话内工具集已是静态列表，这点已满足） |
| 4 | 缓存纪律 | 动态时间注入在用户消息首部，system 前缀稳定 ✓ | 补：MCP 工具列表 60s TTL 可能在会话中途变化 → 整个前缀失效；建议会话内固定工具集 | ⚠️ 部分（extensions/mcp_client.py::_TOOLS_CACHE 仍会刷新） |
| 5 | 工具结果内联上限 | fetch_url 8,000 字符截断，无落盘 | 内联 ~10K 字符，超出落盘 + 回路径与预览 | ⬜ 待办 |
| 6 | 成本核算 | 依赖运行时/框架的 cost 字段 | 按官方价目自算；把"折叠次数 / 每轮估算上下文"记日志（已加） | ⚠️ 部分（折叠事件已记 INFO 日志，缓存命中率未采集） |
| 7 | 模型选择 | 默认致远一号 deepseek-chat | deepseek-v4-pro 已路由到 V4.1-Flash 并按 Flash 计费；峰谷价差 2× | ℹ️ 信息性 |
5.1 本次落地的改动（2026-09-24）
| 文件 | 改动 |
|---|---|
sjtu_agent/agent/context.py | 新增 model_context_window(model, base_url)：先看 SJTU_CONTEXT_WINDOW，再按后端分流（致远一号按官方指南 512k/256k、官方端点按官方规格、其它网关保守 128K），最后才按模型名猜；新增 is_campus_gateway()；context_budget() 按该窗口取一半（SJTU_CONTEXT_BUDGET 可覆盖、上下夹取）；trim_session(budget=None) 改按预算入参；折叠事件记 INFO 日志（预算、折叠轮数、折叠前后估算），供后续用真实数据校准 |
sjtu_agent/agent/runner.py | _run_one_turn 从 SDK 客户端读 base_url 后传 context_budget(model, base_url=...)；新增 _provider_output_cap()（DeepSeek 393,216 / Claude·GPT-6 128K / Gemini 65,536 / Qwen·Kimi 131,072 / 未知 8192）与 _max_output_tokens(base_url, model, prompt_tokens=…)——按 min(厂商上限, 窗口 − prompt − 余量) 自适应，替换 Anthropic 路径两处写死的 4096；后端以 max_tokens 为由拒绝时自动降档重试（最多 2 次）；新增 _estimate_prompt_tokens()（图片按固定视觉成本计，不按 base64） |
.env.example | 新增「上下文与输出预算」段：列出各后端的默认取值与两个窗口/预算环境变量 |
tests/test_context.py、tests/test_runner_limits.py | 新增 12 个用例（后端分流、网关调用名映射、未知网关不猜、环境变量优先、预算夹取、官方/网关输出上限、环境变量覆盖与非法值回落） |
为什么按后端而不是按模型名：致远一号的
deepseek-chat是网关调用名，官方指南写的是 512k，而官方 DeepSeek 同名口径是 1M——按模型名一刀切会把折叠预算算到窗口外面去（500K 预算 + 13K 工具 + 17K 系统 + 输出 > 512K）。反过来，接官方 DeepSeek 时按网关的 512k 保守取值又是白白束手束脚。
6. 缺口与待验证
- 中文/校园场景的分布级 token 数据缺失 [外部]：本机数据是单机样本（1 个用户、DeepSeek Flash），不能代表全体用户；建议在 sjtu-agent 里埋点统计（每轮上下文、折叠次数、缓存命中），两周后再校准第 1 条建议。
- 折叠阈值与"质量下降"的定量关系没有硬数据：外部只有"context rot"定性说法与无方法学的 70% 数字；建议用可控实验（同任务在 256K/500K/800K 预算下对比任务成功率）替代直觉。
- 账本价目表的来源未确认：我只能从数字反推它按 V4-Pro 计价（6.67× 恒定比值），未读到它的价目表源码（本机 checkout 只含 web-app 依赖闭包，未包含用量包本体）。
- dsh
tool-result-pruner的具体阈值未公开（剪枝包本体不在本机 checkout 内）[外部]。 - 未覆盖：非编码 chat 智能体的每轮 token 拆分、研究型 agent 的分布级数据、分 provider 的长期缓存命中统计 [外部]。