diff --git a/Makefile b/Makefile
index f5b66e3..01fc7ac 100644
--- a/Makefile
+++ b/Makefile
@@ -132,20 +132,35 @@ install: build
 test:
 	$(GO) test ./...
 	@$(MAKE) csrc-test
-	@$(MAKE) check-codec-paths
+	@$(MAKE) check-codec-cgo-only
 
-# check-codec-paths：钉死「C 实现与纯 Go 回退都在、且行为等价」。
+# check-codec-cgo-only：钉死「编解码层完全 C 化」这一决定。
 #
-# 为何必须显式测两条：homed 走 cgo（C 路径），而 waiter 等 CGO-free 目标走回退。
-# 只测一条，另一条的破坏不会被发现；而两条路径的语义等价是 C 化的核心约束
-# （见 internal/agent/api/codec_golden_test.go）。
-.PHONY: check-codec-paths
-check-codec-paths:
-	@echo "== 编解码双路径检查 =="
+# 两条断言，缺一不可：
+#   ① CGO_ENABLED=1 下测试全绿（含黄金对照：C 与纯 Go 参考实现逐值相等）
+#   ② CGO_ENABLED=0 下**构建必须失败**
+#
+# 为什么②要断言「失败」而不是「也能编过」：内核已完全 C 化，C 是唯一实现。
+# 若有人在 CGO_ENABLED=0 下让整包静默编过（例如加回一个纯 Go 回退），
+# 就会同时存在两份语义可能分叉的实现 —— 而 C 侧对畸形 UTF-8 的解码边界
+# 一旦与 Go 分叉，只表现为 rune 计数偏差（进而 token 预算与截断点偏移），
+# **不会立刻暴露**。所以这里把「不许有第二条路」变成可执行的断言。
+#
+# 注：这不影响任何现有构建 —— waiter/initconfig/memgc 均不依赖本包
+# （go list -deps 实测）；homed 本就强制 cgo。
+.PHONY: check-codec-cgo-only
+check-codec-cgo-only:
+	@echo "== 编解码层：完全 C 化检查 =="
 	@CGO_ENABLED=1 $(GO) test -count=1 ./internal/agent/api/ \
-		&& echo "  cgo / C 实现路径: OK"
-	@CGO_ENABLED=0 $(GO) test -count=1 ./internal/agent/api/ \
-		&& echo "  !cgo / 纯 Go 回退: OK"
+		&& echo "  ① cgo 下测试全绿（含黄金对照）: OK"
+	@if CGO_ENABLED=0 $(GO) build ./internal/agent/api/ 2>/dev/null; then \
+		echo "  [FAIL] CGO_ENABLED=0 下本包竟然构建成功——"; \
+		echo "         编解码层已完全 C 化，不该存在第二条实现路径。"; \
+		echo "         若是有意引入回退，请同时更新本检查与 codec_cgo.go 的说明。"; \
+		exit 1; \
+	else \
+		echo "  ② CGO_ENABLED=0 下响亮失败（防静默回退）: OK"; \
+	fi
 
 run: build
 	./$(BUILD_DIR)/$(BINARY) -data /tmp/homeagent
diff --git a/csrc/include/ha_codec.h b/csrc/include/ha_codec.h
index 2358364..0ddf49a 100644
--- a/csrc/include/ha_codec.h
+++ b/csrc/include/ha_codec.h
@@ -9,12 +9,21 @@
  * 修改必须走大版本流程（与 third_party/homeagent-sdk 同一冻结标准）。
  *
  * 设计约束（见 docs/zh/c-core/llm-orchestration-c.md §四）：
- *   1. 只吃 const char* + 长度，出数值/JSON 串
- *   2. 不回调 Go、不传 Go 指针
- *   3. 不长期持有 malloc 内存；需要出参的用调用方缓冲区
- *   4. 无状态、纯函数、线程安全（不写全局可变状态）
+ *   1. 只吃 const char* + **显式长度**，出数值/字节偏移 —— 不回调 Go、
+ *      不传 Go 指针、不要求 NUL 结尾
+ *   2. **不 malloc**：不需要出参缓冲区，需要「结果」时返回字节偏移/长度，
+ *      由调用方在自己的缓冲上切片（零拷贝）
+ *   3. 无状态、纯函数、线程安全（不写全局可变状态）
  *
  * 当前覆盖：L1 协议编解码层中的纯计算部分（第一个最小切片）。
+ *
+ * ============================ 为什么签名带长度 ============================
+ * 初版签名用 `const char*` 隐含「NUL 结尾」，于是每次调用都要：
+ *   Go `C.CString` 分配+拷贝一遍 → C `strlen` 再扫一遍。
+ * 实测这部分开销占单次调用的 80% 以上（cgo 边界本身仅 ~30ns，
+ * 而初版 ModelContextWindow 实测 175ns）。
+ * 改为「指针 + 长度」后，Go 侧用 unsafe.StringData 直接传底层数组，
+ * 零分配零拷贝。这是设计约束第 1 条的字面要求。
  */
 
 #include <stddef.h>
@@ -34,31 +43,41 @@ extern "C" {
 #define HA_CODEC_CONTEXT_WINDOW_UNKNOWN (-1)
 
 /* 由模型名推断最大上下文窗口（token 数）；推断不出返回
- * HA_CODEC_CONTEXT_WINDOW_UNKNOWN。model 为 NULL 时同样返回 UNKNOWN。
+ * HA_CODEC_CONTEXT_WINDOW_UNKNOWN。
+ *
+ * model 为 UTF-8 字节序列，**不需要 NUL 结尾**；model_len 是字节数。
+ * model 为 NULL 或 model_len 为 0 时返回 UNKNOWN。
+ *
+ * 匹配大小写不敏感（仅对 ASCII 字母做折叠；非 ASCII 字节按原样比较，
+ * 与 Go 侧对模型名的实际输入一致）。
  *
- * model 为 UTF-8 字符串，匹配大小写不敏感。
  * 语义必须与 Go 侧 modelContextWindowPure 逐值一致（黄金对照测试钉死）。 */
-int ha_codec_model_context_window(const char *model);
+int ha_codec_model_context_window(const char *model, size_t model_len);
 
 /* ==================== token 估算与截断 ==================== */
 
 /* 粗略估算 token 数。
  *
- * 规则（与 Go 侧 EstimateTokens 一致）：中文 ~1.5 token/字、英文 ~0.3 token/字符，
- * 保守取 max(1, runeCount * 2)。text 为 NULL 或空串返回 0。
+ * 规则（与 Go 侧 EstimateTokens 一致）：保守取 max(1, runeCount * 2)。
+ * 按 UTF-8 **字符数**（rune）计，不是字节数。
+ * text 为 NULL 或 text_len 为 0 返回 0。
  *
- * 注意：按 UTF-8 **字符数**（rune）计，不是字节数。 */
-int ha_codec_estimate_tokens(const char *text);
+ * 非法 UTF-8 序列按 Go 的 utf8 解码语义处理（每字节一个 rune），
+ * 保证与 Go 侧逐值一致。 */
+int ha_codec_estimate_tokens(const char *text, size_t text_len);
 
-/* 截断字符串至不超过 maxTokens 估计值，返回写入 out 的字节数（不含结尾 NUL）。
+/* 按 token 预算计算「应保留的字节数」。
  *
- * 语义与 Go 侧 TruncateByTokens 一致：从开头保留 maxTokens/2 个字符。
- * maxTokens <= 0 或 text 为空时写入空串。
+ * ★ 返回的是**字节数**而非字符串：截断结果必然是输入的前缀，
+ *   调用方直接在自己的缓冲上切片即可（零拷贝、无出参缓冲区、无 malloc）。
  *
- * out 由调用方提供，容量须为 outCap（含结尾 NUL）；函数保证 NUL 结尾、
- * 不越界写。返回值是实际写入的字节数（可能因 outCap 不足而短于完整截断结果）。 */
-size_t ha_codec_truncate_by_tokens(const char *text, int max_tokens,
-                                   char *out, size_t out_cap);
+ * 语义与 Go 侧 TruncateByTokens 一致：从开头保留 maxTokens/2 个 rune；
+ * 未超预算时返回 text_len（即整串）。
+ * max_tokens <= 0 或 text 为 NULL/text_len 为 0 时返回 0。
+ *
+ * 返回值保证 <= text_len。 */
+size_t ha_codec_truncate_by_tokens(const char *text, size_t text_len,
+                                   int max_tokens);
 
 #ifdef __cplusplus
 }
diff --git a/csrc/src/ha_codec.c b/csrc/src/ha_codec.c
index 7d80181..426cc05 100644
--- a/csrc/src/ha_codec.c
+++ b/csrc/src/ha_codec.c
@@ -1,132 +1,289 @@
 /*
  * ha_codec.c — HomeAgent 内核编解码层（C 实现）
  *
- * 第一个最小切片：模型窗口推断 + token 估算/截断。
- * 语义必须与 Go 侧实现逐值一致，由黄金对照测试钉死。
+ * ============================ 性能设计（勿回退）============================
+ *   1. **不 malloc**：模型名折叠用栈缓冲（短名走快路径，超长走零分配的回退）。
+ *   2. **不 strlen**：长度由调用方传入（见 ha_codec.h 签名说明）。
+ *   3. **ASCII 批量快路径**：连续 ASCII 成批计数，避免逐字节函数调用。
+ *   4. **截断提前短路**：数满 keep 个 rune 立即返回，不扫完整串。
+ *   5. **截断返回字节数**而非字符串：结果必然是输入前缀，调用方自己切片。
+ *
+ * 初版的三个反例（实测代价，见 docs/zh/c-core/llm-orchestration-c.md §7.1）：
+ *   - Go 侧 C.CString（malloc+拷贝）＋ C 侧 strlen，单这一项约 75ns，
+ *     而 cgo 边界本身仅约 32ns —— 即 **82% 的开销是自找的**，不是 cgo 的成本。
+ *     初版由此得出「C 比 Go 慢」的结论是错的。
+ *   - 逐字节 utf8_next 函数调用 ⇒ 1KB ASCII 比纯 Go 慢 7 倍。
+ *   - 1KB 中文要先扫完整串才判断是否截断。
+ *
+ * 语义必须与 Go 侧实现逐值一致，由黄金对照测试钉死（含畸形 UTF-8）。
  */
 
 #include "ha_codec.h"
 
-#include <ctype.h>
-#include <stdlib.h>
+#include <stdint.h>
 #include <string.h>
 
 /* ---------------------------------------------------------------- */
-/* 小工具                                                            */
+/* 大小写不敏感的子串匹配                                            */
 /* ---------------------------------------------------------------- */
 
-/* 在 s 中查找子串 sub（子串已小写）。s 需已是小写。找不到返回 NULL。 */
-static const char *find_sub(const char *s, const char *sub) {
-    return strstr(s, sub);
+/* 只折 ASCII 字母；非 ASCII 字节原样（与 Go strings.ToLower 对模型名的
+ * 实际效果一致——模型名都是 ASCII，中文/日文字节不受 ToLower 影响）。 */
+static unsigned char ascii_lower(unsigned char c) {
+    return (c >= 'A' && c <= 'Z') ? (unsigned char)(c + 32) : c;
 }
 
-/* 分配一份小写副本。调用方负责 free。失败返回 NULL。 */
-static char *lower_dup(const char *s) {
-    if (s == NULL) {
-        return NULL;
+/* 已折叠缓冲（长度 hn）中是否含子串 sub（sub 必须已小写、ASCII）。
+ * memcmp 版本：折叠一次后可向量化比较，是短名快路径。 */
+static int contains(const char *m, size_t hn, const char *sub) {
+    size_t m_len = strlen(sub);
+    if (m_len == 0 || hn < m_len) {
+        return 0;
     }
-    size_t n = strlen(s);
-    char *p = (char *)malloc(n + 1);
-    if (p == NULL) {
-        return NULL;
+    size_t last = hn - m_len;
+    for (size_t i = 0; i <= last; i++) {
+        /* 首字节过滤掉绝大多数位置，避免无谓 memcmp */
+        if (m[i] == sub[0] && memcmp(m + i, sub, m_len) == 0) {
+            return 1;
+        }
     }
-    for (size_t i = 0; i < n; i++) {
-        /* 只对 ASCII 做小写；UTF-8 多字节原样保留（与 Go strings.ToLower 对
-         * 中文不改变结果一致——Go 会把非 ASCII 也处理，但模型名都是 ASCII）。 */
-        unsigned char c = (unsigned char)s[i];
-        p[i] = (char)((c < 0x80) ? tolower(c) : c);
+    return 0;
+}
+
+/* 边比较边折叠：**任意长度**都正确，无需缓冲（超长模型名的回退路径）。
+ * sub 中的 ASCII 字母按小写处理；非 ASCII 字节按字节精确比较
+ * （因此可直接用于 "\xe9\x9b\xb6\xe4\xb8\x80" 这类多字节字面量）。 */
+static int contains_ci(const char *h, size_t hn, const char *sub) {
+    size_t m_len = strlen(sub);
+    if (m_len == 0 || hn < m_len) {
+        return 0;
     }
-    p[n] = '\0';
-    return p;
+    size_t last = hn - m_len;
+    for (size_t i = 0; i <= last; i++) {
+        size_t j = 0;
+        while (j < m_len &&
+               ascii_lower((unsigned char)h[i + j]) == (unsigned char)sub[j]) {
+            j++;
+        }
+        if (j == m_len) {
+            return 1;
+        }
+    }
+    return 0;
+}
+
+/* 模型名的不可变视图：能进栈缓冲就折叠，否则按原样（用 contains_ci 匹配）。 */
+typedef struct {
+    const char *p;
+    size_t n;
+    int folded;
+} model_view;
+
+/* 栈缓冲容量：模型名实测都是几十字节。超出则退化为不折叠 +
+ * contains_ci —— 仍**零分配且语义正确**，只是少了 memcmp 的向量化优势。 */
+#define HA_MODEL_STACK 256
+
+static int mv_contains(const model_view *v, const char *sub) {
+    return v->folded ? contains(v->p, v->n, sub) : contains_ci(v->p, v->n, sub);
 }
 
 /* ---------------------------------------------------------------- */
 /* 模型上下文窗口推断                                                */
 /* ---------------------------------------------------------------- */
 
-int ha_codec_model_context_window(const char *model) {
-    if (model == NULL) {
+int ha_codec_model_context_window(const char *model, size_t model_len) {
+    if (model == NULL || model_len == 0) {
         return HA_CODEC_CONTEXT_WINDOW_UNKNOWN;
     }
 
-    char *m = lower_dup(model);
-    if (m == NULL) {
-        return HA_CODEC_CONTEXT_WINDOW_UNKNOWN;
+    char stack[HA_MODEL_STACK];
+    model_view v;
+    if (model_len < HA_MODEL_STACK) {
+        for (size_t i = 0; i < model_len; i++) {
+            stack[i] = (char)ascii_lower((unsigned char)model[i]);
+        }
+        stack[model_len] = '\0';
+        v.p = stack;
+        v.n = model_len;
+        v.folded = 1;
+    } else {
+        v.p = model;
+        v.n = model_len;
+        v.folded = 0;
     }
 
-    int result = HA_CODEC_CONTEXT_WINDOW_UNKNOWN;
-
     /* 顺序与 Go 侧 switch 分支**严格一致**：先匹配到的分支胜出。
-     * 这不是「随便一组 if」，顺序错了就会给出不同窗口。 */
-    if (find_sub(m, "deepseek-v4") || find_sub(m, "deepseek-v3")) {
-        result = 1048576;
-    } else if (find_sub(m, "deepseek-r1") || find_sub(m, "deepseek-chat")) {
-        result = 65536;
-    } else if (find_sub(m, "gpt-4") &&
-               (find_sub(m, "turbo") || find_sub(m, "mini") || find_sub(m, "omni"))) {
-        result = 128000;
-    } else if (find_sub(m, "gpt-4")) {
-        result = 8192;
-    } else if (find_sub(m, "gpt-3.5")) {
-        result = 16384;
-    } else if (find_sub(m, "claude-3.5") || find_sub(m, "claude-3")) {
-        result = 200000;
-    } else if (find_sub(m, "claude")) {
-        result = 100000;
-    } else if (find_sub(m, "gemini-1.5") || find_sub(m, "gemini-2")) {
-        result = 1048576;
-    } else if (find_sub(m, "gemini")) {
-        result = 32768;
-    } else if (find_sub(m, "qwen")) {
-        result = 131072;
-    } else if (find_sub(m, "glm") || find_sub(m, "chatglm")) {
-        result = 131072;
-    } else if (find_sub(m, "llama-3")) {
-        result = 8192;
-    } else if (find_sub(m, "llama-2")) {
-        result = 4096;
-    } else if (find_sub(m, "mistral") || find_sub(m, "mixtral")) {
-        result = 32768;
-    } else if (find_sub(m, "yi-") || find_sub(m, "零一")) {
-        result = 200000;
-    } else if (find_sub(m, "moonshot") || find_sub(m, "kimi")) {
-        result = 131072;
+     * 这不是「随便一组 if」，顺序错了就会给出不同窗口
+     * （例：gpt-4-turbo 必须先于裸 gpt-4 命中）。 */
+    if (mv_contains(&v, "deepseek-v4") || mv_contains(&v, "deepseek-v3")) {
+        return 1048576;
+    }
+    if (mv_contains(&v, "deepseek-r1") || mv_contains(&v, "deepseek-chat")) {
+        return 65536;
+    }
+    if (mv_contains(&v, "gpt-4")) {
+        if (mv_contains(&v, "turbo") || mv_contains(&v, "mini") || mv_contains(&v, "omni")) {
+            return 128000;
+        }
+        return 8192;
+    }
+    if (mv_contains(&v, "gpt-3.5")) {
+        return 16384;
+    }
+    if (mv_contains(&v, "claude-3.5") || mv_contains(&v, "claude-3")) {
+        return 200000;
+    }
+    if (mv_contains(&v, "claude")) {
+        return 100000;
+    }
+    if (mv_contains(&v, "gemini-1.5") || mv_contains(&v, "gemini-2")) {
+        return 1048576;
+    }
+    if (mv_contains(&v, "gemini")) {
+        return 32768;
+    }
+    if (mv_contains(&v, "qwen")) {
+        return 131072;
+    }
+    if (mv_contains(&v, "glm") || mv_contains(&v, "chatglm")) {
+        return 131072;
+    }
+    if (mv_contains(&v, "llama-3")) {
+        return 8192;
+    }
+    if (mv_contains(&v, "llama-2")) {
+        return 4096;
+    }
+    if (mv_contains(&v, "mistral") || mv_contains(&v, "mixtral")) {
+        return 32768;
+    }
+    /* "yi-" 与 "零一"（UTF-8 字面量）——contains_ci 对字节精确比较，
+     * 故中文部分不受折叠影响，与 Go 的 strings.Contains 一致。 */
+    if (mv_contains(&v, "yi-") || mv_contains(&v, "\xe9\x9b\xb6\xe4\xb8\x80")) {
+        return 200000;
+    }
+    if (mv_contains(&v, "moonshot") || mv_contains(&v, "kimi")) {
+        return 131072;
     }
 
-    free(m);
-    return result;
+    return HA_CODEC_CONTEXT_WINDOW_UNKNOWN;
+}
+
+/* ---------------------------------------------------------------- */
+/* UTF-8 解码（与 Go utf8.DecodeRuneInString 逐值等价）               */
+/* ---------------------------------------------------------------- */
+
+/* 返回 s[0] 起始字符的字节长度（1..4）。
+ *
+ * 必须与 Go 的 utf8.DecodeRuneInString 语义一致——**包括无效序列只前进
+ * 1 字节**（Go 对无效/截断序列返回 RuneError 且 size=1），否则 rune 计数
+ * 会与 Go 分叉。这正是黄金对照测试用畸形输入能抓到的地方。
+ *
+ * remaining 是当前可读字节数。 */
+static inline size_t utf8_char_len(const char *s, size_t remaining) {
+    unsigned char c0 = (unsigned char)s[0];
+
+    if (c0 < 0x80) {
+        return 1; /* ASCII */
+    }
+    if (c0 < 0xC2) {
+        return 1; /* 0x80..0xC1：续字节或过长编码 → Go 判无效，size=1 */
+    }
+
+    if (c0 < 0xE0) { /* 2 字节：0xC2..0xDF */
+        if (remaining < 2) {
+            return 1;
+        }
+        if (((unsigned char)s[1] & 0xC0) != 0x80) {
+            return 1;
+        }
+        return 2;
+    }
+
+    if (c0 < 0xF0) { /* 3 字节：0xE0..0xEF */
+        if (remaining < 3) {
+            return 1;
+        }
+        /* 用 (c & 0xC0) == 0x80 走单条 AND+CMP（而非两条范围比较），
+         * 并用 & 而非 && 避免短路分支——这是 CJK 主路径，须最短。 */
+        unsigned char c1 = (unsigned char)s[1];
+        unsigned char c2 = (unsigned char)s[2];
+        if (((c1 & 0xC0) == 0x80) & ((c2 & 0xC0) == 0x80)) {
+            /* 常见情形：既非 0xE0（防过长编码）也非 0xED（防代理对） */
+            if (c0 != 0xE0 && c0 != 0xED) {
+                return 3;
+            }
+            if ((c0 == 0xE0 && c1 >= 0xA0) || (c0 == 0xED && c1 <= 0x9F)) {
+                return 3;
+            }
+        }
+        return 1;
+    }
+
+    if (c0 < 0xF5) { /* 4 字节：0xF0..0xF4 */
+        if (remaining < 4) {
+            return 1;
+        }
+        unsigned char c1 = (unsigned char)s[1];
+        unsigned char c2 = (unsigned char)s[2];
+        unsigned char c3 = (unsigned char)s[3];
+        if (((c1 & 0xC0) == 0x80) & ((c2 & 0xC0) == 0x80) & ((c3 & 0xC0) == 0x80)) {
+            if (c0 != 0xF0 && c0 != 0xF4) {
+                return 4;
+            }
+            if ((c0 == 0xF0 && c1 >= 0x90) || (c0 == 0xF4 && c1 <= 0x8F)) {
+                return 4;
+            }
+        }
+        return 1;
+    }
+
+    return 1; /* 0xF5..0xFF：无效 */
+}
+
+/* ASCII 批量扫描：返回从 text[i] 起连续 ASCII 的字节数（扫到串尾）。
+ *
+ * ★ 字（word）级探测：一次读 8 字节，用单条掩码判断「8 字节是否全为 ASCII」。
+ *   逐字节比较会让 1KB ASCII 明显慢于纯 Go（后者内部有 8 字节快路径）。
+ *   实测：逐字节版 ascii_1k 约 2318ns（比 Go 慢 7×），改字级后大幅收敛。 */
+#define HA_HIGH_BITS 0x8080808080808080ULL
+
+static size_t ascii_run(const char *text, size_t i, size_t len) {
+    size_t j = i;
+    while (j + 8 <= len) {
+        uint64_t v;
+        memcpy(&v, text + j, 8); /* memcpy 让编译器按需生成未对齐安全加载 */
+        if (v & HA_HIGH_BITS) {
+            break;
+        }
+        j += 8;
+    }
+    while (j < len && (unsigned char)text[j] < 0x80) {
+        j++;
+    }
+    return j - i;
 }
 
 /* ---------------------------------------------------------------- */
 /* token 估算                                                        */
 /* ---------------------------------------------------------------- */
 
-/* 计 UTF-8 字符数（rune 数）并返回下一字符起点。
- * 非法字节按 1 字符前进（不吞字节），保证不会死循环。 */
-static size_t utf8_next(const char *s, size_t remaining) {
-    unsigned char c = (unsigned char)s[0];
-    size_t len = 1;
-    if (c >= 0xF0 && remaining >= 4) {
-        len = 4;
-    } else if (c >= 0xE0 && remaining >= 3) {
-        len = 3;
-    } else if (c >= 0xC0 && remaining >= 2) {
-        len = 2;
-    }
-    return len;
-}
-
-int ha_codec_estimate_tokens(const char *text) {
-    if (text == NULL || text[0] == '\0') {
+int ha_codec_estimate_tokens(const char *text, size_t text_len) {
+    if (text == NULL || text_len == 0) {
         return 0;
     }
 
-    size_t n = strlen(text);
     size_t runes = 0;
     size_t i = 0;
-    while (i < n) {
-        i += utf8_next(text + i, n - i);
-        runes++;
+    while (i < text_len) {
+        if ((unsigned char)text[i] < 0x80) {
+            size_t n = ascii_run(text, i, text_len);
+            runes += n;
+            i += n;
+        } else {
+            i += utf8_char_len(text + i, text_len - i);
+            runes++;
+        }
     }
 
     /* 与 Go 侧一致：t = runeCount * 2；t < 1 时取 1。
@@ -142,50 +299,39 @@ int ha_codec_estimate_tokens(const char *text) {
 }
 
 /* ---------------------------------------------------------------- */
-/* 按 token 截断                                                     */
+/* 按 token 预算计算应保留的字节数                                    */
 /* ---------------------------------------------------------------- */
 
-size_t ha_codec_truncate_by_tokens(const char *text, int max_tokens,
-                                   char *out, size_t out_cap) {
-    if (out == NULL || out_cap == 0) {
-        return 0;
-    }
-    out[0] = '\0';
-
-    if (max_tokens <= 0 || text == NULL || text[0] == '\0') {
+size_t ha_codec_truncate_by_tokens(const char *text, size_t text_len,
+                                   int max_tokens) {
+    if (text == NULL || text_len == 0 || max_tokens <= 0) {
         return 0;
     }
 
-    size_t n = strlen(text);
-
-    /* 先算 rune 数：与 Go 侧 len([]rune(s))*2 <= maxTokens 的短路一致 */
-    size_t runes = 0;
-    size_t i = 0;
-    while (i < n) {
-        i += utf8_next(text + i, n - i);
-        runes++;
-    }
-
-    /* 未超限：整体返回 */
-    if (runes <= (size_t)0x3FFFFFFF && (int)(runes * 2) <= max_tokens) {
-        size_t copy = (n < out_cap - 1) ? n : (out_cap - 1);
-        memcpy(out, text, copy);
-        out[copy] = '\0';
-        return copy;
-    }
-
-    /* 保留 maxTokens/2 个字符（与 Go 一致：keep := maxTokens / 2，整数除法） */
+    /* 要保留的 rune 数（与 Go 一致：整数除法）。keep==0 时循环首轮即返回 0。 */
     size_t keep = (size_t)(max_tokens / 2);
 
-    size_t byte_end = 0;
-    size_t kept = 0;
-    while (kept < keep && byte_end < n) {
-        byte_end += utf8_next(text + byte_end, n - byte_end);
-        kept++;
+    /* 提前短路：keep 个 rune 数满而串仍有剩余 ⇒ 必然截断，直接返回该字节边界，
+     * 不必扫完整串（长文本上的主要收益）。
+     * 若数完整串仍未数满 keep ⇒ 未超预算，返回全长（= 不截断）。 */
+    size_t runes = 0;
+    size_t i = 0;
+    while (i < text_len) {
+        if (runes == keep) {
+            return i;
+        }
+        if ((unsigned char)text[i] < 0x80) {
+            size_t n = ascii_run(text, i, text_len);
+            if (runes + n >= keep) {
+                /* keep 落在这批 ASCII 内：批内每字节一个 rune */
+                return i + (keep - runes);
+            }
+            runes += n;
+            i += n;
+        } else {
+            runes++;
+            i += utf8_char_len(text + i, text_len - i);
+        }
     }
-
-    size_t copy = (byte_end < out_cap - 1) ? byte_end : (out_cap - 1);
-    memcpy(out, text, copy);
-    out[copy] = '\0';
-    return copy;
+    return text_len; /* 未超预算：整串都留 */
 }
diff --git a/csrc/test/test_ha_codec.c b/csrc/test/test_ha_codec.c
index 9c887a5..9c5be4b 100644
--- a/csrc/test/test_ha_codec.c
+++ b/csrc/test/test_ha_codec.c
@@ -5,6 +5,9 @@
  *   gcc -std=c99 -I../include ../src/ha_codec.c test_ha_codec.c -o test_ha_codec && ./test_ha_codec
  *
  * 这一层钉死 C 实现的语义；与 Go 的逐值一致由黄金对照测试负责（双保险）。
+ *
+ * ★ 注意签名已改为「指针 + 长度」（见 ha_codec.h）：不再依赖 NUL 结尾，
+ *   截断返回字节数而非字符串。测试相应用 LIT()/LEN 辅助宏。
  */
 
 #include "ha_codec.h"
@@ -15,6 +18,9 @@
 static int g_fail = 0;
 static int g_pass = 0;
 
+/* 字面量 → (指针, 长度)：避免每处手写 sizeof-1。 */
+#define LIT(s) (s), (sizeof(s) - 1)
+
 static void check_int(const char *what, int got, int want) {
     if (got != want) {
         printf("  [FAIL] %s: got %d, want %d\n", what, got, want);
@@ -24,101 +30,175 @@ static void check_int(const char *what, int got, int want) {
     }
 }
 
-static void check_str(const char *what, const char *got, const char *want) {
-    if (strcmp(got, want) != 0) {
-        printf("  [FAIL] %s: got \"%s\", want \"%s\"\n", what, got, want);
+/* 断言「截断得到的字节数」确实是原文前缀，且正好是期望的字节长度。 */
+static void check_trunc_prefix(const char *what, const char *text, size_t len,
+                               int max_tokens, size_t want_bytes) {
+    size_t got = ha_codec_truncate_by_tokens(text, len, max_tokens);
+    if (got != want_bytes) {
+        printf("  [FAIL] %s: got %zu bytes, want %zu\n", what, got, want_bytes);
         g_fail++;
-    } else {
-        g_pass++;
+        return;
     }
+    if (got > len) {
+        printf("  [FAIL] %s: 返回值 %zu 超出输入长度 %zu\n", what, got, len);
+        g_fail++;
+        return;
+    }
+    g_pass++;
 }
 
-static void check_size(const char *what, size_t got, size_t want) {
-    if (got != want) {
-        printf("  [FAIL] %s: got %zu, want %zu\n", what, got, want);
+/* 字节级断言：截断结果的字节内容必须与期望字符串逐字节相等。 */
+static void check_trunc_bytes(const char *what, const char *text, size_t len,
+                              int max_tokens, const char *want) {
+    size_t got = ha_codec_truncate_by_tokens(text, len, max_tokens);
+    size_t want_len = strlen(want);
+    if (got != want_len) {
+        printf("  [FAIL] %s: got %zu bytes, want %zu\n", what, got, want_len);
         g_fail++;
-    } else {
-        g_pass++;
+        return;
     }
+    if (got > 0 && memcmp(text, want, got) != 0) {
+        printf("  [FAIL] %s: 字节内容不匹配\n", what);
+        g_fail++;
+        return;
+    }
+    g_pass++;
 }
 
 static void test_context_window(void) {
     printf("model_context_window:\n");
     check_int("deepseek-v4.1-flash",
-              ha_codec_model_context_window("deepseek/deepseek-v4.1-flash"), 1048576);
+              ha_codec_model_context_window(LIT("deepseek/deepseek-v4.1-flash")), 1048576);
     check_int("deepseek-v4-flash",
-              ha_codec_model_context_window("deepseek-v4-flash"), 1048576);
+              ha_codec_model_context_window(LIT("deepseek-v4-flash")), 1048576);
     check_int("deepseek-chat",
-              ha_codec_model_context_window("deepseek-chat"), 65536);
+              ha_codec_model_context_window(LIT("deepseek-chat")), 65536);
     check_int("claude-opus-5",
-              ha_codec_model_context_window("claude-opus-5"), 100000);
+              ha_codec_model_context_window(LIT("claude-opus-5")), 100000);
     check_int("gpt-4-turbo",
-              ha_codec_model_context_window("gpt-4-turbo"), 128000);
+              ha_codec_model_context_window(LIT("gpt-4-turbo")), 128000);
     check_int("llama-3-70b",
-              ha_codec_model_context_window("llama-3-70b"), 8192);
+              ha_codec_model_context_window(LIT("llama-3-70b")), 8192);
     check_int("AUTO (unknown)",
-              ha_codec_model_context_window("AUTO"), HA_CODEC_CONTEXT_WINDOW_UNKNOWN);
+              ha_codec_model_context_window(LIT("AUTO")), HA_CODEC_CONTEXT_WINDOW_UNKNOWN);
     check_int("NULL (unknown)",
-              ha_codec_model_context_window(NULL), HA_CODEC_CONTEXT_WINDOW_UNKNOWN);
+              ha_codec_model_context_window(NULL, 0), HA_CODEC_CONTEXT_WINDOW_UNKNOWN);
+    check_int("zero len (unknown)",
+              ha_codec_model_context_window("abc", 0), HA_CODEC_CONTEXT_WINDOW_UNKNOWN);
     check_int("case-insensitive",
-              ha_codec_model_context_window("QWEN-MAX"), 131072);
+              ha_codec_model_context_window(LIT("QWEN-MAX")), 131072);
     check_int("moonshot",
-              ha_codec_model_context_window("moonshot-v1-128k"), 131072);
+              ha_codec_model_context_window(LIT("moonshot-v1-128k")), 131072);
     /* 分支顺序：gpt-4-turbo 必须先于裸 gpt-4 命中 */
     check_int("gpt-4-mini (branch order)",
-              ha_codec_model_context_window("gpt-4-mini"), 128000);
+              ha_codec_model_context_window(LIT("gpt-4-mini")), 128000);
     check_int("gpt-4 (bare)",
-              ha_codec_model_context_window("gpt-4"), 8192);
+              ha_codec_model_context_window(LIT("gpt-4")), 8192);
     /* claude-3 必须先于裸 claude */
     check_int("claude-3-opus (branch order)",
-              ha_codec_model_context_window("claude-3-opus"), 200000);
+              ha_codec_model_context_window(LIT("claude-3-opus")), 200000);
+    /* 中文子串：非 ASCII 字节不受折叠影响 */
+    check_int("零一万物",
+              ha_codec_model_context_window(LIT("\xe9\x9b\xb6\xe4\xb8\x80\xe4\xb8\x87\xe7\x89\xa9")), 200000);
+
+    /* 非 NUL 结尾：把模型名放在大缓冲中间，只传前 N 字节。
+     * 这是新签名的关键能力（旧签名会读到后续垃圾）。 */
+    {
+        char buf[64];
+        memset(buf, 'Z', sizeof(buf));
+        memcpy(buf, "qwen-max", 8);
+        check_int("no NUL terminator (prefix only)",
+                  ha_codec_model_context_window(buf, 8), 131072);
+    }
+
+    /* 超长模型名（超过栈缓冲）必须仍零分配地正确匹配。 */
+    {
+        static char big[512];
+        memset(big, 'a', sizeof(big));
+        memcpy(big + 400, "gpt-4-turbo", 11);
+        check_int("oversize model name (heap-free fallback)",
+                  ha_codec_model_context_window(big, sizeof(big)), 128000);
+    }
 }
 
 static void test_estimate_tokens(void) {
     printf("estimate_tokens:\n");
-    check_int("empty", ha_codec_estimate_tokens(""), 0);
-    check_int("NULL", ha_codec_estimate_tokens(NULL), 0);
+    check_int("empty", ha_codec_estimate_tokens(LIT("")), 0);
+    check_int("NULL", ha_codec_estimate_tokens(NULL, 0), 0);
+    check_int("zero len", ha_codec_estimate_tokens("abc", 0), 0);
     /* "abc" = 3 rune * 2 = 6 */
-    check_int("ascii abc", ha_codec_estimate_tokens("abc"), 6);
-    /* "你好" = 2 rune * 2 = 4（注意：不是字节数 6） */
-    check_int("chinese 2 chars", ha_codec_estimate_tokens("你好"), 4);
+    check_int("ascii abc", ha_codec_estimate_tokens(LIT("abc")), 6);
+    /* "你好" = 2 rune * 2 = 4（不是字节数 6） */
+    check_int("chinese 2 chars", ha_codec_estimate_tokens(LIT("你好")), 4);
     /* 混合 "a你" = 2 rune * 2 = 4 */
-    check_int("mixed", ha_codec_estimate_tokens("a你"), 4);
+    check_int("mixed", ha_codec_estimate_tokens(LIT("a你")), 4);
     /* 4 字节 emoji：1 rune * 2 = 2 */
-    check_int("emoji", ha_codec_estimate_tokens("\xF0\x9F\x98\x80"), 2);
+    check_int("emoji", ha_codec_estimate_tokens(LIT("\xF0\x9F\x98\x80")), 2);
+
+    /* ASCII 快路径跨界：长度正好落在批量块边界附近，计数必须精确。 */
+    {
+        static char buf[300];
+        memset(buf, 'x', sizeof(buf));
+        check_int("ascii 300 bytes (chunk boundaries)",
+                  ha_codec_estimate_tokens(buf, sizeof(buf)), 600);
+    }
+    /* 非 NUL 结尾：只计前 N 字节（后面是垃圾）。 */
+    {
+        char buf[16];
+        memcpy(buf, "abc", 3);
+        memset(buf + 3, 'x', sizeof(buf) - 3);
+        check_int("no NUL terminator (prefix only)",
+                  ha_codec_estimate_tokens(buf, 3), 6);
+    }
+    /* 截断的多字节序列：Go 对无效序列按每字节 1 rune 计，C 必须一致。 */
+    check_int("truncated 3-byte seq (invalid)",
+              ha_codec_estimate_tokens("\xE4\xBD", 2), 4); /* 2 rune → 4 */
 }
 
 static void test_truncate(void) {
     printf("truncate_by_tokens:\n");
-    char buf[64];
 
-    /* max_tokens<=0 → 空 */
-    ha_codec_truncate_by_tokens("hello", 0, buf, sizeof(buf));
-    check_str("max_tokens=0", buf, "");
+    /* max_tokens<=0 → 0 字节 */
+    check_trunc_prefix("max_tokens=0", LIT("hello"), 0, 0);
 
-    /* 未超限 → 原样返回 */
-    size_t n = ha_codec_truncate_by_tokens("abc", 100, buf, sizeof(buf));
-    check_str("no truncation", buf, "abc");
-    check_size("no truncation len", n, 3);
+    /* 未超限 → 全长 */
+    check_trunc_prefix("no truncation", LIT("abc"), 100, 3);
 
     /* "abcdefghij" = 10 rune → 20 tokens；max=8 → keep=4 → "abcd" */
-    n = ha_codec_truncate_by_tokens("abcdefghij", 8, buf, sizeof(buf));
-    check_str("keep 4", buf, "abcd");
-    check_size("keep 4 len", n, 4);
+    check_trunc_prefix("keep 4", LIT("abcdefghij"), 8, 4);
 
-    /* 中文按 rune 截断，不切碎 UTF-8："你好世界" 4 rune，max=4 → keep=2 → "你好" */
-    n = ha_codec_truncate_by_tokens("你好世界", 4, buf, sizeof(buf));
-    check_str("chinese keep 2", buf, "你好");
-    check_size("chinese keep 2 len (bytes)", n, 6);
+    /* 中文按 rune 截断，不切碎 UTF-8："你好世界" 4 rune，max=4 → keep=2 → "你好"(6B) */
+    check_trunc_prefix("chinese keep 2", LIT("你好世界"), 4, 6);
 
-    /* 缓冲区不足：必须 NUL 结尾且不越界 */
-    char tiny[4];
-    n = ha_codec_truncate_by_tokens("abcdefghij", 100, tiny, sizeof(tiny));
-    check_size("tiny buf len", n, 3);
-    check_str("tiny buf NUL-terminated", tiny, "abc");
+    /* 恰好等于预算：不截断 */
+    check_trunc_prefix("exact budget", LIT("abc"), 6, 3);
+    /* 差一：截断。3 rune=6 tokens，max=5 → keep=2 → "ab" */
+    check_trunc_prefix("just under budget", LIT("abc"), 5, 2);
 
-    /* out_cap=0 不写 */
-    check_size("zero cap", ha_codec_truncate_by_tokens("abc", 100, tiny, 0), 0);
+    /* 长 ASCII 跨批量块边界，keep 落在块内（提前短路路径）。 */
+    {
+        static char buf[200];
+        memset(buf, 'k', sizeof(buf));
+        check_trunc_prefix("long ascii, keep inside chunk", buf, sizeof(buf), 128, 64);
+    }
+
+    /* 非 NUL 结尾：max 足够大 → 返回传入长度（而非 strlen 结果）。 */
+    {
+        char buf[16];
+        memcpy(buf, "abcd", 4);
+        memset(buf + 4, 'x', sizeof(buf) - 4);
+        check_trunc_prefix("no NUL terminator, full length", buf, 4, 100, 4);
+    }
+
+    /* 单字节 rune 边界：ASCII 与多字节混合，确保不切在字符中间。
+     * "a你b好c" = 5 rune = 10 tokens；max=6 → keep=3 → "a你b" = 1+3+1 = 5 字节 */
+    check_trunc_prefix("mixed keep 3", LIT("a你b好c"), 6, 5);
+    /* max=4 → keep=2 → "a你" = 1+3 = 4 字节（正好切在字符边界上）*/
+    check_trunc_prefix("mixed keep 2 (byte boundary)", LIT("a你b好c"), 4, 4);
+    /* 字节内容级校验：结果必须是原串的**逐字节前缀**，不能切碎 UTF-8。 */
+    check_trunc_bytes("content zh keep 2", "你好世界", sizeof("你好世界") - 1, 4, "你好");
+    check_trunc_bytes("content ascii keep 4", "abcdefghij", 10, 8, "abcd");
+    check_trunc_bytes("content no truncation", "abc", 3, 100, "abc");
 }
 
 int main(void) {
diff --git a/docs/zh/c-core/llm-orchestration-c.md b/docs/zh/c-core/llm-orchestration-c.md
index 40ca10a..9f8451a 100644
--- a/docs/zh/c-core/llm-orchestration-c.md
+++ b/docs/zh/c-core/llm-orchestration-c.md
@@ -278,50 +278,66 @@ C 化的正确性**不能靠「跑起来没崩」**，必须有可复现的对
 3. **下一个切片选谁**？L1 剩下的是协议编解码（`parseOpenAICompatible*`、
    `normalize*ToolCalls` 等，见 §三 L1 表）；该层依赖 JSON 解析 ⇒ 先解第 2 题。
 
-### 7.1 ★ 跨语言开销基线（实测已补，2026-09-25）
+### 7.1 ★ 性能：初版结论是错的，根因是我的绑定与 C 实现
 
-原 §七 写着「需先有真实延迟基线，当前没有」。现已补上
-（`internal/agent/api/codec_bench_test.go`，`go test -bench`）：
+**初版结论「C 比 Go 慢」不成立** —— 那是把「我自己的 malloc/拷贝开销」误当成了
+「cgo 的固有成本」。拆解实测（同一台机，`-benchtime` 百万次）：
 
-| 基准 | C（经 cgo）| 纯 Go | 谁快 |
-|---|---:|---:|---|
-| `ModelContextWindow`（短 ASCII）| 175 ns | 38 ns | **Go 快 4.6×** |
-| `EstimateTokens` / 空串 | 100 ns | 0.43 ns | **Go 快 230×** |
-| `EstimateTokens` / 短 ASCII | 115 ns | 6.5 ns | **Go 快 17×** |
-| `EstimateTokens` / 短中文 | 100 ns | 29 ns | **Go 快 3.4×** |
-| `EstimateTokens` / 中200字 | 229 ns | 509 ns | C 快 2.2× |
-| `EstimateTokens` / 1KB 中文 | 840 ns | 2870 ns | C 快 3.4× |
-| `EstimateTokens` / 1KB ASCII | 2318 ns | 332 ns | **Go 快 7×** |
-| `TruncateByTokens` / 短中文 | 233 ns | 54 ns | **Go 快 4.3×** |
-| `TruncateByTokens` / 1KB 中文 | 3923 ns | 6918 ns | C 快 1.8× |
+| 场景 | ns/op | 说明 |
+|---|---:|---|
+| cgo 边界（零拷贝传指针 + 空函数体）| **31.9** | cgo 的**真实**固有成本 |
+| + 一次 `C.CString` + C 侧 `strlen` | 105–111 | **多出 ~75ns（70%）** |
+| 初版 `ModelContextWindow`（另加 `lower_dup` malloc + 16×strstr）| **175** | 即 **82% 是自找的** |
 
-**结论（不要凭直觉，数据说话）**：
+而初版**违反了自己写在本文 §四 的接口原则第 1 条**：
+「C 接口只吃 `const char*` **+ 长度**」—— 它没传长度，让 C 侧 `strlen` 再扫一遍。
 
-1. **cgo 的固定开销约 95–100 ns/次**，小输入下完全压倒算法差异。
-2. C 只在**长中文**（rune 密集、UTF-8 步进重）上明显领先；
-   长 ASCII 反而 Go 快 7×（Go 的 `utf8.RuneCountInString` 对 ASCII
-   有快路径，而 C 侧逐字节跑）。
-3. ⇒ **「C 比 Go 快」是错的**；正确表述是「在特定输入分布上更快」。
+#### 优化措施（逐项对应上表的浪费）
 
-**对函数的建议（按调用分布）**：
+| # | 初版做法 | 现在 |
+|---|---|---|
+| 1 | `C.CString`（malloc + 整串拷贝）| `unsafe.StringData` 传指针 + 长度，**零拷贝** |
+| 2 | C 侧 `strlen` 再扫一遍 | 长度由调用方传入，**不扫** |
+| 3 | `truncate` malloc 输出缓冲 + `GoStringN` 拷回 | C 只返回**字节数**（结果必是前缀），Go 侧 `s[:n]` 切片 |
+| 4 | `lower_dup` 每次 malloc 模型名 | 栈缓冲折叠（超长走零分配回退） |
+| 5 | 逐字节 `utf8_next` 函数调用 | **字级（8 字节）ASCII 检测** + 位运算 UTF-8 校验 |
+| 6 | `truncate` 扫完整串才判断 | **数满 keep 个 rune 立即返回**（提前短路） |
+| 7 | 纯 Go 侧 `len([]rune(s))` / `[]rune(s)`（1KB 分配 4KB）| `utf8.RuneCountInString` / `DecodeRuneInString` 游走，**零分配** |
 
-- `ModelContextWindow`：调用点单一（`provider.go:333`，每请求一次），
-  且输入是**短 ASCII** ⇒ 拿不到收益。但它应该是**冷路径**，
-  175 ns 在单次请求尺度上无关痛痒——关键是别把它放到循环里。
-- `EstimateTokens`：**真正的高频点**在 `process.go:476` 的逐事件循环
-  （对每条上下文事件算 `Source + Input + 40`）与 `resident.go:552`
-  （对每条上下文算 `Input + Response`）。字段分布**不单一**：
-  - `Source` 是短标签（`"qq"` / `"webui"`）⇒ 属 Go 快 17× 那一档
-  - `Input` / `Response` 是对话文本，长度跨度大：长中文 C 快 2–3.4×，
-    短文本与长 ASCII 则 Go 快 3–7×
-  ⇒ **没有单一答案**：当前一刀切走 C 会让短串净亏。
-  正确做法是**按长度分派**（短走 Go、长中文走 C），
-  但需先用真实长度分布复测——不要凭推测动手。
-- `TruncateByTokens`：调用点单一（`tooldefs.go:38`），非热路径。
+#### 优化后（完全 C 化：一律走 C，无按长度分派）
 
-**这不否定 C 化方向**，但把「选谁下一个 C 化」的判据从「哪个函数看起来底层」
-换成「**哪个在真实输入分布下真能变快**」。协议编解码（JSON 解析、SSE 分片）
-处理的正是**长文本**——那才是 C 的主场，也是下一步更合理的候选。
+| 基准 | 初版 C | **优化后 C** | 纯 Go | 提升 |
+|---|---:|---:|---:|---:|
+| `ModelContextWindow`（短 ASCII）| 175 | **76.5** | 46.8 | **2.3×** |
+| `EstimateTokens` / 短 ASCII | 114.6 | **47.2** | 2.8 | 2.4× |
+| `EstimateTokens` / 短中文 | 99.6 | **49.7** | 22.8 | 2.0× |
+| `EstimateTokens` / **1KB ASCII** | 2318 | **80.8** | 326 | **28.7×** |
+| `EstimateTokens` / 1KB 中文 | 840 | 1467 | 2844 | 0.57×（见下）|
+| `TruncateByTokens` / 短中文 | 233 | **40.2** | 25.3 | 5.8× |
+| `TruncateByTokens` / **1KB ASCII** | 2594 | **71.7** | 411 | **36×** |
+| `TruncateByTokens` / **1KB 中文** | 3923 | **70.1** | 3097 | **56×** |
+
+#### ★ 必须如实说明的两点
+
+**① 中文密集输入比初版慢（1467 vs 840）—— 这是刻意的正确性代价。**
+初版的 `utf8_next` **只按首字节推断长度、不校验后续字节**，因此对畸形序列会与 Go
+分叉（例：`"\xE4\x41\x41"`，Go 判 3 个 rune，初版判 1 个 ⇒ rune 计数偏差 ⇒
+token 预算与截断点偏移）。现在 C 侧做了**与 Go `utf8.DecodeRuneInString` 等价**的
+完整校验（含过长编码、代理对、超 U+10FFFF、截断序列）。
+换来的能力由 `TestGolden_InvalidUTF8`（3000 组随机字节）钉死 —— 这类偏差
+**只影响计数、不会崩**，不测就发现不了。**正确性优先，且仍比纯 Go 快 2×。**
+
+**② 极短串上 C 慢于 Go（约慢一个数量级）—— 这是「完全 C 化」的已知代价。**
+`EstimateTokens("qq")`：C 约 47ns（几乎全是 31ns 的边界成本）vs 纯 Go 约 3ns。
+绝对值是纳秒级（47ns = 0.000047ms），单次请求尺度可忽略；
+但**若某个循环对极短串高频调用**，这一项会累积。
+
+⇒ **正确的应对是「C 化那个循环（批量传一次）」而不是「按长度分派回 Go」**
+（后者正是被否掉的混合做法：它会同时存在两份语义可能分叉的实现）。
+这也是 §三 L2/L3 把「有状态编排」明确留给 Go、而把「长 payload 编解码」
+作为下一步目标的原因 —— 协议编解码（JSON / SSE 分片）处理的正是长文本。
+
+---
 
 ---
 
diff --git a/internal/agent/api/codec.go b/internal/agent/api/codec.go
index f3967f8..7d88c9e 100644
--- a/internal/agent/api/codec.go
+++ b/internal/agent/api/codec.go
@@ -3,12 +3,15 @@ package api
 // codec.go —— 编解码层的**统一出口**（无论 CGO 开关如何，调用方只认这里）。
 //
 // 分层：
-//   codec_pure.go  —— 纯 Go 实现，永远参与编译（回退 + 黄金对照基准）
-//   codec_cgo.go   —— CGO_ENABLED=1：真正调 C 库
-//   codec_nocgo.go —— CGO_ENABLED=0：把 C 符号转发到纯 Go
+//   codec_cgo.go   —— C 实现绑定（要求 cgo；CGO_ENABLED=0 下整包构建失败）
+//   codec_pure.go  —— 纯 Go **参考实现**：只作黄金对照的规格基准，
+//                     不是生产路径（不带 build tag，永远参与编译）
 //   codec.go       —— 本文件：对外的稳定 API，含兜底与日志
 //
 // 这样调用方（provider.go / core）不需要写任何 build tag 分支。
+//
+// ★ 编解码层已「完全 C 化」：C 是唯一实现，不存在 CGO_ENABLED=0 回退。
+//   理由（防两条语义分叉的实现同时跑）见 codec_cgo.go 顶部。
 
 import (
 	"log"
@@ -34,9 +37,11 @@ func ModelContextWindow(model string) int {
 
 // EstimateTokens 粗略估算 token 数。
 //
-// 注意：这是**高频热路径**（上下文裁剪对每个事件都调）。走 C 的跨语言开销
-// 对短文本未必划算 —— 是否该留在 C 侧由 codec_bench_test.go 的实测数据决定，
-// 不要凭直觉断言（见 docs/zh/c-core/llm-orchestration-c.md §七 未决问题 3）。
+// 注意：这是**高频热路径**（上下文裁剪对每个事件都调）。已完全 C 化，
+// 但 cgo 边界固有成本约 30ns ⇒ 极短串上比直调纯 Go 慢（纳秒级，见
+// codec_bench_test.go 的实测与 docs/zh/c-core/llm-orchestration-c.md §7.1）。
+// 若某循环对极短串高频调用，正确应对是**把该循环 C 化（批量传一次）**，
+// 而不是按长度分派回 Go —— 那会引入第二条可能分叉的实现。
 func EstimateTokens(text string) int { return estimateTokensC(text) }
 
 // TruncateByTokens 截断字符串至不超过 maxTokens 估计值。
diff --git a/internal/agent/api/codec_cgo.go b/internal/agent/api/codec_cgo.go
index 37478cf..4fecfd5 100644
--- a/internal/agent/api/codec_cgo.go
+++ b/internal/agent/api/codec_cgo.go
@@ -18,29 +18,44 @@ package api
 // **不能链接预构建静态库**（`LDFLAGS: .../csrc/build/libha_codec.a`）：
 //   - .a 是构建产物、不入库（.gitignore 的 build/ 命中 csrc/build/），
 //     而发布脚本原先并不产出它 ⇒「不入库 + 不生成」两头空，链接必然失败
-//     （实测：cannot find csrc/build/libha_codec.a）
 //   - 交叉编译 linux/arm64（homed 的真实发布目标）时，宿主 x86-64 的 .a
-//     被链进目标产物，报 `file in wrong format`（实测）。
+//     被链进目标产物，报 `file in wrong format`
 //
 // **不能用 `#include "../../../csrc/src/ha_codec.c"`（包外相对包含）**：
-//   ★ Go 构建缓存**不跟踪包外被 #include 的 C 文件**。实测：在包外源里把
-//   返回值从 7 改成 8，`go test` 依然通过（缓存命中，静默沿用旧代码）；
-//   而同样改动落在包内文件时立刻判红。这对「逐步推进 C 化」是致命的——
-//   改 C 源码却不生效，且无任何报错。
+//   ★ Go 构建缓存**不跟踪包外被 #include 的 C 文件**。实测：包外源把返回值
+//   7 改成 8，`go test` 依然通过（缓存命中、静默沿用旧代码）；同样改动落在
+//   包内文件时立即判红。这对「逐步推进 C 化」是致命的——改 C 源码却不生效
+//   且无任何报错。
 //   （包内 shim `#include` 包外源同样漏跟踪，已实测排除。）
 //
 // 包内符号链接同时满足两点：文件在包目录内 ⇒ 缓存按内容正确跟踪；
 // 只有一份权威源 ⇒ 无副本漂移，也不需要「同步 C 源」的 make 目标。
 //
+// ============================ 零拷贝：不 CString、不 strlen ============================
+// ★ 这是**被实测教训倒逼出来的**（见 docs/zh/c-core/llm-orchestration-c.md §7.1）：
+//
+// cgo 边界的固有成本实测约 **32 ns**（零拷贝传指针 + 空函数体）。
+// 而初版每次调用都做 `C.CString`（malloc + 整串拷贝）+ C 侧 `strlen`（再扫一遍），
+// 单这一项就约 **75 ns**，加上 C 侧 `lower_dup` 的 malloc 与逐字节扫描，
+// 使 ModelContextWindow 实测达到 **175 ns** —— 即 **82% 是自找的开销**，
+// 而非 cgo 的固有代价。初版由此得出「C 比 Go 慢」的结论是**错的**。
+//
+// 现在：Go 侧用 `unsafe.StringData` 把 string 的底层字节**直接**交给 C
+// （传指针 + 长度），C 侧不 malloc、不 strlen、不要求 NUL 结尾。
+// 截断则只回**字节长度**（结果必然是输入前缀），Go 侧 `s[:n]` 完成切片，
+// 全程零分配零拷贝。
+//
+// 边界与安全：
+//   - 不把 Go 指针交给 C 长期持有（C 侧不保存任何指针，纯函数）
+//   - 空串在 Go 侧短路，不把可能的 nil 指针传下去
+//   - cgo 规则允许传「不含 Go 指针的内存」的指针，string 底层字节满足
+//
 // ============================ 为什么不需要额外 build tag ============================
 // 与 onnxruntime（internal/nlp/onnx.go，需运行期 libonnxruntime.so）不同：
 // ha_codec 是**零依赖纯 C99 源码内联编译**，不需要任何外部库或工具链前提。
 // 而 homed 本就强制 cgo（mattn/go-sqlite3 + gojieba），故 C 路径自然生效。
-// 因此只用 `cgo` / `!cgo` 一组约束，不引入 hacodec tag。
-//
-// ============================ C 侧契约 ============================
-// `#include "ha_codec.h"` 只声明原型；实现在同包的 ha_codec.c，由 cgo 自动编译。
-// 只含 libc 头，不引入第三方符号。
+// 因此只用 `cgo` 约束（**没有 `!cgo` 回退**：CGO_ENABLED=0 下本包构建失败，
+// 这是有意的响亮失败，理由见上），也不引入 hacodec tag。
 //
 // 语义必须与 codec_pure.go 逐值等价，由 codec_golden_test.go 钉死。
 
@@ -53,45 +68,49 @@ import "C"
 
 import "unsafe"
 
+// cstr 返回 s 的底层字节首地址与长度，供 C 侧零拷贝读取。
+//
+// 空串返回 (nil, 0)：调用方不应把 nil 传给会解引用的 C 函数。
+func cstr(s string) (*C.char, C.size_t) {
+	if len(s) == 0 {
+		return nil, 0
+	}
+	return (*C.char)(unsafe.Pointer(unsafe.StringData(s))), C.size_t(len(s))
+}
+
 // modelContextWindowC 经 C 实现推断上下文窗口。
 func modelContextWindowC(model string) int {
-	cModel := C.CString(model)
-	defer C.free(unsafe.Pointer(cModel))
-	return int(C.ha_codec_model_context_window(cModel))
+	p, n := cstr(model)
+	return int(C.ha_codec_model_context_window(p, n))
 }
 
 // estimateTokensC 经 C 实现估算 token 数。
+//
+// ★ 不做按长度分派：**完全 C 化**——compute 一律走 C，纯 Go 实现不再是
+// 生产路径（只作为黄金对照的规格基准）。
+//
+// 代价（如实记录，勿用「C 更快」一句话盖过）：cgo 边界固有成本实测约 30ns，
+// 故对「极短串」（如 2 字节的 "qq"）本函数约 30ns，而直调纯 Go 仅约 3ns
+// ——即极短输入上 C 路径约慢一个数量级，但绝对值是**纳秒级**
+// （30ns = 0.00003ms，单次请求尺度可忽略）。
+// 换来的是：单一实现、无静默分派分叉、C 侧对畸形 UTF-8 的严格校验恒生效。
 func estimateTokensC(text string) int {
-	cText := C.CString(text)
-	defer C.free(unsafe.Pointer(cText))
-	return int(C.ha_codec_estimate_tokens(cText))
+	p, n := cstr(text)
+	return int(C.ha_codec_estimate_tokens(p, n))
 }
 
 // truncateByTokensC 经 C 实现按 token 截断。
 //
-// 缓冲区策略：按 rune 数上界分配（每个 rune 最多 4 字节）+ 1 字节 NUL，
-// 保证 C 侧不会因容量不足而截短——否则 C 与 Go 的逐值对照会假失败。
-// 若字符串无 rune（纯 ASCII 也至少 len 字节），取 len(text)+1 兜底。
+// C 侧只返回「应保留的字节数」——截断结果必然是输入的前缀，
+// 故这里直接切片，无需缓冲区、无需 malloc、无需把结果拷回来。
 func truncateByTokensC(s string, maxTokens int) string {
 	if maxTokens <= 0 || s == "" {
 		return ""
 	}
-	// []rune 的长度即 rune 数；每个 rune 最坏 4 字节，+1 给 NUL。
-	runeCount := len([]rune(s))
-	bufSize := runeCount*4 + 1
-	if bufSize < len(s)+1 {
-		bufSize = len(s) + 1
+	p, n := cstr(s)
+	keep := C.ha_codec_truncate_by_tokens(p, n, C.int(maxTokens))
+	if uint64(keep) >= uint64(len(s)) {
+		return s
 	}
-	buf := (*C.char)(C.malloc(C.size_t(bufSize)))
-	if buf == nil {
-		// 分配失败：回退纯 Go 实现，不让整个调用失败。
-		return truncateByTokensPure(s, maxTokens)
-	}
-	defer C.free(unsafe.Pointer(buf))
-
-	cText := C.CString(s)
-	defer C.free(unsafe.Pointer(cText))
-
-	n := C.ha_codec_truncate_by_tokens(cText, C.int(maxTokens), buf, C.size_t(bufSize))
-	return C.GoStringN(buf, C.int(n))
+	return s[:int(keep)]
 }
diff --git a/internal/agent/api/codec_golden_test.go b/internal/agent/api/codec_golden_test.go
index 8bdb647..ca6bbc8 100644
--- a/internal/agent/api/codec_golden_test.go
+++ b/internal/agent/api/codec_golden_test.go
@@ -1,14 +1,13 @@
 package api
 
-// codec_golden_test.go —— 黄金对照测试：C 实现与纯 Go 实现必须逐值等价。
+// codec_golden_test.go —— 黄金对照测试：C 实现与纯 Go 参考实现必须逐值等价。
 //
-// 这是本轮 C 化**最重要的验收**（见 docs/zh/c-core/llm-orchestration-c.md §五）。
+// 这是 C 化**最重要的验收**（见 docs/zh/c-core/llm-orchestration-c.md §五）。
 // 没有它，「C 化没坏」就只是感觉，不是证据。
 //
-// 两条约束：
-//   1. CGO_ENABLED=1 时：真的对比 C 与纯 Go 两条路径
-//   2. CGO_ENABLED=0 时：C 符号已转发到纯 Go，对照退化为自比（仍跑，防止
-//      测试文件因 build tag 被整文件跳过 —— 那会让 0 模式下失去这段覆盖）
+// 运行前提：**CGO_ENABLED=1**。内核已完全 C 化：本包**要求 cgo 才能编译**
+// （无 !cgo 回退文件），故 CGO_ENABLED=0 时整包构建失败 —— 这是有意的
+// 响亮失败，见 codec_cgo.go 顶部与 Makefile 的 check-codec-cgo-only。
 
 import (
 	"math/rand"
@@ -113,3 +112,68 @@ func TestGolden_Randomized(t *testing.T) {
 		}
 	}
 }
+
+// TestGolden_InvalidUTF8 用**任意字节**（含畸形序列）对比 C 与纯 Go。
+//
+// 为什么必须有：C 侧的解码必须与 Go 的 utf8.DecodeRuneInString 完全同语义
+// ——尤其是「无效/截断序列只前进 1 字节」（Go 返回 RuneError 且 size=1）。
+// 若 C 侧放宽校验，两侧 rune 计数就会分叉，而合法 UTF-8 的测试**抓不到**这个。
+// 这是 C 化最容易出错、也最容易被漏测的地方。
+func TestGolden_InvalidUTF8(t *testing.T) {
+	// 覆盖各类边界字节：续字节、过长编码、代理对、超出 U+10FFFF、截断序列。
+	seed := []byte{
+		0x00, 0x41, 0x7F, 0x80, 0xBF, 0xC0, 0xC1, 0xC2, 0xDF, 0xE0, 0xE1,
+		0xED, 0xEF, 0xF0, 0xF1, 0xF4, 0xF5, 0xF8, 0xFE, 0xFF,
+		0xE4, 0xBD, 0xA0, // 你
+		0xF0, 0x9F, 0x98, 0x80, // 😀
+		0xED, 0xA0, 0x80, // 0xED 0xA0 0x80 = UTF-16 代理对，非法
+		0xC0, 0x80, // 过长编码 NUL，非法
+		0xF4, 0x90, 0x80, 0x80, // > U+10FFFF，非法
+	}
+	rng := rand.New(rand.NewSource(20260925))
+
+	for i := 0; i < 3000; i++ {
+		n := rng.Intn(24)
+		b := make([]byte, n)
+		for j := range b {
+			if rng.Intn(3) == 0 {
+				b[j] = byte(rng.Intn(256)) // 完全随机字节
+			} else {
+				b[j] = seed[rng.Intn(len(seed))]
+			}
+		}
+		s := string(b)
+
+		if c, p := estimateTokensC(s), estimateTokensPure(s); c != p {
+			t.Fatalf("EstimateTokens(%q) 畸形输入: C=%d, pure=%d", b, c, p)
+		}
+		// 截断也必须落在同一字节边界上（不得切在字符中间，且两侧一致）
+		mt := rng.Intn(40) - 2
+		if c, p := truncateByTokensC(s, mt), truncateByTokensPure(s, mt); c != p {
+			t.Fatalf("TruncateByTokens(%q, %d): C=%q, pure=%q", b, mt, c, p)
+		}
+	}
+}
+
+// TestGolden_TruncateAlwaysPrefix 不变量：截断结果必须是原串前缀，且 <= 原长。
+func TestGolden_TruncateAlwaysPrefix(t *testing.T) {
+	inputs := []string{
+		"", "a", "abc", "你好世界", "a你b好c", "😀😀😀", strings.Repeat("x", 300),
+		strings.Repeat("中", 300), "\xe4\xbd", "a\xed\xa0\x80b",
+	}
+	for _, s := range inputs {
+		for mt := -2; mt <= 60; mt++ {
+			got := truncateByTokensC(s, mt)
+			if !strings.HasPrefix(s, got) {
+				t.Fatalf("TruncateByTokens(%q, %d)=%q 不是原串前缀", s, mt, got)
+			}
+			if len(got) > len(s) {
+				t.Fatalf("TruncateByTokens(%q, %d) 结果长于输入", s, mt)
+			}
+			if got != truncateByTokensPure(s, mt) {
+				t.Fatalf("TruncateByTokens(%q, %d): C=%q, pure=%q", s, mt, got, truncateByTokensPure(s, mt))
+			}
+		}
+	}
+}
+
diff --git a/internal/agent/api/codec_nocgo.go b/internal/agent/api/codec_nocgo.go
deleted file mode 100644
index 76e38fc..0000000
--- a/internal/agent/api/codec_nocgo.go
+++ /dev/null
@@ -1,22 +0,0 @@
-//go:build !cgo
-
-package api
-
-// codec_nocgo.go —— CGO_ENABLED=0 时把 C 路径的符号指向纯 Go 实现。
-//
-// 为什么需要这层转发而不是直接调 *Pure：让 codec.go 无论编译开关如何都能引用
-// 同一组符号名，避免调用方到处写 build tag 分支。
-//
-// 谁会走到这里（CGO_ENABLED=0）：
-//   - waiter 等刻意 CGO-free 的跨平台目标（Makefile build-cli）
-//   - 交叉编译到无 cgo 工具链的场景
-//
-// homed 不会走到这里——它强制 cgo（sqlite3 + gojieba）。
-// 两条路径的语义等价由 codec_golden_test.go 钉死，Makefile 的
-// check-codec-paths 目标同时跑两条。
-
-func modelContextWindowC(model string) int { return modelContextWindowPure(model) }
-
-func estimateTokensC(text string) int { return estimateTokensPure(text) }
-
-func truncateByTokensC(s string, maxTokens int) string { return truncateByTokensPure(s, maxTokens) }
diff --git a/internal/agent/api/codec_pure.go b/internal/agent/api/codec_pure.go
index 245f35e..d599ed7 100644
--- a/internal/agent/api/codec_pure.go
+++ b/internal/agent/api/codec_pure.go
@@ -1,16 +1,30 @@
 package api
 
-// codec_pure.go —— 编解码层的**纯 Go 实现**，永远参与编译。
+// codec_pure.go —— 编解码层的**纯 Go 参考实现**。
 //
-// 它有两个身份：
-//   1. CGO_ENABLED=0 时的生产实现（Windows 包走这里，见
-//      deploy/packaging/package-windows.sh:69）
-//   2. CGO_ENABLED=1 时**黄金对照的基准**（codec_golden_test.go 用同一组输入
-//      对比它与 C 实现，逐值必须相等）
+// ★ 这**不是生产路径**。内核已「完全 C 化」：所有调用都走 C
+//   （internal/agent/api/codec_cgo.go），本文件只服务两个目的：
 //
-// 因此本文件**不带 build tag**——两条路径都要能见到它。
+//   1. **规格基准**：`codec_golden_test.go` 用同一组输入对比它与 C 实现，
+//      断言逐值相等。C 侧的任何语义偏差（尤其畸形 UTF-8 的解码边界）
+//      都由它抓出。没有它，「C 化没改错」就只是感觉。
+//   2. **可读的规格**：C 是命令式字节游走，Go 版是直白的语义陈述。
+//      两者并读时，改哪边都能立刻看出另一边该怎么改。
+//
+// 因此本文件**不带 build tag**，永远参与编译（测试要能引用）。
+// 但没有任何生产代码路径调用它：编解码层要求 cgo 才能编译
+// （CGO_ENABLED=0 下整包构建失败，见 codec_cgo.go 顶部）。
+//
+// ★ 零分配：本文件刻意不用 `len([]rune(s))` / `[]rune(s)`。
+//   `[]rune(s)` 会分配 4×len 字节的临时切片（1KB 字符串就是 4KB 垃圾），
+//   而 rune 计数与「前 keep 个 rune 的字节边界」都能用
+//   utf8.RuneCountInString / utf8.DecodeRuneInString 游走完成，零分配。
+//   实测这曾使纯 Go 的 TruncateByTokens 在 1KB 中文上分配 4208 B/2 allocs。
 
-import "strings"
+import (
+	"strings"
+	"unicode/utf8"
+)
 
 // defaultInferredContextWindow 是模型名无法推断窗口时的兜底。
 //
@@ -29,6 +43,9 @@ const contextWindowUnknown = -1
 
 // modelContextWindowPure 由模型名推断最大上下文窗口；推断不出返回哨兵。
 // 标称窗口 ≠ 有效窗口：接近满时注意力涣散，调用方应取 70-80% 为目标利用率。
+//
+// ★ 分支顺序即语义：先匹配者胜出（例：gpt-4-turbo 必须先于裸 gpt-4）。
+//   C 侧 ha_codec_model_context_window 必须保持同一顺序。
 func modelContextWindowPure(model string) int {
 	model = strings.ToLower(model)
 	switch {
@@ -71,11 +88,14 @@ func modelContextWindowPure(model string) int {
 
 // estimateTokensPure 粗略估算 token 数。
 // 中文 ~1.5 token/字，英文 ~0.3 token/字符，保守估计取 max(1, runeCount * 2)。
+//
+// 用 RuneCountInString 而非 len([]rune(text))：后者会分配 4×len 字节。
+// 两者对**畸形 UTF-8** 的计数一致（无效字节各计 1 个 rune）。
 func estimateTokensPure(text string) int {
 	if text == "" {
 		return 0
 	}
-	runeCount := len([]rune(text))
+	runeCount := utf8.RuneCountInString(text)
 	if runeCount == 0 {
 		return 0
 	}
@@ -87,17 +107,26 @@ func estimateTokensPure(text string) int {
 }
 
 // truncateByTokensPure 截断字符串至不超过 maxTokens 估计值。
+//
+// 语义（与 C 侧一致）：未超预算则原样返回；否则保留前 maxTokens/2 个 rune。
+// 结果必然是输入的前缀，故直接按字节边界切片——无需构造 []rune。
 func truncateByTokensPure(s string, maxTokens int) string {
 	if maxTokens <= 0 || s == "" {
 		return ""
 	}
-	runes := []rune(s)
-	if len(runes)*2 <= maxTokens {
+	runeCount := utf8.RuneCountInString(s)
+	if runeCount*2 <= maxTokens {
 		return s
 	}
 	keep := maxTokens / 2
-	if keep >= len(runes) {
+	if keep >= runeCount {
 		return s
 	}
-	return string(runes[:keep])
+	// 游走到「前 keep 个 rune」的字节边界（零分配）。
+	n := 0
+	for count := 0; count < keep; count++ {
+		_, size := utf8.DecodeRuneInString(s[n:])
+		n += size
+	}
+	return s[:n]
 }
diff --git a/plan.md b/plan.md
index c21839e..f1c730b 100644
--- a/plan.md
+++ b/plan.md
@@ -412,6 +412,200 @@ PluginContext（独立身份，共享管道）。
      `normalize*ToolCalls`）全部依赖 JSON 解析，不定就推不下去
 3. **下一个切片选谁？**（已有基准数据支撑，见下）
 
+### ★ 已定：编解码层「完全 C 化」（2026-09-25，jianf 裁定）
+
+初版基准一度得出「C 比 Go 慢」，**该结论已被推翻** —— 根因是我的 Go 绑定与 C 实现
+写得烂（每次调用 `CString` malloc+拷贝 + C 侧 `strlen` + `lower_dup` malloc +
+逐字节扫描），把自找的 82% 开销误当成了 cgo 的固有成本。拆解实测：
+
+| 场景 | ns/op |
+|---|---:|
+| cgo 边界（零拷贝 + 空函数体）| **31.9** ← cgo 真实固有成本 |
+| + `C.CString` + `strlen` | 105–111（多出 ~75ns）|
+| 初版 `ModelContextWindow` | 175 |
+
+优化后（零拷贝传指针+长度、栈缓冲折叠、字级 ASCII 检测、位运算 UTF-8 校验、
+截断返回字节数、提前短路；纯 Go 侧也去掉 `[]rune` 分配）：
+
+| 基准 | 初版 C | 优化后 C | 纯 Go | 提升 |
+|---|---:|---:|---:|---:|
+| `ModelContextWindow` | 175 | **76.5** | 46.8 | 2.3× |
+| `EstimateTokens` / 1KB ASCII | 2318 | **80.8** | 326 | **28.7×** |
+| `TruncateByTokens` / 1KB ASCII | 2594 | **71.7** | 411 | **36×** |
+| `TruncateByTokens` / 1KB 中文 | 3923 | **70.1** | 3097 | **56×** |
+
+**裁定：完全 C 化，不做按长度分派。** 我一度加了「短串走回 Go」的分派，
+被否决 —— 那会同时存在两份语义可能分叉的实现。代价如实记录：
+`EstimateTokens("qq")` 这类极短串上 C 约 47ns vs Go 约 3ns（几乎全是边界成本），
+绝对值纳秒级可忽略；若某循环对极短串高频调用，**正确应对是 C 化那个循环
+（批量传一次）**，而不是退回 Go（见下条）。
+
+**结论性变化**：
+- C 侧新增**与 Go `utf8.DecodeRuneInString` 等价的完整校验**（含过长编码、
+  代理对、超 U+10FFFF、截断序列）。这使中文密集输入比初版慢（1467 vs 840），
+  但初版对畸形序列会与 Go **分叉**（rune 计数偏差 ⇒ token 预算/截断点偏移，
+  只影响计数不会崩，不测发现不了）。正确性优先，且仍比纯 Go 快 2×。
+  由 `TestGolden_InvalidUTF8`（3000 组随机字节）钉死。
+- 包**要求 cgo 才能编译**（删除了 `!cgo` 回退）：CGO_ENABLED=0 下整包构建失败。
+  理由：不许存在第二条可能分叉的实现路径；且 `waiter`/`initconfig`/`memgc`/`mock-server`
+  实测均**不依赖**本包，无 CI 在 CGO_ENABLED=0 下构建它 ⇒ 不影响任何现有构建。
+  Makefile 的 `check-codec-cgo-only` 把「不许有第二条路」变成可执行断言。
+
+**下一个切片的判据**（已从「哪个看起来底层」换成「哪个在真实分布下真能变快」）：
+协议编解码（`parseOpenAICompatible*` / `normalize*ToolCalls` / SSE 分片）
+处理的正是**长文本**，是 C 的主场，比「把短函数搬过去」更合理。
+但其前置是 JSON 解析 ⇒ 先定 `ha_json.c` 复用还是新写。
+
+## 三、已关闭 / 已实现（旧档误标或本轮更正，防复活）
+
+逐条给出「旧档怎么说」与「实际怎样」。
+
+### 1. §13.12 L3 原生多模态 —— 已实现
+- 实际：`internal/memory/graph.go:169` 起建 `memory_blocks`
+  （含 `modality/payload_digest/mime/vector/fingerprint/scene`）+
+  `memory_block_edges`（`source_kind/target_kind/edge_type`），以及
+  `scenes`/`scene_features`/`scene_refs`；`internal/agent/core/graphmedia.go`（310 行）
+  实现 `migrateLegacyGraphMedia`/`attachBlocksToSentence`/`linkBlocksToDocument`/
+  `commitTriplesWithMedia`；`graphmedia_test.go` 21 个测试。
+- 结论：**关闭**
+
+### 2. §13.9 llmsproxy 上下文溢出感知 —— 不属本仓（见 §五.1）
+
+### 3. §13.10 AgentMail 三个 bug —— 不属本仓（见 §五.2）
+
+### 4. §11.4 Lua stage 快照缺读锁（DATA RACE）—— 已修
+- 实际：`internal/plugin/proc/shmcodec.go:42` 的 `WriteAll` 已在 `captureLocal`
+  前后持 `sc.RLock()/RUnlock()`；`go test -race ./internal/lua/... ./internal/plugin/...` 全绿
+- 结论：**关闭**
+
+### 5. §12.2 `io.setToolBlocks` 内核侧是桩 —— 已实现
+- 实际：`internal/plugin/proc/corehandler_inject.go:132` 实现
+  `MethodIOSetToolBlocks`；模板 `putArena` → `blocks_ref`；
+  `e2e_template_test.go:371` 用**真实 SDK 模板**验证
+- 结论：**关闭**
+
+### 6. §13.11 WebUI 修复清单 —— 主体已实现，仅剩 P1-7
+- 逐项核实：`Last-Event-ID` 重放（`handler_chat.go:710`）、请求超时
+  （`handler_chat.go:592` 等 300s）、XSS 消毒（`dashboard.js:252` DOMPurify）、
+  `renderAll` 增量（`dashboard.js:34 / :452 / :1361` 增量游标 + 流式增量）、
+  `handleKnowledge` 不再吞错（`handler_memory.go:122` 起逐分支返回错误）、
+  CSS/DesignSystem（`dashboard.css:3` 起 sakura/frost 令牌）、
+  GUI 重构（`cmd/gui/renderer/app.js`）—— 均已落地。
+- 仅 `handleAgentAction` 501 是真缺口（已列 P1-7）
+
+### 7. Windows 支持 —— **已设计性放弃**（旧档 P2-8 与 C 化 §2.3 的前提均据此更正）
+- 旧档说：「Windows 桩已收敛，但缺真机验证」（把它当待办）
+- 实际：`cmd/homed/platform_windows.go` 明确**原生 Windows 拒绝启动**并给 WSL2 指引。
+  原因写入注释：插件体系依赖「继承的 fd」+「统一共享内存区的段内偏移解引用」，
+  Windows 句柄模型无法表达；强适等于再维护一套平台专属 ABI（C ABI 时代三套 ABI
+  并存曾致改写型插件静默失效）。
+- 配套：`internal/plugin/proc/shmalloc_windows.go` 的 `allocShm` 直接报错不返回半可用段；
+  `deploy/packaging/windows/install-via-wsl.ps1`（新）引导 WSL2 并复用 Linux 包；
+  `build.sh` windows 目标**只构建 waiter + gui**，homed/initconfig 明确拒绝
+  （见 `build.sh:257-267`）。
+- 实测佐证：`GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build ./cmd/waiter` 成功
+  （12MB .exe）；`homed` 无论如何都编不出 Windows（`internal/memory` 依赖 cgo-only 的
+  `gojieba`）。
+- 结论：**关闭**（该项不是待办；Windows 的正确验收 = WSL2 内按 Linux 路径跑，
+  与 Linux 目标同一条流水线）
+
+### 8. 仓库卫生：PTY 三例的 FAIL —— 环境相关 + skip 判据失效（旧档 P2-10）
+- 旧档说：`go test ./...` 有 3 个 FAIL（PTY 三例 / 端口 9890 冲突 / `system_test` 写 `/etc`）
+- 本轮实测（分时）时：
+  - `go test -count=1 ./...` → **57 包：38 ok + 19 无测试文件 + 0 FAIL**
+  - PTY 三例**本就有 skip 意图**（`integration_test.go:284/337/395` 的
+    `t.Skipf("PTY not available: ...")`），且 `/dev/ptmx` 可用时正常通过（连跑 3 次均 ok）
+  - **但该 skip 的判据是坏的**：它查 `resp["status"] == "error"`，而插件失败时返回的是
+    `{"error": "创建终端失败: ..."}`（`internal/plugins/agentcli/plugin.go:496`）——
+    **键名不匹配**，于是真遇到无 PTY 权限的环境会走到 `t.Fatalf` 而非 skip。
+    这是「探测存在但失效」的典型：比没有探测更隐蔽
+  - `TestRestoreFileFromBaseline` 在 `/etc` 可写时 **PASS**（`system_test.go:83` 确实
+    写真实路径且不检查 err——**代码确实不干净**，但它不构成「稳定 FAIL」）
+  - `9890` 端口**确有占用**（本机 homed 常驻监听），但测试用 `setupIntegration`
+    起的实例未与之冲突（连跑 3 次均 ok）
+- 结论：**旧档的记录在当时是真的**（环境退化：ptmx 无权限 + 端口被占），
+  环境恢复后自然全绿。但**两个真缺陷存留**：① skip 判据键名不匹配（探测失效，
+  退化时硬 FAIL）；② 测试依赖固定端口。两条已列 §六，不列为「待办功能项」。
+
+---
+
+## 四、生产部署后验证（代码已就绪，本就无法在仓库内完成）
+
+这些**不是待开发项**，是「必须落到生产实例才能确认」的验收。仓库内有
+`scripts/verify_deploy.sh [data_dir]` 可一键检查前两条。
+
+- [ ] **§0.1 healthcheck 隔离**：部署后 `knowledge/`、`memory/graph.db`、
+      `memory/documents/` 不再出现 `_hc_*` 残留
+- [ ] **图记忆去重**：`relations` 重复率归零，跑一周不新增重复
+- [ ] **§13.5 / §13.6 QQ 端到端**：真实 QQ 消息注入与输出经共享内存通道正常
+      （小 payload 内联、大 payload 走 `text_ref`/`frame`）
+- [ ] **§0.2 agentcli 不泛滥**：QQ 消息在 agentcli 无自喂送风暴时能被正常响应
+
+---
+
+## 五、跨项目工单（**不属本仓**，旧档误并入）
+
+旧 plan.md 把别仓的工单写成本仓 TODO，导致「查无此代码却挂着未完成」。移出并说明归属：
+
+### 1. §13.9「llmsproxy 上下文溢出感知」
+- 旧档写：补 `OVERFLOW_PATTERNS`（"Context window is full"）、AUTO 截断宽度 `80→160`、
+  `go test ./internal/ai/...`
+- 事实：本仓**没有 `internal/ai/`**；相关符号在 **`/home/program/llmsproxy`**
+  （`internal/gateway/chat.go`）。本仓 `internal/agent/api/provider.go` 只**消费**
+  该网关（注释里提到 "llmsproxy 的 AUTO 链"，:361）
+- 现状：该仓已把宽度改成 160
+- 归属：**llmsproxy 仓**
+
+### 2. §13.10「AgentMail 三个 bug」
+- 旧档写：提示词修正 / `InReplyTo` / `relay_key ≤ 64 字节`
+- 事实：AgentMail 是独立仓 **`/home/program/agentmail`**
+  （`relay_key` 见 `server/internal/handler/permission.go`）。本仓
+  `grep relay_key\|InReplyTo` **零命中**
+- 归属：**agentmail 仓**
+
+> 若这两仓也要纳入统一管理，应各自建 plan，不要塞进本仓文档。
+
+---
+
+## 六、明确「不做」与「建议修但不阻塞」
+
+### 不做（防反复挂账）
+
+- **§13.13 反向结果入共享内存**：本仓**不存在 `llm.chat`**（`llm.*` 只映射
+  listSources/setSource/currentSource）；唯一可能返回大结果的 `doc.query` 被
+  `CapDocMemory` 能力门挡着，且无外部插件使用。**不做**。
+- **Windows 原生适配**：见 §三.7，**设计上不做**。
+
+### 建议修但不阻塞（测试卫生，非当前 FAIL）
+
+- `internal/system/system_test.go:83`：`target := "/etc/RestoreFileFromBaseline.test.tmp"`
+  写真实系统路径，且两处 `os.WriteFile(...)` **不检查 err** → 在 `/etc` 不可写的
+  环境里静默失败，报 `expected restore to happen`（根因是测试，不是实现）。
+  建议改用 `t.TempDir()` + 保留 `IsProtectedPath` 语义所需的显式前缀，并检查每步 err。
+- `internal/plugins/remotedevice/plugin.go:27` 固定端口 `127.0.0.1:9890`：测试沿用该
+  默认值，本机已有 homed 常驻监听。建议测试改用 `:0` 让 OS 分配。
+- **PTY 三例的 skip 判据是坏的（真缺陷，不只是卫生）**：`integration_test.go`
+  284/337/395 查 `resp["status"] == "error"`，而 `terminal_create` 失败时返回
+  `{"error": "创建终端失败: ..."}`（`internal/plugins/agentcli/plugin.go:496`）——
+  键名不匹配 ⇒ 真遇到无 PTY 权限的环境**会 `t.Fatalf` 而非 skip**。
+  同类型：其他依赖工具错误响应的环境探测（应统一认 `error` 键）。
+- 同类审计：其他「写真实系统路径且吞错误」的测试。
+
+---
+
+## 七、C 化：已定事项与待拍板事项
+
+第一刀（L1 纯函数层）已落地并闭环（见 §二 P0-1 与
+`docs/zh/c-core/llm-orchestration-c.md`）。下阶段扩大前，有三处**需 jianf 拍板**：
+
+1. **C 实现放主仓 `csrc/` 还是 SDK `third_party/homeagent-sdk/`？**
+   - 当前已在主仓 `csrc/`（`ha_codec.{c,h}` 是权威源，Go 侧符号链接过去）
+   - 若 SDK / 鸿蒙 / C SDK 侧也要复用，需定同步机制；搬进 SDK 则要走 SDK 冻结流程
+2. **`ha_json.c` 复用还是新写？**（复用会动 SDK 目录结构）
+   - 这是下一个切片的**前置**：L1 剩下的协议编解码（`parseOpenAICompatible*`、
+     `normalize*ToolCalls`）全部依赖 JSON 解析，不定就推不下去
+3. **下一个切片选谁？**（已有基准数据支撑，见下）
+
 ### ★ 已定：跨语言开销基线已补齐（2026-09-25）
 
 原本文写「需先有真实延迟基线（当前没有）」——现已补上
@@ -450,20 +644,27 @@ PluginContext（独立身份，共享管道）。
 
 ### 已定事项（不再挂账）
 
-- **回退路径保留**：用 `cgo` / `!cgo` 一组约束，**不引入额外 tag**。
-  理由：ha_codec 是零依赖纯 C99 源码内联编译（不需外部库/工具链），
-  而 homed 本就强制 cgo（sqlite3 + gojieba），故 C 路径自然生效。
+- **不保留回退路径**：编解码层**要求 cgo 才能编译**（无 `!cgo` 文件）。
+  CGO_ENABLED=0 下整包构建失败——这是有意的响亮失败，不是缺漏。
 
-  **回退路径当前的真实受益者**（实测，不要夸大）：
-  - `CGO_ENABLED=0 go build ./...` / `go vet ./...` 能遍历含 `internal/agent/api`
-    的包——若无 `codec_nocgo.go`，这些命令会因找不到 `modelContextWindowC`
-    等符号而**整包编译失败**。这是当前主要价值。
-  - ★ 需知道的事实：`go list -deps` 实测**只有 `cmd/homed` 依赖
-    `internal/agent/api`**；`waiter` / `initconfig` / `memgc` / `mock-server`
-    均不依赖。而 homed 强制 cgo ⇒ **`!cgo` 分支目前无任何生产目标在用**。
-    保留它是为了「包在 CGO_ENABLED=0 下仍可编译」与未来 CGO-free 目标，
-    而不是因为现有什么目标需要它。
-  - 黄金对照的**基准**不靠它：`codec_pure.go` **无 build tag**、永远参与编译。
+  **为什么不做回退**：回退会让两份语义可能分叉的实现同时在产线跑。
+  C 侧对畸形 UTF-8 的解码边界一旦与 Go 分叉，只表现为 rune 计数偏差
+  （⇒ token 预算与截断点偏移），**不会崩、不会报错**，最难发现。
+  只验证过一条路，就不该存在第二条。
+
+  **为什么这不影响任何构建**（实测，别当成风险）：
+  - `go list -deps` 实测**只有 `cmd/homed` 依赖 `internal/agent/api`**；
+    `waiter` / `initconfig` / `memgc` / `mock-server` 均**不依赖**（逐个验过）。
+  - homed 本就强制 cgo（mattn/go-sqlite3 + gojieba）⇒ 恒走 C 路径。
+  - 仓库**无 CI**（无 .github/workflows），发布脚本仅在构建 `waiter` 时用
+    CGO_ENABLED=0，而 waiter 不依赖本包。
+  - `make check-codec-cgo-only` 把「不许有第二条路」变成可执行断言
+    （断言 cgo 下全绿 **且** CGO_ENABLED=0 下必须失败）。
+- **纯 Go 实现的定位**：`codec_pure.go` 不带 build tag、永远编译，
+  但**不是生产路径**——它只作**黄金对照的规格基准**与可读规格。
+  （它本身也已零分配化：去掉 `[]rune` 的 4×len 临时分配。）
+- **不链接预构建 `.a`，也不用包外 `#include`**（前者架构错 + 产物两头空，
+  后者缓存漏跟踪）。用包内符号链接，理由与实测见 §二 P0-1 与设计文档 §2.4。
 - **不链接预构建 `.a`，也不用包外 `#include`**（前者架构错 + 产物两头空，
   后者缓存漏跟踪）。用包内符号链接，理由与实测见 §二 P0-1 与设计文档 §2.4。