bookmark-research 0.5.0-beta.14 → 0.5.0-beta.16

package/.agents/plugins/marketplace.json

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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bookmark-research",
-  "version": "0.5.0-beta.14",
+  "version": "0.5.0-beta.16",
   "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
   "author": {
     "name": "kwenxu"
@@ -33,6 +33,7 @@
         "BOOKMARK_RESEARCH_DATA_DIR",
         "BOOKMARK_RESEARCH_CONFIG",
         "BOOKMARK_RESEARCH_CREDENTIALS",
+        "BOOKMARK_RESEARCH_TOOL_SCOPE",
         "XDG_DATA_HOME",
         "XDG_CONFIG_HOME",
         "EXA_API_KEY",

package/README.md

@@ -5,95 +5,99 @@
 [![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 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 and DSH (DeepSeek Harness)**.
 
 [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).
+> **0.5.0 is a prerelease**, published on npm's `beta` tag; the `latest` tag still points at an older build. Report problems on [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues).
+
+## How it works
 
-**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.
+- **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.
+- **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`, unless it is the DeepSeek Harness Desktop CLI, which carries its own)
-- 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 DSH. 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.14`)**, interactive on macOS, Linux and Windows:
-
 ```sh
-npx bookmark-research@0.5.0-beta.14 install
+npx bookmark-research@beta install
 ```
 
-The installer pins the running package version and needs no `--source`. Re-running it upgrades an existing Claude Code, Pi or DSH installation in place, keeping preferences, keys and data; `@beta` currently points to `0.5.0-beta.14`. A Codex installation keeps the source and version it registered with, so change its version by removing that registration first (see **Update** below).
-
-**Default-channel interactive installation:**
+`@beta` follows the newest prerelease; pin one build with `@0.5.0-beta.16`. 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
-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
 
-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`.
+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.
+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.
 
-**One client, no prompts:**
+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.
+
+### 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; the installer and the wizard locate that bundled CLI themselves on macOS, Windows and Linux, and fall back to it when the `dsh` on PATH has no pnpm. See the [installation guide](docs/installation.en.md).
+| 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` |
+| DSH | `npx bookmark-research@beta 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@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).
 
-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 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>).
+1. Identify your own client: codex, claude or dsh.
+2. Run: npx bookmark-research@beta install <client> --non-interactive
+   - Claude Code: add --scope user (or --scope project --project <dir>).
    - 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).
+- **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` (alias `bookmark`, or `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` |
 | Update or verify all clients | `bookmark-research update` · `bookmark-research verify` |
 
-Use `npx bookmark-research@latest …` if the command is not installed globally.
-
-**Open the configuration page.** In a terminal, `bookmark-research` (or its alias `bookmark`) with no arguments opens the menu: change preferences and API keys, check services, install into another client, update, or print status. `bookmark-research setup` goes straight to the guided wizard, and adding `--lang zh` shows the wizard and menu in Chinese. Preferences and keys are user-wide, so one change applies to every installed client; start a new client session afterwards.
+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.
 
-**Update.** `bookmark-research update` refreshes every installed client from its registered source and keeps preferences, keys and data. Re-running `npx bookmark-research@latest 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 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. 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 |
 | --- | --- | --- |
@@ -103,9 +107,7 @@ Use `npx bookmark-research@latest …` if the command is not installed globally.
 | `JINA_API_KEY` | Jina search | Jina Reader still reads pages anonymously |
 | `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.
+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.
 
 ## Where data is stored
 
@@ -121,11 +123,13 @@ 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 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.
 
@@ -136,20 +140,18 @@ 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`, 42 tools (below; the list grows with capabilities) | Python process started by the client | Installed for you |
+| Local MCP | `bookmark-research`, 44 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` |
 | 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:
 
-This list describes the current source tree; `wiki_refresh` and `wiki_work` have shipped in every release since `0.5.0-beta.10`. Implementation status and remaining work: [upgrade checklist](docs/upgrade-status-2026-10-11.md).
-
 | Group | Tools |
 | --- | --- |
-| Bookmarks | `sync_package`, `index_status`, `source_history`, `source_remove`, `source_merge`, `search_bookmarks`, `get_context` |
+| 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` |
+| 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` |
 | 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` |

package/README.zh.md

@@ -5,95 +5,98 @@
 [![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）**。
+用联网查证来研究你的书签。给它一份书签 URL 列表或 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) 数据包，它会逐条核对链接、搜索和阅读网页，写出带引用、可以接着做的研究报告。支持 **Codex、Claude Code、DSH（DeepSeek Harness）**。
 
 [安装说明](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.5.0 是测试版**，发布在 npm 的 `beta` 标签上；`latest` 标签仍指向更早的构建。遇到问题请到 [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues) 反馈。
+
+## 它是怎么工作的
 
-**发布版统一从 [npm](https://www.npmjs.com/package/bookmark-research) 安装。** GitHub Releases 保留版本说明和 npm 链接，安装包／测试包附件已撤下。GitHub 自动生成的 **Source code** 压缩包是源码快照，不是安装包。
+- **本地理解层。** 数据包按结构读，而不是一张平铺的 URL 清单：卡片与分组的位置、连线的方向与标签、同一书签在不同卡片的出现位置（空间上下文）；日期字段、ID 中协议定义的日期段，以及真正改过内容的 Git 提交（时间上下文）。这些都是离线查询。
+- **外部调研走三条路线。** 读取已知 URL 不需要推理；Agentic 搜索由宿主模型自己规划、搜索、阅读并追查缺口；深度研究在此基础上加入持续清单、独立核验、覆盖检查与报告。启用后的 OpenAI Deep Research／Parallel Task API 是另一条可选路线；无头浏览器与爬虫类项目不在集成范围内。
+- **可复核的知识存储。** 完成的研究可以沉淀成 Wiki：带历史版本和相互链接的已审核页面，之后提问直接复用，不必重新搜索网页。
 
 ## 环境要求
 
-- Python 3.9+，含 SQLite FTS5（可用 `bookmark-research doctor` 检查）
-- 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH（DSH 另需 `pnpm`；若用 DeepSeek Harness 桌面版自带 CLI，则它自带 pnpm，无需另装）
-- 发布版安装需要 Node 18+ 和 npm（GitHub 便捷脚本也需要）
+- Python 3.9+，含 SQLite FTS5（用 `bookmark-research doctor` 检查）
+- 至少一个宿主的 CLI：Codex、Claude Code 或 DSH。DSH 另需 `pnpm`；若用 DeepSeek Harness 桌面版自带 CLI，则它自带 pnpm，无需另装
+- 安装发布版需要 Node 18+ 和 npm
 - 安装和本地查书签都不需要 API Key
 
 ## 安装
 
-**当前测试版（`0.5.0-beta.14`）**，支持 macOS、Linux、Windows 交互安装：
-
 ```sh
-npx bookmark-research@0.5.0-beta.14 install
+npx bookmark-research@beta install
 ```
 
-安装器会锁定当前运行的版本，无需再手动指定 `--source`。重跑该命令可就地升级已装的 Claude Code、Pi 或 DSH，偏好、Key 和数据都保留；`@beta` 标签当前指向 `0.5.0-beta.14`。Codex 会保留登记时的来源与版本，要换版本需先移除该登记（见下文 **更新**）。
-
-**默认渠道的交互安装：**
+`@beta` 跟随最新测试版；要固定某个构建可写 `@0.5.0-beta.16`。加 `--lang zh` 可让向导显示中文。想一直能用 `bookmark-research` 命令，运行 `npm install -g bookmark-research`；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。装好后新建一个宿主会话。
+### 安装向导会问你什么
 
-想一直能用 `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`。
+1. **装到哪些宿主** —— 方向键移动、空格勾选；检测到的 CLI 默认已勾选，随后显示安装计划让你确认。
+2. **默认研究深度（可选）** —— 保持 `auto` 就会按每次请求自动定档；只有想钉死一个默认时才改成 `quick`、`agentic` 或 `deep`。
+3. **答复和报告语言** —— 跟随提问语言、中文或英文。
+4. **搜索与正文读取服务** —— 一个有序多选列表；未选中的服务自动作为备用搜索层。
+5. **存放位置** —— 默认数据目录、自定义统一目录（归档与研究报告），或研究报告放在书签文件／文件夹旁边。
+6. **可选专业研究 API** —— 默认关闭：OpenAI Deep Research 或 Parallel Task API。
+7. **API Key** —— 逐个隐藏输入，当场检查；全部可选，可整段跳过。
+8. **服务检查** —— 自动运行并逐个报告；样例搜索／阅读自检需另行选择。
 
-**指定宿主、不弹提示：**
+回车即保留当前选项，所以整轮可能只需按几次回车。装好后新建一个宿主会话，让 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 安装；安装器与向导会在 macOS、Windows、Linux 上自行定位该 CLI，并在 PATH 中的 `dsh` 缺少 pnpm 时改用它。详见[安装说明](docs/installation.md)。
+| 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` |
+| DSH | `npx bookmark-research@beta 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@beta 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 或 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 <目录>）。
+1. 先确认你自己是哪个宿主：codex、claude 或 dsh。
+2. 运行：npx bookmark-research@beta install <宿主> --non-interactive
+   - Claude Code：加 --scope user（或 --scope project --project <目录>）。
    - 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)。
+- **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`（别名 `bookmark`，或 `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` |
 | 更新或验证所有宿主 | `bookmark-research update` · `bookmark-research verify` |
 
-没有全局安装时，在前面加 `npx`，例如 `npx bookmark-research@latest setup`。
-
-**进入配置页。** 在终端里不带参数运行 `bookmark-research`（或别名 `bookmark`）即可打开菜单：修改配置与 API Key、检查服务、安装到其他宿主、更新、查看状态。`bookmark-research setup` 直接进入引导向导，加上 `--lang zh` 可让向导和菜单显示中文。偏好和 Key 是用户级的，改一次就对所有已安装宿主生效；改完新建宿主会话即可。
+没有全局安装时，在前面加 `npx bookmark-research@beta`。偏好和 Key 是用户级的，改一次就对所有已安装宿主生效；改完新建宿主会话即可。加 `--lang zh` 可让向导和菜单显示中文。
 
-**更新。** `bookmark-research update` 会按各自登记的来源刷新所有已安装宿主，并保留偏好、Key 和数据。重跑 `npx bookmark-research@latest install` 也会就地升级已装的 Claude Code、Pi 或 DSH。Codex 安装会保留登记时的来源与版本，要换版本需先移除该登记（`codex plugin marketplace remove bookmark-research`）再重新安装。
+**更新。** `bookmark-research update` 会按各自登记的来源刷新所有已安装宿主，并保留偏好、Key 和数据。重跑 `npx bookmark-research@beta install` 也会就地升级已装的 Claude Code 或 DSH。Codex 安装会保留登记时的来源与版本，要换版本需先移除该登记（`codex plugin marketplace remove bookmark-research`）再重新安装。
 
-**API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。Key 不接受对话、命令参数或 JSON 文件。
+**API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。
 
 | 环境变量 | 服务 | 不配置时 |
 | --- | --- | --- |
@@ -103,9 +106,7 @@ npx bookmark-research@latest install
 | `JINA_API_KEY` | Jina 搜索 | Jina Reader 仍可匿名读取网页 |
 | `OPENAI_API_KEY` | 可选的 OpenAI Deep Research 任务 | 功能关闭；宿主自己的研究不受影响 |
 
-setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数据目录>/research`，路径可改），或放在书签文件／文件夹旁边（放不了时退回统一目录）。只影响新的研究，已有任务留在原处。接着问研究结束后是否整理进 Wiki：给出建议并先问你（默认）、自动、关闭。
-
-研究深度、答复语言、服务选择、归档、结果位置、Wiki 整理这些偏好，也可以直接在宿主会话里让 agent 改，它会调用 `update_settings` 工具。
+Key 不接受对话、命令参数或 JSON 文件。偏好也可以直接在宿主会话里让 agent 改（「显示 Bookmark Research 的配置」「以后只用 Exa 搜索」），它会调用 `update_settings` 工具。
 
 ## 数据保存在哪里
 
@@ -121,11 +122,13 @@ 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、DSH 使用已加载的宿主工作流接口。并发、取消和代理生命周期由宿主管理。每个子代理都需要拿到相关指令，并访问同一个研究存储。
 
 工作流适配已有模拟接口测试，但安装成功不代表所有宿主都已跑通完整的多代理任务。所需条件见[宿主工作流](skills/bookmark-research/references/zh/host-workflows.md)，实际验证范围见[验证记录](docs/validation-0.4.0.md#host-and-provider-boundaries)。
 
@@ -136,20 +139,18 @@ setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数
 | 层 | 组成 | 运行方式 | 需要配置 |
 | --- | --- | --- | --- |
 | Skill | [`bookmark-research`](skills/bookmark-research/SKILL.md) 及 11 份方法参考，每份都有[中文版](skills/bookmark-research/references/zh/skill-guide.md) | 由宿主加载 | 不需要 |
-| 本地 MCP | `bookmark-research`，42 个工具（见下表；随能力增长） | 宿主启动的 Python 进程 | 安装器自动完成 |
+| 本地 MCP | `bookmark-research`，44 个工具（见下表） | 宿主启动的 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 | Exa Agent、Parallel Task MCP、Tavily Research | 需自行加到宿主里 | `bookmark-research setup` 会给出步骤 |
 
 本地 MCP 的工具：
 
-下表对应当前源码；`wiki_refresh` 和 `wiki_work` 自 `0.5.0-beta.10` 起已包含在每个发布包中。已实现与剩余事项见[升级核对记录](docs/upgrade-status-2026-10-11.md)。
-
 | 分类 | 工具 |
 | --- | --- |
-| 书签 | `sync_package`、`index_status`、`source_history`、`source_remove`、`source_merge`、`search_bookmarks`、`get_context` |
+| 书签 | `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` |
+| 研究 | `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` |

package/docs/bench-preflight-2026-10-21.md

@@ -0,0 +1,85 @@
+# Preflight 规模压测（2026-10-21）
+
+> 对象：`plan_research` 预检、`RawLibrary.search_terms`、`WikiSearchIndex`。
+>
+> 方式：源码内进程内调用，不发网络请求；不写用户数据目录。脚本：[scripts/bench_preflight.py](../scripts/bench_preflight.py)。
+>
+> 环境：macOS 15.7.2、Python 3.9.6、源码基线 `e7706e1` + 当前工作树改动。
+
+## 测什么
+
+| 层 | 数据 | 说明 |
+|---|---|---|
+| 书签预检 | 1k / 5k / 10k / 50k / 100k 书签，38 个栏目 | `ResearchPlan.build(include_wiki=False, include_archive=False)`，测 `plan_scope` 主体 |
+| 归档检索 | 100 / 500 个 capture 页面 | `SourceArchive.save` + `RawLibrary.search_terms` |
+| Wiki 索引 | 100 / 1,000 个合成文档 | `WikiSearchIndex.candidates` + `match`；不含 revision 校验 |
+
+查询：
+
+- `alpha`：泛词，几乎所有卡片命中；
+- `alpha beta`：两个泛词，最重的排序路径；
+- `unique500` / `unique2500` / …：只命中一条书签的长字面词。
+
+每个场景先 warm-up 一次，再取 3 次；表中为 p50 / p95 毫秒。
+
+## 结果
+
+### 书签预检
+
+| 书签数 | `alpha` p50 / p95 | `alpha beta` p50 / p95 | 唯一长词 p50 / p95 | 输出字符 |
+|---:|---:|---:|---:|---:|
+| 1,000 | 10.3 / 10.6 | 11.8 / 11.8 | 8.0 / 8.4 | 1.8–4.1k |
+| 5,000 | 23.8 / 24.3 | 27.4 / 28.6 | 13.1 / 13.5 | 1.8–4.1k |
+| 10,000 | 41.4 / 44.4 | 51.3 / 52.2 | 17.6 / 18.0 | 1.9–4.1k |
+| 50,000 | 197.7 / 200.6 | 255.5 / 257.6 | 65.8 / 67.2 | 1.9–4.1k |
+| 100,000 | 388.5 / 391.5 | 507.5 / 509.1 | 123.1 / 123.5 | 1.9–4.1k |
+
+结论：近似线性，约 **0.4 秒/10 万书签（单泛词）**、**0.5 秒/10 万（双泛词）**；唯一长词约 **0.12 秒/10 万**。输出稳定在 4.1k 字符左右，远低于 8k 上限。
+
+100k 进程峰值 RSS 约 **330 MB**（含 Python、SQLite、临时包和索引生成）。
+
+### 归档检索
+
+| 页面数 | `alpha` p50 / p95 | `alpha beta` p50 / p95 |
+|---:|---:|---:|
+| 100 | 2.8 / 3.2 | 4.5 / 5.3 |
+| 500 | 5.3 / 9.5 | 9.5 / 10.0 |
+
+结论：500 页归档仍在 10ms 量级；当前按词逐个 `search`，每次刷新 archive 索引是主要成本，但规模不大时不是瓶颈。
+
+### Wiki 索引
+
+| 文档数 | `alpha beta` p50 / p95 |
+|---:|---:|
+| 100 | 2.0 / 2.2 |
+| 1,000 | 19.6 / 19.7 |
+
+结论：索引层 1,000 页约 20ms；真实 Wiki 还包含 revision/证据校验，未在此表内。
+
+## 判断
+
+- **当前最慢的是书签预检的全表 OR 查询**，不是 Wiki/归档。10 万书签仍低于 1 秒，可以接受；如果目标是 100 万书签，按线性外推约 4–5 秒，才需要做倒排/分批。
+- **输出预算没有随数据增长**：卡片/URL 上限固定，100k 时输出仍约 4.1k 字符，`preflight_budget` 没有触发截断。
+- **唯一长词**依赖新增的 token-aware 标题命中；这条路径比泛词快，但 100k 仍需约 0.12 秒，因为要扫标题。
+- 归档 500 页、Wiki 索引 1,000 页都不是当前瓶颈。
+
+## 复现
+
+```sh
+# 默认矩阵（1k/5k/10k/50k，100/500 归档，100/1000 Wiki）
+python3 scripts/bench_preflight.py
+
+# 更大书签量、只看书签
+python3 scripts/bench_preflight.py \
+  --sizes 100000 --sections 38 --archive-pages 0 --wiki-documents 0 --repeats 3
+
+# JSON 输出
+python3 scripts/bench_preflight.py --json
+```
+
+## 边界
+
+- 合成数据是“每张卡都有大量 alpha/beta”的偏重场景，不代表真实主题分布；真实包的时间应更低。
+- 没有经过 MCP stdio 传输、宿主调度或 `plan_research` 的 Wiki/归档完整校验；这些是单独的集成层。
+- 归档 benchmark 用同一模板但唯一页面正文，避免被 SHA-256 合并；真实归档的正文大小差异会影响 I/O。
+- 没有测 100 万书签；需要时用同一脚本加 `--sizes 1000000`，但要预留内存和时间。

package/docs/bookmark-research-architecture.md

@@ -1,6 +1,6 @@
 # Bookmark Research 0.4.0 结构图
 
-用户可以直接用自然语言说明“查什么、查多大范围、要什么结果”，不用背固定提示词。安装并加载 Skill 后，由 Codex、Claude Code、Pi 或 DSH 理解请求，再调用插件工具执行。下面先看使用过程，再看内部结构。
+用户可以直接用自然语言说明“查什么、查多大范围、要什么结果”，不用背固定提示词。安装并加载 Skill 后，由 Codex、Claude Code 或 DSH 理解请求，再调用插件工具执行。下面先看使用过程，再看内部结构。
 
 | 研究方式 | 用户可以这样说 | 对书签／画布包怎样处理 | 交付 |
 | --- | --- | --- | --- |
@@ -40,7 +40,7 @@ flowchart TB
 
 ```mermaid
 flowchart TB
-  User["用户<br/>自然语言问题与数据包路径"] --> Host["AI 宿主<br/>Codex / Claude Code / Pi / DSH<br/>模型推理、任务组织与审阅"]
+  User["用户<br/>自然语言问题与数据包路径"] --> Host["AI 宿主<br/>Codex / Claude Code / DSH<br/>模型推理、任务组织与审阅"]
 
   subgraph Plugin["Bookmark Research Plugin"]
     Skill["Skill：Markdown 指令<br/>查询方法、研究规则与宿主路由"]
@@ -81,7 +81,7 @@ flowchart TB
   Knowledge --> Wiki
 ```
 
-各宿主的接入方式有所不同：Codex、Claude Code 使用 Skill + MCP；Pi 使用 Skill + CLI／stdio 桥，子代理工作流依赖已有扩展；DSH 使用 MCP 适配，并配置 Skill 发现和工作流服务。图中的宿主能力取决于实际安装与配置，适配实现及验证范围见[宿主支持说明](details.en.md#client-support)。
+各宿主的接入方式有所不同：Codex、Claude Code 使用 Skill + MCP；DSH 使用 MCP 适配，并配置 Skill 发现和工作流服务。图中的宿主能力取决于实际安装与配置，适配实现及验证范围见[宿主支持说明](details.en.md#client-support)。
 
 SQLite 是随 Python 工具读写的本地数据库文件，用来查询书签、栏目、文件夹和画布关系，并记录来源与同步状态。它可以从来源快照重建，不需要单独启动数据库服务器。