perf(api): SSE 分块 C 导航层 + 差分等价验收（实测更慢 ⇒ 默认关闭）

第三刀：把 ha_json_scan 接进 parseOpenAICompatibleStreamChunkFull。 **结论是否定的** —— 实测比原实现慢，故默认关闭并如实记录。这条提交的价值在于「已钉死的正确性 + 已定位的根因 + 一条防静默回退的断言」。 ## 设计：只做「结构导航」，序列化留在 Go 接线前实测出两条 wire 语义，它们让「整条解析全 C 化」不成立： §5.1 重复键是**字段级合并**，不是替换： {"choices":[{content:a}],"choices":[{reasoning:r}]} → 两个都保留。机制：json.Unmarshal 的 object() 收尾做 v.SetIndex(i, subv.v)，而 subv 拿到的是**已存在元素的指针** ⇒ 第二次是叠加。 §5.2 stringifyContent 的 default 分支 = json.Marshal(interface{})，即**重新序列化**：{"b":1,"a":2}→{"a":2,"b":1}（键排序）、 1e2→100、<→\u003c、大 int 先舍入成 float64。逐值一致 = 复刻 Ryu 最短浮点 + map 键排序 + HTML 转义 + int 舍入。两条都只在**取值**阶段需要，故 C 只回答「值在哪里」（零分配零解码），类型检查靠「用相同的 Go 类型 unmarshal 相同形状的子树」保证，不靠 C 复刻规则。 ## 实测：新路径比原实现慢（20000 次迭代） | 场景 | 新路径 | 原实现 | |---|---|---| | content_ascii | 2016ns / 20allocs | 1325ns / 13allocs | | toolcall | 5854ns / 33allocs | 3270ns / 21allocs | | usage | 3170ns / 24allocs | 2832ns / 12allocs | 分配数**也变多**（20 vs 13），与「消除 GC 抖动」的初衷相反。根因（逐项测量，非猜测）：裸 cgo 调用 168ns；**每次带 out-param 的键查找 205ns + 2 allocs**（out-param 逃逸到堆）；一次解析需要 5+ 次查找 ⇒ 边界与分配成本约 1µs，恰好吃掉全部收益。Go 侧只需**一次** Unmarshal。一句话：**用很多次廉价调用换一次昂贵调用，在这个尺寸上不划算。** ## 天花板实验：方向对，但当前实现没到假设拿到 span 完全免费，只测设计中必须由 Go 做的部分：我的 Go 侧 505ns/7allocs vs 原实现 1239ns/13allocs ⇒ 边界归零后仍有 2.4× 时间、46% 分配的空间。故问题在**逐字段往返** 这个交互方式，不在 C 本身。正确改造：一次调用返回全部字段 span + 结果写调用方栈结构体 + 仅在确需重新编码时回退。 ## 正确性：6 万+ 差分用例全过同一批输入跑两条路径逐字段比对（Content/Reasoning/Done/Finish/ToolCalls/ Usage + bool），5 组：协议形态（含全部回退触发条件）、真实负载、随机 JSON 30000 例、随机字节 30000 例、优化有效性。 ★ 差分测试当场抓出 4 个真实缺陷（其中一个正是「优化压根没生效」）： 1. ha_sse_arr_first 里「重新 init 到 sc.s+sc.i」使 base 变了 ⇒ start 恒 0 ⇒ 返回的是**数组本身**而非首元素。症状是**快速路径永远不生效**—— 而若只看「结果与 Go 一致」，这个 bug 会**完全隐形**（回退总是对的）。 ⇒ 这就是必须单独断言「优化确实被走到」的原因。 2. chunkAssemble 的 bool 被丢弃 ⇒ 空对象被判 true（原实现 false） 3. 键匹配层级搞错：delta 是 **struct**（字段名 CI），不是 map。我一度「推理」成 CS 并以为差分测试会通过——错的。教教训：哪层是 struct、哪层是 map 要**回原实现读类型**，不能凭字段名推断。 4. cgo 边界：out-param 逃逸到堆另修：C 代码从 cgo 前言移进 csrc/ ——前言里的 C **逃出全部 C 门禁** （告警/sanitizer/交叉/模糊测试），而它恰是本刀最易出错处。 ## 防静默回退 TestChunkFast_BenchGate 断言 chunkFastEnabled 必须为 false。后来者看到「快速路径写得全 + 差分测试全过」，很自然会以为它已生效并打开它 —— 而实测更慢。断言把这个事实钉住，改动即判红。 ## 实测汇总 - C 契约 119 项断言、黄金对照 5 组、差分 6 万+ 例：全过 - ASan+UBSan PASS；gcc+clang 零告警；arm64 交叉 0 告警（3 个源文件） - 全量 go test -count=1 ./... 38 包 ok / 0 FAIL - libFuzzer 4948 万次零崩溃（上一刀）教训（与第一刀同源）：**「C 比 Go 快」不是前提，是待验证的假设。** 第一刀被 C.CString 的 82% 自找开销推翻一次，这一刀被逐字段往返推翻一次。两次都是测量推翻直觉。
2026-10-03 07:43:58 +00:00 · 2026-09-26 10:32:20 +08:00
parent 2b78a9288e
commit bf8a01fb67
10 changed files with 1703 additions and 77 deletions
--- a/internal/agent/api/provider.go
+++ b/internal/agent/api/provider.go
@ -625,31 +625,41 @@ func normalizeStreamToolCalls(raw []openAIToolCall) []ToolCall {
 	}
 	out := make([]ToolCall, 0, len(raw))
 	for _, tc := range raw {
-		name := tc.Function.Name
-		argsRaw := tc.Function.Arguments
-		if name == "" {
-			name = tc.Name
-			// 仅当顶层 Arguments 存在才用扁平格式；否则保留 function.arguments 嵌套值
-			// （OpenAI 流式续传 chunk：name 不重发但 function.arguments 继续）
-			if tc.Arguments != nil {
-				argsRaw = tc.Arguments
-			}
-		}
-		typ := tc.Type
-		if typ == "" && (tc.ID != "" || name != "" || argsRaw != nil) {
-			typ = "function"
-		}
-		out = append(out, ToolCall{
-			ID:           tc.ID,
-			Type:         typ,
-			Name:         name,
-			RawArguments: rawArgsString(argsRaw),
-			StreamIndex:  tc.Index,
-		})
+		out = append(out, normalizeStreamToolCall(tc))
 	}
 	return out
 }

+// normalizeStreamToolCall 是单元素的归一化逻辑。
+//
+// ★ 之所以从循环里抽成单元素函数：C 快速路径逐元素处理（而不是整块
+// unmarshal 成 []openAIToolCall），必须与本函数**共用**同一份归一化逻辑，
+// 否则两条路径会在「name 回退 / type 补全 / arguments 取哪一份」这些
+// 条件分支上分叉。抽出后循环与快速路径都调它，结构上无法分叉。
+func normalizeStreamToolCall(tc openAIToolCall) ToolCall {
+	name := tc.Function.Name
+	argsRaw := tc.Function.Arguments
+	if name == "" {
+		name = tc.Name
+		// 仅当顶层 Arguments 存在才用扁平格式；否则保留 function.arguments 嵌套值
+		// （OpenAI 流式续传 chunk：name 不重发但 function.arguments 继续）
+		if tc.Arguments != nil {
+			argsRaw = tc.Arguments
+		}
+	}
+	typ := tc.Type
+	if typ == "" && (tc.ID != "" || name != "" || argsRaw != nil) {
+		typ = "function"
+	}
+	return ToolCall{
+		ID:           tc.ID,
+		Type:         typ,
+		Name:         name,
+		RawArguments: rawArgsString(argsRaw),
+		StreamIndex:  tc.Index,
+	}
+}
+
 func parseToolArguments(v interface{}) map[string]interface{} {
 	switch x := v.(type) {
 	case nil:
@ -705,64 +715,32 @@ func stringifyContent(v interface{}) string {
 // 兼容多种 token 用量键名（prompt_tokens/prompt、total_tokens/total 等）
 // 与 prompt cache 细节字段。返回 false 表示非内容块（纯 usage 心跳等）。
 func parseOpenAICompatibleStreamChunkFull(data string) (StreamChunk, bool) {
-	var raw struct {
-		Choices []struct {
-			Delta struct {
-				Content          interface{}      `json:"content"`
-				ReasoningContent string           `json:"reasoning_content"`
-				ToolCalls        []openAIToolCall `json:"tool_calls"`
-			} `json:"delta"`
-			FinishReason *string `json:"finish_reason"`
-		} `json:"choices"`
-		UpstreamUsage struct {
-			PromptTokens        int `json:"prompt_tokens"`
-			CompletionTokens    int `json:"completion_tokens"`
-			TotalTokens         int `json:"total_tokens"`
-			Prompt              int `json:"prompt"`
-			Completion          int `json:"completion"`
-			Total               int `json:"total"`
-			PromptCacheHit      int `json:"prompt_cache_hit_tokens"`
-			PromptCacheMiss     int `json:"prompt_cache_miss_tokens"`
-			PromptTokensDetails *struct {
-				CachedTokens int `json:"cached_tokens"`
-			} `json:"prompt_tokens_details"`
-		} `json:"usage"`
-	}
-	if err := json.Unmarshal([]byte(data), &raw); err != nil {
-		return StreamChunk{}, false
-	}
-
-	var usage *TokenUsage
-	pu := raw.UpstreamUsage
-	if pu.Total > 0 || pu.TotalTokens > 0 || pu.Prompt > 0 || pu.PromptTokens > 0 {
-		usage = &TokenUsage{
-			Prompt:     pickFirstInt(pu.PromptTokens, pu.Prompt),
-			Completion: pickFirstInt(pu.CompletionTokens, pu.Completion),
-			Total:      pickFirstInt(pu.TotalTokens, pu.Total),
+	// ★ C 快速路径（结构导航）：定位在 C（零分配、零解码），类型检查与
+	//   需要重新序列化的形态交回 Go 的 encoding/json。
+	//
+	//   契约：必须与 chunkParseGo 对所有输入产出完全相同的结果。
+	//   保证方式见 codec_chunkfast_c.go 顶部：任一环节「不确定」即**整体回退**
+	//   chunkParseGo，且拼装/归一化两条路径**共用**同一份代码。
+	//
+	//   为什么保留 Go 实现：它既是回退目标，也是黄金对照的参照实现 ——
+	//   没有它，「C 化没坏」就只是感觉而不是证据。
+	//
+	// ★ 开关：chunkFastEnabled 目前为 false —— 实测本架构比原实现**慢**
+	//   （2016ns/20allocs vs 1325ns/13allocs），根因是「5+ 次 cgo 边界
+	//   × 每次 ~200ns」吃掉了收益。详见 codec_chunkfast_c.go 的说明与
+	//   docs/zh/c-core/sse-codec-c.md §六。改造方向已由天花板实验确认可行。
+	if chunkFastEnabled {
+		if ck, handled, decided := chunkParseFast(data); handled && decided {
+			return ck, true
 		}
 	}
+	return chunkParseGo(data)
+}

-	if len(raw.Choices) == 0 {
-		// 纯 usage 心跳块：有 usage 就透传，否则丢弃
-		if usage != nil {
-			return StreamChunk{Usage: usage}, true
-		}
-		return StreamChunk{}, false
-	}
-
-	choice := raw.Choices[0]
-	ck := StreamChunk{
-		Content:          stringifyContent(choice.Delta.Content),
-		ReasoningContent: choice.Delta.ReasoningContent,
-		ToolCalls:        normalizeStreamToolCalls(choice.Delta.ToolCalls),
-		Usage:            usage,
-	}
-	// finish reason 为空字符串不算终止信号（sensenova 每块都发 ""）
-	if choice.FinishReason != nil && *choice.FinishReason != "" {
-		ck.Done = true
-		ck.FinishReason = *choice.FinishReason
-	}
-	return ck, true
+// parseOpenAICompatibleStreamChunkFullGo 供黄金对照测试直接调原始实现，
+// 用于验证快速路径与它逐值等价。
+func parseOpenAICompatibleStreamChunkFullGo(data string) (StreamChunk, bool) {
+	return chunkParseGo(data)
 }

 // pickFirstInt 返回 a 非零时的 a，否则 b（兼容 *_tokens 与短键名两种 usage 格式）。
@ -772,7 +750,6 @@ func pickFirstInt(a, b int) int {
 	}
 	return b
 }
-
 // streamHTTPClient 返回专用的流式 HTTP client（懒初始化）。
 // SSE 长连接不能套整体超时（非流式 180s 会在长流中途报断），
 // 只保留拨号/握手超时。