HomeAgent

jianf/HomeAgent

Fork 0

mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 14:57:38 +00:00

Commit Graph

Author	SHA1	Message	Date
JianFeeeee	a68d6a428c	feat: 模块化内核（编译期依赖图定序）+ 密钥防火墙 + 插件三态生命周期 (#10 ) * feat(kernel): 模块化内核 + 编译期依赖图定序把单体 init 序列拆成「模块自声明依赖 + 编译期生成依赖图 + 运行期只读图」。 ## 为什么原 cmd/homed/main.go 里 17 步 init 是手写顺序，依赖关系只存在于注释和人脑里。实测踩到的坑（见 docs/zh/kernel-modularization-design.md）： · nlp.defaultParser 被 initONNXParser 写、被 distiller 读，两者相距 60 行，只靠 ticker 10min 才没炸（隐式依赖，无声明） · 加一个模块要人肉找"该插在哪"，插错的表现是运行期 nil 解引用 · 关停是 defer ks.CloseAll()，而热更新路径 os.Exit(42) 跳过 defer ⇒ docStore/distiller/textMem 的 flush 全部丢失（每次热更新都发生） ## 怎么改 - internal/kernelboot/：KernelState（一个结构体收全部包级共享变量，字段 nil 安全）、Module 接口、graphfile（依赖图编解码 + 与二进制 hash 对账）、 scheduler（按 BFS 层并行 Init）、syncbus（层边界写通知）、 lifecycle（Quiesce/Resume 可逆伪关机，区别于一次性 CloseAll） - internal/kernelmod/<name>/：每个模块一个文件夹，Requires/Provides 自声明； all/all.go 是唯一的 import 清单（Go 循环导入约束） - cmd/homed-depgraph：编译期生成依赖图，Makefile 注入 digest - 运行期只读图，不计算顺序（顺序是编译期决定的，源码里没有中央清单） ## 判据 kernelboot 8 条 + 图失败模式 7 条（全部拒绝并给准确错误）+ 模块目录数与注册表一致性。变异测试 15/15 咬住，含： · 删掉 AddCloser 的锁 → -race 报数据竞争 · Scheduler 同批跑去重 → 203 vs 200 · 图 hash 不匹配 → 拒绝启动 ## 顺带修的缺陷热更新路径漏调模块关闭 ⇒ 显式 stopKernelModules()，并用 AST 判据钉住 "必须在 os.Exit 之前"（字符串检查在本仓已骗过我三次）。实测：冷启动 1630ms（5 层/17 模块，原 17 步串行）；生产 22 插件全部建链。 * feat(security): 密钥防火墙 + 配置加密 + close 纪律 ## 密钥防火墙模型只见别名、不见明文；插件工具调用入口（StageHost.ExecuteTool）做入向回填。三维能力： · 出向：工具输出里的密钥被替换成 [[secret:name]] 别名后才进上下文 · 入向：模型传别名，入口处填回真值（插件完全无感知） · 存储：config.db 里不存明文（0644 的库可读），敏感值独立 0600 文件模式库「宁漏勿误伤」：宁可漏掉一次替换，也不把正常文本误当密钥。 ## 配置加密 - internal/security/{codec,key,keyring,store,global}.go：AES-256-GCM， enc:v1: 前缀，密钥轮换（OldKeys 解码 + 新钥加密） - harden.go：数据目录权限收紧 - embedded.go：支持内嵌主密钥（可选，仍保留外部 key 文件路径） - EncryptExistingSecrets / AuditSecrets：启动时幂等迁移 + 审计 ## close 纪律（用户明确要求：只要调 close 就要有前置检查） internal/safeclose：Safe / SafeFunc。全仓 37 处裸 close(chan) → 0。关键教训（都写进注释和判据）： · `select { case <-ch: default: close(ch) }` 不是并发安全的（两个 goroutine 可同时命中 default）—— healthcheck 原先是这种写法 · `sync.Once` 不可重入：X.Do(func(){ Safe(&X, ...) }) 会自锁，症状是 go test 直接挂住（3 个包 600s 超时），栈里只有嵌套的 Once.Do · map 里按请求持有的 channel（mcp/stdio.go、clawhubadapter/sidecar.go）改成 pendingRPC 包装，每通道一个 once ## 判据 security 全量 + TestNoBareCloseOutsideSafeclose（AST 级扫描，含注释剥离） + TestNoNestedSelfOnceDeadlock（正则修正：\w+ 不匹配点号，捕获组要含 '.'）。变异 2/2 咬住。全量 52 包 ok。 feat(plugin+deploy): 插件三态生命周期、数据目录迁移、发行包修复 ## 插件三态生命周期（用户要求：自动启动 / 启用但不自动启动 / 禁用） - Manifest 新增 requires_facilities / auto_start（bool，用于区分 "未声明"与"显式 false"） - plugin-host 模块（internal/kernelmod/pluginhost）：用 kernelboot.Scheduler 按依赖时机拉起，不再手写两阶段* - 运行态停启 StopPlugin/StartPlugin 可逆：不写 disabled_plugins （不改用户决定）、不置 shuttingDown（之后还能加载）、会摘掉注册面 - 与 StopAll 的区别写进注释 —— StopAll 置 shuttingDown 后永久无法加载，那是进程退出用的，误用于"暂停"就是关了就死 ## 数据目录迁移（伪关机 → 迁移 → 唤醒） - kernelboot/lifecycle.go：Quiesce/Resume（可逆，区别于一次性 CloseAll），逆序暂停、逆序恢复、Pause 失败回滚 - kernelboot/migrate.go：BeginMigration/End 编排（先停插件 → 再停内核写者 → 等在途归零） - distiller/textmem 增 Pause/Resume 门（不是 cancel —— cancel 不可逆，恢复要重建整个对象） - 模块 migration：体检 + 生成可执行迁移脚本 ★ 迁移脚本的三个实测教训（都写成了判据）： 1. 无条件改 /etc/systemd/system ⇒ 演练把生产 -data 改成了演练目录。加 --dry-run（零改动）+ 强制校验 systemd 当前 -data == OLD 2. 本机没装 rsync，脚本在"服务已停、数据未搬"处硬失败 ⇒ cp -a 回退，并明确警告不保硬链接/ACL（生产 plugindev 有大量 git 硬链接） ## 发行包修复（全部经实测确认） 1. package-linux.sh 完全漏打 depgraph.bin ⇒ 内核 exit 1 （"生产构建（内嵌 hash 非空）但读不到依赖图"） 2. build_homed 不走 Makefile ⇒ 单独修 Makefile 无效，必须同时生成图+注入 3. build.sh 的 LDFLAGS 用历史模块路径 gitcode.com ⇒ -X 静默 no-op ⇒ --version 显示 unknown 4. Makefile -ldflags 用单引号 ⇒ 注入了字面 $GRAPH_HASH ## ★ build.sh 的版本号必须校验（真实事故）原 `VERSION="$(git describe --tags --dirty)"`。无 tag 分支上它返回分支名 `backup/pre-identity-rewrite-20261005-51-g03d87a4e-dirty`，被注入 meta.Version ⇒ 插件握手判据 MajorVersion() 把整串当主版本 ⇒ 22 个子进程插件全部握手失败（"主版本不匹配"）。内核活着、systemd active、日志每条都像插件的问题 —— 实际是发行包带着非法版本号。修法：git describe 只在形如 vX.Y.Z 时采用，否则回退 meta.Version（权威源），并对最终值做形态守卫。deploy/packaging/version_guard_test.go 3 条判据，变异 2/2 咬住。 ## deb 的 systemd unit 改为 guard 模式 ExecStart=/usr/bin/homed --role=guard --data /var/lib/homeagent （worker exit 42 → guard 重拉，不经过 systemd、不计失败）含 RestartSteps/RestartMaxDelaySec/TimeoutStopSec + 硬化（NoNewPrivileges/ProtectSystem/ProtectHome/DevicePolicy/ReadWritePaths）。 ## 其他 - internal/plugin/proc：非法 JSON 帧的报错可定位（内容摘要 + 可能原因 + 修法）。生产实测 1038 条非法帧（插件往 stdout 打日志 = 污染协议通道） - 示例插件 4 个 14 处 fmt.Printf → log.Printf - hmapdev 模板同步修复；scaffold 判据剥离注释（模板注释里就含 fmt.Printf） * chore: 收尾（主密钥轮换命令、IPC/知识库加固、SDK 对齐） - cmd/homed-key-rotate：把 security 里的 RotateKey/RotateKeyFile/RekeySecrets 串成一条可执行的运维路径。没有它，E-1 就只是库里的能力而不是 "出事时能做的事"，而轮换的价值恰恰在于能执行。 - cmd/homed：kmod_runtime（模块装配入口）、plugins_scheduled（failback 白名单）、memcandidate、bootstrap_order_test / shutdown_flush_test - internal/ipc、internal/devicebridge、internal/knowledge：配套加固 - third_party/homeagent-sdk/sdk：PluginMgrAPI 增三态能力（mgrStop/mgrStart/ mgrIsRuntimeStopped）+ settings 对齐判据：bootstrap_order_test（启动顺序不依赖手写序列）、 shutdown_flush_test（停机的两条路径必须对称 —— exit 42 会跳过 defer，热更新路径下模块关闭/flush 曾全部丢失）。 * test(security): 测试夹具改用不可误认的占位值（修 push protection 拦截） GitHub secret scanning 拦住了推送：三处测试夹具用了"看起来像真密钥"的字面量： internal/security/prefilter_test.go:39 internal/security/store_test.go:177 internal/security/survey_test.go:20 它们全是假密钥（`AKIAIOSFODNN7EXAMPLE` 是 AWS 官方文档的标准示例，其余是 `abcdefghij...` 这类可读占位符），但扫描器无法区分 —— 它只看形态。 ★ 不绕过（不用 unblock URL、不加 allowlist）：直接改夹具。原因：一旦允许"假密钥可以通过"，真密钥混进来时就没有最后一道门了。改法：保留模式库匹配所需的结构，把可识别内容换成 FAKE： glpat-abcdefghijklmnopqrst → glpat-FAKE-TEST-TOKEN-NOT-REAL sk-abcdefghij...012345 → sk-FAKE-TEST-KEY-NOT-REAL-0000000 AKIAIOSFODNN7EXAMPLE → AKIA0000FAKE0000TEST (保持 20 字符) ASIAIOSFODNN7EXAMPLE → ASIA0000FAKE0000TEST xoxb-123456789012-abcdefghijklmnop → xoxb-FAKE-TEST-TOKEN-NOT-REAL ★ 中途踩到一次：AWS 键的模式是 `\b(AKIA\|ASIA)[0-9A-Z]{16}\b`（共 20 字符），我第一次替换成 19 字符的 `AKIAFAKETESTKEY0000` ⇒ 模式匹配不上 ⇒ TestSurvey_WhatIsCaught / TestRecognizesCommonShapes / TestPrefilterNeverBlocksRealMatches 三条当场变红。判据正确地拒绝了"为了过扫描器而削弱覆盖"。顺带核实：全仓 grep 无任何真实密钥泄漏。 * fix(packaging): package-linux.sh 的版本解析与 build.sh 统一上一版只修了 build.sh，漏了 package-linux.sh —— 它仍只看 git describe： VERSION="${VERSION:-$(git describe --tags --dirty)}" 无 tag 分支上 git describe 返回分支名（backup/pre-identity-rewrite-20261005-56-g98850e1），守卫会正确拒绝，但要求人手动传 VERSION 才能打包。而 build.sh 早已能自动回退 meta.Version ⇒ 同一个版本，走 build.sh 打得出来、走 package-linux.sh 打不出来。危害不只是"要手动传参"：运维为了跑通会去掉守卫，而分支名一旦进 meta.Version 就是插件协议主版本的来源 ⇒ 22 个子进程插件全部握手失败（这是真实发生过的事故，见 3efa4e5）。修法：两个脚本用同一套规则（git describe 仅在 vX.Y.Z 形态时采用，否则回退 meta.Version），并对最终值做形态守卫。判据：TestBothPackagingScriptsShareVersionRules —— 逐个读两个脚本，要求都能从 meta/meta.go 取权威版本、都校验 git describe 形态。变异（把 package-linux.sh 改回旧规则）咬住并准确指出是哪个脚本。实测：不传 VERSION 跑 package-linux.sh，输出 [PKG] warn: git describe 给出非版本串（...），改用 meta.Version=1.4.0 Version: 1.4.0 * fix(test): 跨仓判据在 CI 上应 skip 而非 fail（修 PR 双红） CI 上 "Go build / vet / test" 与 "Build linux/amd64" 双红： --- FAIL: TestHmapdevTemplateImplementsAllPluginMgrMethods bridge_sync_test.go:170: 读模板: open ../../../third_party/homeagent-sdk/tools/hmapdev/templates/proc_main.go.tmpl: no such file or directory ## 根因：判据依赖了一个被 gitignore 的路径 `.gitignore:33` 有 `third_party/homeagent-sdk/tools/`（SDK 仓自治，本仓不跟踪）。于是： · 本机（完整 SDK 检出）有该文件 ⇒ 判据通过 · CI（只 checkout 本仓）没有该文件 ⇒ Fatalf ⇒ 必红我提交时只在本机跑测试、没看 CI，所以这个问题拖到 PR 才暴露。 ## 修法文件缺失时 `t.Skipf` 而不是 `t.Fatalf`。 ★ 这不是"放弃检查"： · 跨仓一致性由 SDK 仓自己的判据守着（tools/hmapdev/scaffold_stdout_test.go 等），那里才是模板的真实归属地 · 本判据在本机开发时仍然生效（已验证：有文件时 PASS，缺文件时 SKIP） ## 验证 · 本机（有文件） → PASS（判据真跑） · 模拟 CI（移走 tools/）→ SKIP（不再 fail） · 全量 53 包 ok / 0 fail ## 顺带同目录还有 e2e_template_test.go 也读 tools/，但它是 `//go:build` 门控的 e2e 判据，CI 默认不跑，无需处理。 --------- Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>	2026-10-17 19:18:24 +08:00
JianFeeeee	6f50ec3e20	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 的既有竞态，需单独排查。	2026-09-25 15:40:20 +08:00
JianFeeeee	69dcb2ffbc	feat(c-core): 内核编解码层 C 化第一刀 —— L1 纯函数层落地并打通构建链第一刀只做三个纯函数（窗口推断 / 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 标记为已修复，附实测证据	2026-09-25 14:45:08 +08:00

Author

SHA1

Message

Date

JianFeeeee

a68d6a428c

feat: 模块化内核（编译期依赖图定序）+ 密钥防火墙 + 插件三态生命周期 (#10 )

* feat(kernel): 模块化内核 + 编译期依赖图定序

把单体 init 序列拆成「模块自声明依赖 + 编译期生成依赖图 + 运行期只读图」。

## 为什么

原 cmd/homed/main.go 里 17 步 init 是**手写顺序**，依赖关系只存在于
注释和人脑里。实测踩到的坑（见 docs/zh/kernel-modularization-design.md）：
 · nlp.defaultParser 被 initONNXParser 写、被 distiller 读，两者相距 60 行，
   只靠 ticker 10min 才没炸（隐式依赖，无声明）
 · 加一个模块要人肉找"该插在哪"，插错的表现是运行期 nil 解引用
 · 关停是 defer ks.CloseAll()，而热更新路径 os.Exit(42) **跳过 defer**
   ⇒ docStore/distiller/textMem 的 flush 全部丢失（每次热更新都发生）

## 怎么改

- internal/kernelboot/：KernelState（一个结构体收全部包级共享变量，字段
  nil 安全）、Module 接口、graphfile（依赖图编解码 + 与二进制 hash 对账）、
  scheduler（按 BFS 层并行 Init）、syncbus（层边界写通知）、
  lifecycle（Quiesce/Resume 可逆伪关机，区别于一次性 CloseAll）
- internal/kernelmod/<name>/：每个模块一个文件夹，Requires/Provides 自声明；
  all/all.go 是唯一的 import 清单（Go 循环导入约束）
- cmd/homed-depgraph：编译期生成依赖图，Makefile 注入 digest
- 运行期只**读**图，不计算顺序（顺序是编译期决定的，源码里没有中央清单）

## 判据

kernelboot 8 条 + 图失败模式 7 条（全部拒绝并给准确错误）+ 模块目录数
与注册表一致性。变异测试 15/15 咬住，含：
 · 删掉 AddCloser 的锁 → -race 报数据竞争
 · Scheduler 同批跑去重 → 203 vs 200
 · 图 hash 不匹配 → 拒绝启动

## 顺带修的缺陷

热更新路径漏调模块关闭 ⇒ 显式 stopKernelModules()，并用 AST 判据钉住
"必须在 os.Exit 之前"（字符串检查在本仓已骗过我三次）。

实测：冷启动 1630ms（5 层/17 模块，原 17 步串行）；生产 22 插件全部建链。

* feat(security): 密钥防火墙 + 配置加密 + close 纪律

## 密钥防火墙

模型只见别名、不见明文；插件工具调用入口（StageHost.ExecuteTool）做入向
回填。三维能力：
 · 出向：工具输出里的密钥被替换成 [[secret:name]] 别名后才进上下文
 · 入向：模型传别名，入口处填回真值（插件完全无感知）
 · 存储：config.db 里不存明文（0644 的库可读），敏感值独立 0600 文件

模式库「宁漏勿误伤」：宁可漏掉一次替换，也不把正常文本误当密钥。

## 配置加密

- internal/security/{codec,key,keyring,store,global}.go：AES-256-GCM，
  enc:v1: 前缀，密钥轮换（OldKeys 解码 + 新钥加密）
- harden.go：数据目录权限收紧
- embedded.go：支持内嵌主密钥（可选，仍保留外部 key 文件路径）
- EncryptExistingSecrets / AuditSecrets：启动时幂等迁移 + 审计

## close 纪律（用户明确要求：只要调 close 就要有前置检查）

internal/safeclose：Safe / SafeFunc。全仓 37 处裸 close(chan) → 0。
关键教训（都写进注释和判据）：
 · `select { case <-ch: default: close(ch) }` **不是**并发安全的
   （两个 goroutine 可同时命中 default）—— healthcheck 原先是这种写法
 · `sync.Once` **不可重入**：X.Do(func(){ Safe(&X, ...) }) 会自锁，
   症状是 go test 直接挂住（3 个包 600s 超时），栈里只有嵌套的 Once.Do
 · map 里按请求持有的 channel（mcp/stdio.go、clawhubadapter/sidecar.go）
   改成 *pendingRPC 包装，每通道一个 once

## 判据

security 全量 + TestNoBareCloseOutsideSafeclose（AST 级扫描，含注释剥离）
+ TestNoNestedSelfOnceDeadlock（正则修正：\w+ 不匹配点号，捕获组要含 '.'）。
变异 2/2 咬住。全量 52 包 ok。

* feat(plugin+deploy): 插件三态生命周期、数据目录迁移、发行包修复

## 插件三态生命周期（用户要求：自动启动 / 启用但不自动启动 / 禁用）

- Manifest 新增 requires_facilities / auto_start（*bool，用于区分
  "未声明"与"显式 false"）
- plugin-host 模块（internal/kernelmod/pluginhost）：用 kernelboot.Scheduler
  按依赖时机拉起，**不再手写两阶段**
- 运行态停启 StopPlugin/StartPlugin **可逆**：不写 disabled_plugins
  （不改用户决定）、不置 shuttingDown（之后还能加载）、会摘掉注册面
- 与 StopAll 的区别写进注释 —— StopAll 置 shuttingDown 后**永久无法加载**，
  那是进程退出用的，误用于"暂停"就是关了就死

## 数据目录迁移（伪关机 → 迁移 → 唤醒）

- kernelboot/lifecycle.go：Quiesce/Resume（可逆，区别于一次性 CloseAll），
  逆序暂停、逆序恢复、Pause 失败回滚
- kernelboot/migrate.go：BeginMigration/End 编排（先停插件 → 再停内核写者
  → 等在途归零）
- distiller/textmem 增 Pause/Resume 门（不是 cancel —— cancel 不可逆，
  恢复要重建整个对象）
- 模块 migration：体检 + 生成可执行迁移脚本

★ 迁移脚本的三个实测教训（都写成了判据）：
 1. 无条件改 /etc/systemd/system ⇒ 演练把**生产** -data 改成了演练目录。
    加 --dry-run（零改动）+ 强制校验 systemd 当前 -data == OLD
 2. 本机没装 rsync，脚本在"服务已停、数据未搬"处硬失败 ⇒ cp -a 回退，
    并明确警告不保硬链接/ACL（生产 plugindev 有大量 git 硬链接）

## 发行包修复（全部经实测确认）

 1. package-linux.sh **完全漏打 depgraph.bin** ⇒ 内核 exit 1
    （"生产构建（内嵌 hash 非空）但读不到依赖图"）
 2. build_homed 不走 Makefile ⇒ 单独修 Makefile 无效，必须同时生成图+注入
 3. build.sh 的 LDFLAGS 用**历史模块路径 gitcode.com** ⇒ -X 静默 no-op
    ⇒ --version 显示 unknown
 4. Makefile -ldflags 用**单引号** ⇒ 注入了字面 $GRAPH_HASH

## ★ build.sh 的版本号必须校验（真实事故）

原 `VERSION="$(git describe --tags --dirty)"`。无 tag 分支上它返回**分支名**
`backup/pre-identity-rewrite-20261005-51-g03d87a4e-dirty`，被注入 meta.Version
⇒ 插件握手判据 MajorVersion() 把整串当主版本 ⇒ **22 个子进程插件全部
握手失败**（"主版本不匹配"）。内核活着、systemd active、日志每条都像
插件的问题 —— 实际是发行包带着非法版本号。

修法：git describe 只在形如 vX.Y.Z 时采用，否则回退 meta.Version（权威源），
并对最终值做形态守卫。deploy/packaging/version_guard_test.go 3 条判据，
变异 2/2 咬住。

## deb 的 systemd unit 改为 guard 模式

ExecStart=/usr/bin/homed --role=guard --data /var/lib/homeagent
（worker exit 42 → guard 重拉，不经过 systemd、不计失败）
含 RestartSteps/RestartMaxDelaySec/TimeoutStopSec + 硬化
（NoNewPrivileges/ProtectSystem/ProtectHome/DevicePolicy/ReadWritePaths）。

## 其他

- internal/plugin/proc：非法 JSON 帧的报错**可定位**（内容摘要 + 可能原因 +
  修法）。生产实测 1038 条非法帧（插件往 stdout 打日志 = 污染协议通道）
- 示例插件 4 个 14 处 fmt.Printf → log.Printf
- hmapdev 模板同步修复；scaffold 判据剥离注释（模板注释里就含 fmt.Printf）

* chore: 收尾（主密钥轮换命令、IPC/知识库加固、SDK 对齐）

- cmd/homed-key-rotate：把 security 里的 RotateKey/RotateKeyFile/RekeySecrets
  串成一条**可执行**的运维路径。没有它，E-1 就只是库里的能力而不是
  "出事时能做的事"，而轮换的价值恰恰在于能执行。
- cmd/homed：kmod_runtime（模块装配入口）、plugins_scheduled（failback
  白名单）、memcandidate、bootstrap_order_test / shutdown_flush_test
- internal/ipc、internal/devicebridge、internal/knowledge：配套加固
- third_party/homeagent-sdk/sdk：PluginMgrAPI 增三态能力（mgrStop/mgrStart/
  mgrIsRuntimeStopped）+ settings 对齐

判据：bootstrap_order_test（启动顺序不依赖手写序列）、
shutdown_flush_test（停机的两条路径必须对称 —— exit 42 会跳过 defer，
热更新路径下模块关闭/flush 曾全部丢失）。

* test(security): 测试夹具改用不可误认的占位值（修 push protection 拦截）

GitHub secret scanning 拦住了推送：三处测试夹具用了"看起来像真密钥"的
字面量：

  internal/security/prefilter_test.go:39
  internal/security/store_test.go:177
  internal/security/survey_test.go:20

它们全是**假密钥**（`AKIAIOSFODNN7EXAMPLE` 是 AWS 官方文档的标准示例，
其余是 `abcdefghij...` 这类可读占位符），但扫描器无法区分 —— 它只看形态。

★ 不绕过（不用 unblock URL、不加 allowlist）：直接改夹具。
原因：一旦允许"假密钥可以通过"，真密钥混进来时就没有最后一道门了。

改法：保留**模式库匹配所需的结构**，把可识别内容换成 FAKE：
  glpat-abcdefghijklmnopqrst       → glpat-FAKE-TEST-TOKEN-NOT-REAL
  sk-abcdefghij...012345           → sk-FAKE-TEST-KEY-NOT-REAL-0000000
  AKIAIOSFODNN7EXAMPLE             → AKIA0000FAKE0000TEST   (保持 20 字符)
  ASIAIOSFODNN7EXAMPLE             → ASIA0000FAKE0000TEST
  xoxb-123456789012-abcdefghijklmnop → xoxb-FAKE-TEST-TOKEN-NOT-REAL

★ 中途踩到一次：AWS 键的模式是 `\b(AKIA|ASIA)[0-9A-Z]{16}\b`（共 20 字符），
我第一次替换成 19 字符的 `AKIAFAKETESTKEY0000` ⇒ 模式匹配不上 ⇒
TestSurvey_WhatIsCaught / TestRecognizesCommonShapes /
TestPrefilterNeverBlocksRealMatches 三条当场变红。
判据正确地拒绝了"为了过扫描器而削弱覆盖"。

顺带核实：全仓 grep 无任何真实密钥泄漏。

* fix(packaging): package-linux.sh 的版本解析与 build.sh 统一

上一版只修了 build.sh，漏了 package-linux.sh —— 它仍只看 git describe：

  VERSION="${VERSION:-$(git describe --tags --dirty)}"

无 tag 分支上 git describe 返回**分支名**
（backup/pre-identity-rewrite-20261005-56-g98850e1），守卫会正确拒绝，
但要求人**手动传 VERSION** 才能打包。而 build.sh 早已能自动回退 meta.Version
⇒ 同一个版本，走 build.sh 打得出来、走 package-linux.sh 打不出来。

危害不只是"要手动传参"：运维为了跑通会去掉守卫，而分支名一旦进
meta.Version 就是**插件协议主版本**的来源 ⇒ 22 个子进程插件全部握手失败
（这是真实发生过的事故，见 3efa4e5）。

修法：两个脚本用同一套规则（git describe 仅在 vX.Y.Z 形态时采用，
否则回退 meta.Version），并对最终值做形态守卫。

判据：TestBothPackagingScriptsShareVersionRules —— 逐个读两个脚本，
要求都能从 meta/meta.go 取权威版本、都校验 git describe 形态。
变异（把 package-linux.sh 改回旧规则）咬住并准确指出是哪个脚本。

实测：不传 VERSION 跑 package-linux.sh，输出
  [PKG] warn: git describe 给出非版本串（...），改用 meta.Version=1.4.0
  Version: 1.4.0

* fix(test): 跨仓判据在 CI 上应 skip 而非 fail（修 PR 双红）

CI 上 "Go build / vet / test" 与 "Build linux/amd64" 双红：

  --- FAIL: TestHmapdevTemplateImplementsAllPluginMgrMethods
      bridge_sync_test.go:170: 读模板: open
      ../../../third_party/homeagent-sdk/tools/hmapdev/templates/proc_main.go.tmpl:
      no such file or directory

## 根因：判据依赖了一个**被 gitignore 的路径**

`.gitignore:33` 有 `third_party/homeagent-sdk/tools/`（SDK 仓自治，本仓不跟踪）。
于是：
  · 本机（完整 SDK 检出）有该文件 ⇒ 判据通过
  · CI（只 checkout 本仓）没有该文件 ⇒ Fatalf ⇒ **必红**

我提交时只在本机跑测试、没看 CI，所以这个问题拖到 PR 才暴露。

## 修法

文件缺失时 `t.Skipf` 而不是 `t.Fatalf`。

★ 这不是"放弃检查"：
  · 跨仓一致性由 **SDK 仓自己的判据**守着
    （tools/hmapdev/scaffold_stdout_test.go 等），那里才是模板的真实归属地
  · 本判据在本机开发时**仍然生效**（已验证：有文件时 PASS，缺文件时 SKIP）

## 验证

 · 本机（有文件）  → PASS（判据真跑）
 · 模拟 CI（移走 tools/）→ SKIP（不再 fail）
 · 全量 53 包 ok / 0 fail

## 顺带

同目录还有 e2e_template_test.go 也读 tools/，但它是 `//go:build` 门控的
e2e 判据，CI 默认不跑，无需处理。

---------

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>

2026-10-17 19:18:24 +08:00

JianFeeeee

6f50ec3e20

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 的既有竞态，需单独排查。

2026-09-25 15:40:20 +08:00

JianFeeeee

69dcb2ffbc

feat(c-core): 内核编解码层 C 化第一刀 —— L1 纯函数层落地并打通构建链

第一刀只做三个纯函数（窗口推断 / 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 标记为已修复，附实测证据

2026-09-25 14:45:08 +08:00

3 Commits