mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-26 12:23:23 +00:00
7351c6ca2e
第一刀只做三个纯函数（窗口推断 / token 估算 / token 截断）， 价值不在功能（Go 版没问题），而在打通「Go → cgo → C」全链路并 建立可复现的对照范式，后面每扩一个函数都复用它。 ## 为什么是这三个 按「无状态 → 有状态」分层，L1 协议编解码最安全：纯 string in → struct out， 不碰网络、不碰 Lua、不碰 goroutine。三个函数更是同一组纯算术，最小可验证切片。 ## 关键设计：包内符号链接，不链接静态库、不 include 包外源 三种做法都实测过，只有一种同时满足「可构建 + 可交叉编译 + 缓存可跟踪」： 1. ❌ 链接 `csrc/build/libha_codec.a`（原方案） - .a 是构建产物、不入库（.gitignore 的 build/ 命中 csrc/build/）， 而发布脚本原先并不产出它 ⇒「不入库 + 不生成」两头空， 实测报 `cannot find .../libha_codec.a` - 交叉编译 linux/arm64（homed 真实发布目标）时，宿主 x86-64 的 .a 被链进目标产物，实测报 `file in wrong format` 2. ❌ `#include "../../../csrc/src/ha_codec.c"`（包外相对包含） ★ Go 构建缓存**不跟踪包外被 #include 的 C 文件**。实测：包外源把返回值 7→8，`go test` 依然通过（缓存命中、静默沿用旧代码）；同样改动落在包内 文件时立即判红。对「逐步推进 C 化」这是致命的——改 C 源码不生效且无报错。 （包内 shim `#include` 包外源同样漏跟踪，已实测排除。） 3. ✅ 包内符号链接 `internal/agent/api/ha_codec.{c,h}` → `csrc/` 文件在包目录内 ⇒ 缓存按内容正确跟踪；只有一份权威源 ⇒ 无副本漂移， 也不需要「同步 C 源」的 make 目标。 ## 不需要额外 build tag ha_codec 是零依赖纯 C99 源码内联编译，不需要外部库或工具链前提； 而 homed 本就强制 cgo（sqlite3 + gojieba），故 C 路径自然生效。 只用 `cgo` / `!cgo` 一组约束（对比 onnxruntime：那个需运行期 .so，故必须显式 tag）。 ## 顺带修掉的既有缺陷（非 C 化引入，但一直缺覆盖） - Makefile 的 arm64 目标缺 CC/CXX：cgo 回退到宿主 g++，报 `gcc_arm64.S: no such instruction: 'stp x29,x30,[sp,'` （deploy/packaging/build.sh:49 一直是对的，Makefile 漏了） - Makefile 的 arm64 目标缺 .syso 隔离：cmd/{homed,waiter}/*.syso 是 Windows COFF 资源对象，Go 会把同目录 .syso 无条件链进任何目标，交叉到非 Windows 平台报 `file format not recognized`（build.sh 有 hide_syso_for_target） ## 验证（每条可复现） - `make build-linux-arm64` → ELF 64-bit LSB executable, ARM aarch64（82MB） - `bash deploy/packaging/build.sh linux/arm64 homed` → ELF aarch64（79MB） - 移走 csrc/build/ 后 homed（cgo）与 waiter（CGO=0）均能构建 - 变异 C 源（131072→777）后**同一缓存**下 go test 立即 FAIL（改前：仍报 ok） - `make check-codec-paths` 两条路径 OK；`make csrc-test` C 契约测试 100% - 黄金对照：手写用例 + 2000 次随机对拍，C 与纯 Go 逐值相等 - 全量 `go test -count=1 ./...` → 57 包：38 ok + 19 无测试 + 0 FAIL 新增 `make check-codec-paths` 防回归：只测一条路径时，另一条的破坏不会被发现。 ## 文档 - `docs/zh/c-core/llm-orchestration-c.md` 同步为「已落地」，并更正因 「Windows 原生已放弃」而过时的 §2.3（回退路径的理由需重述） - plan.md 的 P0-1 标记为已修复，附实测证据
68 lines
2.8 KiB
C
68 lines
2.8 KiB
C
#ifndef HA_CODEC_H
|
||
#define HA_CODEC_H
|
||
|
||
/*
|
||
* ha_codec — HomeAgent 内核编解码层（C 实现）
|
||
*
|
||
* ============================ 接口冻结声明 ============================
|
||
* 本头文件是对外契约。函数签名、语义、返回值一经发布即为冻结接口，
|
||
* 修改必须走大版本流程（与 third_party/homeagent-sdk 同一冻结标准）。
|
||
*
|
||
* 设计约束（见 docs/zh/c-core/llm-orchestration-c.md §四）：
|
||
* 1. 只吃 const char* + 长度，出数值/JSON 串
|
||
* 2. 不回调 Go、不传 Go 指针
|
||
* 3. 不长期持有 malloc 内存；需要出参的用调用方缓冲区
|
||
* 4. 无状态、纯函数、线程安全（不写全局可变状态）
|
||
*
|
||
* 当前覆盖：L1 协议编解码层中的纯计算部分（第一个最小切片）。
|
||
*/
|
||
|
||
#include <stddef.h>
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* ==================== 模型上下文窗口推断 ==================== */
|
||
|
||
/* 无法从模型名推断时的哨兵值（与 Go 侧一致）。
|
||
*
|
||
* 为什么返回哨兵而不是直接给兜底值：调用方需要区分「真推断出了」与
|
||
* 「推断不出、只能兜底」——后者要打一行日志（窗口被低估必须可见），
|
||
* 并提示部署方用 per-source context_window 显式声明。
|
||
* 若 C 侧直接返回兜底值，调用方就永远分不清这两种情况。 */
|
||
#define HA_CODEC_CONTEXT_WINDOW_UNKNOWN (-1)
|
||
|
||
/* 由模型名推断最大上下文窗口（token 数）；推断不出返回
|
||
* HA_CODEC_CONTEXT_WINDOW_UNKNOWN。model 为 NULL 时同样返回 UNKNOWN。
|
||
*
|
||
* model 为 UTF-8 字符串，匹配大小写不敏感。
|
||
* 语义必须与 Go 侧 modelContextWindowPure 逐值一致（黄金对照测试钉死）。 */
|
||
int ha_codec_model_context_window(const char *model);
|
||
|
||
/* ==================== token 估算与截断 ==================== */
|
||
|
||
/* 粗略估算 token 数。
|
||
*
|
||
* 规则（与 Go 侧 EstimateTokens 一致）：中文 ~1.5 token/字、英文 ~0.3 token/字符，
|
||
* 保守取 max(1, runeCount * 2)。text 为 NULL 或空串返回 0。
|
||
*
|
||
* 注意：按 UTF-8 **字符数**（rune）计，不是字节数。 */
|
||
int ha_codec_estimate_tokens(const char *text);
|
||
|
||
/* 截断字符串至不超过 maxTokens 估计值，返回写入 out 的字节数（不含结尾 NUL）。
|
||
*
|
||
* 语义与 Go 侧 TruncateByTokens 一致：从开头保留 maxTokens/2 个字符。
|
||
* maxTokens <= 0 或 text 为空时写入空串。
|
||
*
|
||
* out 由调用方提供，容量须为 outCap（含结尾 NUL）；函数保证 NUL 结尾、
|
||
* 不越界写。返回值是实际写入的字节数（可能因 outCap 不足而短于完整截断结果）。 */
|
||
size_t ha_codec_truncate_by_tokens(const char *text, int max_tokens,
|
||
char *out, size_t out_cap);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* HA_CODEC_H */
|