初始提交

初始提交目前已有的文档和基础设置。
此提交还不包含 .gitignore 等文件。

suan-api/deploy.md

@@ -0,0 +1,62 @@
+# 部署
+
+酸 API 同时具备 API 和 MCP 后端的功能。因此，酸 API 不支持 stdio 格式的 MCP 调用。
+
+## 部署 Suan API 示例
+
+目前的 Suan API 在设计上即不允许（或者说不适合）公开部署、公共服务，因此你需要自行部署 Suan API 实例。
+
+### 使用 uv 部署
+
+### 使用 Docker 部署
+
+### 从源码部署
+
+:::warning 性能警告
+直接从 `main.py` 入口运行可能会导致一些潜在的性能问题，表现为 Suan API 会占用较多的性能，而这可能不是你希望看到的。
+
+等芒果帆帆再完善完善，然后争取提供其他更方便的部署选项吧~
+:::
+
+使用 git 命令从 Mango Gitea 上拉取源代码：
+
+```bash
+git clone https://gitea.mangofanfan.cn/SuanDev/NJUPT-Suan-API.git
+```
+
+这会将项目的源代码克隆到 `NJUPT-Suan-API` 目录中。
+
+然后，你需要 uv 和 pnpm 来启动项目，请确保环境中已经安装了它们。
+
+在 `NJUPT-Suan-API` 目录下运行：
+
+```bash
+uv sync
+```
+
+这将会构建 Python 虚拟环境，包括安装 Python 3.13（如果没有）和安装项目使用的依赖。
+
+```bash
+uv run playwright install chromium
+```
+
+这将会安装 chromium 供 playwright 使用。Suan API 通过这个 chromium 来模拟真实用户行为，以及截取课程表图片。
+
+安装 chromium 可能需要一段**比较长的时间**。大体上这是能够成功的，只是需要一段**比较长的时间**。
+
+然后（或者同时），在 `NJUPT-Suan-API/webui` 目录下运行：
+
+```bash
+pnpm install
+pnpm build
+```
+
+这将会安装 WebUI 所使用的依赖，然后构建 WebUI。这一般是很快的。
+
+现在，回到 `NJUPT-Suan-API` 目录下，使用以下命令启动项目：
+
+```bash
+uv run main.py
+```
+
+NJUPT Suan API 应当可以正常启动。

suan-api/introduction.md

@@ -0,0 +1,24 @@
+# NJUPT-Suan-API 介绍
+
+## 这是什么
+
+NJUPT 是 **南京邮电大学** 或者 **Nanjing University of Posts and Telecommunications** 的意思。
+
+Suan 是本项目的代号，芒果酸或者芒果酸酸。
+
+API 是这个东西的工作，作为 API，以及 MCP。
+
+MCP 是模型上下文协议，用于给 LLM 提供可供调用的工具。
+
+## 特别说明
+
+由于在网络上缺少与南京邮电大学相关的 Web API，已有的项目（[NJUPT-API](https://github.com/gaoliang/NJUPT-API)）也已经年久失修，
+芒果帆帆复刻这些 API 的过程也并不顺利。
+
+经过芒果帆帆的社工活动可得，我邮并不对外提供查询课表、跑操次数等数据的接口，因此 NJUPT-Suan-API 不得不另辟蹊径来获得课表数据。
+
+## 技术路线
+
+NJUPT-Suan-API 使用 Python 实现了 API 和 MCP 后端，主要使用了 FastAPI 和 FastMCP，所有功能一式两份在 API 和 MCP 中分别提供。
+
+另外提供 WebUI 管理面板用来便于管理。管理面板使用 Vue 设计。出于一些考量，管理面板不是可选的模块。

suan-api/llm-tools.md

@@ -0,0 +1,127 @@
+# LLM 工具
+
+## 课表工具
+
+### get_course_schedule_json
+
+```python
+@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:
+        未压缩时（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 在调用时可以选择是否压缩。
+
+请注意，[NJUPT Suan](/astrbot-plugin/introduction.md) 提供的渲染课表图片的工具需要经过压缩的课程数据，否则调用时很可能会由于参数过长而失败。
+
+### get_week_course_schedule_json
+
+```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

@@ -0,0 +1,3 @@
+# Playwright
+
+Playwright 是一个用于浏览器自动化的工具，Suan API 通过 playwright 来规避教务系统和统一身份认证的反爬虫措施，顺便用它来截图。