DESIGN.md · diff
git:20261008.13272b0 to git:20261022.0cb5975
12 added, 1 removed. Audit A to A.
# 设计原则：一个学习功能凭什么进来
> 开发规则，写给改这个仓库的人和 AI。2026-09-25 定。
> 起因：发起人指出，一个功能如果没有被验证有效的方法支撑，学生对 AI 说一句「帮我准备讨论题」就能得到同样的东西，这个功能就没有存在的意义。
## 准入五条（五条都要满足）
1. **机制有证据**：写得出这个功能靠哪个学习机制起作用，列作者、年份、期刊、效应量、研究对象、材料类型和边界，标明读到的是全文还是只有摘要。证据的材料类型要对得上：计算题、概念、单词，同一种方法的效果可能相反。
2. **有效成分写死在流程里**：排期、先答后看、混排、样例渐隐由系统执行，学生不用懂原理，也不靠自觉。
3. **一句话做不到**（至少占一条）：
- 跨天的状态（哪题错了、哪天再考）；
- 学生自己的真实数据（截止日、评分标准、课件原文）；
- 可核对（答案用代码算、对得上课件原例和页码）；
- 主动时机（该做那天自己出现在本周清单里）。
4. **能看出有没有用**：记录可观察的结果（比如「之前学过的题，这次一上来就对」的比例），据此调整。
5. **学生真的会用**：低摩擦（一屏一题、点选、无倒计时；09-20 打字作答版被学生退回就是反例）；一切先按学生方便来（10-07 发起人），学生要了就是同意读这门课的课件。
核实文献时顺带看到的一个规律也支持第 3 条：在各个领域里，「只给信息、一次性建议」的版本效果最差——单发评分标准、讲座式团队培训、单次拖延建议、自己随便挑线索的「如果…就…」计划。
## 商科功能重筛（2026-09-25）
| 候选 | 证据 | 结论 |
|---|---|---|
| 计算题练习（公式：记住、看懂、会选会用） | 强 | 做过，10-07 删了（见文末） |
| 考试复习（全专业） | 强：连续再学让真实课程的选择题考试从 72% 到 84%，d=0.65（Rawson, Dunlosky & Sciartelli 2013） | 随「练习」一起删了 |
| 评分标准自查 | 中：自评对成绩 g=.585，校正发表偏差后 .343（Yan et al. 2022）；评分标准只在配合自评或互评时有效，g=.57，校正后 .45（Panadero et al. 2023）；只发评分标准没有证据（Panadero & Jonsson 2013） | 做过检查单，10-07 删了；「交之前对着评分标准自评」并进学习页第 8 节 |
| 小组协调 | 弱到中：高质量的团队章程加明确的任务策略（Mathieu & Rapp 2009，MBA 团队，相关研究）；主要帮尽责性低的团队（Courtright et al. 2017） | 第二批 |
| 讨论和课堂发言准备 | 弱：任务前计划改善当场口语 d≈.46–.58（Johnson & Abdi Tabari 2022），但测的是当场独白，不是课堂讨论；没有学生端准备工具的研究 | 暂不做 |
| 阅读清单进周计划 | 信息完整性，不是学习机制 | 另算（信息类） |
+ ## 10-22：整份收进来的 /humanizer
+
+ 发起人要把 blader/humanizer（MIT）收进救驾，先单独发这一个：打 /humanizer 任何情况下都跟原版一样；救驾以后可能改名，这个口令不能跟着名字走。它是写作工具，不是学习功能，不按上面的准入五条；收之前查的是许可（MIT）、安全（只有文字，不跑程序、不联网）和真跑（维护者拿英文文字实际用过）。
+
+ - 口令就用原作者的名字 humanizer，不加 jj-：原名大家已经认识，改名也不用动。
+ - 整份收：SKILL.md、LICENSE、agents/openai.yaml 原样放在 `skills/humanizer/`，SKILL.md 连文件名都不改。装出去是一个完整的技能，不读主文件夹，所以主文件夹改名、搬家，/humanizer 照样能用。改好的文字直接在对话里给，不做网页。
+ - 认「这份是我们装的」靠旁边的记号文件 `installed-by.json`（主文件夹、版本），记号里不写产品名：改名后的新版照样认得、能更新、能卸载。jj 入口还是靠 SKILL.md 里「<产品名>主文件夹：」那一行认，改名那天要另外处理。
+ - 学生自己装过同名的（多半就是原作者那份）：不覆盖、不删，用那份；链接过来的不往里写。
+ - 原作者更新了，跟着救驾一起更新：发版前读过改了什么、重新导出、更新校验清单（`tests/fixtures/upstream/humanizer.json`）、测好再发；学生电脑不自己去原作者那里拉。
+ - 对外不说「降 AI 率」「过检测」：原作者 README 写明躲检测器不是它的目标，改完的大多数照样会被标出来。README「写作业这件事」那段跟着改了。
+
## 10-07：只留周报和学习页
发起人定：救驾只留周报（连雷达、日报、外部平台、课程说明）和学习页（入口 /jj-learn）。删掉的六个功能和原因：
- 作业检查单（check）、问老师（ask）：周报和学习页已经覆盖了大部分；更要紧的是它们把模型框死了。10-07 用六件真实作业测检查单：
照它的规矩只能摘作业页原文、最多 12 条，100 条硬性要求只覆盖了约三分之二（A3 只有 6/16）；同一批作业让模型不受这些规矩、只要求找全并标出处，
从 9–15 个地方找出 147 条、标出二十多处说法打架。检查单里唯一有证据的一环（交之前对着评分标准自评，再有人看草稿：Yan et al. 2022；Panadero et al. 2023）
并进了学习页第 8 节，学生说一句也能做。
- 拆第一步（start）、目标卡（goal）：周报每件必做已经带第一步；目标卡证据弱，救驾也不主动找人。
- 练习（practice）：证据强（见上表），但不在「周报 + 学习页」里，一起删了。
- 发帖之前（post）：发起人判断没用。
- 原来每条规则的出处、效应量和边界都在 git 历史里：找 7888ace 之前的 DESIGN.md、references/{check,ask,start,goal,practice,post}.md。
+ 这几个功能的研究记录（每条规则的出处、效应量和边界）没有放进公开版。
读网页三种方式一样（10-07 发起人要求「全部方式都能适配」）：本校 Canvas 上的网址先换免登录的打开链接——嵌的工具用 sessionless_launch，Canvas 自己的页面 token 方式用 /login/session_token，浏览器登录方式本来就带着会话；Moodle 用登录过的浏览器。打开链接是一次性的登录凭证，不打印、不落盘。真 USYD 账号（token 方式）实测：Zoom 会议列表、Leganto 阅读清单（5334 字）、MECO6941 课程页面都读到了；Canvas Studio 视频两种方式都是 403，读不到的结果也一样。学校单点登录的网站（Zoom 录像直链、选课系统）：发起人要「让用户最多输入一次」。第一次碰到时问学生一句，同意就弹救驾自己的浏览器窗口，学生自己登（勾 Keep me signed in）；存下整份登录记录（全部网站，含学校统一登录的会话 cookie，浏览器一关本来会丢），每次用完再存一遍；过期了先在后台走一遍学校登录，学校要重新输密码才问。token 和浏览器登录方式用的是同一份浏览器，体验一样；Canvas / Moodle 的登录过期也先在后台自己重进。学校规定多久必须重新输，改不了；不替学生存密码、填密码。模拟的学校登录全测过；真 USYD 没实测（要学生自己登一次）。