AI大师课课程创作工具

产品定位：AI大师课平台官方课程创作与发布工具。

将任意素材（PPT / PDF / DOCX / 图片 / 文本）一键转化为平台上可运行的 交互式 AI 课程，覆盖"素材 → 分段 → 编排 → 生成 → 优化 → 上传 → 发布 → 数据分析"全流程。

课程创作：自动解析素材结构，识别章节与知识点，生成可运行的 Teaching Prompts（每节课）和 Course Prompt（课程级引导指令），采用 MarkdownFlow 格式。

图片处理：自动提取素材中的图片并上传到平台，生成真实图片 URL，直接嵌入课程内容。

原子化发布：通过 build + import + publish 三步，将本地课程文件发布到 AI大师课平台，学员可直接在 /c/{bid} 访问和学习。

课后分析：发布后可查询学习者数量、完成率、卡住课时、评分、订单、收入等数据。

Skill 级别前置检查机制

本 Skill 在 被加载的第一时间 会执行 scripts/precheck.py 对 DISTILLATION_API_KEY 做校验，没有任何例外或降级路径：

若已配置：直接放行，静默通过（exit code 0）
若未配置：
- 交互模式 → 立刻引导用户粘贴 API Key，并询问是否保存到 .env 供以后复用
- 非交互模式（--non-interactive / --quiet） → 打印清晰错误信息并 立即 exit(2)
零依赖：precheck 仅使用 Python 标准库，无需 pip 安装任何包即可运行
LLM 不可绕过：调用任何脚本（distillation-cli.py、extract_images.py、precheck.py 自身）前，必须先运行 python scripts/precheck.py 并拿到 exit code 0

API Key 获取地址：https://ai-dashi.kcidea.com/settings/api-keys

支持与联系

有任何问题或需求，请联系AI大师课团队。

命令行工具 (CLI) — 与 AI大师课平台交互

本 Skill 内置 CLI 工具 scripts/distillation-cli.py，用于连接 AI大师课平台完成课程的创建、上传、发布与分析。

身份认证（第一步，必须）

| 命令 | 说明 | |------|------| | python distillation-cli.py apikey set <ak_...> | 配置你的 API 密钥（保存在 .env，以后自动读取） | | python distillation-cli.py apikey verify | 验证当前密钥能否连接到 AI大师课平台 | | python distillation-cli.py apikey clear | 清除本地保存的密钥 |

课程创作与发布

| 命令 | 说明 | |------|------| | python distillation-cli.py list | 查看你在 AI大师课平台上所有课程 | | python distillation-cli.py show <bid> | 查看某门课程的详细信息（课时数、价格、访问地址等） | | python distillation-cli.py build ./my-course | 本地验证课程目录结构是否符合平台要求 | | python distillation-cli.py import ./my-course | 将本地课程原子化导入到 AI大师课平台（创建或更新） | | python distillation-cli.py publish <bid> | 发布课程 — 发布后学员可通过 /c/{bid} 访问和学习 |

素材与图片处理

| 命令 | 说明 | |------|------| | python distillation-cli.py upload-image ./img.jpg | 上传单张图片到平台（返回图片 URL，可直接嵌入课程） | | python distillation-cli.py extract-images ./material.pdf --json | 从 PDF/PPT/DOCX 中自动提取所有图片并上传，返回图片资源表（JSON），在课程内容生成中内联使用 |

运营分析

| 命令 | 说明 | |------|------| | python distillation-cli.py analytics | 查看课程的课后分析数据：学习者数量、完成率、卡住课时、评分、订单、收入 |

平台配置

API 端点可通过以下方式配置（优先级递减）：命令行 --base-url / --api-key → 环境变量 DISTILLATION_BASE_URL / DISTILLATION_API_KEY → .env 文件。

课程目录结构

使用 CLI 导入的课程目录应包含：

my-course/
├── structure.json       # 课程结构和元数据（必需）
├── course-prompt.md     # 课程级别提示（推荐）
├── README.md            # 课程说明（可选）
└── lessons/
    ├── lesson-01.md     # 每节课的 MarkdownFlow 内容
    ├── lesson-02.md
    └── ...

`structure.json` 支持两种格式：

1. 章节+课时结构（推荐）：

{
  "version": "1.0",
  "title": "我的课程标题",
  "description": "课程描述",
  "price": 99.00,
  "keywords": ["Python", "编程入门"],
  "chapters": [
    {
      "title": "第一章：基础入门",
      "lessons": [
        {
          "id": "lesson-01",
          "title": "第一课标题",
          "file": "lessons/lesson-01.md",
          "type": "trial"
        },
        {
          "id": "lesson-02",
          "title": "第二课标题",
          "file": "lessons/lesson-02.md",
          "type": "normal"
        }
      ]
    },
    {
      "title": "第二章：进阶学习",
      "lessons": [
        {
          "id": "lesson-03",
          "title": "第三课标题",
          "file": "lessons/lesson-03.md",
          "type": "normal"
        }
      ]
    }
  ]
}

2. 扁平课时结构（向后兼容）：

{
  "version": "1.0",
  "title": "我的课程标题",
  "description": "课程描述",
  "price": 99.00,
  "keywords": ["Python", "编程入门"],
  "lessons": [
    {
      "id": "lesson-01",
      "title": "第一课标题",
      "file": "lessons/lesson-01.md",
      "type": "trial"
    },
    {
      "id": "lesson-02",
      "title": "第二课标题",
      "file": "lessons/lesson-02.md",
      "type": "normal"
    }
  ]
}

注意：

优先使用 chapters 结构，这样导入到系统后会有明确的章节和课时层级
如果使用扁平 lessons 结构，系统会自动创建一个默认章节包含所有课时
课时类型：trial（试学）或 normal（正式）

详细的示例请查看 examples/ 目录。

执行模式

有两种模式适用于所有阶段（分段/编排/生成/优化）：

标准模式（默认）：输入质量足够时，使用标准模式完整执行各阶段
回退模式：输入不完整、冲突或质量较低时，生成粗略输出，明确标记不确定性，并提供聚焦的重新运行提示

每个阶段都有自己的回退形态。

对话交互协议（Conversation Interaction Protocol）

核心原则：每个阶段完成后必须提供明确的下一步选项；当缺少凭据或配置时通过对话收集，而非报错退出。

阶段完成后的标准交互

A. 课程生成完成后

当课程内容（teaching prompts + course prompt）生成完毕后，必须按以下模板回复：

"✅ 课程《{课程标题}》已生成完毕！

📊 概览：{X} 章节，{Y} 课时，平均每课时 {Z} 个交互点

📚 课程大纲： {列出3-5个主要章节标题，每项一行}

下一步你想做什么？

🚀 上传到 AI大师课平台（推荐）

👀 先看看某个课时的详细内容

✏️ 进一步优化或调整某些课时

💾 保存为本地文件，稍后再部署

请回复数字，或直接描述你的想法。"

如果用户回复"1"或"上传" → 进入"凭据检查"流程（见下方 B）。 如果用户回复"2"或"查看" → 展示大纲并询问用户想看哪个课时。 如果用户回复"3"或"优化" → 询问具体想优化什么（结构/内容/难度/交互设计）。 如果用户回复"4"或"保存" → 将课程文件写入工作目录并告知路径。

B. 选择"上传到平台"后的凭据检查

当用户选择上传到平台时，立即按以下顺序检查：

检查 1：是否有 API Key

如果没有找到 API Key（没有命令行参数、没有环境变量、没有 .env 文件）：

"🔑 需要先配置 API key

请提供你的 API key（以 ak_ 开头的一串字符）。

获取方式：登录 AI大师课平台 → 设置 → API Keys → 创建新 Key

直接把 key 粘贴在这里即可。"

用户提供 key 后：

"💾 是否保存这个 API key 供以后使用？（回复「保存」或「仅本次使用」）"

如果用户说"保存"：保存到 .env，并告知已保存
如果用户说"仅本次"：仅在本次会话中使用，不持久化

安全规则：在任何后续回复中，永远不要原样回显完整的 API key，仅回显前缀（如 ak_xxxx...）。

检查 2：Base URL 是否可达

如果找到了 API key，先尝试验证连接。如果默认 Base URL（或已配置的 URL）不可达：

"⚠️ 无法连接到服务器 {当前配置的 URL}

请告诉我你的 AI大师课平台实际地址：（例如 https://ai-dashi.kcidea.com 或你自部署的地址）"

用户提供新 URL 后，先验证可达性，再继续上传流程。

C. 上传成功后的后续选项

上传课程到平台成功后，必须按以下模板回复：

"🎉 课程已成功上传到 AI大师课平台！

📋 课程信息：

课程 ID：`{course_bid}`

课时数：{lesson_count}

🔗 有用的链接：

📋 管理后台：{base_url}/creator/course/{course_bid}

👀 课程预览：{base_url}/c/{course_bid}?preview=true

下一步：

🚀 发布课程（让学员可见）

✏️ 在平台上继续编辑

📊 查看课程分析

🎨 生成课程封面图片

想做什么？回复数字即可。"

D. 发布流程

当用户选择"发布课程"时，必须先进行确认：

"⚠️ 发布确认

即将发布《{课程标题}》。

发布后学员将可以：

在平台上搜索到这门课程

可以报名并开始学习

确认发布吗？回复「确认发布」继续，或告诉我你想先调整什么。"

用户确认后执行发布，成功后回复：

"✅ 课程已成功发布！

🎉 学员可以在以下地址访问： {base_url}/c/{course_bid}

需要我帮你生成一条适合朋友圈/社群分享的文案吗？"

配置管理策略

API Key 和 Base URL 的优先级（从高到低）：

对话中用户最新提供的值（本次会话优先）
用户在对话中显式保存到 .env 的值
环境变量 DISTILLATION_API_KEY / DISTILLATION_BASE_URL
默认值：Base URL = https://ai-dashi.kcidea.com

会话上下文记忆：

记住最近一次成功上传的 course_bid 和平台 URL
当用户说"查看那门课程"或"发布刚才那门课"时，能定位到最近的课程
记住用户的 Base URL 偏好，下次对话中优先使用

错误处理与回退

当上传过程中遇到错误（网络问题、权限问题、格式问题等）：

"❌ 上传遇到问题：{简要错误描述}

你可以：

🔄 重试

✏️ 调整后再试（告诉我问题在哪，我帮你修复）

💾 先保存为本地文件，稍后再上传

想怎么做？"

不要让用户看到原始的技术错误信息（如 HTTP 401、堆栈跟踪等），用通俗语言描述。

跨文件概念路由

有些概念跨越多个参考文档。在创作或审核之前，请使用下表定位权威来源：

| 概念 | 语法/格式 | 策略/规则 | 模式/数据 | |------|-----------|-----------|-----------| | 变量 | references/markdownflow.md#variables | references/pedagogy.md#variable-strategy | references/data-contracts.md#variable-table | | 交互 | references/markdownflow.md#interactions | references/pedagogy.md#interaction-design | — | | 视觉内容 | — | references/pedagogy.md#visual-text-coordination | references/data-contracts.md#segment-schema (visual_cue / visual_text_pair_cue) | | 内容保留 | references/markdownflow.md#preservation | references/pedagogy.md#lesson-loop (信息密度) | — | | 输出语言 | — | — | references/data-contracts.md#language-resolution |

创作控制输入

在所有阶段使用以下可选控制：

course_profile (json)：受众和教学参数
delivery_constraints (json)：平台限制、主题政策和不可协商的片段
target_language (BCP-47 字符串，例如 zh-CN / en-US / fr-FR)：明确的输出语言；优先于提示语言检测

字段级别的模式和示例 JSON 请参考 references/data-contracts.md#recommended-object-shapes。

创作泄露规则

请将创作侧的脚手架排除在 Teaching Prompt 和 Course Prompt 输出之外：

避免作者侧的元标签，例如 "知识块 1/2/3"、"课程目标" 或 "交付物"。将这些作为隐式结构，而不是可见的叙述
创作规则、管道说明和流程指令保留在 skill 文档和参考中，不要包含在课程输出中
内部设计说明仅在需要时以 HTML 注释形式出现

Teaching Prompt 和 Course Prompt 创作规则

以下是每个 Teaching Prompt 和 Course Prompt 必须满足的五条红线规则。完整的错误/良好示例和理由在参考文档中；规则陈述保留在这里，以便模型永远不会错过：

脚本风格：指令性，而非手稿。使用命令式、模型引导的语言（"向学习者解释……"、"在收集 {{var}} 之后，分支……"）。不要编写完善的面向学习者的散文或作者/课程计划元叙述。请参考 references/pedagogy.md#script-style。
交互语法：提示在外面，选项在里面。将面向学习者的问题放在交互行之前；仅将选项标签或简短的 ... 输入占位符放在 ?[] 内。每个 ?[] 单独占一行。请参考 references/markdownflow.md#interactions 查看完整的错误/良好示例和 ... 输入标记规则。
强制锚定 + 下游效果。每次交互后，将学习者的选择重述为指令（"将学习者的当前选择重述为 {{var}}。"），并使用 {{var}} 产生可见的下游效果（分支解释、示例、难度、反馈）。请参考 references/pedagogy.md#interaction-design。
视觉内容：图片资源已在编排流程内联处理，不需要单独步骤。

**关键点：**图片提取（extract-images）→ 图片与片段关联（image_resources）→ 课时生成时自动使用真实图片 — 这是编排工作流的前三步，必须在一条连续的工作流中完成，不要拆分成多次对话。

在生成单节课 Teaching Prompt 时：
- 检查本课覆盖的片段是否有 image_resources（每个片段上携带的图片资源列表）
- 如果有 relevance: high 或 relevance: medium 的图片：优先使用真实图片代替"显示一张……的图片"占位符
- 插入语法三选一（按 pedagogy.md 规则）：
  - ===![图x-y：标题](平台URL)===（大多数场景首选）
  - 在此处插入一张图片（以 HTML 方式居中显示）。URL：xxx，图片内容：xxx……（需要精确布局）
  - 在此处并排展示两张图片……（两图对比）
- 图片放在它解释的知识点之后，下方必须紧跟 2-3 句解释文字（引导看图的关键信息）
- 每节课最多插入 3 张图片；多余的图片留给后续课程
- 如果片段上没有图片资源：继续使用自然语言图片占位符（"显示一张……的图片"），不要停止或报错
- 所有图片 URL 必须是平台上传后的 URL（以 /uploads/ 开头的路径或绝对平台 URL）；不要出现本地文件路径或外部图片链接
在任何提示内容之前必须解析输出语言。在生成 Teaching Prompt 或 Course Prompt 内容之前，按照 references/data-contracts.md#language-resolution 运行语言解析。用户的调用语言算作 prompt_language_detection（优先级 4），当没有更高优先级的指令时必须使用。本 skill 和 references/ 中的示例仅以英语编写用于规范说明 — 不要让示例语言覆盖已解析的输出语言。如果用户用中文调用，所有交互、选项标签、下游文本以及 Course Prompt 本身都必须使用中文。

管道概述

这些阶段不是一个平坦的线性管道。编排是一个端到端驱动程序，它内部调用分段和生成。只有优化和部署真正在编排完成后按线性顺序运行。

原始材料
   │
   ▼
编排                          ← 端到端驱动程序
   ├── 调用分段                  (清理 + 语义分段)
   └── 调用生成                  (每节课 Teaching Prompts)
        │
        │ 编排输出：Teaching Prompts + course_index
        │                 + global_variable_table
        ▼
优化                          (审核 + 改进)
        │
        ▼
部署                          (构建 + 导入 + 发布到平台)
        │
        ╰── 可选 ──▶ 分析          (已发布课程的课后数据分析)

分段、生成和优化都可以独立调用 — 请参阅使用路径（路径 B）了解子路径（仅分段 / 仅生成 / 仅优化）。分析是一个独立的发布后路径 — 请参阅使用路径（路径 E）。

使用路径

路径 A：端到端

从原始材料运行完整管道到实时已部署课程。

编排端到端驱动分段和生成，然后运行跨课关卡以生成 Teaching Prompts + course_index + 变量表
优化审核并改进编排的输出，同时生成 Course Prompt
部署写入课程目录、构建、导入并发布到AI大师课平台

路径 B：仅创作

运行从分段到优化的流程以生成优化的 Teaching Prompts 和 Course Prompt，不进行部署。子路径：

仅分段：单独分段用于结构化片段和手动审核
仅生成：在现有片段上单独生成以生成 Teaching Prompts
仅优化：单独优化以审核和改进现有的 Teaching Prompts

路径 C：仅部署

单独运行部署以将现有的 Teaching Prompts 和 Course Prompt 部署到AI大师课平台。

路径 D：管理现有课程

使用部署管理命令（列表、显示、更新、重命名、重新排序、删除、发布、归档）对平台上已有的课程进行操作。

路径 E：课程分析

查询已发布课程的课后数据 — 学习者数量、完成率、卡住课时、订单、收入、评分、积分消耗、受众画像、个人学习者跟踪。

分段

将杂乱的课程源材料转换为可靠的中间结构，供下游课程生成使用。

工作流程

请参考 references/pedagogy.md#segmentation-methodology 了解完整方法论（清理、不可变块标记、语义分段、课时边界建议、源链接）。

重要：分段的输入包括"图片资源表"（编排第一步的输出）。分段时，每个片段除了文本内容，还需要携带关联的图片资源信息。

输出

根据 references/data-contracts.md#segment-schema 的片段列表（每个片段都带有 id、类型、核心点、保留标志、源跨度和转移信号），以及图片资源关联信息，以及带有每个核心问题的课时边界候选。

每个片段（segment）新增字段 image_resources（数组，可空）：

{
  "segment_id": "seg-007",
  "type": "concept",
  "core_point": "梯度下降的三步迭代过程",
  "content": "...",
  "image_resources": [
    {
      "url": "/uploads/cli/xxx/img-page3-fig2.png",
      "caption_hint": "图3-2 梯度下降迭代过程",
      "context_text": "梯度下降算法的核心是沿负梯度方向更新参数……",
      "source_page": 3,
      "relevance": "high"
    }
  ],
  "source_span": {...},
  "transfer_signals": {...}
}

relevance 的取值：high（图片核心内容与本片段核心点高度相关，优先使用）/ medium（辅助配图）/ low（装饰性或与本片段弱相关，可跳过）
没有关联图片的片段，此字段省略或为 []

图片关联规则（分段时用）

按位置对齐：PDF 按 source_page 页码；其他文件按文本上下文近似位置
按语义匹配：图片的 context_text 与片段文本的语义重叠度越高，关联越紧密
每张图片最多关联到一个主片段（最贴合的那一段），避免同一张图在多处重复出现
装饰性图片（纯 Logo、页眉页脚小图标）可以标记为 relevance: low，生成阶段通常会跳过

验证

片段输出按可跟踪顺序覆盖所有有效的源跨度
transfer_signals 对象已填充并可用于下游（模式见 references/data-contracts.md#segment-schema）
image_resources 中的 URL 必须是平台上传后的有效 URL（不是本地路径或外部 URL）
通过保留、单一核心问题和信息密度约束检查 — 请参阅 references/markdownflow.md#preservation 和 references/pedagogy.md#lesson-loop

编排

角色：路径 A 的端到端编排器。编排内部调用分段（segmentation）和生成（generation），然后执行原子阶段无法完成的跨课工作 — 课程索引、全局变量表和强制关卡。

工作流程（含图片处理 — 不要把它当成独立步骤，整个管道是一体完成）

**这是一条连续的工作流，按顺序执行，不要拆分成多次对话：

第一步：预处理 — 从材料中提取图片（在分段之前完成，为后续步骤提供图片资源）

对用户上传的每个文件（PDF / PPT / PPTX / DOC / DOCX / 图片文件）执行：
- python distillation-cli.py extract-images <file> --json
重要行为变化（请仔细阅读）：
1. 该命令永远不会失败退出，即使服务不可达、API key 缺失或网络异常，它都会输出结构化 JSON。
2. 返回的 JSON 分为三类信息：
  - ready_images：已成功上传到平台、可直接用 ===![alt](url)=== 插入的图片
  - offline_images：已从材料中提取但上传失败的图片（附带元数据，可后续补传）
  - server_status：平台服务的可达性检测结果（ok / status / message）
  - hints：针对当前情况的建议（例如"服务不可达，可稍后重试"）

返回 JSON 示例（服务正常时）：

{
  "file": "chapter1.pdf",
  "server_status": {"ok": true, "status": "online", "message": "服务可达（12ms）"},
  "ready_images": [
    {
      "index": 1,
      "url": "/uploads/cli/xxx/img-page3-fig2.png",
      "caption_hint": "图3-2 梯度下降迭代过程",
      "context_text": "梯度下降算法的核心是沿负梯度方向更新参数……",
      "source_page": 3,
      "size_bytes": 184500
    }
  ],
  "offline_images": [],
  "total_extracted": 5,
  "total_ready": 5,
  "total_offline": 0,
  "errors": [],
  "hints": [],
  "note": "成功提取并上传 5 张图片，可直接用于课程内容。"
}

返回 JSON 示例（服务不可达或网络异常时）：

{
  "file": "chapter1.pdf",
  "server_status": {"ok": false, "status": "offline", "message": "服务不可达：Connection refused"},
  "ready_images": [],
  "offline_images": [
    {
      "index": 1,
      "caption_hint": "第3页 图2",
      "context_text": "梯度下降算法的核心是沿负梯度方向更新参数……",
      "source_page": 3,
      "size_bytes": 184500,
      "ext": "png",
      "error": "HTTP connection failed"
    }
  ],
  "total_extracted": 5,
  "total_ready": 0,
  "total_offline": 5,
  "hints": [
    "服务 https://ai-dashi.kcidea.com（或你指定的 base_url）当前不可达。图片已提取但未能上传。你可以：(1) 稍后再调用 extract-images 重新上传；(2) 用 --base-url 指定正确地址；(3) 课程内容先生成纯文本，图片后续补插。"
  ],
  "note": "已提取 5 张图片，但全部未能上传到平台……"
}

你（智能体）的决策逻辑：
- 情况 A： total_ready > 0 → 把 ready_images 中的图片视为可直接在课程内容中使用的资源，按"图片插入规则"插入。忽略 offline_images（它们只是提醒你有部分图片暂时不可用）。
- 情况 B： total_ready == 0 但 total_extracted > 0 → 图片已提取但未能上传。你有两种选择：
  1. 若 server_status.ok == false，可尝试换一个 --base-url 重试；或
  2. 继续生成纯文本课程（使用"显示一张……的图片"占位符），后续再补插图片。 不要因为图片上传失败而停止或中断课程生成流程。
- 情况 C： total_extracted == 0 → 文件中没有图片。继续纯文本生成，使用自然语言图片占位符。
把所有 ready_images 合并到一个临时的"图片资源表"中，按文件和页码排序。

第二步：图片理解 —— 对每张图片进行视觉识别（关键改动：不要跳过这一步）

如果你的模型支持多模态（vision/image understanding）能力，你必须在这一步逐张理解图片。 这一步不是可选的，它是保证后续课程生成质量的基础。

对每张 ready_images 中的图片（即平台 URL 可访问的图片），执行以下流程：

调用多模态能力查看图片内容：你可以直接访问图片 URL（或通过工具下载图片后查看），用图像识别/视觉理解能力描述图中：
- 核心主体：图中主要展示了什么（流程图、架构图、数据图表、截图、示意图……）
- 关键元素：图中有哪些节点/标签/箭头/区块/编号/步骤
- 空间关系：元素之间的布局、方向、层级、流程走向
- 文字内容：如果图片中有文字/代码/标注，尽可能辨认（用于 alt 文本和讲解）
生成结构化描述：对每张图片补全以下字段（没有 vision 能力的模型跳过，用 context_text 替代）：
- vision_summary：一句话概括图片内容（20 字以内，用于 alt 文本）
- vision_description：2-3 句详细描述，说明图片展示了什么、关键要素是什么
- vision_key_points：3-5 个要点，列出图中最值得讲解的信息
- concept_alignment：这张图与周边文字（context_text）描述的概念是如何对应的
补充 relevance 打分：基于图片内容重新判断 relevance（high / medium / low），不再仅凭 context_text 判断
将理解结果写回图片资源表：每张图片的资源对象现在包含了"真实内容"，不再只是位置信息

如果你的模型不支持多模态：跳过图像识别，只用 context_text 和 caption_hint 继续。但要在后续步骤中明确标记"图片描述为推测，非直接识别"。

第三步：分段（基于原始文本 + 已理解的图片资源表

在分段时，如果某个片段附近有图片（根据 source_page 与片段文本上下文匹配），把该图片关联到这个片段上
每个图片关联信息保留在片段 metadata 中（包含 vision_summary / vision_description / vision_key_points），供生成阶段使用
关键：image_resources 的 caption_hint 现在应该用 vision_summary（如果你做了图像识别），不再只是"第 X 页图 Y"

第四步：课时切割（根据分段边界候选，每节课一个核心问题）

第五步：生成 Teaching Prompts（每节课生成时自动使用关联的图片资源

生成课时前，先查看该课时覆盖的所有片段是否关联了哪些图片
有图片时：优先使用真实图片（===![alt](url)=== 或指令风格图片），代替"显示一张……的图片"占位符
图片的 alt 文本使用 vision_summary（如果做了图像识别）；用 vision_description 和 vision_key_points 来撰写图片下方的解释文字
没有图片时：使用自然语言图片占位符
每节课最多使用 3 张图片，选择与本课核心概念最相关的

第六步：构建课程索引和全局变量表

第七步：通过严格关卡仅重新计算失败的课时

强制关卡

在编排声明课程完成之前，所有关卡必须通过：

语法/运行时关卡（违规 → 脚本无法运行）：根据 references/markdownflow.md#preservation 保留代码、图片和必需的源跨度；没有未解析或未收集的变量引用；?[] 在单独的行上；仅对真正固定的内容使用确定性块，见 references/markdownflow.md#deterministic-blocks；每个图片 URL 必须在资源域上 — 固定图片用单行确定性块包装，HTML 视图图片用 (必须原样保留) URL 短语表示为指令风格指令，见 references/markdownflow.md#images。
教学关卡（违规 → 教学质量失败）：每节课一个核心问题、最少教学循环、至少一个深化交互、每节课最多 5 个交互、变量收集节奏、观点分支和视觉-文本配对 — 全部符合 references/pedagogy.md#lesson-loop、#interaction-design、#variable-strategy 和 #visual-text-coordination。

重新计算未通过任何关卡的课时；不要部分通过。

重新运行规则

仅重新计算受影响的课时
当共享变量更改时重新计算依赖关联的课时
仅当全局源顺序更改时重新计算完整课程

失败处理

在回退模式下（请参阅 ## 执行模式），编排：

首先交付粗略的课程草稿；继续尽力而为生成而不是停止
在 course_index 条目中明确标记不确定的跨度
发出 rerun_plan，列出需要重新计算的课时及其原因

回退字段形态见 references/data-contracts.md#fallback-output-extensions。

输出

请参阅 references/data-contracts.md#output-contract 了解 Teaching Prompts、课程索引和全局变量表的模式；保留规则见 references/markdownflow.md#preservation。

验证

所有工件按照 references/data-contracts.md#output-contract 存在
回退输出包括明确的不确定性标记和重新运行提示
上述所有强制关卡都通过

生成（Teaching Prompt — AI大师课课时脚本）

为每节课生成一个可在 AI大师课平台运行的 Teaching Prompt。生成时必须使用本课时覆盖的片段中的 image_resources 图片资源（即平台上传后的真实图片 URL）。

教学模式基线

除非内容需要合理变体，否则应用 references/pedagogy.md#teaching-patterns、#cognitive-techniques、#variable-strategy、#interaction-design 和 #visual-text-coordination 中的模式和约束。

单课生成策略

生成前的图片准备（必需步骤，每次生成课时时都做）：

图片来源（按优先级）：

首选来源：第一步预处理得到的 ready_images（来自 distillation-cli.py extract-images 的返回）——这些是已上传到平台的图片，有完整的 URL。
备用来源：分段时关联到每个片段的 image_resources（如果在预处理阶段之前就完成了分段）。

具体步骤（核心变化：解释文字来自 vision_key_points，不是推测）：

收集可用图片：从首选来源中汇总所有 ready_images；如果没有，从备用来源的 image_resources 中汇总所有 relevance: high 和 relevance: medium 的图片
检查是否有 vision 字段：如果图片资源中没有 vision_summary/vision_description/vision_key_points，但模型支持多模态，在这一步补做图像识别并补全这些字段。不要跳过。
去重 + 排序：同一 URL 的图片只保留一次；按 relevance 降序、source_page 升序排列
上限控制：每节课最多使用 3 张图片；超过的图片标记为"本课时不使用，留给后续课时"
映射到知识点：把每张图片与本课时的一个核心知识点对应（通过 core_point 与 vision_summary / vision_description 的语义匹配 —— 不再用位置信息）
撰写 alt 文本：===![alt](url)=== 中的 alt = vision_summary（如果有）或 caption_hint；不要用"第 3 页图 2"这种位置信息
撰写图片下方的解释文字：用 vision_key_points 作为核心要点，用 vision_description 作为开头概括。不要凭空推测图中有什么。
没有图片时：照常生成，使用自然语言图片占位符（"显示一张……的图片"）；不需要报错或停止
当只有 offline_images 而没有 ready_images 时：由于这些图片未上传到平台，不要尝试直接在课程内容中插入它们的本地路径；继续使用自然语言图片占位符。可选地，在课程末尾添加一句："本课程素材中包含图片，稍后可补插。"

课堂内的图片插入规则：

图片应放在它所解释的知识点之后，紧跟在文本解释的位置
使用形式三选一（按 pedagogy.md 的规则）：
- ===![vision_summary](平台URL)=== （大多数场景首选 —— alt 文本来自视觉识别结果）
- 在此处插入一张图片（以 HTML 方式居中显示）。URL：xxx，图片内容：vision_description…… （需要精确布局时）
- 在此处并排展示两张图片…… （两张图对比时）
每张图片下方必须紧跟 2-3 句解释文字 —— 直接把 vision_key_points 转化为教学语言，不要推测
不要在课程开头把图片批量罗列出来；也不要放在交互题或总结之后
如果没有 vision 字段，在解释文字开头加一行小字："（注：以下图片描述基于上下文推断，建议结合原图理解）"

每节课的必需锚点：

开场目标 + 视觉封面
证据链解释（解释文本 + 相关图片，如有关联图片）
至少一个带有可见下游效果的有效交互
至少一个可重用交付物
课程总结或决策检查点结束

可选模块：观点校准、错误观念纠正、双重交付物（理解 + 行动）、跨课桥接句、额外的视觉-文本强化块。

输出

每节课模式见 references/data-contracts.md#lesson-schema。

验证

每个 teaching_prompt 都是有效的可运行 MarkdownFlow
每节课模式按照 references/data-contracts.md#lesson-schema 填充
教学和语法约束按照 references/pedagogy.md 和 references/markdownflow.md 通过

处理作者提供的图片

当作者提供图片资源 — 本地文件（任何格式包括 heic/heif）或远程 URL — 在生成（以及接触相同课时的任何后续阶段）内应用三个步骤：

1. 在放置之前先理解每张图片。

您无法在不知道图片实际显示内容的情况下决定一张图片属于哪节课，或编写什么替代文本。两种机制：

您可以看到图片（用户在此对话中附加了图片且您的模型是多模态的）：用一句话向自己描述 — 它传达什么概念、关系或示例 — 然后根据 references/pedagogy.md#visual-text-coordination 和 references/course-prompt.md 规则 10/11 选择课时和位置。
您无法看到图片（用户仅给您文件路径/URL，或您的模型是纯文本的）：停止并询问用户。不要从文件名猜测。提供两个选项：(a) 用户为每张图片提供一句话描述（您将作为 --alt 传递），或 (b) 用户将每个文件重命名为有语义的名称，以便您可以推断主题。仅在其中之一到位后继续。

2. 通过AI大师课上传接口上传并捕获 URL。

3. 按照 references/markdownflow.md#images 嵌入到 MarkdownFlow。

默认使用 3.1（确定性包装的标准 markdown）— 图片按原样显示
仅当课程真正需要宽度控制、对齐、图片标题或并排布局时才使用 3.2（指令风格 HTML）。通过措辞表达每个锁定（必须原样保留 / 必须原样输出 / 不要改写）；永远不要将确定性块混合到指令中。

无论哪种方式，图片后紧跟的解释段落都是必需的（请参阅 course-prompt.md 规则 11）。

优化

审核并改进现有的 Teaching Prompts（以及 Course Prompt）。此阶段不用于从头编写。

何时使用

当现有 Teaching Prompts 或 Course Prompt 需要审核和定向改进时使用优化 — 与源的差距分析、不完整重写的质量升级，以及降低运行时失败风险。不适用于从头创作。

高标准约束

针对完整约束集应用优化审核：

教学约束（变量策略、交互设计、视觉-文本协调、课程循环、信息密度）：references/pedagogy.md
语法/运行时约束（保留、确定性块、变量引用）：references/markdownflow.md
完整审核清单（失败模式是这些约束的否定）：references/review-checklist.md

优化工作流程

定义范围（单节课与完整课程）；如果存在多个脚本版本，在编辑前声明权威版本
构建一个覆盖矩阵，映射源点到脚本覆盖
按照 references/review-checklist.md 运行完整审核，使用 references/pedagogy.md#optimization-methodology 中的问题分类法对发现进行分类，并首先应用最小安全编辑

Course Prompt

当输入包括课程材料时，优化还会生成课程级别的 course_prompt 工件。通过逐节填充 references/course-prompt.md#fillable-template 中的模板来生成它，而不是自由形式组合。六个必需部分中的每一个在 references/course-prompt.md#authoring-rules（规则 1–12）中都有一个必须指定的列表 — 每个列出的项目都必须出现在生成的 course_prompt 的相应部分中（使用已解析的输出语言）。不要仅仅因为源材料没有明确要求就省略一个必须指定的项目；这些项目是平台级别的约束。

从现有工件（course_profile、delivery_constraints、根据 references/data-contracts.md#language-resolution 解析的目标语言、分段视觉提示、term_policy）自动填充占位符，而不是重新询问作者。不要在这里重复每课的交互逻辑或变量收集 — 这些属于 Teaching Prompts。

验证

结论和整体风险级别首先显示（报告结构见 references/report-template.md）
针对 references/review-checklist.md 的完整审核通过，或者剩余差距被明确列为非阻塞建议
当输入包括课程材料时生成 course_prompt 工件，所有六个必需部分都存在。# Translation Rules 可以在其触发条件不适用时省略
生成的 course_prompt 覆盖 references/course-prompt.md 规则 1–12 中的每个必须指定项目（对照其规则列表审核每个部分 — 特别是 # Drawing，这是最常填充不足的部分）

部署到 AI大师课平台

将优化后的 Teaching Prompts 作为可运行的交互式课程上传并发布到 AI大师课平台。涉及两个不同的操作，不应混淆：

部署（import） — 通过 build + import 将本地课程文件上传到平台。在此之后，课程存在于平台上，但尚未在公共 URL 上对学员可见。
发布（publish） — 在平台上运行发布，将当前草稿推送到面向学员的公共访问地址 /c/{bid}。

标准的端到端流程：build（本地验证）→ import（部署到平台）→ publish（发布给学员访问）。

部署工作流程

从管道（路径 A 继续）：

将优化输出写入课程目录：lessons/lesson-*.md、README.md、course-prompt.md（优化的 course_prompt 工件，按照 references/course-prompt.md#fillable-template 结构化）以及必需的 structure.json
调用AI大师课 API 构建课程
部署：调用AI大师课 API 导入课程
发布：调用AI大师课 API 发布课程
通过平台 URL 验证

独立部署（路径 C）：

确保课程目录已准备好，包含 Teaching Prompt 文件（每节课一个 MarkdownFlow 文件在 lessons/ 下）、course-prompt.md 和 structure.json。如果 Course Prompt 尚未编写，请在运行构建之前遵循 references/course-prompt.md#fillable-template（以及 references/course-prompt.md#authoring-rules 作为指导）。如果缺少 structure.json，请在运行构建之前创建它
如上运行构建 → 导入（部署）→ 发布

课后数据分析（AI大师课平台）

已发布课程的课后数据查询。调用 AI大师课平台的分析 API，获取以下运营数据：学习者数量、完成率、卡住课时、订单、收入、评分、后续问答量、积分消耗、受众画像分布、个人学习者跟踪。

分析工作流程

解析凭据 — 重用部署身份验证
解析课程 — 运行列表或标题搜索以映射课程 ID ↔ 课程标题
解析大纲（仅用于课程级分析）— 运行显示以映射大纲项目 ID ↔ 名称/位置
运行分析查询 — 调用AI大师课分析 API
在呈现之前翻译 — 通过翻译门传递每个结果

验证

当用户按标题提及时，在运行下游查询之前确认当前的课程 ID → 标题
在任何课程级查询之前建立课程 ID 和大纲映射
在答案显示之前应用翻译门
遵守针对不可访问字段的隐私拒绝

报告模板

在每个阶段结束时使用 references/report-template.md 生成面向用户的报告。每个阶段的锚点：

references/report-template.md#segmentation-report
references/report-template.md#orchestration-report
references/report-template.md#generation-report
references/report-template.md#optimization-report
references/report-template.md#deployment-report

顶级格式规则（URL 需要 markdown 链接等）在 references/report-template.md#formatting-rules 中。

示例

完整的使用路径示例：

examples/pipeline-full.md
examples/segmentation-only.md
examples/generation-only.md
examples/optimization-only.md
examples/fallback-mode.md
examples/end-to-end-deploy.md
examples/deploy-only.md

完整的可运行示例课程见 examples/sample-course/。