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>
This commit is contained in:
JianFeeeee
2026-10-17 19:18:24 +08:00
committed by GitHub
parent 03d87a4e21
commit a68d6a428c
266 changed files with 30185 additions and 1424 deletions

View File

@ -0,0 +1,319 @@
package kernelboot
// 内核装配层(syncbus / scheduler / KernelState)的**压力测试**。
//
// ## 为什么必须有压力测试(不是"跑一遍判据就够了")
//
// 这层代码的并发行为**只有压力才能暴露**:
// · 判据用 2~3 个 goroutine 验证语义正确性
// · 压力用数百 goroutine × 数千轮验证**没有数据竞争 / 死锁 / 状态丢失**
//
// 本仓已有两处真实教训支持这个判断:
// ① ModuleView 第一版把「当前模块」放在共享对象上 ⇒ 判据**偶发**失败
// (3 次里 1 次)—— 那是"偶发"而不是"必现",正是压力测试的领域
// ② syncbus 的 OnUpdate 若持锁回调 ⇒ **死锁**(只在回调读状态时触发)
//
// ## 压什么(本层真实的并发面)
//
// · SyncBus:内核写(MarkDeclared/MarkLayerReady/MarkKernelComplete)
// 与插件读(Known/IsReady/Snapshot/AllReady/**订阅回调**)并发
// · Scheduler:多 goroutine 并发 Submit(同一插件可能被重复提交)
// + 状态变化并发触发 evaluate
// · KernelState:同层模块**并行**写**各自**字段(不同字段,无竞争)
// · PlanFromGraph:并发读图(只读,但验证无共享可变状态)
// · Run:真实分层执行,验证有界并发真的没超
import (
"fmt"
"sync"
"sync/atomic"
"testing"
"time"
)
// ★★★ 压力:**SyncBus 读写并发**(内核写 + N 个插件读 + 订阅回调)。
//
// 用 -race 跑时,任何未保护的状态都会报数据竞争。
func TestStressSyncBusConcurrentReadWrite(t *testing.T) {
bus := NewSyncBus()
const readers = 64
const facilities = 200
var callbacks int64
// 订阅者**读状态**(这正是死锁的触发条件:若 fire 持锁调用回调,
// 回调里 Snapshot() 会等读锁 ⇒ 死锁。压力下必现)
for i := 0; i < 8; i++ {
bus.OnUpdate(func(s SyncState) {
_ = s.Snapshot()
_ = s.AllReady([]string{"llm"})
atomic.AddInt64(&callbacks, 1)
})
}
var wg sync.WaitGroup
stop := make(chan struct{})
// 读侧:N 个"插件"持续查询
for i := 0; i < readers; i++ {
wg.Add(1)
go func(i int) {
defer wg.Done()
for {
select {
case <-stop:
return
default:
}
f := fmt.Sprintf("fac%d", i%facilities)
_ = bus.Known(f)
_ = bus.IsReady(f)
_ = bus.Snapshot()
_ = bus.ReadyInOrder()
_ = bus.KernelComplete()
_ = bus.AllReady([]string{"fac1", "fac2"})
}
}(i)
}
// 写侧:内核持续标记
wg.Add(1)
go func() {
defer wg.Done()
for i := 0; i < facilities; i++ {
bus.MarkLayerReady([]string{fmt.Sprintf("fac%d", i)})
}
}()
// 让它跑一会儿
time.Sleep(400 * time.Millisecond)
bus.MarkKernelComplete()
time.Sleep(100 * time.Millisecond)
close(stop)
wg.Wait()
if atomic.LoadInt64(&callbacks) == 0 {
t.Fatal("订阅回调从未被调用 —— 压力没有真正覆盖通知路径")
}
if !bus.KernelComplete() {
t.Fatal("KernelComplete 应已置位")
}
t.Logf("回调触发 %d 次,%d 个并发读者", atomic.LoadInt64(&callbacks), readers)
}
// ★★★ 压力:**多 goroutine 并发 Submit**(同一插件可能被重复提交)。
//
// 真实场景:插件加载器可能分批提交(发现新插件、重扫目录),
// 而每次提交都会触发状态评估。并发下要保证:
//
// · 不重复拉起同一插件(幂等)
// · 不丢插件(全部最终被拉起)
// · 无数据竞争
func TestStressSchedulerConcurrentSubmit(t *testing.T) {
bus := NewSyncBus()
bus.MarkDeclared([]string{"config", "llm", "memory"})
// ★ 必须 MarkLayerReady:MarkDeclared 只登记"名字存在",
// 不代表就绪。插件要求 config **就绪**才拉起。
// (我第一版漏了这步 ⇒ 压力判据报"0 个拉起" —— 那是判据 bug,非缺陷。)
bus.MarkLayerReady([]string{"config", "llm", "memory"})
const plugins = 300
var mu sync.Mutex
launched := map[string]int{}
sch := NewScheduler(bus, func(p PluginSpec) error {
mu.Lock()
launched[p.Name]++
mu.Unlock()
return nil
})
sch.SetLaunchErrorHandler(func(p PluginSpec, err error) {
t.Errorf("不应有拉起错误: %v", err)
})
// 16 个 goroutine 并发提交同一批插件(模拟重复扫描)
var wg sync.WaitGroup
for g := 0; g < 16; g++ {
wg.Add(1)
go func(g int) {
defer wg.Done()
var specs []PluginSpec
for i := 0; i < plugins; i++ {
specs = append(specs, PluginSpec{
Name: fmt.Sprintf("p%03d", i),
RequiresFacilities: []string{"config"},
AutoStart: true,
})
}
sch.Submit(specs)
}(g)
}
bus.MarkKernelComplete()
wg.Wait()
mu.Lock()
defer mu.Unlock()
if len(launched) != plugins {
t.Fatalf("★ 应拉起 %d 个插件,实际 %d(并发提交丢了插件)", plugins, len(launched))
}
for name, n := range launched {
if n != 1 {
t.Fatalf("★ 插件 %s 被拉起 %d 次(应恰好 1 次 —— 并发下幂等性破坏)", name, n)
}
}
}
// ★★★ 压力:**状态变化 + 提交并发**(真实时序:内核在标记就绪的同时插件在提交)。
func TestStressSchedulerConcurrentStateChange(t *testing.T) {
bus := NewSyncBus()
bus.MarkDeclared([]string{"config", "llm", "memory", "stagehost"})
var launched int64
sch := NewScheduler(bus, func(p PluginSpec) error {
atomic.AddInt64(&launched, 1)
return nil
})
sch.SetLaunchErrorHandler(func(p PluginSpec, err error) {})
const plugins = 200
var wg sync.WaitGroup
// 写侧:内核逐层标记就绪
wg.Add(1)
go func() {
defer wg.Done()
for _, f := range []string{"config", "llm", "memory", "stagehost"} {
bus.MarkLayerReady([]string{f})
}
bus.MarkKernelComplete()
}()
// 提交侧:8 个并发提交者
for g := 0; g < 8; g++ {
wg.Add(1)
go func() {
defer wg.Done()
for i := 0; i < plugins; i++ {
sch.Submit([]PluginSpec{{
Name: fmt.Sprintf("q%03d", i),
RequiresFacilities: []string{"config"},
AutoStart: true,
}})
}
}()
}
wg.Wait()
bus.MarkKernelComplete() // 再触发一次评估,确保挂起的也被拉起
if n := atomic.LoadInt64(&launched); n != plugins {
t.Fatalf("★ 并发 提交×状态变化 下应拉起 %d 个,实际 %d", plugins, n)
}
}
// ★★★ 压力:**PlanFromGraph 并发读**(多插件/多协程同时读启动计划)。
func TestStressPlanFromGraphConcurrentRead(t *testing.T) {
mods := planTestModules()
built, err := Build(mods)
if err != nil {
t.Fatal(err)
}
gf := decodeGraphOrFatal(t, EncodeGraph(planToEdgesForTest(built)))
var wg sync.WaitGroup
errs := make(chan error, 64)
for i := 0; i < 64; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for j := 0; j < 50; j++ {
plan, err := PlanFromGraph(gf, mods)
if err != nil {
errs <- err
return
}
if len(plan.Layers) != 3 {
errs <- fmt.Errorf("层数不对: %d", len(plan.Layers))
return
}
}
}()
}
wg.Wait()
close(errs)
for err := range errs {
t.Fatal(err)
}
}
// ★★★ 压力:**Run 的并发上限真的生效**(大量模块同层时不得超出)。
//
// ★ 这条与判据的 TestRunRespectsMaxParallel 不同:那条 8 个模块,
// 这条 **128 个模块**同层 —— 验证信号量在高压下不漏(观察峰值)。
func TestStressRunRespectsMaxParallelAtScale(t *testing.T) {
const n = 128
const maxP = 8
var active, peak int64
var mu sync.Mutex
var mods []Module
for i := 0; i < n; i++ {
mods = append(mods, &fakeModule{
name: fmt.Sprintf("m%03d", i),
provides: []string{fmt.Sprintf("f%03d", i)},
onInit: func() {
cur := atomic.AddInt64(&active, 1)
mu.Lock()
if cur > peak {
peak = cur
}
mu.Unlock()
time.Sleep(2 * time.Millisecond)
atomic.AddInt64(&active, -1)
},
})
}
plan, err := Build(mods)
if err != nil {
t.Fatal(err)
}
res, err := Run(plan, RunOptions{MaxParallel: maxP})
if err != nil {
t.Fatal(err)
}
mu.Lock()
observed := peak
mu.Unlock()
if observed > maxP {
t.Fatalf("★ 并发上限 %d 被突破:观测峰值 %d(%d 个模块同层)", maxP, observed, n)
}
if len(res.Order) != n {
t.Fatalf("应执行 %d 个模块,实际 %d", n, len(res.Order))
}
t.Logf("%d 个模块同层,上限 %d,观测峰值 %d", n, maxP, observed)
}
// ★★★ 压力:**KernelState 同层并行写**(各写自己字段,无竞争)。
func TestStressKernelStateParallelWrites(t *testing.T) {
ks := NewKernelState()
const n = 256
var wg sync.WaitGroup
for i := 0; i < n; i++ {
wg.Add(1)
go func(i int) {
defer wg.Done()
// 每个"模块"只写自己字段 —— 这正是真实约定。
// 若有人违反(写别人的字段),-race 会报。
ks.AddCloser(func() {})
}(i)
}
wg.Wait()
if len(ks.Closers) != n {
t.Fatalf("应记录 %d 个关闭函数,实际 %d(AddCloser 有丢失)", n, len(ks.Closers))
}
if err := ks.CloseAll(); err != nil {
t.Fatal(err)
}
if len(ks.Closers) != 0 {
t.Fatal("CloseAll 后应清空")
}
}