From 35e501aabb900b42e30f34ceec8bac8b8d49f9bf Mon Sep 17 00:00:00 2001
From: snowy-yang <102860110+snowy-yang@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:18:39 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20Gitea=20Actions=E2=80=94=E2=80=94ruff/p?=
 =?UTF-8?q?yright=20=E6=A3=80=E6=B5=8B=E4=B8=8E=20Cloudflare=20Pages=20?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=87=AA=E5=8A=A8=E9=83=A8=E7=BD=B2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- .gitea/workflows/ci.yml：push(main)/PR/手动触发，setup-uv 装依赖
  后运行与本地一致的 uv run ruff check src tests examples + uv run
  pyright；故意未加 ruff format --check（存量 5 文件格式漂移会打红）
- .gitea/workflows/deploy-docs.yml：main 的文档文件变更时自动部署，
  经 CLOUDFLARE_API_TOKEN/CLOUDFLARE_ACCOUNT_ID secrets 鉴权
- scripts/deploy_docs.sh：组装纯文档 dist/（不含源码，排除
  __pycache__）后 wrangler Direct Upload 上传——CF Pages 的 Git 直连
  只支持 GitHub/GitLab，Gitea 仓库只能走 Direct Upload；新版
  wrangler 的 pages deploy 不再自动建项目，脚本先幂等 create

站点 https://qqbotsdk-docs.pages.dev 已上线。.wrangler/ 缓存与
dist/ 产物入 .gitignore。
---
 .gitea/workflows/ci.yml          | 30 ++++++++++++++++++++++++++++++
 .gitea/workflows/deploy-docs.yml | 29 +++++++++++++++++++++++++++++
 .gitignore                       |  4 ++++
 scripts/deploy_docs.sh           | 26 ++++++++++++++++++++++++++
 4 files changed, 89 insertions(+)
 create mode 100644 .gitea/workflows/ci.yml
 create mode 100644 .gitea/workflows/deploy-docs.yml
 create mode 100644 scripts/deploy_docs.sh

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
new file mode 100644
index 0000000..0c69562
--- /dev/null
+++ b/.gitea/workflows/ci.yml
@@ -0,0 +1,30 @@
+name: 代码检测
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  lint:
+    name: ruff + pyright
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 安装 uv 与 Python 3.13
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: 同步依赖（含 dev 组）
+        run: uv sync
+
+      - name: ruff 静态检查
+        run: uv run ruff check src tests examples
+
+      - name: pyright 类型检查
+        run: uv run pyright
diff --git a/.gitea/workflows/deploy-docs.yml b/.gitea/workflows/deploy-docs.yml
new file mode 100644
index 0000000..61bb6e3
--- /dev/null
+++ b/.gitea/workflows/deploy-docs.yml
@@ -0,0 +1,29 @@
+name: 部署文档
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "index.html"
+      - "_sidebar.md"
+      - "README.md"
+      - "docs/**"
+      - "examples/**"
+      - "CHANGELOG.md"
+      - "scripts/deploy_docs.sh"
+      - ".gitea/workflows/deploy-docs.yml"
+  workflow_dispatch:
+
+jobs:
+  deploy-docs:
+    name: Cloudflare Pages
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 组装并部署（wrangler Direct Upload）
+        run: bash scripts/deploy_docs.sh
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
diff --git a/.gitignore b/.gitignore
index b2ff37d..f691a1a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,10 @@ __pycache__/
 .ruff_cache/
 .pytest_cache/
 
+# 文档部署产物（scripts/deploy_docs.sh 组装）
+dist/
+.wrangler/
+
 # 编辑器/IDE
 .vscode/
 .zcode/
diff --git a/scripts/deploy_docs.sh b/scripts/deploy_docs.sh
new file mode 100644
index 0000000..65b0bb5
--- /dev/null
+++ b/scripts/deploy_docs.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# 组装纯文档目录并部署到 Cloudflare Pages（docsify 零构建，Direct Upload）。
+#
+# 用法：scripts/deploy_docs.sh [项目名]     # 项目名默认取 PROJECT_NAME，再默认 qqbotsdk-docs
+# 本地首次运行会自动唤起 wrangler 浏览器授权（或预先 export CLOUDFLARE_API_TOKEN）；
+# 项目不存在时 wrangler 会自动创建，站点地址 https://<项目名>.pages.dev。
+# CI（.gitea/workflows/deploy-docs.yml）经 CLOUDFLARE_API_TOKEN/CLOUDFLARE_ACCOUNT_ID 鉴权调用本脚本。
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+PROJECT_NAME="${1:-${PROJECT_NAME:-qqbotsdk-docs}}"
+
+rm -rf dist
+mkdir dist
+# docsify 站点只由这些 markdown 和 index.html 组成，静态资源全部走 CDN——
+# 只挑文档文件，不把源码仓库整个传上站点
+cp index.html README.md _sidebar.md CHANGELOG.md dist/
+cp -r docs examples dist/
+cp .nojekyll dist/ 2>/dev/null || true
+# examples/ 里的 Python 字节码缓存不该上站点
+find dist -type d -name __pycache__ -exec rm -rf {} +
+
+# 新版 wrangler 的 pages deploy 不再自动建项目：先幂等创建（已存在则忽略报错）
+npx wrangler pages project create "$PROJECT_NAME" --production-branch=main >/dev/null 2>&1 || true
+npx wrangler pages deploy dist --project-name="$PROJECT_NAME" --branch=main --commit-dirty=true