@tencent-ai/agent-sdk 0.3.99 → 0.3.101

package/cli/dist/web-ui/docs/cn/cli/costs.md

@@ -0,0 +1,174 @@
+# 成本管理
+
+> 通过多场景模型选择和异步压缩策略优化成本，在保证效果的同时实现更快的响应速度和更低的使用成本。
+
+CodeBuddy Code 每次交互都会消耗 Token。成本因代码库大小、查询复杂度和对话长度而异。本文档介绍如何追踪成本、多场景模型机制和降低 Token 消耗。
+
+## 追踪成本
+
+### 使用 /cost 命令
+
+`/cost` 命令提供当前会话的详细 Token 使用统计：
+
+```
+/cost
+  ⎿ Total duration (API):  9m 35.6s
+    Total duration (wall): 22m 14.9s
+    Total code changes:    0 lines added, 0 lines removed
+    Usage by model:
+         claude-sonnet-4:  875.5k input, 11.7k output, 714.3k cache read, 0 cache write
+```
+
+### 使用 /context 命令
+
+`/context` 命令可以分析当前上下文的占用情况，查看不同类型上下文的大小分布：
+
+```
+> /context 
+  ⎿  Context Usage
+     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁    glm-4.7 · 38.1k/200.0k tokens (19.1%)
+     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁
+     ⛁ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶    ⛁ System prompt: 2.1k tokens (1.1%)
+     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶    ⛁ System tools: 16.4k tokens (8.2%)
+     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶    ⛁ Memory files: 3.7k tokens (1.9%)
+     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶    ⛁ Messages: 15.9k tokens (7.9%)
+     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶    ⛶ Free space: 145.9k (72.9%)
+     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶    ⛝ Autocompact buffer: 16.0k tokens (8.0%)
+     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶
+     ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝
+
+     Memory files · /memory
+     └ /Users/yangsubo/.codebuddy/CODEBUDDY.md (User): 18 tokens
+     └ /Users/yangsubo/CODEBUDDY.md (Project): 15 tokens
+     └ /Users/yangsubo/workspace/genie/CODEBUDDY.md (Project): 1.2k tokens
+     └ /Users/yangsubo/workspace/genie/packages/agent-cli/CODEBUDDY.md (Project): 2.5k tokens
+
+     Skills and slash commands · /skills
+
+     Project
+     └ release: 1.1k tokens
+     └ gen-drawio: 846 tokens
+     └ task-manager: 815 tokens
+     └ task-add: 730 tokens
+     └ task-done: 525 tokens
+     └ mr: 519 tokens
+     └ task-start: 493 tokens
+     └ my-task: 238 tokens
+     └ task-list: 233 tokens
+     └ security-review: 30 tokens
+```
+
+通过 `/context` 可以快速识别哪些内容占用了大量上下文空间，从而有针对性地优化。
+
+## 多场景模型机制
+
+不同的任务场景对模型能力的要求不同。简单的文件搜索、快速查询等任务使用轻量级模型即可完成；复杂的架构设计、多步骤推理等任务需要更强大的推理模型。
+
+通过为不同场景自动选择不同的模型，可以实现：
+
+* **效果最优**：复杂任务使用高能力模型，确保质量
+* **速度更快**：简单任务使用轻量模型，响应更迅速
+* **成本更低**：避免在简单任务上使用昂贵的高端模型
+
+### 场景类型
+
+| 场景类型 | 说明 | 典型用例 |
+| :--- | :--- | :--- |
+| `default` | 默认模型，平衡性能与成本 | 一般编程任务、代码编写 |
+| `lite` | 轻量快速模型，低成本高速度 | 文件搜索、简单查询、快速操作 |
+| `reasoning` | 推理增强模型，强大分析能力 | 复杂分析、架构决策、多步骤推理 |
+
+### 自动模型选择
+
+CodeBuddy Code 会根据任务类型自动选择合适的场景模型。当子代理执行时，系统会根据用户当前选择的主模型，自动解析出对应的场景模型。
+
+例如，`contentAnalyzer` 等轻量级子代理会自动使用 `lite` 模型，在保证功能的同时降低成本、提升速度。
+
+Agent 工具支持通过 `model` 参数指定场景类型：
+
+* `default`：继承父模型，适用于一般任务
+* `lite`：快速且低成本，适用于简单搜索、快速文件操作
+* `reasoning`：增强推理能力，适用于复杂分析、架构决策
+
+## 降低 Token 消耗
+
+Token 成本随上下文大小增长：CodeBuddy Code 处理的上下文越大，消耗的 Token 越多。CodeBuddy Code 通过 Prompt 缓存（减少重复内容如系统提示的成本）和自动压缩（在接近上下文限制时压缩对话历史）自动优化成本。
+
+以下策略帮助你保持较小的上下文，降低每条消息的成本。
+
+### 主动管理上下文
+
+使用 `/cost` 检查当前 Token 使用情况。
+
+* **任务间清理**：切换到不相关的工作时使用 `/clear` 重新开始。过时的上下文会在后续每条消息中浪费 Token。清理前使用 `/rename` 以便之后通过 `/resume` 返回。
+* **添加自定义压缩指令**：`/compact Focus on code samples and API usage` 告诉 CodeBuddy Code 在压缩时保留什么内容。
+
+你也可以在 CODEBUDDY.md 中自定义压缩行为：
+
+```markdown
+# Compact instructions
+
+When you are using compact, please focus on test output and code changes.
+```
+
+### 异步压缩策略
+
+当对话历史接近上下文限制时，系统会自动进行压缩：
+
+* **自动触发**：当上下文接近限制时自动启动压缩
+* **后台执行**：压缩过程在后台异步执行，不阻塞用户操作
+* **智能摘要**：保留关键信息，压缩冗余内容
+* **无缝衔接**：用户无感知，获得"无限上下文"体验
+
+压缩时会保留以下关键信息：代码变更记录、重要决策点、用户明确的偏好和指示、当前任务的关键上下文。
+
+### 选择合适的模型
+
+根据任务复杂度选择模型。使用 `/model` 在会话中切换模型，或在 `/config` 中设置默认值。
+
+* **简单任务使用 lite**：文件搜索、快速查询、代码格式化
+* **复杂任务使用 reasoning**：架构设计、性能优化、复杂调试
+* **一般任务使用 default**：日常编码、功能实现
+
+### 减少 MCP 服务器开销
+
+每个 MCP 服务器会将工具定义添加到上下文中，即使处于空闲状态。运行 `/mcp` 查看已配置的服务器。
+
+* **优先使用 CLI 工具**：`gh`、`aws`、`gcloud` 等工具比 MCP 服务器更节省上下文，因为它们不会添加持久的工具定义。CodeBuddy Code 可以直接运行 CLI 命令，无需额外开销。
+* **禁用未使用的服务器**：运行 `/mcp` 查看并禁用未使用的服务器。
+
+### 将详细操作委托给子代理
+
+运行测试、获取文档或处理日志文件可能消耗大量上下文。将这些操作委托给子代理，详细输出保留在子代理的上下文中，只有摘要返回主对话。
+
+### 编写精确的提示
+
+模糊的请求如"改进这个代码库"会触发大范围扫描。精确的请求如"为 auth.ts 中的 login 函数添加输入验证"让 CodeBuddy Code 能够以最少的文件读取高效工作。
+
+### 复杂任务的高效工作方式
+
+对于较长或更复杂的工作，以下习惯有助于避免因走错方向而浪费 Token：
+
+* **复杂任务使用计划模式**：按 Shift+Tab (macOS/Linux) 或 Alt+M (Windows) 进入计划模式。CodeBuddy Code 会探索代码库并提出方案供你批准，避免初始方向错误时的昂贵返工。
+* **尽早纠正方向**：如果 CodeBuddy Code 开始走错方向，按 Escape 立即停止。使用 `/rewind` 或双击 Escape 将对话和代码恢复到之前的检查点。
+* **提供验证目标**：在提示中包含测试用例、截图或预期输出。当 CodeBuddy Code 能够自我验证工作时，它可以在你需要请求修复之前发现问题。
+* **增量测试**：写一个文件，测试它，然后继续。这样可以在问题还容易修复时尽早发现。
+
+## 后台 Token 消耗
+
+CodeBuddy Code 在空闲时也会为某些后台功能消耗 Token：
+
+* **对话摘要**：后台任务会为 `--resume` 功能摘要之前的对话
+* **Prompt 预测**：根据历史对话信息推测下一条最有可能的 Prompt 输入
+
+这些后台进程即使没有活跃交互也会消耗少量 Token。
+
+## 相关文档
+
+* [子代理](sub-agents.md) - 使用子代理隔离高消耗操作
+* [MCP](mcp.md) - 管理 MCP 服务器开销
+* [模型](models.md) - 了解可用的模型选项
+
+---
+
+*本文档帮助您了解如何有效管理 CodeBuddy Code 的使用成本。*