feat(plugins): 面板动作执行器接线 —— 动作真可用，不再 501 兜底（L1）

- 插件管理器加生产动作处理器登记面（RegisterActions）；未登记处理器/未声明动作仍 404 - web-search 四个动作真读写真源 + 真发 HTTP 探针：plugin.listProviders/saveProvider/ testProvider/reauthProvider（配置落 $DATA_DIR/config/plugins/web-search.json，0600） - 失败回结构化错误码（不含上游原文）+ 审计带 code 字段；501 文案改为「未登记处理器」 - 拆出 panelactions.go（动作索引推导/OptionsActionName/三闸门分发），panels.go 519→347 行缺口（如实）：面板保存后运行中的工具**不热重载**（下一片做）；声明面缺 primary/fallback （按 DECISIONS-2026-10-06 #1/#2 补）。
2026-10-06 14:12:23 +08:00
1 parent a150211468
commit 2e1c3ed3fd
@@ -0,0 +1,413 @@
+package main
+
+// 本文件是「搜索提供商」页**五个动作本体**的数据面（切片 L1/PLG-2 的执行面接线）：
+// 可变源的读写（含失败分类）、表格行 / 下拉候选 / 掩码回填的翻译、以及请求体形状的解析。
+//
+// 上游事实（`plugin.listProviders` / `plugin.saveProvider` / `plugin.testProvider` /
+// `plugin.reauthProvider` / `plugin.providers`）由组合根登记到插件管理器上，登记入口在
+// `wire_plugin_actions.go`，探针的传输层绑定在 `websearch_probe.go`。
+//
+// 三条边界（与登记面同）：只经 runtimeconfig 读写可变源；凭据只出掩码；形状不对就报错。
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	pluginmgr "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/plugin"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config/runtimeconfig"
+	"git.yeij.top/AskaEth/Cyrene_v2/plugins/tools/io/search"
+)
+
+// --- 四个动作 + 一个候选来源 -------------------------------------------------
+
+// listProviders 是表格区块的数据源：把可变源里的各条配置翻译成面板行
+// （provider / state / enabled；**凭据与地址都不进行数据**）。
+func (e webSearchActionEnv) listProviders(_ context.Context, _ pluginmgr.ActionRequest) (any, error) {
+	f, err := e.loadFile()
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"rows": providerRows(f)}, nil
+}
+
+// listProviderOptions 给出下拉候选：本期全部已登记的 provider 名（含尚未配置的家）。
+//
+// 给全部而不是「已配置的家」的理由见 search.ProviderOptions：表单的用途就是**新增**
+// 一家，只列已配置的会让第一次配置无从选起。
+func (e webSearchActionEnv) listProviderOptions(_ context.Context, _ pluginmgr.ActionRequest) (any, error) {
+	return map[string]any{"options": search.ProviderOptions()}, nil
+}
+
+// saveProvider 新增 / 修改一条 provider 配置（表单提交，写动作）。
+//
+// 三态写回（与前端 `schema/values.ts:planSubmit` 逐条同义）：
+//   - apiKey **缺位** ⇒ 保留原值（面板只持有掩码，「留空 = 不改」必须是真的）；
+//   - apiKey **空串** ⇒ 显式清空（前端只有勾了「清除」才会送出空串）；
+//   - baseUrl / enabled 缺位或空串 ⇒ 保留；给出（含 false / 空地址）⇒ 采用。
+//
+// 只接受**已登记**的名字：未登记的家存进去也永远不会被选中（注册表按名字取），
+// 那会让「我明明配了 tavily」变成一句假话 —— 所以在这里就拒。
+func (e webSearchActionEnv) saveProvider(_ context.Context, req pluginmgr.ActionRequest) (any, error) {
+	values, err := actionValuesObject(req.Payload)
+	if err != nil {
+		return nil, err
+	}
+	name, err := requiredProviderName(values)
+	if err != nil {
+		return nil, err
+	}
+	if err := requireKnownProvider(name); err != nil {
+		return nil, err
+	}
+	cur, err := e.loadFile()
+	if err != nil {
+		return nil, err
+	}
+	prev, existed := findProviderEntry(cur, name)
+	entry, err := mergeProviderEntry(prev, values)
+	if err != nil {
+		return nil, err
+	}
+	entry.Provider = name
+	if err := runtimeconfig.SaveWebSearch(e.path, runtimeconfig.UpsertProviderEntry(cur, entry)); err != nil {
+		e.log.Error("web-search panel config write failed", "path", e.path, "provider", name, "error", err)
+		return nil, pluginmgr.NewActionError(actionCodeConfigWriteFailed,
+			"面板配置写不进去（磁盘或权限问题），本次改动**没有**生效", http.StatusInternalServerError, err)
+	}
+	e.log.Info("web-search provider saved from panel",
+		"path", e.path, "provider", name, "created", !existed, "enabled", entry.IsEnabled())
+	return map[string]any{
+		"saved":    true,
+		"provider": name,
+		"created":  !existed,
+		"enabled":  entry.IsEnabled(),
+	}, nil
+}
+
+// testProvider 对一条配置**真发一次最小检索**（行内动作「测试连通」）。
+//
+// 凭据与地址都从可变源读（面板里刚存下的就是它），不从前端传上来的行数据读
+// —— 行数据里没有 key（列表列刻意不带凭据），也不该由客户端指定要探的目标。
+//
+// 失败一律回**结构化非 2xx**：面板的行内动作只在失败时显示文案（成功分支只说
+// 「已完成」），把「探不通」放进 200 的 data 里等于让界面报一句假成功。
+func (e webSearchActionEnv) testProvider(ctx context.Context, req pluginmgr.ActionRequest) (any, error) {
+	name, err := providerNameOf(req.Payload)
+	if err != nil {
+		return nil, err
+	}
+	if err := requireKnownProvider(name); err != nil {
+		return nil, err
+	}
+	f, err := e.loadFile()
+	if err != nil {
+		return nil, err
+	}
+	entry, _ := findProviderEntry(f, name)
+	base := e.effectiveBaseURL(name, entry)
+	target, err := newProbeTarget(base)
+	if err != nil {
+		// 地址不合法 / 为空 ⇒ 这条没配齐（探针自己也会这么判，但这里能给出更准的话）。
+		return nil, pluginmgr.NewActionError(search.ProbeNotConfigured,
+			"这条没配齐：接口地址为空或不是 http(s) 绝对地址", http.StatusBadRequest, err)
+	}
+	cfg := search.Config{
+		APIKey:   entry.APIKey,
+		BaseURL:  base,
+		Client:   target.client(e.probeTimeout(f)),
+		MaxBytes: webSearchProbeMaxBytes,
+		Guard:    target.guard,
+	}
+	res := search.Probe(ctx, name, cfg, 0)
+	if !res.OK {
+		e.log.Warn("web-search panel probe failed",
+			"provider", name, "code", res.ErrorCode, "latencyMs", res.LatencyMS)
+		return nil, pluginmgr.NewActionError(res.ErrorCode, res.Error, probeErrorStatus(res.ErrorCode), nil)
+	}
+	e.log.Info("web-search panel probe ok", "provider", name, "count", res.Count, "latencyMs", res.LatencyMS)
+	return res, nil
+}
+
+// reauthProvider 把一条配置**带回表单**（行内动作「重配凭据」，design/09 §5.2.1 示例的
+// reauth 语义）：返回 `{values:{...}}`，前端把它灌进唯一的 form 区块。
+//
+// 两处口径：
+//   - apiKey 回**掩码**（读侧无明文，§5.4.2）：前端对 secret 字段一律不回填输入框，
+//     只把它算作「盘上已有值」⇒ 留空 = 不改动、要清空必须显式勾选；
+//   - 其余字段回**盘上那条的原样**，不做默认值回填：回填代码默认地址会让一次
+//     「只改 key」的保存把默认地址固化进文件（面板显示的是「该条」，不是「生效值」）。
+func (e webSearchActionEnv) reauthProvider(_ context.Context, req pluginmgr.ActionRequest) (any, error) {
+	name, err := providerNameOf(req.Payload)
+	if err != nil {
+		return nil, err
+	}
+	if err := requireKnownProvider(name); err != nil {
+		return nil, err
+	}
+	f, err := e.loadFile()
+	if err != nil {
+		return nil, err
+	}
+	entry, exists := findProviderEntry(f, name)
+	values := map[string]any{
+		"provider": name,
+		"baseUrl":  entry.BaseURL,
+		"enabled":  !exists || entry.IsEnabled(),
+	}
+	if masked, ok := maskedProviderEntry(f, name); ok && strings.TrimSpace(masked.APIKey) != "" {
+		values["apiKey"] = masked.APIKey
+	}
+	return map[string]any{"values": values}, nil
+}
+
+// --- 可变源读写（含失败分类） -------------------------------------------------
+
+// loadFile 读可变源。
+//
+// 文件**缺失或为空** = 「还没配过」（启动期已由 `.env` 播种；极端情况下面板先于启动期
+// 被调用）⇒ 返回空文件，不是错误。
+// 文件**存在但不合法** ⇒ 结构化失败：绝不把损坏配置当成空配置 —— 那会让一次保存
+// 静默盖掉一份人工写坏但可救回的内容（与启动期的处置同向：回落但不覆盖）。
+func (e webSearchActionEnv) loadFile() (runtimeconfig.WebSearchFile, error) {
+	f, found, err := runtimeconfig.LoadWebSearch(e.path)
+	if err != nil {
+		e.log.Error("web-search panel config unreadable", "path", e.path, "error", err)
+		return runtimeconfig.WebSearchFile{}, pluginmgr.NewActionError(actionCodeConfigUnreadable,
+			"面板配置读不出来（文件损坏或权限不足），本次**没有**改动它；详见服务端日志",
+			http.StatusInternalServerError, err)
+	}
+	if !found {
+		return runtimeconfig.WebSearchFile{
+			Version:   runtimeconfig.WebSearchVersion,
+			Providers: []runtimeconfig.ProviderEntry{},
+		}, nil
+	}
+	return f, nil
+}
+
+// providerRows 把各条配置翻译成面板表格行（凭据与地址都不进行数据）。
+func providerRows(f runtimeconfig.WebSearchFile) []search.ProviderRow {
+	inputs := make([]search.ProviderInput, 0, len(f.Providers))
+	for _, p := range f.Providers {
+		inputs = append(inputs, search.ProviderInput{
+			Provider: p.Provider,
+			APIKey:   p.APIKey,
+			BaseURL:  p.BaseURL,
+			Enabled:  p.IsEnabled(),
+		})
+	}
+	return search.BuildRows(inputs)
+}
+
+// findProviderEntry 按名字取一条配置（大小写与首尾空白不敏感，与
+// UpsertProviderEntry 的匹配键同一口径）。
+func findProviderEntry(f runtimeconfig.WebSearchFile, name string) (runtimeconfig.ProviderEntry, bool) {
+	want := strings.ToLower(strings.TrimSpace(name))
+	for _, p := range f.Providers {
+		if strings.EqualFold(strings.TrimSpace(p.Provider), want) {
+			return p, true
+		}
+	}
+	return runtimeconfig.ProviderEntry{}, false
+}
+
+// maskedProviderEntry 取某条配置的**掩码副本**（复用 runtimeconfig 的唯一掩码出口，
+// 不在这里另写一份 maskToken）。
+func maskedProviderEntry(f runtimeconfig.WebSearchFile, name string) (runtimeconfig.ProviderEntry, bool) {
+	return findProviderEntry(runtimeconfig.MaskedWebSearchFile(f), name)
+}
+
+// effectiveBaseURL 给出一条配置**实际会用的**基地址：盘上有就用盘上的，没有就回落到
+// 代码默认值（各云家的厂商默认地址）。
+//
+// searxng 不回落（空地址 = 关掉这家，回落会让「清空地址」变成假话）—— 与
+// `effectiveSearchConfig` 的同一条权威边界。
+func (e webSearchActionEnv) effectiveBaseURL(name string, entry runtimeconfig.ProviderEntry) string {
+	if base := strings.TrimSpace(entry.BaseURL); base != "" {
+		return base
+	}
+	if strings.EqualFold(name, search.NameSearXNG) {
+		return ""
+	}
+	return e.defaultBaseURL(name)
+}
+
+// defaultBaseURL 取某家云 provider 的代码默认基地址（来自 `.env` 解析后的配置，未写该键
+// 时就是标签默认值）。名字表复用组合根既有那张（`searchProviderVector`），不新造一份。
+func (e webSearchActionEnv) defaultBaseURL(name string) string {
+	for _, p := range searchProviderVector(e.envCfg) {
+		if strings.EqualFold(p.Name, name) {
+			return strings.TrimSpace(p.BaseURL)
+		}
+	}
+	return ""
+}
+
+// probeTimeout 给出一次探针的超时上限：面板文件的 timeout 优先（面板里刚存的就是它），
+// 其次 `.env`/代码默认值，最后是包内兜底 —— 与工具运行时的裁决顺序一致。
+func (e webSearchActionEnv) probeTimeout(f runtimeconfig.WebSearchFile) time.Duration {
+	if d, err := f.TimeoutDuration(); err == nil && d > 0 {
+		return d
+	}
+	if e.envCfg.Timeout > 0 {
+		return e.envCfg.Timeout
+	}
+	return webSearchProbeTimeout
+}
+
+// --- 载荷解析（形状不对就报错，不静默当空） ------------------------------------
+
+// actionObject 取请求体的 JSON 对象。空体（nil）返回 (nil, nil)：少数动作不需要参数。
+func actionObject(payload any) (map[string]any, error) {
+	if payload == nil {
+		return nil, nil
+	}
+	obj, ok := payload.(map[string]any)
+	if !ok {
+		return nil, invalidPayloadActionError("请求体必须是一个 JSON 对象")
+	}
+	return obj, nil
+}
+
+// actionValuesObject 取 `{values:{...}}`（表单提交的形状，见前端 formState.useFormSubmit）。
+func actionValuesObject(payload any) (map[string]any, error) {
+	obj, err := actionObject(payload)
+	if err != nil {
+		return nil, err
+	}
+	if obj == nil {
+		return nil, invalidPayloadActionError("缺少 values 对象（表单提交的形状是 {values:{...}}）")
+	}
+	values, ok := obj["values"].(map[string]any)
+	if !ok {
+		return nil, invalidPayloadActionError("缺少 values 对象（表单提交的形状是 {values:{...}}）")
+	}
+	return values, nil
+}
+
+// providerNameOf 从载荷里取 provider 名（三种**显式**来源，不猜字段）：
+// 行内动作给 `{row:{provider}}`（前端 tableState），也可给 `{values:{provider}}`
+// （与表单同一形状），或顶层直接给 `provider`。
+func providerNameOf(payload any) (string, error) {
+	obj, err := actionObject(payload)
+	if err != nil {
+		return "", err
+	}
+	if obj == nil {
+		return "", invalidPayloadActionError("缺少 provider 名（行内动作给 row.provider）")
+	}
+	for _, key := range []string{"row", "values", "provider"} {
+		switch v := obj[key].(type) {
+		case string:
+			if key == "provider" && strings.TrimSpace(v) != "" {
+				return normalizeProviderName(v), nil
+			}
+		case map[string]any:
+			if name := actionString(v, "provider"); name != "" {
+				return normalizeProviderName(name), nil
+			}
+		}
+	}
+	return "", invalidPayloadActionError("缺少 provider 名（行内动作给 row.provider，表单给 values.provider）")
+}
+
+// requiredProviderName 取表单里的 provider 名（必填）。
+func requiredProviderName(values map[string]any) (string, error) {
+	name := actionString(values, "provider")
+	if name == "" {
+		return "", invalidPayloadActionError("provider 必填：请选择 / 填写要配置的提供商名")
+	}
+	return normalizeProviderName(name), nil
+}
+
+// requireKnownProvider 拒掉本期没登记的名字（存了也永远不会被选中；探它只会得到
+// 「未登记」）。错误码与文案与 search 的探针口径一致，前端可按同一个码本地化。
+func requireKnownProvider(name string) error {
+	if search.Known(name) {
+		return nil
+	}
+	return pluginmgr.NewActionError(actionCodeUnknownProvider,
+		fmt.Sprintf("未登记的搜索提供商 %q（本期接入位：%s）", name, strings.Join(search.KnownNames(), ", ")),
+		http.StatusBadRequest, nil)
+}
+
+// actionString 取一个字符串字段（去首尾空白；非字符串与空串都算「没给」）。
+func actionString(m map[string]any, key string) string {
+	s, ok := m[key].(string)
+	if !ok {
+		return ""
+	}
+	return strings.TrimSpace(s)
+}
+
+// normalizeProviderName 归一 provider 名（小写 + 去空白），与注册表/可变源的匹配键同口径。
+func normalizeProviderName(name string) string {
+	return strings.ToLower(strings.TrimSpace(name))
+}
+
+// mergeProviderEntry 把表单补丁合并进一条配置（三态写回，见 saveProvider 的注释）。
+// enabled 给了非布尔值时**显式报错**：静默保留会让「我关了它」变成假话。
+func mergeProviderEntry(prev runtimeconfig.ProviderEntry, values map[string]any) (runtimeconfig.ProviderEntry, error) {
+	out := prev
+	if v, ok := values["apiKey"]; ok {
+		key, err := actionOptionalString(v, "apiKey")
+		if err != nil {
+			return runtimeconfig.ProviderEntry{}, err
+		}
+		out.APIKey = key
+	}
+	if v, ok := values["baseUrl"]; ok {
+		base, err := actionOptionalString(v, "baseUrl")
+		if err != nil {
+			return runtimeconfig.ProviderEntry{}, err
+		}
+		out.BaseURL = base
+	}
+	on, set, err := actionOptionalBool(values["enabled"], "enabled")
+	if err != nil {
+		return runtimeconfig.ProviderEntry{}, err
+	}
+	if set {
+		out.Enabled = runtimeconfig.EnableFlag(on)
+	}
+	return out, nil
+}
+
+// actionOptionalString 校验一个可选字符串字段：缺位 ⇒ 空串（调用方按「未给」处理）；
+// 非字符串 ⇒ 报错（把类型错静默当成空串 = 一次保存悄悄清空了某个字段）。
+func actionOptionalString(v any, key string) (string, error) {
+	if v == nil {
+		return "", nil
+	}
+	s, ok := v.(string)
+	if !ok {
+		return "", invalidPayloadActionError(fmt.Sprintf("%s 必须是字符串", key))
+	}
+	return strings.TrimSpace(s), nil
+}
+
+// actionOptionalBool 解析可选开关：缺位 / nil / 空串 ⇒ 未改动；bool ⇒ 采用；
+// 其它类型 ⇒ 报错（理由同 actionOptionalString）。
+func actionOptionalBool(v any, key string) (value bool, set bool, err error) {
+	switch raw := v.(type) {
+	case nil:
+		return false, false, nil
+	case bool:
+		return raw, true, nil
+	case string:
+		if strings.TrimSpace(raw) == "" {
+			return false, false, nil
+		}
+		return false, false, invalidPayloadActionError(fmt.Sprintf("%s 必须是布尔值", key))
+	default:
+		return false, false, invalidPayloadActionError(fmt.Sprintf("%s 必须是布尔值", key))
+	}
+}
+
+// invalidPayloadActionError 造一个 400 invalid_payload（形状错 = 调用方错，不是上游错）。
+func invalidPayloadActionError(message string) error {
+	return pluginmgr.NewActionError(pluginmgr.ActionCodeInvalidPayload, message, http.StatusBadRequest, nil)
+}
@@ -0,0 +1,88 @@
+package main
+
+// 本文件钉住搜索提供商动作面的**危险/边界结局**（切片 L1/PLG-2）：损坏配置不许被覆盖、
+// 装配期要如实点名「声明了却没实现」的动作。它们与主用例集分开成文件的理由只有一条：
+// `wire_plugin_actions_test.go` 已接近「文件 ≤500 行」的上限（AGENTS §10）。
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/bus"
+	pluginmgr "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/plugin"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/capability/registry"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
+	"git.yeij.top/AskaEth/Cyrene_v2/pkg/plugins/sdk"
+	"git.yeij.top/AskaEth/Cyrene_v2/plugins/tools/io/search"
+)
+
+// TestWebSearchActionConfigUnreadableIsReported 锁定「文件存在但不合法」的口径：
+// 结构化失败（500 config_unreadable），**不覆盖**原文件 —— 损坏的配置可以人工救回。
+func TestWebSearchActionConfigUnreadableIsReported(t *testing.T) {
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+	const broken = `{"version":1,"providers":[{"provider":"bocha"},{"provider":"BOCHA"}]}`
+	wsWriteRawPanel(t, env.path, broken)
+
+	_, err := env.dispatch(t, search.ActionListProviders, map[string]any{})
+	ae, ok := pluginmgr.AsActionError(err)
+	if !ok || ae.Code != actionCodeConfigUnreadable || ae.Status != http.StatusInternalServerError {
+		t.Fatalf("err = %#v, want 500 config_unreadable", err)
+	}
+	if _, err := env.dispatch(t, search.ActionSaveProvider, map[string]any{
+		"values": map[string]any{"provider": search.NameBocha, "apiKey": "sk-x"},
+	}); err == nil {
+		t.Fatal("配置不合法时必须拒绝保存（否则会静默盖掉可救回的原文件）")
+	}
+	raw, rerr := os.ReadFile(env.path)
+	if rerr != nil {
+		t.Fatalf("read: %v", rerr)
+	}
+	if string(raw) != broken {
+		t.Fatalf("原文件被改动了：%q", raw)
+	}
+}
+
+// TestWarnImpliedButMissingNamesGaps 锁定装配期的**核对**：声明里有、登记里没有的动作
+// 必须在日志里点名（否则用户只会看到一个点了回 501 的按钮）。这里直接覆盖核对函数本身。
+func TestWarnImpliedButMissingNamesGaps(t *testing.T) {
+	cfg := wsLoadConfig(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+	b := bus.New()
+	defer b.Close()
+	mgr := pluginmgr.NewManager(registry.New(), filepath.Join(cfg.DataDir, "plugins.json"), testLog())
+	defer mgr.Close(context.Background())
+
+	var buf bytes.Buffer
+	log := logger.New(logger.Options{Out: &buf, Level: "debug"})
+	wirePanelHub(&app{cfg: cfg, log: log, bus: b, plugins: mgr})
+	hub := mgr.Panels()
+
+	// 模拟「插件声明新增了一个动作，但宿主忘了给它接线」：补一条声明（Declare 是整体
+	// 替换语义 ⇒ 原有四个动作 + 候选来源仍在），只多一个没人实现的名字。
+	extra := sdk.Panel{
+		ID: "extra", Title: "额外页",
+		Sections: []sdk.Section{{
+			Type: sdk.SectionTable, ID: "t", Title: "额外表",
+			Source:  &sdk.Source{Action: "plugin.notWired"},
+			Columns: []sdk.Column{{Key: "k", Label: "K"}},
+		}},
+	}
+	if _, err := hub.Declare(search.PanelPluginID, append(search.AdminPanels(), extra)); err != nil {
+		t.Fatalf("Declare: %v", err)
+	}
+	warnImpliedButMissing(hub, log)
+
+	out := buf.String()
+	if !strings.Contains(out, "plugin.notWired") || !strings.Contains(out, "no handler") {
+		t.Fatalf("声明了却没实现的动作必须被点名（否则只剩一个回 501 的按钮）: %q", out)
+	}
+	// 已登记的动作不得被误报。
+	if idx := strings.Index(out, "action=plugin.listProviders"); idx >= 0 &&
+		strings.Contains(out[idx:], "no handler") {
+		t.Fatalf("已登记的动作被误报成缺处理器: %q", out)
+	}
+}
@@ -0,0 +1,117 @@
+package main
+
+// 本文件是「搜索提供商」页**探针**的传输层绑定（切片 L1/PLG-2 的执行面接线的一部分）：
+// 探针要用的 HTTP 客户端、目标约束（同主机守卫）与失败状态映射。
+// 动作本体的语义在 `websearch_action_data.go`，登记面在 `wire_plugin_actions.go`。
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/plugins/tools/io/search"
+)
+
+// 探针的边界值。名字化的理由与 io 包同一套：不许裸魔法数字（项目规范 §10）。
+const (
+	// webSearchProbeTimeout 是探针的兜底超时（面板文件与 `.env` 都没声明时用它）——
+	// 取 io 工具集的默认 http 超时同值（15s），免得「面板测通了、工具超时」这种怪象。
+	webSearchProbeTimeout = 15 * time.Second
+	// webSearchProbeMaxBytes 是探针响应体的读取上限（与 io 包的 http 响应上限同口径 1 MiB）。
+	webSearchProbeMaxBytes = 1 << 20
+	// webSearchProbeMaxRedirects 是探针允许的跳转次数（与 io 的 maxRedirects 同值）。
+	webSearchProbeMaxRedirects = 3
+)
+
+// probeErrorStatus 按探针码给出 HTTP 状态：调用方/配置问题 ⇒ 400；上游或网络 ⇒ 502。
+//
+// 它**不**改变探针的语义（no_results 仍然是 no_results，不是「成功」也不是「该家不可用」），
+// 只是给前端一个非 2xx 的信号，好让面板把结论显示出来（见 testProvider 的注释）。
+func probeErrorStatus(code string) int {
+	switch code {
+	case search.ProbeUnknownProvider, search.ProbeNotConfigured:
+		return http.StatusBadRequest
+	default:
+		return http.StatusBadGateway
+	}
+}
+
+// probeTarget 是一次探针的目标约束：**只允许打到配置里那台主机**。
+//
+// 与 io 包 SSRF 守卫的关系（写清楚，免得被当成第二份安全策略）：地址来自面板里存下的
+// provider 基地址 —— 它是**运维输入**（owner 通过 owner/admin 写动作落下的），不是模型
+// 输入。io 的守卫用「私网/回环黑名单 + 允许清单」，而那个守卫在 `plugins/tools/io`
+// 内部未导出，本片**不改他人文件**（硬边界），因此这里用一条**更严**的规则替代：
+// 探针只与配置主机通话，跨主机（含跨主机重定向）一律拒绝。
+// 缺口如实登记：两处策略不逐字同源（见报告 §未做）。
+type probeTarget struct {
+	// host 是配置主机名（小写、无端口）。
+	host string
+}
+
+// newProbeTarget 解析出配置主机；地址为空 / 非 http(s) / 没有主机名时返回错误。
+func newProbeTarget(baseURL string) (probeTarget, error) {
+	raw := strings.TrimSpace(baseURL)
+	if raw == "" {
+		return probeTarget{}, fmt.Errorf("web-search probe: empty base url")
+	}
+	u, err := url.Parse(raw)
+	if err != nil {
+		return probeTarget{}, fmt.Errorf("web-search probe: parse base url: %w", err)
+	}
+	if !isHTTPURL(u) {
+		return probeTarget{}, fmt.Errorf("web-search probe: unsupported scheme %q", u.Scheme)
+	}
+	host := strings.ToLower(u.Hostname())
+	if host == "" {
+		return probeTarget{}, fmt.Errorf("web-search probe: base url has no host")
+	}
+	return probeTarget{host: host}, nil
+}
+
+// client 造这次探针要用的 HTTP 客户端：超时上限 + 同主机的跳转策略。
+// 它是**每次调用新建**的（探针很少发生，不值得为它维护一份共享客户端与连接池）；
+// 也因此不牵动 http / web-fetch / web-search 共用的那份客户端与白名单。
+func (t probeTarget) client(timeout time.Duration) *http.Client {
+	return &http.Client{Timeout: timeout, CheckRedirect: t.checkRedirect}
+}
+
+// guard 是注入给 search.Config 的地址判定（发请求前对最终地址做一次判定）。
+func (t probeTarget) guard(_ context.Context, rawURL string) error { return t.check(rawURL) }
+
+// checkRedirect 是跳转策略：次数上限 + 每一跳都要过同一条判定。
+func (t probeTarget) checkRedirect(req *http.Request, via []*http.Request) error {
+	if len(via) >= webSearchProbeMaxRedirects {
+		return fmt.Errorf("web-search probe: too many redirects")
+	}
+	if req.URL == nil {
+		return fmt.Errorf("web-search probe: nil redirect target")
+	}
+	return t.check(req.URL.String())
+}
+
+// check 判定一个地址能否访问：必须是 http(s) 且主机等于配置主机。
+func (t probeTarget) check(rawURL string) error {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return fmt.Errorf("web-search probe: parse target: %w", err)
+	}
+	if !isHTTPURL(u) {
+		return fmt.Errorf("web-search probe: unsupported scheme %q", u.Scheme)
+	}
+	if !strings.EqualFold(u.Hostname(), t.host) {
+		return fmt.Errorf("web-search probe: refused cross-host target %q", u.Hostname())
+	}
+	return nil
+}
+
+// isHTTPURL 报告地址是否是可访问的 http(s) 绝对地址。
+func isHTTPURL(u *url.URL) bool {
+	if u == nil {
+		return false
+	}
+	return u.Scheme == "http" || u.Scheme == "https"
+}
@@ -69,24 +69,24 @@ func (a *app) wireFrontend() error {
 		tidyDryRunner = a.memoryTidy
 	}
 	gw, err := gateway.New(a.cfg, gateway.Deps{
-		Log:            logger.WithSource(a.log, "gateway"),
-		Auth:           jwt,
-		Bus:            a.bus,
-		Registry:       a.caps,
-		Loop:           a.loop,
-		Session:        a.sessions,
-		Personas:       a.personas,
-		Memories:       a.memStore,
-		History:        a.history,
-		IoT:            a.iot,
-		Scheduler:      a.scheduler,
-		Tasks:          a.tasks,
-		Automations:    a.automation,
-		Users:          apiKeys,
-		Refresh:        refreshStore,
-		Backthink:      a.backthink,
-		RAG:            ragStore,
-		LLM:            a.llm,
+		Log:         logger.WithSource(a.log, "gateway"),
+		Auth:        jwt,
+		Bus:         a.bus,
+		Registry:    a.caps,
+		Loop:        a.loop,
+		Session:     a.sessions,
+		Personas:    a.personas,
+		Memories:    a.memStore,
+		History:     a.history,
+		IoT:         a.iot,
+		Scheduler:   a.scheduler,
+		Tasks:       a.tasks,
+		Automations: a.automation,
+		Users:       apiKeys,
+		Refresh:     refreshStore,
+		Backthink:   a.backthink,
+		RAG:         ragStore,
+		LLM:         a.llm,
 		// EnvPath 与 main.go 启动时 config.Load(envPath) 用同一条路径：面板
 		// 「重置为 env 默认」（切片 R1）按既有解析入口重读同一份 `.env` 声明，
 		// 网关自己不 fopen `.env`。
@@ -164,7 +164,9 @@ func (a *app) wireFrontend() error {
 }

 // wirePanelHub 给已构造的插件管理器接上面板声明中枢，并把它接到既有进程内 bus 的
-// `ws.panels_changed` 上（design/09 §5.2.1；切片 PLG-2）。
+// `ws.panels_changed` 上（design/09 §5.2.1；切片 PLG-2）。之后再把内置插件的**动作
+// 处理器**登记到管理器上（切片 L1/PLG-2 的执行面接线）：没有这一步，面板的每个动作都
+// 只能诚实回 501（声明在、没人执行）。
 //
 // 三条约束都在这里落地：
 //   - **不新开端口**：热更新信号只走进程内 bus（hub 订阅 ws.> ⇒ 帧类型 panels_changed），
@@ -177,7 +179,8 @@ func wirePanelHub(a *app) {
 	if a.plugins == nil {
 		return
 	}
-	hub, err := pluginmgr.NewPanels(logger.WithSource(a.log, "capability/plugin/panels"))
+	log := logger.WithSource(a.log, "capability/plugin/panels")
+	hub, err := pluginmgr.NewPanels(log)
 	if err != nil {
 		a.log.Warn("panel hub unavailable, plugin panel endpoints will answer 501", "error", err)
 		return
@@ -194,7 +197,12 @@ func wirePanelHub(a *app) {
 		}
 	})
 	a.plugins.AttachPanels(hub)
-	declareBuiltinPanels(hub, logger.WithSource(a.log, "capability/plugin/panels"))
+	declareBuiltinPanels(hub, log)
+	// 登记动作处理器必须在**声明之后**：登记期会核对「登记的处理器有没有对应声明」，
+	// 顺序反过来只会得到一串「声明还没到」的 WARN。
+	// 日志来源另标一处（动作接线 ≠ 面板中枢）：`source=cmd/cyrene/wire_plugin_actions`
+	// 让「谁登记了哪些动作 / 哪些声明没人实现」能在日志里独立定位。
+	wireBuiltinPluginActions(a.plugins, hub, a, logger.WithSource(a.log, actionWireLogSource))
 }

 // declareBuiltinPanels 把**编译进二进制的内置插件**的面板声明交给中枢
@@ -0,0 +1,188 @@
+package main
+
+// 本文件是**内置插件动作面的登记入口**（design/09 §5.2.1「动作分发」；切片 L1/PLG-2 的
+// 执行面接线）：把编译进二进制的插件声明的动作处理器登记到插件管理器上。首个使用者是
+// web-search 的「搜索提供商」页（§5.5 dogfood）：四个动作
+// plugin.listProviders / plugin.saveProvider / plugin.testProvider / plugin.reauthProvider,
+// 外加下拉候选来源 `plugin:providers`（前端按 `optionsFrom` 推出这个名字）。
+//
+// 三个文件的分工（都在本包）：
+//   - 本文件：登记入口、处理器环境、动作名映射、「声明了却没实现」的装配期核对；
+//   - `websearch_action_data.go`：五个动作的业务数据面（可变源的读写与翻译、载荷解析）；
+//   - `websearch_probe.go`：探针的传输层绑定（HTTP 客户端 + 同主机守卫 + 状态映射）。
+//
+// 三条边界：
+//
+//  1. **数据面只读写可变源**：`$DATA_DIR/config/plugins/web-search.json`（design/13 §2.1），
+//     经 runtimeconfig 的读写入口（0600 + temp+rename），宿主自己不开新路径、不猜形状；
+//  2. **探针真发一次请求**：走 `search.Probe`（同一家 provider 构造、同一份归一化），
+//     不靠「配置看起来齐了」假装连通（§5.5 的「测试连通」）；
+//  3. **凭据不出后端**：读侧只回掩码（`MaskedWebSearchFile`），日志只记 provider 名与
+//     结果码，绝不记 key / 地址。
+//
+// 本片不做的事（如实登记，见报告 §未做）：不热替换**运行中**的 web-search 工具 ——
+// 面板保存后工具仍用启动期解析出的 provider 接线，改动在下次重启生效。
+
+import (
+	"log/slog"
+	"sort"
+	"strings"
+
+	pluginmgr "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/plugin"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config/runtimeconfig"
+	"git.yeij.top/AskaEth/Cyrene_v2/pkg/plugins/sdk"
+	"git.yeij.top/AskaEth/Cyrene_v2/plugins/tools/io/search"
+)
+
+// actionWireLogSource 是本文件日志的来源标签（项目规范 §10：禁止无来源裸日志）。
+const actionWireLogSource = "cmd/cyrene/wire_plugin_actions"
+
+// 动作失败码（宿主级，且只在动作面这组文件里使用）。领域自己的码来自 search（探针码）
+// 与 pluginmgr.ActionCodeInvalidPayload。
+const (
+	// actionCodeUnknownProvider 报告请求点名了一家本期没登记的 provider。
+	actionCodeUnknownProvider = "unknown_provider"
+	// actionCodeConfigUnreadable 报告面板配置存在但读不出来（损坏/权限）。
+	actionCodeConfigUnreadable = "config_unreadable"
+	// actionCodeConfigWriteFailed 报告面板配置写不进去（磁盘/权限）。
+	actionCodeConfigWriteFailed = "config_write_failed"
+)
+
+// wireBuiltinPluginActions 把内置插件的动作处理器登记到插件管理器上（§5.2.1：
+// 插件在组合根注册自己的动作处理器）。
+//
+// 登记之后旧账要结清：**声明里写了但没人实现**的动作会如实记一条 WARN（端点对它的
+// 结算就是 501）。这正是 §5.2.1「表里写了一个没实现的动作，review 时一眼可见」的
+// 运行期版本 —— 装配期就把差异说出来，而不是等用户点出一个 501。
+//
+// 登记失败（命名空间非法 / 中枢未接线）只记 ERROR、不阻断启动：一个坏的动作面不该
+// 让整个后端起不来（与面板声明的处置一致：该面板不注册 + 显式报错）。
+func wireBuiltinPluginActions(mgr *pluginmgr.Manager, hub *pluginmgr.Panels, a *app, log *slog.Logger) {
+	if mgr == nil || hub == nil {
+		return
+	}
+	env, ok := a.webSearchActionEnv(log)
+	if !ok {
+		log.Warn("builtin plugin actions not registered: no config/data dir",
+			"pluginId", search.PanelPluginID, "effect", "panel actions will answer 501")
+		return
+	}
+	handlers := webSearchActionHandlers(env)
+	for optionsFrom, handler := range webSearchOptionsHandlers(env) {
+		name := pluginmgr.OptionsActionName(optionsFrom)
+		if name == "" {
+			log.Error("optionsFrom 无法映射成动作名，候选来源未接线",
+				"pluginId", search.PanelPluginID, "optionsFrom", optionsFrom)
+			continue
+		}
+		handlers[name] = handler
+	}
+	if err := mgr.RegisterActions(search.PanelPluginID, handlers); err != nil {
+		log.Error("builtin plugin actions not registered; panel actions will answer 501",
+			"pluginId", search.PanelPluginID, "error", err)
+		return
+	}
+	log.Info("builtin plugin actions registered",
+		"pluginId", search.PanelPluginID, "actions", registeredActionNames(hub))
+	warnImpliedButMissing(hub, log)
+}
+
+// warnImpliedButMissing 把「声明里有、登记里没有」的动作与候选来源如实报出来
+// （前者的结算就是 501 action_not_implemented；后者会让前端静默降级成文本框）。
+func warnImpliedButMissing(hub *pluginmgr.Panels, log *slog.Logger) {
+	registered := make(map[string]bool)
+	for _, name := range hub.ActionHandlerNames(search.PanelPluginID) {
+		registered[name] = true
+	}
+	for _, name := range hub.DeclaredActions(search.PanelPluginID) {
+		if !registered[name] {
+			log.Warn("declared plugin action has no handler; it will answer 501",
+				"pluginId", search.PanelPluginID, "action", name)
+		}
+	}
+	for _, src := range declaredOptionsSources(search.AdminPanels()) {
+		name := pluginmgr.OptionsActionName(src)
+		if name == "" || !registered[name] {
+			log.Warn("declared optionsFrom has no handler; the control degrades to a text input",
+				"pluginId", search.PanelPluginID, "optionsFrom", src, "action", name)
+		}
+	}
+}
+
+// registeredActionNames 返回已登记的处理器的动作名（诊断日志用，已排序）。
+func registeredActionNames(hub *pluginmgr.Panels) []string {
+	names := hub.ActionHandlerNames(search.PanelPluginID)
+	sort.Strings(names)
+	return names
+}
+
+// declaredOptionsSources 从声明里收集全部 `optionsFrom` 取值（去重、排序）。
+//
+// 用途是**反向核对**：声明里出现了一个没有实现的候选来源时，装配期就要说出来 ——
+// 否则前端只会静默降级成文本框，没人知道是「声明多写了一个」。
+func declaredOptionsSources(panels []sdk.Panel) []string {
+	seen := make(map[string]bool)
+	for _, panel := range panels {
+		for _, s := range panel.Sections {
+			for _, f := range s.Fields {
+				if key := strings.TrimSpace(f.OptionsFrom); key != "" {
+					seen[key] = true
+				}
+			}
+		}
+	}
+	out := make([]string, 0, len(seen))
+	for key := range seen {
+		out = append(out, key)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// webSearchActionEnv 是 web-search 动作处理器共享的接线事实（一次装配、多动作复用）。
+//
+// 刻意只装**在多个动作间共享**的东西（日志出口、可变源路径、`.env` 解析后的配置），
+// 每次调用各自读文件：动作之间不共享「当前配置」这份可变状态，就不会出现
+// 「A 动作读到的是 B 动作刚改之前的那份」。
+type webSearchActionEnv struct {
+	log *slog.Logger
+	// path 是可变源落点 `$DATA_DIR/config/plugins/web-search.json`。
+	path string
+	// envCfg 是 `.env` 解析结果（**只用来取代码默认值**：各云家的默认基地址与超时）。
+	// 把面板没写的字段落回代码默认值，与工具运行时的 `orDefault` 口径一致。
+	envCfg config.WebSearchConfig
+}
+
+// webSearchActionEnv 构造处理器环境。ok=false 表示没有配置/数据目录
+// （未装配完成或测试夹具），此时不登记动作，由调用方如实告警。
+func (a *app) webSearchActionEnv(log *slog.Logger) (webSearchActionEnv, bool) {
+	if a.cfg == nil {
+		return webSearchActionEnv{}, false
+	}
+	return webSearchActionEnv{
+		log:    log,
+		path:   runtimeconfig.WebSearchConfigPath(resolveDataDir(a.cfg)),
+		envCfg: a.cfg.WebSearch,
+	}, true
+}
+
+// webSearchActionHandlers 返回 web-search 插件声明的**四个动作**的处理器。
+func webSearchActionHandlers(env webSearchActionEnv) map[string]pluginmgr.ActionHandler {
+	return map[string]pluginmgr.ActionHandler{
+		search.ActionListProviders:  env.listProviders,
+		search.ActionSaveProvider:   env.saveProvider,
+		search.ActionTestProvider:   env.testProvider,
+		search.ActionReauthProvider: env.reauthProvider,
+	}
+}
+
+// webSearchOptionsHandlers 返回「下拉候选来源」的处理器（键 = 声明里的 `optionsFrom` 取值）。
+//
+// 映射成什么动作名由 `pluginmgr.OptionsActionName` 一处决定（与前端
+// `resolveOptionsAction` 同源）：两处若分叉，声明的下拉就会去调一个宿主不认识的名字。
+func webSearchOptionsHandlers(env webSearchActionEnv) map[string]pluginmgr.ActionHandler {
+	return map[string]pluginmgr.ActionHandler{
+		"plugin:providers": env.listProviderOptions,
+	}
+}
@@ -0,0 +1,448 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/bus"
+	pluginmgr "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/plugin"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/capability/registry"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config/runtimeconfig"
+	"git.yeij.top/AskaEth/Cyrene_v2/plugins/tools/io/search"
+)
+
+// 本文件钉住切片 L1/PLG-2 的**执行面接线**：内置插件 web-search 的四个动作 +
+// 下拉候选来源真的被登记到插件管理器上，并且真的能读写可变源、真发一次探针请求。
+//
+// 为什么在组合根测：处理器与可变源的**接线事实**（哪个文件、哪份默认值、哪个客户端）
+// 只在这里成立；插件管理器的单测只能证明「登记面会路由」，证明不了「搜索页点得动」。
+
+// actionTestEnv 是一个接好面板中枢 + 动作处理器的组合根夹具。
+type actionTestEnv struct {
+	app *app
+	mgr *pluginmgr.Manager
+	hub *pluginmgr.Panels
+	// path 是可变源落点（$DATA_DIR/config/plugins/web-search.json）。
+	path string
+}
+
+// newActionTestEnv 按组合根的**同一条路**接线：wirePanelHub（声明 + 动作处理器登记）。
+// extra 是额外的 .env 行，用来控制代码默认值（如 WEB_SEARCH_PROVIDER）。
+func newActionTestEnv(t *testing.T, extra ...string) *actionTestEnv {
+	t.Helper()
+	cfg := wsLoadConfig(t, extra...)
+	b := bus.New()
+	t.Cleanup(func() { _ = b.Close() })
+	mgr := pluginmgr.NewManager(registry.New(), filepath.Join(cfg.DataDir, "plugins.json"), testLog())
+	t.Cleanup(func() { mgr.Close(context.Background()) })
+
+	a := &app{cfg: cfg, log: testLog(), bus: b, plugins: mgr}
+	wirePanelHub(a)
+	hub := mgr.Panels()
+	if hub == nil {
+		t.Fatal("wirePanelHub 未把面板中枢接到插件管理器上")
+	}
+	return &actionTestEnv{app: a, mgr: mgr, hub: hub, path: runtimeconfig.WebSearchConfigPath(cfg.DataDir)}
+}
+
+// dispatch 调一次动作（走生产同一条 Dispatch：声明 → 启用 → 处理器）。
+func (e *actionTestEnv) dispatch(t *testing.T, action string, payload any) (any, error) {
+	t.Helper()
+	return e.hub.Dispatch(context.Background(), pluginmgr.ActionRequest{
+		PluginID: search.PanelPluginID,
+		Action:   action,
+		Payload:  payload,
+	})
+}
+
+// mustDispatch 调一次动作并要求成功。
+func (e *actionTestEnv) mustDispatch(t *testing.T, action string, payload any) any {
+	t.Helper()
+	out, err := e.dispatch(t, action, payload)
+	if err != nil {
+		t.Fatalf("dispatch %s: %v", action, err)
+	}
+	return out
+}
+
+// saveProvider 走保存动作（表单形状 `{values:{...}}`）。
+func (e *actionTestEnv) saveProvider(t *testing.T, values map[string]any) any {
+	t.Helper()
+	return e.mustDispatch(t, search.ActionSaveProvider, map[string]any{"values": values})
+}
+
+// rowsOf 把列表动作的结果解成面板行。
+func (e *actionTestEnv) rowsOf(t *testing.T) []search.ProviderRow {
+	t.Helper()
+	out := e.mustDispatch(t, search.ActionListProviders, map[string]any{})
+	m, ok := out.(map[string]any)
+	if !ok {
+		t.Fatalf("列表结果类型 = %T", out)
+	}
+	rows, ok := m["rows"].([]search.ProviderRow)
+	if !ok {
+		t.Fatalf("列表结果缺 rows: %#v", m)
+	}
+	return rows
+}
+
+// rowOf 取某一家在表格里的那一行（找不到则失败）。
+func (e *actionTestEnv) rowOf(t *testing.T, provider string) search.ProviderRow {
+	t.Helper()
+	for _, r := range e.rowsOf(t) {
+		if r.Provider == provider {
+			return r
+		}
+	}
+	t.Fatalf("表格里没有 %q 这一行（rows = %+v）", provider, e.rowsOf(t))
+	return search.ProviderRow{}
+}
+
+// loadFile 读盘上的可变源（断言「真的落盘了」时用）。
+func (e *actionTestEnv) loadFile(t *testing.T) runtimeconfig.WebSearchFile {
+	t.Helper()
+	f, found, err := runtimeconfig.LoadWebSearch(e.path)
+	if err != nil {
+		t.Fatalf("LoadWebSearch(%s): %v", e.path, err)
+	}
+	if !found {
+		t.Fatalf("可变源不在盘上: %s", e.path)
+	}
+	return f
+}
+
+// entryOf 取盘上某家的条目。
+func (e *actionTestEnv) entryOf(t *testing.T, provider string) runtimeconfig.ProviderEntry {
+	t.Helper()
+	for _, p := range e.loadFile(t).Providers {
+		if p.Provider == provider {
+			return p
+		}
+	}
+	t.Fatalf("盘上没有 %q 条目", provider)
+	return runtimeconfig.ProviderEntry{}
+}
+
+// TestWirePanelHubRegistersBuiltinActions 是接线的主判据：内置插件的四个动作与
+// 下拉候选来源都进了登记面，且每一个都能真的被 Dispatch 执行（不再回 501）。
+func TestWirePanelHubRegistersBuiltinActions(t *testing.T) {
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+
+	want := append([]string(nil), search.ActionNames()...)
+	want = append(want, pluginmgr.OptionsActionName("plugin:providers"))
+	registered := env.hub.ActionHandlerNames(search.PanelPluginID)
+	sort.Strings(want)
+	if strings.Join(registered, ",") != strings.Join(want, ",") {
+		t.Fatalf("已登记的处理器 = %v, want %v", registered, want)
+	}
+	// 每个已登记的动作都必须**已声明**（否则登记它等于登记一个永远调不到的名字）。
+	for _, name := range registered {
+		if _, ok := env.hub.Action(search.PanelPluginID, name); !ok {
+			t.Errorf("动作 %q 已登记但没声明（永远不可达）", name)
+		}
+	}
+	// 声明里的每一个动作都必须有处理器 —— 否则面板上会有一个点了回 501 的按钮。
+	for _, name := range env.hub.DeclaredActions(search.PanelPluginID) {
+		if _, err := env.dispatch(t, name, nil); errors.Is(err, pluginmgr.ErrActionUnavailable) {
+			t.Errorf("声明过的动作 %q 没有处理器（会回 501）", name)
+		}
+	}
+	// 列表动作也必须真的执行（此时可变源还没配过 ⇒ 空表不是错误）。
+	if rows := env.rowsOf(t); len(rows) != 0 {
+		t.Fatalf("没配过任何一家时列表应为空，实际 %+v", rows)
+	}
+}
+
+// TestWebSearchListProvidersShowsStoredEntries 锁定列表动作读的是**可变源**
+// （而不是种子/默认值）：写进盘里的条目与状态都如实出现，且不含任何凭据。
+func TestWebSearchListProvidersShowsStoredEntries(t *testing.T) {
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+	env.saveProvider(t, map[string]any{
+		"provider": search.NameBocha, "apiKey": "sk-bocha-secret",
+		"baseUrl": "https://api.bocha.cn", "enabled": true,
+	})
+
+	rows := env.rowsOf(t)
+	byName := make(map[string]search.ProviderRow, len(rows))
+	for _, r := range rows {
+		byName[r.Provider] = r
+	}
+	if got := byName[search.NameBocha]; got.State != search.StateOK || !got.Enabled {
+		t.Fatalf("bocha 行 = %+v, want state=ok 且启用", got)
+	}
+	raw, err := json.Marshal(rows)
+	if err != nil {
+		t.Fatalf("marshal rows: %v", err)
+	}
+	if strings.Contains(string(raw), "sk-bocha-secret") {
+		t.Fatalf("列表动作泄漏了凭据: %s", raw)
+	}
+}
+
+// TestWebSearchSaveProviderHonoursSecretSentinel 锁定写侧的三态哨兵语义
+// （§5.4.2：空字符串 ≠ 不改动）：
+//   - apiKey 缺位 ⇒ 原值保留（面板只持有掩码，留空必须真的不改）；
+//   - apiKey 显式空串 ⇒ 清空；
+//   - enabled / baseUrl 缺位 ⇒ 保留。
+func TestWebSearchSaveProviderHonoursSecretSentinel(t *testing.T) {
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+	env.saveProvider(t, map[string]any{
+		"provider": search.NameBocha, "apiKey": "sk-first",
+		"baseUrl": "https://api.bocha.cn", "enabled": true,
+	})
+
+	// 只改地址（apiKey / enabled 缺位）⇒ 凭据与启用态一个都不许动。
+	env.saveProvider(t, map[string]any{"provider": search.NameBocha, "baseUrl": "https://mirror.bocha.cn"})
+	got := env.entryOf(t, search.NameBocha)
+	if got.APIKey != "sk-first" {
+		t.Fatalf("apiKey 缺位时被改动了: %q（哨兵语义失效 = 一次保存静默清空凭据）", got.APIKey)
+	}
+	if got.BaseURL != "https://mirror.bocha.cn" || !got.IsEnabled() {
+		t.Fatalf("条目 = %+v, want 新地址 + 仍启用", got)
+	}
+
+	// 显式停用 + 显式清空凭据（前端只有勾了清除才会送出空串）。
+	env.saveProvider(t, map[string]any{"provider": search.NameBocha, "apiKey": "", "enabled": false})
+	got = env.entryOf(t, search.NameBocha)
+	if got.APIKey != "" {
+		t.Fatalf("显式空串必须清空凭据，得到 %q", got.APIKey)
+	}
+	if got.IsEnabled() {
+		t.Fatal("显式 enabled=false 必须落盘（停用态）")
+	}
+	if state := env.rowOf(t, search.NameBocha).State; state != search.StateDisabled {
+		t.Fatalf("停用后 state = %q, want %q", state, search.StateDisabled)
+	}
+}
+
+// TestWebSearchReauthProviderReturnsMaskedValues 锁定 reauth「把该条带回表单」：
+// 返回显式 values（前端 formValuesOfResult 只认 values/formValues），
+// 且 apiKey 只给**掩码** —— 读侧永不回明文（§5.4.2）。
+func TestWebSearchReauthProviderReturnsMaskedValues(t *testing.T) {
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+	env.saveProvider(t, map[string]any{
+		"provider": search.NameBocha, "apiKey": "sk-abcdefgh",
+		"baseUrl": "https://api.bocha.cn", "enabled": true,
+	})
+
+	out := env.mustDispatch(t, search.ActionReauthProvider, map[string]any{
+		"row": map[string]any{"provider": search.NameBocha, "state": search.StateOK},
+	})
+	m, ok := out.(map[string]any)
+	if !ok {
+		t.Fatalf("reauth 结果类型 = %T", out)
+	}
+	values, ok := m["values"].(map[string]any)
+	if !ok {
+		t.Fatalf("reauth 结果缺 values: %#v", m)
+	}
+	if values["provider"] != search.NameBocha || values["baseUrl"] != "https://api.bocha.cn" {
+		t.Fatalf("回填的字段 = %#v", values)
+	}
+	if values["enabled"] != true {
+		t.Fatalf("enabled 回填 = %#v, want true", values["enabled"])
+	}
+	masked, _ := values["apiKey"].(string)
+	if masked == "" || masked == "sk-abcdefgh" {
+		t.Fatalf("apiKey 回填 = %q，必须是掩码（读侧无明文）", masked)
+	}
+	if !strings.HasSuffix(masked, "efgh") {
+		t.Fatalf("掩码口径应与宿主的 maskToken 同源（尾 4 位），得到 %q", masked)
+	}
+}
+
+// TestWebSearchTestProviderHitsRealHTTP 是探针的判据：**真发一次请求**到盘上那条
+// 配置指的地址，用真应答区分「通了」与「没通」。
+func TestWebSearchTestProviderHitsRealHTTP(t *testing.T) {
+	hits := make(chan *http.Request, 1)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		hits <- r
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"results":[{"title":"A","url":"http://a.example","content":"alpha"}]}`))
+	}))
+	defer srv.Close()
+
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+	env.saveProvider(t, map[string]any{
+		"provider": search.NameSearXNG, "baseUrl": srv.URL + "/search", "enabled": true,
+	})
+
+	out := env.mustDispatch(t, search.ActionTestProvider, map[string]any{
+		"row": map[string]any{"provider": search.NameSearXNG},
+	})
+	res, ok := out.(search.ProbeResult)
+	if !ok {
+		t.Fatalf("探针结果类型 = %T", out)
+	}
+	if !res.OK || res.Count != 1 {
+		t.Fatalf("探针结论 = %+v, want ok 且 1 条", res)
+	}
+	select {
+	case r := <-hits:
+		if r.URL.Path != "/search" || !strings.Contains(r.URL.RawQuery, "q=cyrene") {
+			t.Fatalf("上游收到的请求 = %s?%s（探针必须真的搜一次）", r.URL.Path, r.URL.RawQuery)
+		}
+	default:
+		t.Fatal("上游一个请求都没收到 —— 探针没真发请求")
+	}
+}
+
+// TestWebSearchTestProviderReportsFailureHonestly 锁定失败口径：上游拒了凭据 ⇒
+// 结构化非 2xx（码 = 探针码，文案固定不含上游原文），绝不回一句假的「已完成」。
+func TestWebSearchTestProviderReportsFailureHonestly(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+		_, _ = w.Write([]byte(`{"error":"bad key sk-should-not-leak"}`))
+	}))
+	defer srv.Close()
+
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+	env.saveProvider(t, map[string]any{
+		"provider": search.NameSearXNG, "baseUrl": srv.URL, "enabled": true,
+	})
+
+	_, err := env.dispatch(t, search.ActionTestProvider, map[string]any{
+		"row": map[string]any{"provider": search.NameSearXNG},
+	})
+	ae, ok := pluginmgr.AsActionError(err)
+	if !ok {
+		t.Fatalf("探针失败 err = %v，期望结构化 ActionError", err)
+	}
+	if ae.Code != search.ProbeUnauthorized {
+		t.Fatalf("失败码 = %q, want %q", ae.Code, search.ProbeUnauthorized)
+	}
+	if ae.Status != http.StatusBadGateway {
+		t.Fatalf("失败状态 = %d, want 502（上游失败）", ae.Status)
+	}
+	if strings.Contains(ae.Message, "sk-should-not-leak") || ae.Message == "" {
+		t.Fatalf("失败文案 = %q（不得含上游原文，也不得为空）", ae.Message)
+	}
+}
+
+// TestWebSearchTestProviderNotConfiguredIsClientError 锁定「没配齐」归 400：
+// 这是调用方/配置的问题，不是上游不可用（前端据此区分该改配置还是该重试）。
+func TestWebSearchTestProviderNotConfiguredIsClientError(t *testing.T) {
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+	// 存一条**没配齐**的（显式清空 key）：探针必须在发请求**之前**就报 not_configured，
+	// 绝不拿一个没有凭据的配置去戳上游。
+	env.saveProvider(t, map[string]any{"provider": search.NameBocha, "apiKey": ""})
+
+	_, err := env.dispatch(t, search.ActionTestProvider, map[string]any{
+		"row": map[string]any{"provider": search.NameBocha},
+	})
+	ae, ok := pluginmgr.AsActionError(err)
+	if !ok || ae.Code != search.ProbeNotConfigured || ae.Status != http.StatusBadRequest {
+		t.Fatalf("err = %#v, want 400 not_configured", err)
+	}
+}
+
+// TestWebSearchActionsRejectUnknownProviderAndBadPayload 锁定动作的两类调用方错误
+// 都被**显式拒绝**（不静默存一条永远选不中的配置，也不把类型错当成空值）。
+func TestWebSearchActionsRejectUnknownProviderAndBadPayload(t *testing.T) {
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+
+	cases := []struct {
+		name     string
+		action   string
+		payload  any
+		wantCode string
+	}{
+		{"保存未登记的家", search.ActionSaveProvider,
+			map[string]any{"values": map[string]any{"provider": "tavily", "apiKey": "sk-x"}}, actionCodeUnknownProvider},
+		{"保存缺 provider", search.ActionSaveProvider,
+			map[string]any{"values": map[string]any{"apiKey": "sk-x"}}, pluginmgr.ActionCodeInvalidPayload},
+		{"保存缺 values 对象", search.ActionSaveProvider,
+			map[string]any{"apiKey": "sk-x"}, pluginmgr.ActionCodeInvalidPayload},
+		{"保存 enabled 类型错", search.ActionSaveProvider,
+			map[string]any{"values": map[string]any{"provider": search.NameBocha, "enabled": "yes"}}, pluginmgr.ActionCodeInvalidPayload},
+		{"探针未登记的家", search.ActionTestProvider,
+			map[string]any{"row": map[string]any{"provider": "tavily"}}, actionCodeUnknownProvider},
+		{"探针缺 provider", search.ActionTestProvider, map[string]any{}, pluginmgr.ActionCodeInvalidPayload},
+		{"reauth 未登记的家", search.ActionReauthProvider,
+			map[string]any{"row": map[string]any{"provider": "tavily"}}, actionCodeUnknownProvider},
+	}
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := env.dispatch(t, tc.action, tc.payload)
+			ae, ok := pluginmgr.AsActionError(err)
+			if !ok {
+				t.Fatalf("err = %v，期望结构化 ActionError", err)
+			}
+			if ae.Code != tc.wantCode || ae.Status != http.StatusBadRequest {
+				t.Fatalf("err = %+v, want code=%q status=400", ae, tc.wantCode)
+			}
+		})
+	}
+	// 被拒的保存不得在盘上留下痕迹（没写成功时文件可能根本不存在 —— 那也是「没留下」）。
+	if f, found, err := runtimeconfig.LoadWebSearch(env.path); err == nil && found {
+		for _, p := range f.Providers {
+			if p.Provider == "tavily" {
+				t.Fatal("未登记的家被写进了可变源")
+			}
+		}
+	}
+}
+
+// TestWebSearchOptionsActionFeedsDeclaredOptionsFrom 锁死「声明的下拉一定拉得到候选」：
+// 声明里每个 optionsFrom 映射出的动作名都**已登记且已声明**（否则前端只能降级成文本框）。
+func TestWebSearchOptionsActionFeedsDeclaredOptionsFrom(t *testing.T) {
+	env := newActionTestEnv(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+
+	sources := declaredOptionsSources(search.AdminPanels())
+	if len(sources) == 0 {
+		t.Fatal("声明里一个 optionsFrom 都没有：这条判据失去了意义")
+	}
+	for _, src := range sources {
+		name := pluginmgr.OptionsActionName(src)
+		if name == "" {
+			t.Fatalf("optionsFrom %q 映射不出动作名", src)
+		}
+		if _, ok := env.hub.Action(search.PanelPluginID, name); !ok {
+			t.Errorf("候选来源 %q（动作 %s）没进声明索引", src, name)
+		}
+		out, err := env.dispatch(t, name, map[string]any{})
+		if err != nil {
+			t.Errorf("候选来源 %q 调不动: %v", src, err)
+			continue
+		}
+		options, _ := out.(map[string]any)["options"].([]string)
+		if len(options) == 0 {
+			t.Errorf("候选来源 %q 回了空候选（表单下拉会空着）", src)
+		}
+		if strings.Join(options, ",") != strings.Join(search.ProviderOptions(), ",") {
+			t.Errorf("候选 = %v, want %v", options, search.ProviderOptions())
+		}
+	}
+}
+
+// TestWebSearchActionsUnwiredAnswers501 锁定降级口径：**没有配置**（测试夹具/装配未完成）
+// 时不登记任何处理器 ⇒ 已声明的动作诚实回 501（ErrActionUnavailable），
+// 绝不假装成功地回一份空列表。
+func TestWebSearchActionsUnwiredAnswers501(t *testing.T) {
+	cfg := wsLoadConfig(t, "WEB_SEARCH_PROVIDER="+search.NameSearXNG)
+	b := bus.New()
+	defer b.Close()
+	mgr := pluginmgr.NewManager(registry.New(), filepath.Join(cfg.DataDir, "plugins.json"), testLog())
+	defer mgr.Close(context.Background())
+
+	// cfg 为 nil ⇒ 组合根拿不到数据目录，动作登记被跳过（只告警）。
+	wirePanelHub(&app{log: testLog(), bus: b, plugins: mgr})
+	hub := mgr.Panels()
+	if got := hub.ActionHandlerNames(search.PanelPluginID); len(got) != 0 {
+		t.Fatalf("没有配置时不该登记任何处理器，实际 %v", got)
+	}
+	_, err := hub.Dispatch(context.Background(), pluginmgr.ActionRequest{
+		PluginID: search.PanelPluginID, Action: search.ActionListProviders,
+	})
+	if !errors.Is(err, pluginmgr.ErrActionUnavailable) {
+		t.Fatalf("err = %v, want ErrActionUnavailable（未登记处理器必须诚实回 501）", err)
+	}
+}