Revela

English | 中文

Revela 是 Codex plugin，用来把来源材料、调研、数据和用户意图转成可信、可追踪、可直接用于决策沟通的 deck。

在本地 workspace 中，Revela 帮 Codex agent 明确目标、整理材料、写 deck-plan.md、生成 decks/*.html、在 Codex Browser 中打开 deck 供用户审阅，并导出 PDF/PPTX/PNG。

安装

Codex

这部分是给 Codex agent 看的安装说明：用户已经在 Codex 环境中，agent 负责安装或引导安装 Revela plugin。

环境要求：

• Codex 可以从 Git marketplace 安装 plugin。
• 环境中可以执行 bun；Revela plugin 会从已安装的 plugin cache 中运行 bun ./mcp/revela-server.ts 来启动 MCP server。

可选的安装前检查：

codex plugin --help
bun --version

如果 npm package 检查时报 npm cache 权限错误，可以修复 cache owner，或在本地检查时使用可写 cache：

sudo chown -R "$(id -u):$(id -g)" ~/.npm
npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack

从 Codex Git marketplace 安装最新版 Revela：

codex plugin marketplace add https://github.com/cyber-dash-tech/revela
codex plugin add revela@revela

Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 启动 Revela 时，会从已安装的 plugin cache 中运行 bun ./mcp/revela-server.ts，并解析 marketplace runtime。

不需要在 Codex marketplace clone 里运行 bun install。

安装后开启一个新的 Codex thread，让 Codex 加载 Revela 的 skills、MCP tools 和 hooks。

Codex 使用九个 Revela skills：revela 路由下一步 workflow，revela-spec 写根目录 spec.md，revela-helper 查看状态和 active design/domain，revela-design 创建、验证、激活 custom design，revela-domain 创建、验证、激活 custom narrative domain，revela-research 审阅材料、保存 findings、交付 deck-plan.md，revela-make-deck 生成 HTML deck，revela-review 在 Codex Browser 中直接打开 HTML deck，revela-export 导出 PDF/PPTX/PNG。

如果要按发布路径做本地验证，运行 bun run smoke:mcp-pack。它会把当前 checkout 打成临时 npm tarball，解包后通过打包出的 Codex plugin launcher 路径启动 MCP server，不需要先发布到 registry。

Codex 升级

在 Codex 中，可以让 Revela 检查当前 runtime version；plugin 会调用 revela_doctor 并报告正在运行的 version。

如果要固定到某个 release tag，按该 tag 重新安装 plugin：

codex plugin remove revela@revela
codex plugin marketplace remove revela
codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref vX.Y.Z
codex plugin add revela@revela

如果 marketplace entry 本来就有意跟踪 branch 或 movable ref，升级 marketplace clone 后重新添加 plugin：

codex plugin marketplace upgrade revela
codex plugin add revela@revela

Git marketplace ref 和 .mcp.json plugin launcher 属于同一个 release artifact。升级后开启一个新的 Codex thread，让 Codex 重新加载 Revela skills、MCP tools、hooks 和 runtime launcher。

内置设计

Revela 内置多个 deck design。Design preview 由内置 page-template preview fixture 加上当前 design CSS 生成。每组截图保留 cover，并选择更能体现该 design 特征的代表性 template 页面。

starter

summit

monet

lucent

lucent-dark

在 Codex 中切换 design，可以这样问：

使用 Revela 切换到 summit design。

在 Codex 中，可以直接让 Revela 列出或切换 design；新生成的 deck 会使用 active design。已有 deck 要带上文件路径，这样 Revela 会刷新该 deck 的本地 design snapshot，不重写 slide 内容：

使用 Revela 将 @decks/.html 切换到 summit design。

Domains

Domain 提供特定场景的沟通 guidance，例如 consulting、product 或 investor communication。需要让 Revela 按具体沟通场景调整 deck framing 时使用。

使用 Revela 列出 available domains。

在 Codex 中，可以直接让 Revela 列出或切换 domain；active domain 会用于 spec、plan 和 deck framing。

Quick Start

在包含来源材料的 workspace 中打开 Codex，然后按下面流程推进。

1. Spec：确认目标、受众、输出形式、约束、语言、设计偏好和验收标准，并写入 spec.md。

使用 Revela 把这个目标整理成用于决策 deck 的 spec.md。先检查 workspace，只询问真正影响结果的缺失信息，并推荐下一步。

2. Plan：审阅材料、保存带来源的 findings，并产出 deck-plan.md。

使用 Revela 审阅材料，保存有用 findings，并为这个 deck 生成 deck-plan.md。

3. Render Deck：基于 deck-plan.md 生成 decks/*.html。

使用 Revela 根据 deck-plan.md render deck。

4. Review：在 Codex Browser 中直接打开 HTML deck。把 @decks/<file>.html 替换为实际生成的文件路径。

使用 Revela 在 Codex Browser 中 review @decks/.html。

Review 时检查文案、论证节奏、层级、间距、图表、表格、视觉和导出前问题。如果需要诊断报告，再让 Revela 对同一个 deck 文件做 diagnose 或 QA。

5. Export：导出审阅后的 HTML deck。把 @decks/<file>.html 替换为实际生成的文件路径。

使用 Revela 导出 @decks/.html 为 PDF。

使用 Revela 导出 @decks/.html 为可编辑 PPTX。

使用 Revela 导出 @decks/.html 为逐页 PNG。

可选前置设置：

• 使用 Revela 切换到 consulting domain。
• 使用 Revela 切换到 summit design。
• 使用 Revela 创建一个名为 neon-finance 的 custom design，风格是金融仪表盘、深色界面、精密网格和亮绿色重点色。