dsh-web-search-enhanced 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.md +177 -50
- package/docs/configuration.zh-CN.md +20 -4
- package/docs/design-v2.converged.zh-CN.md +6 -4
- package/docs/migration.zh-CN.md +17 -14
- package/docs/v2-implementation.zh-CN.md +3 -3
- package/lib/client.js +6879 -561
- package/lib/client.js.map +1 -1
- package/lib/index.js +7053 -28
- package/lib/types/adapters/structured.d.ts +1 -1
- package/lib/types/catalog.d.ts +17 -1
- package/lib/types/client/SearchConnectionSelector.d.ts +1 -0
- package/lib/types/client/V2Settings.d.ts +4 -3
- package/lib/types/client/v2-settings.css.d.ts +1 -1
- package/lib/types/dsh/bridge.d.ts +9 -2
- package/lib/types/dsh/model-pairing-store.d.ts +31 -0
- package/lib/types/dsh/session-selection.d.ts +1 -0
- package/lib/types/index.d.ts +2 -2
- package/lib/types/migration.d.ts +2 -0
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,32 @@
|
|
|
2
2
|
|
|
3
3
|
记录 `dsh-web-search-enhanced` 的用户可见变化。历史条目描述对应版本，不代表当前行为。
|
|
4
4
|
|
|
5
|
+
## [0.1.2] - 2026-09-22
|
|
6
|
+
|
|
7
|
+
### 新增与修复
|
|
8
|
+
|
|
9
|
+
- 新增 OpenAlex 与 Semantic Scholar 学术检索连接，支持摘要、作者、引用计数与开放获取链接。
|
|
10
|
+
- 修复 OpenAlex 个人 API Key 认证：使用 api_key 查询参数，免 Key 模式不发送凭据；支持配置 mailto 联系邮箱。
|
|
11
|
+
- 模型切换时，尚未手动修改选择的非 fork 会话（revision 为 0）动态更新搜索连接；客户端订阅模型选择变化。
|
|
12
|
+
- 内置及自定义连接的 Key、OpenAlex 邮箱和已有连接编辑统一在对应行下展开，避免共享凭据引用导致重复展开。
|
|
13
|
+
- 移除独立迁移脚本和手动导入入口，仅保留启动自动迁移；统一旧字段检测，验证转换结果后顺序写入凭据与设置，失败时保留旧配置并输出脱敏提示。
|
|
14
|
+
- 更新配置、升级指南及安装示例，补充认证、稀疏旧配置迁移与设置渲染回归测试。
|
|
15
|
+
|
|
16
|
+
### 升级注意
|
|
17
|
+
|
|
18
|
+
- 升级前自行备份 settings.yaml；重新加载插件或重启 DSH 后刷新 Web 页面。
|
|
19
|
+
- 不再提供 pnpm run migrate 命令。自动迁移失败时，检查宿主日志、旧配置和 Credentials 写权限后重启插件。
|
|
20
|
+
- 保存 Key 不会自动切换访问模式；个人 Key 仍需显式选择。
|
|
21
|
+
|
|
22
|
+
## [0.1.1] - 2026-09-21
|
|
23
|
+
|
|
24
|
+
### 新增与优化
|
|
25
|
+
|
|
26
|
+
- **模型与搜索连接智能记忆联动**：引入 `ModelPairingStore` 状态缓存机制（持久化于 `$DSH_HOME/cache/web-search-enhanced/model-connections.json`），实现不同对话模型与其最近一次选择的搜索连接自动绑定与恢复；新会话自动恢复该模型最近一次使用的搜索连接偏好，未记录模型平滑回退至全局默认配置。
|
|
27
|
+
- **自定义连接配置全面采用 DSH 原生 YAML 规范**：设置页自定义连接编辑器升级为 DSH 原生 YAML 块级缩进格式（替代原 JSON 格式），大幅提升阅读与手动编辑体验，并保持完全向后兼容。
|
|
28
|
+
- **配置自动迁移与静默自愈**：该版本提供命令行配置迁移脚本及启动时自动迁移；独立脚本在 0.1.2 中移除。
|
|
29
|
+
- **文档与应用市场体验优化**：优化 README 用户安装与上手指引，补充更友好的安装与使用说明及截图清单 `screenshots.json`。
|
|
30
|
+
|
|
5
31
|
## [0.1.0] - 2026-09-21 🎉
|
|
6
32
|
|
|
7
33
|
### 全新搜索连接架构
|
package/README.md
CHANGED
|
@@ -1,92 +1,219 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
|
|
2
4
|
|
|
3
5
|
# Web Search Enhanced
|
|
4
6
|
|
|
5
|
-
<div align="center">
|
|
6
|
-
|
|
7
7
|
**聊天用喜欢的模型，搜索用合适的连接。**
|
|
8
8
|
|
|
9
|
-
为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
|
|
9
|
+
为 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 打造的增强型联网搜索插件。开箱即用免 Key 起步，支持在每段对话中自由搭配最适合的搜索引擎与实时性偏好。
|
|
10
10
|
|
|
11
11
|
[](https://github.com/Yurzi/dsh-web-search-enhanced/releases)
|
|
12
|
-
[](LICENSE)
|
|
13
13
|
[](package.json)
|
|
14
|
+
[](package.json)
|
|
14
15
|
|
|
15
|
-
[
|
|
16
|
+
[🚀 快速上手](#-快速上手) · [✨ 核心特性](#-核心特性) · [🔍 搜索引擎推荐](#-选哪种搜索服务) · [⚙️ 进阶配置](#️-进阶配置与个人-key) · [❓ 常见问题](#-常见问题-faq) · [📖 详细文档](#-想了解更多)
|
|
16
17
|
|
|
17
18
|
</div>
|
|
18
19
|
|
|
19
|
-
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## ✨ 核心特性
|
|
23
|
+
|
|
24
|
+
- 🐋 **开箱即用，免 Key 起步**：无需繁琐申请 API Key，安装默认选用 Exa 免 Key 检索，同时内置 Firecrawl、Tavily 与 Tinyfish，安装即刻体验联网搜索。
|
|
25
|
+
- 🔀 **搜索与聊天自由解耦**：模型聊天与联网搜索互不干扰！无论你当前在与 Claude、GPT 还是本地模型对话，都可以随时为当前会话指定最擅长该领域的搜索引擎。
|
|
26
|
+
- 💬 **会话级记忆与独立分支**：每段对话都会记住各自选用的搜索服务与实时性偏好；Fork 分支对话互不冲突，各自独立调整。
|
|
27
|
+
- ⚡ **内容实时性自由掌控**：在输入区一键切换「自动 / 优先新鲜 / 优先实时」，随心平衡网页检索速度与最新内容抓取。
|
|
28
|
+
- 🔐 **安全优雅的凭据隔离**：深度接入 DSH 原生 Credentials 体系，敏感 API Key 安全留存于凭据管理器中，绝不污染项目配置文件。
|
|
29
|
+
- 🎨 **无缝融入原生界面**：聊天输入框随手弹出的快捷切换胶囊 + 直观清爽的插件设置面板，自适应浅色/深色主题与移动端窄屏。
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 📸 界面预览
|
|
34
|
+
|
|
35
|
+
### 💬 会话快捷选择器（在聊天框随手切换）
|
|
36
|
+
|
|
37
|
+
> 在输入框工具栏轻轻一点，即可随时为当前会话切换搜索引擎与内容实时性，无需跳转设置，不打断对话灵感。
|
|
38
|
+
|
|
39
|
+
<p align="center">
|
|
40
|
+
<img src="docs/assets/search-picker-desktop.png" alt="会话快捷选择器" width="850" />
|
|
41
|
+
</p>
|
|
42
|
+
<p align="center">
|
|
43
|
+
<sub>切换视图：<b>桌面浅色（上图）</b> · <a href="docs/assets/search-picker-dark.png">桌面深色</a> · <a href="docs/assets/search-picker-narrow.png">移动窄屏</a></sub>
|
|
44
|
+
</p>
|
|
45
|
+
|
|
46
|
+
### ⚙️ 统一插件设置中心
|
|
20
47
|
|
|
21
|
-
|
|
22
|
-
- **🔀 搜索与聊天分开选**：会话内切换搜索服务、专用搜索模型，或跟随当前会话模型，不改变聊天模型。
|
|
23
|
-
- **🕒 每段对话记住偏好**：搜索连接和内容实时性独立持久化，fork 后各自调整。
|
|
24
|
-
- **🔐 凭据不混进配置**：API Key 交给 DSH Credentials；免 Key 与个人 Key 显式切换，不偷偷回退。
|
|
25
|
-
- **🎛️ 原生界面，轻巧配置**：输入区快速切换，设置页管理连接，支持深浅色主题与窄屏。
|
|
48
|
+
> 集中管理默认连接、免 Key / 个人 Key 访问模式、凭据引用与自定义模型端点。
|
|
26
49
|
|
|
27
|
-
>
|
|
50
|
+
<p align="center">
|
|
51
|
+
<img src="docs/assets/settings-desktop.png" alt="插件设置中心" width="850" />
|
|
52
|
+
</p>
|
|
53
|
+
<p align="center">
|
|
54
|
+
<sub>切换视图：<b>桌面浅色（上图）</b> · <a href="docs/assets/settings-dark.png">桌面深色</a> · <a href="docs/assets/settings-mobile.png">移动窄屏</a></sub>
|
|
55
|
+
</p>
|
|
28
56
|
|
|
29
|
-
|
|
57
|
+
---
|
|
30
58
|
|
|
31
|
-
|
|
59
|
+
## 🚀 快速上手
|
|
32
60
|
|
|
33
|
-
|
|
61
|
+
### 环境要求
|
|
62
|
+
|
|
63
|
+
- **DeepSeek Harness**：≥ `0.1.5-rc.2`
|
|
64
|
+
- **Node.js**：`^22.19.0 || >=24.0.0`
|
|
65
|
+
|
|
66
|
+
### 步骤 1：安装插件
|
|
67
|
+
|
|
68
|
+
**方式 A：通过 GitHub Release 离线包安装（推荐）**
|
|
69
|
+
|
|
70
|
+
从 [v0.1.2 Release](https://github.com/Yurzi/dsh-web-search-enhanced/releases/tag/v0.1.2) 下载预构建包 `dsh-web-search-enhanced-0.1.2.tgz`，执行绝对路径安装命令：
|
|
34
71
|
|
|
35
72
|
```sh
|
|
36
|
-
dsh plugin --profile web add /
|
|
73
|
+
dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.2.tgz
|
|
37
74
|
```
|
|
38
75
|
|
|
39
|
-
npm
|
|
76
|
+
**方式 B：通过 npm 在线安装**
|
|
77
|
+
|
|
78
|
+
在版本已发布到 npm 仓库后，也可直接安装：
|
|
40
79
|
|
|
41
80
|
```sh
|
|
42
|
-
dsh plugin --profile web add dsh-web-search-enhanced@0.1.
|
|
81
|
+
dsh plugin --profile web add dsh-web-search-enhanced@0.1.2
|
|
43
82
|
```
|
|
44
83
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
84
|
+
### 步骤 2：生效与刷新
|
|
85
|
+
|
|
86
|
+
1. 重载插件或重启 DSH 服务端。
|
|
87
|
+
2. 刷新浏览器 Web 页面，确保前端客户端组件与后端服务同步更新。
|
|
88
|
+
|
|
89
|
+
### 步骤 3：立即提问体验
|
|
90
|
+
|
|
91
|
+
新建一段会话，输入框上方默认已为你准备好 **Exa · 免 Key** 搜索连接。直接向 AI 提问：
|
|
92
|
+
|
|
93
|
+
> 💡 **提问示例**：“搜索最近的 TypeScript 发布说明，总结最重要的几个变化并附上引用来源。”
|
|
94
|
+
|
|
95
|
+
AI 会自动通过 Web Search Enhanced 检索最新网络资料，并附带网页来源回答你！
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## 🔍 选哪种搜索服务？
|
|
100
|
+
|
|
101
|
+
Web Search Enhanced 内置了多种主流检索服务与模型搜索能力，你可以按需随心选择：
|
|
102
|
+
|
|
103
|
+
| 搜索连接 | 推荐场景 | 访问模式 | 特点说明 |
|
|
104
|
+
| :--------------- | :------------------------------ | :----------------------------- | :-------------------------------------------------------------------------------- |
|
|
105
|
+
| **Exa** _(默认)_ | 💻 开发者、技术文档、论文研究 | 免 Key (开箱即用) / 个人 Key | 强大的语义神经检索，对编程与深度学术内容理解极准；个人 Key 支持配置搜索类型 |
|
|
106
|
+
| **Firecrawl** | 📰 新闻资讯、深度文章抓取 | 免 Key (开箱即用) / 个人 Key | 擅长清洗和抓取干净的 Markdown 网页正文；支持优先获取最新页面 |
|
|
107
|
+
| **Tavily** | 🔍 事实核查、行业调研、综合检索 | 免 Key (开箱即用) / 个人 Key | 专为大语言模型打造的搜索服务，支持自定义搜索深度（快速/进阶）与新闻主题 |
|
|
108
|
+
| **Tinyfish** | 🌍 跨语言搜索、地域本地化资讯 | 免 Key (开箱即用) / 个人 Key | 支持按国家地区、特定语言和搜索用途精准过滤检索范围 |
|
|
109
|
+
| **OpenAlex** | 📚 学术论文、开源文献、引用检索 | 免 Key (开箱即用) / 个人 Key | 全球开放学术图谱，自动解析摘要倒排索引、作者、OA PDF 与引用数；支持 mailto 礼貌池 |
|
|
110
|
+
| **Semantic Scholar** | 🔬 深度学术、论文速读、AI 论文 | 需配置个人 API Key | 专为学术科研打造，内置 TL;DR 速读总结、引用计数与 ArXiv/OA 论文直链 |
|
|
111
|
+
| **专用搜索模型** | 🤖 统一使用特定支持联网的模型 | Anthropic / OpenAI 协议 | 通过服务端搜索能力（如 OpenAI Responses、Anthropic Messages）直接返回带引用的回答 |
|
|
112
|
+
| **跟随会话模型** | 🔄 懒人模式，搜索使用当前模型 | 需配置 provider 的 `apiKeyEnv` | 自动沿用当前会话选定的模型与端点发起联网搜索 |
|
|
113
|
+
|
|
114
|
+
> 💡 **关于免 Key 访问**：
|
|
115
|
+
> 免 Key 模式走的是上游提供的公共接入通道，省去了新用户申请注册 API Key 的繁琐步骤。
|
|
116
|
+
> 公共通道可能因高峰期并发或网络 IP 受限；如遇限流，可以在输入框临时切换到其他免 Key 连接（如 Tavily / Firecrawl），或者在设置中配置自己的专属 API Key。
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## ⏱️ 内容实时性说明
|
|
121
|
+
|
|
122
|
+
在聊天输入框的搜索菜单中，你可以为当前会话设置**内容实时性**：
|
|
123
|
+
|
|
124
|
+
- **自动 (Auto)**：采用搜索引擎默认的缓存与检索策略，响应快速。
|
|
125
|
+
- **优先新鲜 (Fresh)**：优先使用不超过 24 小时的较新网页缓存（Firecrawl / Exa 个人 Key 支持）。
|
|
126
|
+
- **优先实时 (Realtime)**：发起重新爬取，获取页面当前时刻的最新内容（适合突发新闻、最新行情等时效极高的场景）。
|
|
127
|
+
|
|
128
|
+
_注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不支持实时性控制的连接，系统会自动保留偏好并优雅回退至默认检索。_
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## ⚙️ 进阶配置与个人 Key
|
|
133
|
+
|
|
134
|
+
如果你拥有各平台专属的 API Key，或想要自定义专用搜索模型，只需打开 **设置 → 插件 → Web Search Enhanced**：
|
|
135
|
+
|
|
136
|
+
1. **绑定个人 API Key**：
|
|
137
|
+
- 找到目标连接（例如 Firecrawl 或 Tavily）。
|
|
138
|
+
- 点击目标连接行上的“配置 Key”，在行内展开的输入框中填写 API Key 并保存（将自动存入 DSH Credentials，安全可靠）。
|
|
139
|
+
- 将“访问方式”从“免 Key”切换为“个人 Key”。OpenAlex 的个人 Key 会按官方要求通过 api_key 查询参数发送。
|
|
140
|
+
2. **配置 OpenAlex 礼貌邮箱（可选）**：
|
|
141
|
+
- 在 OpenAlex 连接行点击“礼貌邮箱”，行内填写联系邮箱；清空后保存即可恢复默认公共标识。
|
|
142
|
+
3. **设置新会话默认连接**：
|
|
143
|
+
- 在“新会话默认连接”下拉框中选择你最常用的引擎，新创建的对话将自动应用该偏好。
|
|
144
|
+
4. **添加自定义模型或端点**：
|
|
145
|
+
- 支持添加任意兼容 OpenAI 或 Anthropic 服务端搜索协议的模型端点。
|
|
146
|
+
|
|
147
|
+
完整配置语法与高级参数白名单，请参阅 📖 [详细配置指南](docs/configuration.zh-CN.md)。
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## ❓ 常见问题 (FAQ)
|
|
152
|
+
|
|
153
|
+
<details>
|
|
154
|
+
<summary><b>Q1: 搜索时提示 <code>WEB_SEARCH_NOT_SELECTED</code>？</b></summary>
|
|
155
|
+
|
|
156
|
+
**原因**：当前会话没有选定任何搜索连接。
|
|
157
|
+
**解决办法**：在输入框右侧工具栏点击搜索图标/胶囊，在弹出的菜单中勾选任意一个搜索服务（如 Exa 或 Firecrawl）；或者在插件设置中为“新会话默认连接”指定一个默认引擎。
|
|
158
|
+
</details>
|
|
159
|
+
|
|
160
|
+
<details>
|
|
161
|
+
<summary><b>Q2: 免 Key 搜索突然提示失败或限流（<code>WEB_KEYLESS_UNAVAILABLE</code> / <code>WEB_PROVIDER_RATE_LIMITED</code>）？</b></summary>
|
|
162
|
+
|
|
163
|
+
**原因**：免 Key 服务基于上游公共节点，高峰时段或特定网络 IP 可能触发临时频率限制。
|
|
164
|
+
**解决办法**：
|
|
165
|
+
|
|
166
|
+
1. 在会话输入框中快速切换到另一个免 Key 引擎（如从 Exa 换到 Firecrawl 或 Tavily）。
|
|
167
|
+
2. 在设置中为该引擎填入你自己的官方 API Key，并将访问方式切换为“个人 Key”。
|
|
168
|
+
|
|
169
|
+
</details>
|
|
170
|
+
|
|
171
|
+
<details>
|
|
172
|
+
<summary><b>Q3: 我在设置中填了 API Key，为什么搜索依然是免 Key 模式？</b></summary>
|
|
48
173
|
|
|
49
|
-
|
|
174
|
+
**原因**：为了防止意外产生付费额度消耗，插件设计了“显式切换保护”——保存 Key 并不会自动切换通道。
|
|
175
|
+
**解决办法**：在设置页该连接的卡片上，将下拉选项由 **免 Key** 手动切换为 **个人 Key (API Key)** 即可。
|
|
176
|
+
</details>
|
|
50
177
|
|
|
51
|
-
|
|
178
|
+
<details>
|
|
179
|
+
<summary><b>Q4: 我在会话中修改了搜索引擎，会影响其他会话吗？Fork 对话呢？</b></summary>
|
|
52
180
|
|
|
53
|
-
|
|
54
|
-
| --- | --- | --- |
|
|
55
|
-
| **Exa** | 默认开箱尝试；个人 Key 可配置搜索类型 | 免 Key MCP / API Key REST |
|
|
56
|
-
| **Firecrawl** | 搜索并按需获取更鲜的网页正文 | 免 Key / API Key REST |
|
|
57
|
-
| **Tavily** | 配置搜索深度与主题 | 免 Key / API Key REST |
|
|
58
|
-
| **Tinyfish** | 按地区、语言和用途搜索 | 免 Key MCP / API Key REST |
|
|
59
|
-
| **专用模型** | 固定一个支持服务端搜索的模型 | Anthropic Messages / OpenAI Responses / Chat Completions |
|
|
60
|
-
| **跟随会话模型** | 使用当前会话的 provider 和 model | 需显式 `apiKeyEnv`；不接管订阅或 OAuth 登录 |
|
|
181
|
+
**不会**。Web Search Enhanced 是完全**会话隔离**的：
|
|
61
182
|
|
|
62
|
-
|
|
183
|
+
- 修改当前会话的搜索连接，不会影响已经存在的其他会话。
|
|
184
|
+
- Fork（分支）出的新会话会继承分支那一刻的搜索设置，之后两者独立变更，互不干扰。
|
|
63
185
|
|
|
64
|
-
|
|
186
|
+
</details>
|
|
65
187
|
|
|
66
|
-
|
|
188
|
+
<details>
|
|
189
|
+
<summary><b>Q5: 如何从 0.0.x 旧版本平滑升级？</b></summary>
|
|
67
190
|
|
|
68
|
-
|
|
191
|
+
升级后重新加载插件或重启 DSH，插件会在启动时自动检测并迁移旧版全局模型配置；迁移成功后映射为新版连接配置。若出现迁移错误，请检查宿主日志、DSH Credentials 权限和旧配置，再重启插件。详细注意事项请参阅 📖 [升级指南](docs/migration.zh-CN.md)。
|
|
192
|
+
</details>
|
|
69
193
|
|
|
70
|
-
|
|
194
|
+
---
|
|
71
195
|
|
|
72
|
-
|
|
196
|
+
## 📖 想了解更多？
|
|
73
197
|
|
|
74
|
-
|
|
198
|
+
| 文档 | 适合谁读 | 主要内容 |
|
|
199
|
+
| :------------------------------------------------------- | :------------------ | :---------------------------------------------------------------- |
|
|
200
|
+
| 📘 **[配置指南](docs/configuration.zh-CN.md)** | 所有用户 / 进阶用户 | 完整参数列表、凭据机制、高级 options 白名单、自定义端点与排错字典 |
|
|
201
|
+
| 📙 **[升级指南](docs/migration.zh-CN.md)** | 从旧版升级的老用户 | 0.1.0 架构变化、旧版导入指引、升级踩坑预防 |
|
|
202
|
+
| 📗 **[架构设计说明](docs/design-v2.converged.zh-CN.md)** | 开发者 / 架构爱好者 | 会话状态隔离、请求快照机制、多适配器与安全性设计 |
|
|
203
|
+
| 🛠️ **[开发与验证文档](docs/v2-implementation.zh-CN.md)** | 插件二次开发者 | 本地构建、单元测试、浏览器环境验证与打包发布 |
|
|
204
|
+
| 📝 **[更新日志](CHANGELOG.md)** | 所有人 | 版本演进记录与历史变更 |
|
|
75
205
|
|
|
76
|
-
|
|
206
|
+
---
|
|
77
207
|
|
|
78
|
-
|
|
79
|
-
| --- | --- |
|
|
80
|
-
| [配置与使用](docs/configuration.zh-CN.md) | 凭据、供应商、实时性、模型连接、配置示例与排错 |
|
|
81
|
-
| [从旧版升级](docs/migration.zh-CN.md) | V1 导入、行为变化、分支与回退注意事项 |
|
|
82
|
-
| [架构说明](docs/design-v2.converged.zh-CN.md) | 会话状态、请求快照、适配器与安全边界 |
|
|
83
|
-
| [开发与验证](docs/v2-implementation.zh-CN.md) | 本地构建、测试、浏览器检查与发布流程 |
|
|
84
|
-
| [更新日志](CHANGELOG.md) | 0.1.0 重构与历史版本 |
|
|
208
|
+
## 💬 问题反馈
|
|
85
209
|
|
|
86
|
-
|
|
210
|
+
如果在使用过程中遇到问题，欢迎前往 [GitHub Issues](https://github.com/Yurzi/dsh-web-search-enhanced/issues) 提交反馈。
|
|
211
|
+
_提示：提 issue 时请附上 DSH 版本、插件版本及报错简述，并请注意**脱敏**，切勿粘贴个人 API Key 或私密对话内容。_
|
|
87
212
|
|
|
88
|
-
|
|
213
|
+
---
|
|
89
214
|
|
|
90
|
-
|
|
215
|
+
## 🤝 致谢与许可
|
|
91
216
|
|
|
92
|
-
|
|
217
|
+
- 本项目代码遵循 [MIT](LICENSE) 开源协议。
|
|
218
|
+
- 衷心感谢 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 团队及各搜索服务（Exa、Firecrawl、Tavily、Tinyfish 等）的开发者。
|
|
219
|
+
- **关于横幅形象**：Banner 中的 DeepSeek 鲸鱼娘形象来源于 **上善无形原创角色与 ZipZipPipe 二创**；本项目横幅基于用户提供的参考图经 AI 辅助创作。角色与参考作品的著作权利均归原作者所有，不因本项目代码的 MIT 许可而获得再授权，亦不代表官方背书。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# 0.1.
|
|
1
|
+
# 0.1.2 配置参考
|
|
2
2
|
|
|
3
|
-
本指南面向安装版插件。包版本为 **0.1.
|
|
3
|
+
本指南面向安装版插件。包版本为 **0.1.2**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
|
|
4
4
|
|
|
5
5
|
## 配置入口与作用范围
|
|
6
6
|
|
|
@@ -24,6 +24,13 @@ web-search-enhanced:
|
|
|
24
24
|
|
|
25
25
|
未设默认连接时，只有恰好一个本地可用连接才自动选中，否则保持未选择。不要依赖目录顺序。显式默认 ID 不会自动修复为其他连接；请确保它存在、未禁用且凭据可用。已有会话保存的连接（包括未选择）不随默认改变。
|
|
26
26
|
|
|
27
|
+
### 模型与搜索连接的自动配对记忆
|
|
28
|
+
|
|
29
|
+
连接选择器的默认选项具备模型配对跟随机制：
|
|
30
|
+
- 用户在特定模型下通过连接选择器选择搜索连接后，该模型与搜索连接的配对关系将持久保存在状态缓存文件（`$DSH_HOME/cache/web-search-enhanced/model-connections.json`）。
|
|
31
|
+
- 后续为该模型初始化新会话时，将自动沿用上一次选择的配对连接（包括明确选择禁用搜索的 `null`）。
|
|
32
|
+
- 对于未曾配对过的新模型（或缓存中的配对连接已在配置中禁用/移除），则默认使用配置文件里的首选项（即 `defaultConnection`，未指定时按单可用连接回退）。
|
|
33
|
+
|
|
27
34
|
## 内置供应商与访问方式
|
|
28
35
|
|
|
29
36
|
四种结构化服务默认 `access: keyless`。保存个人 Key **不会**自动切换模式；必须显式改为 `api-key`。失败、限流、匿名访问拒绝均不会自动改用个人 Key、其他服务或其他协议。
|
|
@@ -34,6 +41,8 @@ web-search-enhanced:
|
|
|
34
41
|
| `builtin:firecrawl` | `https://api.firecrawl.dev/v2/search`，不发 Authorization | 同址 REST；`FIRECRAWL_API_KEY` |
|
|
35
42
|
| `builtin:tavily` | `https://api.tavily.com/search`，`X-Tavily-Access-Mode: keyless` | 同址 REST；`TAVILY_API_KEY` |
|
|
36
43
|
| `builtin:tinyfish` | `https://agent.tinyfish.ai/mcp`，`search`，`X-TinyFish-Access-Mode: keyless` | `https://api.search.tinyfish.ai`，GET；`TINYFISH_API_KEY` |
|
|
44
|
+
| `builtin:openalex` | `https://api.openalex.org/works`，GET，不发 Authorization | 同址 REST，Bearer Token；`OPENALEX_API_KEY` |
|
|
45
|
+
| `builtin:semanticscholar` | 不支持匿名（公共 IP 限流）；须配置 API Key | `https://api.semanticscholar.org/graph/v1/paper/search`，GET，`x-api-key`；`SEMANTIC_SCHOLAR_API_KEY` |
|
|
37
46
|
| `builtin:session-model` | 不支持匿名；跟随当前实际 agent 模型 | `llm-pi-ai` 对应 provider 的显式 `apiKeyEnv` |
|
|
38
47
|
|
|
39
48
|
免 Key 是上游公共访问能力，不是无限额度、服务可用性或永久免登录承诺。IP、地区、额度、服务策略均可能导致拒绝。设置页显示“已配置 / 免 Key”仅说明本地条件满足，不会发网络请求测试供应商。
|
|
@@ -67,6 +76,13 @@ web-search-enhanced:
|
|
|
67
76
|
| Tinyfish | `language` | 2–3 个英文字母，可带连字符及 2–4 个字母后缀 |
|
|
68
77
|
| Tinyfish | `purpose` | 1–2000 字符，不含 U+0000–U+001F |
|
|
69
78
|
| Tinyfish | `domain_type` | `web`、`news`；个人 Key 另可用 `research_paper` |
|
|
79
|
+
| OpenAlex | `sort` | 单个或逗号分隔的多个 `字段:asc` 或 `字段:desc`，如 `cited_by_count:desc` 或 `publication_year:desc,cited_by_count:desc` |
|
|
80
|
+
| OpenAlex | `filter` | 1–500 字符，如 `publication_year:2024` |
|
|
81
|
+
| OpenAlex | `is_oa` | 布尔（自动合并至 filter，如 `is_oa:true`） |
|
|
82
|
+
| OpenAlex | `mailto` | 合法电子邮箱，用于加入 OpenAlex 礼貌池（Polite Pool）享受更快更稳定的响应，缺省使用插件公共标识邮箱 |
|
|
83
|
+
| Semantic Scholar | `year` | 年份或年份范围，如 `2024` 或 `2020-2024` |
|
|
84
|
+
| Semantic Scholar | `fieldsOfStudy` | 学科分类，如 `Computer Science,Physics` |
|
|
85
|
+
| Semantic Scholar | `publicationTypes` | 出版类型，如 `JournalArticle,Conference` |
|
|
70
86
|
|
|
71
87
|
Exa 免 Key 仅接收查询与数量，非空 options 会被拒绝。Tinyfish 免 Key 查询上限 2000 字符，不能使用 `research_paper`。Firecrawl 查询上限 500 字符，其他结构化 REST 查询上限 10000 字符。数量由工具请求和适配器控制，不能在 options 设置 `limit`、`numResults`、分页或缓存字段。Tavily 请求数量上限 20，Firecrawl/Exa REST 上限 100；Tinyfish 使用单页结果，本地按请求数量裁剪。不自动重试或翻页。
|
|
72
88
|
|
|
@@ -74,7 +90,7 @@ Exa 免 Key 仅接收查询与数量，非空 options 会被拒绝。Tinyfish
|
|
|
74
90
|
|
|
75
91
|
实时性指**内容缓存 / 抓取偏好**，不是发布日期过滤，也不证明页面内容确实最新。它在当前会话持久保存，切换连接保留，fork 复制父会话当前值后独立。连接和实时性共用 revision，多标签页冲突需刷新后重试。请求开始后修改设置不改变该请求已冻结的路由与偏好。
|
|
76
92
|
|
|
77
|
-
| 模式 | Firecrawl（两种访问方式） | Exa 个人 Key | Exa 免 Key、Tavily、Tinyfish、模型 |
|
|
93
|
+
| 模式 | Firecrawl（两种访问方式） | Exa 个人 Key | Exa 免 Key、Tavily、Tinyfish、OpenAlex、Semantic Scholar、模型 |
|
|
78
94
|
| --- | --- | --- | --- |
|
|
79
95
|
| `auto` 自动 | 默认搜索策略 | 默认内容策略 | 默认行为 |
|
|
80
96
|
| `fresh` 优先新鲜 | `scrapeOptions.maxAge=86400000` 毫秒 | `contents.maxAgeHours=24` 小时 | 忽略该偏好，不猜测上游参数 |
|
|
@@ -184,7 +200,7 @@ web-search-enhanced:
|
|
|
184
200
|
| `WEB_PROVIDER_ACCESS_ERROR` | 上游访问 / 计费限制（如 HTTP 402），检查账户 |
|
|
185
201
|
| `WEB_PROVIDER_RATE_LIMITED` | HTTP 429 等限流；等待并检查额度，不自动重试或转付费 |
|
|
186
202
|
| `WEB_SEARCH_FOLLOW_UNSUPPORTED` | 检查 provider 协议、地址、显式 apiKeyEnv、模型能力；必要时用固定连接 |
|
|
187
|
-
| `WEB_SEARCH_MIGRATION_REQUIRED` |
|
|
203
|
+
| `WEB_SEARCH_MIGRATION_REQUIRED` | 自动迁移未完成；检查宿主日志、旧配置与 DSH Credentials 权限后重启插件 |
|
|
188
204
|
| `WEB_SEARCH_CONFIG_INVALID` | 检查未知字段、options、信任确认及引用格式；禁用连接也必须配置合法 |
|
|
189
205
|
| `WEB_SEARCH_STORAGE_UNAVAILABLE` | 检查 DSH storage-domain 及持久后端；恢复后下一请求会重试 |
|
|
190
206
|
| `WEB_SEARCH_CONTEXT_UNAVAILABLE` | 缺少真实请求执行上下文；发起新的模型请求，不在工具参数伪造 Session |
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# 0.1.
|
|
1
|
+
# 0.1.2 当前架构与实现边界
|
|
2
2
|
|
|
3
3
|
本文描述已存在的源码契约，不是未来设计提案或历史验收记录。为避免外部链接失效，保留原文件名。用户配置见[配置参考](configuration.zh-CN.md)，验证方法见[开发验证指南](v2-implementation.zh-CN.md)。
|
|
4
4
|
|
|
@@ -46,7 +46,7 @@ tools/execute 的 exec.agent → 私有 AsyncLocalStorage → enhanced-search
|
|
|
46
46
|
|
|
47
47
|
## 3. 配置和秘密分离
|
|
48
48
|
|
|
49
|
-
当前设置格式为 version 2，包版本为 0.1.
|
|
49
|
+
当前设置格式为 version 2，包版本为 0.1.2。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 keyless，访问方式为显式选择，不根据已保存 Key 猜测。自定义连接只允许支持的 adapter 或固定模型协议；新 endpoint 需要信任确认。
|
|
50
50
|
|
|
51
51
|
内置结构化连接不能重定向地址或改变 adapter。自定义结构化连接只能使用个人 Key；固定模型总是需要显式信任。校验拒绝任意 headers/body、缓存参数、秘密字段等不受支持的 options。禁用连接也参与配置校验。
|
|
52
52
|
|
|
@@ -60,8 +60,10 @@ Storage Domain 名称为 `web_search_enhanced`，版本 1，表为 `selections`
|
|
|
60
60
|
|
|
61
61
|
1. 已有记录优先，保留失效连接 ID 和 `null`。
|
|
62
62
|
2. seeded fork 首次初始化时复制父会话当前值；此后独立，不重建历史 fork 边界。
|
|
63
|
-
3.
|
|
64
|
-
|
|
63
|
+
3. 无记录时（首次初始化）：
|
|
64
|
+
a. 优先读取模型配对状态缓存（位于 `$DSH_HOME/cache/web-search-enhanced/model-connections.json`），若存在当前会话模型上一次选择的配对连接（包括明确关闭搜索的 `null`）且连接有效（存在且未禁用），则默认使用该配对连接。
|
|
65
|
+
b. 若无匹配缓存（新模型或连接已失效），使用配置文件里的显式 `defaultConnection`。
|
|
66
|
+
c. 没有显式默认时，仅有一个本地可用连接才选中，否则为 `null`。
|
|
65
67
|
|
|
66
68
|
旧记录缺少 freshness 时，首次读取以当前全局默认原子补入，保留连接和 revision；以后不再跟随默认变化。两项偏好共用一个 revision，set 可单独更新连接、单独更新实时性或同时更新，至少含一项。基于 storage update 的 CAS 拒绝过期 revision，本地串行队列避免重复初始化。
|
|
67
69
|
|
package/docs/migration.zh-CN.md
CHANGED
|
@@ -30,27 +30,30 @@ dsh plugin --profile web add dsh-web-search-enhanced@0.1.0
|
|
|
30
30
|
|
|
31
31
|
升级含服务端与客户端契约变更。重新加载插件或重启 DSH，**然后刷新 Web 页面**；只刷新浏览器不足以更新服务端。此操作可能影响运行中任务，应在合适时机进行。
|
|
32
32
|
|
|
33
|
-
## 3.
|
|
33
|
+
## 3. 启动时自动迁移旧配置
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
插件现在只保留启动时自动迁移，不再提供命令行迁移脚本或设置页手动导入入口。检测到旧版配置后，插件会在设置注册阶段尝试迁移；迁移成功后写入 V2 连接结构，搜索请求仍会对未完成迁移的配置 fail-closed，并提示检查设置。
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
自动迁移覆盖以下旧字段：
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
- 固定路由字段：`modelMode`、`protocol`、`baseURL`、`model`、`apiKeyEnv`；
|
|
40
|
+
- 旧模型与搜索选项：`fallbackModel`、`apiVersion`、`toolIdentifier`、`maxTokens`、`maxUses`、`chatSearchMode`、`searchContextSize`；
|
|
41
|
+
- 明文 `apiKey` 会先尝试写入 DSH Credentials，随后从配置迁移数据中剥离。
|
|
42
|
+
|
|
43
|
+
迁移规则：
|
|
44
|
+
|
|
45
|
+
| 旧配置 | V2 结果 |
|
|
40
46
|
| --- | --- |
|
|
41
|
-
| `modelMode: configured` 或固定配置 | 新增 `custom:legacy`
|
|
47
|
+
| `modelMode: configured` 或固定配置 | 新增 `custom:legacy` 固定模型连接并设为默认 |
|
|
42
48
|
| `modelMode: current-session` | 新会话默认设为 `builtin:session-model` |
|
|
43
|
-
| `protocol/model/baseURL/apiKeyEnv` | 转为固定连接 binding
|
|
44
|
-
| 模型高级选项 |
|
|
45
|
-
| `fallbackModel` |
|
|
46
|
-
| 非空 `apiKey` |
|
|
47
|
-
| 已有 `custom:legacy` | 固定模式拒绝覆盖；先重命名已有连接或手动选择其他 ID |
|
|
48
|
-
|
|
49
|
-
固定模式缺省值沿用旧导入器约定：`anthropic-messages`、`deepseek-flash`、`https://api.deepseek.com/anthropic/v1`、`WEB_SEARCH_ENHANCED_API`。它们不是新的自动 fallback；必须确认目标真实支持搜索。导入器将旧地址标为 trustedEndpoint，因此点击前应检查目标，不能把导入当作安全认证。
|
|
49
|
+
| `protocol/model/baseURL/apiKeyEnv` | 转为固定连接 binding 的对应字段 |
|
|
50
|
+
| 模型高级选项 | 固定模式导入到连接 `options` |
|
|
51
|
+
| `fallbackModel` | 不执行，不转换为备用连接 |
|
|
52
|
+
| 非空 `apiKey` | 仅在 Credentials 写入成功后继续迁移；失败则保持 fail-closed |
|
|
50
53
|
|
|
51
|
-
|
|
54
|
+
自动迁移不会覆盖已有会话的搜索选择，也不会自动切换新连接。迁移完成后请重新加载插件或重启 DSH，再刷新 Web 页面；已有会话如需使用迁移后的连接，应在会话搜索选择器中显式选择。
|
|
52
55
|
|
|
53
|
-
|
|
56
|
+
如果迁移失败，请先将明文 Key 移入 DSH Credentials，并检查旧配置中的 endpoint、模型协议和 credential 引用。插件不会提供独立迁移命令，也不会创建配置文件备份；进行升级前请由宿主或部署系统负责备份 `settings.yaml`。
|
|
54
57
|
|
|
55
58
|
## 4. 从重构预览版升级
|
|
56
59
|
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# 0.1.
|
|
1
|
+
# 0.1.2 开发与验证指南
|
|
2
2
|
|
|
3
3
|
本文件保留原路径以避免断链，内容改为可重复的开发、验证与交付方法。架构见[当前架构](design-v2.converged.zh-CN.md)，用户使用见[配置参考](configuration.zh-CN.md)，版本升级见[升级指南](migration.zh-CN.md)。测试存在、测试通过、供应商在线可用、运行实例完成部署是四种不同结论，不能互相替代。
|
|
4
4
|
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
- Node.js：`^22.19.0 || >=24.0.0`；pnpm：按 packageManager 使用 `11.7.0`。
|
|
8
8
|
- DSH：包要求 `>=0.1.5-rc.2`，源码以 rc.2 服务契约为基线。依赖声明与锁文件是构建依据，不修改宿主安装的依赖来让测试通过。
|
|
9
|
-
- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.
|
|
9
|
+
- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.2` 与 settings schema 的 `version: 2` 不同。
|
|
10
10
|
|
|
11
11
|
在仓库根执行：
|
|
12
12
|
|
|
@@ -99,7 +99,7 @@ preview-ui 写 `.dsh-smoke-home/settings-preview.html`，不会启动第二个 D
|
|
|
99
99
|
|
|
100
100
|
1. 对最终待发提交运行 check 和所需浏览器 / 网络验证，记录版本与退出状态。
|
|
101
101
|
2. 使用 `pnpm pack` 生成构建包；检查包版本、入口、声明、patch、README 与 docs 完整性。GitHub 自动 Source code archive 不是含 lib 的发行 tgz。
|
|
102
|
-
3. 用户可用 `dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.
|
|
102
|
+
3. 用户可用 `dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.2.tgz` 安装 Release 构建附件。
|
|
103
103
|
4. Git 操作、远端分支调整、标签、Release 和 npm 发布分别需要授权与结果核验；不要把本地构建当作已发布。主线为 main，旧代码保留 legacy/v0.0.x，不需要把历史文档反复改成当前成功记录。
|
|
104
104
|
5. 标签触发发布流程后，单独确认 workflow 和 npm registry 的版本 / 包内容，再宣称 npm 可安装。
|
|
105
105
|
|