Conventions

阅读约定与证据等级

这页规定三件事：如何标注事实、如何标注日期、如何给链接。所有页面都按这套约定写。

证据标签

每个结论后面用方括号标来源。没有标签的句子，默认是「我们的推断」，不能当成事实使用。

标签	含义	什么时候用	可信度
[官方]	学校或上游平台的公开文档	文档明确写出的端点、字段、限制	高，但可能过期
[实测]	我们实际运行过	带上日期、账号权限范围、样本量	最高，仅限当天行为
[社区]	公开项目或文章验证过，不是我们运行	补 Dela 没覆盖的接口	中，需自行复核
[上游]	上游协议或框架文档（OAuth、Discourse、IMAP 等）	协议通用行为；交大站点可能定制	高，但站点可能定制
[协议]	协议本身的事实	如 POP3 没有文件夹语义	高
[代码]	仓库实现，未独立实测	端点形状来自代码，尚未独立运行	中，可能随重构变化
[推断]	从响应结构、代码或命名推出来的	没有直接证据，但足够合理	低，不能当契约
[待验证]	只有线索，没有复现	只放待验证清单	不写入正文事实

组合标签（如 [官方/实测]）表示两类证据都支持；尽量拆成两句，拆不开时按较弱的一类理解。

[实测] 可以来自未入库的内部记录。遇到这种情况，写「内部实测记录未入库」，并尽量附仓库代码路径（如 src/main/shuiyuan/*）；读者无法复核时按较弱证据使用。

写法示例：

• GET /courses 返回 48 门课，其中 5 门列表可见、详情 401。[实测 2026-09-10，本人账号，48 门课]
• 授权码有效期 1 分钟。[官方 2026-10-25，jAccount OIDC 文档]
• 水源点赞后取消点赞返回 403。[实测 2026-09-21，write key]
• 课堂录像只需要 Cookie，不需要 JWT。[实测 2026-10-06，本人账号]

日期与时间

• 平台手册页顶部写 最后验证：YYYY-MM-DD；非平台页在页脚或「变更记录」写 最后复核：YYYY-MM-DD。只写日期，不写「最近」。
• 每个重要段落可以有自己的验证日期；页面顶部的日期是整页最近一次复核。
• 时间默认 Asia/Shanghai。接口返回的 Unix 时间戳要注明是秒还是毫秒。
• 超过 6 个月未复核的段落，加一行：

> [!WARNING]
> 本段最后验证于 2025-12-01，已超过 6 个月，使用前请重新确认。

事实与推断要分开

• 事实：接口返回了什么、状态码是什么、字段叫什么。
• 推断：为什么这样设计、这个字段大概是什么含义。
• 产品设想：能拿这些数据做什么。产品设想不写成接口能力，不放进「可获得的数据」表。

推荐写法：

返回的 tags 元素是对象 {id, name, slug}，不是字符串。[实测 2026-09-15]

推断：这是 Discourse 新版本的序列化形态；旧客户端按字符串处理会拿到 [object Object]。[推断]

页面元信息

每个平台手册页开头放一张小表：

| 项 | 值 |
| --- | --- |
| 平台 | `oc.sjtu.edu.cn` |
| 认证 | 个人 Access Token |
| 数据方向 | 只读为主；讨论回复可写 |
| 难度 | 低 |
| 最后验证 | 2026-09-15 |
| 证据等级 | A（官方文档 + 实测） |

证据等级：

等级	含义	典型页面
A	官方或上游文档 + 本项目实测，关键端点已验证	Canvas、Timetable、Mail、Shuiyuan、Classroom-Video、选课社区
B	官方/上游文档为主，未逐项实测	Open API、InfoPlus、数据资源 API、致远一号、计算与网络、第二课堂、传承·交大
C	社区实现、私有 Web API、公开网页解析为主，未独立验证	Pan、校园公开信息

难度表示接入成本，不代表学校评级：

• 低：几分钟能拿到凭证，标准 REST/协议。
• 中：需要人工登录、处理 Cookie 或异步任务。
• 高：需要单位/部门审批，或接口是私有 Web API。

链接政策

1. 外部链接只作为脚注，挂在它支持的那句话后面；不再设「参考资料」大清单。
2. 每个外链都要能回答「它支持了哪条结论」。回答不了就删。
3. 官方入口只在「申请入口」「文档」「上游协议」三类位置出现，不重复贴。
4. 站内链接用相对链接：[Canvas](Canvas)，不要写死 https://github.com/Chang-Yo/Dela/wiki/Canvas。
5. 唯一例外是 资料来源：它是来源目录，每条必须写「它支持什么」，不承载正文结论。
6. 已发布页面重命名时保留旧页 stub，避免外部收藏 404；从未发布的草稿清理不需要 stub。

代码约定

• 默认 TypeScript/Node 20+，使用原生 fetch、node:fs/promises、node:path。
• 需要展示协议细节时用 curl；需要展示解析逻辑时用 TypeScript；Python 只在数据科学场景给最小片段。
• 示例里不出现真实 Token、Cookie、学号、姓名、邮箱、宿舍、成绩。
• 示例要能独立运行：给出环境变量名、依赖、预期输出；不要只写 doRequest() 这种伪代码。
• 错误处理只写当前场景需要的，不写通用框架。示例应便于修改，不追求封装成库。

状态词

统一使用以下状态词，不使用模糊表述：

词	含义
可用	我们或官方确认当前可用
受限	可用，但有权限、频率、字段或场景限制
易变	私有 Web API，随时可能改
已废弃	确认不可用，或有明确替代
未验证	只有线索，没有复现
不要用	技术上可能，但违反条款/伦理，或风险不可接受

安全约定

• 任何页面都不贴真实凭据、Cookie、签名 URL、个人数据。
• 示例中的域名、路径可以是真的；ID、Token、姓名必须是假的。
• 涉及写操作时，必须写清楚：影响范围、是否需要用户确认、如何撤销。
• 涉及第三方内容的（水源帖子、邮件、课堂录像），必须写清楚不能再分发。

版本与废弃

• 接口变了：更新页面，并在页面底部「变更记录」加一行日期 + 变化。
• 接口死了：移到已废弃接口，写最后可用日期、现象、替代。
• 不要直接删除历史。废弃页记录当前不再推荐的路径；历史事实仍保留在页面变更记录中。

页面检查清单

写完一页，过一遍：

• 删掉所有外链后，读者还能完成一次请求/解析吗？
• 每个端点有 method/path/auth/params/returns 吗？
• 每个常见问题有现象、原因、处理、证据和日期吗？
• 有没有把「官方文档」抄成「可以构建的服务」？
• 有没有收录抢课/抢场馆/造假/验证码绕过？
• 站内链接是相对链接吗？
• 最后验证日期更新了吗？

---

最后复核：2026-10-26。