dsh-web-search-enhanced 0.0.6 → 0.1.1

package/CHANGELOG.md

@@ -1,6 +1,40 @@
-# Changelog
+# 更新日志
 
-All notable changes to the `dsh-web-search-enhanced` package will be documented in this file.
+记录 `dsh-web-search-enhanced` 的用户可见变化。历史条目描述对应版本，不代表当前行为。
+
+## [0.1.1] - 2026-09-21
+
+### 新增与优化
+
+- **模型与搜索连接智能记忆联动**：引入 `ModelPairingStore` 状态缓存机制（持久化于 `$DSH_HOME/cache/web-search-enhanced/model-connections.json`），实现不同对话模型与其最近一次选择的搜索连接自动绑定与恢复；新会话自动恢复该模型最近一次使用的搜索连接偏好，未记录模型平滑回退至全局默认配置。
+- **自定义连接配置全面采用 DSH 原生 YAML 规范**：设置页自定义连接编辑器升级为 DSH 原生 YAML 块级缩进格式（替代原 JSON 格式），大幅提升阅读与手动编辑体验，并保持完全向后兼容。
+- **配置自动迁移与静默自愈**：提供命令行配置迁移脚本 `scripts/migrate-config.mjs` (`pnpm run migrate`)，支持自动定位配置、安全创建 `.bak` 备份，并将旧版 JSON flow-style 自动修复转换为标准 YAML 块级缩进；同时支持插件启动时静默自愈。
+- **文档与应用市场体验优化**：优化 README 用户安装与上手指引，补充更友好的安装与使用说明及截图清单 `screenshots.json`。
+
+## [0.1.0] - 2026-09-21 🎉
+
+### 全新搜索连接架构
+
+- 用会话级搜索连接取代旧全局模型配置；对话模型与搜索连接独立选择。
+- 内置 Exa、Firecrawl、Tavily、Tinyfish，支持显式免 Key / 个人 API Key 模式；安装为新会话默认选择 Exa。
+- 支持固定搜索模型及跟随会话模型，适配 Anthropic Messages、OpenAI Responses、OpenAI Chat Completions。
+- 会话持久化连接与内容实时性偏好；请求使用冻结快照，fork 复制后独立，多标签页通过 revision 检测冲突。
+- 重写设置页与紧凑搜索选择器，支持表单化自定义连接、深浅色主题和窄屏布局。
+- 凭据通过 DSH Credentials 解析；设置仅保存引用与稀疏差异，自定义端点要求显式信任。
+- 扩充传输、宿主集成、会话隔离和 UI 回归测试；重写 README、配置、迁移、架构与开发文档。
+- 新增 Q 版 DeepSeek 鲸鱼娘搜索主题 Banner，并注明角色与参考作品归属。
+
+### 升级注意
+
+- 旧配置需在设置页显式导入；`configured` 映射至 `custom:legacy`，`current-session` 映射至跟随会话模型。明文 Key 先迁入 Credentials。
+- 不再执行 `fallbackModel` 或自动切换 Key / 服务；移除旧模型请求审计事件及 `/search-config` 快捷命令。
+- 跟随会话模型要求 provider 显式配置 `apiKeyEnv`；不重建 OAuth / 订阅凭据，不透传自定义 headers。
+- Tavily / Tinyfish 未显式设置访问方式时使用免 Key；Tinyfish `research_paper` 需要个人 Key。
+- 实时性是内容缓存年龄偏好，不是发布日期过滤，且仅部分适配器支持。
+- 前后端契约同时更新：升级后重新加载插件或重启宿主，并刷新页面。
+- 主开发线使用 `main`；旧 0.0.x 主线保留于 `legacy/v0.0.x`。
+
+详见[升级指南](docs/migration.zh-CN.md)。
 
 ## [0.0.6] - 2026-09-11
 
@@ -51,4 +85,4 @@ All notable changes to the `dsh-web-search-enhanced` package will be documented
 - Initial release of `dsh-web-search-enhanced`.
 - Support for Anthropic Messages, OpenAI Responses, and OpenAI Chat Completions search protocols.
 - Follow mode (`current-session`) and fixed search configuration mode.
-- DeepSeek Harness Web GUI settings card integration.
+- DeepSeek Harness Web GUI settings card integration.

package/README.md

@@ -1,252 +1,215 @@
-# dsh-web-search-enhanced
+<div align="center">
 
-[![npm version](https://img.shields.io/npm/v/dsh-web-search-enhanced.svg)](https://www.npmjs.com/package/dsh-web-search-enhanced)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-%3E%3D0.1.5--rc.2%20(RC%20Only)-blueviolet)](https://github.com/deepseek-ai/deepseek-harness)
+![Q 版 DeepSeek 鲸鱼娘与 Web Search Enhanced](docs/assets/deepseek-search-banner.png)
 
-**dsh-web-search-enhanced** 是为 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 量身打造的增强型多协议联网搜索插件。
+# Web Search Enhanced
 
-### 🌟 核心价值：直接使用模型供应商自身提供的联网搜索
+**聊天用喜欢的模型，搜索用合适的连接。**
 
-传统智能体方案通常需要额外购买和配置第三方搜索引擎 API（如 Tavily、Bing Search API、Google CSE 等），不仅流程繁琐，还带来了额外的账单与调用延迟。
+为 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 打造的增强型联网搜索插件。开箱即用免 Key 起步，支持在每段对话中自由搭配最适合的搜索引擎与实时性偏好。
 
-**dsh-web-search-enhanced** 让你可以**直接调用模型供应商（如 DeepSeek、Anthropic Claude、OpenAI 等）自身原生集成的服务端联网搜索功能**：
-- 🚫 **告别额外依赖**：无需申请或维护独立的搜索引擎 API Key，直接复用你现有的大模型 API 凭据。
-- 💰 **极致降低成本**：依托各大模型供应商原生提供的高性价比或免费搜索能力，大幅节约外部检索成本。
-- 🎯 **深度原生优化**：充分利用厂商针对大模型特别调优的网页抓取、实时索引、正文解析与引用标注体系，检索质量更高、响应更迅速。
-- 🔄 **保持原生体验**：模型端保持原生 `web_search` 工具签名与交互体验不变，无缝支持 Anthropic Messages、OpenAI Responses API 及 OpenAI Chat Completions 三大主流上游协议，并提供 Web 可视化配置面板。
+[![Release](https://img.shields.io/github/v/release/Yurzi/dsh-web-search-enhanced?style=flat-square)](https://github.com/Yurzi/dsh-web-search-enhanced/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-0.1.5--rc.2%2B-536DFE?style=flat-square)](package.json)
+[![Node.js](https://img.shields.io/badge/Node.js-22.19%2B%20%7C%2024%2B-green?style=flat-square)](package.json)
+
+[🚀 快速上手](#-快速上手) · [✨ 核心特性](#-核心特性) · [🔍 搜索引擎推荐](#-选哪种搜索服务) · [⚙️ 进阶配置](#️-进阶配置与个人-key) · [❓ 常见问题](#-常见问题-faq) · [📖 详细文档](#-想了解更多)
+
+</div>
 
 ---
 
 ## ✨ 核心特性
 
-- ⚡ **直接利用模型厂商内置搜索**：原生调用各大模型供应商自身的服务端搜索（如 Anthropic `web_search_20250305`、OpenAI `web_search` / `web_search_options`、DeepSeek 服务端搜索等），免去一切第三方搜索引擎开销。
-- 🌐 **多协议全面兼容**：无缝支持 **Anthropic Messages v1** (`/messages`)、**OpenAI Responses API** (`/responses`) 与 **OpenAI Chat Completions API** (`/chat/completions`) 三大协议，兼容各类官方端点与第三方 / 自建 AI 网关。
-- 🔄 **灵活的双路由模式**：
-  - **跟随当前会话 (`current-session`)**：自动继承当前会话正在使用的模型、提供方、调用协议与凭据，直接使用主模型供应商的搜索功能。
-  - **固定搜索路由 (`configured`)**：为联网搜索单独指定专用搜索模型（如 `deepseek-flash`、`claude-3-7-sonnet`、`gpt-4o` 等），主对话与搜索模型分工明确。
-  - **智能平滑兜底 (`fallbackModel`)**：当跟随模式遇到未知或未配置的模型路由时，自动降级至备用模型，确保搜索永不断流。
-- 🖥️ **Web 控制台可视化与稀疏配置 (Sparse Overrides)**：深度集成 DSH Web 端「设置 → 插件 → Web Search Enhanced」，支持中英文双语、即时表单校验、草稿暂存、一键保存与重置。遵循 DSH 原生稀疏覆盖规范，默认值不写入 `$DSH_HOME/settings.yaml`，杜绝配置文件膨胀与默认值锁死，并支持存量冗余项自动修剪。
-- 🔒 **凭据安全与隐私保护**：通过 DSH 原生 Credentials 机制安全写入并保管 API Key，公开设置文档绝不保存明文密钥；请求强制阻断携带凭据的恶意 HTTP 重定向。
-- 🎯 **开箱即用无感集成**：上游响应中的来源和引用会自动归一化为标准的 DSH `WebSearchResult`；主模型提示词和工作流无需任何改动。
+- 🐋 **开箱即用，免 Key 起步**：无需繁琐申请 API Key，安装默认选用 Exa 免 Key 检索，同时内置 Firecrawl、Tavily 与 Tinyfish，安装即刻体验联网搜索。
+- 🔀 **搜索与聊天自由解耦**：模型聊天与联网搜索互不干扰！无论你当前在与 Claude、GPT 还是本地模型对话，都可以随时为当前会话指定最擅长该领域的搜索引擎。
+- 💬 **会话级记忆与独立分支**：每段对话都会记住各自选用的搜索服务与实时性偏好；Fork 分支对话互不冲突，各自独立调整。
+- ⚡ **内容实时性自由掌控**：在输入区一键切换「自动 / 优先新鲜 / 优先实时」，随心平衡网页检索速度与最新内容抓取。
+- 🔐 **安全优雅的凭据隔离**：深度接入 DSH 原生 Credentials 体系，敏感 API Key 安全留存于凭据管理器中，绝不污染项目配置文件。
+- 🎨 **无缝融入原生界面**：聊天输入框随手弹出的快捷切换胶囊 + 直观清爽的插件设置面板，自适应浅色/深色主题与移动端窄屏。
 
 ---
 
-## 📋 版本兼容与支持策略 (Compatibility & Requirements)
+## 📸 界面预览
 
-- **最低支持的 DSH 版本**：`>= 0.1.5-rc.2`
-- **版本支持范围声明**：
-  > ⚠️ **重要声明**：**本插件仅对 DeepSeek Harness 的 Release Candidate (RC) 版本进行官方维护与兼容性支持（最低版本要求为 0.1.5-rc.2）**。
-  > 插件不提供对开发中的 Alpha / Beta / Nightly 构建版本的稳定性承诺与 API 兼容保证。在升级 DSH 或使用本插件时，请确保运行环境使用的是官方正式的 RC 发布版本。
+### 💬 会话快捷选择器（在聊天框随手切换）
 
----
+> 在输入框工具栏轻轻一点，即可随时为当前会话切换搜索引擎与内容实时性，无需跳转设置，不打断对话灵感。
 
-## 📦 快速安装
+<p align="center">
+  <img src="docs/assets/search-picker-desktop.png" alt="会话快捷选择器" width="850" />
+</p>
+<p align="center">
+  <sub>切换视图：<b>桌面浅色（上图）</b> · <a href="docs/assets/search-picker-dark.png">桌面深色</a> · <a href="docs/assets/search-picker-narrow.png">移动窄屏</a></sub>
+</p>
 
-插件已正式发布至 npmjs，使用 DSH CLI 即可一键安装到 `web` Profile：
+### ⚙️ 统一插件设置中心
 
-```bash
-# 安装插件至 web profile
-dsh plugin --profile web add dsh-web-search-enhanced
-```
+> 集中管理默认连接、免 Key / 个人 Key 访问模式、凭据引用与自定义模型端点。
 
-安装完成后，重启 `dsh web` 服务即可生效：
+<p align="center">
+  <img src="docs/assets/settings-desktop.png" alt="插件设置中心" width="850" />
+</p>
+<p align="center">
+  <sub>切换视图：<b>桌面浅色（上图）</b> · <a href="docs/assets/settings-dark.png">桌面深色</a> · <a href="docs/assets/settings-mobile.png">移动窄屏</a></sub>
+</p>
 
-```bash
-# 启动或重启 DSH Web 服务
-dsh web
-```
+---
 
-> 💡 **提示**：安装后，插件随附的 `cordis.patch.yml` 会自动将搜索提供方指向 `enhanced-search`，并禁用原生默认搜索提供方。
+## 🚀 快速上手
 
----
+### 环境要求
 
-## 🚀 快速上手与配置
+- **DeepSeek Harness**：≥ `0.1.5-rc.2`
+- **Node.js**：`^22.19.0 || >=24.0.0`
 
-### 方式一：Web 界面可视化配置（推荐）
+### 步骤 1：安装插件
 
-> ⚡ **快捷命令**：在任何会话输入框中键入斜杠命令 `/search-config` 并回车，即可一键直达本插件设置面板！
+**方式 A：通过 GitHub Release 离线包安装（推荐）**
 
-1. 打开 DeepSeek Harness Web 界面（默认 `http://127.0.0.1:3080`）。
-2. 点击左侧导航栏的 **设置 (Settings)** → **插件 (Plugins)**（或使用 `/search-config`）。
-3. 找到 **Web Search Enhanced (插件配置)** 卡片。
-4. 根据需要选择**模型路由**、**API 协议**、**接口地址 (Base URL)** 与 **模型标识 (Model ID)**。
-5. 在 **API Key** 输入框中输入对应的模型供应商 API 密钥（输入后仅用于安全保存，保存成功后输入框自动清空，不留明文痕迹）。
-6. 点击 **保存 (Save)** 即可实时生效，无需重启！
+从 [v0.1.1 Release](https://github.com/Yurzi/dsh-web-search-enhanced/releases/tag/v0.1.1) 下载预构建包 `dsh-web-search-enhanced-0.1.1.tgz`，执行绝对路径安装命令：
 
----
+```sh
+dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.1.tgz
+```
+
+**方式 B：通过 npm 在线安装**
 
-### 方式二：环境变量与配置文件配置
+在版本已发布到 npm 仓库后，也可直接安装：
 
-如果你使用 Headless 模式或希望通过环境配置初始化：
+```sh
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.1
+```
 
-1. **设置 API Key 环境变量**（默认变量名为 `WEB_SEARCH_ENHANCED_API`）：
-   ```bash
-   export WEB_SEARCH_ENHANCED_API="sk-your-api-key-here"
-   ```
+### 步骤 2：生效与刷新
 
-2. **在 `cordis.yml` 中声明配置**（可选）：
-   ```yaml
-   - id: web-search-enhanced
-     name: dsh-web-search-enhanced
-     config:
-       modelMode: configured
-       protocol: anthropic-messages
-       baseURL: https://api.deepseek.com/anthropic/v1
-       model: deepseek-flash
-       apiKeyEnv: WEB_SEARCH_ENHANCED_API
-       maxTokens: 4096
-   ```
+1. 重载插件或重启 DSH 服务端。
+2. 刷新浏览器 Web 页面，确保前端客户端组件与后端服务同步更新。
 
----
+### 步骤 3：立即提问体验
 
-## 💡 常用场景配置示例
+新建一段会话，输入框上方默认已为你准备好 **Exa · 免 Key** 搜索连接。直接向 AI 提问：
 
-你可以直接参考以下常见场景的配置参数，轻松接入各厂商自身提供的原生搜索功能：
+> 💡 **提问示例**：“搜索最近的 TypeScript 发布说明，总结最重要的几个变化并附上引用来源。”
 
-### 1. DeepSeek 官方搜索（默认推荐）
-使用 DeepSeek 官方兼容 Anthropic 协议的服务端搜索，速度快且成本极低：
-- **模型路由 (modelMode)**: `固定配置 (configured)`
-- **API 协议 (protocol)**: `Anthropic Messages v1`
-- **接口地址 (baseURL)**: `https://api.deepseek.com/anthropic/v1`
-- **模型标识 (model)**: `deepseek-flash`
-- **API Key**: 填入你的 DeepSeek API Key
+AI 会自动通过 Web Search Enhanced 检索最新网络资料，并附带网页来源回答你！
 
 ---
 
-### 2. Anthropic 官方 Claude 联网搜索
-直接调用 Claude 官方 Messages API 原生内置的 `web_search` 服务端搜索能力：
-- **模型路由 (modelMode)**: `固定配置 (configured)`
-- **API 协议 (protocol)**: `Anthropic Messages v1`
-- **接口地址 (baseURL)**: `https://api.anthropic.com/v1`
-- **模型标识 (model)**: `claude-3-7-sonnet-20250219` 或 `claude-3-5-sonnet-20241022`
-- **内部搜索标识符 (toolIdentifier)**: 留空（默认使用 `web_search_20250305`）
-- **API Key**: 填入你的 Anthropic API Key
+## 🔍 选哪种搜索服务？
 
----
+Web Search Enhanced 内置了多种主流检索服务与模型搜索能力，你可以按需随心选择：
 
-### 3. OpenAI Responses API
-使用 OpenAI 官方 Responses API 内置的原生联网搜索工具：
-- **模型路由 (modelMode)**: `固定配置 (configured)`
-- **API 协议 (protocol)**: `OpenAI Responses API`
-- **接口地址 (baseURL)**: `https://api.openai.com/v1`
-- **模型标识 (model)**: `gpt-4o`
-- **搜索上下文大小 (searchContextSize)**: `中 (medium)`（可选 `low` / `medium` / `high`）
-- **API Key**: 填入你的 OpenAI API Key
+| 搜索连接         | 推荐场景                        | 访问模式                       | 特点说明                                                                          |
+| :--------------- | :------------------------------ | :----------------------------- | :-------------------------------------------------------------------------------- |
+| **Exa** _(默认)_ | 💻 开发者、技术文档、论文研究   | 免 Key (开箱即用) / 个人 Key   | 强大的语义神经检索，对编程与深度学术内容理解极准；个人 Key 支持配置搜索类型       |
+| **Firecrawl**    | 📰 新闻资讯、深度文章抓取       | 免 Key (开箱即用) / 个人 Key   | 擅长清洗和抓取干净的 Markdown 网页正文；支持优先获取最新页面                      |
+| **Tavily**       | 🔍 事实核查、行业调研、综合检索 | 免 Key (开箱即用) / 个人 Key   | 专为大语言模型打造的搜索服务，支持自定义搜索深度（快速/进阶）与新闻主题           |
+| **Tinyfish**     | 🌍 跨语言搜索、地域本地化资讯   | 免 Key (开箱即用) / 个人 Key   | 支持按国家地区、特定语言和搜索用途精准过滤检索范围                                |
+| **专用搜索模型** | 🤖 统一使用特定支持联网的模型   | Anthropic / OpenAI 协议        | 通过服务端搜索能力（如 OpenAI Responses、Anthropic Messages）直接返回带引用的回答 |
+| **跟随会话模型** | 🔄 懒人模式，搜索使用当前模型   | 需配置 provider 的 `apiKeyEnv` | 自动沿用当前会话选定的模型与端点发起联网搜索                                      |
+
+> 💡 **关于免 Key 访问**：
+> 免 Key 模式走的是上游提供的公共接入通道，省去了新用户申请注册 API Key 的繁琐步骤。
+> 公共通道可能因高峰期并发或网络 IP 受限；如遇限流，可以在输入框临时切换到其他免 Key 连接（如 Tavily / Firecrawl），或者在设置中配置自己的专属 API Key。
 
 ---
 
-### 4. OpenAI Chat Completions 专用搜索模型 / 兼容中转网关
-使用 OpenAI 官方搜索模型（如 `gpt-4o-search`）或各类第三方兼容网关（如 OneAPI、NewAPI、OpenRouter 等）提供的原生搜索支持：
-- **模型路由 (modelMode)**: `固定配置 (configured)`
-- **API 协议 (protocol)**: `OpenAI Chat Completions API`
-- **接口地址 (baseURL)**: `https://api.openai.com/v1`（或中转网关地址，如 `https://api.your-proxy.com/v1`）
-- **模型标识 (model)**: 目标搜索模型标识（如 `gpt-4o-search`）
-- **Chat 搜索能力 (chatSearchMode)**: `官方专用搜索模型 (search-model)`（若网关使用自定义字段可切换为 `vendor-options`）
-- **API Key**: 填入网关或官方 API Key
+## ⏱️ 内容实时性说明
 
----
+在聊天输入框的搜索菜单中，你可以为当前会话设置**内容实时性**：
+
+- **自动 (Auto)**：采用搜索引擎默认的缓存与检索策略，响应快速。
+- **优先新鲜 (Fresh)**：优先使用不超过 24 小时的较新网页缓存（Firecrawl / Exa 个人 Key 支持）。
+- **优先实时 (Realtime)**：发起重新爬取，获取页面当前时刻的最新内容（适合突发新闻、最新行情等时效极高的场景）。
 
-### 5. 跟随当前会话模型（自动继承厂商搜索）
-让搜索自动使用当前 Agent 会话正在对话的模型供应商与协议：
-- **模型路由 (modelMode)**: `当前会话模型 (current-session)`
-- **兜底搜索模型 (fallbackModel)**: `deepseek-flash`（当当前模型不支持搜索协议或未解析到凭据时自动平滑回退）
-- **API 协议 / 接口地址 / API Key**: 自动跟随当前会话的 LLM 路由配置
+_注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不支持实时性控制的连接，系统会自动保留偏好并优雅回退至默认检索。_
 
 ---
 
-## ⚙️ 详细配置参数表
-
-| 参数名 | 对应 Web 界面 | 默认值 | 可选值 / 格式 | 说明 |
-| :--- | :--- | :--- | :--- | :--- |
-| `modelMode` | 模型路由 | `configured` | `configured` (固定配置)<br>`current-session` (跟随当前会话) | 决定搜索使用固定的独立模型，还是跟随当前会话的模型与协议。 |
-| `protocol` | API 协议 | `anthropic-messages` | `anthropic-messages`<br>`openai-responses`<br>`openai-chat-completions` | 固定路由或兜底路由使用的上游 HTTP 协议。 |
-| `baseURL` | 接口基础地址 | `https://api.deepseek.com/anthropic/v1` | 绝对 HTTP(S) URL | 上游接口的基础 URL。若末尾未包含协议端点后缀，插件会自动补全。 |
-| `model` | 模型标识 | `deepseek-flash` | 字符串 | 固定路由使用的模型 ID，或无会话模型时的默认模型。 |
-| `fallbackModel` | 兜底搜索模型 | 留空（默认同 `model`） | 字符串 | 仅跟随模式：当无法解析当前会话路由时所采用的兜底模型。 |
-| `apiKeyEnv` | API Key 环境变量 | `WEB_SEARCH_ENHANCED_API` | 环境变量名 | 读取 API Key 的凭据引用名称。 |
-| `apiKey` | API Key | 无 | 字符串（密钥） | Web 设置界面提供的一次性保存输入框，安全存入 DSH 凭据中心后自动清空。 |
-| `toolIdentifier` | 内部搜索标识符 | 依协议自动推导 | 字符串 | 上游搜索工具/选项字段名。留空时自动适配官方默认名称。 |
-| `maxTokens` | 最大输出 Token | `4096` | 正整数 | 单次搜索请求的最大输出 Token 数。 |
-| `maxUses` | 最大搜索次数 | `5` | 正整数 | 仅 Anthropic 协议：单次请求允许服务端调用的最大搜索次数。 |
-| `apiVersion` | Anthropic API 版本 | `2023-06-01` | 字符串 | 仅 Anthropic 协议：写入 `anthropic-version` 请求头的版本标识。 |
-| `chatSearchMode` | Chat 搜索能力 | `search-model` | `search-model`<br>`vendor-options` | 仅 Chat 协议：官方专用搜索模型模式，或第三方网关自定义选项字段模式。 |
-| `searchContextSize` | 搜索上下文大小 | 上游默认 | `low` / `medium` / `high` | 仅 OpenAI 协议：搜索上下文预算大小。 |
+## ⚙️ 进阶配置与个人 Key
 
----
+如果你拥有各平台专属的 API Key，或想要自定义专用搜索模型，只需打开 **设置 → 插件 → Web Search Enhanced**：
 
-## 🔒 凭据安全与隐私设计
+1. **绑定个人 API Key**：
+   - 找到目标连接（例如 Firecrawl 或 Tavily）。
+   - 在凭据输入框填入你的 API Key，点击保存（将自动存入 DSH Credentials，安全可靠）。
+   - 将“访问方式”从“免 Key”切换为“个人 Key”。
+2. **设置新会话默认连接**：
+   - 在“新会话默认连接”下拉框中选择你最常用的引擎，新创建的对话将自动应用该偏好。
+3. **添加自定义模型或端点**：
+   - 支持添加任意兼容 OpenAI 或 Anthropic 服务端搜索协议的模型端点。
 
-1. **凭据安全隔离**：Web 设置卡片中的 API Key 输入框仅作为向 `ctx.remote.credentials.set()` 发送写入请求的临时通道。一旦保存成功，输入框立即清空，DSH 的普通 settings document 中**绝对不会存储明文密钥**。
-2. **防凭据泄漏机制**：所有向上游发起的请求均设置 `redirect: 'error'`。若上游服务发生 HTTP 重定向，请求会立即终止，严防 `Authorization` 或 `x-api-key` 被第三方捕获。
-3. **URL 规范校验**：接口地址 (`baseURL`) 严格禁止包含用户名、密码、Query 参数或 Hash 锚点，杜绝敏感信息通过 URL 泄漏。
+完整配置语法与高级参数白名单，请参阅 📖 [详细配置指南](docs/configuration.zh-CN.md)。
 
 ---
 
 ## ❓ 常见问题 (FAQ)
 
 <details>
-<summary><strong>Q: 为什么推荐直接使用模型供应商的内置搜索，而不是配置第三方搜索引擎？</strong></summary>
+<summary><b>Q1: 搜索时提示 <code>WEB_SEARCH_NOT_SELECTED</code>？</b></summary>
 
-**A**: 
-1. **省心省钱**：直接使用已有的大模型 API 凭据，无需单独注册、付费订阅第三方搜索服务（如 Tavily、Bing API 等）；
-2. **质量与整合度高**：大模型供应商（如 Anthropic、OpenAI、DeepSeek）针对模型理解对抓取内容和上下文预算进行了专门优化；
-3. **低延迟**：检索与正文提取由模型服务端直接完成，避免了客户端多次网络往返。
+**原因**：当前会话没有选定任何搜索连接。  
+**解决办法**：在输入框右侧工具栏点击搜索图标/胶囊，在弹出的菜单中勾选任意一个搜索服务（如 Exa 或 Firecrawl）；或者在插件设置中为“新会话默认连接”指定一个默认引擎。
 </details>
 
 <details>
-<summary><strong>Q: 安装插件后，模型会知道底层搜索协议改变了吗？</strong></summary>
+<summary><b>Q2: 免 Key 搜索突然提示失败或限流（<code>WEB_KEYLESS_UNAVAILABLE</code> / <code>WEB_PROVIDER_RATE_LIMITED</code>）？</b></summary>
+
+**原因**：免 Key 服务基于上游公共节点，高峰时段或特定网络 IP 可能触发临时频率限制。  
+**解决办法**：
+
+1. 在会话输入框中快速切换到另一个免 Key 引擎（如从 Exa 换到 Firecrawl 或 Tavily）。
+2. 在设置中为该引擎填入你自己的官方 API Key，并将访问方式切换为“个人 Key”。
 
-**A**: 不会。DSH 内部采用分层架构，模型端看到的依然是原生的 `web_search` 工具，参数与返回值结构完全保持一致。插件仅在后台将搜索请求代理至你配置的上游协议，并把来源与引用归一化为 DSH 标准的 `WebSearchResult`。
 </details>
 
 <details>
-<summary><strong>Q: 搜索时提示 <code>WEB_PROVIDER_CREDENTIAL_MISSING</code> 怎么办？</strong></summary>
+<summary><b>Q3: 我在设置中填了 API Key，为什么搜索依然是免 Key 模式？</b></summary>
 
-**A**: 表示未找到有效的 API Key。请在 Web 界面「设置 → 插件 → Web Search Enhanced」卡片中输入 API Key 并点击保存，或者在启动 DSH 前配置环境变量（如 `export WEB_SEARCH_ENHANCED_API="sk-..."`）。
+**原因**：为了防止意外产生付费额度消耗，插件设计了“显式切换保护”——保存 Key 并不会自动切换通道。  
+**解决办法**：在设置页该连接的卡片上，将下拉选项由 **免 Key** 手动切换为 **个人 Key (API Key)** 即可。
 </details>
 
 <details>
-<summary><strong>Q: 跟随模式 (current-session) 在什么情况下会触发兜底？</strong></summary>
+<summary><b>Q4: 我在会话中修改了搜索引擎，会影响其他会话吗？Fork 对话呢？</b></summary>
+
+**不会**。Web Search Enhanced 是完全**会话隔离**的：
+
+- 修改当前会话的搜索连接，不会影响已经存在的其他会话。
+- Fork（分支）出的新会话会继承分支那一刻的搜索设置，之后两者独立变更，互不干扰。
 
-**A**: 当出现以下情况时会自动使用 `fallbackModel` 兜底：
-- 当前 Agent 尚未选择具体模型；
-- 当前模型的 Provider 未配置接口地址或协议不匹配；
-- 获取当前路由的 ModelInfo 失败。
 </details>
 
 <details>
-<summary><strong>Q: 如何卸载插件或还原到原生搜索？</strong></summary>
+<summary><b>Q5: 如何从 0.0.x 旧版本平滑升级？</b></summary>
 
-**A**: 运行以下命令从 Profile 中移除插件并重启 DSH：
-```bash
-dsh plugin --profile web remove dsh-web-search-enhanced
-```
+进入 **设置 → 插件 → Web Search Enhanced**，系统会自动检测旧版全局模型配置并弹出“导入旧配置”提示，一键点击即可无缝映射为新版连接配置。详细注意事项请参阅 📖 [升级指南](docs/migration.zh-CN.md)。
 </details>
 
 ---
 
-## 🛠️ 本地开发与调试
+## 📖 想了解更多？
 
-如果你希望基于本项目进行二次开发或贡献代码：
+| 文档                                                     | 适合谁读            | 主要内容                                                          |
+| :------------------------------------------------------- | :------------------ | :---------------------------------------------------------------- |
+| 📘 **[配置指南](docs/configuration.zh-CN.md)**           | 所有用户 / 进阶用户 | 完整参数列表、凭据机制、高级 options 白名单、自定义端点与排错字典 |
+| 📙 **[升级指南](docs/migration.zh-CN.md)**               | 从旧版升级的老用户  | 0.1.0 架构变化、旧版导入指引、升级踩坑预防                        |
+| 📗 **[架构设计说明](docs/design-v2.converged.zh-CN.md)** | 开发者 / 架构爱好者 | 会话状态隔离、请求快照机制、多适配器与安全性设计                  |
+| 🛠️ **[开发与验证文档](docs/v2-implementation.zh-CN.md)** | 插件二次开发者      | 本地构建、单元测试、浏览器环境验证与打包发布                      |
+| 📝 **[更新日志](CHANGELOG.md)**                          | 所有人              | 版本演进记录与历史变更                                            |
 
-```bash
-# 克隆仓库并安装依赖
-git clone https://github.com/your-username/dsh-web-search-enhanced.git
-cd dsh-web-search-enhanced
-pnpm install
-
-# 运行全套检查（类型检查 + 单元测试 + 构建 + 打包契约验证）
-pnpm run check
+---
 
-# 单独运行单元测试
-npx vitest run
-```
+## 💬 问题反馈
 
-技术架构与详细设计文档请参阅 [docs/design.zh-CN.md](docs/design.zh-CN.md)。
+如果在使用过程中遇到问题，欢迎前往 [GitHub Issues](https://github.com/Yurzi/dsh-web-search-enhanced/issues) 提交反馈。  
+_提示：提 issue 时请附上 DSH 版本、插件版本及报错简述，并请注意**脱敏**，切勿粘贴个人 API Key 或私密对话内容。_
 
 ---
 
-## 📄 开源许可证
+## 🤝 致谢与许可
 
-本项目基于 [MIT License](LICENSE) 开源。
+- 本项目代码遵循 [MIT](LICENSE) 开源协议。
+- 衷心感谢 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 团队及各搜索服务（Exa、Firecrawl、Tavily、Tinyfish 等）的开发者。
+- **关于横幅形象**：Banner 中的 DeepSeek 鲸鱼娘形象来源于 **上善无形原创角色与 ZipZipPipe 二创**；本项目横幅基于用户提供的参考图经 AI 辅助创作。角色与参考作品的著作权利均归原作者所有，不因本项目代码的 MIT 许可而获得再授权，亦不代表官方背书。

package/cordis.patch.yml

@@ -13,8 +13,4 @@
     - id: web-search-enhanced
       name: dsh-web-search-enhanced
       config:
-        modelMode: configured
-        protocol: anthropic-messages
-        apiKeyEnv: WEB_SEARCH_ENHANCED_API
-        fallbackModel: deepseek-flash
-        maxTokens: 4096
+        defaultConnection: builtin:exa # Explicit zero-key default for new Sessions; never replaces a saved selection.