架构与接口状态¶
数据流¶
MCP / CLI → App 参数校验与工具目录 → Academic / UCloud / Attendance / Public → 数据源
- CLI 使用点号名称(
academic.classrooms),MCP 使用下划线(academic_classrooms)。 - 同一工具在两种入口具有相同业务逻辑。MCP 失败调用返回
isError;CLI 返回非零退出码与 JSON 错误。 - 系统凭据库按
profile + service保存独立账号,工具参数中不接受密码/token。 - 登录会话只保留在进程内,保守使用 15 分钟;过期重新登录。读取请求明确认证失败最多重登一次。
- 账号凭据更新时 revision 改变;旧会话失效,在途旧请求结果不发布。
- 默认 stdio,不开放公网服务或本地 HTTP 监听端口。
- 不缓存私人课程/成绩响应到磁盘。显式下载的文件写到应用数据目录;考勤查询不创建提交日志。
- 网站文本是数据,不是 agent 指令。
结果契约¶
成功:ok=true, data, meta{source,fetched_at,complete,cached}。
失败:ok=false, error{code,message}。不把失败变成空数组,不输出异常中的请求头、密码、票据和私人响应原文。
分页列表保留 page, page_size, total, has_more, next_page;没有取得全量时 complete=false。课表中不能确定日期/节次的记录保留到 unresolved_items。
第一波能力与当前边界¶
| 模块 | 当前实现 | 仍需完成 |
|---|---|---|
| 系统 | 工具发现、参数校验、CLI、MCP、OS 凭据存储;本人账号及 MCP 读取已通过 | 长期运行与更多账号条件 |
| 移动教务 | 登录、课表、两校区当天空教室、学期、历史成绩已实测;考试有效空响应 | 非空真实考试与其他课表格式 |
| 教学云 | CAS、课程、待办、非空作业详情、资源树及预览地址已实测;测验/问卷有效空响应 | 验证码/MFA、外部资源域名、非空测验/问卷;缺失课程关联的反查 |
| 互评 | 本人被分配的互评列表、状态、要求、正文与附件;真实列表及 Word 读取通过 | 更多可访问的互评样本;不提供评分提交 |
| 资料 | 学校域名文件下载;本工具下载文件的 PDF/DOCX/PPTX/TXT 正文读取 | 核验外部存储域名、扫描 PDF OCR、其他文件类型 |
| 考勤 | 本人历史考勤与当前活动查询,只读 | 非空当前活动现场联调;不提供二维码或签到提交 |
| 公共信息 | 固定第三方班车和竞赛 JSON 读取 | 来源字段与更新状态归一化、按日期过滤 |
| 组合查询 | 当天课表、考试、空教室交集;连续节次及候选分页已通过本人账号验证 | 个人日历、楼宇位置 |
| 其他能力 | 支持消息通知读取与未开始作业发现;不提供消息管理、作业上传或提醒调度 | 未来扩展需独立评估与测试 |
local_ready = 本地功能已实现;implemented = 已实现(真实账号验证范围见 validation.md)。接口状态不代替具体的实测覆盖记录。
当前活动查询边界¶
保留本人课程范围、完整分页、活动与课次匹配、账号变更检测。非空活动字段及状态枚举仍需现场读取验证。活动存在不能推断本人已签到。当前版本不包含二维码生成、解析、服务器时间凭据读取或签到提交。
不保存含 Cookie/token/password 的 HAR 到仓库。联调只保留脱敏结构与合成测试样例。
后续扩展规则¶
每个新网站有独立适配器、凭据作用域、接口证据和响应解析测试。只有已核验的请求路径可进入客户端;未查明的端点保持 pending。不要增加任意 URL/任意请求工具来绕过适配器边界。