尝试配置 GitHub Actions

用 Gitea 自己搓 runner 还是难度太高力，还是用 GitHub Actions 吧~ QAQ

.github/workflows/deploy.yml

@@ -0,0 +1,75 @@
+# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
+#
+name: Deploy VitePress site to Pages
+
+on:
+  # 在针对 `main` 分支的推送上运行。如果你
+  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
+  push:
+    branches: [master]
+
+  # 允许你从 Actions 选项卡手动运行此工作流程
+  workflow_dispatch:
+
+# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
+# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # 构建工作
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
+      - uses: pnpm/action-setup@v3 # 如果使用 pnpm，请取消此区域注释
+        with:
+          version: 9
+      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm # 或 npm / yarn
+      # - name: Setup Pages
+      #   uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: pnpm ci # 或 npm install / yarn install / bun install
+      - name: Build with VitePress
+        run: pnpm docs:build # 或 npm run docs:build / yarn docs:build / bun run docs:build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: .vitepress/dist
+
+      # 上传至腾讯云COS
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.11'  # 设置 Python 版本
+
+      - name: Setup coscmd and sdk
+        run: pip install coscmd
+
+      - name: Configure coscmd
+        env:
+          SECRET_ID: ${{ secrets.SECRET_ID }}
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+          BUCKET: suan-docs-1309266774
+          REGION: ap-nanjing
+        run: coscmd config -a $SECRET_ID -s $SECRET_KEY -b $BUCKET -r $REGION
+
+      - name: Upload to COS
+        run: |
+          coscmd upload -rfs --delete .vitepress/dist/ /

.vitepress/config.mts

@@ -17,6 +17,7 @@ export default defineConfig({
           { text: '介绍', link: '/suan-api/introduction' },
           { text: '部署', link: '/suan-api/deploy' },
           { text: 'Playwright', link: '/suan-api/playwright' },
+          { text: 'API 文档', link: '/suan-api/api-docs' },
           { text: 'LLM 工具', link: '/suan-api/llm-tools' },
         ]
       },

suan-api/api-docs.md

@@ -0,0 +1,22 @@
+# API 文档
+
+Suan API 公开的 API 端点为 `/api`，不需要身份验证即可调用。
+
+在 WebUI 中的「**课表管理**」页面可以查看该版本的 Suan API 提供的公共 API 信息，在 FastAPI 自带的 `/docs` 端点中也可以查看所有 API 的文档。本文档记录的信息默认为最新版本的，并且进行稍详细的介绍，如果你没有使用最新版本的话，可能会有不一样。
+
+## 返回值
+
+大部分端点都会返回统一的结构化数据。在 Suan API 内部的定义如下：
+
+```python
+# router/enhance/lib.py
+class ReturnDto(BaseModel):
+    success: bool
+    message: str | None = None
+    result: Any | None = None
+    img_url: str | None = None
+```
+
+请求得到的响应的状态码也是很重要的信息。对于大部分端点来说，状态码反映的是服务器内部是否出现意料之外的错误（`5XX`），而返回值中的 `success` 字段表示的是请求在业务上是否成功。
+
+`img_url` 是否存在是根据请求时是否有 `img: True` 来决定的，默认为 False。生成图片需要使用 Playwright 进行截图，在服务器上对于性能开销稍大，因此不会默认启用。

suan-api/playwright.md

@@ -1,3 +1,9 @@
 # Playwright
 
 Playwright 是一个用于浏览器自动化的工具，Suan API 通过 playwright 来规避教务系统和统一身份认证的反爬虫措施，顺便用它来截图。
+
+## 安装
+
+Playwright 需要额外的安装步骤，在 [部署](deploy.md) 中已经说明。
+
+在开发中芒果直接使用的是 chromium，暂未测试其他选项（firefox），不过我估计应该也没什么问题就是了~