Fireworks Open ELI5

这是什么？适合谁？

Fireworks Open ELI5（yizhiyanhua-ai/fireworks-open-eli5）是一个开放、可移植的 Agent Skill，把难懂的系统变成真实、可交互的视觉故事。它把一个版本化的 JSON story spec 编译成一个确定性的、自包含的 HTML 文件，离线可用。

它的差异化：

• Truth Ladder（真值阶梯）：把类比、技术机制、注意事项分层呈现
• 证据在断言处：每个场景都能显示来源状态、核心文本、支撑范围，以及 URL 或明确的无定位符边界
• 四种故事语法：概念、仓库模块、工程权衡、事故，各有专属摘要视图和语义校验器
• 失败透镜 + 反问教学：影响、症状、回退、问题、答案揭示都是讲解的一部分，而非附录

核心价值：把「ELI5 层」和「可检查的技术真相」结合——读者能沿着系统追踪一个真实请求或事件、检查每个结论背后的证据、探索失败行为、批注场景、导出结果，而源材料从不发给远程运行时。

适合人群：需要给新人讲清复杂系统的工程师；要做架构讲解/事故复盘的人；想生成带证据链的可视化文档的 Agent 用户。

准备工作

1. Skill 运行时：Node.js 18+；本地文件访问。
2. 依赖：零 npm install、零 Python 运行时、零远程字体、零远程渲染。
3. 安装：安装器（skills@1.5.23 CLI）需 Node 22.20+；已装 Skill 仍跑 Node 18+。
4. 成本：Apache-2.0 开源，免费。
5. 渲染：交互 HTML 和本地 PDF/PNG/PPTX/DOCX 导出用现代浏览器。

快速上手（3 步）

第一步：安装

# 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

-g 装到用户级；去掉则项目级。装完 npx skills@latest list -g --json 检查，再开新 Agent 任务。

第二步：验证渲染管线

node scripts/validate.mjs assets/example-spec.json
node scripts/render.mjs assets/example-spec.json example.html

命令打印紧凑 JSON，失败非零退出。

第三步：让 Agent 生成讲解

Explain how one queued job moves through this repository. Cite real files, let me play the request path, and show what breaks when the lease expires.

成功判定：得到带证据链的离线 HTML，能播放请求路径、看到失败行为、批注并导出。

初级用法

故事管线

问题 + 受众 + 证据
   ↓
版本化 JSON story spec
   ↓ 校验
确定性 HTML 渲染器
   ↓
离线交互讲解 + PDF / 场景 PNG / 全场景 PPTX / DOCX / 可选原生 Pages

JSON spec 是可移植的事实源；HTML 内含其 canonical SHA-256，校验器可逐字节对比。

读者工作区

每个讲解有目录抽屉：收藏、当前大纲、已开讲解、批注浏览。启用「Enable local library」才记录，只记同源已开讲解，不扫描文件系统。

高级玩法

导出矩阵

安全与隐私

渲染器读本地文件、写一个本地文件。HTML 用 hash 白名单 CSP，无远程资源、无 XHR/WebSocket/eval。唯一连接是用户主动的 loopback Pages helper 同源请求。

小技巧

1. 先 validate 后 render：validate.mjs 拒绝不安全来源 URL、外部资源、spec-hash 漂移。
2. 四种语法选对：概念/模块/权衡/事故各有专属摘要视图，别用错模板。
3. 失败透镜是卖点：把失败行为讲进正文而非附录，读者理解更深。
4. --force 慎用：渲染默认 create-only，只有刻意替换已知常规文件才用。
5. 全量检查一条命令：npm run check 跑语法+测试+canonical 示例+发布包内容+渲染/校验 canary。

常见踩坑

踩坑 1：装了但 Agent 没发现

• 现象：装完 Skill，Agent 不用它。
• 原因：Skill 需新任务才会被重新发现。
• 解决：npx skills@latest list -g --json 确认后，开新 Agent 任务。

踩坑 2：覆盖已有安装

• 现象：重复安装覆盖了本地修改。
• 原因：没让 Agent 先审查 SKILL.md。
• 解决：按 README 的 natural language 安装指令，明确「不覆盖已有副本」。

踩坑 3：渲染覆盖了已知文件

• 现象：渲染意外覆盖了已有 HTML。
• 原因：没理解 create-only 语义。
• 解决：默认 create-only；--force 只在刻意替换时用，symlink 永远拒绝。

踩坑 4：Node 版本不匹配

• 现象：安装报错。
• 原因：安装器 CLI 需 Node 22.20+，但已装 Skill 跑 18+ 即可。
• 解决：区分「安装器要求」和「运行时要求」；Node 不够时别擅自升级系统 Node。

踩坑 5：期望实时在线渲染

• 现象：想实时协作。
• 原因：这是确定性离线渲染，不是在线编辑器。
• 解决：交付物是自包含 HTML，离线可分享、可导出。

常见问题 FAQ

Q1: 和 Anthropic 的 eli5 skill 什么关系？

A: Fireworks Open ELI5 是受 Anthropic 社区 eli5 skill 启发的独立实现，不受 Anthropic 认可，但加入了证据链、Truth Ladder、失败透镜等差异化。

Q2: 需要网络吗？

A: 渲染阶段完全不需要（无远程资源/字体/服务）；安装需一次性访问 GitHub 和 npm registry。

Q3: 源材料会上传吗？

A: 不会。渲染器读本地文件、写一个本地文件；HTML 无 XHR/WebSocket/eval；唯一网络是用户主动的 loopback Pages helper。

Q4: 导出格式有哪些？

A: PDF、场景 PNG、全场景 PPTX、Pages 兼容 DOCX，以及可选的原生 .pages（macOS + Apple Pages）。

Q5: 适合团队协作吗？

A: 适合「交付讲解物」。自包含 HTML 离线可分享；批注是浏览器本地、不修改源文件；正式协作需自己配托管。

进阶学习建议

掌握基础后，建议深入：

1. 事故复盘语法：用「incident」语法把真实事故做成带失败透镜和证据链的讲解，沉淀为团队知识库。
2. 工程权衡讲解：用「tradeoff」语法把技术决策讲清，让评审者沿着证据链验证每个结论。
3. 证据链审计：把「每个结论可追溯到来源 URL 或明确边界」作为文档质量标准，推广到全团队的讲解产出。

参考链接

• 官方仓库
• Agent Skills CLI

最后更新：2026-08-27 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成