jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-06 09:17:31 +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

336
internal/plugin/registry.go
View File

@ -90,13 +90,13 @@ type Registry struct {
docStore *doc.Store
// CAS 已淘汰（块自带负载，见 plan.md）。本注册表不保留媒体存储字段：
// 留着会诱导后来者再接线，走回头路。媒体字节走 sdk.Memory().MediaBytes。
ks *knowledge.Store
mgr *agentAPI.ProviderManager
cfgReg *internalConfig.ConfigRegistry
plgDir string
dataDir string // 守护进程数据目录（注入给插件 SettingsAPI.DataDir）
lua *luaVM.VM
baseKey string
ks *knowledge.Store
mgr *agentAPI.ProviderManager
cfgReg *internalConfig.ConfigRegistry
plgDir string
dataDir string // 守护进程数据目录（注入给插件 SettingsAPI.DataDir）
lua *luaVM.VM
baseKey string
regTool sdk.ToolRegistrar
regStage sdk.StageRegistrar
@ -122,6 +122,32 @@ type Registry struct {
knownDisabled map[string]bool
allowlist map[string]bool
// runtimeStopped 是**运行态**关闭门（设计 §2.6.7.3）。
//
// ## 与 knownDisabled / disabled_plugins 的区别（关键）
//
// disabled_plugins（配置） = 持久禁用："是否**允许**加载"，跨重启保留
// runtimeStopped（本字段） = 运行态关闭："这一次不想让它跑"，**不**持久
//
// ## 为什么必须是两个门而不是一个
//
// 实测缺陷：`Enable()` 会调 `cfgReg.RemoveDisabledPlugin`，
// `DisablePlugin()` 会调 `cfgReg.AddDisabledPlugin` —— 全都是
// "改运行态**顺带**改持久态"。于是：
// · agent 想临时关掉某插件 ⇒ 只能调 DisablePlugin ⇒ 顺带写了持久禁用
// ⇒ 用户发现"我只是关了一下，怎么以后开机都不自启了"
// · 想把刚才关的插件开回来 ⇒ EnablePlugin ⇒ 清了禁用标记
// ⇒ 若它本来是"不自启"的，这个动作改掉了用户设置
//
// 所以需要一条**只改运行态**的路径。清除条件也不同：
// · 持久禁用由"启用"清除（用户级决定）
// · 运行态关闭由"启动"清除（会话级决定，重启自然复位）
//
// ★ 不持久是本设计的**有意选择**：运行态关闭 = "这一次不跑"，
// 不是"以后都不跑"。若它持久，agent 关掉一个插件后就再也没法让它
// 随内核起来 —— 那正是要修的毛病。
runtimeStopped map[string]bool
// pluginHashes 记录各插件二进制(plugin.so/plugin.bin/main.lua)的 SHA256，
// 供增量重载(Reload)对比：仅重载有变更的插件，避免全量 StopAll+Load 导致重复加载。
pluginHashes map[string]string
@ -184,6 +210,7 @@ func NewRegistry() *Registry {
pluginAutoRestart: make(map[string]bool),
sdkRefs: make(map[string]*sdk.PluginSDK),
knownDisabled: make(map[string]bool),
runtimeStopped: make(map[string]bool),
pluginHashes: make(map[string]string),
pluginChannels: make(map[string]*pluginChannelSet),
}
@ -274,6 +301,9 @@ func (d *channelDevice) Execute(tool string, args map[string]interface{}) (inter
func (d *channelDevice) ChannelDef() agentIO.ChannelDef { return d.chDef }
func (r *Registry) buildSDK(name string) *sdk.PluginSDK {
// 插件自己的安装目录：rawfile 资源与可写工作目录都挂在它下面。
pluginDir := filepath.Join(r.plgDir, name)
sett := sdk.NewSettings(name, r.cfgReg)
if sd, ok := sett.(interface{ SetDataDir(string) }); ok {
// 插件专属数据目录：<data>/plugin_data/<name>，保证存在
@ -360,12 +390,19 @@ func (r *Registry) buildSDK(name string) *sdk.PluginSDK {
EventBus: r.evBus,
// 块自带负载（媒体字节在块的 Data），不再需要独立的媒体存储句柄。
// 插件名仅用于日志溯源（哪个插件写的块）。
Memory: sdk.NewGraphMemoryWithPlugin(name, r.memDB),
TextMemory: sdk.NewTextMemoryWithPlugin(name, r.textMem),
DocMemory: sdk.NewDocMemoryWithPlugin(name, r.docStore),
Knowledge: sdk.NewKnowledge(r.ks),
LLM: sdk.NewLLM(r.mgr, r.cfgReg, r.lua, r.baseKey),
Settings: sett,
Memory: sdk.NewGraphMemoryWithPlugin(name, r.memDB),
TextMemory: sdk.NewTextMemoryWithPlugin(name, r.textMem),
DocMemory: sdk.NewDocMemoryWithPlugin(name, r.docStore),
Knowledge: sdk.NewKnowledge(r.ks),
LLM: sdk.NewLLM(r.mgr, r.cfgReg, r.lua, r.baseKey),
Settings: sett,
// ★ 变量库：桥接到进程级 security.Global()（**不另建存储**）。
// 内核未启用安全模块时它 Available()==false（不是 nil）。
Secrets: sdk.NewSecretsAPI(),
// ★ 随包资源：读 <插件目录>/rawfile/，可写目录 <插件目录>/work/。
// 内置插件（无独立目录）拿到的路径不存在，Read 会明确报错 ——
// 那是对的：它们本来就没有随包资源。
RawFiles: sdk.NewRawFilesAPI(pluginDir),
RegTool: regTool,
RegStage: regStage,
RegAPI: regAPI,
@ -507,6 +544,17 @@ func (r *Registry) loadOne(plgDir, name string) bool {
r.mu.Unlock()
return false
}
// ② 运行态关闭门（设计 §2.6.7.3）。
//
// 与上面的持久禁用门**分开**：持久禁用由"启用"清除，运行态关闭由
// "启动"清除。复用一个门就会让"临时关一下"变成"以后都不自启"。
//
// 注意这一条也挡住 loadPlugins 的启动扫描 —— 若插件在启动前就被
// 运行态关闭（理论上不会，但保持语义一致），它不该被拉起。
if r.isRuntimeStopped(name) {
log.Printf("[plugin] %s 处于运行态关闭（runtime stop），跳过加载", name)
return false
}
// 1) 查找工厂（init 自注册或 RegisterNative）
r.mu.RLock()
@ -841,6 +889,115 @@ func (r *Registry) Reload(dir string) (string, error) {
return fmt.Sprintf("reloaded %d plugins, %d unchanged", changed, remaining), nil
}
// LoadOneDir 加载**单个**插件目录（供按 syncbus 分阶段启动的调度器使用）。
//
// 与 Load(dir) 的区别：Load 扫描整个目录并加载所有插件；
// 本方法只加载指定的那一个，让调用方（调度器）能控制**时机**。
//
// 复用 loadOne 的全部语义（禁用门、运行态门、工厂查找、握手超时……），
// **不绕过**任何既有机制 —— 分阶段启动不该是本设计的特权路径。
func (r *Registry) LoadOneDir(plgDir, name string) error {
if !r.allowlistAllows(name) {
return fmt.Errorf("plugin %s 不在本启动模式的允许清单内", name)
}
if r.loadOne(plgDir, name) {
return nil
}
return fmt.Errorf("加载插件 %s 失败（见内核日志）", name)
}
// LoadSkipping 加载目录下**除 skip 之外**的全部插件（供分阶段启动的"兜底"路径）。
//
// 语义与 Load(dir) 一致，只是把交给调度器的插件排除掉（它们由调度器按
// 依赖就绪情况拉起），避免"调度器还没轮到、Load 先把它们全拉了"。
//
// ★ 这个排除是分阶段启动能生效的关键：若不做，Load 的全量扫描会把
// 所有插件（含声明了依赖的）立刻加载，调度器就无事可做了。
func (r *Registry) LoadSkipping(dir string, skip map[string]bool) error {
if dir == "" {
dir = r.plgDir
}
os.MkdirAll(dir, 0755)
loaded := map[string]bool{}
entries, err := os.ReadDir(dir)
if err != nil {
if os.IsNotExist(err) {
os.MkdirAll(dir, 0755)
return nil
}
return err
}
for _, entry := range entries {
if !entry.IsDir() {
continue
}
name := entry.Name()
if skip[name] {
continue // 交给调度器按依赖就绪情况拉起
}
if !r.allowlistAllows(name) {
continue
}
if r.loadOne(filepath.Join(dir, name), name) {
loaded[name] = true
}
}
// 内置工厂（编译期注册、可能尚无目录）同样排除 skip 的那些
r.mu.RLock()
allFactories := make(map[string]NativeFactory, len(r.factories))
for name, f := range r.factories {
allFactories[name] = f
}
r.mu.RUnlock()
globalFactories.Range(func(key, val interface{}) bool {
name := key.(string)
if _, ok := allFactories[name]; !ok {
allFactories[name] = val.(NativeFactory)
}
return true
})
for name, factory := range allFactories {
if loaded[name] || skip[name] || !r.allowlistAllows(name) {
continue
}
if r.isDisabled(name) {
log.Printf("[plugin] %s is disabled, skipping", name)
r.mu.Lock()
r.knownDisabled[name] = true
r.mu.Unlock()
continue
}
plgDir := filepath.Join(dir, name)
os.MkdirAll(plgDir, 0755)
cfg := r.readConfig(plgDir)
p, err := factory(name, cfg)
if err != nil {
log.Printf("[plugin] factory %s: %v", name, err)
continue
}
if p == nil {
continue
}
plgSDK := r.buildSDK(name)
if err := p.Start(plgSDK); err != nil {
log.Printf("[plugin] start %s: %v", name, err)
continue
}
r.mu.Lock()
r.plugins[name] = p
r.pluginAutoRestart[name] = plgSDK.AutoRestart()
r.instances = append(r.instances, p)
r.mu.Unlock()
r.warnOutputOnlyChannels(name)
log.Printf("[plugin] loaded: %s", name)
loaded[name] = true
}
return nil
}
func (r *Registry) ReloadOne(name string) error {
plgDir := filepath.Join(r.plgDir, name)
@ -1034,6 +1191,13 @@ func (r *Registry) ListDisabledPlugins() []sdk.DisabledPluginInfo {
func (r *Registry) IsPluginDisabled(name string) bool { return r.isDisabled(name) }
func (r *Registry) DisablePlugin(name, by string) error {
// ★ 自锁守卫（与 StopPlugin 同一类，设计 §2.6.7.4）。
//
// 持久禁用 pluginmgr 比运行态关闭更糟：agent 从此**永远**失去插件管理能力
// （重启也不恢复）。虽然 CLI/webui 可人工解禁，但 agent 侧是死锁。
if err := r.refuseSelfLock(name, "禁用"); err != nil {
return err
}
// 插件不存在（未安装）：拒绝并返回错误，避免把不存在的插件写进 disabled_plugins。
// 判断标准：已加载 / 已注册工厂（内置）/ 插件目录存在，任一命中视为已安装。
if !r.pluginInstalled(name) {
@ -1077,6 +1241,152 @@ func (r *Registry) DisablePlugin(name, by string) error {
func (r *Registry) EnablePlugin(name string) error { return r.Enable(name) }
// isRuntimeStopped 报告插件是否处于**运行态关闭**（设计 §2.6.7.3）。
func (r *Registry) isRuntimeStopped(name string) bool {
r.mu.RLock()
defer r.mu.RUnlock()
return r.runtimeStopped[name]
}
// IsRuntimeStopped 是 isRuntimeStopped 的公开形式（工具层与判据用）。
func (r *Registry) IsRuntimeStopped(name string) bool { return r.isRuntimeStopped(name) }
// IsPluginRuntimeStopped 实现 sdk.PluginManager（命名与该接口其他方法一致）。
func (r *Registry) IsPluginRuntimeStopped(name string) bool { return r.isRuntimeStopped(name) }
// StopPlugin 是**运行态**关闭：现在停掉，但**不改任何持久状态**（设计 §2.6.7.4）。
//
// ## 与 DisablePlugin 的区别（这是本方法存在的全部理由）
//
// DisablePlugin ⇒ 停掉 + 写 disabled_plugins（**持久**）
// StopPlugin ⇒ 停掉，**不写任何配置**（运行态，重启自然复位）
//
// 用户场景："我只是想临时关掉它看现象" —— 用 DisablePlugin 会顺带把
// 开机自启也关掉，用户下次开机会发现"怎么不启动了"。
//
// ## 为何拒绝关闭"插件管理自身"
//
// pluginmgr 被关掉后，agent 就**失去了插件管理能力**，而重新启动它
// **只能靠插件管理工具** —— 鸡生蛋，自锁且无解。
// 所以这条必须在**内核层面**拦死，不能靠 agent 自觉（agent 可以犯错）。
//
// 同理拒绝 webui：它是人机界面，关掉后人就看不见了（可被外部手段恢复，
// 但仍是坏体验，故一并拦）。
func (r *Registry) StopPlugin(name string) error {
if err := r.refuseSelfLock(name, "关闭"); err != nil {
return err
}
r.mu.Lock()
p, ok := r.plugins[name]
if !ok {
r.mu.Unlock()
// 不在运行：标记运行态关闭（幂等），使后续启动不会拉起它
r.mu.Lock()
r.runtimeStopped[name] = true
r.mu.Unlock()
return fmt.Errorf("plugin %s 未在运行（已标记为运行态关闭）", name)
}
r.runStopHandlers(name)
stopErr := p.Stop()
delete(r.plugins, name)
delete(r.sdkRefs, name)
for i, inst := range r.instances {
if inst.Name() == name {
r.instances = append(r.instances[:i], r.instances[i+1:]...)
break
}
}
r.runtimeStopped[name] = true
r.mu.Unlock()
// 摸掉注册面：否则旧闭包（工具/stage/通道）指向已死实例，
// 模型仍能看到并调用它们，只能拿到 ErrProcessExited。
// 与 ReloadOne/Disable 同一处置（那里不摸的后果见 ReloadOne 注释）。
r.detachPlugin(name)
if stopErr != nil {
log.Printf("[plugin] runtime stop %s（Stop 报错）: %v", name, stopErr)
}
log.Printf("[plugin] runtime stopped: %s（不改持久状态）", name)
return nil
}
// StartPlugin 是**运行态**启动：现在拉起，**不改持久状态**（设计 §2.6.7.4）。
//
// ## 为何不清除 disabled_plugins
//
// 与 EnablePlugin 的区别：EnablePlugin 会调 RemoveDisabledPlugin
// ⇒ 若插件本来被持久禁用，这个动作把它**解禁**了（改了用户决定）。
// StartPlugin 只清运行态门，持久禁用仍然生效：
//
// · 被持久禁用的插件 ⇒ StartPlugin **拒绝**（提示先启用）
// 理由：持久禁用是用户的明确决定，绕过它加载等于违背用户意图
// · 只是运行态关闭的插件 ⇒ StartPlugin 正常拉起
//
// ## 重启后的语义
//
// runtimeStopped **不持久** ⇒ 重启后插件按 auto_start + disabled_plugins
// 正常决定。这正是"关闭 ≠ 以后都不启动"的落点。
func (r *Registry) StartPlugin(name string) error {
// 持久禁用优先：用户的明确决定不能被运行态操作绕过
if r.isDisabled(name) {
return fmt.Errorf("plugin %s 已被**持久禁用**，请先用 plugin_enable 启用（运行态启动不会解除持久禁用）", name)
}
// 清运行态门（必须在 loadOne 之前，否则会被门挡住）
r.mu.Lock()
wasStopped := r.runtimeStopped[name]
delete(r.runtimeStopped, name)
r.mu.Unlock()
// 已在运行 ⇒ 幂等成功（不重复加载）。
//
// ★ 判据必须看 **r.plugins**（真的加载了），不能看 PluginRuntime：
// 后者在"工厂已注册但插件并未加载"时也返回 ok=true（它答的是
// "这个插件**已安装**吗"，不是"**正在运行**吗"）。
// 用它会让 StartPlugin 在插件其实已停止时误返回成功 —— 实测抓到
// （TestStopThenStartRoundTrip：停止后启动，插件其实没被重新加载）。
r.mu.RLock()
_, running := r.plugins[name]
r.mu.RUnlock()
if running {
return nil
}
plgDir := filepath.Join(r.plgDir, name)
if r.loadOne(plgDir, name) {
if wasStopped {
log.Printf("[plugin] runtime started: %s（已清运行态关闭）", name)
} else {
log.Printf("[plugin] runtime started: %s", name)
}
return nil
}
// 加载失败 ⇒ 恢复运行态门，避免"启动失败但门被清了"导致状态不一致
r.mu.Lock()
if wasStopped {
r.runtimeStopped[name] = true
}
r.mu.Unlock()
return fmt.Errorf("启动插件 %s 失败（本身加载出错，或插件不存在）", name)
}
// refuseSelfLock 拦住会自锁的关闭/禁用操作（设计 §2.6.7.4）。
//
// 为何在内核层面拦而不是靠工具层校验：agent 可以犯错，
// 而这几个操作一旦执行就**无法从 agent 侧恢复**（自锁）。
// 内核拒绝是唯一可靠的位置。
func (r *Registry) refuseSelfLock(name, action string) error {
switch name {
case "pluginmgr":
return fmt.Errorf("拒绝%s pluginmgr：它是 agent 的插件管理能力本身，"+
"%s后 agent 再也无法启动任何插件（只能靠外部手段恢复）", action, action)
case "webui":
return fmt.Errorf("拒绝%s webui：它是人机界面，%s后用户看不到系统状态"+
"（如需临时停用请用 plugin_disable，或从外部恢复）", action, action)
}
return nil
}
// StopAndUnload 停止并从注册表移除插件，但保留其配置表（config_<name>）。
// 供插件更新/升级流程使用：换 so/文件不动配置，重装后配置原样生效。
// 不执行 onRemove 回调（那是删除专用语义）。目录由调用方管理。