@cyber-dash-tech/revela 0.1.16 → 0.2.1

package/README.zh-CN.md

@@ -2,35 +2,37 @@
 
 [English](README.md) | **中文**
 
-[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-110%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
+[![npm version](https://img.shields.io/npm/v/@cyber-dash-tech/revela)](https://www.npmjs.com/package/@cyber-dash-tech/revela) [![license](https://img.shields.io/npm/l/@cyber-dash-tech/revela)](LICENSE) [![tests](https://img.shields.io/badge/tests-109%20passing-brightgreen)](tests/) [![OpenCode plugin](https://img.shields.io/badge/OpenCode-plugin-blue)](https://opencode.ai) [![Bun](https://img.shields.io/badge/Bun-%E2%89%A51.0-orange)](https://bun.sh)
 
 <p align="center">
   <img src="assets/img/logo.png" alt="Revela" width="800" />
 </p>
 
 Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使用的 agent 变成 HTML 幻灯片生成器。
-在当前会话中启用它之后，agent 可以完成调研、结构设计、HTML 写作和自动 QA，并把结果输出到 `decks/*.html`。
+在当前会话中启用之后，agent 可以完成调研、结构设计、HTML 写作、QA 和导出。
 
-**[在线演示 — AI 权力转移](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)** · 一份使用 Revela 生成的 5 页投资简报。
+**[在线演示 — AI 权力转移](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)**
 
 ---
 
-## Revela 是什么
+## 它能做什么
 
-Revela 是一种工作模式，不是一个独立聊天 agent。
-
-- `/revela enable` 会把演示文稿生成专用的 system prompt 注入到当前 agent
+- 通过 `/revela enable` 向当前 agent 注入演示文稿专用 system prompt
 - prompt 由 3 层组成：核心 skill、当前 domain、当前 design
-- agent 可以扫描工作区文件、委托网页调研、生成 HTML 幻灯片，并自动执行布局 QA
-- design 和 domain 的切换都在本地完成，并会立即重建 active prompt
+- 支持工作区文档扫描，以及 `.pdf`、`.docx`、`.pptx`、`.xlsx` 的透明文本提取
+- agent 每次写入 `decks/*.html` 时自动执行布局 QA
+- 支持导出成 PDF 和可编辑 PPTX
+- design 和 domain 的切换都在本地完成，不消耗 LLM token
+
+Revela 是一种工作模式，不是独立 agent。
 
 ---
 
 ## 环境要求
 
 - [OpenCode](https://opencode.ai)
-- Bun 运行时（`bun >= 1.0.0`）
-- [Google Chrome](https://www.google.com/chrome/) 或 Chromium，用于布局 QA 和 PDF 导出
+- Bun 运行时 `>= 1.0.0`
+- [Google Chrome](https://www.google.com/chrome/) 或 Chromium，用于 QA、PDF 导出和 PPTX 导出
 - Git，用于源码安装
 
 ---
@@ -48,19 +50,13 @@ Revela 是一种工作模式，不是一个独立聊天 agent。
 }
 ```
 
-重启 OpenCode 后，插件会通过 Bun 自动安装。
+然后重启 OpenCode。
 
-如果想全局安装，可以把同样的 `plugin` 配置写到 `~/.config/opencode/opencode.json`。
+如果想全局安装，可以把同样配置写到 `~/.config/opencode/opencode.json`。
 
 ### 本地 wrapper 安装
 
-以下情况建议直接使用本地 wrapper：
-
-- Bun 插件安装不稳定或被网络环境阻塞
-- 你在中国大陆网络环境下使用 OpenCode
-- 你希望直接运行本地源码仓库
-
-源码安装方式：
+如果 Bun 安装被网络阻塞、不稳定，或者你想直接运行本地源码仓库，建议使用本地 wrapper。
 
 ```bash
 git clone https://github.com/cyber-dash-tech/revela
@@ -74,41 +70,44 @@ npm install
 export { default } from "/absolute/path/to/revela/index.ts";
 ```
 
-如果走本地 wrapper 方案，确保 `~/.config/opencode/opencode.json` 里不要同时保留 `@cyber-dash-tech/revela` 的 `plugin` 配置，否则 OpenCode 启动时仍会尝试用 Bun 安装。
+如果使用本地 wrapper，记得把 `opencode.json` 里的 `@cyber-dash-tech/revela` `plugin` 配置删掉，否则 OpenCode 仍可能尝试用 Bun 安装。
 
 ### 中国大陆网络说明
 
-OpenCode 的 npm 插件安装依赖 Bun，而 Bun 可能不会遵循 npm mirror 配置。如果直接安装失败，优先使用上面的本地 wrapper 方案，或者先把包安装到 `~/.config/opencode/`，再手动创建本地插件入口文件。
+OpenCode 的 npm 插件安装依赖 Bun，而 Bun 可能不会遵循 npm mirror 设置。如果直接安装失败，优先使用上面的本地 wrapper 方案。
 
 ---
 
 ## 快速开始
 
-启动 OpenCode：
+先在当前会话中启用 Revela：
 
-```bash
-opencode
+```text
+/revela enable
 ```
 
-在当前会话中启用 Revela：
+如有需要，先切换 design 或 domain：
 
 ```text
-/revela enable
+/revela designs
+/revela designs summit
+/revela domains deeptech-investment
 ```
 
-然后直接给 agent 一个幻灯片任务，例如：
+然后直接给 agent 一个 deck 任务：
 
 ```text
-Create a 6-slide HTML deck on humanoid robotics supply chains. Use the summit design, cite the main market drivers, and save the result to decks/humanoid-robotics.html.
+Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main market drivers, use the active design faithfully, and save the result to decks/humanoid-robotics.html.
 ```
 
-如果需要，把生成好的 HTML 导出为 PDF：
+需要导出时：
 
 ```text
 /revela pdf decks/humanoid-robotics.html
+/revela pptx decks/humanoid-robotics.html
 ```
 
-关闭 Revela，让当前 agent 回到普通模式：
+完成后关闭演示文稿模式：
 
 ```text
 /revela disable
@@ -134,6 +133,7 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Use the summit de
 /revela domains-rm <name>        删除已安装 domain
 
 /revela pdf <file>               将 HTML deck 导出为同目录 PDF
+/revela pptx <file>              将 HTML deck 导出为同目录可编辑 PPTX
 ```
 
 所有 `/revela` 命令都在本地执行，不消耗 LLM token。
@@ -146,11 +146,12 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Use the summit de
 
 这份 prompt 由 3 层组成：
 
-1. `skill/SKILL.md`：核心幻灯片生成流程
-2. 当前 active domain：行业结构与术语
-3. 当前 active design：视觉语言、layout、component 和图表规则
+1. `skill/SKILL.md` - 核心幻灯片生成流程
+2. 当前 active domain - 行业结构与术语
+3. 当前 active design - 视觉系统、layout、component 和图表规则
 
-当前 design 和 domain 会持久化到 `~/.config/revela/config.json`。是否启用 Revela 则是会话级状态，不会跨会话持久化。
+持久化配置保存在 `~/.config/revela/config.json`。
+是否启用 Revela 则只在当前会话生效。
 
 ---
 
@@ -159,60 +160,54 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Use the summit de
 启用 Revela 后，agent 可以使用：
 
 - `revela-workspace-scan` 扫描工作区中的 PDF、Office 文件、CSV、Markdown 和文本文件
-- `revela-research` 子代理抓取目标网页，并把结构化结果保存到 `researches/<topic>/`
-- `revela-research-save` 按 research axis 写入单个 findings 文件
+- `revela-research` 子代理做定向网页调研
+- `revela-research-save` 把结构化 findings 写入 `researches/<topic>/`
+
+支持提取文本的入口：
 
-支持 `@` 引用和自动文本提取的文件类型：
+- 在对话里 `@` 引用或直接粘贴文件
+- 启用 Revela 后通过 `read` 工具访问文件
+
+支持提取的文件类型：
 
 - `.pdf`
 - `.docx`
 - `.pptx`
 - `.xlsx`
 
-Revela 会在主 agent 处理这些文件前，先透明地完成文本提取。
+这些提取过程对主 agent 是透明的。
 
 ---
 
 ## 布局 QA 与合规检查
 
-每次 agent 写入 `decks/*.html` 时，Revela 都会自动在 `1920x1080` 分辨率下运行一轮基于 Puppeteer 的 QA。
-报告会立刻反馈给 agent，用于继续修正布局或 design compliance 问题。
+每次 agent 写入 `decks/*.html` 时，Revela 都会自动在 `1920x1080` 下运行一轮基于 Puppeteer 的 QA。
+报告会立刻返回，便于 agent 继续修正。
 
-当前 QA 维度如下：
+当前 QA 维度：
 
 | 维度 | 检查内容 |
 |---|---|
 | `overflow` | 元素是否超出 slide canvas |
-| `balance` | 是否过稀、重心偏移、底部留白过大等 |
+| `balance` | 是否过稀、重心偏移、底部留白过大 |
 | `symmetry` | 并列列之间的高度或密度是否明显失衡 |
 | `rhythm` | 垂直堆叠元素之间的间距节奏是否不稳定 |
 | `compliance` | 是否使用了 active design 之外的 class 或新增 CSS 规则 |
 
-每张 slide 都必须显式声明 `slide-qa="true"` 或 `slide-qa="false"`。
-
-- `slide-qa="true"`：适用于内容型页面，执行完整 QA
-- `slide-qa="false"`：适用于封面、目录、引用、总结、结尾等结构型页面
+每张 slide 都必须声明 `slide-qa="true"` 或 `slide-qa="false"`。
 
-`compliance` 不是软建议，而是生成流程的一部分。如果 agent 发明了 design 之外的 class 或 CSS rule，QA 会直接指出并要求修正。
+- `slide-qa="true"` 适用于内容型页面，执行完整 QA
+- `slide-qa="false"` 适用于封面、目录、引用、总结、结尾等结构型页面
 
 也可以手动调用 `revela-qa` 工具执行 QA。
 
 ---
 
-## 内置 Designs
-
-使用 `/revela designs <name>` 切换。
-
-| 名称 | 说明 | 预览 |
-|---|---|---|
-| `aurora` | 深色 executive 风格，信息密度更高，适合结构化商业表达和 ECharts 数据可视化 | ![aurora](assets/img/slide-example-aurora.jpg) |
-| `summit` | 年报式 editorial 风格，适合图像丰富、叙事感更强的商业表达 | ![summit](assets/img/slide-example-summit.jpg) |
-
----
+## Designs 与 Domains
 
-## 内置 Domains
+用 `/revela designs` 和 `/revela domains` 查看你当前环境里实际安装的内容。
 
-使用 `/revela domains <name>` 切换。
+仓库内置的 domains：
 
 | 名称 | 说明 |
 |---|---|
@@ -220,11 +215,18 @@ Revela 会在主 agent 处理这些文件前，先透明地完成文本提取。
 | `deeptech-investment` | VC / 投资分析：市场规模、技术成熟度、护城河与投资逻辑 |
 | `consulting` | 战略咨询：go/no-go 判断、战略设计与 belief-change 报告 |
 
+仓库中的 design 示例：
+
+| 名称 | 说明 | 预览 |
+|---|---|---|
+| `summit` | 年报式 editorial 风格，适合图像更丰富、叙事感更强的商业表达 | ![summit](assets/img/slide-example-summit.jpg) |
+| `monet` | 更轻、更安静的 serif 视觉系统，适合带有 art direction 气质的商业叙事 | 仓库内含 `DESIGN.md` |
+
 ---
 
 ## 自定义 Designs
 
-自定义 design 是一个包含 `DESIGN.md` 的文件夹，文件头使用 frontmatter：
+自定义 design 是一个包含 `DESIGN.md` 的文件夹，并带有 frontmatter：
 
 ```yaml
 ---
@@ -235,58 +237,42 @@ version: 1.0.0
 ---
 ```
 
-文件正文定义 agent 可使用的视觉系统。
-
-### Marker 体系
-
-对于较大的 design，建议使用当前 marker 格式：
+对于较大的 design，建议使用 marker 体系：
 
 ```html
 <!-- @design:foundation:start -->
-色彩、字体、CSS 变量、HTML 外壳、基础 JS...
+Foundation rules
 <!-- @design:foundation:end -->
 
 <!-- @design:rules:start -->
-构图规则、正反案例、design 特定约束...
+Design rules
 <!-- @design:rules:end -->
 
 <!-- @design:layouts:start -->
 <!-- @layout:cover:start qa=false -->
-Layout 详情...
+Layout details
 <!-- @layout:cover:end -->
-
-<!-- @layout:two-col:start qa=true -->
-Layout 详情...
-<!-- @layout:two-col:end -->
 <!-- @design:layouts:end -->
 
 <!-- @design:components:start -->
 <!-- @component:card:start -->
-Component HTML + CSS...
+Component details
 <!-- @component:card:end -->
-
-<!-- @component:stat-card:start -->
-Component HTML + CSS...
-<!-- @component:stat-card:end -->
 <!-- @design:components:end -->
 
 <!-- @design:chart-rules:start -->
-图表规则...
+Chart rules
 <!-- @design:chart-rules:end -->
 ```
 
-Prompt 注入行为如下：
+Prompt 注入规则：
 
 - 常驻注入：`@design:foundation`、`@design:rules`、layout index、component index
 - 按需获取：单个 `@layout:*`、单个 `@component:*`、`@design:chart-rules`
 
 如果 design 没有 marker，Revela 会退回到整份 `DESIGN.md` 全量注入。
 
-### 给 design 作者的 compliance 说明
-
-Revela 会从 design 中提取允许使用的 CSS class vocabulary，并在 QA 的 compliance 维度里做校验。如果 agent 发明了新的 class 或 CSS rule，QA 会直接报出。
-
-### 安装自定义 Design
+安装自定义 design：
 
 ```text
 /revela designs-add github:your-org/your-design
@@ -298,31 +284,42 @@ Revela 会从 design 中提取允许使用的 CSS class vocabulary，并在 QA
 
 ## 自定义 Domains
 
-自定义 domain 是一个包含 `INDUSTRY.md` 的文件夹，frontmatter 结构与 design 类似。
+自定义 domain 是一个包含 `INDUSTRY.md` 的文件夹。
 
 ```text
 /revela domains-add github:your-org/your-domain
 ```
 
-`INDUSTRY.md` 是为了兼容历史版本而保留的文件名。
+`INDUSTRY.md` 是为兼容历史版本保留的文件名。
 
 ---
 
-## PDF 导出
+## 导出
 
-把生成好的 HTML deck 导出为 PDF：
+PDF 导出：
 
 ```text
 /revela pdf decks/my-deck.html
 ```
 
-Revela 会通过 Chrome / Chromium 渲染每一页 slide，并在同目录生成最终 PDF。
+可编辑 PPTX 导出：
+
+```text
+/revela pptx decks/my-deck.html
+```
+
+两种导出都会把结果写到源 HTML deck 同目录。
 
 ---
 
-## 日志
+## 开发
+
+```bash
+bun test
+bun run typecheck
+```
 
-Revela 使用 [tslog](https://tslog.js.org/) 输出结构化日志。开启详细调试输出：
+开启详细日志：
 
 ```bash
 REVELA_DEBUG=1 opencode
@@ -332,4 +329,4 @@ REVELA_DEBUG=1 opencode
 
 ## 许可证
 
-MIT，详见 [LICENSE](LICENSE).
+MIT - 见 [LICENSE](LICENSE)

package/lib/agents/research-prompt.ts

@@ -37,8 +37,17 @@ Given a research brief specifying your topic and axis, you will:
 Use the **\`revela-workspace-scan\`** tool in a single call to discover all document
 files in the workspace (PDF, Word, Excel, PowerPoint, CSV, text).
 
-Then read every relevant file using the \`read\` tool. For PDFs and Office formats,
-the Revela plugin extracts text transparently — just call \`read\` normally.
+Then select the files relevant to your research axis.
+
+For every selected file, call **\`revela-extract-document-materials\`** first.
+- \`pptx\`, \`docx\`, and \`xlsx\` will produce a manifest plus extracted text and any available embedded materials
+- unsupported file types will be skipped automatically
+
+After that, use the \`read\` tool on:
+- the original relevant file when you want the plain extracted text
+- the generated manifest and extracted image/table files when visual or tabular evidence matters
+
+For PDFs and Office formats, the Revela plugin extracts text transparently — just call \`read\` normally.
 
 ---
 
@@ -125,6 +134,7 @@ Gaps:
 - **NEVER** ask the user for information you can find through search or workspace files
 - **NEVER** use the raw \`write\` tool — always use \`revela-research-save\`
 - **NEVER** fabricate image URLs — only record URLs you actually found
+- **Always** call \`revela-extract-document-materials\` for every selected workspace file before deciding which extracted materials to read next
 - **Always** include source attribution on every data point
 - **Always** use tables for comparative data (more useful than bullets for presentations)
 - **Preserve** raw data — the primary agent will select what to include in slides

package/lib/commands/help.ts

@@ -34,6 +34,7 @@ export async function handleHelp(
     `\`/revela domains-add <url>\`   — install a domain from URL / github:user/repo\n` +
     `\`/revela designs-rm <name>\`   — remove an installed design\n` +
     `\`/revela domains-rm <name>\`   — remove an installed domain\n` +
-    `\`/revela pdf <file>\`          — export HTML slide deck to PDF`
+    `\`/revela pdf <file>\`          — export HTML slide deck to PDF\n` +
+    `\`/revela pptx <file>\`         — export HTML slide deck to PPTX`
   )
 }

package/lib/commands/pptx.ts

@@ -0,0 +1,75 @@
+/**
+ * lib/commands/pptx.ts
+ *
+ * Handler for `/revela pptx <file_path>` — exports an HTML slide deck to PPTX.
+ *
+ * Output: same directory and base name as the input, with .pptx extension.
+ * Example: decks/my-deck.html → decks/my-deck.pptx
+ */
+
+import { resolve } from "path"
+import { exportToPptx } from "../pptx/export"
+
+function formatSecs(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+export async function handlePptx(
+  filePath: string,
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  if (!filePath) {
+    await send(
+      "**Usage:** `/revela pptx <file_path>`\n\n" +
+      "Example: `/revela pptx decks/my-deck.html`"
+    )
+    return
+  }
+
+  const abs = resolve(filePath)
+  await send(`Exporting \`${abs}\` to PPTX...`)
+
+  try {
+    let lastSlideUpdate = 0
+    let longDeckThreshold: number | null = null
+
+    const result = await exportToPptx(filePath, {
+      onProgress: async (progress) => {
+        if (progress.kind === "stage") {
+          await send(progress.message)
+          return
+        }
+
+        const current = progress.current ?? 0
+        const total = progress.total ?? 0
+        if (!total) return
+
+        if (longDeckThreshold === null) {
+          longDeckThreshold = total >= 8 ? (total > 20 ? 5 : 2) : -1
+        }
+        if (longDeckThreshold < 0) return
+
+        const shouldSend = current === 1 || current === total || current - lastSlideUpdate >= longDeckThreshold
+        if (!shouldSend) return
+
+        lastSlideUpdate = current
+        await send(`Editable export progress: slide ${current}/${total}`)
+      },
+    })
+
+    await send(
+      `**PPTX exported successfully**\n\n` +
+      `- Output: \`${result.outputPath}\`\n` +
+      `- Slides: ${result.slideCount}\n` +
+      `- Time: ${formatSecs(result.durationMs)}\n` +
+      `- Prepare: ${formatSecs(result.timingsMs.prepareMs)}\n` +
+      `- Page setup: ${formatSecs(result.timingsMs.pageSetupMs)}\n` +
+      `- Slide export: ${formatSecs(result.timingsMs.slideExportMs)}\n` +
+      `- Merge: ${formatSecs(result.timingsMs.mergeMs)}\n` +
+      `- Write: ${formatSecs(result.timingsMs.writeMs)}`
+    )
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    await send(`**PPTX export failed**\n\n\`\`\`\n${msg}\n\`\`\``)
+  }
+}