ST-ClaudeCacheGateway-Continued 控制台

使用指南

① 查看完整指南。
② 客户端设置：Base URL 填 http://127.0.0.1:8788/v1。
③ 缓存标记：可手动插入长 / 短 marker，也可在缓存策略中选择自动生成模式。

缓存转译

缓存标记与 Prefix Lock

上游格式 - 加载中

当前缓存 TTL - 缓存有效期窗口

Prefix 记录 - 等待状态

快速动作

请求诊断 加载中

Prefix 锁定 加载中

缓存 TTL 加载中

当前状态

OpenRouter

上游 URL 锁定供应商

上游格式

Anthropic

上游 URL 上游格式

Google Vertex AI

上游 URL 上游格式

Amazon Bedrock

上游 URL 上游格式

Pioneer

上游 URL 上游格式

自定义渠道

当前渠道说明

加载中

Profile 会持久化渠道名称、Base URL、上游格式和额外 JSON；不会保存 API Key。切换渠道后，新请求会立即使用当前 Profile。

缓存原理

稳定前缀
世界书 / 角色卡 / 系统设定

[[CACHE_BREAK]]

动态后缀
近期聊天 / 当前输入

缓存命中的关键：把大段不变的内容放在缓存 marker 之前，动态变化的内容放在它之后。前缀越稳定，命中率越高；需要 5m 短缓存时可在手动 TTL 下使用 [[CACHE_BREAK_SHORT]]。

缓存标记与 TTL

缓存断点标记

两个标记都能建立断点；仅在 TTL 选择“手动”时，普通标记固定为 1 小时，SHORT 标记固定为 5 分钟。最多支持 4 个断点。

[[CACHE_BREAK]][[CACHE_BREAK_SHORT]]

自动生成缓存断点

“自动”会在请求已有任一 marker 或合法 cache_control 时跳过生成，否则在最终 SYSTEM 末尾及每个 ASSISTANT 后生成候选；“开启”始终生成，“关闭”从不生成。

系统身份消息处理

“默认”保持 OpenAI-compatible 原始角色与顺序，转为 Anthropic native 时保留开头 SYSTEM、将中途 SYSTEM 原位转为 USER，并合并相邻同角色发言；“关闭Anthropic优化”保持 OpenAI-compatible 原样，但转换 Anthropic 时会把全部 SYSTEM 放到顶部；“统一将系统身份消息放至最顶部”会在两种上游格式中都统一上移 SYSTEM，缓存前缀更稳定，但可能破坏上下文语义。

缓存有效期 TTL

自动不发送 ttl；5 分钟和 1 小时统一应用对应的 Claude 原生窗口；手动模式按两种 marker 分别使用 1h / 5m。

断点保留策略

固定最前面的稳定缓存点，并可让长上下文中的锚点渐进轮换。

加载中

固定头缓存点

始终保留最前面的 0–4 个候选断点。设为 0 且关闭锚点时，保持旧版“最前 4 点”行为。

数量

缓存锚点

单锚点会保留首次入选的非固定头第一点；滚动锚点会冻结首次实际入选的全部非固定点，轮换时只替换最老一点。

模式

滚动间隔

从最新冻结点起累计的非空逻辑内容块数；达到间隔后的第一个候选断点会替换最老滚动点。

内容块

末锚点自动使用 5 分钟

把 5m 阶段执行时最后一个网关缓存点从 1 小时改为 5 分钟；固定头、普通尾点或锚点都可成为目标，已有调用方 cache_control 不会被覆盖。

忽略末尾锚点

按字面忽略最新的 x 个候选锚点，不让它们参与网关缓存选择。评估模式会先把 x 设为 0，完成 3 次连续对话后按逐块哈希给出建议。

模式 x

处理顺序从上到下执行，靠前的选点阶段先锁定候选与预算

完全自由排序属于高级实验功能。固定头晚于忽略末尾、锚点晚于尾点，或把末缓存点 5m 提前，都可能造成规则被阻止、预算耗尽、转换无目标或 TTL 顺序错误；应用顺序变化会自动清空缓存锚点与 Prefix 学习数据。

上游 4 点预算加载中

固定头、锚点、最新普通尾点和调用方已有的 cache_control 共用 4 个位置。

修改后自动应用

锚点模式与 Prefix Lock 互斥，最后启用的功能生效。策略和学习结果都会保存到本地；更改会影响断点选择的设置时将自动清空不兼容的学习数据。

强制 Prefix 锁定

加载中

开启强制锁定

首个带缓存点的请求会学习其前缀；之后请求强制替换为锁定前缀，杜绝前缀漂移导致的缓存失效。

当前锁定状态

换角色 / 世界书 / 预设后请清空重学。

完整诊断日志会保存在本地，可能包含私密提示词。

详情	时间	模型	状态	缓存注入	Prefix 锁定 / 缓存锚点	Usage	渠道

1 / 1

Documentation

使用指南

快速开始客户端接入缓存标记断点保留 Prefix 锁定缓存转译渠道高级配置诊断常见问题

快速开始

启动网关，确认控制台地址为 http://127.0.0.1:8788/console。
在酒馆 / 客户端里选择 OpenAI-compatible / Chat Completion 接入。
Base URL 填 http://127.0.0.1:8788/v1，API Key 填你的上游供应商 Key。

酒馆里选择的是“入站格式”，决定客户端用哪种协议发给本地网关；控制台里的“上游格式”决定网关再用哪种协议转发给供应商。两者可以不同，例如酒馆用 OpenAI-compatible 接入，网关再按当前渠道设置转发到 OpenAI-compatible 或 Anthropic native 上游。

客户端接入

本机使用：http://127.0.0.1:8788/v1
不要把 API Key 写进渠道 Profile。Key 应放在客户端的 Authorization / x-api-key，或仅在私有机器上用 UPSTREAM_API_KEY 环境变量。

缓存标记

在稳定的大段内容末尾放置 [[CACHE_BREAK]] 或 [[CACHE_BREAK_SHORT]]，网关会移除标记并注入 Claude prompt cache 的 cache_control。

自动断点设为“开启”时，会为最终 SYSTEM 末尾和每个 ASSISTANT 消息生成候选 marker；设为“自动”时，仅在请求没有任何手写 marker 和已有的合法 cache_control 时生成。
适合放在标记前：系统提示词、角色卡、蓝灯世界书、长设定、固定规则。
适合放在标记后：绿灯世界书、最近聊天、当前输入、短期记忆、会频繁变化的内容。
TTL 设为“手动”时，[[CACHE_BREAK]] 固定使用 1h，[[CACHE_BREAK_SHORT]] 固定使用 5m；其他 TTL 模式下两种标记都跟随全局设置。
Claude 每次请求最多支持 4 个缓存断点；两种 marker 和已有 cache_control 共用预算，多余标记会被移除。

固定头与缓存锚点

启用新策略后，网关按“固定头 → 锚点 → 最新普通尾点”的顺序分配最多 4 个缓存点。

固定头缓存点设为 1 时，最前面的候选断点不会再随总断点数量增长而被挤掉。
单锚点会记住新上下文最终入选断点中、排除固定头后的第一个 marker 断点；只要该点之前的完整前缀不变，就持续保留。
滚动锚点会冻结首次实际入选的全部非固定点；普通上下文增长不会移动其中任何一点。首次固定下来的最后一个点会作为保护尾锚点，只有进入待淘汰状态后才会释放；达到设定间隔后，只用一个新点替换最老滚动点，其余位置保持不变。
固定头为 A、间隔为 3 的轮换示例：A / E / F / G → A / E / F / G（间隔未到） → A / F / G / J（只替换 E）。
固定头、锚点、普通尾点以及调用方已有的 cache_control 共用上游 4 点预算。例如固定头为 1、单锚点占 1 点时，长示例只会选择 A / F / O / P，不会再加入第五个 N 点。
可开启“末锚点自动使用 5 分钟”，让最末网关锚点使用 5m，而前面的 1h 锚点保持不变。
“忽略末尾锚点”设置数字时会严格排除最新 x 个网关候选；评估模式先把 x 设为 0，连续 3 次同渠道、同协议、同模型的成功对话后，根据最早发生变化、新增或缺失的块一次性计算结果。0–5 自动填入，6 以上先提示检查预设，再由你选择仍然填入或重新评估。
六阶段默认顺序为固定头、忽略末尾、缓存锚点、普通尾点、保护尾锚点、末点 5m；可自由拖动，阶段编号保持固定，修改参数后自动应用。5m 未开启时对应阶段显示灰色“（未启用）”。
策略和已学习锚点都会本地保存；更改处理顺序等不兼容设置时自动清空并重学。
锚点模式与 Prefix Lock 互斥，最后启用的功能生效。

Prefix 锁定 / 强制锁定

Prefix 锁定用于处理“前缀漂移”：如果世界书、正则、插件或数据库填表内容在缓存点前产生变化，缓存命中率会下降。

开启后，第一个带缓存点的请求会教会网关稳定前缀。
后续请求会用已学习的前缀替换当前请求的缓存点前内容，缓存点后的聊天、输入、绿灯世界书仍保持最新。
它是替换，不是追加，不会把世界书、系统提示词或角色卡重复拼接。
更换角色卡、世界书、预设或缓存点前内容后，请清空并重新学习。
关闭“缓存转译”后，Prefix 锁定也会跳过。
Prefix Lock 与缓存锚点互斥：启用 Prefix Lock 会关闭锚点，启用锚点会关闭并清空 Prefix Lock。

缓存转译与 TTL

“缓存转译”开启时，网关会处理两种缓存 marker、注入 cache_control，并允许 Prefix 锁定参与。
关闭后，网关不做缓存标记转译，也不会执行 Prefix 锁定；但渠道、高级配置、上游格式转换仍然生效。
“系统身份消息处理”的默认模式不改 OpenAI-compatible 顺序，并在转为 Anthropic native 时执行保序映射与同角色合并；关闭 Anthropic 优化只让转换链统一上移 SYSTEM；全局上移模式则连 OpenAI-compatible 上游也会重排。
TTL 选择“自动”时不发送 ttl；选择“5 分钟”或“1 小时”时，所有 marker 统一使用对应窗口。
TTL 选择“手动”时，[[CACHE_BREAK]] 使用 ttl: "1h"，[[CACHE_BREAK_SHORT]] 使用 ttl: "5m"。1h 断点必须排在所有 5m 断点之前。

渠道与供应商

渠道 Profile 会保存名称、Base URL、上游格式和高级配置，不保存 API Key。
Pioneer 是默认自定义渠道；OpenRouter、Anthropic、Vertex、Bedrock 是内置模板。
OpenRouter 的“锁定供应商”会写入 provider 参数，可选择常见供应商，也可以填写自定义供应商名。
Vertex / Bedrock 卡片目前是 Profile 模板，不包含 Google Auth 或 AWS SigV4 签名；需要真实云鉴权时建议先走兼容供应商或自定义代理。

高级配置

Usage 外观：全局设置输入、输出、缓存命中、缓存创建和四档命中率配色；点击预览数据原位编辑示例，输入 / 缓存命中 / 命中率自动联动。
Prefix 锁定 / 缓存锚点外观：分别配置两类主状态、“缓存点额度不足”和“块哈希变更数字”的文字、背景与透明状态，并即时预览。
配置管理：可导出 JSON、导入配置或读取 default-gateway-settings.json 恢复默认；导入不会覆盖当前 upstreamMode、upstreamBaseUrl 或渠道 Profile，并忽略 anchorState。
包含主体参数：把 JSON 对象深度合并到最终请求体，同时支持 OpenAI-compatible 和 Anthropic native 上游；请只填写目标协议支持的字段。
排除主体参数：按字段路径删除请求体字段，例如 stream_options 或 metadata.trace_id。
包含请求头：添加 / 覆写非密钥 header，例如 HTTP-Referer、X-Title。
排除请求头：发送上游前删除指定 header，例如 x-real-ip、x-forwarded-for。

Usage 与 Prefix/锚点外观和预览示例全局保存；主体参数和请求头按当前渠道保存。Authorization、x-api-key、Cookie、token、secret、password 等密钥类字段会被拒绝保存。

全局缺省值来自项目根目录的 default-gateway-settings.json；当 gateway-settings.json 缺少全局参数时会回退到该文件，但不会从默认文件导入渠道 Profile。

诊断

请求诊断开关和完整日志都会本地持久保存；重启后仍可查看旧日志，默认最多保留 20 条，可设置 1–1000。
诊断会记录最终请求体，可能包含私密提示词；不要公开导出的诊断 JSON。
可通过诊断查看最终请求体、全部缓存断点、每个断点的选择原因、Prefix hash、suffix hash 和上游缓存用量。
最终请求体中的每个提示词块都会在消息标题栏显示 10 位 SHA-256 短哈希；与同渠道、同协议、同模型的上一次请求不同或新增的块会加粗，完整哈希保留在诊断 JSON。
请求列表和 Usage 页使用双列对齐显示输入、输出、缓存命中和创建，命中率单独成行并按区间着色；原始 Usage JSON 仍保留在统计区下方。
候选缓存点中未发送的点会在最终请求体的原始位置显示为灰色单行“未使用缓存点”；它表示候选被预算或忽略规则排除，不表示四点额度尚未占满。

常见问题

Mac 打不开 bat？ .bat 只适用于 Windows。macOS / Linux 请用 chmod +x start-gateway.sh 后运行 ./start-gateway.sh。
请求 404 或路径不对？ 酒馆 Base URL 优先填写 http://127.0.0.1:8788/v1。
请求日志要一直开吗？ 不建议。开关和完整正文日志都会跨重启保持；排查结束后请主动关闭并清空本地日志。
缓存没命中？ 确认蓝灯世界书在缓存 marker 之前、绿灯世界书在它之后；必要时开启 Prefix 锁定排查前缀漂移。
使用数据库会影响缓存吗？ 数据库本身不影响缓存，官方渠道验证正常；若数据库蓝灯条目会随填表更新，请把全局注入位置改到缓存点后面，例如角色后、系统。
上游不支持 1h TTL？ 在“缓存策略”里切换为“5 分钟”或“自动”；手动模式下不要使用会生成 1h 的 [[CACHE_BREAK]]。

网关概览

快速动作

当前状态

OpenRouter

Anthropic

Google Vertex AI

Amazon Bedrock

Pioneer

自定义渠道

当前渠道说明

缓存原理

缓存标记与 TTL

断点保留策略

强制 Prefix 锁定

Usage 外观

即时预览

Prefix 锁定 / 缓存锚点外观

即时预览

主体参数处理

包含主体参数

排除主体参数

请求头处理

包含请求头

排除请求头

当前 cache_control / 状态 JSON