Cost-Aware LLM Pipeline Skill 是 Everything Claude Code 的核心成本优化组件，专为需要调用 LLM API（如 Claude、OpenAI）的开发者设计。通过“按任务复杂度自动路由模型、不可变预算追踪、智能重试与 Prompt 缓存”四大机制，Skill 能大幅降低 LLM API 费用、避免预算超支，并提升批量处理与多模型系统的稳定性和可观测性。本文将结合实际项目场景，手把手讲解如何配置与用好该 Skill，助力你的 AI 编程助手实现高性价比的生产级落地。

Everything Claude Code Cost-Aware LLM Pipeline：按任务复杂度路由模型、预算追踪与 Prompt 缓存优化

在 AI 编程助手（如 Claude Code、Codex、Cursor）进入生产环境后，LLM API 的调用成本、稳定性和响应速度成为影响大规模落地的关键因素。传统做法往往简单粗暴——统一用最强模型、无预算保护、遇错全量重试、每次全量发送 Prompt，导致成本失控、响应慢、可观测性差。Cost-Aware LLM Pipeline Skill 正是为了解决这些痛点而设计，帮助开发者用最优策略管控 LLM API 的每一分钱。

本指南将围绕以下四大能力，系统讲解如何在实际项目中用好 cost-aware-llm-pipeline Skill：

1. 按任务复杂度路由模型：自动选择最划算的 LLM，复杂任务用强模型，简单任务用廉价模型。
2. 不可变预算追踪：每次调用都生成新账本，预算超限自动中断，审计溯源零遗漏。
3. 智能重试机制：只对临时性错误（如网络、限流、服务器异常）重试，认证/参数错误立即 fail fast。
4. Prompt 缓存优化：长 System Prompt 只发一次，后续请求自动复用，节省 token 和延迟。

---

1. 典型场景与激活时机

你应该在以下场景激活 cost-aware-llm-pipeline Skill：

• 需要批量处理任务，如代码审查、自动生成文档、批量测试用例生成等，且每个任务复杂度不一。
• LLM API 成本敏感，有明确的月度/批次预算，不允许超支。
• 多模型架构，希望用“便宜模型打底，复杂任务自动升级”模式提升整体性价比。
• 生产环境，对可观测性、可追溯性和稳定性有较高要求。

与 Agent Harness Construction、Agentic Engineering Skill 等体系结合，可实现端到端的自动化与成本闭环。

---

2. 分步操作指南

步骤一：按任务复杂度自动路由模型

Skill 内置模型选择器，根据输入文本长度、待处理 item 数量等维度，自动决定用哪种模型。例如：

MODEL_SONNET = "claude-sonnet-4-6"
MODEL_HAIKU = "claude-haiku-4-5-20251001"

def select_model(text_length: int, item_count: int, force_model: str | None = None) -> str:
    if force_model is not None:
        return force_model
    if text_length >= 10_000 or item_count >= 30:
        return MODEL_SONNET  # 复杂任务，选高配
    return MODEL_HAIKU  # 简单任务，选低价（3-4倍便宜）

实际用法：

• 你在批量代码审查时，短小文件走 Haiku，超长/复杂文件自动切到 Sonnet，节省 60%+ 成本。
• 支持 force_model 强制指定，便于调试或特殊场景兜底。

步骤二：不可变预算追踪

每次 API 调用后，Skill 会生成新的账本对象，累计每个模型的 token 消耗和美元开销，且账本不可变（frozen dataclass），便于审计和回溯。

@dataclass(frozen=True, slots=True)
class CostRecord:
    model: str
    input_tokens: int
    output_tokens: int
    cost_usd: float

@dataclass(frozen=True, slots=True)
class CostTracker:
    budget_limit: float = 1.00
    records: tuple[CostRecord, ...] = ()

    def add(self, record: CostRecord) -> "CostTracker":
        return CostTracker(
            budget_limit=self.budget_limit,
            records=(*self.records, record),
        )

    @property
    def total_cost(self) -> float:
        return sum(r.cost_usd for r in self.records)

    @property
    def over_budget(self) -> bool:
        return self.total_cost > self.budget_limit

实际用法：

• 你在批量处理前设定 budget_limit，每次调用后自动累加。
• 一旦超限，Skill 会抛出异常，提前终止，防止“爆表”。
• 账本对象可直接用于日志、审计、成本分析。

步骤三：智能重试机制

Skill 只会对网络、限流、服务器异常等“临时性错误”重试，认证/参数错误则立即抛出，避免无意义消耗。

_RETRYABLE_ERRORS = (APIConnectionError, RateLimitError, InternalServerError)
_MAX_RETRIES = 3

def call_with_retry(func, *, max_retries: int = _MAX_RETRIES):
    for attempt in range(max_retries):
        try:
            return func()
        except _RETRYABLE_ERRORS:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # 指数退避

实际用法：

• 你在高并发场景下，Skill 自动帮你规避临时性 API 抖动，提升稳定性。
• 不会因为配置错误/密钥失效等“永久性错误”反复浪费预算。

步骤四：Prompt 缓存优化

对于超过 1024 token 的 System Prompt，Skill 会自动缓存，后续请求只需发送变量部分，大幅降低 token 消耗和延迟。

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": system_prompt,
                "cache_control": {"type": "ephemeral"},  # 标记缓存
            },
            {
                "type": "text",
                "text": user_input,
            },
        ],
    }
]

实际用法：

• 你在多轮对话、批量处理同一任务时，长 System Prompt 只发一次，节省 20%~50% token。
• 配合 Content Hash Cache Pattern 可实现路径无关的自动失效。

---

步骤五：全流程组合（Pipeline）

Skill 推荐将上述能力组合为统一 pipeline，典型调用如下：

def process(text: str, config: Config, tracker: CostTracker) -> tuple[Result, CostTracker]:
    # 1. 路由模型
    model = select_model(len(text), estimated_items, config.force_model)

    # 2. 检查预算
    if tracker.over_budget:
        raise BudgetExceededError(tracker.total_cost, tracker.budget_limit)

    # 3. 智能重试 + Prompt 缓存
    response = call_with_retry(lambda: client.messages.create(
        model=model,
        messages=build_cached_messages(system_prompt, text),
    ))

    # 4. 不可变账本追踪
    record = CostRecord(model=model, input_tokens=..., output_tokens=..., cost_usd=...)
    tracker = tracker.add(record)

    return parse_result(response), tracker

输出示例：

• Result：模型返回的结构化结果（如代码审查报告、文档段落等）
• CostTracker：累计账本，含每次调用的模型、token、美元开销，及总成本

---

3. 常见配套 Agent 与 Skill 协作模式

• 与 Agent Harness Construction 配合，实现多 Agent/多模型的自动路由与预算闭环。
• 与 Agentic Engineering Skill 协作，支持复杂任务分解、子任务独立计费与模型动态升级。
• 与 Content Hash Cache Pattern 联用，提升 Prompt 缓存的命中率与失效安全。
• 与 Context Budget Skill 结合，实时审计上下文窗口占用，进一步优化成本结构。

---

4. 最佳实践与反模式

最佳实践：

• 优先用最便宜模型，复杂任务再自动升级，避免“全场 Opus/最强模型”浪费。
• 批量前先设定预算上限，超限 fail fast，防止 API 账单爆表。
• 日志记录每次模型选择、token 消耗，便于后续调优和成本分析。
• 长 Prompt 必须缓存，尤其是多轮对话/批量任务场景。

反模式：

• 所有请求都用最贵模型，无视任务复杂度。
• 所有错误都重试，导致永久性错误反复烧钱。
• 账本对象可变，后续难以追溯和调试。
• 模型名硬编码，后期维护困难。
• 忽略 Prompt 缓存，导致重复消耗。

---

FAQ

Q: Skill 会自动根据任务复杂度切换模型吗？ A: 是的，Skill 内置模型选择器会根据文本长度、item 数量等自动路由，开发者也可通过参数强制指定模型。

Q: 如何防止 LLM API 预算超支？ A: 只需设置 budget_limit，Skill 会在每次调用后自动累计成本，超限时立即中断后续请求。

Q: Prompt 缓存如何生效？需要手动管理吗？ A: Skill 支持自动缓存长 System Prompt，开发者只需按推荐格式构建消息，缓存与失效由系统自动处理。

---