opencode-search-plugin 1.1.0 → 2.0.0

package/README.md

@@ -14,12 +14,12 @@ This repository adds plugins for ten more of them, taking the pool from five pro
 
 ## Install
 
-Three equivalent ways to install; pick one. **npm is recommended**: a version published to the registry is immutable, so a pinned `@1.1.0` always installs the same bytes, whereas a GitHub tag can in principle be moved by a maintainer to point at a different commit. The first two install the same complete package (all ten); use the third for one or two files only.
+Three equivalent ways to install; pick one. **npm is recommended**: a version published to the registry is immutable, so a pinned `@2.0.0` always installs the same bytes, whereas a GitHub tag can in principle be moved by a maintainer to point at a different commit. The first two install the same complete package (all ten); use the third for one or two files only.
 
 ### 1. From npm (recommended)
 
 ```sh
-# add @1.1.0 to pin
+# add @2.0.0 to pin
 opencode plugin add opencode-search-plugin
 ```
 
@@ -35,7 +35,7 @@ or declare it in `opencode.json(c)`:
 ### 2. From GitHub
 
 ```sh
-# add #v1.1.0 to pin
+# add #v2.0.0 to pin
 opencode plugin add github:guotree/opencode-search-plugin
 ```
 
@@ -74,7 +74,7 @@ Loading the package registers all ten, but a provider without a key never joins
   "plugins": [
     {
       "package": "opencode-search-plugin",
-      "options": { "disable": ["serper", "serpapi", "youcom"] }
+      "options": { "disable": ["osp-serper", "osp-serpapi", "osp-youcom"] }
     }
   ]
 }
@@ -93,7 +93,7 @@ opencode plugin update github:guotree/opencode-search-plugin
 opencode plugin update
 ```
 
-The target is the specifier that was configured: an npm install is named by its package name, a GitHub install answers only to its `github:` form — naming it by its bare package name fails with `Plugin is not configured`. Run `opencode plugin check` first to see what is outdated. An install without a pinned version follows new releases; a pinned one — `@1.1.0` on npm, `#v1.1.0` on GitHub — stays on its pin until you re-run `plugin add` with a newer pin or edit the specifier in `opencode.json(c)`. A locally copied file is upgraded by copying the new version over the old one.
+The target is the specifier that was configured: an npm install is named by its package name, a GitHub install answers only to its `github:` form — naming it by its bare package name fails with `Plugin is not configured`. Run `opencode plugin check` first to see what is outdated. An install without a pinned version follows new releases; a pinned one — `@2.0.0` on npm, `#v2.0.0` on GitHub — stays on its pin until you re-run `plugin add` with a newer pin or edit the specifier in `opencode.json(c)`. A locally copied file is upgraded by copying the new version over the old one.
 
 ## Uninstall
 
@@ -123,22 +123,24 @@ Once keys are in place, pick how OpenCode chooses among them:
 { "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.
+`random` spreads queries across every bound provider. Set it to a specific ID such as `"osp-brave"` to pin one, or `false` to turn web search off.
 
 ## Providers
 
+Every ID below carries an `osp-` prefix — this package's namespace. OpenCode's own providers register bare vendor names (`exa`, `tavily`), and a vendor's official plugin would do the same, so the prefix is what keeps those entries from colliding with ours — both in the websearch pool and in the `/connect` table, where credentials are keyed by integration ID. Use the prefixed form verbatim in `websearch.provider` and in `disable`.
+
 | 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 |
-| Keenable | `keenable` | `KEENABLE_API_KEY` | yes | 100,000 requests a month with a key; keyless tier is per IP |
-| 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 |
+| AnySearch | `osp-anysearch` | `ANYSEARCH_API_KEY` | yes | Free tier per IP; intent router, `cn`/`intl` zones |
+| Brave Search | `osp-brave` | `BRAVE_SEARCH_API_KEY` | no | Independent index, 20 results max |
+| Jina | `osp-jina` | `JINA_API_KEY` | no | Page content is opt-in because it is token-billed |
+| Keenable | `osp-keenable` | `KEENABLE_API_KEY` | yes | 100,000 requests a month with a key; keyless tier is per IP |
+| Linkup | `osp-linkup` | `LINKUP_API_KEY` | no | `flash`/`fast`/`standard`/`deep` reasoning depth |
+| Metaso | `osp-metaso` | `METASO_API_KEY` | no | Billed per search, not per result |
+| Querit | `osp-querit` | `QUERIT_API_KEY` | no | Falls back to sentence matches when a snippet is missing |
+| SerpApi | `osp-serpapi` | `SERPAPI_API_KEY` | no | Google via SerpApi; also has its own free 1-hour server cache |
+| Serper | `osp-serper` | `SERPER_API_KEY` | no | Google via Serper; billed per query in credits |
+| You.com | `osp-youcom` | `YDC_API_KEY` | no | Web and news merged; extraction modes |
 
 ## Configuration
 

package/README.zh-CN.md

@@ -14,12 +14,12 @@ OpenCode v2 内置了五个网页搜索 provider：`exa`、`firecrawl`、`parall
 
 ## 安装
 
-三种方式等价，任选其一。**推荐 npm**：已发布到 registry 的版本不可变，固定 `@1.1.0` 后每次安装都拿到同一份字节；GitHub 的 tag 在理论上可以被维护者移动、指向别的 commit。前两种装的是同一个完整包（十个全有），只想用一两个就用第三种。
+三种方式等价，任选其一。**推荐 npm**：已发布到 registry 的版本不可变，固定 `@2.0.0` 后每次安装都拿到同一份字节；GitHub 的 tag 在理论上可以被维护者移动、指向别的 commit。前两种装的是同一个完整包（十个全有），只想用一两个就用第三种。
 
 ### 1. 从 npm 安装（推荐）
 
 ```sh
-# 追加 @1.1.0 可固定到该版本
+# 追加 @2.0.0 可固定到该版本
 opencode plugin add opencode-search-plugin
 ```
 
@@ -35,7 +35,7 @@ opencode plugin add opencode-search-plugin
 ### 2. 从 GitHub 安装
 
 ```sh
-# 追加 #v1.1.0 可固定到该 tag
+# 追加 #v2.0.0 可固定到该 tag
 opencode plugin add github:guotree/opencode-search-plugin
 ```
 
@@ -74,7 +74,7 @@ opencode plugin add github:guotree/opencode-search-plugin
   "plugins": [
     {
       "package": "opencode-search-plugin",
-      "options": { "disable": ["serper", "serpapi", "youcom"] }
+      "options": { "disable": ["osp-serper", "osp-serpapi", "osp-youcom"] }
     }
   ]
 }
@@ -93,7 +93,7 @@ opencode plugin update github:guotree/opencode-search-plugin
 opencode plugin update
 ```
 
-升级目标用的是配置时的说明符：npm 安装用包名，GitHub 安装只认自己的 `github:` 形式——用裸包名会报 `Plugin is not configured`。先跑 `opencode plugin check` 查看有哪些过期。未固定版本的安装会跟上新版本；固定过的——npm 形式的 `@1.1.0`、GitHub 形式的 `#v1.1.0`——会停在原地，直到你用新 pin 重新执行 `plugin add`，或直接修改 `opencode.json(c)` 里的说明符。本地复制的文件则用新版本覆盖旧文件来升级。
+升级目标用的是配置时的说明符：npm 安装用包名，GitHub 安装只认自己的 `github:` 形式——用裸包名会报 `Plugin is not configured`。先跑 `opencode plugin check` 查看有哪些过期。未固定版本的安装会跟上新版本；固定过的——npm 形式的 `@2.0.0`、GitHub 形式的 `#v2.0.0`——会停在原地，直到你用新 pin 重新执行 `plugin add`，或直接修改 `opencode.json(c)` 里的说明符。本地复制的文件则用新版本覆盖旧文件来升级。
 
 ## 卸载
 
@@ -123,22 +123,24 @@ AnySearch 和 Keenable 是例外。两家都有匿名层级，因此始终注册
 { "websearch": { "provider": "random" } }
 ```
 
-`random` 会把查询分散到所有已绑定的 provider。填具体 ID（例如 `"brave"`）则固定用某一家，填 `false` 则完全关闭网页搜索。
+`random` 会把查询分散到所有已绑定的 provider。填具体 ID（例如 `"osp-brave"`）则固定用某一家，填 `false` 则完全关闭网页搜索。
 
 ## 支持的服务
 
+下表每个 ID 都带 `osp-` 前缀——这是本包的命名空间。OpenCode 内置 provider 用的是裸厂商名（`exa`、`tavily`），厂商自己的插件也会注册裸名（Keenable 就已经有一个），所以前缀是避免撞名的唯一保障：既避开搜索池里的重复，也避开 `/connect` 里按 integration ID 存凭据的那张表。在 `websearch.provider` 和 `disable` 里请原样使用带前缀的 ID。
+
 | 服务 | ID | 密钥（环境变量 / `/connect`） | 匿名可用 | 说明 |
 | --- | --- | --- | --- | --- |
-| AnySearch | `anysearch` | `ANYSEARCH_API_KEY` | 是 | 按 IP 的免费额度；意图路由，`cn` / `intl` 分区 |
-| Brave Search | `brave` | `BRAVE_SEARCH_API_KEY` | 否 | 独立索引，最多 20 条结果 |
-| Jina | `jina` | `JINA_API_KEY` | 否 | 页面正文按 token 计费，因此默认不取 |
-| Keenable | `keenable` | `KEENABLE_API_KEY` | 是 | 有 key 每月 100,000 次免费请求；无 key 层级按 IP 限速 |
-| 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` | 否 | 网页与新闻结果合并；多种正文抽取模式 |
+| AnySearch | `osp-anysearch` | `ANYSEARCH_API_KEY` | 是 | 按 IP 的免费额度；意图路由，`cn` / `intl` 分区 |
+| Brave Search | `osp-brave` | `BRAVE_SEARCH_API_KEY` | 否 | 独立索引，最多 20 条结果 |
+| Jina | `osp-jina` | `JINA_API_KEY` | 否 | 页面正文按 token 计费，因此默认不取 |
+| Keenable | `osp-keenable` | `KEENABLE_API_KEY` | 是 | 有 key 每月 100,000 次免费请求；无 key 层级按 IP 限速 |
+| Linkup | `osp-linkup` | `LINKUP_API_KEY` | 否 | `flash` / `fast` / `standard` / `deep` 四档推理深度 |
+| Metaso | `osp-metaso` | `METASO_API_KEY` | 否 | 按次搜索计费，不按结果条数 |
+| Querit | `osp-querit` | `QUERIT_API_KEY` | 否 | 摘要缺失时回退到句子级匹配 |
+| SerpApi | `osp-serpapi` | `SERPAPI_API_KEY` | 否 | 经 SerpApi 调用 Google；另有其自带的免费 1 小时服务端缓存 |
+| Serper | `osp-serper` | `SERPER_API_KEY` | 否 | 经 Serper 调用 Google；按查询消耗积分计费 |
+| You.com | `osp-youcom` | `YDC_API_KEY` | 否 | 网页与新闻结果合并；多种正文抽取模式 |
 
 ## 配置
 

package/index.ts

@@ -22,19 +22,20 @@ type ProviderEffect = (ctx: Plugin.Context) => Effect.Effect<void, never, Scope.
  *
  * 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.
+ * option below. Renaming one would strand existing configuration. Each is
+ * prefixed `osp-` to namespace it to this package; see CONTRIBUTING.md.
  */
 const PROVIDERS: ReadonlyArray<readonly [id: string, run: ProviderEffect]> = [
-  ["anysearch", anysearch],
-  ["brave", brave],
-  ["jina", jina],
-  ["keenable", keenable],
-  ["linkup", linkup],
-  ["metaso", metaso],
-  ["querit", querit],
-  ["serpapi", serpapi],
-  ["serper", serper],
-  ["youcom", youcom],
+  ["osp-anysearch", anysearch],
+  ["osp-brave", brave],
+  ["osp-jina", jina],
+  ["osp-keenable", keenable],
+  ["osp-linkup", linkup],
+  ["osp-metaso", metaso],
+  ["osp-querit", querit],
+  ["osp-serpapi", serpapi],
+  ["osp-serper", serper],
+  ["osp-youcom", youcom],
 ]
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-search-plugin",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Ten self-contained websearch provider plugins for OpenCode v2: AnySearch, Brave, Jina, Keenable, Linkup, Metaso, Querit, SerpApi, Serper and You.com.",
   "type": "module",
   "license": "MIT",

package/plugins/anysearch-search.ts

@@ -27,7 +27,10 @@ const AnySearchResponse = Schema.Struct({
 })
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "anysearch"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `anysearch` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-anysearch"
 
 // AnySearch returns no publication date, so results carry an empty time record.
 function toResult(item: {

package/plugins/brave-search.ts

@@ -21,7 +21,10 @@ const BraveResponse = Schema.Struct({
 })
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "brave"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `brave` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-brave"
 
 function envInt(name: string, fallback: number): number {
   const raw = (process.env[name] ?? "").trim()

package/plugins/jina-search.ts

@@ -21,7 +21,10 @@ const JinaResponse = Schema.Struct({
 })
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "jina"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `jina` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-jina"
 
 // Jina returns no publication date on search hits, so results carry an empty
 // time record rather than a parsed one.

package/plugins/keenable-search.ts

@@ -23,7 +23,10 @@ const KeenableResponse = Schema.Struct({
 })
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "keenable"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `keenable` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-keenable"
 
 // Keenable returns ISO 8601 timestamps, which the parser below accepts as-is.
 // See https://serpapi.com/blog/how-to-parse-dates-from-google-search/

package/plugins/linkup-search.ts

@@ -18,7 +18,10 @@ const LinkupResponse = Schema.Struct({
 })
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "linkup"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `linkup` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-linkup"
 
 function toResult(item: typeof LinkupResult.Type) {
   return {

package/plugins/metaso-search.ts

@@ -16,7 +16,10 @@ const MetasoResponse = Schema.Struct({
 })
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "metaso"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `metaso` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-metaso"
 
 function envInt(name: string, fallback: number): number {
   const raw = (process.env[name] ?? "").trim()

package/plugins/querit-search.ts

@@ -24,7 +24,10 @@ const QueritResponse = Schema.Struct({
 })
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "querit"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `querit` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-querit"
 
 // search_id is documented as both a string and an integer, so read it loosely
 // rather than letting a strict decode reject an otherwise good response.

package/plugins/serpapi-search.ts

@@ -19,7 +19,10 @@ const SerpApiResponse = Schema.Struct({
 })
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "serpapi"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `serpapi` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-serpapi"
 
 function envInt(name: string, fallback: number): number {
   const raw = (process.env[name] ?? "").trim()

package/plugins/serper-search.ts

@@ -19,7 +19,10 @@ const SerperResponse = Schema.Struct({
 })
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "serper"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `serper` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-serper"
 
 function envInt(name: string, fallback: number): number {
   const raw = (process.env[name] ?? "").trim()

package/plugins/youcom-search.ts

@@ -40,7 +40,10 @@ const YouResponse = Schema.Struct({
 type YouHit = typeof YouResult.Type
 
 // The /connect integration ID, and the websearch provider ID it binds to.
-const ID = "youcom"
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, so `youcom` would collide
+// with them, and with the opencode.db row keyed by integration ID.
+const ID = "osp-youcom"
 
 function envInt(name: string, fallback: number): number {
   const raw = (process.env[name] ?? "").trim()