fireworks-open-eli5

Fireworks Open ELI5

把复杂系统变成可信的可视化故事。先生成可移植的 JSON 规范，再生成确定性、自包含的 HTML 讲解。

不可逾越的边界

• 证据优先于视觉润色。为每项证据标注 verified、inferred 或 analogy。
• 绝不能让类比看起来像实现事实。
• 生成的本地 HTML 文件仅为 generated，并非已发布、已上传、已发送或已验证目标位置。
• 未经用户明确请求，且未经过目标工作流自身的验证，不得发布、上传、发送或更改访问权限。
• 渲染过程不会发起网络调用。引用的 URL 是面向读者的链接，不是运行时依赖项。可选的原生 Pages 操作只能调用捆绑的同源辅助工具 127.0.0.1；绝不能联系远程服务。
• 浏览器本地历史记录、收藏和注释功能默认禁用，直到读者主动启用。它们只是便利性状态，并非证据，也绝不会修改源规范或生成的产物。
• 准确描述历史记录：它表示此前在该浏览器中打开过的同源讲解。绝不能声称它会列出所有生成的文件。
• PDF 导出会调用浏览器打印对话框。PNG 导出一个场景；PPTX 和 Pages 兼容的 DOCX 则按每张幻灯片或每页导出一个场景。只有在已安装的 Pages 应用确实保存后，才允许生成原生 .pages 文件；绝不能将 DOCX 重命名为 .pages。生成的下载内容仅为本地产物。

工作流

1. 确定受众、问题、语言，以及故事中应贯穿始终的一件事：请求、数据包、决策、事件或用户操作。

2. 仅选择一种故事结构：

   • concept：直觉 → 机制 → 边界。
   • module：入口点 → 转换 → 输出/依赖项。
   • tradeoff：共同目标 → 竞争选项 → 后果/决策规则。
   • incident：正常路径 → 故障及传播 → 检测/恢复。

3. 收集证据。处理仓库内容时，检查实际文件并使用本地路径。对于外部声明，尽可能使用权威来源。明确记录不确定之处。

4. 按照 references/spec-contract.md 创建版本 1 的 JSON 规范。包含 3–7 个场景、每个场景 2–6 个节点、完整的真相阶梯、追踪记录、术语表、复述、证据映射，以及必需的、因模式而异的 modeData。为有重大影响的节点添加故障信息。

5. 渲染前验证：

   node scripts/validate.mjs path/to/spec.json
   

6. 渲染到新的本地文件：

   node scripts/render.mjs path/to/spec.json path/to/explainer.html
   

   渲染器会拒绝已存在的路径。仅当用户明确要求替换已知的常规文件时，才附加 --force。强制渲染会以原子方式替换文件，但仍会拒绝符号链接和非文件路径。

7. 一并验证规范和产物：

   node scripts/validate.mjs path/to/spec.json path/to/explainer.html
   

8. 浏览器可用时，在桌面宽度和 390px 宽度下检查本地产物。确认只有一个 h1、标签易读、没有水平溢出、键盘焦点正常、选项卡列表彼此独立、全局和场景内播放正常、视口跟随正常、活动的真实边及证据卡片同步、动画的进入/保持/退出阶段正常、故障视图正常、答案揭示正常，且远程资源请求数为零。每张场景证据卡都必须显示其状态、简洁的核心依据、支持范围，以及 URL 或明确的无定位信息边界。

9. 测试阅读器工作区：通过鼠标和键盘打开并关闭模态抽屉；确认焦点返回；主动启用资料库；重新加载并验证收藏项和纯文本注释；确认历史记录仅包含实际打开过的同源讲解内容。使用类似标记语言的注释，验证其仍为非活动文本。

10. 测试导出：确认打印样式表、PNG 签名和尺寸、PPTX 与 DOCX 的 ZIP 签名及必需的 OOXML 部件，以及自动下载被阻止时的备用下载链接。通过视觉检查确认场景图稿包含有界的证据页脚，其中显示状态、核心依据和来源定位信息或边界。当原生 Pages 在范围内时，通过 scripts/serve.mjs 操作，验证 .pages 软件包包含 Index/Document.iwa，然后在 Pages 中重新打开。任何更改后都应修复规范或模板，并重新运行两个验证器。

报告语言

• 默认使用用户最近一条实质性请求的语言撰写最终 QA、状态、交接和生成产物报告。
• 用户明确指定的报告语言优先于此默认规则。
• spec.language 仅控制生成的讲解界面，不会强制要求对话报告使用该语言。
• 在多语言对话中，选择报告语言时忽略简短的确认回复。若翻译代码、命令、路径、标识符、确切错误信息和来源标题会降低准确性，则应保留原文。

完整的语言选择和交付报告规范请参阅 references/reporting.md。

故事构建规则

• 标题应作出具体承诺，而不是充当类别标签。
• 摘要限制为一句话，每个节点只承担一项职责。
• 优先采用 3–5 个场景。只有省略某个阶段会扭曲因果关系时，才使用 6–7 个场景。
• 边表示关系或动作。标签使用简短动词。
• 追踪路径必须按有意义的顺序访问真实节点 ID。
• 只有在已知影响、可见症状和回退方案时，才使用故障数据。
• 简化层必须足够准确，能够经受技术层面的检验。
• 将限制写入 truthLadder.caveat，不要藏在细小的免责声明中。
• 在场景或节点上标注支持它们的来源 ID。
• 不要仅仅因为某个来源与论点相邻，就引用它。

阅读 references/story-grammars.md 了解模式的 结构模式，阅读 references/evidence-rules.md 了解 论点边界；在更改渲染器的视觉语言之前，阅读 references/visual-system.md。在更改持久化、导航、播放或 导出行为之前，阅读 references/library-and-export.md。

质量门槛

只有满足以下条件，作品才可作为本地制品交付：

• 验证器对规范和渲染后的 HTML 均返回 ok: true；
• 所有 ID 和引用均可解析；
• 每个必需的交互部分都有内容；
• 所选故事模式符合其自身的语义契约；
• HTML 具有确定性，并包含规范的 SHA-256 元标签；
• 制品与提供的规范逐字节匹配，并使用可信的 CSP 哈希；
• 制品不含外部资源、不安全的运行时 API 或远程字体；
• 持久化的阅读器状态为可选、采用命名空间、范围受限、同源，并排除在确定性规范哈希之外；
• 注释仅作为文本渲染，无法创建可执行标记；
• 全局播放和局部播放共用一个状态机，且不会同时运行；
• 每个追踪步骤都会激活真实的出向关系路径（或终点的入向路径），保持标签与箭头状态一致，并且只突出显示支持该步骤的证据；
• 场景证据卡保留已验证／推断／类比之间的界限，并展示核心文本以及可操作的定位信息，不获取远程预览；
• 场景 PNG、PPTX 和 DOCX 包具有预期的签名与结构，并包含证据页脚；如果声称支持原生 Pages 导出，还必须已在 Pages 中重新打开验证；
• 移动端使用堆叠式流程，而不是缩小桌面 SVG；
• 最终报告遵循用户当前的交互语言，列出生成的规范和 HTML 路径，并说明是否进行了桌面端、移动端、持久化、播放、证据和导出功能的浏览器 QA。

如果证据不完整，只有在证据图谱和注意事项明确指出缺口时才生成。否则应停止并报告缺失的证据。