bookmark-research 0.6.0 → 0.7.0

package/.agents/plugins/marketplace.json

@@ -9,7 +9,7 @@
       "source": {
         "source": "npm",
         "package": "bookmark-research",
-        "version": "0.6.0",
+        "version": "0.7.0",
         "registry": "https://registry.npmjs.org"
       },
       "policy": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bookmark-research",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
   "author": {
     "name": "kwenxu"
@@ -41,6 +41,9 @@
         "TAVILY_API_KEY",
         "JINA_API_KEY",
         "DEEPSEEK_API_KEY",
+        "PERPLEXITY_API_KEY",
+        "XAI_API_KEY",
+        "CUSTOM_AGENTIC_API_KEY",
         "OPENAI_API_KEY",
         "SystemRoot",
         "windir"

package/README.md

@@ -16,7 +16,7 @@ The stable release includes bilingual Canvas package support, safer Exa batch re
 ## How it works
 
 - **Local understanding.** A Bookmark Canvas package is read as structure, not a flat URL list: card and group layout, edges with their direction and labels, and the same bookmark appearing across cards (spatial context); dated fields, protocol-defined date segments in IDs, and Git commits that changed content (temporal context). These queries run offline.
-- **External research takes one of three routes.** Reading a known URL needs no reasoning; agentic search has the host model plan, search, read and follow the gaps; deep research can use the OpenAI or Parallel research API directly. Persistent inventories and coverage checks are available when you explicitly need a complete collection audit. Host browsers and crawlers can supply source text.
+- **External research takes one of three routes.** Reading a known URL needs no reasoning; agentic search has the host model plan, search, read and follow the gaps; deep research can use the OpenAI or Parallel research API directly. `search_web` aggregates configured URL providers such as Perplexity Search; `agentic_search` can return a separate Grok or user-configured OpenAI-compatible model answer and citations. Custom model search depends on the selected upstream's web capability and is not URL-fused. Persistent inventories and coverage checks are available when you explicitly need a complete collection audit. Host browsers and crawlers can supply source text.
 - **Reviewed knowledge store.** Finished research can be compiled into a Wiki of reviewed pages with revisions and links, reused by later questions instead of searching the web again.
 
 ## Requirements
@@ -43,11 +43,12 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 1. **Clients** — arrow keys and Space to toggle; detected CLIs are preselected. The install plan is shown for confirmation.
 2. **Research depth (optional)** — leave `auto` and the depth is picked from each request; set `quick`, `agentic` or `deep` only to pin one default.
 3. **Answer and report language** — follow the question, Chinese or English.
-4. **Search and page-reading services** — one ordered multiselect. Unselected providers become the fallback search tier.
+4. **Search sources** — one ordered multiselect. Unselected providers become the fallback search tier. Perplexity is search-only; page reading uses a separate provider.
 5. **Storage** — the default data folder, one custom folder for archives and reports, or reports beside the bookmark file or folder.
 6. **Optional professional APIs** — off by default: OpenAI Deep Research or the Parallel Task API.
-7. **API keys** — one hidden prompt per selected key, checked immediately; every key is optional.
-8. **Service check** — runs on its own and reports each provider; a sample search/read test is opt-in.
+7. **Custom model endpoint (optional)** — enter a compatible Base URL, model and protocol; web-search support depends on the upstream.
+8. **API keys** — select the variables for services you enabled (Space to toggle, Enter to continue), then enter each value in a hidden prompt; optional and skippable. Values are saved separately from preferences.
+9. **Service check** — reports configured providers; a sample search/read test is opt-in.
 
 Enter keeps the highlighted value, so a full run can be just a few keystrokes. Then start a new client session so the Skill and MCP tools load. Wiki follow-up suggests retention and honors existing authorization. Optional service diagnostics retain a 15-minute cache.
 
@@ -92,9 +93,10 @@ Install notes:
 | Menu | `bookmark-research` · `bookmark` · `bookmark research` |
 | Clients, preferences, storage, recent research, key status | `bookmark-research status` |
 | Scripted preferences | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
+| Configuration JSON guide and example | [Guide](docs/configuration.en.md) · [Partial JSON](config/settings.example.json) |
 | Update or verify all clients | `bookmark-research update` · `bookmark-research verify` |
 
-Use `npx bookmark-research@latest …` if the command is not installed globally. Preferences and keys are user-wide, so one change applies to every installed client; start a new client session afterwards. `--lang zh` shows the wizard and menu in Chinese. The default `quick` preset exposes 21 everyday tools. Use `bookmark-research config set --tool-scope-preset deep` for the full 43-tool catalog when a persistent collection audit is needed. An explicit `tool_scope` list still overrides the preset.
+Use `npx bookmark-research@latest …` if the command is not installed globally. Preferences and keys are user-wide, so one change applies to every installed client; start a new client session afterwards. `--lang zh` shows the wizard and menu in Chinese. The default `quick` preset exposes 22 everyday tools. Use `bookmark-research config set --tool-scope-preset deep` for the full 44-tool catalog when a persistent collection audit is needed. An explicit `tool_scope` list still overrides the preset.
 
 **Update.** Run `npx bookmark-research@latest install` and confirm the upgrade/overwrite plan to adopt the latest release for your installed clients. For Codex without prompts, use `npx bookmark-research@latest install codex --non-interactive --replace-source`. `bookmark-research update` refreshes the recorded source: Git/npm selectors follow their selected ref, while a bundled build or pinned release stays on that build. Both paths preserve preferences, keys and data. Start a new host session afterwards.
 
@@ -107,9 +109,12 @@ Use `npx bookmark-research@latest …` if the command is not installed globally.
 | `TAVILY_API_KEY` | Tavily search fallback and extraction | Keyless mode |
 | `JINA_API_KEY` | Jina search | Jina Reader still reads pages anonymously |
 | `DEEPSEEK_API_KEY` | Optional DeepSeek Search / Fetch | Not selected; other providers still work |
+| `PERPLEXITY_API_KEY` | Optional Perplexity structured Search | Search results only; no page extraction |
+| `XAI_API_KEY` | Optional Grok Agentic search | Separate `agentic_search` answer channel; not URL-fused |
+| `CUSTOM_AGENTIC_API_KEY` | Optional user-configured OpenAI-compatible endpoint | Separate `agentic_search` channel; set Base URL/model/protocol in setup |
 | `OPENAI_API_KEY` | Optional OpenAI Deep Research runs | Feature off; host-led research still works |
 
-Keys are never accepted in chat, command arguments or JSON files. Preferences can also be changed by asking the agent in a client session ("Show Bookmark Research settings", "Use only Exa for future searches"); it uses the `update_settings` tool.
+At the setup key step, select the keys for enabled services with Space, then enter each key at the hidden prompt; leave the selection empty to skip. Keys go to the separate private `credentials.json` or can come from environment variables, which take precedence. They are not part of `prefs.json` or `settings.json`; the settings JSON import rejects credential fields. Preferences can also be changed by asking the agent in a client session ("Show Bookmark Research settings", "Use only Exa for future searches"); it uses the `update_settings` tool. See the [configuration guide](docs/configuration.en.md) for every key and service.
 
 ## Where data is stored
 
@@ -142,9 +147,10 @@ A bundle of one Skill, one local MCP server, and the remote MCPs and services th
 | Layer | Component | Runs as | Setup |
 | --- | --- | --- | --- |
 | Skill | [`bookmark-research`](skills/bookmark-research/SKILL.md) and method references, each with a [Chinese copy](skills/bookmark-research/references/zh/skill-guide.md) | Loaded by the client | None |
-| Local MCP | `bookmark-research`, 21 default tools (below) | Python process started by the client | Installed for you |
+| Local MCP | `bookmark-research`, 22 default tools (below) | Python process started by the client | Installed for you |
 | Remote MCPs, called by the local MCP | [Exa](https://exa.ai) (search, page reading), [Parallel](https://parallel.ai) (search, fallback reading), [Tavily](https://tavily.com) (search fallback) | HTTPS, no local process | Optional API keys |
-| HTTP services, called by the local MCP | [Jina Reader](https://jina.ai/reader) (fallback reading; search with a key); [DeepSeek Search / Fetch](https://api-docs.deepseek.com/guides/search/) (optional; raw JSON tools API) | HTTPS | Optional `JINA_API_KEY`, `DEEPSEEK_API_KEY` |
+| HTTP services, called by the local MCP | [Jina Reader](https://jina.ai/reader) (fallback reading; search with a key); [DeepSeek Search / Fetch](https://api-docs.deepseek.com/guides/search/); [Perplexity Search](https://docs.perplexity.ai/api-reference/search-post) (structured results only) | HTTPS | Optional provider keys |
+| Model search API | [xAI Grok Responses](https://docs.x.ai/developers/tools/web-search) with optional Web Search and X Search | HTTPS | Optional `XAI_API_KEY`; invoked separately via `agentic_search` |
 | Optional client MCPs | Exa Agent, Parallel Task MCP, Tavily Research | Added to your client by you | `bookmark-research setup` shows the steps |
 
 Default MCP tools:
@@ -152,7 +158,7 @@ Default MCP tools:
 | Group | Tools |
 | --- | --- |
 | Canvas context | `sync_package`, `index_status`, `search_bookmarks`, `get_context`, `plan_research` |
-| Web and archives | `search_web`, `fetch_web`, `search_archive` |
+| Web and archives | `search_web`, `agentic_search`, `fetch_web`, `search_archive` |
 | Wiki | `wiki_write`, `wiki_get`, `wiki_list`, `wiki_search` |
 | Research API | `research_services`, `research_service_prepare`, `_start`, `_status`, `_result`, `_cancel`, `_attach` |
 | Settings | `get_settings`, `update_settings` |

package/README.zh.md

@@ -16,7 +16,7 @@
 ## 它是怎么工作的
 
 - **本地理解层。** 数据包按结构读，而不是一张平铺的 URL 清单：卡片与分组的位置、连线的方向与标签、同一书签在不同卡片的出现位置（空间上下文）；日期字段、ID 中协议定义的日期段，以及真正改过内容的 Git 提交（时间上下文）。这些都是离线查询。
-- **外部调研走三条路线。** 读取已知 URL 不需要推理；Agentic 搜索由宿主模型自己规划、搜索、阅读并追查缺口；Deep Research 可直接调用 OpenAI／Parallel 研究 API；完整清单与覆盖审计在明确需要时启用。宿主已有的浏览器与爬虫可提供来源正文。
+- **外部调研走三条路线。** 读取已知 URL 不需要推理；Agentic 搜索由宿主模型自己规划、搜索、阅读并追查缺口；Deep Research 可直接调用 OpenAI／Parallel 研究 API；完整清单与覆盖审计在明确需要时启用。`search_web` 聚合已配置的 URL 搜索来源（可选 Perplexity Search）；`agentic_search` 可按需返回 Grok 或用户自定义 OpenAI 兼容模型的回答与引用。自定义模型是否真正联网取决于上游能力，且不参加 URL 排名。
 - **可复核的知识存储。** 完成的研究可以沉淀成 Wiki：带历史版本和相互链接的已审核页面，之后提问直接复用，不必重新搜索网页。
 
 ## 环境要求
@@ -43,11 +43,12 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 1. **装到哪些宿主** —— 方向键移动、空格勾选；检测到的 CLI 默认已勾选，随后显示安装计划让你确认。
 2. **默认研究深度（可选）** —— 保持 `auto` 就会按每次请求自动定档；只有想钉死一个默认时才改成 `quick`、`agentic` 或 `deep`。
 3. **答复和报告语言** —— 跟随提问语言、中文或英文。
-4. **搜索与正文读取服务** —— 一个有序多选列表；未选中的服务自动作为备用搜索层。
+4. **搜索来源** —— 一个有序多选列表；未选中的服务自动作为备用搜索层。Perplexity 只提供搜索结果，网页读取由其他服务完成。
 5. **存放位置** —— 默认数据目录、自定义统一目录（归档与研究报告），或研究报告放在书签文件／文件夹旁边。
 6. **可选专业研究 API** —— 默认关闭：OpenAI Deep Research 或 Parallel Task API。
-7. **API Key** —— 逐个隐藏输入，当场检查；全部可选，可整段跳过。
-8. **服务检查** —— 自动运行并逐个报告；样例搜索／阅读自检需另行选择。
+7. **自定义模型端点（可选）** —— 输入兼容 Base URL、模型和协议；联网能力取决于上游。
+8. **API Key** —— 空格勾选上面所选服务需要的 Key，回车继续，再逐个隐藏输入；全部可选，可跳过。Key 与偏好分开保存。
+9. **服务检查** —— 报告已配置服务；样例搜索／阅读自检需另行选择。
 
 回车即保留当前选项，所以整轮可能只需按几次回车。装好后新建一个宿主会话，让 Skill 和 MCP 工具生效。Wiki 默认建议整理；已有保存授权时直接执行。服务诊断保留 15 分钟缓存，按需调用。
 
@@ -91,9 +92,10 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 | 打开菜单 | `bookmark-research` · `bookmark` · `bookmark research` |
 | 查看已装宿主、偏好、保存位置、最近研究、Key 状态 | `bookmark-research status` |
 | 用脚本改偏好 | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
+| JSON 配置说明与示例 | [配置指南](docs/configuration.md) · [部分配置 JSON](config/settings.example.json) |
 | 更新或验证所有宿主 | `bookmark-research update` · `bookmark-research verify` |
 
-没有全局安装时，在前面加 `npx bookmark-research@latest`。偏好和 Key 是用户级的，改一次就对所有已安装宿主生效；改完新建宿主会话即可。加 `--lang zh` 可让向导和菜单显示中文。工具面可用 `bookmark-research config set --tool-scope-preset quick` 使用默认 21 个日常工具；`deep`（或 `all`）启用完整 43 个工具，供明确需要的完整资料审计使用。显式 `tool_scope` 仍优先于预设。
+没有全局安装时，在前面加 `npx bookmark-research@latest`。偏好和 Key 是用户级的，改一次就对所有已安装宿主生效；改完新建宿主会话即可。加 `--lang zh` 可让向导和菜单显示中文。工具面可用 `bookmark-research config set --tool-scope-preset quick` 使用默认 22 个日常工具；`deep`（或 `all`）启用完整 44 个工具，供明确需要的完整资料审计使用。显式 `tool_scope` 仍优先于预设。
 
 **更新。** 运行 `npx bookmark-research@latest install`，在向导中确认升级覆盖，即可为已安装宿主采用最新发布版。Codex 无交互升级可用 `npx bookmark-research@latest install codex --non-interactive --replace-source`。`bookmark-research update` 刷新的是已登记来源：Git／npm 选择器沿用所选 ref，随包保留的构建或固定版本仍留在该构建。两种方式均保留偏好、Key 和数据；完成后新建宿主会话。
 
@@ -106,9 +108,12 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 | `TAVILY_API_KEY` | Tavily 备用搜索与提取 | 使用免 Key 模式 |
 | `JINA_API_KEY` | Jina 搜索 | Jina Reader 仍可匿名读取网页 |
 | `DEEPSEEK_API_KEY` | 可选的 DeepSeek Search / Fetch | 不选择即可；其他 provider 仍可用 |
+| `PERPLEXITY_API_KEY` | 可选的 Perplexity 结构化 Search | 只提供搜索来源，不提供网页抓取 |
+| `XAI_API_KEY` | 可选的 Grok Agentic 搜索 | 独立 `agentic_search` 工具，不参与 URL 聚合 |
+| `CUSTOM_AGENTIC_API_KEY` | 可选的用户自定义 OpenAI 兼容端点 | 单独的 `agentic_search` 通道；在 setup 中配置 Base URL／模型／协议 |
 | `OPENAI_API_KEY` | 可选的 OpenAI Deep Research 任务 | 功能关闭；宿主自己的研究不受影响 |
 
-Key 不接受对话、命令参数或 JSON 文件。偏好也可以直接在宿主会话里让 agent 改（「显示 Bookmark Research 的配置」「以后只用 Exa 搜索」），它会调用 `update_settings` 工具。
+在 setup 的密钥步骤，用空格勾选已启用服务所需的 Key，再在隐藏输入框逐个输入；不选即可跳过。Key 保存在独立的私有 `credentials.json`，也可由环境变量提供，且环境变量优先。Key 不放进 `prefs.json` 或 `settings.json`；设置 JSON 导入会拒绝凭据字段。每个 Key 对应的服务见[配置指南](docs/configuration.md)。偏好也可以直接在宿主会话里让 agent 改（「显示 Bookmark Research 的配置」「以后只用 Exa 搜索」），它会调用 `update_settings` 工具。
 
 ## 数据保存在哪里
 
@@ -141,9 +146,11 @@ Key 不接受对话、命令参数或 JSON 文件。偏好也可以直接在宿
 | 层 | 组成 | 运行方式 | 需要配置 |
 | --- | --- | --- | --- |
 | Skill | [`bookmark-research`](skills/bookmark-research/SKILL.md) 及 11 份方法参考，每份都有[中文版](skills/bookmark-research/references/zh/skill-guide.md) | 由宿主加载 | 不需要 |
-| 本地 MCP | `bookmark-research`，默认 21 个工具（见下表） | 宿主启动的 Python 进程 | 安装器自动完成 |
+| 本地 MCP | `bookmark-research`，默认 22 个工具（见下表） | 宿主启动的 Python 进程 | 安装器自动完成 |
 | 本地 MCP 调用的远程 MCP | [Exa](https://exa.ai)（搜索、网页读取）、[Parallel](https://parallel.ai)（搜索、备用读取）、[Tavily](https://tavily.com)（备用搜索） | HTTPS，不启动本地进程 | 可选 API Key |
-| 本地 MCP 调用的 HTTP 服务 | [Jina Reader](https://jina.ai/reader)（备用读取；有 Key 时可搜索）；[DeepSeek Search / Fetch](https://api-docs.deepseek.com/guides/search/)（可选；原始 JSON tools API） | HTTPS | 可选 `JINA_API_KEY`、`DEEPSEEK_API_KEY` |
+| 本地 MCP 调用的 HTTP 服务 | [Jina Reader](https://jina.ai/reader)（备用读取；有 Key 时可搜索）；[DeepSeek Search / Fetch](https://api-docs.deepseek.com/guides/search/)；[Perplexity Search](https://docs.perplexity.ai/api-reference/search-post)（结构化结果） | HTTPS | 可选 provider Key |
+| 模型搜索 API | [xAI Grok Responses](https://docs.x.ai/developers/tools/web-search)，可选网页与 X 搜索 | HTTPS | 可选 `XAI_API_KEY`；通过独立 `agentic_search` 调用 |
+| 自定义模型 API | 用户配置的 OpenAI 兼容 Chat Completions／Responses 端点 | 用户配置的 HTTP(S) Base URL | `CUSTOM_AGENTIC_API_KEY`；须配置模型与协议，联网由上游决定 |
 | 可选的宿主 MCP | Exa Agent、Parallel Task MCP、Tavily Research | 需自行加到宿主里 | `bookmark-research setup` 会给出步骤 |
 
 本地 MCP 的工具：
@@ -151,7 +158,7 @@ Key 不接受对话、命令参数或 JSON 文件。偏好也可以直接在宿
 | 分类 | 工具 |
 | --- | --- |
 | 画布上下文 | `sync_package`、`index_status`、`search_bookmarks`、`get_context`、`plan_research` |
-| 联网与归档 | `search_web`、`fetch_web`、`search_archive` |
+| 联网与归档 | `search_web`、`agentic_search`、`fetch_web`、`search_archive` |
 | Wiki | `wiki_write`、`wiki_get`、`wiki_list`、`wiki_search` |
 | 研究 API | `research_services`、`research_service_prepare`、`_start`、`_status`、`_result`、`_cancel`、`_attach` |
 | 配置 | `get_settings`、`update_settings` |

package/config/providers.json

@@ -104,6 +104,32 @@
       "required_env": {"search": "DEEPSEEK_API_KEY", "fetch": "DEEPSEEK_API_KEY"},
       "authentication": "Bearer DEEPSEEK_API_KEY. Raw JSON Search/Fetch API; OpenAI-compatible error shape. Search costs $0.75 per 1,000 successful requests (official docs).",
       "docs": "https://api-docs.deepseek.com/guides/search/"
+    },
+    "perplexity": {
+      "label": "Perplexity Search",
+      "url": "https://api.perplexity.ai/search",
+      "transport": "http",
+      "client": "perplexity",
+      "search_url": "https://api.perplexity.ai/search",
+      "search_tools": ["perplexity_search"],
+      "fetch_tools": [],
+      "direct_client": true,
+      "optional_bearer_env": "PERPLEXITY_API_KEY",
+      "required_env": {"search": "PERPLEXITY_API_KEY"},
+      "authentication": "Bearer PERPLEXITY_API_KEY. Structured Search API results; does not generate an answer or fetch arbitrary URLs.",
+      "docs": "https://docs.perplexity.ai/api-reference/search-post"
+    },
+    "browser": {
+      "label": "Local Browser Renderer",
+      "url": "http://127.0.0.1:9222",
+      "transport": "http",
+      "client": "browser",
+      "search_tools": [],
+      "fetch_tools": ["browser_render"],
+      "direct_client": true,
+      "optional_bearer_env": null,
+      "authentication": "Optional local browser execution via CDP or Playwright. Disabled by default; explicit setting required. No cloud credentials needed.",
+      "docs": "https://chromedevtools.github.io/devtools-protocol/"
     }
   },
   "default_providers": [

package/config/settings.example.json

@@ -0,0 +1,36 @@
+{
+  "research": {
+    "depth": "auto",
+    "prefer_host_workflows": true,
+    "response_language": "auto",
+    "methods": ["comparative_analysis", "fact_check", "benchmark_review"]
+  },
+  "search": {
+    "providers": ["exa", "parallel", "perplexity"],
+    "fallback_providers": ["tavily", "jina"],
+    "limit_per_target": 5,
+    "strategy": "hedged"
+  },
+  "fetch": {
+    "provider": "exa",
+    "providers": ["exa", "parallel", "jina"],
+    "strategy": "staggered",
+    "max_characters": 12000
+  },
+  "custom_agentic": {
+    "enabled": false,
+    "base_url": "https://gateway.example/v1",
+    "model": "provider/model-name",
+    "api_mode": "chat_completions",
+    "search_mode": "prompt"
+  },
+  "archive": {
+    "enabled": true
+  },
+  "wiki": {
+    "after_research": "suggest"
+  },
+  "output": {
+    "mode": "central"
+  }
+}

package/docs/bookmark-research-architecture.md

@@ -6,8 +6,8 @@ Codex、Claude Code、DeepSeek Harness 负责推理、工具选择、并发和
 2. **外部调研**：已知 URL 直接读取；Agentic Search 由宿主判断缺口并迭代搜索／阅读，插件提供补充搜索、并发抓取与归档。Deep Research 可直接提交 OpenAI／Parallel API，无需本地研究会话。宿主已有的浏览器、爬虫或研究工具也可供稿。
 3. **LLM Wiki**：检索已有知识，一次提交正文与精确引用，保留来源、修订和页面关系，供后续调研复用。
 
-日常流程是：**取上下文 → 独立检索 Wiki／归档 → 阅读与搜索 → 宿主形成结论 → 按授权保存 Wiki**。`plan_research` 只提供候选，既不设相关性硬门槛，也不决定研究路线；没有书签命中仍会查询其他存储。默认工具面为 21 个。
+日常流程是：**取上下文 → 独立检索 Wiki／归档 → 阅读与搜索 → 宿主形成结论 → 按授权保存 Wiki**。`plan_research` 只提供候选，既不设相关性硬门槛，也不决定研究路线；没有书签命中仍会查询其他存储。默认工具面为 22 个。`search_web` 聚合插件管理的 URL provider；Perplexity Search 返回结构化来源。Grok 和自定义 OpenAI 兼容端点通过 `agentic_search` 独立返回模型回答与引用，引用未经独立核验，不参加 URL 排名。宿主和其他 MCP 工具仍由宿主模型编排。
 
-只有明确要求整包覆盖、持久化任务或中断后续做时，启用 `deep` 预设的完整 43 个工具及分组工作流。高级功能复用现有证据与存储；普通提问不要求经过 readiness、route、inventory 或 coverage 等阶段。
+只有明确要求整包覆盖、持久化任务或中断后续做时，启用 `deep` 预设的完整 44 个工具及分组工作流。高级功能复用现有证据与存储；普通提问不要求经过 readiness、route、inventory 或 coverage 等阶段。
 
 Wiki 一次写入采用 `page.sections[].citations` 与顶层 `sources`，也兼容旧的 research claim 引用格式。程序校验引文与来源完整性，语义支持由宿主或人工审阅。API 报告是二手来源，关键结论仍应核查原文。

package/docs/canvas-tree-reading-acceptance.md

@@ -0,0 +1,98 @@
+# Bookmark Canvas 树状定位手动验收
+
+本文用于在两个 GitHub 仓库的改动推送后，安装本地 Bookmark Research npm 包并重启 Codex 后验收。验收范围是新 AGENTS 模板对 Agent 的约束，以及 Bookmark Research 插件的局部树查询约束。它不验证浏览器导出代码是否已清理历史占位字段，也不授权修改书签包。
+
+## 测试前准备
+
+测试数据目录：`<画布包目录>`（例如 `~/Bookmark-Canvas/bookmark/书签画布`）。换环境时替换为实际画布包目录。
+
+1. 确认两个仓库的模板与插件改动已推送。
+2. 使用 Bookmark Research 仓库生成的本地 `.tgz` 安装/升级 Codex 插件，不从 npm 拉取线上版本。
+3. 完全退出并重启 Codex，重新打开测试数据目录对应的会话。
+4. 测试前记录包内文件列表及目标 JSON 的字节大小。不要把全包或大 JSON 全文贴进对话。
+5. 选择一个含多个层级的临时栏目 JSON。记录文件路径、栏目 ID、目标 folder/bookmark ID，以及目标附近的父子关系，作为本地核对依据。
+
+小型 JSON 可直接读入上下文；大型 JSON 必须由本地解析工具或插件索引读取必要节点。测试过程只读，不写回源文件。
+
+## 场景 A：仅模板，无 Bookmark Research 插件
+
+在 Codex 中关闭或暂时不可用 Bookmark Research MCP/Skill，只保留画布包提供的 AGENTS 模板及本地文件/终端工具。提交以下提示：
+
+> 请按当前画布包的 AGENTS 模板，只读检查临时栏目中的目标书签。先确认目标文件大小；小文件可直接阅读，大文件请用本地解析工具按目标 ID 或标题定位，不要把整份 JSON 输出到对话。按显式 `type` 区分 folder 和 bookmark，不要因 folder 有 `url: ""` 或 bookmark 有 `children: []` 而误判。请返回源文件路径、栏目/section ID、目标 item ID、准确的父级路径、同级顺序、目标的必要字段，以及为回答读取了哪些父子节点、还有哪些范围未读取。不要改文件；没有 `.canvas` 证据时不要描述卡片坐标或空间关系。
+
+分别选择一个目标书签和一个目标文件夹运行。文件夹测试需说明其直接子项与更深后代的区别；同名候选存在时必须列出候选并用 ID/路径消歧，不能按标题猜唯一结果。
+
+**通过标准**
+
+- 使用本地解析/读取工具，且大型文件没有全文进入对话上下文。
+- 目标类型以显式 `type` 判定，空占位字段没有改变判型。
+- 返回的文件路径、ID、父路径和同级顺序能与源 JSON 核对一致。
+- 明确区分已读取与未读取范围；不把局部样本称作全量检查。
+- 源文件在测试前后保持不变；不臆造 `.canvas` 坐标、分组或连线。
+
+## 场景 B：模板与 Bookmark Research 插件共同工作
+
+启用本地安装的 Bookmark Research 插件并重启 Codex。先让 Agent 报告本会话中实际可调用的 Skill/MCP 工具；不能仅凭安装成功推断工具已经加载。随后提交：
+
+> 请依照当前画布包的 AGENTS 模板，只读定位临时栏目中这个目标：`<填入目标书签标题或 item ID>`。优先使用当前会话实际可调用的 Bookmark Research 查询工具；先从指定包/source 找到唯一栏目和 section ID，再按 item ID 读取目标及祖先路径。如果目标是文件夹，请用 `folder_id` 查询其子树并按页读取，只取回答所需节点。明确报告查询的 source/section/item ID、父路径、同级位置、已读条数、总数与 `next_offset`/未读范围。请核对临时项按 `type` 判型，忽略空 `url`/`children` 对类型的干扰。插件结果是索引投影，不要将其当作完整源对象；不要修改文件。若工具不可调用，请说明并退回场景 A 的本地解析流程。
+
+至少执行三次查询：一条已知书签 ID；一个有多层后代的文件夹 ID；一个同名或重复 URL 候选（若数据中存在）。文件夹查询使用有限页大小，至少一次停在非空 `next_offset`，然后继续翻页确认分页边界。
+
+**通过标准**
+
+- 工具来自当前重启后的 Codex 会话，且检索的 source 与实际包一致；没有可用工具时清楚回退。
+- 定点结果的祖先链与 `folder_id` 子树结果能用源 JSON 核验；分页的 `total`、每页条数和下一页偏移一致。
+- 搜索结果保持书签实例、URL 和不同栏目/路径的区别；重复标题或 URL 不被错误合并为一个位置。
+- 条目投影不把空 folder URL 当作链接，也不把 bookmark 的空 children 当作文件夹；原始文件中的这些字段仍然保留。
+- 测试前后源包无变化；没有把精简索引结果写回 JSON，也没有声称未读取部分已检查。
+
+## 场景 C：增量同步（新增书签秒级可见）
+
+在已配置为 live 模式的画布包某栏目 JSON 中，手动追加一条带有唯一标题和 URL 的测试书签（记录其 item ID、title、url 及所属父节点）。
+在 Codex 中不显式执行 `sync_package`，也不重启插件，直接提交提示词：
+
+> 请定位刚在临时栏目中新增的书签：`<填入新增书签标题或 item ID>`。使用 Bookmark Research 查询工具读取其完整层级路径、父节点与同级位置。明确报告该书签当前的 revision、所在 section ID 及父路径。
+
+**通过标准**
+
+- 监控与查询层自动触发增量刷新，新增书签在秒级内可被检索工具定位。
+- 检索返回的新增书签路径、父节点及同级索引与手动编辑的源 JSON 完全一致。
+- 仅被修改文件的书签条目其 `revision` 发生递增，画布包内其他未修改文件的条目其 `revision` 与状态保持稳定。
+- 画布包内所有源文件保持只读，未被插件回写或篡改。
+
+## 场景 D：多源去重与合并（同路径重复源清理与唯一性）
+
+针对同一画布包路径下重复注册了多个旧源（例如 `index_status` 报告同路径存在多个 source_id，或旧源带着包内已不存在的文件而导致 `retained_missing_files` 非空）的场景：
+
+1. 先使用 CLI 进行干跑比对：
+   ```sh
+   python3 src/cli.py source merge <重复源ID> <保留源ID>
+   ```
+2. 确认计数与版本一致后执行正式合并（若内容哈希冲突则改用确认移除）：
+   ```sh
+   python3 src/cli.py source merge <重复源ID> <保留源ID> --confirm
+   # 或
+   python3 src/cli.py source remove <重复源ID> --confirm
+   ```
+3. 在 Codex 中提交提示：
+   ```
+   请检查当前的索引状态及源列表，确认画布包对应的源是否已唯一，且 retained_missing_files 是否已归零。
+   ```
+
+**通过标准**
+
+- 目标路径仅保留一个唯一的有效 source_id，重复源被完全移除或合并。
+- 运行 `index_status` 后，所有源的 `retained_missing_files` 计数均为 0。
+- 合并/清理后，条目检索与上下文定位均指向唯一保留源，不存在跨源冗余命中或已废弃文件的陈旧投影。
+- 整个清理过程未对画布包物理文件产生任何写操作。
+
+## 记录结果
+
+每个场景记录：Codex 会话日期、插件工具是否实际可用、测试文件大小、目标 ID、期望路径、Agent 返回路径、分页/未读范围、源文件是否变化，以及通过/失败和复现步骤。失败时保留最小提示词、目标文件相对路径与相关 ID；不要复制整份用户 JSON 到 issue 或测试文档。
+
+| 场景 | 插件实际可用 | 定点路径正确 | 分页/范围正确 | 占位字段判型正确 | 源文件未变 | 结果/备注 |
+| --- | --- | --- | --- | --- | --- | --- |
+| A：仅模板 | 否 | 待测 | 待测 | 待测 | 待测 | 待测 |
+| B：模板 + 插件 | 待测 | 待测 | 待测 | 待测 | 待测 | 待测 |
+| C：增量同步 | 待测 | 待测 | 待测 | 待测 | 待测 | 待测 |
+| D：多源去重 | 待测 | 待测 | 待测 | 待测 | 待测 | 待测 |

package/docs/configuration.en.md

@@ -0,0 +1,70 @@
+# User Settings JSON
+
+[中文](configuration.md) · **English**
+
+Bookmark Research keeps its cross-host preferences in its own `settings.json`. Configure them in the terminal wizard during installation, rerun `bookmark-research setup`, or copy and import the [partial JSON example](../config/settings.example.json). The default path is `~/.config/bookmark-research/settings.json`; `BOOKMARK_RESEARCH_CONFIG` or `XDG_CONFIG_HOME` can change it. Multiple hosts can share settings by using the same path.
+
+```sh
+bookmark-research config show
+bookmark-research config set --input /absolute/path/to/my-settings.json
+```
+
+`config set` merges the fields in this partial JSON and keeps settings you did not include. Provider names and choices go in `settings.json`; API keys go in a separate `credentials.json` beside it, or can be entered through the hidden `setup` prompt or supplied as environment variables. Environment variables take precedence. `config set --input` imports preferences only and rejects key fields. `config show` displays effective settings and the config path, never key values.
+
+## What Belongs Here
+
+Use this file for long-term preferences and connection parameters that Bookmark Research reads directly:
+
+- Search and reading sources: `search.providers`, `search.fallback_providers`, `fetch.provider`, `fetch.providers` and concurrency strategies. Perplexity provides structured URL search, not page extraction.
+- User preferences: `research.depth`, `research.response_language`, `research.methods`, `archive.enabled`, `wiki.after_research`, `output.mode`, cache and limit settings, and readiness checks.
+- Model endpoints: Base URL, model ID, protocol and search mode under `custom_agentic`. It returns a separate model answer through `agentic_search` and is not fused into `search_web` URL results.
+- Professional research APIs called directly by this plugin: the OpenAI Deep Research or Parallel Task API selection under `professional_research`.
+
+`config/settings.example.json` is an importable partial config; remove or change fields to suit your setup. Values must match the current settings schema. Invalid settings are rejected. For defaults, field details and the complete effective settings shape, see the [settings and archives reference](../skills/bookmark-research/references/settings-and-archive.md).
+
+## MCP And Credentials
+
+Do not put every MCP in the plugin's `settings.json`. MCPs launched or authorized directly by the host, such as Exa Agent, Parallel Task and Tavily Research, use host-specific endpoint, command, OAuth and header formats managed by Codex, Claude Code or DSH. The installer/setup can show connection steps, but the plugin JSON does not register host MCPs or store their OAuth credentials.
+
+When Bookmark Research calls a service through its own API, its selection and non-secret connection settings can live here; the key stays separate. For example:
+
+```json
+{
+  "custom_agentic": {
+    "enabled": true,
+    "base_url": "https://gateway.example/v1",
+    "model": "provider/model-name",
+    "api_mode": "responses",
+    "search_mode": "native"
+  }
+}
+```
+
+`search_mode: "native"` requests the Responses `web_search` tool and requires upstream support. Chat Completions can only be prompted to search; it cannot guarantee that the upstream will go online. Set the key separately as `CUSTOM_AGENTIC_API_KEY`; never put it in JSON, command-line arguments or chat.
+
+Bookmark Research accepts these API keys for its service adapters. Configure only the keys your selected services need. The setup prompt hides input and saves it for you. You can also maintain the credentials JSON directly:
+
+| Key | Service called by the plugin |
+| --- | --- |
+| `EXA_API_KEY` | Exa search and page reading |
+| `PARALLEL_API_KEY` | Parallel search and page reading |
+| `TAVILY_API_KEY` | Tavily fallback search and extraction |
+| `JINA_API_KEY` | Jina Search; Reader can fetch anonymously |
+| `DEEPSEEK_API_KEY` | DeepSeek Search / Fetch |
+| `PERPLEXITY_API_KEY` | Perplexity structured Search |
+| `XAI_API_KEY` | Grok `agentic_search` |
+| `CUSTOM_AGENTIC_API_KEY` | Custom OpenAI-compatible model endpoint |
+| `OPENAI_API_KEY` | OpenAI Deep Research |
+
+```json
+{
+  "EXA_API_KEY": "your-exa-key",
+  "PARALLEL_API_KEY": "your-parallel-key",
+  "PERPLEXITY_API_KEY": "your-perplexity-key",
+  "CUSTOM_AGENTIC_API_KEY": "your-custom-endpoint-key"
+}
+```
+
+The default path is `~/.config/bookmark-research/credentials.json`. This is an unencrypted local file and must have mode `0600` (owner-readable only). Use `setup` to save keys so the permissions are set correctly. Set `BOOKMARK_RESEARCH_CREDENTIALS` to change its path. Host-launched MCPs do not read this file; configure their keys through the host's own mechanism.
+
+You can also ask the host to call `update_settings` for a lasting preference or run `bookmark-research config show` to inspect the current config. Installation and update receipts print this guide and the command to reopen setup.

package/docs/configuration.md

@@ -0,0 +1,70 @@
+# 用户配置 JSON
+
+[English](configuration.en.md) · **中文**
+
+Bookmark Research 使用一份插件自己的 `settings.json` 保存跨宿主共享的偏好。首次安装可在终端向导中配置；之后可运行 `bookmark-research setup`，或复制本页的 [部分配置示例](../config/settings.example.json) 并导入。配置路径默认为 `~/.config/bookmark-research/settings.json`，可用 `BOOKMARK_RESEARCH_CONFIG` 或 `XDG_CONFIG_HOME` 更改。多个宿主使用同一路径即可共享设置。
+
+```sh
+bookmark-research config show
+bookmark-research config set --input /absolute/path/to/my-settings.json
+```
+
+`config set` 会按字段合并示例里的部分 JSON，不会清掉未提及的设置。provider 名称和选择写在 `settings.json`；API Key 放在同目录的独立 `credentials.json`，也可通过 `setup` 隐藏输入或环境变量设置；环境变量优先。`config set --input` 只导入偏好，不接受 Key。`config show` 会显示生效后的设置和配置路径，不显示密钥。
+
+## 放在这份 JSON 中的内容
+
+这份文件适合保存 Bookmark Research 自己读取的长期偏好和连接参数：
+
+- 搜索与读取来源：`search.providers`、`search.fallback_providers`、`fetch.provider`、`fetch.providers` 和并发策略。Perplexity 可用于结构化 URL 搜索，不能作为网页正文读取器。
+- 用户习惯：`research.depth`、`research.response_language`、`research.methods`、`archive.enabled`、`wiki.after_research`、`output.mode` 以及缓存、限额和可用性检查选项。
+- 模型端点：`custom_agentic` 中的 Base URL、模型名、协议和搜索模式。它通过独立 `agentic_search` 返回模型回答，不参加 `search_web` 的 URL 聚合。
+- 插件直接调用的专业研究服务：`professional_research` 中的 OpenAI Deep Research 或 Parallel Task API 选择。
+
+`config/settings.example.json` 是可导入的部分配置，可按需删除或修改字段。字段必须符合当前版本的设置 schema；无效值会被拒绝。配置项说明、默认值和完整有效设置结构见 [配置与归档参考](../skills/bookmark-research/references/zh/settings-and-archive.md)。
+
+## MCP 与认证的边界
+
+不要把所有 MCP 都塞进插件的 `settings.json`。Exa Agent、Parallel Task、Tavily Research 等由宿主直接启动或授权的 MCP，其 endpoint、启动命令、OAuth 和 header 格式由 Codex、Claude Code 或 DSH 自己管理；不同宿主格式不同，OAuth 凭据也应留在宿主。安装器/向导可以给出对应的接入步骤，但插件 JSON 不会注册或保存这些 host MCP。
+
+如果某个服务由 Bookmark Research 自己通过 API 调用，它的选择和非敏感连接参数可以保存在插件 JSON 中，密钥仍单独管理。例如自定义模型：
+
+```json
+{
+  "custom_agentic": {
+    "enabled": true,
+    "base_url": "https://gateway.example/v1",
+    "model": "provider/model-name",
+    "api_mode": "responses",
+    "search_mode": "native"
+  }
+}
+```
+
+`search_mode: "native"` 会请求 Responses `web_search` 工具，需要上游实现该工具；Chat Completions 只能提示上游搜索，不能保证它联网。把对应密钥单独设置为 `CUSTOM_AGENTIC_API_KEY`，不要写入 JSON、命令行参数或对话。
+
+插件支持的 API Key 与服务对应如下。只需配置已启用服务所需的 Key；用 `bookmark-research setup` 输入时会隐藏显示并自动保存。也可以手动维护凭据 JSON：
+
+| Key | 插件调用的服务 |
+| --- | --- |
+| `EXA_API_KEY` | Exa 搜索与网页读取 |
+| `PARALLEL_API_KEY` | Parallel 搜索与网页读取 |
+| `TAVILY_API_KEY` | Tavily 备用搜索与提取 |
+| `JINA_API_KEY` | Jina 搜索；Reader 可匿名读取 |
+| `DEEPSEEK_API_KEY` | DeepSeek Search / Fetch |
+| `PERPLEXITY_API_KEY` | Perplexity 结构化搜索 |
+| `XAI_API_KEY` | Grok `agentic_search` |
+| `CUSTOM_AGENTIC_API_KEY` | 自定义 OpenAI 兼容模型端点 |
+| `OPENAI_API_KEY` | OpenAI Deep Research |
+
+```json
+{
+  "EXA_API_KEY": "your-exa-key",
+  "PARALLEL_API_KEY": "your-parallel-key",
+  "PERPLEXITY_API_KEY": "your-perplexity-key",
+  "CUSTOM_AGENTIC_API_KEY": "your-custom-endpoint-key"
+}
+```
+
+默认凭据路径为 `~/.config/bookmark-research/credentials.json`，文件为未加密的本地明文，权限要求为 `0600`（仅当前用户可读）。建议用 `setup` 写入，避免手动编辑后权限不正确。可用 `BOOKMARK_RESEARCH_CREDENTIALS` 改路径。宿主直接运行的 MCP 不读取这份凭据文件；它需要的 Key 应按该宿主的方式配置。
+
+其他入口：在宿主会话中调用 `update_settings` 改长期设置；用 `bookmark-research config show` 查看当前配置。安装或升级后，收据会打印本指南和重开向导的命令。

package/docs/details.en.md

@@ -11,7 +11,7 @@ Reference material moved from the README: components, data model, research modes
 | **Skill** | [`skills/bookmark-research/SKILL.md`](../skills/bookmark-research/SKILL.md) | Guides package reading, local queries, source verification, and research reports |
 | **MCP server** | [`src/mcp_server.py`](../src/mcp_server.py), started with `python3 src/cli.py serve` | One local `bookmark-research` server with the [shared tool catalog](#mcp-tools) |
 | **Python CLI** | [`src/cli.py`](../src/cli.py) | Runs the same queries and research workflows directly, including from a host without MCP |
-| **Web providers** | [`config/providers.json`](../config/providers.json), [`src/provider_adapters.py`](../src/provider_adapters.py), [`src/jina.py`](../src/jina.py) | Exa, Parallel, Jina HTTP, DeepSeek Search/Fetch and Tavily behind one MCP; schema checks, session reuse and visible partial failures |
+| **Web providers** | [`config/providers.json`](../config/providers.json), [`src/provider_adapters.py`](../src/provider_adapters.py), [`src/jina.py`](../src/jina.py) | Exa, Parallel, Jina HTTP, DeepSeek Search/Fetch, Perplexity structured Search and Tavily behind one MCP; Grok and custom OpenAI-compatible model answers are exposed separately |
 | **Research and coverage** | [`src/research.py`](../src/research.py), [`src/research_coverage.py`](../src/research_coverage.py) | Complete source inventory, all bookmark instances, budgets, evidence, substantive review and reports |
 | **Host workflows** | [`hosts/`](../hosts/) and [`src/routing.py`](../src/routing.py) | Native Codex delegation, Claude workflow and DSH workflow adapter |
 | **Professional research** | [`src/research_services.py`](../src/research_services.py) | Optional provider-owned background tasks, saved run IDs and secondary-report import |
@@ -183,8 +183,9 @@ The [shared Skill](../skills/bookmark-research/SKILL.md) guides the agent's work
 | `search_bookmarks` | Query bookmarks for multiple targets while retaining item context |
 | `get_context` | Read section, card, group, connection, and item-ancestor context; `compact:true` drops raw JSON, descriptions and revisions |
 | `plan_research` | Local preflight for one question: ranked cards and bookmarks, Wiki and archive pointers, relevance, freshness, fetch ownership, and a route; missing-file cards are flagged and their URLs are kept |
-| `search_providers` | List configured web providers |
-| `search_web` | Search through Exa / Parallel / Tavily / keyed Jina and merge results per target |
+| `search_providers` | List configured web providers and per-operation authentication requirements |
+| `search_web` | Search through configured Exa / Parallel / Tavily / Jina / DeepSeek / Perplexity providers and merge results per target |
+| `agentic_search` | Optional Grok or configured custom-model answer/search channel with citations; not URL-fused |
 | `fetch_web` | Read known URLs under a per-page and batch budget, optionally archive text, and continue a saved extract with `capture_id`/`offset` |
 | `search_archive` | Literal full-text search over saved page text in the knowledge archive and all research evidence, merged by content hash |
 | `get_settings` | Read current settings and storage paths |
@@ -215,11 +216,14 @@ The [shared Skill](../skills/bookmark-research/SKILL.md) guides the agent's work
 | **Jina** | HTTP Reader supports anonymous webpage/PDF reading; Search requires `JINA_API_KEY`. The hosted Jina MCP is not used. |
 | **Tavily** | Built-in search fallback and selectable extraction; `TAVILY_API_KEY` uses Bearer, otherwise explicit keyless mode |
 | **DeepSeek Search / Fetch** | Optional raw JSON tools API (`/v1/tools/search`, `/v1/tools/fetch`); requires `DEEPSEEK_API_KEY`; OpenAI-compatible error shape, not a Chat Completions tool |
+| **Perplexity Search** | Optional structured Search API provider; requires `PERPLEXITY_API_KEY`; returns sources only and does not read pages |
+| **xAI Grok** | Optional Responses API tool `agentic_search`; requires `XAI_API_KEY`; returns a model answer and citations outside URL fusion |
+| **Custom model endpoint** | Optional OpenAI-compatible Chat Completions or Responses endpoint; configured Base URL/model/protocol and `CUSTOM_AGENTIC_API_KEY`; separate answer channel, upstream search support is not inferred |
 | **GitHub** | Use the host's existing GitHub MCP or `gh` for repository-specific tasks. No GitHub MCP is bundled; public pages can also be read through Exa / Parallel. |
 
-All retrieval providers run through the plugin's own MCP or CLI; additional host MCP registrations are unnecessary. Search starts with Exa + Parallel under a selectable strategy (hedged by default) with a grace window and total deadline, and uses configured fallbacks for unresolved queries; reading falls back to Parallel + Jina after Exa. Anonymous/keyless access and quotas depend on each service's policy; optional credentials use `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, `JINA_API_KEY` or `DEEPSEEK_API_KEY` in the launching environment. Local queries work offline.
+Bookmark Research aggregates only its configured providers; the host model may call other visible host/MCP search tools and compare their evidence. Search starts with Exa + Parallel under a selectable strategy (hedged by default) with a grace window and total deadline, and uses configured fallbacks for unresolved queries; Perplexity can be added to either search tier. Reading falls back to Parallel + Jina after Exa. Grok and the custom OpenAI-compatible endpoint are separate answer channels; custom search behavior depends on the configured upstream. Anonymous/keyless access and quotas depend on each service's policy; optional credentials use `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, `JINA_API_KEY`, `DEEPSEEK_API_KEY` or `PERPLEXITY_API_KEY` for retrieval, `XAI_API_KEY` for Grok, and `CUSTOM_AGENTIC_API_KEY` for the custom model. Local queries work offline.
 
-`search_providers` describes configuration without network access; `probe:true` discovers remote MCP tools, while Jina and DeepSeek HTTP mappings remain explicitly `not_probed`. Discovery does not prove successful retrieval. Each MCP process reuses remote sessions and a bounded tool catalog. Calls are not automatically replayed after errors. Historical implementation notes remain available in Git history.
+`search_providers` describes configuration without network access; `probe:true` discovers remote MCP tools, while Jina, DeepSeek and Perplexity HTTP mappings remain explicitly `not_probed`. Discovery does not prove successful retrieval. Each MCP process reuses remote sessions and a bounded tool catalog. Calls are not automatically replayed after errors. Historical implementation notes remain available in Git history.
 
 ### Package rules and AGENTS.md
 
@@ -237,7 +241,7 @@ The Skill currently produces answers and research reports. It does not generate
 
 This directory is the **Codex native plugin**, with its manifest at `.codex-plugin/plugin.json`. In Codex 0.153.4, the MCP configuration explicitly uses `cwd: "."` and runs `python3 src/cli.py serve` from the installed plugin directory. That native entry does not expand `${PLUGIN_ROOT}`; the Claude export uses its own path convention.
 
-The Codex manifest forwards these environment variable names through `env_vars`: `BOOKMARK_RESEARCH_DATA_DIR`, `BOOKMARK_RESEARCH_CONFIG`, `XDG_DATA_HOME`, `XDG_CONFIG_HOME`, `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, and `OPENAI_API_KEY`. Actual paths and credentials come from the user's runtime environment.
+The Codex manifest and DSH adapter forward provider credentials including `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, `JINA_API_KEY`, `DEEPSEEK_API_KEY`, `PERPLEXITY_API_KEY`, `XAI_API_KEY` and `CUSTOM_AGENTIC_API_KEY`, along with the configured data/config paths. Actual paths and credentials come from the user's runtime environment.
 
 Run the relevant command **from this directory** to generate another format:
 

package/docs/details.md

@@ -21,12 +21,12 @@
 
 不需要固定提示词。完整数据包研究保留所有原始 URL 和重复书签语境；只有明确限定卡片、分组或专题时才缩小范围。搜索摘要、搜索结果的第一页和外部报告都不能代替原始网页审阅。
 
-一个插件保留一个 MCP 聚合入口和一个执行 Skill；后端服务数量与入口数量无关。MCP 内置 Exa、Parallel、Tavily 搜索／读取适配器、Jina HTTP 接口、可选的 DeepSeek Search／Fetch 接口和 OpenAI／Parallel 研究 API 客户端。Skill 负责根据任务选择并执行三种流程：
+一个插件保留一个 MCP 聚合入口和一个执行 Skill；后端服务数量与入口数量无关。MCP 内置 Exa、Parallel、Tavily 搜索／读取适配器、Jina HTTP 接口、可选的 DeepSeek Search／Fetch 与 Perplexity Search 接口、Grok 和自定义 OpenAI 兼容 Agentic 搜索通道，以及 OpenAI／Parallel 研究 API 客户端。普通 URL 来源由 `search_web` 聚合；模型回答和引用单独返回，不参加 URL 排名。自定义模型是否联网由上游能力决定，工具会标明引用未经独立核验。Skill 负责根据任务选择并执行三种流程：
 
 | 场景 | 基础流程 | 检索与委派支持 |
 | --- | --- | --- |
 | URL 直读 | 当前模型读取已知页面并回答 | Exa 未读到的 URL 交给 Parallel + Jina Reader 并发读取；可配置 Tavily 提取。 |
-| Agentic Web Search | 当前宿主模型先规划 → 搜索／读文 → 判断证据 → 针对缺口补查 | Exa + Parallel 按 `search.strategy` 提供搜索结果（默认并发对冲）；无有效网址的查询再交给 Tavily + 有 key 的 Jina。普通问题无需完整研究会话。 |
+| Agentic Web Search | 当前宿主模型先规划 → 搜索／读文 → 判断证据 → 针对缺口补查 | 优先使用当前宿主实际暴露的搜索工具；`search_web` 聚合已配置服务（Exa + Parallel 默认并发对冲，Perplexity 可选；未解析查询交给 Tavily + Jina）。需要 Grok/X 或已配置的自定义模型通道时按需调用 `agentic_search`，由宿主评估独立回答和未经核验的引用。普通问题无需完整研究会话。 |
 | Deep Research | 直接向研究 API 提交完整问题，观察进度并审阅报告 | 可选 OpenAI／Parallel API；宿主已有研究能力亦可使用。完整清单与覆盖审计按需启用。 |
 
 三个基座共用这套方法：Codex 原生子代理、Claude 普通子代理或已启用团队、已配置的 DSH 子代理／工作流；具体差异与官方依据见 [宿主兼容说明](harness-compatibility.md)。整包脚本用于分组研究。API 可独立调用，无需先运行宿主调查或创建本地研究会话。运行中和结果未知的任务先观察，保留 operation ID，避免重复创建。
@@ -67,7 +67,7 @@ JSON／`.canvas` 是源数据，SQLite 是可重建的本地查询索引，无
 
 可以读取公开 GitHub 仓库页面、README、文件和 issues；读取 README 不等于遍历整个代码仓库。代码审查按任务选择具体文件或宿主已有 GitHub 工具，插件未额外安装 GitHub MCP。
 
-网络访问依赖服务方的认证与额度。可运行 `python3 src/cli.py setup` 隐藏输入密钥，或在宿主环境设置 `EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY`、`JINA_API_KEY`、`OPENAI_API_KEY`。密钥默认保存为配置旁仅当前用户可读的 `credentials.json`，环境变量优先。无需给宿主研究额外填写一套模型地址。
+网络访问依赖服务方的认证与额度。可运行 `python3 src/cli.py setup` 隐藏输入密钥，或在宿主环境设置 `EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY`、`JINA_API_KEY`、`DEEPSEEK_API_KEY`、`PERPLEXITY_API_KEY`、`XAI_API_KEY`、`CUSTOM_AGENTIC_API_KEY`、`OPENAI_API_KEY`。密钥默认保存为配置旁仅当前用户可读的 `credentials.json`，环境变量优先。Perplexity 是结构化搜索来源；Grok 和自定义模型通过独立 `agentic_search` 返回模型回答和引用，不会自动并入 `search_web` 的 URL 聚合。
 
 需要诊断服务访问问题时，可从高级工具面调用 `research_readiness`，显式检查默认在首次、配置／密钥变化或 15 分钟过期时刷新。向导可改为每题检查或仅手动检查；本地查询不联网。结果区分密钥配置、目录可达、实际检索与宿主 OAuth，检查不会启动专业研究任务。
 

package/docs/harness-compatibility.md

@@ -1,6 +1,6 @@
 # 三宿主接入与验证边界
 
-Codex、Claude Code、DeepSeek Harness 共用同一 Skill、Python CLI、stdio MCP、归档和 Wiki。宿主负责推理、搜索策略、协作与最终表达；插件默认提供 21 个日常工具。研究 API 可独立使用，完整资料审计及持久化研究记录通过 `deep` 预设按需启用。
+Codex、Claude Code、DeepSeek Harness 共用同一 Skill、Python CLI、stdio MCP、归档和 Wiki。宿主负责推理、搜索策略、协作与最终表达；插件默认提供 22 个日常工具。`search_web` 聚合插件配置的来源；Perplexity 是可选结构化搜索来源，Grok 则通过独立 `agentic_search` 返回模型回答与引用。研究 API 可独立使用，完整资料审计及持久化研究记录通过 `deep` 预设按需启用。
 
 | 宿主 | 接入 | 协作 |
 | --- | --- | --- |