👾 Open Computer Use – Open-Source Alternative to Codex Computer Use
Swift accessibilityai-agentai-agentsclaude-codecodexcodex-computer-usecomputer-usecomputer-use-agentcross-platformcuadesktop-automationgemini-cligui-automationmacosmcpmodel-context-protocolopen-computer-useopen-computer-use-mcpopenai-codexopencode
Document release workflow guide
ifuryst4e3434f60ba4
diff --git a/AGENTS.md b/AGENTS.mdindex 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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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 暴露出新的流程坑,就不要只在聊天里记住,直接补进这份文档。