# 常见问题

## 插件未加载或设置卡片未出现

确认安装目标与当前会话使用同一个 DSH profile。源码安装需先运行 `pnpm run build`，使 `lib/index.js` 存在。

检查装载配置中是否出现 `web-search-fetch`，以及两个 `aggregated` provider 选择项。Web 卡片还依赖宿主提供的 settings、locale、UI 和 credentials 服务；仅后端装载不证明浏览器卡片可用。

## 搜索返回 `WEB_PROVIDER_ERROR`

查看插件日志中的服务名与原因。未配置凭证、认证失败、服务不可用或全部熔断均可能导致所有服务失败。

确认至少一个搜索服务的凭证已配置且账户权限有效。配置字段填写引用名，密钥值通过 DSH 凭证服务保存。服务返回零条来源时会返回空结果，不一定代表调用失败。

## 动态网页提取失败，静态资源正常

静态 HTTP 路径不需要服务凭证，动态路径需要 Firecrawl、AnySearch 或已启用的扩展提取服务中至少一路可用。检查凭证与回落关系，见[配置参考](./configuration.md#凭证与启用范围)。

动态路径全败时不会自动回退到 HTTP。需要只使用 HTTP 时，将 `fetch.staticRouting` 设为 `false`。这会对所有 URL 使用 HTTP，不保证可提取需要 JavaScript 渲染的页面。

## 操作在约 30 秒时取消

检查会话实际使用的 `tool-web.fetchTimeoutMs`。Web preset 内嵌配置与顶层工具条目可能不同，修改顶层不一定影响当前会话。见[工具超时配置](./configuration.md#工具超时配置)。

`WEB_ABORTED` 表示调用方取消；单个服务超时会丢弃该路并继续使用其他结果。工具预算应覆盖额度检查、并发请求和重排所需时间。

## 服务熔断后不再被调用

插件日志包含触发原因和预计恢复时间。限流使用冷却期限；额度耗尽或余额不足暂停到宿主时区的次日零点。恢复在下一次操作时检查。

搜索和提取的熔断状态独立，且只保存在内存中。恢复尝试不代表服务账户已恢复额度；持续欠费可再次触发熔断。

## 保存设置后调用减少或未派发

检查调用预设、搜索／提取参与范围、服务数量和 HTTP 请求预算。免费接口预设会排除提供免费额度的收费 API；扩展开关打开也仍需列入参与范围。均衡预设最多派发三路，按参与列表顺序选择可用服务。额度查询、重试和重排也消耗请求预算。

## 整理结果出现补充、差异或省略说明

补充片段表示无法可靠对齐或独有的章节；文本差异保留原文变体，不判断真伪。输出预算不足时按完整内容块省略；上游截断无法由整理恢复。可增加 `controls.maxOutputChars` 或在设置页切换旧版单份正文模式。仅返回登录／挑战页或其他目标页面时会报错，不能视为提取成功。

## 设置已保存，但凭证仍不可用

状态中的「已配置」只表示凭证服务持有该引用的值，不证明服务认证成功。检查引用名、账户权限和实际错误响应。

AnySearch 与 Firecrawl 配置了不同搜索／提取引用时，卡片会更新两处引用。豆包搜索与提取分别填写。智谱仅支持搜索；空白填写位保持已有值，清除需使用宿主凭证管理功能。

## 卸载后出现插件覆盖警告

卸载后出现 `patch: entry "web-search-fetch" not found`，说明本地 patch 仍有设置页保存的插件覆盖项。按[卸载与回滚](./lifecycle.md)移除此项并检查 provider，保留其他配置与共享凭证。

## 报告问题

提供插件版本、Node.js 与 DSH 版本、profile 类型、实际工具错误码及可复现步骤。使用公开示例 URL，先脱敏日志和配置。不要上传密钥、凭证文件或带访问令牌的 URL。安全问题按[安全说明](../SECURITY.md)报告。