Fireworks Open ELI5

Fireworks Open ELI5 是一个开放、可移植的 Agent Skill，将晦涩难懂的技术系统、代码库或事故复盘转化为真实、可追溯且可交互的视觉故事。它不依赖复杂的远程服务，而是通过生成版本化的 JSON 故事规格，编译成单个、确定性、自包含且可离线运行的 HTML 文件。

它的核心理念是平衡“小白能懂”的直观性与“技术上经得住追问”的严谨性：读者可以跟随一次真实请求走完整条链路，查看每个结论的依据，切换故障视角，并在不上传源材料的情况下完成多种格式导出。

核心特色

• 事实阶梯 (Fact Ladder)：
  • 明确区分类比（帮助理解）、技术机制（底层原理）与限制条件（边界情况）。
  • 结论旁边直接展示证据状态、核心文本片段、支持范围及来源链接，杜绝“幻觉”。
• 四种故事语法：
  • 针对概念解释、仓库模块分析、工程取舍讨论及事故复盘提供独立的摘要视图和语义校验逻辑。
• 细致播放与交互：
  • 支持全局或局部播放真实节点、连线、标签和证据卡。
  • 自动保持当前场景在视口内，包含进入、停留、离开阶段的平滑过渡。
• 故障透镜与反向检查：
  • 将影响分析、外部症状、降级方案及“Teach-back”问题融入正文，而非作为附录。
  • 支持从故障现象反推根因的交互式探索。
• 读者工作台：
  • 支持同源历史记录、场景收藏、纯文本批注及键盘可访问的目录导航。
  • 所有数据仅保存在浏览器本地，清除数据即销毁，绝不改写源文件。
• 天然可移植与零依赖：
  • 渲染阶段不依赖 npm 包、远程字体或网络请求。
  • 生成的 HTML 携带规范化 SHA-256，校验器可进行字节级一致性检查。

快速开始

1. 安装 (作为 Agent Skill)

推荐使用 npx 进行全局安装，支持 Codex 和 Claude Code：

# 安装到 Codex
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a codex -y

# 安装到 Claude Code
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a claude-code -y

# 同时安装到两者
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a codex -a claude-code -y

2. 本地渲染测试

如果你希望手动验证渲染流程：

# 验证 JSON 规格
node scripts/validate.mjs assets/example-spec.json

# 渲染为 HTML
node scripts/render.mjs assets/example-spec.json example.html

# 再次验证生成的 HTML 与规格的一致性
node scripts/validate.mjs assets/example-spec.json example.html

3. 作为 Agent Skill 使用

安装完成后，你可以向 Agent 提出如下请求：

“解释一个排队任务如何经过这个仓库。引用真实文件，让我播放请求路径，并显示租约过期时哪里会出问题。”

Agent 将根据 SKILL.md 中的工作流，生成对应的 JSON 规格并渲染出可交互的 HTML 故事。

导出与分享

生成的解释器支持多种本地导出格式，无需第三方库：

安全与隐私

• 离线优先：生成的 HTML 使用哈希白名单 CSP，不包含远程资源、XHR、WebSocket 或 eval。
• 本地处理：渲染器仅读写本地文件，唯一的网络连接是用户主动触发的、指向可选 Pages 助手的本地回环请求。
• 隐私保护：批注和收藏仅存储在浏览器本地内存或 LocalStorage 中，不会上传至任何服务器。

适用场景

• 技术文档编写：为复杂的微服务架构或数据流转生成可视化的入门指南。
• 事故复盘 (Post-mortem)：交互式地重现故障发生的时间线、影响范围及修复过程。
• 代码库导览：帮助新入职工程师通过真实请求路径理解模块间的依赖关系。
• 工程决策记录：清晰展示不同技术方案之间的权衡取舍及其依据。

Fireworks Open ELI5 让知识传递不再依赖于静态的文字堆砌，而是通过可交互、可验证的视觉叙事，让每一个技术细节都变得透明且可信。