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/security/store_test.go

@@ -0,0 +1,443 @@
+package security
+
+// 安全模块的判据集。
+//
+// 每条判据对应设计文档里的一条硬约束（S1–S12）。
+// 纪律：**判据必须先跑通，再接内核** —— 否则接线出错时无法区分
+// 「安全模块坏了」还是「接线错了」。
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func testKey() ([]byte, error) {
+	return []byte("0123456789abcdef0123456789abcdef"), nil
+}
+
+func newTestStore(t *testing.T, enabled bool) *Store {
+	t.Helper()
+	dir := t.TempDir()
+	s := New(Options{
+		Path:    filepath.Join(dir, "variables.json"),
+		KeyFn:   testKey,
+		Enabled: enabled,
+	})
+	if err := s.Load(); err != nil {
+		t.Fatal(err)
+	}
+	return s
+}
+
+// const testToken 是一个形状合法的 GitHub token（用于触发模式库）。
+const testToken = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+// ★★ S3 + S11：**同明文自动合并到同一别名**（哈希键的天然性质）。
+func TestSameSecretMergesToSameAlias(t *testing.T) {
+	s := newTestStore(t, true)
+
+	a1, err := s.Alias(testToken)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a2, _ := s.Alias(testToken)
+	if a1 != a2 {
+		t.Fatalf("同一明文必须得到同一别名，实际 %s vs %s", a1, a2)
+	}
+	// 别名形态：sec_ + 16 hex = 20 字符
+	if !strings.HasPrefix(a1, AliasPrefix) || len(a1) != 20 {
+		t.Errorf("别名形态异常: %q (len=%d)", a1, len(a1))
+	}
+	// 不同明文 ⇒ 不同别名
+	other, _ := s.Alias("ghp_ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ")
+	if other == a1 {
+		t.Error("不同明文不应合并")
+	}
+}
+
+// ★★ S3：别名必须**依赖主密钥**（即 HMAC，不是裸哈希）。
+//
+// 裸哈希可被字典枚举（实测 hunter2 当场命中），而别名会进上下文/日志/记忆。
+func TestAliasDependsOnMasterKey(t *testing.T) {
+	s1 := New(Options{Path: filepath.Join(t.TempDir(), "a.json"), KeyFn: testKey, Enabled: true})
+	other := func() ([]byte, error) { return []byte("ffffffffffffffffffffffffffffffff"), nil }
+	s2 := New(Options{Path: filepath.Join(t.TempDir(), "b.json"), KeyFn: other, Enabled: true})
+
+	a1, _ := s1.Alias("same-plain")
+	a2, _ := s2.Alias("same-plain")
+	if a1 == a2 {
+		t.Fatal("不同主密钥必须产出不同别名（否则说明用了裸哈希）")
+	}
+}
+
+// ★ 判据：裸哈希可被字典枚举 —— 用真实数据证明 HMAC 的必要性。
+//
+// 这条不是测代码，而是**固化设计依据**：若有天有人把 HMAC 换成裸 SHA256，
+// 这条判据会连同其注释一起提醒他为什么不行。
+func TestBareHashIsEnumerable(t *testing.T) {
+	// 攻击者视角：拿到别名（裸哈希前 16 hex），拿常见弱口令字典去试
+	weak := "hunter2"
+	sum := sha256Hex16(weak)
+	// 字典命中（一行代码就够）
+	hit := false
+	for _, g := range []string{"password123", "admin", "letmein", "hunter2", "secret"} {
+		if sha256Hex16(g) == sum {
+			hit = true
+		}
+	}
+	if !hit {
+		t.Fatal("本判据的前提失效（裸哈希应可被字典命中）")
+	}
+	// 而 HMAC 版本：没有 key 无法枚举
+	s := newTestStore(t, true)
+	a, _ := s.Alias(weak)
+	if a == AliasPrefix+sum {
+		t.Fatal("别名用了裸哈希 —— 会泄露 secret 内容")
+	}
+	t.Logf("裸哈希（危险）: %s%s ；HMAC（当前实现）: %s", AliasPrefix, sum, a)
+}
+
+// ★★ S1 + 插件无感知：拦截把明文换成别名，稍后能用别名换回（回填）。
+func TestReplaceThenFill(t *testing.T) {
+	s := newTestStore(t, true)
+
+	text := "我的 token 是 " + testToken + " 请使用"
+	out, evts := s.Replace(text, "input", Patterns)
+
+	if strings.Contains(out, testToken) {
+		t.Fatalf("明文未被替换: %s", out)
+	}
+	if !strings.Contains(out, "安全模块自动拦截") {
+		t.Errorf("缺少拦截提示: %s", out)
+	}
+	if len(evts) != 1 {
+		t.Fatalf("应恰好 1 条拦截事件，实际 %d", len(evts))
+	}
+	alias := evts[0].Alias
+	if !strings.Contains(out, "@{"+alias+"}") {
+		t.Errorf("提示里应含 @{%s}: %s", alias, out)
+	}
+
+	// ★ 回填：把别名换回明文（这是插件能用密钥的唯一通道）
+	back, n, used := s.Fill("Authorization: token @{" + alias + "}")
+	if n != 1 {
+		t.Fatalf("应回填 1 处，实际 %d", n)
+	}
+	if !strings.Contains(back, testToken) {
+		t.Fatalf("回填未生效: %s", back)
+	}
+	if len(used) != 1 || used[0] != alias {
+		t.Errorf("应报告用到的别名: %v", used)
+	}
+}
+
+// ★★ S4：**不可误伤** —— 正常文本绝不能被替换。
+//
+// 误报比漏报严重得多：它会把正常内容换掉、把任务搞坏，且归因极难。
+func TestNoFalsePositives(t *testing.T) {
+	s := newTestStore(t, true)
+	benign := []string{
+		"请修复这个 bug，提交到 feat/login 分支",
+		"git commit -m 'add feature'",
+		"https://github.com/JianFeeeee/HomeAgent/pull/42",
+		"这个函数返回 404 或者 500",
+		"hex 颜色 #4f46e5 很好看",
+		// ★ 关键：40 位 git SHA-1 不得被误伤（否则 agent 拿不到 commit id）
+		"commit 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b",
+		"版本号 v1.2.3",
+		"文件 /home/program/TrueAgent/docs/zh/kernel-secret-firewall-design.md",
+		"时间戳 2026-10-14T17:27:16+08:00",
+		"UUID 550e8400-e29b-41d4-a716-446655440000",
+		"讨论一下 secret 管理和 token 轮换的策略", // 含关键词但不是赋值形态
+		"password 字段的长度校验有问题",         // 同上
+	}
+	for _, s0 := range benign {
+		out, evts := s.Replace(s0, "input", Patterns)
+		if len(evts) > 0 {
+			t.Errorf("误伤正常文本 %q → %v", s0, evts)
+		}
+		if out != s0 {
+			t.Errorf("未命中却改动了文本: %q → %q", s0, out)
+		}
+	}
+}
+
+// 各类凭据形状都要能识别（覆盖面）。
+func TestRecognizesCommonShapes(t *testing.T) {
+	s := newTestStore(t, true)
+	cases := []struct{ name, text string }{
+		{"github", testToken},
+		{"gitlab", "glpat-FAKE-TEST-TOKEN-NOT-REAL"},
+		{"openai", "sk-FAKE-TEST-KEY-NOT-REAL-0000000"},
+		{"anthropic", "sk-ant-FAKE-TEST-KEY-NOT-REAL-00"},
+		{"aws", "AKIA0000FAKE0000TEST"},
+		{"slack", "xoxb-FAKE-TEST-TOKEN-NOT-REAL"},
+		{"assignment", `api_key = "FAKE-TEST-ASSIGNED-VALUE-000"`},
+		{"bearer", "Authorization: Bearer FAKE-TEST-BEARER-TOKEN-NOT-REAL"},
+	}
+	for _, c := range cases {
+		_, evts := s.Replace(c.text, "input", Patterns)
+		if len(evts) == 0 {
+			t.Errorf("%s 形状未被识别: %q", c.name, c.text)
+		}
+	}
+}
+
+// ★ 判据：赋值形态保留键名（否则人看不懂发生了什么）。
+func TestAssignmentKeepsKeyName(t *testing.T) {
+	s := newTestStore(t, true)
+	out, evts := s.Replace(`api_key = "FAKE-TEST-ASSIGNED-VALUE-000"`, "input", Patterns)
+	if len(evts) == 0 {
+		t.Fatal("未命中")
+	}
+	if !strings.Contains(out, "api_key") {
+		t.Errorf("应保留键名: %s", out)
+	}
+}
+
+// ★ S1：**不提供取回明文的接口**（看值只能靠回填）。
+//
+// 这条是防回归：若有人加了 Get/Reveal 之类的方法，判据通过编译期就能发现。
+func TestNoPlaintextReadAPI(t *testing.T) {
+	// 语义判据：List() 只给元信息；明文只能经 Fill 出现在"待发送的文本"里
+	s := newTestStore(t, true)
+	alias, err := s.Submit(testToken, "测试")
+	if err != nil {
+		t.Fatal(err)
+	}
+	infos := s.List()
+	if len(infos) != 1 {
+		t.Fatalf("应有 1 条记录，实际 %d", len(infos))
+	}
+	b, _ := json.Marshal(infos)
+	if strings.Contains(string(b), testToken) {
+		t.Fatalf("List 泄露了明文: %s", b)
+	}
+	if !strings.Contains(string(b), alias) {
+		t.Error("List 应给出别名")
+	}
+}
+
+// ★★ 落盘：明文绝不落盘，且文件必须 0600。
+func TestPersistsCiphertextOnlyWith0600(t *testing.T) {
+	s := newTestStore(t, true)
+	if _, err := s.Submit(testToken, "落盘测试"); err != nil {
+		t.Fatal(err)
+	}
+	b, err := os.ReadFile(s.path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(b), testToken) {
+		t.Fatalf("磁盘文件出现明文: %s", b)
+	}
+	if fi, err := os.Stat(s.path); err == nil {
+		if fi.Mode().Perm() != 0o600 {
+			t.Errorf("变量库权限应为 0600，实际 %04o", fi.Mode().Perm())
+		}
+	} else {
+		t.Fatal(err)
+	}
+}
+
+// ★ 判据：权限不安全的变量库**拒绝加载**（响亮失败，不静默降级）。
+func TestRejectsLoosePermissions(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "v.json")
+	if err := os.WriteFile(p, []byte("[]"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	s := New(Options{Path: p, KeyFn: testKey, Enabled: true})
+	if err := s.Load(); err == nil {
+		t.Fatal("0644 的变量库必须被拒绝")
+	}
+	if err := os.Chmod(p, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Load(); err != nil {
+		t.Fatalf("0600 应可加载: %v", err)
+	}
+}
+
+// ★ 持久化往返：重启后别名仍可用（用户要求落盘 + 不自动淘汰）。
+func TestReloadKeepsVariables(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "v.json")
+	s1 := New(Options{Path: p, KeyFn: testKey, Enabled: true})
+	if err := s1.Load(); err != nil {
+		t.Fatal(err)
+	}
+	alias, err := s1.Submit(testToken, "重启测试")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 模拟重启
+	s2 := New(Options{Path: p, KeyFn: testKey, Enabled: true})
+	if err := s2.Load(); err != nil {
+		t.Fatal(err)
+	}
+	out, n, _ := s2.Fill("x=@{" + alias + "}")
+	if n != 1 || !strings.Contains(out, testToken) {
+		t.Fatalf("重启后别名应仍可用: n=%d out=%q", n, out)
+	}
+}
+
+// ★ S12：不自动淘汰，但 agent 可**主动删除**。
+func TestForgetRemovesVariable(t *testing.T) {
+	s := newTestStore(t, true)
+	alias, _ := s.Submit(testToken, "")
+	if err := s.Forget(alias); err != nil {
+		t.Fatalf("删除失败: %v", err)
+	}
+	out, n, _ := s.Fill("x=@{" + alias + "}")
+	if n != 0 || strings.Contains(out, testToken) {
+		t.Fatalf("删除后不应再回填: %q", out)
+	}
+	if err := s.Forget(alias); err != ErrUnknownAlias {
+		t.Errorf("重复删除应返回 ErrUnknownAlias，实际 %v", err)
+	}
+}
+
+// ★ 判据：拿不到密钥 ⇒ **拒绝产出别名**（宁可漏报，不用裸哈希）。
+//
+// 这里要**直接测 `Alias()`**，不能只测 Replace：
+// Replace 里另有一道外层护栏（无密钥就整体早退），会把 Alias 层的降级
+// 挡住 —— 变异实验证实了这一点（只测 Replace 时，把 Alias 改成裸哈希降级
+// 判据仍绿）。纵深防御是对的，但两层必须各自有判据盯着。
+func TestNoKeyMeansNoAlias(t *testing.T) {
+	s := New(Options{Path: filepath.Join(t.TempDir(), "v.json"), KeyFn: nil, Enabled: true})
+
+	// ① Alias() 本身必须报错（不降级为裸哈希）
+	if a, err := s.Alias("anything"); err != ErrNoMasterKey {
+		t.Errorf("无密钥时 Alias 应返回 ErrNoMasterKey，实际 alias=%q err=%v", a, err)
+	}
+	// ② Submit() 也必须失败（不静默记个裸哈希别名）
+	if a, err := s.Submit(testToken, ""); err == nil {
+		t.Errorf("无密钥时 Submit 应失败，实际得到 %q", a)
+	}
+	// ③ outer guard：Replace 原样返回
+	out, evts := s.Replace("token="+testToken, "input", Patterns)
+	if len(evts) != 0 {
+		t.Fatal("无密钥时不得产出别名")
+	}
+	if out != "token="+testToken {
+		t.Errorf("无密钥时应原样保留: %s", out)
+	}
+	// ④ Fill 也应安全降级（不 panic、不改动）
+	if got, n, _ := s.Fill("@{sec_x}"); n != 0 || got != "@{sec_x}" {
+		t.Errorf("无密钥时 Fill 应原样返回: %q", got)
+	}
+	// ⑤ 密钥长度不对也必须拒绝（AES-256 要 32 字节）
+	bad := New(Options{Path: filepath.Join(t.TempDir(), "w.json"),
+		KeyFn: func() ([]byte, error) { return []byte("too-short"), nil }, Enabled: true})
+	if _, err := bad.Alias("x"); err == nil {
+		t.Error("密钥长度不对时必须报错")
+	}
+}
+
+// ★ 开关：关闭后完全不做事（显式才是特权）。
+func TestDisabledDoesNothing(t *testing.T) {
+	s := newTestStore(t, false)
+	out, evts := s.Replace("token="+testToken, "input", Patterns)
+	if len(evts) != 0 || out != "token="+testToken {
+		t.Error("关闭后不应做任何替换")
+	}
+}
+
+// ★ FillMap：工具参数是 map，要能递归回填（插件调用前用）。
+func TestFillMapRecursive(t *testing.T) {
+	s := newTestStore(t, true)
+	alias, _ := s.Submit(testToken, "")
+
+	args := map[string]interface{}{
+		"url": "https://" + "@{" + alias + "}" + "@host/repo",
+		"nested": map[string]interface{}{
+			"token": "@{" + alias + "}",
+		},
+		"list": []interface{}{"plain", "@{" + alias + "}"},
+		"num":  42,
+	}
+	n, used := s.FillMap(args)
+	if n != 3 {
+		t.Fatalf("应回填 3 处，实际 %d", n)
+	}
+	if len(used) != 3 {
+		t.Errorf("应报告 3 次使用: %v", used)
+	}
+	if !strings.Contains(args["url"].(string), testToken) {
+		t.Error("顶层未回填")
+	}
+	if !strings.Contains(args["nested"].(map[string]interface{})["token"].(string), testToken) {
+		t.Error("嵌套 map 未回填")
+	}
+	if !strings.Contains(args["list"].([]interface{})[1].(string), testToken) {
+		t.Error("数组未回填")
+	}
+	if args["num"].(int) != 42 {
+		t.Error("非字符串值不应被改动")
+	}
+}
+
+// ★ 未知别名：原样保留（不报错、不吞掉），以免把正常文本改坏。
+func TestFillKeepsUnknownAlias(t *testing.T) {
+	s := newTestStore(t, true)
+	in := "看看 @{sec_notexist} 和 @{sec_0000000000000000}"
+	out, n, _ := s.Fill(in)
+	if n != 0 {
+		t.Fatalf("未知别名不应被替换，实际 %d", n)
+	}
+	if out != in {
+		t.Errorf("未知别名应原样保留: %q", out)
+	}
+	// 不像引用的文本也不该被碰
+	out2, n2, _ := s.Fill("普通文本 @{bad-name!} 与 email@example.com")
+	if n2 != 0 || out2 != "普通文本 @{bad-name!} 与 email@example.com" {
+		t.Errorf("非引用文本被改动: %q", out2)
+	}
+}
+
+// ★ 拦截事件是**可观测**的（S5，不静默做事），且 merged 标明是否合并。
+func TestInterceptEventsObservable(t *testing.T) {
+	s := newTestStore(t, true)
+	_, e1 := s.Replace("a="+testToken, "input", Patterns)
+	_, e2 := s.Replace("b="+testToken, "tool_result:cmd_run", Patterns)
+
+	if len(e1) != 1 || len(e2) != 1 {
+		t.Fatal("两次都应各产生 1 条事件")
+	}
+	if e1[0].Merged {
+		t.Error("首次应 merged=false")
+	}
+	if !e2[0].Merged {
+		t.Error("第二次同明文应 merged=true（合并）")
+	}
+	if e1[0].Alias != e2[0].Alias {
+		t.Error("同明文应同一别名")
+	}
+	if e2[0].Where != "tool_result:cmd_run" {
+		t.Errorf("应记录来源位置: %q", e2[0].Where)
+	}
+}
+
+// ★ 判据：明文（高熵）不得从**别名**反推出来。
+//
+// 这是 HMAC + 截断的性质，用抽样验证（不是穷举证明，而是防低级错误）。
+func TestAliasDoesNotLeakPlaintext(t *testing.T) {
+	s := newTestStore(t, true)
+	alias, _ := s.Alias(testToken)
+	// 别名里不能包含明文的任何连续 8 字符片段
+	for i := 0; i+8 <= len(testToken); i++ {
+		if strings.Contains(alias, testToken[i:i+8]) {
+			t.Fatalf("别名泄露了明文片段: %s", alias)
+		}
+	}
+}
+
+func sha256Hex16(s string) string {
+	h := sha256Sum([]byte(s))
+	return hexEncode(h[:8])
+}