jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-05 16:57:32 +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

316
internal/kernelmod/agent/mod.go Normal file
View File

@ -0,0 +1,316 @@
// Package agent 是 agent 模块：主 Agent（需在插件加载前创建，
// 因为插件 Configure 需要 StatusProvider）。
//
// ## 依赖
//
// buildAgent 收 provider/providerMgr/iom/mem.db/mem.indexer/trk/docStore/
// knowledge/mem.social/textMem/personality/pluginReg/embedder/
// multimodalSpace/stageHost/evBus ⇒ 依赖除 supervisor 外的几乎全部下层模块。
//
// 人格设定（loadPersonality）在本模块内完成 —— 它只读配置文件，
// 没有独立产物的价值，不必单列模块。
package agent
import (
"fmt"
"log"
"path/filepath"
"strings"
"time"
agentCore "github.com/JianFeeeee/HomeAgent/internal/agent/core"
"github.com/JianFeeeee/HomeAgent/internal/config"
"github.com/JianFeeeee/HomeAgent/internal/events"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/memory"
"github.com/JianFeeeee/HomeAgent/internal/supervisor"
"github.com/JianFeeeee/HomeAgent/pkg/types"
agentPkg "github.com/JianFeeeee/HomeAgent/internal/agent"
)
// Module 提供主 Agent。
type Module struct{}
func (Module) Name() string { return "agent" }
func (Module) Requires() []string {
return []string{kernelmod.FacLLM, kernelmod.FacMemory, kernelmod.FacTracker,
kernelmod.FacDocStore, kernelmod.FacKnowledge, kernelmod.FacTextMem,
kernelmod.FacStageHost}
}
func (Module) Provides() []string { return []string{kernelmod.FacAgent} }
func (Module) Init(k *kernelboot.KernelState) error {
if k.Memory == nil {
return errMissing("agent", kernelmod.FacMemory)
}
if k.LLMManager == nil {
return errMissing("agent", kernelmod.FacLLM)
}
if k.PluginRegistry == nil {
return errMissing("agent", kernelmod.FacStageHost)
}
k.Agent = buildAgent(k)
// 插件 SDK 接线（必须在 loadPlugins 之前）。
wirePluginSDK(k)
return nil
}
func init() { kernelmod.Register(Module{}) }
const defaultSystemPrompt = `你是 HomeAgent，一个持续运行的个人管家。
你的每次回复会自动发送到当前输出通道（默认=输入源），无需额外工具。
如需切换回复通道，使用 output_set_channel。
如需异步发送消息或通知，使用 output_send 指定通道和内容。
使用 output_list_channels 查看可用通道及其能力。
可用工具列表会由系统自动传入，按需使用即可。以下是你尤其需要关注的几类工具：
- memory_* — 图记忆（长期记忆，记录和查询个人信息/事实）
- knowledge_* — 知识库（查阅预设知识文档）
- doc_* — 文档记忆（近期对话的存档，查询后自动清除）
- person_* — 人物特质与社交关系网
- llm_* — LLM 源管理（列出/切换模型提供商）
- output_* — 输出通道管理（切换/发送消息）
- timer_set — 设置定时提醒
- plgreload — 热重载插件
- spawn_child — 生成子 Agent 异步执行独立任务（可传 max_turns 控制工具轮数，默认 5）
并行策略：遇到多个互不依赖的子任务时，优先并行 spawn 多个子 Agent 而非自己串行逐个执行；
长耗时任务（批量处理、多轮搜索汇总）也应交给子 Agent，避免阻塞当前对话。
- describe_image — 描述用户上传的图片
- transcribe_audio — 转写用户上传的音频
- ocr_image — 识别图片中的文字
命令与文件操作策略：
- cmd_run 经完整 shell（bash）执行，支持管道、分号、&&、命令替换、heredoc、重定向。
- 多步交互式程序（vim/top/ssh 会话、需要持续输入的进程）用 terminal_create 创建终端，
terminal_write 发送输入、terminal_read 读输出——不要用 cmd_run 硬等交互程序退出。
- 写文件优先 files_write（原子+留档），生成多行内容时可用 heredoc 或 files_write，
不要用 echo 拼接长文本。
- 读用户发来的文件用 files_read；向 webui 回传图片/文件用 output_send__webui(type=image/file)。
当用户上传图片或音频时，系统会自动附着媒体内容。如果模型不支持直接处理多媒体，请使用上述工具。
回复你的真实想法，用自然语言与用户交流。不要在回复中使用 emoji 表情。`
func buildAgent(k *kernelboot.KernelState) *agentCore.Agent {
cfg := k.Cfg
cfgReg := k.CfgReg
provider := k.LLMProvider
providerMgr := k.LLMManager
iom := k.IO
memDB := k.Memory.DB
memIdx := k.Memory.Indexer
trk := k.Tracker
docStore := k.DocStore
ks := k.Knowledge
socialStore := k.Memory.Social
textMem := k.TextMemory
pluginReg := k.PluginRegistry
embedder := k.Embedder
multimodalSpace := k.MultimodalSpace
mmProviderName := k.MultimodalProviderName
mmErr := k.MultimodalErr
stageHost := k.StageHost
evBus := k.EventBus
personality := loadPersonality(cfg, cfgReg)
sysPrompt := cfgReg.GetString("core.agent.system_prompt", defaultSystemPrompt)
if sysPrompt == "" {
sysPrompt = defaultSystemPrompt
}
// D4：把"设备是否已授权"的判据注入插件侧（toolImpl.CanUse 用）。
// ⚠️ 必须放在 agent 构造**之后**——判据要用 agent 的 allowedOutputs，
// 而 registry 早于 agent 构造（故这里传的是晚绑定闭包）。
// 未注入时 ToolAPI 路径对设备放行：那是"授权可被绕过"的既成缺口。
// 注入后，cli 的 /terminal、seq 序列等一切走 ToolAPI 的调用都受同一道闸。
agent := agentCore.New(agentCore.AgentConfig{
ID: "main",
SystemPrompt: sysPrompt,
Provider: provider,
ProviderManager: providerMgr,
IO: iom,
Memory: memDB,
Indexer: memIdx,
Tracker: trk,
DocStore: docStore,
Knowledge: ks,
SocialStore: socialStore,
TextMemory: textMem,
// MediaStore 已随 CAS 淘汰：块自带负载（见 plan.md）。
Personality: personality,
// 人格落库面：首启门禁（任何通道都问一次）与 persona_set 工具用。
// 与 WebUI 向导共用 internal/config 的同一份落库逻辑。
PersonaStore: config.RegistryPersonaStore{Reg: cfgReg},
PluginReg: pluginReg,
PluginDir: cfg.Plugin.Dir,
// DataDir：驻留子的 temp 图库锚点（<data>/residents/<id>/graph.db）。
// 漏接时的现象是"工具存在、可调用、但创建必失败"——只有真实二进制才看得出来。
DataDir: cfg.Daemon.DataDir,
DistillInterval: cfgReg.GetDuration("core.agent.distill_interval", 30*time.Minute),
ArchiveInterval: cfgReg.GetDuration("core.agent.archive_interval", 60*time.Minute),
ReviewInterval: cfgReg.GetDuration("core.agent.review_interval", 120*time.Minute),
MergeInterval: cfgReg.GetDuration("core.agent.merge_interval", 120*time.Minute),
MaxToolTurns: cfgReg.GetInt("core.agent.max_tool_turns", 10),
// 上下文管理的可调阈值。此前这些值全部硬编码在 ComputeTokenBudget 里，
// 界面改不了、不同窗口的实例也没法各自调优。
CtxTuning: agentCore.ContextTuning{
UtilizationPercent: cfgReg.GetInt("core.agent.context.utilization_percent", 80),
MaxTargetTokens: cfgReg.GetInt("core.agent.context.max_target_tokens", 600000),
MemoryRatioPercent: cfgReg.GetInt("core.agent.context.memory_ratio_percent", 0),
ProtectedCount: cfgReg.GetInt("core.agent.context.protected_count", 10),
},
// ⚠️ 这条键此前被注册进配置面板、也有默认值，但**从未被读取** ——
// 界面上改它没有任何效果，且不报任何错。同一类「死配置」正是
// 本次把阈值接入配置系统时要一并修掉的。
MaxContextSize: cfgReg.GetInt("core.agent.max_context_size", 30),
Offload: agentCore.OffloadOptions{
Enabled: cfgReg.GetBool("core.agent.offload_enabled", false),
BusyAfter: cfgReg.GetDuration("core.agent.offload_busy_after", 5*time.Minute),
MinPending: cfgReg.GetInt("core.agent.offload_min_pending", 3),
MaxResidents: cfgReg.GetInt("core.agent.offload_max_residents", 2),
},
ContextSavePath: filepath.Join(cfg.Daemon.DataDir, "memory", "context.json"),
EmbeddingModelPath: cfgReg.GetString("core.agent.embedding_model_path", ""),
Embedder: embedder,
MultimodalSpace: multimodalSpace,
EmbeddingProvider: mmProviderName,
EmbeddingError: mmErr,
StageHost: stageHost,
EventBus: evBus,
ThinkingEnabled: cfg.LLM.ThinkingEnabled,
InputProcessing: cfg.InputProcessing,
})
// 图记忆读写钩子 → 事件总线。
//
// ★ 为什么在这里接（而不是让各调用方自己发事件）：
// 图读写散在 26 个方法与 180+ 个 db 调用点上，各调用方自报必漏发；
// 而**图库自己就知道它碰了哪些块 ID**。星图此前只能靠工具名猜
// 节点（把 "memory_recall" 拆词去匹配中文实体名，实测命中 0），
// 于是每次都点亮同一批无关节点——这正是「星图没有读写反馈」的真身。
//
// ★ 只在 evBus 非 nil 时接：它把「内核进程」与「独立 CLI 工具」区分开
// （homed-graph-migrate / memgc 等也用 NewGraphDB，但没有事件总线，
// 也不该为一次批量迁移向不存在的订阅者发几万条事件）。
//
// ★ 钩子**必须非阻塞**：它在记忆读写的同步路径上，发布到总线
// 是内存操作（各订阅者回调也都很短），实测开销可忽略。
if memDB != nil && evBus != nil {
memDB.SetAccessHook(func(ev memory.AccessEvent) {
payload := map[string]interface{}{
"op": ev.Op,
}
// 只在非空时带上字段：空数组会让前端白白重算一次。
if len(ev.Blocks) > 0 {
payload["blocks"] = ev.Blocks
}
if len(ev.Created) > 0 {
payload["created"] = ev.Created
}
if len(ev.Removed) > 0 {
payload["removed"] = ev.Removed
}
if len(ev.Merged) > 0 {
merged := make([]map[string]string, 0, len(ev.Merged))
for _, m := range ev.Merged {
merged = append(merged, map[string]string{"from": m.From, "to": m.To})
}
payload["merged"] = merged
}
if ev.Tool != "" {
payload["tool"] = ev.Tool
}
evBus.Publish(&events.Event{
Type: events.EventMemoryAccess,
Source: "main",
Payload: payload,
Timestamp: time.Now().Unix(),
})
})
}
// D4：把「设备是否已授权」的判据注入插件侧（toolImpl.CanUse 消费它）。
//
// 为什么必须在这里：判据要用 agent 自己的 allowedOutputs，而
// pluginReg 早于 agent 构造（newStageAndRegistry 在 main() 里先跑），
// 所以 registry 存的是**晚绑定**闭包，注入点必须在 agent 建好之后。
//
// 不注入的后果（已实测的真实缺口）：设备授权闸只存在于
// core.executeToolCallInner，即「agent 收到模型 tool_call」那条路径；
// 而 ToolAPI.ExecuteTool 是**另一条**独立入口，不经那道闸 ⇒
// 凡是走 ToolAPI 的调用都能绕过 AllowedOutputs。实测范围不止序列：
// cli 的 /terminal 就直接经 ToolAPI 调 agentcli 的终端工具。
pluginReg.SetDeviceAuthQuery(func(deviceID string) bool {
return agent.IsOutputAllowed("device/" + deviceID)
})
// 方案 B：把 agent 的**内置工具面**注入 ToolAPI。
//
// 缺口背景：`memory_*` / `knowledge_*` / `doc_*` / `person_*` 这 20+ 个
// 在 executeToolCallInner 里按前缀分派，从不进 ToolAPI ⇒ 插件经 ToolAPI
// 既查不到也调不了。真机实跑实证：seq_run 报「工具 knowledge_list
// 不存在或未注册」，而同一轮模型直接调它是成功的。
//
// 注入必须在此处（agent 构造之后）：内置工具的可见性由运行期状态门控
// （memory/knowledge 是否就绪），而 provider 持有的是 agent。
agent.InstallBuiltinToolProvider()
return agent
}
// wirePluginSDK 把内核依赖注入插件注册表（原 cmd/homed 的整块平移）。
func wirePluginSDK(k *kernelboot.KernelState) {
k.PluginRegistry.SetLuaVM(k.LuaVM)
k.PluginRegistry.SetBaseAPIKey(k.BaseAPIKey)
k.PluginRegistry.SetSupervisor(supervisor.NewSDKAdapter(k.Supervisor))
k.PluginRegistry.SetTracker(k.Tracker)
k.PluginRegistry.SetConfig(k.Cfg)
k.PluginRegistry.SetStageHost(k.StageHost)
k.PluginRegistry.SetIndexer(k.Memory.Indexer)
k.PluginRegistry.SetStatusProvider(k.Agent)
k.PluginRegistry.SetTerminalAPI(k.Agent)
}
// loadPersonality 载入人格（原 cmd/homed 的整块平移）。
func loadPersonality(cfg *types.Config, cfgReg *config.ConfigRegistry) *agentPkg.Personality {
personalPath := filepath.Join(cfg.Daemon.DataDir, "personal", "personal.md")
personality, err := agentPkg.LoadPersonality(personalPath)
if err != nil {
log.Printf("[homed] warning: load personality: %v", err)
}
if personality != nil && personality.Content != "" {
log.Printf("[homed] 人格来源=文件 %s（优先于配置项），%d 字节", personalPath, len(personality.Content))
if hints := agentPkg.PersonaStaleHints(personality.Content); len(hints) > 0 {
log.Printf("[homed] warning: 人格文件含会腐坏的内容 %v — 建议迁到配置项 core.agent.personal_prompt"+
"（默认模板不含版本号，被问版本时以运行时快照为准）", hints)
}
} else if pv := cfgReg.GetString("core.agent.personal_prompt", config.DefaultPersonaPrompt); strings.TrimSpace(pv) != "" {
personality = &agentPkg.Personality{Content: pv, Path: "(core.agent.personal_prompt)"}
log.Printf("[homed] 人格来源=配置项 core.agent.personal_prompt，%d 字节", len(pv))
} else {
log.Printf("[homed] 人格来源=无（配置项为空且无人格文件）")
}
return personality
}
// errMissing 报告"依赖的模块产物为 nil"。
//
// ★ 为什么立刻报错而不是让 nil 传下去：nil 读出零值后 continue 会在**很远
// 的地方**变成模糊症状（如"模型没有配置"）。这里点出**是哪个模块的哪个
// 产物缺失**，把排查成本从"追几小时"降到"看一行"。
//
// 措辞刻意点出"依赖图本应保证它非 nil" —— 若真出现，说明
// ① 模块忘了声明依赖，或 ② Requires/Provides 设施名不一致（拼写漂移）。
func errMissing(moduleName, facility string) error {
return fmt.Errorf("模块 %s 依赖的设施 %q 对应的数据为 nil —— "+
"依赖图本应保证它已就绪。两种可能：① 该模块没在 Requires 里声明这个依赖；"+
"② Provides/Requires 的设施名写得不一致（拼写漂移）", moduleName, facility)
}
var _ = events.EventMemoryAccess
var _ = memory.AccessEvent{}

43
internal/kernelmod/all/all.go Normal file
View File

@ -0,0 +1,43 @@
// Package all 把全部内核模块**引入编译**（Go 要求 import 才会编译进来）。
//
// ## 为什么这层是必要的（一个真实的 Go 约束）
//
// 模块各自在 init() 里 `kernelmod.Register(...)`，但必须有东西把它们
// 引进来。若把 import 写在 `kernelmod/core.go` 里：
//
// core.go import lua/ ⇒ core → lua → core（lua 要调 Register 必须 import core）
// ⇒ **循环导入**，Go 禁止
//
// 所以注册表 API 在 `kernelmod` 包，模块 import 它（单向），
// 而"引进来"的清单放在**本子包**（`kernelmod/all`）—— 它 import 两者。
//
// ## 加一个新模块要做什么（**唯一的一处编辑**）
//
// ① 新建 internal/kernelmod/<name>/mod.go，实现 kernelboot.Module
// ② 在**本文件**加一行空白 import
//
// 依赖写在模块自己的 Requires() 里 —— **没有**中央依赖清单。
package all
import (
// 每个模块一个独立文件夹（用户设计）。
//
// ★ 顺序**无关**：模块注册顺序由 init() 决定，而注册表刻意乱序
// （见 kernelmod/core.go）。真正的先后只由 Requires/Provides 决定。
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/agent"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/config"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/docstore"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/kernelapi"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/knowledge"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/llm"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/lua"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/memory"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/migration"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/multimodal"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/onnx"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/pluginhost"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/stagehost"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/supervisor"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/textmem"
_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/tracker"
)

112
internal/kernelmod/all/facilities_sync_test.go Normal file
View File

@ -0,0 +1,112 @@
package all
// 设施名「内核 ↔ 公开 SDK」一致性判据（2026-10-16）。
//
// ## 为什么需要它
//
// 设施名同时存在于**两处**，且必须逐字一致：
//
// 内核：internal/kernelmod/facilities.go （模块 Provides 用）
// SDK：third_party/homeagent-sdk/sdk/facilities.go （插件声明用）
//
// 它们**不能合并**：SDK 是独立发布的模块（外部插件依赖它），
// 而内核的 internal 规则又禁止内部包被外部 import。
//
// ⇒ 两处并存 ⇒ 有漂移风险。**改一处忘另一处**的后果是：
// 插件按 SDK 声明的名字，内核从未注册 ⇒ 插件**永不启动**，且（在本判据
// 与运行期校验出现前）无任何报错。
//
// 本判据把"两边一致"变成可执行的检查。
//
// ## 为什么必须从**源码**提取而不是手写清单
//
// 手写清单在"新增了一个设施名但只改了内核"时**也不会包含新名字**
// ⇒ 判据照样绿（守卫形同虚设）。本仓已有先例
// （TestCapability_AllMethodsClassified 初版就是这个毛病）。
import (
"os"
"path/filepath"
"regexp"
"sort"
"testing"
)
// internalOnlyFacilities 是**内核内部**顺序标记（不是给插件的契约）。
//
// ★ 判据要排除它们：它们的消费者是内核模块，不该进公开 SDK。
// 若把它们也拿去比对，会得到"内核有但 SDK 没有"的**假红**（实测撞到：
// knowledge-migrated）。反向也要防：有人误把内部标记放进 SDK 当对外契约。
var internalOnlyFacilities = map[string]bool{
"knowledge-migrated": true,
}
// extractFacilities 从 Go 源码里提取 `FacilityXxx = "值"` 形式的常量。
func extractFacilities(t *testing.T, path string) map[string]string {
t.Helper()
b, err := os.ReadFile(path)
if err != nil {
t.Fatalf("读 %s: %v", path, err)
}
re := regexp.MustCompile(`(?m)^\s*(Fac[A-Za-z0-9_]*|Facility[A-Za-z0-9_]*)\s*=\s*"([^"]+)"`)
out := map[string]string{}
for _, m := range re.FindAllStringSubmatch(string(b), -1) {
out[m[1]] = m[2]
}
if len(out) < 10 {
t.Fatalf("只从 %s 提取到 %d 个设施常量 —— 正则或文件结构变了（判据会假绿）",
path, len(out))
}
return out
}
// ★★★ 判据：**内核与 SDK 的设施名值集合逐字一致**。
func TestFacilityNamesMatchPublicSDK(t *testing.T) {
kernel := extractFacilities(t, filepath.Join("..", "facilities.go"))
sdk := extractFacilities(t, filepath.Join("..", "..", "..",
"third_party", "homeagent-sdk", "sdk", "facilities.go"))
kernelVals := map[string]string{} // 值 → 内核常量名
for name, v := range kernel {
if internalOnlyFacilities[v] {
continue // 内核内部顺序标记，不是插件契约
}
kernelVals[v] = name
}
sdkVals := map[string]string{}
for name, v := range sdk {
sdkVals[v] = name
}
var missingInSDK, missingInKernel []string
for v, name := range kernelVals {
if _, ok := sdkVals[v]; !ok {
missingInSDK = append(missingInSDK, name+"="+v)
}
}
for v, name := range sdkVals {
if _, ok := kernelVals[v]; !ok {
missingInKernel = append(missingInKernel, name+"="+v)
}
}
sort.Strings(missingInSDK)
sort.Strings(missingInKernel)
if len(missingInSDK) > 0 {
t.Errorf("★ 内核有但**公开 SDK 没有**的设施名: %v\n"+
" 后果：插件作者无法 import 该常量（只能照文档抄 ⇒ 易拼错），"+
"且打包期校验会把它当'未知设施名'而拒绝", missingInSDK)
}
for v := range sdkVals {
if internalOnlyFacilities[v] {
t.Errorf("★ 公开 SDK 里出现了内核**内部顺序标记** %q —— "+
"它的消费者是内核模块，不该成为插件契约（插件声明它没有意义，"+
"且会误导作者以为可用）", v)
}
}
if len(missingInKernel) > 0 {
t.Errorf("★ 公开 SDK 有但**内核没有**的设施名: %v\n"+
" 后果：插件按此声明 ⇒ 内核从未注册 ⇒ 插件**永不启动**（静默）",
missingInKernel)
}
}

351
internal/kernelmod/all/registry_test.go Normal file
View File

@ -0,0 +1,351 @@
package all
// 内核模块注册表 + 分层的判据（2026-10-16）。
//
// 设计见 docs/zh/kernel-modularization-design.md §2.3/§2.6/§2.8。
//
// ## 用户的验收标准（必须被判据钉住）
//
// > 模块应该在 /modelname/ 独立文件夹下，根目录只有 core.go，
// > core 内有一个注册表注册各个模块 … 注意注册表中的模块列表是乱序的
//
// ⇒ 四条底线：
// ① 每个模块**独立文件夹**
// ② 依赖写在**模块自己**的 Requires() 里（无中央依赖清单）
// ③ 注册表列表**乱序**（顺序无意义，不能被依赖）
// ④ 第 0 层模块**不依赖任何模块**（"core 不依赖任何模块"字面成立）
import (
"fmt"
"os"
"path/filepath"
"regexp"
"sort"
"strings"
"testing"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
)
// ★★★ 判据：**依赖图可建 + 模块全登记 + 无重复**。
func TestRegistryBuildsValidGraph(t *testing.T) {
if d := kernelmod.Duplicates(); len(d) > 0 {
t.Fatalf("★ 模块名重复注册: %v（两个模块同名，或一个模块被导入两次）", d)
}
mods := kernelmod.Registered()
if len(mods) < 10 {
t.Fatalf("★ 只登记 %d 个模块 —— 可能有模块漏了 init() 注册", len(mods))
}
plan, err := kernelboot.Build(mods)
if err != nil {
t.Fatalf("★ 依赖图无解（结构错误）: %v", err)
}
total := 0
for _, l := range plan.Layers {
total += len(l)
}
if total != len(mods) {
t.Fatalf("★ 分层丢失模块: %d != %d", total, len(mods))
}
}
// ★★★ 判据（用户验收标准 ④）：**第 0 层不依赖任何模块**。
func TestFirstLayerHasNoDependencies(t *testing.T) {
plan, err := kernelboot.Build(kernelmod.Registered())
if err != nil {
t.Fatal(err)
}
for _, m := range plan.Layers[0] {
if len(m.Requires()) != 0 {
t.Errorf("★ 第 0 层模块 %s 有依赖 %v —— 分层正确的话不该有",
m.Name(), m.Requires())
}
}
names := map[string]bool{}
for _, m := range plan.Layers[0] {
names[m.Name()] = true
}
for _, want := range []string{"config", "kernel-api"} {
if !names[want] {
t.Errorf("★ %s 应在第 0 层（它不依赖任何模块）", want)
}
}
}
// ★★★ 判据（用户验收标准 ①②）：**每模块独立文件夹；依赖写在自己文件里**。
func TestEachModuleInOwnFolder(t *testing.T) {
root := ".."
entries, err := os.ReadDir(root)
if err != nil {
t.Fatal(err)
}
modDirs := 0
for _, e := range entries {
if !e.IsDir() {
continue
}
modDirs++
files, _ := filepath.Glob(filepath.Join(root, e.Name(), "*.go"))
if len(files) == 0 {
t.Errorf("★ 模块目录 %s 下没有 .go 文件", e.Name())
}
}
if modDirs < 10 {
t.Fatalf("★ 只找到 %d 个模块目录（期望 ≥10）", modDirs)
}
// ② 依赖不能出现在"中央清单"里：根目录只有 core.go/facilities.go/all 子包
for _, f := range []string{"core.go", "facilities.go"} {
b, err := os.ReadFile(filepath.Join(root, f))
if err != nil {
continue
}
src := string(b)
if strings.Contains(src, "Requires() []string { return []string{") {
t.Errorf("★ %s 里出现了具体的 Requires —— 依赖应写在各模块自己的文件里", f)
}
}
}
// ★★★ 判据（用户验收标准 ③）：**注册表列表乱序**（顺序无意义，不能被依赖）。
//
// ★ 怎么测"乱序"：注册顺序由 init() 决定。这里断言 Names() 的顺序
// **不等于**按名字排序的顺序 —— 若相等，说明有人给它排过序，
// 那会给使用者"这个顺序有意义"的错觉（用户明确要求乱序）。
//
// ⚠ 注意：这条是**性质检查**，不是绝对的（init 顺序恰好等于字典序时也会通过
// 排序检查）。所以真正守"顺序无意义"的是**文档 + 分层器内部排序**，
// 而本判据是"如果有人显式排序就报红"的报警器。
func TestRegistryOrderIsNotMeaningful(t *testing.T) {
names := kernelmod.Names()
if len(names) < 2 {
t.Fatal("模块太少")
}
sorted := append([]string(nil), names...)
sort.Strings(sorted)
if strings.Join(names, ",") == strings.Join(sorted, ",") {
t.Logf("提示：注册顺序恰好等于字典序（不必然是错误，但请确认没有人"+
"给注册表排序——顺序无意义是设计的一部分）: %v", names)
}
// 核心断言：Registered() 返回的列表**不得**按依赖序排列
// （即：不能有人把"启动顺序"写进注册表）
plan, err := kernelboot.Build(kernelmod.Registered())
if err != nil {
t.Fatal(err)
}
var layerOrder []string
for _, l := range plan.Layers {
for _, m := range l {
layerOrder = append(layerOrder, m.Name())
}
}
if strings.Join(names, ",") == strings.Join(layerOrder, ",") {
t.Fatal("★ 注册表顺序恰好等于**依赖分层序** —— 说明注册表被用来表达启动顺序了，" +
"那正是要消灭的隐式顺序依赖（用户要求注册表乱序）")
}
}
// ★★★ 判据：**关键顺序被依赖图保证**（每条都来自真实约束）。
func TestLayeringPreservesCriticalOrder(t *testing.T) {
plan, err := kernelboot.Build(kernelmod.Registered())
if err != nil {
t.Fatal(err)
}
layerOf := map[string]int{}
for i, l := range plan.Layers {
for _, m := range l {
layerOf[m.Name()] = i
}
}
cases := []struct{ a, b, why string }{
{"config", "lua", "initLuaVM(cfg) 收 cfg"},
{"lua", "llm", "initLLMProviders 收 luaVM"},
{"config", "memory", "initMemoryStack 收 cfgReg"},
{"knowledge-migration", "knowledge-store", "迁移必须早于 store 扫盘"},
{"llm", "stage-host", "newStageAndRegistry 收 providerMgr"},
{"memory", "stage-host", "newStageAndRegistry 收 mem.db"},
{"stage-host", "agent", "newMainAgent 收 stageHost"},
{"llm", "agent", "newMainAgent 收 provider"},
{"memory", "agent", "newMainAgent 收 mem.db"},
{"tracker", "agent", "newMainAgent 收 trk"},
}
for _, c := range cases {
la, ok1 := layerOf[c.a]
lb, ok2 := layerOf[c.b]
if !ok1 || !ok2 {
t.Errorf("模块缺失: %s=%v %s=%v", c.a, ok1, c.b, ok2)
continue
}
if la >= lb {
t.Errorf("★ %s 应在 %s 之前（%s），实际层号 %d >= %d", c.a, c.b, c.why, la, lb)
}
}
}
// ★★★ 判据：**text-memory 显式依赖 onnx-parser**（隐藏依赖，见 textmem 包注释）。
//
// ★ 不能用层号断言：text-memory 已因 memory 被推到第 2 层，
// 而 onnx-parser 在第 1 层 ⇒ 删掉依赖后层号依然满足。必须断言**声明本身**。
func TestHiddenDependencyOnnxDeclared(t *testing.T) {
src := readMod(t, filepath.Join("..", "textmem", "mod.go"))
if !strings.Contains(src, "FacONNX") {
t.Fatal("★ text-memory 未声明对 onnx-parser 的依赖 —— " +
"它在运行期读 nlp.defaultParser（onnx 模块写的包级单例）。" +
"当前靠 distillLoop 的 Interval=10min 碰巧安全；" +
"Interval 变小或解析器装配更后 ⇒ 静默降级（图记忆实体退化成整句复合值）")
}
}
// ★★★ 判据：**分层带来并行**（对照原 17 步串行）。
func TestLayeringYieldsParallelism(t *testing.T) {
mods := kernelmod.Registered()
plan, err := kernelboot.Build(mods)
if err != nil {
t.Fatal(err)
}
maxLayer := 0
for _, l := range plan.Layers {
if len(l) > maxLayer {
maxLayer = len(l)
}
}
if len(plan.Layers) >= len(mods) {
t.Fatalf("★ 无并行度（%d 层 / %d 模块）", len(plan.Layers), len(mods))
}
t.Logf("并行度: %d 层 / %d 模块，最宽层 %d 个", len(plan.Layers), len(mods), maxLayer)
}
func readMod(t *testing.T, path string) string {
t.Helper()
b, err := os.ReadFile(path)
if err != nil {
t.Fatalf("读 %s: %v", path, err)
}
return string(b)
}
// ★★★ 判据：**每个模块目录都被 import 引入**（漏 import ⇒ 模块静默消失）。
//
// ## ★ 这条是变异测试发现的**真实覆盖漏洞**
//
// 我删掉 `all.go` 里 `multimodal` 的 import 后，**全部判据仍然通过** ——
// 因为：
//
// · 依赖图仍然解得开（multimodal **没有下游依赖**，没人需要它）
// · 注册表数量检查只有 `>= 10` 这种下限（少一个不报）
//
// 后果：**多模态能力凭空消失**，而启动照常成功、无任何报错。
// 这与本仓反复吃亏的"静默降级"是同一形态：
//
// · 漏 import 插件包 ⇒ 插件静默消失（已有同类教训）
// · 漏 import 模块包 ⇒ 模块静默消失（本条）
//
// ## 判据做法：**统计目录 vs 统计注册**
//
// 扫描 `internal/kernelmod/` 下的模块目录（含 `mod.go` 或实现 Module 的 .go
// 文件），与注册表里的模块名比对 —— 目录有而注册表没有 ⇒ 漏 import。
//
// ★ 为什么不用"手写清单"：手写清单在"新增目录忘了加 import"时
// **也不会包含新目录** ⇒ 判据照样绿（本仓已有先例）。
func TestEveryModuleDirIsImported(t *testing.T) {
root := ".."
entries, err := os.ReadDir(root)
if err != nil {
t.Fatal(err)
}
registered := map[string]bool{}
for _, n := range kernelmod.Names() {
registered[n] = true
}
// 收集"看起来是模块目录"的：含 .go 文件、且文件里有 kernelmod.Register 调用
var moduleDirs []string
for _, e := range entries {
if !e.IsDir() {
continue
}
name := e.Name()
if name == "all" {
continue // 这个子包是 import 清单本身
}
files, _ := filepath.Glob(filepath.Join(root, name, "*.go"))
hasRegister := false
for _, f := range files {
if strings.Contains(f, "_test.go") {
continue
}
b, err := os.ReadFile(f)
if err != nil {
continue
}
if strings.Contains(string(b), "kernelmod.Register(") {
hasRegister = true
break
}
}
if hasRegister {
moduleDirs = append(moduleDirs, name)
}
}
if len(moduleDirs) < 5 {
t.Fatalf("只找到 %d 个模块目录 —— 扫描逻辑失效（判据会假绿）", len(moduleDirs))
}
// 每个模块目录里的 Register(...) 参数名 → 期望的模块名
// （用"目录名"与"注册名"的映射，因为目录名与 Name() 不必相同）
dirToNames := map[string][]string{}
for _, d := range moduleDirs {
files, _ := filepath.Glob(filepath.Join(root, d, "*.go"))
for _, f := range files {
if strings.Contains(f, "_test.go") {
continue
}
b, _ := os.ReadFile(f)
// ★ 正则要容忍 gofmt 的对齐空格（列对齐会让 `{` 前有多个空格）。
// 初版写成 `\{ return` （单空格）⇒ 只匹配到 agent 一个，
// 其余全部"找不到目录"（判据假红）。实测撞到。
re := regexp.MustCompile(`(?m)^func \([A-Za-z0-9_]+\) Name\(\) string\s+\{ return "([^"]+)" \}`)
for _, m := range re.FindAllStringSubmatch(string(b), -1) {
dirToNames[d] = append(dirToNames[d], m[1])
}
}
}
var missing []string
for dir, names := range dirToNames {
if len(names) == 0 {
continue
}
// 该目录的**每个**模块名都必须在注册表里
//（一个目录可含多个模块，如 knowledge/{migration,store}）
anyFound := false
for _, n := range names {
if registered[n] {
anyFound = true
}
}
if !anyFound {
missing = append(missing, fmt.Sprintf("%s(%v)", dir, names))
}
}
sort.Strings(missing)
if len(missing) > 0 {
t.Fatalf("★ 这些模块目录**没有被 import 引入**（模块静默消失，启动不报错）: %v\n"+
" 修复：在 internal/kernelmod/all/all.go 里加空白 import", missing)
}
// 反向：注册表里的每个模块都应能对应到某个目录
known := map[string]bool{}
for _, ns := range dirToNames {
for _, n := range ns {
known[n] = true
}
}
for n := range registered {
if !known[n] {
t.Errorf("★ 注册表里的模块 %s 找不到对应目录 —— 可能是测试夹具注册的，或扫描漏了", n)
}
}
}

43
internal/kernelmod/config/mod.go Normal file
View File

@ -0,0 +1,43 @@
// Package config 是 config 模块：提供配置快照（ks.Cfg）。
//
// ## ★ 它解决了"cfg 是无主模块"的问题
//
// 原先 `cfg := cfgReg.ToConfig()` 之后，cfg 是**游离的局部变量**，
// 被手工传给 11 个 init* —— 谁需要它就靠人肉排在那一行之后。
// 现在它住在 `ks.Cfg`，任何模块直接读即可。
//
// ## 依赖：图上为空，但隐含"必须在 Group 0 之后"
//
// 它读 core.llm.* 里的**密文** ⇒ 必须在安全块（装好密钥）之后。
// 但这不是**图内依赖**（安全块不由任何调度模块提供；声明 crypto 会让
// Build 报"依赖了不存在的设施"）。更本质：那是**时序**要求，不是**数据**依赖。
//
// ⇒ 由 Group 0 阶段保证：Group 0 串行跑完 ⇒ 才启动本调度器。
package config
import (
"fmt"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
)
// Module 提供配置快照。
type Module struct{}
func (Module) Name() string { return "config" }
func (Module) Requires() []string { return nil } // 前提由 Group 0 保证
func (Module) Provides() []string { return []string{kernelmod.FacConfig} }
func (Module) Init(ks *kernelboot.KernelState) error {
// ★ 检查而不是假设（用户说的"nil 加读取前检查"）：
// ks.Cfg 为 nil 说明 Group 0 段没跑或顺序错了。响亮报错远好于让后续
// 模块拿到 nil —— 那会在很远的地方变成"模型没有配置"之类的模糊症状。
if ks.Cfg == nil {
return fmt.Errorf("config 模块：ks.Cfg 为 nil —— Group 0 必须先完成 " +
"`cfg := cfgReg.ToConfig()`（且必须在安全块之后，否则密文解不开 ⇒ 全 provider 401）")
}
return nil
}
func init() { kernelmod.Register(Module{}) }

141
internal/kernelmod/core.go Normal file
View File

@ -0,0 +1,141 @@
// Package kernelmod 是内核模块的**注册表**（用户设计的 core）。
//
// ## 用户的设计意图（原话）
//
// > 模块应该在 /modelname/ 独立文件夹下，根目录只有 core.go，
// > core 内有一个注册表注册各个模块，各个模块通过该注册表得知内核有哪些模块，
// > 从而声明对其他模块的依赖，注意注册表中的模块列表是乱序的，
// > 只是为了向模块展示内核注册了哪些模块
//
// ## 目录形状
//
// internal/kernelmod/
// ├── core.go ← 本文件：注册表（+ 唯一的 import 清单）
// ├── facilities.go ← 设施名常量（模块间的协议）
// ├── config/mod.go ← 每个模块一个独立文件夹
// ├── kernelapi/mod.go
// ├── lua/mod.go
// ├── llm/mod.go
// ├── memory/mod.go
// ├── supervisor/mod.go
// ├── tracker/mod.go
// ├── textmem/mod.go
// ├── docstore/mod.go
// ├── knowledge/{migration,store}.go
// ├── multimodal/mod.go
// ├── onnx/mod.go
// ├── stagehost/mod.go
// └── agent/mod.go
//
// ## 职责边界（刻意做窄）
//
// 本文件**只做两件事**：
//
// · `Register(m)` —— 模块在 init() 里自注册
// · `Registered()` —— 返回已注册模块（**乱序**，仅供查询"内核有哪些模块"）
//
// 它**不做**依赖解析/分层/执行 —— 那些是 `internal/kernelboot` 的事。
// 分开的理由：注册表是"名册"，分层器是"调度器"。混在一起会让
// "只想知道有哪些模块"的人被迫拉进整个调度逻辑。
//
// ## ★ 为什么列表是"乱序"，以及这为什么是对的
//
// 注册顺序取决于 **Go 的 init() 执行顺序**（由 import 图决定，
// 规范未定义跨包的**具体**顺序）。若把注册顺序当成"可信的启动顺序"，
// 那就是**隐式顺序依赖** —— 正是本设计要消灭的东西（§1 的病 A）。
//
// 所以 `Registered()` **刻意不排序**，并明确"顺序无意义"：
//
// · 模块只能用它回答"内核注册了哪些模块"
// · **不能**用它推断先后 —— 先后只由 Requires/Provides 决定
//
// ★ 分层器（kernelboot.Build）内部会按名字排序以保证**结果可复现**，
// 那是分层器的实现细节，与"注册表乱序"不矛盾。
//
// ## ★ 关于下面那份 import 清单（为什么必须有，且它是**唯一**的一处）
//
// Go 要求"包被 import 才会编译进来"。模块各自在 init() 里注册，
// 但**必须有东西把它们引进来** —— 这就是下面那些空白导入。
//
// 为什么不能省（也解释了一个真实的 Go 约束）：
//
// core.go 想 import lua/ ⇒ core → lua → core（lua 要调 Register）
// ⇒ **循环导入**，Go 禁止
//
// 解法：注册表 API 放在**本包**、模块 import 本包（单向），
// 而"把它们引进来"的清单只能放在**本包之外** —— 见
// `internal/kernelmod/all/all.go`（只做 import，无逻辑）。
//
// ⇒ 加模块 = **加一个文件夹 + 在 all.go 加一行**（唯一的一处编辑）。
package kernelmod
import (
"sync"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
)
var (
mu sync.Mutex
list []kernelboot.Module
seen = map[string]bool{}
dups []string
)
// Register 由模块在自己的 init() 里调用。
//
// 重复注册同名模块会被**记录**（不 panic）：panic 发生在 init 阶段，
// 栈信息对使用者毫无意义（他只想知道哪个模块重名）。由 Registered 报出。
func Register(m kernelboot.Module) {
if m == nil {
return
}
mu.Lock()
defer mu.Unlock()
name := m.Name()
if seen[name] {
dups = append(dups, name)
return
}
seen[name] = true
list = append(list, m)
}
// Registered 返回全部已注册模块。
//
// ★ **顺序无意义**（见包注释）：它取决于 init() 执行顺序。
// 只用它回答"内核注册了哪些模块"，**不要**用它推断先后。
func Registered() []kernelboot.Module {
mu.Lock()
defer mu.Unlock()
out := make([]kernelboot.Module, len(list))
copy(out, list)
return out
}
// Duplicates 返回重复注册的模块名（诊断用）。
func Duplicates() []string {
mu.Lock()
defer mu.Unlock()
out := make([]string, len(dups))
copy(out, dups)
return out
}
// Names 返回已注册模块名（诊断用；顺序同 Registered，无意义）。
func Names() []string {
mu.Lock()
defer mu.Unlock()
out := make([]string, 0, len(list))
for _, m := range list {
out = append(out, m.Name())
}
return out
}
// IsRegistered 报告某模块是否已注册（模块可用它判断依赖是否存在）。
func IsRegistered(name string) bool {
mu.Lock()
defer mu.Unlock()
return seen[name]
}

37
internal/kernelmod/docstore/mod.go Normal file
View File

@ -0,0 +1,37 @@
// Package docstore 是 doc-store 模块：文档记忆（文本块 + 向量）。
//
// 依赖 config：`initDocStore(cfg)` 读 cfg.Daemon.DataDir。
package docstore
import (
"log"
"path/filepath"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/memory"
"github.com/JianFeeeee/HomeAgent/internal/memory/document"
)
// Module 提供文档记忆。
type Module struct{}
func (Module) Name() string { return "doc-store" }
func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
func (Module) Provides() []string { return []string{kernelmod.FacDocStore} }
func (Module) Init(ks *kernelboot.KernelState) error {
docStore := document.NewStore(
filepath.Join(ks.Cfg.Daemon.DataDir, "memory", "documents"), memory.TokenizeWords)
if err := docStore.Start(); err != nil {
log.Printf("[homed] warning: document store: %v", err)
}
// 关停时落盘：文档记忆的内存态变更（迁移结果、访问计数等）只在 flush 里写盘，
// 而 flush 的唯一入口是 Stop() —— 此前全仓无人调用它，
// 于是迁移结果永不落盘、每次启动白算一遍。
ks.DocStore = docStore
ks.AddCloser(docStore.Stop)
return nil
}
func init() { kernelmod.Register(Module{}) }

46
internal/kernelmod/facilities.go Normal file
View File

@ -0,0 +1,46 @@
package kernelmod
// 设施名常量（依赖图上被引用的名字）。
//
// ★ 为何用常量而不是裸字符串：拼错依赖名时**编译不过**，
// 而不是"永远等不到就绪"（运行期表现是静默挂起 / 静默拿到 nil，极难排查）。
//
// ★ 为何放在 core.go 之外：用户要求"根目录只有 core.go"，
// 而 core.go 专注注册表职责。设施名是**模块间的协议**，与注册表分开更清晰。
const (
// ── 插件可依赖的设施（与公开 SDK 的 sdk.Facility* **逐字一致**）──
//
// ★ 判据 TestFacilityNamesMatchPublicSDK 守这个一致性。
// 这些名字会出现在 plugin.json 的 requires_facilities 里。
FacConfig = "config"
FacKernelIO = "kernel-io"
FacMemory = "memory"
FacLua = "lua"
FacSupervisor = "supervisor"
FacTracker = "tracker"
FacTextMem = "textmem"
FacLLM = "llm"
FacDocStore = "docmem"
FacKnowledge = "knowledge"
FacMultimodal = "multimodal"
FacONNX = "onnx"
FacStageHost = "stagehost"
FacAgent = "agent"
// ── 内核**内部**顺序标记（**不是**给插件的设施）──
//
// ★ 为什么不与上面的混在一起：这两类东西的**消费者不同**。
// · 上面的：插件按它声明启动时机（对外契约，必须进公开 SDK）
// · 这里的：只用于**内核模块之间**表达顺序（如"迁移必须先于扫盘"）
//
// 混在一起会让"内核内部标记"被误当成"插件可选设施"
// ⇒ 插件可能声明它（然后永远等不到 —— 因为它的就绪时机是装配中途，
// 而插件提交发生在装配**完成之后**……实际会立刻满足，但语义是错的：
// 它不该成为插件的契约）。
//
// 判据 TestFacilityNamesMatchPublicSDK 只比对上面那组 ⇒ 天然拦住
// "把内部标记泄漏成对外契约"。
// FacMigrated 标记"知识库目录迁移已完成"（用于让 store 排在迁移之后）。
FacMigrated = "knowledge-migrated"
)

35
internal/kernelmod/kernelapi/mod.go Normal file
View File

@ -0,0 +1,35 @@
// Package kernelapi 是 kernel-api 模块：IOManager + EventBus。
//
// ## 依赖：**真无依赖**
//
// `initKernelAPI()` 不收任何参数 ⇒ 它与 config 并列第 0 层。
// 这条"真无依赖"是有意的：让"最先初始化的 core 不依赖任何模块"
// 在代码里**字面成立**。
package kernelapi
import (
"log"
agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
"github.com/JianFeeeee/HomeAgent/internal/events"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
)
// Module 提供 IO 抽象层与事件总线。
type Module struct{}
func (Module) Name() string { return "kernel-api" }
func (Module) Requires() []string { return nil }
func (Module) Provides() []string { return []string{kernelmod.FacKernelIO} }
func (Module) Init(ks *kernelboot.KernelState) error {
iom := agentIO.NewIOManager()
evBus := events.NewBus()
log.Printf("[homed] kernel API ready: IOManager + EventBus")
ks.IO = iom
ks.EventBus = evBus
return nil
}
func init() { kernelmod.Register(Module{}) }

53
internal/kernelmod/knowledge/migrate_impl.go Normal file
View File

@ -0,0 +1,53 @@
package knowledge
import (
"log"
"github.com/JianFeeeee/HomeAgent/internal/knowledge"
)
// runKnowledgeMigration 是本迁移的真实实现（原 cmd/homed 的整块平移：
// 语句、日志文本、错误语义不变，只把 cfg 参数换成 root）。
func runKnowledgeMigration(root string) {
const (
// defaultApply = false ⇒ 启动时只扫描并报告，不改名。
defaultApply = false
// maxRenamePerRun 限制单次重命名数：给失控的目录规模设上限，
// 避免启动阶段被一次大迁移拖住。
maxRenamePerRun = 200
)
items, err := knowledge.PlanMigration(root)
if err != nil {
log.Printf("[homed] 知识库迁移扫描失败（跳过）: %v", err)
return
}
need, illegal := 0, 0
for _, it := range items {
if it.Illegal {
illegal++
} else if it.NewName != "" {
need++
}
}
if need == 0 && illegal == 0 {
return
}
if illegal > 0 {
log.Printf("[homed] 知识库迁移：%d 条名称非法（含 .. / 点段 / 隐藏段），写入与删除均已拒绝，需人工处理", illegal)
}
if need == 0 {
return
}
log.Printf("[homed] 知识库迁移：%d/%d 条目录名待规范化（例：%s → %s）", need, len(items),
items[0].OldName, items[0].NewName)
if !defaultApply {
log.Printf("[homed] 知识库迁移：当前为只报告模式。确认清单后执行：homed-kb-migrate -root %s -apply", root)
return
}
if need > maxRenamePerRun {
log.Printf("[homed] 知识库迁移：需改名 %d 条超过单次上限 %d，本次只处理前 %d 条",
need, maxRenamePerRun, maxRenamePerRun)
}
applied, failed := knowledge.ApplyMigration(root, items, maxRenamePerRun)
log.Printf("[homed] 知识库迁移完成：成功 %d，失败 %d", applied, failed)
}

36
internal/kernelmod/knowledge/migration.go Normal file
View File

@ -0,0 +1,36 @@
// 知识库目录改名迁移（幂等）。**独立模块**，见下。
//
// ## ★ 为什么迁移必须是独立模块而不是 store 里的一行
//
// 原 main 注释："迁移必须在 store 扫盘**之前**：改名后扫盘一次到位，
// 避免先以旧名建索引、再改名造成内存键与盘上目录短暂不一致"。
//
// 这是**真实的顺序约束**（不是副作用顺序，是"必须先改名再扫盘"）⇒
// 在依赖图上是知识库 store 的前置。声明成依赖 ⇒ 分层器保证它们**不同层**
// （同层就是并行了，那会破坏约束）。
//
// ★ 若把迁移并进 store 的 Init 里，这个约束就"藏在函数体内"了 ——
// 那正是"加模块必须调顺序"的病根形态。
package knowledge
import (
"path/filepath"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
)
// MigrationModule 做知识库目录改名迁移。
type MigrationModule struct{}
func (MigrationModule) Name() string { return "knowledge-migration" }
func (MigrationModule) Requires() []string { return []string{kernelmod.FacConfig} }
func (MigrationModule) Provides() []string { return []string{kernelmod.FacMigrated} }
func (MigrationModule) Init(ks *kernelboot.KernelState) error {
root := filepath.Join(ks.Cfg.Daemon.DataDir, "knowledge")
runKnowledgeMigration(root)
return nil
}
func init() { kernelmod.Register(MigrationModule{}) }

33
internal/kernelmod/knowledge/store.go Normal file
View File

@ -0,0 +1,33 @@
// 知识库 store 模块。
package knowledge
import (
"log"
"path/filepath"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/knowledge"
)
// StoreModule 提供知识库。
type StoreModule struct{}
func (StoreModule) Name() string { return "knowledge-store" }
func (StoreModule) Requires() []string {
// ★ FacMigrated 是**刻意的顺序依赖**：迁移必须早于扫盘（见 migration.go）。
return []string{kernelmod.FacConfig, kernelmod.FacMigrated}
}
func (StoreModule) Provides() []string { return []string{kernelmod.FacKnowledge} }
func (StoreModule) Init(ks *kernelboot.KernelState) error {
ks.Knowledge = knowledge.NewStore(filepath.Join(ks.Cfg.Daemon.DataDir, "knowledge"))
if err := ks.Knowledge.Start(); err != nil {
log.Printf("[homed] warning: knowledge store: %v", err)
} else {
log.Printf("[homed] knowledge store active with %d items", len(ks.Knowledge.List()))
}
return nil
}
func init() { kernelmod.Register(StoreModule{}) }

89
internal/kernelmod/llm/mod.go Normal file
View File

@ -0,0 +1,89 @@
// Package llm 是 llm 模块：多源 Provider 管理（经 Lua 适配器做协议转换）。
//
// 依赖 config + lua：`initLLMProviders(cfg, luaVM, baseAPIKey)`。
package llm
import (
"log"
"os"
"github.com/JianFeeeee/HomeAgent/internal/agent/api"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
luapkg "github.com/JianFeeeee/HomeAgent/internal/lua"
"github.com/JianFeeeee/HomeAgent/pkg/types"
)
// Module 提供多源 provider 管理。
type Module struct{}
func (Module) Name() string { return "llm" }
func (Module) Requires() []string { return []string{kernelmod.FacConfig, kernelmod.FacLua} }
func (Module) Provides() []string { return []string{kernelmod.FacLLM} }
func (Module) Init(ks *kernelboot.KernelState) error {
// ★ 敏感信息防火模块的装配点。
//
// 原 main 注释："必须在任何 provider 注册之前装配"—— provider 的出向
// 装饰器在 ProviderManager.Register 里读 security.Global()。装配晚了，
// 先注册的那批 provider 就没被装饰（静默漏掉一条出网路径）。
//
// 实测：该装配**就在 initLLMProviders 内部**（不是 main 的独立语句）
// ⇒ 声明式下它天然"紧邻"，不再依赖 main 里那两行的相对位置。
ks.BaseAPIKey = resolveBaseAPIKey(ks.Cfg)
ks.LLMManager = buildProviderManager(ks.Cfg, ks.LuaVM, ks.BaseAPIKey)
ks.LLMProvider = ks.LLMManager.Default()
return nil
}
// buildProviderManager 按配置注册全部 LLM 源（原 cmd/homed 的整块平移）。
func buildProviderManager(cfg *types.Config, luaVM *luapkg.VM, baseAPIKey string) *api.ProviderManager {
providerMgr := api.NewProviderManager()
adapterConcurrency := map[string]int{}
for _, src := range cfg.LLM.Sources {
if !api.IsValidSourceConfig(src.Name, src.BaseURL, src.Model, src.Adapter) {
log.Printf("[homed] skip invalid llm source %q (base_url=%q model=%q adapter=%q)",
src.Name, src.BaseURL, src.Model, src.Adapter)
continue
}
key := src.APIKey
if key == "" {
key = baseAPIKey
}
luaProvider := api.NewLuaAdaptedProvider(api.BaseConfig{
Model: src.Model,
BaseURL: src.BaseURL,
APIKey: key,
Temperature: cfg.LLM.Temperature,
MaxTokens: cfg.LLM.MaxTokens,
ContextWindow: src.ContextWindow,
MaxConcurrent: src.MaxConcurrent,
Priority: src.Priority,
Vision: src.Vision,
Audio: src.Audio,
}, luaVM, src.Name, src.Adapter)
providerMgr.Register(src.Name, luaProvider)
if src.Adapter != "" {
adapterConcurrency[src.Adapter] += src.MaxConcurrent
}
}
luaVM.ConfigureConcurrency(adapterConcurrency)
if cfg.LLM.Provider != "" {
providerMgr.SetDefault(cfg.LLM.Provider)
}
return providerMgr
}
// resolveBaseAPIKey 决定基础 key（配置 > LLM_API_KEY > DEEPSEEK_API_KEY）。
func resolveBaseAPIKey(cfg *types.Config) string {
apiKey := cfg.LLM.APIKey
if apiKey == "" {
apiKey = os.Getenv("LLM_API_KEY")
}
if apiKey == "" {
apiKey = os.Getenv("DEEPSEEK_API_KEY")
}
return apiKey
}
func init() { kernelmod.Register(Module{}) }

34
internal/kernelmod/lua/mod.go Normal file
View File

@ -0,0 +1,34 @@
// Package lua 是 lua 模块：Lua VM（LLM 协议适配）。
//
// 依赖 config：`initLuaVM(cfg)` 读 cfg.Daemon.DataDir（adapter 目录）。
package lua
import (
"log"
"path/filepath"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
luapkg "github.com/JianFeeeee/HomeAgent/internal/lua"
)
// Module 提供 Lua 协议适配 VM。
type Module struct{}
func (Module) Name() string { return "lua" }
func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
func (Module) Provides() []string { return []string{kernelmod.FacLua} }
func (Module) Init(ks *kernelboot.KernelState) error {
luaVM := luapkg.NewVM(filepath.Join(ks.Cfg.Daemon.DataDir, "adapters"))
if err := luaVM.Start(); err != nil {
log.Printf("[homed] warning: lua vm init failed: %v", err)
ks.LuaVM = luaVM
return nil // 与原语义一致：起不来只告警，仍交回实例
}
ks.LuaVM = luaVM
ks.AddCloser(luaVM.Stop)
return nil
}
func init() { kernelmod.Register(Module{}) }

85
internal/kernelmod/memory/distiller_wiring_test.go Normal file
View File

@ -0,0 +1,85 @@
package memory
// 蒸馏器接线回归判据（从 cmd/homed/bootstrap_test.go 迁移而来）。
//
// ## 为什么这条判据必须存在（历史 bug）
//
// `main()` 拆分时，initMemoryStack 函数体内残留一句 `defer distiller.Stop()`，
// 函数一 return 就 cancel 掉刚启动的循环 ⇒ **规则蒸馏 10min 心跳从不运行**。
//
// ★ 该缺陷**不会让任何单测变红** —— pipeline 的 `TestDistillOnce*` 直接调
// `distillOnce`，**绕过了 Start/Stop 接线**。只有按「启动阶段函数」的真实
// 调用方式断言（调用 → 检查仍在跑 → 调 cleanup → 检查已停），才照得出来。
//
// ## 迁移说明
//
// 本判据原先针对 `cmd/homed` 的 `initMemoryStack`。模块化后该逻辑搬进
// `internal/kernelmod/memory.Module.Init`，所以判据跟着搬 —— 且**必须保留**：
// 迁移过程中"忘了 AddCloser"或"改成 defer"是同一类缺陷的新形态。
//
// 判据改为直接跑真实模块（经 kernelboot.Run），确保测的是**真实入口**。
import (
"os"
"path/filepath"
"testing"
internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
)
// ★★★ 判据：模块 Init 返回后蒸馏器**仍在运行**（无 defer Stop 残留）。
func TestMemoryModuleKeepsDistillerRunning(t *testing.T) {
dir := t.TempDir()
if err := os.MkdirAll(filepath.Join(dir, "memory"), 0o755); err != nil {
t.Fatal(err)
}
// ★ 需要真 cfgReg：memory 模块读 core.agent.embedding_model_path，
// 而它对 nil 会现在**明确报错**（而不是 panic 在 strings.Split）。
reg := internalConfig.NewConfigRegistry(filepath.Join(dir, "config.db"))
defer reg.Close()
ks := &kernelboot.KernelState{DataDir: dir, CfgReg: reg}
if err := (Module{}).Init(ks); err != nil {
t.Fatalf("memory 模块 Init: %v", err)
}
if ks.Memory == nil || ks.Memory.Distiller == nil {
t.Fatal("memory 模块未产出蒸馏器")
}
if ks.Memory.DB == nil {
t.Skip("图库未初始化，无法验证蒸馏接线")
}
// ★ 关键断言：Init 已返回，蒸馏循环必须还在跑
if ks.Memory.Distiller.Stopped() {
t.Fatal("★ memory 模块 Init 返回后蒸馏循环已被停掉" +
"（defer Stop 残留？）—— 规则蒸馏 10min 心跳将从不运行")
}
// 关闭函数是唯一的停机点（经 AddCloser 登记，由 KernelState.CloseAll 逆序执行）
if err := ks.CloseAll(); err != nil {
t.Fatalf("CloseAll: %v", err)
}
if !ks.Memory.Distiller.Stopped() {
t.Fatal("CloseAll 之后蒸馏器应已停止（关闭函数未登记？）")
}
}
// ★★★ 判据：**关闭函数经 AddCloser 登记**（不是 defer）。
//
// 这是上一条的机制保证：若有人把 AddCloser 改回 defer，
// 上一条判据报红；本判据报"没登记"，两条互相印证、定位更快。
func TestMemoryModuleRegistersCloser(t *testing.T) {
dir := t.TempDir()
os.MkdirAll(filepath.Join(dir, "memory"), 0o755)
reg := internalConfig.NewConfigRegistry(filepath.Join(dir, "config.db"))
defer reg.Close()
ks := &kernelboot.KernelState{DataDir: dir, CfgReg: reg}
if err := (Module{}).Init(ks); err != nil {
t.Fatal(err)
}
// 内存模块应恰好登记 1 个关闭函数（停蒸馏器 + 关图库，合在一个闭包里）
if len(ks.Closers) != 1 {
t.Fatalf("★ 应登记 1 个关闭函数，实际 %d —— "+
"若为 0 说明改成了 defer（Init 返回即停机）", len(ks.Closers))
}
}

149
internal/kernelmod/memory/mod.go Normal file
View File

@ -0,0 +1,149 @@
// Package memory 是 memory 模块：图记忆 + 索引 + 社交图 + 蒸馏管线 + 共享词嵌入。
//
// ## 为什么依赖 kernel-io
//
// 本模块产出 MemoryBundle（4 个同生共死的东西打包）。它**不**直接读 IO，
// 但"记忆子系统就绪"在语义上包含它后续要被候选消费管线使用，而那条管线需要 iom。
//
// ★ 这是**刻意声明**的依赖（不是签名要求的）：让"记忆子系统在 IO 就绪后才建"
// 成为结构保证 —— 若将来 initMemoryStack 内部要用 iom，不会因为"忘了声明"
// 而静默拿 nil。
package memory
import (
"fmt"
"log"
"path/filepath"
"strings"
"time"
"github.com/JianFeeeee/HomeAgent/internal/config"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/memory"
"github.com/JianFeeeee/HomeAgent/internal/memory/distill"
"github.com/JianFeeeee/HomeAgent/internal/memory/pipeline"
"github.com/JianFeeeee/HomeAgent/internal/memory/social"
"github.com/JianFeeeee/HomeAgent/pkg/generation"
)
// Module 提供图记忆子系统。
type Module struct{}
func (Module) Name() string { return "memory" }
func (Module) Requires() []string { return []string{kernelmod.FacKernelIO} }
func (Module) Provides() []string { return []string{kernelmod.FacMemory} }
func (Module) Init(ks *kernelboot.KernelState) error {
// ★ 读取前检查（用户指定的做法："结构体成员初始置 nil 加读取前检查"）。
//
// 为何要检查 CfgReg：它是 **Group 0** 的产物（不由任何调度模块提供），
// 所以不可能通过 Requires 声明它 —— 依赖图保证不了它非 nil。
// 而上面那行 `ks.CfgReg.GetString(...)` 在 nil 时会**panic**，
// 栈信息指向 strings.Split 之类无关处，排查成本高。
if ks.CfgReg == nil {
return fmt.Errorf("memory 模块：ks.CfgReg 为 nil —— " +
"Group 0 必须先建好配置中心（NewConfigRegistry）再启动本调度器")
}
if ks.DataDir == "" {
return fmt.Errorf("memory 模块：ks.DataDir 为空 —— 它是 Group 0 的产物，必须先设置")
}
memDB, err := memory.NewGraphDB(filepath.Join(ks.DataDir, "memory", "graph.db"))
if err != nil {
log.Printf("[homed] warning: memory init failed: %v", err)
memDB = nil
} else {
log.Printf("[homed] graph memory initialized")
}
memIdx := memory.NewIndexer(memDB)
memIdx.Sync() // 启动时立即同步，避免前 30 分钟空窗
socialStore := social.New(memDB)
distiller := pipeline.NewDistiller(memDB, ks.DataDir, pipeline.DistillerConfig{
Interval: 10 * time.Minute,
RetentionDays: 7,
BatchSize: 50,
})
// ★ 必须在 distiller.Start() **之前**注入：Start 会起 distillLoop，
// 而第一次 tick 在 Interval 之后。若先 Start 再注入，头一个周期
// （实测配置 10 分钟）会白跑一次 jieba 路 —— 而那条路实测产出 0 条。
if memDB != nil {
distiller.SetSplitter(initDistillSplitter(ks.CfgReg))
}
if memDB != nil {
// 这里**故意不写 defer distiller.Stop()**：函数 return 即触发 defer，
// 而 Stop() → cancel() 会让刚启动的 distillLoop 立刻退出，
// 规则蒸馏管线启动即死、10min 心跳从不运行（旧 main() 拆分时的残留）。
// 停机由 AddCloser 负责（见下方）。
distiller.Start()
}
ks.Memory = &kernelboot.MemoryBundle{
DB: memDB,
Indexer: memIdx,
Social: socialStore,
Distiller: distiller,
}
// 共享词嵌入：蒸馏与 Agent 上下文复用同一实例
// （避免同一模型被二次加载，约 200k×300 维 ≈ 数百 MB）。
ks.Embedder = memory.NewStaticEmbedder(
strings.Split(ks.CfgReg.GetString("core.agent.embedding_model_path", ""), ",")...)
distiller.SetEmbedder(ks.Embedder)
// ★ 伪关机登记（迁移数据目录用，见 kernelboot/lifecycle.go）。
// 只登记**持有写句柄**的 distiller —— 它每 10min 写 memory/graph.db，
// 迁移期间一旦写入就会搬走"写了一半的库"。
if ks.Memory != nil && ks.Memory.Distiller != nil {
ks.AddQuiescer("distiller",
func() error { return ks.Memory.Distiller.Pause() },
func() error { return ks.Memory.Distiller.Resume() })
}
ks.AddCloser(func() {
// 与原 main 的两个 defer 同序（LIFO）：先停蒸馏器，再关图库。
if memDB != nil {
distiller.Stop()
memDB.Close()
}
})
return nil
}
// initDistillSplitter 按配置打开蒸馏用的生成侧 provider 并组装拆分器。
//
// 返回 nil 表示不启用（未配置 provider、或打开失败）—— 此时蒸馏回退既有的
// jieba/ONNX 路。**不因为模型不可用而让蒸馏停摆**：那条路虽然实测产出 0 条，
// 但它至少不会让对话记忆丢失。
func initDistillSplitter(cfgReg *config.ConfigRegistry) pipeline.RecordSplitter {
if cfgReg == nil {
return nil
}
providerName := cfgReg.GetString("core.memory.distill.generation.provider", "")
if providerName == "" {
return nil
}
opts := map[string]string{}
const optPrefix = "core.memory.distill.generation.options."
for _, key := range cfgReg.List(optPrefix) {
opts[strings.TrimPrefix(key, optPrefix)] = cfgReg.GetString(key, "")
}
provider, err := generation.Open(providerName, generation.Config{Options: opts})
if err != nil {
log.Printf("[homed] warning: 蒸馏生成 provider %q 打开失败: %v（蒸馏回退 jieba 路；已注册: %s）",
providerName, err, strings.Join(generation.Names(), ", "))
return nil
}
if !provider.Info().SupportsJSONSchema {
// 拆分器的零幻觉完全依赖 schema 约束。不支持 schema 的 provider
// 会拿到自由文本，解析必炸 —— 与其让它运行时反复失败，不如现在就拒。
log.Printf("[homed] warning: 蒸馏生成 provider %q 不支持 JSON Schema，拆分不可靠（蒸馏回退 jieba 路）",
providerName)
provider.Close()
return nil
}
log.Printf("[homed] distill generation active: provider=%s model=%s",
providerName, provider.Info().Model)
return distill.NewExtractor(provider, nil)
}
func init() { kernelmod.Register(Module{}) }

71
internal/kernelmod/memory/nilcheck_test.go Normal file
View File

@ -0,0 +1,71 @@
package memory
// "nil 加读取前检查" 的判据（用户指定的做法）。
//
// ## 为什么需要判据守它
//
// `KernelState` 的字段是**类型化的**（用户设计），好处是拼错/取错类型是
// 编译错误。但**跨模块的"未就绪"仍表现为 nil** —— 而 nil 解引用会
// **panic**，栈信息指向无关处（如 `strings.Split`），排查成本高。
//
// 用户明确要求："结构体成员初始置 nil 加**读取前检查**"。
// 本判据确保每个模块对**不由依赖图保证**的字段（Group 0 产物）做检查。
//
// ★ 为什么要判据而不是靠自觉：`ks.CfgReg` 是 Group 0 的产物，
// **无法通过 Requires 声明**（Group 0 不是调度模块）⇒ 依赖图保证不了它。
// 这正是最容易忘、忘了就 panic 的地方。
import (
"path/filepath"
"strings"
"testing"
internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
)
// ★★★ 判据：**CfgReg 为 nil 时给可操作错误，而不是 panic**。
func TestMemoryModuleRejectsNilCfgReg(t *testing.T) {
dir := t.TempDir()
ks := &kernelboot.KernelState{DataDir: dir} // CfgReg 故意为 nil
defer func() {
if r := recover(); r != nil {
t.Fatalf("★ CfgReg 为 nil 时 panic 了（应返回可操作错误）: %v\n"+
" 用户要求的是「nil 加读取前检查」，panic 的栈信息指向无关处", r)
}
}()
err := (Module{}).Init(ks)
if err == nil {
t.Fatal("★ CfgReg 为 nil 却成功返回 —— 后面会在读配置时 panic")
}
// 错误必须点出**是哪个字段**以及**该做什么**
msg := err.Error()
if !strings.Contains(msg, "CfgReg") {
t.Errorf("错误应点名字段 CfgReg（便于定位）: %v", err)
}
if !strings.Contains(msg, "Group 0") {
t.Errorf("错误应指出根因（Group 0 必须先跑）: %v", err)
}
}
// ★★★ 判据：**DataDir 为空时也拒绝**（同类检查）。
func TestMemoryModuleRejectsEmptyDataDir(t *testing.T) {
dir := t.TempDir()
reg := newTestReg(t, dir)
ks := &kernelboot.KernelState{CfgReg: reg} // DataDir 空
err := (Module{}).Init(ks)
if err == nil {
t.Fatal("★ DataDir 为空却成功返回")
}
if !strings.Contains(err.Error(), "DataDir") {
t.Errorf("错误应点名字段 DataDir: %v", err)
}
}
func newTestReg(t *testing.T, dir string) *internalConfig.ConfigRegistry {
t.Helper()
return internalConfig.NewConfigRegistry(filepath.Join(dir, "config.db"))
}

284
internal/kernelmod/migration/mod.go Normal file
View File

@ -0,0 +1,284 @@
// Package migration 提供**数据目录迁移**的内核能力（伪关机 → 迁移 → 唤醒）。
//
// ## 它提供什么
//
// 两个工具（暴露给模型/WebUI）：
//
// migrate_data_preflight → 只读体检：报告能不能迁、要迁多少、有哪些风险
// migrate_data_plan → 生成可执行迁移脚本（伪关机窗口由脚本自己 stop 覆盖）
//
// ## ★ 为什么不提供"一键迁移"工具
//
// 迁移是**破坏性且不可逆**的（21G 数据 + 12 处 DB 改写 + 46 个文件改写），
// 而且内核跑在 systemd 沙箱里（ProtectSystem/ProtectHome）**本来就写不了
// /etc/systemd**，更没法把 /home/newqqagent 搬到别的挂载点（跨目录 rename 会失败，
// 必须 rsync 全量）。
//
// ⇒ 内核的职责是：**体检 + 生成正确的脚本 + 提供伪关机/唤醒能力**；
//
// 真正的搬数据由运维执行脚本。这样每一步都可审查、可回滚。
//
// ## 依赖声明
//
// Requires 里**故意不含** plugin-host：本模块只读 fs + 读 config，
// 伪关机能力（PluginQuiescer）由调用方在需要时注入，不硬依赖。
package migration
import (
"fmt"
"os"
"path/filepath"
"sort"
"syscall"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/systemd"
)
func init() { kernelmod.Register(Module{}) }
// Module 是数据目录迁移模块。
type Module struct{}
func (Module) Name() string { return "migration" }
// Requires 只需要配置（读 data_dir）与 kernel-io（日志）。
func (Module) Requires() []string { return []string{"config", "kernel-io"} }
func (Module) Provides() []string { return []string{"migration"} }
// MigrateReport 是体检结果。
type MigrateReport struct {
DataDir string `json:"data_dir"`
TotalBytes int64 `json:"total_bytes"`
Dirs []DirInfo `json:"dirs"`
Mounts []string `json:"mounts"` // 必须先卸载的挂载点
Risks []string `json:"risks"` // 会导致数据丢失/错误的点
DBPathKeys []string `json:"db_path_keys"` // 数据库里存绝对路径的键
SameDevice bool `json:"same_device"` // 目标与源是否同一设备（决定能否 rename）
CanRename bool `json:"can_rename"` // 同设备可直接 rename，否则必须 rsync
ScriptPath string `json:"script_path,omitempty"`
}
// DirInfo 是单目录的信息。
type DirInfo struct {
Name string `json:"name"`
Bytes int64 `json:"bytes"`
Kind string `json:"kind"` // data | runtime | optional | mount
}
func (Module) Init(ks *kernelboot.KernelState) error {
// 体检结果放在 KernelState 上，供工具/WebUI 读（可选能力，nil 安全）
ks.MigrationPreflight = func(target string) (interface{}, error) {
return Preflight(ks.DataDir, target)
}
return nil
}
// Preflight 体检：数据目录现在是什么状态、迁到 target 需要注意什么。
func Preflight(dataDir, target string) (*MigrateReport, error) {
rep := &MigrateReport{DataDir: dataDir}
// 目录分类（来自 2026-10-17 生产盘点，21G）
// data=必须迁 runtime=不迁（重启重建） optional=可丢 mount=挂载点需先卸
classify := map[string]string{
"agentfs": "mount",
"plugindev": "data",
"blocklauncher": "data",
"browser_profiles": "data",
"models": "data",
"plugins": "data",
"mcbridge": "data",
"memory": "data",
"plugin_data": "data",
"knowledge": "data",
"skills": "data",
"mcp": "data",
"nlp": "data",
"adapters": "data",
"data": "data",
"uploads": "data",
"device_media": "data",
"webui_files": "data",
"changesets": "data",
"heartbeat": "runtime",
"log": "optional",
"backups": "optional",
"memory.bak": "optional",
}
entries, err := os.ReadDir(dataDir)
if err != nil {
return nil, fmt.Errorf("读数据目录: %w", err)
}
for _, e := range entries {
name := e.Name()
if !e.IsDir() {
continue
}
info := DirInfo{Name: name, Kind: classify[name]}
if info.Kind == "" {
info.Kind = "data" // 未知目录默认**必须迁**（宁可多迁，不可漏迁）
}
info.Bytes = dirSize(filepath.Join(dataDir, name))
rep.Dirs = append(rep.Dirs, info)
rep.TotalBytes += info.Bytes
}
sort.Slice(rep.Dirs, func(i, j int) bool { return rep.Dirs[i].Bytes > rep.Dirs[j].Bytes })
// ① 挂载点：agentfs 是 overlay（lower/upper/work），不卸就搬空壳。
//
// ★ 风险说明**无条件**报出，只有"要不要 umount"取决于实际挂载状态。
//
// 为什么分开：如果只在挂载时才提风险，那"现在没挂、迁移脚本跑起来时
// 服务又把它挂上了"这种时序就完全没提示 —— 而 agentfs 恰恰是内核
// 启动时才挂的。运维在**停机状态**做体检会看不到这条警示，
// 但迁移脚本里的 stop 又会把它挂回来（见脚本的 umount 步骤）。
// 判据 TestPreflightReportsKnownRisks 就是为了钉住这条。
if _, err := os.Stat(filepath.Join(dataDir, "agentfs")); err == nil {
merged := filepath.Join(dataDir, "agentfs", "merged")
if isMountpoint(merged) {
rep.Mounts = append(rep.Mounts, merged)
}
rep.Risks = append(rep.Risks,
"agentfs/merged 是 overlay 挂载点（lower/upper/work 三段）：不先 umount 会搬走'空壳'，"+
"真正内容仍挂在旧路径 ⇒ 新目录 agentfs 不可用。"+
"注意：内核启动时才挂它，所以**停机体检看不到挂载**也仍要卸")
}
// ② 数据库绝对路径：不改会"看起来记忆全丢"（内核按旧路径找不到就重建空库，且不报错）
rep.DBPathKeys = []string{
"core.daemon.data_dir", "core.plugin.dir", "core.memory.graph",
"core.memory.text", "core.memory.documents", "core.knowledge.path",
"core.log.path", "core.memory.multimodal_space.options.model_dir",
}
rep.Risks = append(rep.Risks,
fmt.Sprintf("数据库有 %d 个键存绝对路径；不改写会导致重启后按旧路径找数据，"+
"找不到就**静默重建空库**（看起来像记忆全丢）", len(rep.DBPathKeys)),
"plugin_data 下实测有 46 个文件写死了绝对路径（典型：commondev 的 git 镜像/workdir）",
"security.key 不迁 ⇒ 所有加密配置解不开（敏感信息全部失效）",
)
// ③ 是否同设备：决定 rename（瞬时）还是 rsync（几分钟）
if target != "" {
if src, err := os.Stat(dataDir); err == nil {
if dst, err := os.Stat(filepath.Dir(target)); err == nil {
a := src.Sys().(*syscall.Stat_t).Dev
b := dst.Sys().(*syscall.Stat_t).Dev
rep.SameDevice = a == b
rep.CanRename = rep.SameDevice
if !rep.SameDevice {
rep.Risks = append(rep.Risks,
"目标不在同一设备 ⇒ 不能用 rename，必须 rsync 全量拷贝（耗时随数据量增长）")
}
}
}
}
// ④ 当前 systemd 权威 vs DB 权威是否一致（两个权威不等价）
// 运行时权威 = -data（本模块的 dataDir）；配置权威 = DB core.daemon.data_dir
if st, err := systemd.Check(dataDir, dataDir); err == nil {
if st.RuntimeDataDir != "" && st.ConfigDataDir != "" && st.RuntimeDataDir != st.ConfigDataDir {
rep.Risks = append(rep.Risks,
fmt.Sprintf("★ 数据目录有**两个权威且不一致**：-data=%s（管 memory/graph.db + 插件 DataDir）"+
" vs DB core.daemon.data_dir=%s（管 memory/text、knowledge、nlp 等 6 个模块）⇒ 数据会分裂",
st.RuntimeDataDir, st.ConfigDataDir))
}
}
return rep, nil
}
// dirSize 递归统计目录大小（符号链接不跟随，避免重复计算硬链接/环）。
func dirSize(root string) int64 {
var total int64
filepath.Walk(root, func(p string, info os.FileInfo, err error) error {
if err != nil || info == nil {
return nil
}
if info.Mode()&os.ModeSymlink != 0 {
return nil
}
if !info.IsDir() {
total += info.Size()
}
return nil
})
return total
}
// isMountpoint 判断路径是否为挂载点（读 /proc/mounts，不依赖外部命令）。
func isMountpoint(p string) bool {
data, err := os.ReadFile("/proc/mounts")
if err != nil {
return false
}
clean := filepath.Clean(p)
for _, line := range splitLines(string(data)) {
f := splitFields(line)
if len(f) >= 2 && unescapeMount(f[1]) == clean {
return true
}
}
return false
}
func splitLines(s string) []string {
var out []string
start := 0
for i := 0; i < len(s); i++ {
if s[i] == '\n' {
out = append(out, s[start:i])
start = i + 1
}
}
if start < len(s) {
out = append(out, s[start:])
}
return out
}
func splitFields(s string) []string {
var out []string
i := 0
for i < len(s) {
for i < len(s) && s[i] == ' ' {
i++
}
j := i
for j < len(s) && s[j] != ' ' {
j++
}
if j > i {
out = append(out, s[i:j])
}
i = j
}
return out
}
// unescapeMount 还原 /proc/mounts 里的八进制转义（空格写作 \040）。
func unescapeMount(s string) string {
out := make([]byte, 0, len(s))
for i := 0; i < len(s); i++ {
if s[i] == '\\' && i+3 < len(s) {
v := 0
ok := true
for k := 1; k <= 3; k++ {
c := s[i+k]
if c < '0' || c > '7' {
ok = false
break
}
v = v*8 + int(c-'0')
}
if ok {
out = append(out, byte(v))
i += 3
continue
}
}
out = append(out, s[i])
}
return string(out)
}

171
internal/kernelmod/migration/mod_test.go Normal file
View File

@ -0,0 +1,171 @@
package migration
// 数据目录迁移体检的判据。
//
// ## 为什么要这些判据
//
// 迁移是**破坏性**操作。体检是唯一能让运维在动手前看到"会丢什么"的东西，
// 所以它漏报的后果是**数据丢失**（而不是一个报错）。
//
// 三个必须守住的点（都来自 2026-10-17 生产实测）：
// 1. overlay 挂载点必须被识别（不识别 ⇒ 搬走空壳）
// 2. 未知目录默认**必须迁**（宁可多迁，不可漏迁）
// 3. 同设备/跨设备必须判对（跨设备不能 rename，必须 rsync）
import (
"os"
"path/filepath"
"testing"
)
// ★★★ 判据：未知目录默认 data（必须迁），不能被当成"可丢"。
func TestPreflightDefaultsUnknownDirsToData(t *testing.T) {
dir := t.TempDir()
// 造一个体检表里没有的目录
mustMkdir(t, filepath.Join(dir, "some_new_thing"))
os.WriteFile(filepath.Join(dir, "some_new_thing", "f"), make([]byte, 100), 0o644)
rep, err := Preflight(dir, "")
if err != nil {
t.Fatal(err)
}
found := false
for _, d := range rep.Dirs {
if d.Name == "some_new_thing" {
found = true
if d.Kind != "data" {
t.Fatalf("★ 未知目录被归为 %q（应为 data）—— 漏迁 = 丢数据", d.Kind)
}
}
}
if !found {
t.Fatal("体检未列出目录")
}
}
// ★★★ 判据：heartbeat 归 runtime（不迁），log/backups/memory.bak 归 optional。
func TestPreflightClassifiesRuntimeAndOptional(t *testing.T) {
dir := t.TempDir()
for _, n := range []string{"heartbeat", "log", "backups", "memory.bak", "memory"} {
mustMkdir(t, filepath.Join(dir, n))
}
rep, err := Preflight(dir, "")
if err != nil {
t.Fatal(err)
}
want := map[string]string{
"heartbeat": "runtime", "log": "optional", "backups": "optional",
"memory.bak": "optional", "memory": "data",
}
got := map[string]string{}
for _, d := range rep.Dirs {
got[d.Name] = d.Kind
}
for n, w := range want {
if got[n] != w {
t.Fatalf("★ %s 分类为 %q，应为 %q", n, got[n], w)
}
}
}
// ★★★ 判据：overlay 挂载点必须被识别（不识别 = 搬走空壳）。
//
// 用真实的 /proc/mounts 判断：若本机恰好有 agentfs/merged 挂载则验证识别，
// 否则验证"没挂载时不给假警告"。
func TestPreflightDetectsOverlayMount(t *testing.T) {
if !isMountpoint("/proc") {
t.Fatal("isMountpoint 连 /proc 都识别不出 ⇒ /proc/mounts 解析坏了")
}
dir := t.TempDir()
mustMkdir(t, filepath.Join(dir, "agentfs", "merged"))
rep, err := Preflight(dir, "")
if err != nil {
t.Fatal(err)
}
// 临时目录里 agentfs/merged 不是真挂载点 ⇒ 不应报进 Mounts
for _, m := range rep.Mounts {
if m == filepath.Join(dir, "agentfs", "merged") {
t.Fatal("★ 非挂载点被误报为挂载点（会导致迁移脚本 umount 报错）")
}
}
}
// ★★★ 判据：体检必须报出"数据库绝对路径"与"security.key"两类风险。
//
// 这四条风险是生产实测得到的；少报任何一条，运维都会踩坑。
func TestPreflightReportsKnownRisks(t *testing.T) {
dir := t.TempDir()
mustMkdir(t, filepath.Join(dir, "memory"))
// agentfs 必须存在，overlay 风险才会计入（风险是关于 agentfs 的）
mustMkdir(t, filepath.Join(dir, "agentfs", "merged"))
rep, err := Preflight(dir, "")
if err != nil {
t.Fatal(err)
}
needles := []string{"overlay", "绝对路径", "security.key"}
joined := ""
for _, r := range rep.Risks {
joined += r + "\n"
}
for _, n := range needles {
if !contains(joined, n) {
t.Fatalf("★ 体检未报出风险 %q；实际风险: %v", n, rep.Risks)
}
}
if len(rep.DBPathKeys) != 8 {
t.Fatalf("★ DB 绝对路径键应为 8 个，实际 %d", len(rep.DBPathKeys))
}
}
// ★★★ 判据：同设备 → CanRename=true；跨设备 → false 且报风险。
func TestPreflightDeviceDetection(t *testing.T) {
dir := t.TempDir()
mustMkdir(t, filepath.Join(dir, "memory"))
// 同设备：目标父目录就是 dir 自己
rep, err := Preflight(dir, filepath.Join(dir, "target"))
if err != nil {
t.Fatal(err)
}
if !rep.SameDevice || !rep.CanRename {
t.Fatalf("★ 同设备未被识别：same=%v canRename=%v", rep.SameDevice, rep.CanRename)
}
// 跨设备：/dev/shm 通常 tmpfs，与 t.TempDir() 不同设备
if st, err := os.Stat("/dev/shm"); err == nil && st.IsDir() {
rep2, err := Preflight(dir, "/dev/shm/xxagent")
if err != nil {
t.Fatal(err)
}
if rep2.SameDevice {
t.Skip("/dev/shm 与临时目录同设备，跳过跨设备分支")
}
if rep2.CanRename {
t.Fatal("★ 跨设备被判为可 rename ⇒ 迁移会失败")
}
found := false
for _, r := range rep2.Risks {
if contains(r, "同设备") || contains(r, "rename") {
found = true
}
}
if !found {
t.Fatal("★ 跨设备未报风险")
}
}
}
func mustMkdir(t *testing.T, p string) {
t.Helper()
if err := os.MkdirAll(p, 0o755); err != nil {
t.Fatal(err)
}
}
func contains(s, sub string) bool {
for i := 0; i+len(sub) <= len(s); i++ {
if s[i:i+len(sub)] == sub {
return true
}
}
return false
}

70
internal/kernelmod/multimodal/mod.go Normal file
View File

@ -0,0 +1,70 @@
// Package multimodal 是 multimodal 模块：多模态向量空间。
//
// 依赖 config：从配置读"用哪个 provider"。
package multimodal
import (
"log"
"strings"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/memory/vector"
"github.com/JianFeeeee/HomeAgent/pkg/embedding"
)
// Module 提供多模态向量空间。
type Module struct{}
func (Module) Name() string { return "multimodal" }
func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
func (Module) Provides() []string { return []string{kernelmod.FacMultimodal} }
func (Module) Init(ks *kernelboot.KernelState) error {
cfgReg := ks.CfgReg
var multimodalSpace vector.MultimodalEmbedder
// 这两个值只用于状态报告（healthcheck_kernel 的 onnx 段）：
// 「配了哪个 provider」与「为什么没启用」，避免只能看到 false 却不知原因。
var mmProviderName, mmErr string
var closeAdapted func()
if mmProvider := cfgReg.GetString("core.memory.multimodal_space.provider", ""); mmProvider != "" {
mmProviderName = mmProvider
opts := map[string]string{}
const optPrefix = "core.memory.multimodal_space.options."
for _, key := range cfgReg.List(optPrefix) {
opts[strings.TrimPrefix(key, optPrefix)] = cfgReg.GetString(key, "")
}
provider, err := embedding.Open(mmProvider, embedding.Config{Options: opts})
if err != nil {
mmErr = err.Error()
log.Printf("[homed] warning: 多模态向量 provider %q 打开失败: %v（多模态向量检索已禁用；已注册: %s）",
mmProvider, err, strings.Join(embedding.Names(), ", "))
} else if adapted, err := vector.AdaptProvider(provider); err != nil {
provider.Close()
mmErr = err.Error()
log.Printf("[homed] warning: 多模态向量 provider %q 元数据不合法: %v（多模态向量检索已禁用）", mmProvider, err)
} else {
multimodalSpace = adapted
closeAdapted = provider.Close
info := provider.Info()
// 指纹可能很长（模型文件哈希），日志里只取前 12 个字符便于对照。
shortFP := info.Fingerprint
if len(shortFP) > 12 {
shortFP = shortFP[:12]
}
log.Printf("[homed] multimodal space active: provider=%s dim=%d fp=%s modalities=%v",
mmProvider, info.Dimension, shortFP, info.Modalities)
}
}
ks.MultimodalSpace = multimodalSpace
ks.MultimodalProviderName = mmProviderName
ks.MultimodalErr = mmErr
if closeAdapted != nil {
ks.AddCloser(closeAdapted)
}
return nil
}
func init() { kernelmod.Register(Module{}) }

47
internal/kernelmod/onnx/mod.go Normal file
View File

@ -0,0 +1,47 @@
// Package onnx 是 onnx-parser 模块：依存句法分析器（失败退回规则引擎）。
//
// ## ★ 它为什么是独立模块
//
// 它写的是**包级单例** `nlp.defaultParser`（internal/nlp/parser.go:15），
// 而该单例由**运行期**读取（`nlp.NewExtractor(nil)` 构造时快照它，
// 由蒸馏路径 `extractKeyTriples` 调用）。
//
// 这正是设计 §2.8.2 说的"签名看不到的隐藏依赖"：没有参数传递，
// 而是**包级变量 + 运行期读**。
//
// ⇒ 独立成模块，让 text-memory 能**显式声明**对它的依赖
// （见 kernelmod/textmem 的说明）。这样"碰巧安全"变成"结构保证"。
package onnx
import (
"log"
"path/filepath"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/nlp"
)
// Module 初始化依存句法分析器。
type Module struct{}
func (Module) Name() string { return "onnx-parser" }
func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
func (Module) Provides() []string { return []string{kernelmod.FacONNX} }
func (Module) Init(ks *kernelboot.KernelState) error {
modelPath := ks.CfgReg.GetString("core.agent.onnx_model_path", "")
onnxParser, err := nlp.NewONNXParser(nlp.ONNXConfig{
ModelPath: modelPath,
DataDir: filepath.Join(ks.Cfg.Daemon.DataDir, "nlp"),
})
if err != nil {
log.Printf("[homed] warn: ONNX parser init: %v, using fallback", err)
return nil
}
nlp.SetDefaultParser(onnxParser)
log.Printf("[homed] dep parser initialized (model: %s)", modelPath)
return nil
}
func init() { kernelmod.Register(Module{}) }

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() }

97
internal/kernelmod/stagehost/mod.go Normal file
View File

@ -0,0 +1,97 @@
// Package stagehost 是 stage-host 模块：阶段管道（StageHost）+ 插件注册表 + SDK 接线。
//
// ## 依赖
//
// 收 iom/evBus/mem.db/textMem/docStore/knowledge/providerMgr
// ⇒ 声明 kernel-io / memory / textmem / docmem / knowledge / llm。
//
// ★ 顺序上它在 llm 之后（providerMgr 是它的参数）—— 这不是"刻意安排"，
// 而是签名直接推出来的。
package stagehost
import (
"log"
"strings"
"github.com/JianFeeeee/HomeAgent/internal/config"
agentCore "github.com/JianFeeeee/HomeAgent/internal/agent/core"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/plugin"
cli "github.com/JianFeeeee/HomeAgent/internal/plugins/cli"
webui "github.com/JianFeeeee/HomeAgent/internal/plugins/webui"
"github.com/JianFeeeee/HomeAgent/internal/sdk"
)
// Module 提供阶段管道与插件注册表。
type Module struct{}
func (Module) Name() string { return "stage-host" }
func (Module) Requires() []string {
return []string{kernelmod.FacKernelIO, kernelmod.FacMemory, kernelmod.FacTextMem,
kernelmod.FacDocStore, kernelmod.FacKnowledge, kernelmod.FacLLM}
}
func (Module) Provides() []string { return []string{kernelmod.FacStageHost} }
func (Module) Init(ks *kernelboot.KernelState) error {
stageHost := agentCore.NewStageHost()
pluginReg := plugin.NewRegistry()
pluginReg.SetIOManager(ks.IO)
pluginReg.SetEventBus(ks.EventBus)
pluginReg.SetMemory(ks.Memory.DB)
pluginReg.SetTextMemory(ks.TextMemory)
pluginReg.SetDocStore(ks.DocStore)
pluginReg.SetKnowledge(ks.Knowledge)
pluginReg.SetProviderManager(ks.LLMManager)
pluginReg.SetConfigRegistry(ks.CfgReg)
pluginReg.SetPluginDir(ks.Cfg.Plugin.Dir)
pluginReg.SetDataDir(ks.DataDir) // 插件 SettingsAPI.DataDir() 的数据根目录
// Wire registration callbacks: plugins' RegisterTool/RegisterStage → StageHost
pluginReg.SetToolRegistrar(func(name string, def sdk.ToolDef, handler sdk.ToolHandler) error {
log.Printf("[homed] SetToolRegistrar registering tool: %s (plugin=%s)", name, def.Plugin)
return stageHost.RegisterTool(name, def, handler)
})
pluginReg.SetStageRegistrar(func(stage sdk.Stage, handler sdk.StageHandler) {
stageHost.RegisterStage(stage, handler)
})
pluginReg.SetAPIRegistrar(func(name string) error { return nil })
pluginReg.SetToolCleaner(stageHost)
ks.StageHost = stageHost
ks.PluginRegistry = pluginReg
// ★ 这两行必须在插件 Start（loadPlugins）**之前**设置：
// CLI 插件的 unix socket 路径，与 webui 的监听地址覆盖。
//
// 归入本模块的理由：它们都是**插件读的配置**，与插件系统同生共死。
// （原先它们在 main 里紧邻 loadPlugins —— 声明式下"同模块"是等价保证。）
cli.DefaultSocket = ks.CLISocket
webui.SetListenOverride(resolveWebUIOverride(ks.CfgReg, ks.HTTPAddr))
return nil
}
// resolveWebUIOverride 解析 webui 监听地址的覆盖值，空串表示不覆盖。
//
// 优先级：CLI --webui > 核心配置 webui.listen_addr（仅当被改成非内置默认值）。
// 两者都不给时由 webui 插件自己的 settings["addr"] 决定。
//
// 为什么不写成"内核在插件加载前 Set 插件 settings['addr']"：那时
// config_webui 表还没建（表只在插件注册 def 时创建），PluginSettings.Set 的
// INSERT 会失败而错误被忽略，随后插件 Start 里 RegisterDef 才建表并写入默认
// :8080 —— 于是 CLI --webui 与 webui.listen_addr **一直是死配置**。
func resolveWebUIOverride(cfgReg *config.ConfigRegistry, httpAddr string) string {
if strings.TrimSpace(httpAddr) != "" {
return strings.TrimSpace(httpAddr)
}
// webui.listen_addr 的播种默认值就是 ":8080"；与默认值相同视为"未配置"，
// 否则会把用户在设置页里改过的插件 addr 顶掉。
if v := strings.TrimSpace(cfgReg.GetString("webui.listen_addr", ":8080")); v != "" && v != ":8080" {
return v
}
return ""
}
func init() { kernelmod.Register(Module{}) }

32
internal/kernelmod/supervisor/mod.go Normal file
View File

@ -0,0 +1,32 @@
// Package supervisor 是 supervisor 模块：代理生命周期守护。
//
// 依赖 config：`initSupervisor(cfg)` 收 cfg。
//
// ★ 全仓唯一有 `log.Fatalf` 的 init*（其余都是记日志不中断）⇒ 它**必须成功**。
package supervisor
import (
"log"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/supervisor"
)
// Module 提供代理生命周期守护。
type Module struct{}
func (Module) Name() string { return "supervisor" }
func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
func (Module) Provides() []string { return []string{kernelmod.FacSupervisor} }
func (Module) Init(ks *kernelboot.KernelState) error {
sup := supervisor.New(ks.Cfg)
if err := sup.Start(); err != nil {
log.Fatalf("start supervisor: %v", err)
}
ks.Supervisor = sup
return nil
}
func init() { kernelmod.Register(Module{}) }

61
internal/kernelmod/textmem/mod.go Normal file
View File

@ -0,0 +1,61 @@
// Package textmem 是 text-memory 模块：文本记忆。
//
// ## ★ 显式依赖 onnx-parser —— 一条**签名看不到**的依赖
//
// 候选消费管线会启动蒸馏循环，而蒸馏路径在**运行期**读
// `nlp.defaultParser`（包级单例，由 onnx 模块写）：
//
// distiller.Start() → go distillLoop() → distillOnce()
// → extractKeyTriples() → nlp.NewExtractor(nil)
// → 构造时快照 defaultParser（parser.go:60）
//
// 原 main 的顺序是**反的**（蒸馏在 226 行启动、解析器 289 行才装上），
// 目前**碰巧安全** —— `distillLoop` 用 ticker，首个 tick 要等
// `Interval = 10 分钟`，那时解析器早装好了。
//
// ★ 但"碰巧安全"不是保证：Interval 变小或解析器装配更后 ⇒ **静默降级**
// （defaultParser 为 nil ⇒ POS 模板抽不出 ⇒ 图记忆实体退化成整句复合值
// ⇒ 跨维度检索全失效，基线 0/5。该后果由 pipeline.go:60 注释记录。）
//
// ⇒ 声明出来就是**结构保证**：两者不同层，分层器保证先后。
package textmem
import (
"log"
"path/filepath"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/memory/text"
)
// Module 提供文本记忆。
type Module struct{}
func (Module) Name() string { return "text-memory" }
func (Module) Requires() []string {
// onnx-parser：见包注释（隐藏依赖，显式声明）。
return []string{kernelmod.FacConfig, kernelmod.FacMemory,
kernelmod.FacKernelIO, kernelmod.FacONNX}
}
func (Module) Provides() []string { return []string{kernelmod.FacTextMem} }
func (Module) Init(ks *kernelboot.KernelState) error {
textMem := text.New(filepath.Join(ks.Cfg.Daemon.DataDir, "memory", "text"))
if err := textMem.Start(); err != nil {
log.Printf("[homed] warning: text memory start: %v", err)
ks.TextMemory = textMem
return nil
}
log.Printf("[homed] text memory active at %s", filepath.Join(ks.Cfg.Daemon.DataDir, "memory", "text"))
ks.TextMemory = textMem
// ★ 伪关机登记（迁移数据目录用）：text memory 的 rotationLoop 会周期性写盘。
ks.AddQuiescer("textmem",
func() error { return textMem.Pause() },
func() error { return textMem.Resume() })
ks.AddCloser(textMem.Stop)
return nil
}
func init() { kernelmod.Register(Module{}) }

38
internal/kernelmod/tracker/mod.go Normal file
View File

@ -0,0 +1,38 @@
// Package tracker 是 tracker 模块：变更追踪（overlayfs）。
//
// 依赖 config + AgentWorkDir（后者由 Group 0 的 ensureDataDirs 产出）。
package tracker
import (
"log"
"time"
"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
"github.com/JianFeeeee/HomeAgent/internal/tracker"
)
// Module 提供变更追踪。
type Module struct{}
func (Module) Name() string { return "tracker" }
func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
func (Module) Provides() []string { return []string{kernelmod.FacTracker} }
func (Module) Init(ks *kernelboot.KernelState) error {
trk := tracker.NewTracker(ks.Cfg.Daemon.DataDir, ks.AgentWorkDir,
tracker.WithKeepChangesets(100),
tracker.WithMaxChangesetAge(30*24*time.Hour),
)
if err := trk.Init(); err != nil {
log.Printf("[homed] warning: tracker init: %v", err)
} else if err := trk.Start(); err != nil {
log.Printf("[homed] warning: tracker mount overlay: %v (non-fatal: no overlayfs support?)", err)
} else {
log.Printf("[homed] change tracker active at %s", trk.MergeDir())
}
ks.Tracker = trk
return nil
}
func init() { kernelmod.Register(Module{}) }