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

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

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

## 为什么

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

## 怎么改

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

## 判据

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

## 顺带修的缺陷

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

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

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

## 密钥防火墙

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

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

## 配置加密

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

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

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

## 判据

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

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

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

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

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

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

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

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

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

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

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

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

## deb 的 systemd unit 改为 guard 模式

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

## 其他

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## 修法

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

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

## 验证

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

## 顺带

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

---------

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

internal/kernelmod/agent/mod.go

@@ -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{}