bookmark-research 0.5.0-beta.3 → 0.5.0-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/.agents/plugins/marketplace.json +4 -2
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/README.md +15 -13
  4. package/README.zh.md +15 -13
  5. package/docs/distribution.md +35 -0
  6. package/docs/installation.en.md +35 -14
  7. package/docs/installation.md +39 -24
  8. package/docs/release-notes-0.5.0-beta.4.md +39 -0
  9. package/install.sh +59 -298
  10. package/package.json +2 -2
  11. package/scripts/host_install.py +10 -1
  12. package/scripts/install.py +149 -43
  13. package/scripts/launcher.py +3 -0
  14. package/scripts/npm_source.py +74 -0
  15. package/skills/bookmark-research/SKILL.md +32 -55
  16. package/skills/bookmark-research/references/package-semantics.md +16 -0
  17. package/skills/bookmark-research/references/zh/package-semantics.md +16 -0
  18. package/skills/bookmark-research/references/zh/skill-guide.md +33 -56
package/.agents/plugins/marketplace.json CHANGED
@@ -7,8 +7,10 @@
7
7
  {
8
8
  "name": "bookmark-research",
9
9
  "source": {
10
- "source": "local",
11
- "path": "./"
10
+ "source": "npm",
11
+ "package": "bookmark-research",
12
+ "version": "0.5.0-beta.3",
13
+ "registry": "https://registry.npmjs.org"
12
14
  },
13
15
  "policy": {
14
16
  "installation": "AVAILABLE",
package/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bookmark-research",
3
- "version": "0.5.0-beta.3",
3
+ "version": "0.5.0-beta.4",
4
4
  "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
5
5
  "author": {
6
6
  "name": "kwenxu"
package/README.md CHANGED
@@ -6,7 +6,7 @@ Research your bookmarks with verified web sources. Give it a list of bookmark UR
6
6
 
7
7
  Works in **Codex, Claude Code, Pi and DSH (DeepSeek Harness)**.
8
8
 
9
- [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)
9
+ [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)
10
10
 
11
11
  > [!NOTE]
12
12
  > **0.5.0 is a beta.** Report problems on [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues).
@@ -15,7 +15,7 @@ Works in **Codex, Claude Code, Pi and DSH (DeepSeek Harness)**.
15
15
 
16
16
  - Python 3.9+ with SQLite FTS5 (check with `bookmark-research doctor`)
17
17
  - The CLI of at least one client: Codex, Claude Code, Pi or DSH (DSH also needs `pnpm`)
18
- - Node 18+ for the `bookmark-research` command; optional on macOS/Linux
18
+ - Node 18+ and npm for release installation (including the GitHub convenience script)
19
19
  - No API key is needed to install or to query bookmarks locally
20
20
 
21
21
  ## Install
@@ -23,25 +23,27 @@ Works in **Codex, Claude Code, Pi and DSH (DeepSeek Harness)**.
23
23
  **Interactive** (macOS, Linux, Windows):
24
24
 
25
25
  ```sh
26
- npx bookmark-research install
26
+ npx bookmark-research@latest install
27
27
  ```
28
28
 
29
29
  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.
30
30
 
31
- 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`.
31
+ 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`.
32
32
 
33
33
  **One client, no prompts:**
34
34
 
35
35
  | Client | Command | Registers with |
36
36
  | --- | --- | --- |
37
- | Codex | `npx bookmark-research install codex --non-interactive` | `codex plugin add` |
38
- | Claude Code | `npx bookmark-research install claude --scope user --non-interactive` | `claude plugin install` |
39
- | Pi | `npx bookmark-research install pi --non-interactive` | `pi install` |
40
- | DSH | `npx bookmark-research install dsh --profile web --non-interactive` | `dsh plugin add` |
37
+ | Codex | `npx bookmark-research@latest install codex --non-interactive` | `codex plugin add` |
38
+ | Claude Code | `npx bookmark-research@latest install claude --scope user --non-interactive` | `claude plugin install` |
39
+ | Pi | `npx bookmark-research@latest install pi --non-interactive` | `pi install` |
40
+ | DSH | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
41
+
42
+ **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).
41
43
 
42
44
  **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.
43
45
 
44
- 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).
46
+ 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).
45
47
 
46
48
  **Ask your agent to install it.** Paste this into Codex, Claude Code, Pi or DSH:
47
49
 
@@ -49,12 +51,12 @@ Several at once: `npx bookmark-research install claude dsh --profile web --non-i
49
51
  Install the Bookmark Research plugin into the client you are running in.
50
52
 
51
53
  1. Identify your own client: codex, claude, pi or dsh.
52
- 2. Run: npx bookmark-research install <client> --non-interactive
54
+ 2. Run: npx bookmark-research@latest install <client> --non-interactive
53
55
  - Claude Code or Pi: add --scope user (or --scope project --project <dir>).
54
56
  - DSH: add --profile <profile>; ask me for the profile name.
55
57
  3. The command prints JSON. Confirm "verified": true and report any "error".
56
58
  4. Do not ask me for API keys in chat. Tell me to run `bookmark-research setup`
57
- (or `npx bookmark-research setup`) in my terminal to enter them.
59
+ (or `npx bookmark-research@latest setup`) in my terminal to enter them.
58
60
  5. Tell me to start a new session so the Skill and MCP tools load.
59
61
  ```
60
62
 
@@ -70,7 +72,7 @@ No reinstall is needed. Settings and keys apply to every installed client; start
70
72
  | Script preferences | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
71
73
  | Update or verify all clients | `bookmark-research update` · `bookmark-research verify` |
72
74
 
73
- Use `npx bookmark-research …` if the command is not installed globally.
75
+ Use `npx bookmark-research@latest …` if the command is not installed globally.
74
76
 
75
77
  **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.
76
78
 
@@ -127,7 +129,7 @@ Tool descriptions: [details](docs/details.en.md#mcp-tools).
127
129
 
128
130
  ## More
129
131
 
130
- - [Installation guide](docs/installation.en.md): all install options, updates, ZIP downloads
132
+ - [Installation guide](docs/installation.en.md): all install options, npm updates and source development
131
133
  - [User guide](docs/user-guide.en.md): first use, the three research modes, languages
132
134
  - [Details](docs/details.en.md): data model, research modes, settings, export formats, development checks
133
135
  - [Architecture](docs/bookmark-research-architecture.md) (Chinese)
package/README.zh.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  支持 **Codex、Claude Code、Pi、DSH（DeepSeek Harness）**。
8
8
 
9
- [安装说明](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)
9
+ [安装说明](docs/installation.md) · [使用指南](docs/user-guide.md) · [详细说明](docs/details.md) · [npm](https://www.npmjs.com/package/bookmark-research)
10
10
 
11
11
  > [!NOTE]
12
12
  > **0.5.0 是测试版。** 遇到问题请到 [GitHub Issues](https://github.com/Browser-bookmark-hub/Bookmark-Research/issues) 反馈。
@@ -15,7 +15,7 @@
15
15
 
16
16
  - Python 3.9+，含 SQLite FTS5（可用 `bookmark-research doctor` 检查）
17
17
  - 至少一个宿主的 CLI：Codex、Claude Code、Pi 或 DSH（DSH 另需 `pnpm`）
18
- - `bookmark-research` 命令需要 Node 18+；macOS/Linux 上可不用
18
+ - 发布版安装需要 Node 18+ 和 npm（GitHub 便捷脚本也需要）
19
19
  - 安装和本地查书签都不需要 API Key
20
20
 
21
21
  ## 安装
@@ -23,25 +23,27 @@
23
23
  **交互安装**（macOS、Linux、Windows）：
24
24
 
25
25
  ```sh
26
- npx bookmark-research install
26
+ npx bookmark-research@latest install
27
27
  ```
28
28
 
29
29
  用方向键和空格选择宿主，确认汇总后安装，再选择搜索服务、输入 API Key。装好后新建一个宿主会话。
30
30
 
31
- 想一直能用 `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`。
31
+ 想一直能用 `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`。
32
32
 
33
33
  **指定宿主、不弹提示：**
34
34
 
35
35
  | 宿主 | 命令 | 实际登记方式 |
36
36
  | --- | --- | --- |
37
- | Codex | `npx bookmark-research install codex --non-interactive` | `codex plugin add` |
38
- | Claude Code | `npx bookmark-research install claude --scope user --non-interactive` | `claude plugin install` |
39
- | Pi | `npx bookmark-research install pi --non-interactive` | `pi install` |
40
- | DSH | `npx bookmark-research install dsh --profile web --non-interactive` | `dsh plugin add` |
37
+ | Codex | `npx bookmark-research@latest install codex --non-interactive` | `codex plugin add` |
38
+ | Claude Code | `npx bookmark-research@latest install claude --scope user --non-interactive` | `claude plugin install` |
39
+ | Pi | `npx bookmark-research@latest install pi --non-interactive` | `pi install` |
40
+ | DSH | `npx bookmark-research@latest install dsh --profile web --non-interactive` | `dsh plugin add` |
41
+
42
+ **四个宿主统一发布来源：** npm 包包含共享运行时、Skill 和宿主适配。安装器下载发布包，生成所选宿主格式，再调用宿主原生命令；更新记录 npm 来源，不依赖 npx 临时缓存。GitHub 提供源码和安装清单，未发布源码用 Python 安装器。见[发布约定与官方依据](docs/distribution.md)。
41
43
 
42
44
  **Windows：** Windows 上常常没有能用的 `python3`，所以安装器会把检测到的 Python 路径写进各宿主的 MCP 配置。Codex 请用 `bookmark-research install codex` 安装，不要直接把仓库加进 Codex。`bookmark-research status` 可以查看实际使用的 Python。
43
45
 
44
- 一次装多个：`npx bookmark-research install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
46
+ 一次装多个：`npx bookmark-research@latest install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。
45
47
 
46
48
  **让 agent 帮你装。** 把下面这段粘贴给 Codex、Claude Code、Pi 或 DSH：
47
49
 
@@ -49,12 +51,12 @@ npx bookmark-research install
49
51
  请把 Bookmark Research 插件安装到你当前运行的这个宿主里。
50
52
 
51
53
  1. 先确认你自己是哪个宿主：codex、claude、pi 或 dsh。
52
- 2. 运行：npx bookmark-research install <宿主> --non-interactive
54
+ 2. 运行：npx bookmark-research@latest install <宿主> --non-interactive
53
55
  - Claude Code 或 Pi：加 --scope user（或 --scope project --project <目录>）。
54
56
  - DSH：加 --profile <名称>；profile 名称请先问我。
55
57
  3. 命令会输出 JSON。确认 "verified": true，有 "error" 就告诉我。
56
58
  4. 不要在对话里向我要 API Key。请让我在终端运行 `bookmark-research setup`
57
- （或 `npx bookmark-research setup`）自己输入。
59
+ （或 `npx bookmark-research@latest setup`）自己输入。
58
60
  5. 提醒我新建一个会话，让 Skill 和 MCP 工具生效。
59
61
  ```
60
62
 
@@ -70,7 +72,7 @@ npx bookmark-research install
70
72
  | 用脚本改偏好 | `bookmark-research config show` · `bookmark-research config set --input prefs.json` |
71
73
  | 更新或验证所有宿主 | `bookmark-research update` · `bookmark-research verify` |
72
74
 
73
- 没有全局安装时，在前面加 `npx`，例如 `npx bookmark-research setup`。
75
+ 没有全局安装时，在前面加 `npx`，例如 `npx bookmark-research@latest setup`。
74
76
 
75
77
  **API Key 都是可选的。** 在 `bookmark-research setup` 里输入（隐藏显示，输完当场检查，保存在仅当前用户可读的本地文件），或者设置环境变量（优先于已保存的 Key）。Key 不接受对话、命令参数或 JSON 文件。
76
78
 
@@ -125,7 +127,7 @@ setup 还会问研究报告和证据放在哪里：统一目录（默认 `<数
125
127
 
126
128
  ## 更多
127
129
 
128
- - [安装说明](docs/installation.md)：全部安装方式、更新、ZIP 下载
130
+ - [安装说明](docs/installation.md)：全部安装方式、npm 更新与源码开发
129
131
  - [使用指南](docs/user-guide.md)：首次使用、三种研究方式、语言
130
132
  - [详细说明](docs/details.md)：使用方式、数据包与保存位置、宿主与验证范围、开发
131
133
  - [结构与触发流程](docs/bookmark-research-architecture.md)
package/docs/distribution.md ADDED
@@ -0,0 +1,35 @@
1
+ # 发布与安装约定
2
+
3
+ 正式发布只使用 npm 的 `bookmark-research` 包。它包含共享 Python 运行时、Skill 和各宿主适配文件；不维护四份独立源码或四个发布版本。GitHub 用于源码、问题跟踪、版本说明及安装清单。
4
+
5
+ | 入口 | 插件内容来源 | 登记和缓存 |
6
+ | --- | --- | --- |
7
+ | `npx bookmark-research@latest install codex` | npm 发布包 → Codex 格式 | Codex 原生命令 |
8
+ | `npx bookmark-research@latest install claude` | 同一个 npm 包 → Claude 格式 | Claude Code 原生命令 |
9
+ | `npx bookmark-research@latest install pi` | 同一个 npm 包 → Pi 格式 | `pi install` |
10
+ | `npx bookmark-research@latest install dsh --profile web` | 同一个 npm 包 → DSH bundle | `dsh plugin --profile web add` |
11
+ | GitHub `install.sh` | 转交上述 npm 入口 | 所选宿主原生命令 |
12
+ | Codex GitHub marketplace | 清单中固定的 npm 版本 | Codex 直接下载和登记 |
13
+
14
+ 统一的是发布内容和来源。不同宿主需要不同清单，安装器只生成所需格式，用户配置、宿主登记及缓存仍交给宿主命令。Pi 的基础路径提供 Skill 和 CLI；其他宿主按各自适配提供 MCP。
15
+
16
+ 默认安装器记录 `npm:bookmark-research`（`latest`），更新时重新下载，不依赖已清理的 npx 缓存。显式 `--source npm:bookmark-research@VERSION` 会保留版本；要测试同一个固定发布版，在四个宿主使用相同参数。Codex 原生 marketplace 使用清单固定版本，跟随清单更新。需要新版安装器时运行 `npx bookmark-research@latest update`，或先更新全局 npm 安装。
17
+
18
+ 源码开发使用 `python3 scripts/install.py install --source PATH`，也可显式选择 Git 仓库和 `--ref`。旧 Git／本地安装保留来源，不静默转成 npm；切换时先用宿主命令处理旧登记。源码导出、ZIP 和测试包脚本保留为开发工具，CI 的发布候选只输出 npm `.tgz` 与 SHA-256 校验文件。历史 GitHub 附件不删除。
19
+
20
+ 发布顺序：修改源码版本并完成 CI，发布已经验证的 npm 包，确认 registry 可取得该版本，再更新 GitHub marketplace 的固定版本。未发布源码不能通过 npm 入口安装；需要先用源码入口测试。
21
+
22
+ 测试版使用 npm 的 `beta` 标签，并在 GitHub 标记为预发布；不会自动移动 npm 的 `latest` 标签。安装测试版时同时固定安装器与内容来源，例如 `npx bookmark-research@0.5.0-beta.4 install --source npm:bookmark-research@0.5.0-beta.4`。仅将 npx 改为 `@beta` 不会改变默认内容来源 `latest`；已固定的旧版安装也不会自动换成测试版。
23
+
24
+ ## 官方资料与项目实例
25
+
26
+ 2026-10-08 通过网页搜索并读取以下页面。它们支持多种发行方式，**没有“所有插件都只用 npm”的行业要求**；这里选择 npm 是为了减少本项目的发行分支。
27
+
28
+ - [OpenAI：Package your plugin](https://developers.openai.com/plugins/build/plugins)：marketplace 可指向本地、Git 或 npm；npm 内容下载不执行生命周期脚本。
29
+ - [Claude Code：Plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces#npm-packages)：支持 npm、GitHub、Git URL 和本地目录等来源。
30
+ - [Pi：Packages](https://pi.dev/docs/latest/packages)：支持 npm、Git 和本地路径；版本化 npm 来源保持固定。
31
+ - [DSH：Package and install a plugin](https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/publish)：支持 Git 安装，也建议发布已构建的 npm 包或 tarball，免去用户安装时构建。
32
+ - [Superpowers](https://github.com/obra/superpowers)：按宿主提供不同安装方式，Pi 使用 Git 仓库，Claude Code 使用 marketplace，并非 npm 唯一来源。
33
+ - [pi-skills](https://github.com/badlogic/pi-skills)：跨宿主 Skill 集合，文档仍提供 Git 克隆安装。
34
+
35
+ 这些资料说明“宿主安装方式不同”是正常的；本项目统一发布包后仍保留必要的宿主适配。
package/docs/installation.en.md CHANGED
@@ -6,23 +6,23 @@ Install the same plugin for English or Chinese use. See the [user guide](user-gu
6
6
 
7
7
  ## The `bookmark-research` command (recommended)
8
8
 
9
- After `npm install -g bookmark-research`, type `bookmark-research` to open a menu for preferences and API keys, service checks, installing into another client, updates and status. Subcommands work directly: `install [HOST...]`, `update`, `verify`, `setup`, `status`, `config show|set`, `doctor`. The npm package is only an entry point that runs the bundled Python installer and runtime, so Python 3.9+ is still required; it works on native Windows, macOS and Linux. Run the latest `main` with `npx github:Browser-bookmark-hub/Bookmark-Research`. Without arguments and without a terminal (agents/CI) it prints status JSON instead of opening the menu.
9
+ After `npm install -g bookmark-research`, type `bookmark-research` to open a menu for preferences and API keys, service checks, installing into another client, updates and status. Subcommands work directly: `install [HOST...]`, `update`, `verify`, `setup`, `status`, `config show|set`, `doctor`. npm is the single release package for all four hosts and includes the Python installer, runtime, Skill and adapters, so Python 3.9+ is still required; it works on native Windows, macOS and Linux. Use `npx bookmark-research@latest install HOST` for a release, and the Python source installer for unpublished development changes. Without arguments and without a terminal (agents/CI) it prints status JSON instead of opening the menu.
10
10
 
11
11
  <a id="one-command-codex-installation"></a>
12
12
 
13
13
  ## One-command installation
14
14
 
15
- Requirements: Bash, Git, Python 3.9+ with SQLite FTS5, and the selected host CLI (Codex, Claude Code, Pi or DSH). Other hosts do not need Codex installed.
15
+ Requirements: Bash, Node.js/npm, Python 3.9+ with SQLite FTS5, and the selected host CLI (Codex, Claude Code, Pi or DSH). Other hosts do not need Codex installed.
16
16
 
17
17
  ```sh
18
18
  curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
19
19
  ```
20
20
 
21
- The terminal wizard detects available CLIs and lets you choose one or more hosts: arrow keys move, Space toggles, Enter confirms, and detected hosts are preselected. It then asks each host's scope/project/profile and shows a summary to confirm before installing. It works with piped installation by reading `/dev/tty`; without a capable terminal, or with `BOOKMARK_RESEARCH_PLAIN=1`, it uses plain numbered prompts. If no supported CLI is found, the bootstrap stops before downloading. `--interactive` requires a terminal; `--non-interactive` never prompts. Without a terminal or an explicit host, the legacy default is Codex. Agents should pass `--host`.
21
+ The terminal wizard detects available CLIs and lets you choose one or more hosts: arrow keys move, Space toggles, Enter confirms, and detected hosts are preselected. It then asks each host's scope/project/profile and shows a summary to confirm before installing. It works with piped installation by reading `/dev/tty`; without a capable terminal, or with `BOOKMARK_RESEARCH_PLAIN=1`, it uses plain numbered prompts. The npm installer checks the selected host before native registration. `--interactive` requires a terminal; `--non-interactive` never prompts. Without a terminal or an explicit host, the legacy default is Codex. Agents should pass `--host`.
22
22
 
23
- The first installation follows `main` and uses the selected host's native registration commands. It does not use GitHub Release assets. Codex retains its own Git source/cache; other hosts receive complete persistent exports and installation receipts under `${XDG_DATA_HOME:-~/.local/share}/bookmark-research/installations/` (override with `--install-dir`). Temporary downloads can then be removed. Start a new host session to load the Skill and tools.
23
+ The first installation selects `npm:bookmark-research` (`latest`). All four hosts receive a clean export from that release through their native registration commands. The recorded source is the npm package and selector, not the temporary download or npx cache. `update` downloads that selector again; it does not need the original cache. GitHub serves this convenience script and source catalogs, not a separate release ZIP. Persistent host exports live under `${XDG_DATA_HOME:-~/.local/share}/bookmark-research/installations/` (override with `BOOKMARK_RESEARCH_INSTALL_DIR`; other hosts also accept `--install-dir`). Temporary downloads can then be removed. Start a new host session to load the Skill and tools.
24
24
 
25
- From a checkout, choose a host directly:
25
+ Choose a release host directly, even when running the bootstrap from a checkout:
26
26
 
27
27
  ```sh
28
28
  bash install.sh install --host codex
@@ -42,11 +42,11 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
42
42
  curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash -s -- verify --host codex --lang en
43
43
  ```
44
44
 
45
- `--lang en` selects English help/onboarding; `--lang zh` selects Chinese. The default `auto` checks `LC_ALL`, then `LC_MESSAGES`, then `LANG`. Chinese locales select Chinese; other or missing locales select English. The bootstrap forwards its selection through `BOOKMARK_RESEARCH_INSTALL_LANG`; an explicit Python `--lang` overrides that hint. Technical errors returned by Git, Codex and the runtime retain their original text. Installation language does not persist a research-language preference.
45
+ `--lang en` selects English help/onboarding; `--lang zh` selects Chinese. The default `auto` checks `LC_ALL`, then `LC_MESSAGES`, then `LANG`. Chinese locales select Chinese; other or missing locales select English. The bootstrap forwards `--lang` unchanged to the npm installer; `BOOKMARK_RESEARCH_INSTALL_LANG` remains an optional locale override. Technical errors returned by Git, Codex and the runtime retain their original text. Installation language does not persist a research-language preference.
46
46
 
47
47
  `--dry-run` reads registration and downloads/prepares a temporary export but does not install, save preferences or modify host registration. `--help` performs no download. `--timeout 60` limits each native command to 1–300 seconds; human input has no timeout. A service readiness timeout is configured separately.
48
48
 
49
- To select a previously published snapshot on a **first installation**, use `install --ref v0.2.0`. Repeat installations and updates retain the registered ref; an update does not advance a fixed tag. A historical tag uses its own installer and features, so older versions may retain their original onboarding language. The current bootstrap does not send unsupported language flags to historical installers.
49
+ For a pinned release on first installation, use `npx bookmark-research@latest install HOST --source npm:bookmark-research@0.5.0-beta.3`. The same selector is retained on reinstall/update. Without a pin, `latest` advances with npm publication. `--ref` belongs to explicit Git development sources only; it no longer chooses a release through the bootstrap. Existing Git/local installations retain their original source; they are not silently migrated to npm. To adopt npm, resolve the old registration using the host’s own commands first.
50
50
 
51
51
  The Codex branch manages `bookmark-research@bookmark-research`. If already installed through `personal` or another marketplace, keep using that source's update flow. Other hosts also reject conflicting sources and preserve existing settings. Claude receives a content-derived native version so changed local/main code refreshes its cache even when the release version is unchanged. Pi retains the persistent local package. DSH installs a relocatable native bundle in the selected profile.
52
52
 
@@ -77,9 +77,9 @@ Search/read adapters are included. Optional Exa Agent, Parallel Task and Tavily
77
77
 
78
78
  Optional service failures appear under `setup.needs_attention` and do not block local work or other providers. Native install or setup failures return nonzero, with installation and setup status reported separately. Historical versions without setup can still install without requesting that newer feature.
79
79
 
80
- ## Local checkout or ZIP
80
+ ## Source development and historical ZIPs
81
81
 
82
- Published ZIPs and test packs appear on [Releases](https://github.com/Browser-bookmark-hub/Bookmark-Research/releases). Local 0.4.0 validation is recorded separately in [validation](validation-0.4.0.md). Preserve hidden `.codex-plugin/` and `.agents/` directories when extracting.
82
+ GitHub [Releases](https://github.com/Browser-bookmark-hub/Bookmark-Research/releases) retain historical artifacts. New release candidates are npm `.tgz` packages. ZIP/export helpers remain available for local development and tests; they are not a second release channel. Preserve required plugin manifests when extracting a historical package.
83
83
 
84
84
  From a checkout or ZIP containing the installer:
85
85
 
@@ -90,21 +90,42 @@ python3 scripts/install.py verify --host codex --lang en
90
90
 
91
91
  Commands also work from another directory using an absolute script path. Quote paths containing spaces. The installer locates its source from its own file location.
92
92
 
93
+ Local checkouts, npm packages, extracted ZIPs and new Git sources are exported before Codex registration. Personal `.claude/`, `.codex/`, `.pi/`, `.agent/`, `.git/` and old build artifacts are excluded; plugin declarations and runtime content remain. The original source is recorded beside the persistent export, and `update` exports it again. Installation compares the native cache file list with the clean export. Keep local sources and the persistent export for future updates. Git origins record the repository and selected ref: branches advance on update; tags and commits remain selected. Reinstalling without `--ref` retains the saved ref; an explicit different ref is rejected.
94
+
95
+ An older installation registered directly from a local source migrates through native `marketplace remove/add` and `plugin add` commands only when its catalog contains this plugin alone. The original source stays the same; user configuration is never edited by the installer. `--dry-run` previews the migration. Conflicting sources and catalogs containing other plugins are preserved for resolution in Codex.
96
+
97
+ For an older Git marketplace, Codex retains its registration and ref. The installer runs native `marketplace upgrade`, exports that fetched checkout, and passes the clean path through per-command `-c` overrides to native `plugin add`. Those overrides do not rewrite the Git registration. This also preserves pins whose ref is absent from native listing JSON. This fallback applies to historical catalogs that point at their repository root. The current release catalog selects an npm package; native updates retain that package source. A Git checkout or GitHub source archive can contain development files; it is not the plugin cache.
98
+
93
99
  | Command | Behavior |
94
100
  | --- | --- |
95
101
  | `install` | Installs or reinstalls the script's local source. |
96
102
  | `install --source PATH` | Selects another valid local marketplace root. |
97
- | `install --source owner/repo --ref TAG` | Registers the chosen Git ref on the first installation. |
103
+ | `install --source owner/repo --ref TAG` | Exports the chosen Git ref and registers the clean bundle. |
98
104
  | `install --dry-run` | Prints the planned commands after checking registration. |
99
- | `update` | Refreshes the registered Git source/ref, or reinstalls current local files. |
105
+ | `install --source npm:bookmark-research[@VERSION]` | Installs the shared npm release for the selected host. |
106
+ | `update` | Re-fetches the recorded npm selector, refreshes the Git source/ref, or reinstalls local files. |
100
107
  | `verify` | Checks enabled registration, cache version, FTS5 and MCP initialization/tool discovery. |
101
108
 
102
109
  The Python installer accepts the same host/setup flags. `verify --installed-path PATH` is Codex-only. Verification uses an isolated store, does not import bookmarks, and does not test provider authentication. Stdout stays JSON; prompts use the terminal and diagnostics use stderr. The setup stage persists only selected preferences; unreadable settings are reported and preserved.
103
110
 
104
- The native commands for this repository's explicit marketplace are:
111
+ ### Native Codex installation of the published release
112
+
113
+ The repository marketplace points to the explicitly pinned `bookmark-research@0.5.0-beta.3` npm package. Codex downloads that package without lifecycle scripts, then owns registration and caching. Adding the repository installs the published release, including its released Skill; it does not install unpublished source changes from `main`.
114
+
115
+ ```sh
116
+ codex plugin marketplace add Browser-bookmark-hub/Bookmark-Research --ref main
117
+ codex plugin add bookmark-research@bookmark-research
118
+ ```
119
+
120
+ For subsequent native updates, run `codex plugin marketplace upgrade bookmark-research`, then `codex plugin add bookmark-research@bookmark-research`. The pinned package changes only when the catalog is updated after that version is published; a frozen Git catalog retains its selected npm version. `bookmark-research update codex` also preserves a native release source. npm and a working `python3` with SQLite FTS5 must be on the host's PATH. On Windows without a working `python3`, use the installer described above to pin the detected interpreter.
121
+
122
+ To install the current checkout, use `python3 scripts/install.py install --source /absolute/path/to/checkout`. To install current source from Git, use `install --source owner/repo --ref BRANCH_OR_TAG`. Both prepare clean exports of the selected source. If this marketplace is already registered, keep its existing source or explicitly choose the intended source in Codex first.
123
+
124
+ To install current source manually with native commands, first export to a new persistent directory. Exported bundles have a local marketplace pointing at their own clean root, so this path does not fetch the published npm release:
105
125
 
106
126
  ```sh
107
- codex plugin marketplace add .
127
+ python3 scripts/export_bundle.py --format codex --output /absolute/path/to/clean/bookmark-research
128
+ codex plugin marketplace add /absolute/path/to/clean/bookmark-research
108
129
  codex plugin add bookmark-research@bookmark-research
109
130
  codex plugin list --json
110
131
  ```
@@ -160,7 +181,7 @@ python3 scripts/install.py install --host dsh --profile web
160
181
  python3 scripts/install.py verify --host dsh --profile web
161
182
  ```
162
183
 
163
- The installer exports a relocatable `dsh.bundle` and calls `dsh plugin --profile web add PATH`. `dsh plugin` delegates to pnpm, so install it first (`npm install -g pnpm` or `corepack enable pnpm`); without it the installer stops before creating a profile and the wizard shows DSH as unavailable. The bundle registers the shared Skill and resolves Python/MCP paths from the installed module. The selected profile must provide the Skill registry and official MCP client. For manual distribution, export with `--format dsh` and install the stable export using that native command. The legacy `cordis.patch.yml` still contains absolute paths and requires separate Skill discovery. Workflow execution separately requires the host service/engine; `hosts/dsh/workflow-call.py --research-id RID --run-key KEY` prepares a call without launching it.
184
+ The installer exports a relocatable `dsh.bundle` and calls `dsh plugin --profile web add PATH`. `dsh plugin` delegates to pnpm, so install it first (`npm install -g pnpm` or `corepack enable pnpm`); without it the installer stops before creating a profile and the wizard shows DSH as unavailable. The bundle registers the shared Skill and resolves Python/MCP paths from the installed module. The selected profile must provide the Skill registry and official MCP client. For local development, export with `--format dsh` and install the stable export using that native command. The legacy `cordis.patch.yml` still contains absolute paths and requires separate Skill discovery. Workflow execution separately requires the host service/engine; `hosts/dsh/workflow-call.py --research-id RID --run-key KEY` prepares a call without launching it.
164
185
 
165
186
  ### Agent Plugins 1.0.0
166
187
 
package/docs/installation.md CHANGED
@@ -4,25 +4,25 @@
4
4
 
5
5
  执行 Skill 和方法参考以英文维护，配完整中文阅读版及双语宿主提示说明，见[指令索引](instructions.md)。安装导出会携带这些文件。
6
6
 
7
- Bookmark Research 使用 Python 3.9+ 标准库和 SQLite FTS5。先安装 Python 与要使用的客户端；运行 `python3 src/cli.py doctor` 可以离线检查 Python 和 FTS5。当前 checkout 的四宿主工作流及验证范围见 [宿主兼容说明](harness-compatibility.md)。下文 v0.2.0 Release 链接是历史发布产物，不包含新增宿主脚本；使用这些工作流时从当前源码导出。
7
+ Bookmark Research 使用 Python 3.9+ 标准库和 SQLite FTS5。先安装 Python 与要使用的客户端；运行 `python3 src/cli.py doctor` 可以离线检查 Python 和 FTS5。当前 checkout 的四宿主工作流及验证范围见 [宿主兼容说明](harness-compatibility.md)。正式发布统一使用 npm；源码与历史 ZIP 的本地验证仍可使用导出器。
8
8
 
9
9
  ## `bookmark-research` 命令（推荐）
10
10
 
11
- `npm install -g bookmark-research` 之后在终端输入 `bookmark-research`，即可打开主菜单：修改配置与 API Key、检查服务、安装到其他宿主、更新、查看状态。也可以直接带子命令：`install [宿主…]`、`update`、`verify`、`setup`、`status`、`config show|set`、`doctor`。npm 包只是入口，内部调用包内的 Python 安装器和运行时，因此仍需 Python 3.9+；Windows 原生、macOS、Linux 都可以用。想用最新 `main` 可运行 `npx github:Browser-bookmark-hub/Bookmark-Research`。不带参数且不在终端中运行时（agent／CI），它只输出状态 JSON，不弹菜单。
11
+ `npm install -g bookmark-research` 之后在终端输入 `bookmark-research`，即可打开主菜单：修改配置与 API Key、检查服务、安装到其他宿主、更新、查看状态。也可以直接带子命令：`install [宿主…]`、`update`、`verify`、`setup`、`status`、`config show|set`、`doctor`。npm 是四个宿主共用的唯一正式发布包，包含 Python 安装器、运行时、Skill 和适配文件，因此仍需 Python 3.9+；Windows 原生、macOS、Linux 都可以用。发布版使用 `npx bookmark-research@latest install HOST`；未发布源码使用 Python 源码安装器。不带参数且不在终端中运行时（agent／CI），它只输出状态 JSON，不弹菜单。
12
12
 
13
13
  ## 一条命令引导安装
14
14
 
15
- 已安装 Bash、Git、Python 3.9+（含 SQLite FTS5）和要使用的宿主 CLI 后，可以在任意工作目录执行；其他宿主不需要安装 Codex：
15
+ 已安装 Bash、Node.js/npm、Python 3.9+（含 SQLite FTS5）和要使用的宿主 CLI 后，可以在任意工作目录执行；其他宿主不需要安装 Codex：
16
16
 
17
17
  ```sh
18
18
  curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash
19
19
  ```
20
20
 
21
- 终端向导检测可用 CLI，可多选 Codex、Claude Code、Pi、DSH：方向键移动、空格勾选、回车确认，已检测到的宿主默认勾选；随后逐个询问作用域／项目／profile，并显示摘要确认后再安装。`curl | bash` 从 `/dev/tty` 读取回答，不会误读脚本或 Agent 的输入；终端不支持或设置 `BOOKMARK_RESEARCH_PLAIN=1` 时改用普通编号提示。未找到任何受支持的 CLI 时，引导脚本在下载前停止。`--interactive` 要求终端，`--non-interactive` 不询问；没有终端且未指定宿主时保留默认 Codex 的旧行为，Agent 应显式传入 `--host`。
21
+ 终端向导检测可用 CLI，可多选 Codex、Claude Code、Pi、DSH：方向键移动、空格勾选、回车确认，已检测到的宿主默认勾选；随后逐个询问作用域／项目／profile，并显示摘要确认后再安装。`curl | bash` 从 `/dev/tty` 读取回答，不会误读脚本或 Agent 的输入；终端不支持或设置 `BOOKMARK_RESEARCH_PLAIN=1` 时改用普通编号提示。npm 安装器会在原生登记前检查所选宿主。`--interactive` 要求终端，`--non-interactive` 不询问；没有终端且未指定宿主时保留默认 Codex 的旧行为，Agent 应显式传入 `--host`。
22
22
 
23
- 首次安装跟随 `main`，通过所选宿主的原生命令登记与验证。Codex 保留自己的 Git 源码／缓存；其他宿主的完整导出和安装记录持久保存在 `${XDG_DATA_HOME:-~/.local/share}/bookmark-research/installations/`，可用 `--install-dir` 改位置。随后清理临时下载目录，安装后新建宿主会话。
23
+ 首次安装选择 `npm:bookmark-research`（`latest`）。四个宿主都从该发布包导出所需格式，再由原生命令登记与验证。安装记录保存 npm 包名和版本选择，不保存临时下载或 npx 缓存路径；更新会重新取得同一选择器指向的发布包。各宿主的持久导出保存在 `${XDG_DATA_HOME:-~/.local/share}/bookmark-research/installations/`；可用 `BOOKMARK_RESEARCH_INSTALL_DIR` 改位置，其他宿主也支持 `--install-dir`。随后清理临时下载目录，安装后新建宿主会话。
24
24
 
25
- 在 checkout 中也可直接选择目标：
25
+ 即使在 checkout 中运行以下脚本，默认也安装 npm 发布版：
26
26
 
27
27
  ```sh
28
28
  bash install.sh install --host codex
@@ -43,7 +43,7 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
43
43
  python3 scripts/install.py install --lang zh
44
44
  ```
45
45
 
46
- `--lang en` 选择英文，`--lang auto` 恢复自动判断。Shell 用 `BOOKMARK_RESEARCH_INSTALL_LANG` 向 Python 安装器传递选择；Python 的显式 `--lang` 优先。该选项只影响安装引导，不保存研究语言设置；Git、Codex 和运行时的技术诊断保留原文。固定到旧 tag 时使用该版本的安装器，旧版本可能仍显示当时的引导语言。
46
+ `--lang en` 选择英文，`--lang auto` 恢复自动判断。Shell 原样转发 `--lang`；`BOOKMARK_RESEARCH_INSTALL_LANG` 仍可覆盖默认 locale。该选项只影响安装引导，不保存研究语言设置；Git、Codex 和运行时的技术诊断保留原文。
47
47
 
48
48
  更新、检查和预览使用同一入口：
49
49
 
@@ -55,17 +55,17 @@ curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Resea
55
55
 
56
56
  `--dry-run` 仍会下载安装器、读取登记和准备临时导出，但不安装、不保存偏好或修改宿主登记。`--help` 只显示帮助；curl 自身仍需下载入口。`--timeout 60` 限制每条原生命令，范围 1–300 秒，不限制人类输入；服务检查另有超时设置。使用本地 `scripts/install.py verify --host HOST` 可省去 bootstrap 下载。
57
57
 
58
- 需要固定版本时，在**首次登记来源**时选择 tag 或 commit：
58
+ 需要固定发布版时，在首次安装中指定 npm 版本：
59
59
 
60
60
  ```sh
61
- curl -fsSL https://raw.githubusercontent.com/Browser-bookmark-hub/Bookmark-Research/main/install.sh | bash -s -- install --ref v0.2.0
61
+ npx bookmark-research@latest install claude --source npm:bookmark-research@0.5.0-beta.3
62
62
  ```
63
63
 
64
- `--ref` 同时选择 Git 中的安装器和待安装插件，所选版本须包含 `scripts/install.py`（从 v0.2.0 开始）。再次安装时省略 `--ref`；已登记的分支、tag 或 commit 会保留。`update` 也保持该 ref，固定 tag 不会自动升级到其他版本。默认跟随 `main` 适合接收开发更新，固定 tag/commit 适合复现。
64
+ 再次安装和更新保留该选择器。默认 `latest` 随 npm 发布更新；显式版本保持固定。`--ref` 只用于显式 Git 开发来源，不再通过 bootstrap 选择发布版。已有 Git／本地安装保留原来源；如需转为 npm，先通过宿主命令处理旧登记，避免静默切换开发环境。
65
65
 
66
66
  Codex 分支管理 `bookmark-research@bookmark-research`。已通过 `personal` 等来源安装时沿用原更新流程。其他宿主也会检查来源冲突并保留原有设置。Claude 用内容派生的原生版本刷新缓存，同一发布版本下的源码变化也能生效；Pi 使用持久本地包；DSH 向指定 profile 安装可搬移 bundle。更新失败保留原包并记录待验证状态，之后可重试安装／更新。
67
67
 
68
- **Git tag、GitHub Release 和安装脚本是三个独立部分。** Git tag 标记源码版本；Release 提供说明、ZIP 和校验文件；`install.sh` 负责取得源码并安装。上述命令直接使用 Git，不访问 Release API 或 ZIP 资产，只有仓库也能安装和更新。
68
+ **npm 是正式发布来源。** GitHub 提供源码、版本说明与安装清单；`install.sh` 调用 npm 入口。CI 只生成 npm `.tgz` 发布候选及校验文件。ZIP 与各宿主导出器用于本地开发、测试和历史兼容。见[发布约定与官方依据](distribution.md)。
69
69
 
70
70
  ## 向导与就绪检查
71
71
 
@@ -94,19 +94,17 @@ Agent 可使用 `install --host pi --non-interactive --preferences FILE --skip-c
94
94
 
95
95
  可选服务故障显示在 `setup.needs_attention`，不阻塞本地查询或其他服务。原生安装或配置失败返回非零，JSON 分别报告安装与 setup 状态。未主动请求新版向导时，缺少 setup 的历史版本仍可正常安装。
96
96
 
97
- ## 取得代码或 ZIP
97
+ ## 源码开发与历史 ZIP
98
98
 
99
- 以下下载示例固定到已发布的 [v0.2.0 Release](https://github.com/Browser-bookmark-hub/Bookmark-Research/releases/tag/v0.2.0)：[插件 ZIP](https://github.com/Browser-bookmark-hub/Bookmark-Research/releases/download/v0.2.0/bookmark-research-0.2.0.zip) 和用于离线验证的 [测试包](https://github.com/Browser-bookmark-hub/Bookmark-Research/releases/download/v0.2.0/bookmark-research-test-pack-0.2.0.zip)。其他已发布版本以 [Releases](https://github.com/Browser-bookmark-hub/Bookmark-Research/releases) 为准；本地 0.4.0 构建及验证见 [验证记录](validation-0.4.0.md)。两个包均包含 `MANIFEST.sha256`，Release 另提供 ZIP 的 `SHA256SUMS`。解压时保留 `.codex-plugin/` 和 `.agents/` 等隐藏目录，并把目录放在一个稳定位置。
100
-
101
- 仓库地址：<https://github.com/Browser-bookmark-hub/Bookmark-Research>。复现该历史快照使用 `v0.2.0` 标签；`main` 跟随开发更新。ZIP 是可选的分发形式，也可以直接克隆源码：
99
+ GitHub [Releases](https://github.com/Browser-bookmark-hub/Bookmark-Research/releases) 中的旧附件保留历史用途。新发布以 npm 为准，不再另发插件 ZIP 或测试包。仓库的 ZIP／导出脚本仍可用于本地验证。
102
100
 
103
101
  ```sh
104
- git clone --branch v0.2.0 https://github.com/Browser-bookmark-hub/Bookmark-Research.git
102
+ git clone https://github.com/Browser-bookmark-hub/Bookmark-Research.git
105
103
  cd Bookmark-Research
106
- python3 src/cli.py doctor
104
+ python3 scripts/install.py install --source . --host codex
107
105
  ```
108
106
 
109
- 请在包含 `scripts/install.py` 的 0.2.0 或后续版本 checkout、ZIP 中使用下方安装入口。旧提交仍可使用原生 Codex 命令或各自版本的导出器。
107
+ 该 Python 入口显式安装当前源码。历史解压目录须包含安装器及必要插件清单。
110
108
 
111
109
  ## Codex CLI 安装
112
110
 
@@ -119,6 +117,8 @@ python3 scripts/install.py verify
119
117
 
120
118
  安装器会调用 Codex 原生 `plugin marketplace add`、`plugin add` 和 JSON 查询接口；Codex 管理其配置和安装缓存。当前 `main` 的安装器在成功后显示当前配置、首次提问模板和配置查询命令；已有配置会照实显示，读取失败时明确提示修正。stdout 保持 JSON，面向用户的引导写到 stderr，管道执行时也会显示。v0.2.0 固定快照保留当时的安装输出。
121
119
 
120
+ 本地源码、npm 包、解压目录和新 Git 来源均先导出干净插件目录，排除个人 `.claude/`、`.codex/`、`.pi/`、`.agent/`、`.git/` 和旧产物；仅保留插件所需声明和内容。导出旁记录原来源，`update` 从原来源重新导出；安装后对比宿主缓存的文件清单。本地来源需保留原源码和持久导出目录。Git 来源记录仓库和 ref：分支更新跟随分支，tag／commit 保持固定；重复安装省略 `--ref` 时沿用记录，显式指定不同 ref 时拒绝切换。
121
+
122
122
  安装完成后新建 Codex thread，以载入新 Skill 和 MCP 工具。Python 必须能以 `python3` 被 Codex 的 MCP 子进程找到。需要支持这些子命令和 `--json` 的 Codex CLI；本仓库验证环境为 0.153.4。
123
123
 
124
124
  安装入口从自身文件位置查找源码，因此也可以在其他工作目录运行。含空格或中文的路径使用引号：
@@ -131,15 +131,16 @@ python3 "/absolute/path/Bookmark Research/scripts/install.py" install
131
131
  | --- | --- |
132
132
  | `install` | 安装当前脚本所属目录；可重复执行 |
133
133
  | `install --source /absolute/path/to/source` | 安装另一个有效的本地 marketplace 根目录 |
134
- | `install --source owner/repo --ref TAG_OR_COMMIT` | 让 Codex 安装指定 Git 来源；占位符需替换为实际已存在的版本 |
134
+ | `install --source owner/repo --ref TAG_OR_COMMIT` | 导出指定 Git ref，再由 Codex 安装干净目录；占位符需替换为实际版本 |
135
135
  | `install --dry-run` | 读取现有注册状态，打印计划，不运行安装命令 |
136
- | `update` | 更新当前已安装来源；Git 源先执行 `marketplace upgrade`，本地源重新安装其当前文件 |
136
+ | `install --source npm:bookmark-research[@VERSION]` | 为所选宿主安装同一个 npm 发布包 |
137
+ | `update` | 重新下载已登记 npm 选择器，或更新原 Git／本地开发来源 |
137
138
  | `update --dry-run` | 查看现有来源的更新计划 |
138
139
  | `verify` | 检查已启用注册、安装缓存版本、FTS5、MCP 初始化和工具发现 |
139
140
 
140
141
  每个动作可指定 `--codex /absolute/path/to/codex` 和 `--timeout 60`。输出为 JSON；验证或前置步骤失败时返回非零退出码。`verify --installed-path PATH` 可明确指定 `codex plugin add --json` 返回的 `installedPath`，用于 Codex 缓存布局发生变化的情况。
141
142
 
142
- 安装器不会把已有同名 marketplace 自动切换到另一个 Git 仓库或本地目录。遇到来源冲突，先用 `codex plugin marketplace list --json` 和 `codex plugin list --json` 核对要保留的来源，再在 Codex 中处理来源选择。这样不会因更新本插件而连带移除 marketplace 中的其他插件。
143
+ 安装器不会把已有同名 marketplace 切换到另一个原始来源。旧版直接登记源码目录的安装，仅在市场中只有本插件时，通过 Codex 原生 `marketplace remove/add` 迁移到同一来源的干净导出，再执行 `plugin add`；不手写用户配置。`--dry-run` 可预览这些命令。含其他插件或来源冲突时保留现状，先用 `codex plugin marketplace list --json` 和 `codex plugin list --json` 核对来源，再在 Codex 中处理。
143
144
 
144
145
  `--ref` 用于首次注册 Git marketplace。已有 Git 来源再次安装时省略 `--ref`，保持其原注册版本；如要换 tag 或分支，先在 Codex 中处理来源变更。当前原生 JSON 不返回已注册 ref，安装器不会把“同一个仓库”推断成“同一个固定版本”。
145
146
 
@@ -147,15 +148,29 @@ python3 "/absolute/path/Bookmark Research/scripts/install.py" install
147
148
 
148
149
  ## 使用 Codex 原生命令
149
150
 
150
- 如果不使用本仓库的安装入口，在本地 marketplace 根目录运行：
151
+ 旧版 Git marketplace 由 Codex 保留原登记和 ref。安装器先执行原生 `marketplace upgrade`，从宿主实际获取的 checkout 导出干净目录，再通过本次命令的 `-c` 参数将目录交给原生 `plugin add`；参数不会改写 Git 登记，也不需要猜测原生列表未返回的 ref。这条回退路径适用于仍指向仓库根目录的历史 catalog。当前发行 catalog 指向 npm 包，原生更新保留该发布来源。Git checkout 和 GitHub 自动生成的源码压缩包可以含开发文件，它们不是插件缓存。
152
+
153
+ 当前仓库的 marketplace 固定指向已发布的 `bookmark-research@0.5.0-beta.3` npm 包。Codex 下载该包，不执行生命周期脚本，再自行登记和缓存。直接添加 GitHub 仓库会安装发布版及其已发布 Skill，不会安装 `main` 尚未发布的源码改动：
154
+
155
+ ```sh
156
+ codex plugin marketplace add Browser-bookmark-hub/Bookmark-Research --ref main
157
+ codex plugin add bookmark-research@bookmark-research
158
+ ```
159
+
160
+ 后续先执行 `codex plugin marketplace upgrade bookmark-research`，再执行 `codex plugin add bookmark-research@bookmark-research`。只有发布新 npm 版本并更新 catalog 后，包版本才变化；固定 Git catalog 会保留其中选定的 npm 版本。`bookmark-research update codex` 也会保留原生发布来源。宿主 PATH 需有 npm 和可用的 `python3`（含 SQLite FTS5）；Windows 没有可用 `python3` 时，使用上方安装器固定检测到的解释器。
161
+
162
+ 要安装当前 checkout，使用 `python3 scripts/install.py install --source /absolute/path/to/checkout`；要安装指定 Git 源码，使用 `install --source owner/repo --ref BRANCH_OR_TAG`。两者都会对所选源码做干净导出。已登记同名 marketplace 时，继续使用原来源，或先在 Codex 中明确选择要使用的来源。
163
+
164
+ 如果希望通过原生命令手动安装当前源码，先导出到新的持久目录，再交给 Codex。导出目录的 marketplace 指向自身的干净根目录，不会改为下载 npm 发布版：
151
165
 
152
166
  ```sh
153
- codex plugin marketplace add .
167
+ python3 scripts/export_bundle.py --format codex --output /absolute/path/to/clean/bookmark-research
168
+ codex plugin marketplace add /absolute/path/to/clean/bookmark-research
154
169
  codex plugin add bookmark-research@bookmark-research
155
170
  codex plugin list --json
156
171
  ```
157
172
 
158
- 固定安装 v0.2.0 时，使用 `codex plugin marketplace add Browser-bookmark-hub/Bookmark-Research --ref v0.2.0`，再执行 `codex plugin add bookmark-research@bookmark-research`。`--ref main` 跟随开发分支，其他固定版本使用实际已存在的标签或 commit。已有同名来源先按上文核对其注册状态。
173
+ 历史 tag 的 catalog 保留历史行为，可能仍指向整个源码目录；需要该版本源码且保持安装干净时，使用本安装器的 `install --source owner/repo --ref TAG`，或先导出再原生安装。
159
174
 
160
175
  原生命令依据 [OpenAI plugin packaging documentation](https://developers.openai.com/plugins/build/plugins) 和 [Codex CLI reference](https://developers.openai.com/codex/cli/reference#codex-plugin)。默认个人 marketplace `~/.agents/plugins/marketplace.json` 是 Codex 的隐式发现机制；上面的 `marketplace add` 用于本仓库自己的显式 marketplace，二者不要混淆。
161
176
 
package/docs/release-notes-0.5.0-beta.4.md ADDED
@@ -0,0 +1,39 @@
1
+ # Bookmark Research 0.5.0 beta 4
2
+
3
+ **Beta / 测试版.** Published on the npm `beta` channel. The npm `latest` tag is unchanged.
4
+
5
+ ## Install this beta
6
+
7
+ Pin both the installer and the plugin content so the default `latest` source cannot select an earlier release:
8
+
9
+ ```sh
10
+ npx bookmark-research@0.5.0-beta.4 install --source npm:bookmark-research@0.5.0-beta.4
11
+ ```
12
+
13
+ Choose Codex, Claude Code, Pi or DSH in the installer, or supply the host explicitly:
14
+
15
+ ```sh
16
+ npx bookmark-research@0.5.0-beta.4 install codex --source npm:bookmark-research@0.5.0-beta.4
17
+ npx bookmark-research@0.5.0-beta.4 install claude --source npm:bookmark-research@0.5.0-beta.4
18
+ npx bookmark-research@0.5.0-beta.4 install pi --source npm:bookmark-research@0.5.0-beta.4
19
+ npx bookmark-research@0.5.0-beta.4 install dsh --profile web --source npm:bookmark-research@0.5.0-beta.4
20
+ ```
21
+
22
+ Existing installations retain their source and version selection. The GitHub Codex marketplace will point to this npm version after publication; existing managed Git/local or pinned npm installs are not silently migrated.
23
+
24
+ ## Changes
25
+
26
+ - **One npm release for all four hosts.** The shell bootstrap delegates to the npm launcher. Host adapters generate the required format and use each host's native registration commands. Pi's base installation provides the Skill and CLI; MCP availability follows each host adapter.
27
+ - **Durable installation sources.** npm installs retain a managed export and source receipt, so updates do not depend on an expired temporary npx directory. Explicit version pins and existing Git/local origins are preserved.
28
+ - **Clean payloads.** npm and Codex's native npm installation exclude personal agent state, development tests and build artifacts. Only the required `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` hidden metadata files are included.
29
+ - **Actionable Canvas Skill.** The main Skill explains when to query locally, read a known URL, investigate a question or retain a research report. It reads `.canvas` layout before selecting card context, preserves independent text cards, distinguishes directed and undirected edges, and avoids double-counting permanent copy anchors.
30
+ - **Large Canvas guidance.** The Skill describes compact local JSON extraction when a whole layout is too large. No graph service, dependency or new MCP tool is added.
31
+ - **Release checks.** CI covers Python 3.9/3.12 on Linux, macOS and Windows, native Codex installation/update, all four exported host formats and npm package contents. Release candidates are npm `.tgz` files with SHA-256 checksums.
32
+
33
+ ## Validation and limits
34
+
35
+ The implementation passed the existing 495-test local suite (one opt-in test skipped) and all 10 CI jobs before this version bump. A local Canvas sample passed 14 comparisons between original JSON and actual MCP responses, including bookmark metadata, geometry, group membership and copy identity; original files remained unchanged. Nine MCP operations were exercised in that sample session.
36
+
37
+ Web reading was also exercised: one URL failed through all configured fallback readers; another returned a partial excerpt that could be retrieved from the local archive. This release does not guarantee webpage availability, complete extraction, interpretation of unstated user intent or large-canvas performance. End-to-end Skill triggering across every host and every MCP operation is not established by these tests.
38
+
39
+ The release artifact is the tested npm tarball, also attached here with its checksum. GitHub's automatically generated source archives are source checkouts, not the installation package. Historical ZIP attachments remain available on earlier releases.