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-06 01:07:35 +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/agent/api/codec_cgo.go
+++ b/internal/agent/api/codec_cgo.go
@ -84,11 +84,12 @@ import "unsafe"
 // codecABIVersionExpected 是 C 侧 ha_abi.h 里 HA_CODEC_ABI_VERSION 的 Go 副本。
 //
 // ★ 为什么要手工拄一份而不是让 cgo 直接读宏：
-//   cgo 顶部的 C 代码在 cgo 阶段被**预处理并丢弃**，其中的宏在 Go 侧不可见；
-//   能看到的只有 cgo 生成的文件。用 cgo 的 `const` 桥接（C.ha_codec_abi_version）只能在
-//   **运行期**问到版本，编译期拿不到，无法把「两侧版本不一致」变成构建失败。
-//   而「注释里说冻结」不是机制。这份 Go 常量 + codec_abiversion_test.go
-//   把版本漂移变成**测试期断言**，真正对得上才跑得起来。
+//
+//	cgo 顶部的 C 代码在 cgo 阶段被**预处理并丢弃**，其中的宏在 Go 侧不可见；
+//	能看到的只有 cgo 生成的文件。用 cgo 的 `const` 桥接（C.ha_codec_abi_version）只能在
+//	**运行期**问到版本，编译期拿不到，无法把「两侧版本不一致」变成构建失败。
+//	而「注释里说冻结」不是机制。这份 Go 常量 + codec_abiversion_test.go
+//	把版本漂移变成**测试期断言**，真正对得上才跑得起来。
 //
 // 改动规则（与 ha_abi.h 一致）：
 //   - C 侧新增函数/枚举值（纯追加）→ 同步把这里 +1，并改 abi_test 的期望
@ -101,20 +102,21 @@ const (
 // codecABIVersionMacroValue 查询 C 侧 HA_CODEC_ABI_VERSION 宏展开后的值。
 //
 // ★ 它的存在是为了堵一个盲区：TestABIVersionMatches 比的是
-//   「Go 常量 vs C 函数返回值」。若有人同时把 Go 常量和 C 函数
-//   一起改掉（而忘了改 ha_abi.h 的宏），那条测试照样通过 ——
-//   **两边一起错成一样**是它的盲区。这个值直接取自 C 宏，
-//   由 codec_abimacro_test.go 拿来交叉核对。
+//
+//	「Go 常量 vs C 函数返回值」。若有人同时把 Go 常量和 C 函数
+//	一起改掉（而忘了改 ha_abi.h 的宏），那条测试照样通过 ——
+//	**两边一起错成一样**是它的盲区。这个值直接取自 C 宏，
+//	由 codec_abimacro_test.go 拿来交叉核对。
 //
 // ★ 为何是函数而非 Go 常量：cgo 生成的 `*_Cvar_*` 不是 Go 常量
-//   （实测 "is not constant"），无法在编译期参与断言。
-//   编译期的保证在 C 侧（codec_cgo.go 里的 _Static_assert）。
+//
+//	（实测 "is not constant"），无法在编译期参与断言。
+//	编译期的保证在 C 侧（codec_cgo.go 里的 _Static_assert）。
 func codecABIVersionMacroValue() int { return int(C.ha_abi_version_macro()) }

 // codecABIVersion 查询 C 侧自称的 ABI 版本（major*1000 + minor）。
 func codecABIVersion() int { return int(C.ha_codec_abi_version()) }

-
 // cstr2 与 cstr 同义（返回 Go 的 string 版本），供 cgo 桥接层使用。
 // 名字不同是为了与测试文件里的辅助函数区分，避免包内重名。
 func cstr2(s string) (*C.char, C.size_t) { return cstr(s) }
--- a/internal/agent/api/codec_chunkfast_bench_test.go
+++ b/internal/agent/api/codec_chunkfast_bench_test.go
@ -12,11 +12,11 @@ import (
 )

 var benchChunks = map[string]string{
-	"content_zh": `{"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1727000000,"model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"content":"这是一段来自真实流式响应的中文内容，用于测量解析开销。"},"finish_reason":null}]}`,
+	"content_zh":    `{"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1727000000,"model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"content":"这是一段来自真实流式响应的中文内容，用于测量解析开销。"},"finish_reason":null}]}`,
 	"content_ascii": `{"id":"chatcmpl-abc","choices":[{"index":0,"delta":{"content":"hello world this is a longer ascii content chunk"},"finish_reason":null}]}`,
-	"toolcall": `{"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1727000000,"model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_9a","type":"function","function":{"name":"memory_recall","arguments":"{\"query\":\"用户偏好\",\"limit\":20}"}}]},"finish_reason":null}]}`,
-	"usage": `{"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1727000000,"model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"content":""},"finish_reason":null}],"usage":{"prompt_tokens":3821,"completion_tokens":117,"total_tokens":3938,"prompt_cache_hit_tokens":3584,"prompt_cache_miss_tokens":237}}`,
-	"finish": `{"id":"c","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}`,
+	"toolcall":      `{"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1727000000,"model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_9a","type":"function","function":{"name":"memory_recall","arguments":"{\"query\":\"用户偏好\",\"limit\":20}"}}]},"finish_reason":null}]}`,
+	"usage":         `{"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1727000000,"model":"deepseek-v4.1-flash","choices":[{"index":0,"delta":{"content":""},"finish_reason":null}],"usage":{"prompt_tokens":3821,"completion_tokens":117,"total_tokens":3938,"prompt_cache_hit_tokens":3584,"prompt_cache_miss_tokens":237}}`,
+	"finish":        `{"id":"c","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}`,
 }

 // BenchmarkChunkFast_Entry 走真实入口（含 C 路径 + 必要的回退）。
@ -52,10 +52,11 @@ func BenchmarkChunkFast_GoOnly(b *testing.B) {
 // TestChunkFast_BenchGate 钉死当前事实：chunkFastEnabled 必须为 false。
 //
 // ★ 为什么把「一个优化是关的」也做成断言：
-//   「还没验证有效就先关着」是**容易丢失的状态** —— 后来者看到
-//   「快速路径写得挺全 + 6 万条差分测试全过」，很自然会以为它已生效，
-//   进而打开它、甚至删掉开关。而实测它**更慢**。
-//   断言把这个事实钉在测试里，开关一旦被改就立刻判红。
+//
+//	「还没验证有效就先关着」是**容易丢失的状态** —— 后来者看到
+//	「快速路径写得挺全 + 6 万条差分测试全过」，很自然会以为它已生效，
+//	进而打开它、甚至删掉开关。而实测它**更慢**。
+//	断言把这个事实钉在测试里，开关一旦被改就立刻判红。
 func TestChunkFast_BenchGate(t *testing.T) {
 	if chunkFastEnabled {
 		t.Fatalf("chunkFastEnabled 被打开了，但实测本架构比原实现慢：\n" +
--- a/internal/agent/api/codec_chunkfast_c.go
+++ b/internal/agent/api/codec_chunkfast_c.go
@ -53,7 +53,6 @@ package api
 //   ③ 一条**永不静默回退**的机制：若未来把它切回默认开启，
 //      TestChunkFast_BenchGate 会立刻用基准把它按回去。

-
 import "encoding/json"

 const chunkFastEnabled = false
--- a/internal/agent/api/codec_chunkfast_golden_test.go
+++ b/internal/agent/api/codec_chunkfast_golden_test.go
@ -212,9 +212,9 @@ func randJSONValue(rng *rand.Rand, depth int) interface{} {
 		return []interface{}{randJSONValue(rng, depth-1)}
 	case 2:
 		return map[string]interface{}{
-			"prompt_tokens":    rng.Intn(9999),
-			"total_tokens":     rng.Intn(9999),
-			"completion":       rng.Intn(999),
+			"prompt_tokens":           rng.Intn(9999),
+			"total_tokens":            rng.Intn(9999),
+			"completion":              rng.Intn(999),
 			"prompt_cache_hit_tokens": rng.Intn(10),
 		}
 	default:
@ -241,7 +241,7 @@ func TestChunkFast_RandomJSON(t *testing.T) {
 		case 0:
 			obj["choices"] = []interface{}{map[string]interface{}{
 				"index":         rng.Intn(3),
-				"delta":        map[string]interface{}{"content": randJSONValue(rng, 2)},
+				"delta":         map[string]interface{}{"content": randJSONValue(rng, 2)},
 				"finish_reason": []interface{}{nil, "", "stop", "length"}[rng.Intn(4)],
 			}}
 		case 1:
--- a/internal/agent/api/codec_estimate_calib_test.go
+++ b/internal/agent/api/codec_estimate_calib_test.go
@ -96,7 +96,7 @@ func TestEstimateNeverBelowRealWorldFloors(t *testing.T) {
 func TestEstimateMonotonicNonDecreasingInBytes(t *testing.T) {
 	prev := 0
 	for n := 1; n <= 64; n++ {
-		s := strings.Repeat("a", n)       // ASCII 侧
+		s := strings.Repeat("a", n) // ASCII 侧
 		got := estimateTokensPure(s)
 		if got < prev {
 			t.Fatalf("estimate(\"a\"×%d)=%d < 前值 %d —— 非单调", n, got, prev)
@ -105,7 +105,7 @@ func TestEstimateMonotonicNonDecreasingInBytes(t *testing.T) {
 	}
 	prev = 0
 	for n := 1; n <= 64; n++ {
-		s := strings.Repeat("你", n)      // CJK 侧
+		s := strings.Repeat("你", n) // CJK 侧
 		got := estimateTokensPure(s)
 		if got < prev {
 			t.Fatalf("estimate(\"你\"×%d)=%d < 前值 %d —— 非单调", n, got, prev)
--- a/internal/agent/api/codec_golden_test.go
+++ b/internal/agent/api/codec_golden_test.go
@ -176,4 +176,3 @@ func TestGolden_TruncateAlwaysPrefix(t *testing.T) {
 		}
 	}
 }
-
--- a/internal/agent/api/codec_jsongolden_test.go
+++ b/internal/agent/api/codec_jsongolden_test.go
@ -113,10 +113,10 @@ func TestJSONGolden_StringDecode(t *testing.T) {
 		`\"`, `\\`, `\/`, `\b`, `\f`, `\n`, `\r`, `\t`,
 		`\u0041`, `\u00e9`, `\u4f60\u597d`, `\ud83d\ude00`, `\u0000`,
 		`mixed \u4e2d\u6587 and ascii`,
-		`\ud83d` + `real`,       // 孤立高代理
-		`\udc00` + `real`,       // 孤立低代理
-		`\ud83dx`,               // 高代理 + 非转义
-		`\ud83d\u0041`,          // 高代理 + 非低代理
+		`\ud83d` + `real`, // 孤立高代理
+		`\udc00` + `real`, // 孤立低代理
+		`\ud83dx`,         // 高代理 + 非转义
+		`\ud83d\u0041`,    // 高代理 + 非低代理
 		"\xff", "\xfe", "\xff\xfe", "\xc3", "\xc3\x28", "\xe0\x80\x80",
 		"\xed\xa0\x80", "\xf5\x80\x80\x80", "\xf0\x9f\x98\x80", // 正常 4 字节
 		"a\xffb", "\x80", "\xbf",
@ -255,11 +255,12 @@ func TestJSONScanABIVersion(t *testing.T) {
 // goUnquoteBody 用 encoding/json 自身解码一个 JSON 字符串体（raw = 不含两端引号）。
 //
 // ★ 正确做法是**直接把 body 原样**放进引号里交给 Unmarshal ——
-//   body 里本来就带着它自己的转义（`\n` 是两个字节），若在此处再转义一遍，
-//   就把「转义序列」变成了「字面量」，参照值会整体跑偏。
-//   实测踩过：初版对 body 里的 `\` 和 `"` 做了二次转义，
-//   导致 Go 侧期望 `\n`（两字节）而 C 侧正确给出换行符 ——
-//   测试报了一堆「分歧」，其实错的是测试自己的参照。
+//
+//	body 里本来就带着它自己的转义（`\n` 是两个字节），若在此处再转义一遍，
+//	就把「转义序列」变成了「字面量」，参照值会整体跑偏。
+//	实测踩过：初版对 body 里的 `\` 和 `"` 做了二次转义，
+//	导致 Go 侧期望 `\n`（两字节）而 C 侧正确给出换行符 ——
+//	测试报了一堆「分歧」，其实错的是测试自己的参照。
 func goUnquoteBody(body string) (string, error) {
 	var out string
 	if err := json.Unmarshal([]byte(`"`+body+`"`), &out); err != nil {
--- a/internal/agent/api/codec_jsonscan_cgo.go
+++ b/internal/agent/api/codec_jsonscan_cgo.go
@ -110,10 +110,11 @@ func cjsMembersInit(m *C.ha_json_members, s string) bool {
 // cjsMembersStep 推进一次迭代，只把**键**交回 Go。
 //
 // ★ 为什么只返回键：cgo 规则禁止把「Go 指针指向的 Go 指针」传给 C
-//   （cgo argument has Go pointer to unpinned Go pointer）——若把 key 与
-//   value 两个 span 都交回 Go，再在同一个调用里传回 C，就会构成
-//   「Go 切片 → Go 指针 → Go 指针」的未固定链，运行时直接 panic。
-//   所以每次跨语言只搬运**一个**字符串，其余信息留到下一次调用。
+//
+//	（cgo argument has Go pointer to unpinned Go pointer）——若把 key 与
+//	value 两个 span 都交回 Go，再在同一个调用里传回 C，就会构成
+//	「Go 切片 → Go 指针 → Go 指针」的未固定链，运行时直接 panic。
+//	所以每次跨语言只搬运**一个**字符串，其余信息留到下一次调用。
 //
 // ★ 值 span 只在需要时**在 C 侧**用（见 cjsWalkMembers）。
 func cjsMembersStep(m *C.ha_json_members) (key string, ok bool) {
@ -201,9 +202,10 @@ func cjsWalkMembers(s string) (inited bool, count int, complete bool) {
 // JSON 值，尾部除空白外不得有残留。
 //
 // ★ 为什么测试不能只调 ha_json_skip：skip 的语义是「跳过这里的一个值」，
-//   它成功返回并不能证明「整串就是这一个值」。实测 `{"a":1}{"b":2}`
-//   在 skip 下成功，而 json.Valid=false —— 这正是两者职责的差别。
-//   内核协议层要的是严格语义，故这里显式做尾部校验。
+//
+//	它成功返回并不能证明「整串就是这一个值」。实测 `{"a":1}{"b":2}`
+//	在 skip 下成功，而 json.Valid=false —— 这正是两者职责的差别。
+//	内核协议层要的是严格语义，故这里显式做尾部校验。
 func cjsSkipStrict(s string) bool {
 	p, n := cstr2(s)
 	return C.go_skip_strict(p, n) == 1
--- a/internal/agent/api/codec_pure.go
+++ b/internal/agent/api/codec_pure.go
@ -45,7 +45,8 @@ const contextWindowUnknown = -1
 // 标称窗口 ≠ 有效窗口：接近满时注意力涣散，调用方应取 70-80% 为目标利用率。
 //
 // ★ 分支顺序即语义：先匹配者胜出（例：gpt-4-turbo 必须先于裸 gpt-4）。
-//   C 侧 ha_codec_model_context_window 必须保持同一顺序。
+//
+//	C 侧 ha_codec_model_context_window 必须保持同一顺序。
 func modelContextWindowPure(model string) int {
 	model = strings.ToLower(model)
 	switch {
--- a/internal/agent/api/codec_streamchunk_c.go
+++ b/internal/agent/api/codec_streamchunk_c.go
@ -144,7 +144,8 @@ func (s strSpan) valid() bool { return s.p != nil && s.n > 0 }
 // bytes 把 span 变成 Go 字节切片（此处才产生一次拷贝）。
 //
 // ★ 用途：把「已定位的原始子树」交给 json.Unmarshal —— 用同一 Go 类型
-//   unmarshal 同一形状，是本层保证「类型检查语义与原实现一致」的手段。
+//
+//	unmarshal 同一形状，是本层保证「类型检查语义与原实现一致」的手段。
 func (s strSpan) bytes() []byte {
 	if s.p == nil || s.n == 0 {
 		return nil
@ -172,7 +173,6 @@ func (s strSpan) firstByte() byte {
 // 定位
 // ---------------------------------------------------------------------

-
 // ---------------------------------------------------------------------
 // 取值（C 可判定的热分支）
 // ---------------------------------------------------------------------
@ -180,8 +180,9 @@ func (s strSpan) firstByte() byte {
 // decBuf 是解码/反转义用的可写缓冲。
 //
 // ★ 尺寸必须按输入长度定：C 侧要求 cap >= len*3+4（最坏每字节一个 U+FFFD），
-//   不足时它会返回 0 让调用方回退 Go（宁可慢也不截断）。
-//   每次调用 1 次分配（原来整块 Unmarshal 是 12~21 次）—— 这是主要的节省点。
+//
+//	不足时它会返回 0 让调用方回退 Go（宁可慢也不截断）。
+//	每次调用 1 次分配（原来整块 Unmarshal 是 12~21 次）—— 这是主要的节省点。
 func decBuf(n int) []byte { return make([]byte, n*3+8) }

 // stringifyC 对应 Go stringifyContent 的**C 可判定分支**
@ -200,7 +201,6 @@ func stringifyC(val strSpan) (string, bool) {
 	return string(buf[:int(outLen)]), true
 }

-
 // ---------------------------------------------------------------------
 // 顶层 helper：大小写不敏感（struct 字段语义）与根对象校验
 // ---------------------------------------------------------------------
@ -253,7 +253,6 @@ func sseRootObject(doc strSpan) bool {
 	return C.go_root_object(doc.p, doc.n) == 1
 }

-
 // ---------------------------------------------------------------------
 // 批量定位（第三刀的重做：一次 cgo 调用代替 5+ 次）
 // ---------------------------------------------------------------------
@ -302,9 +301,9 @@ const (
 	kindArray  = 4
 	kindOther  = 5

-	chunkOK         = 0
-	chunkFallback   = -1
-	chunkTypeFail   = -2
+	chunkOK       = 0
+	chunkFallback = -1
+	chunkTypeFail = -2
 )

 // locateChunkBatch 一次调用完成整块定位。
@ -348,5 +347,3 @@ func locateChunkBatch(data string) chunkLocateResult {
 	out.finish = string(s[co.finish_off : co.finish_off+co.finish_len])
 	return out
 }
-
-
--- a/internal/agent/api/provider.go
+++ b/internal/agent/api/provider.go
@ -17,6 +17,8 @@ import (
 	"time"

 	luaVM "github.com/JianFeeeee/HomeAgent/internal/lua"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
 )

 // ContentBlock 定义多模态内容块，用于图片/音频等非文本输入。
@ -945,7 +947,8 @@ func (p *LuaAdaptedProvider) ChatStream(ctx context.Context, req *CompletionRequ
 	ch := make(chan StreamChunk, 64)
 	go func() {
 		defer resp.Body.Close()
-		defer close(ch)
+		var chOnce sync.Once
+		defer safeclose.Safe(&chOnce, ch)

 		scanner := bufio.NewScanner(resp.Body)
 		scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
@ -1037,7 +1040,8 @@ func (p *LuaAdaptedProvider) ChatStream(ctx context.Context, req *CompletionRequ
 		}
 		out := make(chan StreamChunk, 64)
 		go func() {
-			defer close(out)
+			var outOnce sync.Once
+			defer safeclose.Safe(&outOnce, out)
 			out <- first
 			for ck := range ch {
 				out <- ck
@ -1094,7 +1098,28 @@ func (m *ProviderManager) Reset() {
 	m.status = make(map[string]*providerStatus)
 }

+// Register 登记一个 provider。
+//
+// ★ 这里是**安全模块的唯一挂载点**：出向改写的装饰器包在这里，
+// 就覆盖了全部取用路径（Get / Default / OrderedProviders /
+// ResolveForModel 都从同一张 map 取，已核）。
+//
+// 为何不逐个改调用方：CodeGraph 交叉验证显示 NewLuaAdaptedProvider 有 6 个
+// 调用者（含插件运行时动态注册 llm_impl.go:115、failback.go:28），
+// 逐个改必漏；而且插件新增 provider 时无人在意去挂装饰器。
+//
+// 安全模块未启用时 security.Global() 返回 nil ⇒ 装饰器完全不介入，零成本。
 func (m *ProviderManager) Register(name string, p Provider) {
+	// 出向明文 → 别名（防泄漏）。未启用时原样透传。
+	//
+	// 守卫：已是本层装饰过的实例就不再包一层。
+	// 双重包裹本身无害（第二遍看到的已无明文，是空转），但会白跑一遗
+	// 正则扫描 —— 而热路径上每条消息都扫一遍，不值得。
+	if store := security.Global(); store != nil {
+		if _, alreadyWrapped := p.(*secureProviderDecorator); !alreadyWrapped {
+			p = WrapProviderForSecurity(p, store)
+		}
+	}
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	m.providers[name] = p
--- a/internal/agent/api/provider_error_class_test.go
+++ b/internal/agent/api/provider_error_class_test.go
@ -99,4 +99,4 @@ func TestClassify_Mutation_调换优先级后401翻案(t *testing.T) {
 		t.Fatalf("当前实现应判 ErrCredential，实际 %v", got)
 	}
 	// 若有人把顺序改成「先查特征词」，上面这行就会失败 —— 即本测试能捕获该回归。
-}
+}
--- a/internal/agent/api/provider_security.go
+++ b/internal/agent/api/provider_security.go
@ -0,0 +1,99 @@
+// provider 出向装饰器：把明文替换成变量别名。
+//
+// 落点：`ProviderManager.Register`（唯一入口，已核 —— 见
+// docs/zh/kernel-secret-firewall-design.md §5.1）。
+//
+// 装饰在这里而不是每个调用方，是因为 CodeGraph 交叉验证确认：
+// Get / Default / OrderedProviders / ResolveForModel 全都从 Register
+// 写入的那张 map 取，装饰 Register 即全覆盖。
+package api
+
+import (
+	"context"
+	"log"
+
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+// secureProviderDecorator 在**发往 LLM 之前**把消息里的明文换成别名。
+//
+// ### 为何要逐条消息扫，而不是拼起来扫
+//
+// 拼接会跨越消息边界产生误报：上一条的结尾与下一条的开头恰好连成
+// 一个 token 形状。逐条扫不可能有这种跨边界命中。
+//
+// ### 为何同时处理 Content 与 Blocks
+//
+// 内核的消息有多模态 Blocks（截图描述等）。只扫 Content 会漏掉
+// 图片 URL 之类的载荷。这里两者都过一遍。
+type secureProviderDecorator struct {
+	inner Provider
+	store *security.Store
+}
+
+// WrapProviderForSecurity 给 provider 套上出向改写。
+//
+// store 为 nil 时原样返回（安全模块未启用 ⇒ **零成本**）。
+func WrapProviderForSecurity(p Provider, store *security.Store) Provider {
+	if p == nil || store == nil {
+		return p
+	}
+	return &secureProviderDecorator{inner: p, store: store}
+}
+
+func (d *secureProviderDecorator) Name() string          { return d.inner.Name() }
+func (d *secureProviderDecorator) MaxContextTokens() int { return d.inner.MaxContextTokens() }
+
+// scrubRequest 逐条消息改写（**原地**改，因为 req 是要发出去的那一份）。
+func (d *secureProviderDecorator) scrubRequest(req *CompletionRequest) {
+	if req == nil {
+		return
+	}
+	for i := range req.Messages {
+		m := &req.Messages[i]
+
+		if m.Content != "" {
+			out, evts := d.store.Replace(m.Content, "llm_out:"+m.Role, security.Patterns)
+			if len(evts) > 0 {
+				m.Content = out
+				d.logEvts(evts)
+			}
+		}
+
+		// 多模态 Blocks：文本块要扫；image_url 里的 data URL 也要扫
+		// （截图/文档里可能带凭据）。
+		for j := range m.Blocks {
+			b := &m.Blocks[j]
+			if b.Text != "" {
+				if out, evts := d.store.Replace(b.Text, "llm_out:"+m.Role+":block", security.Patterns); len(evts) > 0 {
+					b.Text = out
+					d.logEvts(evts)
+				}
+			}
+			if b.ImageURL != nil && b.ImageURL.URL != "" {
+				if out, evts := d.store.Replace(b.ImageURL.URL, "llm_out:"+m.Role+":image", security.Patterns); len(evts) > 0 {
+					b.ImageURL.URL = out
+					d.logEvts(evts)
+				}
+			}
+		}
+	}
+}
+
+// logEvts 记录拦截（**只记别名，绝不记明文**）。
+func (d *secureProviderDecorator) logEvts(evts []security.Evt) {
+	for _, e := range evts {
+		log.Printf("[security] 出向拦截 %s ← 模式 %s，%d 字节，合并=%v，位置 %s",
+			e.Alias, e.Kind, e.Len, e.Merged, e.Where)
+	}
+}
+
+func (d *secureProviderDecorator) Chat(ctx context.Context, req *CompletionRequest) (*CompletionResponse, error) {
+	d.scrubRequest(req)
+	return d.inner.Chat(ctx, req)
+}
+
+func (d *secureProviderDecorator) ChatStream(ctx context.Context, req *CompletionRequest) (<-chan StreamChunk, error) {
+	d.scrubRequest(req)
+	return d.inner.ChatStream(ctx, req)
+}
--- a/internal/agent/api/security_premise_test.go
+++ b/internal/agent/api/security_premise_test.go
@ -0,0 +1,341 @@
+package api
+
+// 前提验证：**安全模块能否稳在 provider 层**。
+//
+// 设计依据：docs/zh/kernel-secret-firewall-design.md §5.1。
+//
+// 整件事成立的前提是两条：
+//
+//	P1. 所有发往 LLM 的调用都经 `Provider.Chat` / `Provider.ChatStream`
+//	    （没有绕过接口的直发路径）
+//	P2. `ProviderManager.Register` 是所有 provider 的**唯一入口**
+//	    ⇒ 在 Register 处包一层装饰器，就能覆盖全部取用路径
+//	       （Get / Default / OrderedProviders / ResolveForModel 都从同一 map 取）
+//
+// 若 P1 或 P2 不成立，安全模块必须下沉到更底层（HTTP 客户端），改动面大得多。
+// ⇒ 先验它，再写实现（本仓纪律：前提不成立时不要继续设计上层）。
+
+import (
+	"context"
+	"encoding/json"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+// countingProvider 记录它被调用了几次、收到什么消息。
+type countingProvider struct {
+	calls  int
+	seen   []string
+	stream int
+}
+
+func (c *countingProvider) Name() string { return "counting" }
+
+func (c *countingProvider) Chat(ctx context.Context, req *CompletionRequest) (*CompletionResponse, error) {
+	c.calls++
+	for _, m := range req.Messages {
+		c.seen = append(c.seen, m.Content)
+	}
+	return &CompletionResponse{Content: "ok"}, nil
+}
+
+func (c *countingProvider) ChatStream(ctx context.Context, req *CompletionRequest) (<-chan StreamChunk, error) {
+	c.stream++
+	ch := make(chan StreamChunk, 1)
+	close(ch)
+	return ch, nil
+}
+
+func (c *countingProvider) MaxContextTokens() int { return 8192 }
+
+// ★★ P2：装饰 Register ⇒ **所有取用路径都拿到装饰后的实例**。
+//
+// 这是安全模块能"一处生效、处处覆盖"的机制保证。
+func TestPremise_RegisterDecorateCoversAllAccessPaths(t *testing.T) {
+	m := NewProviderManager()
+
+	inner := &countingProvider{}
+	var wrapped Provider
+	// 模拟安全模块：在 Register 处包一层
+	m.Register("p1", &proxyProvider{inner: inner, onCall: func() { wrapped = nil }})
+	_ = wrapped
+
+	// ① Get 拿到的是装饰后的
+	got := m.Get("p1")
+	if got == nil {
+		t.Fatal("Get 返回 nil")
+	}
+	if _, isProxy := got.(*proxyProvider); !isProxy {
+		t.Fatalf("Get 未拿到装饰后的实例，实际类型 %T", got)
+	}
+	// ② Default 也拿到装饰后的
+	if _, isProxy := m.Default().(*proxyProvider); !isProxy {
+		t.Fatal("Default 未拿到装饰后的实例")
+	}
+	// ③ OrderedProviders 也是
+	ord := m.OrderedProviders()
+	if len(ord) != 1 {
+		t.Fatalf("OrderedProviders 数量 %d", len(ord))
+	}
+	if _, isProxy := ord[0].(*proxyProvider); !isProxy {
+		t.Fatal("OrderedProviders 未拿到装饰后的实例")
+	}
+	// ④ ResolveForModel 也是
+	res := m.ResolveForModel("")
+	if len(res) == 0 {
+		t.Fatal("ResolveForModel 为空")
+	}
+	if _, isProxy := res[0].(*proxyProvider); !isProxy {
+		t.Fatal("ResolveForModel 未拿到装饰后的实例")
+	}
+}
+
+// ★★ P1：经 manager 取到的 provider，其 Chat 必经装饰器。
+//
+// 这条证明"安全模块能看见每一条出网请求"。
+func TestPremise_DecoratorSeesEveryChat(t *testing.T) {
+	m := NewProviderManager()
+	inner := &countingProvider{}
+	var seen int
+	m.Register("p1", &proxyProvider{inner: inner, onCall: func() { seen++ }})
+
+	p := m.Get("p1")
+	if _, err := p.Chat(context.Background(), &CompletionRequest{
+		Messages: []Message{{Role: "user", Content: "hello"}},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if seen != 1 {
+		t.Fatalf("装饰器应看到 1 次 Chat，实际 %d", seen)
+	}
+	if inner.calls != 1 {
+		t.Fatalf("内层应被调 1 次，实际 %d", inner.calls)
+	}
+	// ChatStream 同样要经过
+	if _, err := p.ChatStream(context.Background(), &CompletionRequest{}); err != nil {
+		t.Fatal(err)
+	}
+	if seen != 2 {
+		t.Fatalf("ChatStream 也应经装饰器，实际 seen=%d", seen)
+	}
+}
+
+// ★★ 关键能力验证：装饰器**能改写请求**（这正是安全模块要做的替换）。
+func TestPremise_DecoratorCanRewriteMessages(t *testing.T) {
+	m := NewProviderManager()
+	inner := &countingProvider{}
+	// 模拟安全模块：把明文换成别名
+	m.Register("p1", &proxyProvider{inner: inner, onCall: func() {}})
+
+	// 直接用能改写的装饰器
+	m.Register("p2", &rewriteProvider{inner: inner})
+
+	req := &CompletionRequest{Messages: []Message{
+		{Role: "user", Content: "token=SECRET-XYZ"},
+	}}
+	if _, err := m.Get("p2").Chat(context.Background(), req); err != nil {
+		t.Fatal(err)
+	}
+	// 内层必须收到**改写后**的内容（证明改写真的生效、不是只读）
+	found := false
+	for _, s := range inner.seen {
+		if strings.Contains(s, "SECRET-XYZ") {
+			t.Fatal("明文被原样透传，改写未生效")
+		}
+		if strings.Contains(s, "@{sec_") {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("内层未收到改写后的别名，实际收到: %v", inner.seen)
+	}
+}
+
+// ★ 覆盖面：ChatStream 也必须能被装饰（流式是主路径之一）。
+func TestPremise_StreamAlsoDecorated(t *testing.T) {
+	m := NewProviderManager()
+	inner := &countingProvider{}
+	m.Register("p1", &proxyProvider{inner: inner, onCall: func() {}})
+	if _, err := m.Get("p1").ChatStream(context.Background(), &CompletionRequest{}); err != nil {
+		t.Fatal(err)
+	}
+	if inner.stream != 1 {
+		t.Fatalf("内层 ChatStream 应被调 1 次，实际 %d", inner.stream)
+	}
+}
+
+// ---------------- 测试替身 ----------------
+
+// proxyProvider 是"只观察不修改"的装饰器。
+type proxyProvider struct {
+	inner  Provider
+	onCall func()
+}
+
+func (p *proxyProvider) Name() string { return p.inner.Name() }
+func (p *proxyProvider) Chat(ctx context.Context, req *CompletionRequest) (*CompletionResponse, error) {
+	if p.onCall != nil {
+		p.onCall()
+	}
+	return p.inner.Chat(ctx, req)
+}
+func (p *proxyProvider) ChatStream(ctx context.Context, req *CompletionRequest) (<-chan StreamChunk, error) {
+	if p.onCall != nil {
+		p.onCall()
+	}
+	return p.inner.ChatStream(ctx, req)
+}
+func (p *proxyProvider) MaxContextTokens() int { return p.inner.MaxContextTokens() }
+
+// rewriteProvider 是"会改写请求"的装饰器（模拟安全模块）。
+type rewriteProvider struct{ inner Provider }
+
+func (p *rewriteProvider) Name() string { return p.inner.Name() }
+func (p *rewriteProvider) Chat(ctx context.Context, req *CompletionRequest) (*CompletionResponse, error) {
+	// 模拟：把明文换成别名（真实实现会用模式库 + HMAC 键）
+	for i := range req.Messages {
+		if strings.Contains(req.Messages[i].Content, "SECRET-XYZ") {
+			req.Messages[i].Content = "token=@{sec_deadbeef}"
+		}
+	}
+	return p.inner.Chat(ctx, req)
+}
+func (p *rewriteProvider) ChatStream(ctx context.Context, req *CompletionRequest) (<-chan StreamChunk, error) {
+	return p.inner.ChatStream(ctx, req)
+}
+func (p *rewriteProvider) MaxContextTokens() int { return p.inner.MaxContextTokens() }
+
+// ---------------- 接线判据（装饰器真的挂在 Register 上） ----------------
+
+// ★★ 判据：经 Register 登记后，取出的 provider 就是**装饰过的**，
+// 且出向明文被换成了别名。
+//
+// 这是端到端接线判据：它同时验证
+//
+//	① Register 挂上了装饰器
+//	② 装饰器能拿到全局单例
+//	③ 替换真的发生了
+func TestWired_RegisterDecoratesAndScrubs(t *testing.T) {
+	dir := t.TempDir()
+	store, err := security.InitGlobal(security.Options{
+		Path:    filepath.Join(dir, "vars.json"),
+		KeyFn:   func() ([]byte, error) { return []byte("0123456789abcdef0123456789abcdef"), nil },
+		Enabled: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { security.SetGlobal(nil) })
+
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	var got string
+	inner := &recordingProvider{name: "wired", capture: &got}
+	m := NewProviderManager()
+	m.Register("p", inner)
+
+	// 取出（任何一条取用路径都应拿到装饰后的实例）
+	p := m.Default()
+	if p == nil {
+		t.Fatal("Default 返回 nil")
+	}
+	req := &CompletionRequest{Messages: []Message{{Role: "user", Content: "token=" + tok}}}
+	if _, err := p.Chat(context.Background(), req); err != nil {
+		t.Fatal(err)
+	}
+
+	if strings.Contains(got, tok) {
+		t.Fatalf("明文泄漏到 provider: %s", got)
+	}
+	if !strings.Contains(got, "安全模块自动拦截") {
+		t.Errorf("未见拦截提示: %s", got)
+	}
+	if store.Count() != 1 {
+		t.Errorf("应登记 1 条变量，实际 %d", store.Count())
+	}
+	// 记录里不得有明文
+	b, _ := json.Marshal(store.List())
+	if strings.Contains(string(b), tok) {
+		t.Error("变量记录泄露明文")
+	}
+}
+
+// ★ 判据：安全模块未初始化时，Register **不介入**（零成本）。
+func TestWired_NoStoreMeansNoInterference(t *testing.T) {
+	security.SetGlobal(nil)
+	t.Cleanup(func() { security.SetGlobal(nil) })
+
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	var got string
+	m := NewProviderManager()
+	m.Register("p", &recordingProvider{name: "plain", capture: &got})
+
+	if _, err := m.Default().Chat(context.Background(),
+		&CompletionRequest{Messages: []Message{{Role: "user", Content: "token=" + tok}}}); err != nil {
+		t.Fatal(err)
+	}
+	if got != "token="+tok {
+		t.Errorf("未启用安全模块时不得改动内容: %q", got)
+	}
+}
+
+// ★ 判据：回填把别名换回明文（入向通道）。
+func TestWired_FillToolArgs(t *testing.T) {
+	dir := t.TempDir()
+	store, err := security.InitGlobal(security.Options{
+		Path:    filepath.Join(dir, "vars.json"),
+		KeyFn:   func() ([]byte, error) { return []byte("0123456789abcdef0123456789abcdef"), nil },
+		Enabled: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { security.SetGlobal(nil) })
+
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	alias, err := store.Submit(tok, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	args := map[string]interface{}{"token": "@{" + alias + "}", "other": "unchanged"}
+	n, used := security.FillToolArgs("some_plugin_tool", args)
+	if n != 1 {
+		t.Fatalf("应回填 1 处，实际 %d", n)
+	}
+	if args["token"] != tok {
+		t.Errorf("回填结果不对: %v", args["token"])
+	}
+	if args["other"] != "unchanged" {
+		t.Error("无关字段不应被改动")
+	}
+	if len(used) != 1 || used[0] != alias {
+		t.Errorf("应报告别名: %v", used)
+	}
+}
+
+// recordingProvider 记录它收到的最后一条消息内容。
+type recordingProvider struct {
+	name    string
+	capture *string
+}
+
+func (r *recordingProvider) Name() string { return r.name }
+func (r *recordingProvider) Chat(_ context.Context, req *CompletionRequest) (*CompletionResponse, error) {
+	if req != nil && len(req.Messages) > 0 {
+		*r.capture = req.Messages[0].Content
+	}
+	return &CompletionResponse{}, nil
+}
+func (r *recordingProvider) ChatStream(_ context.Context, req *CompletionRequest) (<-chan StreamChunk, error) {
+	if req != nil && len(req.Messages) > 0 {
+		*r.capture = req.Messages[0].Content
+	}
+	ch := make(chan StreamChunk)
+	close(ch)
+	return ch, nil
+}
+func (r *recordingProvider) MaxContextTokens() int { return 1000 }
--- a/internal/agent/api/security_wiring_test.go
+++ b/internal/agent/api/security_wiring_test.go
@ -0,0 +1,193 @@
+package api
+
+// 装配顺序判据。
+//
+// ## 为什么这个顺序值得单独立判据
+//
+// 安全模块的初始化必须在**任何 provider 注册之前**。装晚了的后果是：
+// 先注册的那批 provider 没被装饰 ⇒ **静默漏掉一条出网路径**，
+// 而且没有任何报错、日志也正常 —— 属于最难发现的那类失效。
+//
+// 而这个坑在本仓是真实存在的：
+//   · `cmd/homed/main.go` 的 initLLMProviders（主路径）
+//   · `internal/sdk/llm_impl.go` 的 ReloadFromConfig（配置热重载）
+//   · `cmd/homed/failback.go` 的 runFailbackRecovery（降级救援）
+//
+// 三个地方都会 Register。前两个在 security 之后；failback 也必须之后
+// （main.go 里它是第 174 行，安全模块是 162 行）。
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+// ★★ 判据：**晚注册的 provider 也自动被装饰**（因为装饰挂在 Register 上）。
+//
+// 这条钉住的是"挂载点选择正确"：如果装饰挂在某个初始化函数里
+// （而不是 Register），那么后注册的 provider 就会漏掉。
+func TestLateRegistrationStillDecorated(t *testing.T) {
+	dir := t.TempDir()
+	store, err := security.InitGlobal(security.Options{
+		Path:    filepath.Join(dir, "v.json"),
+		KeyFn:   func() ([]byte, error) { return []byte("0123456789abcdef0123456789abcdef"), nil },
+		Enabled: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { security.SetGlobal(nil) })
+
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	m := NewProviderManager()
+
+	// ① 先注册一个
+	var first string
+	m.Register("early", &recordingProvider{name: "early", capture: &first})
+
+	// ② 模拟"热重载"：Reset 后注册全新一批（ReloadFromConfig 的真实流程）
+	m.Reset()
+	var second string
+	m.Register("late", &recordingProvider{name: "late", capture: &second})
+
+	// ③ 再模拟 failback 的 rescue provider
+	var third string
+	m.Register("rescue", &recordingProvider{name: "rescue", capture: &third})
+
+	// 三个都必须被装饰
+	for _, tc := range []struct {
+		name string
+		got  *string
+	}{{"late", &second}, {"rescue", &third}} {
+		if _, err := m.Get(tc.name).Chat(context.Background(),
+			&CompletionRequest{Messages: []Message{{Role: "user", Content: "t=" + tok}}}); err != nil {
+			t.Fatal(err)
+		}
+		if strings.Contains(*tc.got, tok) {
+			t.Errorf("provider %s 未被装饰（明文泄漏）: %s", tc.name, *tc.got)
+		}
+	}
+	_ = first
+	if store.Count() == 0 {
+		t.Error("应登记变量")
+	}
+}
+
+// ★ 判据：**已装饰的不再包第二层**（避免热路径白跑）。
+func TestNoDoubleWrapping(t *testing.T) {
+	dir := t.TempDir()
+	if _, err := security.InitGlobal(security.Options{
+		Path:    filepath.Join(dir, "v.json"),
+		KeyFn:   func() ([]byte, error) { return []byte("0123456789abcdef0123456789abcdef"), nil },
+		Enabled: true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { security.SetGlobal(nil) })
+
+	m := NewProviderManager()
+	base := &recordingProvider{name: "x", capture: new(string)}
+	m.Register("a", base)
+	inner := m.Get("a")
+
+	// 把已装饰的实例再注册一次（某些装配路径会这么干）
+	m.Register("b", inner)
+	if _, isDecorator := m.Get("b").(*secureProviderDecorator); !isDecorator {
+		t.Fatal("应当仍是装饰实例")
+	}
+	// 再包一层的话，类型仍是装饰器但会嵌套 —— 用指针比较确认是同一个
+	if m.Get("b") != inner {
+		t.Error("已装饰的实例不应被再包一层（会白跑一遍正则扫描）")
+	}
+}
+
+// ★★ 判据：**main.go 里安全模块的初始化必须早于 initLLMProviders**。
+//
+// 这是源码级判据（读文件而不是跑逻辑），因为顺序错误在单测里
+// 构造不出来（main 的装配流程没法在测试里复现）。
+// 源码判据在此是有意为之：它盯的是一个**真实的、曾经坑过的**装配顺序。
+func TestMainInitsSecurityBeforeProviders(t *testing.T) {
+	src, err := os.ReadFile("../../../cmd/homed/main.go")
+	if err != nil {
+		t.Skipf("读不到 main.go（相对路径变了？）: %v", err)
+	}
+	text := string(src)
+
+	iSec := strings.Index(text, "security.InitGlobal")
+	// ★ 锚点已随"内核模块化"改写（2026-10-16）。
+	//
+	// 原先锚 `initLLMProviders(cfg,`（那时它直接写在 main 里）。
+	// 模块化后 **provider 注册搬进了 llm 模块**（`internal/kernelmod/llm`），
+	// 它在 `RunKernelModules` 内部执行 ⇒ 旧的字符串在 main.go 里**已经不存在**，
+	// 判据因"找不到"而失败（假红）。
+	//
+	// **注意：这不是放宽判据，而是把锚点换到新的真实装配点。**
+	// 不变量本身没变：安全模块必须早于**任何 provider 注册**。
+	// 新的等价表述：安全模块早于 `RunKernelModules`（llm 模块在它内部）。
+	//
+	// 为防止"换个锚点就变绿"式的偷懒，另加两条硬校验（见下）。
+	iProv := strings.Index(text, "RunKernelModules(")
+	if iSec < 0 {
+		t.Fatal("main.go 里找不到 security.InitGlobal —— 安全模块根本没被装配")
+	}
+	if iProv < 0 {
+		t.Fatal("main.go 里找不到 RunKernelModules —— 内核模块装配点没了")
+	}
+	if iSec > iProv {
+		t.Fatalf("装配顺序错误：security.InitGlobal 在第 %d 字节，RunKernelModules 在第 %d 字节\n"+
+			"必须先初始化安全模块 —— 内核模块装配时会注册 LLM provider，"+
+			"晚于它则 provider 不会被装饰（静默漏掉一条出网路径）",
+			iSec, iProv)
+	}
+	// ★ 加固 ①：provider 注册**确实**在内核模块里（否则新锚点就是空的 ——
+	// 那等于把判据锚在一个与 provider 无关的位置上）。
+	// 判据：kernelmod/llm 模块必须注册，且其 Init 里出现 initLLMProviders。
+	llmSrc, lerr := os.ReadFile("../../kernelmod/llm/mod.go")
+	if lerr != nil {
+		t.Fatalf("读不到 llm 模块（provider 注册应在这里）: %v", lerr)
+	}
+	if !strings.Contains(string(llmSrc), "initLLMProviders") {
+		t.Fatal("★ llm 模块里没有 initLLMProviders —— " +
+			"那么上面锚 RunKernelModules 就与 provider 注册无关了（判据会变空）")
+	}
+	// ★ 加固 ②：llm 模块必须是**真注册过**的（不是死代码）
+	allSrc, aerr := os.ReadFile("../../kernelmod/all/all.go")
+	if aerr != nil {
+		t.Fatalf("读不到模块总表: %v", aerr)
+	}
+	if !strings.Contains(string(allSrc), "kernelmod/llm") {
+		t.Fatal("★ llm 模块没被 import ⇒ 它的 init() 不跑 ⇒ provider 永不注册")
+	}
+
+	// failback 也要在之后
+	iFail := strings.Index(text, "runFailbackRecovery")
+	if iFail >= 0 && iSec > iFail {
+		t.Error("runFailbackRecovery 在安全模块之前 —— rescue provider 会漏装饰")
+	}
+}
+
+// ★ 判据：阶段断言 —— 源码里装饰发生在 Register 内部（挂载点正确）。
+func TestDecorateHappensInsideRegister(t *testing.T) {
+	src, err := os.ReadFile("provider.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(src)
+	// Register 函数体内必须出现 WrapProviderForSecurity
+	i := strings.Index(text, "func (m *ProviderManager) Register(")
+	if i < 0 {
+		t.Fatal("找不到 Register")
+	}
+	// 取到下一个顶层 func 为止
+	rest := text[i:]
+	if j := strings.Index(rest[1:], "\nfunc "); j > 0 {
+		rest = rest[:j+1]
+	}
+	if !strings.Contains(rest, "WrapProviderForSecurity") {
+		t.Fatal("Register 函数体内没有装饰调用 —— 装饰被挪走了（后注册的 provider 会漏掉）")
+	}
+}