bookmark-research 0.5.0-beta.1 → 0.5.0-beta.10

package/.agents/plugins/marketplace.json

@@ -7,8 +7,10 @@
     {
       "name": "bookmark-research",
       "source": {
-        "source": "local",
-        "path": "./"
+        "source": "npm",
+        "package": "bookmark-research",
+        "version": "0.5.0-beta.10",
+        "registry": "https://registry.npmjs.org"
       },
       "policy": {
         "installation": "AVAILABLE",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bookmark-research",
-  "version": "0.5.0-beta.1",
+  "version": "0.5.0-beta.10",
   "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
   "author": {
     "name": "kwenxu"
@@ -39,7 +39,9 @@
         "PARALLEL_API_KEY",
         "TAVILY_API_KEY",
         "JINA_API_KEY",
-        "OPENAI_API_KEY"
+        "OPENAI_API_KEY",
+        "SystemRoot",
+        "windir"
       ]
     }
   }

package/README.md

@@ -6,40 +6,56 @@ Research your bookmarks with verified web sources. Give it a list of bookmark UR
 
 Works in **Codex, Claude Code, Pi 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) · [Releases](https://github.com/Browser-bookmark-hub/Bookmark-Research/releases)
+[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).
 
+**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.
+
 ## Requirements
 
 - Python 3.9+ with SQLite FTS5 (check with `bookmark-research doctor`)
 - The CLI of at least one client: Codex, Claude Code, Pi or DSH (DSH also needs `pnpm`)
-- Node 18+ for the `bookmark-research` command; optional on macOS/Linux
+- Node 18+ and npm for release installation (including the GitHub convenience script)
 - No API key is needed to install or to query bookmarks locally
 
 ## Install
 
-**Interactive** (macOS, Linux, Windows):
+**Current beta (`0.5.0-beta.10`)**, interactive on macOS, Linux and Windows:
+
+```sh
+npx bookmark-research@0.5.0-beta.10 install --source npm:bookmark-research@0.5.0-beta.10
+```
+
+This pins both the installer and the content. The `@latest` examples below follow the default channel, which remains `0.5.0-beta.3`; `@beta` currently points to `0.5.0-beta.10`. Changing only the npx selector does not change the installer's default content source.
+
+**Default-channel interactive installation:**
 
 ```sh
-npx bookmark-research install
+npx bookmark-research@latest install
 ```
 
 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.
 
-For a permanent `bookmark-research` command: `npm install -g bookmark-research`. Without Node (macOS/Linux/WSL): `curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash`.
+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`.
 
 **One client, no prompts:**
 
 | Client | Command | Registers with |
 | --- | --- | --- |
-| Codex | `npx bookmark-research install codex --non-interactive` | `codex plugin add` |
-| Claude Code | `npx bookmark-research install claude --scope user --non-interactive` | `claude plugin install` |
-| Pi | `npx bookmark-research install pi --non-interactive` | `pi install` |
-| DSH | `npx bookmark-research install dsh --profile web --non-interactive` | `dsh plugin add` |
+| 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` |
 
-Several at once: `npx bookmark-research 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).
+**One release source for all four hosts:** npm contains the shared runtime, Skill and host adapters. The installer downloads the release, prepares the selected host format, then invokes the host’s native commands. Updates retain an npm selector rather than an npx cache path. GitHub hosts source and installation catalogs; unpublished source uses the Python installer. See [distribution policy and official references](docs/distribution.md).
+
+**DSH installs the release directly:** the published package declares `dsh.bundle.patch`, so `dsh plugin --profile <name> add bookmark-research@<version>` — or the DSH plugin manager — installs it with no export first, resolving Python and MCP paths from the installed package. DeepSeek Harness Desktop reserves the `desktop` profile for its own carrier, so install that one with the app's CLI. See the [installation guide](docs/installation.en.md).
+
+**Windows:** the installer writes the detected Python path into each client's MCP config, because Windows often has no working `python3`. Install Codex with `bookmark-research install codex` rather than adding the repository to Codex directly. `bookmark-research status` shows the interpreter in use.
+
+Several at once: `npx bookmark-research@latest install claude dsh --profile web --non-interactive`. Project scope: `--scope project --project /path/to/project` (Claude Code, Pi). All options: [installation guide](docs/installation.en.md).
 
 **Ask your agent to install it.** Paste this into Codex, Claude Code, Pi or DSH:
 
@@ -47,12 +63,12 @@ Several at once: `npx bookmark-research install claude dsh --profile web --non-i
 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 install <client> --non-interactive
+2. Run: npx bookmark-research@latest install <client> --non-interactive
    - Claude Code or Pi: add --scope user (or --scope project --project <dir>).
    - DSH: add --profile <profile>; ask me for the profile name.
 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 setup`) in my terminal to enter them.
+   (or `npx bookmark-research@latest setup`) in my terminal to enter them.
 5. Tell me to start a new session so the Skill and MCP tools load.
 ```
 
@@ -64,11 +80,11 @@ No reinstall is needed. Settings and keys apply to every installed client; start
 | --- | --- |
 | Menu: configure, check, install, update | `bookmark-research` |
 | Preferences and API keys | `bookmark-research setup` |
-| Installed clients, preferences, key status | `bookmark-research status` |
+| 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` |
 | Update or verify all clients | `bookmark-research update` · `bookmark-research verify` |
 
-Use `npx bookmark-research …` if the command is not installed globally.
+Use `npx bookmark-research@latest …` if the command is not installed globally.
 
 **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.
 
@@ -80,47 +96,62 @@ Use `npx bookmark-research …` 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 |
 
-Preferences (research depth, answer language, providers, archiving) can also be changed by asking the agent in a client session; it uses the `update_settings` tool.
+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.
 
-## What's inside
+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.
+
+## Where data is stored
 
-### Skill
+Nothing is written into your bookmark files or the plugin. The data directory is `$BOOKMARK_RESEARCH_DATA_DIR`, or `${XDG_DATA_HOME:-~/.local/share}/bookmark-research`.
 
-| Skill | Use it for |
+| Location | Contents |
 | --- | --- |
-| [`bookmark-research`](skills/bookmark-research/SKILL.md) | Query bookmarks, check links, run a full research pass over every bookmark and write a cited report. English, with a [Chinese reading copy](skills/bookmark-research/references/zh/skill-guide.md). |
+| `research/` (or `<input>.bookmark-research/` beside the input) | One folder per research task: report, sources, evidence, and `work/` for the agent's intermediate files |
+| `research-locations.json` | Where every task folder is, so tasks stay listed after the location setting changes |
+| `knowledge/` | Saved page reads: `sources/` per fetch, `pages/` with each distinct text stored once |
+| `wiki/` | Reviewed knowledge pages and revisions; `index.md` catalog and `log.md` timeline |
+| `index.sqlite3`, `index.sqlite3.sources/` | Bookmark search index and managed snapshots of imported packages |
+| `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
 
-### MCP server
+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.
 
-One local stdio server, `bookmark-research` (`python3 src/cli.py serve`), with 36 tools:
+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.
+
+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.
+
+## What's inside
+
+A bundle of one Skill, one local MCP server, and the remote MCPs and services that server connects to. The client registers only the local MCP.
+
+| 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 |
+| 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` are available in local development builds and are not included in the published `0.5.0-beta.9` package. Implementation status and remaining work: [upgrade checklist](docs/upgrade-status-2026-10-11.md).
 
 | Group | Tools |
 | --- | --- |
-| Bookmarks | `sync_package`, `index_status`, `source_history`, `search_bookmarks`, `get_context` |
-| Web | `search_web`, `fetch_web`, `search_providers` |
+| Bookmarks | `sync_package`, `index_status`, `source_history`, `source_remove`, `source_merge`, `search_bookmarks`, `get_context` |
+| Web | `search_web`, `fetch_web`, `search_archive`, `search_providers` |
 | Research | `research_readiness`, `research_start`, `research_status`, `research_search`, `research_fetch`, `research_source`, `research_record`, `research_inventory`, `research_coverage`, `research_import_evidence`, `research_finish`, `research_route` |
 | Research services (optional) | `research_services`, `research_service_prepare`, `_start`, `_status`, `_result`, `_cancel`, `_attach`, `_import` |
 | Settings | `get_settings`, `update_settings` |
-| Wiki and evaluation | `wiki_write`, `wiki_get`, `wiki_list`, `wiki_search`, `wiki_lint`, `evaluate_research` |
+| Wiki and evaluation | `wiki_write`, `wiki_get`, `wiki_list`, `wiki_search`, `wiki_refresh`, `wiki_work`, `wiki_lint`, `wiki_acknowledge`, `evaluate_research` |
 
 Tool descriptions: [details](docs/details.en.md#mcp-tools).
 
-### Web services
-
-Called by the plugin's own MCP server; you do not add their MCPs separately.
-
-| Service | Role |
-| --- | --- |
-| [Exa](https://exa.ai) | Primary search; first page reader |
-| [Parallel](https://parallel.ai) | Primary search; fallback page reader |
-| [Tavily](https://tavily.com) | Search fallback |
-| [Jina Reader](https://jina.ai/reader) | Fallback page reader; search with a key |
-
-Optional research MCPs you may add to your client yourself: Exa Agent, Parallel Task and Tavily Research. `bookmark-research setup` shows the steps for each client.
-
 ## More
 
-- [Installation guide](docs/installation.en.md): all install options, updates, ZIP downloads
+- [Installation guide](docs/installation.en.md): all install options, npm updates and source development
 - [User guide](docs/user-guide.en.md): first use, the three research modes, languages
 - [Details](docs/details.en.md): data model, research modes, settings, export formats, development checks
 - [Architecture](docs/bookmark-research-architecture.md) (Chinese)

package/README.zh.md

@@ -6,40 +6,56 @@
 
 支持 **Codex、Claude Code、Pi、DSH（DeepSeek Harness）**。
 
-[安装说明](docs/installation.md) · [使用指南](docs/user-guide.md) · [详细说明](docs/details.md) · [npm](https://www.npmjs.com/package/bookmark-research) · [Releases](https://github.com/Browser-bookmark-hub/Bookmark-Research/releases)
+[安装说明](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) 反馈。
 
+**发布版统一从 [npm](https://www.npmjs.com/package/bookmark-research) 安装。** GitHub Releases 保留版本说明和 npm 链接，安装包／测试包附件已撤下。GitHub 自动生成的 **Source code** 压缩包是源码快照，不是安装包。
+
 ## 环境要求
 
 - Python 3.9+，含 SQLite FTS5（可用 `bookmark-research doctor` 检查）
 - 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH（DSH 另需 `pnpm`）
-- `bookmark-research` 命令需要 Node 18+；macOS/Linux 上可不用
+- 发布版安装需要 Node 18+ 和 npm（GitHub 便捷脚本也需要）
 - 安装和本地查书签都不需要 API Key
 
 ## 安装
 
-**交互安装**（macOS、Linux、Windows）：
+**当前测试版（`0.5.0-beta.10`）**，支持 macOS、Linux、Windows 交互安装：
+
+```sh
+npx bookmark-research@0.5.0-beta.10 install --source npm:bookmark-research@0.5.0-beta.10
+```
+
+这条命令同时固定安装器和插件内容。下面的 `@latest` 示例使用默认渠道，目前仍为 `0.5.0-beta.3`；`@beta` 当前指向 `0.5.0-beta.10`。只改 npx 的版本选择，不会改变安装器默认下载的内容来源。
+
+**默认渠道的交互安装：**
 
 ```sh
-npx bookmark-research install
+npx bookmark-research@latest install
 ```
 
 用方向键和空格选择宿主，确认汇总后安装，再选择搜索服务、输入 API Key。装好后新建一个宿主会话。
 
-想一直能用 `bookmark-research` 命令：`npm install -g bookmark-research`。不用 Node（macOS/Linux/WSL）：`curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash`。
+想一直能用 `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`。
 
 **指定宿主、不弹提示：**
 
 | 宿主 | 命令 | 实际登记方式 |
 | --- | --- | --- |
-| Codex | `npx bookmark-research install codex --non-interactive` | `codex plugin add` |
-| Claude Code | `npx bookmark-research install claude --scope user --non-interactive` | `claude plugin install` |
-| Pi | `npx bookmark-research install pi --non-interactive` | `pi install` |
-| DSH | `npx bookmark-research install dsh --profile web --non-interactive` | `dsh plugin add` |
+| 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` |
 
-一次装多个：`npx bookmark-research install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
+**四个宿主统一发布来源：** npm 包包含共享运行时、Skill 和宿主适配。安装器下载发布包，生成所选宿主格式，再调用宿主原生命令；更新记录 npm 来源，不依赖 npx 临时缓存。GitHub 提供源码和安装清单，未发布源码用 Python 安装器。见[发布约定与官方依据](docs/distribution.md)。
+
+**DSH 可直接安装发布包：** 发布包声明 `dsh.bundle.patch`，`dsh plugin --profile <名称> add bookmark-research@<版本>`（或 DSH 插件管理界面）无需先导出即可安装，Python 与 MCP 路径按安装位置解析。DeepSeek Harness 桌面版把 `desktop` profile 保留给自身载体，该 profile 请用桌面版自带 CLI 安装。详见[安装说明](docs/installation.md)。
+
+**Windows：** Windows 上常常没有能用的 `python3`，所以安装器会把检测到的 Python 路径写进各宿主的 MCP 配置。Codex 请用 `bookmark-research install codex` 安装，不要直接把仓库加进 Codex。`bookmark-research status` 可以查看实际使用的 Python。
+
+一次装多个：`npx bookmark-research@latest install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
 
 **让 agent 帮你装。** 把下面这段粘贴给 Codex、Claude Code、Pi 或 DSH：
 
@@ -47,12 +63,12 @@ npx bookmark-research install
 请把 Bookmark Research 插件安装到你当前运行的这个宿主里。
 
 1. 先确认你自己是哪个宿主：codex、claude、pi 或 dsh。
-2. 运行：npx bookmark-research install <宿主> --non-interactive
+2. 运行：npx bookmark-research@latest install <宿主> --non-interactive
    - Claude Code 或 Pi：加 --scope user（或 --scope project --project <目录>）。
    - DSH：加 --profile <名称>；profile 名称请先问我。
 3. 命令会输出 JSON。确认 "verified": true，有 "error" 就告诉我。
 4. 不要在对话里向我要 API Key。请让我在终端运行 `bookmark-research setup`
-   （或 `npx bookmark-research setup`）自己输入。
+   （或 `npx bookmark-research@latest setup`）自己输入。
 5. 提醒我新建一个会话，让 Skill 和 MCP 工具生效。
 ```
 
@@ -64,11 +80,11 @@ npx bookmark-research install
 | --- | --- |
 | 主菜单：配置、检查、安装、更新 | `bookmark-research` |
 | 修改偏好和 API Key | `bookmark-research setup` |
-| 查看已装宿主、偏好、Key 状态 | `bookmark-research status` |
+| 查看已装宿主、偏好、保存位置、最近研究、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 setup`。
+没有全局安装时，在前面加 `npx`，例如 `npx bookmark-research@latest setup`。
 
 **API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。Key 不接受对话、命令参数或 JSON 文件。
 
@@ -80,45 +96,60 @@ npx bookmark-research install
 | `JINA_API_KEY` | Jina 搜索 | Jina Reader 仍可匿名读取网页 |
 | `OPENAI_API_KEY` | 可选的 OpenAI Deep Research 任务 | 功能关闭；宿主自己的研究不受影响 |
 
-研究深度、答复语言、服务选择、归档这些偏好，也可以直接在宿主会话里让 agent 改，它会调用 `update_settings` 工具。
+setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数据目录>/research`，路径可改），或放在书签文件／文件夹旁边（放不了时退回统一目录）。只影响新的研究，已有任务留在原处。接着问研究结束后是否整理进 Wiki：给出建议并先问你（默认）、自动、关闭。
 
-## 插件包含什么
+研究深度、答复语言、服务选择、归档、结果位置、Wiki 整理这些偏好，也可以直接在宿主会话里让 agent 改，它会调用 `update_settings` 工具。
+
+## 数据保存在哪里
 
-### Skill
+不会写入你的书签文件或插件目录。数据目录为 `$BOOKMARK_RESEARCH_DATA_DIR`，未设置时为 `${XDG_DATA_HOME:-~/.local/share}/bookmark-research`。
 
-| Skill | 用途 |
+| 位置 | 内容 |
 | --- | --- |
-| [`bookmark-research`](skills/bookmark-research/SKILL.md) | 查书签、核对链接、对每条书签做完整研究并写出带引用的报告。英文执行版，另有[中文阅读版](skills/bookmark-research/references/zh/skill-guide.md)。 |
+| `research/`（或输入旁边的 `<输入名>.bookmark-research/`） | 每个研究任务一个文件夹：报告、来源、证据，以及存放 agent 中间文件的 `work/` |
+| `research-locations.json` | 所有任务文件夹的位置，改了位置设置后旧任务仍能列出 |
+| `knowledge/` | 保存的网页读取：`sources/` 按每次读取保存，`pages/` 中相同正文只存一份 |
+| `wiki/` | 审核后的知识页面与历史版本；`index.md` 目录、`log.md` 时间线 |
+| `index.sqlite3`、`index.sqlite3.sources/` | 书签检索索引，以及导入数据包的托管快照 |
+| `raw-library.sqlite3` | `search_archive` 使用的全文索引，可重建 |
+| `${XDG_CONFIG_HOME:-~/.config}/bookmark-research/` | `settings.json` 和 `credentials.json`（仅当前用户可读） |
+
+## Agent 循环与子代理
 
-### MCP 服务
+宿主模型负责规划、搜索／阅读、评估证据，再追查未解决的问题。Skill 指导这个循环，MCP 保存输入范围、证据、预算和进度；保存研究任务不会启动后台代理。
 
-一个本地 stdio 服务 `bookmark-research`（`python3 src/cli.py serve`），共 36 个工具：
+对于分组报告，插件提供“阅读代理 → 新的验证代理 → 覆盖检查 → 补查 → 报告”的流程。Codex 使用原生子代理和附带的委派指南；Claude Code、DSH 使用已加载的宿主工作流接口；Pi 需要加载相应的子代理／工作流扩展。并发、取消和代理生命周期由宿主管理。每个子代理都需要拿到相关指令，并访问同一个研究存储。
+
+工作流适配已有模拟接口测试，但安装成功不代表所有宿主都已跑通完整的多代理任务。所需条件见[宿主工作流](skills/bookmark-research/references/zh/host-workflows.md)，实际验证范围见[验证记录](docs/validation-0.4.0.md#host-and-provider-boundaries)。
+
+## 插件包含什么
+
+由 1 个 Skill、1 个本地 MCP 服务，以及这个服务内部连接的远程 MCP 和网页服务组成。宿主里只需要登记这 1 个本地 MCP。
+
+| 层 | 组成 | 运行方式 | 需要配置 |
+| --- | --- | --- | --- |
+| Skill | [`bookmark-research`](skills/bookmark-research/SKILL.md) 及 11 份方法参考，每份都有[中文版](skills/bookmark-research/references/zh/skill-guide.md) | 由宿主加载 | 不需要 |
+| 本地 MCP | `bookmark-research`，42 个工具（见下表；随能力增长） | 宿主启动的 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.9` npm 包中。已实现与剩余事项见[升级核对记录](docs/upgrade-status-2026-10-11.md)。
 
 | 分类 | 工具 |
 | --- | --- |
-| 书签 | `sync_package`、`index_status`、`source_history`、`search_bookmarks`、`get_context` |
-| 网页 | `search_web`、`fetch_web`、`search_providers` |
+| 书签 | `sync_package`、`index_status`、`source_history`、`source_remove`、`source_merge`、`search_bookmarks`、`get_context` |
+| 网页 | `search_web`、`fetch_web`、`search_archive`、`search_providers` |
 | 研究 | `research_readiness`、`research_start`、`research_status`、`research_search`、`research_fetch`、`research_source`、`research_record`、`research_inventory`、`research_coverage`、`research_import_evidence`、`research_finish`、`research_route` |
 | 专业研究服务（可选） | `research_services`、`research_service_prepare`、`_start`、`_status`、`_result`、`_cancel`、`_attach`、`_import` |
 | 设置 | `get_settings`、`update_settings` |
-| Wiki 与评测 | `wiki_write`、`wiki_get`、`wiki_list`、`wiki_search`、`wiki_lint`、`evaluate_research` |
-
-### 网页服务
-
-由插件自带的 MCP 服务直接调用，不需要另外添加它们的 MCP。
-
-| 服务 | 作用 |
-| --- | --- |
-| [Exa](https://exa.ai) | 主要搜索；首选网页读取 |
-| [Parallel](https://parallel.ai) | 主要搜索；备用网页读取 |
-| [Tavily](https://tavily.com) | 备用搜索 |
-| [Jina Reader](https://jina.ai/reader) | 备用网页读取；有 Key 时可搜索 |
-
-另有可选的研究 MCP 可以自己加到宿主里：Exa Agent、Parallel Task、Tavily Research。`bookmark-research setup` 会给出各宿主的接入步骤。
+| Wiki 与评测 | `wiki_write`、`wiki_get`、`wiki_list`、`wiki_search`、`wiki_refresh`、`wiki_work`、`wiki_lint`、`wiki_acknowledge`、`evaluate_research` |
 
 ## 更多
 
-- [安装说明](docs/installation.md)：全部安装方式、更新、ZIP 下载
+- [安装说明](docs/installation.md)：全部安装方式、npm 更新与源码开发
 - [使用指南](docs/user-guide.md)：首次使用、三种研究方式、语言
 - [详细说明](docs/details.md)：使用方式、数据包与保存位置、宿主与验证范围、开发
 - [结构与触发流程](docs/bookmark-research-architecture.md)

package/bundle.patch.yml

@@ -0,0 +1,18 @@
+# DeepSeek Harness bundle layer. Paths resolve from the installed package through
+# the module's context, so this file is identical in the npm package and in an
+# exported copy; `python` and the forwarded environment come from the module
+# (see hosts/dsh/plugin.js), not from this machine.
+- insert:
+    - id: bookmark-research-skill
+      name: bookmark-research
+    - id: bookmark-research-mcp
+      name: '@deepseek-ai/dsh-mcp-client'
+      inject: [bookmarkResearchPaths]
+      config:
+        serverName: bookmark-research
+        transport: stdio
+        command: !!js ctx.bookmarkResearchPaths.python.command
+        args: !!js ctx.bookmarkResearchPaths.mcpArgs
+        cwd: !!js ctx.bookmarkResearchPaths.root
+        env: !!js ctx.bookmarkResearchPaths.env
+        failOnStartupError: true

package/docs/bookmark-research-architecture.md

@@ -44,7 +44,7 @@ flowchart TB
 
   subgraph Plugin["Bookmark Research Plugin"]
     Skill["Skill：Markdown 指令<br/>查询方法、研究规则与宿主路由"]
-    MCP["本地 MCP 入口<br/>src/mcp_server.py · 35 个工具"]
+    MCP["本地 MCP 入口<br/>src/mcp_server.py · 工具随能力增长（本版 40 个）"]
     CLI["Python CLI 入口<br/>src/cli.py"]
     Core["共用 Python 运行时<br/>Python 3.9+ 标准库"]
     Sources["来源接入、增量同步与本地查询"]

package/docs/cli-launcher-plan.md

@@ -1,5 +1,7 @@
 # `bookmark-research` 命令与跨平台安装计划
 
+> 本文保留原始计划和阶段验收。当前统一采用 npm 分发；四宿主的最新安装检查和未完成范围见 [2026-10-11 升级核对](upgrade-status-2026-10-11.md)。
+
 日期：2026-09-24。目标：像 `claude`、`codex` 一样，在终端输入 `bookmark-research` 即可安装、配置、检查和更新插件；macOS、Linux、Windows 原生均可用。
 
 ## 决策
@@ -35,7 +37,7 @@ bookmark-research doctor          检查 Python 与 SQLite FTS5
 
 | 位置 | 问题 | 改法 |
 | --- | --- | --- |
-| `src/tui.py` | 用 `termios` 读按键 | Windows 用 `msvcrt.getwch()`，方向键前缀 `\xe0`/`\x00`；启用 VT 输��。无法读键时退回纯文本模式。 |
+| `src/tui.py` | 用 `termios` 读按键 | Windows 用 `msvcrt.getwch()`，方向键前缀 `\xe0`/`\x00`；启用 VT 输出。无法读键时退回纯文本模式。 |
 | `src/onboarding.py` | 从 `/dev/tty` 打开终端 | Windows 用 `CONIN$`/`CONOUT$`。 |
 | `scripts/host_install.py` | `fcntl` 安装锁 | Windows 用 `msvcrt.locking`（与 `src/settings.py` 相同做法）。 |
 | MCP 启动命令 | 写死 `python3` | 导出与安装时写入实际解析到的 Python（`python3` → `python` → `py -3`）；Codex 仓库清单保持 `python3`，Windows 上由安装器改写本地导出。 |
@@ -55,4 +57,4 @@ bookmark-research doctor          检查 Python 与 SQLite FTS5
 
 - 已实现：`bin/bookmark-research.js`、根目录 `package.json`（含 `bin` 与 `pi.skills`）、`scripts/launcher.py` 主菜单与子命令、Windows 按键／控制台／安装锁／Python 路径适配、`.github/workflows/test.yml` 三系统矩阵、README 与安装文档。
 - 已验证（macOS）：全量 450 个测试通过；`npm pack` 后全局安装的 `bookmark-research` 真实完成 Claude Code 安装、`status`、`verify`（36 个 MCP 工具）；主菜单在伪终端中可用。
-- 待验证：Windows 原生只由 CI 配置与模拟单元测试覆盖，需推送后看 CI；npm 包尚未发布；Codex 在 Windows 上仍使用仓库 manifest 中的 `python3` 启动 MCP，若系统没有 `python3` 命令需另行处理。
+- 已处理（0.5.0-beta.2）：Windows 上 Codex 改为登记固定了检测到的 Python 路径的副本，清单转发 `SystemRoot`／`windir`。仍待真机验证：Windows 上的四宿主实际安装、Pi。

package/docs/details.en.md

@@ -159,7 +159,9 @@ Run `python3 src/cli.py setup` to revisit the terminal wizard. Before each new w
 
 The default configuration file is `~/.config/bookmark-research/settings.json`, created on the first update. Page archives default to `~/.local/share/bookmark-research/knowledge/`; XDG and plugin data-directory environment variables are respected. You can choose your own absolute paths. These files live outside the plugin and canvas package, so plugin updates do not replace them.
 
-With archiving enabled, received fetch responses create a snapshot directory: `response.json` stores the actual MCP response; `manifest.json` records URLs, provider, fetch time, response and text hashes, and status; `pages/<URL-hash>.md` stores successfully recognized text. Transport failures without a response return a classified error and no `result` or invented archive. Publication dates and authors are recorded separately. Conflicting responses for the same URL are retained and marked. Excerpts and unknown completeness are identified, and archive errors are returned with the fetch result. Later reads add snapshots without overwriting earlier ones.
+Research task folders go to `~/.local/share/bookmark-research/research/` by default (`output.mode: central`, path changeable) or, with `beside_input`, next to a single bookmark file or folder as `<name>.bookmark-research/`; URL lists, several sources, Git repositories, canvas packages and unwritable locations fall back to the central folder with a stated reason. Changes apply to new tasks only; `research-locations.json` keeps every task listed. `wiki.after_research` (`suggest` by default, `auto`, `off`) decides whether finished research proposes or writes Wiki updates. Each Wiki write also refreshes `wiki/index.md` and appends `wiki/log.md`.
+
+With archiving enabled, received fetch responses create a snapshot directory: `response.json` stores the actual MCP response; `manifest.json` records URLs, provider, fetch time, response and text hashes, and status; successfully recognized text is stored once per distinct body in the archive's `pages/<SHA-256>.md`. `search_archive` searches that text and all research evidence without network access. Transport failures without a response return a classified error and no `result` or invented archive. Publication dates and authors are recorded separately. Conflicting responses for the same URL are retained and marked. Excerpts and unknown completeness are identified, and archive errors are returned with the fetch result. Later reads add snapshots without overwriting earlier ones.
 
 ```sh
 python3 src/cli.py config show
@@ -180,11 +182,13 @@ The [shared Skill](../skills/bookmark-research/SKILL.md) guides the agent's work
 | `index_status` | Inspect registered sources and index status |
 | `sync_package` | Import a package or synchronize changes |
 | `source_history` | List reusable source snapshots and recovery paths |
+| `source_remove` / `source_merge` | Preview or confirm removal and merging of registered sources |
 | `search_bookmarks` | Query bookmarks for multiple targets while retaining item context |
 | `get_context` | Read section, card, group, connection, and item-ancestor context |
 | `search_providers` | List configured web providers |
 | `search_web` | Search through Exa / Parallel / Tavily / keyed Jina and merge results per target |
 | `fetch_web` | Read known URLs and optionally archive responses and page text |
+| `search_archive` | Literal full-text search over saved page text in the knowledge archive and all research evidence, merged by content hash |
 | `get_settings` | Read current settings and storage paths |
 | `update_settings` | Update persistent settings |
 | `research_readiness` | Check credentials, selected services and observed host tools; return setup/login guidance |
@@ -199,7 +203,9 @@ The [shared Skill](../skills/bookmark-research/SKILL.md) guides the agent's work
 | `research_import_evidence` | Import actual host-read original text or explicitly secondary reports with provenance |
 | `research_route` | Recommend a route using current host observations and saved preferences |
 | `research_services` / `research_service_*` | Describe, prepare, start, observe, read, cancel, attach and import optional professional runs |
-| `wiki_write` / `wiki_get` / `wiki_list` / `wiki_search` / `wiki_lint` | Maintain reviewed knowledge and immutable evidence-linked revisions |
+| `wiki_write` / `wiki_get` / `wiki_list` / `wiki_search` / `wiki_lint` / `wiki_acknowledge` | Maintain reviewed knowledge, immutable evidence-linked revisions and input review acknowledgements |
+| `wiki_refresh` | Fetch cited URLs, record source observations and identify pages that need review |
+| `wiki_work` | Resume compilation and review using saved work states and committed publication receipts |
 | `evaluate_research` | Compute metrics from explicit tasks, outputs, measurements and reviewer labels |
 
 ### Web providers
@@ -261,8 +267,8 @@ From this plugin directory **in a full repository checkout**, developers can run
 python3 -m unittest discover -s tests -v
 python3 scripts/verify_fixture.py --output /tmp/bookmark-research-verification
 python3 scripts/verify_quality.py
-python3 scripts/build_zip.py --output dist/bookmark-research-0.5.0-beta.1.zip
-python3 scripts/build_zip.py --include-tests --output dist/bookmark-research-test-pack-0.5.0-beta.1.zip
+python3 scripts/build_zip.py --output dist/bookmark-research-0.5.0-beta.3.zip
+python3 scripts/build_zip.py --include-tests --output dist/bookmark-research-test-pack-0.5.0-beta.3.zip
 ```
 
 The fixture verifier checks independent bookmark counts, copy-card semantics, scoped queries, unchanged source hashes, incremental sync, and a two-round research lifecycle with a failed page and resumed operation. To additionally validate your own package, append `--package /absolute/path/to/package`; this stays offline and writes derived files only to the new output directory.

package/docs/details.md

@@ -51,11 +51,13 @@ JSON／`.canvas` 是源数据，SQLite 是可重建的本地查询索引，无
 
 - `index.sqlite3`：来源登记、书签和画布关系索引。
 - `index.sqlite3.sources/`：原始协议文件和关系清单的版本快照。
-- `knowledge/`：普通网页响应、正文和来源记录。
-- `research/`：完整输入清单、任务、证据、覆盖与报告。
-- `wiki/`：主题／实体页和不可变修订。
+- `knowledge/`：普通网页响应、正文（`pages/` 中相同正文只存一份）和来源记录。
+- `research/`：完整输入清单、任务、证据、覆盖与报告；每个任务的 `work/` 存放 agent 中间文件。设置 `output.mode: beside_input` 时，新任务放在单个书签文件／文件夹旁边的 `<名称>.bookmark-research/`，URL 列表、多个来源、Git 仓库、画布包或没有写权限时退回统一目录并说明原因。改设置只影响新任务。
+- `research-locations.json`：所有任务文件夹的位置登记。
+- `wiki/`：主题／实体页和不可变修订；每次写入更新 `index.md`（目录）并追加 `log.md`（时间线）。
+- `raw-library.sqlite3`：`search_archive` 的全文索引，覆盖 `knowledge/` 与所有研究证据，可重建。
 
-配置默认为 `~/.config/bookmark-research/settings.json`。支持 XDG 和显式路径覆盖，多宿主可共享数据。索引更新不会自动抓网页、运行 LLM 或改写 Wiki；来源变化时提示复核，旧研究与证据保留。
+配置默认为 `~/.config/bookmark-research/settings.json`。`wiki.after_research` 决定研究结束后的 Wiki 整理：`suggest`（默认，先建议再问）、`auto`、`off`。支持 XDG 和显式路径覆盖，多宿主可共享数据。索引更新不会自动抓网页、运行 LLM 或改写 Wiki；来源变化时提示复核，旧研究与证据保留。
 
 `research_record` 支持单条 `entry` 或每批至多 50 条的 `entries`，按顺序校验后一次保存，返回精简编号；稳定的 `batch_id` 可避免重试产生重复记录。依赖新 claim ID 的记录在读取返回值后另批提交。`resume` 和 `external_run` 仍需单条调用，详见 [证据记录](../skills/bookmark-research/references/zh/deep-research.md)。
 

package/docs/diff-review-2026-10-09.md

@@ -0,0 +1,38 @@
+# Diff 审查与修正记录（2026-10-09）
+
+> 本文的问题已由后续修正及 beta.8 覆盖；当前工作树和未完成升级项见 [2026-10-11 升级核对](upgrade-status-2026-10-11.md)。原始版本与验收结果保留。
+
+本轮审查从 `a4b7630` 之后的工作树 diff 出发，通过 CodeGraph 定位实现与调用链，交叉检查 DSH 分发、检索、研究并发和 Wiki 证据生命周期。原始改动已单独保存为 `264d910`；其发布文件与 npm `0.5.0-beta.7` 的 120 个文件逐字节一致。
+
+DSH 修复的方向正确：发布包具有入口与 `dsh.bundle.patch` 声明，路径从安装位置解析，ESM 范围限制在 DSH 目录，环境变量按明确列表转发。用户已确认当前 DSH 跑通，旧评估报告中的失效状态属于历史记录。本轮没有重新安装或修改用户的 DSH profile。
+
+原始 diff 的 561 项测试通过，但交叉审查发现了并发和兼容边界，特别是来源数据保护与证据复核。以下问题均有隔离复现，并已在后续源码提交中修正。
+
+| 优先级 | 原始 diff 的问题 | 本轮修正 |
+| --- | --- | --- |
+| P1 | 研究取消或生成 incomplete 报告后，慢请求仍提交结果，导致最终报告与状态文件不一致；取消后还可能追加 fallback 请求。 | 提交与 fallback 预算预留都重新检查研究为 active、操作为 pending。已关闭或确认中断的操作拒绝迟到结果。 |
+| P1 | merge 在事务外判断版本相同，同步可在检查后写入独有内容，再被 merge 删除。两个未版本化的 legacy 来源也会因 `None == None` 被误合并。 | 在写事务内重新读取并校验双方有效内容版本；legacy 来源须先同步。 |
+| P1 | remove/merge 提交数据库后删除原目录，可能删掉另一连接刚以相同 source ID 重新导入的快照。 | 提交前将旧快照改名为唯一隔离目录，提交后只清理该目录；异常回滚恢复旧版本且不覆盖并发新版本。 |
+| P1 | 已发布证据的响应制品被修改后，`wiki acknowledge` 可重新计算 hash，把 `invalid_evidence` 清成 current。 | 持研究锁校验上一修订的证据与链接；存在 error 时拒绝复核，保留原校验基线。 |
+| P2 | 并发导入最终分配的 source ID 与提前写出的 manifest ID 不一致。 | 在提交锁内分配最终 ID 后生成 manifest，回放保留该 ID。 |
+| P2 | 删除引用来源后，freshness 为 unknown，但 Wiki 仍显示 current。 | 不可解析的来源产生 `source_input_unavailable`，页面进入 needs_review。 |
+| P2 | 旧版 DSH 包缺少新增的嵌套 `package.json`，无法进入承诺的旧包导出兼容分支。 | 仅在文件缺失时生成 ESM manifest；符号链接和错误文件类型仍拒绝。 |
+| P2 | Codex、Claude、Agent Plugins 导出没有根 `package.json`，握手版本退成 `0+unknown`。 | 读取各分发格式自己的 manifest；存在但损坏的优先 manifest 不被其他文件掩盖。 |
+| P2 | 含 `%`、`_`、反斜杠的画布线索在 SQL 命中后又被丢弃。 | SQL 保留转义，结果归属使用原始查询文本。 |
+| P2 | doctor 泄漏探测文件描述符、可能删除预存同名文件，并把普通文件阻断的目录路径报为可写。 | 使用自动关闭的随机临时文件；遇到非目录路径组件立即报告不可写。 |
+
+DSH 的重装提示也已改为明确指定 profile 和版本的原生命令，避免默认 `latest` 指向旧发布。Wiki 复核记录保存本次提交的说明。
+
+修正快照清理后，第二轮交叉复核发现了“目录改名后、数据库提交前强制终止进程”的恢复窗口。已补启动恢复：在写事务内，根据数据库仍引用的版本及 manifest/hash 校验恢复目录，保留已有新版本，不复活已删除来源。真实子进程强制退出及后续 partial 导入均纳入验证。
+
+验证结果：
+
+- 最终本地全量测试：**587 项，0 失败，3 项按条件跳过**，Python 3.9.6 / SQLite 3.43.2。跳过项为原生 Pi/DSH 安装、显式启用的 Codex/npm 集成和全宿主 npm 下载测试；不将其计作本轮宿主安装通过。
+- 独立下载真实 npm beta.5，使用当前导出器生成 DSH 包，删除源副本并搬到含中文、空格和引号的路径后，Skill 和实际 MCP 调用通过。
+- 当前五种导出同样在删除源副本、搬迁后完成真实 MCP initialize，全部报告 beta.7；DSH 解释器、参数和环境转发契约通过。
+- 用户画布样例验收：638 个书签实例、557 个唯一 URL、122 个文件夹、5 个栏目；完整库存分页保留全部 ID，二次同步识别未修改内容，原文件 hash 未变。测试未调用网络研究服务。
+- 合成研究验收正确阻止未读完来源时宣称研究完成。已发布 npm 包的 CLI help、doctor、status 冒烟通过。
+
+实现仍有明确边界：取消后已经返回的响应可能留下未引用制品，但不能再进入已结束研究的状态或报告。启动恢复只处理数据库仍引用且校验通过的快照；未引用的 `.removed-*` 残留保守保留，不自动回收。普通异常回滚、并发重新导入、回滚后出现新版本，以及提交前/后强制退出均有回归覆盖。
+
+这些审查修正属于 `264d910` 之后的源码提交，**不包含在已经发布的 npm beta.7 中**。本轮只提交并推送 Git，没有重新发布 npm，也没有移动 dist-tag。复现所用本机报告、索引和私人样例未纳入提交。