用途：在真实编码过程中顺带讲解正在使用的技术原理，以当前项目为实例，同时不打断任务推进。仅当操作者开启 learn 模式后启动，关闭即停止讲解与工具调用，已有进度保留。
主要能力：通过本地 learn 工具按概念 id 或公开术语选择概念，依据返回深度（walkthrough/paragraph/line/none）呈现卡片自带的片段与图示，出现 Effect、Alchemy、XState 等概念时给出对应讲解；可读取与设置本地显示偏好（width、visual、snippet）；记录 shown、used、got-it、skipped、dismissed 等事件；在操作者明示开启问题后可进行适度检查。
使用方式：需一份带 learn 命令的 rat-stack 检出，先校验： git -C <checkout> status --porcelain node <checkout>/apps/cli/dist/cli.js --help 帮助输出须含 learnNext、learnRecord、learnPreferences、learnSetPreferences。存在本地改动时不得 pull/reset/stash，应另行克隆： git clone --depth 1 https://github.com/joelhooks/rat-stack.git rat-stack-learn cd rat-stack-learn pnpm install pnpm turbo run build --filter=@rat-stack/cli MCP 客户端运行 node apps/cli/dist/cli.js mcp。也可直接读取公开 deck： curl -fsS https://ratstack.sh/_content/learn.json curl -fsS https://ratstack.sh/api/learnDeck -H 'content-type: application/json' --data '{}' 偏好存于 ~/.rat-learn/preferences.json，默认 width=narrow、visual=inline-text、snippet=full。环境变量 RAT_LEARN_DIRECTORY、RAT_LEARN_ORIGIN 可改路径与来源。
前提与限制：卡片片段与图示须原样使用，不得自造；仅记录操作者实际使用与理解，不得从沉默或时长推断；进度保留在本地，公开端点默认不上传进度；不得手动编辑 JSONL；若 deck 或 CLI 不可用，只能如实说明并继续任务，不得声称进度已保存。反馈流程需设备授权，凭证仅用于 learnFeedback、三十分钟过期，仅在操作者主动要求时使用。技能仅建议不自动安装。