跳转至

架构与接口状态

数据流

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/任意请求工具来绕过适配器边界。