dsh-web-search-enhanced

dsh-web-search-enhanced 是为 DeepSeek Harness (DSH) 量身打造的增强型多协议联网搜索插件。

🌟 核心价值：直接使用模型供应商自身提供的联网搜索

传统智能体方案通常需要额外购买和配置第三方搜索引擎 API（如 Tavily、Bing Search API、Google CSE 等），不仅流程繁琐，还带来了额外的账单与调用延迟。

dsh-web-search-enhanced 让你可以直接调用模型供应商（如 DeepSeek、Anthropic Claude、OpenAI 等）自身原生集成的服务端联网搜索功能：

• 🚫 告别额外依赖：无需申请或维护独立的搜索引擎 API Key，直接复用你现有的大模型 API 凭据。
• 💰 极致降低成本：依托各大模型供应商原生提供的高性价比或免费搜索能力，大幅节约外部检索成本。
• 🎯 深度原生优化：充分利用厂商针对大模型特别调优的网页抓取、实时索引、正文解析与引用标注体系，检索质量更高、响应更迅速。
• 🔄 保持原生体验：模型端保持原生 web_search 工具签名与交互体验不变，无缝支持 Anthropic Messages、OpenAI Responses API 及 OpenAI Chat Completions 三大主流上游协议，并提供 Web 可视化配置面板。

✨ 核心特性

• ⚡ 直接利用模型厂商内置搜索：原生调用各大模型供应商自身的服务端搜索（如 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-v4-flash、claude-3-7-sonnet、gpt-4o 等），主对话与搜索模型分工明确。
  • 智能平滑兜底 (fallbackModel)：当跟随模式遇到未知或未配置的模型路由时，自动降级至备用模型，确保搜索永不断流。
• 🖥️ Web 控制台可视化配置：深度集成 DSH Web 端「设置 → 插件 → Web Search Enhanced」，支持中英文双语、即时表单校验、草稿暂存、一键保存与重置。
• 🔒 凭据安全与隐私保护：通过 DSH 原生 Credentials 机制安全写入并保管 API Key，公开设置文档绝不保存明文密钥；请求强制阻断携带凭据的恶意 HTTP 重定向。
• 🎯 开箱即用无感集成：上游响应中的来源和引用会自动归一化为标准的 DSH WebSearchResult；主模型提示词和工作流无需任何改动。

📦 快速安装

插件已正式发布至 npmjs，使用 DSH CLI 即可一键安装到 web Profile：

# 安装插件至 web profile
dsh plugin --profile web add dsh-web-search-enhanced

安装完成后，重启 dsh web 服务即可生效：

# 启动或重启 DSH Web 服务
dsh web

💡 提示：安装后，插件随附的 cordis.patch.yml 会自动将搜索提供方指向 enhanced-search，并禁用原生默认搜索提供方。

🚀 快速上手与配置

方式一：Web 界面可视化配置（推荐）

1. 打开 DeepSeek Harness Web 界面（默认 http://127.0.0.1:3080）。
2. 点击左侧/顶部导航栏的 设置 (Settings) → 插件 (Plugins)。
3. 找到 Web Search Enhanced (插件配置) 卡片。
4. 根据需要选择模型路由、API 协议、接口地址 (Base URL) 与 模型标识 (Model ID)。
5. 在 API Key 输入框中输入对应的模型供应商 API 密钥（输入后仅用于安全保存，保存成功后输入框自动清空，不留明文痕迹）。
6. 点击 保存 (Save) 即可实时生效，无需重启！

方式二：环境变量与配置文件配置

如果你使用 Headless 模式或希望通过环境配置初始化：

1. 设置 API Key 环境变量（默认变量名为 WEB_SEARCH_ENHANCED_API）：

   export WEB_SEARCH_ENHANCED_API="sk-your-api-key-here"
   

2. 在 cordis.yml 中声明配置（可选）：

   - id: web-search-enhanced
     name: dsh-web-search-enhanced
     config:
       modelMode: configured
       protocol: anthropic-messages
       baseURL: https://api.deepseek.com/anthropic/v1
       model: deepseek-v4-flash
       apiKeyEnv: WEB_SEARCH_ENHANCED_API
       maxTokens: 4096
   

💡 常用场景配置示例

你可以直接参考以下常见场景的配置参数，轻松接入各厂商自身提供的原生搜索功能：

1. DeepSeek 官方搜索（默认推荐）

使用 DeepSeek 官方兼容 Anthropic 协议的服务端搜索，速度快且成本极低：

• 模型路由 (modelMode): 固定配置 (configured)
• API 协议 (protocol): Anthropic Messages v1
• 接口地址 (baseURL): https://api.deepseek.com/anthropic/v1
• 模型标识 (model): deepseek-v4-flash
• API Key: 填入你的 DeepSeek API Key

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

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

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

5. 跟随当前会话模型（自动继承厂商搜索）

让搜索自动使用当前 Agent 会话正在对话的模型供应商与协议：

• 模型路由 (modelMode): 当前会话模型 (current-session)
• 兜底搜索模型 (fallbackModel): deepseek-v4-flash（当当前模型不支持搜索协议或未解析到凭据时自动平滑回退）
• API 协议 / 接口地址 / API Key: 自动跟随当前会话的 LLM 路由配置

⚙️ 详细配置参数表

🔒 凭据安全与隐私设计

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)

dsh plugin --profile web remove dsh-web-search-enhanced

🛠️ 本地开发与调试

如果你希望基于本项目进行二次开发或贡献代码：

# 克隆仓库并安装依赖
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。

📄 开源许可证

本项目基于 MIT License 开源。