# 发布与安装约定

正式发布只使用 npm 的 `bookmark-research` 包。它包含共享 Python 运行时、Skill 和各宿主适配文件；不维护四份独立源码或四个发布版本。GitHub 用于源码、问题跟踪、版本说明及安装清单。GitHub Release 可选，仅保留版本说明和 npm 链接，不再附安装包、测试包或配套校验文件；历史附件已备份撤下。

| 入口 | 插件内容来源 | 登记和缓存 |
| --- | --- | --- |
| `npx bookmark-research@latest install codex` | npm 发布包 → Codex 格式 | Codex 原生命令 |
| `npx bookmark-research@latest install claude` | 同一个 npm 包 → Claude 格式 | Claude Code 原生命令 |
| `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 直接下载和登记 |

统一的是发布内容和来源。不同宿主需要不同清单，安装器只生成所需格式，用户配置、宿主登记及缓存仍交给宿主命令。Claude Code、Codex 和 DSH 按各自适配提供 MCP 或 Skill。

默认安装器保留当前启动包的内容快照，`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 压缩包是源码快照，不能单独关闭，不作为安装包。

发布顺序：修改源码版本并完成 CI，发布已经验证的 npm 包，确认 registry 可取得该版本，再更新 GitHub marketplace 的固定版本。未发布源码不能通过 npm 入口安装；需要先用源码入口测试。

候选版本在 `release/` 分支同步三个版本清单并运行 CI。该分支的 registry 集成测试使用当前已发布渠道版本，源码测试、原生安装测试和 npm 打包检查仍验证候选内容；主分支的 registry 测试始终验证 marketplace 固定版本。发布通过 CI 的 npm 包并核验 registry 后，再将候选分支合入主分支，避免默认安装清单提前指向未发布版本。

发布时保持 npm 的 `latest` 标签始终指向最新构建，用户直接使用 `npx bookmark-research install`（或 `npx bookmark-research@latest install`）即可默认安装最新版。启动器会自动读取当前运行包版本并固定内容来源，无需重复指定 `--source`。已存在的宿主配置支持无缝覆盖升级。

## 官方资料与项目实例

2026-10-08 通过网页搜索并读取以下页面。它们支持多种发行方式，**没有“所有插件都只用 npm”的行业要求**；这里选择 npm 是为了减少本项目的发行分支。

- [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 和本地目录等来源。
- [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)：按宿主提供不同安装方式；Claude Code 使用 marketplace，并非 npm 唯一来源。

这些资料说明“宿主安装方式不同”是正常的；本项目统一发布包后仍保留必要的宿主适配。