bookmark-research 0.5.0-beta.9 → 0.7.0

package/.agents/plugins/marketplace.json

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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bookmark-research",
-  "version": "0.5.0-beta.9",
+  "version": "0.7.0",
   "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
   "author": {
     "name": "kwenxu"
@@ -33,12 +33,17 @@
         "BOOKMARK_RESEARCH_DATA_DIR",
         "BOOKMARK_RESEARCH_CONFIG",
         "BOOKMARK_RESEARCH_CREDENTIALS",
+        "BOOKMARK_RESEARCH_TOOL_SCOPE",
         "XDG_DATA_HOME",
         "XDG_CONFIG_HOME",
         "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",
         "SystemRoot",
         "windir"

package/README.md

@@ -2,91 +2,105 @@
 
 **English** · [中文](README.zh.md)
 
-Research your bookmarks with verified web sources. Give it a list of bookmark URLs or a [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) package; it checks every link, searches and reads the web, and writes a cited report you can resume.
+[![GitHub Bookmark-Canvas](https://img.shields.io/badge/GitHub-Bookmark--Canvas-181717?logo=github&logoColor=white)](https://github.com/Browser-bookmark-hub/Bookmark-Canvas)
+[![npm version](https://img.shields.io/npm/v/bookmark-research?logo=npm)](https://www.npmjs.com/package/bookmark-research)
 
-Works in **Codex, Claude Code, Pi and DSH (DeepSeek Harness)**.
+Research with bookmark context and retain reusable knowledge. Read a [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) package, investigate with the host model or a research API, and save sourced Wiki pages. Works in **Codex, Claude Code and DeepSeek Harness (dsh)**.
 
 [Installation guide](docs/installation.en.md) · [User guide](docs/user-guide.en.md) · [Details](docs/details.en.md) · [npm](https://www.npmjs.com/package/bookmark-research)
 
-> [!NOTE]
-> **0.5.0 is a beta.** Report problems on [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues).
+## Version 0.6.0
 
-**Install releases from [npm](https://www.npmjs.com/package/bookmark-research).** GitHub Releases retain version notes and npm links; downloadable installation/test packages have been withdrawn. GitHub's automatic **Source code** archives are source checkouts, not installation packages.
+The stable release includes bilingual Canvas package support, safer Exa batch reading that isolates ambiguous pages, and concise installation/update summaries. Installation prints the version, actual paths, checks and any required action. Use `--json` for complete structured diagnostics; `--non-interactive` only disables prompts. Existing settings, credentials and research data are retained during upgrades.
+
+## 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. `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
 
-- Python 3.9+ with SQLite FTS5 (check with `bookmark-research doctor`)
-- The CLI of at least one client: Codex, Claude Code, Pi or DSH (DSH also needs `pnpm`)
-- Node 18+ and npm for release installation (including the GitHub convenience script)
-- No API key is needed to install or to query bookmarks locally
+- Python 3.9+ with SQLite FTS5 (checked by `bookmark-research doctor`)
+- The CLI of at least one client: Codex, Claude Code or DeepSeek Harness (dsh). DeepSeek Harness (dsh) also needs `pnpm`, unless it is the DeepSeek Harness Desktop CLI, which carries its own
+- Node 18+ and npm to install a release
+- No API key is needed to install, or to query bookmarks locally
 
 ## Install
 
-**Current beta (`0.5.0-beta.9`)**, interactive on macOS, Linux and Windows:
-
 ```sh
-npx bookmark-research@0.5.0-beta.9 install --source npm:bookmark-research@0.5.0-beta.9
+npx bookmark-research@latest install
 ```
 
-This pins both the installer and the content. The `@latest` examples below follow the default channel, which remains `0.5.0-beta.3`; `@beta` currently points to `0.5.0-beta.9`. Changing only the npx selector does not change the installer's default content source.
-
-**Default-channel interactive installation:**
+Installs the latest stable release directly. To pin this release, use `npx bookmark-research@0.6.0 install`. Add `--lang zh` for the Chinese wizard. For a permanent command, run `npm install -g bookmark-research@latest`; the GitHub convenience script uses the same npm release (macOS/Linux/WSL):
 
 ```sh
-npx bookmark-research@latest install
+curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
 ```
 
-Pick clients with the arrow keys and Space, confirm the summary, then choose search services and enter API keys. Start a new client session afterwards.
+### What the installer asks
+
+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 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. **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.
 
-For a permanent `bookmark-research` command: `npm install -g bookmark-research`. The GitHub convenience script uses the same npm release (macOS/Linux/WSL): `curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash`.
+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.
 
-**One client, no prompts:**
+### Non-interactive install
 
 | Client | Command | Registers with |
 | --- | --- | --- |
 | Codex | `npx bookmark-research@latest install codex --non-interactive` | `codex plugin add` |
 | Claude Code | `npx bookmark-research@latest install claude --scope user --non-interactive` | `claude plugin install` |
-| Pi | `npx bookmark-research@latest install pi --non-interactive` | `pi install` |
-| DSH | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
-
-**One release source for all four hosts:** npm contains the shared runtime, Skill and host adapters. The installer downloads the release, prepares the selected host format, then invokes the host’s native commands. Updates retain an npm selector rather than an npx cache path. GitHub hosts source and installation catalogs; unpublished source uses the Python installer. See [distribution policy and official references](docs/distribution.md).
-
-**DSH installs the release directly:** the published package declares `dsh.bundle.patch`, so `dsh plugin --profile <name> add bookmark-research@<version>` — or the DSH plugin manager — installs it with no export first, resolving Python and MCP paths from the installed package. DeepSeek Harness Desktop reserves the `desktop` profile for its own carrier, so install that one with the app's CLI. See the [installation guide](docs/installation.en.md).
+| DeepSeek Harness (dsh) | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
 
-**Windows:** the installer writes the detected Python path into each client's MCP config, because Windows often has no working `python3`. Install Codex with `bookmark-research install codex` rather than adding the repository to Codex directly. `bookmark-research status` shows the interpreter in use.
+Several at once: `npx bookmark-research@latest install claude dsh --profile web --non-interactive`. Project scope: `--scope project --project /path/to/project` (Claude Code). All options: [installation guide](docs/installation.en.md).
 
-Several at once: `npx bookmark-research@latest install claude dsh --profile web --non-interactive`. Project scope: `--scope project --project /path/to/project` (Claude Code, Pi). All options: [installation guide](docs/installation.en.md).
-
-**Ask your agent to install it.** Paste this into Codex, Claude Code, Pi or DSH:
+**Ask your agent to install it.** Paste this into Codex, Claude Code or DeepSeek Harness (dsh):
 
 ```text
 Install the Bookmark Research plugin into the client you are running in.
 
-1. Identify your own client: codex, claude, pi or dsh.
-2. Run: npx bookmark-research@latest install <client> --non-interactive
-   - Claude Code or Pi: add --scope user (or --scope project --project <dir>).
-   - DSH: add --profile <profile>; ask me for the profile name.
+1. Identify your own client: codex, claude or dsh.
+2. Run: npx bookmark-research@latest install <client> --non-interactive --json
+   - Claude Code: add --scope user (or --scope project --project <dir>).
+   - DeepSeek Harness (dsh): add --profile <profile>; ask me for the profile name.
 3. The command prints JSON. Confirm "verified": true and report any "error".
 4. Do not ask me for API keys in chat. Tell me to run `bookmark-research setup`
-   (or `npx bookmark-research@latest setup`) in my terminal to enter them.
+   in my terminal to enter them.
 5. Tell me to start a new session so the Skill and MCP tools load.
 ```
 
-## Configure and API keys
+Install notes:
+
+- **npm is the single release source** for all three hosts; it contains the shared runtime, Skill and host adapters. The installer downloads the release, prepares the host's format, then calls the host's native commands. GitHub hosts source, versions and the installation catalog; unpublished source uses the Python installer. See [distribution policy](docs/distribution.md).
+- **DeepSeek Harness (dsh) installs the release directly.** The package declares `dsh.bundle.patch`, so `dsh plugin --profile <name> add bookmark-research@<version>` installs it with no export first. The reserved `desktop` profile belongs to DeepSeek Harness Desktop; use that app's CLI, which the installer and wizard locate themselves.
+- **Windows** often has no working `python3`, so the installer writes the detected Python path into each client's MCP config. Install Codex with `bookmark-research install codex` rather than adding the repository to Codex directly; `bookmark-research status` shows the interpreter in use.
 
-No reinstall is needed. Settings and keys apply to every installed client; start a new client session after changing them.
+## Configure and update
+
+**Open the configuration page.** Run `bookmark-research` with no arguments in a terminal: the menu covers preferences and API keys, service checks, installing into another client, updates and status. The alias `bookmark` (or `bookmark research`) does the same, and `bookmark-research setup` goes straight to the wizard.
 
 | Task | Command |
 | --- | --- |
-| Menu: configure, check, install, update | `bookmark-research` |
 | Preferences and API keys | `bookmark-research setup` |
-| Installed clients, preferences, storage locations, recent research, key status | `bookmark-research status` |
-| Script preferences | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
+| 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.
+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.
 
-**API keys are optional.** Enter them in `bookmark-research setup` (hidden input, checked immediately, saved in a private local file) or set environment variables, which take precedence. Keys are never accepted in chat, command arguments or JSON files.
+**API keys are optional.** Enter them in `bookmark-research setup` (hidden input, checked immediately, saved in a private local file) or set environment variables, which take precedence.
 
 | Variable | Service | Without it |
 | --- | --- | --- |
@@ -94,11 +108,13 @@ Use `npx bookmark-research@latest …` if the command is not installed globally.
 | `PARALLEL_API_KEY` | Parallel search and page reading | Free anonymous use with lower limits |
 | `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 |
 
-Setup also asks where research reports and evidence go: a central folder (default `<data dir>/research`, path changeable) or beside the bookmark file or folder (falls back to the central folder when that is not possible). This affects new research only; existing tasks stay where they are. It then asks whether finished research should update the Wiki: suggest pages and ask first (default), automatic, or off.
-
-Preferences (research depth, answer language, providers, archiving, output location, Wiki follow-up) can also be changed by asking the agent in a client session; 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
 
@@ -114,13 +130,15 @@ Nothing is written into your bookmark files or the plugin. The data directory is
 | `raw-library.sqlite3` | Rebuildable full-text index for `search_archive` |
 | `${XDG_CONFIG_HOME:-~/.config}/bookmark-research/` | `settings.json` and `credentials.json` (private, owner-only) |
 
-## Agent loops and delegation
+Changing the location affects new research only; existing tasks stay where they are.
+
+## Research loops and delegation
 
 The host model plans the research, searches or reads pages, evaluates the evidence and follows unresolved questions. The Skill guides this loop; MCP stores inputs, evidence, budgets and progress. Saving a research task does not start a background agent.
 
-For a grouped report, the plugin supplies a reader → fresh verifier → coverage check → follow-up → report workflow. Codex uses its native subagent tools and the bundled delegation guide; Claude Code and DSH use available host workflow hooks, while Pi requires a loaded subagent/workflow extension. The host owns concurrency, cancellation and agent lifetime. All children must receive the relevant instructions and access the same research store.
+For a grouped report, the plugin supplies a reader → fresh verifier → coverage check → follow-up → report workflow. Codex uses its native subagent tools and the bundled delegation guide; Claude Code and DeepSeek Harness (dsh) use available host workflow hooks. The host owns concurrency, cancellation and agent lifetime. All children must receive the relevant instructions and access the same research store.
 
-The workflow adapters have simulated contract tests, but a successful install does not prove that every host can execute the complete multi-agent workflow. See [host workflows](skills/bookmark-research/references/host-workflows.md) for requirements and [the validation matrix](docs/validation-0.4.0.md#host-and-provider-boundaries) for observed limits.
+The workflow adapters have simulated contract tests, but a successful install does not prove that every host can execute the complete multi-agent workflow. See [host workflows](skills/bookmark-research/references/host-workflows.md) for requirements. Historical validation records are available in Git history.
 
 ## What's inside
 
@@ -128,22 +146,26 @@ 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 11 method references, each with a [Chinese copy](skills/bookmark-research/references/zh/skill-guide.md) | Loaded by the client | None |
-| Local MCP | `bookmark-research`, 40 tools (below; the list grows with capabilities) | Python process started by the client | Installed for you |
+| 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`, 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 service, called by the local MCP | [Jina Reader](https://jina.ai/reader) (fallback reading; search with a key) | HTTPS | Optional `JINA_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 |
 
-Local MCP tools:
+Default MCP tools:
 
 | Group | Tools |
 | --- | --- |
-| Bookmarks | `sync_package`, `index_status`, `source_history`, `source_remove`, `source_merge`, `search_bookmarks`, `get_context` |
-| Web | `search_web`, `fetch_web`, `search_archive`, `search_providers` |
-| Research | `research_readiness`, `research_start`, `research_status`, `research_search`, `research_fetch`, `research_source`, `research_record`, `research_inventory`, `research_coverage`, `research_import_evidence`, `research_finish`, `research_route` |
-| Research services (optional) | `research_services`, `research_service_prepare`, `_start`, `_status`, `_result`, `_cancel`, `_attach`, `_import` |
+| Canvas context | `sync_package`, `index_status`, `search_bookmarks`, `get_context`, `plan_research` |
+| 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` |
-| Wiki and evaluation | `wiki_write`, `wiki_get`, `wiki_list`, `wiki_search`, `wiki_lint`, `wiki_acknowledge`, `evaluate_research` |
+
+`plan_research` retrieves local candidates and independently checks the Wiki/archive; the host assesses relevance and follows gaps. It also works without a Canvas source. `wiki_write` accepts authored sections, exact citations and source text or capture IDs in one call. Research APIs accept a question without a local research session.
+
+The `deep` preset additionally exposes source maintenance, persistent research records, routing diagnostics and Wiki maintenance. These support explicit audits and resumption. Git history uses the host's shell.
 
 Tool descriptions: [details](docs/details.en.md#mcp-tools).
 

package/README.zh.md

@@ -2,91 +2,104 @@
 
 [English](README.md) · **中文**
 
-用联网查证来研究你的书签。给它一份书签 URL 列表或 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) 数据包，它会逐条核对链接、搜索和阅读网页，写出带引用、可以接着做的研究报告。
+[![GitHub Bookmark-Canvas](https://img.shields.io/badge/GitHub-Bookmark--Canvas-181717?logo=github&logoColor=white)](https://github.com/Browser-bookmark-hub/Bookmark-Canvas)
+[![npm version](https://img.shields.io/npm/v/bookmark-research?logo=npm)](https://www.npmjs.com/package/bookmark-research)
 
-支持 **Codex、Claude Code、Pi、DSH（DeepSeek Harness）**。
+带着书签上下文调研，把结论留成可复用知识。读取 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) 数据包，使用宿主模型或研究 API 调查，再保存带来源的 Wiki 页面。支持 **Codex、Claude Code、DeepSeek Harness (dsh)**。
 
 [安装说明](docs/installation.md) · [使用指南](docs/user-guide.md) · [详细说明](docs/details.md) · [npm](https://www.npmjs.com/package/bookmark-research)
 
-> [!NOTE]
-> **0.5.0 是测试版。** 遇到问题请到 [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues) 反馈。
+## 0.6.0 正式版
 
-**发布版统一从 [npm](https://www.npmjs.com/package/bookmark-research) 安装。** GitHub Releases 保留版本说明和 npm 链接，安装包／测试包附件已撤下。GitHub 自动生成的 **Source code** 压缩包是源码快照，不是安装包。
+本版包含双语画布数据包支持、隔离歧义页面的 Exa 批量正文解析，以及精简后的安装／更新摘要。默认只显示版本、实际路径、检查结果和需处理事项；添加 `--json` 获取完整结构化诊断，`--non-interactive` 仅控制是否询问。升级保留已有配置、密钥和研究数据。
+
+## 它是怎么工作的
+
+- **本地理解层。** 数据包按结构读，而不是一张平铺的 URL 清单：卡片与分组的位置、连线的方向与标签、同一书签在不同卡片的出现位置（空间上下文）；日期字段、ID 中协议定义的日期段，以及真正改过内容的 Git 提交（时间上下文）。这些都是离线查询。
+- **外部调研走三条路线。** 读取已知 URL 不需要推理；Agentic 搜索由宿主模型自己规划、搜索、阅读并追查缺口；Deep Research 可直接调用 OpenAI／Parallel 研究 API；完整清单与覆盖审计在明确需要时启用。`search_web` 聚合已配置的 URL 搜索来源（可选 Perplexity Search）；`agentic_search` 可按需返回 Grok 或用户自定义 OpenAI 兼容模型的回答与引用。自定义模型是否真正联网取决于上游能力，且不参加 URL 排名。
+- **可复核的知识存储。** 完成的研究可以沉淀成 Wiki：带历史版本和相互链接的已审核页面，之后提问直接复用，不必重新搜索网页。
 
 ## 环境要求
 
-- Python 3.9+，含 SQLite FTS5（可用 `bookmark-research doctor` 检查）
-- 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH（DSH 另需 `pnpm`）
-- 发布版安装需要 Node 18+ 和 npm（GitHub 便捷脚本也需要）
+- Python 3.9+，含 SQLite FTS5（用 `bookmark-research doctor` 检查）
+- 至少一个宿主的 CLI：Codex、Claude Code 或 DeepSeek Harness (dsh)。DeepSeek Harness (dsh) 另需 `pnpm`；若用 DeepSeek Harness 桌面版自带 CLI，则它自带 pnpm，无需另装
+- 安装发布版需要 Node 18+ 和 npm
 - 安装和本地查书签都不需要 API Key
 
 ## 安装
 
-**当前测试版（`0.5.0-beta.9`）**，支持 macOS、Linux、Windows 交互安装：
-
 ```sh
-npx bookmark-research@0.5.0-beta.9 install --source npm:bookmark-research@0.5.0-beta.9
+npx bookmark-research@latest install
 ```
 
-这条命令同时固定安装器和插件内容。下面的 `@latest` 示例使用默认渠道，目前仍为 `0.5.0-beta.3`；`@beta` 当前指向 `0.5.0-beta.9`。只改 npx 的版本选择，不会改变安装器默认下载的内容来源。
-
-**默认渠道的交互安装：**
+默认安装最新正式版。固定安装本版可用 `npx bookmark-research@0.6.0 install`。加 `--lang zh` 可让向导显示中文。想一直能用 `bookmark-research` 命令，运行 `npm install -g bookmark-research@latest`；GitHub 便捷脚本使用同一 npm 发布版（macOS/Linux/WSL）：
 
 ```sh
-npx bookmark-research@latest install
+curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
 ```
 
-用方向键和空格选择宿主，确认汇总后安装，再选择搜索服务、输入 API Key。装好后新建一个宿主会话。
+### 安装向导会问你什么
+
+1. **装到哪些宿主** —— 方向键移动、空格勾选；检测到的 CLI 默认已勾选，随后显示安装计划让你确认。
+2. **默认研究深度（可选）** —— 保持 `auto` 就会按每次请求自动定档；只有想钉死一个默认时才改成 `quick`、`agentic` 或 `deep`。
+3. **答复和报告语言** —— 跟随提问语言、中文或英文。
+4. **搜索来源** —— 一个有序多选列表；未选中的服务自动作为备用搜索层。Perplexity 只提供搜索结果，网页读取由其他服务完成。
+5. **存放位置** —— 默认数据目录、自定义统一目录（归档与研究报告），或研究报告放在书签文件／文件夹旁边。
+6. **可选专业研究 API** —— 默认关闭：OpenAI Deep Research 或 Parallel Task API。
+7. **自定义模型端点（可选）** —— 输入兼容 Base URL、模型和协议；联网能力取决于上游。
+8. **API Key** —— 空格勾选上面所选服务需要的 Key，回车继续，再逐个隐藏输入；全部可选，可跳过。Key 与偏好分开保存。
+9. **服务检查** —— 报告已配置服务；样例搜索／阅读自检需另行选择。
 
-想一直能用 `bookmark-research` 命令：`npm install -g bookmark-research`。GitHub 便捷脚本也使用同一 npm 发布版（macOS/Linux/WSL）：`curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash`。
+回车即保留当前选项，所以整轮可能只需按几次回车。装好后新建一个宿主会话，让 Skill 和 MCP 工具生效。Wiki 默认建议整理；已有保存授权时直接执行。服务诊断保留 15 分钟缓存，按需调用。
 
-**指定宿主、不弹提示：**
+### 指定宿主、不弹提示
 
 | 宿主 | 命令 | 实际登记方式 |
 | --- | --- | --- |
 | Codex | `npx bookmark-research@latest install codex --non-interactive` | `codex plugin add` |
 | Claude Code | `npx bookmark-research@latest install claude --scope user --non-interactive` | `claude plugin install` |
-| Pi | `npx bookmark-research@latest install pi --non-interactive` | `pi install` |
-| DSH | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
-
-**四个宿主统一发布来源：** npm 包包含共享运行时、Skill 和宿主适配。安装器下载发布包，生成所选宿主格式，再调用宿主原生命令；更新记录 npm 来源，不依赖 npx 临时缓存。GitHub 提供源码和安装清单，未发布源码用 Python 安装器。见[发布约定与官方依据](docs/distribution.md)。
-
-**DSH 可直接安装发布包：** 发布包声明 `dsh.bundle.patch`，`dsh plugin --profile <名称> add bookmark-research@<版本>`（或 DSH 插件管理界面）无需先导出即可安装，Python 与 MCP 路径按安装位置解析。DeepSeek Harness 桌面版把 `desktop` profile 保留给自身载体，该 profile 请用桌面版自带 CLI 安装。详见[安装说明](docs/installation.md)。
+| DeepSeek Harness (dsh) | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
 
-**Windows：** Windows 上常常没有能用的 `python3`，所以安装器会把检测到的 Python 路径写进各宿主的 MCP 配置。Codex 请用 `bookmark-research install codex` 安装，不要直接把仓库加进 Codex。`bookmark-research status` 可以查看实际使用的 Python。
+一次装多个：`npx bookmark-research@latest install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code）。全部参数见[安装说明](docs/installation.md)。
 
-一次装多个：`npx bookmark-research@latest install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
-
-**让 agent 帮你装。** 把下面这段粘贴给 Codex、Claude Code、Pi 或 DSH：
+**让 agent 帮你装。** 把下面这段粘贴给 Codex、Claude Code 或 DeepSeek Harness (dsh)：
 
 ```text
 请把 Bookmark Research 插件安装到你当前运行的这个宿主里。
 
-1. 先确认你自己是哪个宿主：codex、claude、pi 或 dsh。
-2. 运行：npx bookmark-research@latest install <宿主> --non-interactive
-   - Claude Code 或 Pi：加 --scope user（或 --scope project --project <目录>）。
-   - DSH：加 --profile <名称>；profile 名称请先问我。
+1. 先确认你自己是哪个宿主：codex、claude 或 dsh。
+2. 运行：npx bookmark-research@latest install <宿主> --non-interactive --json
+   - Claude Code：加 --scope user（或 --scope project --project <目录>）。
+   - DeepSeek Harness (dsh)：加 --profile <名称>；profile 名称请先问我。
 3. 命令会输出 JSON。确认 "verified": true，有 "error" 就告诉我。
-4. 不要在对话里向我要 API Key。请让我在终端运行 `bookmark-research setup`
-   （或 `npx bookmark-research@latest setup`）自己输入。
+4. 不要在对话里向我要 API Key。请让我在终端运行 `bookmark-research setup` 自己输入。
 5. 提醒我新建一个会话，让 Skill 和 MCP 工具生效。
 ```
 
-## 配置与 API Key
+安装补充说明：
+
+- **npm 是三个宿主唯一的发布来源**，包内含共享运行时、Skill 和宿主适配文件。安装器下载发布包、生成该宿主需要的格式，再调用宿主原生命令登记。GitHub 提供源码、版本说明和安装清单；未发布源码用 Python 安装器。见[发布约定](docs/distribution.md)。
+- **DeepSeek Harness (dsh) 可直接安装发布包。** 包内声明 `dsh.bundle.patch`，`dsh plugin --profile <名称> add bookmark-research@<版本>` 无需先导出即可安装。`desktop` profile 保留给 DeepSeek Harness 桌面版，请用桌面版自带 CLI 安装；安装器与向导会自行定位该 CLI。
+- **Windows** 上常常没有能用的 `python3`，所以安装器会把检测到的 Python 路径写进各宿主的 MCP 配置。Codex 请用 `bookmark-research install codex` 安装，不要直接把仓库加进 Codex；`bookmark-research status` 可以查看实际使用的 Python。
 
-不需要重新安装。配置和 Key 对所有已安装的宿主生效，修改后新建宿主会话即可。
+## 配置页与更新
+
+**进入配置页。** 在终端里不带参数运行 `bookmark-research` 就会打开菜单：修改配置与 API Key、检查服务、安装到其他宿主、更新、查看状态。别名 `bookmark`（或 `bookmark research`）等价，`bookmark-research setup` 直接进入向导。
 
 | 要做什么 | 命令 |
 | --- | --- |
-| 主菜单：配置、检查、安装、更新 | `bookmark-research` |
 | 修改偏好和 API Key | `bookmark-research setup` |
+| 打开菜单 | `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`，例如 `npx bookmark-research@latest setup`。
+没有全局安装时，在前面加 `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 和数据；完成后新建宿主会话。
 
-**API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。Key 不接受对话、命令参数或 JSON 文件。
+**API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。
 
 | 环境变量 | 服务 | 不配置时 |
 | --- | --- | --- |
@@ -94,11 +107,13 @@ npx bookmark-research@latest install
 | `PARALLEL_API_KEY` | Parallel 搜索与网页读取 | 免费匿名使用，额度较低 |
 | `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 任务 | 功能关闭；宿主自己的研究不受影响 |
 
-setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数据目录>/research`，路径可改），或放在书签文件／文件夹旁边（放不了时退回统一目录）。只影响新的研究，已有任务留在原处。接着问研究结束后是否整理进 Wiki：给出建议并先问你（默认）、自动、关闭。
-
-研究深度、答复语言、服务选择、归档、结果位置、Wiki 整理这些偏好，也可以直接在宿主会话里让 agent 改，它会调用 `update_settings` 工具。
+在 setup 的密钥步骤，用空格勾选已启用服务所需的 Key，再在隐藏输入框逐个输入；不选即可跳过。Key 保存在独立的私有 `credentials.json`，也可由环境变量提供，且环境变量优先。Key 不放进 `prefs.json` 或 `settings.json`；设置 JSON 导入会拒绝凭据字段。每个 Key 对应的服务见[配置指南](docs/configuration.md)。偏好也可以直接在宿主会话里让 agent 改（「显示 Bookmark Research 的配置」「以后只用 Exa 搜索」），它会调用 `update_settings` 工具。
 
 ## 数据保存在哪里
 
@@ -114,13 +129,15 @@ setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数
 | `raw-library.sqlite3` | `search_archive` 使用的全文索引，可重建 |
 | `${XDG_CONFIG_HOME:-~/.config}/bookmark-research/` | `settings.json` 和 `credentials.json`（仅当前用户可读） |
 
+位置设置只影响新的研究任务，已有任务留在原处。
+
 ## Agent 循环与子代理
 
 宿主模型负责规划、搜索／阅读、评估证据，再追查未解决的问题。Skill 指导这个循环，MCP 保存输入范围、证据、预算和进度；保存研究任务不会启动后台代理。
 
-对于分组报告，插件提供“阅读代理 → 新的验证代理 → 覆盖检查 → 补查 → 报告”的流程。Codex 使用原生子代理和附带的委派指南；Claude Code、DSH 使用已加载的宿主工作流接口；Pi 需要加载相应的子代理／工作流扩展。并发、取消和代理生命周期由宿主管理。每个子代理都需要拿到相关指令，并访问同一个研究存储。
+对于分组报告，插件提供“阅读代理 → 新的验证代理 → 覆盖检查 → 补查 → 报告”的流程。Codex 使用原生子代理和附带的委派指南；Claude Code、DeepSeek Harness (dsh) 使用已加载的宿主工作流接口。并发、取消和代理生命周期由宿主管理。每个子代理都需要拿到相关指令，并访问同一个研究存储。
 
-工作流适配已有模拟接口测试，但安装成功不代表所有宿主都已跑通完整的多代理任务。所需条件见[宿主工作流](skills/bookmark-research/references/zh/host-workflows.md)，实际验证范围见[验证记录](docs/validation-0.4.0.md#host-and-provider-boundaries)。
+工作流适配已有模拟接口测试，但安装成功不代表所有宿主都已跑通完整的多代理任务。所需条件见[宿主工作流](skills/bookmark-research/references/zh/host-workflows.md)；历史验证记录可从 Git 历史查阅。
 
 ## 插件包含什么
 
@@ -129,21 +146,26 @@ setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数
 | 层 | 组成 | 运行方式 | 需要配置 |
 | --- | --- | --- | --- |
 | Skill | [`bookmark-research`](skills/bookmark-research/SKILL.md) 及 11 份方法参考，每份都有[中文版](skills/bookmark-research/references/zh/skill-guide.md) | 由宿主加载 | 不需要 |
-| 本地 MCP | `bookmark-research`，40 个工具（见下表；随能力增长） | 宿主启动的 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 时可搜索） | HTTPS | 可选 `JINA_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 的工具：
 
 | 分类 | 工具 |
 | --- | --- |
-| 书签 | `sync_package`、`index_status`、`source_history`、`source_remove`、`source_merge`、`search_bookmarks`、`get_context` |
-| 网页 | `search_web`、`fetch_web`、`search_archive`、`search_providers` |
-| 研究 | `research_readiness`、`research_start`、`research_status`、`research_search`、`research_fetch`、`research_source`、`research_record`、`research_inventory`、`research_coverage`、`research_import_evidence`、`research_finish`、`research_route` |
-| 专业研究服务（可选） | `research_services`、`research_service_prepare`、`_start`、`_status`、`_result`、`_cancel`、`_attach`、`_import` |
-| 设置 | `get_settings`、`update_settings` |
-| Wiki 与评测 | `wiki_write`、`wiki_get`、`wiki_list`、`wiki_search`、`wiki_lint`、`wiki_acknowledge`、`evaluate_research` |
+| 画布上下文 | `sync_package`、`index_status`、`search_bookmarks`、`get_context`、`plan_research` |
+| 联网与归档 | `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` |
+
+`plan_research` 返回本地候选，并独立检索 Wiki／归档；相关性和后续调查由宿主判断。没有画布来源也能使用。`wiki_write` 一次接收编写好的章节、精确引文与来源正文或 capture ID；研究 API 可直接接收问题，无需先创建本地研究会话。
+
+`deep` 预设额外提供来源维护、完整研究记录、选路诊断与 Wiki 维护，用于明确要求的完整审计和断点续做。Git 时间上下文由宿主 shell 查询。
 
 ## 更多
 

package/bin/bookmark-research.js

@@ -22,8 +22,16 @@ if (!python) {
   process.exit(1);
 }
 
+// The same file is installed as `bookmark-research` and as the short alias
+// `bookmark`. A leading literal `research` is accepted in both spellings, so
+// `bookmark status`, `bookmark research status` and `bookmark-research status`
+// all run the same command, while `bookmark` or `bookmark research` alone
+// opens the menu.
+const args = process.argv.slice(2);
+if (args[0] === "research") args.shift();
+
 const [command, ...prefix] = python;
-const child = spawn(command, [...prefix, launcher, ...process.argv.slice(2)], { stdio: "inherit", windowsHide: true });
+const child = spawn(command, [...prefix, launcher, ...args], { stdio: "inherit", windowsHide: true });
 // The terminal delivers Ctrl+C to the whole process group; let Python handle it.
 process.on("SIGINT", () => {});
 child.on("exit", (code, signal) => process.exit(signal ? 130 : code ?? 1));

package/config/providers.json

@@ -89,6 +89,47 @@
         "note": "May be advertised to keyless clients but requires an API key to execute. The aggregator routes search and extraction only."
       },
       "docs": "https://docs.tavily.com/documentation/mcp"
+    },
+    "deepseek": {
+      "label": "DeepSeek Search / Fetch",
+      "url": "https://api.deepseek.com",
+      "transport": "http",
+      "client": "deepseek",
+      "search_url": "https://api.deepseek.com/v1/tools/search",
+      "fetch_url": "https://api.deepseek.com/v1/tools/fetch",
+      "search_tools": ["deepseek_search"],
+      "fetch_tools": ["deepseek_fetch"],
+      "direct_client": true,
+      "optional_bearer_env": "DEEPSEEK_API_KEY",
+      "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"
+  }
+}