bookmark-research 0.5.0-beta.15 → 0.5.0-beta.17

package/.agents/plugins/marketplace.json

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

package/.codex-plugin/plugin.json

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

package/README.md

@@ -5,7 +5,7 @@
 [![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/beta?logo=npm)](https://www.npmjs.com/package/bookmark-research)
 
-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. 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)
 
@@ -15,13 +15,13 @@ Research your bookmarks with verified web sources. Give it a list of bookmark UR
 ## 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 adds a persistent inventory, independent verification, a coverage check and a report. Enabled OpenAI Deep Research or Parallel Task API runs are a separate, optional route; headless-browser and scraping projects are not bundled.
+- **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.
 - **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 (checked by `bookmark-research doctor`)
-- The CLI of at least one client: Codex, Claude Code, Pi or DSH. DSH also needs `pnpm`, unless it is the DeepSeek Harness Desktop CLI, which carries its own
+- 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
 
@@ -31,7 +31,7 @@ Research your bookmarks with verified web sources. Give it a list of bookmark UR
 npx bookmark-research@beta install
 ```
 
-`@beta` follows the newest prerelease; pin one build with `@0.5.0-beta.15`. Add `--lang zh` for the Chinese wizard. For a permanent command, run `npm install -g bookmark-research`; the GitHub convenience script uses the same npm release (macOS/Linux/WSL):
+`@beta` follows the newest prerelease; pin one build with `@0.5.0-beta.17`. Add `--lang zh` for the Chinese wizard. For a permanent command, run `npm install -g bookmark-research`; the GitHub convenience script uses the same npm release (macOS/Linux/WSL):
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
@@ -48,7 +48,7 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 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.
 
-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 (suggest and ask first) and the pre-research availability check (15-minute cache) are on by default and need no answer.
+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.
 
 ### Non-interactive install
 
@@ -56,20 +56,19 @@ Enter keeps the highlighted value, so a full run can be just a few keystrokes. T
 | --- | --- | --- |
 | Codex | `npx bookmark-research@beta install codex --non-interactive` | `codex plugin add` |
 | Claude Code | `npx bookmark-research@beta install claude --scope user --non-interactive` | `claude plugin install` |
-| Pi | `npx bookmark-research@beta install pi --non-interactive` | `pi install` |
-| DSH | `npx bookmark-research@beta install dsh --profile web --non-interactive` | `dsh plugin add` |
+| DeepSeek Harness (dsh) | `npx bookmark-research@beta install dsh --profile web --non-interactive` | `dsh plugin add` |
 
-Several at once: `npx bookmark-research@beta 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).
+Several at once: `npx bookmark-research@beta 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).
 
-**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.
+1. Identify your own client: codex, claude or dsh.
 2. Run: npx bookmark-research@beta 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.
+   - 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`
    in my terminal to enter them.
@@ -78,8 +77,8 @@ Install the Bookmark Research plugin into the client you are running in.
 
 Install notes:
 
-- **npm is the single release source** for all four 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).
-- **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.
+- **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.
 
 ## Configure and update
@@ -94,9 +93,9 @@ Install notes:
 | Scripted preferences | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
 | Update or verify all clients | `bookmark-research update` · `bookmark-research verify` |
 
-Use `npx bookmark-research@beta …` 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.
+Use `npx bookmark-research@beta …` 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.
 
-**Update.** `bookmark-research update` refreshes every installed client from its registered source and keeps preferences, keys and data. Re-running `npx bookmark-research@beta install` also upgrades an existing Claude Code, Pi or DSH installation in place. A Codex installation keeps the source and version it was registered with; to move it to another version, remove that registration first (`codex plugin marketplace remove bookmark-research`) and install again.
+**Update.** `bookmark-research update` refreshes every installed client from its registered source and keeps preferences, keys and data. Re-running `npx bookmark-research@beta install` also upgrades an existing Claude Code or DeepSeek Harness (dsh) installation in place. A Codex installation keeps the source and version it was registered with; to move it to another version, remove that registration first (`codex plugin marketplace remove bookmark-research`) and install again.
 
 **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.
 
@@ -106,6 +105,7 @@ Use `npx bookmark-research@beta …` if the command is not installed globally. P
 | `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 |
 | `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.
@@ -130,9 +130,9 @@ Changing the location affects new research only; existing tasks stay where they
 
 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
 
@@ -140,22 +140,25 @@ 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`, 44 tools (below) | 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`, 21 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/) (optional; raw JSON tools API) | HTTPS | Optional `JINA_API_KEY`, `DEEPSEEK_API_KEY` |
 | 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`, `plan_research` |
-| 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`, `discovery_bundle` |
-| 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`, `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_refresh`, `wiki_work`, `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

@@ -5,7 +5,7 @@
 [![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/beta?logo=npm)](https://www.npmjs.com/package/bookmark-research)
 
-用联网查证来研究你的书签。给它一份书签 URL 列表或 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) 数据包，它会逐条核对链接、搜索和阅读网页，写出带引用、可以接着做的研究报告。支持 **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)
 
@@ -15,13 +15,13 @@
 ## 它是怎么工作的
 
 - **本地理解层。** 数据包按结构读，而不是一张平铺的 URL 清单：卡片与分组的位置、连线的方向与标签、同一书签在不同卡片的出现位置（空间上下文）；日期字段、ID 中协议定义的日期段，以及真正改过内容的 Git 提交（时间上下文）。这些都是离线查询。
-- **外部调研走三条路线。** 读取已知 URL 不需要推理；Agentic 搜索由宿主模型自己规划、搜索、阅读并追查缺口；深度研究在此基础上加入持续清单、独立核验、覆盖检查与报告。启用后的 OpenAI Deep Research／Parallel Task API 是另一条可选路线；无头浏览器与爬虫类项目不在集成范围内。
+- **外部调研走三条路线。** 读取已知 URL 不需要推理；Agentic 搜索由宿主模型自己规划、搜索、阅读并追查缺口；Deep Research 可直接调用 OpenAI／Parallel 研究 API；完整清单与覆盖审计在明确需要时启用。宿主已有的浏览器与爬虫可提供来源正文。
 - **可复核的知识存储。** 完成的研究可以沉淀成 Wiki：带历史版本和相互链接的已审核页面，之后提问直接复用，不必重新搜索网页。
 
 ## 环境要求
 
 - Python 3.9+，含 SQLite FTS5（用 `bookmark-research doctor` 检查）
-- 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH。DSH 另需 `pnpm`；若用 DeepSeek Harness 桌面版自带 CLI，则它自带 pnpm，无需另装
+- 至少一个宿主的 CLI：Codex、Claude Code 或 DeepSeek Harness (dsh)。DeepSeek Harness (dsh) 另需 `pnpm`；若用 DeepSeek Harness 桌面版自带 CLI，则它自带 pnpm，无需另装
 - 安装发布版需要 Node 18+ 和 npm
 - 安装和本地查书签都不需要 API Key
 
@@ -31,7 +31,7 @@
 npx bookmark-research@beta install
 ```
 
-`@beta` 跟随最新测试版；要固定某个构建可写 `@0.5.0-beta.15`。加 `--lang zh` 可让向导显示中文。想一直能用 `bookmark-research` 命令，运行 `npm install -g bookmark-research`；GitHub 便捷脚本使用同一 npm 发布版（macOS/Linux/WSL）：
+`@beta` 跟随最新测试版；要固定某个构建可写 `@0.5.0-beta.17`。加 `--lang zh` 可让向导显示中文。想一直能用 `bookmark-research` 命令，运行 `npm install -g bookmark-research`；GitHub 便捷脚本使用同一 npm 发布版（macOS/Linux/WSL）：
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
@@ -48,7 +48,7 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 7. **API Key** —— 逐个隐藏输入，当场检查；全部可选，可整段跳过。
 8. **服务检查** —— 自动运行并逐个报告；样例搜索／阅读自检需另行选择。
 
-回车即保留当前选项，所以整轮可能只需按几次回车。装好后新建一个宿主会话，让 Skill 和 MCP 工具生效。Wiki 整理（默认「给出建议并先问你」）和联网前的可用性检查（默认 15 分钟缓存）都已自动开启，不需要回答。
+回车即保留当前选项，所以整轮可能只需按几次回车。装好后新建一个宿主会话，让 Skill 和 MCP 工具生效。Wiki 默认建议整理；已有保存授权时直接执行。服务诊断保留 15 分钟缓存，按需调用。
 
 ### 指定宿主、不弹提示
 
@@ -56,20 +56,19 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 | --- | --- | --- |
 | Codex | `npx bookmark-research@beta install codex --non-interactive` | `codex plugin add` |
 | Claude Code | `npx bookmark-research@beta install claude --scope user --non-interactive` | `claude plugin install` |
-| Pi | `npx bookmark-research@beta install pi --non-interactive` | `pi install` |
-| DSH | `npx bookmark-research@beta install dsh --profile web --non-interactive` | `dsh plugin add` |
+| DeepSeek Harness (dsh) | `npx bookmark-research@beta install dsh --profile web --non-interactive` | `dsh plugin add` |
 
-一次装多个：`npx bookmark-research@beta install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
+一次装多个：`npx bookmark-research@beta install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code）。全部参数见[安装说明](docs/installation.md)。
 
-**让 agent 帮你装。** 把下面这段粘贴给 Codex、Claude Code、Pi 或 DSH：
+**让 agent 帮你装。** 把下面这段粘贴给 Codex、Claude Code 或 DeepSeek Harness (dsh)：
 
 ```text
 请把 Bookmark Research 插件安装到你当前运行的这个宿主里。
 
-1. 先确认你自己是哪个宿主：codex、claude、pi 或 dsh。
+1. 先确认你自己是哪个宿主：codex、claude 或 dsh。
 2. 运行：npx bookmark-research@beta install <宿主> --non-interactive
-   - Claude Code 或 Pi：加 --scope user（或 --scope project --project <目录>）。
-   - DSH：加 --profile <名称>；profile 名称请先问我。
+   - Claude Code：加 --scope user（或 --scope project --project <目录>）。
+   - DeepSeek Harness (dsh)：加 --profile <名称>；profile 名称请先问我。
 3. 命令会输出 JSON。确认 "verified": true，有 "error" 就告诉我。
 4. 不要在对话里向我要 API Key。请让我在终端运行 `bookmark-research setup` 自己输入。
 5. 提醒我新建一个会话，让 Skill 和 MCP 工具生效。
@@ -77,8 +76,8 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 
 安装补充说明：
 
-- **npm 是四个宿主唯一的发布来源**，包内含共享运行时、Skill 和宿主适配文件。安装器下载发布包、生成该宿主需要的格式，再调用宿主原生命令登记。GitHub 提供源码、版本说明和安装清单；未发布源码用 Python 安装器。见[发布约定](docs/distribution.md)。
-- **DSH 可直接安装发布包。** 包内声明 `dsh.bundle.patch`，`dsh plugin --profile <名称> add bookmark-research@<版本>` 无需先导出即可安装。`desktop` profile 保留给 DeepSeek Harness 桌面版，请用桌面版自带 CLI 安装；安装器与向导会自行定位该 CLI。
+- **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。
 
 ## 配置页与更新
@@ -93,9 +92,9 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 | 用脚本改偏好 | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
 | 更新或验证所有宿主 | `bookmark-research update` · `bookmark-research verify` |
 
-没有全局安装时，在前面加 `npx bookmark-research@beta`。偏好和 Key 是用户级的，改一次就对所有已安装宿主生效；改完新建宿主会话即可。加 `--lang zh` 可让向导和菜单显示中文。
+没有全局安装时，在前面加 `npx bookmark-research@beta`。偏好和 Key 是用户级的，改一次就对所有已安装宿主生效；改完新建宿主会话即可。加 `--lang zh` 可让向导和菜单显示中文。工具面可用 `bookmark-research config set --tool-scope-preset quick` 使用默认 21 个日常工具；`deep`（或 `all`）启用完整 43 个工具，供明确需要的完整资料审计使用。显式 `tool_scope` 仍优先于预设。
 
-**更新。** `bookmark-research update` 会按各自登记的来源刷新所有已安装宿主，并保留偏好、Key 和数据。重跑 `npx bookmark-research@beta install` 也会就地升级已装的 Claude Code、Pi 或 DSH。Codex 安装会保留登记时的来源与版本，要换版本需先移除该登记（`codex plugin marketplace remove bookmark-research`）再重新安装。
+**更新。** `bookmark-research update` 会按各自登记的来源刷新所有已安装宿主，并保留偏好、Key 和数据。重跑 `npx bookmark-research@beta install` 也会就地升级已装的 Claude Code 或 DeepSeek Harness (dsh)。Codex 安装会保留登记时的来源与版本，要换版本需先移除该登记（`codex plugin marketplace remove bookmark-research`）再重新安装。
 
 **API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。
 
@@ -105,6 +104,7 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
 | `PARALLEL_API_KEY` | Parallel 搜索与网页读取 | 免费匿名使用，额度较低 |
 | `TAVILY_API_KEY` | Tavily 备用搜索与提取 | 使用免 Key 模式 |
 | `JINA_API_KEY` | Jina 搜索 | Jina Reader 仍可匿名读取网页 |
+| `DEEPSEEK_API_KEY` | 可选的 DeepSeek Search / Fetch | 不选择即可；其他 provider 仍可用 |
 | `OPENAI_API_KEY` | 可选的 OpenAI Deep Research 任务 | 功能关闭；宿主自己的研究不受影响 |
 
 Key 不接受对话、命令参数或 JSON 文件。偏好也可以直接在宿主会话里让 agent 改（「显示 Bookmark Research 的配置」「以后只用 Exa 搜索」），它会调用 `update_settings` 工具。
@@ -129,9 +129,9 @@ Key 不接受对话、命令参数或 JSON 文件。偏好也可以直接在宿
 
 宿主模型负责规划、搜索／阅读、评估证据，再追查未解决的问题。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 历史查阅。
 
 ## 插件包含什么
 
@@ -140,21 +140,24 @@ Key 不接受对话、命令参数或 JSON 文件。偏好也可以直接在宿
 | 层 | 组成 | 运行方式 | 需要配置 |
 | --- | --- | --- | --- |
 | Skill | [`bookmark-research`](skills/bookmark-research/SKILL.md) 及 11 份方法参考，每份都有[中文版](skills/bookmark-research/references/zh/skill-guide.md) | 由宿主加载 | 不需要 |
-| 本地 MCP | `bookmark-research`，44 个工具（见下表） | 宿主启动的 Python 进程 | 安装器自动完成 |
+| 本地 MCP | `bookmark-research`，默认 21 个工具（见下表） | 宿主启动的 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/)（可选；原始 JSON tools API） | HTTPS | 可选 `JINA_API_KEY`、`DEEPSEEK_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`、`plan_research` |
-| 网页 | `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`、`discovery_bundle` |
-| 专业研究服务（可选） | `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_refresh`、`wiki_work`、`wiki_lint`、`wiki_acknowledge`、`evaluate_research` |
+| 画布上下文 | `sync_package`、`index_status`、`search_bookmarks`、`get_context`、`plan_research` |
+| 联网与归档 | `search_web`、`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/config/providers.json

@@ -89,6 +89,21 @@
         "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/"
     }
   },
   "default_providers": [

package/docs/bookmark-research-architecture.md

@@ -1,124 +1,13 @@
-# Bookmark Research 0.4.0 结构图
+# 三个宿主，共用三项基础能力
 
-用户可以直接用自然语言说明“查什么、查多大范围、要什么结果”，不用背固定提示词。安装并加载 Skill 后，由 Codex、Claude Code、Pi 或 DSH 理解请求，再调用插件工具执行。下面先看使用过程，再看内部结构。
+Codex、Claude Code、DeepSeek Harness 负责推理、工具选择、并发和最终表达。插件保留三项职责：
 
-| 研究方式 | 用户可以这样说 | 对书签／画布包怎样处理 | 交付 |
-| --- | --- | --- | --- |
-| ① 快速查证 `quick` | “打开包里 Exa 的官方文档，查一下它是否支持 MCP。” | 找到对应书签，读取已有 URL；找不到明确来源时，搜索后读取关键页。 | 简短答案与来源链接。 |
-| ② 主动搜索 `agentic` | “比较我收藏的搜索服务，查清检索、正文读取和研究能力的区别。” | 读取相关卡片说明、书签和分组语境；拆出问题，搜索、读文、比较，再根据证据缺口补查。 | 带证据的比较与结论。 |
-| ③ 深度研究 `deep` | “把整个 AI 调研包全量调查，核验排行榜，与我们的插件比较，交付报告和 Wiki。” | 冻结完整来源清单，按专题组织持续调查，保存证据，逐项审阅，检查遗漏与冲突后交付。 | 研究档案、覆盖明细、报告；按要求整理 Wiki。 |
+1. **上下文**：读取 JSON Canvas 节点、连接线、卡片与空间关系。时间信息保留来源与可信度；Git 历史直接交给宿主 shell。
+2. **外部调研**：已知 URL 直接读取；Agentic Search 由宿主判断缺口并迭代搜索／阅读，插件提供补充搜索、并发抓取与归档。Deep Research 可直接提交 OpenAI／Parallel API，无需本地研究会话。宿主已有的浏览器、爬虫或研究工具也可供稿。
+3. **LLM Wiki**：检索已有知识，一次提交正文与精确引用，保留来源、修订和页面关系，供后续调研复用。
 
-第一行是插件的“快速查证”流程。[OpenAI 官方文档](https://developers.openai.com/api/docs/guides/tools-web-search)中的 **Non-reasoning** 指模型不进行主动的多轮搜索规划，并不要求用户已经有 URL。插件可以提供短流程，但不会把宿主模型自动切成非推理模型。Exa、Parallel、Tavily 是供这些流程使用的检索服务，不与三种研究深度一一对应。
+日常流程是：**取上下文 → 独立检索 Wiki／归档 → 阅读与搜索 → 宿主形成结论 → 按授权保存 Wiki**。`plan_research` 只提供候选，既不设相关性硬门槛，也不决定研究路线；没有书签命中仍会查询其他存储。默认工具面为 21 个。
 
-默认 `research.depth=auto`：宿主根据任务判断深度，也可以遵循用户明确提出的“这次快速查证”或“这次深度研究”。`research_route` 只根据宿主报告的任务类型和可用工具建议入口；真正的工具调用、子代理启动或工作流执行由宿主发起。一般用户不需要手写这些参数。
+只有明确要求整包覆盖、持久化任务或中断后续做时，启用 `deep` 预设的完整 43 个工具及分组工作流。高级功能复用现有证据与存储；普通提问不要求经过 readiness、route、inventory 或 coverage 等阶段。
 
-```mermaid
-flowchart TB
-  Request["你说明范围、问题和交付要求"] --> Host["宿主读取 Skill<br/>判断采用哪种研究方式"]
-  Host --> Context["按任务范围定位书签<br/>读取卡片说明、文件夹、组与连线语境"]
-  Context -->|快速查证| Quick["读取目标网页<br/>必要时搜索发现来源"]
-  Context -->|主动搜索| Agentic["拆问题 → 搜索 → 读文 → 比较"]
-  Context -->|深度研究| Deep["冻结完整范围<br/>分组调查、记录证据、审阅与核验"]
-  Quick --> Answer["简短答复与来源"]
-  Agentic --> Check{"证据足够回答问题？"}
-  Check -->|还不够，补查| Agentic
-  Check -->|足够| Comparison["比较结论与证据"]
-  Deep --> Coverage{"原始来源与研究问题有缺口？"}
-  Coverage -->|有，继续调查| Deep
-  Coverage -->|完成条件满足| Report["报告与覆盖明细<br/>按要求编写 Wiki"]
-```
-
-深度研究有两条执行路线：宿主自身持续搜索、阅读、推理，必要时使用可用子代理／工作流；或者调用已启用并配置凭据的 OpenAI Deep Research API／Parallel Task API。插件实现了专业服务接口，但安装插件或在提示词里写“Deep Research”不会自动启用账户访问。实际是否可用，以当前配置和服务调用结果为准。特定宿主的专用命令，例如已加载的 Claude `/deep-research`，还要按该命令的调用方式启动。
-
-交给专业服务时，插件把明确的研究问题与选定原 URL 整理成请求；画布语境由宿主用于构造问题，本机目录不会自动变成云端可读资料。服务返回的报告进入证据档案，所引原页仍需核验，不能用一份外部报告代替整包覆盖检查。
-
-**研究深度与研究范围分别决定。** 只查一个书签就处理该书签；研究指定卡片就保留该卡片的范围；要求“研究整个包”时，默认保留整包全部原始 URL 和每个重复书签的语境。分批、子代理数量和搜索结果页数都不能缩小这个范围。深度研究中也会反复使用直接读取和主动搜索。
-
-目录、ZIP 和单卡经过同一套接入程序。书签提供要读的 URL，卡片说明、文件夹、分组和连线提供研究语境；它们保存在本地索引中。仅问“某个书签在哪张卡片”时，查本地数据即可。接入包本身不会自动开始联网研究。
-
-下面两张图对应当前 0.4.0 实现。宿主负责理解问题、模型推理、子代理或已有工作流；Plugin 提供安装封装，Skill 提供方法指令，Python 提供实际工具。CLI 和 MCP 共用同一套实现，也可以配置为共用本地数据。实线表示调用或数据流，虚线表示指令或配置影响。
-
-```mermaid
-flowchart TB
-  User["用户<br/>自然语言问题与数据包路径"] --> Host["AI 宿主<br/>Codex / Claude Code / Pi / DSH<br/>模型推理、任务组织与审阅"]
-
-  subgraph Plugin["Bookmark Research Plugin"]
-    Skill["Skill：Markdown 指令<br/>查询方法、研究规则与宿主路由"]
-    MCP["本地 MCP 入口<br/>src/mcp_server.py · 工具随能力增长（本版 40 个）"]
-    CLI["Python CLI 入口<br/>src/cli.py"]
-    Core["共用 Python 运行时<br/>Python 3.9+ 标准库"]
-    Sources["来源接入、增量同步与本地查询"]
-    Research["搜索、正文读取与研究记录"]
-    Knowledge["Wiki 保存、引用核验与质量评测"]
-    MCP --> Core
-    CLI --> Core
-    Core --> Sources
-    Core --> Research
-    Core --> Knowledge
-  end
-
-  Skill -.->|提供方法指令| Host
-  Host -->|工具调用| MCP
-  Host -->|命令调用| CLI
-  Settings["用户配置<br/>settings.json"] -.->|服务选择与存储位置| Core
-  Input["用户的画布数据<br/>目录 / ZIP / 单卡 JSON"] --> Sources
-  Research --> Remote["外部服务<br/>搜索、正文读取与可选研究 API"]
-
-  subgraph Local["本地持久化数据：位于原包和插件缓存之外"]
-    DB[("SQLite 查询索引<br/>index.sqlite3")]
-    Snapshots["来源版本快照<br/>index.sqlite3.sources/"]
-    Pages["网页响应与正文<br/>knowledge/"]
-    Runs["研究清单、证据、覆盖与报告<br/>research/"]
-    Wiki["Wiki 页面与不可变修订<br/>wiki/"]
-  end
-
-  Sources --> DB
-  Sources --> Snapshots
-  Research -->|读取书签与关系| DB
-  Research --> Pages
-  Research --> Runs
-  Knowledge -->|读取已审阅证据| Runs
-  Knowledge --> Wiki
-```
-
-各宿主的接入方式有所不同：Codex、Claude Code 使用 Skill + MCP；Pi 使用 Skill + CLI／stdio 桥，子代理工作流依赖已有扩展；DSH 使用 MCP 适配，并配置 Skill 发现和工作流服务。图中的宿主能力取决于实际安装与配置，适配实现及验证范围见[宿主支持说明](details.en.md#client-support)。
-
-SQLite 是随 Python 工具读写的本地数据库文件，用来查询书签、栏目、文件夹和画布关系，并记录来源与同步状态。它可以从来源快照重建，不需要单独启动数据库服务器。
-
-默认数据目录为 `~/.local/share/bookmark-research/`，默认配置文件为 `~/.config/bookmark-research/settings.json`。安装插件提供工具与默认设置；首次接入用户数据后才建立来源记录。本地查询无需 API 密钥，网络服务按各自的认证要求配置。
-
-数据接入与同步的关键是把**输入载体**和**来源寿命**分开。单卡中的“永久／临时”是内容类型；`snapshot`／`live` 决定后续怎样更新。
-
-```mermaid
-flowchart TB
-  Export["手动导出目录<br/>JSON + .canvas"] --> Read
-  Zip["ZIP 数据包<br/>含完整包或单卡"] --> Read
-  Card["单个卡片 JSON<br/>永久卡片 / 临时卡片"] --> Read
-  Git["GitHub 等现有同步工具"] -->|将变化同步到磁盘| Directory["长期保留的本地目录"]
-  Directory --> Read
-
-  Read["统一读取与校验<br/>source_inputs.py"] --> Register["来源登记<br/>source_manager.py<br/>source_id、路径别名、mode、completeness"]
-  Register --> Mode{"来源寿命"}
-  Mode -->|snapshot| Fixed["固定快照<br/>新导出需主动重新接入"]
-  Mode -->|live：仅目录| Live["持续目录<br/>首次接入及后续变化检查"]
-  Trigger["更新触发<br/>MCP 进程内轮询 / CLI watch<br/>查询前补检查"] --> Live
-
-  Fixed --> Sync["增量索引<br/>bookmark_index.py<br/>文件哈希比较与事务写入"]
-  Live --> Sync
-  Sync --> DB[("SQLite<br/>当前有效索引与来源状态")]
-  Sync --> Versions["来源版本快照<br/>package/：必要原始协议文件<br/>manifest.json：哈希、路径与关系"]
-  Versions -->|选择历史版本重新导入| Read
-  DB --> Query["本地书签查询与画布关系查询"]
-```
-
-新的普通导出默认使用 `snapshot`，Git 仓库内目录默认使用 `live`；已登记来源沿用原模式。同一画布换路径导出时显式沿用 `source_id`，以后记住路径别名；不同画布不会因标题或 URL 相同而合并。
-
-两种模式都会保存版本快照。局部导入保留下来的旧栏目也进入快照，因此删除原下载包后仍可使用已接入的 snapshot，并能从保存的版本恢复。默认 `completeness=partial` 保留此次未提供的文件；明确指定 `complete` 才按完整镜像删除缺失文件。已提供栏目内删除的书签仍会同步，单卡固定使用 `partial`。
-
-`live` 的后台检查跟随 MCP 进程：默认每 1 秒检查，普通变化稳定 2 秒后同步，整文件删除等待 5 秒。关闭进程后停止，重连和查询时补查。一次性 CLI 命令执行完即退出，持续监控需要运行前台 `watch`。Git 拉取、推送和登录由原有同步工具或宿主承担。
-
-无效 JSON、目录暂时消失等情况会保留上次有效索引，并返回待更新或错误状态。这部分借鉴 CodeGraph 的增量更新和恢复机制，CodeGraph 本身不是运行依赖。详细参数与恢复命令见[来源生命周期说明](../skills/bookmark-research/references/source-lifecycle.md)。
-
-普通书签查询和单个 URL 读取可以直接调用工具，无需先建立正式研究任务。正式全包研究中的搜索摘要、外部研究报告不能自动算作原始页面已读；覆盖不足时继续补查，或保存明确标记为未完成的报告。质量评测依据显式标注和运行数据，方法见[Wiki 与评测说明](wiki-quality.md)。
-
-**自动更新的边界：`live` 目录在检查时同步本地索引，不会自动抓网页、调用 LLM 或改写 Wiki。** 研究状态检查会比较冻结输入与当前索引；发生变化时提示 `source_freshness.requires_review`，Wiki 读取／核验会标记 `needs_review`。宿主据此发起补充调查和修订，旧正文、研究清单与 Wiki 修订继续保留。
+Wiki 一次写入采用 `page.sections[].citations` 与顶层 `sources`，也兼容旧的 research claim 引用格式。程序校验引文与来源完整性，语义支持由宿主或人工审阅。API 报告是二手来源，关键结论仍应核查原文。