| name | node-learning |
| description | 图谱节点学习专用编排。用户选中学习节点、要求"学习/讲解/教教我/图解/生成练习"某个知识点时，按成本阶梯组合图文（引用图/搜图/生图）、图表、选项题、双向交互与动画教学等多维形式讲解，控制成本与效果的平衡；到期复习走 review-coach，图谱结构变更走 graph-generation。 |
节点学习编排（成本感知的多维教学）
何时使用
- 用户在图谱中选中学习节点并发起"学习 / 讲解 / 教教我 / 展开讲讲 / 图解 / 做个练习"等请求。
- 本轮上下文已绑定选中学习节点（selected learning nodes），需要把复杂知识点讲得更容易懂。
- 前端"生成一道可验证的练习"快捷入口也走本 Skill 的"讲解→自测→记录"流程。
边界：到期复习 / 考前查薄弱点 → review-coach；图谱拆分细化 / 增删节点 → graph-generation；目标澄清与路线日程 → goal-learning-route / roadmap-planning。本 Skill 只负责"把已选节点的知识讲清楚、讲得容易懂"，不越界改图谱结构。
核心原则：首次学习全力投入，追问后按需收缩
教学强度分两段：首次学习新概念时默认浑身解数——用足多维形式（视觉 + 交互/动画 + 自测）一次讲透；用户追问或表示已懂后按需收缩，降档到刚好够用。下表只是"用什么"的选型目录，强度由"首次全力、追问收缩"决定；升维度的唯一目的是"让复杂知识更容易懂"，不是炫技。首次学习的视觉维度一律优先 L1 自绘 SVG，并尽量配交互练习（L3/L4）。
| 档位 | 形式 | 成本 | 何时用它 |
|---|
| L0 | 文本 + Markdown 表格 / 列表 / 代码块 / ASCII 图 | 极低 | 默认起点；简单定义、列举、步骤 |
| L1 | 自绘 SVG / 静态 HTML 图（magic_card 静态） | 低 | 结构图、流程图、概念关系（首次学习视觉首选；比生图/搜图便宜且更准确） |
| L2 | create_chart 图表 | 低 | 数值对比、趋势、占比（真实数据必须带 sources） |
| L3 | canvas 组件：单选 / 多选 / 填空 / 简答（带判分） | 低 | 自测、交互练习、即时反馈（首次学习尽量配） |
| L4 | magic_card 双向交互（翻卡 / 步进 / 拖拽 / 模拟） | 中 | 过程性知识、需要动手探索、逐步推导 |
| L5 | 动画教学（magic_card 内 CSS / SVG 动画） | 中 | 流程、机制、时序、算法步骤——动起来才看得懂 |
| L6 | 图片：引用 → 搜图 → 生图 | 中-高 | 真实照片、实物场景、抽象概念配图（见下节） |
| L7 | 静态学习页（sandbox HTML → sandbox_publish_file） | 中-高 | 用户要求"整理成一页纸 / 学习卡片 / 保存下来" |
编排规则：
- 首次学习：默认浑身解数——L0 主干 + L1 自绘 SVG 图（视觉首选；仅真实照片/实物才用 L6，数值对比才用 L2） + 至少 1 个交互/动画维度（L4/L5）+ L3 交互练习（尽量配，1～3 题判分组件），用足 3～4 档一次讲透；内容量大时先给骨架再逐块展开，但每块保持多维度。
- 追问 / 表示已懂 / 要求简要：按需收缩，降档到刚好够用（通常 L0 或 L0+L1，直接回答追问点），不重复全量教学；需要演示、配图或自测时再临时升档。
- L4/L5/L6 同一节点首次学习各 ≤1 个实例；L7 静态页仍只在用户要求时产出。
图片三来源（按此优先级决策，搜图 ≠ 生图 ≠ 引用）
- 引用已有图（≈0 成本）：会话文件（
list_session_files / read_session_file 解析 file_id）→ 用 image_frame 展示或正文直接引用；资料、文档、之前生成过的图优先复用。禁止凭记忆文字转述旧图。
- 搜图（低成本）：
search_images（文搜图 / 图搜图）→ 需要落盘时 download_external_image 经宿主网关下载。适合真实照片、人物、实物、场景。
- 生图（高成本，慎用）：
generate_image。仅当①②都不可行且视觉收益明显（抽象概念、无现成图的示意、用户明确要配图）时才用；尺寸 16:9→2048x1152，不确定→auto。
概念图 / 结构图 / 流程图一律优先用 L1 自绘 SVG/HTML（零图片成本、改字方便、不会画错）——首次学习的视觉维度首选，不要让生图/搜图代劳。
配图力度：首次学习默认至少配 1 张图（按 ①②③ 优先级选来源，概念/结构类仍优先 L1 SVG 自绘）；追问阶段不主动加图，用户要才加。
成本护栏（硬性约束）
- 生图：首次学习可主动配图但守住上限（每节点 ≤1 张、同一会话 ≤2 张）；追问/收尾阶段不生图；每次生成前先过一遍"引用→搜图→SVG"。
- 联网：联网未开启则不检索；开启后仅当需要事实 / 数据 / 最新信息时
search_web，每个节点 ≤1～2 次；检索结果必须带 URL 才能作为事实引用，否则明说"未检索到权威来源"。
- 交互：不把整篇讲解做成交互。每节点自测 1～3 题（channel A 组件）足够；交互页面只给"过程 / 推导 / 探索"型知识；普通表单、选择题一律 channel A，不写 HTML。
- magic_card：自包含 HTML ≤100k 字符，禁 CDN / 远程脚本 / 图片 / 字体 / fetch / WebSocket；别拿它替代表单。
- 静态页：默认不产；用户要求"保存 / 整理成页面"时才产出单文件 HTML 并
sandbox_publish_file；多文件 web app 仅当明确需要且成本可接受。
- 透明汇报：首次学习用一句话说明投入了哪些维度与理由（如"这次用文字骨架 + 结构图 + 动画演示 + 一题自测"）；追问阶段说明收缩了哪些，让用户感知成本可控。
教学编排流程（每个节点必走）
- 读上下文：从本轮 UI 选区拿选中节点（label / node_id）；
lg_graph_read（graph_id + query）读节点描述与前置关系；lg_learning_mastery_read 读掌握度——新节点 / 低掌握度 → 完整教学；已掌握 → 快速巩固 + 拔高，不重复讲。
- 定维度组合：首次学习按"编排规则"用足 3～4 档（主干 + 视觉 + 交互/动画 + 自测）；追问阶段按需收缩。
- 讲解：图文并茂优先——文字 + L1 自绘 SVG 图（结构/流程/概念关系）/ 图表 / 一段动画；引用资料必须带来源（file_id 或 URL）。
- 自测（交互练习）：首次学习尽量配 1～3 题 channel A 组件（
correct_option_ids / option.is_correct + explanation，前端可判分；多题连发会被前端堆叠成一套分页练习）；用户答对后用 lg_learning_evidence_record（source_type="exercise"）记录真实表现，不替用户编造掌握度。
- 收尾：一句话总结 + 下一步建议（补前置节点 / 做练习 / 安排复习）；用户要求时产出静态学习页并
sandbox_publish_file。
详细编排手册
- 场景模板（概念 / 机制流程 / 对比分类 / 数值规律 / 动手实操 / 已掌握巩固）：
references/orchestration.md
- 交互组件选型、动画与 SVG 速成、图片决策矩阵、成本预算明细、提交前自检清单：同上。
需要更细的维度选型、模板或写法时，先用 lg_skill_read 展开 references/orchestration.md 再执行，不要凭本页速查表猜测完整细节。
