dsh-web-search-enhanced 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,13 +2,30 @@
 
 记录 `dsh-web-search-enhanced` 的用户可见变化。历史条目描述对应版本，不代表当前行为。
 
+## [0.1.2] - 2026-09-22
+
+### 新增与修复
+
+- 新增 OpenAlex 与 Semantic Scholar 学术检索连接，支持摘要、作者、引用计数与开放获取链接。
+- 修复 OpenAlex 个人 API Key 认证：使用 api_key 查询参数，免 Key 模式不发送凭据；支持配置 mailto 联系邮箱。
+- 模型切换时，尚未手动修改选择的非 fork 会话（revision 为 0）动态更新搜索连接；客户端订阅模型选择变化。
+- 内置及自定义连接的 Key、OpenAlex 邮箱和已有连接编辑统一在对应行下展开，避免共享凭据引用导致重复展开。
+- 移除独立迁移脚本和手动导入入口，仅保留启动自动迁移；统一旧字段检测，验证转换结果后顺序写入凭据与设置，失败时保留旧配置并输出脱敏提示。
+- 更新配置、升级指南及安装示例，补充认证、稀疏旧配置迁移与设置渲染回归测试。
+
+### 升级注意
+
+- 升级前自行备份 settings.yaml；重新加载插件或重启 DSH 后刷新 Web 页面。
+- 不再提供 pnpm run migrate 命令。自动迁移失败时，检查宿主日志、旧配置和 Credentials 写权限后重启插件。
+- 保存 Key 不会自动切换访问模式；个人 Key 仍需显式选择。
+
 ## [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 块级缩进；同时支持插件启动时静默自愈。
+- **配置自动迁移与静默自愈**：该版本提供命令行配置迁移脚本及启动时自动迁移；独立脚本在 0.1.2 中移除。
 - **文档与应用市场体验优化**：优化 README 用户安装与上手指引，补充更友好的安装与使用说明及截图清单 `screenshots.json`。
 
 ## [0.1.0] - 2026-09-21 🎉

package/README.md

@@ -67,10 +67,10 @@
 
 **方式 A：通过 GitHub Release 离线包安装（推荐）**
 
-从 [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`，执行绝对路径安装命令：
+从 [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`，执行绝对路径安装命令：
 
 ```sh
-dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.1.tgz
+dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.2.tgz
 ```
 
 **方式 B：通过 npm 在线安装**
@@ -78,7 +78,7 @@ dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.1.tgz
 在版本已发布到 npm 仓库后，也可直接安装：
 
 ```sh
-dsh plugin --profile web add dsh-web-search-enhanced@0.1.1
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.2
 ```
 
 ### 步骤 2：生效与刷新
@@ -106,6 +106,8 @@ Web Search Enhanced 内置了多种主流检索服务与模型搜索能力，你
 | **Firecrawl**    | 📰 新闻资讯、深度文章抓取       | 免 Key (开箱即用) / 个人 Key   | 擅长清洗和抓取干净的 Markdown 网页正文；支持优先获取最新页面                      |
 | **Tavily**       | 🔍 事实核查、行业调研、综合检索 | 免 Key (开箱即用) / 个人 Key   | 专为大语言模型打造的搜索服务，支持自定义搜索深度（快速/进阶）与新闻主题           |
 | **Tinyfish**     | 🌍 跨语言搜索、地域本地化资讯   | 免 Key (开箱即用) / 个人 Key   | 支持按国家地区、特定语言和搜索用途精准过滤检索范围                                |
+| **OpenAlex**     | 📚 学术论文、开源文献、引用检索 | 免 Key (开箱即用) / 个人 Key   | 全球开放学术图谱，自动解析摘要倒排索引、作者、OA PDF 与引用数；支持 mailto 礼貌池 |
+| **Semantic Scholar** | 🔬 深度学术、论文速读、AI 论文 | 需配置个人 API Key             | 专为学术科研打造，内置 TL;DR 速读总结、引用计数与 ArXiv/OA 论文直链               |
 | **专用搜索模型** | 🤖 统一使用特定支持联网的模型   | Anthropic / OpenAI 协议        | 通过服务端搜索能力（如 OpenAI Responses、Anthropic Messages）直接返回带引用的回答 |
 | **跟随会话模型** | 🔄 懒人模式，搜索使用当前模型   | 需配置 provider 的 `apiKeyEnv` | 自动沿用当前会话选定的模型与端点发起联网搜索                                      |
 
@@ -133,11 +135,13 @@ _注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不
 
 1. **绑定个人 API Key**：
    - 找到目标连接（例如 Firecrawl 或 Tavily）。
-   - 在凭据输入框填入你的 API Key，点击保存（将自动存入 DSH Credentials，安全可靠）。
-   - 将“访问方式”从“免 Key”切换为“个人 Key”。
-2. **设置新会话默认连接**：
+   - 点击目标连接行上的“配置 Key”，在行内展开的输入框中填写 API Key 并保存（将自动存入 DSH Credentials，安全可靠）。
+   - 将“访问方式”从“免 Key”切换为“个人 Key”。OpenAlex 的个人 Key 会按官方要求通过 api_key 查询参数发送。
+2. **配置 OpenAlex 礼貌邮箱（可选）**：
+   - 在 OpenAlex 连接行点击“礼貌邮箱”，行内填写联系邮箱；清空后保存即可恢复默认公共标识。
+3. **设置新会话默认连接**：
    - 在“新会话默认连接”下拉框中选择你最常用的引擎，新创建的对话将自动应用该偏好。
-3. **添加自定义模型或端点**：
+4. **添加自定义模型或端点**：
    - 支持添加任意兼容 OpenAI 或 Anthropic 服务端搜索协议的模型端点。
 
 完整配置语法与高级参数白名单，请参阅 📖 [详细配置指南](docs/configuration.zh-CN.md)。
@@ -184,7 +188,7 @@ _注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不
 <details>
 <summary><b>Q5: 如何从 0.0.x 旧版本平滑升级？</b></summary>
 
-进入 **设置 → 插件 → Web Search Enhanced**，系统会自动检测旧版全局模型配置并弹出“导入旧配置”提示，一键点击即可无缝映射为新版连接配置。详细注意事项请参阅 📖 [升级指南](docs/migration.zh-CN.md)。
+升级后重新加载插件或重启 DSH，插件会在启动时自动检测并迁移旧版全局模型配置；迁移成功后映射为新版连接配置。若出现迁移错误，请检查宿主日志、DSH Credentials 权限和旧配置，再重启插件。详细注意事项请参阅 📖 [升级指南](docs/migration.zh-CN.md)。
 </details>
 
 ---

package/docs/configuration.zh-CN.md

@@ -1,6 +1,6 @@
-# 0.1.1 配置参考
+# 0.1.2 配置参考
 
-本指南面向安装版插件。包版本为 **0.1.1**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
+本指南面向安装版插件。包版本为 **0.1.2**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
 
 ## 配置入口与作用范围
 
@@ -41,6 +41,8 @@ web-search-enhanced:
 | `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:openalex` | `https://api.openalex.org/works`，GET，不发 Authorization | 同址 REST，Bearer Token；`OPENALEX_API_KEY` |
+| `builtin:semanticscholar` | 不支持匿名（公共 IP 限流）；须配置 API Key | `https://api.semanticscholar.org/graph/v1/paper/search`，GET，`x-api-key`；`SEMANTIC_SCHOLAR_API_KEY` |
 | `builtin:session-model` | 不支持匿名；跟随当前实际 agent 模型 | `llm-pi-ai` 对应 provider 的显式 `apiKeyEnv` |
 
 免 Key 是上游公共访问能力，不是无限额度、服务可用性或永久免登录承诺。IP、地区、额度、服务策略均可能导致拒绝。设置页显示“已配置 / 免 Key”仅说明本地条件满足，不会发网络请求测试供应商。
@@ -74,6 +76,13 @@ web-search-enhanced:
 | Tinyfish | `language` | 2–3 个英文字母，可带连字符及 2–4 个字母后缀 |
 | Tinyfish | `purpose` | 1–2000 字符，不含 U+0000–U+001F |
 | Tinyfish | `domain_type` | `web`、`news`；个人 Key 另可用 `research_paper` |
+| OpenAlex | `sort` | 单个或逗号分隔的多个 `字段:asc` 或 `字段:desc`，如 `cited_by_count:desc` 或 `publication_year:desc,cited_by_count:desc` |
+| OpenAlex | `filter` | 1–500 字符，如 `publication_year:2024` |
+| OpenAlex | `is_oa` | 布尔（自动合并至 filter，如 `is_oa:true`） |
+| OpenAlex | `mailto` | 合法电子邮箱，用于加入 OpenAlex 礼貌池（Polite Pool）享受更快更稳定的响应，缺省使用插件公共标识邮箱 |
+| Semantic Scholar | `year` | 年份或年份范围，如 `2024` 或 `2020-2024` |
+| Semantic Scholar | `fieldsOfStudy` | 学科分类，如 `Computer Science,Physics` |
+| Semantic Scholar | `publicationTypes` | 出版类型，如 `JournalArticle,Conference` |
 
 Exa 免 Key 仅接收查询与数量，非空 options 会被拒绝。Tinyfish 免 Key 查询上限 2000 字符，不能使用 `research_paper`。Firecrawl 查询上限 500 字符，其他结构化 REST 查询上限 10000 字符。数量由工具请求和适配器控制，不能在 options 设置 `limit`、`numResults`、分页或缓存字段。Tavily 请求数量上限 20，Firecrawl/Exa REST 上限 100；Tinyfish 使用单页结果，本地按请求数量裁剪。不自动重试或翻页。
 
@@ -81,7 +90,7 @@ Exa 免 Key 仅接收查询与数量，非空 options 会被拒绝。Tinyfish
 
 实时性指**内容缓存 / 抓取偏好**，不是发布日期过滤，也不证明页面内容确实最新。它在当前会话持久保存，切换连接保留，fork 复制父会话当前值后独立。连接和实时性共用 revision，多标签页冲突需刷新后重试。请求开始后修改设置不改变该请求已冻结的路由与偏好。
 
-| 模式 | Firecrawl（两种访问方式） | Exa 个人 Key | Exa 免 Key、Tavily、Tinyfish、模型 |
+| 模式 | Firecrawl（两种访问方式） | Exa 个人 Key | Exa 免 Key、Tavily、Tinyfish、OpenAlex、Semantic Scholar、模型 |
 | --- | --- | --- | --- |
 | `auto` 自动 | 默认搜索策略 | 默认内容策略 | 默认行为 |
 | `fresh` 优先新鲜 | `scrapeOptions.maxAge=86400000` 毫秒 | `contents.maxAgeHours=24` 小时 | 忽略该偏好，不猜测上游参数 |
@@ -191,7 +200,7 @@ web-search-enhanced:
 | `WEB_PROVIDER_ACCESS_ERROR` | 上游访问 / 计费限制（如 HTTP 402），检查账户 |
 | `WEB_PROVIDER_RATE_LIMITED` | HTTP 429 等限流；等待并检查额度，不自动重试或转付费 |
 | `WEB_SEARCH_FOLLOW_UNSUPPORTED` | 检查 provider 协议、地址、显式 apiKeyEnv、模型能力；必要时用固定连接 |
-| `WEB_SEARCH_MIGRATION_REQUIRED` | 按升级指南显式导入旧配置 |
+| `WEB_SEARCH_MIGRATION_REQUIRED` | 自动迁移未完成；检查宿主日志、旧配置与 DSH Credentials 权限后重启插件 |
 | `WEB_SEARCH_CONFIG_INVALID` | 检查未知字段、options、信任确认及引用格式；禁用连接也必须配置合法 |
 | `WEB_SEARCH_STORAGE_UNAVAILABLE` | 检查 DSH storage-domain 及持久后端；恢复后下一请求会重试 |
 | `WEB_SEARCH_CONTEXT_UNAVAILABLE` | 缺少真实请求执行上下文；发起新的模型请求，不在工具参数伪造 Session |

package/docs/design-v2.converged.zh-CN.md

@@ -1,4 +1,4 @@
-# 0.1.1 当前架构与实现边界
+# 0.1.2 当前架构与实现边界
 
 本文描述已存在的源码契约，不是未来设计提案或历史验收记录。为避免外部链接失效，保留原文件名。用户配置见[配置参考](configuration.zh-CN.md)，验证方法见[开发验证指南](v2-implementation.zh-CN.md)。
 
@@ -46,7 +46,7 @@ tools/execute 的 exec.agent → 私有 AsyncLocalStorage → enhanced-search
 
 ## 3. 配置和秘密分离
 
-当前设置格式为 version 2，包版本为 0.1.1。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 keyless，访问方式为显式选择，不根据已保存 Key 猜测。自定义连接只允许支持的 adapter 或固定模型协议；新 endpoint 需要信任确认。
+当前设置格式为 version 2，包版本为 0.1.2。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 keyless，访问方式为显式选择，不根据已保存 Key 猜测。自定义连接只允许支持的 adapter 或固定模型协议；新 endpoint 需要信任确认。
 
 内置结构化连接不能重定向地址或改变 adapter。自定义结构化连接只能使用个人 Key；固定模型总是需要显式信任。校验拒绝任意 headers/body、缓存参数、秘密字段等不受支持的 options。禁用连接也参与配置校验。
 

package/docs/migration.zh-CN.md

@@ -30,51 +30,30 @@ dsh plugin --profile web add dsh-web-search-enhanced@0.1.0
 
 升级含服务端与客户端契约变更。重新加载插件或重启 DSH，**然后刷新 Web 页面**；只刷新浏览器不足以更新服务端。此操作可能影响运行中任务，应在合适时机进行。
 
-## 3. 显式导入旧配置与自动迁移脚本
+## 3. 启动时自动迁移旧配置
 
-针对老用户的历史配置，插件提供两种迁移方式：**Web 设置页导入**与**命令行自动迁移脚本**。
+插件现在只保留启动时自动迁移，不再提供命令行迁移脚本或设置页手动导入入口。检测到旧版配置后，插件会在设置注册阶段尝试迁移；迁移成功后写入 V2 连接结构，搜索请求仍会对未完成迁移的配置 fail-closed，并提示检查设置。
 
-### 方式一：命令行自动迁移脚本（推荐）
+自动迁移覆盖以下旧字段：
 
-针对已有部署或自动化环境，插件提供了针对老用户的自动迁移脚本。该脚本会自动检测 DSH `settings.yaml`，备份原文件，将遗留的 JSON / flow-style 格式转换为标准 DSH YAML 块级缩进格式，并完成 v1 到 v2 模型的无缝迁移：
+- 固定路由字段：`modelMode`、`protocol`、`baseURL`、`model`、`apiKeyEnv`；
+- 旧模型与搜索选项：`fallbackModel`、`apiVersion`、`toolIdentifier`、`maxTokens`、`maxUses`、`chatSearchMode`、`searchContextSize`；
+- 明文 `apiKey` 会先尝试写入 DSH Credentials，随后从配置迁移数据中剥离。
 
-```sh
-# 预览迁移效果（不修改文件）
-node scripts/migrate-config.mjs --dry-run
-
-# 执行自动迁移（自动备份原文件为 .bak）
-pnpm run migrate
-# 或
-node scripts/migrate-config.mjs
-```
-
-脚本特性：
-- **安全备份**：在对配置文件做任何修改前，自动创建 `.bak` 备份文件。
-- **YAML 格式规范化**：自动修复此前设置页或外部写入产生的 JSON 行内花括号 (`flow-style`)，统一输出为符合 DSH 原生规范的标准块级 YAML。
-- **旧版路由迁移**：自动将旧版 `modelMode: configured` 转换为 `custom:legacy`，或将 `modelMode: current-session` 转换为 `builtin:session-model`。
-- **凭据安全保护**：若旧配置存在明文 `apiKey`，脚本会明确告警并将其从公开配置中剥离，提示移入 DSH Credentials。
+迁移规则：
 
-### 方式二：Web 界面显式导入
-
-打开设置 → 插件 → Web Search Enhanced。检测到旧 `modelMode/protocol/baseURL/model/apiKeyEnv` 且未标记 version 2 时，显示导入入口。搜索返回 `WEB_SEARCH_MIGRATION_REQUIRED` 是保护措施，不会静默选新默认替代旧路由。
-
-导入前核对 endpoint 与凭据归属，点击“导入旧配置（不迁移或删除 Key）”：
-
-| 旧配置 | 0.1.0 结果 |
+| 旧配置 | V2 结果 |
 | --- | --- |
-| `modelMode: configured` 或固定配置 | 新增 `custom:legacy` 固定模型，设为新会话默认 |
+| `modelMode: configured` 或固定配置 | 新增 `custom:legacy` 固定模型连接并设为默认 |
 | `modelMode: current-session` | 新会话默认设为 `builtin:session-model` |
-| `protocol/model/baseURL/apiKeyEnv` | 转为固定连接 binding 的 `protocol/model/baseURL/credentialRef` |
-| 模型高级选项 | 固定模式导入到 options；跟随模式按需重新配置 optionsByProtocol |
-| `fallbackModel` | 不执行，不变成备用连接 |
-| 非空 `apiKey` | 拒绝导入，须先移入 Credentials |
-| 已有 `custom:legacy` | 固定模式拒绝覆盖；先重命名已有连接或手动选择其他 ID |
-
-固定模式缺省值沿用旧导入器约定：`anthropic-messages`、`deepseek-flash`、`https://api.deepseek.com/anthropic/v1`、`WEB_SEARCH_ENHANCED_API`。它们不是新的自动 fallback；必须确认目标真实支持搜索。导入器将旧地址标为 trustedEndpoint，因此点击前应检查目标，不能把导入当作安全认证。
+| `protocol/model/baseURL/apiKeyEnv` | 转为固定连接 binding 的对应字段 |
+| 模型高级选项 | 固定模式导入到连接 `options` |
+| `fallbackModel` | 不执行，不转换为备用连接 |
+| 非空 `apiKey` | 仅在 Credentials 写入成功后继续迁移；失败则保持 fail-closed |
 
-UI 以 Settings revision 写入转换结果，并清理用户层的旧路由字段；继承层原配置可能仍保留。导入函数本身只生成对象，不写配置或读取秘密。不要手工仅补 `version: 2` 来“消除错误”，那不会转换旧路由。
+自动迁移不会覆盖已有会话的搜索选择，也不会自动切换新连接。迁移完成后请重新加载插件或重启 DSH，再刷新 Web 页面；已有会话如需使用迁移后的连接，应在会话搜索选择器中显式选择。
 
-**导入只改新会话默认，不覆盖已有会话选择。** 导入后请在已有会话里显式选 `custom:legacy` 或跟随会话模型；新建会话检查默认是否符合预期。多窗口编辑冲突时刷新后重试。
+如果迁移失败，请先将明文 Key 移入 DSH Credentials，并检查旧配置中的 endpoint、模型协议和 credential 引用。插件不会提供独立迁移命令，也不会创建配置文件备份；进行升级前请由宿主或部署系统负责备份 `settings.yaml`。
 
 ## 4. 从重构预览版升级
 

package/docs/v2-implementation.zh-CN.md

@@ -1,4 +1,4 @@
-# 0.1.1 开发与验证指南
+# 0.1.2 开发与验证指南
 
 本文件保留原路径以避免断链，内容改为可重复的开发、验证与交付方法。架构见[当前架构](design-v2.converged.zh-CN.md)，用户使用见[配置参考](configuration.zh-CN.md)，版本升级见[升级指南](migration.zh-CN.md)。测试存在、测试通过、供应商在线可用、运行实例完成部署是四种不同结论，不能互相替代。
 
@@ -6,7 +6,7 @@
 
 - Node.js：`^22.19.0 || >=24.0.0`；pnpm：按 packageManager 使用 `11.7.0`。
 - DSH：包要求 `>=0.1.5-rc.2`，源码以 rc.2 服务契约为基线。依赖声明与锁文件是构建依据，不修改宿主安装的依赖来让测试通过。
-- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.1` 与 settings schema 的 `version: 2` 不同。
+- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.2` 与 settings schema 的 `version: 2` 不同。
 
 在仓库根执行：
 
@@ -99,7 +99,7 @@ preview-ui 写 `.dsh-smoke-home/settings-preview.html`，不会启动第二个 D
 
 1. 对最终待发提交运行 check 和所需浏览器 / 网络验证，记录版本与退出状态。
 2. 使用 `pnpm pack` 生成构建包；检查包版本、入口、声明、patch、README 与 docs 完整性。GitHub 自动 Source code archive 不是含 lib 的发行 tgz。
-3. 用户可用 `dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.1.tgz` 安装 Release 构建附件。
+3. 用户可用 `dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.2.tgz` 安装 Release 构建附件。
 4. Git 操作、远端分支调整、标签、Release 和 npm 发布分别需要授权与结果核验；不要把本地构建当作已发布。主线为 main，旧代码保留 legacy/v0.0.x，不需要把历史文档反复改成当前成功记录。
 5. 标签触发发布流程后，单独确认 workflow 和 npm registry 的版本 / 包内容，再宣称 npm 可安装。