dsh-web-search-free

配置

启动 Web 界面（dsh web）后找到配置卡片。它的位置由 dsh 版本决定，插件会自动落到当前版本存在的那个位置：

dsh 版本	卡片位置
≥ 0.1.6	侧栏 插件 → 「已安装」里的 web-search-free，表单在包说明与「包含的组件」之间
≤ 0.1.5	设置 → 插件 → 插件配置 → 免费网页搜索（英文界面下为 Web Search Free）

卡片里的引擎分成两组：**「调用顺序」是已存过 Key、真正参与调用的（带 #1、#2 序号），「其他可用引擎 (n)」**是还没填 Key 的。

1. 点击一行展开，粘贴 API Key；行内「获取 API Key ↗」直达申请页。一个引擎可填多个 Key，每行一个，按行顺序轮换。保存后该行自动移进「调用顺序」。
2. 拖行左侧的 ⋮⋮ 手柄改调用顺序：靠前的先调，失败按序 fallback，任一 (引擎, Key) 成功即返回。只有「调用顺序」组里的行可拖；点行体是展开/收起，要拖请抓 ⋮⋮。
3. 顶部的 「启用 web_fetch（URL 抓取）」 开关控制模型能否抓取 URL 全文。关闭后调用会收到明确的错误提示，而不是从工具表移除工具。
4. 点保存。配置存在 dsh 的设置命名空间 web-search-free 里，下一次搜索即时生效，无需重启。

至少配置一个引擎的 Key，否则搜索会报 No web search providers configured.

找不到配置卡片时

dsh 的插件配置界面还在快速演进，卡片所在的插槽名换过不止一次。插件同时认识历史上出现过的几个插槽，但如果你的 dsh 比本插件更新、插槽又改名了，卡片就不会出现——这时浏览器控制台会打印一行 [web-search-free] no settings card mounted: …，附上这版 dsh 实际声明的插槽名，欢迎把这行贴到 issue 里。

不用等新版本：所有配置都能直接写进 profile 的 ~/.dsh/profiles/web/cordis.patch.yml，这条路径不依赖任何界面。插件装上时已由自己的 bundle 层插入了 web-search-free 这一行，所以这里写的是按 id 覆盖它的 config（不要再写 insert，那会插出重复的行）：

- id: web-search-free
  config:
    tavilyApiKey: tvly-xxxxxxxx
    exaApiKey: |-
      key-1
      key-2
    enableFetch: true
    providerOrder: [tavily, exa, tinyfish]

字段名与卡片一一对应（见 src/index.ts 的 Config）：ApiKey（多 Key 用多行字符串）、enableFetch、providerOrder。写完重启 dsh 生效。

这里和卡片的关系随 dsh 版本而变：dsh ≥ 0.1.7 的卡片就是往这个文件写，两者是同一层，在卡片里保存会覆盖你手写的同名字段；dsh ≤ 0.1.6 的卡片写的是另一份设置文档（~/.dsh/settings.yaml），那边的值属于用户层，会盖住这里的 base 值。

升级到 dsh 0.1.7 后 Key 不见了

配置的存放位置在 dsh 0.1.7 变了：≤ 0.1.6 存在 ~/.dsh/settings.yaml，≥ 0.1.7 存进 profile 的 cordis.patch.yml。dsh 自己会做一次迁移——把 settings.yaml 改名为 settings.yaml.imported 并把各段写进同 id 的 entry——但它只跑一次，而且只接受当时运行组合里认识的段落。

升级那一刻本插件如果起不来（1.5.x 在 0.1.7 上会让整个 Web 界面停在 "Failed to load plugins"），它就正好会被跳过，Key 留在改名后的文件里没人管。

数据没丢，在 dsh 主目录（默认 ~/.dsh）的 settings.yaml.imported 里。插件检测到这种情况时会在启动日志里说明，卡片上也会显示同样的提示。最省事的办法是把这段话发给 dsh 让它代劳：

把 dsh 主目录（默认 ~/.dsh）下 settings.yaml.imported 里 web-search-free 段的所有字段，原样写进当前 profile 的 cordis.patch.yml，作为 id 为 web-search-free 的 entry 的 config；该 entry 不存在就新增。保留原文件的注释和格式，改动前先备份。

也可以照上面那段 YAML 的格式自己手抄过去，或者干脆在卡片里重新输一遍。

找不到配置卡片时

dsh 的插件配置界面还在快速演进，卡片所在的插槽名换过不止一次。插件同时认识历史上出现过的几个插槽，但如果你的 dsh 比本插件更新、插槽又改名了，卡片就不会出现——这时浏览器控制台会打印一行 [web-search-free] no settings card mounted: …，附上这版 dsh 实际声明的插槽名，欢迎把这行贴到 issue 里。

不用等新版本：所有配置都能直接写进 profile 的 ~/.dsh/profiles/web/cordis.patch.yml，这条路径不依赖任何界面。插件装上时已由自己的 bundle 层插入了 web-search-free 这一行，所以这里写的是按 id 覆盖它的 config（不要再写 insert，那会插出重复的行）：

- id: web-search-free
  config:
    tavilyApiKey: tvly-xxxxxxxx
    exaApiKey: |-
      key-1
      key-2
    enableFetch: true
    providerOrder: [tavily, exa, tinyfish]

字段名与卡片一一对应（见 src/index.ts 的 Config）：ApiKey（多 Key 用多行字符串）、enableFetch、providerOrder。写完重启 dsh 生效。

这里和卡片的关系随 dsh 版本而变：dsh ≥ 0.1.7 的卡片就是往这个文件写，两者是同一层，在卡片里保存会覆盖你手写的同名字段；dsh ≤ 0.1.6 的卡片写的是另一份设置文档（~/.dsh/settings.yaml），那边的值属于用户层，会盖住这里的 base 值。