fix(cache): stable instructions head for prompt_cache_key + claude cache test method

Author: 6Kmfi6HP

docs/claude-cache-test-method.md

@@ -0,0 +1,99 @@
+# Claude Code 缓存测试法（网关强制指向）
+
+> 任何"缓存命中率 / `prompt_cache_key` / instructions 变化"类测试，
+> 一律按此法执行。合成 curl 只用于冒烟，结论必须来自真机 + 网关日志。
+
+## 1. 铁律（违反则结论作废）
+
+1. 模型必须用网关现存模型（如 `muse-spark-1.3-contributor-free`）。
+   网关没有的模型会触发 `[claude-code:unrecognized_model]`，流量可能旁路网关。
+2. 必须用 `--settings <gw-settings.json>` 强制指向网关。
+   `~/.claude/settings.json` 自带 `ANTHROPIC_BASE_URL` 与 `ANTHROPIC_AUTH_TOKEN`，
+   进程 env 的优先级不稳定，裸 `export` 经常被覆盖，导致流量根本没进网关
+   （现象：回了 `TURN_ONE_OK` 但网关 `cache_debug_key_parts` 计数不涨）。
+   不要手配 `ANTHROPIC_AUTH_TOKEN=sk-123` 类 env（`launch_env.go` 已证明它会劫持
+   Claude Code 网络栈）。一切以 `--settings` 文件为准。
+3. 两轮必须同会话：首轮 `--session-id $UUID`，次轮 `--resume $UUID`。
+4. 网关必须带 `OPENCODE2API_CACHE_DEBUG=1` 启动，且是最新 `bin/opencode2api`
+   （`make build` 后重启才生效）。
+
+## 2. 标准步骤
+
+```bash
+# 0. 起网关（新二进制 + debug）
+OPENCODE2API_CACHE_DEBUG=1 ./bin/opencode2api -port 8080 -log-stdout
+
+# 1. 写强制网关的 settings（模型换成网关现存的）
+python3 -c "
+import json
+m='muse-spark-1.3-contributor-free'
+env={
+ 'ANTHROPIC_BASE_URL':'http://127.0.0.1:8080',
+ 'ANTHROPIC_AUTH_TOKEN':'sk-123',
+ 'ANTHROPIC_MODEL':m,
+ 'ANTHROPIC_DEFAULT_OPUS_MODEL':m,   'ANTHROPIC_DEFAULT_OPUS_MODEL_NAME':m,
+ 'ANTHROPIC_DEFAULT_SONNET_MODEL':m, 'ANTHROPIC_DEFAULT_SONNET_MODEL_NAME':m,
+ 'ANTHROPIC_DEFAULT_HAIKU_MODEL':m,  'ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME':m,
+ 'ANTHROPIC_DEFAULT_FABLE_MODEL':m,  'ANTHROPIC_DEFAULT_FABLE_MODEL_NAME':m,
+ 'CLAUDE_CODE_SUBAGENT_MODEL':m,
+}
+json.dump({'env':env}, open('/tmp/cc-cache-test/gw-settings.json','w'), indent=2)
+"
+
+# 2. 第一轮（记 BASE 计数）
+UUID=$(uuidgen | tr 'A-Z' 'a-z'); echo "$UUID" > /tmp/cc-cache-test/session.id
+echo "BASE=$(grep -a -c cache_debug_key_parts opencode2api.log)"
+cd /tmp/cc-cache-test && timeout 280 claude -p --session-id "$UUID" \
+  --settings /tmp/cc-cache-test/gw-settings.json \
+  "Reply with exactly: TURN_ONE_OK and nothing else. Do not use any tools." \
+  --max-turns 3 2>&1 | tail -4
+
+# 3. 有效性检查：计数必须涨，否则流量没进网关，本轮作废
+grep -a -c "cache_debug_key_parts" opencode2api.log  # 必须 > BASE
+
+# 4. 同会话第二轮
+UUID=$(cat /tmp/cc-cache-test/session.id)
+cd /tmp/cc-cache-test && timeout 280 claude -p --resume "$UUID" \
+  --settings /tmp/cc-cache-test/gw-settings.json \
+  "Reply with exactly: TURN_TWO_OK and nothing else. Do not use any tools." \
+  --max-turns 3 2>&1 | tail -4
+```
+
+## 3. 标准读数
+
+```bash
+# 跨轮 pck / 全长 / 入 key 长
+grep -a "cache_debug_key_parts" opencode2api.log | tail -n 6 | python3 -c "
+import sys,re
+for line in sys.stdin:
+    ts=line[:30]
+    pck=re.search(r'pck=(\S+)',line).group(1)[-12:]
+    fl=re.search(r'instr_full_len=(\d+)',line)
+    fs=re.search(r'instr_full_segs=(\d+)',line)
+    pl=re.search(r'part0_len=(\d+)',line)
+    print(ts,'pck=..'+pck,'part0_len=',pl.group(1) if pl else '?','full_len=',fl.group(1) if fl else '?','full_segs=',fs.group(1) if fs else '?')
+"
+# 命中
+grep -a "cache_debug_usage" opencode2api.log | tail -n 4 | grep -oE "input_tokens=[0-9]+ output_tokens=[0-9]+.*cached_tokens=[0-9]+"
+# 池 key 是否钉住
+grep -a "upstream_attempt" opencode2api.log | tail -n 4 | grep -oE "key_id=k[0-9]+"
+```
+
+判定：
+
+- `part0_len` 同 + `pck` 同 + 池 key 同 + 轮 2 `cached>0` = 修好。
+- `instr_full_len` 涨但 `part0_len` 不涨 = 稳定头截断生效。
+- 计数不涨 = 流量没进网关，重查模型名 / settings / `--resume`。
+
+## 4. 背景：2026-10-08 缓存命中率修复
+
+- 现象：同会话 `part0_len 31397→36694`，`first_user`/tools 不变，两轮 `cached=0`。
+- 定位：`instructions` = system 参数 + `role=system` 消息 join，
+  Claude Code 每轮尾部追加约 18 段（`59→77` 段，`+6KB`），全量哈希导致每轮换 key。
+- 修复：`contentPromptCacheKey` 只取 `instructions` 前 16 段
+ （`stableInstructionsHead`，见 `internal/app/chat.go`）入 key；
+  `config.json` 本地 `key_pool.strategy round_robin→sticky`、
+  `prompt_cache_retention off→24h`。
+- 验证（本测试法）：尾部 `+5KB` 时 `pck` 不变、池 key 钉住、
+  轮 2 `7025/16984≈41%` 命中。回归测试
+  `TestContentPromptCacheKey_StableHeadIgnoresAppendedTail`。

internal/app/chat.go

@@ -1910,24 +1910,45 @@ func preferContentKey(hasToken bool) bool {
 	return !hasToken
 }
 
+// stableInstrHeadSegs 是 instructions 稳定前缀的段数："\n\n" 切段后只取前 N 段
+// 参与 prompt_cache_key 哈希。Claude 侧 instructions = system 参数 +
+// role=system 消息顺序 join，实测头 16 段跨轮逐段同哈希、尾部每轮追加约 18 段；
+// 只哈希稳定头则同会话跨轮 key 不变，上游 prefix-cache 才能命中。N=16 覆盖实测
+// 稳定区并留出余量；不同会话/不同 system 头天然不同段，不会误撞。
+const stableInstrHeadSegs = 16
+
+// stableInstructionsHead 返回参与缓存 key 的 instructions 稳定前缀：按 "\n\n"
+// 切段取前 stableInstrHeadSegs 段 join。段数不足时返回原文（短 instructions 不
+// 截断）；尾部追加段被排除在 key 之外，但仍会原样发往上游，不丢上下文。
+func stableInstructionsHead(instr string) string {
+	segs := strings.Split(instr, "\n\n")
+	if len(segs) <= stableInstrHeadSegs {
+		return instr
+	}
+	return strings.Join(segs[:stableInstrHeadSegs], "\n\n")
+}
+
 // contentPromptCacheKey 对上游请求体（已 marshal 的 chat/responses JSON）的
-// 公共前缀求 SHA-256 派生稳定 key：system 提示、工具清单、instructions 与
-// 首个 user message 决定缓存前缀；assistant/tool 后续消息会随轮次变化，
+// 公共前缀求 SHA-256 派生稳定 key：system 提示、工具清单、instructions 稳定
+// 前缀与首个 user message 决定缓存前缀；assistant/tool 后续消息会随轮次变化，
 // 不参与哈希。同一份系统提示 + 工具栈在跨 launch 之间生成同一 key，让上游
 // 一致性哈希到同一 zen 缓存分片；前缀内容一旦改动则自然换 key，避免串污染。
+// instructions 只取稳定头（见 stableInstructionsHead）：实测 Claude Code 每轮
+// 在尾部追加 role=system 消息（59→77 段，+6KB），全量哈希会导致同会话每轮换
+// key、prefix-cache 归零；头 16 段跨轮逐段同哈希，是真正的稳定前缀。
 func contentPromptCacheKey(m map[string]any) string {
 	if m == nil {
 		return ""
 	}
-	// 采样：system 块、tools 形状、instructions、首个 user 消息文本——这些
-	// 是任何 agent 会话的稳定前缀；其它动态字段忽略。
+	// 采样：system 块、tools 形状、instructions 稳定头、首个 user 消息文本——
+	// 这些是任何 agent 会话的稳定前缀；其它动态字段忽略。
 	parts := []string{}
 	if sys, ok := m["system"]; ok {
 		b, _ := json.Marshal(sys)
 		parts = append(parts, "sys:"+string(b))
 	}
 	if instr, ok := m["instructions"].(string); ok && instr != "" {
-		parts = append(parts, "instr:"+instr)
+		parts = append(parts, "instr:"+stableInstructionsHead(instr))
 	}
 	if tools, ok := m["tools"].([]any); ok {
 		if b, err := json.Marshal(tools); err == nil {
@@ -2002,8 +2023,10 @@ func contentPromptCacheKey(m map[string]any) string {
 	if len(parts) == 0 {
 		return ""
 	}
+	sum := sha256.Sum256([]byte(strings.Join(parts, "\n")))
+	pck := "oc2api:csha:" + hex.EncodeToString(sum[:16])
 	if cacheDebugEnabled() {
-		attrs := []any{"parts", len(parts)}
+		attrs := []any{"parts", len(parts), "pck", pck}
 		for i, p := range parts {
 			idx := strings.Index(p, ":")
 			name, body := p, p
@@ -2012,9 +2035,38 @@ func contentPromptCacheKey(m map[string]any) string {
 			}
 			attrs = append(attrs, fmt.Sprintf("part%d", i), name+"="+hashTextPrefix(body))
 			attrs = append(attrs, fmt.Sprintf("part%d_len", i), len(body))
+			if name == "instr" {
+				// part0 已是稳定头（stableInstructionsHead 截断后），full 长度
+				// 需从原始请求体另取：m["instructions"] 即原文。
+				if full, _ := m["instructions"].(string); full != "" {
+					attrs = append(attrs, "instr_full_len", len(full))
+					attrs = append(attrs, "instr_full_segs", len(strings.Split(full, "\n\n")))
+				}
+				segs := strings.Split(body, "\n\n")
+				attrs = append(attrs, "instr_segs", len(segs))
+				// 头 16 + 尾 16:Claude 侧 instructions = system 参数 +
+				// role=system 消息 join,膨胀段常在尾部,32 上限截断后看不见。
+				// 只记哈希前缀+长度,不记原文。
+				emit := func(si int) {
+					attrs = append(attrs, fmt.Sprintf("instr_seg%d", si), hashTextPrefix(segs[si]))
+					attrs = append(attrs, fmt.Sprintf("instr_seg%d_len", si), len(segs[si]))
+				}
+				n := len(segs)
+				for si := 0; si < n && si < 16; si++ {
+					emit(si)
+				}
+				if n > 32 {
+					for si := n - 16; si < n; si++ {
+						emit(si)
+					}
+				} else {
+					for si := 16; si < n && si < 32; si++ {
+						emit(si)
+					}
+				}
+			}
 		}
 		slog.Info("cache_debug_key_parts", attrs...)
 	}
-	sum := sha256.Sum256([]byte(strings.Join(parts, "\n")))
-	return "oc2api:csha:" + hex.EncodeToString(sum[:16])
+	return pck
 }

internal/app/main_test.go

@@ -339,6 +339,50 @@ func TestPromptCacheKeyRecomputedAfterFingerprint(t *testing.T) {
 	}
 }
 
+func TestContentPromptCacheKey_StableHeadIgnoresAppendedTail(t *testing.T) {
+	// 实测 Claude Code 每轮在 instructions 尾部追加 role=system 消息
+	// （59→77 段，+6KB），全量哈希会导致同会话每轮换 key、prefix-cache 归零。
+	// key 只取前 stableInstrHeadSegs 段：尾部追加不换 key，头部改动仍换 key。
+	mkSegs := func(n int, prefix string) string {
+		segs := make([]string, n)
+		for i := range segs {
+			segs[i] = prefix + "_seg_" + string(rune('a'+i%26)) + "_body_padding_for_length"
+		}
+		return strings.Join(segs, "\n\n")
+	}
+	head := mkSegs(stableInstrHeadSegs, "stable")
+	body := func(instr string) map[string]any {
+		return map[string]any{
+			"model":        "muse-spark-1.3-contributor-free",
+			"instructions": instr,
+			"tools":        []any{map[string]any{"type": "function", "name": "Bash"}},
+			"input": []any{
+				map[string]any{"role": "user", "content": []any{
+					map[string]any{"type": "input_text", "text": "hi"},
+				}},
+			},
+		}
+	}
+	base := contentPromptCacheKey(body(head))
+	appended := contentPromptCacheKey(body(head + "\n\n" + mkSegs(18, "appended_tail")))
+	if base == "" || appended == "" {
+		t.Fatalf("keys must be non-empty: base=%q appended=%q", base, appended)
+	}
+	if base != appended {
+		t.Fatalf("tail append changed key: base=%q appended=%q", base, appended)
+	}
+	// 头部改动必须换 key（避免串污染）。
+	mutated := contentPromptCacheKey(body(mkSegs(stableInstrHeadSegs, "other") + "\n\ntail"))
+	if mutated == base {
+		t.Fatalf("head mutation must change key: %q", mutated)
+	}
+	// 短 instructions（不足 N 段）不截断：行为与原来一致。
+	short := "only one segment"
+	if got := stableInstructionsHead(short); got != short {
+		t.Fatalf("short instr truncated: %q", got)
+	}
+}
+
 func TestCallOpenCodeAPIKeyedAuthDoesNotCrossModelFallback(t *testing.T) {
 	tests := []struct {
 		name   string