Learning OS

Learning OS 是一个可复用、证据驱动的 Codex 辅助学习系统。它不是某一门课程本身，而是一套用来创建课程包、规划学习 session、收集证据、验收能力、补救短板和跨设备恢复进度的个人学习操作系统。

README 只记录项目说明、功能边界和实现进展，不记录当前学习状态。实时状态以 state/、sessions/、state/handoff/ 和 CLI 输出为准。

先看哪里

如果你只是想恢复学习，或者觉得目录名太长、看不懂项目结构，只看：

开始这里.md

目录地图.md 只在你想找某类文件时再看；LEARNER.md 只补充怎么和 Codex 配合。

日常学习时不需要理解整个仓库。你可以直接对 Codex 说：

继续
暂停并同步
验收

Codex 负责读取状态、检查仓库、运行校验、更新 handoff 和同步。

项目结构

• engine/：学习引擎，定义规划、验收、补救、handoff、同步、schema、模板和 CLI。
• tracks/：课程包，定义具体学什么；source/ 是事实源，generated/ 是可重建的人类阅读文档。
• state/：机器可读状态，记录 active track、current session、outcome 进度和 handoff 指针。
• sessions/：每次学习 session 的计划、证据、结果和下一步。
• workspace/：真实练习、项目和实验产物。
• journal/：长期笔记、错误、问题、决策和跨课程洞察。
• tests/：CLI 和状态校验相关自动化测试。

核心能力

• 从学习目标创建课程包壳。
• 用 JSON source 描述 module、outcome、project 和 rubric。
• 用 session 文件规划每轮学习任务、支持边界、证据要求和验收标准。
• 用 schema 和一致性校验保护 state、session、track source、handoff 之间的关系。
• 支持暂停、恢复、切换课程包和跨设备同步。
• 强制记录独立程度：solo、hinted、assisted、codex_written。
• 用 evidence 和 rubric 推进进度，避免凭感觉或聊天印象推进。

CLI

常用命令：

npm run 当前
npm run 下一步
npm run 检查
npm run 体检
npm run 环境

原始英文命令仍然保留：

npm run status
npm run validate
npm run doctor
npm run learn -- next
npm run learn -- env-doctor
npm test

学习状态维护命令：

npm run learn -- resume-session
npm run learn -- pause-session
npm run learn -- begin-assessment
npm run learn -- finish-session <pass|partial|fail> <independence> <nextAction> [outcomeId=status ...]
npm run learn -- save-evidence "<text>"
npm run learn -- record-journal <target> "<text>"

finish-session 会根据 session 的 targetOutcomeIds 更新 outcome 进度；如果某个 outcome 的结果不同，可以追加 outcomeId=status 做细粒度覆盖。

课程包维护命令：

npm run learn -- new-track my-track "My Track"
npm run learn -- switch my-track

new-track 只创建课程包壳。真实课程内容需要根据 engine/prompts/create-track.md 生成并写入 tracks/<track-id>/source/。

验证范围

npm run validate 会检查：

• 必需目录和文件是否存在。
• 全局状态、学习者画像、课程包 source、session 和 track state 是否符合 JSON Schema。
• global.activeSessionId 与 active track 的 currentSessionId 是否一致。
• current session 是否仍是可继续的未闭环状态。
• session 引用的 module/outcome 是否属于对应课程包 source。
• session JSON 与 session Markdown 的状态、结果、独立程度和 next action 是否一致。
• active track 的 handoff 是否反映 current session、module、session status、blocker 和唯一下一步。
• 每个课程包是否具备对应的 sessions/、workspace/、journal/、state/tracks/ 和 state/handoff/ 文件。

当前实现进展

• 已完成 Learning OS 基础目录、策略文档、prompt、模板和 schema。
• 已实现 engine/cli/learn.mjs，覆盖状态查看、校验、doctor、环境检查、课程包创建/切换、session 暂停/恢复、证据记录、journal 记录和 session 结束。
• 已加入基于 Node test runner 的 CLI 校验测试。
• 已创建第一条试运行课程包 fullstack，包含 9 个 module、36 个 outcome、5 个 project 和 5 份 rubric。
• 已补充学习者入口文档 LEARNER.md。
• 已建立跨设备恢复和同步规则，恢复学习时不依赖聊天记录。

已知边界

• README 不作为当前学习进度事实源。
• tracks/*/generated/ 是派生文档，不能覆盖 tracks/*/source/。
• outcome 掌握进度由 finish-session 写入 track state；复杂验收需要用 outcomeId=status 显式覆盖。
• project milestone 当前以标题级粒度为主，具体任务拆分由后续 session 承担。
• 环境差异，例如 pnpm/npm 可用性、Node 版本、数据库或 SSH 配置，应记录为 blocker，而不是学习失败。

实时状态

查看当前学习位置：

npm run status

查看唯一下一步：

npm run learn -- next

做跨设备恢复检查：

npm run doctor

学习者日常只需要阅读：

开始这里.md
目录地图.md
LEARNER.md

使用模型

1. 从学习目标创建或选择课程包。
2. 根据课程包 source 和当前 state 规划一次 session。
3. 学习者完成任务并提交 evidence。
4. Codex 按 rubric 验收，记录独立程度。
5. 根据结果推进、补救、复习或修订路线。
6. 更新 state、session、handoff 和必要的 journal。
7. 通过 validate 和 git 同步保证跨设备可恢复。

设计原则

• engine 只定义怎么学，tracks 只定义学什么。
• 状态文件机器可读，跨设备恢复不靠聊天记忆。
• 完成必须有 evidence，进度必须能被 rubric 支撑。
• Codex 代写可以完成产物，但不能直接证明学习者掌握能力。
• 学习系统应能复用于新的学习目标，而不绑定单一课程。