opencode-search-plugin 1.0.1 → 2.0.0

package/README.md

@@ -2,30 +2,45 @@
 
 **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.
+Ten 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 ten.
 
-[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/)
+[AnySearch](https://www.anysearch.com/) · [Brave Search](https://brave.com/search/api/) · [Jina](https://jina.ai/) · [Keenable](https://keenable.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.
+This repository adds plugins for ten more of them, taking the pool from five providers to fifteen. AnySearch and Keenable run 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
+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.
 
-```sh
-# from GitHub (add #v1.0.1 to pin)
-opencode plugin add github:guotree/opencode-search-plugin
+### 1. From npm (recommended)
 
-# or from npm (add @1.0.1 to pin)
+```sh
+# add @2.0.0 to pin
 opencode plugin add opencode-search-plugin
 ```
 
 or declare it in `opencode.json(c)`:
 
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-search-plugin"]
+}
+```
+
+### 2. From GitHub
+
+```sh
+# add #v2.0.0 to pin
+opencode plugin add github:guotree/opencode-search-plugin
+```
+
+or declare it in `opencode.json(c)`:
+
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
@@ -33,7 +48,7 @@ or declare it in `opencode.json(c)`:
 }
 ```
 
-### One or two, by copying a file
+### 3. 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:
 
@@ -52,31 +67,55 @@ For a location that is not auto-discovered, list it explicitly:
 
 ### 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:
+Loading the package registers all ten, 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"] }
+      "package": "opencode-search-plugin",
+      "options": { "disable": ["osp-serper", "osp-serpapi", "osp-youcom"] }
     }
   ]
 }
 ```
 
-`disable` takes the provider IDs listed in the table below.
+`disable` takes the provider IDs listed in the table below. AnySearch and Keenable need no key, so `disable` is the only way to keep those two out of the pool.
+
+## Upgrade
+
+```sh
+# installed from npm
+opencode plugin update opencode-search-plugin
+# installed from GitHub
+opencode plugin update github:guotree/opencode-search-plugin
+# everything outdated
+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 — `@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
+
+```sh
+# installed from npm
+opencode plugin remove opencode-search-plugin
+# installed from GitHub
+opencode plugin remove github:guotree/opencode-search-plugin
+```
+
+The same rule: pass the specifier you installed with. The command edits the global configuration; if the plugin is instead a `plugins` entry in `opencode.json(c)` or a locally copied file, delete the entry or the copied `.ts` file. Saved `/connect` credentials are untouched — a reinstall finds them again — and to turn off a few providers instead of the whole plugin, use `disable` above.
 
 ## Keys
 
-Every provider except AnySearch needs an API key. Give it one of two ways:
+Every provider except AnySearch and Keenable 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.
+AnySearch and Keenable are the exceptions. Both have an anonymous tier, so they are always registered and only attach their credential header when a key exists. For Keenable the two tiers draw on separate budgets: a key spends the free allowance of 100,000 requests a month, while a keyless call goes to the `/public` endpoint instead and is metered by rate — 1,000 requests an hour and 10 a second per IP, on a pool shared with everyone else on your egress address. A key is what makes that shared headroom irrelevant.
 
 Once keys are in place, pick how OpenCode chooses among them:
 
@@ -84,27 +123,30 @@ 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 |
-| 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
 
 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
+### Shared by all ten
 
 | Variable | Default | Meaning |
 | --- | --- | --- |
@@ -139,6 +181,15 @@ Knobs are environment variables, read once when OpenCode starts — change one a
 | `JINA_GL` / `JINA_HL` | — | Country / language code |
 | `JINA_LOCATION` | — | City-level origin to simulate, e.g. `Berlin` |
 
+### Keenable
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `KEENABLE_MAX_RESULTS` | `10` | Results per search, clamped to 1–50 |
+| `KEENABLE_MODE` | — | `pro` (deeper retrieval) or `realtime` (fastest); unset leaves Keenable's own default |
+| `KEENABLE_TITLE` | `opencode-search-plugin` | App name sent as `X-Keenable-Title`, which the keyless endpoint requires to attribute the call |
+| `KEENABLE_API_KEY` | — | Optional; keyless access works without it |
+
 ### Linkup
 
 | Variable | Default | Meaning |
@@ -203,12 +254,14 @@ opencode plugin list
 
 # Which providers are actually in the pool?
 # A provider missing here has no key, or is listed in `disable`.
+# AnySearch and Keenable are always present, since neither needs one.
 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 `Keenable rate limited the request (HTTP 429)`** — the keyless pool is capped at 1,000 requests an hour and 10 a second per IP, shared with the rest of your egress address. Set `KEENABLE_API_KEY` to draw on your own allowance instead.
 - **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`.

package/README.zh-CN.md

@@ -2,30 +2,45 @@
 
 # opencode-search-plugin
 
-九个相互独立的 [OpenCode](https://opencode.ai) v2 插件，各自注册一个网页搜索 provider。每个文件都能单独使用：复制一个进你的插件目录，或者安装这个包一次拿全九个。
+十个相互独立的 [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/)
+[AnySearch](https://www.anysearch.com/) · [Brave Search](https://brave.com/search/api/) · [Jina](https://jina.ai/) · [Keenable](https://keenable.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 之后才会绑定，因此装上这个包也不会把查询路由到一个注定失败的服务上。至于哪几家值得用，取决于它们各自当前的免费额度，长期依赖某家之前建议先确认它的定价。
+本仓库为其中十家补上了插件，把可用池从五个 provider 扩到十五个。AnySearch 和 Keenable 无需任何 key 即可使用；其余八家只在你提供 key 之后才会绑定，因此装上这个包也不会把查询路由到一个注定失败的服务上。至于哪几家值得用，取决于它们各自当前的免费额度，长期依赖某家之前建议先确认它的定价。
 
 ## 安装
 
-### 一次性装全九个：包安装
+三种方式等价，任选其一。**推荐 npm**：已发布到 registry 的版本不可变，固定 `@2.0.0` 后每次安装都拿到同一份字节；GitHub 的 tag 在理论上可以被维护者移动、指向别的 commit。前两种装的是同一个完整包（十个全有），只想用一两个就用第三种。
 
-```sh
-# 从 GitHub 安装（追加 #v1.0.1 可固定到该 tag）
-opencode plugin add github:guotree/opencode-search-plugin
+### 1. 从 npm 安装（推荐）
 
-# 或从 npm 安装（追加 @1.0.1 可固定到该版本）
+```sh
+# 追加 @2.0.0 可固定到该版本
 opencode plugin add opencode-search-plugin
 ```
 
 或者写进 `opencode.json(c)`：
 
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-search-plugin"]
+}
+```
+
+### 2. 从 GitHub 安装
+
+```sh
+# 追加 #v2.0.0 可固定到该 tag
+opencode plugin add github:guotree/opencode-search-plugin
+```
+
+或者写进 `opencode.json(c)`：
+
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
@@ -33,7 +48,7 @@ opencode plugin add opencode-search-plugin
 }
 ```
 
-### 只要一两个：直接复制文件
+### 3. 本地复制文件
 
 每个插件都是单个 `.ts` 文件，没有相对导入，也没有构建步骤。放进 OpenCode 会自动发现插件的位置即可：
 
@@ -52,31 +67,55 @@ opencode plugin add opencode-search-plugin
 
 ### 跳过你没有 key 的服务
 
-装包会注册全部九家，但没有 key 的 provider 永远不会进入搜索池——见下文[密钥](#密钥)。想让它们连注册表都不出现：
+装包会注册全部十家，但没有 key 的 provider 永远不会进入搜索池——见下文[密钥](#密钥)。想让它们连注册表都不出现：
 
 ```jsonc
 {
   "plugins": [
     {
-      "package": "github:guotree/opencode-search-plugin",
-      "options": { "disable": ["serper", "serpapi", "youcom"] }
+      "package": "opencode-search-plugin",
+      "options": { "disable": ["osp-serper", "osp-serpapi", "osp-youcom"] }
     }
   ]
 }
 ```
 
-`disable` 填的是下表中的 provider ID。
+`disable` 填的是下表中的 provider ID。AnySearch 和 Keenable 不需要 key，想把这两家也排除在搜索池之外，只能用 `disable`。
+
+## 升级
+
+```sh
+# 从 npm 安装的
+opencode plugin update opencode-search-plugin
+# 从 GitHub 安装的
+opencode plugin update github:guotree/opencode-search-plugin
+# 更新所有过期插件
+opencode plugin update
+```
+
+升级目标用的是配置时的说明符：npm 安装用包名，GitHub 安装只认自己的 `github:` 形式——用裸包名会报 `Plugin is not configured`。先跑 `opencode plugin check` 查看有哪些过期。未固定版本的安装会跟上新版本；固定过的——npm 形式的 `@2.0.0`、GitHub 形式的 `#v2.0.0`——会停在原地，直到你用新 pin 重新执行 `plugin add`，或直接修改 `opencode.json(c)` 里的说明符。本地复制的文件则用新版本覆盖旧文件来升级。
+
+## 卸载
+
+```sh
+# 从 npm 安装的
+opencode plugin remove opencode-search-plugin
+# 从 GitHub 安装的
+opencode plugin remove github:guotree/opencode-search-plugin
+```
+
+同上：传入安装时使用的说明符。该命令修改的是全局配置；若插件是写在 `opencode.json(c)` 的 `plugins` 条目里或本地复制的文件，删掉对应条目、或删掉复制的 `.ts` 文件即可。`/connect` 里保存的密钥不受影响——重新装回就能继续用——只想关掉其中几家而不是整个插件，用上文的 `disable`。
 
 ## 密钥
 
-除 AnySearch 外，每家服务都需要 API key。两种给法二选一：
+除 AnySearch 和 Keenable 外，每家服务都需要 API key。两种给法二选一：
 
 - **OpenCode 内的 `/connect`** —— 按 provider 存储，轮换后无需重启，且不受环境变量变动影响。
 - **环境变量** —— 作为兜底读取，因此在无界面和 CI 场景下也能工作。
 
 没有 key 的 provider 会保持未绑定状态：它不在 websearch 池中，所以 `"provider": "random"` 绝不会把查询路由到一个注定失败的服务上。
 
-AnySearch 是例外。它有匿名额度，因此始终注册，只有存在 key 时才附带 `Authorization` 头。
+AnySearch 和 Keenable 是例外。两家都有匿名层级，因此始终注册，只有存在 key 时才附带各自的凭据头。Keenable 的两层额度互不通用：有 key 时消耗每月 100,000 次的免费额度，无 key 的请求则改走 `/public` 端点，按速率限制——每个 IP 每小时 1,000 次、每秒 10 次，且与同一出口地址上的所有人共用。想摆脱这个共享池的不确定性，就得配一把 key。
 
 密钥就位后，再决定 OpenCode 如何在它们之间做选择：
 
@@ -84,27 +123,30 @@ AnySearch 是例外。它有匿名额度，因此始终注册，只有存在 key
 { "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 计费，因此默认不取 |
-| 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` | 否 | 网页与新闻结果合并；多种正文抽取模式 |
 
 ## 配置
 
 所有配置项都是环境变量，OpenCode 启动时读取一次——改了要重启。默认值取自各家 API 文档，所以一开始什么都不设就是合理的起点。
 
-### 九家通用
+### 十家通用
 
 | 变量 | 默认值 | 含义 |
 | --- | --- | --- |
@@ -139,6 +181,15 @@ AnySearch 是例外。它有匿名额度，因此始终注册，只有存在 key
 | `JINA_GL` / `JINA_HL` | — | 国家 / 语言代码 |
 | `JINA_LOCATION` | — | 模拟的城市级来源，例如 `Berlin` |
 
+### Keenable
+
+| 变量 | 默认值 | 含义 |
+| --- | --- | --- |
+| `KEENABLE_MAX_RESULTS` | `10` | 每次搜索的结果数，限制在 1–50 |
+| `KEENABLE_MODE` | — | `pro`（更深的检索）或 `realtime`（最快）；不设则沿用 Keenable 自己的默认值 |
+| `KEENABLE_TITLE` | `opencode-search-plugin` | 作为 `X-Keenable-Title` 发出的应用名，无 key 端点靠它归属调用方 |
+| `KEENABLE_API_KEY` | — | 可选；不设也能匿名使用 |
+
 ### Linkup
 
 | 变量 | 默认值 | 含义 |
@@ -203,12 +254,14 @@ opencode plugin list
 
 # 搜索池里到底有哪些 provider？
 # 这里少了一家，说明它没有 key，或者被写进了 `disable`。
+# AnySearch 和 Keenable 永远在列，因为它们都不需要 key。
 opencode api get "/api/websearch/provider"
 ```
 
 另外几个值得检查的地方：
 
 - **某家 provider 不在池里** —— 它没有 key。执行 `/connect` 或导出对应环境变量，然后重启；在 `/connect` 里做的凭据变更会自动重绑，不需要重启。
+- **搜索报错 `Keenable rate limited the request (HTTP 429)`** —— 无 key 层级每个 IP 每小时 1,000 次、每秒 10 次，且与同一出口地址上的其他人共用。改用 `KEENABLE_API_KEY` 就会记到你自己的额度上。
 - **搜索报错 `Connect X in /connect, or set X_API_KEY`** —— key 在绑定和搜索之间消失了。重新连接或重新导出。
 - **一切都很慢、或者积分烧得飞快** —— 把 `*_CACHE_TTL` 保持在默认值。时间窗内的重复查询由内存直接返回。
 - **改了插件文件却没反应** —— OpenCode 会监视插件并自动重载；如果没有，执行 `opencode service restart`。

package/index.ts

@@ -5,6 +5,7 @@ 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 keenable } from "./plugins/keenable-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"
@@ -15,24 +16,26 @@ 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
+ * The ten 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.
+ * 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],
-  ["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,7 +1,7 @@
 {
   "name": "opencode-search-plugin",
-  "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.",
+  "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",
   "keywords": [
@@ -25,6 +25,7 @@
     "./anysearch-search": "./plugins/anysearch-search.ts",
     "./brave-search": "./plugins/brave-search.ts",
     "./jina-search": "./plugins/jina-search.ts",
+    "./keenable-search": "./plugins/keenable-search.ts",
     "./linkup-search": "./plugins/linkup-search.ts",
     "./metaso-search": "./plugins/metaso-search.ts",
     "./querit-search": "./plugins/querit-search.ts",

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

@@ -0,0 +1,280 @@
+import { Plugin } from "@opencode/plugin/effect"
+import { Effect, Schema } from "effect"
+
+// Keenable answers with a flat object: `results` carries ranked hits, `mode`
+// echoes the tier that served the call, and there is no failure envelope --
+// refusals arrive as plain HTTP statuses. Every field but the URL is optional,
+// and a missing one means "Keenable provided none", not an error.
+const KeenableResponse = Schema.Struct({
+  query: Schema.optional(Schema.String),
+  mode: Schema.optional(Schema.String),
+  results: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        title: Schema.optional(Schema.String),
+        url: Schema.String,
+        description: Schema.optional(Schema.String),
+        snippet: Schema.optional(Schema.String),
+        published_at: Schema.optional(Schema.String),
+        acquired_at: Schema.optional(Schema.String),
+      }),
+    ),
+  ),
+})
+
+// The /connect integration ID, and the websearch provider ID it binds to.
+// 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/
+const RELATIVE_MS: Record<string, number> = {
+  minute: 60_000,
+  hour: 3_600_000,
+  day: 86_400_000,
+  week: 604_800_000,
+  month: 2_592_000_000,
+  year: 31_536_000_000,
+  分钟: 60_000,
+  小时: 3_600_000,
+  天: 86_400_000,
+  周: 604_800_000,
+  个月: 2_592_000_000,
+  月: 2_592_000_000,
+  年: 31_536_000_000,
+}
+
+const RELATIVE_DATE =
+  /^(\d+)\s*(minute|hour|day|week|month|year|分钟|小时|天|周|个月|月|年)s?\s*(?:ago|前)$/i
+
+const ABSOLUTE_DATE = [
+  /^\d{1,2}\s+[A-Za-z]{3,9}\s+\d{4}$/, // "3 Jan 2022", "31 Mar 2026"
+  /^[A-Za-z]{3,9}\s+\d{1,2},?\s+\d{4}$/, // "Sep 30, 2026", "Jan 27, 2025"
+  /^\d{4}-\d{2}-\d{2}$/, // "2026-10-16"
+  // ISO 8601 with a time component, which Keenable returns on `published_at`.
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$/,
+]
+
+function parseSearchDate(value: string | undefined): number {
+  const text = value?.trim()
+  if (!text) return NaN
+
+  const relative = RELATIVE_DATE.exec(text)
+  if (relative) {
+    const unit = relative[2] !== undefined ? RELATIVE_MS[relative[2].toLowerCase()] : undefined
+    const amount = Number(relative[1])
+    if (unit === undefined || !Number.isFinite(amount)) return NaN
+    return Date.now() - amount * unit
+  }
+
+  // Only trust Date.parse on shapes these providers actually emit -- its lenient
+  // parser invents a year for strings like "Nov 1", which would date the result
+  // to 2001.
+  return ABSOLUTE_DATE.some((shape) => shape.test(text)) ? Date.parse(text) : NaN
+}
+
+function toResult(item: {
+  title?: string | undefined
+  url: string
+  description?: string | undefined
+  snippet?: string | undefined
+  published_at?: string | undefined
+}) {
+  const published = parseSearchDate(item.published_at)
+  return {
+    url: item.url,
+    title: item.title || item.url,
+    // The snippet is the longer excerpt, so it is the better answer to give an
+    // agent; the description is the short summary behind it, and Keenable often
+    // returns it empty -- `||`, not `??`, so an empty snippet still falls back.
+    content: item.snippet || item.description || "",
+    time: Number.isFinite(published) ? { published } : {},
+  }
+}
+
+type SearchResult = ReturnType<typeof toResult>
+
+function envInt(name: string, fallback: number): number {
+  const raw = (process.env[name] ?? "").trim()
+  if (raw === "") return fallback
+  const value = Number(raw)
+  return Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
+function envStr(name: string): string {
+  return (process.env[name] ?? "").trim()
+}
+
+// Keenable has two tiers that draw on separate budgets. With a key, a call is
+// metered against the free monthly allowance of 100,000 requests per
+// organization. Without one, a call goes to the `/public` twin of each endpoint
+// and is limited per IP instead -- 1,000 an hour and 10 a second on a pool
+// shared with everyone else on the egress address -- and spends no credits.
+// A missing key therefore routes elsewhere rather than failing, which is why
+// this provider never gates on `bound`. Knobs are read once at load time,
+// restart after changing them.
+//
+//   KEENABLE_CACHE_TTL    ms to reuse a response for the same query (0 disables)
+//   KEENABLE_MAX_RESULTS  results per search, clamped to 1-50 (the API's range)
+//   KEENABLE_MODE         "pro" for deeper retrieval, "realtime" for speed;
+//                         leave unset and the organization's default applies
+//   KEENABLE_TITLE        app name sent as X-Keenable-Title, which the keyless
+//                         endpoint requires to attribute traffic (max 256 chars)
+//   KEENABLE_API_KEY      optional; keyless access works without it
+const CACHE_TTL = envInt("KEENABLE_CACHE_TTL", 600_000)
+const SEARCH_SIZE = Math.min(Math.max(envInt("KEENABLE_MAX_RESULTS", 10), 1), 50)
+const MODE = envStr("KEENABLE_MODE")
+const TITLE = (envStr("KEENABLE_TITLE") || "opencode-search-plugin").slice(0, 256)
+
+const SEARCH_URL = "https://api.keenable.ai/v1/search"
+const PUBLIC_URL = "https://api.keenable.ai/v1/search/public"
+
+const CACHE_LIMIT = 200
+const cache = new Map<string, { at: number; results: SearchResult[] }>()
+
+function cacheKey(query: string): string {
+  return query.trim().replace(/\s+/g, " ")
+}
+
+function readCache(queryKey: string): SearchResult[] | undefined {
+  if (CACHE_TTL <= 0) return undefined
+  const hit = cache.get(queryKey)
+  return hit && Date.now() - hit.at < CACHE_TTL ? hit.results : undefined
+}
+
+function writeCache(queryKey: string, results: SearchResult[]): void {
+  if (CACHE_TTL <= 0) return
+  cache.set(queryKey, { at: Date.now(), results })
+  if (cache.size > CACHE_LIMIT) {
+    const oldest = cache.keys().next().value
+    if (oldest !== undefined) cache.delete(oldest)
+  }
+}
+
+// Unlike the key-requiring providers in this repo, Keenable never gates on
+// `bound`: keyless access is a first-class mode, so the provider is always in
+// the pool. The key is still read per call, which is why no credential-event
+// subscription is needed -- a rotated key takes effect on the next search
+// without a reload.
+export const effect = (ctx: Plugin.Context) =>
+  Effect.gen(function* () {
+    // Make "Keenable" show up in /connect with an API-key method.
+    yield* ctx.integration.transform((editor) => {
+      editor.update(ID, (integration) => {
+        integration.name = "Keenable"
+      })
+      editor.method.update({
+        integrationID: ID,
+        method: { type: "key", label: "Keenable API key" },
+      })
+      editor.method.update({
+        integrationID: ID,
+        method: { type: "env", names: ["KEENABLE_API_KEY"] },
+      })
+    })
+
+    // The host instantiates this API's failure channel as `unknown`, which would
+    // make the whole plugin effect unrunnable. A credential read must never take
+    // the plugin down: a failed read degrades to "no stored key", and the
+    // environment fallback below applies exactly as it does when the credential
+    // simply does not exist.
+    const soften = <A>(read: Effect.Effect<A, unknown>): Effect.Effect<A | undefined, never> =>
+      read.pipe(Effect.catch(() => Effect.succeed(undefined)))
+
+    yield* ctx.websearch.transform((editor) => {
+      editor.add({
+        id: ID,
+        name: "Keenable",
+        execute: ({ query }) =>
+          Effect.gen(function* () {
+            const queryKey = cacheKey(query)
+            const cached = readCache(queryKey)
+            if (cached) return cached
+
+            // Keyless access is a first-class mode, so a missing key is not an
+            // error: it only moves the request to the `/public` endpoint.
+            const connection = yield* soften(ctx.integration.connection.active(ID))
+            const credential = connection
+              ? yield* soften(ctx.integration.connection.resolve(connection))
+              : undefined
+            const key =
+              credential?.type === "key" ? credential.key : process.env.KEENABLE_API_KEY
+
+            const headers: Record<string, string> = {
+              Accept: "application/json",
+              "Content-Type": "application/json",
+              // Required by the keyless endpoint, where an absent value is a
+              // 400. It names the calling application rather than the user, so
+              // it rides along with a key too.
+              "X-Keenable-Title": TITLE,
+            }
+            if (key) headers["X-API-Key"] = key
+
+            const response = yield* Effect.tryPromise({
+              try: () =>
+                fetch(key ? SEARCH_URL : PUBLIC_URL, {
+                  method: "POST",
+                  headers,
+                  body: JSON.stringify({
+                    query: queryKey,
+                    max_results: SEARCH_SIZE,
+                    ...(MODE ? { mode: MODE } : {}),
+                  }),
+                }),
+              catch: (error) => new Error("Keenable request failed: " + String(error)),
+            })
+
+            if (!response.ok) {
+              // Only a keyed call is metered, so only a keyed call can exhaust
+              // the monthly allowance. The keyless pool is limited by rate, so
+              // it answers 429 instead.
+              if (response.status === 402 && key) {
+                return yield* Effect.fail(
+                  new Error(
+                    "Keenable credits exhausted (HTTP 402): the free monthly " +
+                      "allowance of 100,000 requests is spent. Connect Keenable " +
+                      "in /connect or set KEENABLE_API_KEY to buy credits, or " +
+                      "wait for the allowance to reset.",
+                  ),
+                )
+              }
+              if (response.status === 429) {
+                const retry = response.headers.get("Retry-After")
+                return yield* Effect.fail(
+                  new Error(
+                    "Keenable rate limited the request (HTTP 429)" +
+                      (retry ? ", retry after " + retry + "s" : "") +
+                      (key
+                        ? ""
+                        : ". The keyless pool allows 1,000 requests an hour and " +
+                          "10 a second per IP; set KEENABLE_API_KEY to spend your " +
+                          "own 100,000-request monthly allowance instead."),
+                  ),
+                )
+              }
+              const detail = yield* Effect.tryPromise({
+                try: () => response.text(),
+                catch: () => new Error("response body unavailable"),
+              })
+              return yield* Effect.fail(
+                new Error("Keenable API error " + response.status + ": " + detail),
+              )
+            }
+
+            const json = yield* Effect.tryPromise({
+              try: () => response.json(),
+              catch: (error) => new Error("Invalid Keenable response: " + String(error)),
+            })
+
+            const body = yield* Schema.decodeUnknownEffect(KeenableResponse)(json)
+            const results = (body.results ?? []).map(toResult)
+            writeCache(queryKey, results)
+            return results
+          }),
+      })
+    })
+  })
+
+export default Plugin.define({ id: "keenable-search", effect })

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()