Learning Process Manager

面向 AI Agent 的本地学习过程管理 CLI：以学习单元和可验证证据组织路线，持久化真实会话，并通过 FSRS 或艾宾浩斯间隔重复算法安排延迟检索。

功能概览

创建和维护学习项目元数据
管理学习单元、依赖关系、掌握状态和证据引用
识别首次课程、新单元和续学入口，为 Agent 提供机器可读的默认导览顺序
记录学习会话、学习时长、阶段和摘要
管理传统闪卡，以及引用式笔记、知识点、实践项目复习项
查询待复习、过期复习内容，并提交复习评分
输出人类可读文本、JSON 或 porcelain 格式，方便 Agent 和脚本集成
通过文件锁和原子写入保护项目索引、复习索引、复习历史和会话历史

Agent Skills

本仓库提供两个并列的 Agent skill：

skills/learning-cli/：管理 learn CLI、学习项目、复习队列、闪卡和数据边界。
skills/learning-guide/：基于 learn CLI 编排学习引导、复习、测验和会话记录。

npm 发布包包含两个完整 Skill。安装或同步时复制对应的完整 skill 目录，不要只复制单个 SKILL.md。

学习状态语义

session end 只记录实际发生的学习会话，不代表知识已经掌握。
项目的 stage 和 progress 是项目级元数据，不替代单个知识单元的掌握证据。
单元在本次会话撤去提示后通过解释和应用，只能记为“待巩固”；经过时间间隔后的独立检索仍然通过，才能记为“稳定掌握”。
Note 前部维护适合快速回顾的稳定知识，只在证据区保留能够反映关键错误、提示依赖或验收结果的代表性回答；复习调度继续由 CLI 管理。
learning-units.json 是单元状态和证据索引的事实源；Note 面向快速回顾，只追加具有诊断或验收价值的精选证据，不保存完整对话。

教学入口语义

learn status <project> --json 和 learn session start ... --json 会返回 data.teachingEntry：

learn status and learn next also return data.learningPlan for "continue" and recovery flows. It includes the current unit, current objective, completed objectives, pending objective, next action, allowed scope, recommended interaction type, recent checkpoint, recent evidence, evidence gaps, and available diagrams. When the user says "continue", follow learningPlan.nextAction and learningPlan.pendingObjective by default; if the user asks a side question, answer it and then return to the saved plan.

project_and_unit_overview：首次进入项目，先做课程总览，再做首单元导览。
project_overview：首次进入项目，但还没有可教学单元。
unit_overview：进入一个没有历史会话的新单元。
resume：续学已有历史会话的单元，只需简短定位。
none：没有需要呈现的教学入口。

sequence 给出 project_overview → unit_overview → diagnostic 等默认执行顺序，sources 给出应读取的项目内相对文件。课程总览必须先建立学习对象的最小心智模型：一句话定义、核心问题、整体运行图景、相邻概念对比、非例和适用边界，然后再介绍价值、路线和完成证据。导览不构成掌握证据，也不会自动推进单元状态。

CLI 只依据项目历史推导入口，不解析用户自然语言。用户明确说“重新开始”“从头学习”或“按新方案重来”时，learning-guide 应覆盖默认 resume，重新执行课程与当前单元导览，但不得清空已有进度。重置或删除进度属于另一项需要明确确认的数据操作。

项目初始化问询

创建学习项目时，Agent 优先从当前对话、已有材料和项目环境推断信息。只有缺失内容会改变学习终点、路线规模或实践可行性时，才一次集中询问，最多三个短问题：目标任务、使用场景和时间约束。README 在路线之前先建立学习对象的最小心智模型；当前基础在首个学习单元通过诊断任务验证，不要求用户自报抽象等级，其他缺失信息以明确假设记录在项目 README 中。

环境要求

Node.js >= 18
npm

安装

发布到 npm 后，普通用户可以全局安装：

npm install -g learning-process-manager
learn init
learn doctor

自测或跨平台测试时，可以从发布附件或其他下载地址拿到 .tgz 包后安装：

npm install -g ./learning-process-manager-0.1.0-alpha.1.tgz
learn init
learn doctor

本地开发安装：

npm install
npm run build
npm link

完成后会注册全局 learn 命令。

常用开发命令

npm run build        # 编译到 dist/
npm run dev          # 监听模式构建
npm run typecheck    # TypeScript 类型检查
npm run test:run     # Vitest 单元测试
npm run test:e2e     # 构建后 CLI 端到端测试
npm run lint         # ESLint
npm run verify       # lint/typecheck/test/build/audit/pack 全量检查
npm run pack:dry-run # 检查 npm 包内容
npm run clean        # 清理 dist/

快速开始

learn init
learn new "JVM 深入理解" --topics 12
learn unit add --project "jvm-深入理解" --id class-loading --title "类加载机制"
learn list
learn session start --project "jvm-深入理解" --unit class-loading
learn unit evidence --project "jvm-深入理解" --unit class-loading --type explain --summary "能独立解释类加载委派链"
learn session end --project "jvm-深入理解" --duration 45 --summary "学习类加载机制"
learn flashcard create --project "jvm-深入理解" --front "什么是双亲委派模型？" --back "类加载器优先委托父加载器加载类。"
learn review "jvm-深入理解" --due
learn review-submit <content-id> good --project "jvm-深入理解"
learn status "jvm-深入理解" --json
learn stats --json

如果命令写入了非预期目录，先运行 learn doctor 查看当前索引路径、项目目录和配置来源。

CLI 命令

全局选项：

learn --json       # 输出 JSON，供 Agent 或脚本使用
learn --porcelain  # 输出机器可解析文本
learn --quiet      # 最小输出

主要命令：

learn new <主题> [--path <路径>] [--topics <数量>]
learn project import --path <目录> [--name <项目名>] [--topic <主题>] [--json]
learn list [--json] [--porcelain]
learn progress [项目名] [--stage <阶段>] [--json]
learn status [项目名] [--limit <数量>] [--json]
learn next [项目名] [--limit <数量>] [--json]
learn unit add --project <项目名> --id <单元ID> --title "<标题>" [--note <路径>] [--prerequisites <ID列表>]
learn unit list --project <项目名>
learn unit next --project <项目名>
learn unit evidence --project <项目名> --unit <单元ID> --type <类型> --role <角色> --summary "<证据>" [--assisted] [--delayed]
learn unit transition --project <项目名> --unit <单元ID> --to <状态>
learn checkpoint add --project <项目名> --event <事件> --summary "<检查点>" [--unit <单元ID>] [--objective <目标>] [--completed <目标>] [--pending <目标>] [--next-action <动作>]
learn checkpoint list --project <项目名> [--unit <单元ID>] [--limit <数量>]
learn session start --project <项目名> [--unit <单元ID>]
learn session end --project <项目名> [--duration <分钟>] --summary "<摘要>" [--stage <阶段>]
learn review [项目名] [--due] [--overdue] [--type <类型>] [--limit <数量>] [--json]
learn review-submit <content-id> <again|hard|good|easy> --project <项目名> [--json]
learn flashcard create --project <项目名> --front "<问题>" --back "<答案>"
learn flashcard add-note --project <项目名> --file <笔记路径> --title "<标题>"
learn flashcard add-knowledge --project <项目名> --file <笔记路径> --title "<标题>" [--start <行>] [--end <行>]
learn flashcard add-project --project <项目名> --dir <路径> --title "<标题>"
learn flashcard list-all --project <项目名> [--type <类型>] [--json]
learn stats [--week] [--month] [--json]
learn init [--json]
learn config get [配置项] [--json]
learn doctor [--json]

数据存储

默认项目索引会保存在当前用户的应用数据目录中；在 Codex 工作区沙箱中运行时，会改为保存在当前工作目录的 .learning-process-manager/ 下，避免写入工作区外的锁文件失败：

Codex workspace: <当前工作目录>/.learning-process-manager/learning-projects.json
Windows: %APPDATA%\learning-process-manager\learning-projects.json
macOS: ~/Library/Application Support/learning-process-manager/learning-projects.json
Linux: ${XDG_DATA_HOME:-~/.local/share}/learning-process-manager/learning-projects.json

默认项目目录：

<应用数据目录>/projects/<project-name>/

每个学习项目包含：

README.md
progress.md
learning-units.json
notes/
knowledge/
flashcards/
projects/
resources/
reviews/
  review-index.json
  review-history.json
  session-history.json
  checkpoints.json

说明：

review-index.json 保存可复习内容索引。
review-history.json 保存复习提交记录。
session-history.json 保存 learn session end 生成的学习会话记录，learn stats 的周/月统计基于该文件计算。
checkpoints.json saves structured learning checkpoints for recovery: objective, evidence ids, next action, and pending work. It must not contain full chat transcripts. If checkpoint writing fails, the Agent must report the failure instead of claiming progress was saved.
active-session.json 只在会话进行中存在，保存真实开始时间和绑定单元。
learning-units.json 保存学习单元、依赖、状态和精选证据；由 CLI 管理，不手工修改。
教学入口不单独落库；CLI 根据已结束会话、活动会话和下一单元状态实时推导。

学习单元状态机

not_started → learning → assessment_pending → consolidating → mastered
                    └──────────────→ remediation ────────────┘

进入 consolidating 前必须同时存在独立的解释和应用证据。
进入 mastered 前必须存在经过时间间隔的独立证据。
前置单元未 mastered 时，后续单元不能进入 learning。
项目完成数和进度由 mastered 单元同步，不由学习时长推断。

证据类型表示能力层级：recall、explain、apply、transfer、artifact。证据角色表示事实性质：attempt、misconception、correction、verification、observation。只有独立的 correction/verification 能满足掌握门槛；带 --assisted 的证据表示仍依赖提示，带 --delayed 的证据表示经过时间间隔后的检索或应用。

配置

项目支持通过 cosmiconfig 加载配置，搜索文件包括：

.learning-clirc
.learning-clirc.json
.learning-clirc.yaml
.learning-clirc.yml
package.json

常用配置项：

{
  "indexPath": "/path/to/learning-data/learning-projects.json",
  "defaultProjectsDir": "/path/to/learning-data/projects",
  "reviewAlgorithm": "fsrs",
  "ebbinghausIntervals": [0.5, 1, 3, 7, 14, 30, 90],
  "timezone": "Asia/Shanghai"
}

如果存在显式配置，learn new 会使用配置中的 defaultProjectsDir 作为默认项目目录；也可以通过 learn new --path <路径> 覆盖单个项目路径。indexPath 控制全局项目索引文件位置，和 defaultProjectsDir 是两个独立概念。

也可以用环境变量覆盖路径：

LEARN_HOME=/path/to/learning-data
LEARN_INDEX_PATH=/path/to/learning-projects.json
LEARN_PROJECTS_DIR=/path/to/projects

首次使用可运行 learn init 创建索引文件；路径排查可运行 learn doctor；查看有效配置可运行 learn config get --json。

复习模型

复习内容类型：

note
knowledge-point
project
flashcard

存储方式：

inline: 直接存储问题和答案，适合传统闪卡。
reference: 只保存文档路径、章节或行号，复习时动态读取源文档。

评分：

again
hard
good
easy

默认算法是 FSRS，基于 ts-fsrs 动态调整下一次复习时间。也支持艾宾浩斯固定间隔策略。

项目结构

src/
  cli.ts                       # Commander 程序入口
  bin/learn.ts                 # learn 可执行入口
  commands/                    # CLI 子命令
  config/                      # 配置加载
  lib/
    project.ts                 # 项目索引和元数据管理
    spaced-repetition.ts       # FSRS/艾宾浩斯和复习索引
    file-utils.ts              # 文件锁与原子写入
    session-history.ts         # 学习会话历史
    teaching-entry.ts          # 课程/单元导览与续学入口推导
  types/                       # 类型定义
templates/                     # 新学习项目模板
tests/                         # Vitest 测试

验证

npm run typecheck
npm run build
npm run test

许可证

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github		.github
e2e		e2e
learning-projects		learning-projects
skills		skills
src		src
templates		templates
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
SECURITY.md		SECURITY.md
TEST_REPORT.md		TEST_REPORT.md
TEST_REPORT_V2.md		TEST_REPORT_V2.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Navigation Menu

Repository files navigation

Learning Process Manager

功能概览

Agent Skills

学习状态语义

教学入口语义

项目初始化问询

环境要求

安装

常用开发命令

快速开始

CLI 命令

数据存储

学习单元状态机

配置

复习模型

项目结构

验证

许可证

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Learning Process Manager

功能概览

Agent Skills

学习状态语义

教学入口语义

项目初始化问询

环境要求

安装

常用开发命令

快速开始

CLI 命令

数据存储

学习单元状态机

配置

复习模型

项目结构

验证

许可证

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages