bookmark-research 0.5.0-beta.8 → 0.6.0

package/docs/bookmark-research-architecture.md

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

package/docs/details.en.md

@@ -10,13 +10,13 @@ Reference material moved from the README: components, data model, research modes
 | --- | --- | --- |
 | **Skill** | [`skills/bookmark-research/SKILL.md`](../skills/bookmark-research/SKILL.md) | Guides package reading, local queries, source verification, and research reports |
 | **MCP server** | [`src/mcp_server.py`](../src/mcp_server.py), started with `python3 src/cli.py serve` | One local `bookmark-research` server with the [shared tool catalog](#mcp-tools) |
-| **Python CLI** | [`src/cli.py`](../src/cli.py) | Runs the same queries and research workflows directly, including from Pi |
-| **Web providers** | [`config/providers.json`](../config/providers.json), [`src/provider_adapters.py`](../src/provider_adapters.py), [`src/jina.py`](../src/jina.py) | Exa, Parallel, Jina HTTP and Tavily behind one MCP; schema checks, session reuse and visible partial failures |
+| **Python CLI** | [`src/cli.py`](../src/cli.py) | Runs the same queries and research workflows directly, including from a host without MCP |
+| **Web providers** | [`config/providers.json`](../config/providers.json), [`src/provider_adapters.py`](../src/provider_adapters.py), [`src/jina.py`](../src/jina.py) | Exa, Parallel, Jina HTTP, DeepSeek Search/Fetch and Tavily behind one MCP; schema checks, session reuse and visible partial failures |
 | **Research and coverage** | [`src/research.py`](../src/research.py), [`src/research_coverage.py`](../src/research_coverage.py) | Complete source inventory, all bookmark instances, budgets, evidence, substantive review and reports |
-| **Host workflows** | [`hosts/`](../hosts/) and [`src/routing.py`](../src/routing.py) | Native Codex delegation, Claude workflow, Pi extension recipe and DSH workflow adapter |
+| **Host workflows** | [`hosts/`](../hosts/) and [`src/routing.py`](../src/routing.py) | Native Codex delegation, Claude workflow and DSH workflow adapter |
 | **Professional research** | [`src/research_services.py`](../src/research_services.py) | Optional provider-owned background tasks, saved run IDs and secondary-report import |
-| **Wiki and evaluation** | [`src/wiki.py`](../src/wiki.py), [`src/evaluation.py`](../src/evaluation.py) | Reviewed knowledge, immutable revisions, source/link lint and metrics from explicit labels |
-| **Client integrations** | Native manifests, [`bin/bookmark-research.js`](../bin/bookmark-research.js), [`scripts/launcher.py`](../scripts/launcher.py), [`install.sh`](../install.sh), [`scripts/install.py`](../scripts/install.py) and [`scripts/export_bundle.py`](../scripts/export_bundle.py) | The `bookmark-research` command, guided installation and native install/update/verify for all four hosts |
+| **Wiki** | [`src/wiki.py`](../src/wiki.py) | Reviewed knowledge, immutable revisions, source/link lint and freshness checks |
+| **Client integrations** | Native manifests, [`bin/bookmark-research.js`](../bin/bookmark-research.js), [`scripts/launcher.py`](../scripts/launcher.py), [`install.sh`](../install.sh), [`scripts/install.py`](../scripts/install.py) and [`scripts/export_bundle.py`](../scripts/export_bundle.py) | The `bookmark-research` command (alias `bookmark`, or `bookmark research`), guided installation and native install/update/verify for all three hosts |
 
 The runtime requires Python 3.9+ and SQLite with FTS5; `doctor` checks these requirements. It uses the Python standard library and does not require a separate database service.
 
@@ -26,12 +26,9 @@ The runtime requires Python 3.9+ and SQLite with FTS5; `doctor` checks these req
 | --- | --- | --- | --- | --- |
 | **Codex** | Included | MCP | Native plugin and marketplace | Native install/update and stdio checks in isolated profiles |
 | **Claude Code** | Included | MCP | Persistent marketplace/plugin plus Dynamic Workflow | Native install/update/cache checks in isolated profiles; model execution is separate |
-| **Pi** | Included through `pi.skills` | CLI / stdio bridge | Persistent package plus project workflow registrar | Installer/adapter scenarios; subagent workflows require optional extensions |
 | **DSH / DeepSeek Harness** | Included through Skill provider | MCP through the official client | Relocatable `dsh.bundle` plus optional workflow adapter | Installer/adapter scenarios; workflows require a configured service, engine and tool |
 
-Install verification does not mean all four live clients completed a research task. Pi's basic Skill + CLI works without subagent extensions. DSH's bundle registers the Skill and resolves the bundled Python path after installation; its legacy `cordis.patch.yml` export remains specific to its original location. See [host workflows](../skills/bookmark-research/references/host-workflows.md) for optional collaboration and actual resume limits.
-
-**Agent Plugins 1.0.0** is also available as a separate standard export: root `plugin.json` + `mcp.json`. It is a package format, not another client or the Codex native manifest. See [export formats](#export-formats) for commands and the [compatibility notes (Chinese)](harness-compatibility.md) for first-party references and verification boundaries.
+Install verification does not mean all three live clients completed a research task. DSH's bundle registers the Skill and resolves the bundled Python path after installation; its legacy `cordis.patch.yml` export remains specific to its original location. See [host workflows](../skills/bookmark-research/references/host-workflows.md) for optional collaboration and actual resume limits.
 
 ## Data and query model
 
@@ -117,17 +114,17 @@ This version has no embeddings, vector database or background page monitoring. R
 | --- | --- | --- |
 | Quick lookup | Read a known URL, or search once to discover it | A concise sourced answer |
 | Agentic search | The current host model first plans, searches/reads, judges evidence and follows gaps | A sourced answer; ordinary questions need no full research session |
-| Deep research | Extend the host loop with sustained investigation, optional native collaboration, independent review and coverage checks | A persistent research archive with original inventory, evidence, coverage, report and optional Wiki |
+| Deep research | Submit the question to a research API, observe the job and review the report | A sourced report; persistent inventories and coverage audits are optional |
 
 These modes follow [OpenAI's web search guide](https://developers.openai.com/api/docs/guides/tools-web-search). Having a URL does not determine whether a model reasons. `research_route` recommends an entrypoint from reported current tools and commands without launching it. Professional APIs have separate authentication and lifecycle contracts; anonymous Search MCP access does not authorize a Task API.
 
-One MCP entry point aggregates several backend services, and one Skill executes all three workflows. Reading defaults to Exa followed by concurrent Parallel + Jina Reader fallback for unresolved URLs; Tavily extraction can be added to `fetch.providers`. Search starts with Exa + Parallel, then calls `search.fallback_providers` (Tavily + keyed Jina) concurrently only for queries with no usable URL. Missing fallback credentials are skipped; successful results stay intact. Set the search fallback list to `[]` to disable it. An existing saved search provider list without a fallback field retains its original service scope.
+One MCP entry point aggregates several backend services, and one Skill executes all three workflows. Reading starts with Exa under `fetch.strategy` (staggered by default: the next provider joins once the current one stalls past `fetch.grace_seconds`; hedged and sequential are the alternatives; abandoned providers are listed in `abandoned_providers`), then concurrent Parallel + Jina Reader fallback for unresolved URLs; Tavily extraction can be added to `fetch.providers`. `fetch.reuse_seconds` can return text saved within that window as `reused_sources` without a new request, and `search.cache_seconds` serves a repeated identical search from a short-lived cache. Search starts with Exa + Parallel under `search.strategy` (hedged by default, with staggered, sequential and wait_all alternatives) and the `search.grace_seconds` / `search.deadline_seconds` bounds; dropped or uncalled providers are listed in `routing`. Then `search.fallback_providers` (Tavily + keyed Jina) run concurrently only for queries with no usable URL. Missing fallback credentials are skipped; successful results stay intact. Set the search fallback list to `[]` to disable it. An existing saved search provider list without a fallback field retains its original service scope.
 
-The host model leads both research modes. Codex native subagents, Claude ordinary subagents or enabled teams, Pi extensions, and configured DSH subagents/workflows supply collaboration; see [host capabilities](harness-compatibility.md). The grouped package scripts are optional for batch research. Exa `agent_run`, complete Parallel Task MCP tools and enabled OpenAI/Parallel APIs can handle scoped external work after host assessment. A saved API preference orders these optional services; an explicit provider selects it exclusively. On confirmed failure, use cumulative `failed_routes` to continue the same investigation, preserving running/unknown/cancelled jobs. API execution follows prepare → start → status → result → import and requires separate credentials. Scrapling, Firecrawl and MarkItDown remain researched projects. A public GitHub README fetch does not inspect the whole repository.
+The host model leads both research modes. Codex native subagents, Claude ordinary subagents or enabled teams, and configured DSH subagents/workflows supply collaboration; see [host capabilities](harness-compatibility.md). The grouped package scripts are optional for batch research. Exa `agent_run`, complete Parallel Task MCP tools and enabled OpenAI/Parallel APIs can handle scoped external work after host assessment. A saved API preference orders these optional services; an explicit provider selects it exclusively. On confirmed failure, use cumulative `failed_routes` to continue the same investigation, preserving running/unknown/cancelled jobs. API execution follows prepare → start → status → result → import and requires separate credentials. Scrapling, Firecrawl and MarkItDown remain researched projects. A public GitHub README fetch does not inspect the whole repository.
 
 Read the [deep research guide](../skills/bookmark-research/references/deep-research.md) for inputs and CLI examples. `research_start` freezes the complete indexed packages selected by `source_ids`; a subset requires explicit `scope_mode:"subset"`. Paginate `research_inventory` to the end. `bookmark_refs` identify focus items without silently narrowing whole-package scope.
 
-`research_search` and `research_fetch` reserve retrieval attempts; repeating the same `operation_id` returns its recorded outcome. The default fetch budget accounts for the selected input size: 207 URLs require at least 26 full batches and receive 38 calls, within an 80-call limit. Explicit budgets are retained; insufficient capacity is reported without removing URLs. These controls do not measure or limit invisible host/model calls.
+`research_search` and `research_fetch` reserve retrieval attempts; repeating the same `operation_id` returns its recorded outcome. The default fetch budget accounts for the selected input size: 207 URLs require at least 13 full batches and receive 25 calls, within an 80-call limit. Explicit budgets are retained; insufficient capacity is reported without removing URLs. These controls do not measure or limit invisible host/model calls.
 
 `research_source` reads saved text. Record content acceptance, quoted claims and each original URL's substantive judgment. A rejected source or retracted claim reopens affected questions. `research_coverage` reports gaps; `research_finish` refuses completion while original-source reviews, questions, conflicts or active/unknown external runs remain unresolved. Blocked and excluded sources remain visible in the original denominator. An `incomplete` report preserves the remaining work.
 
@@ -139,7 +136,7 @@ Active tasks can continue directly. After exporting an `incomplete` report, use
 
 [Professional service tools](../skills/bookmark-research/references/research-services.md) prepare the exact brief/source payload, start once, observe the existing run, and archive its report. OpenAI cancellation is supported; Parallel cancellation is not established by this adapter. Unknown create outcomes are retained without resubmission. Imported reports remain secondary evidence and never mark all cited original URLs as read.
 
-[Wiki and quality evaluation](wiki-quality.md) track reviewed knowledge and measure supplied run results. Semantic citation accuracy requires actual reviewer labels. The included synthetic fixture demonstrates the scorer; it provides no evidence that a host, workflow or provider produces better research.
+[Wiki](../skills/bookmark-research/references/wiki.md) stores reviewed knowledge with immutable revisions, evidence links and freshness checks. It is a knowledge base, not an automatic scorer; quality claims still need actual reviewer labels and real runs.
 
 ## Duplicate bookmarks, context, and result merging
 
@@ -155,7 +152,7 @@ Duplicate item IDs within one section are identity conflicts and cause import fa
 
 Ask "Show the plugin settings," "Use only Exa for future searches," "Save page text to my knowledge directory," or "Read this page without archiving." The model uses `get_settings`, `update_settings`, or parameters for the current `fetch_web` call. There is no separate graphical settings page.
 
-Run `python3 src/cli.py setup` to revisit the terminal wizard. Before each new web research question, the Skill calls `research_readiness`: by default it refreshes checks on first use, configuration/key changes, or after 15 minutes. Choose `always` or `manual` in setup. Local bookmark queries stay offline. Readiness separates missing keys, reachable catalogs, tested retrieval, and host-managed OAuth; it never starts a professional research job.
+Run `python3 src/cli.py setup` to revisit the terminal wizard. Use `research_readiness` from the advanced catalog when diagnosing access; explicit checks refresh on first use, configuration/key changes, or after 15 minutes. Choose `always` or `manual` in setup. Local bookmark queries stay offline. Readiness separates missing keys, reachable catalogs, tested retrieval, and host-managed OAuth; it never starts a professional research job.
 
 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.
 
@@ -182,11 +179,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 |
+| `get_context` | Read section, card, group, connection, and item-ancestor context; `compact:true` drops raw JSON, descriptions and revisions |
+| `plan_research` | Local preflight for one question: ranked cards and bookmarks, Wiki and archive pointers, relevance, freshness, fetch ownership, and a route; missing-file cards are flagged and their URLs are kept |
 | `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 |
+| `fetch_web` | Read known URLs under a per-page and batch budget, optionally archive text, and continue a saved extract with `capture_id`/`offset` |
 | `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 |
@@ -201,9 +200,11 @@ The [shared Skill](../skills/bookmark-research/SKILL.md) guides the agent's work
 | `research_inventory` / `research_coverage` | Paginate original sources and compare actual review against the complete frozen scope |
 | `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 |
+| `discovery_bundle` | Own the route-② budget check and assemble the citable evidence bundle (excerpts, then digest, then a URL list) from the sources the host read; only usable pages become evidence |
 | `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 |
-| `evaluate_research` | Compute metrics from explicit tasks, outputs, measurements and reviewer labels |
+| `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 |
 
 ### Web providers
 
@@ -213,11 +214,12 @@ The [shared Skill](../skills/bookmark-research/SKILL.md) guides the agent's work
 | **Parallel** | Built into the MCP server and CLI for search and URL reading |
 | **Jina** | HTTP Reader supports anonymous webpage/PDF reading; Search requires `JINA_API_KEY`. The hosted Jina MCP is not used. |
 | **Tavily** | Built-in search fallback and selectable extraction; `TAVILY_API_KEY` uses Bearer, otherwise explicit keyless mode |
+| **DeepSeek Search / Fetch** | Optional raw JSON tools API (`/v1/tools/search`, `/v1/tools/fetch`); requires `DEEPSEEK_API_KEY`; OpenAI-compatible error shape, not a Chat Completions tool |
 | **GitHub** | Use the host's existing GitHub MCP or `gh` for repository-specific tasks. No GitHub MCP is bundled; public pages can also be read through Exa / Parallel. |
 
-All four retrieval providers run through the plugin's own MCP or CLI; additional host MCP registrations are unnecessary. Search starts with Exa + Parallel and uses configured fallbacks for unresolved queries; reading falls back to Parallel + Jina after Exa. Anonymous/keyless access and quotas depend on each service's policy; optional credentials use `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY` or `JINA_API_KEY` in the launching environment. Local queries work offline.
+All retrieval providers run through the plugin's own MCP or CLI; additional host MCP registrations are unnecessary. Search starts with Exa + Parallel under a selectable strategy (hedged by default) with a grace window and total deadline, and uses configured fallbacks for unresolved queries; reading falls back to Parallel + Jina after Exa. Anonymous/keyless access and quotas depend on each service's policy; optional credentials use `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, `JINA_API_KEY` or `DEEPSEEK_API_KEY` in the launching environment. Local queries work offline.
 
-`search_providers` describes configuration without network access; `probe:true` discovers remote MCP tools, while Jina's HTTP mapping remains explicitly `not_probed`. Discovery does not prove successful retrieval. Each MCP process reuses remote sessions and a bounded tool catalog. Calls are not automatically replayed after errors. See [MCP architecture and observed service behavior](mcp-aggregation-0.2.0.md) for the initial implementation and checks.
+`search_providers` describes configuration without network access; `probe:true` discovers remote MCP tools, while Jina and DeepSeek HTTP mappings remain explicitly `not_probed`. Discovery does not prove successful retrieval. Each MCP process reuses remote sessions and a bounded tool catalog. Calls are not automatically replayed after errors. Historical implementation notes remain available in Git history.
 
 ### Package rules and AGENTS.md
 
@@ -225,13 +227,15 @@ Analysis rules are included in the Skill. The [package reading protocol](../skil
 
 Routine analysis of supported formats does not require rereading the entire package `AGENTS.md`, and the runtime does not depend on it. Consult relevant original instructions for new formats, field conflicts, or package-specific conventions. Applicable directory instructions already loaded by the client still apply.
 
+An exported guide may name this plugin as an optional read-only companion. That mention does not grant write access; the guide's hard constraints still govern any edit to the package.
+
 GitHub references and Git sync rules in a package's `AGENTS.md` do not automatically connect a GitHub service. See [GitHub and sync boundaries](../skills/bookmark-research/references/github-and-sync.md).
 
-The Skill currently produces answers and research reports. It does not generate importable bookmark packages or write changes back to source data. A future generation Skill could reuse the reading protocol with additional writing rules and validation.
+The Skill currently produces answers and research reports. It does not generate importable bookmark packages or write changes back to source data. A future generation Skill could reuse the reading protocol with additional writing rules and validation, but the package's exported guide remains the write protocol.
 
 ## Export formats
 
-This directory is the **Codex native plugin**, with its manifest at `.codex-plugin/plugin.json`. In Codex 0.153.4, the MCP configuration explicitly uses `cwd: "."` and runs `python3 src/cli.py serve` from the installed plugin directory. That native entry does not expand `${PLUGIN_ROOT}`; the Agent Plugins and Claude exports use their own path conventions.
+This directory is the **Codex native plugin**, with its manifest at `.codex-plugin/plugin.json`. In Codex 0.153.4, the MCP configuration explicitly uses `cwd: "."` and runs `python3 src/cli.py serve` from the installed plugin directory. That native entry does not expand `${PLUGIN_ROOT}`; the Claude export uses its own path convention.
 
 The Codex manifest forwards these environment variable names through `env_vars`: `BOOKMARK_RESEARCH_DATA_DIR`, `BOOKMARK_RESEARCH_CONFIG`, `XDG_DATA_HOME`, `XDG_CONFIG_HOME`, `EXA_API_KEY`, `PARALLEL_API_KEY`, `TAVILY_API_KEY`, and `OPENAI_API_KEY`. Actual paths and credentials come from the user's runtime environment.
 
@@ -240,17 +244,13 @@ Run the relevant command **from this directory** to generate another format:
 ```sh
 python3 scripts/export_bundle.py --format codex --output exports/codex/bookmark-research
 python3 scripts/export_bundle.py --format claude --output exports/claude/bookmark-research
-python3 scripts/export_bundle.py --format pi --output exports/pi/bookmark-research
 python3 scripts/export_bundle.py --format dsh --output exports/dsh/bookmark-research
-python3 scripts/export_bundle.py --format agent-plugin --output exports/agent-plugin/bookmark-research
 ```
 
 The destination must be new or empty. Exports include their own English setup README with links to bundled Chinese and English user guides, and exclude indexes, caches, tests, and credentials. The exporter writes files; follow the generated README or [installation guide](installation.en.md) to load them in your client.
 
 - **Claude Code:** plugin + marketplace manifests, `.mcp.json` and a Dynamic Workflow; supports persistent native installation or session loading with `--plugin-dir`.
-- **Pi:** `package.json` declares `pi.skills`; the Skill calls the CLI. Register the project workflow for the separately installed subagent extensions when available.
 - **DSH:** a relocatable `dsh.bundle` that connects the Skill and MCP, plus the legacy absolute-path patch and workflow call generator. Workflow components remain optional and host-managed.
-- **Agent Plugins 1.0.0:** root `plugin.json` + `mcp.json`, for clients implementing that specification; generated separately from Codex's native manifest.
 
 See the [client support table](#client-support) for verification status and [compatibility notes (Chinese)](harness-compatibility.md) for format differences and official sources.
 
@@ -263,13 +263,12 @@ From this plugin directory **in a full repository checkout**, developers can run
 ```sh
 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.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.
 
-Network verification is explicit: `python3 tests/live_provider_smoke.py --run-live --output /tmp/provider-smoke.json` makes at most three searches and three fetches. The [0.4.0 validation record](validation-0.4.0.md) combines source lifecycle, whole-package research, bilingual instructions and host/service boundaries; [0.2.0](validation-0.2.0.md) retains the earlier provider evidence.
+Network verification is explicit: `python3 tests/live_provider_smoke.py --run-live --output /tmp/provider-smoke.json` makes at most three searches and three fetches. Historical validation records remain available in Git history.
 
 The local stdio server exposes fixed tools. Its remote client implements the selected providers' Streamable HTTP lifecycle, bounded paginated tool discovery and limited session recovery; it is not a general OAuth client or a complete MCP SDK.

package/docs/details.md

@@ -21,21 +21,21 @@
 
 不需要固定提示词。完整数据包研究保留所有原始 URL 和重复书签语境；只有明确限定卡片、分组或专题时才缩小范围。搜索摘要、搜索结果的第一页和外部报告都不能代替原始网页审阅。
 
-一个插件保留一个 MCP 聚合入口和一个执行 Skill；后端服务数量与入口数量无关。MCP 内置 Exa、Parallel、Tavily 搜索／读取适配器、Jina HTTP 接口和 OpenAI／Parallel 研究 API 客户端。Skill 负责根据任务选择并执行三种流程：
+一个插件保留一个 MCP 聚合入口和一个执行 Skill；后端服务数量与入口数量无关。MCP 内置 Exa、Parallel、Tavily 搜索／读取适配器、Jina HTTP 接口、可选的 DeepSeek Search／Fetch 接口和 OpenAI／Parallel 研究 API 客户端。Skill 负责根据任务选择并执行三种流程：
 
 | 场景 | 基础流程 | 检索与委派支持 |
 | --- | --- | --- |
 | URL 直读 | 当前模型读取已知页面并回答 | Exa 未读到的 URL 交给 Parallel + Jina Reader 并发读取；可配置 Tavily 提取。 |
-| Agentic Web Search | 当前宿主模型先规划 → 搜索／读文 → 判断证据 → 针对缺口补查 | Exa + Parallel 提供搜索结果；无有效网址的查询再交给 Tavily + 有 key 的 Jina。普通问题无需完整研究会话。 |
-| Deep Research | 在宿主研究循环上增加持续调查、按需协作、独立核验、覆盖检查与报告 | 优先利用宿主现有子代理／工作流；外部 Research MCP／API 可承担宿主判断后的子问题或用户明确指定的任务。 |
+| Agentic Web Search | 当前宿主模型先规划 → 搜索／读文 → 判断证据 → 针对缺口补查 | Exa + Parallel 按 `search.strategy` 提供搜索结果（默认并发对冲）；无有效网址的查询再交给 Tavily + 有 key 的 Jina。普通问题无需完整研究会话。 |
+| Deep Research | 直接向研究 API 提交完整问题，观察进度并审阅报告 | 可选 OpenAI／Parallel API；宿主已有研究能力亦可使用。完整清单与覆盖审计按需启用。 |
 
-四个基座共用这套方法：Codex 原生子代理、Claude 普通子代理或已启用团队、Pi 扩展、已配置的 DSH 子代理／工作流；具体差异与官方依据见 [宿主兼容说明](harness-compatibility.md)。整包脚本用于分组研究。保存的 API 偏好只排列外部服务，显式 provider 才直接指定服务；明确路线失败可继续换路，运行中、结果未知或已取消任务不自动重建。
+三个基座共用这套方法：Codex 原生子代理、Claude 普通子代理或已启用团队、已配置的 DSH 子代理／工作流；具体差异与官方依据见 [宿主兼容说明](harness-compatibility.md)。整包脚本用于分组研究。API 可独立调用，无需先运行宿主调查或创建本地研究会话。运行中和结果未知的任务先观察，保留 operation ID，避免重复创建。
 
 “备用”表示已加入回退列表；“需要配置”表示条件未满足时跳过；“仅调研”表示没有接入，失败也不会自动安装。OpenAI／Parallel 研究 API 默认关闭，需启用并提供凭据。宿主已加载的 Exa `agent_run`、完整 Parallel Task MCP 会被路由识别，实际认证仍以调用结果为准。Scrapling、Firecrawl、MarkItDown 等调研项目没有集成成自动后端。
 
 ## 数据包与保存位置
 
-JSON／`.canvas` 是源数据，SQLite 是可重建的本地查询索引，无需单独数据库服务器。插件不会回写原始画布包。
+JSON／`.canvas` 是源数据，SQLite 是可重建的本地查询索引，无需单独数据库服务器。插件不会回写原始画布包。导出的 `AGENTS.md`/`CLAUDE.md` 可能把本插件列为可选的只读辅助；这个提及不授予写入权限，包内修改仍以该指南为准。
 
 | 来源 | 默认行为 |
 | --- | --- |
@@ -57,21 +57,21 @@ JSON／`.canvas` 是源数据，SQLite 是可重建的本地查询索引，无
 - `wiki/`：主题／实体页和不可变修订；每次写入更新 `index.md`（目录）并追加 `log.md`（时间线）。
 - `raw-library.sqlite3`：`search_archive` 的全文索引，覆盖 `knowledge/` 与所有研究证据，可重建。
 
-配置默认为 `~/.config/bookmark-research/settings.json`。`wiki.after_research` 决定研究结束后的 Wiki 整理：`suggest`（默认，先建议再问）、`auto`、`off`。支持 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)。
 
 ## 搜索、配置与语言
 
-`search.providers` 为第一轮，`search.fallback_providers` 为无结果时的备用列表；设为空数组可关闭搜索回退。读取单独配置 `fetch.provider` 和 `fetch.providers`。调用时明确指定 provider／providers 则只用指定服务。已有配置若只设置过搜索 providers，会保留原来的服务范围；新研究冻结当时的选择，旧记录重放不会增加请求。瀑布流按轮补缺，同轮服务并发；已发出的请求仍需等待结束或超时。普通网页归档开启，深度研究始终保存任务证据。
+`search.providers` 为第一轮，`search.fallback_providers` 为无结果时的备用列表；设为空数组可关闭搜索回退。第一轮策略由 `search.strategy` 选择（默认 hedged 全并发对冲；staggered 错峰、sequential 顺序、wait_all 等全部），按 `search.grace_seconds`（默认 2）与 `search.deadline_seconds`（默认 10）约束：超限的 provider 被放弃或不再调用，分别记入 `routing.abandoned_providers` 与 `routing.not_attempted_providers`，被放弃的请求可能仍消耗额度；研究任务保持等待全部。读取单独配置 `fetch.provider` 和 `fetch.providers`，策略由 `fetch.strategy` 选择（默认 staggered：当前提供商停滞超过 `fetch.grace_seconds` 才并行下一家；hedged 全并发、sequential 逐家；被放弃者记入 `abandoned_providers`）。`fetch.reuse_seconds` 可在窗口内直接复用已存正文（返回 `reused_sources`，不联网、不占抓取预算），`search.cache_seconds` 让重复的相同搜索走短期缓存（批次标记 `cached:true`）。调用时明确指定 provider／providers 则只用指定服务。已有配置若只设置过搜索 providers，会保留原来的服务范围；新研究冻结当时的选择，旧记录重放不会增加请求。瀑布流按轮补缺，同轮服务并发；已发出的请求仍需等待结束或超时。普通网页归档开启，深度研究始终保存任务证据。
 
 可以读取公开 GitHub 仓库页面、README、文件和 issues；读取 README 不等于遍历整个代码仓库。代码审查按任务选择具体文件或宿主已有 GitHub 工具，插件未额外安装 GitHub MCP。
 
 网络访问依赖服务方的认证与额度。可运行 `python3 src/cli.py setup` 隐藏输入密钥，或在宿主环境设置 `EXA_API_KEY`、`PARALLEL_API_KEY`、`TAVILY_API_KEY`、`JINA_API_KEY`、`OPENAI_API_KEY`。密钥默认保存为配置旁仅当前用户可读的 `credentials.json`，环境变量优先。无需给宿主研究额外填写一套模型地址。
 
-Skill 在每个联网研究新问题前调用 `research_readiness`，默认首次、配置／密钥变化或 15 分钟过期时刷新。向导可改为每题检查或仅手动检查；本地查询不联网。结果区分密钥配置、目录可达、实际检索与宿主 OAuth，检查不会启动专业研究任务。
+需要诊断服务访问问题时，可从高级工具面调用 `research_readiness`，显式检查默认在首次、配置／密钥变化或 15 分钟过期时刷新。向导可改为每题检查或仅手动检查；本地查询不联网。结果区分密钥配置、目录可达、实际检索与宿主 OAuth，检查不会启动专业研究任务。
 
-中英文用户共用一个插件；回答、报告正文和 Wiki 章节跟随用户指定语言。原始引用和 URL 保留原文，译文另列。执行 Skill 和 11 篇方法参考以英文维护，配完整中文阅读对照；子代理和工作流也会接收本次输出语言。详见[指令与提示索引](instructions.md)。工具字段、技术诊断和部分固定元数据标签使用英文。
+中英文用户共用一个插件；回答、报告正文和 Wiki 章节跟随用户指定语言。原始引用和 URL 保留原文，译文另列。执行 Skill 和方法参考以英文维护，配完整中文阅读对照；子代理和工作流也会接收本次输出语言。详见[指令与提示索引](instructions.md)。工具字段、技术诊断和部分固定元数据标签使用英文。
 
 ## 宿主与验证范围
 
@@ -79,10 +79,9 @@ Skill 在每个联网研究新问题前调用 `research_readiness`，默认首
 | --- | --- | --- |
 | Codex | 原生 Plugin + Skill + MCP | 隔离配置中的原生安装／更新与 stdio 检查。 |
 | Claude Code | 持久 marketplace／插件和 Dynamic Workflow | 隔离配置中的原生安装／更新／缓存检查；模型调用另行验证。 |
-| Pi | Skill + CLI／stdio 桥 | 适配器隔离验证；子代理工作流依赖已有扩展。 |
 | DSH | 可搬移 bundle，包含 Skill 与 MCP | 安装器／适配器验证；工作流仍需宿主服务与引擎。 |
 
-另有 Agent Plugins 1.0.0 标准格式导出。适配器存在不代表每个宿主都已完成真实研究。Wiki 保存引用、审阅和修订；评测根据实际运行数据及显式评审标签计算，示例分数不能证明研究质量。
+适配器存在不代表每个宿主都已完成真实研究。Wiki 保存引用、审阅和修订；来源完整性与语义支持分别判断，工具检查通过不能证明研究质量。
 
 ## 开发与来源
 
@@ -92,4 +91,4 @@ python3 scripts/verify_fixture.py --output /tmp/bookmark-research-verification
 python3 scripts/export_bundle.py --format codex --output exports/codex/bookmark-research
 ```
 
-研究来源与演进见[设计调研](research-0.2.0.md)、[宿主兼容性](harness-compatibility.md)和[Wiki／评测](wiki-quality.zh.md)。项目源自 Bookmark Canvas，沿用 [GPL-3.0](../LICENSE)。
+研究来源与演进见[宿主兼容性](harness-compatibility.md)和[Wiki](../skills/bookmark-research/references/zh/wiki.md)；早期设计与验证记录可从 Git 历史查阅。项目源自 Bookmark Canvas，沿用 [GPL-3.0](../LICENSE)。

package/docs/distribution.md

@@ -6,14 +6,13 @@
 | --- | --- | --- |
 | `npx bookmark-research@latest install codex` | npm 发布包 → Codex 格式 | Codex 原生命令 |
 | `npx bookmark-research@latest install claude` | 同一个 npm 包 → Claude 格式 | Claude Code 原生命令 |
-| `npx bookmark-research@latest install pi` | 同一个 npm 包 → Pi 格式 | `pi install` |
 | `npx bookmark-research@latest install dsh --profile web` | 同一个 npm 包 → DSH bundle | `dsh plugin --profile web add` |
 | GitHub `install.sh` | 转交上述 npm 入口 | 所选宿主原生命令 |
 | Codex GitHub marketplace | 清单中固定的 npm 版本 | Codex 直接下载和登记 |
 
-统一的是发布内容和来源。不同宿主需要不同清单，安装器只生成所需格式，用户配置、宿主登记及缓存仍交给宿主命令。Pi 的基础路径提供 Skill 和 CLI；其他宿主按各自适配提供 MCP。
+统一的是发布内容和来源。不同宿主需要不同清单，安装器只生成所需格式，用户配置、宿主登记及缓存仍交给宿主命令。Claude Code、Codex 和 DSH 按各自适配提供 MCP 或 Skill。
 
-默认安装器记录 `npm:bookmark-research`（`latest`），更新时重新下载，不依赖已清理的 npx 缓存。显式 `--source npm:bookmark-research@VERSION` 会保留版本；要测试同一个固定发布版，在四个宿主使用相同参数。Codex 原生 marketplace 使用清单固定版本，跟随清单更新。需要新版安装器时运行 `npx bookmark-research@latest update`，或先更新全局 npm 安装。
+默认安装器保留当前启动包的内容快照，`update` 继续使用这一构建，不依赖已清理的 npx 缓存。采用新发布版时运行 `npx bookmark-research@latest install` 并确认升级覆盖；Codex 非交互方式添加 `--replace-source`。显式 `--source npm:bookmark-research` 记录 `latest` 并在更新时重新下载；`--source npm:bookmark-research@VERSION` 固定版本。要测试同一个固定发布版，在三个宿主使用相同参数。Codex 原生 marketplace 使用清单固定版本，跟随清单更新。需要新版安装器时使用 `npx bookmark-research@latest`，或先更新全局 npm 安装；采用新版发布内容需运行 `install` 并确认升级覆盖。
 
 源码开发使用 `python3 scripts/install.py install --source PATH`，也可显式选择 Git 仓库和 `--ref`。旧 Git／本地安装保留来源，不静默转成 npm；切换时先用宿主命令处理旧登记。源码导出、ZIP 和测试包脚本保留为开发工具，CI 的验证产物仍可包含 npm `.tgz` 与 SHA-256 校验文件，但不作为 GitHub Release 下载入口。GitHub 自动生成的 Source code 压缩包是源码快照，不能单独关闭，不作为安装包。
 
@@ -21,7 +20,7 @@
 
 候选版本在 `release/` 分支同步三个版本清单并运行 CI。该分支的 registry 集成测试使用当前已发布渠道版本，源码测试、原生安装测试和 npm 打包检查仍验证候选内容；主分支的 registry 测试始终验证 marketplace 固定版本。发布通过 CI 的 npm 包并核验 registry 后，再将候选分支合入主分支，避免默认安装清单提前指向未发布版本。
 
-测试版使用 npm 的 `beta` 标签；若创建 GitHub 版本说明，则标记为预发布。不会自动移动 npm 的 `latest` 标签。安装测试版时同时固定安装器与内容来源，例如 `npx bookmark-research@0.5.0-beta.8 install --source npm:bookmark-research@0.5.0-beta.8`。仅将 npx 改为 `@beta` 不会改变默认内容来源 `latest`；已固定的旧版安装也不会自动换成测试版。
+发布时保持 npm 的 `latest` 标签始终指向最新构建，用户直接使用 `npx bookmark-research install`（或 `npx bookmark-research@latest install`）即可默认安装最新版。启动器会自动读取当前运行包版本并固定内容来源，无需重复指定 `--source`。已存在的宿主配置支持无缝覆盖升级。
 
 ## 官方资料与项目实例
 
@@ -29,9 +28,7 @@
 
 - [OpenAI：Package your plugin](https://developers.openai.com/plugins/build/plugins)：marketplace 可指向本地、Git 或 npm；npm 内容下载不执行生命周期脚本。
 - [Claude Code：Plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces#npm-packages)：支持 npm、GitHub、Git URL 和本地目录等来源。
-- [Pi：Packages](https://pi.dev/docs/latest/packages)：支持 npm、Git 和本地路径；版本化 npm 来源保持固定。
 - [DSH：Package and install a plugin](https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/publish)：支持 Git 安装，也建议发布已构建的 npm 包或 tarball，免去用户安装时构建。
-- [Superpowers](https://github.com/obra/superpowers)：按宿主提供不同安装方式，Pi 使用 Git 仓库，Claude Code 使用 marketplace，并非 npm 唯一来源。
-- [pi-skills](https://github.com/badlogic/pi-skills)：跨宿主 Skill 集合，文档仍提供 Git 克隆安装。
+- [Superpowers](https://github.com/obra/superpowers)：按宿主提供不同安装方式；Claude Code 使用 marketplace，并非 npm 唯一来源。
 
 这些资料说明“宿主安装方式不同”是正常的；本项目统一发布包后仍保留必要的宿主适配。