Document release flow and add manual PyPI workflow

Author: oceanusXXD

.github/workflows/publish-pypi.yml

@@ -0,0 +1,61 @@
+name: Publish PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      expected_version:
+        description: "Package version expected from the selected ref, for example 0.1.6"
+        required: true
+        type: string
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install release dependencies
+        run: python -m pip install -e .[release]
+
+      - name: Validate version
+        shell: bash
+        run: |
+          python - <<'PY'
+          import pathlib
+          import tomllib
+          import sys
+
+          root = pathlib.Path(".")
+          sys.path.insert(0, str(root / "src"))
+          from code2skill import __version__
+
+          expected = "${{ inputs.expected_version }}"
+          pyproject = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+          declared = pyproject["project"]["version"]
+          if declared != expected:
+              raise SystemExit(f"Expected version {expected}, but pyproject version is {declared}.")
+          if __version__ != expected:
+              raise SystemExit(f"Expected version {expected}, but runtime version is {__version__}.")
+          PY
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package metadata
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

README.md

@@ -456,90 +456,19 @@ Common reasons to fall back to a full rebuild:
 - cached state was generated for a different repository root
 
 Recommended GitHub Actions workflow:
-
-```yaml
-name: code2skill
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  build-skills:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Restore code2skill cache
-        uses: actions/cache@v4
-        with:
-          path: .code2skill
-          key: code2skill-${{ runner.os }}-${{ github.ref_name }}-${{ github.sha }}
-          restore-keys: |
-            code2skill-${{ runner.os }}-${{ github.ref_name }}-
-            code2skill-${{ runner.os }}-
-
-      - name: Install
-        run: pip install code2skill
-
-      - name: Run code2skill
-        env:
-          QWEN_API_KEY: ${{ secrets.QWEN_API_KEY }}
-          CODE2SKILL_LLM: qwen
-          CODE2SKILL_MODEL: qwen-plus-latest
-        run: |
-          code2skill ci \
-            --mode auto \
-            --base-ref origin/${{ github.base_ref || 'main' }} \
-            --head-ref HEAD
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: code2skill-output
-          path: .code2skill
-```
+See [CI Guide](./docs/ci.md) for a consumer workflow example and the checked-in repository workflows.
 
 Notes:
 
 - `fetch-depth: 0` matters, otherwise the base ref may not exist locally.
 - Caching `.code2skill` is what enables fast incremental reuse.
 - The first CI run on a branch usually behaves like a full build because there is no prior state.
 - If you want a no-LLM CI sanity check, use `code2skill ci --mode auto --structure-only`.
-- This repository now includes checked-in workflows under `.github/workflows/` for CI and tagged releases.
+- This repository now includes checked-in workflows under `.github/workflows/` for CI, GitHub Releases, and manual PyPI publication.
 
 ## Output Layout
 
-Typical output:
-
-```text
-.code2skill/
-  project-summary.md
-  skill-blueprint.json
-  skill-plan.json
-  report.json
-  references/
-    architecture.md
-    code-style.md
-    workflows.md
-    api-usage.md
-  skills/
-    index.md
-    *.md
-  state/
-    analysis-state.json
-```
+See [Output Layout](./docs/output-layout.md) for the command-by-command artifact matrix and adapted target files.
 
 ## Typical Use Cases
 

README.zh-CN.md

@@ -455,90 +455,19 @@ code2skill estimate --pricing-file pricing.json
 - 缓存 state 记录的 `repo_root` 与当前仓库根目录不一致
 
 推荐的 GitHub Actions 配置：
-
-```yaml
-name: code2skill
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  build-skills:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Restore code2skill cache
-        uses: actions/cache@v4
-        with:
-          path: .code2skill
-          key: code2skill-${{ runner.os }}-${{ github.ref_name }}-${{ github.sha }}
-          restore-keys: |
-            code2skill-${{ runner.os }}-${{ github.ref_name }}-
-            code2skill-${{ runner.os }}-
-
-      - name: Install
-        run: pip install code2skill
-
-      - name: Run code2skill
-        env:
-          QWEN_API_KEY: ${{ secrets.QWEN_API_KEY }}
-          CODE2SKILL_LLM: qwen
-          CODE2SKILL_MODEL: qwen-plus-latest
-        run: |
-          code2skill ci \
-            --mode auto \
-            --base-ref origin/${{ github.base_ref || 'main' }} \
-            --head-ref HEAD
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: code2skill-output
-          path: .code2skill
-```
+完整示例见 [CI Guide](./docs/ci.md)。该文档同时说明了仓库内已提供的 workflow。
 
 说明：
 
 - `fetch-depth: 0` 很重要，否则 base ref 可能不在本地历史里
 - 缓存 `.code2skill` 是增量提速的关键
 - 一个分支上的第一次 CI 通常接近 `full`，因为还没有历史 state
 - 如果只想做不调用 LLM 的 CI 健康检查，可以运行 `code2skill ci --mode auto --structure-only`
-- 当前仓库已经提供 `.github/workflows/` 下的 CI 和 release workflow
+- 当前仓库已经提供 `.github/workflows/` 下的 CI、GitHub Release 和手动 PyPI 发布 workflow
 
 ## 输出目录
 
-典型输出如下：
-
-```text
-.code2skill/
-  project-summary.md
-  skill-blueprint.json
-  skill-plan.json
-  report.json
-  references/
-    architecture.md
-    code-style.md
-    workflows.md
-    api-usage.md
-  skills/
-    index.md
-    *.md
-  state/
-    analysis-state.json
-```
+按命令区分的产物矩阵和适配后文件位置见 [Output Layout](./docs/output-layout.md)。
 
 ## 典型场景
 

docs/ci.md

@@ -18,6 +18,7 @@ This repository includes checked-in workflows under `.github/workflows/`:
 
 - `ci.yml`: test matrix, build, metadata check, and install smoke test
 - `release.yml`: version validation, build, metadata check, and GitHub Release creation on version tags
+- `publish-pypi.yml`: manual PyPI publication workflow
 
 The README includes a sample consumer workflow for running `code2skill` inside another repository.
 

docs/release.md

@@ -53,9 +53,23 @@ This repository includes:
 
 - `.github/workflows/ci.yml`: unit tests plus package build and install smoke check
 - `.github/workflows/release.yml`: version validation, build, `twine check`, and GitHub Release creation on version tags
+- `.github/workflows/publish-pypi.yml`: manual PyPI publishing from a selected ref
 
 The checked-in release workflow is intentionally repository-focused. It does not publish to PyPI automatically.
-If you want package publishing later, treat that as a separate manual or dedicated workflow concern.
+PyPI publishing is handled separately through the manual `publish-pypi.yml` workflow.
+
+## Manual PyPI Publish
+
+Use `.github/workflows/publish-pypi.yml` only when you explicitly want to publish a built version to PyPI.
+
+Recommended flow:
+
+1. prepare and push the final release commit
+2. make sure the version in `pyproject.toml` and `src/code2skill/__init__.py` is final
+3. run the `Release` workflow via a version tag so GitHub Release creation succeeds
+4. manually run `Publish PyPI` from the same ref and provide the exact version string
+
+This keeps repository release automation and package publication separate.
 
 ## Manual Release Safety Notes