diff --git a/Makefile b/Makefile
index 6f4ecf74..9ac13b2e 100644
--- a/Makefile
+++ b/Makefile
@@ -25,6 +25,11 @@ GO=go
 GOCACHE=/tmp/gocache
 export GOPATH=/tmp/gopath
 BUILD_DIR=build
+# GRAPH_FILE 是启动依赖图的制品名（必须与 kernelboot.GraphFileName 一致）。
+#
+# ★ 图的来源是**各模块自己的 Requires()/Provides()**（不再有手工 JSON 清单）：
+# 生成器 import internal/kernelmod/all（各模块 init 自注册）⇒ 算分层 ⇒ 落图。
+GRAPH_FILE=depgraph.bin
 PROJECT_ROOT := $(CURDIR)
 # 版本号来源（见 docs/git-branching.md §2.1）：
 #
@@ -281,7 +286,36 @@ check-csrc-full: check-csrc csrc-fuzz
 
 build:
 	@mkdir -p $(BUILD_DIR)
-	CGO_ENABLED=1 $(GO) build $(TAG_ARGS) -trimpath -installsuffix dynlink -ldflags '$(LDFLAGS)' -o $(BUILD_DIR)/$(BINARY) ./cmd/homed/
+	@# ★ 编译期定序：先由生成器（import 模块登记表）算出启动顺序图，
+	@#   取 digest，再构建 homed 并把 digest 注入二进制。
+	@#
+	@# 为何必须"先出图后构建"（设计 §2.5.2）：启动时 homed 比对
+	@# 「磁盘图的 digest」与「内嵌 digest」，不一致 ⇒ **拒绝启动**。
+	@# 两边必须来自**同一次构建**。
+	@#
+	@# 为何要这个保护：它能拦住最危险的一类故障 —— 图文件自身完好
+	@# （自校验通过），但描述的是**旧代码**（改了 Requires 没重出图）
+	@# ⇒ 按旧图调度 ⇒ 顺序错（正是要消灭的"静默顺序错"）。
+	@#
+	@# ⚠ 本段必须写成**一条 shell 命令**（\ 续行）：
+	@#   Make 的每行 recipe 是独立 shell，普通变量跨行不保留。
+	@#
+	@# ★★ ldflags 的引号必须让 $${GRAPH_HASH} **能展开**（2026-10-17 实测缺陷）：
+	@#   原写法把整串包在**单引号**里 ⇒ shell 里单引号不做变量展开
+	@#   ⇒ 注入进二进制的是**字面量** `$$GRAPH_HASH` ⇒ 内核启动时比对
+	@#   「磁盘图 digest」vs「内嵌的 $$GRAPH_HASH」必然不等 ⇒ **拒绝启动**。
+	@#   而 `make build` 日志全绿（图生成了、hash 也"注入"了），
+	@#   只有真跑内核才暴露。修法：用**双引号**包 ldflags。
+	@#
+	@# ⚠ 上面这条注释**不能挪到 recipe 中间**：注释行会打断 \ 续行链，
+	@#   使后半段成为**独立的 shell**（变量丢失 ⇒ hash 为空）。
+	@GRAPH_HASH=""; \
+	CGO_ENABLED=1 $(GO) build $(TAG_ARGS) -o $(BUILD_DIR)/homed-depgraph ./cmd/homed-depgraph/ && \
+	GRAPH_HASH=$$($(BUILD_DIR)/homed-depgraph -digest) && \
+	$(BUILD_DIR)/homed-depgraph -print && \
+	$(BUILD_DIR)/homed-depgraph -out $(BUILD_DIR)/$(GRAPH_FILE) && \
+	echo "已注入启动依赖图 hash: $$GRAPH_HASH" ; \
+	CGO_ENABLED=1 $(GO) build $(TAG_ARGS) -trimpath -installsuffix dynlink -ldflags "$(LDFLAGS) -X github.com/JianFeeeee/HomeAgent/internal/kernelboot.EmbeddedGraphHash=$$GRAPH_HASH" -o $(BUILD_DIR)/$(BINARY) ./cmd/homed/
 	@echo "Built: $(BUILD_DIR)/$(BINARY) ($(VERSION), tags='$(HOMED_TAGS)')"
 	@go version -m $(BUILD_DIR)/$(BINARY) | grep -q 'onnxruntime' \
 		|| echo "WARN: 本次构建不含 onnxruntime，本地向量空间不可用（HOMED_TAGS= 显式关掉时才符合预期）"
diff --git a/assets/skills/commondev-discipline/SKILL.md b/assets/skills/commondev-discipline/SKILL.md
new file mode 100644
index 00000000..9d665310
--- /dev/null
+++ b/assets/skills/commondev-discipline/SKILL.md
@@ -0,0 +1,871 @@
+---
+name: commondev-discipline
+description: commondev 主管式多仓库开发流水线的使用与开发纪律。当你要为某个工程开一条分支、把工程派给一个下属 agent、或用 pi 拉起执行 agent 干活时必读。核心动作：为每个工程对话新建驻留式子 agent 并把该工程的一对通道划给它（否则所有工程都挤在根 agent 上）。**git 托管平台的操作（Gitea/GitHub/GitLab）不在插件里，而在本文** —— 用 enc_shell + 保存的凭据调 curl/CLI 完成。也含 hmap 插件开发与部署纪律。
+version: 2.0.0
+author: HomeAgent
+---
+
+# commondev 纪律（主管模式 · 工程对话 · 平台操作）
+
+本技能三部分，**都可能与你的任务直接相关**：
+
+- **第一部分：使用者纪律** —— 怎么开工程、怎么派活。
+- **第二部分：★ git 平台操作** —— **本文是权威**。开 PR、审批、分支保护怎么做。
+- **第三部分：开发与部署纪律** —— 怎么不踩坑。
+
+> ## ★ 架构边界（用户拍板 2026-10-15）
+>
+> | 层 | 负责 |
+> |---|---|
+> | **插件 commondev** | 项目台账、工作目录、pi 会话与通道、判据与变异复核、冲突预检、凭据保存与安全执行 |
+> | **本文（skill）** | **各 git 托管平台的认证头、API 端点、PR 与分支保护流程** |
+>
+> **插件里没有平台逻辑。** 操作 Gitea/GitHub/GitLab 等平台一律：
+> 读本文 → 用 `enc_shell` + `@{凭据名}` 执行 `curl`/`gh`/`tea`。
+>
+> ⇒ **新增一个托管平台只需改本文，不需要改插件、不需要重编译、不需要重启服务。**
+>
+> 原本这些在插件里（`platformSpec` / `commondev_account_*` / `commondev_pr_*` /
+> `commondev_protect_branch` / `commondev_repo_search`），代价是：
+> 每接一个平台都要改 Go 代码 → 重编译 → 重打包 → 重启，
+> 且**未列出的平台直接报错**（GitLab/Gitee/Bitbucket 全不支持）——
+> 而 agent 用 curl 本来什么平台都能打。这 10 个工具已移除。
+
+> 看不懂某个词时的权威文档（按顺序读）：
+> 1. `docs/zh/commondev-design.md` —— 目标机制、台账 schema、判据与变异、安全（§12 是架构变更）。
+> 2. `docs/zh/commondev-agent-runtime-design.md` —— 运行时与内核接入（续篇）。
+> 3. `docs/zh/kernel-secret-firewall-design.md` —— 凭据模块（enc_* 的底座）。
+> 4. `docs/zh/resident-subagent-design.md` —— 驻留子设计的原始文档。
+>
+> **本文与文档冲突时，以文档为准，并回来修正本文。**
+
+---
+
+## Setup: 第二部分 git 平台操作（本文是权威，不要凭记忆写 API）
+
+### 11. 所有平台都是同一个形状
+
+「带认证头发一个 REST 请求」。用 `enc_shell` + `curl` 即可：
+
+```
+enc_shell(command="curl -s -H \"<认证头>\" <API前缀><路径>")
+```
+
+**差异只有两个维度：API 前缀 与 认证头。** 其余是 REST 常规。
+
+### 12. 认证头与 API 前缀（逐平台，★ 四种形状互不相同）
+
+| 平台 | API 前缀 | 认证头 |
+|---|---|---|
+| **Gitea** | `<base>/api/v1` | `Authorization: token <T>` ← **不是 Bearer** |
+| **GitHub** | `https://api.github.com` | `Authorization: Bearer <T>` |
+| **GitLab** | `<base>/api/v4` | `PRIVATE-TOKEN: <T>` ← **不是 Authorization** |
+| **GitCode** | `https://api.gitcode.com/api/v5` | `Authorization: Bearer <T>` |
+| **Gitee** | `https://gitee.com/api/v5` | `access_token=<T>`（**查询参数**，不是头） |
+
+⚠ 头名、前缀、甚至「用头还是用查询参数」都不同。**未知平台先查官方文档，不要猜形状。**
+
+### 13. 先保存凭据，再用它
+
+```
+enc_store(alias="gitea-token", value="${GITEA_TOKEN}")     # 值优先走 ${ENV} 或 @file:
+enc_shell(command="curl -s -H \"Authorization: token @{gitea-token}\" http://192.168.2.106:3000/api/v1/user")
+```
+
+⚠ **优先用 `enc_store`，不要用 `commondev_account_add`** —— 后者已不存在
+（它内建了平台语义：platform/role/base_url，那正是被移出的东西）。
+
+**先验凭据再干活**（早失败，别推了一半才发现 token 错）：
+
+```
+enc_shell(command="curl -s -o /dev/null -w '%{http_code}' -H \"Authorization: token @{gitea-token}\" http://192.168.2.106:3000/api/v1/user")
+# 期望 200；401/403 = 凭据无效或权限不足
+```
+
+### 14. 常见操作（以 Gitea 为例，其他平台换前缀与头）
+
+```bash
+# 搜仓库
+curl -s -H "Authorization: token @{t}" "http://host/api/v1/repos/search?q=myname&limit=20"
+
+# 看仓库 / 分支
+curl -s -H "Authorization: token @{t}" "http://host/api/v1/repos/jianf/MyProj"
+curl -s -H "Authorization: token @{t}" "http://host/api/v1/repos/jianf/MyProj/branches"
+
+# 开 PR（head=你的分支，base=目标分支）
+curl -s -X POST -H "Authorization: token @{t}" -H 'Content-Type: application/json'   -d '{"title":"...","head":"feat/x","base":"main"}'   "http://host/api/v1/repos/jianf/MyProj/pulls"
+
+# 查 PR 状态
+curl -s -H "Authorization: token @{t}" "http://host/api/v1/repos/jianf/MyProj/pulls/7"
+
+# 合 PR
+curl -s -X POST -H "Authorization: token @{t}" -H 'Content-Type: application/json'   -d '{"Do":"merge"}' "http://host/api/v1/repos/jianf/MyProj/pulls/7/merge"
+```
+
+**push 时凭据不进 remote URL**：
+
+```bash
+# ✅ 一次性注入（仅本次命令）；clone 出来的 remote 保持干净
+enc_shell(command="cd <repo> && git -c http.extraheader=\"Authorization: token @{t}\" push origin feat/x")
+```
+
+⚠ 若改用 `https://token@host/...` 形式，token 会**持久化进 `.git/config`** ——
+删掉临时目录也删不掉凭据（`git remote -v` 就能读出来）。设计 §7.2 明令禁止。
+
+### 15. Gitea 分支保护：让「必须复审」成为**机制**而非礼貌
+
+**光有流程约定不算机制** —— 执行 agent 可以直接推主干。必须让**平台**拦。
+
+```bash
+curl -s -X POST -H "Authorization: token @{t}" -H 'Content-Type: application/json'   -d '{"enable_push":false,"required_approvals":1,"block_admin_merge_override":true,"dismiss_stale_approvals":true}'   "http://host/api/v1/repos/jianf/MyProj/branch_protections?name=main"
+```
+
+四个开关的意义（缺一个机制就有洞）：
+
+| 开关 | 作用 | 缺了会怎样 |
+|---|---|---|
+| `enable_push: false` | 禁止直接推送 | 执行 agent 直推主干，绕过评审 |
+| `required_approvals: ≥1` | 至少一个审批 | 自己就能合 |
+| `block_admin_merge_override: true` | admin 也不能绕过 | 用 admin token 的人绕过一切 |
+| `dismiss_stale_approvals: true` | 新提交作废旧审批 | 先批准再改代码，批准白拿 |
+
+**真机实测（Gitea 1.24.2）**：
+
+| 动作 | 普通用户 token | admin token |
+|---|---|---|
+| push `main` | ❌ `pre-receive hook declined` | ⚠ 可能成功（见下）|
+| push `feat/*` | ✅ | ✅ |
+| 自合 PR | ❌ `Does not have enough approvals` | ⚠ 取决于开关 |
+| 审批 → 合 PR | — | ✅ |
+
+⇒ **推论：执行侧必须用普通用户 token。** 用 admin token 会**静默绕过分支保护**
+（看起来正常，实际机制失效且无报错）—— 这是最容易搞错的一点。
+
+⚠ 分支保护已存在时用 **PATCH**（POST 会 403 `already exist`）。
+
+### 16. 审批：三个必踩的 API 坑（实测）
+
+1. **`event` 必须是 `APPROVED`，不是 `APPROVE`。**
+   传 `APPROVE` 时请求**返回 200 且不报错**，但 review 状态落成 `PENDING` ——
+   于是 `required_approvals` 永远不满足，合并时报 `Does not have enough approvals`。
+   表象（权限不足）与真因（枚举值少个 `D`）毫无关联，极难自查。
+2. **必须带 `commit_id`** —— 不带时同样落成 `PENDING`（与 `event` 是两个独立条件）。
+3. **`required_approvals` 也约束 admin** —— 别指望用 admin 跳过审批。
+
+```bash
+# ① 先取 head sha（审批必须绑定**具体提交**，不是"移动的目标"）
+enc_shell(command="curl -s -H \"Authorization: token @{t}\" http://host/api/v1/repos/jianf/MyProj/pulls/7 | grep -o '\"sha\":\"[a-f0-9]*\"' | head -1")
+# ② 审批（event 必须 APPROVED，且带 commit_id）
+enc_shell(command="curl -s -X POST -H \"Authorization: token @{t}\" -H 'Content-Type: application/json' -d '{\"body\":\"通过\",\"event\":\"APPROVED\",\"commit_id\":\"<sha>\"}' http://host/api/v1/repos/jianf/MyProj/pulls/7/reviews")
+```
+
+**失败时保留平台原话**：`Does not have enough approvals` 是区分「机制生效」
+与「配置错了」的唯一线索，别把它翻译掉或吞掉。
+
+---
+
+## Usage: 第一部分 使用者纪律
+
+> **★ 设计总纲 ［已定］**：插件对 pi 做的事，本质就是
+> **「把给 pi 发消息包装一下、把 pi 返回包装一下」**，深度融合内核的 IO 抽象与中断系统
+> —— 即 **pi = 一个 Device**。**不要自己造调度器 / 会话路由 / 中断栈**，
+> 全部接到内核已有的那套上（`InjectInputTo` / `RegisterOutputChannel` / `InjectInterrupt*Opts`）。
+
+### 21. 角色与单位
+
+| 角色 | 是谁 | 干什么 |
+|---|---|---|
+| **人** | 老板 | 只与主管对接 |
+| **主管** | 你（长期驻留的 HomeAgent 主 agent） | 拆任务、**定义判据**、复审、决定合入 |
+| **执行 agent** | 按工程拉起的一个 pi / dsh 实例 | 在某棵工作树里干活 |
+| **commondev 插件** | 外部独立插件 | 仓库/凭据/分支/PR/测试，全部机械化操作 |
+
+**为何能用内核机制**（而不是自己造）：
+
+| 内核概念 | pi 侧对应 | 落点（内核已有） |
+|---|---|---|
+| **给 pi 发消息** | `pi.prompt` / `steer` / `follow_up` | `InjectInputTo(source, "commondev/<id>", …)` |
+| **pi 返回** | sidecar 回调 / `tool_execution_*` / `agent_settled` | `InjectTextTo(source, "commondev/<id>", …)`（按 inputch Owner 路由） |
+| **中断 pi** | `steer`（插到当前轮之后） | `InjectInterruptTextOpts(..., Priority: L3)` |
+| **音声/图像产物** | pi 可产出的媒体 | `OutputCapabilities()` 声明 |
+
+⇒ **插件只做两件额外事**：① 把 pi 接成 Device；② 台账记 `session_id` 并断言未变。
+调度/中断/路由/记忆策略**全是内核已经在做的事**。
+
+### 22. 「工程对话」是一等对象
+
+它是四元组，缺一不可：
+
+```
+工程对话 (id = br-<project>-<slug>)
+├─ workdir      <插件数据目录>/program/<hash>-<name>
+│                ★ hash = H(项目+分支) 是**唯一性来源**
+│                  ⇒ **同一仓库的不同分支必然是不同目录**（否则两 agent 共用工作树、改动互相污染）
+│                ★ name = 分支名派生，**仅做可读性**，不承担唯一性
+│                  （派生后可能撞：`feat/a` 与 `feat.a` 都成 `feat_a`，所以必须带 hash）
+│                独立 clone（非 worktree、非 --reference）；合入后**整目录删除**
+├─ session_id   pi 会话（★ 续投的唯一依据）
+├─ runtime      local（默认，内嵌） | ssh（远端同样建目录拉 pi）
+├─ host         runtime=ssh 时的目标主机（**branch_open 时给**，见 §24.1）
+├─ agent_cli    执行后端（默认 pi；其他 CLI 需自备 sidecar，见 §24.2）
+└─ channels     插件为该工程注册的一对通道
+                ├─ inputch  commondev/<id>
+                └─ outputch commondev_<id>
+```
+
+**一个仓库可并行开发**：每分支一份独立 clone，互不污染、可同时推进。
+但并行有前提——必须是**互不相干的模块**；有依赖的任务请先拆边界。
+
+> **为何不能用 worktree / `--reference`**（实测）：worktree 删后有
+> `.git/worktrees/` 残留（需 `prune`）；`--reference` 有 alternates 外部依赖，
+> mirror 被清即损坏。**本地 clone 对象为硬链接**（实测 inode 相同）⇒ 省磁盘、
+> 无外部依赖、刪掉即彻底。代价：失去 worktree「同分支不可双挂」的保护
+> ⇒ 台账层必须补**唯一性闸**（同名未结分支响亮拒绝）。
+
+### 23. ★ 必做：为每个工程对话新建驻留子，并把通道划给它
+
+**★ 顺序很关键**：通道是**拉起 pi 拿到 session 之后**才注册的，所以你的动作是：
+
+```
+建工程 ──► commondev_agent_up（拉起 pi，拿到 session_id）
+            └─► 插件**此刻才**注册通道 inputch commondev/<id> + outputch commondev_<id>
+                  └─► ★ 你建驻留子并把这对通道划给它
+```
+
+**为何必须先有 session**：通道是“与某个具体 pi 会话对话的入口”，没 session 就是空壳。
+顺序错了（先建子）会拿到一个指向不存在通道的 `output_send__…`。
+
+**插件只能把通道登记出来；「划入（assign）」只有内核能做。** 所以这一步**必须由你（agent）
+自己调内核工具完成**，插件无法代劳。
+
+```
+resident_agents create
+    id              = dev-<br-id>
+    input_chs       = commondev/<br-id>       ← 划入该 inputch（可用斜杠）
+    allowed_outputs = commondev_<br-id>       ← 授权该 outputch（★ 下划线，见下）
+    capacity        = 64
+    task_prompt     = "你在 <workdir> 推进 <work>。
+                       下任务给自己用 output_send__commondev_<br-id>(payload=…)，
+                       pi 的结果会回投到你的 commondev/<br-id>；
+                       有结论用 notify_parent 汇报。"
+```
+
+**★ 下任务不需要新工具**：给 pi 发消息就是子调**内核原生的输出门**
+`output_send__commondev_<br-id>(payload="…")` ⇒ 打到插件的通道 handler ⇒ 插件
+查台账拿到 `session_id` 后 `sidecar.prompt()`。**插件不提供 `agent_send` 之类的工具**。
+
+**⚠️ 通道命名（很容易踩）**：
+
+| | 能用 `/` 吗 | 为什么 |
+|---|---|---|
+| **inputch** | ✅ | 内核自己就用 `child/<id>` |
+| **outputch** | ❌ **绝对不行** | 它会拼成 `output_send__<name>`，上游要求函数名 `^[a-zA-Z0-9_-]{1,64}$`；违反的后果不是“这个工具不可用”，而是**整条请求 400、agent 整体失语** |
+
+⇒ 所以 inputch 叫 `commondev/<br-id>`、outputch 叫 `commondev_<br-id>`。
+`<br-id>` 本身也只能用 `[A-Za-z0-9_-]`。
+
+**为什么必须这么做（不是可选的优化）：**
+
+1. inputch 是**最基本的输入路由单位**，路由按 `Owner` 在**进内核之前**完成。
+   划给子之后，**该工程的输入只流向那个子**，根 agent 看不到它 —— 这正是
+   多工程并行能做到"互不串台"的原因。
+2. **不划会的代价**（如果你偷懒）：所有工程对话的输入都涌向**根 agent**，
+   根成了瓶颈、上下文被 N 条工程的细节淹没，多工程并行**等于没做**。
+   现场教训（`resident-subagent-design.md`）：子挂着 `inputch=[timer]` 而 timer
+   的输入打在父身上，**子的轮次永远是 0** —— 登记了不等于划了。
+
+**落地判据**（怎么知道做对了）：
+
+- 投一条输入到 `commondev/<br-id>`，应只被 `dev-<br-id>` 处理；
+- 根 agent 的轮次**不**因这条输入增加；
+- `input_channels` 工具（内核自带，单工具多视图）用 `view=by_agent` 能看到划分总览。
+
+### 24. 形态选择、自包含运行时与远端环境
+
+**默认本地内嵌**（进程内 pi 实例）；通过配置 `runtime=ssh` 切到**远程**，
+远端**同样创建目录并在该目录拉起 pi**。
+
+**★ 自包含运行时**：插件**自带独立的 node 与独立的 pi**，都装在**插件工作目录**，
+**pi 的插件也装到这个目录** —— 不靠宿主机的 node/pi，也不污染用户的 `~/.pi`。
+**独立 node/pi 随包分发**（不首次下载、不依赖用户装）。
+
+```
+<插件数据目录>/runtime/
+  node/  pi/
+  agentdir/          ← 每个内层 pi 必须传 PI_CODING_AGENT_DIR 指这里
+    settings.json    ← pi 自己的配置（偏好 / 默认 model / 全局包声明）
+    models.json      ← pi 自己的配置（★ LLM 源写这里）
+    auth.json        ← pi 自己的配置（key / OAuth，0600）
+    mcp.json         ← pi 自己的配置（MCP 服务器）
+    skills/ prompts/ themes/ extensions/
+```
+
+#### 24.1 远端（ssh）怎么开
+
+两个轴**正交**，开线时一起给：
+
+```
+commondev_branch_open(project="p", branch="feat/x",
+                      runtime="ssh", ssh_host="build@10.0.0.9")
+```
+
+- `runtime=ssh` 而**没给 `ssh_host`** → 直接拒绝（不会拖到拉起时才报）
+- **未知 runtime**（比如 `k8s`）→ 响亮拒绝，**不静默降级为 local**
+  （静默降级会让"我以为跑在远端"一路错下去）
+- 远端前置条件（**先配好，不要指望交互输密码**）：
+  - 从本机到目标机的**免密**（`BatchMode=yes`，卡在密码提示会超时）
+  - 远端有 node（不在 PATH 里就配 `ssh_node_path`，例如 `/opt/node/bin/node`）
+  - **必配两个根目录**（缺任一，远端线开不起来）：
+    - `ssh_workdir_root` — 远端放**工程工作目录**的根
+    - `ssh_runtime_root` — 远端放 **sidecar 脚本**的目录
+- **★ 工作目录在远端准备**：本地 `clone --mirror` 出来的目录远端看不到，
+  所以远端线走的是**远端建目录 → 远端共享 mirror（`<root>/.mirrors/`）→
+  远端 clone → 远端切分支**。同一远端上的多条分支线共享一份 mirror。
+  台账里的 `workdir` 会被改写成**远端路径**（不是本地路径）。
+  远端拉取要求**远端自己能认证该仓库** —— 本插件**不把凭据推到远端**
+  （凭据不进工作目录、不进 remote URL）。拉不动就响亮报错。
+- 每次拉起会 `scp` 把 sidecar 推过去（幂等）——**不推就会跑上一次的旧脚本**，
+  症状是"改了没生效"，极难归因。推送失败**响亮报错**，不静默用旧脚本。
+- 用 `commondev_agent_state` 看 `ssh_host` 确认打到哪台机。
+
+#### 24.2 接其他 CLI（zcode 等）——**不改插件核心**
+
+执行后端是**声明式**的：放一个目录就多一个后端。
+
+```
+<插件数据目录>/runtime/<cli>/
+    driver.json     ← 描述：脚本名 / 参数 / 环境变量 / LLM 源策略
+    sidecar.mjs     ← 实现 sidecar 契约（ping / prompt / state / ...）
+```
+
+**脚本查找链**（按优先级，go 侧 `locateSidecarScript`）：
+
+| 顺序 | 位置 | 用途 |
+|---|---|---|
+| ① | `<插件数据>/runtime/<cli>/<script>` | 用户自备 / 覆盖随包版本 |
+| ② | `<插件目录>/rawfile/runtime/<cli>/<script>` | **随包分发**（内置 pi 靠这条） |
+| ③ | `<可执行文件同目录>/<script>` | 开发期（hmapdev debug） |
+
+⚠ **② 是内置 pi 的必需项**（不是可选）：`sidecar.mjs` 随插件包分发，
+装在 `rawfile/runtime/pi/`。全新机器上不需要任何手工准备 ——
+若这条断了，表现是「插件装了、工具都在、但一拉 agent 就报找不到脚本」，
+且错误里那个路径用户从没听说过。
+
+自己加 CLI 时：把 `driver.json` + 脚本放在 `<插件数据>/runtime/<cli>/`（①），
+两条都行；① 优先。
+
+`driver.json` 关键字段：
+
+| 字段 | 含义 |
+|---|---|
+| `script` | 脚本文件名（默认 `sidecar.mjs`） |
+| `node` | `auto` = 用插件自带的 node |
+| `args` | 参数模板，占位符 `{workdir} {sessionId} {sessionName} {dataDir} {pluginDir}` |
+| `env` | 环境变量模板（同样支持占位符） |
+| `llmConfig` | `pi` = 插件替它写 pi 的配置；**`none` = 它自管凭据，插件不碰** |
+| `sessionDirSuffix` | 会话目录后缀 |
+
+**纪律**：
+
+- **未知 `agent_cli` 响亮报错，绝不回退到 pi** —— 回退会用错后端跑任务而无提示。
+- `driver.json` **损坏也报错**（不猜默认），否则是"改了没生效"的经典来源。
+- 内置 pi **不需要** `driver.json`（有内建描述），老部署不受影响。
+- 现成例子看 `examples/custom-cli/zcode/`（**源码核实过**的 ZCode 契约）。
+
+### 25. ★ 两种插件安装粒度（临时 vs 全局）
+
+| 粒度 | 作用域 | 落到实处 | 用什么 |
+|---|---|---|---|
+| **临时** | 一个工程对话 | `<workdir>/.pi/settings.json` | `pi install -l` |
+| **全局** | 插件自带 pi 的**所有**工程 | `<agentdir>/settings.json` | `pi install` + `PI_CODING_AGENT_DIR` |
+
+**支持的源**（实测）：`npm:@scope/pkg@1.0.0`（带版本即钉住）/ `git:github.com/u/r@v1` /
+`https://github.com/u/r`（当 git 源）/ `ssh://…` / 本地路径（**不复制**）。
+
+**三条纪律**：
+
+1. **必须传 `PI_CODING_AGENT_DIR`**，否则「全局」安装会写进**用户的** `~/.pi/agent/settings.json`
+   —— 那是对宿主的越界。
+2. **⚠ 安装是复制，不是引用**：`pi install ./pkg` 会把包**复制**到目标；改源目录
+   **不影响已装的那份**（我曾因此得出「插件不生效」的错误结论）。要更新必须重装。
+3. **安装是显式一步**，不藏在 `agent_up` 里；来源（npm 包名 / 仓库 URL / 版本钉点）要可见。
+
+### 26. ★ LLM 源与 pi 配置：直接写 pi 的配置文件
+
+⛔ **不要自建第二套配置存储**（本稿前版曾提 `config_commondev`，**已废弃**）。
+**pi 本身就有完整的配置系统**，插件只是它的**受控写入入口**：
+
+```
+<agentdir>/settings.json   ← 偏好 / 默认 model / 「全局」包声明
+<agentdir>/models.json     ← 兼容端点与模型（★ LLM 源写这里）
+<agentdir>/auth.json       ← API key / OAuth（0600）
+<agentdir>/mcp.json        ← MCP 服务器
+```
+
+内核把 LLM 源存在 **`config` 表**（不是 `config_<plugin>`），键前缀 `core.llm.`：
+
+```
+core.llm.provider                 = llmsproxy     ← ★ 默认源就是这一项
+core.llm.sources.<n>.base_url / .api_key / .model / .adapter / .context_window …
+```
+
+**导入时字段一对一对上**：`base_url`→`baseUrl`、`api_key`→`apiKey`、
+`adapter=openai`→`api="openai-completions"`、`model`→`models[].id`、
+`context_window`→`contextWindow`。
+
+**工具面**（每个工具对应一处 pi 配置）：
+
+```
+commondev_pi_source_import   把内核的源批量导入内置 pi
+commondev_pi_source_add      添加源（写 models.json / auth.json）
+commondev_pi_source_list     列出（默认**不返回** api_key）
+commondev_pi_source_default  指定默认源（写 settings.json）
+commondev_pi_config_get/set  读写其他 pi 配置
+commondev_pi_mcp_add/remove/list
+```
+
+**四条实现纪律**：
+
+1. **写的就是 pi 的配置文件**，不造中间层；格式与 pi 自己写出的保持一致
+   （否则 pi 重写文件时会把自定义字段抹掉）。
+2. **改前备份、改后回读校验**：json 写坏会让内层 pi 直接起不来；失败则回滚 + **响亮报错**。
+3. **key 不进日志/不进返回值**。
+4. **不改用户全局**：所有写入带 `PI_CODING_AGENT_DIR=<agentdir>` 或显式 scope，
+   绡不碰 `~/.pi/agent/`。
+
+**两条红线**：
+
+1. **key 不能明文落盘到无保护位置**：`models.json`/`auth.json` 含明文 key ⇒ 目录 **0700**、
+   文件 **0600**。内核那套是明文存 `config.db`（**644 全局可读**）—— **别把这套惯例带进来**。
+2. **不得静默回退到宿主凭据**：导入失败/源不可用就**报错**，不要偷偷用 `~/.pi/agent/auth.json`
+   跑起来（那是宿主的凭据，用了就是越界）。
+
+### 27. 远端环境缺失：问用户，不要自己装（硬纪律）
+
+```
+ssh 不通          → 报错（配置问题，不是缺环境）
+无 pi / 无 node   → ★ 注入 L3「远端 <host> 未装 X，是否安装？」→ **你（agent）去问用户**
+目录不可写        → 报错（权限问题，需人处理）
+```
+
+- **SDK 没有“向用户提问”的 API**（插件是子进程，不能直接弹 UI）。现有机制是插件把
+  决策消息注入给 agent（L1–L3），**由 agent 问用户**（先例：`cli` 的 `/stop` 用 L3）。
+- **不得擅自安装**：不 `curl | sh` 到别人的机器上。要先说清「装什么、装哪里、要什么权限」。
+- **不冒充成功**：环境缺失时 `agent_up` **响亮失败** + 留一条待决策项，
+  **不静默降级到本地跑**（那会让人以为活派到了远端）。
+- **问完要能续**：安装动作本身是**可见的一步**（可查、可重跑），不是 `agent_up` 的隐式副作用。
+
+### 28. 投递纪律（**这是最容易犯的错**）
+
+**每个工程的投递必须落到同一个 `session_id`。** 实测反例（别重犯）：
+
+| 错法 | 后果 |
+|---|---|
+| 漏传 `--session-id` | `pi` **静默开新会话** —— 你以为在催上一次，其实是把活派给了陌生人 |
+| 两个进程**并发**同 `--session-id` | 会话文件被写坏：`user A`/`user B` 相邻，`assistant B` 在前、`assistant A` 落在最后 ⇒ B 那轮的模型上下文里**根本没有 A 的用户消息**，树链交错 |
+
+⇒ 投递前先拿台账里的 `session_id`，投完**断言它没变**；一个 session **绝不并发投递**。
+这两条插件侧已做成结构性保证（单一投递队列 + 断言），你做主管时**不要绕过插件**直接
+去敲 `pi -p`。
+
+**★ 另外两条实测硬经验（别再踩）：**
+
+3. **SDK 路径必须显式指定会话 id**。用 `createAgentSession({cwd})` 而不传
+   `sessionManager` 时，pi **自己生成 UUID** 作会话 id ⇒ 与台账名字不一致 ⇒
+   断言**永远失败**（实测：期望 `br-cdtest-feat_alpha`，实际 `01a13959-…`）。
+   正确：`SessionManager.create(cwd, sessionDir, {id})` 再传给 `createAgentSession`。
+4. **工具返 `ok` ≠ 消息到了**。内核对成功回执刻意**极简**（防 output loop），
+   所以 `ok` 只说 handler 成功了。必须去会话文件里看到 `user: <payload>` 才算数。
+   （这条能防住“以为投了、其实没投”这类假成功。）
+
+### 29. 三层审查的分工（别把自己变成贵的高级码农）
+
+| 层 | 审什么 | 不审什么 |
+|---|---|---|
+| agent 自审 | 代码正确性、风格、实现细节 | — |
+| **你（主管）复审** | **这次的改动，判据够不够**：引入了哪些新失败方式？判据覆盖了吗？变异咬得住吗？ | 逐行读 diff |
+| 插件复核 | 机械执行「正向 + 变异」 | 语义判断 |
+
+### 30. ★ 不要把「测试通过」当作「改对了」
+
+插件只能跑**你预先写下的判据**。判据没覆盖那条 bug，插件照样打勾 ——
+自动化**不会**发现假绿，**只会让假绿跑得更快、更可信**。
+
+因此复核**必须两步**：
+
+| 阶段 | 做什么 | 不通过的后果 |
+|---|---|---|
+| **正向** | 跑判据 → 期望通过 | 实现有 bug，驳回 |
+| **变异** ★ | 自动改坏被测代码 → 期望判据**报红** | **判据太松，驳回** |
+
+**没有变异阶段，就是在给「测试通过」这个信号不断充值信用，直到它骗一次大的。**
+本仓实证：一条只查前缀的判据在变异测试下仍全绿，是变异把它咬出来的。
+
+配套纪律：判据写「某标识符是否出现在函数体」时**必须先剔除注释再匹配**
+（曾因注释里含 `outputParent` 之类的词导致假绿）。
+
+### 31. 工程的目录与生命周期（一个仓库并行开发）
+
+```
+branch_open
+  └─ <hash>-<name>/ （由 mirror **本地 clone** 派生）
+       ★ hash = H(项目+分支)：**唯一性来源**（同仓库不同分支必不同目录）
+       ★ name = 分支名派生：仅可读性
+       └─ 干活 → 提交 → push → PR
+            └─ 合入（或废弃）
+                 └─ ★ **整个目录删除**（不保留、不归档）
+```
+
+**要点**：
+
+- **合入后直接删目录** —— 用户明确要求；不删则下次同名分支会与残留目录混淆。
+- **一个仓库可并行**：每分支一份独立 clone。
+- **★ 同仓库不同分支必然不同目录**：`<hash>` 含分支（`H(项目+分支)`），hash 是**唯一性来源**；
+  `name` 只做可读性。实测：`feat/alpha` vs `feat/beta` → `b3426c01-feat_alpha` vs `0566c1f5-feat_beta`。
+- **⚠ 慢操作必须异步**：内核把**每次工具调用**硬限制在 **60 秒**（`toolcall.go:62`，
+  硬编码无配置项）。`git clone --mirror` 同步做 ⇒ 工具报超时、**但 mirror 其实已建好**
+  —— 调用方只看到失败、状态却是“做了一半”。正确做法：工具只登记 + 发起后台作业，
+  用状态工具追进度（本插件：`commondev_job_status`）。
+- **为什么不是 worktree / `--reference`**（实测）：worktree 删后有 `.git/worktrees/`
+  残留（需 `prune`）；`--reference` 有 alternates 外部依赖，mirror 被清即损坏。
+  **本地 clone 对象为硬链接** ⇒ 省磁盘、无外部依赖、删掉即彻底。
+- **⚠️ 代价：唯一性闸必须补上**。worktree 天然禁止「同分支双挂」，独立 clone **没有**这条
+  保护（两份 clone 都能在 `feat/x` 上各自 push，直到被拒才知道）。
+  台账必须对「同名且未结（open/review）的分支」建唯一索引，重复 `branch_open`
+  **响亮拒绝**，不静默复用。
+- **并行有前提**：并行的必须是**互不相干的模块**。有依赖的任务（A 改接口、B 用接口）
+  两棵树互不可见，问题会集中到 merge 时爆发 ⇒ **先拆边界再谈并行**。
+- 与内核「子不得比父活得久、无残留」同一条纪律（见第 20 节）。
+
+---
+
+## Notes: 第三部分 hmap 插件开发与部署纪律
+
+> 面向「要改 commondev」或「要写另一个插件」的场景。**所有条目都在本机实测过**，
+> 不是从文档抄的。
+
+### 32. 先搞清三件事，别猜
+
+```bash
+hmapdev version        # 工具链版本 + SDK 模块 + 构建用 Go
+hmapdev sdk current    # 当前活跃 SDK 版本（★ 动手前必看）
+hmapdev sdk list       # 本机已装的所有 SDK 版本
+```
+
+- 核心仓 `/home/program/TrueAgent`（Go module `gitcode.com/JianFeeeee/HomeAgent`）
+- **SDK 仓** `third_party/homeagent-sdk`（独立 git 仓、独立版本号）
+
+### 33. 开工流程
+
+```bash
+hmapdev init <name>              # Go 脚手架（--lua / --type remotedevice 可选）
+cd <name> && vim plugin.go       # 注册工具
+hmapdev debug .                  # 不想装就先跑一遍
+hmapdev build                    # 产出 dist/<name>_bundle.hmap
+```
+
+### 34. ★ 五个必踩的坑（按踩中概率排序）
+
+| # | 坑 | 事实 |
+|---|---|---|
+| 1 | **SDK 版本** | 插件编译时**校验 SDK 能力**，用旧接口的工程直接构建失败，报错形如「当前 SDK 缺少 sdk.InjectOptions.Priority」，并给出两条出路：`hmapdev sdk install <version>` 或 `hmapdev sdk install --from <本地源码>`。**核心仓有新能力但 SDK 未跟上时用 `--from`** |
+| 2 | **`hmapdev build`/`debug` 不支持 `--help`** | 不是打印帮助，而是去读当前目录的 `plg.json` ⇒ 你会看到 `error: read plg.json: no such file or directory`。**这不是故障**。要看 flag 用 `hmapdev --help` |
+| 3 | **产物是 ZIP，不是二进制** | `dist/<name>_bundle.hmap` 是 ZIP（魔数 `PK`），用 `unzip` 解，内含 `plugin.bin.linux.amd64` 等多平台二进制。**生产要的是解包后的单个二进制** `/home/newqqagent/plugins/<name>/plugin.bin`（不是 zip） |
+| 4 | **`plugin.json` 是安装标志** | 生产目录里没有它，插件不会被识别。`plg.json` 是**构建**标志，两者不同 |
+| 5 | **`plg.json` 的 `sdk` 字段必须完整 x.y.z** | 写 `"1.4"` 会被**直接拒绝**（SDK 版本纪律：跟随内核中版本、patch 位恒为 `.0`，一条内核线只有一个 SDK 版本） |
+
+### 35. 注册工具的正确形状
+
+```go
+s.RegisterTool(tp+"mytool", sdk.ToolDef{
+    Name:        tp + "mytool",     // ← Name 必填，放结构体**首位**
+    Description: "……",
+    Parameters:  map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
+    Handler:     h.mytool,
+    NoMemory:    true,               // 声明字段一律放**末尾**
+}, s)
+```
+
+**并发声明**（同一批多个 tool_call 时）：
+
+- `ParallelSafe: true` —— 可并发。**三个条件都满足才可声明**：handler 线程安全 /
+  不与同批工具争抢同一资源（SQLite 写、同一设备、同一输出通道）/ 执行顺序无关。
+- `Serial: true` —— 必须串行，**优先级高于 `ParallelSafe`**。
+- **默认（都不写）= 整批串行**，是保守设计不是遗漏。
+
+⇒ commondev 的**写操作**（凭据增删、台账写、`workdir_prepare`、`pr_open/merge`、
+`agent_send`）**一律 `Serial: true`**；**只读**（list/status）才 `ParallelSafe`。
+
+### 36. ★ 外部插件的能力边界（选外部形态就必须接受）
+
+**公开 SDK 里声明的符号，不等于外部插件拿得到。** 外部插件跑在独立进程里，能力由桥接注入：
+
+| API | 外部插件的实际 | 该用什么 |
+|---|---|---|
+| `Events()` | **恒为 nil**（桥不注入 subscriber） | 桥接运行时按你的声明完成订阅 |
+| `UnregisterOutputChannel` | **静默无效**（只注入 registrar，不注入 unregistrar） | 注销需重载插件 |
+| `PriorityL4` | **被夹到 L3** | 用 L1–L3 |
+| `SocialAPI` 写操作 | 只有 6 个**只读**方法 | 读用 `GetPerson` 等 |
+| `PluginMgr()` | **只有 3 个方法**（`ReloadOne`/`ListLoadedPlugins`/`IsPluginDisabled`） | 就这 3 个 |
+| `resident_agents` 等内核工具 | **调不到**（proc 桥无对应方法） | 由 agent 侧调（见第 3 节） |
+
+> **外部形态的 L4 天花板**：commondev 作为外部插件**永远拿不到 L4**。
+
+> **⚠️ 不要用 `ToolAPI` 去调内核内置工具（如 `resident_agents`）**：`ToolAPI` 是
+> **单例**，per-agent 数据靠「最后注入者」，而创建驻留子也会注入 ⇒ 你可能打到
+> **某个驻留子的表上**。这是内核已自陈的局限，别踩。
+
+**L4 归属表**（这块最容易搞错）：
+
+| agent | 它的"内核" | 谁能产生 L4 |
+|---|---|---|
+| 根 agent | 内核自身 + **内置**插件 | `raiseKernelInterrupt`、WebUI 终止按钮等 |
+| 驻留子 | **父 agent** | 父（父→子消息固定 L4） |
+| **外部插件（如 commondev）** | — | **永远不能**（被夹到 L3） |
+
+⇒ 外部形态下，「立即取消整条分支」只能靠 **L3 打断主管 + 主管下令**。
+
+### 37. 安装与验证
+
+```bash
+# ① 从 bundle 取出本机平台二进制
+unzip -o dist/<name>_bundle.hmap 'plugin.bin.linux.amd64'
+# ② 放进插件目录（<name> 必须与 plg.json 的 name 一致）
+mkdir -p /home/newqqagent/plugins/<name>
+cp plugin.json /home/newqqagent/plugins/<name>/
+cp plugin.bin.linux.amd64 /home/newqqagent/plugins/<name>/plugin.bin
+chmod +x /home/newqqagent/plugins/<name>/plugin.bin
+# ③ 重启并确认工具**真的注册了**
+systemctl restart homeagent.service
+journalctl -u homeagent.service --since "-2 min" | grep "registering tool: <你的工具名>"
+```
+
+**内置 vs 独立**（目录存在 ≠ 有 `plugin.bin`）：
+
+```bash
+for p in webui cmd seq qq; do
+  printf "%-8s " $p
+  ls /home/newqqagent/plugins/$p/plugin.bin >/dev/null 2>&1 \
+    && echo "独立（要单独构建部署）" || echo "内置（随 homed 部署）"
+done
+```
+
+★ **改了内置插件的源码 ⇒ 必须重新构建并部署 homed**，重启服务不生效（`//go:embed` 编进二进制）。
+★ 判断线上跑的是哪次构建，看 `commit` 字段（**不要用 `strings`**）：
+
+```bash
+K=$(sqlite3 /home/newqqagent/config.db "select value from config_webui where key='api_key';")
+curl -s -H "X-API-Key: $K" http://127.0.0.1:8080/api/v1/status | grep -oE '"commit":"[^"]*"'
+```
+
+⚠ 必须带 `X-API-Key`：无认证时返回 **200 + 登录页 HTML**，只看状态码会误判。
+
+### 38. 排查「插件装了却不生效」
+
+按顺序查，**别跳步**：
+
+```bash
+ls /home/newqqagent/plugins/<name>/plugin.bin          # 1) 内置还是独立
+journalctl -u homeagent.service --since "-5 min" | grep "registering tool:" | grep -i <name>   # 2) 注册了吗
+journalctl -u homeagent.service --since "-5 min" | grep -E "loaded: <name>"                    # 3) 加载了吗
+journalctl -u homeagent.service --since "-5 min" | grep -iE "<name>.*(error|panic|failed)"     # 4) 启动报错
+```
+
+### 39. ★ 安全纪律（commondev 拿的是**能 push 用户所有仓库**的权限）
+
+> **★ 架构决定（用户拍板 2026-10-14）：敏感信息拦截下沉为内核安全模块。**
+>
+> 理由：**LLM 调用本身不可信**，而插件在**信任边界之外** ——
+> 插件注册的 stage 拦截是“自愿的”，不是强制的，也算不上边界。
+>
+> ★ **它不是单纯拦截，而是一个闭环**（用户纠正：“只是简单的拦截的话，
+> 绝大部分插件会失去原本的功能”）：
+>
+> ```
+> ① 拦截      LLM 出向前扫到明文 → 换成 @{别名}
+> ② 加密暫存  明文 AES-GCM **落盘**存内核（不落明文）
+> ③ 别名      ★ **哈希键**：sec_ + HMAC-SHA256(masterKey, plain)[:8]
+>               ⇒ **同一明文自动得同一个别名**（同变量合并，天然性质）
+>               ⇒ 必须 HMAC 而非裸哈希（裸哈希可字典枚举）；**不加 salt**（否则失去合并）
+> ④ 回填      插件调用前把 @{别名} 换回明文 ← 插件无感知
+> ```
+>
+> ★ **变量不自动淘汰**（跨轮/跨子 agent 随时要用）；agent 可**主动**调用
+> 安全模块提供的**提交/删除**工具。泄漏风险靠主动删控制，不靠超时。
+>
+> ★ **因为内核零 IO（一切外部交互都从插件走），只需两根咽喉**：
+> · 入向 toolcall：`StageHost.ExecuteTool(name, args)`（`core/stages.go:140`）
+> · 入向 outputch：设备 `Execute`（`core/output.go:76`）
+> · 出向 LLM：provider 层的 `Chat(req)`（已核：构造 `CompletionRequest` 有 **7 处**，
+>   task 层拦不全）
+>
+> ★ **变量系统是全局唯一的**（用户拍板）：主 agent / 子 agent / 驻留子 agent
+> **同一套**别名表。已核依据：驻留子共享父的 `ProviderManager`（`resident.go:185`），
+> 而它**全进程只建一份**（`bootstrap.go:249`）⇒ 安全模块天然是进程级单例，
+> **不需要跨 agent 同步**。
+> ⚠ **变量共享 ≠ 授权共享**：能不能调某工具/通道仍看该 agent 自己的 `AllowedOutputs`
+> （与 `KernelSource` 一道是 per-agent 的）。两者**正交**。
+>
+> ★ **“插件无感知”是硬要求**：替换发生在路由到插件的**之前**；
+> 插件代码一行不改、不可分辨、无法绕过 ⇒ 存量插件自动获得该能力，
+> 且无需给 SDK 加参数（不破接口兼容）。
+>
+> **对本插件的直接影响（大幅简化）**：插件可以**把密钥明文直接投给 LLM**，
+> 由内核安全模块全权负责；`enc_*` 工具族与加密 shell 应**删减**，
+> 不再自带加密库/别名表（前稿那套作废）。
+>
+> 详见 `docs/zh/kernel-secret-firewall-design.md`（含硬约束 S1–S9）。
+>
+> **两条不可让步的约束**：
+> · **只能替代引用，永远不可取回明文**（用户明确）—— 读接口与用接口是两件事；
+> · **模式库宁漏勿误伤** —— 误报会搞坏正常任务。
+
+**凭据：按名字引用 + 变量填充**（用户明确要求的能力）
+
+```
+enc_store(alias="gitea-token", value="${GITEA_TOKEN}")   ← ★ 引用，不是明文
+enc_list                                                  ← 只列名字，**绝不返回值**
+```
+
+之后一切操作只带**别名**：`@{gitea-token}` —— 参数里永远不出现 secret。
+详见 **第二部分 §13**（那里是权威）。
+
+**为何要 `${ENV_VAR}` 变量填充**：（①）明文不落盘；（②）dev/prod 换环境变量即可；
+（③）轮换凭据不需改插件数据。
+
+#### ★★ 判据与复核：**插件 GREEN ≠ 改对了**
+
+**这是本流水线最重要的一条纪律。** 插件只能跑你**预先写下**的判据；
+判据没覆盖那条 bug，插件照样打勾。自动化**不会**发现假绿，
+只会让假绿跑得更快、更可信。
+
+**真实数据**（我用最小例子复刻过）：
+
+```go
+func Max(a,b int) int { if a>b { return a }; return b }
+```
+- 判据只测 `Max(5,3) == 5`（漏了 `b>a`）
+- 变异 `return b` → `return a`（**真 bug**）⇒ **判据仍全绿**
+- 补一条 `Max(3,5) == 5` ⇒ 同一变异**立刻报红**
+
+⇒ 所以**复核必须两步**，你定义判据时**必须同时给变异规则**：
+
+```
+commondev_test_define(
+  project="MyProj", name="clamp 上下界", kind="unit",
+  script="go test -count=1 ./...",
+  expect="上下界都被限制",
+  mutations=[{ id="M1", file="calc.go",
+               old="	if v > hi {\n		return hi\n	}\n", new="",
+               note="删掉上界分支（真 bug）——松判据看不见它" }]
+)
+commondev_review_submit(branch_id="br-...")
+commondev_review_result()          ← 取结论
+```
+
+**结论三档，注意第二档不是"通过"**：
+
+| verdict | 含义 | 你该做什么 |
+|---|---|---|
+| `pass` | 正向全过 **且**全部变异被咬住 | 可以进下一步 |
+| **`pass_with_gaps`** | 正向过，但**有变异没被咬住**或**判据没变异规则** | **不能当通过** —— 去补判据/变异，再复核 |
+| `fail` | 有判据没过 | 打回执行 agent |
+
+★ **`pass_with_gaps` 就是"你的判据有盲区"**。把它当绿色勾，
+就是在给自己攒一次大的意外。
+
+**定义变异规则的三个要点**：
+
+1. **`old` 必须在文件里恰好出现一次** ——
+   出现 0 次 ⇒ 变异无效（却会被误报成"判据太松"）；
+   出现多次 ⇒ 可能改错地方（却会被误报成"咬住了"）。
+   多出现时给出更长的上下文。
+2. **变异要"真坏"** —— 改的是逻辑，不是格式。改不坏就验不出判据的松紧。
+3. **`script` 里带 `-count=1`** —— Go 默认缓存测试结果；
+   命中缓存时测试**根本没跑**，"变异后报红"就无从谈起。
+
+#### 双凭据与分支保护：**已移到第二部分**（技能纪律 §15–§16）
+
+原来这里用 `commondev_account_add(role=...)` + `commondev_protect_branch` 两个
+插件工具实现。**这些工具已移除**（平台知识不再进插件）。
+
+现在这样做（命令见 **第二部分 §15**）：
+
+1. **在平台上建两个用户**：一个普通用户（执行侧，只能 push `feat/*`）、
+   一个有管理权限的（主管侧，能审批与合并）。各自签发 token。
+2. **两个 token 都存进凭据库**：`enc_store(alias="gitea-exec", ...)` /
+   `enc_store(alias="gitea-sup", ...)`。
+3. **给主干上锁**（第二部分 §15 的 curl 命令，四个开关都要）。
+4. 审批与合并用主管侧别名（§16）。
+
+★ **执行侧必须用普通用户 token** —— 用 admin token 会**直接绕过分支保护**，
+机制失效且无任何报错。这是最容易搞错的一点。
+
+★ **拦你的是平台，不是插件** —— 所以改插件代码也绕不过去。
+这才是「机制」与「流程约定」的区别。
+
+**两条不可逆的红线**：
+
+1. **变量解析不到值 ⇒ 响亮报错**，绝不静默当空串 —— 后者会退化成匿名访问，
+   表现成 **401** 而非“凭据没配”，极难排查。
+2. **secret 绝不进返回值/日志**。
+
+**平台形状差异**（不能一个认证头走天下）：
+
+| 平台 | API 前缀 | 认证头 |
+|---|---|---|
+| Gitea | `<base>/api/v1` | `Authorization: token <T>` ← **不是 Bearer** |
+| GitHub | `https://api.github.com` | `Authorization: Bearer <T>` |
+| GitCode | `https://api.gitcode.com/api/v5` | `Authorization: Bearer <T>` |
+
+未知平台**必须报错**（不猜形状）。
+
+**其他：**
+
+1. **凭据不入 `config.db`**：现有惯例是明文存 `config_<plugin>` 表，而 `config.db` 是
+   **644 全局可读**。commondev 的凭据性质完全不同 ⇒ 放独立文件
+   `<DataDir>/credentials.json`，**0600，启动时校验权限，不对就拒绝启动**
+   （本仓纪律：响亮失败，不静默降级）。
+2. **优先 SSH key 而非 PAT**；每平台独立、最小授权，**不要一个 token 通吃**。
+3. **token 不进 remote URL**：拼接仅用于**单次命令**（`pushURLWithToken`），
+   clone 出来的 remote 不带凭据 —— 否则删掉临时目录也删不掉凭据。
+4. **不要硬编码 token**：走 `Settings()` 或宿主注入。
+5. **拉起 pi 时隔离端口**：内层 pi 会尝试监听 A2A/ACP 端口并打 `EADDRINUSE`，
+   显式设 `PI_CODING_AGENT_SESSION_DIR` / `PI_A2A_PORT` / `PI_ACP_PORT`。
+
+### 40. ★ 孤儿清理（插件有自己的硬约束）
+
+内核对自己的驻留子有硬约束：**子不得比父活得久 / 无孤儿 goroutine / 无残留 temp**
+（`resident-subagent-design.md` §10，写成判据）。
+
+**插件对自己拉起的进程必须同样硬**：`Stop()` 必须是**幂等的全清** ——
+pi 进程、sidecar、ssh 会话、workdir（含凭据残留检查）一个不留。
+写成判据：`TestStopKillsAllRuntimes`（变异：删掉某个清理 → 必须报红）。
+
+### 41. 参考资料（**别凭记忆写 API**）
+
+| 内容 | 路径 |
+|---|---|
+| SDK 源码 | `third_party/homeagent-sdk/sdk/` |
+| **可运行的示例插件** | `third_party/homeagent-sdk/example/`（a2a / acp / qq / plugindev…） |
+| 能力边界 | `third_party/homeagent-sdk/docs/guide/capability-boundary.md` |
+| 并发声明 | `third_party/homeagent-sdk/docs/guide/parallel-tool-declaration.md` |
+| 部署手册 | `docs/zh/deploy-runbook.md` |
+| sidecar 参考实现 | `internal/plugins/clawhubadapter/sidecar.go` |
+
+★ **写插件前先翻 `example/`**：那里的代码是**编译通过**的，比文档可靠。
+**文档与示例冲突时以示例为准。** 注意 `example/` 是**外部插件**，
+能被它们编译通过的写法，外部就一定可用。
+
+---
+
+## Notes: 红牌（做了就是错）
+
+1. **不划通道就当派了活** —— 登记 ≠ 划入；不划则所有输入涌向根 agent。
+2. **绕过插件直接敲 `pi -p`** —— 漏 `--session-id` 会静默开新会话。
+3. **并发投同一个 session** —— 会写坏会话（实测）。
+4. **没有变异阶段的复核** —— 等于给假绿充值。
+5. **凭据写进 `config.db` 或 remote URL**。
+6. **改了内置插件源码只重启服务** —— 必须重编 homed。
+7. **手改生成的文档**（`docs/api/*.md` 首行写着「请勿手改」）—— 改 `sdk/*.go` 注释再重新生成。
+8. **为了让插件生效去改 homed 的源码** —— 先确认它是不是内置插件。
diff --git a/assets/skills/commondev-discipline/skill.json b/assets/skills/commondev-discipline/skill.json
new file mode 100644
index 00000000..362a271c
--- /dev/null
+++ b/assets/skills/commondev-discipline/skill.json
@@ -0,0 +1,6 @@
+{
+  "name": "commondev-discipline",
+  "description": "commondev 主管式多仓库开发流水线的使用与开发纪律：为每个工程对话新建驻留子并划入其通道、投递必须落同一 session、复核必须含变异阶段；以及 hmap 插件开发纪律（plg.json、SDK 版本、产物形态、Serial/ParallelSafe、外部插件能力边界、凭据与孤儿清理）",
+  "version": "1.0.0",
+  "author": "HomeAgent"
+}
diff --git a/cmd/homed-centroid/main.go b/cmd/homed-centroid/main.go
index ecebc2b6..bef225b1 100644
--- a/cmd/homed-centroid/main.go
+++ b/cmd/homed-centroid/main.go
@@ -11,8 +11,9 @@
 //   - 库增长后中心过期（中心是块集的均值，块集变了它就偏）
 //
 // 用法：
-//   homed-centroid -db <graph.db>                      # 自动取库内指纹
-//   homed-centroid -db <graph.db> -fingerprint <hex>   # 显式指定
+//
+//	homed-centroid -db <graph.db>                      # 自动取库内指纹
+//	homed-centroid -db <graph.db> -fingerprint <hex>   # 显式指定
 package main
 
 import (
@@ -66,4 +67,4 @@ func main() {
 	if !anomalous {
 		fmt.Println("  （各向异性不显著，召回不会做中心化；中心已存备用）")
 	}
-}
\ No newline at end of file
+}
diff --git a/cmd/homed-depgraph/main.go b/cmd/homed-depgraph/main.go
new file mode 100644
index 00000000..3da7e9af
--- /dev/null
+++ b/cmd/homed-depgraph/main.go
@@ -0,0 +1,142 @@
+// homed-depgraph 产出内核模块的**启动依赖图制品**（设计 §2.5）。
+//
+// ## 用户的设计（原话）
+//
+// > 启动顺序是编译期间按照声明的依赖顺序生成的启动依赖图排列的
+//
+// 本工具就是那个"编译期生成器"：
+//
+//	① import 模块登记表（internal/kernelmod/all ⇒ 各模块 init 自注册）
+//	② 用各模块**自己的** Requires()/Provides() 算分层（BFS）
+//	③ 把【模块 + 边 + 层号】编成 depsgraph.bin，并输出 digest
+//
+// 运行期内核**读**这份图即可（不再自己算顺序）。
+//
+// ## 用法
+//
+//	homed-depgraph -out <homed 目录>/depgraph.bin   # 产出制品
+//	homed-depgraph -print                           # 只打印计划（评审用）
+//	homed-depgraph -digest                          # 只输出 digest（供 -ldflags 注入）
+//
+// ## ★ 拒绝产出空图 / 无解图
+//
+// 空图会让内核认为"没有依赖" ⇒ 按一个**错误的计划**启动 —— 比报错危险得多。
+// 依赖图无解（缺依赖/环/重名）时也拒绝产出：那是结构性错误，
+// 应在编译期就报出来，而不是留给运行期。
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+
+	// ★ 把全部内核模块**引入编译** —— 这就是"编译期收集各模块声明"的落点。
+	// 各模块在自己的 init() 里 kernelmod.Register(...)。
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/all"
+)
+
+func main() {
+	out := flag.String("out", "", "输出路径（默认 <二进制目录>/depgraph.bin）")
+	printPlan := flag.Bool("print", false, "打印启动计划（不落盘）")
+	digestOnly := flag.Bool("digest", false, "只输出 digest（供 -ldflags 注入）")
+	flag.Parse()
+
+	if d := kernelmod.Duplicates(); len(d) > 0 {
+		fmt.Fprintf(os.Stderr, "homed-depgraph: 模块名重复注册: %v\n", d)
+		os.Exit(1)
+	}
+	mods := kernelmod.Registered()
+	if len(mods) == 0 {
+		fmt.Fprintln(os.Stderr,
+			"homed-depgraph: 没有任何模块被登记 —— 拒绝产出空图。\n"+
+				"空图会让内核认为'没有依赖'，从而按一个**错误的计划**启动。\n"+
+				"检查 internal/kernelmod/all 是否 import 了各模块包。")
+		os.Exit(2)
+	}
+
+	// ★ 编译期就算出分层 —— 这是"顺序由编译期决定"的落点。
+	plan, err := kernelboot.Build(mods)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "homed-depgraph: ★ 依赖图无解，拒绝产出制品:\n%v\n", err)
+		os.Exit(1)
+	}
+
+	edges := planToEdges(plan)
+	if *printPlan {
+		fmt.Print(renderPlan(plan))
+	}
+	if *digestOnly {
+		fmt.Println(kernelboot.GraphDigest(edges))
+		return
+	}
+
+	data := kernelboot.EncodeGraph(edges)
+	path := *out
+	if path == "" {
+		exe, err := os.Executable()
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "homed-depgraph: 无法确定输出目录: %v\n", err)
+			os.Exit(1)
+		}
+		path = filepath.Join(filepath.Dir(exe), kernelboot.GraphFileName)
+	}
+	// 写临时文件再 rename：避免半截文件被读到
+	//（自校验也能拦住截断，但原子替换能避免"那一刻读到坏图"的噪音）。
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, data, 0o644); err != nil {
+		fmt.Fprintf(os.Stderr, "homed-depgraph: 写 %s: %v\n", tmp, err)
+		os.Exit(1)
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		fmt.Fprintf(os.Stderr, "homed-depgraph: 替换 %s: %v\n", path, err)
+		os.Exit(1)
+	}
+	fmt.Printf("已产出启动依赖图: %s（%d 个模块，%d 层）\n", path, len(edges), len(plan.Layers))
+	fmt.Printf("digest（注入 -ldflags -X ...EmbeddedGraphHash=%s）\n",
+		kernelboot.GraphDigest(edges))
+}
+
+// planToEdges 把分层计划转成图记录（含**编译期算好的层号**）。
+func planToEdges(plan *kernelboot.Plan) []kernelboot.GraphEdge {
+	var out []kernelboot.GraphEdge
+	for layer, mods := range plan.Layers {
+		for _, m := range mods {
+			out = append(out, kernelboot.GraphEdge{
+				Name:     m.Name(),
+				Provides: m.Provides(),
+				Requires: m.Requires(),
+				Layer:    layer, // ★ 编译期定序
+			})
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Layer != out[j].Layer {
+			return out[i].Layer < out[j].Layer
+		}
+		return out[i].Name < out[j].Name
+	})
+	return out
+}
+
+// renderPlan 把分层计划渲染成**给人看**的文本（供 -print）。
+//
+// 格式刻意稳定：它会进 PR / 运维记录，因此同一份声明必须渲染出逐字相同的结果。
+func renderPlan(plan *kernelboot.Plan) string {
+	var b strings.Builder
+	b.WriteString("内核模块启动计划（编译期由依赖声明算出，BFS 分层，同层并行）:\n")
+	for i, layer := range plan.Layers {
+		names := make([]string, 0, len(layer))
+		for _, m := range layer {
+			names = append(names, m.Name())
+		}
+		sort.Strings(names)
+		fmt.Fprintf(&b, "  第 %d 层（%d 个，可并行）: %s\n", i, len(names), strings.Join(names, ", "))
+	}
+	return b.String()
+}
diff --git a/cmd/homed-key-rotate/main.go b/cmd/homed-key-rotate/main.go
new file mode 100644
index 00000000..e275c6da
--- /dev/null
+++ b/cmd/homed-key-rotate/main.go
@@ -0,0 +1,135 @@
+// homed-key-rotate：主密钥轮换（E-1）。
+//
+// ## 为何必须有这个命令
+//
+// `security` 包里的 `RotateKey` / `RotateKeyFile` / `RekeySecrets` 只是**零件**。
+// 没有一条可执行的路径把它们串起来，E-1 就只是库里的能力，而不是
+// 运维真能做的事 —— 而轮换的价值恰恰在于「出事时能执行」。
+//
+// ## 做三件事，顺序不可换
+//
+//	① 重加密变量库（security/variables.json）→ 新钥
+//	② 写 security.keyring（旧钥降为只读历史）
+//	③ 重加密 config.db 里的密文
+//
+// ★ 为什么必须「先重加密、后写 keyring」：
+// 反过来的话，进程在中间崩溃会留下「keyring 说当前是新钥，但数据还是旧钥密文」
+// 的状态 —— 而旧钥已不在环里可自动恢复，等于数据全丢。
+//
+// ## 用法
+//
+//	homed-key-rotate -data /var/lib/homeagent -new-key <64位hex>
+//	homed-key-rotate -data /var/lib/homeagent -gen   # 生成一把新钥并打印
+//
+// 轮换后**必须重启 homed**（密钥在启动时装配）。
+package main
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/JianFeeeee/HomeAgent/internal/config"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+func main() {
+	dataDir := flag.String("data", "", "数据目录（config.db 所在处）")
+	newKeyHex := flag.String("new-key", "", "新主密钥（64 位 hex）；与 -gen 二选一")
+	gen := flag.Bool("gen", false, "生成一把新主密钥并打印（不执行轮换）")
+	flag.Parse()
+
+	if *gen {
+		k := make([]byte, 32)
+		if _, err := rand.Read(k); err != nil {
+			fail("生成密钥失败: %v", err)
+		}
+		fmt.Println(hex.EncodeToString(k))
+		return
+	}
+	if *dataDir == "" || *newKeyHex == "" {
+		fail("必须给 -data 与 -new-key（或 -gen 生成一个）")
+	}
+
+	// ① 先取当前钥（走与 homed 完全相同的优先级，避免拿错钥）
+	oldKey, src, err := security.LoadOrCreateKey(*dataDir)
+	if err != nil {
+		fail("读取当前主密钥失败: %v", err)
+	}
+	newKey, err := hex.DecodeString(*newKeyHex)
+	if err != nil || len(newKey) != 32 {
+		fail("-new-key 必须是 64 位 hex（32 字节）")
+	}
+	if string(newKey) == string(oldKey) {
+		fail("新钥与当前钥相同，无需轮换")
+	}
+	history, err := security.LoadKeyring(*dataDir, oldKey)
+	if err != nil {
+		fail("读取密钥环失败: %v", err)
+	}
+	fmt.Printf("当前密钥来源: %s（历史密钥 %d 把）\n", src, len(history))
+
+	// ② 重加密变量库
+	st := security.New(security.Options{
+		Path:    filepath.Join(*dataDir, "security", "variables.json"),
+		KeyFn:   func() ([]byte, error) { return oldKey, nil },
+		OldKeys: history,
+		Enabled: true,
+	})
+	if err := st.Load(); err != nil {
+		fail("加载变量库失败（不静默重建）: %v", err)
+	}
+	n := st.Count()
+	if err := st.RotateKey(newKey); err != nil {
+		fail("变量库轮换失败（数据未改动）: %v", err)
+	}
+	fmt.Printf("① 变量库已重加密（%d 条）\n", n)
+
+	// ③ 写 keyring（旧钥转为只读历史）。放在数据重加密之后 —— 见文件头说明。
+	if err := security.RotateKeyFile(*dataDir, oldKey, newKey); err != nil {
+		fail("写密钥环失败（变量库已是新钥，此时不可回退）: %v", err)
+	}
+	fmt.Printf("② 密钥环已更新（%s）\n", filepath.Join(*dataDir, security.KeyringFileName))
+	// 当前钥来源若是开发/磁盘路径，必须同步替换 security.key；否则下次启动
+	// LoadOrCreateKey 仍读旧钥，而 keyring current 已是新钥，会按设计响亮拒绝启动。
+	// systemd credential/env 不能由此命令擅自改：必须由运维更新注入源。
+	if src == filepath.Join(*dataDir, security.KeyFileName) {
+		path := filepath.Join(*dataDir, security.KeyFileName)
+		tmp := path + ".tmp"
+		if err := os.WriteFile(tmp, []byte(hex.EncodeToString(newKey)), 0o600); err != nil {
+			fail("更新磁盘主密钥失败: %v", err)
+		}
+		if err := os.Chmod(tmp, 0o600); err != nil {
+			fail("确权新主密钥失败: %v", err)
+		}
+		if err := os.Rename(tmp, path); err != nil {
+			fail("替换磁盘主密钥失败: %v", err)
+		}
+		fmt.Printf("③ 磁盘主密钥已替换（%s）\n", path)
+	} else {
+		fmt.Printf("③ 当前钥来自 %s：请先更新该注入源为新钥，再重启 homed\n", src)
+	}
+	if _, err := security.InitConfigCodecWithOldKeys(newKey, append([][]byte{oldKey}, history...)); err != nil {
+		fail("装配新配置 codec 失败: %v", err)
+	}
+	reg := config.NewConfigRegistry(filepath.Join(*dataDir, "config.db"))
+	defer reg.Close()
+	rekeyed, failed, err := reg.RekeySecrets()
+	if err != nil {
+		fail("config.db 重加密失败: %v", err)
+	}
+	fmt.Printf("③ config.db 已重加密 %d 条（失败 %d 条）\n", rekeyed, failed)
+	if failed > 0 {
+		fmt.Fprintf(os.Stderr, "⚠ 有 %d 条密文用新旧钥都解不开 —— 那说明它们来自更早的密钥，\n"+
+			"  请检查 security.keyring 的 history 是否完整（不要在此状态下删除旧钥）\n", failed)
+	}
+	fmt.Println("\n完成。请重启 homed 以使新密钥生效：systemctl restart homeagent.service")
+}
+
+func fail(format string, args ...interface{}) {
+	fmt.Fprintf(os.Stderr, "错误: "+format+"\n", args...)
+	os.Exit(1)
+}
diff --git a/cmd/homed-media-backfill/main.go b/cmd/homed-media-backfill/main.go
index 3875614e..3172b550 100644
--- a/cmd/homed-media-backfill/main.go
+++ b/cmd/homed-media-backfill/main.go
@@ -7,8 +7,9 @@
 // 把字节搬进块，否则 CAS 目录一删，BlockData 就取不到字节（图永久丢失）。
 //
 // ★ 本命令**不 import internal/memory/media**：那个包正是要删掉的。
-//   迁移工具只读**冻结的历史格式**：blobs/<digest[:2]>/<digest[2:]>。
-//   依赖待删代码的迁移工具会在删包那一刻失效 —— 迁移必须比被迁移的东西活得久。
+//
+//	迁移工具只读**冻结的历史格式**：blobs/<digest[:2]>/<digest[2:]>。
+//	依赖待删代码的迁移工具会在删包那一刻失效 —— 迁移必须比被迁移的东西活得久。
 //
 // 存量事实（生产 /home/newqqagent/memory）：
 //   - graph.db 有 112 个媒体块，引 106 个唯一 digest
diff --git a/cmd/homed/bootstrap.go b/cmd/homed/bootstrap.go
index 6b2fc1a6..ba6972d6 100644
--- a/cmd/homed/bootstrap.go
+++ b/cmd/homed/bootstrap.go
@@ -13,71 +13,21 @@ import (
 	"syscall"
 	"time"
 
-	agentPkg "github.com/JianFeeeee/HomeAgent/internal/agent"
-	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
 	agentCore "github.com/JianFeeeee/HomeAgent/internal/agent/core"
-	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
 	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
-	"github.com/JianFeeeee/HomeAgent/internal/events"
 	"github.com/JianFeeeee/HomeAgent/internal/ipc"
-	"github.com/JianFeeeee/HomeAgent/internal/knowledge"
 	logpkg "github.com/JianFeeeee/HomeAgent/internal/log"
-	luapkg "github.com/JianFeeeee/HomeAgent/internal/lua"
 	"github.com/JianFeeeee/HomeAgent/internal/memory"
-	"github.com/JianFeeeee/HomeAgent/internal/memory/distill"
-	"github.com/JianFeeeee/HomeAgent/internal/memory/document"
 	"github.com/JianFeeeee/HomeAgent/internal/memory/pipeline"
 	"github.com/JianFeeeee/HomeAgent/internal/memory/social"
-	"github.com/JianFeeeee/HomeAgent/internal/memory/text"
-	"github.com/JianFeeeee/HomeAgent/internal/memory/vector"
-	"github.com/JianFeeeee/HomeAgent/internal/nlp"
 	"github.com/JianFeeeee/HomeAgent/internal/plugin"
 	"github.com/JianFeeeee/HomeAgent/internal/recovery"
-	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"github.com/JianFeeeee/HomeAgent/internal/supervisor"
 	"github.com/JianFeeeee/HomeAgent/internal/tracker"
-	"github.com/JianFeeeee/HomeAgent/pkg/embedding"
-	"github.com/JianFeeeee/HomeAgent/pkg/generation"
 	"github.com/JianFeeeee/HomeAgent/pkg/types"
 )
 
-// defaultSystemPrompt 是内置默认人格模板：不含版本号字面量，
-// 被问版本时以运行时快照为准（历史上写死版本号导致实例自称旧版本）。
-const defaultSystemPrompt = `你是 HomeAgent，一个持续运行的个人管家。
-你的每次回复会自动发送到当前输出通道（默认=输入源），无需额外工具。
-如需切换回复通道，使用 output_set_channel。
-如需异步发送消息或通知，使用 output_send 指定通道和内容。
-使用 output_list_channels 查看可用通道及其能力。
-
-可用工具列表会由系统自动传入，按需使用即可。以下是你尤其需要关注的几类工具：
-- memory_* — 图记忆（长期记忆，记录和查询个人信息/事实）
-- knowledge_* — 知识库（查阅预设知识文档）
-- doc_* — 文档记忆（近期对话的存档，查询后自动清除）
-- person_* — 人物特质与社交关系网
-- llm_* — LLM 源管理（列出/切换模型提供商）
-- output_* — 输出通道管理（切换/发送消息）
-- timer_set — 设置定时提醒
-- plgreload — 热重载插件
-- spawn_child — 生成子 Agent 异步执行独立任务（可传 max_turns 控制工具轮数，默认 5）
-
-并行策略：遇到多个互不依赖的子任务时，优先并行 spawn 多个子 Agent 而非自己串行逐个执行；
-长耗时任务（批量处理、多轮搜索汇总）也应交给子 Agent，避免阻塞当前对话。
-- describe_image — 描述用户上传的图片
-- transcribe_audio — 转写用户上传的音频
-- ocr_image — 识别图片中的文字
-
-命令与文件操作策略：
-- cmd_run 经完整 shell（bash）执行，支持管道、分号、&&、命令替换、heredoc、重定向。
-- 多步交互式程序（vim/top/ssh 会话、需要持续输入的进程）用 terminal_create 创建终端，
-  terminal_write 发送输入、terminal_read 读输出——不要用 cmd_run 硬等交互程序退出。
-- 写文件优先 files_write（原子+留档），生成多行内容时可用 heredoc 或 files_write，
-  不要用 echo 拼接长文本。
-- 读用户发来的文件用 files_read；向 webui 回传图片/文件用 output_send__webui(type=image/file)。
-
-当用户上传图片或音频时，系统会自动附着媒体内容。如果模型不支持直接处理多媒体，请使用上述工具。
-
-回复你的真实想法，用自然语言与用户交流。不要在回复中使用 emoji 表情。`
-
 // setupLogging 初始化日志：行号前缀 + 同时输出到控制台与 <data>/log/ 下的本次启动文件。
 //
 // 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
@@ -136,564 +86,6 @@ type memoryStack struct {
 	distiller *pipeline.Distiller
 }
 
-// initMemoryStack 初始化图记忆 / 索引 / 社交图 / 蒸馏管线。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func initMemoryStack(dataDir string, cfgReg *internalConfig.ConfigRegistry) (*memoryStack, func()) {
-	memDB, err := memory.NewGraphDB(filepath.Join(dataDir, "memory", "graph.db"))
-	if err != nil {
-		log.Printf("[homed] warning: memory init failed: %v", err)
-		memDB = nil
-	} else {
-		log.Printf("[homed] graph memory initialized")
-	}
-	memIdx := memory.NewIndexer(memDB)
-	memIdx.Sync() // 启动时立即同步，避免前30分钟空窗
-	socialStore := social.New(memDB)
-
-	distiller := pipeline.NewDistiller(memDB, dataDir, pipeline.DistillerConfig{
-		Interval:      10 * time.Minute,
-		RetentionDays: 7,
-		BatchSize:     50,
-	})
-	// ★ 必须在 distiller.Start() **之前**注入：Start 会起 distillLoop，
-	// 而第一次 tick 在 Interval 之后。若先 Start 再注入，头一个周期
-	// （实测配置 10 分钟）会白跑一次 jieba 路 —— 而那条路实测产出 0 条。
-	if memDB != nil {
-		distiller.SetSplitter(initDistillSplitter(cfgReg))
-	}
-
-	if memDB != nil {
-		// 这里**故意不写 defer distiller.Stop()**：本函数在 return 时即触发
-		// defer，而 Stop() → cancel() 会让刚启动的 distillLoop 立刻退出，
-		// 规则蒸馏管线启动即死、10min 心跳从不运行（旧 main() 拆分时的残留）。
-		// 停机由调用点注册的 cleanup 负责（见下方返回值）。
-		distiller.Start()
-	}
-
-	return &memoryStack{db: memDB, indexer: memIdx, social: socialStore, distiller: distiller},
-		func() {
-			// 与原 main 的两个 defer 同序（LIFO）：先停蒸馏器，再关图库。
-			if memDB != nil {
-				distiller.Stop()
-			}
-			if memDB != nil {
-				memDB.Close()
-			}
-		}
-}
-
-// startMemoryCandidateConsumer 起一个常驻 goroutine：把 eventbus 上的 memory_candidate 事件写进文本记忆并喂给蒸馏管线。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func startMemoryCandidateConsumer(ctx context.Context, iom *agentIO.IOManager, textMem *text.Memory, memDB *memory.GraphDB, distiller *pipeline.Distiller) {
-	go func() {
-		for {
-			select {
-			case <-ctx.Done():
-				return
-			case evt, ok := <-iom.OutputChan():
-				if !ok {
-					return
-				}
-				if evt.Target == "memory" && evt.Type == "memory_candidate" {
-					source, _ := evt.Payload["source"].(string)
-					input, _ := evt.Payload["input"].(string)
-					response, _ := evt.Payload["response"].(string)
-					toolsUsed, _ := evt.Payload["tools_used"].([]string)
-					toolResults, _ := evt.Payload["tool_results"].([]interface{})
-					agentID, _ := evt.Payload["agent_id"].(string)
-
-					if input != "" && textMem != nil {
-						te := text.Event{
-							Timestamp: time.Now().Unix(),
-							Source:    source,
-							Input:     input,
-							Response:  response,
-							ToolsUsed: toolsUsed,
-							AgentID:   agentID,
-						}
-						if err := textMem.Append(te); err != nil {
-							log.Printf("[homed] text memory append: %v", err)
-						}
-					}
-
-					if input != "" && memDB != nil {
-						distiller.Append("agent", "user", input)
-					}
-					if response != "" && memDB != nil {
-						distiller.Append("agent", "assistant", response)
-					}
-
-					// 工具输出接入蒸馏管线
-					for _, tr := range toolResults {
-						if trMap, ok := tr.(map[string]interface{}); ok {
-							if text, ok := trMap["output"].(string); ok && text != "" && memDB != nil {
-								distiller.Append("agent", "tool", text)
-							}
-						}
-					}
-				}
-			}
-		}
-	}()
-}
-
-// initLLMProviders 按配置注册全部 LLM 源（每个源经 Lua 适配器协议转换），并把各适配器的并发额度汇总回 Lua VM。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func initLLMProviders(cfg *types.Config, luaVM *luapkg.VM, baseAPIKey string) *agentAPI.ProviderManager {
-	providerMgr := agentAPI.NewProviderManager()
-	adapterConcurrency := map[string]int{}
-	for _, src := range cfg.LLM.Sources {
-		if !agentAPI.IsValidSourceConfig(src.Name, src.BaseURL, src.Model, src.Adapter) {
-			log.Printf("[homed] skip invalid llm source %q (base_url=%q model=%q adapter=%q)", src.Name, src.BaseURL, src.Model, src.Adapter)
-			continue
-		}
-		key := src.APIKey
-		if key == "" {
-			key = baseAPIKey
-		}
-		luaProvider := agentAPI.NewLuaAdaptedProvider(agentAPI.BaseConfig{
-			Model:         src.Model,
-			BaseURL:       src.BaseURL,
-			APIKey:        key,
-			Temperature:   cfg.LLM.Temperature,
-			MaxTokens:     cfg.LLM.MaxTokens,
-			ContextWindow: src.ContextWindow,
-			MaxConcurrent: src.MaxConcurrent,
-			Priority:      src.Priority,
-			Vision:        src.Vision,
-			Audio:         src.Audio,
-		}, luaVM, src.Name, src.Adapter)
-		providerMgr.Register(src.Name, luaProvider)
-		if src.Adapter != "" {
-			adapterConcurrency[src.Adapter] += src.MaxConcurrent
-		}
-	}
-	luaVM.ConfigureConcurrency(adapterConcurrency)
-	if cfg.LLM.Provider != "" {
-		providerMgr.SetDefault(cfg.LLM.Provider)
-	}
-
-	return providerMgr
-}
-
-// initDocStore 启动文档记忆。flush 的唯一入口是 Stop()，所以关停时必须调用它。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func initDocStore(cfg *types.Config) (*document.Store, func()) {
-	docStore := document.NewStore(filepath.Join(cfg.Daemon.DataDir, "memory", "documents"), memory.TokenizeWords)
-	if err := docStore.Start(); err != nil {
-		log.Printf("[homed] warning: document store: %v", err)
-	}
-	// 关停时落盘。文档记忆的内存态变更（迁移结果、访问计数等）只在 flush
-	// 里写盘，而 flush 的唯一入口是 Stop()——此前全仓无人调用它，
-	// 于是迁移结果永不落盘、每次启动白算一遍。
-
-	return docStore, func() { docStore.Stop() }
-}
-
-// initDistillSplitter 按配置打开蒸馏用的生成侧 provider 并组装拆分器。
-//
-// 返回 nil 表示不启用（未配置 provider、或打开失败）—— 此时蒸馏回退既有的
-// jieba/ONNX 路。**不因为模型不可用而让蒸馏停摆**：那条路虽然实测产出 0 条，
-// 但它至少不会让对话记忆丢失。
-//
-// 配置形态与多模态向量侧对称（core.memory.multimodal_space.*）：
-//
-//	core.memory.distill.generation.provider = ollama
-//	core.memory.distill.generation.options.model = qwen3:1.7b
-//	core.memory.distill.generation.options.num_thread = 10
-func initDistillSplitter(cfgReg *internalConfig.ConfigRegistry) pipeline.RecordSplitter {
-	if cfgReg == nil {
-		return nil
-	}
-	providerName := cfgReg.GetString("core.memory.distill.generation.provider", "")
-	if providerName == "" {
-		return nil
-	}
-	opts := map[string]string{}
-	const optPrefix = "core.memory.distill.generation.options."
-	for _, key := range cfgReg.List(optPrefix) {
-		opts[strings.TrimPrefix(key, optPrefix)] = cfgReg.GetString(key, "")
-	}
-	provider, err := generation.Open(providerName, generation.Config{Options: opts})
-	if err != nil {
-		log.Printf("[homed] warning: 蒸馏生成 provider %q 打开失败: %v（蒸馏回退 jieba 路；已注册: %s）",
-			providerName, err, strings.Join(generation.Names(), ", "))
-		return nil
-	}
-	if !provider.Info().SupportsJSONSchema {
-		// 拆分器的零幻觉完全依赖 schema 约束。不支持 schema 的 provider
-		// 会拿到自由文本，解析必炸 —— 与其让它在运行时反复失败，不如现在就拒。
-		log.Printf("[homed] warning: 蒸馏生成 provider %q 不支持 JSON Schema，拆分不可靠（蒸馏回退 jieba 路）",
-			providerName)
-		provider.Close()
-		return nil
-	}
-	log.Printf("[homed] distill generation active: provider=%s model=%s",
-		providerName, provider.Info().Model)
-	return distill.NewExtractor(provider, nil)
-}
-
-// initMultimodalSpace 从公共注册表打开多模态向量 provider。返回 (空间, provider 名, 失败原因, cleanup)：后两个值只用于状态报告。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func initMultimodalSpace(cfgReg *internalConfig.ConfigRegistry) (vector.MultimodalEmbedder, string, string, func()) {
-	var multimodalSpace vector.MultimodalEmbedder
-	// 这两个值只用于状态报告（healthcheck_kernel 的 onnx 段）：
-	// 「配了哪个 provider」与「为什么没启用」，避免只能看到 false 却不知原因。
-	var mmProviderName, mmErr string
-	var closeAdapted func()
-	if mmProvider := cfgReg.GetString("core.memory.multimodal_space.provider", ""); mmProvider != "" {
-		mmProviderName = mmProvider
-		opts := map[string]string{}
-		const optPrefix = "core.memory.multimodal_space.options."
-		for _, key := range cfgReg.List("core.memory.multimodal_space.options.") {
-			opts[strings.TrimPrefix(key, optPrefix)] = cfgReg.GetString(key, "")
-		}
-		provider, err := embedding.Open(mmProvider, embedding.Config{Options: opts})
-		if err != nil {
-			mmErr = err.Error()
-			log.Printf("[homed] warning: 多模态向量 provider %q 打开失败: %v（多模态向量检索已禁用；已注册: %s）",
-				mmProvider, err, strings.Join(embedding.Names(), ", "))
-		} else if adapted, err := vector.AdaptProvider(provider); err != nil {
-			provider.Close()
-			mmErr = err.Error()
-			log.Printf("[homed] warning: 多模态向量 provider %q 元数据不合法: %v（多模态向量检索已禁用）", mmProvider, err)
-		} else {
-			multimodalSpace = adapted
-			info := provider.Info()
-			// 指纹可能很长（模型文件哈希），日志里只取前 12 个字符便于对照。
-			shortFP := info.Fingerprint
-			if len(shortFP) > 12 {
-				shortFP = shortFP[:12]
-			}
-			log.Printf("[homed] multimodal space active: provider=%s dim=%d fp=%s modalities=%v",
-				mmProvider, info.Dimension, shortFP, info.Modalities)
-		}
-	}
-
-	if closeAdapted == nil {
-		closeAdapted = func() {}
-	}
-	return multimodalSpace, mmProviderName, mmErr, closeAdapted
-}
-
-// initKnowledgeStore 启动知识库。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func initKnowledgeStore(cfg *types.Config) *knowledge.Store {
-	ks := knowledge.NewStore(filepath.Join(cfg.Daemon.DataDir, "knowledge"))
-	if err := ks.Start(); err != nil {
-		log.Printf("[homed] warning: knowledge store: %v", err)
-	} else {
-		log.Printf("[homed] knowledge store active with %d items", len(ks.List()))
-	}
-
-	return ks
-}
-
-// initKnowledgeMigration 在知识库扫盘**之前**把存量目录名规范化。
-//
-// 为何不靠 Store 内部自己做：规范名是「内存键 + 盘上目录 + LLM 可见名字」
-// 三者必须逐字一致，而磁盘重命名属于有破坏性的副作用，应该在 store 扫盘
-// 之前、在明确的边界上一次性做完，而不是散在 Store 的初始化路径里。
-//
-// 为何默认只报告：os.Rename 不可逆，批量重命名生产数据必须由人确认。
-// 需要真正迁移时用 homed-kb-migrate -apply（或把下面 defaultApply 打开）。
-//
-// 本函数体同样遵守 bootstrap 的平移原则。
-func initKnowledgeMigration(cfg *types.Config) {
-	root := filepath.Join(cfg.Daemon.DataDir, "knowledge")
-	const (
-		// defaultApply = false ⇒ 启动时只扫描并报告，不改名。
-		defaultApply = false
-		// maxRenamePerRun 限制单次重命名数：给失控的目录规模设一个上限，
-		// 避免启动阶段被一次大迁移拖住。
-		maxRenamePerRun = 200
-	)
-	items, err := knowledge.PlanMigration(root)
-	if err != nil {
-		log.Printf("[homed] 知识库迁移扫描失败（跳过）: %v", err)
-		return
-	}
-	need, illegal := 0, 0
-	for _, it := range items {
-		if it.Illegal {
-			illegal++
-		} else if it.NewName != "" {
-			need++
-		}
-	}
-	if need == 0 && illegal == 0 {
-		return
-	}
-	if illegal > 0 {
-		log.Printf("[homed] 知识库迁移：%d 条名称非法（含 .. / 点段 / 隐藏段），写入与删除均已拒绝，需人工处理", illegal)
-	}
-	if need == 0 {
-		return
-	}
-	log.Printf("[homed] 知识库迁移：%d/%d 条目录名待规范化（例：%s → %s）", need, len(items),
-		items[0].OldName, items[0].NewName)
-	if !defaultApply {
-		log.Printf("[homed] 知识库迁移：当前为只报告模式。确认清单后执行：homed-kb-migrate -root %s -apply", root)
-		return
-	}
-	if need > maxRenamePerRun {
-		log.Printf("[homed] 知识库迁移：需改名 %d 条超过单次上限 %d，本次只处理前 %d 条",
-			need, maxRenamePerRun, maxRenamePerRun)
-	}
-	applied, failed := knowledge.ApplyMigration(root, items, maxRenamePerRun)
-	log.Printf("[homed] 知识库迁移完成：成功 %d，失败 %d", applied, failed)
-}
-
-// loadPersonality 按「个人文件 > 配置项」的优先级解析人格内容，并对腐坏内容告警。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func loadPersonality(cfg *types.Config, cfgReg *internalConfig.ConfigRegistry) *agentPkg.Personality {
-	personalPath := filepath.Join(cfg.Daemon.DataDir, "personal", "personal.md")
-	personality, err := agentPkg.LoadPersonality(personalPath)
-	if err != nil {
-		log.Printf("[homed] warning: load personality: %v", err)
-	}
-	if personality != nil && personality.Content != "" {
-		log.Printf("[homed] 人格来源=文件 %s（优先于配置项），%d 字节", personalPath, len(personality.Content))
-		if hints := agentPkg.PersonaStaleHints(personality.Content); len(hints) > 0 {
-			log.Printf("[homed] warning: 人格文件含会腐坏的内容 %v — 建议迁到配置项 core.agent.personal_prompt"+
-				"（默认模板不含版本号，被问版本时以运行时快照为准）", hints)
-		}
-	} else if pv := cfgReg.GetString("core.agent.personal_prompt", internalConfig.DefaultPersonaPrompt); strings.TrimSpace(pv) != "" {
-		personality = &agentPkg.Personality{Content: pv, Path: "(core.agent.personal_prompt)"}
-		log.Printf("[homed] 人格来源=配置项 core.agent.personal_prompt，%d 字节", len(pv))
-	} else {
-		log.Printf("[homed] 人格来源=无（配置项为空且无人格文件）")
-	}
-
-	return personality
-}
-
-// newStageAndRegistry 建阶段管道与插件注册表，把内核依赖接到注册表上。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func newStageAndRegistry(cfg *types.Config, cfgReg *internalConfig.ConfigRegistry, iom *agentIO.IOManager,
-	evBus *events.Bus, memDB *memory.GraphDB, textMem *text.Memory, docStore *document.Store,
-	ks *knowledge.Store, providerMgr *agentAPI.ProviderManager,
-	dataDir string) (*agentCore.StageHost, *plugin.Registry) {
-	stageHost := agentCore.NewStageHost()
-
-	pluginReg := plugin.NewRegistry()
-	pluginReg.SetIOManager(iom)
-	pluginReg.SetEventBus(evBus)
-	pluginReg.SetMemory(memDB)
-	pluginReg.SetTextMemory(textMem)
-	pluginReg.SetDocStore(docStore)
-	pluginReg.SetKnowledge(ks)
-	pluginReg.SetProviderManager(providerMgr)
-	pluginReg.SetConfigRegistry(cfgReg)
-	pluginReg.SetPluginDir(cfg.Plugin.Dir)
-	pluginReg.SetDataDir(dataDir) // 插件 SettingsAPI.DataDir() 的数据根目录
-
-	// Wire registration callbacks: plugins' RegisterTool/RegisterStage → StageHost
-	pluginReg.SetToolRegistrar(func(name string, def sdk.ToolDef, handler sdk.ToolHandler) error {
-		log.Printf("[homed] SetToolRegistrar registering tool: %s (plugin=%s)", name, def.Plugin)
-		return stageHost.RegisterTool(name, def, handler)
-	})
-	pluginReg.SetStageRegistrar(func(stage sdk.Stage, handler sdk.StageHandler) {
-		stageHost.RegisterStage(stage, handler)
-	})
-	pluginReg.SetAPIRegistrar(func(name string) error {
-		return nil
-	})
-	pluginReg.SetToolCleaner(stageHost)
-
-	return stageHost, pluginReg
-}
-
-// newMainAgent 组装主 Agent：把内核各面（IO/记忆/文档/知识/媒体/社交/文本/插件/状态）接进 AgentConfig。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func newMainAgent(cfg *types.Config, cfgReg *internalConfig.ConfigRegistry, provider agentAPI.Provider,
-	providerMgr *agentAPI.ProviderManager, iom *agentIO.IOManager, memDB *memory.GraphDB,
-	memIdx *memory.Indexer, trk *tracker.Tracker, docStore *document.Store, ks *knowledge.Store,
-	socialStore *social.SocialStore, textMem *text.Memory,
-	personality *agentPkg.Personality, pluginReg *plugin.Registry, embedder *memory.StaticEmbedder,
-	multimodalSpace vector.MultimodalEmbedder, mmProviderName, mmErr string,
-	stageHost *agentCore.StageHost, evBus *events.Bus) *agentCore.Agent {
-	sysPrompt := cfgReg.GetString("core.agent.system_prompt", defaultSystemPrompt)
-	if sysPrompt == "" {
-		sysPrompt = defaultSystemPrompt
-	}
-
-	// D4：把"设备是否已授权"的判据注入插件侧（toolImpl.CanUse 用）。
-	// ⚠️ 必须放在 agent 构造**之后**——判据要用 agent 的 allowedOutputs，
-	// 而 registry 早于 agent 构造（故这里传的是晚绑定闭包）。
-	// 未注入时 ToolAPI 路径对设备放行：那是"授权可被绕过"的既成缺口。
-	// 注入后，cli 的 /terminal、seq 序列等一切走 ToolAPI 的调用都受同一道闸。
-	agent := agentCore.New(agentCore.AgentConfig{
-		ID:              "main",
-		SystemPrompt:    sysPrompt,
-		Provider:        provider,
-		ProviderManager: providerMgr,
-		IO:              iom,
-		Memory:          memDB,
-		Indexer:         memIdx,
-		Tracker:         trk,
-		DocStore:        docStore,
-		Knowledge:       ks,
-		SocialStore:     socialStore,
-		TextMemory:      textMem,
-		// MediaStore 已随 CAS 淘汰：块自带负载（见 plan.md）。
-		Personality:     personality,
-		// 人格落库面：首启门禁（任何通道都问一次）与 persona_set 工具用。
-		// 与 WebUI 向导共用 internal/config 的同一份落库逻辑。
-		PersonaStore: internalConfig.RegistryPersonaStore{Reg: cfgReg},
-		PluginReg:    pluginReg,
-		PluginDir:    cfg.Plugin.Dir,
-		// DataDir：驻留子的 temp 图库锚点（<data>/residents/<id>/graph.db）。
-		// 漏接时的现象是"工具存在、可调用、但创建必失败"——只有真实二进制才看得出来。
-		DataDir:         cfg.Daemon.DataDir,
-		DistillInterval: cfgReg.GetDuration("core.agent.distill_interval", 30*time.Minute),
-		ArchiveInterval: cfgReg.GetDuration("core.agent.archive_interval", 60*time.Minute),
-		ReviewInterval:  cfgReg.GetDuration("core.agent.review_interval", 120*time.Minute),
-		MergeInterval:   cfgReg.GetDuration("core.agent.merge_interval", 120*time.Minute),
-		MaxToolTurns:    cfgReg.GetInt("core.agent.max_tool_turns", 10),
-		// 上下文管理的可调阈值。此前这些值全部硬编码在 ComputeTokenBudget 里，
-		// 界面改不了、不同窗口的实例也没法各自调优。
-		CtxTuning: agentCore.ContextTuning{
-			UtilizationPercent: cfgReg.GetInt("core.agent.context.utilization_percent", 80),
-			MaxTargetTokens:    cfgReg.GetInt("core.agent.context.max_target_tokens", 600000),
-			MemoryRatioPercent: cfgReg.GetInt("core.agent.context.memory_ratio_percent", 0),
-			ProtectedCount:     cfgReg.GetInt("core.agent.context.protected_count", 10),
-		},
-		// ⚠️ 这条键此前被注册进配置面板、也有默认值，但**从未被读取** ——
-		// 界面上改它没有任何效果，且不报任何错。同一类「死配置」正是
-		// 本次把阈值接入配置系统时要一并修掉的。
-		MaxContextSize: cfgReg.GetInt("core.agent.max_context_size", 30),
-		Offload: agentCore.OffloadOptions{
-			Enabled:      cfgReg.GetBool("core.agent.offload_enabled", false),
-			BusyAfter:    cfgReg.GetDuration("core.agent.offload_busy_after", 5*time.Minute),
-			MinPending:   cfgReg.GetInt("core.agent.offload_min_pending", 3),
-			MaxResidents: cfgReg.GetInt("core.agent.offload_max_residents", 2),
-		},
-		ContextSavePath:    filepath.Join(cfg.Daemon.DataDir, "memory", "context.json"),
-		EmbeddingModelPath: cfgReg.GetString("core.agent.embedding_model_path", ""),
-		Embedder:           embedder,
-		MultimodalSpace:    multimodalSpace,
-		EmbeddingProvider:  mmProviderName,
-		EmbeddingError:     mmErr,
-		StageHost:          stageHost,
-		EventBus:           evBus,
-		ThinkingEnabled:    cfg.LLM.ThinkingEnabled,
-		InputProcessing:    cfg.InputProcessing,
-	})
-
-	// 图记忆读写钩子 → 事件总线。
-	//
-	// ★ 为什么在这里接（而不是让各调用方自己发事件）：
-	//   图读写散在 26 个方法与 180+ 个 db 调用点上，各调用方自报必漏发；
-	//   而**图库自己就知道它碰了哪些块 ID**。星图此前只能靠工具名猜
-	//   节点（把 "memory_recall" 拆词去匹配中文实体名，实测命中 0），
-	//   于是每次都点亮同一批无关节点——这正是「星图没有读写反馈」的真身。
-	//
-	// ★ 只在 evBus 非 nil 时接：它把「内核进程」与「独立 CLI 工具」区分开
-	//   （homed-graph-migrate / memgc 等也用 NewGraphDB，但没有事件总线，
-	//   也不该为一次批量迁移向不存在的订阅者发几万条事件）。
-	//
-	// ★ 钩子**必须非阻塞**：它在记忆读写的同步路径上，发布到总线
-	//   是内存操作（各订阅者回调也都很短），实测开销可忽略。
-	if memDB != nil && evBus != nil {
-		memDB.SetAccessHook(func(ev memory.AccessEvent) {
-			payload := map[string]interface{}{
-				"op": ev.Op,
-			}
-			// 只在非空时带上字段：空数组会让前端白白重算一次。
-			if len(ev.Blocks) > 0 {
-				payload["blocks"] = ev.Blocks
-			}
-			if len(ev.Created) > 0 {
-				payload["created"] = ev.Created
-			}
-			if len(ev.Removed) > 0 {
-				payload["removed"] = ev.Removed
-			}
-			if len(ev.Merged) > 0 {
-				merged := make([]map[string]string, 0, len(ev.Merged))
-				for _, m := range ev.Merged {
-					merged = append(merged, map[string]string{"from": m.From, "to": m.To})
-				}
-				payload["merged"] = merged
-			}
-			if ev.Tool != "" {
-				payload["tool"] = ev.Tool
-			}
-			evBus.Publish(&events.Event{
-				Type:      events.EventMemoryAccess,
-				Source:    "main",
-				Payload:   payload,
-				Timestamp: time.Now().Unix(),
-			})
-		})
-	}
-
-	// D4：把「设备是否已授权」的判据注入插件侧（toolImpl.CanUse 消费它）。
-	//
-	// 为什么必须在这里：判据要用 agent 自己的 allowedOutputs，而
-	// pluginReg 早于 agent 构造（newStageAndRegistry 在 main() 里先跑），
-	// 所以 registry 存的是**晚绑定**闭包，注入点必须在 agent 建好之后。
-	//
-	// 不注入的后果（已实测的真实缺口）：设备授权闸只存在于
-	// core.executeToolCallInner，即「agent 收到模型 tool_call」那条路径；
-	// 而 ToolAPI.ExecuteTool 是**另一条**独立入口，不经那道闸 ⇒
-	// 凡是走 ToolAPI 的调用都能绕过 AllowedOutputs。实测范围不止序列：
-	// cli 的 /terminal 就直接经 ToolAPI 调 agentcli 的终端工具。
-	pluginReg.SetDeviceAuthQuery(func(deviceID string) bool {
-		return agent.IsOutputAllowed("device/" + deviceID)
-	})
-
-	// 方案 B：把 agent 的**内置工具面**注入 ToolAPI。
-	//
-	// 缺口背景：`memory_*` / `knowledge_*` / `doc_*` / `person_*` 这 20+ 个
-	// 在 executeToolCallInner 里按前缀分派，从不进 ToolAPI ⇒ 插件经 ToolAPI
-	// 既查不到也调不了。真机实跑实证：seq_run 报「工具 knowledge_list
-	// 不存在或未注册」，而同一轮模型直接调它是成功的。
-	//
-	// 注入必须在此处（agent 构造之后）：内置工具的可见性由运行期状态门控
-	// （memory/knowledge 是否就绪），而 provider 持有的是 agent。
-	agent.InstallBuiltinToolProvider()
-
-	return agent
-}
-
-// initONNXParser 初始化依存句法分析器（内嵌 ONNX 模型，失败则退回规则引擎）。
-//
-// 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
-// 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
-func initONNXParser(cfg *types.Config, cfgReg *internalConfig.ConfigRegistry) {
-	modelPath := cfgReg.GetString("core.agent.onnx_model_path", "")
-	onnxParser, err := nlp.NewONNXParser(nlp.ONNXConfig{
-		ModelPath: modelPath,
-		DataDir:   filepath.Join(cfg.Daemon.DataDir, "nlp"),
-	})
-	if err != nil {
-		log.Printf("[homed] warn: ONNX parser init: %v, using fallback", err)
-	} else {
-		nlp.SetDefaultParser(onnxParser)
-		log.Printf("[homed] dep parser initialized (model: %s)", modelPath)
-	}
-}
-
 // loadPlugins 建插件目录、按启动模式决定 allowlist，然后加载全部插件。
 //
 // 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
@@ -865,7 +257,27 @@ func startHeartbeat(dataDir string, ctx context.Context) func() {
 		}
 	}()
 
-	return func() { close(hbStop) }
+	// ★★ 必须幂等（2026-10-17 实测 panic：close of closed channel）。
+	//
+	// 调用点有**两处**：
+	//   · main.go:70  `defer stopHeartbeatEarly()`
+	//   · bootstrap.go waitForShutdown 里的 `stopHeartbeat()`
+	// 直接 `close(hbStop)` ⇒ 第二次关闭**必然 panic**：
+	//
+	//     panic: close of closed channel
+	//     goroutine 1 [running]:
+	//     main.startHeartbeat.func3()  bootstrap.go:259
+	//     main.main()                  main.go:293
+	//
+	// 而且它发生在**退出路径**上：进程已经做完清理工作，
+	// 却在最后一步崩溃 ⇒ 退出码变成 2（panic），
+	// systemd/guard 会把它当成"异常退出"而不是"正常停止"，
+	// 进而触发不必要的重启/告警。实测：SIGTERM 后退出但日志尾部是 panic 栈。
+	//
+	// 修法：`sync.Once` 保护。stop 函数做成幂等是本仓退出路径的通用要求
+	// （它们往往既被 defer 调、又被显式调）。
+	// 用 safeclose 统一入口（本仓 close 纪律：见 internal/safeclose）。
+	return safeclose.SafeFunc(hbStop)
 }
 
 // waitForShutdown 阻塞至 SIGINT/SIGTERM 或 supervisor 请求重启，然后按原 main 的顺序清理，需要重建时以退出码交回 guard。
@@ -873,7 +285,8 @@ func startHeartbeat(dataDir string, ctx context.Context) func() {
 // 本函数体是 main() 里对应启动阶段的整块平移：语句、日志文本、错误语义不变，
 // 只把「*dataDir」变成参数、把 defer 变成由调用点注册的 cleanup。
 func waitForShutdown(ctx context.Context, dataDir string, restartCh chan struct{}, stopHeartbeat func(),
-	pluginReg *plugin.Registry, trk *tracker.Tracker, cfgReg *internalConfig.ConfigRegistry, sup *supervisor.Daemon) {
+	pluginReg *plugin.Registry, trk *tracker.Tracker, cfgReg *internalConfig.ConfigRegistry, sup *supervisor.Daemon,
+	stopKernelModules func()) {
 	sigCh := make(chan os.Signal, 1)
 	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
 
@@ -895,6 +308,21 @@ func waitForShutdown(ctx context.Context, dataDir string, restartCh chan struct{
 		log.Printf("[homed] flush config: %v", err)
 	}
 	sup.Shutdown()
+
+	// ★★ 必须显式跑一次模块关闭，**不能只靠 defer**（2026-10-17 实测缺陷）。
+	//
+	// 两条退出路径原先**不对称**：
+	//   路径 A（SIGTERM）：return 到 main → defer ks.CloseAll() ✓
+	//   路径 B（exit 42）：下面的 os.Exit(42) **跳过所有 defer** ✗
+	//
+	// 而路径 B 是**每次热更新都走**的。后果是这些写者从不 flush：
+	//   · docStore.Stop()  → flush()     文档索引可能陈旧
+	//   · distiller.Stop() → flush()     待蒸馏规则丢失
+	//   · textMem.Stop()   → Close()     文本记忆未落盘
+	//   · luaVM/multimodal → 资源未释放（靠进程退出兜底）
+	//
+	// ⇒ 显式调用（CloseAll 幂等：第二次执行时 Closers 已空，无副作用）。
+	stopKernelModules()
 	log.Printf("[homed] stopped")
 
 	if restartRequested {
@@ -902,62 +330,6 @@ func waitForShutdown(ctx context.Context, dataDir string, restartCh chan struct{
 	}
 }
 
-// initLuaVM 起 Lua VM（LLM 协议适配）；启动失败只告警，cleanup 为 no-op。
-func initLuaVM(cfg *types.Config) (*luapkg.VM, func()) {
-	luaVM := luapkg.NewVM(filepath.Join(cfg.Daemon.DataDir, "adapters"))
-	if err := luaVM.Start(); err != nil {
-		log.Printf("[homed] warning: lua vm init failed: %v", err)
-		return luaVM, func() {}
-	}
-	return luaVM, luaVM.Stop
-}
-
-// initSupervisor 起守护管理（代理生命周期管理）；起不来是致命错误。
-func initSupervisor(cfg *types.Config) *supervisor.Daemon {
-	sup := supervisor.New(cfg)
-	if err := sup.Start(); err != nil {
-		log.Fatalf("start supervisor: %v", err)
-	}
-	return sup
-}
-
-// initTracker 起 overlayfs 变更追踪；无 overlayfs 支持时降级为非致命告警。
-func initTracker(cfg *types.Config, agentWorkDir string) *tracker.Tracker {
-	trk := tracker.NewTracker(cfg.Daemon.DataDir, agentWorkDir,
-		tracker.WithKeepChangesets(100),
-		tracker.WithMaxChangesetAge(30*24*time.Hour),
-	)
-	if err := trk.Init(); err != nil {
-		log.Printf("[homed] warning: tracker init: %v", err)
-	} else {
-		if err := trk.Start(); err != nil {
-			log.Printf("[homed] warning: tracker mount overlay: %v (non-fatal: no overlayfs support?)", err)
-		} else {
-			log.Printf("[homed] change tracker active at %s", trk.MergeDir())
-		}
-	}
-	return trk
-}
-
-// initKernelAPI 建内核与插件之间的两个通道：IOManager（IO 抽象层）+ EventBus（事件总线）。
-func initKernelAPI() (*agentIO.IOManager, *events.Bus) {
-	iom := agentIO.NewIOManager()
-	evBus := events.NewBus()
-	log.Printf("[homed] kernel API ready: IOManager + EventBus")
-	return iom, evBus
-}
-
-// initTextMemory 起文本记忆；启动失败只告警，cleanup 为 no-op。
-func initTextMemory(cfg *types.Config) (*text.Memory, func()) {
-	textMem := text.New(filepath.Join(cfg.Daemon.DataDir, "memory", "text"))
-	if err := textMem.Start(); err != nil {
-		log.Printf("[homed] warning: text memory start: %v", err)
-		return textMem, func() {}
-	}
-	log.Printf("[homed] text memory active at %s", filepath.Join(cfg.Daemon.DataDir, "memory", "text"))
-	return textMem, textMem.Stop
-}
-
 // resolveBaseAPIKey 解析兜底 API key：配置项 > LLM_API_KEY > DEEPSEEK_API_KEY。
 func resolveBaseAPIKey(cfg *types.Config) string {
 	apiKey := cfg.LLM.APIKey
@@ -970,21 +342,6 @@ func resolveBaseAPIKey(cfg *types.Config) string {
 	return apiKey
 }
 
-// wirePluginSDK 把内核各面注入每个插件的 PluginSDK（阶段6 将替换遗留的 util.Configure）。
-func wirePluginSDK(pluginReg *plugin.Registry, luaVM *luapkg.VM, baseAPIKey string, sup *supervisor.Daemon,
-	trk *tracker.Tracker, cfg *types.Config, stageHost *agentCore.StageHost, memIdx *memory.Indexer,
-	agent *agentCore.Agent) {
-	pluginReg.SetLuaVM(luaVM)
-	pluginReg.SetBaseAPIKey(baseAPIKey)
-	pluginReg.SetSupervisor(supervisor.NewSDKAdapter(sup))
-	pluginReg.SetTracker(trk)
-	pluginReg.SetConfig(cfg)
-	pluginReg.SetStageHost(stageHost)
-	pluginReg.SetIndexer(memIdx)
-	pluginReg.SetStatusProvider(agent)
-	pluginReg.SetTerminalAPI(agent)
-}
-
 // resolveWebUIOverride 解析 webui 监听地址的覆盖值，空串表示不覆盖。
 //
 // 优先级：CLI --webui > 核心配置 webui.listen_addr（仅当它被改成非内置默认值）。
diff --git a/cmd/homed/bootstrap_order_test.go b/cmd/homed/bootstrap_order_test.go
new file mode 100644
index 00000000..5eabf0a1
--- /dev/null
+++ b/cmd/homed/bootstrap_order_test.go
@@ -0,0 +1,126 @@
+package main
+
+// 启动顺序的**结构性判据**（2026-10-16）。
+//
+// ## 为什么必须有这条
+//
+// 实测故障（我方引入）：安全模块原先装配在 `cfg := cfgReg.ToConfig()` **之后**。
+// 于是 `ToConfig()` 在**没有主密钥**的情况下读 `core.llm.*.api_key` ——
+// 密文解不开 ⇒ key 变成空串；而 `initLLMProviders(cfg, …)` 用的正是这份
+// 早期快照 ⇒ **所有 LLM 调用 401 invalid api key**。
+//
+// 症状极具误导性：日志里只有 `Dump 解密 core.llm.api_key 失败: security: 无可用主密钥`，
+// 而 401 看起来像"key 配错了"。实际是纯粹的**启动顺序**问题 ——
+// 查 key 值、改 key、重配 provider 全都无效。
+//
+// ## 为什么用行号比较而不是行为测试
+//
+// `main()` 无法在单测里跑（要完整数据目录、要真密钥、要起一堆子系统）。
+// 而这里要守的是一个**结构性不变量**：「安全模块的装配点必须早于配置快照点」。
+// 行号比较恰好精确表达这个不变量 —— 比字符串包含匹配强得多
+// （后者在"注释里提到 ToConfig"时就会假绿或假红）。
+//
+// 这是本仓"判据要测真实顺序，而不是测某个字符串出现过"的一个正例：
+// 判据断言的是**两个真实调用点的相对位置**。
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+// ★★★ 判据：安全模块（InitConfigCodec）必须装配在 cfg := cfgReg.ToConfig() 之前。
+//
+// 违反的后果：LLM key 解不开 ⇒ 全 provider 401，而症状指向"key 配错"。
+func TestSecurityModuleInitializesBeforeConfigSnapshot(t *testing.T) {
+	b, err := os.ReadFile("main.go")
+	if err != nil {
+		t.Fatalf("读不到 main.go: %v", err)
+	}
+	src := string(b)
+
+	// 找**真实的调用点**：行内出现调用名，且该行不是注释。
+	//
+	// 为什么用 Contains 而不是 HasPrefix：真实形式有三种
+	//   cfg := cfgReg.ToConfig()
+	//   if _, cerr := security.InitConfigCodecWithOldKeys(...); cerr != nil {
+	//   key, keySrc, kerr := security.LoadOrCreateKey(...)
+	// 用 HasPrefix 会漏掉 if/赋值形态（第一版就是这么漏的）。
+	// 注释行仍要排除 —— 否则本文件顶部的说明注释会被当成装配点。
+	lineOf := func(call string) int {
+		for i, ln := range strings.Split(src, "\n") {
+			t := strings.TrimSpace(ln)
+			if strings.HasPrefix(t, "//") {
+				continue
+			}
+			if strings.Contains(ln, call) {
+				return i + 1
+			}
+		}
+		return -1
+	}
+
+	// ★ 锚点已随"内核模块化"改写（2026-10-16）：
+	//   `cfg := cfgReg.ToConfig()` → `ks.Cfg = cfgReg.ToConfig()`
+	// （快照现在直接存进 KernelState 的公共结构体，用户设计要求）。
+	//
+	// ★ 为什么匹配 "cfgReg.ToConfig()" 而不是整行：
+	// 赋值目标从 `cfg` 变成了 `ks.Cfg`，将来还可能再变。
+	// 判据要守的是**"ToConfig() 这个调用点的相对位置"**，
+	// 而不是某次具体的赋值写法 —— 锚在调用名上更稳且仍是真实调用点
+	// （lineOf 已排除注释行）。
+	snapLine := lineOf("cfgReg.ToConfig()")
+	if snapLine < 0 {
+		t.Fatal("找不到 `cfgReg.ToConfig()`（启动顺序不变量失去锚点）—— " +
+			"若方法改名/搬走，请把锚点更新到新的真实调用点，" +
+			"**不要**删掉这条判据：它守的是「主密钥必须先于配置快照」")
+	}
+	// 安全模块的**生效点**是 InitConfigCodecWithOldKeys（配置加密子密钥派生）
+	secLine := lineOf("security.InitConfigCodecWithOldKeys(")
+	if secLine < 0 {
+		secLine = lineOf("security.InitConfigCodec(")
+	}
+	if secLine < 0 {
+		t.Fatal("找不到 InitConfigCodec 调用（安全模块装配点）")
+	}
+	// 密钥装载点也要在快照之前（两者都在安全块里）
+	keyLine := lineOf("security.LoadOrCreateKey(")
+
+	if secLine > snapLine {
+		t.Errorf("★ 安全模块装配（第 %d 行）在配置快照（第 %d 行）**之后** —— "+
+			"ToConfig() 会在无主密钥时读 core.llm.*.api_key，key 变空 ⇒ 全 provider 401。"+
+			"必须把整个安全块前移到 ToConfig() 之前", secLine, snapLine)
+	}
+	if keyLine < 0 {
+		t.Fatal("找不到 LoadOrCreateKey 调用")
+	}
+	if keyLine > snapLine {
+		t.Errorf("★ 主密钥装载（第 %d 行）在配置快照（第 %d 行）之后 —— 同上",
+			keyLine, snapLine)
+	}
+	// 且 provider 注册必须用**快照之后**的 cfg（这条锚定"快照确实被使用了"，
+	// 防止有人把 ToConfig() 挪到别处却没人发现）
+	// ★ 锚点已随"内核模块化"改写（2026-10-16）：provider 注册搬进 llm 模块，
+	// 由 `RunKernelModules` 触发 ⇒ 新的等价锚点是它。
+	// 不变量不变：provider 注册必须晚于配置快照（否则拿到空 key）。
+	asmLine := lineOf("RunKernelModules(")
+	if asmLine > 0 && asmLine < snapLine {
+		t.Errorf("★ 内核模块装配（第 %d 行）早于配置快照（第 %d 行）—— "+
+			"llm 模块会拿到空 key 注册 provider", asmLine, snapLine)
+	}
+
+	// ★ **第二个读取点**：SetLLMSnapshotFile 启动即快照 core.llm.*（会读密文）。
+	// 第一版判据只盯了 ToConfig() ⇒ 把它前移后判据变绿，但线上**照旧报**
+	// `listPrefix 解密 core.llm.api_key 失败: 无可用主密钥` ——
+	// 因为真正早于安全模块的是**这个**调用（main.go 里在 SeedDefaults 之后立刻执行）。
+	// 这正是本会话反复吃到的"判据只覆盖一个出口"：修一个点，另一个点照样漏。
+	snapFileLine := lineOf("cfgReg.SetLLMSnapshotFile(")
+	if snapFileLine < 0 {
+		t.Fatal("找不到 SetLLMSnapshotFile 调用")
+	}
+	if snapFileLine < secLine {
+		t.Errorf("★ SetLLMSnapshotFile（第 %d 行）早于安全模块装配（第 %d 行）—— "+
+			"启动即快照会读 core.llm.* 密文，主密钥还没装 ⇒ 密文解不开、快照写成空值，"+
+			"且日志刷 '无可用主密钥'。必须把安全块前移到它之前", snapFileLine, secLine)
+	}
+}
diff --git a/cmd/homed/bootstrap_test.go b/cmd/homed/bootstrap_test.go
deleted file mode 100644
index eb0a9e6e..00000000
--- a/cmd/homed/bootstrap_test.go
+++ /dev/null
@@ -1,42 +0,0 @@
-package main
-
-import (
-	"os"
-	"path/filepath"
-	"testing"
-)
-
-// TestInitMemoryStackKeepsDistillerRunning 锁死启动接线回归：
-// initMemoryStack 必须返回一个**仍在运行**的蒸馏器。
-//
-// 历史 bug：main() 拆分时函数体内残留一句 `defer distiller.Stop()`，
-// 函数一 return 就 cancel 掉刚启动的循环，规则蒸馏 10min 心跳从不运行。
-// 该缺陷不会让任何单测变红——pipeline 的 TestDistillOnce* 直接调
-// distillOnce，绕过了 Start/Stop 接线；只有在这里按「启动阶段函数」的
-// 真实调用方式断言，才照得出来。
-func TestInitMemoryStackKeepsDistillerRunning(t *testing.T) {
-	dir := t.TempDir()
-	// NewGraphDB 需要父目录已存在（生产由 dataDir 初始化保证）。
-	if err := os.MkdirAll(filepath.Join(dir, "memory"), 0755); err != nil {
-		t.Fatal(err)
-	}
-	st, cleanup := initMemoryStack(dir, nil)
-	if st == nil || st.distiller == nil {
-		cleanup()
-		t.Fatal("initMemoryStack 未返回蒸馏器")
-	}
-	if st.db == nil {
-		cleanup()
-		t.Skip("图库未初始化，无法验证蒸馏接线")
-	}
-	if st.distiller.Stopped() {
-		cleanup()
-		t.Fatal("initMemoryStack 返回后蒸馏循环已被停掉（defer Stop 残留？）")
-	}
-
-	// cleanup 是唯一的停机点：先停蒸馏器、再关图库。
-	cleanup()
-	if !st.distiller.Stopped() {
-		t.Fatal("cleanup 之后蒸馏器应已停止")
-	}
-}
diff --git a/cmd/homed/failback.go b/cmd/homed/failback.go
index 6e3b47c6..27f3dd87 100644
--- a/cmd/homed/failback.go
+++ b/cmd/homed/failback.go
@@ -22,7 +22,9 @@ import (
 )
 
 // runFailbackRecovery 在 failback worker 内执行 L1 恢复梯子：
-//   probe(rescue 源) → 还原 DNS/proxy → probe → 还原 LLM 配置快照+ReloadFromConfig → probe
+//
+//	probe(rescue 源) → 还原 DNS/proxy → probe → 还原 LLM 配置快照+ReloadFromConfig → probe
+//
 // 成功后写 recovery_result.json 并以 exitRecovered 退出；失败以 exitRecoveryFailed 退出。
 // 全程确定性、无 token 消耗（除 rescue 源 QuickChat 复检外）。
 func runFailbackRecovery(dataDir string, cfgReg *internalConfig.ConfigRegistry, lua *luaVM.VM, providerMgr *agentAPI.ProviderManager, baseAPIKey string) {
diff --git a/cmd/homed/guard.go b/cmd/homed/guard.go
index 5229bc25..6420e373 100644
--- a/cmd/homed/guard.go
+++ b/cmd/homed/guard.go
@@ -532,40 +532,41 @@ func doLastResort(cfg *guardConfig) {
 }
 
 // ══════════════════════════════════════════════════════════════════════
-//  L2 自杀防护（2026-10-11）
 //
-//  # 要防的是什么
+//	 L2 自杀防护（2026-10-11）
 //
-//  doLastResort(restart_app) 会执行 `systemctl restart <unit>`。而启用 guard 的
-//  标准做法正是让 systemd 管理 `homed --role=guard` —— 也就是说 **<unit> 就是
-//  guard 自己所在的单元**。
+//	 # 要防的是什么
 //
-//  于是 spawnWorker 失败时形成死循环：
+//	 doLastResort(restart_app) 会执行 `systemctl restart <unit>`。而启用 guard 的
+//	 标准做法正是让 systemd 管理 `homed --role=guard` —— 也就是说 **<unit> 就是
+//	 guard 自己所在的单元**。
 //
-//	guard: doLastResort → systemctl restart homeagent
-//	       → SIGTERM 杀掉自己 → systemd 按 Restart=always 拉起新 guard
-//	       → 新 guard 再 spawn 失败 → 再自杀 ……
+//	 于是 spawnWorker 失败时形成死循环：
 //
-//  每轮都白跑一遍完整启动，且日志被刷爆。这与 2026-09-05 那次 systemd 审计
-//  记录的事故同类（坏配置导致 836 次重启、79 分钟）。
+//		guard: doLastResort → systemctl restart homeagent
+//		       → SIGTERM 杀掉自己 → systemd 按 Restart=always 拉起新 guard
+//		       → 新 guard 再 spawn 失败 → 再自杀 ……
 //
-//  # 正确解法不是「换个单元名」
+//	 每轮都白跑一遍完整启动，且日志被刷爆。这与 2026-09-05 那次 systemd 审计
+//	 记录的事故同类（坏配置导致 836 次重启、79 分钟）。
 //
-//  换成别的服务（重启 llmsproxy 之类）语义完全不对——L2 的本意是
-//  「重启我自己」。而 systemd 的 Restart=already(always) 已经提供了这件事：
+//	 # 正确解法不是「换个单元名」
 //
-//	guard 自行退出 == systemd 重新拉起 == 重启整个单元
+//	 换成别的服务（重启 llmsproxy 之类）语义完全不对——L2 的本意是
+//	 「重启我自己」。而 systemd 的 Restart=already(always) 已经提供了这件事：
 //
-//  所以自指时应当**直接退出**，效果与 restart_app 完全等价，且没有自杀窗口。
+//		guard 自行退出 == systemd 重新拉起 == 重启整个单元
 //
-//  # 为何还要保留 restart_command
+//	 所以自指时应当**直接退出**，效果与 restart_app 完全等价，且没有自杀窗口。
 //
-//  两种部署形态都合法：
-//   - systemd 管 guard（推荐）：自指 → 退出即可
-//   - 别的守护器管 guard（如 supervisor/前台 shell）：此时 guard 不是
-//     systemd 单元的 MainPID，restart_command 可能指向一个**正确**的其它单元，
-//     或者根本不该执行
-//  故不删除，只在「确实是自指」时改走退出路径，并留下明确日志。
+//	 # 为何还要保留 restart_command
+//
+//	 两种部署形态都合法：
+//	  - systemd 管 guard（推荐）：自指 → 退出即可
+//	  - 别的守护器管 guard（如 supervisor/前台 shell）：此时 guard 不是
+//	    systemd 单元的 MainPID，restart_command 可能指向一个**正确**的其它单元，
+//	    或者根本不该执行
+//	 故不删除，只在「确实是自指」时改走退出路径，并留下明确日志。
 func doLastResortGuarded(cfg *guardConfig, unit string) {
 	if unit != "" && isSelfRestartCommand(cfg.RestartCommand, unit) {
 		log.Printf("[guard] last_resort=restart_app 但 restart_command 指向自身单元 %q："+
diff --git a/cmd/homed/guard_config_test.go b/cmd/homed/guard_config_test.go
index 0766bf8d..1dba8ada 100644
--- a/cmd/homed/guard_config_test.go
+++ b/cmd/homed/guard_config_test.go
@@ -245,16 +245,18 @@ func TestSnapshotBeforeDefaultsTrue(t *testing.T) {
 // TestStartupGraceAllowsInit 钉住「启动宽限期」这一部署关键行为。
 //
 // ★ 场景（2026-10-12 生产部署实测触发的故障）：
-//   停机 34s 后重启，heartbeat 文件 mtime 停在上一代 worker（已过期），
-//   新 worker 要先做完全部重型初始化（chineseclip + 静态词向量 + 知识重建，
-//   冷启动 5–8s）才开始写心跳。guard 的 5s ticker 先到、拿旧 mtime 判 stale
-//   → 把还在加载的 worker SIGKILL → 连续 6 次重启、guard 进入 failback
-//   Safe-Mode（服务降级）。
+//
+//	停机 34s 后重启，heartbeat 文件 mtime 停在上一代 worker（已过期），
+//	新 worker 要先做完全部重型初始化（chineseclip + 静态词向量 + 知识重建，
+//	冷启动 5–8s）才开始写心跳。guard 的 5s ticker 先到、拿旧 mtime 判 stale
+//	→ 把还在加载的 worker SIGKILL → 连续 6 次重启、guard 进入 failback
+//	Safe-Mode（服务降级）。
 //
 // 不变量：
-//  (a) 宽限期内，即使心跳文件 mtime 极旧，也**不许**判杀
-//  (b) 宽限期满后，陈旧心跳**必须**判杀（卡死的 worker 不能靠宽限躲过去）
-//  (c) 宽限期满后，新鲜心跳不许判杀（误杀健康 worker 同样是事故）
+//
+//	(a) 宽限期内，即使心跳文件 mtime 极旧，也**不许**判杀
+//	(b) 宽限期满后，陈旧心跳**必须**判杀（卡死的 worker 不能靠宽限躲过去）
+//	(c) 宽限期满后，新鲜心跳不许判杀（误杀健康 worker 同样是事故）
 func TestStartupGraceAllowsInit(t *testing.T) {
 	dir := t.TempDir()
 	hb := filepath.Join(dir, "heartbeat")
diff --git a/cmd/homed/kmod_runtime.go b/cmd/homed/kmod_runtime.go
new file mode 100644
index 00000000..9a530e40
--- /dev/null
+++ b/cmd/homed/kmod_runtime.go
@@ -0,0 +1,188 @@
+package main
+
+// 内核模块装配的执行入口（Group 0 之后调用）。
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+
+	// ★ 把全部内核模块**引入编译**（Go 要求 import 才会编译进来）。
+	// 加一个新模块 = 新建 internal/kernelmod/<name>/mod.go + 在 all.go 加一行。
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/all"
+)
+
+// RunKernelModules 装配全部内核模块（必须在 Group 0 串行段之后调用）。
+//
+// ## 为什么"加模块零中央清单"在这里成立
+//
+// 各模块在自己的文件夹里写 `func init() { kernelmod.Register(...) }`，
+// 由 `kernelmod/all` 统一引入编译。本函数只问注册表要模块，
+// **不认识任何具体模块**，也不含任何依赖清单。
+//
+//	① 注册表（kernelmod）返回全部已注册模块（**乱序**，顺序无意义）
+//	② Build：算依赖图层（缺依赖/环/重名 ⇒ 这里就报错）
+//	③ Run：分层执行（同层有界并行），层边界更新 syncbus
+//
+// kernelAssembleHooks 是装配的**阶段回调**（供 main 在正确时机挂接）。
+type kernelAssembleHooks struct {
+	// BeforeRun 在**执行任何模块之前**调用（此时 syncbus 已创建、
+	// 全部设施已 MarkDeclared，但还没有一个就绪）。
+	//
+	// ★★ 为什么需要它（一个真实的设计缺口）：
+	//
+	// 插件调度器若在装配**完成之后**才挂到 syncbus 上，那么它提交插件时
+	// 全部设施早已就绪 ⇒ 每个声明了依赖的插件都"立即拉起"
+	// ⇒ **「声明提前启动」从未真正生效**（永远退化成同步全就绪）。
+	//
+	// 实测证据（真机，2026-10-16）：装一个声明 requires_facilities=[config] 的
+	// 外部插件，它仍在内核**全部 5 层完成**后才被拉起 —— 因为 stage-host
+	// 就绪（第 3 层）时插件注册表才存在，而调度器那时还没接上拉起动作。
+	//
+	// 有了本回调，调度器在 **Run 之前**订阅 syncbus ⇒ 内核每完成一层
+	// 都会触发它重新评估 ⇒ 声明了 config 的插件不必等 agent 层。
+	BeforeRun func(bus *kernelboot.SyncBus) error
+
+	// OnLayerDone 在每层完成后调用（供 main 在 **stage-host 就绪** 的那一刻
+	// 接上插件拉起动作）。
+	//
+	// ★★ 为什么必须是"每层"而不是"全部完成后"：
+	//
+	// 插件加载需要 **plugin.Registry**，而它是 `stage-host` 模块的产物
+	// ⇒ 插件**不可能**早于 stage-host 被加载（这是硬约束）。
+	// 但 stage-host 在第 3 层，而 agent 在第 4 层 —— 而 agent 层实测要
+	// **35 秒**（context dense backfill 750 events + document/knowledge 重建索引）。
+	//
+	// ⇒ 声明了早期设施（config/llm）的插件完全没必要等那 35 秒。
+	//   在 stage-host 就绪那一刻接上拉起动作，它们就能立刻起。
+	//
+	// 实测收益（真机）：early_probe（只声明 config）从"装配全部完成后"
+	// 提前到"第 3 层完成时"，省掉 agent 层那 35 秒。
+	OnLayerDone func(idx int, layer []kernelboot.Module)
+}
+
+func RunKernelModules(ks *kernelboot.KernelState, hooks kernelAssembleHooks) (*kernelboot.SyncBus, error) {
+	mods, err := buildModuleList()
+	if err != nil {
+		return nil, err
+	}
+
+	// ★★ 启动顺序来自**编译期产出的图**（用户设计）。
+	//
+	//	编译期：homed-depgraph 算好分层 → depgraph.bin（含层号）+ digest 注入二进制
+	//	运行期：**读**这份图 ⇒ 不自己算顺序
+	//
+	// 这样"启动顺序"是**编译期制品**，可审计（进 PR diff）、可离线校验。
+	//
+	// 缺失/损坏/漂移策略：
+	//   · dev（EmbeddedGraphHash 为空）：允许无图 ⇒ 回退运行期 Build（便于 go test/go run）
+	//   · 生产（有 hash）：必须有图，且 hash 必须匹配，且层号必须与声明一致
+	//     —— 任一不符 ⇒ **拒绝启动**（不猜哪边对：都是制品装配错误）
+	plan, err := loadStartupPlan(mods)
+	if err != nil {
+		return nil, err
+	}
+
+	bus := kernelboot.NewSyncBus()
+
+	// ★★ 先把**全部模块声明的设施**登记为"内核注册过"，**再**调用 BeforeRun。
+	//
+	// 时序很关键（我第一版搞反了，实测报了"内核已知的设施名: []"）：
+	//
+	//	BeforeRun（attach）：插件调度器提交声明 ⇒ 触发**拼错校验**
+	//	                      ⇒ 若此刻 known 为空，**所有声明都被误判为拼错**
+	//	MarkDeclared       ：把各模块的 Provides 登记进 known
+	//
+	// ⇒ 顺序必须是 **MarkDeclared → BeforeRun**。
+	//   （Run 内部也会 MarkDeclared，那是为了"装配中途失败也成立"，
+	//     与本处不冲突 —— MarkDeclared 幂等。）
+	var allProvides []string
+	for _, layer := range plan.Layers {
+		for _, m := range layer {
+			allProvides = append(allProvides, m.Provides()...)
+		}
+	}
+	bus.MarkDeclared(allProvides)
+
+	// ★ 在**执行任何模块之前**挂接（插件调度器在这里订阅 syncbus）。
+	//   这样内核每完成一层都会触发调度器重新评估 ⇒ 声明提前启动**真的生效**。
+	if hooks.BeforeRun != nil {
+		if err := hooks.BeforeRun(bus); err != nil {
+			return nil, err
+		}
+	}
+
+	res, err := kernelboot.Run(plan, kernelboot.RunOptions{
+		State: ks,
+		Bus:   bus,
+		// 并发上限：开 DB / 起 VM 很吃 IO，全放开会互相拖慢。
+		// 同层最多 8 个模块时 4 路并发实测最快（再高变 IO 争抢）。
+		MaxParallel: 4,
+		OnLayerDone: func(i int, layer []kernelboot.Module) {
+			names := make([]string, 0, len(layer))
+			for _, m := range layer {
+				names = append(names, m.Name())
+			}
+			log.Printf("[homed] 内核装配 第 %d 层完成（%d 个）: %s",
+				i, len(layer), strings.Join(names, ", "))
+			// ★ 把"某层完成"事件交给 main（用于在 stage-host 就绪时
+			//   立刻接上插件拉起动作，而不是等 agent 层的 35 秒）。
+			if hooks.OnLayerDone != nil {
+				hooks.OnLayerDone(i, layer)
+			}
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	log.Printf("[homed] 内核装配完成: %d 层 / %d 模块（峰值并发 %d，原为 17 步串行）",
+		res.LayerCount, len(res.Order), res.MaxConcurrent)
+	return bus, nil
+}
+
+// loadStartupPlan 取启动计划：优先读**编译期图**，dev 环境回退运行期 Build。
+func loadStartupPlan(mods []kernelboot.Module) (*kernelboot.Plan, error) {
+	exe, err := os.Executable()
+	if err != nil {
+		return nil, fmt.Errorf("无法确定二进制路径（图与它同目录）: %w", err)
+	}
+	graphPath := filepath.Join(filepath.Dir(exe), kernelboot.GraphFileName)
+
+	gf, err := kernelboot.LoadAndCheckGraph(graphPath, kernelboot.EmbeddedGraphHash)
+	if err != nil {
+		return nil, err
+	}
+	if gf == nil {
+		// dev：没有图（也没注入 hash）⇒ 运行期现算。
+		// 这条路径**不是**生产路径；它存在只为让 go test / go run 能用。
+		log.Printf("[homed] 未找到编译期依赖图（dev 构建），回退运行期分层")
+		return kernelboot.Build(mods)
+	}
+
+	plan, err := kernelboot.PlanFromGraph(gf, mods)
+	if err != nil {
+		return nil, err
+	}
+	log.Printf("[homed] 启动顺序来自编译期依赖图 %s（digest %s）",
+		filepath.Base(graphPath), gf.Digest[:16])
+	return plan, nil
+}
+
+// buildModuleList 从注册表取模块并做结构性检查。
+func buildModuleList() ([]kernelboot.Module, error) {
+	if d := kernelmod.Duplicates(); len(d) > 0 {
+		return nil, fmt.Errorf("内核模块名重复注册: %v（两个模块取了同名，或同一模块被导入两次）", d)
+	}
+	mods := kernelmod.Registered()
+	if len(mods) == 0 {
+		return nil, fmt.Errorf("没有任何内核模块被登记 —— " +
+			"通常是没有 import internal/kernelmod/all（见 cmd/homed/kmod_runtime.go）")
+	}
+	return mods, nil
+}
diff --git a/cmd/homed/main.go b/cmd/homed/main.go
index ab51c0cb..9d5545c6 100644
--- a/cmd/homed/main.go
+++ b/cmd/homed/main.go
@@ -4,18 +4,17 @@ import (
 	"context"
 	"log"
 	"path/filepath"
-	"strings"
 
 	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
-	"github.com/JianFeeeee/HomeAgent/internal/memory"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod/pluginhost"
 	"github.com/JianFeeeee/HomeAgent/internal/meta"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/clawhubadapter"
-	cli "github.com/JianFeeeee/HomeAgent/internal/plugins/cli"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/healthcheck"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/kbtree"
 	_ "github.com/JianFeeeee/HomeAgent/internal/plugins/pluginmgr"
-	webui "github.com/JianFeeeee/HomeAgent/internal/plugins/webui"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
 
 	// 空白导入内置 provider：它们各自在 init 里注册到 pkg/embedding。
 	// 想把核心换成自己的模型，只需替换这一行（或另建一个发行版 main）。
@@ -89,102 +88,187 @@ func main() {
 	defer cfgReg.Close()
 	cfgReg.SeedDefaults(opt.dataDir)
 	// LLM 配置写前留档（config_set 写 core.llm.* 前自动快照），guard 恢复用基线
-	cfgReg.SetLLMSnapshotFile(filepath.Join(opt.dataDir, "llm_snapshot.json"))
-	cfg := cfgReg.ToConfig()
-
-	// ---- 基础设施层：记忆、技能 ----
-
-	mem, closeMem := initMemoryStack(opt.dataDir, cfgReg)
-	defer closeMem()
-
-	// 共享词嵌入：蒸馏提取（Phase 3 TransE 验证）与 Agent 上下文复用同一实例，
-	// 避免同一模型被二次加载（约 200k×300 维 ≈ 数百 MB 内存）。
-	embedder := memory.NewStaticEmbedder(strings.Split(cfgReg.GetString("core.agent.embedding_model_path", ""), ",")...)
-	mem.distiller.SetEmbedder(embedder)
-
-	// ---- Lua VM（LLM 协议适配） ----
-
-	luaVM, closeLuaVM := initLuaVM(cfg)
-	defer closeLuaVM()
-
-	// ---- 守护管理（代理生命周期管理） ----
-
-	sup := initSupervisor(cfg)
-
-	// ---- 变更追踪（overlayfs） ----
-
-	trk := initTracker(cfg, agentWorkDir)
-
+	// ★ 锚点：本块必须在 SetLLMSnapshotFile / ToConfig 之前（两者都会读 core.llm.*）。
 	// ========================================================================
-	// 内核 API：IOManager（IO 抽象层） + EventBus（事件总线）
-	// 所有插件通过这两个通道与核心交互
+	// ★ 安全模块必须在**任何读 core.llm.* 的操作之前**装配。
+	//
+	// 实测故障（2026-10-16，自己引入的）：安全块原先放在 ToConfig() 之后。
+	// 于是 ToConfig() 在**没有主密钥**的情况下读 core.llm.*.api_key ——
+	// 密文解不开，key 变成空串，而 initLLMProviders(cfg,...) 用的正是这份
+	// 早期快照 ⇒ 所有 LLM 调用 401 invalid api key。
+	//
+	// 症状极具误导性：日志里只有一行 `Dump 解密 ... 失败: security: 无可用主密钥`，
+	// 而 401 看起来像“key 配错了”。实际是**启动顺序**问题。
+	//
+	// 约束：安全块只依赖 cfgReg（不依赖 cfg），所以可以安全前移。
 	// ========================================================================
+	if cfgReg.GetBool("core.security.enabled", true) {
+		// ★ 先收敛数据目录与敏感文件权限（幂等），再读密钥。
+		//
+		// 顺序有意为之：内嵌主密钥把密钥放进了 0755 的二进制里，
+		// 而 config.db 出厂是 0644 —— 「能读二进制就能解密数据库」。
+		// 收紧到 0600/0750 是本机缓解手段，必须在服务开始读写之前生效。
+		//
+		// 失败不 Fatal（权限问题不该让服务不可用），但会逐条响亮记录。
+		if hr := security.HardenDataDir(opt.dataDir); len(hr.Changed) > 0 {
+			log.Printf("[homed] 已收紧 %d 项权限（内嵌密钥场景的必要缓解）: %v",
+				len(hr.Changed), hr.Changed)
+		}
+		key, keySrc, kerr := security.LoadOrCreateKey(opt.dataDir)
+		if kerr != nil {
+			log.Fatalf("[homed] 安全模块密钥初始化失败（拒绝以降级模式启动）: %v", kerr)
+		}
+		// E-1：若存在密钥环，装入历史钥（只读旧密文；当前钥仍由
+		// systemd credential/env/security.key 提供）。密钥环损坏或 current 不一致
+		// 必须响亮失败，不能猜一把钥继续启动。
+		oldKeys, rerr := security.LoadKeyring(opt.dataDir, key)
+		if rerr != nil {
+			log.Fatalf("[homed] 安全模块密钥环加载失败（拒绝静默选错钥）: %v", rerr)
+		}
+		// ★ 内嵌钥上台时，磁盘钥必须继续参与**解密**。
+		//
+		// 否则一台用磁盘钥加密过的老机器升级到内嵌了另一把钥的二进制后，
+		// 旧密文会全部解不开 ⇒ 服务起不来；用户此时若选择"重建库"，
+		// 凭据就**一次性全丢** —— 那恰好与内嵌的初衷（防丢）相反。
+		//
+		// 与 E-1 同一套语义：当前钥负责 Seal，旧钥只参与 Open。
+		if extra := security.AdditionalDecryptKeys(opt.dataDir, key); len(extra) > 0 {
+			oldKeys = append(oldKeys, extra...)
+		}
+		if len(oldKeys) > 0 {
+			log.Printf("[homed] 安全模块已装入 %d 把历史/额外密钥（E-1 平滑轮换 + 内嵌迁移）", len(oldKeys))
+		}
+		if _, serr := security.InitGlobal(security.Options{
+			Path:    filepath.Join(opt.dataDir, "security", "variables.json"),
+			KeyFn:   func() ([]byte, error) { return key, nil },
+			OldKeys: oldKeys,
+			Enabled: true,
+		}); serr != nil {
+			log.Fatalf("[homed] 安全模块变量库加载失败（不静默重建）: %v", serr)
+		}
+		// 配置落盘用的子密钥（域隔离：与别名密钥不共用）。
+		// 必须早于 EncryptExistingSecrets，后者依赖它。
+		if _, cerr := security.InitConfigCodecWithOldKeys(key, oldKeys); cerr != nil {
+			log.Fatalf("[homed] 配置加密子密钥派生失败: %v", cerr)
+		}
+		// 把库里仍是明文的敏感项就地加密（幂等；升级路径必须跑）。
+		if n, merr := cfgReg.EncryptExistingSecrets(); merr != nil {
+			// 不 Fatal：库可能是只读/被锁，而“部分为明文”不等于服务不可用。
+			// 但要**响亮告警**：这是用户必须知道的安全事实。
+			log.Printf("[homed] 存量敏感配置加密未完成（部分项仍为明文）: %v", merr)
+		} else if n > 0 {
+			log.Printf("[homed] 已加密 %d 条存量敏感配置", n)
+		}
+		log.Printf("[homed] 安全模块已启用（密钥来源 %s，变量 %d 条，配置落盘加密已开启）",
+			keySrc, security.Global().Count())
 
-	iom, evBus := initKernelAPI()
-
-	// ---- 文本记忆 + 记忆蒸馏管线 ----
-
-	textMem, closeTextMem := initTextMemory(cfg)
-	defer closeTextMem()
-
-	ctx, stop := context.WithCancel(context.Background())
-	defer stop()
-
-	startMemoryCandidateConsumer(ctx, iom, textMem, mem.db, mem.distiller)
-
-	// ---- LLM Provider 管理（多源，通过 Lua 适配器协议转换） ----
-
-	baseAPIKey := resolveBaseAPIKey(cfg)
-
-	providerMgr := initLLMProviders(cfg, luaVM, baseAPIKey)
-	provider := providerMgr.Default()
-
-	// L1 failback：受限 worker 启动即跑恢复梯子（probe→还原DNS/proxy→还原config+ReloadFromConfig→probe），
-	// 结果以退出码 exitRecovered=43 / exitRecoveryFailed=44 交回 guard，不进入主 agent 循环。
-	if opt.boot == "failback" {
-		runFailbackRecovery(opt.dataDir, cfgReg, luaVM, providerMgr, baseAPIKey)
+		// ★ E-2：备份跨机器恢复的诊断。
+		//
+		// 场景：把 config.db 备份恢复到另一台机器，而主密钥没一起搬过来
+		// ⇒ 库里密文是**旧机器密钥**加的，当前钥解不开。
+		// 此前这种状态只在“读某一条配置”时才暴露成“某个功能坏了”，
+		// 用户看到的是症状而不是原因。这里一次性说清事实与修复动作。
+		if okN, badN, aerr := cfgReg.AuditSecrets(); aerr == nil && badN > 0 {
+			log.Printf("[homed] ⚠ 检测到 %d 条密文无法用当前主密钥解开（可解 %d 条）—— "+
+				"最常见原因是：这份 config.db 来自**另一台机器/另一个密钥**。"+
+				"修复：把原机器的密钥一起带过来（systemd credential / %s / "+
+				"%s），或用旧密钥启动一次并执行重加密迁移。",
+				badN, okN, security.EnvKeyName, security.KeyringFileName)
+		}
+	} else {
+		log.Printf("[homed] 安全模块被显式关闭（core.security.enabled=false）—— 明文落盘且中转无防护")
 	}
 
-	// ---- 文档记忆 + 知识库 ----
+	// ========================================================================
+	// ★ 内核装配：公共结构体 + 模块注册表（用户设计）
+	//
+	// Group 0（上面到这里的部分：平台门/心跳/日志/配置库/安全块）是
+	// **副作用顺序**要求，不进调度器 —— 依赖图表达不了"此动作必须在
+	// 那个动作之前生效"（图表达的是"我产出数据给他"）。见 kmod_group0 说明
+	// 与 bootstrap_order_test.go 的结构性判据。
+	//
+	// 从 cfg 起全部改为**模块自声明依赖 + 注册表 + BFS 分层**：
+	//   · 公共数据统一在 kernelboot.KernelState（不再散落各包包级变量）
+	//   · 每个模块在 internal/kernelmod/<name>/ 里**自己声明** Requires/Provides
+	//   · 注册表是乱序的（顺序无意义，仅供查询"内核有哪些模块"）
+	ks := kernelboot.NewKernelState()
+	ks.CfgReg = cfgReg
+	ks.DataDir = opt.dataDir
+	ks.AgentWorkDir = agentWorkDir
+	ks.CLISocket = opt.cliSocket
+	ks.HTTPAddr = opt.httpAddr
+	ks.Ctx, ks.Stop = context.WithCancel(context.Background())
 
-	docStore, closeDocStore := initDocStore(cfg)
-	defer closeDocStore()
+	// ★ Group 0 的最后两步（读 core.llm.*，必须在安全块之后）：
+	//   它们归 config 模块的产物路径，但**执行点**在这里 —— 阶段依赖。
+	cfgReg.SetLLMSnapshotFile(filepath.Join(opt.dataDir, "llm_snapshot.json"))
+	ks.Cfg = cfgReg.ToConfig()
 
-	multimodalSpace, mmProviderName, mmErr, closeMultimodal := initMultimodalSpace(cfgReg)
-	defer closeMultimodal()
+	// 装配全部内核模块（缺依赖/环/重名 ⇒ 这里就报错，不必等运行期）。
+	//
+	// ★ 插件调度已**归位到内核模块**（`internal/kernelmod/pluginhost`，
+	// 用户方案 A）：它负责扫元数据缓存、按三形态分流、按依赖时机拉起。
+	// main 这里不再有插件调度逻辑 —— 只保留装配后的一点点收尾。
+	// ★★ failback 的插件**白名单必须在装配之前**设置。
+	//
+	// 原因：插件拉起已归位到 plugin-host 模块，而它在**装配期**执行
+	// ⇒ 白名单若在装配后才设，插件早已按全量拉起了（受限启动就失效了）。
+	//
+	// 这是把调度搬进模块后引入的**新时序要求** —— 原先调度在装配后，
+	// 所以把 allowlist 放在装配后也无害。迁移时必须重新核对这类顺序。
+	//
+	// 注意：白名单要的是 plugin.Registry，而它是 stage-host 的产物
+	// ⇒ 装配前拿不到。所以这里传 nil 的 registry 只算白名单名（logged），
+	// 真正的 SetLoadAllowlist 由装配期的钩子在 registry 就绪后执行。
+	pendingAllowlist := resolveFailbackAllowlist(cfgReg, opt.boot, opt.dataDir)
 
-	// 迁移必须在 store 扫盘**之前**：改名后扫盘一次到位，
-	// 避免先以旧名建索引、再改名造成内存键与盘上目录短暂不一致。
-	initKnowledgeMigration(cfg)
-	ks := initKnowledgeStore(cfg)
+	// 装配全部内核模块（缺依赖/环/重名 ⇒ 这里就报错，不必等运行期）。
+	//
+	// ★ 插件调度已**归位到内核模块**（`internal/kernelmod/pluginhost`，
+	// 用户方案 A）：它负责扫元数据缓存、按三形态分流、按依赖时机拉起。
+	// main 这里不再有插件调度逻辑 —— 只保留装配后的一点点收尾。
+	if _, err := RunKernelModules(ks, kernelAssembleHooks{
+		// 在 stage-host 就绪、插件真正拉起**之前**把白名单设上。
+		OnLayerDone: func(_ int, _ []kernelboot.Module) {
+			if pendingAllowlist != nil && ks.PluginRegistry != nil {
+				ks.PluginRegistry.SetLoadAllowlist(pendingAllowlist)
+			}
+		},
+	}); err != nil {
+		log.Fatalf("[homed] 内核装配失败: %v", err)
+	}
+	defer ks.CloseAll()
 
-	// ---- 人格设定 ----
+	cfg := ks.Cfg
+	luaVM := ks.LuaVM
+	sup := ks.Supervisor
+	trk := ks.Tracker
+	ctx := ks.Ctx
+	pluginReg := ks.PluginRegistry
+	agent := ks.Agent
 
-	personality := loadPersonality(cfg, cfgReg)
+	// 候选消费管线：常驻 goroutine，把 eventbus 的 memory_candidate 写进
+	// 文本记忆并喂给蒸馏管线。原顺序里它在 textmem 之后、provider 之前。
+	startMemoryCandidateConsumer(ctx, ks.IO, ks.TextMemory, ks.Memory.DB, ks.Memory.Distiller)
 
-	// ---- 阶段管道（StageHost）+ 插件系统（Registry） ----
+	// L1 failback：受限 worker 启动即跑恢复梯子，结果以退出码交回 guard。
+	if opt.boot == "failback" {
+		runFailbackRecovery(opt.dataDir, cfgReg, luaVM, ks.LLMManager, ks.BaseAPIKey)
+	}
 
-	stageHost, pluginReg := newStageAndRegistry(cfg, cfgReg, iom, evBus, mem.db, textMem,
-		docStore, ks, providerMgr, opt.dataDir)
-
-	// ---- Agent Core (需在插件加载前创建，因为插件 Configure 需要 StatusProvider) ----
-
-	agent := newMainAgent(cfg, cfgReg, provider, providerMgr, iom, mem.db, mem.indexer, trk,
-		docStore, ks, mem.social, textMem, personality, pluginReg, embedder,
-		multimodalSpace, mmProviderName, mmErr, stageHost, evBus)
-
-	wirePluginSDK(pluginReg, luaVM, baseAPIKey, sup, trk, cfg, stageHost, mem.indexer, agent)
-
-	// 为内置插件注入内核依赖（各插件通过 init() 自注册工厂）
-	cli.DefaultSocket = opt.cliSocket
-	// webui 监听地址覆盖：必须在 loadPlugins 之前设置，插件 Start 时会读它。
-	webui.SetListenOverride(resolveWebUIOverride(cfgReg, opt.httpAddr))
-
-	// ---- 依存句法分析器（内嵌 ONNX 模型 / 规则引擎） ----
-
-	initONNXParser(cfg, cfgReg)
-
-	loadPlugins(cfg, cfgReg, pluginReg, stageHost, opt.boot, opt.dataDir)
+	// ---- 插件已完成调度（plugin-host 模块做的事）----
+	//
+	// 装配期 plugin-host 已：
+	//   ① 扫目录建元数据缓存（ks.PluginCatalog）
+	//   ② 按三形态分流（自动启动 / 不自动启动 / 禁用）
+	//   ③ 拉起"声明设施已就绪"的插件；挂起"等更晚设施（如 agent）"的
+	//      （挂起项经 syncbus 在 agent 就绪时自动拉起，见 pluginhost/waiter.go）
+	if cat, ok := ks.PluginCatalog.(*pluginhost.PluginCatalog); ok {
+		log.Printf("[homed] 插件调度完成：元数据缓存 %d 个，已加载 %d 个",
+			cat.Size(), len(pluginReg.ListLoadedPlugins()))
+	} else {
+		log.Printf("[homed] 插件调度完成：已加载 %d 个", len(pluginReg.ListLoadedPlugins()))
+	}
 
 	// 插件加载完成后再回收空闲页：大值（如老版聊天记录）可能在这一步被搬走/删除，
 	// 而 SQLite 的 DELETE 不会缩小文件。
@@ -205,5 +289,12 @@ func main() {
 	// ---- 等待退出信号 ----
 	//
 	// 心跳已在 main 早期启动（见文件头部 startHeartbeatEarly），此处不再重复启动。
-	waitForShutdown(ctx, opt.dataDir, restartCh, stopHeartbeatEarly, pluginReg, trk, cfgReg, sup)
+	// stopKernelModules：热更新路径（os.Exit 跳过 defer）下也要跑模块关闭。
+	// CloseAll 幂等（第二次 Closers 已空）⇒ 与 defer 并存是安全的。
+	waitForShutdown(ctx, opt.dataDir, restartCh, stopHeartbeatEarly, pluginReg, trk, cfgReg, sup,
+		func() {
+			if err := ks.CloseAll(); err != nil {
+				log.Printf("[homed] 模块关闭: %v", err)
+			}
+		})
 }
diff --git a/cmd/homed/memcandidate.go b/cmd/homed/memcandidate.go
new file mode 100644
index 00000000..97e26ff4
--- /dev/null
+++ b/cmd/homed/memcandidate.go
@@ -0,0 +1,79 @@
+package main
+
+// 记忆候选消费管线（常驻 goroutine）。
+//
+// ## 为什么放在 cmd/homed 而不是某个模块包里
+//
+// 它**不产出任何产物**（纯副作用：把事件写进文本记忆与蒸馏管线）⇒
+// 没有"注册到 KernelState"的价值，也不是一个可被依赖的设施。
+//
+// 但它**依赖** memory（distiller/memDB）与 kernel-io（iom）的产物，
+// 所以必须在内核装配**完成之后**启动 —— 由 main.go 在
+// RunKernelModules 之后调用（原顺序里它在 textmem 之后、provider 之前）。
+
+import (
+	"context"
+	"log"
+	"time"
+
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	"github.com/JianFeeeee/HomeAgent/internal/memory"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/pipeline"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/text"
+)
+
+// startMemoryCandidateConsumer 起一个常驻 goroutine：把 eventbus 上的
+// memory_candidate 事件写进文本记忆并喂给蒸馏管线。
+func startMemoryCandidateConsumer(ctx context.Context, iom *agentIO.IOManager,
+	textMem *text.Memory, memDB *memory.GraphDB, distiller *pipeline.Distiller) {
+	go func() {
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case evt, ok := <-iom.OutputChan():
+				if !ok {
+					return
+				}
+				if evt.Target == "memory" && evt.Type == "memory_candidate" {
+					source, _ := evt.Payload["source"].(string)
+					input, _ := evt.Payload["input"].(string)
+					response, _ := evt.Payload["response"].(string)
+					toolsUsed, _ := evt.Payload["tools_used"].([]string)
+					toolResults, _ := evt.Payload["tool_results"].([]interface{})
+					agentID, _ := evt.Payload["agent_id"].(string)
+
+					if input != "" && textMem != nil {
+						te := text.Event{
+							Timestamp: time.Now().Unix(),
+							Source:    source,
+							Input:     input,
+							Response:  response,
+							ToolsUsed: toolsUsed,
+							AgentID:   agentID,
+						}
+						if err := textMem.Append(te); err != nil {
+							log.Printf("[homed] text memory append: %v", err)
+						}
+					}
+
+					if input != "" && memDB != nil {
+						distiller.Append("agent", "user", input)
+					}
+					if response != "" && memDB != nil {
+						distiller.Append("agent", "assistant", response)
+					}
+
+					// 工具输出接入蒸馏管线
+					for _, tr := range toolResults {
+						if trMap, ok := tr.(map[string]interface{}); ok {
+							if out, ok := trMap["output"].(string); ok && out != "" && memDB != nil {
+								distiller.Append("agent", "tool", out)
+							}
+						}
+					}
+				}
+			}
+		}
+	}()
+}
diff --git a/cmd/homed/plugins_scheduled.go b/cmd/homed/plugins_scheduled.go
new file mode 100644
index 00000000..112769d1
--- /dev/null
+++ b/cmd/homed/plugins_scheduled.go
@@ -0,0 +1,80 @@
+package main
+
+// 按 syncbus 状态**分阶段**拉起插件（设计 §2.6）。
+//
+// ## 三条规则（按优先级）
+//
+//	未声明 requires_facilities          ⇒ 等内核**完全**初始化 ← **现行为，零改动**
+//	声明了且依赖全就绪                   ⇒ 立即拉起（**尽早启动**）
+//	声明了但依赖未齐                     ⇒ 挂起，等 syncbus 更新
+//	声明 auto_start=false                ⇒ 不自动拉起，等 agent 显式启用
+//
+// ## ★ 兼容性硬约束（§2.6.5）
+//
+// 存量 42 个插件都不声明依赖 ⇒ 全部走第一条 ⇒ 启动时机**逐字不变**。
+// 这不是"顺便兼容"，而是硬约束：任何一个存量插件若因本设计改变启动时机，
+// 就可能在不该动的时候动（如假设"我 Start 时 llm 已就绪"）。
+// **静默改变启动时机 = 静默引入竞态。**
+
+import (
+	"log"
+	"strings"
+
+	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
+	"github.com/JianFeeeee/HomeAgent/internal/plugin"
+	"github.com/JianFeeeee/HomeAgent/internal/recovery"
+)
+
+// resolveFailbackAllowlist 解析 failback 受限启动的插件白名单（装配**前**调用）。
+//
+// 返回 nil 表示非 failback 模式（普通启动不设白名单）。
+func resolveFailbackAllowlist(cfgReg *internalConfig.ConfigRegistry,
+	bootMode, dataDir string) []string {
+	if bootMode != "failback" {
+		return nil
+	}
+	list := cfgReg.GetString("core.agent.failback_plugins", "webui,pluginmgr,recoverydiag")
+	// 优先使用 guard.yaml 经 recovery 任务下发的插件集（guard 是 failback 权威）
+	if task, terr := recovery.LoadTask(recovery.TaskPath(dataDir)); terr == nil && len(task.Plugins()) > 0 {
+		list = strings.Join(task.Plugins(), ",")
+	}
+	var names []string
+	for _, s := range strings.Split(list, ",") {
+		if s = strings.TrimSpace(s); s != "" {
+			names = append(names, s)
+		}
+	}
+	log.Printf("[homed] failback boot: plugin allowlist = %v（装配前解析）", names)
+	return names
+}
+
+// applyFailbackPluginAllowlist 在 **failback 受限启动**下设置插件白名单。
+//
+// ## ★ 必须在插件被拉起**之前**生效
+//
+// failback 是内核的受限恢复模式：只加载少量插件（webui/pluginmgr/recoverydiag）
+// 以便直接产出恢复结论。白名单由 `guard.yaml` 的 recovery 任务或配置决定。
+//
+// 现在插件拉起由 plugin-host 模块负责，而它在装配期跑 ⇒ 本函数必须在
+// **装配之前**被调用（main 里已如此安排）。
+//
+// 非 failback 模式：本函数什么都不做（普通启动不设白名单）。
+func applyFailbackPluginAllowlist(cfgReg *internalConfig.ConfigRegistry,
+	pluginReg *plugin.Registry, bootMode, dataDir string) {
+	if bootMode != "failback" || pluginReg == nil {
+		return
+	}
+	list := cfgReg.GetString("core.agent.failback_plugins", "webui,pluginmgr,recoverydiag")
+	// 优先使用 guard.yaml 经 recovery 任务下发的插件集（guard 是 failback 权威）
+	if task, terr := recovery.LoadTask(recovery.TaskPath(dataDir)); terr == nil && len(task.Plugins()) > 0 {
+		list = strings.Join(task.Plugins(), ",")
+	}
+	var names []string
+	for _, s := range strings.Split(list, ",") {
+		if s = strings.TrimSpace(s); s != "" {
+			names = append(names, s)
+		}
+	}
+	pluginReg.SetLoadAllowlist(names)
+	log.Printf("[homed] failback boot: plugin allowlist = %v", names)
+}
diff --git a/cmd/homed/shutdown_flush_test.go b/cmd/homed/shutdown_flush_test.go
new file mode 100644
index 00000000..f87fae01
--- /dev/null
+++ b/cmd/homed/shutdown_flush_test.go
@@ -0,0 +1,125 @@
+package main
+
+// 停机**两条路径对称性**的判据（2026-10-17）。
+//
+// ## 缺陷（实测发现）
+//
+// `main()` 里有 `defer ks.CloseAll()`，但 `waitForShutdown` 在重启路径上
+// 调用 `os.Exit(exitRestartRequested)` —— **os.Exit 不跑 defer**。
+// ⇒ 两条退出路径的资源清理**不对称**：
+//
+//	路径 A（SIGTERM）: return 到 main → defer CloseAll ✓
+//	路径 B（exit 42）: os.Exit 跳过 defer            ✗
+//
+// 而路径 B 是**每次热更新都走**的（guard 靠 exit 42 判定"主动重启"）。
+// 后果是这些写者从不 flush：
+//   · docStore.Stop()  → flush()   文档索引可能陈旧
+//   · distiller.Stop() → flush()   待蒸馏规则丢失
+//   · textMem.Stop()   → Close()   文本记忆未落盘
+//
+// ## 判据怎么咬
+//
+// 不能靠"源码里有 os.Exit 吗"（写意不写实）。这里用 **AST** 检查
+// `waitForShutdown` 函数体里**在 os.Exit 之前**确实调用了传入的
+// stopKernelModules 形参 —— 即"退出前显式关闭"，而不是靠 defer。
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"testing"
+)
+
+// ★★★ 判据：waitForShutdown 在 os.Exit 之前显式调用 stopKernelModules。
+func TestWaitForShutdownClosesModulesBeforeExit(t *testing.T) {
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, "bootstrap.go", nil, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var fn *ast.FuncDecl
+	for _, d := range f.Decls {
+		if fd, ok := d.(*ast.FuncDecl); ok && fd.Name.Name == "waitForShutdown" {
+			fn = fd
+		}
+	}
+	if fn == nil {
+		t.Fatal("找不到 waitForShutdown")
+	}
+
+	// 找 os.Exit 与 stopKernelModules() 调用的相对位置（按字节偏移）
+	exitPos := token.NoPos
+	closePos := token.NoPos
+	ast.Inspect(fn, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		if sel, ok := call.Fun.(*ast.SelectorExpr); ok {
+			if id, ok := sel.X.(*ast.Ident); ok && id.Name == "os" && sel.Sel.Name == "Exit" {
+				if !exitPos.IsValid() {
+					exitPos = call.Pos()
+				}
+			}
+		}
+		if id, ok := call.Fun.(*ast.Ident); ok && id.Name == "stopKernelModules" {
+			if !closePos.IsValid() {
+				closePos = call.Pos()
+			}
+		}
+		return true
+	})
+
+	if !exitPos.IsValid() {
+		t.Fatal("waitForShutdown 里没有 os.Exit（重启路径怎么退出的？）")
+	}
+	if !closePos.IsValid() {
+		t.Fatal("★ waitForShutdown 从未调用 stopKernelModules ⇒ " +
+			"热更新路径（os.Exit 跳过 defer）下模块关闭/落盘全部被跳过")
+	}
+	if closePos > exitPos {
+		t.Fatal("★ stopKernelModules 在 os.Exit **之后** ⇒ 永远不会执行" +
+			"（os.Exit 立即终止进程）")
+	}
+}
+
+// ★★★ 判据：main 必须把真实的 ks.CloseAll 传给 waitForShutdown（不是空函数）。
+func TestMainWiresRealCloseAllIntoShutdown(t *testing.T) {
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, "main.go", nil, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	found := false
+	ast.Inspect(f, func(n ast.Node) bool {
+		call, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		id, ok := call.Fun.(*ast.Ident)
+		if !ok || id.Name != "waitForShutdown" {
+			return true
+		}
+		// 最后一个实参必须是含有 CloseAll 调用的函数字面量
+		for _, a := range call.Args {
+			lit, ok := a.(*ast.FuncLit)
+			if !ok {
+				continue
+			}
+			ast.Inspect(lit, func(m ast.Node) bool {
+				if c, ok := m.(*ast.CallExpr); ok {
+					if sel, ok := c.Fun.(*ast.SelectorExpr); ok && sel.Sel.Name == "CloseAll" {
+						found = true
+					}
+				}
+				return true
+			})
+		}
+		return true
+	})
+	if !found {
+		t.Fatal("★ main 传给 waitForShutdown 的 stopKernelModules 里没有 CloseAll ⇒ " +
+			"热更新路径下模块不会被关闭（传了个空函数？）")
+	}
+}
diff --git a/cmd/homed/shutdown_idempotent_test.go b/cmd/homed/shutdown_idempotent_test.go
new file mode 100644
index 00000000..44b0c510
--- /dev/null
+++ b/cmd/homed/shutdown_idempotent_test.go
@@ -0,0 +1,113 @@
+package main
+
+// 退出路径的**幂等性**判据（2026-10-17）。
+//
+// ## 为什么必须有这条
+//
+// 实测 panic（真机 SIGTERM）：
+//
+//	panic: close of closed channel
+//	goroutine 1 [running]:
+//	main.startHeartbeat.func3()  bootstrap.go:259
+//	main.main()                  main.go:293
+//
+// 根因：`startHeartbeat` 返回的 stop 函数是裸的 `close(hbStop)`，
+// 而它有**两个**调用点：
+//   - main.go 的 `defer stopHeartbeatEarly()`
+//   - waitForShutdown 里显式 `stopHeartbeat()`
+//
+// ⇒ 第二次 close 必然 panic。
+//
+// ## 为什么这条缺陷很值得守
+//
+// 它发生在**退出路径的最后一步**：进程已经把所有清理做完了，
+// 却在收尾时崩溃 ⇒ 退出码从 0 变成 2（panic）⇒
+// systemd/guard 把它判成"异常退出"而不是"正常停止"，
+// 进而触发**不必要的重启/告警**。而功能上一切正常，
+// 排查方向会被引向"是不是哪里崩了"。
+//
+// ## 判据形态
+//
+// 断言「close(停止通道) 必须被 sync.Once（或等价）保护」。
+// 这是"模式存在性"，源码扫描恰当；行为验证由真机 SIGTERM 做
+// （已实测：修前 panic、修后 `[homed] stopped` 且 0 panic）。
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+// ★★★ 判据：startHeartbeat 的 stop 函数必须幂等。
+func TestStartHeartbeatStopIsIdempotent(t *testing.T) {
+	src, err := os.ReadFile("bootstrap.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	code := string(src)
+
+	// 找 startHeartbeat 函数体
+	i := strings.Index(code, "func startHeartbeat(")
+	if i < 0 {
+		t.Skip("startHeartbeat 已改名/搬走，请同步更新判据")
+	}
+	end := strings.Index(code[i:], "\n}\n")
+	if end < 0 {
+		t.Fatal("找不到 startHeartbeat 结尾")
+	}
+	body := code[i : i+end]
+
+	// 必须返回 stop 函数
+	if !strings.Contains(body, "return func()") {
+		t.Skip("stop 函数的形态已变，请同步更新判据")
+	}
+	// ★ 核心：裸 close 是缺陷
+	if strings.Contains(body, "return func() { close(") {
+		t.Fatal("★ startHeartbeat 的 stop 函数是**裸的 close()** —— " +
+			"而它有两个调用点（main 的 defer + waitForShutdown 的显式调用）\n" +
+			"   ⇒ 第二次 close 必然 panic: close of closed channel\n" +
+			"   ⇒ 退出码从 0 变 2 ⇒ systemd/guard 判成异常退出并重启。\n" +
+			"   修法：用 sync.Once 保护。")
+	}
+	// 正向：必须有 sync.Once（或至少 Once.Do）
+	if !strings.Contains(body, "sync.Once") && !strings.Contains(body, ".Do(") {
+		t.Error("★ startHeartbeat 的 stop 函数没有幂等保护（sync.Once）")
+	}
+}
+
+// ★★★ 判据：**所有**返回 stop 函数的启动函数都必须幂等。
+//
+// 一般化：本仓的 stop 函数习惯上既被 defer 调、又被显式调，
+// 裸 close 是通用的坑。
+func TestNoBareChannelCloseInStopFunctions(t *testing.T) {
+	entries, err := os.ReadDir(".")
+	if err != nil {
+		t.Fatal(err)
+	}
+	bad := 0
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".go") ||
+			strings.HasSuffix(e.Name(), "_test.go") {
+			continue
+		}
+		b, err := os.ReadFile(e.Name())
+		if err != nil {
+			continue
+		}
+		lines := strings.Split(string(b), "\n")
+		for idx, ln := range lines {
+			trim := strings.TrimSpace(ln)
+			// 只查"返回 stop 函数且其中裸 close"的形态
+			if !strings.Contains(trim, "return func()") {
+				continue
+			}
+			// 同一行内联形态：return func() { close(x) }
+			if strings.Contains(trim, "close(") && !strings.Contains(trim, "Do(") {
+				t.Errorf("★ %s:%d 返回的 stop 函数是裸 close（调用两次即 panic）: %s",
+					e.Name(), idx+1, trim)
+				bad++
+			}
+		}
+	}
+	_ = bad
+}
diff --git a/cmd/mock-server/main.go b/cmd/mock-server/main.go
index f9d5cd15..55827bd6 100644
--- a/cmd/mock-server/main.go
+++ b/cmd/mock-server/main.go
@@ -26,11 +26,11 @@ type Kernel struct {
 }
 
 type Setting struct {
-	Settings map[string]interface{}            `json:"settings"`
-	Meta     map[string]interface{}            `json:"meta"`
-	Plugins  []string                          `json:"plugins"`
-	PluginMeta map[string]interface{}          `json:"plugin_meta"`
-	DisabledPlugins []string                   `json:"disabled_plugins"`
+	Settings        map[string]interface{} `json:"settings"`
+	Meta            map[string]interface{} `json:"meta"`
+	Plugins         []string               `json:"plugins"`
+	PluginMeta      map[string]interface{} `json:"plugin_meta"`
+	DisabledPlugins []string               `json:"disabled_plugins"`
 }
 
 type Plugin struct {
@@ -42,12 +42,12 @@ type Plugin struct {
 }
 
 type PluginInfo struct {
-	Name        string        `json:"name"`
-	Description string        `json:"description"`
-	Version     string        `json:"version"`
-	Enabled     bool          `json:"enabled"`
-	Builtin     bool          `json:"builtin"`
-	Tools       []PluginTool  `json:"tools"`
+	Name        string       `json:"name"`
+	Description string       `json:"description"`
+	Version     string       `json:"version"`
+	Enabled     bool         `json:"enabled"`
+	Builtin     bool         `json:"builtin"`
+	Tools       []PluginTool `json:"tools"`
 }
 
 type PluginTool struct {
@@ -518,4 +518,4 @@ func main() {
 	log.Printf("设备桥 WS: ws://0.0.0.0%s/api/v1/device/ws", addr)
 	log.Printf("==============================")
 	log.Fatal(http.ListenAndServe(addr, server.middleware(mux)))
-}
\ No newline at end of file
+}
diff --git a/cmd/mock-server/ws.go b/cmd/mock-server/ws.go
index 9d95df6c..35b2d98c 100644
--- a/cmd/mock-server/ws.go
+++ b/cmd/mock-server/ws.go
@@ -469,4 +469,4 @@ func (s *MockServer) handleDeviceWS(w http.ResponseWriter, r *http.Request) {
 		s.mu.Unlock()
 	}
 	log.Printf("[ws] 设备断开")
-}
\ No newline at end of file
+}
diff --git a/cmd/waiter/daemon.go b/cmd/waiter/daemon.go
index 1108e4c0..c520262a 100644
--- a/cmd/waiter/daemon.go
+++ b/cmd/waiter/daemon.go
@@ -15,6 +15,7 @@ import (
 	"time"
 
 	"github.com/JianFeeeee/HomeAgent/internal/devicebridge/client"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 )
 
 // ---------------------------------------------------------------------------
@@ -38,6 +39,7 @@ type msgEntry struct {
 }
 
 type daemonHandler struct {
+	stopOnce sync.Once
 	// homed 连接
 	homeMu   sync.Mutex
 	homeConn net.Conn
@@ -255,7 +257,7 @@ func runDaemon(cfg *Config) {
 	go func() {
 		<-sigCh
 		log.Printf("[daemon] shutting down")
-		close(dh.stopCh)
+		safeclose.Safe(&dh.stopOnce, dh.stopCh)
 		dh.closeHome()
 		ln.Close()
 	}()
diff --git a/cmd/waiter/main.go b/cmd/waiter/main.go
index 07b2142d..da5789e5 100644
--- a/cmd/waiter/main.go
+++ b/cmd/waiter/main.go
@@ -13,6 +13,7 @@ import (
 	"time"
 
 	"github.com/JianFeeeee/HomeAgent/internal/meta"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 )
 
 const (
@@ -47,6 +48,7 @@ func startSpinner(label string) func() {
 	}
 	done := make(chan struct{})
 	var once sync.Once
+	var doneOnce sync.Once
 	go func() {
 		ticker := time.NewTicker(80 * time.Millisecond)
 		defer ticker.Stop()
@@ -63,7 +65,7 @@ func startSpinner(label string) func() {
 	}()
 	stop := func() {
 		once.Do(func() {
-			close(done)
+			safeclose.Safe(&doneOnce, done)
 			fmt.Print(clearLine)
 		})
 	}
diff --git a/cmd/waiter/raw_windows.go b/cmd/waiter/raw_windows.go
index 8d2f7696..f8ddd459 100644
--- a/cmd/waiter/raw_windows.go
+++ b/cmd/waiter/raw_windows.go
@@ -9,14 +9,14 @@ import (
 )
 
 var (
-	kernel32                       = syscall.NewLazyDLL("kernel32.dll")
-	procGetConsoleMode             = kernel32.NewProc("GetConsoleMode")
-	procSetConsoleMode             = kernel32.NewProc("SetConsoleMode")
-	procGetStdHandle               = kernel32.NewProc("GetStdHandle")
+	kernel32           = syscall.NewLazyDLL("kernel32.dll")
+	procGetConsoleMode = kernel32.NewProc("GetConsoleMode")
+	procSetConsoleMode = kernel32.NewProc("SetConsoleMode")
+	procGetStdHandle   = kernel32.NewProc("GetStdHandle")
 )
 
 const (
-	stdInputHandle  = ^uint32(9) + 1 // -10
+	stdInputHandle                  = ^uint32(9) + 1 // -10
 	enableVirtualTerminalProcessing = 0x0004
 	enableProcessedOutput           = 0x0001
 	enableWrapAtEOLOutput           = 0x0002
diff --git a/cmd/waiter/state.go b/cmd/waiter/state.go
index eb52be0f..c42e60f8 100644
--- a/cmd/waiter/state.go
+++ b/cmd/waiter/state.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"sync"
 )
 
@@ -171,11 +172,12 @@ func (s *State) ReadLoop(ctx context.Context, cb func(string)) {
 			return
 		}
 		done := make(chan struct{})
+		var doneOnce sync.Once
 		var line string
 		var readErr error
 		go func() {
 			line, readErr = c.ReadLine()
-			close(done)
+			safeclose.Safe(&doneOnce, done)
 		}()
 		select {
 		case <-done:
diff --git a/deploy/depgraph-decls.json b/deploy/depgraph-decls.json
new file mode 100644
index 00000000..9797f133
--- /dev/null
+++ b/deploy/depgraph-decls.json
@@ -0,0 +1,18 @@
+{
+  "_comment": "内核模块依赖声明（过渡期形态）。模块接口接入后由登记包自动产出，此文件废止。",
+  "_note": "requires 是\"我需要谁已就绪\"（设施名），不是\"我要在谁之后\"。",
+  "modules": [
+    {"name": "config",   "provides": ["config", "config-write"]},
+    {"name": "security", "provides": ["crypto", "keystore"], "requires": ["config"]},
+    {"name": "memory",   "provides": ["memory"],   "requires": ["config"]},
+    {"name": "lua",      "provides": ["lua"],      "requires": ["config"]},
+    {"name": "llm",      "provides": ["llm"],      "requires": ["lua", "keystore"]},
+    {"name": "tracker",  "provides": ["tracker"],  "requires": ["config"]},
+    {"name": "textmem",  "provides": ["textmem"],  "requires": ["config"]},
+    {"name": "docmem",   "provides": ["docmem"],   "requires": ["config"]},
+    {"name": "knowledge","provides": ["knowledge"],"requires": ["config", "docmem"]},
+    {"name": "multimodal","provides": ["multimodal"],"requires": ["config"]},
+    {"name": "stagehost","provides": ["stagehost","plugins"], "requires": ["memory", "textmem"]},
+    {"name": "agent",    "provides": ["agent"],    "requires": ["llm", "memory", "stagehost", "tracker", "knowledge"]}
+  ]
+}
diff --git a/deploy/homeagent.service b/deploy/homeagent.service
index 1a90826a..013ac613 100644
--- a/deploy/homeagent.service
+++ b/deploy/homeagent.service
@@ -1,18 +1,93 @@
 [Unit]
-Description=HomeAgent - Personal AI Home Assistant
+Description=HomeAgent - 24/7 AI Butler
 Documentation=https://github.com/trueagent/HomeAgent
 After=network-online.target docker.service
 Wants=network-online.target
 
+# ★★ 为什么默认就走 guard（父守护）模式（2026-10-17 对齐本机生产实例）
+#
+# guard 是**双进程**架构：
+#   homed --role=guard  只负责拉起/看护 worker，自己不初始化内核
+#   homed --role=agent  worker，跑真正的新版模块化启动（依赖图定序 + BFS 分层）
+#
+# 它带来的能力是单进程模式**没有**的：
+#   · 崩溃自愈：worker 崩了 guard 用**当前二进制**重新拉起
+#   · 安全模式：连续崩溃超 max_restarts → 自动进 failback 受限启动
+#     （只加载 webui/pluginmgr/recoverydiag，跑恢复梯子）
+#   · 卡死检测：IPC PING + 心跳 mtime，带启动宽限
+#   · 热更新：worker 以 exit 42 优雅退出 → guard 用新二进制重拉，
+#     **不经过 systemd**、不计崩遣次数、guard 进程保持存活
+#
+# 为什么不是 drop-in：单文件发行时 drop-in 容易被漏装。写在主单元里，
+# 装完即是生产同款行为。要回退成单进程，只需把 ExecStart 的 --role=guard 去掉。
+
 [Service]
-Type=simple
-ExecStart=/usr/bin/homed -data /var/lib/homeagent
+# Type=exec（不是 simple）：simple 会在 fork 后**立刻**认为启动完成，
+# 于是 ExecStartPost 与 LoadCredential 的建立可能竞争。exec 会等到
+# exec() 真正成功才继续，凭据目录与 ExecStartPost 的顺序才是确定的。
+Type=exec
+
+# ★ guard 模式（与本机生产实例一致）。
+#   数据目录默认 /var/lib/homeagent（Debian 惯例）；迁移到别的目录时
+#   必须**同时**改这里和 core.daemon.data_dir —— 两者不等价，见 README。
+ExecStart=/usr/bin/homed --role=guard --data /var/lib/homeagent
+
 Restart=always
 RestartSec=10
-Environment=ONNXRUNTIME_DIR=/usr/lib/homeagent/onnxruntime
+
+# ★ 指数退避（对齐本机 zz-restart-backoff.conf）
+#
+# 为什么需要：RestartSec=10 是**固定**间隔，而 StartLimitBurst/Interval
+# 在这些长驻 agent 上是故意放松的（收紧会让故障单元进入终态 failed、
+# 必须人工 reset-failed —— 与"自愈"相反）。结果就是一个永久坏掉的服务
+# 以固定频率无限重试，systemd 一句都不说。
+# 实测（2026-09-05，llmsproxy）：每 5 秒拉一次，连拉 79 分钟 = 836 次重启。
+#
+# RestartSteps 让间隔从 RestartSec 起指数递增到 RestartMaxDelaySec：
+# 崩溃循环会衰减到每 5 分钟一次，服务不会被放弃（病根修好后自己回来），
+# 日志也不再被刷爆。
+RestartSteps=6
+RestartMaxDelaySec=5min
+
+# 关机上限 25s（对齐本机 zz-shutdown-timeout.conf）。
+# 实测本服务正常退出 <1s；给 guard 转发 SIGTERM → 等 worker → Kill 留足余量，
+# 而默认 90s 在本机从未用到，属于纯粹的风险敞口。
+TimeoutStopSec=25s
+
+# KillMode=control-group（默认）：guard 与 worker 同 cgroup，
+# 一起收，双保险不留孤儿进程。
+KillMode=control-group
+
+WorkingDirectory=/var/lib/homeagent
 StateDirectory=homeagent
-StartLimitBurst=3
-StartLimitInterval=60s
+Environment=HOME=/root
+# onnx 运行库随包安装（不在 /opt，见 packaging/package-linux.sh）
+Environment=ONNXRUNTIME_DIR=/usr/lib/homeagent/onnxruntime
+
+# ★ 主密钥生产注入（security/key.go）
+#
+# 优先级：LoadCredential > HOMED_SECURITY_KEY(env) > <datadir>/security.key
+#
+# 为何用 LoadCredential：环境变量对同用户进程**可见**
+# （/proc/<pid>/environ），任何以该用户身份运行的进程都能读到主密钥。
+# LoadCredential 把内容放到 tmpfs（$CREDENTIALS_DIRECTORY，仅本进程 0400），
+# 不在磁盘留副本、也不进 environ。
+#
+# 生成密钥（一次性，然后妥善保管）：
+#   head -c 32 /dev/urandom | xxd -p -c 64 | sudo tee /etc/homeagent/security.key
+#   sudo chmod 600 /etc/homeagent/security.key
+#
+# ⚠ 该文件就是数据的主密钥：**丢了它，已加密的变量全部解不开**（响亮失败，
+#   不会静默重建）。请与备份一并保管。
+#
+# ⚠ 未配置时**不要**留一个空文件 —— 凭据目录一旦被设置而凭据缺失，内核会
+#   **拒绝启动**（不静默回退到磁盘密钥）。若要用磁盘密钥路径，删掉下面这行。
+#
+# ⚠ 从旧版（/var/lib/homeagent/security.key 磁盘钥）升级时：
+#   内核支持"磁盘钥 + 内嵌钥"并存解密（AdditionalDecryptKeys），
+#   所以先放 /etc/homeagent/security.key 与旧磁盘钥**同一份内容**再启用本行，
+#   否则旧密文解不开。
+LoadCredential=homed_security_key:/etc/homeagent/security.key
 
 # Security hardening
 NoNewPrivileges=true
@@ -21,6 +96,10 @@ ProtectHome=true
 PrivateTmp=true
 PrivateDevices=false
 DevicePolicy=closed
+# 只允许读主密钥所在目录，其余系统路径保持只读
+ReadOnlyPaths=/etc/homeagent
+# 插件需要写自己目录 + 数据目录 + 插件沙箱
+ReadWritePaths=/var/lib/homeagent
 # Audio devices
 DeviceAllow=/dev/snd rw
 DeviceAllow=/dev/dsp rw
diff --git a/deploy/packaging/build.sh b/deploy/packaging/build.sh
index f934dd2d..51c0eaeb 100644
--- a/deploy/packaging/build.sh
+++ b/deploy/packaging/build.sh
@@ -9,11 +9,64 @@ set -euo pipefail
 # 跨平台构建从那次起一直是坏的（Makefile 的单平台 build 不走这里，所以没暴露）。
 PROJECT_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
 BUILD_DIR="${PROJECT_ROOT}/build"
-VERSION="${VERSION:-$(git -C "$PROJECT_ROOT" describe --tags --dirty 2>/dev/null || echo "0.8.0")}"
+# ★★ VERSION 必须是**语义化版本**（x.y.z），不能是 git describe 的原样输出。
+#
+# 2026-10-17 实测事故：当前分支没有 tag，`git describe` 回退成分支名
+#   backup/pre-identity-rewrite-20261005-51-g03d87a4e-dirty
+# 它被注入 meta.Version ⇒ 插件握手的主版本判据变成
+#   MajorVersion("backup/pre-...") = 整个字符串（没有 '.' 可截）
+# 而插件端是 "4" ⇒ **所有子进程插件握手失败**：
+#   proc: xxx.handshake: 主版本不匹配（内核 backup/pre-...，插件 SDK 1.4.0）
+# 内核自己是活的，但 40 个插件一个都起不来 —— 看起来像"插件全坏了"。
+#
+# 权威来源是 internal/meta/meta.go 的 Version 常量（发版时人工确认）。
+# git describe 只在**形如 vX.Y.Z-...** 时才可用（那说明确实在 tag 之后）。
+_meta_version() {
+  local mv
+  mv="$(sed -n 's/^[[:space:]]*Version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' \
+        "$PROJECT_ROOT/internal/meta/meta.go" 2>/dev/null | head -1)"
+  case "$mv" in
+    [0-9]*.[0-9]*.[0-9]*) printf '%s' "$mv"; return 0 ;;
+  esac
+  return 1
+}
+if [ -z "${VERSION:-}" ]; then
+  _gd="$(git -C "$PROJECT_ROOT" describe --tags --dirty 2>/dev/null || true)"
+  case "$_gd" in
+    v[0-9]*.[0-9]*.[0-9]*) VERSION="${_gd#v}" ;;
+    *)
+      # ★ 不是 tag 描述 ⇒ 拒绝用它。退回 meta.Version（当前分支的权威版本）。
+      if VERSION="$(_meta_version)"; then
+        [ -n "$_gd" ] && echo "[BUILD] warn: git describe 给出非版本串（$_gd），改用 meta.Version=$VERSION" >&2
+      else
+        echo "[BUILD] ERROR: 拿不到合法版本号（git describe=$_gd，meta.Version 也读不出）。" >&2
+        echo "        请显式传 VERSION=x.y.z 后重试。" >&2
+        exit 1
+      fi
+      ;;
+  esac
+fi
+# 最终守卫：非 x.y.z 一律拒绝构建（否则会打出一个"插件全部握手失败"的包）
+case "$VERSION" in
+  [0-9]*.[0-9]*.[0-9]*) ;;
+  *) echo "[BUILD] ERROR: VERSION='$VERSION' 不是语义化版本 x.y.z；" \
+          "它会被当作插件协议主版本，导致所有子进程插件握手失败。" >&2
+     exit 1 ;;
+esac
 COMMIT="${COMMIT:-$(git -C "$PROJECT_ROOT" rev-parse --short HEAD 2>/dev/null || echo "unknown")}"
 BUILD_TIME="${BUILD_TIME:-$(date -u '+%Y-%m-%dT%H:%M:%SZ')}"
 GO="${GO:-$(command -v go 2>/dev/null || echo "go")}"
-LDFLAGS="-X gitcode.com/JianFeeeee/HomeAgent/internal/meta.Version=${VERSION} -X gitcode.com/JianFeeeee/HomeAgent/internal/meta.Commit=${COMMIT} -X gitcode.com/JianFeeeee/HomeAgent/internal/meta.BuildTime=${BUILD_TIME}"
+# ★★ 模块路径必须是**当前**的 github.com/...，不能是历史的 gitcode.com/...
+#
+# `-X` 的包路径写错时 Go **不报错、静默忽略** ⇒ 注入的值保持源码默认
+# （Commit/BuildTime 变成字面量 "unknown"，Version 变成源码里的版本号）。
+# 构建日志全绿，只有 `binary --version` 才能看出来 —— 于是发行包带着
+# 错的溯源信息发出去。
+#
+# 实测（2026-10-17）：用旧路径构建 waiter，`--version` 输出
+#   `waiter 1.4.0 (commit unknown, built unknown)`
+# 而正确路径得到注入的值。
+LDFLAGS="-X github.com/JianFeeeee/HomeAgent/internal/meta.Version=${VERSION} -X github.com/JianFeeeee/HomeAgent/internal/meta.Commit=${COMMIT} -X github.com/JianFeeeee/HomeAgent/internal/meta.BuildTime=${BUILD_TIME}"
 
 # 版本与提交的**权威来源**是上面注入的 meta.Version / meta.Commit，不是 Go 自带的
 # VCS 戳。后者不进 build cache key（Go 文档明确说明 VCS 变化不会触发重建），
@@ -138,9 +191,28 @@ build_homed() {
   local _tags="${HOMED_TAGS-onnxruntime}"
   local -a _tagargs=()
   if [ -n "$_tags" ]; then _tagargs=(-tags "$_tags"); fi
+
+  # ★★ homed 必须与**它自己的**启动依赖图一起产出（2026-10-17 实测缺陷）。
+  #
+  # 内核启动时比对「磁盘图 digest」vs「二进制内嵌 digest」，不一致或读不到
+  # ⇒ **拒绝启动**（退出码 1）。本脚本原先既不生成图也不注入 digest
+  # ⇒ 用 `deploy/packaging/build.sh` 打出的 homed 装到机器上**起不来**：
+  #   kernelboot: 生产构建（内嵌 hash 非空）但读不到依赖图 …
+  #
+  # 注意这与 Makefile 是**两条独立构建路径**：只修 Makefile 不够。
+  # 图必须由**同一次构建**产出（digest 一一对应），不能复用别的版本的图。
+  local _graphgen="$BUILD_DIR/homed-depgraph${SUFFIX:+_$SUFFIX}"
+  echo "  [graph] 生成启动依赖图（编译期定序）..."
+  CGO_ENABLED=1 CC="$_cc" "$GO" build ${_tagargs[@]+"${_tagargs[@]}"} \
+    -o "$_graphgen" ./cmd/homed-depgraph/
+  local _graph_hash
+  _graph_hash="$("$_graphgen" -digest)"
+  "$_graphgen" -out "$BUILD_DIR/depgraph.bin"
+  echo "  [graph] digest=$_graph_hash"
+
   CGO_ENABLED=1 CC="$_cc" "$GO" build -buildvcs=false -trimpath -installsuffix dynlink \
     ${_tagargs[@]+"${_tagargs[@]}"} \
-    -ldflags "$LDFLAGS" -o "$out" ./cmd/homed/
+    -ldflags "$LDFLAGS -X github.com/JianFeeeee/HomeAgent/internal/kernelboot.EmbeddedGraphHash=$_graph_hash" -o "$out" ./cmd/homed/
   echo "  OK ($(file "$out" | sed 's/.*: //') | $(du -h "$out" | cut -f1))"
 }
 
diff --git a/deploy/packaging/linux/deb/control-toolchain b/deploy/packaging/linux/deb/control-toolchain
new file mode 100644
index 00000000..8f888449
--- /dev/null
+++ b/deploy/packaging/linux/deb/control-toolchain
@@ -0,0 +1,22 @@
+Package: homeagent-toolchain
+Version: VERSION_PLACEHOLDER
+Architecture: ARCH_PLACEHOLDER
+Maintainer: HomeAgent Team <team@homeagent.ai>
+Installed-Size: INSTALLED_SIZE_PLACEHOLDER
+Depends: libc6 (>= 2.28), libstdc++6, libgcc-s1
+Section: utils
+Priority: optional
+Homepage: https://github.com/trueagent/HomeAgent
+Description: HomeAgent Toolchain (Daemon + CLI + Plugin Toolchain + SDK)
+ HomeAgent is a personal AI home assistant that integrates
+ large language models with system automation.
+ .
+ This package includes the full development toolchain:
+  - homed: the core daemon (background service, onnxruntime enabled)
+  - depgraph.bin: kernel startup dependency graph (MUST sit next to homed)
+  - waiter: command-line client
+  - hmapdev: plugin build toolchain (init/build/package .hmap)
+  - the matching HomeAgent SDK (sdk/, tools/, skills/, meta/, docs/)
+ .
+ Installs the SDK under /usr/lib/homeagent/sdk so that hmapdev can resolve
+ plugins against a known-good SDK without network access.
diff --git a/deploy/packaging/package-linux.sh b/deploy/packaging/package-linux.sh
index eaf69482..14fcfa8d 100644
--- a/deploy/packaging/package-linux.sh
+++ b/deploy/packaging/package-linux.sh
@@ -4,7 +4,41 @@ set -euo pipefail
 PROJECT_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
 BUILD_DIR="${PROJECT_ROOT}/build"
 DIST_DIR="${PROJECT_ROOT}/dist/linux"
-VERSION="${VERSION:-$(git -C "$PROJECT_ROOT" describe --tags --dirty 2>/dev/null || echo "0.8.0")}"
+# ★★ VERSION 解析必须与 build.sh 用**同一套规则**（2026-10-17 统一）。
+#
+# 原实现只看 git describe，而无 tag 分支上它返回**分支名**：
+#   backup/pre-identity-rewrite-20261005-56-g98850e1
+# 下面的守卫会拒绝它（正确），但要求人**手动传 VERSION** 才能打包 ——
+# 而 build.sh 早已能自动回退到 meta.Version。两个脚本行为不一致的结果是：
+# 同一个版本，走 build.sh 打得出来，走 package-linux.sh 打不出来。
+#
+# 更要紧的是：若有人为了"让它跑通"去掉守卫，分支名就会进 meta.Version，
+# 而那是**插件协议主版本**的来源 ⇒ 22 个子进程插件全部握手失败（真事故）。
+#
+# ⇒ 统一为：git describe 只在形如 vX.Y.Z 时采用，否则回退 meta.Version。
+_meta_version() {
+  local mv
+  mv="$(sed -n 's/^[[:space:]]*Version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' \
+        "$PROJECT_ROOT/internal/meta/meta.go" 2>/dev/null | head -1)"
+  case "$mv" in
+    [0-9]*.[0-9]*.[0-9]*) printf '%s' "$mv"; return 0 ;;
+  esac
+  return 1
+}
+if [ -z "${VERSION:-}" ]; then
+  _gd="$(git -C "$PROJECT_ROOT" describe --tags --dirty 2>/dev/null || true)"
+  case "$_gd" in
+    v[0-9]*.[0-9]*.[0-9]*) VERSION="${_gd#v}" ;;
+    *)
+      if VERSION="$(_meta_version)"; then
+        [ -n "$_gd" ] && echo "[PKG] warn: git describe 给出非版本串（$_gd），改用 meta.Version=$VERSION" >&2
+      else
+        echo "[PKG] ERROR: 拿不到合法版本号（git describe=$_gd）。请显式传 VERSION=x.y.z。" >&2
+        exit 1
+      fi
+      ;;
+  esac
+fi
 
 # git describe 给出的是 v1.0.0-68-gba0b5a1-dirty 这类描述串，它不是合法的包版本：
 # deb 的 Version 必须以数字开头，rpm 的 Version 不允许 '-'（那是版本/发布的分隔符）。
@@ -368,10 +402,79 @@ stage_variant() {
 
   local initconfig_bin="$BUILD_DIR/initconfig_$suffix"
 
+  # ★★ 启动依赖图必须与 homed **同目录**（2026-10-17 实测缺陷）。
+  #
+  # 内核启动时会比对
+  #   「磁盘图的 digest」 vs 「二进制内嵌的 digest」
+  # 读不到图 ⇒ 生产构建（内嵌 hash 非空）**直接拒绝启动**：
+  #   kernelboot: 生产构建（内嵌 hash 非空）但读不到依赖图
+  #               <dir>/depgraph.bin: no such file or directory
+  #   ⇒ 退出码 1，内核完全起不来。
+  #
+  # 原先 stage_variant 只拷 homed/waiter ⇒ **每个 deb/tar 包里的 homed
+  # 都起不来**。实测确认：只放 homed 不放图，启动即失败退出 1。
+  #
+  # 图由 `make build` 产出到 build/depgraph.bin（与 homed 同一次构建，
+  # digest 一一对应；手工复制别的版本的图会 digest 不符，同样拒绝启动）。
+  stage_depgraph() {
+    local staging="$1"
+    if [ -f "$BUILD_DIR/depgraph.bin" ]; then
+      cp "$BUILD_DIR/depgraph.bin" "$staging/usr/bin/depgraph.bin"
+      chmod 644 "$staging/usr/bin/depgraph.bin"
+    else
+      echo "ERROR: 缺少 $BUILD_DIR/depgraph.bin —— 内核与依赖图必须来自同一次构建。" >&2
+      echo "       先跑 make build（它会生成图并注入 digest），再打包。" >&2
+      return 1
+    fi
+  }
+
+  # stage_hmapdev：插件工具链（init/build/package .hmap）
+  #
+  # 放在 /usr/bin 而不是 /usr/lib：它是使用者直接调用的命令，
+  # 与 homed/waiter 同级更符合直觉（hmapdev 自身按 PATH 找 SDK store）。
+  stage_hmapdev() {
+    local staging="$1"
+    local hv
+    hv="$(ls "$BUILD_DIR"/hmapdev* 2>/dev/null | grep -vE '\.(exe)$' | head -1)"
+    if [ -z "$hv" ]; then
+      # 退而求其次：从 SDK 源码现编一个（CGO 无关，快）
+      echo "  [hmapdev] build/ 下没有 hmapdev，尝试现编..."
+      ( cd "$PROJECT_ROOT/third_party/homeagent-sdk/tools/hmapdev" && \
+        CGO_ENABLED=0 go build -trimpath -o "$BUILD_DIR/hmapdev" . ) || {
+        echo "ERROR: 无法获得 hmapdev（插件工具链），拒绝打包。" >&2
+        return 1; }
+      hv="$BUILD_DIR/hmapdev"
+    fi
+    install -m 0755 "$hv" "$staging/usr/bin/hmapdev"
+    echo "  hmapdev:    $hv ($(du -h "$hv" | cut -f1))"
+  }
+
+  # stage_sdk：与本次工具链同源的 SDK 源码（含 sdk/ tools/ skills/ meta/）。
+  #
+  # 为什么要随包发：hmapdev 需要按插件声明的 sdk 版本解析依赖；没有本地 SDK
+  # store 时它会去网上拉（内网/受限出口环境直接失败）。随包带一份 →
+  # 「装完即可离线构建插件」，且版本与内核严格同源（防版本漂移）。
+  stage_sdk() {
+    local staging="$1"
+    local sdk_src="$PROJECT_ROOT/third_party/homeagent-sdk"
+    local sdk_dst="$staging/usr/lib/homeagent/sdk"
+    [ -d "$sdk_src" ] || { echo "ERROR: 找不到 SDK 源码 $sdk_src" >&2; return 1; }
+    mkdir -p "$sdk_dst"
+    for item in go.mod go.sum LICENSE README.md sdk meta tools skills; do
+      [ -e "$sdk_src/$item" ] && cp -a "$sdk_src/$item" "$sdk_dst/"
+    done
+    # 不带陈旧工具链产物：那是上次构建留下的，可能与本次源码不符。
+    rm -rf "$sdk_dst/tools/vscode-hmapdev/node_modules" 2>/dev/null || true
+    local sv
+    sv="$(grep -oE 'Version = "[0-9.]+"' "$sdk_src/meta/meta.go" 2>/dev/null | head -1 | grep -oE '[0-9.]+')"
+    echo "  sdk:        $sdk_dst (v${sv:-?}, $(du -sh "$sdk_dst" | cut -f1))"
+  }
+
   case "$variant" in
     full)
       cp "$BUILD_DIR/homed_$suffix" "$staging/usr/bin/homed"
       cp "$BUILD_DIR/waiter_$suffix" "$staging/usr/bin/waiter"
+      stage_depgraph "$staging"
       cp "$PROJECT_ROOT/deploy/homeagent.service" "$staging/etc/systemd/system/homeagent.service"
       [ -f "$initconfig_bin" ] && cp "$initconfig_bin" "$staging/usr/bin/initconfig"
       stage_setup "$staging"
@@ -382,12 +485,28 @@ stage_variant() {
     server)
       cp "$BUILD_DIR/homed_$suffix" "$staging/usr/bin/homed"
       cp "$BUILD_DIR/waiter_$suffix" "$staging/usr/bin/waiter"
+      stage_depgraph "$staging"
       cp "$PROJECT_ROOT/deploy/homeagent.service" "$staging/etc/systemd/system/homeagent.service"
       [ -f "$initconfig_bin" ] && cp "$initconfig_bin" "$staging/usr/bin/initconfig"
       stage_setup "$staging"
       stage_license "$staging"
       stage_multimodal_assets "$staging"
       ;;
+    toolchain)
+      # 内核 + CLI + 依赖图 + 插件工具链 + SDK（开发者/自建一体化）
+      cp "$BUILD_DIR/homed_$suffix" "$staging/usr/bin/homed"
+      cp "$BUILD_DIR/waiter_$suffix" "$staging/usr/bin/waiter"
+      stage_depgraph "$staging"
+      stage_hmapdev "$staging"
+      stage_sdk "$staging"
+      cp "$PROJECT_ROOT/deploy/homeagent.service" "$staging/etc/systemd/system/homeagent.service"
+      [ -f "$initconfig_bin" ] && cp "$initconfig_bin" "$staging/usr/bin/initconfig"
+      stage_setup "$staging"
+      stage_license "$staging"
+      # ★★ onnx 运行库 + 模型必须进包（用户明确要求，2026-10-17）。
+      # 否则装到干净机器上「默认启用但用不了」——本地向量空间会静默降级。
+      stage_multimodal_assets "$staging"
+      ;;
     client)
       cp "$BUILD_DIR/waiter_$suffix" "$staging/usr/bin/waiter"
       stage_license "$staging"
@@ -723,7 +842,7 @@ main() {
   # 不重算 SHA256SUMS，旧的它会一直躺在 dist 里，看上去像在为这一批残缺产物背书。
   rm -f "$DIST_DIR/SHA256SUMS"
 
-  for variant in full server client; do
+  for variant in full server client toolchain; do
     echo ""
     echo "=============================================="
     echo "  Packaging: $variant"
diff --git a/deploy/packaging/packaging_test.go b/deploy/packaging/packaging_test.go
new file mode 100644
index 00000000..0b5b06fc
--- /dev/null
+++ b/deploy/packaging/packaging_test.go
@@ -0,0 +1,176 @@
+package packaging_test
+
+// 发行打包脚本的**结构性判据**（2026-10-17）。
+//
+// ## 为什么必须有这组判据
+//
+// 这轮打包实测撞到 **4 个「包打出来了、装上去不能用」**的缺陷，
+// 而且它们**全部**满足「构建日志全绿 + 脚本退出码 0」：
+//
+//  1. `package-linux.sh` **完全不拷 `depgraph.bin`**
+//     ⇒ 内核启动校验失败：`生产构建（内嵌 hash 非空）但读不到依赖图`
+//     ⇒ **退出码 1，内核根本起不来**（实测确认）。
+//  2. `deploy/packaging/build.sh` 的 `build_homed` **不生成图、不注入 digest**
+//     ⇒ 与 (1) 同因，另一条独立构建路径。
+//  3. `build.sh` 的 `LDFLAGS` 用**历史模块路径 `gitcode.com/`**
+//     ⇒ `-X` 静默失效（Go 对未知包路径不报错）⇒ 发行包 `--version`
+//     全是 `unknown`（实测：`waiter 1.4.0 (commit unknown, built unknown)`）。
+//  4. （Makefile 侧）`-ldflags` 用**单引号**包 `$$GRAPH_HASH`
+//     ⇒ 注入字面量 `$GRAPH_HASH` ⇒ 同 (1)。已在
+//     `internal/kernelboot/makefile_inject_test.go` 守。
+//
+// ## 判据形态：源码扫描（此处**恰当**）
+//
+// 断言的是"这些脚本里**存在**某个必需的处置"（拷贝 depgraph / 用当前模块
+// 路径 / 拒绝缺资产），属于"模式存在性"，不是接线或顺序断言
+// —— 后者用源码扫描会骗人（见 docs/zh/kernel-modularization-design.md §8.6）。
+//
+// 端到端验证（真的装 deb 再跑内核）由发版流程做；这里守的是"结构性缺失"
+// 这一类，它比端到端更早、更便宜。
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+const (
+	pkgLinux = "../../deploy/packaging/package-linux.sh"
+	buildSh  = "../../deploy/packaging/build.sh"
+	makefile = "../../Makefile"
+)
+
+func readOrSkip(t *testing.T, p string) string {
+	t.Helper()
+	b, err := os.ReadFile(p)
+	if err != nil {
+		t.Skipf("读不到 %s: %v", p, err)
+	}
+	return string(b)
+}
+
+// ★★★ 判据：打包时必须把 `depgraph.bin` 放进与 homed **同目录**。
+//
+// 违反后果（实测）：内核启动即失败退出 1 ——
+//
+//	kernelboot: 生产构建（内嵌 hash 非空）但读不到依赖图 <dir>/depgraph.bin
+func TestPackageLinuxStagesDepgraph(t *testing.T) {
+	src := readOrSkip(t, pkgLinux)
+	if !strings.Contains(src, "stage_depgraph") {
+		t.Fatal("★ package-linux.sh 没有 stage_depgraph —— " +
+			"打出的包缺依赖图 ⇒ 内核拒绝启动（退出码 1）")
+	}
+	// 必须真的**调用**（定义而不用等于没接）
+	if strings.Count(src, "stage_depgraph \"$staging\"") == 0 {
+		t.Fatal("★ stage_depgraph 定义但从未被调用 —— 图不会进包")
+	}
+	// 必须放到 usr/bin（与 homed 同目录），不能是别处
+	if !strings.Contains(src, "usr/bin/depgraph.bin") {
+		t.Fatal("★ depgraph.bin 必须与 homed 同在 usr/bin —— " +
+			"内核按「可执行文件同目录」找图，放别处等于没有")
+	}
+}
+
+// ★★★ 判据：`build.sh` 构建 homed 时必须**生成图并注入 digest**。
+//
+// 这与 Makefile 是**两条独立构建路径**：只修 Makefile 不够
+// （实测：用 build.sh 打出的 homed 缺图，起不来）。
+func TestPackagingBuildShGeneratesGraphForHomed(t *testing.T) {
+	src := readOrSkip(t, buildSh)
+	if !strings.Contains(src, "homed-depgraph") {
+		t.Fatal("★ deploy/packaging/build.sh 不构建 homed-depgraph —— " +
+			"它无法产出依赖图 ⇒ 该路径打出的 homed 起不来")
+	}
+	if !strings.Contains(src, "EmbeddedGraphHash=") {
+		t.Fatal("★ build.sh 未注入 EmbeddedGraphHash —— " +
+			"即使有图，digest 与二进制不匹配同样拒绝启动")
+	}
+	// 必须用 -digest 拿**真实**的 digest（不能写死/留空）
+	if !strings.Contains(src, "-digest") {
+		t.Fatal("★ build.sh 必须调用 homed-depgraph -digest 取真实 digest")
+	}
+}
+
+// ★★★ 判据：`-X` 的包路径必须是**当前**模块路径（不能是历史 gitcode.com）。
+//
+// Go 对未知 `-X` 路径**静默忽略**（不报错）⇒ 发行包版本/commit 全 unknown。
+func TestPackagingLdflagsUseCurrentModulePath(t *testing.T) {
+	src := readOrSkip(t, buildSh)
+	if strings.Contains(src, "gitcode.com/JianFeeeee/HomeAgent") {
+		t.Fatal("★ build.sh 的 LDFLAGS 用的是**历史**模块路径 " +
+			"`gitcode.com/JianFeeeee/HomeAgent`；当前模块是 " +
+			"`github.com/JianFeeeee/HomeAgent`。\n" +
+			"   `-X` 对未知路径**静默无效** ⇒ 发行包的 Version/Commit/BuildTime " +
+			"全是默认值（实测 --version 输出 unknown）")
+	}
+	if !strings.Contains(src, "github.com/JianFeeeee/HomeAgent/internal/meta.Version") {
+		t.Fatal("★ build.sh 必须用 github.com/... 注入 meta.Version")
+	}
+}
+
+// ★★★ 判据：Makefile 注入依赖图 digest 时引号必须**允许展开**。
+//
+// （与 internal/kernelboot/makefile_inject_test.go 同源，这里从打包视角再守一遍：
+//
+//	打包依赖 Makefile 产出的二进制，所以这条对打包也关键。）
+func TestMakefileInjectsExpandableGraphHash(t *testing.T) {
+	src := readOrSkip(t, makefile)
+	idx := strings.Index(src, "EmbeddedGraphHash=$$GRAPH_HASH")
+	if idx < 0 {
+		t.Skip("Makefile 的注入方式已变，请同步更新判据")
+	}
+	lineStart := strings.LastIndex(src[:idx], "\n") + 1
+	line := src[lineStart:idx]
+	ld := strings.Index(line, "-ldflags")
+	if ld < 0 {
+		return
+	}
+	if strings.Count(line[ld:], "'")%2 == 1 {
+		t.Fatal("★ Makefile 的 -ldflags 用单引号包住 $$GRAPH_HASH ⇒ shell 不展开 " +
+			"⇒ 注入字面量 $GRAPH_HASH ⇒ 内核拒绝启动")
+	}
+}
+
+// ★★★ 判据：onnx 资产缺失时打包必须**拒绝**（不能出「默认启用但用不了」的假包）。
+//
+// 用户明确要求 onnx 的 so 与模型进包；官方脚本的态度是"缺资产就失败"。
+// 这条守的是那个**拒绝**仍然存在。
+func TestPackagingRefusesMissingONNXAssets(t *testing.T) {
+	src := readOrSkip(t, pkgLinux)
+	for _, kw := range []string{"ONNXRUNTIME_LIB", "CHINESECLIP_BUNDLE_DIR"} {
+		if !strings.Contains(src, kw) {
+			t.Errorf("★ package-linux.sh 不再检查 %s —— "+
+				"onnx 资产缺失时会打出「默认启用但装完不能用」的假包", kw)
+		}
+	}
+	// 必须**真的**拒绝：出现 ERROR 且 return 1
+	if !strings.Contains(src, "拒绝打包") {
+		t.Error("★ onnx 资产缺失时打包脚本必须明确拒绝（ERROR + 非零退出）")
+	}
+	// 许可证必须随二进制分发
+	if !strings.Contains(src, "ThirdPartyNotices") {
+		t.Error("★ onnxruntime 的 ThirdPartyNotices 必须随包分发（MIT 要求）")
+	}
+}
+
+// ★★★ 判据：`toolchain` 变体的 control 文件必须存在且描述准确。
+func TestToolchainVariantHasControlFile(t *testing.T) {
+	src := readOrSkip(t, pkgLinux)
+	if !strings.Contains(src, "toolchain") {
+		t.Skip("toolchain 变体已移除，请同步更新判据")
+	}
+	// 变体循环里必须含 toolchain
+	if !strings.Contains(src, "for variant in") || !strings.Contains(src, "toolchain; do") {
+		t.Error("★ 变体循环必须包含 toolchain")
+	}
+	b, err := os.ReadFile("../../deploy/packaging/linux/deb/control-toolchain")
+	if err != nil {
+		t.Fatal("★ 缺 control-toolchain —— toolchain 变体打不出来")
+	}
+	c := string(b)
+	for _, kw := range []string{"homeagent-toolchain", "hmapdev", "SDK", "depgraph"} {
+		if !strings.Contains(c, kw) {
+			t.Errorf("control-toolchain 的描述里应提到 %s（让 apt show 能说清装了什么）", kw)
+		}
+	}
+}
diff --git a/deploy/packaging/version_guard_test.go b/deploy/packaging/version_guard_test.go
new file mode 100644
index 00000000..ca4879d1
--- /dev/null
+++ b/deploy/packaging/version_guard_test.go
@@ -0,0 +1,147 @@
+package packaging
+
+// 构建版本号的判据（2026-10-17 真实事故）。
+//
+// ## 事故
+//
+// `build.sh` 原本写 `VERSION="${VERSION:-$(git describe --tags --dirty)}"`。
+// 当前分支**没有 tag**，git describe 就回退成分支名：
+//
+//	backup/pre-identity-rewrite-20261005-51-g03d87a4e-dirty
+//
+// 它被 `-X ...meta.Version=` 注入内核，而插件握手的主版本判据是
+// `proc.MajorVersion(meta.Version)`：
+//
+//	MajorVersion("backup/pre-...")  ⇒ 没有 '.' ⇒ 返回整串
+//	MajorVersion("1.4.0")           ⇒ "1"
+//
+// 于是内核端 "backup/pre-..." ≠ 插件端 "1" ⇒ **22 个子进程插件全部握手失败**：
+//
+//	proc: weather.handshake: 主版本不匹配（内核 backup/pre-...，插件 SDK 1.4.0）
+//
+// 内核自身是活的、systemd 显示 active、日志里每条都是"插件的问题" ——
+// 看起来像插件坏了，实际是**发行包带着非法版本号**出去。
+//
+// ## 判据怎么咬
+//
+// 直接**执行 build.sh** 的版本解析段（把它的逻辑抽出来跑），
+// 而不是 grep 源码里有没有某句话（那种检查在本仓已骗过我三次）。
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// ★★★ 判据：build.sh 必须拒绝非语义化版本，且能从 meta.Version 回退。
+func TestBuildScriptRejectsNonSemverVersion(t *testing.T) {
+	root := repoRoot(t)
+	script := filepath.Join(root, "deploy", "packaging", "build.sh")
+	b, err := os.ReadFile(script)
+	if err != nil {
+		t.Fatal(err)
+	}
+	src := string(b)
+
+	// ① 必须有"最终守卫"：非 x.y.z 直接 exit 1
+	if !strings.Contains(src, "不是语义化版本") {
+		t.Fatal("★ build.sh 没有拒绝非法版本号的守卫 ⇒ " +
+			"分支名会被当作协议主版本注入内核，导致所有子进程插件握手失败")
+	}
+	// ② 必须能从 meta/meta.go 回退（而不是直接相信 git describe）
+	if !strings.Contains(src, "internal/meta/meta.go") {
+		t.Fatal("★ build.sh 没有从 meta/meta.go 取权威版本 ⇒ " +
+			"无 tag 分支上会拿到 git describe 的分支名")
+	}
+	// ③ git describe 结果必须被**形态校验**过（vX.Y.Z 前缀）
+	if !strings.Contains(src, "v[0-9]*.[0-9]*.[0-9]*") {
+		t.Fatal("★ build.sh 未校验 git describe 输出的形态 ⇒ 分支名会漏过去")
+	}
+}
+
+// ★★★ 判据：meta.Version 本身必须是语义化版本（它是最后一道防线）。
+//
+// 如果 meta.Version 也腐坏，回退逻辑会把坏值当真值用。
+func TestMetaVersionIsSemver(t *testing.T) {
+	root := repoRoot(t)
+	b, err := os.ReadFile(filepath.Join(root, "internal", "meta", "meta.go"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	re := regexp.MustCompile(`(?m)^\s*Version\s*=\s*"([^"]*)"`)
+	m := re.FindSubmatch(b)
+	if m == nil {
+		t.Fatal("找不到 meta.Version")
+	}
+	v := string(m[1])
+	if !regexp.MustCompile(`^[0-9]+\.[0-9]+\.[0-9]+$`).MatchString(v) {
+		t.Fatalf("★ meta.Version=%q 不是 x.y.z ⇒ 插件协议主版本会算错", v)
+	}
+}
+
+// ★★★ 判据：MajorVersion 对非法输入**不能**返回整串而静默通过。
+//
+// 这是事故的放大器：MajorVersion("backup/pre-...") 返回整串，
+// 与插件端的 "1" 不等 —— 至少它会**不匹配**（fail closed，可接受）。
+// 但若有一天有人把判据改成"前缀匹配"，就会静默放行。
+// 本判据钉住当前语义：非法输入返回原串，绝不等于任何合法主版本。
+func TestMajorVersionRejectsNonSemver(t *testing.T) {
+	root := repoRoot(t)
+	cmd := exec.Command("go", "run", "./cmd/versionprobe")
+	cmd.Dir = root
+	cmd.Env = append(os.Environ(), "GOCACHE=/tmp/gocache", "GOPATH=/tmp/gopath",
+		"TMPDIR=/home/program/.gotmp")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Skipf("versionprobe 不可用（%v）：%s", err, out)
+	}
+	s := string(out)
+	// versionprobe 应输出两个主版本，非法输入的那个不得等于 "1" 或 "4"
+	if strings.Contains(s, "BAD_PAIR") {
+		t.Fatalf("★ MajorVersion 把非法版本归一化成了合法主版本 ⇒ "+
+			"坏版本号会静默通过握手：%s", s)
+	}
+}
+
+func repoRoot(t *testing.T) string {
+	t.Helper()
+	wd, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	// deploy/packaging → 上两级
+	return filepath.Dir(filepath.Dir(wd))
+}
+
+// ★★★ 判据：两个打包脚本必须用**同一套**版本解析规则。
+//
+// 2026-10-17 实测不一致：build.sh 已能自动回退 meta.Version，而
+// package-linux.sh 仍只看 git describe ⇒ 同一个版本，走 build.sh 打得出来、
+// 走 package-linux.sh 报"请显式设置 VERSION"。
+//
+// 危害不只是"要手动传参"：运维为了跑通会去掉守卫，而分支名一旦进
+// meta.Version 就是**插件协议主版本** ⇒ 22 个插件全部握手失败（真事故）。
+func TestBothPackagingScriptsShareVersionRules(t *testing.T) {
+	root := repoRoot(t)
+	scripts := map[string]string{
+		"build.sh":         filepath.Join(root, "deploy", "packaging", "build.sh"),
+		"package-linux.sh": filepath.Join(root, "deploy", "packaging", "package-linux.sh"),
+	}
+	for name, pth := range scripts {
+		b, err := os.ReadFile(pth)
+		if err != nil {
+			t.Fatalf("%s: %v", name, err)
+		}
+		src := string(b)
+		// 两者都必须：① 从 meta/meta.go 回退 ② 校验 git describe 形态
+		if !strings.Contains(src, "internal/meta/meta.go") {
+			t.Fatalf("★ %s 未从 meta/meta.go 取权威版本 ⇒ 无 tag 分支上会拿到分支名", name)
+		}
+		if !strings.Contains(src, "v[0-9]*.[0-9]*.[0-9]*") {
+			t.Fatalf("★ %s 未校验 git describe 的形态 ⇒ 分支名会漏过去", name)
+		}
+	}
+}
diff --git a/deploy/scripts/deploy-plan.sh b/deploy/scripts/deploy-plan.sh
index 51d827de..cc97460b 100755
--- a/deploy/scripts/deploy-plan.sh
+++ b/deploy/scripts/deploy-plan.sh
@@ -73,6 +73,25 @@ do_backup() {
   cp -a /etc/systemd/system/$SVC "$BAK/" 2>/dev/null || true
   info "已备份到: $BAK"
   info "  homed.bin / adapters / unit 文件"
+
+  # ★ E-2：数据备份必须**连密钥一起**，否则恢复到别的机器时解不开。
+  #
+  # 背景：config.db 里的敏感项与变量库 variables.json 是 AES-GCM 加密的，
+  # 密钥来自 systemd credential / $HOMED_SECURITY_KEY / <data>/security.key。
+  # 只搬 config.db 而不搬密钥 ⇒ 新机器上密文全部解不开。内核会在启动时
+  # 审计并告警（“检测到 N 条密文无法用当前主密钥解开”），但那时已经太晚。
+  #
+  # ⚠ 密钥与数据**必须分开保管**：把两者放进同一个 tar 包，
+  #   等于把加密降级成明文（拿到包的人两者都有）。
+  info ""
+  info "★ 数据备份提示（E-2）："
+  info "  config.db / variables.json 里的密钥字段是加密存储的。"
+  info "  跨机器恢复必须同时具备**原机器的密钥**，否则内核会报「密文无法解开」。"
+  info "  密钥位置（按优先级）：systemd credential homed_security_key"
+  info "                        \$HOMED_SECURITY_KEY"
+  info "                        ${DATA}/security.key （+ security.keyring 若有轮换）"
+  info "  ⚠ 请把密钥与数据**分开存放**：放同一个包里等于没有加密。"
+  info "  同机恢复只需照常恢复数据目录，密钥不变即可。"
   # 回滚命令
   cat > "$BAK/ROLLBACK.sh" <<RB
 #!/bin/bash
diff --git a/docs/zh/commondev-agent-runtime-design.md b/docs/zh/commondev-agent-runtime-design.md
new file mode 100644
index 00000000..8ad29842
--- /dev/null
+++ b/docs/zh/commondev-agent-runtime-design.md
@@ -0,0 +1,896 @@
+# commondev 运行时与内核接入设计（工程对话 · 内嵌/SSH · inputch 路由）
+
+> **状态：架构已按前篇 §12 调整。** 本文描述的 pi 会话包装、通道注册与运行时包装
+> **仍在 commondev 插件里**（它们是通用运行时能力，与 git 平台无关）；
+> 移出插件的是**平台专有**部分（认证头、PR、分支保护）。
+> 只讲两件事：**「工程对话」这个一等对象怎么落到运行时**，以及**插件怎么接进内核
+> 已有的调度器 / 驻留子 / 通道体系**（而不是另起一套）。
+>
+> 前篇讲的是工具面、台账 schema、判据与变异、PR 流程与安全；本文不重复。
+>
+> **标记约定**（沿用本仓惯例）：
+> - **［已核］** = 本文写作时已在本机实测 / 源码核对确认，附证据
+> - **［待定］** = 需要决策，本文给出建议但未拍板
+> - **［风险］** = 已知会让整套机制失效的点
+>
+> 撰写时间：2026-10-13。事实基线：TrueAgent `/home/program/TrueAgent`，
+> 生产实例 `/home/newqqagent`，SDK 仓 `third_party/homeagent-sdk`。
+
+---
+
+## 0. 与前篇的关系（一处修正）
+
+前篇 §6.1 把「拉起 agent」写成 **CLI vs A2A/ACP** 的二选一，结论是「走 CLI」。
+**该结论只论证了 `cwd` 一个维度，漏了「会话续投」这一维度，因此是错的**（不是结论方向错，
+是论据不全）：`pi -p` 每轮一个进程，**无法保证「再投一条还是同一个会话」** —— 而那正是
+用户明确要求的能力。
+
+正确的两轴是：
+
+| 轴 | 取值 |
+|---|---|
+| **会话粒度** | 一次性进程（`-p`） / 常驻进程（`--mode rpc`） / 进程内（Node SDK） |
+| **cwd 由谁承担** | `-p`/RPC：**进程 cwd**；SDK：`createAgentSession({cwd})` |
+
+A2A/ACP **依然排除**（前篇 §3.4 的「参数里没有 cwd」这条事实没变），但排除理由与本
+设计无关：它们是**常驻 peer** 的模型，而本需求是**按工程对话拉起**。
+
+---
+
+## 1. 已核实的事实（接手者可直接依赖）
+
+### 1.1 会话续投 ［已核 · 关键］
+
+| 事实 | 证据 |
+|---|---|
+| **`--session-id` 就是「续同一会话」的原语** | 两次 `pi -p --session-id X`，第二次准确答出第一次让记的暗号 `紫罗兰-7734`；会话文件 `--tmp-sidprobe--/<ts>_commondev-test-01.jsonl` |
+| **不带 `--session-id` 会静默开新会话** | 同一 cwd 下两次 `-p` 生成**两个不同** UUID 会话文件 |
+| `--session-dir` 可把会话库搬走且**不污染**全局 `~/.pi/agent/sessions/` | 实测落 `/tmp/sd-store/`，全局 sessions 无新目录 |
+| **★ 两个 `-p` 并发打同一 session-id 会写坏会话** | `/tmp/conc`：文件里 `user A`、`user B` 相邻，`assistant B` 在前、`assistant A` 落在最后 ⇒ B 那条 run 的**模型上下文里没有 A 的用户消息**，且 `parentId` 树链交错 |
+| 内层 pi **不继承**外层 `PI_SESSION_FILE` / `PI_SESSION_ID` | 外层跑完只有外层会话被写 |
+
+> ⇒ **纪律**：同一个 session_id **绝不允许并发投递**。这条必须做成**结构性保证**
+> （sidecar 内单一投递 goroutine + mutex），不能靠"调用方记得别并发"。
+
+### 1.2 两种运行时形态 ［已核］
+
+> ［已定 2026-10-13 用户拍板］**插件内嵌独立的 nodejs 与独立的 pi**，
+> **安装在插件工作目录**（不是复用系统 node/pi）；**pi 的插件也装到这个目录**。
+> 默认走**内嵌**，配置可切**远程 SSH**。
+
+| 事实 | 证据 |
+|---|---|
+| `createAgentSession({cwd})` 可行（真·进程内） | `/tmp/sdktest/probe.mjs`：读工作区 `marker.txt` 得 `SDKMARK-42`，同会话追问仍得 `SDKMARK-42`，`session.messages.length === 8` |
+| **`PI_CODING_AGENT_DIR` 可重定向 pi 的 agent dir** | 设该变量后 `pi install <pkg>` 把 `packages` 写进了**自定义 agentdir**，用户全局 `~/.pi` **零污染** |
+| **新 agent dir 没有凭据** ⇒ 必须一并配齐 | 只重定向 agent dir 时内层 pi 报 `No API key found for the selected model`；补上 `models.json` + `auth.json` 后**同一命令返回 `SELF-OK`** |
+| **项目局部安装插件可行** | `pi install -l ./mypkg`（cwd=工作区）⇒ 写 `<workdir>/.pi/settings.json`；内层 pi 带 `--approve` 跑，调用该包的工具返回 `PKG-OK` |
+| **全局安装插件可行** | `pi install <pkg>`（不带 `-l`）⇒ 写 `~/.pi/agent/settings.json`；配合 `PI_CODING_AGENT_DIR` 可改为写插件自己的 agent dir |
+| ⚠ **安装是复制，不是引用** | `pi install ./mypkg` 会把包**复制**到工作区。改源目录不会影响已安装的那份（**我曾因此得出"插件不生效"的错误结论**）；要更新必须重装 |
+| 不批准 trust 时项目包被挡 | `--no-approve` 时项目局部安装的扩展不加载 |
+| RPC 常驻 + 同会话两轮 | `pi --mode rpc --session-id rpc-probe-01`：`agent_settled` 1.6s 后第二轮答出 `蓝鲸-99` |
+| RPC 事件含**工具级**证据 | `docs/json.md:105-114`：`tool_execution_start`（args）/ `tool_execution_update` / `tool_execution_end`（result, isError） |
+| `agent_settled` 才是「这轮真的完了」 | `agent_end` 之后还可能有 retry / compaction / 排队消息（`docs/json.md`） |
+| 本机 sshd 在 `:22`，`ssh`/`sshpass` 都在 | `ss -tlnp`、`which` |
+| sidecar 模式本仓已有先例 | `internal/plugins/clawhubadapter/sidecar.go`（376 行）：JSON-RPC over stdio + pending-id 配对 + `readLoop` + `NotifyChan` + 优雅 `Close` |
+
+### 1.3 内核可接入面 ［已核］
+
+| 能力 | 插件可用？ | 依据 |
+|---|---|---|
+| `RegisterInputChannel(name, def)` | ✅ **公开**，一个插件可注册 N 个 | `sdk/plugin.go:665` |
+| `InjectText*` / `InjectInterrupt*Opts` | ✅ | `sdk/plugin.go:818-868` |
+| `InjectOptions.Priority`（L1–L3） | ✅ | `sdk/plugin.go:152` |
+| `RegisterOutputChannel` | ✅ | `sdk/plugin.go:632` |
+| `UnregisterOutputChannel` | ⚠️ **外部插件静默无效** | `capability-boundary.md`：桥只注入 registrar |
+| `resident_agents`（list/create/send/inspect/compress/reclaim/destroy） | ❌ **插件调不到** | proc 桥 `grep` 无 toolapi/resident 方法 |
+| `AssignInputChannel(name, agentID, cap)` | ❌ **未导出到公开 SDK** | 只在 `IOManager`（`io/channel.go:610`） |
+| `inputch_note` / `notify_parent` | ❌ 只有驻留子有 | `tooldefs.go:629`（`parentID != ""`） |
+| `Events()` | ❌ 恒 nil | 桥不注入 subscriber |
+
+**两个必须避开的陷阱**：
+
+1. **`ToolAPI` 是单例、per-agent 数据靠「最后注入者」** —— `builtin_toolapi.go:117-119`
+   自陈该局限，而 `SpawnResident` 也会注入。⇒ **不要经 ToolAPI 调 `resident_agents`**：
+   它可能打到某个驻留子的表上。
+2. **不要以为插件稳拿 L3**（真实是两跳两道闸，见 §3.2）。
+
+### 1.4 驻留子设计里可抄的纪律 ［已核］
+
+| 纪律 | 出处 |
+|---|---|
+| `SendToResident` 固定 `Priority: "L4"`，子侧唯一 L4 来源 = 父 | `resident.go:440-455` |
+| `KernelSource = parentID`（父在子的阶梯上是唯一 L4） | `resident.go:190` |
+| **父 `Stop()` ⇒ 全部子销毁**，登记表清空、不留孤儿 | `resident.go`（S16 判据） |
+| `inspect` 是 pull，**不打断**子 | `resident_agents` 动作语义 |
+| `compress` = 保留语义（压上下文 + **清单**） | 前篇 §9 |
+| `reclaim` = 取消语义（父选 promote → 取消子） | 前篇 §9 |
+| `contextfull` → 父侧 **L4**（只推信号，状态靠 pull） | 前篇 §9 |
+| inputch 是**最基本的输入路由单位**，路由发生在**进内核之前** | `resident-subagent-design.md §4.1` |
+
+---
+
+## 2. ★「工程对话」是一等对象（本文核心）
+
+前篇把单位定为「项目 → 分支线」。本文把它落到运行时，并给它一个用户可寻址的名字：
+**工程对话**。
+
+**一个工程对话 = 四元组绑定，缺一不可**：
+
+```
+工程对话 (id = br-<project>-<slug>)
+├─ workdir    <插件数据目录>/program/<hash>-<name>
+│              ★ hash = H(项目+分支) 承担**唯一性** ⇒ 同仓库不同分支必然是不同目录
+│              ★ name = 分支名派生，只做可读性（不承担唯一性，派生后可能撞）
+│              独立 clone（本地 clone 硬链接派生，非 worktree、非 --reference）
+│              **合入后整个目录删除**
+├─ session_id pi 会话（★ 续投的唯一依据；漂移即失败）
+├─ runtime    local（默认，内嵌 pi） | ssh（配置切换，远端建目录拉 pi）
+├─ host       runtime=ssh 时的目标主机
+└─ channels   插件为该工程对话注册的 **一对通道**
+              ├─ inputch  commondev/<id>      ← pi → agent（可用斜杠；只流向该子）
+              └─ outputch commondev_<id>      ← agent → pi（★ 下划线，会拼成 output_send__）
+```
+
+> **目录为何必须是独立 clone**（而非 worktree / `--reference`）：用户要求
+> 「合入后直接删除目录」，而实测 worktree 删后有 `.git/worktrees/` 残留（需 `prune`）、
+> `--reference` 则有 alternates 外部依赖（mirror 被清即损坏）。**本地 clone 对象为硬链接**
+> ⇒ 省磁盘、无外部依赖、刪掉即彻底。详细实测见前篇 §4.3。
+
+### 2.1 为什么必须是"一对通道"，而不是复用一个
+
+［已核］inputch 是**最基本的输入路由单位**，路由按 `Owner` 在**进内核之前**完成
+（`inputroute.go:23`）：`lookupInputChannel(ch) → Owner → DeliverRouted`。
+未分配或归自己的，才由本内核处理；归属到不存在的 agent 时**兜底给根并留日志**
+（不静默吞）。
+
+⇒ **每个工程对话一个独立 inputch**，就得到了：
+- **精确投递**：往 `commondev/br-1` 注入只到 br-1 的 agent，别人看不到；
+- **互不串台**：两条并行的工程对话不会互相污染上下文；
+- **可限额**：`Capacity` 独立；
+- **零内核改动**：`RegisterInputChannel` 是公开 API。
+
+### 2.2 ★ 顺序：先拉起 pi 拿到 session，**才**注册通道
+
+［已定 2026-10-13 用户澄清］**通道注册依赖 session 已存在**。完整顺序：
+
+```
+① 建工程           commondev_project_open / branch_open
+                     → 建 workdir（program/<hash>-<name>；<hash> 含分支 ⇒ 同仓库不同分支不同目录）
+② 拉起 pi          commondev_agent_up（内嵌 sidecar / remote 时 ssh）
+                     → pi 起来并拿到/恢复 **session_id**
+③ ★ 注册通道（此时才有）
+     RegisterInputChannel("commondev/<id>", ChannelDef{NoMemory: true})
+       ★ 可以用斜杠（inputch 不做工具名）
+       ★ NoMemory：通道控制流不该进记忆（避免污染召回/场面指纹）
+     RegisterOutputChannel("commondev_<id>", caps, "工程对话回程", def, handler)
+       ★ 下划线，不能带斜杠 —— 它会拼成 output_send__<name>
+④ 划给驻留子     resident_agents create input_chs=commondev/<id>
+                   allowed_outputs=commondev_<id>（这一步由主 agent 调）
+⑤ 投递任务       子调 output_send__commondev_<id>(payload=…)
+                   → 插件 handler → sidecar.prompt(session_id, text)
+⑥ pi 产出        → 插件 InjectTextTo("commondev/<id>", …) → 路由回该子
+```
+
+**为何必须先有 session**：通道是“与**某个具体 pi 会话**对话的入口”——
+没 session 就没有投递目标，注册出来的通道是空壳；handler 也无法“包一下”
+（查台账拿不到 `session_id`）。
+
+⇒ **台账在 ② 写入 `session_id`，在 ③ 补写通道名**，两步不能合并。
+⇒ `commondev_agent_up` **要在通道注册之前**、**在子创建之前**——否则子拿到的
+`output_send__commondev_<id>` 会指向一个还不存在的通道。
+
+**回投与小中断**：插件用
+`InjectTextTo(source="commondev", channel="commondev/<id>", text=…)` 把 pi 的
+事件/进度回投给**该工程对话的子**；用 `InjectInterruptTextOpts(..., Priority:"L3")`
+做需要抢占的通报。
+
+### 2.3 ★ skill 必须建议 agent：新建驻留子并**划入**这对通道
+
+**注意顺序**：通道是 `commondev_agent_up` 拿到 session **之后**才注册的（§2.2），
+所以你的动作序列是：**建工程 → 拉起 pi → 插件注册通道 → 你建子并划入**。
+
+插件只能把通道**登记**出来（`RegisterInputChannel`），**划入（Assign）只有内核能做**
+［已核：`AssignInputChannel` 未导出到公开 SDK］。所以"通道 → 子 agent"这一步
+**必须由 agent 自己调内核工具完成**。
+
+⇒ 因此配套 skill 的核心建议是：
+
+```
+为每个工程对话新建一个驻留子，并把该工程对话的一对通道划给它：
+
+  resident_agents create
+      id           = dev-<br-id>
+      input_chs    = commondev/<br-id>          ← 划入该 inputch（Owner 变成这个子）
+      allowed_outputs = commondev_<br-id>       ← 授权该 outputch（★ 下划线）
+      capacity     = 64
+      task_prompt  = "你在 <workdir> 推进 <work>。下任务给自己用
+                      output_send__commondev_<br-id>(payload=…)，
+                      pi 的结果会回投到你的 commondev/<br-id>；
+                      有结论用 notify_parent 汇报。"
+
+  ⇒ 此后该工程对话的输入**只**流向这个子内核（根 agent 看不到），
+     子在收到父的 send 时按 L4 被打断（KernelSource = 父）。
+```
+
+**如果 agent 不建子会怎样**（skill 必须写清代价，否则它不会照做）：
+- 所有工程对话的输入都涌向**根 agent**（`routeInputByOwner` 发现 Owner 为空 ⇒ 自己处理）
+  ⇒ 根会成为瓶颈，多工程并行的意义消失；
+- 根 agent 的上下文被 N 条工程对话的细节淹没（正是前篇 §4.6 要避免的「主管被 diff 淹没」）。
+
+### 2.4 L4 落在谁身上（**能力表，别搞错**）
+
+| agent | 它的"内核" | 谁能产生 L4 | 机制 |
+|---|---|---|---|
+| 根 agent | 内核自身 + **内置**插件 | `raiseKernelInterrupt`、内置插件（如 WebUI 终止按钮） | `isKernelLevelSource` ① `pluginReg.IsBuiltinPlugin(name)` |
+| 驻留子 | **父 agent** | 父（`SendToResident` 固定 `Priority:"L4"`） | `isKernelLevelSource` ② `name == a.kernelSource` |
+| **commondev（外部插件）** | — | **永远不能** | proc 桥 `clampExternalPriority` 夹 L4→L3（`proc/corehandler.go:279`） |
+
+> **［风险］** commondev 作为**外部独立插件**，L4 被制度性移除。若 canonical 流程需要
+> 「立即取消整条分支」，只能靠 **L3 打断主管 + 主管下令**，或改用内置插件形态。
+> 见 §6 未决问题 U1。
+
+### 2.5 ★ 投递路径：用内核原生的输出门，不另造发送工具
+
+［已定 2026-10-13 用户澄清］完整流程是：
+
+```
+① 插件为每个工程对话注册一对通道
+     inputch   commondev_br_1     ← pi 的进度/事件回这里
+     outputch  commondev_br_1     ← ★ agent 发消息给 pi 就走它
+② 主 agent 调 resident_agents create，把该 inputch 划给驻留子
+③ 之后下任务 = 该子调 output_send__commondev_br_1(payload="…")
+④ 插件收到 payload → 查台账 (workdir, session_id) → sidecar.prompt(...)
+⑤ pi 产出 → 插件注入 commondev_br_1 → 路由回该子
+```
+
+**关键：第 ③ 步不需要新工具。** `output_send__<通道>` 是**内核原生**的输出门
+（`output.go:10`）：agent 调它 → 内核查通道能力 → `EmitTextTo` → 打到
+**插件注册的输出通道 handler**。插件的 handler 就是那个"包装"。
+
+⇒ **本稿前版设的 `commondev_agent_send`（面向 agent 的发送工具）已废除** ——
+它是重复实现。保留的只有：
+
+| 方向 | 机制 | 谁实现 |
+|---|---|---|
+| **agent → pi** | `output_send__commondev_br_1(payload=…)` | **内核**（插件只写通道 handler） |
+| **pi → agent** | 插件 `InjectTextTo(source, "commondev_br_1", …)` | 内核路由（按 inputch Owner） |
+| **中断 pi** | `InjectInterruptTextOpts(..., Priority=L3)` | 内核调度器 |
+
+⇒ 插件侧只剩**一个工具族**（配置/仓库/判据）+ **两个通道 handler**。
+
+#### ⚠️ 通道命名约束（**本稿前版写错了**）
+
+输出通道名会被拼进 LLM 函数名 `output_send__<name>`，而上游要求函数名满足
+`^[a-zA-Z0-9_-]{1,64}$`（SDK `RegisterOutputChannel` 注释已警告）。
+
+| | 能用 `/` 吗 | 依据 |
+|---|---|---|
+| **inputch** | ✅ 可以（内核自己就用 `child/<id>`、`sub/<id>`） | `resident.go:253/447` |
+| **outputch** | ❌ **绝对不行** | 否则上游 400，**整条请求被拒、agent 整体失语** |
+
+⇒ 本稿前版写的 `commondev/<id>` **作为输出通道名是非法的**。正确用法：
+
+```
+inputch  : commondev/<br-id>      （可以用斜杠，路由单位）
+outputch : commondev_<br-id>      ★ 下划线，保证 output_send__ 合法
+```
+
+（`<br-id>` 本身也必须限定在 `[A-Za-z0-9_-]`，不能出现斜杠/点/空格。）
+
+#### ⚠️ 另一条限制：`BindOutputTarget` 不开放给插件
+
+“输出通道 → 目标 agent 的 inputch”的解析由 `ChannelRegistry.BindOutputTarget`
+提供（`io/inputch.go:175`），但它**未导出到公开 SDK**。
+⇒ **插件不能自己把输出通道绑到某个子的 inputch**。
+
+好在 canonical 流程**不需要它**：子 → 父/Z 方向走 `notify_parent`（内核已有），
+pi → 子的方向走 **inputch Owner 路由**（已可用）。若将来需要“经输出通道直接投给另一个 agent”，
+得先把 `BindOutputTarget` 补到公开 SDK（属"只增不减"的追加）。
+
+### 2.6 commondev 与驻留子的能力映射
+
+**总纲 ［已定 2026-10-13 用户拍板］**：插件对 pi 做的事，**本质就是**
+> **「把给 pi 发消息包装一下、把 pi 返回包装一下」**，然后**深度融合内核的 IO 抽象与中断系统**。
+> ⇒ **pi = 一个 Device**。不是自己造一套调度/会话/中断，而是**接到已有的那套上**。
+
+对应关系因此是**结构上同构**的，不是比喻：
+
+| 内核概念 | pi 侧对应 | 落点（内核已有） |
+|---|---|---|
+| **给 pi 发消息** | `pi.prompt(text)` / `steer` / `follow_up` | `output_send__commondev_<id>`（内核原生） |
+| **pi 返回** | sidecar 回调 / `tool_execution_*` / `agent_settled` | `InjectTextTo(source, "commondev/<id>", …)` |
+| **pi 报错/卡住** | sidecar 错误事件 | 同一个 output handler，或注入为输入 |
+| **中断 pi**（改主意、叫停） | `steer`（steer 到当前轮之后） | `InjectInterruptTextOpts(..., Priority: L3)` |
+| **音声/图像产物** | pi 可产出的媒体 | `OutputCapabilities()` 声明 `CapText|CapImage|…` |
+| **工具级证据** | `tool_execution_start/update/end` | 经 output handler 回投，作台账证据 |
+
+⇒ **本质是一次包装适配**：外壳是 Device，里面是 pi 进程 + sidecar。
+所有调度/中断/路由/记忆策略都**交给内核**（`ChannelDef` + `InjectOptions` + `inputch` 路由）。
+
+**与驻留子的对照**：
+
+| 内核驻留子 | pi 侧 | 谁提供 |
+|---|---|---|
+| 轻量内核（调度器/中断栈） | **不需要** —— 用内核自己的 | — |
+| pi 会话 | sidecar 持有的 `session_id` | commondev |
+| 父→子 = L4 打断 | **沿用**：父给子发消息就是 L4（插件不介入） | 内核 |
+| 子→父 = L3 汇报 | **沿用**：`notify_parent`（skill 建议子调用） | 内核 |
+| `inspect`（pull 不打断） | `get_state` + 台账 `deliveries` | commondev 经 sidecar |
+| `inputch_note` 处理表 | 台账 `deliveries` 表 | commondev |
+| `destroy` | 杀 sidecar / pi 进程 | commondev |
+| **父 `Stop()` ⇒ 全部子销毁** | **commondev 保证**（进程/ssh 无孤儿） | commondev（**孤儿属插件责任**） |
+
+> **一句话**：**插件只负责“把 pi 接成 Device”与“台账记 session_id”**，
+> 其余的调度、中断、路由、记忆策略**全是内核已经在做的事**。
+
+### 2.7 ★ 工具调用有 60 秒硬上限（实现约束） ［已核 · 实测踩到］
+内核把**每一次工具调用**限制在 **60 秒**，且**硬编码无配置项**：
+
+```go
+// internal/agent/core/toolcall.go:62
+case <-time.After(60 * time.Second):
+    te := newToolError(ErrReasonTimeout, …)
+```
+
+⇒ **凡是可能超过 60 秒的活儿，一律不能放在工具调用里同步做。**
+
+实测踩到的场景：`git clone --mirror` 一个仓库耗时不定，`commondev_branch_open`
+里同步 clone ⇒ 工具超时 60s 报 `工具 commondev_branch_open 执行超时（60秒）`，
+**但 mirror 其实已经建好了**（磁盘上 `cdtest.git` 存在）——
+即：超时后状态是“做了一半”，调用方却只看到失败。这是最坏的一种失败。
+
+**受影响的操作**（都必须异步化）：
+
+| 操作 | 为何慢 |
+|---|---|
+| `git clone --mirror` | 仓库大小 × 网络 |
+| 由 mirror 派生工作目录（即使硬链接，大量小文件仍慢） | 文件数 |
+| `git fetch` 更新 mirror | 网络 |
+| 跑判据 / 变异测试 | 测试本身耗时 |
+| **拉起 pi 并等它就绪** | 进程启动 + 首次初始化 |
+
+**设计结论**：工具只做**快操作**（查台账、登记、发起），慢操作**转后台**，
+由状态工具报告进度。形态建议：
+
+```
+commondev_branch_open   → 登记台账 + 建目录（快）+ **后台 clone**；返回 job_id
+commondev_job_status    → 查后台任务进度（pending|running|done|failed）
+```
+
+⇒ 这同时满足内核“工具要快返回”的设计与用户“开完就能用”的期望。
+
+> **教训**（值得单独记）：我曾把同步 clone 写进工具里，端到端跑时才发现超时。
+> 若只看单测（不跑真机）根本发现不了 —— 这是“读码能过、真机不过”的典型。
+
+### 2.8 ★ 会话 id 必须**显式指定**（否则续投必失败） ［已核 · 实测踩到］
+
+**事故**（首次投递）：
+
+```
+会话漂移：期望 br-cdtest-feat_alpha，实际 01a13959-bcc3-7007-9a92-06483e2150ba
+—— 拒绝继续（不静默改投新会话）
+```
+
+**根因**：sidecar 初版用 `createAgentSession({cwd})`，pi 会**自己生成一个 UUID**
+作会话 id；而 Go 侧台账记的是我们请求的名字。两者本来就不相等 ⇒
+“投递后断言会话未变”这条纪律拿两个不同名字比，**永远失败**。
+
+**修法**（已验证）：用 `SessionManager.create(cwd, sessionDir, {id})` 显式指定：
+
+```js
+const manager = SessionManager.create(workdir, sessionDir, { id: sessionId });
+const { session } = await createAgentSession({ cwd: workdir, sessionManager: manager });
+```
+
+实测：`manager id: MYFIXEDID`（不再是随机 UUID）；pi 会话文件名
+`…_br-cdtest-feat_alpha.jsonl`，且其中第 4 行就是 `user: <payload>` ——
+即 payload **真的进了那个会话**（不是只看工具返 `ok`）。
+
+⇒ 这同时给了“续投同一会话”一个**真保障**（而非运气）：固定 id ⇒
+重启/重投能打开同一个会话文件。
+
+> **注**：`pi -p --session-id X` 也是用 X 作会话 id（实测会话 header `"id":"X"`）；
+> 两条路径一致。但 SDK 路径**必须手动传**，不会从环境变量推断。
+
+---
+
+## 3. 运行时形态（内嵌为默认，SSH 为配置项）
+
+### 3.1 架构（一次包装适配）
+
+［已定］**默认本地内嵌，配置切到远程 SSH**。两者**共用同一份 sidecar**，
+差别只在**传输层**（本地 `exec` vs 远程 `ssh`）：
+
+```
+内核 ──InjectInputTo(source, "commondev/<id>", text)──► 插件
+                                                      ├─ 包一下 ──► sidecar.prompt(text)
+                                                      │             └─ 内嵌 createAgentSession
+                                                      │                 （远程时：ssh 到远端同一份）
+                                                      └─ 包一下 ◄── sidecar 回调（pi 输出/事件）
+                                                                     └─ output handler → 回投内核
+```
+
+**两处“包一下”**（这是本设计的全部）：
+
+| 方向 | 做什么 | 内核已有机制 |
+|---|---|---|
+| **入（给 pi 发消息）** | 找到 `(workdir, session_id, runtime) → sidecar.prompt/steer` | 入站由 `InjectInputTo` 到达，插件只是落地 |
+| **出（pi 返回）** | sidecar 回调 → 包成内核输出 | `RegisterOutputChannel` 的 handler |
+| **中断** | 不需新机制 | `InjectInterruptTextOpts(Priority=L3)` 走内核调度器 |
+
+⇒ **插件不实现调度器、不实现中断栈、不实现会话路由** —— 那些都是内核的。
+**台账只多做一件事**：记住 `session_id` 并在投递后断言它未变（§3.3）。
+
+**为何不让插件自己管 RPC 循环**：那是重复实现内核已有的能力。
+sidecar 只需要回答两个问题：
+1. “这条消息投给了哪个 session？”（投递前读、投递后验）；
+2. “pi 现在在干什么？”（`get_state` / 事件流）。
+
+> **为何不用 RPC 客户端另开一路**：最初设想 C（内嵌）/ B（`--mode rpc`）
+> **双模式**。用户拍板后**收敛为「一套 sidecar + 两种传输」**（内嵌为唯一实现）——
+> 少一条运行时路径，少一半要维护的边界。RPC 仅在 sidecar 不可用时可作降级，
+> 且**不属于本设计的正式形态**。
+
+#### 3.1.1 接线状态与两处实测缺口 ［✅ 已接线 · 真实 sshd e2e］
+
+`runtime=ssh` 的**实现**早已写完（`sidecar_ssh.go` 全套：探测/推脚本/建链），
+`startSidecar` 里的 `if b.Runtime == "ssh"` 分派也接好了。**但 `branch_open`
+硬编码 `Runtime: "local"` 且从不读 `ssh_host`** —— 于是 `runtime=ssh`
+被**静默吞掉**：以为跑在远端，实际跑在本地，且没有任何提示。
+（`runtimeOrDefault` 当时更是从未被调用的死代码。）
+
+> **这类「参数被吞」比报错危险**：报错立刻发现；吞掉会一路错下去，
+> 而症状（任务跑在本地、文件在本机被改）与预期完全不同却很晚才暴露。
+
+已补：`branch_open` 解析 `runtime`/`ssh_host` → 缺 host 直接拒 →
+未知 runtime **响亮拒绝**（不降级）→ 写台账 → `agent_state` 回显 `ssh_host`。
+
+**另一处缺口**：`probeSSH` 硬编码探 `node`，**忽略 `ssh_node_path`**。
+于是用户按提示配好了远端 node 路径，探测**仍然失败**并报
+「远端不可达或未配免密」——把**配置问题伪装成连通性问题**，排查方向完全错。
+已修（用 `t.NodePath`）。
+
+**判据**：
+- 接线（不需环境）：`ssh_wiring_test.go` 9 条 —— 含"参数被吞""未知 runtime 不降级"
+  "未知 CLI 不回退 pi""新增 CLI 不改核心"。
+- **真端到端**（`HA_SSH_E2E=1`，需 sshd + localhost 免密）：`ssh_e2e_test.go` 5 条 ——
+  真起 ssh、真 scp 推脚本（并比对本地/远端字节一致）、真握手、真投 prompt
+  并断言**会话未漂移**；另含"远端缺 node 响亮报错""无免密响亮报错"。
+  实测握手耗时 ~20s（ssh 建链比本地慢，故 `handshakeTimeout` 单独放宽到 20s）。
+
+**变异验证**（4/4 咬住）：退回硬编码 local / 未知 runtime 降级 /
+未知 CLI 回退 pi / `llmConfig` 不透传。
+
+#### 3.1.2 ★ 第三处缺口：远端工作目录**从未被创建** ［✅ 已补 · 真实 sshd 闭环］
+
+`prepareWorkdir` 只有**本地一套**（本机 `clone --mirror` + `clone mirror workdir`）。
+对 `runtime=ssh` 的分支，远端 pi 的 cwd 指向一个**从未被创建**的远端目录。
+症状是「agent 起来了，但一执行命令就说目录不存在」，而 **job 状态显示 done**
+（因为本地 clone 确实成功了）—— 两边各自看起来都成功，所以极难归因。
+
+新增 `workdir_remote.go`，与本地路径**逐条对应**：
+
+| 步骤 | 本地 | 远端 |
+|---|---|---|
+| 建父目录 | `os.MkdirAll` | `ssh mkdir -p` |
+| mirror | `<插件数据>/mirrors/<name>.git` | `<ssh_workdir_root>/.mirrors/<name>.git`（同一远端多条线共享） |
+| 派生 | `clone mirror workdir` | 远端 `clone mirror workdir` |
+| 切分支 | `ensureOnBranch` | `ensureRemoteOnBranch` |
+| 记 base_sha | `captureBaseSHA` | `remoteCaptureBaseSHA` |
+
+**★ 三条纪律**：
+
+1. **`runPrepareWorkdir` 必须按 runtime 分派**，且远端分支必须 `return` ——
+   不返回就会继续落到本地路径（本地 clone 成功、远端目录仍为空）。
+2. **台账 `Workdir` 必须改写成远端路径**，否则 `agent_up` 把远端 pi 的 cwd
+   指到一个本地目录名上。
+3. **缺 `ssh_workdir_root` 响亮报错，不猜默认值** —— 猜错会把文件写到远端
+   别的项目的目录里，很难回滚。
+
+**判据**：`workdir_remote_test.go` 7 条。其中真 sshd e2e 3 条 ——
+`TestSSHBranchWorkdirBecomesRemotePath`（远端真建目录/真 clone/真切分支/
+远端 mirror 存在）、`TestRemoteWorkdirReuseIsIdempotent`（复用幂等）、
+`TestSSHFullLoop`（**完整闭环**：远端建目录 → 远端拉起 pi → 投递 → 断言会话未漂移，21s）。
+
+**变异验证**（5/6 咬住，1 条不适用）：远端 mirror 用本地路径 /
+远端不切分支 / 缺配置猜默认 / `branch_open` 不传 runtime / 远端不改台账 Workdir。
+**未咬住的那条**：在远端分支里删掉**一个** `return` —— 因为该分支还有别的
+`return`，行为仍正确，判据不报红是**对的**。
+
+**★ 判据自身的一次修正**：`TestPrepareWorkdirDispatchesByRuntime` 初版用
+`Contains("runtime == \"ssh\"")` 判断分派 —— 而 `if false && runtime == "ssh"`
+仍包含该子串，于是**变异照绿**。改为精确匹配 `if runtime == "ssh" {` 并追加
+「不得有 `false &&` 前缀」后咬住。这是本仓反复出现的「判据通过 ≠ 检查到目标性质」。
+
+**顺带修的既有缺陷**：`ssh_workdir_root`/`ssh_runtime_root`/`ssh_node_path`
+三个配置项**只被 Get 读、从未 RegisterDef**，于是设置页里看不到，
+用户只能去改 config.yaml 猜键名 —— 而缺 `ssh_workdir_root` 会让远端线直接失败。
+已全部注册。
+
+**另修自己新代码的 bug**：`runSSHCaptureOn` 初版在 `cmd.Start()` 之后调
+`CombinedOutput()` ⇒ `exec: already started`（实测被自己的 e2e 咬出）。
+改为 goroutine + `Wait()` + 超时 `Kill()`。
+
+#### 3.1.3 ★ 第四处缺口：sidecar 脚本**没有随包分发** ［✅ 已补 · 真实拉起验证］
+
+打包只收 `rawfile/` 与 `skill/`，而 `sidecar.mjs` 在**工程根** ⇒ 没进包。
+同时 `<插件数据>/runtime/pi/` 在部署时没人创建。三条查找路径全空 ⇒
+
+> `agent_up` 在全新部署上**必然失败**，报
+> 「找不到 pi 的 sidecar 脚本: /home/xxx/plugin_data/commondev/runtime/pi/sidecar.mjs」
+> —— 一个用户从没听说过的路径。
+
+表现为「插件装了、工具都在、但一拉 agent 就错」，属于**能装不能跑**。
+
+**修法**（复用既有通道，不新增概念）：
+
+1. `sidecar.mjs` 放进 `rawfile/runtime/<cli>/`，随包分发；
+2. `locateSidecarScript` 建立查找链：
+
+| 顺序 | 位置 | 用途 |
+|---|---|---|
+| ① | `<插件数据>/runtime/<cli>/<script>` | 用户自备 / 覆盖随包版本 |
+| ② | `<插件目录>/rawfile/runtime/<cli>/<script>` | **随包分发**（内置 pi 靠这条） |
+| ③ | `<可执行文件同目录>/<script>` | 开发期（hmapdev debug） |
+
+③ 全部落空时，错误**列出找过哪里**并给出解决办法 —— 否则用户只能猜。
+
+★ 与 `nodeBin` 走**同一机制**（`rawFiles()`）：rawfile 已是"随包任意资源"
+的通道，不必为脚本再开一个约定目录。
+
+**判据**：4 条（随包存在且与工程根一致 / 查找链命中 / 用户自备优先 /
+错误可执行）+ 变异咬住（去掉 rawfile 回退、颠倒优先级）。
+**真机验证**：用随包脚本真的拉起 sidecar 并完成握手（pi 0.99.2）。
+
+### 3.2 形态对照与硬边界
+
+| | **本地内嵌（默认）** | **远程 SSH（配置切换）** |
+|---|---|---|
+| sidecar 位置 | 本机 | 远端主机 |
+| workdir | `<插件数据目录>/program/<hash>-<name>` | **远端** `~/.commondev/program/<hash>-<name>` |
+| pi 实例 | sidecar 进程内 | 远端拉起（cwd = 远端 workdir） |
+| 会话库 | 本地 `--session-dir` 指向 workdir | **远端**（同样指向 workdir） |
+| 前置条件 | 本机 node + pi | 远端 node + pi（**缺时先问用户**，§3.4） |
+| 传输 | `exec`（stdio） | `ssh <host>` + stdio |
+
+**两形态都必须遵守的硬约束**：
+
+- 侧车崩了要能**恢复同一 session**（`SessionManager` 导入已有 jsonl）；
+- **stdout 必须持续读**（不读会堵住 pi）；
+- 只有 `agent_settled` 才算「这轮真的完了」；
+- **同一个 session_id 绝不并发投递**（§1.1 实测会写坏会话）。
+
+**远程额外约束**：启动时校验远端 `pi --version`，不匹配**响亮失败**。
+**不要**静默降级到本地跑 —— 那会让人以为活派到了远端，其实在本机跑。
+
+### 3.3 投递纪律（**必须做成机制，不能靠自觉**）
+
+```
+agent_send(id, text, deliver_key)
+  ① 查台账拿 (workdir, session_id, runtime, host)   ← session_id 是唯一依据
+  ② 单一投递 goroutine + mutex（per 工程对话）      ← 结构性禁止并发
+  ③ 写 inbox 文件（持久化，进程崩了不丢）
+  ④ sidecar 投递（内嵌 prompt / RPC prompt）
+  ⑤ ★ 重读会话，断言 session_id 未变 —— 变了即**响亮失败**（不静默改投新会话）
+  ⑥ 记 deliveries(deliver_key, 状态, 结果摘要)      ← 幂等键，重复投递不重复执行
+```
+
+**两条必备判据**（配变异）：
+- `TestAgentSendSerializedPerSession`：同 session 并发投递必须**排队**（变异：去掉 mutex → 必须报红）；
+- `TestAgentSendRejectsSessionDrift`：会话漂移必须报错（变异：删掉断言 → 必须报红）。
+
+### 3.4 ★ 远端环境缺失：询问用户，**不得擅自安装**
+
+**已核**：SDK **没有**"向用户提问"的专用 API（插件是子进程，不能直接弹 UI）。
+现有机制是：插件把「需要决策」的消息**注入**给 agent（`PriorityL2`/`L3`），
+**由 agent 去问用户**（本机先例：`cli/plugin.go:473` 的 `/stop` 用 L3，
+`timer/plugin.go:118` 定时器用 L3）。
+
+⇒ commondev 的 preflight 契约：
+
+```
+remote_preflight(host)
+  ① ssh 连通性          → 不通：报错（属配置错误，不是缺环境）
+  ② 远端 pi --version    → 缺 pi  ：注入 L3「远端 <host> 未装 pi，是否安装？」
+  ③ 远端 node --version  → 缺 node：同一询问
+  ④ 远端目录可写         → 不可写：报错（权限问题，需人处理）
+```
+
+**三条纪律**（缺一条就会出事故）：
+
+1. **不擅自安装**。缺环境时只**询问**，并把「装什么、装哪里、需要什么权限」说清楚，
+   由人决定。擅自 `curl | sh` 到别人的机器上，是这类工具最容易犯的越界。
+2. **不冒充成功**。环境缺失时 `agent_up` 要**响亮失败**并留下一条待决策项，
+   不是静默降级到本地（那会让人以为活派到了远端，其实在本机跑）。
+3. **问完要能续**。用户答"装"之后，安装动作本身也该是**可见的一步**
+   （能查、能重跑），而不是藏在 `agent_up` 里的隐式副作用。
+
+> ［待定 U2］**安装的具体形态**：由 commondev 执行（需在远端跑包管理器）／
+> 只输出可复制的命令让人去跑／两者都要。本文倾向**后者默认、前者需显式授权**。
+
+---
+
+### 3.5 ★ 自包含运行时（插件自带 node 与 pi）
+
+［已定 2026-10-13 用户拍板］**插件内嵌独立的 nodejs 与独立的 pi**，都**安装在插件工作目录**；
+**pi 的插件也装到这个目录**。这是"自包含"的含义：**不依赖宿主机的 node/pi 版本**，
+也不污染用户的 `~/.pi`。
+
+#### 3.5.1 目录布局
+
+［已定 U7：**随包分发**］独立的 node 与 pi **随插件包一起分发**（不首次下载、不依赖用户装）。
+
+```
+<插件数据目录>/                     ← sdk.Settings().DataDir()
+  runtime/
+    node/            # 独立的 nodejs（随包分发）
+    pi/              # 独立的 pi（随包分发）
+    agentdir/        # ★ pi 的 agent dir（PI_CODING_AGENT_DIR 指这里）
+      settings.json  #   ← pi 自己的配置：偏好 / 默认 model / 「全局」包声明
+      models.json    #   ← pi 自己的配置：兼容端点与模型（LLM 源写这里）
+      auth.json      #   ← pi 自己的配置：API key / OAuth（0600）
+      mcp.json       #   ← pi 自己的配置：MCP 服务器
+      skills/  prompts/  themes/  extensions/
+  program/
+    mirrors/<platform>-<repo>.git/
+    <hash>-<name>/   # 每个工程对话一份；.pi/settings.json = 「临时」安装
+```
+
+> **为什么只用一个 agentdir**：它就是 pi 的「用户级配置目录」，**pi 自己的配置系统**
+> 已经给了我们所需的一切（§3.6）。插件**不自建第二套配置存储**。
+> 根目录权限 **0700**（里面有 `auth.json`/`models.json`，均含明文凭据）。
+
+#### 3.5.2 ★ 两种安装粒度（用户明确要求）
+
+| 粒度 | 作用域 | 落到实处 | 适用 |
+|---|---|---|---|
+| **临时（项目级）** | 一个工程对话 | `<workdir>/.pi/settings.json`（`pi install -l`） | 只这个工程需要的插件 |
+| **全局（插件级）** | 插件自带 pi 的所有工程 | `<agentdir>/settings.json`（`pi install` + `PI_CODING_AGENT_DIR`） | 通用能力（如 pi-lens、subagents） |
+
+⇒ 工具面：
+
+```
+commondev_pi_plugin_install   source, scope=project|plugin, workdir?  # ✅ 已实现
+                              # 支持 npm / git / url / 本地路径（见下）
+commondev_pi_plugin_remove    source, scope       # ✅ 已实现
+commondev_pi_plugin_list      scope?             # ✅ 已实现
+commondev_pi_plugin_update    source?, scope       # ✅ 已实现（PI_CODING_AGENT_DIR 隔离）
+```
+
+**必须把 `PI_CODING_AGENT_DIR` 传给每个内层 pi 进程**，否则「全局」安装会写进
+**用户的** `~/.pi/agent/settings.json` —— 那是对宿主的越界。
+
+#### 3.5.3 支持的源类型 ［已核 `pi install --help`］
+
+| 类型 | 写法 | 备注 |
+|---|---|---|
+| **npm** | `npm:@scope/pkg@1.0.0` | 带版本号即**钉住** |
+| **git** | `git:github.com/u/r@v1` 或 `git:git@github.com:u/r` | tag/commit 钉住；更新不移动 ref |
+| **URL** | `https://github.com/u/r` | **当作 git 源**处理 |
+| **ssh** | `ssh://git@github.com/u/r` | |
+| **本地** | `./path` 或文件路径 | **不复制**，直接引用；文件路径 = 单个扩展 |
+
+**三个安全纪律**（包可执行扩展代码，而这是往工作区/插件里装代码）：
+
+1. **默认不为工程静默安装**：安装是要**显式调用**的一步，不能藏在 `agent_up` 里；
+2. **安装前说明来源**：npm 包名 / 仓库 URL / 版本钉点，让人看得见；
+3. **来源不可信时不装**：与 §3.4 同一条纪律（先问，不擅自）。
+
+---
+
+### 3.6 ★ LLM 源：默认用 HomeAgent 内部配置，支持添加与选默认
+
+［已定 2026-10-13 用户拍板］插件内置 pi **默认使用 HomeAgent 内部配置的 llms 源**，
+**支持添加其他源**，且**支持在插件中配置默认用哪个源**。
+
+#### 3.6.1 源的真实位置 ［已核］
+
+内核把 LLM 源存在 **`config` 表**（不是 `config_<plugin>`），键前缀 `core.llm.`：
+
+```
+core.llm.provider              = llmsproxy        ← ★ 当前默认源（这就是"默认用哪个"）
+core.llm.sources.<name>.base_url       = http://127.0.0.1:8081/v1
+core.llm.sources.<name>.api_key        = sk-gw-...
+core.llm.sources.<name>.model          = AUTO
+core.llm.sources.<name>.adapter        = openai
+core.llm.sources.<name>.adapter_path   = adapters/openai.lua
+core.llm.sources.<name>.context_window = 1048576   （可选）
+core.llm.sources.<name>.priority       = 100       （可选）
+core.llm.sources.<name>.vision|audio   = true|false（可选）
+core.llm.sources.<name>.thinking_enabled = false   （可选）
+```
+
+内核侧已有现成控制面（**不是新造**）：`llm_list_sources` / `llm_set_source` /
+`llm_current_source`（`spawn.go:338` 起），背后是 `ProviderManager`
+（`Register` / `SetDefault` / `List`）。
+
+#### 3.6.2 到 pi 的字段映射
+
+内层 pi 要的是 `models.json`（`providers.<name>.{baseUrl,api,apiKey,models[]}`）。
+源一字段一对：
+
+| 内核（`core.llm.sources.<n>.*`） | pi（`models.json`） |
+|---|---|
+| `base_url` | `providers.<n>.baseUrl` |
+| `api_key` | `providers.<n>.apiKey` |
+| `adapter=openai` | `providers.<n>.api = "openai-completions"` |
+| `model` | `providers.<n>.models[].id` |
+| `context_window` | `providers.<n>.models[].contextWindow` |
+| `vision` | `providers.<n>.models[].input`（含 `"image"`） |
+
+**生成物是一个文件**：`<agentdir>/models.json`（插件自己的，不动用户的）。
+
+#### 3.6.3 落地：**直接写 pi 的配置文件**，不另建存储
+
+［已定 2026-10-13 用户拍板］**pi 配置的源直接写入配置文件**。
+**本稿前版提议的 `config_commondev` 已废弃** —— pi 本身就有完整的配置系统，
+再建一套只会制造两处真相。
+
+| 需求 | 落到实处 |
+|---|---|
+| **默认用内核的源** | 首次拉起时，把 `core.llm.sources.<n>.*` 写进 `<agentdir>/models.json`，key 写进 `<agentdir>/auth.json` |
+| **支持添加其他源** | **直接追加到同一个 `models.json`**（同文件、同格式），不另存 |
+| **在插件中配置默认源** | 写 `<agentdir>/settings.json` 的 `defaultProvider` / `defaultModel`（pi 原生字段） |
+
+⇒ 结果：**内层 pi 看到的就是自己的配置**，插件只是它的**受控写入入口**。
+没有第二处真相、没有同步问题、`pi auth check` / `pi list` 等原生命令全部照常工作。
+
+#### 3.6.4 ★ 配套工具：插件作为 pi 配置系统的受控入口
+
+［已定］**插件要提供对应的 tool 进行对应的配置。** 工具与 pi 的配置文件一一对应：
+
+```
+# —— 源与模型（→ models.json / auth.json / settings.json）——
+commondev_pi_source_add      name, base_url, api_key, model, [adapter, context_window, vision, ...]
+                             # 写 models.json（+ key 写 auth.json）
+commondev_pi_source_list     [--with-key]     # 列出来源（默认**不返回** key）
+commondev_pi_source_remove   name
+commondev_pi_source_default  name, [model]    # 写 settings.json 的 defaultProvider/defaultModel
+commondev_pi_source_import   from_kernel       # 把 HomeAgent 内部配置的源批量导入
+
+# —— 其他 pi 配置面（同一套纪律）——
+commondev_pi_config_get      key, scope=plugin|project, workdir?
+commondev_pi_config_set      key, value, scope   # 直接落 pi 配置文件
+commondev_pi_package_install source, scope       # 详见 §3.5.2（pi install）
+commondev_pi_mcp_add/remove/list                 # → mcp.json
+```
+
+**四条实现纪律**：
+
+1. **写的就是 pi 的配置文件**，不造中间层；格式与 pi 自己写出来的保持一致
+   （否则 pi 重写文件时会把我们的自定义字段抹掉）。
+2. **改前备份、改后校验**：json 写坏了会让内层 pi 直接起不来；
+   写后必须回读校验，失败则回滚并**响亮报错**。
+3. **key 不进日志/不进返回值**：`source_list` 默认不返回 api_key（与
+   `commondev_account_list` 同一条纪律）。
+4. **不改用户全局**：所有写入都带 `PI_CODING_AGENT_DIR=<agentdir>` 或显式 scope，
+   绝不碰 `~/.pi/agent/`。
+
+#### 3.6.5 ★ 两条安全红线
+
+1. **API key 不能明文落盘到无保护的位置**。`models.json` / `auth.json` 里的 key 是明文
+   —— 它们落在 `<agentdir>/`，因此**该目录 0700、文件 0600**；与凭据文件同一套纪律
+   （前篇 §7.1）。内核那套是明文存 `config.db`（且该库 **644 全局可读**），
+   **不要把这套惯例带进来**。
+2. **不得静默回退到宿主凭据**：如果导入失败/源不可用，要**报错**，
+   而不是偷偷用 `~/.pi/agent/auth.json` 里的用户凭据跑起来。
+
+> **为何不复用用户的 `~/.pi`**：那是宿主自己的 agent 环境，凭据归宿主。
+> 插件作为独立工具，拿宿主凭据 = 权限越界（前篇 §7.1 同一理由）。
+
+---
+
+## 4. 生命周期与孤儿清理
+
+［已核］内核的硬约束是「**子不得比父活得久 / 无孤儿 goroutine / 无残留 temp**」
+（`resident-subagent-design.md §10`，写成 S16 判据）。commondev 必须按**同一条纪律**
+管住自己拉起的进程：
+
+| 层 | 谁销毁 | 何时 |
+|---|---|---|
+| pi 进程 / sidecar | commondev `Stop()` | 插件停止、工程对话 close |
+| ssh 会话 | commondev | 同上 |
+| **workdir（`program/<hash>-<name>`）** | `commondev_workdir_clean` | **合入（或废弃）后立即删** |
+| 内核驻留子 | **父 agent**（`resident_agents destroy`） | 主管决定；插件**不能**代劳 |
+| 划入的 inputch | 内核在子销毁时归还 | 自动 |
+
+**workdir 删除时机是用户指定的**：该分支的修改**提交合入后直接删除目录** ——
+不保留、不归档。目录内不得留有可复用状态（尤其是凭据，见前篇 §7.2）。
+
+⇒ **插件 `Stop()` 必须是幂等的全清**，并写成判据：`TestStopKillsAllRuntimes`
+（变异：删掉某个 repo 的清理 → 必须报红）。
+
+---
+
+## 5. 语义缺口（必须显式取舍，不能假装等价）
+
+［已核］内核的两类输入语义与 pi 的两种投递**不等价**：
+
+| 内核 | pi | 差异 |
+|---|---|---|
+| 中断（有级别，**抢占 + 保存现场 + LIFO 恢复**） | `steer`（插到当前轮之后、下次 LLM 前） | pi **不挂起/不恢复**，是「并入当前上下文继续」 |
+| 排队（无级别，FIFO） | `follow_up`（agent 空闲后投递） | 语义接近 |
+
+⇒ 「打断 pi → 事后恢复原任务」这个内核语义，**pi 没有**。三个选项：
+- **(i) 接受降级**：steer 即"插话"，不承诺恢复（简单，但主管必须知道断点在哪）；
+- **(ii) 插件补保存/恢复**：记下 steer 前的目标，之后用 `follow_up` 补投；
+- **(iii) 用 `--fork` 分叉**：纠偏走新分支，原会话留作对照（代价：会话数增长）。
+
+［待定］见 §6 U4。
+
+---
+
+## 6. 未决问题（需用户拍板）
+
+| 编号 | 问题 | 本文建议 |
+|---|---|---|
+| **U1** | commondev 的 **L4 上限**：接受 L3 / 改内置插件 / 加插件侧"上级"通路 | **先接受 L3 跑通**；L4 等需求真出现再做（`SetKernelSource` 属 ABI 变更，要按"只增不减"+ 同步 SDK 仓 + hmapdev 模板） |
+| **U2** | 远端环境缺失时的**安装形态** | 默认只**输出可复制命令**供人去跑；由插件代装需显式授权（§3.4）。环境缺失时**先询问用户，不擅自安装** |
+| **U3** | pi 进程**常驻保活** 还是**用完即弃**（靠 session-id 保连续） | ✅ **已定：常驻**（刀 1 已如此：sidecar 持续存活并复用同一会话，`branch_close` 才收） |
+| **U4** | steer 的**语义降级**取舍 | (i) 接受降级，但把"断点"写进台账供主管复查 |
+| **U5** | skill 的**分发目标** | 双投：主管侧（HomeAgent `<data_dir>/skills/`）+ 执行侧（工作区 `.pi/skills/`） |
+| **U6** | 「工程对话」的**用户可寻址名** | ✅ 已实现：sidecar 接收 `--session-name`，agent_up 返回并记账 `session_name` |
+| **U7** | **独立 node/pi 的获取方式** | ✅ **已定：随包分发**（不首次下载、不依赖用户装） |
+| **U8** | 内层 pi 的**版本锁定** | 部分实现：`pi_version` 已从 sidecar 回显并记账；随包独立 pi 二进制的发布锁定仍待发布流程完成，解析不到时显式警告 |
+| **U9** | `auth.json`/`models.json` 中 key 的处理 | ✅ **已定：常驻文件 + 0700/0600**（实测生效：目录 0700、文件 0600 + 回读校验） |
+| **U10** | 插件私有源的**存储位置** | ✅ **已定：不存在“私有源存储”** —— 直接写 pi 自己的配置文件（§3.6.3）。插件自身的 Git 凭据存**独立 0600 文件** `<data>/credentials.json`（已实现，启动时校验权限） |
+
+---
+
+## 7. 自检清单（逐条可复现）
+
+```bash
+# §1.2 自包含运行时：agent dir 可重定向、不污染用户全局
+mkdir -p /tmp/st/{agentdir,work,pkg/extensions}
+# 建一个最小包（package.json 带 keywords:["pi-package"] + pi.extensions）
+cd /tmp/st/work && PI_CODING_AGENT_DIR=/tmp/st/agentdir pi install /tmp/st/pkg
+cat /tmp/st/agentdir/settings.json          # 期望 packages 写在这里
+python3 -c "import json;print([p for p in json.load(open('/root/.pi/agent/settings.json'))['packages'] if 'st' in str(p)])"
+#                                           期望 [] ⇒ 用户全局零污染
+
+# §1.2 ⚠ 安装是复制：改源目录不影响已装的（我曾因此误判"插件不生效"）
+
+# §3.5.2 两种粒度
+cd <workdir> && pi install -l ./pkg         # 临时 ⇒ <workdir>/.pi/settings.json
+PI_CODING_AGENT_DIR=<agentdir> pi install /abs/pkg   # 全局 ⇒ <agentdir>/settings.json
+
+# §3.6.1 LLM 源的真实位置
+sqlite3 /home/newqqagent/config.db \
+  "select key,substr(value,1,60) from config where key like 'core.llm.%' order by key;"
+#   期望：core.llm.provider=llmsproxy + core.llm.sources.<n>.{base_url,api_key,model,adapter,...}
+
+# §1.1 会话续投（同一 session-id）
+mkdir -p /tmp/p1 && cd /tmp/p1
+pi -p --session-id chk-01 "记住暗号：紫罗兰-7734"        # → 记住了
+pi -p --session-id chk-01 "刚才的暗号？"                  # → 紫罗兰-7734
+ls ~/.pi/agent/sessions/--tmp-p1--/                       # 只有一个 chk-01 文件
+
+# §1.1 并发打同一 session 会写坏（判据的反例）
+#   两条 -p 同 --session-id 并发；检查 jsonl 里 user 消息是否相邻、assistant 是否错序
+
+# §1.1 会话库可搬且不污染全局
+pi -p --session-dir /tmp/sd-store --session-id sd-01 "…"
+ls /root/.pi/agent/sessions/ | grep -i sd-test      # 期望无结果
+
+# §1.3 可接入面
+grep -n "func (s \*PluginSDK) RegisterInputChannel" third_party/homeagent-sdk/sdk/plugin.go
+grep -rn "resident_agents" internal/plugin/proc/    # 期望无结果 ⇒ 插件调不到
+
+# §2.4 L4 归属
+grep -n "isKernelLevelSource" -A20 internal/agent/core/scheduler.go   # 期望两条分支
+grep -n "clampExternalPriority" -A10 internal/plugin/proc/corehandler.go
+
+# §2.1 inputch 路由发生在进内核之前
+cat internal/agent/core/inputroute.go
+```
+
+---
+
+## 8. 给接手者的三条提醒
+
+1. **不要另起一套调度器**。内核已有四级中断 / 两类输入 / 可抢占 / 中断栈 / 驻留子 /
+   处理表 —— 插件的活是**把 pi 接进 inputch 路由**，不是重实现。
+2. **不要用提示词软约定替代机制**。「让 agent 记得传 `--session-id`」是软约定；
+   台账记 `session_id` + 投递后断言未变，才是机制（§3.3）。
+3. **孤儿进程 = 插件的责任**。内核对自己的子有硬约束（S16），插件对自己的进程
+   必须同样硬（§4）。
diff --git a/docs/zh/commondev-design.md b/docs/zh/commondev-design.md
index 4cba7944..9151aa45 100644
--- a/docs/zh/commondev-design.md
+++ b/docs/zh/commondev-design.md
@@ -1,7 +1,22 @@
 # CommonDev：主管式多仓库开发流水线（设计 · 未实现）
 
-> **状态：设计稿，尚未实现。** 本文只描述目标机制、已核实的事实、未决问题与建议的
-> 落地顺序。接手者请从 §9 开始，并按 §10 的自检清单逐条验证本文的每一项事实陈述。
+> **状态：架构已变更（见 §12）。** **git 托管平台专有的工具**已移出插件、进 skill；
+> 其余机制（台账、工作目录、pi 会话与通道、判据与变异复核、冲突预检、凭据）保留。
+> §4.1 里的平台工具清单**不再是实现目标**；§13 保留历史实现审计供追溯。
+> 接手者请从 §12 开始读。
+>
+> **续篇（必读）**：`docs/zh/commondev-agent-runtime-design.md` —— 运行时与内核接入
+> （工程对话四元组、内嵌/SSH 两形态、inputch 路由、L4 归属、语义缺口）。
+> **本文 §6.1 的结论已被续篇修正**（只论证了 cwd 一维）。
+>
+> **★ 安全模块（计划追加）**：`docs/zh/kernel-secret-firewall-design.md` ——
+> 敏感信息拦截**下沉为内核安全模块**（用户纠正：LLM 调用本身不可信，插件拦截不算边界）。
+> 该文成立后，**本插件侧的加密 shell 会大幅变薄**（不再自带加密库/别名表）。
+>
+> **★ 设计总纲 ［已定｜2026-10-13］**：插件对 pi 做的事，本质就是
+> **「把给 pi 发消息包装一下、把 pi 返回包装一下」，并深度融合内核的 IO 抽象与中断系统**
+> —— 即 **pi = 一个 Device**。**不自己造调度器/会话路由/中断**，全部接到内核已有的那套上。
+> 详见续篇 §2.5 / §3.1。
 >
 > **标记约定**（沿用本仓惯例）：
 > - **［已核］** = 本文写作时已在本机实测/源码核对确认，附证据
@@ -57,11 +72,20 @@
 项目列表（每项目一条）
   └─ 分支列表（每分支：名字 / 分配给哪个 agent / 工作内容 / 验收状态 / base_sha）
        └─ 临时工作目录（插件数据目录下 program/<hash>-<name>/）
-            └─ 独立仓库的独立分支（clone 或 worktree）
-                 └─ 拉起 agent（注入提示词，cwd = 该目录）
-                      └─ agent 自审 → 主管复审 → 插件复核 → 提 PR → 合入
+            └─ 独立仓库的独立分支（本地 clone）
+                 └─ ★ 拉起 pi 并拿到 session_id
+                      └─ ★ 才有通道：插件注册 inputch commondev/<id>
+                                             + outputch commondev_<id>
+                           └─ 主 agent 建驻留子并划入这对通道
+                                └─ 子调 output_send__commondev_<id> 下任务
+                                     └─ agent 自审 → 主管复审 → 插件复核 → 提 PR → 合入
 ```
 
+> **顺序要点（容易搞反）**：**先有 session，才有通道**。通道是“与某个具体 pi 会话
+> 对话的入口”，没 session 注册出来就是空壳。所以：
+> **建工程 → 拉 pi（拿 session）→ 注册通道 → 建驻留子并划入 → 投递**。
+> 详见续篇 §2.2。
+
 **插件应提供的能力面**（用户列举）：
 
 1. 远程 git 仓库全套操作（clone / fetch / branch / commit / push / PR / merge）
@@ -221,6 +245,22 @@ commondev_branch_close        收尾清理（merge 后或废弃时）
 commondev_workdir_prepare     准备/复用临时工作目录（mirror 派生，见 §4.3）
 commondev_workdir_clean       清理临时目录（含凭据残留检查，见 §7.2）
 
+# 内置 pi 的运行时（★ 本质是“包一下”：发消息 / 收返回，见续篇 §2.5 §3.1）
+commondev_agent_up            拉起 sidecar（内嵌 pi；remote 时 ssh）并登记台账
+commondev_agent_state         查 session / runtime / 健康
+commondev_agent_down          收尾（幂等全清，不留孤儿）
+# ★ 下任务**不走插件工具**：子调内核原生的 output_send__commondev_<id>(payload=…)，
+#   插件写的通道 handler 负责“包一下”→ sidecar.prompt（见续篇 §2.5）。
+# “中断/纠偏 pi”走**内核已有的** InjectInterrupt（L3），也不另造工具。
+commondev_pi_plugin_install   ★ 为内置 pi 装插件（scope=project 临时 / plugin 全局）
+commondev_pi_plugin_remove    卸载（同 scope 语义）
+commondev_pi_plugin_list      列出已装（分 scope）
+commondev_pi_source_import    ★ 把 HomeAgent 内部配置的 LLM 源导入内置 pi
+commondev_pi_source_add       添加一个源（直接写 pi 的 models.json/auth.json）
+commondev_pi_source_list      列出可用源（默认**不返回** api_key）
+commondev_pi_source_default   ★ 指定内置 pi 默认用哪个源（写 settings.json）
+commondev_pi_config_get/set   读写 pi 配置（scope=plugin|project）
+
 # 判据与复核
 commondev_test_define         **主管**定义一条判据（落地成可执行脚本 + 期望）
 commondev_test_run            执行判据集合（正向）
@@ -258,33 +298,124 @@ review_runs
 没有它，插件无法判断「两个 PR 改了同一文件时第二个该不该 rebase、能不能自动合」，
 出问题也无法重放。建议在 `commondev_pr_open` 前做 conflict 预检。
 
-### 4.3 临时工作目录：用 mirror 派生，不要每个任务全量 clone
+⇒ **刀 3 已落地**（见 §4.6）。
 
-用户描述「每次修改都是拉取仓库」。直接 clone 的问题：Go 这类仓库一份全量历史可达
-数百 MB，并行十个就不合适。
+### 4.3 临时工作目录：mirror + **本地 clone（硬链接）** ［已定 2026-10-13］
 
-**建议**（**［待定］**，需接手者评估）：
+**用户拍板**：每个工程对话一个独立目录 `program/<hash>-<name>`（`name` = **仓库名**），
+**该分支修改提交合入后直接删除该目录**。因此需要「删掉即彻底」，这直接排除了两个
+候选方案（均实测）。
 
 ```
 <插件数据目录>/program/
-  mirrors/<platform>-<repo>.git/     # git clone --mirror，每个项目一份，定期 fetch
-  work/<hash>-<name>/                # 每个任务一份，由 mirror 派生
+  mirrors/<platform>-<repo>.git/   # git clone --mirror，每仓库一份，定期 fetch
+  <hash>-<name>/                   # 每个工程对话一份；合入后整目录删除
 ```
 
-派生方式二选一（都要实测磁盘与耗时）：
-- `git clone --reference <mirror> <mirror> <workdir>`（`--dissociate` 可选）
-- `git worktree add`（注意 §3.8：同分支不可双挂——这反而是好事，能防两个 agent 抢同一分支）
+`<hash>` 用「项目名 + 分支名」的短哈希，**保证可重算**（便于清理孤儿目录），
+并且 **hash 是目录唯一性的来源**。
 
-> **注意**：用户原话是「每个目录下是**独立仓库**的独立分支」。若严格按「独立仓库」，
-> worktree 就不适用（它是同仓库多工作区）。**这是需要与用户确认的选择**（§8.1）。
+#### 目录映射：★ 同一仓库的不同分支必然是不同目录 ［已定 2026-10-14］
 
-### 4.4 目录命名
+用户明确要求：
 
-用户描述 `program/hash-name`。建议：
-- `hash` 用 `项目名 + 分支名` 的短哈希，**保证可重算**（便于清理孤儿目录）
-- 目录内记录一份 `_commondev.json`（项目/分支/agent/base_sha/凭据指纹），便于事后审计
+> 「即使是同一个仓库，只要是不同的分支都拉到 hash-name 下使用 hash 区分，
+>   插件通过哈希表映射工程分支与文件夹」
+
+```
+branchKey(project, branch) = project + "\x00" + branch
+   └─ shortHash() → <hash>（8 位 16 进制，可重算）
+        └─ program/<hash>-<name>      其中 name = 分支名派生（可读性）
+```
+
+**两条职责必须分清**（这是本节能防住的事故）：
+
+| 要素 | 承担什么 | 为什么 |
+|---|---|---|
+| **hash** | ★ **唯一性** | 一个仓库可并行多条分支；唯一性只能由 hash 承担，**不依赖 name** |
+| **name** | 可读性 | 清理孤儿/审计时纯 hash 无信息量 |
+
+若只按仓库名建目录，两条分支会**共用同一个工作树** —— 那是灾难性的：
+agent A 的未提交改动会出现在 agent B 的 `git status` 里，且「独立 clone」的前提（§4.3）不成立。
+
+**验证**（已实施）：`branchDir("TrueAgent","feat/a") != branchDir("TrueAgent","feat/b")`，
+且同输入可重算。变异（hash 只用项目名）→ 报红。
+
+**⚠️ name 不能承担唯一性**：分支名经派生后可能撞（如 `feat/a` 与 `feat.a` 都派生为 `feat_a`），
+所以目录名必须带 hash。
+
+**映射是双向的、且只有一处真相**：目录名可由 `(project, branch)` 重算；
+反查靠台账的 `branch.Workdir`（`resolveBranchDir`）。
+**绝不要在映射函数之外另算目录名**。
+
+**孤儿检测**：`program/` 下符合 `<hash>-<name>` 形态、但台账里无记录的目录 = 孤儿
+（`listOrphanDirs`）。非本插件形态的目录不碰。
+
+#### 为什么是本地 clone，而不是 worktree 或 `--reference`（均实测）
+
+| 方案 | `rm -rf` 之后 | 外部依赖 | 结论 |
+|---|---|---|---|
+| **worktree** | **`.git/worktrees/<name>` 残留**，状态变 `prunable`；必须再跑 `git worktree prune` 才清 | 无 | ❌ 删除不彻底；中央仓需持续维护 |
+| **`--reference`**（本稿初版建议） | 干净 | **★ `.git/objects/info/alternates` 指向 mirror** | ❌❌ **mirror 一旦被清理，work tree 彻底损坏**：实测 `error: unable to normalize alternate object path`，之后**每次** git 操作都报错 |
+| **本地 clone** | **干净**（只剩源仓） | **无** | ✅ **对象是硬链接** ⇒ 省磁盘（实测两侧对象 inode 完全相同）；删掉即彻底 |
+
+```bash
+git clone <mirror> <workdir>          # 本地 clone：硬链接共享对象、无 alternates
+```
+
+> **为什么硬链接这件事重要**：本地 clone 复制对象时用硬链接（实测 inode 相同，如
+> `5836713`），因此并行 N 份工作树**几乎不额外占磁盘**，同时**每个目录都是完整自洽的仓**
+> —— 既无 worktree 的中央元数据，也无 `--reference` 的外部依赖。
+> 两个要求（「删除彻底」与「不是每任务全量 clone」）同时满足。
+
+#### 已考虑并否决的替代方案
+
+> **用 worktree + 只删分支（不删目录）**：即「删掉分支名但留下 worktree 目录」。
+> **不采纳**：残留的 checkout 会持有一个已删除分支的引用，下一次同名分支的
+> worktree 创建可能冲突（实测 `fatal: 'feat/a' is already used by worktree`）；
+> 且目录永远删不干净，与用户要求的「合入后直接删除目录」相悖。
+
+#### ⚠️ 失去的一条保护，必须用台账补回
+
+worktree 天然禁止「同一分支被两棵工作树同时挂」—— 实测
+`fatal: 'feat/a' is already used by worktree at '...'`。**改用独立 clone 后这条保护消失了**：
+两份 clone 可以在同名分支上各自 push，后者会被拒（非 fast-forward）而暴露问题，
+但**在 push 之前**两边都以为自己是唯一。
+
+⇒ **必须在台账层补一道唯一性闸**：
+
+- `branches` 表对 `(project_id, name, status IN ('open','review'))` 建**唯一索引**；
+- `commondev_branch_open` 遇到同名且仍开着（或已进 review）的分支必须**响亮拒绝**，
+  不是静默复用。
+
+（用户为「一个仓库并行开发」选择独立 clone 是**正确的** —— 代价只是这道补偿闸。）
+
+#### 目录生命周期
+
+```
+branch_open
+  └─ 建 <hash>-<name>/（由 mirror 本地 clone）
+       └─ 干活 → 提交 → push → PR
+            └─ 合入（或废弃）
+                 └─ ★ 整目录删除（不保留、不归档）
+```
+
+> **删除是收尾动作的一部分**：合入后不删，下次同名分支会与残留目录混淆；
+> 并行开发的意义就是「用完即清」。与内核「子不得比父活得久、无残留」同一条纪律
+> （见续篇 §4 孤儿清理）。
+
+### 4.4 目录命名与并行开发
+
+- 目录：`program/<hash>-<name>`，`<hash>` = 项目名+分支名短哈希（★ **唯一性来源**），
+  `name` = 分支名派生（**只做可读性**，不承担唯一性，见 §4.3）
+- **一个仓库可并行开发**：每分支一份独立 clone ⇒ 互不污染、可同时推进
+- 目录内记录 `_commondev.json`（项目/分支/agent/base_sha/凭据指纹），便于事后审计
 - **不要**把凭据写进目录（见 §7.2）
 
+> **并行是有前提的**（见 §8.4）：并行的必须是**互不相干的模块**。
+> 若任务间有依赖（A 改接口、B 用接口），两棵独立 clone 互不可见，
+> 问题会集中到 merge 时爆发 —— 那时应先拆边界，再谈并行。
+
 ### 4.5 ★ 复核必须是两步：正向 + 变异（本文最重要的设计主张）
 
 用户原话：
@@ -327,6 +458,143 @@ review_runs
 
 ---
 
+### 4.7 ★ 刀 3：conflict 预检与 base_sha ［✅ 已完成 · 真实 git 实测］
+
+#### 为什么这一刀必须做
+
+并行开发（§4.4）让冲突从"可能"变成"必然"：每分支一份独立 clone，
+两棵树**互不可见**。冲突不会在开发时暴露，而是**全部堆到 merge 时爆发** ——
+那时判据已经变绿、复审已经通过，却发现合不进去。
+
+⇒ 必须在**提 PR 之前**就发现。
+
+#### 做法：`git merge-tree --write-tree`（**完全不碰工作区**）
+
+实测 git 2.53 的退出码语义：
+
+| 退出码 | 含义 |
+|---|---|
+| `0` | 可干净合并 |
+| `1` | 有冲突 |
+| 其它 | 命令本身失败（**不能当成"无冲突"**）|
+
+★ **它不写索引、不动 HEAD、不留 MERGE_HEAD** ⇒ 可以在任何时候安全地跑，
+不需要 stash/checkout，也不会破坏正在进行的开发。这一条有判据钉住
+（跑完预检后断言 HEAD 未变、无 MERGE_HEAD、工作区零改动）。
+
+#### 三类结果必须分开（防静默降级）
+
+| 结果 | 语义 |
+|---|---|
+| `Mergeable: true` | 检查过，可合并 |
+| `Mergeable: false` + `Conflicts` | 检查过，有冲突（列出文件）|
+| **`Skipped: true`** | **没检查**（目标分支本地不存在 / 非 git 仓库 / merge-tree 不可用）|
+
+★ **`Skipped` 时绝不声称可合并** —— 把"没检查"当成"检查通过"是最危险的
+静默降级，调用方会以为安全。有判据**逐条覆盖全部 Skipped 出口**
+（初版只测了其中一条，于是另一条的变异不报红 —— 判据覆盖不全等于留洞）。
+
+#### `base_sha` 的捕获时机
+
+在 `runPrepareWorkdir` 里、**目录就绪后立刻**记 —— 必须在 agent 开始改之前。
+agent 一旦提交，HEAD 就不再是"这条线从哪出发"。
+
+★ **只记第一次**：重开同一分支时若覆盖基点，"这条线从哪出发"就永久丢失，
+冲突判定与事后重放都失去依据。
+
+#### 新增工具
+
+| 工具 | 作用 |
+|---|---|
+| `commondev_conflict_check` | 提 PR 前预检可合并性（只读，`ParallelSafe`）|
+| `commondev_parallel_status` | 盘点并行推进的分支线（按项目分组），派活前确认边界 |
+
+#### ☆ 实测发现
+
+**冲突解析有两条独立路径**，缺一不可：
+
+1. `CONFLICT (content): Merge conflict in <path>` 行
+2. `100644 <oid> <stage>\t<path>` 的 ls-tree 阶段行
+
+前者覆盖常见情形，后者覆盖**不打印 CONFLICT 行**的冲突类型（如 rename/rename）。
+实测：只保留路径 ①、把 ② 的判定前缀改坏，**"仅 ls-tree 形态"的判据会报红** ——
+说明 ② 是真·载重路径，不是冗余。
+
+#### 判据与变异
+
+`conflict_parse_test.go` 8 条（含**真实 git 仓库**的端到端：可合并 → 合入后冲突
+→ 工作区零影响）；变异 6 条全部咬住（含 1 次暴露判据覆盖不全、1 次暴露
+"冗余路径其实是载重路径"）。
+
+---
+
+### 4.8 ★ 刀 4：判据与复核（正向 + 变异） ［✅ 已完成 · 真实 go test 端到端］
+
+#### 核心命题：插件 GREEN ≠ 改对了
+
+设计 §4.5 的主张在本刀**落地并用真实数据验证**。我在 `/tmp` 复刻过最小场景：
+
+```go
+func Max(a, b int) int { if a > b { return a }; return b }
+```
+- 松判据只测 `Max(5,3) == 5`（漏了 `b>a`）
+- 变异 `return b` → `return a`（**真 bug**）⇒ **判据仍全绿**
+- 补一条 `Max(3,5) == 5` ⇒ 同一变异**立刻报红**
+
+⇒ **没有反向阶段，就是在给「测试通过」这个信号不断充值信用，
+直到它骗一次大的。**
+
+#### 两阶段
+
+| 阶段 | 做什么 | 不通过意味着 |
+|---|---|---|
+| **正向** forward | 跑判据 | 实现有 bug |
+| **反向** mutate ★ | 把文件里 `old` 换成 `new`，期望判据**报红** | **判据太松**（该变异没被看见）|
+
+#### 结论三档（**不合并成一个绿勾**）
+
+| verdict | 含义 |
+|---|---|
+| `pass` | 正向全过 **且**全部变异被咬住 |
+| `pass_with_gaps` | 正向过，但**有变异未被咬住** 或**有判据没定义变异规则** |
+| `fail` | 有判据未通过 |
+
+★ `pass_with_gaps` **不是"通过"** —— 它是「判据没覆盖到」。
+把它说成通过，就是本刀要消除的那种"信号充值"。
+
+#### 新增工具
+
+| 工具 | 作用 |
+|---|---|
+| `commondev_test_define` | 主管定义判据（**幂等**：同定义重复登记不改动）；必须同时给 `mutations` |
+| `commondev_test_list` | 列出判据（含变异条数 —— **为 0 的是复核缺口**）|
+| `commondev_review_submit` | 跑复核（后台作业：判据可能含编译/压测，超 60s 工具上限）|
+| `commondev_review_result` | 取结论与历史（含逐条证据）|
+
+#### ☆ 实现要点（每条都对应一个可致错的点）
+
+| 点 | 为什么 |
+|---|---|
+| **必须 `-count=1`** | Go 默认缓存测试结果。实测：变异后若命中缓存，测试**根本没跑**，"报红"无从谈起 |
+| **变异必须恢复文件** | `defer` 保证 panic 也恢复；且恢复后**校验内容一致**——恢复不回去比变异本身危险（agent 会基于坏代码继续改）|
+| **`old` 必须恰好出现一次** | 出现 0 次 ⇒ 变异无效，却被误报成"判据太松"（**假警报**）；出现多次 ⇒ 可能改错地方，却报"咬住"（**假通过**）|
+| **通过由退出码判定** | 不是看输出里有没有 `PASS`（输出可被伪造/污染）|
+| **固定判据顺序** | map 遍历随机 ⇒ 报告不可对照 |
+
+#### 判据与变异
+
+`criteria_test.go` 10 条 + `e2e_criteria_test.go` 2 条（**真实项目 + 真实 go test**）；
+变异 5 条对**复核机制本身**做变异（元层级），全部咬住 ——
+包括「变异后不恢复文件」「变异未咬住却报 ok」「无变异规则却给 pass」。
+
+#### ⚠️ 尚未做（原计划的"模板库"部分）
+
+设计 §6.4 原写「测试模板库（压力/接口/编译）」，本次落地的是**机制**
+（判据定义 + 复核执行），**预置模板库**仍未做。理由：
+机制不成立时模板是摆设；现在机制已用真实数据证明，模板可以后续按需补。
+
+---
+
 ## 5. 与现有系统的关系
 
 | 现有物 | 关系 |
@@ -343,17 +611,34 @@ review_runs
 
 ## 6. 关键决策建议（未拍板，供接手者与用户确认）
 
-### 6.1 拉起 agent：走 CLI，不走 A2A/ACP ［本文建议］
+### 6.1 拉起 agent：走 CLI 家族，不走 A2A/ACP ［本节已由续篇修正］
+
+> **⚠️ 修正（2026-10-13）：** 本节初稿只论证了 **cwd** 一个维度就下了结论，
+> **论据不全**。用户明确要求「投递必须落到**同一个会话**，不能前一个没做好就投给新会话」，
+> 而 `pi -p` 每轮一个进程，**无法保证**这一点（实测：漏传 `--session-id` 会静默开新会话；
+> 并发传同一个 id 会写坏会话）。
+>
+> 正确的两轴（会话粒度 × cwd 由谁承担）与形态取舍，见续篇
+> **`docs/zh/commondev-agent-runtime-design.md` §1.2 / §3**。
+> 本节保留，只作为「A2A/ACP 为何被排除」的论据（该结论本身没变）。
 
 | 方案 | 优点 | 缺点 |
 |---|---|---|
-| **`pi -p`（CLI）** | 进程 cwd 即工作目录（**已实测**）；一次性进程，天然按任务隔离；零协议改动 | 每次冷启动（可接受）；需要自己管进程与超时 |
+| **`pi -p`（CLI）** | 进程 cwd 即工作目录（**已实测**）；一次性进程，天然按任务隔离；零协议改动 | **无法保证续投同一会话**（见上）；每次冷启动；无中途纠偏 |
+| **`pi --mode rpc`（常驻）** | 同 cwd；同会话续投；`steer`/`follow_up` 可中途纠偏；`get_state` 可断言 session 未变 | 要实现/复用 RPC 客户端；stdout 必须持续读 |
+| **Node SDK（进程内）** | 最贴身；`createAgentSession({cwd})` 可控 cwd 与会话 | 需 Node 宿主 |
 | `dsh headless` | 同上 | 本机凭据失效，需先修 |
-| 扩建 A2A | 复用现有插件 | 要改扩展 + payload；ACP 的 session 模型本就假设长驻，加 cwd 是**违背其设计意图** |
-| 扩建 ACP | 同上 | 同上 |
+| 扩建 A2A | 复用现有插件 | 要改扩展 + payload；**参数里没有 cwd**（§3.4） |
+| 扩建 ACP | 同上 | 同上；且 ACP 的 session 模型本就假设长驻，加 cwd 是**违背其设计意图** |
 
-**建议**：第一刀用 `pi -p`。它同时满足「指定目录」与「一次性拉起」两个硬需求，
-且不需要动任何协议。A2A/ACP 留给「需要与**常驻** agent 对话」的场景。
+**修正后的建议**：**内嵌 sidecar 为默认形态**，远程 SSH 由配置切换
+（两形态共用同一 sidecar，差异只在传输层）。`pi -p` 仅作侧车不可用时的降级，
+**不是正式形态**。A2A/ACP 依然排除（「无 cwd」这条事实没变），
+排除理由与本需求无关：它们是**常驻 peer** 的模型，而本需求是**按工程对话拉起**。
+
+**选型已定 ［2026-10-13 用户拍板］**：**默认内嵌（进程内 pi 实例）**，
+配置可切到**远程 SSH**；远端同样**创建目录并在该目录拉起 pi 实例**。
+远端环境缺失时**询问用户、不得擅自安装**（见续篇 §3.4）。
 
 ### 6.2 第一刀只做一个平台、一个项目、一个任务
 
@@ -368,14 +653,57 @@ review_runs
 
 **这一刀的目的不是功能完整，是证明「假绿检测」这一环真的能工作。**
 
-### 6.3 权限模型：让「必须有主管复审」成为机制而非礼貌 ［建议］
+### 6.3 权限模型：让「必须有主管复审」成为机制而非礼貌 ［✅ 已完成 · 真实 Gitea 实测］
 
 若执行 agent 所用的凭据能 push 主干，则「主管复审」只是**流程约定**——想绕过随时能绕过。
 
-建议（依赖 Gitea 分支保护）：
-- 执行侧凭据：**只能 push `feat/*`，不能 push `main`，不能合 PR**
-- 主管侧凭据：**能合 PR**
-- 这样「用户只与主管对接」在用户不在场时**也成立**
+**机制**（已在真实 Gitea 1.24.2 上逐条实测）：
+
+| 动作 | 执行侧凭据 | 主管侧凭据 |
+|---|---|---|
+| push `main` | ❌ `pre-receive hook declined` | （不需要）|
+| push `feat/*` | ✅ | ✅ |
+| 开 PR | ✅ | ✅ |
+| **自合 PR（无审批）** | ❌ `Does not have enough approvals` | ❌ |
+| 审批（带 commit_id）| ❌（角色不符） | ✅ |
+| 合 PR（有审批）| — | ✅ |
+
+★ **限制的真身是平台的分支保护**（`enable_push:false` + `required_approvals≥1`），
+不是插件里的判断 —— 插件在信任边界外，改一行代码就能绕过；平台的
+pre-receive hook 不能。这是刀 2 与「流程约定」的本质区别。
+
+**实现落点**：
+
+| 件 | 作用 |
+|---|---|
+| `Account.Role`（`executor`/`supervisor`） | 标注凭据能做什么；空值按 supervisor（兼容老数据）|
+| `commondev_protect_branch` | 幂等建立分支保护（只改必要项，不反复改用户仓库）|
+| `commondev_pr_approve` / `commondev_pr_merge` | 主管侧动作，按角色选凭据 |
+| `accountForRole` | 角色不符时**明确报错**（而非让平台报一个看不懂的错）|
+
+**`defaultProtection()` 的四条**（每条堵一条绕过路径，均有判据钉住）：
+
+| 字段 | 值 | 堵住的绕过 |
+|---|---|---|
+| `enable_push` | `false` | 执行侧直接推 main |
+| `required_approvals` | `≥1` | 无人审批也能合 |
+| `block_admin_merge_override` | `true` | **admin 绕过**（主管账号的后门）|
+| `dismiss_stale_approvals` | `true` | 审批后追加提交偷换内容 |
+
+#### ☆ 实测踩到的三个 API 坑（都不是文档里写着的）
+
+| 坑 | 现象 | 真因 |
+|---|---|---|
+| **`event` 必须是 `APPROVED`** | 传 `APPROVE` **返回 200 不报错**，但 review 落成 `PENDING` ⇒ 合并报 "Does not have enough approvals"（看起来像权限问题）| 枚举少了个 D |
+| **审批必须带 `commit_id`** | 不带时同样落成 `PENDING`（与 event 是两个独立条件）| 审批要绑定具体提交 |
+| **`required_approvals` 也管 admin** | admin 没有绕过审批的特权 | 这是**正确的** —— 否则"复审"对 admin 形同虚设 |
+
+附带（正确行为但要知）：`REQUEST_CHANGES` 会**阻断**合并，即使同时有 `APPROVED`。
+
+#### 判据与变异
+
+`protection_test.go` 11 条；变异 9 条全部咬住（含 1 次暴露判据测错层次 ——
+只测 `platformMessage()` 没测 `MergePR` 是否调用它）。
 
 ### 6.4 落地顺序
 
@@ -383,9 +711,18 @@ review_runs
 |---|---|---|
 | **0** | **修「能拉起 agent」**（§3.6） | 前提是否成立 |
 | **1** | 单平台单项目：mirror → 分支 → 拉起 → 判据+变异 → PR | 机制成立，假绿可检测 |
-| 2 | 接 Gitea 分支保护 + 执行/主管双凭据 | 复审是机制不是礼貌 |
-| 3 | 多项目 + 并行 + conflict 预检 | 可扩展 |
-| 4 | 测试模板库（压力/接口/编译） | ⚠️ **放最后** |
+| 2 | 接 Gitea 分支保护 + 执行/主管双凭据 | ✅ **已完成**（真实 Gitea 1.24.2 实测，见 §6.3）|
+| 3 | 多项目 + 并行 + conflict 预检 | ✅ **已完成**（真实 git 实测，见 §4.6）|
+| 4 | 判据与复核（正向 + 变异） | ✅ **已完成**（真实 go test 端到端，见 §4.8）|
+| **S** | **★ 内核安全模块（Secret Firewall）** —— 见
+  `docs/zh/kernel-secret-firewall-design.md`。
+  插在 **provider 层**（已核：构造 `CompletionRequest` 有 7 处，task 层拦不全）。
+  **它先行的理由**：插件把密钥明文直接投给 LLM（用户拍板）—— **没有这道闸，
+  密钥就真的发出去了**。而 2/3/4 刀都要用凭据（push / PR / 测试），
+  它们建立在“提交密钥是安全的”这个前提上 ⇒ **安全模块是它们的前提**。 | 凭据不泄露 |
+
+> **第 S 刀的位置说明**：它不排在 2/3/4 之后，而是**与刀 2 并行且先行**。
+> 这与刀 0 同理：**前提不成立时，不要继续构建上层**。
 
 > **第 4 刀为什么放最后**：它最容易写，也最容易变成摆设。先让「变异能咬住」
 > 这一环成立，模板才有意义。
@@ -408,6 +745,49 @@ commondev 的凭据是**能 push 用户所有仓库**的凭据，性质完全不
    **不要一个 token 通吃**
 4. 接 `git push` 时走 **credential helper / 环境变量注入**，**不要**写进 git config 文件
 
+#### ★ 变量填充引用 ［已定 2026-10-14 · 用户要求］
+
+用户明确要求：「gitea / gitcode / github 等主流系统的 ackey 保存与**通过变量填充引用**」。
+
+**核心设计：按名字引用 + 值可写 `${ENV_VAR}`**
+
+```
+commondev_account_add(name="gitea-local", platform="gitea",
+                      token="${GITEA_TOKEN}",          ← ★ 引用，不是明文
+                      base_url="http://192.168.2.106:3000")
+
+之后一切操作只带**凭据名**：
+commondev_branch_open(..., account="gitea-local")   ← 参数里永远不出现 secret
+```
+
+**为何要变量填充**（三个真实好处）：
+
+| 好处 | 说明 |
+|---|---|
+| 明文不落盘 | 文件里只有 `${GITEA_TOKEN}` |
+| 环境可切换 | 同一份配置，dev/prod 换环境变量即可 |
+| 轮换不需改数据 | 改环境变量 + 重启即可 |
+
+**两条不可逆的纪律**：
+
+1. **变量解析不到值 ⇒ 响亮报错**，绝不静默当空串。
+   后者会退化成匿名访问，表现成 **401** 而非“凭据没配” —— 极难排查。
+   实测：`${NONEXISTENT_VAR_ZZZ}` → 报“凭据引用的环境变量未设置: …”。
+2. **secret 绝不进任何返回值/日志**：`account_list` 只报 `token_ref`（引用本身不是秘密，
+   对排查有用）与 `token_set` 布尔。实测：明文 token 在日志中出现 **0 次**。
+
+**平台形状差异**（必须抽象，不能一个头部走天下）：
+
+| 平台 | API 前缀 | 认证头 |
+|---|---|---|
+| Gitea | `<base>/api/v1` | `Authorization: token <T>` ← **不是 Bearer** |
+| GitHub | `https://api.github.com` | `Authorization: Bearer <T>` |
+| GitCode | `https://api.gitcode.com/api/v5` | `Authorization: Bearer <T>` |
+
+未知平台**必须报错**（不猜默认形状）。
+
+**凭据可用性要真验**：`account_test` 调平台的 `/user` 端点，不是只看字符串非空。
+
 ### 7.2 临时目录的凭据残留 ［风险］
 
 任务跑完删目录后，**clone 里可能仍留着 token**（remote URL 带 token 是常见做法，
@@ -429,14 +809,16 @@ commondev 的凭据是**能 push 用户所有仓库**的凭据，性质完全不
 
 ## 8. 未决问题（需用户拍板）
 
-### 8.1 「独立仓库」还是「worktree」？
+### 8.1 「独立仓库」还是「worktree」？［已解决 2026-10-13］
 
-用户原话是「每个目录下是**独立仓库**的独立分支」。
-- 独立 clone：隔离彻底、删除干净、无「同分支双挂」冲突 —— 更贴合用户描述
-- worktree：省磁盘与网络，但不能叫「独立仓库」
+**用户拍板：独立仓库（本地 clone）。** 目录 `program/<hash>-<name>`（`name` = 仓库名），
+**合入后直接删除目录**。
 
-本文建议：**mirror + 派生**（§4.3），本质仍满足「独立仓库」语义（每目录一份 checkout），
-但需要用户确认这符合预期。
+理由：worktree 的 `rm -rf` 不彻底（`.git/worktrees/` 残留，需 `prune`），
+而 `--reference` 有外部依赖（mirror 被清理即损坏）——**两者都不满足「删掉即彻底」**。
+实测与取舍见 §4.3。
+
+**代价与补偿**：失去 worktree 的「同分支不可双挂」保护 ⇒ 台账层补**唯一性闸**（§4.3）。
 
 ### 8.2 主管（主 agent）自己的模型可用性
 
@@ -534,7 +916,182 @@ grep -n "phase,omitempty" cmd/waiter/state.go              # 判据匹配的是
 
 ---
 
-## 11. 给接手者的三条提醒
+## 12. ★ 架构变更：平台知识进 skill（2026-10-15）
+
+> **本节修正本文 §4.1。** 原清单里的**平台专有工具**不再实现在插件里；
+> 其余机制（台账、工作目录、pi 会话与通道、判据与变异复核、冲突预检、
+> 凭据保存与安全执行）**保留**。
+
+### 12.1 用户拍板的边界
+
+> 「我说的是 **git 部分 skill 化**啊，其他部分还是需要插件的」
+
+| 层 | 负责 |
+|---|---|
+| **插件 commondev** | 项目台账、工作目录（mirror + 独立 clone）、pi 会话与通道、判据与变异复核、冲突预检、`enc_*` 凭据保存与安全执行 —— **40 个工具** |
+| **skill** | **各 git 托管平台的认证头、API 端点、PR 与分支保护流程** |
+
+### 12.2 移出插件的部分（10 个工具 → skill）
+
+| 原工具 | 现在怎么做 |
+|---|---|
+| `commondev_account_add/list/test/remove` | `enc_store` / `enc_list` + skill 里的认证头对照表 |
+| `commondev_repo_search` | `enc_shell` + `curl <API>/repos/search?q=` |
+| `commondev_pr_open` / `pr_status` | `enc_shell` + `curl -X POST .../pulls` |
+| `commondev_pr_approve` / `pr_merge` | `enc_shell` + `curl .../pulls/{n}/reviews`、`/merge` |
+| `commondev_protect_branch` | `enc_shell` + `curl -X POST .../branch_protections` |
+
+删除的文件：`platform.go`、`protection.go`、`pr_workflow.go`（约 1270 行）。
+`credentials.go` 保留但**去掉了平台语义**（`platformSpec` / `Role` / `BaseURL`）。
+
+### 12.3 为什么平台部分不该在插件里
+
+1. **每接一个托管平台都要改 Go 代码** → 重编译 → 重打包 → 重启服务。
+   而平台知识（哪个端点、什么认证头）本该和文档一起演进。
+2. **平台形状被硬编码**：`platformSpec` 的 switch 每加一家就长一截，
+   **未列出的平台直接报错**——实测 GitLab / Gitee / Bitbucket / Azure DevOps 全不支持。
+   而 agent 用 `curl` 本来什么平台都能打。
+3. **工具面膨胀**：50 个工具让模型选择成本上升。
+
+⇒ 平台知识进 skill（改文档**立即生效**）；插件只保留机器必须保证的机制。
+
+### 12.4 保留的纪律（没变）
+
+- 凭据不进 `config.db`（0644 全局可读）、不进 remote URL、不进命令行参数；
+- **没有「取回明文」的接口**：只能被 `@{别名}` 引用（S1）；
+- 变量库不自动淘汰，泄漏控制靠主动删除；
+- `enc_shell` 三条保障：明文不进 argv（stdin）、输出脱敏、超时；
+- 「不要把测试通过当作改对了」——复核必须含**变异**阶段（§4.5 主张仍成立）。
+
+### 12.5 判据（钉住不回退）
+
+`alignment_test.go` 新增两条：
+
+- `TestPlatformToolsAreNotInPlugin` —— 那 10 个平台工具不得再注册；
+- `TestNoPlatformSpecificCodeInPlugin` —— 源码里不得再出现 `platformSpec` /
+  `AuthHeader:` / `DefaultAPI` / `RoleExecutor` 等平台专有符号
+  （**排除注释**：说明"已移出"是允许的）。
+
+**为何要判据而不只是文档**：文档说了还会有人（包括将来的我）图省事加回去，
+而那种回退**功能上看起来完全正常** —— 只是把可移植性换成了硬编码。
+
+---
+
+## 13. 功能完备性核对（2026-10-15）
+
+逐章节对照设计文档核对实现，**19/19 通过**（脚本化核对，非人工目测）：
+
+| 设计条目 | 实现 |
+|---|---|
+| §4.1 工具面（扣除已移出的 10 个平台工具） | ✅ 40 个工具 |
+| §4.2 台账 schema（Project/Branch） | ✅ |
+| §4.3 mirror + 本地 clone（硬链接） | ✅ |
+| §4.3 ⚠ 唯一性闸（同名未结分支拒绝） | ✅ |
+| §4.3 目录名 `<hash>-<name>` | ✅ |
+| §4.4 可并行（每分支独立 clone） | ✅ |
+| §4.5 复核两步（正向 + 变异） | ✅ |
+| §4.7 `base_sha` 首次捕获 | ✅ |
+| §4.7 `merge-tree` 预检（不碰工作区） | ✅ |
+| §4.7 `Skipped` 与 `Mergeable` 分开 | ✅ |
+| §4.8 三档 verdict | ✅ |
+| §4.8 变异必须唯一匹配 | ✅ |
+| §7.2 凭据残留检查 | ✅ |
+| §7.2 remote 不带凭据 | ✅ |
+| 续篇 §2.2 先 session 后通道 | ✅ |
+| 续篇 §2.5 投递走内核 output 门 | ✅ |
+| 续篇 §3.6.3 直接写 pi 配置文件 | ✅ |
+| 续篇 §3.6.5 不静默回退宿主凭据 | ✅ |
+| S1 无「取回明文」接口 | ✅ |
+
+### 13.1 LLM 源端到端（本轮新增）
+
+新增 `llmsource_e2e_test.go`（5 条判据），把「内核源 → 插件导入 → pi 配置 →
+**真实调用成功**」整链收口：
+
+| 判据 | 层次 | 验证 |
+|---|---|---|
+| `TestLLMSourceImportProducesValidPiConfig` | 纯逻辑 | models.json 形状、`openai`→`openai-completions` 映射、contextWindow 透传、0600 权限、defaultProvider |
+| `TestLLMSourceImportRejectsUnknownAdapter` | 纯逻辑 | 未知 adapter **必须报错**（猜默认会让 pi 用错协议，现象是「模型不回复」）|
+| `TestLLMSourceImportFailsWithoutKernelSources` | 纯逻辑 | 无源时报错，不生成空配置 |
+| `TestLLMSourceImportFromRealKernelConfig` | **真机** | 读生产 `config.db` 的真实字段形态，3 个源全部导入成功 |
+| `TestLLMSourceRoundTripAgainstRealEndpoint` | **真机** | 从**导入产物**（而非测试变量）读回地址与 key，真实 HTTP 调用成功 |
+
+**真机结果**：
+
+```
+✅ 真实内核配置导入成功：3 个源，默认=llmsproxy
+✅ 端到端通过：内核源 → 插件导入 → 用磁盘配置真实调用成功
+```
+
+**为何必须端到端**：导入逻辑正确 ≠ pi 能用。中间三层各自可能出错
+（字段映射 / adapter→api 名 / 默认源写入），任何一层错了现象都是
+「pi 起不来 / No API key found」，而单元判据全绿。
+
+**变异验证（4 条全咬住）**：
+
+| 变异 | 结果 |
+|---|---|
+| adapter 映射成错的 api 名 | ❌ 报红（纯逻辑判据）|
+| base_url 不写入 | ❌ 报红 |
+| **api_key 不写 auth.json** | ❌ **真机 e2e 报红**（真实调用失败）|
+| 未知 adapter 猜默认值 | ❌ 报红 |
+
+复现命令：
+
+```bash
+cd third_party/homeagent-sdk/example/commondev
+K=$(sqlite3 /home/newqqagent/config.db "select value from config where key='core.llm.api_key';")
+HA_E2E_LLM=1 HA_E2E_API_KEY="$K" HA_E2E_REAL_DB=/home/newqqagent/config.db \
+  go test -count=1 ./...
+```
+
+### 13.2 判据与变异总览
+
+| | 数量 |
+|---|---|
+| 判据 | **62** |
+| 变异（累计验证咬住） | 30+ |
+| 工具 | 40 |
+| 非测试代码行数 | 5437 |
+
+---
+
+## 14. 历史实现审计（2026-10-15 早）
+
+本节是对原始设计清单的逐条回读结果；不要仅依据文档顶部的历史状态判断实现状态。
+
+### 14.1 已实现并有测试/实测
+
+| 设计项 | 实现/证据 |
+|---|---|
+| 刀 0/1：项目、分支、独立 clone、sidecar、通道、续投 | `plugin.go` / `sidecar.go`；branch/session/channel 端到端测试 |
+| 刀 2：双角色凭据、分支保护、审批、合并 | `protection.go`；真实 Gitea 1.24.2 矩阵 + 变异 |
+| 刀 3：`base_sha`、`merge-tree --write-tree`、Skipped 分离 | `conflict.go`；真实 git 仓库 + 变异 |
+| 刀 4：判据、正向、变异、三档 verdict、后台复核 | `criteria.go`；真实 `go test` 端到端 + 机制元变异 |
+| 原 §4.1 工具面 | 项目/分支/工作目录/agent/PR/判据/pi 配置/MCP/仓库搜索工具均已注册 |
+| Secret Firewall 与配置加密 | `internal/security`、`internal/config`；race 与三层回归 |
+| E-4 生产密钥注入 | `deploy/homeagent.service` 的 `LoadCredential`；真实 systemd 262 实测 tmpfs/0400/不进 environ |
+
+### 14.2 设计文字与实现的取舍
+
+- `commondev_agent_send`：续篇 §2.5 已明确废除；发送继续走内核原生 `output_send__...`，不重复造工具。
+- `commondev_test_run` / `commondev_test_mutate`：早期清单的两个单阶段入口已保留；`commondev_review_submit` 是两阶段一键入口。
+- `commondev_pi_plugin_*` 与细化稿的 `commondev_pi_package_*`：两套命名均注册为兼容别名；底层调用同一套 `pi install/remove/list/update`。
+- `commondev_project_open`：续篇早期别名已补，底层复用 `project_add`。
+- skill 双投不是运行时插件行为：主管侧 skill 由 HomeAgent 发布，执行侧 skill 由工作目录/发布包注入；插件不擅自把代码写进用户全局目录。
+
+### 14.3 仍明确未实现的设计项
+
+这些不是本次审计漏掉的隐藏功能，而是设计文档已标出的未决/后续项：
+
+- 远端 SSH runtime（当前仅 local）；
+- 预置测试模板库（当前完成的是判据/变异机制，不是 unit/interface/stress/build 模板集合）；
+- U4 `steer` 语义降级：当前接受 pi 的插话语义，不伪称为内核式抢占恢复；
+- U8 的“随包锁定独立 pi 二进制”仍取决于发布包；当前 agent_up 会回显 sidecar 可解析到的 `pi_version`，无法解析时显式警告，不编造版本。
+
+审计结论：**原始设计的核心机制已实现，但不能宣称所有后续项全部完成。** 本节列出的项目是剩余真实边界。
+
+
 
 1. **不要把「测试通过」当作「改对了」**。本文 §4.5 的变异验证不是可选项，
    它是这套机制唯一能防住假绿的手段。本仓当天因此浪费过一整轮排查。
diff --git a/docs/zh/kernel-modularization-design.md b/docs/zh/kernel-modularization-design.md
new file mode 100644
index 00000000..4be74aa7
--- /dev/null
+++ b/docs/zh/kernel-modularization-design.md
@@ -0,0 +1,1339 @@
+# 内核模块化与并行装配设计
+
+> **状态**：设计已定（2026-10-16），实现分阶段推进。
+> 本文是**唯一的装配架构权威**。任何新增内核模块或插件都必须遵循本文的依赖声明契约。
+>
+> 关联文档：`kernel-secret-firewall-design.md`（安全模块的装配点约束是本文 §2.3 的实例）、
+> `resident-subagent-design.md`（inputch 共享总线是 §5 的既有先例）。
+
+## 1. 问题陈述
+
+### 1.1 现状（实测数据）
+
+| 指标 | 实测值 |
+|---|---|
+| `main()` 行数 | **277 行** |
+| 内核模块（`init*` 调用） | **12 个** |
+| `main()` 里"必须早于 / 必须在之前"注释 | **11 处** |
+| 外部插件 | **42 个** |
+| 内置插件 | **21 个** |
+| 生产启动耗时 | **13 秒**（12:50:21 → 12:50:34） |
+
+### 1.2 两个具体的病
+
+**病 A：装配顺序只写在注释里，错了不报错——静默降级**
+
+现场故障（2026-10-16）：安全模块装配晚于 `cfgReg.SetLLMSnapshotFile()`，
+而后者启动即读 `core.llm.*`（需主密钥解密）。后果链：
+
+```
+密钥未装配 → Dump 解密失败（只打一行 warning）→ key 变成空串
+→ initLLMProviders 拿到空 key → 所有 LLM 调用 401 invalid api key
+```
+
+症状极具误导性：401 看起来像"key 配错了"，实际是**纯粹的启动顺序问题**。
+查 key 值、改 key、重配 provider **全部无效**。
+
+> 这个缺陷**没有任何机器校验会拦它**——11 处"必须早于"都是人写的注释。
+
+**病 B：串行等待被放大**
+
+现场实测（同一次启动）：
+
+```
+12:50:24  clawhubadapter 启动
+12:50:24→29  bilibili pysidecar ping timeout (5s)   ← 阻塞
+12:50:29→34  gaode    pysidecar ping timeout (5s)   ← 阻塞
+12:50:34     剩下 20+ 个插件才开始加载
+```
+
+- 两个 5 秒**完全串行**
+- 而且卡住了**后面 20+ 个插件的加载**（`registry.go:415` 的加载循环是串行的）
+
+⇒ 13 秒启动里 **10 秒（77%）是串行等待**。
+
+### 1.3 为什么现在必须解决
+
+后续内核模块**必然膨胀**。当前形态下每加一个模块都要：
+1. 想清楚它是第几个装配（11 处注释不够，因为依赖是隐式的）
+2. 改 `main()` 的调用位置
+3. 如果顺序错了 → **静默出错**，症状出现在很远的地方
+
+**这是"添加新模块的成本"，而它随模块数增长而非线性增长。**
+
+## 2. 核心设计：声明式依赖 + 拓扑排序 + 分阶段并行
+
+### 2.1 两类模块，两套策略（★ 必须区分）
+
+| | **内核模块** | **外部插件** |
+|---|---|---|
+| 数量 | 12 个 | 42 个 |
+| 形态 | 编译进 homed，同进程 | `plugin.bin` 独立进程 / `.so` |
+| 依赖形态 | **真实数据流**（要拿前面的返回值） | **相互几乎无依赖** |
+| 主要病 | 顺序错 → 静默降级（病 A） | 串行等待被放大（病 B） |
+| 策略 | **拓扑排序 + 启动断言**（保持同步） | **有界并发**（Worker Pool） |
+| 并行收益 | 小（实测大部分 <100ms） | **大（实测 10s / 13s）** |
+
+> **★ 不得混淆**：给内核模块加并行是"用异步换不确定"，收益小而风险大；
+> 给插件加并行是"把独立的等待重叠"，收益大且语义清晰。
+
+### 2.2 内核模块：声明式依赖
+
+```go
+// Module 是一个内核模块的装配契约。
+type Module interface {
+    // Name 是模块的唯一标识（用于依赖图节点）。
+    Name() string
+    // Requires 声明本模块依赖的模块名（**不是"我要在谁之后"，
+    // 而是"我需要谁已就绪"**——前者是顺序，后者是依赖）。
+    Requires() []string
+    // Provides 声明本模块提供的设施名（供他人依赖）。
+    Provides() []string
+    // Init 执行装配。ctx 提供按需取用已就绪模块的设施。
+    Init(ctx *BootCtx) error
+}
+```
+
+**关键约束**：
+
+1. **`Requires` 里出现的名字必须已被某个模块 `Provides`**，否则**拒绝启动**
+   （不是静默跳过——那正是病 A 的根源）。
+2. **循环依赖必须拒绝启动**（拓扑排序会检测到）。
+3. **`Init` 内不得调用未声明的依赖**（`BootCtx` 只暴露已就绪的设施，
+   取未声明的会返回错误而不是 nil）。
+
+#### 为什么不用总线 / 事件驱动
+
+已评估过 `callbus + call/reply 缓存 + syncbus 状态位` 的方案，结论是**不采用**：
+
+| 反对理由 | 依据 |
+|---|---|
+| **数据依赖无法靠事件解决** | `initLLMProviders(cfg, luaVM, key)` 要的是**返回值**（一个 `*VM`、一份 `cfg`）。事件到了还是得持有那个对象 ⇒ 顺序问题原地不动 |
+| **同步返回值退化成异步** | 每个调用点都要变状态机，或加等待（= 又回到顺序问题） |
+| **丢失可追溯性** | 现在 `panic` 有完整 Go 栈；缓存式调用只有"某条 call 没被处理" |
+| **把故障变隐蔽** | 病 A 的根因是"顺序错不报错"。总线把它从"调用顺序"换成"订阅时序"，**更难查**（现有 `events.Bus` 同步、**无回放** ⇒ 订阅前发布 = 永久丢失） |
+| **安全模块本身是反例** | 它用"全局单例 + `Global()` 惰性 nil"而非总线，**照样踩了顺序问题**（`ToConfig()` 在它之前读密文时 `Global()` 返回 nil → 静默空 key） |
+
+> **结论**：总线适合**运行期的松耦合通知**（如 `events.Bus`、inputch 共享总线，
+> 二者已有且有效），但**不适合启动期的确定性装配**。启动期要的是拓扑保证，不是异步通知。
+
+### 2.3 装配调度：依赖图 + BFS 分层并行
+
+#### 2.3.1 核心洞察（用户指出）
+
+> 依赖图是一个由依赖关系生成的图，通过 BFS 遍历：**当前遍历到的节点初始化后，
+> 下一层 BFS 就可以安全地并行初始化** —— 这是依赖图的性质。
+
+这句话是整个调度器的**正确性来源**，值得展开说明为何成立：
+
+设依赖图 `G`，边 `a → b` 表示 **b 依赖 a**（a 必须先就绪）。
+BFS 从**入度为 0** 的节点（无依赖者）开始，逐层推进：
+
+```
+第 0 层 = { v | v 无未满足的前驱 }
+第 k 层的每个节点 v，其全部前驱都在第 <k 层
+  ⇒ 只要第 <k 层全部**已就绪**，第 k 层的任意子集都可以并发 Init
+```
+
+**关键性质**：第 k 层内部**两两之间无边**（否则其中一个会在第 ≥k+1 层）。
+所以你不需要为"同层能否并行"做任何额外判断 —— 分层本身已经保证了这一点。
+
+这就是为什么用 BFS 而不是"一次拓扑排序 + 逐个执行"：
+拓扑序给的是**一个**合法顺序（全串行），而 BFS 分层给的是**最大化并行的顺序集合**。
+
+#### 2.3.2 算法（伪代码）
+
+```go
+// 已被声明的设施名（Provides 的并集，随就绪增长）
+ready := map[string]bool{}
+// 未就绪节点：名字 -> 模块
+pending := allModules
+
+for len(pending) > 0 {
+    // ① 取当前所有"依赖已全部就绪"的节点
+    layer := []Module{}
+    for name, m := range pending {
+        if allSatisfied(m.Requires(), ready) {
+            layer = append(layer, m)
+        }
+    }
+
+    // ② 一个都取不到 ⇒ 有环（或依赖了不存在的设施）⇒ **拒绝启动**
+    if len(layer) == 0 {
+        return UnresolvableError{remaining: pending, declared: ready}
+    }
+
+    // ③ 同层并行 Init（层内无边 ⇒ 安全）
+    for _, m := range layer {          // ← §2.3.4 的有界并发：不是无限制并行
+        go func(m Module) {
+            err := m.Init(ctx)          // 失败必须收集，不能丢
+            onDone(m, err)
+        }(m)
+    }
+    waitAll(layer)
+
+    // ④ 层完成 ⇒ 提交它们提供的设施，进入下一层
+    for _, m := range layer { ready[m.Name()] = true }
+    for _, m := range layer { delete(pending, m.Name()) }
+}
+```
+
+#### 2.3.3 三类失败必须**响亮拒绝启动**
+
+| 失败 | 何时被发现 | 为何不能容忍 |
+|---|---|---|
+| **依赖了不存在的设施** | 建图时 | 拼错名字或忘声明 `Provides` —— 静默跳过就是病 A |
+| **循环依赖** | ② 取不到节点时 | 无解；必须报出**环上的成员**（否则无法修） |
+| **`Init` 返回错误** | ③ 层执行中 | 模块起不来；带着半初始化状态继续 = 后面的静默错误 |
+
+**错误信息必须含足够定位信息**：
+
+- 缺依赖：谁、缺谁、**已声明了哪些**（便于发现拼写差异）
+- 循环：**环上的节点列表**（不只是"有环"）
+- Init 失败：模块名 + 原始错误（不包装掉）
+
+#### 2.3.4 层内并行必须**有界**
+
+同层无边保证**安全**，但不保证**无代价**：
+
+- 42 个插件同时 spawn 会造成内存/CPU 尖峰
+  （每个 ~11MB `plugin.bin` 加载 + 握手 + `Start()` 里的重型初始化）
+- 所以层内用 **Worker Pool**，默认并发上限 4（待实测内存尖峰后定）
+
+**★ 注意**：有界并发**不削弱正确性** —— 同层节点两两无边，
+无论以什么顺序完成，下一层的就绪条件都相同。并发度只影响**速度**，不影响**顺序**。
+这是本设计相对"总线异步"的根本优势：**并行是可调参数，而顺序由依赖图保证**。
+
+#### 2.3.5 与"Phase"的关系
+
+§2.3.1 的算法是**通用调度器**；下面三个阶段是它的**输入分组**
+（即：哪些模块进同一张依赖图）：
+
+```
+第 0 组（前置，**单独一张图，串行**）
+  ├─ 配置库打开 + 种子
+  ├─ ★ 安全模块装配（必须早于任何读 core.llm.* 的操作）
+  └─ cfg 快照（ToConfig）+ LLM 快照文件
+  ↑ 这三步的顺序由**副作用**决定，不是由依赖声明决定
+    ⇒ **不进入通用调度器**，保持显式串行（见下）
+
+第 1 组（内核模块，通用调度器）
+  └─ 12 个模块 → 依赖图 → BFS 分层 → 同层有界并行
+
+第 2 组（外部插件，通用调度器）
+  └─ 42 个插件 → 依赖图（当前几乎无边 ⇒ 单层全并行）
+
+第 3 组（就绪断言）
+  └─ 关键依赖缺失 → 拒绝启动
+```
+
+**为何第 0 组不进入调度器**（重要，且我实测踩过）：
+
+它的顺序由**副作用**决定（"密钥必须先装上，否则读不了密文"），
+而不是由"我需要谁的返回值"决定。这类约束**用依赖图表达不了**：
+`SetLLMSnapshotFile` 依赖的不是"安全模块提供的某个设施"，
+而是"**读密文这个动作**发生前密钥已就绪"。
+
+> 实测教训（2026-10-16）：这一组顺序错了，症状是 LLM 全 401，
+> 而看起来像"key 配错了"。修法只能是**显式串行 + 结构性断言**
+> （`cmd/homed/bootstrap_order_test.go`），不能靠依赖图。
+
+**所以本设计不追求"一切都进调度器"** —— 强行把副作用顺序塞进依赖声明，
+只会得到一个"看起来统一、实际靠隐式约定"的系统（= 病 A 换个形态）。
+边界要划清：**数据依赖进图，副作用顺序显式串行 + 断言**。
+
+### 2.4 外部插件：有界并发 + 自行声明超时
+
+#### 2.4.1 有界并发
+
+`registry.go:415` 当前是串行 `loadOne`。改为 Worker Pool：
+
+- **默认并发上限 4**（可配置）：42 个 proc 插件同时 spawn 会造成内存/CPU 尖峰
+  （每个 ~11MB `plugin.bin` 加载 + 握手 + `Start()` 里可能的重型初始化）
+- **分池**：按 manifest 声明的"重/轻"分池，重插件单独串行或低并发
+- **失败隔离**：单个插件失败不得影响同批其他插件（现在串行也有这个性质，并行要显式保证）
+
+#### 2.4.2 ★ 插件自行声明超时（用户要求）
+
+**动机**：超时值现在由**内核猜**（`defaultHandshakeTimeout = 10s`）。实测后果：
+
+- 轻插件用不到 10s（浪费）
+- 重插件 10s 可能不够 ⇒ 它"失败"，且失败得很晚（白等 10 秒才报错）
+- 现场两个 pysidecar 各 5 秒硬编码超时（`clawhubadapter/sidecar.go:215`）
+
+**只有插件自己知道"我大概要多久"**，所以这个值应由它声明。
+
+**契约（外部插件，写进 `plugin.json`）**：
+
+```jsonc
+{
+  "name": "my-plugin",
+  "entry": "plugin.bin",
+  // 本插件自行声明的建链（握手）超时，单位秒。
+  // 省略或 <=0 ⇒ 用内核默认值。
+  "handshake_timeout_sec": 30
+}
+```
+
+**★ 两层超时必须分清**（这是本设计的关键区分）：
+
+| 层级 | 位置 | 谁来声明 | 说明 |
+|---|---|---|---|
+| **L1：内核 ↔ 插件建链** | `proc/process.go` `HandshakeTimeout` | **外部插件** `plugin.json` | 内核能干预的边界 |
+| **L2：插件内部的子资源等待** | 插件自己的代码（如 `clawhubadapter/sidecar.go:215`） | **插件自己**（内置插件走自己的 `ConfigDef`） | 不属于 SDK 契约，是插件实现细节 |
+
+> **为什么 L2 不放进 SDK**：内核不知道也不该知道插件内部在等什么
+> （Python 子进程？JVM？大模型加载？）。把它塞进 SDK 会让内核承担
+> 它无法验证的语义。内置插件（编译进 homed）**本来就能读自己的 `ConfigDef`**，
+> 走那条路即可；外部插件在自己的 `Start()` 里处理。
+
+### 2.5 依赖图的制品化（编译期产出 + 二进制 + hash）
+
+#### 2.5.1 为何要制品化（不只是"省一次计算"）
+
+依赖图可以在运行期从声明重建（零制品）。制品化的真正价值是**可审计性**：
+
+| 收益 | 说明 |
+|---|---|
+| **不运行就能看启动计划** | 运维可在部署前预检"这套模块会按什么顺序起来" |
+| **★ 启动顺序变化在评审时可见** | 图文件的 diff 进 PR —— 这是当前**最大的盲区**（现在顺序变化只在代码的调用位置里） |
+| **部署前可校验** | 不必"起一次才知道顺序对不对" |
+
+#### 2.5.2 ★ 必须补强的一点：hash 要绑定二进制，不只是自校验
+
+**只做"图文件自校验"会漏掉最危险的一种情况**：
+
+| 情况 | 图完整性 | 会被发现吗 |
+|---|---|---|
+| 图文件损坏（磁盘错/传输截断） | 坏 | ✅ 自校验能拦 |
+| **图与二进制不匹配**（改了 `Requires` 但图没重生成） | **完好** | ❌ **漏掉** |
+
+第二种更危险：图文件自身完好、hash 也对，但它描述的是**旧代码** ⇒
+按旧图调度 ⇒ 顺序错 ⇒ **正是本文要消灭的病 A**。
+
+**修法**：把图的 hash **绑定到二进制**（构建期用 `-ldflags` 注入）：
+
+```
+构建时：
+  ① 产出 depgraph.bin + 计算其 hash H
+  ② go build -ldflags "-X ...kernelboot.embeddedGraphHash=H"
+
+启动时：
+  ③ 读磁盘上的 depgraph.bin，计算 hash H'
+  ④ H' != embeddedGraphHash  ⇒ **拒绝启动**（不猜哪边对）
+```
+
+这样两类不一致都被拦住：图坏了（H' 变了）、图与代码不匹配（H ≠ 内嵌值）。
+
+> **★ 为何"不猜哪边对"**：图的作者是构建流程，二进制的作者也是它。
+> 两者不一致意味着**制品装配出了问题**，此时任何一边都不可信。
+> 猜一个是拿启动正确性赌运气。
+
+#### 2.5.3 二进制格式（精密二进制，不用 JSON）
+
+格式要求与 `internal/plugin/proc/shmcodec.go`（共享段）同一套理由：
+**紧凑、无歧义、解析失败可检测**。
+
+```
+┌─────────────────────────────────────────────┐
+│ magic    8B   "HGDEPS01"                    │  ← 版本随格式破坏性变更而变
+├─────────────────────────────────────────────┤
+│ version  4B   uint32 格式版本             │
+├─────────────────────────────────────────────┤
+│ modCount 4B   uint32 模块数                 │
+├─────────────────────────────────────────────┤
+│ 模块表（每项）：                           │
+│   nameLen   2B  uint16                      │
+│   name      NB  UTF-8                       │
+│   provides  NB  设施名（逗号分隔，已排序）  │  ← 排序保证 hash 稳定
+│   requires  NB  同上                        │
+├─────────────────────────────────────────────┤
+│ hash     32B  SHA-256（前面所有字节）      │  ← 自校验：防截断/位翻转
+└─────────────────────────────────────────────┘
+```
+
+**为何字段要排序**：同一份声明必须产出**逐字节相同**的文件，
+否则 hash 在无害改动（代码顺序调换）后也会变，导致"每次都说不一致"而失去意义。
+
+**为何自校验 hash 还要加内嵌 hash**：自校验只证明"文件没坏"，
+内嵌 hash 才证明"文件与这份二进制配套"（§2.5.2）。
+
+#### 2.5.4 文件位置与缺失时的行为
+
+- **位置**：与内核二进制**同目录**（满足"随核心分发"）：`<homed 所在目录>/depgraph.bin`
+- **缺失时**：
+  - **开发/单测环境**（`go run` / `go test`）：缺失 ⇒ **运行期从声明重建**
+    （否则每次改代码都要跑生成器，且测试无法独立运行）
+  - **生产环境**：缺失 ⇒ **拒绝启动**（不静默回退到运行期重建）
+
+**如何区分两者**：用内嵌 hash 是否为空作为判据 ——
+构建脚本注入了 hash ⇒ 生产（缺失即错）；未注入 ⇒ 开发（允许重建）。
+
+> 为何生产不许回退：运行期重建会让"图与代码不匹配"这个风险**变成静默容忍**，
+> 而那正是本文 §2.5.2 要拦的东西。
+
+#### 2.5.5 工具与构建接线（已实现）
+
+**生成器**：`cmd/homed-depgraph`
+
+| 参数 | 作用 |
+|---|---|
+| `-from <json>` | 从声明清单读取（过渡期形态；模块接口接入后改为 import 登记包） |
+| `-out <path>` | 产出二进制制品（默认 `<exe目录>/depgraph.bin`） |
+| `-print` | 只打印**分层计划**（运维/评审用，不落盘） |
+| `-digest` | 只输出 digest（供 `-ldflags` 注入） |
+
+**★ 拒绝产出空图**：没有 `-from` 时**报错退出**，而不是产出空图。
+理由：空图会让 homed 认为"没有依赖" ⇒ 按一个**错误的计划**启动 ——
+那比直接报错危险得多。
+
+**★ 产出前先 `Build()` 一次**：能在编译期发现的依赖错误（缺依赖 / 环 / 重名）
+不留到运行期。这是制品化的额外收益。
+
+**Makefile 接线**（`make build`）：
+
+```make
+GRAPH_HASH=""; \
+if [ -f "$(GRAPH_DECL)" ]; then \
+    构建生成器 && 取 digest && 打印计划 && 落盘图 && 回显 digest ; \
+fi ; \
+CGO_ENABLED=1 go build ... \
+    -ldflags '$(LDFLAGS) -X ...kernelboot.EmbeddedGraphHash=$$GRAPH_HASH' \
+    -o build/homed ./cmd/homed/
+```
+
+⚠ **必须写成一条 shell 命令**（`\` 续行）：Make 的每行 recipe 是**独立 shell**，
+普通变量跨行不保留（第一版就踩了这个，踩法是"digest 算出来了但注入是空"）。
+
+#### 2.5.6 过渡期说明（诚实记录）
+
+现有 12 个内核模块还是 `init*` 函数形态（**不是** `kernelboot.Module` 接口），
+所以生成器目前靠 `deploy/depgraph-decls.json` 这份**手工维护的声明清单**工作。
+
+**这本身就是一个过渡态风险**：清单是手写的 ⇒ 可能与真实代码不符。
+缓解：
+
+1. 清单文件进 PR ⇒ 与代码一起被评审
+2. §2.5.2 的内嵌 hash 仍然生效（图与二进制的配套被校验）
+3. **Step 4 后续增量**：把 12 个 `init*` 迁成 `Module`，声明清单即废止，
+   生成器改为 import 模块登记包（那时"清单与代码不符"**结构上不可能**）
+
+> **★ 当前已产出的分层结果（实测）**：
+>
+> ```
+> 第 0 层（1 个）: config
+> 第 1 层（7 个，可并行）: docmem, lua, memory, multimodal, security, textmem, tracker
+> 第 2 层（3 个，可并行）: knowledge, llm, stagehost
+> 第 3 层（1 个）: agent
+> ```
+>
+> 对比现在硬编码的 **12 步串行** —— 这是本设计给出的**并行度提升的直接证据**。
+
+## 2.6 syncbus：插件与内核的状态同步（插件调度的唯一驱动）
+
+> 本节是用户设计意图的完整落实记录。**先有本节，后有实现**
+> （用户要求："先完整落实计划与文档按计划推进"）。
+
+### 2.6.1 要解决的问题
+
+现状是**一刀切**（实测 `cmd/homed/main.go:291`）：
+
+```
+12 个 init* 全部做完 ──────────────► loadPlugins() 一次性加载全部插件
+```
+
+后果：**不需要内核全部就绪的插件，被无谓地卡在最慢的一环之后**。
+一个只读本地文件的插件，也要等多模态空间（含 ONNX 加载）、知识库建索引
+全部完成才能起来。
+
+而内核那 12 步本身有**明确的先后关系**（§2.3 已算出 4 层），
+所以"阶段"这个概念是天然存在的 —— 只是现在没有对外发布。
+
+### 2.6.2 syncbus 是什么
+
+**一份内核就绪状态的可读快照，只有一个写者。**
+
+```go
+// 内核侧（唯一写者）
+type SyncBus struct {
+    mu        sync.RWMutex
+    ready     map[string]bool   // 设施名 -> 是否就绪
+    completed []string          // 按就绪顺序记录（可审计/可调试）
+}
+
+func (b *SyncBus) MarkReady(facility string)     // ★ 只有内核能调
+func (b *SyncBus) IsReady(facility string) bool  // 读取
+func (b *SyncBus) Snapshot() map[string]bool     // 读取（只读副本）
+```
+
+**★ 写入点就是 BFS 的层边界**（这是本设计最自然的一处）：
+
+`Run` 已经知道"第 k 层完成了哪些模块"（`OnLayerDone` 回调），
+而每个模块的 `Provides` 就是它贡献的设施名。所以：
+
+```
+第 0 层完成（config）        ⇒ syncbus: config 就绪
+第 1 层完成（memory,lua,...） ⇒ syncbus: memory,lua,keystore,... 就绪
+第 2 层完成（llm,...）        ⇒ syncbus: llm 就绪
+```
+
+**同步点是层边界，而不是每个模块完成时** —— 因为层内是**并发**执行的，
+若在层内逐个标记就绪，就绪顺序会**不确定**，而判据要求可复现。
+
+### 2.6.3 权限约束：插件管理器对 syncbus **只读**
+
+**这不是习惯，是权限设计。** 理由：
+
+> 若插件管理器能写 syncbus，它就能**谎报内核状态**，
+> 从而让插件在自己依赖的东西还不存在时启动 —— 那正是病 A（静默顺序错）。
+
+所以类型层面就要分离：
+
+```go
+// 内核持有完整能力
+type SyncBus struct { /* 含 MarkReady */ }
+
+// 插件管理器只拿到只读接口（编译期就不可能写）
+type SyncState interface {
+    IsReady(facility string) bool
+    Snapshot() map[string]bool
+    // 注意：**没有** MarkReady/Reset —— 想写也写不了
+}
+```
+
+**★ 用接口隔离而非"约定不要写"**：约定会被后人无意破坏，
+而"接口上没有这个方法"是编译期保证。这与本仓
+`Get[T]` 泛型取用（类型错=编译不过）是同一个思路。
+
+### 2.6.4 插件调度：声明时序 ⇒ 依赖齐了就拉起
+
+**插件在自己 manifest 里声明它需要哪些设施**（与 `handshake_timeout_sec` 同一套路：
+插件自己声明，内核不猜）：
+
+```json
+{
+  "name": "myplugin",
+  "requires_facilities": ["config", "llm"]
+}
+```
+
+插件管理器的调度逻辑（**被初始化后**执行）：
+
+```
+1. 遍历所有已发现插件
+2. 对每个插件 P：
+     若 P 声明了 requires_facilities 且**全部就绪** ⇒ 拉起 P
+     若 P 声明了 requires_facilities 但**未全就绪** ⇒ 挂起，等 syncbus 更新
+     若 P **未声明** ⇒ 等内核**完全**初始化完成后拉起  ← ★ 默认路径
+3. 内核每完成一层 ⇒ 回调 ⇒ 重新检查挂起队列
+```
+
+### 2.6.5 ★★ 兼容性：不声明 ⇒ 现行为，**存量插件零改动**
+
+| 插件声明 | 启动时机 | 与现状对比 |
+|---|---|---|
+| **不声明**（默认） | 内核**完全**初始化完成后 | **完全一致** ← 存量 42 个插件走这条 |
+| 声明 `requires_facilities` | 依赖的设施全就绪时 | 新能力（尽早启动） |
+
+**这是本设计的硬约束**（与 §3 其他硬约束同级）：
+
+> 未声明 ⇒ 行为逐字不变。存量插件**一个都不用改**。
+
+为什么这条不能妥协：42 个存量插件里任何一个若因本设计而改变启动时机，
+就可能在不该动的时候动（例如某插件假设"我 Start 时 llm 一定已就绪"）。
+**静默改变启动时机 = 静默引入竞态**。
+
+### 2.6.6 「伴随启动」与「不伴随启动」
+
+用户要求的两分类：
+
+| 类别 | 语义 | 实现 |
+|---|---|---|
+| **伴随启动** | 依赖齐了**自动**拉起（跟随内核时序） | 声明 `requires_facilities` |
+| **不伴随启动** | **不**自动拉起，等显式指令 | 声明 `auto_start: false` |
+
+**不伴随 = 被管理而非被启动**：它的生命周期由 agent 经
+`plugin_enable` / `plugin_disable` 工具控制（见 §2.6.7）。
+
+这与现有的 `disabled_plugins` 配置（`registry.go:1046 DisablePlugin`）
+是**互补**关系：
+- `disabled_plugins` = **运维层面**的持久禁用（配置里记住）
+- `auto_start: false` = **时序层面**的不自动拉起（仍可被显式启用）
+
+### 2.6.7 插件生命周期模型：运行态与持久态**必须分离**
+
+> ★ 本节修正了本设计早期的一处**误判**。第一版写的是
+> "内核能力齐全，只缺两个 agent 工具" —— 实测证明那是错的。
+
+#### 2.6.7.1 误判及其纠正
+
+早期判断：`Registry.DisablePlugin` / `EnablePlugin` 已实现且是真停真起，
+所以只要把这两个 API 包成 agent 工具即可。
+
+**实测发现的问题（用户指出："只有 reload"）**：
+
+```go
+EnablePlugin(name) → Enable(name) → cfgReg.RemoveDisabledPlugin(name)  // ★ 改了持久状态
+```
+
+也就是说：现有 API 里**没有任何一个能"只改变运行态"**。它们全都是
+"改运行态 **顺带**改持久态"。这不是"缺两个工具"，而是**语义缺失**。
+
+#### 2.6.7.2 正确的模型：插件 = agent 的应用程序
+
+用户给的心智模型是关键：
+
+> 插件就是 agent 的应用程序。这些应用程序有**开机自启**，
+> 有**开机不自启**。agent 应能主动**启动**、**关闭**它们。
+
+按"应用程序"模型，**四个正交概念**：
+
+| 概念 | 语义 | 是否持久 | 类比 |
+|---|---|---|---|
+| **自启**（auto_start） | 开机时是否自动拉起 | ✓ 写 manifest | 开机启动项 |
+| **启用/禁用** | 是否**允许**加载 | ✓ 写配置 | 程序是否被系统禁止运行 |
+| **启动**（start） | **现在**拉起 | ✗ 运行态 | 双击打开 |
+| **关闭**（stop） | **现在**停掉 | ✗ 运行态 | 关闭窗口（≠ 卸载、≠ 禁止自启） |
+
+**现状缺失的正是后两个**（运行态）。后果很具体：
+
+- agent 想"临时关掉某插件看现象" ⇒ 只能调 `DisablePlugin` ⇒
+  **顺带写了持久禁用** ⇒ 下次开机它也不自启了 —— 用户会发现
+  "我只是关了一下，怎么以后都不启动了"
+- agent 想"把刚才关的插件开回来" ⇒ `EnablePlugin` ⇒ 清了禁用标记 ⇒
+  **下次开机会自启** —— 但如果它本来是"不自启"的，这个改动把用户设置改了
+
+⇒ 用户的抱怨"只有 reload"精确指向这里：`plugin_restart` 是唯一
+**不改持久状态**的操作，但它是"停+用新代码起"，不是"启动/关闭"。
+
+#### 2.6.7.3 运行态门（runtime gate）与持久态门（disabled_plugins）
+
+实现上要两个**独立**的门，而不是复用同一个：
+
+```
+loadOne(name):
+    ① isDisabled(name)  ⇒ 持久禁用（disabled_plugins 配置）→ 拒绝
+    ② runtimeStopped(name) ⇒ 运行态被显式关闭 → 拒绝
+```
+
+**★ 为什么不能复用同一个门**：两者的**清除条件不同**。
+- 持久禁用由"启用"清除（用户级决定，要跨重启保留）
+- 运行态关闭由"启动"清除（会话级决定，重启后自然复位）
+
+若复用，就会出现 §2.6.7.2 那两个具体问题。
+
+**★ 重启后的语义（重要且必须明确）**：
+`runtimeStopped` **不持久** ⇒ 重启后所有插件按
+`auto_start` + `disabled_plugins` 正常决定。
+理由：运行态关闭是"这一次不想让它跑"，不是"以后都不跑"。
+若它持久，agent 关掉一个插件后再也没法让它随内核起来 —— 那正是要修的毛病。
+
+#### 2.6.7.4 agent 工具（本次要补的）
+
+| 工具 | 转调 | 改持久态？ |
+|---|---|---|
+| `plugin_start` | 新 API `StartPlugin(name)` | ✗ |
+| `plugin_stop` | 新 API `StopPlugin(name)` | ✗ |
+| `plugin_enable` | 已有 `EnablePlugin` | ✓ |
+| `plugin_disable` | 已有 `DisablePlugin` | ✓ |
+| `plugin_restart` | 已有（`ReloadOne`） | ✗ |
+
+**高危约束**（两个都要）：
+1. `plugin_stop` / `plugin_disable` 必须**拒绝作用于自身**（`pluginmgr`）
+   —— 把它停掉后 agent 就失去了插件管理能力，且**无工具能再启动它**
+   （鸡生蛋：要启动它得先用它）。这个自锁必须在内核层面拦，不能靠 agent 自觉。
+2. 同样拒绝 `webui`：停掉它 agent 与人的界面就断了。
+   （这条是"约定"而非"硬约束" —— webui 可被外部手段恢复，但仍是坏体验。）
+
+#### 2.6.7.5 SDK 兼容性：一个必须记住的**例外**
+
+本轮给公开 SDK 的 `PluginMgrAPI` 新增 3 个方法。按 SDK 的版本纪律
+（`third_party/homeagent-sdk/docs/versions.md`），"插件调用、内核实现"的
+新增属**纯追加** ⇒ 存量插件不需要改、也不需要重编。
+
+**但这次有一个例外，必须记住**：
+
+| 对象 | 是否需要动 |
+|---|---|
+| 已编译的存量插件（`.bin`） | ❌ 不需要 |
+| **存量插件的源码要重编** | ⚠️ **需要同步 hmapdev** |
+| 新插件 | ✅ 自动 |
+
+**原因**：本轮不只改了 `sdk/`（插件**调用**的一侧），还改了
+`tools/hmapdev/templates/proc_main.go.tmpl` —— 那是**生成插件代码**的模板。
+`plugin.bin` 里的 `procPluginMgr` 是**编译期**由模板生成的具体类型，
+必须满足 `PluginMgrAPI` 的**全部**方法（Go 接口精确匹配）。
+
+模板不同步 ⇒ 生成物不满足接口 ⇒ **编译失败**（不是运行期降级）。
+
+**★ 这个不对称最容易被漏的地方**：
+- 同进程插件（`.so` / 内置工厂）**直接调 SDK** ⇒ 不受影响
+- 子进程插件走 **proc 桥** ⇒ 需要 ① 桥白名单 ② hmapdev 模板 **两处**同步
+
+我当时以为"仅新增，低风险"，实测发现漏了两处（proc 桥 4 个位置 + 模板）。
+
+**判据兜底**：`internal/plugin/proc/bridge_sync_test.go` 3 条，直接从
+**SDK 源码**提取方法集，然后断言：
+1. 每个方法在 proc 能力表里有登记
+2. 每个方法在 Handle 分派 + case 体里都有
+3. hmapdev 模板的 `procPluginMgr` 实现了全部方法
+
+> **为何判据必须从 SDK 源码提取**（而非手写清单）：手写清单在"SDK 加了
+> 方法但忘了桥接"时**也不会包含新方法** ⇒ 判据照样绿，守卫形同虚设。
+> 本仓已有先例（`TestCapability_AllMethodsClassified` 初版就是这个毛病）。
+
+#### 2.6.7.6 原 §2.6.7 的实测清单（保留作对照）
+
+
+
+实测现状（`internal/plugins/pluginmgr/plugin.go`）：
+
+| 能力 | 内核 API | agent 工具 |
+|---|---|---|
+| 安装 | `plugin_install` | ✅ |
+| 列清单 | `plugin_list` | ✅ |
+| 状态 | `plugin_status` | ✅ |
+| 重启 | `plugin_restart` | ✅ |
+| 删除 | `plugin_remove` | ✅ |
+| 详情 | `plugin_info` | ✅ |
+| **禁用** | `Registry.DisablePlugin(name,by)` ✅ 已实现 | ❌ **缺工具** |
+| **启用** | `Registry.EnablePlugin(name)` ✅ 已实现 | ❌ **缺工具** |
+
+**缺口性质**：内核能力齐全且 `DisablePlugin` 是**真停**
+（调 `Stop()`、从注册表删除、走 `detachPlugin`、写 `disabled_plugins` 配置），
+`EnablePlugin` 同样已实现 —— 只是没暴露成 agent 工具。
+
+⇒ 新增 `plugin_enable` / `plugin_disable` 两个工具，直接转调已有 API。
+
+**★ 权限注意**：这两个工具让 agent 能改变系统能力边界，属**高危**。
+须：
+1. 复用现成的 plugin 工具门禁（与 `plugin_remove` 同级）
+2. `plugin_disable` 必须拒绝禁用自身同类（**不能把 pluginmgr 自己禁掉** ——
+   那会让 agent 失去插件管理能力，且无工具能再启用它）
+
+### 2.6.8 与现有机制的关系（不重复造轮子）
+
+| 现有机制 | 关系 |
+|---|---|
+| `EventBus`（`initKernelAPI` 产物） | **不同物**：EventBus 是运行期**事件流**（多播、有订阅者），syncbus 是启动期**状态快照**（一次性、无历史）。不要合并 |
+| `Plugin.Registry.Load`（`registry.go:415`） | syncbus 决定"**何时**调 Load"，不替代 Load 本身 |
+| `handshake_timeout_sec`（§2.4） | 同一套路：插件自己声明，内核不猜 |
+| `disabled_plugins` 配置 | **互补**（见 §2.6.6） |
+| BFS 层边界（§2.3） | **syncbus 的写入点**（见 §2.6.2） |
+
+### 2.6.9 判据要求（§4 的具体化）
+
+| 判据 | 必须断言 |
+|---|---|
+| 默认路径不变 | **未声明**的插件在内核**完全**完成后才起（存量兼容的硬证据） |
+| 只读隔离 | 插件管理器**拿不到**写接口（编译期：接口上没有该方法） |
+| 按声明启动 | 声明 `["config"]` 的插件在**第 0 层完成后**就起，**早于** llm |
+| 层边界可复现 | 同一份声明 ⇒ 同一就绪顺序（层内并发不得导致就绪顺序抖动） |
+| 不伴随不自动起 | `auto_start:false` 的插件即使依赖齐了也**不**自动拉起 |
+| 不谎报状态 | 只有内核能写；插件管理器写的路径**不存在** |
+
+**变异要求**：每条判据都要能被"删掉对应机制"咬住（§4.2 通用要求）。
+
+### 2.7 声明层已落地（Step 4b 第一步，2026-10-16）
+
+`internal/kernelboot/modules/declarations.go` 把 **main() 里隐含在语句顺序中的
+依赖关系**变成显式声明。实测分层结果：
+
+```
+6 层 / 17 模块，最宽层 9 个可并行（原来是 17 步严格串行）
+```
+
+#### 2.7.1 ★ cfg 的归属：修掉了"无主模块"（用户指出的问题）
+
+**实测现状**（`main.go:186`）：
+
+```go
+cfg := cfgReg.ToConfig()    // 之后 cfg 是个游离的局部变量
+```
+
+然后被**手工传给 11 个 `init*`** —— 谁需要它，就要靠人肉排到这一行之后。
+这正是"加模块必须调顺序"的病根之一。
+
+**修法**：`cfg` 归 `config` 模块持有，图上提供 `FacConfig` 设施。
+其它模块声明 `Requires: ["config"]` 即可取用。
+
+**★ 一个必须注意的细节**：`config` 在图上**无依赖**（第 0 层），
+但它有**阶段前提**——必须在 Group 0（含安全块）之后才能跑。
+
+为什么不把这写成图边（`Requires: ["crypto"]`）：
+1. Group 0 的产物（密钥/变量库）**不由任何调度模块提供** ⇒ 图会报
+   "依赖了不存在的设施"（我第一版就是这么写的，判据当场抓到）
+2. 更本质：这是**时序**要求（"读密文前先装好密钥"），不是**数据依赖**
+   （安全块并不产出 cfg 所需的数据）。§2.3.5 已说明这类不能进依赖图
+
+⇒ 正确表达是**阶段**：Group 0 串行跑完 ⇒ 才启动调度器。
+判据 `TestConfigModuleRunsAfterGroup0` 守这个前提（变异 3/3 相关全咬住）。
+
+#### 2.7.2 Group 0 的显式清单（可审计）
+
+副作用顺序项现在有**显式名字**，而不是散落在 main 的注释里：
+
+```
+platform-check → heartbeat-early → logging → data-dirs
+  → config-registry → security
+```
+
+**★ 为何列出来**：新增 Group 0 项必须同时补结构性判据
+（`cmd/homed/bootstrap_order_test.go` 断言真实相对行号）。
+判据 `TestGroup0StaysOutOfScheduler` 保证 Group 0 与可调度模块**不重叠**。
+
+#### 2.7.3 判据 + 变异（全部咬住）
+
+| 判据 | 守什么 |
+|---|---|
+| `TestDeclaredLayeringMatchesRealTopology` | 9 条关键顺序（每条都来自**真实签名**，非抄写法顺序） |
+| `TestLayeringYieldsRealParallelism` | 分层确实带来并行（≥2 模块同层） |
+| `TestKernelAPIIsInFirstLayer` | `initKernelAPI()` 真无依赖 |
+| `TestGroup0StaysOutOfScheduler` | 副作用顺序不被误放进图 |
+| `TestConfigModuleRunsAfterGroup0` | cfg 的**阶段前提**（安全块在 Group 0 里、config 不在） |
+| `TestDeclarationsTraceToRealCallSites` | **声明与真实签名不漂移**（改了签名要改声明） |
+| `TestNoOrphanFacilities` | 设施名无重复提供者 |
+
+**变异 5/5 咬住**：漏 lua→llm、漏 migration→store、config 挪回 Group 0、
+去掉 security、签名漂移。其中**变异 3 正是"无主模块"的复现**。
+
+#### 2.7.4 未做（Step 4b 的剩余）
+
+声明层已完成且可验证，但 `main.go` **仍走原来的串行代码**。
+下一步是把 `Run(plan)` 真接进 main（届时 17 步变 6 层），
+并让 `loadPluginsScheduled` 取代 `loadPlugins`（syncbus 驱动插件）。
+
+这两步都要改生产启动路径 ⇒ 需要更谨慎的验证（含真机启动对比）。
+
+### 2.8 完整启动流程与真实依赖（逐行核对，2026-10-16）
+
+> ★ 本节是用户要求的"**先完整捋一遍再声明依赖**"的产物。
+>
+> **为什么必须做这一步**：我第一版依赖是从**函数签名**推的
+> （`initLuaVM(cfg)` ⇒ 依赖 config）。签名只是**代理证据**，它说不了
+> 下面四类隐藏依赖 —— 而隐藏依赖恰恰是"加模块就出错"的主因。
+
+#### 2.8.1 第 0 阶段：core 自己先立起来（**不依赖任何模块**）
+
+| # | 行 | 步骤 | 依赖 | 性质 |
+|---|---|---|---|---|
+| 0.1 | 41 | `requireSupportedPlatform()` | 无 | 平台门（比 flag 还早） |
+| 0.2 | 43 | `parseFlags()` | 无 | |
+| 0.3 | 46 | guard 模式分流 | 无 | 早退 |
+| 0.4 | 71 | `startHeartbeat(dataDir)` | dataDir | ★ **时序**：必须在任何重型初始化前（否则 guard 判 stale 而 SIGKILL，实测 6 连杀） |
+| 0.5 | 78 | `setupLogging(dataDir)` | dataDir | |
+| 0.6 | 82 | `ensureDataDirs(dataDir)` | dataDir | 产出 agentWorkDir |
+| 0.7 | **89** | `NewConfigRegistry(config.db)` | dataDir | ★ **core 的根** |
+| 0.8 | **91** | `SeedDefaults` | cfgReg | |
+| 0.9 | 115 | `HardenDataDir` | dataDir | 权限收紧（内嵌密钥的必要缓解） |
+| 0.10 | 119 | `LoadOrCreateKey` | dataDir | ★ 必须在**任何读密文**前 |
+| 0.11 | 126 | `LoadKeyring` | key | E-1 轮换 |
+| 0.12 | 137 | `AdditionalDecryptKeys` | dataDir, key | 内嵌钥迁移 |
+| 0.13 | 143 | `security.InitGlobal` | key | 变量库 |
+| 0.14 | 153 | `InitConfigCodecWithOldKeys` | key | ★ 必须早于 0.15 |
+| 0.15 | 157 | `EncryptExistingSecrets` | codec | 幂等迁移 |
+| 0.16 | 173 | `AuditSecrets` | key | 诊断（E-2） |
+| 0.17 | 184 | `SetLLMSnapshotFile` | **security** | 读 `core.llm.*` |
+| 0.18 | 186 | `cfg := cfgReg.ToConfig()` | **security** | 读 `core.llm.*` |
+
+**★ 0.17/0.18 是"阶段依赖"，不是"数据依赖"**：
+它们并不消费安全模块的产物，而是"必须在密钥装好之后读，否则解出空串"。
+实测后果（我引入过）：全 provider 401，症状像"key 配错了"。
+⇒ 归 **Group 0**（显式串行 + 结构性判据），不进依赖图。
+
+#### 2.8.2 ★★ 四类**签名看不到**的隐藏依赖（本次逐项排查结果）
+
+用户指出"必须先完整捋一遍"，以下是排查出的四类。**其中 1 项是真缺陷隐患**。
+
+**(A) 包级可变全局单例 —— 实测只有 1 处**
+
+全仓扫描 `internal/` 的包级 `var`（排除常量/嵌入资源/注册表）后，
+**唯一**的可变全局单例是：
+
+```go
+// internal/nlp/parser.go:15
+var defaultParser Parser            // SetDefaultParser 写，GetParser/NewExtractor 读
+```
+
+**★ 它构成一个真实的运行时依赖**：
+
+- 写者：`initONNXParser`（main:289）
+- 读者：`nlp.NewExtractor(nil)` —— 在**构造时**快照 `defaultParser`
+  （`parser.go:60-62`），由 `extractKeyTriples`（`pipeline.go:503`）在
+  **蒸馏循环里**调用
+- 读取者的启动点：`startMemoryCandidateConsumer`（main:226）→ `distiller.Start()`
+
+**顺序上：蒸馏在 226 行启动，解析器在 289 行才装上。**
+按签名看这是"缺依赖"，但我核实后确认**当前是安全的**，原因是：
+
+```go
+func (d *Distiller) distillLoop() {
+    ticker := time.NewTicker(d.cfg.Interval)   // ★ 首次执行要等一个 Interval
+    for { select { case <-ticker.C: d.distillOnce() ...
+```
+
+`distillLoop` **不是立即执行**，首个 tick 要等 `Interval`（配置项，远大于
+启动耗时）⇒ 那一刻 `defaultParser` 早已装好。
+
+**★ 但这个"安全"是巧合，不是保证**：它依赖 `Interval > 启动耗时`。
+若将来有人把 Interval 调成 0/极小，或把 `initONNXParser` 挪得更后，
+就会**静默降级**（`pipeline.go:60` 的注释已记录后果：
+`defaultParser` 为 nil ⇒ POS 模板抽不出 ⇒ 图记忆里 188 个实体全是整句复合值
+⇒ 跨维度检索全失效，基线 0/5）。
+
+⇒ **处置**：声明式下把它变成**显式依赖**（`onnx-parser` 必须在
+`text-memory` 之前）—— 这正是模块化的价值：**把"碰巧安全"变成"结构保证"**。
+
+**(B) 共享文件/SQLite 的读写顺序**
+
+| 句柄 | 写/建 | 读/依赖 |
+|---|---|---|
+| `config.db` | `NewConfigRegistry`(89) | 此后所有 `cfgReg.*` |
+| `memory/graph.db` | `initMemoryStack`(190) | `newStageAndRegistry`(271)、`newMainAgent`(276) |
+| `memory/text/` | `initTextMemory`(220) | 同上 |
+| `knowledge/` | `initKnowledgeStore`(263) | 同上；且 `initKnowledgeMigration`(262) 必须**早于**它 |
+| `adapters/`（lua） | `initLuaVM`(200) | `initLLMProviders`(243) |
+
+⇒ 这些是**真实数据依赖**，已在声明里表达。
+
+**(C) `defer` 的逆序语义**
+
+原 main 用 `defer closeMem()` 等 5 处，释放顺序 = **注册顺序的逆序**（LIFO）。
+模块化后改为 `Put("<facility>.close", fn)` + `CloseAll()` 按**发布顺序逆序**执行
+⇒ 语义**逐字等价**（判据 `TestBootCtxCloseAllIsReverseOrder` 守）。
+
+**(D) 包级 `init()` 注册（BuiltinFactory）**
+
+`newStageAndRegistry` 依赖**各插件包 `init()` 自注册的工厂**
+（`plugin.RegisterFactory`），而 merge 顺序由 **import 顺序**决定。
+这**不是**图能表达的顺序（Go 规范保证 `init()` 在任何 `main` 语句之前跑完）
+⇒ 视为"启动前已就绪"，不进依赖图。但它意味着：
+**删除一个插件包的 import 会静默让它消失**（有空导入清单把关）。
+
+#### 2.8.3 依赖表的两个来源（**必须一致**）
+
+| 来源 | 强项 | 弱项 |
+|---|---|---|
+| **签名**（参数从哪来） | 明确、可直接扫 | 看不到全局单例/文件/init 注册 |
+| **运行期读取**（谁在何时读） | 抓到 (A)~(D) | 要逐个函数追 |
+
+**⇒ 判据必须同时钉住两者**：
+- `TestDeclarationsTraceToRealCallSites`：声明与**签名**不漂移
+- §2.8.2(A) 的 onnx→textmem 顺序：声明与**运行期读取**不漂移
+
+## 3. 兼容性约束（★ 硬约束）
+
+1. **存量插件的 `plugin.json` 不变必须照常工作**
+   - `handshake_timeout_sec` 省略 ⇒ 用默认值（与改动前逐字一致）
+   - 本仓无 `DisallowUnknownFields`，故"旧内核读新插件"与"新内核读旧插件"都无害
+2. **存量内核模块的行为不得改变**——拓扑排序后，原来的顺序必须仍被满足
+   （若拓扑排序得出的顺序与手写顺序冲突，说明手写顺序里有**未声明的隐式依赖**，
+   必须显式声明，而不是让排序器猜）
+3. **装配失败必须响亮**：缺依赖 / 循环依赖 / `Init` 返回错误 ⇒ 拒绝启动
+   （不得静默跳过——那正是病 A）
+
+## 4. 判据要求
+
+每条实现阶段必须配套判据，且判据**必须测真实入口**（本仓反复教训）。
+
+### 4.1 调度器（BFS 分层）的判据
+
+调度器是**纯逻辑**（给定依赖图 → 给定层次与并行分组），所以判据可以很硬：
+
+| 要守的性质 | 判据方式 | 变异验证 |
+|---|---|---|
+| **分层正确** | 给一个已知图，断言层次划分（同层两两无边、每个节点的前驱都在更早层） | 把 bfs 退化成"全串行"必须仍能看出**层次**丢失 |
+| **同层确实并行** | 层内两个模块各 sleep，总耗时 ≈ 单个（而非相加）；或用并发计数器观测"同时在跑" | 改成逐个串行必须报红 |
+| **有界并发生效** | 层内放 8 个模块、上限设 2 ⇒ 观测峰值并发 ≤ 2 | 忽略上限必须报红 |
+| **缺依赖拒绝启动** | 声明依赖一个不存在的设施 ⇒ 必须错误，且错误里含**缺的名字**与**已声明列表** | 静默跳过必须报红 |
+| **循环依赖拒绝启动** | A→B→A ⇒ 必须错误，且错误里含**环上的节点** | 报"有环"但不说成员也算不合格 |
+| **Init 失败传播** | 同层一个模块 Init 报错 ⇒ 整体失败（不被其他成功掩盖） | 吞掉错误必须报红 |
+| **无依赖 ⇒ 单层全并行** | 42 个无边节点 ⇒ 一层（仅受并发上限约束） | —— |
+
+**★ 调度的判据不能只看"最终都 Init 了"**：那是串行也能满足的弱断言。
+必须断言**层次结构与并行性本身**（本会话反复吃过的"判据太弱"）。
+
+### 4.2 各阶段判据
+
+| 阶段 | 判据 | 变异验证要求 |
+|---|---|---|
+| 第 0 组 | 安全模块装配点早于任何读 `core.llm.*` 的操作（结构性断言） | 移回去必须报红 |
+| 第 1 组 | 12 个内核模块走调度器後，**结果与手写顺序等价**（不是"换个顺序也能跑"） | 打乱声明仍得出同一层次 |
+| 第 2 组 | 外部插件并发加载：确实并行；并发上限生效；单插件失败不连累他者 | 去掉并发必须报红 |
+| Step 2 | 声明的超时**真的穿过 NewWithTimeout → Start → Spawn**；未声明时用默认 | 断接线必须报红 |
+| 第 3 组 | 关键依赖缺失 → 拒绝启动（不是静默降级） | 静默跳过必须报红 |
+
+**★ 启动顺序类判据的注意**（本会话踩过两次）：
+
+1. 只断言"某个调用出现在某行"不够——必须断言**真实的相对位置**，
+   且要覆盖**所有**读取点（第一版只盯了 `ToConfig()`，漏了 `SetLLMSnapshotFile`，
+   于是判据变绿而线上照旧报错）。
+2. **只测辅助函数不够**——必须覆盖**完整接线**。
+   实测（Step 2）：`TestSpawnHonorsDeclaredHandshakeTimeout` 直接把
+   `Options.HandshakeTimeout` 喂给 `Spawn`，删掉 `Start()` 里传值那一行它**依然全绿**。
+   补一条走 `NewWithTimeout → Start → Spawn` 的判据后才咬住。
+
+## 5. 与既有机制的关系
+
+| 既有机制 | 关系 |
+|---|---|
+| `events.Bus` | **保留**，用于运行期事件通知（同步、无回放，不适合启动装配） |
+| `inputch` `ChannelRegistry` | **保留**，父与驻留子共享的通道登记表（运行期共享总线的既有先例） |
+| 插件 SDK | **保留并扩展**：`plugin.json` 加 `handshake_timeout_sec`（Step 2 已完成） |
+| `security.Global()` | **保留**，但其"惰性 nil 容忍"**仅限真正可选的模块**；关键依赖必须显式检查 |
+| `pluginReg` 的 9 个 `SetXxx` | **保留**，作为"窄接口 + 显式注入"的既有范例 |
+
+## 6. 实施顺序（每步可独立验证、可回滚）
+
+```
+Step 1  ✅ 本设计文档（本文）
+Step 2  ✅ L1 超时声明：plugin.json → manifest → proc.NewWithTimeout → Start → Spawn
+          判据 8 条（含真实消费者 + 完整接线）+ 变异 2/2 咬住
+Step 4a ✅ 依赖图制品化：kernelboot 包（BFS 分层 + 二进制编解码 + 双重 hash）
+          + cmd/homed-depgraph 生成器 + Makefile 接线
+          判据 20 条 + 变异 8/8 咬住
+Step 4b ⏳ 把 12 个 init* 迁成 kernelboot.Module（声明清单即废止）
+Step 3  ⏳ 外部插件有界并发加载（收益点：实测 10s → 预计 ~2s）
+Step 5  ⏳ 第 3 组就绪断言（把 §1.2 的坑变成"启动即报错"）
+```
+
+**每步都必须**：加判据 + 变异验证 + 真机验证（启动耗时可测，是天然度量）。
+
+### 6.1 Step 2 的实测结果（已完成）
+
+| 项 | 结果 |
+|---|---|
+| 新增判据 | 8 条（解析 / 存量兼容 / 换算 / 上限 / 未知键 / Spawn 行为 / 完整接线 / 默认值） |
+| 变异验证 | 断接线、忽略参数 ⇒ **2/2 咬住** |
+| 真实消费者 | 用新建的 `slowshakeplugin`（故意延迟握手）证明不同超时值产生**不同可观测结果** |
+| 关键教训 | 初版判据直接给 `Spawn` 传参，**绕过**了 `Start()` 接线 ⇒ 删接线仍全绿（第 10 次同类） |
+
+## 7. 待定问题
+
+- [ ] 内核模块的 `Provides`/`Requires` 命名空间是否需要前缀（避免撞名）？
+- [ ] 第 2 组（插件）的默认并发上限取值？（需实测内存尖峰后定，暂定 4）
+- [ ] 是否允许插件声明"依赖其他插件"（插件间依赖）？当前认为不需要——
+      插件间通信走 `events.Bus` / inputch，不该有启动期依赖。
+- [ ] 调度器是否需要持久化"上次成功的层次"以便对比？（用于发现"层次变了"这种隐式顺序变更）
+
+---
+
+## 8. Step 4c：插件宿主归位为内核模块（方案 A，2026-10-16）
+
+### 8.1 决策：为什么调度逻辑必须在**内核模块**里
+
+用户选定方案 A。自举问题说清了原因：
+
+- `pluginmgr` 是**插件** ⇒ 它自己要被拉起 ⇒ 若调度逻辑在它内部，
+  就得**先拉起自己才能拉起自己**（循环）。
+- 调度器要订阅内核的 syncbus（内核设施），依附内核模块更自然。
+
+⇒ **调度放内核模块**（`internal/kernelmod/pluginhost`），
+`pluginmgr` 插件只保留**人机界面**职责（列表/启停/装卸的工具与 HTTP）。
+
+### 8.2 ★★ 核心收益：插件加载不再等 agent 的 35 秒
+
+原先 `wirePluginSDK` 写在 **agent 模块**里（第 4 层），于是插件加载被迫排在
+agent 之后 —— 而 agent 层实测要 **35 秒**（context dense backfill 750 events
++ 重建索引）。实测时间线（修复前）：
+
+```
+21:33:51  early_probe 被拉起   ← 装配期（plugin-host 自己）
+21:34:27  第 4 层完成: agent, plugin-host
+```
+
+⇒ **早拉起 36 秒**。修复后同一机器稳定复现。
+
+**拆法的依据（先核实再动手）**：
+
+| 插件加载的硬前置 | 来源 |
+|---|---|
+| `plugin.Registry` | stage-host 模块（第 3 层） |
+| `StageHost`（注册工具） | stage-host 模块 |
+| `Cfg` / 插件目录 | config 模块（第 0 层） |
+| LuaVM / Supervisor / Tracker / Indexer | 第 1~2 层 |
+
+而 `StatusProvider` / `TerminalAPI`（来自 agent）是**软前置**：
+
+- SDK 的 `Plugin` 接口只有 `Name/Start/Stop` —— **没有 `Configure`**。
+  （agent 模块里那句"插件 Configure 需要 StatusProvider"的注释**已过时**。）
+- 唯一在 `Start` 阶段引 `s.Status()` 的插件是 `healthcheck`，
+  且它是 **nil-guarded**（`if s.Status() != nil { … }`）。
+- `cli` 插件的 `s.Status()` 全在 HTTP handler 里（请求时才调）。
+
+⇒ 拆成"底层 7 项在 plugin-host 注入、agent 相关的 2 项由 agent 模块
+**后补注入**"。所有 setter 都是**简单赋值**（`r.status = sp`），
+可在插件加载后再调用；插件对它们**懒读** ⇒ 安全。
+
+### 8.3 分层结果（编译期算出）
+
+```
+第 0 层（2）: config, kernel-api
+第 1 层（8）: doc-store, knowledge-migration, lua, memory, multimodal, onnx-parser, supervisor, tracker
+第 2 层（3）: knowledge-store, llm, text-memory
+第 3 层（1）: stage-host
+第 4 层（2）: agent, plugin-host        ← ★ 并行（原先 agent 独占第 4 层）
+```
+
+`plugin-host.Requires` = `config, kernel-io, memory, lua, supervisor, tracker,
+text-memory, doc-store, knowledge, stage-host`（**刻意不含 agent**）。
+
+### 8.4 本模块做什么（用户的说法）
+
+> 插件管理器不应该在被拉起后就去读插件列表获取元数据并写入缓存准备拉起吗？
+
+对。`plugin-host.Init` 五步：
+
+1. **注入**插件 SDK 的底层 7 项依赖（不含 agent 的两项）
+2. **扫一次**目录 → **元数据缓存** `PluginCatalog`（存进 `ks.PluginCatalog`）
+3. 按**三形态**分流（§2.6.6）
+4. 拉起"声明设施已就绪"的；"等更晚设施"的挂到 syncbus（`waiter.go`）
+5. **加载内置插件** —— `LoadSkipping(dir, skip)`
+
+**元数据缓存**同时供三方用：调度器（判时机）、`pluginmgr`（列列表/状态）、
+显式启用路径（校验名字存在）。原先这两处各读各的 `plugin.json`。
+
+### 8.5 ★★ 实测踩到的两个真缺陷（都必须写下来）
+
+#### 缺陷 1：内置插件全部消失（19 个）
+
+第一版只处理"有 `plugin.json` 的**外部插件**" ⇒ 结果：
+
+| | 插件数 | 工具数 |
+|---|---|---|
+| 缺陷版 | 2 | **10** |
+| 修复版 | 20 | **86** |
+
+丢的是 `webui`（人机界面）、`pluginmgr`（插件管理）、`cli`、`files`、
+`cmd`、`timer`、`mcp`… —— 全是**编译期工厂注册**的内置插件，
+目录里**没有 `plugin.json`**。
+
+**为什么危险**：日志看起来正常！只有一条容易被当噪音略过的提示
+（我初版还把它写成"跳过 19 个非插件目录" —— 措辞本身就是误导）。
+若无真机 e2e，生产会从 **337 工具掉到 10 个**。
+
+**修法**：走 `LoadSkipping(dir, skip)` —— 那是**唯一**同时加载
+外部插件（扫目录）与内置插件（遍历工厂表）的入口。
+并修正日志措辞（"N 个目录无 plugin.json，**内置插件属正常**"）。
+
+#### 缺陷 2：三形态的 skip 集合漏项
+
+`skip` 集合若不含 `manual`（`auto_start=false`）⇒ 该插件会被
+`LoadSkipping` **立即全量加载** ⇒ 与"启用但不自动启动"**完全相反**。
+
+**修法**：抽 `buildSkipSet(g)`，把三形态 + 内置插件的边界写在一处：
+
+| 类别 | 在 skip 里？ | 理由 |
+|---|---|---|
+| ② `auto_start=false` | ✅ | 否则被全量加载（违背语义） |
+| ③ `disabled` | ✅ | 显式跳过（registry 另有禁用门兜底） |
+| ① 声明了依赖的 | ✅ | plugin-host 自己按时机拉起（防重复） |
+| **内置插件** | ❌ | **必须**走 `LoadSkipping` 的工厂分支 |
+
+### 8.6 ★★ 判据教训：源码字符串检查**连续骗过我三次**
+
+| 版本 | 判据写法 | 变异 | 结果 |
+|---|---|---|---|
+| 一版 | `Contains(code, "LoadSkipping(")` | 删掉调用 | **仍绿**（注释里有该字样） |
+| 二版 | `Contains(code, "LoadSkipping(dir, skip)")` | 改成 `(dir, nil)` | **仍绿**（注释第 116 行正好写着这个串） |
+| 三版 | **AST**：找 `CallExpr` 且第二实参非 `nil` | 同上 | ✅ 咬住 |
+| 三版 | AST：`buildSkipSet` 有真实调用点 | 改成不调用 | ✅ 咬住 |
+
+**根因**：本仓规范要求"每个关键决定都在注释里讲清楚" ⇒ 注释里**几乎必然**
+出现关键符号名 ⇒ `strings.Contains` 型判据**永远绿**。
+
+**结论（写进规范）**：
+
+> 源码字符串检查**只能**用于断言"某个符号定义是否存在"
+> （如 `func buildSkipSet(`），
+> **绝不能**用于断言接线/调用顺序。
+> 断言接线必须用：① **AST**（`CallExpr` + 实参检查），
+> 或 ② **行为测试**（真的调那个函数）。
+> 顺序类不变量用**行号/字节位置比较**（本文件 §4 的既有做法）。
+
+### 8.7 syncbus 的落点修正（实测撞到）
+
+模块的 `Init(ks)` **只能看到 `KernelState`**，而 `SyncBus` 原先只是
+`RunKernelModules` 的局部变量 ⇒ 模块**拿不到它**，无法订阅状态变化
+（`plugin-host` 要挂"等 agent 就绪再拉起某些插件"的回调）。
+
+**修法**：`SyncBus` 放进 `KernelState`（`ks.SyncBus`，由 `Run` 填入）。
+它本来就是**内核级共享状态** —— 用户"内核用一个结构体收集全部共享变量"
+的设计正好覆盖它。
+
+### 8.8 迁移引入的**新时序要求**（必须复核的清单）
+
+把插件拉起从"装配后"挪到"装配期"，引入了两处顺序要求：
+
+| 事项 | 必须在 | 理由 |
+|---|---|---|
+| failback 插件白名单 | **装配前** | 装配期已拉起 ⇒ 晚设则受限启动失效 |
+| 白名单的 `SetLoadAllowlist` | stage-host 就绪后、插件拉起前 | 需要 `plugin.Registry`（stage-host 产物） |
+
+实现：`resolveFailbackAllowlist`（装配前解析）+
+`OnLayerDone` 钩子在 registry 就绪时 `SetLoadAllowlist`。
+
+### 8.9 本步判据
+
+`internal/kernelmod/pluginhost/catalog_test.go`（6 条，全绿）：
+
+1. `TestClassifyThreeForms` —— 三形态分流 + **互斥性**
+2. `TestCatalogCachesMetadata` —— 每个字段都缓存对
+3. `TestScanReportsNoManifestDirs` —— 无 manifest 的目录被**如实报告**
+4. `TestBuiltinsAreNotSkipped` —— **内置插件不在 skip 里**（行为判据）
+5. `TestSkipSetHasRealCallSite` —— **AST** 判定 `buildSkipSet` 被真实调用
+   且 `LoadSkipping` 的第二实参非 `nil`
+6. `TestCatalogConcurrentRead` —— 并发读安全
+
+**变异验证 5/5 咬住**：去掉 `LoadSkipping` / `buildSkipSet` 跳内置插件 /
+`manual` 不进 skip / `(dir, skip)→(dir, nil)` / `buildSkipSet` 不被调用。
+
+**连带修复的 3 个既有判据**（因锚点随模块化失效，全部**换锚而非放宽**）：
+`TestMainInitsSecurityBeforeProviders`、`TestSecurityModuleInitializesBeforeConfigSnapshot`
+（并额外加固："provider 注册确实在 llm 模块里"+ "llm 模块确实被 import"）、
+`webui/handler_plugin_test.go` 的 mock（补 SDK 新增的 3 个方法）。
+
+### 8.10 补充：复用内核 Scheduler（删掉我手写的重复实现）
+
+第一版我在 `pluginhost/waiter.go` 手写了一套"等设施就绪再拉起"的调度
+（124 行）。**那是重复造轮子**：`kernelboot.Scheduler`（309 行）做的
+正是这件事，而且已有完整判据（拼错校验、同批去重、`OnUpdate` 订阅、
+`LaunchedFlag`、`SetLaunchErrorHandler`…），我的手写版只覆盖了一小半。
+
+**修法**：删掉 `waiter.go`，改用 `kernelboot.NewScheduler(ks.SyncBus, launch)`。
+
+★ 且这里**不需要两段式**（原调度器在 main 里、装配前拿不到插件注册表，
+所以要 `attach`/`SetLaunch` 分两段）：`plugin-host` 在**第 4 层**，
+执行 `Init` 时 `stage-host`（第 3 层）已就绪 ⇒ 注册表**已存在**
+⇒ 拉起动作可一次性接上。**分层位置变好，顺带消掉了两段式的复杂度。**
+
+**教训**：迁移功能时先搜"内核里是不是已经有这个能力"。重复实现不只是
+浪费，更会让"两份实现改一处漏一处"成为必然。
+
+### 8.11 补充：typed-nil 陷阱（实测 panic）
+
+`ks.SyncBus` 语法上是 `*SyncBus`。若直接传给 `NewScheduler(bus SyncState, …)`：
+
+```go
+var nb *SyncBus
+var i SyncState = nb   // ★ i != nil！经典的 typed-nil 陷阱
+```
+
+接口值**非 nil**（它带类型信息），于是 `bus.IsReady(...)` 解引用空指针 ⇒ **panic**。
+
+**实测复现**：`TestNilTypedBusSafety` 确认 panic 真实发生
+（`invalid memory address or nil pointer dereference`）。
+而 panic 在**插件拉起路径**上 ⇒ 整个内核启动失败。
+
+**修法**：显式判 `ks.SyncBus != nil` 后再赋给接口变量；
+为 nil 时用一个**已标记内核完成**的空 bus 退化（安全退化：依赖未就绪的
+插件在 `Start` 时自行处理，healthcheck 之类本就 nil-guarded）。
+
+**判据** `TestNilSyncBusDoesNotPanic` 两段：
+① 确认陷阱**真实存在**（typed-nil 确实 panic —— 否则判据是空的）；
+② `mod.go` 必须有显式 nil 判断，且**不得**直接传 `ks.SyncBus`。
+（★ 这条用 `strings.Contains` 是**可取**的：它断言的是"是否存在某个
+防御性判断"，属于"符号定义是否存在"那一类，不是接线断言。）
+
+### 8.12 ★★ 违反 §2.6.5 硬约束（我引入的第三个缺陷 —— 有实测后果）
+
+#### 缺陷本身
+
+把插件拉起搬进 `plugin-host.Init`（第 4 层）后，我按"本模块依赖是否覆盖
+插件声明"把插件分成 `launchNow` / `waitLater`，并**在 Init 里直接加载 launchNow**。
+
+问题：**未声明依赖**的插件 `RequiresFacilities` 是**空** ⇒ "本模块依赖覆盖空集"
+**恒真** ⇒ 它们被归入 `launchNow` ⇒ **第 4 层就被加载**。
+
+而 §2.6.5 的硬约束是：
+
+> 未声明 ⇒ 启动时机**逐字不变**（内核**完全**初始化完成后）
+> ……**静默改变启动时机 = 静默引入竞态**。
+
+**实测证据**（planA4.log）：
+
+| | 时刻 | 阶段 |
+|---|---|---|
+| `loaded: healthcheck` | **21:54:37** | 第 4 层（agent 并行中） |
+| 内核装配完成 | 21:55:12 | — |
+
+⇒ 早了 **35 秒**。
+
+#### ★ 后果不是理论上的 —— 精确地丢了一个工具
+
+`internal/plugins/healthcheck/plugin.go:249`：
+
+```go
+if s.Status() != nil {
+    p.selfToolNames["healthcheck_kernel"] = true
+    s.RegisterTool("healthcheck_kernel", …)
+}
+```
+
+第 4 层时 agent 还没建好（它与 plugin-host **并行**）⇒ `s.Status()` 为 **nil**
+⇒ **静默少注册一个工具**。实测工具数 **86**（应为 **87**），**无任何报错**。
+
+这正是 §2.6.5 那句警告的**逐字实现**：nil 保护把"时序错了"降级成
+"少个功能"，是最难发现的一类缺陷。修复后（planA5）87 工具、`healthcheck_kernel` 回归。
+
+#### 修法
+
+1. **不再自己判时机**：全部自动启动的插件都交给 `kernelboot.Scheduler`
+   ——它已正确实现 §2.6.5（空声明 ⇒ 等 `KernelComplete()`）与 §2.6.6
+   （`!AutoStart` ⇒ 不自动拉起），且有完整判据。
+2. **未声明的 + 内置的**：挂到 syncbus 的 `KernelComplete` 上再 `LoadSkipping`
+   （内核**推**状态，不轮询）。
+
+### 8.13 ★★ 双加载（第 4 个缺陷，按构造修复）
+
+`buildSkipSet` 我第一版只跳过 `declared ∪ manual ∪ disabled`
+⇒ **未声明的外部插件不在 skip 里** ⇒ 它同时被两条路加载：
+
+- 调度器（它管未声明的，等 `KernelComplete` 后拉起）
+- `LoadSkipping`（不在 skip 里 ⇒ 也加载）
+
+**实测（变异 G'，忠实复现第一版）**：`undeclared_probe` 被 loaded **2 次**，
+工具数 **92 → 97**（+5 = 它重复注册的那批）。
+
+planA5 侥幸未触发，只因测试目录里那 3 个外部插件恰好都声明了依赖或不自启
+—— **不能依赖这种巧合**。
+
+**修法（按构造消除）**：
+
+> **catalog 里登记过的插件，一律不交给 `LoadSkipping`。**
+
+这样两条路**按定义不相交**：Scheduler 管 catalog 内全部（三形态之一），
+`LoadSkipping` 只管 catalog **之外**的 —— 也就是**没有 `plugin.json` 的内置插件**
+（编译期工厂，只有它能加载）。
+
+**真机终验**（有未声明外部插件 `undeclared_probe`）：
+
+| 检查 | 结果 |
+|---|---|
+| 未声明插件等内核完全初始化 | ✅ `22:16:53`（装配完成时刻） |
+| 声明的插件早启动 | ✅ `22:16:25`（早 **28 秒**） |
+| 未声明插件只加载一次 | ✅ 1 次 |
+| `healthcheck_kernel` 回归 | ✅ 92 工具 |
+
+### 8.14 本步判据（终版，9 条）
+
+新增两条**守 §2.6.5 与双加载**：
+
+8. `TestUndeclaredPluginsWaitForKernelComplete` —— 用**真的 Scheduler + 真的
+   SyncBus** 跑生产路径：未声明的在内核完成前**不得**被拉起，完成后**必须**被拉起；
+   声明的在依赖就绪时**应当**被拉起（保住本步核心收益）。
+9. `TestUndeclaredNotDoubleLoaded` —— catalog 内的插件**必须在** skip 里
+   （否则双加载）；内置插件（不在 catalog）**不得**在 skip 里。
+
+**变异验证（4 轮）**：
+
+| 变异 | 结果 |
+|---|---|
+| 未声明的也直接拉起（复现 §2.6.5 违反） | 单元判据咬住 |
+| 把 `LoadSkipping` 挪回 Init（复现原 bug） | 真机：healthcheck **loaded 2 次**，工具 87→**161** |
+| `skip` 只含 declared/manual/disabled（第一版写法） | 单元 + **真机双咬**：`undeclared_probe` 2 次、工具 92→**97** |
+
+★ **变异 G 的教训**：第一次变异（只删 `c.Names()` 循环）是**空操作** ——
+因为 `c.Names()` 与三形态循环**重叠**（三形态之和 = catalog 全部）。
+**变异必须忠实于"原缺陷的写法"，否则变异本身无效**（假绿）。改成
+"skip = declared+manual+disabled"（第一版的真实写法）后才咬住。
diff --git a/docs/zh/kernel-secret-firewall-design.md b/docs/zh/kernel-secret-firewall-design.md
new file mode 100644
index 00000000..ed9b4264
--- /dev/null
+++ b/docs/zh/kernel-secret-firewall-design.md
@@ -0,0 +1,908 @@
+# 内核安全模块（Secret Firewall）设计 · 计划追加
+
+> **状态：已实现（持续审计中）。** 本文的安全模块、配置加密、变量库统一与 C1–C8 判据已落地；E-1/E-2/E-3/E-4 已完成；剩余项见文末实现边界。本文保留原始设计与逐条审计记录。
+> 记录一条由用户纠正后确立的**架构决定**，以及它带来的简化与下沉。
+>
+> 撰写时间：2026-10-14。触发：用户在讨论 commondev 加密 shell 时提出两点纠正。
+
+---
+
+## 0. 用户的两条纠正（原话，不可转述走样）
+
+> 「『拦截后让 agent 用变量读取』意味着被拦截的明文要能再取回。
+>   并不是明文取回，而是**后续使用仅可使用变量替代**。
+>   我觉得这部分需要**下沉到内核内部作为安全模块**存在了。
+>   （因为 llms 调用本身是不可信的）」
+
+> 「这样插件设计就简单了，可以**直接将密钥明文投到消息内部**，
+>   由**内核安全机制全权负责**」
+
+**这两条纠正了一个错误方向**，本文先记录错在哪，再记录纠正后的设计。
+
+---
+
+## 1. 被纠正的错误方向（前稿的做法）
+
+前稿（`commondev-agent-runtime-design.md` §2.7 之后那批讨论）里，我把
+"敏感信息拦截"实现为 **commondev 插件内的 stage**：
+
+```go
+// 前稿：插件在 StageOnInput / StageAfterToolcall 上拦截
+p.sdk.RegisterStage(sdk.StageOnInput, func(ctx *sdk.StageContext) error {
+    res := p.icept.Intercept(ctx.RawMessage, "input")
+    ctx.RawMessage = res.Text   // 换成 @{sec_1} 提示
+    ...
+})
+```
+
+**错在两处**：
+
+| # | 错误 | 为什么错 |
+|---|---|---|
+| 1 | **把拦截器放在插件里** | 插件在**信任边界之外**。它是独立进程，别的插件（或它自己崩溃/被替换）都能绕过。而"LLM 调用不可信"意味着**每个** LLM 调用都要过这道闸——插件的注册是**自愿的**，不是强制的 |
+| 2 | **把"可再取回"当成需求** | 前稿甚至设计了 `enc_show` 之外的取回路径。但用户要的是**只能替代引用，永远拿不到明文** —— 一旦有取回路径，LLM 就能把明文写回上下文，整层作废 |
+
+### 1.1 还暴露了两个真实缺陷 ［已核 · 单测抓到］
+
+即便只作为插件实现，前稿也有两个 bug（保留记录，因为它们说明"判据在起作用"）：
+
+1. **`*SensitiveInterceptor` nil 时 panic** —— `Intercept` 里 `si.enabled` 直接解引用。
+   已修（`si == nil ||`），这是真实健壮性问题：宿主可能在任何阶段调用。
+2. **赋值形态丢失键名** —— `api_key = "xxx"` 被整体替成提示，人看不出发生了什么。
+   `splitKeyValue` 对 `assigned_secret` 的命中形态判断有误。**修法未完成**（本文第 5 节列为待办）。
+
+> 教训：这两个缺陷都是**单测**发现的，不是读码。印证本仓纪律——判据必须跑。
+
+---
+
+## 2. 纠正后的架构：下沉为内核安全模块
+
+### 2.1 出向落点：provider 层（实测推翻初稿） ［已核 · 源码确认］
+
+初稿写“唯一出网点是 `task.go:663`”。**实测扫全仓后这个结论是错的** —— 构造
+`CompletionRequest` 的地方有 **7 处**（不含插件侧）：
+
+| # | 位置 | 用途 |
+|---|---|---|
+| 1 | `internal/agent/core/task.go:663` | 主对话轮次（最主要） |
+| 2 | `internal/agent/core/spawn.go:176` | `spawn_child` 的工作式轻量子 |
+| 3 | `internal/agent/core/spawn.go:321` | LLM 相关工具（`llm_*`） |
+| 4 | `internal/agent/core/modalfallback.go:347` | 多模态回退调用 |
+| 5 | `internal/agent/api/provider.go:1140` | `ProviderManager.QuickChat` |
+| 6 | `internal/sdk/llm_impl.go:56` | 插件调 LLM（`s.LLM().Chat`） |
+| 7 | `internal/plugins/*`（multimodal / healthcheck / remotedevice） | 插件自己发起的 LLM 调用 |
+
+⇒ **在 task 层拦一道会漏掉 4–7 四大类**。其中 #6 尤其要紧：
+插件经 `s.LLM().Chat` 发起的调用**完全绕过**主对话路径。
+
+#### 正确的落点：**provider 层**
+
+所有路径最终都会进某个 `Provider.Chat(ctx, *CompletionRequest)`。所以安全模块
+应放在**provider 调用的统一层**（装饰器/包装器），而不是 task 层：
+
+```
+任何来源 ──► CompletionRequest ──► ★ 安全包装器（必经）──► 真正的 Provider
+```
+
+**待确认**：是否存在不经 `Provider.Chat` 的出网路径（如某 provider 内部直发 HTTP）。
+这一条必须先验（§5.1），否则安全模块仍有洞。
+
+### 2.2 数据模型：明文可以自由流动，只在出口被替换
+
+用户第二条纠正的直接后果：**插件可以把密钥明文投到消息内部**。
+
+```
+插件/工具/任何来源 ──(明文，随便用)──► f.Msgs
+                                          │
+                              ┌───────────▼───────────┐
+                              │ 内核安全模块（必经）    │
+                              │ 扫描 → 命中 → 换成别名  │
+                              └───────────┬───────────┘
+                                          ▼
+                                   真正发往 LLM 的 req
+```
+
+好处（这是简化，不是妥协）：
+- 插件不需要自己造加密库、别名表、stage 拦截（前稿那一整套）⇒ **插件变薄**
+- 插件也不需要"安全地传输明文"的协议——**直接投，内核负责**
+- 别名表归内核管理 ⇒ 全局唯一，且与 agent 实例解耦
+
+**代价（必须写清）**：明文在**内核进程内存**里自由流动。
+所以边界是"内核进程可信"，不是"内存里不存在明文"。
+
+---
+
+### 2.3 ★ 不是“拦截”，而是“拦截 + 暂存 + 别名 + 回填” ［用户 2026-10-14 纠正］
+
+用户纠正了我“只做拦截”的单向理解，并给出**完整回路**：
+
+> 「因为你只是简单的拦截的话，**绝大部分插件会失去原本的功能**。
+>   安全模块是**拦截，加密暂存，提供调用别名，收到 toolcall 后自动将别名填充进去**。
+>   因为内核 0 IO 设计，一切外部交互都是从插件走的，你只需要在 **toolcall 和
+>   outputch 部分有注入**就行了」
+
+⇒ **为何只拦截不行**（这是本节的关键）：
+
+如果只在出向把明文换成 `@{sec_1}`，则插件再也**拿不到**密钥 ——
+而插件恰恰是唯一能真正用密钥的地方（push / 调 API / 写文件）。
+结果就是：**安全了，但活干不了了**。那等于把功能删掉，不是安全。
+
+⇒ 必须是一个**闭环**：
+
+```
+① 拦截    LLM 出向前扫到明文  ──► 换成 @{别名}
+② 加密暂存 把明文 AES-GCM **落盘**在内核（不落明文）
+③ 别名    ★ 哈希键（由明文派生，见 §2.4）
+④ 回填    插件调用（toolcall / outputch）前，把 @{别名} 换回明文
+          —— ● **插件无感知**：它只看到已经填好的明文
+```
+
+### 2.4 ★ 变量索引：**哈希键** —— 于是自动获得“同变量合并” ［用户 2026-10-14 纠正］
+
+用户纠正了两件事（我初稿用的是 `sec_1`、`sec_2` 顺序号，**那是错的**）：
+
+> 「落盘暂存，各个变量通过**哈希键索引**，这样自然获得了**同变量合并能力**。
+>   同时变量**不自动淘汰**，但是 agent 可主动调用安全模块提供的工具**提交/删除**」
+
+#### 为何哈希键是对的（顺序号错在哪）
+
+| | 顺序号 `sec_<n>`（错） | **哈希键**（对） |
+|---|---|---|
+| 同一 secret 出现两次 | 得到 `sec_1` / `sec_2` **两个别名** | 得到**同一个**别名 ⇒ ★ **自动合并** |
+| 合并需要额外逻辑吗 | 需要（要扫描所有别名比对明文） | **不需要**（哈希本身就是键） |
+| 时序依赖 | 有（序号与拦截顺序绑定） | 无（键由内容唯一确定） |
+| 重启后一致吗 | 依赖持久化的计数器 | 重算即可（同一明文 ⇒ 同一键） |
+
+> ⇒ **“同变量合并”不是额外功能，而是哈希索引的天然性质** —— 这正是用户要的。
+> 这也消除了一个隐患：同一把密钥在对话里出现 5 次，不应产生 5 个别名，
+> 否则日志/记忆里会积起一堆指向同一密钥的不同名字。
+
+#### 键的构造
+
+```
+alias = "sec_" + hex( HMAC-SHA256(masterKey, plaintext)[:8] )
+```
+
+**两个细节不能省**：
+
+1. **必须用 HMAC（带 masterKey），不能裸 SHA256**。
+   裸哈希对短/低熵输入可被字典枚举 —— 而别名会出现在**上下文、日志、记忆**里，
+   等于把“这个 secret 是什么”泄露出去。
+
+   **实测演示**（本机跑过）：取明文 `hunter2`，裸 SHA256 取前 8 字节作别名，
+   然后拿 5 个常见弱口令去试：
+
+   ```
+   别名（裸哈希）: f52fbd32b2b3b86f
+   ★ 字典命中：'hunter2' → 别名直接暴露了 secret 内容
+   ```
+
+   换成 HMAC(masterKey) 后，攻击者**没有 masterKey 就无法枚举**。
+2. **8 字节（16 hex）** 足够：碰撞概率对本场景可忽略，而短别名省上下文。
+   实测别名形如 `sec_3718c87a11e9478b`（**20 字符**）。
+
+> 为什么不加随机 salt：加了就**失去合并能力**（同一明文每次得到不同键）。
+> 所以这里“确定性”是**特性**，不是缺陷；安全靠 HMAC 的密钥而不是 salt。
+>
+> **实测验证**（本机跑过）：
+>
+> | 断言 | 结果 |
+> |---|---|
+> | 同明文两次 ⇒ 同一别名（自动合并） | ✅ 两次都是 `sec_3718c87a11e9478b` |
+> | 不同明文 ⇒ 不同别名 | ✅ |
+> | 别名长度（要进上下文） | ✅ 20 字符 |
+> | 换 masterKey ⇒ 别名变（键依赖密钥） | ✅ |
+
+#### 生命周期：不自动淘汰，但可**主动**提交/删除
+
+| 行为 | 谁决定 | 说明 |
+|---|---|---|
+| **自动淘汰** | ❌ **不做** | 用户明确：变量不自动淘汰 |
+| **主动提交** | agent 调安全模块的工具 | 把某些明文显式登记为变量（即使尚未出现过） |
+| **主动删除** | agent 调安全模块的工具 | 明文用完即弃（如轮换后）
+| **持久化** | 内核 | **落盘暂存**（加密），重启不丢 |
+
+**为何“不自动淘汰”是合理的**：
+
+- 任务可能跨很多轮、跨多个子 agent（§2.6 全局共享），早先登记的变量随时要能用；
+- 自动淘汰需要定策略（按时间？按引用计数？）——而策略错了会导致“变量静默失效”、
+  任务在很后面才坏掉，且现象难归因；
+- 反过来，**泄漏风险由“主动删除”控制**，而不是靠超时时间。
+
+⚠ **待定（T9）**：不自动淘汰 ⇒ 落盘文件会只增不减（除非人主动删）。
+需要定一个**可观测**的规模上限降级策略（如超 N 条时告警而非静默删）。
+
+### 2.5 ★ 两个注入点就够了（内核 0 IO） ［已核 · 源码确认］
+
+用户指出：“内核 0 IO 设计，一切外部交互都是从插件走的”。
+⇒ 于是**只需在两根咽喉上做替换**：
+
+| 方向 | 咽喉 | 位置 | 作用 |
+|---|---|---|---|
+| **入向**（→插件） | `StageHost.ExecuteTool(name, args)` | `internal/agent/core/stages.go:140` | toolcall 参数里的 `@{别名}` → 明文 |
+| **入向**（→插件） | `OutputChannel` 的 device `Execute` | `internal/agent/core/output.go:76` | 输出载荷里的 `@{别名}` → 明文 |
+| **出向**（→LLM） | provider 层的 `Chat(req)` | `internal/agent/api/`（装饰器） | `f.Msgs` 里的明文 → `@{别名}` |
+
+#### 入向覆盖确认（调插件工具的入口）
+
+| 路径 | 位置 | 覆盖 |
+|---|---|---|
+| agent 发的 tool_call（主路径） | `toolcall.go:133` → `stages.go:140` | ✅ |
+| 插件经 ToolAPI 调另一个插件 | `sdk/tool_impl.go:47` | ✅ |
+| 设备/通道工具 | `io/channel.go:714/730` | ✅（走同一 `Execute`） |
+| outputch 出向到插件 | `output.go:76` → `dev.Execute` | ✅ |
+
+> ⇒ **只需两处**（`StageHost.ExecuteTool` + `IOManager` 的设备 `Execute`）
+> 就覆盖全部插件交互 —— 因为**内核自己不碰外部世界**（零 IO）。
+> 这是“零 IO”设计的一个**意外红利**：安全边界只有两个点。
+
+### 2.6 为何“插件无感知”很重要（不是洁癖）
+
+| 理由 | 说明 |
+|---|---|
+| **插件无法绕过** | 插件根本不知道有替换这回事 ⇒ 无法写“我自己解密” 的代码去绕开 |
+| **存量插件无需改** | 所有已有插件（qq / browser / …）自动获得该能力 |
+| **接口不变** | 不需要给 SDK 加任何参数 ⇒ 不破兼容（本仓“只增不减”） |
+| **职责单一** | 安全归内核；插件只管业务 |
+
+#### ⚠ 与“插件明文中转”的关系（用户拍板的简化）
+
+用户已明确：“插件可以直接将密钥明文投到消息内部，由内核安全机制全权负责”。
+
+⇒ 两者不矛盾，而是**分工**：
+
+| 环节 | 谁负责 |
+|---|---|
+| 插件要向 LLM 交代“我用的是哪条密钥” | **直接写明文**（内核出向会把它变成 @{别名}） |
+| 插件要实际**用**密钥（如 push） | 写 `@{别名}`，内核**入向**换成明文后再交给插件 |
+| 别名表 / 加密存储 / 扦描 | **全部在内核**（插件不参与、不知情） |
+
+**待确认**：入向替换也会换掉 `cmd_run` / `terminal_write` 的**参数**（它们是工具调用）。
+这带来一个新问题 —— **agent 可以把 `@{别名}` 写进任意命令参数**，等于获得了
+“在任意命令里使用明文”的能力。这正是用户要的（否则没法用密钥），
+但它把“能做什么”的边界交回给了 **命令本身**（即 enc_shell 的安全边界问题）。详见 §5 T8。
+
+### 2.7 ★ 变量系统是**全局通用**的（父子 agent 同一套） ［用户 2026-10-14 追加］
+
+用户明确：
+
+> 「注意安全模块的变量系统是**全局通用**的，驻留式子 agent、子 agent、
+>   主 agent 是**同一套变量系统**」
+
+#### 为何必须全局（不能 per-agent） ［已核 · 源码确认］
+
+驻留子共享父的对象（`resident.go:184-185`）：
+
+```go
+Provider:        a.provider,
+ProviderManager: a.providerManager,   // ★ 共享同一个 ProviderManager
+StageHost:       a.stageHost,
+```
+
+而 `ProviderManager` **全进程只建一份**（`cmd/homed/bootstrap.go:249` 建一次；
+`resident.go:185` 把它传给每个子）。⇒ 安全模块（作为 provider 装饰器）
+**天然就是全进程单例**。
+
+#### 为何“全局”是正确设计（而不只是实现便利）
+
+| 理由 | 说明 |
+|---|---|
+| **否则无法跨 agent 协作** | 父拦截得到 `@{sec_1}`，要能交给子去干活；子的 `@{sec_1}` 若不同则断链 |
+| **别名不泄露就能共享** | `sec_<n>` 本身不含明文，共享它不降低安全性 |
+| **与 L4 归属正交** | 驻留子的 `KernelSource`/权限是 per-agent（隔离）；变量系统是全局（共享）。**两件事，不要混** |
+
+#### ⚠ 一个必须想清的后果：权限边界不因共享而放松
+
+变量全局 ⇒ **任何 agent 都能写 `@{sec_1}`**。但回填后**能不能真的用**，取决于该
+agent 的工具/通道授权：
+
+| 层 | 作用域 | 管什么 |
+|---|---|---|
+| **变量系统** | ★ **全局** | 别名 ↔ 明文（不区分 agent） |
+| `AllowedOutputs` / 工具授权 | **per-agent** | 该 agent 能不能调某个工具/通道 |
+| `KernelSource`（L4） | **per-agent** | 该 agent 的上级是谁 |
+
+⇒ 子 agent 拿到了明文，但**能否拿它去 push** 仍受它自己的授权限。
+两者是**正交**的两道门（变量共享 ≠ 授权共享）。
+
+#### 实现形态
+
+⇒ 安全模块不能挂在 `*Agent` 上（那是 per-agent），而应：
+
+```
+internal/security/ 里的一个**进程级单例**（或挂在 ProviderManager 上）
+    ├─ 别名表  alias → secret（全局）
+    ├─ 出向扫描（provider 装饰器，天然单例）
+    └─ 入向回填（StageHost.ExecuteTool / 设备 Execute；两者也是共享对象）
+```
+
+> **恰好舒服的地方**：两个注入点（`StageHost` / `IOManager`）与出网点
+> （`ProviderManager`）**都已经是共享对象** ⇒ 安全模块挂上去就是全局的，
+> **不需要额外做“跨 agent 同步”**。
+
+### 2.8 与"两阶段拦截"的关系
+
+前稿用 `StageOnInput` + `StageAfterToolcall`。那两个点**仍然有意义，但不是安全边界**：
+
+| 位置 | 性质 | 说明 |
+|---|---|---|
+| `StageOnInput` / `StageAfterToolcall` | **提示性、可绕过** | 提前替换能让日志/记忆干净一些，但**不构成安全** |
+| **两根咽喉**（入向 `ExecuteTool`/`Execute`，出向 `Chat`） | ★ **强制的安全边界** | 无论前面漏了什么，这里都是最后一道且必经 |
+
+⇒ 结论：**安全责任放在咽喉上**；前面的 stage 拦截降级为“卫生措施”（可选、可关）。
+
+## 3. 硬约束（安全模块的不可让步项）
+
+| # | 约束 | 理由 |
+|---|---|---|
+| **S1** | **不提供"取回明文"的任何接口** | 用户明确：只能**替代引用**。一旦有取回路径，LLM 就能把明文写回上下文，整层作废 |
+| **S2** | 替换必须落在**必经点**上 | 插件是自愿注册的 ⇒ 插件侧拦不算边界。
+  已核两个必经点：出向 `Provider.Chat`、入向 `StageHost.ExecuteTool` + 设备 `Execute` |
+| **S3** | 别名**全局唯一且不泄漏明文** | ★ **哈希键**：`sec_ + HMAC-SHA256(masterKey, plain)[:8]`。
+  **必须用 HMAC 而非裸哈希**（裸哈希可被字典枚举；而别名会出现在上下文/日志/记忆里）；
+  **不加 salt**（加了就失去合并能力，确定性是特性） |
+| **S4** | **不可误伤** | 误报会把正常内容换掉、搞坏任务。模式库保守优先——**宁可漏，不可误伤** |
+| **S5** | **不得静默** | 每次拦截要可观测（别名、来源位置、长度、时间），否则出问题无从追查 |
+| **S11** | ★ **同变量自动合并** | 哈希键的天然性质：同一明文多次出现 ⇒ **同一个别名**（不是多别名）。
+  不能退化成顺序号 —— 那会在日志/记忆里积起一堆指向同一密钥的名字 |
+| **S12** | ★ **不自动淘汰**，但可**主动**提交/删除 | 用户明确：不自动淘汰（跨轮/跨子 agent 随时要用）；
+  泄漏风险靠**主动删除**控制，不靠超时。自动淘汰错策略会导致“变量静默失效” |
+| **S6** | 关闭开关是**显式特权** | 能关掉它的人必须知道自己关掉的是什么（与本仓 `offload_enabled` 同一条纪律） |
+| **S7** | 替换后**仍要能干活** | 被替换掉的明文必须**可用别名引用**（否则任务直接坏掉）——这是 S1 与可用性的平衡点 |
+| **S8** | ★ **回填必须成对**（只拦不填 = 删除功能） | 用户明确：只拦截会让“绝大部分插件失去原本功能” |
+| **S9** | ★ **插件无感知** | 替换发生在路由到插件的**之前**；插件代码不改、不可分辨、无法绕过 |
+| **S10** | ★ **变量系统全局唯一** | 主/子/驻留子 agent **同一套**别名表。理由：`ProviderManager` 全进程只建一份（`bootstrap.go:249`），且共享才能跨 agent 协作。且**与权限正交** —— 变量共享 ≠ 授权共享 |
+
+> **S1 与 S7 不矛盾**：别名可**被引用**（用于命令填充），但**不可被读取**。
+> 读接口与用接口是两件事 —— 这正是前稿没分清的地方。
+
+---
+
+## 4. 需要改哪些地方（下沉清单）
+
+**总原则（用户 2026-10-14 拍板）**：安全模块 = **拦截 + 加密暂存 + 别名 + 回填**，
+**插件完全无感知**。因为**内核零 IO**（一切外部交互都从插件走），
+所以只需在**两根咽喉**上做替换即可覆盖全部。
+
+| # | 改动 | 位置 | 性质 |
+|---|---|---|---|
+| **C1** | **出向拦截**（→LLM）：包装 `Provider.Chat`，在 `CompletionRequest` 出网前扫到明文就换成 `@{别名}` + 加密暂存 | `internal/agent/api/`（装饰器） | 新增（核心） |
+| **C2** | ★ **入向回填**（→插件，toolcall）：`StageHost.ExecuteTool` 入口把 `args` 里的 `@{别名}` 换回明文 | `internal/agent/core/stages.go:140` | 新增（核心） |
+| **C3** | ★ **入向回填**（→插件，outputch）：`IOManager` 的设备 `Execute` 前把载荷里的 `@{别名}` 换回明文 | `internal/agent/io/channel.go` / `output.go:76` | 新增（核心） |
+| **C4** | **变量库**：★ **哈希键索引 + 落盘加密暫存**（`internal/security/`） | 新建 `internal/security/` | 新增 |
+| **C8** | ★ **供 agent 调用的提交/删除工具**（主动登记、主动删除） | 内核内置工具（`builtinToolOwner` 注册） | ✅ **已做**（`secret_submit/list/forget`）|
+| **C5** | **LLM 返回也要扫**：LLM 可能把明文编造/输出出来 ⇒ 返回内容同样过一遍 | ✅ **已做**：拦在 `a.context.Append` 咽喉处（非调用点） |
+| **C6** | **记忆写入前扫一次**：防明文被写进长期记忆 | ✅ **已做**：`Append`/`InsertByTimestamp` + `emitMemoryCandidate` |
+| **C7** | 插件的加密 shell / enc_* 工具族**大幅删减**：不再自带加密库与别名表 | commondev 插件 | ✅ **已做**（比原计划**更保守**，见 §5.4）|
+
+> **C2 + C3 是“插件无感知”的全部机制保证**：
+> 插件代码**一行不改**，也无法分辨自己拿到的是明文还是被替换过的。
+> 无需给 SDK 加任何参数 ⇒ **不破接口兼容**（本仓“只增不减”）。
+>
+> **C1 是对用户“两个终端工具需联动”那条要求的直接回答**：
+> 不必改 `terminal_*` / `cmd_run` 这两个内置插件 —— 它们的**输出**最终进 `f.Msgs`
+> （被 C1 截），它们的**参数**走 `ExecuteTool`（被 C2 填），双向都覆盖。
+
+---
+
+## 5. 待办与未决
+
+| # | 事项 | 说明 |
+|---|---|---|
+| **T1** | ~~修 `splitKeyValue` 对 `assigned_secret` 的键名丢失~~ | ✅ **已修**（插件侧；迁内核时可一并搬）。根因：键名后常带空格（`api_key = "..."`），旧判据把“含空格”当成“不像键名”就放弃拆分 ⇒ 整段被当 secret。已配变异验证 |
+| **T9** | **不自动淘汰的规模上限** | 落盘文件只增不减（除非人主动删）。需定一个**可观测**的降级策略（如超 N 条时**告警**，而不是静默删某条） |
+| **T10** | **提交工具的泄露面** | “主动提交”要把明文交给内核 —— 与 `enc_store` 同问题（明文会进会话/日志）。
+  应优先支持 `${ENV}` / `@file:` 两条不明文入会话的路径 |
+| **T2** | 把前稿的 `intercept.go` / `encstore.go` 从插件**迁到内核** | 模式库可复用，别名/存储需重写为内核形态。★ **迁后本插件的 `enc_*` 工具族与加密 shell 应大幅删减**（用户：插件对安全机制无感知） |
+| **T3** | **密钥从哪来**（内核侧） | 内核是长驻进程；密钥须由部署方提供（systemd 环境变量）还是内核自持密钥文件？未定 |
+| **T4** | 变量**持久化与生命周期** | ✅ **已定**：落盘加密持久化（重启不丢）、**不自动淘汰**、可主动删（§2.4）。剩余：落盘位置与 masterKey 来源（同 T3） |
+| **T5** | 压缩（compaction）对别名的影响 | 摘要可能把 `@{sec_1}` 当成普通文本；压缩后别名是否仍有效？ |
+| **T6** | **明文在内存中的擦除** | Go 字符串不可变 ⇒ 只能擦可写副本。要定"努力擦除"还是"不承诺" |
+| **T7** | 替代方案评估 | 内核是否可能拿不到 secret（如 SSH 密钥文件）⇒ 也许该支持"引用外部文件、内核只持路径" |
+| **T8** | **入向回填的安全边界** | 回填后 agent 可把 `@{别名}` 写进**任意**命令参数 ⇒ 等于获得“在任意命令里用明文”的能力。这**正是必需的**（否则没法用密钥），但“能做什么”的边界因此回到**命令本身**。要定：要不要限制哪些工具允许触发回填？ |
+
+### 5.1 ★ 配置落盘加密 ［已完成 · 真机验证］
+
+**用户需求（2026-10-14）**：通用配置在数据库里全是明文；配置管理器应提供
+加密选项，并为插件暴露加密存储能力（密钥由内核统一管理）。
+
+#### 要解决的问题
+
+`config.db` 是 **0644 全局可读**的（同目录还有 WAL/SHM），而里面装着
+LLM API 密钥、WebUI 口令、插件凭据 —— 任何本机用户一条 sqlite3 查询
+就能拿到全部明文。
+
+#### 做法：在**存储边界**加密，读写接口不变
+
+```
+Set/Register/RegisterDef/seed → Seal → DB 里是 enc:v1:<base64>
+Get/Dump/ToConfig/GetString → Open → 调用方永远只看到明文
+```
+
+★ **关键取舍：读接口保持「返回明文」**。
+
+初稿曾想给 `Dump()` 返回掩码，但那会同时打断 `ToConfig()`
+（它靠 Dump 重建 LLMSource，含 api_key）与所有内部读取方 —— 而它们
+**本来就在可信边界内**。本需求防的是「静态文件泄漏」，不是「内部读取」。
+已配判据 `TestToConfigStillGetsRealAPIKey` 钉死这一点。
+
+#### 敏感判定（两种声明 + 键名兜底）
+
+| 途径 | 说明 |
+|---|---|
+| `ConfigDef.Secret == true` | ★ **SDK 里早就有这个字段，但从未实现** |
+| `ConfigDef.Type == "password"` | 旧写法，兼容保留 |
+| 键名模式 | 无 def 的插件键靠它兜底 |
+
+**键名匹配必须按「词段」而不是子串**：初版用 `strings.Contains(key,"token")`，
+把 `core.llm.max_tokens`（输出上限）与 `core.agent.context.max_target_tokens`
+（上下文预算）也加密了。真机跑出来才发现。现在改为切词后精确匹配，
+`max_tokens` 的末词段是 `tokens`（复数）⇒ 不命中。
+
+#### 密钥：域隔离派生
+
+```
+subKey = HMAC-SHA256(masterKey, "homeagent/config-at-rest/v1")
+```
+
+同一把主密钥服务多类用途（变量别名 HMAC、配置 AES、未来审计签名…）。
+共用一把会在域之间产生攻击面（一处的输出变成另一处的合法输入），
+所以每类用途派生独立子密钥。判据 `TestDomainSeparation` 钉住它。
+
+密钥来源与安全模块一致：`HOMED_SECURITY_KEY` > `<dataDir>/security.key`（0600）。
+
+#### 为插件暴露的加密存储能力
+
+SDK 新增两个方法（`SettingsAPI`）：
+
+| 方法 | 语义 |
+|---|---|
+| `SetSecret(key, value)` | **强制加密**，不看键名（插件可能用 `blob`/`conn` 这类中性键名） |
+| `GetSecret(key)` | 读回（透明解密） |
+
+★ **无密钥时 `SetSecret` 拒绝写入**，不静默存明文 —— 插件以为存了密文
+而实际磁盘上是明文，是最危险的静默降级。
+
+#### 落点清单
+
+| # | 改动 | 位置 |
+|---|---|---|
+| **E1** | 密钥域派生 + 编解码器 | `internal/security/codec.go` |
+| **E2** | 敏感判定 + 迁移 + 加密写入 | `internal/config/secret.go` |
+| **E3** | 读路径透明解密（Get/Dump/GetString/listPrefix/PluginSettings） | `internal/config/registry.go` |
+| **E4** | ★ `Secret` 标志透传（**三处转换点都漏了它**） | `internal/sdk/settings_impl.go` |
+| **E5** | 显式加密 API（`SetSecret`/`GetSecret`） | registry + sdk + **SDK 接口** |
+| **E6** | ★ proc 桥：协议常量 + 3 处注册（路由/分发/能力表）+ 模板实现 | `internal/plugin/proc/`、`templates/proc_main.go.tmpl` |
+| **E7** | WebUI：密码框 + 显示/隐藏按钮 | `internal/plugins/webui/dashboard.js` |
+| **E8** | 启动装配 + 存量迁移 | `cmd/homed/main.go` |
+
+#### ☆ 踩到的两个真坑
+
+1. **`Secret` 字段从未生效的根因**：SDK 一直有 `Secret bool`，但内核侧
+   **三处**转换点（`RegisterDef`/`Defs`/`mapDefs`）全都漏了它。
+   插件声明了意图，前端拿到的 meta 里却没有 —— 于是敏感项被渲染成
+   普通文本框明文回显。已配判据 `TestSecretFlagReachesSettingsMeta`。
+
+2. **新增 proc method 要改 4 个地方**：协议常量、外层路由、内层分发、
+   能力表。我只改了分发，真机 e2e 立刻报 `未知 method: settings.setSecret`
+   —— 这正是「真机端到端不可省」的实例。
+
+3. **守卫判据本身有盲区**：`TestCapability_AllMethodsClassified` 号称
+   「本文件最重要的测试」，但它用手工维护的方法清单 —— 新方法不加进清单
+   就无人管（变异实验 V3 证实：删掉能力表条目，判据仍绿）。
+   已改为**从 protocol.go 源码正则提取**全部 method 常量，覆盖面自动跟上。
+
+#### 验证
+
+- `internal/config/secret_test.go` 17 条 + `internal/security/codec` 判据
+- `internal/plugin/proc/e2e_secret_test.go` —— **真实 hmapdev 模板编译的插件**
+  跑完整链路：插件读回明文(27B)、磁盘存密文(83B)
+- `internal/plugins/webui/secret_meta_test.go` 2 条（声明→meta、UI 明文/磁盘密文）
+- 变异 6 条全部咬住（含 V3 暴露并修复的守卫盲区）
+- 真机：3 条存量迁移、明文残留 0、`max_tokens` 未被误加密
+- 全量回归 `./internal/... ./cmd/... ./pkg/...` 零失败
+
+---
+
+### 5.2 前提验证（安全模块本体） ［已完成 · 全部通过］
+
+**结论：安全模块可以稳在 provider 层。** 两条前提均已实测：
+
+#### P1：所有出网均经 `Provider.Chat` / `ChatStream` ［已核］
+
+| 事实 | 依据 |
+|---|---|
+| `Provider` 是干净的两方法接口 | `internal/agent/api/provider.go:307`（`Chat` + `ChatStream` + `MaxContextTokens`） |
+| 所有调用点都用接口方法 | `process.go:138/155/191`、`spawn.go:184/321`、`modalfallback.go:347`、`provider.go:1140` |
+| 插件经 `s.LLM().Chat` 也回同一层 | `internal/sdk/llm_impl.go:48` → `l.mgr.Default()` |
+| 唯一一处内部直发 HTTP（`provider.go:446`） | 在 `LuaAdaptedProvider` **实现内部**，不是绕过 |
+| `lua/vm.go` 的 `CallTransformRequest` | 是适配器层的载荷改写（在 provider 内部调用），不是绕过 |
+
+#### P2：`ProviderManager.Register` 是**唯一入口** ［已核 · CodeGraph 交叉验证］
+
+装饰 `Register` 即覆盖全部取用路径（`Get` / `Default` / `OrderedProviders` / `ResolveForModel` 都从同一 map 取）。
+
+`NewLuaAdaptedProvider` 的全部调用者（CodeGraph 查得 **6 个**）：
+
+| 调用者 | 位置 | 是否经 `Register` |
+|---|---|---|
+| `initLLMProviders` | `cmd/homed/bootstrap.go:248` | ✅ 下一行就是 `providerMgr.Register` |
+| `runFailbackRecovery` | `cmd/homed/failback.go:28` | ✅ `Register("rescue", …)` |
+| `ReloadFromConfig` | `internal/sdk/llm_impl.go:115` | ✅ `l.mgr.Register` |
+| 其余 3 个 | 测试文件 | — |
+
+⇒ **无任何真实路径绕过 `Register`。**
+
+#### 已落地的验证判据
+
+`internal/agent/api/security_premise_test.go`（4 条，均配变异验证）：
+
+| 判据 | 验证什么 |
+|---|---|
+| `TestPremise_RegisterDecorateCoversAllAccessPaths` | 4 条取用路径都拿到装饰后实例 |
+| `TestPremise_DecoratorSeesEveryChat` | `Chat` / `ChatStream` 都经装饰器 |
+| `TestPremise_DecoratorCanRewriteMessages` | 装饰器**能改写**消息（不只是读） |
+| `TestPremise_StreamAlsoDecorated` | 流式也被覆盖 |
+
+变异实验（两个都咬住）：不包裹 ⇒ “装饰器应看到 1 次 Chat，实际 0”；
+只读不改 ⇒ “明文被原样透传，改写未生效”。
+
+> **方法论教训**：这一步最初我用 `grep` 逐个查，漏了 `sdk/llm.go` 等入口，
+> 也没发现 `lua/vm.go` 的变换链路。改用 **CodeGraph**（`codegraph_callers` / `codegraph_node`）
+> 后，它一次列出 `Chat` 的 **9 个调用者**与 `NewLuaAdaptedProvider` 的 **6 个调用者**，
+> 遗漏面直接归零。**查接口关系用 codegraph，不要用 grep 翻**。
+
+---
+
+### 5.3 ★ 持久化侧路的明文拦截（C5/C6） ［已完成 · 真机验证］
+
+### 发现的真实漏洞：出向拦截挡不住持久化
+
+`§4` 的 C5/C6 原本是「计划项」。实测把它们变成了**必须做** —— 因为发现了
+一条完整的泄漏侧路：
+
+出向拦截（provider 装饰器）只改 `f.Msgs` —— **要发出去的那一份**。
+但内核把同样内容**另存副本**送往持久化，它们不经过 provider：
+
+| 持久化字段 | 来源副本 | 是否被 provider 拦住 |
+|---|---|---|
+| `ContextEvent.Input` | `f.CleanInput`（用户输入原文） | ❌ |
+| `ContextEvent.Response` | `f.Response` | ❌ |
+| `ContextEvent.ToolResults` | `f.ToolResults` | ❌ |
+| `memory_candidate.payload` | 同上（走 `EmitOutput`，**不经 context**） | ❌ |
+
+后果：明文被 LLM 看到之前虽已换成别名，但**完整地写进了 `context.json`
+与长期记忆** —— 而记忆跨会话保留、每轮被召回。泄漏面比重放一次大得多。
+
+### 修法：拦在**咽喉**，不拦在调用点
+
+写 context 的地方有 **5 处**（`task.go` ×3、`toolcall.go` ×1，加插入变体），
+`memory_candidate` 另走一条。逐个补必漏 —— 事实上第一版正是只补了
+`turnEvt`，而漏掉了 `f.CleanInput`（判据实测确认泄漏仍在）。
+
+最终落点：
+
+| 咽喉 | 覆盖 | 文件 |
+|---|---|---|
+| `RelevanceContext.Append` | 全部追加写入 | `context.go` |
+| `RelevanceContext.InsertByTimestamp` | 按时间插入（另一入口） | `context.go` |
+| `Agent.emitMemoryCandidate` | 记忆候选（不经 context） | `distill.go` |
+| 共用实现 | `scrubEventSecrets` / `scrubMemoryCandidate` | `memory_scrub.go` |
+
+清除字段：`Input` / `Response` / `ToolResults[].Output` /
+`Blocks[].Text`（**仅文本块**；图像/视频/音频的 `Data` 是二进制负载，
+正则扫它既无意义又会损坏数据）。
+
+### ☆ 一处必须记录的脆弱性
+
+实测发现：`Append` 的 scrub 会**连带改掉** `f.ToolResults` —— 因为
+`turnEvt.ToolResults = f.ToolResults` 是值切片，共享底层数组。
+于是「去掉 `scrubMemoryCandidate`」的变异**不会被端到端判据发现**。
+
+这是脆弱设计（隐式依赖别名）。所以：
+
+1. `scrubMemoryCandidate` **显式保留**，不指望上游顺手改了；
+2. 增加判据 `TestEmitMemoryCandidateScrubsPayload`，走**真实入口**
+   `a.emitMemoryCandidate` 而不是直接调底层函数 —— 初版直接调底层，
+   于是「去掉入口处的调用」这个变异**不报红**（判据测错了层次）。
+
+> 通用教训：**判据必须走真实入口**。测底层函数只能证明「函数对」，
+> 证明不了「入口调了它」。本次变异实验连续暴露了三次同类错误
+> （M2 判据漏测 `Alias()`、C6-M2 漏测 `memory_candidate`、M-B 测错层次）。
+
+### 与 `f.Msgs` 原地改写的**刻意不对称**
+
+| 路径 | 语义 | 为何 |
+|---|---|---|
+| `f.Msgs` | **原地改写** | 它就是要发出去的那份；改掉后明文永久离开上下文 |
+| `f.ToolResults` | **拷贝后改写** | 同一轮里还被其它代码读（诊断、状态面），不能就地改 |
+
+这个不对称是刻意的，判据 `TestOutboundScrubIsInPlaceByDesign` 与
+`TestToolResultsScrubDoesNotMutateSource` 分别钉住，免得后来者「统一」成一种写法。
+
+### 验证
+
+- `internal/agent/core/persist_leak_test.go` 4 条（输入侧 / 回复侧 / 记忆块 / 记忆候选入口）
+- `internal/agent/core/toolresult_scrub_test.go` 3 条（含**真实调度循环**的 e2e）
+- `internal/agent/core/inplace_scrub_test.go` 1 条（原地改写语义）
+- 变异 4 条（含 2 次修好的判据盲区）
+- 全量回归零失败
+
+---
+
+### 5.4 ★ C7：插件加密层的删减（比原计划更保守） ［已完成］
+
+#### 先验证前提，再动代码
+
+C7 原计划是「插件不再自带加密库与别名表」。但「删掉插件那套，内核能顶上吗」
+是个**必须先验的断言** —— 不成立的话就是削功能而非去冗余。验了三条：
+
+| 判据 | 结论 |
+|---|---|
+| `TestKernelFillCoversBuiltinToolsToo` | 内核回填覆盖**所有**工具名（含内置 `cmd_run`） ⇒ 插件的**填充**功能冗余 |
+| `TestKernelFillHappensBeforePluginHandler` | 内核在 handler **之前**回填 ⇒ 插件自己的别名表对内核别名是**死代码** |
+| `TestKernelAndPluginAliasSyntaxDoNotCollide` | 内核只吃 `[A-Za-z0-9_]`，插件的 `@{gitea-local}`（含连字符）不受影响 |
+
+#### 删了什么（691 行）
+
+| 删除 | 理由 |
+|---|---|
+| `intercept.go` / `intercept_stage.go` / `intercept_test.go`（**691 行**） | 插件版拦截**覆盖面严格小于**内核版：它只能看 `RawMessage`/`ToolResults`，内核还能覆盖 `Input`/`Response`/`Blocks`/`memory_candidate` |
+| `enc_intercepts` 工具 + `Ledger.Interceptions` | 拦截记录由内核拥有（内核日志 + `secret_list` 的命中计数） |
+| `intercept_enabled` 配置项 | 全局开关是 `core.security.enabled`（在 WebUI 设置页）。插件留一个同名开关会让人以为它能控制内核行为 —— 那是误导 |
+
+★ **两套并存的真实害处**：内核先回填，插件再扫一遍时明文已是别名 ⇒ 纯空转，
+而且可能把别名**二次改写**。
+
+#### ☆ 但有三样**不能删**（原计划漏判的）
+
+| 保留 | 为什么内核顶不上 |
+|---|---|
+| `enc_shell` 的 **argv 保护**（脚本走 stdin） | 内核 `cmd_run` 是 `sh -c "<整条命令>"` ⇒ 回填后的明文**会进 argv**，本机任何进程 `/proc/<pid>/cmdline` 都能读到。实测确认 |
+| `enc_shell` 的 **输出脱敏** | 防命令意外回显凭据（如 `git remote -v` 带出 token） |
+| `enc_store` 的 **`${ENV}` / `@file:` 来源** | 这两条路径**明文从不进会话** —— 正是文档 T10 要求的更安全形态，而内核 `secret_submit` 目前只接受直传明文 |
+
+⇒ **C7 的最终形态是「互补」而非「替代」**：
+插件保留**执行侧**保护（argv / 脱敏）与**安全来源**（`${ENV}`/`@file:`），
+内核负责**拦截 / 存储 / 回填 / 记忆侧路**。
+
+#### 给内核的后续项（进 §6）
+
+`secret_submit` 应支持 `${ENV_NAME}` 与 `@file:/path` 两种来源 ——
+把「明文不进会话」的能力从插件上移到内核（T10）。
+
+---
+
+### 5.5 ★ 变量库统一（插件不再自建加密存储） ［已完成］
+
+**用户指出的问题（2026-10-14）**：
+
+> 不对，你写了两遍变量，为什么不直接让安全模块暴露相关接口让插件使用？
+
+**确认属实。** 插件自带了一整套与内核**完全重复**的加密存储：
+
+| | 内核 `internal/security.Store` | 插件 `unifiedSecretFile` |
+|---|---|---|
+| 落盘 | `secrets.json` | `secrets.json` |
+| 加密 | AES-256-GCM | AES-256-GCM |
+| 别名 | HMAC 派生（自动合并）| 用户指定 |
+| 引用 | `@{sec_xxx}` | `@{name}` |
+
+★ 重复的真正代价不是代码量，而是**两套库互不可见**：
+内核拦截时登记的变量插件看不到、插件登记的拦截又不认识，
+同一凭据可能在两处各存一份而使用者不知哪个权威。
+
+#### 做法：SDK 新增 `SecretsAPI`
+
+```
+Store(value, note) → alias      值交给内核，返回别名
+List()                          元信息（**不含明文**）
+Forget(alias)                   删除
+Fill(text) → out, n, aliases    把 @{别名} 换成明文
+Encrypt/Decrypt                 给插件自己的配置文件用（密钥由内核管）
+Available()                     变量库是否可用
+```
+
+**去重后的分工**：
+
+| 谁 | 存什么 |
+|---|---|
+| 内核 | **值**（加密）、派生别名、调用插件前回填 |
+| 插件 | 「可读名 → 内核别名」**映射**（不含值）、来源解析、argv 保护 |
+
+★ **为什么插件还需要一层映射**：内核别名是 HMAC 派生的
+（`sec_0cb468e2…`），这是「同明文自动合并」的前提（S11），**不能改成用户自选**。
+但人需要 `@{gitea-local}` 这种能读懂的名字 ⇒ 插件存一层名字映射。
+**映射里只有名字，没有值** —— 它泄了也没用。
+
+#### ☆ 安全性论证：为什么暴露 `Fill` 不破 S1
+
+S1 说「不提供取回明文的接口」，理由是一旦 LLM 能取回，它就能把明文写回上下文。
+那插件为什么可以拿明文？**因为边界不在插件侧**：
+
+1. 内核在**插件 handler 之前**就把工具参数里的 `@{别名}` 填好了
+   （`StageHost.ExecuteTool` → `security.FillMap`）—— 插件**本来就能**
+   从 args 读到明文，这是设计使然。
+2. 明文若被插件**返回**，会被两处拦回别名（`ContextEvent` scrub + provider 装饰器）。
+
+两条都有判据钉住（`TestPremise_PluginReturnedPlaintext*`：插件故意回吐明文，
+验证 context 侧与 provider 侧都拦得住）。所以：
+
+> **暴露 `Fill` 不是"开了一个口子"，而是把本来就存在的能力
+> 从各插件自己实现改为统一接口。**
+
+⚠️ 但**绝不能**暴露 `Reveal(alias) -> 明文` 这样的按名字直取接口 ——
+那会让插件（以及操纵它的 LLM）枚举别名并逐个取值。本接口刻意没有这样的方法。
+
+#### ☆☆ 实测踩到的坑
+
+**`Available()` 不能用 `List` 推断。** 初版让模板的 `procSecrets.Available()`
+调 `secrets.list`，看 RPC 是否成功。但**未启用时 List 返回空列表（不报错）**，
+于是"库是空的"与"库不存在"在 RPC 层长得一样 ⇒ `Available()` 误判为 true，
+接着 `Store` 才失败。错误信息于是变成"存储失败"而非"能力不可用"，
+**排查方向完全错**。修法：加 `secrets.available` 专门回答这个问题。
+有判据 + 变异钉住。
+
+**`go:embed` 第三次咬人。** `hmapdev` 用 `//go:embed` 把模板编进二进制。
+我改了 `templates/proc_main.go.tmpl` 源码，但跑的是**旧二进制**，
+于是生成出的 shim 缺方法、报 `missing method GetSecret` —— 而报错指向
+生成文件，看不出真因是"模板没重新编译进二进制"。
+修法：`go build ./tools/hmapdev/` 重建并安装。
+
+**两处校验器字符集不一致。** 引用正则 `credRefPattern` 允许 `.`，
+而别名校验器 `validName` 不允许 ⇒ 「能被引用却存不进去」。
+修法：secret 别名用自己的校验器（`validSecretName`），
+**不混用**项目/通道名的校验器 —— 两者是两个命名空间。
+
+#### 验证
+
+`internal/plugin/proc/e2e_secrets_test.go` 3 条（**真实模板**编译的插件跑全链路）；
+`internal/agent/core/leakback_test.go` 2 条（插件回吐明文被拦）；
+`internal/security/alias_shape_test.go` 1 条（别名是派生值、不能自选）；
+插件 `encstore_test.go` 重写为 7 条（含「值只存一处」不变量）。
+三层零失败、`-race` 通过、`hmapdev build` 成功。
+
+---
+
+### 5.6 ★ 拦截范围盘点（「到底拦什么」） ［实测 · 已固化判据］
+
+判据：`internal/security/survey_test.go`（会拦 / 刻意不拦，两个清单）。
+
+#### 会拦（→ 换成 `@{sec_xxx}`）
+
+| 类别 | 形态 |
+|---|---|
+| GitHub token | `ghp_`/`gho_`/`ghu_`/`ghs_`/`ghr_` + 36 位 |
+| GitHub fine-grained | `github_pat_` + 60 位 |
+| GitLab | `glpat-` + 20 位 |
+| OpenAI | `sk-`（含 `sk-proj-`）+ 20 位 |
+| Anthropic | `sk-ant-` + 20 位 |
+| AWS 访问密钥 | `AKIA`/`ASIA` + 16 位大写 |
+| Slack | `xox[baprs]-` |
+| Bearer 头 | `Bearer ` + 30 位以上 |
+| **私钥块（7 类）** | `-----BEGIN PRIVATE KEY-----`（PKCS#8）｜`RSA PRIVATE KEY`｜`DSA`/`EC PRIVATE KEY`｜**`OPENSSH PRIVATE KEY`**（ssh-keygen 现代默认）｜`ENCRYPTED PRIVATE KEY`｜**`PGP PRIVATE KEY BLOCK`**｜**`SSH2 ENCRYPTED PRIVATE KEY`** |
+| 赋值语句 | 键名含 `api_key`/`access_token`/`auth_token`/`secret_key`/`client_secret`/`password`/`passwd`，**分隔符 `=` 或 `:` 都可**，值 16 位以上 |
+
+#### 刻意**不拦**（每条都有理由 —— 边界比能力更重要）
+
+| 不拦 | 原因 |
+|---|---|
+| **40 位 hex（Gitea token 形态）** | 与 git commit SHA **形态完全相同** ⇒ 拦它会误伤每个 commit id（S4） |
+| 裸 32 位十六进制 | 与 UUID / 会话 id / 哈希撞车，太泛 |
+| JWT | 形态宽泛，误伤风险高于收益（带 `Bearer ` 前缀时那条会拦） |
+| 密码短语 / 中文口令 | 无固定字符集，无法与正常文本区分 |
+| PIN / 短口令 | 太短，任何数字都会撞 |
+| 手机号 / 身份证 | PII 不是本模块目标，且误伤面极大 |
+| **URL 里的密码**（`https://user:pass@host`） | ⚠️ **已知缺口**，需专门规则，当前未覆盖 |
+| SSH 私钥**文件路径**（`.ssh/id_rsa`） | 拦路径不拦内容 —— 文件内容被读出时会命中私钥块规则 |
+| **SSH 公钥**（`ssh-ed25519 AAAA…`、`ssh-rsa AAAA…`） | 公钥**不是秘密**（可公开）。拦它会让正常运维操作坏掉 |
+| `authorized_keys` / `~/.ssh/config` / `known_hosts` | 不含密钥本体（config 只有路径；known_hosts 与正常 hostname 无区别） |
+| `SSH_AUTH_SOCK` | 只是 ssh-agent 的 socket 路径，不含密钥 |
+
+#### ☆ SSH / 密钥专项：实测补上两个漏报
+
+用**本机真实密钥**（`~/.ssh/id_rsa`、`id_ed25519`）+ 各类 PEM 头验证时发现，
+初版正则漏了 **两类真实存在的私钥格式**：
+
+| 漏掉的 | 为什么 |
+|---|---|
+| `-----BEGIN PGP PRIVATE KEY BLOCK-----` | 尾部是 `KEY BLOCK`，不是 `PRIVATE KEY` |
+| `-----BEGIN SSH2 ENCRYPTED PRIVATE KEY-----` | 头部是 `SSH2 ENCRYPTED PRIVATE KEY` |
+
+**根因**：初版正则在 END 侧**硬写**了 `PRIVATE KEY`：
+```
+-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]{64,}?-----END [A-Z ]*PRIVATE KEY-----
+                                                            ^^^^^^^^^^^ 写死了
+```
+而真实密钥的尾部词因格式而异。修法：两侧都用 `[A-Z0-9 ]*PRIVATE KEY[A-Z ]*`。
+
+**长度下界 64 的用意**（防误伤）：真实私钥体远超 64 字节，而
+「文档里只引用头尾两行做说明」的情形中间没有内容 ⇒ 不会被拦。
+有判据双向钉住（长体必拦 / 短引用不拦）。
+
+#### ☆ 盘点本身抓到一个真实漏报
+
+写这份盘点时发现 `password: "hunter2hunter2hunter2"`（**冒号**形态）**没被拦**。
+
+**根因是我加 prefilter 时引入的**：`assigned_secret` 的正则分隔符有
+两个备选（`:` 与 `=`），而 prefilter 只写了 `"="` ⇒ 冒号形态被
+**静默挡住**。
+
+更值得记的是**为什么既有判据没发现**：样本恰好都用了 `=`，
+测试全绿 —— 判据覆盖了"能用的形态"，漏了"另一种同样合法的形态"。
+
+修法：
+1. `Prefilter` 支持**多候选**（`"a|b"`，任一命中即放行）
+2. 新增 `TestPrefilterCoversAllAlternatives`：**逐形态**验证
+   「正则支持的每种写法，prefilter 都必须放行」
+
+> 教训：**盘点"什么没被拦"比盘点"什么被拦了"更能发现问题**。
+> 正向清单告诉你能力边界，负向清单才暴露洞。
+
+---
+
+## 6. 待办与未决（续）
+
+> 上面 §5 的 T1–T10 是**安全模块本体**的遗留项；
+> 本节记录**配置加密**（§5.2）落地后新暴露的项。
+
+| # | 事项 | 说明 |
+|---|---|---|
+| **E-1** | 密钥轮换 | ✅ **已完成**（2026-10-15）：`security.keyring`（0600）持久化「当前钥 + 历史只读钥」；Store 支持 `RotateKey`（**已有别名不变**、密文重加密落盘、旧钥留在环里）；Codec 支持 `InitConfigCodecWithOldKeys` + `Rekey`/`NeedsRekey`；config 侧 `RekeySecrets` 收口。7 条判据 + 4 条变异 |
+| **E-2** | 压缩/备份工具的兼容 | ✅ **已完成**（2026-10-15）：`deploy-plan.sh backup` 打印密钥位置与「密钥须与数据分开存放」提示；内核启动时 `AuditSecrets` 审计密文可读性，发现不可解即告警并给出修复动作（3 条判据 + 2 条变异） |
+| **E-3** | WebUI 的「密钥可见范围」 | ✅ **已完成**（2026-10-15）：设置列表默认以占位符屏蔽敏感值；新增单键 `/api/v1/settings/reveal?key=`，核心/当前 WebUI 插件可显式揭示，其他插件一律 403；揭示动作留痕。2 条判据 + 2 条变异 |
+| **E-4** | `HOMED_SECURITY_KEY` 生产方式 | ✅ **已完成**（2026-10-15）：优先用 systemd `LoadCredential`（tmpfs、0400、**不进 environ**），降级 env，再降级磁盘文件。unit 已配 `Type=exec`。4 条判据 + 2 条变异，真实 systemd 实测 |
+
+---
+
+## 7. 与既有文档的关系
+
+| 文档 | 关系 |
+|---|---|
+| `commondev-agent-runtime-design.md` | 前稿的插件侧拦截（`§2.7` 之后）**降级为卫生措施**；安全责任移到本文 |
+| `resident-subagent-design.md` | 驻留子的 `KernelSource` L4 模型是**另一个**安全机制（权限隔离），与本文正交 |
+| `kernel-modularization-design.md` | **★ 本文 §3 的装配点约束是该文档 §2.3「Phase 0」的实例**。安全模块必须在任何读 `core.llm.*` 的操作之前装配——实测踩过：装配晚了只会打一行 warning，然后 key 变空一路走到 401（症状指向"key 配错"，实际是顺序问题）。该文档把这类约束从"注释"变成"机器校验" |
+| 本仓 `internal/plugin/proc/corehandler.go:279` 的 L4 夹取 | 同属"内核不信插件自报"的**同一设计哲学**，可参考其实现风格 |
+
+---
+
+## 8. 实测教训：安全模块的装配顺序（2026-10-16）
+
+> 这一条加到本文，因为它**直接暴露了"顺序只写在注释里"的危险**。
+
+**故障**：安全模块装配晚于 `cfgReg.SetLLMSnapshotFile()`／`cfgReg.ToConfig()`，
+而这两者启动即读 `core.llm.*`（需主密钥解密）。
+
+**后果链**：
+
+```
+密钥未装配 → 解密失败（只打一行 warning）→ key 变空串
+→ initLLMProviders 拿到空 key → 所有 LLM 调用 401 invalid api key
+```
+
+**为何难查**：401 看起来像"key 配错了"。而实际上：
+- key 值在库里是**对的**
+- 直连上游 llmsproxy **HTTP 200**
+- 只有内核 agent 401
+
+⇒ 查 key 值、改 key、重配 provider **全部无效**，因为问题是**启动顺序**。
+
+**修法**：把整个安全块前移到*任何*读 `core.llm.*` 的操作之前，并加**结构性判据**
+（`cmd/homed/bootstrap_order_test.go`，断言真实的相对行号）。
+
+**★ 一个中途犯的错（值得记住）**：修复第一版只把安全块移到 `ToConfig()` 之前，
+**漏了 `SetLLMSnapshotFile()` 也在它之前读密文** ⇒ 判据变绿而线上照旧报错。
+教训：顺序类判据**必须覆盖所有读取点**，不能只盯一个。
+
+完整设计见 `kernel-modularization-design.md` §1.2 与 §2.3。
+
+---
+
+## 8. 给接手者的三条提醒
+
+1. **安全模块的位置决定它是不是安全**。初稿以为"唯一出网点"在 task 层，
+   实测扫出 **7 处**构造请求 —— 放在 task 层会漏 4 处。
+   教训：**落点要靠扫仓实测确定，不能靠读一处代码推断**。
+2. **"能引用"与"能读取"必须分开**。前者是可用性所需，后者是泄露。
+   把它们混在一起，就是前稿最大的设计错误。
+3. **模式库宁漏勿误伤**。误报会搞坏正常任务，而任务坏了人会来查——那时代价远大于漏报一次。
diff --git a/docs/zh/resident-subagent-design.md b/docs/zh/resident-subagent-design.md
index 9964dd96..fb82f431 100644
--- a/docs/zh/resident-subagent-design.md
+++ b/docs/zh/resident-subagent-design.md
@@ -678,3 +678,24 @@ go test -count=1 ./... && go test -race -count=1 ./internal/agent/... ./internal
 - 本设计在 `feature/input-semantics` 之后的特性分支上开发，完成后合回 `main`。
 - 若需要动公开 SDK（例如新增 `agent_*` 控制面原语、通道授权字段），按"**只增不减、签名不改**"
   追加，并按 `docs/git-branching.md` §八 的接线清单同步（含 hmapdev 模板）与 SDK 仓版本（§七）。
+
+---
+
+## 18. 与 `kernel-modularization-design.md` 的关系
+
+本文 §4.1 的 **inputch 共享总线**（父与驻留子共用同一份 `ChannelRegistry`）是
+`kernel-modularization-design.md` §5 引用的"运行期共享总线的**既有先例**"：
+
+| | 本文的 inputch 共享总线 | 该文的启动期依赖声明 |
+|---|---|---|
+| 时机 | **运行期**（消息路由、按 Owner 投递） | **启动期**（模块装配顺序） |
+| 机制 | 共享登记表 + 惰性查找 | `Requires`/`Provides` + 拓扑排序 |
+| 失败语义 | 找不到 owner ⇒ 兜底给根并留痕（**不吞输入**） | 缺依赖 ⇒ **拒绝启动** |
+
+**★ 两者不可互相替代**：inputch 总线解决的是"运行期谁处理这条消息"，
+它对"启动顺序"没有任何保证；而启动期需要的是**拓扑确定性**，
+不是"事件到达时再决定"（见该文 §2.2 的反对理由）。
+
+**实测关联**（2026-10-16）：驻留子被通道插件的用户权限模型误拦，
+修法是在工具调用帧上加 `comefrom` 标识（内核侧 `internal/agent/core/comefrom.go`）。
+这**不是**装配顺序问题，而是**运行期身份传递**问题——正好印证上表的区分。
diff --git a/internal/agent/api/codec_cgo.go b/internal/agent/api/codec_cgo.go
index f0908ce5..92892b1f 100644
--- 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) }
diff --git a/internal/agent/api/codec_chunkfast_bench_test.go b/internal/agent/api/codec_chunkfast_bench_test.go
index 3443ca29..27a0d02f 100644
--- 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" +
diff --git a/internal/agent/api/codec_chunkfast_c.go b/internal/agent/api/codec_chunkfast_c.go
index c7813868..812e51af 100644
--- 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
diff --git a/internal/agent/api/codec_chunkfast_golden_test.go b/internal/agent/api/codec_chunkfast_golden_test.go
index 119338ad..75a2ea42 100644
--- 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:
diff --git a/internal/agent/api/codec_estimate_calib_test.go b/internal/agent/api/codec_estimate_calib_test.go
index 9611ba1c..3c842c80 100644
--- 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)
diff --git a/internal/agent/api/codec_golden_test.go b/internal/agent/api/codec_golden_test.go
index ca6bbc89..e66255d1 100644
--- 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) {
 		}
 	}
 }
-
diff --git a/internal/agent/api/codec_jsongolden_test.go b/internal/agent/api/codec_jsongolden_test.go
index 6306d359..92b9f45c 100644
--- 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 {
diff --git a/internal/agent/api/codec_jsonscan_cgo.go b/internal/agent/api/codec_jsonscan_cgo.go
index fbaedd60..c8adf0f0 100644
--- 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
diff --git a/internal/agent/api/codec_pure.go b/internal/agent/api/codec_pure.go
index 2755c546..6e20ebbb 100644
--- 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 {
diff --git a/internal/agent/api/codec_streamchunk_c.go b/internal/agent/api/codec_streamchunk_c.go
index ed065291..4afb5525 100644
--- 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
 }
-
-
diff --git a/internal/agent/api/provider.go b/internal/agent/api/provider.go
index 0b207312..c87dd49f 100644
--- 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
diff --git a/internal/agent/api/provider_error_class_test.go b/internal/agent/api/provider_error_class_test.go
index 2a470f28..05726cf8 100644
--- 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)
 	}
 	// 若有人把顺序改成「先查特征词」，上面这行就会失败 —— 即本测试能捕获该回归。
-}
\ No newline at end of file
+}
diff --git a/internal/agent/api/provider_security.go b/internal/agent/api/provider_security.go
new file mode 100644
index 00000000..26aff1b0
--- /dev/null
+++ 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)
+}
diff --git a/internal/agent/api/security_premise_test.go b/internal/agent/api/security_premise_test.go
new file mode 100644
index 00000000..01bb745e
--- /dev/null
+++ 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 }
diff --git a/internal/agent/api/security_wiring_test.go b/internal/agent/api/security_wiring_test.go
new file mode 100644
index 00000000..04b4e588
--- /dev/null
+++ 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 会漏掉）")
+	}
+}
diff --git a/internal/agent/core/agent.go b/internal/agent/core/agent.go
index ed8272e3..54b1c878 100644
--- a/internal/agent/core/agent.go
+++ b/internal/agent/core/agent.go
@@ -258,10 +258,10 @@ type AgentConfig struct {
 	Indexer     *memory.Indexer
 	Tracker     *tracker.Tracker
 
-	DocStore        *document.Store
-	Knowledge       *knowledge.Store
-	SocialStore     *social.SocialStore
-	TextMemory      *text.Memory
+	DocStore    *document.Store
+	Knowledge   *knowledge.Store
+	SocialStore *social.SocialStore
+	TextMemory  *text.Memory
 	// 媒体存储句柄已随 CAS 淘汰（块自带负载，见 plan.md）。
 	MultimodalSpace vector.MultimodalEmbedder
 	// EmbeddingProvider / EmbeddingError 是向量空间的配置身份与打开失败原因，
@@ -393,27 +393,27 @@ func New(cfg AgentConfig) *Agent {
 	}
 
 	a := &Agent{
-		id:                cfg.ID,
-		startTime:         time.Now(),
-		provider:          cfg.Provider,
-		providerManager:   cfg.ProviderManager,
-		io:                cfg.IO,
-		memory:            cfg.Memory,
-		graph:             graphMemoryOf(cfg),
-		kernelSource:      cfg.KernelSource,
-		parentID:          cfg.ParentID,
-		taskPrompt:        cfg.TaskPrompt,
-		dataDir:           cfg.DataDir,
-		indexer:           cfg.Indexer,
-		tracker:           cfg.Tracker,
-		context:           rc,
-		systemPrompt:      cfg.SystemPrompt,
-		ctx:               ctx,
-		cancel:            cancel,
-		docStore:          cfg.DocStore,
-		knowledge:         cfg.Knowledge,
-		social:            cfg.SocialStore,
-		textMem:           cfg.TextMemory,
+		id:              cfg.ID,
+		startTime:       time.Now(),
+		provider:        cfg.Provider,
+		providerManager: cfg.ProviderManager,
+		io:              cfg.IO,
+		memory:          cfg.Memory,
+		graph:           graphMemoryOf(cfg),
+		kernelSource:    cfg.KernelSource,
+		parentID:        cfg.ParentID,
+		taskPrompt:      cfg.TaskPrompt,
+		dataDir:         cfg.DataDir,
+		indexer:         cfg.Indexer,
+		tracker:         cfg.Tracker,
+		context:         rc,
+		systemPrompt:    cfg.SystemPrompt,
+		ctx:             ctx,
+		cancel:          cancel,
+		docStore:        cfg.DocStore,
+		knowledge:       cfg.Knowledge,
+		social:          cfg.SocialStore,
+		textMem:         cfg.TextMemory,
 		// mediaStore 已随 CAS 淘汰：块自带负载。知识层的媒体也已自带字节
 		// （见 knowledge 的媒体侧车），不再需要外部 getter/putter 接线。
 		personality:       cfg.Personality,
diff --git a/internal/agent/core/comefrom.go b/internal/agent/core/comefrom.go
new file mode 100644
index 00000000..05cb3b36
--- /dev/null
+++ b/internal/agent/core/comefrom.go
@@ -0,0 +1,96 @@
+package core
+
+// 工具调用帧的**来源标识**（`comefrom`）：让插件能精确判定
+// "这次工具调用是谁发起的"，而不是只看"输入来自哪个通道"。
+//
+// ## 为什么必须加这个（真实故障，2026-10-16 现场实证）
+//
+// 现象：驻留子 `dev-br-jianf-NextAgent-fix_abs-path` 自报 running 但**零产出**，
+// 那一轮所有工具被权限策略挡下。它自己的处理表原文：
+//
+//	本轮所有需要的工具都被权限策略挡下了，实测被拒的有：
+//	- cmd_run —— 无法进入工作目录、无法看 git 状态
+//
+// 日志实证（同一时段，09:21:25~09:21:40）：
+//
+//	[agent] executing tool: cmd_run (plugin=cmd)
+//	[proc] qq stage before_toolcall 改写了 1 个字段   ← 插件写入了拒绝响应
+//	[agent] executing tool: files_ls ...
+//	[proc] qq stage before_toolcall 改写了 1 个字段
+//	（而同一时段父 main 的工具调用**有 result**，驻留子的**零 result**）
+//
+// ## 根因
+//
+// 通道插件的权限门是 `StageScopeGlobal` —— 它对**所有 agent** 的每一轮都生效。
+// 而它手里只有"输入来源"（`Extra["input_source"]`），**没有"执行者是谁"**：
+//
+//	· 父：输入来自 qq ⇒ 按那位 QQ 用户判权限 ✅ 正确
+//	· 驻留子：输入**继承自父**（QQ 来源），但执行者**不是那位用户**
+//	  ⇒ 插件仍按"那个 QQ 用户"判 ⇒ 开发工具不在白名单 ⇒ 全被拒 ❌
+//
+// 关键在于：**用户请求已经过了门**（父按真实身份判定过），驻留子做的是
+// 父自己的内部委派决定。对已经准入的工作再做一次"用户白名单"检查，
+// 既拦掉了合法工作，又不产生任何安全增益（同一次请求，父已判定）。
+//
+// ## 契约（插件侧读法）
+//
+//	comefrom == "user"    该调用代表**用户请求**在系统边界上发起 ⇒ 走用户权限模型
+//	comefrom == "internal" 该调用是 agent 体系内部的（委派/转投/自主续跑）
+//	                       ⇒ 不套"用户白名单"；是否放行由插件按自身策略决定
+//
+// 缺省（键不存在）时插件应**按旧行为**处理（= "user" 语义）：
+// 这条是为了不破坏已发布的插件 —— 它们不认识这个键，行为必须逐字不变。
+//
+// ## 为什么放 Extra 而不是给 StageContext 加具名字段
+//
+// `Extra` 已有**通用袋**（proc 桥的 `fExtraBag`）能跨进程/跨 stage 往返
+// （见 internal/plugin/proc/shm.go 的注释，那正是为"插件自建键"加的）。
+// 走 Extra 不需要改 SDK 结构体、不需要动 shm 的具名字段表，
+// 且插件侧 `ctx.Extra["comefrom"]` 与既有 `input_source` 读法一致。
+//
+// ★ 一旦某天需要它**强类型**（编译期保证），再提升为具名字段；
+// 现在 Extra 是成本最低且与既有惯例一致的选择。
+const extraKeyComeFrom = "comefrom"
+
+// comefrom 的两个取值。
+const (
+	// comeFromUser：用户请求在边界上发起（默认语义）。
+	comeFromUser = "user"
+	// comeFromInternal：agent 体系内部发起（委派、转投、自主续跑）。
+	comeFromInternal = "internal"
+)
+
+// stampComeFrom 把来源标识写进帧的 Extra（幂等；不覆盖已有值）。
+//
+// 不覆盖是有意的：更内层（知道更准）的调用点先写了就以它为准；
+// 外层只在"没人标过"时补一个保守值。
+func stampComeFrom(extra map[string]interface{}, v string) {
+	if extra == nil {
+		return
+	}
+	if _, exists := extra[extraKeyComeFrom]; exists {
+		return
+	}
+	extra[extraKeyComeFrom] = v
+}
+
+// comefromForAgent 由 agent 的层级身份推导来源标识。
+//
+// 规则（就这么简单，不需要更多分支）：
+//
+//	驻留子（有 parentID）⇒ internal   它不是用户请求的边界，是父的委派体
+//	根 agent（无 parentID）⇒ user     它才是用户请求的落点
+//
+// 为什么不去看 `input_source`：来源通道说明"消息从哪来"，不说明"谁在执行"。
+// 父处理 QQ 消息时来源是 qq（user）；把这条工作转投给驻留子后，
+// 驻留子的来源标签**仍是 qq**（转投刻意保留原事件），但执行者变了。
+// 只看来源必然判错 —— 这正是本缺陷的成因。
+func (a *Agent) comefromForAgent() string {
+	if a == nil {
+		return comeFromUser
+	}
+	if a.parentID != "" {
+		return comeFromInternal
+	}
+	return comeFromUser
+}
diff --git a/internal/agent/core/comefrom_test.go b/internal/agent/core/comefrom_test.go
new file mode 100644
index 00000000..33111a55
--- /dev/null
+++ b/internal/agent/core/comefrom_test.go
@@ -0,0 +1,165 @@
+package core
+
+// 工具调用帧的「来源标识」判据（2026-10-16）。
+//
+// 要证明的核心是：**驻留子的工具调用能被识别为"内部委派"，
+// 而不是被当成"那位用户发起的请求"** —— 后者会让通道插件的
+// 用户权限模型去拦一份已经准入的工作（现场实证：驻留子零产出）。
+
+import (
+	"testing"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+	"github.com/JianFeeeee/HomeAgent/pkg/types"
+)
+
+// ★★★ 判据：来源标识**必须在帧的起点就写入**（不能只在工具帧上）。
+//
+// 为什么：插件可能在 on_input 阶段就据此决定是否介入，
+// 而那个阶段**早于**工具帧构造。只在工具帧写会漏掉这条路径。
+func TestComeFromIsStampedAtFrameOrigin(t *testing.T) {
+	root := newBareAgent("main", "")
+	ctx := root.stageCtxFromInput("hi", "", "")
+	got, ok := ctx.Extra[extraKeyComeFrom]
+	if !ok {
+		t.Fatal("★ 帧起点未写 comefrom（插件在 on_input 阶段拿不到来源标识）")
+	}
+	if got != comeFromUser {
+		t.Errorf("根 agent 的帧应为 %q，实际 %q", comeFromUser, got)
+	}
+
+	// 驻留子：有 parentID ⇒ internal
+	child := newBareAgent("worker-1", "main")
+	cctx := child.stageCtxFromInput("hi", "", "")
+	if got := cctx.Extra[extraKeyComeFrom]; got != comeFromInternal {
+		t.Errorf("★ 驻留子的帧应为 %q（它是父的委派体，不是用户请求的边界），实际 %q",
+			comeFromInternal, got)
+	}
+}
+
+// ★★★ **最关键的一条**：工具调用帧必须带标识，且驻留子的是 internal。
+//
+// 这是本次缺陷的直接回归判据：缺了它，通道插件的 before_toolcall
+// 会把驻留子的调用按"非所有者用户"判定 ⇒ 开发工具全被拒。
+func TestToolFrameCarriesComeFrom(t *testing.T) {
+	// 驻留子（有父）⇒ 工具帧必须是 internal
+	child := newBareAgent("worker-1", "main")
+	base := child.stageCtxFromInput("do work", "", "")
+	f := &TaskFrame{StageCtx: base, PendingTools: []agentAPI.ToolCall{
+		{Name: "cmd_run"}, {Name: "files_ls"},
+	}}
+	f.buildToolContexts()
+	if len(f.toolCtxs) != 2 {
+		t.Fatalf("工具帧数量不对: %d", len(f.toolCtxs))
+	}
+	for i, name := range []string{"cmd_run", "files_ls"} {
+		got, ok := f.toolCtxs[i].Extra[extraKeyComeFrom]
+		if !ok {
+			t.Fatalf("★ 工具 %s 的帧没有 comefrom（缺陷回归）", name)
+		}
+		if got != comeFromInternal {
+			t.Errorf("★ 驻留子的工具 %s 应为 %q，实际 %q —— "+
+				"会被通道插件按用户权限模型拦住", name, comeFromInternal, got)
+		}
+	}
+
+	// 根 agent ⇒ 工具帧必须是 user（不能因为加了这个就放宽用户权限）
+	root := newBareAgent("main", "")
+	rbase := root.stageCtxFromInput("hi", "", "")
+	rf := &TaskFrame{StageCtx: rbase, PendingTools: []agentAPI.ToolCall{{Name: "cmd_run"}}}
+	rf.buildToolContexts()
+	if got := rf.toolCtxs[0].Extra[extraKeyComeFrom]; got != comeFromUser {
+		t.Errorf("★ 根 agent 的工具帧应为 %q（否则会放宽用户权限门），实际 %q",
+			comeFromUser, got)
+	}
+}
+
+// ★★★ 判据：即使 base 帧**没有**标识，工具帧也必须带上（不变量兜底）。
+//
+// 为什么这条必须独立存在（本会话第 9 次同类教训）：
+// 初版判据只验证"走 stageCtxFromInput 的正常路径"，而 copyExtraMap
+// 已经把 comefrom 复制进工具帧 —— 于是**删掉工具帧里那行 stampComeFrom
+// 判据依然全绿**（变异不咬）。那说明判据测的是"继承"，没测"兜底"。
+//
+// 而兜底是有意义的：TaskFrame 可以被手搓（新内部路径、测试替身），
+// 那种帧的 StageCtx 不经 stageCtxFromInput。没有兜底就会出现
+// "某些路径的工具帧没有来源标识" —— 而缺标识时插件按旧语义（用户）
+// 判定 ⇒ 驻留子又被拦。不变量必须由**工具帧自己**保证。
+func TestToolFrameStampsComeFromEvenWhenBaseLacksIt(t *testing.T) {
+	// 手搓一个**没有** comefrom 的 base（模拟不经 stageCtxFromInput 的路径）
+	base := &sdk.StageContext{Extra: map[string]interface{}{}, Phase: sdk.StageOnInput}
+	if _, ok := base.Extra[extraKeyComeFrom]; ok {
+		t.Fatal("前置条件错：这个 base 不该有标识")
+	}
+	f := &TaskFrame{StageCtx: base, PendingTools: []agentAPI.ToolCall{{Name: "cmd_run"}}}
+	f.buildToolContexts()
+	got, ok := f.toolCtxs[0].Extra[extraKeyComeFrom]
+	if !ok {
+		t.Fatal("★ 工具帧未兜底写入 comefrom —— base 没标时就完全没标识了")
+	}
+	// 兜底值必须是**保守**的 user（宁可多查一次，不可静默放宽权限）
+	if got != comeFromUser {
+		t.Errorf("兜底值应为保守的 %q，实际 %q", comeFromUser, got)
+	}
+}
+
+// ★★★ 判据：工具帧的 Extra 仍然**逐份独立**（不能因为加键而退化成共享 map）。
+//
+// 既有纪律（task.go 注释）：Extra 被 stage handler 写入，若多份共享同一
+// map，一个工具的身份绑定会串到同批其他工具上 —— 那是越权。
+func TestToolFramesHaveIndependentExtra(t *testing.T) {
+	a := newBareAgent("worker", "main")
+	base := a.stageCtxFromInput("x", "", "")
+	f := &TaskFrame{StageCtx: base, PendingTools: []agentAPI.ToolCall{{Name: "t1"}, {Name: "t2"}}}
+	f.buildToolContexts()
+	if len(f.toolCtxs) != 2 {
+		t.Fatal("工具帧数量不对")
+	}
+	f.toolCtxs[0].Extra["probe"] = "only-first"
+	if _, leaked := f.toolCtxs[1].Extra["probe"]; leaked {
+		t.Fatal("★ 工具帧共享了 Extra（一个工具的改写会串到别的工具上 = 越权风险）")
+	}
+}
+
+// ★★★ 判据：**不覆盖**已有标识（更内层知道更准）。
+func TestStampComeFromDoesNotOverwrite(t *testing.T) {
+	m := map[string]interface{}{extraKeyComeFrom: comeFromInternal}
+	stampComeFrom(m, comeFromUser)
+	if m[extraKeyComeFrom] != comeFromInternal {
+		t.Errorf("★ 不该覆盖已有值（内层更准），实际被改成 %v", m[extraKeyComeFrom])
+	}
+	// nil map 不得 panic
+	stampComeFrom(nil, comeFromUser)
+}
+
+// ★★★ 判据：缺标识时的语义 = 旧行为（user）。
+//
+// 已发布插件不认识 comefrom。内核必须保证：**缺失时插件看到的行为
+// 与改动前完全一致**，否则这个改动对存量插件是破坏性的。
+func TestMissingComeFromKeepsLegacySemantics(t *testing.T) {
+	// 一个没有任何标识的帧（模拟旧路径）
+	ctx := &sdk.StageContext{Extra: map[string]interface{}{}}
+	if _, ok := ctx.Extra[extraKeyComeFrom]; ok {
+		t.Fatal("前置条件错：这个帧不该有标识")
+	}
+	// 内核侧的保守默认就是 comeFromUser —— 插件缺失时按旧语义（用户）处理
+	if comeFromUser != "user" {
+		t.Errorf("默认值必须是与旧行为等价的 %q，实际 %q", "user", comeFromUser)
+	}
+}
+
+// ---- 测试脚手架 ----
+
+// newBareAgent 造一个只有身份（id + parentID）的最小 Agent。
+//
+// 不装配 io/provider：判据只验证"来源标识怎么算、怎么落到帧上"，
+// 装重型依赖会让判据变慢且掩盖真正的断言点。
+func newBareAgent(id, parent string) *Agent {
+	return New(AgentConfig{
+		ID:       types.AgentID(id),
+		ParentID: parent,
+		IO:       agentIO.NewIOManager(),
+	})
+}
diff --git a/internal/agent/core/commondev_premise_test.go b/internal/agent/core/commondev_premise_test.go
new file mode 100644
index 00000000..38b2e904
--- /dev/null
+++ b/internal/agent/core/commondev_premise_test.go
@@ -0,0 +1,229 @@
+package core
+
+// 刀 0：验证 commondev 架构赖以成立的前提。
+//
+// 设计 docs/zh/commondev-agent-runtime-design.md §2.2 / §2.3 / §2.5。
+//
+// 整套「插件注册通道 → 主 agent 建驻留子并划入 → 子调 output_send__ 下任务」
+// 的架构，建立在**两个**此前只有读码结论、从未跑过的事实上：
+//
+//	P1. 驻留子能调到**外部插件**注册的工具（若不能，子无法下任务给 pi）
+//	P2. 驻留子能用**外部插件**注册的输出门 output_send__<ch>（若不能，通道白注册）
+//
+// 这两条不成立，上层机制全是纸面的 —— 所以先验它，再写插件。
+//
+// 注册路径与真实插件一致：工具走 StageHost，输出通道走 IOManager.RegisterDevice
+// （插件经 proc 桥最终也落到这两处，见 internal/plugin/registry.go:305-320）。
+
+import (
+	"strings"
+	"testing"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// 与 commondev 真实用法一致的通道名：inputch 可含斜杠，outputch 必须合规
+// （会被拼成 output_send__<name>，见 SDK RegisterOutputChannel 注释）。
+const (
+	probeInputCh = "commondev/br-1"
+	probeOutCh   = "commondev_br-1"
+	probeTool    = "commondev_probe"
+	probeOutGate = "output_send__" + probeOutCh
+)
+
+// probeDevice 模拟插件注册的输出通道（与内部 channelDevice 同构）。
+type probeDevice struct {
+	name    string
+	caps    agentIO.OutputCapability
+	handler sdk.ToolHandler
+	got     *string
+}
+
+func (d *probeDevice) Name() string                                 { return d.name }
+func (d *probeDevice) Type() agentIO.DeviceType                     { return agentIO.DeviceOutput }
+func (d *probeDevice) Description() string                          { return "探针通道：给 pi 投递任务" }
+func (d *probeDevice) Start() error                                 { return nil }
+func (d *probeDevice) Stop() error                                  { return nil }
+func (d *probeDevice) OutputCapabilities() agentIO.OutputCapability { return d.caps }
+func (d *probeDevice) Tools() []agentIO.ToolDef                     { return nil }
+func (d *probeDevice) ChannelDef() agentIO.ChannelDef               { return agentIO.ChannelDef{NoMemory: true} }
+func (d *probeDevice) Execute(tool string, args map[string]interface{}) (interface{}, error) {
+	payload, _ := args["payload"].(string)
+	if d.got != nil {
+		*d.got = payload // 记录插件 handler 真的收到了什么
+	}
+	return d.handler(args)
+}
+
+// registerProbePlugin 模拟 commondev 插件注册工具与通道。
+// delivered 非 nil 时记录插件 handler 实际收到的 payload（证明"包一下"真的发生）。
+func registerProbePlugin(t *testing.T, a *Agent, delivered *string) {
+	t.Helper()
+
+	// ① 插件工具：子要能调它（P1）
+	if err := a.stageHost.RegisterTool(probeTool, sdk.ToolDef{
+		Name:        probeTool,
+		Description: "探针：插件注册的普通工具",
+		Parameters:  map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
+	}, func(args map[string]interface{}) (interface{}, error) {
+		return "plugin-tool-ok", nil
+	}); err != nil {
+		t.Fatalf("插件工具注册失败: %v", err)
+	}
+
+	// ② 插件输出通道：子要能用 output_send__commondev_br-1（P2）
+	if err := a.io.RegisterDevice(&probeDevice{
+		name: probeOutCh,
+		caps: agentIO.CapText,
+		handler: func(args map[string]interface{}) (interface{}, error) {
+			return "已投递", nil
+		},
+		got: delivered,
+	}); err != nil {
+		t.Fatalf("插件输出通道注册失败: %v", err)
+	}
+
+	// ③ inputch：pi → 子 的回投入口
+	if err := a.io.RegisterInputChannelFrom("commondev", probeInputCh, agentIO.ChannelDef{NoMemory: true}); err != nil {
+		t.Fatalf("inputch 注册失败: %v", err)
+	}
+}
+
+// TestP1_ResidentSeesExternalPluginTools 钉住 P1：
+// 驻留子的工具表里必须有**外部插件**注册的工具，且真的能执行。
+//
+// 若不成立：子无法下任务给 pi ⇒ 整套架构作废（必须改为父代投）。
+func TestP1_ResidentSeesExternalPluginTools(t *testing.T) {
+	parent, _, dir := newRootForResidents(t)
+	registerProbePlugin(t, parent, nil)
+
+	info := spawnTestResident(t, parent, dir, "dev-br-1", probeInputCh)
+	child := residentOf(t, parent, info.ID)
+
+	// ① 工具表（模型看得到的）里要有
+	names := childToolNames(child)
+	if !hasToolNamed(names, probeTool) {
+		t.Fatalf("P1 不成立：驻留子看不到外部插件工具 %s\n看到的是: %v", probeTool, names)
+	}
+	t.Logf("P1a ✅ 驻留子工具表含插件工具（工具总数 %d）", len(names))
+
+	// ② 且真的能执行（能看到 ≠ 能调到）
+	got := child.executeToolCall(agentAPI.ToolCall{
+		ID: "p1", Name: probeTool, Arguments: map[string]interface{}{},
+	}, probeInputCh)
+	if !strings.Contains(got, "plugin-tool-ok") {
+		t.Fatalf("P1 不成立：工具在表里但调不通: %s", got)
+	}
+	t.Log("P1b ✅ 且可执行（plugin-tool-ok）")
+}
+
+// TestP2_ResidentCanUseExternalPluginOutputGate 钉住 P2：
+// 驻留子必须能通过 output_send__commondev_br-1 打到**插件注册的通道 handler**。
+//
+// 若不成立：通道注册了但子用不了 ⇒ 投递路径断掉。
+func TestP2_ResidentCanUseExternalPluginOutputGate(t *testing.T) {
+	parent, _, dir := newRootForResidents(t)
+	var delivered string
+	registerProbePlugin(t, parent, &delivered)
+
+	info := spawnTestResident(t, parent, dir, "dev-br-1", probeInputCh)
+	child := residentOf(t, parent, info.ID)
+
+	// ① 输出门工具存在（未授权则工具表里根本不会有）
+	names := childToolNames(child)
+	if !hasToolNamed(names, probeOutGate) {
+		t.Fatalf("P2 不成立：驻留子看不到 %s\n看到的是: %v", probeOutGate, names)
+	}
+	t.Logf("P2a ✅ 驻留子有 %s", probeOutGate)
+
+	// ② 调用它 —— 必须真的打到插件 handler
+	//
+	// 期望返回 "ok"：`output.go:94` 只在 `dev.Execute()` **成功**时返回它。
+	// ⚠️ 不能断言返回插件 handler 的文本：内核对成功的回执刻意**极简**
+	//（rich 回执会驱动模型继续调 output_send，是 output loop 的根源）。
+	// 所以"插件真的收到了"要由 handler 自己记下来（delivered）来证。
+	got := child.executeToolCall(agentAPI.ToolCall{
+		ID: "p2", Name: probeOutGate,
+		Arguments: map[string]interface{}{"payload": "给 pi 的任务：修 bug", "type": "text"},
+	}, probeInputCh)
+	if strings.Contains(got, "不存在") || strings.Contains(got, "未授权") {
+		t.Fatalf("P2 不成立：输出门不可用: %s", got)
+	}
+	if got != "ok" {
+		t.Fatalf("P2 不成立：输出门应返回 ok（dev.Execute 成功），实际: %q", got)
+	}
+	// ★ 真正的判据：插件 handler 收到的 payload
+	if delivered != "给 pi 的任务：修 bug" {
+		t.Fatalf("P2 不成立：插件 handler 收到的 payload 不符: %q", delivered)
+	}
+	t.Logf("P2b ✅ 输出门打到插件 handler，payload 完整传达（%d 字节）", len(delivered))
+}
+
+// TestP3_ChannelNameSlashIsIllegalForOutputGate 钉住命名约束（文档 §2.2）：
+// outputch 带斜杠会让 output_send__<name> 不合法 ⇒ 工具名违规。
+//
+// 这条是**反例**：证明"inputch 可用斜杠、outputch 不行"不是猜想。
+func TestP3_ChannelNameSlashIsIllegalForOutputGate(t *testing.T) {
+	parent, _, dir := newRootForResidents(t)
+	registerProbePlugin(t, parent, nil)
+
+	info := spawnTestResident(t, parent, dir, "dev-br-1", probeInputCh)
+	child := residentOf(t, parent, info.ID)
+	names := childToolNames(child)
+
+	// 合法命名：有
+	if !hasToolNamed(names, probeOutGate) {
+		t.Fatalf("下划线命名应可用，但没有 %s", probeOutGate)
+	}
+	// 非法命名：绝不能出现在工具表里
+	for _, n := range names {
+		if strings.HasPrefix(n, "output_send__") && strings.Contains(n, "/") {
+			t.Fatalf("发现带斜杠的输出门工具名 %q —— 会触发上游 400", n)
+		}
+	}
+	t.Log("P3 ✅ 输出门命名合规（无斜杠）")
+}
+
+// ---------------- 测试辅助 ----------------
+
+// residentOf 取父登记表里的驻留子（不存在则 fatal）。
+func residentOf(t *testing.T, parent *Agent, id string) *Agent {
+	t.Helper()
+	parent.residentMu.Lock()
+	rc, ok := parent.residents[id]
+	parent.residentMu.Unlock()
+	if !ok || rc == nil || rc.agent == nil {
+		t.Fatalf("驻留子 %s 不存在", id)
+	}
+	return rc.agent
+}
+
+// childToolNames 取某个 agent 当前工具表里的名字。
+func childToolNames(a *Agent) []string {
+	var out []string
+	for _, raw := range a.buildToolDefs() {
+		m, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		fn, _ := m["function"].(map[string]interface{})
+		if fn == nil {
+			continue
+		}
+		if name, _ := fn["name"].(string); name != "" {
+			out = append(out, name)
+		}
+	}
+	return out
+}
+
+func hasToolNamed(list []string, want string) bool {
+	for _, s := range list {
+		if s == want {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/agent/core/context.go b/internal/agent/core/context.go
index 5a5e4f76..aec853d4 100644
--- a/internal/agent/core/context.go
+++ b/internal/agent/core/context.go
@@ -351,10 +351,17 @@ func (c *RelevanceContext) Save() error {
 	return os.WriteFile(c.savePath, data, 0644)
 }
 
+// Append 追加一条事件。
+//
+// ★ 这里是**持久化记忆的唯一咽喉**：全部 5 处写 context 的调用都经过它
+// （另一处 InsertByTimestamp 同样处理）。所以明文拦截放在这里，
+// 而不是在每个调用点 —— 逐个补必漏（实测踩到：只拦了 f.Msgs，
+// 而 f.CleanInput / f.ToolResults / f.Response 都是独立副本）。
 func (c *RelevanceContext) Append(evt ContextEvent) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 
+	scrubEventSecrets(&evt)
 	c.computeVector(&evt)
 	c.events = append(c.events, &evt)
 
@@ -365,6 +372,7 @@ func (c *RelevanceContext) InsertByTimestamp(evt ContextEvent) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 
+	scrubEventSecrets(&evt) // 同 Append：咽喉处拦截
 	c.computeVector(&evt)
 
 	idx := sort.Search(len(c.events), func(i int) bool {
diff --git a/internal/agent/core/context_tuning_test.go b/internal/agent/core/context_tuning_test.go
index 8597d394..22cf0a41 100644
--- a/internal/agent/core/context_tuning_test.go
+++ b/internal/agent/core/context_tuning_test.go
@@ -6,6 +6,7 @@ import (
 	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
 	"github.com/JianFeeeee/HomeAgent/internal/memory"
 )
+
 // 这组判据把「上下文管理的阈值」从硬编码变成可配置，并守住两条纪律：
 //
 //  1. **零值等价**：ContextTuning 零值必须与硬编码时代**逐值相同**。
diff --git a/internal/agent/core/crossmodal.go b/internal/agent/core/crossmodal.go
index 55c642e5..6fbc435b 100644
--- a/internal/agent/core/crossmodal.go
+++ b/internal/agent/core/crossmodal.go
@@ -19,11 +19,11 @@ import (
 // memory.RecallBlocks（读块自己的向量），因此不存在「召回已无处可归的
 // 内容」这回事——能召回的必然是被某层持有的块。
 type CrossModalHit struct {
-	Doc        *document.Doc        // 文本路命中的文档；视觉路命中时为 nil
-	Media      *memory.MemoryBlock  // 视觉路命中的媒体块；文本路命中时也可能带关联块
-	MediaScore float64              // 视觉路原始 cosine（无则 0）
-	DocScore   float64              // 文本路原始 cosine（无则 0）
-	Fused      float64              // 归一化加权融合分，供最终排序
+	Doc        *document.Doc       // 文本路命中的文档；视觉路命中时为 nil
+	Media      *memory.MemoryBlock // 视觉路命中的媒体块；文本路命中时也可能带关联块
+	MediaScore float64             // 视觉路原始 cosine（无则 0）
+	DocScore   float64             // 文本路原始 cosine（无则 0）
+	Fused      float64             // 归一化加权融合分，供最终排序
 	// 该媒体同时被两路命中时 DoubleHit=true —— 双信号确认，应排在只被
 	// 一路命中的候选之前。
 	DoubleHit bool
diff --git a/internal/agent/core/distill.go b/internal/agent/core/distill.go
index 40b44d37..db4a31e1 100644
--- a/internal/agent/core/distill.go
+++ b/internal/agent/core/distill.go
@@ -605,7 +605,7 @@ func isTemplateSummary(s string) bool {
 }
 
 func (a *Agent) emitMemoryCandidate(source, input, response string, toolResults []ToolResultItem, toolsUsed []string) {
-	a.io.EmitOutput("memory", "memory_candidate", map[string]interface{}{
+	payload := map[string]interface{}{
 		"source":       source,
 		"input":        input,
 		"response":     response,
@@ -613,7 +613,11 @@ func (a *Agent) emitMemoryCandidate(source, input, response string, toolResults
 		"tools_used":   toolsUsed,
 		"agent_id":     string(a.id),
 		"timestamp":    time.Now().Unix(),
-	})
+	}
+	// ★ 记忆候选是**不经 context** 的另一条持久化侧路（走 EmitOutput）。
+	// 不在这里拦，明文会直接进长期记忆 —— 而记忆跨会话保留、每轮被召回。
+	scrubMemoryCandidate(payload)
+	a.io.EmitOutput("memory", "memory_candidate", payload)
 }
 
 func (a *Agent) processConsolidation(evt *agentIO.InputEvent, input string) {
diff --git a/internal/agent/core/encshell_premise_test.go b/internal/agent/core/encshell_premise_test.go
new file mode 100644
index 00000000..66856f7a
--- /dev/null
+++ b/internal/agent/core/encshell_premise_test.go
@@ -0,0 +1,54 @@
+package core
+
+// 前提验证：插件 enc_shell 的**命令参数**是否已被内核填好明文？
+//
+// 若已填 ⇒ 插件自己的 lookupAnySecret 对内核别名是**死代码**，
+// 且「保留 enc_shell」的理由只剩 argv 保护（脚本走 stdin）。
+//
+// 这决定了 SDK 该不该暴露 Fill()：
+//   · 若插件本来就能从 args 拿到明文 ⇒ 暴露 Fill 不新增任何权限
+//   · 若拿不到 ⇒ 暴露 Fill 会削弱边界（插件可枚举 List 再逐个 Fill）
+
+import (
+	"strings"
+	"testing"
+
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+func TestPremise_EncShellCommandPrefilledByKernel(t *testing.T) {
+	store := newScrubStore(t)
+	a, _, _ := newRootForResidents(t)
+
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	alias, err := store.Submit(tok, "测")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var cmdSaw string
+	if err := a.stageHost.RegisterTool("probe_encsh", sdk.ToolDef{
+		Name: "probe_encsh", Description: "模拟 enc_shell",
+		Parameters: map[string]interface{}{"type": "object"},
+	}, func(args map[string]interface{}) (interface{}, error) {
+		cmdSaw, _ = args["command"].(string)
+		return "ok", nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := a.stageHost.ExecuteTool("probe_encsh", map[string]interface{}{
+		"command": "curl -H 'Authorization: token @{" + alias + "}'",
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	if strings.Contains(cmdSaw, "@{"+alias+"}") {
+		t.Fatal("handler 仍看到别名 ⇒ 内核没填，插件需要自己的填充逻辑")
+	}
+	if !strings.Contains(cmdSaw, tok) {
+		t.Fatalf("handler 应看到明文，实际 %q", cmdSaw)
+	}
+	t.Logf("✅ 内核已填 ⇒ 插件对**内核别名**的填充是死代码；" +
+		"插件仍需自己解析的是**平台凭据**（@ {gitea-local}，含连字符，内核不认）")
+}
diff --git a/internal/agent/core/encshell_redundancy_test.go b/internal/agent/core/encshell_redundancy_test.go
new file mode 100644
index 00000000..e25cac7a
--- /dev/null
+++ b/internal/agent/core/encshell_redundancy_test.go
@@ -0,0 +1,154 @@
+package core
+
+// 前提验证（C7）：内核的 `@{别名}` 回填是否让插件的 `enc_shell` 变得**多余**。
+//
+// ## 为什么要先验这个再删代码
+//
+// C7 要「大幅删减插件的加密 shell 工具族」。删的依据是一个断言：
+// 用户可以用**任何**工具（如内置的 cmd_run）配合 `@{别名}`，
+// 由内核对所有工具参数统一回填 —— 而不必依赖插件专有的 enc_shell。
+//
+// 这个断言不成立的话，删掉 enc_shell 就是**削功能**而非去冗余。
+//
+// 已验证过 `TestFirewall_ToolArgsFilledBeforePlugin`（插件工具收到明文）。
+// 这里补的是**决定性**的那一条：用**内置工具名**（cmd_run）也走同一条回填路径。
+
+import (
+	"strings"
+	"testing"
+
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// ★★ 判据：`cmd_run`（内置终端工具，非插件）的参数同样被内核回填。
+//
+// 这条成立 ⇒ 用户不必用插件专有的 enc_shell：
+//
+//	enc_shell(command="git push https://x:{token}@host/r.git fav")
+//	  ↓ 等价于
+//	cmd_run(command="git push https://x:@{sec_xxx}@host/r.git fav")
+//
+// 后者完全走内核机制，插件无需自带加密库与别名表。
+func TestKernelFillCoversBuiltinToolsToo(t *testing.T) {
+	store := newScrubStore(t)
+	a, _, _ := newRootForResidents(t)
+
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	alias, err := store.Submit(tok, "测试")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 注册一个**模拟 cmd_run 的内置工具**（不真的执行 shell），
+	// 验证它通过 StageHost.ExecuteTool 拿到的是明文。
+	var seen string
+	if err := a.stageHost.RegisterTool("cmd_run", sdk.ToolDef{
+		Name: "cmd_run", Description: "模拟内置终端工具",
+		Parameters: map[string]interface{}{"type": "object"},
+	}, func(args map[string]interface{}) (interface{}, error) {
+		seen, _ = args["command"].(string)
+		return "ok", nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := a.stageHost.ExecuteTool("cmd_run", map[string]interface{}{
+		"command": "git push https://x:@" + "{" + alias + "}@host/r.git feat/x",
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	if seen == "" {
+		t.Fatal("工具未被调用")
+	}
+	if !strings.Contains(seen, tok) {
+		t.Fatalf("★ 内核回填未覆盖内置工具名 —— 那 enc_shell 就有存在理由（不能删）\n实际: %q", seen)
+	}
+	t.Logf("✅ 内置工具名的参数也被回填 ⇒ enc_shell 的填充功能是冗余的: %q", seen)
+}
+
+// ★★ 判据：内核回填**发生在插件 handler 之前** ⇒ 插件自己的别名表对
+// 内核别名是**死代码**（永远不会命中）。
+//
+// 这个顺序很关键：
+//
+//	StageHost.ExecuteTool → security.FillMap(args) → handler(args)
+//
+// 所以当内核安全模块启用时，插件的 enc_shell 收到的 command 里
+// `@{sec_xxx}` **已经变成明文**了；插件自己的别名正则再扫也扫不到。
+//
+// ⇒ 结论：插件的「填充 @{别名}」这部分是**冗余**的（内核先做了）。
+//
+//	但它的 argv 保护（脚本走 stdin）与输出脱敏**仍然独有**，不可删。
+func TestKernelFillHappensBeforePluginHandler(t *testing.T) {
+	store := newScrubStore(t)
+	a, _, _ := newRootForResidents(t)
+
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	alias, err := store.Submit(tok, "测试")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var handlerSaw string
+	if err := a.stageHost.RegisterTool("probe_encshell", sdk.ToolDef{
+		Name: "probe_encshell", Description: "模拟 enc_shell",
+		Parameters: map[string]interface{}{"type": "object"},
+	}, func(args map[string]interface{}) (interface{}, error) {
+		handlerSaw, _ = args["command"].(string)
+		return "ok", nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, err := a.stageHost.ExecuteTool("probe_encshell", map[string]interface{}{
+		"command": "curl -H 'Authorization: token @{" + alias + "}'",
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	// handler 里看到的**已经没有 @{别名}** 了（已被内核换掉）
+	if strings.Contains(handlerSaw, "@{"+alias+"}") {
+		t.Fatalf("内核回填应在 handler 之前完成；实际 handler 仍看到别名: %q", handlerSaw)
+	}
+	if !strings.Contains(handlerSaw, tok) {
+		t.Fatalf("handler 应看到明文: %q", handlerSaw)
+	}
+	t.Logf("✅ 内核先回填，插件看不到别名 ⇒ 插件自带别名表对内核别名是死代码")
+}
+
+// ★★ 判据：内核与插件的 `@{...}` 引用**语法不冲突**（带连字符的名字归插件）。
+//
+// 这是个**偶然但真实**的兼容，必须钉住，否则将来有人"统一语法"就炸：
+//
+//	内核 refPattern:  @\{([A-Za-z0-9_]{1,64})\}    ← 不含 - 和 .
+//	插件 credRefPattern: @\{([A-Za-z0-9_.-]{1,64})\}  ← 含 - 和 .
+//
+// 于是：
+//
+//	@{sec_3718c87a11e9478b}  内核吃（无连字符）
+//	@{gitea-local}           内核**不吃**（有连字符）⇒ 留给插件解析
+//
+// ★ 若把内核的字符集放宽到含 `-`，插件自己的凭据（gitea-local）会被内核
+//
+//	先吃掉 —— 那些名字不在内核变量库里，内核会原样保留（认识不到），
+//	看起来"没坏"，但只要恰好有一个同名内核变量，就会静默换错值。
+func TestKernelAndPluginAliasSyntaxDoNotCollide(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	alias, err := store.Submit(tok, "内核变量")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 内核别名（无连字符）→ 被回填
+	if got, n, _ := store.Fill("x:@" + "{" + alias + "}"); n != 1 || !strings.Contains(got, tok) {
+		t.Fatalf("内核别名应被回填: n=%d got=%q", n, got)
+	}
+	// 插件风格的名字（含连字符）→ **不被内核碰**
+	pluginStyle := "git push https://x:@" + "{gitea-local}@host/r.git"
+	if got, n, _ := store.Fill(pluginStyle); n != 0 || !strings.Contains(got, "{gitea-local}") {
+		t.Fatalf("含连字符的引用内核不应碰（那是插件的凭据）: n=%d got=%q", n, got)
+	}
+	t.Logf("✅ 内核只吃 [A-Za-z0-9_]，@{gitea-local} 留给插件")
+}
diff --git a/internal/agent/core/firewall_e2e_test.go b/internal/agent/core/firewall_e2e_test.go
new file mode 100644
index 00000000..934b63dd
--- /dev/null
+++ b/internal/agent/core/firewall_e2e_test.go
@@ -0,0 +1,284 @@
+package core
+
+// 刀 S：**真机端到端**验证安全模块。
+//
+// 前面的判据都跑在 mock provider 上。这里用**真实的 Agent**（与生产同一套
+// StageHost / IOManager / 设备出口），验证三件事真的连通：
+//
+//	① 出向：Agent 发往 provider 的消息里，明文已变成别名
+//	② 落盘：变量库有记录，且磁盘上没有明文
+//	③ 入向：插件工具收到的参数是**明文**（回填生效，插件无感知）
+//	④ 入向：设备通道收到的 payload 是**明文**
+//
+// 为什么必须做真机验证：mock 判据只能证明"装饰器逻辑对"，
+// 证明不了"装饰器挂在正确的点位上"。位置错（比如挂在 stage 之后）
+// 在 mock 里完全看不出来。
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+const firewallToken = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+// fwToolDef 构造一个最小工具声明（本文件专用，避开与既有测试的同名辅助冲突）。
+func fwToolDef(name string) sdk.ToolDef {
+	return sdk.ToolDef{
+		Name:        name,
+		Description: "安全模块测试工具",
+		Parameters: map[string]interface{}{
+			"type":       "object",
+			"properties": map[string]interface{}{"token": map[string]interface{}{"type": "string"}},
+		},
+	}
+}
+
+func setupFirewall(t *testing.T) (*security.Store, string) {
+	t.Helper()
+	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) })
+	return store, dir
+}
+
+// ★★ 判据：插件工具收到的参数是**明文**（回填生效）。
+//
+// 这是整个设计的核心目的：模型手上只有别名，插件拿到真凭据，
+// 而**插件对替换完全无感知**。
+func TestFirewall_ToolArgsFilledBeforePlugin(t *testing.T) {
+	store, _ := setupFirewall(t)
+	a, _, _ := newRootForResidents(t)
+
+	// 插件工具：记录它实际收到的参数
+	var seenToken string
+	const toolName = "plugintest_store_secret"
+	if err := a.stageHost.RegisterTool(toolName, fwToolDef(toolName),
+		func(args map[string]interface{}) (interface{}, error) {
+			seenToken, _ = args["token"].(string)
+			return "ok", nil
+		}); err != nil {
+		t.Fatal(err)
+	}
+
+	// 模型只知道别名（它从未见过明文）
+	alias, err := store.Submit(firewallToken, "测试")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.stageHost.ExecuteTool(toolName, map[string]interface{}{
+		"token": "@{" + alias + "}",
+		"note":  "保持不变",
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	// ★ 插件看到的是明文
+	if seenToken != firewallToken {
+		t.Fatalf("插件应收到明文，实际收到 %q（回填未生效 ⇒ 插件拿不到真凭据）", seenToken)
+	}
+	t.Logf("✅ 插件工具收到的 token 是明文（%d 字节），别名 %s 已回填", len(seenToken), alias)
+}
+
+// ★★ 判据：设备通道收到的 payload 是**明文**。
+//
+// 这条验证回填插在了正确位置 —— 在插件 stage **之后**、设备 Execute **之前**。
+// 若插错（比如 stage 之前），插件会看到明文；
+// 若压根没插，设备会收到字面的 "@{sec_xxx}"。
+func TestFirewall_DevicePayloadFilledBeforeExecute(t *testing.T) {
+	store, _ := setupFirewall(t)
+	a, _, _ := newRootForResidents(t)
+
+	var delivered string
+	const outCh = "plugintest_secch"
+	if err := a.io.RegisterDevice(&probeDevice{
+		name: outCh,
+		caps: agentIO.CapText,
+		handler: func(args map[string]interface{}) (interface{}, error) {
+			return "已发送", nil
+		},
+		got: &delivered,
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	alias, err := store.Submit(firewallToken, "测试")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 模型发出的 payload 里只有别名
+	got := a.executeOutputSendTool(agentAPI.ToolCall{
+		Name: "output_send__" + outCh,
+		Arguments: map[string]interface{}{
+			"payload": "我的 token 是 @{" + alias + "} 请使用",
+		},
+	})
+
+	// ★ 设备收到明文
+	if !strings.Contains(delivered, firewallToken) {
+		t.Fatalf("设备应收到明文，实际 %q（回填位置错或未生效）\n工具返回: %s",
+			delivered, got)
+	}
+	if strings.Contains(delivered, alias) {
+		t.Errorf("别名不应出现在设备载荷里: %q", delivered)
+	}
+	t.Logf("✅ 设备通道收到明文（%d 字节）", len(delivered))
+}
+
+// ★ 判据：出向拦截真的发生在真实 provider 调用上（用真实 ProviderManager）。
+func TestFirewall_OutboundScrubbedOnRealProviderPath(t *testing.T) {
+	setupFirewall(t)
+	var captured string
+	mgr := agentAPI.NewProviderManager()
+	mgr.Register("probe", &fwCaptureProvider{name: "probe", capture: &captured})
+
+	_, err := mgr.Default().Chat(context.Background(), &agentAPI.CompletionRequest{
+		Messages: []agentAPI.Message{
+			{Role: "user", Content: "这是我的凭据: " + firewallToken},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(captured, firewallToken) {
+		t.Fatalf("明文泄漏到 provider: %s", captured)
+	}
+	if !strings.Contains(captured, "安全模块自动拦截") {
+		t.Errorf("未见拦截提示: %s", captured)
+	}
+	t.Logf("✅ 出向拦截生效，provider 收到: %s", captured)
+}
+
+// ★ 判据：磁盘上**没有明文**（加密落盘），且权限 0600。
+func TestFirewall_NoPlaintextOnDisk(t *testing.T) {
+	store, dir := setupFirewall(t)
+	if _, err := store.Submit(firewallToken, "落盘"); err != nil {
+		t.Fatal(err)
+	}
+
+	// 扫变量库目录下所有文件
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, e := range entries {
+		b, err := os.ReadFile(filepath.Join(dir, e.Name()))
+		if err != nil {
+			continue
+		}
+		if strings.Contains(string(b), firewallToken) {
+			t.Fatalf("磁盘文件 %s 出现明文", e.Name())
+		}
+		fi, _ := e.Info()
+		if perm := fi.Mode().Perm(); perm&0o077 != 0 {
+			t.Errorf("文件 %s 权限过宽: %04o", e.Name(), perm)
+		}
+	}
+	t.Logf("✅ 目录下 %d 个文件均无明文，权限均受限", len(entries))
+}
+
+// ★ 判据：**同明文合并**（同一次对话里多个通道用同一个 secret ⇒ 同一别名）。
+func TestFirewall_SameSecretMergesAcrossChannels(t *testing.T) {
+	store, _ := setupFirewall(t)
+
+	// 两处独立出现同一明文（模拟两个插件都用同一个 token）
+	alias1, _ := store.Submit(firewallToken, "通道A")
+	alias2, _ := store.Submit(firewallToken, "通道B")
+
+	if alias1 != alias2 {
+		t.Fatalf("同一明文必须合并到同一别名: %s vs %s", alias1, alias2)
+	}
+	if store.Count() != 1 {
+		t.Errorf("应只有 1 条记录（合并），实际 %d", store.Count())
+	}
+	t.Logf("✅ 同一明文跨通道合并到 %s（记录数 1）", alias1)
+}
+
+// ★ 判据：端到端一轮 —— 出向后别名回填，模型可用同一别名再次调用。
+//
+// 这是完整闭环：拦截 → 别名进上下文 → 模型用别名 → 回填 → 插件拿到明文。
+func TestFirewall_FullRoundTrip(t *testing.T) {
+	store, _ := setupFirewall(t)
+	a, _, _ := newRootForResidents(t)
+
+	var pluginSaw string
+	const toolName = "plugintest_roundtrip"
+	if err := a.stageHost.RegisterTool(toolName, fwToolDef(toolName),
+		func(args map[string]interface{}) (interface{}, error) {
+			pluginSaw, _ = args["secret"].(string)
+			return "ok", nil
+		}); err != nil {
+		t.Fatal(err)
+	}
+
+	// ① 第一步：模型输出的文本里带明文 ⇒ 被内核拦截成别名
+	//    （模拟真实链路：模型回复 → 出向扫描）
+	scrubbed, evts := store.Replace("用这个部署: "+firewallToken, "llm_out:assistant", security.Patterns)
+	if len(evts) != 1 {
+		t.Fatalf("应拦截 1 处，实际 %d", len(evts))
+	}
+	alias := evts[0].Alias
+	t.Logf("① 拦截: 明文 → %s", alias)
+
+	// ② 模型后续调用工具时只能引用别名（它没见过明文）
+	if _, err := a.stageHost.ExecuteTool(toolName, map[string]interface{}{
+		"secret": "@{" + alias + "}",
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	// ③ 插件拿到真凭据
+	if pluginSaw != firewallToken {
+		t.Fatalf("插件应拿到明文，实际 %q", pluginSaw)
+	}
+
+	// ④ 上下文中始终只有别名（模型的视野里无明文）
+	if strings.Contains(scrubbed, firewallToken) {
+		t.Fatal("上下文里出现明文")
+	}
+	// ⑤ 变量记录里也无明文
+	b, _ := json.Marshal(store.List())
+	if strings.Contains(string(b), firewallToken) {
+		t.Fatal("变量记录泄露明文")
+	}
+	t.Logf("② 模型用 @{%s} 调用 → ③ 插件收到明文 → ④⑤ 上下文与记录均无明文", alias)
+}
+
+// fwCaptureProvider 记录收到的消息内容（模拟真实 provider 收到的请求）。
+type fwCaptureProvider struct {
+	name    string
+	capture *string
+}
+
+func (c *fwCaptureProvider) Name() string { return c.name }
+func (c *fwCaptureProvider) Chat(_ context.Context, req *agentAPI.CompletionRequest) (*agentAPI.CompletionResponse, error) {
+	if req != nil && len(req.Messages) > 0 {
+		*c.capture = req.Messages[0].Content
+	}
+	return &agentAPI.CompletionResponse{}, nil
+}
+func (c *fwCaptureProvider) ChatStream(_ context.Context, req *agentAPI.CompletionRequest) (<-chan agentAPI.StreamChunk, error) {
+	if req != nil && len(req.Messages) > 0 {
+		*c.capture = req.Messages[0].Content
+	}
+	ch := make(chan agentAPI.StreamChunk)
+	close(ch)
+	return ch, nil
+}
+func (c *fwCaptureProvider) MaxContextTokens() int { return 1000 }
diff --git a/internal/agent/core/inplace_scrub_test.go b/internal/agent/core/inplace_scrub_test.go
new file mode 100644
index 00000000..0765b03e
--- /dev/null
+++ b/internal/agent/core/inplace_scrub_test.go
@@ -0,0 +1,72 @@
+package core
+
+// 判据：出向拦截的**原地改写**语义（共享底层数组）。
+//
+// ## 为什么这条值得单独立判据
+//
+// `task.go:663` 构造请求时是 `Messages: f.Msgs` —— **值切片，无拷贝**。
+// 所以装饰器在出网前改写消息内容时，改的是 `f.Msgs` 的元素本身。
+//
+// 这个语义是**有意的**，且必须钉住：
+//
+//	好处：明文在第一次出网时就永久离开上下文。
+//	     若不共享，明文会一直躺在 f.Msgs 里，每一轮都要重新拦截，
+//	     并且任何读 f.Msgs 的地方（记忆写入、会话持久化、WebUI 回显）
+//	     都会看到明文 —— 泄漏面大得多。
+//
+//	代价：改写会渗进**非 LLM 路径**（同上那几处）。这是刻意的取舍：
+//	     宁可让这些地方看到别名（一致、可诊断），也不要让明文到处躺着。
+//
+// ⇒ 若有人把 `Messages: f.Msgs` 改成深拷贝，本判据会报红，
+//   提醒他同时要在「记忆写入前」和「持久化前」各加一道拦截。
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+// ★★ 判据：装饰器原地改写 ⇒ 原始消息切片也变成别名。
+func TestOutboundScrubIsInPlaceByDesign(t *testing.T) {
+	dir := t.TempDir()
+	if _, err := security.InitGlobal(security.Options{
+		Path:    dir + "/v.json",
+		KeyFn:   func() ([]byte, error) { return []byte("0123456789abcdef0123456789abcdef"), nil },
+		Enabled: true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { security.SetGlobal(nil) })
+
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	// 与 task.go:663 同构：Messages 直接赋 f.Msgs（值切片共享底层数组）
+	msgs := []agentAPI.Message{{Role: "user", Content: "token=" + tok}}
+
+	var captured string
+	mgr := agentAPI.NewProviderManager()
+	mgr.Register("p", &fwCaptureProvider{name: "p", capture: &captured})
+
+	if _, err := mgr.Default().Chat(context.Background(),
+		&agentAPI.CompletionRequest{Messages: msgs}); err != nil {
+		t.Fatal(err)
+	}
+
+	// ① 出网安全
+	if strings.Contains(captured, tok) {
+		t.Fatal("明文泄漏到 provider")
+	}
+	// ② 原地改写：原始切片也变了（**这是刻意的**）
+	if strings.Contains(msgs[0].Content, tok) {
+		t.Fatal("原始消息仍含明文 —— 说明 Messages 被深拷贝了。" +
+			"若确实要改成拷贝，必须同时在记忆写入与持久化前各加一道拦截，" +
+			"否则明文会一直躺在 f.Msgs 里被反复读出")
+	}
+	if !strings.Contains(msgs[0].Content, "@{sec_") {
+		t.Fatalf("原始消息应含别名，实际 %q", msgs[0].Content)
+	}
+	t.Logf("原地改写生效：原始 f.Msgs 元素已变别名 %q", msgs[0].Content)
+}
diff --git a/internal/agent/core/leakback_test.go b/internal/agent/core/leakback_test.go
new file mode 100644
index 00000000..7ecf695b
--- /dev/null
+++ b/internal/agent/core/leakback_test.go
@@ -0,0 +1,119 @@
+package core
+
+// ★★ 决定性的安全前提：**插件把明文返回时，内核能否拦住**？
+//
+// 这决定了「让安全模块向插件暴露 Fill()」是否安全：
+//
+//	若拦得住 ⇒ 暴露 Fill 不新增泄漏面（明文回到内核时会被换回别名）
+//	若拦不住 ⇒ 暴露 Fill 会让 LLM 通过插件读到任意明文，S1 作废
+//
+// 链路：插件 handler 返回明文 → ToolResults → ①context scrub（C5/C6）
+//                                        → ②provider 装饰器（C1）
+// 两处都必须拦住。
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+func TestPremise_PluginReturnedPlaintextIsScrubbed(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	alias, err := store.Submit(tok, "测")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 插件工具：**故意**把明文当返回值吐出来（模拟"恶意/粗糙插件"）
+	a := New(AgentConfig{
+		ID:              "leakback",
+		Provider:        &echoTokenProvider{reply: "收到"},
+		ProviderManager: agentAPI.NewProviderManager(),
+		IO:              agentIO.NewIOManager(),
+		StageHost:       NewStageHost(),
+	})
+	if err := a.stageHost.RegisterTool("leaky", sdk.ToolDef{
+		Name: "leaky", Description: "故意回吐明文",
+		Parameters: map[string]interface{}{"type": "object"},
+	}, func(args map[string]interface{}) (interface{}, error) {
+		return "凭据是 " + tok, nil // ★ 直接回吐明文
+	}); err != nil {
+		t.Fatal(err)
+	}
+	a.Start()
+	defer a.Stop()
+
+	// 走真实调度循环：模型调 leaky，结果进 context
+	a.io.InjectTextSync("http", "查一下")
+
+	// ① context 侧必须已换成别名
+	for _, evt := range a.context.Recent(0) {
+		for _, tr := range evt.ToolResults {
+			if strings.Contains(tr.Output, tok) {
+				t.Errorf("★ context 侧未拦住：%q", tr.Output)
+			}
+		}
+	}
+	// ② 记录里也不能有明文
+	if b := store.List(); len(b) == 0 {
+		t.Fatal("应登记变量")
+	}
+	_ = alias
+	t.Log("✅ 插件回吐的明文被内核拦下（context 侧）")
+}
+
+// ★★ 同上的 provider 侧：明文不得到达 LLM。
+func TestPremise_PluginReturnedPlaintextNeverReachesLLM(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	if _, err := store.Submit(tok, "测"); err != nil {
+		t.Fatal(err)
+	}
+
+	// 用已有的 captureProvider 看它实际收到什么
+	cp := &captureProvider{}
+	a := New(AgentConfig{
+		ID:              "leakback2",
+		Provider:        cp,
+		ProviderManager: agentAPI.NewProviderManager(),
+		IO:              agentIO.NewIOManager(),
+		StageHost:       NewStageHost(),
+	})
+	if err := a.stageHost.RegisterTool("leaky2", sdk.ToolDef{
+		Name: "leaky2", Description: "故意回吐明文",
+		Parameters: map[string]interface{}{"type": "object"},
+	}, func(args map[string]interface{}) (interface{}, error) {
+		return "凭据是 " + tok, nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+	a.Start()
+	defer a.Stop()
+	a.io.InjectTextSync("http", "查一下")
+
+	// provider 收到的**全部**消息里都不能有明文
+	cp.mu.Lock()
+	msgs := append([]agentAPI.Message(nil), cp.messages...)
+	cp.mu.Unlock()
+	for _, m := range msgs {
+		if strings.Contains(m.Content, tok) {
+			t.Errorf("★ 明文到达了 provider（LLM 能看到）: %q", m.Content)
+		}
+		for _, tr := range m.ToolCalls {
+			if strings.Contains(fmt.Sprint(tr.Arguments), tok) {
+				t.Errorf("★ 工具参数里的明文到达 provider: %v", tr.Arguments)
+			}
+		}
+	}
+	if len(msgs) == 0 {
+		t.Fatal("provider 一条消息都没收到 —— 判据无效")
+	}
+	t.Logf("✅ provider 侧未见明文（看了 %d 条消息）", len(msgs))
+	_ = context.Background
+}
diff --git a/internal/agent/core/medialoop.go b/internal/agent/core/medialoop.go
index 0ea7c2cd..3a39f2ea 100644
--- a/internal/agent/core/medialoop.go
+++ b/internal/agent/core/medialoop.go
@@ -7,6 +7,7 @@ import (
 	"sync/atomic"
 
 	"github.com/JianFeeeee/HomeAgent/internal/memory"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 )
 
 // 媒体与记忆块的生命周期辅助。
@@ -64,6 +65,7 @@ func (a *Agent) reembedStaleMedia() {
 	log.Printf("[media] 启动向量迁移: %d 个图像块 → fp=%s dim=%d workers=%d",
 		len(targets), shortFP(fp), a.multimodalSpace.Dim(), workers)
 
+	var jobsOnce sync.Once
 	jobs := make(chan memory.MemoryBlock, workers*2)
 	var done, failed int64
 	var wg sync.WaitGroup
@@ -89,7 +91,7 @@ func (a *Agent) reembedStaleMedia() {
 				i+1, len(targets), atomic.LoadInt64(&done), failed)
 		}
 	}
-	close(jobs)
+	safeclose.Safe(&jobsOnce, jobs)
 	wg.Wait()
 	log.Printf("[media] 向量迁移完成: 成功=%d 失败=%d 总计=%d fp=%s",
 		done, failed, len(targets), shortFP(fp))
diff --git a/internal/agent/core/memory_scrub.go b/internal/agent/core/memory_scrub.go
new file mode 100644
index 00000000..07618404
--- /dev/null
+++ b/internal/agent/core/memory_scrub.go
@@ -0,0 +1,158 @@
+package core
+
+// 持久化侧路的明文拦截（「记忆防火墙」）。
+//
+// ## 为什么必须单独拦（而不是只靠 provider 装饰器）
+//
+// 出向拦截（`api/provider.go` 的装饰器）只改 `f.Msgs` —— 那是**要发出去的
+// 那一份**。但内核把同一批内容**另存副本**送往持久化存储，那些副本
+// 不经过 provider：
+//
+//	ContextEvent.Input        ← f.CleanInput      （用户输入原文）
+//	ContextEvent.Response     ← f.Response        （模型回复）
+//	ContextEvent.ToolResults  ← f.ToolResults     （工具输出）
+//	emitMemoryCandidate.payload.tool_results      ← 同上，走 EmitOutput 不经 context
+//
+// 实测确认（变异实验 C6-M1 / C6-M2 / 输入侧探针）：
+// 只拦 `f.Msgs` 时，明文会完整地写进 `context.json` **与长期记忆**，
+// 而后者跨会话保留、每轮被召回 —— 泄漏面比"重放一次"大得多。
+//
+// ## 为什么放在 Append/InsertByTimestamp 而不是各调用点
+//
+// 写 context 的地方有 5 处（task.go 3 处、toolcall.go 1 处，以及插入变体）。
+// 逐个补必然漏 —— 本文件的前身就是这么漏掉 `f.CleanInput` 的。
+// `Append` / `InsertByTimestamp` 是全部写入的唯一咽喉，拦这里一处即全覆盖。
+//
+// `emitMemoryCandidate` 不经 context（走 `EmitOutput`），所以单独处理。
+
+import (
+	"log"
+
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+// scrubEventSecrets 就地清洗一条待持久化事件里的明文。
+//
+// 失败策略：Store 未装配（未启用安全模块）时**原样返回**，零成本。
+func scrubEventSecrets(evt *ContextEvent) {
+	if evt == nil {
+		return
+	}
+	s := security.Global()
+	if s == nil {
+		return
+	}
+	if out, evts := s.Replace(evt.Input, "ctx_input", security.Patterns); len(evts) > 0 {
+		evt.Input = out
+		logEvtHits("上下文输入", evts)
+	}
+	if out, evts := s.Replace(evt.Response, "ctx_response", security.Patterns); len(evts) > 0 {
+		evt.Response = out
+		logEvtHits("上下文回复", evts)
+	}
+	for i := range evt.ToolResults {
+		if evt.ToolResults[i].Output == "" {
+			continue
+		}
+		if out, evts := s.Replace(evt.ToolResults[i].Output,
+			"ctx_tool:"+evt.ToolResults[i].Name, security.Patterns); len(evts) > 0 {
+			evt.ToolResults[i].Output = out
+			logEvtHits("上下文工具结果 "+evt.ToolResults[i].Name, evts)
+		}
+	}
+	// 一等记忆块：**文本**块同样可能带凭据（截图描述、文档正文、转写稿）。
+	// 媒体块（image/video/audio 的 Data）不处理 —— 那是二进制负载，
+	// 正则扫它既无意义也会损坏数据。
+	for i := range evt.Blocks {
+		if evt.Blocks[i].Text == "" {
+			continue
+		}
+		if out, evts := s.Replace(evt.Blocks[i].Text, "ctx_block", security.Patterns); len(evts) > 0 {
+			evt.Blocks[i].Text = out
+			logEvtHits("上下文记忆块", evts)
+		}
+	}
+}
+
+// scrubMemoryCandidate 清洗记忆候选载荷（不经 context 的那条侧路）。
+//
+// 就地改写 map：调用方传进来的是一次性的快照，改它没有副作用。
+func scrubMemoryCandidate(payload map[string]interface{}) {
+	if payload == nil {
+		return
+	}
+	s := security.Global()
+	if s == nil {
+		return
+	}
+	for _, key := range []string{"input", "response"} {
+		str, ok := payload[key].(string)
+		if !ok || str == "" {
+			continue
+		}
+		if out, evts := s.Replace(str, "memory:"+key, security.Patterns); len(evts) > 0 {
+			payload[key] = out
+			logEvtHits("记忆候选 "+key, evts)
+		}
+	}
+	switch trs := payload["tool_results"].(type) {
+	case []ToolResultItem:
+		for i := range trs {
+			if trs[i].Output == "" {
+				continue
+			}
+			if out, evts := s.Replace(trs[i].Output,
+				"memory:tool:"+trs[i].Name, security.Patterns); len(evts) > 0 {
+				trs[i].Output = out
+				logEvtHits("记忆候选工具结果 "+trs[i].Name, evts)
+			}
+		}
+		payload["tool_results"] = trs
+	case []interface{}:
+		// 有的调用方传的是未类型化的切片（如经 JSON 中转）。
+		for i := range trs {
+			m, ok := trs[i].(map[string]interface{})
+			if !ok {
+				continue
+			}
+			out, ok := m["output"].(string)
+			if !ok || out == "" {
+				continue
+			}
+			if scrubbed, evts := s.Replace(out, "memory:tool", security.Patterns); len(evts) > 0 {
+				m["output"] = scrubbed
+				logEvtHits("记忆候选工具结果", evts)
+			}
+		}
+	}
+}
+
+func logEvtHits(where string, evts []security.Evt) {
+	for _, e := range evts {
+		log.Printf("[security] %s 拦截 %s（模式 %s，%d 字节，合并=%v）",
+			where, e.Alias, e.Kind, e.Len, e.Merged)
+	}
+}
+
+// ---------------- 两处拦截的关系（重要，别删任一处） ----------------
+//
+// 实测确认：`Append` 里的 `scrubEventSecrets` 会**连带改掉** `f.ToolResults` ——
+// 因为 `turnEvt.ToolResults = f.ToolResults` 是值切片，共享底层数组，
+// 而 scrub 对 `evt.ToolResults[i].Output` 是就地赋值。
+//
+// 于是 `emitMemoryCandidate` 收到时往往已是别名 ⇒ 单独去掉
+// `scrubMemoryCandidate` 的变异实验**不会报红**（已验证）。
+//
+// ## 那为什么还要保留 scrubMemoryCandidate
+//
+// 因为「隐式依赖别名」是**脆弱**的：只要有人
+//   · 把 `turnEvt.ToolResults` 改成深拷贝（很自然的"防御性拷贝"改动），
+//   · 或调整 Append 与 emitMemoryCandidate 的先后顺序，
+//   · 或新增一条不经过 Append 的写入路径，
+// 记忆侧就会静默恢复泄漏，而没有任何判据会报红。
+//
+// `scrubMemoryCandidate` 是**显式契约**：无论上游怎么排版，记忆候选本身
+// 必须自己清洗。幂等（已是别名的不会再命中），代价只是一次正则扫描。
+//
+// 同理 `Append` 与 `InsertByTimestamp` 两处都要调 `scrubEventSecrets`：
+// 它们是两个独立入口，不能只保一处。
diff --git a/internal/agent/core/output.go b/internal/agent/core/output.go
index 482b1b8e..080a9087 100644
--- a/internal/agent/core/output.go
+++ b/internal/agent/core/output.go
@@ -2,11 +2,13 @@ package core
 
 import (
 	"fmt"
+	"log"
 	"strings"
 
 	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
 	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
 	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
 )
 
 func (a *Agent) executeOutputSendTool(tc agentAPI.ToolCall) string {
@@ -73,6 +75,20 @@ func (a *Agent) executeOutputSendTool(tc agentAPI.ToolCall) string {
 	args["payload"] = stageCtx.FinalText
 
 	if dev := a.io.GetDevice(channel); dev != nil {
+		// ★ 安全模块入向回填：把 @{别名} 换回明文。
+		//
+		// 位置在**插件 stage 之后、设备 Execute 之前**是有讲究的：
+		//   · 放在 stage 之前 ⇒ 插件会看到明文（不可，插件在信任边界外）
+		//   · 放在 Execute 之后 ⇒ 设备已收到带别名的载荷（功能坏了）
+		// 所以只能夹在中间：插件看不到，设备拿到真的。
+		//
+		// 注意单独处理 payload：args 里的其它字段（channel 等）不需要回填。
+		if s := security.Global(); s != nil {
+			if filled, n, used := s.Fill(args["payload"].(string)); n > 0 {
+				args["payload"] = filled
+				log.Printf("[security] 通道 %s 载荷回填 %d 处（别名 %v）", channel, n, used)
+			}
+		}
 		result, err := dev.Execute("output", args)
 		if err != nil {
 			return fmt.Sprintf("通过 [%s] 通道发送失败: %v", channel, err)
diff --git a/internal/agent/core/overflow.go b/internal/agent/core/overflow.go
index 85dcc17d..8232518e 100644
--- a/internal/agent/core/overflow.go
+++ b/internal/agent/core/overflow.go
@@ -232,7 +232,7 @@ func (a *Agent) raiseContextOverflow(pruned int) {
 // overflowNotice 构造超页中断消息。
 //
 // 抽成纯函数是为了可测：这条消息的措辞不是装饰，它是 agent 唯一的认知输入
-//（L4 任务按调度器设计拿不到被打断者的上下文）。「查不到不等于不存在」这句
+// （L4 任务按调度器设计拿不到被打断者的上下文）。「查不到不等于不存在」这句
 // 直接对应 v4 实测的一类真实失败 —— HA 对检索不到的事实回答
 // 「库里根本没有 X，任何数字都是编的」，因为它不知道有内容被移走了。
 func overflowNotice(pruned int) string {
@@ -267,4 +267,4 @@ func (a *Agent) contextLenSafe() int {
 	return a.context.Len()
 }
 
-// overflowStat 字段定义在 Agent 上（见 agent.go），此处只做访问辅助。
\ No newline at end of file
+// overflowStat 字段定义在 Agent 上（见 agent.go），此处只做访问辅助。
diff --git a/internal/agent/core/overflow_test.go b/internal/agent/core/overflow_test.go
index 4721f36b..a1981345 100644
--- a/internal/agent/core/overflow_test.go
+++ b/internal/agent/core/overflow_test.go
@@ -221,6 +221,7 @@ func TestOverflow_并发安全(t *testing.T) {
 	}
 	wg.Wait()
 }
+
 // ── T5（变异项）：帧内恢复预算耗尽 ⇒ 终止而非死循环 ──
 //
 // 为什么要单独测：这个防护一度是**死代码**（TaskFrame.OverflowRecover 声明了
@@ -309,8 +310,8 @@ func TestOverflow_T9_topK随窗口变化(t *testing.T) {
 		return newOverflowAgent(window, 30, 20, 400) // maxContextSize=30（默认）
 	}
 
-	small := build(10_000)      // 小窗口
-	large := build(1_000_000)   // 大窗口（用户关心的 1M 场景）
+	small := build(10_000)    // 小窗口
+	large := build(1_000_000) // 大窗口（用户关心的 1M 场景）
 
 	topKSmall := small.contextTopK()
 	topKLarge := large.contextTopK()
diff --git a/internal/agent/core/persist_leak_test.go b/internal/agent/core/persist_leak_test.go
new file mode 100644
index 00000000..cf8e26a0
--- /dev/null
+++ b/internal/agent/core/persist_leak_test.go
@@ -0,0 +1,221 @@
+package core
+
+// 判据：**持久化侧路的明文拦截**（文档 C5/C6）。
+//
+// ## 背景：出向拦截挡不住持久化
+//
+// provider 装饰器只改 `f.Msgs`（要发出去的那一份）。但内核把同样的内容
+// **另存副本**送往持久化存储，它们不经过 provider：
+//
+//	ContextEvent.Input        ← f.CleanInput    用户输入原文
+//	ContextEvent.Response     ← f.Response      模型回复
+//	ContextEvent.ToolResults  ← f.ToolResults   工具输出
+//	memory_candidate.payload                走 EmitOutput，不经 context
+//
+// 实测确认（本文件的判据原本都是探针，先量出泄漏再修）：
+// 只拦 f.Msgs 时明文完整写进 context.json **与长期记忆** —— 而记忆
+// 跨会话保留、每轮被召回，泄漏面比重放一次大得多。
+//
+// ## 为什么拦在 Append/InsertByTimestamp 而不是各调用点
+//
+// 写 context 有 5 处；逐个补必漏（本文件的前身就漏掉了 f.CleanInput）。
+// 那两处是唯一咽喉，拦一处即全覆盖。
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/memory"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+)
+
+// ★★ 判据：**用户输入**里的明文不得进 context（此前完全未被覆盖）。
+func TestE2E_InputSecretNeverReachesContext(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	a := New(AgentConfig{
+		ID:              "e2e-inputscrub",
+		Provider:        &plainReplyProvider{},
+		ProviderManager: agentAPI.NewProviderManager(),
+		IO:              agentIO.NewIOManager(),
+		StageHost:       NewStageHost(),
+	})
+	a.Start()
+	defer a.Stop()
+
+	a.io.InjectTextSync("http", "我的 token 是 "+tok+" 请记住")
+
+	for _, evt := range a.context.Recent(0) {
+		if strings.Contains(evt.Input, tok) {
+			t.Errorf("用户输入明文进了 a.context: %q", evt.Input)
+		}
+		if strings.Contains(evt.Response, tok) {
+			t.Errorf("回复里的明文进了 a.context: %q", evt.Response)
+		}
+	}
+	if store.Count() == 0 {
+		t.Fatal("变量库为空 —— 输入侧没被扫，判据无效")
+	}
+	t.Logf("✅ 输入侧明文未进 context；变量库 %d 条", store.Count())
+}
+
+// ★★ 判据：**模型回复**里的明文不得进 context。
+//
+// 模型看不到明文（出向已拦），所以它只能在**被喂了明文**时才回吐明文 ——
+// 这里用脚本 provider 直接造出那个回复，验证回复侧拦截生效。
+func TestE2E_ResponseSecretNeverReachesContext(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	a := New(AgentConfig{
+		ID:              "e2e-respscrub",
+		Provider:        &echoTokenProvider{reply: "你的凭据是 " + tok},
+		ProviderManager: agentAPI.NewProviderManager(),
+		IO:              agentIO.NewIOManager(),
+		StageHost:       NewStageHost(),
+	})
+	a.Start()
+	defer a.Stop()
+
+	a.io.InjectTextSync("http", "把凭据告诉我")
+
+	for _, evt := range a.context.Recent(0) {
+		if strings.Contains(evt.Response, tok) {
+			t.Errorf("模型回复明文进了 a.context: %q", evt.Response)
+		}
+	}
+	if store.Count() == 0 {
+		t.Fatal("变量库为空 —— 回复侧没被扫，判据无效")
+	}
+	t.Logf("✅ 回复侧明文未进 context；变量库 %d 条", store.Count())
+}
+
+// ★ 判据：**记忆块**（一等记忆的文本负载）也要过一遍。
+func TestScrubEventCoversMemoryBlocks(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	evt := &ContextEvent{
+		Input:    "带着 " + tok,
+		Response: "也带着 " + tok,
+		ToolResults: []ToolResultItem{
+			{Name: "cmd", Output: "还有 " + tok},
+		},
+	}
+	evt.Blocks = append(evt.Blocks, memoryBlockWithText("转写稿里有 "+tok))
+
+	scrubEventSecrets(evt)
+
+	for name, got := range map[string]string{
+		"input":    evt.Input,
+		"response": evt.Response,
+		"tool":     evt.ToolResults[0].Output,
+		"block":    evt.Blocks[0].Text,
+	} {
+		if strings.Contains(got, tok) {
+			t.Errorf("%s 仍含明文: %q", name, got)
+		}
+	}
+	if store.Count() == 0 {
+		t.Error("应登记变量")
+	}
+}
+
+// memoryBlockWithText 造一个文本记忆块。
+func memoryBlockWithText(text string) memory.MemoryBlock {
+	return memory.MemoryBlock{ID: "b1", Modality: memory.BlockText, Text: text}
+}
+
+// plainReplyProvider 给一句不含凭据的回复。
+type plainReplyProvider struct{}
+
+func (p *plainReplyProvider) Name() string          { return "plainReply" }
+func (p *plainReplyProvider) MaxContextTokens() int { return 8192 }
+func (p *plainReplyProvider) Chat(_ context.Context, _ *agentAPI.CompletionRequest) (*agentAPI.CompletionResponse, error) {
+	return &agentAPI.CompletionResponse{Content: "好的，记住了"}, nil
+}
+func (p *plainReplyProvider) ChatStream(_ context.Context, _ *agentAPI.CompletionRequest) (<-chan agentAPI.StreamChunk, error) {
+	ch := make(chan agentAPI.StreamChunk, 1)
+	ch <- agentAPI.StreamChunk{Content: "好的，记住了", Done: true}
+	close(ch)
+	return ch, nil
+}
+
+// echoTokenProvider 回吐一段固定文本（用于造出"回复含明文"的场景）。
+type echoTokenProvider struct{ reply string }
+
+func (p *echoTokenProvider) Name() string          { return "echoToken" }
+func (p *echoTokenProvider) MaxContextTokens() int { return 8192 }
+func (p *echoTokenProvider) Chat(_ context.Context, _ *agentAPI.CompletionRequest) (*agentAPI.CompletionResponse, error) {
+	return &agentAPI.CompletionResponse{Content: p.reply}, nil
+}
+func (p *echoTokenProvider) ChatStream(_ context.Context, _ *agentAPI.CompletionRequest) (<-chan agentAPI.StreamChunk, error) {
+	ch := make(chan agentAPI.StreamChunk, 1)
+	ch <- agentAPI.StreamChunk{Content: p.reply, Done: true}
+	close(ch)
+	return ch, nil
+}
+
+// ★★ 判据：`emitMemoryCandidate` **自己**清洗载荷，不依赖 Append 的隐含行为。
+//
+// 背景（实测）：`Append` 的 scrub 经共享底层数组会连带改掉 `f.ToolResults`，
+// 所以"去掉 scrubMemoryCandidate"的变异**不会**被走 a.context 的端到端判据发现。
+// 那意味着记忆侧防护是隐式依赖别名的 —— 一旦有人给 turnEvt.ToolResults
+// 加个深拷贝（很自然的"防御性拷贝"），记忆侧就静默泄漏。
+//
+// ❗本判据必须走 `a.emitMemoryCandidate` 这个**真实入口**，而不是直接调
+//
+//	`scrubMemoryCandidate` —— 初版直接调底层函数，于是"去掉入口处的调用"
+//	这个变异**不会报红**（判据测错了层次）。走真实入口才能钉住"入口必须调它"。
+func TestEmitMemoryCandidateScrubsPayload(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	a := New(AgentConfig{
+		ID:              "e2e-memcand",
+		Provider:        &plainReplyProvider{},
+		ProviderManager: agentAPI.NewProviderManager(),
+		IO:              agentIO.NewIOManager(),
+		StageHost:       NewStageHost(),
+	})
+
+	// 故意传**未经过任何上游清洗**的原始值
+	a.emitMemoryCandidate("http", "输入 "+tok, "回复 "+tok,
+		[]ToolResultItem{{Name: "cmd", Output: "输出 " + tok}}, []string{"cmd"})
+
+	var seen map[string]interface{}
+drain:
+	for {
+		select {
+		case evt := <-a.io.OutputChan():
+			if evt != nil && evt.Type == "memory_candidate" {
+				seen = evt.Payload
+			}
+		default:
+			break drain
+		}
+	}
+	if seen == nil {
+		t.Fatal("没有观察到 memory_candidate 输出")
+	}
+	if s, _ := seen["input"].(string); strings.Contains(s, tok) {
+		t.Errorf("记忆候选 input 含明文: %q", s)
+	}
+	if s, _ := seen["response"].(string); strings.Contains(s, tok) {
+		t.Errorf("记忆候选 response 含明文: %q", s)
+	}
+	if trs, ok := seen["tool_results"].([]ToolResultItem); ok {
+		for _, tr := range trs {
+			if strings.Contains(tr.Output, tok) {
+				t.Errorf("记忆候选 tool_results 含明文: %q", tr.Output)
+			}
+		}
+	}
+	if store.Count() == 0 {
+		t.Error("应登记变量")
+	}
+}
diff --git a/internal/agent/core/plugins.go b/internal/agent/core/plugins.go
index f3b31444..43b506cc 100644
--- a/internal/agent/core/plugins.go
+++ b/internal/agent/core/plugins.go
@@ -80,6 +80,8 @@ var builtinToolOwner = map[string]string{
 	"llm_list_sources": "core", "llm_set_source": "core", "llm_current_source": "core",
 	"plgreload": "core", "get_plugin_tools": "core", "list_devices": "core",
 	"devicedetect": "core", "device_ctl_status": "core", "device_ctl_cmdrun": "core",
+	// 安全模块的变量库（内核能力，不是插件）
+	"secret_submit": "core", "secret_list": "core", "secret_forget": "core",
 	"device_ctl_cmdresult": "core", "screensee": "core",
 }
 
diff --git a/internal/agent/core/secret_tools.go b/internal/agent/core/secret_tools.go
new file mode 100644
index 00000000..7bbfd15c
--- /dev/null
+++ b/internal/agent/core/secret_tools.go
@@ -0,0 +1,154 @@
+package core
+
+// 安全模块的**面向 agent 的工具族**（文档 C8）。
+//
+// ## 为什么需要这几个工具
+//
+// 用户拍板的模型是：
+//
+//	变量 = 内核全局库；**不自动淘汰**，但 agent 可以**主动提交/删除**。
+//
+// 「不自动淘汰」意味着泄漏控制不能靠超时，只能靠 agent（或人）主动删。
+// 那就必须有工具能做这两件事 —— 否则「可主动删除」只是文档里的一句空话。
+//
+// ## ★ 设计红线：**永不返回明文**
+//
+// 这几个工具**只能引用别名，不能读回明文**（设计文档 S1）。一旦提供
+// 「取回明文」的接口，模型就能把明文写回上下文，整层防护作废 ——
+// 因为它会把明文交给 LLM，而那正是要避免的。
+//
+// 所以：
+//   · `secret_submit` 接受明文（这是唯一入口，且必须如此才能登记）
+//   · `secret_list` 只给元信息（别名、来源、命中次数）
+//   · `secret_forget` 按别名删除
+//   · **没有** `secret_get`
+//
+// ## 关于 secret_submit 的明文暴露面（文档 T10）
+//
+// 提交时明文会经过 context（模型输出的参数）。这是**已知且可接受**的：
+// 提交的目的是「让内核记住这个凭据」，而模型本来就是从这里知道的。
+// 真正要防的是「凭据被送到 LLM 之外或写进持久化」—— 那由
+// memory_scrub 与 provider 装饰器覆盖。
+//
+// 更安全的替代路径（`${ENV}` / `@file:`）留给后续（T10），
+// 当前先提供最直接的形态。
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+func (a *Agent) executeSecretTool(tc agentAPI.ToolCall) string {
+	s := security.Global()
+	if s == nil {
+		return "安全模块未启用（core.security.enabled=false），变量库不可用"
+	}
+	switch tc.Name {
+	case "secret_submit":
+		return a.execSecretSubmit(s, tc)
+	case "secret_list":
+		return a.execSecretList(s, tc)
+	case "secret_forget":
+		return a.execSecretForget(s, tc)
+	}
+	return "未知的 secret 工具: " + tc.Name
+}
+
+// execSecretSubmit 主动登记一条凭据，返回其别名。
+//
+// 用途：agent 知道后面要用某个凭据（如刚读到的 token），
+// 先登记它，后续在工具参数里用 @{别名} 引用。
+func (a *Agent) execSecretSubmit(s *security.Store, tc agentAPI.ToolCall) string {
+	value, _ := tc.Arguments["value"].(string)
+	if strings.TrimSpace(value) == "" {
+		return "value 不能为空"
+	}
+	note, _ := tc.Arguments["note"].(string)
+	alias, err := s.Submit(value, note)
+	if err != nil {
+		// 无密钥等情况：**响亮失败**，不静默存明文。
+		return fmt.Sprintf("登记失败（未以明文降级存储）: %v", err)
+	}
+	// ★ 只回别名，绝不回明文 —— 否则这个工具就成了"明文读回接口"。
+	return fmt.Sprintf("已登记为变量 @{%s}。后续调用请用 @{%s} 引用，不要直接写明文。", alias, alias)
+}
+
+// execSecretList 列出变量元信息（**不含明文**）。
+func (a *Agent) execSecretList(s *security.Store, tc agentAPI.ToolCall) string {
+	infos := s.List()
+	if len(infos) == 0 {
+		return "变量库为空。用 secret_submit 登记凭据。"
+	}
+	// 稳定排序：便于人/模型对照（map 遍历顺序是随机的）。
+	sort.Slice(infos, func(i, j int) bool { return infos[i].Alias < infos[j].Alias })
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "共 %d 个变量（只显示元信息，明文不可读回）：\n", len(infos))
+	for _, in := range infos {
+		fmt.Fprintf(&b, "  @{%s}", in.Alias)
+		if in.Note != "" {
+			fmt.Fprintf(&b, "  %s", in.Note)
+		}
+		fmt.Fprintf(&b, "  [来源 %s, 命中 %d]", in.Source, in.Hits)
+		if in.CreatedAt != "" {
+			fmt.Fprintf(&b, "  建于 %s", in.CreatedAt)
+		}
+		b.WriteByte('\n')
+	}
+	b.WriteString("\n在工具参数里用 @{别名} 引用即可（内核会换回真实值，插件无感知）。")
+	return b.String()
+}
+
+// execSecretForget 按别名删除一个变量。
+func (a *Agent) execSecretForget(s *security.Store, tc agentAPI.ToolCall) string {
+	alias, _ := tc.Arguments["alias"].(string)
+	alias = strings.TrimSpace(alias)
+	// 宽容一点：模型可能把 @{sec_xxx} 整个传进来
+	alias = strings.TrimPrefix(alias, "@{")
+	alias = strings.TrimSuffix(alias, "}")
+	if alias == "" {
+		return "alias 不能为空"
+	}
+	if err := s.Forget(alias); err != nil {
+		if err == security.ErrUnknownAlias {
+			return fmt.Sprintf("未找到变量 %s（用 secret_list 查看现有变量）", alias)
+		}
+		return fmt.Sprintf("删除失败: %v", err)
+	}
+	return fmt.Sprintf("已删除 %s。该别名不再可用。", alias)
+}
+
+// secretToolDefs 返回这几个工具的定义（供 buildToolDefs 注入）。
+//
+// 直接用 toolDef 构造，与其它内置工具同形 —— 免得两处各写一份 schema。
+func secretToolDefs() []interface{} {
+	return []interface{}{
+		toolDef("secret_submit",
+			"登记一条凭据（token/密钥/口令）到内核变量库，返回别名。之后在工具参数里用 @{别名} 引用它 —— 内核会在调用插件前把别名换回真实值，插件完全无感知。用于：你刚读到一个凭据、后面要用它，但不想让明文反复出现在对话里。注意：明文只应在本次登记时出现一次。",
+			map[string]interface{}{
+				"value": map[string]interface{}{
+					"type":        "string",
+					"description": "凭据原文（只需在这里出现一次）",
+				},
+				"note": map[string]interface{}{
+					"type":        "string",
+					"description": "可选：给人看的用途说明（如「Gitea 推送令牌」）",
+				},
+			}, "value"),
+		toolDef("secret_list",
+			"列出内核变量库里的全部变量（只给别名与元信息，**不含明文** —— 明文无法读回，这是刻意设计）。用于查看有哪些可用变量、某变量是否已登记。",
+			map[string]interface{}{}),
+		toolDef("secret_forget",
+			"删除一个变量（按别名）。变量库**不会自动淘汰** —— 泄漏控制靠人/agent 主动删，所以凭据用完后应主动删除。",
+			map[string]interface{}{
+				"alias": map[string]interface{}{
+					"type":        "string",
+					"description": "要删除的别名（sec_xxx 或 @{sec_xxx} 均可）",
+				},
+			}, "alias"),
+	}
+}
diff --git a/internal/agent/core/secret_tools_test.go b/internal/agent/core/secret_tools_test.go
new file mode 100644
index 00000000..31ba95c3
--- /dev/null
+++ b/internal/agent/core/secret_tools_test.go
@@ -0,0 +1,191 @@
+package core
+
+// 判据：agent 面向的变量库工具（文档 C8）。
+//
+// 设计红线（文档 S1）：**永不返回明文**。
+// 一旦有"取回明文"的路径，模型就能把明文写回上下文，整层防护作废。
+// 下面的判据把这条红线钉死。
+
+import (
+	"strings"
+	"testing"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+const c8Token = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+func newSecretToolAgent(t *testing.T) (*Agent, *security.Store) {
+	t.Helper()
+	store := newScrubStore(t) // 复用已有的测试夹具
+	a := New(AgentConfig{
+		ID:              "c8",
+		ProviderManager: agentAPI.NewProviderManager(),
+		StageHost:       NewStageHost(),
+	})
+	return a, store
+}
+
+func callSecret(a *Agent, name string, args map[string]interface{}) string {
+	return a.executeSecretTool(agentAPI.ToolCall{Name: name, Arguments: args})
+}
+
+// ★★ 判据：secret_submit 登记后**只返回别名，不回显明文**。
+func TestSecretSubmitReturnsAliasNotPlaintext(t *testing.T) {
+	a, store := newSecretToolAgent(t)
+
+	out := callSecret(a, "secret_submit", map[string]interface{}{
+		"value": c8Token, "note": "测试令牌",
+	})
+	if strings.Contains(out, c8Token) {
+		t.Fatalf("★ 违反 S1：secret_submit 回显了明文: %q", out)
+	}
+	if !strings.Contains(out, "@{sec_") {
+		t.Fatalf("应返回别名: %q", out)
+	}
+	if store.Count() != 1 {
+		t.Fatalf("应登记 1 条，实际 %d", store.Count())
+	}
+	// 别名可用：回填能换回明文
+	alias := store.List()[0].Alias
+	if got, _, _ := store.Fill("@" + "{" + alias + "}"); !strings.Contains(got, c8Token) {
+		t.Error("别名应能回填出明文（这是唯一通道）")
+	}
+}
+
+// ★★ 判据：**secret_list 绝不泄露明文**（S1 的核心）。
+func TestSecretListNeverLeaksPlaintext(t *testing.T) {
+	a, _ := newSecretToolAgent(t)
+	callSecret(a, "secret_submit", map[string]interface{}{"value": c8Token, "note": "n"})
+
+	out := callSecret(a, "secret_list", nil)
+	if strings.Contains(out, c8Token) {
+		t.Fatalf("★ 违反 S1：secret_list 泄露了明文: %q", out)
+	}
+	if !strings.Contains(out, "@{sec_") {
+		t.Errorf("应列出别名: %q", out)
+	}
+	if !strings.Contains(out, "明文不可读回") {
+		t.Error("应明确告知明文不可读回（防模型反复尝试）")
+	}
+}
+
+// ★ 判据：**不存在 secret_get**（防回归：有人加了它，这条会指出为什么不行）。
+func TestNoSecretGetTool(t *testing.T) {
+	a, _ := newSecretToolAgent(t)
+	callSecret(a, "secret_submit", map[string]interface{}{"value": c8Token})
+
+	out := callSecret(a, "secret_get", map[string]interface{}{"alias": "sec_x"})
+	if !strings.Contains(out, "未知的 secret 工具") {
+		t.Fatalf("不应存在 secret_get（会把明文交回模型）: %q", out)
+	}
+	// 工具表里也不能有
+	for _, d := range secretToolDefs() {
+		m, _ := d.(map[string]interface{})
+		name, _ := m["name"].(string)
+		if name == "secret_get" || name == "secret_show" || name == "secret_reveal" {
+			t.Fatalf("工具表里出现了明文读回工具 %q —— 违反 S1", name)
+		}
+	}
+}
+
+// ★★ 判据：secret_forget 删除后别名失效，且**不自动淘汰**。
+func TestSecretForgetRemovesAndNoAutoEviction(t *testing.T) {
+	a, store := newSecretToolAgent(t)
+	callSecret(a, "secret_submit", map[string]interface{}{"value": c8Token})
+	alias := store.List()[0].Alias
+
+	// 宽容传参：@{sec_xxx} 与裸别名都可
+	if out := callSecret(a, "secret_forget", map[string]interface{}{
+		"alias": "@{" + alias + "}",
+	}); !strings.Contains(out, "已删除") {
+		t.Fatalf("删除应成功: %q", out)
+	}
+	if store.Count() != 0 {
+		t.Fatalf("删除后应为空，实际 %d", store.Count())
+	}
+	if got, n, _ := store.Fill("@" + "{" + alias + "}"); n != 0 || strings.Contains(got, c8Token) {
+		t.Error("删除后别名不应再回填")
+	}
+	// 重复删 → 明确提示（不是静默成功）
+	if out := callSecret(a, "secret_forget", map[string]interface{}{"alias": alias}); !strings.Contains(out, "未找到") {
+		t.Errorf("重复删除应明确提示: %q", out)
+	}
+}
+
+// ★ 判据：空值提交被拒（不是静默登记一个空变量）。
+func TestSecretSubmitRejectsEmpty(t *testing.T) {
+	a, store := newSecretToolAgent(t)
+	for _, v := range []string{"", "   "} {
+		if out := callSecret(a, "secret_submit", map[string]interface{}{"value": v}); !strings.Contains(out, "不能为空") {
+			t.Errorf("空值应被拒: %q", out)
+		}
+	}
+	if store.Count() != 0 {
+		t.Error("空值不应入库")
+	}
+}
+
+// ★ 判据：安全模块未启用时，工具明确报不可用（不静默失败）。
+func TestSecretToolsReportUnavailable(t *testing.T) {
+	dir := t.TempDir()
+	_ = dir
+	security.SetGlobal(nil)
+	defer newScrubStore(t) // 复原给后续判据
+
+	a := New(AgentConfig{ID: "c8-off", StageHost: NewStageHost()})
+	out := callSecret(a, "secret_list", nil)
+	if !strings.Contains(out, "未启用") {
+		t.Fatalf("未启用时应明确报不可用: %q", out)
+	}
+}
+
+// ★ 判据：未启用时**不向模型暴露**这些工具（避免无谓往返）。
+func TestSecretToolsHiddenWhenDisabled(t *testing.T) {
+	security.SetGlobal(nil)
+	a := New(AgentConfig{ID: "c8-hidden", StageHost: NewStageHost()})
+
+	var names []string
+	for _, d := range a.buildToolDefs() {
+		m, ok := d.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		fn, _ := m["function"].(map[string]interface{})
+		if fn == nil {
+			fn = m
+		}
+		if n, _ := fn["name"].(string); strings.HasPrefix(n, "secret_") {
+			names = append(names, n)
+		}
+	}
+	if len(names) > 0 {
+		t.Fatalf("未启用安全模块时不应暴露 secret_* 工具: %v", names)
+	}
+}
+
+// ★ 判据：启用时**要暴露**（否则模型不知道能用）。
+func TestSecretToolsExposedWhenEnabled(t *testing.T) {
+	newScrubStore(t)
+	a := New(AgentConfig{ID: "c8-shown", StageHost: NewStageHost()})
+
+	got := map[string]bool{}
+	for _, d := range a.buildToolDefs() {
+		m, ok := d.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		// toolDef 返回的是 {"type":"function","function":{...}}
+		if fn, ok := m["function"].(map[string]interface{}); ok {
+			if n, _ := fn["name"].(string); strings.HasPrefix(n, "secret_") {
+				got[n] = true
+			}
+		}
+	}
+	for _, want := range []string{"secret_submit", "secret_list", "secret_forget"} {
+		if !got[want] {
+			t.Errorf("启用后应暴露 %s；实际得到 %v", want, got)
+		}
+	}
+}
diff --git a/internal/agent/core/security_concurrency_test.go b/internal/agent/core/security_concurrency_test.go
new file mode 100644
index 00000000..115e594f
--- /dev/null
+++ b/internal/agent/core/security_concurrency_test.go
@@ -0,0 +1,287 @@
+package core
+
+// 安全模块的**端到端并发压测**。
+//
+// ## 为什么必须做
+//
+// 安全模块挂在每次 LLM 调用与每次工具调用的必经路径上，而内核是
+// **并发**的：多 agent、多任务、调度器并行、插件回调各自的 goroutine。
+//
+// security 包自己的并发判据只验了 Store 内部；
+// **Store 的使用方**（provider 装饰器、ExecuteTool、Append、emitMemoryCandidate）
+// 是否并发安全，只有让真实 Agent 并跑才看得出来。
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+// ★★ 判据：**多 agent 并发出向** —— 明文一律不得泄漏到 provider。
+//
+// 每个 agent 有自己的 provider 实例，但它们共享**同一个**
+// ProviderManager 装饰器与变量库单例（这正是设计要验的点）。
+func TestConcurrency_MultiAgentOutboundScrub(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	const agents = 16
+	const rounds = 40
+
+	var leaked atomic.Int64
+	var wg sync.WaitGroup
+
+	for a := 0; a < agents; a++ {
+		wg.Add(1)
+		go func(a int) {
+			defer wg.Done()
+			var captured string
+			mgr := agentAPI.NewProviderManager()
+			mgr.Register("p", &fwCaptureProvider{name: "p", capture: &captured})
+			p := mgr.Default()
+
+			for r := 0; r < rounds; r++ {
+				// 并发登记（同明文 ⇒ 应合并到同一别名）
+				if _, err := store.Submit(tok, "conc"); err != nil {
+					t.Errorf("Submit: %v", err)
+					return
+				}
+				req := &agentAPI.CompletionRequest{Messages: []agentAPI.Message{
+					{Role: "user", Content: fmt.Sprintf("agent%d round%d token=%s", a, r, tok)},
+				}}
+				if _, err := p.Chat(nil, req); err != nil { //nolint:staticcheck
+					t.Errorf("Chat: %v", err)
+					return
+				}
+				if strings.Contains(captured, tok) {
+					leaked.Add(1)
+				}
+			}
+		}(a)
+	}
+	wg.Wait()
+
+	if leaked.Load() > 0 {
+		t.Fatalf("★ 并发下 %d 次出向泄漏明文（装饰器不是并发安全的）", leaked.Load())
+	}
+	// 同明文必须合并成一条
+	if got := store.Count(); got != 1 {
+		t.Errorf("★ 同明文并发登记应合并为 1 条，实际 %d", got)
+	}
+	t.Logf("✅ %d agent × %d 轮并发出向，零泄漏；变量库 1 条", agents, rounds)
+}
+
+// ★★ 判据：**并发工具调用** —— 参数回填不串号。
+//
+// 真实风险：A 的工具参数里的别名被填成 B 的凭据（串号），
+// 这会造成"用了错的凭据"且**不报错**。
+func TestConcurrency_ToolArgsDoNotCrossTalk(t *testing.T) {
+	store := newScrubStore(t)
+	a, _, _ := newRootForResidents(t)
+
+	// 每个 goroutine 用**自己**的凭据与别名
+	const workers = 12
+	aliases := make([]string, workers)
+	plains := make([]string, workers)
+	for i := 0; i < workers; i++ {
+		plains[i] = fmt.Sprintf("distinct-secret-%02d-aaaaaaaaaaaaaaaaaaaa", i)
+		al, err := store.Submit(plains[i], fmt.Sprintf("w%d", i))
+		if err != nil {
+			t.Fatal(err)
+		}
+		aliases[i] = al
+	}
+
+	var mixed atomic.Int64
+	var wg sync.WaitGroup
+	for i := 0; i < workers; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			var seen string
+			tool := fmt.Sprintf("conc_tool_%d", i)
+			// 每个 goroutine 注册自己的工具（StageHost 的注册是加锁的）
+			if err := a.stageHost.RegisterTool(tool, sdk.ToolDef{
+				Name: tool, Description: "并发压测",
+				Parameters: map[string]interface{}{"type": "object"},
+			}, func(args map[string]interface{}) (interface{}, error) {
+				seen, _ = args["secret"].(string)
+				return "ok", nil
+			}); err != nil {
+				t.Errorf("RegisterTool: %v", err)
+				return
+			}
+			for r := 0; r < 60; r++ {
+				seen = ""
+				if _, err := a.stageHost.ExecuteTool(tool, map[string]interface{}{
+					"secret": "@{" + aliases[i] + "}",
+				}); err != nil {
+					t.Errorf("ExecuteTool: %v", err)
+					return
+				}
+				// ★ 必须填成**自己的**那个，不能是别人的
+				if seen != plains[i] {
+					mixed.Add(1)
+					return
+				}
+			}
+		}(i)
+	}
+	wg.Wait()
+
+	if mixed.Load() > 0 {
+		t.Fatal("★ 并发工具调用发生**串号**（填成了别的凭据）—— 用错凭据且不报错")
+	}
+	t.Logf("✅ %d goroutine × 60 轮并发工具调用，零串号", workers)
+}
+
+// ★★ 判据：**并发上下文写入**（Append 咽喉的 scrub）不丢不串。
+func TestConcurrency_ConcurrentContextScrub(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	if _, err := store.Submit(tok, "ctx"); err != nil {
+		t.Fatal(err)
+	}
+
+	a, _, _ := newRootForResidents(t)
+
+	const writers = 10
+	const perWriter = 50
+	var wg sync.WaitGroup
+	for w := 0; w < writers; w++ {
+		wg.Add(1)
+		go func(w int) {
+			defer wg.Done()
+			for i := 0; i < perWriter; i++ {
+				a.context.Append(ContextEvent{
+					Source:   fmt.Sprintf("w%d", w),
+					Input:    fmt.Sprintf("in %d token=%s", i, tok),
+					Response: "out contains " + tok,
+					ToolResults: []ToolResultItem{
+						{Name: "t", Output: "tool " + tok},
+					},
+				})
+			}
+		}(w)
+	}
+	wg.Wait()
+
+	// 全部事件都不该含明文
+	bad := 0
+	for _, evt := range a.context.Recent(0) {
+		if strings.Contains(evt.Input, tok) || strings.Contains(evt.Response, tok) {
+			bad++
+		}
+		for _, tr := range evt.ToolResults {
+			if strings.Contains(tr.Output, tok) {
+				bad++
+			}
+		}
+	}
+	if bad > 0 {
+		t.Fatalf("★ 并发写入下有 %d 处明文未被拦下", bad)
+	}
+	if n := a.context.Len(); n < writers*perWriter {
+		t.Errorf("并发写入丢事件：期望至少 %d，实际 %d", writers*perWriter, n)
+	}
+	t.Logf("✅ %d goroutine × %d 次并发写入全部拦下（事件数 %d）",
+		writers, perWriter, a.context.Len())
+}
+
+// ★★ 判据：**并发记忆候选**（emitMemoryCandidate 的 scrub）。
+func TestConcurrency_ConcurrentMemoryCandidate(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	if _, err := store.Submit(tok, "mem"); err != nil {
+		t.Fatal(err)
+	}
+
+	a := New(AgentConfig{
+		ID:              "conc-mem",
+		Provider:        &plainReplyProvider{},
+		ProviderManager: agentAPI.NewProviderManager(),
+		IO:              agentIO.NewIOManager(),
+		StageHost:       NewStageHost(),
+	})
+
+	const n = 200
+	var wg sync.WaitGroup
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			a.emitMemoryCandidate("src",
+				fmt.Sprintf("in %d %s", i, tok),
+				"resp "+tok,
+				[]ToolResultItem{{Name: "t", Output: "tool " + tok}},
+				[]string{"t"})
+		}(i)
+	}
+	wg.Wait()
+
+	// 排空输出，逐条检查载荷
+	leaked := 0
+	got := 0
+	for {
+		select {
+		case evt := <-a.io.OutputChan():
+			if evt == nil || evt.Type != "memory_candidate" {
+				continue
+			}
+			got++
+			if s, _ := evt.Payload["input"].(string); strings.Contains(s, tok) {
+				leaked++
+			}
+			if s, _ := evt.Payload["response"].(string); strings.Contains(s, tok) {
+				leaked++
+			}
+			if trs, ok := evt.Payload["tool_results"].([]ToolResultItem); ok {
+				for _, tr := range trs {
+					if strings.Contains(tr.Output, tok) {
+						leaked++
+					}
+				}
+			}
+		default:
+			goto done
+		}
+	}
+done:
+	if leaked > 0 {
+		t.Fatalf("★ 并发记忆候选中 %d 处含明文（会写进长期记忆）", leaked)
+	}
+	if got == 0 {
+		t.Fatal("没有观察到记忆候选 —— 判据无效")
+	}
+	t.Logf("✅ %d 条并发记忆候选全部已清洗", got)
+}
+
+// ★ 判据：并发守卫（未启用安全模块）时零成本且不 panic。
+func TestConcurrency_DisabledIsSafe(t *testing.T) {
+	security.SetGlobal(nil)
+	t.Cleanup(func() { newScrubStore(t) })
+
+	a, _, _ := newRootForResidents(t)
+
+	var wg sync.WaitGroup
+	for i := 0; i < 20; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			a.context.Append(ContextEvent{
+				Source: "s", Input: "in", Response: "out",
+				ToolResults: []ToolResultItem{{Name: "t", Output: "o"}},
+			})
+			a.emitMemoryCandidate("s", "in", "out", nil, nil)
+		}(i)
+	}
+	wg.Wait()
+	t.Log("✅ 未启用时并发调用不 panic")
+}
diff --git a/internal/agent/core/stage.go b/internal/agent/core/stage.go
index 06cedddf..afe2ebac 100644
--- a/internal/agent/core/stage.go
+++ b/internal/agent/core/stage.go
@@ -53,13 +53,18 @@ func (a *Agent) publishEvent(evtType events.EventType, payload map[string]interf
 }
 
 func (a *Agent) stageCtxFromInput(input, userID, groupID string) *sdk.StageContext {
-	return &sdk.StageContext{
+	ctx := &sdk.StageContext{
 		RawMessage: input,
 		UserID:     userID,
 		GroupID:    groupID,
 		Phase:      sdk.StageOnInput,
 		Extra:      make(map[string]interface{}),
 	}
+	// ★ 来源标识必须在**帧的起点**就写入，不能只写在工具帧上：
+	// 插件可能在 on_input 阶段就据此决定是否介入（而那个阶段早于工具帧构造）。
+	// 见 comefrom.go 的完整说明。
+	stampComeFrom(ctx.Extra, a.comefromForAgent())
+	return ctx
 }
 
 func (a *Agent) injectSourceContext(stageCtx *sdk.StageContext, evt *agentIO.InputEvent) {
diff --git a/internal/agent/core/stages.go b/internal/agent/core/stages.go
index a9f6e001..43b7f653 100644
--- a/internal/agent/core/stages.go
+++ b/internal/agent/core/stages.go
@@ -7,10 +7,15 @@ import (
 	"sync"
 
 	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
 )
 
 type StageHost struct {
+	// frozenFn 报告内核是否处于伪关机（迁移中）。nil = 永不冻结。
+	// 用函数而不是直接引用 plugin.Registry，避免 agent/core 反向依赖 plugin 包。
+	frozenFn    func() bool
 	mu          sync.RWMutex
 	toolDefs    []sdk.ToolDef
 	tools       map[string]sdk.ToolHandler
@@ -156,6 +161,16 @@ func (h *StageHost) ExecuteTool(name string, args map[string]interface{}) (ret i
 	if handler == nil {
 		return nil, fmt.Errorf("tool %s has nil handler", name)
 	}
+	// ★ 安全模块入向回填：这里是**插件工具调用的唯一入口**，
+	// 填在这里就覆盖了全部插件 —— 插件本身完全无感知。
+	//
+	// 为何必须填而不是拒绝：模型手上只有别名（它从未见过明文），
+	// 而插件需要真凭据。回填是二者之间唯一的通道。
+	if s := security.Global(); s != nil && args != nil {
+		if n, used := s.FillMap(args); n > 0 {
+			log.Printf("[security] 工具 %s 参数回填 %d 处（别名 %v）", name, n, used)
+		}
+	}
 	return handler(args)
 }
 
@@ -237,6 +252,7 @@ func (h *StageHost) RunStage(stage sdk.Stage, ctx *sdk.StageContext) {
 	}
 	var wg sync.WaitGroup
 	errCh := make(chan error, len(entries))
+	var errChOnce sync.Once
 	for _, entry := range entries {
 		wg.Add(1)
 		go func(fn sdk.StageHandler) {
@@ -252,7 +268,7 @@ func (h *StageHost) RunStage(stage sdk.Stage, ctx *sdk.StageContext) {
 		}(entry.fn)
 	}
 	wg.Wait()
-	close(errCh)
+	safeclose.Safe(&errChOnce, errCh)
 
 	var errs []string
 	for err := range errCh {
diff --git a/internal/agent/core/task.go b/internal/agent/core/task.go
index ecaa63fc..61b54f51 100644
--- a/internal/agent/core/task.go
+++ b/internal/agent/core/task.go
@@ -534,6 +534,8 @@ func (a *Agent) finishInputTask(f *TaskFrame, out stepOutcome) {
 		ToolResults: f.ToolResults,
 	}
 	a.bindEventMedia(&turnEvt, a.drainMediaBlocks())
+	// ★ 明文拦截发生在 a.context.Append **内部**（见 context.go 的 Append），
+	// 不是在每个调用点 —— 写 context 的地方有 5 处，逐个补必漏。
 	a.context.Append(turnEvt)
 
 	a.emitResponse(evt, f.Response, f.turnUsage)
@@ -1353,6 +1355,15 @@ func (f *TaskFrame) buildToolContexts() {
 			Extra:    copyExtraMap(base.Extra),
 			NoMemory: base.NoMemory,
 		}
+		// ★ **工具调用帧必须带来源标识**（comefrom）：
+		// 通道插件的权限门（before_toolcall）靠它区分"这是用户请求"还是
+		// "这是 agent 内部委派"。缺了它，驻留子的工具调用会被按**用户**
+		// 权限模型判定 ⇒ 合法工作全被拦（2026-10-16 现场实证，见 comefrom.go）。
+		//
+		// 从 base 继承（StageCtx 已由 stageCtxFromInput 标过）；copyExtraMap
+		// 会把该键一并复制，这里只在因某种路径缺失时补一个**保守值**
+		// （保守 = 按旧语义当作用户请求，宁可多查一次也不再出现"静默越权"）。
+		stampComeFrom(f.toolCtxs[i].Extra, comeFromUser)
 		// Phase 由 runStage 每次调用时设置，此处不预置。
 	}
 }
diff --git a/internal/agent/core/toolcall.go b/internal/agent/core/toolcall.go
index 4b576e4a..4daefbf0 100644
--- a/internal/agent/core/toolcall.go
+++ b/internal/agent/core/toolcall.go
@@ -122,6 +122,8 @@ func (a *Agent) executeToolCallInner(tc agentAPI.ToolCall, channel string, turnS
 		return toolOutcome{Text: a.executeChildResultTool(tc)}
 	case strings.HasPrefix(tc.Name, "llm_"):
 		return toolOutcome{Text: a.executeLLMTool(tc)}
+	case strings.HasPrefix(tc.Name, "secret_"):
+		return toolOutcome{Text: a.executeSecretTool(tc)}
 		// ★★ 2026-10-06：describe_image / transcribe_audio / ocr_image 已移出内核，
 		//   改为内置插件 multimodal（见 internal/plugins/multimodal）。
 		//   理由：它们要读本地文件（IO），而内核承诺零 IO。
diff --git a/internal/agent/core/tooldefs.go b/internal/agent/core/tooldefs.go
index 96ad7406..0f6047ae 100644
--- a/internal/agent/core/tooldefs.go
+++ b/internal/agent/core/tooldefs.go
@@ -9,6 +9,7 @@ import (
 	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
 	"github.com/JianFeeeee/HomeAgent/internal/meta"
 	"github.com/JianFeeeee/HomeAgent/internal/sdk"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
 	sdkmeta "github.com/JianFeeeee/homeagentsdk/meta"
 )
 
@@ -356,6 +357,8 @@ func init() {
 		"get_plugin_tools", "llm_list_sources",
 		// 文档：检索
 		"doc_query",
+		// 安全模块：列举变量（只读，无共享写）
+		"secret_list",
 	} {
 		declareParallelTool(name)
 	}
@@ -403,6 +406,14 @@ func (a *Agent) buildToolDefs() []interface{} {
 		}, "mode"))
 	}
 
+	// 安全模块的变量库工具（文档 C8）。
+	//
+	// 仅当安全模块真的启用时才暴露：未启用时变量库不可用，
+	// 把工具给模型只会让它反复撞到"安全模块未启用"（无谓往返）。
+	if security.Global() != nil {
+		tools = append(tools, secretToolDefs()...)
+	}
+
 	if a.memory != nil {
 		tools = append(tools, toolDef("memory_merge", "【记忆清理】合并两个同义实体。将所有关系从 source 重定向到 target，然后彻底删除 source。注意：实体删除后不可恢复，合并前请确认语义一致。", map[string]interface{}{
 			"source": map[string]interface{}{"type": "string", "description": "被合并的实体名（合并后消失）"},
diff --git a/internal/agent/core/toolresult_scrub_test.go b/internal/agent/core/toolresult_scrub_test.go
new file mode 100644
index 00000000..33391e46
--- /dev/null
+++ b/internal/agent/core/toolresult_scrub_test.go
@@ -0,0 +1,222 @@
+package core
+
+// 判据：工具结果侧路的明文拦截（文档 C6）。
+//
+// ## 为什么这条侧路必须单独拦
+//
+// 出向拦截（provider 装饰器）只改 `f.Msgs`。但工具结果另有一条路经
+//
+//	turnEvt.ToolResults = f.ToolResults  →  a.context.Append  →  持久化历史
+//	                                                      ↘  emitMemoryCandidate → 长期记忆
+//
+// 到达**持久化存储**。先前实测确认这条路**不经过** provider 装饰器
+// （`TestToolResultsPathBypassesScrub` 的原始探针给出了阳性证据）。
+//
+// 后果：凭据被 LLM 看到之前虽然换成了别名，但早已从侧路进了跨会话保留、
+// 每轮被召回的长期记忆 —— 泄漏面比重放一次大得多。
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+func newScrubStore(t *testing.T) *security.Store {
+	t.Helper()
+	dir := t.TempDir()
+	s, err := security.InitGlobal(security.Options{
+		Path:    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) })
+	return s
+}
+
+// ★★ 判据：进 a.context 的工具结果不含明文（走 agent 的真实代码路径）。
+func TestToolResultsScrubbedBeforeHistory(t *testing.T) {
+	store := newScrubStore(t)
+	a, _, _ := newRootForResidents(t)
+
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	// 直接验证 scrub 逻辑本身（与 task.go 里那段同构）。
+	// 用真实 Store 而不是 mock，确保别名形态/落盘都一致。
+	items := []ToolResultItem{
+		{Name: "cmd_run", Output: "部署用的 token 是 " + tok + " ，请使用"},
+		{Name: "read_file", Output: "普通内容，不该被改"},
+	}
+	scrubbed := make([]ToolResultItem, len(items))
+	copy(scrubbed, items)
+	for i := range scrubbed {
+		if out, evts := store.Replace(scrubbed[i].Output,
+			"tool_result:"+scrubbed[i].Name, security.Patterns); len(evts) > 0 {
+			scrubbed[i].Output = out
+		}
+	}
+
+	if strings.Contains(scrubbed[0].Output, tok) {
+		t.Fatalf("工具结果仍含明文，会进持久化记忆: %q", scrubbed[0].Output)
+	}
+	if !strings.Contains(scrubbed[0].Output, "@{sec_") {
+		t.Errorf("应含别名提示: %q", scrubbed[0].Output)
+	}
+	if scrubbed[1].Output != items[1].Output {
+		t.Errorf("无关结果不应被改动: %q", scrubbed[1].Output)
+	}
+	// 原始切片不受影响（我们显式拷贝 —— 与 Msgs 的原地改写不同，见下）
+	if !strings.Contains(items[0].Output, tok) {
+		t.Error("不应改动调用方的原始切片（f.ToolResults 仍被其它路径读取）")
+	}
+	_ = a
+}
+
+// ★ 判据：**工具结果路径用拷贝而非原地改写** —— 与 f.Msgs 的取舍相反。
+//
+// 为何不同：`f.ToolResults` 在同一轮里可能被其它代码读到（如
+// `f.ToolsUsed` 之外的诊断、状态面渲染），原地改会让它们看到替换后的文本；
+// 而 `f.Msgs` 本来就是「要发出去的那一份」，原地改正是我们要的。
+//
+// 这个不对称是刻意的，判据把它钉住，免得后来者「统一」成一种写法。
+func TestToolResultsScrubDoesNotMutateSource(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	src := []ToolResultItem{{Name: "t", Output: tok}}
+	dst := make([]ToolResultItem, len(src))
+	copy(dst, src)
+	for i := range dst {
+		dst[i].Output, _ = store.Replace(dst[i].Output, "tool_result", security.Patterns)
+	}
+	if dst[0].Output == src[0].Output {
+		t.Fatal("拷贝出来的应被改写（否则拦截没生效）")
+	}
+	if src[0].Output != tok {
+		t.Fatal("原始 f.ToolResults 不应被改动 —— 它还被其它路径读取")
+	}
+}
+
+// ★★ 决定性判据：**走真实调度循环**，工具返回的明文不得进 a.context。
+//
+// 上面两条判据复刻了 scrub 逻辑。这条不同 —— 它跑真实的
+// `a.Start()` + 注入 + 工具回环 + finishInputTask，然后读 `a.context`
+// 看实际落进去的是什么。若我只在 task.go 里写错位置（比如放在
+// Append 之后、或忘了给 emitMemoryCandidate 用过滤后的副本），
+// 只有这条会报红。
+func TestE2E_ToolResultSecretNeverReachesContext(t *testing.T) {
+	store := newScrubStore(t)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	a := New(AgentConfig{
+		ID:              "e2e-trscrub",
+		Provider:        &secretToolProvider{},
+		ProviderManager: agentAPI.NewProviderManager(),
+		IO:              agentIO.NewIOManager(),
+		StageHost:       NewStageHost(),
+	})
+
+	// 注册一个会吐出凭据的工具（模拟 cmd_run 读了 .env）
+	if err := a.stageHost.RegisterTool("secretecho", sdk.ToolDef{
+		Name: "secretecho", Description: "回显凭据",
+		Parameters: map[string]interface{}{"type": "object"},
+	}, func(map[string]interface{}) (interface{}, error) {
+		return "credential=" + tok, nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	a.Start()
+	defer a.Stop()
+
+	if out := a.io.InjectTextSync("http", "查一下凭据"); out == nil {
+		t.Fatal("同步注入没有回执")
+	}
+
+	// ★ 读真实 context：明文不得出现在任何事件里
+	found := false
+	for _, evt := range a.context.Recent(0) {
+		for _, tr := range evt.ToolResults {
+			if strings.Contains(tr.Output, tok) {
+				found = true
+				t.Errorf("工具结果明文进了 a.context（持久化记忆的源头）: %q", tr.Output)
+			}
+		}
+		if strings.Contains(evt.Response, tok) || strings.Contains(evt.Input, tok) {
+			t.Errorf("事件正文含明文: input=%q response=%q", evt.Input, evt.Response)
+		}
+	}
+	if found {
+		t.Fatal("★ 侧路泄漏：出向拦截挡不住工具结果进记忆")
+	}
+
+	// ★ 第二条侧路：memory_candidate。它经 EmitOutput 把 tool_results
+	// 交给记忆管线（distill.go:607），**不经过 a.context**。
+	// 只看 a.context 会漏掉这条（变异实验 C6-M2 证实了这个盲区）。
+	memLeak := false
+drain:
+	for {
+		select {
+		case evt := <-a.io.OutputChan():
+			if evt == nil || evt.Type != "memory_candidate" {
+				continue
+			}
+			if trs, ok := evt.Payload["tool_results"].([]ToolResultItem); ok {
+				for _, tr := range trs {
+					if strings.Contains(tr.Output, tok) {
+						memLeak = true
+						t.Errorf("记忆候选里的工具结果含明文（会写进长期记忆）: %q", tr.Output)
+					}
+				}
+			}
+		default:
+			break drain
+		}
+	}
+	if memLeak {
+		t.Fatal("★ 记忆侧路泄漏")
+	}
+	// 确认确实发生了拦截（否则可能是工具压根没被调用，判据假绿）
+	if store.Count() == 0 {
+		t.Fatal("变量库为空 —— 说明工具没被调用或没拦截，本判据无效")
+	}
+	t.Logf("✅ 工具回环后 a.context 无明文；变量库已登记 %d 条", store.Count())
+}
+
+// secretToolProvider 第一轮请求调工具，第二轮给最终答复。
+type secretToolProvider struct{ round int }
+
+func (p *secretToolProvider) Name() string          { return "secretTool" }
+func (p *secretToolProvider) MaxContextTokens() int { return 8192 }
+
+func (p *secretToolProvider) next() *agentAPI.CompletionResponse {
+	p.round++
+	if p.round == 1 {
+		return &agentAPI.CompletionResponse{
+			Content: "让我查一下",
+			ToolCalls: []agentAPI.ToolCall{
+				{ID: "c1", Name: "secretecho", Arguments: map[string]interface{}{}},
+			},
+		}
+	}
+	return &agentAPI.CompletionResponse{Content: "查完了"}
+}
+
+func (p *secretToolProvider) Chat(_ context.Context, _ *agentAPI.CompletionRequest) (*agentAPI.CompletionResponse, error) {
+	return p.next(), nil
+}
+
+func (p *secretToolProvider) ChatStream(_ context.Context, _ *agentAPI.CompletionRequest) (<-chan agentAPI.StreamChunk, error) {
+	ch := make(chan agentAPI.StreamChunk, 1)
+	r := p.next()
+	ch <- agentAPI.StreamChunk{Content: r.Content, ToolCalls: r.ToolCalls, Done: true}
+	close(ch)
+	return ch, nil
+}
diff --git a/internal/agent/io/channel_test.go b/internal/agent/io/channel_test.go
index 80d96c2a..da5abb5e 100644
--- a/internal/agent/io/channel_test.go
+++ b/internal/agent/io/channel_test.go
@@ -20,10 +20,10 @@ type mockDevice struct {
 	mu             sync.Mutex
 }
 
-func (d *mockDevice) Name() string                           { return d.name }
-func (d *mockDevice) Type() DeviceType                       { return d.devType }
-func (d *mockDevice) Description() string                    { return d.desc }
-func (d *mockDevice) Tools() []ToolDef                       { return d.tools }
+func (d *mockDevice) Name() string        { return d.name }
+func (d *mockDevice) Type() DeviceType    { return d.devType }
+func (d *mockDevice) Description() string { return d.desc }
+func (d *mockDevice) Tools() []ToolDef    { return d.tools }
 func (d *mockDevice) Start() error {
 	d.mu.Lock()
 	d.startCallCount++
@@ -43,7 +43,7 @@ func (d *mockDevice) Stop() error {
 	return nil
 }
 func (d *mockDevice) OutputCapabilities() OutputCapability { return d.caps }
-func (d *mockDevice) ChannelDef() ChannelDef { return ChannelDef{} }
+func (d *mockDevice) ChannelDef() ChannelDef               { return ChannelDef{} }
 func (d *mockDevice) Execute(tool string, args map[string]interface{}) (interface{}, error) {
 	if d.executeFn != nil {
 		return d.executeFn(tool, args)
@@ -275,13 +275,13 @@ func TestExecuteToolNotFound(t *testing.T) {
 func TestListChannels(t *testing.T) {
 	m := NewIOManager()
 	m.RegisterDevice(&mockDevice{
-		name: "screen",
-		caps: CapText | CapImage,
+		name:    "screen",
+		caps:    CapText | CapImage,
 		devType: DeviceOutput,
 	})
 	m.RegisterDevice(&mockDevice{
-		name: "mic",
-		caps: 0,
+		name:    "mic",
+		caps:    0,
 		devType: DeviceInput,
 	})
 
diff --git a/internal/config/backup_diag_test.go b/internal/config/backup_diag_test.go
new file mode 100644
index 00000000..cef617ed
--- /dev/null
+++ b/internal/config/backup_diag_test.go
@@ -0,0 +1,93 @@
+package config
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+// ★★ E-2：备份来自**另一台机器**（密钥不同）时，审计必须报出“不可解”，
+// 而不是静默当明文/空值，也不是等到某个功能坏了才发现。
+//
+// 这是备份恢复场景的核心判据：db 能打开、表能读、但密文解不开 ——
+// 那种状态最容易被误判成“配置丢了”。
+func TestAuditSecretsDetectsForeignKeyBackup(t *testing.T) {
+	// 本包的 codec 是**进程级全局**，测试必须还原现场，
+	// 否则会把密钥泄漏给同包其它判据（实测：导致 GetInt 读到密文）。
+	t.Cleanup(security.ClearConfigCodec)
+	dir := t.TempDir()
+	keyA := []byte("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
+	keyB := []byte("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb")
+
+	// 机器 A：写入一条加密配置
+	security.ClearConfigCodec()
+	if _, err := security.InitConfigCodec(keyA); err != nil {
+		t.Fatal(err)
+	}
+	regA := NewConfigRegistry(filepath.Join(dir, "config.db"))
+	regA.RegisterDef(cfgDef("core.llm.api_key"))
+	if err := regA.Set("core.llm.api_key", "sk-machine-a"); err != nil {
+		t.Fatal(err)
+	}
+	ok, bad, err := regA.AuditSecrets()
+	if err != nil || ok != 1 || bad != 0 {
+		t.Fatalf("machine A 自审应为 ok=1 bad=0，实际 ok=%d bad=%d err=%v", ok, bad, err)
+	}
+	regA.Close()
+
+	// 机器 B：同一份 db，但密钥不同
+	security.ClearConfigCodec()
+	if _, err := security.InitConfigCodec(keyB); err != nil {
+		t.Fatal(err)
+	}
+	regB := NewConfigRegistry(filepath.Join(dir, "config.db"))
+	defer regB.Close()
+	ok2, bad2, err := regB.AuditSecrets()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if bad2 == 0 {
+		t.Fatal("★ 外来密钥的备份未被识别 —— 会被误判为「配置丢了」而非「密钥不匹配」")
+	}
+	if ok2 != 0 {
+		t.Errorf("外来密钥下可解条数应为 0，实际 %d", ok2)
+	}
+	// 读取该键必须**响亮报错**，不能把密文当明文交出去
+	if v, err := regB.Get("core.llm.api_key"); err == nil {
+		t.Fatalf("★ 密文解不开却返回了值: %v", v)
+	}
+}
+
+// ★ 同一密钥下重启（正常恢复）必须全部可解 —— 不能把正常备份误报成坏。
+func TestAuditSecretsCleanOnSameKey(t *testing.T) {
+	t.Cleanup(security.ClearConfigCodec)
+	dir := t.TempDir()
+	key := []byte("cccccccccccccccccccccccccccccccc")
+	security.ClearConfigCodec()
+	if _, err := security.InitConfigCodec(key); err != nil {
+		t.Fatal(err)
+	}
+	db := filepath.Join(dir, "config.db")
+	reg := NewConfigRegistry(db)
+	reg.RegisterDef(cfgDef("core.llm.api_key"))
+	if err := reg.Set("core.llm.api_key", "sk-1"); err != nil {
+		t.Fatal(err)
+	}
+	reg.Close()
+
+	if _, err := security.InitConfigCodec(key); err != nil {
+		t.Fatal(err)
+	}
+	reg2 := NewConfigRegistry(db)
+	defer reg2.Close()
+	ok, bad, err := reg2.AuditSecrets()
+	if err != nil || bad != 0 || ok != 1 {
+		t.Fatalf("同密钥重启应为 ok=1 bad=0，实际 ok=%d bad=%d err=%v", ok, bad, err)
+	}
+}
+
+// cfgDef 造一个最小 secret 键定义。
+func cfgDef(key string) ConfigDef {
+	return ConfigDef{Key: key, Type: "string", Secret: true}
+}
diff --git a/internal/config/registry.go b/internal/config/registry.go
index 997952f5..faa17111 100644
--- 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 {
diff --git a/internal/config/secret.go b/internal/config/secret.go
new file mode 100644
index 00000000..f3110ab7
--- /dev/null
+++ b/internal/config/secret.go
@@ -0,0 +1,408 @@
+package config
+
+// 配置落盘加密（敏感项 at-rest encryption）。
+//
+// ## 要解决的问题
+//
+// `config.db` 是 **0644 全局可读**的（它同目录还有 WAL/SHM），
+// 而里面装着 LLM API 密钥、WebUI 口令、插件凭据等 —— 任何本机用户
+// `sqlite3 config.db 'select * from config'` 就能拿到全部明文。
+//
+// ## 做法：在**存储边界**加密，读写接口不变
+//
+//	Set/Register/seed  →  Seal  →  DB 里是 `enc:v1:<base64>`
+//	Get/Dump/ToConfig  →  Open  →  调用方永远只看到明文
+//
+// ★ 关键取舍：**读接口保持"返回明文"**。
+//
+// 初稿曾考虑让 `Dump()` 返回掩码、让 WebUI 看不到明文。但那样会同时
+// 打断 `ToConfig()`（它靠 Dump 重建 LLMSource，含 api_key）与任何
+// 需要真实值的内部读取方 —— 而它们**本来就在可信边界内**。
+// 本需求要防的是「静态文件泄漏」，不是「内部读取」。
+//
+// ## 标记来源（两种都支持）
+//
+//	1. `ConfigDef.Secret == true`   ← SDK 里早就有这个字段，但从未被实现
+//	2. `ConfigDef.Type == "password"` / `"secret"`
+//
+// ## 无 def 的键怎么办
+//
+// 插件的 key 常常没有 def（`Set()` 可以直接写任意键）。
+// 所以还要靠**键名模式**兜底（`secretKeyPattern`），否则
+// `plugin.qq.token` 这类会被漏掉。
+
+import (
+	"database/sql"
+	"log"
+	"strings"
+
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+// secretSegmentPattern 是无 def 时的兜底判定。
+//
+// ## 为何不能直接 `strings.Contains(key, "token")`
+//
+// 初版就是这么写的，结果把这两个**非敏感**项也加密了：
+//
+//	core.llm.max_tokens                  ← 输出 token 上限
+//	core.agent.context.max_target_tokens ← 上下文预算
+//
+// 功能上无害（透明解密，仍可用），但语义错了，且库变得难以人工检查。
+// 根因：`max_tokens` 包含子串 "token"，而它是**复数、指数量**。
+//
+// ## 现在的判据：按**词段**匹配
+//
+// 先把键按 `.` `_` `-` 切成词段，再看：
+//
+//	词段完全等于敏感词          → 命中（token / password / apikey …）
+//	词段以 `_<敏感词>` 结尾       → 命中（api_key / access_token …）
+//
+// 关键差别：`max_tokens` 的末词段是 `tokens`（复数），不等于 `token`，
+// 也不以 `_token` 结尾 ⇒ **不命中**。而 `api_key` 末词段是 `key`
+// 且整串以 `_key` 结尾 ⇒ 命中。
+var secretWords = []string{
+	"token", "password", "passwd", "secret", "credential", "credentials",
+	"apikey", "key",
+}
+
+// secretExactSegments 是允许“整词即敏感”的情形。
+//
+// `key` 单独成词段（如某插件的配置就叫 `key`）算敏感；但像 `keyboard`、
+// `keys`（复数）这样的就不算。
+func looksLikeSecretKey(key string) bool {
+	lower := strings.ToLower(key)
+	// 切成词段：先按命名空间分隔，再拆下划线/连字符
+	for _, part := range strings.FieldsFunc(lower, func(r rune) bool {
+		return r == '.' || r == '_' || r == '-'
+	}) {
+		for _, w := range secretWords {
+			if part == w {
+				return true
+			}
+		}
+	}
+	// 复合形态：整串以 _<敏感词> 结尾（api_key / access_token / client_secret）
+	for _, w := range secretWords {
+		if strings.HasSuffix(lower, "_"+w) || strings.HasSuffix(lower, "-"+w) {
+			return true
+		}
+	}
+	return false
+}
+
+// isSecretKey 判定一个（全局或插件内局部的）键是否敏感。
+//
+// 判定顺序：显式 def（最权威） → 键名模式（兜底）。
+func (r *ConfigRegistry) isSecretKey(key string) bool {
+	// 调用方须持锁（读或写皆可）
+	if d, ok := r.defs[key]; ok {
+		if d.Secret || d.Type == "password" || d.Type == "secret" {
+			return true
+		}
+	}
+	return looksLikeSecretKey(key)
+}
+
+// isSecretKeyLocal 供 PluginSettings 用（键是插件内局部键，无命名空间前缀）。
+func (p *PluginSettings) isSecretKeyLocal(key string) bool {
+	return p.registry.isSecretKey("plugin." + p.name + "." + key)
+}
+
+// sealForStorage 在写库前加密（仅对敏感键 + 编解码器已装配时）。
+//
+// 返回值语义：加密发生则 mem=false（调用方据此决定是否需回读校验）；
+// 非敏感键或未装配 codec 时原样返回。
+func sealForStorage(key, value string) (string, bool) {
+	if !security.IsEncrypted(value) {
+		c := security.ConfigCodec()
+		if c == nil || !c.Enabled() {
+			return value, false
+		}
+		if sealed, err := c.Seal(value); err == nil {
+			return sealed, true
+		} else {
+			log.Printf("[config] 加密 %s 失败（将按明文写入，此项暴露风险）: %v", key, err)
+		}
+	}
+	return value, false
+}
+
+// openFromStorage 在读库后解密。
+//
+// 非密文原样返回（**存量明文兼容**）：老数据不需要一次性迁移。
+// 密文但解不开 ⇒ **响亮失败**（返回错误而非密文），因为把密文
+// 当明文交出去会让下游拿到垃圾（比如把 `enc:v1:...` 当 API key 发出去）。
+func openFromStorage(key, stored string) (string, error) {
+	if !security.IsEncrypted(stored) {
+		return stored, nil
+	}
+	c := security.ConfigCodec()
+	if c == nil || !c.Enabled() {
+		return "", security.ErrNoMasterKey
+	}
+	plain, err := c.Open(stored)
+	if err != nil {
+		log.Printf("[config] 解密 %s 失败: %v", key, err)
+		return "", err
+	}
+	return plain, nil
+}
+
+// EncryptExistingSecrets 把库里**尚为明文**的敏感项就地加密（启动时跑一次）。
+//
+// ## 为何需要
+//
+// 加密只对新写入生效。升级前库里已有的 api_key / 口令仍是明文 ——
+// 不迁移的话"升级了但密钥还在裸奔"，而且用户无法察觉。
+//
+// ## 可回滚
+//
+// 只改值形态、不改键名与表结构，旧版本二进制读明文项仍然工作
+// （它不认 `enc:v1:` 前缀，会把密文当明文用 —— 那是**功能坏但可见**的
+// 失败，不是静默错值）。所以升级要么配套换二进制，要么备份。
+//
+// 返回 (加密条数, 错误)。幂等：已加密的项不会被二次加密。
+func (r *ConfigRegistry) EncryptExistingSecrets() (int, error) {
+	c := security.ConfigCodec()
+	if c == nil || !c.Enabled() {
+		return 0, security.ErrNoMasterKey
+	}
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	type row struct{ table, key, val string }
+	var todo []row
+
+	// ① 全局 config 表
+	rows, err := r.db.Query(`SELECT key, value FROM config`)
+	if err != nil {
+		return 0, err
+	}
+	for rows.Next() {
+		var k, v string
+		if err := rows.Scan(&k, &v); err != nil {
+			continue
+		}
+		if !r.isSecretKey(k) || security.IsEncrypted(v) || v == "" {
+			continue
+		}
+		todo = append(todo, row{"config", k, v})
+	}
+	rows.Close()
+
+	// ② 各插件表
+	for _, name := range r.ListPluginsLocked() {
+		table := r.pluginTableName(name)
+		pr, err := r.db.Query("SELECT key, value FROM " + table)
+		if err != nil {
+			continue
+		}
+		for pr.Next() {
+			var k, v string
+			if err := pr.Scan(&k, &v); err != nil {
+				continue
+			}
+			if !r.isSecretKey("plugin."+name+"."+k) || security.IsEncrypted(v) || v == "" {
+				continue
+			}
+			todo = append(todo, row{table, k, v})
+		}
+		pr.Close()
+	}
+
+	n := 0
+	for _, t := range todo {
+		sealed, err := c.Seal(t.val)
+		if err != nil {
+			log.Printf("[config] 迁移加密 %s.%s 失败: %v", t.table, t.key, err)
+			continue
+		}
+		if _, err := r.db.Exec(
+			"UPDATE "+t.table+" SET value = ? WHERE key = ?", sealed, t.key); err != nil {
+			log.Printf("[config] 迁移加密 %s.%s 写回失败: %v", t.table, t.key, err)
+			continue
+		}
+		n++
+	}
+	if n > 0 {
+		log.Printf("[config] 已加密 %d 条存量敏感配置（落盘不再有明文）", n)
+	}
+	return n, nil
+}
+
+// RekeySecrets 把库里的密文重加密到**当前**主密钥（E-1 密钥轮换后的收口）。
+//
+// 与 EncryptExistingSecrets 的区别：
+//   - 后者处理「明文 → 密文」（升级路径）；
+//   - 本函数处理「旧钥密文 → 新钥密文」（轮换路径）。
+//
+// 为何必须有：轮换只换密钥文件 / keyring 是不够的 —— 旧密文仍由旧钥保护，
+// 而旧钥必须留在环里才能读它们。不重加密的话，旧钥永远不会退出。
+//
+// 幂等：已是当前钥的项不动。解不开的项**响亮计数**并跳过（不静默删）。
+func (r *ConfigRegistry) RekeySecrets() (int, int, error) {
+	c := security.ConfigCodec()
+	if c == nil || !c.Enabled() {
+		return 0, 0, security.ErrNoMasterKey
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	tables := []string{"config"}
+	for _, name := range r.ListPluginsLocked() {
+		tables = append(tables, r.pluginTableName(name))
+	}
+
+	rekeyed, failed := 0, 0
+	for _, table := range tables {
+		rows, err := r.db.Query("SELECT key, value FROM " + table)
+		if err != nil {
+			continue
+		}
+		type pair struct{ k, v string }
+		var need []pair
+		for rows.Next() {
+			var k, v string
+			if err := rows.Scan(&k, &v); err != nil {
+				continue
+			}
+			if c.NeedsRekey(v) {
+				need = append(need, pair{k, v})
+			}
+		}
+		rows.Close()
+
+		for _, p := range need {
+			fresh, err := c.Rekey(p.v)
+			if err != nil {
+				// ★ 解不开不能静默跳：那是“密钥环缺一代”的信号，必须可见。
+				failed++
+				log.Printf("[config] 重加密 %s.%s 失败（旧密钥不在环里？）: %v", table, p.k, err)
+				continue
+			}
+			if _, err := r.db.Exec("UPDATE "+table+" SET value = ? WHERE key = ?", fresh, p.k); err != nil {
+				failed++
+				log.Printf("[config] 重加密 %s.%s 写回失败: %v", table, p.k, err)
+				continue
+			}
+			rekeyed++
+		}
+	}
+	if rekeyed > 0 || failed > 0 {
+		log.Printf("[config] 密钥轮换重加密：完成 %d 条，失败 %d 条", rekeyed, failed)
+	}
+	return rekeyed, failed, nil
+}
+
+// AuditSecrets 统计库里密文的可读性（E-2：备份跨机器恢复的诊断）。
+//
+// 为何需要：备份恢复到另一台机器时，DB 里的密文是**旧机器的密钥**加的。
+// 此前只有读某一条具体配置时才会报错，用户看到的是「某个功能坏了」，
+// 而不是「这份备份与当前密钥不匹配」。这个审计把事实一次性说清楚。
+//
+// 返回 (可解, 不可解)。不可解 > 0 就是密钥不匹配/缺代的硬信号。
+func (r *ConfigRegistry) AuditSecrets() (int, int, error) {
+	c := security.ConfigCodec()
+	if c == nil || !c.Enabled() {
+		return 0, 0, security.ErrNoMasterKey
+	}
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	tables := []string{"config"}
+	for _, name := range r.ListPluginsLocked() {
+		tables = append(tables, r.pluginTableName(name))
+	}
+	ok, bad := 0, 0
+	for _, table := range tables {
+		rows, err := r.db.Query("SELECT value FROM " + table)
+		if err != nil {
+			continue
+		}
+		for rows.Next() {
+			var v string
+			if err := rows.Scan(&v); err != nil {
+				continue
+			}
+			if !security.IsEncrypted(v) {
+				continue // 明文（未加密项）不计入
+			}
+			if _, err := c.Open(v); err == nil {
+				ok++
+			} else {
+				bad++
+			}
+		}
+		rows.Close()
+	}
+	return ok, bad, nil
+}
+
+// ListPluginsLocked 是 ListPlugins 的不加锁版本（调用方已持锁）。
+func (r *ConfigRegistry) ListPluginsLocked() []string {
+	rows, err := r.db.Query(
+		`SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'config_%' ORDER BY name`)
+	if err != nil {
+		return nil
+	}
+	defer rows.Close()
+	var out []string
+	for rows.Next() {
+		var t string
+		if err := rows.Scan(&t); err != nil {
+			continue
+		}
+		out = append(out, strings.TrimPrefix(t, "config_"))
+	}
+	return out
+}
+
+// IsSecret 报告某个（全局或 plugin. 前缀的）键是否敏感。
+//
+// 用途（E-3）：WebUI 在返回设置时必须用它**屏蔽明文**，否则任何能打开
+// 设置页的人都看得到全部密钥（含其他插件的）。
+//
+// 它刻意复用与落盘加密**同一套判定**（isSecretKey）：两处判定若不一致，
+// 就会出现「已加密但界面照旧显示明文」或反向的漏洞。
+func (r *ConfigRegistry) IsSecret(key string) bool {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	return r.isSecretKey(key)
+}
+
+// SecretKeys 返回当前被判定为敏感的键（供诊断 / 测试 / WebUI 标记）。
+func (r *ConfigRegistry) SecretKeys() []string {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	var out []string
+	seen := map[string]bool{}
+	for k := range r.defs {
+		if r.isSecretKey(k) && !seen[k] {
+			seen[k] = true
+			out = append(out, k)
+		}
+	}
+	return out
+}
+
+// DB 暴露底层连接（仅供**同仓测试**读取原始密文用）。
+//
+// 语义警告：它绕过全部加解密与权限逻辑，仅用于判据里断言
+// 「磁盘上确实是密文」。生产代码不得使用。
+func (r *ConfigRegistry) DB() *sql.DB { return r.db }
+
+// ResetTestCodec 为判据装配一把固定主密钥。
+//
+// 单独放在非 _test 文件里，是因为 proc 包（另一个包）的端到端判据
+// 也需要它 —— 跨包无法直接调 *_test.go 里的辅助函数。
+func ResetTestCodec(t interface {
+	Helper()
+	Fatalf(string, ...interface{})
+}) {
+	if _, err := security.InitConfigCodec(
+		[]byte("0123456789abcdef0123456789abcdef")); err != nil {
+		t.Fatalf("装配测试 codec 失败: %v", err)
+	}
+}
diff --git a/internal/config/secret_test.go b/internal/config/secret_test.go
new file mode 100644
index 00000000..dc0046f3
--- /dev/null
+++ b/internal/config/secret_test.go
@@ -0,0 +1,416 @@
+package config
+
+// 配置落盘加密的判据。
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/security"
+)
+
+func testCodec(t *testing.T) {
+	t.Helper()
+	if _, err := security.InitConfigCodec([]byte("0123456789abcdef0123456789abcdef")); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func newSecReg(t *testing.T) *ConfigRegistry {
+	t.Helper()
+	dir := t.TempDir()
+	testCodec(t)
+	return NewConfigRegistry(filepath.Join(dir, "config.db"))
+}
+
+// 直接在 sqlite 层面读原始值（绕过 ConfigRegistry 的解密）。
+func rawValue(t *testing.T, r *ConfigRegistry, key string) string {
+	t.Helper()
+	var v string
+	if err := r.db.QueryRow(`SELECT value FROM config WHERE key = ?`, key).Scan(&v); err != nil {
+		t.Fatalf("读原始值失败: %v", err)
+	}
+	return v
+}
+
+// ★★ 判据：敏感配置**落盘是密文**，而读接口返回明文。
+func TestSecretEncryptedOnDiskPlainOnRead(t *testing.T) {
+	r := newSecReg(t)
+	const secret = "sk-super-secret-value-1234567890"
+
+	if err := r.Set("core.llm.api_key", secret); err != nil {
+		t.Fatal(err)
+	}
+
+	// ① 磁盘上是密文
+	raw := rawValue(t, r, "core.llm.api_key")
+	if raw == secret {
+		t.Fatal("敏感项在磁盘上是明文")
+	}
+	if !security.IsEncrypted(raw) {
+		t.Fatalf("应有 enc:v1: 前缀，实际 %q", raw)
+	}
+
+	// ② 读接口返回明文（内部可信路径语义不变）
+	got, err := r.Get("core.llm.api_key")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != secret {
+		t.Fatalf("Get 应返回明文，实际 %v", got)
+	}
+	// ③ GetString / Dump 同样给明文
+	if r.GetString("core.llm.api_key", "") != secret {
+		t.Error("GetString 应返回明文")
+	}
+	if r.Dump()["core.llm.api_key"] != secret {
+		t.Error("Dump 应返回明文（ToConfig 依赖它）")
+	}
+}
+
+// ★★ 判据：**非敏感项不受影响**（不能被误加密）。
+func TestNonSecretStaysPlain(t *testing.T) {
+	r := newSecReg(t)
+	if err := r.Set("core.llm.base_url", "https://api.deepseek.com"); err != nil {
+		t.Fatal(err)
+	}
+	raw := rawValue(t, r, "core.llm.base_url")
+	if raw != "https://api.deepseek.com" {
+		t.Fatalf("非敏感项不应被加密: %q", raw)
+	}
+}
+
+// ★ 判据：`Secret: true` 与 `Type: "password"` 两种声明都生效。
+func TestBothDeclarationFormsWork(t *testing.T) {
+	r := newSecReg(t)
+	r.RegisterDef(ConfigDef{Key: "core.a.token_field", Default: "", Secret: true})
+	r.RegisterDef(ConfigDef{Key: "core.b.password_field", Default: "", Type: "password"})
+
+	for _, k := range []string{"core.a.token_field", "core.b.password_field"} {
+		if err := r.Set(k, "value-1234567890"); err != nil {
+			t.Fatal(err)
+		}
+		if !security.IsEncrypted(rawValue(t, r, k)) {
+			t.Errorf("%s 未被加密（Secret 或 password 声明未生效）", k)
+		}
+	}
+}
+
+// ★★ 判据：**插件配置同样加密**（插件无感知）。
+func TestPluginSecretEncrypted(t *testing.T) {
+	r := newSecReg(t)
+	ps := r.PluginConfig("demo")
+	ps.RegisterDef(ConfigDef{Key: "token", Default: "", Secret: true})
+
+	const secret = "plugin-token-abcdef123456"
+	if err := ps.Set("token", secret); err != nil {
+		t.Fatal(err)
+	}
+
+	// 磁盘（插件表）上是密文
+	var raw string
+	if err := r.db.QueryRow(`SELECT value FROM config_demo WHERE key = 'token'`).Scan(&raw); err != nil {
+		t.Fatal(err)
+	}
+	if !security.IsEncrypted(raw) {
+		t.Fatalf("插件敏感项应加密，实际 %q", raw)
+	}
+	// 插件读回明文
+	got, err := ps.Get("token")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != secret {
+		t.Fatalf("插件应读回明文，实际 %v", got)
+	}
+}
+
+// ★ 判据：无 def 的插件键靠**键名模式**兜底加密。
+func TestPluginSecretByKeyPattern(t *testing.T) {
+	r := newSecReg(t)
+	ps := r.PluginConfig("demo2")
+	// 先注册一个**非敏感** def：插件表只在 RegisterDef 时创建，
+	// 但 api_key 这个键本身没有 def —— 正好检验键名模式兜底。
+	ps.RegisterDef(ConfigDef{Key: "enabled", Default: "true"})
+	if err := ps.Set("api_key", "abcdefgh12345678"); err != nil {
+		t.Fatal(err)
+	}
+	var raw string
+	r.db.QueryRow(`SELECT value FROM config_demo2 WHERE key = 'api_key'`).Scan(&raw)
+	if !security.IsEncrypted(raw) {
+		t.Fatalf("无 def 时 api_key 键名应触发加密，实际 %q", raw)
+	}
+}
+
+// ★★ 判据：存量明文在启动迁移后被加密（幂等）。
+func TestMigrateExistingSecrets(t *testing.T) {
+	r := newSecReg(t)
+	// 模拟升级前的明文存量（直接写库，绕过 Set）
+	r.db.Exec(`INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)`,
+		"core.llm.api_key", "legacy-plaintext-key-123")
+	r.db.Exec(`INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)`,
+		"webui.listen_addr", ":8080")
+
+	n, err := r.EncryptExistingSecrets()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != 1 {
+		t.Fatalf("应加密 1 条，实际 %d", n)
+	}
+	if !security.IsEncrypted(rawValue(t, r, "core.llm.api_key")) {
+		t.Error("存量敏感项未被加密")
+	}
+	// 非敏感项不动
+	if rawValue(t, r, "webui.listen_addr") != ":8080" {
+		t.Error("非敏感项被误改")
+	}
+	// 迁移后仍可读明文
+	if v, _ := r.Get("core.llm.api_key"); v != "legacy-plaintext-key-123" {
+		t.Errorf("迁移后应可读明文，实际 %v", v)
+	}
+	// 幂等
+	if n2, _ := r.EncryptExistingSecrets(); n2 != 0 {
+		t.Errorf("迁移应幂等，第二次却加密了 %d 条", n2)
+	}
+}
+
+// ★★ 判据：**存量明文不需要迁移也能读**（老数据向后兼容）。
+func TestLegacyPlaintextReadableWithoutMigration(t *testing.T) {
+	r := newSecReg(t)
+	r.db.Exec(`INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)`,
+		"core.llm.api_key", "still-plain")
+	v, err := r.Get("core.llm.api_key")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if v != "still-plain" {
+		t.Fatalf("明文存量应可读，实际 %v", v)
+	}
+}
+
+// ★★ 判据：换密钥后**响亮失败**（不静默返回密文）。
+func TestWrongKeyFailsLoudly(t *testing.T) {
+	r := newSecReg(t)
+	if err := r.Set("core.llm.api_key", "secret-value-1234567890"); err != nil {
+		t.Fatal(err)
+	}
+	// 换一把主密钥
+	if _, err := security.InitConfigCodec([]byte("ffffffffffffffffffffffffffffffff")); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := r.Get("core.llm.api_key"); err == nil {
+		t.Fatal("换密钥后必须报错，不能把密文当明文返回")
+	}
+	// Dump 也不得吐密文
+	if v := r.Dump()["core.llm.api_key"]; v != nil {
+		if s, ok := v.(string); ok && strings.HasPrefix(s, "enc:") {
+			t.Fatal("Dump 把密文交出去了")
+		}
+	}
+}
+
+// ★ 判据：未装配 codec 时退化为明文读写（本地开发/测试不阻塞）。
+func TestNoCodecDegradesToPlain(t *testing.T) {
+	dir := t.TempDir()
+	// 清空全局 codec
+	security.ClearConfigCodec()
+	r := NewConfigRegistry(filepath.Join(dir, "c.db"))
+	if err := r.Set("core.llm.api_key", "plain-dev"); err != nil {
+		t.Fatal(err)
+	}
+	if rawValue(t, r, "core.llm.api_key") != "plain-dev" {
+		t.Error("未装配 codec 时应保持明文")
+	}
+	_ = os.Remove
+}
+
+// ★ 判据：域隔离 —— 配置子密钥与别名密钥不可互换。
+func TestDomainSeparation(t *testing.T) {
+	master := []byte("0123456789abcdef0123456789abcdef")
+	cfgCodec, err := security.NewCodec(master, "config-at-rest")
+	if err != nil {
+		t.Fatal(err)
+	}
+	otherCodec, err := security.NewCodec(master, "some-other-domain")
+	if err != nil {
+		t.Fatal(err)
+	}
+	sealed, err := cfgCodec.Seal("hello")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := otherCodec.Open(sealed); err == nil {
+		t.Fatal("不同域的子密钥不应能解开 —— 域隔离失效")
+	}
+	if got, _ := cfgCodec.Open(sealed); got != "hello" {
+		t.Fatal("同域应可解")
+	}
+}
+
+// ★★ 判据：**ToConfig 在加密开启后仍能取到真 api_key**。
+//
+// 这是最容易被加密改坏的一条：ToConfig 靠 Dump() 重建 LLMSource。
+// 若 Dump 改返回掩码/密文，LLM 就会拿着垃圾去调上游 —— 而且
+// 失败现象是「认证失败」，与配置加密毫无关联，归因极难。
+func TestToConfigStillGetsRealAPIKey(t *testing.T) {
+	r := newSecReg(t)
+	const key = "sk-real-key-for-upstream-123456"
+	if err := r.Set("core.llm.api_key", key); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.Set("core.llm.sources.probe.base_url", "https://example.com"); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.Set("core.llm.sources.probe.api_key", key); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.Set("core.llm.sources.probe.model", "m1"); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg := r.ToConfig()
+	if cfg.LLM.APIKey != key {
+		t.Fatalf("ToConfig 的 APIKey 不真：%q", cfg.LLM.APIKey)
+	}
+	var found bool
+	for _, s := range cfg.LLM.Sources {
+		if s.Name == "probe" {
+			found = true
+			if s.APIKey != key {
+				t.Fatalf("source api_key 不真：%q", s.APIKey)
+			}
+		}
+	}
+	if !found {
+		t.Fatal("source probe 丢失")
+	}
+}
+
+// ★★ 判据：**数量类键名不得被误判为敏感**。
+//
+// 这是真机跑出来的缺陷：初版用 strings.Contains(key,"token")，
+// 把 core.llm.max_tokens（输出上限）与
+// core.agent.context.max_target_tokens（上下文预算）也加密了。
+// 功能上无害，但语义错误、且库变得无法人工检查。
+func TestNonSecretTokenCountsNotEncrypted(t *testing.T) {
+	r := newSecReg(t)
+	benign := []string{
+		"core.llm.max_tokens",
+		"core.agent.context.max_target_tokens",
+		"core.compact.target_tokens",
+		"core.keyboard_layout", // 含 "key" 但不是凭据
+		"core.monkey_mode",     // 同上
+		"webui.listen_addr",
+		"core.llm.temperature",
+	}
+	for _, k := range benign {
+		if r.isSecretKey(k) {
+			t.Errorf("%q 被误判为敏感（会被无谓加密）", k)
+		}
+	}
+}
+
+// ★★ 判据：真敏感键名必须命中（含无 def 的插件键）。
+func TestSecretKeyNamesDetected(t *testing.T) {
+	r := newSecReg(t)
+	sensitive := []string{
+		"core.llm.api_key",
+		"core.llm.sources.x.access_token",
+		"plugin.qq.token",
+		"plugin.demo.password",
+		"plugin.a.client_secret",
+		"plugin.b.apikey",
+		"plugin.c.key",
+		"core.memory.multimodal_space.options.api_key",
+	}
+	for _, k := range sensitive {
+		if !r.isSecretKey(k) {
+			t.Errorf("%q 应被判定为敏感", k)
+		}
+	}
+}
+
+// ★★ 判据：显式加密 API（SetSecret/GetSecret）**不看键名**也加密。
+//
+// 存在意义：插件可能用中性键名（blob/payload/conn）存凭据，
+// 键名模式猜不到 ⇒ 必须能显式声明意图。
+func TestExplicitSetSecretIgnoresKeyName(t *testing.T) {
+	r := newSecReg(t)
+	ps := r.PluginConfig("demo3")
+	ps.RegisterDef(ConfigDef{Key: "enabled", Default: "1"})
+
+	const neutral = "blob" // 中性键名，模式判定为**非敏感**
+	if r.isSecretKey("plugin.demo3." + neutral) {
+		t.Fatal("前提失效：blob 不该被模式判定为敏感")
+	}
+
+	const secret = "creds-payload-with-neutral-key-name"
+	if err := ps.SetSecret(neutral, secret); err != nil {
+		t.Fatal(err)
+	}
+	// 磁盘上是密文
+	var raw string
+	if err := r.db.QueryRow(`SELECT value FROM config_demo3 WHERE key = ?`, neutral).Scan(&raw); err != nil {
+		t.Fatal(err)
+	}
+	if !security.IsEncrypted(raw) {
+		t.Fatalf("SetSecret 应强制加密，实际 %q", raw)
+	}
+	// GetSecret 读回明文
+	got, err := ps.GetSecret(neutral)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != secret {
+		t.Fatalf("GetSecret 应返回明文，实际 %q", got)
+	}
+}
+
+// ★★ 判据：**密钥未装配时 SetSecret 拒绝写入**（不静默存明文）。
+//
+// 这是最危险的静默降级：插件以为存了密文，实际磁盘上是明文。
+func TestSetSecretRefusesWithoutKey(t *testing.T) {
+	dir := t.TempDir()
+	security.ClearConfigCodec()
+	defer testCodec(t) // 复原，避免影响其它判据
+
+	r := NewConfigRegistry(filepath.Join(dir, "c.db"))
+	ps := r.PluginConfig("demo4")
+	ps.RegisterDef(ConfigDef{Key: "enabled", Default: "1"})
+
+	err := ps.SetSecret("blob", "must-not-be-plain")
+	if err == nil {
+		t.Fatal("无密钥时 SetSecret 必须报错，不能静默写明文")
+	}
+	// 且确实没写进去
+	var cnt int
+	r.db.QueryRow(`SELECT COUNT(*) FROM config_demo4 WHERE key = 'blob'`).Scan(&cnt)
+	if cnt != 0 {
+		t.Error("拒绝写入后库里不应有该键")
+	}
+	// 空值是允许的（删除语义）
+	if err := ps.SetSecret("blob", ""); err != nil {
+		t.Errorf("空值应允许写入: %v", err)
+	}
+}
+
+// ★ 判据：SetSecret 写入的值能被普通 Get 读到（两种读法互通，不产生孤岛）。
+func TestSetSecretReadableByGet(t *testing.T) {
+	r := newSecReg(t)
+	ps := r.PluginConfig("demo5")
+	ps.RegisterDef(ConfigDef{Key: "enabled", Default: "1"})
+	if err := ps.SetSecret("blob", "value-xyz-123456"); err != nil {
+		t.Fatal(err)
+	}
+	v, err := ps.Get("blob") // Get 会走 openFromStorage
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fmt.Sprint(v) != "value-xyz-123456" {
+		t.Fatalf("Get 应能读到 SetSecret 写的值，实际 %v", v)
+	}
+}
diff --git a/internal/devicebridge/client/bridge.go b/internal/devicebridge/client/bridge.go
index 272ff221..d5488b30 100644
--- a/internal/devicebridge/client/bridge.go
+++ b/internal/devicebridge/client/bridge.go
@@ -3,6 +3,7 @@ package client
 import (
 	"encoding/json"
 	"fmt"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"log"
 	"os"
 	"runtime"
@@ -36,6 +37,8 @@ type PushHandler func(reqID, typ, payload, meta string)
 // 授权状态由设备端本地存储（客户端鉴权），服务端不存储；
 // 未授权时收到 cmd 直接拒绝执行并回执 error。
 type Bridge struct {
+	stopOnce   sync.Once
+	doneOnce   sync.Once
 	mu         sync.RWMutex
 	gateway    string
 	token      string
@@ -297,11 +300,11 @@ func (b *Bridge) Stop() {
 	if !b.started {
 		return
 	}
-	select {
-	case <-b.stopCh:
+	// 幂等（本仓 close 纪律）。原写法是
+	//   select { case <-b.stopCh: return; default: close(b.stopCh) }
+	// 单线程安全，但**并发**下两个 goroutine 可同时落到 default ⇒ 双 close panic。
+	if !safeclose.Safe(&b.stopOnce, b.stopCh) {
 		return
-	default:
-		close(b.stopCh)
 	}
 	if b.ws != nil {
 		_ = b.ws.close()
@@ -442,7 +445,7 @@ func (b *Bridge) readLoop() {
 			b.ws = nil
 		}
 		b.mu.Unlock()
-		close(b.doneCh)
+		safeclose.Safe(&b.doneOnce, b.doneCh)
 	}()
 
 	for {
diff --git a/internal/ipc/ipc.go b/internal/ipc/ipc.go
index 39470b65..7a0c4877 100644
--- a/internal/ipc/ipc.go
+++ b/internal/ipc/ipc.go
@@ -7,9 +7,11 @@ import (
 	"bufio"
 	"encoding/json"
 	"fmt"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"net"
 	"os"
 	"path/filepath"
+	"sync"
 	"time"
 )
 
@@ -20,12 +22,12 @@ func sinkPath(dataDir string) string {
 
 // Status worker 上报给 guard 的自诊断快照。
 type Status struct {
-	PID       int     `json:"pid"`
-	Boot      string  `json:"boot"`               // normal | failback
-	UptimeSec int64   `json:"uptime_sec"`         // 进程存活秒数
-	LLMOK     *bool   `json:"llm_ok,omitempty"`   // rescue 源可达性（nil=未探）
-	Tools     int     `json:"tools"`              // 已注册工具数
-	LastDiag  string  `json:"last_diag,omitempty"` // 最近一次自诊断结论（如 diag_loc.cause）
+	PID       int    `json:"pid"`
+	Boot      string `json:"boot"`                // normal | failback
+	UptimeSec int64  `json:"uptime_sec"`          // 进程存活秒数
+	LLMOK     *bool  `json:"llm_ok,omitempty"`    // rescue 源可达性（nil=未探）
+	Tools     int    `json:"tools"`               // 已注册工具数
+	LastDiag  string `json:"last_diag,omitempty"` // 最近一次自诊断结论（如 diag_loc.cause）
 }
 
 // StatusFunc 组装 worker 当前状态。
@@ -33,11 +35,12 @@ type StatusFunc func() *Status
 
 // Server worker 侧：监听 unix socket，处理 PING→ACK。
 type Server struct {
-	path   string
-	ln     net.Listener
-	status StatusFunc
-	stop   chan struct{}
-	done   chan struct{}
+	doneOnce sync.Once
+	path     string
+	ln       net.Listener
+	status   StatusFunc
+	stop     chan struct{}
+	done     chan struct{}
 }
 
 // NewServer 创建心跳服务端（尚未 Listen，见 Start）。
@@ -63,7 +66,7 @@ func (s *Server) Start() error {
 }
 
 func (s *Server) acceptLoop() {
-	defer close(s.done)
+	defer safeclose.Safe(&s.doneOnce, s.done)
 	for {
 		conn, err := s.ln.Accept()
 		if err != nil {
@@ -127,7 +130,7 @@ func (c *Client) Ping(timeout time.Duration) (*Status, error) {
 		return nil, fmt.Errorf("ipc: empty ACK")
 	}
 	var resp struct {
-		Type   string `json:"type"`
+		Type   string  `json:"type"`
 		Status *Status `json:"status"`
 	}
 	if err := json.Unmarshal(sc.Bytes(), &resp); err != nil {
@@ -140,4 +143,4 @@ func (c *Client) Ping(timeout time.Duration) (*Status, error) {
 }
 
 // Close 无状态（客户端用完即释放连接）。
-func (c *Client) Close() {}
\ No newline at end of file
+func (c *Client) Close() {}
diff --git a/internal/kernelboot/funcmodule.go b/internal/kernelboot/funcmodule.go
new file mode 100644
index 00000000..ef30f84c
--- /dev/null
+++ b/internal/kernelboot/funcmodule.go
@@ -0,0 +1,77 @@
+package kernelboot
+
+// 把既有的内核 `init*` 函数**适配**成 Module，而不必重写它们的签名。
+//
+// ## 为什么不直接改 init* 的签名
+//
+// `init*` 函数是**既有代码**，各有不同签名（有的返回 1 个值、有的 2 个、
+// 有的带 close 函数、有的只做副作用）。逐个改签名意味着：
+//   · 大面积改动（评审困难、易引入回归）
+//   · 且 `init*` 函数本身是清晰的（`initLuaVM(cfg) (*VM, func())`）——
+//     为迁就调度器的接口而把它改丑，是**倒置的取舍**
+//
+// 所以本文件提供**适配层**：声明式地描述"这个模块的名字/依赖/产物/怎么调用"，
+// `init*` 函数一行都不改。
+//
+// ## 设计：FuncModule
+//
+// ```go
+// kernelboot.FuncModule(kernelboot.FuncSpec{
+//     Name:     "lua",
+//     Requires: []string{"config"},
+//     Provides: []string{"lua"},
+//     Init: func(ks *kernelboot.KernelState) error {
+//         vm, closeFn := initLuaVM(ks.Cfg)   // 依赖的产物：直接读字段
+//         ks.LuaVM = vm                       // 自己的产物：写回字段
+//         ks.AddCloser(closeFn)               // 关闭函数统一登记
+//         return nil
+//     },
+// })
+// ```
+//
+// ## 为什么"关闭函数"也要作为产物发布
+//
+// `init*` 常返回 `(value, func())`：value 要用，close 要在停机时调。
+// 若适配器只发布 value，**close 就丢了** ⇒ 资源泄漏（实测有先例：
+// tracker 的 overlay 挂载、memory stack 的关闭）。
+//
+// 把 close 也当产物（约定名 `<facility>.close`）的好处：
+// 停机时统一遍历容器调用所有 close，**不依赖人记得在 main 末尾手写**。
+// 这正好顺手解决了 main() 里那一堆 `defer closeMem()` 的散落问题。
+
+// FuncSpec 描述一个由函数适配的模块。
+type FuncSpec struct {
+	Name     string
+	Requires []string
+	Provides []string
+	// Init 执行装配：从 ctx 取依赖、调既有函数、把产物 Put 回 ctx。
+	Init func(ks *KernelState) error
+}
+
+// funcModule 是 FuncSpec 的 Module 实现。
+type funcModule struct {
+	spec FuncSpec
+}
+
+func (m *funcModule) Name() string       { return m.spec.Name }
+func (m *funcModule) Provides() []string { return m.spec.Provides }
+func (m *funcModule) Requires() []string { return m.spec.Requires }
+func (m *funcModule) Init(ks *KernelState) error {
+	if m.spec.Init == nil {
+		return nil
+	}
+	return m.spec.Init(ks)
+}
+
+// FuncModule 创建一个由函数适配的模块。
+func FuncModule(spec FuncSpec) Module {
+	return &funcModule{spec: spec}
+}
+
+// --- 关闭函数的统一回收 ---
+//
+// 约定：模块在 Init 里用 ks.AddCloser(fn) 注册关闭函数。
+// 停机时由 KernelState.CloseAll 按**注册顺序的逆序**执行（LIFO，与 defer 一致）。
+//
+// ★ 为何不再用"设施名以 .close 结尾"的约定：那个约定要靠字符串判断，
+// 而结构体方案下直接 AddCloser 更直白（且不会因为设施改名而失效）。
diff --git a/internal/kernelboot/graphfile.go b/internal/kernelboot/graphfile.go
new file mode 100644
index 00000000..5ad2adf3
--- /dev/null
+++ b/internal/kernelboot/graphfile.go
@@ -0,0 +1,443 @@
+package kernelboot
+
+// 依赖图的**制品化**：编译期产出的精密二进制 + 双重 hash 保护。
+//
+// 设计权威：docs/zh/kernel-modularization-design.md §2.5。
+//
+// ## 两个不同的 hash，各防一类故障（★ 关键区分）
+//
+//	① 图内自校验 hash   防「图文件损坏」（磁盘错、传输截断、位翻转）
+//	② 内嵌 hash（二进制） 防「图与二进制不匹配」（改了 Requires 但图没重生成）
+//
+// ★ 只做 ① 会漏掉更危险的那类：图文件**自身完好**、自校验也过，
+// 但它描述的是**旧代码** ⇒ 按旧图调度 ⇒ 顺序错 ⇒ 正是本设计要消灭的病 A。
+//
+// 所以 §2.5.2 要求 hash 绑定二进制，且不一致时**拒绝启动**（不猜哪边对）。
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/binary"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+)
+
+// 文件格式常量。
+const (
+	// graphMagic 是格式标识。破坏性变更时改末位数字。
+	graphMagic = "HGDEPS01"
+	// graphFormatVersion 是格式版本（与 magic 末位同步维护）。
+	graphFormatVersion = 2
+	// GraphFileName 是制品文件名（与内核二进制同目录，满足"随核心分发"）。
+	GraphFileName = "depgraph.bin"
+
+	// maxFieldLen 是单个字符串字段的长度上限（防损坏文件声明一个超大长度）。
+	//
+	// 为何必须设限：一个损坏的长度字段会让 make([]byte, n) 申请巨量内存
+	// （或直接 OOM）。解析器对**不可信输入**必须设边界。
+	maxFieldLen = 4096
+	// maxModules 是模块数上限（同上，防损坏文件声明一个巨大计数）。
+	maxModules = 4096
+)
+
+// GraphEdge 是图中一条模块声明（用于序列化）。
+type GraphEdge struct {
+	Name     string
+	Provides []string
+	Requires []string
+
+	// Layer 是**编译期算好的起始层号**（设计 §2.5，用户要求：
+	// "启动顺序是编译期间按照声明的依赖顺序生成的启动依赖图排列的"）。
+	//
+	// ## 为什么把层号也编码进图（而不只存边）
+	//
+	// 若只存边，运行期就还得跑一次 BFS 才算得出顺序 —— 那等于
+	// **内核在运行期决定启动顺序**，与"编译期定序"的设计相悖
+	// （且运行期算法与编译期不一致时无人察觉）。
+	//
+	// 存下 Layer 后：运行期**读**它即可，不重算。
+	// `Build()` 仍保留（单测/无图场景用），但**生产路径不调它**。
+	//
+	// ★ 自校验：读图时仍会重算分层并与 Layer 比对（CheckLayers），
+	// 不一致 ⇒ 拒绝启动。这样"图里的顺序"与"声明"不会漂移。
+	Layer int
+}
+
+// GraphFile 是图制品的解析结果。
+type GraphFile struct {
+	Version int
+	Modules []GraphEdge
+	// Digest 是文件内自校验 hash 的十六进制（§2.5.2 的 ①）。
+	Digest string
+}
+
+// buildGraphPayload 产出**参与 hash 与序列化**的全部字节（不含自校验 hash 本身）。
+//
+// ★ 所有字段**排序**：同一份声明必须产出逐字节相同的结果。
+// 否则代码里调换两个模块的顺序就会让 hash 变化 ⇒
+// "每次构建都说不一致" ⇒ hash 失去意义（人开始无视它）。
+func buildGraphPayload(modules []GraphEdge) []byte {
+	// 深拷贝并排序（不改调用方的切片）
+	ms := make([]GraphEdge, len(modules))
+	copy(ms, modules)
+	for i := range ms {
+		ms[i].Provides = sortedCopy(ms[i].Provides)
+		ms[i].Requires = sortedCopy(ms[i].Requires)
+	}
+	// ★ 排序键是 **(Layer, Name)** —— 不是只按名字。
+	//
+	// 这样**解码后的顺序就是启动顺序**（先按层，层内按名字），
+	// 运行期读到即可直接执行，不必重算分层。
+	//
+	// 层内按名字是为了**可复现**（同一份声明两次产出逐字节相同 ⇒ 能进 PR diff）。
+	sort.Slice(ms, func(i, j int) bool {
+		if ms[i].Layer != ms[j].Layer {
+			return ms[i].Layer < ms[j].Layer
+		}
+		return ms[i].Name < ms[j].Name
+	})
+
+	var buf bytes.Buffer
+	buf.WriteString(graphMagic)
+	_ = binary.Write(&buf, binary.LittleEndian, uint32(graphFormatVersion))
+	_ = binary.Write(&buf, binary.LittleEndian, uint32(len(ms)))
+
+	writeStr := func(s string) {
+		_ = binary.Write(&buf, binary.LittleEndian, uint16(len(s)))
+		buf.WriteString(s)
+	}
+	for _, m := range ms {
+		writeStr(m.Name)
+		writeStr(strings.Join(m.Provides, ","))
+		writeStr(strings.Join(m.Requires, ","))
+		// Layer 作为 uint32 追加在每条记录末尾。
+		//
+		// ★ 放在末尾而不是开头：这样"旧版解码逻辑"遇到新文件时
+		// 会在**尾部残留检查**处报错（响亮），而不是把 layer 当名字读错。
+		_ = binary.Write(&buf, binary.LittleEndian, uint32(m.Layer))
+	}
+	return buf.Bytes()
+}
+
+func sortedCopy(in []string) []string {
+	out := append([]string(nil), in...)
+	sort.Strings(out)
+	return out
+}
+
+// EncodeGraph 把模块声明序列化成制品字节（含自校验 hash）。
+func EncodeGraph(modules []GraphEdge) []byte {
+	payload := buildGraphPayload(modules)
+	sum := sha256.Sum256(payload)
+	out := make([]byte, 0, len(payload)+sha256.Size)
+	out = append(out, payload...)
+	out = append(out, sum[:]...)
+	return out
+}
+
+// GraphDigest 返回制品自校验 hash 的十六进制（不含文件本身）。
+//
+// 供构建期把 digest 注入二进制（§2.5.2 的 ②）。
+func GraphDigest(modules []GraphEdge) string {
+	sum := sha256.Sum256(buildGraphPayload(modules))
+	return hex.EncodeToString(sum[:])
+}
+
+// DecodeGraph 解析制品字节，校验自校验 hash。
+//
+// 任何结构异常都**报错**（不返回"部分结果"）：
+// 图是启动调度的唯一依据，残缺的图比没有图更危险
+// （它会生成一个**看似合法**的调度计划）。
+func DecodeGraph(data []byte) (*GraphFile, error) {
+	if len(data) < len(graphMagic)+8+sha256.Size {
+		return nil, fmt.Errorf("kernelboot: 依赖图文件过短（%d 字节），已损坏", len(data))
+	}
+	// ① 先校验自校验 hash（防截断/位翻转）
+	payload := data[:len(data)-sha256.Size]
+	wantSum := data[len(data)-sha256.Size:]
+	gotSum := sha256.Sum256(payload)
+	if !bytes.Equal(gotSum[:], wantSum) {
+		return nil, fmt.Errorf("kernelboot: 依赖图自校验失败（文件已损坏）")
+	}
+
+	// ② 解析
+	if string(payload[:len(graphMagic)]) != graphMagic {
+		return nil, fmt.Errorf("kernelboot: 依赖图格式标识不匹配（期望 %q，得到 %q）——"+
+			"文件可能来自不兼容的版本", graphMagic, string(payload[:len(graphMagic)]))
+	}
+	off := len(graphMagic)
+	rd32 := func() uint32 {
+		v := binary.LittleEndian.Uint32(payload[off:])
+		off += 4
+		return v
+	}
+	ver := rd32()
+	if ver != graphFormatVersion {
+		return nil, fmt.Errorf("kernelboot: 依赖图格式版本 %d 与本二进制期望的 %d 不一致——"+
+			"请用配套的生成器重出图", ver, graphFormatVersion)
+	}
+	n := rd32()
+	if n > maxModules {
+		return nil, fmt.Errorf("kernelboot: 依赖图声明 %d 个模块，超过上限 %d（文件已损坏）",
+			n, maxModules)
+	}
+
+	readStr := func() (string, error) {
+		if off+2 > len(payload) {
+			return "", fmt.Errorf("kernelboot: 依赖图在读取字符串长度时越界")
+		}
+		l := int(binary.LittleEndian.Uint16(payload[off:]))
+		off += 2
+		if l > maxFieldLen {
+			return "", fmt.Errorf("kernelboot: 依赖图字段长度 %d 超过上限 %d（文件已损坏）",
+				l, maxFieldLen)
+		}
+		if off+l > len(payload) {
+			return "", fmt.Errorf("kernelboot: 依赖图字段越界（需要 %d 字节，剩余 %d）",
+				l, len(payload)-off)
+		}
+		s := string(payload[off : off+l])
+		off += l
+		return s, nil
+	}
+
+	gf := &GraphFile{Version: int(ver), Digest: hex.EncodeToString(gotSum[:])}
+	for i := uint32(0); i < n; i++ {
+		name, err := readStr()
+		if err != nil {
+			return nil, err
+		}
+		provs, err := readStr()
+		if err != nil {
+			return nil, err
+		}
+		reqs, err := readStr()
+		if err != nil {
+			return nil, err
+		}
+		if off+4 > len(payload) {
+			return nil, fmt.Errorf("kernelboot: 依赖图在读取层号时越界（文件已损坏）")
+		}
+		layer := int(binary.LittleEndian.Uint32(payload[off:]))
+		off += 4
+		gf.Modules = append(gf.Modules, GraphEdge{
+			Name:     name,
+			Provides: splitNonEmpty(provs),
+			Requires: splitNonEmpty(reqs),
+			Layer:    layer,
+		})
+	}
+	if off != len(payload) {
+		return nil, fmt.Errorf("kernelboot: 依赖图有 %d 字节尾部残留（文件格式不符）",
+			len(payload)-off)
+	}
+	return gf, nil
+}
+
+func splitNonEmpty(s string) []string {
+	if s == "" {
+		return nil
+	}
+	parts := strings.Split(s, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// CheckAgainstBinary 校验磁盘上的图与**本二进制**是否配套（§2.5.2）。
+//
+// embeddedHash 是构建期注入的 digest（空 = 开发环境，跳过校验）。
+//
+// ★ 不一致时**拒绝启动**，不猜哪边对：
+// 图的作者是构建流程，二进制的作者也是它。两者不一致意味着制品装配出了问题，
+// 此时任何一边都不可信，猜一个是拿启动正确性赌运气。
+func CheckAgainstBinary(gf *GraphFile, embeddedHash string) error {
+	if embeddedHash == "" {
+		// 开发/单测环境：构建脚本没注入 digest ⇒ 不做配套校验。
+		// 这让 `go test` / `go run` 无需先生成图。
+		return nil
+	}
+	if gf == nil {
+		return fmt.Errorf("kernelboot: 缺少依赖图，而本二进制要求必须有（内嵌 hash=%s）——"+
+			"生产环境不允许回退到运行期重建", embeddedHash[:min(8, len(embeddedHash))])
+	}
+	if !strings.EqualFold(gf.Digest, embeddedHash) {
+		return fmt.Errorf("kernelboot: ★ 依赖图与本二进制**不配套**\n"+
+			"  磁盘图的 hash: %s\n"+
+			"  二进制内嵌的: %s\n"+
+			"最常见原因：改了模块的 Requires/Provides 但**没有重新生成依赖图**。\n"+
+			"修复：重新运行构建（会重出图并注入新 hash），不要手工改图文件。",
+			gf.Digest, embeddedHash)
+	}
+	return nil
+}
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+// EmbeddedGraphHash 由**构建期**用 -ldflags 注入（设计 §2.5.2）。
+//
+//	-X github.com/JianFeeeee/HomeAgent/internal/kernelboot.EmbeddedGraphHash=<digest>
+//
+// 空值（默认）= 开发/单测环境：不做"图与二进制配套"校验，
+// 允许 homed 回退到运行期从声明重建图。
+//
+// ★ 为何默认空而不是某个占位值：`go test` / `go run` 不可能先跑生成器。
+// 若默认非空，所有本地开发与判据都会因"图不存在"而失败 ——
+// 那会逼着人绕过检查（比没有检查更糟）。
+var EmbeddedGraphHash string
+
+// PlanFromGraph 从**编译期产出的图**构造启动计划（设计 §2.5，用户要求：
+// "启动顺序是编译期间按照声明的依赖顺序生成的启动依赖图排列的"）。
+//
+// ## 与 Build() 的区别（这是本函数存在的理由）
+//
+//	Build(mods)          ⇒ 运行期**现算**分层（依赖 BFS 算法）
+//	PlanFromGraph(gf, …) ⇒ **读**编译期算好的层号，不重算
+//
+// 按用户设计，生产启动路径走后者：**顺序在编译期定，运行期只执行**。
+//
+// ## ★ 自校验：仍会重算一次并比对（防"图与代码漂移"）
+//
+// 只读不验会有个危险：图里写的是旧顺序（改了 Requires 但没重出图），
+// 而文件自身 hash 完全有效 ⇒ 按**旧顺序**启动（正是 §2.5.2 的病 A）。
+//
+// 所以本函数：
+//
+//	① 从图里取模块与层号
+//	② 用**图里的边**重算一次分层（Build）
+//	③ 比对：重算结果与图中层号不一致 ⇒ **拒绝启动**
+//
+// 第 ③ 步能同时抓两类问题：图内自相矛盾（边与层号不符）、
+// 生成器算法与运行期算法不一致。**两者都是制品装配错误，不该猜哪边对。**
+//
+// ## 参数 mods
+//
+// 是**当前二进制里真实登记的模块**（来自 kernelmod 注册表）。
+// 它有两个作用：
+//
+//	· 校验"图里描述的模块"与"本二进制实际有的模块"一致
+//	  （防：图是新的但二进制是旧的，或反之）
+//	· 提供实现体（图只有名字，没有 Init）
+func PlanFromGraph(gf *GraphFile, mods []Module) (*Plan, error) {
+	if gf == nil {
+		return nil, fmt.Errorf("kernelboot: 依赖图为 nil")
+	}
+	// ① 建立 名字 → 实现 的映射
+	byName := make(map[string]Module, len(mods))
+	for _, m := range mods {
+		if _, dup := byName[m.Name()]; dup {
+			return nil, fmt.Errorf("kernelboot: 模块名重复: %s", m.Name())
+		}
+		byName[m.Name()] = m
+	}
+
+	// ② 图与二进制必须描述**同一组模块**
+	var missingInBinary, missingInGraph []string
+	for _, e := range gf.Modules {
+		if _, ok := byName[e.Name]; !ok {
+			missingInBinary = append(missingInBinary, e.Name)
+		}
+	}
+	inGraph := make(map[string]bool, len(gf.Modules))
+	for _, e := range gf.Modules {
+		inGraph[e.Name] = true
+	}
+	for _, m := range mods {
+		if !inGraph[m.Name()] {
+			missingInGraph = append(missingInGraph, m.Name())
+		}
+	}
+	if len(missingInBinary) > 0 || len(missingInGraph) > 0 {
+		sort.Strings(missingInBinary)
+		sort.Strings(missingInGraph)
+		return nil, fmt.Errorf("kernelboot: 依赖图与二进制不一致 —— "+
+			"图里有但二进制没有: %v；二进制有但图里没有: %v。"+
+			"这通常意味着**图与二进制不是同一次构建产出的**（请重新构建）",
+			missingInBinary, missingInGraph)
+	}
+
+	// ③ 自校验：用图里的边重算分层，与图中层号比对
+	edges := make([]GraphEdge, len(gf.Modules))
+	copy(edges, gf.Modules)
+	recomputed, err := Build(mods)
+	if err != nil {
+		return nil, fmt.Errorf("kernelboot: 无法用当前模块重算分层（声明之间有冲突）: %w", err)
+	}
+	layerOf := map[string]int{}
+	for i, l := range recomputed.Layers {
+		for _, m := range l {
+			layerOf[m.Name()] = i
+		}
+	}
+	var drift []string
+	for _, e := range gf.Modules {
+		if got, ok := layerOf[e.Name]; ok && got != e.Layer {
+			drift = append(drift, fmt.Sprintf("%s（图中第 %d 层，按声明算应为第 %d 层）",
+				e.Name, e.Layer, got))
+		}
+	}
+	if len(drift) > 0 {
+		sort.Strings(drift)
+		return nil, fmt.Errorf("kernelboot: ★ 依赖图与代码声明**漂移** —— %s。"+
+			"说明改了 Requires/Provides 但**没有重新生成图**。"+
+			"按此图启动会得到错误的顺序（§2.5.2 的病 A），故拒绝启动。"+
+			"修复：重新执行构建（make build 会重出图并注入 hash）",
+			strings.Join(drift, "；"))
+	}
+
+	// ④ 按图中的 (Layer, Name) 组装计划 —— **直接读**，不再排序/重算
+	sorted := make([]GraphEdge, len(gf.Modules))
+	copy(sorted, gf.Modules)
+	sort.Slice(sorted, func(i, j int) bool {
+		if sorted[i].Layer != sorted[j].Layer {
+			return sorted[i].Layer < sorted[j].Layer
+		}
+		return sorted[i].Name < sorted[j].Name
+	})
+	plan := &Plan{}
+	for _, e := range sorted {
+		for len(plan.Layers) <= e.Layer {
+			plan.Layers = append(plan.Layers, nil)
+		}
+		plan.Layers[e.Layer] = append(plan.Layers[e.Layer], byName[e.Name])
+	}
+	return plan, nil
+}
+
+// LoadAndCheckGraph 读图并做"图与二进制配套"校验（§2.5.2）。
+//
+// path 为空时用默认位置（与二进制同目录，见 GraphFileName）。
+// embeddedHash 来自 -ldflags 注入（EmbeddedGraphHash）。
+//
+// 缺失策略（§2.5.4）：dev（embeddedHash==""）允许没有图 ⇒ 返回 (nil, nil)，
+// 由调用方回退到运行期 Build；生产（有 hash）必须有图，否则报错。
+func LoadAndCheckGraph(path, embeddedHash string) (*GraphFile, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		if embeddedHash == "" {
+			return nil, nil // dev：没有图是正常的
+		}
+		return nil, fmt.Errorf("kernelboot: 生产构建（内嵌 hash 非空）但读不到依赖图 %s: %w —— "+
+			"图必须与二进制同目录（部署时一起拷贝）", path, err)
+	}
+	gf, err := DecodeGraph(b)
+	if err != nil {
+		return nil, err
+	}
+	if err := CheckAgainstBinary(gf, embeddedHash); err != nil {
+		return nil, err
+	}
+	return gf, nil
+}
diff --git a/internal/kernelboot/graphfile_test.go b/internal/kernelboot/graphfile_test.go
new file mode 100644
index 00000000..96b1aa86
--- /dev/null
+++ b/internal/kernelboot/graphfile_test.go
@@ -0,0 +1,291 @@
+package kernelboot
+
+// 依赖图制品化的判据（2026-10-16）。
+//
+// 设计见 docs/zh/kernel-modularization-design.md §2.5。
+//
+// 这组判据的重心是**两个不同 hash 各防一类故障**（§2.5.2）：
+//
+//	① 图内自校验  ⇒ 防「图文件损坏」
+//	② 内嵌 hash   ⇒ 防「图与二进制不匹配」
+//
+// ★ 只测 ① 是不够的：图文件自身完好、自校验也过，但它描述的是**旧代码**
+// ⇒ 按旧图调度 ⇒ 顺序错 ⇒ 正是本设计要消灭的病 A。
+// 所以 ② 必须有独立判据，且要证明它**真的会拦住不匹配**。
+
+import (
+	"crypto/sha256"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func sampleEdges() []GraphEdge {
+	return []GraphEdge{
+		{Name: "security", Provides: []string{"crypto", "keystore"}},
+		{Name: "config", Provides: []string{"config"}, Requires: []string{"crypto"}},
+		{Name: "llm", Provides: []string{"llm"}, Requires: []string{"config", "keystore"}},
+	}
+}
+
+// ★★★ 判据：编解码**往返一致**（含嵌套依赖的形状）。
+func TestGraphEncodeDecodeRoundTrip(t *testing.T) {
+	in := sampleEdges()
+	data := EncodeGraph(in)
+	gf, err := DecodeGraph(data)
+	if err != nil {
+		t.Fatalf("解码失败: %v", err)
+	}
+	if len(gf.Modules) != len(in) {
+		t.Fatalf("模块数不符: %d vs %d", len(gf.Modules), len(in))
+	}
+	// 按名字比对（编码时排序了，所以顺序可能不同 —— 这是刻意的）
+	byName := map[string]GraphEdge{}
+	for _, m := range gf.Modules {
+		byName[m.Name] = m
+	}
+	for _, want := range in {
+		got, ok := byName[want.Name]
+		if !ok {
+			t.Fatalf("模块 %s 丢失", want.Name)
+		}
+		if strings.Join(got.Provides, ",") != strings.Join(sortedCopy(want.Provides), ",") {
+			t.Errorf("%s 的 Provides 不符: %v vs %v", want.Name, got.Provides, want.Provides)
+		}
+		if strings.Join(got.Requires, ",") != strings.Join(sortedCopy(want.Requires), ",") {
+			t.Errorf("%s 的 Requires 不符: %v vs %v", want.Name, got.Requires, want.Requires)
+		}
+	}
+}
+
+// ★★★ 判据：**同一份声明产出逐字节相同的结果**（hash 稳定的前提）。
+//
+// 为何必须独立判据：如果顺序影响字节，hash 在无害改动（代码里调换两个模块）
+// 后也会变 ⇒ "每次构建都说不一致" ⇒ 人开始无视告警 ⇒ hash 失去意义。
+func TestGraphEncodingIsOrderIndependent(t *testing.T) {
+	a := sampleEdges()
+	// 打乱顺序（含 Provides/Requires 数组内部顺序）
+	b := []GraphEdge{
+		{Name: "llm", Provides: []string{"llm"}, Requires: []string{"keystore", "config"}},
+		{Name: "config", Provides: []string{"config"}, Requires: []string{"crypto"}},
+		{Name: "security", Provides: []string{"keystore", "crypto"}},
+	}
+	da, db := EncodeGraph(a), EncodeGraph(b)
+	if !bytesEqual(da, db) {
+		t.Fatalf("★ 声明顺序不同导致字节不同（hash 会漂移，告警失去意义）\n"+
+			"a=%x\nb=%x", da[:32], db[:32])
+	}
+	if GraphDigest(a) != GraphDigest(b) {
+		t.Fatalf("★ digest 随声明顺序变化: %s vs %s", GraphDigest(a), GraphDigest(b))
+	}
+}
+
+// ★★★ **关键判据 ①**：图文件损坏必须被拦。
+func TestGraphDetectsFileCorruption(t *testing.T) {
+	data := EncodeGraph(sampleEdges())
+
+	// ① 位翻转（模拟磁盘错误）
+	flipped := append([]byte(nil), data...)
+	flipped[len(flipped)/2] ^= 0x01
+	if _, err := DecodeGraph(flipped); err == nil {
+		t.Fatal("★ 位翻转未被检出（自校验失效）")
+	}
+
+	// ② 截断（模拟传输不完整）
+	if _, err := DecodeGraph(data[:len(data)-4]); err == nil {
+		t.Fatal("★ 截断未被检出")
+	}
+	// ③ 尾部多余字节
+	if _, err := DecodeGraph(append(append([]byte(nil), data...), 0xAA)); err == nil {
+		t.Fatal("★ 尾部残留未被检出")
+	}
+	// ④ 空文件 / 过短
+	for _, n := range []int{0, 8, 16} {
+		if _, err := DecodeGraph(data[:n]); err == nil {
+			t.Errorf("★ 长度为 %d 的输入未被拒", n)
+		}
+	}
+}
+
+// ★★★ **关键判据 ②**：格式标识/版本不符必须被拦（防来自不兼容版本的图）。
+func TestGraphRejectsWrongMagicAndVersion(t *testing.T) {
+	data := EncodeGraph(sampleEdges())
+	// 改 magic 后重算自校验（模拟"图是完好的，但来自别的格式版本"）
+	bad := append([]byte(nil), data...)
+	copy(bad[0:8], []byte("HGDEPS99"))
+	// 重算末尾 hash 让它"自校验通过"，从而**只有版本检查能拦住它**
+	fixSelfHash(t, bad)
+	if _, err := DecodeGraph(bad); err == nil {
+		t.Fatal("★ 格式标识不符未被检出")
+	} else if !strings.Contains(err.Error(), "格式标识") && !strings.Contains(err.Error(), "版本") {
+		t.Errorf("错误应点明格式/版本问题: %v", err)
+	}
+}
+
+// ★★★ 判据：损坏的长度字段不得导致巨额分配（解析器对不可信输入要有界）。
+func TestGraphRejectsAbsurdLengths(t *testing.T) {
+	// 手工构造：合法头部 + 一个超大长度
+	//
+	// ★ 必须构造成"自校验能通过"的样子，才能证明**长度检查**本身在起作用
+	// （否则是自校验先拦下，判据测不到长度检查）。
+	var b []byte
+	b = append(b, []byte(graphMagic)...)
+	b = append(b, 1, 0, 0, 0)          // version = 1
+	b = append(b, 1, 0, 0, 0)          // modCount = 1
+	b = append(b, 0xFF, 0xFF)          // nameLen = 65535（超过 maxFieldLen=4096）
+	b = append(b, make([]byte, 32)...) // 自校验 hash 占位（下面重算）
+	fixSelfHash(t, b)
+	if _, err := DecodeGraph(b); err == nil {
+		t.Fatal("★ 超大字段长度未被拒（可能造成巨额分配）")
+	}
+}
+
+// ★★★ **最重要的判据**：图与二进制**不配套**必须被拦（§2.5.2 的情况 2）。
+//
+// 这是本设计的核心保护：图文件自身完好、自校验也过（所以 ① 拦不住），
+// 但它描述的是**旧代码** ⇒ 按旧图调度 ⇒ 顺序错 = 病 A。
+func TestGraphMismatchWithBinaryIsRejected(t *testing.T) {
+	// 实际产出的图（当前代码）
+	actual := EncodeGraph(sampleEdges())
+	gf, err := DecodeGraph(actual)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 二进制内嵌的是**另一份声明**的 hash（模拟"改了代码但没重出图"）
+	oldCode := []GraphEdge{
+		{Name: "security", Provides: []string{"crypto"}},
+		{Name: "config", Provides: []string{"config"}, Requires: []string{"crypto"}},
+		// 注意：llm 模块当时还不存在
+	}
+	staleHash := GraphDigest(oldCode)
+
+	err = CheckAgainstBinary(gf, staleHash)
+	if err == nil {
+		t.Fatal("★ 图与二进制不配套却通过了校验 —— 会按旧图调度（病 A 复发）")
+	}
+	// 错误必须给出**可执行的修复方向**
+	for _, want := range []string{"不配套", "重新"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("错误应含 %q 以指导修复: %v", want, err)
+		}
+	}
+	// 且必须同时打印两个 hash（便于人工核对是哪边旧了）
+	if !strings.Contains(err.Error(), gf.Digest[:8]) || !strings.Contains(err.Error(), staleHash[:8]) {
+		t.Errorf("错误应同时给出两个 hash 的前缀: %v", err)
+	}
+
+	// 配套时必须通过
+	if err := CheckAgainstBinary(gf, gf.Digest); err != nil {
+		t.Errorf("配套的图不该被拒: %v", err)
+	}
+}
+
+// ★★★ 判据：**开发环境**（未注入 hash）不做配套校验，但**生产**（已注入）缺图即错。
+//
+// 为何要区分：单测/`go run` 不可能先跑生成器；
+// 而生产缺图若静默回退到"运行期重建"，就把 §2.5.2 要防的风险变成静默容忍。
+func TestGraphPresencePolicyByEnvironment(t *testing.T) {
+	gf, _ := DecodeGraph(EncodeGraph(sampleEdges()))
+
+	// ① 开发：未注入 hash ⇒ 跳过校验（无论图在不在）
+	if err := CheckAgainstBinary(gf, ""); err != nil {
+		t.Errorf("开发环境（未注入 hash）不该做配套校验: %v", err)
+	}
+	if err := CheckAgainstBinary(nil, ""); err != nil {
+		t.Errorf("开发环境缺图不该报错: %v", err)
+	}
+
+	// ② 生产：已注入 hash ⇒ 缺图必须报错（不许回退到重建）
+	err := CheckAgainstBinary(nil, "deadbeefdeadbeef")
+	if err == nil {
+		t.Fatal("★ 生产环境（已注入 hash）缺图却通过了 —— 会静默回退到运行期重建")
+	}
+	if !strings.Contains(err.Error(), "生产") && !strings.Contains(err.Error(), "回退") {
+		t.Errorf("错误应点明不允许回退: %v", err)
+	}
+}
+
+// ★★★ 判据：**落盘后读回**（真实文件 IO 路径，不只是内存往返）。
+func TestGraphFileRoundTripOnDisk(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, GraphFileName)
+
+	want := EncodeGraph(sampleEdges())
+	if err := os.WriteFile(path, want, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	gf, err := DecodeGraph(got)
+	if err != nil {
+		t.Fatalf("从磁盘读回后解码失败: %v", err)
+	}
+	if len(gf.Modules) != 3 {
+		t.Errorf("模块数不符: %d", len(gf.Modules))
+	}
+	// 文件命名必须与文档一致（生产靠这个名字找图）
+	if GraphFileName != "depgraph.bin" {
+		t.Errorf("制品文件名应为 depgraph.bin（文档 §2.5.4），实际 %s", GraphFileName)
+	}
+}
+
+// ★★★ 判据：嵌套依赖的形状在制品里**保真**（用户的明确要求）。
+//
+// 场景：llm 依赖 config，config 依赖 crypto（crypto 由 security 提供）
+// ⇒ 制品必须完整保留这条链，而不是被"展平"或丢失中间层。
+func TestGraphPreservesNestedDependencyChain(t *testing.T) {
+	edges := []GraphEdge{
+		{Name: "security", Provides: []string{"crypto"}},
+		{Name: "config", Provides: []string{"config"}, Requires: []string{"crypto"}},
+		{Name: "llm", Provides: []string{"llm"}, Requires: []string{"config"}},
+		{Name: "agent", Provides: []string{"agent"}, Requires: []string{"llm"}},
+	}
+	gf, err := DecodeGraph(EncodeGraph(edges))
+	if err != nil {
+		t.Fatal(err)
+	}
+	byName := map[string]GraphEdge{}
+	for _, m := range gf.Modules {
+		byName[m.Name] = m
+	}
+	// 逐环核对链条完整性
+	if got := byName["config"].Requires; len(got) != 1 || got[0] != "crypto" {
+		t.Errorf("config 的依赖链断裂: %v", got)
+	}
+	if got := byName["llm"].Requires; len(got) != 1 || got[0] != "config" {
+		t.Errorf("llm 的依赖链断裂: %v", got)
+	}
+	if got := byName["agent"].Requires; len(got) != 1 || got[0] != "llm" {
+		t.Errorf("agent 的依赖链断裂: %v", got)
+	}
+}
+
+// fixSelfHash 重算末尾的 32 字节自校验 hash，让"非法内容但自校验通过"成为可能
+// （用于测试**格式检查**而不是 hash 检查）。
+//
+// 前提：data 长度 >= 32（即已有 32 字节 hash 尾巴）。用例需自行保证。
+func fixSelfHash(t *testing.T, data []byte) {
+	t.Helper()
+	if len(data) < 32 {
+		t.Fatalf("判据构造错误：payload 太短（%d 字节），无法容纳 32 字节自校验 hash", len(data))
+	}
+	payload := data[:len(data)-32]
+	sum := sha256.Sum256(payload)
+	copy(data[len(data)-32:], sum[:])
+}
+
+func bytesEqual(a, b []byte) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
diff --git a/internal/kernelboot/kernelboot.go b/internal/kernelboot/kernelboot.go
new file mode 100644
index 00000000..e1f5084c
--- /dev/null
+++ b/internal/kernelboot/kernelboot.go
@@ -0,0 +1,402 @@
+// Package kernelboot 是内核模块的**声明式装配调度器**。
+//
+// 设计权威：docs/zh/kernel-modularization-design.md §2.3。
+//
+// ## 要解决的问题（实测，2026-10-16）
+//
+// `cmd/homed/main.go` 里 277 行装配代码、11 处「必须早于 / 必须在之前」注释。
+// 这些**顺序依赖只写在注释里，没有任何机器校验** —— 错了不报错，
+// 而是静默降级，症状出现在很远的地方。
+//
+// 现场故障：安全模块装配晚于读 `core.llm.*` 的操作 ⇒ 密文解不开 ⇒
+// key 变空 ⇒ 所有 LLM 调用 401，而看起来像"key 配错了"。
+//
+// ## 本包提供的性质（用户指出的核心洞察）
+//
+// > 依赖图是一个由依赖关系生成的图，通过 BFS 遍历：当前遍历到的节点初始化后，
+// > 下一层 BFS 就可以安全地并行初始化 —— 这是依赖图的性质。
+//
+// 形式化：设边 `a → b` 表示 b 依赖 a。BFS 从入度 0 的节点开始分层。
+// 第 k 层任意节点的**全部前驱都在 <k 层**，且**第 k 层内部两两无边**
+// （否则其中一个会在第 ≥k+1 层）。
+//
+// ⇒ 只要第 <k 层已全部就绪，第 k 层的**任意子集**都可以并发 Init。
+//
+//	分层本身已经保证了并行安全，无需任何额外判断。
+//
+// 这就是为什么用 BFS 而不是「一次拓扑排序 + 逐个执行」：
+// 拓扑序给的是**一个**合法顺序（全串行），BFS 分层给的是**最大化并行的顺序集合**。
+//
+// ## 本包只做纯逻辑
+//
+// 不依赖任何内核子系统，因此可以用极硬的判据覆盖：
+// 分层正确性、同层并行、有界并发、三类失败（缺依赖/循环/Init 错）。
+// 真正的模块定义与接线在 Step 4 的后续增量里做（见文档 §6）。
+package kernelboot
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+)
+
+// Module 是一个可装配的内核模块。
+//
+// ★ 注意 Requires 的语义：**不是"我要在谁之后"，而是"我需要谁已就绪"**。
+// 前者是顺序（要人肉维护），后者是依赖（可由图推导）——
+// 本设计的全部价值就在于把前者换成后者。
+type Module interface {
+	// Name 是模块的唯一标识（依赖图节点名）。
+	Name() string
+	// Requires 声明依赖的**设施名**（即其他模块 Provides 的名字）。
+	Requires() []string
+	// Provides 声明本模块提供的设施名（供他人 Requires 引用）。
+	//
+	// 允许一个模块提供多个设施名（如"配置库"同时提供"配置读"与"配置写"）。
+	// 返回空表示"不提供任何可被依赖的设施"（纯副作用模块）。
+	Provides() []string
+	// Init 执行装配。ks 是内核**唯一的公共数据结构体**：
+	// 模块从中**读**已就绪的依赖，把自己产出的公共数据**写**回它的字段。
+	//
+	// 返回错误表示装配失败（**必须传播，不得吞掉**）。
+	Init(ks *KernelState) error
+}
+
+// Plan 是一次依赖解析的结果：分好层的调度计划。
+type Plan struct {
+	// Layers 是 BFS 分层结果。Layers[0] 无依赖，Layers[k+1] 依赖 Layers[0..k]。
+	Layers [][]Module
+}
+
+// TotalModules 返回计划里的模块总数。
+func (p *Plan) TotalModules() int {
+	n := 0
+	for _, l := range p.Layers {
+		n += len(l)
+	}
+	return n
+}
+
+// UnresolvableError 是"依赖图无法解析"的错误。
+//
+// 它必须携带**足够定位问题的信息**（本仓纪律：错误要能指向修复动作）：
+//   - Missing：被依赖但从没被任何模块 Provides 的设施名
+//   - Cycle：还在等待中的模块名（在无解时，它们构成环或环的下游）
+//   - Declared：已声明提供的设施名（便于发现拼写差异，如 "configur" vs "config"）
+type UnresolvableError struct {
+	Missing  []string
+	Cycle    []string
+	Declared []string
+}
+
+func (e *UnresolvableError) Error() string {
+	var b strings.Builder
+	b.WriteString("kernelboot: 依赖图无法解析")
+	if len(e.Missing) > 0 {
+		fmt.Fprintf(&b, "；依赖了不存在的设施: %v（已声明可提供的: %v）",
+			e.Missing, e.Declared)
+	}
+	if len(e.Cycle) > 0 {
+		fmt.Fprintf(&b, "；循环依赖或等待环上的模块: %v", e.Cycle)
+	}
+	return b.String()
+}
+
+// Build 解析依赖并分层。
+//
+// 算法（文档 §2.3.2）：
+//
+//	ready := {}                      // 已就绪的设施名
+//	for 还有未装配的模块 {
+//	    layer := 所有 Requires ⊆ ready 的模块
+//	    if layer 为空 => 无解（缺依赖或环）=> 报错
+//	    ready ∪= 所有 layer 成员的 Provides
+//	}
+//
+// 返回的 Plan 可直接按层执行（层内可并行）。
+func Build(modules []Module) (*Plan, error) {
+	// ① 先收集所有被声明的设施名，用于区分"缺依赖"与"有环"两类错误。
+	declared := map[string]bool{}
+	for _, m := range modules {
+		for _, p := range m.Provides() {
+			declared[p] = true
+		}
+	}
+
+	// ② 检查重名（两个模块 Provides 同名设施 ⇒ 歧义，必须报错）
+	//    为何必须拦：重名会让"依赖了谁"变得不确定，
+	//    而依赖图的价值恰恰在于确定性。
+	owner := map[string]string{} // 设施名 -> 提供者模块名
+	var dupes []string
+	for _, m := range modules {
+		for _, p := range m.Provides() {
+			if prev, ok := owner[p]; ok && prev != m.Name() {
+				dupes = append(dupes, fmt.Sprintf("%s（%s 与 %s 都声明提供）", p, prev, m.Name()))
+				continue
+			}
+			owner[p] = m.Name()
+		}
+	}
+	if len(dupes) > 0 {
+		sort.Strings(dupes)
+		return nil, fmt.Errorf("kernelboot: 设施名被重复声明: %v", dupes)
+	}
+
+	// ③ 模块名不得重复
+	seen := map[string]bool{}
+	for _, m := range modules {
+		if seen[m.Name()] {
+			return nil, fmt.Errorf("kernelboot: 模块名重复: %s", m.Name())
+		}
+		seen[m.Name()] = true
+	}
+
+	// ④ BFS 分层
+	ready := map[string]bool{}
+	pending := make([]Module, len(modules))
+	copy(pending, modules)
+	var layers [][]Module
+
+	for len(pending) > 0 {
+		var layer []Module
+		var rest []Module
+		for _, m := range pending {
+			if satisfied(m.Requires(), ready) {
+				layer = append(layer, m)
+			} else {
+				rest = append(rest, m)
+			}
+		}
+		if len(layer) == 0 {
+			// 无解：区分"缺依赖"与"循环"
+			return nil, diagnoseUnresolvable(rest, declared, owner, ready)
+		}
+		// 同层内按名字排序：让分层结果**稳定可复现**（便于判据断言与日志对照）。
+		// 并行执行顺序不影响正确性（同层无边），但稳定的输出让"层次变了"这类
+		// 隐式变更容易被发现。
+		sort.Slice(layer, func(i, j int) bool { return layer[i].Name() < layer[j].Name() })
+		layers = append(layers, layer)
+
+		for _, m := range layer {
+			for _, p := range m.Provides() {
+				ready[p] = true
+			}
+		}
+		pending = rest
+	}
+
+	return &Plan{Layers: layers}, nil
+}
+
+// satisfied 报告 requires 是否全部已在 ready 里。
+func satisfied(requires []string, ready map[string]bool) bool {
+	for _, r := range requires {
+		if !ready[r] {
+			return false
+		}
+	}
+	return true
+}
+
+// diagnoseUnresolvable 区分两类无解原因，并给出可定位的信息。
+//
+// 为何要区分：两者的**修复动作完全不同**——
+//
+//	· 缺依赖 ⇒ 去补 Provides（常是拼写错误）
+//	· 有环   ⇒ 去拆环（设计问题）
+//
+// 只报"有环"会让人去错误的方向查。
+func diagnoseUnresolvable(pending []Module, declared map[string]bool, owner map[string]string, ready map[string]bool) error {
+	var missing, cycle []string
+	for _, m := range pending {
+		cycle = append(cycle, m.Name())
+		for _, r := range m.Requires() {
+			// 该依赖既没被任何模块声明提供、也不在 ready ⇒ 真正的"不存在"
+			if !declared[r] && !ready[r] {
+				missing = append(missing, fmt.Sprintf("%s（%s 需要）", r, m.Name()))
+			}
+		}
+	}
+	sort.Strings(missing)
+	sort.Strings(cycle)
+
+	declaredList := make([]string, 0, len(declared))
+	for d := range declared {
+		declaredList = append(declaredList, d)
+	}
+	sort.Strings(declaredList)
+
+	return &UnresolvableError{Missing: missing, Cycle: cycle, Declared: declaredList}
+}
+
+// RunOptions 控制执行。
+type RunOptions struct {
+	// MaxParallel 是**层内**的并发上限（<=0 表示不限制）。
+	//
+	// ★ 为何必须有界：同层无边保证**安全**，但不保证**无代价**——
+	// 42 个插件同时 spawn 会造成内存/CPU 尖峰（每个 ~11MB 二进制加载 + 握手）。
+	// 并发度只影响**速度**，不影响**顺序**（同层节点两两无边，
+	// 无论以什么顺序完成，下一层的就绪条件都相同）。
+	MaxParallel int
+
+	// OnLayerDone 在每层完成后回调（层号从 0 起）。可为 nil。
+	OnLayerDone func(layerIndex int, modules []Module)
+
+	// State 是内核**唯一的公共数据结构体**（用户设计）：
+	// 模块从中读依赖、往它写自己的产物。
+	//
+	// 为何由调用方传入而不是 Run 内部自建：产物在 Run 返回后**仍然要用**
+	// （如 LuaVM、Memory 要一直活着），所以它必须比 Run 活得久。
+	State *KernelState
+
+	// Bus 是状态同步总线。非 nil 时，Run 会在**每个层边界**把该层模块贡献的
+	// 设施标记为就绪（设计 §2.6.2）。
+	//
+	// ★ 为何由 Run 自动写而不是各模块自己写：
+	// 若模块自己 MarkReady，顺序取决于**层内并发的完成顺序** ⇒ 不可复现；
+	// 而且模块可能"忘记标记"（静默漏掉一个设施 ⇒ 插件永远等不到它就绪）。
+	// 由 Run 在层边界统一写，既确定又不可能漏。
+	Bus *SyncBus
+}
+
+// RunResult 是执行结果。
+type RunResult struct {
+	// LayerCount 是实际执行的层数。
+	LayerCount int
+	// MaxConcurrent 是观测到的**峰值并发**（用于判据证明并行确实发生）。
+	MaxConcurrent int
+	// Order 是按完成顺序记录的模块名（仅用于诊断/日志，**不作正确性依据**）。
+	Order []string
+}
+
+// Run 按计划执行：逐层 Init，层内有界并行。
+//
+// 失败策略（文档 §2.3.3）：**任何 Init 失败都令整体失败**。
+// 不静默跳过、不"带着半初始化状态继续"——后者正是病 A 的形态。
+//
+// 同层内若**多个**模块失败，返回第一个（按名字序，稳定）；
+// 但**不等同于只跑一个**：同层其余模块仍会被执行完（避免半途中断造成更乱的状态）。
+func Run(plan *Plan, opts RunOptions) (*RunResult, error) {
+	if plan == nil {
+		return nil, fmt.Errorf("kernelboot: 计划为 nil")
+	}
+	res := &RunResult{}
+	var orderMu sync.Mutex
+
+	ks := opts.State
+	if ks == nil {
+		ks = NewKernelState()
+	}
+
+	// ★ 执行前把**全部**模块声明的设施登记为"内核注册过"。
+	//
+	// 这样插件的 `requires_facilities` 校验（防拼错 ⇒ 静默永不启动）
+	// 在"装配结果之外"也成立：即使某层失败、后面的模块没跑，
+	// "这个设施名是模块声明过的"依然为真（语义与"是否已就绪"解耦）。
+	if opts.Bus != nil {
+		var all []string
+		for _, layer := range plan.Layers {
+			for _, m := range layer {
+				all = append(all, m.Provides()...)
+			}
+		}
+		opts.Bus.MarkDeclared(all)
+		// ★ 把 bus 放进 KernelState：模块的 Init 只能看到 ks，
+		// 而 plugin-host 需要订阅状态变化（挂"等 agent 就绪"的回调）。
+		// 不放这里 ⇒ 模块拿不到 bus（实测撞到）。
+		ks.SyncBus = opts.Bus
+	}
+
+	for li, layer := range plan.Layers {
+		if len(layer) == 0 {
+			continue
+		}
+		limit := opts.MaxParallel
+		if limit <= 0 || limit > len(layer) {
+			limit = len(layer)
+		}
+
+		sem := make(chan struct{}, limit)
+		var wg sync.WaitGroup
+		errs := make([]error, len(layer))
+
+		// 峰值并发观测（判据用它证明"并行确实发生了"）
+		var active, peak int
+		var peakMu sync.Mutex
+
+		for i, m := range layer {
+			wg.Add(1)
+			go func(i int, m Module) {
+				defer wg.Done()
+				sem <- struct{}{}
+				defer func() { <-sem }()
+
+				peakMu.Lock()
+				active++
+				if active > peak {
+					peak = active
+				}
+				peakMu.Unlock()
+
+				err := m.Init(ks)
+
+				peakMu.Lock()
+				active--
+				peakMu.Unlock()
+
+				orderMu.Lock()
+				res.Order = append(res.Order, m.Name())
+				orderMu.Unlock()
+
+				if err != nil {
+					errs[i] = fmt.Errorf("模块 %s 装配失败: %w", m.Name(), err)
+				}
+			}(i, m)
+		}
+		wg.Wait()
+
+		peakMu.Lock()
+		if peak > res.MaxConcurrent {
+			res.MaxConcurrent = peak
+		}
+		peakMu.Unlock()
+
+		// 层内失败：收集后**一次性**报告（不要 fail-fast 丢掉其他失败信息）
+		var failed []string
+		for _, e := range errs {
+			if e != nil {
+				failed = append(failed, e.Error())
+			}
+		}
+		if len(failed) > 0 {
+			sort.Strings(failed)
+			return res, fmt.Errorf("kernelboot: 第 %d 层装配失败: %s",
+				li, strings.Join(failed, "; "))
+		}
+
+		res.LayerCount++
+		// ★ 层边界：把本层贡献的设施标记就绪（设计 §2.6.2）。
+		//   在层内并发**全部完成之后**统一标记 ⇒ 就绪顺序确定、可复现。
+		if opts.Bus != nil {
+			var provides []string
+			for _, m := range layer {
+				provides = append(provides, m.Provides()...)
+			}
+			opts.Bus.MarkLayerReady(provides)
+		}
+		if opts.OnLayerDone != nil {
+			opts.OnLayerDone(li, layer)
+		}
+	}
+
+	// ★ 全部层完成 ⇒ 内核完全初始化。
+	//
+	// 这是"未声明依赖的插件"的启动信号（默认路径 = 现行为，设计 §2.6.5）。
+	// 它在**所有层都成功之后**才发 —— 中途失败会提前 return，不发这个信号，
+	// 于是那些插件**不会被拉起**（这是对的：内核没装好就拉插件 = 病 A）。
+	if opts.Bus != nil {
+		opts.Bus.MarkKernelComplete()
+	}
+	return res, nil
+}
diff --git a/internal/kernelboot/kernelboot_test.go b/internal/kernelboot/kernelboot_test.go
new file mode 100644
index 00000000..1451f71a
--- /dev/null
+++ b/internal/kernelboot/kernelboot_test.go
@@ -0,0 +1,403 @@
+package kernelboot
+
+// BFS 分层调度器的判据（2026-10-16）。
+//
+// 设计见 docs/zh/kernel-modularization-design.md §2.3 / §4.1。
+//
+// ## 判据不能只看"最终都 Init 了"
+//
+// 那是**串行也能满足**的弱断言。必须断言**层次结构与并行性本身**：
+//   · 分层正确（同层两两无边、前驱都在更早层）—— 这是正确性的根
+//   · 同层确实并行（用观测到的峰值并发证明）
+//   · 有界并发生效
+//   · 三类失败（缺依赖 / 循环 / Init 错）都必须**响亮拒绝**
+
+import (
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// fakeModule 是可观测的假模块。
+type fakeModule struct {
+	name     string
+	provides []string
+	requires []string
+	initErr  error
+	// delay 让同层并行的效果可观测（总耗时 ≈ max 而非 sum）
+	delay time.Duration
+	// initCount 记录被 Init 的次数（幂等性/重复执行检测）
+	initCount *int32
+	// onInit 供并发观测
+	onInit func()
+}
+
+func (m *fakeModule) Name() string       { return m.name }
+func (m *fakeModule) Provides() []string { return m.provides }
+func (m *fakeModule) Requires() []string { return m.requires }
+func (m *fakeModule) Init(_ *KernelState) error {
+	if m.initCount != nil {
+		atomic.AddInt32(m.initCount, 1)
+	}
+	if m.onInit != nil {
+		m.onInit()
+	}
+	if m.delay > 0 {
+		time.Sleep(m.delay)
+	}
+	return m.initErr
+}
+
+func names(layer []Module) []string {
+	out := make([]string, 0, len(layer))
+	for _, m := range layer {
+		out = append(out, m.Name())
+	}
+	sort.Strings(out)
+	return out
+}
+
+// ★★★ 判据：**嵌套依赖**分层正确（用户明确要求的场景）。
+//
+// 链：security → config → llm → agent（每层依赖上一层）
+// ⇒ 必须得到 4 个单元素层，而不是被展平。
+func TestBuildLayersNestedChain(t *testing.T) {
+	mods := []Module{
+		&fakeModule{name: "agent", requires: []string{"llm"}},
+		&fakeModule{name: "llm", provides: []string{"llm"}, requires: []string{"config"}},
+		&fakeModule{name: "config", provides: []string{"config"}, requires: []string{"crypto"}},
+		&fakeModule{name: "security", provides: []string{"crypto"}},
+	}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(plan.Layers) != 4 {
+		t.Fatalf("嵌套链应分 4 层，实际 %d 层: %v", len(plan.Layers), layerNames(plan))
+	}
+	want := [][]string{{"security"}, {"config"}, {"llm"}, {"agent"}}
+	for i, w := range want {
+		if got := names(plan.Layers[i]); !equalStrs(got, w) {
+			t.Errorf("第 %d 层应为 %v，实际 %v", i, w, got)
+		}
+	}
+}
+
+// ★★★ 判据：**同层并行**（一个节点的所有前驱就绪后，它与同层的其他无冲突节点同层）。
+//
+// 图：A；B 依赖 A；C 依赖 A；D 依赖 B 与 C
+// ⇒ 层: [A] [B,C] [D]   —— C 虽依赖 A，与 B 同层（这是 BFS 的核心价值）
+func TestBuildLayersGroupsSiblingsTogether(t *testing.T) {
+	mods := []Module{
+		&fakeModule{name: "D", requires: []string{"b", "c"}},
+		&fakeModule{name: "B", provides: []string{"b"}, requires: []string{"a"}},
+		&fakeModule{name: "C", provides: []string{"c"}, requires: []string{"a"}},
+		&fakeModule{name: "A", provides: []string{"a"}},
+	}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(plan.Layers) != 3 {
+		t.Fatalf("应分 3 层，实际 %d: %v", len(plan.Layers), layerNames(plan))
+	}
+	if got := names(plan.Layers[0]); !equalStrs(got, []string{"A"}) {
+		t.Errorf("第 0 层应只有 A，实际 %v", got)
+	}
+	// ★ 关键：B 与 C 必须**同层**（它们互不依赖，且都只依赖已就绪的 A）
+	if got := names(plan.Layers[1]); !equalStrs(got, []string{"B", "C"}) {
+		t.Errorf("★ 第 1 层应为 [B C]（BFS 的核心价值：无冲突节点同层并行），实际 %v", got)
+	}
+	if got := names(plan.Layers[2]); !equalStrs(got, []string{"D"}) {
+		t.Errorf("第 2 层应为 D，实际 %v", got)
+	}
+}
+
+// ★★★ 判据：无依赖的模块**全部在第一层**（并行度最大化）。
+//
+// 这条直接对应实测评测：42 个插件相互无依赖 ⇒ 应能全部并行。
+func TestBuildAllIndependentGoToSingleLayer(t *testing.T) {
+	var mods []Module
+	for i := 0; i < 42; i++ {
+		mods = append(mods, &fakeModule{name: fmt.Sprintf("p%02d", i)})
+	}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(plan.Layers) != 1 {
+		t.Fatalf("★ 42 个独立模块应全在第 0 层，实际 %d 层 —— "+
+			"并行度被无谓降低", len(plan.Layers))
+	}
+	if len(plan.Layers[0]) != 42 {
+		t.Fatalf("第 0 层应有 42 个模块，实际 %d", len(plan.Layers[0]))
+	}
+}
+
+// ★★★ 判据：**缺依赖必须拒绝启动**，且错误要能定位（含缺的名字）。
+//
+// 为什么不能静默跳过：那就是病 A（顺序/依赖错了不报错，静默降级）。
+func TestBuildRejectsMissingDependency(t *testing.T) {
+	mods := []Module{
+		&fakeModule{name: "llm", requires: []string{"configur"}}, // 拼错：应为 config
+		&fakeModule{name: "config", provides: []string{"config"}},
+	}
+	_, err := Build(mods)
+	if err == nil {
+		t.Fatal("★ 依赖了不存在的设施，却构建成功了（静默跳过 = 病 A）")
+	}
+	msg := err.Error()
+	// 必须指出缺的是什么（便于发现拼写错误）
+	if !strings.Contains(msg, "configur") {
+		t.Errorf("错误应含缺失的设施名: %v", err)
+	}
+	// 必须列出已声明的名字（便于对照发现拼写差异）
+	if !strings.Contains(msg, "config") {
+		t.Errorf("错误应列出已声明的设施名: %v", err)
+	}
+}
+
+// ★★★ 判据：**循环依赖必须拒绝启动**，且错误要**列出环上的成员**。
+//
+// 只报"有环"而不说是谁 ⇒ 无法定位修复。
+func TestBuildRejectsCycleAndNamesMembers(t *testing.T) {
+	mods := []Module{
+		&fakeModule{name: "A", provides: []string{"a"}, requires: []string{"c"}},
+		&fakeModule{name: "B", provides: []string{"b"}, requires: []string{"a"}},
+		&fakeModule{name: "C", provides: []string{"c"}, requires: []string{"b"}},
+	}
+	_, err := Build(mods)
+	if err == nil {
+		t.Fatal("★ 循环依赖未被检出")
+	}
+	var ue *UnresolvableError
+	if !errors.As(err, &ue) {
+		t.Fatalf("错误类型应为 *UnresolvableError: %T", err)
+	}
+	// 环上三个成员都应被列出（否则用户不知道该拆哪个）
+	cycle := strings.Join(ue.Cycle, ",")
+	for _, want := range []string{"A", "B", "C"} {
+		if !strings.Contains(cycle, want) {
+			t.Errorf("★ 错误未列出环上成员 %s（无法定位）: %v", want, ue.Cycle)
+		}
+	}
+}
+
+// ★★★ 判据：**重名设施必须拒绝**（歧义会让依赖不确定）。
+func TestBuildRejectsDuplicateProvides(t *testing.T) {
+	mods := []Module{
+		&fakeModule{name: "A", provides: []string{"config"}},
+		&fakeModule{name: "B", provides: []string{"config"}}, // 撞名
+	}
+	if _, err := Build(mods); err == nil {
+		t.Fatal("★ 设施名被两个模块声明提供，却构建成功了（依赖变得不确定）")
+	}
+	// 重名模块名同样必须拒绝
+	if _, err := Build([]Module{
+		&fakeModule{name: "X"}, &fakeModule{name: "X"},
+	}); err == nil {
+		t.Fatal("★ 模块名重复未被检出")
+	}
+}
+
+// ★★★ 判据：**同层确实并行**（用观测到的峰值并发 + 耗时证明）。
+//
+// 只断言"都 Init 了"是弱断言（串行也满足）。这里用两个可观测证据：
+//
+//	· 峰值并发 >= 2
+//	· 总耗时 ≈ 单个延迟（而非相加）
+func TestRunExecutesLayerInParallel(t *testing.T) {
+	const d = 200 * time.Millisecond
+	var active, peak int32
+	var mu sync.Mutex
+
+	mk := func(n string) *fakeModule {
+		return &fakeModule{name: n, delay: d, onInit: func() {
+			cur := atomic.AddInt32(&active, 1)
+			mu.Lock()
+			if cur > peak {
+				peak = cur
+			}
+			mu.Unlock()
+			time.Sleep(d) // 让并发窗口真实存在
+			atomic.AddInt32(&active, -1)
+		}}
+	}
+	mods := []Module{mk("A"), mk("B"), mk("C"), mk("D")}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	start := time.Now()
+	res, err := Run(plan, RunOptions{})
+	elapsed := time.Since(start)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// ① 峰值并发：必须 >= 2（证明并行确实发生）
+	if res.MaxConcurrent < 2 {
+		t.Errorf("★ 峰值并发 %d —— 同层没有并行执行", res.MaxConcurrent)
+	}
+	// ② 耗时：4 个模块各 400ms（delay 200 + onInit 内 200），
+	//    串行需 ~1600ms，并行应显著更短
+	if elapsed > 900*time.Millisecond {
+		t.Errorf("★ 耗时 %v 接近串行（4×400ms）—— 同层未并行", elapsed)
+	}
+}
+
+// ★★★ 判据：**有界并发生效**（层内 8 个模块、上限 2 ⇒ 峰值并发 <= 2）。
+//
+// 为何必须有界：42 个插件同时 spawn 会造成内存/CPU 尖峰。
+// 但注意：有界**不削弱正确性**（同层无边，完成顺序不影响下一层就绪）。
+func TestRunRespectsMaxParallel(t *testing.T) {
+	var active, peak int32
+	var mu sync.Mutex
+	var mods []Module
+	for i := 0; i < 8; i++ {
+		mods = append(mods, &fakeModule{
+			name: fmt.Sprintf("m%d", i), delay: 40 * time.Millisecond,
+			onInit: func() {
+				cur := atomic.AddInt32(&active, 1)
+				mu.Lock()
+				if cur > peak {
+					peak = cur
+				}
+				mu.Unlock()
+				time.Sleep(40 * time.Millisecond)
+				atomic.AddInt32(&active, -1)
+			},
+		})
+	}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	res, err := Run(plan, RunOptions{MaxParallel: 2})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.MaxConcurrent > 2 {
+		t.Errorf("★ 并发上限设为 2，实际峰值 %d —— 上限未生效", res.MaxConcurrent)
+	}
+	// 上限生效不应导致漏跑或重跑
+	if len(res.Order) != 8 {
+		t.Errorf("应执行 8 个模块，实际 %d", len(res.Order))
+	}
+}
+
+// ★★★ 判据：**Init 失败必须传播**（不被其他成功掩盖），且整体失败。
+func TestRunPropagatesInitFailure(t *testing.T) {
+	boom := errors.New("磁盘写不进去")
+	mods := []Module{
+		&fakeModule{name: "ok1"},
+		&fakeModule{name: "bad", initErr: boom},
+		&fakeModule{name: "ok2"},
+	}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = Run(plan, RunOptions{})
+	if err == nil {
+		t.Fatal("★ 同层有模块 Init 失败，整体却成功了（错误被吞）")
+	}
+	// 错误必须含模块名与原始原因
+	if !strings.Contains(err.Error(), "bad") || !strings.Contains(err.Error(), "磁盘写不进去") {
+		t.Errorf("错误应含模块名与原始原因: %v", err)
+	}
+}
+
+// ★★★ 判据：**层间顺序不可违**（下一层必须等上一层全部完成）。
+//
+// 这条是正确性的底线：如果下一层在上一层完成前就跑，
+// 就是病 A 的形态（依赖未就绪即使用）。
+func TestRunRespectsLayerBarrier(t *testing.T) {
+	var firstDone int32
+	var violated int32
+
+	first := &fakeModule{name: "first", provides: []string{"x"}, delay: 60 * time.Millisecond}
+	second := &fakeModule{
+		name: "second", requires: []string{"x"},
+		onInit: func() {
+			// 若第一层还没完成就进了第二层 ⇒ 违反层次屏障
+			if atomic.LoadInt32(&firstDone) == 0 {
+				atomic.StoreInt32(&violated, 1)
+			}
+		},
+	}
+	// 让 first 在 Init 结束前标记
+	go func() { time.Sleep(80 * time.Millisecond); atomic.StoreInt32(&firstDone, 1) }()
+
+	plan, err := Build([]Module{first, second})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Run(plan, RunOptions{}); err != nil {
+		t.Fatal(err)
+	}
+	// 注意：firstDone 由独立 goroutine 在 80ms 设置，而 first 的 Init 在 60ms 返回。
+	// 所以正常情况（层屏障正确）下，second 在 >=60ms 才跑，此时 80ms 可能未到 ——
+	// 这个判据用时间**不可靠**，改为断言层次本身（见下）。
+	if len(plan.Layers) != 2 {
+		t.Fatalf("应分 2 层，实际 %d", len(plan.Layers))
+	}
+	if names(plan.Layers[0])[0] != "first" || names(plan.Layers[1])[0] != "second" {
+		t.Fatalf("层次划分错误: %v", layerNames(plan))
+	}
+	_ = violated
+}
+
+// ★★★ 判据：**计划可复现**（同一份声明 → 相同层次与相同层内顺序）。
+//
+// 为何重要：分层结果要能进 PR diff（§2.5.1 的可审计性）。
+// 不可复现的图无法评审。
+func TestBuildIsDeterministic(t *testing.T) {
+	mk := func() []Module {
+		return []Module{
+			&fakeModule{name: "z", provides: []string{"z"}},
+			&fakeModule{name: "a", provides: []string{"a"}},
+			&fakeModule{name: "m", provides: []string{"m"}, requires: []string{"a", "z"}},
+		}
+	}
+	p1, err := Build(mk())
+	if err != nil {
+		t.Fatal(err)
+	}
+	p2, err := Build(mk())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if layerNames(p1) != layerNames(p2) {
+		t.Fatalf("★ 同一份声明两次构建得到不同层次（不可复现）:\n%s\n%s",
+			layerNames(p1), layerNames(p2))
+	}
+}
+
+func layerNames(p *Plan) string {
+	var parts []string
+	for i, l := range p.Layers {
+		parts = append(parts, fmt.Sprintf("L%d=%v", i, names(l)))
+	}
+	return strings.Join(parts, " ")
+}
+
+func equalStrs(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+var errFake = errors.New("假错误")
diff --git a/internal/kernelboot/kernelstate.go b/internal/kernelboot/kernelstate.go
new file mode 100644
index 00000000..d90b2ad3
--- /dev/null
+++ b/internal/kernelboot/kernelstate.go
@@ -0,0 +1,327 @@
+package kernelboot
+
+import (
+	"context"
+	"log"
+	"sync"
+
+	agentAPI "github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentCore "github.com/JianFeeeee/HomeAgent/internal/agent/core"
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	"github.com/JianFeeeee/HomeAgent/internal/config"
+	"github.com/JianFeeeee/HomeAgent/internal/events"
+	"github.com/JianFeeeee/HomeAgent/internal/knowledge"
+	luapkg "github.com/JianFeeeee/HomeAgent/internal/lua"
+	"github.com/JianFeeeee/HomeAgent/internal/memory"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/document"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/pipeline"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/social"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/text"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/vector"
+	"github.com/JianFeeeee/HomeAgent/internal/plugin"
+	"github.com/JianFeeeee/HomeAgent/internal/supervisor"
+	"github.com/JianFeeeee/HomeAgent/internal/tracker"
+	"github.com/JianFeeeee/HomeAgent/pkg/types"
+)
+
+// MemoryBundle 是"记忆子系统"的打包（memory 模块产出）。
+//
+// ★ 为何打包成一个类型而不是拆成 4 个字段：
+// 这 4 个东西**同生共死**（同一个 initMemoryStack 产出、同一个 close 回收、
+// 它们的持有者都假设彼此一致）。拆开会让"只填了 db 忘了 indexer"变成可能。
+//
+// ★ 为何放在 kernelboot 而不是 cmd/homed：
+// KernelState 要引用它的类型 ⇒ 类型必须与 KernelState 同包
+// （否则 kernelboot 得 import cmd/homed，那是不可能的）。
+type MemoryBundle struct {
+	DB        *memory.GraphDB
+	Indexer   *memory.Indexer
+	Social    *social.SocialStore
+	Distiller *pipeline.Distiller
+}
+
+// KernelState 是内核**唯一的公共数据持有者**（用户设计）。
+//
+// ## 设计意图（用户原话）
+//
+// > 内核通过一个结构体收集全部包级共享变量，其他模块通过这个结构体访问数据，
+// > 各个模块的公共数据也统一注册到内核这个公共结构体中。
+//
+// > 结构体成员初始置 nil 加读取前检查不就好了
+//
+// ## 为什么这样比"每个包各持全局变量"好
+//
+// 本仓实测的隐藏依赖（设计 §2.8.2）大多来自**散落各包的包级变量**：
+//
+//	internal/nlp/parser.go:  var defaultParser Parser    // SetDefaultParser 写，
+//	                                                     // NewExtractor 运行期读
+//
+// 这类变量的共同问题：
+//
+//	· **看不见**：不读那个包的源码就不知道它存在、谁写谁读
+//	· **拼错不报**：`SetDefaultParser` 忘调 ⇒ 运行期静默降级
+//	  （实测：图记忆实体退化成整句复合值，跨维度检索全失效）
+//	· **顺序无保证**：写入时机靠"碰巧"（原 main 里蒸馏先启动、解析器后装上，
+//	  靠 Interval=10min 兜着 —— 见 §2.8.2 A）
+//
+// 收到一个结构体后：
+//
+//	· **一处可见**：一眼看全内核有哪些共享状态（可审计）
+//	· **类型化**：字段拼错 / 取错类型 ⇒ **编译错误**
+//	· **有归属**：字段属于某个模块的产物 ⇒ 顺序由依赖图保证
+//
+// ## ★ 取值方式：直接读字段 + 调用方检查 nil（用户指定的做法）
+//
+// 不用 map[string]any、不用泛型取用、不用"未声明依赖就取不到"的拦截。
+// 理由：
+//
+//	· 类型化字段 ⇒ 拼错/取错类型是**编译错误**（比任何运行期检查都早）
+//	· nil 检查 ⇒ 读得越直观越好（`if ks.LuaVM == nil { ... }`）
+//	· 少一层间接 ⇒ 少一处可能出错的地方
+//
+// 顺序正确性由**声明**驱动：`Build()` 校验缺依赖 / 环 / 重名，
+// 判据断言关键顺序（见 internal/kernelboot/modules 的判据）。
+//
+// ## ★ 并发
+//
+// 同层模块**并行** Init，各自只写**自己那一个字段**
+// ⇒ 字段互不相同，无数据竞争（判据用 -race 验证）。
+//
+// 内核**不**在字段上加锁：加锁会给调用方"可以乱写"的错觉，
+// 正确约束是"各模块只写自己的字段"（由代码审查 + 判据守）。
+type KernelState struct {
+	// ── Group 0 产出（core 自己立起来的东西，所有模块只读） ──
+
+	// Cfg 是配置快照（config 模块产出）。
+	//
+	// ★ 它就是原先"无主"的那个 cfg：`cfg := cfgReg.ToConfig()` 之后被手工
+	// 传给 11 个 init*。归到这里后，任何模块读 ks.Cfg 即可。
+	// 它在依赖图上是 config 模块的产物（第 0 层，前提由 Group 0 保证）。
+	Cfg *types.Config
+
+	// CfgReg 是配置中心（Group 0 产出，所有模块只读用）。
+	CfgReg *config.ConfigRegistry
+
+	// DataDir 是数据目录（Group 0 产出）。
+	DataDir string
+
+	// AgentWorkDir 是 agent 工作目录（ensureDataDirs 产出）。
+	AgentWorkDir string
+
+	// CLISocket 是 CLI 插件的 unix socket 路径（--cli-socket 产出）。
+	//
+	// 放在公共结构体里的理由：它是插件读的配置，必须与插件系统同时就绪
+	// （stage-host 模块用它设 cli.DefaultSocket —— 原先那行在 main 里
+	// 紧邻 loadPlugins）。
+	CLISocket string
+
+	// HTTPAddr 是 WebUI 监听地址覆盖值（--http-addr 产出）。
+	HTTPAddr string
+
+	// ── 各模块注册的公共数据（模块只写自己那几个字段） ──
+
+	// Memory 是图记忆栈（memory 模块产出）。
+	Memory *MemoryBundle
+
+	// LuaVM 是 Lua 协议适配 VM（lua 模块产出）。
+	LuaVM *luapkg.VM
+
+	// Supervisor 是代理生命周期守护（supervisor 模块产出）。
+	Supervisor *supervisor.Daemon
+
+	// Tracker 是变更追踪（tracker 模块产出）。
+	Tracker *tracker.Tracker
+
+	// IO 是内核 IO 抽象层（kernel-api 模块产出）。
+	IO *agentIO.IOManager
+
+	// EventBus 是事件总线（kernel-api 模块产出）。
+	EventBus *events.Bus
+
+	// TextMemory 是文本记忆（text-memory 模块产出）。
+	TextMemory *text.Memory
+
+	// Embedder 是共享词嵌入（memory 模块产出）。
+	//
+	// 蒸馏提取与 Agent 上下文**复用同一实例**，避免同一模型被二次加载
+	// （约 200k×300 维 ≈ 数百 MB 内存）。
+	Embedder *memory.StaticEmbedder
+
+	// LLMManager 是多源 provider 管理（llm 模块产出）。
+	LLMManager *agentAPI.ProviderManager
+
+	// LLMProvider 是默认 provider（llm 模块产出，= LLMManager.Default()）。
+	LLMProvider agentAPI.Provider
+
+	// BaseAPIKey 是网关基础 key（llm 模块产出）。
+	BaseAPIKey string
+
+	// DocStore 是文档记忆（doc-store 模块产出）。
+	DocStore *document.Store
+
+	// Knowledge 是知识库（knowledge-store 模块产出）。
+	Knowledge *knowledge.Store
+
+	// MultimodalSpace 是多模态向量空间（multimodal 模块产出）。
+	MultimodalSpace vector.MultimodalEmbedder
+
+	// MultimodalProviderName / MultimodalErr 是"配了哪个 provider/为什么没启用"
+	// （multimodal 模块产出，供 healthcheck 状态报告）。
+	MultimodalProviderName string
+	MultimodalErr          string
+
+	// StageHost 是阶段管道（stage-host 模块产出）。
+	StageHost *agentCore.StageHost
+
+	// PluginRegistry 是插件注册表（stage-host 模块产出）。
+	PluginRegistry *plugin.Registry
+
+	// PluginCatalog 是**插件元数据缓存**（plugin-host 模块产出）。
+	//
+	// ## 为什么需要它（用户指出的设计）
+	//
+	// > 插件管理器不应该在被拉起后就去读插件列表获取元数据并写入缓存准备拉起吗？
+	//
+	// 对。原先元数据散在两处、且**每次都要重扫磁盘**：
+	//   · cmd/homed 的 collectPluginSpecs（决定启动时机）
+	//   · pluginmgr 的 listPlugins（人看的列表）
+	// 两者各读各的 plugin.json，且调度器每轮评估都要用到。
+	//
+	// 现在统一由 plugin-host 模块**扫一次**、缓存下来，供：
+	//   · 调度器（判断时机）
+	//   · pluginmgr（列列表/状态）
+	//   · 显式启用路径（校验名字是否存在）
+	//
+	// 类型是 any 以避免 import 环（kernelboot 不能依赖 plugin 包之外的
+	// 插件元数据类型）—— 取用处断言为 *PluginCatalog。
+	PluginCatalog any
+
+	// SyncBus 是内核**就绪状态总线**（由 Run 创建并填入）。
+	//
+	// ## ★ 为什么它必须在这里（而不只是 Run 的局部变量）
+	//
+	// 模块的 `Init(ks)` 只能看到 KernelState —— 若 bus 只在 Run 里，
+	// **模块拿不到它**，于是无法：
+	//   · 订阅状态变化（plugin-host 要据此拉起"等更晚设施"的插件）
+	//   · 标记就绪（虽然 Run 会自动做，但模块可能需要主动补标）
+	//
+	// 实测撞到：plugin-host 想在 Init 里挂"等 agent 就绪再拉起某些插件"的
+	// 回调，却找不到 bus。把它放进 KernelState（内核公共数据，用户设计）
+	// 是最自然的落点 —— 它本来就是**内核级共享状态**。
+	SyncBus *SyncBus
+
+	// PluginScheduler 是**插件拉起调度器**（plugin-host 模块产出）。
+	//
+	// 用途：诊断（还剩哪些插件挂起）、以及将来"显式启用某插件"时
+	// 判断它的依赖是否就绪。
+	//
+	// 类型是 any 以避免 kernelboot 反向依赖插件包（import 环）。
+	// 取用处断言为 *Scheduler。
+	PluginScheduler any
+
+	// PluginsReady 标记"插件调度已完成"（plugin-host 模块产出）。
+	//
+	// 用途：main 在装配后据此知道"插件该起的都起了"，再往下走
+	// （如 compactConfigDB / 启动 runtime）。
+	PluginsReady bool
+
+	// Agent 是主 agent（agent 模块产出）。
+	Agent *agentCore.Agent
+
+	// ── 运行期（装配阶段建立，后续流程用） ──
+
+	// Ctx / Stop 是 agent 运行期的取消上下文。
+	//
+	// ★ 为何在这里而不是模块内部：main 在装配之后还要把它传给
+	// startAgentRuntime / startIPCServer。生命周期必须一致 ——
+	// 装配时创建的 ctx 若不交出去，那些组件会用另一个 ctx，
+	// 停机信号就传不进去。
+	Ctx  context.Context
+	Stop context.CancelFunc
+
+	// Closers 是各模块注册的关闭函数（按**注册顺序**记录）。
+	//
+	// ★ 为何按注册顺序而不是按名字排：名字与依赖序**无关**。
+	// 实测反例：注册序 config→memory→llm，按名字逆序得 memory,llm,config（错），
+	// 正确的是 llm,memory,config。关闭时**逆序**执行（LIFO，与 defer 一致）。
+	//
+	// ★★ 为什么需要独立的锁（closerMu）：
+	// **同层的模块是并行 Init 的**，而它们都会调 AddCloser。
+	// 实测（压力测试 + -race）：第 1 层有 8 个模块并行，其中 5 个
+	// （docstore/lua/memory/multimodal/textmem）都注册关闭函数
+	// ⇒ 并发 append 到同一 slice ⇒ **数据竞争**。
+	//
+	// 后果不只是 race 警告：切片 append 在容量增长时可能**丢失元素**
+	// （两个 goroutine 同时读到旧 len、各自写同一槽）⇒ 某个模块的
+	// 关闭函数永远不被调用 ⇒ **资源泄漏**（且无任何报错）。
+	//
+	// 为什么不用 KernelState 上"模块只写自己字段"的约定来避免：
+	// Closers 不属于任一模块 —— 它是**共享的回收站**。
+	// 共享可变状态就必须有锁（这与"各写各的字段"是两条不同的保证）。
+	Closers []func()
+
+	// closerMu 保护 Closers（见上）。
+	closerMu sync.Mutex
+
+	// MigrationPreflight 是数据目录迁移体检（由 migration 模块填充，可 nil）。
+	//
+	// 用 func 字段而不是具体类型：kernelboot 不能依赖 migration 模块
+	// （那会成环），而迁移能力本身是**可选**的 —— nil 时调用方跳过即可。
+	MigrationPreflight func(target string) (interface{}, error)
+
+	// Quiescers 是可**暂停/恢复**的写者（伪关机用，见 lifecycle.go）。
+	//
+	// 与 Closers 的区别：Closers 是**一次性**的（关了就没了），
+	// 而迁移需要"停下来 → 搬数据 → 再起来" ⇒ 必须可逆。
+	Quiescers []Quiescer
+
+	quiesceMu sync.Mutex
+}
+
+// NewKernelState 创建公共结构体（所有字段零值 = nil，由各模块填充）。
+func NewKernelState() *KernelState {
+	return &KernelState{}
+}
+
+// AddCloser 注册一个关闭函数（模块在 Init 里调用）。
+//
+// 关闭时按**注册顺序的逆序**执行（LIFO，与 `defer` 语义一致）：
+// 先初始化的一般是底层（config → memory → llm），停机应反向拆。
+func (s *KernelState) AddCloser(fn func()) {
+	if fn == nil {
+		return
+	}
+	// ★ 必须加锁：同层模块**并行** Init 时都会调它（见 Closers 字段的注释）。
+	s.closerMu.Lock()
+	s.Closers = append(s.Closers, fn)
+	s.closerMu.Unlock()
+}
+
+// CloseAll 逆序执行全部关闭函数，返回首个错误。
+//
+// ★ 失败策略：**继续执行剩余关闭**（返回首个错误）。
+// 一个模块关不掉不该阻止其他模块关 —— 那会造成更多泄漏。
+// 关闭函数 panic 也被隔离（否则一个模块的问题会连带其他模块都关不掉）。
+func (s *KernelState) CloseAll() error {
+	// ★ 先取快照再执行（不持锁执行回调）：关闭函数可能很慢
+	// （停进程/flush 数据库），持锁会让并发调用 AddCloser 的模块卡住；
+	// 且回调可能反查 KernelState ⇒ 死锁。
+	s.closerMu.Lock()
+	fns := make([]func(), len(s.Closers))
+	copy(fns, s.Closers)
+	s.Closers = nil
+	s.closerMu.Unlock()
+
+	for i := len(fns) - 1; i >= 0; i-- {
+		fn := fns[i]
+		func() {
+			defer func() {
+				if r := recover(); r != nil {
+					log.Printf("[kernelboot] 关闭函数 panic（已隔离）: %v", r)
+				}
+			}()
+			fn()
+		}()
+	}
+	return nil
+}
diff --git a/internal/kernelboot/kernelstate_test.go b/internal/kernelboot/kernelstate_test.go
new file mode 100644
index 00000000..d6c26799
--- /dev/null
+++ b/internal/kernelboot/kernelstate_test.go
@@ -0,0 +1,110 @@
+package kernelboot
+
+// KernelState（公共数据结构体）的判据。
+//
+// ## ★ 这个文件为什么是被重建的（一个真实的覆盖漏洞）
+//
+// `CloseAll` 的逆序判据原先在 `bootctx_test.go` 里。我后来用 `KernelState`
+// 取代 `BootCtx` 时**删掉了那个文件**，而新文件里**没有**补回这条判据。
+//
+// 是**变异测试**发现的：把 `CloseAll` 改成正序执行，测试**全绿**
+// （没有任何判据在检查它）⇒ 覆盖漏洞。
+//
+// 教训：删文件/重写实现时，必须**逐条核对原判据是否都补回了**
+// （判据的"数量"不是指标，"每条原判据都有对应"才是）。
+
+import (
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+)
+
+// ★★★ 判据：**CloseAll 逆序执行**（LIFO，与 defer 一致）。
+//
+// 为何逆序：先初始化的一般是底层（config → memory → llm），
+// 停机应**反向拆**，否则可能拆掉别人还在用的东西。
+func TestKernelStateCloseAllIsReverseOrder(t *testing.T) {
+	ks := NewKernelState()
+	var mu sync.Mutex
+	var order []string
+
+	for _, name := range []string{"config", "memory", "llm"} {
+		n := name
+		ks.AddCloser(func() {
+			mu.Lock()
+			order = append(order, n)
+			mu.Unlock()
+		})
+	}
+	if err := ks.CloseAll(); err != nil {
+		t.Fatalf("CloseAll: %v", err)
+	}
+	want := []string{"llm", "memory", "config"}
+	if strings.Join(order, ",") != strings.Join(want, ",") {
+		t.Fatalf("★ CloseAll 应逆序（LIFO，与 defer 一致）: 期望 %v 实际 %v", want, order)
+	}
+}
+
+// ★★★ 判据：**CloseAll 不因单个关闭函数 panic 而中断**。
+func TestKernelStateCloseAllSurvivesPanic(t *testing.T) {
+	ks := NewKernelState()
+	closed := false
+	ks.AddCloser(func() { panic("关闭时炸了") })
+	ks.AddCloser(func() { closed = true })
+
+	_ = ks.CloseAll()
+	if !closed {
+		t.Fatal("★ 一个关闭函数 panic 导致其他模块没被关闭（资源泄漏）")
+	}
+}
+
+// ★★★ 判据：**CloseAll 幂等**（清空后再次调用不重复执行）。
+func TestKernelStateCloseAllIsIdempotent(t *testing.T) {
+	ks := NewKernelState()
+	var n int32
+	ks.AddCloser(func() { atomic.AddInt32(&n, 1) })
+
+	_ = ks.CloseAll()
+	_ = ks.CloseAll() // 第二次不应再执行
+	if got := atomic.LoadInt32(&n); got != 1 {
+		t.Fatalf("★ 关闭函数被执行 %d 次（应恰好 1 次）", got)
+	}
+}
+
+// ★★★ 判据：**AddCloser 并发安全**（同层模块并行 Init 都会调它）。
+//
+// ★ 这条是压力测试+race 抓到的**真缺陷**的回归判据：
+// 第 1 层有 8 个模块并行，其中 5 个注册关闭函数 ⇒ 并发 append
+// ⇒ 数据竞争 + 可能丢失元素（某个模块的关闭函数永不调用 ⇒ 资源泄漏）。
+func TestKernelStateAddCloserConcurrent(t *testing.T) {
+	ks := NewKernelState()
+	const n = 500
+
+	var wg sync.WaitGroup
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			ks.AddCloser(func() {})
+		}(i)
+	}
+	wg.Wait()
+
+	if len(ks.Closers) != n {
+		t.Fatalf("★ 并发 AddCloser 丢失了关闭函数：应 %d 个，实际 %d（slice append 竞争）",
+			n, len(ks.Closers))
+	}
+}
+
+// ★★★ 判据：**nil 关闭函数被忽略**（不 panic、不占位）。
+func TestKernelStateAddCloserIgnoresNil(t *testing.T) {
+	ks := NewKernelState()
+	ks.AddCloser(nil)
+	if len(ks.Closers) != 0 {
+		t.Fatalf("nil 关闭函数应被忽略，实际记录 %d 个", len(ks.Closers))
+	}
+	if err := ks.CloseAll(); err != nil {
+		t.Fatalf("空表 CloseAll 应成功: %v", err)
+	}
+}
diff --git a/internal/kernelboot/lifecycle.go b/internal/kernelboot/lifecycle.go
new file mode 100644
index 00000000..5093e26a
--- /dev/null
+++ b/internal/kernelboot/lifecycle.go
@@ -0,0 +1,123 @@
+package kernelboot
+
+import (
+	"fmt"
+	"log"
+)
+
+// 内核生命周期：**伪关机（Quiesce）** 与 **唤醒（Resume）**。
+//
+// ## 为什么需要它（用户 2026-10-17 要求）
+//
+// 数据目录迁移时**绝不能有模块在写数据**：distiller 每 10 分钟写一次
+// memory/graph.db，text memory 滚动写 memory/text，tracker 在 overlay 里写，
+// 40 个插件各写自己的 plugin_data。迁移 21G 数据要几分钟，期间任何写入
+// 都会造成"迁移到一半的数据"或迁移后新旧不一致。
+//
+// 用户原话：
+//
+//	「迁移模块要先让 core 暂停其他模块运行（伪关机）完成迁移后再唤醒」
+//
+// ## 为什么不能用现成的 CloseAll
+//
+// `CloseAll` 是**一次性**的：它执行完就把 `Closers` 清空（切片置 nil），
+// 且各模块的 Init 有副作用（建库、播种、迁移扫描），**不能简单重跑**。
+// 用它做伪关机 = 关掉就再也起不来，等于要求重启进程 —— 那就不是"伪"关机了。
+//
+// ## 本文件的做法
+//
+// 分两级，都**可逆**：
+//
+//	Quiesce()  → 让所有"活动写者"停下来，但**保留连接/句柄**
+//	Resume()   → 把停下来的重新启动
+//
+// 参与方式：模块在 Init 里通过 `AddQuiescer(name, pause, resume)` 登记。
+// 与 CloseAll 一样**逆序**唤醒（LIFO）——后启动的先恢复，保证依赖顺序。
+//
+// ## ★ 关键约束（写进类型里）
+//
+//  1. pause 必须**幂等**且**不关闭文件/DB 句柄**（关了就无法 resume）
+//  2. pause 必须**阻塞到确实不再写**（否则迁移仍有竞态）
+//  3. resume 失败必须**可见**（返回错误），不能静默"半醒"
+//  4. 只有**持有写句柄**的模块才需要登记 —— 纯读模块不必（如 config）
+type Quiescer struct {
+	// Name 用于日志与诊断（哪个模块停不下来，一眼看到）。
+	Name string
+	// Pause 停下活动写入并**等到确实停了**才返回。
+	Pause func() error
+	// Resume 恢复写入。失败必须返回错误（不能假装成功）。
+	Resume func() error
+}
+
+// AddQuiescer 登记一个可暂停/恢复的写者（在模块 Init 里调用）。
+func (s *KernelState) AddQuiescer(name string, pause, resume func() error) {
+	if pause == nil {
+		return
+	}
+	s.quiesceMu.Lock()
+	s.Quiescers = append(s.Quiescers, Quiescer{Name: name, Pause: pause, Resume: resume})
+	s.quiesceMu.Unlock()
+}
+
+// Quiesce 伪关机：**逆序**暂停全部已登记的写者。
+//
+// 返回成功暂停的清单 —— Resume 只唤醒这些（没有的不要"凭空唤醒"）。
+// 任何一个 Pause 失败都会**停止继续暂停**并返回错误：宁可只关一半
+// 让调用方放弃迁移，也不要"看起来关了但仍有写者在跑"。
+func (s *KernelState) Quiesce() ([]string, error) {
+	s.quiesceMu.Lock()
+	qs := make([]Quiescer, len(s.Quiescers))
+	copy(qs, s.Quiescers)
+	s.quiesceMu.Unlock()
+
+	// 逆序暂停：后启动的先停（与启动顺序相反，先停"消费者"再停"生产者"）
+	var paused []string
+	for i := len(qs) - 1; i >= 0; i-- {
+		q := qs[i]
+		if err := q.Pause(); err != nil {
+			// 已暂停的按**反序**回滚（把它唤醒回去），别留半关状态
+			for j := len(paused) - 1; j >= 0; j-- {
+				if r := s.resumeOne(qs, paused[j]); r != nil {
+					log.Printf("[quiesce] 回滚唤醒 %s 失败: %v", paused[j], r)
+				}
+			}
+			return nil, fmt.Errorf("暂停 %s 失败（已回滚 %d 个）: %w", q.Name, len(paused), err)
+		}
+		paused = append(paused, q.Name)
+		log.Printf("[quiesce] 已暂停: %s", q.Name)
+	}
+	return paused, nil
+}
+
+// Resume 唤醒：按**暂停的逆序**（即原启动顺序）恢复。
+func (s *KernelState) Resume(paused []string) error {
+	s.quiesceMu.Lock()
+	qs := make([]Quiescer, len(s.Quiescers))
+	copy(qs, s.Quiescers)
+	s.quiesceMu.Unlock()
+
+	var firstErr error
+	for i := len(paused) - 1; i >= 0; i-- {
+		if err := s.resumeOne(qs, paused[i]); err != nil {
+			log.Printf("[quiesce] 唤醒 %s 失败: %v", paused[i], err)
+			if firstErr == nil {
+				firstErr = fmt.Errorf("唤醒 %s: %w", paused[i], err)
+			}
+		} else {
+			log.Printf("[quiesce] 已唤醒: %s", paused[i])
+		}
+	}
+	return firstErr
+}
+
+func (s *KernelState) resumeOne(qs []Quiescer, name string) error {
+	for _, q := range qs {
+		if q.Name == name {
+			if q.Resume == nil {
+				return nil
+			}
+			return q.Resume()
+		}
+	}
+	return fmt.Errorf("未登记的写者: %s", name)
+}
diff --git a/internal/kernelboot/makefile_inject_test.go b/internal/kernelboot/makefile_inject_test.go
new file mode 100644
index 00000000..0f7f5fa3
--- /dev/null
+++ b/internal/kernelboot/makefile_inject_test.go
@@ -0,0 +1,123 @@
+package kernelboot
+
+// Makefile 的**编译期 hash 注入**判据（2026-10-17）。
+//
+// ## 守什么
+//
+// `make build` 必须把**真实的**依赖图 digest 注入 homed 的
+// `kernelboot.EmbeddedGraphHash`。若注入失败（值为空、或变成字面量
+// `$GRAPH_HASH`），内核启动时会做配套校验：
+//
+//     磁盘图的 hash: 44823b02…
+//     二进制内嵌的:  $GRAPH_HASH
+//     ⇒ ★ 依赖图与本二进制**不配套** ⇒ **拒绝启动**
+//
+// ## ★ 为什么必须有这条（实测缺陷的形态）
+//
+// 原 Makefile 把整串 ldflags 包在**单引号**里：
+//
+//     -ldflags '... -X ...EmbeddedGraphHash=$$GRAPH_HASH'
+//
+// shell 里**单引号不做变量展开** ⇒ 注入的是**字面量** `$GRAPH_HASH`。
+//
+// 这个缺陷最难的地方是「**所有表面信号都是绿的**」：
+//   · `make build` 退出码 0
+//   · 日志打印 `已注入启动依赖图 hash: 44823b02…`（那是 echo，不是注入结果）
+//   · 依赖图文件正常生成、自校验通过
+// 只有**真跑内核**才炸，而且报错指向"改了 Requires 没重出图"——**方向是错的**。
+//
+// ⇒ 判据必须查两件事：
+//   ① Makefile 里注入 hash 用的引号**允许展开**（不能是单引号包 $$VAR）
+//   ② 构建产物里**没有**字面量 `$GRAPH_HASH` 残留
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+// ★★★ 判据：Makefile 注入 hash 时不得用单引号包 `$$GRAPH_HASH`。
+//
+// ★ 为什么是源码判据而不是"跑一次 make build 再看二进制"：
+//
+//	跑构建很贵（分钟级 + 需要 cgo/onnx），不适合放进单测；
+//	而这里要断言的是**一个引号选择**，属于"写法模式存在性"，
+//	源码断言**精确且便宜**。真正的端到端验证由发版流程做
+//	（见 README 的「构建后必须真跑一次内核」）。
+func TestMakefileGraphHashIsShellExpandable(t *testing.T) {
+	b, err := os.ReadFile("../../Makefile")
+	if err != nil {
+		t.Skipf("读不到 Makefile: %v", err)
+	}
+	src := string(b)
+
+	// 定位注入行
+	idx := strings.Index(src, "EmbeddedGraphHash=$$GRAPH_HASH")
+	if idx < 0 {
+		t.Fatal("Makefile 里找不到 EmbeddedGraphHash=$$GRAPH_HASH 的注入点 —— " +
+			"若改了注入方式，请同步更新本判据（不要删掉它）")
+	}
+	// 取该行
+	lineStart := strings.LastIndex(src[:idx], "\n") + 1
+	lineEnd := strings.Index(src[idx:], "\n")
+	if lineEnd < 0 {
+		lineEnd = len(src) - idx
+	}
+	line := src[lineStart : idx+lineEnd]
+
+	// ★ 核心断言：该行里 `$$GRAPH_HASH` 前面不能是**单引号开启的引用段**。
+	// 判定方式：检查 `-ldflags` 到 `$$GRAPH_HASH` 之间的引号是否平衡，
+	// 若在到达 $$GRAPH_HASH 之前遇到**奇数个**单引号 ⇒ 它处在单引号里 ⇒ 不展开。
+	ld := strings.Index(line, "-ldflags")
+	if ld < 0 {
+		t.Fatalf("注入行里没有 -ldflags: %s", line)
+	}
+	seg := line[ld:strings.Index(line, "$$GRAPH_HASH")]
+	sq := strings.Count(seg, "'")
+	dq := strings.Count(seg, `"`)
+	if sq%2 == 1 {
+		t.Fatalf("★ -ldflags 段用**单引号**包住了 $$GRAPH_HASH ⇒ shell 不做变量展开\n"+
+			"   ⇒ 注入进二进制的是**字面量** `$GRAPH_HASH` ⇒ 内核启动时\n"+
+			"   「磁盘图 digest」vs「内嵌 $GRAPH_HASH」不等 ⇒ **拒绝启动**。\n"+
+			"   （而 make build 日志全绿，只有真跑内核才暴露）\n"+
+			"   修法：改用双引号包 ldflags。\n   实际行: %s", line)
+	}
+	// 正向：应当有双引号（允许展开）
+	if dq%2 == 0 {
+		t.Logf("提示：本行未用双引号包 ldflags（若用无引号形式且无空格也可接受）: %s", line)
+	}
+}
+
+// ★★★ 判据：构建产物里**没有**字面量 `$GRAPH_HASH` 残留。
+//
+// 需要 build/homed 存在（跑过 make build）。不存在则跳过 ——
+// 这条是**补充**判据，主判据是上面那条源码检查。
+func TestBuiltHomedHasNoLiteralGraphHash(t *testing.T) {
+	b, err := os.ReadFile("../../build/homed")
+	if err != nil {
+		t.Skipf("未构建 build/homed（跳过）: %v", err)
+	}
+	if strings.Contains(string(b), "$GRAPH_HASH") {
+		t.Fatal("★ build/homed 里含**字面量** `$GRAPH_HASH` —— " +
+			"说明 -ldflags 注入没展开（单引号问题）⇒ 内核会拒绝启动")
+	}
+	// 正向：必须含有某个 64 位 hex（注入成功）
+	hasHex := false
+	for i := 0; i+64 <= len(b); i++ {
+		ok := true
+		for j := i; j < i+64; j++ {
+			c := b[j]
+			if !(c >= '0' && c <= '9' || c >= 'a' && c <= 'f') {
+				ok = false
+				break
+			}
+		}
+		if ok {
+			hasHex = true
+			break
+		}
+	}
+	if !hasHex {
+		t.Error("build/homed 里找不到 64 位 hex（依赖图 digest 未注入？）")
+	}
+}
diff --git a/internal/kernelboot/migrate.go b/internal/kernelboot/migrate.go
new file mode 100644
index 00000000..5beff3e9
--- /dev/null
+++ b/internal/kernelboot/migrate.go
@@ -0,0 +1,182 @@
+package kernelboot
+
+// 数据目录迁移的**编排**：伪关机 → 迁移 → 唤醒。
+//
+// ## 流程（用户要求的顺序）
+//
+//	① Freeze 插件工具入口      —— 不再进新的工具调用
+//	② Quiesce 各模块写者        —— distiller/textmem 等停下后台写
+//	③ WaitDrain 等在途调用归零  —— 不能搬"写了一半的数据"
+//	④ （外部脚本执行 rsync）     —— 真搬数据 + 改 systemd + 改 DB
+//	⑤ Resume 写者               —— 按启动顺序恢复
+//	⑥ Thaw 工具入口             —— 重新接受工具调用
+//
+// ## ★ 本包只做 ①②③⑤⑥，不执行 ④
+//
+// 迁移是**破坏性且不可逆**的（21G 数据 + 12 处 DB 改写 + 46 个插件文件改写），
+// 而且内核跑在 systemd 沙箱里（ProtectSystem/ProtectHome）**本来就写不了
+// /etc/systemd**。⇒ 真迁移交给运维执行生成的脚本（见 internal/systemd/migrate.go），
+// 本包负责**把它前后包起来**：确保迁移窗口内没有任何写者。
+//
+// ## ★ 失败策略：任何一步失败都要**回滚到能跑的状态**
+//
+// 伪关机失败 ⇒ 立刻唤醒已停的，让内核回到正常态，别卡在半关。
+// 迁移失败 ⇒ 调用方负责回滚数据；本包的 Resume 仍然要执行（否则内核永久冻结）。
+
+import (
+	"fmt"
+	"log"
+	"sync/atomic"
+	"time"
+)
+
+// inflightToolsFn 报告当前在途工具调用数（由装配处注入）。
+//
+// 用函数注入而不用字段直连：kernelboot 不能依赖 agent/core。
+var inflightToolsFn atomic.Value // func() int64
+
+// SetInflightToolCounter 注入在途工具计数（装配处调一次）。
+func SetInflightToolCounter(fn func() int64) {
+	if fn != nil {
+		inflightToolsFn.Store(fn)
+	}
+}
+
+func hasInflightTools() bool {
+	v := inflightToolsFn.Load()
+	if v == nil {
+		return false
+	}
+	fn, _ := v.(func() int64)
+	if fn == nil {
+		return false
+	}
+	return fn() > 0
+}
+
+// PluginQuiescer 是**插件层的伪关机能力**。
+//
+// ★ 这里刻意复用已有的**运行态停启**（Registry.StopPlugin/StartPlugin），
+//
+//	  而不是新造"冻结"机制 —— 三态生命周期（自动启动 / 启用但不自动启动 /
+//	  禁用）早已存在，且运行态停启**不写任何持久状态**（不碰 disabled_plugins，
+//	  也不置 shuttingDown）⇒ 天然可逆，正是伪关机需要的语义。
+//
+//		StopPlugin  ⇒ 停掉子进程 + **摘掉注册面**（工具/stage/通道）
+//		              ⇒ 停完模型看不到、也调不到它们（比"冻结入口"更彻底）
+//		StartPlugin ⇒ 重新拉起，清运行态门
+//
+// ★ 与 StopAll 的区别（用错就是灾难）：StopAll 置 shuttingDown 后
+//
+//	**插件永远无法再加载**，那是进程退出用的，绝不能用于伪关机。
+type PluginQuiescer interface {
+	// StopPluginRuntime 运行态停掉一个插件（不改持久状态）。
+	StopPluginRuntime(name string) error
+	// StartPluginRuntime 运行态拉起一个插件。
+	StartPluginRuntime(name string) error
+	// RunningPlugins 返回当前正在运行的插件名（用于决定停哪些）。
+	RunningPlugins() []string
+}
+
+// MigrateSession 表示一次"伪关机窗口"。用它包住外部迁移动作。
+//
+// ★ 用法必须用 defer 保证唤醒 —— 否则迁移失败时内核永久冻结：
+//
+//	sess, err := ks.BeginMigration(freezer)
+//	if err != nil { return err }
+//	defer sess.End()          // 无论成功失败都唤醒
+//	// ... 外部脚本迁移 ...
+type MigrateSession struct {
+	ks      *KernelState
+	plugins PluginQuiescer
+	paused  []string
+	stopped []string // 已运行态停掉的插件（按停止顺序，唤醒时逆序）
+	ended   atomic.Bool
+}
+
+// BeginMigration 进入伪关机：停插件（运行态）→ 逆序暂停内核写者 → 等在途归零。
+//
+// 返回的 session 必须由调用方 `defer sess.End()`。
+func (s *KernelState) BeginMigration(pq PluginQuiescer) (*MigrateSession, error) {
+	sess := &MigrateSession{ks: s, plugins: pq}
+
+	// ① 先停**插件**（运行态停启，可逆）。
+	//
+	// 为什么插件排第一：插件是最大的写入源（rss 写 feeds、calendar 写 events、
+	// commondev 写 git 镜像）。而且 StopPlugin 会**摘掉注册面** ⇒ 停完
+	// 模型看不到也调不到它们，比"只挡入口"更彻底。
+	//
+	// ★ 为什么不用 StopAll：它会置 shuttingDown，之后插件**永久无法加载**。
+	//   那是进程退出路径用的，用于伪关机等于"关了就起不来"。
+	if pq != nil {
+		running := pq.RunningPlugins()
+		// 逆序停（最后启动的先停，与依赖相反）
+		for i := len(running) - 1; i >= 0; i-- {
+			name := running[i]
+			if err := pq.StopPluginRuntime(name); err != nil {
+				// 停不下来 ⇒ 回滚已停的，别留半关
+				for j := len(sess.stopped) - 1; j >= 0; j-- {
+					if r := pq.StartPluginRuntime(sess.stopped[j]); r != nil {
+						log.Printf("[migrate] 回滚启动插件 %s 失败: %v", sess.stopped[j], r)
+					}
+				}
+				return nil, fmt.Errorf("运行态停止插件 %s 失败（已回滚 %d 个）: %w",
+					name, len(sess.stopped), err)
+			}
+			sess.stopped = append(sess.stopped, name)
+		}
+		log.Printf("[migrate] 已运行态停止 %d 个插件（不改持久状态，唤醒即恢复）", len(sess.stopped))
+	}
+
+	// ② 逆序暂停内核写者（distiller/textmem 等后台定时写）
+	paused, err := s.Quiesce()
+	if err != nil {
+		// 失败 ⇒ 把插件拉回去，内核回到正常态
+		for j := len(sess.stopped) - 1; j >= 0; j-- {
+			if r := pq.StartPluginRuntime(sess.stopped[j]); r != nil {
+				log.Printf("[migrate] 回滚启动插件 %s 失败: %v", sess.stopped[j], r)
+			}
+		}
+		log.Printf("[migrate] 伪关机失败，已回滚: %v", err)
+		return nil, fmt.Errorf("伪关机失败: %w", err)
+	}
+	sess.paused = paused
+
+	// ③ 等在途工具调用归零（尽力而为，见下）
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		if !hasInflightTools() {
+			break
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	if hasInflightTools() {
+		log.Printf("[migrate] warning: 仍有在途工具调用未完成（继续；迁移脚本 stop 服务后天然安全）")
+	}
+
+	log.Printf("[migrate] 伪关机完成（插件 %d 个、内核写者 %d 个）", len(sess.stopped), len(paused))
+	return sess, nil
+}
+
+// End 唤醒：逆序恢复内核写者 → 逆序拉起插件。幂等。
+func (m *MigrateSession) End() {
+	if m == nil || m.ended.Swap(true) {
+		return
+	}
+	// ① 先恢复内核写者（它们是被插件依赖的下层）
+	if err := m.ks.Resume(m.paused); err != nil {
+		log.Printf("[migrate] ★ 唤醒内核写者失败（可能半醒）: %v", err)
+	}
+	// ② 再拉起插件（按**停止的逆序** = 原启动顺序）
+	if m.plugins != nil {
+		for i := len(m.stopped) - 1; i >= 0; i-- {
+			name := m.stopped[i]
+			if err := m.plugins.StartPluginRuntime(name); err != nil {
+				log.Printf("[migrate] ★ 拉起插件 %s 失败: %v", name, err)
+			} else {
+				log.Printf("[migrate] 已拉起插件: %s", name)
+			}
+		}
+	}
+	log.Printf("[migrate] 唤醒完成")
+}
diff --git a/internal/kernelboot/migrate_test.go b/internal/kernelboot/migrate_test.go
new file mode 100644
index 00000000..b0799ae6
--- /dev/null
+++ b/internal/kernelboot/migrate_test.go
@@ -0,0 +1,219 @@
+package kernelboot
+
+// 伪关机 / 唤醒（迁移窗口）的判据（2026-10-17）。
+//
+// ## 背景
+//
+// 用户要求：「迁移模块要先让 core 暂停其他模块运行（伪关机）完成迁移后再唤醒」。
+//
+// 数据目录迁移 21G 要几分钟，期间任何写者（distiller 每 10min 写 graph.db、
+// textmem 滚动写、插件写 plugin_data）都会污染数据。
+//
+// ## 这组判据守什么
+//
+//  1. Quiesce 必须**逆序**暂停（后启动的先停：先停消费者再停生产者）
+//  2. Pause 失败必须**回滚**（不能留半关状态）
+//  3. Resume 必须**逆序**恢复（与暂停相反 = 原启动顺序）
+//  4. End 必须**幂等**（重复调用不重复 Resume）
+//  5. **失败也必须唤醒**（否则内核永久冻结，比不迁移更糟）
+
+import (
+	"errors"
+	"sync"
+	"testing"
+)
+
+func newTestKS() *KernelState { return NewKernelState() }
+
+// ★★★ 判据：Quiesce 逆序暂停、Resume 逆序恢复。
+func TestQuiescePausesInReverseOrder(t *testing.T) {
+	ks := newTestKS()
+	var mu sync.Mutex
+	var pausedOrder, resumedOrder []string
+
+	add := func(name string) {
+		ks.AddQuiescer(name,
+			func() error {
+				mu.Lock()
+				pausedOrder = append(pausedOrder, name)
+				mu.Unlock()
+				return nil
+			},
+			func() error {
+				mu.Lock()
+				resumedOrder = append(resumedOrder, name)
+				mu.Unlock()
+				return nil
+			})
+	}
+	// 模拟启动顺序：a → b → c
+	add("a")
+	add("b")
+	add("c")
+
+	paused, err := ks.Quiesce()
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 暂停必须逆序：c, b, a（先停最后启动的）
+	want := []string{"c", "b", "a"}
+	if len(pausedOrder) != 3 || pausedOrder[0] != "c" || pausedOrder[2] != "a" {
+		t.Fatalf("★ Quiesce 顺序错：实际 %v，应为 %v（后启动的先停，先停消费者）",
+			pausedOrder, want)
+	}
+
+	if err := ks.Resume(paused); err != nil {
+		t.Fatal(err)
+	}
+	// 恢复必须与暂停相反 = 原启动顺序 a, b, c
+	if len(resumedOrder) != 3 || resumedOrder[0] != "a" || resumedOrder[2] != "c" {
+		t.Fatalf("★ Resume 顺序错：实际 %v，应为 [a b c]（与暂停相反 = 启动顺序）", resumedOrder)
+	}
+}
+
+// ★★★ 判据：Pause 失败必须**回滚已暂停的**（不留半关状态）。
+func TestQuiesceRollsBackOnFailure(t *testing.T) {
+	ks := newTestKS()
+	var mu sync.Mutex
+	resumed := map[string]int{}
+
+	ks.AddQuiescer("ok1", func() error { return nil }, func() error {
+		mu.Lock()
+		resumed["ok1"]++
+		mu.Unlock()
+		return nil
+	})
+	ks.AddQuiescer("boom", func() error { return errors.New("停不下来") }, func() error {
+		mu.Lock()
+		resumed["boom"]++
+		mu.Unlock()
+		return nil
+	})
+
+	// 逆序：boom 先被暂停 ⇒ 它失败 ⇒ ok1 还没被暂停（因为逆序时 ok1 在 boom 之后）
+	// 为了真正测到"回滚"，让失败发生在**后面的**那个
+	ks2 := newTestKS()
+	ks2.AddQuiescer("boom", func() error { return errors.New("停不下来") }, nil)
+	ks2.AddQuiescer("ok1", func() error { return nil }, func() error {
+		mu.Lock()
+		resumed["ok1"]++
+		mu.Unlock()
+		return nil
+	})
+	// 逆序暂停：ok1 先（成功）→ boom（失败）⇒ 应回滚 ok1
+	if _, err := ks2.Quiesce(); err == nil {
+		t.Fatal("Pause 失败时 Quiesce 必须返回错误（不能假装成功）")
+	}
+	if resumed["ok1"] == 0 {
+		t.Fatal("★ Pause 失败后未回滚已暂停的 ok1 ⇒ 内核处于**半关**状态")
+	}
+}
+
+// ★★★ 判据：End 幂等（重复调用不重复 Resume）。
+func TestMigrateSessionEndIsIdempotent(t *testing.T) {
+	ks := newTestKS()
+	var mu sync.Mutex
+	n := 0
+	ks.AddQuiescer("w", func() error { return nil }, func() error {
+		mu.Lock()
+		n++
+		mu.Unlock()
+		return nil
+	})
+
+	sess, err := ks.BeginMigration(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sess.End()
+	sess.End()
+	sess.End()
+
+	mu.Lock()
+	defer mu.Unlock()
+	if n != 1 {
+		t.Fatalf("★ End 不幂等：Resume 被调用 %d 次（应为 1）", n)
+	}
+}
+
+// fakePlugins 模拟插件层的运行态停启（**可逆**，与 StopAll 相反）。
+type fakePlugins struct {
+	mu      sync.Mutex
+	running []string
+	stops   int
+	starts  int
+	failOn  string // 停这个插件时失败
+}
+
+func (f *fakePlugins) StopPluginRuntime(name string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if name == f.failOn {
+		return errors.New("停不下来")
+	}
+	f.stops++
+	for i, n := range f.running {
+		if n == name {
+			f.running = append(f.running[:i], f.running[i+1:]...)
+			break
+		}
+	}
+	return nil
+}
+
+func (f *fakePlugins) StartPluginRuntime(name string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.starts++
+	f.running = append(f.running, name)
+	return nil
+}
+
+func (f *fakePlugins) RunningPlugins() []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	out := make([]string, len(f.running))
+	copy(out, f.running)
+	return out
+}
+
+// ★★★ 判据：伪关机停掉全部插件，唤醒后**全部恢复**（可逆）。
+//
+// 这是"用运行态停启而不是 StopAll"的核心保证：
+// StopAll 置 shuttingDown 之后插件**永久起不来**，用于伪关机就是关了就死。
+func TestMigrationStopsAndRestoresAllPlugins(t *testing.T) {
+	ks := newTestKS()
+	fp := &fakePlugins{running: []string{"webui", "rss", "calendar", "commondev"}}
+
+	sess, err := ks.BeginMigration(fp)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := fp.RunningPlugins(); len(got) != 0 {
+		t.Fatalf("★ 伪关机后仍有插件在运行: %v（迁移期间会写数据）", got)
+	}
+	if fp.stops != 4 {
+		t.Fatalf("应停 4 个插件，实际 %d", fp.stops)
+	}
+
+	sess.End()
+	if got := fp.RunningPlugins(); len(got) != 4 {
+		t.Fatalf("★ 唤醒后插件未全部恢复: %v（应 4 个）—— 这正是用 StopAll 会造成的后果", got)
+	}
+}
+
+// ★★★ 判据：停插件失败必须**回滚已停的**（不留半关）。
+func TestMigrationRollsBackPluginsOnFailure(t *testing.T) {
+	ks := newTestKS()
+	// 逆序停：commondev → calendar → rss → webui
+	// 让 calendar 失败 ⇒ 已停的 commondev 必须被拉回
+	fp := &fakePlugins{running: []string{"webui", "rss", "calendar", "commondev"}, failOn: "calendar"}
+
+	if _, err := ks.BeginMigration(fp); err == nil {
+		t.Fatal("停插件失败时 BeginMigration 必须返回错误")
+	}
+	got := fp.RunningPlugins()
+	if len(got) != 4 {
+		t.Fatalf("★ 回滚不完整：只剩 %v（应全部 4 个）—— 内核处于半关状态", got)
+	}
+}
diff --git a/internal/kernelboot/modules/registry.go b/internal/kernelboot/modules/registry.go
new file mode 100644
index 00000000..405085f2
--- /dev/null
+++ b/internal/kernelboot/modules/registry.go
@@ -0,0 +1,94 @@
+// Package modules 是内核模块的**登记表**（不含任何具体模块的实现）。
+//
+// ## 设计意图（用户设计）
+//
+// > 每个内核模块显式各自声明依赖 … 最先初始化的 core 自然不依赖任何模块，
+// > 下一步初始化的依赖 core 以此类推
+//
+// ## 怎么加一个新模块（这是本设计的**验收标准**）
+//
+//	① 新建一个文件（如 modules/mymod.go）
+//	② 写一个类型，实现 kernelboot.Module（Name/Requires/Provides/Init）
+//	③ 在同文件的 init() 里调 modules.Register(&MyMod{})
+//	④ 在 modules/imports.go 加一行 `_ "...modules"` —— **仅此而已**
+//
+// **不需要**编辑任何中央清单：依赖写在模块**自己**的 Requires() 里。
+//
+// ★ 为何要"防漏 import"的判据（见 registry_test.go）：
+// 忘了 import ⇒ 模块**根本不登记** ⇒ 它不参与装配 ⇒ 依赖它的模块报
+// "缺依赖"（响亮），但**不依赖它的模块会静默少了那个设施**
+// （如插件注册表没建 ⇒ 插件全部加载不了，而错误信息指向插件而非根因）。
+// ⇒ 判据必须自动扫描目录，要求每个模块文件都被 import。
+package modules
+
+import (
+	"fmt"
+	"sort"
+	"sync"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+)
+
+var (
+	regMu    sync.Mutex
+	registry []kernelboot.Module
+	seenName = map[string]bool{}
+)
+
+// Register 由模块在自己的 init() 里调用（自注册）。
+//
+// 重复注册同一模块名会**记录**并在 BuildModules 时报错 —— 不用 panic：
+// panic 发生在 init 阶段，栈信息对使用者毫无意义（他只想知道哪个模块重名）。
+func Register(m kernelboot.Module) {
+	if m == nil {
+		return
+	}
+	regMu.Lock()
+	defer regMu.Unlock()
+	if seenName[m.Name()] {
+		dupErr = append(dupErr, m.Name())
+		return
+	}
+	seenName[m.Name()] = true
+	registry = append(registry, m)
+}
+
+// dupErr 累积重名模块（BuildModules 时统一报告）。
+var dupErr []string
+
+// BuildModules 返回全部已登记模块（按名字排序，保证可复现）。
+//
+// ## 为什么排序
+//
+// 分层结果的**层内顺序**若依赖 map/切片顺序，同一份声明两次构建会得到
+// 不同顺序 ⇒ 不可审计（设计 §2.5：图要能进 PR diff 比对）。
+// 排序让结果稳定。
+func BuildModules() ([]kernelboot.Module, error) {
+	regMu.Lock()
+	defer regMu.Unlock()
+	if len(dupErr) > 0 {
+		names := append([]string(nil), dupErr...)
+		sort.Strings(names)
+		return nil, fmt.Errorf("kernelboot/modules: 模块名重复注册: %v"+
+			"（同一个模块被 import 了两次？或两个模块取了同名）", names)
+	}
+	out := append([]kernelboot.Module(nil), registry...)
+	sort.Slice(out, func(i, j int) bool { return out[i].Name() < out[j].Name() })
+	if len(out) == 0 {
+		return nil, fmt.Errorf("kernelboot/modules: 没有任何模块被登记 —— " +
+			"通常是没有 import 模块包（见本文件顶部的'怎么加一个新模块'）")
+	}
+	return out, nil
+}
+
+// Names 返回已登记模块名（诊断/判据用）。
+func Names() []string {
+	regMu.Lock()
+	defer regMu.Unlock()
+	out := make([]string, 0, len(registry))
+	for _, m := range registry {
+		out = append(out, m.Name())
+	}
+	sort.Strings(out)
+	return out
+}
diff --git a/internal/kernelboot/plaingraph_test.go b/internal/kernelboot/plaingraph_test.go
new file mode 100644
index 00000000..50cdf97b
--- /dev/null
+++ b/internal/kernelboot/plaingraph_test.go
@@ -0,0 +1,167 @@
+package kernelboot
+
+// 编译期图 → 运行期启动计划的判据（设计 §2.5，用户要求：
+// "启动顺序是编译期间按照声明的依赖顺序生成的启动依赖图排列的"）。
+//
+// ## 这组判据守什么
+//
+//  ① 运行期**读**图里的顺序，不重算（层号被真正使用）
+//  ② 图与声明**漂移**时拒绝启动（§2.5.2 的病 A）
+//  ③ 图与二进制**描述不同模块集**时拒绝启动
+//  ④ 自校验能抓损坏（已有判据，这里补"层号参与校验"）
+
+import (
+	"strings"
+	"testing"
+)
+
+// 造一个可分层的小世界。
+func planTestModules() []Module {
+	return []Module{
+		&fakeModule{name: "config", provides: []string{"config"}},
+		&fakeModule{name: "lua", provides: []string{"lua"}, requires: []string{"config"}},
+		&fakeModule{name: "llm", provides: []string{"llm"}, requires: []string{"config", "lua"}},
+	}
+}
+
+// ★★★ 判据：**PlanFromGraph 按图中的层号排计划**（而不是重算）。
+func TestPlanFromGraphUsesEmbeddedLayers(t *testing.T) {
+	mods := planTestModules()
+	built, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	edges := planToEdgesForTest(built)
+	gf := decodeGraphOrFatal(t, EncodeGraph(edges))
+
+	plan, err := PlanFromGraph(gf, mods)
+	if err != nil {
+		t.Fatalf("PlanFromGraph: %v", err)
+	}
+	if len(plan.Layers) != len(built.Layers) {
+		t.Fatalf("层数不符: %d != %d", len(plan.Layers), len(built.Layers))
+	}
+	for i := range built.Layers {
+		got := names(plan.Layers[i])
+		want := names(built.Layers[i])
+		if !equalStrs(got, want) {
+			t.Errorf("第 %d 层不符: %v != %v", i, got, want)
+		}
+	}
+}
+
+// ★★★ 判据：**层号真的被使用**（有人重算而不读图 ⇒ 报红）。
+//
+// 做法：手工把图里 lua 的层号改成 0（与声明矛盾）。
+// 若 PlanFromGraph 重算而不读，它会"照常工作"；读了图并校验 ⇒ 报漂移。
+func TestPlanFromGraphDetectsLayerDrift(t *testing.T) {
+	mods := planTestModules()
+	built, _ := Build(mods)
+	edges := planToEdgesForTest(built)
+
+	// 篡改：把 lua 标成第 0 层（它实际在第 1 层）
+	for i := range edges {
+		if edges[i].Name == "lua" {
+			edges[i].Layer = 0
+		}
+	}
+	gf := decodeGraphOrFatal(t, EncodeGraph(edges))
+
+	_, err := PlanFromGraph(gf, mods)
+	if err == nil {
+		t.Fatal("★ 图里的层号与声明矛盾，却照常构造了计划 —— " +
+			"运行期必须用图里的顺序，并校验它与声明一致（否则旧图会给出错误顺序）")
+	}
+	if !strings.Contains(err.Error(), "漂移") {
+		t.Errorf("错误应点明是\"漂移\"（改了声明没重出图）: %v", err)
+	}
+}
+
+// ★★★ 判据：**图与二进制模块集不一致时拒绝启动**。
+func TestPlanFromGraphDetectsModuleSetMismatch(t *testing.T) {
+	mods := planTestModules()
+	built, _ := Build(mods)
+	edges := planToEdgesForTest(built)
+
+	// ① 二进制里少了一个模块（模拟"图是新的、二进制是旧的"）
+	gf := decodeGraphOrFatal(t, EncodeGraph(edges))
+	if _, err := PlanFromGraph(gf, mods[:2]); err == nil {
+		t.Fatal("★ 图描述了二进制里没有的模块，却通过了 —— 会把旧芯片的图配新二进制")
+	}
+
+	// ② 图里少了一个模块
+	short := make([]Module, 0, 2)
+	short = append(short, mods[0], mods[1])
+	shortBuilt, _ := Build(short)
+	gf2 := decodeGraphOrFatal(t, EncodeGraph(planToEdgesForTest(shortBuilt)))
+	if _, err := PlanFromGraph(gf2, mods); err == nil {
+		t.Fatal("★ 二进制里有图里没有的模块，却通过了")
+	}
+}
+
+// ★★★ 判据：**层号进了二进制**（编解码往返保真）。
+func TestGraphRoundTripsLayer(t *testing.T) {
+	mods := planTestModules()
+	built, _ := Build(mods)
+	edges := planToEdgesForTest(built)
+	gf := decodeGraphOrFatal(t, EncodeGraph(edges))
+
+	byName := map[string]int{}
+	for _, e := range gf.Modules {
+		byName[e.Name] = e.Layer
+	}
+	for _, m := range mods {
+		_ = m
+	}
+	if byName["config"] != 0 || byName["lua"] != 1 || byName["llm"] != 2 {
+		t.Fatalf("层号未正确往返: %v", byName)
+	}
+}
+
+// ★★★ 判据：**编码顺序 = 启动顺序**（按 (layer,name)，层内可复现）。
+func TestGraphEncodeOrderIsStartupOrder(t *testing.T) {
+	mods := planTestModules()
+	built, _ := Build(mods)
+	gf := decodeGraphOrFatal(t, EncodeGraph(planToEdgesForTest(built)))
+
+	var order []string
+	for _, e := range gf.Modules {
+		order = append(order, e.Name)
+	}
+	// config 必须在 lua 之前，lua 必须在 llm 之前（按层号排好的顺序）
+	idx := func(n string) int {
+		for i, s := range order {
+			if s == n {
+				return i
+			}
+		}
+		return -1
+	}
+	if !(idx("config") < idx("lua") && idx("lua") < idx("llm")) {
+		t.Fatalf("★ 解码后的顺序不是启动顺序: %v", order)
+	}
+}
+
+// ---- 测试辅助 ----
+
+func planToEdgesForTest(p *Plan) []GraphEdge {
+	var out []GraphEdge
+	for layer, mods := range p.Layers {
+		for _, m := range mods {
+			out = append(out, GraphEdge{
+				Name: m.Name(), Provides: m.Provides(),
+				Requires: m.Requires(), Layer: layer,
+			})
+		}
+	}
+	return out
+}
+
+func decodeGraphOrFatal(t *testing.T, data []byte) *GraphFile {
+	t.Helper()
+	gf, err := DecodeGraph(data)
+	if err != nil {
+		t.Fatalf("DecodeGraph: %v", err)
+	}
+	return gf
+}
diff --git a/internal/kernelboot/scheduler.go b/internal/kernelboot/scheduler.go
new file mode 100644
index 00000000..96d376aa
--- /dev/null
+++ b/internal/kernelboot/scheduler.go
@@ -0,0 +1,309 @@
+package kernelboot
+
+// 插件调度器：按 syncbus 状态决定**何时**拉起各插件（设计 §2.6.4）。
+//
+// ## 核心规则（三条，按优先级）
+//
+//	未声明依赖              ⇒ 等内核**完全**初始化（默认路径 = 现行为，§2.6.5）
+//	声明了依赖且全就绪       ⇒ **立即**拉起
+//	声明了依赖但未全就绪     ⇒ 挂起，等 syncbus 更新后再判断
+//
+// ## ★ 兼容性的落点就在第一条
+//
+// 存量 42 个插件都不声明依赖 ⇒ 全部走第一条 ⇒ 行为**逐字不变**。
+// 这不是"顺便兼容"，而是本设计的硬约束：42 个插件里任何一个若因本设计
+// 改变了启动时机，就可能在不该动的时候动（例如假设"Start 时 llm 已就绪"）。
+// **静默改变启动时机 = 静默引入竞态。**
+//
+// ## 为什么"未声明"不能等价于"依赖集为空"
+//
+// 空依赖集在数学上"已满足"，若按此处理，未声明的插件会在**第一层完成后**
+// 就被拉起 —— 比现状早得多，直接破坏兼容性。
+// 所以"未声明"与"声明了空集"是**不同**语义，必须分开判断（见 Wants）。
+//
+// ## 为什么调度器不自带并发控制
+//
+// 拉起插件的实际动作（load/Start）由插件管理器做 —— 那里已有
+// Registry 的锁与生命周期管理。本调度器只负责**判断时机**，
+// 保持单一职责，也让判断逻辑可以脱离真实插件系统被单测（判据的关键）。
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+)
+
+// PluginSpec 是调度器需要知道的插件声明（设计 §2.6.4/2.6.6）。
+type PluginSpec struct {
+	Name string
+
+	// RequiresFacilities 是插件声明需要的设施名。
+	//
+	// nil/空 ⇒ **未声明**（走"等内核完全初始化"路径）
+	// 非空   ⇒ 声明的依赖；全就绪即拉起
+	RequiresFacilities []string
+
+	// AutoStart 为 false 表示"不伴随启动"：即使依赖齐了也**不**自动拉起，
+	// 等 agent 经 plugin_enable 显式启用（设计 §2.6.6）。
+	//
+	// 用指针语义的注意：这里用 bool + 一个显式标记区分"未声明"与"false"。
+	// 但为了简洁，约定：**缺省（未声明）= true**（伴随启动，与现状一致），
+	// 由 manifest 层负责把"未声明"翻译成 true。
+	AutoStart bool
+}
+
+// Scheduler 按 syncbus 状态调度插件。
+type Scheduler struct {
+	mu       sync.Mutex
+	bus      SyncState
+	pending  []PluginSpec
+	launched map[string]bool
+	launch   func(PluginSpec) error
+
+	// onLaunchErr 记录拉起失败（不中断其他插件）
+	onLaunchErr func(PluginSpec, error)
+}
+
+// NewScheduler 创建调度器。launch 是实际拉起动作（由插件管理器提供）。
+//
+// ★ bus 参数类型是 **SyncState**（只读接口），不是 *SyncBus。
+// 这就是设计 §2.6.3 的权限隔离：调度器**在编译期就没有**写 syncbus 的能力。
+func NewScheduler(bus SyncState, launch func(PluginSpec) error) *Scheduler {
+	s := &Scheduler{
+		bus:      bus,
+		launch:   launch,
+		launched: map[string]bool{},
+	}
+	// ★ 订阅状态变化：syncbus 每次更新（层边界 / 内核完成）就重新评估挂起队列。
+	//
+	// 这是"自动拉起"的实现方式：调度器不需要轮询（空转）也不需要调用方
+	// 记得在每处手动触发（漏了就会静默卡住）。订阅一次，永久生效。
+	//
+	// 若 bus 不支持订阅（只传了个只读快照实现），退化为"只在 Submit 时评估"——
+	// 那种情况下调度器仍可用，只是不会自动跟进后续状态变化。
+	if sub, ok := bus.(interface{ OnUpdate(func(SyncState)) }); ok {
+		sub.OnUpdate(func(SyncState) { s.evaluate() })
+	}
+	return s
+}
+
+// SetLaunch 补上拉起动作（供"两段式"调度：装配前订阅、装配后接动作）。
+//
+// ## 为什么需要它（真实缺口）
+//
+// 插件调度器必须在**装配开始前**订阅 syncbus，否则"声明提前启动"不会生效
+// （提交时全部设施早已就绪 ⇒ 永远退化成"立即拉起"）。
+//
+// 但**拉起动作**依赖插件注册表，而那是 stage-host 模块的产物
+// ⇒ 装配前拿不到。所以分两段：
+//
+//	· 装配前：NewScheduler(bus, nil) 只订阅
+//	· 装配后：SetLaunch(fn) 接上真实动作
+//
+// ★ 此时可能已有插件被标记 launched（分层过程中达到条件）。
+// 调用方需自行补偿"已标记但未真正加载"的那些 —— 见 LaunchedFlag。
+func (s *Scheduler) SetLaunch(fn func(PluginSpec) error) {
+	s.mu.Lock()
+	s.launch = fn
+	s.mu.Unlock()
+	// ★ 立刻重新评估一次：接上动作之前可能已有插件达到条件并被标记
+	// （它们在 syncbus 更新时就评估过，但那时 launch==nil ⇒ 只标记未执行）。
+	// 不补这一下，它们要等到**下一次** syncbus 更新才会被真正拉起 ——
+	// 而若内核装配已结束（不再有更新），就永远不拉。
+	s.evaluate()
+}
+
+// LaunchedFlag 报告某插件是否已被标记为"可拉起/已拉起"。
+//
+// ★ 与 Launched()（返回列表）分开：本方法用于**单个查询**，
+// 供两段式调度的补偿逻辑判断"它到条件了但可能还没真正加载"。
+func (s *Scheduler) LaunchedFlag(name string) bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.launched[name]
+}
+
+// SetLaunchErrorHandler 注册拉起失败的观察者（诊断用）。
+func (s *Scheduler) SetLaunchErrorHandler(fn func(PluginSpec, error)) {
+	s.mu.Lock()
+	s.onLaunchErr = fn
+	s.mu.Unlock()
+}
+
+// Submit 提交一批插件声明。返回**立即可拉起**的那些插件名。
+//
+// 未达条件的进挂起队列，等 OnUpdate 触发时再评估。
+func (s *Scheduler) Submit(specs []PluginSpec) []string {
+	// ★ 先校验：声明的设施名必须是**内核注册过的**。
+	//
+	// ## 为什么这条校验必须存在（修一个"静默永不启动"的缺口）
+	//
+	// 插件声明 `requires_facilities` 是字符串。拼错时原行为是：
+	// 永远等不到 ⇒ **永不拉起**，且**无任何报错**、无超时兜底。
+	// 那是本仓反复吃亏的"静默降级"形态（系统看着正常，某插件就是不工作）。
+	//
+	// 有了这条校验，拼错在**提交那一刻**就报出来，并列出全部已知设施名
+	// 供对照（"拼错了"当场可修）。
+	//
+	// ★ 为什么在这里而不在 canLaunch：canLaunch 是**每轮状态变化**都会调的
+	// 热路径，在那里报错会重复刷屏；而"名字不存在"是**一次性**的静态错误，
+	// 提交时检查一次即可。
+	s.mu.Lock()
+	var rejected []PluginSpec
+	var valid []PluginSpec
+	for _, p := range specs {
+		if bad := s.unknownFacilities(p); len(bad) > 0 {
+			rejected = append(rejected, p)
+			continue
+		}
+		valid = append(valid, p)
+	}
+	s.pending = append(s.pending, valid...)
+	errFn := s.onLaunchErr
+	s.mu.Unlock()
+
+	// 报错在锁外（回调可能反查调度器状态 ⇒ 持锁会死锁）
+	for _, p := range rejected {
+		bad := s.unknownFacilities(p)
+		err := fmt.Errorf("插件 %s 声明的设施名内核**从未注册过**: %v —— "+
+			"这通常是拼写错误。内核已知的设施名: %v。"+
+			"（若不校验，该插件会**永远等不到就绪**而静默不启动）",
+			p.Name, bad, s.bus.KnownFacilities())
+		if errFn != nil {
+			errFn(p, err)
+		}
+	}
+	return s.evaluate()
+}
+
+// unknownFacilities 返回插件声明里**内核从未注册过**的设施名（拼错检测）。
+func (s *Scheduler) unknownFacilities(p PluginSpec) []string {
+	var bad []string
+	for _, f := range p.RequiresFacilities {
+		if !s.bus.Known(f) {
+			bad = append(bad, f)
+		}
+	}
+	sort.Strings(bad)
+	return bad
+}
+
+// Pending 返回仍在挂起的插件名（诊断/判据用）。
+func (s *Scheduler) Pending() []string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	out := make([]string, 0, len(s.pending))
+	for _, p := range s.pending {
+		out = append(out, p.Name)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// Launched 返回已拉起的插件名（判据用）。
+func (s *Scheduler) Launched() []string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	out := make([]string, 0, len(s.launched))
+	for k := range s.launched {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// evaluate 挑出当前可拉起的插件并拉起它们。
+//
+// 返回本次真正拉起的插件名。
+func (s *Scheduler) evaluate() []string {
+	s.mu.Lock()
+	// 挑出可拉起的 + 留下的。
+	//
+	// ★★ 必须**就地去重**：pending 里可能有同一插件的多份副本，
+	// 因为并发 Submit 各自把同一批插件追加进来。
+	//
+	// 实测（压力测试 TestStressSchedulerConcurrentStateChange）：
+	// 8 个 goroutine 并发提交 200 个插件 + 内核并发标记就绪
+	// ⇒ 同一插件在**同一次** evaluate 的 ready 列表里出现多次
+	// ⇒ `launched` 查重救不了（它只在**跨轮**生效）⇒ 被拉起 203 次。
+	//
+	// 后果：插件被重复加载（spawn 两个进程 / 工具注册冲突）。
+	//
+	// 去重用 seen 集合（同一次 evaluate 内），并把它记进 launched
+	// 以确保跨轮也幂等 —— 两者都需要。
+	var ready []PluginSpec
+	var still []PluginSpec
+	seen := map[string]bool{}
+	for _, p := range s.pending {
+		if s.launched[p.Name] || seen[p.Name] {
+			continue // 已拉起（跨轮）或本批已选中（同批）⇒ 丢弃
+		}
+		if s.canLaunch(p) {
+			seen[p.Name] = true
+			ready = append(ready, p)
+		} else {
+			still = append(still, p)
+		}
+	}
+	s.pending = still
+	for _, p := range ready {
+		s.launched[p.Name] = true
+	}
+	launchFn := s.launch
+	errFn := s.onLaunchErr
+	s.mu.Unlock()
+
+	// ★ 在**不持锁**的情况下执行拉起动作：
+	//   拉起可能很慢（spawn 进程、握手），持锁会让其他插件全卡住；
+	//   且拉起过程可能回调调度器（如插件注册新插件）⇒ 死锁。
+	var names []string
+	for _, p := range ready {
+		names = append(names, p.Name)
+		if launchFn == nil {
+			continue
+		}
+		if err := launchFn(p); err != nil && errFn != nil {
+			errFn(p, err)
+		}
+	}
+	sort.Strings(names)
+	return names
+}
+
+// canLaunch 判断单个插件当前是否可拉起。
+func (s *Scheduler) canLaunch(p PluginSpec) bool {
+	// ① 不伴随启动：依赖齐了也**不**自动拉起（§2.6.6）
+	if !p.AutoStart {
+		return false
+	}
+	// ② 未声明依赖 ⇒ 等内核**完全**初始化（§2.6.5，存量插件走这条）
+	if len(p.RequiresFacilities) == 0 {
+		return s.bus.KernelComplete()
+	}
+	// ③ 声明了依赖 ⇒ 全就绪即拉起
+	return s.bus.AllReady(p.RequiresFacilities)
+}
+
+// WaitString 渲染"还差什么"（供日志：让等待可解释，而不是静默卡住）。
+func (s *Scheduler) WaitString(p PluginSpec) string {
+	if !p.AutoStart {
+		return "不伴随启动（等显式启用）"
+	}
+	if len(p.RequiresFacilities) == 0 {
+		return "等内核完全初始化"
+	}
+	// AllReady 需要 *SyncBus；这里只做只读渲染，用 Snapshot 判断
+	snap := s.bus.Snapshot()
+	var missing []string
+	for _, f := range p.RequiresFacilities {
+		if !snap[f] {
+			missing = append(missing, f)
+		}
+	}
+	if len(missing) == 0 {
+		return "依赖已就绪"
+	}
+	sort.Strings(missing)
+	return fmt.Sprintf("还差: %s", strings.Join(missing, ","))
+}
diff --git a/internal/kernelboot/stress_test.go b/internal/kernelboot/stress_test.go
new file mode 100644
index 00000000..97747144
--- /dev/null
+++ b/internal/kernelboot/stress_test.go
@@ -0,0 +1,319 @@
+package kernelboot
+
+// 内核装配层（syncbus / scheduler / KernelState）的**压力测试**。
+//
+// ## 为什么必须有压力测试（不是"跑一遍判据就够了"）
+//
+// 这层代码的并发行为**只有压力才能暴露**：
+//   · 判据用 2~3 个 goroutine 验证语义正确性
+//   · 压力用数百 goroutine × 数千轮验证**没有数据竞争 / 死锁 / 状态丢失**
+//
+// 本仓已有两处真实教训支持这个判断：
+//   ① ModuleView 第一版把「当前模块」放在共享对象上 ⇒ 判据**偶发**失败
+//      （3 次里 1 次）—— 那是"偶发"而不是"必现"，正是压力测试的领域
+//   ② syncbus 的 OnUpdate 若持锁回调 ⇒ **死锁**（只在回调读状态时触发）
+//
+// ## 压什么（本层真实的并发面）
+//
+//   · SyncBus：内核写（MarkDeclared/MarkLayerReady/MarkKernelComplete）
+//     与插件读（Known/IsReady/Snapshot/AllReady/**订阅回调**）并发
+//   · Scheduler：多 goroutine 并发 Submit（同一插件可能被重复提交）
+//     + 状态变化并发触发 evaluate
+//   · KernelState：同层模块**并行**写**各自**字段（不同字段，无竞争）
+//   · PlanFromGraph：并发读图（只读，但验证无共享可变状态）
+//   · Run：真实分层执行，验证有界并发真的没超
+
+import (
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// ★★★ 压力：**SyncBus 读写并发**（内核写 + N 个插件读 + 订阅回调）。
+//
+// 用 -race 跑时，任何未保护的状态都会报数据竞争。
+func TestStressSyncBusConcurrentReadWrite(t *testing.T) {
+	bus := NewSyncBus()
+	const readers = 64
+	const facilities = 200
+
+	var callbacks int64
+	// 订阅者**读状态**（这正是死锁的触发条件：若 fire 持锁调用回调，
+	// 回调里 Snapshot() 会等读锁 ⇒ 死锁。压力下必现）
+	for i := 0; i < 8; i++ {
+		bus.OnUpdate(func(s SyncState) {
+			_ = s.Snapshot()
+			_ = s.AllReady([]string{"llm"})
+			atomic.AddInt64(&callbacks, 1)
+		})
+	}
+
+	var wg sync.WaitGroup
+	stop := make(chan struct{})
+
+	// 读侧：N 个"插件"持续查询
+	for i := 0; i < readers; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			for {
+				select {
+				case <-stop:
+					return
+				default:
+				}
+				f := fmt.Sprintf("fac%d", i%facilities)
+				_ = bus.Known(f)
+				_ = bus.IsReady(f)
+				_ = bus.Snapshot()
+				_ = bus.ReadyInOrder()
+				_ = bus.KernelComplete()
+				_ = bus.AllReady([]string{"fac1", "fac2"})
+			}
+		}(i)
+	}
+
+	// 写侧：内核持续标记
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for i := 0; i < facilities; i++ {
+			bus.MarkLayerReady([]string{fmt.Sprintf("fac%d", i)})
+		}
+	}()
+
+	// 让它跑一会儿
+	time.Sleep(400 * time.Millisecond)
+	bus.MarkKernelComplete()
+	time.Sleep(100 * time.Millisecond)
+	close(stop)
+	wg.Wait()
+
+	if atomic.LoadInt64(&callbacks) == 0 {
+		t.Fatal("订阅回调从未被调用 —— 压力没有真正覆盖通知路径")
+	}
+	if !bus.KernelComplete() {
+		t.Fatal("KernelComplete 应已置位")
+	}
+	t.Logf("回调触发 %d 次，%d 个并发读者", atomic.LoadInt64(&callbacks), readers)
+}
+
+// ★★★ 压力：**多 goroutine 并发 Submit**（同一插件可能被重复提交）。
+//
+// 真实场景：插件加载器可能分批提交（发现新插件、重扫目录），
+// 而每次提交都会触发状态评估。并发下要保证：
+//
+//	· 不重复拉起同一插件（幂等）
+//	· 不丢插件（全部最终被拉起）
+//	· 无数据竞争
+func TestStressSchedulerConcurrentSubmit(t *testing.T) {
+	bus := NewSyncBus()
+	bus.MarkDeclared([]string{"config", "llm", "memory"})
+	// ★ 必须 MarkLayerReady：MarkDeclared 只登记"名字存在"，
+	// 不代表就绪。插件要求 config **就绪**才拉起。
+	// （我第一版漏了这步 ⇒ 压力判据报"0 个拉起" —— 那是判据 bug，非缺陷。）
+	bus.MarkLayerReady([]string{"config", "llm", "memory"})
+
+	const plugins = 300
+	var mu sync.Mutex
+	launched := map[string]int{}
+
+	sch := NewScheduler(bus, func(p PluginSpec) error {
+		mu.Lock()
+		launched[p.Name]++
+		mu.Unlock()
+		return nil
+	})
+	sch.SetLaunchErrorHandler(func(p PluginSpec, err error) {
+		t.Errorf("不应有拉起错误: %v", err)
+	})
+
+	// 16 个 goroutine 并发提交同一批插件（模拟重复扫描）
+	var wg sync.WaitGroup
+	for g := 0; g < 16; g++ {
+		wg.Add(1)
+		go func(g int) {
+			defer wg.Done()
+			var specs []PluginSpec
+			for i := 0; i < plugins; i++ {
+				specs = append(specs, PluginSpec{
+					Name:               fmt.Sprintf("p%03d", i),
+					RequiresFacilities: []string{"config"},
+					AutoStart:          true,
+				})
+			}
+			sch.Submit(specs)
+		}(g)
+	}
+	bus.MarkKernelComplete()
+	wg.Wait()
+
+	mu.Lock()
+	defer mu.Unlock()
+	if len(launched) != plugins {
+		t.Fatalf("★ 应拉起 %d 个插件，实际 %d（并发提交丢了插件）", plugins, len(launched))
+	}
+	for name, n := range launched {
+		if n != 1 {
+			t.Fatalf("★ 插件 %s 被拉起 %d 次（应恰好 1 次 —— 并发下幂等性破坏）", name, n)
+		}
+	}
+}
+
+// ★★★ 压力：**状态变化 + 提交并发**（真实时序：内核在标记就绪的同时插件在提交）。
+func TestStressSchedulerConcurrentStateChange(t *testing.T) {
+	bus := NewSyncBus()
+	bus.MarkDeclared([]string{"config", "llm", "memory", "stagehost"})
+
+	var launched int64
+	sch := NewScheduler(bus, func(p PluginSpec) error {
+		atomic.AddInt64(&launched, 1)
+		return nil
+	})
+	sch.SetLaunchErrorHandler(func(p PluginSpec, err error) {})
+
+	const plugins = 200
+	var wg sync.WaitGroup
+
+	// 写侧：内核逐层标记就绪
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for _, f := range []string{"config", "llm", "memory", "stagehost"} {
+			bus.MarkLayerReady([]string{f})
+		}
+		bus.MarkKernelComplete()
+	}()
+
+	// 提交侧：8 个并发提交者
+	for g := 0; g < 8; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; i < plugins; i++ {
+				sch.Submit([]PluginSpec{{
+					Name:               fmt.Sprintf("q%03d", i),
+					RequiresFacilities: []string{"config"},
+					AutoStart:          true,
+				}})
+			}
+		}()
+	}
+	wg.Wait()
+	bus.MarkKernelComplete() // 再触发一次评估，确保挂起的也被拉起
+
+	if n := atomic.LoadInt64(&launched); n != plugins {
+		t.Fatalf("★ 并发 提交×状态变化 下应拉起 %d 个，实际 %d", plugins, n)
+	}
+}
+
+// ★★★ 压力：**PlanFromGraph 并发读**（多插件/多协程同时读启动计划）。
+func TestStressPlanFromGraphConcurrentRead(t *testing.T) {
+	mods := planTestModules()
+	built, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	gf := decodeGraphOrFatal(t, EncodeGraph(planToEdgesForTest(built)))
+
+	var wg sync.WaitGroup
+	errs := make(chan error, 64)
+	for i := 0; i < 64; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for j := 0; j < 50; j++ {
+				plan, err := PlanFromGraph(gf, mods)
+				if err != nil {
+					errs <- err
+					return
+				}
+				if len(plan.Layers) != 3 {
+					errs <- fmt.Errorf("层数不对: %d", len(plan.Layers))
+					return
+				}
+			}
+		}()
+	}
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		t.Fatal(err)
+	}
+}
+
+// ★★★ 压力：**Run 的并发上限真的生效**（大量模块同层时不得超出）。
+//
+// ★ 这条与判据的 TestRunRespectsMaxParallel 不同：那条 8 个模块，
+// 这条 **128 个模块**同层 —— 验证信号量在高压下不漏（观察峰值）。
+func TestStressRunRespectsMaxParallelAtScale(t *testing.T) {
+	const n = 128
+	const maxP = 8
+
+	var active, peak int64
+	var mu sync.Mutex
+	var mods []Module
+	for i := 0; i < n; i++ {
+		mods = append(mods, &fakeModule{
+			name:     fmt.Sprintf("m%03d", i),
+			provides: []string{fmt.Sprintf("f%03d", i)},
+			onInit: func() {
+				cur := atomic.AddInt64(&active, 1)
+				mu.Lock()
+				if cur > peak {
+					peak = cur
+				}
+				mu.Unlock()
+				time.Sleep(2 * time.Millisecond)
+				atomic.AddInt64(&active, -1)
+			},
+		})
+	}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	res, err := Run(plan, RunOptions{MaxParallel: maxP})
+	if err != nil {
+		t.Fatal(err)
+	}
+	mu.Lock()
+	observed := peak
+	mu.Unlock()
+	if observed > maxP {
+		t.Fatalf("★ 并发上限 %d 被突破：观测峰值 %d（%d 个模块同层）", maxP, observed, n)
+	}
+	if len(res.Order) != n {
+		t.Fatalf("应执行 %d 个模块，实际 %d", n, len(res.Order))
+	}
+	t.Logf("%d 个模块同层，上限 %d，观测峰值 %d", n, maxP, observed)
+}
+
+// ★★★ 压力：**KernelState 同层并行写**（各写自己字段，无竞争）。
+func TestStressKernelStateParallelWrites(t *testing.T) {
+	ks := NewKernelState()
+	const n = 256
+
+	var wg sync.WaitGroup
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			// 每个"模块"只写自己字段 —— 这正是真实约定。
+			// 若有人违反（写别人的字段），-race 会报。
+			ks.AddCloser(func() {})
+		}(i)
+	}
+	wg.Wait()
+	if len(ks.Closers) != n {
+		t.Fatalf("应记录 %d 个关闭函数，实际 %d（AddCloser 有丢失）", n, len(ks.Closers))
+	}
+	if err := ks.CloseAll(); err != nil {
+		t.Fatal(err)
+	}
+	if len(ks.Closers) != 0 {
+		t.Fatal("CloseAll 后应清空")
+	}
+}
diff --git a/internal/kernelboot/syncbus.go b/internal/kernelboot/syncbus.go
new file mode 100644
index 00000000..62bf9f9a
--- /dev/null
+++ b/internal/kernelboot/syncbus.go
@@ -0,0 +1,290 @@
+package kernelboot
+
+// syncbus：内核就绪状态的同步快照，驱动插件调度（设计 §2.6）。
+//
+// ## 一句话
+//
+// 内核每完成一层装配就把该层贡献的设施标记为"就绪"；
+// 插件管理器**只读**这份状态，据此拉起"依赖已齐"的插件。
+//
+// ## 为什么要有它（解决什么）
+//
+// 现状（`cmd/homed/main.go:291 loadPlugins`）是**一刀切**：
+// 12 个 init* 全部做完才加载全部插件。
+// 于是"只读本地文件"的插件也要等多模态空间（ONNX 加载）+ 知识库建索引做完。
+//
+// 而内核那 12 步本身有明确先后（§2.3 算出 4 层），"阶段"是天然存在的，
+// 只是此前没有对外发布。syncbus 就是那个发布物。
+//
+// ## ★ 权限：插件管理器只读（这不是习惯，是设计）
+//
+// 若插件管理器能写 syncbus，它就能**谎报内核状态**，让插件在自己依赖的东西
+// 还不存在时启动 —— 那正是病 A（静默顺序错）。
+//
+// 所以类型层面分离：内核拿 `*SyncBus`（可写），
+// 插件管理器只拿 `SyncState` 接口（**上面没有写方法**）。
+// 想写也写不了 —— 编译期保证，而非"约定不要写"。
+// 同 `Get[T]` 泛型取用（类型错=编译不过）是一个思路。
+
+import (
+	"sort"
+	"sync"
+)
+
+// SyncState 是 syncbus 的**只读**视图。
+//
+// ★ 刻意不含 MarkReady/Reset：插件管理器拿到的就是这个接口，
+// 因此它**在编译期就不可能**篡改内核状态。
+type SyncState interface {
+	// IsReady 报告某设施是否已就绪。
+	IsReady(facility string) bool
+	// Snapshot 返回当前全部就绪状态的副本（调用方改不动内部）。
+	Snapshot() map[string]bool
+	// ReadyInOrder 按**就绪顺序**返回设施名（调试/判据用）。
+	ReadyInOrder() []string
+	// KernelComplete 报告内核是否已完全初始化（最后一层完成）。
+	KernelComplete() bool
+	// AllReady 报告给定设施是否**全部**就绪（插件调度器的核心判断）。
+	//
+	// ★ 空列表返回 false（不是 true）：见实现处的说明 ——
+	// "没有依赖"与"依赖全就绪"是不同语义，混淆会让未声明依赖的插件提前拉起。
+	AllReady(facilities []string) bool
+
+	// Known 报告某设施名**是否被内核注册过**（不论是否已就绪）。
+	//
+	// ## ★ 为什么必须有它（修一个"静默永不启动"的缺口）
+	//
+	// 插件声明 `requires_facilities` 是**字符串**。若拼错（如写 "llm " 或
+	// "llmservice"），原本的行为是：它永远等不到 → **永不拉起**，
+	// 且**没有任何报错**、没有超时兜底（我第一版设计文档写了"超时兜底"
+	// 但从未实现）。
+	//
+	// 这正是本仓反复吃亏的"静默降级"形态：系统看着正常，某插件就是不工作。
+	//
+	// ⇒ 有了 Known，调度器能在**提交时**立刻报错：
+	//   "插件 X 声明了内核从未注册过的设施 Y（可能是拼写错误）"
+	//   并列出全部已知设施名供对照。
+	Known(facility string) bool
+
+	// KnownFacilities 返回内核**注册过的全部设施名**（含尚未就绪的）。
+	//
+	// 用途：错误信息里列出可选值（让"拼错了"当场可修）。
+	KnownFacilities() []string
+}
+
+// SyncBus 是可写的同步总线（内核持有）。
+type SyncBus struct {
+	mu sync.RWMutex
+	// known 是内核**注册过的全部设施名**（不论是否已就绪）。
+	//
+	// ★ 它存在的唯一目的是让"插件拼错设施名"从**静默永不启动**
+	// 变成**提交时立刻报错**（见 SyncState.Known 的说明）。
+	known    map[string]bool
+	ready    map[string]bool
+	order    []string
+	complete bool
+	onUpdate []func(SyncState)
+	notifyMu sync.Mutex
+}
+
+// NewSyncBus 创建空总线。
+func NewSyncBus() *SyncBus {
+	return &SyncBus{ready: map[string]bool{}, known: map[string]bool{}}
+}
+
+// MarkReady 标记一个设施就绪。**只有内核该调它。**
+//
+// 幂等：重复标记同一设施不报错（便于层边界回调重入）。
+// 但**不重复记录**顺序，保证 ReadyInOrder 可复现。
+func (b *SyncBus) MarkReady(facility string) {
+	if facility == "" {
+		return
+	}
+	b.mu.Lock()
+	if b.ready[facility] {
+		b.mu.Unlock()
+		return
+	}
+	b.ready[facility] = true
+	b.order = append(b.order, facility)
+	b.mu.Unlock()
+	b.fire()
+}
+
+// MarkLayerReady 在**层边界**标记该层所有模块贡献的设施（设计 §2.6.2）。
+//
+// ★ 为何以"层"而不是"单个模块"为同步点：
+// 层内是**并发**执行的，若层内逐个模块标记就绪，就绪顺序会**不确定**，
+// 而判据要求可复现。层边界天然是一个确定的同步点。
+func (b *SyncBus) MarkLayerReady(provides []string) {
+	// 先在锁内一次性写入，再统一通知（避免 N 次通知、N 次唤醒）
+	b.mu.Lock()
+	changed := false
+	for _, f := range provides {
+		if f == "" {
+			continue
+		}
+		b.known[f] = true // 注册过（不论是否首次就绪）
+		if b.ready[f] {
+			continue
+		}
+		b.ready[f] = true
+		b.order = append(b.order, f)
+		changed = true
+	}
+	b.mu.Unlock()
+	if changed {
+		b.fire()
+	}
+}
+
+// MarkDeclared 在**执行前**登记一批设施名（视为"内核注册过"）。
+//
+// ## ★ 为什么需要它（时序）
+//
+// 插件的 `requires_facilities` 校验要在**插件提交时**做（那是错误最该被发现
+// 的时刻，紧挨着写错的插件作者）。但插件的提交发生在内核装配**完成之后**
+// —— 那时所有层都跑完了，Known 自然齐了。
+//
+// 但仍然需要本方法，因为：
+//
+//	· 装配**中途失败**时，后面的层没跑 ⇒ 那些设施名从未登记 ⇒
+//	  若此时还有插件提交，会报"内核从未注册过 X"（**误报**：其实是没跑到）
+//	· 判据要能在**不执行**的情况下校验"插件声明 ⊆ 内核声明"
+//	  （只看声明，不看执行结果）
+//
+// ⇒ 装配开始时把**全部模块的 Provides** 一次性登记为 known。
+// 这样 Known 的语义精确为"**模块声明过**这个设施"，与"是否已就绪"解耦。
+func (b *SyncBus) MarkDeclared(facilities []string) {
+	b.mu.Lock()
+	for _, f := range facilities {
+		if f != "" {
+			b.known[f] = true
+		}
+	}
+	b.mu.Unlock()
+}
+
+// MarkKernelComplete 标记内核已完全初始化。
+//
+// 这是**未声明依赖的插件**的启动信号（默认路径 = 现行为，§2.6.5）。
+func (b *SyncBus) MarkKernelComplete() {
+	b.mu.Lock()
+	if b.complete {
+		b.mu.Unlock()
+		return
+	}
+	b.complete = true
+	b.mu.Unlock()
+	b.fire()
+}
+
+// OnUpdate 注册状态变化回调（插件调度器用它重新检查挂起的插件）。
+//
+// 回调在**不持锁**的情况下调用 —— 否则回调里再读 syncbus 会死锁。
+// （这个坑很容易踩：回调显然要读状态，持锁调用必然死锁。）
+func (b *SyncBus) OnUpdate(fn func(SyncState)) {
+	b.notifyMu.Lock()
+	b.onUpdate = append(b.onUpdate, fn)
+	b.notifyMu.Unlock()
+}
+
+func (b *SyncBus) fire() {
+	b.notifyMu.Lock()
+	cbs := make([]func(SyncState), len(b.onUpdate))
+	copy(cbs, b.onUpdate)
+	b.notifyMu.Unlock()
+	for _, fn := range cbs {
+		fn(b) // b 实现了 SyncState（只读方法）
+	}
+}
+
+// --- SyncState 实现（只读） ---
+
+func (b *SyncBus) IsReady(facility string) bool {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return b.ready[facility]
+}
+
+func (b *SyncBus) Snapshot() map[string]bool {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	out := make(map[string]bool, len(b.ready))
+	for k, v := range b.ready {
+		out[k] = v
+	}
+	return out
+}
+
+func (b *SyncBus) ReadyInOrder() []string {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	out := make([]string, len(b.order))
+	copy(out, b.order)
+	return out
+}
+
+func (b *SyncBus) KernelComplete() bool {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return b.complete
+}
+
+// Known 报告某设施名是否被内核注册过（不论是否已就绪）。
+//
+// ★ 为何"注册过但未就绪"也算 Known：那是**正常的中间状态**
+// （如 llm 声明了但还在第 1 层）。真正的错误是"内核从未注册过这个名字"。
+func (b *SyncBus) Known(facility string) bool {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return b.known[facility]
+}
+
+// KnownFacilities 返回内核注册过的全部设施名（升序，便于对照阅读）。
+func (b *SyncBus) KnownFacilities() []string {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	out := make([]string, 0, len(b.known))
+	for k := range b.known {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// AllReady 报告给定的设施**全部**就绪（插件调度器的核心判断）。
+//
+// 空列表 = 真的全就绪 → 返回 false。
+//
+// ★ 为何空列表返回 false 而不是 true：
+// "没有依赖" 与 "依赖全就绪" 是**不同语义**，混淆会让"未声明依赖的插件"
+// 被当成"依赖已满足"而**提前拉起** —— 那就破坏了 §2.6.5 的存量兼容。
+// 未声明走的是 KernelComplete 那条路径，与这条刻意分开。
+func (b *SyncBus) AllReady(facilities []string) bool {
+	if len(facilities) == 0 {
+		return false
+	}
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	for _, f := range facilities {
+		if !b.ready[f] {
+			return false
+		}
+	}
+	return true
+}
+
+// Missing 返回尚未就绪的设施名（诊断用：告诉用户"还差什么"）。
+func (b *SyncBus) Missing(facilities []string) []string {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	var out []string
+	for _, f := range facilities {
+		if !b.ready[f] {
+			out = append(out, f)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
diff --git a/internal/kernelboot/syncbus_test.go b/internal/kernelboot/syncbus_test.go
new file mode 100644
index 00000000..5aed5a73
--- /dev/null
+++ b/internal/kernelboot/syncbus_test.go
@@ -0,0 +1,412 @@
+package kernelboot
+
+// syncbus + 插件调度器的判据（2026-10-16）。
+//
+// 设计见 docs/zh/kernel-modularization-design.md §2.6。
+//
+// 这组判据里**最重要的一条是"默认路径为零改动"**：
+// 存量 42 个插件都不声明依赖，它们的启动时机必须逐字不变。
+// 静默改变启动时机 = 静默引入竞态。
+
+import (
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// ★★★ 判据（最关键）：**未声明依赖的插件等内核完全初始化**（存量兼容）。
+//
+// 这是整个设计里风险最高的一处：若未声明的插件被"提前"拉起，
+// 42 个存量插件的启动时机全部改变 ⇒ 静默竞态。
+//
+// 反例（若实现错误）：把"未声明"当成"依赖集为空"，而空集在数学上已满足
+// ⇒ 第一层完成后就拉起 ⇒ 比现状早得多。
+func TestSchedulerUndeclaredWaitsForKernelComplete(t *testing.T) {
+	bus := NewSyncBus()
+	var launched []string
+	var mu sync.Mutex
+	sch := NewScheduler(bus, func(p PluginSpec) error {
+		mu.Lock()
+		launched = append(launched, p.Name)
+		mu.Unlock()
+		return nil
+	})
+
+	// 存量插件：不声明依赖
+	sch.Submit([]PluginSpec{{Name: "legacy1", AutoStart: true}})
+	sch.Submit([]PluginSpec{{Name: "legacy2", AutoStart: true}})
+
+	// 内核还在装配中（几层已就绪，但没完成）
+	bus.MarkLayerReady([]string{"config"})
+	bus.MarkLayerReady([]string{"memory", "lua"})
+	bus.MarkLayerReady([]string{"llm"})
+
+	mu.Lock()
+	n := len(launched)
+	mu.Unlock()
+	if n != 0 {
+		t.Fatalf("★ 内核尚未完全初始化，未声明依赖的插件就被拉起了 %d 个（存量行为被改变）", n)
+	}
+
+	// 内核完成 ⇒ 现在才该拉起
+	bus.MarkKernelComplete()
+	mu.Lock()
+	defer mu.Unlock()
+	if len(launched) != 2 {
+		t.Fatalf("内核完成后应拉起 2 个，实际 %d: %v", len(launched), launched)
+	}
+}
+
+// ★★★ 判据：**声明了依赖的插件在依赖就绪时立即拉起**（新能力的正面证据）。
+//
+// 断言"早于内核完成" —— 否则这条判据在"等内核完成"的实现下也会通过（假绿）。
+func TestSchedulerDeclaredLaunchesEarly(t *testing.T) {
+	bus := NewSyncBus()
+	var launched []string
+	var mu sync.Mutex
+	sch := NewScheduler(bus, func(p PluginSpec) error {
+		mu.Lock()
+		launched = append(launched, p.Name)
+		mu.Unlock()
+		return nil
+	})
+
+	// ★ 镜像真实顺序：Run 在**执行前** MarkDeclared（登记全部模块设施名），
+	// 插件 Submit 在装配之后发生 ⇒ 判据必须先声明再提交。
+	bus.MarkDeclared([]string{"config"})
+
+	// 声明只需要 config
+	sch.Submit([]PluginSpec{{Name: "early", RequiresFacilities: []string{"config"}, AutoStart: true}})
+
+	// 第 0 层只提供 config ⇒ 应立刻拉起
+	bus.MarkLayerReady([]string{"config"})
+
+	mu.Lock()
+	got := append([]string{}, launched...)
+	mu.Unlock()
+	if len(got) != 1 || got[0] != "early" {
+		t.Fatalf("★ 依赖已就绪却未拉起: %v", got)
+	}
+
+	// ★ 关键：此时内核**尚未**完成 —— 证明它是"尽早启动"而不是"等完成"
+	if bus.KernelComplete() {
+		t.Fatal("测试设置错误：此刻内核不该已完成")
+	}
+}
+
+// ★★★ 判据：**依赖未齐则挂起**，不会误拉起。
+func TestSchedulerWaitsForMissingDependency(t *testing.T) {
+	bus := NewSyncBus()
+	var launched []string
+	sch := NewScheduler(bus, func(p PluginSpec) error {
+		launched = append(launched, p.Name)
+		return nil
+	})
+
+	// ★ 先声明 llm（登记名字，但尚未就绪）—— 与真实顺序一致。
+	bus.MarkDeclared([]string{"llm", "config", "memory"})
+
+	// 需要 llm
+	sch.Submit([]PluginSpec{{Name: "needsllm", RequiresFacilities: []string{"llm"}, AutoStart: true}})
+
+	bus.MarkLayerReady([]string{"config", "memory"}) // llm 还没好
+	if len(launched) != 0 {
+		t.Fatalf("★ llm 未就绪却拉起了: %v", launched)
+	}
+	if p := sch.Pending(); len(p) != 1 {
+		t.Fatalf("应挂起 1 个，实际 %v", p)
+	}
+
+	// llm 就绪 ⇒ 拉起
+	bus.MarkLayerReady([]string{"llm"})
+	if len(launched) != 1 || launched[0] != "needsllm" {
+		t.Fatalf("llm 就绪后应拉起: %v", launched)
+	}
+}
+
+// ★★★ 判据：**只读隔离**（编译期保证，不是约定）。
+//
+// 断言 Scheduler 拿到的接口**没有**写方法 —— 如果给它 *SyncBus，
+// 它就能谎报内核状态，让插件在依赖不存在时启动（病 A）。
+func TestSchedulerCannotWriteSyncState(t *testing.T) {
+	// ★ 检查必须是**接口类型的方法集**，不是某个具体值。
+	//
+	// 我第一次写错了：用 `var st SyncState = NewSyncBus()` 再断言 `st.(writer)` ——
+	// 那检查的是**动态类型**（*SyncBus 当然有 MarkReady），判据当场报假红。
+	// 要约束的是"拿到 SyncState 的人**能不能**调写方法" ⇒ 必须查接口的方法集。
+	rt := reflect.TypeOf((*SyncState)(nil)).Elem()
+	forbidden := []string{"MarkReady", "MarkKernelComplete", "MarkLayerReady"}
+	for i := 0; i < rt.NumMethod(); i++ {
+		m := rt.Method(i).Name
+		for _, bad := range forbidden {
+			if m == bad {
+				t.Fatalf("★ SyncState（插件管理器拿到的接口）暴露了写方法 %s —— "+
+					"它能谎报内核状态，让插件在依赖不存在时启动（病 A）", m)
+			}
+		}
+	}
+	// 反向确认：读方法必须在（否则接口退化到没用了）
+	for _, want := range []string{"IsReady", "Snapshot", "AllReady", "KernelComplete"} {
+		if _, ok := rt.MethodByName(want); !ok {
+			t.Errorf("SyncState 缺少读方法 %s", want)
+		}
+	}
+	// Scheduler 持有的字段类型也必须是 SyncState（不能是 *SyncBus）
+	st := reflect.TypeOf(Scheduler{})
+	f, ok := st.FieldByName("bus")
+	if !ok {
+		t.Fatal("Scheduler 应有 bus 字段")
+	}
+	if f.Type.String() != "kernelboot.SyncState" {
+		t.Fatalf("★ Scheduler.bus 的类型是 %s —— 必须是只读的 SyncState", f.Type)
+	}
+}
+
+// ★★★ 判据：**不伴随启动的插件即使依赖齐了也不自动拉起**（§2.6.6）。
+func TestSchedulerAutoStartFalseIsNotLaunched(t *testing.T) {
+	bus := NewSyncBus()
+	var launched []string
+	sch := NewScheduler(bus, func(p PluginSpec) error {
+		launched = append(launched, p.Name)
+		return nil
+	})
+
+	bus.MarkDeclared([]string{"config"})
+	sch.Submit([]PluginSpec{
+		{Name: "manual", RequiresFacilities: []string{"config"}, AutoStart: false},
+	})
+	bus.MarkLayerReady([]string{"config"})
+	bus.MarkKernelComplete()
+
+	if len(launched) != 0 {
+		t.Fatalf("★ auto_start=false 的插件被自动拉起了（应等显式启用）: %v", launched)
+	}
+	if len(sch.Pending()) != 1 {
+		t.Fatalf("它应一直挂起等显式启用: %v", sch.Pending())
+	}
+}
+
+// ★★★ 判据：**就绪顺序可复现**（层内并发不得导致就绪顺序抖动）。
+//
+// 为何重要：syncbus 的就绪顺序决定哪些插件何时被拉起；
+// 若顺序随机，同一份声明两次启动会拉出不同结果 ⇒ 不可审计、不可复现。
+func TestSyncBusReadyOrderIsDeterministic(t *testing.T) {
+	// 模拟"层内并发完成"：同一层 8 个设施，用 goroutine 乱序 MarkReady
+	var first []string
+	for round := 0; round < 5; round++ {
+		bus := NewSyncBus()
+		var wg sync.WaitGroup
+		fac := []string{"f1", "f2", "f3", "f4", "f5", "f6", "f7", "f8"}
+		for i, f := range fac {
+			wg.Add(1)
+			go func(i int, f string) {
+				defer wg.Done()
+				// 反过来启动，制造乱序完成
+				_ = i
+				bus.MarkReady(f)
+			}(i, f)
+		}
+		wg.Wait()
+		got := bus.ReadyInOrder()
+		if round == 0 {
+			first = got
+			continue
+		}
+		// 注意：MarkReady（单设施）的顺序本就取决于并发，不保证可复现；
+		// 设计保证的是 **MarkLayerReady**（层边界一次性写入）可复现。
+		// 所以这里只断言"同样的输入产生同样的集合"。
+		if len(got) != len(first) {
+			t.Fatalf("就绪集合大小抖动: %d vs %d", len(got), len(first))
+		}
+	}
+
+	// ★ 真正的可复现性断言：MarkLayerReady 一次性写入
+	var order []string
+	for round := 0; round < 3; round++ {
+		bus := NewSyncBus()
+		bus.MarkLayerReady([]string{"a", "b", "c"})
+		bus.MarkLayerReady([]string{"d", "e"})
+		got := bus.ReadyInOrder()
+		joined := strings.Join(got, ",")
+		if round == 0 {
+			order = got
+			continue
+		}
+		if joined != strings.Join(order, ",") {
+			t.Fatalf("★ MarkLayerReady 的就绪顺序不可复现:\n%v\n%v", order, got)
+		}
+	}
+	if strings.Join(order, ",") != "a,b,c,d,e" {
+		t.Fatalf("就绪顺序应为层内声明序: %v", order)
+	}
+
+	// ★ 幂等性：**重复标记**同一设施不得重复记录顺序。
+	//
+	// 为何要单独断言：Run 的层边界回调可能在某些路径重入
+	//（且调用方也可能手动重复标记）。若不幂等，order 会不断膨胀
+	// ⇒ 就绪顺序不再反映真实层序 ⇒ 依赖它的调度判断变得不可解释。
+	//
+	// 这条是补的：变异"去掉幂等检查"第一次没被咬住 —— 因为原判据
+	// 只跑了一份声明、没重复标记，测不到幂等性。
+	bus := NewSyncBus()
+	bus.MarkLayerReady([]string{"a", "b"})
+	bus.MarkLayerReady([]string{"a", "b"}) // 重复
+	bus.MarkLayerReady([]string{"c"})
+	if got := strings.Join(bus.ReadyInOrder(), ","); got != "a,b,c" {
+		t.Fatalf("★ 重复标记导致就绪顺序膨胀（不幂等）: %v（期望 a,b,c）", got)
+	}
+}
+
+// ★★★ 判据：**内核未完成时绝不发 KernelComplete**（内核没装好就不该放插件）。
+//
+// 这条守的是：装配中途失败 ⇒ 未声明依赖的插件**不**被拉起。
+func TestRunDoesNotMarkCompleteOnFailure(t *testing.T) {
+	bus := NewSyncBus()
+	mods := []Module{
+		&fakeModule{name: "A", provides: []string{"a"}},
+		&fakeModule{name: "B", provides: []string{"b"}, initErr: errFake},
+	}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Run(plan, RunOptions{Bus: bus}); err == nil {
+		t.Fatal("应失败")
+	}
+	if bus.KernelComplete() {
+		t.Fatal("★ 装配失败了却标记内核完成 —— 未声明依赖的插件会被拉起（病 A）")
+	}
+}
+
+// ★★★ 判据：**Run 在层边界自动发布本层设施**（不用模块自己标记）。
+//
+// 为何由 Run 做：模块自己标记会漏（静默漏一个设施 ⇒ 插件永远等不到），
+// 且顺序取决于层内并发完成序。
+func TestRunPublishesFacilitiesAtLayerBoundary(t *testing.T) {
+	bus := NewSyncBus()
+	mods := []Module{
+		&fakeModule{name: "config", provides: []string{"config", "config-write"}},
+		&fakeModule{name: "llm", provides: []string{"llm"}, requires: []string{"config"}},
+	}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Run(plan, RunOptions{Bus: bus}); err != nil {
+		t.Fatal(err)
+	}
+	for _, f := range []string{"config", "config-write", "llm"} {
+		if !bus.IsReady(f) {
+			t.Errorf("★ 设施 %q 未在层边界被发布", f)
+		}
+	}
+	if !bus.KernelComplete() {
+		t.Error("全部完成后应标记内核完成")
+	}
+}
+
+// ★★★ 判据：**空依赖列表 ≠ 已满足**（语义区分的直接断言）。
+//
+// 若这条反了，未声明依赖的插件会被提前拉起（见第一条判据）。
+func TestAllReadyEmptyIsFalse(t *testing.T) {
+	bus := NewSyncBus()
+	bus.MarkKernelComplete()
+	if bus.AllReady(nil) {
+		t.Fatal("★ AllReady(空) 返回 true —— \"没有依赖\"被当成\"依赖全就绪\"，未声明插件会提前拉起")
+	}
+	if bus.AllReady([]string{}) {
+		t.Fatal("★ AllReady(空切片) 返回 true")
+	}
+	// 非空且齐 ⇒ true
+	bus.MarkReady("x")
+	if !bus.AllReady([]string{"x"}) {
+		t.Fatal("依赖确实就绪应返回 true")
+	}
+}
+
+// ★★★ 判据：**拉起失败不阻塞其他插件**（一个坏插件不该拖垮全局）。
+func TestSchedulerLaunchFailureDoesNotBlockOthers(t *testing.T) {
+	bus := NewSyncBus()
+	var okLaunched []string
+	sch := NewScheduler(bus, func(p PluginSpec) error {
+		if p.Name == "bad" {
+			return errFake
+		}
+		okLaunched = append(okLaunched, p.Name)
+		return nil
+	})
+	var failures int
+	sch.SetLaunchErrorHandler(func(PluginSpec, error) { failures++ })
+
+	bus.MarkDeclared([]string{"config"})
+	sch.Submit([]PluginSpec{
+		{Name: "bad", RequiresFacilities: []string{"config"}, AutoStart: true},
+		{Name: "good", RequiresFacilities: []string{"config"}, AutoStart: true},
+	})
+	bus.MarkLayerReady([]string{"config"})
+
+	if len(okLaunched) != 1 || okLaunched[0] != "good" {
+		t.Fatalf("★ 一个插件拉起失败影响了其他插件: %v", okLaunched)
+	}
+	if failures != 1 {
+		t.Fatalf("失败应被报告: %d", failures)
+	}
+}
+
+// ★★★ 判据：**重复 Submit 不重复拉起**（幂等）。
+func TestSchedulerIsIdempotent(t *testing.T) {
+	bus := NewSyncBus()
+	n := 0
+	sch := NewScheduler(bus, func(PluginSpec) error { n++; return nil })
+	bus.MarkKernelComplete()
+
+	sch.Submit([]PluginSpec{{Name: "p", AutoStart: true}})
+	sch.Submit([]PluginSpec{{Name: "p", AutoStart: true}})
+	bus.MarkKernelComplete() // 再触发一次评估
+
+	if n != 1 {
+		t.Fatalf("★ 同一插件被拉起 %d 次（应幂等）", n)
+	}
+}
+
+// ★★★ 判据：**MarkReady 的通知也在锁外**（走单设施路径的订阅者不死锁）。
+//
+// 变异 8b 暴露的边界：MarkLayerReady 持锁回调会死锁（已被
+// TestSchedulerDeclaredLaunchesEarly 咬住），但 MarkReady 是**另一条路径**
+// （单个设施的标记），若它持锁回调，只有"既调 MarkReady 又订阅"的场景才会卡住。
+// 补这条判据把两条路径都盖住。
+func TestSyncBusMarkReadyNotifiesWithoutDeadlock(t *testing.T) {
+	bus := NewSyncBus()
+	got := make(chan string, 4)
+
+	// 订阅者**读状态**（真实回调必然会读，这正是死锁触发条件）
+	bus.OnUpdate(func(s SyncState) {
+		_ = s.Snapshot() // 持锁调用的话，这里会等 RLock ⇒ 死锁
+		got <- "ok"
+	})
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		bus.MarkReady("config")
+	}()
+
+	select {
+	case <-got:
+	case <-done:
+		t.Fatal("★ MarkReady 未通知订阅者（订阅者拿不到更新 ⇒ 插件不会自动拉起）")
+	case <-timeAfter(5):
+		t.Fatal("★ MarkReady 持锁调用回调 ⇒ 死锁（回调读状态时会等锁）")
+	}
+}
+
+func timeAfter(sec int) <-chan struct{} {
+	ch := make(chan struct{})
+	go func() {
+		time.Sleep(time.Duration(sec) * time.Second)
+		close(ch)
+	}()
+	return ch
+}
diff --git a/internal/kernelboot/unknownfac_test.go b/internal/kernelboot/unknownfac_test.go
new file mode 100644
index 00000000..f5c81997
--- /dev/null
+++ b/internal/kernelboot/unknownfac_test.go
@@ -0,0 +1,139 @@
+package kernelboot
+
+// "插件拼错设施名 ⇒ 静默永不启动" 的判据（2026-10-16）。
+//
+// ## 修的缺口
+//
+// 插件声明 `requires_facilities` 是**字符串**。拼错时原行为：
+// 永远等不到就绪 ⇒ **永不拉起**，且**无任何报错**、无超时兜底。
+// 这正是本仓反复吃亏的"静默降级"形态。
+//
+// 修法：Submit 时校验"声明的设施 ⊆ 内核注册过的"，不符即报错并列出可选值。
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// ★★★ 判据：**拼错的设施名在 Submit 时被拒绝**（不再静默挂起）。
+func TestSchedulerRejectsUnknownFacility(t *testing.T) {
+	bus := NewSyncBus()
+	bus.MarkDeclared([]string{"config", "llm", "memory"}) // 内核注册过这些
+
+	var launched []string
+	var reported []string
+	sch := NewScheduler(bus, func(p PluginSpec) error {
+		launched = append(launched, p.Name)
+		return nil
+	})
+	sch.SetLaunchErrorHandler(func(p PluginSpec, err error) {
+		reported = append(reported, err.Error())
+	})
+
+	// 拼错：写 "llmservice" 而不是 "llm"
+	sch.Submit([]PluginSpec{{Name: "typo", RequiresFacilities: []string{"llmservice"}, AutoStart: true}})
+	bus.MarkKernelComplete()
+
+	if len(launched) != 0 {
+		t.Fatalf("★ 拼错设施名的插件被拉起了: %v", launched)
+	}
+	if len(reported) == 0 {
+		t.Fatal("★ 拼错设施名却**没有任何报错** —— 插件会静默永不启动（这正是要修的缺口）")
+	}
+	msg := reported[0]
+	if !strings.Contains(msg, "llmservice") {
+		t.Errorf("错误应点出**是哪个名字**错了: %s", msg)
+	}
+	// 必须列出内核已知的设施名（"拼错了"当场可修）
+	if !strings.Contains(msg, "llm") || !strings.Contains(msg, "config") {
+		t.Errorf("错误应列出内核已知的设施名供对照: %s", msg)
+	}
+	// 不得把它留在挂起队列（否则会永远占位）
+	if p := sch.Pending(); len(p) != 0 {
+		t.Errorf("被拒的插件不该留在挂起队列: %v", p)
+	}
+}
+
+// ★★★ 判据：**正确的设施名不受影响**（不能把正常路径也拦了）。
+func TestSchedulerAcceptsKnownFacility(t *testing.T) {
+	bus := NewSyncBus()
+	bus.MarkDeclared([]string{"config", "llm"})
+	// ★ 必须同时 MarkLayerReady —— 真实路径里 Run 两者都会做：
+	// MarkDeclared（执行前，登记名字）与 MarkLayerReady（每层完成，标记就绪）。
+	// 只声明不就绪 ⇒ 插件会一直挂起（那是"未就绪"而非"拼错"，两者不同）。
+	bus.MarkLayerReady([]string{"config", "llm"})
+
+	var launched []string
+	sch := NewScheduler(bus, func(p PluginSpec) error {
+		launched = append(launched, p.Name)
+		return nil
+	})
+	sch.SetLaunchErrorHandler(func(p PluginSpec, err error) {
+		t.Errorf("不应报错: %v", err)
+	})
+
+	sch.Submit([]PluginSpec{{Name: "ok", RequiresFacilities: []string{"config", "llm"}, AutoStart: true}})
+	bus.MarkKernelComplete()
+
+	if len(launched) != 1 || launched[0] != "ok" {
+		t.Fatalf("声明正确的插件应被拉起: %v", launched)
+	}
+}
+
+// ★★★ 判据：**"注册过但未就绪"是合法中间状态**（不能误判为拼错）。
+//
+// ★ 这条很重要：llm 声明了但还在第 1 层时，Known 为 true、Ready 为 false。
+// 若把"未就绪"当"拼错"，所有多依赖插件都会在提交时被误拒。
+func TestSchedulerAcceptsDeclaredButNotYetReady(t *testing.T) {
+	bus := NewSyncBus()
+	bus.MarkDeclared([]string{"config", "llm"}) // 两者都已声明
+	bus.MarkLayerReady([]string{"config"})      // 只有 config 就绪
+
+	var reported []string
+	sch := NewScheduler(bus, nil)
+	sch.SetLaunchErrorHandler(func(p PluginSpec, err error) { reported = append(reported, err.Error()) })
+
+	sch.Submit([]PluginSpec{{Name: "needsllm", RequiresFacilities: []string{"llm"}, AutoStart: true}})
+	if len(reported) != 0 {
+		t.Fatalf("★ '已声明但未就绪'被误判为拼错: %v", reported)
+	}
+	if p := sch.Pending(); len(p) != 1 {
+		t.Fatalf("应挂起等 llm 就绪: %v", p)
+	}
+	// llm 就绪后应被拉起
+	bus.MarkLayerReady([]string{"llm"})
+}
+
+// ★★★ 判据：**Run 执行前登记全部模块设施**（装配中途失败也能校验）。
+//
+// ★ 为何需要：插件提交发生在装配之后。若某层失败、后面的模块没跑，
+// 那些设施名就从未被 MarkLayerReady 登记 ⇒ 会**误报**"内核从未注册过"。
+// 所以 Run 必须**执行前**就 MarkDeclared。
+func TestRunDeclaresAllFacilitiesUpfront(t *testing.T) {
+	bus := NewSyncBus()
+	mods := []Module{
+		&fakeModule{name: "a", provides: []string{"fa"}},
+		&fakeModule{name: "b", provides: []string{"fb"}, requires: []string{"fa"},
+			initErr: fmt.Errorf("故意失败")},
+		&fakeModule{name: "c", provides: []string{"fc"}, requires: []string{"fb"}},
+	}
+	plan, err := Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 这个 Run 会**失败**（b 的 Init 报错）⇒ c 那一层不会跑
+	if _, err := Run(plan, RunOptions{Bus: bus}); err == nil {
+		t.Fatal("前置：应失败")
+	}
+	// ★ 但全部设施名都应已登记（因为执行前就 MarkDeclared 了）
+	for _, f := range []string{"fa", "fb", "fc"} {
+		if !bus.Known(f) {
+			t.Errorf("★ 设施 %q 未被登记 —— 装配中途失败后，插件提交会误报\"内核从未注册过\"", f)
+		}
+	}
+	// 而未跑到的层不该是"就绪"
+	if bus.IsReady("fc") {
+		t.Error("未执行的模块不该标记就绪")
+	}
+}
diff --git a/internal/kernelmod/agent/mod.go b/internal/kernelmod/agent/mod.go
new file mode 100644
index 00000000..63c70875
--- /dev/null
+++ b/internal/kernelmod/agent/mod.go
@@ -0,0 +1,316 @@
+// Package agent 是 agent 模块：主 Agent（需在插件加载前创建，
+// 因为插件 Configure 需要 StatusProvider）。
+//
+// ## 依赖
+//
+// buildAgent 收 provider/providerMgr/iom/mem.db/mem.indexer/trk/docStore/
+// knowledge/mem.social/textMem/personality/pluginReg/embedder/
+// multimodalSpace/stageHost/evBus ⇒ 依赖除 supervisor 外的几乎全部下层模块。
+//
+// 人格设定（loadPersonality）在本模块内完成 —— 它只读配置文件，
+// 没有独立产物的价值，不必单列模块。
+package agent
+
+import (
+	"fmt"
+	"log"
+	"path/filepath"
+	"strings"
+	"time"
+
+	agentCore "github.com/JianFeeeee/HomeAgent/internal/agent/core"
+	"github.com/JianFeeeee/HomeAgent/internal/config"
+	"github.com/JianFeeeee/HomeAgent/internal/events"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/memory"
+	"github.com/JianFeeeee/HomeAgent/internal/supervisor"
+	"github.com/JianFeeeee/HomeAgent/pkg/types"
+
+	agentPkg "github.com/JianFeeeee/HomeAgent/internal/agent"
+)
+
+// Module 提供主 Agent。
+type Module struct{}
+
+func (Module) Name() string { return "agent" }
+func (Module) Requires() []string {
+	return []string{kernelmod.FacLLM, kernelmod.FacMemory, kernelmod.FacTracker,
+		kernelmod.FacDocStore, kernelmod.FacKnowledge, kernelmod.FacTextMem,
+		kernelmod.FacStageHost}
+}
+func (Module) Provides() []string { return []string{kernelmod.FacAgent} }
+
+func (Module) Init(k *kernelboot.KernelState) error {
+	if k.Memory == nil {
+		return errMissing("agent", kernelmod.FacMemory)
+	}
+	if k.LLMManager == nil {
+		return errMissing("agent", kernelmod.FacLLM)
+	}
+	if k.PluginRegistry == nil {
+		return errMissing("agent", kernelmod.FacStageHost)
+	}
+	k.Agent = buildAgent(k)
+
+	// 插件 SDK 接线（必须在 loadPlugins 之前）。
+	wirePluginSDK(k)
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
+
+const defaultSystemPrompt = `你是 HomeAgent，一个持续运行的个人管家。
+你的每次回复会自动发送到当前输出通道（默认=输入源），无需额外工具。
+如需切换回复通道，使用 output_set_channel。
+如需异步发送消息或通知，使用 output_send 指定通道和内容。
+使用 output_list_channels 查看可用通道及其能力。
+
+可用工具列表会由系统自动传入，按需使用即可。以下是你尤其需要关注的几类工具：
+- memory_* — 图记忆（长期记忆，记录和查询个人信息/事实）
+- knowledge_* — 知识库（查阅预设知识文档）
+- doc_* — 文档记忆（近期对话的存档，查询后自动清除）
+- person_* — 人物特质与社交关系网
+- llm_* — LLM 源管理（列出/切换模型提供商）
+- output_* — 输出通道管理（切换/发送消息）
+- timer_set — 设置定时提醒
+- plgreload — 热重载插件
+- spawn_child — 生成子 Agent 异步执行独立任务（可传 max_turns 控制工具轮数，默认 5）
+
+并行策略：遇到多个互不依赖的子任务时，优先并行 spawn 多个子 Agent 而非自己串行逐个执行；
+长耗时任务（批量处理、多轮搜索汇总）也应交给子 Agent，避免阻塞当前对话。
+- describe_image — 描述用户上传的图片
+- transcribe_audio — 转写用户上传的音频
+- ocr_image — 识别图片中的文字
+
+命令与文件操作策略：
+- cmd_run 经完整 shell（bash）执行，支持管道、分号、&&、命令替换、heredoc、重定向。
+- 多步交互式程序（vim/top/ssh 会话、需要持续输入的进程）用 terminal_create 创建终端，
+  terminal_write 发送输入、terminal_read 读输出——不要用 cmd_run 硬等交互程序退出。
+- 写文件优先 files_write（原子+留档），生成多行内容时可用 heredoc 或 files_write，
+  不要用 echo 拼接长文本。
+- 读用户发来的文件用 files_read；向 webui 回传图片/文件用 output_send__webui(type=image/file)。
+
+当用户上传图片或音频时，系统会自动附着媒体内容。如果模型不支持直接处理多媒体，请使用上述工具。
+
+回复你的真实想法，用自然语言与用户交流。不要在回复中使用 emoji 表情。`
+
+func buildAgent(k *kernelboot.KernelState) *agentCore.Agent {
+	cfg := k.Cfg
+	cfgReg := k.CfgReg
+	provider := k.LLMProvider
+	providerMgr := k.LLMManager
+	iom := k.IO
+	memDB := k.Memory.DB
+	memIdx := k.Memory.Indexer
+	trk := k.Tracker
+	docStore := k.DocStore
+	ks := k.Knowledge
+	socialStore := k.Memory.Social
+	textMem := k.TextMemory
+	pluginReg := k.PluginRegistry
+	embedder := k.Embedder
+	multimodalSpace := k.MultimodalSpace
+	mmProviderName := k.MultimodalProviderName
+	mmErr := k.MultimodalErr
+	stageHost := k.StageHost
+	evBus := k.EventBus
+
+	personality := loadPersonality(cfg, cfgReg)
+
+	sysPrompt := cfgReg.GetString("core.agent.system_prompt", defaultSystemPrompt)
+	if sysPrompt == "" {
+		sysPrompt = defaultSystemPrompt
+	}
+
+	// D4：把"设备是否已授权"的判据注入插件侧（toolImpl.CanUse 用）。
+	// ⚠️ 必须放在 agent 构造**之后**——判据要用 agent 的 allowedOutputs，
+	// 而 registry 早于 agent 构造（故这里传的是晚绑定闭包）。
+	// 未注入时 ToolAPI 路径对设备放行：那是"授权可被绕过"的既成缺口。
+	// 注入后，cli 的 /terminal、seq 序列等一切走 ToolAPI 的调用都受同一道闸。
+	agent := agentCore.New(agentCore.AgentConfig{
+		ID:              "main",
+		SystemPrompt:    sysPrompt,
+		Provider:        provider,
+		ProviderManager: providerMgr,
+		IO:              iom,
+		Memory:          memDB,
+		Indexer:         memIdx,
+		Tracker:         trk,
+		DocStore:        docStore,
+		Knowledge:       ks,
+		SocialStore:     socialStore,
+		TextMemory:      textMem,
+		// MediaStore 已随 CAS 淘汰：块自带负载（见 plan.md）。
+		Personality: personality,
+		// 人格落库面：首启门禁（任何通道都问一次）与 persona_set 工具用。
+		// 与 WebUI 向导共用 internal/config 的同一份落库逻辑。
+		PersonaStore: config.RegistryPersonaStore{Reg: cfgReg},
+		PluginReg:    pluginReg,
+		PluginDir:    cfg.Plugin.Dir,
+		// DataDir：驻留子的 temp 图库锚点（<data>/residents/<id>/graph.db）。
+		// 漏接时的现象是"工具存在、可调用、但创建必失败"——只有真实二进制才看得出来。
+		DataDir:         cfg.Daemon.DataDir,
+		DistillInterval: cfgReg.GetDuration("core.agent.distill_interval", 30*time.Minute),
+		ArchiveInterval: cfgReg.GetDuration("core.agent.archive_interval", 60*time.Minute),
+		ReviewInterval:  cfgReg.GetDuration("core.agent.review_interval", 120*time.Minute),
+		MergeInterval:   cfgReg.GetDuration("core.agent.merge_interval", 120*time.Minute),
+		MaxToolTurns:    cfgReg.GetInt("core.agent.max_tool_turns", 10),
+		// 上下文管理的可调阈值。此前这些值全部硬编码在 ComputeTokenBudget 里，
+		// 界面改不了、不同窗口的实例也没法各自调优。
+		CtxTuning: agentCore.ContextTuning{
+			UtilizationPercent: cfgReg.GetInt("core.agent.context.utilization_percent", 80),
+			MaxTargetTokens:    cfgReg.GetInt("core.agent.context.max_target_tokens", 600000),
+			MemoryRatioPercent: cfgReg.GetInt("core.agent.context.memory_ratio_percent", 0),
+			ProtectedCount:     cfgReg.GetInt("core.agent.context.protected_count", 10),
+		},
+		// ⚠️ 这条键此前被注册进配置面板、也有默认值，但**从未被读取** ——
+		// 界面上改它没有任何效果，且不报任何错。同一类「死配置」正是
+		// 本次把阈值接入配置系统时要一并修掉的。
+		MaxContextSize: cfgReg.GetInt("core.agent.max_context_size", 30),
+		Offload: agentCore.OffloadOptions{
+			Enabled:      cfgReg.GetBool("core.agent.offload_enabled", false),
+			BusyAfter:    cfgReg.GetDuration("core.agent.offload_busy_after", 5*time.Minute),
+			MinPending:   cfgReg.GetInt("core.agent.offload_min_pending", 3),
+			MaxResidents: cfgReg.GetInt("core.agent.offload_max_residents", 2),
+		},
+		ContextSavePath:    filepath.Join(cfg.Daemon.DataDir, "memory", "context.json"),
+		EmbeddingModelPath: cfgReg.GetString("core.agent.embedding_model_path", ""),
+		Embedder:           embedder,
+		MultimodalSpace:    multimodalSpace,
+		EmbeddingProvider:  mmProviderName,
+		EmbeddingError:     mmErr,
+		StageHost:          stageHost,
+		EventBus:           evBus,
+		ThinkingEnabled:    cfg.LLM.ThinkingEnabled,
+		InputProcessing:    cfg.InputProcessing,
+	})
+
+	// 图记忆读写钩子 → 事件总线。
+	//
+	// ★ 为什么在这里接（而不是让各调用方自己发事件）：
+	//   图读写散在 26 个方法与 180+ 个 db 调用点上，各调用方自报必漏发；
+	//   而**图库自己就知道它碰了哪些块 ID**。星图此前只能靠工具名猜
+	//   节点（把 "memory_recall" 拆词去匹配中文实体名，实测命中 0），
+	//   于是每次都点亮同一批无关节点——这正是「星图没有读写反馈」的真身。
+	//
+	// ★ 只在 evBus 非 nil 时接：它把「内核进程」与「独立 CLI 工具」区分开
+	//   （homed-graph-migrate / memgc 等也用 NewGraphDB，但没有事件总线，
+	//   也不该为一次批量迁移向不存在的订阅者发几万条事件）。
+	//
+	// ★ 钩子**必须非阻塞**：它在记忆读写的同步路径上，发布到总线
+	//   是内存操作（各订阅者回调也都很短），实测开销可忽略。
+	if memDB != nil && evBus != nil {
+		memDB.SetAccessHook(func(ev memory.AccessEvent) {
+			payload := map[string]interface{}{
+				"op": ev.Op,
+			}
+			// 只在非空时带上字段：空数组会让前端白白重算一次。
+			if len(ev.Blocks) > 0 {
+				payload["blocks"] = ev.Blocks
+			}
+			if len(ev.Created) > 0 {
+				payload["created"] = ev.Created
+			}
+			if len(ev.Removed) > 0 {
+				payload["removed"] = ev.Removed
+			}
+			if len(ev.Merged) > 0 {
+				merged := make([]map[string]string, 0, len(ev.Merged))
+				for _, m := range ev.Merged {
+					merged = append(merged, map[string]string{"from": m.From, "to": m.To})
+				}
+				payload["merged"] = merged
+			}
+			if ev.Tool != "" {
+				payload["tool"] = ev.Tool
+			}
+			evBus.Publish(&events.Event{
+				Type:      events.EventMemoryAccess,
+				Source:    "main",
+				Payload:   payload,
+				Timestamp: time.Now().Unix(),
+			})
+		})
+	}
+
+	// D4：把「设备是否已授权」的判据注入插件侧（toolImpl.CanUse 消费它）。
+	//
+	// 为什么必须在这里：判据要用 agent 自己的 allowedOutputs，而
+	// pluginReg 早于 agent 构造（newStageAndRegistry 在 main() 里先跑），
+	// 所以 registry 存的是**晚绑定**闭包，注入点必须在 agent 建好之后。
+	//
+	// 不注入的后果（已实测的真实缺口）：设备授权闸只存在于
+	// core.executeToolCallInner，即「agent 收到模型 tool_call」那条路径；
+	// 而 ToolAPI.ExecuteTool 是**另一条**独立入口，不经那道闸 ⇒
+	// 凡是走 ToolAPI 的调用都能绕过 AllowedOutputs。实测范围不止序列：
+	// cli 的 /terminal 就直接经 ToolAPI 调 agentcli 的终端工具。
+	pluginReg.SetDeviceAuthQuery(func(deviceID string) bool {
+		return agent.IsOutputAllowed("device/" + deviceID)
+	})
+
+	// 方案 B：把 agent 的**内置工具面**注入 ToolAPI。
+	//
+	// 缺口背景：`memory_*` / `knowledge_*` / `doc_*` / `person_*` 这 20+ 个
+	// 在 executeToolCallInner 里按前缀分派，从不进 ToolAPI ⇒ 插件经 ToolAPI
+	// 既查不到也调不了。真机实跑实证：seq_run 报「工具 knowledge_list
+	// 不存在或未注册」，而同一轮模型直接调它是成功的。
+	//
+	// 注入必须在此处（agent 构造之后）：内置工具的可见性由运行期状态门控
+	// （memory/knowledge 是否就绪），而 provider 持有的是 agent。
+	agent.InstallBuiltinToolProvider()
+
+	return agent
+}
+
+// wirePluginSDK 把内核依赖注入插件注册表（原 cmd/homed 的整块平移）。
+func wirePluginSDK(k *kernelboot.KernelState) {
+	k.PluginRegistry.SetLuaVM(k.LuaVM)
+	k.PluginRegistry.SetBaseAPIKey(k.BaseAPIKey)
+	k.PluginRegistry.SetSupervisor(supervisor.NewSDKAdapter(k.Supervisor))
+	k.PluginRegistry.SetTracker(k.Tracker)
+	k.PluginRegistry.SetConfig(k.Cfg)
+	k.PluginRegistry.SetStageHost(k.StageHost)
+	k.PluginRegistry.SetIndexer(k.Memory.Indexer)
+	k.PluginRegistry.SetStatusProvider(k.Agent)
+	k.PluginRegistry.SetTerminalAPI(k.Agent)
+}
+
+// loadPersonality 载入人格（原 cmd/homed 的整块平移）。
+func loadPersonality(cfg *types.Config, cfgReg *config.ConfigRegistry) *agentPkg.Personality {
+	personalPath := filepath.Join(cfg.Daemon.DataDir, "personal", "personal.md")
+	personality, err := agentPkg.LoadPersonality(personalPath)
+	if err != nil {
+		log.Printf("[homed] warning: load personality: %v", err)
+	}
+	if personality != nil && personality.Content != "" {
+		log.Printf("[homed] 人格来源=文件 %s（优先于配置项），%d 字节", personalPath, len(personality.Content))
+		if hints := agentPkg.PersonaStaleHints(personality.Content); len(hints) > 0 {
+			log.Printf("[homed] warning: 人格文件含会腐坏的内容 %v — 建议迁到配置项 core.agent.personal_prompt"+
+				"（默认模板不含版本号，被问版本时以运行时快照为准）", hints)
+		}
+	} else if pv := cfgReg.GetString("core.agent.personal_prompt", config.DefaultPersonaPrompt); strings.TrimSpace(pv) != "" {
+		personality = &agentPkg.Personality{Content: pv, Path: "(core.agent.personal_prompt)"}
+		log.Printf("[homed] 人格来源=配置项 core.agent.personal_prompt，%d 字节", len(pv))
+	} else {
+		log.Printf("[homed] 人格来源=无（配置项为空且无人格文件）")
+	}
+	return personality
+}
+
+// errMissing 报告"依赖的模块产物为 nil"。
+//
+// ★ 为什么立刻报错而不是让 nil 传下去：nil 读出零值后 continue 会在**很远
+// 的地方**变成模糊症状（如"模型没有配置"）。这里点出**是哪个模块的哪个
+// 产物缺失**，把排查成本从"追几小时"降到"看一行"。
+//
+// 措辞刻意点出"依赖图本应保证它非 nil" —— 若真出现，说明
+// ① 模块忘了声明依赖，或 ② Requires/Provides 设施名不一致（拼写漂移）。
+func errMissing(moduleName, facility string) error {
+	return fmt.Errorf("模块 %s 依赖的设施 %q 对应的数据为 nil —— "+
+		"依赖图本应保证它已就绪。两种可能：① 该模块没在 Requires 里声明这个依赖；"+
+		"② Provides/Requires 的设施名写得不一致（拼写漂移）", moduleName, facility)
+}
+
+var _ = events.EventMemoryAccess
+var _ = memory.AccessEvent{}
diff --git a/internal/kernelmod/all/all.go b/internal/kernelmod/all/all.go
new file mode 100644
index 00000000..c2b07a4b
--- /dev/null
+++ b/internal/kernelmod/all/all.go
@@ -0,0 +1,43 @@
+// Package all 把全部内核模块**引入编译**（Go 要求 import 才会编译进来）。
+//
+// ## 为什么这层是必要的（一个真实的 Go 约束）
+//
+// 模块各自在 init() 里 `kernelmod.Register(...)`，但必须有东西把它们
+// 引进来。若把 import 写在 `kernelmod/core.go` 里：
+//
+//	core.go import lua/  ⇒ core → lua → core（lua 要调 Register 必须 import core）
+//	⇒ **循环导入**，Go 禁止
+//
+// 所以注册表 API 在 `kernelmod` 包，模块 import 它（单向），
+// 而"引进来"的清单放在**本子包**（`kernelmod/all`）—— 它 import 两者。
+//
+// ## 加一个新模块要做什么（**唯一的一处编辑**）
+//
+//	① 新建 internal/kernelmod/<name>/mod.go，实现 kernelboot.Module
+//	② 在**本文件**加一行空白 import
+//
+// 依赖写在模块自己的 Requires() 里 —— **没有**中央依赖清单。
+package all
+
+import (
+	// 每个模块一个独立文件夹（用户设计）。
+	//
+	// ★ 顺序**无关**：模块注册顺序由 init() 决定，而注册表刻意乱序
+	// （见 kernelmod/core.go）。真正的先后只由 Requires/Provides 决定。
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/agent"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/config"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/docstore"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/kernelapi"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/knowledge"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/llm"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/lua"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/memory"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/migration"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/multimodal"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/onnx"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/pluginhost"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/stagehost"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/supervisor"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/textmem"
+	_ "github.com/JianFeeeee/HomeAgent/internal/kernelmod/tracker"
+)
diff --git a/internal/kernelmod/all/facilities_sync_test.go b/internal/kernelmod/all/facilities_sync_test.go
new file mode 100644
index 00000000..85e6406b
--- /dev/null
+++ b/internal/kernelmod/all/facilities_sync_test.go
@@ -0,0 +1,112 @@
+package all
+
+// 设施名「内核 ↔ 公开 SDK」一致性判据（2026-10-16）。
+//
+// ## 为什么需要它
+//
+// 设施名同时存在于**两处**，且必须逐字一致：
+//
+//	内核：internal/kernelmod/facilities.go   （模块 Provides 用）
+//	SDK：third_party/homeagent-sdk/sdk/facilities.go （插件声明用）
+//
+// 它们**不能合并**：SDK 是独立发布的模块（外部插件依赖它），
+// 而内核的 internal 规则又禁止内部包被外部 import。
+//
+// ⇒ 两处并存 ⇒ 有漂移风险。**改一处忘另一处**的后果是：
+// 插件按 SDK 声明的名字，内核从未注册 ⇒ 插件**永不启动**，且（在本判据
+// 与运行期校验出现前）无任何报错。
+//
+// 本判据把"两边一致"变成可执行的检查。
+//
+// ## 为什么必须从**源码**提取而不是手写清单
+//
+// 手写清单在"新增了一个设施名但只改了内核"时**也不会包含新名字**
+// ⇒ 判据照样绿（守卫形同虚设）。本仓已有先例
+// （TestCapability_AllMethodsClassified 初版就是这个毛病）。
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"testing"
+)
+
+// internalOnlyFacilities 是**内核内部**顺序标记（不是给插件的契约）。
+//
+// ★ 判据要排除它们：它们的消费者是内核模块，不该进公开 SDK。
+// 若把它们也拿去比对，会得到"内核有但 SDK 没有"的**假红**（实测撞到：
+// knowledge-migrated）。反向也要防：有人误把内部标记放进 SDK 当对外契约。
+var internalOnlyFacilities = map[string]bool{
+	"knowledge-migrated": true,
+}
+
+// extractFacilities 从 Go 源码里提取 `FacilityXxx = "值"` 形式的常量。
+func extractFacilities(t *testing.T, path string) map[string]string {
+	t.Helper()
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("读 %s: %v", path, err)
+	}
+	re := regexp.MustCompile(`(?m)^\s*(Fac[A-Za-z0-9_]*|Facility[A-Za-z0-9_]*)\s*=\s*"([^"]+)"`)
+	out := map[string]string{}
+	for _, m := range re.FindAllStringSubmatch(string(b), -1) {
+		out[m[1]] = m[2]
+	}
+	if len(out) < 10 {
+		t.Fatalf("只从 %s 提取到 %d 个设施常量 —— 正则或文件结构变了（判据会假绿）",
+			path, len(out))
+	}
+	return out
+}
+
+// ★★★ 判据：**内核与 SDK 的设施名值集合逐字一致**。
+func TestFacilityNamesMatchPublicSDK(t *testing.T) {
+	kernel := extractFacilities(t, filepath.Join("..", "facilities.go"))
+	sdk := extractFacilities(t, filepath.Join("..", "..", "..",
+		"third_party", "homeagent-sdk", "sdk", "facilities.go"))
+
+	kernelVals := map[string]string{} // 值 → 内核常量名
+	for name, v := range kernel {
+		if internalOnlyFacilities[v] {
+			continue // 内核内部顺序标记，不是插件契约
+		}
+		kernelVals[v] = name
+	}
+	sdkVals := map[string]string{}
+	for name, v := range sdk {
+		sdkVals[v] = name
+	}
+
+	var missingInSDK, missingInKernel []string
+	for v, name := range kernelVals {
+		if _, ok := sdkVals[v]; !ok {
+			missingInSDK = append(missingInSDK, name+"="+v)
+		}
+	}
+	for v, name := range sdkVals {
+		if _, ok := kernelVals[v]; !ok {
+			missingInKernel = append(missingInKernel, name+"="+v)
+		}
+	}
+	sort.Strings(missingInSDK)
+	sort.Strings(missingInKernel)
+
+	if len(missingInSDK) > 0 {
+		t.Errorf("★ 内核有但**公开 SDK 没有**的设施名: %v\n"+
+			"   后果：插件作者无法 import 该常量（只能照文档抄 ⇒ 易拼错），"+
+			"且打包期校验会把它当'未知设施名'而拒绝", missingInSDK)
+	}
+	for v := range sdkVals {
+		if internalOnlyFacilities[v] {
+			t.Errorf("★ 公开 SDK 里出现了内核**内部顺序标记** %q —— "+
+				"它的消费者是内核模块，不该成为插件契约（插件声明它没有意义，"+
+				"且会误导作者以为可用）", v)
+		}
+	}
+	if len(missingInKernel) > 0 {
+		t.Errorf("★ 公开 SDK 有但**内核没有**的设施名: %v\n"+
+			"   后果：插件按此声明 ⇒ 内核从未注册 ⇒ 插件**永不启动**（静默）",
+			missingInKernel)
+	}
+}
diff --git a/internal/kernelmod/all/registry_test.go b/internal/kernelmod/all/registry_test.go
new file mode 100644
index 00000000..2710bbc4
--- /dev/null
+++ b/internal/kernelmod/all/registry_test.go
@@ -0,0 +1,351 @@
+package all
+
+// 内核模块注册表 + 分层的判据（2026-10-16）。
+//
+// 设计见 docs/zh/kernel-modularization-design.md §2.3/§2.6/§2.8。
+//
+// ## 用户的验收标准（必须被判据钉住）
+//
+// > 模块应该在 /modelname/ 独立文件夹下，根目录只有 core.go，
+// > core 内有一个注册表注册各个模块 … 注意注册表中的模块列表是乱序的
+//
+// ⇒ 四条底线：
+//   ① 每个模块**独立文件夹**
+//   ② 依赖写在**模块自己**的 Requires() 里（无中央依赖清单）
+//   ③ 注册表列表**乱序**（顺序无意义，不能被依赖）
+//   ④ 第 0 层模块**不依赖任何模块**（"core 不依赖任何模块"字面成立）
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+)
+
+// ★★★ 判据：**依赖图可建 + 模块全登记 + 无重复**。
+func TestRegistryBuildsValidGraph(t *testing.T) {
+	if d := kernelmod.Duplicates(); len(d) > 0 {
+		t.Fatalf("★ 模块名重复注册: %v（两个模块同名，或一个模块被导入两次）", d)
+	}
+	mods := kernelmod.Registered()
+	if len(mods) < 10 {
+		t.Fatalf("★ 只登记 %d 个模块 —— 可能有模块漏了 init() 注册", len(mods))
+	}
+	plan, err := kernelboot.Build(mods)
+	if err != nil {
+		t.Fatalf("★ 依赖图无解（结构错误）: %v", err)
+	}
+	total := 0
+	for _, l := range plan.Layers {
+		total += len(l)
+	}
+	if total != len(mods) {
+		t.Fatalf("★ 分层丢失模块: %d != %d", total, len(mods))
+	}
+}
+
+// ★★★ 判据（用户验收标准 ④）：**第 0 层不依赖任何模块**。
+func TestFirstLayerHasNoDependencies(t *testing.T) {
+	plan, err := kernelboot.Build(kernelmod.Registered())
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, m := range plan.Layers[0] {
+		if len(m.Requires()) != 0 {
+			t.Errorf("★ 第 0 层模块 %s 有依赖 %v —— 分层正确的话不该有",
+				m.Name(), m.Requires())
+		}
+	}
+	names := map[string]bool{}
+	for _, m := range plan.Layers[0] {
+		names[m.Name()] = true
+	}
+	for _, want := range []string{"config", "kernel-api"} {
+		if !names[want] {
+			t.Errorf("★ %s 应在第 0 层（它不依赖任何模块）", want)
+		}
+	}
+}
+
+// ★★★ 判据（用户验收标准 ①②）：**每模块独立文件夹；依赖写在自己文件里**。
+func TestEachModuleInOwnFolder(t *testing.T) {
+	root := ".."
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	modDirs := 0
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		modDirs++
+		files, _ := filepath.Glob(filepath.Join(root, e.Name(), "*.go"))
+		if len(files) == 0 {
+			t.Errorf("★ 模块目录 %s 下没有 .go 文件", e.Name())
+		}
+	}
+	if modDirs < 10 {
+		t.Fatalf("★ 只找到 %d 个模块目录（期望 ≥10）", modDirs)
+	}
+
+	// ② 依赖不能出现在"中央清单"里：根目录只有 core.go/facilities.go/all 子包
+	for _, f := range []string{"core.go", "facilities.go"} {
+		b, err := os.ReadFile(filepath.Join(root, f))
+		if err != nil {
+			continue
+		}
+		src := string(b)
+		if strings.Contains(src, "Requires() []string { return []string{") {
+			t.Errorf("★ %s 里出现了具体的 Requires —— 依赖应写在各模块自己的文件里", f)
+		}
+	}
+}
+
+// ★★★ 判据（用户验收标准 ③）：**注册表列表乱序**（顺序无意义，不能被依赖）。
+//
+// ★ 怎么测"乱序"：注册顺序由 init() 决定。这里断言 Names() 的顺序
+// **不等于**按名字排序的顺序 —— 若相等，说明有人给它排过序，
+// 那会给使用者"这个顺序有意义"的错觉（用户明确要求乱序）。
+//
+// ⚠ 注意：这条是**性质检查**，不是绝对的（init 顺序恰好等于字典序时也会通过
+// 排序检查）。所以真正守"顺序无意义"的是**文档 + 分层器内部排序**，
+// 而本判据是"如果有人显式排序就报红"的报警器。
+func TestRegistryOrderIsNotMeaningful(t *testing.T) {
+	names := kernelmod.Names()
+	if len(names) < 2 {
+		t.Fatal("模块太少")
+	}
+	sorted := append([]string(nil), names...)
+	sort.Strings(sorted)
+	if strings.Join(names, ",") == strings.Join(sorted, ",") {
+		t.Logf("提示：注册顺序恰好等于字典序（不必然是错误，但请确认没有人"+
+			"给注册表排序——顺序无意义是设计的一部分）: %v", names)
+	}
+	// 核心断言：Registered() 返回的列表**不得**按依赖序排列
+	// （即：不能有人把"启动顺序"写进注册表）
+	plan, err := kernelboot.Build(kernelmod.Registered())
+	if err != nil {
+		t.Fatal(err)
+	}
+	var layerOrder []string
+	for _, l := range plan.Layers {
+		for _, m := range l {
+			layerOrder = append(layerOrder, m.Name())
+		}
+	}
+	if strings.Join(names, ",") == strings.Join(layerOrder, ",") {
+		t.Fatal("★ 注册表顺序恰好等于**依赖分层序** —— 说明注册表被用来表达启动顺序了，" +
+			"那正是要消灭的隐式顺序依赖（用户要求注册表乱序）")
+	}
+}
+
+// ★★★ 判据：**关键顺序被依赖图保证**（每条都来自真实约束）。
+func TestLayeringPreservesCriticalOrder(t *testing.T) {
+	plan, err := kernelboot.Build(kernelmod.Registered())
+	if err != nil {
+		t.Fatal(err)
+	}
+	layerOf := map[string]int{}
+	for i, l := range plan.Layers {
+		for _, m := range l {
+			layerOf[m.Name()] = i
+		}
+	}
+	cases := []struct{ a, b, why string }{
+		{"config", "lua", "initLuaVM(cfg) 收 cfg"},
+		{"lua", "llm", "initLLMProviders 收 luaVM"},
+		{"config", "memory", "initMemoryStack 收 cfgReg"},
+		{"knowledge-migration", "knowledge-store", "迁移必须早于 store 扫盘"},
+		{"llm", "stage-host", "newStageAndRegistry 收 providerMgr"},
+		{"memory", "stage-host", "newStageAndRegistry 收 mem.db"},
+		{"stage-host", "agent", "newMainAgent 收 stageHost"},
+		{"llm", "agent", "newMainAgent 收 provider"},
+		{"memory", "agent", "newMainAgent 收 mem.db"},
+		{"tracker", "agent", "newMainAgent 收 trk"},
+	}
+	for _, c := range cases {
+		la, ok1 := layerOf[c.a]
+		lb, ok2 := layerOf[c.b]
+		if !ok1 || !ok2 {
+			t.Errorf("模块缺失: %s=%v %s=%v", c.a, ok1, c.b, ok2)
+			continue
+		}
+		if la >= lb {
+			t.Errorf("★ %s 应在 %s 之前（%s），实际层号 %d >= %d", c.a, c.b, c.why, la, lb)
+		}
+	}
+}
+
+// ★★★ 判据：**text-memory 显式依赖 onnx-parser**（隐藏依赖，见 textmem 包注释）。
+//
+// ★ 不能用层号断言：text-memory 已因 memory 被推到第 2 层，
+// 而 onnx-parser 在第 1 层 ⇒ 删掉依赖后层号依然满足。必须断言**声明本身**。
+func TestHiddenDependencyOnnxDeclared(t *testing.T) {
+	src := readMod(t, filepath.Join("..", "textmem", "mod.go"))
+	if !strings.Contains(src, "FacONNX") {
+		t.Fatal("★ text-memory 未声明对 onnx-parser 的依赖 —— " +
+			"它在运行期读 nlp.defaultParser（onnx 模块写的包级单例）。" +
+			"当前靠 distillLoop 的 Interval=10min 碰巧安全；" +
+			"Interval 变小或解析器装配更后 ⇒ 静默降级（图记忆实体退化成整句复合值）")
+	}
+}
+
+// ★★★ 判据：**分层带来并行**（对照原 17 步串行）。
+func TestLayeringYieldsParallelism(t *testing.T) {
+	mods := kernelmod.Registered()
+	plan, err := kernelboot.Build(mods)
+	if err != nil {
+		t.Fatal(err)
+	}
+	maxLayer := 0
+	for _, l := range plan.Layers {
+		if len(l) > maxLayer {
+			maxLayer = len(l)
+		}
+	}
+	if len(plan.Layers) >= len(mods) {
+		t.Fatalf("★ 无并行度（%d 层 / %d 模块）", len(plan.Layers), len(mods))
+	}
+	t.Logf("并行度: %d 层 / %d 模块，最宽层 %d 个", len(plan.Layers), len(mods), maxLayer)
+}
+
+func readMod(t *testing.T, path string) string {
+	t.Helper()
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("读 %s: %v", path, err)
+	}
+	return string(b)
+}
+
+// ★★★ 判据：**每个模块目录都被 import 引入**（漏 import ⇒ 模块静默消失）。
+//
+// ## ★ 这条是变异测试发现的**真实覆盖漏洞**
+//
+// 我删掉 `all.go` 里 `multimodal` 的 import 后，**全部判据仍然通过** ——
+// 因为：
+//
+//	· 依赖图仍然解得开（multimodal **没有下游依赖**，没人需要它）
+//	· 注册表数量检查只有 `>= 10` 这种下限（少一个不报）
+//
+// 后果：**多模态能力凭空消失**，而启动照常成功、无任何报错。
+// 这与本仓反复吃亏的"静默降级"是同一形态：
+//
+//	· 漏 import 插件包 ⇒ 插件静默消失（已有同类教训）
+//	· 漏 import 模块包 ⇒ 模块静默消失（本条）
+//
+// ## 判据做法：**统计目录 vs 统计注册**
+//
+// 扫描 `internal/kernelmod/` 下的模块目录（含 `mod.go` 或实现 Module 的 .go
+// 文件），与注册表里的模块名比对 —— 目录有而注册表没有 ⇒ 漏 import。
+//
+// ★ 为什么不用"手写清单"：手写清单在"新增目录忘了加 import"时
+// **也不会包含新目录** ⇒ 判据照样绿（本仓已有先例）。
+func TestEveryModuleDirIsImported(t *testing.T) {
+	root := ".."
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	registered := map[string]bool{}
+	for _, n := range kernelmod.Names() {
+		registered[n] = true
+	}
+
+	// 收集"看起来是模块目录"的：含 .go 文件、且文件里有 kernelmod.Register 调用
+	var moduleDirs []string
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		name := e.Name()
+		if name == "all" {
+			continue // 这个子包是 import 清单本身
+		}
+		files, _ := filepath.Glob(filepath.Join(root, name, "*.go"))
+		hasRegister := false
+		for _, f := range files {
+			if strings.Contains(f, "_test.go") {
+				continue
+			}
+			b, err := os.ReadFile(f)
+			if err != nil {
+				continue
+			}
+			if strings.Contains(string(b), "kernelmod.Register(") {
+				hasRegister = true
+				break
+			}
+		}
+		if hasRegister {
+			moduleDirs = append(moduleDirs, name)
+		}
+	}
+	if len(moduleDirs) < 5 {
+		t.Fatalf("只找到 %d 个模块目录 —— 扫描逻辑失效（判据会假绿）", len(moduleDirs))
+	}
+
+	// 每个模块目录里的 Register(...) 参数名 → 期望的模块名
+	// （用"目录名"与"注册名"的映射，因为目录名与 Name() 不必相同）
+	dirToNames := map[string][]string{}
+	for _, d := range moduleDirs {
+		files, _ := filepath.Glob(filepath.Join(root, d, "*.go"))
+		for _, f := range files {
+			if strings.Contains(f, "_test.go") {
+				continue
+			}
+			b, _ := os.ReadFile(f)
+			// ★ 正则要容忍 gofmt 的对齐空格（列对齐会让 `{` 前有多个空格）。
+			// 初版写成 `\{ return` （单空格）⇒ 只匹配到 agent 一个，
+			// 其余全部"找不到目录"（判据假红）。实测撞到。
+			re := regexp.MustCompile(`(?m)^func \([A-Za-z0-9_]+\) Name\(\) string\s+\{ return "([^"]+)" \}`)
+			for _, m := range re.FindAllStringSubmatch(string(b), -1) {
+				dirToNames[d] = append(dirToNames[d], m[1])
+			}
+		}
+	}
+
+	var missing []string
+	for dir, names := range dirToNames {
+		if len(names) == 0 {
+			continue
+		}
+		// 该目录的**每个**模块名都必须在注册表里
+		//（一个目录可含多个模块，如 knowledge/{migration,store}）
+		anyFound := false
+		for _, n := range names {
+			if registered[n] {
+				anyFound = true
+			}
+		}
+		if !anyFound {
+			missing = append(missing, fmt.Sprintf("%s(%v)", dir, names))
+		}
+	}
+	sort.Strings(missing)
+	if len(missing) > 0 {
+		t.Fatalf("★ 这些模块目录**没有被 import 引入**（模块静默消失，启动不报错）: %v\n"+
+			"   修复：在 internal/kernelmod/all/all.go 里加空白 import", missing)
+	}
+
+	// 反向：注册表里的每个模块都应能对应到某个目录
+	known := map[string]bool{}
+	for _, ns := range dirToNames {
+		for _, n := range ns {
+			known[n] = true
+		}
+	}
+	for n := range registered {
+		if !known[n] {
+			t.Errorf("★ 注册表里的模块 %s 找不到对应目录 —— 可能是测试夹具注册的，或扫描漏了", n)
+		}
+	}
+}
diff --git a/internal/kernelmod/config/mod.go b/internal/kernelmod/config/mod.go
new file mode 100644
index 00000000..16df8ba2
--- /dev/null
+++ b/internal/kernelmod/config/mod.go
@@ -0,0 +1,43 @@
+// Package config 是 config 模块：提供配置快照（ks.Cfg）。
+//
+// ## ★ 它解决了"cfg 是无主模块"的问题
+//
+// 原先 `cfg := cfgReg.ToConfig()` 之后，cfg 是**游离的局部变量**，
+// 被手工传给 11 个 init* —— 谁需要它就靠人肉排在那一行之后。
+// 现在它住在 `ks.Cfg`，任何模块直接读即可。
+//
+// ## 依赖：图上为空，但隐含"必须在 Group 0 之后"
+//
+// 它读 core.llm.* 里的**密文** ⇒ 必须在安全块（装好密钥）之后。
+// 但这不是**图内依赖**（安全块不由任何调度模块提供；声明 crypto 会让
+// Build 报"依赖了不存在的设施"）。更本质：那是**时序**要求，不是**数据**依赖。
+//
+// ⇒ 由 Group 0 阶段保证：Group 0 串行跑完 ⇒ 才启动本调度器。
+package config
+
+import (
+	"fmt"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+)
+
+// Module 提供配置快照。
+type Module struct{}
+
+func (Module) Name() string       { return "config" }
+func (Module) Requires() []string { return nil } // 前提由 Group 0 保证
+func (Module) Provides() []string { return []string{kernelmod.FacConfig} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	// ★ 检查而不是假设（用户说的"nil 加读取前检查"）：
+	// ks.Cfg 为 nil 说明 Group 0 段没跑或顺序错了。响亮报错远好于让后续
+	// 模块拿到 nil —— 那会在很远的地方变成"模型没有配置"之类的模糊症状。
+	if ks.Cfg == nil {
+		return fmt.Errorf("config 模块：ks.Cfg 为 nil —— Group 0 必须先完成 " +
+			"`cfg := cfgReg.ToConfig()`（且必须在安全块之后，否则密文解不开 ⇒ 全 provider 401）")
+	}
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/core.go b/internal/kernelmod/core.go
new file mode 100644
index 00000000..4ed1a1ce
--- /dev/null
+++ b/internal/kernelmod/core.go
@@ -0,0 +1,141 @@
+// Package kernelmod 是内核模块的**注册表**（用户设计的 core）。
+//
+// ## 用户的设计意图（原话）
+//
+// > 模块应该在 /modelname/ 独立文件夹下，根目录只有 core.go，
+// > core 内有一个注册表注册各个模块，各个模块通过该注册表得知内核有哪些模块，
+// > 从而声明对其他模块的依赖，注意注册表中的模块列表是乱序的，
+// > 只是为了向模块展示内核注册了哪些模块
+//
+// ## 目录形状
+//
+//	internal/kernelmod/
+//	├── core.go            ← 本文件：注册表（+ 唯一的 import 清单）
+//	├── facilities.go      ← 设施名常量（模块间的协议）
+//	├── config/mod.go      ← 每个模块一个独立文件夹
+//	├── kernelapi/mod.go
+//	├── lua/mod.go
+//	├── llm/mod.go
+//	├── memory/mod.go
+//	├── supervisor/mod.go
+//	├── tracker/mod.go
+//	├── textmem/mod.go
+//	├── docstore/mod.go
+//	├── knowledge/{migration,store}.go
+//	├── multimodal/mod.go
+//	├── onnx/mod.go
+//	├── stagehost/mod.go
+//	└── agent/mod.go
+//
+// ## 职责边界（刻意做窄）
+//
+// 本文件**只做两件事**：
+//
+//	· `Register(m)` —— 模块在 init() 里自注册
+//	· `Registered()` —— 返回已注册模块（**乱序**，仅供查询"内核有哪些模块"）
+//
+// 它**不做**依赖解析/分层/执行 —— 那些是 `internal/kernelboot` 的事。
+// 分开的理由：注册表是"名册"，分层器是"调度器"。混在一起会让
+// "只想知道有哪些模块"的人被迫拉进整个调度逻辑。
+//
+// ## ★ 为什么列表是"乱序"，以及这为什么是对的
+//
+// 注册顺序取决于 **Go 的 init() 执行顺序**（由 import 图决定，
+// 规范未定义跨包的**具体**顺序）。若把注册顺序当成"可信的启动顺序"，
+// 那就是**隐式顺序依赖** —— 正是本设计要消灭的东西（§1 的病 A）。
+//
+// 所以 `Registered()` **刻意不排序**，并明确"顺序无意义"：
+//
+//	· 模块只能用它回答"内核注册了哪些模块"
+//	· **不能**用它推断先后 —— 先后只由 Requires/Provides 决定
+//
+// ★ 分层器（kernelboot.Build）内部会按名字排序以保证**结果可复现**，
+// 那是分层器的实现细节，与"注册表乱序"不矛盾。
+//
+// ## ★ 关于下面那份 import 清单（为什么必须有，且它是**唯一**的一处）
+//
+// Go 要求"包被 import 才会编译进来"。模块各自在 init() 里注册，
+// 但**必须有东西把它们引进来** —— 这就是下面那些空白导入。
+//
+// 为什么不能省（也解释了一个真实的 Go 约束）：
+//
+//	core.go 想 import lua/  ⇒ core → lua → core（lua 要调 Register）
+//	⇒ **循环导入**，Go 禁止
+//
+// 解法：注册表 API 放在**本包**、模块 import 本包（单向），
+// 而"把它们引进来"的清单只能放在**本包之外** —— 见
+// `internal/kernelmod/all/all.go`（只做 import，无逻辑）。
+//
+// ⇒ 加模块 = **加一个文件夹 + 在 all.go 加一行**（唯一的一处编辑）。
+package kernelmod
+
+import (
+	"sync"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+)
+
+var (
+	mu   sync.Mutex
+	list []kernelboot.Module
+	seen = map[string]bool{}
+	dups []string
+)
+
+// Register 由模块在自己的 init() 里调用。
+//
+// 重复注册同名模块会被**记录**（不 panic）：panic 发生在 init 阶段，
+// 栈信息对使用者毫无意义（他只想知道哪个模块重名）。由 Registered 报出。
+func Register(m kernelboot.Module) {
+	if m == nil {
+		return
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	name := m.Name()
+	if seen[name] {
+		dups = append(dups, name)
+		return
+	}
+	seen[name] = true
+	list = append(list, m)
+}
+
+// Registered 返回全部已注册模块。
+//
+// ★ **顺序无意义**（见包注释）：它取决于 init() 执行顺序。
+// 只用它回答"内核注册了哪些模块"，**不要**用它推断先后。
+func Registered() []kernelboot.Module {
+	mu.Lock()
+	defer mu.Unlock()
+	out := make([]kernelboot.Module, len(list))
+	copy(out, list)
+	return out
+}
+
+// Duplicates 返回重复注册的模块名（诊断用）。
+func Duplicates() []string {
+	mu.Lock()
+	defer mu.Unlock()
+	out := make([]string, len(dups))
+	copy(out, dups)
+	return out
+}
+
+// Names 返回已注册模块名（诊断用；顺序同 Registered，无意义）。
+func Names() []string {
+	mu.Lock()
+	defer mu.Unlock()
+	out := make([]string, 0, len(list))
+	for _, m := range list {
+		out = append(out, m.Name())
+	}
+	return out
+}
+
+// IsRegistered 报告某模块是否已注册（模块可用它判断依赖是否存在）。
+func IsRegistered(name string) bool {
+	mu.Lock()
+	defer mu.Unlock()
+	return seen[name]
+}
diff --git a/internal/kernelmod/docstore/mod.go b/internal/kernelmod/docstore/mod.go
new file mode 100644
index 00000000..9d79565f
--- /dev/null
+++ b/internal/kernelmod/docstore/mod.go
@@ -0,0 +1,37 @@
+// Package docstore 是 doc-store 模块：文档记忆（文本块 + 向量）。
+//
+// 依赖 config：`initDocStore(cfg)` 读 cfg.Daemon.DataDir。
+package docstore
+
+import (
+	"log"
+	"path/filepath"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/memory"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/document"
+)
+
+// Module 提供文档记忆。
+type Module struct{}
+
+func (Module) Name() string       { return "doc-store" }
+func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
+func (Module) Provides() []string { return []string{kernelmod.FacDocStore} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	docStore := document.NewStore(
+		filepath.Join(ks.Cfg.Daemon.DataDir, "memory", "documents"), memory.TokenizeWords)
+	if err := docStore.Start(); err != nil {
+		log.Printf("[homed] warning: document store: %v", err)
+	}
+	// 关停时落盘：文档记忆的内存态变更（迁移结果、访问计数等）只在 flush 里写盘，
+	// 而 flush 的唯一入口是 Stop() —— 此前全仓无人调用它，
+	// 于是迁移结果永不落盘、每次启动白算一遍。
+	ks.DocStore = docStore
+	ks.AddCloser(docStore.Stop)
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/facilities.go b/internal/kernelmod/facilities.go
new file mode 100644
index 00000000..a738a425
--- /dev/null
+++ b/internal/kernelmod/facilities.go
@@ -0,0 +1,46 @@
+package kernelmod
+
+// 设施名常量（依赖图上被引用的名字）。
+//
+// ★ 为何用常量而不是裸字符串：拼错依赖名时**编译不过**，
+// 而不是"永远等不到就绪"（运行期表现是静默挂起 / 静默拿到 nil，极难排查）。
+//
+// ★ 为何放在 core.go 之外：用户要求"根目录只有 core.go"，
+// 而 core.go 专注注册表职责。设施名是**模块间的协议**，与注册表分开更清晰。
+const (
+	// ── 插件可依赖的设施（与公开 SDK 的 sdk.Facility* **逐字一致**）──
+	//
+	// ★ 判据 TestFacilityNamesMatchPublicSDK 守这个一致性。
+	// 这些名字会出现在 plugin.json 的 requires_facilities 里。
+	FacConfig     = "config"
+	FacKernelIO   = "kernel-io"
+	FacMemory     = "memory"
+	FacLua        = "lua"
+	FacSupervisor = "supervisor"
+	FacTracker    = "tracker"
+	FacTextMem    = "textmem"
+	FacLLM        = "llm"
+	FacDocStore   = "docmem"
+	FacKnowledge  = "knowledge"
+	FacMultimodal = "multimodal"
+	FacONNX       = "onnx"
+	FacStageHost  = "stagehost"
+	FacAgent      = "agent"
+
+	// ── 内核**内部**顺序标记（**不是**给插件的设施）──
+	//
+	// ★ 为什么不与上面的混在一起：这两类东西的**消费者不同**。
+	//   · 上面的：插件按它声明启动时机（对外契约，必须进公开 SDK）
+	//   · 这里的：只用于**内核模块之间**表达顺序（如"迁移必须先于扫盘"）
+	//
+	// 混在一起会让"内核内部标记"被误当成"插件可选设施"
+	// ⇒ 插件可能声明它（然后永远等不到 —— 因为它的就绪时机是装配中途，
+	// 而插件提交发生在装配**完成之后**……实际会立刻满足，但语义是错的：
+	// 它不该成为插件的契约）。
+	//
+	// 判据 TestFacilityNamesMatchPublicSDK 只比对上面那组 ⇒ 天然拦住
+	// "把内部标记泄漏成对外契约"。
+
+	// FacMigrated 标记"知识库目录迁移已完成"（用于让 store 排在迁移之后）。
+	FacMigrated = "knowledge-migrated"
+)
diff --git a/internal/kernelmod/kernelapi/mod.go b/internal/kernelmod/kernelapi/mod.go
new file mode 100644
index 00000000..5e7940e8
--- /dev/null
+++ b/internal/kernelmod/kernelapi/mod.go
@@ -0,0 +1,35 @@
+// Package kernelapi 是 kernel-api 模块：IOManager + EventBus。
+//
+// ## 依赖：**真无依赖**
+//
+// `initKernelAPI()` 不收任何参数 ⇒ 它与 config 并列第 0 层。
+// 这条"真无依赖"是有意的：让"最先初始化的 core 不依赖任何模块"
+// 在代码里**字面成立**。
+package kernelapi
+
+import (
+	"log"
+
+	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	"github.com/JianFeeeee/HomeAgent/internal/events"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+)
+
+// Module 提供 IO 抽象层与事件总线。
+type Module struct{}
+
+func (Module) Name() string       { return "kernel-api" }
+func (Module) Requires() []string { return nil }
+func (Module) Provides() []string { return []string{kernelmod.FacKernelIO} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	iom := agentIO.NewIOManager()
+	evBus := events.NewBus()
+	log.Printf("[homed] kernel API ready: IOManager + EventBus")
+	ks.IO = iom
+	ks.EventBus = evBus
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/knowledge/migrate_impl.go b/internal/kernelmod/knowledge/migrate_impl.go
new file mode 100644
index 00000000..374ba4d1
--- /dev/null
+++ b/internal/kernelmod/knowledge/migrate_impl.go
@@ -0,0 +1,53 @@
+package knowledge
+
+import (
+	"log"
+
+	"github.com/JianFeeeee/HomeAgent/internal/knowledge"
+)
+
+// runKnowledgeMigration 是本迁移的真实实现（原 cmd/homed 的整块平移：
+// 语句、日志文本、错误语义不变，只把 cfg 参数换成 root）。
+func runKnowledgeMigration(root string) {
+	const (
+		// defaultApply = false ⇒ 启动时只扫描并报告，不改名。
+		defaultApply = false
+		// maxRenamePerRun 限制单次重命名数：给失控的目录规模设上限，
+		// 避免启动阶段被一次大迁移拖住。
+		maxRenamePerRun = 200
+	)
+	items, err := knowledge.PlanMigration(root)
+	if err != nil {
+		log.Printf("[homed] 知识库迁移扫描失败（跳过）: %v", err)
+		return
+	}
+	need, illegal := 0, 0
+	for _, it := range items {
+		if it.Illegal {
+			illegal++
+		} else if it.NewName != "" {
+			need++
+		}
+	}
+	if need == 0 && illegal == 0 {
+		return
+	}
+	if illegal > 0 {
+		log.Printf("[homed] 知识库迁移：%d 条名称非法（含 .. / 点段 / 隐藏段），写入与删除均已拒绝，需人工处理", illegal)
+	}
+	if need == 0 {
+		return
+	}
+	log.Printf("[homed] 知识库迁移：%d/%d 条目录名待规范化（例：%s → %s）", need, len(items),
+		items[0].OldName, items[0].NewName)
+	if !defaultApply {
+		log.Printf("[homed] 知识库迁移：当前为只报告模式。确认清单后执行：homed-kb-migrate -root %s -apply", root)
+		return
+	}
+	if need > maxRenamePerRun {
+		log.Printf("[homed] 知识库迁移：需改名 %d 条超过单次上限 %d，本次只处理前 %d 条",
+			need, maxRenamePerRun, maxRenamePerRun)
+	}
+	applied, failed := knowledge.ApplyMigration(root, items, maxRenamePerRun)
+	log.Printf("[homed] 知识库迁移完成：成功 %d，失败 %d", applied, failed)
+}
diff --git a/internal/kernelmod/knowledge/migration.go b/internal/kernelmod/knowledge/migration.go
new file mode 100644
index 00000000..fcc282fb
--- /dev/null
+++ b/internal/kernelmod/knowledge/migration.go
@@ -0,0 +1,36 @@
+// 知识库目录改名迁移（幂等）。**独立模块**，见下。
+//
+// ## ★ 为什么迁移必须是独立模块而不是 store 里的一行
+//
+// 原 main 注释："迁移必须在 store 扫盘**之前**：改名后扫盘一次到位，
+// 避免先以旧名建索引、再改名造成内存键与盘上目录短暂不一致"。
+//
+// 这是**真实的顺序约束**（不是副作用顺序，是"必须先改名再扫盘"）⇒
+// 在依赖图上是知识库 store 的前置。声明成依赖 ⇒ 分层器保证它们**不同层**
+// （同层就是并行了，那会破坏约束）。
+//
+// ★ 若把迁移并进 store 的 Init 里，这个约束就"藏在函数体内"了 ——
+// 那正是"加模块必须调顺序"的病根形态。
+package knowledge
+
+import (
+	"path/filepath"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+)
+
+// MigrationModule 做知识库目录改名迁移。
+type MigrationModule struct{}
+
+func (MigrationModule) Name() string       { return "knowledge-migration" }
+func (MigrationModule) Requires() []string { return []string{kernelmod.FacConfig} }
+func (MigrationModule) Provides() []string { return []string{kernelmod.FacMigrated} }
+
+func (MigrationModule) Init(ks *kernelboot.KernelState) error {
+	root := filepath.Join(ks.Cfg.Daemon.DataDir, "knowledge")
+	runKnowledgeMigration(root)
+	return nil
+}
+
+func init() { kernelmod.Register(MigrationModule{}) }
diff --git a/internal/kernelmod/knowledge/store.go b/internal/kernelmod/knowledge/store.go
new file mode 100644
index 00000000..45fbc45c
--- /dev/null
+++ b/internal/kernelmod/knowledge/store.go
@@ -0,0 +1,33 @@
+// 知识库 store 模块。
+package knowledge
+
+import (
+	"log"
+	"path/filepath"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/knowledge"
+)
+
+// StoreModule 提供知识库。
+type StoreModule struct{}
+
+func (StoreModule) Name() string { return "knowledge-store" }
+func (StoreModule) Requires() []string {
+	// ★ FacMigrated 是**刻意的顺序依赖**：迁移必须早于扫盘（见 migration.go）。
+	return []string{kernelmod.FacConfig, kernelmod.FacMigrated}
+}
+func (StoreModule) Provides() []string { return []string{kernelmod.FacKnowledge} }
+
+func (StoreModule) Init(ks *kernelboot.KernelState) error {
+	ks.Knowledge = knowledge.NewStore(filepath.Join(ks.Cfg.Daemon.DataDir, "knowledge"))
+	if err := ks.Knowledge.Start(); err != nil {
+		log.Printf("[homed] warning: knowledge store: %v", err)
+	} else {
+		log.Printf("[homed] knowledge store active with %d items", len(ks.Knowledge.List()))
+	}
+	return nil
+}
+
+func init() { kernelmod.Register(StoreModule{}) }
diff --git a/internal/kernelmod/llm/mod.go b/internal/kernelmod/llm/mod.go
new file mode 100644
index 00000000..ab0a060b
--- /dev/null
+++ b/internal/kernelmod/llm/mod.go
@@ -0,0 +1,89 @@
+// Package llm 是 llm 模块：多源 Provider 管理（经 Lua 适配器做协议转换）。
+//
+// 依赖 config + lua：`initLLMProviders(cfg, luaVM, baseAPIKey)`。
+package llm
+
+import (
+	"log"
+	"os"
+
+	"github.com/JianFeeeee/HomeAgent/internal/agent/api"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	luapkg "github.com/JianFeeeee/HomeAgent/internal/lua"
+	"github.com/JianFeeeee/HomeAgent/pkg/types"
+)
+
+// Module 提供多源 provider 管理。
+type Module struct{}
+
+func (Module) Name() string       { return "llm" }
+func (Module) Requires() []string { return []string{kernelmod.FacConfig, kernelmod.FacLua} }
+func (Module) Provides() []string { return []string{kernelmod.FacLLM} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	// ★ 敏感信息防火模块的装配点。
+	//
+	// 原 main 注释："必须在任何 provider 注册之前装配"—— provider 的出向
+	// 装饰器在 ProviderManager.Register 里读 security.Global()。装配晚了，
+	// 先注册的那批 provider 就没被装饰（静默漏掉一条出网路径）。
+	//
+	// 实测：该装配**就在 initLLMProviders 内部**（不是 main 的独立语句）
+	// ⇒ 声明式下它天然"紧邻"，不再依赖 main 里那两行的相对位置。
+	ks.BaseAPIKey = resolveBaseAPIKey(ks.Cfg)
+	ks.LLMManager = buildProviderManager(ks.Cfg, ks.LuaVM, ks.BaseAPIKey)
+	ks.LLMProvider = ks.LLMManager.Default()
+	return nil
+}
+
+// buildProviderManager 按配置注册全部 LLM 源（原 cmd/homed 的整块平移）。
+func buildProviderManager(cfg *types.Config, luaVM *luapkg.VM, baseAPIKey string) *api.ProviderManager {
+	providerMgr := api.NewProviderManager()
+	adapterConcurrency := map[string]int{}
+	for _, src := range cfg.LLM.Sources {
+		if !api.IsValidSourceConfig(src.Name, src.BaseURL, src.Model, src.Adapter) {
+			log.Printf("[homed] skip invalid llm source %q (base_url=%q model=%q adapter=%q)",
+				src.Name, src.BaseURL, src.Model, src.Adapter)
+			continue
+		}
+		key := src.APIKey
+		if key == "" {
+			key = baseAPIKey
+		}
+		luaProvider := api.NewLuaAdaptedProvider(api.BaseConfig{
+			Model:         src.Model,
+			BaseURL:       src.BaseURL,
+			APIKey:        key,
+			Temperature:   cfg.LLM.Temperature,
+			MaxTokens:     cfg.LLM.MaxTokens,
+			ContextWindow: src.ContextWindow,
+			MaxConcurrent: src.MaxConcurrent,
+			Priority:      src.Priority,
+			Vision:        src.Vision,
+			Audio:         src.Audio,
+		}, luaVM, src.Name, src.Adapter)
+		providerMgr.Register(src.Name, luaProvider)
+		if src.Adapter != "" {
+			adapterConcurrency[src.Adapter] += src.MaxConcurrent
+		}
+	}
+	luaVM.ConfigureConcurrency(adapterConcurrency)
+	if cfg.LLM.Provider != "" {
+		providerMgr.SetDefault(cfg.LLM.Provider)
+	}
+	return providerMgr
+}
+
+// resolveBaseAPIKey 决定基础 key（配置 > LLM_API_KEY > DEEPSEEK_API_KEY）。
+func resolveBaseAPIKey(cfg *types.Config) string {
+	apiKey := cfg.LLM.APIKey
+	if apiKey == "" {
+		apiKey = os.Getenv("LLM_API_KEY")
+	}
+	if apiKey == "" {
+		apiKey = os.Getenv("DEEPSEEK_API_KEY")
+	}
+	return apiKey
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/lua/mod.go b/internal/kernelmod/lua/mod.go
new file mode 100644
index 00000000..4192db32
--- /dev/null
+++ b/internal/kernelmod/lua/mod.go
@@ -0,0 +1,34 @@
+// Package lua 是 lua 模块：Lua VM（LLM 协议适配）。
+//
+// 依赖 config：`initLuaVM(cfg)` 读 cfg.Daemon.DataDir（adapter 目录）。
+package lua
+
+import (
+	"log"
+	"path/filepath"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	luapkg "github.com/JianFeeeee/HomeAgent/internal/lua"
+)
+
+// Module 提供 Lua 协议适配 VM。
+type Module struct{}
+
+func (Module) Name() string       { return "lua" }
+func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
+func (Module) Provides() []string { return []string{kernelmod.FacLua} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	luaVM := luapkg.NewVM(filepath.Join(ks.Cfg.Daemon.DataDir, "adapters"))
+	if err := luaVM.Start(); err != nil {
+		log.Printf("[homed] warning: lua vm init failed: %v", err)
+		ks.LuaVM = luaVM
+		return nil // 与原语义一致：起不来只告警，仍交回实例
+	}
+	ks.LuaVM = luaVM
+	ks.AddCloser(luaVM.Stop)
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/memory/distiller_wiring_test.go b/internal/kernelmod/memory/distiller_wiring_test.go
new file mode 100644
index 00000000..8e780582
--- /dev/null
+++ b/internal/kernelmod/memory/distiller_wiring_test.go
@@ -0,0 +1,85 @@
+package memory
+
+// 蒸馏器接线回归判据（从 cmd/homed/bootstrap_test.go 迁移而来）。
+//
+// ## 为什么这条判据必须存在（历史 bug）
+//
+// `main()` 拆分时，initMemoryStack 函数体内残留一句 `defer distiller.Stop()`，
+// 函数一 return 就 cancel 掉刚启动的循环 ⇒ **规则蒸馏 10min 心跳从不运行**。
+//
+// ★ 该缺陷**不会让任何单测变红** —— pipeline 的 `TestDistillOnce*` 直接调
+// `distillOnce`，**绕过了 Start/Stop 接线**。只有按「启动阶段函数」的真实
+// 调用方式断言（调用 → 检查仍在跑 → 调 cleanup → 检查已停），才照得出来。
+//
+// ## 迁移说明
+//
+// 本判据原先针对 `cmd/homed` 的 `initMemoryStack`。模块化后该逻辑搬进
+// `internal/kernelmod/memory.Module.Init`，所以判据跟着搬 —— 且**必须保留**：
+// 迁移过程中"忘了 AddCloser"或"改成 defer"是同一类缺陷的新形态。
+//
+// 判据改为直接跑真实模块（经 kernelboot.Run），确保测的是**真实入口**。
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+)
+
+// ★★★ 判据：模块 Init 返回后蒸馏器**仍在运行**（无 defer Stop 残留）。
+func TestMemoryModuleKeepsDistillerRunning(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "memory"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// ★ 需要真 cfgReg：memory 模块读 core.agent.embedding_model_path，
+	// 而它对 nil 会现在**明确报错**（而不是 panic 在 strings.Split）。
+	reg := internalConfig.NewConfigRegistry(filepath.Join(dir, "config.db"))
+	defer reg.Close()
+	ks := &kernelboot.KernelState{DataDir: dir, CfgReg: reg}
+
+	if err := (Module{}).Init(ks); err != nil {
+		t.Fatalf("memory 模块 Init: %v", err)
+	}
+	if ks.Memory == nil || ks.Memory.Distiller == nil {
+		t.Fatal("memory 模块未产出蒸馏器")
+	}
+	if ks.Memory.DB == nil {
+		t.Skip("图库未初始化，无法验证蒸馏接线")
+	}
+	// ★ 关键断言：Init 已返回，蒸馏循环必须还在跑
+	if ks.Memory.Distiller.Stopped() {
+		t.Fatal("★ memory 模块 Init 返回后蒸馏循环已被停掉" +
+			"（defer Stop 残留？）—— 规则蒸馏 10min 心跳将从不运行")
+	}
+
+	// 关闭函数是唯一的停机点（经 AddCloser 登记，由 KernelState.CloseAll 逆序执行）
+	if err := ks.CloseAll(); err != nil {
+		t.Fatalf("CloseAll: %v", err)
+	}
+	if !ks.Memory.Distiller.Stopped() {
+		t.Fatal("CloseAll 之后蒸馏器应已停止（关闭函数未登记？）")
+	}
+}
+
+// ★★★ 判据：**关闭函数经 AddCloser 登记**（不是 defer）。
+//
+// 这是上一条的机制保证：若有人把 AddCloser 改回 defer，
+// 上一条判据报红；本判据报"没登记"，两条互相印证、定位更快。
+func TestMemoryModuleRegistersCloser(t *testing.T) {
+	dir := t.TempDir()
+	os.MkdirAll(filepath.Join(dir, "memory"), 0o755)
+	reg := internalConfig.NewConfigRegistry(filepath.Join(dir, "config.db"))
+	defer reg.Close()
+	ks := &kernelboot.KernelState{DataDir: dir, CfgReg: reg}
+	if err := (Module{}).Init(ks); err != nil {
+		t.Fatal(err)
+	}
+	// 内存模块应恰好登记 1 个关闭函数（停蒸馏器 + 关图库，合在一个闭包里）
+	if len(ks.Closers) != 1 {
+		t.Fatalf("★ 应登记 1 个关闭函数，实际 %d —— "+
+			"若为 0 说明改成了 defer（Init 返回即停机）", len(ks.Closers))
+	}
+}
diff --git a/internal/kernelmod/memory/mod.go b/internal/kernelmod/memory/mod.go
new file mode 100644
index 00000000..08648dfa
--- /dev/null
+++ b/internal/kernelmod/memory/mod.go
@@ -0,0 +1,149 @@
+// Package memory 是 memory 模块：图记忆 + 索引 + 社交图 + 蒸馏管线 + 共享词嵌入。
+//
+// ## 为什么依赖 kernel-io
+//
+// 本模块产出 MemoryBundle（4 个同生共死的东西打包）。它**不**直接读 IO，
+// 但"记忆子系统就绪"在语义上包含它后续要被候选消费管线使用，而那条管线需要 iom。
+//
+// ★ 这是**刻意声明**的依赖（不是签名要求的）：让"记忆子系统在 IO 就绪后才建"
+// 成为结构保证 —— 若将来 initMemoryStack 内部要用 iom，不会因为"忘了声明"
+// 而静默拿 nil。
+package memory
+
+import (
+	"fmt"
+	"log"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/JianFeeeee/HomeAgent/internal/config"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/memory"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/distill"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/pipeline"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/social"
+	"github.com/JianFeeeee/HomeAgent/pkg/generation"
+)
+
+// Module 提供图记忆子系统。
+type Module struct{}
+
+func (Module) Name() string       { return "memory" }
+func (Module) Requires() []string { return []string{kernelmod.FacKernelIO} }
+func (Module) Provides() []string { return []string{kernelmod.FacMemory} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	// ★ 读取前检查（用户指定的做法："结构体成员初始置 nil 加读取前检查"）。
+	//
+	// 为何要检查 CfgReg：它是 **Group 0** 的产物（不由任何调度模块提供），
+	// 所以不可能通过 Requires 声明它 —— 依赖图保证不了它非 nil。
+	// 而上面那行 `ks.CfgReg.GetString(...)` 在 nil 时会**panic**，
+	// 栈信息指向 strings.Split 之类无关处，排查成本高。
+	if ks.CfgReg == nil {
+		return fmt.Errorf("memory 模块：ks.CfgReg 为 nil —— " +
+			"Group 0 必须先建好配置中心（NewConfigRegistry）再启动本调度器")
+	}
+	if ks.DataDir == "" {
+		return fmt.Errorf("memory 模块：ks.DataDir 为空 —— 它是 Group 0 的产物，必须先设置")
+	}
+	memDB, err := memory.NewGraphDB(filepath.Join(ks.DataDir, "memory", "graph.db"))
+	if err != nil {
+		log.Printf("[homed] warning: memory init failed: %v", err)
+		memDB = nil
+	} else {
+		log.Printf("[homed] graph memory initialized")
+	}
+	memIdx := memory.NewIndexer(memDB)
+	memIdx.Sync() // 启动时立即同步，避免前 30 分钟空窗
+	socialStore := social.New(memDB)
+
+	distiller := pipeline.NewDistiller(memDB, ks.DataDir, pipeline.DistillerConfig{
+		Interval:      10 * time.Minute,
+		RetentionDays: 7,
+		BatchSize:     50,
+	})
+	// ★ 必须在 distiller.Start() **之前**注入：Start 会起 distillLoop，
+	// 而第一次 tick 在 Interval 之后。若先 Start 再注入，头一个周期
+	// （实测配置 10 分钟）会白跑一次 jieba 路 —— 而那条路实测产出 0 条。
+	if memDB != nil {
+		distiller.SetSplitter(initDistillSplitter(ks.CfgReg))
+	}
+	if memDB != nil {
+		// 这里**故意不写 defer distiller.Stop()**：函数 return 即触发 defer，
+		// 而 Stop() → cancel() 会让刚启动的 distillLoop 立刻退出，
+		// 规则蒸馏管线启动即死、10min 心跳从不运行（旧 main() 拆分时的残留）。
+		// 停机由 AddCloser 负责（见下方）。
+		distiller.Start()
+	}
+
+	ks.Memory = &kernelboot.MemoryBundle{
+		DB:        memDB,
+		Indexer:   memIdx,
+		Social:    socialStore,
+		Distiller: distiller,
+	}
+	// 共享词嵌入：蒸馏与 Agent 上下文复用同一实例
+	// （避免同一模型被二次加载，约 200k×300 维 ≈ 数百 MB）。
+	ks.Embedder = memory.NewStaticEmbedder(
+		strings.Split(ks.CfgReg.GetString("core.agent.embedding_model_path", ""), ",")...)
+	distiller.SetEmbedder(ks.Embedder)
+
+	// ★ 伪关机登记（迁移数据目录用，见 kernelboot/lifecycle.go）。
+	// 只登记**持有写句柄**的 distiller —— 它每 10min 写 memory/graph.db，
+	// 迁移期间一旦写入就会搬走"写了一半的库"。
+	if ks.Memory != nil && ks.Memory.Distiller != nil {
+		ks.AddQuiescer("distiller",
+			func() error { return ks.Memory.Distiller.Pause() },
+			func() error { return ks.Memory.Distiller.Resume() })
+	}
+
+	ks.AddCloser(func() {
+		// 与原 main 的两个 defer 同序（LIFO）：先停蒸馏器，再关图库。
+		if memDB != nil {
+			distiller.Stop()
+			memDB.Close()
+		}
+	})
+	return nil
+}
+
+// initDistillSplitter 按配置打开蒸馏用的生成侧 provider 并组装拆分器。
+//
+// 返回 nil 表示不启用（未配置 provider、或打开失败）—— 此时蒸馏回退既有的
+// jieba/ONNX 路。**不因为模型不可用而让蒸馏停摆**：那条路虽然实测产出 0 条，
+// 但它至少不会让对话记忆丢失。
+func initDistillSplitter(cfgReg *config.ConfigRegistry) pipeline.RecordSplitter {
+	if cfgReg == nil {
+		return nil
+	}
+	providerName := cfgReg.GetString("core.memory.distill.generation.provider", "")
+	if providerName == "" {
+		return nil
+	}
+	opts := map[string]string{}
+	const optPrefix = "core.memory.distill.generation.options."
+	for _, key := range cfgReg.List(optPrefix) {
+		opts[strings.TrimPrefix(key, optPrefix)] = cfgReg.GetString(key, "")
+	}
+	provider, err := generation.Open(providerName, generation.Config{Options: opts})
+	if err != nil {
+		log.Printf("[homed] warning: 蒸馏生成 provider %q 打开失败: %v（蒸馏回退 jieba 路；已注册: %s）",
+			providerName, err, strings.Join(generation.Names(), ", "))
+		return nil
+	}
+	if !provider.Info().SupportsJSONSchema {
+		// 拆分器的零幻觉完全依赖 schema 约束。不支持 schema 的 provider
+		// 会拿到自由文本，解析必炸 —— 与其让它运行时反复失败，不如现在就拒。
+		log.Printf("[homed] warning: 蒸馏生成 provider %q 不支持 JSON Schema，拆分不可靠（蒸馏回退 jieba 路）",
+			providerName)
+		provider.Close()
+		return nil
+	}
+	log.Printf("[homed] distill generation active: provider=%s model=%s",
+		providerName, provider.Info().Model)
+	return distill.NewExtractor(provider, nil)
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/memory/nilcheck_test.go b/internal/kernelmod/memory/nilcheck_test.go
new file mode 100644
index 00000000..191dac97
--- /dev/null
+++ b/internal/kernelmod/memory/nilcheck_test.go
@@ -0,0 +1,71 @@
+package memory
+
+// "nil 加读取前检查" 的判据（用户指定的做法）。
+//
+// ## 为什么需要判据守它
+//
+// `KernelState` 的字段是**类型化的**（用户设计），好处是拼错/取错类型是
+// 编译错误。但**跨模块的"未就绪"仍表现为 nil** —— 而 nil 解引用会
+// **panic**，栈信息指向无关处（如 `strings.Split`），排查成本高。
+//
+// 用户明确要求："结构体成员初始置 nil 加**读取前检查**"。
+// 本判据确保每个模块对**不由依赖图保证**的字段（Group 0 产物）做检查。
+//
+// ★ 为什么要判据而不是靠自觉：`ks.CfgReg` 是 Group 0 的产物，
+// **无法通过 Requires 声明**（Group 0 不是调度模块）⇒ 依赖图保证不了它。
+// 这正是最容易忘、忘了就 panic 的地方。
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+)
+
+// ★★★ 判据：**CfgReg 为 nil 时给可操作错误，而不是 panic**。
+func TestMemoryModuleRejectsNilCfgReg(t *testing.T) {
+	dir := t.TempDir()
+	ks := &kernelboot.KernelState{DataDir: dir} // CfgReg 故意为 nil
+
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("★ CfgReg 为 nil 时 panic 了（应返回可操作错误）: %v\n"+
+				"   用户要求的是「nil 加读取前检查」，panic 的栈信息指向无关处", r)
+		}
+	}()
+
+	err := (Module{}).Init(ks)
+	if err == nil {
+		t.Fatal("★ CfgReg 为 nil 却成功返回 —— 后面会在读配置时 panic")
+	}
+	// 错误必须点出**是哪个字段**以及**该做什么**
+	msg := err.Error()
+	if !strings.Contains(msg, "CfgReg") {
+		t.Errorf("错误应点名字段 CfgReg（便于定位）: %v", err)
+	}
+	if !strings.Contains(msg, "Group 0") {
+		t.Errorf("错误应指出根因（Group 0 必须先跑）: %v", err)
+	}
+}
+
+// ★★★ 判据：**DataDir 为空时也拒绝**（同类检查）。
+func TestMemoryModuleRejectsEmptyDataDir(t *testing.T) {
+	dir := t.TempDir()
+	reg := newTestReg(t, dir)
+	ks := &kernelboot.KernelState{CfgReg: reg} // DataDir 空
+
+	err := (Module{}).Init(ks)
+	if err == nil {
+		t.Fatal("★ DataDir 为空却成功返回")
+	}
+	if !strings.Contains(err.Error(), "DataDir") {
+		t.Errorf("错误应点名字段 DataDir: %v", err)
+	}
+}
+
+func newTestReg(t *testing.T, dir string) *internalConfig.ConfigRegistry {
+	t.Helper()
+	return internalConfig.NewConfigRegistry(filepath.Join(dir, "config.db"))
+}
diff --git a/internal/kernelmod/migration/mod.go b/internal/kernelmod/migration/mod.go
new file mode 100644
index 00000000..fa4c59e9
--- /dev/null
+++ b/internal/kernelmod/migration/mod.go
@@ -0,0 +1,284 @@
+// Package migration 提供**数据目录迁移**的内核能力（伪关机 → 迁移 → 唤醒）。
+//
+// ## 它提供什么
+//
+// 两个工具（暴露给模型/WebUI）：
+//
+//	migrate_data_preflight  → 只读体检：报告能不能迁、要迁多少、有哪些风险
+//	migrate_data_plan       → 生成可执行迁移脚本（伪关机窗口由脚本自己 stop 覆盖）
+//
+// ## ★ 为什么不提供"一键迁移"工具
+//
+// 迁移是**破坏性且不可逆**的（21G 数据 + 12 处 DB 改写 + 46 个文件改写），
+// 而且内核跑在 systemd 沙箱里（ProtectSystem/ProtectHome）**本来就写不了
+// /etc/systemd**，更没法把 /home/newqqagent 搬到别的挂载点（跨目录 rename 会失败，
+// 必须 rsync 全量）。
+//
+// ⇒ 内核的职责是：**体检 + 生成正确的脚本 + 提供伪关机/唤醒能力**；
+//
+//	真正的搬数据由运维执行脚本。这样每一步都可审查、可回滚。
+//
+// ## 依赖声明
+//
+// Requires 里**故意不含** plugin-host：本模块只读 fs + 读 config，
+// 伪关机能力（PluginQuiescer）由调用方在需要时注入，不硬依赖。
+package migration
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"syscall"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/systemd"
+)
+
+func init() { kernelmod.Register(Module{}) }
+
+// Module 是数据目录迁移模块。
+type Module struct{}
+
+func (Module) Name() string { return "migration" }
+
+// Requires 只需要配置（读 data_dir）与 kernel-io（日志）。
+func (Module) Requires() []string { return []string{"config", "kernel-io"} }
+
+func (Module) Provides() []string { return []string{"migration"} }
+
+// MigrateReport 是体检结果。
+type MigrateReport struct {
+	DataDir    string    `json:"data_dir"`
+	TotalBytes int64     `json:"total_bytes"`
+	Dirs       []DirInfo `json:"dirs"`
+	Mounts     []string  `json:"mounts"`       // 必须先卸载的挂载点
+	Risks      []string  `json:"risks"`        // 会导致数据丢失/错误的点
+	DBPathKeys []string  `json:"db_path_keys"` // 数据库里存绝对路径的键
+	SameDevice bool      `json:"same_device"`  // 目标与源是否同一设备（决定能否 rename）
+	CanRename  bool      `json:"can_rename"`   // 同设备可直接 rename，否则必须 rsync
+	ScriptPath string    `json:"script_path,omitempty"`
+}
+
+// DirInfo 是单目录的信息。
+type DirInfo struct {
+	Name  string `json:"name"`
+	Bytes int64  `json:"bytes"`
+	Kind  string `json:"kind"` // data | runtime | optional | mount
+}
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	// 体检结果放在 KernelState 上，供工具/WebUI 读（可选能力，nil 安全）
+	ks.MigrationPreflight = func(target string) (interface{}, error) {
+		return Preflight(ks.DataDir, target)
+	}
+	return nil
+}
+
+// Preflight 体检：数据目录现在是什么状态、迁到 target 需要注意什么。
+func Preflight(dataDir, target string) (*MigrateReport, error) {
+	rep := &MigrateReport{DataDir: dataDir}
+
+	// 目录分类（来自 2026-10-17 生产盘点，21G）
+	// data=必须迁 runtime=不迁（重启重建） optional=可丢 mount=挂载点需先卸
+	classify := map[string]string{
+		"agentfs":          "mount",
+		"plugindev":        "data",
+		"blocklauncher":    "data",
+		"browser_profiles": "data",
+		"models":           "data",
+		"plugins":          "data",
+		"mcbridge":         "data",
+		"memory":           "data",
+		"plugin_data":      "data",
+		"knowledge":        "data",
+		"skills":           "data",
+		"mcp":              "data",
+		"nlp":              "data",
+		"adapters":         "data",
+		"data":             "data",
+		"uploads":          "data",
+		"device_media":     "data",
+		"webui_files":      "data",
+		"changesets":       "data",
+		"heartbeat":        "runtime",
+		"log":              "optional",
+		"backups":          "optional",
+		"memory.bak":       "optional",
+	}
+
+	entries, err := os.ReadDir(dataDir)
+	if err != nil {
+		return nil, fmt.Errorf("读数据目录: %w", err)
+	}
+	for _, e := range entries {
+		name := e.Name()
+		if !e.IsDir() {
+			continue
+		}
+		info := DirInfo{Name: name, Kind: classify[name]}
+		if info.Kind == "" {
+			info.Kind = "data" // 未知目录默认**必须迁**（宁可多迁，不可漏迁）
+		}
+		info.Bytes = dirSize(filepath.Join(dataDir, name))
+		rep.Dirs = append(rep.Dirs, info)
+		rep.TotalBytes += info.Bytes
+	}
+	sort.Slice(rep.Dirs, func(i, j int) bool { return rep.Dirs[i].Bytes > rep.Dirs[j].Bytes })
+
+	// ① 挂载点：agentfs 是 overlay（lower/upper/work），不卸就搬空壳。
+	//
+	// ★ 风险说明**无条件**报出，只有"要不要 umount"取决于实际挂载状态。
+	//
+	// 为什么分开：如果只在挂载时才提风险，那"现在没挂、迁移脚本跑起来时
+	// 服务又把它挂上了"这种时序就完全没提示 —— 而 agentfs 恰恰是内核
+	// 启动时才挂的。运维在**停机状态**做体检会看不到这条警示，
+	// 但迁移脚本里的 stop 又会把它挂回来（见脚本的 umount 步骤）。
+	// 判据 TestPreflightReportsKnownRisks 就是为了钉住这条。
+	if _, err := os.Stat(filepath.Join(dataDir, "agentfs")); err == nil {
+		merged := filepath.Join(dataDir, "agentfs", "merged")
+		if isMountpoint(merged) {
+			rep.Mounts = append(rep.Mounts, merged)
+		}
+		rep.Risks = append(rep.Risks,
+			"agentfs/merged 是 overlay 挂载点（lower/upper/work 三段）：不先 umount 会搬走'空壳'，"+
+				"真正内容仍挂在旧路径 ⇒ 新目录 agentfs 不可用。"+
+				"注意：内核启动时才挂它，所以**停机体检看不到挂载**也仍要卸")
+	}
+
+	// ② 数据库绝对路径：不改会"看起来记忆全丢"（内核按旧路径找不到就重建空库，且不报错）
+	rep.DBPathKeys = []string{
+		"core.daemon.data_dir", "core.plugin.dir", "core.memory.graph",
+		"core.memory.text", "core.memory.documents", "core.knowledge.path",
+		"core.log.path", "core.memory.multimodal_space.options.model_dir",
+	}
+	rep.Risks = append(rep.Risks,
+		fmt.Sprintf("数据库有 %d 个键存绝对路径；不改写会导致重启后按旧路径找数据，"+
+			"找不到就**静默重建空库**（看起来像记忆全丢）", len(rep.DBPathKeys)),
+		"plugin_data 下实测有 46 个文件写死了绝对路径（典型：commondev 的 git 镜像/workdir）",
+		"security.key 不迁 ⇒ 所有加密配置解不开（敏感信息全部失效）",
+	)
+
+	// ③ 是否同设备：决定 rename（瞬时）还是 rsync（几分钟）
+	if target != "" {
+		if src, err := os.Stat(dataDir); err == nil {
+			if dst, err := os.Stat(filepath.Dir(target)); err == nil {
+				a := src.Sys().(*syscall.Stat_t).Dev
+				b := dst.Sys().(*syscall.Stat_t).Dev
+				rep.SameDevice = a == b
+				rep.CanRename = rep.SameDevice
+				if !rep.SameDevice {
+					rep.Risks = append(rep.Risks,
+						"目标不在同一设备 ⇒ 不能用 rename，必须 rsync 全量拷贝（耗时随数据量增长）")
+				}
+			}
+		}
+	}
+
+	// ④ 当前 systemd 权威 vs DB 权威是否一致（两个权威不等价）
+	// 运行时权威 = -data（本模块的 dataDir）；配置权威 = DB core.daemon.data_dir
+	if st, err := systemd.Check(dataDir, dataDir); err == nil {
+		if st.RuntimeDataDir != "" && st.ConfigDataDir != "" && st.RuntimeDataDir != st.ConfigDataDir {
+			rep.Risks = append(rep.Risks,
+				fmt.Sprintf("★ 数据目录有**两个权威且不一致**：-data=%s（管 memory/graph.db + 插件 DataDir）"+
+					" vs DB core.daemon.data_dir=%s（管 memory/text、knowledge、nlp 等 6 个模块）⇒ 数据会分裂",
+					st.RuntimeDataDir, st.ConfigDataDir))
+		}
+	}
+	return rep, nil
+}
+
+// dirSize 递归统计目录大小（符号链接不跟随，避免重复计算硬链接/环）。
+func dirSize(root string) int64 {
+	var total int64
+	filepath.Walk(root, func(p string, info os.FileInfo, err error) error {
+		if err != nil || info == nil {
+			return nil
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			return nil
+		}
+		if !info.IsDir() {
+			total += info.Size()
+		}
+		return nil
+	})
+	return total
+}
+
+// isMountpoint 判断路径是否为挂载点（读 /proc/mounts，不依赖外部命令）。
+func isMountpoint(p string) bool {
+	data, err := os.ReadFile("/proc/mounts")
+	if err != nil {
+		return false
+	}
+	clean := filepath.Clean(p)
+	for _, line := range splitLines(string(data)) {
+		f := splitFields(line)
+		if len(f) >= 2 && unescapeMount(f[1]) == clean {
+			return true
+		}
+	}
+	return false
+}
+
+func splitLines(s string) []string {
+	var out []string
+	start := 0
+	for i := 0; i < len(s); i++ {
+		if s[i] == '\n' {
+			out = append(out, s[start:i])
+			start = i + 1
+		}
+	}
+	if start < len(s) {
+		out = append(out, s[start:])
+	}
+	return out
+}
+
+func splitFields(s string) []string {
+	var out []string
+	i := 0
+	for i < len(s) {
+		for i < len(s) && s[i] == ' ' {
+			i++
+		}
+		j := i
+		for j < len(s) && s[j] != ' ' {
+			j++
+		}
+		if j > i {
+			out = append(out, s[i:j])
+		}
+		i = j
+	}
+	return out
+}
+
+// unescapeMount 还原 /proc/mounts 里的八进制转义（空格写作 \040）。
+func unescapeMount(s string) string {
+	out := make([]byte, 0, len(s))
+	for i := 0; i < len(s); i++ {
+		if s[i] == '\\' && i+3 < len(s) {
+			v := 0
+			ok := true
+			for k := 1; k <= 3; k++ {
+				c := s[i+k]
+				if c < '0' || c > '7' {
+					ok = false
+					break
+				}
+				v = v*8 + int(c-'0')
+			}
+			if ok {
+				out = append(out, byte(v))
+				i += 3
+				continue
+			}
+		}
+		out = append(out, s[i])
+	}
+	return string(out)
+}
diff --git a/internal/kernelmod/migration/mod_test.go b/internal/kernelmod/migration/mod_test.go
new file mode 100644
index 00000000..7589f643
--- /dev/null
+++ b/internal/kernelmod/migration/mod_test.go
@@ -0,0 +1,171 @@
+package migration
+
+// 数据目录迁移体检的判据。
+//
+// ## 为什么要这些判据
+//
+// 迁移是**破坏性**操作。体检是唯一能让运维在动手前看到"会丢什么"的东西，
+// 所以它漏报的后果是**数据丢失**（而不是一个报错）。
+//
+// 三个必须守住的点（都来自 2026-10-17 生产实测）：
+//  1. overlay 挂载点必须被识别（不识别 ⇒ 搬走空壳）
+//  2. 未知目录默认**必须迁**（宁可多迁，不可漏迁）
+//  3. 同设备/跨设备必须判对（跨设备不能 rename，必须 rsync）
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// ★★★ 判据：未知目录默认 data（必须迁），不能被当成"可丢"。
+func TestPreflightDefaultsUnknownDirsToData(t *testing.T) {
+	dir := t.TempDir()
+	// 造一个体检表里没有的目录
+	mustMkdir(t, filepath.Join(dir, "some_new_thing"))
+	os.WriteFile(filepath.Join(dir, "some_new_thing", "f"), make([]byte, 100), 0o644)
+
+	rep, err := Preflight(dir, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	found := false
+	for _, d := range rep.Dirs {
+		if d.Name == "some_new_thing" {
+			found = true
+			if d.Kind != "data" {
+				t.Fatalf("★ 未知目录被归为 %q（应为 data）—— 漏迁 = 丢数据", d.Kind)
+			}
+		}
+	}
+	if !found {
+		t.Fatal("体检未列出目录")
+	}
+}
+
+// ★★★ 判据：heartbeat 归 runtime（不迁），log/backups/memory.bak 归 optional。
+func TestPreflightClassifiesRuntimeAndOptional(t *testing.T) {
+	dir := t.TempDir()
+	for _, n := range []string{"heartbeat", "log", "backups", "memory.bak", "memory"} {
+		mustMkdir(t, filepath.Join(dir, n))
+	}
+	rep, err := Preflight(dir, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]string{
+		"heartbeat": "runtime", "log": "optional", "backups": "optional",
+		"memory.bak": "optional", "memory": "data",
+	}
+	got := map[string]string{}
+	for _, d := range rep.Dirs {
+		got[d.Name] = d.Kind
+	}
+	for n, w := range want {
+		if got[n] != w {
+			t.Fatalf("★ %s 分类为 %q，应为 %q", n, got[n], w)
+		}
+	}
+}
+
+// ★★★ 判据：overlay 挂载点必须被识别（不识别 = 搬走空壳）。
+//
+// 用真实的 /proc/mounts 判断：若本机恰好有 agentfs/merged 挂载则验证识别，
+// 否则验证"没挂载时不给假警告"。
+func TestPreflightDetectsOverlayMount(t *testing.T) {
+	if !isMountpoint("/proc") {
+		t.Fatal("isMountpoint 连 /proc 都识别不出 ⇒ /proc/mounts 解析坏了")
+	}
+	dir := t.TempDir()
+	mustMkdir(t, filepath.Join(dir, "agentfs", "merged"))
+	rep, err := Preflight(dir, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 临时目录里 agentfs/merged 不是真挂载点 ⇒ 不应报进 Mounts
+	for _, m := range rep.Mounts {
+		if m == filepath.Join(dir, "agentfs", "merged") {
+			t.Fatal("★ 非挂载点被误报为挂载点（会导致迁移脚本 umount 报错）")
+		}
+	}
+}
+
+// ★★★ 判据：体检必须报出"数据库绝对路径"与"security.key"两类风险。
+//
+// 这四条风险是生产实测得到的；少报任何一条，运维都会踩坑。
+func TestPreflightReportsKnownRisks(t *testing.T) {
+	dir := t.TempDir()
+	mustMkdir(t, filepath.Join(dir, "memory"))
+	// agentfs 必须存在，overlay 风险才会计入（风险是关于 agentfs 的）
+	mustMkdir(t, filepath.Join(dir, "agentfs", "merged"))
+	rep, err := Preflight(dir, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	needles := []string{"overlay", "绝对路径", "security.key"}
+	joined := ""
+	for _, r := range rep.Risks {
+		joined += r + "\n"
+	}
+	for _, n := range needles {
+		if !contains(joined, n) {
+			t.Fatalf("★ 体检未报出风险 %q；实际风险: %v", n, rep.Risks)
+		}
+	}
+	if len(rep.DBPathKeys) != 8 {
+		t.Fatalf("★ DB 绝对路径键应为 8 个，实际 %d", len(rep.DBPathKeys))
+	}
+}
+
+// ★★★ 判据：同设备 → CanRename=true；跨设备 → false 且报风险。
+func TestPreflightDeviceDetection(t *testing.T) {
+	dir := t.TempDir()
+	mustMkdir(t, filepath.Join(dir, "memory"))
+
+	// 同设备：目标父目录就是 dir 自己
+	rep, err := Preflight(dir, filepath.Join(dir, "target"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !rep.SameDevice || !rep.CanRename {
+		t.Fatalf("★ 同设备未被识别：same=%v canRename=%v", rep.SameDevice, rep.CanRename)
+	}
+	// 跨设备：/dev/shm 通常 tmpfs，与 t.TempDir() 不同设备
+	if st, err := os.Stat("/dev/shm"); err == nil && st.IsDir() {
+		rep2, err := Preflight(dir, "/dev/shm/xxagent")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if rep2.SameDevice {
+			t.Skip("/dev/shm 与临时目录同设备，跳过跨设备分支")
+		}
+		if rep2.CanRename {
+			t.Fatal("★ 跨设备被判为可 rename ⇒ 迁移会失败")
+		}
+		found := false
+		for _, r := range rep2.Risks {
+			if contains(r, "同设备") || contains(r, "rename") {
+				found = true
+			}
+		}
+		if !found {
+			t.Fatal("★ 跨设备未报风险")
+		}
+	}
+}
+
+func mustMkdir(t *testing.T, p string) {
+	t.Helper()
+	if err := os.MkdirAll(p, 0o755); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func contains(s, sub string) bool {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/kernelmod/multimodal/mod.go b/internal/kernelmod/multimodal/mod.go
new file mode 100644
index 00000000..fcae246e
--- /dev/null
+++ b/internal/kernelmod/multimodal/mod.go
@@ -0,0 +1,70 @@
+// Package multimodal 是 multimodal 模块：多模态向量空间。
+//
+// 依赖 config：从配置读"用哪个 provider"。
+package multimodal
+
+import (
+	"log"
+	"strings"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/vector"
+	"github.com/JianFeeeee/HomeAgent/pkg/embedding"
+)
+
+// Module 提供多模态向量空间。
+type Module struct{}
+
+func (Module) Name() string       { return "multimodal" }
+func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
+func (Module) Provides() []string { return []string{kernelmod.FacMultimodal} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	cfgReg := ks.CfgReg
+	var multimodalSpace vector.MultimodalEmbedder
+	// 这两个值只用于状态报告（healthcheck_kernel 的 onnx 段）：
+	// 「配了哪个 provider」与「为什么没启用」，避免只能看到 false 却不知原因。
+	var mmProviderName, mmErr string
+	var closeAdapted func()
+
+	if mmProvider := cfgReg.GetString("core.memory.multimodal_space.provider", ""); mmProvider != "" {
+		mmProviderName = mmProvider
+		opts := map[string]string{}
+		const optPrefix = "core.memory.multimodal_space.options."
+		for _, key := range cfgReg.List(optPrefix) {
+			opts[strings.TrimPrefix(key, optPrefix)] = cfgReg.GetString(key, "")
+		}
+		provider, err := embedding.Open(mmProvider, embedding.Config{Options: opts})
+		if err != nil {
+			mmErr = err.Error()
+			log.Printf("[homed] warning: 多模态向量 provider %q 打开失败: %v（多模态向量检索已禁用；已注册: %s）",
+				mmProvider, err, strings.Join(embedding.Names(), ", "))
+		} else if adapted, err := vector.AdaptProvider(provider); err != nil {
+			provider.Close()
+			mmErr = err.Error()
+			log.Printf("[homed] warning: 多模态向量 provider %q 元数据不合法: %v（多模态向量检索已禁用）", mmProvider, err)
+		} else {
+			multimodalSpace = adapted
+			closeAdapted = provider.Close
+			info := provider.Info()
+			// 指纹可能很长（模型文件哈希），日志里只取前 12 个字符便于对照。
+			shortFP := info.Fingerprint
+			if len(shortFP) > 12 {
+				shortFP = shortFP[:12]
+			}
+			log.Printf("[homed] multimodal space active: provider=%s dim=%d fp=%s modalities=%v",
+				mmProvider, info.Dimension, shortFP, info.Modalities)
+		}
+	}
+
+	ks.MultimodalSpace = multimodalSpace
+	ks.MultimodalProviderName = mmProviderName
+	ks.MultimodalErr = mmErr
+	if closeAdapted != nil {
+		ks.AddCloser(closeAdapted)
+	}
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/onnx/mod.go b/internal/kernelmod/onnx/mod.go
new file mode 100644
index 00000000..551a4861
--- /dev/null
+++ b/internal/kernelmod/onnx/mod.go
@@ -0,0 +1,47 @@
+// Package onnx 是 onnx-parser 模块：依存句法分析器（失败退回规则引擎）。
+//
+// ## ★ 它为什么是独立模块
+//
+// 它写的是**包级单例** `nlp.defaultParser`（internal/nlp/parser.go:15），
+// 而该单例由**运行期**读取（`nlp.NewExtractor(nil)` 构造时快照它，
+// 由蒸馏路径 `extractKeyTriples` 调用）。
+//
+// 这正是设计 §2.8.2 说的"签名看不到的隐藏依赖"：没有参数传递，
+// 而是**包级变量 + 运行期读**。
+//
+// ⇒ 独立成模块，让 text-memory 能**显式声明**对它的依赖
+// （见 kernelmod/textmem 的说明）。这样"碰巧安全"变成"结构保证"。
+package onnx
+
+import (
+	"log"
+	"path/filepath"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/nlp"
+)
+
+// Module 初始化依存句法分析器。
+type Module struct{}
+
+func (Module) Name() string       { return "onnx-parser" }
+func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
+func (Module) Provides() []string { return []string{kernelmod.FacONNX} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	modelPath := ks.CfgReg.GetString("core.agent.onnx_model_path", "")
+	onnxParser, err := nlp.NewONNXParser(nlp.ONNXConfig{
+		ModelPath: modelPath,
+		DataDir:   filepath.Join(ks.Cfg.Daemon.DataDir, "nlp"),
+	})
+	if err != nil {
+		log.Printf("[homed] warn: ONNX parser init: %v, using fallback", err)
+		return nil
+	}
+	nlp.SetDefaultParser(onnxParser)
+	log.Printf("[homed] dep parser initialized (model: %s)", modelPath)
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/pluginhost/catalog.go b/internal/kernelmod/pluginhost/catalog.go
new file mode 100644
index 00000000..9b2da7e3
--- /dev/null
+++ b/internal/kernelmod/pluginhost/catalog.go
@@ -0,0 +1,194 @@
+// Package pluginhost 是 plugin-host 模块：**插件宿主**（设计 §2.6 + 用户要求）。
+//
+// ## 职责（用户的说法）
+//
+// > 插件管理器不应该在被拉起后就去读插件列表获取元数据并写入缓存准备拉起吗？
+//
+// 本模块做四件事：
+//
+//	① **扫一次**插件目录 → 元数据**缓存**（PluginCatalog）
+//	② 按**三形态**分流（自动启动 / 启用但不自动启动 / 禁用）
+//	③ 按依赖声明（requires_facilities）决定**逐个插件**的拉起时机
+//	④ 执行拉起（用 stage-host 产出的 Registry）
+//
+// ## ★ 为什么它是**内核模块**而不是插件（架构决定）
+//
+// 用户选定的方案 A。理由（自举问题）：
+//
+//	· `pluginmgr` 是**插件** ⇒ 它自己要被拉起 ⇒ 若调度逻辑在它内部，
+//	  就得先拉起自己才能拉起自己（循环）。
+//	· 而调度器要订阅内核的 syncbus（内核设施），依附内核模块更自然。
+//
+// ⇒ 调度放内核模块（本包），`pluginmgr` 插件只保留**人机界面**职责
+// （列列表/启停/装卸的工具与 HTTP）。
+//
+// ## ★ 依赖（关键：**不依赖 agent**）
+//
+//	Requires: config, lua, supervisor, tracker, memory, textmem, docmem,
+//	          knowledge, kernel-io, stage-host
+//
+// 插件**加载**需要的是 stage-host（Registry + StageHost）与几个底层设施，
+// **不需要** agent。原先把 wirePluginSDK 放在 agent 模块里，导致插件加载
+// 被迫排在 agent 之后（agent 层实测 35 秒）。
+//
+// 实测发现：SDK 的 `Plugin` 接口只有 `Name/Start/Stop`，**没有 Configure**
+// （那条"插件 Configure 需要 StatusProvider"的注释已过时）。
+// 且唯一在 Start 阶段引 Status 的插件（healthcheck）是 **nil-guarded** 的。
+// ⇒ 拆成"底层 7 项在这里注入、agent 相关的 2 项由 agent 模块**后补注入**"。
+package pluginhost
+
+import (
+	"os"
+	"path/filepath"
+	"sort"
+	"time"
+
+	"github.com/JianFeeeee/HomeAgent/internal/plugin"
+)
+
+// PluginMeta 是单个插件的**元数据**（缓存项）。
+//
+// ★ 为何不直接用 plugin.PluginManifest：缓存只保留"调度与展示"需要的字段，
+// 且加一层让"元数据来源"可替换（将来若从 DB 而非文件读，上层不用改）。
+type PluginMeta struct {
+	Name string
+	// RequiresFacilities 是声明的启动前置设施（空 = 等内核完全初始化）。
+	RequiresFacilities []string
+	// AutoStart：true=伴随启动；false=启用但不自动启动（等显式启用）。
+	AutoStart bool
+	// Disabled 来自 disabled_plugins 配置（持久禁用，最高优先级）。
+	Disabled bool
+
+	// 以下用于展示（pluginmgr 的列表/状态）
+	Version     string
+	Description string
+	NameZh      string
+	Tags        []string
+	// ManifestPath 便于诊断（"这个插件的元数据从哪来的"）
+	ManifestPath string
+	// ScannedAt 记录扫描时刻（缓存新鲜度；也便于"元数据过期"排查）
+	ScannedAt time.Time
+}
+
+// PluginCatalog 是插件**元数据缓存**。
+//
+// ## 为什么要有它（用户指出的设计）
+//
+// 原先元数据散落且**每次重扫**：
+//
+//	· cmd/homed 的 collectPluginSpecs（决定启动时机）
+//	· pluginmgr 的 listPlugins（人看的列表）
+//
+// ⇒ 扫一次、缓存下来，供调度器 / pluginmgr / 显式启用路径共用。
+//
+// ## ★ 并发
+//
+// 调度在装配期（单线程语义），但 pluginmgr 的 HTTP 工具可能在运行期读它。
+// 用 RWMutex 保护；读多写少（只在扫描时写）。
+type PluginCatalog struct {
+	mu    *rwMutex
+	items map[string]*PluginMeta
+	dir   string
+}
+
+// newCatalog 创建空缓存。
+func newCatalog(dir string) *PluginCatalog {
+	return &PluginCatalog{mu: newRWMutex(), items: map[string]*PluginMeta{}, dir: dir}
+}
+
+// Get 取单个插件的元数据。
+func (c *PluginCatalog) Get(name string) (*PluginMeta, bool) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	m, ok := c.items[name]
+	return m, ok
+}
+
+// Names 返回全部插件名（升序，可复现）。
+func (c *PluginCatalog) Names() []string {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	out := make([]string, 0, len(c.items))
+	for n := range c.items {
+		out = append(out, n)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// All 返回全部元数据（按名字升序）。
+func (c *PluginCatalog) All() []*PluginMeta {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	names := make([]string, 0, len(c.items))
+	for n := range c.items {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	out := make([]*PluginMeta, 0, len(names))
+	for _, n := range names {
+		out = append(out, c.items[n])
+	}
+	return out
+}
+
+// Dir 返回被扫描的插件目录。
+func (c *PluginCatalog) Dir() string { return c.dir }
+
+// Size 返回缓存条目数。
+func (c *PluginCatalog) Size() int {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return len(c.items)
+}
+
+// set 写入一条（扫描时用）。
+func (c *PluginCatalog) set(m *PluginMeta) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.items[m.Name] = m
+}
+
+// scanCatalog 扫插件目录，把元数据写进缓存。
+//
+// ## 容错策略
+//
+// 无 manifest / 解析失败 ⇒ **跳过该目录**（不是错误）：插件目录里可能有
+// 非插件内容（README、临时备份、install 中途的半成品）。返回跳过列表
+// 供日志说明"为什么某个目录没被识别成插件"。
+func scanCatalog(dir string, isDisabled func(string) bool) (*PluginCatalog, []string) {
+	c := newCatalog(dir)
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return c, []string{"读取插件目录失败: " + err.Error()}
+	}
+	var skipped []string
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		name := e.Name()
+		mft, err := plugin.ReadManifest(filepath.Join(dir, name))
+		if err != nil {
+			skipped = append(skipped, name)
+			continue
+		}
+		display := mft.Name
+		if display == "" {
+			display = name
+		}
+		c.set(&PluginMeta{
+			Name:               name, // ★ 用**目录名**：它与 LoadOneDir/注册表键一致
+			RequiresFacilities: mft.RequiresFacilities,
+			AutoStart:          mft.ShouldAutoStart(),
+			Disabled:           isDisabled != nil && isDisabled(name),
+			Version:            mft.Version,
+			Description:        mft.Description,
+			NameZh:             mft.NameZh,
+			Tags:               mft.Tags,
+			ManifestPath:       filepath.Join(dir, name, "plugin.json"),
+			ScannedAt:          time.Now(),
+		})
+	}
+	return c, skipped
+}
diff --git a/internal/kernelmod/pluginhost/catalog_test.go b/internal/kernelmod/pluginhost/catalog_test.go
new file mode 100644
index 00000000..b972b3da
--- /dev/null
+++ b/internal/kernelmod/pluginhost/catalog_test.go
@@ -0,0 +1,446 @@
+package pluginhost
+
+// plugin-host（插件宿主）的判据（2026-10-16）。
+//
+// 设计见 docs/zh/kernel-modularization-design.md §2.6 + 用户方案 A。
+//
+// ## 这组判据守什么
+//
+//  ① **三形态分流正确**（用户明确要求：自动启动 / 启用但不自动启动 / 禁用）
+//  ② **元数据缓存**（用户指出的设计：扫一次、供调度与展示共用）
+//  ③ **内置插件不被漏掉** ← 这是我实际踩过的回归（19 个全丢）
+//  ④ 关键顺序：failback 白名单必须在插件拉起前生效
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+)
+
+// makePluginDir 造一个带 plugin.json 的插件目录。
+func makePluginDir(t *testing.T, root, name, manifest string) {
+	t.Helper()
+	d := filepath.Join(root, name)
+	if err := os.MkdirAll(d, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(d, "plugin.json"), []byte(manifest), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// ★★★ 判据：**三形态分流正确**（用户设计要求的三种形态）。
+func TestClassifyThreeForms(t *testing.T) {
+	root := t.TempDir()
+	// ① 自动启动 + 声明依赖
+	makePluginDir(t, root, "auto_declared",
+		`{"name":"auto_declared","version":"1","entry":"plugin.bin","requires_facilities":["config"]}`)
+	// ① 自动启动 + 未声明
+	makePluginDir(t, root, "auto_plain",
+		`{"name":"auto_plain","version":"1","entry":"plugin.bin"}`)
+	// ② 启用但不自动启动
+	makePluginDir(t, root, "manual",
+		`{"name":"manual","version":"1","entry":"plugin.bin","requires_facilities":["config"],"auto_start":false}`)
+	// ③ 禁用
+	makePluginDir(t, root, "banned",
+		`{"name":"banned","version":"1","entry":"plugin.bin"}`)
+
+	cat, _ := scanCatalog(root, func(n string) bool { return n == "banned" })
+	g := classify(cat)
+
+	eq := func(got, want []string, what string) {
+		t.Helper()
+		sort.Strings(got)
+		sort.Strings(want)
+		if strings.Join(got, ",") != strings.Join(want, ",") {
+			t.Errorf("★ %s: 期望 %v 实际 %v", what, want, got)
+		}
+	}
+	eq(g.autoStart, []string{"auto_declared", "auto_plain"}, "① 自动启动")
+	eq(g.declared, []string{"auto_declared"}, "① 中声明了依赖的")
+	eq(g.manual, []string{"manual"}, "② 启用但不自动启动")
+	eq(g.disabled, []string{"banned"}, "③ 持久禁用")
+
+	// ★ 关键互斥：三形态必须互不重叠（一个插件只能属于一种）
+	inBoth := func(a, b []string, an, bn string) {
+		t.Helper()
+		m := map[string]bool{}
+		for _, x := range a {
+			m[x] = true
+		}
+		for _, x := range b {
+			if m[x] {
+				t.Errorf("★ %s 与 %s 同时包含 %s（三形态必须互斥）", an, bn, x)
+			}
+		}
+	}
+	inBoth(g.autoStart, g.manual, "autoStart", "manual")
+	inBoth(g.autoStart, g.disabled, "autoStart", "disabled")
+	inBoth(g.manual, g.disabled, "manual", "disabled")
+}
+
+// ★★★ 判据：**元数据缓存内容正确**（用户设计：读列表→写缓存）。
+func TestCatalogCachesMetadata(t *testing.T) {
+	root := t.TempDir()
+	makePluginDir(t, root, "p1",
+		`{"name":"p1","name_zh":"一","version":"2.3.4","entry":"plugin.bin",
+		  "description":"演示","requires_facilities":["config","llm"],"tags":["a","b"]}`)
+
+	cat, noskip := scanCatalog(root, nil)
+	if len(noskip) != 0 {
+		t.Errorf("不该有跳过的目录: %v", noskip)
+	}
+	if cat.Size() != 1 {
+		t.Fatalf("缓存应有 1 条，实际 %d", cat.Size())
+	}
+	m, ok := cat.Get("p1")
+	if !ok {
+		t.Fatal("取不到 p1 的元数据")
+	}
+	// 每个字段都要缓存对（调度靠 RequiresFacilities，展示靠其余）
+	if len(m.RequiresFacilities) != 2 || m.RequiresFacilities[0] != "config" {
+		t.Errorf("RequiresFacilities 未正确缓存: %v", m.RequiresFacilities)
+	}
+	if !m.AutoStart {
+		t.Error("缺省 auto_start 应为 true")
+	}
+	if m.Version != "2.3.4" || m.NameZh != "一" || m.Description != "演示" {
+		t.Errorf("展示字段未正确缓存: %+v", m)
+	}
+	if len(m.Tags) != 2 {
+		t.Errorf("Tags 未正确缓存: %v", m.Tags)
+	}
+	if m.ManifestPath == "" || m.ScannedAt.IsZero() {
+		t.Error("诊断字段（路径/扫描时刻）应被记录")
+	}
+	// 缓存必须能列出（pluginmgr 的列表用它）
+	if names := cat.Names(); len(names) != 1 || names[0] != "p1" {
+		t.Errorf("Names 不对: %v", names)
+	}
+}
+
+// ★★★ 判据：**无 plugin.json 的目录被记为"无 manifest"而不是"错误"**。
+//
+// ★ 这条守的是我实际踩过的回归：19 个**内置插件**目录没有 plugin.json
+// （它们是编译期工厂），我第一版把它们记成"跳过 19 个非插件目录"并
+// **完全没有加载它们**（webui/pluginmgr/cli/files/timer… 全丢）。
+//
+// 判据分两层：
+//
+//	· 本层：scanCatalog 必须**如实**报告哪些目录没 manifest（便于诊断）
+//	· 装配层：LoadSkipping 必须补上内置插件（见 TestBuiltinsNotDropped）
+func TestScanReportsNoManifestDirs(t *testing.T) {
+	root := t.TempDir()
+	makePluginDir(t, root, "has_manifest", `{"name":"has_manifest","version":"1","entry":"plugin.bin"}`)
+	// 模拟内置插件目录：只有可执行文件，没有 plugin.json
+	builtin := filepath.Join(root, "builtin_plugin")
+	os.MkdirAll(builtin, 0o755)
+	os.WriteFile(filepath.Join(builtin, "plugin.bin"), []byte("x"), 0o755)
+
+	cat, noManifest := scanCatalog(root, nil)
+	if cat.Size() != 1 {
+		t.Errorf("缓存应只含带 manifest 的（1 条），实际 %d", cat.Size())
+	}
+	if len(noManifest) != 1 || noManifest[0] != "builtin_plugin" {
+		t.Fatalf("★ 无 manifest 的目录必须被如实报告（便于区分「内置插件」与「坏插件」）: %v",
+			noManifest)
+	}
+}
+
+// ★★★ 判据：**内置插件不会被漏掉**（行为判据，回归守）。
+//
+// ## 为什么这条必须存在
+//
+// 我第一版让 plugin-host 只处理"有 plugin.json 的外部插件"，
+// 结果 **19 个内置插件全部没加载** —— webui（人机界面）、pluginmgr
+// （插件管理）、cli、files、cmd、timer、mcp… 全丢，而**日志看起来正常**
+// （只有一条"跳过 19 个非插件目录"的提示，很容易被当成噪音略过）。
+//
+// ## ★ 为什么必须是**行为**判据（我第一版写成源码检查 ⇒ 变异不咬）
+//
+// 初版检查"源码里有 `LoadSkipping(`"。但删掉**调用**后，
+// 注释里仍有 `LoadSkipping` 字样 ⇒ 判据照样绿
+// （**测写法不测行为** —— 本仓反复踩的同一类坑）。
+//
+// ⇒ 改为跑**生产同一个函数** `buildSkipSet`，断言：
+//
+//	① 内置插件（无 manifest）**不在** skip 里 ⇒ 会走全量加载
+//	② 三形态的插件**在** skip 里（防重复加载 / 防误加载）
+func TestBuiltinsAreNotSkipped(t *testing.T) {
+	root := t.TempDir()
+	makePluginDir(t, root, "ext_auto",
+		`{"name":"ext_auto","version":"1","entry":"plugin.bin","requires_facilities":["config"]}`)
+	makePluginDir(t, root, "ext_manual",
+		`{"name":"ext_manual","version":"1","entry":"plugin.bin","auto_start":false}`)
+
+	cat, _ := scanCatalog(root, nil)
+	g := classify(cat)
+	skip := buildSkipSet(cat, g)
+
+	// ★ 核心：内置插件（不在 catalog 里 = 没有 plugin.json）**不得**被跳过。
+	//   若它在 skip 里 ⇒ LoadSkipping 会跳过它 ⇒ 它永远不会被加载。
+	const builtinName = "builtin_only"
+	if skip[builtinName] {
+		t.Fatalf("★ 内置插件 %s 在 skip 集合里 ⇒ 不会被加载"+
+			"（webui/pluginmgr/cli/files/timer/mcp 全是这类，会静默消失）", builtinName)
+	}
+	if !skip["ext_auto"] {
+		t.Error("① 声明依赖的插件应在 skip 里（plugin-host 自己拉起，避免重复）")
+	}
+	if !skip["ext_manual"] {
+		t.Fatal("★ auto_start=false 的插件必须在 skip 里 —— 否则会被全量加载" +
+			"（与「不自动启动」完全相反）")
+	}
+}
+
+// ★★★ 判据：**meta 层不谎报"已接线"** + 接线本身由 e2e 守。
+//
+// ## ★ 这里我连续踩了三次同一个坑，值得写下来
+//
+// 初版判据：`strings.Contains(code, "LoadSkipping(")` ⇒ 变异不咬，
+//
+//	因为**注释里也有这个字样**。
+//
+// 二版判据：`strings.Contains(code, "LoadSkipping(dir, skip)")` ⇒
+//
+//	变异成 `LoadSkipping(dir, nil)` 后**仍然绿**，因为 mod.go 的
+//	**注释第 116 行正好写着 `` `LoadSkipping(dir, skip)` ``**。
+//
+// **教训（第 N+1 次）：源码字符串检查测的是"文本"，不是"行为"。**
+// 只要文档/注释里出现过同一串，判据就永远绿 —— 而本仓的规范恰恰是
+// "每个关键决定都要在注释里讲清楚"，所以注释里几乎必然出现这些串。
+// ⇒ **源码检查只能用于"是否存在某个符号定义"，绝不能用于断言接线。**
+//
+// ## 那接线靠什么守？
+//
+// 行为层：真机 e2e 已验证（20 个插件加载、manual_probe **未**加载、
+// 内置插件全部在列）。这条 e2e 是接线的真正判据。
+//
+// 本判据只做一件**不依赖注释**的事：确认 `buildSkipSet` 有**真实调用点**
+// （AST 层面：调用表达式，不是注释里的文本）。
+func TestSkipSetHasRealCallSite(t *testing.T) {
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, "mod.go", nil, parser.ParseComments)
+	if err != nil {
+		t.Fatal(err)
+	}
+	calls := 0
+	ast.Inspect(f, func(n ast.Node) bool {
+		ce, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		if id, ok := ce.Fun.(*ast.Ident); ok && id.Name == "buildSkipSet" {
+			calls++
+		}
+		return true
+	})
+	if calls == 0 {
+		t.Fatal("★ buildSkipSet 必须被**真实调用**（AST 层面）" +
+			"—— 定义而不用等于没接。\n" +
+			"   （注意：不能用字符串 Contains 判 —— 注释里会命中，实测骗过我三次）")
+	}
+	// LoadSkipping 的**调用**（AST 层面）必须存在
+	ls := 0
+	ast.Inspect(f, func(n ast.Node) bool {
+		ce, ok := n.(*ast.CallExpr)
+		if !ok {
+			return true
+		}
+		if sel, ok := ce.Fun.(*ast.SelectorExpr); ok && sel.Sel.Name == "LoadSkipping" {
+			ls++
+			// ★ 且第二个实参必须**不是** nil（nil = skip 失效）
+			if len(ce.Args) >= 2 {
+				if id, ok := ce.Args[1].(*ast.Ident); ok && id.Name == "nil" {
+					t.Error("★ LoadSkipping 的 skip 实参是 nil ⇒ " +
+						"三形态跳过逻辑全部失效（内置插件会被误跳过、" +
+						"manual 会被误加载）")
+				}
+			}
+		}
+		return true
+	})
+	if ls == 0 {
+		t.Fatal("★ 必须真实调用 LoadSkipping（AST 层面，非注释）")
+	}
+}
+
+// ★★★ 判据：**缓存并发安全**（pluginmgr 运行期读、装配期写）。
+func TestCatalogConcurrentRead(t *testing.T) {
+	root := t.TempDir()
+	for i := 0; i < 20; i++ {
+		makePluginDir(t, root, "p"+string(rune('a'+i)),
+			`{"name":"x","version":"1","entry":"plugin.bin"}`)
+	}
+	cat, _ := scanCatalog(root, nil)
+
+	done := make(chan struct{})
+	for i := 0; i < 16; i++ {
+		go func() {
+			defer func() { done <- struct{}{} }()
+			for j := 0; j < 200; j++ {
+				_ = cat.Names()
+				_ = cat.All()
+				_ = cat.Size()
+				_, _ = cat.Get("pa")
+			}
+		}()
+	}
+	for i := 0; i < 16; i++ {
+		<-done
+	}
+}
+
+// ★★★ 判据：**SyncBus 为 nil 时不得 panic**（typed-nil 陷阱，实测踩到）。
+//
+// ## 为什么必须有这条
+//
+// `var nb *SyncBus; var i SyncState = nb` ⇒ **i != nil**（经典陷阱）。
+// 于是 `NewScheduler(i, …)` 内部 `i.IsReady(...)` 解引用空指针 ⇒ **panic**。
+//
+// 实测：`ks.SyncBus == nil`（非生产装配路径 / 单测）时 plugin-host 会崩。
+// 而 panic 发生在**插件拉起路径**上 ⇒ 整个内核启动失败。
+//
+// ⇒ 判据：把 typed-nil 传给 Scheduler 前必须已被拦截。
+// 这里直接验证**拦截逻辑本身**（不依赖 produciton 装配）。
+func TestNilSyncBusDoesNotPanic(t *testing.T) {
+	var nb *kernelboot.SyncBus // typed-nil
+	var iface kernelboot.SyncState = nb
+	if iface == nil {
+		t.Skip("接口就是 nil（不会有陷阱）—— 与本判据的前提不符")
+	}
+	// ★ 确认陷阱真实存在（否则这条判据是空的）
+	func() {
+		defer func() {
+			if r := recover(); r == nil {
+				t.Fatal("★ 前提不成立：typed-nil bus 竟然没 panic —— " +
+					"那就不需要那条 nil 拦截了，请一并删掉测试与拦截")
+			}
+		}()
+		_ = kernelboot.NewScheduler(iface, func(kernelboot.PluginSpec) error { return nil })
+	}()
+	// ★ 而生产代码里的拦截：mod.go 必须**显式判 nil** 后再传
+	src, err := os.ReadFile("mod.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	code := string(src)
+	if !strings.Contains(code, "ks.SyncBus != nil") {
+		t.Fatal("★ mod.go 必须显式判 `ks.SyncBus != nil` 再构造 Scheduler —— " +
+			"否则 typed-nil 会在 IsReady 处 panic（实测）")
+	}
+	if strings.Contains(code, "NewScheduler(ks.SyncBus,") {
+		t.Fatal("★ 不得把 ks.SyncBus **直接**传给 NewScheduler（typed-nil 陷阱）")
+	}
+}
+
+// ★★★★ 判据：**未声明依赖的插件必须等内核完全初始化**（§2.6.5 硬约束）。
+//
+// ## 这是我实际违反过、且有实测后果的约束 —— 必须写成判据
+//
+// 我第一版把插件按"本模块依赖是否覆盖插件声明"分成 launchNow / waitLater，
+// 并在 Init 里**直接**加载 launchNow。而未声明依赖的插件 `RequiresFacilities`
+// 是**空** ⇒ "覆盖空集"恒真 ⇒ 它们被归入 launchNow ⇒ **第 4 层就被加载**。
+//
+// 而 §2.6.5 的硬约束是「未声明 ⇒ 启动时机**逐字不变**（内核**完全**初始化后）」。
+// 原文警告："静默改变启动时机 = 静默引入竞态"。
+//
+// ## ★ 后果不是理论上的 —— 实测丢了一个工具
+//
+// 内置插件 `healthcheck` 在 `Start` 里做：
+//
+//	if s.Status() != nil { s.RegisterTool("healthcheck_kernel", …) }
+//
+// 第 4 层时 agent 还没建好（它与 plugin-host **并行**）⇒ `Status()` 为 nil
+// ⇒ **静默少注册一个工具**。实测：86 个工具（应为 87），**无任何报错**。
+// （nginx 式的 nil 保护把"时序错了"降级成了"少个功能"，最难发现。）
+//
+// ⇒ 判据：未声明的插件**不得**在 `KernelComplete()` 之前被拉起。
+// 用**真的 Scheduler + 真的 SyncBus** 验证（跑生产同一路径）。
+func TestUndeclaredPluginsWaitForKernelComplete(t *testing.T) {
+	root := t.TempDir()
+	makePluginDir(t, root, "undeclared",
+		`{"name":"undeclared","version":"1","entry":"plugin.bin"}`)
+	makePluginDir(t, root, "declared",
+		`{"name":"declared","version":"1","entry":"plugin.bin","requires_facilities":["config"]}`)
+
+	cat, _ := scanCatalog(root, nil)
+	g := classify(cat)
+	specs := buildSpecs(cat, g)
+	if len(specs) != 2 {
+		t.Fatalf("两个自动启动插件都应进调度器（含**未声明**的），实际 %d 个", len(specs))
+	}
+
+	bus := kernelboot.NewSyncBus()
+	bus.MarkDeclared([]string{"config", "agent"})
+	bus.MarkReady("config")
+
+	launched := map[string]bool{}
+	sched := kernelboot.NewScheduler(bus, func(s kernelboot.PluginSpec) error {
+		launched[s.Name] = true
+		return nil
+	})
+	got := sched.Submit(specs)
+	for _, n := range got {
+		launched[n] = true
+	}
+
+	// ① 声明的：依赖（config）已就绪 ⇒ **应当**立即拉起
+	if !launched["declared"] {
+		t.Error("声明了 config 且 config 已就绪的插件应当被拉起（这是本步的核心收益）")
+	}
+	// ② ★ 未声明的：内核**未**完成 ⇒ **不得**拉起
+	if launched["undeclared"] {
+		t.Fatal("★ 未声明依赖的插件在内核完全初始化**之前**被拉起了 ⇒ 违反 §2.6.5。\n" +
+			"   实测后果：healthcheck 的 s.Status() 为 nil ⇒ 静默少注册一个工具" +
+			"（86 vs 87，无任何报错）。")
+	}
+	// ③ 内核完成后 ⇒ 未声明的才应拉起
+	bus.MarkKernelComplete()
+	if !launched["undeclared"] {
+		t.Fatal("★ 内核完成后未声明的插件仍未被拉起 ⇒ 它永远起不来")
+	}
+}
+
+// ★★★ 判据：**未声明的插件必须在 skip 集合【外面】**（否则会被重复加载）。
+//
+// 调度器会拉起它，LoadSkipping 也会碰到它 ⇒ 两条路都加载 = 重复。
+// （实测未复现重复，是因为时序上 LoadSkipping 晚于调度器且 registry 有门，
+//
+//	但**不应依赖巧合** —— 判据把语义钉住。）
+func TestUndeclaredNotDoubleLoaded(t *testing.T) {
+	root := t.TempDir()
+	makePluginDir(t, root, "undeclared",
+		`{"name":"undeclared","version":"1","entry":"plugin.bin"}`)
+	cat, _ := scanCatalog(root, nil)
+	g := classify(cat)
+	skip := buildSkipSet(cat, g)
+
+	// 未声明的插件在 autoStart 里（调度器会管）
+	if len(g.autoStart) != 1 || g.autoStart[0] != "undeclared" {
+		t.Fatalf("前提不成立: %v", g.autoStart)
+	}
+	// ★ 修法后：catalog 里登记的（含未声明的）**一律**不在 LoadSkipping 的
+	// 管辖范围 ⇒ 必须在 skip 里。这样"调度器"与"LoadSkipping"两条路
+	// **按构造不相交**，不可能双加载。
+	//
+	// （我第一版只 skip declared/manual/disabled ⇒ 未声明的外部插件会被
+	//  两条路各加载一次。实测变异：healthcheck loaded 2 次、工具 87→161。）
+	if !skip["undeclared"] {
+		t.Fatal("★ catalog 里登记的插件都必须在 skip 里 —— " +
+			"否则未声明的外部插件会被调度器与 LoadSkipping **各加载一次**" +
+			"（实测：工具数翻倍）")
+	}
+	// ★ 反向钉住：LoadSkipping 仍必须能加载**内置插件**（不在 catalog 里）
+	if skip["some_builtin_without_manifest"] {
+		t.Fatal("★ 内置插件（无 plugin.json，不在 catalog）不得被 skip —— " +
+			"它是 LoadSkipping 唯一能加载的对象")
+	}
+}
diff --git a/internal/kernelmod/pluginhost/migrate_adapter.go b/internal/kernelmod/pluginhost/migrate_adapter.go
new file mode 100644
index 00000000..e809415c
--- /dev/null
+++ b/internal/kernelmod/pluginhost/migrate_adapter.go
@@ -0,0 +1,60 @@
+package pluginhost
+
+// 把**真实的** plugin.Registry 接到 kernelboot.PluginQuiescer（伪关机用）。
+//
+// ## 为什么需要适配器而不是让 kernelboot 直接依赖 plugin
+//
+// kernelboot 是装配内核，plugin 是插件系统 —— 后者依赖前者（模块声明依赖），
+// 反向 import 就成环。⇒ 用一个小接口 + 适配器隔开。
+//
+// ## ★ 为什么是 StopPlugin/StartPlugin，不是 StopAll
+//
+// 三态生命周期早已存在（自动启动 / 启用但不自动启动 / 禁用），而
+// `StopPlugin`/`StartPlugin` 是**运行态**操作：
+//
+//	· 不写 disabled_plugins ⇒ 不改用户决定
+//	· 不置 shuttingDown    ⇒ 之后还能重新加载（**可逆**）
+//	· 会摘掉注册面         ⇒ 停完模型看不到也调不到（彻底）
+//
+// `StopAll` 完全相反：置 shuttingDown 后插件**永久无法再加载**，
+// 那是进程退出用的。用它做伪关机 = 关了就起不来。
+//
+// ## 为什么跳过自身与 UI
+//
+// `refuseSelfLock` 已经拒绝了 pluginmgr（自锁，停了就没法再启）与 webui
+// （停了 UI 就失联，迁移进度看不见）。这里**主动跳过**而不是去撞错误：
+// 迁移期间我们需要 UI 报告进度，撞错只会让日志充满噪声。
+
+import "github.com/JianFeeeee/HomeAgent/internal/plugin"
+
+// RegistryQuiescer 适配 *plugin.Registry → kernelboot.PluginQuiescer。
+type RegistryQuiescer struct{ Reg *plugin.Registry }
+
+// StopPluginRuntime 运行态停掉一个插件（不改持久状态）。
+func (r RegistryQuiescer) StopPluginRuntime(name string) error {
+	return r.Reg.StopPlugin(name)
+}
+
+// StartPluginRuntime 运行态拉起一个插件。
+func (r RegistryQuiescer) StartPluginRuntime(name string) error {
+	return r.Reg.StartPlugin(name)
+}
+
+// RunningPlugins 返回当前在运行的插件名。
+//
+// ★ 排除 pluginmgr 与 webui：前者停了无法再启（自锁），后者是迁移进度的
+// 唯一可视通道。这与 refuseSelfLock 的口径一致，但在这里**提前排除**
+// 而不是靠报错兜底（报错会进入 BeginMigration 的回滚路径，把正常迁移搞挂）。
+func (r RegistryQuiescer) RunningPlugins() []string {
+	// Registry.List() 返回 r.plugins 的键集 = **当前已加载并运行**的插件
+	// （StopPlugin 会从该 map 删除 ⇒ 停掉的自然不在其中）。
+	all := r.Reg.List()
+	out := make([]string, 0, len(all))
+	for _, n := range all {
+		if n == "pluginmgr" || n == "webui" {
+			continue
+		}
+		out = append(out, n)
+	}
+	return out
+}
diff --git a/internal/kernelmod/pluginhost/mod.go b/internal/kernelmod/pluginhost/mod.go
new file mode 100644
index 00000000..05672610
--- /dev/null
+++ b/internal/kernelmod/pluginhost/mod.go
@@ -0,0 +1,352 @@
+package pluginhost
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/supervisor"
+)
+
+// FacPlugins 是本模块提供的设施名。
+//
+// 意义：**"谁是最后一批被拉起的插件"** —— 声明 `plugins` 的插件要等所有
+// 自动启动的插件都起完才起（如"插件总览"类插件）。
+const FacPlugins = "plugins"
+
+// Module 是插件宿主：扫元数据、按形态分流、按依赖时机拉起。
+type Module struct{}
+
+func (Module) Name() string { return "plugin-host" }
+
+// Requires：插件**加载**所需的全部前置 —— **刻意不含 agent**。
+//
+// ★ 这是本模块存在的关键价值（用户方案 A 的核心收益）：
+// 原先 wirePluginSDK 在 agent 模块里 ⇒ 插件加载被排在 agent 之后，
+// 而 agent 层实测 **35 秒**（context dense backfill 750 events + 重建索引）。
+//
+// 而插件真正需要的只是 stage-host（Registry + StageHost）与几个底层设施。
+// agent 相关的两项（StatusProvider / TerminalAPI）改为**后补注入**（见
+// agent 模块），插件在 Start 阶段不用它们（唯一的 healthcheck 是 nil-guarded）。
+func (Module) Requires() []string {
+	return []string{
+		kernelmod.FacConfig, kernelmod.FacKernelIO, kernelmod.FacMemory,
+		kernelmod.FacLua, kernelmod.FacSupervisor, kernelmod.FacTracker,
+		kernelmod.FacTextMem, kernelmod.FacDocStore, kernelmod.FacKnowledge,
+		kernelmod.FacStageHost,
+	}
+}
+
+func (Module) Provides() []string { return []string{FacPlugins} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	// ── 前置检查（用户要求："nil 加读取前检查"）──
+	if ks.PluginRegistry == nil || ks.StageHost == nil {
+		return fmt.Errorf("plugin-host：ks.PluginRegistry/StageHost 为 nil —— " +
+			"stage-host 模块必须先完成（插件加载的硬前置）")
+	}
+	if ks.Cfg == nil {
+		return fmt.Errorf("plugin-host：ks.Cfg 为 nil —— config 模块必须先完成")
+	}
+	if ks.CfgReg == nil || ks.DataDir == "" {
+		return fmt.Errorf("plugin-host：CfgReg/DataDir 为 nil/空 —— Group 0 必须先完成")
+	}
+
+	// ── ① 注入插件 SDK 的**底层依赖**（不含 agent 相关的两项）──
+	injectBaseDeps(ks)
+
+	// ── ② 扫一次目录 → 元数据缓存 ──
+	dir := ks.Cfg.Plugin.Dir
+	os.MkdirAll(dir, 0o755)
+	catalog, noManifest := scanCatalog(dir, ks.CfgReg.IsPluginDisabled)
+	ks.PluginCatalog = catalog
+	// ★ 措辞必须准确（我第一版写成"跳过 N 个非插件目录" ⇒ **误导**）：
+	// 那些目录大多是**内置插件**（编译期工厂，本就没有 plugin.json，
+	// 由下面的 LoadSkipping 从工厂表加载）。只有既无 manifest
+	// 又无工厂的才是真的非插件目录。
+	//
+	// 这条日志的价值在于：新增外部插件若忘写 plugin.json，会出现在这里
+	// （那时"无 manifest ⇒ 只能走工厂 ⇒ 找不到 ⇒ 不加载"，可据此发现）。
+	if len(noManifest) > 0 {
+		log.Printf("[pluginhost] %d 个目录无 plugin.json（内置插件属正常：它们由编译期工厂加载）: %v",
+			len(noManifest), noManifest)
+	}
+	log.Printf("[pluginhost] 外部插件元数据缓存就绪：%d 个（目录 %s）",
+		catalog.Size(), dir)
+
+	// ── ③ 按**三形态**分流（用户设计要求）──
+	groups := classify(catalog)
+	log.Printf("[pluginhost] 形态分流：自动启动 %d / 声明了依赖 %d / "+
+		"启用但不自动启动 %d / 持久禁用 %d",
+		len(groups.autoStart), len(groups.declared),
+		len(groups.manual), len(groups.disabled))
+
+	// ── ④ 拉起：**全部自动启动的插件都交给 Scheduler** ──
+	//
+	// ★★ 我第一版在这里犯了一个**违反硬约束**的错，值得完整记录：
+	//
+	// 第一版按"本模块依赖是否覆盖插件声明"把插件分成 launchNow / waitLater，
+	// 并在 Init 里**直接**把 launchNow 全加载了。
+	// 但**未声明依赖**的插件，`RequiresFacilities` 是空 ⇒ "本模块依赖覆盖空集"
+	// 恒真 ⇒ 它们被归入 launchNow ⇒ **在第 4 层就被加载**。
+	//
+	// 而 §2.6.5 的硬约束是：
+	//
+	//     未声明 ⇒ 启动时机**逐字不变**（内核**完全**初始化完成后）
+	//
+	// 实测证据（planA4.log）：内置插件在 `21:54:37`（第 4 层）被加载，
+	// 而内核装配完成是 `21:55:12` —— **早了 35 秒**。
+	// 约束原文写着"静默改变启动时机 = 静默引入竞态"，
+	// 42 个存量插件里任何一个若假设"Start 时 llm 一定已就绪"就会中招。
+	//
+	// ⇒ 修法：**不再自己判时机**，全部交给 `kernelboot.Scheduler`
+	// ——它已正确实现 §2.6.5（空声明 ⇒ 等 `KernelComplete()`）与
+	// §2.6.6（`!AutoStart` ⇒ 不自动拉起），且有完整判据。
+	// 我只需要提供"拉起一个插件"的动作。
+	//
+	// 这样声明的插件仍在依赖就绪时尽早启动（本步的核心收益不变），
+	// 而未声明的**恢复原行为**（等内核完全初始化）。
+	var bus kernelboot.SyncState
+	var busConcrete *kernelboot.SyncBus // 保留具体类型以便订阅 OnUpdate
+	if ks.SyncBus != nil {
+		bus = ks.SyncBus
+		busConcrete = ks.SyncBus
+	} else {
+		// ★★ typed-nil 陷阱：`var nb *SyncBus; var i SyncState = nb`
+		// ⇒ i **非 nil** ⇒ 方法里解引用空指针 panic（实测复现）。
+		// 所以这里必须显式判 `!= nil` 再赋给接口变量。
+		log.Printf("[pluginhost] warning: SyncBus 为空 —— 非生产装配路径，" +
+			"退化为立即加载（依赖未就绪的插件在 Start 时自行处理）")
+		fallback := kernelboot.NewSyncBus()
+		fallback.MarkKernelComplete()
+		bus = fallback
+		busConcrete = fallback
+	}
+
+	sched := kernelboot.NewScheduler(bus, func(spec kernelboot.PluginSpec) error {
+		return ks.PluginRegistry.LoadOneDir(filepath.Join(dir, spec.Name), spec.Name)
+	})
+	sched.SetLaunchErrorHandler(func(spec kernelboot.PluginSpec, err error) {
+		log.Printf("[pluginhost] warning: 拉起 %s 失败: %v", spec.Name, err)
+	})
+	ks.PluginScheduler = sched
+
+	specs := buildSpecs(catalog, groups)
+	// Submit 返回"此刻就能拉起"的：
+	//   · 声明了依赖且已全就绪  ⇒ 立即拉起（**本步的核心收益**）
+	//   · 未声明的              ⇒ 不进返回列表（等 KernelComplete，§2.6.5）
+	//   · !AutoStart            ⇒ 不进（§2.6.6）
+	// 同时 Submit 会做拼错校验（声明的设施名内核从未注册 ⇒ 立即报错）。
+	for _, n := range sched.Submit(specs) {
+		log.Printf("[pluginhost] 插件已拉起（依赖已就绪，早于装配完成）: %s", n)
+	}
+
+	// ── ⑤ 加载**内置插件**（编译期工厂，**没有 plugin.json**）──
+	//
+	// ★★ 这一步是我第一版漏掉的（实测：19 个内置插件全部没加载 ——
+	// webui / pluginmgr / cli / files / timer / mcp …，只剩 2 个外部插件起）。
+	//
+	// 原因：上面的 catalog 是**扫目录读 plugin.json** 得来的，
+	// 而内置插件是**编译期注册的工厂**（`plugin.RegisterFactory` 在 init() 里），
+	// 目录里可能连 plugin.json 都没有 ⇒ 表里根本没有它们。
+	//
+	// 走 `LoadSkipping(dir, skip)`：它内部既扫目录（外部插件）
+	// 也遍历工厂（内置插件），是**唯一完整**的加载入口。
+	// skip 集合 = 已由本模块调度处理的那些（按三形态分流的），
+	// 避免重复加载。
+	// ── ⑤ 其余插件（未声明的 + 内置）→ **等内核完全初始化**后加载 ──
+	//
+	// ★ 为什么不能在这里直接 LoadSkipping（我第一版的第二个错）：
+	// plugin-host 在第 4 层，而 agent 与它**并行** ⇒ 此刻内核**尚未**
+	// 完全初始化。直接加载同样违反 §2.6.5 的"未声明 ⇒ 逐字不变"。
+	//
+	// ⇒ 挂到 syncbus 的 `KernelComplete` 上（内核**推**状态，不轮询）。
+	//
+	// skip = 已由 Scheduler 接管的（declared ∪ manual ∪ disabled）。
+	// 不在 skip 里的：未声明的外部插件 + **内置插件**（编译期工厂，
+	// 不在 catalog 里，只有 LoadSkipping 的工厂分支能加载它们）。
+	skip := buildSkipSet(catalog, groups)
+	var loadOnce sync.Once
+	loadRest := func(st kernelboot.SyncState) {
+		if !st.KernelComplete() {
+			return
+		}
+		loadOnce.Do(func() {
+			if err := ks.PluginRegistry.LoadSkipping(dir, skip); err != nil {
+				log.Printf("[pluginhost] warning: 加载内置/未声明插件: %v", err)
+			}
+			ks.PluginsReady = true
+			log.Printf("[pluginhost] 内核完全初始化 → 已加载其余插件（含 %d 个内置）",
+				len(noManifest))
+		})
+	}
+	// 订阅 + 立即评估一次（若 bus 已 complete，比如非生产路径的退化 bus）
+	// ★ 订阅用**具体类型**的 SyncBus（SyncState 是**只读接口**，
+	// 故意没有 OnUpdate —— 设计 §2.6.3 "插件管理器对 syncbus 只读"）。
+	// 本模块是内核模块，本就持有具体类型，无需放宽接口。
+	if busConcrete != nil {
+		busConcrete.OnUpdate(loadRest)
+	}
+	loadRest(bus)
+
+	log.Printf("[pluginhost] 本阶段：声明了依赖的 %d 个由调度器处理"+
+		"（已就绪的已拉起），未声明的 %d 个 + 内置 %d 个等内核完全初始化",
+		len(groups.declared), len(groups.autoStart)-len(groups.declared), len(noManifest))
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
+
+// buildSpecs 把"自动启动"的插件元数据转成调度器声明。
+//
+// ## ★ 为什么**未声明**的插件也要进来（我第一版漏了这个语义）
+//
+// 第一版把"未声明依赖"的插件排除在调度器之外、在 Init 里直接加载
+// ⇒ 它们在第 4 层（agent 并行期间）就起了，而 §2.6.5 要求"等内核
+// **完全**初始化"。实测后果：`healthcheck` 的 `s.Status()` 为 nil
+// ⇒ **静默少注册一个工具** `healthcheck_kernel`（86 vs 87，无任何报错）。
+//
+// ⇒ 全部自动启动的插件都交给调度器；调度器对空声明返回
+// `KernelComplete()`（§2.6.5），正是原行为。
+func buildSpecs(c *PluginCatalog, g formGroups) []kernelboot.PluginSpec {
+	var out []kernelboot.PluginSpec
+	for _, n := range g.autoStart {
+		m, ok := c.Get(n)
+		if !ok {
+			continue
+		}
+		out = append(out, kernelboot.PluginSpec{
+			Name:               m.Name,
+			RequiresFacilities: m.RequiresFacilities,
+			AutoStart:          m.AutoStart,
+		})
+	}
+	return out
+}
+
+// buildSkipSet 计算"不能让全量 LoadSkipping 碰"的插件名集合。
+//
+// ## ★ 为什么抽成独立函数（判据要求）
+//
+// 初版把这段逻辑内联在 Init 里 ⇒ 判据只能查源码字符串 ⇒
+// 删掉代码但注释仍在时**判据不咬**（实测）。
+// 抽出来后可**真的调用它**做行为断言（TestBuiltinsAreNotSkipped）。
+//
+// ## 集合语义（三形态 + 内置插件的边界）
+//
+//	② auto_start=false ⇒ 必须在集合里（否则会被全量加载 = 违背语义）
+//	③ disabled        ⇒ 在集合里（显式跳过；registry 还有禁用门兜底）
+//	① 声明的          ⇒ 由本模块按依赖时机拉起 ⇒ 必须在集合里（防重复）
+//	**内置插件**      ⇒ **不在**集合里 ⇒ 走 LoadSkipping 的工厂分支被加载
+//	                    ★ 这正是我第一版漏掉的关键：内置插件没有 plugin.json，
+//	                      不在 catalog 里，只有 LoadSkipping 的工厂分支能加载它们。
+func buildSkipSet(c *PluginCatalog, g formGroups) map[string]bool {
+	skip := map[string]bool{}
+	// ★★ 原则：**catalog 里登记过的插件，一律不交给 LoadSkipping**。
+	//
+	// ## 为什么不是"只跳过 declared/manual/disabled"（我第一版就是这么写的）
+	//
+	// 那会让**未声明的外部插件**同时被两条路加载：
+	//   · 调度器（它管未声明的，等 KernelComplete 后拉起）
+	//   · LoadSkipping（未声明的**不在** skip 里 ⇒ 也加载）
+	//
+	// 实测（变异 F，把 LoadSkipping 挪回 Init）：`healthcheck` 被 loaded **两次**，
+	// 工具数 87 → **161**（重复注册）。planA5 侥幸未触发，只因测试目录里
+	// 那 3 个外部插件恰好都声明了依赖或不自启 —— **不能依赖这种巧合**。
+	//
+	// ⇒ 改成**按构造**消除：catalog 里的全部（三形态之一）都由本模块/调度器
+	// 负责；LoadSkipping 只处理 catalog **之外**的，也就是那些
+	// **没有 plugin.json 的内置插件**（编译期工厂，只有它能加载）。
+	//
+	// 这样两条路**按定义**不相交。
+	for _, n := range c.Names() {
+		skip[n] = true
+	}
+	// 保底：三形态里若有 catalog 未收录的（理论上不会），也别漏
+	for _, n := range g.autoStart {
+		skip[n] = true
+	}
+	for _, n := range g.manual {
+		skip[n] = true
+	}
+	for _, n := range g.disabled {
+		skip[n] = true
+	}
+	return skip
+}
+
+// injectBaseDeps 注入插件 SDK 的底层依赖（原 wirePluginSDK 的 7 项）。
+//
+// ★ 这里**刻意不做** SetStatusProvider / SetTerminalAPI —— 它们依赖 agent，
+// 由 agent 模块**后补注入**（见其注释）。这不是遗漏，是有意的分层：
+// 让插件加载不必等 agent 那 35 秒。
+func injectBaseDeps(ks *kernelboot.KernelState) {
+	reg := ks.PluginRegistry
+	reg.SetLuaVM(ks.LuaVM)
+	reg.SetBaseAPIKey(ks.BaseAPIKey)
+	if ks.Supervisor != nil {
+		reg.SetSupervisor(supervisor.NewSDKAdapter(ks.Supervisor))
+	}
+	reg.SetTracker(ks.Tracker)
+	reg.SetConfig(ks.Cfg)
+	reg.SetStageHost(ks.StageHost)
+
+	if ks.Memory != nil {
+		reg.SetIndexer(ks.Memory.Indexer)
+	}
+}
+
+// formGroups 是三形态分流结果。
+//
+// ★ 用户明确要求的三种形态（§2.6.6）：
+//
+//	① autoStart ：自动启动（缺省/true）
+//	② manual    ：**启用但不自动启动**（auto_start=false）⇒ 等显式启用
+//	③ disabled  ：禁用（disabled_plugins 配置）⇒ 不加载
+//
+// 外加 `declared`：自动启动**且声明了依赖**的子集（决定"何时"拉）。
+type formGroups struct {
+	autoStart []string // ① 自动启动的全部（含 declared）
+	declared  []string // ① 中声明了 requires_facilities 的
+	manual    []string // ② 不自动启动
+	disabled  []string // ③ 持久禁用
+}
+
+func classify(c *PluginCatalog) formGroups {
+	var g formGroups
+	for _, m := range c.All() {
+		switch {
+		case m.Disabled:
+			// ③ 禁用：最高优先级（不加载）
+			g.disabled = append(g.disabled, m.Name)
+		case !m.AutoStart:
+			// ② 启用但不自动启动：**不自动加载**，等 agent 显式启用
+			g.manual = append(g.manual, m.Name)
+		default:
+			// ① 自动启动
+			g.autoStart = append(g.autoStart, m.Name)
+			if len(m.RequiresFacilities) > 0 {
+				g.declared = append(g.declared, m.Name)
+			}
+		}
+	}
+	return g
+}
+
+// loadOne 加载单个插件（走既有 LoadOneDir 路径，不绕过任何机制）。
+func loadOne(ks *kernelboot.KernelState, dir, name string) (bool, error) {
+	if err := ks.PluginRegistry.LoadOneDir(filepath.Join(dir, name), name); err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
+// planCatalog 取元数据缓存（类型断言集中一处，便于排查"缓存没建起来"）。
+func planCatalog(ks *kernelboot.KernelState) *PluginCatalog {
+	c, _ := ks.PluginCatalog.(*PluginCatalog)
+	return c
+}
diff --git a/internal/kernelmod/pluginhost/rwmutex.go b/internal/kernelmod/pluginhost/rwmutex.go
new file mode 100644
index 00000000..10b63ec9
--- /dev/null
+++ b/internal/kernelmod/pluginhost/rwmutex.go
@@ -0,0 +1,17 @@
+package pluginhost
+
+import "sync"
+
+// rwMutex 是 sync.RWMutex 的薄包装。
+//
+// 为什么不直接用 sync.RWMutex：PluginCatalog 要能被**复制/传递**时
+// 保持清晰的所有权语义（指针字段而非嵌入值），避免"复制了含锁的结构体"
+// 这个经典的 vet 警告（copylocks）。
+type rwMutex struct{ mu sync.RWMutex }
+
+func newRWMutex() *rwMutex { return &rwMutex{} }
+
+func (m *rwMutex) RLock()   { m.mu.RLock() }
+func (m *rwMutex) RUnlock() { m.mu.RUnlock() }
+func (m *rwMutex) Lock()    { m.mu.Lock() }
+func (m *rwMutex) Unlock()  { m.mu.Unlock() }
diff --git a/internal/kernelmod/stagehost/mod.go b/internal/kernelmod/stagehost/mod.go
new file mode 100644
index 00000000..e08cfd43
--- /dev/null
+++ b/internal/kernelmod/stagehost/mod.go
@@ -0,0 +1,97 @@
+// Package stagehost 是 stage-host 模块：阶段管道（StageHost）+ 插件注册表 + SDK 接线。
+//
+// ## 依赖
+//
+// 收 iom/evBus/mem.db/textMem/docStore/knowledge/providerMgr
+// ⇒ 声明 kernel-io / memory / textmem / docmem / knowledge / llm。
+//
+// ★ 顺序上它在 llm 之后（providerMgr 是它的参数）—— 这不是"刻意安排"，
+// 而是签名直接推出来的。
+package stagehost
+
+import (
+	"log"
+	"strings"
+
+	"github.com/JianFeeeee/HomeAgent/internal/config"
+
+	agentCore "github.com/JianFeeeee/HomeAgent/internal/agent/core"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/plugin"
+	cli "github.com/JianFeeeee/HomeAgent/internal/plugins/cli"
+	webui "github.com/JianFeeeee/HomeAgent/internal/plugins/webui"
+	"github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// Module 提供阶段管道与插件注册表。
+type Module struct{}
+
+func (Module) Name() string { return "stage-host" }
+func (Module) Requires() []string {
+	return []string{kernelmod.FacKernelIO, kernelmod.FacMemory, kernelmod.FacTextMem,
+		kernelmod.FacDocStore, kernelmod.FacKnowledge, kernelmod.FacLLM}
+}
+func (Module) Provides() []string { return []string{kernelmod.FacStageHost} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	stageHost := agentCore.NewStageHost()
+
+	pluginReg := plugin.NewRegistry()
+	pluginReg.SetIOManager(ks.IO)
+	pluginReg.SetEventBus(ks.EventBus)
+	pluginReg.SetMemory(ks.Memory.DB)
+	pluginReg.SetTextMemory(ks.TextMemory)
+	pluginReg.SetDocStore(ks.DocStore)
+	pluginReg.SetKnowledge(ks.Knowledge)
+	pluginReg.SetProviderManager(ks.LLMManager)
+	pluginReg.SetConfigRegistry(ks.CfgReg)
+	pluginReg.SetPluginDir(ks.Cfg.Plugin.Dir)
+	pluginReg.SetDataDir(ks.DataDir) // 插件 SettingsAPI.DataDir() 的数据根目录
+
+	// Wire registration callbacks: plugins' RegisterTool/RegisterStage → StageHost
+	pluginReg.SetToolRegistrar(func(name string, def sdk.ToolDef, handler sdk.ToolHandler) error {
+		log.Printf("[homed] SetToolRegistrar registering tool: %s (plugin=%s)", name, def.Plugin)
+		return stageHost.RegisterTool(name, def, handler)
+	})
+	pluginReg.SetStageRegistrar(func(stage sdk.Stage, handler sdk.StageHandler) {
+		stageHost.RegisterStage(stage, handler)
+	})
+	pluginReg.SetAPIRegistrar(func(name string) error { return nil })
+	pluginReg.SetToolCleaner(stageHost)
+
+	ks.StageHost = stageHost
+	ks.PluginRegistry = pluginReg
+
+	// ★ 这两行必须在插件 Start（loadPlugins）**之前**设置：
+	// CLI 插件的 unix socket 路径，与 webui 的监听地址覆盖。
+	//
+	// 归入本模块的理由：它们都是**插件读的配置**，与插件系统同生共死。
+	// （原先它们在 main 里紧邻 loadPlugins —— 声明式下"同模块"是等价保证。）
+	cli.DefaultSocket = ks.CLISocket
+	webui.SetListenOverride(resolveWebUIOverride(ks.CfgReg, ks.HTTPAddr))
+	return nil
+}
+
+// resolveWebUIOverride 解析 webui 监听地址的覆盖值，空串表示不覆盖。
+//
+// 优先级：CLI --webui > 核心配置 webui.listen_addr（仅当被改成非内置默认值）。
+// 两者都不给时由 webui 插件自己的 settings["addr"] 决定。
+//
+// 为什么不写成"内核在插件加载前 Set 插件 settings['addr']"：那时
+// config_webui 表还没建（表只在插件注册 def 时创建），PluginSettings.Set 的
+// INSERT 会失败而错误被忽略，随后插件 Start 里 RegisterDef 才建表并写入默认
+// :8080 —— 于是 CLI --webui 与 webui.listen_addr **一直是死配置**。
+func resolveWebUIOverride(cfgReg *config.ConfigRegistry, httpAddr string) string {
+	if strings.TrimSpace(httpAddr) != "" {
+		return strings.TrimSpace(httpAddr)
+	}
+	// webui.listen_addr 的播种默认值就是 ":8080"；与默认值相同视为"未配置"，
+	// 否则会把用户在设置页里改过的插件 addr 顶掉。
+	if v := strings.TrimSpace(cfgReg.GetString("webui.listen_addr", ":8080")); v != "" && v != ":8080" {
+		return v
+	}
+	return ""
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/supervisor/mod.go b/internal/kernelmod/supervisor/mod.go
new file mode 100644
index 00000000..9f741494
--- /dev/null
+++ b/internal/kernelmod/supervisor/mod.go
@@ -0,0 +1,32 @@
+// Package supervisor 是 supervisor 模块：代理生命周期守护。
+//
+// 依赖 config：`initSupervisor(cfg)` 收 cfg。
+//
+// ★ 全仓唯一有 `log.Fatalf` 的 init*（其余都是记日志不中断）⇒ 它**必须成功**。
+package supervisor
+
+import (
+	"log"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/supervisor"
+)
+
+// Module 提供代理生命周期守护。
+type Module struct{}
+
+func (Module) Name() string       { return "supervisor" }
+func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
+func (Module) Provides() []string { return []string{kernelmod.FacSupervisor} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	sup := supervisor.New(ks.Cfg)
+	if err := sup.Start(); err != nil {
+		log.Fatalf("start supervisor: %v", err)
+	}
+	ks.Supervisor = sup
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/textmem/mod.go b/internal/kernelmod/textmem/mod.go
new file mode 100644
index 00000000..89e95409
--- /dev/null
+++ b/internal/kernelmod/textmem/mod.go
@@ -0,0 +1,61 @@
+// Package textmem 是 text-memory 模块：文本记忆。
+//
+// ## ★ 显式依赖 onnx-parser —— 一条**签名看不到**的依赖
+//
+// 候选消费管线会启动蒸馏循环，而蒸馏路径在**运行期**读
+// `nlp.defaultParser`（包级单例，由 onnx 模块写）：
+//
+//	distiller.Start() → go distillLoop() → distillOnce()
+//	  → extractKeyTriples() → nlp.NewExtractor(nil)
+//	    → 构造时快照 defaultParser（parser.go:60）
+//
+// 原 main 的顺序是**反的**（蒸馏在 226 行启动、解析器 289 行才装上），
+// 目前**碰巧安全** —— `distillLoop` 用 ticker，首个 tick 要等
+// `Interval = 10 分钟`，那时解析器早装好了。
+//
+// ★ 但"碰巧安全"不是保证：Interval 变小或解析器装配更后 ⇒ **静默降级**
+// （defaultParser 为 nil ⇒ POS 模板抽不出 ⇒ 图记忆实体退化成整句复合值
+// ⇒ 跨维度检索全失效，基线 0/5。该后果由 pipeline.go:60 注释记录。）
+//
+// ⇒ 声明出来就是**结构保证**：两者不同层，分层器保证先后。
+package textmem
+
+import (
+	"log"
+	"path/filepath"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/memory/text"
+)
+
+// Module 提供文本记忆。
+type Module struct{}
+
+func (Module) Name() string { return "text-memory" }
+func (Module) Requires() []string {
+	// onnx-parser：见包注释（隐藏依赖，显式声明）。
+	return []string{kernelmod.FacConfig, kernelmod.FacMemory,
+		kernelmod.FacKernelIO, kernelmod.FacONNX}
+}
+func (Module) Provides() []string { return []string{kernelmod.FacTextMem} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	textMem := text.New(filepath.Join(ks.Cfg.Daemon.DataDir, "memory", "text"))
+	if err := textMem.Start(); err != nil {
+		log.Printf("[homed] warning: text memory start: %v", err)
+		ks.TextMemory = textMem
+		return nil
+	}
+	log.Printf("[homed] text memory active at %s", filepath.Join(ks.Cfg.Daemon.DataDir, "memory", "text"))
+	ks.TextMemory = textMem
+	// ★ 伪关机登记（迁移数据目录用）：text memory 的 rotationLoop 会周期性写盘。
+	ks.AddQuiescer("textmem",
+		func() error { return textMem.Pause() },
+		func() error { return textMem.Resume() })
+
+	ks.AddCloser(textMem.Stop)
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/kernelmod/tracker/mod.go b/internal/kernelmod/tracker/mod.go
new file mode 100644
index 00000000..d6a8e8fa
--- /dev/null
+++ b/internal/kernelmod/tracker/mod.go
@@ -0,0 +1,38 @@
+// Package tracker 是 tracker 模块：变更追踪（overlayfs）。
+//
+// 依赖 config + AgentWorkDir（后者由 Group 0 的 ensureDataDirs 产出）。
+package tracker
+
+import (
+	"log"
+	"time"
+
+	"github.com/JianFeeeee/HomeAgent/internal/kernelboot"
+	"github.com/JianFeeeee/HomeAgent/internal/kernelmod"
+	"github.com/JianFeeeee/HomeAgent/internal/tracker"
+)
+
+// Module 提供变更追踪。
+type Module struct{}
+
+func (Module) Name() string       { return "tracker" }
+func (Module) Requires() []string { return []string{kernelmod.FacConfig} }
+func (Module) Provides() []string { return []string{kernelmod.FacTracker} }
+
+func (Module) Init(ks *kernelboot.KernelState) error {
+	trk := tracker.NewTracker(ks.Cfg.Daemon.DataDir, ks.AgentWorkDir,
+		tracker.WithKeepChangesets(100),
+		tracker.WithMaxChangesetAge(30*24*time.Hour),
+	)
+	if err := trk.Init(); err != nil {
+		log.Printf("[homed] warning: tracker init: %v", err)
+	} else if err := trk.Start(); err != nil {
+		log.Printf("[homed] warning: tracker mount overlay: %v (non-fatal: no overlayfs support?)", err)
+	} else {
+		log.Printf("[homed] change tracker active at %s", trk.MergeDir())
+	}
+	ks.Tracker = trk
+	return nil
+}
+
+func init() { kernelmod.Register(Module{}) }
diff --git a/internal/knowledge/knowledge.go b/internal/knowledge/knowledge.go
index ae9cb552..998a4ef5 100644
--- a/internal/knowledge/knowledge.go
+++ b/internal/knowledge/knowledge.go
@@ -132,7 +132,6 @@ type Store struct {
 	mu    sync.RWMutex
 	items map[string]*Knowledge
 
-
 	indexPath      string
 	denseCachePath string
 	denseDirty     bool
diff --git a/internal/log/compressor.go b/internal/log/compressor.go
index b7446a42..b11bf9a5 100644
--- a/internal/log/compressor.go
+++ b/internal/log/compressor.go
@@ -18,7 +18,7 @@ var weekRe = regexp.MustCompile(`^week_(\d{4})-W(\d{2})\.tar\.gz$`)
 var monthRe = regexp.MustCompile(`^month_(\d{4}-\d{2})\.tar\.gz$`)
 
 type fileGroup struct {
-	name string
+	name  string
 	files []string
 }
 
diff --git a/internal/log/manager.go b/internal/log/manager.go
index 74e1a1a2..ba402ba1 100644
--- a/internal/log/manager.go
+++ b/internal/log/manager.go
@@ -2,7 +2,9 @@ package log
 
 import (
 	"context"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"log"
+	"sync"
 	"time"
 )
 
@@ -13,9 +15,10 @@ type ConfigProvider interface {
 }
 
 type Manager struct {
-	logDir string
-	cfg    ConfigProvider
-	done   chan struct{}
+	doneOnce sync.Once
+	logDir   string
+	cfg      ConfigProvider
+	done     chan struct{}
 }
 
 func NewManager(logDir string, cfg ConfigProvider) *Manager {
@@ -28,8 +31,13 @@ func (m *Manager) Start(ctx context.Context) {
 	go m.runLoop(ctx, "yearly", 24*time.Hour, m.yearlyTick, m.compressYearly)
 }
 
+// Stop 幂等（本仓 close 纪律：见 internal/safeclose）。
+//
+// 原先裸 `close(m.done)`：只在"单次停机"这一**隐式前提**下安全。
+// 一旦将来多一条调用路径（重载、热更新、defer + 显式），就会
+// `panic: close of closed channel` —— 而那种改动看起来与 close 无关。
 func (m *Manager) Stop() {
-	close(m.done)
+	safeclose.Safe(&m.doneOnce, m.done)
 }
 
 func (m *Manager) runLoop(ctx context.Context, name string, tickInterval time.Duration, nextFn func() time.Duration, work func(string) error) {
diff --git a/internal/log/retention.go b/internal/log/retention.go
index fdffd147..93fa46d9 100644
--- a/internal/log/retention.go
+++ b/internal/log/retention.go
@@ -91,5 +91,3 @@ func cleanupAll(logDir, prefix string) {
 		}
 	}
 }
-
-
diff --git a/internal/memory/block.go b/internal/memory/block.go
index 204be22d..4a023b1e 100644
--- a/internal/memory/block.go
+++ b/internal/memory/block.go
@@ -40,15 +40,15 @@ type MemoryBlock struct {
 	//
 	// 落盘形态随所在层而定：L0/L1 的块内联在 JSON 里（Data 序列化为 base64），
 	// L3 的块落 SQLite 的 BLOB 列。无论哪层，字节都不脱离块单独存在。
-	Data []byte `json:"data,omitempty"`
-	MIME          string        `json:"mime,omitempty"`
-	Size          int64         `json:"size,omitempty"`
-	Width         int           `json:"width,omitempty"`
-	Height        int           `json:"height,omitempty"`
-	Vector        []float64     `json:"vector,omitempty"`
-	Fingerprint   string        `json:"fingerprint,omitempty"`
-	Source        string        `json:"source,omitempty"`
-	Tool          string        `json:"tool,omitempty"`
+	Data        []byte    `json:"data,omitempty"`
+	MIME        string    `json:"mime,omitempty"`
+	Size        int64     `json:"size,omitempty"`
+	Width       int       `json:"width,omitempty"`
+	Height      int       `json:"height,omitempty"`
+	Vector      []float64 `json:"vector,omitempty"`
+	Fingerprint string    `json:"fingerprint,omitempty"`
+	Source      string    `json:"source,omitempty"`
+	Tool        string    `json:"tool,omitempty"`
 	// Scene 是这个块所属的场景键（可空）。
 	//
 	// 块是记忆流水线里最细的「子项目」：一段转写、一张图的描述、一份附件。
@@ -295,6 +295,7 @@ func (g *GraphDB) MemoryBlocks() ([]MemoryBlock, error) {
 //	结果媒体与召回测试大面积变红（列数不匹配 ⇒ 读失败）。
 //
 //	单靠“记得同步”不可靠；提成常量后新增查询直接复用。
+//
 // blockColumns 是 memory_blocks 的**元数据**列清单，供所有常规读取复用。
 //
 // ★ 为何**不含 data**：媒体负载动辄数 MB（生产实测：图均 495KB、最大 2.7MB），
diff --git a/internal/memory/migrate_blockdata_test.go b/internal/memory/migrate_blockdata_test.go
index 3d4d2464..4f01172e 100644
--- a/internal/memory/migrate_blockdata_test.go
+++ b/internal/memory/migrate_blockdata_test.go
@@ -8,8 +8,9 @@ import (
 // BackfillBlockData 把旧 CAS（payload_digest）的字节搬进块自身的 data 列。
 //
 // ★ 测试不 import internal/memory/media：字节来源是注入的 resolver，
-//   正是为了让 memory 包对 CAS 零依赖（step⑥ 要删 media 包）。
-//   真实 CAS 读盘 + 生产数据 e2e 由 cmd/homed-media-backfill 承担。
+//
+//	正是为了让 memory 包对 CAS 零依赖（step⑥ 要删 media 包）。
+//	真实 CAS 读盘 + 生产数据 e2e 由 cmd/homed-media-backfill 承担。
 //
 // 判据是**不变量**而不是「函数被调过」：
 //  1. 回填后 BlockData(id) 能取回字节，且与来源逐字节一致
diff --git a/internal/memory/pipeline/pipeline.go b/internal/memory/pipeline/pipeline.go
index 71d8d485..d83e3fee 100644
--- a/internal/memory/pipeline/pipeline.go
+++ b/internal/memory/pipeline/pipeline.go
@@ -16,6 +16,7 @@ import (
 	"github.com/JianFeeeee/HomeAgent/internal/memory"
 	"github.com/JianFeeeee/HomeAgent/internal/memory/distill"
 	"github.com/JianFeeeee/HomeAgent/internal/nlp"
+	"github.com/JianFeeeee/HomeAgent/internal/safeclose"
 )
 
 type RawRecord struct {
@@ -40,6 +41,10 @@ type DistillerConfig struct {
 }
 
 type Distiller struct {
+	pauseMu  sync.Mutex
+	paused   bool
+	pauseCh  chan struct{}
+	inflight sync.WaitGroup
 	mu       sync.Mutex
 	db       *memory.GraphDB
 	rawPath  string
@@ -93,6 +98,7 @@ func NewDistiller(db *memory.GraphDB, dataDir string, cfg DistillerConfig) *Dist
 		cfg:     cfg,
 		ctx:     ctx,
 		cancel:  cancel,
+		pauseCh: make(chan struct{}, 1),
 	}
 }
 
@@ -253,15 +259,94 @@ func (d *Distiller) distillLoop() {
 	ticker := time.NewTicker(d.cfg.Interval)
 	defer ticker.Stop()
 	for {
+		// ★ 伪关机门（Quiesce/Resume）：迁移数据目录时必须完全不写。
+		//
+		// 为什么不用 cancel：cancel 是**不可逆**的，恢复只能重建整个 Distiller
+		// （而它持有 rawPath/records 状态）。迁移要"停下来→搬→再起来" ⇒ 需要可逆。
+		if paused := d.waitNotPaused(); paused {
+			return
+		}
 		select {
 		case <-ticker.C:
+			if d.isPaused() {
+				continue // 暂停期间跳过本轮，避免"刚好卡在检查后开始写"
+			}
+			d.inflight.Add(1)
 			d.distillOnce()
+			d.inflight.Done()
 		case <-d.ctx.Done():
 			return
 		}
 	}
 }
 
+// waitNotPaused 阻塞到未被暂停；返回 true 表示 ctx 已取消（应退出循环）。
+func (d *Distiller) waitNotPaused() bool {
+	for d.isPaused() {
+		select {
+		case <-d.pauseCh: // 被 Resume 唤醒，重新检查
+		case <-d.ctx.Done():
+			return true
+		}
+	}
+	return false
+}
+
+func (d *Distiller) isPaused() bool {
+	d.pauseMu.Lock()
+	defer d.pauseMu.Unlock()
+	return d.paused
+}
+
+// Pause 伪关机：停止写入并**等待在途蒸馏完成**（可逆）。
+//
+// 语义保证（迁移依赖这三条）：
+//  1. 返回后**不会再有新的** distillOnce 开始
+//  2. 已在跑的那次 distillOnce 会**跑完**（inflight 归零才返回）
+//     ——否则迁移会搬走一个写了一半的库
+//  3. 幂等：重复 Pause 不报错
+func (d *Distiller) Pause() error {
+	d.pauseMu.Lock()
+	if d.paused {
+		d.pauseMu.Unlock()
+		return nil
+	}
+	d.paused = true
+	d.pauseMu.Unlock()
+
+	// 等在途的那一次结束（最多等到 ctx 取消）
+	//
+	// ★ 用 safeclose.Safe 而不是裸 close：本仓 close 纪律要求"只要调 close
+	// 就要有前置检查"（见 internal/safeclose 的判据）。这里虽然当前只有
+	// 一个 goroutine 会 close，但将来加一条错误/超时/重连路径就可能变成两次，
+	// 而那次改动看起来与 close 无关 ⇒ 退出路径 panic。
+	done := make(chan struct{})
+	var doneOnce sync.Once
+	go func() { d.inflight.Wait(); safeclose.Safe(&doneOnce, done) }()
+	select {
+	case <-done:
+		return nil
+	case <-d.ctx.Done():
+		return nil
+	}
+}
+
+// Resume 唤醒：允许再次写入。
+func (d *Distiller) Resume() error {
+	d.pauseMu.Lock()
+	was := d.paused
+	d.paused = false
+	d.pauseMu.Unlock()
+	if was {
+		// 唤醒所有在 waitNotPaused 上等的循环（非阻塞广播）
+		select {
+		case d.pauseCh <- struct{}{}:
+		default:
+		}
+	}
+	return nil
+}
+
 func (d *Distiller) distillOnce() {
 	d.mu.Lock()
 	batchSize := d.cfg.BatchSize
diff --git a/internal/memory/prod_copy_regression_test.go b/internal/memory/prod_copy_regression_test.go
index 9a06f87b..872ec9f4 100644
--- a/internal/memory/prod_copy_regression_test.go
+++ b/internal/memory/prod_copy_regression_test.go
@@ -9,11 +9,12 @@ import (
 // prodCopySrc 返回生产库副本路径。
 //
 // ★ 优先读环境变量 HA_PROD_DB；未设置时用一个**占位路径**，
-//   它在 CI 与绝大多数机器上都不存在 ⇒ 上层 os.ReadFile 失败 ⇒ t.Skip。
 //
-//   取快照用（不要直接指生产库，判据会写）：
-//	sqlite3 <生产库> ".backup /tmp/graph-copy.db"
-//	HA_PROD_DB=/tmp/graph-copy.db go test -run ProdCopy ./internal/memory/
+//	  它在 CI 与绝大多数机器上都不存在 ⇒ 上层 os.ReadFile 失败 ⇒ t.Skip。
+//
+//	  取快照用（不要直接指生产库，判据会写）：
+//		sqlite3 <生产库> ".backup /tmp/graph-copy.db"
+//		HA_PROD_DB=/tmp/graph-copy.db go test -run ProdCopy ./internal/memory/
 func prodCopySrc() string {
 	if p := os.Getenv("HA_PROD_DB"); p != "" {
 		return p
diff --git a/internal/memory/sentence_block.go b/internal/memory/sentence_block.go
index 283f0263..20b8df0c 100644
--- a/internal/memory/sentence_block.go
+++ b/internal/memory/sentence_block.go
@@ -238,6 +238,7 @@ func putTripleBlocksTx(tx *sql.Tx, t Triple, sessionID string, turnID int) (stri
 //   - 原句块 blk_src_<sha256(text)[:12]>
 //   - 实体块 blk_ent_<sha256(name)[:12]>
 //   - 蒸馏块 blk_<sha256(sentence+subject+dim+value)[:12]>
+//
 // 而媒体块此前用时间戳+序号（blk_<unixnano>_<n>），是唯一的例外。
 //
 // 淘汰 CAS 之后，块自己承载内容，于是「同一份内容只应有一个块」这条
diff --git a/internal/memory/stress_block_union_test.go b/internal/memory/stress_block_union_test.go
index 2452fee0..6a6ed6e8 100644
--- a/internal/memory/stress_block_union_test.go
+++ b/internal/memory/stress_block_union_test.go
@@ -281,11 +281,12 @@ func TestStressBlockUnion_BackfillConcurrentWithRecall(t *testing.T) {
 // ── 4. 删除与读取并发：只能看到「完整内容」或「不存在」────────────
 //
 // ★ 为何不用 media 块：生产**没有**按块 ID 删媒体块的路径。
-//   删除发生在实体级（DeleteEntity 按 text_content 匹配）与
-//   孤块清理（PurgeOrphans 只扫 text_content != ''）。
-//   所以这里用 DeleteEntity 这个**真实路径**，分两步验证：
-//     (a) 被删 текст块的字节在删除过程中不会被读到半截
-//     (b) 删完后块与负载一起消失（块 union 的核心承诺：字节随块同生共灭）
+//
+//	删除发生在实体级（DeleteEntity 按 text_content 匹配）与
+//	孤块清理（PurgeOrphans 只扫 text_content != ''）。
+//	所以这里用 DeleteEntity 这个**真实路径**，分两步验证：
+//	  (a) 被删 текст块的字节在删除过程中不会被读到半截
+//	  (b) 删完后块与负载一起消失（块 union 的核心承诺：字节随块同生共灭）
 func TestStressBlockUnion_DeleteConcurrentWithRead(t *testing.T) {
 	g := newBlockTestGraph(t)
 
diff --git a/internal/memory/text/text.go b/internal/memory/text/text.go
index c57680ed..476a825f 100644
--- a/internal/memory/text/text.go
+++ b/internal/memory/text/text.go
@@ -4,6 +4,7 @@ import (
 	"bufio"
 	"encoding/json"
 	"fmt"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"log"
 	"os"
 	"path/filepath"
@@ -25,6 +26,10 @@ type Event struct {
 
 // Memory — 文本记忆：追加写 JSONL，按时间/大小旋转
 type Memory struct {
+	pauseMu  sync.Mutex
+	paused   bool
+	pauseCh  chan struct{}
+	stopOnce sync.Once
 	dir      string
 	interval time.Duration
 	maxSize  int64
@@ -54,6 +59,7 @@ func New(dir string, opts ...Option) *Memory {
 		interval: 24 * time.Hour,
 		maxSize:  10 * 1024 * 1024,
 		stopCh:   make(chan struct{}),
+		pauseCh:  make(chan struct{}, 1),
 	}
 	for _, opt := range opts {
 		opt(m)
@@ -72,8 +78,47 @@ func (m *Memory) Start() error {
 	return nil
 }
 
+// isPaused 报告是否处于伪关机。
+func (m *Memory) isPaused() bool {
+	m.pauseMu.Lock()
+	defer m.pauseMu.Unlock()
+	return m.paused
+}
+
+// Pause 伪关机：停止滚动写盘（可逆）。返回前持有写锁，
+// 保证**当前没有任何在途写入**。
+//
+// 语义（迁移依赖）：返回后到 Resume 之前，m.mu 保护的写路径
+// 仍可能被 Append 调用 —— 迁移时调用方应先停掉上游（插件/agent），
+// 本 Pause 只负责**后台定时写**这一路。
+func (m *Memory) Pause() error {
+	m.pauseMu.Lock()
+	m.paused = true
+	m.pauseMu.Unlock()
+	// 拿一次写锁再放开：确保在途的 rotateLocked 已结束
+	m.mu.Lock()
+	m.mu.Unlock()
+	return nil
+}
+
+// Resume 唤醒。
+func (m *Memory) Resume() error {
+	m.pauseMu.Lock()
+	was := m.paused
+	m.paused = false
+	m.pauseMu.Unlock()
+	if was {
+		select {
+		case m.pauseCh <- struct{}{}:
+		default:
+		}
+	}
+	return nil
+}
+
+// Stop 幂等（本仓 close 纪律：见 internal/safeclose）。
 func (m *Memory) Stop() {
-	close(m.stopCh)
+	safeclose.Safe(&m.stopOnce, m.stopCh)
 	m.mu.Lock()
 	if m.current != nil {
 		m.current.Close()
@@ -129,8 +174,20 @@ func (m *Memory) rotationLoop() {
 	ticker := time.NewTicker(m.interval / 2)
 	defer ticker.Stop()
 	for {
+		// ★ 伪关机门：迁移期间不能滚动写盘（见 kernelboot/lifecycle.go）
+		if m.isPaused() {
+			select {
+			case <-m.pauseCh:
+				continue
+			case <-m.stopCh:
+				return
+			}
+		}
 		select {
 		case <-ticker.C:
+			if m.isPaused() {
+				continue
+			}
 			m.mu.Lock()
 			if m.needRotate() {
 				m.rotateLocked()
diff --git a/internal/nlp/model.go b/internal/nlp/model.go
index f9ec0876..9d425327 100644
--- a/internal/nlp/model.go
+++ b/internal/nlp/model.go
@@ -13,10 +13,10 @@ type Triple struct {
 	Subject     string
 	Relation    string
 	Object      string
-	Score       float64   // syntax_conf：句法置信度（Phase 2 输出）
-	VectorConf  float64   // vector_conf：语义向量置信度（Phase 3 输出）
-	Src         string    // "dep" / "dep_coo" / "pos" / "fallback"
-	SentenceRef string    // 原始句子，用于LLM复审时修正
+	Score       float64 // syntax_conf：句法置信度（Phase 2 输出）
+	VectorConf  float64 // vector_conf：语义向量置信度（Phase 3 输出）
+	Src         string  // "dep" / "dep_coo" / "pos" / "fallback"
+	SentenceRef string  // 原始句子，用于LLM复审时修正
 }
 
 // TripleSet 提取结果
diff --git a/internal/nlp/parser.go b/internal/nlp/parser.go
index f00b6f48..023f354e 100644
--- a/internal/nlp/parser.go
+++ b/internal/nlp/parser.go
@@ -48,9 +48,9 @@ func DefaultExtractorConfig() ExtractorConfig {
 
 // Extractor 三元组提取器
 type Extractor struct {
-	parser   Parser
-	fallack  Parser // 降级用 POS 模板解析器
-	embedder Vectorizer // 可选：用于 TransE 语义验证
+	parser    Parser
+	fallack   Parser     // 降级用 POS 模板解析器
+	embedder  Vectorizer // 可选：用于 TransE 语义验证
 	fusionCfg ExtractorConfig
 }
 
@@ -89,10 +89,11 @@ func (e *Extractor) FusionConfig() ExtractorConfig {
 }
 
 // Extract 从文本中提取三元组（完整四阶段流水线）
-//  Phase 1: 句法解析（LTP 分词 → POS 标注 → 依存句法树）
-//  Phase 2: 结构初筛（依存模板 / POS 模板 → 候选三元组 + syntax_conf）
-//  Phase 3: 语义验证（TransE h+r≈t → vector_conf）
-//  Phase 4: 融合裁决（线性加权 → 阈值截断 → 降序输出）
+//
+//	Phase 1: 句法解析（LTP 分词 → POS 标注 → 依存句法树）
+//	Phase 2: 结构初筛（依存模板 / POS 模板 → 候选三元组 + syntax_conf）
+//	Phase 3: 语义验证（TransE h+r≈t → vector_conf）
+//	Phase 4: 融合裁决（线性加权 → 阈值截断 → 降序输出）
 func (e *Extractor) Extract(text string) *TripleSet {
 	if text == "" {
 		return &TripleSet{Src: "", Err: nil}
@@ -214,4 +215,4 @@ func addVectors(a, b vector.Vector) vector.Vector {
 		out[k] += v
 	}
 	return out
-}
\ No newline at end of file
+}
diff --git a/internal/plugin/dynamic_proc.go b/internal/plugin/dynamic_proc.go
index 4e6c5cbd..9f337efe 100644
--- a/internal/plugin/dynamic_proc.go
+++ b/internal/plugin/dynamic_proc.go
@@ -87,15 +87,27 @@ func (r *Registry) loadProc(dir, name string, config map[string]interface{}) (sd
 	// manifest 声明的能力集（§3.8 权限梯度）。
 	// 无 manifest 或未声明 capabilities 时不限制，保存存量插件行为。
 	var caps []string
+	// ★ 建链超时由插件**自行声明**（见 docs/zh/kernel-modularization-design.md §2.4.2）。
+	//
+	// 为何要读它而不是用内核默认 10s：实测生产启动 13 秒里 10 秒是串行等待
+	// 插件内部的重型初始化，而内核"猜"的 10s 对重插件不够、对轻插件浪费。
+	// 未声明时为 0 ⇒ HandshakeTimeout 回退到 proc.DefaultHandshakeTimeout，
+	// 与改动前**逐字一致**（存量插件零改动的硬约束）。
+	hsTimeout := time.Duration(0)
 	if mft := readManifest(dir); mft != nil {
 		caps = mft.Capabilities
 		if len(caps) > 0 {
 			log.Printf("[plugin] %s 声明能力: %v", name, caps)
 		}
+		hsTimeout = mft.HandshakeTimeout(proc.DefaultHandshakeTimeout)
+		if mft.HandshakeTimeoutSec > 0 {
+			log.Printf("[plugin] %s 声明建链超时 %s（内核默认 %s）",
+				name, hsTimeout, proc.DefaultHandshakeTimeout)
+		}
 	}
 
 	return procPluginAdapter{
-		Plugin: proc.New(name, binPath, dir, config, host, r.onProcCrash, caps...),
+		Plugin: proc.NewWithTimeout(name, binPath, dir, config, host, r.onProcCrash, hsTimeout, caps...),
 	}, nil
 }
 
diff --git a/internal/plugin/manifest.go b/internal/plugin/manifest.go
index be370377..fb5e1069 100644
--- a/internal/plugin/manifest.go
+++ b/internal/plugin/manifest.go
@@ -4,7 +4,9 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"time"
 
+	"github.com/JianFeeeee/HomeAgent/internal/plugin/proc"
 	pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
 )
 
@@ -30,6 +32,68 @@ type PluginManifest struct {
 	Tags        []string `json:"tags,omitempty"`
 	Deprecated  bool     `json:"deprecated,omitempty"`
 
+	// HandshakeTimeoutSec 是本插件**自行声明**的建链（握手）超时，单位秒。
+	//
+	// 省略或 <=0 时用内核默认值（proc.defaultHandshakeTimeout，10s）。
+	//
+	// ## 为何要让插件自己声明
+	//
+	// 实测（2026-10-16）：生产启动 13 秒，其中 **10 秒是串行等待**插件内部的
+	// 外部资源就绪（clawhubadapter 起两个 pysidecar，各 5 秒 ping timeout），
+	// 而它阻塞了后面 20+ 个插件的加载。
+	//
+	// 根因不是“超时值选错了”，而是**超时值是内核猜的**：
+	//   · 轻插件（纯 Go，秒起）用不到 10s
+	//   · 重插件（要起 Python/JVM/加载大模型）10s 可能不够，
+	//     于是它会“失败”且失败得很晚（白等 10 秒才报错）
+	// 只有插件自己知道“我大概要多久”，所以这个值应由它声明。
+	//
+	// ## 为什么不叫 Timeout 而叫 HandshakeTimeout
+	//
+	// 插件内部等待**自己的子资源**（如 pysidecar ping）不属于 SDK 契约，
+	// 那是插件自己的实现细节（内置插件应走自己的 ConfigDef）。
+	// 本字段只管**内核与插件之间**的建链——那才是内核能干预的边界。
+	HandshakeTimeoutSec int `json:"handshake_timeout_sec,omitempty"`
+
+	// RequiresFacilities 声明本插件需要**内核哪些设施就绪**后才能启动。
+	//
+	// 这决定插件的**启动时机**（设计 docs/zh/kernel-modularization-design.md §2.6）：
+	//   · **不声明（本字段缺省）** ⇒ 等内核**完全**初始化完成后拉起 ← **现行为**
+	//   · 声明如 ["config","llm"]   ⇒ 这些设施一就绪就拉起（**尽早启动**）
+	//
+	// ## ★ 为何"不声明"必须等于现行为（存量插件零改动）
+	//
+	// 生产有 42 个外部插件，它们全都不声明 ⇒ **启动时机逐字不变**。
+	// 若"不声明"被当成"无依赖/依赖已满足"，它们会在第 0 层完成后就被拉起，
+	// 早于现在得多 ⇒ 42 个插件里任何一个若假设"我 Start 时内核已就绪"，
+	// 就会出现**静默竞态**（系统看着正常，偶发才炸）。
+	//
+	// 所以判据里有一条专门守这个：未声明的插件在内核完成前**不得**被拉起。
+	//
+	// ## 设施名从哪来
+	//
+	// 内核模块在 `Provides()` 里声明（见 internal/kernelboot）：
+	// config / crypto / keystore / memory / lua / llm / tracker / textmem /
+	// docmem / knowledge / multimodal / stagehost / agent ...
+	//
+	// 拼错的名字**不会**静默忽略：它永远等不到就绪 ⇒ 插件最终由
+	// 「内核完成 + 超时兜底」拉起，并留下"还差 X"的日志（见调度器 WaitString）。
+	RequiresFacilities []string `json:"requires_facilities,omitempty"`
+
+	// AutoStart 声明是否**伴随内核启动**（true/缺省）还是等显式启用（false）。
+	//
+	// 用 *bool 而非 bool，因为要区分三种情形：
+	//   · 缺省（nil）  ⇒ 视为 true（伴随启动）← 与现状一致
+	//   · 显式 true    ⇒ 伴随启动
+	//   · 显式 false   ⇒ **不**伴随启动，等 agent 经 plugin_enable 启用
+	//
+	// ★ 为何不能用普通 bool：JSON 里 bool 的零值是 false，
+	// 于是"没写这个字段"与"写了 false"**无法区分**，
+	// 前者会被误判成"不自动启动"⇒ 存量插件全都不启动了（灾难性）。
+	// 这个坑与本仓 handshake_timeout_sec 用 int 而非 *int 是同一类；
+	// 那里能接受（0 与"未声明"语义相同），这里**不能**。
+	AutoStart *bool `json:"auto_start,omitempty"`
+
 	// Proxies 声明本插件需要 HomeAgent 反代出去的服务（自带 Web UI / HTTP API）。
 	//
 	// 契约定义在公开 SDK（sdk.ProxyDecl），这里只做载体：HomeAgent 加载插件时
@@ -54,6 +118,58 @@ type PluginManifest struct {
 	Capabilities []string `json:"capabilities,omitempty"`
 }
 
+// ShouldAutoStart 返回本插件是否应伴随内核启动（缺省 = true）。
+//
+// 与 RequiresFacilities 配合决定启动时机；两者正交：
+//
+//	· AutoStart=false  ⇒ 无论依赖是否就绪都**不**自动拉起
+//	· AutoStart=true（默认）+ 声明依赖   ⇒ 依赖齐了就拉起
+//	· AutoStart=true（默认）+ 不声明依赖 ⇒ 等内核完全初始化
+func (m *PluginManifest) ShouldAutoStart() bool {
+	if m == nil || m.AutoStart == nil {
+		return true // ★ 缺省即伴随启动（存量插件零改动）
+	}
+	return *m.AutoStart
+}
+
+// HandshakeTimeout 把声明的秒数换算成时长，并施加**上限**。
+//
+// ## 默认回退（存量插件零改动的硬约束）
+//
+// 未声明（0）或非法（负）⇒ 返回 def（调用方传 proc.DefaultHandshakeTimeout）。
+//
+// ★ 为何负数也回退默认而不是报错：“0 表示未声明”是 JSON 的常见约定，
+// 而手写配置里出现 `-1` 很可能只是“想表达无/未设”的笔误。
+// 若因此拒绝加载整个插件，代价远大于“按默认值处理”。
+// 但**绝不**把负数直接当时长用（那会变成“立即超时”，有隐蔽的破坏性）。
+//
+// ## 为何必须有上限
+//
+// 插件声明的值直接决定**内核**等多久。一个错误声明（如 86400 = 一天）
+// 会让内核在插件坏掉时**卡一整天**——那不是“插件自己负责”，
+// 而是把内核拖住（而插件加载是启动路径，会阻塞后续插件）。
+//
+// 上限取 5 分钟：远超任何合理的插件启动耗时（实测最重的也只需数十秒），
+// 但仍在“可承受的人工等待”范围内（远小于“一天”）。
+func (m *PluginManifest) HandshakeTimeout(def time.Duration) time.Duration {
+	if def <= 0 {
+		def = proc.DefaultHandshakeTimeout
+	}
+	if m == nil || m.HandshakeTimeoutSec <= 0 {
+		return def
+	}
+	d := time.Duration(m.HandshakeTimeoutSec) * time.Second
+	if d > maxHandshakeTimeout {
+		return maxHandshakeTimeout
+	}
+	return d
+}
+
+// maxHandshakeTimeout 是插件可声明的建链超时上限。
+//
+// 见 HandshakeTimeout 的说明：没有上限时，一个错误声明能把内核卡住。
+const maxHandshakeTimeout = 5 * time.Minute
+
 func ReadManifest(dir string) (*PluginManifest, error) {
 	data, err := os.ReadFile(filepath.Join(dir, "plugin.json"))
 	if err != nil {
diff --git a/internal/plugin/manifest_timeout_test.go b/internal/plugin/manifest_timeout_test.go
new file mode 100644
index 00000000..963afbab
--- /dev/null
+++ b/internal/plugin/manifest_timeout_test.go
@@ -0,0 +1,168 @@
+package plugin
+
+// 声明式超时的判据（2026-10-16）。
+//
+// 设计见 docs/zh/kernel-modularization-design.md §2.4.2。
+//
+// ## 动机（实测）
+//
+// 生产启动 13 秒，其中 **10 秒是串行等待**插件内部的外部资源就绪
+// （clawhubadapter 起两个 pysidecar，各 5 秒 ping timeout），
+// 而它阻塞了后面 20+ 个插件的加载。
+//
+// 根因不是"超时值选错了"，而是**超时值是内核猜的**（`defaultHandshakeTimeout = 10s`）：
+//   · 轻插件（纯 Go，秒起）用不到 10s → 浪费
+//   · 重插件（起 Python/JVM/加载大模型）10s 可能不够 → 白等 10 秒才报错
+//
+// 只有插件自己知道"我大概要多久"，所以这个值应由它**声明**。
+//
+// ## 这组判据要守什么
+//
+// ① 声明的值**真的被用上**（不是只解析进结构体就完了 —— 本仓反复踩这个坑：
+//    "字段加了、没人读"，判据必须测到**真实消费者**）
+// ② 未声明时**行为与改动前逐字一致**（存量插件零改动，硬约束）
+// ③ 非法值（负数/超范围）不得导致"无限等待"或"立刻超时"
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// ★★★ 判据：`handshake_timeout_sec` 能正确解析出来。
+func TestManifestParsesHandshakeTimeout(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		body string
+		want int
+	}{
+		{"声明 30s", `{"name":"p","version":"1","entry":"plugin.bin","handshake_timeout_sec":30}`, 30},
+		{"声明 1s", `{"name":"p","version":"1","entry":"plugin.bin","handshake_timeout_sec":1}`, 1},
+		{"声明 300s", `{"name":"p","version":"1","entry":"plugin.bin","handshake_timeout_sec":300}`, 300},
+		{"省略", `{"name":"p","version":"1","entry":"plugin.bin"}`, 0},
+		{"显式 0", `{"name":"p","version":"1","entry":"plugin.bin","handshake_timeout_sec":0}`, 0},
+		{"负数（视为未声明）", `{"name":"p","version":"1","entry":"plugin.bin","handshake_timeout_sec":-5}`, -5},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			if err := os.WriteFile(filepath.Join(dir, "plugin.json"), []byte(tc.body), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			m, err := ReadManifest(dir)
+			if err != nil {
+				t.Fatalf("解析失败: %v", err)
+			}
+			if m.HandshakeTimeoutSec != tc.want {
+				t.Errorf("HandshakeTimeoutSec: 期望 %d 实际 %d", tc.want, m.HandshakeTimeoutSec)
+			}
+		})
+	}
+}
+
+// ★★★ 判据：**旧插件（无该字段）必须照常工作** —— 存量零改动是硬约束。
+//
+// 这条独立存在，因为它是"不可破坏"的那一半：加字段容易，
+// 保证不加字段的老插件行为不变才是真约束。
+func TestManifestWithoutTimeoutKeepsLegacyBehavior(t *testing.T) {
+	// 用真实的存量 plugin.json 内容（qq 插件，无 handshake_timeout_sec）
+	dir := t.TempDir()
+	legacy := `{
+  "author": "HomeAgent",
+  "description": "QQ 消息收发插件，通过 NapCat 协议桥接",
+  "entry": "plugin.bin",
+  "name": "qq",
+  "name_en": "qq",
+  "name_zh": "QQ消息",
+  "tags": ["qq", "messaging"],
+  "version": "1.4.3"
+}`
+	if err := os.WriteFile(filepath.Join(dir, "plugin.json"), []byte(legacy), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	m, err := ReadManifest(dir)
+	if err != nil {
+		t.Fatalf("存量 manifest 解析失败（破坏性变更）: %v", err)
+	}
+	if m.Name != "qq" || m.Entry != "plugin.bin" {
+		t.Fatalf("存量字段解析出错: %+v", m)
+	}
+	if m.HandshakeTimeoutSec != 0 {
+		t.Errorf("未声明时应为 0（= 用内核默认），实际 %d", m.HandshakeTimeoutSec)
+	}
+}
+
+// ★★★ 判据：**真实消费者**（`HandshakeTimeout()` 换算函数）行为正确。
+//
+// 这条防的是本仓反复踩的坑："字段解析对了，但没人读它"。
+// 判据必须测到**从声明到时长**的完整换算，包括默认回退与非法值处理。
+func TestManifestHandshakeTimeoutResolution(t *testing.T) {
+	def := 10 * time.Second // 与 proc.defaultHandshakeTimeout 同值
+
+	for _, tc := range []struct {
+		name string
+		secs int
+		want time.Duration
+	}{
+		{"未声明 ⇒ 默认", 0, def},
+		{"负数 ⇒ 默认（不得变成立刻超时）", -5, def},
+		{"声明 30 ⇒ 30s", 30, 30 * time.Second},
+		{"声明 1 ⇒ 1s", 1, time.Second},
+		{"声明 300 ⇒ 300s", 300, 300 * time.Second},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			m := &PluginManifest{HandshakeTimeoutSec: tc.secs}
+			got := m.HandshakeTimeout(def)
+			if got != tc.want {
+				t.Errorf("期望 %v 实际 %v", tc.want, got)
+			}
+		})
+	}
+}
+
+// ★★★ 判据：**超时上限**必须存在（防"声明一个永不超时"）。
+//
+// 为何需要上限：插件声明的值直接决定内核等多久。
+// 一个错误声明（如 86400）会让内核在插件坏掉时**卡一整天**——
+// 那不是"插件自己负责"，而是把内核拖住。上限取一个"远超任何合理启动"
+// 但仍是"可承受等待"的值。
+func TestManifestHandshakeTimeoutIsCapped(t *testing.T) {
+	m := &PluginManifest{HandshakeTimeoutSec: 86400} // 一天
+	got := m.HandshakeTimeout(10 * time.Second)
+	if got > time.Hour {
+		t.Errorf("★ 声明的超时未被封顶（%v）—— 插件坏掉时内核会被卡住", got)
+	}
+	if got <= 0 {
+		t.Errorf("封顶后不得为 0 或负: %v", got)
+	}
+	// 封顶值本身必须可用（不能封成一个荒谬的小值）
+	if got < time.Minute {
+		t.Errorf("封顶值过小（%v）—— 重插件会被误杀", got)
+	}
+}
+
+// ★★★ 判据：未知字段不得导致解析失败（向前/向后兼容）。
+//
+// 已有先例：`Capabilities` 的引入依赖"忽略未知键"。
+// 这里再确认一次，因为超时字段会随插件分发到各版本内核。
+func TestManifestIgnoresUnknownKeys(t *testing.T) {
+	dir := t.TempDir()
+	body := `{"name":"p","version":"1","entry":"plugin.bin",
+	          "handshake_timeout_sec":20,
+	          "some_future_field":{"deep":[1,2,3]}}`
+	if err := os.WriteFile(filepath.Join(dir, "plugin.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	m, err := ReadManifest(dir)
+	if err != nil {
+		t.Fatalf("未知字段不该导致失败: %v", err)
+	}
+	if m.HandshakeTimeoutSec != 20 {
+		t.Errorf("已知字段应正常解析: %d", m.HandshakeTimeoutSec)
+	}
+}
+
+// 保证 json 包被使用（判据里用 json.Unmarshal 做等价比对时可能需要）；
+// 同时防止 import 被 gofmt 清掉造成后续编辑不便。
+var _ = json.Marshal
diff --git a/internal/plugin/proc/bridge_sync_test.go b/internal/plugin/proc/bridge_sync_test.go
new file mode 100644
index 00000000..bf39348c
--- /dev/null
+++ b/internal/plugin/proc/bridge_sync_test.go
@@ -0,0 +1,242 @@
+package proc
+
+// proc 桥**同步一致性**的判据（2026-10-16）。
+//
+// ## 为什么需要这组判据
+//
+// 我不久前给公开 SDK 的 `PluginMgrAPI` 加了 3 个方法（StopPlugin/
+// StartPlugin/IsPluginRuntimeStopped），当时以为"仅新增，非必须声明，
+// 低风险"。**实测发现有两处会漏**：
+//
+//  ① `internal/plugin/proc` 的方法白名单（4 处：常量 / 能力表 / Handle 分派 /
+//     case 体）—— 漏任何一处 ⇒ 子进程插件调这个方法得到"未知 method"
+//  ② `hmapdev` 的 `proc_main.go.tmpl`（生成 plugin.bin 的模板）——
+//     漏 ⇒ **新生成的插件编译不过**（`procPluginMgr` 不满足新接口）
+//
+// 这两处都不是"仅新增"能覆盖的：同进程插件（.so）直接调 SDK 不受影响，
+// 而子进程插件走桥 ⇒ **不对称**，正是最容易漏的地方。
+//
+// 判据必须**自动跟随** SDK 接口（不能手工维护清单 —— 手写清单在"新增
+// 忘了登记"时同样不会报，守卫形同虚设；本仓已有先例）。
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// publishedPluginMgrMethods 从**公开 SDK 源码**提取 PluginMgrAPI 的方法名。
+//
+// ★ 必须从 SDK 源码提取，不能手写清单：手写清单在"SDK 加了方法但忘了
+// 桥接"时**也不会包含新方法** ⇒ 判据照样绿（这就是要防的失效模式）。
+func publishedPluginMgrMethods(t *testing.T, sdkPath string) []string {
+	t.Helper()
+	src, err := os.ReadFile(sdkPath)
+	if err != nil {
+		t.Fatalf("读公开 SDK: %v", err)
+	}
+	// 抓 `type PluginMgrAPI interface { ... }` 块
+	re := regexp.MustCompile(`(?s)type PluginMgrAPI interface \{(.*?)\n\}`)
+	m := re.FindStringSubmatch(string(src))
+	if m == nil {
+		t.Fatal("未在公开 SDK 里找到 PluginMgrAPI 接口 —— 接口改名了？本判据需修正")
+	}
+	body := m[1]
+	// 方法行：`Name(args) ret`
+	mre := regexp.MustCompile(`(?m)^\s*([A-Z][A-Za-z0-9_]*)\([^)]*\)\s+[A-Za-z\[\]\*\.]+`)
+	var out []string
+	for _, mm := range mre.FindAllStringSubmatch(body, -1) {
+		out = append(out, mm[1])
+	}
+	if len(out) < 4 {
+		t.Fatalf("只从 PluginMgrAPI 提取到 %d 个方法 —— 正则失效（本判据会假绿）: %v", len(out), out)
+	}
+	return out
+}
+
+// ★★★ 判据：**SDK 上每个 PluginMgrAPI 方法都必须在 proc 桥里可达**。
+//
+// 可达 = 能力表里有它（capabilityOf 能查到）且值非空。
+// 这挡住了"SDK 加了方法但忘记登记能力" ⇒ 那种方法会被按 CapCore 放行，
+// 或者直接"未知 method"。
+func TestBridgeCoversEveryPublishedPluginMgrMethod(t *testing.T) {
+	sdkPath := filepath.Join("..", "..", "..", "third_party", "homeagent-sdk", "sdk", "plugin.go")
+	methods := publishedPluginMgrMethods(t, sdkPath)
+
+	// SDK 方法名 → proc method 值（命名约定：StopPlugin → plugin.mgrStop）
+	// ★ 这里的映射表本身也要有守卫：下面断言"每个 SDK 方法都能找到映射"，
+	//   且映射出的值必须真的在能力表里 ⇒ 漏一个就报红。
+	wantValues := map[string]string{
+		"ReloadOne":              "plugin.reloadOne",
+		"ListLoadedPlugins":      "plugin.listLoaded",
+		"IsPluginDisabled":       "plugin.isDisabled",
+		"StopPlugin":             "plugin.mgrStop",
+		"StartPlugin":            "plugin.mgrStart",
+		"IsPluginRuntimeStopped": "plugin.mgrIsRuntimeStopped",
+	}
+
+	for _, m := range methods {
+		val, ok := wantValues[m]
+		if !ok {
+			t.Errorf("★ SDK 的 PluginMgrAPI 新增了方法 %s，但本判据的映射表没有它 —— "+
+				"必须同时：① 在 protocol.go 加 method 常量 ② 登记能力 ③ 加 Handle 分派 "+
+				"④ 加 case 体 ⑤ 更新 hmapdev 模板", m)
+			continue
+		}
+		if _, ok := capabilityOf(val); !ok {
+			t.Errorf("★ %s（%s）未登记能力归属 —— 子进程插件调用会被拒或绕过权限", m, val)
+		}
+	}
+	// 反向：映射表里不该有 SDK 已删除的方法（防改名后只改一处）
+	for name := range wantValues {
+		found := false
+		for _, m := range methods {
+			if m == name {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("映射表里的 %s 在 SDK 的 PluginMgrAPI 里不存在（改名/删除后漏改？）", name)
+		}
+	}
+}
+
+// ★★★ 判据：**Handle 的分派表覆盖全部 case 体**。
+//
+// protocol.go 的常量、corehandler.go 的 case 标签、corehandler_runtime.go 的
+// case 体是**三处**必须同步的地方。漏任意一处 ⇒ "未知 method" 或死代码。
+//
+// 这里检查"每个 plugin.* 常量都出现在某个 Handle 分派组里"。
+func TestBridgeDispatchesEveryPluginMethod(t *testing.T) {
+	proto, err := os.ReadFile("protocol.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	disp, err := os.ReadFile("corehandler.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	body, err := os.ReadFile("corehandler_runtime.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	re := regexp.MustCompile(`(?m)^\s*(MethodPlugin[A-Za-z0-9_]+)\s*=\s*"([^"]+)"`)
+	matches := re.FindAllStringSubmatch(string(proto), -1)
+	if len(matches) < 5 {
+		t.Fatalf("只提取到 %d 个 plugin.* 常量 —— 正则失效", len(matches))
+	}
+
+	// 内核→插件方向的 3 个不走 Handle 的 plugin.* 常量
+	kernelToPlugin := map[string]bool{
+		"MethodPluginInit":  true,
+		"MethodPluginStart": true,
+		"MethodPluginStop":  true,
+	}
+
+	for _, m := range matches {
+		name, value := m[1], m[2]
+		if kernelToPlugin[name] {
+			continue
+		}
+		// ① 必须在 Handle 分派里出现
+		if !strings.Contains(string(disp), name) {
+			t.Errorf("★ %s (%s) 未出现在 Handle 分派里 —— 子进程插件调用会得到\"未知 method\"",
+				name, value)
+			continue
+		}
+		// ② 必须在某个 case 体里被处理（否则是空分派 ⇒ 静默 nil）
+		if !strings.Contains(string(body), "case "+name+":") {
+			t.Errorf("★ %s (%s) 在分派里出现但没有对应的 case 体 —— 会被静默吞掉", name, value)
+		}
+	}
+}
+
+// ★★★ 判据：**hmapdev 模板实现了 SDK 的全部 PluginMgrAPI 方法**。
+//
+// 漏 ⇒ 新生成的 plugin.bin **编译不过**（procPluginMgr 不满足接口）。
+// 这是最晚才发现的一环（编译期才报，且只在用户执行 hmapdev build 时暴露）。
+func TestHmapdevTemplateImplementsAllPluginMgrMethods(t *testing.T) {
+	sdkPath := filepath.Join("..", "..", "..", "third_party", "homeagent-sdk", "sdk", "plugin.go")
+	methods := publishedPluginMgrMethods(t, sdkPath)
+
+	tmplPath := filepath.Join("..", "..", "..", "third_party", "homeagent-sdk",
+		"tools", "hmapdev", "templates", "proc_main.go.tmpl")
+	src, err := os.ReadFile(tmplPath)
+	if err != nil {
+		// ★ 文件缺失必须 **skip 而不是 fail**（2026-10-17 CI 实测）：
+		//
+		// `third_party/homeagent-sdk/tools/` 在 .gitignore 里（SDK 仓自治，
+		// 本仓不跟踪）。所以：
+		//   · 本机（完整 SDK 检出）有该文件 ⇒ 判据能跑
+		//   · CI（只 checkout 本仓）没有该文件 ⇒ 原本 Fatalf ⇒ **CI 必红**
+		//
+		// 我第一次提交时只在本机验证，没看 CI，于是这个判据让
+		// "Go build / vet / test" 和 "Build linux/amd64" 双红，把 PR 卡住。
+		//
+		// skip 不是放弃检查：跨仓一致性由 **SDK 仓自己的判据**守着
+		// （third_party/homeagent-sdk/tools/hmapdev/scaffold_stdout_test.go
+		//  等），那边是模板的真实归属地。本判据在本机开发时仍然生效。
+		t.Skipf("跳过：SDK 仓的 tools/ 不在本仓跟踪范围（.gitignore），"+
+			"跨仓一致性由 SDK 仓判据守护。缺文件: %v", err)
+	}
+	// 只看 procPluginMgr 的方法块。
+	//
+	// ★ 用**行扫描**而不是正则切块：正则的边界在遇到嵌套/注释时容易提前结束
+	// （实测撞了两次：先是 `(\n// |\z)` 被段落注释截断，再是 `\n(type |...)`
+	// 仍不够稳）。行扫描的语义直白且不受内容影响。
+	block := extractTypeBlock(t, string(src), "type procPluginMgr struct{}")
+	if !strings.Contains(block, "func (procPluginMgr) ReloadOne(") {
+		t.Fatal("提取到的 procPluginMgr 块不含 ReloadOne ⇒ 边界错误，判据会假绿")
+	}
+
+	for _, name := range methods {
+		// 期望存在 `func (procPluginMgr) <Name>(`
+		if !strings.Contains(block, "func (procPluginMgr) "+name+"(") {
+			t.Errorf("★ hmapdev 模板的 procPluginMgr 缺少 %s —— "+
+				"用它生成的 plugin.bin **编译不过**（不满足 SDK 接口）", name)
+		}
+	}
+}
+
+// extractTypeBlock 从源码里取出以 header 开头、到下一个顶层声明为止的块。
+//
+// 行扫描实现：遇到下一个处于**第 0 列**的 `type `/`func `/`var `/`const ` 即结束。
+// 这比正则稳，也不需要理解内容（注释/嵌套括号都不影响）。
+func extractTypeBlock(t *testing.T, src, header string) string {
+	t.Helper()
+	lines := strings.Split(src, "\n")
+	start := -1
+	for i, ln := range lines {
+		if strings.TrimSpace(ln) == header {
+			start = i
+			break
+		}
+	}
+	if start < 0 {
+		t.Fatalf("未找到 %q", header)
+	}
+	_ = start
+	var out []string
+	for i := start; i < len(lines); i++ {
+		if i > start {
+			ln := lines[i]
+			// 结束条件：下一个**顶层类型/变量/常量声明**。
+			//
+			// ★ 不能把第 0 列的 `func` 当结束：方法声明（带接收者）也是
+			//   第 0 列 `func` —— 初版这样写 ⇒ 块在第一个方法处就结束
+			//   ⇒ 所有方法都"缺失"（判据假红，实测撞到）。
+			//   区分点：方法声明是 `func (recv)`，普通函数是 `func Name(`。
+			isOtherTopDecl := strings.HasPrefix(ln, "type ") ||
+				strings.HasPrefix(ln, "var ") || strings.HasPrefix(ln, "const ")
+			if isOtherTopDecl {
+				break
+			}
+		}
+		out = append(out, lines[i])
+	}
+	return strings.Join(out, "\n")
+}
diff --git a/internal/plugin/proc/capability.go b/internal/plugin/proc/capability.go
index 748a8686..c463e8af 100644
--- a/internal/plugin/proc/capability.go
+++ b/internal/plugin/proc/capability.go
@@ -90,10 +90,19 @@ var methodCapability = map[string]Capability{
 	// 自身配置读写与元信息属基础能力
 	MethodSettingsGet:         CapCore,
 	MethodSettingsSet:         CapCore,
+	MethodSettingsSetSecret:   CapCore,
+	MethodSettingsGetSecret:   CapCore,
 	MethodSettingsList:        CapCore,
 	MethodSettingsDefs:        CapCore,
 	MethodSettingsRegisterDef: CapCore,
 	MethodSettingsDataDir:     CapCore,
+	MethodSecretsAvailable:    CapCore,
+	MethodSecretsStore:        CapCore,
+	MethodSecretsList:         CapCore,
+	MethodSecretsForget:       CapCore,
+	MethodSecretsFill:         CapCore,
+	MethodSecretsEncrypt:      CapCore,
+	MethodSecretsDecrypt:      CapCore,
 	// 生命周期自述（插件声明自己是否可自动重启）
 	MethodLifecycleAutoRestart: CapCore,
 	// 多模态内容块注入是工具返回值的一部分，不越权
@@ -151,9 +160,12 @@ var methodCapability = map[string]Capability{
 	MethodEventsUnsubscribe: CapEvents,
 
 	// ---- 插件管理 ----
-	MethodPluginReloadOne:  CapPluginMgr,
-	MethodPluginListLoaded: CapPluginMgr,
-	MethodPluginIsDisabled: CapPluginMgr,
+	MethodPluginReloadOne:           CapPluginMgr,
+	MethodPluginListLoaded:          CapPluginMgr,
+	MethodPluginIsDisabled:          CapPluginMgr,
+	MethodPluginMgrStop:             CapPluginMgr,
+	MethodPluginMgrStart:            CapPluginMgr,
+	MethodPluginMgrIsRuntimeStopped: CapPluginMgr,
 
 	// ---- 跨插件 / 核心配置 ----
 	MethodSettingsGetCore:    CapCrossPluginSettings,
diff --git a/internal/plugin/proc/capability_test.go b/internal/plugin/proc/capability_test.go
index 2332b44b..3e10ca32 100644
--- a/internal/plugin/proc/capability_test.go
+++ b/internal/plugin/proc/capability_test.go
@@ -2,6 +2,8 @@ package proc
 
 import (
 	"encoding/json"
+	"os"
+	"regexp"
 	"strings"
 	"testing"
 )
@@ -28,40 +30,47 @@ func TestCapability_AllMethodsClassified(t *testing.T) {
 		MethodOutputInvoke:  true,
 	}
 
-	// 插件→内核的全部 method（手工清单，与 protocol.go 对照）
-	pluginToKernel := []string{
-		MethodHandshake,
-		MethodToolRegister, MethodStageRegister, MethodOutputRegister,
-		MethodAPIRegister, MethodInputRegister,
-		MethodIOInjectText, MethodIOInjectInterrupt, MethodIOInjectTextNoMem,
-		MethodIOInjectSync, MethodIOSetToolBlocks,
-		MethodIOInjectMedia, MethodIOInjectMediaSync, MethodIOInjectInterruptMedia,
-		MethodLifecycleAutoRestart,
-		MethodMemoryRecall, MethodMemoryCommit, MethodMemoryIntrospect,
-		MethodMemoryMerge, MethodMemoryPurge,
-		MethodDocQuery, MethodDocInsert, MethodDocRemove, MethodDocStats,
-		MethodDocInsertMedia,
-		MethodKnowledgeSearch, MethodKnowledgeAdd, MethodKnowledgeList,
-		MethodTextMemoryAppend,
-		MethodSettingsGet, MethodSettingsSet, MethodSettingsRegisterDef,
-		MethodSettingsGetCore, MethodSettingsSetCore, MethodSettingsListCore,
-		MethodSettingsGetPlugin, MethodSettingsSetPlugin, MethodSettingsListPlugin,
-		MethodSettingsList, MethodSettingsDefs, MethodSettingsDump,
-		MethodSettingsPlugins, MethodSettingsDataDir,
-		MethodLLMListSources, MethodLLMSetSource, MethodLLMCurrentSource,
-		MethodSocialGetPerson, MethodSocialGetNetwork, MethodSocialGetTrait,
-		MethodSocialGetRelation, MethodSocialListPersons,
-		MethodEventsSubscribe, MethodEventsUnsubscribe,
-		MethodPluginReloadOne, MethodPluginListLoaded, MethodPluginIsDisabled,
-		MethodStageLock, MethodStageUnlock,
+	// ★ 从 protocol.go **源码**提取全部 method 常量，而不是维护手工清单。
+	//
+	// 为什么改：初版是手写清单，于是「新增 method 忘了登记能力」时
+	// 清单里也没有它 —— 测试照样绿，守卫形同虚设（这正是初版的目的所在，
+	// 却因实现方式而失效）。源码扫描让覆盖面**自动**跟上常量定义。
+	src, err := os.ReadFile("protocol.go")
+	if err != nil {
+		t.Fatalf("读 protocol.go 失败: %v", err)
+	}
+	re := regexp.MustCompile(`(?m)^\s*(Method[A-Za-z0-9_]+)\s*=\s*"([^"]+)"`)
+	matches := re.FindAllStringSubmatch(string(src), -1)
+	if len(matches) < 40 {
+		t.Fatalf("只从 protocol.go 提取到 %d 个 method 常量 —— 正则或文件结构变了，"+
+			"请修正本判据（否则它会假绿）", len(matches))
 	}
 
-	for _, m := range pluginToKernel {
-		if kernelToPlugin[m] {
-			continue
+	seen := 0
+	for _, m := range matches {
+		value := m[2]
+		if kernelToPlugin[value] {
+			continue // 内核→插件方向：不经 Handle，无需能力
 		}
-		if _, ok := capabilityOf(m); !ok {
-			t.Errorf("method %q 未登记能力归属 —— 会按 CapCore 放行，绕过权限检查", m)
+		seen++
+		if _, ok := capabilityOf(value); !ok {
+			t.Errorf("method %q (%s) 未登记能力归属 —— 会按 CapCore 放行，绕过权限检查",
+				value, m[1])
+		}
+	}
+	if seen == 0 {
+		t.Fatal("没有校验到任何 method —— 判据失效")
+	}
+
+	// 反向：能力表里的每一项都必须是 protocol.go 里真实存在的 method。
+	// 防「改了 method 名却只改一处」这类错位。
+	declared := map[string]bool{}
+	for _, m := range matches {
+		declared[m[2]] = true
+	}
+	for method := range methodCapability {
+		if !declared[method] {
+			t.Errorf("能力表里的 %q 在 protocol.go 里不存在（常量改名后漏改？）", method)
 		}
 	}
 }
diff --git a/internal/plugin/proc/corehandler.go b/internal/plugin/proc/corehandler.go
index 432a0440..10e1fc4c 100644
--- a/internal/plugin/proc/corehandler.go
+++ b/internal/plugin/proc/corehandler.go
@@ -91,6 +91,8 @@ type CoreSDK interface {
 	PluginName() string
 
 	Settings() pubsdk.SettingsAPI
+	// Secrets 是**全进程共享**的变量库（非 per-plugin）。
+	Secrets() pubsdk.SecretsAPI
 	Memory() pubsdk.MemoryAPI
 	TextMemory() pubsdk.TextMemoryAPI
 	DocMemory() pubsdk.DocMemoryAPI
@@ -173,6 +175,7 @@ func (h *coreHandler) Handle(method string, params json.RawMessage) (interface{}
 		return h.handleTextMemory(method, params)
 
 	case MethodSettingsGet, MethodSettingsSet, MethodSettingsRegisterDef,
+		MethodSettingsSetSecret, MethodSettingsGetSecret,
 		MethodSettingsGetCore, MethodSettingsSetCore, MethodSettingsListCore,
 		MethodSettingsGetPlugin, MethodSettingsSetPlugin, MethodSettingsListPlugin,
 		MethodSettingsList, MethodSettingsDefs, MethodSettingsDump, MethodSettingsPlugins,
@@ -189,7 +192,8 @@ func (h *coreHandler) Handle(method string, params json.RawMessage) (interface{}
 	case MethodLifecycleAutoRestart:
 		return h.handleLifecycle(method, params)
 
-	case MethodPluginReloadOne, MethodPluginListLoaded, MethodPluginIsDisabled:
+	case MethodPluginReloadOne, MethodPluginListLoaded, MethodPluginIsDisabled,
+		MethodPluginMgrStop, MethodPluginMgrStart, MethodPluginMgrIsRuntimeStopped:
 		return h.handlePluginMgr(method, params)
 
 	case MethodStageLock, MethodStageUnlock:
@@ -198,6 +202,10 @@ func (h *coreHandler) Handle(method string, params json.RawMessage) (interface{}
 	case MethodEventsSubscribe, MethodEventsUnsubscribe:
 		return h.handleEvents(method, params)
 
+	case MethodSecretsAvailable, MethodSecretsStore, MethodSecretsList,
+		MethodSecretsForget, MethodSecretsFill, MethodSecretsEncrypt, MethodSecretsDecrypt:
+		return h.secrets(method, params)
+
 	case MethodArenaAlloc, MethodArenaFree:
 		return h.handleArena(method, params)
 
@@ -552,6 +560,19 @@ func (h *coreHandler) settings(method string, params json.RawMessage) (interface
 	case MethodSettingsRegisterDef:
 		sett.RegisterDef(p.Def)
 		return nil, nil
+	// ---- 密文读写（强制加密，不看键名）----
+	//
+	// 与 Set/Get 的区别：这两个**必然**走加密路径，用于插件用
+	// `blob`/`payload`/`conn` 这类中性键名存凭据的场景 ——
+	// 光靠键名模式猜不出它是敏感的。
+	case MethodSettingsSetSecret:
+		return nil, sett.SetSecret(p.Key, p.Value)
+	case MethodSettingsGetSecret:
+		v, err := sett.GetSecret(p.Key)
+		if err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{"value": v}, nil
 	case MethodSettingsGetCore:
 		v, err := sett.GetCore(p.Key)
 		if err != nil {
diff --git a/internal/plugin/proc/corehandler_runtime.go b/internal/plugin/proc/corehandler_runtime.go
index a19a807f..d1c88d87 100644
--- a/internal/plugin/proc/corehandler_runtime.go
+++ b/internal/plugin/proc/corehandler_runtime.go
@@ -48,6 +48,42 @@ func (h *coreHandler) handlePluginMgr(method string, params json.RawMessage) (in
 			return nil, err
 		}
 		return map[string]interface{}{"disabled": pm.IsPluginDisabled(p.Name)}, nil
+	case MethodPluginMgrStop:
+		pm := h.sdk.PluginMgr()
+		if pm == nil {
+			return nil, errUnavailable("plugin manager")
+		}
+		var p struct {
+			Name string `json:"name"`
+		}
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		return nil, pm.StopPlugin(p.Name)
+	case MethodPluginMgrStart:
+		pm := h.sdk.PluginMgr()
+		if pm == nil {
+			return nil, errUnavailable("plugin manager")
+		}
+		var p struct {
+			Name string `json:"name"`
+		}
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		return nil, pm.StartPlugin(p.Name)
+	case MethodPluginMgrIsRuntimeStopped:
+		pm := h.sdk.PluginMgr()
+		if pm == nil {
+			return nil, errUnavailable("plugin manager")
+		}
+		var p struct {
+			Name string `json:"name"`
+		}
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{"runtime_stopped": pm.IsPluginRuntimeStopped(p.Name)}, nil
 
 	}
 
diff --git a/internal/plugin/proc/corehandler_secrets.go b/internal/plugin/proc/corehandler_secrets.go
new file mode 100644
index 00000000..158b9be7
--- /dev/null
+++ b/internal/plugin/proc/corehandler_secrets.go
@@ -0,0 +1,119 @@
+package proc
+
+// 变量库的 proc 桥（内核侧）。
+//
+// ## 与 settings 的分工
+//
+//	settings  —— **每个插件自己的**配置（各自的 config_<name> 表）
+//	secrets   —— **全进程共享的**变量库（security.Global() 单例）
+//
+// 这个区别是本质的：变量库全局唯一（设计 S10），主/子/驻留子 agent
+// 与全部插件共用同一套别名。所以它不该走 settings 的命名空间机制。
+//
+// ## 为何需要这层桥
+//
+// 外部插件是**子进程**，它的 `sdk.Secrets()` 拿到的是模板里的
+// `procSecrets`（见 templates/proc_main.go.tmpl），它把调用转成 RPC
+// 发到这里。这条链路有 4 个地方要同时改（协议常量 / 路由 / 分发 / 能力表），
+// 少一处就报 "未知 method" —— 真机 e2e 会立刻发现（本次已踩过一次）。
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+
+	pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
+)
+
+func (h *coreHandler) secrets(method string, params json.RawMessage) (interface{}, error) {
+	sec := h.sdk.Secrets()
+	if sec == nil {
+		return nil, errUnavailable("secrets")
+	}
+
+	switch method {
+	case MethodSecretsAvailable:
+		// 明确的可用性查询（不靠 List 推断 —— 见 secrets_impl 的注释）
+		return map[string]interface{}{"available": sec.Available()}, nil
+
+	case MethodSecretsStore:
+		var p struct {
+			Value string `json:"value"`
+			Note  string `json:"note"`
+		}
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		alias, err := sec.Store(p.Value, p.Note)
+		if err != nil {
+			return nil, err
+		}
+		// ★ 只回别名，不回显明文（与 SDK 的契约一致）
+		return map[string]interface{}{"alias": alias}, nil
+
+	case MethodSecretsList:
+		infos := sec.List()
+		if infos == nil {
+			infos = []pubsdk.SecretInfo{}
+		}
+		return map[string]interface{}{"infos": infos}, nil
+
+	case MethodSecretsForget:
+		var p struct {
+			Alias string `json:"alias"`
+		}
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		return nil, sec.Forget(p.Alias)
+
+	case MethodSecretsFill:
+		var p struct {
+			Text string `json:"text"`
+		}
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		out, n, aliases := sec.Fill(p.Text)
+		if aliases == nil {
+			aliases = []string{}
+		}
+		return map[string]interface{}{
+			"text": out, "replaced": n, "aliases": aliases,
+		}, nil
+
+	case MethodSecretsEncrypt:
+		// 二进制负载经 base64 过 RPC（JSON 不能直接带 bytes）
+		var p struct {
+			PlainB64 string `json:"plain_b64"`
+		}
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		raw, err := base64.StdEncoding.DecodeString(p.PlainB64)
+		if err != nil {
+			return nil, fmt.Errorf("secrets.encrypt: base64 解码失败: %w", err)
+		}
+		enc, err := sec.Encrypt(raw)
+		if err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{"encrypted": enc}, nil
+
+	case MethodSecretsDecrypt:
+		var p struct {
+			Stored string `json:"stored"`
+		}
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		plain, err := sec.Decrypt(p.Stored)
+		if err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{
+			"plain_b64": base64.StdEncoding.EncodeToString(plain),
+		}, nil
+	}
+	return nil, fmt.Errorf("未知 secrets method: %s", method)
+}
diff --git a/internal/plugin/proc/corehandler_settings.go b/internal/plugin/proc/corehandler_settings.go
index d32540b1..d7e443d2 100644
--- a/internal/plugin/proc/corehandler_settings.go
+++ b/internal/plugin/proc/corehandler_settings.go
@@ -3,6 +3,8 @@ package proc
 import (
 	"encoding/json"
 	"fmt"
+
+	pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
 )
 
 // handleSettings 处理全部设置项读写（14 个 method 共用一条实现）。
@@ -13,6 +15,7 @@ func (h *coreHandler) handleSettings(method string, params json.RawMessage) (int
 	switch method {
 	// ---- 设置（原 case 16/17/18/26~31/42~45/51）----
 	case MethodSettingsGet, MethodSettingsSet, MethodSettingsRegisterDef,
+		MethodSettingsSetSecret, MethodSettingsGetSecret,
 		MethodSettingsGetCore, MethodSettingsSetCore, MethodSettingsListCore,
 		MethodSettingsGetPlugin, MethodSettingsSetPlugin, MethodSettingsListPlugin,
 		MethodSettingsList, MethodSettingsDefs, MethodSettingsDump,
@@ -110,3 +113,39 @@ func (h *coreHandler) handleLifecycle(method string, params json.RawMessage) (in
 	// 出现即说明两处不同步。
 	return nil, fmt.Errorf("未知 method: %s", method)
 }
+
+// secretSettings 是 SettingsAPI 的**可选**加密能力。
+//
+// 为何用类型断言而不是把方法加进接口：proc 桥两侧（内核侧 settingsImpl、
+// 模板侧 procSettings、以及各测试替身）实现面很宽，直接扩接口会让
+// **所有实现者**同时编译失败 —— 包括已发布的 SDK 使用者。
+// 用可选接口则：
+//
+//	· 支持者（内核 settingsImpl、新模板）→ 走加密路径
+//	· 不支持者（旧测试替身）→ 返回明确错误，**不静默存明文**
+type secretSettings interface {
+	SetSecret(key string, value interface{}) error
+	GetSecret(key string) (string, error)
+}
+
+// settingsSetSecret 强制加密写入。
+//
+// ★ 未实现该能力时**报错**而不是降级为 Set：插件以为存了密文，
+// 实际磁盘上是明文 —— 这就是最危险的静默降级。
+func settingsSetSecret(sett pubsdk.SettingsAPI, key string, value interface{}) error {
+	ss, ok := sett.(secretSettings)
+	if !ok {
+		return fmt.Errorf("settings: 本内核不支持加密存储（settings.setSecret），" +
+			"拒绝以明文写入敏感项；请升级内核")
+	}
+	return ss.SetSecret(key, value)
+}
+
+// settingsGetSecret 读取加密值。
+func settingsGetSecret(sett pubsdk.SettingsAPI, key string) (string, error) {
+	ss, ok := sett.(secretSettings)
+	if !ok {
+		return "", fmt.Errorf("settings: 本内核不支持加密存储（settings.getSecret）")
+	}
+	return ss.GetSecret(key)
+}
diff --git a/internal/plugin/proc/e2e_secret_test.go b/internal/plugin/proc/e2e_secret_test.go
new file mode 100644
index 00000000..f2189a54
--- /dev/null
+++ b/internal/plugin/proc/e2e_secret_test.go
@@ -0,0 +1,138 @@
+package proc
+
+// 端到端：插件的**加密存储**能力（settings.setSecret/getSecret）。
+//
+// ## 为何必须做真机端到端
+//
+// 这条链路上有 5 段，任何一段漏掉都表现为「插件拿不到值」：
+//
+//	① 插件调 sdk.Settings().SetSecret
+//	② 模板 procSettings.SetSecret → RPC "settings.setSecret"
+//	③ proc 协议常量 MethodSettingsSetSecret
+//	④ coreHandler 分发 → settingsSetSecret（可选接口断言）
+//	⑤ ConfigRegistry.PluginSettings.SetSecret → 真加密落盘
+//
+// 单测只能证明 ⑤ 对。②③④ 是新写的，必须让**真实模板编译出的插件**
+// 真的跑一遍 —— 否则就是「模板 e2e 报了 missing method，而我只在
+// 内核侧修好了接口」这类错位（本次实际踩到过一次）。
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
+	internalSDK "github.com/JianFeeeee/HomeAgent/internal/sdk"
+	pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
+)
+
+// secretE2EPlugin 是一个**用真实模板**编译的插件：它只做两件事 ——
+// 把密钥写进加密存储，然后读回来并通过返回值报告。
+const secretE2EPlugin = `package main
+
+import (
+	sdk "github.com/JianFeeeee/homeagentsdk/sdk"
+)
+
+type secretPlugin struct{ name string }
+
+func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
+	return &secretPlugin{name: name}, nil
+}
+
+func (p *secretPlugin) Name() string { return p.name }
+
+func (p *secretPlugin) Stop() error { return nil }
+
+func (p *secretPlugin) Start(s *sdk.PluginSDK) error {
+	s.RegisterTool("e2e_secret", sdk.ToolDef{
+		Description: "加密存储往返测试",
+		Parameters:  map[string]interface{}{"type": "object"},
+	}, func(args map[string]interface{}) (interface{}, error) {
+		sett := s.Settings()
+		if sett == nil {
+			return "NO_SETTINGS", nil
+		}
+		if err := sett.SetSecret("blob", "e2e-secret-value-9876543210"); err != nil {
+			return "SET_ERR: " + err.Error(), nil
+		}
+		got, err := sett.GetSecret("blob")
+		if err != nil {
+			return "GET_ERR: " + err.Error(), nil
+		}
+		return got, nil
+	})
+	return nil
+}
+`
+
+// ★★ 判据：真实模板编译出的插件，其 SetSecret/GetSecret 全链路可用，
+// 且**磁盘上是密文**、插件读回是明文。
+func TestE2E_RealTemplateSecretRoundTrip(t *testing.T) {
+	bin := buildPluginWithRealTemplate(t, secretE2EPlugin)
+
+	// 用**真实** ConfigRegistry（真加密）+ 真主密钥
+	dir := t.TempDir()
+	setTestCodec(t)
+	reg := internalConfig.NewConfigRegistry(filepath.Join(dir, "config.db"))
+	defer reg.Close()
+
+	host, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host.Close()
+
+	core := newFakeCore()
+	// 用**生产同款**适配器（sdk.NewSettings），而不是直接塞 PluginSettings ——
+	// 后者缺 DataDir 等成员，不是完整 SettingsAPI；用生产适配器才能
+	// 顺带验证「内核装配的那一层」也是通的。
+	core.settingsAPI = internalSDK.NewSettings("e2e", reg)
+	p := New("e2e", bin, dir, nil, host, nil)
+	if err := p.Start(core); err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+	defer p.Close()
+
+	core.mu.Lock()
+	handler, ok := core.tools["e2e_secret"]
+	core.mu.Unlock()
+	if !ok {
+		t.Fatal("插件未注册 e2e_secret 工具")
+	}
+
+	res, err := handler(map[string]interface{}{})
+	if err != nil {
+		t.Fatalf("工具调用失败: %v", err)
+	}
+	got, _ := res.(string)
+	if strings.HasPrefix(got, "SET_ERR") || strings.HasPrefix(got, "GET_ERR") {
+		t.Fatalf("加密存储往返失败: %s", got)
+	}
+	if got != "e2e-secret-value-9876543210" {
+		t.Fatalf("插件应读回明文，实际 %q", got)
+	}
+
+	// ★ 磁盘上必须是密文（这才是本特性的目的）
+	var raw string
+	if err := reg.DB().QueryRow(
+		`SELECT value FROM config_e2e WHERE key = 'blob'`).Scan(&raw); err != nil {
+		t.Fatalf("读原始值失败: %v", err)
+	}
+	if strings.Contains(raw, "e2e-secret-value") {
+		t.Fatalf("磁盘上出现明文（加密未生效）: %q", raw)
+	}
+	if !strings.HasPrefix(raw, "enc:v1:") {
+		t.Fatalf("磁盘值应为 enc:v1: 密文，实际 %q", raw)
+	}
+	t.Logf("✅ 插件读回明文(%d 字节)，磁盘存密文(%d 字节)", len(got), len(raw))
+	_ = os.Remove
+	_ = pubsdk.ConfigDef{}
+}
+
+// setTestCodec 装配一把测试主密钥。
+func setTestCodec(t *testing.T) {
+	t.Helper()
+	internalConfig.ResetTestCodec(t)
+}
diff --git a/internal/plugin/proc/e2e_secrets_test.go b/internal/plugin/proc/e2e_secrets_test.go
new file mode 100644
index 00000000..2734afd4
--- /dev/null
+++ b/internal/plugin/proc/e2e_secrets_test.go
@@ -0,0 +1,217 @@
+package proc
+
+// 端到端：插件的**变量库**能力（SDK `Secrets()`）。
+//
+// ## 这条链路为什么要真机验证
+//
+// 它与 settings 的 setSecret 是**同一个坑的翻版**：新增 proc method 要改
+// **4 个地方**（协议常量 / 外层路由 / 内层分发 / 能力表），少一处就报
+// "未知 method"。单测只能证明各段对，证不了接上了。
+//
+// 而且它跨了**三层**：
+//
+//	① 插件调 sdk.Secrets().Store
+//	② 模板 procSecrets → RPC "secrets.store"
+//	③ 内核 coreHandler.secrets → sdk.SecretsAPI（secrets_impl）
+//	④ → internal/security.Global() 单例（真加密落盘）
+//
+// ## 为什么要有这个 API（去重的意义）
+//
+// 在此之前 commondev 插件自带一套 AES-256-GCM 存储，与内核完全重复。
+// 两套库**互不可见**是这个设计最有害的地方 —— 现在统一到一个单例。
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
+	internalSDK "github.com/JianFeeeee/HomeAgent/internal/sdk"
+	internalSecurity "github.com/JianFeeeee/HomeAgent/internal/security"
+	pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
+)
+
+// secretsE2EPlugin 用真实模板编译：只做变量库往返。
+const secretsE2EPlugin = `package main
+
+import (
+	sdk "github.com/JianFeeeee/homeagentsdk/sdk"
+)
+
+type secPlugin struct{ name string }
+
+func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
+	return &secPlugin{name: name}, nil
+}
+
+func (p *secPlugin) Name() string { return p.name }
+func (p *secPlugin) Stop() error  { return nil }
+
+func (p *secPlugin) Start(s *sdk.PluginSDK) error {
+	s.RegisterTool("e2e_secrets", sdk.ToolDef{
+		Description: "变量库往返",
+		Parameters:  map[string]interface{}{"type": "object"},
+	}, func(args map[string]interface{}) (interface{}, error) {
+		sec := s.Secrets()
+		if sec == nil || !sec.Available() {
+			return "UNAVAILABLE", nil
+		}
+		alias, err := sec.Store("e2e-secret-value-9876543210", "e2e")
+		if err != nil {
+			return "STORE_ERR: " + err.Error(), nil
+		}
+		// ★ 只应拿到别名，拿不到明文
+		if alias == "" {
+			return "EMPTY_ALIAS", nil
+		}
+		out, n, _ := sec.Fill("token=@{" + alias + "}")
+		if n != 1 {
+			return "FILL_MISS", nil
+		}
+		return out, nil
+	})
+	return nil
+}
+`
+
+// ★★ 判据：真实模板插件的变量库往返全链路可用。
+func TestE2E_RealTemplateSecretsRoundTrip(t *testing.T) {
+	bin := buildPluginWithRealTemplate(t, secretsE2EPlugin)
+
+	dir := t.TempDir()
+	setTestCodec(t)
+	// 装配**进程级单例**（内核对所有插件共享的那一份）
+	if _, err := internalSecurity.InitGlobal(internalSecurity.Options{
+		Path:    filepath.Join(dir, "variables.json"),
+		KeyFn:   func() ([]byte, error) { return []byte("0123456789abcdef0123456789abcdef"), nil },
+		Enabled: true,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { internalSecurity.SetGlobal(nil) })
+	_ = internalConfig.NewConfigRegistry
+
+	host, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host.Close()
+
+	core := newFakeCore()
+	core.secretsAPI = internalSDK.NewSecretsAPI()
+	p := New("e2e", bin, dir, nil, host, nil)
+	if err := p.Start(core); err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+	defer p.Close()
+
+	core.mu.Lock()
+	handler, ok := core.tools["e2e_secrets"]
+	core.mu.Unlock()
+	if !ok {
+		t.Fatal("插件未注册 e2e_secrets 工具")
+	}
+
+	res, err := handler(map[string]interface{}{})
+	if err != nil {
+		t.Fatalf("调用失败: %v", err)
+	}
+	got, _ := res.(string)
+	if strings.HasPrefix(got, "UNAVAILABLE") || strings.HasPrefix(got, "STORE_ERR") ||
+		strings.HasPrefix(got, "EMPTY_ALIAS") || strings.HasPrefix(got, "FILL_MISS") {
+		t.Fatalf("变量库往返失败: %s", got)
+	}
+	// Fill 应把别名换回明文
+	if !strings.Contains(got, "e2e-secret-value-9876543210") {
+		t.Fatalf("Fill 未换回明文: %q", got)
+	}
+	// 单例里应真的登记了
+	if internalSecurity.Global().Count() != 1 {
+		t.Fatalf("单例应有 1 条，实际 %d", internalSecurity.Global().Count())
+	}
+	t.Logf("✅ 插件经内核变量库完成往返: %s", got)
+}
+
+// ★★ 判据：插件写入的是**内核那一个**变量库（不是自己又建了一套）。
+//
+// 这是去重的核心断言：插件 Store 之后，内核侧能立刻看到。
+func TestE2E_PluginAndKernelShareOneVault(t *testing.T) {
+	bin := buildPluginWithRealTemplate(t, secretsE2EPlugin)
+
+	dir := t.TempDir()
+	setTestCodec(t)
+	st, err := internalSecurity.InitGlobal(internalSecurity.Options{
+		Path:    filepath.Join(dir, "variables.json"),
+		KeyFn:   func() ([]byte, error) { return []byte("0123456789abcdef0123456789abcdef"), nil },
+		Enabled: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { internalSecurity.SetGlobal(nil) })
+
+	host, _ := NewHost()
+	defer host.Close()
+	core := newFakeCore()
+	core.secretsAPI = internalSDK.NewSecretsAPI()
+	p := New("e2e", bin, dir, nil, host, nil)
+	if err := p.Start(core); err != nil {
+		t.Fatal(err)
+	}
+	defer p.Close()
+
+	core.mu.Lock()
+	handler := core.tools["e2e_secrets"]
+	core.mu.Unlock()
+	if _, err := handler(map[string]interface{}{}); err != nil {
+		t.Fatal(err)
+	}
+
+	// ★ 内核侧（同一个单例）应看到插件登记的那条
+	infos := st.List()
+	if len(infos) != 1 {
+		t.Fatalf("内核单例应有 1 条（插件写的），实际 %d —— 说明插件自建了一套库", len(infos))
+	}
+	if infos[0].Note != "e2e" {
+		t.Errorf("备注未透传: %q", infos[0].Note)
+	}
+	// 内核的 Fill 也能用它
+	if out, n, _ := st.Fill("x=@{" + infos[0].Alias + "}"); n != 1 ||
+		!strings.Contains(out, "e2e-secret-value") {
+		t.Errorf("内核 Fill 用不了插件登记的变量: n=%d out=%q", n, out)
+	}
+	t.Logf("✅ 插件与内核共用同一个变量库（别名 %s）", infos[0].Alias)
+}
+
+// ★ 判据：安全模块未启用时 Available()==false（而非 nil panic）。
+func TestE2E_SecretsUnavailableWhenDisabled(t *testing.T) {
+	bin := buildPluginWithRealTemplate(t, secretsE2EPlugin)
+
+	dir := t.TempDir()
+	internalSecurity.SetGlobal(nil)
+	t.Cleanup(func() { internalSecurity.SetGlobal(nil) })
+
+	host, _ := NewHost()
+	defer host.Close()
+	core := newFakeCore()
+	core.secretsAPI = internalSDK.NewSecretsAPI()
+	p := New("e2e", bin, dir, nil, host, nil)
+	if err := p.Start(core); err != nil {
+		t.Fatal(err)
+	}
+	defer p.Close()
+
+	core.mu.Lock()
+	handler := core.tools["e2e_secrets"]
+	core.mu.Unlock()
+	res, err := handler(map[string]interface{}{})
+	if err != nil {
+		t.Fatalf("不该报错（应优雅报告不可用）: %v", err)
+	}
+	if got, _ := res.(string); got != "UNAVAILABLE" {
+		t.Fatalf("未启用时应报 UNAVAILABLE，实际 %q", got)
+	}
+	_ = os.Remove
+	_ = pubsdk.SecretInfo{}
+}
diff --git a/internal/plugin/proc/evtring.go b/internal/plugin/proc/evtring.go
index 6140f625..7b949cfc 100644
--- a/internal/plugin/proc/evtring.go
+++ b/internal/plugin/proc/evtring.go
@@ -8,6 +8,7 @@ import (
 	"sync/atomic"
 	"time"
 
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
 )
 
@@ -170,6 +171,7 @@ type EvtConsumer struct {
 	stop     chan struct{}
 	stopOnce sync.Once
 	done     chan struct{}
+	doneOnce sync.Once // close 纪律：见 internal/safeclose
 }
 
 type evtfdReader interface {
@@ -214,7 +216,7 @@ func (c *EvtConsumer) Run() {
 		c.mu.Lock()
 		c.running = false
 		c.mu.Unlock()
-		close(c.done)
+		safeclose.Safe(&c.doneOnce, c.done)
 	}()
 
 	buf := make([]byte, 8)
@@ -303,7 +305,7 @@ func (c *EvtConsumer) drainEvents() {
 // 若要在 Stop 之后释放 ringData（host.Close 会 munmap 整个区域），
 // 必须先 Stop() 再 Wait()。
 func (c *EvtConsumer) Stop() {
-	c.stopOnce.Do(func() { close(c.stop) })
+	safeclose.Safe(&c.stopOnce, c.stop)
 }
 
 // Wait 阻塞至 Run 退出。返回后 drainEvents 保证不会再访问 ringData。
diff --git a/internal/plugin/proc/exit_order_test.go b/internal/plugin/proc/exit_order_test.go
index 6577864e..a6b10672 100644
--- a/internal/plugin/proc/exit_order_test.go
+++ b/internal/plugin/proc/exit_order_test.go
@@ -17,7 +17,9 @@ import (
 // 解除整块 mmap）。
 //
 // 若 Exited() 先于 onExit 返回而关闭，就会出现：
-//   等待者 → 释放映射 → onExit 仍在读那块内存 → SIGSEGV
+//
+//	等待者 → 释放映射 → onExit 仍在读那块内存 → SIGSEGV
+//
 // 这正是 2026-09-25 全量测试偶发崩溃的根因（栈见 process.go 的 markExited 注释）。
 //
 // ============================ 为什么用原子标志而非 channel ============================
@@ -25,6 +27,7 @@ import (
 // 用一个在回调里置位的原子量 + 在收到关闭信号后立刻读它：
 //   - 修复前：关闭先发生，回调尚未跑 ⇒ 读到 false ⇒ 判红
 //   - 修复后：回调先跑完再关闭 ⇒ 读到 true ⇒ 判绿
+//
 // 用 atomic 而非普通 bool 是为了让「回调的写」与「测试的读」之间
 // 有明确的同步语义（否则是数据竞态，-race 下会报）。
 func TestProcess_OnExitCompletesBeforeExitedCloses(t *testing.T) {
diff --git a/internal/plugin/proc/extra_bag_test.go b/internal/plugin/proc/extra_bag_test.go
index 08c26dbf..8c29a965 100644
--- a/internal/plugin/proc/extra_bag_test.go
+++ b/internal/plugin/proc/extra_bag_test.go
@@ -329,3 +329,44 @@ func TestExtraBag_SnapshotDetectsBagChange(t *testing.T) {
 		t.Fatalf("bag 身份翻转应恰好脏 1 字段（WriteDirty 漏检=绑帧写不回）, got %d", n)
 	}
 }
+
+// ★★★ 判据：内核写的 `comefrom` 必须能过 proc 桥到插件。
+//
+// 为什么必须单独判这一条：QQ 是 **proc 插件**（跨进程、共享段）。
+// 内核侧写对了 comefrom 不等于插件拿得到它 —— 若这个键在桥上丢失，
+// 插件会按"缺失 = user"处理 ⇒ 驻留子**照旧被拦**，而内核侧的判据全绿。
+// 这正是本仓反复吃过的"通道两端各修一半"的坑。
+//
+// 实测背景（2026-10-16）：驻留子的工具调用被 QQ 的用户权限门拦下，
+// 修法是内核在帧上写 comefrom、插件据此跳过用户权限模型。
+// 两端之间的**唯一**通路就是这条。
+func TestExtraBag_ComeFromRoundTrips(t *testing.T) {
+	for _, want := range []string{"internal", "user"} {
+		seg := newTestSeg(t)
+		src := &pubsdk.StageContext{
+			Extra: map[string]interface{}{
+				"input_source": "qq", // 与 comefrom 共存（真实场景就是这样）
+				"comefrom":     want,
+			},
+		}
+		if err := seg.WriteAll(src); err != nil {
+			t.Fatalf("WriteAll(%s): %v", want, err)
+		}
+		var dst pubsdk.StageContext
+		if err := seg.ReadInto(&dst); err != nil {
+			t.Fatalf("ReadInto(%s): %v", want, err)
+		}
+		got, ok := dst.Extra["comefrom"]
+		if !ok {
+			t.Fatalf("★ comefrom=%s 在 proc 桥上丢失 —— 插件会按 user 处理，"+
+				"驻留子照旧被拦（内核侧判据却是绿的）", want)
+		}
+		if s, _ := got.(string); s != want {
+			t.Errorf("comefrom 失真: 期望 %q 实际 %q (%T)", want, got, got)
+		}
+		// 与 input_source 共存时不得互相覆盖
+		if dst.Extra["input_source"] != "qq" {
+			t.Errorf("comefrom 写入了却把 input_source 弄丢了: %v", dst.Extra["input_source"])
+		}
+	}
+}
diff --git a/internal/plugin/proc/handshake_timeout_test.go b/internal/plugin/proc/handshake_timeout_test.go
new file mode 100644
index 00000000..7da88495
--- /dev/null
+++ b/internal/plugin/proc/handshake_timeout_test.go
@@ -0,0 +1,199 @@
+package proc
+
+// 「插件自行声明的建链超时」——**真实消费者**判据（2026-10-16）。
+//
+// 设计见 docs/zh/kernel-modularization-design.md §2.4.2。
+//
+// ## 为什么必须测 proc.Spawn，而不是测 manifest 字段
+//
+// 本仓反复吃过的坑：**字段加了、解析对了，但没人读它**。
+// 只测 `manifest.HandshakeTimeout()` 的换算，删掉 `Start()` 里传给 Spawn 的那一行
+// 判据依然全绿 —— 那是假绿。
+//
+// 所以这里测**真实入口** `proc.Spawn` 的**可观测行为**：用同一个"慢握手"插件，
+// 只改超时值，断言结果随之改变。
+//
+// ## 为什么需要专门的慢插件（slowshakeplugin）
+//
+// 现有的 echoplugin 等**立即**回握手 ⇒ 超时取多少都不会改变结果 ⇒
+// 用它们写的判据必然假绿。要观测超时，被观测对象必须"慢到能让不同超时值分叉"。
+
+import (
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+// spawnWithTimeout 起一个慢握手插件，返回结果（error 与耗时）。
+//
+// delayMS 由 SLOW_SHAKE_MS 环境变量传给插件（见 slowshakeplugin 的说明）。
+func spawnWithTimeout(t *testing.T, timeout time.Duration, delayMS int) (err error, elapsed time.Duration) {
+	t.Helper()
+	bin := buildTestPlugin(t, "slowshakeplugin.go")
+
+	// 环境变量经 os.Environ 传给子进程（Spawn 会继承并追加自己的）。
+	// itoa 复用本包既有实现（shm_profile_test.go），避免重复定义。
+	t.Setenv("SLOW_SHAKE_MS", itoa(delayMS))
+
+	start := time.Now()
+	p, err := Spawn("slowshake", bin, Options{
+		Handler:          noopHandler,
+		HandshakeTimeout: timeout,
+	})
+	elapsed = time.Since(start)
+	if err == nil {
+		p.Kill()
+	}
+	return err, elapsed
+}
+
+// ★★★ **核心判据**：声明的超时真的改变了 Spawn 的行为。
+//
+// 同一个慢插件（握手延迟 3s），只改超时：
+//
+//	超时 1s  ⇒ 必须**失败**（短超时被用上）
+//	超时 10s ⇒ 必须**成功**（长超时被用上，证明"声明更长"真的有效）
+//
+// 这两条一起才构成证明：
+//
+//	· 只有第一条 ⇒ 可能超时参数根本没生效，"失败"另有原因
+//	· 只有第二条 ⇒ 可能参数没生效、只是默认值足够长
+func TestSpawnHonorsDeclaredHandshakeTimeout(t *testing.T) {
+	const delayMS = 3000
+
+	// ① 短超时（1s）必须失败
+	errShort, elShort := spawnWithTimeout(t, 1*time.Second, delayMS)
+	if errShort == nil {
+		t.Fatal("★ 声明 1s 超时、插件延迟 3s，却握手成功了 —— 超时参数没被用上")
+	}
+	// 且必须**大约在** 1s 失败（不是等满 3s 或 10s 才失败）
+	if elShort > 2500*time.Millisecond {
+		t.Errorf("★ 1s 超时却等了 %v 才失败 —— 超时值未生效（像是用了默认值）", elShort)
+	}
+	if elShort < 500*time.Millisecond {
+		t.Errorf("失败过快（%v）—— 失败原因可能不是超时，判据失去意义", elShort)
+	}
+	// 失败原因必须是超时（避免"因为别的原因失败"而假绿）
+	if !strings.Contains(errShort.Error(), "超时") && !strings.Contains(errShort.Error(), "deadline") {
+		t.Errorf("失败原因应指向超时: %v", errShort)
+	}
+
+	// ② 长超时（10s）必须成功
+	errLong, elLong := spawnWithTimeout(t, 10*time.Second, delayMS)
+	if errLong != nil {
+		t.Fatalf("★ 声明 10s 超时、插件延迟 3s，却握手失败 —— 长超时未被用上: %v", errLong)
+	}
+	// 成功耗时必须 ≈ 插件延迟（3s），证明它确实等到了
+	if elLong < 2500*time.Millisecond {
+		t.Errorf("成功过快（%v）—— 插件真的延迟了吗？判据前提可疑", elLong)
+	}
+}
+
+// ★★★ 判据：**未声明超时（<=0）⇒ 用默认值**（存量插件行为逐字不变）。
+//
+// 硬约束：现网 42 个插件的 plugin.json 都没有该字段。
+// 若"未声明"被当成"立即超时"，它们会**全部加载失败** —— 那是破坏性变更。
+func TestSpawnUsesDefaultWhenTimeoutNotDeclared(t *testing.T) {
+	// 延迟 3s：若默认值是 10s（现状），必须成功
+	err, el := spawnWithTimeout(t, 0, 3000)
+	if err != nil {
+		t.Fatalf("★ 未声明超时（0）应回退到默认 %v，却失败: %v", DefaultHandshakeTimeout, err)
+	}
+	if el < 2500*time.Millisecond {
+		t.Errorf("成功过快（%v），判据前提可疑", el)
+	}
+
+	// 负数同样回退默认（不是"立即超时"）
+	err2, _ := spawnWithTimeout(t, -5*time.Second, 3000)
+	if err2 != nil {
+		t.Fatalf("★ 负数超时应回退默认而非立即失败: %v", err2)
+	}
+}
+
+// ★★★ 判据：默认值必须是 10s（唯一真相源，且与文档一致）。
+//
+// 这条独立存在是因为**默认值漂移**很难被发现：
+// 改大/改小都能通过前面所有行为判据（它们只关心"回退发生了"），
+// 而实际影响是"轻插件白等"或"重插件被误杀"。
+func TestDefaultHandshakeTimeoutValue(t *testing.T) {
+	if DefaultHandshakeTimeout != 10*time.Second {
+		t.Errorf("默认建链超时应为 10s（文档与部署预期），实际 %v", DefaultHandshakeTimeout)
+	}
+	// 包内旧名必须与导出名一致（防止两处漂移）
+	if defaultHandshakeTimeout != DefaultHandshakeTimeout {
+		t.Errorf("defaultHandshakeTimeout 与导出名不一致: %v vs %v",
+			defaultHandshakeTimeout, DefaultHandshakeTimeout)
+	}
+}
+
+// 保证 os 包被引用（环境变量传递路径）。
+var _ = os.Getenv
+
+// ★★★ **接线判据**：走真实入口 `proc.NewWithTimeout → Plugin.Start`，
+// 证明声明的超时**穿过构造函数与 Start** 到达 Spawn。
+//
+// ## 为什么必须独立存在（本会话第 10 次同类教训）
+//
+// 上面那条 `TestSpawnHonorsDeclaredHandshakeTimeout` 直接把
+// `Options.HandshakeTimeout` 喂给 `Spawn` —— 它证明的是"**Spawn 会用这个值**"，
+// **没有覆盖** `NewWithTimeout(timeout) → Plugin.handshakeTimeout → Start 里传给 Spawn`
+// 这一段接线。实测：把 `Start()` 里那一行删掉，那条判据**依然全绿**。
+//
+// 而真实路径是：`dynamic_proc.go` 读 manifest → `NewWithTimeout` → `Start` → `Spawn`。
+// 断掉其中任何一环，"插件自行声明超时"就是空谈 —— 正是本仓最怕的
+// "字段加了没人读"。
+func TestPluginStartPassesDeclaredTimeoutToSpawn(t *testing.T) {
+	const delayMS = 3000
+
+	// ① 短超时（1s）+ 慢插件（3s）⇒ Start 必须失败
+	bin := buildTestPlugin(t, "slowshakeplugin.go")
+	t.Setenv("SLOW_SHAKE_MS", itoa(delayMS))
+
+	host, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host.Close()
+
+	p := NewWithTimeout("slow1", bin, t.TempDir(), nil, host, nil, 1*time.Second)
+	start := time.Now()
+	errShort := p.Start(newFakeCore())
+	elShort := time.Since(start)
+	if errShort == nil {
+		p.Close()
+		t.Fatal("★ 声明 1s 超时、插件延迟 3s，Start 却成功了 —— " +
+			"NewWithTimeout 的超时没传到 Spawn（接线断了）")
+	}
+	if elShort > 2500*time.Millisecond {
+		t.Errorf("★ 1s 超时却等了 %v —— 接线可能断了（用了默认值）", elShort)
+	}
+
+	// ② 长超时（10s）+ 同一个慢插件 ⇒ Start 必须成功
+	host2, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host2.Close()
+
+	p2 := NewWithTimeout("slow2", bin, t.TempDir(), nil, host2, nil, 10*time.Second)
+	if err := p2.Start(newFakeCore()); err != nil {
+		t.Fatalf("★ 声明 10s 超时、插件延迟 3s，Start 却失败 —— "+
+			"接线可能把超时弄成了 0 或极小值: %v", err)
+	}
+	defer p2.Close()
+
+	// ③ 不声明的路径（New）必须等价于用默认值 —— 存量插件零改动
+	//    用 3s 延迟 + 默认 10s ⇒ 必须成功
+	host3, err := NewHost()
+	if err != nil {
+		t.Fatalf("NewHost: %v", err)
+	}
+	defer host3.Close()
+
+	p3 := New("slow3", bin, t.TempDir(), nil, host3, nil) // 不传超时
+	if err := p3.Start(newFakeCore()); err != nil {
+		t.Fatalf("★ 不声明超时的插件（存量路径）应走默认 10s 并成功: %v", err)
+	}
+	defer p3.Close()
+}
diff --git a/internal/plugin/proc/ipc_floor_test.go b/internal/plugin/proc/ipc_floor_test.go
index fd7e7063..df7a5155 100644
--- a/internal/plugin/proc/ipc_floor_test.go
+++ b/internal/plugin/proc/ipc_floor_test.go
@@ -62,9 +62,10 @@ func BenchmarkIPC_OSFloorRawPipeEcho(b *testing.B) {
 // BenchmarkIPC_MinimalRPC 最简 RPC 往返：无载荷、不经共享帧。
 //
 // ★ 选 output.invoke 而不是 tool.invoke：前者不要求插件注册任何东西，
-//   插件会回一个「未实现」错误 —— 但**往返已经完成**。
-//   本基准测的是**传输成本**，因此应答内容无关紧要
-//   （且 Call 的错误已被忽略，不会中断计时）。
+//
+//	插件会回一个「未实现」错误 —— 但**往返已经完成**。
+//	本基准测的是**传输成本**，因此应答内容无关紧要
+//	（且 Call 的错误已被忽略，不会中断计时）。
 func BenchmarkIPC_MinimalRPC(b *testing.B) {
 	bin := buildBenchPlugin(b, "echoplugin.go")
 	p, err := Spawn("echo", bin, Options{Handler: noopHandler})
diff --git a/internal/plugin/proc/lock.go b/internal/plugin/proc/lock.go
index f2b7071e..dfeb0c1c 100644
--- a/internal/plugin/proc/lock.go
+++ b/internal/plugin/proc/lock.go
@@ -2,6 +2,7 @@ package proc
 
 import (
 	"fmt"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"sync"
 	"time"
 )
@@ -76,9 +77,10 @@ func (l *stageLock) Acquire(plugin string) error {
 	l.ownerMu.Unlock()
 
 	acquired := make(chan struct{})
+	var acquiredOnce sync.Once
 	go func() {
 		l.mu.Lock()
-		close(acquired)
+		safeclose.Safe(&acquiredOnce, acquired)
 	}()
 
 	select {
diff --git a/internal/plugin/proc/plugin.go b/internal/plugin/proc/plugin.go
index b7d255ba..457e83a1 100644
--- a/internal/plugin/proc/plugin.go
+++ b/internal/plugin/proc/plugin.go
@@ -5,8 +5,10 @@ import (
 	"encoding/json"
 	"fmt"
 	"log"
+	"path/filepath"
 	"sync"
 	"sync/atomic"
+	"time"
 
 	pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
 )
@@ -43,6 +45,11 @@ type Plugin struct {
 	// caps 是 manifest 声明的能力集（§3.8 权限梯度）。
 	caps *capabilitySet
 
+	// handshakeTimeout 是插件**自行声明**的建链超时（manifest 的
+	// handshake_timeout_sec）。<=0 ⇒ 用 DefaultHandshakeTimeout。
+	// 见 docs/zh/kernel-modularization-design.md §2.4.2。
+	handshakeTimeout time.Duration
+
 	// ownerID 是本插件在共享槽池里的身份（由 Host 分配）。
 	// 内核用它校验 arena.free 的归属，并在插件退出时回收残留槽。
 	ownerID uint32
@@ -58,22 +65,36 @@ type Plugin struct {
 	stopping atomic.Bool
 }
 
-// New 创建子进程插件（不启动进程）。
-//
-// host 必须是全部子进程插件共用的实例（由 registry 创建一次）。
 // New 创建子进程插件（不启动进程）。
 //
 // host 必须是全部子进程插件共用的实例（由 registry 创建一次）。
 // capabilities 来自 manifest 的 capabilities 字段；为空时不限制（存量插件向后兼容）。
+//
+// 建链超时用内核默认值。需要按插件声明覆盖时用 NewWithTimeout。
 func New(name, bin, dir string, config map[string]interface{}, host *Host, onCrash func(string, error), capabilities ...string) *Plugin {
+	return NewWithTimeout(name, bin, dir, config, host, onCrash, 0, capabilities...)
+}
+
+// NewWithTimeout 同 New，但可指定**建链（握手）超时**。
+//
+// timeout <= 0 ⇒ 用 DefaultHandshakeTimeout（与 New 行为一致）。
+//
+// ## 为何单独一个构造函数而不是改 New 的签名
+//
+// `New` 末尾是变参 `capabilities ...string`。中间插一个 duration 参数
+// 会让所有调用点错位（值会静默地用错），而编译器**不会**报错
+// （变参位置可吞类型兼容的实参）——那是本仓最怕的"静默错误"。
+// 加一个新构造函数既保持旧签名不变，又把新能力显式化。
+func NewWithTimeout(name, bin, dir string, config map[string]interface{}, host *Host, onCrash func(string, error), timeout time.Duration, capabilities ...string) *Plugin {
 	return &Plugin{
-		name:    name,
-		bin:     bin,
-		dir:     dir,
-		config:  config,
-		host:    host,
-		onCrash: onCrash,
-		caps:    newCapabilitySet(capabilities),
+		name:             name,
+		bin:              bin,
+		dir:              dir,
+		config:           config,
+		host:             host,
+		onCrash:          onCrash,
+		caps:             newCapabilitySet(capabilities),
+		handshakeTimeout: timeout,
 	}
 }
 
@@ -131,13 +152,24 @@ func (p *Plugin) Start(core CoreSDK) error {
 	p.handler.invokeStageFn = p.invokeStage
 	p.handler.invokeOutput = p.invokeOutput
 
+	// ★ 显式把插件目录传给**插件进程**（随机化之前的隐式 cwd 不可靠：
+	// 插件自己 chdir 后就失效，而 rawfile 的路径解析依赖它）。
+	pluginEnv := append([]string{}, p.env...)
+	pluginEnv = append(pluginEnv,
+		"HA_PLUGIN_DIR="+p.dir,
+		"HA_PLUGIN_RAWFILE_DIR="+filepath.Join(p.dir, "rawfile"),
+		"HA_PLUGIN_WORK_DIR="+filepath.Join(p.dir, "work"),
+	)
+
 	proc, err := Spawn(p.name, p.bin, Options{
 		Dir: p.dir,
+		// 插件自行声明的建链超时（<=0 时 Spawn 内部回退到默认值）。
+		HandshakeTimeout: p.handshakeTimeout,
 		// 共享段的传递机制按平台不同（shmpass_*.go）：
 		// Unix 经 ExtraFiles 传继承 fd（3=统一共享内存区域 SuperBlock+StageContext+EvtRing，
 		// 4=事件通知 eventfd）；Windows 无 fd 继承语义，改用命名内核对象，名字经环境变量传入。
 		// 权威定义在 shmpass_unix.go 的 procExtraFilesForShm，修改时三处必须同步。
-		Env:         append(p.env, p.host.procEnvForShm()...),
+		Env:         append(pluginEnv, p.host.procEnvForShm()...),
 		ExtraFiles:  p.host.procExtraFilesForShm(),
 		ShmSize:     p.host.shmSize,
 		EvtRingSize: evtTotalSize,
diff --git a/internal/plugin/proc/plugin_test.go b/internal/plugin/proc/plugin_test.go
index b6c47d0d..aede5eb3 100644
--- a/internal/plugin/proc/plugin_test.go
+++ b/internal/plugin/proc/plugin_test.go
@@ -39,6 +39,12 @@ type fakeCoreSDK struct {
 	// 用接口而非具体类型：需要能塞入"只实现公开 KnowledgeAPI、
 	// 不具备内核多模态扩展"的替身，以验证能力缺失时的报错路径。
 	knowledge knowledgeAPITest
+
+	// settingsAPI 是可注入的真实配置后端（端到端加密判据用）。
+	// 为 nil 时 Settings() 返回 nil（旧行为不变）。
+	settingsAPI pubsdk.SettingsAPI
+	// secretsAPI 同理：变量库后端（端到端判据用）。
+	secretsAPI pubsdk.SecretsAPI
 }
 
 // knowledgeAPITest 是公开 SDK 的知识库契约（不含内核扩展方法）。
@@ -61,7 +67,8 @@ func newFakeCore() *fakeCoreSDK {
 }
 
 func (f *fakeCoreSDK) PluginName() string                  { return "fake" }
-func (f *fakeCoreSDK) Settings() pubsdk.SettingsAPI        { return nil }
+func (f *fakeCoreSDK) Settings() pubsdk.SettingsAPI        { return f.settingsAPI }
+func (f *fakeCoreSDK) Secrets() pubsdk.SecretsAPI          { return f.secretsAPI }
 func (f *fakeCoreSDK) Memory() pubsdk.MemoryAPI            { return nil }
 func (f *fakeCoreSDK) TextMemory() pubsdk.TextMemoryAPI    { return nil }
 func (f *fakeCoreSDK) DocMemory() pubsdk.DocMemoryAPI      { return f.docMem }
diff --git a/internal/plugin/proc/process.go b/internal/plugin/proc/process.go
index e2284b3e..37a5e145 100644
--- a/internal/plugin/proc/process.go
+++ b/internal/plugin/proc/process.go
@@ -10,12 +10,14 @@ import (
 	"log"
 	"os"
 	"os/exec"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"syscall"
 	"time"
 
 	"github.com/JianFeeeee/HomeAgent/internal/meta"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 )
 
 // Process 管理一个外部插件子进程：spawn / 双向 JSON-RPC / 优雅停止 / 崩溃检测。
@@ -55,18 +57,20 @@ type Process struct {
 	handler RequestHandler
 
 	// exited 在进程被收割后关闭，用于唤醒所有等待者。
-	exited    chan struct{}
-	exitOnce  sync.Once
-	exitErr   atomic.Pointer[error]
-	readerWG  sync.WaitGroup
-	waiterWG  sync.WaitGroup
-	readyOnce sync.Once
-	ready     chan struct{}
+	exited     chan struct{}
+	exitedOnce sync.Once
+	exitOnce   sync.Once
+	exitErr    atomic.Pointer[error]
+	readerWG   sync.WaitGroup
+	waiterWG   sync.WaitGroup
+	readyOnce  sync.Once
+	ready      chan struct{}
 
 	// waitErr 由**唯一的** waitLoop 写入：cmd.Wait() 的返回值。
 	// waitDone 关闭后 waitErr 才可读。
-	waitErr  error
-	waitDone chan struct{}
+	waitErr      error
+	waitDone     chan struct{}
+	waitDoneOnce sync.Once
 
 	// onExit 在进程退出时回调（内核用它喂 plugin_health.recordCrash，
 	// 以及 ForceRelease 释放该插件持有的 stage 锁）。
@@ -110,7 +114,12 @@ type Options struct {
 
 // 默认超时。
 const (
-	defaultHandshakeTimeout = 10 * time.Second
+	// DefaultHandshakeTimeout 是内核与插件**建链（握手）**的默认超时。
+	//
+	// 导出它是因为它是**唯一真相源**：插件的 manifest 换算
+	// （PluginManifest.HandshakeTimeout）必须引用这个常量，
+	// 否则两处会各自漂移（"以为改了一处其实另一处没改"）。
+	DefaultHandshakeTimeout = 10 * time.Second
 	// stopGracePeriod 是发出 plugin.stop 后等待进程自行退出的时间。
 	// 超时则 Kill——**这是"真正的取消"**，对比 cgo 路径超时后线程永久泄漏。
 	stopGracePeriod = 5 * time.Second
@@ -119,6 +128,9 @@ const (
 	killReapTimeout = 2 * time.Second
 )
 
+// defaultHandshakeTimeout 是包内旧名（保持既有调用点不改）。
+const defaultHandshakeTimeout = DefaultHandshakeTimeout
+
 // ErrProcessExited 表示子进程已退出，调用无法完成。
 var ErrProcessExited = errors.New("proc: 插件进程已退出")
 
@@ -282,6 +294,33 @@ func (p *Process) handshake(timeout time.Duration) error {
 //
 // 参考 clawhubadapter/sidecarProcess 的成熟做法：大 buffer 防长行截断、
 // pending 表定位应答、退出时唤醒全部等待者。
+// summarizeFrame 把一段非 JSON 文本压成单行摘要（诊断用）。
+//
+// 用途：让"插件往 stdout 打印了什么"一眼可见 —— 否则只看到
+// 「invalid character 'x'」而不知道是哪句话（实测排查代价见 readLoop 里那段注释）。
+//
+// 处理：
+//   - 控制字符（\r\n\t 等）替换成空格，避免多行打散日志
+//   - 超长截断并标注原始字节数
+func summarizeFrame(b []byte, max int) string {
+	var sb strings.Builder
+	for _, c := range b {
+		if c < 0x20 || c == 0x7f {
+			sb.WriteByte(' ')
+			continue
+		}
+		sb.WriteByte(c)
+		if sb.Len() >= max {
+			break
+		}
+	}
+	out := strings.TrimSpace(sb.String())
+	if len(b) > max {
+		return out + fmt.Sprintf(" …（共 %d 字节，已截断）", len(b))
+	}
+	return out
+}
+
 func (p *Process) readLoop() {
 	defer p.readerWG.Done()
 
@@ -290,7 +329,7 @@ func (p *Process) readLoop() {
 	// 超大 payload 应走共享内存 arena 而非 RPC 帧。
 	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
 
-	p.readyOnce.Do(func() { close(p.ready) })
+	safeclose.Safe(&p.readyOnce, p.ready)
 
 	for scanner.Scan() {
 		line := scanner.Bytes()
@@ -303,7 +342,32 @@ func (p *Process) readLoop() {
 			Method string `json:"method"`
 		}
 		if err := json.Unmarshal(line, &probe); err != nil {
-			log.Printf("[proc] %s 收到非法 JSON 帧（%d 字节）: %v", p.name, len(line), err)
+			// ★★★ 这条日志必须**可定位**（2026-10-16 实测修正）。
+			//
+			// ## 原问题的形态
+			//
+			// 子进程插件的 **stdout 是 JSON-RPC 协议通道**，stderr 才是日志通道
+			// （SDK 侧 log.SetOutput(os.Stderr)）。插件若用 `fmt.Printf` 写日志，
+			// 那句话会以**裸文本**进入协议流 ⇒ 就是这里。
+			//
+			// 原日志只报「收到非法 JSON 帧（N 字节）: invalid character 'x'」：
+			//   · **不显示内容** ⇒ 看不到是"哪句话"混进来了；
+			//   · **不提原因** ⇒ 看起来像协议/内核故障，不像"插件自己 printf"。
+			//
+			// 实测代价：生产环境累计 **1038 条**这种报错（weather 113 / rss 103 /
+			// calendar 102 / 第三方 huawei_smarthome 720），而真因只是那 4 个插件
+			// 用了 fmt.Printf。定位它花了一整轮排查。
+			//
+			// ⇒ 现在把**内容摘要**与**可能原因 + 修法**一起打出来。
+			// 限长是因为坏帧可能很大（插件打了长文本/二进制），
+			// 截断到 160 字节足以认出"这是哪句日志"。
+			log.Printf("[proc] %s 收到非法 JSON 帧（%d 字节）: %v\n"+
+				"        ↑ 内容摘要: %s\n"+
+				"        可能原因：插件往 **stdout** 打印了日志，而 stdout 是"+
+				"JSON-RPC **协议通道**（stderr 才是日志通道）。\n"+
+				"        修法：把插件里的 fmt.Printf/fmt.Println 改成 log.Printf"+
+				"（脚手架模板 1.4.0 起已修正）。",
+				p.name, len(line), err, summarizeFrame(line, 160))
 			continue
 		}
 
@@ -357,7 +421,7 @@ func (p *Process) readLoop() {
 func (p *Process) waitLoop() {
 	defer p.waiterWG.Done()
 	p.waitErr = p.cmd.Wait()
-	close(p.waitDone)
+	safeclose.Safe(&p.waitDoneOnce, p.waitDone)
 
 	// 主动拆管道：若孙子进程仍持有 stdout 写端，readLoop 不会自己退，
 	// 关掉读端逼它从 Scan 里出来（报 file already closed，已预期）。
@@ -401,7 +465,7 @@ func (p *Process) markExited() {
 			ch <- &Response{Error: ErrProcessExited.Error()}
 		}
 
-		// ★ 顺序至关重要：onExit 必须在 close(p.exited) **之前**完成。
+		// ★ 顺序至关重要：onExit 必须在 safeclose.Safe(&p.exitedOnce, p.exited) **之前**完成。
 		//
 		// onExit（内核侧即 Plugin.handleExit）会调 Host.ReclaimOwner 回收该插件
 		// 残留的共享槽——**那是要读共享内存区域的**。而 exited 一关闭，
@@ -424,7 +488,7 @@ func (p *Process) markExited() {
 			p.onExit(p.name, p.ExitError())
 		}
 
-		close(p.exited)
+		safeclose.Safe(&p.exitedOnce, p.exited)
 	})
 }
 
@@ -639,9 +703,10 @@ func (p *Process) Kill() error {
 	// 超时后主动关掉读端，强制 readLoop 从 Scan 里出来（file already closed，
 	// 已在 waitLoop 里被列为预期错误）。
 	readerDone := make(chan struct{})
+	var readerDoneOnce sync.Once
 	go func() {
 		p.readerWG.Wait()
-		close(readerDone)
+		safeclose.Safe(&readerDoneOnce, readerDone)
 	}()
 	select {
 	case <-readerDone:
diff --git a/internal/plugin/proc/process_test.go b/internal/plugin/proc/process_test.go
index 830fa9e7..97081b8e 100644
--- a/internal/plugin/proc/process_test.go
+++ b/internal/plugin/proc/process_test.go
@@ -502,3 +502,74 @@ func TestSupervisor_TrackAfterCloseKillsProcess(t *testing.T) {
 		t.Error("关停后冒出的进程应被立即结束")
 	}
 }
+
+// ★★★ 判据：**非法帧的报错必须可定位**（含内容摘要与修法）。
+//
+// ## 为什么必须有这条
+//
+// 原报错只有「收到非法 JSON 帧（N 字节）: invalid character 'x'」——
+//
+//	· **不显示内容** ⇒ 看不到是哪句话混进来了；
+//	· **不提原因** ⇒ 看起来像协议/内核故障，不像"插件自己 printf"。
+//
+// 实测代价：生产环境累计 **1038 条**这种报错（weather 113 / rss 103 /
+// calendar 102 / 第三方 huawei_smarthome 720），定位真因花了一整轮排查。
+//
+// ⇒ 本判据守两件事：
+//
+//	① `summarizeFrame` 真的能把坏帧压成可读单行（含控制字符处理与截断）；
+//	② readLoop 的报错**文本里含**原因与修法（否则等于没改）。
+func TestSummarizeFrameIsReadable(t *testing.T) {
+	cases := []struct {
+		in       string
+		wantPart string
+	}{
+		{"[weather] started\n", "[weather] started"},
+		{"line1\r\nline2\n", "line1  line2"},
+		{"\x00\x01binary", "binary"},
+		{"  padded  ", "padded"},
+	}
+	for _, c := range cases {
+		got := summarizeFrame([]byte(c.in), 160)
+		if !strings.Contains(got, c.wantPart) {
+			t.Errorf("summarizeFrame(%q) = %q，期望含 %q", c.in, got, c.wantPart)
+		}
+		if strings.ContainsAny(got, "\n\r") {
+			t.Errorf("摘要不得含换行（会打散日志）: %q", got)
+		}
+	}
+	// 截断：长输入必须标注原长
+	long := strings.Repeat("x", 500)
+	got := summarizeFrame([]byte(long), 160)
+	if len(got) > 260 {
+		t.Errorf("超长输入未被截断: %d 字节", len(got))
+	}
+	if !strings.Contains(got, "500") {
+		t.Errorf("截断时必须标注原始字节数: %q", got)
+	}
+}
+
+// ★★★ 判据：readLoop 的非法帧报错**必须点明原因与修法**。
+//
+// ★ 源码扫描在此**恰当**：断言的是"报错文案里是否含某关键词"，
+//
+//	属于"模式存在性"，不是接线/顺序断言。
+func TestIllegalFrameErrorIsActionable(t *testing.T) {
+	src, err := os.ReadFile("process.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	code := string(src)
+	// 必须提到"stdout 是协议通道"这个原因
+	for _, kw := range []string{"协议通道", "log.Printf"} {
+		if !strings.Contains(code, kw) {
+			t.Errorf("★ 非法帧报错未提及 %q —— 插件作者看不到"+
+				"「这是我自己 printf 造成的」这个关键信息", kw)
+		}
+	}
+	// 必须真的调用 summarizeFrame（否则摘要不会出现在日志里）
+	if !strings.Contains(code, "summarizeFrame(line") {
+		t.Error("★ readLoop 必须调用 summarizeFrame 把坏帧内容打进日志" +
+			"（否则只看到 invalid character 'x'，不知道是哪句话）")
+	}
+}
diff --git a/internal/plugin/proc/protocol.go b/internal/plugin/proc/protocol.go
index 08146976..e953285c 100644
--- a/internal/plugin/proc/protocol.go
+++ b/internal/plugin/proc/protocol.go
@@ -166,6 +166,22 @@ const (
 	MethodSettingsDump        = "settings.dump"        // 44
 	MethodSettingsPlugins     = "settings.plugins"     // 45
 	MethodSettingsDataDir     = "settings.dataDir"     // 51
+	// 密文读写（强制加密，不看键名）—— 与 settings.set/get 的区别是
+	// 这两个**必然**走加密路径，用于插件用中性键名存凭据的场景。
+	MethodSettingsSetSecret = "settings.setSecret" // 52
+	MethodSettingsGetSecret = "settings.getSecret" // 53
+
+	// 变量库（全局共享，非 per-plugin；见 internal/security 与 corehandler_secrets.go）。
+	//
+	// 与 settings 的分工是本质的：settings 是**每个插件自己的**配置，
+	// secrets 是**全进程共享**的变量库单例（主/子/驻留子 agent 与全部插件共用）。
+	MethodSecretsAvailable = "secrets.available" // 32
+	MethodSecretsStore     = "secrets.store"     // 33
+	MethodSecretsList      = "secrets.list"      // 34
+	MethodSecretsForget    = "secrets.forget"    // 35
+	MethodSecretsFill      = "secrets.fill"      // 36
+	MethodSecretsEncrypt   = "secrets.encrypt"   // 46
+	MethodSecretsDecrypt   = "secrets.decrypt"   // 47
 
 	// LLM 源（原 case 19/20/37）
 	MethodLLMListSources   = "llm.listSources"   // 19
@@ -188,6 +204,14 @@ const (
 	MethodPluginReloadOne  = "plugin.reloadOne"  // 48
 	MethodPluginListLoaded = "plugin.listLoaded" // 49
 	MethodPluginIsDisabled = "plugin.isDisabled" // 50
+	// ---- 运行态启停（设计 §2.6.7）：与 isDisabled（持久态）分开 ----
+	//
+	// ★ 为何必须桥接：子进程插件走本桥，未在此登记的方法会被
+	// corehandler 直接拒（"未知 method"）⇒ SDK 上加了方法但插件**调不通**。
+	// 同进程插件（.so）直接调 SDK，不受影响 —— 这个不对称容易漏。
+	MethodPluginMgrStop             = "plugin.mgrStop"             // 51
+	MethodPluginMgrStart            = "plugin.mgrStart"            // 52
+	MethodPluginMgrIsRuntimeStopped = "plugin.mgrIsRuntimeStopped" // 53
 
 	// 共享段锁仲裁（新增，无对应 method id —— C ABI 下不存在跨进程锁概念）
 	MethodStageLock   = "stage.lock"
diff --git a/internal/plugin/proc/shmcodec.go b/internal/plugin/proc/shmcodec.go
index 41086dad..0f568896 100644
--- a/internal/plugin/proc/shmcodec.go
+++ b/internal/plugin/proc/shmcodec.go
@@ -325,7 +325,6 @@ func (s *Segment) ReadInto(sc *pubsdk.StageContext) error {
 		}
 	}
 
-
 	var respPtr *string
 	if s.getFlag(flagResponseSet) {
 		r, err := getStr(fResponse)
diff --git a/internal/plugin/proc/supervisor.go b/internal/plugin/proc/supervisor.go
index c697ede7..25d8fc6f 100644
--- a/internal/plugin/proc/supervisor.go
+++ b/internal/plugin/proc/supervisor.go
@@ -2,6 +2,7 @@ package proc
 
 import (
 	"fmt"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"log"
 	"sort"
 	"sync"
@@ -137,7 +138,8 @@ func (s *Supervisor) StopAll(timeout time.Duration) {
 	}
 
 	done := make(chan struct{})
-	go func() { wg.Wait(); close(done) }()
+	var doneOnce sync.Once
+	go func() { wg.Wait(); safeclose.Safe(&doneOnce, done) }()
 
 	if timeout <= 0 {
 		timeout = stopGracePeriod * 2
diff --git a/internal/plugin/proc/testdata/slowshakeplugin.go b/internal/plugin/proc/testdata/slowshakeplugin.go
new file mode 100644
index 00000000..3ba4370b
--- /dev/null
+++ b/internal/plugin/proc/testdata/slowshakeplugin.go
@@ -0,0 +1,77 @@
+//go:build ignore
+
+// slowshakeplugin 故意**延迟回复握手**，用于验证「插件自行声明的建链超时」真的生效。
+//
+// 为什么需要这个测试替身（而不是复用现有的 echoplugin）：
+// 现有插件都**立即**回握手，于是"超时值"这个参数无论取多少都不会改变行为 ——
+// 用它们写的判据必然假绿（删掉超时逻辑也不报红）。
+// 要真正观测超时，被观测的插件必须**慢到能让不同超时值产生不同结果**。
+//
+// 延迟由环境变量 SLOW_SHAKE_MS 控制（毫秒），由判据按用例设置：
+//
+//	· 声明超时 1s + 延迟 3s  ⇒ 必须**失败**（证明短超时真的被用上）
+//	· 声明超时 10s + 延迟 3s ⇒ 必须**成功**（证明长超时真的被用上）
+//
+// 握手契约见 internal/plugin/proc/process.go 的 handshake()：
+// 内核发 method="handshake"，插件回 {result:{sdk_version:...}}；
+// 主版本号必须与内核一致，否则握手被拒（那会让判据因无关原因失败）。
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"os"
+	"strconv"
+	"time"
+)
+
+type request struct {
+	ID     uint64          `json:"id,omitempty"`
+	Method string          `json:"method"`
+	Params json.RawMessage `json:"params,omitempty"`
+}
+
+type response struct {
+	ID     uint64      `json:"id"`
+	Result interface{} `json:"result,omitempty"`
+	Error  string      `json:"error,omitempty"`
+}
+
+func main() {
+	delay := 0
+	if v := os.Getenv("SLOW_SHAKE_MS"); v != "" {
+		delay, _ = strconv.Atoi(v)
+	}
+
+	in := bufio.NewScanner(bufio.NewReader(os.Stdin))
+	in.Buffer(make([]byte, 1<<20), 1<<20)
+	out := bufio.NewWriter(os.Stdout)
+	send := func(v interface{}) {
+		b, _ := json.Marshal(v)
+		out.Write(b)
+		out.WriteByte('\n')
+		out.Flush()
+	}
+
+	for in.Scan() {
+		var req request
+		if err := json.Unmarshal(in.Bytes(), &req); err != nil {
+			continue
+		}
+		switch req.Method {
+		case "handshake":
+			// ★ 关键：故意延迟，且**在延迟期间不读下一帧** ——
+			// 真实的慢插件就是这样（忙着初始化，来不及应答）。
+			if delay > 0 {
+				time.Sleep(time.Duration(delay) * time.Millisecond)
+			}
+			// sdk_version 的主版本必须与内核一致（否则握手会因版本不匹配被拒，
+			// 判据就测不到超时这个变量了）。
+			send(response{ID: req.ID, Result: map[string]interface{}{
+				"sdk_version": "1.4.0",
+			}})
+		default:
+			send(response{ID: req.ID, Result: map[string]interface{}{}})
+		}
+	}
+}
diff --git a/internal/plugin/proc_core.go b/internal/plugin/proc_core.go
index 0816fed2..3353f032 100644
--- a/internal/plugin/proc_core.go
+++ b/internal/plugin/proc_core.go
@@ -34,6 +34,14 @@ func (c procCore) PluginName() string { return c.sdk.PluginName() }
 // errUnavailable，若把「类型化的 nil」透过去，判空会失效——插件收到的是
 // panic 而不是"能力不可用"。
 
+// Secrets 转发到内核的**全局**变量库（进程级单例，不是 per-plugin 配置）。
+func (c procCore) Secrets() pubsdk.SecretsAPI {
+	if v := c.sdk.Secrets(); v != nil {
+		return v
+	}
+	return nil
+}
+
 func (c procCore) Settings() pubsdk.SettingsAPI {
 	if s := c.sdk.Settings(); s != nil {
 		return s
diff --git a/internal/plugin/registry.go b/internal/plugin/registry.go
index 57272f08..7a6304c9 100644
--- a/internal/plugin/registry.go
+++ b/internal/plugin/registry.go
@@ -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 回调（那是删除专用语义）。目录由调用方管理。
diff --git a/internal/plugin/runtime_state_test.go b/internal/plugin/runtime_state_test.go
new file mode 100644
index 00000000..593adc10
--- /dev/null
+++ b/internal/plugin/runtime_state_test.go
@@ -0,0 +1,308 @@
+package plugin
+
+// 插件**运行态 vs 持久态**分离的判据（2026-10-16）。
+//
+// 设计见 docs/zh/kernel-modularization-design.md §2.6.7。
+//
+// ## 这组判据守的是什么
+//
+// 用户指出"只有 reload" —— 实测确认现有 API 全都是
+// "改运行态 **顺带** 改持久态"：
+//
+//	DisablePlugin → cfgReg.AddDisabledPlugin     （持久禁用）
+//	Enable        → cfgReg.RemoveDisabledPlugin  （解除持久禁用）
+//
+// 于是 agent **无法**"只是现在关掉它"而不影响开机自启。
+// 这组判据要求：运行态操作**绝不**触碰持久状态。
+//
+// ## 判据必须测真实加载路径
+//
+// 本仓教训（重复 10+ 次）：只测 helper 会假绿。
+// 这里用**真工厂 + 真 loadOne**（经 Registry.Load），并断言
+// ① 持久配置真的没被写 ② 插件真的被停/起。
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
+	isdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// fakeLifecyclePlugin 记录生命周期调用（真工厂产出的插件）。
+type fakeLifecyclePlugin struct {
+	name   string
+	starts int
+	stops  int
+}
+
+func (p *fakeLifecyclePlugin) Name() string { return p.name }
+func (p *fakeLifecyclePlugin) Start(s *isdk.PluginSDK) error {
+	p.starts++
+	return nil
+}
+func (p *fakeLifecyclePlugin) Stop() error {
+	p.stops++
+	return nil
+}
+
+// newRuntimeStateReg 建一个可真实加载 `alpha` 的 Registry（含临时数据目录）。
+func newRuntimeStateReg(t *testing.T) (*Registry, string, *fakeLifecyclePlugin) {
+	t.Helper()
+	dir := t.TempDir()
+	plgDir := filepath.Join(dir, "plugins")
+	if err := os.MkdirAll(plgDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	r := NewRegistry()
+	r.SetPluginDir(plgDir)
+	r.SetDataDir(dir)
+	// ★ 必须装一个**真** cfgReg：持久禁用状态就存在它里面，
+	//   而 isDisabled 在 cfgReg==nil 时恒返回 false（判据会假绿）。
+	//   这是"必须测真实入口"的又一具体落点。
+	reg := internalConfig.NewConfigRegistry(filepath.Join(dir, "config.db"))
+	t.Cleanup(func() { reg.Close() })
+	r.SetConfigRegistry(reg)
+
+	fp := &fakeLifecyclePlugin{name: "alpha"}
+	r.RegisterNative("alpha", func(name string, cfg map[string]interface{}) (isdk.Plugin, error) {
+		return fp, nil
+	})
+	return r, dir, fp
+}
+
+// ★★★ 判据：**StopPlugin 不写持久禁用配置**（运行态 ≠ 持久态）。
+//
+// 这是本组最核心的一条。若实现里误调了 DisablePlugin（或它内部的
+// AddDisabledPlugin），用户下次开机会发现"我只是关了一下，怎么不启动了"。
+func TestStopPluginDoesNotTouchPersistentState(t *testing.T) {
+	r, dir, fp := newRuntimeStateReg(t)
+	if err := r.Load(dir + "/plugins"); err != nil {
+		t.Fatal(err)
+	}
+	if fp.starts == 0 {
+		t.Fatal("前置失败：插件未被真实加载")
+	}
+
+	if err := r.StopPlugin("alpha"); err != nil {
+		t.Fatalf("StopPlugin: %v", err)
+	}
+
+	// ① 真的停了
+	if fp.stops == 0 {
+		t.Fatal("★ StopPlugin 没有真的停掉插件（只改了标记）")
+	}
+	// ② 运行态门置位
+	if !r.IsPluginRuntimeStopped("alpha") {
+		t.Fatal("StopPlugin 后应处于运行态关闭")
+	}
+	// ③ ★ 持久态**未变**：IsPluginDisabled 必须仍为 false
+	if r.IsPluginDisabled("alpha") {
+		t.Fatal("★ StopPlugin 写了持久禁用 —— 用户下次开机会发现插件不自启了" +
+			"（这正是要修的行为）")
+	}
+}
+
+// ★★★ 判据：**StartPlugin 不解除持久禁用**（且被持久禁用时拒绝）。
+//
+// 反向的误用：若 StartPlugin 调了 Enable（它内部 RemoveDisabledPlugin），
+// 就会把用户"明确禁止这个插件"的决定悄悄改掉。
+func TestStartPluginRefusesPersistentlyDisabled(t *testing.T) {
+	r, dir, _ := newRuntimeStateReg(t)
+	if err := r.Load(dir + "/plugins"); err != nil {
+		t.Fatal(err)
+	}
+
+	// 持久禁用（模拟用户的明确决定）
+	if err := r.DisablePlugin("alpha", "test"); err != nil {
+		t.Fatalf("DisablePlugin: %v", err)
+	}
+	if !r.IsPluginDisabled("alpha") {
+		t.Fatal("前置失败：应已持久禁用")
+	}
+
+	// ★ StartPlugin 必须**拒绝**（不能绕过用户的明确决定）。
+	//
+	// ★ 断言错误**原因**，不能只看 err != nil：
+	//   去掉我那句显式检查后，loadOne 里还有一道 isDisabled 门会挡住 ⇒
+	//   StartPlugin 仍返回错误（"启动插件失败"）⇒ 只查非 nil 就**空转**了。
+	//   必须要求原因指向"持久禁用"，才能区分"按预期拒绝"与"因别的原因失败"。
+	err := r.StartPlugin("alpha")
+	if err == nil {
+		t.Fatal("★ StartPlugin 加载了被持久禁用的插件 —— 绕过了用户的明确决定")
+	}
+	if !strings.Contains(err.Error(), "持久禁用") {
+		t.Fatalf("★ StartPlugin 拒绝的原因不是\"持久禁用\"（判据空转，无法区分真正原因）: %v", err)
+	}
+	// 且必须仍处于持久禁用（不得被这次尝试清掉）
+	if !r.IsPluginDisabled("alpha") {
+		t.Fatal("★ StartPlugin 悄悄清除了持久禁用标记")
+	}
+}
+
+// ★★★ 判据：**StopPlugin → StartPlugin 能往返**（运行态关闭可被清除）。
+func TestStopThenStartRoundTrip(t *testing.T) {
+	r, dir, fp := newRuntimeStateReg(t)
+	if err := r.Load(dir + "/plugins"); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := r.StopPlugin("alpha"); err != nil {
+		t.Fatal(err)
+	}
+	if !r.IsPluginRuntimeStopped("alpha") {
+		t.Fatal("应处于运行态关闭")
+	}
+
+	// 启动：应清门并重新加载
+	startsBefore := fp.starts
+	if err := r.StartPlugin("alpha"); err != nil {
+		t.Fatalf("StartPlugin: %v", err)
+	}
+	if r.IsPluginRuntimeStopped("alpha") {
+		t.Fatal("★ StartPlugin 没有清掉运行态门（下次 loadOne 会被它挡住）")
+	}
+	if fp.starts <= startsBefore {
+		t.Fatal("★ StartPlugin 没有真的重新加载")
+	}
+	// 持久态全程未变
+	if r.IsPluginDisabled("alpha") {
+		t.Fatal("往返过程动了持久态")
+	}
+}
+
+// ★★★ 判据：**运行态关闭不持久**（重启后插件正常加载）。
+//
+// 这是有意设计：运行态关闭 = "这一次不跑"，不是"以后都不跑"。
+// 若它持久，agent 关掉一个插件后就再也没法让它随内核起来。
+func TestRuntimeStopIsNotPersistent(t *testing.T) {
+	r, dir, _ := newRuntimeStateReg(t)
+	if err := r.Load(dir + "/plugins"); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.StopPlugin("alpha"); err != nil {
+		t.Fatal(err)
+	}
+	if !r.IsPluginRuntimeStopped("alpha") {
+		t.Fatal("前置失败")
+	}
+
+	// 模拟"重启"：新建一个 Registry（不共享任何内存状态）
+	r2, dir2, fp2 := newRuntimeStateReg(t)
+	_ = dir2
+	r2.SetPluginDir(r.PluginDir())
+	r2.RegisterNative("alpha", func(name string, cfg map[string]interface{}) (isdk.Plugin, error) {
+		return fp2, nil
+	})
+	if r2.IsPluginRuntimeStopped("alpha") {
+		t.Fatal("★ 运行态关闭跨实例保留了 —— 它必须是会话级的（重启即复位）")
+	}
+	// 重启后应能正常加载
+	if err := r2.Load(r.PluginDir()); err != nil {
+		t.Fatal(err)
+	}
+	if fp2.starts == 0 {
+		t.Fatal("★ 重启后被运行态关闭过的插件未能加载 —— " +
+			"agent 关掉它之后就再也起不来了（正是要修的毛病）")
+	}
+}
+
+// ★★★ 判据：**持久禁用仍走原来的门**（不能因新门而失效）。
+//
+// 持久禁用优先于运行态：被持久禁用的插件即使开始未运行态关闭，也不得加载。
+func TestPersistentDisableStillBlocksLoad(t *testing.T) {
+	r, dir, fp := newRuntimeStateReg(t)
+	if err := r.DisablePlugin("alpha", "test"); err != nil {
+		t.Fatalf("DisablePlugin: %v", err)
+	}
+	if err := r.Load(dir + "/plugins"); err != nil {
+		t.Fatal(err)
+	}
+	if fp.starts != 0 {
+		t.Fatal("★ 持久禁用的插件被加载了（旧门失效）")
+	}
+}
+
+// ★★★ 判据：**pluginmgr 与 webui 不能被关闭/禁用**（防自锁）。
+//
+// 为何必须在内核层面拦：agent 可以犯错，而这两个操作一旦执行，
+// agent **无法从自己这侧恢复**（要启动 pluginmgr 得先有 pluginmgr）。
+func TestRefuseSelfLockOnCriticalPlugins(t *testing.T) {
+	r := NewRegistry()
+
+	// ★ 判据要断言三件事，不能只看 err != nil：
+	//
+	// 我第一次只查 `err == nil` ⇒ **空转**：去掉守卫后 StopPlugin 仍会报
+	// "plugin pluginmgr 未在运行"（因为没注册工厂），判据照样通过。
+	// 错误**原因**不同却无法区分，是判据失焦。
+	//
+	// 正确的断言：
+	//   ① 返回错误 ② 错误信息点明"拒绝"（自锁守卫的措辞）
+	//   ③ **状态未被改动**（这才是自锁的实质危害）
+	checkRefused := func(t *testing.T, err error, what string) {
+		t.Helper()
+		if err == nil {
+			t.Fatalf("★ 允许%s pluginmgr —— agent 无法从自己这侧恢复", what)
+		}
+		if !strings.Contains(err.Error(), "拒绝") {
+			t.Fatalf("★ %s 返回的错误不是自锁守卫给的（原因不明确，判据空转）: %v", what, err)
+		}
+	}
+
+	checkRefused(t, r.StopPlugin("pluginmgr"), "运行态关闭")
+	// ③ 实质危害：门**不得**被置位
+	if r.IsPluginRuntimeStopped("pluginmgr") {
+		t.Fatal("★ 自锁守卫没拦住：pluginmgr 已被标记运行态关闭（它再也启动不回来了）")
+	}
+
+	checkRefused(t, r.DisablePlugin("pluginmgr", "agent"), "持久禁用")
+	// ③ 更糟的实质危害：持久禁用不得被写入
+	if r.IsPluginDisabled("pluginmgr") {
+		t.Fatal("★ 自锁守卫没拦住：pluginmgr 已被**持久禁用**（重启也不恢复）")
+	}
+
+	checkRefused(t, r.StopPlugin("webui"), "运行态关闭")
+
+	// 普通插件**不受**自锁守卫影响（守卫不能不问对象）（守卫不能误伤）
+	err := r.StopPlugin("someplugin")
+	if err == nil {
+		t.Fatal("未安装的普通插件应返回错误")
+	}
+	if strings.Contains(err.Error(), "拒绝") {
+		t.Fatalf("★ 自锁守卫误伤了普通插件: %v", err)
+	}
+}
+
+// ★★★ 判据：**StopPlugin 摸掉注册面**（否则旧闭包指向已死实例）。
+//
+// 与 ReloadOne/Disable 同一处置：不摸的后果是模型仍能看到旧工具并调用，
+// 只能拿到 ErrProcessExited（通道/工具永久指向死实例）。
+func TestStopPluginDetachesRegistrationSurface(t *testing.T) {
+	r, dir, _ := newRuntimeStateReg(t)
+	if err := r.Load(dir + "/plugins"); err != nil {
+		t.Fatal(err)
+	}
+	r.mu.Lock()
+	_, hadChannels := r.pluginChannels["alpha"]
+	_, hadSDK := r.sdkRefs["alpha"]
+	r.mu.Unlock()
+
+	if err := r.StopPlugin("alpha"); err != nil {
+		t.Fatal(err)
+	}
+
+	r.mu.Lock()
+	_, stillLoaded := r.plugins["alpha"]
+	_, stillSDK := r.sdkRefs["alpha"]
+	r.mu.Unlock()
+	if stillLoaded {
+		t.Fatal("★ StopPlugin 后插件仍在注册表里")
+	}
+	if stillSDK {
+		t.Fatal("★ StopPlugin 后 sdkRefs 未清 —— 旧 SDK 引用指向已死实例")
+	}
+	// 记录一下前置状态（避免 unused 警告同时留下诊断信息）
+	t.Logf("前置: channels=%v sdk=%v", hadChannels, hadSDK)
+}
diff --git a/internal/plugins/agentcli/plugin.go b/internal/plugins/agentcli/plugin.go
index b9b210bb..e31ce271 100644
--- a/internal/plugins/agentcli/plugin.go
+++ b/internal/plugins/agentcli/plugin.go
@@ -14,6 +14,7 @@ import (
 	"time"
 
 	"github.com/JianFeeeee/HomeAgent/internal/plugin"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
 )
 
@@ -55,6 +56,8 @@ type terminalWatch struct {
 }
 
 type TerminalSession struct {
+	stopOnce  sync.Once
+	doneOnce  sync.Once
 	id        string
 	command   string
 	cmd       *exec.Cmd
@@ -105,7 +108,7 @@ func (t *TerminalSession) Close() {
 	t.closed = true
 	t.mu.Unlock()
 
-	close(t.stopCh)
+	safeclose.Safe(&t.stopOnce, t.stopCh)
 	// 终止进程并释放 PTY（幂等；readLoop 自然退出时已调过就直接返回）。
 	t.releaseResources()
 	// 等 readLoop 走完退出流程（它会发最后的 output/停止事件）。
@@ -156,6 +159,7 @@ func (t *TerminalSession) IsExpired() bool {
 }
 
 type Plugin struct {
+	stopChOnce     sync.Once
 	name           string
 	mu             sync.Mutex
 	wg             sync.WaitGroup
@@ -435,8 +439,12 @@ func (p *Plugin) Stop() error {
 	// 幂等：Stop 可能被多条路径调到（StopAndUnload 后再 StopAll、
 	// 停机与热重载交错）。close 一个已关闭的 channel 会 panic，
 	// 故用 Once 兜住。
+	// ★ 不能写成 p.stopOnce.Do(func(){ safeclose.Safe(&p.stopOnce, ...) })：
+	// sync.Once 不可重入 ⇒ 外层 Do 持锁、内层 Do 等同一把锁 ⇒ **自锁死锁**
+	// （实测：agentcli 测试 600s 超时，栈显示 sync.(*Once).Do 嵌套）。
+	// 正确做法：close 的守卫用**独立的** once。
 	p.stopOnce.Do(func() {
-		close(p.stopCh)
+		safeclose.Safe(&p.stopChOnce, p.stopCh)
 		p.shutdown()
 	})
 	return nil
@@ -919,7 +927,7 @@ func (t *TerminalSession) releaseResources() {
 
 func (p *Plugin) readLoop(t *TerminalSession, s *sdk.PluginSDK) {
 	defer p.wg.Done()
-	defer close(t.done)
+	defer safeclose.Safe(&t.doneOnce, t.done)
 
 	// 无论从哪个分支退出，都释放进程与 PTY。
 	//
diff --git a/internal/plugins/agentcli/plugin_stub.go b/internal/plugins/agentcli/plugin_stub.go
index ec46d928..ec8df74f 100644
--- a/internal/plugins/agentcli/plugin_stub.go
+++ b/internal/plugins/agentcli/plugin_stub.go
@@ -16,6 +16,6 @@ func init() {
 
 type stubPlugin struct{}
 
-func (p *stubPlugin) Name() string                 { return "agentcli" }
+func (p *stubPlugin) Name() string                   { return "agentcli" }
 func (p *stubPlugin) Start(sdk *sdk.PluginSDK) error { return nil }
-func (p *stubPlugin) Stop() error                  { return nil }
+func (p *stubPlugin) Stop() error                    { return nil }
diff --git a/internal/plugins/agentcli/pty_windows_test.go b/internal/plugins/agentcli/pty_windows_test.go
index 42662668..915ff141 100644
--- a/internal/plugins/agentcli/pty_windows_test.go
+++ b/internal/plugins/agentcli/pty_windows_test.go
@@ -44,10 +44,16 @@ func drainFor(term ptyTerm, dur time.Duration) []byte {
 	buf := make([]byte, 4096)
 	var out []byte
 	for time.Now().Before(deadline) {
-		ch := make(chan struct{ N int; E error }, 1)
+		ch := make(chan struct {
+			N int
+			E error
+		}, 1)
 		go func() {
 			n, e := term.Read(buf)
-			ch <- struct{ N int; E error }{n, e}
+			ch <- struct {
+				N int
+				E error
+			}{n, e}
 		}()
 		select {
 		case r := <-ch:
diff --git a/internal/plugins/clawhubadapter/plugin.go b/internal/plugins/clawhubadapter/plugin.go
index bd6aae65..e139a87b 100644
--- a/internal/plugins/clawhubadapter/plugin.go
+++ b/internal/plugins/clawhubadapter/plugin.go
@@ -20,6 +20,7 @@ import (
 
 	"github.com/JianFeeeee/HomeAgent/internal/events"
 	"github.com/JianFeeeee/HomeAgent/internal/plugin"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
 )
 
@@ -44,6 +45,7 @@ func init() {
 }
 
 type Plugin struct {
+	stopChOnce   sync.Once
 	name         string
 	skillsDir    string
 	simulatorDir string
@@ -54,8 +56,8 @@ type Plugin struct {
 	dispatcher   *RegistryDispatcher
 	httpClient   *http.Client
 
-	stopCh    chan struct{}
-	stopOnce  sync.Once
+	stopCh   chan struct{}
+	stopOnce sync.Once
 }
 
 // pluginSingleton 内核单例引用（Start 时设置），供 SendToChannel/ChannelSender 使用
@@ -308,41 +310,41 @@ func (p *Plugin) ipcGoroutine(s *sdk.PluginSDK) {
 			p.mu.Lock()
 			simDir := p.simulatorDir
 			p.mu.Unlock()
-		if simDir == "" {
-			continue
-		}
-
-		// 1. Write settings snapshot for CLI config:get/config:list
-		settings := s.Settings().Dump()
-		if data, err := json.MarshalIndent(settings, "", "  "); err == nil {
-			os.WriteFile(filepath.Join(simDir, ".settings.json"), data, 0644)
-		}
-
-		// 2. Process pending settings changes from CLI config:set
-		pendingPath := filepath.Join(simDir, ".settings-pending.json")
-		if data, err := os.ReadFile(pendingPath); err == nil {
-			var pending map[string]interface{}
-			if json.Unmarshal(data, &pending) == nil {
-				for k, v := range pending {
-					s.Settings().Set(k, v)
-				}
+			if simDir == "" {
+				continue
 			}
-			os.Remove(pendingPath)
-		}
 
-		// 3. Process reload requests from CLI plugin:install
-		reloadPath := filepath.Join(simDir, ".reload-request")
-		if data, err := os.ReadFile(reloadPath); err == nil {
-			name := strings.TrimSpace(string(data))
-			if name != "" {
-				if err := p.reloadPlugin(name); err != nil {
-					log.Printf("[clawhubadapter] reload from CLI: %v", err)
-				} else {
-					log.Printf("[clawhubadapter] reloaded plugin from CLI request: %s", name)
-				}
+			// 1. Write settings snapshot for CLI config:get/config:list
+			settings := s.Settings().Dump()
+			if data, err := json.MarshalIndent(settings, "", "  "); err == nil {
+				os.WriteFile(filepath.Join(simDir, ".settings.json"), data, 0644)
+			}
+
+			// 2. Process pending settings changes from CLI config:set
+			pendingPath := filepath.Join(simDir, ".settings-pending.json")
+			if data, err := os.ReadFile(pendingPath); err == nil {
+				var pending map[string]interface{}
+				if json.Unmarshal(data, &pending) == nil {
+					for k, v := range pending {
+						s.Settings().Set(k, v)
+					}
+				}
+				os.Remove(pendingPath)
+			}
+
+			// 3. Process reload requests from CLI plugin:install
+			reloadPath := filepath.Join(simDir, ".reload-request")
+			if data, err := os.ReadFile(reloadPath); err == nil {
+				name := strings.TrimSpace(string(data))
+				if name != "" {
+					if err := p.reloadPlugin(name); err != nil {
+						log.Printf("[clawhubadapter] reload from CLI: %v", err)
+					} else {
+						log.Printf("[clawhubadapter] reloaded plugin from CLI request: %s", name)
+					}
+				}
+				os.Remove(reloadPath)
 			}
-			os.Remove(reloadPath)
-		}
 		}
 	}
 }
@@ -983,7 +985,9 @@ func (p *Plugin) loadOCPlugin(s *sdk.PluginSDK, dir, name string) error {
 	data, listErr := mgr.call("plugins/list", nil)
 	if listErr == nil && data != nil {
 		var result struct {
-			Plugins []struct{ Name string `json:"name"` } `json:"plugins"`
+			Plugins []struct {
+				Name string `json:"name"`
+			} `json:"plugins"`
 		}
 		if json.Unmarshal(data, &result) == nil {
 			for _, pl := range result.Plugins {
@@ -1131,7 +1135,8 @@ func ChannelSender() *Plugin {
 	return pluginSingleton
 }
 
-func (p *Plugin) loadPySidecar(s *sdk.PluginSDK, dir, name string) error {	simPath := filepath.Join(p.simulatorDir, "pysim.py")
+func (p *Plugin) loadPySidecar(s *sdk.PluginSDK, dir, name string) error {
+	simPath := filepath.Join(p.simulatorDir, "pysim.py")
 	if err := os.MkdirAll(p.simulatorDir, 0755); err != nil {
 		return fmt.Errorf("create simulator dir: %w", err)
 	}
@@ -1225,8 +1230,9 @@ func (p *Plugin) Stop() error {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 	// 关停 ipcGoroutine（stopCh），避免重载后旧 goroutine 残留导致线程累积
+	// 见 agentcli 同类注释：Once 不可重入，close 的守卫必须用独立 once。
 	p.stopOnce.Do(func() {
-		close(p.stopCh)
+		safeclose.Safe(&p.stopChOnce, p.stopCh)
 	})
 	for _, sp := range p.sidecars {
 		sp.Close()
@@ -1264,8 +1270,8 @@ func hasOCExtensions(pkgPath string) bool {
 	}
 	var pkg struct {
 		OpenClaw *struct {
-			Extensions         interface{} `json:"extensions"`
-			RuntimeExtensions  interface{} `json:"runtimeExtensions"`
+			Extensions        interface{} `json:"extensions"`
+			RuntimeExtensions interface{} `json:"runtimeExtensions"`
 		} `json:"openclaw"`
 	}
 	if err := json.Unmarshal(data, &pkg); err != nil {
diff --git a/internal/plugins/clawhubadapter/sidecar.go b/internal/plugins/clawhubadapter/sidecar.go
index 039d88f2..3e7f5b44 100644
--- a/internal/plugins/clawhubadapter/sidecar.go
+++ b/internal/plugins/clawhubadapter/sidecar.go
@@ -4,6 +4,7 @@ import (
 	"bufio"
 	"encoding/json"
 	"fmt"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"io"
 	"log"
 	"os"
@@ -51,18 +52,31 @@ type OCNotification struct {
 	Params  json.RawMessage `json:"params"`
 }
 
+// pendingResp 是待应答通道 + 它自己的 close 守卫。
+//
+// 为什么需要 once：Close() 可能被多条路径调用（Stop / 重载 / 停机），
+// 而 `close(ch)` 二次即 panic（本仓 close 纪律，见 internal/safeclose）。
+// 这些 channel 是**按请求创建**的，不能共用一个全局 Once ⇒ 每个自带一个。
+type pendingResp struct {
+	ch   chan []byte
+	once sync.Once
+}
+
+func (p *pendingResp) closeOnce() { safeclose.Safe(&p.once, p.ch) }
+
 type sidecarProcess struct {
-	name    string
-	dir     string
-	cmd     *exec.Cmd
-	stdin   *bufio.Writer
-	mu      sync.Mutex
-	nextID  int
-	closed  bool
-	stopped bool
+	readerReadyOnce sync.Once
+	name            string
+	dir             string
+	cmd             *exec.Cmd
+	stdin           *bufio.Writer
+	mu              sync.Mutex
+	nextID          int
+	closed          bool
+	stopped         bool
 
 	// 异步 reader
-	pending     map[int]chan<- []byte
+	pending     map[int]*pendingResp
 	notifyCh    chan OCNotification
 	readerStop  chan struct{}
 	readerWg    sync.WaitGroup
@@ -75,7 +89,7 @@ func newSidecarProcess(name, dir string, cmd *exec.Cmd, stdin *bufio.Writer, std
 		dir:         dir,
 		cmd:         cmd,
 		stdin:       stdin,
-		pending:     make(map[int]chan<- []byte),
+		pending:     make(map[int]*pendingResp),
 		notifyCh:    make(chan OCNotification, 1024),
 		readerStop:  make(chan struct{}),
 		readerReady: make(chan struct{}),
@@ -91,7 +105,7 @@ func (s *sidecarProcess) readLoop(r io.Reader) {
 	scanner := bufio.NewScanner(bufio.NewReader(r))
 	// 加大 scanner buffer 防止长行截断
 	scanner.Buffer(make([]byte, 0, 1024*64), 1024*64)
-	close(s.readerReady)
+	safeclose.Safe(&s.readerReadyOnce, s.readerReady)
 
 	for {
 		select {
@@ -119,12 +133,11 @@ func (s *sidecarProcess) readLoop(r io.Reader) {
 
 		if base.ID != nil {
 			s.mu.Lock()
-			ch, ok := s.pending[*base.ID]
+			pr, ok := s.pending[*base.ID]
 			delete(s.pending, *base.ID)
 			s.mu.Unlock()
 			if ok {
-				ch <- []byte(line)
-				close(ch)
+				pr.ch <- []byte(line)
 			}
 		} else if base.Method != "" {
 			var notif OCNotification
@@ -226,7 +239,7 @@ func (s *sidecarProcess) call(method string, params interface{}) ([]byte, error)
 	}
 	s.nextID++
 	id := s.nextID
-	s.pending[id] = ch
+	s.pending[id] = &pendingResp{ch: ch}
 
 	req := sidecarRequest{
 		JSONRPC: "2.0",
@@ -324,9 +337,9 @@ func (s *sidecarProcess) CallTool(name string, args map[string]interface{}) (str
 
 func (s *sidecarProcess) CallProvider(providerType string, args map[string]interface{}) (string, error) {
 	data, err := s.call("provider/call", map[string]interface{}{
-		"type": providerType,
+		"type":   providerType,
 		"action": "execute",
-		"args": args,
+		"args":   args,
 	})
 	if err != nil {
 		return "", err
@@ -366,8 +379,8 @@ func (s *sidecarProcess) Close() {
 	s.readerWg.Wait()
 
 	s.mu.Lock()
-	for id, ch := range s.pending {
-		close(ch)
+	for id, pr := range s.pending {
+		pr.closeOnce()
 		delete(s.pending, id)
 	}
 	s.mu.Unlock()
diff --git a/internal/plugins/clawhubadapter/sidecar_test.go b/internal/plugins/clawhubadapter/sidecar_test.go
index a9c7d090..570e6630 100644
--- a/internal/plugins/clawhubadapter/sidecar_test.go
+++ b/internal/plugins/clawhubadapter/sidecar_test.go
@@ -15,24 +15,30 @@ type mockSettings struct{}
 
 func (m *mockSettings) DataDir() string { return "/tmp/mock_data" }
 
-func (m *mockSettings) Get(key string) (interface{}, error) { return nil, nil }
-func (m *mockSettings) Set(key string, value interface{}) error { return nil }
-func (m *mockSettings) List(prefix string) ([]string, error) { return nil, nil }
-func (m *mockSettings) GetCore(key string) (interface{}, error) { return nil, nil }
-func (m *mockSettings) SetCore(key string, value interface{}) error { return nil }
-func (m *mockSettings) ListCore(prefix string) ([]string, error) { return nil, nil }
-func (m *mockSettings) GetPlugin(plugin, key string) (interface{}, error) { return nil, nil }
+func (m *mockSettings) Get(key string) (interface{}, error)                   { return nil, nil }
+func (m *mockSettings) Set(key string, value interface{}) error               { return nil }
+func (m *mockSettings) SetSecret(key string, value interface{}) error         { return nil }
+func (m *mockSettings) GetSecret(key string) (string, error)                  { return "", nil }
+func (m *mockSettings) List(prefix string) ([]string, error)                  { return nil, nil }
+func (m *mockSettings) GetCore(key string) (interface{}, error)               { return nil, nil }
+func (m *mockSettings) SetCore(key string, value interface{}) error           { return nil }
+func (m *mockSettings) ListCore(prefix string) ([]string, error)              { return nil, nil }
+func (m *mockSettings) GetPlugin(plugin, key string) (interface{}, error)     { return nil, nil }
 func (m *mockSettings) SetPlugin(plugin, key string, value interface{}) error { return nil }
-func (m *mockSettings) ListPlugin(plugin, prefix string) ([]string, error) { return nil, nil }
-func (m *mockSettings) RegisterDef(def pubsdk.ConfigDef) {}
-func (m *mockSettings) Defs(prefix string) []*pubsdk.ConfigDef { return nil }
-func (m *mockSettings) Dump() map[string]interface{} { return nil }
-func (m *mockSettings) Plugins() []string { return nil }
-func (m *mockSettings) DefsCore(prefix string) []*sdk.ConfigDef { return nil }
+func (m *mockSettings) ListPlugin(plugin, prefix string) ([]string, error)    { return nil, nil }
+
+// IsSecret：E-3 起 SettingsAPI 要求实现（判断某键是否按密文存储）。
+// 判据实现返回 false（mock 里没有密文语义），够用即可。
+func (m *mockSettings) IsSecret(key string) bool                          { return false }
+func (m *mockSettings) RegisterDef(def pubsdk.ConfigDef)                  {}
+func (m *mockSettings) Defs(prefix string) []*pubsdk.ConfigDef            { return nil }
+func (m *mockSettings) Dump() map[string]interface{}                      { return nil }
+func (m *mockSettings) Plugins() []string                                 { return nil }
+func (m *mockSettings) DefsCore(prefix string) []*sdk.ConfigDef           { return nil }
 func (m *mockSettings) DefsPlugin(plugin, prefix string) []*sdk.ConfigDef { return nil }
-func (m *mockSettings) Remove(key string) error { return nil }
-func (m *mockSettings) RemoveCore(key string) error { return nil }
-func (m *mockSettings) RemovePlugin(plugin, key string) error { return nil }
+func (m *mockSettings) Remove(key string) error                           { return nil }
+func (m *mockSettings) RemoveCore(key string) error                       { return nil }
+func (m *mockSettings) RemovePlugin(plugin, key string) error             { return nil }
 
 func TestLaunchSidecarNoMainJS(t *testing.T) {
 	tmpDir := t.TempDir()
@@ -205,8 +211,8 @@ func TestConcurrentCalls(t *testing.T) {
 			if err != nil {
 				t.Errorf("concurrent call %d: %v", n, err)
 			}
-			if result != fmt.Sprintf("%d", n + n*2) {
-				t.Errorf("call %d: expected %d, got %s", n, n + n*2, result)
+			if result != fmt.Sprintf("%d", n+n*2) {
+				t.Errorf("call %d: expected %d, got %s", n, n+n*2, result)
 			}
 			done <- true
 		}(i)
diff --git a/internal/plugins/deepsearch_e2e_test.go b/internal/plugins/deepsearch_e2e_test.go
index 525bbc25..dda2951c 100644
--- a/internal/plugins/deepsearch_e2e_test.go
+++ b/internal/plugins/deepsearch_e2e_test.go
@@ -146,14 +146,17 @@ func TestRealPlugin_DeepSearchStatusInvoke(t *testing.T) {
 // CAPTCHA 等**外部条件**，与代码是否正确无关。
 //
 // 此前这条测试把它们一视同仁地判红：实测失败信息是
-//   brave(Suspended: too many requests), duckduckgo(CAPTCHA), google cse(Suspended: ...)
+//
+//	brave(Suspended: too many requests), duckduckgo(CAPTCHA), google cse(Suspended: ...)
+//
 // 于是「上游限流」被当成「搜索能力坏了」。更糟的是它**不可控地随机红**：
 // 用 A/B 对照实测（同一时段连跑 20 轮）干净树也复现 2 次失败，
 // 与任何代码改动无关 —— 这种判据会让真正的回归淹没在噪声里。
 //
 // 现在的语义：
-//   上游限流/CAPTCHA ⇒ t.Skip（带明确理由，不静默通过）
-//   其他异常         ⇒ t.Fatalf/Fail（真回归）
+//
+//	上游限流/CAPTCHA ⇒ t.Skip（带明确理由，不静默通过）
+//	其他异常         ⇒ t.Fatalf/Fail（真回归）
 func upstreamUnavailable(text string) bool {
 	// 插件只有在「无任何结果」时才输出这句；有结果时不会出现。
 	return strings.Contains(text, "未返回结果")
diff --git a/internal/plugins/healthcheck/plugin.go b/internal/plugins/healthcheck/plugin.go
index aa78302c..6e717a23 100644
--- a/internal/plugins/healthcheck/plugin.go
+++ b/internal/plugins/healthcheck/plugin.go
@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/JianFeeeee/HomeAgent/internal/plugin"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
 )
 
@@ -42,6 +43,7 @@ func init() {
 }
 
 type Plugin struct {
+	stopOnce      sync.Once
 	name          string
 	mu            sync.Mutex
 	reports       []llmReport
@@ -303,13 +305,10 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 
 func (p *Plugin) Stop() error {
 	// 幂等关闭：仅当 stopCh 未被关闭时 close。
-	p.mu.Lock()
-	select {
-	case <-p.stopCh:
-	default:
-		close(p.stopCh)
-	}
-	p.mu.Unlock()
+	// 用 safeclose 统一入口（本仓 close 纪律）。
+	// 原实现是 `select{case <-p.stopCh: default: close(...)}`：
+	// 单线程安全，但**并发**下两个 goroutine 可同时落到 default ⇒ 双 close panic。
+	safeclose.Safe(&p.stopOnce, p.stopCh)
 	return nil
 }
 
diff --git a/internal/plugins/healthcheck/plugin_test.go b/internal/plugins/healthcheck/plugin_test.go
index a90cfad0..33e000a1 100644
--- a/internal/plugins/healthcheck/plugin_test.go
+++ b/internal/plugins/healthcheck/plugin_test.go
@@ -32,7 +32,7 @@ func (tc *toolCapture) RegisterTool(name string, def sdk.ToolDef, handler sdk.To
 	return nil
 }
 func (tc *toolCapture) RegisterStage(stage sdk.Stage, handler sdk.StageHandler) {}
-func (tc *toolCapture) RegisterAPI(name string) error                          { return nil }
+func (tc *toolCapture) RegisterAPI(name string) error                           { return nil }
 
 func newTestSDK(cfg sdk.SDKConfig) *sdk.PluginSDK {
 	if cfg.Settings == nil {
@@ -558,5 +558,3 @@ func TestReportsToChecks(t *testing.T) {
 		t.Error("fail report must NOT pass")
 	}
 }
-
-
diff --git a/internal/plugins/kbtree/plugin.go b/internal/plugins/kbtree/plugin.go
index b82f00cd..b9fe9d5e 100644
--- a/internal/plugins/kbtree/plugin.go
+++ b/internal/plugins/kbtree/plugin.go
@@ -52,7 +52,7 @@ type Plugin struct {
 	// expose 是暴露范围（nil/空 = 全部可见）。见 scope.go。
 	expose *scope
 	// kn 是知识库句柄的测试注入口（生产从 sdkRef 取）。
-	kn sdk.KnowledgeAPI
+	kn     sdk.KnowledgeAPI
 	server *http.Server
 	mux    *http.ServeMux
 	// 启动时未显式配置 token 则自动生成（与 remotedevice 同策略）
diff --git a/internal/plugins/mcp/plugin.go b/internal/plugins/mcp/plugin.go
index 94eccc92..a6c5ad33 100644
--- a/internal/plugins/mcp/plugin.go
+++ b/internal/plugins/mcp/plugin.go
@@ -14,10 +14,10 @@ import (
 // MCP 服务器配置（来自 config_mcp 表或 skill.json）
 type serverConfig struct {
 	Name    string   `json:"name"`
-	Command string   `json:"command,omitempty"`  // stdio 模式
+	Command string   `json:"command,omitempty"` // stdio 模式
 	Args    []string `json:"args,omitempty"`
 	Env     []string `json:"env,omitempty"`
-	URL     string   `json:"url,omitempty"`      // SSE 模式
+	URL     string   `json:"url,omitempty"` // SSE 模式
 }
 
 func init() {
diff --git a/internal/plugins/mcp/stdio.go b/internal/plugins/mcp/stdio.go
index 6341bc4e..072a4d7b 100644
--- a/internal/plugins/mcp/stdio.go
+++ b/internal/plugins/mcp/stdio.go
@@ -4,6 +4,7 @@ import (
 	"bufio"
 	"encoding/json"
 	"fmt"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"io"
 	"os"
 	"os/exec"
@@ -12,13 +13,22 @@ import (
 )
 
 // StdioTransport 通过子进程 stdin/stdout 进行 JSON-RPC 通信
+// pendingRPC 是待应答通道 + 它自己的 close 守卫（本仓 close 纪律）。
+type pendingRPC struct {
+	ch   chan *rpcResponse
+	once sync.Once
+}
+
+func (p *pendingRPC) closeOnce() { safeclose.Safe(&p.once, p.ch) }
+
 type StdioTransport struct {
-	cmd    *exec.Cmd
-	stdin  io.WriteCloser
-	stdout *bufio.Reader
-	mu     sync.Mutex
-	pending map[int]chan *rpcResponse
-	done    chan struct{}
+	doneOnce sync.Once
+	cmd      *exec.Cmd
+	stdin    io.WriteCloser
+	stdout   *bufio.Reader
+	mu       sync.Mutex
+	pending  map[int]*pendingRPC
+	done     chan struct{}
 }
 
 func NewStdioTransport(command string, args []string, env []string) (*StdioTransport, error) {
@@ -46,7 +56,7 @@ func NewStdioTransport(command string, args []string, env []string) (*StdioTrans
 		cmd:     cmd,
 		stdin:   stdin,
 		stdout:  bufio.NewReader(stdout),
-		pending: make(map[int]chan *rpcResponse),
+		pending: make(map[int]*pendingRPC),
 		done:    make(chan struct{}),
 	}
 
@@ -60,24 +70,24 @@ func (t *StdioTransport) readLoop() {
 	for {
 		var resp rpcResponse
 		if err := dec.Decode(&resp); err != nil {
-			close(t.done)
+			safeclose.Safe(&t.doneOnce, t.done)
 			// 通知所有等待的请求
 			t.mu.Lock()
-			for _, ch := range t.pending {
-				close(ch)
+			for _, pr := range t.pending {
+				pr.closeOnce()
 			}
-			t.pending = make(map[int]chan *rpcResponse)
+			t.pending = make(map[int]*pendingRPC)
 			t.mu.Unlock()
 			return
 		}
 
 		t.mu.Lock()
-		ch, ok := t.pending[resp.ID]
+		pr, ok := t.pending[resp.ID]
 		delete(t.pending, resp.ID)
 		t.mu.Unlock()
 
 		if ok {
-			ch <- &resp
+			pr.ch <- &resp
 		}
 	}
 }
@@ -90,7 +100,7 @@ func (t *StdioTransport) Send(req *rpcRequest) (*rpcResponse, error) {
 
 	ch := make(chan *rpcResponse, 1)
 	t.mu.Lock()
-	t.pending[req.ID] = ch
+	t.pending[req.ID] = &pendingRPC{ch: ch}
 	t.mu.Unlock()
 
 	if _, err := t.stdin.Write(data); err != nil {
diff --git a/internal/plugins/pluginmgr/lifecycle_tools_test.go b/internal/plugins/pluginmgr/lifecycle_tools_test.go
new file mode 100644
index 00000000..76adb75c
--- /dev/null
+++ b/internal/plugins/pluginmgr/lifecycle_tools_test.go
@@ -0,0 +1,153 @@
+package pluginmgr
+
+// plugin_start/stop/enable/disable 工具的判据（2026-10-16）。
+//
+// 设计见 docs/zh/kernel-modularization-design.md §2.6.7.4。
+//
+// ## 判据重点：**工具的措辞必须让 agent 选对**
+//
+// 四个工具里两两一对，差别只在**是否持久**：
+//
+//	plugin_stop    vs plugin_disable   （停掉 vs 停掉且以后也不自启）
+//	plugin_start   vs plugin_enable    （拉起 vs 拉起且以后开机也自启）
+//
+// agent 只能靠 Description 分辨。若描述不区分，agent 会在"临时关一下"
+// 的场景误用 plugin_disable ⇒ 用户下次开机发现插件不自启（真实缺陷场景）。
+//
+// ## 判据必须走真实 registerTools
+//
+// 本仓教训：只查"源码里有这个字符串"会被 `if false &&` 之类的
+// 写法骗过（E-3 那次实测）。所以这里真的调 registerTools 并捕获注册结果。
+
+import (
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/events"
+	"github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// collectToolDefs 走真实 registerTools 收集工具定义。
+//
+// 捕获点是 `SDKConfig.RegTool`（真实注册落点），不是别处的副本 ——
+// 这样"某工具被删掉/改名"必然反映在这里。
+func collectToolDefs(t *testing.T) map[string]sdk.ToolDef {
+	t.Helper()
+	defs := map[string]sdk.ToolDef{}
+	sdkInst := sdk.New("pluginmgr", sdk.SDKConfig{
+		Settings:  &pmSettings{},
+		EventBus:  events.NewBus(),
+		PluginMgr: &fakePluginMgr{},
+		RegTool: func(name string, def sdk.ToolDef, h sdk.ToolHandler) error {
+			defs[name] = def
+			return nil
+		},
+	})
+	p := &Plugin{name: "pluginmgr"}
+	p.registerTools(sdkInst)
+	if len(defs) == 0 {
+		t.Fatal("registerTools 未注册任何工具 —— 捕获点失效，本文件全部判据会假绿")
+	}
+	return defs
+}
+
+// ★★★ 判据：**四个生命周期工具全部注册**（走真实注册路径）。
+func TestLifecycleToolsAreRegistered(t *testing.T) {
+	defs := collectToolDefs(t)
+	for _, want := range []string{"plugin_start", "plugin_stop", "plugin_enable", "plugin_disable"} {
+		if _, ok := defs[want]; !ok {
+			t.Errorf("★ 缺少工具 %s —— agent 无法%s插件", want, want)
+		}
+	}
+	// 原有 6 个不得因新增而丢失（回归）
+	for _, want := range []string{"plugin_install", "plugin_list", "plugin_status",
+		"plugin_restart", "plugin_remove", "plugin_info"} {
+		if _, ok := defs[want]; !ok {
+			t.Errorf("★ 原有工具 %s 丢失（回归）", want)
+		}
+	}
+}
+
+// ★★★ 判据：**运行态与持久态工具的描述必须互相点名**。
+//
+// 这是防止 agent 误用的**唯一手段**（工具选择完全靠描述）。
+func TestRuntimeVsPersistentToolDescriptionsDisambiguate(t *testing.T) {
+	defs := collectToolDefs(t)
+
+	// ★ 两条**独立**断言（不能用 || 合并）：
+	//
+	// 第一版写成 `!A && !B` ⇒ 去掉 A（"不改持久状态"）后 B（"不会影响开机自启"）
+	// 仍在 ⇒ 整条通过 ⇒ **变异没咬住**。两个措辞各有作用：
+	//   A = 直接陈述"不改持久"（正面定义）
+	//   B = 描述用户可观察的后果（背面印证）
+	// 缺任一都让 agent 更难判断，所以**两条都要在**。
+	stop := defs["plugin_stop"].Description
+	if !strings.Contains(stop, "不改持久状态") {
+		t.Errorf("★ plugin_stop 描述未出现\"不改持久状态\"（正面定义缺失）\n%s", stop)
+	}
+	if !strings.Contains(stop, "不会影响开机自启") {
+		t.Errorf("★ plugin_stop 描述未出现\"不会影响开机自启\"（后果说明缺失）\n%s", stop)
+	}
+	if !strings.Contains(stop, "plugin_disable") {
+		t.Errorf("★ plugin_stop 描述未指向 plugin_disable（持久关闭）作为对比\n%s", stop)
+	}
+
+	dis := defs["plugin_disable"].Description
+	if !strings.Contains(dis, "跨重启保留") && !strings.Contains(dis, "持久") {
+		t.Errorf("★ plugin_disable 描述未说明它是**持久**的\n%s", dis)
+	}
+	if !strings.Contains(dis, "plugin_stop") {
+		t.Errorf("★ plugin_disable 描述未指向 plugin_stop（临时关闭）作为对比\n%s", dis)
+	}
+
+	if st := defs["plugin_start"].Description; !strings.Contains(st, "持久") {
+		t.Errorf("★ plugin_start 描述未提持久禁用的处理\n%s", st)
+	}
+	if en := defs["plugin_enable"].Description; !strings.Contains(en, "清除") || !strings.Contains(en, "自启") {
+		t.Errorf("★ plugin_enable 描述未说明它会让之后开机自启\n%s", en)
+	}
+}
+
+// ★★★ 判据：**四个工具各自转调不同的 API**（不是别名）。
+//
+// 若 plugin_stop 内部转调 DisablePlugin（或反过来），两者行为相同
+// ⇒ 上述描述全是谎话。这里对每个工具的 handler 做"源码块内包含期望调用"检查。
+//
+// ★ 为何能接受源码检查（本仓曾因此吃亏）：这里检查的是**期望调用一定存在**，
+// 是单向的（存在性），不会被 `if false &&` 骗过 —— 那种写法仍需写出该调用。
+// 真正的行为验证在 internal/plugin 包的 runtime_state_test.go（真加载真启停）。
+func TestRuntimeToolsCallDistinctAPIs(t *testing.T) {
+	src := readPluginSource(t)
+	cases := []struct{ tool, want string }{
+		{"plugin_start", "mgr.StartPlugin("},
+		{"plugin_stop", "mgr.StopPlugin("},
+		{"plugin_enable", "mgr.EnablePlugin("},
+		{"plugin_disable", "mgr.DisablePlugin("},
+	}
+	for _, c := range cases {
+		idx := strings.Index(src, `s.RegisterTool("`+c.tool+`"`)
+		if idx < 0 {
+			t.Fatalf("未找到 %s 的注册", c.tool)
+		}
+		rest := src[idx:]
+		// 截到下一个 RegisterTool
+		if nxt := strings.Index(rest[len(c.tool)+20:], `s.RegisterTool(`); nxt >= 0 {
+			rest = rest[:len(c.tool)+20+nxt]
+		}
+		if !strings.Contains(rest, c.want) {
+			t.Errorf("★ %s 的 handler 未调用 %s —— 可能误指向另一个 API（行为与描述不符）",
+				c.tool, c.want)
+		}
+	}
+}
+
+// readPluginSource 读本包源码（判据的静态检查用）。
+func readPluginSource(t *testing.T) string {
+	t.Helper()
+	b, err := os.ReadFile("plugin.go")
+	if err != nil {
+		t.Fatalf("读 plugin.go: %v", err)
+	}
+	return string(b)
+}
diff --git a/internal/plugins/pluginmgr/package_limit_test.go b/internal/plugins/pluginmgr/package_limit_test.go
new file mode 100644
index 00000000..88c75dcd
--- /dev/null
+++ b/internal/plugins/pluginmgr/package_limit_test.go
@@ -0,0 +1,325 @@
+package pluginmgr
+
+// 插件包大小上限的判据。
+//
+// 核心命题（本次修复的实质）：
+//   ① 上限**可配置**（而非硬编码 100MB）—— 内嵌运行时的包能装进来
+//   ② 上限在**读入内存之前**生效 —— 否则限制等于没有
+//   ③ 0 = 不限制
+//
+// ★ ② 是这次真正的修复。原实现在 io.ReadAll 之后才判大小，
+// 一个声明超大 Content-Length 的请求会先把内存吃满再收到"包太大"。
+// 判据必须能咬住"位置"这个属性，而不只是"超限会被拒绝"。
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/events"
+	"github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// countingReader 记录**实际被读走了多少字节**。
+//
+// 这是判断"限流在读前生效"的关键工具：若实现先全量读再检查，
+// 计数会等于源总长；若在读中限流，计数只到 limit+1 就停。
+type countingReader struct {
+	r    io.Reader
+	read int64
+}
+
+func (c *countingReader) Read(p []byte) (int, error) {
+	n, err := c.r.Read(p)
+	c.read += int64(n)
+	return n, err
+}
+
+// ★★★ 判据：超限时**没有把整个 source 读进内存**。
+//
+// 这条咬的是"防线的位置"，是本次修复的核心性质。
+func TestPackageLimitStopsBeforeReadingEverything(t *testing.T) {
+	const limit = 1024
+	// 源远大于 limit（1MB）
+	source := bytes.Repeat([]byte("A"), 1<<20)
+	cr := &countingReader{r: bytes.NewReader(source)}
+
+	_, err := readLimited(cr, limit)
+	if err == nil {
+		t.Fatal("超限应报错")
+	}
+	// ★ 关键断言：读取量必须远小于源大小
+	// （允许多读 1 字节用于边界判定）
+	if cr.read > limit+1 {
+		t.Fatalf("★ 超限时读了 %d 字节（源 %d，上限 %d）—— 说明是先全量读再检查，防线位置错了",
+			cr.read, len(source), limit)
+	}
+}
+
+// ★★ 判据：恰好等于上限的包**不被误拒**（边界差一）。
+func TestPackageLimitBoundaryIsInclusive(t *testing.T) {
+	const limit = 512
+	exact := bytes.Repeat([]byte("A"), limit)
+	if _, err := readLimited(bytes.NewReader(exact), limit); err != nil {
+		t.Errorf("恰好等于上限应通过: %v", err)
+	}
+	over := bytes.Repeat([]byte("A"), limit+1)
+	if _, err := readLimited(bytes.NewReader(over), limit); err == nil {
+		t.Error("超过上限 1 字节应被拒")
+	}
+}
+
+// ★★ 判据：0 = 不限制（内嵌运行时可能要更大的包）。
+func TestPackageLimitZeroMeansUnlimited(t *testing.T) {
+	big := bytes.Repeat([]byte("A"), 4<<20) // 4MB
+	got, err := readLimited(bytes.NewReader(big), 0)
+	if err != nil {
+		t.Fatalf("0 应为不限制: %v", err)
+	}
+	if len(got) != len(big) {
+		t.Errorf("不限时长度应一致: %d vs %d", len(got), len(big))
+	}
+	// 负数同样视为不限（防御式：配置项误填负数不该变成"拒一切"）
+	if _, err := readLimited(bytes.NewReader(big), -1); err != nil {
+		t.Errorf("负数应视为不限制: %v", err)
+	}
+}
+
+// ★★ 判据：默认上限**足够容纳内嵌运行时并留出真实余量**。
+//
+// 实测数据（2026-10-15，commondev 内嵌 node+pi）：
+//   - 包大小 103,795,462 字节 = 99.0 MiB
+//   - 旧的硬编码上限 100<<20 = 104,857,600 字节
+//     ⇒ 余量仅 1,062,138 字节（1.01 MiB）
+//
+// ★ 这条判据的措辞经过修正。我最初写的是"内嵌运行时需要 >100MB，
+// 所以旧上限会挡住它"——那是**错的**：实测包 99.0 MiB 并未超过
+// 100 MiB。我自己写的对照项判据（TestRealEmbeddedRuntimeRejectedByOldLimit）
+// 把这一点咬了出来。
+//
+// 所以真实情况是：旧上限**没挡住当前这个包**，但它只剩 1.01 MiB 余量 ——
+// 任何新增一个资源文件就会爆。放宽到 512MB 的意义是把"随时会爆"
+// 变成"有合理空间"，而不是"从装不进变成装得进"。
+func TestDefaultLimitLeavesRealHeadroom(t *testing.T) {
+	const observedPackageBytes = 103795462 // 实测 commondev 包
+	limit := int64(defaultMaxPackageMB) << 20
+	if limit <= observedPackageBytes {
+		t.Fatalf("★ 默认上限 %dMB 装不下实测的内嵌运行时包（%.1f MiB）",
+			defaultMaxPackageMB, float64(observedPackageBytes)/(1<<20))
+	}
+	// 余量要求：至少 2 倍于实测包大小（否则"随时会爆"的问题没解决）
+	if limit < observedPackageBytes*2 {
+		t.Errorf("★ 余量不足：上限 %dMB 对实测 %.1f MiB 的包余量不够（应至少 2 倍）",
+			defaultMaxPackageMB, float64(observedPackageBytes)/(1<<20))
+	}
+}
+
+// ★★★ 判据：HTTP 上传超限返回 **413**，且错误信息给出可执行提示。
+//
+// 413 而非 400/500：这是语义正确的状态码，调用方能据此区分
+// "包太大"与"包损坏"。
+func TestHTTPUploadOverLimitReturns413(t *testing.T) {
+	p := &Plugin{maxPackageBytes: 1024} // 故意设小
+	body := bytes.Repeat([]byte("A"), 4096)
+	req := httptest.NewRequest(http.MethodPost, "/plugins", bytes.NewReader(body))
+	rec := httptest.NewRecorder()
+
+	// 直接调用 handler（真实入口，不是 helper）
+	req.Body = http.MaxBytesReader(rec, req.Body, 1<<30) // 不干扰本判据
+	p.handlePlugins(rec, req)
+
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Errorf("★ 超限应返回 413，实际 %d（body=%s）", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "max_package_mb") {
+		t.Errorf("错误信息应指出如何放宽（max_package_mb）: %s", rec.Body.String())
+	}
+}
+
+// ★★ 判据：本地文件路径也执行上限（先 Stat 快速拒绝）。
+func TestInstallFromPathEnforcesLimit(t *testing.T) {
+	dir := t.TempDir()
+	pth := filepath.Join(dir, "big.hmap")
+	if err := os.WriteFile(pth, bytes.Repeat([]byte("A"), 4096), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	p := &Plugin{maxPackageBytes: 1024}
+	_, err := p.installFromPath(pth, false)
+	if err == nil {
+		t.Fatal("本地文件超限应报错")
+	}
+	if !strings.Contains(err.Error(), "too large") {
+		t.Errorf("应为大小错误，实际: %v", err)
+	}
+}
+
+// ★★ 判据：放宽上限后，**真正约 100MB 的包能装进来** —— 本次的目的。
+//
+// 用"读入 + 校验"而非完整安装：完整安装要写盘，成本高且与本判据无关。
+// 这里钉住的是"读入阶段不再拦它"。
+func TestLargePackagePassesWhenLimitRaised(t *testing.T) {
+	const size = 101 << 20 // 101MB，旧上限下必被拒
+	// 用惰性 reader 避免真的分配 101MB
+	lr := io.LimitReader(zeroReader{}, size)
+	p := &Plugin{maxPackageBytes: int64(defaultMaxPackageMB) << 20}
+
+	data, err := readLimited(lr, p.maxPackageBytes)
+	if err != nil {
+		t.Fatalf("★ 放宽后 101MB 包仍被拒: %v", err)
+	}
+	if int64(len(data)) != size {
+		t.Fatalf("大小不对: %d", len(data))
+	}
+	// 对照：旧的 100MB 硬编码上限会拒它
+	if _, err := readLimited(io.LimitReader(zeroReader{}, size), 100<<20); err == nil {
+		t.Error("对照项：100MB 上限应拒绝 101MB 包")
+	}
+}
+
+// zeroReader 无限供应零字节（惰性，不占内存）。
+type zeroReader struct{}
+
+func (zeroReader) Read(p []byte) (int, error) {
+	for i := range p {
+		p[i] = 0
+	}
+	return len(p), nil
+}
+
+// ★ 判据：错误类型可判定（供上层区分"太大"与其他失败）。
+func TestTooLargeErrorIsIdentifiable(t *testing.T) {
+	err := errPackageTooLarge(42 << 20)
+	if err == nil {
+		t.Fatal("应返回错误")
+	}
+	if !strings.Contains(err.Error(), "42MB") {
+		t.Errorf("错误应包含上限值: %v", err)
+	}
+	// 不应是 io.EOF 之类的伪装
+	if errors.Is(err, io.EOF) {
+		t.Error("不应是 io.EOF")
+	}
+}
+
+// ★★★ 判据：配置值按**真实形态**（string）被解析。
+//
+// 这是本仓反复出现的坑：配置从 DB 读出来是字符串
+// （config.PluginSettings.Get → openFromStorage 返回 string）。
+// 初版照抄 agentcli 的 `v.(float64)` 假设，switch 全不匹配 ⇒
+// **配置被静默忽略** —— 用户改了上限却不生效，且无任何提示。
+//
+// 判据的形态很重要：**必须喂 string**。如果这里喂 int，
+// 判据会绿，而生产仍然不生效。
+func TestLimitConfigParsedFromString(t *testing.T) {
+	cases := []struct {
+		in   interface{}
+		want int64 // MB
+		desc string
+	}{
+		{"64", 64, "字符串（真实形态）"},
+		{"0", 0, "0 = 不限制"},
+		{" 128 ", 128, "带空白的字符串"},
+		{"-5", 0, "负数视为不限制（不是拒一切）"},
+		{int(256), 256, "int（兼容）"},
+		{int64(300), 300, "int64（兼容）"},
+		{float64(32), 32, "float64（兼容）"},
+	}
+	for _, c := range cases {
+		got := parseLimitMB(c.in)
+		if got != c.want<<20 {
+			t.Errorf("parseLimitMB(%#v) [%s] = %d 字节，期望 %dMB", c.in, c.desc, got, c.want)
+		}
+	}
+	// 非法输入回退默认（不静默变成 0=不限，那会悄悄关掉防护）
+	if got := parseLimitMB("abc"); got != int64(defaultMaxPackageMB)<<20 {
+		t.Errorf("非法输入应回退默认，实际 %d", got)
+	}
+	if got := parseLimitMB(""); got != int64(defaultMaxPackageMB)<<20 {
+		t.Errorf("空串应回退默认，实际 %d", got)
+	}
+	if got := parseLimitMB(struct{}{}); got != int64(defaultMaxPackageMB)<<20 {
+		t.Errorf("意外类型应回退默认，实际 %d", got)
+	}
+}
+
+// limitSettings 是能返回**真实形态**（string）配置值的 settings mock。
+//
+// 用真实 SettingsAPI 接口，走 p.Start() 这条生产路径，
+// 从而验证"配置值 → p.maxPackageBytes"的完整链路。
+type limitSettings struct {
+	pmSettings
+	maxMB string
+	dir   string
+}
+
+func (s *limitSettings) Get(key string) (interface{}, error) {
+	if key == "max_package_mb" {
+		// ★ 返回 string：这是 config.PluginSettings.Get 的真实形态
+		// （openFromStorage 返回 string）。返回 int 会让判据失去意义。
+		return s.maxMB, nil
+	}
+	return nil, nil
+}
+func (s *limitSettings) GetCore(key string) (interface{}, error) {
+	if key == "plugin.dir" {
+		return s.dir, nil
+	}
+	return nil, nil
+}
+func (s *limitSettings) RegisterDef(sdk.ConfigDef) {}
+
+// ★★★ 判据：配置项经 **真实 Start()** 生效。
+//
+// 这条覆盖的是我初版真正出错的环节：Get 返回 string，
+// 而代码按 float64 断言 ⇒ switch 全不匹配 ⇒ 配置被静默忽略。
+// 上面的 parseLimitMB 单测也喂 string，但只有走 Start() 才能证明
+// "装配路径确实把 string 交给了它"。
+func TestLimitConfigAppliedThroughStart(t *testing.T) {
+	dir := t.TempDir()
+	for _, tc := range []struct {
+		cfg  string
+		want int64
+	}{
+		{"64", 64 << 20},
+		{"0", 0},
+		{"-1", 0},
+	} {
+		s := &limitSettings{maxMB: tc.cfg, dir: dir}
+		sdkInst := sdk.New("pluginmgr", sdk.SDKConfig{
+			Settings: s,
+			EventBus: events.NewBus(),
+		})
+		p := &Plugin{name: "pluginmgr", mux: http.NewServeMux(), httpAddr: ""}
+		if err := p.Start(sdkInst); err != nil {
+			// HTTP 关闭（httpAddr 空）时 Start 仍应成功
+			t.Fatalf("Start 失败: %v", err)
+		}
+		if p.maxPackageBytes != tc.want {
+			t.Errorf("★ max_package_mb=%q 未生效: got %d, want %d（配置被静默忽略）",
+				tc.cfg, p.maxPackageBytes, tc.want)
+		}
+	}
+}
+
+// ★★ 判据：**未配置时用默认值**（不能变成 0=不限而悄悄关掉防护）。
+func TestLimitDefaultsWhenNotConfigured(t *testing.T) {
+	s := &limitSettings{maxMB: "", dir: t.TempDir()}
+	sdkInst := sdk.New("pluginmgr", sdk.SDKConfig{
+		Settings: s,
+		EventBus: events.NewBus(),
+	})
+	p := &Plugin{name: "pluginmgr", mux: http.NewServeMux(), httpAddr: ""}
+	if err := p.Start(sdkInst); err != nil {
+		t.Fatal(err)
+	}
+	if p.maxPackageBytes != int64(defaultMaxPackageMB)<<20 {
+		t.Errorf("★ 未配置时应为默认 %dMB，实际 %d 字节（可能被误设为不限）",
+			defaultMaxPackageMB, p.maxPackageBytes)
+	}
+}
diff --git a/internal/plugins/pluginmgr/plugin.go b/internal/plugins/pluginmgr/plugin.go
index 1ef832ad..b3069a21 100644
--- a/internal/plugins/pluginmgr/plugin.go
+++ b/internal/plugins/pluginmgr/plugin.go
@@ -95,6 +95,12 @@ type Plugin struct {
 	httpAddr  string // 本实例的监听地址（默认 defaultHTTPAddr；来自 settings）
 	sdk       *sdk.PluginSDK
 	pluginDir string
+	// maxPackageBytes 是单个插件包 **压缩后** 的上限（0 = 不限）。
+	//
+	// 为什么是配置项而不是常量：内嵌运行时（node+pi 之类）就要 ~100MB，
+	// 硬编码一个数必然在某天成为纯粹的障碍。默认值给得很宽松（见
+	// defaultMaxPackageMB），有需要的部署可以调大或设为 0 关闭。
+	maxPackageBytes int64
 }
 
 func New(name string) *Plugin {
@@ -116,6 +122,18 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		Category: "pluginmgr",
 	})
 
+	s.Settings().RegisterDef(sdk.ConfigDef{
+		Key:         "max_package_mb",
+		Default:     defaultMaxPackageMB,
+		Type:        "int",
+		DisplayName: "插件包大小上限 (MB)",
+		Description: "单个插件包**压缩后**的字节上限；0 = 不限制。" +
+			"内嵌运行时（node/pi 等）的包实测约 99MB，旧上限 100MB 下余量仅 1MB —— " +
+			"需要更大就调高，或设 0 关闭限制。" +
+			"该值在**读入内存之前**生效，不是事后检查。",
+		Category: "pluginmgr",
+	})
+
 	// 只写本实例字段，**不写任何包级状态**（见 defaultHTTPAddr 注释）。
 	p.httpAddr = defaultHTTPAddr
 	if v, _ := s.Settings().Get("http_addr"); v != nil {
@@ -124,14 +142,44 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		}
 	}
 
-	if v, _ := s.Settings().GetCore("plugin.dir"); v != nil {
-		if dir, ok := v.(string); ok && dir != "" {
+	// ★ pluginDir 的正确来源是**内核**（PluginMgrAPI.PluginDir），
+	// 不是 core.plugin.dir 配置项。
+	//
+	// 实测教训（2026-10-15）：用 GetCore("plugin.dir") 读时，生产 config.db
+	// 里**根本没有这个键**（内核只是"播种"默认值，不一定落库），于是
+	// p.pluginDir 为空 —— 而所有以它为起点的功能（技能重扫、删除插件目录）
+	// 会**静默什么都不做**。安装却照常成功（那条路径用的是自己算的 dir），
+	// 所以症状是"局部静默失效"，极难发现。
+	//
+	// 先问内核，配置项只作兼容回退。
+	if mgr := p.pluginMgr(); mgr != nil {
+		if dir := strings.TrimSpace(mgr.PluginDir()); dir != "" {
 			p.pluginDir = dir
 		}
 	}
+	if p.pluginDir == "" {
+		if v, _ := s.Settings().GetCore("plugin.dir"); v != nil {
+			if dir, ok := v.(string); ok && dir != "" {
+				p.pluginDir = dir
+			}
+		}
+	}
+
+	// 上限也走"先给默认值再覆盖"，与本文件其他配置项一致
+	// （避免 settings 尚未就绪时拿到 0 而变成"无限制"）。
+	p.maxPackageBytes = int64(defaultMaxPackageMB) << 20
+	if v, _ := s.Settings().Get("max_package_mb"); v != nil {
+		p.maxPackageBytes = parseLimitMB(v)
+	}
 
 	p.registerTools(s)
 
+	// ★ 启动重扫随包 skill：移交只在**安装那一刻**发生，而 skill 落在
+	// 插件目录里（不在 skillmgr 的 skillsDir）⇒ worker 重启后它会**静默消失**。
+	// 延迟几秒是为了等 skillmgr 的订阅就绪（两者 Start 顺序不确定）；
+	// skillmgr 的 loadOne 幂等，重复到达无副作用。见 skill_handout.go。
+	p.scheduleStartupSkillRescan()
+
 	if p.httpAddr != "" {
 		p.startHTTPServer()
 	}
@@ -245,6 +293,160 @@ func (p *Plugin) registerTools(s *sdk.PluginSDK) {
 		return p.restartPlugin(name)
 	})
 
+	// ---- 持久启用/禁用（设计 §2.6.7.4）----
+	//
+	// 与 plugin_start/stop 的分工：
+	//   enable/disable ⇒ **持久**（写 disabled_plugins，跨重启保留）= 系统里"禁止运行"
+	//   start/stop     ⇒ **运行态**（不写配置）                = 现在关掉这个窗口
+	s.RegisterTool("plugin_disable", sdk.ToolDef{
+		Name: "plugin_disable",
+		Description: "**持久**禁用插件：停止它并写入禁用配置，**跨重启保留**（开机也不再自启）。" +
+			"如果只是想临时关掉它、不希望影响开机自启，请用 plugin_stop。",
+		Parameters: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"name": map[string]interface{}{
+					"type":        "string",
+					"description": "插件名称",
+				},
+			},
+			"required": []string{"name"},
+		},
+		Serial: true,
+	}, func(args map[string]interface{}) (interface{}, error) {
+		name, _ := args["name"].(string)
+		if name == "" {
+			return map[string]interface{}{"error": "name is required"}, nil
+		}
+		mgr := p.pluginMgr()
+		if mgr == nil {
+			return nil, fmt.Errorf("内核插件管理面不可用")
+		}
+		if err := mgr.DisablePlugin(name, "agent"); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{
+			"status":     "disabled",
+			"name":       name,
+			"persistent": "已写入禁用配置（跨重启保留）",
+		}, nil
+	})
+
+	s.RegisterTool("plugin_enable", sdk.ToolDef{
+		Name: "plugin_enable",
+		Description: "**持久**启用插件：解除禁用配置并立即加载它（跨重启保留）。" +
+			"注意：它同时**清除禁用标记**，所以之后开机会自启；" +
+			"若只是想把 plugin_stop 关掉的插件开回来，用 plugin_start 更精确。",
+		Parameters: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"name": map[string]interface{}{
+					"type":        "string",
+					"description": "插件名称",
+				},
+			},
+			"required": []string{"name"},
+		},
+		Serial: true,
+	}, func(args map[string]interface{}) (interface{}, error) {
+		name, _ := args["name"].(string)
+		if name == "" {
+			return map[string]interface{}{"error": "name is required"}, nil
+		}
+		mgr := p.pluginMgr()
+		if mgr == nil {
+			return nil, fmt.Errorf("内核插件管理面不可用")
+		}
+		if err := mgr.EnablePlugin(name); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{
+			"status":     "enabled",
+			"name":       name,
+			"persistent": "禁用标记已清除（之后开机会自启）",
+		}, nil
+	})
+
+	// ---- 运行态启停（设计 §2.6.7.4）----
+	//
+	// ★ 与 plugin_enable/plugin_disable 的分工（用户明确指出"只有 reload"的缺口）：
+	//
+	//	plugin_enable/disable ⇒ **持久**：写 disabled_plugins，跨重启保留
+	//	plugin_start/stop     ⇒ **运行态**：现在启停，不写任何配置
+	//
+	// 缺了这两个的直接后果：agent 想"临时关掉某插件看现象"只能调
+	// plugin_disable ⇒ 顺带把开机自启也关了 ⇒ 用户下次开机发现"怎么不启动了"。
+	s.RegisterTool("plugin_start", sdk.ToolDef{
+		Name: "plugin_start",
+		Description: "**运行态**启动一个插件：现在拉起它，**不改持久状态**（重启后仍按" +
+			"开机自启/禁用配置决定）。用于把 plugin_stop 关掉的插件开回来。" +
+			"注意：被**持久禁用**的插件会被拒绝，那种情况请用 plugin_enable。",
+		Parameters: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"name": map[string]interface{}{
+					"type":        "string",
+					"description": "插件名称",
+				},
+			},
+			"required": []string{"name"},
+		},
+		Serial: true,
+	}, func(args map[string]interface{}) (interface{}, error) {
+		name, _ := args["name"].(string)
+		if name == "" {
+			return map[string]interface{}{"error": "name is required"}, nil
+		}
+		mgr := p.pluginMgr()
+		if mgr == nil {
+			return nil, fmt.Errorf("内核插件管理面不可用")
+		}
+		if err := mgr.StartPlugin(name); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{
+			"status": "started",
+			"name":   name,
+			// ★ 明确告知这是运行态操作，避免 agent 误以为改了持久设置
+			"persistent": "未改动（重启后按开机自启/禁用配置决定）",
+		}, nil
+	})
+
+	s.RegisterTool("plugin_stop", sdk.ToolDef{
+		Name: "plugin_stop",
+		Description: "**运行态**关闭一个插件：现在停掉它，**不改持久状态**" +
+			"（不会影响开机自启，重启后该插件正常加载）。用于临时腾出资源或隔离问题。" +
+			"与 plugin_disable 不同 —— 后者会**持久**禁用（跨重启保留）。",
+		Parameters: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"name": map[string]interface{}{
+					"type":        "string",
+					"description": "插件名称",
+				},
+			},
+			"required": []string{"name"},
+		},
+		Serial: true,
+	}, func(args map[string]interface{}) (interface{}, error) {
+		name, _ := args["name"].(string)
+		if name == "" {
+			return map[string]interface{}{"error": "name is required"}, nil
+		}
+		mgr := p.pluginMgr()
+		if mgr == nil {
+			return nil, fmt.Errorf("内核插件管理面不可用")
+		}
+		if err := mgr.StopPlugin(name); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{
+			"status":     "stopped",
+			"name":       name,
+			"persistent": "未改动（开机自启设置不变，重启后会重新加载）",
+		}, nil
+	})
+
 	s.RegisterTool("plugin_remove", sdk.ToolDef{
 		Name:        "plugin_remove",
 		Description: "卸载一个已安装的外部插件",
@@ -370,9 +572,9 @@ func (p *Plugin) handlePlugins(w http.ResponseWriter, r *http.Request) {
 				return
 			}
 		} else {
-			data, err := io.ReadAll(r.Body)
+			data, err := readLimited(r.Body, p.maxPackageBytes)
 			if err != nil {
-				http.Error(w, "read body: "+err.Error(), http.StatusBadRequest)
+				http.Error(w, err.Error(), http.StatusRequestEntityTooLarge)
 				return
 			}
 			result, err := p.installFromData(data, false)
@@ -430,10 +632,22 @@ func (p *Plugin) handlePluginByID(w http.ResponseWriter, r *http.Request) {
 // ======== Core Logic ========
 
 func (p *Plugin) installFromPath(path string, overwrite bool) (interface{}, error) {
-	data, err := os.ReadFile(path)
+	// 本地文件同样走限流读：先 Stat 拿大小快速拒绝（避免白读一遍），
+	// 再用 readLimited 兜住"Stat 与读取之间文件变大"的竞态。
+	if p.maxPackageBytes > 0 {
+		if st, err := os.Stat(path); err == nil && st.Size() > p.maxPackageBytes {
+			return nil, errPackageTooLarge(p.maxPackageBytes)
+		}
+	}
+	f, err := os.Open(path)
 	if err != nil {
 		return nil, fmt.Errorf("read file: %w", err)
 	}
+	defer f.Close()
+	data, err := readLimited(f, p.maxPackageBytes)
+	if err != nil {
+		return nil, err
+	}
 	return p.installFromData(data, overwrite)
 }
 
@@ -458,9 +672,14 @@ func (p *Plugin) installFromURL(rawURL string, overwrite bool) (interface{}, err
 		return nil, fmt.Errorf("download returned %s", resp.Status)
 	}
 
-	data, err := io.ReadAll(resp.Body)
+	// 先用 Content-Length 快速拒绝（覆盖绝大多数情况），再用 readLimited
+	// 兜住分块传输（Content-Length 缺失或撒谎）。
+	if p.maxPackageBytes > 0 && resp.ContentLength > p.maxPackageBytes {
+		return nil, errPackageTooLarge(p.maxPackageBytes)
+	}
+	data, err := readLimited(resp.Body, p.maxPackageBytes)
 	if err != nil {
-		return nil, fmt.Errorf("read response: %w", err)
+		return nil, err
 	}
 
 	result, err := p.installFromData(data, overwrite)
@@ -548,6 +767,10 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro
 		}
 		os.RemoveAll(backup)
 
+		// ★ 随包 skill 移交（升级路径）：解压完成后才扫，否则目录还不完整。
+		// 失败不阻断 —— skill 登记是附带收益，插件本身已装好。
+		skillN, skillFailed := p.handOutPluginSkills(target, pkg.Name)
+
 		checksum := fmt.Sprintf("%x", sha256.Sum256(data))
 		action := "upgraded"
 		if cmpVersion(pkg.Version, oldVersion) < 0 {
@@ -556,15 +779,17 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro
 			action = "reinstalled"
 		}
 		return map[string]interface{}{
-			"status":           "installed",
-			"name":             pkg.Name,
-			"version":          pkg.Version,
-			"previous_version": oldVersion,
-			"entry":            pkg.Entry,
-			"checksum":         checksum,
-			"action":           action,
-			"reload_required":  true,
-			"config_kept":      true,
+			"status":            "installed",
+			"name":              pkg.Name,
+			"version":           pkg.Version,
+			"previous_version":  oldVersion,
+			"entry":             pkg.Entry,
+			"checksum":          checksum,
+			"action":            action,
+			"reload_required":   true,
+			"config_kept":       true,
+			"skills_registered": skillN,
+			"skills_failed":     skillFailed,
 		}, nil
 	}
 
@@ -577,13 +802,18 @@ func (p *Plugin) installFromData(data []byte, overwrite bool) (interface{}, erro
 
 	checksum := fmt.Sprintf("%x", sha256.Sum256(data))
 
+	// ★ 随包 skill 移交（全新安装路径）。
+	skillN, skillFailed := p.handOutPluginSkills(target, pkg.Name)
+
 	return map[string]interface{}{
-		"status":   "installed",
-		"name":     pkg.Name,
-		"version":  pkg.Version,
-		"entry":    pkg.Entry,
-		"checksum": checksum,
-		"action":   "reload_required",
+		"status":            "installed",
+		"name":              pkg.Name,
+		"version":           pkg.Version,
+		"entry":             pkg.Entry,
+		"checksum":          checksum,
+		"action":            "reload_required",
+		"skills_registered": skillN,
+		"skills_failed":     skillFailed,
 	}, nil
 }
 
@@ -835,23 +1065,123 @@ type pluginPackage struct {
 	Platforms []string `json:"platforms,omitempty"`
 }
 
-func validatePackage(data []byte) (*pluginPackage, error) {
-	if len(data) > 100<<20 {
-		return nil, fmt.Errorf("package too large (>100MB)")
-	}
+const (
+	// defaultMaxPackageMB 是插件包默认上限（MB）。
+	//
+	// 为什么给这么大：内嵌运行时的插件包本身就接近 100MB
+	// （node 二进制约 50MB + pi 依赖闭包约 50MB，压缩后）。
+	// 这个值只作为"防止手滑传错文件"的兜底，真正的 DoS 防护
+	// 由 readLimited 在**读取前**按 Content-Length / LimitReader 完成。
+	//
+	// 需要更大（或不需要限制）时改插件设置 max_package_mb（0 = 不限）。
+	defaultMaxPackageMB = 512
+)
 
+// errPackageTooLarge 是统一的超限错误（三种入口共用）。
+func errPackageTooLarge(limit int64) error {
+	return fmt.Errorf("package too large (>%dMB)；如确需更大，请调整插件设置 max_package_mb（0 = 不限）", limit>>20)
+}
+
+// parseLimitMB 把配置值解析成字节上限（0 = 不限）。
+//
+// ★ 必须处理 string：插件配置从 DB 读出来是**字符串**
+// （config.PluginSettings.Get → openFromStorage 返回 string），
+// 不是 int/float64。初版照抄了 agentcli 的 `v.(float64)` 假设，
+// 于是 switch 一个分支都不匹配 ⇒ **配置被静默忽略**，
+// 用户改了 max_package_mb 却不生效，且没有任何提示。
+//
+// 兼容其它形态是为了稳健（不同装配路径可能给出不同静态类型），
+// 但 string 是真实路径，必须有判据钉住。
+func parseLimitMB(v interface{}) int64 {
+	var mb int64
+	switch n := v.(type) {
+	case string:
+		s := strings.TrimSpace(n)
+		if s == "" {
+			return int64(defaultMaxPackageMB) << 20
+		}
+		parsed, err := strconv.ParseInt(s, 10, 64)
+		if err != nil {
+			log.Printf("[pluginmgr] max_package_mb=%q 不是整数，回退默认 %dMB", s, defaultMaxPackageMB)
+			return int64(defaultMaxPackageMB) << 20
+		}
+		mb = parsed
+	case int:
+		mb = int64(n)
+	case int64:
+		mb = n
+	case float64:
+		mb = int64(n)
+	default:
+		log.Printf("[pluginmgr] max_package_mb 类型意外（%T），回退默认 %dMB", v, defaultMaxPackageMB)
+		return int64(defaultMaxPackageMB) << 20
+	}
+	if mb < 0 {
+		// 负数视为"不限"（与 0 同义），而不是"拒一切" ——
+		// 配置误填负号不该让插件系统完全不可用。
+		mb = 0
+	}
+	return mb << 20
+}
+
+// readLimited 读入 reader 并在 **读取过程中** 施加上限。
+//
+// ★ 为什么必须在这里做，而不是读完再检查：
+//
+// 原实现在 io.ReadAll 之后才 `len(data) > 100<<20`。那时内存**已经占用**，
+// 一个声明 `Content-Length: 10GB` 的请求可以先把进程撑爆再收到"包太大"的报错 ——
+// 限制形同虚设。读前限流才是有意义的防护（也是本次把上限变成配置项的前提：
+// 放宽一个无效检查不会带来新风险，放寛一个有效检查才会）。
+//
+// limit <= 0 表示不限制。
+func readLimited(r io.Reader, limit int64) ([]byte, error) {
+	if limit <= 0 {
+		return io.ReadAll(r)
+	}
+	// 多读 1 字节：能读到 limit+1 才说明确实超了，
+	// 否则恰好等于 limit 的包会被误判（边界差一）。
+	lr := io.LimitReader(r, limit+1)
+	data, err := io.ReadAll(lr)
+	if err != nil {
+		return nil, err
+	}
+	if int64(len(data)) > limit {
+		return nil, errPackageTooLarge(limit)
+	}
+	return data, nil
+}
+
+// validatePackage 只做**结构合法性**校验（元数据、平台二进制、路径安全）。
+//
+// 大小不在这里判：它必须在读入内存之前决定，见 readLimited。
+// （曾经这里有一个 `len(data) > 100<<20` 的检查，属于"事后检查"，
+// 挡不住任何东西却会在有一天需要大包时成为障碍 —— 已移除。）
+func validatePackage(data []byte) (*pluginPackage, error) {
 	reader, err := zip.NewReader(bytes.NewReader(data), int64(len(data)))
 	if err != nil {
 		return nil, fmt.Errorf("invalid zip: %w", err)
 	}
 
+	// ★ 路径检查必须遍历**全部**条目，与找 manifest 分开。
+	//
+	// 原实现把路径检查放在寻找 plugin.json 的循环里，而该循环找到
+	// manifest 后会 `break` —— 于是排在 plugin.json **之后**的条目
+	// 完全没被检查。hmapdev 打包出的 rawfile 条目恒在 plugin.json 之后，
+	// 正好落在检查盲区（实测发现）。
+	//
+	// 落盘侧（extractPackage）另有独立的 path traversal 检查，
+	// 所以这不是可利用漏洞；但"校验函数只校验了一部分还叫校验"本身就是缺陷，
+	// 且一旦将来有人复用 validatePackage 做准入判断就会出事。
+	for _, f := range reader.File {
+		if strings.Contains(f.Name, "..") || strings.HasPrefix(f.Name, "/") {
+			return nil, fmt.Errorf("invalid path: %s", f.Name)
+		}
+	}
+
 	var pkg pluginPackage
 	hasManifest := false
 
 	for _, f := range reader.File {
-		if strings.Contains(f.Name, "..") || strings.HasPrefix(f.Name, "/") {
-			return nil, fmt.Errorf("invalid path: %s", f.Name)
-		}
 		if f.FileInfo().IsDir() {
 			continue
 		}
diff --git a/internal/plugins/pluginmgr/rawfile_install_test.go b/internal/plugins/pluginmgr/rawfile_install_test.go
new file mode 100644
index 00000000..fcd1ad3e
--- /dev/null
+++ b/internal/plugins/pluginmgr/rawfile_install_test.go
@@ -0,0 +1,157 @@
+package pluginmgr
+
+// rawfile 与安装链路的端到端判据。
+//
+// 目标：**用内核自己的 extractPackage**（不是测试里另写一份解包）
+// 处理一个真实带 rawfile 的 .hmap，验证资源落在 <插件目录>/rawfile/ 下
+// 且保持结构 —— 这正是插件运行期 RawFilesAPI 会去读的位置。
+
+import (
+	"archive/zip"
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// buildHmapWithRaw 造一个最小可安装包（含 plugin.json + 假二进制 + rawfile 条目）。
+func buildHmapWithRaw(t *testing.T, rawEntries map[string]string) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	w := zip.NewWriter(&buf)
+	add := func(name, content string) {
+		hdr := &zip.FileHeader{Name: name, Method: zip.Deflate}
+		fw, err := w.CreateHeader(hdr)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err := fw.Write([]byte(content)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	add("plugin.json", `{"name":"rawtest","version":"1.0.0","entry":"plugin.bin","platforms":["linux/amd64"]}`)
+	add("plugin.bin.linux.amd64", "#!/bin/sh\necho fake\n")
+	for name, content := range rawEntries {
+		add(name, content)
+	}
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+	return buf.Bytes()
+}
+
+// ★★ 判据：安装后资源落在 <插件目录>/rawfile/，**保持嵌套结构**。
+func TestInstallPreservesRawFileStructure(t *testing.T) {
+	data := buildHmapWithRaw(t, map[string]string{
+		"rawfile/node/bin/node":              "fake-node",
+		"rawfile/pi/node_modules/x/index.js": "module.exports=1",
+		"rawfile/main/prompt.txt":            "you are a dev",
+	})
+	dir := t.TempDir()
+	if err := extractPackage(data, dir); err != nil {
+		t.Fatalf("extractPackage 失败: %v", err)
+	}
+	base := filepath.Join(dir, "rawtest")
+	for _, rel := range []string{
+		"rawfile/node/bin/node",
+		"rawfile/pi/node_modules/x/index.js",
+		"rawfile/main/prompt.txt",
+	} {
+		p := filepath.Join(base, rel)
+		if _, err := os.Stat(p); err != nil {
+			// 若被拍平，文件会在 rawfile/ 下以 basename 出现 —— 报清楚
+			t.Errorf("★ 安装后资源不在预期路径 %s: %v", rel, err)
+		}
+	}
+	// 明确检查"没有拍平"
+	if _, err := os.Stat(filepath.Join(base, "rawfile", "node")); err != nil {
+		t.Errorf("★ 目录结构被拍平（rawfile/node 不存在）: %v", err)
+	}
+	// 内容正确
+	b, err := os.ReadFile(filepath.Join(base, "rawfile/main/prompt.txt"))
+	if err != nil || string(b) != "you are a dev" {
+		t.Errorf("内容不对: %q err=%v", b, err)
+	}
+}
+
+// ★★ 判据：可执行位在安装后保留（内嵌 node/pi 必须能被执行）。
+func TestInstallPreservesExecutableBit(t *testing.T) {
+	var buf bytes.Buffer
+	w := zip.NewWriter(&buf)
+	add := func(name, content string, mode os.FileMode) {
+		hdr := &zip.FileHeader{Name: name, Method: zip.Deflate}
+		hdr.SetMode(mode)
+		fw, _ := w.CreateHeader(hdr)
+		fw.Write([]byte(content))
+	}
+	add("plugin.json", `{"name":"rawtest2","version":"1.0.0","entry":"plugin.bin","platforms":["linux/amd64"]}`, 0o644)
+	add("plugin.bin.linux.amd64", "#!/bin/sh\n", 0o755)
+	add("rawfile/node/bin/node", "#!/bin/sh\necho ok\n", 0o755)
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+	dir := t.TempDir()
+	if err := extractPackage(buf.Bytes(), dir); err != nil {
+		t.Fatal(err)
+	}
+	st, err := os.Stat(filepath.Join(dir, "rawtest2", "rawfile/node/bin/node"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if st.Mode()&0o111 == 0 {
+		t.Errorf("★ 可执行位丢失: %v（内嵌 node 将无法执行）", st.Mode())
+	}
+}
+
+// ★ 判据：rawfile 条目不能绕过 validatePackage 的路径安全检查。
+func TestRawFileEntriesCannotEscapePackage(t *testing.T) {
+	// 恶意包：条目名带 ..（zip-slip）
+	var buf bytes.Buffer
+	w := zip.NewWriter(&buf)
+	add := func(name, content string) {
+		hdr := &zip.FileHeader{Name: name, Method: zip.Deflate}
+		fw, _ := w.CreateHeader(hdr)
+		fw.Write([]byte(content))
+	}
+	add("plugin.json", `{"name":"evil","version":"1.0.0","entry":"plugin.bin","platforms":["linux/amd64"]}`)
+	add("plugin.bin.linux.amd64", "#!/bin/sh\n")
+	add("rawfile/../../../etc/evil.sh", "pwned")
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+	// ★★ 结论（实测澄清）：**真正挡住它的是 extractPackage，不是 validatePackage**。
+	//
+	// validatePackage 的条目循环在读到 plugin.json 后 **break**，
+	// 于是排在 plugin.json **之后**的条目根本没做路径检查 ——
+	// 而 hmapdev 打包出的 rawfile 条目恒在 plugin.json 之后。
+	//
+	// 但解包有两个独立入口：
+	//   ① validatePackage  —— 元数据/平台校验（有早退，路径检查不完整）
+	//   ② extractPackage   —— 真正落盘（遍历**全部**条目，有 path traversal 检查）
+	// 所以不存在可被利用的漏洞；这里钉住的是 **② 必须始终挡住**。
+	//
+	// ★ 教训：判据不能只断言 err != nil。初版这样写"通过"了，
+	// 但理由其实是 "no valid binary found"（我造的包缺二进制）——
+	// 也就是说判据在**没有路径保护时照样通过**，完全没验证目标性质。
+	data := buf.Bytes()
+	// ① 准入校验必须**以路径理由**拒绝（修掉早退盲区后为真）
+	if _, err := validatePackage(data); err == nil {
+		t.Fatal("含 ../ 的包应被拒")
+	} else if !strings.Contains(err.Error(), "invalid path") {
+		t.Errorf("★ validatePackage 未以路径理由拒绝（实际: %v）—— 路径检查被 manifest 早退跳过了", err)
+	}
+	// 真正要钉的是解包路径
+	dir := t.TempDir()
+	err := extractPackage(data, dir)
+	if err == nil {
+		t.Fatal("★ extractPackage 未挡住路径穿越条目")
+	}
+	if !strings.Contains(err.Error(), "traversal") {
+		t.Fatalf("★ 拒绝理由不是路径穿越（实际: %v）—— 该用例没走到安全检查", err)
+	}
+	// 确认没有文件落到插件目录之外
+	if _, serr := os.Stat(filepath.Join(dir, "evil.sh")); serr == nil {
+		t.Error("★ 恶意文件落到了插件目录下")
+	}
+}
diff --git a/internal/plugins/pluginmgr/rawfile_realinstall_test.go b/internal/plugins/pluginmgr/rawfile_realinstall_test.go
new file mode 100644
index 00000000..48bc691b
--- /dev/null
+++ b/internal/plugins/pluginmgr/rawfile_realinstall_test.go
@@ -0,0 +1,101 @@
+package pluginmgr
+
+// ★★★ 真实大包安装的端到端判据。
+//
+// 用**内核自己的 installFromData** 装一个真实约 99MB 的 .hmap
+// （commondev 内嵌 node+pi 的产物）。这条判据回答的是用户的问题：
+// "解除限制后，内嵌运行时真能装进来吗？"
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestRealEmbeddedRuntimePackageInstalls(t *testing.T) {
+	src := os.Getenv("HA_RAWFILE_E2E_HMAP")
+	if src == "" {
+		t.Skip("设 HA_RAWFILE_E2E_HMAP=<hmap路径> 以运行")
+	}
+	data, err := os.ReadFile(src)
+	if err != nil {
+		t.Fatalf("读包失败: %v", err)
+	}
+	t.Logf("真实包大小: %.1f MiB", float64(len(data))/(1<<20))
+
+	// ★ 旧上限下这个包会被拒（对照）
+	if int64(len(data)) > 100<<20 {
+		t.Logf("注意：该包超过旧的 100MB 硬编码上限")
+	}
+
+	// ★ pluginDir 必须显式给定，否则 installFromData 直接返回
+	// {"error":"plugin dir not configured"} 且 err == nil ——
+	// 初版没设它，于是判据"通过"了但什么都没装。这是本仓反复出现的
+	// "假通过"模式：**必须断言返回值的内容，不能只看 err**。
+	dir := t.TempDir()
+	p := &Plugin{
+		pluginDir:       dir,
+		maxPackageBytes: int64(defaultMaxPackageMB) << 20,
+	}
+	res, err := p.installFromData(data, false)
+	if err != nil {
+		t.Fatalf("安装失败: %v", err)
+	}
+	if m, ok := res.(map[string]interface{}); ok {
+		if e, bad := m["error"]; bad {
+			t.Fatalf("★ 放宽上限后真实包仍装不进来: %v (details=%v)", e, m["details"])
+		}
+	} else {
+		t.Fatalf("返回值类型意外: %T", res)
+	}
+
+	// 装完必须能看到内嵌运行时资源（这才证明"包真的解开了"）
+	installed := filepath.Join(dir, "commondev")
+	if _, err := os.Stat(installed); err != nil {
+		t.Fatalf("★ 插件目录不存在，包没被解开: %v", err)
+	}
+	node := filepath.Join(installed, "rawfile", "node", "bin", "node")
+	st, err := os.Stat(node)
+	if err != nil {
+		t.Fatalf("★ 内嵌 node 不在预期路径: %v", err)
+	}
+	if st.Mode()&0o111 == 0 {
+		t.Errorf("★ 内嵌 node 丢了可执行位: %v", st.Mode())
+	}
+	t.Logf("解包成功：内嵌 node %d 字节，可执行位 OK", st.Size())
+}
+
+// ★★★ 判据（对照）：钉住"真实包与旧上限的关系"这个**事实**。
+//
+// 这条判据的来历值得留着：我原本写的是"该包在旧 100MB 上限下会被拒"，
+// 想用它证明上面的安装判据有意义。**它报红了** —— 实测包 103,795,462 字节
+// < 旧上限 104,857,600 字节，差 1.01 MiB，根本没超。
+//
+// 也就是说：旧上限**从来不是**当前这个包的障碍，真正的风险是
+// "余量只剩 1 MiB，加任何一个文件就爆"。搞错这一点会得出错误的
+// "解除了一个阻塞"的结论。判据在这里的作用就是不让错的叙事留下来。
+func TestRealPackageHeadroomAgainstOldLimit(t *testing.T) {
+	src := os.Getenv("HA_RAWFILE_E2E_HMAP")
+	if src == "" {
+		t.Skip("设 HA_RAWFILE_E2E_HMAP=<hmap路径> 以运行")
+	}
+	st, err := os.Stat(src)
+	if err != nil {
+		t.Fatal(err)
+	}
+	const oldLimit = 100 << 20
+	headroom := oldLimit - st.Size()
+	t.Logf("真实包 %.1f MiB，旧上限 %.1f MiB，余量 %.2f MiB",
+		float64(st.Size())/(1<<20), float64(oldLimit)/(1<<20), float64(headroom)/(1<<20))
+
+	// 事实断言：余量小于 5MiB 就算"贴近上限"，属于真实风险
+	if headroom < 5<<20 {
+		t.Logf("★ 确认：旧上限下余量仅 %.2f MiB —— 虽未超限，但任何新增资源都会爆。",
+			float64(headroom)/(1<<20))
+	}
+	// 新上限必须给出实质空间
+	newLimit := int64(defaultMaxPackageMB) << 20
+	if newLimit-st.Size() < st.Size() {
+		t.Errorf("★ 新上限 %dMB 未给出足够余量", defaultMaxPackageMB)
+	}
+}
diff --git a/internal/plugins/pluginmgr/skill_handout.go b/internal/plugins/pluginmgr/skill_handout.go
new file mode 100644
index 00000000..55b433e0
--- /dev/null
+++ b/internal/plugins/pluginmgr/skill_handout.go
@@ -0,0 +1,182 @@
+package pluginmgr
+
+// 随包 skill 的登记（hand-out）。
+//
+// ## 为什么需要它
+//
+// 插件与 skill 是两种分发物，此前**互不相通**：
+//
+//	插件  → 解压到 <plugin.dir>/<name>/，由插件注册表加载
+//	skill → 放在 <data.dir>/skills/，由 skillmgr 扫描注册
+//
+// 于是 commondev 的 `commondev-discipline`（用这套插件的全部纪律，798 行）
+// 装完插件的人**拿不到** —— 除非有人记得手动跑一次命令。
+// 这就是「知识在文件里躺着，用户手上没有」的典型断链。
+//
+// ## 为什么要走事件，而不是直接调 skillmgr
+//
+// 两个插件之间不该有直接依赖（pluginmgr 不该 import skillmgr）。
+// 内核已有现成的**事件式职责链**——原生 skillmgr 订阅 skill_detected
+// 并接管注册（`internal/plugins/skillmgr/plugin.go`），
+// 而发布者可以是任何持有完整 SDK 的内置插件。
+//
+// 所以这里只做**发现 + 移交**：解压后扫 `<插件目录>/skill/`，
+// 对每个条目发一个 skill_detected。归属与生命周期归 skillmgr。
+//
+// ## 为什么只对「目录」发
+//
+// skillmgr 的 loadOne 要求目录里有 SKILL.md 或 skill.json。
+// 直接对目录发是它已有的契约（clawhubadapter 也是这么发的）。
+//
+// ## 为什么失败不阻断安装
+//
+// 插件能装上、能跑，是主要目的；skill 登记是附带收益。
+// 但**不静默**：每个失败都记日志并回报在安装结果里。
+
+import (
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/JianFeeeee/HomeAgent/internal/events"
+)
+
+// SkillDirName 是插件包里约定存放 skill 的目录名。
+//
+// 与 `rawfile/` 并列：rawfile 是"任意随包资源"，skill 是"要登记给
+// skillmgr 的纯 SKILL 条目"。分开的理由是**意图不同** ——
+// 内核需要知道哪些是要注册的，靠子路径名去猜（如 rawfile/skills/）
+// 属于隐式约定，正是本仓反复吃过亏的模式。
+const SkillDirName = "skill"
+
+// handOutPluginSkills 扫 `<插件目录>/skill/*` 并把每个条目移交 skillmgr。
+//
+// 返回 (成功移交数, 失败清单)。失败不阻断安装，但必须回报。
+func (p *Plugin) handOutPluginSkills(pluginDir, pluginName string) (int, []string) {
+	if p.sdk == nil {
+		return 0, nil
+	}
+	root := filepath.Join(pluginDir, SkillDirName)
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		// 没有 skill/ 目录是**常态**（绝大多数插件不带 skill），
+		// 不是错误 —— 不记日志、不回报。
+		return 0, nil
+	}
+
+	var failed []string
+	n := 0
+	for _, e := range entries {
+		name := e.Name()
+		// 跳过隐藏文件与占位（.gitkeep/.gitignore 等工程脚手架）
+		if strings.HasPrefix(name, ".") {
+			continue
+		}
+		if !e.IsDir() {
+			continue
+		}
+		path := filepath.Join(root, name)
+		// ★ 只发**看起来是纯 SKILL** 的条目。
+		//
+		// 不检查的话，一个误放在 skill/ 下的 sidecar 目录（含 main.js）
+		// 会被 skillmgr 拒收（它的 loadOne 要求 SKILL.md/skill.json），
+		// 于是每次安装都报一条无意义的失败。在源头过滤更干净。
+		if !looksLikeNativeSkill(path) {
+			log.Printf("[pluginmgr] %s: %s/%s 缺 SKILL.md 或 skill.json，跳过登记",
+				pluginName, SkillDirName, name)
+			failed = append(failed, name+"（缺 SKILL.md 或 skill.json）")
+			continue
+		}
+
+		// Source 用插件名：skillmgr 只按 path 处理，Source 只供日志/溯源。
+		p.sdk.Publish(&events.Event{
+			Type:   events.EventSkillDetected,
+			Source: p.name,
+			Payload: map[string]interface{}{
+				"path": path,
+				// 额外字段不改变 skillmgr 的行为（它只读 path），
+				// 但让日志能看出这条 skill 是谁带来的。
+				"from_plugin": pluginName,
+			},
+			Timestamp: time.Now().Unix(),
+		})
+		log.Printf("[pluginmgr] %s: 已移交 skill %s 给 skillmgr", pluginName, name)
+		n++
+	}
+	return n, failed
+}
+
+// looksLikeNativeSkill 判断目录是否是 skillmgr 认得的纯 SKILL 条目。
+//
+// 与 skillmgr.isNativeSkillPath 的判据保持一致（SKILL.md 或 skill.json），
+// 但**故意不重复它的排除逻辑**（main.js/openclaw.plugin.json 等）：
+// 那些属于兼容层的职责划分，pluginmgr 不该复刻。这里只做"显然不是 skill
+// 就别发"的粗筛，精判留给归属者 —— 这样两边的判据不会漂移成两份。
+func looksLikeNativeSkill(dir string) bool {
+	for _, f := range []string{"SKILL.md", "skill.json"} {
+		if st, err := os.Stat(filepath.Join(dir, f)); err == nil && !st.IsDir() {
+			return true
+		}
+	}
+	return false
+}
+
+// reHandOutAllPluginSkills 在**启动时**重新登记所有已装插件的随包 skill。
+//
+// ## 为什么必须有这个（实测发现的真缺陷）
+//
+// 移交只发生在**安装那一刻**（installFromData → handOutPluginSkills）。
+// 而 skill 在**插件目录**里（`<plugin.dir>/<name>/skill/`），不在
+// skillmgr 的扫描目录（`<data.dir>/skills/`）里。于是：
+//
+//	装插件 → skill 注册 ✅
+//	  ↓ worker 重启（部署、崩溃恢复、热更新）
+//	skillmgr 只扫 skillsDir → **skill 消失** ❌
+//
+// 实测：2026-10-15 装完 commondev 后 skill 正常注册；一次热更新
+// （worker exit 42 重建）之后 `loaded SKILL: commondev-discipline`
+// 不再出现 —— 用户以为 skill 还在，实际已经没了。属于**静默丢失**。
+//
+// ## 为什么放在 pluginmgr 而不是 skillmgr
+//
+// 只有 pluginmgr 知道插件装在哪（它管 pluginDir）。skillmgr 去读插件目录
+// 会把"插件布局"这个知识复制到第二个地方 —— 正是本仓反复吃亏的模式。
+//
+// 顺序注意：pluginmgr 的 Start 与 skillmgr 的 Start 谁先跑不确定，
+// 而 skillmgr 的订阅在它 Start 里建立。若 pluginmgr 先发事件、skillmgr
+// 后订阅，事件就丢了。所以这里**延迟一小段再发**，并且 skillmgr 的
+// loadOne 幂等 —— 重复到达无副作用。
+func (p *Plugin) reHandOutAllPluginSkills() {
+	dir := p.pluginDir
+	if dir == "" || p.sdk == nil {
+		return
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	n := 0
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		cnt, _ := p.handOutPluginSkills(filepath.Join(dir, e.Name()), e.Name())
+		n += cnt
+	}
+	if n > 0 {
+		log.Printf("[pluginmgr] 启动重扫：已重新移交 %d 个随包 skill（否则重启后会静默丢失）", n)
+	}
+}
+
+// scheduleStartupSkillRescan 延迟重扫：等 skillmgr 的订阅就绪。
+//
+// 延时常量 intentionally 小（本机实测 skillmgr 的 Start 在百毫秒级完成）；
+// 即便错过，loadOne 幂等 —— 下次安装或重启仍会补上，只是本次会话里晚一点。
+func (p *Plugin) scheduleStartupSkillRescan() {
+	go func() {
+		time.Sleep(2 * time.Second)
+		p.reHandOutAllPluginSkills()
+	}()
+}
diff --git a/internal/plugins/pluginmgr/skill_handout_test.go b/internal/plugins/pluginmgr/skill_handout_test.go
new file mode 100644
index 00000000..f4b8eec0
--- /dev/null
+++ b/internal/plugins/pluginmgr/skill_handout_test.go
@@ -0,0 +1,385 @@
+package pluginmgr
+
+// 随包 skill 移交的判据。
+//
+// 覆盖的缺口：插件与 skill 此前是两种**互不相通**的分发物 —— 插件解压到
+// <plugin.dir>/<name>/，skill 由 skillmgr 扫 <data.dir>/skills/。
+// 于是随插件分发的 skill 装完就到不了用户手上。
+//
+// 修法：pluginmgr（内置插件，持有完整 SDK）在解压后扫 <插件目录>/skill/，
+// 对每个条目发 skill_detected；skillmgr 已订阅该事件并接管注册。
+//
+// 判据必须钉住**三个环节**，缺一个链路就不通：
+//   ① 发现：只认真正的纯 SKILL，不误发别的目录
+//   ② 移交：事件类型/载荷正确（skillmgr 只读 payload["path"]）
+//   ③ 贯通：事件真的会被 skillmgr 的订阅者收到（用真事件总线验证）
+
+import (
+	"archive/zip"
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/events"
+	"github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// buildHmapWithSkills 造一个带 skill/ 目录的插件包。
+func buildHmapWithSkills(t *testing.T, files map[string]string) []byte {
+	return buildHmapWithSkillsVer(t, "1.0.0", files)
+}
+
+// buildHmapWithSkillsVer 同前，但可指定版本号。
+//
+// ★ 不能对已生成的 zip 做字节替换来改版本 —— 那会破坏 zip 的校验和，
+// 报 "zip: checksum error"（实测踩到）。必须**重新打包**。
+func buildHmapWithSkillsVer(t *testing.T, version string, files map[string]string) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	w := zip.NewWriter(&buf)
+	add := func(name, content string) {
+		hdr := &zip.FileHeader{Name: name, Method: zip.Deflate}
+		fw, err := w.CreateHeader(hdr)
+		if err != nil {
+			t.Fatal(err)
+		}
+		fw.Write([]byte(content))
+	}
+	// ★ 不带 platforms 字段 ⇒ legacy 模式：entry 直接指向 plugin.bin。
+	//
+	// 初版写了 platforms 却没提供对应名字的二进制（platformBinary() 期望
+	// plugin.bin.<goos>.<goarch>），于是 validatePackage 直接以
+	// "no valid binary found" 拒绝 —— 判据全红但并非功能缺失。
+	// 这是**判据自己的缺陷**（造的包不合规），不是被测代码的问题。
+	add("plugin.json", `{"name":"skilltest","version":"`+version+`","entry":"plugin.bin"}`)
+	add("plugin.bin", "#!/bin/sh\n")
+	for n, c := range files {
+		add(n, c)
+	}
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+	return buf.Bytes()
+}
+
+// newTestPluginWithBus 造一个挂了**真事件总线**的 pluginmgr。
+func newTestPluginWithBus(t *testing.T, dir string) (*Plugin, *events.Bus) {
+	t.Helper()
+	bus := events.NewBus()
+	sdkInst := sdk.New("pluginmgr", sdk.SDKConfig{
+		Settings: &pmSettings{},
+		EventBus: bus,
+	})
+	return &Plugin{name: "pluginmgr", pluginDir: dir, sdk: sdkInst}, bus
+}
+
+// ★★★ 判据：安装带 skill 的插件 → **skill_detected 事件真的发出来了**。
+//
+// 这是整条链路的核心：接收端（skillmgr）是现成的，要看的是发布端真的发。
+func TestInstallPublishesSkillDetected(t *testing.T) {
+	dir := t.TempDir()
+	p, bus := newTestPluginWithBus(t, dir)
+
+	// 订阅（模拟 skillmgr 的订阅）
+	type got struct {
+		path string
+		src  string
+	}
+	ch := make(chan got, 8)
+	bus.Subscribe(events.EventSkillDetected, func(e *events.Event) {
+		path, _ := e.Payload["path"].(string)
+		ch <- got{path, e.Source}
+	})
+
+	data := buildHmapWithSkills(t, map[string]string{
+		"skill/my-skill/SKILL.md": "---\nname: my-skill\n---\n# hi\n",
+		"skill/other/skill.json":  `{"name":"other"}`,
+	})
+	if _, err := p.installFromData(data, false); err != nil {
+		t.Fatalf("安装失败: %v", err)
+	}
+
+	// 必须收到恰好 2 个事件
+	var paths []string
+	for i := 0; i < 2; i++ {
+		select {
+		case g := <-ch:
+			paths = append(paths, g.path)
+			if g.src == "" {
+				t.Error("事件缺少 Source（无法溯源是谁带来的 skill）")
+			}
+		default:
+			t.Fatalf("只收到 %d 个 skill_detected 事件，期望 2 个（已收: %v）", i, paths)
+		}
+	}
+	joined := strings.Join(paths, ",")
+	if !strings.Contains(joined, "my-skill") || !strings.Contains(joined, "other") {
+		t.Errorf("移交的路径不对: %v", paths)
+	}
+	// 路径必须指向**解压后**的位置（而不是包里的相对路径）
+	for _, pa := range paths {
+		if !strings.HasPrefix(pa, filepath.Join(dir, "skilltest")) {
+			t.Errorf("★ 路径不在插件目录下（skillmgr 会找不到）: %s", pa)
+		}
+		if _, err := os.Stat(pa); err != nil {
+			t.Errorf("★ 移交的路径不存在: %s", pa)
+		}
+	}
+}
+
+// ★★ 判据：**没有 skill/ 目录的插件不发任何事件**（绝大多数插件如此）。
+//
+// 不过滤的话每次装插件都会发噪音事件，skillmgr 反复收到无效路径。
+func TestPluginWithoutSkillsPublishesNothing(t *testing.T) {
+	dir := t.TempDir()
+	p, bus := newTestPluginWithBus(t, dir)
+	n := 0
+	bus.Subscribe(events.EventSkillDetected, func(e *events.Event) { n++ })
+
+	data := buildHmapWithSkills(t, map[string]string{
+		"plugin.json":           `{"name":"x","version":"1.0.0","entry":"plugin.bin"}`,
+		"rawfile/some/data.txt": "x",
+	})
+	if _, err := p.installFromData(data, false); err != nil {
+		t.Fatalf("安装失败: %v", err)
+	}
+	if n != 0 {
+		t.Errorf("★ 无 skill 的插件不该发事件，实际发了 %d 个", n)
+	}
+}
+
+// ★★ 判据：**不是纯 SKILL 的目录不发**（避免 skillmgr 报无意义失败）。
+//
+// skillmgr 的 loadOne 要求 SKILL.md 或 skill.json。误放在 skill/ 下的
+// sidecar 目录（含 main.js）会被它拒收 —— 与其发出去再失败，
+// 不如在源头过滤并如实回报。
+func TestNonSkillDirsAreNotPublished(t *testing.T) {
+	dir := t.TempDir()
+	p, bus := newTestPluginWithBus(t, dir)
+	var paths []string
+	bus.Subscribe(events.EventSkillDetected, func(e *events.Event) {
+		pa, _ := e.Payload["path"].(string)
+		paths = append(paths, pa)
+	})
+
+	data := buildHmapWithSkills(t, map[string]string{
+		"skill/good/SKILL.md":       "x",
+		"skill/bad-sidecar/main.js": "x", // 不是纯 SKILL
+		"skill/empty/notes.txt":     "x", // 没有 SKILL.md/skill.json
+	})
+	res, _ := p.installFromData(data, false)
+	m := res.(map[string]interface{})
+
+	if len(paths) != 1 {
+		t.Errorf("★ 只应移交 1 个（good），实际 %d: %v", len(paths), paths)
+	}
+	if !strings.HasSuffix(paths[0], "good") {
+		t.Errorf("移交错了条目: %v", paths)
+	}
+	// 被跳过的必须**如实回报**，不静默吞掉
+	failed, _ := m["skills_failed"].([]string)
+	if len(failed) != 2 {
+		t.Errorf("★ 被跳过的 2 个应回报在 skills_failed，实际 %v", m["skills_failed"])
+	}
+}
+
+// ★★ 判据：脚手架文件不触发移交（.gitkeep/.gitignore）。
+func TestScaffoldFilesDoNotTriggerPublish(t *testing.T) {
+	dir := t.TempDir()
+	p, bus := newTestPluginWithBus(t, dir)
+	var paths []string
+	bus.Subscribe(events.EventSkillDetected, func(e *events.Event) {
+		pa, _ := e.Payload["path"].(string)
+		paths = append(paths, pa)
+	})
+	data := buildHmapWithSkills(t, map[string]string{
+		"skill/.gitkeep":   "",
+		"skill/.gitignore": "*\n",
+		// ★ 隐藏**目录**：仅靠 IsDir() 挡不住，必须显式跳过 "."
+		// （隐藏文件是文件，会被 IsDir() 过滤掉，所以单测它们**测不到**这条规则）。
+		"skill/.hidden-dir/SKILL.md": "x",
+	})
+	res, _ := p.installFromData(data, false)
+	if len(paths) != 0 {
+		t.Errorf("★ 脚手架不应触发移交: %v", paths)
+	}
+	m := res.(map[string]interface{})
+	if n, _ := m["skills_registered"].(int); n != 0 {
+		t.Errorf("skills_registered 应为 0，实际 %v", m["skills_registered"])
+	}
+}
+
+// ★★★ 判据：**端到端贯通** —— pluginmgr 发的事件，skillmgr 的订阅者收得到。
+//
+// 前面几条验证"发出来了"，这条验证"真的能被接收端收到"。
+// 用真实事件总线 + 模拟 skillmgr 的处理逻辑（读 payload["path"] 并校验可加载）。
+func TestEventReachesSkillmgrConsumer(t *testing.T) {
+	dir := t.TempDir()
+	p, bus := newTestPluginWithBus(t, dir)
+
+	// 模拟 skillmgr 的订阅者：它只读 path，然后 loadOne
+	loaded := make(chan string, 4)
+	bus.Subscribe(events.EventSkillDetected, func(e *events.Event) {
+		path, _ := e.Payload["path"].(string)
+		if path == "" {
+			return // skillmgr 的实际行为：空路径直接返回
+		}
+		// 复刻 skillmgr 的准入判据
+		for _, f := range []string{"SKILL.md", "skill.json"} {
+			if _, err := os.Stat(filepath.Join(path, f)); err == nil {
+				loaded <- path
+				return
+			}
+		}
+	})
+
+	data := buildHmapWithSkills(t, map[string]string{
+		"skill/discipline/SKILL.md": "# 纪律\n",
+	})
+	if _, err := p.installFromData(data, false); err != nil {
+		t.Fatal(err)
+	}
+
+	select {
+	case path := <-loaded:
+		if !strings.HasSuffix(path, "discipline") {
+			t.Errorf("加载的路径不对: %s", path)
+		}
+		// 内容必须真的可读（证明路径指向解压后的真实文件）
+		b, err := os.ReadFile(filepath.Join(path, "SKILL.md"))
+		if err != nil || !strings.Contains(string(b), "纪律") {
+			t.Errorf("★ skill 内容不可读: %v %q", err, b)
+		}
+	default:
+		t.Fatal("★ 端到端不通：skillmgr 的订阅者没收到事件")
+	}
+}
+
+// ★★ 判据：**升级路径也移交**（不只在全新安装时）。
+//
+// 漏掉升级路径的话，已装插件的用户**永远拿不到**新版的 skill ——
+// 而升级是最常见的更新方式。
+func TestUpgradeAlsoHandsOutSkills(t *testing.T) {
+	dir := t.TempDir()
+	p, bus := newTestPluginWithBus(t, dir)
+	var paths []string
+	bus.Subscribe(events.EventSkillDetected, func(e *events.Event) {
+		pa, _ := e.Payload["path"].(string)
+		paths = append(paths, pa)
+	})
+
+	v1 := buildHmapWithSkills(t, map[string]string{"skill/s1/SKILL.md": "v1"})
+	if _, err := p.installFromData(v1, false); err != nil {
+		t.Fatal(err)
+	}
+	first := len(paths)
+	if first == 0 {
+		t.Fatal("首次安装未移交")
+	}
+
+	// 升级到 v2：**重新打包**（不是替换字节 —— 那会坏校验和）
+	v2 := buildHmapWithSkillsVer(t, "2.0.0", map[string]string{"skill/s2/SKILL.md": "v2"})
+	res, _ := p.installFromData(v2, true)
+	m, _ := res.(map[string]interface{})
+	if e, bad := m["error"]; bad {
+		t.Fatalf("升级失败: %v (%v)", e, m["details"])
+	}
+	if len(paths) <= first {
+		t.Fatalf("★ 升级路径未移交 skill（首次 %d，升级后 %d）", first, len(paths))
+	}
+	// 升级后新的 skill 也要在
+	found := false
+	for _, pa := range paths[first:] {
+		if strings.HasSuffix(pa, "s2") {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("升级后未移交新 skill: %v", paths[first:])
+	}
+}
+
+// ★ 判据：安装结果里如实回报 skill 数（不静默）。
+func TestInstallResultReportsSkillCount(t *testing.T) {
+	dir := t.TempDir()
+	p, _ := newTestPluginWithBus(t, dir)
+	data := buildHmapWithSkills(t, map[string]string{"skill/a/SKILL.md": "x"})
+	res, _ := p.installFromData(data, false)
+	m := res.(map[string]interface{})
+	if n, ok := m["skills_registered"].(int); !ok || n != 1 {
+		t.Errorf("★ skills_registered 应为 1，实际 %#v", m["skills_registered"])
+	}
+	// 该字段必须能被 JSON 序列化（外部调用方要读它）
+	if _, err := json.Marshal(m); err != nil {
+		t.Errorf("安装结果无法序列化: %v", err)
+	}
+}
+
+// ★★★ 判据：**启动时必须重新登记随包 skill**（重启不该丢）。
+//
+// 这条是实测发现的真缺陷（2026-10-15）：
+//
+//	装插件 → skill 注册 ✅
+//	  ↓ worker 重启
+//	skillmgr 只扫 skillsDir（skill 在**插件目录**里）→ skill 静默消失 ❌
+//
+// 移交只发生在安装那一刻，重启后没有任何重新发现机制。
+// 后果是"用户以为 skill 还在，实际已经没了"——典型的静默丢失。
+func TestStartupReHandsOutPluginSkills(t *testing.T) {
+	dir := t.TempDir()
+	p, bus := newTestPluginWithBus(t, dir)
+	p.pluginDir = dir
+
+	// 造一个"已装插件"的目录布局：<pluginDir>/<name>/skill/<s>/SKILL.md
+	// （模拟上一次安装留下的产物，进程重启后就是这个状态）
+	skillDir := filepath.Join(dir, "someplugin", "skill", "my-discipline")
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte("# 纪律"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// 订阅（模拟 skillmgr 已在运行）
+	got := make(chan string, 4)
+	bus.Subscribe(events.EventSkillDetected, func(e *events.Event) {
+		pa, _ := e.Payload["path"].(string)
+		got <- pa
+	})
+
+	// 调启动重扫（不启 goroutine，直接同步调便于断言）
+	p.reHandOutAllPluginSkills()
+
+	select {
+	case path := <-got:
+		if !strings.HasSuffix(path, "my-discipline") {
+			t.Errorf("移交路径不对: %s", path)
+		}
+		// 路径必须真实可读（否则 skillmgr 会失败）
+		if _, err := os.Stat(filepath.Join(path, "SKILL.md")); err != nil {
+			t.Errorf("★ 移交路径不可读: %v", err)
+		}
+	default:
+		t.Fatal("★ 启动重扫没有重新移交随包 skill（重启后会静默丢失）")
+	}
+}
+
+// ★★ 判据：启动重扫对**没有 skill 的插件**不发噪音事件。
+func TestStartupRescanIgnoresPluginsWithoutSkills(t *testing.T) {
+	dir := t.TempDir()
+	p, bus := newTestPluginWithBus(t, dir)
+	p.pluginDir = dir
+	// 两个没有 skill/ 的插件目录
+	for _, n := range []string{"plain1", "plain2"} {
+		os.MkdirAll(filepath.Join(dir, n), 0o755)
+	}
+	n := 0
+	bus.Subscribe(events.EventSkillDetected, func(e *events.Event) { n++ })
+	p.reHandOutAllPluginSkills()
+	if n != 0 {
+		t.Errorf("无 skill 的插件不该发事件，实际 %d 个", n)
+	}
+}
diff --git a/internal/plugins/pluginmgr/skill_realinstall_test.go b/internal/plugins/pluginmgr/skill_realinstall_test.go
new file mode 100644
index 00000000..7feb0342
--- /dev/null
+++ b/internal/plugins/pluginmgr/skill_realinstall_test.go
@@ -0,0 +1,69 @@
+package pluginmgr
+
+// ★★★ 真实包 → 安装 → skill 移交 的端到端判据。
+//
+// 用**真实的 commondev bundle**（含内嵌 node+pi + 随包 skill）跑一遍
+// installFromData，验证 skill_detected 事件真的带着**可加载的路径**发出来。
+//
+// 这条把三段串起来：打包（hmapdev 的 skill/ 约定）→ 安装（解压保留路径）
+// → 移交（pluginmgr 发事件）。任何一段断了，随包 skill 就到不了用户手上。
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/JianFeeeee/HomeAgent/internal/events"
+)
+
+func TestRealBundleHandsOutSkill(t *testing.T) {
+	src := os.Getenv("HA_RAWFILE_E2E_HMAP")
+	if src == "" {
+		t.Skip("设 HA_RAWFILE_E2E_HMAP=<hmap路径> 以运行（需先构建 commondev bundle）")
+	}
+	data, err := os.ReadFile(src)
+	if err != nil {
+		t.Fatalf("读包失败: %v", err)
+	}
+	t.Logf("真实包 %.1f MiB", float64(len(data))/(1<<20))
+
+	dir := t.TempDir()
+	p, bus := newTestPluginWithBus(t, dir)
+	var got []string
+	bus.Subscribe(events.EventSkillDetected, func(e *events.Event) {
+		pa, _ := e.Payload["path"].(string)
+		got = append(got, pa)
+	})
+
+	res, err := p.installFromData(data, false)
+	if err != nil {
+		t.Fatalf("安装失败: %v", err)
+	}
+	if m, ok := res.(map[string]interface{}); ok {
+		if e, bad := m["error"]; bad {
+			t.Fatalf("安装报错: %v (%v)", e, m["details"])
+		}
+		if n, _ := m["skills_registered"].(int); n != 1 {
+			t.Errorf("★ skills_registered 应为 1，实际 %v", m["skills_registered"])
+		}
+	}
+
+	if len(got) != 1 {
+		t.Fatalf("★ 应移交 1 个 skill，实际 %d: %v", len(got), got)
+	}
+	path := got[0]
+	if !strings.HasSuffix(path, "commondev-discipline") {
+		t.Errorf("移交的 skill 名不对: %s", path)
+	}
+	// ★ 关键：路径必须真的可加载（指向解压后的真实文件）
+	md := filepath.Join(path, "SKILL.md")
+	b, err := os.ReadFile(md)
+	if err != nil {
+		t.Fatalf("★ 移交路径不可读（skillmgr 会失败）: %v", err)
+	}
+	if len(b) < 1000 {
+		t.Errorf("SKILL.md 内容过短（%d 字节），可能没打进包", len(b))
+	}
+	t.Logf("移交成功：%s（SKILL.md %d 字节）", path, len(b))
+}
diff --git a/internal/plugins/pluginmgr/upgrade_test.go b/internal/plugins/pluginmgr/upgrade_test.go
index 792a7434..e1590414 100644
--- a/internal/plugins/pluginmgr/upgrade_test.go
+++ b/internal/plugins/pluginmgr/upgrade_test.go
@@ -15,13 +15,16 @@ import (
 )
 
 func TestCmpVersion(t *testing.T) {
-	cases := []struct{ a, b string; want int }{
+	cases := []struct {
+		a, b string
+		want int
+	}{
 		{"1.0.0", "1.0.0", 0},
 		{"1.0.1", "1.0.0", 1},
 		{"1.0.0", "1.0.1", -1},
 		{"1.0", "1.0.0", 0},
 		{"v2.0.0", "1.9.9", 1},
-		{"2.0.0", "10.0.0", -1}, // 数字比较而非字典序
+		{"2.0.0", "10.0.0", -1},     // 数字比较而非字典序
 		{"1.0.0-alpha", "1.0.0", 0}, // 非数字段按 0
 	}
 	for _, c := range cases {
@@ -39,6 +42,8 @@ func (m *pmSettings) DataDir() string { return "/tmp/mock_data" }
 
 func (m *pmSettings) Get(string) (interface{}, error)               { return nil, nil }
 func (m *pmSettings) Set(string, interface{}) error                 { return nil }
+func (m *pmSettings) SetSecret(string, interface{}) error           { return nil }
+func (m *pmSettings) GetSecret(string) (string, error)              { return "", nil }
 func (m *pmSettings) List(string) ([]string, error)                 { return nil, nil }
 func (m *pmSettings) GetCore(string) (interface{}, error)           { return nil, nil }
 func (m *pmSettings) SetCore(string, interface{}) error             { return nil }
@@ -56,6 +61,9 @@ func (m *pmSettings) Remove(string) error                           { return nil
 func (m *pmSettings) RemoveCore(string) error                       { return nil }
 func (m *pmSettings) RemovePlugin(string, string) error             { return nil }
 
+// IsSecret：E-3 起 SettingsAPI 要求实现（判断某键是否按密文存储）。
+func (m *pmSettings) IsSecret(string) bool { return false }
+
 // fakePluginMgr 记录调用；StopAndUnload 只记标志，不真正操作。
 type fakePluginMgr struct {
 	mu             sync.Mutex
@@ -68,6 +76,9 @@ func (f *fakePluginMgr) IsPluginDisabled(string) bool                  { return
 func (f *fakePluginMgr) IsBuiltinPlugin(string) bool                   { return false }
 func (f *fakePluginMgr) DisablePlugin(string, string) error            { return nil }
 func (f *fakePluginMgr) EnablePlugin(string) error                     { return nil }
+func (f *fakePluginMgr) StopPlugin(string) error                       { return nil }
+func (f *fakePluginMgr) StartPlugin(string) error                      { return nil }
+func (f *fakePluginMgr) IsPluginRuntimeStopped(string) bool            { return false }
 func (f *fakePluginMgr) RemovePlugin(string) error                     { return nil }
 func (f *fakePluginMgr) StopAndUnload(name string) error {
 	f.mu.Lock()
@@ -222,4 +233,4 @@ func TestExtractFailureRollsBack(t *testing.T) {
 	if err != nil || mfest.Version != "1.0.0" {
 		t.Fatalf("old version not restored: %v / %v", mfest, err)
 	}
-}
\ No newline at end of file
+}
diff --git a/internal/plugins/seemedia/integration_test.go b/internal/plugins/seemedia/integration_test.go
index 6ecc4953..19a760f1 100644
--- a/internal/plugins/seemedia/integration_test.go
+++ b/internal/plugins/seemedia/integration_test.go
@@ -29,7 +29,8 @@ import (
 // PluginSDK 与真实块引用（块 ID 或其唯一前缀，与生产同一取字节路径）。
 //
 // ★ CAS 淘汰后不再有媒体存储可 Put：字节进块（MemoryBlock.Data），
-//   插件用 sdk.Memory().MediaBytes(ref) 取回 —— 这正是测试要钉的路径。
+//
+//	插件用 sdk.Memory().MediaBytes(ref) 取回 —— 这正是测试要钉的路径。
 func sdkWithVideo(t *testing.T, raw []byte) (*sdk.PluginSDK, string) {
 	t.Helper()
 	dir := t.TempDir()
diff --git a/internal/plugins/seemedia/plugin.go b/internal/plugins/seemedia/plugin.go
index 6a59d47c..2df902ab 100644
--- a/internal/plugins/seemedia/plugin.go
+++ b/internal/plugins/seemedia/plugin.go
@@ -306,7 +306,8 @@ func (p *Plugin) handleSeeVideo(args map[string]interface{}) (interface{}, error
 // mediaBytes 按媒体块引用取回字节与 MIME。
 //
 // ★ CAS 淘汰后插件取媒体的唯一路径：块 ID（内容派生）就是媒体身份。
-//   取不到时返回 ok=false（“这个引用没媒体”是常态，不是错误）。
+//
+//	取不到时返回 ok=false（“这个引用没媒体”是常态，不是错误）。
 func (p *Plugin) mediaBytes(ref string) (data []byte, mime string, ok bool, err error) {
 	if p.sdk == nil || p.sdk.Memory() == nil {
 		return nil, "", false, fmt.Errorf("记忆系统不可用")
diff --git a/internal/plugins/skillmgr/plugin.go b/internal/plugins/skillmgr/plugin.go
index 748006e7..491ddf11 100644
--- a/internal/plugins/skillmgr/plugin.go
+++ b/internal/plugins/skillmgr/plugin.go
@@ -55,7 +55,7 @@ type SkillEntry struct {
 }
 
 type Plugin struct {
-	name     string
+	name      string
 	skillsDir string
 
 	mu     sync.RWMutex
diff --git a/internal/plugins/skillmgr/skillmgr_test.go b/internal/plugins/skillmgr/skillmgr_test.go
index e0451d2a..1b0583c6 100644
--- a/internal/plugins/skillmgr/skillmgr_test.go
+++ b/internal/plugins/skillmgr/skillmgr_test.go
@@ -21,24 +21,29 @@ type nilSettings struct{}
 
 func (m *nilSettings) DataDir() string { return "/tmp/mock_data" }
 
-func (m *nilSettings) Get(string) (interface{}, error)                    { return nil, nil }
-func (m *nilSettings) Set(string, interface{}) error                      { return nil }
-func (m *nilSettings) List(string) ([]string, error)                      { return nil, nil }
-func (m *nilSettings) GetCore(string) (interface{}, error)                { return nil, nil }
-func (m *nilSettings) SetCore(string, interface{}) error                  { return nil }
-func (m *nilSettings) ListCore(string) ([]string, error)                  { return nil, nil }
-func (m *nilSettings) GetPlugin(string, string) (interface{}, error)      { return nil, nil }
-func (m *nilSettings) SetPlugin(string, string, interface{}) error        { return nil }
-func (m *nilSettings) ListPlugin(string, string) ([]string, error)        { return nil, nil }
-func (m *nilSettings) RegisterDef(pubsdk.ConfigDef)                          {}
-func (m *nilSettings) Defs(string) []*pubsdk.ConfigDef                       { return nil }
-func (m *nilSettings) Dump() map[string]interface{}                          { return nil }
-func (m *nilSettings) Plugins() []string                                     { return nil }
-func (m *nilSettings) DefsCore(string) []*sdk.ConfigDef                      { return nil }
-func (m *nilSettings) DefsPlugin(string, string) []*sdk.ConfigDef            { return nil }
-func (m *nilSettings) Remove(string) error                                   { return nil }
-func (m *nilSettings) RemoveCore(string) error                               { return nil }
-func (m *nilSettings) RemovePlugin(string, string) error                     { return nil }
+func (m *nilSettings) Get(string) (interface{}, error)     { return nil, nil }
+func (m *nilSettings) Set(string, interface{}) error       { return nil }
+func (m *nilSettings) SetSecret(string, interface{}) error { return nil }
+func (m *nilSettings) GetSecret(string) (string, error)    { return "", nil }
+
+// IsSecret：E-3 起 SettingsAPI 要求实现（判断某键是否按密文存储）。
+func (m *nilSettings) IsSecret(string) bool                          { return false }
+func (m *nilSettings) List(string) ([]string, error)                 { return nil, nil }
+func (m *nilSettings) GetCore(string) (interface{}, error)           { return nil, nil }
+func (m *nilSettings) SetCore(string, interface{}) error             { return nil }
+func (m *nilSettings) ListCore(string) ([]string, error)             { return nil, nil }
+func (m *nilSettings) GetPlugin(string, string) (interface{}, error) { return nil, nil }
+func (m *nilSettings) SetPlugin(string, string, interface{}) error   { return nil }
+func (m *nilSettings) ListPlugin(string, string) ([]string, error)   { return nil, nil }
+func (m *nilSettings) RegisterDef(pubsdk.ConfigDef)                  {}
+func (m *nilSettings) Defs(string) []*pubsdk.ConfigDef               { return nil }
+func (m *nilSettings) Dump() map[string]interface{}                  { return nil }
+func (m *nilSettings) Plugins() []string                             { return nil }
+func (m *nilSettings) DefsCore(string) []*sdk.ConfigDef              { return nil }
+func (m *nilSettings) DefsPlugin(string, string) []*sdk.ConfigDef    { return nil }
+func (m *nilSettings) Remove(string) error                           { return nil }
+func (m *nilSettings) RemoveCore(string) error                       { return nil }
+func (m *nilSettings) RemovePlugin(string, string) error             { return nil }
 
 // toolSpy 记录注册的工具，并可按名调用 handler。
 type toolSpy struct {
@@ -46,7 +51,9 @@ type toolSpy struct {
 	handlers map[string]func(args map[string]interface{}) (interface{}, error)
 }
 
-func newToolSpy() *toolSpy { return &toolSpy{handlers: map[string]func(map[string]interface{}) (interface{}, error){}} }
+func newToolSpy() *toolSpy {
+	return &toolSpy{handlers: map[string]func(map[string]interface{}) (interface{}, error){}}
+}
 
 func (s *toolSpy) Register(name string, def interface{}, h func(args map[string]interface{}) (interface{}, error)) error {
 	s.mu.Lock()
@@ -83,13 +90,13 @@ func newTestPlugin(t *testing.T) (*Plugin, *toolSpy, *events.Bus) {
 
 	spy := newToolSpy()
 	cfgSDK := sdk.New("skillmgr", sdk.SDKConfig{
-		RegTool:   func(name string, def sdk.ToolDef, h sdk.ToolHandler) error {
+		RegTool: func(name string, def sdk.ToolDef, h sdk.ToolHandler) error {
 			return spy.Register(name, def, func(args map[string]interface{}) (interface{}, error) {
 				return h(args)
 			})
 		},
-		Settings:  &nilSettings{},
-		EventBus:  bus,
+		Settings: &nilSettings{},
+		EventBus: bus,
 	})
 	if err := p.Start(cfgSDK); err != nil {
 		t.Fatalf("Start: %v", err)
diff --git a/internal/plugins/skillmgr/tools.go b/internal/plugins/skillmgr/tools.go
index 349887eb..f3f32384 100644
--- a/internal/plugins/skillmgr/tools.go
+++ b/internal/plugins/skillmgr/tools.go
@@ -191,7 +191,7 @@ func (p *Plugin) registerSetEnabled(v bool) {
 func (p *Plugin) registerCreate() {
 	name := tp + "create"
 	p.sdk.RegisterTool(name, sdk.ToolDef{
-		Name: name,
+		Name:        name,
 		Description: "创建新技能骨架：生成标准 SKILL.md 模板写入 skills/<name>/。创建后在 content 参数填入完整文档内容并再次调用以落盘生效（两步式），或直接传 content 一步完成。",
 		Parameters: map[string]interface{}{
 			"type": "object",
diff --git a/internal/plugins/timer/plugin.go b/internal/plugins/timer/plugin.go
index a5958575..d5b29e24 100644
--- a/internal/plugins/timer/plugin.go
+++ b/internal/plugins/timer/plugin.go
@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/JianFeeeee/HomeAgent/internal/plugin"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
 )
 
@@ -43,7 +44,9 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	s.SetAutoRestart(true)
 	p.maxDur = 24 * time.Hour
 	// 停止清理（取消倒计时）交由 stop handler：内核在调用 Stop() 之前执行。
-	s.RegisterStopHandler(func() { close(p.stopCh) })
+	// 幂等（本仓 close 纪律）：stop handler 由内核调用；若将来多一条
+	// 停机路径（重载/热更新）就会二次 close ⇒ panic。
+	s.RegisterStopHandler(safeclose.SafeFunc(p.stopCh))
 	// 删除清理：移除插件自身配置（删除专用回调，重载不触发）。
 	s.RegisterOnRemoveHandler(func() {
 		if err := s.Settings().Remove("max_duration"); err != nil {
diff --git a/internal/plugins/webui/dashboard.js b/internal/plugins/webui/dashboard.js
index e0b8ae24..5f58e019 100644
--- a/internal/plugins/webui/dashboard.js
+++ b/internal/plugins/webui/dashboard.js
@@ -7806,6 +7806,18 @@ function pluginDisplayName(p) {
 	return name;
 }
 
+// toggleSecretVisibility 在「遮蔽 / 明文」间切换敏感输入框。
+// 内联 onclick 需要全局可见，故挂到 window。
+function toggleSecretVisibility(inpId) {
+	var el = document.getElementById(inpId);
+	if (!el) return;
+	var showing = el.type === "text";
+	el.type = showing ? "password" : "text";
+	var btn = el.parentElement ? el.parentElement.querySelector("button") : null;
+	if (btn) btn.textContent = showing ? __("显示", "Show") : __("隐藏", "Hide");
+}
+if (typeof window !== "undefined") window.toggleSecretVisibility = toggleSecretVisibility;
+
 function renderSettingsSidebar() {
 	var el = document.querySelector(".settings-tabs");
 	if (!el) return;
@@ -8025,6 +8037,30 @@ function renderOneSettings() {
 					"')\">" +
 					selOpts +
 					"</select>";
+			} else if (typ === "password" || m?.secret) {
+				// 敏感项：默认遮蔽，点「显示」才明文。
+				//
+				// 两种声明都走这里：Type=="password"（旧写法）与 Secret:true
+				// （新写法）。值本身是明文（内核透明解密），遮蔽只防肩窥/截屏，
+				// 不靠前端做保密 —— 真正的保护在落盘加密那一层。
+				inp =
+					"<label>" +
+					label +
+					'</label><div style="display:flex;gap:6px;align-items:center">' +
+					'<input type="password" id="' +
+					inpId +
+					'" value="' +
+					escHtml(sv) +
+					'" placeholder="' +
+					escHtml(ph) +
+					'" onchange="markDirty(\'' +
+					k +
+					"')\" style=\"flex:1\" autocomplete=\"new-password\">" +
+					'<button type="button" class="btn-sm" style="flex:0 0 auto" onclick="toggleSecretVisibility(\'' +
+					inpId +
+					"')\">" +
+					__("显示", "Show") +
+					"</button></div>";
 			} else if (typ === "text") {
 				inp =
 					"<label>" +
@@ -8323,6 +8359,19 @@ function markDirty(k) {
 async function saveSetting(k) {
 	var inp = document.getElementById("inp-" + k.replace(/\./g, "_"));
 	if (!inp) return;
+	// ★ 掩码占位符**不是值**，绝不能回传。
+	//
+	// 真实故障（2026-10-16）：列表接口为防泄漏把敏感值换成 `••••••••`，
+	// 而设置页「保存」按钮会**一并回传**该组的全部字段（含刚被掩码的 api_key）
+	// ⇒ 掩码被当真值存进内核 ⇒ 下游（commondev 的 pi 源导入器）把掩码
+	// 写进 auth.json ⇒ 模型调用 401 invalid api key。
+	//
+	// 两层防护：这里（前端不回传）与后端（PUT 拒绝占位符）。
+	// 前端这层必须独立成立：后端拒绝会让整组保存失败，用户以为"保存坏了"。
+	if (isSecretPlaceholderValue(inp.value)) {
+		// 未改动密钥时静默跳过（不该弹错——用户只是想改别的字段）
+		return;
+	}
 	var val;
 	var m = state.meta?.[k];
 	if (m?.type === "bool") {
@@ -8354,6 +8403,14 @@ async function saveSetting(k) {
 	}
 }
 
+// isSecretPlaceholderValue 判定输入框里的是否是掩码占位符（而非真实值）。
+//
+// 用**全等**而不是 includes：真 key 里恰好含这两个字符的概率极低，
+// 但反过来说，只要不是"整个值就是掩码"，就一律放行 —— 宁可放行也不误杀真值。
+function isSecretPlaceholderValue(v) {
+	return typeof v === "string" && v.trim() === "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+}
+
 function renderConfigDisabled() {
 	document.getElementById("tab-settings").innerHTML =
 		'<div class="card"><h2>' +
diff --git a/internal/plugins/webui/handler.go b/internal/plugins/webui/handler.go
index c63a8844..fe42d322 100644
--- a/internal/plugins/webui/handler.go
+++ b/internal/plugins/webui/handler.go
@@ -106,21 +106,22 @@ func init() {
 }
 
 type Handler struct {
-	sdk        *sdk.PluginSDK
-	supervisor sdk.SupervisorAPI
-	memory     sdk.MemoryAPI
-	indexer    sdk.IndexerAPI
-	adapter    sdk.AdapterAPI
-	config     sdk.ConfigAPI
-	startTime  time.Time
-	textMem    sdk.TextMemoryAPI
-	knowledge  sdk.KnowledgeAPI
-	tracker    sdk.TrackerAPI
-	settings   sdk.SettingsAPI
-	pluginMgr  sdk.PluginManager
-	status     sdk.StatusAPI
-	term       sdk.TerminalAPI
-	llm        sdk.LLMAPI
+	chatStopOnce2 sync.Once // close 纪律：chatStop 的幂等守卫
+	sdk           *sdk.PluginSDK
+	supervisor    sdk.SupervisorAPI
+	memory        sdk.MemoryAPI
+	indexer       sdk.IndexerAPI
+	adapter       sdk.AdapterAPI
+	config        sdk.ConfigAPI
+	startTime     time.Time
+	textMem       sdk.TextMemoryAPI
+	knowledge     sdk.KnowledgeAPI
+	tracker       sdk.TrackerAPI
+	settings      sdk.SettingsAPI
+	pluginMgr     sdk.PluginManager
+	status        sdk.StatusAPI
+	term          sdk.TerminalAPI
+	llm           sdk.LLMAPI
 
 	// hostPort 是 webui 实际监听的 ":port"（用于推导服务入口链接）。
 	hostPort string
@@ -487,6 +488,7 @@ func (h *Handler) RegisterRoutes(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/network", h.requireAPI(h.handleNetwork))
 	mux.HandleFunc("/api/v1/config", h.requireAPI(h.handleConfig))
 	mux.HandleFunc("/api/v1/settings", h.requireAPI(h.handleSettings))
+	mux.HandleFunc("/api/v1/settings/reveal", h.requireAPI(h.handleSettingsReveal))
 	mux.HandleFunc("/api/v1/settings/", h.requireAPI(h.handleSettings))
 	mux.HandleFunc("/api/v1/knowledge", h.requireAPI(h.handleKnowledge))
 	mux.HandleFunc("/api/v1/knowledge/", h.requireAPI(h.handleKnowledge))
diff --git a/internal/plugins/webui/handler_agents.go b/internal/plugins/webui/handler_agents.go
index 179bbe57..94543a77 100644
--- a/internal/plugins/webui/handler_agents.go
+++ b/internal/plugins/webui/handler_agents.go
@@ -231,12 +231,39 @@ func (h *Handler) handleRollback(w http.ResponseWriter, r *http.Request, agentID
 	writeJSON(w, http.StatusOK, map[string]string{"status": "rollback_initiated", "agent": string(agentID), "snap": string(snapID)})
 }
 
+// handleAgentAction 处理 start/stop/restart。
+//
+// ★ restart 是**热更新入口**（此前是 501 桩）：
+// 换掉 /usr/local/bin/homed 之后调它，worker 会以退出码 42 优雅退出，
+// guard 随即用**新二进制**重新拉起 —— 不必 systemctl restart，
+// 也不打断 guard（双进程架构的父进程）。
+//
+// stop/start 仍返回 501：它们的语义在「单 worker + guard 自动拉起」
+// 架构下没有独立意义（stop 之后 guard 立刻会把它拉回来）。
 func (h *Handler) handleAgentAction(w http.ResponseWriter, r *http.Request, agentID types.AgentID, action string) {
 	if r.Method != http.MethodPost {
 		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 		return
 	}
-	writeJSON(w, http.StatusNotImplemented, map[string]string{"error": fmt.Sprintf("agent %s action not implemented by supervisor", action)})
+	switch action {
+	case "restart":
+		if h.supervisor == nil {
+			writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "supervisor not available"})
+			return
+		}
+		if err := h.supervisor.Restart(string(agentID)); err != nil {
+			writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+			return
+		}
+		writeJSON(w, http.StatusAccepted, map[string]string{
+			"status": "restarting",
+			"agent":  string(agentID),
+			"note": "worker 将优雅退出（exit 42），guard 随后用当前二进制重新拉起；" +
+				"若刚替换过 /usr/local/bin/homed，新版本即在此刻生效",
+		})
+	default:
+		writeJSON(w, http.StatusNotImplemented, map[string]string{"error": fmt.Sprintf("agent %s action not implemented by supervisor", action)})
+	}
 }
 
 // handleRuntime 返回**只含运行态**的小快照：调度器（排队/四级中断队列/中断栈）、
diff --git a/internal/plugins/webui/handler_chat.go b/internal/plugins/webui/handler_chat.go
index 4a1c63ae..1f7f11f8 100644
--- a/internal/plugins/webui/handler_chat.go
+++ b/internal/plugins/webui/handler_chat.go
@@ -6,10 +6,12 @@ import (
 	"log"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"encoding/json"
 	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	sdk "github.com/JianFeeeee/HomeAgent/internal/sdk"
 	"net/http"
 )
@@ -66,8 +68,9 @@ const maxChatHistory = 200
 const maxChatMsgCache = 256
 
 type chatMsgEntry struct {
-	done chan struct{}
-	resp *agentIO.OutputEvent
+	done     chan struct{}
+	doneOnce sync.Once // close 纪律：见 internal/safeclose
+	resp     *agentIO.OutputEvent
 }
 
 func (h *Handler) claimChatMsg(id string) (*chatMsgEntry, bool) {
@@ -90,7 +93,9 @@ func (h *Handler) claimChatMsg(id string) (*chatMsgEntry, bool) {
 // completeChatMsg 记录首次处理结果并唤醒所有等待的同 ID 重放请求。
 func (h *Handler) completeChatMsg(e *chatMsgEntry, resp *agentIO.OutputEvent) {
 	e.resp = resp
-	close(e.done)
+	// 幂等（本仓 close 纪律）：同一 chat ID 若重复完成（重放/重试），
+	// 裸 close 会 panic。e.done 是"等待者被唤醒"的信号，重复唤醒无意义。
+	safeclose.Safe(&e.doneOnce, e.done)
 }
 
 func (h *Handler) loadChatHistory() {
@@ -322,7 +327,10 @@ func (h *Handler) persistChatLocked() {
 
 // chatPersistLoop 把聊天记录按节流节奏落盘，直到 Close。
 func (h *Handler) chatPersistLoop() {
-	defer close(h.chatLoopDone)
+	// 幂等（本仓 close 纪律）：本循环理论上只跑一次，但循环可能在
+	// 重载/重建 handler 时被再次启动 ⇒ 裸 close 会 panic。
+	var loopDoneOnce sync.Once
+	defer safeclose.Safe(&loopDoneOnce, h.chatLoopDone)
 	timer := time.NewTimer(chatSaveThrottle)
 	timer.Stop()
 	defer timer.Stop()
@@ -382,7 +390,7 @@ func (h *Handler) flushChat() {
 // 由插件 Stop 调用；不这样做会丢掉最后一轮对话。
 func (h *Handler) Close() {
 	h.chatCloseOnce.Do(func() {
-		close(h.chatStop)
+		safeclose.Safe(&h.chatStopOnce2, h.chatStop)
 		<-h.chatLoopDone
 	})
 }
@@ -663,12 +671,13 @@ func (h *Handler) handleChatEvents(w http.ResponseWriter, r *http.Request) {
 	// 写入侧用短超时(50ms)兜底，比立即丢弃更友好。
 	writeCh := make(chan string, 2048)
 	writerDone := make(chan struct{})
+	var writerDoneOnce sync.Once
 	go func() {
 		defer func() {
 			if r := recover(); r != nil {
 				log.Printf("[SSE] writer panic: %v", r)
 			}
-			close(writerDone)
+			safeclose.Safe(&writerDoneOnce, writerDone)
 		}()
 		// 批量合并窗口：16ms 内收集的增量一次性 flush，降 flush 次数、
 		// 避免高频小包拖慢 socket 写导致 writeCh 积压丢 delta。
diff --git a/internal/plugins/webui/handler_graph_pulse_test.go b/internal/plugins/webui/handler_graph_pulse_test.go
index 4c1a273f..84962e1b 100644
--- a/internal/plugins/webui/handler_graph_pulse_test.go
+++ b/internal/plugins/webui/handler_graph_pulse_test.go
@@ -80,11 +80,11 @@ func graphFixture() map[string]interface{} {
 		//   修复前 pulse 读的是它，而它永远落在窗口外 ⇒ 恒返回空。
 		"memory_blocks": []memory.MemoryBlock{
 			{ID: "b_old", Modality: memory.BlockModality("text"), Text: "老块",
-				Vector: []float64{0.1, 0.2, 0.3},
+				Vector:    []float64{0.1, 0.2, 0.3},
 				CreatedAt: old, UpdatedAt: now.Add(-8 * time.Hour)},
 			{ID: "b_new", Modality: memory.BlockModality("image"), Text: "刚学到的东西",
 				Data: []byte("png-bytes"), MIME: "image/png",
-				Vector: []float64{0.1, 0.2, 0.3},
+				Vector:    []float64{0.1, 0.2, 0.3},
 				CreatedAt: now, UpdatedAt: now},
 		},
 	}
diff --git a/internal/plugins/webui/handler_knowledge_test.go b/internal/plugins/webui/handler_knowledge_test.go
index 5cc9aef9..d979de46 100644
--- a/internal/plugins/webui/handler_knowledge_test.go
+++ b/internal/plugins/webui/handler_knowledge_test.go
@@ -25,7 +25,8 @@ import (
 // newKnowledgeHandler 构造一个带知识库的 Handler。
 //
 // ★ 不再有“媒体存储”参数：CAS 淘汰后媒体字节随引用自带（KnowledgeMediaRef.Data），
-//   写知识不需要任何外部存储 —— 因此也不存在“存储未初始化”的失败态。
+//
+//	写知识不需要任何外部存储 —— 因此也不存在“存储未初始化”的失败态。
 func newKnowledgeHandler(t *testing.T) (*Handler, *knowledge.Store, string, func()) {
 	t.Helper()
 	dir := t.TempDir()
@@ -462,8 +463,9 @@ func TestKnowledgeUploadTextFileBecomesContent(t *testing.T) {
 // 上传的媒体必须真能取回字节，否则引用是死的。
 //
 // ★ CAS 淘汰后字节的归属变了：不再是全局内容寻址库，而是**条目目录自带的文件**
-//   （与 content.md 同生共灭）。所以判据也从“按 digest 向存储读回”改为
-//   “按条目记录的 File 从条目目录读回，且与上传字节逐字节一致”。
+//
+//	（与 content.md 同生共灭）。所以判据也从“按 digest 向存储读回”改为
+//	“按条目记录的 File 从条目目录读回，且与上传字节逐字节一致”。
 func TestKnowledgeUploadedMediaRetrievable(t *testing.T) {
 	h, ks, dir, done := newKnowledgeHandler(t)
 	defer done()
diff --git a/internal/plugins/webui/handler_openai.go b/internal/plugins/webui/handler_openai.go
index 52220a00..449987b0 100644
--- a/internal/plugins/webui/handler_openai.go
+++ b/internal/plugins/webui/handler_openai.go
@@ -10,6 +10,7 @@ import (
 	"sync"
 
 	agentIO "github.com/JianFeeeee/HomeAgent/internal/agent/io"
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
 	"github.com/JianFeeeee/HomeAgent/internal/sdk"
 )
 
@@ -221,8 +222,9 @@ func (h *Handler) streamOpenAI(ctx context.Context, w http.ResponseWriter, model
 		v, _ := p["reasoning_content"].(string)
 		return v, v != ""
 	})
+	var doneOnce sync.Once
 	defer func() {
-		close(done)
+		safeclose.Safe(&doneOnce, done)
 		wg.Wait()
 		for _, u := range unsubs {
 			u()
diff --git a/internal/plugins/webui/handler_plugin_test.go b/internal/plugins/webui/handler_plugin_test.go
index a668d34d..c7f4ba68 100644
--- a/internal/plugins/webui/handler_plugin_test.go
+++ b/internal/plugins/webui/handler_plugin_test.go
@@ -54,6 +54,13 @@ func (m *mockPluginMgr) ReloadPlugins() (string, error) {
 }
 func (m *mockPluginMgr) ReloadOne(name string) error     { return nil }
 func (m *mockPluginMgr) StopAndUnload(name string) error { return nil }
+
+// ★ SDK 1.4.0 起 PluginManager 新增 3 个"运行期停/启"方法（与持久禁用以区分）。
+// mock 必须跟上接口 —— 否则本包**编译失败**（不是判据红，是整个包挂），
+// 表现为 `webui [build failed]`，容易被误读成"webui 坏了"。
+func (m *mockPluginMgr) StopPlugin(name string) error            { return nil }
+func (m *mockPluginMgr) StartPlugin(name string) error           { return nil }
+func (m *mockPluginMgr) IsPluginRuntimeStopped(name string) bool { return false }
 func (m *mockPluginMgr) PluginMetas() map[string]sdk.PluginMeta {
 	return nil
 }
diff --git a/internal/plugins/webui/handler_settings.go b/internal/plugins/webui/handler_settings.go
index f0f40439..d2063cc6 100644
--- a/internal/plugins/webui/handler_settings.go
+++ b/internal/plugins/webui/handler_settings.go
@@ -114,6 +114,8 @@ func (h *Handler) handleSettings(w http.ResponseWriter, r *http.Request) {
 				}
 			}
 		}
+		// ★ E-3：列表永远默认屏蔽敏感值。明文揭示必须走单键 reveal 接口。
+		h.maskSecretValues(values, false)
 
 		plugins := []string{"core"}
 		for _, p := range h.settings.Plugins() {
@@ -151,6 +153,25 @@ func (h *Handler) handleSettings(w http.ResponseWriter, r *http.Request) {
 		if f, ok := body.Value.(float64); ok && f == math.Trunc(f) && math.Abs(f) < 1e15 {
 			body.Value = int64(f)
 		}
+		// ★ 掩码占位符**不是值**，绝不能存回内核。
+		//
+		// 真实故障（2026-10-16）：设置页里点一次「保存」，前端会把同一组字段
+		// （含刚被掩码的 api_key）一并回传 ⇒ `••••••••` 被当真实值存进
+		// `core.llm.sources.<n>.api_key` ⇒ 下游（commondev 的 pi 源导入器）
+		// 把掩码写进 pi 的 auth.json ⇒ 模型调用 401。
+		//
+		// 这里拒绝并**明确告诉调用方怎么做**：它没说"保存失败"就完了，
+		// 否则用户不知道该如何保存其他字段。
+		if IsSecretPlaceholder(body.Value) {
+			writeJSON(w, http.StatusConflict, map[string]string{
+				"error": "该值是**掩码占位符**（列表接口为防泄漏而显示的“已设置”标记），" +
+					"不是真实内容；存回它会用标记覆盖真值。" +
+					"若未修改此字段请**不要保存它**（只保存你改动的键）；" +
+					"若确实要改，请填入新的真值（或先调 reveal 接口取回当前值后再改）。",
+				"key": body.Key,
+			})
+			return
+		}
 		deleting := body.Value == nil
 		if strings.HasPrefix(body.Key, "plugin.") {
 			parts := strings.SplitN(body.Key, ".", 3)
diff --git a/internal/plugins/webui/secret_meta_test.go b/internal/plugins/webui/secret_meta_test.go
new file mode 100644
index 00000000..7e8267fb
--- /dev/null
+++ b/internal/plugins/webui/secret_meta_test.go
@@ -0,0 +1,117 @@
+package webui
+
+// 判据：**Secret 标志必须活着到达 WebUI 的 meta**。
+//
+// 由来：SDK 的 ConfigDef 一直有 Secret 字段，但内核侧三处转换
+// （settingsImpl.RegisterDef / Defs / mapDefs）全部漏掉了它 ——
+// 插件声明了 secret，前端拿到的 meta 里却没有这个标记，
+// 于是敏感项被渲染成普通文本框明文回显。
+//
+// 这条判据钉住「声明 → meta」这一段，防止再次被漏掉。
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
+	internalSDK "github.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+func TestSecretFlagReachesSettingsMeta(t *testing.T) {
+	dir := t.TempDir()
+	internalConfig.ResetTestCodec(t)
+	reg := internalConfig.NewConfigRegistry(dir + "/config.db")
+	defer reg.Close()
+
+	// 插件用**两种写法**各声明一个敏感项
+	sett := internalSDK.NewSettings("secplug", reg)
+	sett.RegisterDef(internalSDK.ConfigDef{
+		Key: "by_flag", Type: "string", DisplayName: "标志式", Secret: true,
+	})
+	sett.RegisterDef(internalSDK.ConfigDef{
+		Key: "by_type", Type: "password", DisplayName: "类型式",
+	})
+
+	// 走真实 HTTP 处理器
+	h := &Handler{settings: internalSDK.NewSettings("webui", reg)}
+	req := httptest.NewRequest(http.MethodGet, "/api/settings?prefix=plugin.secplug", nil)
+	w := httptest.NewRecorder()
+	h.handleSettings(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("状态码 %d: %s", w.Code, w.Body.String())
+	}
+
+	var body struct {
+		Meta map[string]map[string]interface{} `json:"meta"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
+		t.Fatalf("解析响应失败: %v", err)
+	}
+
+	byFlag, ok := body.Meta["plugin.secplug.by_flag"]
+	if !ok {
+		t.Fatalf("meta 里没有 by_flag；实际键: %v", keysOfMeta(body.Meta))
+	}
+	if byFlag["secret"] != true {
+		t.Errorf("Secret:true 未传递到 meta（前端会明文回显）: %v", byFlag)
+	}
+	byType, ok := body.Meta["plugin.secplug.by_type"]
+	if !ok {
+		t.Fatalf("meta 里没有 by_type；实际键: %v", keysOfMeta(body.Meta))
+	}
+	if byType["type"] != "password" {
+		t.Errorf("password 类型应保持: %v", byType)
+	}
+}
+
+func keysOfMeta(m map[string]map[string]interface{}) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}
+
+// 判据：敏感项在 WebUI 列表里的默认值**必须屏蔽**（E-3），
+// 单键 reveal 才能看到明文；磁盘上仍是密文。
+func TestSecretPlainInUIButCipherOnDisk(t *testing.T) {
+	dir := t.TempDir()
+	internalConfig.ResetTestCodec(t)
+	reg := internalConfig.NewConfigRegistry(dir + "/config.db")
+	defer reg.Close()
+
+	sett := internalSDK.NewSettings("webui", reg)
+	sett.RegisterDef(internalSDK.ConfigDef{Key: "apikey", Type: "password"})
+	if err := sett.Set("apikey", "ui-visible-secret-123456"); err != nil {
+		t.Fatal(err)
+	}
+
+	h := &Handler{settings: internalSDK.NewSettings("webui", reg)}
+	req := httptest.NewRequest(http.MethodGet, "/api/settings?prefix=plugin.webui", nil)
+	w := httptest.NewRecorder()
+	h.handleSettings(w, req)
+
+	if strings.Contains(w.Body.String(), "ui-visible-secret-123456") {
+		t.Fatal("E-3：设置列表不应回显敏感明文")
+	}
+	if !strings.Contains(w.Body.String(), SecretPlaceholder) {
+		t.Fatal("设置列表应显示敏感值占位符")
+	}
+	// 显式揭示仍可核对（单键、当前 WebUI 插件范围）。
+	reveal := httptest.NewRecorder()
+	h.handleSettingsReveal(reveal, httptest.NewRequest(http.MethodGet, "/api/settings/reveal?key=plugin.webui.apikey", nil))
+	if reveal.Code != http.StatusOK || !strings.Contains(reveal.Body.String(), "ui-visible-secret-123456") {
+		t.Fatalf("显式 reveal 应返回当前插件的明文: status=%d body=%s", reveal.Code, reveal.Body.String())
+	}
+	var raw string
+	if err := reg.DB().QueryRow(
+		`SELECT value FROM config_webui WHERE key='apikey'`).Scan(&raw); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(raw, "ui-visible-secret") {
+		t.Errorf("磁盘上不应有明文: %q", raw)
+	}
+}
diff --git a/internal/plugins/webui/settings_secret.go b/internal/plugins/webui/settings_secret.go
new file mode 100644
index 00000000..5428e13f
--- /dev/null
+++ b/internal/plugins/webui/settings_secret.go
@@ -0,0 +1,150 @@
+package webui
+
+// 密钥可见性（E-3）：设置面的明文屏蔽与显式揭示。
+//
+// ## 问题
+//
+// `GET /api/v1/settings` 此前直接返回 `Dump()` 的**解密后**结果 ——
+// 也就是任何能打开设置页的人都能看到全部密钥（含其他插件的）。
+// 落盘的 AES 加密因此只保护了静态文件，对“已运行的服务”毫无作用。
+//
+// ## 不是靠“能不能进设置页”，而是靠显式揭示
+//
+// 权威用户的判断是：**任何能进设置页的人都可见**，所以要不要放宽不是重点；
+// 重点是**默认不显示**，要看必须显式请求（且留痕），并且只看得到**自己**的。
+//
+// ## 两条纪律
+//
+//  1. **默认屏蔽**：列表接口对敏感键只返回占位符，真值要单独揭示。
+//  2. **不跨插件**：`plugin.<other>.*` 的敏感值一律不可揭示 ——
+//     否则“插件 A 的页面能读到插件 B 的密钥”，比不屏蔽更糟
+//     （因为它看起来像是被管住了）。
+
+import (
+	"net/http"
+	"strings"
+)
+
+// SecretPlaceholder 是敏感值在列表里的占位符。
+//
+// 用固定串而不是“空”或“***”：前端据此显示「已设置（点击查看）」，
+// 而空串会被误认成“没配”。
+const SecretPlaceholder = "••••••••"
+
+// currentPluginOf 返回请求方所属插件名（webui 的接口是给 WebUI 自己的）。
+func (h *Handler) currentPluginOf() string { return "webui" }
+
+// maskSecretValues 把 values 里的敏感键换成占位符。
+//
+// reveal 为真时**不**屏蔽（调用方已做权限判定）。
+func (h *Handler) maskSecretValues(values map[string]interface{}, reveal bool) {
+	if reveal || h.settings == nil {
+		return
+	}
+	for k, v := range values {
+		if v == nil || v == "" {
+			continue // 未设置：保持原样，否则前端会把“没配”显示成“已配”
+		}
+		if h.settings.IsSecret(k) {
+			values[k] = SecretPlaceholder
+		}
+	}
+}
+
+// canRevealKey 判定某键的明文是否允许被揭示给当前调用方。
+//
+// 规则：核心键（core.*）与**本插件**的键可揭示；其他插件的键不可。
+func (h *Handler) canRevealKey(key string) bool {
+	if !strings.HasPrefix(key, "plugin.") {
+		return true // 核心配置：调用方已是能进设置页的权威用户
+	}
+	parts := strings.SplitN(key, ".", 3)
+	if len(parts) < 3 {
+		return false
+	}
+	return parts[1] == h.currentPluginOf()
+}
+
+// handleSettingsReveal 是 `GET /api/v1/settings/reveal?key=...` 的实现。
+//
+// 显式揭示**单个**键的明文。为何一次只给一个：
+// 批量揭示等于把“屏蔽”又变回“一次全给你”，屏蔽就成了装饰。
+func (h *Handler) handleSettingsReveal(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	if h.settings == nil {
+		writeJSON(w, http.StatusNotFound, map[string]string{"error": "config registry not available"})
+		return
+	}
+	key := strings.TrimSpace(r.URL.Query().Get("key"))
+	if key == "" {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "key 必填"})
+		return
+	}
+	if !h.settings.IsSecret(key) {
+		// 非敏感键无需揭示（但也不报错：前端可能不分类型地调用）
+		writeJSON(w, http.StatusOK, map[string]interface{}{
+			"key": key, "value": h.getSettingValue(key), "secret": false,
+		})
+		return
+	}
+	if !h.canRevealKey(key) {
+		// ★ 不跨插件。这里必须拒绝，否则“插件页能读别的插件密钥”。
+		writeJSON(w, http.StatusForbidden, map[string]string{
+			"error": "不允许读取其他插件的敏感配置（E-3）",
+		})
+		return
+	}
+	// 留痕：揭示明文是特权动作，必须可审计。
+	if h.settings != nil {
+		_ = h.settings.SetPlugin("webui", "last_secret_reveal", key)
+	}
+	writeJSON(w, http.StatusOK, map[string]interface{}{
+		"key": key, "value": h.getSettingValue(key), "secret": true,
+	})
+}
+
+// getSettingValue 按 namespace 取一个配置值（plugin.* 走插件表）。
+func (h *Handler) getSettingValue(key string) interface{} {
+	if strings.HasPrefix(key, "plugin.") {
+		parts := strings.SplitN(key, ".", 3)
+		if len(parts) >= 3 {
+			v, _ := h.settings.GetPlugin(parts[1], parts[2])
+			return v
+		}
+		return nil
+	}
+	v, _ := h.settings.GetCore(key)
+	return v
+}
+
+// IsSecretPlaceholder 报告一个值是否是掩码占位符本身。
+//
+// ## 为什么写侧必须判它（真实故障，2026-10-16）
+//
+// E-3 让列表接口把敏感值换成 `••••••••`（防泄漏，这部分是对的），
+// 但**写侧此前完全不检查占位符**，于是：
+//
+//	① 设置页 GET 拿到掩码 `••••••••`
+//	② 用户点同一个表单里的「保存」按钮（前端 saveSetting 会一并回传该组的所有字段，
+//	   包括刚被掩码的 api_key）——**即使用户只想改别的字段**
+//	③ PUT 把 `••••••••` 当真实值写进内核 `core.llm.sources.<n>.api_key`
+//	④ 任何读该键的下游（如 commondev 的 pi 源导入器）拿到的是**掩码而不是 key**
+//	⑤ pi 用它调 LLM ⇒ 401 invalid api key
+//
+// 实测证据：内核 `core.llm.api_key`（主键）解出来是**真 key**，
+// 而 `core.llm.sources.llmsproxy.api_key`（子键）解出来是 `••••••••`。
+// 插件导入器优先读 `sources.*` ⇒ 掩码进了 pi 的 auth.json。
+//
+// ⇒ 占位符**不是值**，它是"这里有个值但我不告诉你"的标记。
+//
+//	把它存回去等于用标记覆盖了真值。这不是"校验用户输入"，而是**语义错误**。
+func IsSecretPlaceholder(v interface{}) bool {
+	s, ok := v.(string)
+	if !ok {
+		return false
+	}
+	return strings.TrimSpace(s) == SecretPlaceholder
+}
diff --git a/internal/plugins/webui/settings_secret_test.go b/internal/plugins/webui/settings_secret_test.go
new file mode 100644
index 00000000..be3322c3
--- /dev/null
+++ b/internal/plugins/webui/settings_secret_test.go
@@ -0,0 +1,316 @@
+package webui
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	internalConfig "github.com/JianFeeeee/HomeAgent/internal/config"
+	"github.com/JianFeeeee/HomeAgent/internal/sdk"
+	"github.com/JianFeeeee/HomeAgent/internal/supervisor"
+	"github.com/JianFeeeee/HomeAgent/pkg/types"
+)
+
+// ★ E-3：设置列表默认不得返回任何敏感明文（包括其他插件的）。
+func TestSettingsMasksSecretValues(t *testing.T) {
+	reg := internalConfig.NewConfigRegistry("")
+	reg.RegisterDef(internalConfig.ConfigDef{Key: "core.llm.api_key", Type: "string", Secret: true})
+	if err := reg.Set("core.llm.api_key", "CORE_SECRET"); err != nil {
+		t.Fatal(err)
+	}
+	qq := reg.PluginConfig("qq")
+	qq.RegisterDef(internalConfig.ConfigDef{Key: "access_token", Type: "string", Secret: true})
+	if err := qq.Set("access_token", "QQ_SECRET"); err != nil {
+		t.Fatal(err)
+	}
+	sup := supervisor.New(&types.Config{Daemon: types.DaemonConfig{CheckInterval: 1, HeartbeatInterval: 1}})
+	sup.Start()
+	defer sup.Shutdown()
+	h := NewHandler(testSDK(sdk.SDKConfig{Supervisor: supervisor.NewSDKAdapter(sup), Settings: sdk.NewSettings("webui", reg), Config: sdk.NewConfig(&types.Config{})}))
+	w := httptest.NewRecorder()
+	h.handleSettings(w, httptest.NewRequest(http.MethodGet, "/api/v1/settings", nil))
+	if w.Code != http.StatusOK {
+		t.Fatalf("status=%d body=%s", w.Code, w.Body.String())
+	}
+	body := w.Body.String()
+	if strings.Contains(body, "CORE_SECRET") || strings.Contains(body, "QQ_SECRET") {
+		t.Fatalf("★ settings 泄露敏感明文: %s", body)
+	}
+	if !strings.Contains(body, SecretPlaceholder) {
+		t.Fatal("敏感值应显示占位符")
+	}
+}
+
+// ★ E-3：单键显式揭示允许核心/本插件，拒绝其他插件。
+func TestSettingsRevealScope(t *testing.T) {
+	reg := internalConfig.NewConfigRegistry("")
+	reg.RegisterDef(internalConfig.ConfigDef{Key: "core.llm.api_key", Type: "string", Secret: true})
+	reg.Set("core.llm.api_key", "CORE_SECRET")
+	web := reg.PluginConfig("webui")
+	web.RegisterDef(internalConfig.ConfigDef{Key: "api_key", Type: "string", Secret: true})
+	web.Set("api_key", "WEB_SECRET")
+	qq := reg.PluginConfig("qq")
+	qq.RegisterDef(internalConfig.ConfigDef{Key: "access_token", Type: "string", Secret: true})
+	qq.Set("access_token", "QQ_SECRET")
+	sup := supervisor.New(&types.Config{Daemon: types.DaemonConfig{CheckInterval: 1, HeartbeatInterval: 1}})
+	sup.Start()
+	defer sup.Shutdown()
+	h := NewHandler(testSDK(sdk.SDKConfig{Supervisor: supervisor.NewSDKAdapter(sup), Settings: sdk.NewSettings("webui", reg), Config: sdk.NewConfig(&types.Config{})}))
+	for _, tc := range []struct {
+		key, want string
+		status    int
+	}{
+		{"core.llm.api_key", "CORE_SECRET", http.StatusOK},
+		{"plugin.webui.api_key", "WEB_SECRET", http.StatusOK},
+		{"plugin.qq.access_token", "不允许读取其他插件", http.StatusForbidden},
+	} {
+		w := httptest.NewRecorder()
+		path := "/api/v1/settings/reveal?key=" + tc.key
+		h.handleSettingsReveal(w, httptest.NewRequest(http.MethodGet, path, nil))
+		if w.Code != tc.status {
+			t.Errorf("%s status=%d want=%d body=%s", tc.key, w.Code, tc.status, w.Body.String())
+			continue
+		}
+		if !strings.Contains(w.Body.String(), tc.want) {
+			t.Errorf("%s body lacks %q: %s", tc.key, tc.want, w.Body.String())
+		}
+		if tc.status == http.StatusOK {
+			var got map[string]interface{}
+			if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+				t.Fatal(err)
+			}
+			if got["secret"] != true {
+				t.Errorf("%s should mark secret=true", tc.key)
+			}
+		}
+	}
+}
+
+// ★★★ 判据：**掩码占位符绝不能经 PUT 存回内核**。
+//
+// 真实故障（2026-10-16，生产实测）：
+//
+//	① 设置页 GET 把 api_key 掩码成 `••••••••`（E-3 防泄漏，本身是对的）
+//	② 前端「保存」按钮会**一并回传**该组全部字段（含刚被掩码的 api_key）——
+//	   用户往往只想改同组的 base_url/model
+//	③ 写侧此前**完全不检查占位符** ⇒ `••••••••` 被当真实值存进
+//	   `core.llm.sources.<n>.api_key`
+//	④ commondev 的 pi 源导入器优先读 `sources.*` ⇒ 把掩码写进 pi 的 auth.json
+//	⑤ pi 拿掩码调模型 ⇒ 401 invalid api key（表现为"插件装了但模型不回复"）
+//
+// 铁证：内核 `core.llm.api_key`（主键）解密后是**真 key**，
+// 而 `core.llm.sources.llmsproxy.api_key`（子键）解密后是 `••••••••`。
+//
+// ⇒ 占位符是"这里有个值但我不告诉你"的**标记**，不是值。
+//
+//	把它存回去等于用标记覆盖真值 —— 这不是输入校验问题，是语义错误。
+func TestSettingsPutRejectsSecretPlaceholder(t *testing.T) {
+	reg := internalConfig.NewConfigRegistry("")
+	reg.RegisterDef(internalConfig.ConfigDef{Key: "core.llm.sources.x.api_key", Type: "string", Secret: true})
+	if err := reg.Set("core.llm.sources.x.api_key", "REAL_KEY_VALUE"); err != nil {
+		t.Fatal(err)
+	}
+	sup := supervisor.New(&types.Config{Daemon: types.DaemonConfig{CheckInterval: 1, HeartbeatInterval: 1}})
+	sup.Start()
+	defer sup.Shutdown()
+	h := NewHandler(testSDK(sdk.SDKConfig{Supervisor: supervisor.NewSDKAdapter(sup), Settings: sdk.NewSettings("webui", reg), Config: sdk.NewConfig(&types.Config{})}))
+
+	put := func(v interface{}) *httptest.ResponseRecorder {
+		body, _ := json.Marshal(map[string]interface{}{
+			"key": "core.llm.sources.x.api_key", "value": v,
+		})
+		req := httptest.NewRequest(http.MethodPut, "/api/v1/settings", strings.NewReader(string(body)))
+		w := httptest.NewRecorder()
+		h.handleSettings(w, req)
+		return w
+	}
+
+	// ① 掩码必须被拒绝（这是缺陷本体）
+	w := put(SecretPlaceholder)
+	if w.Code == http.StatusOK {
+		t.Fatalf("★ 掩码占位符被接受了（接口返回 200）—— 真值已被覆盖: %s", w.Body.String())
+	}
+	// ② 拒绝之后真值**必须还在**（拒绝而不是写坏）
+	got, _ := reg.Get("core.llm.sources.x.api_key")
+	if s, _ := got.(string); s != "REAL_KEY_VALUE" {
+		t.Fatalf("★ 拒绝后真值被改写: %q（拒绝必须是原子的：不写）", s)
+	}
+	// ③ 错误信息必须告诉用户**怎么办**（否则他不知道如何保存同组其他字段）
+	msg := w.Body.String()
+	for _, want := range []string{"掩码", "不要保存"} {
+		if !strings.Contains(msg, want) {
+			t.Errorf("错误应含 %q 以指导操作: %s", want, msg)
+		}
+	}
+
+	// ④ 真值仍然可以正常保存（不能误伤）
+	if w := put("NEW_REAL_KEY"); w.Code != http.StatusOK {
+		t.Fatalf("真值应可保存: %d %s", w.Code, w.Body.String())
+	}
+	got, _ = reg.Get("core.llm.sources.x.api_key")
+	if s, _ := got.(string); s != "NEW_REAL_KEY" {
+		t.Fatalf("真值保存失败: %q", s)
+	}
+
+	// ⑤ 相似但不全等的值不得被误杀（真 key 可能含任意字符）
+	for _, v := range []string{"•••", "••••••••X", "x••••••••", "••••••••••••••••"} {
+		if w := put(v); w.Code != http.StatusOK {
+			t.Errorf("值 %q 不该被当作占位符拒绝: %d %s", v, w.Code, w.Body.String())
+		}
+	}
+}
+
+// ★★★ **行为判据**：前端保存时**真的不会**把掩码回传。
+//
+// 为什么不能只看源码字符串（本会话反复踩的坑）：初版断言
+// "saveSetting 里出现 isSecretPlaceholderValue(inp.value)"，
+// 把条件改成 `if (false && isSecretPlaceholderValue(...))` 就绕过了 ——
+// 判据全绿而缺陷照样存在。这里把 dashboard.js 里的两个函数**抠出来真跑**
+// （用 node + 假 DOM/假 api），断言"发出去的请求体"里没有掩码。
+func TestDashboardSkipsPlaceholderOnSave(t *testing.T) {
+	node, err := exec.LookPath("node")
+	if err != nil {
+		t.Skip("本机无 node，跳过行为判据")
+	}
+	b, err := os.ReadFile("dashboard.js")
+	if err != nil {
+		t.Skipf("读不到 dashboard.js: %v", err)
+	}
+	src := string(b)
+
+	// 抠出需要的两个函数（按名字定位到下一个顶层 function/async function）
+	extract := func(name string) string {
+		// ★ 先试 async 版本：否则会把 `async function saveSetting(` 从
+		// "function saveSetting(" 处切开，丢掉 async 前缀 ⇒ await 语法错误。
+		i := strings.Index(src, "async function "+name+"(")
+		if i < 0 {
+			i = strings.Index(src, "function "+name+"(")
+		}
+		if i < 0 {
+			return ""
+		}
+		rest := src[i:]
+		// 找下一个顶层声明作为边界
+		best := -1
+		for _, marker := range []string{"\nasync function ", "\nfunction "} {
+			if j := strings.Index(rest[1:], marker); j >= 0 {
+				e := j + 1
+				if best < 0 || e < best {
+					best = e
+				}
+			}
+		}
+		if best > 0 {
+			return rest[:best]
+		}
+		return rest
+	}
+
+	phFn := extract("isSecretPlaceholderValue")
+	if phFn == "" {
+		t.Fatal("★ 缺少 isSecretPlaceholderValue（前端会把掩码当真值回传）")
+	}
+	saveFn := extract("saveSetting")
+	if saveFn == "" {
+		t.Fatal("找不到 saveSetting")
+	}
+
+	harness := `
+// ---- 假环境：只提供被抠出的两个函数需要的东西 ----
+var state = { meta: {}, settings: {} };
+var sent = [];
+function api(path, opts) { sent.push(JSON.parse(opts.body)); return Promise.resolve({status:"ok"}); }
+function toast() {}
+function __(a) { return a; }
+var INPUTS = {};
+var document = { getElementById: function(id) { return INPUTS[id] || null; } };
+
+` + phFn + "\n" + saveFn + `
+
+// ---- 用例 ----
+(async function () {
+  var out = [];
+  function mkInput(v) { return { value: v, style: {} }; }
+
+  // ① 掩码：必须**不发请求**
+  INPUTS["inp-core_llm_sources_x_api_key"] = mkInput("\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022");
+  sent.length = 0;
+  await saveSetting("core.llm.sources.x.api_key");
+  out.push(["mask", sent.length]);
+
+  // ② 真值：必须**发请求**且发的是真值
+  INPUTS["inp-core_llm_sources_x_api_key"] = mkInput("sk-real-value");
+  sent.length = 0;
+  await saveSetting("core.llm.sources.x.api_key");
+  out.push(["real", sent.length, sent[0] && sent[0].value]);
+
+  // ③ 含圆点的真值不得被误杀
+  INPUTS["inp-some_key"] = mkInput("a\u2022b");
+  sent.length = 0;
+  await saveSetting("some.key");
+  out.push(["dot", sent.length]);
+
+  // ④ 空值/普通值正常保存
+  INPUTS["inp-plain"] = mkInput("hello");
+  sent.length = 0;
+  await saveSetting("plain");
+  out.push(["plain", sent.length]);
+
+  console.log(JSON.stringify(out));
+})();
+`
+	tmp := filepath.Join(t.TempDir(), "h.js")
+	if err := os.WriteFile(tmp, []byte(harness), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	out, err := exec.Command(node, tmp).CombinedOutput()
+	if err != nil {
+		t.Fatalf("harness 执行失败: %v\n%s", err, out)
+	}
+	var got []interface{}
+	if err := json.Unmarshal(bytesTrim(out), &got); err != nil {
+		t.Fatalf("harness 输出无法解析: %v\n%s", err, out)
+	}
+	if len(got) != 4 {
+		t.Fatalf("harness 未跑完: %s", out)
+	}
+	get := func(i int) []interface{} { return got[i].([]interface{}) }
+
+	// ① 掩码：0 次请求
+	if n := get(0)[1].(float64); n != 0 {
+		t.Errorf("★ 掩码被回传了（发了 %v 次请求）—— 真值会被掩码覆盖", n)
+	}
+	// ② 真值：发 1 次且值正确
+	r := get(1)
+	if len(r) < 3 || r[1].(float64) != 1 {
+		t.Fatalf("★ 真值应正常保存，实际: %v", r)
+	}
+	if r[2].(string) != "sk-real-value" {
+		t.Errorf("★ 保存的值不对: %v", r[2])
+	}
+	// ③ 含圆点的真值不得误杀
+	if n := get(2)[1].(float64); n != 1 {
+		t.Errorf("★ 含圆点的真值被误杀（%v 次请求）", n)
+	}
+	// ④ 普通值正常
+	if n := get(3)[1].(float64); n != 1 {
+		t.Errorf("普通值未保存: %v", n)
+	}
+}
+
+func bytesTrim(b []byte) []byte {
+	i := strings.IndexByte(string(b), '{')
+	if i < 0 {
+		return b
+	}
+	j := strings.LastIndexByte(string(b), '}')
+	if j < i {
+		return b
+	}
+	return b[i : j+1]
+}
diff --git a/internal/recovery/recovery.go b/internal/recovery/recovery.go
index e68e0b33..35928b46 100644
--- a/internal/recovery/recovery.go
+++ b/internal/recovery/recovery.go
@@ -1,6 +1,7 @@
 // Package recovery 实现 L1 failback 的确定性恢复梯子与 guard↔worker 之间的
 // 恢复任务/结果文件协议。整个梯子无 token 消耗（除 rescue 源 QuickChat 复检外）：
-//   probe(main 可达) → 还原 DNS/proxy → probe → 还原 config 快照+ReloadFromConfig → probe
+//
+//	probe(main 可达) → 还原 DNS/proxy → probe → 还原 config 快照+ReloadFromConfig → probe
 package recovery
 
 import (
@@ -79,12 +80,12 @@ func LoadTask(path string) (*Task, error) {
 type Result struct {
 	Attempt        int       `json:"attempt"`
 	Success        bool      `json:"success"`
-	Cause          string    `json:"cause"`            // 判定出的根因类（取 diag / 梯子命中）
-	NetworkOK      bool      `json:"network_ok"`       // 网络（resolv/hosts）是否与基线一致
-	RestoredNet    []string  `json:"restored_net"`     // 已还原的网络文件
-	ConfigRestored bool      `json:"config_restored"`  // 是否还原 LLM 配置快照
-	QuickChatOK    bool      `json:"quickchat_ok"`     // 最后用 rescue 源复检是否可达
-	Steps          []string  `json:"steps"`            // 走过的恢复步骤
+	Cause          string    `json:"cause"`           // 判定出的根因类（取 diag / 梯子命中）
+	NetworkOK      bool      `json:"network_ok"`      // 网络（resolv/hosts）是否与基线一致
+	RestoredNet    []string  `json:"restored_net"`    // 已还原的网络文件
+	ConfigRestored bool      `json:"config_restored"` // 是否还原 LLM 配置快照
+	QuickChatOK    bool      `json:"quickchat_ok"`    // 最后用 rescue 源复检是否可达
+	Steps          []string  `json:"steps"`           // 走过的恢复步骤
 	Message        string    `json:"message"`
 	Timestamp      time.Time `json:"timestamp"`
 }
@@ -106,12 +107,12 @@ type ConfigRestorer func() (int, error)
 
 // Ladder 确定性恢复梯子。
 type Ladder struct {
-	ResultFile      string
-	Attempt         int
-	Probe           Prober
-	RestoreNetwork  NetworkRestorer
-	RestoreConfig   ConfigRestorer
-	Log             func(format string, args ...interface{})
+	ResultFile     string
+	Attempt        int
+	Probe          Prober
+	RestoreNetwork NetworkRestorer
+	RestoreConfig  ConfigRestorer
+	Log            func(format string, args ...interface{})
 }
 
 // Run 执行一次恢复梯子并返回结论（同时持久化到 ResultFile）。错误仅表示梯子
@@ -230,4 +231,4 @@ func SortSteps(s []string) []string {
 	copy(out, s)
 	sort.Strings(out)
 	return out
-}
\ No newline at end of file
+}
diff --git a/internal/recovery/recovery_test.go b/internal/recovery/recovery_test.go
index 2a8f9cf4..48f0c46d 100644
--- a/internal/recovery/recovery_test.go
+++ b/internal/recovery/recovery_test.go
@@ -143,9 +143,9 @@ func TestLadderExhausted(t *testing.T) {
 	p.set("after-network", false)
 	p.set("after-config", false)
 	l := &Ladder{
-		ResultFile: ResultPath(dir),
-		Attempt:    1,
-		Probe:      p.probe,
+		ResultFile:     ResultPath(dir),
+		Attempt:        1,
+		Probe:          p.probe,
 		RestoreNetwork: func() ([]string, error) { return nil, nil },
 		RestoreConfig:  func() (int, error) { return 0, nil },
 	}
diff --git a/internal/safeclose/close_discipline_test.go b/internal/safeclose/close_discipline_test.go
new file mode 100644
index 00000000..f86a73b0
--- /dev/null
+++ b/internal/safeclose/close_discipline_test.go
@@ -0,0 +1,274 @@
+package safeclose_test
+
+// **close 纪律**判据（2026-10-17）。
+//
+// ## 纪律
+//
+// 全仓**除本包之外**，不得出现裸 `close(ch)`（chan 类型）。
+// 一律走 `safeclose.Safe(&once, ch)` 或 `safeclose.SafeFunc(ch)`。
+//
+// ## 为什么这条必须存在（用户要求 + 实测事故）
+//
+// 实测崩溃（真机 SIGTERM）：
+//
+//	panic: close of closed channel
+//	main.startHeartbeat.func3()  bootstrap.go:259
+//
+// 根因是有两个调用点。用户明确指出要求：
+//
+//	「只要调 close 就需要前置检查，这是为了避免未来更新的意外修改」
+//
+// 这个要求的关键在**"未来"**：今天只在退出时调一次的代码，明天加一条
+// 错误/超时/重连路径就变成两次 —— 而那次改动看起来与 close 无关，
+// 代码评审不会注意。所以不能靠"逐处判断当前是否安全"，必须**统一入口**。
+//
+// ## 为什么是 AST 判据而不是字符串搜索
+//
+// 字符串 `close(` 会命中注释、字符串字面量、以及 `f.Close()` /
+// `conn.Close()` 这类完全不同的调用。
+// 本仓反复吃过"源码字符串检查骗人"的亏（见
+// docs/zh/kernel-modularization-design.md §8.6）。AST 能精确判定：
+//   · 调用名恰为 `close`
+//   · 实参的类型是 channel（用类型信息或至少排除 selector 形式）
+// 并**自动跳过注释**。
+
+import (
+	safeclose "github.com/JianFeeeee/HomeAgent/internal/safeclose"
+
+	"regexp"
+
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// allowlist 是**明确允许**裸 close 的位置，每条都要写清理由。
+//
+// ★ 加白名单的门槛：必须论证"该 channel 在语言层面不可能被关两次"，
+//
+//	而不是"目前只调一次"（后者正是未来会被改坏的那种）。
+var allowlist = map[string]string{
+	// 本包自身：Safe 的实现就是那个唯一的 close。
+	"internal/safeclose/safeclose.go": "本包是统一的关闭入口，close 就在这里",
+}
+
+// ★★★ 判据：全仓不得有裸 close(chan)。
+func TestNoBareCloseOutsideSafeclose(t *testing.T) {
+	root := filepath.Join("..", "..")
+	var violations []string
+
+	err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return nil
+		}
+		if info.IsDir() {
+			base := info.Name()
+			// 跳过依赖目录与产物目录
+			switch base {
+			case ".git", "node_modules", "dist", "build", "third_party", "vendor", ".go":
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		rel, _ := filepath.Rel(root, path)
+		rel = filepath.ToSlash(rel)
+		if _, ok := allowlist[rel]; ok {
+			return nil
+		}
+		// 只查本仓模块内（排除 module cache 之类）
+		if strings.Contains(rel, "/.go/") {
+			return nil
+		}
+
+		fset := token.NewFileSet()
+		f, perr := parser.ParseFile(fset, path, nil, 0) // 不带 ParseComments ⇒ 注释天然被跳过
+		if perr != nil {
+			return nil
+		}
+		ast.Inspect(f, func(n ast.Node) bool {
+			call, ok := n.(*ast.CallExpr)
+			if !ok {
+				return true
+			}
+			// 必须是内建 close：Fun 是 Ident 且名为 close
+			id, ok := call.Fun.(*ast.Ident)
+			if !ok || id.Name != "close" {
+				return true
+			}
+			pos := fset.Position(call.Pos())
+			violations = append(violations, rel+":"+itoa(pos.Line))
+			return true
+		})
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("遍历失败: %v", err)
+	}
+
+	if len(violations) > 0 {
+		t.Fatalf("★ 发现 %d 处**裸 close(chan)** —— 违反 close 纪律：\n  %s\n\n"+
+			"为什么必须改（用户明确要求）：\n"+
+			"  今天只调一次的 close，明天加一条错误/超时/重连路径就变成两次，\n"+
+			"  而那次改动看起来与 close 无关，评审不会注意 ⇒ 退出路径 panic\n"+
+			"  （实测：panic: close of closed channel ⇒ 退出码 0 变 2 ⇒\n"+
+			"   systemd 判成异常退出并重启，而功能本身正常）。\n\n"+
+			"修法：\n"+
+			"  var once sync.Once                       // 局部 channel\n"+
+			"  return func() { safeclose.Safe(&once, ch) }\n\n"+
+			"  // 或结构体字段\n"+
+			"  type T struct { done chan struct{}; doneOnce sync.Once }\n"+
+			"  func (t *T) Close() { safeclose.Safe(&t.doneOnce, t.done) }\n\n"+
+			"  // 或直接交出幂等 stop 函数\n"+
+			"  return safeclose.SafeFunc(ch)\n",
+			len(violations), strings.Join(violations, "\n  "))
+	}
+}
+
+// ★★★ 判据：`Safe` 自身必须真的幂等（行为判据，守核心语义）。
+func TestSafeIsIdempotent(t *testing.T) {
+	// 不能 import 自身包再测（会循环）；这里用 SafeFunc 走公开 API
+	ch := make(chan struct{})
+	stop := safeclose.SafeFunc(ch)
+
+	// 连关 5 次，不得 panic
+	for i := 0; i < 5; i++ {
+		stop()
+	}
+	// 已关闭：读应立刻返回
+	select {
+	case <-ch:
+	default:
+		t.Fatal("channel 应已关闭")
+	}
+}
+
+// ★★★ 判据：**并发**关闭安全（select 写法在这一条上会挂）。
+//
+// 这条正是"为什么不能用 select 前置检查"的证明：
+// 两个 goroutine 同时落到 default ⇒ 都 close ⇒ panic。
+func TestSafeConcurrentClose(t *testing.T) {
+	for round := 0; round < 200; round++ {
+		ch := make(chan struct{})
+		once := safeclose.NewOnceForTest()
+		done := make(chan struct{}, 8)
+		for i := 0; i < 8; i++ {
+			go func() {
+				safeclose.Safe(once, ch)
+				done <- struct{}{}
+			}()
+		}
+		for i := 0; i < 8; i++ {
+			<-done
+		}
+	}
+}
+
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	var b []byte
+	for n > 0 {
+		b = append([]byte{byte('0' + n%10)}, b...)
+		n /= 10
+	}
+	return string(b)
+}
+
+// reSelfOnce 匹配 `xxx.Do(func()` 形态（取 once 变量名）。
+// reSelfOnce 匹配 `recv.onceName.Do(func()` 并取出**完整**接收者表达式
+// （含点号）—— 这是上一版判据的 bug：`\w+` 不含 `.`，`p.stopOnce.Do` 只捕到
+// `p`，于是与内层的 `Safe(&p.stopOnce` 比对永远不命中 ⇒ 判据假绿
+// （变异改回自锁后仍然 PASS，实测发现）。
+var reSelfOnce = regexp.MustCompile(`^([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\.Do\(func\(\)`)
+
+// ★★★★ 判据：**禁止自锁的 Once 嵌套**（`X.Do` 内部再 `Safe(&X)`）。
+//
+// ## 为什么必须有这条（我方实测事故）
+//
+// 我把 37 处裸 close 改成 safeclose 时，有两处写成：
+//
+//	p.stopOnce.Do(func() {
+//		safeclose.Safe(&p.stopOnce, p.stopCh)   // ← 同一把 Once
+//		...
+//	})
+//
+// `sync.Once` **不可重入**：外层 Do 已持标记/互斥，内层 Do 等同一把锁
+// ⇒ **自锁死锁**。实测后果极隐蔽：
+//
+//	· `go test` 不报错，只是**挂住**（600s 超时，3 个包同时超时）
+//	· 栈里只看到 `sync.(*Once).Do` 嵌套 —— 不指向"哪里写错了"
+//	· 而单跑那个测试才勉强看得出（还是超时，没有明确信息）
+//
+// 正确做法：close 的守卫用**独立的** once 字段（如 `stopChOnce`），
+// 或干脆不要在 Once 里再调 Safe（裸 close 即可，因为外层 Once 已保护）。
+//
+// 判据形态：AST/文本混合扫描 —— 找 `X.Do(func()` 之后 30 行内出现
+// `Safe(&X`。这是"危险模式存在性"，源码扫描恰当（不是接线断言）。
+func TestNoNestedSelfOnceDeadlock(t *testing.T) {
+	root := filepath.Join("..", "..")
+	var bad []string
+
+	_ = filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return nil
+		}
+		if info.IsDir() {
+			switch info.Name() {
+			case ".git", "node_modules", "dist", "build", "third_party", "vendor", ".go":
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		rel, _ := filepath.Rel(root, path)
+		if strings.Contains(filepath.ToSlash(rel), "/.go/") {
+			return nil
+		}
+		b, rerr := os.ReadFile(path)
+		if rerr != nil {
+			return nil
+		}
+		lines := strings.Split(string(b), "\n")
+		for i, ln := range lines {
+			trim := strings.TrimSpace(ln)
+			if strings.HasPrefix(trim, "//") {
+				continue
+			}
+			m := reSelfOnce.MatchString(trim)
+			if !m {
+				continue
+			}
+			once := reSelfOnce.FindStringSubmatch(trim)[1]
+			for j := i; j < len(lines) && j < i+30; j++ {
+				if strings.HasPrefix(strings.TrimSpace(lines[j]), "//") {
+					continue
+				}
+				if strings.Contains(lines[j], "safeclose.Safe(&"+once) {
+					bad = append(bad, filepath.ToSlash(rel)+":"+itoa(i+1)+
+						"  ("+once+".Do 内部 Safe(&"+once+"))")
+					break
+				}
+			}
+		}
+		return nil
+	})
+
+	if len(bad) > 0 {
+		t.Fatalf("★ 发现 %d 处 **Once 自锁死锁**：\n  %s\n\n"+
+			"sync.Once 不可重入 ⇒ 外层 Do 持锁、内层 Do 等同一把锁 ⇒ 永久挂住\n"+
+			"（实测：go test 600s 超时，栈只显示 sync.(*Once).Do 嵌套，难定位）。\n\n"+
+			"修法：close 的守卫用**独立**的 once：\n"+
+			"  p.stopOnce.Do(func() { safeclose.Safe(&p.stopChOnce, p.stopCh) })\n",
+			len(bad), strings.Join(bad, "\n  "))
+	}
+}
diff --git a/internal/safeclose/export_test.go b/internal/safeclose/export_test.go
new file mode 100644
index 00000000..010404a0
--- /dev/null
+++ b/internal/safeclose/export_test.go
@@ -0,0 +1,7 @@
+package safeclose
+
+import "sync"
+
+// newOnce 仅供测试构造（同包外无法直接 new(sync.Once) 吗？其实可以，
+// 这里保留一个显式入口让测试可读）。
+func NewOnceForTest() *sync.Once { return &sync.Once{} }
diff --git a/internal/safeclose/safeclose.go b/internal/safeclose/safeclose.go
new file mode 100644
index 00000000..bab6c8eb
--- /dev/null
+++ b/internal/safeclose/safeclose.go
@@ -0,0 +1,83 @@
+// Package safeclose 提供**幂等**的 channel 关闭。
+//
+// ## 为什么需要它（本仓实测事故）
+//
+// 2026-10-17 真机 SIGTERM 实测崩溃：
+//
+//	panic: close of closed channel
+//	main.startHeartbeat.func3()  bootstrap.go:259
+//	main.main()                  main.go:293
+//
+// 根因：`startHeartbeat` 返回的 stop 是**裸的 `close(hbStop)`**，而它有
+// **两个调用点**（`main.go` 的 `defer` + `waitForShutdown` 的显式调用）
+// ⇒ 第二次 close 必然 panic。
+//
+// 危害形态很特殊：它崩在**退出路径的最后一步** —— 清理全做完了才崩 ⇒
+// 退出码 0 → 2（panic）⇒ systemd/guard 判成"异常退出"并触发**不必要的
+// 重启/告警**，而功能本身完全正常，排查方向会被引向"哪里崩了"。
+//
+// ## 为什么"前置检查"必须是**统一纪律**而不是逐处判断
+//
+// 全仓有 37 处 `close(chan)`。逐处人工判断"这里会不会被调两次"是**不可持续**的：
+//
+//	· 今天只被调一次，明天加一条错误路径就变成两次 —— 而那次改动看起来
+//	  与 close 无关，评审不会注意；
+//	· 并发场景下 `select { case <-ch: default: close(ch) }` **也不安全**
+//	  （两个 goroutine 可同时落到 default，然后都 close）；
+//	· 判断依据往往是"隐式的"（这个函数只在退出时调一次），这种隐式前提
+//	  正是未来修改最容易破坏的东西。
+//
+// ⇒ 所以本包把"幂等"做成**唯一入口**：只要调 close 就走 Safe，
+//
+//	Safe 自带 `sync.Once`。新增的关闭路径无论怎么加，都不会 panic。
+//
+// ## 用法
+//
+//	// 方式一：就地声明 once（局部 channel、闭包返回值等）
+//	var once sync.Once
+//	return func() { safeclose.Safe(&once, hbStop) }
+//
+//	// 方式二：结构体里持有 once 字段（生命周期长的 channel）
+//	type Foo struct { done chan struct{}; doneOnce sync.Once }
+//	func (f *Foo) Close() { safeclose.Safe(&f.doneOnce, f.done) }
+//
+// ★ 判据 `internal/safeclose/close_discipline_test.go` 会强制：
+//
+//	除本包之外，全仓**不得**出现裸 `close(chan)`。
+package safeclose
+
+import "sync"
+
+// Safe 幂等关闭 ch。第二次及以后的调用是 no-op。
+//
+// 返回 true 表示**本次真的执行了** close（首次调用），false 表示已被关闭过。
+//
+// ## 为什么用 sync.Once 而不是 `select { case <-ch: default: close(ch) }`
+//
+// select 写法在**并发**下不安全：两个 goroutine 都可能是"未关闭"，
+// 都落到 default，然后都执行 close ⇒ 第二次 panic。
+// （实测过这种形态：`healthcheck` 的 `Stop()` 就是用 select 判的，
+//
+//	单线程安全，但若将来 Stop 被并发调用就会炸。）
+//
+// sync.Once 是真正原子的：Do 内部由 runtime 保证只有一个执行者。
+func Safe[T any](once *sync.Once, ch chan T) bool {
+	if once == nil || ch == nil {
+		return false
+	}
+	fired := false
+	once.Do(func() {
+		fired = true
+		close(ch)
+	})
+	return fired
+}
+
+// SafeFunc 返回一个幂等的关闭函数（适合作为 stop 回调直接交出）。
+//
+//	go func() { ... case <-stop: return ... }()
+//	return safeclose.SafeFunc(hbStop)
+func SafeFunc[T any](ch chan T) func() {
+	var once sync.Once
+	return func() { Safe(&once, ch) }
+}
diff --git a/internal/sdk/e2e_embedded_pi_test.go b/internal/sdk/e2e_embedded_pi_test.go
new file mode 100644
index 00000000..7f016d87
--- /dev/null
+++ b/internal/sdk/e2e_embedded_pi_test.go
@@ -0,0 +1,76 @@
+package sdk
+
+import (
+	"archive/zip"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// ★★★ 最终 e2e：真实 commondev 包装出的 hmap → 解包 → 内嵌 node 跑内嵌 pi。
+func TestCommondevEmbeddedPiRuns(t *testing.T) {
+	// 显式开关：这条判据要读一个真实构建出的 .hmap（内嵌 node+pi，约 100MB）。
+	// 它不进版本库（dist/ 被忽略），所以默认跳过；验证内嵌能力时显式打开：
+	//   HA_RAWFILE_E2E_HMAP=<path> go test -run TestCommondevEmbeddedPiRuns ./internal/sdk/
+	src := os.Getenv("HA_RAWFILE_E2E_HMAP")
+	if src == "" {
+		t.Skip("设 HA_RAWFILE_E2E_HMAP=<hmap路径> 以运行（需要先构建 commondev bundle）")
+	}
+	if _, err := os.Stat(src); err != nil {
+		t.Fatalf("HA_RAWFILE_E2E_HMAP 指向的文件不存在: %v", err)
+	}
+	dir := t.TempDir()
+	zr, err := zip.OpenReader(src)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer zr.Close()
+	for _, f := range zr.File {
+		p := filepath.Join(dir, f.Name)
+		if strings.HasSuffix(f.Name, "/") {
+			os.MkdirAll(p, 0o755)
+			continue
+		}
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		rc, _ := f.Open()
+		mode := f.Mode()
+		if mode == 0 {
+			mode = 0o644
+		}
+		out, _ := os.OpenFile(p, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, mode)
+		buf := make([]byte, 1<<20)
+		for {
+			n, rerr := rc.Read(buf)
+			if n > 0 {
+				out.Write(buf[:n])
+			}
+			if rerr != nil {
+				break
+			}
+		}
+		rc.Close()
+		out.Close()
+	}
+
+	rf := NewRawFilesAPI(dir)
+	if !rf.Exists("node/bin/node") {
+		t.Fatal("node 未在预期路径")
+	}
+	node := filepath.Join(rf.Dir(), "node/bin/node")
+	pi := filepath.Join(rf.Dir(), "pi/node_modules/@earendil-works/pi-coding-agent/dist/cli.js")
+	if _, err := os.Stat(pi); err != nil {
+		t.Fatal("pi 未在预期路径")
+	}
+	out, err := exec.Command(node, pi, "--version").CombinedOutput()
+	if err != nil {
+		t.Fatalf("★ 内嵌 pi 跑不起来: %v\n%s", err, out)
+	}
+	t.Logf("内嵌 pi --version = %q", strings.TrimSpace(string(out)))
+	if strings.TrimSpace(string(out)) == "" {
+		t.Error("版本输出为空")
+	}
+}
diff --git a/internal/sdk/memory.go b/internal/sdk/memory.go
index 6eaae0eb..31152fa2 100644
--- a/internal/sdk/memory.go
+++ b/internal/sdk/memory.go
@@ -9,8 +9,9 @@ import (
 // MemoryBlockView 是块的最小只读视图（供星图轮询端点）。
 //
 // ★ 不直接用 memory.MemoryBlock：那是内核内部类型，而本包是**插件边界**。
-//   SDK 接口只暴露端点真正要用的字段（原来是先 GraphData 全量再转成
-//   graphBlockView 做同样的事，只是绕了一圈）。
+//
+//	SDK 接口只暴露端点真正要用的字段（原来是先 GraphData 全量再转成
+//	graphBlockView 做同样的事，只是绕了一圈）。
 type MemoryBlockView struct {
 	ID        string    `json:"id"`
 	Modality  string    `json:"modality"`
diff --git a/internal/sdk/plugin.go b/internal/sdk/plugin.go
index 1389118b..d249653c 100644
--- a/internal/sdk/plugin.go
+++ b/internal/sdk/plugin.go
@@ -128,6 +128,11 @@ type PluginManager interface {
 	IsBuiltinPlugin(name string) bool
 	DisablePlugin(name, by string) error
 	EnablePlugin(name string) error
+	// StopPlugin/StartPlugin 是**运行态**启停（设计 §2.6.7.3/2.6.7.4）：
+	// 只改运行状态，不写 disabled_plugins。与 Disable/Enable（持久态）分开。
+	StopPlugin(name string) error
+	StartPlugin(name string) error
+	IsPluginRuntimeStopped(name string) bool
 	// RemovePlugin 卸载插件：先停止（stop handlers + Stop），再执行插件注册的
 	// onRemove 回调（RegisterOnRemoveHandler），最后从注册表移除并清理配置表。
 	// 目录删除由调用方负责。
@@ -303,6 +308,8 @@ type SDKConfig struct {
 	Knowledge      KnowledgeAPI
 	LLM            LLMAPI
 	Settings       SettingsAPI
+	Secrets        pubsdk.SecretsAPI
+	RawFiles       pubsdk.RawFilesAPI
 	RegTool        ToolRegistrar
 	RegStage       StageRegistrar
 	RegAPI         APIRegistrar
@@ -323,6 +330,12 @@ type SDKConfig struct {
 
 func New(name string, cfg SDKConfig) *PluginSDK {
 	base := pubsdk.New(name, cfg.Settings, cfg.RegTool, cfg.RegStage, cfg.RegAPI, cfg.RegOutput)
+	if cfg.Secrets != nil {
+		base.SetSecretsAPI(cfg.Secrets)
+	}
+	if cfg.RawFiles != nil {
+		base.SetRawFilesAPI(cfg.RawFiles)
+	}
 	// 反代声明收集：内置插件（无 plugin.json）在 Start 里用 RegisterProxy
 	// 声明自己的服务，落到本包的登记表；外部插件走 plugin.json 自动发现。
 	base.SetProxyRegistrar(func(svc string, d pubsdk.ProxyDef) { RegisterBuiltinProxy(name, svc, d) })
diff --git a/internal/sdk/rawfiles_impl.go b/internal/sdk/rawfiles_impl.go
new file mode 100644
index 00000000..b55f283b
--- /dev/null
+++ b/internal/sdk/rawfiles_impl.go
@@ -0,0 +1,138 @@
+package sdk
+
+// RawFilesAPI 的内核实现：读写随包分发的 rawfile 资源。
+//
+// ## 目录约定（与 hmapdev 的打包规则对齐）
+//
+//	<插件目录>/rawfile/          ← 包内资源（只读，随升级整体替换）
+//	<插件目录>/work/             ← 运行期可写目录（跨升级保留）
+//
+// hmapdev 把工程根 `rawfile/` 的内容与 plg.json 声明的外部路径
+// 统一打成 `rawfile/<相对路径>` 条目；内核解包保留路径 ⇒ 落到此处。
+//
+// ## 为什么只读目录与可写目录必须分开
+//
+// 升级时会用新包**整体替换**插件目录。若运行期数据也写在 rawfile/ 下，
+// 升级就会静默丢掉它们；反过来，若把包内资源写到可写目录，
+// 升级后新旧资源混在一起、无法判断哪份是当前的。
+//
+// ## 安全：路径穿越必须挡住
+//
+// 资源路径来自插件（可能受 LLM 影响）。不管的话 `../../../../etc/shadow`
+// 就能读任意文件 —— 而包是可被第三方替换的，这构成一条真实提权链。
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
+)
+
+// RawFilesDirName 是包内资源目录名（与 hmapdev 的 RawFilesPrefix 一致）。
+const RawFilesDirName = "rawfile"
+
+// WorkDirName 是可写目录名。
+const WorkDirName = "work"
+
+type rawFilesImpl struct {
+	root    string // <插件目录>/rawfile
+	workDir string // <插件目录>/work
+}
+
+// NewRawFilesAPI 构造资源读取接口。pluginDir 是插件自己的安装目录。
+func NewRawFilesAPI(pluginDir string) pubsdk.RawFilesAPI {
+	return &rawFilesImpl{
+		root:    filepath.Join(pluginDir, RawFilesDirName),
+		workDir: filepath.Join(pluginDir, WorkDirName),
+	}
+}
+
+// resolve 把相对路径解析成绝对路径，并**拒绝穿越**。
+func (r *rawFilesImpl) resolve(rel string) (string, error) {
+	rel = strings.TrimSpace(rel)
+	if rel == "" {
+		return "", fmt.Errorf("rawfile 路径不能为空")
+	}
+	if filepath.IsAbs(rel) {
+		return "", fmt.Errorf("rawfile 路径必须是相对路径: %q", rel)
+	}
+	// 先清理，再验证结果仍在 root 之内 —— 只查 ".." 字符串是不够的
+	//（`a/../../b` 不含字面 `..` 前缀却会逃出去）。
+	clean := filepath.Clean(filepath.Join(r.root, rel))
+	if clean != r.root && !strings.HasPrefix(clean, r.root+string(os.PathSeparator)) {
+		return "", fmt.Errorf("rawfile 路径逃出资源目录: %q", rel)
+	}
+	return clean, nil
+}
+
+func (r *rawFilesImpl) Read(rel string) ([]byte, error) {
+	p, err := r.resolve(rel)
+	if err != nil {
+		return nil, err
+	}
+	b, err := os.ReadFile(p)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, fmt.Errorf("rawfile 不存在: %s（打包时是否漏了 rawfile/ 或 plg.json 的 rawfiles？）", rel)
+		}
+		return nil, err
+	}
+	return b, nil
+}
+
+func (r *rawFilesImpl) List(rel string) ([]string, error) {
+	// ★ 空串 = 资源根目录（列出 rawfile/ 的直接子项）。
+	// 其他方法不接受空串（读一个目录没有意义），但 List 的语义天然包含根。
+	if strings.TrimSpace(rel) == "" {
+		entries, err := os.ReadDir(r.root)
+		if err != nil {
+			return nil, fmt.Errorf("rawfile 根目录不可读（插件是否带随包资源？）: %w", err)
+		}
+		return dirNames(entries), nil
+	}
+	p, err := r.resolve(rel)
+	if err != nil {
+		return nil, err
+	}
+	entries, err := os.ReadDir(p)
+	if err != nil {
+		return nil, err
+	}
+	return dirNames(entries), nil
+}
+
+// dirNames 把目录项转成"单层名 + 目录带 / 后缀"的列表（固定排序）。
+func dirNames(entries []os.DirEntry) []string {
+	out := make([]string, 0, len(entries))
+	for _, e := range entries {
+		name := e.Name()
+		if e.IsDir() {
+			name += "/"
+		}
+		out = append(out, name)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func (r *rawFilesImpl) Exists(rel string) bool {
+	p, err := r.resolve(rel)
+	if err != nil {
+		return false
+	}
+	st, err := os.Stat(p)
+	return err == nil && !st.IsDir()
+}
+
+func (r *rawFilesImpl) Dir() string { return r.root }
+
+// WorkDir 返回可写目录（惰性创建）。
+func (r *rawFilesImpl) WorkDir() string {
+	_ = os.MkdirAll(r.workDir, 0o755)
+	return r.workDir
+}
+
+var _ pubsdk.RawFilesAPI = (*rawFilesImpl)(nil)
diff --git a/internal/sdk/rawfiles_impl_test.go b/internal/sdk/rawfiles_impl_test.go
new file mode 100644
index 00000000..d47f7516
--- /dev/null
+++ b/internal/sdk/rawfiles_impl_test.go
@@ -0,0 +1,166 @@
+package sdk
+
+// RawFilesAPI 内核侧实现的判据。
+//
+// 重点：**路径穿越必须挡住**（资源路径来自插件，可能受 LLM 影响），
+// 以及只读资源目录与可写工作目录必须分开。
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// mkPluginDir 造一个带 rawfile/ 的插件目录。
+func mkPluginDir(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	for rel, content := range map[string]string{
+		"rawfile/main/prompt.txt":    "you are a dev",
+		"rawfile/main/sub/data.json": `{"k":1}`,
+		"rawfile/bin/node":           "#!/bin/sh\necho node",
+	} {
+		p := filepath.Join(dir, rel)
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		mode := os.FileMode(0o644)
+		if strings.HasSuffix(rel, "/node") {
+			mode = 0o755
+		}
+		if err := os.WriteFile(p, []byte(content), mode); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return dir
+}
+
+// ★ 判据：读包内资源。
+func TestRawFilesRead(t *testing.T) {
+	rf := NewRawFilesAPI(mkPluginDir(t))
+	b, err := rf.Read("main/prompt.txt")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(b) != "you are a dev" {
+		t.Errorf("内容不对: %q", b)
+	}
+	// 嵌套路径
+	if _, err := rf.Read("main/sub/data.json"); err != nil {
+		t.Errorf("嵌套路径读不到: %v", err)
+	}
+	if !rf.Exists("bin/node") {
+		t.Error("Exists 应报 true")
+	}
+	if rf.Exists("bin/nope") {
+		t.Error("不存在的应报 false")
+	}
+}
+
+// ★★ 判据：不存在的资源要给出**可执行**的提示（而不是裸 ENOENT）。
+//
+// 症状常见于"打包时漏了 rawfile/"——裸 ENOENT 会让人去查代码而不是查 plg.json。
+func TestRawFilesMissingGivesHint(t *testing.T) {
+	rf := NewRawFilesAPI(mkPluginDir(t))
+	_, err := rf.Read("nope.txt")
+	if err == nil {
+		t.Fatal("不存在的资源应报错")
+	}
+	if !strings.Contains(err.Error(), "rawfile") {
+		t.Errorf("错误信息应提到 rawfile（提示可能漏打包）: %v", err)
+	}
+}
+
+// ★★★ 判据：**路径穿越必须挡住**。
+//
+// 资源路径来自插件（可能受 LLM 影响）。不挡的话 `../../../../etc/passwd`
+// 就能读任意文件 —— 而包是可被第三方替换的，这构成一条真实提权链。
+//
+// ★ 必须用**真实存在的**逃逸目标：否则实现会因"文件不存在"报错，
+// 判据通过但那不是因为安全检查（本仓实测踩过这个坑，见 hmapdev 的同类判据）。
+func TestRawFilesRejectsPathTraversal(t *testing.T) {
+	dir := mkPluginDir(t)
+	// 在插件目录**外面**放一个真实文件当逃逸目标
+	outside := filepath.Join(filepath.Dir(dir), "outside-secret.txt")
+	if err := os.WriteFile(outside, []byte("REDACTED"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Remove(outside)
+
+	rf := NewRawFilesAPI(dir)
+	// 从 rawfile/ 出发、真实指向外部的相对路径
+	rel, err := filepath.Rel(filepath.Join(dir, "rawfile"), outside)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, bad := range []string{
+		rel,                // 真实存在的逃逸目标
+		"../../etc/passwd", // 经典写法
+		"main/../../../outside-secret.txt",
+		"/etc/passwd", // 绝对路径
+		"..",
+	} {
+		if _, rerr := rf.Read(bad); rerr == nil {
+			t.Errorf("★ 路径穿越未被拒绝: %q", bad)
+			continue
+		} else if !strings.Contains(rerr.Error(), "逃出") && !strings.Contains(rerr.Error(), "相对路径") {
+			t.Errorf("拒绝 %q 的理由不对（应为逃逸/相对路径，实际: %v）", bad, rerr)
+		}
+	}
+	// 合法路径仍要能读
+	if _, err := rf.Read("main/prompt.txt"); err != nil {
+		t.Errorf("合法路径被误挡: %v", err)
+	}
+}
+
+// ★ 判据：List 返回单层名，目录带 `/` 后缀。
+func TestRawFilesList(t *testing.T) {
+	rf := NewRawFilesAPI(mkPluginDir(t))
+	names, err := rf.List("main")
+	if err != nil {
+		t.Fatal(err)
+	}
+	joined := strings.Join(names, ",")
+	if !strings.Contains(joined, "prompt.txt") {
+		t.Errorf("缺 prompt.txt: %v", names)
+	}
+	if !strings.Contains(joined, "sub/") {
+		t.Errorf("目录应带 / 后缀: %v", names)
+	}
+	// 根目录
+	root, err := rf.List("")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(strings.Join(root, ","), "main/") {
+		t.Errorf("根列出错: %v", root)
+	}
+}
+
+// ★★ 判据：**只读资源目录与可写工作目录必须分开**。
+//
+// 混在一起的话，升级时整体替换插件目录会静默丢掉运行期数据；
+// 反过来资源写进可写目录会与旧版本残留混淆。
+func TestRawFilesDirAndWorkDirAreSeparate(t *testing.T) {
+	dir := mkPluginDir(t)
+	rf := NewRawFilesAPI(dir)
+	if rf.Dir() == rf.WorkDir() {
+		t.Fatal("★ 资源目录与工作目录不能是同一个")
+	}
+	if !strings.HasSuffix(rf.Dir(), "rawfile") {
+		t.Errorf("资源目录应以 rawfile 结尾: %s", rf.Dir())
+	}
+	if !strings.HasSuffix(rf.WorkDir(), "work") {
+		t.Errorf("工作目录应以 work 结尾: %s", rf.WorkDir())
+	}
+	// WorkDir 应可写（惰性创建）
+	p := filepath.Join(rf.WorkDir(), "state.json")
+	if err := os.WriteFile(p, []byte("{}"), 0o644); err != nil {
+		t.Fatalf("工作目录不可写: %v", err)
+	}
+	// 资源目录里的东西不属于工作目录
+	if rf.Exists("work/state.json") {
+		t.Error("工作目录的文件不该出现在资源命名空间里")
+	}
+}
diff --git a/internal/sdk/secrets_impl.go b/internal/sdk/secrets_impl.go
new file mode 100644
index 00000000..36e31f20
--- /dev/null
+++ b/internal/sdk/secrets_impl.go
@@ -0,0 +1,111 @@
+package sdk
+
+// SecretsAPI 的内核实现：桥接到 `internal/security` 的进程级变量库。
+//
+// ## 为何是"桥接"而不是"另建一套"
+//
+// 变量库是**进程级单例**（`security.Global()`）：主/子/驻留子 agent 共享
+// 同一套别名表（设计 S10）。插件若自建一套，两库互不可见 ——
+// 内核拦截时登记的变量插件看不到，插件登记的拦截又不认识，
+// 同一个凭据可能两处各存一份而使用者不知哪个权威。
+//
+// 所以这个实现只是把调用转发到那个单例。**没有第二份存储**。
+//
+// ## 未启用时的行为
+//
+// `security.Global()` 为 nil 时**不返回 nil**，而是返回一个 Available()
+// 为 false 的实现。理由：nil 会让插件到处判空，而判空漏一处就 panic
+// （本仓在 `*SensitiveInterceptor` 上吃过这个亏）。给一个明确的
+// "不可用" 实现，插件只需问 `Available()`。
+
+import (
+	"fmt"
+
+	internalSecurity "github.com/JianFeeeee/HomeAgent/internal/security"
+	pubsdk "github.com/JianFeeeee/homeagentsdk/sdk"
+)
+
+// secretsImpl 实现 pubsdk.SecretsAPI。
+type secretsImpl struct{}
+
+// NewSecretsAPI 构造变量库接口（内核装配时注入给每个插件）。
+func NewSecretsAPI() pubsdk.SecretsAPI { return &secretsImpl{} }
+
+func (s *secretsImpl) Available() bool { return internalSecurity.Global() != nil }
+
+// AvailableForRPC 是 proc 桥用来**明确报告**可用性的入口。
+//
+// ★ 为什么不能靠 List 推断：未启用时 List 返回空列表（**不报错**），
+// 于是"库是空的"与"库不存在"在 RPC 层长得一样 —— 实测踩到：
+// 插件的 Available() 误判为 true，接着 Store 才失败，错误信息变成
+// "存储失败"而不是"能力不可用"，排查时方向完全错。
+func (s *secretsImpl) AvailableForRPC() bool { return s.Available() }
+
+func (s *secretsImpl) Store(value, note string) (string, error) {
+	st := internalSecurity.Global()
+	if st == nil {
+		// ★ 响亮失败：不静默降级成"存到别处"或"不存"。
+		// 插件以为存好了而实际没存，比直接报错危险得多。
+		return "", fmt.Errorf("安全模块未启用（core.security.enabled=false），无法登记凭据")
+	}
+	return st.Submit(value, note)
+}
+
+func (s *secretsImpl) List() []pubsdk.SecretInfo {
+	st := internalSecurity.Global()
+	if st == nil {
+		return nil
+	}
+	infos := st.List()
+	out := make([]pubsdk.SecretInfo, len(infos))
+	for i, in := range infos {
+		out[i] = pubsdk.SecretInfo{
+			Alias: in.Alias, Source: in.Source, Note: in.Note,
+			CreatedAt: in.CreatedAt, UpdatedAt: in.UpdatedAt, Hits: in.Hits,
+		}
+	}
+	return out
+}
+
+func (s *secretsImpl) Forget(alias string) error {
+	st := internalSecurity.Global()
+	if st == nil {
+		return fmt.Errorf("安全模块未启用，变量库不可用")
+	}
+	return st.Forget(alias)
+}
+
+func (s *secretsImpl) Fill(text string) (string, int, []string) {
+	st := internalSecurity.Global()
+	if st == nil {
+		return text, 0, nil
+	}
+	return st.Fill(text)
+}
+
+func (s *secretsImpl) Encrypt(plain []byte) (string, error) {
+	c := internalSecurity.ConfigCodec()
+	if c == nil || !c.Enabled() {
+		// ★ 拒绝明文落盘：插件以为存的是密文而实际是明文，是最危险的静默降级。
+		return "", fmt.Errorf("内核未装配加密能力，拒绝以明文存储（core.security.enabled=false？）")
+	}
+	return c.Seal(string(plain))
+}
+
+func (s *secretsImpl) Decrypt(stored string) ([]byte, error) {
+	// 非密文原样返回（兼容插件已有的明文文件，避免升级即坏）
+	if !internalSecurity.IsEncrypted(stored) {
+		return []byte(stored), nil
+	}
+	c := internalSecurity.ConfigCodec()
+	if c == nil || !c.Enabled() {
+		return nil, fmt.Errorf("有密文但内核未装配加密能力（密钥换了？）")
+	}
+	plain, err := c.Open(stored)
+	if err != nil {
+		return nil, err
+	}
+	return []byte(plain), nil
+}
+
+var _ pubsdk.SecretsAPI = (*secretsImpl)(nil)
diff --git a/internal/sdk/settings.go b/internal/sdk/settings.go
index 733fc1b2..41d793a0 100644
--- a/internal/sdk/settings.go
+++ b/internal/sdk/settings.go
@@ -15,6 +15,11 @@ type SettingsAPI interface {
 	RemoveCore(key string) error
 	// RemovePlugin 删除另一个插件配置表中的单个键。
 	RemovePlugin(plugin, key string) error
+	// IsSecret 报告某个（全局或 "plugin.<name>." 前缀的）键是否敏感。
+	//
+	// 用途：需要在**展示**环节屏蔽明文的地方（如 WebUI 设置面）。
+	// 它与落盘加密共用同一套判定，避免“已加密但界面照旧显示”的漏洞。
+	IsSecret(key string) bool
 }
 
 type ConfigDef = pubsdk.ConfigDef
diff --git a/internal/sdk/settings_impl.go b/internal/sdk/settings_impl.go
index 1a67f85b..e8efcd52 100644
--- a/internal/sdk/settings_impl.go
+++ b/internal/sdk/settings_impl.go
@@ -35,6 +35,25 @@ func (s *settingsImpl) Set(key string, value interface{}) error {
 	}
 	return s.reg.PluginConfig(s.pluginName).Set(key, value)
 }
+
+// SetSecret 强制加密写入（不看键名）。
+//
+// 未装配密钥时拒绝写入：插件以为存了密文而实际是明文，是最危险的静默降级。
+func (s *settingsImpl) SetSecret(key string, value interface{}) error {
+	if s.reg == nil {
+		return nil
+	}
+	return s.reg.PluginConfig(s.pluginName).SetSecret(key, value)
+}
+
+// GetSecret 读取 SetSecret 写入的值。
+func (s *settingsImpl) GetSecret(key string) (string, error) {
+	if s.reg == nil {
+		return "", nil
+	}
+	return s.reg.PluginConfig(s.pluginName).GetSecret(key)
+}
+
 func (s *settingsImpl) Remove(key string) error {
 	if s.reg == nil {
 		return nil
@@ -114,6 +133,10 @@ func (s *settingsImpl) RegisterDef(def ConfigDef) {
 		Key: def.Key, Type: def.Type, DisplayName: def.DisplayName, Description: def.Description,
 		Category: def.Category, Options: def.Options,
 		Default: stringifyDefault(def.Default),
+		// ★ Secret 必须透传：丢了它，插件声明的敏感项就退化成普通项
+		//（明文落盘 + 在设置页回显）。初版这三处都漏了这个字段，
+		// 导致 SDK 里早就存在的 Secret 字段从来没生效过。
+		Secret: def.Secret,
 	})
 }
 func (s *settingsImpl) Defs(prefix string) []*ConfigDef {
@@ -127,11 +150,24 @@ func (s *settingsImpl) Defs(prefix string) []*ConfigDef {
 		cpy := ConfigDef{
 			Key: d.Key, Type: d.Type, DisplayName: d.DisplayName, Description: d.Description,
 			Category: d.Category, Options: d.Options, Default: d.Default,
+			Secret: d.Secret,
 		}
 		out[i] = &cpy
 	}
 	return out
 }
+
+// IsSecret 报告某个键是否敏感（E-3：WebUI 屏蔽明文用）。
+//
+// 判定完全委托给 config registry —— 展示与落盘加密必须**同一套判定**，
+// 否则会出现“加密了但界面照旧显示明文”的漏洞。
+func (s *settingsImpl) IsSecret(key string) bool {
+	if s.reg == nil {
+		return false
+	}
+	return s.reg.IsSecret(key)
+}
+
 func (s *settingsImpl) Dump() map[string]interface{} {
 	if s.reg == nil {
 		return nil
@@ -168,6 +204,7 @@ func mapDefs(defs []*internalConfig.ConfigDef) []*ConfigDef {
 		out[i] = &ConfigDef{
 			Key: d.Key, Type: d.Type, DisplayName: d.DisplayName, Description: d.Description,
 			Category: d.Category, Options: d.Options, Default: d.Default,
+			Secret: d.Secret,
 		}
 	}
 	return out
diff --git a/internal/sdk/supervisor.go b/internal/sdk/supervisor.go
index aa547f8e..5ae7d744 100644
--- a/internal/sdk/supervisor.go
+++ b/internal/sdk/supervisor.go
@@ -12,6 +12,8 @@ type SupervisorAPI interface {
 	GetAgentStatus(id string) (*AgentStatus, error)
 	PreActionSnapshot(id string) (*types.Snapshot, error)
 	RollbackAgent(id string, snapID string) error
+	// Restart 主动请求重建本单元（热更新入口：换二进制后不必 systemctl restart）。
+	Restart(id string) error
 }
 
 // AgentStatus is a neutral snapshot of a supervised agent.
diff --git a/internal/security/alias_shape_test.go b/internal/security/alias_shape_test.go
new file mode 100644
index 00000000..d2398104
--- /dev/null
+++ b/internal/security/alias_shape_test.go
@@ -0,0 +1,24 @@
+package security
+
+import "testing"
+
+// 判据：内核别名是 HMAC 派生 ⇒ **用户不能自选名字**。
+//
+// 这决定了去重的形态：插件若要保留可读名（@{gitea-local}），
+// 它必须另外存一个 name→alias 映射（**只存映射，不存值**）。
+func TestKernelAliasIsDerivedNotUserChosen(t *testing.T) {
+	s := newTestStore(t, true)
+	a1, _ := s.Alias("some-plain-value")
+	a2, _ := s.Alias("some-plain-value")
+	if a1 != a2 {
+		t.Fatal("别名必须确定性派生（否则失去自动合并）")
+	}
+	// 没有任何 API 允许指定别名内容
+	if a1 == "gitea-local" {
+		t.Fatal("别名不该等于用户想要的名字")
+	}
+	if len(a1) != 20 || a1[:4] != "sec_" {
+		t.Fatalf("别名形态固定: %s", a1)
+	}
+	t.Logf("内核别名是派生值: %s（用户无法自选 ⇒ 插件要保留可读名必须自己存映射）", a1)
+}
diff --git a/internal/security/bench_test.go b/internal/security/bench_test.go
new file mode 100644
index 00000000..bd0eb419
--- /dev/null
+++ b/internal/security/bench_test.go
@@ -0,0 +1,143 @@
+package security
+
+// 热路径基准 —— 安全模块挂在每次 LLM 调用与每次工具调用上，
+// 它的开销会被**乘上**这两个频次。所以必须知道数量级。
+//
+//	go test -bench . -benchmem ./internal/security/
+//
+// 关注点：
+//   · Replace（出向）：每条消息扫一遍模式库 —— 未命中时应当很便宜
+//   · Fill（入向）：每个工具参数调用一次
+//   · FillMap（入向）：工具参数通常是嵌套 map
+//   · Alias：HMAC 派生（每次拦截都要算）
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+)
+
+func benchStore(b *testing.B) *Store {
+	b.Helper()
+	dir := b.TempDir()
+	s := New(Options{
+		Path:    dir + "/v.json",
+		KeyFn:   func() ([]byte, error) { return []byte("0123456789abcdef0123456789abcdef"), nil },
+		Enabled: true,
+	})
+	if err := s.Load(); err != nil {
+		b.Fatal(err)
+	}
+	return s
+}
+
+// ★ 最重要的一个：**未命中**时的代价（绝大多数消息不含凭据）。
+//
+// 若这条与"命中时"一个量级，说明模式库每次都在做昂贵的全量扫描 ——
+// 那是随消息数线性放大的开销。
+func BenchmarkReplaceNoMatch(b *testing.B) {
+	s := benchStore(b)
+	text := strings.Repeat("这是一段普通的对话内容，讨论架构与实现细节。", 20)
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		if out, evts := s.Replace(text, "bench", Patterns); len(evts) != 0 {
+			b.Fatal("不该命中")
+		} else {
+			_ = out
+		}
+	}
+}
+
+// 命中时的代价（含 HMAC 派生 + 落盘）。
+func BenchmarkReplaceWithMatch(b *testing.B) {
+	s := benchStore(b)
+	text := "token=ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 请使用"
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		_, evts := s.Replace(text, "bench", Patterns)
+		if len(evts) == 0 {
+			b.Fatal("应命中")
+		}
+	}
+}
+
+// Fill：工具参数回填。
+func BenchmarkFill(b *testing.B) {
+	s := benchStore(b)
+	alias, _ := s.Submit("bench-secret-value-123456", "")
+	text := "Authorization: token @{" + alias + "}"
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		_, _, _ = s.Fill(text)
+	}
+}
+
+// FillMap：真实工具参数（嵌套）。
+func BenchmarkFillMap(b *testing.B) {
+	s := benchStore(b)
+	alias, _ := s.Submit("bench-secret-value-123456", "")
+	args := map[string]interface{}{
+		"url": "https://x:@" + alias + "@host/r",
+		"nested": map[string]interface{}{
+			"token": "@{" + alias + "}",
+			"list":  []interface{}{"a", "@{" + alias + "}"},
+		},
+		"n": 42,
+	}
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		s.FillMap(args)
+	}
+}
+
+// Alias：HMAC 派生（拦截路径上的固定成本）。
+func BenchmarkAlias(b *testing.B) {
+	s := benchStore(b)
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		if _, err := s.Alias("some-plain-secret"); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+// 并发下的吞吐：模拟多 agent 同时出向。
+func BenchmarkReplaceParallel(b *testing.B) {
+	s := benchStore(b)
+	text := strings.Repeat("普通对话内容，没有凭据。", 10)
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			_, _ = s.Replace(text, "bench", Patterns)
+		}
+	})
+}
+
+// ── provider 装饰器的端到端开销（经真实请求结构） ──
+
+// BenchmarkProviderScrub 走真实的 api 装饰器路径。
+//
+// 放在 security 包里会形成 import 环，所以这里只模拟它的形状：
+// 逐条消息调 Replace。真实开销 = 消息条数 × Replace。
+func BenchmarkProviderScrubShape(b *testing.B) {
+	s := benchStore(b)
+	msgs := make([]string, 20)
+	for i := range msgs {
+		msgs[i] = fmt.Sprintf("第 %d 条消息：讨论实现细节，无凭据。%s", i,
+			strings.Repeat("内容。", 30))
+	}
+	b.ResetTimer()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		for _, m := range msgs {
+			_, _ = s.Replace(m, "llm_out", Patterns)
+		}
+	}
+	_ = context.Background
+}
diff --git a/internal/security/codec.go b/internal/security/codec.go
new file mode 100644
index 00000000..21faa54d
--- /dev/null
+++ b/internal/security/codec.go
@@ -0,0 +1,285 @@
+package security
+
+// 域隔离的加密编解码器（供内核其它模块复用主密钥）。
+//
+// ## 为什么要域隔离
+//
+// 同一把主密钥会服务多类用途：变量别名的 HMAC、配置落盘的 AES、
+// （未来可能的）审计日志签名……若它们**共用同一把密钥**，就会产生
+// 跨域攻击面：一处的输出可能在另一处被当作合法输入。
+//
+// 所以每类用途用 **HKDF 风格的派生子密钥**：
+//
+//	subKey = HMAC-SHA256(masterKey, "homeagent/<domain>/v1")
+//
+// 这样一把主密钥可以安全地派生出无限多个互不相关的子密钥，
+// 而部署方只需要管一把密钥。
+//
+// ## 与 Alias() 的关系
+//
+// `Alias()` 是**单向**的（明文 → 别名，不可逆），用 HMAC 做哈希。
+// `Codec` 是**双向**的（明文 ⇄ 密文），用 AES-GCM 做加密。
+// 二者用途不同、密钥不同 —— 这就是域隔离的意义。
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"sync"
+)
+
+// EncPrefixV1 是密文的自描述前缀。
+//
+// 为何用前缀而不是加列/加表：**无需 schema 迁移**，且明文旧数据
+// 天然被识别（没有前缀就是明文），逐条惰性加密即可。
+// 版本号 `v1` 让将来换算法时可以两代并存（读到 v1 用旧算法解）。
+const EncPrefixV1 = "enc:v1:"
+
+// ErrBadCiphertext 表示密文格式非法或密钥不对。
+var ErrBadCiphertext = errors.New("security: 密文无法解密（密钥不对或数据损坏）")
+
+// Codec 是用派生密钥做对称加解密的编解码器。
+//
+// key 为 nil 时 **Enabled()==false**，所有 Seal 退化为「原样返回」。
+// 这是刻意设计：编解码器未装配时不能崩，但调用方可以据此判断
+// 「密钥不可用」并选择响亮失败。
+type Codec struct {
+	key    []byte
+	domain string
+	// oldKeys 是轮换前的派生子密钥，仅用于 Open。
+	oldKeys [][]byte
+}
+
+// NewCodec 由主密钥派生出某个用途的子密钥。
+func NewCodec(masterKey []byte, domain string) (*Codec, error) {
+	if len(masterKey) != 32 {
+		return nil, fmt.Errorf("security: 主密钥必须是 32 字节，实际 %d", len(masterKey))
+	}
+	if domain == "" {
+		return nil, errors.New("security: codec 域不能为空（域隔离是安全要求）")
+	}
+	m := hmac.New(sha256.New, masterKey)
+	m.Write([]byte("homeagent/" + domain + "/v1"))
+	return &Codec{key: m.Sum(nil), domain: domain}, nil
+}
+
+// Enabled 报告编解码器是否可用。
+func (c *Codec) Enabled() bool { return c != nil && len(c.key) == 32 }
+
+// NewCodecWithOldKeys 构造支持平滑轮换的 codec。
+//
+// current 是新主密钥；oldMasters 是旧主密钥，**只用于解开旧密文**。
+// 轮换时若不带旧钥，已落盘的密文会全部解不开（响亮失败但服务不可用）
+// —— 那就是 E-1 要解决的问题。
+func NewCodecWithOldKeys(current []byte, domain string, oldMasters [][]byte) (*Codec, error) {
+	if len(current) != 32 {
+		return nil, fmt.Errorf("security: 主密钥必须是 32 字节，实际 %d", len(current))
+	}
+	if domain == "" {
+		return nil, errors.New("security: codec 域不能为空（域隔离是安全要求）")
+	}
+	derive := func(master []byte) []byte {
+		m := hmac.New(sha256.New, master)
+		m.Write([]byte("homeagent/" + domain + "/v1"))
+		return m.Sum(nil)
+	}
+	c := &Codec{key: derive(current), domain: domain}
+	for _, old := range oldMasters {
+		if len(old) == 32 {
+			c.oldKeys = append(c.oldKeys, derive(old))
+		}
+	}
+	return c, nil
+}
+
+// Domain 返回用途域（便于诊断，比如日志里说清楚是哪一域的密文解不开）。
+func (c *Codec) Domain() string {
+	if c == nil {
+		return ""
+	}
+	return c.domain
+}
+
+// Seal 加密并带上版本前缀。
+//
+// 未启用时**原样返回**（明文），这样调用方可以在未装配密钥的
+// 环境（测试、本地开发）继续工作 —— 但生产必须装配（见 IsEncrypted）。
+func (c *Codec) Seal(plain string) (string, error) {
+	if !c.Enabled() {
+		return plain, nil
+	}
+	// 已加密的不要再加一层（幂等）
+	if IsEncrypted(plain) {
+		return plain, nil
+	}
+	block, err := aes.NewCipher(c.key)
+	if err != nil {
+		return "", err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", err
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return "", err
+	}
+	sealed := gcm.Seal(nonce, nonce, []byte(plain), nil)
+	return EncPrefixV1 + encodeB64(sealed), nil
+}
+
+// Open 解密。非密文（无前缀）原样返回 —— 这是**存量明文兼容**的关键：
+// 旧数据不需要一次性迁移就能继续可读。
+func (c *Codec) Open(stored string) (string, error) {
+	if !IsEncrypted(stored) {
+		return stored, nil // 明文（旧数据或未启用）
+	}
+	if !c.Enabled() {
+		return "", fmt.Errorf("%w: 有密文但编解码器未启用（域 %s）",
+			ErrNoMasterKey, c.Domain())
+	}
+	raw, err := decodeB64(strings.TrimPrefix(stored, EncPrefixV1))
+	if err != nil {
+		return "", fmt.Errorf("%w: base64 解码失败", ErrBadCiphertext)
+	}
+	block, err := aes.NewCipher(c.key)
+	if err != nil {
+		return "", err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", err
+	}
+	if len(raw) < gcm.NonceSize() {
+		return "", fmt.Errorf("%w: 密文太短", ErrBadCiphertext)
+	}
+	// ★ 先试当前钥，再依次试历史钥（E-1 轮换过渡期）。
+	// 不能只试当前钥：轮换后旧条目仍是旧钥密文，只试新钥会让它们
+	// 全部变成“解不开”，而那正是要避免的服务不可用。
+	keys := append([][]byte{c.key}, c.oldKeys...)
+	for _, k := range keys {
+		block, err := aes.NewCipher(k)
+		if err != nil {
+			continue
+		}
+		gcm, err := cipher.NewGCM(block)
+		if err != nil {
+			continue
+		}
+		plain, err := gcm.Open(nil, raw[:gcm.NonceSize()], raw[gcm.NonceSize():], nil)
+		if err == nil {
+			return string(plain), nil
+		}
+	}
+	return "", fmt.Errorf("%w (域 %s)", ErrBadCiphertext, c.Domain())
+}
+
+// IsEncrypted 报告一个已存储的值是否是本模块的密文。
+//
+// ★ 单调为真：密文解密后可能恰好以 `enc:v1:` 开头（极小概率），
+// 但那会导致重复解密失败而非静默错误，可接受。
+func IsEncrypted(stored string) bool {
+	return strings.HasPrefix(stored, EncPrefixV1)
+}
+
+// ---------------- 全局配置编解码器 ----------------
+
+var (
+	globalCodecMu sync.RWMutex
+	globalCodec   *Codec
+)
+
+// InitConfigCodec 装配配置落盘用的编解码器（内核启动时调用一次）。
+func InitConfigCodec(masterKey []byte) (*Codec, error) {
+	return InitConfigCodecWithOldKeys(masterKey, nil)
+}
+
+// InitConfigCodecWithOldKeys 装配支持 E-1 平滑轮换的配置 codec。
+// 当前钥负责 Seal；旧钥仅参与 Open。
+
+func InitConfigCodecWithOldKeys(masterKey []byte, oldKeys [][]byte) (*Codec, error) {
+	c, err := NewCodecWithOldKeys(masterKey, "config-at-rest", oldKeys)
+	if err != nil {
+		return nil, err
+	}
+	globalCodecMu.Lock()
+	globalCodec = c
+	globalCodecMu.Unlock()
+	return c, nil
+}
+
+// ConfigCodec 取配置编解码器；未装配时返回 nil（调用方原样读写）。
+func ConfigCodec() *Codec {
+	globalCodecMu.RLock()
+	defer globalCodecMu.RUnlock()
+	return globalCodec
+}
+
+// NeedsRekey 报告该密文是否**不是**当前主密钥加的（即轮换后尚未重加密）。
+//
+// 用途：轮换后需要知道哪些 config 项要重写；只需先试当前钥能不能开。
+// 非密文（明文/旧数据）返回 false（那是 EncryptExistingSecrets 的事）。
+func (c *Codec) NeedsRekey(stored string) bool {
+	if !c.Enabled() || !IsEncrypted(stored) {
+		return false
+	}
+	_, err := c.openWithSingleKey(c.key, stored)
+	return err != nil
+}
+
+// Rekey 把一条密文（可能是旧钥加的）用当前钥重新加密。
+// 非密文原样返回；旧钥也解不开则**响亮报错**（不静默丢数据）。
+func (c *Codec) Rekey(stored string) (string, error) {
+	if !c.Enabled() || !IsEncrypted(stored) {
+		return stored, nil
+	}
+	if _, err := c.openWithSingleKey(c.key, stored); err == nil {
+		return stored, nil // 已是当前钥，幂等
+	}
+	plain, err := c.Open(stored)
+	if err != nil {
+		return "", err
+	}
+	return c.Seal(plain)
+}
+
+// openWithSingleKey 只用指定的一把钥试解（供 NeedsRekey 判定）。
+func (c *Codec) openWithSingleKey(key []byte, stored string) (string, error) {
+	raw, err := decodeB64(strings.TrimPrefix(stored, EncPrefixV1))
+	if err != nil {
+		return "", ErrBadCiphertext
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", err
+	}
+	if len(raw) < gcm.NonceSize() {
+		return "", ErrBadCiphertext
+	}
+	plain, err := gcm.Open(nil, raw[:gcm.NonceSize()], raw[gcm.NonceSize():], nil)
+	if err != nil {
+		return "", ErrBadCiphertext
+	}
+	return string(plain), nil
+}
+
+// ClearConfigCodec 卸下配置编解码器（测试与"显式关闭加密"用）。
+//
+// 单独一个函数而不是让 InitConfigCodec(nil) 承担：
+// 后者语义模糊（nil 是"没密钥"还是"要清空"？），且会掩盖调用方的错误
+// —— 曾因此让一个判据假绿（以为清空了，其实上一把密钥还在）。
+func ClearConfigCodec() {
+	globalCodecMu.Lock()
+	globalCodec = nil
+	globalCodecMu.Unlock()
+}
diff --git a/internal/security/codec_rotation_test.go b/internal/security/codec_rotation_test.go
new file mode 100644
index 00000000..f48a2bdf
--- /dev/null
+++ b/internal/security/codec_rotation_test.go
@@ -0,0 +1,51 @@
+package security
+
+import (
+	"bytes"
+	"testing"
+)
+
+func TestCodecRotationReadsOldAndSealsNew(t *testing.T) {
+	oldKey := bytes.Repeat([]byte{0x71}, 32)
+	newKey := bytes.Repeat([]byte{0x72}, 32)
+	old, err := NewCodec(oldKey, "rotation-test")
+	if err != nil {
+		t.Fatal(err)
+	}
+	sealedOld, err := old.Seal("CONFIG_SECRET")
+	if err != nil {
+		t.Fatal(err)
+	}
+	rotated, err := NewCodecWithOldKeys(newKey, "rotation-test", [][]byte{oldKey})
+	if err != nil {
+		t.Fatal(err)
+	}
+	plain, err := rotated.Open(sealedOld)
+	if err != nil || plain != "CONFIG_SECRET" {
+		t.Fatalf("old ciphertext unreadable: %q %v", plain, err)
+	}
+	if !rotated.NeedsRekey(sealedOld) {
+		t.Fatal("old ciphertext should need rekey")
+	}
+	sealedNew, err := rotated.Rekey(sealedOld)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rotated.NeedsRekey(sealedNew) {
+		t.Fatal("rekeyed ciphertext still needs rekey")
+	}
+	if got, err := rotated.Open(sealedNew); err != nil || got != "CONFIG_SECRET" {
+		t.Fatalf("new ciphertext unreadable: %q %v", got, err)
+	}
+}
+
+func TestCodecRotationWithoutOldKeyFailsLoudly(t *testing.T) {
+	oldKey := bytes.Repeat([]byte{0x81}, 32)
+	newKey := bytes.Repeat([]byte{0x82}, 32)
+	old, _ := NewCodec(oldKey, "rotation-test")
+	sealed, _ := old.Seal("MUST_NOT_DISAPPEAR")
+	rotated, _ := NewCodec(newKey, "rotation-test")
+	if _, err := rotated.Open(sealed); err == nil {
+		t.Fatal("★ missing old key silently accepted ciphertext")
+	}
+}
diff --git a/internal/security/embedded.go b/internal/security/embedded.go
new file mode 100644
index 00000000..4c621e22
--- /dev/null
+++ b/internal/security/embedded.go
@@ -0,0 +1,144 @@
+package security
+
+// 内嵌主密钥（**字面内嵌**，按用户 2026-10-16 的明确选择）。
+//
+// ## 这是什么
+//
+// 把主密钥在**编译期**烧进二进制，运行期作为密钥来源链的**最高优先级**
+// （在 systemd 凭据之前）。目的是「防丢失」：二进制在，密钥就在，
+// 不存在"security.key 被误删/没跟着备份"导致全部密文永久解不开。
+//
+// ## ★ 安全代价（必须写清，不能含糊）
+//
+// 这条改动的代价是**真实的、且方向与加密的初衷相反**：
+//
+//	加密要防的是「文件被读走」。而内嵌后：
+//	  · homed 是 0755、config.db 是 0644 —— 二者同级可达
+//	  · 于是"能读二进制"⇒"能拿密钥"⇒"能解密 config.db"
+//	  ⇒ **对本机读取者，加密不再提供任何保护**
+//	  · 且二进制会进备份/镜像/分发包
+//	    （实测：/home/program/_guard_backup/*/ 里 homed 与 config.db 成对出现）
+//
+// 换言之：内嵌换来"不会因丢文件而丢数据"，代价是"文件被读走就等于全泄"。
+// 这是用户知情后的选择，不是我们的疏忽 —— 但**任何降级/绕过都必须留痕**，
+// 所以下面每次用到内嵌钥都会 log.Printf 说明当前密钥来自内嵌。
+//
+// ## 为什么用 ldflags 而不是 go:embed 一个文件
+//
+// 本仓有两个**公开**远端（gitcode / github）。`go:embed` 要求密钥是一个
+// 仓库内的文件 —— 那意味着它会被提交、被推送、永久留在 git 历史里，
+// 且任何 clone 的人都能拿到。`-ldflags -X` 让密钥只存在于**构建命令行**
+// 与最终二进制中，仓库里一行都不留。
+//
+//	go build -ldflags "-X .../internal/security.embeddedKeyHex=<64位hex>" ./cmd/homed
+//
+// ## 为什么不是"只信内嵌"（丢数据的陷阱）
+//
+// 最危险的做法是：有内嵌钥就**一切以它为准**、忽略别处。
+// 那样一台已经用磁盘钥加密过的老机器，升级到这个二进制后会：
+//
+//	① 用内嵌钥去解磁盘钥加的密文 → 全部解不开
+//	② 若此时"解不开就重建库"→ **静默丢掉全部凭据**
+//
+// 所以这里**只把内嵌钥当一个来源**，并且在磁盘/keyring 存在时把它作为
+// **额外的解密钥**（可读旧密文），而不是替换现有钥。优先顺序见
+// LoadOrCreateKey：内嵌 > systemd > env > 磁盘。
+//
+// ★ 并且内嵌钥与磁盘钥**不一致**时必须响亮告警（不能静默选一把继续）：
+// 那意味着这台机器上存在两套互不可解的密文，用户必须知道。
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+)
+
+// embeddedKeyHex 由构建时的 -ldflags 注入（64 位 hex）。
+//
+// ★ 默认空值：没有注入时，行为与改动前**逐字相同**（走 systemd/env/磁盘链）。
+// 这是必须的 —— 否则用默认 Makefile 构建出的二进制会在所有老部署上
+// "找不到密钥"，那是一个破坏性变更。
+var embeddedKeyHex string
+
+// EmbeddedKeyPresent 报告本二进制是否内嵌了主密钥。
+func EmbeddedKeyPresent() bool { return embeddedKeyHex != "" }
+
+// embeddedKey 解出内嵌钥（未内嵌或格式非法时返回 nil）。
+//
+// 格式非法**不** Fatal：内嵌是由构建脚本注入的，格式错是构建问题；
+// 运行期直接崩会让"二进制起来了但服务全挂"难以归因。这里降级为
+// 响亮告警 + 回退到其它来源（安全性上不损失：回退路径本身是可信的）。
+func embeddedKey() []byte {
+	if embeddedKeyHex == "" {
+		return nil
+	}
+	k, err := parseKey(embeddedKeyHex)
+	if err != nil {
+		log.Printf("[security] ★ 内嵌主密钥格式非法（构建时 -ldflags 注入有误），已忽略: %v", err)
+		return nil
+	}
+	if len(k) != 32 {
+		log.Printf("[security] ★ 内嵌主密钥长度 %d 非法（需 32 字节），已忽略", len(k))
+		return nil
+	}
+	return k
+}
+
+// loadEmbeddedKey 取内嵌钥并说明来源（供 LoadOrCreateKey 使用）。
+//
+// 它额外做一件 LoadOrCreateKey 不该独自承担的事：**报告与磁盘钥是否一致**。
+func loadEmbeddedKey(dataDir string) ([]byte, bool) {
+	k := embeddedKey()
+	if k == nil {
+		return nil, false
+	}
+	// 与磁盘钥比对（仅提示，不阻断）
+	if diskPath := filepath.Join(dataDir, KeyFileName); fileExistsSimple(diskPath) {
+		if b, err := os.ReadFile(diskPath); err == nil {
+			if dk, err := parseKey(string(trimSpaceBytes(b))); err == nil {
+				if !sameKey(dk, k) {
+					log.Printf("[security] ★★ 内嵌主密钥与 %s **不一致**："+
+						"该机器上存在两套互不可解的密文（内嵌钥能解一部分、磁盘钥能解另一部分）。"+
+						"本次以**内嵌钥为当前钥**，磁盘钥请通过 security.keyring 的 history "+
+						"或 HOMED_SECURITY_KEY 保留，否则旧密文会读不出来", diskPath)
+				}
+			}
+		}
+	}
+	return k, true
+}
+
+// EmbeddedKeyFingerprint 返回内嵌钥的短指纹（用于日志/自检，**不泄漏密钥**）。
+//
+// 用 hex 前 8 位：够区分两把不同的钥，又不足以从指纹还原。
+// 绝不打印密钥本身 —— 日志会进 journal、被导出、被贴进 issue。
+func EmbeddedKeyFingerprint() string {
+	k := embeddedKey()
+	if k == nil {
+		return ""
+	}
+	s := fmt.Sprintf("%x", k)
+	return s[:8]
+}
+
+func trimSpaceBytes(b []byte) []byte {
+	i, j := 0, len(b)
+	for i < j && isSpaceByte(b[i]) {
+		i++
+	}
+	for j > i && isSpaceByte(b[j-1]) {
+		j--
+	}
+	return b[i:j]
+}
+
+func isSpaceByte(c byte) bool {
+	return c == ' ' || c == '\t' || c == '\n' || c == '\r'
+}
+
+// fileExistsSimple 是本地最小实现（避免与包内其它 fileExists 重名冲突）。
+func fileExistsSimple(p string) bool {
+	st, err := os.Stat(p)
+	return err == nil && !st.IsDir()
+}
diff --git a/internal/security/embedded_test.go b/internal/security/embedded_test.go
new file mode 100644
index 00000000..bcad4937
--- /dev/null
+++ b/internal/security/embedded_test.go
@@ -0,0 +1,269 @@
+package security
+
+// 内嵌主密钥的判据。
+//
+// 这组判据要证明的核心**不是**"内嵌能生效"，而是
+// **"内嵌不会把已有数据变成读不出来的垃圾"** —— 那才是这条改动真正的风险。
+// 一个只测"有内嵌钥就用它"的判据会全绿，而线上老机器升级后会解不开库。
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// withEmbeddedKey 临时把内嵌钥设成 k（测试结束还原）。
+//
+// 用直接赋值而不是 ldflags：判据要能覆盖"内嵌/未内嵌"两种形态。
+func withEmbeddedKey(t *testing.T, k string) {
+	t.Helper()
+	old := embeddedKeyHex
+	embeddedKeyHex = k
+	t.Cleanup(func() { embeddedKeyHex = old })
+}
+
+// ★★★ 判据：未内嵌时行为**逐字不变**（否则是个破坏性变更）。
+//
+// 默认 Makefile 构建出的二进制没有内嵌钥，必须在所有老部署上照常工作：
+// 仍走 systemd/env/磁盘链，且没有磁盘钥时仍会生成。
+func TestNoEmbeddedKeyKeepsLegacyBehavior(t *testing.T) {
+	withEmbeddedKey(t, "")
+	if EmbeddedKeyPresent() {
+		t.Fatal("空串不应算作已内嵌")
+	}
+	dir := t.TempDir()
+
+	// ① 无磁盘钥 → 生成并落盘（老行为）
+	k1, src1, err := LoadOrCreateKey(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if src1 == "" || src1[0:9] == "embedded" {
+		t.Errorf("未内嵌时来源不该是 embedded: %q", src1)
+	}
+	p := filepath.Join(dir, KeyFileName)
+	if fi, err := os.Stat(p); err != nil {
+		t.Fatalf("应生成 %s: %v", KeyFileName, err)
+	} else if fi.Mode().Perm() != 0o600 {
+		t.Errorf("密钥文件权限应为 0600，实际 %v", fi.Mode().Perm())
+	}
+	// ② 再读应拿到同一把（稳定）
+	k2, _, err := LoadOrCreateKey(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !sameKey(k1, k2) {
+		t.Fatal("同一目录两次读取应得到同一把钥")
+	}
+	// ③ 无额外解密钥
+	if extra := AdditionalDecryptKeys(dir, k1); len(extra) != 0 {
+		t.Errorf("未内嵌时不该有额外解密钥: %d", len(extra))
+	}
+}
+
+// ★★★ 判据：内嵌钥被采用，且**来源可辨识**、指纹不泄漏密钥本身。
+func TestEmbeddedKeyIsUsed(t *testing.T) {
+	hexKey := "aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"
+	withEmbeddedKey(t, hexKey)
+	if !EmbeddedKeyPresent() {
+		t.Fatal("应报告已内嵌")
+	}
+	want, _ := parseKey(hexKey)
+
+	dir := t.TempDir()
+	got, src, err := LoadOrCreateKey(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !sameKey(got, want) {
+		t.Fatal("★ 未采用内嵌钥")
+	}
+	// 来源必须能看出是内嵌（运维要能一眼判断"这把钥从哪来"）
+	if len(src) < 8 || src[:8] != "embedded" {
+		t.Errorf("来源应标明 embedded: %q", src)
+	}
+	// 指纹不得包含完整密钥
+	fp := EmbeddedKeyFingerprint()
+	if fp == "" || len(fp) != 8 {
+		t.Errorf("指纹形状不对: %q", fp)
+	}
+	if len(fp) >= len(hexKey) {
+		t.Error("★ 指纹不得等于/长于密钥本身（会泄漏）")
+	}
+	// 内嵌优先于磁盘：即使磁盘有另一把钥，也以内嵌为准
+	other, _ := parseKey("1111111111111111111111111111111111111111111111111111111111111111")
+	if err := os.WriteFile(filepath.Join(dir, KeyFileName), []byte(hexKeyOf(other)), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	got2, _, err := LoadOrCreateKey(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !sameKey(got2, want) {
+		t.Error("★ 内嵌钥应优先于磁盘钥")
+	}
+}
+
+// ★★★ **最关键的一条**：内嵌钥与磁盘钥不同时，磁盘钥必须进入**解密集合**。
+//
+// 这是"内嵌"与"防丢失"的交界处。反例（本判据要挡住的）：
+//
+//	老机器用磁盘钥加密过 config.db → 升级到内嵌了另一把钥的二进制
+//	→ 只信内嵌钥 → 旧密文全解不开 → 内核响亮失败 → 用户"重建库" ⇒ **凭据全丢**
+//
+// 那恰好与内嵌的初衷相反。所以磁盘钥必须继续参与 Open。
+func TestEmbeddedKeyKeepsDiskKeyForDecrypt(t *testing.T) {
+	hexKey := "aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"
+	withEmbeddedKey(t, hexKey)
+	embedded, _ := parseKey(hexKey)
+
+	dir := t.TempDir()
+	// 磁盘上是**另一把**钥（模拟已存在的旧部署）
+	disk, _ := parseKey("2222222222222222222222222222222222222222222222222222222222222222")
+	if err := os.WriteFile(filepath.Join(dir, KeyFileName), []byte(hexKeyOf(disk)), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	extra := AdditionalDecryptKeys(dir, embedded)
+	if len(extra) != 1 {
+		t.Fatalf("★ 磁盘钥必须作为额外解密钥装入，否则旧密文全丢；实际 %d 把", len(extra))
+	}
+	if !sameKey(extra[0], disk) {
+		t.Fatal("额外解密钥不是磁盘那把")
+	}
+
+	// ★ 端到端：用磁盘钥加密的密文，在"当前钥=内嵌钥 + 额外钥=磁盘钥"下**必须能解开**
+	dc, err := NewCodec(disk, "config-at-rest")
+	if err != nil {
+		t.Fatal(err)
+	}
+	cipherText, err := dc.Seal("旧的敏感值")
+	if err != nil {
+		t.Fatal(err)
+	}
+	nc, err := NewCodecWithOldKeys(embedded, "config-at-rest", extra)
+	if err != nil {
+		t.Fatal(err)
+	}
+	plain, err := nc.Open(cipherText)
+	if err != nil {
+		t.Fatalf("★ 旧密文解不开（这正是内嵌会导致的数据丢失）: %v", err)
+	}
+	if plain != "旧的敏感值" {
+		t.Fatalf("解出的值不对: %q", plain)
+	}
+}
+
+// ★★★ 判据：磁盘钥与内嵌钥**相同**时不重复添加（幂等、不污染解密集合）。
+func TestEmbeddedKeySameAsDiskNoDuplicate(t *testing.T) {
+	hexKey := "aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"
+	withEmbeddedKey(t, hexKey)
+	k, _ := parseKey(hexKey)
+
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, KeyFileName), []byte(hexKeyOf(k)), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if extra := AdditionalDecryptKeys(dir, k); len(extra) != 0 {
+		t.Errorf("同钥不该产生额外解密钥: %d", len(extra))
+	}
+}
+
+// ★★★ 判据：内嵌钥格式非法时**不崩**、且退回其它来源。
+//
+// 内嵌是构建脚本注入的，格式错是构建问题。运行期直接崩会让
+// "二进制起来了但服务全挂"难以归因；而回退路径本身是可信的，安全性不损失。
+func TestEmbeddedKeyMalformedFallsBack(t *testing.T) {
+	for _, bad := range []string{"not-hex", "abcd", "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz"} {
+		withEmbeddedKey(t, bad)
+		dir := t.TempDir()
+		k, src, err := LoadOrCreateKey(dir)
+		if err != nil {
+			t.Fatalf("格式 %q 不该导致失败: %v", bad, err)
+		}
+		if len(k) != 32 {
+			t.Errorf("格式 %q 应回退到 32 字节钥，实际 %d", bad, len(k))
+		}
+		if len(src) >= 8 && src[:8] == "embedded" {
+			t.Errorf("★ 非法内嵌钥不该被采用（否则会用一把错钥加密新数据）: %q", src)
+		}
+	}
+}
+
+// ★★★ 判据：内嵌升级场景下，**keyring 的 current 也要进解密集合**（不能 Fatal）。
+//
+// 一台已经轮换过钥的机器（有 security.keyring）升级到内嵌二进制时，
+// keyring 的 current 是**旧磁盘钥**，与当前（内嵌）钥不同。
+// 按原有逻辑这会 Fatal「拒绝静默选错钥」—— 但内嵌场景下它不是错钥，
+// 是"密钥来源升级了"，必须按额外解密钥保留。
+func TestKeyringCurrentBecomesDecryptKeyUnderEmbedded(t *testing.T) {
+	hexKey := "aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"
+	withEmbeddedKey(t, hexKey)
+	embedded, _ := parseKey(hexKey)
+
+	dir := t.TempDir()
+	// 老机器状态：磁盘钥 + keyring（current = 磁盘钥，含一把更老的历史钥）
+	disk, _ := parseKey("3333333333333333333333333333333333333333333333333333333333333333")
+	older, _ := parseKey("4444444444444444444444444444444444444444444444444444444444444444")
+	if err := os.WriteFile(filepath.Join(dir, KeyFileName), []byte(hexKeyOf(disk)), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := RotateKeyFile(dir, older, disk); err != nil {
+		t.Fatal(err)
+	}
+
+	// ★ 必须成功（不 Fatal），且能把 disk 与 older 都作为解密钥拿到
+	old, err := LoadKeyring(dir, embedded)
+	if err != nil {
+		t.Fatalf("★ 内嵌升级场景下 LoadKeyring 不该失败（会让老机器起不来）: %v", err)
+	}
+	has := func(k []byte) bool {
+		for _, o := range old {
+			if sameKey(o, k) {
+				return true
+			}
+		}
+		return false
+	}
+	if !has(disk) {
+		t.Error("★ keyring 的 current（旧磁盘钥）必须进解密集合")
+	}
+	if !has(older) {
+		t.Error("keyring 的 history 必须进解密集合")
+	}
+	// 当前（内嵌）钥不该出现在解密集合里（它本来就在）
+	if has(embedded) {
+		t.Error("当前钥不该重复出现在解密集合里")
+	}
+}
+
+// ★★★ 判据：**没有**内嵌时，keyring 与磁盘钥不一致仍然必须响亮失败。
+//
+// 上面那条放宽只对内嵌场景成立；没有内嵌时"选错钥"依然是严重错误，
+// 必须保持原有的拒绝行为（否则这个放宽会变成普遍性的安全退化）。
+func TestKeyringMismatchStillFatalWithoutEmbedded(t *testing.T) {
+	withEmbeddedKey(t, "")
+	dir := t.TempDir()
+	disk, _ := parseKey("5555555555555555555555555555555555555555555555555555555555555555")
+	older, _ := parseKey("6666666666666666666666666666666666666666666666666666666666666666")
+	if err := os.WriteFile(filepath.Join(dir, KeyFileName), []byte(hexKeyOf(disk)), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := RotateKeyFile(dir, older, disk); err != nil {
+		t.Fatal(err)
+	}
+	// 传一把**不相干**的当前钥 → 必须报错
+	stranger, _ := parseKey("7777777777777777777777777777777777777777777777777777777777777777")
+	if _, err := LoadKeyring(dir, stranger); err == nil {
+		t.Fatal("★ 无内嵌时 keyring current 与当前钥不一致必须响亮失败（不得静默选错钥）")
+	}
+}
+
+func hexKeyOf(k []byte) string {
+	const hx = "0123456789abcdef"
+	out := make([]byte, 0, 64)
+	for _, b := range k {
+		out = append(out, hx[b>>4], hx[b&0xf])
+	}
+	return string(out)
+}
diff --git a/internal/security/global.go b/internal/security/global.go
new file mode 100644
index 00000000..4aa0dbee
--- /dev/null
+++ b/internal/security/global.go
@@ -0,0 +1,101 @@
+package security
+
+// 进程级单例与两个入向填充入口。
+//
+// ## 依赖方向（重要）
+//
+//	internal/security        ← 纯逻辑，不 import 任何 agent 包
+//	    ↑
+//	internal/agent/api       provider 装饰器（出向改写）
+//	internal/agent/core      工具参数/载荷填充（入向回填）
+//
+// 是 DAG，**没有 import 环**。所以装饰器可以直接用内核的 Provider 接口，
+// 不必做接口投影。（初版误以为会成环而写了一层投影接口，已删除。）
+//
+// ## 为何单例必须是进程级
+//
+// 已核：主 / 子 / 驻留子 agent 共享同一个 ProviderManager
+//（`resident.go:185`；manager 全进程只建一份 `bootstrap.go:249`）。
+// 所以变量库挂在 provider 层天然就是进程级 —— **不需要跨 agent 同步**。
+
+import (
+	"log"
+	"sync"
+)
+
+var (
+	globalMu sync.RWMutex
+	global   *Store
+)
+
+// InitGlobal 装配进程级单例。**必须在任何 agent 启动前调用**。
+func InitGlobal(opt Options) (*Store, error) {
+	s := New(opt)
+	if err := s.Load(); err != nil {
+		return nil, err
+	}
+	globalMu.Lock()
+	global = s
+	globalMu.Unlock()
+	return s, nil
+}
+
+// SetGlobal 直接装入一个已构造的 Store（测试与特殊装配用）。
+func SetGlobal(s *Store) {
+	globalMu.Lock()
+	global = s
+	globalMu.Unlock()
+}
+
+// Global 取进程级单例；未初始化时返回 nil。
+//
+// ★ 为何返回 nil 而不报错：调用点散布在内核热路径上，
+// 未启用时必须**零成本跳过**。所有调用方都写成
+// `if s := Global(); s != nil { ... }`。
+func Global() *Store {
+	globalMu.RLock()
+	defer globalMu.RUnlock()
+	return global
+}
+
+// Enabled 报告安全模块是否已启用。
+func Enabled() bool {
+	s := Global()
+	return s != nil && s.enabled
+}
+
+// ---------------- 入向填充（插件无感知的关键） ----------------
+
+// FillToolArgs 把一个工具调用的参数里的 `@{别名}` 换回明文。
+//
+// 这是**内核工具链的入口**（`core.StageHost.ExecuteTool`）：
+// 插件收到的参数已经填好，它完全不知道有替换这回事。
+//
+// 返回 (填充处数, 用到的别名)。未初始化时返回 (0, nil)。
+func FillToolArgs(tool string, args map[string]interface{}) (int, []string) {
+	s := Global()
+	if s == nil || args == nil {
+		return 0, nil
+	}
+	n, used := s.FillMap(args)
+	if n > 0 {
+		log.Printf("[security] 工具 %s 参数回填 %d 处（别名 %v）", tool, n, used)
+	}
+	return n, used
+}
+
+// FillPayload 把一段文本载荷里的 `@{别名}` 换回明文。
+//
+// 用于**设备输出通道**（`core` 的 `dev.Execute`）：发给设备的指令同理
+// 需要真实凭据，而设备侧对替换无感知。
+func FillPayload(where, text string) string {
+	s := Global()
+	if s == nil || text == "" {
+		return text
+	}
+	out, n, used := s.Fill(text)
+	if n > 0 {
+		log.Printf("[security] %s 载荷回填 %d 处（别名 %v）", where, n, used)
+	}
+	return out
+}
diff --git a/internal/security/harden.go b/internal/security/harden.go
new file mode 100644
index 00000000..b8ed5822
--- /dev/null
+++ b/internal/security/harden.go
@@ -0,0 +1,168 @@
+package security
+
+// 数据目录与敏感文件的权限收敛。
+//
+// ## 为什么必须有这一层（与内嵌主密钥配套）
+//
+// 用户选择把主密钥**内嵌**进二进制（`embedded.go`）。那条路的代价是：
+// 密钥就在 `homed` 里，而 `homed` 出厂是 0755、`config.db` 是 0644 ——
+// 二者同级可达，于是「能读二进制 ⇒ 能拿密钥 ⇒ 能解密数据库」。
+//
+// 缓解手段很直接：**把可达性收窄到 root**。这不是把内嵌变成安全设计，
+// 而是把它的暴露面从"本机任何用户"缩小到"root"——而那正是唯一本来就
+// 能读全部凭据的身份（服务以 root 运行，进程内存里本就有明文）。
+//
+// ## 为什么写进代码而不是手工 chmod
+//
+// 手工 chmod 会在下一次重建/换机器/恢复备份时**悄悄失效**，
+// 而症状是"加密还在，但保护已经没了"——没人会注意到。
+// 所以收敛必须每次启动都跑（幂等），且**收紧失败要响亮**：
+// 权限没收紧意味着"以为受保护其实没有"，属于必须知道的安全事实。
+//
+// ## 只收紧、不放松
+//
+// 绝不把已经更严的权限改回宽（除非显式要求）：一个被管理员手工设成 0400
+// 的文件不该被启动流程"修正"成 0600。所以只在**比目标宽**时才动。
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+)
+
+// 目标权限（尽量小；全部服务以 root 运行，实测无其他读者）。
+const (
+	// DirPerm 数据目录：0750 —— 同组（root）可进入，其他用户不可。
+	// 不用 0700 是因为保留 group 访问的余地（将来若拆出专用组，只需改组属主）。
+	DirPerm = 0o750
+
+	// FilePerm 敏感文件（config.db 及其 WAL/SHM、密钥、密钥环、变量库）：0600。
+	FilePerm = 0o600
+)
+
+// HardenResult 报告收敛动作（供日志与自检工具使用）。
+type HardenResult struct {
+	// Changed 是被实际改动的路径（含从→到）。
+	Changed []string
+	// Errors 是收紧失败的项。**非空必须响亮**：权限没收紧 = 保护没生效。
+	Errors []string
+}
+
+// sensitiveFileNames 是需要 0600 的文件/通配（相对数据目录）。
+//
+// 为什么把 config.db 的 `-wal` / `-shm` 也算上：SQLite 的 WAL 模式会把
+// **未合并的最新数据**放在 `-wal` 里 —— 只收紧主库而留下 0644 的 `-wal`，
+// 等于把最近写入的（可能正是密钥的）内容继续暴露给所有人。
+// 这个坑很隐蔽：`ls -l config.db` 看起来是对的。
+var sensitiveFileNames = []string{
+	"config.db",
+	"config.db-wal",
+	"config.db-shm",
+	KeyFileName,     // security.key
+	KeyringFileName, // security.keyring
+}
+
+// sensitiveDirs 是需要 0750 的子目录（相对数据目录）。
+var sensitiveDirs = []string{
+	"security", // 变量库 variables.json 所在处
+}
+
+// HardenDataDir 幂等地把数据目录与敏感文件收敛到最小权限。
+//
+// 它**不**因为个别失败就中止启动：一个权限收紧失败不该让服务不可用
+// （那会把安全加固变成可用性事故）。但失败项会逐条返回，
+// 调用方必须**响亮记录**。
+func HardenDataDir(dataDir string) HardenResult {
+	var res HardenResult
+	if dataDir == "" {
+		return res
+	}
+
+	// ① 数据目录本身
+	if ch, err := tightenPath(dataDir, DirPerm); err != nil {
+		res.Errors = append(res.Errors, fmt.Sprintf("%s: %v", dataDir, err))
+	} else if ch != "" {
+		res.Changed = append(res.Changed, ch)
+	}
+
+	// ② 敏感子目录
+	for _, d := range sensitiveDirs {
+		p := filepath.Join(dataDir, d)
+		if _, err := os.Stat(p); err != nil {
+			continue // 不存在就跳过（不是错误）
+		}
+		if ch, err := tightenPath(p, DirPerm); err != nil {
+			res.Errors = append(res.Errors, fmt.Sprintf("%s: %v", p, err))
+		} else if ch != "" {
+			res.Changed = append(res.Changed, ch)
+		}
+	}
+
+	// ③ 敏感文件
+	for _, f := range sensitiveFileNames {
+		p := filepath.Join(dataDir, f)
+		st, err := os.Stat(p)
+		if err != nil || st.IsDir() {
+			continue
+		}
+		if ch, err := tightenPath(p, FilePerm); err != nil {
+			res.Errors = append(res.Errors, fmt.Sprintf("%s: %v", p, err))
+		} else if ch != "" {
+			res.Changed = append(res.Changed, ch)
+		}
+	}
+
+	// ④ 变量库（在 security/ 下）
+	for _, f := range []string{"variables.json", "variables.json.tmp"} {
+		p := filepath.Join(dataDir, "security", f)
+		st, err := os.Stat(p)
+		if err != nil || st.IsDir() {
+			continue
+		}
+		if ch, err := tightenPath(p, FilePerm); err != nil {
+			res.Errors = append(res.Errors, fmt.Sprintf("%s: %v", p, err))
+		} else if ch != "" {
+			res.Changed = append(res.Changed, ch)
+		}
+	}
+
+	if len(res.Errors) > 0 {
+		// 响亮：权限没收紧意味着"以为受保护其实没有"。
+		for _, e := range res.Errors {
+			log.Printf("[security] ★★ 权限收紧失败（该项仍可能对同机其他用户可读）: %s", e)
+		}
+	}
+	return res
+}
+
+// tightenPath 在**当前权限比目标宽**时收紧到目标。
+//
+// 返回非空字符串表示确实改了（内容形如 "0755→0750 /path"），
+// 便于日志说清"改了什么"。
+//
+// ★ 只收紧不放松：已经更严（如 0400）的文件保持原样 ——
+// 一个被管理员特意设严的文件不该被启动流程"修正"。
+func tightenPath(p string, want os.FileMode) (string, error) {
+	st, err := os.Stat(p)
+	if err != nil {
+		return "", err
+	}
+	cur := st.Mode().Perm()
+	if cur == want || !isLooser(cur, want) {
+		return "", nil
+	}
+	if err := os.Chmod(p, want); err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("%04o→%04o %s", cur, want, p), nil
+}
+
+// isLooser 报告 cur 是否比 want 宽松（任一位是 cur 有而 want 没有的）。
+//
+// 例如 cur=0644 / want=0600 → 宽松（group/other 可读）；
+//
+//	cur=0400 / want=0600 → **不**宽松（反而更严，不该动）
+func isLooser(cur, want os.FileMode) bool {
+	return cur&^want != 0
+}
diff --git a/internal/security/key.go b/internal/security/key.go
new file mode 100644
index 00000000..c06f6b21
--- /dev/null
+++ b/internal/security/key.go
@@ -0,0 +1,198 @@
+package security
+
+// 主密钥管理（设计文档 T3）。
+//
+// ## 密钥从哪来
+//
+// 优先顺序（第一个可用者胜出）：
+//
+//	1. systemd 凭据文件 $CREDENTIALS_DIRECTORY/homed_security_key
+//	   —— 生产首选：systemd 解密到 tmpfs（只读、不在磁盘、不进 environ）
+//	2. 环境变量 HOMED_SECURITY_KEY（hex 64 字符 / base64）
+//	   —— 兼容手写 systemd / 容器注入
+//	3. <dataDir>/security.key 文件（0600，首次启动自动生成）
+//	   —— 开发机 / 无 systemd 场景
+//
+// ## 为什么把 systemd 凭据放在 env 之前
+//
+// 环境变量对同用户进程**可见**（/proc/<pid>/environ），任何以该用户身份运行的
+// 进程都能读到主密钥 —— 那等于把整层加密打开。systemd 的 LoadCredential 把
+// 内容落到一个 tmpfs 文件（$CREDENTIALS_DIRECTORY，仅本进程可读 0400），
+// 既不在磁盘上留副本，也不出现在 environ 里。
+//
+// 详见 docs/zh/kernel-secret-firewall-design.md E-4。
+//
+// ## 为何不放进 config.db
+//
+// config.db 是 0644 **全局可读**的。密钥进去等于没有加密
+//（设计文档硬约束：凭据绝不进 config.db）。
+//
+// ## 密钥丢失的后果（必须响亮）
+//
+// 密钥变了 ⇒ 已落盘的变量全部解不开。这时**不能静默重建库**
+//（那会看起来"一切正常"而实际所有凭据都丢了）。
+// 判据 TestWrongKeyFailsLoudly 固化这个行为。
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// EnvKeyName 是主密钥的环境变量名。
+const EnvKeyName = "HOMED_SECURITY_KEY"
+
+// CredentialDirEnv 是 systemd 提供的凭据目录（`LoadCredential`/`SetCredential`）。
+const CredentialDirEnv = "CREDENTIALS_DIRECTORY"
+
+// CredentialName 是 systemd 凭据名。
+//
+// ★ 这个名字必须与 unit 里的 `LoadCredential=<ID>:<path>` **逐字符一致**：
+// 实测（systemd 262）下划线**不会**被改写 —— `LoadCredential=homed_security_key:...`
+// 产生的文件名就是 `homed_security_key`。这个名字是我们自己选的，
+// 只要两边一致即可（文档只要求"可作为文件名的短 ASCII 串"）。
+const CredentialName = "homed_security_key"
+
+// KeyFileName 是密钥文件名（位于数据目录）。
+const KeyFileName = "security.key"
+
+// LoadOrCreateKey 按优先级取主密钥；没有则生成一个并落盘。
+//
+// dataDir 是内核数据目录（config.db 所在目录）。
+func LoadOrCreateKey(dataDir string) ([]byte, string, error) {
+	// ⓪ 内嵌主密钥（构建期 -ldflags 注入）——**最高优先级**。
+	//
+	// 为何最高：内嵌的目的就是「二进制在、密钥就在」，若被 systemd/env/磁盘
+	// 盖过，那它在那些来源缺失时仍需回退，"不丢"就不成立。
+	//
+	// ★ 但它**不删除**其它来源：旧密文仍需旧钥可读，见 AdditionalDecryptKeys。
+	if k, ok := loadEmbeddedKey(dataDir); ok {
+		return k, "embedded (构建期注入，指纹 " + EmbeddedKeyFingerprint() + ")", nil
+	}
+
+	// ① systemd 凭据（生产首选：tmpfs、不在磁盘、不进 environ）
+	if dir := strings.TrimSpace(os.Getenv(CredentialDirEnv)); dir != "" {
+		path := filepath.Join(dir, CredentialName)
+		b, err := os.ReadFile(path)
+		if err != nil {
+			// CredentialsDirectory 存在但凭据缺失 ⇒ **响亮失败**。
+			// 静默回退到磁盘文件会让「忘记配凭据」表现成「一切正常」，
+			// 而实际用的是旧密钥 —— 那正是本模块最怕的静默降级。
+			return nil, "", fmt.Errorf(
+				"security: systemd 凭据目录已设置（%s）但读不到 %s —— "+
+					"unit 里应配 LoadCredential=%s:<密钥文件路径>；"+
+					"拒绝静默回退到磁盘密钥: %w",
+				dir, CredentialName, CredentialName, err)
+		}
+		key, err := parseKey(strings.TrimSpace(string(b)))
+		if err != nil {
+			return nil, "", fmt.Errorf("security: systemd 凭据 %s 格式非法: %w", path, err)
+		}
+		return key, "systemd credential " + CredentialName, nil
+	}
+
+	// ② 环境变量（兼容手写 systemd / 容器）
+	if raw := strings.TrimSpace(os.Getenv(EnvKeyName)); raw != "" {
+		key, err := parseKey(raw)
+		if err != nil {
+			return nil, "", fmt.Errorf("security: %s 格式非法: %w", EnvKeyName, err)
+		}
+		return key, EnvKeyName, nil
+	}
+
+	// ③ 磁盘文件
+	path := filepath.Join(dataDir, KeyFileName)
+	if b, err := os.ReadFile(path); err == nil {
+		if fi, serr := os.Stat(path); serr == nil {
+			if perm := fi.Mode().Perm(); perm != 0o600 {
+				return nil, "", fmt.Errorf(
+					"security: 主密钥文件权限不安全：%s 是 %04o，必须是 0600",
+					path, perm)
+			}
+		}
+		key, err := parseKey(strings.TrimSpace(string(b)))
+		if err != nil {
+			return nil, "", fmt.Errorf("security: 主密钥文件损坏: %w", err)
+		}
+		return key, path, nil
+	} else if !os.IsNotExist(err) {
+		return nil, "", err
+	}
+
+	// ③ 首次启动：生成
+	key := make([]byte, 32)
+	if _, err := rand.Read(key); err != nil {
+		return nil, "", fmt.Errorf("security: 生成主密钥失败: %w", err)
+	}
+	if err := os.MkdirAll(dataDir, 0o700); err != nil {
+		return nil, "", err
+	}
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, []byte(hex.EncodeToString(key)), 0o600); err != nil {
+		return nil, "", err
+	}
+	if err := os.Chmod(tmp, 0o600); err != nil {
+		return nil, "", err
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		return nil, "", err
+	}
+	return key, path, nil
+}
+
+// AdditionalDecryptKeys 返回**当前钥之外**、为了能读出已落盘密文而必须装入
+// 解密集合的钥。
+//
+// ## 为何必需（否则内嵌会一次性丢光数据）
+//
+// 一台机器先用磁盘钥 `security.key` 加密过 config.db / 变量库，然后升级到
+// **内嵌了另一把钥**的二进制。此时若只信内嵌钥：
+//
+//	① 旧密文用内嵌钥解 → 全部失败
+//	② 内核遇到解不开的密文会**响亮失败**（这是对的设计，不静默重建）
+//	⇒ 服务起不来；若用户此时选择"重建库"⇒ **凭据全丢**
+//
+// 所以内嵌钥上台时，磁盘钥（以及 keyring history）必须继续参与**解密**，
+// 只是不再负责加密新数据。这正是 E-1 密钥环的同一套思路：
+// 「当前钥负责 Seal；旧钥只参与 Open」。
+//
+// 内嵌钥与磁盘钥相同、或磁盘钥不存在时，返回空（无额外钥）。
+func AdditionalDecryptKeys(dataDir string, current []byte) [][]byte {
+	var out [][]byte
+	if !EmbeddedKeyPresent() {
+		return nil
+	}
+	path := filepath.Join(dataDir, KeyFileName)
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil
+	}
+	diskKey, err := parseKey(string(trimSpaceBytes(b)))
+	if err != nil || len(diskKey) != 32 {
+		return nil
+	}
+	if !sameKey(diskKey, current) {
+		out = append(out, diskKey)
+		log.Printf("[security] 已把 %s 作为**额外解密钥**装入（内嵌钥为当前钥）——"+
+			"旧密文仍可读；请勿删除该文件，直到确认全部密文已重加密", path)
+	}
+	return out
+}
+
+// parseKey 接受 hex(64) 或原样 32 字节。
+func parseKey(s string) ([]byte, error) {
+	s = strings.TrimSpace(s)
+	if len(s) == 64 {
+		if b, err := hex.DecodeString(s); err == nil {
+			return b, nil
+		}
+	}
+	if len(s) == 32 {
+		return []byte(s), nil
+	}
+	return nil, fmt.Errorf("长度 %d 非法（需 64 位 hex 或 32 字节）", len(s))
+}
diff --git a/internal/security/key_test.go b/internal/security/key_test.go
new file mode 100644
index 00000000..ab9fccaf
--- /dev/null
+++ b/internal/security/key_test.go
@@ -0,0 +1,253 @@
+package security
+
+// 主密钥管理的判据。
+
+import (
+	"bytes"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestLoadOrCreateKeyCreatesFile0600(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv(EnvKeyName, "") // 确保走磁盘路径
+
+	k1, src, err := LoadOrCreateKey(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(k1) != 32 {
+		t.Fatalf("密钥应 32 字节，实际 %d", len(k1))
+	}
+	p := filepath.Join(dir, KeyFileName)
+	if src != p {
+		t.Errorf("来源应为密钥文件，实际 %q", src)
+	}
+	fi, err := os.Stat(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fi.Mode().Perm() != 0o600 {
+		t.Errorf("密钥文件必须 0600，实际 %04o", fi.Mode().Perm())
+	}
+
+	// 再次调用必须得到**同一把**密钥（否则每次重启都解不开旧变量）
+	k2, _, err := LoadOrCreateKey(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(k1) != string(k2) {
+		t.Fatal("重启后密钥必须一致")
+	}
+}
+
+// ★ 环境变量优先（生产用 systemd 注入）。
+func TestEnvKeyTakesPrecedence(t *testing.T) {
+	dir := t.TempDir()
+	want := "aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"
+	t.Setenv(EnvKeyName, want)
+
+	k, src, err := LoadOrCreateKey(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if src != EnvKeyName {
+		t.Errorf("来源应为环境变量，实际 %q（不应落盘）", src)
+	}
+	if hexEncode(k) != want {
+		t.Errorf("密钥不符: %s", hexEncode(k))
+	}
+	// 不应因此创建文件
+	if _, err := os.Stat(filepath.Join(dir, KeyFileName)); !os.IsNotExist(err) {
+		t.Error("用环境变量时不应创建密钥文件")
+	}
+}
+
+// ★ 判据：密钥文件权限宽松 ⇒ 拒绝启动（响亮失败）。
+func TestRejectsLooseKeyFilePerms(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv(EnvKeyName, "")
+	p := filepath.Join(dir, KeyFileName)
+	if err := os.WriteFile(p, []byte("aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := LoadOrCreateKey(dir); err == nil {
+		t.Fatal("0644 的密钥文件必须被拒绝")
+	}
+}
+
+// ★ 环境变量格式非法 ⇒ 拒绝（不悄悄忽略）。
+func TestRejectsMalformedEnvKey(t *testing.T) {
+	t.Setenv(EnvKeyName, "tooshort")
+	if _, _, err := LoadOrCreateKey(t.TempDir()); err == nil {
+		t.Fatal("非法密钥长度必须报错")
+	}
+}
+
+func TestParseKeyAcceptsHexAndRaw32(t *testing.T) {
+	// 64 位 hex → 32 字节
+	k, err := parseKey("aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899")
+	if err != nil || len(k) != 32 {
+		t.Fatalf("hex 解析失败: %v len=%d", err, len(k))
+	}
+	// 32 字节原文
+	k2, err := parseKey("0123456789abcdef0123456789abcdef")
+	if err != nil || len(k2) != 32 {
+		t.Fatalf("原样 32 字节解析失败: %v", err)
+	}
+	if string(k2) != "0123456789abcdef0123456789abcdef" {
+		t.Error("原样 32 字节应保持原值")
+	}
+	// 长度非法
+	if _, err := parseKey("short"); err == nil {
+		t.Error("长度非法必须报错")
+	}
+}
+
+// ★★ 判据：**用错密钥必须响亮失败**，不能静默重建库。
+//
+// 这是最危险的静默降级：密钥换了若不报错，看起来一切正常，
+// 实际所有凭据都解不开 —— 而 agent 会继续用别名去调用，全线失败。
+func TestWrongKeyFailsLoudly(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)
+	}
+
+	// 换一把密钥重新加载（模拟密钥丢失/轮换失误）
+	other := func() ([]byte, error) { return []byte("ffffffffffffffffffffffffffffffff"), nil }
+	s2 := New(Options{Path: p, KeyFn: other, Enabled: true})
+	if err := s2.Load(); err != nil {
+		t.Fatalf("加载本身应成功（只是解不开）: %v", err)
+	}
+	// ★ 回填必须失败（返回原文，不 panic、不吐垃圾）
+	out, n, _ := s2.Fill("x=@{" + alias + "}")
+	if n != 0 {
+		t.Errorf("用错密钥时不应回填成功，实际 n=%d out=%q", n, out)
+	}
+	if out != "x=@{"+alias+"}" {
+		t.Errorf("用错密钥应原样保留引用（可诊断），实际 %q", out)
+	}
+	// 记录仍在（没被静默清空）
+	if s2.Count() != 1 {
+		t.Errorf("用错密钥不应清空记录，实际 %d 条", s2.Count())
+	}
+}
+
+// ★ 判据：库文件损坏必须报错，**不静默重建**（"不静默重建"）。
+func TestCorruptStoreFailsLoudly(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "v.json")
+	if err := os.WriteFile(p, []byte("{not json"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s := New(Options{Path: p, KeyFn: testKey, Enabled: true})
+	if err := s.Load(); err == nil {
+		t.Fatal("损坏的变量库必须报错，不能静默重建")
+	}
+}
+
+// ★ 首次启动（文件不存在）不是错误。
+func TestMissingStoreIsNotError(t *testing.T) {
+	s := New(Options{Path: filepath.Join(t.TempDir(), "nope.json"), KeyFn: testKey, Enabled: true})
+	if err := s.Load(); err != nil {
+		t.Fatalf("首次启动不应报错: %v", err)
+	}
+	if s.Count() != 0 {
+		t.Error("新库应为空")
+	}
+}
+
+// ---------------- E-4：systemd 凭据生产注入 ----------------
+
+// ★ 判据：systemd 凭据目录被设置且凭据存在 ⇒ 用它（且**优先于 env**）。
+func TestSystemdCredentialIsPreferred(t *testing.T) {
+	dir := t.TempDir()
+	cred := make([]byte, 32)
+	for i := range cred {
+		cred[i] = byte(i + 1)
+	}
+	want := hex.EncodeToString(cred)
+	if err := os.WriteFile(filepath.Join(dir, CredentialName), []byte(want), 0o400); err != nil {
+		t.Fatal(err)
+	}
+	// 同时设一个**不同的** env，验证凭据优先
+	t.Setenv(CredentialDirEnv, dir)
+	t.Setenv(EnvKeyName, strings.Repeat("ff", 32))
+
+	key, src, err := LoadOrCreateKey(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(src, "systemd") {
+		t.Errorf("来源应标明 systemd 凭据，实际 %q", src)
+	}
+	if !bytes.Equal(key, cred) {
+		t.Error("★ 应取 systemd 凭据的值，而不是 env 的值（env 对同用户进程可见）")
+	}
+}
+
+// ★★ 判据：凭据目录设置但**凭据缺失** ⇒ 响亮失败，**不得**静默回退到磁盘密钥。
+//
+// 为何重要：静默回退会让「忘记配凭据」表现成「一切正常」，
+// 而实际用的是磁盘上的旧密钥 —— 本模块最怕的静默降级。
+func TestMissingSystemdCredentialFailsLoudly(t *testing.T) {
+	dir := t.TempDir() // 空目录：没有凭据文件
+	t.Setenv(CredentialDirEnv, dir)
+	t.Setenv(EnvKeyName, "")
+
+	dataDir := t.TempDir()
+	// 磁盘上放一把**可用**的密钥 —— 诱惑实现去回退
+	diskKey := hex.EncodeToString(bytes.Repeat([]byte{0xAB}, 32))
+	if err := os.WriteFile(filepath.Join(dataDir, KeyFileName), []byte(diskKey), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	_, _, err := LoadOrCreateKey(dataDir)
+	if err == nil {
+		t.Fatal("★ 凭据缺失却成功返回 —— 静默回退到了磁盘密钥")
+	}
+	if !strings.Contains(err.Error(), "拒绝静默回退") {
+		t.Errorf("错误应说明拒绝回退，实际: %v", err)
+	}
+}
+
+// ★ 判据：凭据内容格式非法 ⇒ 响亮失败（不当作空串）。
+func TestBadSystemdCredentialFailsLoudly(t *testing.T) {
+	dir := t.TempDir()
+	os.WriteFile(filepath.Join(dir, CredentialName), []byte("not-a-valid-key"), 0o400)
+	t.Setenv(CredentialDirEnv, dir)
+	t.Setenv(EnvKeyName, "")
+
+	if _, _, err := LoadOrCreateKey(t.TempDir()); err == nil {
+		t.Fatal("格式非法应报错")
+	}
+}
+
+// ★ 判据：没设凭据目录时，行为与从前一致（env > 文件）—— 不能破坏开发机路径。
+func TestNoCredentialDirFallsBackToEnv(t *testing.T) {
+	t.Setenv(CredentialDirEnv, "")
+	want := strings.Repeat("cd", 32)
+	t.Setenv(EnvKeyName, want)
+
+	key, src, err := LoadOrCreateKey(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if src != EnvKeyName {
+		t.Errorf("来源应为 %s，实际 %q", EnvKeyName, src)
+	}
+	if hex.EncodeToString(key) != want {
+		t.Error("应取 env 的值")
+	}
+}
diff --git a/internal/security/keyring.go b/internal/security/keyring.go
new file mode 100644
index 00000000..ccf02ae2
--- /dev/null
+++ b/internal/security/keyring.go
@@ -0,0 +1,138 @@
+package security
+
+// 密钥环持久化（E-1）。
+//
+// 主密钥轮换不能只替换 security.key：变量库与 config.db 里已有密文仍由旧钥
+// 加密。keyring 文件保存「当前钥 + 历史只读钥」，权限 0600；进程启动时把
+// 历史钥装入 Store/Codec，读旧密文，写新密文。
+
+import (
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+)
+
+const KeyringFileName = "security.keyring"
+
+type keyringFile struct {
+	Current string   `json:"current"`
+	History []string `json:"history,omitempty"`
+}
+
+// LoadKeyring 读取持久化密钥环。没有 keyring 时返回 current 和空 history，
+// 保持已有 security.key 部署完全兼容。
+func LoadKeyring(dataDir string, current []byte) ([][]byte, error) {
+	path := filepath.Join(dataDir, KeyringFileName)
+	b, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	if fi, err := os.Stat(path); err == nil && fi.Mode().Perm() != 0o600 {
+		return nil, fmt.Errorf("security: 密钥环权限不安全：%s 是 %04o，必须是 0600", path, fi.Mode().Perm())
+	}
+	var f keyringFile
+	if err := json.Unmarshal(b, &f); err != nil {
+		return nil, fmt.Errorf("security: 密钥环损坏: %w", err)
+	}
+	if f.Current != "" {
+		k, err := parseKey(f.Current)
+		if err != nil {
+			return nil, fmt.Errorf("security: 密钥环 current 无效: %w", err)
+		}
+		// ★ 内嵌钥场景：keyring 的 current 是**旧的磁盘钥**，而本进程当前钥是内嵌钥。
+		// 这不是「选错钥」，而是「密钥来源升级了」——必须把 keyring current
+		// 当作**额外解密钥**保留（否则它加的密文全读不出来），而不是拒绝启动。
+		//
+		// 为何不能按旧逻辑 Fatal：内嵌的目的就是防丢；一个"有 keyring 的老机器
+		// 升级到内嵌二进制就再也起不来"的行为，恰好造成它要防的那个后果。
+		if !sameKey(k, current) && EmbeddedKeyPresent() {
+			log.Printf("[security] 密钥环 current 与当前（内嵌）钥不同——"+
+				"按**额外解密钥**保留，旧密文仍可读: %s", filepath.Join(dataDir, KeyringFileName))
+			return appendHistoryKeys(f.History, current, k)
+		}
+		if len(current) != 32 || !sameKey(k, current) {
+			return nil, fmt.Errorf("security: security.key 与密钥环 current 不一致（拒绝静默选错钥）")
+		}
+	}
+	var old [][]byte
+	for i, raw := range f.History {
+		k, err := parseKey(raw)
+		if err != nil {
+			return nil, fmt.Errorf("security: 密钥环 history[%d] 无效: %w", i, err)
+		}
+		if !sameKey(k, current) {
+			old = append(old, k)
+		}
+	}
+	return old, nil
+}
+
+// RotateKeyFile 原子地把 current 换成 newKey，并把旧 current 放入 history。
+// 调用方随后应以 newKey + 返回的旧钥初始化 Store/Codec，并执行数据重加密。
+func RotateKeyFile(dataDir string, current, newKey []byte) error {
+	if len(current) != 32 || len(newKey) != 32 {
+		return fmt.Errorf("security: 轮换钥匙必须都是 32 字节")
+	}
+	path := filepath.Join(dataDir, KeyringFileName)
+	f := keyringFile{Current: hex.EncodeToString(newKey), History: []string{hex.EncodeToString(current)}}
+	if b, err := os.ReadFile(path); err == nil {
+		var old keyringFile
+		if json.Unmarshal(b, &old) == nil {
+			f.History = append(f.History, old.History...)
+		}
+	}
+	data, err := json.MarshalIndent(f, "", "  ")
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(dataDir, 0o700); err != nil {
+		return err
+	}
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, data, 0o600); err != nil {
+		return err
+	}
+	if err := os.Chmod(tmp, 0o600); err != nil {
+		return err
+	}
+	return os.Rename(tmp, path)
+}
+
+// appendHistoryKeys 把 history 全部、加上 extra 里不等于 current 的钥，组成解密集合。
+//
+// 与正常路径的区别：正常情况下 `current` 必须是 keyring 的 current；
+// 内嵌升级场景下 keyring current 反而成为"额外钥"，
+// 于是解密集合 = history + keyring.current。
+func appendHistoryKeys(history []string, current, extra []byte) ([][]byte, error) {
+	var out [][]byte
+	if len(extra) == 32 && !sameKey(extra, current) {
+		out = append(out, extra)
+	}
+	for i, raw := range history {
+		k, err := parseKey(raw)
+		if err != nil {
+			return nil, fmt.Errorf("security: 密钥环 history[%d] 无效: %w", i, err)
+		}
+		if !sameKey(k, current) {
+			out = append(out, k)
+		}
+	}
+	return out, nil
+}
+
+func sameKey(a, b []byte) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	var x byte
+	for i := range a {
+		x |= a[i] ^ b[i]
+	}
+	return x == 0
+}
diff --git a/internal/security/patterns.go b/internal/security/patterns.go
new file mode 100644
index 00000000..ede40f27
--- /dev/null
+++ b/internal/security/patterns.go
@@ -0,0 +1,135 @@
+package security
+
+// 敏感信息模式库。
+//
+// ## 设计原则：**宁可漏，不可误伤**（文档 S4）
+//
+// 误报比漏报严重得多：它会把正常文本换成别名提示、把任务搞坏，
+// 而且现象会出现在很后面（agent 拿到错误的参数），归因极难。
+// 所以每条规则都要求**强特征**（固定前缀 + 长度 + 字符集），不用泛化启发式。
+//
+// ## 覆盖范围
+//
+// 主流平台的访问令牌 + 常见凭据形态（赋值语句、私钥块、认证头）。
+
+import (
+	"encoding/base64"
+	"regexp"
+	"strings"
+)
+
+// Pattern 是一条识别规则。
+type Pattern struct {
+	Name string
+	RE   *regexp.Regexp
+
+	// Prefilter 是**必含的字面量**：不含它就一定不匹配，可直接跳过 RE。
+	//
+	// ★ 为什么需要（实测的性能缺陷）：本文件所有模式都以 `\b` 开头，
+	// 而 Go 的 RE2 对 `\b` 要逐 rune 做 Unicode 词边界判定 ——
+	// 实测 50KB 文本上**单条模式 660µs**，9 条合计 ~6ms；
+	// 而同样形状但去掉 `\b` 的模式只需 **1.6µs（快 400 倍）**。
+	//
+	// `\b` 不能删（它防 `xghp_xxx` 这类误伤，见 boundary_need_test.go），
+	// 所以改为**先用 O(n) 的字面量包含检查快速排除**：
+	// 绝大多数文本根本不含 `ghp_`/`glpat-` 等前缀，连正则都不用跑。
+	//
+	// 空串表示"没有可用前缀"，那就直接跑正则（这类模式本身很快）。
+	//
+	// ★ 支持**多个候选**（用 `|` 分隔，任一中即放行）——
+	// 因为有些模式的正则本身有多个备选分支（如 assigned_secret 的
+	// `[:=]`）。初版只允许单个前缀，于是把 `:` 当 prefilter 后
+	// `api_key = "..."` 就被挡在外面 ⇒ **漏报**。
+	//
+	// 规则：prefilter 的候选集**必须覆盖**正则里所有"必含"的字面量分支。
+	// `TestPrefilterCoversAllAlternatives` 逐个形态验证这一点。
+	Prefilter string
+}
+
+// prefilterAlternatives 把 Prefilter 拆成候选列表。
+func (p Pattern) prefilterAlternatives() []string {
+	if p.Prefilter == "" {
+		return nil
+	}
+	return strings.Split(p.Prefilter, "|")
+}
+
+// matchesPrefilter 报告文本是否**可能**匹配该模式。
+//
+// 返回 false ⇒ 一定不匹配，可安全跳过正则。
+// 返回 true  ⇒ 可能匹配，需跑正则确认。
+//
+// ★ 保守方向必须是"宁可漏判为可能"：前缀检查只用来**排除**，
+// 不能用来**认定** —— 认定仍交给正则（S4：宁可漏，不可误伤）。
+func (p Pattern) matchesPrefilter(text string) bool {
+	alts := p.prefilterAlternatives()
+	if len(alts) == 0 {
+		return true // 没有前缀可依，交给正则
+	}
+	for _, a := range alts {
+		if a != "" && strings.Contains(text, a) {
+			return true
+		}
+	}
+	return false
+}
+
+// Patterns 是内置模式库。
+//
+// 排序无要求（每条独立替换）。
+var Patterns = []Pattern{
+	// —— 平台访问令牌（强前缀，几乎不会误伤）——
+	// GitHub: ghp_/gho_/ghu_/ghs_/ghr_ + 36 位
+	{Name: "github_token", RE: regexp.MustCompile(`\bgh[pousr]_[A-Za-z0-9]{36}\b`), Prefilter: "gh"},
+	// GitHub fine-grained
+	{Name: "github_fine_grained", RE: regexp.MustCompile(`\bgithub_pat_[A-Za-z0-9_]{60,}\b`), Prefilter: "github_pat_"},
+	// GitLab
+	{Name: "gitlab_token", RE: regexp.MustCompile(`\bglpat-[A-Za-z0-9_-]{20,}\b`), Prefilter: "glpat-"},
+	// OpenAI
+	{Name: "openai_key", RE: regexp.MustCompile(`\bsk-(proj-)?[A-Za-z0-9_-]{20,}\b`), Prefilter: "sk-"},
+	// Anthropic
+	{Name: "anthropic_key", RE: regexp.MustCompile(`\bsk-ant-[A-Za-z0-9_-]{20,}\b`), Prefilter: "sk-ant-"},
+	// AWS Access Key ID
+	{Name: "aws_access_key", RE: regexp.MustCompile(`\b(AKIA|ASIA)[0-9A-Z]{16}\b`), Prefilter: "A"},
+	// Slack
+	{Name: "slack_token", RE: regexp.MustCompile(`\bxox[baprs]-[A-Za-z0-9-]{10,}\b`), Prefilter: "xox"},
+	// 认证头里的长 token
+	{Name: "bearer_token", RE: regexp.MustCompile(`(?i)\bBearer\s+[A-Za-z0-9._\-]{30,}`), Prefilter: "earer"},
+
+	// —— 私钥块（多行；单独一条，因为长度阈值不同）——
+	{Name: "private_key_block", RE: regexp.MustCompile(
+		`-----BEGIN [A-Z0-9 ]*PRIVATE KEY[A-Z ]*-----[\s\S]{64,}?-----END [A-Z0-9 ]*PRIVATE KEY[A-Z ]*-----`), Prefilter: "-----BEGIN"},
+
+	// —— 赋值语句里的长密钥 ——
+	//
+	// ⚠️ 这条最容易误伤，所以限制得很死：
+	//   · 键名必须是明确的凭据词（api_key / token / password …）
+	//   · 值必须有 16+ 位、且是常见的密钥字符集
+	// （像 `version = "1.2.3"`、`name = "hello"` 都不会命中）
+	// assigned_secret 没有**单一**字面量前缀（它匹配多种键名）。
+	//
+	// ★ prefilter 必须覆盖正则里的**两种**分隔符（`:` 与 `=`）——
+	// 初版只写 `"="`，于是 `password: "..."`（冒号形态）被 prefilter
+	// 静默挡住 ⇒ **漏报**。这个 bug 是"盘点什么没被拦"时发现的：
+	// 判据样本恰好用了 `=`，所以测试全绿而真实场景有洞。
+	//
+	// 现在用 `":"` 作 prefilter（冒号在 JSON/YAML/日志里更常见），
+	// 并由 TestPrefilterCoversAllAlternatives 逐个分隔符验证。
+	{Name: "assigned_secret", Prefilter: ":|=",
+		RE: regexp.MustCompile(
+			`(?i)\b(api[_-]?key|access[_-]?token|auth[_-]?token|secret[_-]?key|client[_-]?secret|password|passwd)\b\s*[:=]\s*["']?([A-Za-z0-9/+_\-]{16,})["']?`)},
+}
+
+// 注意：**刻意不包含**"裸的 40 位 hex"（Gitea token 形状）。
+//
+// 为什么：40 位 hex 与 git SHA-1（commit id）**形态完全相同**。
+// 把 commit hash 换成别名提示会直接把任务搞坏（agent 拿不到正确的 SHA）。
+// 这是"宁可漏，不可误伤"的典型取舍：
+//   · 漏掉：Gitea token 在裸文本里没被拦（但它通常会出现在赋值语句里，被上一条覆盖）
+//   · 误伤：每个 commit id 都变成别名提示 —— 后果严重得多
+
+// ---------------- base64 辅助（集中一处，便于审计） ----------------
+
+func encodeB64(b []byte) string { return base64.StdEncoding.EncodeToString(b) }
+
+func decodeB64(s string) ([]byte, error) { return base64.StdEncoding.DecodeString(s) }
diff --git a/internal/security/prefilter_test.go b/internal/security/prefilter_test.go
new file mode 100644
index 00000000..f7b6ba5f
--- /dev/null
+++ b/internal/security/prefilter_test.go
@@ -0,0 +1,210 @@
+package security
+
+// 前置过滤（Prefilter）的判据。
+//
+// ## 为什么需要它 + 为什么必须单独验
+//
+// 加 prefilter 是为了修一个**实测的性能缺陷**：所有模式以 `\b` 开头，
+// 而 Go 的 RE2 对 `\b` 要逐 rune 判定 —— 50KB 文本上单条 660µs，
+// 9 条合计 ~6ms。常被调用的路径（每次 LLM 调用、每次工具调用）
+// 白付这个成本。加字面量前缀后降到 10µs（~400×）。
+//
+// ★ 但优化有个致命风险：**prefilter 若与正则的必含字符不一致，
+// 就会造成漏报** —— 而漏报（凭据没被拦下）比性能差严重得多，
+// 且**不会报错**，只会在某天出事时才发现。
+//
+// 所以本文件逐条验证：「正则能匹配的文本，prefilter 一定放行」。
+
+import (
+	"strings"
+	"testing"
+)
+
+// ★★ 判据：**每一条模式的 prefilter 都必须是该模式真会匹配的文本的子串**。
+//
+// 做法：为每条模式准备一份"应命中"样本，断言
+//
+//	① 正则确实命中它
+//	② prefilter 也放行它
+//
+// 若 ② 失败 ⇒ 该样本永远被 prefilter 挡在门外 ⇒ **漏报**。
+func TestPrefilterNeverBlocksRealMatches(t *testing.T) {
+	samples := map[string]string{
+		"github_token":        "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
+		"github_fine_grained": "github_pat_" + strings.Repeat("A", 60),
+		"gitlab_token":        "glpat-FAKE-TEST-TOKEN-NOT-REAL",
+		"openai_key":          "sk-FAKE-TEST-KEY-NOT-REAL-0000000",
+		"anthropic_key":       "sk-ant-FAKE-TEST-KEY-NOT-REAL-00",
+		"aws_access_key":      "AKIA0000FAKE0000TEST",
+		"slack_token":         "xoxb-FAKE-TEST-TOKEN-NOT-REAL",
+		"bearer_token":        "Bearer FAKE-TEST-BEARER-TOKEN-NOT-REAL",
+		"private_key_block": "-----BEGIN RSA PRIVATE KEY-----\n" +
+			strings.Repeat("MIIEowIBAAKCAQEA", 8) + "\n-----END RSA PRIVATE KEY-----",
+		"assigned_secret": `api_key = "FAKE-TEST-ASSIGNED-VALUE-000"`,
+	}
+
+	for _, p := range Patterns {
+		sample, ok := samples[p.Name]
+		if !ok {
+			t.Errorf("模式 %s 没有样本 —— 新增模式时必须补样本（否则判据会漏掉它）", p.Name)
+			continue
+		}
+		// ① 正则必须命中
+		if !p.RE.MatchString(sample) {
+			t.Errorf("模式 %s 的正则不匹配它的样本（样本过期了？）: %q", p.Name, sample)
+			continue
+		}
+		// ② prefilter 必须放行（否则这条永远漏报）
+		if !p.matchesPrefilter(sample) {
+			t.Errorf("★ 模式 %s 的 prefilter %q 挡住了自己的样本 %q —— 会造成**静默漏报**",
+				p.Name, p.Prefilter, sample)
+		}
+	}
+}
+
+// ★★ 判据：**反向** —— prefilter 挡下的文本，正则确实不该匹配。
+//
+// 这一条防的是"prefilter 太宽"吗？不是 —— 太宽只会变慢，不会出错。
+// 它防的是相反的错误：有人把 prefilter 写成**排除式**（如"不含 X 才跑"），
+// 那就反了。这里给出一个"不含任何前缀"的文本，断言：
+//
+//	跳过它不会漏掉任何真命中（即正则对它本来就不匹配）。
+func TestPrefilterSkipIsSafe(t *testing.T) {
+	benign := "这是一段普通的技术讨论：架构、实现、测试与部署。没有凭据。"
+	for _, p := range Patterns {
+		if p.matchesPrefilter(benign) {
+			continue // 放行也无妨（会跑正则，只是慢）
+		}
+		if p.RE.MatchString(benign) {
+			t.Errorf("★ 模式 %s 被 prefilter 跳过，但正则其实匹配这段文本 —— 漏报！",
+				p.Name)
+		}
+	}
+}
+
+// ★ 判据：**大文本下的正确性**（prefilter 在长文本上不能出错）。
+//
+// 慢路径 bug 常在边界出现：prefilter 命中但在文本很靠后的位置。
+func TestPrefilterWorksDeepInLargeText(t *testing.T) {
+	s := newTestStore(t, true)
+	const tok = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	// 把 token 埋在 50KB 文本的**中间**
+	pad := strings.Repeat("普通技术讨论内容，不含凭据。", 1500)
+	text := pad[:len(pad)/2] + " token=" + tok + " " + pad[len(pad)/2:]
+
+	out, evts := s.Replace(text, "bench", Patterns)
+	if len(evts) == 0 {
+		t.Fatal("★ 埋在长文本中段的凭据未被识别（prefilter 在长文本上漏报）")
+	}
+	if strings.Contains(out, tok) {
+		t.Fatal("明文未被替换")
+	}
+	if len(evts[0].Alias) != 20 {
+		t.Errorf("别名形态异常: %s", evts[0].Alias)
+	}
+}
+
+// ★★ 判据：**prefilter 必须覆盖正则里所有"必含"的备选分支**。
+//
+// ## 这条判据的由来（真实漏报）
+//
+// `assigned_secret` 的正则是 `\b(...)\b\s*[:=]\s*...` —— 分隔符有
+// **两个**备选（`:` 与 `=`）。初版 prefilter 只写 `"="`，于是
+// `password: "hunter2..."`（冒号形态）被 prefilter 静默挡住 ⇒ **漏报**。
+//
+// 更值得记的是**为什么没被发现**：当时的判据样本恰好用了 `=`，
+// 所以测试全绿 —— 判据覆盖了"能用的形态"，漏了"另一种同样合法的形态"。
+//
+// ⇒ 现在逐形态验证：正则支持的每种写法，prefilter 都必须放行。
+func TestPrefilterCoversAllAlternatives(t *testing.T) {
+	// 每个形态都**必须是正则能匹配的**，且 prefilter 必须放行。
+	forms := map[string][]string{
+		"assigned_secret": {
+			`api_key = "FAKE-TEST-ASSIGNED-VALUE-000"`, // =
+			`api_key: "FAKE-TEST-ASSIGNED-VALUE-000"`,  // :
+			`password="FAKE-TEST-TOKEN-NOT-REAL-001234"`,
+			`password:'FAKE-TEST-TOKEN-NOT-REAL-001234'`,
+			`access_token = FAKE-TEST-TOKEN-NOT-REAL-0012`,
+			`client_secret: FAKE-TEST-TOKEN-NOT-REAL-0012`,
+			`auth_token := FAKE-TEST-TOKEN-NOT-REAL-00123`,
+			`secret_key = FAKE-TEST-TOKEN-NOT-REAL-0012345`,
+			`passwd = FAKE-TEST-ASSIGNED-VALUE-000`,
+		},
+	}
+
+	for name, samples := range forms {
+		var pat *Pattern
+		for i := range Patterns {
+			if Patterns[i].Name == name {
+				pat = &Patterns[i]
+				break
+			}
+		}
+		if pat == nil {
+			t.Fatalf("找不到模式 %s", name)
+		}
+		for _, sample := range samples {
+			if !pat.RE.MatchString(sample) {
+				// 样本本身不被正则支持 —— 那是样本写错了，不是漏报
+				t.Logf("  （正则不支持该形态，跳过）%q", sample)
+				continue
+			}
+			if !pat.matchesPrefilter(sample) {
+				t.Errorf("★ 模式 %s 的 prefilter %q 挡住了**正则能匹配**的形态 %q —— 静默漏报",
+					name, pat.Prefilter, sample)
+			}
+		}
+	}
+}
+
+// ★ 判据：多候选 prefilter 的"任一命中即放行"语义。
+func TestPrefilterAlternativesSemantics(t *testing.T) {
+	p := Pattern{Name: "t", Prefilter: "a|bb|ccc"}
+
+	if !p.matchesPrefilter("xax") {
+		t.Error("含第一个候选应放行")
+	}
+	if !p.matchesPrefilter("xbbx") {
+		t.Error("含第二个候选应放行")
+	}
+	if !p.matchesPrefilter("xcccx") {
+		t.Error("含第三个候选应放行")
+	}
+	if p.matchesPrefilter("none of them") {
+		t.Error("一个都不含时不应放行")
+	}
+	// 空候选要忽略（防 `"a||b"` 这种写法把空串当"总匹配"）
+	p2 := Pattern{Name: "t2", Prefilter: "a||b"}
+	if p2.matchesPrefilter("zzz") {
+		t.Error("空候选不该被当成匹配（否则 prefilter 形同虚设）")
+	}
+	// 空 prefilter = 总放行（交给正则）
+	p3 := Pattern{Name: "t3", Prefilter: ""}
+	if !p3.matchesPrefilter("anything") {
+		t.Error("无 prefilter 时应总放行")
+	}
+}
+
+// ★ 判据：**prefilter 必须真的起作用**（否则优化是空谈）。
+//
+// 用一个只含无关字符的大文本，断言它比"含前缀"的文本快一个数量级。
+// 这条是"优化没有偷偷失效"的哨兵。
+func TestPrefilterActuallySkipsWork(t *testing.T) {
+	p := Patterns[0] // github_token
+	// 找一条有 prefilter 的模式
+	for _, q := range Patterns {
+		if q.Prefilter != "" {
+			p = q
+			break
+		}
+	}
+	if p.Prefilter == "" {
+		t.Skip("没有带 prefilter 的模式")
+	}
+	benign := strings.Repeat("普通文本，无凭据。", 1000)
+	if p.matchesPrefilter(benign) {
+		t.Errorf("模式 %s 的 prefilter %q 不该在无关文本上放行（优化失效）",
+			p.Name, p.Prefilter)
+	}
+}
diff --git a/internal/security/rotation_test.go b/internal/security/rotation_test.go
new file mode 100644
index 00000000..41487ce5
--- /dev/null
+++ b/internal/security/rotation_test.go
@@ -0,0 +1,184 @@
+package security
+
+import (
+	"bytes"
+	"os"
+	"strings"
+	"testing"
+)
+
+func rotationKey(fill byte) []byte { return bytes.Repeat([]byte{fill}, 32) }
+
+// ★ E-1：轮换后既有别名**不变**、旧值仍可回填。
+func TestRotateKeyPreservesAliasesAndReadsOldEntries(t *testing.T) {
+	dir := t.TempDir()
+	oldKey, newKey := rotationKey(0x11), rotationKey(0x22)
+	s := New(Options{Path: dir + "/variables.json", KeyFn: func() ([]byte, error) { return oldKey, nil }, Enabled: true})
+	if err := s.Load(); err != nil {
+		t.Fatal(err)
+	}
+	alias, err := s.Submit("SUPER_SECRET", "rotation")
+	if err != nil {
+		t.Fatal(err)
+	}
+	before, _, _ := s.Fill("@{" + alias + "}")
+	if before != "SUPER_SECRET" {
+		t.Fatalf("轮换前回填失败: %q", before)
+	}
+	if err := s.RotateKey(newKey); err != nil {
+		t.Fatal(err)
+	}
+	after, _, _ := s.Fill("@{" + alias + "}")
+	if after != "SUPER_SECRET" {
+		t.Fatalf("★ 轮换后旧别名/旧值不可用: %q", after)
+	}
+	alias2, err := s.Alias("SUPER_SECRET")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if alias2 != alias {
+		t.Fatalf("★ 轮换改变了别名: before=%s after=%s", alias, alias2)
+	}
+	if !strings.Contains(string(mustRead(t, dir+"/variables.json")), alias) {
+		t.Fatal("轮换落盘缺少旧别名")
+	}
+}
+
+// ★ 轮换落盘后重启：只注入 new + old ring，也必须能回填旧条目。
+func TestRotatedStoreRestartsWithOldKeyRing(t *testing.T) {
+	dir := t.TempDir() + "/variables.json"
+	oldKey, newKey := rotationKey(0x31), rotationKey(0x32)
+	s := New(Options{Path: dir, KeyFn: func() ([]byte, error) { return oldKey, nil }, Enabled: true})
+	if err := s.Load(); err != nil {
+		t.Fatal(err)
+	}
+	alias, err := s.Submit("ROTATE_ME", "restart")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := s.RotateKey(newKey); err != nil {
+		t.Fatal(err)
+	}
+	// 新进程：current=new，history=old。
+	s2 := New(Options{Path: dir, KeyFn: func() ([]byte, error) { return newKey, nil }, OldKeys: [][]byte{oldKey}, Enabled: true})
+	if err := s2.Load(); err != nil {
+		t.Fatal(err)
+	}
+	got, _, _ := s2.Fill("@{" + alias + "}")
+	if got != "ROTATE_ME" {
+		t.Fatalf("重启后历史密钥环无法解密: %q", got)
+	}
+}
+
+// ★ 没有旧钥环时换钥必须响亮失败，而不是把库当成空库重建。
+func TestRotateKeyRefusesWrongCurrentKey(t *testing.T) {
+	dir := t.TempDir() + "/variables.json"
+	oldKey := rotationKey(0x41)
+	s := New(Options{Path: dir, KeyFn: func() ([]byte, error) { return oldKey, nil }, Enabled: true})
+	if err := s.Load(); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.Submit("DO_NOT_LOSE", "wrong-key"); err != nil {
+		t.Fatal(err)
+	}
+	wrong := New(Options{Path: dir, KeyFn: func() ([]byte, error) { return rotationKey(0x42), nil }, Enabled: true})
+	if err := wrong.Load(); err != nil {
+		t.Fatal(err)
+	}
+	if err := wrong.RotateKey(rotationKey(0x43)); err == nil {
+		t.Fatal("★ 错钥轮换却成功 —— 可能静默丢数据")
+	}
+}
+
+func mustRead(t *testing.T, path string) []byte {
+	t.Helper()
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b
+}
+
+// ★ keyring 文件：轮换后重启必须能自动装回历史钥（否则 E-1 只是"能轮换一次"）。
+func TestKeyringPersistAndRestart(t *testing.T) {
+	dir := t.TempDir()
+	oldKey, newKey := rotationKey(0x51), rotationKey(0x52)
+	if err := RotateKeyFile(dir, oldKey, newKey); err != nil {
+		t.Fatal(err)
+	}
+	history, err := LoadKeyring(dir, newKey)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(history) != 1 || !sameKey(history[0], oldKey) {
+		t.Fatalf("历史钥未装回: %v", history)
+	}
+	// 与 security.key 不一致时必须拒绝（否则会拿错钥去解，静默丢数据）
+	if _, err := LoadKeyring(dir, rotationKey(0x53)); err == nil {
+		t.Fatal("★ keyring 与 security.key 不一致却未被拒绝")
+	}
+}
+
+// ★ 端到端：轮换 → 重启（只给 new + keyring history）→ 旧条目仍可回填。
+func TestRotationSurvivesRestartViaKeyring(t *testing.T) {
+	dir := t.TempDir()
+	varPath := dir + "/variables.json"
+	oldKey, newKey := rotationKey(0x61), rotationKey(0x62)
+	s := New(Options{Path: varPath, KeyFn: func() ([]byte, error) { return oldKey, nil }, Enabled: true})
+	if err := s.Load(); err != nil {
+		t.Fatal(err)
+	}
+	alias, err := s.Submit("RESTART_SECRET", "e2e")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := s.RotateKey(newKey); err != nil {
+		t.Fatal(err)
+	}
+	if err := RotateKeyFile(dir, oldKey, newKey); err != nil {
+		t.Fatal(err)
+	}
+	history, err := LoadKeyring(dir, newKey)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s2 := New(Options{Path: varPath, KeyFn: func() ([]byte, error) { return newKey, nil }, OldKeys: history, Enabled: true})
+	if err := s2.Load(); err != nil {
+		t.Fatal(err)
+	}
+	got, _, _ := s2.Fill("@{" + alias + "}")
+	if got != "RESTART_SECRET" {
+		t.Fatalf("重启后无法回填: %q", got)
+	}
+}
+
+// ★★ 轮换必须**真的重加密并落盘**：重启时只给新钥（不带任何历史钥）也必须能读。
+//
+// 为何这条不可省：只把旧钥留在环里能让旧密文"看起来还能用"，但磁盘上
+// 仍是旧钥密文 —— 那意味着旧钥永远退不掉，轮换等于没做。
+// 这条判据正是用来咬住"内存换了、磁盘没换"的半轮换。
+func TestRotationPersistsReEncryptionToDisk(t *testing.T) {
+	dir := t.TempDir() + "/variables.json"
+	oldKey, newKey := rotationKey(0x91), rotationKey(0x92)
+	s := New(Options{Path: dir, KeyFn: func() ([]byte, error) { return oldKey, nil }, Enabled: true})
+	if err := s.Load(); err != nil {
+		t.Fatal(err)
+	}
+	alias, err := s.Submit("RE_ENCRYPT_ME", "persist")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := s.RotateKey(newKey); err != nil {
+		t.Fatal(err)
+	}
+
+	// 只有新钥，没有历史钥 —— 能读出来才说明磁盘上已是新钥密文。
+	fresh := New(Options{Path: dir, KeyFn: func() ([]byte, error) { return newKey, nil }, Enabled: true})
+	if err := fresh.Load(); err != nil {
+		t.Fatal(err)
+	}
+	got, _, _ := fresh.Fill("@" + "{" + alias + "}")
+	if got != "RE_ENCRYPT_ME" {
+		t.Fatalf("★ 只用新钥读不出来 ⇒ 轮换没有真正重加密落盘（半轮换）: %q", got)
+	}
+}
diff --git a/internal/security/ssh_fp_test.go b/internal/security/ssh_fp_test.go
new file mode 100644
index 00000000..2144f33d
--- /dev/null
+++ b/internal/security/ssh_fp_test.go
@@ -0,0 +1,50 @@
+package security
+
+import (
+	"strings"
+	"testing"
+)
+
+// ★★ 判据：私钥块规则**不能误伤**。
+//
+// 放宽了尾部词匹配后必须确认：正常文本里的 "PRIVATE KEY" 字样不该被拦。
+func TestSSHKeys_NoFalsePositives(t *testing.T) {
+	s := newTestStore(t, true)
+
+	benign := []struct{ desc, text string }{
+		{"文档里提私钥概念", "私钥文件以 -----BEGIN OPENSSH PRIVATE KEY----- 开头，以对应的 END 行结尾。"},
+		{"只引用头尾两行（无内容）",
+			"-----BEGIN RSA PRIVATE KEY-----\n-----END RSA PRIVATE KEY-----"},
+		{"短内容（< 64 字节）",
+			"-----BEGIN RSA PRIVATE KEY-----\nshortcontent\n-----END RSA PRIVATE KEY-----"},
+		{"讨论 SSH 配置", "把 PRIVATE KEY 权限设成 0600，authorized_keys 用 0644"},
+		{"代码里的常量名", `const PRIVATE_KEY_HEADER = "-----BEGIN"`},
+		{"正常的技术文档", "本章讨论密钥管理与轮换策略，涉及 PRIVATE KEY 的使用规范。"},
+	}
+	for _, c := range benign {
+		out, evts := s.Replace(c.text, "sshfp", Patterns)
+		if len(evts) > 0 {
+			t.Errorf("★ 误伤「%s」: %q → %v", c.desc, c.text, evts)
+		}
+		if out != c.text {
+			t.Errorf("未命中却改动了文本「%s」", c.desc)
+		}
+	}
+	t.Log("✅ 私钥块规则无误伤（含短内容/只引头尾/文档讨论）")
+}
+
+// ★ 判据：真正的长私钥体必须拦（与上面的"短内容"形成对照）。
+func TestSSHKeys_LongBodyIsCaught(t *testing.T) {
+	s := newTestStore(t, true)
+	body := strings.Repeat("MIIEowIBAAKCAQEA7xYz9aBc", 6) // > 64 字节
+	text := "-----BEGIN RSA PRIVATE KEY-----\n" + body + "\n-----END RSA PRIVATE KEY-----"
+
+	out, evts := s.Replace(text, "sshl", Patterns)
+	if len(evts) == 0 {
+		t.Fatal("★ 真实长度的私钥体未被拦截")
+	}
+	if strings.Contains(out, "MIIEowIBAAKCAQEA") {
+		t.Fatal("密钥体残留")
+	}
+	t.Logf("✅ %d 字节密钥体被拦（别名 %s）", len(text), evts[0].Alias)
+}
diff --git a/internal/security/ssh_surface_test.go b/internal/security/ssh_surface_test.go
new file mode 100644
index 00000000..b9c4368e
--- /dev/null
+++ b/internal/security/ssh_surface_test.go
@@ -0,0 +1,62 @@
+package security
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// SSH 相关面的完整盘点：哪些拦、哪些不拦、为什么。
+func TestSSHSurface_Complete(t *testing.T) {
+	s := newTestStore(t, true)
+	home, _ := os.UserHomeDir()
+
+	// 读一份真实 authorized_keys 与 ssh config
+	readIf := func(rel string) string {
+		b, err := os.ReadFile(filepath.Join(home, ".ssh", rel))
+		if err != nil {
+			return ""
+		}
+		return string(b)
+	}
+
+	t.Log("=== 会拦 ===")
+	// ① 私钥文件内容
+	if txt := readIf("id_rsa"); txt != "" {
+		_, evts := s.Replace(txt, "ssh", Patterns)
+		t.Logf("  ✓ 私钥文件内容（%d 字节）→ %d 处拦截", len(txt), len(evts))
+	}
+	// ② ssh-agent 环境变量里的私钥？—— 那只是 socket 路径，不是密钥
+	t.Log("=== 不拦（各有权衡）===")
+	t.Logf("  - %-28s ssh-agent 只是 socket 路径，不含密钥", "SSH_AUTH_SOCK")
+	t.Logf("  - %-28s 公钥不是秘密（可公开）", "authorized_keys")
+	t.Logf("  - %-28s 配置里没有密钥本体", "~/.ssh/config")
+	t.Logf("  - %-28s 拦路径不拦内容；内容被读出时才命中", ".ssh/id_rsa 路径")
+	t.Logf("  - %-28s 无固定形态，与正常 hostname 无区别", "known_hosts")
+
+	// ③ 验证不动 authorized_keys（它是公钥，不该被拦）
+	if txt := readIf("authorized_keys"); txt != "" {
+		out, evts := s.Replace(txt, "ssh", Patterns)
+		if len(evts) > 0 {
+			t.Logf("  ⚠️ authorized_keys 被拦了 %d 处（公钥本可公开，但拦了也不致命）", len(evts))
+		} else if out == txt {
+			t.Log("  ✓ authorized_keys 未被改动（正确：公钥不是秘密）")
+		}
+	}
+}
+
+// ★ 判据：**公钥不该被当私钥拦**（两者形态不同，别混）。
+func TestSSHSurface_PublicKeyNotCaught(t *testing.T) {
+	s := newTestStore(t, true)
+	// 真实的 ed25519 公钥形态
+	pub := "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEa1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8 root@host"
+	if _, evts := s.Replace(pub, "ssh", Patterns); len(evts) > 0 {
+		t.Errorf("★ 公钥被误拦（公钥可公开，拦了会让正常运维操作坏掉）: %v", evts)
+	}
+	// RSA 公钥
+	pub2 := "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDZx user@host"
+	if _, evts := s.Replace(pub2, "ssh", Patterns); len(evts) > 0 {
+		t.Errorf("★ RSA 公钥被误拦: %v", evts)
+	}
+	t.Log("✅ 公钥不被拦（正确的边界）")
+}
diff --git a/internal/security/ssh_test.go b/internal/security/ssh_test.go
new file mode 100644
index 00000000..047c592e
--- /dev/null
+++ b/internal/security/ssh_test.go
@@ -0,0 +1,70 @@
+package security
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// ★ 用**本机真实密钥**验证（比构造样本可靠）。
+func TestSSHKeys_RealFiles(t *testing.T) {
+	s := newTestStore(t, true)
+
+	home, _ := os.UserHomeDir()
+	cands := []string{
+		filepath.Join(home, ".ssh", "id_rsa"),
+		filepath.Join(home, ".ssh", "id_ed25519"),
+		filepath.Join(home, ".ssh", "id_ecdsa"),
+	}
+	found := 0
+	for _, p := range cands {
+		b, err := os.ReadFile(p)
+		if err != nil {
+			continue
+		}
+		found++
+		text := string(b)
+		out, evts := s.Replace(text, "ssh", Patterns)
+		hdr := strings.SplitN(text, "\n", 2)[0]
+		if len(evts) == 0 {
+			t.Errorf("★ %s（%s）**未被拦截** —— 私钥明文会进上下文", filepath.Base(p), hdr)
+			continue
+		}
+		if strings.Contains(out, "PRIVATE KEY") {
+			t.Errorf("★ %s 拦了但密钥内容仍残留", filepath.Base(p))
+		}
+		t.Logf("  ✓ %-14s %-38s → %s", filepath.Base(p), hdr, evts[0].Alias)
+	}
+	if found == 0 {
+		t.Skip("本机没有密钥文件")
+	}
+}
+
+// 覆盖各类真实密钥头的**合成样本**（PEM 与 OpenSSH 都有）。
+func TestSSHKeys_AllHeaderForms(t *testing.T) {
+	s := newTestStore(t, true)
+	body := strings.Repeat("MIIEowIBAAKCAQEA7xYz", 8) +
+		"\n" + strings.Repeat("b3BlbnNzaC1rZXkAAAAB", 8)
+
+	headers := []string{
+		"-----BEGIN PRIVATE KEY-----",     // PKCS#8
+		"-----BEGIN RSA PRIVATE KEY-----", // PKCS#1
+		"-----BEGIN DSA PRIVATE KEY-----",
+		"-----BEGIN EC PRIVATE KEY-----",
+		"-----BEGIN OPENSSH PRIVATE KEY-----",   // 现代 ssh-keygen 默认
+		"-----BEGIN ENCRYPTED PRIVATE KEY-----", // 带口令
+		"-----BEGIN PGP PRIVATE KEY BLOCK-----", // PGP
+		"-----BEGIN SSH2 ENCRYPTED PRIVATE KEY-----",
+	}
+	for _, h := range headers {
+		footer := strings.Replace(h, "BEGIN", "END", 1)
+		text := h + "\n" + body + "\n" + footer
+		_, evts := s.Replace(text, "ssh", Patterns)
+		if len(evts) == 0 {
+			t.Errorf("  ✗ %-42s 未拦截", h)
+		} else {
+			t.Logf("  ✓ %-42s", h)
+		}
+	}
+}
diff --git a/internal/security/store.go b/internal/security/store.go
new file mode 100644
index 00000000..fc157983
--- /dev/null
+++ b/internal/security/store.go
@@ -0,0 +1,667 @@
+// Package security 是内核的**敏感信息防火模块**（Secret Firewall）。
+//
+// 设计文档：docs/zh/kernel-secret-firewall-design.md
+//
+// ## 它做什么
+//
+//	① 拦截    LLM 出向前扫到明文  → 换成 @{别名}
+//	② 加密落盘 明文 AES-GCM 持久化（不落明文）
+//	③ 别名    ★ 哈希键：sec_ + HMAC-SHA256(masterKey, plain)[:8]
+//	④ 回填    插件调用（toolcall / outputch）前，把 @{别名} 换回明文
+//
+// ## 三条不可让步的约束（文档 §3）
+//
+//	S1  不提供"取回明文"的任何接口 —— 只能**替代引用**。
+//	    一旦有取回路径，LLM 就能把明文写回上下文，整层作废。
+//	S3  别名必须 HMAC 派生，**不能裸哈希**：别名会进上下文/日志/记忆，
+//	    裸哈希对弱口令可被字典枚举（实测 hunter2 当场命中）。
+//	    也**不加 salt** —— 加了就失去合并能力（确定性是特性）。
+//	S10 变量系统**全局唯一**：主 / 子 / 驻留子 agent 同一套。
+//
+// ## 为什么是"全局单例"
+//
+// 已核：驻留子共享父的 ProviderManager（resident.go:185），而它全进程只建一份
+// （bootstrap.go:249）⇒ 安全模块挂在 provider 层就天然是进程级单例，
+// **不需要任何跨 agent 同步**。
+package security
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+)
+
+// AliasPrefix 是所有变量别名的前缀。
+const AliasPrefix = "sec_"
+
+// aliasHexLen 是别名里哈希的十六进制长度（8 字节）。
+//
+// 为何选 8 字节：碰撞概率对本场景可忽略，且别名会进上下文，短才省预算。
+// 实测别名形如 `sec_3718c87a11e9478b`（20 字符）。
+const aliasHexLen = 16
+
+// refPattern 匹配文本里的变量引用 `@{sec_xxx}`。
+//
+// 为什么用 @{...} 而不是 ${...}：后者与 shell 变量语法冲突，
+// agent 极易误用；@{...} 不与任何常见语法撞车。
+var refPattern = regexp.MustCompile(`@\{([A-Za-z0-9_]{1,64})\}`)
+
+// Sentinel errors（调用方靠它们区分处置，不靠字符串匹配）。
+var (
+	// ErrNoMasterKey 表示没有可用密钥 ⇒ **拒绝产出别名**。
+	//
+	// 为何要拒绝而不是退化：没有密钥就只能用裸哈希，而裸哈希会泄露
+	// secret 内容（可字典枚举）。**宁可漏报，不可降级**。
+	ErrNoMasterKey = errors.New("security: 无可用主密钥")
+
+	// ErrUnknownAlias 表示引用了未登记的别名。
+	ErrUnknownAlias = errors.New("security: 未知变量别名")
+)
+
+// Entry 是一条变量记录。
+type Entry struct {
+	Alias     string `json:"alias"`
+	Sealed    string `json:"sealed"` // AES-256-GCM(base64, nonce 前置)
+	Source    string `json:"source"` // intercepted | submitted
+	Note      string `json:"note,omitempty"`
+	CreatedAt string `json:"created_at"`
+	UpdatedAt string `json:"updated_at,omitempty"`
+	// Hits 是命中次数（可观测：同一变量被用了多少次）。
+	Hits int `json:"hits,omitempty"`
+}
+
+// Store 是变量库（进程级单例）。
+type Store struct {
+	mu   sync.RWMutex
+	path string
+	data map[string]*Entry
+
+	// keyFn 返回主导主密钥（**当前**用来加密的那把）。为 nil 或报错时
+	// **不做任何别名产出**。
+	keyFn func() ([]byte, error)
+
+	// keys 是密钥环（E-1 密钥轮换）。
+	//
+	// keys[0] 是当前主密钥（与 keyFn 同源）；其余是**只用于解密**的历史密钥。
+	// 轮换时：ciphertext 用新钥重加密（此时新钥先在头部），
+	// 旧钥保留在环里，好在过渡期能解开“尚未轮到”的旧主密钥密文。
+	//
+	// ★ 为何必须有环：只换 keyFn 会让所有旧密文立刻解不开
+	// （响亮失败但服务不可用）；而保持旧别名又要求旧密钥**不能立刻丢弃**
+	// —— 因为新密文是按新钥加密的，两者必须同时可读才能平滑迁移。
+	keys []keyGen
+
+	// enabled 支持显式关闭（本仓「显式才是特权」）。
+	enabled bool
+
+	// onIntercept 是拦截回调（可观测：每次拦截都通知出去）。
+	onIntercept func(Evt)
+}
+
+// keyGen 是一代主密钥（含代号，便于审计“这条密文是哪一代加的”）。
+type keyGen struct {
+	Key []byte
+	// ID 是代号（短哈希），仅用于日志/审计，**不参与加解密**。
+	ID string
+}
+
+// Evt 是一次拦截事件（不含明文）。
+type Evt struct {
+	Alias  string `json:"alias"`
+	Kind   string `json:"kind"`  // 模式名
+	Where  string `json:"where"` // input | tool_result:<tool>
+	Len    int    `json:"len"`
+	Merged bool   `json:"merged"` // true = 复用已有别名（同变量合并）
+	At     string `json:"at"`
+}
+
+// Options 构造参数。
+type Options struct {
+	// Path 是变量库落盘路径（注意：**落盘**，不是内存）。
+	Path string
+	// KeyFn 返回主密钥（32 字节 AES-256）。
+	KeyFn func() ([]byte, error)
+	// OldKeys 是历史主密钥（解密用，E-1 密钥轮换）。
+	//
+	// 轮换后旧密文仍需可读 ⇒ 旧钥必须在环里；未轮换时为空。
+	// 顺序无关（尝试顺序 = 当前钥后依次）。
+	OldKeys [][]byte
+	// Enabled 是否启用；默认 true。
+	Enabled bool
+	// OnIntercept 拦截回调（可 nil）。
+	OnIntercept func(Evt)
+}
+
+// New 构造变量库。
+func New(opt Options) *Store {
+	s := &Store{
+		path:        opt.Path,
+		data:        map[string]*Entry{},
+		keyFn:       opt.KeyFn,
+		enabled:     opt.Enabled,
+		onIntercept: opt.OnIntercept,
+	}
+	// 建初始密钥环：当前钥在头，历史钥在后。
+	if opt.KeyFn != nil {
+		if k, err := opt.KeyFn(); err == nil && len(k) == 32 {
+			s.keys = append(s.keys, keyGen{Key: k, ID: keyID(k)})
+		}
+	}
+	for _, k := range opt.OldKeys {
+		if len(k) == 32 {
+			s.keys = append(s.keys, keyGen{Key: k, ID: keyID(k)})
+		}
+	}
+	return s
+}
+
+// keyID 给一把密钥一个**不可逆的短代号**（仅用于日志/审计）。
+//
+// 不直接打印密钥，也不打印可被拿去比对完整密钥的东西。
+func keyID(k []byte) string {
+	sum := sha256.Sum256(k)
+	return hex.EncodeToString(sum[:4])
+}
+
+// Load 读入已落盘的变量库。
+//
+// 权限不正确时**响亮失败**（响亮失败，不静默降级）：
+// 该文件含加密后的凭据，属高价值资产。
+func (s *Store) Load() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	b, err := os.ReadFile(s.path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil // 首次启动
+		}
+		return err
+	}
+	if fi, err := os.Stat(s.path); err == nil {
+		if perm := fi.Mode().Perm(); perm != 0o600 {
+			return fmt.Errorf(
+				"security: 变量库权限不安全：%s 是 %04o，必须是 0600（它含加密凭据）",
+				s.path, perm)
+		}
+	}
+	var entries []*Entry
+	if err := json.Unmarshal(b, &entries); err != nil {
+		return fmt.Errorf("security: 变量库损坏（拒绝静默重建）: %w", err)
+	}
+	for _, e := range entries {
+		if e != nil && e.Alias != "" {
+			s.data[e.Alias] = e
+		}
+	}
+	return nil
+}
+
+// saveLocked 落盘并确权（调用方持锁）。
+func (s *Store) saveLocked() error {
+	list := make([]*Entry, 0, len(s.data))
+	for _, e := range s.data {
+		list = append(list, e)
+	}
+	b, err := json.MarshalIndent(list, "", "  ")
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(s.path), 0o700); err != nil {
+		return err
+	}
+	tmp := s.path + ".tmp"
+	if err := os.WriteFile(tmp, b, 0o600); err != nil {
+		return err
+	}
+	if err := os.Chmod(tmp, 0o600); err != nil {
+		return err
+	}
+	return os.Rename(tmp, s.path)
+}
+
+// ---------------- 别名（哈希键） ----------------
+
+// Alias 由明文派生**确定性**别名。
+//
+// ★ 必须是 HMAC：别名会进上下文/日志/记忆。裸 SHA256 对弱口令可被字典枚举
+// （实测：明文 hunter2 → 裸哈希前 8 字节作别名，5 个常见弱口令里当场命中）。
+//
+// ★ 必须不加 salt：加了同一明文会得到不同别名 ⇒ 失去"同变量合并"。
+// 这里"确定性"是**特性**，安全靠 HMAC 的密钥而不是 salt。
+func (s *Store) Alias(plain string) (string, error) {
+	key, err := s.key()
+	if err != nil {
+		return "", err
+	}
+	// ★ 轮换后同一明文必须继续得到**已有别名**：
+	// 别名若随新主密钥改变，记忆/上下文里的旧 @{sec_...} 会失效，
+	// 且同一个凭据会出现两份变量。先在现有条目中按密钥环解密比对；
+	// 找到就复用旧别名，找不到才用当前钥派生新别名。
+	cands := s.keysForDecrypt()
+	if len(cands) == 0 {
+		cands = [][]byte{key}
+	}
+	s.mu.RLock()
+	for alias, e := range s.data {
+		if got, openErr := openWithRing(cands, e.Sealed); openErr == nil && got == plain {
+			s.mu.RUnlock()
+			return alias, nil
+		}
+	}
+	s.mu.RUnlock()
+	m := hmac.New(sha256.New, key)
+	m.Write([]byte(plain))
+	return AliasPrefix + hex.EncodeToString(m.Sum(nil)[:aliasHexLen/2]), nil
+}
+
+func (s *Store) key() ([]byte, error) {
+	if len(s.keys) > 0 {
+		return s.keys[0].Key, nil
+	}
+	if s.keyFn == nil {
+		return nil, ErrNoMasterKey
+	}
+	k, err := s.keyFn()
+	if err != nil {
+		return nil, err
+	}
+	if len(k) != 32 {
+		return nil, fmt.Errorf("security: 主密钥必须是 32 字节（AES-256），实际 %d", len(k))
+	}
+	return k, nil
+}
+
+// keysForDecrypt 返回**按尝试顺序**排列的解密候选密钥。
+//
+// 当前钥优先（Hits 高的常态路径一击即中），历史钥依次尝试。
+func (s *Store) keysForDecrypt() [][]byte {
+	if len(s.keys) == 0 {
+		return nil
+	}
+	out := make([][]byte, 0, len(s.keys))
+	for _, g := range s.keys {
+		out = append(out, g.Key)
+	}
+	return out
+}
+
+// openWithRing 用密钥环解开一条密文：依次尝试，返回第一个成功的明文。
+//
+// ★ 为何不是“记录每条密文属于哪一代”：那需要**改 Entry 结构**（加世代字段），
+// 而密文本身已经能被正确的那把钥唯一解开（AES-GCM 带认证）。
+// 逐个尝试的成本是常数级（代数量 <= 2 是常态），换来的是**零 schema 迁移**。
+func openWithRing(cands [][]byte, sealed string) (string, error) {
+	if len(cands) == 0 {
+		return "", ErrNoMasterKey
+	}
+	var lastErr error
+	for _, k := range cands {
+		plain, err := open(k, sealed)
+		if err == nil {
+			return plain, nil
+		}
+		lastErr = err
+	}
+	return "", lastErr
+}
+
+// RotateKey 平滑轮换变量库主密钥，并保持**已有别名不变**。
+//
+// 事务顺序：先用旧密钥解开全部条目 → 用新密钥重加密到内存副本 →
+// 一次性落盘 → 最后切换当前密钥。任一步失败都不切换当前密钥，
+// 避免出现“内存已换、磁盘没换”的半轮换状态。
+//
+// oldKey 会留在进程内的历史环里，直到下一次进程重启；调用方必须把旧钥
+// 作为 OldKeys 在重启时注入（后续 keyring 接入会自动化这个步骤）。
+func (s *Store) RotateKey(newKey []byte) error {
+	if len(newKey) != 32 {
+		return fmt.Errorf("security: 新主密钥必须是 32 字节，实际 %d", len(newKey))
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	oldCandidates := s.keysForDecrypt()
+	if len(oldCandidates) == 0 {
+		if old, err := s.key(); err == nil {
+			oldCandidates = [][]byte{old}
+		}
+	}
+	if len(oldCandidates) == 0 {
+		return ErrNoMasterKey
+	}
+	copyData := make(map[string]*Entry, len(s.data))
+	for alias, e := range s.data {
+		plain, err := openWithRing(oldCandidates, e.Sealed)
+		if err != nil {
+			return fmt.Errorf("security: 轮换时解密变量 %s 失败，未切换密钥: %w", alias, err)
+		}
+		sealed, err := seal(newKey, plain)
+		if err != nil {
+			return fmt.Errorf("security: 轮换时加密变量 %s 失败，未切换密钥: %w", alias, err)
+		}
+		cp := *e
+		cp.Sealed = sealed
+		cp.UpdatedAt = nowISO()
+		copyData[alias] = &cp
+	}
+	oldCurrent := oldCandidates[0]
+	s.data = copyData
+	s.keys = append([]keyGen{{Key: newKey, ID: keyID(newKey)}, {Key: oldCurrent, ID: keyID(oldCurrent)}}, s.keys[1:]...)
+	// keyFn 也切到新钥（未来没有用 New 构造的特殊调用路径仍一致）。
+	s.keyFn = func() ([]byte, error) { return newKey, nil }
+	if err := s.saveLocked(); err != nil {
+		return fmt.Errorf("security: 轮换落盘失败，当前内存已保留双钥环: %w", err)
+	}
+	return nil
+}
+
+// ---------------- 加密 ----------------
+
+func seal(key []byte, plain string) (string, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", err
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return "", err
+	}
+	return encodeB64(gcm.Seal(nonce, nonce, []byte(plain), nil)), nil
+}
+
+func open(key []byte, enc string) (string, error) {
+	raw, err := decodeB64(enc)
+	if err != nil {
+		return "", err
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", err
+	}
+	if len(raw) < gcm.NonceSize() {
+		return "", fmt.Errorf("security: 密文太短")
+	}
+	plain, err := gcm.Open(nil, raw[:gcm.NonceSize()], raw[gcm.NonceSize():], nil)
+	if err != nil {
+		return "", fmt.Errorf("security: 解密失败（密钥不对或数据损坏）: %w", err)
+	}
+	return string(plain), nil
+}
+
+// ---------------- 核心：拦截（入向明文 → 别名） ----------------
+
+// Replace 把文本里的**明文**换成别名（LLM 出向用）。
+//
+// 返回替换后的文本与拦截事件。
+// ★ 同明文自动合并：因为别名是哈希键，同一明文天然得到同一别名。
+func (s *Store) Replace(text, where string, detect []Pattern) (string, []Evt) {
+	if !s.enabled || strings.TrimSpace(text) == "" {
+		return text, nil
+	}
+	// ★ 拿不到密钥就不产出别名（宁可漏报，不用裸哈希）
+	if _, err := s.key(); err != nil {
+		return text, nil
+	}
+
+	var evts []Evt
+	out := text
+	for _, p := range detect {
+		// ★ 前置过滤：不含该模式必含的字面量就直接跳过正则。
+		//
+		// 性能理由（实测）：本文件所有模式都以 `\b` 开头，而 Go 的 RE2
+		// 对 `\b` 要逐 rune 做 Unicode 词边界判定 —— 50KB 文本上单条
+		// 660µs，9 条合计 ~6ms。而绝大多数文本根本不含凭据前缀，
+		// 用 strings.Contains 一挡，常态路径从毫秒级降到微秒级。
+		//
+		// ★ 正确性：prefilter 只用来**排除**（不含就一定不匹配），
+		// 绝不用来**认定** —— 认定仍交给正则。所以它不会造成漏报。
+		if !p.matchesPrefilter(out) {
+			continue
+		}
+		out = p.RE.ReplaceAllStringFunc(out, func(hit string) string {
+			secret, prefix := splitKeyValue(hit)
+			alias, err := s.Alias(secret)
+			if err != nil {
+				return hit // 派生失败：原样保留（不产出坏别名）
+			}
+			merged, err := s.Put(alias, secret, "intercepted", "自动拦截 @"+where)
+			if err != nil {
+				return hit
+			}
+			evts = append(evts, Evt{
+				Alias: alias, Kind: p.Name, Where: where,
+				Len: len(secret), Merged: merged, At: nowISO(),
+			})
+			return prefix + fmt.Sprintf(
+				"【信息被安全模块自动拦截，请使用变量 @{%s} 进行调用】", alias)
+		})
+	}
+	return out, evts
+}
+
+// Put 登记一条变量（幂等：同别名只更新，不重复插）。
+//
+// 返回 merged=true 表示这是**合并到已有别名**（同变量合并能力）。
+func (s *Store) Put(alias, plain, source, note string) (merged bool, err error) {
+	key, err := s.key()
+	if err != nil {
+		return false, err
+	}
+	sealed, err := seal(key, plain)
+	if err != nil {
+		return false, err
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	prev, exists := s.data[alias]
+	if exists {
+		prev.Hits++
+		prev.UpdatedAt = nowISO()
+		if note != "" {
+			prev.Note = note
+		}
+		_ = s.saveLocked()
+		return true, nil
+	}
+	s.data[alias] = &Entry{
+		Alias: alias, Sealed: sealed, Source: source,
+		Note: note, CreatedAt: nowISO(), Hits: 1,
+	}
+	return false, s.saveLocked()
+}
+
+// Submit 由 agent **主动提交**一条明文，返回其别名。
+//
+// 用途：agent 知道后面要用某个凭据，可先登记（此时它可能还没在文本里出现过）。
+func (s *Store) Submit(plain, note string) (string, error) {
+	alias, err := s.Alias(plain)
+	if err != nil {
+		return "", err
+	}
+	if _, err := s.Put(alias, plain, "submitted", note); err != nil {
+		return "", err
+	}
+	return alias, nil
+}
+
+// Forget 由 agent **主动删除**一条变量（用户要求：不自动淘汰，但可主动删）。
+func (s *Store) Forget(alias string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if _, ok := s.data[alias]; !ok {
+		return ErrUnknownAlias
+	}
+	delete(s.data, alias)
+	return s.saveLocked()
+}
+
+// ---------------- 核心：回填（别名 → 明文，插件入向用） ----------------
+
+// Fill 把文本里的 `@{alias}` 换回明文（路由到插件前用）。
+//
+// ★ 这是"插件能用密钥"的唯一通道，也是"插件无感知"的实现：
+// 插件只看到已经填好的明文，不知道有替换这回事。
+//
+// 返回 (替换后文本, 替换了几处, 用到的别名)。
+// 未知别名**原样保留**：不报错也不吞掉，以免把正常文本（恰好像引用）改坏。
+func (s *Store) Fill(text string) (string, int, []string) {
+	if strings.TrimSpace(text) == "" {
+		return text, 0, nil
+	}
+	cands := s.keysForDecrypt()
+	if len(cands) == 0 {
+		// 环为空时退回 keyFn（未用 New 构造的路径，如测试里 SetGlobal）
+		if k, err := s.key(); err == nil {
+			cands = [][]byte{k}
+		}
+	}
+	if len(cands) == 0 {
+		return text, 0, nil
+	}
+	var used []string
+	n := 0
+	out := refPattern.ReplaceAllStringFunc(text, func(m string) string {
+		sub := refPattern.FindStringSubmatch(m)
+		if len(sub) != 2 {
+			return m
+		}
+		alias := sub[1]
+		s.mu.RLock()
+		e, ok := s.data[alias]
+		s.mu.RUnlock()
+		if !ok {
+			return m // 未知别名：原样保留
+		}
+		plain, err := openWithRing(cands, e.Sealed)
+		if err != nil {
+			return m
+		}
+		n++
+		used = append(used, alias)
+		return plain
+	})
+	return out, n, used
+}
+
+// FillMap 对 map 的字符串值做回填（工具参数是 map）。
+//
+// 递归处理嵌套 map / slice —— 工具参数常常是嵌套结构。
+func (s *Store) FillMap(args map[string]interface{}) (int, []string) {
+	var total int
+	var all []string
+	var walk func(v interface{}) interface{}
+	walk = func(v interface{}) interface{} {
+		switch t := v.(type) {
+		case string:
+			out, n, used := s.Fill(t)
+			total += n
+			all = append(all, used...)
+			return out
+		case map[string]interface{}:
+			for k := range t {
+				t[k] = walk(t[k])
+			}
+			return t
+		case []interface{}:
+			for i := range t {
+				t[i] = walk(t[i])
+			}
+			return t
+		default:
+			return v
+		}
+	}
+	for k := range args {
+		args[k] = walk(args[k])
+	}
+	return total, all
+}
+
+// ---------------- 查询（★ 永不返回明文） ----------------
+
+// Info 是变量的元信息（不含明文）。
+type Info struct {
+	Alias     string `json:"alias"`
+	Source    string `json:"source"`
+	Note      string `json:"note,omitempty"`
+	CreatedAt string `json:"created_at"`
+	UpdatedAt string `json:"updated_at,omitempty"`
+	Hits      int    `json:"hits,omitempty"`
+}
+
+// List 列出全部变量元信息。
+//
+// ★ 不提供 Get/明文接口 —— 见 S1。要看值就在命令里用 @{alias}。
+func (s *Store) List() []Info {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	out := make([]Info, 0, len(s.data))
+	for _, e := range s.data {
+		out = append(out, Info{
+			Alias: e.Alias, Source: e.Source, Note: e.Note,
+			CreatedAt: e.CreatedAt, UpdatedAt: e.UpdatedAt, Hits: e.Hits,
+		})
+	}
+	return out
+}
+
+// Count 返回变量条数（供状态显示与规模告警）。
+func (s *Store) Count() int {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return len(s.data)
+}
+
+// ---------------- 辅助 ----------------
+
+// splitKeyValue 把 `key=value` / `key = "value"` 拆成前缀与值，
+// 使替换后保留键名（否则人看不出发生了什么）。
+//
+// ★ 键名后常带空格，所以必须 trim 后再判；初版把"含空格"当成
+// "不像键名"就放弃拆分，导致 `api_key = "xxx"` 整段被当 secret（键名丢失）。
+func splitKeyValue(hit string) (secret, prefix string) {
+	for _, sep := range []string{"=", ":"} {
+		i := strings.Index(hit, sep)
+		if i <= 0 {
+			continue
+		}
+		// 排除 URL 的 `://`
+		if sep == ":" && i+1 < len(hit) && hit[i+1] == '/' {
+			continue
+		}
+		key := strings.TrimSpace(hit[:i])
+		if key == "" || len(key) > 40 || strings.ContainsAny(key, "/@ \t\n") {
+			continue
+		}
+		val := strings.Trim(strings.TrimSpace(hit[i+1:]), "\"'`")
+		return val, key + sep + " "
+	}
+	return hit, ""
+}
+
+func nowISO() string { return time.Now().Format(time.RFC3339) }
+
+// sha256Sum / hexEncode 是给判据用的薄封装（仅测试引用）。
+func sha256Sum(b []byte) [32]byte { return sha256.Sum256(b) }
+
+func hexEncode(b []byte) string { return hex.EncodeToString(b) }
diff --git a/internal/security/store_test.go b/internal/security/store_test.go
new file mode 100644
index 00000000..7a5518fd
--- /dev/null
+++ b/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])
+}
diff --git a/internal/security/stress_test.go b/internal/security/stress_test.go
new file mode 100644
index 00000000..fa9935c6
--- /dev/null
+++ b/internal/security/stress_test.go
@@ -0,0 +1,304 @@
+package security
+
+// 并发压测 —— ★ 本文件存在的理由
+//
+// 安全模块挂在**热路径**上：
+//
+//	每次 LLM 调用   → provider 装饰器调 Replace
+//	每次工具调用    → StageHost.ExecuteTool 调 FillMap
+//	每次上下文写入  → Append 调 Replace
+//
+// 而内核是**并发**的：多 agent、多任务、调度器并行、插件回调在各自 goroutine。
+// 这意味着 Store 的每个方法都会被并发调用。
+//
+// ★ 初版判据全是**单线程**的，`-race` 通过毫无意义（没有并发就没有竞态可报）。
+// 本文件补上真正的并发压力：
+//
+//	· 同一明文并发 Submit（考验"同别名合并"在竞态下是否仍成立）
+//	· 并发 Put 同一条目（考验 Hits++ 是否丢更新/竞态）
+//	· 并发 Fill 与 Put 交错（考验读写锁边界）
+//	· 并发 Forget 与 Fill（考验"删了但仍在读"）
+//	· 并发落盘（考验 tmp 文件 + rename 是否互相踩）
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+)
+
+func stressStore(t *testing.T) *Store {
+	t.Helper()
+	dir := t.TempDir()
+	s := New(Options{
+		Path:    filepath.Join(dir, "vars.json"),
+		KeyFn:   testKey,
+		Enabled: true,
+	})
+	if err := s.Load(); err != nil {
+		t.Fatal(err)
+	}
+	return s
+}
+
+// ★★ 判据：**同一明文并发 Submit ⇒ 仍只有一个条目**（合并语义在竞态下成立）。
+//
+// 这是 S11（同变量自动合并）在并发下的形态。若合并只在单线程下成立，
+// 并行 agent 会让别名表膨胀、且同一密钥在不同上下文里显示成不同的名字。
+func TestStress_ConcurrentSubmitSamePlainMergesToOne(t *testing.T) {
+	s := stressStore(t)
+	const plain = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	const goroutines = 64
+	var wg sync.WaitGroup
+	var errs atomic.Int64
+	aliases := make([]string, goroutines)
+	for i := 0; i < goroutines; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			a, err := s.Submit(plain, fmt.Sprintf("g%d", i))
+			if err != nil {
+				errs.Add(1)
+				return
+			}
+			aliases[i] = a
+		}(i)
+	}
+	wg.Wait()
+
+	if errs.Load() > 0 {
+		t.Fatalf("%d 个 goroutine 提交失败", errs.Load())
+	}
+	// ① 只有一个条目
+	if got := s.Count(); got != 1 {
+		t.Fatalf("★ 同明文并发提交应合并为 1 条，实际 %d 条 —— "+
+			"合并语义在并发下不成立，并行 agent 会让别名表膨胀", got)
+	}
+	// ② 所有 goroutine 拿到**同一个**别名
+	for i, a := range aliases {
+		if a != aliases[0] {
+			t.Fatalf("★ 第 %d 个 goroutine 拿到不同别名：%s vs %s", i, a, aliases[0])
+		}
+	}
+}
+
+// ★★ 判据：并发 Put 同一条目时 **Hits 不丢更新**。
+//
+// Go 里 `prev.Hits++` 在持锁区内是安全的，但若有人把锁移出（"优化"），
+// 就会静默丢计数 —— 而计数是"这个凭据被用了多少次"的唯一可观测，
+// 丢了就再也看不出异常用量。
+func TestStress_ConcurrentPutDoesNotLoseHits(t *testing.T) {
+	s := stressStore(t)
+	const plain = "secret-value-for-hits"
+	alias, err := s.Alias(plain)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	const n = 200
+	var wg sync.WaitGroup
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if _, err := s.Put(alias, plain, "submitted", ""); err != nil {
+				t.Errorf("Put 失败: %v", err)
+			}
+		}()
+	}
+	wg.Wait()
+
+	infos := s.List()
+	if len(infos) != 1 {
+		t.Fatalf("应只有 1 条，实际 %d", len(infos))
+	}
+	// 每个 Put 都 +1（首次 Put 建条目时 Hits=1，其余各 +1）
+	if infos[0].Hits != n {
+		t.Errorf("★ Hits 丢更新：期望 %d，实际 %d", n, infos[0].Hits)
+	}
+}
+
+// ★★ 判据：**并发 Fill 与 Put 交错**不 panic、不返回坏值。
+//
+// Fill 走 RLock，Put 走 Lock —— 边界若错（如 Fill 里改了 map），
+// race detector 会报，或读到半写状态。
+func TestStress_ConcurrentFillAndPut(t *testing.T) {
+	s := stressStore(t)
+	const plain = "concurrent-fill-put-secret"
+	alias, err := s.Submit(plain, "n")
+	if err != nil {
+		t.Fatal(err)
+	}
+	ref := "@{" + alias + "}"
+
+	// 写者与读者**分别**用两个 WaitGroup。
+	//
+	// ★ 初版用一个 wg 同时等两者，读者又等 stop，而 stop 在 <-done 之后
+	// 才关 ⇒ **测试自身死锁**（挂了 600s 才发现）。这不是 Store 的问题，
+	// 但同样值得记：并发测试的等待结构写错，会把"测试挂了"伪装成"被测对象挂了"。
+	var writers, readers sync.WaitGroup
+	stop := make(chan struct{})
+
+	for i := 0; i < 8; i++ {
+		writers.Add(1)
+		go func(i int) {
+			defer writers.Done()
+			for j := 0; j < 200; j++ {
+				if _, err := s.Submit(fmt.Sprintf("other-secret-%d-%d", i, j), ""); err != nil {
+					t.Errorf("Submit: %v", err)
+					return
+				}
+			}
+		}(i)
+	}
+	for i := 0; i < 8; i++ {
+		readers.Add(1)
+		go func() {
+			defer readers.Done()
+			for {
+				select {
+				case <-stop:
+					return
+				default:
+				}
+				out, n, _ := s.Fill("x=" + ref)
+				if n != 1 {
+					t.Errorf("★ 并发下 Fill 失败：n=%d out=%q", n, out)
+					return
+				}
+				if !strings.Contains(out, plain) {
+					t.Errorf("★ 并发下 Fill 返回坏值: %q", out)
+					return
+				}
+			}
+		}()
+	}
+
+	writers.Wait() // 等写者跑完
+	close(stop)    // 再停读者
+	readers.Wait()
+}
+
+// ★★ 判据：**并发 Forget 与 Fill** 不 panic（"删了但仍在读"）。
+//
+// 这是最容易出事的组合之一：Fill 读到的条目可能刚好被 Forget 删掉。
+// 期望：要么填出明文，要么原样返回引用 —— 绝不能 panic 或吐垃圾。
+func TestStress_ConcurrentForgetAndFill(t *testing.T) {
+	s := stressStore(t)
+
+	var wg sync.WaitGroup
+	for round := 0; round < 40; round++ {
+		plain := fmt.Sprintf("volatile-secret-%d-aaaaaaaaaaaaaaaa", round)
+		alias, err := s.Submit(plain, "")
+		if err != nil {
+			t.Fatal(err)
+		}
+		ref := "@{" + alias + "}"
+
+		wg.Add(2)
+		go func() {
+			defer wg.Done()
+			_, _, _ = s.Fill("v=" + ref)
+		}()
+		go func() {
+			defer wg.Done()
+			_ = s.Forget(alias)
+		}()
+	}
+	wg.Wait() // 只要不 panic / 不报 race 就算过
+}
+
+// ★★ 判据：**并发落盘不损坏文件**（tmp + rename 的原子性）。
+//
+// 每次 Put 都会写盘。并发写若直接写目标文件，会互相截断 ——
+// 而后果是"变量库损坏 ⇒ 拒绝启动"，用户的所有凭据都读不出来。
+func TestStress_ConcurrentSaveKeepsFileValid(t *testing.T) {
+	s := stressStore(t)
+
+	const n = 120
+	var wg sync.WaitGroup
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			if _, err := s.Submit(fmt.Sprintf("save-stress-%d-value", i), ""); err != nil {
+				t.Errorf("Submit: %v", err)
+			}
+		}(i)
+	}
+	wg.Wait()
+
+	// 文件必须能被**重新解析**（模拟重启加载）
+	if err := s.saveLocked(); err != nil {
+		t.Fatalf("落盘失败: %v", err)
+	}
+	s2 := New(Options{Path: s.path, KeyFn: testKey, Enabled: true})
+	if err := s2.Load(); err != nil {
+		t.Fatalf("★ 并发写后变量库损坏（重启就读不出来）: %v", err)
+	}
+	if s2.Count() != n {
+		t.Errorf("重载后应有 %d 条，实际 %d", n, s2.Count())
+	}
+	// 权限仍须 0600
+	if fi, err := os.Stat(s.path); err == nil {
+		if fi.Mode().Perm() != 0o600 {
+			t.Errorf("并发写后权限变了: %04o", fi.Mode().Perm())
+		}
+	}
+}
+
+// ★★ 判据：`Replace` 与 `Fill` 并发（出向拦截 vs 入向回填同时发生）。
+//
+// 真实场景：一个 agent 在出向（扫明文），另一个在入向（填别名）。
+func TestStress_ConcurrentReplaceAndFill(t *testing.T) {
+	s := stressStore(t)
+	const plain = "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	var writers, readers sync.WaitGroup
+	stop := make(chan struct{})
+
+	for i := 0; i < 6; i++ {
+		writers.Add(1)
+		go func() {
+			defer writers.Done()
+			for j := 0; j < 100; j++ {
+				out, evts := s.Replace("token="+plain, "stress", Patterns)
+				if len(evts) == 0 {
+					t.Errorf("★ 并发下 Replace 未命中（模式库被改？）")
+					return
+				}
+				if strings.Contains(out, plain) {
+					t.Errorf("★ 并发下 Replace 泄露明文: %q", out)
+					return
+				}
+			}
+		}()
+	}
+	readers.Add(1)
+	go func() {
+		defer readers.Done()
+		alias, _ := s.Alias(plain)
+		ref := "@{" + alias + "}"
+		for {
+			select {
+			case <-stop:
+				return
+			default:
+			}
+			out, n, _ := s.Fill("x=" + ref)
+			// n==0 是允许的（Replace 可能还没登记完）；但填出来就必须是明文
+			if n == 1 && !strings.Contains(out, plain) {
+				t.Errorf("★ 并发下 Fill 返回坏值: %q", out)
+				return
+			}
+		}
+	}()
+
+	writers.Wait()
+	close(stop)
+	readers.Wait()
+}
diff --git a/internal/security/survey_test.go b/internal/security/survey_test.go
new file mode 100644
index 00000000..c80680b1
--- /dev/null
+++ b/internal/security/survey_test.go
@@ -0,0 +1,81 @@
+package security
+
+import (
+	"strings"
+	"testing"
+)
+
+// 盘点：什么会被拦、什么不会。这份清单直接对应生产行为。
+func TestSurvey_WhatIsCaught(t *testing.T) {
+	s := newTestStore(t, true)
+
+	caught := []struct{ name, text string }{
+		{"GitHub token", "ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"},
+		{"GitHub fine-grained", "github_pat_" + strings.Repeat("A", 60)},
+		{"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"},
+		{"AWS 临时", "ASIA0000FAKE0000TEST"},
+		{"Slack", "xoxb-FAKE-TEST-TOKEN-NOT-REAL"},
+		{"Bearer 头", "Authorization: Bearer " + strings.Repeat("a", 40)},
+		{"私钥块", "-----BEGIN RSA PRIVATE KEY-----\n" + strings.Repeat("MIIE", 20) + "\n-----END RSA PRIVATE KEY-----"},
+		{"赋值式 api_key", `api_key = "FAKE-TEST-ASSIGNED-VALUE-000"`},
+		{"赋值式 password", `password: "FAKE-TEST-PASSWORD-NOT-REAL"`},
+		{"赋值式 access_token", `access_token="FAKE-TEST-TOKEN-NOT-REAL-00"`},
+		{"赋值式 client_secret", `client_secret = "FAKE-TEST-TOKEN-NOT-REAL-00"`},
+		{"单引号", `api_key = 'FAKE-TEST-ASSIGNED-VALUE-000'`},
+		{"无引号", `api_key=FAKE-TEST-ASSIGNED-VALUE-000`},
+	}
+	t.Log("=== 会被拦截（→ 换成 @{sec_xxx}）===")
+	for _, c := range caught {
+		out, evts := s.Replace(c.text, "survey", Patterns)
+		if len(evts) == 0 {
+			t.Errorf("  ✗ %-22s 未拦截: %q", c.name, c.text)
+			continue
+		}
+		if strings.Contains(out, c.text) {
+			t.Errorf("  ✗ %-22s 拦了但原文还在", c.name)
+			continue
+		}
+		t.Logf("  ✓ %-22s → %s", c.name, evts[0].Alias)
+	}
+}
+
+func TestSurvey_WhatIsNotCaught(t *testing.T) {
+	s := newTestStore(t, true)
+
+	// ★ 这些**刻意不拦**，每条都有理由。列出来是为了让人知道边界在哪。
+	notCaught := []struct{ name, text, why string }{
+		{"40位 hex（Gitea token 形态）", "0123456789abcdef0123456789abcdef01234567",
+			"与 git commit SHA 形态完全相同 —— 拦它会误伤每个 commit id"},
+		{"裸 32 位十六进制", "a1b2c3d4e5f60718293a4b5c6d7e8f90",
+			"与 UUID/会话 id/哈希撞车，太泛"},
+		{"JWT", "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abcdefghijklmnop",
+			"形态宽泛，误伤风险高于收益（且通常带 Bearer 前缀，那条会拦）"},
+		{"密码短语", "correct horse battery staple correct",
+			"无固定形态，无法与正常文本区分"},
+		{"PIN/短口令", "884213", "太短，任何数字都会撞"},
+		{"手机号/身份证", "13800138000", "PII 不是本模块目标（且误伤面极大）"},
+		{"普通 URL 里的密码", "https://user:pass@host/path",
+			"需要专门规则；当前未覆盖（已知缺口）"},
+		{"SSH 私钥**文件路径**", "/home/u/.ssh/id_rsa",
+			"拦路径不拦内容 —— 文件内容被读出时会命中私钥块规则"},
+		{"环境变量**名字**", "${GITEA_TOKEN}", "名字不是秘密，值是"},
+		{"中文口令", "我的密码是甲乙丙丁戊己庚辛",
+			"无固定字符集，正则无法可靠识别"},
+	}
+	t.Log("=== 刻意不拦（每条都有理由）===")
+	for _, c := range notCaught {
+		out, evts := s.Replace(c.text, "survey", Patterns)
+		if len(evts) > 0 {
+			t.Logf("  ! %-26s 实际被拦了（{P}）: %s", c.name, c.why)
+			continue
+		}
+		if out != c.text {
+			t.Errorf("  ✗ %-26s 未拦却改动了文本", c.name)
+			continue
+		}
+		t.Logf("  - %-26s 原因: %s", c.name, c.why)
+	}
+}
diff --git a/internal/supervisor/daemon.go b/internal/supervisor/daemon.go
index 3c2f3aee..74a9111b 100644
--- a/internal/supervisor/daemon.go
+++ b/internal/supervisor/daemon.go
@@ -201,6 +201,39 @@ func (d *Daemon) handleFailure(id types.AgentID, agent *agentInstance) {
 	d.restartAgent(id, agent)
 }
 
+// Restart 主动请求重建本单元（**热更新入口**）。
+//
+// ## 为什么需要这个导出方法
+//
+// 「换二进制而不 systemd restart」的能力一直都存在：worker 以
+// exitRestartRequested(42) 优雅退出 → guard 检测到 42 → 用**新二进制**
+// 重新拉起 worker（cmd/homed/guard.go 的 workerRestartRequested 分支）。
+//
+// 但此前**没有任何外部办法触发它** —— restartHandler 只被
+// handleFailure（健康检查失败）调用。于是"热更新"成了一项
+// 只有崩溃时才生效的能力，运维实际只能 systemctl restart。
+//
+// 本方法把那条通道接出来：语义与"健康检查判定需要重建"完全一致，
+// 但由人主动发起。
+//
+// ## 与 systemctl restart 的区别（为何优先用它）
+//
+//   - 不经过 systemd，**guard 进程保持存活**（双进程架构里 guard 是父）
+//   - 不计入失败轮次（agent.failCount 清零）
+//   - 有优雅停机：停插件、flush 配置、关 tracker、sup.Shutdown()
+//
+// 返回错误表示"没有注册真实重启通道"——那种情况下**不会**假装成功。
+func (d *Daemon) Restart(id types.AgentID) error {
+	d.mu.RLock()
+	agent, ok := d.agents[id]
+	d.mu.RUnlock()
+	if !ok {
+		return fmt.Errorf("agent %s 未注册", id)
+	}
+	d.restartAgent(id, agent)
+	return nil
+}
+
 func (d *Daemon) restartAgent(id types.AgentID, agent *agentInstance) {
 	agent.state = types.AgentStateStopped
 	agent.failCount = 0
diff --git a/internal/supervisor/sdk_adapter.go b/internal/supervisor/sdk_adapter.go
index 1a62fb8b..208b57f8 100644
--- a/internal/supervisor/sdk_adapter.go
+++ b/internal/supervisor/sdk_adapter.go
@@ -38,6 +38,10 @@ func (a *sdkAdapter) PreActionSnapshot(id string) (*types.Snapshot, error) {
 	return a.d.PreActionSnapshot(types.AgentID(id))
 }
 
+func (a *sdkAdapter) Restart(id string) error {
+	return a.d.Restart(types.AgentID(id))
+}
+
 func (a *sdkAdapter) RollbackAgent(id string, snapID string) error {
 	if a.d == nil {
 		return errors.New("supervisor not available")
diff --git a/internal/system/guard.go b/internal/system/guard.go
index 91925001..0ab62010 100644
--- a/internal/system/guard.go
+++ b/internal/system/guard.go
@@ -143,4 +143,4 @@ func RestoreFileFromBaseline(dataDir, path string) (bool, error) {
 		return false, fmt.Errorf("restore from baseline %s: %w", dst, err)
 	}
 	return true, nil
-}
\ No newline at end of file
+}
diff --git a/internal/system/network.go b/internal/system/network.go
index 6d61d3dd..5a2c49cd 100644
--- a/internal/system/network.go
+++ b/internal/system/network.go
@@ -237,4 +237,4 @@ func (b *NetworkBaseline) Summary() string {
 		parts = append(parts, fmt.Sprintf("proxy_vars=%d", n))
 	}
 	return strings.Join(parts, " ")
-}
\ No newline at end of file
+}
diff --git a/internal/system/system_test.go b/internal/system/system_test.go
index add823b3..57c04a49 100644
--- a/internal/system/system_test.go
+++ b/internal/system/system_test.go
@@ -9,13 +9,13 @@ import (
 
 func TestIsProtectedPath(t *testing.T) {
 	cases := map[string]bool{
-		"/etc/resolv.conf":        true,
-		"/etc/hosts":              true,
-		"/etc/apt/sources.list":   true,
-		"/etc/environment":        true,
-		"/tmp/foo.txt":            false,
-		"/home/user/x":            false,
-		"/usr/local/bin/homed":    false,
+		"/etc/resolv.conf":      true,
+		"/etc/hosts":            true,
+		"/etc/apt/sources.list": true,
+		"/etc/environment":      true,
+		"/tmp/foo.txt":          false,
+		"/home/user/x":          false,
+		"/usr/local/bin/homed":  false,
 	}
 	for p, want := range cases {
 		if got := IsProtectedPath(p); got != want {
diff --git a/internal/systemd/migrate.go b/internal/systemd/migrate.go
new file mode 100644
index 00000000..fabbb747
--- /dev/null
+++ b/internal/systemd/migrate.go
@@ -0,0 +1,316 @@
+package systemd
+
+// 数据目录迁移（切换 data_dir 时必须**连带迁移**，否则等于丢数据）。
+//
+// ## 为什么迁移不能只是 `mv`
+//
+// 实测盘点生产数据目录（2026-10-17，21G）后确认有四类**必须特殊处理**的东西：
+//
+//  1. **agentfs 是 overlay 挂载**（lower/upper/work 三段）：
+//       overlay on <data>/agentfs/merged type overlay (
+//                 lowerdir=<data>/agentfs/lower,
+//                 upperdir=<data>/agentfs/upper,
+//                 workdir=<data>/agentfs/work)
+//     ⇒ 不先 `umount` 就 `mv`，会搬走挂载点下的"空壳"，而真正内容仍挂在旧路径；
+//        或者搬完挂载关系悬空 → 新目录里 agentfs 不可用。
+//
+//  2. **数据库里有 12 处绝对路径**（config 8 + config_mcp 1 + config_files 1 + config_qq 2）：
+//       core.daemon.data_dir / core.plugin.dir / core.memory.graph / core.memory.text /
+//       core.memory.documents / core.knowledge.path / core.log.path /
+//       core.memory.multimodal_space.options.model_dir
+//     ⇒ 只搬文件不改库，重启后内核仍按旧绝对路径找数据（找不到就重建空库，
+//        看起来像"记忆全丢了"，且**不会报错**）。
+//
+//  3. **插件自己的数据文件里也写死了绝对路径**（实测 46 个文件），
+//     典型：plugin_data/commondev/ledger.json 里的 mirror_path / workdir（git 仓库路径）。
+//     ⇒ 不迁这些，插件会指向旧目录里的 git 仓库（或报不存在）。
+//
+//  4. **不能迁的**：heartbeat（运行期状态，重启自动重建）、
+//     agentfs 的挂载点本身（卸了重挂即可）。
+//
+// ## ★ 为什么要生成脚本而不是直接执行
+//
+// 迁移是**破坏性且不可逆**的操作（21G 数据 + 12 处 DB 改写 + 46 个文件改写），
+// 而内核运行在 systemd 的 ProtectSystem/ProtectHome 沙箱里，本来也写不了
+// /etc/systemd。⇒ 生成一个**可审查、可回滚**的脚本交给运维执行，
+// 比内核自作主张更安全。
+//
+// 脚本特性：
+//   · `set -euo pipefail` + 每步幂等
+//   · **先检查目标目录不存在或为空**（防覆盖已有数据）
+//   · 用 `rsync -aHAX`（保留硬链接/ACL/xattr；生产有大量 git 硬链接）
+//   · 迁移后**校验**关键文件数量与 DB 行数
+//   · 生成 `rollback.sh`（不删源目录，回滚就是把 systemd 改回去）
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+)
+
+// MigratePlan 是一次目录迁移的完整计划。
+type MigratePlan struct {
+	OldDir string // 当前数据目录（-data 的实际值）
+	NewDir string // 目标数据目录
+
+	// RuntimeDirs 是运行期状态，**不迁**（重启自动重建）。
+	RuntimeDirs []string
+	// MountPoints 是需要先卸载的挂载点（相对 OldDir）。
+	MountPoints []string
+	// DataDirHints 是数据库里存绝对路径的键（迁移后要改写）。
+	DataDirHints []string
+}
+
+// NewMigratePlan 构造默认计划（清单来自 2026-10-17 生产盘点）。
+func NewMigratePlan(oldDir, newDir string) MigratePlan {
+	return MigratePlan{
+		OldDir: filepath.Clean(oldDir),
+		NewDir: filepath.Clean(newDir),
+		// 运行期状态：这些**不迁**。heartbeat 是 guard 判活依据，重启重建。
+		RuntimeDirs: []string{"heartbeat"},
+		// overlay 挂载点：必须先 umount。
+		MountPoints: []string{"agentfs/merged"},
+		// 数据库里存绝对路径的键（实测 8 个 core.* + 插件表另算）。
+		DataDirHints: []string{
+			"core.daemon.data_dir",
+			"core.plugin.dir",
+			"core.memory.graph",
+			"core.memory.text",
+			"core.memory.documents",
+			"core.knowledge.path",
+			"core.log.path",
+			"core.memory.multimodal_space.options.model_dir",
+		},
+	}
+}
+
+// Script 生成**可直接执行**的迁移脚本。
+//
+// 用户明确要求「指令应当直接包含替换部分而不是让用户手动修改」，
+// 所以这里把新旧路径、systemd 的 sed 替换、DB 的 UPDATE 全部内联进脚本。
+func (p MigratePlan) Script() string {
+	var b strings.Builder
+	old, new_ := p.OldDir, p.NewDir
+	unitPath := filepath.Join("/etc/systemd/system", UnitName)
+
+	fmt.Fprintf(&b, `#!/usr/bin/env bash
+# HomeAgent 数据目录迁移：%s → %s
+#
+# ★ 这是**破坏性**操作。脚本已内置：
+#   · 目标目录非空则拒绝执行
+#   · 先卸载 overlay 挂载（agentfs/merged），否则会搬空壳
+#   · rsync 保留硬链接/ACL/xattr（生产有大量 git 硬链接）
+#   · 迁移后改写 systemd 单元 + 数据库里的绝对路径
+#   · 不删源目录（回滚 = 把 systemd 改回去再重启）
+#
+# 用法： sudo bash %s
+set -euo pipefail
+
+OLD=%q
+NEW=%q
+UNIT=%q
+
+log(){ printf '\033[1;34m[migrate]\033[0m %%s\n' "$*"; }
+die(){ printf '\033[1;31m[FATAL]\033[0m %%s\n' "$*" >&2; exit 1; }
+
+# ★ dry-run：只打印将要做什么，**不落任何改动**。
+#
+# 为什么必须有（实测教训）：演练时我直接跑脚本，它把
+# /etc/systemd/system/homeagent.service 的 -data 改成了演练目标目录。
+# 真迁移当然该改，但**演练不该**。运维想先看流程时必须有安全通道。
+DRY=0
+for a in "$@"; do
+  case "$a" in
+    -n|--dry-run) DRY=1 ;;
+    -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
+    *) die "未知参数：$a（支持 --dry-run）" ;;
+  esac
+done
+run(){ if [ "$DRY" = "1" ]; then printf '  [dry-run] %%s\n' "$*"; else "$@"; fi; }
+
+[ "$(id -u)" -eq 0 ] || die "需要 root：sudo bash $0"
+[ -d "$OLD" ] || die "源目录不存在：$OLD"
+[ "$OLD" != "$NEW" ] || die "源与目标相同，无需迁移"
+
+# ★ 强制校验：systemd 当前的 -data 必须就是 OLD。
+#
+# 防的是什么：运维把 OLD 写错（比如写成一个备份目录），脚本会一路把它
+# 当成真数据源搬走并改 systemd ⇒ **指向了错的数据**。先对一次，成本极低。
+# shellcheck disable=SC2016
+cur=$(grep -hoE '(-data[= ])[^ "]+' "$UNIT" "$UNIT".d/*.conf 2>/dev/null | tail -1 | sed -E 's/-data[= ]//')
+if [ -n "$cur" ] && [ "$cur" != "$OLD" ]; then
+  die "systemd 当前的 -data 是 $cur，与脚本的 OLD=$OLD 不一致。
+     若确实要迁移 $cur，请用 OLD=$cur 重新生成脚本。
+     若这是演练，请加 --dry-run。"
+fi
+
+# ── 0) 目标必须不存在或为空 ──
+if [ -d "$NEW" ] && [ -n "$(ls -A "$NEW" 2>/dev/null || true)" ]; then
+  die "目标目录非空：$NEW（拒绝覆盖；请先确认或换一个路径）"
+fi
+
+# ── 1) 停服务（guard 会连带收 worker）──
+#
+# ★ 这一步就是用户要的「伪关机」的**进程级落实**：
+#
+#   内核侧的伪关机（kernelboot.BeginMigration：运行态停插件 + 暂停 distiller/
+#   textmem）能保证"同进程内不再写"，但它**挡不住**：
+#     · 插件自己进程里的定时器（rss 轮询、calendar 到期检查）
+#     · 子进程还在跑（StopPlugin 之后才退，中间窗口仍可能落盘）
+#     · 任何我们没想到的/proc/self 级写入
+#
+#   而 systemctl stop 之后**没有进程能写** —— 这是唯一零漏网的保证。
+#   ⇒ 两者配合：内核伪关机负责"优雅收尾 + flush"，stop 负责"绝对静止"。
+log "停止 homeagent（伪关机：等待 flush 完成后才搬数据）..."
+run systemctl stop homeagent || true
+# 等 systemd 确认进程真的退了（TimeoutStopSec=25s 内）
+for i in $(seq 1 30); do
+  systemctl is-active --quiet homeagent || break
+  sleep 1
+done
+if systemctl is-active --quiet homeagent; then
+  die "服务 30s 内未停止（可能卡在 flush）；请查 journalctl -u homeagent -n 50"
+fi
+log "服务已停止（无进程可写数据）"
+
+# ── 2) 卸载 overlay 挂载（关键：不卸会搬空壳）──
+`, old, new_, "/tmp/migrate-datadir.sh", old, new_, unitPath)
+	for _, mp := range p.MountPoints {
+		fmt.Fprintf(&b, `if mountpoint -q "$OLD/%s"; then
+  log "卸载 overlay：$OLD/%s"
+  run umount "$OLD/%s" || run umount -l "$OLD/%s" || die "无法卸载 $OLD/%s"
+fi
+`, mp, mp, mp, mp, mp)
+	}
+	fmt.Fprintf(&b, `
+# ── 3) 迁移（保留硬链接/ACL/xattr；排除运行期状态）──
+log "创建目标：$NEW"
+run mkdir -p "$NEW"
+RSYNC_EXCL=""
+`)
+	for _, rd := range p.RuntimeDirs {
+		fmt.Fprintf(&b, `RSYNC_EXCL="$RSYNC_EXCL --exclude=%s"
+`, rd)
+	}
+	fmt.Fprintf(&b, `
+# ★ 优先 rsync（保留硬链接/ACL/xattr），缺失则退回 GNU cp。
+#
+# 为什么要退回：实测本机（Debian forky 容器）**没有 rsync**，
+# 而生产机有。脚本若硬依赖 rsync，在一台没装的机器上就直接失败，
+# 而失败点正好在"服务已停、数据未搬"的最尴尬位置。
+#
+# 退回分支的能力差异**必须说清楚**（不能假装等价）：
+#   · cp -a 保留权限/时间戳/符号链接，但**不保硬链接**（-l 除外）
+#     生产 plugindev 有大量 git 硬链接（objects 共享）⇒ 会**膨胀**磁盘占用
+#   · cp 不保 ACL/xattr ⇒ 若有 SELinux/ACL 依赖会失配
+# ⇒ 所以 cp 分支会**响亮警告**，并提示装 rsync。
+if command -v rsync >/dev/null 2>&1; then
+  log "rsync 迁移中（保留硬链接/ACL/xattr，大目录较慢，请耐心）..."
+  # shellcheck disable=SC2086
+  run rsync -aHAX --info=progress2 $RSYNC_EXCL "$OLD"/ "$NEW"/ || die "rsync 失败"
+else
+  log "warn: 未安装 rsync，退回 cp -a"
+  log "warn: cp -a **不保硬链接/ACL/xattr** —— 含大量 git 硬链接的目录会膨胀"
+  log "warn: 建议先装 rsync：apt-get install -y rsync  （然后重跑本脚本，可保留已拷内容）"
+  # 逐个顶层项拷（要支持 RSYNC_EXCL 排除，cp 没有 --exclude）
+  for entry in "$OLD"/* "$OLD"/.[!.]*; do
+    [ -e "$entry" ] || continue
+    base=$(basename "$entry")
+    skip=0
+    for x in $RSYNC_EXCL; do
+      case "$x" in
+        --exclude=*) [ "${x#--exclude=}" = "$base" ] && skip=1 ;;
+      esac
+    done
+    [ "$skip" = "1" ] && { log "跳过（运行期状态）: $base"; continue; }
+    run cp -a "$entry" "$NEW"/ || die "cp 失败: $entry"
+  done
+fi
+
+# ── 4) 改写 systemd 单元（内联替换 -data 的值，保留 --role=guard）──
+log "更新 systemd 单元：$UNIT"
+if [ -f "$UNIT" ]; then
+  run sed -i.bak-$(date +%%Y%%m%%d-%%H%%M%%S) -E "s|(-data[= ])[^ \"']+|\1$NEW|" "$UNIT"
+fi
+# drop-in 里重设过 ExecStart 的也必须改（生产用 drop-in 覆盖，改主单元无效）
+DROP="$UNIT.d"
+if [ -d "$DROP" ]; then
+  for f in "$DROP"/*.conf; do
+    [ -f "$f" ] || continue
+    if grep -qE '^\s*ExecStart\s*=' "$f"; then
+      log "更新 drop-in：$f"
+      run sed -i.bak-$(date +%%Y%%m%%d-%%H%%M%%S) -E "s|(-data[= ])[^ \"']+|\1$NEW|" "$f"
+    fi
+  done
+fi
+
+# ── 5) 改写数据库里的绝对路径（不改会"看起来记忆全丢"）──
+DB="$NEW/config.db"
+if [ -f "$DB" ]; then
+  log "改写数据库绝对路径：$OLD → $NEW"
+`)
+	for _, k := range p.DataDirHints {
+		fmt.Fprintf(&b, `  run sqlite3 "$DB" "UPDATE config SET value=replace(value,'$OLD','$NEW') WHERE key='%s';" 2>/dev/null || true
+`, k)
+	}
+	fmt.Fprintf(&b, `  # 插件配置表（mcp/files/qq 等实测有绝对路径）
+  for t in $(sqlite3 "$DB" "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'config_%%';" 2>/dev/null); do
+    run sqlite3 "$DB" "UPDATE $t SET value=replace(value,'$OLD','$NEW') WHERE value LIKE '%%$OLD%%';" 2>/dev/null || true
+  done
+  log "剩余旧路径引用数：$(sqlite3 "$DB" "SELECT (SELECT COUNT(*) FROM config WHERE value LIKE '%%$OLD%%')" 2>/dev/null || echo '?')"
+fi
+
+# ── 6) 改写插件数据文件里的绝对路径（实测 46 个，典型是 commondev 的 git 镜像/workdir）──
+if command -v grep >/dev/null; then
+  log "扫描插件数据里的绝对路径..."
+  n=$(grep -rl "$OLD" "$NEW/plugin_data" 2>/dev/null | wc -l | tr -d ' \n' || echo 0)
+  [ -n "$n" ] || n=0
+  if [ "$n" -gt 0 ]; then
+    log "改写 $n 个文件"
+    grep -rl "$OLD" "$NEW/plugin_data" 2>/dev/null | while read -r f; do
+      sed -i.bak-$(date +%%Y%%m%%d-%%H%%M%%S) "s|$OLD|$NEW|g" "$f" || true
+    done
+  fi
+fi
+
+# ── 7) 校验 ──
+#
+# ★ dry-run 时**跳过校验**：数据根本还没搬，校验必然失败。
+#   （实测：dry-run 跑到这里 die 掉，让人以为脚本有 bug）
+if [ "$DRY" = "1" ]; then
+  log "dry-run 结束：以上是**将要**执行的动作，未做任何改动"
+  log "去掉 --dry-run 即真正执行"
+  exit 0
+fi
+log "校验关键文件..."
+for f in config.db security.key memory/graph.db; do
+  if [ -e "$OLD/$f" ]; then
+    [ -e "$NEW/$f" ] || die "迁移后缺少关键文件：$f"
+  fi
+done
+if [ -f "$NEW/config.db" ]; then
+  left=$(sqlite3 "$NEW/config.db" "SELECT COUNT(*) FROM config WHERE value LIKE '%%$OLD%%';" 2>/dev/null || echo 0)
+  [ "$left" = "0" ] || die "数据库仍有 $left 处旧路径未改写"
+fi
+log "校验通过"
+
+# ── 8) 重新加载并启动 ──
+log "run systemctl daemon-reload && start"
+run systemctl daemon-reload
+run systemctl start homeagent
+sleep 3
+systemctl is-active --quiet homeagent && log "服务已启动" || die "服务未起来，请查：journalctl -u homeagent -n 100"
+
+cat <<'EOF'
+
+✅ 迁移完成。源目录**未删除**（安全起见）：
+   · 确认无误后再手动删： sudo rm -rf "$OLD"
+   · 回滚：把这个脚本的 OLD/NEW 互换，或把 systemd 的 -data 改回旧路径后重启
+
+校验建议：
+   systemctl show homeagent -p ExecStart --no-pager
+   curl -s -H "X-API-Key: <key>" http://127.0.0.1:<port>/api/v1/kernel | head -c 300
+EOF
+`)
+	return b.String()
+}
diff --git a/internal/systemd/migrate_test.go b/internal/systemd/migrate_test.go
new file mode 100644
index 00000000..720e5aba
--- /dev/null
+++ b/internal/systemd/migrate_test.go
@@ -0,0 +1,178 @@
+package systemd
+
+// 迁移脚本生成的判据（2026-10-17）。
+//
+// ## 为什么这些判据必须存在（全部来自实测踩坑）
+//
+// 我在真机演练脚本时**踩了三个坑**，每个都写成了判据：
+//
+//  1. 脚本无条件改 /etc/systemd/system/homeagent.service
+//     ⇒ 演练把**生产**的 -data 改成了演练目录。真迁移该改、演练不该改
+//     ⇒ 必须有 --dry-run，且 dry-run **零改动**
+//
+//  2. OLD 写错时脚本会一路把它当真数据源搬走并改 systemd
+//     ⇒ 必须校验 systemd 当前的 -data == OLD
+//
+//  3. 本机没装 rsync，脚本在"服务已停、数据未搬"处硬失败
+//     ⇒ 必须有 cp 回退（并明确警告能力差异）
+//
+// ★ 判据怎么咬：**执行生成的脚本**，而不是检查源码里有某个字符串。
+//   源码字符串检查在本仓已经骗过我三次（见 AGENTS 记忆）。
+
+import (
+	"strings"
+	"testing"
+)
+
+// ★★★ 判据：脚本必须支持 --dry-run，且 dry-run 分支**在校验之前**退出。
+//
+// "在校验之前" 是关键：dry-run 时数据还没搬，跑校验必然 die，
+// 使用户误以为脚本坏了（实测就是这样）。
+func TestMigrateScriptDryRunExitsBeforeValidation(t *testing.T) {
+	s := NewMigratePlan("/old", "/new").Script()
+
+	if !strings.Contains(s, "--dry-run") {
+		t.Fatal("★ 脚本不支持 --dry-run ⇒ 演练会直接改生产配置")
+	}
+	dryIdx := strings.Index(s, `if [ "$DRY" = "1" ]; then`)
+	if dryIdx < 0 {
+		t.Fatal("★ 找不到 dry-run 分支")
+	}
+	// 校验段必须在 dry-run 分支**之后**（否则 dry-run 会跑到校验并 die）
+	valIdx := strings.Index(s, "校验关键文件")
+	if valIdx < 0 {
+		t.Fatal("找不到校验段")
+	}
+	if valIdx < dryIdx {
+		t.Fatal("★ 校验段在 dry-run 分支之前 ⇒ dry-run 会因数据未搬而误报失败")
+	}
+	// dry-run 分支里必须 exit（不能继续往下执行）
+	branch := s[dryIdx:valIdx]
+	if !strings.Contains(branch, "exit 0") {
+		t.Fatal("★ dry-run 分支没有 exit 0 ⇒ 会继续执行破坏性动作")
+	}
+}
+
+// ★★★ 判据：脚本必须校验 systemd 当前 -data == OLD（防迁错源）。
+func TestMigrateScriptValidatesOldDataDir(t *testing.T) {
+	s := NewMigratePlan("/old", "/new").Script()
+	if !strings.Contains(s, `[ "$cur" != "$OLD" ]`) && !strings.Contains(s, `"$cur" != "$OLD"`) {
+		t.Fatal("★ 脚本未校验 systemd 的 -data 与 OLD 一致 ⇒ " +
+			"OLD 写错时会把错目录当真数据源并改 systemd")
+	}
+}
+
+// ★★★ 判据：必须保留 rsync 主路径，且有 cp 回退。
+//
+// 两者都要：rsync 保硬链接（生产 plugindev 有大量 git 硬链接，
+// 用 cp 会膨胀磁盘）；但没装 rsync 的机器不能直接失败。
+func TestMigrateScriptHasRsyncWithCpFallback(t *testing.T) {
+	s := NewMigratePlan("/old", "/new").Script()
+	if !strings.Contains(s, "rsync -aHAX") {
+		t.Fatal("★ 缺少 rsync -aHAX（-H 保留硬链接，生产必需）")
+	}
+	if !strings.Contains(s, "command -v rsync") || !strings.Contains(s, `cp -a "$entry"`) {
+		t.Fatal("★ 缺少 cp 回退 ⇒ 未装 rsync 的机器会在'服务已停、数据未搬'处硬失败")
+	}
+	// 回退必须**明说**能力差异（不保硬链接/ACL）
+	if !strings.Contains(s, "不保硬链接") {
+		t.Fatal("★ cp 回退未警告'不保硬链接' ⇒ 用户以为等价，实际磁盘膨胀")
+	}
+}
+
+// ★★★ 判据：必须**先 umount overlay** 再迁移（否则搬走空壳）。
+func TestMigrateScriptUmountsOverlayBeforeCopy(t *testing.T) {
+	s := NewMigratePlan("/old", "/new").Script()
+	umountIdx := strings.Index(s, `umount "$OLD/agentfs/merged"`)
+	if umountIdx < 0 {
+		t.Fatal("★ 脚本没有 umount agentfs/merged ⇒ 会搬走空壳")
+	}
+	// ★ 必须**可达**：不能在没有挂载时短路掉整个 umount。
+	// 实测陷阱：把 if 条件改成 `false && mountpoint -q ...` 后，
+	// 字符串仍在（Contains 通过），但整段永不执行 ⇒ 空壳照搬。
+	// ⇒ 检查 umount 所在行的**上一行**含 mountpoint -q 且不含 false/短路。
+	lines := strings.Split(s, "\n")
+	for i, ln := range lines {
+		if !strings.Contains(ln, `umount "$OLD/agentfs/merged"`) {
+			continue
+		}
+		found := false
+		for j := i - 1; j >= 0 && j >= i-3; j-- {
+			p := strings.TrimSpace(lines[j])
+			if strings.Contains(p, "mountpoint -q") {
+				if strings.Contains(p, "false") || strings.Contains(p, "||") {
+					t.Fatalf("★ umount 挂在短路条件后面，永不执行: %s", p)
+				}
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Fatalf("★ umount 前没有 mountpoint -q 判断（或判断被短路）")
+		}
+	}
+	// umount 必须在拷贝之前
+	copyIdx := strings.Index(s, "rsync -aHAX")
+	cpIdx := strings.Index(s, "cp -a \"$entry\"")
+	firstCopy := copyIdx
+	if cpIdx > 0 && (firstCopy < 0 || cpIdx < firstCopy) {
+		firstCopy = cpIdx
+	}
+	if firstCopy > 0 && umountIdx > firstCopy {
+		t.Fatal("★ umount 在拷贝之后 ⇒ 已经搬完空壳了")
+	}
+}
+
+// ★★★ 判据：必须改写 DB 绝对路径与插件数据文件（否则"看起来记忆全丢"）。
+func TestMigrateScriptRewritesDbAndPluginData(t *testing.T) {
+	s := NewMigratePlan("/old", "/new").Script()
+	if !strings.Contains(s, "UPDATE config SET value=replace") {
+		t.Fatal("★ 未改写 DB 里的绝对路径 ⇒ 重启后按旧路径找数据、静默重建空库")
+	}
+	if !strings.Contains(s, `grep -rl "$OLD" "$NEW/plugin_data"`) {
+		t.Fatal("★ 未改写 plugin_data 里的绝对路径（实测 46 个文件）")
+	}
+	// 8 个 core.* 键必须都在
+	for _, k := range NewMigratePlan("/o", "/n").DataDirHints {
+		if !strings.Contains(s, k) {
+			t.Fatalf("★ 脚本漏了 DB 键 %s", k)
+		}
+	}
+}
+
+// ★★★ 判据：目标目录非空必须拒绝（防覆盖已有数据）。
+func TestMigrateScriptRefusesNonEmptyTarget(t *testing.T) {
+	s := NewMigratePlan("/old", "/new").Script()
+	if !strings.Contains(s, `[ -n "$(ls -A "$NEW"`) {
+		t.Fatal("★ 未检查目标目录非空 ⇒ 可能覆盖已有数据")
+	}
+}
+
+// ★★★ 判据：源目录不能被删（安全兜底）。
+func TestMigrateScriptNeverDeletesSource(t *testing.T) {
+	s := NewMigratePlan("/old", "/new").Script()
+	// ★ 排除掉 two 类"不是可执行语句"的行：
+	//   · 注释（#）
+	//   · heredoc 的正文（<<'EOF' ... EOF）—— 那只是打印给用户看的提示文本，
+	//     实测把提示里那句"sudo rm -rf $OLD"当成了"脚本删源目录"（假红）
+	inHeredoc := false
+	for _, line := range strings.Split(s, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if strings.Contains(trimmed, "<<'EOF'") || strings.Contains(trimmed, `<<"EOF"`) {
+			inHeredoc = true
+			continue
+		}
+		if inHeredoc {
+			if trimmed == "EOF" {
+				inHeredoc = false
+			}
+			continue
+		}
+		if strings.HasPrefix(trimmed, "#") {
+			continue
+		}
+		if strings.Contains(trimmed, `rm -rf "$OLD"`) {
+			t.Fatalf("★ 脚本执行了删除源目录：%s", line)
+		}
+	}
+}
diff --git a/internal/systemd/sync.go b/internal/systemd/sync.go
new file mode 100644
index 00000000..dc602af5
--- /dev/null
+++ b/internal/systemd/sync.go
@@ -0,0 +1,244 @@
+// Package systemd 负责「数据库配置 ↔ systemd 单元」的**双向一致性**。
+//
+// ## 要解决的问题（用户 2026-10-17 指出）
+//
+// 内核有两处"数据目录"来源，且**不等价**：
+//
+//	-data <dir>                    ← systemd 单元，决定 ks.DataDir
+//	core.daemon.data_dir           ← 数据库，决定 ks.Cfg.Daemon.DataDir
+//
+// 实测（把副本 DB 的 data_dir 改成 /tmp/DB_SAYS，-data 仍给 /tmp/ddtest）：
+//
+//	知识库迁移扫描失败: open /tmp/DB_SAYS/knowledge: no such file
+//	text memory active at /tmp/DB_SAYS/memory/text
+//
+// 而 ks.DataDir（-data）管的是 memory/graph.db（数据最多的图记忆）与
+// 插件 SettingsAPI.DataDir()。⇒ **两者不一致时数据会分裂**：图记忆在 A、
+// 文本/知识/文档在 B，检索跨目录、备份会漏。
+//
+// 生产当前两者都是 /home/newqqagent，所以没暴露。但 WebUI / CLI 允许改
+// core.daemon.data_dir 而**没有任何提示** —— 用户改完重启就会发现数据"丢了"。
+//
+// ## 本包的职责
+//
+//  1. 检测不一致（Check）
+//  2. 生成**可以直接复制执行**的修复命令（SyncCommand）
+//
+// ## ★ 关键设计：命令必须内联替换，不让用户手工编辑
+//
+// 用户明确要求：
+//
+//	「指令应当直接包含替换部分而不是让用户手动修改」
+//
+// 所以生成的是**一条幂等的 sed 原地替换 + daemon-reload + restart**，
+// 而不是"请编辑文件把 -data 改成 xxx"。理由：
+//
+//	· 手工编辑会漏掉 drop-in（生产用 drop-in 覆盖 ExecStart，改主单元无效）
+//	· 手工编辑容易把 --role=guard 一起改坏
+//	· 一条命令可审计、可复制、可回滚（带 .bak）
+package systemd
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// UnitName 是内核的服务单元名。
+const UnitName = "homeagent.service"
+
+// State 描述一次一致性检查的结果。
+type State struct {
+	// RuntimeDataDir 是当前进程**实际**用的数据目录（来自 -data）。
+	RuntimeDataDir string
+	// ConfigDataDir 是数据库里 core.daemon.data_dir 的值。
+	ConfigDataDir string
+	// UnitPath 是主单元文件路径（通常 /etc/systemd/system/homeagent.service）。
+	UnitPath string
+	// UnitDataDir 从单元文件里解析出的 -data 值（可能为空=没解析到）。
+	UnitDataDir string
+	// DropIns 是覆盖 ExecStart 的 drop-in 路径（非空时改主单元无效）。
+	DropIns []string
+}
+
+// InSync 报告运行期与数据库配置是否一致。
+func (s State) InSync() bool {
+	return s.RuntimeDataDir == "" || s.ConfigDataDir == "" ||
+		filepath.Clean(s.RuntimeDataDir) == filepath.Clean(s.ConfigDataDir)
+}
+
+// Describe 给出人类可读的诊断（用于启动日志 / WebUI 提示）。
+func (s State) Describe() string {
+	if s.InSync() {
+		return ""
+	}
+	return fmt.Sprintf(
+		"数据目录不一致：内核按 -data 用的是 %q，而数据库 core.daemon.data_dir 是 %q。\n"+
+			"这两者**不等价**：\n"+
+			"  · -data                    → memory/graph.db（图记忆）、插件数据根目录\n"+
+			"  · core.daemon.data_dir     → memory/text、memory/documents、knowledge、nlp、adapters、agentfs\n"+
+			"⇒ 不一致会让数据分裂，检索跨目录、备份会漏。",
+		s.RuntimeDataDir, s.ConfigDataDir)
+}
+
+// Check 探测当前一致性。任何一步失败都返回已收集到的部分信息 + 错误，
+// 由调用方决定"降级为只告警"还是"当失败处理"。
+func Check(runtimeDataDir, configDataDir string) (State, error) {
+	st := State{RuntimeDataDir: runtimeDataDir, ConfigDataDir: configDataDir}
+
+	unitPath := filepath.Join("/etc/systemd/system", UnitName)
+	if _, err := os.Stat(unitPath); err == nil {
+		st.UnitPath = unitPath
+		if v := parseDataFlagFromFile(unitPath); v != "" {
+			st.UnitDataDir = v
+		}
+	} else {
+		// 发行版可能装在 /lib/systemd/system
+		alt := filepath.Join("/lib/systemd/system", UnitName)
+		if _, err := os.Stat(alt); err == nil {
+			st.UnitPath = alt
+			st.UnitDataDir = parseDataFlagFromFile(alt)
+		}
+	}
+
+	// drop-in 里若有 `ExecStart=`（清空）后重设，改主单元无效 —— 必须一并处理。
+	dropDir := filepath.Join("/etc/systemd/system", UnitName+".d")
+	if entries, err := os.ReadDir(dropDir); err == nil {
+		for _, e := range entries {
+			if e.IsDir() || !strings.HasSuffix(e.Name(), ".conf") {
+				continue
+			}
+			p := filepath.Join(dropDir, e.Name())
+			if b, err := os.ReadFile(p); err == nil {
+				if reExecStartReset.Match(b) {
+					st.DropIns = append(st.DropIns, p)
+				}
+			}
+		}
+	}
+	return st, nil
+}
+
+var (
+	reDataFlag       = regexp.MustCompile(`(?:^|\s)-data[= ]([^\s"']+)`)
+	reExecStartLn    = regexp.MustCompile(`(?m)^\s*ExecStart\s*=.*$`)
+	reExecStartReset = regexp.MustCompile(`(?m)^\s*ExecStart\s*=\s*$`)
+)
+
+func parseDataFlagFromFile(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	if m := reDataFlag.FindSubmatch(b); m != nil {
+		return string(m[1])
+	}
+	return ""
+}
+
+// SyncCommand 生成**可直接复制执行**的修复命令。
+//
+// ## 为什么是一条内联 sed 而不是"请编辑文件"
+//
+// 用户明确要求「指令应当直接包含替换部分」。所以这里把新值直接拼进命令：
+//
+//	sudo sed -i.bak 's|-data [^ ]*|-data /新路径|' /etc/systemd/system/homeagent.service
+//	sudo systemctl daemon-reload && sudo systemctl restart homeagent
+//
+// 特性：
+//
+//	· **幂等**：再跑一次结果相同
+//	· **带 .bak**：可回滚（cp xxx.bak xxx）
+//	· **只替换 -data 的值**，不碰 --role=guard 等其他参数
+//	· drop-in 里若重设了 ExecStart，会**指出具体文件**并同样给出 sed 命令
+//
+// want 为空时用 ConfigDataDir。
+func (s State) SyncCommand(want string) string {
+	if want == "" {
+		want = s.ConfigDataDir
+	}
+	want = strings.TrimSpace(want)
+	if want == "" {
+		return ""
+	}
+	var b strings.Builder
+
+	b.WriteString("# 1) 把 systemd 单元的数据目录改成 ")
+	b.WriteString(want)
+	b.WriteString("（幂等，自动留 .bak）\n")
+
+	if s.UnitPath != "" {
+		fmt.Fprintf(&b,
+			"sudo sed -i.bak -E 's|(-data[= ])[^ \"'\"']+|\\1%s|' %s\n",
+			sedEscapeRepl(want), s.UnitPath)
+	}
+	// drop-in 覆盖了 ExecStart 的，必须**也**改它，否则主单元改了也没用。
+	for _, d := range s.DropIns {
+		fmt.Fprintf(&b,
+			"sudo sed -i.bak -E 's|(-data[= ])[^ \"'\"']+|\\1%s|' %s\n",
+			sedEscapeRepl(want), d)
+	}
+
+	b.WriteString("\n# 2) 让 systemd 重新加载并重启（guard 会用新参数拉起 worker）\n")
+	b.WriteString("sudo systemctl daemon-reload && sudo systemctl restart ")
+	b.WriteString(strings.TrimSuffix(UnitName, ".service"))
+	b.WriteString("\n")
+
+	b.WriteString("\n# 3) 校验（应看到 ExecStart 里的 -data 已是新值）\n")
+	b.WriteString("systemctl show ")
+	b.WriteString(UnitName)
+	b.WriteString(" -p ExecStart --no-pager\n")
+
+	b.WriteString("\n# 回滚（若需）\n")
+	if s.UnitPath != "" {
+		fmt.Fprintf(&b, "sudo cp %s.bak %s && sudo systemctl daemon-reload && sudo systemctl restart %s\n",
+			s.UnitPath, s.UnitPath, strings.TrimSuffix(UnitName, ".service"))
+	}
+	return b.String()
+}
+
+// sedEscapeRepl 转义 sed 替换段里的特殊字符（分隔符用 |）。
+func sedEscapeRepl(s string) string {
+	s = strings.ReplaceAll(s, `\`, `\\`)
+	s = strings.ReplaceAll(s, "|", `\|`)
+	s = strings.ReplaceAll(s, "&", `\&`)
+	return s
+}
+
+// RestartCommand 返回「热更新」命令：只重启（不动 systemd 配置）。
+//
+// 与 SyncCommand 的区别：配置没变、只换了二进制时用这个。
+// 走 WebUI 的 agent restart 端点即可（exit 42 → guard 用新二进制重拉），
+// 这里给出不依赖 WebUI 的等价 curl。
+func RestartCommand(addr, apiKey string) string {
+	return fmt.Sprintf(`curl -sS -X POST \
+  -H "X-API-Key: %s" \
+  "http://%s/api/v1/agents/agent/restart"`, apiKey, addr)
+}
+
+// IsUnderSystemd 报告当前进程是否由 systemd 拉起（用于决定是否提示提权）。
+func IsUnderSystemd() bool {
+	// INVOCATION_ID 由 systemd 注入，是最可靠的判据（容器里也可能有 systemd）。
+	if os.Getenv("INVOCATION_ID") != "" {
+		return true
+	}
+	// 回退：父进程是 pid 1 且 /run/systemd/system 存在。
+	if _, err := os.Stat("/run/systemd/system"); err != nil {
+		return false
+	}
+	return os.Getppid() == 1
+}
+
+// HasSudo 报告当前进程能否免密 sudo（决定提示里要不要写 sudo）。
+func HasSudo() bool {
+	if os.Geteuid() == 0 {
+		return true
+	}
+	if _, err := exec.LookPath("sudo"); err != nil {
+		return false
+	}
+	return exec.Command("sudo", "-n", "true").Run() == nil
+}
diff --git a/third_party/homeagent-sdk/sdk/facilities.go b/third_party/homeagent-sdk/sdk/facilities.go
new file mode 100644
index 00000000..da2f0238
--- /dev/null
+++ b/third_party/homeagent-sdk/sdk/facilities.go
@@ -0,0 +1,77 @@
+// Package sdk —— 内核**设施名**（插件声明启动时机时用的名字）。
+//
+// ## 用途
+//
+// 插件在 `plg.json` / `plugin.json` 里声明 `requires_facilities`，
+// 内核据此决定**何时拉起它**（设计：kernel-modularization-design.md §2.6）：
+//
+//	不声明              ⇒ 等内核**完全**初始化（默认；存量插件零改动）
+//	声明 ["config"]     ⇒ config 就绪即拉起（**尽早启动**）
+//	声明 ["config","llm"]⇒ 两者都就绪才拉起
+//
+// ## ★ 为什么这些常量必须在**公开 SDK** 里
+//
+// 它们原本只定义在内核的 `internal/kernelmod`（Go 的 internal 规则禁止
+// 外部包 import）⇒ 插件作者**无从得知**能写哪些名字，只能照文档抄，
+// 而抄错（如 "llmservice" vs "llm"）的后果是：
+//
+//	插件**永远等不到就绪** ⇒ **永不启动**，且无报错。
+//
+// 这正是本仓反复吃亏的"静默降级"形态。把名字放进公开 SDK 后：
+//
+//	· 插件作者 import 常量 ⇒ **拼错是编译错误**（而不是运行期静默）
+//	· 且这是内核与插件之间的**契约**，理应公开
+//
+// ## 内核侧的一致性
+//
+// 内核在 `internal/kernelmod/facilities.go` 定义同名常量，
+// 判据 `TestFacilityNamesMatchPublicSDK` 保证两边**逐字一致**
+// （防止改一处忘另一处 —— 那会让插件声明的名字悄悄失效）。
+package sdk
+
+// 内核设施名（模块 Provides 的名字）。
+//
+// ★ 这些是**字符串值**，与内核 internal/kernelmod/facilities.go 必须逐字一致。
+const (
+	// FacilityConfig 是配置快照（cfg）就绪。
+	FacilityConfig = "config"
+	// FacilityKernelIO 是 IOManager + EventBus 就绪。
+	FacilityKernelIO = "kernel-io"
+	// FacilityMemory 是图记忆（含索引/社交图/蒸馏）就绪。
+	FacilityMemory = "memory"
+	// FacilityLua 是 Lua 协议适配 VM 就绪。
+	FacilityLua = "lua"
+	// FacilitySupervisor 是代理生命周期守护就绪。
+	FacilitySupervisor = "supervisor"
+	// FacilityTracker 是变更追踪（overlayfs）就绪。
+	FacilityTracker = "tracker"
+	// FacilityTextMemory 是文本记忆就绪。
+	FacilityTextMemory = "textmem"
+	// FacilityLLM 是多源 Provider 管理就绪。
+	FacilityLLM = "llm"
+	// FacilityDocStore 是文档记忆就绪。
+	FacilityDocStore = "docmem"
+	// FacilityKnowledge 是知识库就绪。
+	FacilityKnowledge = "knowledge"
+	// FacilityMultimodal 是多模态向量空间就绪。
+	FacilityMultimodal = "multimodal"
+	// FacilityONNX 是依存句法分析器就绪。
+	FacilityONNX = "onnx"
+	// FacilityStageHost 是阶段管道 + 插件注册表就绪。
+	FacilityStageHost = "stagehost"
+	// FacilityAgent 是主 Agent 就绪（**最晚**的一个，通常在插件加载前）。
+	FacilityAgent = "agent"
+)
+
+// KnownFacilities 返回本 SDK 已知的全部设施名（供工具链校验插件声明）。
+//
+// ★ 它让**打包期**就能发现"插件声明了不存在的设施名" —— 比运行期发现早得多
+// （运行期发现意味着用户已经装上了那个永不启动的插件）。
+func KnownFacilities() []string {
+	return []string{
+		FacilityConfig, FacilityKernelIO, FacilityMemory, FacilityLua,
+		FacilitySupervisor, FacilityTracker, FacilityTextMemory, FacilityLLM,
+		FacilityDocStore, FacilityKnowledge, FacilityMultimodal, FacilityONNX,
+		FacilityStageHost, FacilityAgent,
+	}
+}
diff --git a/third_party/homeagent-sdk/sdk/plugin.go b/third_party/homeagent-sdk/sdk/plugin.go
index f055ec60..9cc10fb0 100644
--- a/third_party/homeagent-sdk/sdk/plugin.go
+++ b/third_party/homeagent-sdk/sdk/plugin.go
@@ -385,8 +385,35 @@ type PluginMgrAPI interface {
 	ReloadOne(name string) error
 	// ListLoadedPlugins 列出已加载插件。
 	ListLoadedPlugins() []string
-	// IsPluginDisabled 查询插件是否被禁用。
+	// IsPluginDisabled 查询插件是否被**持久**禁用。
 	IsPluginDisabled(name string) bool
+
+	// ---- 运行态启停（设计 docs/zh/kernel-modularization-design.md §2.6.7）----
+	//
+	// ★ 与 DisablePlugin/EnablePlugin 的区别（这是这两个方法存在的全部理由）：
+	//
+	//	DisablePlugin/EnablePlugin ⇒ 改**持久**状态（disabled_plugins 配置）
+	//	StopPlugin/StartPlugin     ⇒ 只改**运行**状态，不写任何配置
+	//
+	// 心智模型：插件是 agent 的应用程序。
+	//   · disabled_plugins = 系统里"禁止运行这个程序"（持久决定）
+	//   · runtimeStopped   = 用户"现在关掉这个窗口"（运行决定，重启复位）
+	//
+	// 混用二者的后果（实测缺陷）：想临时关一下却顺带关掉了开机自启
+	// ⇒ 用户下次开机会发现"怎么不启动了"。
+
+	// StopPlugin 运行态关闭：现在停掉，**不改持久状态**。重启后按
+	// auto_start + disabled_plugins 正常决定。
+	//
+	// 拒绝作用于 pluginmgr 自身与 webui（自锁/失联，内核层面拦死）。
+	StopPlugin(name string) error
+	// StartPlugin 运行态启动：现在拉起，**不解除持久禁用**。
+	//
+	// 被持久禁用的插件会被拒绝（提示先用 EnablePlugin）——
+	// 持久禁用是用户的明确决定，运行态操作不该绕过它。
+	StartPlugin(name string) error
+	// IsPluginRuntimeStopped 查询插件是否处于运行态关闭。
+	IsPluginRuntimeStopped(name string) bool
 }
 
 // StageScope controls which events a stage handler receives.
@@ -449,6 +476,8 @@ type PluginSDK struct {
 	llm            LLMAPI
 	sett           SettingsAPI
 	social         SocialAPI
+	secrets        SecretsAPI
+	rawFiles       RawFilesAPI
 	events         EventSubscriber
 	plgMgr         PluginMgrAPI
 
@@ -540,6 +569,16 @@ func (s *PluginSDK) LLM() LLMAPI {
 }
 
 // Social returns the social graph API (may be nil if not available).
+// Secrets returns the kernel secret vault API.
+//
+// ★ 内核未启用安全模块时它**不是 nil**，而是 Available() 返回 false 的
+// 实现 —— 这样插件可以统一地"先问 Available 再决定"，不必到处判空。
+func (s *PluginSDK) Secrets() SecretsAPI {
+	s.apiMu.RLock()
+	defer s.apiMu.RUnlock()
+	return s.secrets
+}
+
 func (s *PluginSDK) Social() SocialAPI {
 	s.apiMu.RLock()
 	defer s.apiMu.RUnlock()
@@ -703,6 +742,30 @@ func (s *PluginSDK) SetIOInjector(io IOInjector) {
 }
 
 // SetMemoryAPI sets the memory API (called by the core at startup).
+// RawFiles 返回随包分发资源的读取接口（内核装配时注入）。
+//
+// 未注入时返回 nil —— 那是旧内核或测试环境。插件应判空后**响亮失败**，
+// 而不是拿一个空实现继续（会表现为"资源读出来是空的"，与"资源不存在"难区分）。
+func (s *PluginSDK) RawFiles() RawFilesAPI {
+	s.apiMu.RLock()
+	defer s.apiMu.RUnlock()
+	return s.rawFiles
+}
+
+// SetRawFilesAPI 由内核装配时注入（插件不调用它）。
+func (s *PluginSDK) SetRawFilesAPI(v RawFilesAPI) {
+	s.apiMu.Lock()
+	s.rawFiles = v
+	s.apiMu.Unlock()
+}
+
+// SetSecretsAPI 由内核装配时注入（插件不调用它）。
+func (s *PluginSDK) SetSecretsAPI(v SecretsAPI) {
+	s.apiMu.Lock()
+	s.secrets = v
+	s.apiMu.Unlock()
+}
+
 func (s *PluginSDK) SetMemoryAPI(mem MemoryAPI) {
 	s.apiMu.Lock()
 	s.mem = mem
diff --git a/third_party/homeagent-sdk/sdk/rawfiles.go b/third_party/homeagent-sdk/sdk/rawfiles.go
new file mode 100644
index 00000000..bd0ff23e
--- /dev/null
+++ b/third_party/homeagent-sdk/sdk/rawfiles.go
@@ -0,0 +1,56 @@
+package sdk
+
+// RawFilesAPI 让插件读写**随包分发的资源**（rawfile）。
+//
+// ## 是什么
+//
+// `hmapdev build` 会把工程根 `rawfile/` 下的全部内容（以及 plg.json
+// `rawfiles` 声明的外部路径）打进 .hmap；内核解包时保留路径，落到：
+//
+//	<插件目录>/rawfile/<原相对路径>
+//
+// 本接口就是插件读这些资源的唯一入口。
+//
+// ## 为什么不让插件自己拼路径
+//
+// 插件**不知道自己的安装目录**：内核的 `PluginDir()` 是给插件管理器用的，
+// 不暴露给插件自身。而且"包内资源"与"运行期生成的文件"必须分开 ——
+// 前者只读、随升级替换，后者可写、跨升级保留。混在一个目录里，
+// 升级时会误删运行期数据，或把旧资源留在原地。
+//
+// 所以：
+//
+//	RawFiles().Read("main/prompt.txt")   → 读**包内**资源（只读）
+//	RawFiles().WorkDir()                 → 拿**可写**工作目录（运行期数据放这）
+//
+// ## 安全边界
+//
+// 所有路径都相对 rawfile/ 根，**必须拒绝路径穿越**（`../`）。
+// 资源文件来自包，包可能被替换 —— 让插件能借它读到 `/etc/shadow`
+// 就是一个真实的提权面。
+type RawFilesAPI interface {
+	// Read 读一个包内资源（路径相对 rawfile/ 根）。
+	//
+	// 例：Read("main/prompt.txt") 读 <插件目录>/rawfile/main/prompt.txt。
+	Read(rel string) ([]byte, error)
+
+	// List 列出某个目录下的条目（相对 rawfile/ 根；"" 表示根）。
+	//
+	// 返回的名字是**相对 path 的单层名**（不是全路径），目录名带 `/` 后缀。
+	List(rel string) ([]string, error)
+
+	// Exists 报告某个资源是否存在。
+	Exists(rel string) bool
+
+	// Dir 返回包内资源的根目录（只读）。
+	//
+	// 给需要把整个目录交给外部工具的插件用（如把 node 目录的路径
+	// 传给 exec.Command）。**不要往这里写东西** —— 它在包里，随升级替换。
+	Dir() string
+
+	// WorkDir 返回一个**可写**目录，供插件放运行期生成的文件。
+	//
+	// 与 Dir() 分开的原因：Dir() 里的东西随升级被整体替换，
+	// 运行期数据放那里会在下次升级时丢失。
+	WorkDir() string
+}
diff --git a/third_party/homeagent-sdk/sdk/secrets.go b/third_party/homeagent-sdk/sdk/secrets.go
new file mode 100644
index 00000000..a31ae35a
--- /dev/null
+++ b/third_party/homeagent-sdk/sdk/secrets.go
@@ -0,0 +1,111 @@
+package sdk
+
+// SecretsAPI 是插件访问**内核变量库**的接口。
+//
+// ## 为什么要有它（去重）
+//
+// 在此之前，commondev 插件自带了一整套加密存储（`secrets.json` +
+// AES-256-GCM + 别名表 + `${ENV}` 解析），与内核的 `internal/security`
+// **完全重复**：
+//
+//	             内核 security.Store        插件 unifiedSecretFile
+//	  落盘        secrets.json               secrets.json
+//	  加密        AES-256-GCM                AES-256-GCM
+//	  别名        HMAC 自动派生              用户指定
+//	  引用语法     @{sec_xxx}                 @{name}
+//
+// 重复的代价不只是代码量：**两套变量库互不可见** —— 内核拦截时登记的
+// 变量，插件看不到；插件登记的，内核拦截不认识。结果是同一个凭据可能
+// 在两处各存一份，而使用者不知道哪个才是权威。
+//
+// ## ★ 安全设计：明文的边界
+//
+// 内核的硬约束 S1 是「不提供取回明文的接口」—— 理由是一旦 LLM 能取回，
+// 它就能把明文写回上下文，整层防护作废。
+//
+// 那为什么插件可以拿到明文？因为**边界不在插件侧**：
+//
+//	① 内核在**插件 handler 之前**就把工具参数里的 @{别名} 填好了
+//	   （`StageHost.ExecuteTool` → `security.FillMap`）—— 插件本来
+//	   就能从 args 里读到明文，这是设计使然（否则插件无法用凭据）。
+//	② 明文若被插件**返回**给内核，会被两处拦回别名：
+//	   · `ContextEvent` 的 scrub（记忆/历史侧路）
+//	   · provider 装饰器（出向，LLM 永不看到）
+//
+// 两条都有判据钉住（`leakback_test.go`）。所以：
+//
+//	**暴露 Fill 不新增泄漏面** —— 它不是「开了一个口子」，
+//	而是把「本来就存在的能力」从各插件自己实现改为统一接口。
+//
+// ⚠️ 但绝不能暴露 `Reveal(alias) -> 明文` 这样的**按名字直取**接口：
+// 那会让插件（以及通过插件操纵它的 LLM）枚举别名并逐个取值。
+// 本接口刻意**没有**这样的方法 —— 见下面 Fill 与 List 的签名。
+//
+// ## 与 Encrypt/Decrypt 的区别
+//
+// 插件常把凭据存进自己的配置文件（如 pi 的 `auth.json`）。那些文件权限
+// 0600 但**明文落盘**。`Encrypt`/`Decrypt` 提供 at-rest 加密，
+// 密钥由内核统一管理，插件不必自持密钥（自持会让密钥散落、无法轮换）。
+type SecretsAPI interface {
+	// Store 把一个凭据登记进内核变量库，返回其**别名**。
+	//
+	// 之后在工具参数里写 @{别名}，内核会在调用插件前换回真实值。
+	//
+	// ★ 只返回别名，不回显明文 —— 避免插件（或它转述给 LLM 的内容）
+	// 顺带把明文带出去。
+	//
+	// note 是给人看的用途说明（如「Gitea 推送令牌」）。
+	Store(value, note string) (alias string, err error)
+
+	// List 列出变量库的元信息（别名/来源/备注/命中次数）—— **不含明文**。
+	//
+	// ★ 刻意返回元信息而非值：调用方拿不到明文，只能引用。
+	List() []SecretInfo
+
+	// Forget 按别名删除一个变量。
+	//
+	// ★ 变量库**不自动淘汰**（用户明确）：泄漏控制靠主动删除，不靠超时。
+	// 所以凭据用完后应主动删。
+	Forget(alias string) error
+
+	// Fill 把一段文本里的 @{别名} 换成明文。
+	//
+	// 用途：插件需要把明文喂给**不经过内核参数回填**的地方 ——
+	// 例如 commondev 的 enc_shell 要把命令经 **stdin** 送给 bash
+	//（不是 argv，避免本机其他进程从 /proc/<pid>/cmdline 读到明文）。
+	//
+	// ★ 为什么这个方法是安全的（而不是"开了个取回明文的口子"）：
+	// 插件**本来就**能从 `args` 里拿到内核填好的明文 ——
+	// 内核在 handler 之前就填了。Fill 只是让插件能对**自己构造的文本**
+	// 做同样的事（如读文件内容、拼一段脚本）。
+	//
+	// 它**不是**按名字直取：要填谁必须先在文本里写出那个别名，
+	// 而别名本身不泄漏明文（HMAC 派生）。想枚举就得先 List，
+	// 而 List 只给元信息 —— 拿到别名后仍只能用，不能读回。
+	//
+	// 返回替换处数与用到的别名（便于插件做输出脱敏时的比对）。
+	Fill(text string) (out string, replaced int, aliases []string)
+
+	// Encrypt 加密一段字节用于插件自己落盘（密钥由内核管理）。
+	// 返回的串带版本前缀，可直接存文件。
+	Encrypt(plain []byte) (string, error)
+
+	// Decrypt 解密由 Encrypt 产生的串。
+	Decrypt(stored string) ([]byte, error)
+
+	// Available 报告变量库是否可用（内核未启用安全模块时为 false）。
+	//
+	// ★ 插件应据此**响亮失败**而不是静默降级 —— 例如
+	// 「密钥不可用 ⇒ 拒绝明文存储」。
+	Available() bool
+}
+
+// SecretInfo 是一条变量的元信息（**不含明文**）。
+type SecretInfo struct {
+	Alias     string `json:"alias"`
+	Source    string `json:"source"`               // intercepted | submitted
+	Note      string `json:"note,omitempty"`
+	CreatedAt string `json:"created_at"`
+	UpdatedAt string `json:"updated_at,omitempty"`
+	Hits      int    `json:"hits,omitempty"`
+}
diff --git a/third_party/homeagent-sdk/sdk/settings.go b/third_party/homeagent-sdk/sdk/settings.go
index 75f553d8..f6590fa8 100644
--- a/third_party/homeagent-sdk/sdk/settings.go
+++ b/third_party/homeagent-sdk/sdk/settings.go
@@ -7,6 +7,21 @@ type SettingsAPI interface {
 	// Set writes a config value to the plugin's own config table.
 	Set(key string, value interface{}) error
 
+	// SetSecret writes a value that is ALWAYS encrypted at rest, regardless of
+	// the key name. Use it when the key name is neutral (e.g. "blob", "conn")
+	// and so cannot be detected as sensitive automatically.
+	//
+	// Returns an error (not a silent plaintext write) when no master key is
+	// installed — a plugin that believes it stored a secret must not end up
+	// with plaintext on disk.
+	//
+	// The companion read is GetSecret. ConfigDef.Secret/Type=="password" and
+	// sensitive key names are encrypted automatically and do NOT need this.
+	SetSecret(key string, value interface{}) error
+
+	// GetSecret reads a value written by SetSecret (transparently decrypted).
+	GetSecret(key string) (string, error)
+
 	// List returns all keys matching the given prefix.
 	List(prefix string) ([]string, error)