Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

Document release workflow guide

ifuryst4e3434f60ba4
diff --git a/AGENTS.md b/AGENTS.md
index 12077ab..5675189 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,6 +28,7 @@
- `docs/FRONTEND.md`:如果仓库包含前端界面,这里记录对应规范。
- `CONTRIBUTING.md`:提 PR 前后的默认检查项和协作要求。
- `docs/releases/README.md`:如何维护面向用户的发布记录。
+- `docs/releases/RELEASE_GUIDE.md`:只要任务涉及 bump 版本、打 tag、推 release,先读这份发版必读。
- `docs/references/README.md`:沉淀到仓库里的外部参考资料。
## 工作规则
diff --git a/docs/histories/2026-04/20260419-2203-document-release-guide.md b/docs/histories/2026-04/20260419-2203-document-release-guide.md
new file mode 100644
index 0000000..d973be5
--- /dev/null
+++ b/docs/histories/2026-04/20260419-2203-document-release-guide.md
@@ -0,0 +1,26 @@
+## [2026-04-19 22:03] | Task: 沉淀发版必读文档
+
+### 🤖 Execution Context
+* **Agent ID**: `codex`
+* **Base Model**: `gpt-5`
+* **Runtime**: `Codex CLI`
+
+### 📥 User Query
+> 这个发版本的落个独立的md到docs把,然后AGENTS.md加个发版本必读的指向。这样未来新发版本就都知道怎么做了
+
+### 🛠 Changes Overview
+**Scope:** `docs/`、`AGENTS.md`
+
+**Key Actions:**
+- **[Release Guide]**: 新增 `docs/releases/RELEASE_GUIDE.md`,把版本源、release checklist、tag 推送命令、GitHub Actions 排查方式,以及 tag 打错后的修复路径单独沉淀下来。
+- **[Agent Routing]**: 在 `AGENTS.md` 里新增“发版本必读”导航,让版本 bump / 打 tag / 查 release 失败这类任务一开始就能命中正确文档。
+- **[Docs Index Sync]**: 更新 `docs/releases/README.md`,把面向用户的 release note 入口和面向维护者的发版指南区分开。
+
+### 🧠 Design Intent (Why)
+这次 release 修复暴露出一个典型问题:版本源和 tag 约定如果只存在于聊天里,下一次发版时仍然很容易再踩一遍。把“必须先改哪几个版本文件、怎么验证 staging 包真的变成新版本、CI 失败先查什么”沉淀成独立文档,再在 `AGENTS.md` 里做最短路径导航,后续 Agent 和人都能按同一套流程执行,不需要继续靠记忆维持。
+
+### 📁 Files Modified
+- `AGENTS.md`
+- `docs/releases/README.md`
+- `docs/releases/RELEASE_GUIDE.md`
+- `docs/histories/2026-04/20260419-2203-document-release-guide.md`
diff --git a/docs/releases/README.md b/docs/releases/README.md
index 57c6c3e..7794755 100644
--- a/docs/releases/README.md
+++ b/docs/releases/README.md
@@ -2,6 +2,8 @@
`feature-release-notes.md` 用来记录对用户可感知的新功能、体验优化和重要修复。
+如果任务是“准备发版 / bump 版本 / 打 tag / 查 release 失败”,先读 `RELEASE_GUIDE.md`。
+
## 规则
- 按月份分组,格式使用 `## YYYY-MM`
diff --git a/docs/releases/RELEASE_GUIDE.md b/docs/releases/RELEASE_GUIDE.md
new file mode 100644
index 0000000..9afa54f
--- /dev/null
+++ b/docs/releases/RELEASE_GUIDE.md
@@ -0,0 +1,126 @@
+# 发版指南
+
+这份文档约束这个仓库未来的 patch / minor release 流程,目标是避免再次出现 “git tag 已经发了,但 npm staging 产物版本还是旧值” 这类版本源不一致问题。
+
+## 什么时候必读
+
+- 只要任务里包含这些动作之一,就先读这份文档:
+ - bump 版本
+ - 打 release tag
+ - 推送 release tag
+ - 看 GitHub Actions release 失败原因
+ - 重发某个失败版本
+
+## 当前 release 入口
+
+- 本地 staging / 打 tgz:`./scripts/release-package.sh`
+- 本地 stage npm 包目录:`node ./scripts/npm/build-packages.mjs`
+- 本地 publish:`node ./scripts/npm/publish-packages.mjs`
+- CI workflow:`.github/workflows/release.yml`
+- 用户可见发布记录:`docs/releases/feature-release-notes.md`
+
+## 当前版本源
+
+这个仓库的 npm staging 包版本,当前以 `plugins/open-computer-use/.codex-plugin/plugin.json` 里的 `version` 为准。
+
+也就是说:
+
+- 只改 git tag,不改这个 manifest,不会得到新 npm 版本。
+- `scripts/npm/build-packages.mjs` 会从这个 manifest 读取版本,再生成三个 staging 包。
+- 所以 release 前必须先把这份 manifest bump 到目标版本。
+
+## Release Checklist
+
+### 1. 先统一版本号
+
+至少检查并同步这些位置:
+
+- `plugins/open-computer-use/.codex-plugin/plugin.json`
+- `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/OpenComputerUseVersion.swift`
+- `apps/OpenComputerUseSmokeSuite/Sources/OpenComputerUseSmokeSuite/main.swift`
+- `packages/OpenComputerUseKit/Tests/OpenComputerUseKitTests/OpenComputerUseKitTests.swift`
+- `scripts/computer-use-cli/main.go`
+- `scripts/computer-use-cli/README.md`
+- `docs/releases/feature-release-notes.md`
+- `docs/histories/` 中本轮 release 对应的 history
+
+如果这轮 release 还改了其他对外暴露版本字符串,也要一起对齐,不要只改一半。
+
+### 2. 本地验证版本源已经生效
+
+至少跑这两步:
+
+```bash
+swift test
+node ./scripts/npm/build-packages.mjs --skip-build --out-dir dist/release/npm-staging-check
+```
+
+然后直接检查 staging 包版本:
+
+```bash
+node -p "require('./dist/release/npm-staging-check/open-codex-computer-use-mcp/package.json').version"
+```
+
+如果这里打印的不是目标版本,不要打 tag。
+
+### 3. 提交版本 bump
+
+- 用单独 commit 提交 release version bump。
+- commit message 要能直接看出这是 release 收口,而不是普通功能提交。
+
+### 4. 打 tag 并推送
+
+当前约定用 `vX.Y.Z`:
+
+```bash
+git tag -a v0.1.12 -m "v0.1.12"
+git push origin main
+git push origin v0.1.12
+```
+
+## Release 失败时怎么查
+
+### 1. 先看最新 run
+
+```bash
+gh run list -R iFurySt/open-codex-computer-use --limit 10
+gh run view -R iFurySt/open-codex-computer-use <run-id> --log-failed
+```
+
+### 2. 重点看哪一类错误
+
+- `npm error 403 ... You cannot publish over the previously published versions`
+ - 通常不是 token 权限问题,而是 staging 包版本仍然是旧版本。
+ - 先回头检查 `plugin.json` 的 `version`,再检查 staging 包实际产出的 `package.json`。
+- 构建阶段失败
+ - 优先看 `Build npm release artifacts` 或 Swift 编译错误。
+- publish 认证失败
+ - 再去看 `.github/workflows/release.yml`、`scripts/npm/publish-packages.mjs` 和 npm trusted publishing / token fallback 配置。
+
+## 如果 tag 已经打错了
+
+如果远端 tag 已经指向错误 commit,先删 tag,再修版本源,再重打。
+
+本地删 tag:
+
+```bash
+git tag -d v0.1.12
+```
+
+远端删 tag:
+
+```bash
+git push origin :refs/tags/v0.1.12
+```
+
+修好后再重新创建并推送同名 tag。
+
+## 文档同步要求
+
+每次 release 都至少同步这三类文档:
+
+- `docs/releases/feature-release-notes.md`
+- `docs/histories/` 对应 release history
+- 如果 release 流程本身有变化,这份 `docs/releases/RELEASE_GUIDE.md`
+
+如果一次 release 暴露出新的流程坑,就不要只在聊天里记住,直接补进这份文档。