agentleFS
wangyendtwangyendt/wayne-skills/learning-tutor/SKILL.md

learning-tutor

Skill9 starsChanged 9 months agoMITView on GitHub

Teach a field, concept, or paper through one-question-at-a-time dialogue, Feynman explanations, and evidence-based assessment; query or resume persistent learning records across sessions. Use for 开始学习, 带我学, 学过没有, 学习进度, 继续学习, or 重新学 with learning intent. Includes learning-session capture and event-driven synchronization; distinct from generating a one-shot report or teaching video.

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

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 当跨设备引用。
  • 不创建复习计划、定时提醒、到期任务,不因经过一段时间自动降分。用户主动说忘了时,读取历史误区,给一个小诊断后重新教学。

每轮保存与续学

  • 让同步 capture hook 先落盘当前证据;仅基于已经完整的轮次提交评估,当前回答所在轮次尚未完成时留待下一轮补评;用 resume 读取实际消息 ID。禁止捏造回答、事件 ID 或评分证据。
  • 有可评估的回答时执行 assess,按评估与状态格式提交理由、提示次数、rubric 和评估者。对话已存但漏评估时保留未评估,之后可基于原始回答补评。
  • 普通指令、寒暄、学习目标不是考试答案;unassessed_user_messages 是待判读候选,不代表每条都必须打分。
  • 每次改变教学方向、结束单元或用户中断时更新 checkpoint:当前问题、误区、已给提示、资料位置、下一步。不要只写“第三章”。录制开关/待同步条数从 status 读取,不固化在 checkpoint 中,避免恢复时出现过期状态。
  • 并行 checkpoint 保留分支;兼容分支可生成新 checkpoint,并把所有被合并的 head ID 放入 parents。有真实目标冲突才问用户。保留各次评估,不平均、不只取最高分。
  • 纠正 AI 错评时提交新 assessment,supersedes 引用被纠正的记录;保留原始证据和修正原因。
  • 查询前先 sync --pull-only;档案显示 archived=1 时先 hydrate,失败则说明当前缺原始证据。“未搜到”仅代表当前查询范围没有匹配,不等于从未学过。

故障、配置与数据

  • 服务断连:首次失败提示实际已知原因,自动检查现有配置与既有连接、短时重试;原因变化或需要用户操作时再提示,同一故障不逐轮刷屏,恢复后提示一次。失败不阻断学习;后续录制开启的事件携带此前失败的完整轮次重试,没有网络恢复监听或后台定时重试。修改连接配置/适配器/服务前说明具体方案并确认。异步通知的可见性因宿主而异,下次同步 hook 和 Agent 读取 status 必须转达未显示的故障。只有完整入库回执才标记服务端确认。
  • 本地存储失败或采集协议未知:明确报错,不宣称已保存或采集完整;停止采集的用户指令优先生效。已发生缺口保留诊断。
  • 没有服务器:按安装指南解释 local-only 模式,提供 SSH 后端或 HTTPS API 配置步骤。现有 Context API 和 PostgreSQL 端口不等于学习 API。
  • 服务器原文保留到主动删除;手动 prune 清理超过 30 天的、已同步且不活跃的本地原文。最小主题目录和去重凭据保留,之后按需恢复。待同步记录不按年龄清除。
  • 导出含私密学习证据;文件权限与磁盘加密交给设备环境。令牌只由运行环境提供,不写进 skill、示例或日志。
  • PostgreSQL 教学记录后端与 OSS 图片服务已在 hx470 部署,通过现有 SSH 使用;公网 HTTPS 网关未部署。文字和图片分别核验回执,不由图片成功推断文字/评分已同步。客户端不保存 OSS/数据库密钥。全局 hooks、新开端口、个人记忆和 embedding 仍需明确确认。数据库使用单个教学 schema,主题层级放在数据中。

按需读取

  • 首次安装、配置、宿主故障:setup.md
  • 教学图片、OSS、图片索引与跨设备取图:assets.md
  • 评估、合并和 CLI JSON:assessment.md
  • 服务端协议与数据不变量:protocol.md
  • 后端部署、查询与运维:record-backend.md
  • 辐辏角首个教学单元:vergence.md
  • 本版测试边界:validation.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.