Screenpipe SDK 发布运行手册：npm、SwiftPM 与 Cargo 三通道的完整发布流程-平芜编程栈

Screenpipe SDK 发布运行手册：npm、SwiftPM 与 Cargo 三通道的完整发布流程

【免费下载链接】screenpipeYC (S26) | Open Computer History | Record your screen continuously locally and provide context to your agents (Claude, Codex, Openclaw, Hermes, Runner...)项目地址: https://gitcode.com/GitHub_Trending/sc/screenpipe

Screenpipe SDK 是 screenpipe 开源仓库中面向 Electron、Swift、Tauri 与 Node 应用的商业化屏幕录制 SDK（见 packages/sdk/README.md），其交付方式横跨 npm、SwiftPM 与 Cargo 三条分发通道。本文以仓库内的 SDK 发布运行手册为骨架，结合 sdk-release.yml 工作流、package.json 与 Cargo.toml 等源码级证据，完整拆解三通道的发布前置条件、本地 dry-run、自动化发布步骤、版本一致性校验机制，以及 Cargo 通道当前被刻意封锁的深层原因与未来可选路径。读完本文，你将能独立完成 SDK 的 npm 与 SwiftPM 发布，并准确判断 Rust crate 何时具备发布条件。

SDK 的三个分发面与"发布铁律"

运行手册开宗明义：SDK 同时面向三个分发生态，各有其形态：

分发通道	产物形态	消费方
npm	`@screenpipe/sdk`+ napi-rs 生成的原生平台包	Electron、Node，以及 Swift/Tauri 辅助层经由的 Node bridge
SwiftPM	根目录含`Package.swift`的 Git tag 仓库	苹果生态应用
Cargo	Rust crate（当前树内不可发布）	Rust/Tauri 原生集成

其中 npm 是主通道——它是 Electron、Node 的主分发面，也是 Swift 桥接层与 Tauri 前端 helper 所依赖的底层。

手册同时立下一条铁律：绝不要从未合并的分支发布。任何公开发布前，必须先在干净检出（clean checkout）上合并 SDK 相关 PR、拉取最新main，并跑完下面的检查。这条约束与工作流中的validate阶段（见后文）共同构成"发布前防线"。

npm 通道：从本地 dry-run 到 GitHub Actions 手动发布

人工前置条件

发布@screenpipescope 下的包之前，需要满足三类前置：

拥有@screenpipescope 的 npm 发布权限；
若走 GitHub Actions 发布，仓库需配置具备发布权限的NPM_TOKENsecret；
按 npm 发布规则配置 2FA 或 granular token；
package.json、Cargo.toml以及全部optionalDependencies必须指向同一个版本号。

第四点尤为关键。查看 package.json 可以看到版本一致性的实物形态——publishConfig声明access: "public"与官方 registry，optionalDependencies中的四个平台包全部锁死为0.4.3，与根包版本完全一致：

"optionalDependencies": { "@screenpipe/sdk-darwin-x64": "0.4.3", "@screenpipe/sdk-darwin-arm64": "0.4.3", "@screenpipe/sdk-win32-x64-msvc": "0.4.3", "@screenpipe/sdk-win32-arm64-msvc": "0.4.3" }

这四个包正是 napi-rs 在 package.json 的napi.triples.additional中声明的那四个平台目标。

本地 dry-run：发布前的第一道闸

手册给出的本地验证命令组合：

cd packages/sdk bun install --frozen-lockfile cargo metadata --manifest-path Cargo.toml --format-version 1 --no-deps npm pack --dry-run --ignore-scripts

bun install --frozen-lockfile严格按 bun.lock 锁定依赖安装，防止锁文件与依赖漂移；
cargo metadata --format-version 1 --no-deps校验 Rust manifest 可被 cargo 正确解析（不拉取依赖）；
npm pack --dry-run --ignore-scripts模拟打包，--ignore-scripts跳过生命周期脚本，只确认产物清单（对应 package.json 的files白名单，其中包含bridges、electron、session、tauri、Sources、Package.swift等发布所需内容）。

手动发布工作流（GitHub Actions）

手册推荐通过 .github/workflows/sdk-release.yml 中的Release SDK工作流执行发布，操作步骤为：

打开 GitHub Actions 页面；
运行Release SDK（workflow_dispatch手动触发）；
将version设为已提交的 SDK 版本，例如0.1.0（当前仓库为0.4.3，package.json）；
以publish_npm=false运行，得到一次纯打包 dry-run；
确认无误后，设publish_npm=true且confirm=publish-sdk-0.1.0（版本号替换为实际值）正式发布。

该工作流的validate阶段会在任何构建开始前做两件事（源码见 sdk-release.yml）：

版本一致性校验：用 Node 脚本逐一比对package.json的version字段、全部optionalDependencies的版本号，以及 SDK workspace 下三份Rust manifest（Cargo.toml、recorder-core/Cargo.toml、tauri/rust/Cargo.toml）中的version，任何一处不匹配立即失败。工作流注释还记录了历史教训：recorder-core曾在 0.4.x 升级中被遗漏而静默停留在 0.3.0，只有人工 grep 版本号才被发现——这正是该校验存在的理由；
发布确认串校验：publish_npm=true时强制要求confirm等于publish-sdk-${VERSION}，防止误触发布；false时则直接进入 dry-run 模式。

校验通过后，build阶段在矩阵中同时构建四个平台绑定（工作流矩阵与 package.json 的 napi triples 一一对应）：

x86_64-apple-darwin（macOS Intel）
aarch64-apple-darwin（macOS Apple Silicon）
x86_64-pc-windows-msvc（Windows x64）
aarch64-pc-windows-msvc（Windows ARM64）

发布顺序有严格要求：先发布四个生成的平台包，再发布根包@screenpipe/sdk。这与 packages/sdk/README.md 开发文档中的指示完全一致——根包的optionalDependencies指向平台包，平台包必须先上线，否则用户安装根包时无法解析到对应平台的原生二进制。此外工作流用concurrency将发布串行化，cancel-in-progress: false保证发布中途不会被并发触发打断。

SwiftPM 通道：镜像仓库 + semver tag

SwiftPM 从 Git URL 与 semver tag 消费包。由于Package.swift嵌套在packages/sdk目录下（见 Package.swift），手册给出的干净方案是维护一个以 SDK 目录为根、专门用于 Swift 分发的镜像仓库。

手动发布命令序列

手册给出的完整发布流程：

VERSION=0.1.0 WORKDIR=$(mktemp -d) git clone git@github.com:screenpipe/sdk.git "$WORKDIR/sdk" rsync -a --delete \ --exclude '.git' \ --exclude 'node_modules' \ /path/to/screenpipe/packages/sdk/ "$WORKDIR/sdk/" cd "$WORKDIR/sdk" swift test git add -A git commit -m "release sdk ${VERSION}" git tag "${VERSION}" git push origin main git push origin "${VERSION}"

要点解析：

rsync -a --delete将本地 SDK 目录整树同步进镜像仓库的干净克隆，--exclude '.git'与--exclude 'node_modules'避免污染仓库与携带依赖；
swift test在发布前运行 Swift 测试（对应 Tests/ScreenpipeTests）；
提交后打${VERSION}tag 并同时推送main与 tag——SwiftPM 依赖的就是这个 semver tag。

客户侧安装

客户通过 SwiftPM 的.package(url:from:)消费：

.package(url: "https://github.com/screenpipe/sdk.git", from: "0.1.0")

from:要求 tag 遵循 semver 兼容规则。SDK 的 Package.swift 声明平台下限为 macOS 13，库名为Screenpipe，并打包了Resources/screenpipe-node-bridge.mjs作为桥接脚本资源。

公开前的最后检查

如果镜像仓库当前仍是私有仓库，必须确认企业版 SDK 许可证（LicenseRef-Screenpipe-Enterprise，见 packages/sdk/Cargo.toml）与 README 内容均正确无误后，才可将其转为公开。

Cargo 通道：为什么现在"不能发"

这是三条通道中唯一被刻意封锁的。手册的结论是：目前不要将 Rust SDK crate 发布到 crates.io，并给出了三个明确阻塞点，逐一核对源码全部属实：

publish = false：packages/sdk/Cargo.toml 明确声明publish = false；tauri/rust/Cargo.toml 同样如此；
本地 path 依赖：SDK 原生层依赖本地 monorepo crate——screenpipe-sdk依赖screenpipe-recorder = { path = "recorder-core" }（Cargo.toml），screenpipe-tauri依赖screenpipe-recorder = { path = "../../recorder-core" }（tauri/rust/Cargo.toml）。crates.io 不允许已发布包仅依赖未发布的本地 path 依赖，这是硬性规则；
企业许可证：SDK 采用企业许可证，未来任何 crates.io 包都需要 registry 安全的license-file配置，并要做出最终的法律/产品决策。

值得一提的是，SDK 的 Cargo workspace 设计本身就刻意独立于父级 screenpipe workspace（见 Cargo.toml 注释）：自建 workspace 把recorder-core与tauri/rust收为兄弟成员，让三者共享同一份 lockfile——因为它们包装的是同一批 monorepo crate，单一 lockfile 意味着单一解析结果、无版本重复。

未来可选的收窄路径

如果未来确实需要发布 Rust 包，手册给出两个更窄的选项，而非整体发布：

发布小的screenpipe-tauri包装 crate：为该 crate 单独提供许可证文件，并跑cargo publish --dry-run验证；
拆分一个 registry 安全的 Rust API crate：该 crate 不得再依赖任何仅存在于本地的 monorepo crate。

对应地，仓库已提供 dry-run 探测命令：

cargo publish --dry-run --manifest-path packages/sdk/tauri/rust/Cargo.toml

手册明确预期：在移除publish = false并补齐 registry 安全元数据之前，该命令会失败——这是有意为之的护栏。只有 dry-run 成功且包经过"作为 crates.io 上公开、永久产物的审查"之后，才允许真正执行cargo publish。

发布前自检清单

综合运行手册与工作流源码，可将发布检查浓缩为如下清单，供任何一次 SDK 发版复用：

分支合规：确认已合并 SDK 相关 PR，且基于最新main的干净检出；
版本同步：package.json、三份 Rust manifest（Cargo.toml、recorder-core/Cargo.toml、tauri/rust/Cargo.toml）与四个平台optionalDependencies版本号完全一致；
本地验证：bun install --frozen-lockfile、cargo metadata、npm pack --dry-run --ignore-scripts、swift test依次通过；
npm 发布顺序：平台包先于根包@screenpipe/sdk；
SwiftPM：镜像仓库同步（rsync -a --delete）→ 测试 → 提交 → 打 tag → 推送 main 与 tag；私有镜像转公开前复核许可证与 README；
Cargo：当前保持publish = false，除非完成收窄路径设计（独立许可证 + 无本地 path 依赖 + dry-run 通过）。

这三条通道的分工与隔离，既保证了 Electron/Node/Swift/Tauri 用户能稳定拿到原生 SDK 能力（npm 与 SwiftPM 已打通），也用publish = false与 path 依赖约束为 Rust 侧的企业级发布留出了审慎的决策空间——理解了这套机制，你就能安全地参与或复用 SDK 的后续发版流程。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考