@cyber-dash-tech/revela 0.1.1 → 0.1.3

package/README.md

@@ -2,14 +2,18 @@
 
 **English** | [中文](README.zh-CN.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-73%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>
+
 An [OpenCode](https://opencode.ai) plugin that turns your AI into a presentation assistant.
-Describe what you want to present — Revela researches, analyses, and generates a complete slide deck for you.
+Tell Revela what's on your mind — it'll finish the research and analysis, and deliver a complete slide deck in a couple of minutes.
+
 
-[![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-73%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)
+
+**[Live Demo — The AI Power Shift](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)** · A 5-slide investment brief generated entirely by Revela.
 
 ---
 
@@ -55,18 +59,21 @@ export { default } from "/absolute/path/to/revela/index.ts";
 
 ## Quick Start
 
+Enable OpenCode's web search (recommended):
+```bash
+OPENCODE_ENABLE_EXA=1 opencode
+```
+
+Enable Revela in your OpenCode session — turns the primary agent into a slide design expert:
 ```
 /revela enable
 ```
 
-Then describe your presentation goal to the AI. Revela will understand your real intent through conversation, then generate a complete slide deck. Open the output file in any browser — no build step, no framework.
-
+To turn it off and restore the primary agent to normal:
 ```
 /revela disable
 ```
 
-Turns off Revela's system prompt for the current session.
-
 ---
 
 ## Commands
@@ -93,11 +100,11 @@ All commands execute locally — zero LLM cost, instant feedback.
 
 Three designs are bundled. Switch with `/revela designs <name>`.
 
-| Name | Description |
-|---|---|
-| `default` | Dark executive style — deep navy/slate, sharp typography, ECharts data visualization |
-| `minimal` | Clean light theme — high contrast, generous whitespace, professional look |
-| `editorial-ribbon` | Bold editorial layout — accent ribbons, strong headlines, high visual impact |
+| Name | Description | Preview |
+|---|---|---|
+| `default` | Dark executive style — deep navy/slate, sharp typography, ECharts data visualization | ![default](assets/img/slide-example-default.jpg) |
+| `minimal` | Clean light theme — high contrast, generous whitespace, professional look | ![minimal](assets/img/slide-example-minimal.jpg) |
+| `editorial-ribbon` | Bold editorial layout — accent ribbons, strong headlines, high visual impact | ![editorial-ribbon](assets/img/slide-example-ribbon.jpg) |
 
 ---
 
@@ -141,7 +148,7 @@ Checks performed on every slide:
 | **Density imbalance** | Columns where CSS `align-items: stretch` hides content imbalance |
 | **Sparse** | Slides with too few visible elements |
 
-Cover, TOC, divider, summary, and closing slides are automatically exempted from fill/spacing checks via the `data-slide-type` attribute.
+Structural slides (cover, TOC, quote, summary, closing) set `slide-qa="false"` and are automatically exempted from fill/spacing checks. Content-heavy slides set `slide-qa="true"` to opt in.
 
 You can also invoke QA manually: ask the AI to "run QA on slides/my-deck.html" or use the `revela-qa` tool directly.
 

package/README.zh-CN.md

@@ -2,14 +2,19 @@
 
 [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-73%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) 插件，让 AI 成为你的PPT助手。
 用对话方式描述你的需求，Revela 会自动调研、分析、洞察，最后呈现你心中的PPT。
 
-[![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-73%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)
+
+
+**[在线演示 — AI 权力转移](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)** · 一份由 Revela 全程生成的 5 页投资简报。
 
 ---
 
@@ -85,18 +90,21 @@ export { default } from "/path/to/revela/index.ts";
 
 ## 快速开始
 
+启用opencode搜索功能（推荐）
+```Bash
+OPENCODE_ENABLE_EXA=1 opencode
+```
+
+在 opencode 中启动 Revela（默认关闭），将 primary agent 变为演讲稿设计专家
 ```
 /revela enable
 ```
 
-然后向 AI 描述你的演讲目标。Revela 会通过聊天洞察你的真实诉求，随后生成一个完整的幻灯片文件。用浏览器直接打开，无需构建，无需框架。
-
+关闭当前会话中 Revela，primary agent 恢复正常
 ```
 /revela disable
 ```
 
-关闭当前会话中 Revela 的系统提示注入。
-
 ---
 
 ## 命令
@@ -119,19 +127,19 @@ export { default } from "/path/to/revela/index.ts";
 
 ---
 
-## 内置设计
+## 内置设计模版
 
 插件内置三套设计，用 `/revela designs <name>` 切换。
 
-| 名称 | 说明 |
-|---|---|
-| `default` | 深色商务风格 —— 深海军蓝/石板色，锐利字体，ECharts 数据可视化 |
-| `minimal` | 简洁浅色主题 —— 高对比度，充足留白，专业外观 |
-| `editorial-ribbon` | 大胆的编辑版式 —— 强调色横幅，醒目标题，高视觉冲击力 |
+| 名称 | 说明 | 预览 |
+|---|---|---|
+| `default` | 深色商务风格 —— 深海军蓝/石板色，锐利字体，ECharts 数据可视化 | ![default](assets/img/slide-example-default.jpg) |
+| `minimal` | 简洁浅色主题 —— 高对比度，充足留白，专业外观 | ![minimal](assets/img/slide-example-minimal.jpg) |
+| `editorial-ribbon` | 大胆的编辑版式 —— 强调色横幅，醒目标题，高视觉冲击力 | ![editorial-ribbon](assets/img/slide-example-ribbon.jpg) |
 
 ---
 
-## 内置领域
+## 内置行业SOP
 
 领域为 AI 的上下文提供特定行业的报告框架和术语。
 
@@ -156,9 +164,9 @@ export { default } from "/path/to/revela/index.ts";
 
 ---
 
-## 布局 QA
+## 排版 QA
 
-每次 AI 写入幻灯片文件时，Revela 会自动在 1920×1080 分辨率下运行基于 Puppeteer 的布局检测。发现问题后立即将报告反馈给 AI，AI 自行修正，无需人工干预。
+每次 AI 写入幻灯片文件时，Revela 会自动在 1920×1080 分辨率下运行基于 Puppeteer 的排版质检。发现问题后立即将报告反馈给 AI，AI 自行修正，无需人工干预。（**功能持续更新中 ...**）
 
 每张幻灯片的检查项：
 
@@ -171,7 +179,7 @@ export { default } from "/path/to/revela/index.ts";
 | **密度失衡** | CSS `align-items: stretch` 列布局中隐藏的内容不平衡 |
 | **稀疏** | 可见元素过少的幻灯片 |
 
-封面、目录、分隔、总结、结语幻灯片通过 `data-slide-type` 属性自动豁免填充/间距检查。
+结构性幻灯片（封面、目录、引言、总结、结语）设置 `slide-qa="false"`，自动豁免填充/间距检查。内容型幻灯片设置 `slide-qa="true"` 启用 QA 检查。
 
 也可以手动触发：让 AI "对 slides/my-deck.html 运行 QA"，或直接使用 `revela-qa` 工具。
 
@@ -179,7 +187,7 @@ export { default } from "/path/to/revela/index.ts";
 
 ---
 
-## 自定义设计
+## 自定义模版
 
 设计是包含 `DESIGN.md` 文件的文件夹，frontmatter 声明元数据：
 
@@ -232,7 +240,7 @@ ECharts / 数据可视化规范...
 
 没有标记时，整个 `DESIGN.md` 内容每轮全量注入（向后兼容）。
 
-### 安装自定义设计
+### 自定义模版安装
 
 ```
 /revela designs-add github:your-org/your-design
@@ -242,7 +250,7 @@ ECharts / 数据可视化规范...
 
 ---
 
-## 自定义领域
+## 自定义行业SOP
 
 领域为 AI 增加特定行业的报告框架、术语和结构化指导。
 

package/lib/config.ts

@@ -28,7 +28,7 @@ export const CONFIG_FILE = join(CONFIG_DIR, "config.json")
 export const ACTIVE_PROMPT_FILE = join(CONFIG_DIR, "_active-prompt.md")
 
 /** Default design name. */
-export const DEFAULT_DESIGN = "default"
+export const DEFAULT_DESIGN = "aurora"
 
 /** Default domain name. */
 export const DEFAULT_DOMAIN = "general"

package/lib/design/designs.ts

@@ -145,28 +145,41 @@ export function getDesignSkillMd(name?: string): string {
 // Marker-based section / component parsing
 // ---------------------------------------------------------------------------
 
+export interface LayoutInfo {
+  /** Full text content of the layout block (without marker lines). */
+  content: string
+  /** Whether this layout type should be QA-checked for balance/rhythm. */
+  qa: boolean
+}
+
 export interface DesignSections {
-  /** Map of section name → extracted content (without marker lines). */
+  /** Map of @design:<name> section → extracted content (without marker lines). */
   sections: Record<string, string>
-  /** Map of component name → extracted content (without marker lines). */
+  /** Map of @layout:<name> → LayoutInfo with content + qa flag. */
+  layouts: Record<string, LayoutInfo>
+  /** Map of @component:<name> → extracted content (without marker lines). */
   components: Record<string, string>
   /** Whether the DESIGN.md has any markers at all. */
   hasMarkers: boolean
 }
 
 /**
- * Parse a DESIGN.md body (no frontmatter) into sections and components
- * using the two-layer HTML comment marker convention:
- *   <!-- @section:<name>:start --> … <!-- @section:<name>:end -->
+ * Parse a DESIGN.md body (no frontmatter) into sections, layouts, and components
+ * using the three-layer HTML comment marker convention:
+ *   <!-- @design:<name>:start --> … <!-- @design:<name>:end -->
+ *   <!-- @layout:<name>:start qa=true|false --> … <!-- @layout:<name>:end -->
  *   <!-- @component:<name>:start --> … <!-- @component:<name>:end -->
  *
+ * The `qa` attribute on layout markers defaults to `true` when omitted.
  * Returns an object with empty maps and hasMarkers=false when no markers found.
  */
 export function parseDesignSections(body: string): DesignSections {
   const sections: Record<string, string> = {}
+  const layouts: Record<string, LayoutInfo> = {}
   const components: Record<string, string> = {}
 
-  const sectionRe = /<!--\s*@section:(\w[\w-]*):start\s*-->([\s\S]*?)<!--\s*@section:\1:end\s*-->/g
+  const sectionRe   = /<!--\s*@design:(\w[\w-]*):start\s*-->([\s\S]*?)<!--\s*@design:\1:end\s*-->/g
+  const layoutRe    = /<!--\s*@layout:(\w[\w-]*):start(?:\s+qa=(true|false))?\s*-->([\s\S]*?)<!--\s*@layout:\1:end\s*-->/g
   const componentRe = /<!--\s*@component:(\w[\w-]*):start\s*-->([\s\S]*?)<!--\s*@component:\1:end\s*-->/g
 
   let hasMarkers = false
@@ -177,12 +190,20 @@ export function parseDesignSections(body: string): DesignSections {
     sections[match[1]] = match[2].trim()
   }
 
+  while ((match = layoutRe.exec(body)) !== null) {
+    hasMarkers = true
+    const qaAttr = match[2]
+    // qa defaults to true when attribute is omitted
+    const qa = qaAttr === "false" ? false : true
+    layouts[match[1]] = { content: match[3].trim(), qa }
+  }
+
   while ((match = componentRe.exec(body)) !== null) {
     hasMarkers = true
     components[match[1]] = match[2].trim()
   }
 
-  return { sections, components, hasMarkers }
+  return { sections, layouts, components, hasMarkers }
 }
 
 /**
@@ -219,6 +240,75 @@ export function generateComponentIndex(components: Record<string, string>): stri
   ].join("\n")
 }
 
+/**
+ * Generate a compact Layout Index table from parsed layouts.
+ * Lists each layout name with the QA flag and a one-line description.
+ */
+export function generateLayoutIndex(layouts: Record<string, LayoutInfo>): string {
+  const names = Object.keys(layouts)
+  if (names.length === 0) return ""
+
+  const rows = names.map((name) => {
+    const { content, qa } = layouts[name]
+    const firstLine = content
+      .split("\n")
+      .map((l) => l.trim())
+      .find((l) => l && !l.startsWith("<!--") && !l.startsWith("```"))
+    const desc = firstLine
+      ? firstLine.replace(/^#+\s*/, "").replace(/\(.*?\)/, "").trim()
+      : ""
+    const qaIcon = qa ? "✓" : "—"
+    return `| \`${name}\` | ${qaIcon} | ${desc} |`
+  })
+
+  return [
+    "### Layout Index",
+    "",
+    "| Layout | QA | Description |",
+    "|---|---|---|",
+    ...rows,
+    "",
+    "_Use `revela-designs` tool with `action: \"read\"` and `layout: \"<name>\"` to get full HTML/CSS for any layout._",
+  ].join("\n")
+}
+
+/**
+ * Get the raw text of one or more named layouts from a DESIGN.md.
+ * @param layoutNames - Comma-separated layout names or an array.
+ * @param designName - Design to read from (defaults to active).
+ */
+export function getDesignLayout(
+  layoutNames: string | string[],
+  designName?: string,
+): string {
+  const name = designName || activeDesign()
+  const mdPath = join(DESIGNS_DIR, name, "DESIGN.md")
+  if (!existsSync(mdPath)) {
+    throw new Error(`Design '${name}' is not installed`)
+  }
+  const text = readFileSync(mdPath, "utf-8")
+  const { body } = parseFrontmatter(text)
+  const { layouts, hasMarkers } = parseDesignSections(body)
+
+  if (!hasMarkers) {
+    throw new Error(`Design '${name}' has no markers — use getDesignSkillMd() for full text`)
+  }
+
+  const names = Array.isArray(layoutNames)
+    ? layoutNames
+    : layoutNames.split(",").map((s) => s.trim())
+
+  const parts: string[] = []
+  for (const layoutName of names) {
+    if (!(layoutName in layouts)) {
+      throw new Error(`Layout '${layoutName}' not found in design '${name}'`)
+    }
+    const { content, qa } = layouts[layoutName]
+    parts.push(`### Layout: ${layoutName} (qa=${qa})\n\n${content}`)
+  }
+  return parts.join("\n\n---\n\n")
+}
+
 /**
  * Get the raw text of a named section from a DESIGN.md.
  * Throws if the design is not installed or the section doesn't exist.

package/lib/prompt-builder.ts

@@ -29,10 +29,10 @@ import {
   getDesignSkillMd,
   parseDesignSections,
   generateComponentIndex,
+  generateLayoutIndex,
 } from "./design/designs"
 import { activeDomain, getDomainSkillMd } from "./domain/domains"
 import { parseFrontmatter } from "./frontmatter"
-import { SLIDE_TYPES, type SlideType } from "./qa/checks"
 import { childLog } from "./log"
 
 const promptLog = childLog("prompt-builder")
@@ -40,21 +40,6 @@ const promptLog = childLog("prompt-builder")
 /** Path to SKILL.md shipped with this package. */
 const SKILL_MD_PATH = resolve(__dirname, "..", "skill", "SKILL.md")
 
-/**
- * Human-readable descriptions for each slide type.
- * Used to generate the data-slide-type table injected into SKILL.md.
- * Kept here (not in checks.ts) — these are prose for the AI, not QA logic.
- */
-const SLIDE_TYPE_DESCRIPTIONS: Record<SlideType, string> = {
-  cover: "Title / opening slide",
-  toc: "Table of contents",
-  content: "Regular content slides (default)",
-  summary: "Key takeaways slide",
-  closing: "Thank-you / Q&A / contact slide",
-  divider: "Section-break / transition slide",
-  "thank-you": "Alias for `closing`",
-}
-
 /**
  * Build the combined system prompt and write it to _active-prompt.md.
  *
@@ -66,9 +51,8 @@ export function buildPrompt(designName?: string, domainName?: string): string {
   const design = designName || activeDesign()
   const domain = domainName || activeDomain()
 
-  // Layer 1 — SKILL.md (with dynamic slide-type table injected)
-  let coreSkill = readFileSync(SKILL_MD_PATH, "utf-8")
-  coreSkill = injectSlideTypes(coreSkill)
+  // Layer 1 — SKILL.md
+  const coreSkill = readFileSync(SKILL_MD_PATH, "utf-8")
 
   // Check for preview.html
   const designDir = join(DESIGNS_DIR, design)
@@ -121,13 +105,14 @@ export function buildPrompt(designName?: string, domainName?: string): string {
  * Build the design layer text.
  *
  * If the DESIGN.md has markers:
- *   - Always include @section:global
- *   - Always include @section:layouts (layout primitives — always needed)
- *   - Include a generated Component Index table (lightweight catalog)
- *   - Omit @section:components detail, @section:charts, @section:guide
+ *   - Always include @design:foundation (colors, fonts, CSS, JS, HTML skeleton)
+ *   - Always include @design:rules (composition rules, do/don't — always resident)
+ *   - Always include generated Layout Index (with QA column)
+ *   - Always include generated Component Index
+ *   - Omit individual layout details, component details, @design:chart-rules
  *     (available on demand via revela-designs tool)
  *
- * If no markers: return the full DESIGN.md body unchanged.
+ * If no markers: return the full DESIGN.md body unchanged (backward compat).
  */
 function buildDesignLayer(designName: string): string {
   const mdPath = join(DESIGNS_DIR, designName, "DESIGN.md")
@@ -137,7 +122,7 @@ function buildDesignLayer(designName: string): string {
 
   const raw = readFileSync(mdPath, "utf-8")
   const { body } = parseFrontmatter(raw)
-  const { sections, components, hasMarkers } = parseDesignSections(body)
+  const { sections, layouts, components, hasMarkers } = parseDesignSections(body)
 
   if (!hasMarkers) {
     // Backward-compatible: full text injection
@@ -146,23 +131,29 @@ function buildDesignLayer(designName: string): string {
 
   const layerParts: string[] = []
 
-  // 1. Global section (colors, typography, CSS, JS class, HTML structure)
-  if (sections["global"]) {
-    layerParts.push(sections["global"])
+  // 1. Foundation section (colors, typography, CSS vars, JS, HTML skeleton)
+  if (sections["foundation"]) {
+    layerParts.push(sections["foundation"])
+  }
+
+  // 2. Rules section (composition rules, do/don't — always resident)
+  if (sections["rules"]) {
+    layerParts.push(sections["rules"])
   }
 
-  // 2. Component Index — compact catalog
-  const index = generateComponentIndex(components)
-  if (index) {
-    layerParts.push(index)
+  // 3. Layout Index — compact catalog with QA column
+  const layoutIndex = generateLayoutIndex(layouts)
+  if (layoutIndex) {
+    layerParts.push(layoutIndex)
   }
 
-  // 3. Layouts section — always resident (needed for every slide)
-  if (sections["layouts"]) {
-    layerParts.push(sections["layouts"])
+  // 4. Component Index — compact catalog
+  const componentIndex = generateComponentIndex(components)
+  if (componentIndex) {
+    layerParts.push(componentIndex)
   }
 
-  // 4. On-demand note
+  // 5. On-demand note
   layerParts.push(
     [
       "### On-Demand Design Sections",
@@ -172,23 +163,11 @@ function buildDesignLayer(designName: string): string {
       "",
       "| Section | Fetch with |",
       "|---|---|",
+      "| Layout HTML/CSS details | `layout: \"<name>\"` (see Layout Index above) |",
       "| Component CSS/HTML details | `component: \"<name>\"` (see Component Index above) |",
-      "| Data Visualization (ECharts) | `section: \"charts\"` |",
-      "| Composition Guide & Do/Don't | `section: \"guide\"` |",
+      "| Data Visualization (ECharts) | `section: \"chart-rules\"` |",
     ].join("\n"),
   )
 
   return layerParts.join("\n\n---\n\n")
 }
-
-/**
- * Replace the <!-- @slide-types --> placeholder in SKILL.md with a generated
- * markdown table built from SLIDE_TYPES (single source of truth in checks.ts).
- */
-function injectSlideTypes(skillMd: string): string {
-  const rows = SLIDE_TYPES.map(
-    (t) => `| \`${t}\` | ${SLIDE_TYPE_DESCRIPTIONS[t]} |`,
-  )
-  const table = ["| Value | Use for |", "|-------|---------|", ...rows].join("\n")
-  return skillMd.replace("<!-- @slide-types -->", table)
-}