wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault backup: 2026-06-09 23:15:17

Browse Source
This commit is contained in:
wonder
2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude-code-best/docs/features/token-budget.md
+45 -53
View File
@@ -1,17 +1,23 @@
---
tags: [token-budget, 自动持续, 预算, feature-flag]
create time: 2026-06-09 22:30
---
# TOKEN_BUDGET — Token 预算自动持续模式
## 概述
TOKEN_BUDGET 让用户在 prompt 中指定一个 output token 预算目标（如 `+500k`、`spend 2M tokens`），Claude 会**自动持续工作**直到达到目标，无需用户反复按回车催促继续。适用于大型重构、批量修改、大规模代码生成等需要多轮工具调用的长任务。
> [!info]
> Feature Flag: `FEATURE_TOKEN_BUDGET=1`
> 实现状态：完整可用
## 一、功能概述
## 正文
TOKEN_BUDGET 让用户在 prompt 中指定一个 output token 预算目标（如 `+500k`、`spend 2M tokens`），Claude 会**自动持续工作**直到达到目标，无需用户反复按回车催促继续。
### 用户交互
适用于大型重构、批量修改、大规模代码生成等需要多轮工具调用的长任务。
## 二、用户交互
### 语法
#### 语法
| 格式 | 示例 | 说明 |
|------|------|------|
@@ -21,7 +27,7 @@ TOKEN_BUDGET 让用户在 prompt 中指定一个 output token 预算目标（如
单位支持：`k`（千）、`m`（百万）、`b`（十亿），大小写不敏感。
### UI 反馈
#### UI 反馈
- **输入框高亮**：输入包含预算语法时，对应文字会被高亮标记（`PromptInput.tsx` 通过 `findTokenBudgetPositions` 计算）
- **Spinner 进度**：底部 spinner 显示实时进度，格式如：
@@ -29,46 +35,26 @@ TOKEN_BUDGET 让用户在 prompt 中指定一个 output token 预算目标（如
- 已完成：`Target: 510,000 used (500,000 min ✓)`
- 包含 ETA（基于当前 token 产出速率计算）
## 三、实现架构
### 实现架构
### 数据流
#### 数据流
```
用户输入 "+500k"
│
▼
┌─────────────────────────┐
│ parseTokenBudget() │ src/utils/tokenBudget.ts
│ 正则解析 → 500,000 │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ REPL.tsx │ 提交时调用
│ snapshotOutputTokens │ snapshotOutputTokensForTurn(500000)
│ ForTurn(500000) │ 记录 turn 起始 token 数 + 预算
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ query.ts 主循环 │ 每轮结束后检查
│ checkTokenBudget() │ 当前 output tokens vs 预算
└────────┬────────────────┘
│
┌────┴─────┐
│ │
▼ ▼
continue stop
(未达 90%) (已达 90% 或收益递减)
│ │
▼ ▼
注入 nudge 正常结束
消息继续 发送完成事件
```mermaid
flowchart TD
A["用户输入 +500k"] --> B["parseTokenBudget() src/utils/tokenBudget.ts"]
B --> C["正则解析 -> 500,000"]
C --> D["REPL.tsx 提交时调用"]
D --> E["snapshotOutputTokensForTurn(500000)"]
E --> F["记录 turn 起始 token 数 + 预算"]
F --> G["query.ts 主循环 每轮结束后检查"]
G --> H{"checkTokenBudget() 当前 output tokens vs 预算"}
H -->|"未达 90%"| I["continue 注入 nudge 消息继续"]
H -->|"已达 90% 或收益递减"| J["stop 正常结束 发送完成事件"]
```
### 核心模块
#### 核心模块
#### 1. 解析层 — `src/utils/tokenBudget.ts`
##### 1. 解析层 — `src/utils/tokenBudget.ts`
三个正则表达式解析用户输入：
@@ -82,7 +68,7 @@ VERBOSE_RE = /\b(?:use|spend)\s+(\d+(?:\.\d+)?)\s*(k|m|b)\s*tokens?\b/i
- `findTokenBudgetPositions(text)` — 返回匹配位置数组，用于输入框高亮
- `getBudgetContinuationMessage(pct, turnTokens, budget)` — 生成继续消息
#### 2. 状态层 — `src/bootstrap/state.ts`
##### 2. 状态层 — `src/bootstrap/state.ts`
模块级单例变量追踪当前 turn 的预算状态：
@@ -98,7 +84,7 @@ budgetContinuationCount — 本 turn 已自动续接的次数
- `snapshotOutputTokensForTurn(budget)` — 重置 turn 起点，设置新预算
- `getCurrentTurnTokenBudget()` — 返回当前预算
#### 3. 决策层 — `src/query/tokenBudget.ts`
##### 3. 决策层 — `src/query/tokenBudget.ts`
`checkTokenBudget(tracker, agentId, budget, globalTurnTokens)` 做出 continue/stop 决策：
@@ -115,7 +101,7 @@ budgetContinuationCount — 本 turn 已自动续接的次数
**收益递减检测**：`continuationCount >= 3` 且最近两次 nudge 的 delta 都 < 500 tokens。
#### 4. 主循环集成 — `src/query.ts`
##### 4. 主循环集成 — `src/query.ts`
```
query() 函数内：
@@ -130,7 +116,7 @@ query() 函数内：
- 正常返回
```
#### 5. UI 层
##### 5. UI 层
| 文件 | 职责 |
|------|------|
@@ -140,15 +126,16 @@ query() 函数内：
| `screens/REPL.tsx:2138` | 用户取消时清除预算 |
| `screens/REPL.tsx:2963` | turn 结束时捕获预算信息用于显示 |
#### 6. 系统提示 — `src/constants/prompts.ts:538-551`
##### 6. 系统提示 — `src/constants/prompts.ts:538-551`
注入 `token_budget` section：
> "When the user specifies a token target (e.g., '+500k', 'spend 2M tokens', 'use 1B tokens'), your output token count will be shown each turn. Keep working until you approach the target — plan your work to fill it productively. The target is a hard minimum, not a suggestion. If you stop early, the system will automatically continue you."
注意：这段 prompt **无条件缓存**（不随预算开关变化），因为 "When the user specifies..." 的措辞在没有预算时是空操作。
> [!tip]
> 这段 prompt **无条件缓存**（不随预算开关变化），因为 "When the user specifies..." 的措辞在没有预算时是空操作。
#### 7. API 附件 — `src/utils/attachments.ts:3830-3845`
##### 7. API 附件 — `src/utils/attachments.ts:3830-3845`
每轮 API 调用附带 `output_token_usage` attachment：
@@ -163,7 +150,7 @@ query() 函数内：
让模型能看到自己的进度。
## 四、关键设计决策
### 关键设计决策
1. **90% 阈值而非 100%**：在 `COMPLETION_THRESHOLD = 0.9` 处停止，避免最后一轮 nudge 产生远超预算的 token
2. **收益递减保护**：连续 3 轮 nudge 后如果每轮产出 < 500 tokens，判定模型已无实质进展，提前终止
@@ -171,7 +158,7 @@ query() 函数内：
4. **无条件缓存系统提示**：预算 prompt 始终注入（不随预算变化 toggle），避免每次切换预算导致 ~20K token 的 cache miss
5. **用户取消清预算**：按 Escape 取消时调用 `snapshotOutputTokensForTurn(null)`，防止残留预算触发续接
## 五、使用方式
### 使用方式
```bash
# 启用 feature
@@ -183,7 +170,7 @@ FEATURE_TOKEN_BUDGET=1 bun run dev
> 帮我写完整的 CRUD 模块 +1m
```
## 六、文件索引
### 文件索引
| 文件 | 行数 | 职责 |
|------|------|------|
@@ -196,3 +183,8 @@ FEATURE_TOKEN_BUDGET=1 bun run dev
| `src/screens/REPL.tsx:2897,2963,2138` | 20 | REPL 提交/完成/取消处理 |
| `src/components/Spinner.tsx:319-338` | 20 | 进度条 UI |
| `src/components/PromptInput/PromptInput.tsx:534` | 1 | 输入高亮 |
## 关联笔记
- [[claude-code-best/docs/features/proactive]]
- [[claude-code-best/docs/features/kairos]]