Copilot for Obsidian 预发布（Prerelease）版本管理实战：从 semver 语义到 GitHub Actions 自动化发布-北京尧图网络

AI 应用大模型AI Agent交互助手RAG【免费下载链接】obsidian-copilotRun agents in Obsidian - OpenCode, Codex, Claude Code etc.项目地址https://gitcode.com/gh_mirrors/ob/obsidian-copilot点击查看免费下载导读本文以开源仓库 obsidian-copilotCopilot for Obsidian 插件的预发布 Agent 定义为主体系统讲解如何为 Obsidian 社区插件切一个 beta / rc / alpha 预发布版本从预发布与稳定发布的本质区别、Pre-flight 六项安全检查到版本号提升、预发布说明撰写、RELEASES.md 更新与 PR 创建并辅以 version-bump.mjs 与 .github/workflows/release.yml 的源码级印证。读完本文你将掌握一套完整、可复制、可自动化的预发布流水线理解manifest.json/manifest-beta.json双轨制的底层原理并能亲手创建一条触发 GitHub Release 预发布标记的 PR。一、预发布与稳定发布的本质区别在 Copilot for Obsidian 的发布体系中一次预发布prerelease与稳定发布共享同一条 GitHub Actions 自动发布流水线但存在几个关键差异PR 标题是预发布 semver形如X.Y.Z-tag.N例如3.2.9-beta.1、3.3.0-rc.0、4.0.0-alpha.2。这个标题本身既是版本号也是触发发布流程的信号。发布工作流自动识别并标记release.yml 检测到预发布模式后会在gh release create时传入--prerelease标志生成的 GitHub Release 被标记为 prerelease。Obsidian 的插件浏览器不会把预发布当作稳定更新推送给普通用户——这正是预发布给测试者、稳定版给终端用户两套通道能够共存的机制基础。master 上的manifest.json永不因预发布被修改Obsidian 社区插件商店读取 master 分支上的manifest.json来决定对外提供哪个 GitHub Release 产物因此它必须始终指向最新稳定版本。预发布的元数据放在manifest-beta.json中。version-bump.mjs 通过环境变量npm_package_version是否包含-来判定预发布是预发布则只写manifest-beta.json和versions.json。package.json由 npm 自身更新为预发布版本号它是 Agent 读取当前版本的唯一事实来源对应仓库根目录的 package.json 中的version字段。发布工作流仅在 runner 内部做一次 manifest 交换上传 Release 产物前工作流把manifest-beta.json复制为manifest.json仅存在于 runner 中不会提交回 master这样下载预发布产物的测试者拿到的是携带预发布版本的manifest.json而 master 上提交的manifest.json依旧钉在最新稳定版上。源码印证release.yml 的 semver 判定release.yml 中通过两段正则区分三种情况^[0-9]\.[0-9]\.[0-9]$→ 稳定 semver如3.2.3is_prereleasefalse^[0-9]\.[0-9]\.[0-9]-[0-9A-Za-z-]\.[0-9]$→ 预发布 semver如3.2.9-beta.1、3.3.0-rc.0is_prereleasetrue其他标题 → 非 semver工作流静默跳过不创建任何 Release。工作流在pull_request.closed且merged true时触发release.yml因此普通功能 PR 合并后不会误触发发布。二、Step 0Pre-flight 六项安全检查在动任何版本号之前必须先验证仓库处于可发布状态。任何一项不通过就停下并向用户报告而不是掩盖问题继续推进——从损坏的 master 发布预发布会误导测试者对下一个稳定版状态的判断。1. 确认 master 工作区干净git checkout master git pull origin master git status --porcelain任何未提交的状态都意味着有 PR 正在进行或上一次 Agent 运行遗留了文件。此时应停下请用户先澄清。2. 运行完整项目检查npm ci npm run lint npm run build npm test对应仓库 package.json 中定义的linteslint、buildtailwind esbuild tsc 类型检查、testjest脚本。任一环节失败即代表 master 已损坏应停下并报告具体失败步骤与用户协商后续方案。3. 检查构建产物 main.js 的体积ls -lh main.js如果main.js超过5 MB需要向用户上报该体积。预发布测试的就是稳定用户将要拿到的同一份 Release 产物因此同样的 Sync StandardObsidian 同步标准关注点同样适用。询问用户是照常发布还是先搁置。4. 校验 manifest 完整性两个文件稳定版 manifestnode -p JSON.stringify(require(./manifest.json), null, 2)确认isDesktopOnly已声明、minAppVersion与代码实际调用的 Obsidian API 匹配。当前仓库 manifest.json 中的取值为isDesktopOnly: false、minAppVersion: 1.11.4version为4.0.11。如果manifest-beta.json存在说明有预发布正在流转也要检查[ -f manifest-beta.json ] node -p JSON.stringify(require(./manifest-beta.json), null, 2)manifest-beta.json的minAppVersion及其他元数据必须与manifest.json一致——预发布通道不测试不同的最低版本要求。5. 断言 master 的 manifest.json.version 与最新稳定 Release 一致如果 master 与最新稳定发布标签发生漂移预发布会建立在错误状态之上。务必在一切动作之前捕获漂移# 使用 /releases/latest单次调用即返回最近的非预发布、非草稿 Release # 无论自上次稳定发布以来累积了多少预发布都适用。 LATEST_STABLE$(gh api repos/logancyang/obsidian-copilot/releases/latest -q .tag_name) MASTER_VERSION$(node -p require(./manifest.json).version) if [ $LATEST_STABLE ! $MASTER_VERSION ]; then echo DRIFT: master manifest.json.version$MASTER_VERSION but latest stable Release$LATEST_STABLE. Stop. 2 exit 1 fi此检查失败就停下并告知用户绝不能在预发布 PR 内修复 master 的 manifest.json。release.yml 的 Verify 步骤也内置了同样的漂移守卫release.yml当IS_PRERELEASEtrue时工作流用gh api repos/${GITHUB_REPOSITORY}/releases/latest比对合并提交上的manifest.json与最新稳定标签不一致则拒绝发布。6. 确认存在已合并的 PR 可供预发布git describe --tags --abbrev0 git log --oneline $(git describe --tags --abbrev0)..HEAD | head如果为空说明没有新东西可测停下并告诉用户。六项检查全部通过后才进入 Step 1。三、Step 1确定预发布身份在提升版本号之前需要向用户确认三个维度Tagbeta、rc、alpha等用户未指定时默认beta基础版本目标prepatch、preminor、premajor本次预发布通往哪个稳定版本prepatch最常见3.2.8→3.2.9-beta.0preminor3.2.8→3.3.0-beta.0premajor3.2.8→4.0.0-beta.0还是对既有预发布线的迭代如果当前版本本身已是预发布如3.2.9-beta.0则用prerelease只递增预发布计数器3.2.9-beta.0→3.2.9-beta.1。这对应 npm semver 预发布规则prepatch/preminor/premajor分别只提升 patch/minor/major 段并追加预发布后缀prerelease只递增已有预发布线的序号。四、Step 23准备分支并提升版本号准备分支git checkout master git pull origin master创建包含预发布身份的描述性分支名git checkout -b prerelease/vX.Y.Z-tag.N提升版本号使用 npm version 命令--preid指定所选 tag--no-git-tag-version让 npm不在本地创建 git tag打标签交给发布工作流处理开启新的预发布线npm version prepatch|preminor|premajor --preidtag --no-git-tag-version递增既有预发布npm version prerelease --preidtag --no-git-tag-version示例3.2.8npm version prepatch --preidbeta --no-git-tag-version→3.2.9-beta.03.2.9-beta.0npm version prerelease --preidbeta --no-git-tag-version→3.2.9-beta.13.2.9-beta.5npm version prerelease --preidrc --no-git-tag-version→3.2.9-rc.0npm version会触发package.json中的version脚本见 package.json即执行 version-bump.mjs。该脚本将更新manifest-beta.json不存在时用manifest.json作种子创建和versions.json绝不触碰manifest.json。提升完成后从package.json读取新版本号供后续步骤使用。源码印证version-bump.mjs 的双轨写盘逻辑version-bump.mjs 的核心判断只有一行const isPrerelease targetVersion.includes(-); const manifestPath isPrerelease ? manifest-beta.json : manifest.json;预发布路径manifest-beta.json不存在时从manifest.json种子复制version-bump.mjs从而继承description、fundingUrl、minAppVersion等稳定版字段仅覆盖versionversions.json 记录versions[targetVersion] minAppVersionversion-bump.mjsObsidian 安装器据此为用户的 Obsidian 版本挑选合适的插件版本预发布与稳定条目都记录于此仓库根目录 versions.json 的结构即版本号 → 最低 Obsidian 版本稳定版发布时清理当目标版本不是预发布且manifest-beta.json存在时脚本将其git rm若已被跟踪或直接删除若仅在工作树中使新稳定版取代任何在途预发布version-bump.mjs。五、Step 4收集并理解合并的 PR与稳定发布 Agent 相同找到最近一个 tag它本身可能就是预发布列出其后的合并 PR并逐条阅读 PR 描述以获取上下文。git describe --tags --abbrev0 gh pr list --state merged --base master --search merged:YYYY-MM-DD --json number,title,author,labels --limit 500如果最近 tag 是预发布如3.2.9-beta.0则列出自该预发布以来合并的 PR而不是自上次稳定版以来。预发布说明只应反映自上一个测试产物以来的新增内容——这正是迭代式预发布的增量测试理念。六、Step 5生成预发布说明沿用稳定发布的 RELEASES.md 格式仓库中已有大量历史条目可作风格参考但做如下调整头部格式# Copilot for Obsidian - Prerelease vX.Y.Z-tag.N 表示测试意图。其他合适的 emoji进行中、研究、bug 修复类预发布。开头行说明这是面向测试者的预发布并指出本次测试重点。示例This is a beta release for testing the new Vault QA caching path before it ships in 3.2.9. Please report any indexing or query issues in Discord.项目符号列表与稳定版相同的 emoji 加粗轻松风格但对未经验证的内容必须诚实。若某功能存在已知的尖锐问题请明确说明。不要默认包含稳定版那种完整的 Improvements / Bug Fixes PR 汇总除非用户明确要求。预发布说明应当简短、聚焦测试。必须包含 What to Test 小节用明确的条目告诉测试者聚焦点## What to Test - New behavior X: try Y workflow and confirm Z. - Changed behavior W: confirm it still does what it used to do. - Known sharp edges: list anything you suspect is unstable so testers dont waste time reporting it.必须包含 How to Install 小节——大多数用户不知道如何安装预发布## How to Install the Prerelease 1. Download main.js, manifest.json, and styles.css from this prereleases GitHub release page. 2. Replace the same three files in your vaults .obsidian/plugins/copilot/ folder. 3. Reload the plugin (Settings → Community Plugins → toggle Copilot off and back on, or restart Obsidian). 4. Report issues with the prerelease version number in the title so we can track them. To return to the stable release: reinstall the plugin from Obsidians community-plugin browser.结尾与稳定版一样加上 Troubleshoot 页脚If models are missing, navigate to Copilot settings - Models tab...并以---分隔符收尾。七、Step 6更新 RELEASES.md将预发布条目置顶插入到 RELEASES.md 中# Release Notes标题行之后保留所有既有条目不动。当对应的稳定版发布时稳定版说明会追加到该预发布条目的上方而非删除预发布条目。预发布条目作为历史记录永久保留在文件中——这也解释了为何工作流规则明确禁止 force-push 或修改既有 Release 条目。八、Step 7提交并创建 PR暂存所有变更文件。注意预发布改动的是manifest-beta.json而不是manifest.jsongit add package.json package-lock.json manifest-beta.json versions.json RELEASES.md如果git status显示manifest.json被修改说明出了问题——version-bump.mjs 在预发布提升时绝不应触碰manifest.json。停下并告知用户。提交信息prerelease: vX.Y.Z-tag.N推送并创建 PRgit push -u origin prerelease/vX.Y.Z-tag.N gh pr create --title X.Y.Z-tag.N --body $(cat EOF ## Prerelease vX.Y.Z-tag.N [Paste the prerelease notes content here] --- Generated by the prerelease agent. EOF )关键点PR 标题必须精确等于预发布 semver 字符串如3.2.9-beta.1不带v前缀、不加任何其他文字。这个模式正是触发发布工作流传入--prerelease的依据——对照 release.yml 的正则判定标题不匹配则不会进入发布分支。源码印证合并后的发布链路当该 PR 合并进 master 后release.yml 依次执行版本校验比对 PR 标题与manifest-beta.json的version并对 master 的manifest.json做最新稳定标签漂移守卫release.yml构建npm ci、npm run review:obsidian、npm run buildrelease.yml 内对应步骤Runner 内 manifest 交换cp manifest-beta.json manifest.jsonrelease.yml使上传产物的 manifest 携带预发布版本但绝不回写 master产物签名与 Release 创建gh release create $VERSION --target $MERGE_SHA --title $VERSION --notes-file /tmp/release-notes.md $PRERELEASE_FLAG main.js manifest.json styles.cssrelease.yml其中IS_PRERELEASEtrue时PRERELEASE_FLAG--prerelease。工作流同时用actions/attest-build-provenancev2对main.js/manifest.json/styles.css生成构建来源证明release.yml并在 runner 内 manifest 交换之后执行保证被签名验证的 manifest 与上传到 Release 的文件完全一致。九、Step 8向用户汇报分享 PR 链接并总结切出的预发布版本号是什么包含哪些 PR数量与关键特性main.js 体积供关注提醒PR 标题就是预发布 tag合并它即发布一个预发布 GitHub Release。十、重要规则清单绝不 force-push绝不修改 RELEASES.md 中既有的发布条目始终从最新 master 出发——分支前先 pullPR 标题必须是裸预发布 semver 字符串X.Y.Z-tag.N如3.2.9-beta.1无v前缀、无多余文字这是发布工作流标记 prerelease 的依据稳定发布走稳定发布 Agent不走本流程形如3.2.9无预发布后缀的标题属于稳定发布流程对照 .claude/agents/release.md 的规则写 RELEASES.md 前先读既有条目语气与格式保持一致预发布条目要有视觉区分度标题、显式 What to Test、How to Install 小节对未经验证的内容诚实预发布存在的意义是暴露 bug而不是过度推销稳定性。如果你不敢拿自己的声誉为某功能背书就如实写进说明任何 Pre-flight 失败即停止不要从 lint/build/test 失败或体积超标的 master 发布预发布报告并询问而不是掩盖不要在预发布 PR 中静默修改manifest.minAppVersion或manifest.isDesktopOnly与稳定版规则相同这类变更应走独立 PR绝不在预发布中修改 master 的manifest.json它必须始终反映最新稳定版本Obsidian 插件商店依赖这一点预发布元数据只进manifest-beta.json若npm version失败或version-bump.mjs未运行手动更新manifest-beta.json和versions.json以匹配预发布 semver同样不要触碰manifest.json。十一、与稳定发布流程的对照预发布与稳定发布共享同一套发布工作流与大部分操作步骤差异集中在版本号语义与 manifest 处理对照 .claude/agents/release.md维度稳定发布预发布PR 标题X.Y.Z如3.2.4X.Y.Z-tag.N如3.2.9-beta.1npm versionpatch/minor/majorprepatch/preminor/premajor/prerelease写入的 manifestmanifest.jsonmanifest-beta.json不存在时从manifest.json种子创建manifest.json状态更新为发布版本保持最新稳定版不动工作流标志不带--prerelease带--prerelease发布通道Obsidian 插件浏览器稳定更新仅测试者可见插件浏览器不推送对manifest-beta.json自动删除新稳定版取代在途预发布创建或更新理解这张对照表就能清楚什么时候切 beta、什么时候放稳定版并保证 Obsidian 社区插件商店始终服务于最新稳定版本而预发布产物永远只流向愿意主动安装测试的群体。参考资源预发布 Agent 完整定义本文核心依据稳定发布 Agent 定义流程对照version-bump.mjs版本号写盘与双轨 manifest 逻辑.github/workflows/release.yml自动发布工作流RELEASES.md发布说明历史与格式范本manifest.json 与 versions.json版本元数据与最低版本映射package.json版本号事实来源与version脚本赞分享AI 应用大模型AI Agent交互助手RAG【免费下载链接】obsidian-copilotRun agents in Obsidian - OpenCode, Codex, Claude Code etc.项目地址https://gitcode.com/gh_mirrors/ob/obsidian-copilot点击查看免费下载相关推荐p5.js 发布流程实战基于 GitHub Actions 与 semver 的自动化版本发布指南p5.js 发布流程实战基于 GitHub Actions 与 semver 的自动化版本发布指南本文以 p5.js 官方发布流程文档为核心结合仓库中实际前端图形学3D渲染ESP32 机器狗搭建实录99 元 4 路舵机让一只会聊天的小狗落地ESP32 机器狗搭建实录99 元 4 路舵机让一只会聊天的小狗落地上个月我终于把这只 ESP32 机器狗搭了出来。整套方案基于 ESP HI 板E人工智能大模型语音交互助手嵌入式物联网智能硬件MCP 服务EmDash 插件发布实战从本地 publish 到 GitHub Actions 自动化委托发布EmDash 插件发布实战从本地 publish 到 GitHub Actions 自动化委托发布 EmDash基于 Astro 的全栈 TypeScripCMS后端前端插件系统上一篇WebToApp HTML 应用类型实战指南把本地静态站点打包成离线 APK下一篇Android性能优化实测Uperf Game Turbo 五档CPU调频模式与安装配置全解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Copilot for Obsidian 预发布（Prerelease）版本管理实战：从 semver 语义到 GitHub Actions 自动化发布

相关推荐

STM32CubeMX安装失败原因揭秘：路径、JDK11与Windows防护三重硬约束

免备案域名购买平台一文搞懂：3种方案避坑指南

DeepCTR MMOE 多任务学习模型实战指南：源码解析、参数详解与完整训练示例

更多资讯

[Warning] [context7] mcpServers.context7: Windows requires ‘cmd /c‘ wrapper to execute npx——TaoToken

OpenClaw 能干什么？我让 AI 帮我干了 7 天活，结果出乎意料：TaoToken 统一 Key 接入配置实录

如何提高网站流量与郴州网站建设有限公司对比

网站建设项目开发书：3步搞定备案与开发避坑指南

泉州seo优化排名公司实战：3个步骤搞定官网设计与SEO最佳实践

IDEA 新 UI 配置启用指南：TaoToken 统一 Key 接入 settings.json 骨架与验证

今日更新

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？