Skip to content

feat(websearch): add a keyless multi-engine search plugin - #203

Open
JochenYang wants to merge 1 commit into
zai-org:mainfrom
JochenYang:feat/websearch-plugin
Open

JochenYang wants to merge 1 commit into
zai-org:mainfrom
JochenYang:feat/websearch-plugin

Conversation

@JochenYang

Copy link
Copy Markdown

Plugin type (required) / 插件类型(必填)

  • UI Plugin / 是 UI 插件 — provides MCP Apps interactive pages / 提供 MCP Apps 交互页面
  • Standard plugin / 普通插件(非 UI) — does not provide MCP Apps interactive pages / 不提供 MCP Apps 交互页面
  • Not applicable / 不适用 — repository-only changes; no plugin content changed / 仅仓库级改动,不涉及插件内容

Affected plugin name(s) / 涉及的插件名称:websearch

What / 改动内容

Problem / 问题. ZCode's built-in WebSearch tool only exists when the model provider supports server-side native search (supportsNativeWebSearch), so under providers without it a session has no web search at all. / ZCode 内置的 WebSearch 走模型 provider 的服务端原生搜索,provider 不支持时整个会话就没有网页搜索可用。

Change / 方案. Adds external_plugins/websearch: a keyless multi-engine web search plugin shipped as a single zero-dependency MCP server (Node 18+ global fetch — no node_modules, no build step, stdio transport).

  • Engines chained with automatic fallback: AnySearch → Exa → Parallel → Bing → SearXNG; one deadline covers the whole call; URL dedupe + 300-character snippets; per-engine attempts with quota hints. 新增 external_plugins/websearch:多引擎自动回退的网页搜索。
  • Tools / 工具:web_search (query / limit / engines) and fetch_page (static page text with SSRF guards).
  • Every engine works without a key; optional per-engine keys switch to the user's own quota. 所有引擎免 Key 可用,各引擎可选填自己的 Key。
  • Configuration lives in websearch.json inside the plugin data folder — auto-created on first start, its absolute path baked into the tool descriptions so users can just ask for it. 配置文件首启自动生成,路径写在工具描述里,问模型即可。
  • Security boundary the host does not provide for MCP servers / 自实现的宿主外安全边界:http/https only; loopback / private / link-local / CGNAT / unique-local refused; every redirect hop re-checked; 2 MB response ceiling; request timeouts.
  • Bilingual docs (README.md EN / README_CN.md 中文), MIT license, market icon at assets/websearch/icon.png.

Self-check / 自查清单

  • Plugin name is unique kebab-case; new external plugin directory is external_plugins/websearch/ / 插件名唯一且 kebab-case,新增插件位于 external_plugins/websearch/
  • Usage category is set independently of publisher ownership / category: productivity
  • Plugin type and affected names are declared above / 已声明插件类型与涉及名称
  • version bumped in BOTH plugin.json and marketplace.json (artifacts are immutable) — both are 0.1.5 / 两处版本号一致(0.1.5)
  • README.md (EN) and README_CN.md (中文) both updated and equivalent / 中英文 README 均已提供且语义一致
  • description_i18n has both en and zh-CN / description_i18n 包含 en 与 zh-CN(manifest 与市场条目完全一致)
  • No secrets, machine-specific paths, or private dependencies / 不含密钥、机器专属路径或私有依赖
  • Model/API/network dependencies documented / 网络、API 依赖已写明(见下)
  • python3 scripts/validate.py passes locally / 本地校验通过(60 plugins validated)
  • python3 scripts/build_dist.py / git diff --check — see testing notes / 见下方测试说明

Dependencies, network requests, permissions, side effects / 依赖、网络、权限与副作用

  • Outbound network, engine endpoints only / 仅出站访问以下引擎端点:www.bing.com, cn.bing.com, api.anysearch.com, mcp.exa.ai, mcp.parallel.ai, plus user-configured SearXNG instances(用户自配的 SearXNG 实例).
  • Optional user keys for AnySearch / Exa / Parallel are stored in the user's own plugin data folder (websearch.json); they are never shipped with the plugin. 可选 Key 存在用户本机的数据目录,不随插件分发。
  • File writes / 文件写入: one auto-created websearch.json (config template) inside $ZCODE_PLUGIN_DATA; nothing else. 仅自动生成一个配置模板文件。
  • Permissions / 权限: standard MCP stdio server; no elevated grants, no telemetry, no callbacks. 标准 MCP stdio,无遥测无回调。
  • Side effects / 副作用: none beyond the network calls above. bin/server.mjs is the source of a zero-dependency server (Node 18+ global fetch), not a build artifact.
  • Licensing / 许可: plugin code MIT (original implementation, ported by the author from their own cindy-websearch project); engines are third-party services documented in the READMEs; icon generated with an image model, no third-party assets. 插件代码为作者原创(MIT),图标为 AI 生成,无第三方素材。

Testing / 测试

  • node --check bin/server.mjs, node bin/server.mjs --self-test (offline parser / config / SSRF assertions) — OK.
  • python tests/test-server.py: offline MCP handshake, tool list, error paths (15 checks) — OK.
  • python tests/test-server.py --live: real engines — bing 3 results, default chain answered by anysearch, fetch_page read example.com, loopback refused with FETCH_BLOCKED — OK.
  • Installed in ZCode desktop and used in real sessions (exhibition search: web_search ×2 → fetch_page ×3). / 已在桌面端真实会话中使用。
  • python3 scripts/build_dist.py: validate.py passes for all 60 plugins; build_zip verified for websearch directly (27 KB deterministic zip). The full build_dist run currently fails on the pre-existing unbuilt UI plugins (excalidraw requires pnpm build first) — unrelated to this PR; CI's build-plugins.mjs step covers that. / 全量 build_dist 在既有的未构建 UI 插件处失败,与本 PR 无关;websearch 单项打包已验证通过。

@panda920

Copy link
Copy Markdown
Collaborator

✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants