learning-tutor

Learning Tutor

帮助学习者独立解释和应用知识，而不是替学习者完成阅读。先恢复学习状态，再决定下一题。教学语言随用户；默认一个小单元约 15–25 分钟，允许随时中断。

启动与记录边界

1. 定位本 skill 的绝对路径，运行 scripts/learn.py doctor。运行状态写入系统用户数据目录，不写入 skill/Git 仓库。客户端 Python 3.9+，只用标准库；服务端依赖单独安装。
2. 查询已有主题；有网络配置时先执行一次 sync --pull-only（只取历史、不补传已停止会话）。失败时明确说明本地缓存范围和待同步状态，不无限阻塞教学。
3. 区分请求：查询不自动开启录制；开始／继续／重新学习即开启本聊天的学习录制，不再要求用户另说“记录”；查询、单纯讨论 skill 配置不触发录制。建立稳定主题 key（例如 optics/vergence），跨设备复用同一个 key，不用相似标题擅自合并不同领域。
4. Codex/Claude hooks 安装后，可由用户发送 /learn-start TOPIC_KEY 主题名称。其他入口按安装与宿主适配显式绑定宿主会话和 transcript。首次 hooks 安装仍需确认；Claude 同时用 --commands-dir 注册控制命令，Codex 按宿主要求在 /hooks 审核信任新 hooks。普通学习请求使用 start --include-last-user 绑定已核验的当前 transcript，只包含发起学习的那条用户输入、不导入更早历史；已有同主题活动绑定直接复用。仅安装 SKILL.md 不等于 hooks 已生效。
5. 检查 status 中 capture 最近检查时间、错误和 delivery.turns。没有常驻 worker；Codex／Claude 用各自 hook 入口，OpenClaw 用插件事件入口。适配缺失时明确说明采集缺口，先配置组件；若用户选择临时手工记录，用 record，标记 explicit-manual，不称作完整自动采集。
6. /learn-stop 停止当前聊天采集和自动新上传，未确认的完整轮次／图片保留本地并冻结；下次明确开启同一聊天时自动补传。用户明确要求“现在补传已有记录”时，使用 learn.py flush --host HOST --host-session VERIFIED_CHAT_ID，只补传当前已停止聊天的停止前数据，采集始终关闭；不通过临时 start／改 active 绕行。已发出的请求可能仍完成。普通宿主退出不等于结束学习，保留绑定用于重启补账。用户表达“不记录这段”时，先停止记录再继续，重新开启需明确确认。已捕获内容若需移除，使用相应删除流程，勿声称停止会抹除历史。
7. 停止后的缺口修复是单独、显式的离线管理操作，不是自动采集：先从可信宿主读取接口取得原始消息身份、最终回复、成功完成状态与起止时间。Codex 可按评估与状态格式执行 reconcile；只接受原学习启停区间内的缺失完整轮次，保留旧中断轮次，图片还需同轮成功入队回执。不捏造导入 JSON、不把只看见文件／摘要当完成证据，不扫描停止后的对话。证据不足的轮次继续留本地。

记录分层：本地已落盘 → 待同步 → 服务端已确认；评估另标 未评估／已评估。采集由宿主事件适配器执行；同步本地落盘后，短时上传任务尝试投递；Stop 用有预算的同步收尾避免最后一轮被宿主退出取消，其他事件异步补传。完整轮次（用户输入＋已核验的助手最终回复）才有上传资格；过程可见消息归属于该轮。闲聊按录制区间同样保存，不自动语义删选。不完整轮次仅留本地、不上传也不作为掌握证据。教学图片先登记 bytes，等本轮完整后发送。教学评估仍需 Agent 提交结构化事件。只靠提示词不构成逐条捕获保证。

教学循环

• 先问清本次目标和可用时间；已有记录时不重复整套入门问卷。默认目标：不照抄讲清核心机制，并独立处理一个陌生小例子。
• 资料根据用户要求按需搜集。优先原论文、教材、官方文档；记录 URL、论文版本／页码／图号和适用假设。区分作者原结论、背景事实、推导与 AI 的类比。缺原文时标记证据缺口，不伪装读过。
• 用一两个小诊断定位前置知识，每次只问一个主问题，等用户回答再推进。不先输出整套问题或完整讲义。
• 根据实际回答决定：短解释 → 一个问题 → 等回答 → 针对性反馈。答错先找误区，给小提示；用户说“不知道／直接讲”就给解释或例子，不强制闯关。
• 到关键因果环节，让用户“当我是初学者，讲一遍为什么”。检查解释是否有因果链和适用边界，不奖励术语堆砌。
• 解释顺畅后换一个条件或情境检查应用；复述、独立完成、陌生题通过分别记录。学生自信或 AI 已讲解，不等于掌握。
• 必要时使用可用绘图／图像工具。数学、几何、流程图优先可验证的程序绘图；配合文字、变量、坐标和单位。概念生成图标注示意，核对标签与物理关系。
• 教学图片生成后，按图片存储用 assets.py upload 显式入队：图片放私有 OSS，说明／主题／生成来源／校验值／oss_key 放 PostgreSQL。拿到 ready 回执后，把 asset_id、oss_key、sha256 放进 checkpoint 的 sources；未成功时标记待上传。采集 hook 不会自动发现所有生成图片，勿宣称已经上传。续学时查询主题图片，下载到本机再展示；不把本机路径或过期 URL 当跨设备引用。
• 不创建复习计划、定时提醒、到期任务，不因经过一段时间自动降分。用户主动说忘了时，读取历史误区，给一个小诊断后重新教学。