feat: 模块化内核（编译期依赖图定序）+ 密钥防火墙 + 插件三态生命周期 (#10)

* feat(kernel): 模块化内核 + 编译期依赖图定序

把单体 init 序列拆成「模块自声明依赖 + 编译期生成依赖图 + 运行期只读图」。

## 为什么

原 cmd/homed/main.go 里 17 步 init 是**手写顺序**，依赖关系只存在于
注释和人脑里。实测踩到的坑（见 docs/zh/kernel-modularization-design.md）：
 · nlp.defaultParser 被 initONNXParser 写、被 distiller 读，两者相距 60 行，
   只靠 ticker 10min 才没炸（隐式依赖，无声明）
 · 加一个模块要人肉找"该插在哪"，插错的表现是运行期 nil 解引用
 · 关停是 defer ks.CloseAll()，而热更新路径 os.Exit(42) **跳过 defer**
   ⇒ docStore/distiller/textMem 的 flush 全部丢失（每次热更新都发生）

## 怎么改

- internal/kernelboot/：KernelState（一个结构体收全部包级共享变量，字段
  nil 安全）、Module 接口、graphfile（依赖图编解码 + 与二进制 hash 对账）、
  scheduler（按 BFS 层并行 Init）、syncbus（层边界写通知）、
  lifecycle（Quiesce/Resume 可逆伪关机，区别于一次性 CloseAll）
- internal/kernelmod/<name>/：每个模块一个文件夹，Requires/Provides 自声明；
  all/all.go 是唯一的 import 清单（Go 循环导入约束）
- cmd/homed-depgraph：编译期生成依赖图，Makefile 注入 digest
- 运行期只**读**图，不计算顺序（顺序是编译期决定的，源码里没有中央清单）

## 判据

kernelboot 8 条 + 图失败模式 7 条（全部拒绝并给准确错误）+ 模块目录数
与注册表一致性。变异测试 15/15 咬住，含：
 · 删掉 AddCloser 的锁 → -race 报数据竞争
 · Scheduler 同批跑去重 → 203 vs 200
 · 图 hash 不匹配 → 拒绝启动

## 顺带修的缺陷

热更新路径漏调模块关闭 ⇒ 显式 stopKernelModules()，并用 AST 判据钉住
"必须在 os.Exit 之前"（字符串检查在本仓已骗过我三次）。

实测：冷启动 1630ms（5 层/17 模块，原 17 步串行）；生产 22 插件全部建链。

* feat(security): 密钥防火墙 + 配置加密 + close 纪律

## 密钥防火墙

模型只见别名、不见明文；插件工具调用入口（StageHost.ExecuteTool）做入向
回填。三维能力：
 · 出向：工具输出里的密钥被替换成 [[secret:name]] 别名后才进上下文
 · 入向：模型传别名，入口处填回真值（插件完全无感知）
 · 存储：config.db 里不存明文（0644 的库可读），敏感值独立 0600 文件

模式库「宁漏勿误伤」：宁可漏掉一次替换，也不把正常文本误当密钥。

## 配置加密

- internal/security/{codec,key,keyring,store,global}.go：AES-256-GCM，
  enc:v1: 前缀，密钥轮换（OldKeys 解码 + 新钥加密）
- harden.go：数据目录权限收紧
- embedded.go：支持内嵌主密钥（可选，仍保留外部 key 文件路径）
- EncryptExistingSecrets / AuditSecrets：启动时幂等迁移 + 审计

## close 纪律（用户明确要求：只要调 close 就要有前置检查）

internal/safeclose：Safe / SafeFunc。全仓 37 处裸 close(chan) → 0。
关键教训（都写进注释和判据）：
 · `select { case <-ch: default: close(ch) }` **不是**并发安全的
   （两个 goroutine 可同时命中 default）—— healthcheck 原先是这种写法
 · `sync.Once` **不可重入**：X.Do(func(){ Safe(&X, ...) }) 会自锁，
   症状是 go test 直接挂住（3 个包 600s 超时），栈里只有嵌套的 Once.Do
 · map 里按请求持有的 channel（mcp/stdio.go、clawhubadapter/sidecar.go）
   改成 *pendingRPC 包装，每通道一个 once

## 判据

security 全量 + TestNoBareCloseOutsideSafeclose（AST 级扫描，含注释剥离）
+ TestNoNestedSelfOnceDeadlock（正则修正：\w+ 不匹配点号，捕获组要含 '.'）。
变异 2/2 咬住。全量 52 包 ok。

* feat(plugin+deploy): 插件三态生命周期、数据目录迁移、发行包修复

## 插件三态生命周期（用户要求：自动启动 / 启用但不自动启动 / 禁用）

- Manifest 新增 requires_facilities / auto_start（*bool，用于区分
  "未声明"与"显式 false"）
- plugin-host 模块（internal/kernelmod/pluginhost）：用 kernelboot.Scheduler
  按依赖时机拉起，**不再手写两阶段**
- 运行态停启 StopPlugin/StartPlugin **可逆**：不写 disabled_plugins
  （不改用户决定）、不置 shuttingDown（之后还能加载）、会摘掉注册面
- 与 StopAll 的区别写进注释 —— StopAll 置 shuttingDown 后**永久无法加载**，
  那是进程退出用的，误用于"暂停"就是关了就死

## 数据目录迁移（伪关机 → 迁移 → 唤醒）

- kernelboot/lifecycle.go：Quiesce/Resume（可逆，区别于一次性 CloseAll），
  逆序暂停、逆序恢复、Pause 失败回滚
- kernelboot/migrate.go：BeginMigration/End 编排（先停插件 → 再停内核写者
  → 等在途归零）
- distiller/textmem 增 Pause/Resume 门（不是 cancel —— cancel 不可逆，
  恢复要重建整个对象）
- 模块 migration：体检 + 生成可执行迁移脚本

★ 迁移脚本的三个实测教训（都写成了判据）：
 1. 无条件改 /etc/systemd/system ⇒ 演练把**生产** -data 改成了演练目录。
    加 --dry-run（零改动）+ 强制校验 systemd 当前 -data == OLD
 2. 本机没装 rsync，脚本在"服务已停、数据未搬"处硬失败 ⇒ cp -a 回退，
    并明确警告不保硬链接/ACL（生产 plugindev 有大量 git 硬链接）

## 发行包修复（全部经实测确认）

 1. package-linux.sh **完全漏打 depgraph.bin** ⇒ 内核 exit 1
    （"生产构建（内嵌 hash 非空）但读不到依赖图"）
 2. build_homed 不走 Makefile ⇒ 单独修 Makefile 无效，必须同时生成图+注入
 3. build.sh 的 LDFLAGS 用**历史模块路径 gitcode.com** ⇒ -X 静默 no-op
    ⇒ --version 显示 unknown
 4. Makefile -ldflags 用**单引号** ⇒ 注入了字面 $GRAPH_HASH

## ★ build.sh 的版本号必须校验（真实事故）

原 `VERSION="$(git describe --tags --dirty)"`。无 tag 分支上它返回**分支名**
`backup/pre-identity-rewrite-20261005-51-g03d87a4e-dirty`，被注入 meta.Version
⇒ 插件握手判据 MajorVersion() 把整串当主版本 ⇒ **22 个子进程插件全部
握手失败**（"主版本不匹配"）。内核活着、systemd active、日志每条都像
插件的问题 —— 实际是发行包带着非法版本号。

修法：git describe 只在形如 vX.Y.Z 时采用，否则回退 meta.Version（权威源），
并对最终值做形态守卫。deploy/packaging/version_guard_test.go 3 条判据，
变异 2/2 咬住。

## deb 的 systemd unit 改为 guard 模式

ExecStart=/usr/bin/homed --role=guard --data /var/lib/homeagent
（worker exit 42 → guard 重拉，不经过 systemd、不计失败）
含 RestartSteps/RestartMaxDelaySec/TimeoutStopSec + 硬化
（NoNewPrivileges/ProtectSystem/ProtectHome/DevicePolicy/ReadWritePaths）。

## 其他

- internal/plugin/proc：非法 JSON 帧的报错**可定位**（内容摘要 + 可能原因 +
  修法）。生产实测 1038 条非法帧（插件往 stdout 打日志 = 污染协议通道）
- 示例插件 4 个 14 处 fmt.Printf → log.Printf
- hmapdev 模板同步修复；scaffold 判据剥离注释（模板注释里就含 fmt.Printf）

* chore: 收尾（主密钥轮换命令、IPC/知识库加固、SDK 对齐）

- cmd/homed-key-rotate：把 security 里的 RotateKey/RotateKeyFile/RekeySecrets
  串成一条**可执行**的运维路径。没有它，E-1 就只是库里的能力而不是
  "出事时能做的事"，而轮换的价值恰恰在于能执行。
- cmd/homed：kmod_runtime（模块装配入口）、plugins_scheduled（failback
  白名单）、memcandidate、bootstrap_order_test / shutdown_flush_test
- internal/ipc、internal/devicebridge、internal/knowledge：配套加固
- third_party/homeagent-sdk/sdk：PluginMgrAPI 增三态能力（mgrStop/mgrStart/
  mgrIsRuntimeStopped）+ settings 对齐

判据：bootstrap_order_test（启动顺序不依赖手写序列）、
shutdown_flush_test（停机的两条路径必须对称 —— exit 42 会跳过 defer，
热更新路径下模块关闭/flush 曾全部丢失）。

* test(security): 测试夹具改用不可误认的占位值（修 push protection 拦截）

GitHub secret scanning 拦住了推送：三处测试夹具用了"看起来像真密钥"的
字面量：

  internal/security/prefilter_test.go:39
  internal/security/store_test.go:177
  internal/security/survey_test.go:20

它们全是**假密钥**（`AKIAIOSFODNN7EXAMPLE` 是 AWS 官方文档的标准示例，
其余是 `abcdefghij...` 这类可读占位符），但扫描器无法区分 —— 它只看形态。

★ 不绕过（不用 unblock URL、不加 allowlist）：直接改夹具。
原因：一旦允许"假密钥可以通过"，真密钥混进来时就没有最后一道门了。

改法：保留**模式库匹配所需的结构**，把可识别内容换成 FAKE：
  glpat-abcdefghijklmnopqrst       → glpat-FAKE-TEST-TOKEN-NOT-REAL
  sk-abcdefghij...012345           → sk-FAKE-TEST-KEY-NOT-REAL-0000000
  AKIAIOSFODNN7EXAMPLE             → AKIA0000FAKE0000TEST   (保持 20 字符)
  ASIAIOSFODNN7EXAMPLE             → ASIA0000FAKE0000TEST
  xoxb-123456789012-abcdefghijklmnop → xoxb-FAKE-TEST-TOKEN-NOT-REAL

★ 中途踩到一次：AWS 键的模式是 `\b(AKIA|ASIA)[0-9A-Z]{16}\b`（共 20 字符），
我第一次替换成 19 字符的 `AKIAFAKETESTKEY0000` ⇒ 模式匹配不上 ⇒
TestSurvey_WhatIsCaught / TestRecognizesCommonShapes /
TestPrefilterNeverBlocksRealMatches 三条当场变红。
判据正确地拒绝了"为了过扫描器而削弱覆盖"。

顺带核实：全仓 grep 无任何真实密钥泄漏。

* fix(packaging): package-linux.sh 的版本解析与 build.sh 统一

上一版只修了 build.sh，漏了 package-linux.sh —— 它仍只看 git describe：

  VERSION="${VERSION:-$(git describe --tags --dirty)}"

无 tag 分支上 git describe 返回**分支名**
（backup/pre-identity-rewrite-20261005-56-g98850e1），守卫会正确拒绝，
但要求人**手动传 VERSION** 才能打包。而 build.sh 早已能自动回退 meta.Version
⇒ 同一个版本，走 build.sh 打得出来、走 package-linux.sh 打不出来。

危害不只是"要手动传参"：运维为了跑通会去掉守卫，而分支名一旦进
meta.Version 就是**插件协议主版本**的来源 ⇒ 22 个子进程插件全部握手失败
（这是真实发生过的事故，见 3efa4e5）。

修法：两个脚本用同一套规则（git describe 仅在 vX.Y.Z 形态时采用，
否则回退 meta.Version），并对最终值做形态守卫。

判据：TestBothPackagingScriptsShareVersionRules —— 逐个读两个脚本，
要求都能从 meta/meta.go 取权威版本、都校验 git describe 形态。
变异（把 package-linux.sh 改回旧规则）咬住并准确指出是哪个脚本。

实测：不传 VERSION 跑 package-linux.sh，输出
  [PKG] warn: git describe 给出非版本串（...），改用 meta.Version=1.4.0
  Version: 1.4.0

* fix(test): 跨仓判据在 CI 上应 skip 而非 fail（修 PR 双红）

CI 上 "Go build / vet / test" 与 "Build linux/amd64" 双红：

  --- FAIL: TestHmapdevTemplateImplementsAllPluginMgrMethods
      bridge_sync_test.go:170: 读模板: open
      ../../../third_party/homeagent-sdk/tools/hmapdev/templates/proc_main.go.tmpl:
      no such file or directory

## 根因：判据依赖了一个**被 gitignore 的路径**

`.gitignore:33` 有 `third_party/homeagent-sdk/tools/`（SDK 仓自治，本仓不跟踪）。
于是：
  · 本机（完整 SDK 检出）有该文件 ⇒ 判据通过
  · CI（只 checkout 本仓）没有该文件 ⇒ Fatalf ⇒ **必红**

我提交时只在本机跑测试、没看 CI，所以这个问题拖到 PR 才暴露。

## 修法

文件缺失时 `t.Skipf` 而不是 `t.Fatalf`。

★ 这不是"放弃检查"：
  · 跨仓一致性由 **SDK 仓自己的判据**守着
    （tools/hmapdev/scaffold_stdout_test.go 等），那里才是模板的真实归属地
  · 本判据在本机开发时**仍然生效**（已验证：有文件时 PASS，缺文件时 SKIP）

## 验证

 · 本机（有文件）  → PASS（判据真跑）
 · 模拟 CI（移走 tools/）→ SKIP（不再 fail）
 · 全量 53 包 ok / 0 fail

## 顺带

同目录还有 e2e_template_test.go 也读 tools/，但它是 `//go:build` 门控的
e2e 判据，CI 默认不跑，无需处理。

---------

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>

internal/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>' +

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))

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 返回**只含运行态**的小快照：调度器（排队/四级中断队列/中断栈）、

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。

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},
 		},
 	}

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()

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()

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
 }

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)

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)
+	}
+}

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
+}

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]
+}