token-optimization

Token 优化最佳实践

深度知识：使用 technology 为 token-optimization 的 mcp__documentation__fetch_docs 获取完整文档。

最大限度减少 MCP 服务和外部工具交互中的 Token 消耗的指南。

不应使用此技能的情况

此技能侧重于优化 API／工具调用。以下情况请勿使用：

• 运行时性能——使用 performance 技能优化速度
• 代码压缩——使用构建工具（Vite、Webpack 等）
• 数据库查询优化——使用数据库专用技能
• 算法效率——运用计算机科学基础知识
• 提示词工程——此技能讲的是工具使用，而非提示词设计

通用原则

原则	说明
按需加载	仅在确有必要时加载信息
最少输出	只请求所需数据，使用 limit 和 compact 参数
渐进式深入	从概览／摘要开始，仅在需要时深入了解
优先使用缓存	外部调用前，先检查上下文中是否已有相关信息

反模式

反模式	不足之处	节省 Token 的解决方案
**SELECT ***	返回不需要的列	指定所需的确切列
不加 LIMIT 子句	返回整个数据集	始终添加 LIMIT（例如 100）
请求完整架构	返回庞大的规格信息	使用 compact=true 或 format="summary"
递归获取文档	获取整个文档树	使用 search_docs 并指定查询内容
获取完整日志	返回数千行内容	使用 tail_logs，或使用带 limit 的 find_errors
复制粘贴文档	重复内容	概述并引用，不要逐字照搬
不使用分页	一次性返回所有结果	对大型数据集使用 offset／limit
探索完整 API 架构	规格文件可能达数 MB	先获取端点列表，按需查看详情

快速故障排查

问题	检查项	解决方案
MCP 响应过大	输出大小 > 2000 个 Token	添加 limit 参数，使用紧凑格式
重复调用 API	多次调用同一工具	在对话上下文中缓存结果
上下文增长过慢	工具调用过多	批量处理相关查询，使用更具体的工具
不必要的文档获取	信息已知	先检查技能文件，最后再获取文档
全表扫描结果过多	数据库查询返回内容过多	添加 WHERE 子句和 LIMIT
错误日志过于冗长	重复输出完整堆栈跟踪	概述错误并引用行号

MCP 服务模式

database-query

-- BAD: Query without limits
SELECT * FROM users

-- GOOD: Query with filters and limits
SELECT id, name, email FROM users WHERE active = true LIMIT 100

工具用法：

• execute_query：始终使用 limit 参数（默认值：1000）
• get_schema(compact=true)：概览数据库结构
• describe_table：在执行探索性查询前使用
• explain_query：在大型表上执行复杂查询前使用

api-explorer

-- BAD: Full schema
get_api_schema(format="full")

-- GOOD: Summary only for overview
get_api_schema(format="summary")

-- GOOD: Path list with limit
list_api_paths(limit=50)

-- GOOD: Single endpoint details
get_api_endpoint_details(path="/users/{id}", method="GET")

工具用法：

• get_api_schema(format="summary")：概览 API
• list_api_paths(limit=50)：获取端点列表
• get_api_models(compact=true)：获取模型列表，不返回完整架构
• search_api(limit=10)：执行针对性搜索

documentation

-- BAD: Entire document
fetch_docs(topic="react")

-- GOOD: Targeted search
search_docs(query="useEffect cleanup", maxResults=3)

工具用法：

• search_docs(maxResults=3)：搜索特定信息
• fetch_docs：仅用于非常具体的主题
• 获取文档前，先检查技能文件

log-analyzer

-- BAD: All logs
parse_logs(file="/var/log/app.log")

-- GOOD: Recent errors only
find_errors(file="/var/log/app.log", limit=50)

-- GOOD: Tail for live debugging
tail_logs(file="/var/log/app.log", lines=50)

工具用法：

• tail_logs(lines=50)：获取近期日志
• find_errors(limit=50)：调试错误
• parse_logs(limit=200)：仅在需要完整分析时使用

security-scanner

工具用法：

• scan_dependencies：优先于 scan_all 使用
• scan_secrets：比完整扫描更快
• scan_all：仅用于完整审计

代码质量

工具使用：

• analyze_complexity(path="src/specific/file.ts")：针对特定文件
• find_duplicates(minLines=10)：仅筛选重要的重复代码
• code_metrics：用于概览的精简输出

MCP 调用前检查清单

调用 MCP 工具前，请确认：

• 我是否已在上下文中获取此信息？
• 我能否使用更具体的工具，而非通用工具？
• 我是否设置了合适的 limit？
• 如果可用，我是否使用了 compact=true？
• 预期输出是否合理（< 2000 个 token）？

输出格式规范

代码分析

• 每个类别最多列出 5 个问题
• 代码片段最多 10 行
• 列表使用表格

数据库查询

• 直接输出最多 20 行
• 结果超过 20 行时：“找到 N 行。前 20 行：...”
• 使用紧凑的表格格式

文档

• 仅引用相关内容（最多 500 个字符）
• 链接到完整文档，不要复制内容
• 使用摘要，而非逐字引用

高效响应示例

数据库查询 - 精简输出

Found 1523 rows. First 20:
| id | name | status |
|----|------|--------|
| 1  | ...  | active |
...
Use offset=20 for next page.

API 探索 - 逐步深入

API has 45 endpoints. Summary by tag:
- users: 8 endpoints
- auth: 5 endpoints
- products: 12 endpoints
...
Use get_api_endpoint_details for specifics.

日志分析 - 聚焦输出

Found 234 errors in last hour. Top 5 by frequency:
1. ConnectionTimeout: 89 occurrences
2. ValidationError: 45 occurrences
...
Use tail_logs or parse_logs with filters for details.

参考文档

深入了解：将技术设为 token-optimization，使用 mcp__documentation__fetch_docs 获取高级优化技巧。