opencode-search-plugin 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guotree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,234 @@
-# Temporary Holding Version
+# opencode-search-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [简体中文](README.zh-CN.md)
+
+Nine self-contained [OpenCode](https://opencode.ai) v2 plugins that register web search providers. Each file stands on its own: copy one into your plugins directory, or install the package to get all nine.
+
+[AnySearch](https://www.anysearch.com/) · [Brave Search](https://brave.com/search/api/) · [Jina](https://jina.ai/) · [Linkup](https://www.linkup.so/) · [Metaso](https://metaso.cn/) · [Querit](https://querit.ai/) · [SerpApi](https://serpapi.com/) · [Serper](https://serper.dev/) · [You.com](https://you.com/)
+
+## Why this exists
+
+OpenCode v2 ships with five web search providers built in: `exa`, `firecrawl`, `parallel`, `tavily` and `tinyfish`. Outside that set, a much wider field of search APIs offers free quotas or free tiers — enough to run an agent's searches without paying for the privilege.
+
+This repository adds plugins for nine more of them, taking the pool from five providers to fourteen. AnySearch runs without a key at all; the other eight bind only when you supply one, so installing this package never routes a query to a provider that would immediately fail. Which of them are worth your time depends on the free tier each one currently offers, so check a provider's pricing before you rely on it.
+
+## Install
+
+### All nine, as a package
+
+```sh
+# from GitHub (add #v1.0.1 to pin)
+opencode plugin add github:guotree/opencode-search-plugin
+
+# or from npm (add @1.0.1 to pin)
+opencode plugin add opencode-search-plugin
+```
+
+or declare it in `opencode.json(c)`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["github:guotree/opencode-search-plugin"]
+}
+```
+
+### One or two, by copying a file
+
+Every plugin is a single `.ts` file with no relative imports and no build step. Drop it where OpenCode auto-discovers plugins:
+
+```text
+~/.config/opencode/plugins/            # global
+<project>/.opencode/plugins/           # one project
+```
+
+For a location that is not auto-discovered, list it explicitly:
+
+```jsonc
+{ "plugins": ["./plugins/brave-search.ts"] }
+```
+
+> Do not install the package *and* copy its files. Both register the same websearch provider IDs, so the pool would contain each service twice.
+
+### Skip the services you have no key for
+
+Loading the package registers all nine, but a provider without a key never joins the search pool — see [Keys](#keys). To keep them out of the registry entirely:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "github:guotree/opencode-search-plugin",
+      "options": { "disable": ["serper", "serpapi", "youcom"] }
+    }
+  ]
+}
+```
+
+`disable` takes the provider IDs listed in the table below.
+
+## Keys
+
+Every provider except AnySearch needs an API key. Give it one of two ways:
+
+- **`/connect`** inside OpenCode — stored per provider, rotated without a restart, and survives environment changes.
+- **Environment variable** — read as a fallback, so it works in headless and CI contexts.
+
+A provider with no key stays unbound: it is absent from the websearch pool, so `"provider": "random"` can never route a query to a service that would immediately fail.
+
+AnySearch is the exception. It has an anonymous tier, so it is always registered and only attaches an `Authorization` header when a key exists.
+
+Once keys are in place, pick how OpenCode chooses among them:
+
+```jsonc
+{ "websearch": { "provider": "random" } }
+```
+
+`random` spreads queries across every bound provider. Set it to a specific ID such as `"brave"` to pin one, or `false` to turn web search off.
+
+## Providers
+
+| Provider | ID | Key (env / `/connect`) | Anonymous | Notes |
+| --- | --- | --- | --- | --- |
+| AnySearch | `anysearch` | `ANYSEARCH_API_KEY` | yes | Free tier per IP; intent router, `cn`/`intl` zones |
+| Brave Search | `brave` | `BRAVE_SEARCH_API_KEY` | no | Independent index, 20 results max |
+| Jina | `jina` | `JINA_API_KEY` | no | Page content is opt-in because it is token-billed |
+| Linkup | `linkup` | `LINKUP_API_KEY` | no | `flash`/`fast`/`standard`/`deep` reasoning depth |
+| Metaso | `metaso` | `METASO_API_KEY` | no | Billed per search, not per result |
+| Querit | `querit` | `QUERIT_API_KEY` | no | Falls back to sentence matches when a snippet is missing |
+| SerpApi | `serpapi` | `SERPAPI_API_KEY` | no | Google via SerpApi; also has its own free 1-hour server cache |
+| Serper | `serper` | `SERPER_API_KEY` | no | Google via Serper; billed per query in credits |
+| You.com | `youcom` | `YDC_API_KEY` | no | Web and news merged; extraction modes |
+
+## Configuration
+
+Knobs are environment variables, read once when OpenCode starts — change one and restart. Defaults match what each API documents, so leaving them unset is the right starting point.
+
+### Shared by all nine
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `<PROVIDER>_CACHE_TTL` | `600000` | Milliseconds to reuse a response for the same normalized query. `0` disables caching. |
+
+### AnySearch
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `ANYSEARCH_MAX_RESULTS` | `10` | Results per search, clamped to the API's 1–10 |
+| `ANYSEARCH_TAG` | — | Pin the intent router to a sub-domain, e.g. `code.doc` |
+| `ANYSEARCH_ZONE` | — | `cn` or `intl` |
+| `ANYSEARCH_LANGUAGE` | — | Preferred result language, e.g. `zh-CN` |
+| `ANYSEARCH_FORMAT` | `markdown` | `markdown` or `json` for the content field |
+| `ANYSEARCH_API_KEY` | — | Optional; anonymous access works without it |
+
+### Brave Search
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `BRAVE_NUM` | `8` | Results per search, clamped to 1–20 (Brave's maximum) |
+| `BRAVE_COUNTRY` | — | Two-letter country code, or `ALL` |
+| `BRAVE_LANG` | — | Result language, e.g. `en`, `zh-hans`, `pt-br` |
+| `BRAVE_FRESHNESS` | — | `pd` (24h), `pw` (7d), `pm` (31d), `py` (365d), or `YYYY-MM-DDtoYYYY-MM-DD` |
+
+### Jina
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `JINA_NUM` | `0` | Results per search, 1–100. `0` omits the parameter, which keeps Jina's faster and wider result types |
+| `JINA_INCLUDE_CONTENT` | off | `true` returns each hit's full page markdown — far more context and billed tokens |
+| `JINA_GL` / `JINA_HL` | — | Country / language code |
+| `JINA_LOCATION` | — | City-level origin to simulate, e.g. `Berlin` |
+
+### Linkup
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `LINKUP_DEPTH` | `fast` | `flash`, `fast`, `standard`, or `deep` |
+| `LINKUP_MAX_RESULTS` | `10` | Results per search, clamped to 1–100 |
+
+### Metaso
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `METASO_SEARCH_SIZE` | `20` | Results per search, clamped to 1–100 |
+| `METASO_INCLUDE_RAW_CONTENT` | off | `true` returns every hit's full source text at the same search cost, but far more context tokens |
+
+### Querit
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `QUERIT_COUNT` | `8` | Results per search |
+
+### SerpApi
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `SERPAPI_GL` / `SERPAPI_HL` | — | Country / language code |
+| `SERPAPI_TBS` | — | Advanced filter, e.g. `qdr:d` (past day), `qdr:y` (past year) |
+
+There is deliberately no result-count knob: Google withdrew the `num` parameter, so SerpApi cannot honour one.
+
+### Serper
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `SERPER_NUM` | `10` | Results per search, clamped to 1–100 |
+| `SERPER_GL` / `SERPER_HL` | — | Country / language code |
+| `SERPER_TBS` | — | Time filter: `qdr:h`, `qdr:d`, `qdr:w`, `qdr:m`, `qdr:y` |
+
+### You.com
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `YOUCOM_COUNT` | `10` | Results per section (web and news each), clamped to 1–100 |
+| `YOUCOM_EXTRACTION` | `highlights` | `highlights` returns answering passages, `none` returns bare snippets, `full_page` crawls every hit and bills per live-fetched page |
+| `YOUCOM_LANGUAGE` / `YOUCOM_COUNTRY` | — | e.g. `EN` / `US` |
+| `YOUCOM_FRESHNESS` | — | `day`, `week`, `month`, `year`, or `YYYY-MM-DDtoYYYY-MM-DD` |
+
+## How a query flows
+
+1. OpenCode asks the selected provider for the query.
+2. The normalized query (trimmed, whitespace collapsed) is checked against an in-memory cache. A hit returns immediately — repeat queries are free and instant.
+3. On a miss the key is resolved again, so a key rotated in `/connect` applies to the very next search.
+4. The request goes out; failures surface the HTTP status and response body so you can see what the provider actually said.
+5. The response is schema-decoded, mapped to `{ url, title, content, time }`, and cached.
+
+Dates are parsed from relative phrases (`3 hours ago`, `3小时前`), absolute formats (`Sep 30, 2026`, `31 Mar 2026`), and ISO 8601. Strings whose lenient parsing would invent a wrong year — `Nov 1`, which `Date.parse` reads as 2001 — are dropped rather than reported as a bogus timestamp.
+
+## Troubleshooting
+
+```sh
+# Is the plugin loaded, and did it fail?
+opencode plugin list
+
+# Which providers are actually in the pool?
+# A provider missing here has no key, or is listed in `disable`.
+opencode api get "/api/websearch/provider"
+```
+
+Also worth checking:
+
+- **A provider is missing from the pool** — it has no key. Run `/connect` or export its variable, then restart; credential changes made in `/connect` rebind without one.
+- **A search fails with `Connect X in /connect, or set X_API_KEY`** — the key disappeared between binding and searching. Reconnect or re-export.
+- **Everything is slow or burning credits** — leave `*_CACHE_TTL` at its default. Repeated queries within the window are served from memory.
+- **Nothing happens after editing a plugin file** — OpenCode watches plugins and reloads them; if it does not, `opencode service restart`.
+
+Logs live at `~/.local/share/opencode/log/opencode.log`; filter for `loading plugin` to see every plugin OpenCode resolved, with its entrypoint.
+
+## Development
+
+```sh
+npm install
+npm run check     # typecheck + tests
+```
+
+- `npm run typecheck` — strict TypeScript across every plugin and test.
+- `npm test` — the shared provider contract, per-provider behaviour, date parsing, aggregate registration, and repository-structure guards.
+
+`@opencode/plugin` and `effect` are declared as **devDependencies**, not `dependencies`. OpenCode provides both to plugins at runtime — the same mechanism that lets a single `.ts` file run from `~/.config/opencode/plugins/` with no `node_modules` at all. Declaring them as runtime dependencies would make `opencode plugin add` install a 127 MB tree (`effect` alone is 47 MB, and `@opencode/plugin` pulls in `@aws-sdk`, `google-auth-library` and `@opentelemetry`) to reach 100 KB of plugin source; as devDependencies they are present for typechecking and tests, and absent from a consumer's install.
+
+The structure tests exist because each file must remain independently copyable: they fail if a plugin starts importing a sibling module, if the shared blocks stop being byte-identical copies, or if a provider's IDs drift apart. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,234 @@
+[English](README.md) · **简体中文**
+
+# opencode-search-plugin
+
+九个相互独立的 [OpenCode](https://opencode.ai) v2 插件，各自注册一个网页搜索 provider。每个文件都能单独使用：复制一个进你的插件目录，或者安装这个包一次拿全九个。
+
+[AnySearch](https://www.anysearch.com/) · [Brave Search](https://brave.com/search/api/) · [Jina](https://jina.ai/) · [Linkup](https://www.linkup.so/) · [Metaso](https://metaso.cn/) · [Querit](https://querit.ai/) · [SerpApi](https://serpapi.com/) · [Serper](https://serper.dev/) · [You.com](https://you.com/)
+
+## 为什么做这个插件
+
+OpenCode v2 内置了五个网页搜索 provider：`exa`、`firecrawl`、`parallel`、`tavily`、`tinyfish`。在这个范围之外，还有大量搜索 API 提供免费额度或免费层级，足以支撑 agent 的日常检索而不必为此付费。
+
+本仓库为其中九家补上了插件，把可用池从五个 provider 扩到十四个。AnySearch 无需任何 key 即可使用；其余八家只在你提供 key 之后才会绑定，因此装上这个包也不会把查询路由到一个注定失败的服务上。至于哪几家值得用，取决于它们各自当前的免费额度，长期依赖某家之前建议先确认它的定价。
+
+## 安装
+
+### 一次性装全九个：包安装
+
+```sh
+# 从 GitHub 安装（追加 #v1.0.1 可固定到该 tag）
+opencode plugin add github:guotree/opencode-search-plugin
+
+# 或从 npm 安装（追加 @1.0.1 可固定到该版本）
+opencode plugin add opencode-search-plugin
+```
+
+或者写进 `opencode.json(c)`：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["github:guotree/opencode-search-plugin"]
+}
+```
+
+### 只要一两个：直接复制文件
+
+每个插件都是单个 `.ts` 文件，没有相对导入，也没有构建步骤。放进 OpenCode 会自动发现插件的位置即可：
+
+```text
+~/.config/opencode/plugins/            # 全局
+<project>/.opencode/plugins/           # 单个项目
+```
+
+如果位置不在自动发现范围内，就显式列出：
+
+```jsonc
+{ "plugins": ["./plugins/brave-search.ts"] }
+```
+
+> **不要既装包、又复制它的文件。** 两者注册的是同一批 websearch provider ID，搜索池里每家服务会出现两次。
+
+### 跳过你没有 key 的服务
+
+装包会注册全部九家，但没有 key 的 provider 永远不会进入搜索池——见下文[密钥](#密钥)。想让它们连注册表都不出现：
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "github:guotree/opencode-search-plugin",
+      "options": { "disable": ["serper", "serpapi", "youcom"] }
+    }
+  ]
+}
+```
+
+`disable` 填的是下表中的 provider ID。
+
+## 密钥
+
+除 AnySearch 外，每家服务都需要 API key。两种给法二选一：
+
+- **OpenCode 内的 `/connect`** —— 按 provider 存储，轮换后无需重启，且不受环境变量变动影响。
+- **环境变量** —— 作为兜底读取，因此在无界面和 CI 场景下也能工作。
+
+没有 key 的 provider 会保持未绑定状态：它不在 websearch 池中，所以 `"provider": "random"` 绝不会把查询路由到一个注定失败的服务上。
+
+AnySearch 是例外。它有匿名额度，因此始终注册，只有存在 key 时才附带 `Authorization` 头。
+
+密钥就位后，再决定 OpenCode 如何在它们之间做选择：
+
+```jsonc
+{ "websearch": { "provider": "random" } }
+```
+
+`random` 会把查询分散到所有已绑定的 provider。填具体 ID（例如 `"brave"`）则固定用某一家，填 `false` 则完全关闭网页搜索。
+
+## 支持的服务
+
+| 服务 | ID | 密钥（环境变量 / `/connect`） | 匿名可用 | 说明 |
+| --- | --- | --- | --- | --- |
+| AnySearch | `anysearch` | `ANYSEARCH_API_KEY` | 是 | 按 IP 的免费额度；意图路由，`cn` / `intl` 分区 |
+| Brave Search | `brave` | `BRAVE_SEARCH_API_KEY` | 否 | 独立索引，最多 20 条结果 |
+| Jina | `jina` | `JINA_API_KEY` | 否 | 页面正文按 token 计费，因此默认不取 |
+| Linkup | `linkup` | `LINKUP_API_KEY` | 否 | `flash` / `fast` / `standard` / `deep` 四档推理深度 |
+| Metaso | `metaso` | `METASO_API_KEY` | 否 | 按次搜索计费，不按结果条数 |
+| Querit | `querit` | `QUERIT_API_KEY` | 否 | 摘要缺失时回退到句子级匹配 |
+| SerpApi | `serpapi` | `SERPAPI_API_KEY` | 否 | 经 SerpApi 调用 Google；另有其自带的免费 1 小时服务端缓存 |
+| Serper | `serper` | `SERPER_API_KEY` | 否 | 经 Serper 调用 Google；按查询消耗积分计费 |
+| You.com | `youcom` | `YDC_API_KEY` | 否 | 网页与新闻结果合并；多种正文抽取模式 |
+
+## 配置
+
+所有配置项都是环境变量，OpenCode 启动时读取一次——改了要重启。默认值取自各家 API 文档，所以一开始什么都不设就是合理的起点。
+
+### 九家通用
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `<PROVIDER>_CACHE_TTL` | `600000` | 同一条归一化查询可复用响应的毫秒数。`0` 关闭缓存。 |
+
+### AnySearch
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `ANYSEARCH_MAX_RESULTS` | `10` | 每次搜索的结果数，限制在 API 允许的 1–10 |
+| `ANYSEARCH_TAG` | — | 把意图路由器固定到某个子域，例如 `code.doc` |
+| `ANYSEARCH_ZONE` | — | `cn` 或 `intl` |
+| `ANYSEARCH_LANGUAGE` | — | 首选结果语言，例如 `zh-CN` |
+| `ANYSEARCH_FORMAT` | `markdown` | content 字段用 `markdown` 还是 `json` |
+| `ANYSEARCH_API_KEY` | — | 可选；不设也能匿名使用 |
+
+### Brave Search
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `BRAVE_NUM` | `8` | 每次搜索的结果数，限制在 1–20（Brave 的上限） |
+| `BRAVE_COUNTRY` | — | 两位国家代码，或 `ALL` |
+| `BRAVE_LANG` | — | 结果语言，例如 `en`、`zh-hans`、`pt-br` |
+| `BRAVE_FRESHNESS` | — | `pd`（24 小时）、`pw`（7 天）、`pm`（31 天）、`py`（365 天），或 `YYYY-MM-DDtoYYYY-MM-DD` |
+
+### Jina
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `JINA_NUM` | `0` | 每次搜索的结果数，1–100。`0` 表示不传该参数，从而保留 Jina 更快、类型更全的结果 |
+| `JINA_INCLUDE_CONTENT` | 关 | `true` 返回每条命中的整页 markdown——上下文和计费 token 都会大幅增加 |
+| `JINA_GL` / `JINA_HL` | — | 国家 / 语言代码 |
+| `JINA_LOCATION` | — | 模拟的城市级来源，例如 `Berlin` |
+
+### Linkup
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `LINKUP_DEPTH` | `fast` | `flash`、`fast`、`standard` 或 `deep` |
+| `LINKUP_MAX_RESULTS` | `10` | 每次搜索的结果数，限制在 1–100 |
+
+### Metaso
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `METASO_SEARCH_SIZE` | `20` | 每次搜索的结果数，限制在 1–100 |
+| `METASO_INCLUDE_RAW_CONTENT` | 关 | `true` 返回每条命中的完整原文，搜索成本不变，但上下文 token 大幅增加 |
+
+### Querit
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `QUERIT_COUNT` | `8` | 每次搜索的结果数 |
+
+### SerpApi
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `SERPAPI_GL` / `SERPAPI_HL` | — | 国家 / 语言代码 |
+| `SERPAPI_TBS` | — | 高级筛选，例如 `qdr:d`（一天内）、`qdr:y`（一年内） |
+
+这里**刻意没有**结果条数的配置项：Google 已经废弃了 `num` 参数，SerpApi 无法遵守它。
+
+### Serper
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `SERPER_NUM` | `10` | 每次搜索的结果数，限制在 1–100 |
+| `SERPER_GL` / `SERPER_HL` | — | 国家 / 语言代码 |
+| `SERPER_TBS` | — | 时间筛选：`qdr:h`、`qdr:d`、`qdr:w`、`qdr:m`、`qdr:y` |
+
+### You.com
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `YOUCOM_COUNT` | `10` | 每个分区（网页、新闻各自）的结果数，限制在 1–100 |
+| `YOUCOM_EXTRACTION` | `highlights` | `highlights` 返回直接回答问题的段落，`none` 只给原始摘要，`full_page` 会抓取每个命中的页面并按实时抓取的页数计费 |
+| `YOUCOM_LANGUAGE` / `YOUCOM_COUNTRY` | — | 例如 `EN` / `US` |
+| `YOUCOM_FRESHNESS` | — | `day`、`week`、`month`、`year`，或 `YYYY-MM-DDtoYYYY-MM-DD` |
+
+## 一次查询的完整流程
+
+1. OpenCode 向选定的 provider 发起查询。
+2. 归一化后的查询（去首尾、压缩空白）先查内存缓存；命中则直接返回——重复查询免费且即时。
+3. 未命中时重新解析密钥，因此在 `/connect` 里轮换的 key 立即对下一次搜索生效。
+4. 发出请求；失败时会带上 HTTP 状态码和响应体，让你看到服务方到底说了什么。
+5. 响应经 schema 解码，映射为 `{ url, title, content, time }`，然后写入缓存。
+
+日期解析支持相对表述（`3 hours ago`、`3小时前`）、绝对格式（`Sep 30, 2026`、`31 Mar 2026`）和 ISO 8601。凡是宽松解析会凭空造出错误年份的字符串——比如 `Nov 1`，`Date.parse` 会读成 2001 年——一律丢弃，而不是返回一个错误的时间戳。
+
+## 排错
+
+```sh
+# 插件加载了吗？失败了吗？
+opencode plugin list
+
+# 搜索池里到底有哪些 provider？
+# 这里少了一家，说明它没有 key，或者被写进了 `disable`。
+opencode api get "/api/websearch/provider"
+```
+
+另外几个值得检查的地方：
+
+- **某家 provider 不在池里** —— 它没有 key。执行 `/connect` 或导出对应环境变量，然后重启；在 `/connect` 里做的凭据变更会自动重绑，不需要重启。
+- **搜索报错 `Connect X in /connect, or set X_API_KEY`** —— key 在绑定和搜索之间消失了。重新连接或重新导出。
+- **一切都很慢、或者积分烧得飞快** —— 把 `*_CACHE_TTL` 保持在默认值。时间窗内的重复查询由内存直接返回。
+- **改了插件文件却没反应** —— OpenCode 会监视插件并自动重载；如果没有，执行 `opencode service restart`。
+
+日志在 `~/.local/share/opencode/log/opencode.log`；过滤 `loading plugin` 可以看到 OpenCode 解析到的每个插件及其入口文件。
+
+## 开发
+
+```sh
+npm install
+npm run check     # 类型检查 + 测试
+```
+
+- `npm run typecheck` —— 对所有插件和测试做严格 TypeScript 检查。
+- `npm test` —— 覆盖通用 provider 契约、各家行为、日期解析、聚合注册，以及仓库结构守卫。
+
+`@opencode/plugin` 和 `effect` 声明为 **devDependencies**，而不是 `dependencies`。这两个模块由 OpenCode 在运行时提供——这正是单个 `.ts` 文件可以放进 `~/.config/opencode/plugins/` 且完全不需要 `node_modules` 的原因。若写成运行时依赖，`opencode plugin add` 会为了 100 KB 的插件源码安装 127 MB 的依赖树（仅 `effect` 就 47 MB，`@opencode/plugin` 还会拖进 `@aws-sdk`、`google-auth-library` 和 `@opentelemetry`）；放进 devDependencies 后，类型检查和测试照常可用，而使用者安装时拿不到这份依赖树。
+
+存在结构测试，是因为每个文件必须保持可独立复制：一旦某个插件开始 import 同级模块、共享代码块不再是逐字相同的副本、或者某家的 ID 出现偏移，测试就会失败。详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 许可证
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1,59 @@
+import { Plugin } from "@opencode/plugin/effect"
+import { Effect } from "effect"
+import type { Scope } from "effect"
+
+import { effect as anysearch } from "./plugins/anysearch-search"
+import { effect as brave } from "./plugins/brave-search"
+import { effect as jina } from "./plugins/jina-search"
+import { effect as linkup } from "./plugins/linkup-search"
+import { effect as metaso } from "./plugins/metaso-search"
+import { effect as querit } from "./plugins/querit-search"
+import { effect as serpapi } from "./plugins/serpapi-search"
+import { effect as serper } from "./plugins/serper-search"
+import { effect as youcom } from "./plugins/youcom-search"
+
+type ProviderEffect = (ctx: Plugin.Context) => Effect.Effect<void, never, Scope.Scope>
+
+/**
+ * The nine providers this package registers, in alphabetical order. Each entry
+ * is the same effect its standalone file uses as a default export, so a file
+ * copied out of this repository behaves exactly as it does here.
+ *
+ * The key of each entry is the websearch provider ID -- the one that appears in
+ * `/api/websearch/provider`, in `websearch.provider`, and in the `disable`
+ * option below. Renaming one would strand existing configuration.
+ */
+const PROVIDERS: ReadonlyArray<readonly [id: string, run: ProviderEffect]> = [
+  ["anysearch", anysearch],
+  ["brave", brave],
+  ["jina", jina],
+  ["linkup", linkup],
+  ["metaso", metaso],
+  ["querit", querit],
+  ["serpapi", serpapi],
+  ["serper", serper],
+  ["youcom", youcom],
+]
+
+/**
+ * Reads the `disable` plugin option. A key-requiring provider that is disabled
+ * here is never registered, which is how a user trims the pool down to the
+ * services they actually hold keys for.
+ */
+function disabledProviders(ctx: Plugin.Context): ReadonlySet<string> {
+  const requested: unknown = ctx.options["disable"]
+  if (!Array.isArray(requested)) return new Set()
+  return new Set(requested.filter((entry): entry is string => typeof entry === "string"))
+}
+
+export default Plugin.define({
+  id: "opencode-search-plugin",
+  effect: (ctx) =>
+    Effect.gen(function* () {
+      const disabled = disabledProviders(ctx)
+      for (const [id, run] of PROVIDERS) {
+        if (disabled.has(id)) continue
+        yield* run(ctx)
+      }
+    }),
+})

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "opencode-search-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Nine self-contained websearch provider plugins for OpenCode v2: AnySearch, Brave, Jina, Linkup, Metaso, Querit, SerpApi, Serper and You.com.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "websearch",
+    "search",
+    "serp",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guotree/opencode-search-plugin.git"
+  },
+  "homepage": "https://github.com/guotree/opencode-search-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/guotree/opencode-search-plugin/issues"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./anysearch-search": "./plugins/anysearch-search.ts",
+    "./brave-search": "./plugins/brave-search.ts",
+    "./jina-search": "./plugins/jina-search.ts",
+    "./linkup-search": "./plugins/linkup-search.ts",
+    "./metaso-search": "./plugins/metaso-search.ts",
+    "./querit-search": "./plugins/querit-search.ts",
+    "./serpapi-search": "./plugins/serpapi-search.ts",
+    "./serper-search": "./plugins/serper-search.ts",
+    "./youcom-search": "./plugins/youcom-search.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "plugins",
+    "index.ts",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "npm run typecheck && npm run test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "2.0.30",
+    "@types/node": "^26.6.5",
+    "effect": "4.0.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}