sunnyboy-y/learngraph/graph-cover

图谱封面生成

适用场景

Goal 工作流中的图谱提案审核确认后，以及图谱标题、节点结构或掌握进度变化后，需要在图谱书架显示定制封面时使用。绘制由后端自动执行；模型或用户明确要求替换封面时，可使用封面读取/更新工具，本 Skill 说明编排和输出约定。

流程

1. 图谱提案审核确认并写入后，后端读取该图谱标题、全部节点标签和学习进度（掌握星级 ≥ 3 的节点占比）；提案待审核时不生成正式封面。不要把对话中的任意指令当作封面 SVG 代码执行。
2. 以标题生成稳定的主题色，以节点数量和顺序生成结构化点线图。
3. 对标题做 XML 文本转义、移除 XML 不支持的字符，并限制文本长度、节点数量和进度范围。
4. 输出 data:image/svg+xml, 开头的 SVG data URL。
5. 确认结果通过 result.cover_svg 返回封面；图谱列表和详情接口根据当前数据重新生成并返回 cover_svg，由书架卡片直接嵌入，不创建临时文件。工具调用仍只提交图谱 schema 允许的字段，不手写 SVG 参数。
6. 生成抛错、输出为空或 SVG 解析失败时，后端返回独立生成的默认封面；前端使用默认封面作为背景底层，覆盖图片加载失败的情形。失败不改变图谱确认结果，不阻断路线/日程，不重复提交图谱或要求用户处理。

注意工具返回值里的 used_default：为 true 表示这次落库的是降级默认封面（不是定制封面）。如实说明，不要把它描述成"已生成定制封面"。

模型与用户的封面替换

• 模型需要图谱结构或掌握进度时，先调用 lg_graph_read；需要查看当前封面、可用模板和 AI 状态时调用 lg_graph_cover_read。
• 用户明确要求替换封面时调用 lg_graph_cover_update，mode 可选 generated、template、image、svg（均不调用模型），以及 AI 的 ai_draft、ai（见下节）。模板使用 ancient、literature、history、science、chemistry（以及兼容保留的 paper、midnight、sunrise）；图片必须是有效的 PNG/JPEG/WebP/GIF data URL；SVG 只能包含安全的静态元素和本地片段引用。
• lg_graph_cover_update 只修改封面字段，不改变图谱 revision、Goal 状态、节点掌握度或审核结果。模型不得在用户未提出封面意图时自行覆盖已有封面。
• 书架编辑器提供同样的模板选择、图片上传和「按图谱绘制」入口；上传图片由服务端解码、裁剪、重新编码后保存，原始文件名和 MIME 声明不作为信任依据。

AI 生成（两阶段、两引擎）

只有用户明确要求"AI 生成封面 / 让 AI 画一张封面"时才用，且它会花钱。 绝不能因为"觉得封面不好看"自行触发。

1. 先拟草案（便宜，只调用文本模型，不出图）：mode="ai_draft"，可带 engine 与 hint。返回的 prompt 是一段可编辑的封面描述，prompt_source 为 model（模型代写）或 fallback（模型不可用时的拼接草案）。
2. 把草案原样交给用户，等用户确认或改写。prompt_source="fallback" 时说明这段描述是系统拼接的、可以随便改。
3. 确认后再出图：mode="ai"，带上最终 prompt 与 engine。

• engine="svg"：文本模型直接画矢量封面，不产生图片模型费用；产物必须通过静态 SVG 安全校验（禁脚本、外链、<image>、style 属性，元素与体积有上限），不合规会回灌错误重试一次，仍不合规则整个任务失败（不会悄悄退回算法封面）。
• engine="image"：调用工作区图片 Provider 生成位图，再由服务端裁剪归一化成 640×300 的 JPEG。

1. 提交是异步的：mode="ai" 立刻返回 status="queued" 与 cover_job_id，生成在后台完成（数十秒）。不要重复提交，也不要在同一轮对话里连点；需要进度就用 lg_graph_cover_read 看 ai.generating。
2. 失败要如实说：lg_graph_cover_read 的 ai.last_status="failed" 时，ai.last_error 是可读原因（未配置图片模型、预算不足、上游限流、SVG 未通过安全校验等）。原样转述并给出下一步（去 Provider 管理启用、稍后重试），不要假装成功，也不要默默重试（每次重试都会再花钱）。
3. 取消由用户在编辑器里点击；模型侧不提供取消语义。

输出约束

• SVG 画布固定为 640 × 300，适合书架横向封面。
• 算法封面（generated）必须是确定性的：相同标题、节点结构和进度得到相同封面。不额外调用模型或网络。
• AI 封面是装饰，不是教学内容：可能出现糊图或错字，不要用它承载知识点，也不要把它当作事实依据。
• 封面只表达图谱主题和结构，不复制节点正文或用户隐私内容。
• 生成失败时使用标题主题色的通用 SVG 作为降级封面，并如实报告（见 used_default）。