> 本文是我开源项目 codeAgent（终端 AI 编程智能体）的系列第 1 篇，每天讲一个里面真实用到的技术点，**全部附源码**。
> 仓库：https://github.com/Harvil1/codeAgent

![请添加图片描述](https://developer.qcloudimg.com/http-save/yehe-11433786/d8e109fb90750b3263bf7cabe75cada2.png)

## 一个真实场景

Agent 类应用每一轮都要把**全部历史**重发给模型。对话到第 50 轮，前面 49 轮的内容其实一个字没变，但费用照付。

主流大模型服务商（DeepSeek、OpenAI、Anthropic……）都给了优惠：**你的请求开头如果跟上次一模一样，这段"复读"的部分打折**，输入价常见能打到一折到五折。

这就是前缀缓存（Prompt Caching）。

## 打个比方

复读机折扣：你每天去早餐店报同样的单，老板第三天就懒得重新听了——"还是老三样？直接拿，收你半价"。

但规则很苛刻：**前缀必须逐字节一致**。从第一个不同的字节开始，后面全部恢复原价。

## 什么会"毒死"缓存

| 操作 | 后果 |
|---|---|
| 往历史**中间**插一条新消息 | 从插入点往后缓存全灭 |
| 每轮注入不同临时信息（时间戳、推送）且**写进正式历史** | 每轮前缀都变，缓存等于没有 |
| 消息里带内部记账字段没剥干净就发 | 同上 |
| 中途修改 system prompt | 从头全灭，最贵的一种 |

## 我项目里的三个对策（附源码）

### 对策一：临时消息走"便签通道"，绝不落正式历史

后台推送、队友邮件这类一次性信息，只给模型看一眼就扔。源码在 `agent/ephemeral_inject.py`，文件头把铁律写得很直白：

```python
# 设计原则（临时注入 = ephemeral，即只给大模型看一眼、不留底的消息）：
# - 临时消息一律伪装成 user 角色，**绝不改 system prompt**（保护前缀缓存）
# - 函数返回带 `_ephemeral=True` 标记的 dict，调用方把它追加到 messages
#   （本轮发给 LLM），但**不写进 conversation_history**（不落盘、不留档）
```

随便看一个构造函数（目标模式下"踢"模型继续干活的那条消息）：

```python
def build_goal_continue_message(goal_state) -> Optional[dict]:
    if goal_state is None:
        return None
    if goal_state.status != "active":
        return None
    return {
        "role": "user",
        "content": (
            f'<continue_goal objective="{goal_state.objective}" '
            f'iteration="{goal_state.iteration_count}" />'
        ),
        "_ephemeral": True,   # ← 灵魂就在这个标记：本轮用完即弃
    }
```

主循环每轮组装请求时把它追加到 messages 发出去，**但 conversation_history 一个字不动**——下一轮的前缀和上一轮完全一致，缓存照常命中。

### 对策二：内部字段发送前统一"洗澡"

我给消息打过 `_timestamp`（判断旧消息能不能清理用）这类记账字段，它们**绝不能**混进发给 LLM 的内容。`agent/context_pipeline.py`：

```python
def strip_internal_fields(messages: list) -> list:
    """把消息里的内部字段（如 _timestamp 时间戳、_ephemeral 临时标记）洗掉，再发给 LLM。

    为什么：这些字段是程序自己记账用的，混进发给 LLM 的内容里不但没用，
    还会改变文本、打穿 prompt cache（服务商按前缀复用的缓存）。
    """
    INTERNAL_KEYS = ("_timestamp", "_ephemeral")
    out = []
    for m in messages:
        if any(k in m for k in INTERNAL_KEYS):
            new_m = {k: v for k, v in m.items() if k not in INTERNAL_KEYS}
            out.append(new_m)
        else:
            out.append(m)
    return out
```

注意一个细节：`_ephemeral` 标记本身也要洗掉，但消息的 content/role 照常保留——**LLM 需要内容，不需要我们的记账标记**。标记是给主循环看的，不是给模型看的。

### 对策三：system prompt 会话开头建一次，之后当化石供着

这是主循环 `agent/__init__.py` 文档里原文写的设计：

```python
# 几个必须知道的设计：
# - system prompt（系统提示词）只在会话开头构建一次然后缓存——中途改它
#   会让 LLM 服务商的前缀缓存（prompt cache）失效，token 费用翻倍
```

很多人喜欢每轮往 system prompt 里塞动态信息（当前时间、最新状态）——等于每轮亲手把缓存全部作废。动态信息走对策一的 user 临时消息，system 稳如泰山。

## 效果量级

以 DeepSeek 为例：缓存命中的输入约 1 折。长会话里历史越滚越长，没做缓存的版本可能比做了的多花好几倍——而且这个优化**零成本**：不改模型、不加依赖，只是管住自己的手别乱动消息。

## 小结

三句话带走：

1. 前缀缓存 = 复读折扣，按字节严格匹配，中途改 system 最伤
2. 临时信息走 `_ephemeral` 便签通道：本轮注入、用完即弃、不进历史
3. 记账字段（`_timestamp` 等）发送前统一 strip

下一篇讲它的搭档：**API 突然报 prompt_too_long、任务跑一半，怎么自救**（我给它设计了条"紧急逃生通道"，一样附源码）。

---

仓库在这，注释全中文，欢迎 Star ⭐：https://github.com/Harvil1/codeAgent

本文是我开源项目 codeAgent（终端 AI 编程智能体）的系列第 1 篇，每天讲一个里面真实用到的技术点，全部附源码。 仓库：https://github.com/Harvil1/codeAgent

你的大模型 API 账单能打折：前缀缓存，我用一次踩坑换来的

Agent 每轮都要把全部历史重发给大模型，费用照付；但服务商对逐字节一致的前缀有缓存折扣，输入价最低一折。本文讲清前缀缓存的命中规则、四种"毒死缓存"的常见写法，并附我开源项目 codeAgent 的三段真实源码：临时消息走便签通道不进正式历史、_timestamp 等记账字段发送前统一剥离、system prompt 只构建一次。零依赖零成本，长会话能省数倍 token 费用，附完整代码。

人工智能

后端

开发工具

开源项目codeAgent系列首篇，聚焦Prompt Caching优化技术。文章解析前缀缓存机制如何实现token费用大幅折扣，并揭示三个关键对策：临时消息走ephemeral便签通道、内部字段发送前清洗、system prompt固定不修改。附完整源码，帮助开发者实现长会话缓存复用，节省数倍成本。

代码解释

智能体

AI编程

DeepSeek

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

你的大模型 API 账单能打折：前缀缓存，我用一次踩坑换来的-腾讯云开发者社区-腾讯云

你的大模型 API 账单能打折：前缀缓存，我用一次踩坑换来的

你的大模型 API 账单能打折：前缀缓存，我用一次踩坑换来的

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐