jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 14:57:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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
Download Patch File Download Diff File Expand all files Collapse all files

194
internal/kernelmod/pluginhost/catalog.go Normal file
View File

@ -0,0 +1,194 @@
// Package pluginhost 是 plugin-host 模块：**插件宿主**（设计 §2.6 + 用户要求）。
//
// ## 职责（用户的说法）
//
// > 插件管理器不应该在被拉起后就去读插件列表获取元数据并写入缓存准备拉起吗？
//
// 本模块做四件事：
//
// ① **扫一次**插件目录 → 元数据**缓存**（PluginCatalog）
// ② 按**三形态**分流（自动启动 / 启用但不自动启动 / 禁用）
// ③ 按依赖声明（requires_facilities）决定**逐个插件**的拉起时机
// ④ 执行拉起（用 stage-host 产出的 Registry）
//
// ## ★ 为什么它是**内核模块**而不是插件（架构决定）
//
// 用户选定的方案 A。理由（自举问题）：
//
// · `pluginmgr` 是**插件** ⇒ 它自己要被拉起 ⇒ 若调度逻辑在它内部，
// 就得先拉起自己才能拉起自己（循环）。
// · 而调度器要订阅内核的 syncbus（内核设施），依附内核模块更自然。
//
// ⇒ 调度放内核模块（本包），`pluginmgr` 插件只保留**人机界面**职责
// （列列表/启停/装卸的工具与 HTTP）。
//
// ## ★ 依赖（关键：**不依赖 agent**）
//
// Requires: config, lua, supervisor, tracker, memory, textmem, docmem,
// knowledge, kernel-io, stage-host
//
// 插件**加载**需要的是 stage-host（Registry + StageHost）与几个底层设施，
// **不需要** agent。原先把 wirePluginSDK 放在 agent 模块里，导致插件加载
// 被迫排在 agent 之后（agent 层实测 35 秒）。
//
// 实测发现：SDK 的 `Plugin` 接口只有 `Name/Start/Stop`，**没有 Configure**
// （那条"插件 Configure 需要 StatusProvider"的注释已过时）。
// 且唯一在 Start 阶段引 Status 的插件（healthcheck）是 **nil-guarded** 的。
// ⇒ 拆成"底层 7 项在这里注入、agent 相关的 2 项由 agent 模块**后补注入**"。
package pluginhost
import (
"os"
"path/filepath"
"sort"
"time"
"github.com/JianFeeeee/HomeAgent/internal/plugin"
)
// PluginMeta 是单个插件的**元数据**（缓存项）。
//
// ★ 为何不直接用 plugin.PluginManifest：缓存只保留"调度与展示"需要的字段，
// 且加一层让"元数据来源"可替换（将来若从 DB 而非文件读，上层不用改）。
type PluginMeta struct {
Name string
// RequiresFacilities 是声明的启动前置设施（空 = 等内核完全初始化）。
RequiresFacilities []string
// AutoStart：true=伴随启动；false=启用但不自动启动（等显式启用）。
AutoStart bool
// Disabled 来自 disabled_plugins 配置（持久禁用，最高优先级）。
Disabled bool
// 以下用于展示（pluginmgr 的列表/状态）
Version string
Description string
NameZh string
Tags []string
// ManifestPath 便于诊断（"这个插件的元数据从哪来的"）
ManifestPath string
// ScannedAt 记录扫描时刻（缓存新鲜度；也便于"元数据过期"排查）
ScannedAt time.Time
}
// PluginCatalog 是插件**元数据缓存**。
//
// ## 为什么要有它（用户指出的设计）
//
// 原先元数据散落且**每次重扫**：
//
// · cmd/homed 的 collectPluginSpecs（决定启动时机）
// · pluginmgr 的 listPlugins（人看的列表）
//
// ⇒ 扫一次、缓存下来，供调度器 / pluginmgr / 显式启用路径共用。
//
// ## ★ 并发
//
// 调度在装配期（单线程语义），但 pluginmgr 的 HTTP 工具可能在运行期读它。
// 用 RWMutex 保护；读多写少（只在扫描时写）。
type PluginCatalog struct {
mu *rwMutex
items map[string]*PluginMeta
dir string
}
// newCatalog 创建空缓存。
func newCatalog(dir string) *PluginCatalog {
return &PluginCatalog{mu: newRWMutex(), items: map[string]*PluginMeta{}, dir: dir}
}
// Get 取单个插件的元数据。
func (c *PluginCatalog) Get(name string) (*PluginMeta, bool) {
c.mu.RLock()
defer c.mu.RUnlock()
m, ok := c.items[name]
return m, ok
}
// Names 返回全部插件名（升序，可复现）。
func (c *PluginCatalog) Names() []string {
c.mu.RLock()
defer c.mu.RUnlock()
out := make([]string, 0, len(c.items))
for n := range c.items {
out = append(out, n)
}
sort.Strings(out)
return out
}
// All 返回全部元数据（按名字升序）。
func (c *PluginCatalog) All() []*PluginMeta {
c.mu.RLock()
defer c.mu.RUnlock()
names := make([]string, 0, len(c.items))
for n := range c.items {
names = append(names, n)
}
sort.Strings(names)
out := make([]*PluginMeta, 0, len(names))
for _, n := range names {
out = append(out, c.items[n])
}
return out
}
// Dir 返回被扫描的插件目录。
func (c *PluginCatalog) Dir() string { return c.dir }
// Size 返回缓存条目数。
func (c *PluginCatalog) Size() int {
c.mu.RLock()
defer c.mu.RUnlock()
return len(c.items)
}
// set 写入一条（扫描时用）。
func (c *PluginCatalog) set(m *PluginMeta) {
c.mu.Lock()
defer c.mu.Unlock()
c.items[m.Name] = m
}
// scanCatalog 扫插件目录，把元数据写进缓存。
//
// ## 容错策略
//
// 无 manifest / 解析失败 ⇒ **跳过该目录**（不是错误）：插件目录里可能有
// 非插件内容（README、临时备份、install 中途的半成品）。返回跳过列表
// 供日志说明"为什么某个目录没被识别成插件"。
func scanCatalog(dir string, isDisabled func(string) bool) (*PluginCatalog, []string) {
c := newCatalog(dir)
entries, err := os.ReadDir(dir)
if err != nil {
return c, []string{"读取插件目录失败: " + err.Error()}
}
var skipped []string
for _, e := range entries {
if !e.IsDir() {
continue
}
name := e.Name()
mft, err := plugin.ReadManifest(filepath.Join(dir, name))
if err != nil {
skipped = append(skipped, name)
continue
}
display := mft.Name
if display == "" {
display = name
}
c.set(&PluginMeta{
Name: name, // ★ 用**目录名**：它与 LoadOneDir/注册表键一致
RequiresFacilities: mft.RequiresFacilities,
AutoStart: mft.ShouldAutoStart(),
Disabled: isDisabled != nil && isDisabled(name),
Version: mft.Version,
Description: mft.Description,
NameZh: mft.NameZh,
Tags: mft.Tags,
ManifestPath: filepath.Join(dir, name, "plugin.json"),
ScannedAt: time.Now(),
})
}
return c, skipped
}

446
internal/kernelmod/pluginhost/catalog_test.go Normal file
View File

@ -0,0 +1,446 @@
package pluginhost
// plugin-host（插件宿主）的判据（2026-10-16）。
//
// 设计见 docs/zh/kernel-modularization-design.md §2.6 + 用户方案 A。
//
// ## 这组判据守什么
//
// ① **三形态分流正确**（用户明确要求：自动启动 / 启用但不自动启动 / 禁用）
// ② **元数据缓存**（用户指出的设计：扫一次、供调度与展示共用）
// ③ **内置插件不被漏掉** ← 这是我实际踩过的回归（19 个全丢）
// ④ 关键顺序：failback 白名单必须在插件拉起前生效
import (
"go/ast"
"go/parser"
"go/token"
"os"
"path/filepath"
"sort"
"strings"
"testing"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
)
// makePluginDir 造一个带 plugin.json 的插件目录。
func makePluginDir(t *testing.T, root, name, manifest string) {
t.Helper()
d := filepath.Join(root, name)
if err := os.MkdirAll(d, 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(d, "plugin.json"), []byte(manifest), 0o644); err != nil {
t.Fatal(err)
}
}
// ★★★ 判据：**三形态分流正确**（用户设计要求的三种形态）。
func TestClassifyThreeForms(t *testing.T) {
root := t.TempDir()
// ① 自动启动 + 声明依赖
makePluginDir(t, root, "auto_declared",
`{"name":"auto_declared","version":"1","entry":"plugin.bin","requires_facilities":["config"]}`)
// ① 自动启动 + 未声明
makePluginDir(t, root, "auto_plain",
`{"name":"auto_plain","version":"1","entry":"plugin.bin"}`)
// ② 启用但不自动启动
makePluginDir(t, root, "manual",
`{"name":"manual","version":"1","entry":"plugin.bin","requires_facilities":["config"],"auto_start":false}`)
// ③ 禁用
makePluginDir(t, root, "banned",
`{"name":"banned","version":"1","entry":"plugin.bin"}`)
cat, _ := scanCatalog(root, func(n string) bool { return n == "banned" })
g := classify(cat)
eq := func(got, want []string, what string) {
t.Helper()
sort.Strings(got)
sort.Strings(want)
if strings.Join(got, ",") != strings.Join(want, ",") {
t.Errorf("★ %s: 期望 %v 实际 %v", what, want, got)
}
}
eq(g.autoStart, []string{"auto_declared", "auto_plain"}, "① 自动启动")
eq(g.declared, []string{"auto_declared"}, "① 中声明了依赖的")
eq(g.manual, []string{"manual"}, "② 启用但不自动启动")
eq(g.disabled, []string{"banned"}, "③ 持久禁用")
// ★ 关键互斥：三形态必须互不重叠（一个插件只能属于一种）
inBoth := func(a, b []string, an, bn string) {
t.Helper()
m := map[string]bool{}
for _, x := range a {
m[x] = true
}
for _, x := range b {
if m[x] {
t.Errorf("★ %s 与 %s 同时包含 %s（三形态必须互斥）", an, bn, x)
}
}
}
inBoth(g.autoStart, g.manual, "autoStart", "manual")
inBoth(g.autoStart, g.disabled, "autoStart", "disabled")
inBoth(g.manual, g.disabled, "manual", "disabled")
}
// ★★★ 判据：**元数据缓存内容正确**（用户设计：读列表→写缓存）。
func TestCatalogCachesMetadata(t *testing.T) {
root := t.TempDir()
makePluginDir(t, root, "p1",
`{"name":"p1","name_zh":"一","version":"2.3.4","entry":"plugin.bin",
"description":"演示","requires_facilities":["config","llm"],"tags":["a","b"]}`)
cat, noskip := scanCatalog(root, nil)
if len(noskip) != 0 {
t.Errorf("不该有跳过的目录: %v", noskip)
}
if cat.Size() != 1 {
t.Fatalf("缓存应有 1 条，实际 %d", cat.Size())
}
m, ok := cat.Get("p1")
if !ok {
t.Fatal("取不到 p1 的元数据")
}
// 每个字段都要缓存对（调度靠 RequiresFacilities，展示靠其余）
if len(m.RequiresFacilities) != 2 || m.RequiresFacilities[0] != "config" {
t.Errorf("RequiresFacilities 未正确缓存: %v", m.RequiresFacilities)
}
if !m.AutoStart {
t.Error("缺省 auto_start 应为 true")
}
if m.Version != "2.3.4" || m.NameZh != "一" || m.Description != "演示" {
t.Errorf("展示字段未正确缓存: %+v", m)
}
if len(m.Tags) != 2 {
t.Errorf("Tags 未正确缓存: %v", m.Tags)
}
if m.ManifestPath == "" || m.ScannedAt.IsZero() {
t.Error("诊断字段（路径/扫描时刻）应被记录")
}
// 缓存必须能列出（pluginmgr 的列表用它）
if names := cat.Names(); len(names) != 1 || names[0] != "p1" {
t.Errorf("Names 不对: %v", names)
}
}
// ★★★ 判据：**无 plugin.json 的目录被记为"无 manifest"而不是"错误"**。
//
// ★ 这条守的是我实际踩过的回归：19 个**内置插件**目录没有 plugin.json
// （它们是编译期工厂），我第一版把它们记成"跳过 19 个非插件目录"并
// **完全没有加载它们**（webui/pluginmgr/cli/files/timer… 全丢）。
//
// 判据分两层：
//
// · 本层：scanCatalog 必须**如实**报告哪些目录没 manifest（便于诊断）
// · 装配层：LoadSkipping 必须补上内置插件（见 TestBuiltinsNotDropped）
func TestScanReportsNoManifestDirs(t *testing.T) {
root := t.TempDir()
makePluginDir(t, root, "has_manifest", `{"name":"has_manifest","version":"1","entry":"plugin.bin"}`)
// 模拟内置插件目录：只有可执行文件，没有 plugin.json
builtin := filepath.Join(root, "builtin_plugin")
os.MkdirAll(builtin, 0o755)
os.WriteFile(filepath.Join(builtin, "plugin.bin"), []byte("x"), 0o755)
cat, noManifest := scanCatalog(root, nil)
if cat.Size() != 1 {
t.Errorf("缓存应只含带 manifest 的（1 条），实际 %d", cat.Size())
}
if len(noManifest) != 1 || noManifest[0] != "builtin_plugin" {
t.Fatalf("★ 无 manifest 的目录必须被如实报告（便于区分「内置插件」与「坏插件」）: %v",
noManifest)
}
}
// ★★★ 判据：**内置插件不会被漏掉**（行为判据，回归守）。
//
// ## 为什么这条必须存在
//
// 我第一版让 plugin-host 只处理"有 plugin.json 的外部插件"，
// 结果 **19 个内置插件全部没加载** —— webui（人机界面）、pluginmgr
// （插件管理）、cli、files、cmd、timer、mcp… 全丢，而**日志看起来正常**
// （只有一条"跳过 19 个非插件目录"的提示，很容易被当成噪音略过）。
//
// ## ★ 为什么必须是**行为**判据（我第一版写成源码检查 ⇒ 变异不咬）
//
// 初版检查"源码里有 `LoadSkipping(`"。但删掉**调用**后，
// 注释里仍有 `LoadSkipping` 字样 ⇒ 判据照样绿
// （**测写法不测行为** —— 本仓反复踩的同一类坑）。
//
// ⇒ 改为跑**生产同一个函数** `buildSkipSet`，断言：
//
// ① 内置插件（无 manifest）**不在** skip 里 ⇒ 会走全量加载
// ② 三形态的插件**在** skip 里（防重复加载 / 防误加载）
func TestBuiltinsAreNotSkipped(t *testing.T) {
root := t.TempDir()
makePluginDir(t, root, "ext_auto",
`{"name":"ext_auto","version":"1","entry":"plugin.bin","requires_facilities":["config"]}`)
makePluginDir(t, root, "ext_manual",
`{"name":"ext_manual","version":"1","entry":"plugin.bin","auto_start":false}`)
cat, _ := scanCatalog(root, nil)
g := classify(cat)
skip := buildSkipSet(cat, g)
// ★ 核心：内置插件（不在 catalog 里 = 没有 plugin.json）**不得**被跳过。
// 若它在 skip 里 ⇒ LoadSkipping 会跳过它 ⇒ 它永远不会被加载。
const builtinName = "builtin_only"
if skip[builtinName] {
t.Fatalf("★ 内置插件 %s 在 skip 集合里 ⇒ 不会被加载"+
"（webui/pluginmgr/cli/files/timer/mcp 全是这类，会静默消失）", builtinName)
}
if !skip["ext_auto"] {
t.Error("① 声明依赖的插件应在 skip 里（plugin-host 自己拉起，避免重复）")
}
if !skip["ext_manual"] {
t.Fatal("★ auto_start=false 的插件必须在 skip 里 —— 否则会被全量加载" +
"（与「不自动启动」完全相反）")
}
}
// ★★★ 判据：**meta 层不谎报"已接线"** + 接线本身由 e2e 守。
//
// ## ★ 这里我连续踩了三次同一个坑，值得写下来
//
// 初版判据：`strings.Contains(code, "LoadSkipping(")` ⇒ 变异不咬，
//
// 因为**注释里也有这个字样**。
//
// 二版判据：`strings.Contains(code, "LoadSkipping(dir, skip)")` ⇒
//
// 变异成 `LoadSkipping(dir, nil)` 后**仍然绿**，因为 mod.go 的
// **注释第 116 行正好写着 `` `LoadSkipping(dir, skip)` ``**。
//
// **教训（第 N+1 次）：源码字符串检查测的是"文本"，不是"行为"。**
// 只要文档/注释里出现过同一串，判据就永远绿 —— 而本仓的规范恰恰是
// "每个关键决定都要在注释里讲清楚"，所以注释里几乎必然出现这些串。
// ⇒ **源码检查只能用于"是否存在某个符号定义"，绝不能用于断言接线。**
//
// ## 那接线靠什么守？
//
// 行为层：真机 e2e 已验证（20 个插件加载、manual_probe **未**加载、
// 内置插件全部在列）。这条 e2e 是接线的真正判据。
//
// 本判据只做一件**不依赖注释**的事：确认 `buildSkipSet` 有**真实调用点**
// （AST 层面：调用表达式，不是注释里的文本）。
func TestSkipSetHasRealCallSite(t *testing.T) {
fset := token.NewFileSet()
f, err := parser.ParseFile(fset, "mod.go", nil, parser.ParseComments)
if err != nil {
t.Fatal(err)
}
calls := 0
ast.Inspect(f, func(n ast.Node) bool {
ce, ok := n.(*ast.CallExpr)
if !ok {
return true
}
if id, ok := ce.Fun.(*ast.Ident); ok && id.Name == "buildSkipSet" {
calls++
}
return true
})
if calls == 0 {
t.Fatal("★ buildSkipSet 必须被**真实调用**（AST 层面）" +
"—— 定义而不用等于没接。\n" +
" （注意：不能用字符串 Contains 判 —— 注释里会命中，实测骗过我三次）")
}
// LoadSkipping 的**调用**（AST 层面）必须存在
ls := 0
ast.Inspect(f, func(n ast.Node) bool {
ce, ok := n.(*ast.CallExpr)
if !ok {
return true
}
if sel, ok := ce.Fun.(*ast.SelectorExpr); ok && sel.Sel.Name == "LoadSkipping" {
ls++
// ★ 且第二个实参必须**不是** nil（nil = skip 失效）
if len(ce.Args) >= 2 {
if id, ok := ce.Args[1].(*ast.Ident); ok && id.Name == "nil" {
t.Error("★ LoadSkipping 的 skip 实参是 nil ⇒ " +
"三形态跳过逻辑全部失效（内置插件会被误跳过、" +
"manual 会被误加载）")
}
}
}
return true
})
if ls == 0 {
t.Fatal("★ 必须真实调用 LoadSkipping（AST 层面，非注释）")
}
}
// ★★★ 判据：**缓存并发安全**（pluginmgr 运行期读、装配期写）。
func TestCatalogConcurrentRead(t *testing.T) {
root := t.TempDir()
for i := 0; i < 20; i++ {
makePluginDir(t, root, "p"+string(rune('a'+i)),
`{"name":"x","version":"1","entry":"plugin.bin"}`)
}
cat, _ := scanCatalog(root, nil)
done := make(chan struct{})
for i := 0; i < 16; i++ {
go func() {
defer func() { done <- struct{}{} }()
for j := 0; j < 200; j++ {
_ = cat.Names()
_ = cat.All()
_ = cat.Size()
_, _ = cat.Get("pa")
}
}()
}
for i := 0; i < 16; i++ {
<-done
}
}
// ★★★ 判据：**SyncBus 为 nil 时不得 panic**（typed-nil 陷阱，实测踩到）。
//
// ## 为什么必须有这条
//
// `var nb *SyncBus; var i SyncState = nb` ⇒ **i != nil**（经典陷阱）。
// 于是 `NewScheduler(i, …)` 内部 `i.IsReady(...)` 解引用空指针 ⇒ **panic**。
//
// 实测：`ks.SyncBus == nil`（非生产装配路径 / 单测）时 plugin-host 会崩。
// 而 panic 发生在**插件拉起路径**上 ⇒ 整个内核启动失败。
//
// ⇒ 判据：把 typed-nil 传给 Scheduler 前必须已被拦截。
// 这里直接验证**拦截逻辑本身**（不依赖 produciton 装配）。
func TestNilSyncBusDoesNotPanic(t *testing.T) {
var nb *kernelboot.SyncBus // typed-nil
var iface kernelboot.SyncState = nb
if iface == nil {
t.Skip("接口就是 nil（不会有陷阱）—— 与本判据的前提不符")
}
// ★ 确认陷阱真实存在（否则这条判据是空的）
func() {
defer func() {
if r := recover(); r == nil {
t.Fatal("★ 前提不成立：typed-nil bus 竟然没 panic —— " +
"那就不需要那条 nil 拦截了，请一并删掉测试与拦截")
}
}()
_ = kernelboot.NewScheduler(iface, func(kernelboot.PluginSpec) error { return nil })
}()
// ★ 而生产代码里的拦截：mod.go 必须**显式判 nil** 后再传
src, err := os.ReadFile("mod.go")
if err != nil {
t.Fatal(err)
}
code := string(src)
if !strings.Contains(code, "ks.SyncBus != nil") {
t.Fatal("★ mod.go 必须显式判 `ks.SyncBus != nil` 再构造 Scheduler —— " +
"否则 typed-nil 会在 IsReady 处 panic（实测）")
}
if strings.Contains(code, "NewScheduler(ks.SyncBus,") {
t.Fatal("★ 不得把 ks.SyncBus **直接**传给 NewScheduler（typed-nil 陷阱）")
}
}
// ★★★★ 判据：**未声明依赖的插件必须等内核完全初始化**（§2.6.5 硬约束）。
//
// ## 这是我实际违反过、且有实测后果的约束 —— 必须写成判据
//
// 我第一版把插件按"本模块依赖是否覆盖插件声明"分成 launchNow / waitLater，
// 并在 Init 里**直接**加载 launchNow。而未声明依赖的插件 `RequiresFacilities`
// 是**空** ⇒ "覆盖空集"恒真 ⇒ 它们被归入 launchNow ⇒ **第 4 层就被加载**。
//
// 而 §2.6.5 的硬约束是「未声明 ⇒ 启动时机**逐字不变**（内核**完全**初始化后）」。
// 原文警告："静默改变启动时机 = 静默引入竞态"。
//
// ## ★ 后果不是理论上的 —— 实测丢了一个工具
//
// 内置插件 `healthcheck` 在 `Start` 里做：
//
// if s.Status() != nil { s.RegisterTool("healthcheck_kernel", …) }
//
// 第 4 层时 agent 还没建好（它与 plugin-host **并行**）⇒ `Status()` 为 nil
// ⇒ **静默少注册一个工具**。实测：86 个工具（应为 87），**无任何报错**。
// （nginx 式的 nil 保护把"时序错了"降级成了"少个功能"，最难发现。）
//
// ⇒ 判据：未声明的插件**不得**在 `KernelComplete()` 之前被拉起。
// 用**真的 Scheduler + 真的 SyncBus** 验证（跑生产同一路径）。
func TestUndeclaredPluginsWaitForKernelComplete(t *testing.T) {
root := t.TempDir()
makePluginDir(t, root, "undeclared",
`{"name":"undeclared","version":"1","entry":"plugin.bin"}`)
makePluginDir(t, root, "declared",
`{"name":"declared","version":"1","entry":"plugin.bin","requires_facilities":["config"]}`)
cat, _ := scanCatalog(root, nil)
g := classify(cat)
specs := buildSpecs(cat, g)
if len(specs) != 2 {
t.Fatalf("两个自动启动插件都应进调度器（含**未声明**的），实际 %d 个", len(specs))
}
bus := kernelboot.NewSyncBus()
bus.MarkDeclared([]string{"config", "agent"})
bus.MarkReady("config")
launched := map[string]bool{}
sched := kernelboot.NewScheduler(bus, func(s kernelboot.PluginSpec) error {
launched[s.Name] = true
return nil
})
got := sched.Submit(specs)
for _, n := range got {
launched[n] = true
}
// ① 声明的：依赖（config）已就绪 ⇒ **应当**立即拉起
if !launched["declared"] {
t.Error("声明了 config 且 config 已就绪的插件应当被拉起（这是本步的核心收益）")
}
// ② ★ 未声明的：内核**未**完成 ⇒ **不得**拉起
if launched["undeclared"] {
t.Fatal("★ 未声明依赖的插件在内核完全初始化**之前**被拉起了 ⇒ 违反 §2.6.5。\n" +
" 实测后果：healthcheck 的 s.Status() 为 nil ⇒ 静默少注册一个工具" +
"（86 vs 87，无任何报错）。")
}
// ③ 内核完成后 ⇒ 未声明的才应拉起
bus.MarkKernelComplete()
if !launched["undeclared"] {
t.Fatal("★ 内核完成后未声明的插件仍未被拉起 ⇒ 它永远起不来")
}
}
// ★★★ 判据：**未声明的插件必须在 skip 集合【外面】**（否则会被重复加载）。
//
// 调度器会拉起它，LoadSkipping 也会碰到它 ⇒ 两条路都加载 = 重复。
// （实测未复现重复，是因为时序上 LoadSkipping 晚于调度器且 registry 有门，
//
// 但**不应依赖巧合** —— 判据把语义钉住。）
func TestUndeclaredNotDoubleLoaded(t *testing.T) {
root := t.TempDir()
makePluginDir(t, root, "undeclared",
`{"name":"undeclared","version":"1","entry":"plugin.bin"}`)
cat, _ := scanCatalog(root, nil)
g := classify(cat)
skip := buildSkipSet(cat, g)
// 未声明的插件在 autoStart 里（调度器会管）
if len(g.autoStart) != 1 || g.autoStart[0] != "undeclared" {
t.Fatalf("前提不成立: %v", g.autoStart)
}
// ★ 修法后：catalog 里登记的（含未声明的）**一律**不在 LoadSkipping 的
// 管辖范围 ⇒ 必须在 skip 里。这样"调度器"与"LoadSkipping"两条路
// **按构造不相交**，不可能双加载。
//
// （我第一版只 skip declared/manual/disabled ⇒ 未声明的外部插件会被
// 两条路各加载一次。实测变异：healthcheck loaded 2 次、工具 87→161。）
if !skip["undeclared"] {
t.Fatal("★ catalog 里登记的插件都必须在 skip 里 —— " +
"否则未声明的外部插件会被调度器与 LoadSkipping **各加载一次**" +
"（实测：工具数翻倍）")
}
// ★ 反向钉住：LoadSkipping 仍必须能加载**内置插件**（不在 catalog 里）
if skip["some_builtin_without_manifest"] {
t.Fatal("★ 内置插件（无 plugin.json，不在 catalog）不得被 skip —— " +
"它是 LoadSkipping 唯一能加载的对象")
}
}

60
internal/kernelmod/pluginhost/migrate_adapter.go Normal file
View File

@ -0,0 +1,60 @@
package pluginhost
// 把**真实的** plugin.Registry 接到 kernelboot.PluginQuiescer（伪关机用）。
//
// ## 为什么需要适配器而不是让 kernelboot 直接依赖 plugin
//
// kernelboot 是装配内核，plugin 是插件系统 —— 后者依赖前者（模块声明依赖），
// 反向 import 就成环。⇒ 用一个小接口 + 适配器隔开。
//
// ## ★ 为什么是 StopPlugin/StartPlugin，不是 StopAll
//
// 三态生命周期早已存在（自动启动 / 启用但不自动启动 / 禁用），而
// `StopPlugin`/`StartPlugin` 是**运行态**操作：
//
// · 不写 disabled_plugins ⇒ 不改用户决定
// · 不置 shuttingDown ⇒ 之后还能重新加载（**可逆**）
// · 会摘掉注册面 ⇒ 停完模型看不到也调不到（彻底）
//
// `StopAll` 完全相反：置 shuttingDown 后插件**永久无法再加载**，
// 那是进程退出用的。用它做伪关机 = 关了就起不来。
//
// ## 为什么跳过自身与 UI
//
// `refuseSelfLock` 已经拒绝了 pluginmgr（自锁，停了就没法再启）与 webui
// （停了 UI 就失联，迁移进度看不见）。这里**主动跳过**而不是去撞错误：
// 迁移期间我们需要 UI 报告进度，撞错只会让日志充满噪声。
import "github.com/JianFeeeee/HomeAgent/internal/plugin"
// RegistryQuiescer 适配 *plugin.Registry → kernelboot.PluginQuiescer。
type RegistryQuiescer struct{ Reg *plugin.Registry }
// StopPluginRuntime 运行态停掉一个插件（不改持久状态）。
func (r RegistryQuiescer) StopPluginRuntime(name string) error {
return r.Reg.StopPlugin(name)
}
// StartPluginRuntime 运行态拉起一个插件。
func (r RegistryQuiescer) StartPluginRuntime(name string) error {
return r.Reg.StartPlugin(name)
}
// RunningPlugins 返回当前在运行的插件名。
//
// ★ 排除 pluginmgr 与 webui：前者停了无法再启（自锁），后者是迁移进度的
// 唯一可视通道。这与 refuseSelfLock 的口径一致，但在这里**提前排除**
// 而不是靠报错兜底（报错会进入 BeginMigration 的回滚路径，把正常迁移搞挂）。
func (r RegistryQuiescer) RunningPlugins() []string {
// Registry.List() 返回 r.plugins 的键集 = **当前已加载并运行**的插件
// （StopPlugin 会从该 map 删除 ⇒ 停掉的自然不在其中）。
all := r.Reg.List()
out := make([]string, 0, len(all))
for _, n := range all {
if n == "pluginmgr" || n == "webui" {
continue
}
out = append(out, n)
}
return out
}

352
internal/kernelmod/pluginhost/mod.go Normal file
View File

@ -0,0 +1,352 @@
package pluginhost
import (
"fmt"
"log"
"os"
"path/filepath"
"sync"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/supervisor"
)
// FacPlugins 是本模块提供的设施名。
//
// 意义：**"谁是最后一批被拉起的插件"** —— 声明 `plugins` 的插件要等所有
// 自动启动的插件都起完才起（如"插件总览"类插件）。
const FacPlugins = "plugins"
// Module 是插件宿主：扫元数据、按形态分流、按依赖时机拉起。
type Module struct{}
func (Module) Name() string { return "plugin-host" }
// Requires：插件**加载**所需的全部前置 —— **刻意不含 agent**。
//
// ★ 这是本模块存在的关键价值（用户方案 A 的核心收益）：
// 原先 wirePluginSDK 在 agent 模块里 ⇒ 插件加载被排在 agent 之后，
// 而 agent 层实测 **35 秒**（context dense backfill 750 events + 重建索引）。
//
// 而插件真正需要的只是 stage-host（Registry + StageHost）与几个底层设施。
// agent 相关的两项（StatusProvider / TerminalAPI）改为**后补注入**（见
// agent 模块），插件在 Start 阶段不用它们（唯一的 healthcheck 是 nil-guarded）。
func (Module) Requires() []string {
return []string{
kernelmod.FacConfig, kernelmod.FacKernelIO, kernelmod.FacMemory,
kernelmod.FacLua, kernelmod.FacSupervisor, kernelmod.FacTracker,
kernelmod.FacTextMem, kernelmod.FacDocStore, kernelmod.FacKnowledge,
kernelmod.FacStageHost,
}
}
func (Module) Provides() []string { return []string{FacPlugins} }
func (Module) Init(ks *kernelboot.KernelState) error {
// ── 前置检查（用户要求："nil 加读取前检查"）──
if ks.PluginRegistry == nil || ks.StageHost == nil {
return fmt.Errorf("plugin-host：ks.PluginRegistry/StageHost 为 nil —— " +
"stage-host 模块必须先完成（插件加载的硬前置）")
}
if ks.Cfg == nil {
return fmt.Errorf("plugin-host：ks.Cfg 为 nil —— config 模块必须先完成")
}
if ks.CfgReg == nil || ks.DataDir == "" {
return fmt.Errorf("plugin-host：CfgReg/DataDir 为 nil/空 —— Group 0 必须先完成")
}
// ── ① 注入插件 SDK 的**底层依赖**（不含 agent 相关的两项）──
injectBaseDeps(ks)
// ── ② 扫一次目录 → 元数据缓存 ──
dir := ks.Cfg.Plugin.Dir
os.MkdirAll(dir, 0o755)
catalog, noManifest := scanCatalog(dir, ks.CfgReg.IsPluginDisabled)
ks.PluginCatalog = catalog
// ★ 措辞必须准确（我第一版写成"跳过 N 个非插件目录" ⇒ **误导**）：
// 那些目录大多是**内置插件**（编译期工厂，本就没有 plugin.json，
// 由下面的 LoadSkipping 从工厂表加载）。只有既无 manifest
// 又无工厂的才是真的非插件目录。
//
// 这条日志的价值在于：新增外部插件若忘写 plugin.json，会出现在这里
// （那时"无 manifest ⇒ 只能走工厂 ⇒ 找不到 ⇒ 不加载"，可据此发现）。
if len(noManifest) > 0 {
log.Printf("[pluginhost] %d 个目录无 plugin.json（内置插件属正常：它们由编译期工厂加载）: %v",
len(noManifest), noManifest)
}
log.Printf("[pluginhost] 外部插件元数据缓存就绪：%d 个（目录 %s）",
catalog.Size(), dir)
// ── ③ 按**三形态**分流（用户设计要求）──
groups := classify(catalog)
log.Printf("[pluginhost] 形态分流：自动启动 %d / 声明了依赖 %d / "+
"启用但不自动启动 %d / 持久禁用 %d",
len(groups.autoStart), len(groups.declared),
len(groups.manual), len(groups.disabled))
// ── ④ 拉起：**全部自动启动的插件都交给 Scheduler** ──
//
// ★★ 我第一版在这里犯了一个**违反硬约束**的错，值得完整记录：
//
// 第一版按"本模块依赖是否覆盖插件声明"把插件分成 launchNow / waitLater，
// 并在 Init 里**直接**把 launchNow 全加载了。
// 但**未声明依赖**的插件，`RequiresFacilities` 是空 ⇒ "本模块依赖覆盖空集"
// 恒真 ⇒ 它们被归入 launchNow ⇒ **在第 4 层就被加载**。
//
// 而 §2.6.5 的硬约束是：
//
// 未声明 ⇒ 启动时机**逐字不变**（内核**完全**初始化完成后）
//
// 实测证据（planA4.log）：内置插件在 `21:54:37`（第 4 层）被加载，
// 而内核装配完成是 `21:55:12` —— **早了 35 秒**。
// 约束原文写着"静默改变启动时机 = 静默引入竞态"，
// 42 个存量插件里任何一个若假设"Start 时 llm 一定已就绪"就会中招。
//
// ⇒ 修法：**不再自己判时机**，全部交给 `kernelboot.Scheduler`
// ——它已正确实现 §2.6.5（空声明 ⇒ 等 `KernelComplete()`）与
// §2.6.6（`!AutoStart` ⇒ 不自动拉起），且有完整判据。
// 我只需要提供"拉起一个插件"的动作。
//
// 这样声明的插件仍在依赖就绪时尽早启动（本步的核心收益不变），
// 而未声明的**恢复原行为**（等内核完全初始化）。
var bus kernelboot.SyncState
var busConcrete *kernelboot.SyncBus // 保留具体类型以便订阅 OnUpdate
if ks.SyncBus != nil {
bus = ks.SyncBus
busConcrete = ks.SyncBus
} else {
// ★★ typed-nil 陷阱：`var nb *SyncBus; var i SyncState = nb`
// ⇒ i **非 nil** ⇒ 方法里解引用空指针 panic（实测复现）。
// 所以这里必须显式判 `!= nil` 再赋给接口变量。
log.Printf("[pluginhost] warning: SyncBus 为空 —— 非生产装配路径，" +
"退化为立即加载（依赖未就绪的插件在 Start 时自行处理）")
fallback := kernelboot.NewSyncBus()
fallback.MarkKernelComplete()
bus = fallback
busConcrete = fallback
}
sched := kernelboot.NewScheduler(bus, func(spec kernelboot.PluginSpec) error {
return ks.PluginRegistry.LoadOneDir(filepath.Join(dir, spec.Name), spec.Name)
})
sched.SetLaunchErrorHandler(func(spec kernelboot.PluginSpec, err error) {
log.Printf("[pluginhost] warning: 拉起 %s 失败: %v", spec.Name, err)
})
ks.PluginScheduler = sched
specs := buildSpecs(catalog, groups)
// Submit 返回"此刻就能拉起"的：
// · 声明了依赖且已全就绪 ⇒ 立即拉起（**本步的核心收益**）
// · 未声明的 ⇒ 不进返回列表（等 KernelComplete，§2.6.5）
// · !AutoStart ⇒ 不进（§2.6.6）
// 同时 Submit 会做拼错校验（声明的设施名内核从未注册 ⇒ 立即报错）。
for _, n := range sched.Submit(specs) {
log.Printf("[pluginhost] 插件已拉起（依赖已就绪，早于装配完成）: %s", n)
}
// ── ⑤ 加载**内置插件**（编译期工厂，**没有 plugin.json**）──
//
// ★★ 这一步是我第一版漏掉的（实测：19 个内置插件全部没加载 ——
// webui / pluginmgr / cli / files / timer / mcp …，只剩 2 个外部插件起）。
//
// 原因：上面的 catalog 是**扫目录读 plugin.json** 得来的，
// 而内置插件是**编译期注册的工厂**（`plugin.RegisterFactory` 在 init() 里），
// 目录里可能连 plugin.json 都没有 ⇒ 表里根本没有它们。
//
// 走 `LoadSkipping(dir, skip)`：它内部既扫目录（外部插件）
// 也遍历工厂（内置插件），是**唯一完整**的加载入口。
// skip 集合 = 已由本模块调度处理的那些（按三形态分流的），
// 避免重复加载。
// ── ⑤ 其余插件（未声明的 + 内置）→ **等内核完全初始化**后加载 ──
//
// ★ 为什么不能在这里直接 LoadSkipping（我第一版的第二个错）：
// plugin-host 在第 4 层，而 agent 与它**并行** ⇒ 此刻内核**尚未**
// 完全初始化。直接加载同样违反 §2.6.5 的"未声明 ⇒ 逐字不变"。
//
// ⇒ 挂到 syncbus 的 `KernelComplete` 上（内核**推**状态，不轮询）。
//
// skip = 已由 Scheduler 接管的（declared ∪ manual ∪ disabled）。
// 不在 skip 里的：未声明的外部插件 + **内置插件**（编译期工厂，
// 不在 catalog 里，只有 LoadSkipping 的工厂分支能加载它们）。
skip := buildSkipSet(catalog, groups)
var loadOnce sync.Once
loadRest := func(st kernelboot.SyncState) {
if !st.KernelComplete() {
return
}
loadOnce.Do(func() {
if err := ks.PluginRegistry.LoadSkipping(dir, skip); err != nil {
log.Printf("[pluginhost] warning: 加载内置/未声明插件: %v", err)
}
ks.PluginsReady = true
log.Printf("[pluginhost] 内核完全初始化 → 已加载其余插件（含 %d 个内置）",
len(noManifest))
})
}
// 订阅 + 立即评估一次（若 bus 已 complete，比如非生产路径的退化 bus）
// ★ 订阅用**具体类型**的 SyncBus（SyncState 是**只读接口**，
// 故意没有 OnUpdate —— 设计 §2.6.3 "插件管理器对 syncbus 只读"）。
// 本模块是内核模块，本就持有具体类型，无需放宽接口。
if busConcrete != nil {
busConcrete.OnUpdate(loadRest)
}
loadRest(bus)
log.Printf("[pluginhost] 本阶段：声明了依赖的 %d 个由调度器处理"+
"（已就绪的已拉起），未声明的 %d 个 + 内置 %d 个等内核完全初始化",
len(groups.declared), len(groups.autoStart)-len(groups.declared), len(noManifest))
return nil
}
func init() { kernelmod.Register(Module{}) }
// buildSpecs 把"自动启动"的插件元数据转成调度器声明。
//
// ## ★ 为什么**未声明**的插件也要进来（我第一版漏了这个语义）
//
// 第一版把"未声明依赖"的插件排除在调度器之外、在 Init 里直接加载
// ⇒ 它们在第 4 层（agent 并行期间）就起了，而 §2.6.5 要求"等内核
// **完全**初始化"。实测后果：`healthcheck` 的 `s.Status()` 为 nil
// ⇒ **静默少注册一个工具** `healthcheck_kernel`（86 vs 87，无任何报错）。
//
// ⇒ 全部自动启动的插件都交给调度器；调度器对空声明返回
// `KernelComplete()`（§2.6.5），正是原行为。
func buildSpecs(c *PluginCatalog, g formGroups) []kernelboot.PluginSpec {
var out []kernelboot.PluginSpec
for _, n := range g.autoStart {
m, ok := c.Get(n)
if !ok {
continue
}
out = append(out, kernelboot.PluginSpec{
Name: m.Name,
RequiresFacilities: m.RequiresFacilities,
AutoStart: m.AutoStart,
})
}
return out
}
// buildSkipSet 计算"不能让全量 LoadSkipping 碰"的插件名集合。
//
// ## ★ 为什么抽成独立函数（判据要求）
//
// 初版把这段逻辑内联在 Init 里 ⇒ 判据只能查源码字符串 ⇒
// 删掉代码但注释仍在时**判据不咬**（实测）。
// 抽出来后可**真的调用它**做行为断言（TestBuiltinsAreNotSkipped）。
//
// ## 集合语义（三形态 + 内置插件的边界）
//
// ② auto_start=false ⇒ 必须在集合里（否则会被全量加载 = 违背语义）
// ③ disabled ⇒ 在集合里（显式跳过；registry 还有禁用门兜底）
// ① 声明的 ⇒ 由本模块按依赖时机拉起 ⇒ 必须在集合里（防重复）
// **内置插件** ⇒ **不在**集合里 ⇒ 走 LoadSkipping 的工厂分支被加载
// ★ 这正是我第一版漏掉的关键：内置插件没有 plugin.json，
// 不在 catalog 里，只有 LoadSkipping 的工厂分支能加载它们。
func buildSkipSet(c *PluginCatalog, g formGroups) map[string]bool {
skip := map[string]bool{}
// ★★ 原则：**catalog 里登记过的插件，一律不交给 LoadSkipping**。
//
// ## 为什么不是"只跳过 declared/manual/disabled"（我第一版就是这么写的）
//
// 那会让**未声明的外部插件**同时被两条路加载：
// · 调度器（它管未声明的，等 KernelComplete 后拉起）
// · LoadSkipping（未声明的**不在** skip 里 ⇒ 也加载）
//
// 实测（变异 F，把 LoadSkipping 挪回 Init）：`healthcheck` 被 loaded **两次**，
// 工具数 87 → **161**（重复注册）。planA5 侥幸未触发，只因测试目录里
// 那 3 个外部插件恰好都声明了依赖或不自启 —— **不能依赖这种巧合**。
//
// ⇒ 改成**按构造**消除：catalog 里的全部（三形态之一）都由本模块/调度器
// 负责；LoadSkipping 只处理 catalog **之外**的，也就是那些
// **没有 plugin.json 的内置插件**（编译期工厂，只有它能加载）。
//
// 这样两条路**按定义**不相交。
for _, n := range c.Names() {
skip[n] = true
}
// 保底：三形态里若有 catalog 未收录的（理论上不会），也别漏
for _, n := range g.autoStart {
skip[n] = true
}
for _, n := range g.manual {
skip[n] = true
}
for _, n := range g.disabled {
skip[n] = true
}
return skip
}
// injectBaseDeps 注入插件 SDK 的底层依赖（原 wirePluginSDK 的 7 项）。
//
// ★ 这里**刻意不做** SetStatusProvider / SetTerminalAPI —— 它们依赖 agent，
// 由 agent 模块**后补注入**（见其注释）。这不是遗漏，是有意的分层：
// 让插件加载不必等 agent 那 35 秒。
func injectBaseDeps(ks *kernelboot.KernelState) {
reg := ks.PluginRegistry
reg.SetLuaVM(ks.LuaVM)
reg.SetBaseAPIKey(ks.BaseAPIKey)
if ks.Supervisor != nil {
reg.SetSupervisor(supervisor.NewSDKAdapter(ks.Supervisor))
}
reg.SetTracker(ks.Tracker)
reg.SetConfig(ks.Cfg)
reg.SetStageHost(ks.StageHost)
if ks.Memory != nil {
reg.SetIndexer(ks.Memory.Indexer)
}
}
// formGroups 是三形态分流结果。
//
// ★ 用户明确要求的三种形态（§2.6.6）：
//
// ① autoStart ：自动启动（缺省/true）
// ② manual ：**启用但不自动启动**（auto_start=false）⇒ 等显式启用
// ③ disabled ：禁用（disabled_plugins 配置）⇒ 不加载
//
// 外加 `declared`：自动启动**且声明了依赖**的子集（决定"何时"拉）。
type formGroups struct {
autoStart []string // ① 自动启动的全部（含 declared）
declared []string // ① 中声明了 requires_facilities 的
manual []string // ② 不自动启动
disabled []string // ③ 持久禁用
}
func classify(c *PluginCatalog) formGroups {
var g formGroups
for _, m := range c.All() {
switch {
case m.Disabled:
// ③ 禁用：最高优先级（不加载）
g.disabled = append(g.disabled, m.Name)
case !m.AutoStart:
// ② 启用但不自动启动：**不自动加载**，等 agent 显式启用
g.manual = append(g.manual, m.Name)
default:
// ① 自动启动
g.autoStart = append(g.autoStart, m.Name)
if len(m.RequiresFacilities) > 0 {
g.declared = append(g.declared, m.Name)
}
}
}
return g
}
// loadOne 加载单个插件（走既有 LoadOneDir 路径，不绕过任何机制）。
func loadOne(ks *kernelboot.KernelState, dir, name string) (bool, error) {
if err := ks.PluginRegistry.LoadOneDir(filepath.Join(dir, name), name); err != nil {
return false, err
}
return true, nil
}
// planCatalog 取元数据缓存（类型断言集中一处，便于排查"缓存没建起来"）。
func planCatalog(ks *kernelboot.KernelState) *PluginCatalog {
c, _ := ks.PluginCatalog.(*PluginCatalog)
return c
}

17
internal/kernelmod/pluginhost/rwmutex.go Normal file
View File

@ -0,0 +1,17 @@
package pluginhost
import "sync"
// rwMutex 是 sync.RWMutex 的薄包装。
//
// 为什么不直接用 sync.RWMutex：PluginCatalog 要能被**复制/传递**时
// 保持清晰的所有权语义（指针字段而非嵌入值），避免"复制了含锁的结构体"
// 这个经典的 vet 警告（copylocks）。
type rwMutex struct{ mu sync.RWMutex }
func newRWMutex() *rwMutex { return &rwMutex{} }
func (m *rwMutex) RLock() { m.mu.RLock() }
func (m *rwMutex) RUnlock() { m.mu.RUnlock() }
func (m *rwMutex) Lock() { m.mu.Lock() }
func (m *rwMutex) Unlock() { m.mu.Unlock() }