node-learning

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 静态页仍只在用户要求时产出。

图片三来源（按此优先级决策，搜图 ≠ 生图 ≠ 引用）

1. 引用已有图（≈0 成本）：会话文件（list_session_files / read_session_file 解析 file_id）→ 用 image_frame 展示或正文直接引用；资料、文档、之前生成过的图优先复用。禁止凭记忆文字转述旧图。
2. 搜图（低成本）：search_images（文搜图 / 图搜图）→ 需要落盘时 download_external_image 经宿主网关下载。适合真实照片、人物、实物、场景。
3. 生图（高成本，慎用）：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 仅当明确需要且成本可接受。
• 透明汇报：首次学习用一句话说明投入了哪些维度与理由（如"这次用文字骨架 + 结构图 + 动画演示 + 一题自测"）；追问阶段说明收缩了哪些，让用户感知成本可控。

教学编排流程（每个节点必走）

1. 读上下文：从本轮 UI 选区拿选中节点（label / node_id）；lg_graph_read（graph_id + query）读节点描述与前置关系；lg_learning_mastery_read 读掌握度——新节点 / 低掌握度 → 完整教学；已掌握 → 快速巩固 + 拔高，不重复讲。
2. 定维度组合：首次学习按"编排规则"用足 3～4 档（主干 + 视觉 + 交互/动画 + 自测）；追问阶段按需收缩。
3. 讲解：图文并茂优先——文字 + L1 自绘 SVG 图（结构/流程/概念关系）/ 图表 / 一段动画；引用资料必须带来源（file_id 或 URL）。
4. 自测（交互练习）：首次学习尽量配 1～3 题 channel A 组件（correct_option_ids / option.is_correct + explanation，前端可判分；多题连发会被前端堆叠成一套分页练习）；用户答对后用 lg_learning_evidence_record（source_type="exercise"）记录真实表现，不替用户编造掌握度。
5. 收尾：一句话总结 + 下一步建议（补前置节点 / 做练习 / 安排复习）；用户要求时产出静态学习页并 sandbox_publish_file。

详细编排手册

• 场景模板（概念 / 机制流程 / 对比分类 / 数值规律 / 动手实操 / 已掌握巩固）：references/orchestration.md
• 交互组件选型、动画与 SVG 速成、图片决策矩阵、成本预算明细、提交前自检清单：同上。

需要更细的维度选型、模板或写法时，先用 lg_skill_read 展开 references/orchestration.md 再执行，不要凭本页速查表猜测完整细节。