light-diagram

项目目录与续作

需要落盘或继续已有项目时，先读 项目目录约定，按其中的本阶段位置、版本与关联规则保存；用户指定路径和旧项目优先。包内资源相对本 skill，研究产物相对真实项目，二者不要混用。只做局部讨论时无需初始化目录。

这是总入口，负责阶段衔接、工具选择和结果验收。四个子 skill 保持独立职责；总入口按需要读取它们的 SKILL.md，不要求用户逐个调用。默认目标是科学关系正确、可继续编辑的科研示意图，不承诺 1:1 完美复现。定量数据图使用相应数据绘图流程；混合图中的真实数据面板保留作者素材。

所有相对路径以本包目录为基准。参考仓库和大图库是可选学习资料，不是执行依赖。

继续项目、修稿或响应评审时，按需读 项目证据与修订衔接：先看有关 Memory，再回原论文、设计、分析及采用的稿图版本核对。记忆用于恢复上下文，图像生成结果用于视觉参考；两者均不替代科学原件。局部请求直接完成，不强制创建完整交接。

先判断从哪里开始

用户已提供清晰参考时不强制重新生图。只有风格参考、没有待画的科学内容时，不能把参考论文的机制直接借给新图。仅有摘要时可以做有边界的概念图，不能补出未读方法细节。

工作流程

1. 建立共同 brief

读取相关论文内容、方法、图注或用户说明；明确领域、核心图意、必须实体、重要关系与方向、精确标签、画布、真实证据素材和未知项。记录读到的范围，示意构型与实验事实分开。复杂图给重复组件稳定 ID，并列出关键边、物理层位和局部放大来源。

沿用用户已明确的工具、输出格式和可见绘制偏好。本项目用户希望看见制作，桌面应用可用时默认可见创建；其他使用者仅在请求可见制作时启用相应节奏。先发现可用工具和应用，不能等选定路线后才发现无法运行。

2. 新图先生成视觉参考

需要新图时读取 light-diagram-prompt，先产出科学 brief、结构蓝图、完整生图提示词及检查点。每次生图或编辑前，先在用户可见回复中输出完整提示词，或提供实际提示词文件的可点击链接；无需等待确认，再继续调用。 工具内部日志和仅写入磁盘不能替代这次交付。只执行所交付的版本，修订后也先交付再执行。

根据预期编辑工具，把可重建性提前反馈给提示词：复杂纹理可限定为局部素材，文字与关键关系留出清楚空间；不要为了软件方便删掉科学信息。执行前保存完整提示词，执行后记录实际生成图路径和哈希。新生成、编辑、复用及“仅修订未执行”分别记录，未知模型版本/seed 留空。

统一按 生图能力与自定义配置 路由，单独调用 prompt 子 skill 时也采用同一规则：

1. 用户明确只要提示词时，到提示词交付结束。
2. 否则先发现宿主实际可调用的生图工具；可用就直接调用，遵守宿主工具与生图 skill 的要求，不要求 API Key。
3. 宿主没有生图能力时，使用用户配置的 URL、Key、模型等调用生图服务。用户明确指定自定义服务时遵从该选择。
4. 两者都没有，或配置不完整时，交付提示词即可；说明未生图的实际原因，不要求用户为完成提示词交付而配置服务。

宿主能力未知时先发现，不以“不知道”等同于“不支持”。调用出错保留提示词和失败记录；遵循宿主已有授权的 fallback 路线，技术失败可按其约定切换，安全拒绝不换供应商绕过，不无界重试。已有 imagegen-fallback 时复用它的工具和配置，不要求用户再配一套 Key。可移植自定义接口助手见 light-diagram-prompt/scripts/image_service.py；它不能调用宿主内部工具，也不负责图像质量判断。

用户请求制作新图时，生图属于已授权制作步骤，无需每个阶段再次确认。提示词子 skill 直接调用时可到图片交付结束；由总入口调用时继续下列核查和后端流程。提示词降级交付时保留原始目标为 requested_output_mode，本次 output_mode 为 prompt_only，不把它说成已经交付图片或可编辑文件。

3. 核查参考并形成交接

实际查看生成图或用户参考，按科学实体/关系 → 文字 → 结构可读性 → 视觉细节核查。科学错误先定位到具体边、对象或放大层位。

小范围问题可明确留到原生重建修正，保留原图、修改清单与“科学关系修正版”标记；根本结构错误应先修订完整提示词并局部编辑或重生成。重生成后重查整张关键关系，避免只看刚改的区域。不要把错误参考当作科学依据，也不为追求像素重合恢复已知错误。

需要跨阶段交接或留档时，在案例目录保存共同 handoff.json，将 brief、科学原件与定位、关系说明、实际执行提示词、选定参考、错误/修正、工具选择和检查证据交给下一阶段。新记录用 1.1，将检查绑定具体文件版本；旧 1.0 只读兼容，不补写未发生的检查。后端场景格式仍各自保留，不将三种软件强制套成一种坐标/连接模型。

4. 选择一个主要编辑工具

用户指定工具/格式优先；否则结合参考内容、后续编辑方式与当前可用能力选择。工具选择可在生图前预判，在查看参考后最终确定。说明选择原因即可，不引入例行审批。

图型不是硬编码：Visio 能画自由曲线，PowerPoint 能画复杂机制；Illustrator 的路径没有 Visio/PPT 式原生节点吸附。优先满足用户的后续操作，不能只凭“哪个更像绘图软件”选择。

一般只执行一个主要后端；仅在用户需要多格式比较或确需组合素材时调用多个。局部生图素材可用于任一后端，但需记录范围和编辑边界，不能整图嵌入后声称重建完成。指定应用不可用时继续可独立完成的准备，说明缺口；不静默换工具或安装软件。

5. 原生重建、复查与交付

读取选定子 skill 后才执行它的专用路线，包括宿主工具要求、场景验证、可见创建、保存重开、原生文字与关系/组移动检查。共同交接中的参考、标签、关键关系和修正清单是输入；图形脚本不是自动识图器。

检查分开记：文件结构、真实应用行为、视觉效果、科学关系。查看实际应用导出的最终预览，不能用一个 passed 推定全部通过。失败时返回对应阶段修复；不因绘图工具的限制改坏源机制，不把几何近似说成逐像素还原。

交付目标原生文件、最终预览、必要导出、来源与改动说明，保持用户要求的可见最终文档。记录哈希和每项检查依据；文件换版后，旧审计不能沿用。只做 prompt 或图片的请求无需制造后端交付文件。

使用与验证边界

直接请求示例：“用 $light-diagram 根据这篇论文做方法图，选择合适工具，给我可编辑版本，我要看到制作过程。”用户可指定任一阶段或子工具，不必先回答一套字段。

本包由当前助手按这些指令串联，并非已经存在一个命令即可无人值守识图、生图和重建的程序。scripts/validate_handoff.py 只核对交接状态、文件、哈希和证据引用，不会调用生图或绘图软件，也不能证明科学或视觉正确。

既有后端已有真实应用案例；总入口新增的交接与一致性验证见 集成记录。该记录将旧案例接入新交接格式，没有重新生图或重画，不能称为新总入口已完成全新端到端生图实测。

提示词先交付、宿主/自定义服务选择与无服务降级的验证见 生图路由记录。本轮使用本地模拟接口验证协议，不代表真实第三方生图服务或图片效果已经实测。

另有 用户自定义服务真实接入测试：实际返回一张简单双分支方法图，记录地址补齐、请求标识兼容性及目视核查；不是复杂科研图或新总入口全流程的通过率评估。