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