dsh-web-search-enhanced 0.0.6 → 0.1.0

package/CHANGELOG.md

@@ -1,6 +1,31 @@
-# Changelog
+# 更新日志
 
-All notable changes to the `dsh-web-search-enhanced` package will be documented in this file.
+记录 `dsh-web-search-enhanced` 的用户可见变化。历史条目描述对应版本，不代表当前行为。
+
+## [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 +76,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,92 @@
-# dsh-web-search-enhanced
+![Q 版 DeepSeek 鲸鱼娘与 Web Search Enhanced](docs/assets/deepseek-search-banner.png)
 
-[![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)
+# Web Search Enhanced
 
-**dsh-web-search-enhanced** 是为 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 量身打造的增强型多协议联网搜索插件。
+<div align="center">
 
-### 🌟 核心价值：直接使用模型供应商自身提供的联网搜索
+**聊天用喜欢的模型，搜索用合适的连接。**
 
-传统智能体方案通常需要额外购买和配置第三方搜索引擎 API（如 Tavily、Bing Search API、Google CSE 等），不仅流程繁琐，还带来了额外的账单与调用延迟。
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 增强原生 `web_search`，让每段对话都有自己的搜索方式。
 
-**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/code-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)
 
----
+[快速开始](#快速开始) · [配置指南](docs/configuration.zh-CN.md) · [升级指南](docs/migration.zh-CN.md) · [开发文档](docs/v2-implementation.zh-CN.md)
 
-## ✨ 核心特性
+</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 起步**：安装默认选用 Exa，也可选择 Firecrawl、Tavily 或 Tinyfish。
+- **🔀 搜索与聊天分开选**：会话内切换搜索服务、专用搜索模型，或跟随当前会话模型，不改变聊天模型。
+- **🕒 每段对话记住偏好**：搜索连接和内容实时性独立持久化，fork 后各自调整。
+- **🔐 凭据不混进配置**：API Key 交给 DSH Credentials；免 Key 与个人 Key 显式切换，不偷偷回退。
+- **🎛️ 原生界面，轻巧配置**：输入区快速切换，设置页管理连接，支持深浅色主题与窄屏。
 
-## 📋 版本兼容与支持策略 (Compatibility & Requirements)
+> 免 Key 不等于无限免费：上游可能限流、限制 IP 或调整匿名访问政策。插件不会绕过限制，也不会自动改用你的付费 Key。
 
-- **最低支持的 DSH 版本**：`>= 0.1.5-rc.2`
-- **版本支持范围声明**：
-  > ⚠️ **重要声明**：**本插件仅对 DeepSeek Harness 的 Release Candidate (RC) 版本进行官方维护与兼容性支持（最低版本要求为 0.1.5-rc.2）**。
-  > 插件不提供对开发中的 Alpha / Beta / Nightly 构建版本的稳定性承诺与 API 兼容保证。在升级 DSH 或使用本插件时，请确保运行环境使用的是官方正式的 RC 发布版本。
+## 快速开始
 
----
+需要 **DSH ≥ 0.1.5-rc.2** 和 **Node.js `^22.19.0 || >=24.0.0`**。本版以 DSH 0.1.5-rc.2 契约为验证基线，不承诺兼容 alpha 或任意未来版本。
 
-## 📦 快速安装
+从 [v0.1.0 Release](https://github.com/Yurzi/dsh-web-search-enhanced/releases/tag/v0.1.0) 下载 `dsh-web-search-enhanced-0.1.0.tgz`，使用绝对路径安装：
 
-插件已正式发布至 npmjs，使用 DSH CLI 即可一键安装到 `web` Profile：
-
-```bash
-# 安装插件至 web profile
-dsh plugin --profile web add dsh-web-search-enhanced
+```sh
+dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.0.tgz
 ```
 
-安装完成后，重启 `dsh web` 服务即可生效：
+npm 上提供该版本后，也可以：
 
-```bash
-# 启动或重启 DSH Web 服务
-dsh web
+```sh
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.0
 ```
 
-> 💡 **提示**：安装后，插件随附的 `cordis.patch.yml` 会自动将搜索提供方指向 `enhanced-search`，并禁用原生默认搜索提供方。
-
----
-
-## 🚀 快速上手与配置
-
-### 方式一：Web 界面可视化配置（推荐）
-
-> ⚡ **快捷命令**：在任何会话输入框中键入斜杠命令 `/search-config` 并回车，即可一键直达本插件设置面板！
-
-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)** 即可实时生效，无需重启！
-
----
-
-### 方式二：环境变量与配置文件配置
-
-如果你使用 Headless 模式或希望通过环境配置初始化：
-
-1. **设置 API Key 环境变量**（默认变量名为 `WEB_SEARCH_ENHANCED_API`）：
-   ```bash
-   export WEB_SEARCH_ENHANCED_API="sk-your-api-key-here"
-   ```
-
-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，再刷新 Web 页面，使前后端一起更新。
+2. 新建会话，在输入区选择搜索连接；安装默认是 **Exa · 免 Key**。
+3. 直接提问：**“搜索最近的 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
+要使用个人 Key 或专用搜索模型？打开 **设置 → 插件 → Web Search Enhanced**。旧版用户请先阅读[升级指南](docs/migration.zh-CN.md)，已有会话不会被新默认值覆盖。
 
----
+## 选一种搜索方式
 
-### 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
+| 连接 | 适合怎么用 | 访问方式 |
+| --- | --- | --- |
+| **Exa** | 默认开箱尝试；个人 Key 可配置搜索类型 | 免 Key MCP / API Key REST |
+| **Firecrawl** | 搜索并按需获取更鲜的网页正文 | 免 Key / API Key REST |
+| **Tavily** | 配置搜索深度与主题 | 免 Key / API Key REST |
+| **Tinyfish** | 按地区、语言和用途搜索 | 免 Key MCP / API Key REST |
+| **专用模型** | 固定一个支持服务端搜索的模型 | Anthropic Messages / OpenAI Responses / Chat Completions |
+| **跟随会话模型** | 使用当前会话的 provider 和 model | 需显式 `apiKeyEnv`；不接管订阅或 OAuth 登录 |
 
----
+协议兼容不等于模型具备搜索能力；各模式支持的选项也不同。详见[连接与参数说明](docs/configuration.zh-CN.md)。
 
-### 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
+### 内容实时性，由当前会话决定
 
----
+可选 **自动 / 优先新鲜 / 优先实时**。这是网页内容缓存年龄偏好，不是“只搜最近发布的文章”。目前 Firecrawl 和 Exa 个人 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
+## 界面预览
 
----
+![Web Search Enhanced 设置界面](docs/assets/settings-desktop.png)
 
-### 5. 跟随当前会话模型（自动继承厂商搜索）
-让搜索自动使用当前 Agent 会话正在对话的模型供应商与协议：
-- **模型路由 (modelMode)**: `当前会话模型 (current-session)`
-- **兜底搜索模型 (fallbackModel)**: `deepseek-flash`（当当前模型不支持搜索协议或未解析到凭据时自动平滑回退）
-- **API 协议 / 接口地址 / API Key**: 自动跟随当前会话的 LLM 路由配置
+[深色设置](docs/assets/settings-dark.png) · [窄屏设置](docs/assets/settings-mobile.png) · [会话选择器](docs/assets/search-picker-desktop.png) · [深色选择器](docs/assets/search-picker-dark.png) · [窄屏选择器](docs/assets/search-picker-narrow.png)
 
----
+<sub>预览来自实际 React 组件的隔离浏览器渲染，不代表你的 DSH 已完成安装。</sub>
 
-## ⚙️ 详细配置参数表
+## 想了解更多？
 
-| 参数名 | 对应 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 协议：搜索上下文预算大小。 |
-
----
-
-## 🔒 凭据安全与隐私设计
-
-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 泄漏。
-
----
-
-## ❓ 常见问题 (FAQ)
-
-<details>
-<summary><strong>Q: 为什么推荐直接使用模型供应商的内置搜索，而不是配置第三方搜索引擎？</strong></summary>
-
-**A**: 
-1. **省心省钱**：直接使用已有的大模型 API 凭据，无需单独注册、付费订阅第三方搜索服务（如 Tavily、Bing API 等）；
-2. **质量与整合度高**：大模型供应商（如 Anthropic、OpenAI、DeepSeek）针对模型理解对抓取内容和上下文预算进行了专门优化；
-3. **低延迟**：检索与正文提取由模型服务端直接完成，避免了客户端多次网络往返。
-</details>
-
-<details>
-<summary><strong>Q: 安装插件后，模型会知道底层搜索协议改变了吗？</strong></summary>
-
-**A**: 不会。DSH 内部采用分层架构，模型端看到的依然是原生的 `web_search` 工具，参数与返回值结构完全保持一致。插件仅在后台将搜索请求代理至你配置的上游协议，并把来源与引用归一化为 DSH 标准的 `WebSearchResult`。
-</details>
-
-<details>
-<summary><strong>Q: 搜索时提示 <code>WEB_PROVIDER_CREDENTIAL_MISSING</code> 怎么办？</strong></summary>
-
-**A**: 表示未找到有效的 API Key。请在 Web 界面「设置 → 插件 → Web Search Enhanced」卡片中输入 API Key 并点击保存，或者在启动 DSH 前配置环境变量（如 `export WEB_SEARCH_ENHANCED_API="sk-..."`）。
-</details>
-
-<details>
-<summary><strong>Q: 跟随模式 (current-session) 在什么情况下会触发兜底？</strong></summary>
-
-**A**: 当出现以下情况时会自动使用 `fallbackModel` 兜底：
-- 当前 Agent 尚未选择具体模型；
-- 当前模型的 Provider 未配置接口地址或协议不匹配；
-- 获取当前路由的 ModelInfo 失败。
-</details>
-
-<details>
-<summary><strong>Q: 如何卸载插件或还原到原生搜索？</strong></summary>
-
-**A**: 运行以下命令从 Profile 中移除插件并重启 DSH：
-```bash
-dsh plugin --profile web remove dsh-web-search-enhanced
-```
-</details>
-
----
-
-## 🛠️ 本地开发与调试
-
-如果你希望基于本项目进行二次开发或贡献代码：
-
-```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/configuration.zh-CN.md) | 凭据、供应商、实时性、模型连接、配置示例与排错 |
+| [从旧版升级](docs/migration.zh-CN.md) | V1 导入、行为变化、分支与回退注意事项 |
+| [架构说明](docs/design-v2.converged.zh-CN.md) | 会话状态、请求快照、适配器与安全边界 |
+| [开发与验证](docs/v2-implementation.zh-CN.md) | 本地构建、测试、浏览器检查与发布流程 |
+| [更新日志](CHANGELOG.md) | 0.1.0 重构与历史版本 |
 
-技术架构与详细设计文档请参阅 [docs/design.zh-CN.md](docs/design.zh-CN.md)。
+遇到问题请提交 [Issue](https://github.com/Yurzi/dsh-web-search-enhanced/issues)，附 DSH / 插件版本、连接类型及脱敏错误；请勿上传 API Key、私有查询或完整凭据文件。
 
----
+## 致谢与许可
 
-## 📄 开源许可证
+代码以 [MIT](LICENSE) 开源。感谢 DeepSeek Harness 及各搜索服务的开发者。
 
-本项目基于 [MIT License](LICENSE) 开源。
+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.

package/docs/configuration.zh-CN.md

@@ -0,0 +1,195 @@
+# 0.1.0 配置参考
+
+本指南面向安装版插件。包版本为 **0.1.0**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
+
+## 配置入口与作用范围
+
+在 DSH 设置的 Web Search Enhanced 卡片管理搜索连接、凭据引用与新会话默认值，在已有会话输入区选择搜索连接和内容实时性。搜索连接独立于对话模型。设置按宿主 SettingsScope 保存稀疏覆盖，不复制整个内置目录；恢复继承设置、删除用户连接覆盖均不删除 Credentials。继承层中的连接在移除用户覆盖后仍可能存在。
+
+以下 YAML 的 `web-search-enhanced` 是 Settings 命名空间。若编辑 Cordis 插件条目的 `config`，仅放该命名空间下的字段，不能原样把整个示例作为 Cordis 根配置。优先使用设置 UI，避免覆盖其他插件设置。
+
+```yaml
+web-search-enhanced:
+  version: 2
+  defaultConnection: builtin:exa
+  freshness: auto
+```
+
+| 顶层字段 | 类型 / 默认 | 含义 |
+| --- | --- | --- |
+| `version` | `2`；纯新配置可省略 | 显式标记当前配置格式；旧路由必须导入，不能只改版本绕过迁移 |
+| `defaultConnection` | 非空连接 ID；解析器不设默认 | 仅初始化没有持久选择的会话。安装补丁显式设为 `builtin:exa` |
+| `freshness` | `auto` / `fresh` / `realtime`；`auto` | 新会话默认实时性；旧记录缺少此字段时首次读取补入一次 |
+| `connections` | ID → 配置对象；空覆盖 | 内置连接的差异或完整自定义连接 |
+
+未设默认连接时，只有恰好一个本地可用连接才自动选中，否则保持未选择。不要依赖目录顺序。显式默认 ID 不会自动修复为其他连接；请确保它存在、未禁用且凭据可用。已有会话保存的连接（包括未选择）不随默认改变。
+
+## 内置供应商与访问方式
+
+四种结构化服务默认 `access: keyless`。保存个人 Key **不会**自动切换模式；必须显式改为 `api-key`。失败、限流、匿名访问拒绝均不会自动改用个人 Key、其他服务或其他协议。
+
+| ID | 免 Key 路径 | 个人 Key 路径 / 默认凭据引用 |
+| --- | --- | --- |
+| `builtin:exa` | `https://mcp.exa.ai/mcp`，工具 `web_search_exa` | `https://api.exa.ai/search`；`EXA_API_KEY` |
+| `builtin:firecrawl` | `https://api.firecrawl.dev/v2/search`，不发 Authorization | 同址 REST；`FIRECRAWL_API_KEY` |
+| `builtin:tavily` | `https://api.tavily.com/search`，`X-Tavily-Access-Mode: keyless` | 同址 REST；`TAVILY_API_KEY` |
+| `builtin:tinyfish` | `https://agent.tinyfish.ai/mcp`，`search`，`X-TinyFish-Access-Mode: keyless` | `https://api.search.tinyfish.ai`，GET；`TINYFISH_API_KEY` |
+| `builtin:session-model` | 不支持匿名；跟随当前实际 agent 模型 | `llm-pi-ai` 对应 provider 的显式 `apiKeyEnv` |
+
+免 Key 是上游公共访问能力，不是无限额度、服务可用性或永久免登录承诺。IP、地区、额度、服务策略均可能导致拒绝。设置页显示“已配置 / 免 Key”仅说明本地条件满足，不会发网络请求测试供应商。
+
+内置结构化连接只允许覆盖 `label`（非空）、`disabled`（布尔，默认 false）、`credentialRef`、`access`、`options`。不能改其 `kind`、`adapter`、`endpoint` 或添加任意请求字段。
+
+```yaml
+web-search-enhanced:
+  version: 2
+  connections:
+    builtin:exa:
+      access: api-key
+      credentialRef: EXA_API_KEY
+      options:
+        type: fast
+    builtin:firecrawl:
+      disabled: true
+```
+
+### 结构化 options 白名单
+
+| adapter | 字段 | 接受值 |
+| --- | --- | --- |
+| Firecrawl | `country` | 两个英文字母 |
+| Firecrawl | `location` | 1–200 字符，不含 U+0000–U+001F |
+| Firecrawl | `safe` | 布尔 |
+| Exa | `type` | `auto`、`fast`、`instant`；仅个人 Key |
+| Tavily | `search_depth` | `basic`、`advanced`、`fast`、`ultra-fast` |
+| Tavily | `topic` | `general`、`news`、`finance` |
+| Tinyfish | `location` | 两个英文字母 |
+| Tinyfish | `language` | 2–3 个英文字母，可带连字符及 2–4 个字母后缀 |
+| Tinyfish | `purpose` | 1–2000 字符，不含 U+0000–U+001F |
+| Tinyfish | `domain_type` | `web`、`news`；个人 Key 另可用 `research_paper` |
+
+Exa 免 Key 仅接收查询与数量，非空 options 会被拒绝。Tinyfish 免 Key 查询上限 2000 字符，不能使用 `research_paper`。Firecrawl 查询上限 500 字符，其他结构化 REST 查询上限 10000 字符。数量由工具请求和适配器控制，不能在 options 设置 `limit`、`numResults`、分页或缓存字段。Tavily 请求数量上限 20，Firecrawl/Exa REST 上限 100；Tinyfish 使用单页结果，本地按请求数量裁剪。不自动重试或翻页。
+
+## 内容实时性
+
+实时性指**内容缓存 / 抓取偏好**，不是发布日期过滤，也不证明页面内容确实最新。它在当前会话持久保存，切换连接保留，fork 复制父会话当前值后独立。连接和实时性共用 revision，多标签页冲突需刷新后重试。请求开始后修改设置不改变该请求已冻结的路由与偏好。
+
+| 模式 | Firecrawl（两种访问方式） | Exa 个人 Key | Exa 免 Key、Tavily、Tinyfish、模型 |
+| --- | --- | --- | --- |
+| `auto` 自动 | 默认搜索策略 | 默认内容策略 | 默认行为 |
+| `fresh` 优先新鲜 | `scrapeOptions.maxAge=86400000` 毫秒 | `contents.maxAgeHours=24` 小时 | 忽略该偏好，不猜测上游参数 |
+| `realtime` 优先实时 | `scrapeOptions.maxAge=0` | `contents.maxAgeHours=0` | 同上 |
+
+Firecrawl 非 auto 会请求内联 Markdown 正文，正文缺失时不拿旧搜索摘要冒充新抓取内容。内联抓取可能增加延迟和额度消耗。内部诊断使用 default/applied/ignored/partial，但 `freshnessVerified` 始终为 false；诊断不是结果新鲜度认证或公开 UI 接口。
+
+## 凭据
+
+个人 Key 由 **DSH Credentials** 保存和解析。设置只写引用名称；引用须匹配 `[A-Za-z_][A-Za-z0-9_]*`。不要把 Key 写进 YAML、options、URL 或日志。匿名路径不解析个人凭据，也不发送个人认证头。Key 的撤销在实际执行时生效，因为请求快照冻结引用而非秘密值。
+
+在设置中选择或填写引用并保存 Key；只读凭据由其宿主配置来源管理。空输入不是删除凭据命令。引用名称正确、已配置仍不保证供应商授权或额度有效。无独立密钥文件管理、订阅登录抓取或隐式认证猜测。
+
+## 自定义结构化连接
+
+ID 格式为 `custom:` 加 1–100 个字符，首字符为字母或数字，后续可含字母、数字、点、下划线、连字符。必需 `label`、`kind: structured`、已支持的 `adapter`、`credentialRef`；可用 `disabled`、`endpoint`、`trustedEndpoint`、`options`。省略 endpoint 使用该 adapter 的官方 REST 地址；不同地址必须显式 `trustedEndpoint: true`。自定义结构化连接**只用个人 Key**，不接受 `access`、任意 headers 或任意 body。
+
+```yaml
+web-search-enhanced:
+  version: 2
+  connections:
+    custom:team-tavily:
+      label: 团队 Tavily
+      kind: structured
+      adapter: tavily
+      credentialRef: TEAM_TAVILY_API_KEY
+      options:
+        topic: news
+```
+
+自定义地址必须为绝对 HTTP(S) URL，不含内嵌账号密码、查询或片段。信任标志意味着你同意向该地址发送搜索词与所选凭据，不是自动安全检测；建议使用 HTTPS。
+
+## 固定搜索模型
+
+自定义模型必须为 `kind: model`，含 `label`、`trustedEndpoint: true` 和完整 `binding`。`disabled` 默认 false，`options` 默认空对象。
+
+```yaml
+web-search-enhanced:
+  version: 2
+  connections:
+    custom:search-model:
+      label: 专用搜索模型
+      kind: model
+      trustedEndpoint: true
+      binding:
+        mode: fixed
+        protocol: openai-responses
+        model: YOUR_SEARCH_CAPABLE_MODEL
+        baseURL: https://api.openai.com/v1
+        credentialRef: SEARCH_MODEL_API_KEY
+      options:
+        maxTokens: 4096
+        searchContextSize: medium
+```
+
+`model` 必须非空；示例占位值需替换为实际支持服务端搜索的模型。`baseURL` 遵守上述 URL 约束。支持协议和路径：
+
+| protocol | 请求路径 | 默认 toolIdentifier |
+| --- | --- | --- |
+| `anthropic-messages` | 规范化为 `/v1/messages` | `web_search_20260209` |
+| `openai-responses` | 追加 `/responses` | `web_search` |
+| `openai-chat-completions` | 追加 `/chat/completions` | `web_search_options` |
+
+已有对应完整后缀不会重复追加；OpenAI 基地址需要的 `/v1` 由用户提供。协议兼容不等于该模型 / 代理实现了搜索工具。
+
+| 模型 options | 默认 / 验证 | 生效范围 |
+| --- | --- | --- |
+| `apiVersion` | `2023-06-01`，非空字符串 | Anthropic 版本头 |
+| `toolIdentifier` | 见上表；字母开头，后接字母、数字、`_ . : -`，总长不超过 128 | Anthropic 工具类型、Responses 工具类型、Chat vendor 字段 |
+| `maxTokens` | 4096，正整数 | 三种协议输出预算 |
+| `maxUses` | 5，正整数 | Anthropic `max_uses` |
+| `chatSearchMode` | `search-model` 或 `vendor-options`；前者默认 | Chat 前者固定发 `web_search_options`，后者以 toolIdentifier 为字段名 |
+| `searchContextSize` | 未设置；可选 `low` / `medium` / `high` | Responses / Chat 搜索上下文 |
+
+这些是白名单而非任意参数透传。模型路径可能返回回答文本及引用；结构化路径只返回来源，不生成额外摘要。
+
+## 跟随会话模型
+
+`builtin:session-model` 仅允许 `disabled` 和 `optionsByProtocol` 覆盖，不能重命名或设置固定 binding。每个协议单独保存上述模型 options：
+
+```yaml
+web-search-enhanced:
+  version: 2
+  defaultConnection: builtin:session-model
+  connections:
+    builtin:session-model:
+      optionsByProtocol:
+        anthropic-messages:
+          maxUses: 3
+        openai-responses:
+          searchContextSize: low
+```
+
+实际 agent 请求头必须有完整 provider/model；仅无请求头时才读同一 agent options，不混拼不完整字段。插件读取 `llm-pi-ai.providers[provider]` 的 `api`、`baseURL`、`apiKeyEnv`；协议也识别宿主的 `openai-completions` 为 Chat Completions。只在缺省协议 / 地址时尝试只读模型目录补齐。
+
+必须有显式 `apiKeyEnv` 并能通过 Credentials 解析。当前不支持 OAuth、订阅认证、内联 apiKey/auth、非空自定义 headers，或 model 级路由覆盖。宿主能对话不代表此连接可搜索；不支持时改选结构化服务或显式固定模型，不会自动 fallback。
+
+## 故障与恢复
+
+| 错误 / 现象 | 处理 |
+| --- | --- |
+| `WEB_SEARCH_NOT_SELECTED` | 在当前会话显式选择连接，或设置新会话默认后创建新会话 |
+| `WEB_SEARCH_CONNECTION_INVALID` | 已保存连接被删除 / 禁用；恢复它或重新选择，插件不会偷换 |
+| `WEB_PROVIDER_CREDENTIAL_MISSING` | 检查当前模式、引用和 DSH Credentials；保存 Key 后仍须显式选个人 Key 模式 |
+| `WEB_KEYLESS_UNAVAILABLE` | 当前网络被上游拒绝匿名访问；等待或手动选个人 Key / 其他连接，不绕过上游限制 |
+| `WEB_PROVIDER_AUTH_ERROR` | 个人凭据鉴权失败，检查 Key 与 endpoint 的归属 |
+| `WEB_PROVIDER_ACCESS_ERROR` | 上游访问 / 计费限制（如 HTTP 402），检查账户 |
+| `WEB_PROVIDER_RATE_LIMITED` | HTTP 429 等限流；等待并检查额度，不自动重试或转付费 |
+| `WEB_SEARCH_FOLLOW_UNSUPPORTED` | 检查 provider 协议、地址、显式 apiKeyEnv、模型能力；必要时用固定连接 |
+| `WEB_SEARCH_MIGRATION_REQUIRED` | 按升级指南显式导入旧配置 |
+| `WEB_SEARCH_CONFIG_INVALID` | 检查未知字段、options、信任确认及引用格式；禁用连接也必须配置合法 |
+| `WEB_SEARCH_STORAGE_UNAVAILABLE` | 检查 DSH storage-domain 及持久后端；恢复后下一请求会重试 |
+| `WEB_SEARCH_CONTEXT_UNAVAILABLE` | 缺少真实请求执行上下文；发起新的模型请求，不在工具参数伪造 Session |
+| `WEB_PROVIDER_TIMEOUT` / `WEB_ABORTED` | 检查网络或取消状态；网络操作期限为 90 秒 |
+| `WEB_PROVIDER_ERROR` | 网络、格式或上游工具失败；错误刻意不返回上游 body / cause |
+| 多窗口保存冲突 | 刷新当前选择 / 设置后重做修改，避免覆盖别处更新 |
+
+网络传输拒绝重定向，响应上限 2 MiB。UI 不展示不可用连接，但不会据此修改已保存选择。空白会话首消息前没有独立搜索选择器，由新会话默认处理。插件不接管 `web_fetch`。源码依据见 [config.ts](../src/config.ts)、[service.ts](../src/search/service.ts)、[structured.ts](../src/adapters/structured.ts)、[protocols.ts](../src/protocols.ts)。