-
Notifications
You must be signed in to change notification settings - Fork 8
Project Docs
一句话 TL;DR:仓库根 7 份公开文档,加 docs/ 下 232 个被 git 跟踪的文件——各讲什么、什么时候翻。想加学校、报 bug、查旧版本,先来这里定位入口。功能与架构的细节在本 wiki,仓库文档管流程与入口,两边互为索引。
中文版是本体,英文版是翻译,两者小节一一对应(README_EN.md:33-478)。内容覆盖:概要(包名、SDK、语言)、三种视图、多课表管理、节次配置、教务导入与协议族、七种导入格式、四类导出、五类 Widget、冲突与撤回、OPPO 流体云、提醒、关于页、主题、技术栈、项目结构、构建安装。学校目录数字以正文为准:高校教务直连数量写在 README.md:57(文案随版本更新,当前 schools.json 实测 340 所)。
两处入口容易被划过:
- 顶部导航直接链到适配采集教程
docs/adapt-kit/README.md(README.md:24)。 - 「Documentation」一节链到站外两篇:blog.qdp.qzz.io 上的用户操作手册与技术长文(README.md:482-485,英文版 README_EN.md:471)。
160 行,10 个小节,从「关于项目本身」到「用户故事」。开头写明双重用途:给用户看,也给 AI 搜索引擎抓,回答用真实事实、不用营销腔(FAQ.md:3)。「我学校不在名单里怎么办」「ColorOS 上 widget 空白」「能不能从 WakeUp 迁移」这类高频问题都在这里。测试基线和贡献入口各有一句指引(FAQ.md:134-137)。
只保留最近两个版本,双语,英文在前中文在后:v1.0.35 与 v1.0.34 各出现两遍(CHANGELOG.md:3、45、119、161),全文 231 行。每个版本按「改了什么、为什么、Build 三行(versionCode / versionName / APK 文件名)」展开。更早的版本去 docs/ 下的 release-notes 文件,见下一节。
贡献流程一页说完:环境与测试基线(CONTRIBUTING.md:7-16);提 Bug 用三类 issue 模板,教务问题附 sleepy-adapt-*.zip 采集包(:18-23);分支命名与 commit 格式(:27-31);合并前 testDebugUnitTest 与 lintDebug 全绿,改 WebView 内 JS 正则还须过对应的 *WebViewContractTest(:32-39);关联 issue 用 ref #N(:41);教务适配另加调研归档、致谢、红绿测试三条要求(:43-49);commit 身份(:51-54)。
28 行。只修最新发布版;漏洞禁开公开 issue,走邮箱或 GitHub 私下漏洞报告(SECURITY.md:10-15);范围划在三处——导入解析的文件处理(10 种 MIME 与分享接收)、WebView 直连的 JS 注入与凭据处理、导出文件里的个人信息(:24-29)。
改编自 Contributor Covenant 2.0(CODE_OF_CONDUCT.md:3)。适配方案有分歧时摆事实——抓包、页面结构、测试结果(:13)。教务数据属于个人信息,issue 附采集包必须先脱敏,维护者发现未脱敏附件会代为处理(:20)。
按 llmstxt.org 规范写的机器可读事实索引,面向 LLM、AI 搜索引擎和 RAG 管道,末次复核 2026-09-11(llms.txt:3)。内容:项目身份与技术栈版本、源码规模(data/jw/ 下 43 个 parser 文件,是最大的源码目录,llms.txt:53-56)、18 个协议族的对照表,校数标注随版本更新(文案当时为 179 校)、导入导出格式、五类 Widget、行为保证(做什么/不做什么)、可引用的工程事实、新学校收录政策、引用规范(:224-233)。README 指明 AI 引擎可同时抓 llms.txt 与 FAQ.md(README.md:61)。
它是带日期的快照:文中「当前版本」写的是 v1.0.52(llms.txt:222),以 GitHub Releases 为准。
git ls-files docs/ 共 232 个,分八类。README 的项目结构一节也画了 docs/ 的骨架(README.md:408-412)。
v1.0.1 到 v1.0.53 共 52 份(v1.0.4 无对应文件),平铺在 docs/ 根。每份双语,英文在前:v1.0.53 的英文节从 release-notes-v1.0.53.md:1 起,中文节从 :89 起,末尾有 Build 行(versionCode 57)与验证节(:85、:173)。查任意旧版本改了什么从这里入手;CHANGELOG.md 只留最近两版。
命名 <school>-adapt-research-<日期>,覆盖 9 所学校的适配调研:ahu(安徽大学)、bjtu(北京交通大学)、buaa(北航)、hebzyhj(河北资源环境职院)、hfut(合工大,两轮)、jou(江苏海洋大学)、nbt(浙大宁波理工)、neu(东北大学)、ucas(国科大)。标准六件套:scope.md(任务边界)、candidates.json(GitHub 候选仓)、attribution-candidates.*(开源参考候选)、findings.json(逐仓发现)、protocol-matrix.md(协议对照)、current-code-state.md(代码现状)。bjtu 另存 search-raw/ 原始搜索记录;hebzyhj 的 capture/ 只跟踪 .gitignore 与 README,真实采集数据不入库。
示例:合工大二轮调研的 scope.md:1-9 写明这是对已适配学校的 issue 诊断,目标是用真实采集数据在单测层复现失败,边界是不动协议、不加学校。另有一个同构目录 ysu-boya-pp-saas-survey-2026-09-10(6 个文件),是燕大博雅研究生平台(多校 SaaS 产品)的协议调查。
179 所学校的全量交叉验证存证:17 个 bucket_.json、18 个 result_.json(含 BUPT)、1 份 README。总账:DRIFT 17 所(16 所有新 URL 可填)、OFFICIAL_DENY 2 所、PASS 5 所(README.md:15-19)。
adapt-kit:面向用户的采集教程
两个文件。README.md 共 257 行,零编程门槛:按平台下载 sleepy-collector 二进制、运行、提交 zip,总耗时约 10 分钟(:3-4);第 4 节讲包里有什么、没有什么(不含 cookie、token、登录态,:169);第 6 节是备选的 F12 控制台脚本方式(:204);第 7 节给想深究的人逐项解释采集包结构(:235)。collect.js(604 行)是脚本的源文件。学校不在目录、直连失败时,README 的申请流程先要教务 URL 和失败现象,被要求补充数据时才按此教程采集,全程禁止提交账号、密码、验证码(README.md:163)。
INDEX.md 的定位:把各厂商启动器对 Android AppWidget 的额外限制落成对照资料,作为跨厂商兼容的事实依据(INDEX.md:1-4)。小米独立进程与曝光刷新、OPPO 冻结 Glance 等关键限制列在目录表(:15-23)。每个文件头部标注证据等级 A(厂商官方原文)/ B(官方加社区核实)/ C(仅社区)与抓取时间(:26-32)。华为 HarmonyOS 服务卡片被明确划出适配范围(:34-40)。
plans/ 10 份带日期的实施计划(如 2026-09-08-per-card-irregular.md),specs/ 7 份设计文档(如 2026-09-01-conflict-course-display-design.md:1)。想了解某个已上线功能的设计过程,先翻这里,再对照源码。
audits/CODE_AUDIT_v1.0.29.md(审计基准 HEAD c34b22f,79 个 Kotlin 文件 18704 行,逐条列 P0/P1 修复,docs/archive/audits/CODE_AUDIT_v1.0.29.md:1-5),加 widget-iterations/ 下 7 张 v1.0.15-v1.0.20 时期的 widget 迭代截图。历史参考,不代表现状。
- HEU_JWGL_IMPORT.md:哈工程金智教务协议记录——CAS SSO 登录流程、验证码、jwapp 课表 API、字段映射(HEU_JWGL_IMPORT.md:1-3)。
- YSU_BOYA_PP_IMPORT.md:燕大博雅研究生平台(boya_pp)协议,首个研究生直连校(YSU_BOYA_PP_IMPORT.md:1-5)。
- PARSER_SPEC_REPORT.md:对照 WakeupSchedule_BUPT 仓列出的 10 个 parser 实现规格,生成于 2026-06-19,早于当前代码,只作背景参考(PARSER_SPEC_REPORT.md:1-5)。
- 985-batch-b-wave-2-plan.md / wave-3-plan.md:985 批量收录 B 档两波的实施计划(985-batch-b-wave-2-plan.md:1-3)。
- oppo-coloros-fluid-cloud.md:OPPO 流体云官方文档入口与接入调查(oppo-coloros-fluid-cloud.md:1-3)。
- screenshots/ 20 张 PNG:README 全部截图的出处(README.md:33-73 引用);logo.png、social-preview.png 是 README 顶部 logo 与社交预览图。
该目录在仓库里只跟踪一个文件。README 声明:公开侧不列举、不引用任何内部流程文件名,需要时直接打开本地文件,.gitignore 已永久排除目录下的其余文件(docs/sop/README.md:5-7;README.md:412)。
| 你想做什么 | 去哪 |
|---|---|
| 让自己学校支持教务直连 | 开 school_adaptation.yml issue,带教务 URL 和失败现象(README.md:163);被要求补充数据时按 docs/adapt-kit/README.md 采集 |
| 报 bug | CONTRIBUTING.md「提 Bug」节(CONTRIBUTING.md:18-23);常见问题先查 FAQ.md |
| 查某个旧版本改了什么 |
docs/release-notes-v1.0.<N>.md;最近两版看 CHANGELOG.md |
| 贡献代码 | CONTRIBUTING.md 全文;PR 用 ref #N 关联 issue(CONTRIBUTING.md:41) |
| 报安全漏洞 | SECURITY.md,私下渠道,禁开公开 issue(SECURITY.md:10-15) |
| 写文章 / 让 AI 引用 Sleepy | llms.txt,引用规范在 llms.txt:224-233 |
| 看某校教务协议细节 |
docs/<school>-adapt-research-*/ 下的 scope.md 与 protocol-matrix.md |
| 看某功能的设计来龙去脉 | docs/superpowers/specs/ 与 plans/ |
Sleepy Wiki
入门
界面与视图
课程管理
导入导出
小组件与提醒
数据与设置
项目
社区