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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/README.md +54 -51
  4. package/README.zh.md +50 -48
  5. package/docs/beta15-improvement-plan-2026-10-17.md +469 -0
  6. package/docs/details.en.md +2 -0
  7. package/docs/distribution.md +1 -1
  8. package/docs/installation.en.md +1 -1
  9. package/docs/installation.md +1 -1
  10. package/docs/release-notes-0.5.0-beta.15.md +44 -0
  11. package/hosts/dsh/workflow-call.py +21 -5
  12. package/hosts/pi/register-workflow.py +26 -18
  13. package/hosts/shared/discovery-flow.js +211 -0
  14. package/hosts/shared/discovery.json +14 -0
  15. package/hosts/shared/research-call.py +4 -2
  16. package/package.json +1 -1
  17. package/scripts/host_assets.py +25 -15
  18. package/skills/bookmark-research/SKILL.md +2 -0
  19. package/skills/bookmark-research/references/cli.md +2 -1
  20. package/skills/bookmark-research/references/deep-research.md +7 -1
  21. package/skills/bookmark-research/references/host-workflows.md +14 -3
  22. package/skills/bookmark-research/references/package-semantics.md +4 -1
  23. package/skills/bookmark-research/references/settings-and-archive.md +2 -2
  24. package/skills/bookmark-research/references/wiki-and-evaluation.md +1 -1
  25. package/skills/bookmark-research/references/zh/cli.md +2 -1
  26. package/skills/bookmark-research/references/zh/deep-research.md +7 -1
  27. package/skills/bookmark-research/references/zh/host-workflows.md +14 -3
  28. package/skills/bookmark-research/references/zh/package-semantics.md +4 -1
  29. package/skills/bookmark-research/references/zh/settings-and-archive.md +2 -2
  30. package/skills/bookmark-research/references/zh/skill-guide.md +2 -0
  31. package/skills/bookmark-research/references/zh/wiki-and-evaluation.md +1 -1
  32. package/src/archive.py +174 -2
  33. package/src/bookmark_index.py +278 -4
  34. package/src/cli.py +3 -0
  35. package/src/context_output.py +10 -4
  36. package/src/discovery.py +110 -0
  37. package/src/mcp_server.py +40 -9
  38. package/src/onboarding.py +3 -2
  39. package/src/research.py +137 -6
  40. package/src/research_plan.py +87 -0
  41. package/src/search_results.py +4 -1
  42. package/src/web_search.py +75 -12
  43. package/src/wiki.py +27 -5
package/.agents/plugins/marketplace.json CHANGED
@@ -9,7 +9,7 @@
9
9
  "source": {
10
10
  "source": "npm",
11
11
  "package": "bookmark-research",
12
- "version": "0.5.0-beta.14",
12
+ "version": "0.5.0-beta.15",
13
13
  "registry": "https://registry.npmjs.org"
14
14
  },
15
15
  "policy": {
package/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bookmark-research",
3
- "version": "0.5.0-beta.14",
3
+ "version": "0.5.0-beta.15",
4
4
  "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
5
5
  "author": {
6
6
  "name": "kwenxu"
package/README.md CHANGED
@@ -5,60 +5,61 @@
5
5
  [![GitHub Bookmark-Canvas](https://img.shields.io/badge/GitHub-Bookmark--Canvas-181717?logo=github&logoColor=white)](https://github.com/Browser-bookmark-hub/Bookmark-Canvas)
6
6
  [![npm version](https://img.shields.io/npm/v/bookmark-research/beta?logo=npm)](https://www.npmjs.com/package/bookmark-research)
7
7
 
8
- 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.
9
-
10
- Works in **Codex, Claude Code, Pi and DSH (DeepSeek Harness)**.
8
+ 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)**.
11
9
 
12
10
  [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)
13
11
 
14
12
  > [!NOTE]
15
- > **0.5.0 is a beta.** Report problems on [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues).
13
+ > **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).
14
+
15
+ ## How it works
16
16
 
17
- **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.
17
+ - **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.
18
+ - **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.
19
+ - **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.
18
20
 
19
21
  ## Requirements
20
22
 
21
- - Python 3.9+ with SQLite FTS5 (check with `bookmark-research doctor`)
22
- - 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)
23
- - Node 18+ and npm for release installation (including the GitHub convenience script)
24
- - No API key is needed to install or to query bookmarks locally
23
+ - Python 3.9+ with SQLite FTS5 (checked by `bookmark-research doctor`)
24
+ - 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
25
+ - Node 18+ and npm to install a release
26
+ - No API key is needed to install, or to query bookmarks locally
25
27
 
26
28
  ## Install
27
29
 
28
- **Current beta (`0.5.0-beta.14`)**, interactive on macOS, Linux and Windows:
29
-
30
30
  ```sh
31
- npx bookmark-research@0.5.0-beta.14 install
31
+ npx bookmark-research@beta install
32
32
  ```
33
33
 
34
- 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).
35
-
36
- **Default-channel interactive installation:**
34
+ `@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):
37
35
 
38
36
  ```sh
39
- npx bookmark-research@latest install
37
+ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
40
38
  ```
41
39
 
42
- 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.
40
+ ### What the installer asks
43
41
 
44
- 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`.
42
+ 1. **Clients** — arrow keys and Space to toggle; detected CLIs are preselected. The install plan is shown for confirmation.
43
+ 2. **Research depth (optional)** — leave `auto` and the depth is picked from each request; set `quick`, `agentic` or `deep` only to pin one default.
44
+ 3. **Answer and report language** — follow the question, Chinese or English.
45
+ 4. **Search and page-reading services** — one ordered multiselect. Unselected providers become the fallback search tier.
46
+ 5. **Storage** — the default data folder, one custom folder for archives and reports, or reports beside the bookmark file or folder.
47
+ 6. **Optional professional APIs** — off by default: OpenAI Deep Research or the Parallel Task API.
48
+ 7. **API keys** — one hidden prompt per selected key, checked immediately; every key is optional.
49
+ 8. **Service check** — runs on its own and reports each provider; a sample search/read test is opt-in.
45
50
 
46
- **One client, no prompts:**
51
+ 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.
52
+
53
+ ### Non-interactive install
47
54
 
48
55
  | Client | Command | Registers with |
49
56
  | --- | --- | --- |
50
- | Codex | `npx bookmark-research@latest install codex --non-interactive` | `codex plugin add` |
51
- | Claude Code | `npx bookmark-research@latest install claude --scope user --non-interactive` | `claude plugin install` |
52
- | Pi | `npx bookmark-research@latest install pi --non-interactive` | `pi install` |
53
- | DSH | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
54
-
55
- **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).
56
-
57
- **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).
57
+ | Codex | `npx bookmark-research@beta install codex --non-interactive` | `codex plugin add` |
58
+ | Claude Code | `npx bookmark-research@beta install claude --scope user --non-interactive` | `claude plugin install` |
59
+ | Pi | `npx bookmark-research@beta install pi --non-interactive` | `pi install` |
60
+ | DSH | `npx bookmark-research@beta install dsh --profile web --non-interactive` | `dsh plugin add` |
58
61
 
59
- **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.
60
-
61
- 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).
62
+ 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).
62
63
 
63
64
  **Ask your agent to install it.** Paste this into Codex, Claude Code, Pi or DSH:
64
65
 
@@ -66,34 +67,38 @@ Several at once: `npx bookmark-research@latest install claude dsh --profile web
66
67
  Install the Bookmark Research plugin into the client you are running in.
67
68
 
68
69
  1. Identify your own client: codex, claude, pi or dsh.
69
- 2. Run: npx bookmark-research@latest install <client> --non-interactive
70
+ 2. Run: npx bookmark-research@beta install <client> --non-interactive
70
71
  - Claude Code or Pi: add --scope user (or --scope project --project <dir>).
71
72
  - DSH: add --profile <profile>; ask me for the profile name.
72
73
  3. The command prints JSON. Confirm "verified": true and report any "error".
73
74
  4. Do not ask me for API keys in chat. Tell me to run `bookmark-research setup`
74
- (or `npx bookmark-research@latest setup`) in my terminal to enter them.
75
+ in my terminal to enter them.
75
76
  5. Tell me to start a new session so the Skill and MCP tools load.
76
77
  ```
77
78
 
78
- ## Configure and API keys
79
+ Install notes:
80
+
81
+ - **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).
82
+ - **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.
83
+ - **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.
79
84
 
80
- No reinstall is needed. Settings and keys apply to every installed client; start a new client session after changing them.
85
+ ## Configure and update
86
+
87
+ **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.
81
88
 
82
89
  | Task | Command |
83
90
  | --- | --- |
84
- | Menu: configure, check, install, update | `bookmark-research` (alias `bookmark`, or `bookmark research`) |
85
91
  | Preferences and API keys | `bookmark-research setup` |
86
- | Installed clients, preferences, storage locations, recent research, key status | `bookmark-research status` |
87
- | Script preferences | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
92
+ | Menu | `bookmark-research` · `bookmark` · `bookmark research` |
93
+ | Clients, preferences, storage, recent research, key status | `bookmark-research status` |
94
+ | Scripted preferences | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
88
95
  | Update or verify all clients | `bookmark-research update` · `bookmark-research verify` |
89
96
 
90
- Use `npx bookmark-research@latest …` if the command is not installed globally.
91
-
92
- **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.
97
+ 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.
93
98
 
94
- **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.
99
+ **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.
95
100
 
96
- **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.
101
+ **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.
97
102
 
98
103
  | Variable | Service | Without it |
99
104
  | --- | --- | --- |
@@ -103,9 +108,7 @@ Use `npx bookmark-research@latest …` if the command is not installed globally.
103
108
  | `JINA_API_KEY` | Jina search | Jina Reader still reads pages anonymously |
104
109
  | `OPENAI_API_KEY` | Optional OpenAI Deep Research runs | Feature off; host-led research still works |
105
110
 
106
- 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.
107
-
108
- 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.
111
+ 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.
109
112
 
110
113
  ## Where data is stored
111
114
 
@@ -121,7 +124,9 @@ Nothing is written into your bookmark files or the plugin. The data directory is
121
124
  | `raw-library.sqlite3` | Rebuildable full-text index for `search_archive` |
122
125
  | `${XDG_CONFIG_HOME:-~/.config}/bookmark-research/` | `settings.json` and `credentials.json` (private, owner-only) |
123
126
 
124
- ## Agent loops and delegation
127
+ Changing the location affects new research only; existing tasks stay where they are.
128
+
129
+ ## Research loops and delegation
125
130
 
126
131
  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.
127
132
 
@@ -136,20 +141,18 @@ A bundle of one Skill, one local MCP server, and the remote MCPs and services th
136
141
  | Layer | Component | Runs as | Setup |
137
142
  | --- | --- | --- | --- |
138
143
  | 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 |
139
- | Local MCP | `bookmark-research`, 42 tools (below; the list grows with capabilities) | Python process started by the client | Installed for you |
144
+ | Local MCP | `bookmark-research`, 44 tools (below) | Python process started by the client | Installed for you |
140
145
  | 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 |
141
146
  | HTTP service, called by the local MCP | [Jina Reader](https://jina.ai/reader) (fallback reading; search with a key) | HTTPS | Optional `JINA_API_KEY` |
142
147
  | Optional client MCPs | Exa Agent, Parallel Task MCP, Tavily Research | Added to your client by you | `bookmark-research setup` shows the steps |
143
148
 
144
149
  Local MCP tools:
145
150
 
146
- 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).
147
-
148
151
  | Group | Tools |
149
152
  | --- | --- |
150
- | Bookmarks | `sync_package`, `index_status`, `source_history`, `source_remove`, `source_merge`, `search_bookmarks`, `get_context` |
153
+ | Bookmarks | `sync_package`, `index_status`, `source_history`, `source_remove`, `source_merge`, `search_bookmarks`, `get_context`, `plan_research` |
151
154
  | Web | `search_web`, `fetch_web`, `search_archive`, `search_providers` |
152
- | 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` |
155
+ | 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` |
153
156
  | Research services (optional) | `research_services`, `research_service_prepare`, `_start`, `_status`, `_result`, `_cancel`, `_attach`, `_import` |
154
157
  | Settings | `get_settings`, `update_settings` |
155
158
  | 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 CHANGED
@@ -5,60 +5,61 @@
5
5
  [![GitHub Bookmark-Canvas](https://img.shields.io/badge/GitHub-Bookmark--Canvas-181717?logo=github&logoColor=white)](https://github.com/Browser-bookmark-hub/Bookmark-Canvas)
6
6
  [![npm version](https://img.shields.io/npm/v/bookmark-research/beta?logo=npm)](https://www.npmjs.com/package/bookmark-research)
7
7
 
8
- 用联网查证来研究你的书签。给它一份书签 URL 列表或 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) 数据包，它会逐条核对链接、搜索和阅读网页，写出带引用、可以接着做的研究报告。
9
-
10
- 支持 **Codex、Claude Code、Pi、DSH（DeepSeek Harness）**。
8
+ 用联网查证来研究你的书签。给它一份书签 URL 列表或 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) 数据包，它会逐条核对链接、搜索和阅读网页，写出带引用、可以接着做的研究报告。支持 **Codex、Claude Code、Pi、DSH（DeepSeek Harness）**。
11
9
 
12
10
  [安装说明](docs/installation.md) · [使用指南](docs/user-guide.md) · [详细说明](docs/details.md) · [npm](https://www.npmjs.com/package/bookmark-research)
13
11
 
14
12
  > [!NOTE]
15
- > **0.5.0 是测试版。** 遇到问题请到 [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues) 反馈。
13
+ > **0.5.0 是测试版**，发布在 npm 的 `beta` 标签上；`latest` 标签仍指向更早的构建。遇到问题请到 [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues) 反馈。
14
+
15
+ ## 它是怎么工作的
16
16
 
17
- **发布版统一从 [npm](https://www.npmjs.com/package/bookmark-research) 安装。** GitHub Releases 保留版本说明和 npm 链接，安装包／测试包附件已撤下。GitHub 自动生成的 **Source code** 压缩包是源码快照，不是安装包。
17
+ - **本地理解层。** 数据包按结构读，而不是一张平铺的 URL 清单：卡片与分组的位置、连线的方向与标签、同一书签在不同卡片的出现位置（空间上下文）；日期字段、ID 中协议定义的日期段，以及真正改过内容的 Git 提交（时间上下文）。这些都是离线查询。
18
+ - **外部调研走三条路线。** 读取已知 URL 不需要推理；Agentic 搜索由宿主模型自己规划、搜索、阅读并追查缺口；深度研究在此基础上加入持续清单、独立核验、覆盖检查与报告。启用后的 OpenAI Deep Research／Parallel Task API 是另一条可选路线；无头浏览器与爬虫类项目不在集成范围内。
19
+ - **可复核的知识存储。** 完成的研究可以沉淀成 Wiki：带历史版本和相互链接的已审核页面，之后提问直接复用，不必重新搜索网页。
18
20
 
19
21
  ## 环境要求
20
22
 
21
- - Python 3.9+，含 SQLite FTS5（可用 `bookmark-research doctor` 检查）
22
- - 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH（DSH 另需 `pnpm`；若用 DeepSeek Harness 桌面版自带 CLI，则它自带 pnpm，无需另装）
23
- - 发布版安装需要 Node 18+ 和 npm（GitHub 便捷脚本也需要）
23
+ - Python 3.9+，含 SQLite FTS5（用 `bookmark-research doctor` 检查）
24
+ - 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH。DSH 另需 `pnpm`；若用 DeepSeek Harness 桌面版自带 CLI，则它自带 pnpm，无需另装
25
+ - 安装发布版需要 Node 18+ 和 npm
24
26
  - 安装和本地查书签都不需要 API Key
25
27
 
26
28
  ## 安装
27
29
 
28
- **当前测试版（`0.5.0-beta.14`）**，支持 macOS、Linux、Windows 交互安装：
29
-
30
30
  ```sh
31
- npx bookmark-research@0.5.0-beta.14 install
31
+ npx bookmark-research@beta install
32
32
  ```
33
33
 
34
- 安装器会锁定当前运行的版本，无需再手动指定 `--source`。重跑该命令可就地升级已装的 Claude Code、Pi 或 DSH，偏好、Key 和数据都保留；`@beta` 标签当前指向 `0.5.0-beta.14`。Codex 会保留登记时的来源与版本，要换版本需先移除该登记（见下文 **更新**）。
35
-
36
- **默认渠道的交互安装：**
34
+ `@beta` 跟随最新测试版；要固定某个构建可写 `@0.5.0-beta.15`。加 `--lang zh` 可让向导显示中文。想一直能用 `bookmark-research` 命令，运行 `npm install -g bookmark-research`；GitHub 便捷脚本使用同一 npm 发布版（macOS/Linux/WSL）：
37
35
 
38
36
  ```sh
39
- npx bookmark-research@latest install
37
+ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
40
38
  ```
41
39
 
42
- 用方向键和空格选择宿主，确认汇总后安装，再选择搜索服务、输入 API Key。装好后新建一个宿主会话。
40
+ ### 安装向导会问你什么
43
41
 
44
- 想一直能用 `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`。
42
+ 1. **装到哪些宿主** —— 方向键移动、空格勾选；检测到的 CLI 默认已勾选，随后显示安装计划让你确认。
43
+ 2. **默认研究深度（可选）** —— 保持 `auto` 就会按每次请求自动定档；只有想钉死一个默认时才改成 `quick`、`agentic` 或 `deep`。
44
+ 3. **答复和报告语言** —— 跟随提问语言、中文或英文。
45
+ 4. **搜索与正文读取服务** —— 一个有序多选列表；未选中的服务自动作为备用搜索层。
46
+ 5. **存放位置** —— 默认数据目录、自定义统一目录（归档与研究报告），或研究报告放在书签文件／文件夹旁边。
47
+ 6. **可选专业研究 API** —— 默认关闭：OpenAI Deep Research 或 Parallel Task API。
48
+ 7. **API Key** —— 逐个隐藏输入，当场检查；全部可选，可整段跳过。
49
+ 8. **服务检查** —— 自动运行并逐个报告；样例搜索／阅读自检需另行选择。
45
50
 
46
- **指定宿主、不弹提示：**
51
+ 回车即保留当前选项，所以整轮可能只需按几次回车。装好后新建一个宿主会话，让 Skill 和 MCP 工具生效。Wiki 整理（默认「给出建议并先问你」）和联网前的可用性检查（默认 15 分钟缓存）都已自动开启，不需要回答。
52
+
53
+ ### 指定宿主、不弹提示
47
54
 
48
55
  | 宿主 | 命令 | 实际登记方式 |
49
56
  | --- | --- | --- |
50
- | Codex | `npx bookmark-research@latest install codex --non-interactive` | `codex plugin add` |
51
- | Claude Code | `npx bookmark-research@latest install claude --scope user --non-interactive` | `claude plugin install` |
52
- | Pi | `npx bookmark-research@latest install pi --non-interactive` | `pi install` |
53
- | DSH | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
54
-
55
- **四个宿主统一发布来源：** npm 包包含共享运行时、Skill 和宿主适配。安装器下载发布包，生成所选宿主格式，再调用宿主原生命令；更新记录 npm 来源，不依赖 npx 临时缓存。GitHub 提供源码和安装清单，未发布源码用 Python 安装器。见[发布约定与官方依据](docs/distribution.md)。
56
-
57
- **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)。
57
+ | Codex | `npx bookmark-research@beta install codex --non-interactive` | `codex plugin add` |
58
+ | Claude Code | `npx bookmark-research@beta install claude --scope user --non-interactive` | `claude plugin install` |
59
+ | Pi | `npx bookmark-research@beta install pi --non-interactive` | `pi install` |
60
+ | DSH | `npx bookmark-research@beta install dsh --profile web --non-interactive` | `dsh plugin add` |
58
61
 
59
- **Windows：** Windows 上常常没有能用的 `python3`，所以安装器会把检测到的 Python 路径写进各宿主的 MCP 配置。Codex 请用 `bookmark-research install codex` 安装，不要直接把仓库加进 Codex。`bookmark-research status` 可以查看实际使用的 Python。
60
-
61
- 一次装多个：`npx bookmark-research@latest install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
62
+ 一次装多个：`npx bookmark-research@beta install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
62
63
 
63
64
  **让 agent 帮你装。** 把下面这段粘贴给 Codex、Claude Code、Pi 或 DSH：
64
65
 
@@ -66,34 +67,37 @@ npx bookmark-research@latest install
66
67
  请把 Bookmark Research 插件安装到你当前运行的这个宿主里。
67
68
 
68
69
  1. 先确认你自己是哪个宿主：codex、claude、pi 或 dsh。
69
- 2. 运行：npx bookmark-research@latest install <宿主> --non-interactive
70
+ 2. 运行：npx bookmark-research@beta install <宿主> --non-interactive
70
71
  - Claude Code 或 Pi：加 --scope user（或 --scope project --project <目录>）。
71
72
  - DSH：加 --profile <名称>；profile 名称请先问我。
72
73
  3. 命令会输出 JSON。确认 "verified": true，有 "error" 就告诉我。
73
- 4. 不要在对话里向我要 API Key。请让我在终端运行 `bookmark-research setup`
74
- （或 `npx bookmark-research@latest setup`）自己输入。
74
+ 4. 不要在对话里向我要 API Key。请让我在终端运行 `bookmark-research setup` 自己输入。
75
75
  5. 提醒我新建一个会话，让 Skill 和 MCP 工具生效。
76
76
  ```
77
77
 
78
- ## 配置与 API Key
78
+ 安装补充说明：
79
+
80
+ - **npm 是四个宿主唯一的发布来源**，包内含共享运行时、Skill 和宿主适配文件。安装器下载发布包、生成该宿主需要的格式，再调用宿主原生命令登记。GitHub 提供源码、版本说明和安装清单；未发布源码用 Python 安装器。见[发布约定](docs/distribution.md)。
81
+ - **DSH 可直接安装发布包。** 包内声明 `dsh.bundle.patch`，`dsh plugin --profile <名称> add bookmark-research@<版本>` 无需先导出即可安装。`desktop` profile 保留给 DeepSeek Harness 桌面版，请用桌面版自带 CLI 安装；安装器与向导会自行定位该 CLI。
82
+ - **Windows** 上常常没有能用的 `python3`，所以安装器会把检测到的 Python 路径写进各宿主的 MCP 配置。Codex 请用 `bookmark-research install codex` 安装，不要直接把仓库加进 Codex；`bookmark-research status` 可以查看实际使用的 Python。
79
83
 
80
- 不需要重新安装。配置和 Key 对所有已安装的宿主生效，修改后新建宿主会话即可。
84
+ ## 配置页与更新
85
+
86
+ **进入配置页。** 在终端里不带参数运行 `bookmark-research` 就会打开菜单：修改配置与 API Key、检查服务、安装到其他宿主、更新、查看状态。别名 `bookmark`（或 `bookmark research`）等价，`bookmark-research setup` 直接进入向导。
81
87
 
82
88
  | 要做什么 | 命令 |
83
89
  | --- | --- |
84
- | 主菜单：配置、检查、安装、更新 | `bookmark-research`（别名 `bookmark`，或 `bookmark research`） |
85
90
  | 修改偏好和 API Key | `bookmark-research setup` |
91
+ | 打开菜单 | `bookmark-research` · `bookmark` · `bookmark research` |
86
92
  | 查看已装宿主、偏好、保存位置、最近研究、Key 状态 | `bookmark-research status` |
87
93
  | 用脚本改偏好 | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
88
94
  | 更新或验证所有宿主 | `bookmark-research update` · `bookmark-research verify` |
89
95
 
90
- 没有全局安装时，在前面加 `npx`，例如 `npx bookmark-research@latest setup`。
91
-
92
- **进入配置页。** 在终端里不带参数运行 `bookmark-research`（或别名 `bookmark`）即可打开菜单：修改配置与 API Key、检查服务、安装到其他宿主、更新、查看状态。`bookmark-research setup` 直接进入引导向导，加上 `--lang zh` 可让向导和菜单显示中文。偏好和 Key 是用户级的，改一次就对所有已安装宿主生效；改完新建宿主会话即可。
96
+ 没有全局安装时，在前面加 `npx bookmark-research@beta`。偏好和 Key 是用户级的，改一次就对所有已安装宿主生效；改完新建宿主会话即可。加 `--lang zh` 可让向导和菜单显示中文。
93
97
 
94
- **更新。** `bookmark-research update` 会按各自登记的来源刷新所有已安装宿主，并保留偏好、Key 和数据。重跑 `npx bookmark-research@latest install` 也会就地升级已装的 Claude Code、Pi 或 DSH。Codex 安装会保留登记时的来源与版本，要换版本需先移除该登记（`codex plugin marketplace remove bookmark-research`）再重新安装。
98
+ **更新。** `bookmark-research update` 会按各自登记的来源刷新所有已安装宿主，并保留偏好、Key 和数据。重跑 `npx bookmark-research@beta install` 也会就地升级已装的 Claude Code、Pi 或 DSH。Codex 安装会保留登记时的来源与版本，要换版本需先移除该登记（`codex plugin marketplace remove bookmark-research`）再重新安装。
95
99
 
96
- **API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。Key 不接受对话、命令参数或 JSON 文件。
100
+ **API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。
97
101
 
98
102
  | 环境变量 | 服务 | 不配置时 |
99
103
  | --- | --- | --- |
@@ -103,9 +107,7 @@ npx bookmark-research@latest install
103
107
  | `JINA_API_KEY` | Jina 搜索 | Jina Reader 仍可匿名读取网页 |
104
108
  | `OPENAI_API_KEY` | 可选的 OpenAI Deep Research 任务 | 功能关闭；宿主自己的研究不受影响 |
105
109
 
106
- setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数据目录>/research`，路径可改），或放在书签文件／文件夹旁边（放不了时退回统一目录）。只影响新的研究，已有任务留在原处。接着问研究结束后是否整理进 Wiki：给出建议并先问你（默认）、自动、关闭。
107
-
108
- 研究深度、答复语言、服务选择、归档、结果位置、Wiki 整理这些偏好，也可以直接在宿主会话里让 agent 改，它会调用 `update_settings` 工具。
110
+ Key 不接受对话、命令参数或 JSON 文件。偏好也可以直接在宿主会话里让 agent 改（「显示 Bookmark Research 的配置」「以后只用 Exa 搜索」），它会调用 `update_settings` 工具。
109
111
 
110
112
  ## 数据保存在哪里
111
113
 
@@ -121,6 +123,8 @@ setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数
121
123
  | `raw-library.sqlite3` | `search_archive` 使用的全文索引，可重建 |
122
124
  | `${XDG_CONFIG_HOME:-~/.config}/bookmark-research/` | `settings.json` 和 `credentials.json`（仅当前用户可读） |
123
125
 
126
+ 位置设置只影响新的研究任务，已有任务留在原处。
127
+
124
128
  ## Agent 循环与子代理
125
129
 
126
130
  宿主模型负责规划、搜索／阅读、评估证据，再追查未解决的问题。Skill 指导这个循环，MCP 保存输入范围、证据、预算和进度；保存研究任务不会启动后台代理。
@@ -136,20 +140,18 @@ setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数
136
140
  | 层 | 组成 | 运行方式 | 需要配置 |
137
141
  | --- | --- | --- | --- |
138
142
  | Skill | [`bookmark-research`](skills/bookmark-research/SKILL.md) 及 11 份方法参考，每份都有[中文版](skills/bookmark-research/references/zh/skill-guide.md) | 由宿主加载 | 不需要 |
139
- | 本地 MCP | `bookmark-research`，42 个工具（见下表；随能力增长） | 宿主启动的 Python 进程 | 安装器自动完成 |
143
+ | 本地 MCP | `bookmark-research`，44 个工具（见下表） | 宿主启动的 Python 进程 | 安装器自动完成 |
140
144
  | 本地 MCP 调用的远程 MCP | [Exa](https://exa.ai)（搜索、网页读取）、[Parallel](https://parallel.ai)（搜索、备用读取）、[Tavily](https://tavily.com)（备用搜索） | HTTPS，不启动本地进程 | 可选 API Key |
141
145
  | 本地 MCP 调用的 HTTP 服务 | [Jina Reader](https://jina.ai/reader)（备用读取；有 Key 时可搜索） | HTTPS | 可选 `JINA_API_KEY` |
142
146
  | 可选的宿主 MCP | Exa Agent、Parallel Task MCP、Tavily Research | 需自行加到宿主里 | `bookmark-research setup` 会给出步骤 |
143
147
 
144
148
  本地 MCP 的工具：
145
149
 
146
- 下表对应当前源码；`wiki_refresh` 和 `wiki_work` 自 `0.5.0-beta.10` 起已包含在每个发布包中。已实现与剩余事项见[升级核对记录](docs/upgrade-status-2026-10-11.md)。
147
-
148
150
  | 分类 | 工具 |
149
151
  | --- | --- |
150
- | 书签 | `sync_package`、`index_status`、`source_history`、`source_remove`、`source_merge`、`search_bookmarks`、`get_context` |
152
+ | 书签 | `sync_package`、`index_status`、`source_history`、`source_remove`、`source_merge`、`search_bookmarks`、`get_context`、`plan_research` |
151
153
  | 网页 | `search_web`、`fetch_web`、`search_archive`、`search_providers` |
152
- | 研究 | `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` |
154
+ | 研究 | `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` |
153
155
  | 专业研究服务（可选） | `research_services`、`research_service_prepare`、`_start`、`_status`、`_result`、`_cancel`、`_attach`、`_import` |
154
156
  | 设置 | `get_settings`、`update_settings` |
155
157
  | Wiki 与评测 | `wiki_write`、`wiki_get`、`wiki_list`、`wiki_search`、`wiki_refresh`、`wiki_work`、`wiki_lint`、`wiki_acknowledge`、`evaluate_research` |