For Codex runtime, do not copy the whole repository into .codex/skills. Use the pruned sync script so docs, examples, adapters, images, and GitHub workflow files do not become runtime noise:

git clone https://github.com/heyu-233/learning-workflow-designer.git D:\codex_project\tutorial\learning-workflow-designer
cd D:\codex_project\tutorial\learning-workflow-designer
python scripts\sync_codex_skill.py --target $env:USERPROFILE\.codex\skills\learning-workflow-designer

This keeps only runtime files: SKILL.md, agents/, references/, scripts/, assets/, templates/, and LICENSE.

git clone https://github.com/heyu-233/learning-workflow-designer.git $env:USERPROFILE\.codex\skills\learning-workflow-designer

也可以让 Codex 安装：

请帮我安装这个 skill：https://github.com/heyu-233/learning-workflow-designer

我想学习这个项目，请整理成学习包。

进入 project-lab mode，围绕这个小项目生成 10 章学习路线和练习题。

通过练习一步一步完成这个项目，练习题里要有答题空间、运行记录和验收标准。

批改我的答案，并更新 learning-progress.json 和 skill-tree.html。

仓库提供了 Claude Code adapter：

adapters/claude-code/

安装后可以这样触发：

Use the learning-workflow-designer skill. Enter project-lab mode and generate a 10-chapter learning package in tutorial/.

中文：

使用 learning-workflow-designer skill。进入项目实验模式，先做材料审计，再生成默认 10 章学习包。

很多学习任务的问题不是“没有资料”，而是资料、源码、实验目标和最终项目混在一起，很难知道今天该做哪一步。

Learning Workflow Designer 不是通用 workflow engine。它更准确的定位是 project-driven learning package designer：把输入材料整理成一套可执行学习包。

如果已经有学习包，skill 会先看已有文件，再决定最小改动范围：

• 复用已有材料审计、章节结构、题目 ID、分值和技能树设置。
• 只重写用户要求改的章节或文件。
• 后续补充运行环境、源码、日志、截图、命令、板子信息或评分要求时，只合并进已有学习包，更新相关 待确认 项。
• 只有进度 JSON、分值或节点状态变化时才重新渲染 skill-tree.html。
• 只对本轮改过的中文文件跑编码检查。
• Project-Lab 和实操题默认不给完整参考答案，只给验收标准、最低提交证据、常见失败点和排查顺序。

这个仓库现在优先服务 Codex，因为 Codex Skill 能直接读文件、写学习包、渲染技能树并持续批改进度。但学习包本身不应该被 Codex 锁死。

跨平台使用说明见 docs/platform-adapters.md。

学习包质量会受原始材料影响。材料越清楚，练习越能落到具体文件、命令、日志、硬件现象和验收标准上。

生成完整学习包前，skill 会尽量从 5 个维度检查输入：

如果材料不足，它应该先输出“已确认 / 待补充 / 影响”，并把生成结果标记为临时学习包，而不是编造不存在的文件、命令或硬件现象。

技能树	练习链路	答题空间

它会：

1. 提取最终项目目标和验收标准。
2. 拆出 4 到 8 个项目里程碑。
3. 保留默认 10 个学习章节，除非用户明确要求改变章节数。
4. 把项目里程碑映射到 10 个章节里。
5. 让每章练习都连接基础知识、源码阅读、实现任务、运行观察和失败排查。

Project-Lab 任务通常会包含：

这一步要做什么：
怎么做：
1. 先看/先查：
2. 再修改/新建：
3. 然后运行/观察：
为什么这样做：
做到什么算完成：
如果失败，先查：
填写区：
- 我看了哪些文件/命令：
- 我改了什么：
- 我运行了什么：
- 我看到了什么现象：
- 我判断是否完成的依据：
- 我的具体卡点：写清楚卡在哪个概念/文件/现象，以及已经尝试过什么

输入可以像这样：

进入 project-lab mode。
目标是深入研究 FreeRTOS 源码，阅读分析主要流程，运行跟踪调试；
同时通过以函数为单位的临摹移植，逐步完成一个 IAP 二级启动小项目。
请生成默认 10 章学习路线、练习题、答题空间和验收标准。

输出会更像一套可做的实验路线，而不是泛泛的知识总结：

仓库内置了一个轻量示例：

• examples/freertos-lightweight/exercises.md
• examples/freertos-lightweight/reference-answers.md
• examples/freertos-lightweight/learning-progress.json
• examples/freertos-lightweight/skill-tree.html

重新渲染示例技能树：

python scripts/render_skill_tree.py examples/freertos-lightweight/learning-progress.json examples/freertos-lightweight/skill-tree.html --skin engineering

默认学习模式会生成一个 tutorial/ 文件夹：

练习题不会只是一串问题。它会保留可填写的答题区，例如空行、记录表、命令输出区、日志路径区和结论区。

平台无关规范见：

• docs/learning-package-spec.md
• docs/platform-adapters.md
• docs/prompt-pack.md
• templates/learning-package/

技能树由 learning-progress.json 驱动。XP 只来自显式带分值的练习，不会凭“感觉懂了”自动加分。

默认 5 级：

默认大多数项目使用 classic 称号组；少数项目会稳定抽到 sao、eu4、hoi4 或 civ6 风格称号，增加一点新鲜感。你也可以在 learning-progress.json 里指定 level_title_set 或自定义 level_titles。

这个 skill 会尽量遵守以下规则：

• 生成完整学习包前先做材料审计；材料不足时列出待补充项。
• 重做已有学习包时先判断改动范围，优先复用旧结构，不默认全量重做。
• 所有题目必须说人话：说明要做什么、怎么做、为什么做、做到什么算完成。
• 不用“建立环境基线、打通链路、构建能力闭环”这类抽象标题糊弄学生。
• 默认学习包为 10 章，除非用户明确要求改变章节数。
• 后面的章节可以复用前面的知识点，前面的章节不能依赖后面才讲的内容。
• 练习题、试卷和项目实验任务必须留下答题空间。
• 工程类任务必须包含可观察证据，例如命令输出、日志、截图路径或运行现象。
• Project-Lab Mode 中，每个主要练习都应该推动最终项目向前完成一小步。
• Project-Lab 和实操题的参考答案默认可以是轻量验收清单，不强制写完整答案。
• 对未知文件、命令、接口、硬件现象或验收日志写 待确认，不硬编。
• 中文输出生成后应运行编码检查，避免 PowerShell/CMD 写入导致乱码。

python scripts/validate_text_encoding.py tutorial

• 这是 Codex-first 项目；Claude Code adapter 已可用，但最完整的验证和渲染流程仍在 Codex 侧打磨。
• 输入材料质量会显著影响输出质量；材料不足时只能生成临时学习包。
• 它不是通用工作流编排器，也不负责替代真实编译、烧录、硬件调试或教师验收。
• 生成的练习和答案需要结合真实环境验证，尤其是嵌入式、Linux 驱动、Bootloader 和 RTOS 项目。

• 完善 source intake：更稳定地输出材料评分、缺失清单和临时学习包。
• 提升 Project-Lab Mode：让练习更像逐步实验手册，而不是题目列表。
• 扩展平台适配：继续完善 Claude Code，并补充 ChatGPT、Claude、Obsidian、VS Code 使用方式。
• 增加 CLI 雏形：输入资料路径，输出材料审计、学习包骨架、质量校验和技能树。
• 增加更多真实示例：FreeRTOS、Linux 驱动、U-Boot、论文阅读和课程复习。

Markdown 和 HTML 输出可直接使用。若需要 DOCX 转换，请确认 Python 环境中安装了 python-docx。

python scripts/md_to_docx.py learning-content.md learning-content.docx

这版 README 参考了几个 10k+ star 项目的信息结构：freeCodeCamp/freeCodeCamp 的学习定位和目录化组织、microsoft/vscode 的产品截图前置、vercel/next.js 的简洁 Quickstart、langchain-ai/langchain 的一句话定位和生态入口。这里借鉴的是呈现方式，不复制它们的文案。

MIT License. See LICENSE.