From 4658a565355254960cc523098ae403d7469b2bf0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=85=B0=E6=B6=9B?= <550947002@qq.com> Date: Thu, 3 Sep 2026 20:52:53 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20docs(dev-workflow):=20=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=20CLI-Core=20=E4=BE=9D=E8=B5=96=E6=A8=A1=E5=9E=8B?= =?UTF-8?q?=E4=B8=8E=E5=8F=91=E7=89=88=E6=B5=81=E7=A8=8B=E5=8F=A3=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CLI 对 Core 的依赖描述:caret range → **精确 pin**(与 PR #53 引入的 CLI-pin-Core 联动制对齐;`version:set:core` 会自动同步 CLI 依赖 + 提示锁步 patch) - 明确 Core 兼容修复也必须 CLI 锁步 bump + 同发;仅改 CLI 自身代码时才允许 CLI 单独发 - 新增「发版执行步骤(CI 触发)」小节:标准流程走 GitHub Release 触发 `.github/workflows/publish-npm.yml`,才能拿到 npm 详情页的 provenance 勾;禁止本地 `npm publish` - 三端手写镜像同步(.claude / .cursor / .codex) 背景:本次 core-v3.8.0 / cli-v3.6.3 是本地直接 npm publish 发的,npm 详情页无 provenance 徽章。规则里那段过期的 caret range 描述误导了发版决策——本 PR 修回。 --- .../rules/repo-dev-workflow-constraints.md | 27 ++++++++++++++----- .../topics/repo-dev-workflow-constraints.md | 27 ++++++++++++++----- .../rules/repo-dev-workflow-constraints.mdc | 27 ++++++++++++++----- 3 files changed, 60 insertions(+), 21 deletions(-) diff --git a/.claude/rules/repo-dev-workflow-constraints.md b/.claude/rules/repo-dev-workflow-constraints.md index 7e64548..5f503b3 100644 --- a/.claude/rules/repo-dev-workflow-constraints.md +++ b/.claude/rules/repo-dev-workflow-constraints.md @@ -47,10 +47,10 @@ Template Version packages/core/package.json.templateVersion Protocol Version packages/core/capabilities.json.protocolVersion ``` -- CLI 对 Core 使用运行时依赖 caret range（当前为 `^3.5.0`）；Core 必须落在该范围内。 -- Core 兼容修复/新增 API 可只升 Core；Template Version 不变，不触发知识库升级。 -- Rule、Skill、Hook、知识模板变化时升 Core，并显式执行 `version:set:template`。 -- CLI 开始调用新版 Core API 时，升 CLI 并显式提高最低 Core range。 +- CLI 对 Core 使用运行时依赖**精确 pin**（`packages/cli/package.json` 里写死 Core 版本号,不是 caret range）；`scripts/workspace-version.js` 会自动同步。 +- Core 兼容修复/新增 API 也**必须 CLI 锁步 patch bump 并同发**——CLI 精确 pin 决定的:Core 一升,CLI 依赖字段就变,CLI 版本号必须跟着走(`version:set:core` 回执会提示 `remember to bump CLI patch — release in lockstep`)。仅改 CLI 自身代码(不动 Core)时才允许 CLI 单独发。 +- Rule、Skill、Hook、知识模板变化时升 Core,并显式执行 `version:set:template`（同样锁步 CLI patch）。 +- CLI 开始调用新版 Core API 时,升 CLI 并同步 Core 精确 pin。 - Protocol Version 只在公共协议不兼容时调整。 - 根 private workspace version 不参与 npm 发布匹配。 @@ -67,10 +67,23 @@ npm run version:check - `core-vX.Y.Z` 只测试、打包并发布 `@double-coding/flow2spec-core`。 - `cli-vX.Y.Z` 只测试、打包并发布 `@double-coding/flow2spec`。 -- 同时发布时先 Core 后 CLI；禁止发布没有版本变化的包。 -- CLI README 与根 README 保持一致；Core README 独立维护。 +- 同时发布时先 Core 后 CLI(CLI 精确 pin Core);禁止发布没有版本变化的包。 +- CLI README 与根 README 保持一致;Core README 独立维护。 - 发布前运行 `npm run version:check`、`npm run pack:check`、`node scripts/test-package-install.js`。 -- `packages/core/templates/` 必须直接进入 Core tarball；不存在模板复制或漂移检查步骤。 +- `packages/core/templates/` 必须直接进入 Core tarball;不存在模板复制或漂移检查步骤。 + +## 发版执行步骤(CI 触发,不本地 npm publish) + +`.github/workflows/publish-npm.yml` 通过 GitHub OIDC + npm trusted publishing 自动发包并带 provenance。**只有走 CI 才能拿到 npm 详情页的 provenance 勾**;本地 `npm publish` 发出的版本会缺失该证明,已发出去无法补签,只能下版本再发时用 CI 拿回。 + +标准流程: + +1. 在版本 PR(如 `chore/release-core-3.8.0`) merge 到 main 后,本地 `git checkout main && git pull`; +2. 打两个 tag 并推送:`git tag core-vX.Y.Z && git tag cli-vX.Y.Z && git push --tags`; +3. **到 GitHub Releases 页面**为每个 tag **创建 Release**(标题 `core-vX.Y.Z` / `cli-vX.Y.Z`);Release published 事件触发 `publish-npm.yml`; +4. workflow 内已包含 `npm run version:check --tag`、`npm test`、`pack:check`、`npm publish --provenance`,失败即中止。 + +**禁止本地跑 `npm publish`**——即便临时需要 hotfix,也应通过 workflow 走。若确因意外走了本地发布(如本次 3.8.0 / 3.6.3),须在发版 PR / Release notes 中显式记录「本次发布无 provenance」。 ## 更新语义 diff --git a/.codex/topics/repo-dev-workflow-constraints.md b/.codex/topics/repo-dev-workflow-constraints.md index 7e64548..5f503b3 100644 --- a/.codex/topics/repo-dev-workflow-constraints.md +++ b/.codex/topics/repo-dev-workflow-constraints.md @@ -47,10 +47,10 @@ Template Version packages/core/package.json.templateVersion Protocol Version packages/core/capabilities.json.protocolVersion ``` -- CLI 对 Core 使用运行时依赖 caret range（当前为 `^3.5.0`）；Core 必须落在该范围内。 -- Core 兼容修复/新增 API 可只升 Core；Template Version 不变，不触发知识库升级。 -- Rule、Skill、Hook、知识模板变化时升 Core，并显式执行 `version:set:template`。 -- CLI 开始调用新版 Core API 时，升 CLI 并显式提高最低 Core range。 +- CLI 对 Core 使用运行时依赖**精确 pin**（`packages/cli/package.json` 里写死 Core 版本号,不是 caret range）；`scripts/workspace-version.js` 会自动同步。 +- Core 兼容修复/新增 API 也**必须 CLI 锁步 patch bump 并同发**——CLI 精确 pin 决定的:Core 一升,CLI 依赖字段就变,CLI 版本号必须跟着走(`version:set:core` 回执会提示 `remember to bump CLI patch — release in lockstep`)。仅改 CLI 自身代码(不动 Core)时才允许 CLI 单独发。 +- Rule、Skill、Hook、知识模板变化时升 Core,并显式执行 `version:set:template`（同样锁步 CLI patch）。 +- CLI 开始调用新版 Core API 时,升 CLI 并同步 Core 精确 pin。 - Protocol Version 只在公共协议不兼容时调整。 - 根 private workspace version 不参与 npm 发布匹配。 @@ -67,10 +67,23 @@ npm run version:check - `core-vX.Y.Z` 只测试、打包并发布 `@double-coding/flow2spec-core`。 - `cli-vX.Y.Z` 只测试、打包并发布 `@double-coding/flow2spec`。 -- 同时发布时先 Core 后 CLI；禁止发布没有版本变化的包。 -- CLI README 与根 README 保持一致；Core README 独立维护。 +- 同时发布时先 Core 后 CLI(CLI 精确 pin Core);禁止发布没有版本变化的包。 +- CLI README 与根 README 保持一致;Core README 独立维护。 - 发布前运行 `npm run version:check`、`npm run pack:check`、`node scripts/test-package-install.js`。 -- `packages/core/templates/` 必须直接进入 Core tarball；不存在模板复制或漂移检查步骤。 +- `packages/core/templates/` 必须直接进入 Core tarball;不存在模板复制或漂移检查步骤。 + +## 发版执行步骤(CI 触发,不本地 npm publish) + +`.github/workflows/publish-npm.yml` 通过 GitHub OIDC + npm trusted publishing 自动发包并带 provenance。**只有走 CI 才能拿到 npm 详情页的 provenance 勾**;本地 `npm publish` 发出的版本会缺失该证明,已发出去无法补签,只能下版本再发时用 CI 拿回。 + +标准流程: + +1. 在版本 PR(如 `chore/release-core-3.8.0`) merge 到 main 后,本地 `git checkout main && git pull`; +2. 打两个 tag 并推送:`git tag core-vX.Y.Z && git tag cli-vX.Y.Z && git push --tags`; +3. **到 GitHub Releases 页面**为每个 tag **创建 Release**(标题 `core-vX.Y.Z` / `cli-vX.Y.Z`);Release published 事件触发 `publish-npm.yml`; +4. workflow 内已包含 `npm run version:check --tag`、`npm test`、`pack:check`、`npm publish --provenance`,失败即中止。 + +**禁止本地跑 `npm publish`**——即便临时需要 hotfix,也应通过 workflow 走。若确因意外走了本地发布(如本次 3.8.0 / 3.6.3),须在发版 PR / Release notes 中显式记录「本次发布无 provenance」。 ## 更新语义 diff --git a/.cursor/rules/repo-dev-workflow-constraints.mdc b/.cursor/rules/repo-dev-workflow-constraints.mdc index 7e64548..5f503b3 100644 --- a/.cursor/rules/repo-dev-workflow-constraints.mdc +++ b/.cursor/rules/repo-dev-workflow-constraints.mdc @@ -47,10 +47,10 @@ Template Version packages/core/package.json.templateVersion Protocol Version packages/core/capabilities.json.protocolVersion ``` -- CLI 对 Core 使用运行时依赖 caret range（当前为 `^3.5.0`）；Core 必须落在该范围内。 -- Core 兼容修复/新增 API 可只升 Core；Template Version 不变，不触发知识库升级。 -- Rule、Skill、Hook、知识模板变化时升 Core，并显式执行 `version:set:template`。 -- CLI 开始调用新版 Core API 时，升 CLI 并显式提高最低 Core range。 +- CLI 对 Core 使用运行时依赖**精确 pin**（`packages/cli/package.json` 里写死 Core 版本号,不是 caret range）；`scripts/workspace-version.js` 会自动同步。 +- Core 兼容修复/新增 API 也**必须 CLI 锁步 patch bump 并同发**——CLI 精确 pin 决定的:Core 一升,CLI 依赖字段就变,CLI 版本号必须跟着走(`version:set:core` 回执会提示 `remember to bump CLI patch — release in lockstep`)。仅改 CLI 自身代码(不动 Core)时才允许 CLI 单独发。 +- Rule、Skill、Hook、知识模板变化时升 Core,并显式执行 `version:set:template`（同样锁步 CLI patch）。 +- CLI 开始调用新版 Core API 时,升 CLI 并同步 Core 精确 pin。 - Protocol Version 只在公共协议不兼容时调整。 - 根 private workspace version 不参与 npm 发布匹配。 @@ -67,10 +67,23 @@ npm run version:check - `core-vX.Y.Z` 只测试、打包并发布 `@double-coding/flow2spec-core`。 - `cli-vX.Y.Z` 只测试、打包并发布 `@double-coding/flow2spec`。 -- 同时发布时先 Core 后 CLI；禁止发布没有版本变化的包。 -- CLI README 与根 README 保持一致；Core README 独立维护。 +- 同时发布时先 Core 后 CLI(CLI 精确 pin Core);禁止发布没有版本变化的包。 +- CLI README 与根 README 保持一致;Core README 独立维护。 - 发布前运行 `npm run version:check`、`npm run pack:check`、`node scripts/test-package-install.js`。 -- `packages/core/templates/` 必须直接进入 Core tarball；不存在模板复制或漂移检查步骤。 +- `packages/core/templates/` 必须直接进入 Core tarball;不存在模板复制或漂移检查步骤。 + +## 发版执行步骤(CI 触发,不本地 npm publish) + +`.github/workflows/publish-npm.yml` 通过 GitHub OIDC + npm trusted publishing 自动发包并带 provenance。**只有走 CI 才能拿到 npm 详情页的 provenance 勾**;本地 `npm publish` 发出的版本会缺失该证明,已发出去无法补签,只能下版本再发时用 CI 拿回。 + +标准流程: + +1. 在版本 PR(如 `chore/release-core-3.8.0`) merge 到 main 后,本地 `git checkout main && git pull`; +2. 打两个 tag 并推送:`git tag core-vX.Y.Z && git tag cli-vX.Y.Z && git push --tags`; +3. **到 GitHub Releases 页面**为每个 tag **创建 Release**(标题 `core-vX.Y.Z` / `cli-vX.Y.Z`);Release published 事件触发 `publish-npm.yml`; +4. workflow 内已包含 `npm run version:check --tag`、`npm test`、`pack:check`、`npm publish --provenance`,失败即中止。 + +**禁止本地跑 `npm publish`**——即便临时需要 hotfix,也应通过 workflow 走。若确因意外走了本地发布(如本次 3.8.0 / 3.6.3),须在发版 PR / Release notes 中显式记录「本次发布无 provenance」。 ## 更新语义