# 东师附深-学生留言系统api封装

**Repository Path**: SandMo/DSFS-MessageAPI

## Basic Information

- **Project Name**: 东师附深-学生留言系统api封装
- **Description**: 造福学弟，虽然不一定有用
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-06
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 家校通留言板

微信「东北师大附属中学深圳学校」家校通家长端 **留言板 API 封装**。

支持AI回信，OpenAI兼容 `/chat/completions`（DeepSeek / OpenAI / 任意兼容服务）。

## 目录结构

| 文件 | 用途 |
|---|---|
| `school_api.py` | 家校通留言板接口封装（拉取 / 家长发送 / 学生侧发送 / 已读） |
| `ai.py` | OpenAI 兼容大模型客户端 |
| `bot.py` | AI 自动回复机器人（轮询 → 识别学生来言 → 生成回复 → 代发） |
| `server.py` | 本地网页服务（127.0.0.1:8080），内置启动机器人 |
| `index.html` | 网页：气泡对话 + 发送 + AI 状态 / 自动回复开关 / AI 试回 |
| `config.json` | 运行配置（会话凭据、身份、AI），已 gitignore，不入库 |
| `config.sample.json` | 配置格式示例（真实数据中间部分已用 `*` 脱敏，仅作字段形状参考） |
| `server.bat` / `bot.bat` | Windows 双击启动脚本 |
| `talk-api.md` | 逆向整理的协议文档（登录链路、接口参数、加密） |
| `state.json` | 机器人轮询水位（last_autoid），自动生成，不入库 |

## 快速开始

1. 准备 Python 3.6+（本机示例：`C:\Pyblock\resources\app\Python-win64\python.exe`；或装好后直接用 `python`）。
2. 复制 `config.sample.json` 为 `config.json`（其中的 `*` 为脱敏占位，须按下方「抓取凭证」用自己的真实数据替换），或直接把你的有效 `config.json` 放进来。
3. 双击 `server.bat`（或 `python server.py`），浏览器打开 `http://127.0.0.1:8080`。
4. 只想要命令行自动回复机器人：双击 `bot.bat`（或 `python bot.py`）。
   - `server.bat` / `bot.bat` 里的 Python 路径可按本机实际修改。

## 抓取凭证（Reqable）

> 必须自己抓自己微信里的登录态。会话 Cookie 为**会话级**，失效后重新抓即可。

**操作步骤**

1. 电脑安装 [Reqable](https://reqable.com/zh-CN/)，打开并启用 **HTTPS 解密**（首次按提示安装并信任其根证书）。
2. 手机与电脑连同一 WiFi；手机代理指向 电脑IP + Reqable 端口（Reqable 界面上有客服端二维码/配网指引，推荐用手机端 Reqable 与桌面端对连）。
3. 手机微信打开学校公众号 → 家长端入口 → 进入家长首页 `jiazhang.html` → 打开「留言」页，随手收发一条。
4. 在 Reqable 中过滤 `pos.dsfzsz.cn`，提取以下内容填入 `config.json`：

| config.json 字段 | 从哪里取 |
|---|---|
| `session.ASP.NET_SessionId` | 任一 `NewDZBPService.ashx` 请求头 `Cookie:` 里的 `ASP.NET_SessionId` |
| `session.EncryptedUserInfo` | 同请求 Cookie 里的 `EncryptedUserInfo` |
| `identity.me.uuid` | `jiazhang.html` 的 URL 参数 `PersonUUID`（或 `IMApp.ashx` `WeChatSignIn` 响应 `rows[0].PersonUUID`） |
| `identity.me.role` | 固定 `家长` |
| `identity.student.accountNo` | `jiazhang.html` 的 URL 参数 `accountno`（一卡通/学号） |
| `identity.student.name` | 孩子姓名（`rows[0].ChildName`，如 `刘小明`） |
| `identity.student.role` | 固定 `学生` |

5. 保存后重新启动 `server.bat` 即可。

## 接口封装（school_api.py）

```python
from school_api import SchoolChat
import json

cfg = json.load(open('config.json', encoding='utf-8'))
c = SchoolChat(cfg)

rows = c.get_messages()          # 拉取留言列表
c.send('放学来接我')              # 家长身份发送
c.send_as_student('我到家了')     # 学生（班牌侧）身份发送
c.mark_read()                    # 标记已读
c.unread_count()                 # 未读数
```

- `get_messages()` 返回 `rows`，每条含 `autoid`（消息ID）、`Content`、`Spendtime`、`LRoleName`（发送方角色）、`JRoleName`。
- `send(text)` / `send_as_student(text)` 返回 `{"result": "1"}` 表示成功；`2` 表示成功但班牌未绑定班级/教室。
- 关键实测结论：学生侧发送 `fsaccountno` 需传一卡通账号（与 `accountno` 相同），传学生 PersonUUID 会被受理但不落库。

## AI 自动回复

**逻辑**（`bot.py`）：

1. 每 `pollIntervalSec`（默认 10s）拉一次 `ContentList`。
2. 以 `autoid` 水位 + `LRoleName != 我` 过滤出新留言（学生来言）。
3. 用最近 `history_len` 条对话做上下文 → 调 AI 生成家长口吻回复 → 自动代发。
4. `reply_cooldown_sec` 内不重复回复，防刷屏；水位持久化到 `state.json`，重启不重复回复。

**config.json 的 ai 段**

| 字段 | 说明 |
|---|---|
| `auto_reply` | 是否自动回复（网页上也可运行时开关） |
| `base_url` | OpenAI 兼容接口地址，如 `https://api.deepseek.com/v1`（已预填） |
| `api_key` | 你的密钥；也可用环境变量 `AI_API_KEY` 注入，避免明文入库 |
| `model` | 模型名，如 `deepseek-chat` |
| `system_prompt` / `temperature` / `max_tokens` | 回复风格参数 |
| `history_len` / `reply_cooldown_sec` | 上下文条数 / 回复冷却 |

**网页功能**：右上角显示 AI 状态、自动回复开关、`AI 试回`（不发送只预览一次回复）。

## 网页接口

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/` `/index.html` | 聊天页面 |
| GET | `/api/messages` | 留言 + 状态（含 `ai` 状态） |
| POST | `/api/send` `{text}` | 家长发送 |
| POST | `/api/markread` | 标记已读 |
| POST | `/api/ai/enabled` `{enabled}` | 开关自动回复 |
| POST | `/api/ai/test` | 试回（不进 AI 逻辑，仅生成） |

## 排查

- 页面提示「AI 未配置」：`config.json.ai.api_key` 为空。
- 发送失败 / 拉取报错：会话 Cookie 过期，用 Reqable 重新抓 `session`。
- 换学校 / 换账号：改 `identity` 与 `session`（对应方接口的 `baseUrl`/`servicePath` 在 `api` 段）。

## 安全提醒

`config.json`（含**有效会话 Cookie**）与 `*.har`（抓包数据，含个人敏感信息）已被 `.gitignore` 排除，**不会进入 Git 历史**。公开仓库请勿强制加入；即使私人仓库也建议用 `AI_API_KEY` 环境变量注入密钥。