Revela

English | 中文

Revela 可在 OpenCode 和 Codex 中使用，把来源材料、调研、数据和用户意图转成可信、可追踪、可直接用于决策沟通的 narrative artifact。

它的 narrative workspace 会记录生成 brief 或 deck 所需的关键要素：受众、决策目标、论点、论据、资料来源、风险、潜在质疑和待补齐的信息。

安装

OpenCode

通过 opencode.json 安装 npm package @cyber-dash-tech/revela：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@cyber-dash-tech/revela"]
}

重启 OpenCode。

如果想全局安装，把同样配置写到 ~/.config/opencode/opencode.json。

Codex

环境要求：

• 需要已安装 Codex CLI，并且 shell 中可以执行 codex。
• 环境中需要可以执行 npx；Revela 会用 npx -y @cyber-dash-tech/[email protected] mcp 启动 MCP server。
• 如果使用 Review UI 的 Insight、Comment 或 Apply Fix，需要 codex exec 可用。

可选的安装前检查：

codex --version
codex exec --help
npx --version

如果 npx 报 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 --ref v0.17.21
codex plugin add revela@revela

Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 npx -y @cyber-dash-tech/[email protected] mcp，由 npm 获取已发布 package 及其 dependencies。

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

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

如果要按发布路径做本地验证，运行 bun run smoke:mcp-pack。它会把当前 checkout 打成临时 npm tarball，再通过 npx 启动 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 npm pin 属于同一个 release artifact。升级后开启一个新的 Codex thread，让 Codex 重新加载 Revela skills、MCP tools、hooks 和 runtime pin。

内置设计

Revela 内置多个 deck design：

summit

monet

starter 是简洁默认演示风格。

切换设计：

/revela design --use summit

在 Codex 中，可以直接让 Revela 列出或切换 design；生成 deck 时会使用 active design。

Domains

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

/revela domain

在 Codex 中，可以直接让 Revela 列出或切换 domain；active domain 会用于 init、research 和 story 阶段的叙事 framing。

Quick Start

在包含来源材料的 workspace 中打开 Codex，然后按下面步骤逐条发送 prompt。

1. 先选择 domain，让 Revela 按你的沟通场景 framing 受众、决策、风险和潜在质疑。

revela，use consulting as domain.

2. 再选择 design，让后续生成的 deck 使用指定视觉风格。

revela，use summit as design.

3. 如果需要不同的视觉方向，可以创建一个自定义 design。

revela，创建一个名为 neon-finance 的新 design：金融仪表盘风格，深色界面、精密网格、亮绿色重点色。

Revela 可能会继续询问参考图、风格约束或禁忌项，然后创建并校验 design。创建完成后再切换使用：

revela，使用 neon-finance 作为 design。

4. 从本地材料初始化 narrative。Init 负责基于 workspace 做 grounding 并暴露 gap；它不替代 research 步骤。

revela，帮我 init 这个 workspace，先读本地材料。

5. 针对 gap 做 research，并且只把来源明确支持的 evidence 绑定回 narrative。

revela，research 当前 gaps，只绑定 source-supported evidence。

6. 生成 deck 前先读 Story，检查 claim flow、证据支撑、caveats、unsupported scope 和 open gaps。

revela，先给我看 Story，再 make deck。

7. 先创建或更新 deck plan，明确 slide 顺序、章节结构、evidence trace、caveats 和 visual intent，再生成 HTML。

revela，生成 HTML 前先 create or update deck plan。

8. 基于当前 deck plan 和 canonical narrative 生成 HTML deck。

revela，基于当前 deck plan 和 narrative make deck。

9. Review 生成后的 deck，检查 traceability、diagnostics，并做定向修改。

revela，review 生成好的 deck。

10. QA 通过后导出 PDF。

revela，把 deck export 成 PDF。

11. QA 通过后导出可编辑 PPTX。

revela，把 deck export 成 PPTX。

Review Deck

生成 HTML deck 后可以进入 Review：

/revela review --deck

Review 会打开本地 deck 工作台，主要包含两种模式：

• Insight：解释选中的 slide 内容支持哪个 claim、有哪些 evidence、还剩哪些 caveat 或 gap，以及它在叙事里的作用。
• Comment：对 deck 发起定向修改，例如 layout、文案、层级、间距或视觉调整。