企业官网建设流程全解析

OpenMAIC 螺旋式课程设计 Skill 完全指南：用概念脊柱驱动系列课的结构性升阶重访

【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC

导读

本文基于 OpenMAIC Agent Runtime 内置的spiral-curriculumSkill（定义于 skills/agent-runtime/spiral-curriculum/SKILL.md）展开，讲解如何为一组系列课堂建立布鲁纳（Bruner）式螺旋课程架构：让少数核心概念在整个系列中反复回来，并且每次回来都发生结构性升阶，而不是线性铺排或机械复习。读完本文，你将掌握概念脊柱、遭遇史、升阶操作符、Spiral Contract、两层设计流程与假螺旋检查这套完整方法论，并理解它在 OpenMAIC 中对应的工具调用链与仓库源码实现。

一、Skill 定位与触发边界

spiral-curriculum是 OpenMAIC Agent Runtime 的系列课规划 Skill，与同目录下的stage-design（单节课堂创建基线）、curriculum-planner（多课堂文件夹与批量交付）组合使用。它的 frontmatter 声明了触发语义：

• 何时使用：用户明确要求布鲁纳式螺旋课程、渐进式概念重访，或希望以"理解如何发展"为主线组织系列课；
• 何时不使用：单节独立课（走stage-design+ 主题 Skill）、只要求顺序覆盖内容而无概念升阶重访（走curriculum-planner）、风格复制或 PPT 导入（走style-clone/pptx-import）。

在 OpenMAIC 中，Skill 的最小设计对象不是某一节课的目录，而是"概念脊柱 + 每个概念的遭遇史"。每个 Skill 由目录名作为唯一契约 id，从 lib/server/agent-runtime/skills.ts 中描述的LoadedSkill（含id、title、description、content、constraints等字段）加载；目录位置可通过OPENMAIC_AGENT_SKILLS_DIR环境变量覆盖，默认指向${process.cwd()}/skills/agent-runtime（见 lib/server/agent-runtime/config.ts）。工作台界面中该 Skill 以"螺旋式课程设计 / Spiral curriculum design"展示（见 lib/i18n/workbench.ts 与 L450 的中英文词条）。

二、第一原则：Revisit 不等于 Review

"第 1 课讲概念、第 3 课复习概念、第 6 课再复习"不是螺旋。每次重访必须明确回答：这一次比上一次多了什么？原 Skill 给出了六个升维维度：

判定规则很硬：如果一次回来没有在任何维度更高，就只是重复，必须重写。这也是下文"假螺旋检查"的第一条判据（Repeated, not spiraled）的正面表达。

三、页面内容红线：规划语言不下沉

Concept Spine、encounter、growth operator、Spiral Contract、revisit、概念脊柱、遭遇史、●/▲/◆等属于教师侧规划语言，可以出现在对话、架构和页面 brief 中，但不得出现在学生可见的标题、标签或正文。

两条具体执行规则：

1. "本次比上次多了什么"写进 brief，不写成学生页面上的"复杂度升级"标签；
2. 老师与代理的口述走 narration / actions，不写成"老师说""学生说"的静态正文。

这条红线与feynman-learning、stage-design中"规划黑话留在教师侧、学生页面只呈现可执行动作"的约定一脉相承，是 OpenMAIC 所有教学法 Skill 共享的内容纪律。

四、概念脊柱（Concept Spine）：先立观念，再排课时

不要先排课时清单。先回答：整个系列结束后，学生真正应该建立哪几个能够反复使用和迁移的核心观念？

• 每个核心概念写成一句可迁移的理解，而不是一个名词（例如"函数是把重复过程命名并可复用的思维单元"，而非"函数"二字）；
• 一个系列通常选择3–6 个核心概念，过多会导致每课浅尝辄止；
• 每个概念同时声明初始理解目标和最终理解目标，作为 Learner Progression 的两个端点；
• 可先结合understanding-by-design（skills/agent-runtime/understanding-by-design/SKILL.md）确定大概念、基本问题与表现性证据，再用本 Skill 安排跨课升阶重访——两个 Skill 的分工是：UbD 负责"理解什么、如何证明"，螺旋负责"概念如何跨课升级地回来"。

五、Spiral Map：为每个概念维护遭遇史

为每个核心概念维护跨课遭遇史，标准演进路径为：直觉经验 → 机制解释 → 多变量关系 → 形式化模型 → 陌生情境迁移 → 与其他概念整合。

教师侧 Spiral Map 使用三个符号标记：

关键约束：每个标记旁边还必须写明本次新增结构——只有符号、没有升阶说明的表格没有价值。Spiral Map 本质上就是"每个概念的遭遇史 + 每次回来的新增量"的可视化记录。

六、规划一次重访：四个决策

对每个concept + previous encounter + target growth组合，决定四件事：

1. 保留什么：哪些已有理解不需要重新教学（避免把旧内容当新课再讲一遍）；
2. 增加什么：本轮新增的内容或条件（对应升阶操作符选型）；
3. 重组什么：哪些孤立知识需要组成机制或关系（对应"关系密度"维度）；
4. 迁移到哪里：用哪个新情境检验概念结构（对应"迁移距离"维度）。

这四个决策同时回答了第一原则的追问——"这一次比上一次多了什么"——并把答案落到 brief 而非学生页面。

七、升阶操作符（Growth Operators）：结构升级的最小动作集

Skill 定义了七种升阶操作符，作为"本次重访升在哪"的原子表达：

使用纪律：一次重访通常选择 1 个主操作符和少量辅助操作符，不要一次叠满所有操作符——那只会堆难度，不会加深理解。例如首次引入"函数"时主操作符用ADD_RELATION（函数与变量、流程的关系），第二次回来换CHANGE_REPRESENTATION（从口述流程到画流程图再到符号表达），第三次再上INCREASE_TRANSFER_DISTANCE（跨到非编程领域找"把过程命名并复用"的例子）。

八、概念记忆：螺旋依赖跨 stage 的共享记忆

螺旋依赖跨 stage 的共享记忆，而平台不会替本 Skill 自动维护概念模型，因此必须由 Agent 在当前对话中保存教师侧运行记录，至少包含 10 项字段：

concept id encounter history representation history complexity level known relations misconceptions detected examples used transfer distance mastery evidence next revisit target

开始下一课前，必须使用read_stage_outline回读前面课堂的持久化页面列表（而非信任原计划）；需要核对真实内容时继续用read_stage。这条纪律在仓库后端有对应实现：read_stage_outline工具（lib/server/agent-runtime/curriculum-tools.ts）返回某 stage 的标题与页面列表（order/title/type），并通过mergeStageOutline把"真实已生成的 scenes"与"仍处于 planned 状态的 outline 条目"做联合视图，保证回读的是课堂实际落盘内容。工具本身按会话 owner 做 fail-closed 的权限隔离，foreign stage 一律拒绝——这也是跨课读取安全边界的一部分。

九、每课的 Spiral Contract：七字段重访契约

每个 stage 在教师侧规划中必须有一份 contract，原 Skill 定义了七字段：

• returning_concepts：哪些旧概念回来；
• new_concepts：哪些概念第一次出现；
• added_complexity：比之前复杂或抽象在哪里；
• new_relation：新增了什么概念关系；
• representation_shift：是否更换表征；
• transfer_target：进入哪个新情境；
• future_hook：故意留下什么，供后续重访。

一个典型的第三课 contract 示例：

{ "returning_concepts": ["函数", "循环"], "new_concepts": ["递归的直觉前奏"], "added_complexity": "从单层调用升级为调用链：一个函数体内出现另一个函数调用", "new_relation": "函数与循环：把重复迭代封装为可调用单元", "representation_shift": "从自然语言流程图升级为伪代码符号", "transfer_target": "把'命名并复用过程'迁移到做饭步骤组织", "future_hook": "故意留下'递归为什么可行'的缺口，第五课才闭合" }

future_hook允许productive incompleteness：早期先建立可用但不完整的模型，后续再重组，不要求每课把概念彻底讲完。这是螺旋区别于"线性讲完再复习"的关键机制——每课都留一根线，由后续课拉起来。

十、两层设计：先架构后生成

第一层：Spiral Architecture（对话中确认）

先在对话中产出并请用户确认五件事：

1. Concept Spine：每个核心概念的初始与最终理解目标；
2. Course Timeline：各课的主题和任务；
3. Concept Spiral Map：每个概念何时出现、何时回来、每次增加什么；
4. Learner Progression：学生理解应怎样逐课变化；
5. 每课的 Spiral Contract 和概念交叉点。

使用ask_user让用户能调整课时数、概念出现时机、深度与交叉关系。架构未确认前不要创建课堂。这一步与curriculum-planner的 Gate 2 确认门禁一致：系列课是单节课数倍的工作量，用户必须在任何 stage 创建之前看到完整蓝图（skills/agent-runtime/curriculum-planner/SKILL.md 中明确 "Never start building before the user has signed off on the full series"）。

第二层：Generate Lessons（架构确认后批量交付）

架构确认后，默认把整个已批准系列持续建到完成，不在每课之间重复停下确认，除非用户明确要求分批验收。执行序列：

1. create_folder创建系列文件夹（工具实现于 lib/server/agent-runtime/curriculum-tools.ts，folderId是后续 stage 归类的锚点）；
2. 每课调用create_stage，传入该folderId，使 stage 在创建的同时归档进文件夹，不留在 ungrouped 区；
3. 每课先set_roster，再按批准计划逐页generate_scene；
4. 需要补写旁白时逐页generate_actions，修改旁白后补generate_tts；
5. 使用list_scenes、read_stage_outline和read_stage验收持久化结果；
6. 开始后续课堂前更新概念记忆。

工具调用顺序由stage-design（skills/agent-runtime/stage-design/SKILL.md）约束：create_stage → set_roster → 逐页 generate_scene → list_scenes → read_stage 校验 speech action 的 audioId → 缺失则 generate_tts。螺旋 Skill 在此之上增加跨课编排，但不改变单课构建序列。架构本身只留在教师侧规划中，不生成成学生页面。

十一、假螺旋检查：六种失败模式

整套系列完成后，逐概念对照检查，命中任一项即回到对应 Spiral Contract 修改页面 brief 或课程安排，再重新验收：

注意这六条都是"症状 → 定性"对，而非定量阈值——判定依据是教师侧记录的遭遇史与升阶操作符是否真实落地。

十二、完成标准

一次完整的螺旋课程系列交付必须同时满足：

• 每个概念都有初始理解目标、最终理解目标和完整遭遇史；
• 每次重访都标明主升阶操作符及新增结构；
• 每课都有七字段 Spiral Contract；
• 架构先确认，确认后整个系列被持续持久化到文件夹中；
• 每课实际内容已回读，概念记忆不是只依赖原计划；
• 学生可见文字不包含螺旋元数据、规划黑话或角色台词；
• 每课仍满足stage-design的页面、roster、持久化与音频完成标准（所有 speech action 必须有audioId，旁白改词后必须重新generate_tts，否则页面静音输出）；
• 系列通过假螺旋检查。

十三、与其他教学法 Skill 的关系

OpenMAIC 的 agent-runtime Skill 体系是组合而非替代关系：

• understanding-by-design：先确定大概念、基本问题和表现性评估，本 Skill 负责让这些概念跨课升阶重访——一个是"目标设计"，一个是"升阶编排"；
• feynman-learning：在一节课堂内推动解释反复外化和重建（学习者先讲、暴露最小缺口、追问补链、去术语、拆类比、迁移、留学习记录），本 Skill 在整个系列中安排概念反复回来——一个在单课内螺旋，一个在系列间螺旋；
• learning-to-learn与social-emotional-learning：是平行目标，只有服务当前概念重访时才嵌入，不另起课程主线。

十四、仓库落地：Skill 如何被加载与约束

从源码角度理解本 Skill 的运行机制：

• 加载入口：skillsDir由OPENMAIC_AGENT_SKILLS_DIR覆盖，默认${process.cwd()}/skills/agent-runtime（lib/server/agent-runtime/config.ts）；Skill 的 id 即目录名，是 Agent 匹配与读取的契约，title为展示名（lib/server/agent-runtime/skills.ts 中LoadedSkill类型注释明确 "The id is the contract"）；
• 跨课工具：系列层工具create_folder、move_to_folder、list_folder_stages、read_stage_outline全部集中在 lib/server/agent-runtime/curriculum-tools.ts，带 owner 作用域与 fail-closed 权限校验，且每个 execute 都在 IO 边界重新检查 abort signal；
• 单课工具：create_stage、set_roster、generate_scene、list_scenes、read_stage、patch_stage、generate_actions、generate_tts等由stage-design与stage-dsl（skills/agent-runtime/stage-dsl/SKILL.md）给出读写路径约定，例如read_stage用path:/scenes/<order|sceneId>定位单页、用detail:"source"检查 speech action 的audioId；
• 约束体检：若配置了outline-constraints.json，运行时会在每页生成后对照真实 stage 做结构体检；spiral-curriculum本身未配置结构化约束文件，其约束主要落在对话规划层面——这也意味着假螺旋检查是教师侧执行的责任，而非运行时自动完成。

结语

螺旋式课程设计 Skill 的核心交付物不是课堂页面，而是"概念脊柱 + 遭遇史 + 升阶操作符 + Spiral Contract"这一整套教师侧架构。在 OpenMAIC 中，它的边界清晰：架构在对话中确认，课堂在确认后批量持久化，假螺旋检查在交付前兜底。若要从零搭建一个系列，建议按 skills/agent-runtime/spiral-curriculum/SKILL.md 原文、配合 stage-design 与 curriculum-planner 三份文档组合阅读，再对照 curriculum-tools.ts 理解每一步调用在后台的真实落盘行为。

【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC