mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-01 14:57:38 +00:00
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
GitHub
402
internal/kernelboot/kernelboot.go
Normal file
402
internal/kernelboot/kernelboot.go
Normal file
@ -0,0 +1,402 @@
|
||||
// Package kernelboot 是内核模块的**声明式装配调度器**。
|
||||
//
|
||||
// 设计权威：docs/zh/kernel-modularization-design.md §2.3。
|
||||
//
|
||||
// ## 要解决的问题（实测，2026-10-16）
|
||||
//
|
||||
// `cmd/homed/main.go` 里 277 行装配代码、11 处「必须早于 / 必须在之前」注释。
|
||||
// 这些**顺序依赖只写在注释里，没有任何机器校验** —— 错了不报错，
|
||||
// 而是静默降级，症状出现在很远的地方。
|
||||
//
|
||||
// 现场故障：安全模块装配晚于读 `core.llm.*` 的操作 ⇒ 密文解不开 ⇒
|
||||
// key 变空 ⇒ 所有 LLM 调用 401，而看起来像"key 配错了"。
|
||||
//
|
||||
// ## 本包提供的性质（用户指出的核心洞察）
|
||||
//
|
||||
// > 依赖图是一个由依赖关系生成的图，通过 BFS 遍历：当前遍历到的节点初始化后，
|
||||
// > 下一层 BFS 就可以安全地并行初始化 —— 这是依赖图的性质。
|
||||
//
|
||||
// 形式化：设边 `a → b` 表示 b 依赖 a。BFS 从入度 0 的节点开始分层。
|
||||
// 第 k 层任意节点的**全部前驱都在 <k 层**，且**第 k 层内部两两无边**
|
||||
// （否则其中一个会在第 ≥k+1 层）。
|
||||
//
|
||||
// ⇒ 只要第 <k 层已全部就绪，第 k 层的**任意子集**都可以并发 Init。
|
||||
//
|
||||
// 分层本身已经保证了并行安全，无需任何额外判断。
|
||||
//
|
||||
// 这就是为什么用 BFS 而不是「一次拓扑排序 + 逐个执行」：
|
||||
// 拓扑序给的是**一个**合法顺序（全串行），BFS 分层给的是**最大化并行的顺序集合**。
|
||||
//
|
||||
// ## 本包只做纯逻辑
|
||||
//
|
||||
// 不依赖任何内核子系统，因此可以用极硬的判据覆盖：
|
||||
// 分层正确性、同层并行、有界并发、三类失败（缺依赖/循环/Init 错）。
|
||||
// 真正的模块定义与接线在 Step 4 的后续增量里做（见文档 §6）。
|
||||
package kernelboot
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"sort"
|
||||
"strings"
|
||||
"sync"
|
||||
)
|
||||
|
||||
// Module 是一个可装配的内核模块。
|
||||
//
|
||||
// ★ 注意 Requires 的语义：**不是"我要在谁之后"，而是"我需要谁已就绪"**。
|
||||
// 前者是顺序（要人肉维护），后者是依赖（可由图推导）——
|
||||
// 本设计的全部价值就在于把前者换成后者。
|
||||
type Module interface {
|
||||
// Name 是模块的唯一标识（依赖图节点名）。
|
||||
Name() string
|
||||
// Requires 声明依赖的**设施名**（即其他模块 Provides 的名字）。
|
||||
Requires() []string
|
||||
// Provides 声明本模块提供的设施名（供他人 Requires 引用）。
|
||||
//
|
||||
// 允许一个模块提供多个设施名（如"配置库"同时提供"配置读"与"配置写"）。
|
||||
// 返回空表示"不提供任何可被依赖的设施"（纯副作用模块）。
|
||||
Provides() []string
|
||||
// Init 执行装配。ks 是内核**唯一的公共数据结构体**：
|
||||
// 模块从中**读**已就绪的依赖，把自己产出的公共数据**写**回它的字段。
|
||||
//
|
||||
// 返回错误表示装配失败（**必须传播，不得吞掉**）。
|
||||
Init(ks *KernelState) error
|
||||
}
|
||||
|
||||
// Plan 是一次依赖解析的结果：分好层的调度计划。
|
||||
type Plan struct {
|
||||
// Layers 是 BFS 分层结果。Layers[0] 无依赖，Layers[k+1] 依赖 Layers[0..k]。
|
||||
Layers [][]Module
|
||||
}
|
||||
|
||||
// TotalModules 返回计划里的模块总数。
|
||||
func (p *Plan) TotalModules() int {
|
||||
n := 0
|
||||
for _, l := range p.Layers {
|
||||
n += len(l)
|
||||
}
|
||||
return n
|
||||
}
|
||||
|
||||
// UnresolvableError 是"依赖图无法解析"的错误。
|
||||
//
|
||||
// 它必须携带**足够定位问题的信息**（本仓纪律：错误要能指向修复动作）：
|
||||
// - Missing：被依赖但从没被任何模块 Provides 的设施名
|
||||
// - Cycle：还在等待中的模块名（在无解时，它们构成环或环的下游）
|
||||
// - Declared：已声明提供的设施名（便于发现拼写差异，如 "configur" vs "config"）
|
||||
type UnresolvableError struct {
|
||||
Missing []string
|
||||
Cycle []string
|
||||
Declared []string
|
||||
}
|
||||
|
||||
func (e *UnresolvableError) Error() string {
|
||||
var b strings.Builder
|
||||
b.WriteString("kernelboot: 依赖图无法解析")
|
||||
if len(e.Missing) > 0 {
|
||||
fmt.Fprintf(&b, "；依赖了不存在的设施: %v（已声明可提供的: %v）",
|
||||
e.Missing, e.Declared)
|
||||
}
|
||||
if len(e.Cycle) > 0 {
|
||||
fmt.Fprintf(&b, "；循环依赖或等待环上的模块: %v", e.Cycle)
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
|
||||
// Build 解析依赖并分层。
|
||||
//
|
||||
// 算法（文档 §2.3.2）：
|
||||
//
|
||||
// ready := {} // 已就绪的设施名
|
||||
// for 还有未装配的模块 {
|
||||
// layer := 所有 Requires ⊆ ready 的模块
|
||||
// if layer 为空 => 无解（缺依赖或环）=> 报错
|
||||
// ready ∪= 所有 layer 成员的 Provides
|
||||
// }
|
||||
//
|
||||
// 返回的 Plan 可直接按层执行（层内可并行）。
|
||||
func Build(modules []Module) (*Plan, error) {
|
||||
// ① 先收集所有被声明的设施名，用于区分"缺依赖"与"有环"两类错误。
|
||||
declared := map[string]bool{}
|
||||
for _, m := range modules {
|
||||
for _, p := range m.Provides() {
|
||||
declared[p] = true
|
||||
}
|
||||
}
|
||||
|
||||
// ② 检查重名（两个模块 Provides 同名设施 ⇒ 歧义，必须报错）
|
||||
// 为何必须拦：重名会让"依赖了谁"变得不确定，
|
||||
// 而依赖图的价值恰恰在于确定性。
|
||||
owner := map[string]string{} // 设施名 -> 提供者模块名
|
||||
var dupes []string
|
||||
for _, m := range modules {
|
||||
for _, p := range m.Provides() {
|
||||
if prev, ok := owner[p]; ok && prev != m.Name() {
|
||||
dupes = append(dupes, fmt.Sprintf("%s（%s 与 %s 都声明提供）", p, prev, m.Name()))
|
||||
continue
|
||||
}
|
||||
owner[p] = m.Name()
|
||||
}
|
||||
}
|
||||
if len(dupes) > 0 {
|
||||
sort.Strings(dupes)
|
||||
return nil, fmt.Errorf("kernelboot: 设施名被重复声明: %v", dupes)
|
||||
}
|
||||
|
||||
// ③ 模块名不得重复
|
||||
seen := map[string]bool{}
|
||||
for _, m := range modules {
|
||||
if seen[m.Name()] {
|
||||
return nil, fmt.Errorf("kernelboot: 模块名重复: %s", m.Name())
|
||||
}
|
||||
seen[m.Name()] = true
|
||||
}
|
||||
|
||||
// ④ BFS 分层
|
||||
ready := map[string]bool{}
|
||||
pending := make([]Module, len(modules))
|
||||
copy(pending, modules)
|
||||
var layers [][]Module
|
||||
|
||||
for len(pending) > 0 {
|
||||
var layer []Module
|
||||
var rest []Module
|
||||
for _, m := range pending {
|
||||
if satisfied(m.Requires(), ready) {
|
||||
layer = append(layer, m)
|
||||
} else {
|
||||
rest = append(rest, m)
|
||||
}
|
||||
}
|
||||
if len(layer) == 0 {
|
||||
// 无解：区分"缺依赖"与"循环"
|
||||
return nil, diagnoseUnresolvable(rest, declared, owner, ready)
|
||||
}
|
||||
// 同层内按名字排序：让分层结果**稳定可复现**（便于判据断言与日志对照）。
|
||||
// 并行执行顺序不影响正确性（同层无边），但稳定的输出让"层次变了"这类
|
||||
// 隐式变更容易被发现。
|
||||
sort.Slice(layer, func(i, j int) bool { return layer[i].Name() < layer[j].Name() })
|
||||
layers = append(layers, layer)
|
||||
|
||||
for _, m := range layer {
|
||||
for _, p := range m.Provides() {
|
||||
ready[p] = true
|
||||
}
|
||||
}
|
||||
pending = rest
|
||||
}
|
||||
|
||||
return &Plan{Layers: layers}, nil
|
||||
}
|
||||
|
||||
// satisfied 报告 requires 是否全部已在 ready 里。
|
||||
func satisfied(requires []string, ready map[string]bool) bool {
|
||||
for _, r := range requires {
|
||||
if !ready[r] {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
// diagnoseUnresolvable 区分两类无解原因，并给出可定位的信息。
|
||||
//
|
||||
// 为何要区分：两者的**修复动作完全不同**——
|
||||
//
|
||||
// · 缺依赖 ⇒ 去补 Provides（常是拼写错误）
|
||||
// · 有环 ⇒ 去拆环（设计问题）
|
||||
//
|
||||
// 只报"有环"会让人去错误的方向查。
|
||||
func diagnoseUnresolvable(pending []Module, declared map[string]bool, owner map[string]string, ready map[string]bool) error {
|
||||
var missing, cycle []string
|
||||
for _, m := range pending {
|
||||
cycle = append(cycle, m.Name())
|
||||
for _, r := range m.Requires() {
|
||||
// 该依赖既没被任何模块声明提供、也不在 ready ⇒ 真正的"不存在"
|
||||
if !declared[r] && !ready[r] {
|
||||
missing = append(missing, fmt.Sprintf("%s（%s 需要）", r, m.Name()))
|
||||
}
|
||||
}
|
||||
}
|
||||
sort.Strings(missing)
|
||||
sort.Strings(cycle)
|
||||
|
||||
declaredList := make([]string, 0, len(declared))
|
||||
for d := range declared {
|
||||
declaredList = append(declaredList, d)
|
||||
}
|
||||
sort.Strings(declaredList)
|
||||
|
||||
return &UnresolvableError{Missing: missing, Cycle: cycle, Declared: declaredList}
|
||||
}
|
||||
|
||||
// RunOptions 控制执行。
|
||||
type RunOptions struct {
|
||||
// MaxParallel 是**层内**的并发上限（<=0 表示不限制）。
|
||||
//
|
||||
// ★ 为何必须有界：同层无边保证**安全**，但不保证**无代价**——
|
||||
// 42 个插件同时 spawn 会造成内存/CPU 尖峰（每个 ~11MB 二进制加载 + 握手）。
|
||||
// 并发度只影响**速度**，不影响**顺序**（同层节点两两无边，
|
||||
// 无论以什么顺序完成，下一层的就绪条件都相同）。
|
||||
MaxParallel int
|
||||
|
||||
// OnLayerDone 在每层完成后回调（层号从 0 起）。可为 nil。
|
||||
OnLayerDone func(layerIndex int, modules []Module)
|
||||
|
||||
// State 是内核**唯一的公共数据结构体**（用户设计）：
|
||||
// 模块从中读依赖、往它写自己的产物。
|
||||
//
|
||||
// 为何由调用方传入而不是 Run 内部自建：产物在 Run 返回后**仍然要用**
|
||||
// （如 LuaVM、Memory 要一直活着），所以它必须比 Run 活得久。
|
||||
State *KernelState
|
||||
|
||||
// Bus 是状态同步总线。非 nil 时，Run 会在**每个层边界**把该层模块贡献的
|
||||
// 设施标记为就绪（设计 §2.6.2）。
|
||||
//
|
||||
// ★ 为何由 Run 自动写而不是各模块自己写：
|
||||
// 若模块自己 MarkReady，顺序取决于**层内并发的完成顺序** ⇒ 不可复现；
|
||||
// 而且模块可能"忘记标记"（静默漏掉一个设施 ⇒ 插件永远等不到它就绪）。
|
||||
// 由 Run 在层边界统一写，既确定又不可能漏。
|
||||
Bus *SyncBus
|
||||
}
|
||||
|
||||
// RunResult 是执行结果。
|
||||
type RunResult struct {
|
||||
// LayerCount 是实际执行的层数。
|
||||
LayerCount int
|
||||
// MaxConcurrent 是观测到的**峰值并发**（用于判据证明并行确实发生）。
|
||||
MaxConcurrent int
|
||||
// Order 是按完成顺序记录的模块名（仅用于诊断/日志，**不作正确性依据**）。
|
||||
Order []string
|
||||
}
|
||||
|
||||
// Run 按计划执行：逐层 Init，层内有界并行。
|
||||
//
|
||||
// 失败策略（文档 §2.3.3）：**任何 Init 失败都令整体失败**。
|
||||
// 不静默跳过、不"带着半初始化状态继续"——后者正是病 A 的形态。
|
||||
//
|
||||
// 同层内若**多个**模块失败，返回第一个（按名字序，稳定）；
|
||||
// 但**不等同于只跑一个**：同层其余模块仍会被执行完（避免半途中断造成更乱的状态）。
|
||||
func Run(plan *Plan, opts RunOptions) (*RunResult, error) {
|
||||
if plan == nil {
|
||||
return nil, fmt.Errorf("kernelboot: 计划为 nil")
|
||||
}
|
||||
res := &RunResult{}
|
||||
var orderMu sync.Mutex
|
||||
|
||||
ks := opts.State
|
||||
if ks == nil {
|
||||
ks = NewKernelState()
|
||||
}
|
||||
|
||||
// ★ 执行前把**全部**模块声明的设施登记为"内核注册过"。
|
||||
//
|
||||
// 这样插件的 `requires_facilities` 校验（防拼错 ⇒ 静默永不启动）
|
||||
// 在"装配结果之外"也成立：即使某层失败、后面的模块没跑，
|
||||
// "这个设施名是模块声明过的"依然为真（语义与"是否已就绪"解耦）。
|
||||
if opts.Bus != nil {
|
||||
var all []string
|
||||
for _, layer := range plan.Layers {
|
||||
for _, m := range layer {
|
||||
all = append(all, m.Provides()...)
|
||||
}
|
||||
}
|
||||
opts.Bus.MarkDeclared(all)
|
||||
// ★ 把 bus 放进 KernelState：模块的 Init 只能看到 ks，
|
||||
// 而 plugin-host 需要订阅状态变化（挂"等 agent 就绪"的回调）。
|
||||
// 不放这里 ⇒ 模块拿不到 bus（实测撞到）。
|
||||
ks.SyncBus = opts.Bus
|
||||
}
|
||||
|
||||
for li, layer := range plan.Layers {
|
||||
if len(layer) == 0 {
|
||||
continue
|
||||
}
|
||||
limit := opts.MaxParallel
|
||||
if limit <= 0 || limit > len(layer) {
|
||||
limit = len(layer)
|
||||
}
|
||||
|
||||
sem := make(chan struct{}, limit)
|
||||
var wg sync.WaitGroup
|
||||
errs := make([]error, len(layer))
|
||||
|
||||
// 峰值并发观测（判据用它证明"并行确实发生了"）
|
||||
var active, peak int
|
||||
var peakMu sync.Mutex
|
||||
|
||||
for i, m := range layer {
|
||||
wg.Add(1)
|
||||
go func(i int, m Module) {
|
||||
defer wg.Done()
|
||||
sem <- struct{}{}
|
||||
defer func() { <-sem }()
|
||||
|
||||
peakMu.Lock()
|
||||
active++
|
||||
if active > peak {
|
||||
peak = active
|
||||
}
|
||||
peakMu.Unlock()
|
||||
|
||||
err := m.Init(ks)
|
||||
|
||||
peakMu.Lock()
|
||||
active--
|
||||
peakMu.Unlock()
|
||||
|
||||
orderMu.Lock()
|
||||
res.Order = append(res.Order, m.Name())
|
||||
orderMu.Unlock()
|
||||
|
||||
if err != nil {
|
||||
errs[i] = fmt.Errorf("模块 %s 装配失败: %w", m.Name(), err)
|
||||
}
|
||||
}(i, m)
|
||||
}
|
||||
wg.Wait()
|
||||
|
||||
peakMu.Lock()
|
||||
if peak > res.MaxConcurrent {
|
||||
res.MaxConcurrent = peak
|
||||
}
|
||||
peakMu.Unlock()
|
||||
|
||||
// 层内失败：收集后**一次性**报告（不要 fail-fast 丢掉其他失败信息）
|
||||
var failed []string
|
||||
for _, e := range errs {
|
||||
if e != nil {
|
||||
failed = append(failed, e.Error())
|
||||
}
|
||||
}
|
||||
if len(failed) > 0 {
|
||||
sort.Strings(failed)
|
||||
return res, fmt.Errorf("kernelboot: 第 %d 层装配失败: %s",
|
||||
li, strings.Join(failed, "; "))
|
||||
}
|
||||
|
||||
res.LayerCount++
|
||||
// ★ 层边界：把本层贡献的设施标记就绪（设计 §2.6.2）。
|
||||
// 在层内并发**全部完成之后**统一标记 ⇒ 就绪顺序确定、可复现。
|
||||
if opts.Bus != nil {
|
||||
var provides []string
|
||||
for _, m := range layer {
|
||||
provides = append(provides, m.Provides()...)
|
||||
}
|
||||
opts.Bus.MarkLayerReady(provides)
|
||||
}
|
||||
if opts.OnLayerDone != nil {
|
||||
opts.OnLayerDone(li, layer)
|
||||
}
|
||||
}
|
||||
|
||||
// ★ 全部层完成 ⇒ 内核完全初始化。
|
||||
//
|
||||
// 这是"未声明依赖的插件"的启动信号（默认路径 = 现行为，设计 §2.6.5）。
|
||||
// 它在**所有层都成功之后**才发 —— 中途失败会提前 return，不发这个信号，
|
||||
// 于是那些插件**不会被拉起**（这是对的：内核没装好就拉插件 = 病 A）。
|
||||
if opts.Bus != nil {
|
||||
opts.Bus.MarkKernelComplete()
|
||||
}
|
||||
return res, nil
|
||||
}
|
||||
Reference in New Issue
Block a user