更新部署信息和项目介绍

配合 NJUPT Suan API v0.1.1 更新一下文档的基本内容~

.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 install # 或 npm ci / 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' },
         ]
       },

astrbot-plugin/introduction.md

@@ -14,8 +14,9 @@ NJUPT Suan 当中的 `Suan` 是芒果酸酸的酸，本插件为 Astrbot 中运
 
 ### 生成课程表
 
-NJUPT-MCP 包含了[能够返回课程表数据的工具](/njupt-mcp/llm-tools.md)。NJUPT Suan 可以根据 NJUPT-MCP 的返回数据渲染课程表图片，
+:::info 已归档
-目前版本的渲染效果如下。
+不再支持生成以下图片。
+:::
 
 ![单日课表](/image/astrbot-plugin-schedule-1.png)
 

readme.md

@@ -5,14 +5,14 @@
 **芒果酸**、**芒果酸酸**、**Mango Suan** 都是本项目的代称。本项目包含以下子项目：
 
 * **NJUPT-Suan-API** - API 与 MCP 服务器，向调用客户端以及 LLM 工具返回数据；
-* **astrbot_plugin_njupt_suan** - Astrbot 插件，需要结合 njupt-mcp 使用，提升交互体验。
+* *astrbot_plugin_njupt_suan*（已归档） - Astrbot 插件，需要结合 ~~njupt-mcp~~ 使用，提升交互体验。
 * **SuanDocs** - 文档项目，本文档站点。
 
 本项目的有关仓库均位于 **[Mango Gitea](https://gitea.mangofanfan.cn)** 上，这是芒果帆帆自己的 Gitea 实例，用于存放这些代码仓库。
 
 当芒果帆帆认为某个仓库的代码已经足够见人时，会将仓库公开至 GitHub，以方便任何人更方便地使用。
 
-项目中的部分代码由 Kimi code 完成，芒果帆帆在其中起到一个吉祥物的作用。因此你也无需认真对待这些代码。
+项目中的部分代码由 Kimi code 完成。
 
 ## 反馈
 

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/deploy.md

@@ -2,22 +2,55 @@
 
 酸 API 同时具备 API 和 MCP 后端的功能。因此，酸 API 不支持 stdio 格式的 MCP 调用。
 
+## cli 命令
+
+NJUPT Suan API 现在拥有一个 cli 命令行，可以作为入口以及管理工具。在设计上，这个命令行工具叫做 `njupt-suan-api`，与包名一致。
+
+|命令|简介|
+|--|--|
+|init|初始化 NJUPT Suan API，包括创建工作目录、创建配置文件以及下载 playwright chromium|
+|token|显示以及生成新的管理后端令牌|
+|run|运行 NJUPT Suan API，支持传入 host port reload 参数|
+
+使用 `njupt-suan-api --version` 查看已安装的 NJUPT Suan API 版本。
+
+cli 拥有完整的帮助文档，你可以使用 `--help` 查看。
+
+cli 的启动速度可能有些慢，这是因为 cli 会加载许多基于 FastAPI 工作的模块，这是一个技术性妥协，需要等待未来再优化了。
+
 ## 部署 Suan API 示例
 
 目前的 Suan API 在设计上即不允许（或者说不适合）公开部署、公共服务，因此你需要自行部署 Suan API 实例。
 
 ### 使用 uv 部署
 
+芒果已经把 NJUPT Suan API 做成一个 uv 工具，你现在可以直接用如下命令部署它。
+
+```bash
+# 先指定一个工作目录，建议创建一个新文件夹。
+mkdir xxx
+cd xxx
+
+# 将 njupt-suan-api 作为工具安装，指定 Python 版本为 3.13。
+uv tool install njupt-suan-api -p 3.13
+
+# 在当前目录下初始化。
+# 也可以使用 uvx njupt-suan-api 来调用，下同。
+njupt-suan-api init -f
+
+# 运行项目。
+# 数据会存储在当前目录下，因此你每次都需要在当前目录下运行 Suan API，设计为之。
+njupt-suan-api run
+```
+
+初始化时需要加上 `-f` 是一个技术性妥协，芒果需要研究一些更优雅的解决方法。不过目前是可以使用的，芒果已经在 Windows 和 Linux 上做过测试了~
+
 ### 使用 Docker 部署
 
+感觉 Docker 好麻烦啊，等我再研究研究好嘛。
+
 ### 从源码部署
 
-:::warning 性能警告
-直接从 `main.py` 入口运行可能会导致一些潜在的性能问题，表现为 Suan API 会占用较多的性能，而这可能不是你希望看到的。
-
-等芒果帆帆再完善完善，然后争取提供其他更方便的部署选项吧~
-:::
-
 使用 git 命令从 Mango Gitea 上拉取源代码：
 
 ```bash
@@ -42,21 +75,28 @@ uv run playwright install chromium
 
 这将会安装 chromium 供 playwright 使用。Suan API 通过这个 chromium 来模拟真实用户行为，以及截取课程表图片。
 
-安装 chromium 可能需要一段**比较长的时间**。大体上这是能够成功的，只是需要一段**比较长的时间**。
+安装 chromium 可能需要一段**比较长的时间**。
 
-然后（或者同时），在 `NJUPT-Suan-API/webui` 目录下运行：
+如需从源码运行，你还需要自行构建 WebUI。请在 `NJUPT-Suan-API/webui` 目录下运行：
 
 ```bash
 pnpm install
 pnpm build
 ```
 
-这将会安装 WebUI 所使用的依赖，然后构建 WebUI。这一般是很快的。
+这将会安装 WebUI 所使用的依赖，然后构建 WebUI。这一般是很快的。WebUI 的构建产物位于 `src/njupt_suan_api/static` 中，该目录已经位于 `.gitignore` 中，无需担心其被 git 管理。
 
 现在，回到 `NJUPT-Suan-API` 目录下，使用以下命令启动项目：
 
 ```bash
-uv run main.py
+uv run src/njupt_suan_api/manage.py init -f
+uv run src/njupt_suan_api/manage.py run
+```
+
+或者从 `main.py` 入口启动，但不建议，未来可能会移除 `main.py`。
+
+```bash
+uv run src/njupt_suan_api/main.py
 ```
 
 NJUPT Suan API 应当可以正常启动。

suan-api/introduction.md

@@ -10,6 +10,8 @@ API 是这个东西的工作，作为 API，以及 MCP。
 
 MCP 是模型上下文协议，用于给 LLM 提供可供调用的工具。
 
+NJUPT Suan API 已经可以使用，查看[部署](./deploy.md)页面了解如何部署。在仓库中查看最新的版本日志（[GitHub](https://github.com/mangofanfan/NJUPT-Suan-API/blob/master/CHANGELOG.md)|[Mango Gitea](https://gitea.mangofanfan.cn/SuanDev/NJUPT-Suan-API/src/branch/master/CHANGELOG.md)）。
+
 ## 特别说明
 
 由于在网络上缺少与南京邮电大学相关的 Web API，已有的项目（[NJUPT-API](https://github.com/gaoliang/NJUPT-API)）也已经年久失修，

suan-api/llm-tools.md

@@ -1,127 +1,17 @@
 # LLM 工具
 
-## 课表工具
+LLM 工具是 NJUPT Suan API 为 LLM 提供的可调用 MCP 协议工具。
 
-### get_course_schedule_json
+MCP 接口端点为 `/mcp`，支持 streamable HTTP 模式。
 
-```python
+把给 LLM 使用的工具详细介绍给人类看似乎有些不太合适。请放心，Suan API 为工具提供详细的文档和参数注释，LLM 一定看得懂~
-@mcp.tool(
-    name="get_course_schedule_json",
-    title="获取课表 JSON",
-    description="以 JSON 格式获取整学期整周全部课表数据，可选择是否压缩",
-    annotations=ToolAnnotations(
-        title="获取课表 JSON",
-        readOnlyHint=True,  # 只读取数据，不修改
-        destructiveHint=False,  # 非破坏性操作
-        idempotentHint=True,  # 幂等：重复调用结果相同
-        openWorldHint=False,  # 不依赖外部世界状态
-    ),
-)
-async def get_course_schedule_json(compressed: bool = False) -> list[dict] | list[tuple]:
-    """以 JSON 格式获取整学期整周全部课表
 
-    Args:
+## 图片说明
-        compressed: 是否压缩为紧凑的元组格式，默认为 False
 
-    Returns:
+课表工具可能会返回课程表图片的 URL。与 API 调用时一样，该 URL 是临时的，计划在 Suan API 的正式版本中设计为固定时间内有效、超时后删除。当前，图片会在 Suan API 重启后清理。
-        未压缩时（compressed=False）：
-            课程字典列表，每个课程包含：
-            - name: 课程名称
-            - teacher: 授课教师（可能为 None）
-            - classroom: 教室（可能为 None）
-            - weeks: 周数，list[int]
-            - day: 星期几，int
-            - classes: 当日第几节课，list[int]
-        压缩时（compressed=True）：
-            元组列表 (name, teacher, classroom, weeks_str, day, classes)
-            其中 weeks_str 为压缩后的周数字符串（如 "1-17"）
-        失败时返回空列表
-    """
-```
 
-LLM 在调用时可以选择是否压缩。
+Suan API 提供一个专门返回图片本身的 LLM 工具，以帮助 LLM 将课程表图片直接包含在对话数据中，避免随着图片超时被删除而丢失。
 
-请注意，[NJUPT Suan](/astrbot-plugin/introduction.md) 提供的渲染课表图片的工具需要经过压缩的课程数据，否则调用时很可能会由于参数过长而失败。
+## 工具文档
 
-### get_week_course_schedule_json
+工具文档也被包含在 WebUI 中。
-
-```python
-@mcp.tool(
-    name="get_week_course_schedule_json",
-    title="获取指定周课表",
-    description="以 JSON 格式获取指定教学周的全部课表数据，可选择是否压缩",
-    annotations=ToolAnnotations(
-        title="获取指定周课表",
-        readOnlyHint=True,  # 只读取数据，不修改
-        destructiveHint=False,  # 非破坏性操作
-        idempotentHint=True,  # 幂等：重复调用结果相同
-        openWorldHint=False,  # 不依赖外部世界状态
-    ),
-)
-async def get_week_course_schedule_json(week: int, compressed: bool = False) -> list[dict] | list[tuple]:
-    """以 JSON 格式获取指定教学周的全部课表
-
-    Args:
-        week: 教学周数，范围通常为 1-20
-        compressed: 是否压缩为紧凑的元组格式，默认为 False
-
-    Returns:
-        未压缩时（compressed=False）：
-            指定周的课程字典列表，每个课程包含：
-            - name: 课程名称
-            - teacher: 授课教师（可能为 None）
-            - classroom: 教室（可能为 None）
-            - weeks: 周数，list[int]
-            - day: 星期几，int (1-7)
-            - classes: 当日第几节课，list[int]
-        压缩时（compressed=True）：
-            元组列表 (name, teacher, classroom, weeks_str, day, classes)
-            其中 weeks_str 为压缩后的周数字符串
-        该周无课程或参数错误时返回空列表
-    """
-```
-
-同上。
-
-### get_week_day_course_schedule_json
-
-```python
-@mcp.tool(
-    name="get_week_day_course_schedule_json",
-    title="获取指定周星期课表",
-    description="以 JSON 格式获取指定教学周和星期的课表数据，可选择是否压缩",
-    annotations=ToolAnnotations(
-        title="获取指定周星期课表",
-        readOnlyHint=True,  # 只读取数据，不修改
-        destructiveHint=False,  # 非破坏性操作
-        idempotentHint=True,  # 幂等：重复调用结果相同
-        openWorldHint=False,  # 不依赖外部世界状态
-    ),
-)
-async def get_week_day_course_schedule_json(week: int, day: int, compressed: bool = False) -> list[dict] | list[tuple]:
-    """以 JSON 格式获取指定教学周和星期的课表
-
-    Args:
-        week: 教学周数，范围通常为 1-20
-        day: 星期几，1=星期一，2=星期二，...，7=星期日
-        compressed: 是否压缩为紧凑的元组格式，默认为 False
-
-    Returns:
-        未压缩时（compressed=False）：
-            指定周和星期的课程字典列表，每个课程包含：
-            - name: 课程名称
-            - teacher: 授课教师（可能为 None）
-            - classroom: 教室（可能为 None）
-            - weeks: 周数，list[int]
-            - day: 星期几，int (1-7)
-            - classes: 当日第几节课，list[int]
-        压缩时（compressed=True）：
-            元组列表 (name, teacher, classroom, weeks_str, day, classes)
-            其中 weeks_str 为压缩后的周数字符串
-        该时段无课程或参数错误时返回空列表
-    """
-```
-
-同上。
-
-此三个工具的返回格式是统一的。

suan-api/playwright.md

@@ -1,3 +1,17 @@
 # Playwright
 
-Playwright 是一个用于浏览器自动化的工具，Suan API 通过 playwright 来规避教务系统和统一身份认证的反爬虫措施，顺便用它来截图。
+playwright 是一个用于浏览器自动化的工具，Suan API 通过 playwright 来规避教务系统和统一身份认证的反爬虫措施，顺便用它来截图。
+
+## 安装
+
+playwright chromium 的安装会在 `suanapi init` 初始化过程中完成。
+
+如需从源代码运行，则 playwright 需要额外的安装步骤，在 [部署](deploy.md) 中已经说明。
+
+在开发中芒果直接使用的是 chromium，暂未测试其他选项（firefox），不过我估计应该也没什么问题就是了~
+
+## 截图
+
+课程表图片是使用其来渲染的，渲染效果如下。
+
+![芒果酸也要上课](/image/njupt-suan-api-schedule-1.png)