bookmark-research 0.5.0-beta.1

package/README.md

@@ -0,0 +1,128 @@
+# Bookmark Research
+
+**English** · [中文](README.zh.md)
+
+Research your bookmarks with verified web sources. Give it a list of bookmark URLs or a [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) package; it checks every link, searches and reads the web, and writes a cited report you can resume.
+
+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)
+
+> [!NOTE]
+> **0.5.0 is a beta.** Report problems on [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues).
+
+## 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
+- No API key is needed to install or to query bookmarks locally
+
+## Install
+
+**Interactive** (macOS, Linux, Windows):
+
+```sh
+npx bookmark-research 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`.
+
+**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` |
+
+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).
+
+**Ask your agent to install it.** Paste this into Codex, Claude Code, Pi 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 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.
+5. Tell me to start a new session so the Skill and MCP tools load.
+```
+
+## Configure and API keys
+
+No reinstall is needed. Settings and keys apply to every installed client; start a new client session after changing them.
+
+| Task | Command |
+| --- | --- |
+| Menu: configure, check, install, update | `bookmark-research` |
+| Preferences and API keys | `bookmark-research setup` |
+| Installed clients, preferences, 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.
+
+**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.
+
+| Variable | Service | Without it |
+| --- | --- | --- |
+| `EXA_API_KEY` | Exa search and page reading | Anonymous use where Exa allows it |
+| `PARALLEL_API_KEY` | Parallel search and page reading | Free anonymous use with lower limits |
+| `TAVILY_API_KEY` | Tavily search fallback and extraction | Keyless mode |
+| `JINA_API_KEY` | Jina search | Jina Reader still reads pages anonymously |
+| `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.
+
+## What's inside
+
+### Skill
+
+| Skill | Use it for |
+| --- | --- |
+| [`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). |
+
+### MCP server
+
+One local stdio server, `bookmark-research` (`python3 src/cli.py serve`), with 36 tools:
+
+| Group | Tools |
+| --- | --- |
+| Bookmarks | `sync_package`, `index_status`, `source_history`, `search_bookmarks`, `get_context` |
+| Web | `search_web`, `fetch_web`, `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` |
+
+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
+- [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)
+
+Originally developed in [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas). License: [GPL-3.0](LICENSE).

package/README.zh.md

@@ -0,0 +1,126 @@
+# Bookmark Research
+
+[English](README.md) · **中文**
+
+用联网查证来研究你的书签。给它一份书签 URL 列表或 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas) 数据包，它会逐条核对链接、搜索和阅读网页，写出带引用、可以接着做的研究报告。
+
+支持 **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)
+
+> [!NOTE]
+> **0.5.0 是测试版。** 遇到问题请到 [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues) 反馈。
+
+## 环境要求
+
+- Python 3.9+，含 SQLite FTS5（可用 `bookmark-research doctor` 检查）
+- 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH（DSH 另需 `pnpm`）
+- `bookmark-research` 命令需要 Node 18+；macOS/Linux 上可不用
+- 安装和本地查书签都不需要 API Key
+
+## 安装
+
+**交互安装**（macOS、Linux、Windows）：
+
+```sh
+npx bookmark-research 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`。
+
+**指定宿主、不弹提示：**
+
+| 宿主 | 命令 | 实际登记方式 |
+| --- | --- | --- |
+| 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` |
+
+一次装多个：`npx bookmark-research 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：
+
+```text
+请把 Bookmark Research 插件安装到你当前运行的这个宿主里。
+
+1. 先确认你自己是哪个宿主：codex、claude、pi 或 dsh。
+2. 运行：npx bookmark-research 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`）自己输入。
+5. 提醒我新建一个会话，让 Skill 和 MCP 工具生效。
+```
+
+## 配置与 API Key
+
+不需要重新安装。配置和 Key 对所有已安装的宿主生效，修改后新建宿主会话即可。
+
+| 要做什么 | 命令 |
+| --- | --- |
+| 主菜单：配置、检查、安装、更新 | `bookmark-research` |
+| 修改偏好和 API Key | `bookmark-research setup` |
+| 查看已装宿主、偏好、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`。
+
+**API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。Key 不接受对话、命令参数或 JSON 文件。
+
+| 环境变量 | 服务 | 不配置时 |
+| --- | --- | --- |
+| `EXA_API_KEY` | Exa 搜索与网页读取 | 在 Exa 允许的范围内匿名使用 |
+| `PARALLEL_API_KEY` | Parallel 搜索与网页读取 | 免费匿名使用，额度较低 |
+| `TAVILY_API_KEY` | Tavily 备用搜索与提取 | 使用免 Key 模式 |
+| `JINA_API_KEY` | Jina 搜索 | Jina Reader 仍可匿名读取网页 |
+| `OPENAI_API_KEY` | 可选的 OpenAI Deep Research 任务 | 功能关闭；宿主自己的研究不受影响 |
+
+研究深度、答复语言、服务选择、归档这些偏好，也可以直接在宿主会话里让 agent 改，它会调用 `update_settings` 工具。
+
+## 插件包含什么
+
+### Skill
+
+| Skill | 用途 |
+| --- | --- |
+| [`bookmark-research`](skills/bookmark-research/SKILL.md) | 查书签、核对链接、对每条书签做完整研究并写出带引用的报告。英文执行版，另有[中文阅读版](skills/bookmark-research/references/zh/skill-guide.md)。 |
+
+### MCP 服务
+
+一个本地 stdio 服务 `bookmark-research`（`python3 src/cli.py serve`），共 36 个工具：
+
+| 分类 | 工具 |
+| --- | --- |
+| 书签 | `sync_package`、`index_status`、`source_history`、`search_bookmarks`、`get_context` |
+| 网页 | `search_web`、`fetch_web`、`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` 会给出各宿主的接入步骤。
+
+## 更多
+
+- [安装说明](docs/installation.md)：全部安装方式、更新、ZIP 下载
+- [使用指南](docs/user-guide.md)：首次使用、三种研究方式、语言
+- [详细说明](docs/details.md)：使用方式、数据包与保存位置、宿主与验证范围、开发
+- [结构与触发流程](docs/bookmark-research-architecture.md)
+
+项目源自 [Bookmark Canvas](https://github.com/Browser-bookmark-hub/Bookmark-Canvas)。许可证：[GPL-3.0](LICENSE)。

package/bin/bookmark-research.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Thin cross-platform entry: find Python 3.9+ and run the bundled launcher.
+"use strict";
+const { spawnSync, spawn } = require("child_process");
+const path = require("path");
+
+const launcher = path.join(__dirname, "..", "scripts", "launcher.py");
+const candidates = [];
+if (process.env.BOOKMARK_RESEARCH_PYTHON) candidates.push([process.env.BOOKMARK_RESEARCH_PYTHON]);
+candidates.push(["python3"], ["python"]);
+if (process.platform === "win32") candidates.push(["py", "-3"]);
+
+const check = "import sys, sqlite3; sys.exit(0 if sys.version_info >= (3, 9) else 3)";
+const python = candidates.find(([command, ...args]) =>
+  spawnSync(command, [...args, "-c", check], { stdio: "ignore", windowsHide: true }).status === 0);
+
+if (!python) {
+  const chinese = /^zh/i.test(process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || "");
+  console.error(chinese
+    ? "Bookmark Research 需要 Python 3.9+（含 SQLite）。请从 https://www.python.org/downloads/ 安装，或设置 BOOKMARK_RESEARCH_PYTHON 指向 Python。"
+    : "Bookmark Research needs Python 3.9+ with SQLite. Install it from https://www.python.org/downloads/ or set BOOKMARK_RESEARCH_PYTHON.");
+  process.exit(1);
+}
+
+const [command, ...prefix] = python;
+const child = spawn(command, [...prefix, launcher, ...process.argv.slice(2)], { stdio: "inherit", windowsHide: true });
+// The terminal delivers Ctrl+C to the whole process group; let Python handle it.
+process.on("SIGINT", () => {});
+child.on("exit", (code, signal) => process.exit(signal ? 130 : code ?? 1));
+child.on("error", (error) => { console.error(error.message); process.exit(1); });

package/config/providers.json

@@ -0,0 +1,98 @@
+{
+  "schema_version": 1,
+  "providers": {
+    "exa": {
+      "label": "Exa",
+      "url": "https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa",
+      "search_tools": [
+        "web_search_exa"
+      ],
+      "fetch_tools": [
+        "web_fetch_exa"
+      ],
+      "direct_client": true,
+      "optional_header_env": {
+        "x-api-key": "EXA_API_KEY"
+      },
+      "authentication": "Anonymous rate-limited search/extraction, or optional EXA_API_KEY header. This plugin does not implement OAuth.",
+      "native_research": {
+        "url": "https://mcp.exa.ai/mcp?tools=agent_run",
+        "tools": ["agent_run"],
+        "required_tools": ["agent_run"],
+        "workflow_tools": ["agent_run"],
+        "authentication_required": true,
+        "mode": "host_native_mcp",
+        "note": "Opt-in Exa Agent; resumable with runId. Not part of the default search/extraction catalog."
+      },
+      "docs": "https://exa.ai/docs/reference/exa-mcp"
+    },
+    "parallel": {
+      "label": "Parallel",
+      "url": "https://search.parallel.ai/mcp",
+      "search_tools": [
+        "web_search"
+      ],
+      "fetch_tools": [
+        "web_fetch"
+      ],
+      "direct_client": true,
+      "optional_bearer_env": "PARALLEL_API_KEY",
+      "authentication": "Anonymous rate-limited search/extraction, or optional PARALLEL_API_KEY Bearer header. OAuth endpoint is host-managed.",
+      "native_research": {
+        "url": "https://task-mcp.parallel.ai/mcp",
+        "tools": ["createDeepResearch", "createTaskGroup", "getStatus", "getResultMarkdown"],
+        "required_tools": ["createDeepResearch", "getStatus", "getResultMarkdown"],
+        "workflow_tools": ["createDeepResearch", "getStatus", "getResultMarkdown"],
+        "authentication_required": true,
+        "mode": "host_native_mcp",
+        "docs": "https://docs.parallel.ai/integrations/mcp/task-mcp",
+        "note": "A separate authenticated asynchronous Task MCP; Search MCP capability probes do not contact it."
+      },
+      "docs": "https://docs.parallel.ai/integrations/mcp/search-mcp"
+    },
+    "jina": {
+      "label": "Jina Reader / Search",
+      "url": "https://r.jina.ai/",
+      "search_url": "https://s.jina.ai/",
+      "transport": "http",
+      "search_tools": ["jina_search"],
+      "fetch_tools": ["jina_reader"],
+      "direct_client": true,
+      "optional_bearer_env": "JINA_API_KEY",
+      "required_env": {"search": "JINA_API_KEY"},
+      "authentication": "Reader supports anonymous rate-limited webpage/PDF extraction. Search requires JINA_API_KEY. Uses the HTTP APIs, not the hosted Jina MCP, whose anonymous reading is not established.",
+      "docs": "https://jina.ai/reader/"
+    },
+    "tavily": {
+      "label": "Tavily",
+      "url": "https://mcp.tavily.com/mcp/",
+      "search_tools": [
+        "tavily_search",
+        "tavily-search"
+      ],
+      "fetch_tools": [
+        "tavily_extract",
+        "tavily-extract"
+      ],
+      "direct_client": true,
+      "optional_bearer_env": "TAVILY_API_KEY",
+      "keyless_headers": {
+        "X-Tavily-Access-Mode": "keyless"
+      },
+      "authentication": "Optional TAVILY_API_KEY Bearer header; otherwise explicitly selects keyless search/extraction. OAuth is host-managed.",
+      "keyless_docs": "https://docs.tavily.com/documentation/keyless",
+      "native_research": {
+        "url": "https://mcp.tavily.com/mcp/",
+        "tools": ["tavily_research", "tavily-research"],
+        "authentication_required": true,
+        "mode": "host_native_mcp",
+        "note": "May be advertised to keyless clients but requires an API key to execute. The aggregator routes search and extraction only."
+      },
+      "docs": "https://docs.tavily.com/documentation/mcp"
+    }
+  },
+  "default_providers": [
+    "exa",
+    "parallel"
+  ]
+}

package/docs/bookmark-research-architecture.md

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

package/docs/cli-launcher-plan.md

@@ -0,0 +1,58 @@
+# `bookmark-research` 命令与跨平台安装计划
+
+日期：2026-09-24。目标：像 `claude`、`codex` 一样，在终端输入 `bookmark-research` 即可安装、配置、检查和更新插件；macOS、Linux、Windows 原生均可用。
+
+## 决策
+
+| 问题 | 决定 | 理由 |
+| --- | --- | --- |
+| 分发途径 | **npm 为主入口，GitHub 为源码与备选入口** | npm 在三个系统上自动生成可执行命令；Pi、DSH、Codex 用户基本已有 Node。`curl \| bash` 保留给不想用 Node 的 macOS/Linux 用户。 |
+| 包名 | `bookmark-research`（2026-09-24 查询 npm 未被占用） | 与插件名一致。 |
+| 运行时 | npm 包只是薄入口，调用包内 Python（3.9+，含 FTS5） | 不重写已测试的 Python 安装器与 MCP。 |
+| 发布前 | `npx github:Browser-bookmark-hub/Bookmark-Research` 可直接从 GitHub 运行 | 不依赖 npm 账号即可试用。 |
+
+## 命令设计
+
+```
+bookmark-research                 终端中打开主菜单；非终端输出 JSON 状态
+bookmark-research install [HOST…] 安装到一个或多个宿主（无参数时进入向导）
+bookmark-research update [HOST…]  更新已安装宿主（默认全部）
+bookmark-research verify [HOST…]  验证已安装宿主
+bookmark-research setup           配置向导（偏好、服务、隐藏输入 Key、可用性检查）
+bookmark-research status          已安装宿主、服务与 Key 状态（JSON）
+bookmark-research config show|set 查看或修改偏好（set 从 --input 读取 JSON）
+bookmark-research doctor          检查 Python 与 SQLite FTS5
+```
+
+规则：
+
+1. 命令不绑定版本号。所有操作都用 npm 包自带（或 checkout 中）的 Python 源码；配置与 Key 属于用户级数据，与宿主安装分离。
+2. 已安装宿主从安装记录读取：Codex 读 `codex plugin list`，其他宿主读 `~/.local/share/bookmark-research/installations/*/receipt.json`。
+3. 非终端（agent/CI）不弹菜单；需要的参数必须显式传入，输出 JSON。
+4. API Key 仍只允许隐藏输入或环境变量，不接受命令参数与 JSON。
+
+## Windows 原生适配
+
+| 位置 | 问题 | 改法 |
+| --- | --- | --- |
+| `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 上由安装器改写本地导出。 |
+| 入口 | bash 脚本 | npm `bin` 为 Node 脚本，查找 Python 后转发参数。 |
+
+## 实施与验收
+
+1. `bin/bookmark-research.js`（Node）+ 根目录 `package.json` 的 `bin`/`files`；查找 Python，版本不足时给出安装说明。
+2. `scripts/launcher.py`：子命令分派与主菜单，复用 `install.py`、`cli.py`。
+3. Windows 适配（上表）。
+4. 测试：launcher 分派、Python 探测、非终端行为；跨平台逻辑单元测试；GitHub Actions 矩阵（ubuntu / macos / windows）。本机只能验证 macOS。
+5. README：安装、后续配置、插件包含的 MCP 与 Skill。
+
+完成标准：本机全量测试通过；`npm pack` 后用 `npx ./bookmark-research-*.tgz` 在隔离目录跑通 `status`、`install --dry-run`；Windows 仅以 CI 配置和单元测试覆盖，真实 Windows 验证待 CI 运行。
+
+## 完成情况（2026-09-24）
+
+- 已实现：`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` 命令需另行处理。