mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-26 12:23:23 +00:00
perf(c-core): 完全 C 化 + 消灭初版的 malloc/拷贝开销（C 从「更慢」变「明显更快」）
上一提交的基准结论是错的："C 比 Go 慢" 不成立 —— 那是我把自己的
malloc/拷贝开销误当成了 cgo 的固有成本。本提交先拆解成本、再逐项消灭。
## 成本拆解（同机、百万次 benchtime）
| 场景 | ns/op |
|---|---:|
| cgo 边界（零拷贝传指针 + 空函数体）| 31.9 ← cgo 真实固有成本 |
| + 一次 C.CString + C 侧 strlen | 105-111（多出 ~75ns）|
| 初版 ModelContextWindow（另加 lower_dup malloc + 16×strstr）| 175 |
即 82% 开销是自找的。而初版还违反了自己写在设计文档 §四 的原则第 1 条
「C 接口只吃 const char* + 长度」——它没传长度，让 C 侧 strlen 再扫一遍。
## 逐项修复
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 检测
6. truncate 扫完整串才判断 → 数满 keep 个 rune 立即返回（提前短路）
7. 纯 Go 侧 len([]rune(s))/[]rune(s)（1KB 分配 4KB）→
utf8.RuneCountInString / DecodeRuneInString 游走，零分配
## 结果
| 基准 | 初版 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 化（jianf 裁定）
撤掉我一度加的「短串 <32B 走回 Go」按长度分派：那会同时存在两份语义
可能分叉的实现。C 是唯一实现。
代价如实记录：EstimateTokens("qq") 这类极短串上 C 约 47ns（几乎全是
31ns 边界成本）vs 纯 Go 约 3ns，慢约一个数量级；绝对值纳秒级
（0.000047ms），单次请求尺度可忽略。若某循环对极短串高频调用，
正确应对是**把该循环 C 化（批量传一次）**，而不是按长度分派回 Go。
## 顺带补的正确性缺口（初版是真错的）
初版 C 的 UTF-8 解码只按首字节推断长度、**不校验后续字节**，
因此对畸形序列会与 Go 分叉：例 "\xE4\x41\x41"，Go 判 3 rune，
初版判 1 rune ⇒ rune 计数偏差 ⇒ token 预算与截断点偏移。
这类偏差**只影响计数、不会崩**，不测发现不了。
现在 C 侧做与 utf8.DecodeRuneInString 等价的完整校验（含过长编码、
代理对、超 U+10FFFF、截断序列），语义边界逐条注释。
代价：中文密集输入比初版慢（1467 vs 840）—— 这是刻意的正确性代价，
且仍比纯 Go 快 2×。
新增测试：
- TestGolden_InvalidUTF8：3000 组**任意字节**（含畸形序列）对拍，
覆盖初版会分叉的输入类别
- TestGolden_TruncateAlwaysPrefix：截断结果必为原串前缀且不超长
- C 契约测试从 21 项扩到 40 项（含非 NUL 结尾、超长名、畸形 UTF-8）
## 包现在要求 cgo 才能编译
删除 codec_nocgo.go：CGO_ENABLED=0 下整包构建失败（错误直指缺失符号）。
不保留回退的理由：只验证过一条路，就不该存在第二条。
实测这不影响任何构建 —— go list -deps 证明只有 cmd/homed 依赖本包，
而 waiter/initconfig/memgc/mock-server 均不依赖（逐个验过），
且 homed 本就强制 cgo（sqlite3 + gojieba）。仓库无 CI。
Makefile 把「不许有第二条路」变成可执行断言：check-codec-cgo-only
（断言 cgo 下全绿 **且** CGO_ENABLED=0 下必须失败）。
## 验证
- C 契约测试 40/40（gcc -Wall -Wextra 零警告）
- 黄金对照 6 个测试全绿（含 2000 组随机 + 3000 组畸形字节对拍）
- 变异测试：改 C 侧返回值后 go test 立即 FAIL（确认真的走 C）
- make check-codec-cgo-only 两项断言通过
- go vet ./... 干净；全量 go test -count=1 ./... → 38 ok / 0 FAIL
## 已知既有 flaky（与本改动无关，单独记录）
internal/plugins 在全量并发下偶发一次 SIGSEGV，栈在
internal/plugin/proc/{unified.go:234,arena.go:197}（arena 的 getU32）。
该两文件最后修改于 09-10，本提交 0 处触及；随后连跑 5 次单包 +
2 次全量均通过。初步判断是 arena/shared-region 的既有竞态，需单独排查。
This commit is contained in:
JianFeeeee
37
Makefile
37
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
|
||||
|
||||
@ -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
|
||||
}
|
||||
|
||||
@ -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; /* 未超预算：整串都留 */
|
||||
}
|
||||
|
||||
@ -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) {
|
||||
|
||||
@ -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 分片）处理的正是长文本。
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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 估计值。
|
||||
|
||||
@ -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)]
|
||||
}
|
||||
|
||||
@ -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))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@ -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) }
|
||||
@ -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]
|
||||
}
|
||||
|
||||
227
plan.md
227
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。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user