build(release): automate CLI releases with Changesets

.changeset/README.md

@@ -0,0 +1,12 @@
+# Changesets
+
+Changesets records user-facing changes that should be included in the next
+`@doocs/md-cli` release.
+
+Run `pnpm changeset`, select `@doocs/md-cli`, choose the semantic version bump,
+and write a concise release-note summary. Commit the generated Markdown file
+with the change.
+
+After changes land on `main`, the release workflow keeps a release pull request
+up to date. Merging that pull request publishes the package to npm and creates
+the corresponding Git tag and GitHub release.

.changeset/clean-otters-release.md

@@ -0,0 +1,5 @@
+---
+"@doocs/md-cli": patch
+---
+
+Automate CLI versioning, changelog generation, and npm publishing with Changesets.

.changeset/config.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@4.0.0/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    {
+      "repo": "doocs/md"
+    }
+  ],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": ["md", "doocs-md"]
+}

.github/workflows/release-cli.yml

@@ -1,18 +1,25 @@
-name: Create CLI Release
+name: Release CLI
 
 on:
   push:
-    tags:
-      - 'cli-v*'
+    branches: [main]
+  workflow_dispatch:
 
-permissions:
-  id-token: write  # Required for OIDC trusted publishing
-  contents: read
+permissions: {}
+
+concurrency:
+  group: release-cli-${{ github.ref }}
+  cancel-in-progress: false
 
 jobs:
-  build:
+  select-mode:
     runs-on: ubuntu-latest
     if: github.repository == 'doocs/md'
+    permissions:
+      contents: read
+    outputs:
+      mode: ${{ steps.select-mode.outputs.mode }}
+      publish-plan-artifact-id: ${{ steps.select-mode.outputs.publish-plan-artifact-id }}
     steps:
       - name: Checkout
         uses: actions/checkout@v7
@@ -23,23 +30,112 @@ jobs:
         uses: pnpm/setup@v3
         with:
           version: 12.14.0
+          runtime: node@22
           cache: true
           install: false
 
-      - name: Set up Node
-        uses: actions/setup-node@v7
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Select release mode
+        id: select-mode
+        uses: changesets/action/select-mode@v2
+
+  version:
+    needs: select-mode
+    if: needs.select-mode.outputs.mode == 'version'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
         with:
-          node-version: 22
-          registry-url: https://registry.npmjs.org/
+          persist-credentials: false
 
-      - name: Update npm
-        run: npm install -g npm@latest
+      - name: Set up pnpm
+        uses: pnpm/setup@v3
+        with:
+          version: 12.14.0
+          runtime: node@22
+          cache: true
+          install: false
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create or update release pull request
+        uses: changesets/action/version@v2
+        with:
+          github-token: ${{ secrets.DOOCS_BOT_ACTION_TOKEN }}
+          script: pnpm changeset:version
+          commit-message: 'chore: release CLI'
+          pr-title: 'chore: release CLI'
+
+  pack:
+    needs: select-mode
+    if: needs.select-mode.outputs.mode == 'publish'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      pack-dir-artifact-id: ${{ steps.pack.outputs.pack-dir-artifact-id }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up pnpm
+        uses: pnpm/setup@v3
+        with:
+          version: 12.14.0
+          runtime: node@22
+          cache: true
+          install: false
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
       - name: Build CLI
         run: pnpm run build:cli
 
+      - name: Pack CLI
+        id: pack
+        uses: changesets/action/pack@v2
+        with:
+          publish-plan-artifact-id: ${{ needs.select-mode.outputs.publish-plan-artifact-id }}
+
+  publish:
+    needs: pack
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up pnpm
+        uses: pnpm/setup@v3
+        with:
+          version: 12.14.0
+          runtime: node@22
+          cache: true
+          install: false
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
       - name: Publish CLI
-        run: cd packages/md-cli && npm publish --registry=https://registry.npmjs.org/
+        uses: changesets/action/publish@v2
+        with:
+          pack-dir-artifact-id: ${{ needs.pack.outputs.pack-dir-artifact-id }}
+        env:
+          NPM_CONFIG_PROVENANCE: true

AGENTS.md

@@ -36,8 +36,9 @@ pnpm install          # 安装所有依赖
 pnpm start            # 等同于 `pnpm web dev`
 pnpm run lint         # ESLint --fix 全项目检查
 pnpm run type-check   # vue-tsc 类型检查
-pnpm run build:cli    # 构建 web + 复制到 md-cli + npm pack
-pnpm run release:cli  # 通过 scripts/release.js 发布 CLI
+pnpm run build:cli    # 构建 web + 复制产物到 md-cli
+pnpm run pack:cli     # 构建并生成 CLI npm tarball
+pnpm changeset        # 记录下一次 CLI 发布的版本级别与更新说明
 pnpm utools:package   # 打包 uTools 插件
 pnpm run inspector    # node-modules-inspector 查看依赖树
 ```

CONTRIBUTING.md

@@ -76,23 +76,24 @@ pnpm web dev
    ```
 
 3. 编码 & 编写/更新测试。
-4. 运行检查：
+4. 如果变更需要随 npm CLI 发布，运行 `pnpm changeset`，选择 `@doocs/md-cli`、版本变更级别，并填写面向用户的更新说明。将生成的 `.changeset/*.md` 文件一并提交。
+5. 运行检查：
 
    ```bash
    pnpm run lint        # ESLint + Prettier
    pnpm run type-check  # TypeScript 类型检查
    pnpm web build       # 产物验证
    ```
 
-5. 提交并推送：
+6. 提交并推送：
 
    ```bash
    git add .
    git commit -m "feat: awesome feature"
    git push origin feat/awesome-feature
    ```
 
-6. 在 GitHub 页面发起 **Pull Request**，并按 [`.github/pull_request_template.md`](./.github/pull_request_template.md) 填写说明。
+7. 在 GitHub 页面发起 **Pull Request**，并按 [`.github/pull_request_template.md`](./.github/pull_request_template.md) 填写说明。
 
 > [!TIP]
 > 开发时可在 `apps/web` 目录下新建 `.env.local` 文件，配置 `VITE_LAUNCH_EDITOR` 为 `code` （默认值）或其他 [支持的编辑器](https://github.com/yyx990803/launch-editor?tab=readme-ov-file#supported-editors)，方便调试。

package.json

@@ -24,8 +24,11 @@
     "mcp": "pnpm --filter @md/mcp-server",
     "api": "pnpm --filter @md/api",
     "cli": "pnpm --filter @doocs/md-cli",
-    "build:cli": "pnpm web build && npx shx rm -rf packages/md-cli/dist && npx shx rm -rf dist/**/*.map && npx shx cp -r apps/web/dist packages/md-cli/ && cd packages/md-cli && npm pack",
-    "release:cli": "node ./scripts/release.js",
+    "build:cli": "pnpm web build && shx rm -rf packages/md-cli/dist && shx cp -r apps/web/dist packages/md-cli/",
+    "pack:cli": "pnpm run build:cli && pnpm --dir packages/md-cli pack",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "release:cli": "pnpm run build:cli && changeset publish",
     "lint": "eslint . --fix",
     "type-check": "pnpm type-check:web && pnpm type-check:packages",
     "type-check:web": "pnpm --filter @md/web run type-check",
@@ -37,6 +40,8 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "9.5.1",
+    "@changesets/changelog-github": "1.0.1",
+    "@changesets/cli": "3.0.2",
     "@types/node": "^26.6.5",
     "archiver": "^8.0.0",
     "eslint": "^10.13.0",

packages/md-cli/package.json

@@ -28,6 +28,10 @@
   "bugs": {
     "url": "https://github.com/doocs/md/issues"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "dependencies": {
     "express": "^5.3.0",
     "form-data": "4.0.6",