[codex] 自动化网站部署与 npm 发布

.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  cli:
+    name: CLI / Node ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version:
+          - 18
+          - 20
+          - 22
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Run CLI tests
+        run: npm test
+
+      - name: Verify npm package contents
+        run: npm run pack:check
+
+  website:
+    name: Astro website
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install website dependencies
+        working-directory: website
+        run: npm ci
+
+      - name: Build website
+        working-directory: website
+        run: npm run build

.github/workflows/deploy-pages.yml

@@ -0,0 +1,63 @@
+name: Deploy website to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - .github/workflows/deploy-pages.yml
+      - docs/**
+      - website/**
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Astro website
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install dependencies
+        working-directory: website
+        run: npm ci
+
+      - name: Build website
+        working-directory: website
+        run: npm run build
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/dist
+
+  deploy:
+    name: Deploy GitHub Pages
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish-npm.yml

@@ -0,0 +1,59 @@
+name: Publish package to npm
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: npm-publish-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish @double-coding/flow2spec
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out release commit
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Verify release commit belongs to main
+        shell: bash
+        run: |
+          git fetch origin main
+          git merge-base --is-ancestor HEAD origin/main
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Update npm for trusted publishing
+        run: npm install --global npm@latest
+
+      - name: Verify tag matches package version
+        shell: bash
+        run: |
+          package_version="$(node -p "require('./package.json').version")"
+          tag_version="${GITHUB_REF_NAME#[vV]}"
+          if [[ "$tag_version" != "$package_version" ]]; then
+            echo "Release tag $GITHUB_REF_NAME does not match package version $package_version." >&2
+            exit 1
+          fi
+
+      - name: Run tests
+        run: npm test
+
+      - name: Verify npm package contents
+        run: npm run pack:check
+
+      - name: Publish package with provenance
+        run: npm publish --access public --provenance

docs/发布与部署.md

@@ -0,0 +1,46 @@
+# 发布与部署
+
+Flow2Spec 使用 GitHub Actions 分别处理持续集成、网站部署和 npm 正式发布。维护者不再直接修改或推送 `gh-pages`。
+
+## 持续集成
+
+`.github/workflows/ci.yml` 在 Pull Request 和 `main` 推送时执行：
+
+- Node.js 18、20、22 下运行 CLI 测试与 npm 打包检查；
+- Node.js 22 下安装网站依赖并构建 Astro 静态站点。
+
+## 网站部署
+
+`.github/workflows/deploy-pages.yml` 在 `main` 中的 `website/`、`docs/` 或部署工作流发生变化时触发，也支持在 Actions 页面手动执行。
+
+仓库必须在 **Settings -> Pages -> Build and deployment** 中将 Source 设为 **GitHub Actions**。工作流构建 `website/dist`，通过官方 Pages artifact 发布，不再提交生成文件到 `gh-pages`。
+
+## npm 正式发布
+
+`.github/workflows/publish-npm.yml` 只在 GitHub Release 发布时触发。发布前依次校验：
+
+1. Release 对应的提交属于 `main`；
+2. Tag（`v3.3.0` 或 `V3.3.0`）与 `package.json` 版本一致；
+3. CLI 测试通过；
+4. `npm pack --dry-run` 通过。
+
+全部通过后，工作流使用 npm Trusted Publishing（OIDC）执行带 provenance 的公开发布，不需要在 GitHub 保存长期 `NPM_TOKEN`。
+
+首次启用时，在 npmjs.com 的 `@double-coding/flow2spec` 包设置中添加 GitHub Actions Trusted Publisher：
+
+| 字段 | 值 |
+| --- | --- |
+| Organization or user | `double-coding-lab` |
+| Repository | `Flow2Spec` |
+| Workflow filename | `publish-npm.yml` |
+| Environment | 留空 |
+
+正式发布顺序：
+
+1. 在分支中修改 `package.json` 版本并完成 PR；
+2. PR 合并到 `main`；
+3. 在合并提交上创建匹配版本的 Git Tag；
+4. 基于该 Tag 创建并发布 GitHub Release；
+5. 在 Actions 中确认 `Publish package to npm` 成功。
+
+失败的发布不得通过修改同一版本重试；修复后递增版本，再创建新的 Tag 与 Release。

scripts/sync-gh-pages.sh

@@ -1,105 +1,17 @@
 #!/usr/bin/env bash
-# sync-gh-pages.sh — 把 presentations/ 下的中英文 PPT 同步到 gh-pages 分支
-#
-# 用法（在仓库根执行）:
-#   ./scripts/sync-gh-pages.sh
-#
-# 做了什么:
-#   1. 校验工作区（允许从 main / dev_v3 执行）
-#   2. 校验 html-ppt skill assets 存在
-#   3. 切 gh-pages，用源 PPT + skill assets 重新铺一遍
-#   4. 中文版放根目录，英文版放 /en/
-#   5. 改 index.html 资源路径为同级 assets/
-#   6. 提交并 push
-#   7. 自动切回原分支
-
 set -euo pipefail
 
-TARGET_BRANCH="gh-pages"
-PUB_DIR="presentations/flow2spec-intro-public"
-PUB_DIR_EN="presentations/flow2spec-intro-public-en"
-SKILL_ASSETS=".claude/skills/html-ppt/assets"
-
-err() { printf '\033[31m[x]\033[0m %s\n' "$*" >&2; exit 1; }
-ok()  { printf '\033[32m[ok]\033[0m %s\n' "$*"; }
-info(){ printf '\033[36m[i]\033[0m %s\n' "$*"; }
-
-# 1. 前置检查
-[[ -d .git ]] || err "请在仓库根执行"
-
-SOURCE_BRANCH=$(git rev-parse --abbrev-ref HEAD)
-info "源分支: $SOURCE_BRANCH"
-
-if [[ -n "$(git status --porcelain)" ]]; then
-  err "工作区不干净，请先提交或 stash"
-fi
-
-[[ -d "$PUB_DIR" ]]       || err "找不到 $PUB_DIR"
-[[ -d "$SKILL_ASSETS" ]]  || err "找不到 $SKILL_ASSETS（需先 npx skills add html-ppt）"
-
-# 2. 快照到临时目录
-SNAP=$(mktemp -d)
-trap 'rm -rf "$SNAP"' EXIT
-
-# 中文版 → 根
-cp "$PUB_DIR"/index.html "$PUB_DIR"/style.css "$SNAP/"
-[[ -f "$PUB_DIR"/market-compare.md ]] && cp "$PUB_DIR"/market-compare.md "$SNAP/"
-[[ -f presentations/scroll-hint.js ]] && cp presentations/scroll-hint.js "$SNAP/"
-cp -rL "$SKILL_ASSETS" "$SNAP/assets"
-
-# 英文版 → /en/
-if [[ -d "$PUB_DIR_EN" ]]; then
-  mkdir -p "$SNAP/en"
-  cp "$PUB_DIR_EN"/index.html "$PUB_DIR_EN"/style.css "$SNAP/en/"
-  # en 版共享同一份 assets（用相对路径 ../assets/）
-  sed -i '' 's|\.\./\.\./\.claude/skills/html-ppt/assets/|../assets/|g' "$SNAP/en/index.html"
-  ok "英文版已加入 /en/"
-else
-  info "未找到英文版 ($PUB_DIR_EN)，跳过"
-fi
-
-# 改中文版 index.html 资源路径: ../../.claude/skills/html-ppt/assets/ → assets/
-sed -i '' 's|\.\./\.\./\.claude/skills/html-ppt/assets/|assets/|g' "$SNAP/index.html"
-sed -i '' 's|src="../scroll-hint.js"|src="scroll-hint.js"|g' "$SNAP/index.html"
-
-ok "快照已准备: $SNAP"
-
-# 3. 切 gh-pages 并更新
-git checkout "$TARGET_BRANCH"
-
-# 清空除 .git 外的内容
-find . -mindepth 1 -maxdepth 1 ! -name .git ! -name .agents -exec rm -rf {} +
-
-cp -r "$SNAP"/. .
-
-# 写/保留 README
-cat > README.md <<'MD'
-# Flow2Spec · Presentation
-
-13-slide HTML PPT demonstrating how Flow2Spec keeps AI "always in context" across sessions.
-
-**Live (Chinese)**: https://double-coding-lab.github.io/Flow2Spec
-
-**Live (English)**: https://double-coding-lab.github.io/Flow2Spec
-
-**Keyboard**: ← → navigate · `T` toggle theme · `S` speaker mode · `F` fullscreen · `O` overview
+cat >&2 <<'EOF'
+Flow2Spec website deployment is managed by GitHub Actions.
 
-Main repo: https://github.com/double-coding-lab/Flow2Spec
-MD
+Merge website or docs changes into main to trigger:
+  .github/workflows/deploy-pages.yml
 
-git add -A
+For a local production build, run:
+  npm --prefix website ci
+  npm --prefix website run build
 
-if git diff --cached --quiet; then
-  info "gh-pages 内容无变化，无需提交"
-else
-  MSG="🔄 sync: deploy zh+en from $SOURCE_BRANCH @ $(git rev-parse --short "$SOURCE_BRANCH")"
-  git commit -m "$MSG"
-  git push origin "$TARGET_BRANCH"
-  ok "已推送: $MSG"
-fi
+This legacy script no longer writes or pushes the gh-pages branch.
+EOF
 
-git checkout "$SOURCE_BRANCH"
-ok "已切回 $SOURCE_BRANCH"
-echo ""
-echo "📍 中文版: https://double-coding-lab.github.io/Flow2Spec"
-echo "📍 英文版: https://double-coding-lab.github.io/Flow2Spec"
+exit 1