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>
2026-11-01 06:47:29 +00:00 · 2026-10-17 19:18:24 +08:00
parent 03d87a4e21
commit a68d6a428c
266 changed files with 30185 additions and 1424 deletions
--- a/internal/config/registry.go
+++ b/internal/config/registry.go
@ -28,6 +28,16 @@ type ConfigDef struct {
 	Options     []string `json:"options,omitempty"`
 	Hidden      bool     `json:"hidden,omitempty"`
 	Category    string   `json:"category,omitempty"`
+
+	// Secret 标记该配置项为敏感值：**落盘加密且不回显**。
+	//
+	// ★ 与 Type=="password" 等价，但更显式。SDK 侧（pubsdk.ConfigDef）
+	// 一直有这个字段，只是内核这边没实现 —— 插件早就声明了意图却没有效果。
+	//
+	// 两种写法都会生效（见 isSecretKey）：
+	//   · Type: "password"            旧写法，兼容保留
+	//   · Secret: true                推荐，意图明确
+	Secret bool `json:"secret,omitempty"`
 }

 type ConfigRegistry struct {
@ -36,6 +46,12 @@ type ConfigRegistry struct {
 	dbPath      string
 	defs        map[string]*ConfigDef
 	llmSnapFile string
+
+	// secrets 是「需要加密落盘」的键集合（由 def 推导，见 isSecretKey）。
+	//
+	// 为何缓存成集合而不是每次查 def：写入是热路径，而 def 查询要拿锁；
+	// 且 secret 判定必须对**无 def 的键**也能生效（见 secretByKeyPattern）。
+	secrets map[string]bool
 }

 func NewConfigRegistry(dbPath string) *ConfigRegistry {
@ -47,7 +63,7 @@ func NewConfigRegistry(dbPath string) *ConfigRegistry {
 		panic(fmt.Sprintf("open config db: %v", err))
 	}
 	db.Exec("PRAGMA journal_mode=WAL")
-	r := &ConfigRegistry{db: db, dbPath: dbPath, defs: make(map[string]*ConfigDef)}
+	r := &ConfigRegistry{db: db, dbPath: dbPath, defs: make(map[string]*ConfigDef), secrets: make(map[string]bool)}
 	r.initCoreTable()
 	return r
 }
@ -133,11 +149,19 @@ func (r *ConfigRegistry) IsPluginDisabled(name string) bool {
 }

 func (r *ConfigRegistry) ensurePluginTable(name string) {
-	table := r.pluginTableName(name)
 	r.db.Exec(fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
 		key   TEXT PRIMARY KEY,
 		value TEXT NOT NULL
-	)`, table))
+	)`, r.pluginTableName(name)))
+}
+
+// ensurePluginTableErr 同 ensurePluginTable 但返回错误（显式加密写入需要它）。
+func (r *ConfigRegistry) ensurePluginTableErr(name string) error {
+	_, err := r.db.Exec(fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
+		key   TEXT PRIMARY KEY,
+		value TEXT NOT NULL
+	)`, r.pluginTableName(name)))
+	return err
 }

 func (r *ConfigRegistry) pluginTableName(name string) string {
@ -153,7 +177,11 @@ func (r *ConfigRegistry) pluginTableName(name string) string {
 func (r *ConfigRegistry) Register(key string, value interface{}) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
-	r.db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, key, fmt.Sprint(value))
+	stored := fmt.Sprint(value)
+	if r.isSecretKey(key) {
+		stored, _ = sealForStorage(key, stored)
+	}
+	r.db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, key, stored)
 }

 func (r *ConfigRegistry) RegisterDefault(key string, value interface{}) {
@ -164,7 +192,12 @@ func (r *ConfigRegistry) RegisterDef(def ConfigDef) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	r.defs[def.Key] = &def
-	r.db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, def.Key, def.Default)
+	// 默认值也要加密落盘（否则声明了 secret 的项一启动就是明文）。
+	stored := def.Default
+	if r.isSecretKey(def.Key) {
+		stored, _ = sealForStorage(def.Key, stored)
+	}
+	r.db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, def.Key, stored)
 }

 func (r *ConfigRegistry) GetDef(key string) *ConfigDef {
@ -306,7 +339,12 @@ func (r *ConfigRegistry) Get(key string) (interface{}, error) {
 	if err != nil {
 		return nil, err
 	}
-	return val, nil
+	// 敏感项在库里是密文 ⇒ 对调用方透明解密（读接口语义不变）。
+	if plain, oerr := openFromStorage(key, val); oerr == nil {
+		return plain, nil
+	} else {
+		return nil, oerr
+	}
 }

 func (r *ConfigRegistry) Set(key string, value interface{}) error {
@ -315,7 +353,12 @@ func (r *ConfigRegistry) Set(key string, value interface{}) error {
 	if strings.HasPrefix(key, "core.llm.") {
 		r.writeLLMSnapshotLocked()
 	}
-	_, err := r.db.Exec(`INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)`, key, fmt.Sprint(value))
+	stored := fmt.Sprint(value)
+	// ★ 敏感项在**写库前**加密：库文件里只有密文。
+	if r.isSecretKey(key) {
+		stored, _ = sealForStorage(key, stored)
+	}
+	_, err := r.db.Exec(`INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)`, key, stored)
 	if err == nil && strings.HasPrefix(key, "core.llm.sources.") {
 		rest := strings.TrimPrefix(key, "core.llm.sources.")
 		parts := strings.SplitN(rest, ".", 2)
@ -455,6 +498,9 @@ func LoadLLMSnapshot(path string) (map[string]string, error) {
 }

 // listPrefixLocked 调用方须持有锁；返回 prefix 开头的全部键值。
+//
+// ★ 返回的是**解密后**的值（调用方都是内核内部可信路径，如
+// ToConfig / LLM 快照 / guard 基线）。
 func (r *ConfigRegistry) listPrefixLocked(prefix string) map[string]string {
 	out := make(map[string]string)
 	rows, err := r.db.Query(`SELECT key, value FROM config WHERE key LIKE ? ORDER BY key`, prefix+"%")
@ -465,7 +511,12 @@ func (r *ConfigRegistry) listPrefixLocked(prefix string) map[string]string {
 	for rows.Next() {
 		var k, v string
 		if err := rows.Scan(&k, &v); err == nil {
-			out[k] = v
+			if plain, oerr := openFromStorage(k, v); oerr == nil {
+				out[k] = plain
+			} else {
+				// 解不开就不给值：宁可缺失（可诊断）也不把密文当明文交出去。
+				log.Printf("[config] listPrefix 解密 %s 失败，已跳过: %v", k, oerr)
+			}
 		}
 	}
 	return out
@ -483,7 +534,14 @@ func (r *ConfigRegistry) Dump() map[string]interface{} {
 	for rows.Next() {
 		var k, v string
 		if err := rows.Scan(&k, &v); err == nil {
-			result[k] = v
+			// ★ 返回**明文**：Dump 的调用方都是内核内部可信路径
+			//（ToConfig 重建 LLMSource、WebUI 设置页、插件读自身/他人配置）。
+			// 本需求防的是「静态文件泄漏」，不是「内部读取」。
+			if plain, oerr := openFromStorage(k, v); oerr == nil {
+				result[k] = plain
+			} else {
+				log.Printf("[config] Dump 解密 %s 失败: %v", k, oerr)
+			}
 		}
 	}
 	return result
@ -723,7 +781,7 @@ func (r *ConfigRegistry) seedDBValues(dataDir string) {
 	set("core.memory.documents", filepath.Join(dataDir, "memory", "documents"))
 	// 发行版默认启用本地向量空间。用 chineseclip（text+image、512 维、实测
 	// 稳态约 0.89GB、Apache-2.0）而不是 qwen3vl（视觉塔按需加载，峰值约 9.4GB）：
-    // 多数机器装不下后者。
+	// 多数机器装不下后者。
 	// 产物不在仓库里，用 scripts/export_chineseclip_onnx.py 生成到这个路径；
 	// 产物缺失时 homed 会打印明确错误并退回 fastText 文本路径（不静默假装启用）。
 	set("core.memory.multimodal_space.provider", "chineseclip")
@ -885,7 +943,10 @@ func (r *ConfigRegistry) GetString(key, defaultVal string) string {
 	if err != nil {
 		return defaultVal
 	}
-	return v
+	if plain, oerr := openFromStorage(key, v); oerr == nil {
+		return plain
+	}
+	return defaultVal
 }

 func (r *ConfigRegistry) GetInt(key string, defaultVal int) int {
@ -1154,7 +1215,11 @@ func (r *ConfigRegistry) SetPluginConfig(name, key string, value interface{}) er
 	defer r.mu.Unlock()
 	r.ensurePluginTable(name)
 	table := r.pluginTableName(name)
-	_, err := r.db.Exec(fmt.Sprintf(`INSERT OR REPLACE INTO %s (key, value) VALUES (?, ?)`, table), key, fmt.Sprint(value))
+	stored := fmt.Sprint(value)
+	if r.isSecretKey("plugin." + name + "." + key) {
+		stored, _ = sealForStorage("plugin."+name+"."+key, stored)
+	}
+	_, err := r.db.Exec(fmt.Sprintf(`INSERT OR REPLACE INTO %s (key, value) VALUES (?, ?)`, table), key, stored)
 	return err
 }

@ -1183,17 +1248,65 @@ func (p *PluginSettings) Get(key string) (interface{}, error) {
 	if err != nil {
 		return nil, err
 	}
-	return val, nil
+	// 敏感项透明解密
+	if plain, oerr := openFromStorage("plugin."+p.name+"."+key, val); oerr == nil {
+		return plain, nil
+	} else {
+		return nil, oerr
+	}
 }

 func (p *PluginSettings) Set(key string, value interface{}) error {
 	p.registry.mu.Lock()
 	defer p.registry.mu.Unlock()
-	_, err := p.registry.db.Exec(fmt.Sprintf(`INSERT OR REPLACE INTO %s (key, value) VALUES (?, ?)`, p.table), key, fmt.Sprint(value))
+	stored := fmt.Sprint(value)
+	// ★ 插件敏感项同样加密落盘（插件无感知：它 Set 明文，Get 也得到明文）。
+	if p.isSecretKeyLocal(key) {
+		stored, _ = sealForStorage("plugin."+p.name+"."+key, stored)
+	}
+	_, err := p.registry.db.Exec(fmt.Sprintf(`INSERT OR REPLACE INTO %s (key, value) VALUES (?, ?)`, p.table), key, stored)
 	return err
 }

-// Remove 删除插件配置中的单个键（用于插件删除时的自身配置清理）。
+// SetSecret 强制加密写入（不看键名，也不需 def）。
+//
+// ★ 为何要显式 API：键名模式无法覆盖所有情形 —— 插件可能用
+// `blob`、`payload`、`conn` 这类中性键名存凭据。显式声明意图比猜名字可靠。
+//
+// 未装配密钥时 **拒绝写入**（不静默存明文）：插件以为存了密文而
+// 实际是明文，是最危险的静默降级。空值例外（删除语义）。
+func (p *PluginSettings) SetSecret(key string, value interface{}) error {
+	stored := fmt.Sprint(value)
+	sealed := stored
+	if stored != "" {
+		var ok bool
+		sealed, ok = sealForStorage("plugin."+p.name+"."+key, stored)
+		if !ok {
+			return fmt.Errorf("config: 密钥未装配，拒绝以明文存储敏感项 %q", key)
+		}
+	}
+	p.registry.mu.Lock()
+	defer p.registry.mu.Unlock()
+	if err := p.registry.ensurePluginTableErr(p.name); err != nil {
+		return err
+	}
+	_, err := p.registry.db.Exec(
+		fmt.Sprintf(`INSERT OR REPLACE INTO %s (key, value) VALUES (?, ?)`, p.table), key, sealed)
+	return err
+}
+
+// GetSecret 读取由 SetSecret 写入的值（透明解密）。
+func (p *PluginSettings) GetSecret(key string) (string, error) {
+	p.registry.mu.RLock()
+	defer p.registry.mu.RUnlock()
+	var val string
+	err := p.registry.db.QueryRow(
+		fmt.Sprintf(`SELECT value FROM %s WHERE key = ?`, p.table), key).Scan(&val)
+	if err != nil {
+		return "", err
+	}
+	return openFromStorage("plugin."+p.name+"."+key, val)
+}
 func (p *PluginSettings) Remove(key string) error {
 	p.registry.mu.Lock()
 	defer p.registry.mu.Unlock()
@ -1226,10 +1339,18 @@ func (p *PluginSettings) RegisterDef(def ConfigDef) {
 	// 只有注册配置定义才创建插件配置表：任意 scope 的读写不得隐式建表，
 	// 避免非插件（如 SKILL 目录名）被注册成配置命名空间。
 	p.registry.ensurePluginTable(p.name)
-	p.registry.db.Exec(fmt.Sprintf(`INSERT OR IGNORE INTO %s (key, value) VALUES (?, ?)`, p.table), def.Key, def.Default)
-	qualified := "plugin." + p.name + "." + def.Key
+
+	localKey := def.Key                              // 表内用局部键
+	qualified := "plugin." + p.name + "." + localKey // defs 里用限定键
 	def.Key = qualified
-	p.registry.defs[def.Key] = &def
+	// ★ def 必须先入 defs：isSecretKey 靠它判定，而下面的默认值要加密。
+	p.registry.defs[qualified] = &def
+
+	stored := def.Default
+	if p.registry.isSecretKey(qualified) {
+		stored, _ = sealForStorage(qualified, stored)
+	}
+	p.registry.db.Exec(fmt.Sprintf(`INSERT OR IGNORE INTO %s (key, value) VALUES (?, ?)`, p.table), localKey, stored)
 }

 func (p *PluginSettings) ListDefs(prefix string) []*ConfigDef {