ESC
开源 3 分钟阅读

Fireworks Open ELI5：面向 Codex 与 Claude Code 的循证交互式可视化解释器

Fireworks Open ELI5 是一个开源、可移植的 Agent Skill，可将复杂系统转化为真实、可交互的视觉故事。它把版本化的 JSON 故事规范编译为确定性的独立 HTML 文件，支持离线查看、证据溯源、失败行为探索、场景批注与本地导出（PDF/PNG/PPTX/DOCX/Pages）。无需 npm 安装、远程字体或网络连接，兼容 Node.js 18+，并面向 Codex 与 C

来源：GitHub

Fireworks Open ELI5 owl

Fireworks Open ELI5

English · 简体中文

一个开放、可移植的 Agent Skill，用于将复杂系统转化为真实、可交互的视觉故事。它可将版本化的 JSON 故事规范编译为一个确定性的、自包含的 HTML 文件，支持离线使用。

该项目结合了 ELI5 层与可检查的技术事实：读者可以跟踪系统中真实请求或事件的流转，检查每个结论背后的证据，探索失败行为，为场景添加注释，并将结果导出，而无需将源材料发送到远程运行时。

Agent 架构解释器，含源支持的场景

一个生成的中文场景，同时展示图谱、本地操作和结论级证据。

独特之处

  • 事实阶梯（Truth Ladder） — 将类比、技术机制和注意事项分开。
  • 结论级证据（Evidence at the claim） — 每个场景可展示来源状态、核心文本、支持范围，以及 URL 或明确的“无定位器”边界。
  • 四种故事语法 — 概念、仓库模块、工程权衡和事件，每种都有专属的摘要视图和语义验证器。
  • 细粒度回放 — 全局或场景级轨迹可动画展示真实节点、关系、标签、箭头标记、证据卡片以及进入/保持/退出阶段，同时保持活动场景可见。
  • 故障视角与教回（Failure lens and teach-back） — 影响、症状、回退、问题和答案揭示都是解释器的一部分，而非附录。
  • 读者工作区 — 可选启用同源历史、收藏、纯文本注释，以及键盘可访问的场景导航。
  • 本地导出 — PDF、场景 PNG、全场景 PPTX、与 Pages 兼容的 DOCX，以及可选的经验证的原生 .pages 转换。
  • 天然可移植 — 渲染时无需运行时包、远程字体、远程资源或网络访问。

要求

  • Skill 运行时： Node.js 18 或更高版本，以及本地文件访问权限。
  • 包依赖： 无。无需 npm install、Python 运行时、远程字体或远程渲染服务。
  • 渲染： 无需浏览器或网络连接。
  • 阅读与导出： 使用现代浏览器查看交互式 HTML，并本地导出 PDF、PNG、PPTX 或 DOCX。
  • 可选的原生 .pages 导出： macOS、Apple Pages 以及附带的回环辅助程序。

安装程序和已安装的 Skill 有各自的要求。发布金丝雀使用的 skills@1.5.23 CLI 要求 Node.js 22.20 或更高版本；已安装的 Skill 仍可在 Node.js 18 或更高版本上运行。安装需要一次性访问公共 GitHub 仓库；npx 方式还需要 npm 注册表。公开安装无需 GitHub 账号或令牌。

安装

自然语言（推荐）

将以下请求之一粘贴到你的 agent 中。它应检查 SKILL.md，未经允许不得覆盖已有安装，并报告最终位置。

Codex

使用 Codex 的 Skill 安装器，从 https://github.com/yizhiyanhua-ai/fireworks-open-eli5 全局安装 fireworks-open-eli5 Agent Skill。仓库根目录（.）即 Skill 目录，安装名称必须为 fireworks-open-eli5。先查看 SKILL.md，未经询问不要替换现有副本，验证安装路径，并告知我使用前是否需要新建 Codex 任务。

Claude Code

从 https://github.com/yizhiyanhua-ai/fireworks-open-eli5 为 Claude Code 全局安装 fireworks-open-eli5 Agent Skill。先查看 SKILL.md，在可用时使用 Agent Skills CLI，未经询问不要替换现有副本。如果安装器要求不满足，请报告，不要更改我的 Node.js 安装。验证 Claude Code 可以发现该 Skill，并报告安装路径。

使用 npx 安装

开放的 Agent Skills CLI 支持 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

# 两种 agent
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a codex -a claude-code -y

-g 表示用户级安装。去掉它则进行项目级安装。使用 npx skills@latest list -g --json 检查结果，然后启动新的 agent 任务以便重新发现 Skill。使用前请审查 Skills：它们以宿主 agent 的权限运行。

快速开始

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

命令会输出紧凑 JSON，失败时以非零状态退出。默认渲染仅创建文件。仅在故意替换已知普通文件时使用 --force；符号链接始终被拒绝。

运行完整的贡献者与分发门禁：

npm run check

这会检查 JavaScript 语法、聚焦测试、规范示例、发布包内容，以及从解压归档中进行的渲染/验证金丝雀测试。

在 Node.js 22.20 或更高版本上，还会通过固定的 Agent Skills CLI 版本，在隔离环境中测试 Codex 和 Claude Code 的安装：

npm run check:agent-install

作为 Agent Skill 使用

安装后，请求一个循证的可视化解释，例如：

解释一个排队任务如何在该仓库中流转。引用真实文件，让我播放请求路径，并展示租约过期时会出现什么故障。

阅读 SKILL.md 了解 agent 工作流，阅读 references/spec-contract.md 了解版本 1 故事规范。

故事流水线

问题 + 受众 + 证据
            │
            ▼
  版本化 JSON 故事规范
            │ 验证
            ▼
 确定性 HTML 渲染器
            │
            ├── 离线交互式解释器
            ├── 打印 / PDF
            ├── 当前场景 PNG
            ├── 全场景 PPTX
            ├── 与 Pages 兼容的 DOCX
            └── 可选原生 Pages 转换

JSON 规范是可移植的真相来源。HTML 包含其规范 SHA-256，验证器可将提供的规范与新的确定性渲染结果进行逐字节比较。

读者工作区

每个解释器都有一个目录抽屉。收藏项优先显示，随后是当前大纲、之前打开的解释器和注释浏览的独立标签页。读者可以播放、收藏、注释或导出一个场景，而无需启动全局轨迹。

本地库在读者选择 启用本地库（Enable local library） 之前保持禁用。它只记录在相同 scheme、host 和 port 下实际打开过的解释器；从不扫描文件系统。收藏和注释保存在浏览器本地、未加密，并在该源站点的浏览器数据被清除时删除。它们从不修改源 JSON 或生成的 HTML。file:// 和不可用的存储会降级为内存会话。

有关持久化、隐私、可访问性、回放和导出契约，请参阅 references/library-and-export.md。

导出

操作结果验证边界
打印 / PDF浏览器打印对话框读者在可用时选择“另存为 PDF”
PNG所选场景的 1600×900 图像PNG 签名、尺寸和场景证据页脚
PPTX每个场景一张 16:9 幻灯片ZIP 签名和必需的 OOXML 部件
DOCX每个场景一页 16:9 页面ZIP 签名和必需的 OOXML 部件
原生 PagesApple Pages 保存的真实 .pages 包必须包含 Index/Document.iwa 并能重新在 Pages 中打开

PNG、PPTX 和 DOCX 在浏览器本地构建，无需第三方库。原生 Pages 转换绝不会通过重命名 DOCX 来伪造。使用以下命令提供受信任的解释器目录：

node scripts/serve.mjs --root /absolute/path/to/explainers --port 8772

该辅助程序仅绑定 127.0.0.1，验证精确来源和轮换进程令牌，限制并验证生成的 DOCX/PNG 结构，序列化转换，并清理任务专属临时文件。这些控制用于保护浏览器操作免受跨站请求；它们不是针对其他本地进程的身份验证。

安全与隐私

渲染器读取本地文件并写入一个本地文件。生成的 HTML 使用哈希白名单内容安全策略，不嵌入远程资源，也不包含 XHR、WebSocket、eval 或 HTML 字符串 DOM 插入。其唯一连接是用户发起的、同源的可选回环 Pages 辅助程序请求。引用的 HTTP(S) URL 是普通的面向读者的链接，绝不是运行时依赖。

注释有长度限制且以文本方式插入。验证器拒绝不安全的源 URL、外部资源、运行时篡改、规范哈希漂移和意外的 CSP 哈希。参见 SECURITY.md 报告漏洞。

项目地图

  • SKILL.md — agent 工作流与交付边界
  • assets/example-spec.json — 完整的 DNS 中文示例
  • assets/explainer-shell.html — 离线视觉与交互外壳
  • scripts/render.mjs — 确定性渲染器
  • scripts/validate.mjs — 规范与输出验证器
  • scripts/serve.mjs — 仅回环的原生 Pages 辅助程序
  • references/ — 证据、语法、视觉、报告、工作区和导出契约
  • evals/ — 任务质量与触发评估提示
  • tests/ — Node 内置测试与对抗性固定用例

贡献

阅读 CONTRIBUTING.md，然后运行：

npm run check

发布包使用显式允许列表并保持 private: true 以防止意外发布到 npm。此仓库用于分发 Agent Skill，而非 npm 运行时库。

许可证与署名

Apache-2.0。参见 LICENSE 和 NOTICE。

Fireworks Open ELI5 是受 Anthropic 社区 eli5 skill 启发的独立实现，未经 Anthropic 认可。