@cyber-dash-tech/revela 0.3.1 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 **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-125%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-138%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" />
@@ -54,9 +54,13 @@ Restart OpenCode.
 
 To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 
+OpenCode `v1.14.22+` respects `.npmrc` settings during plugin installs, so direct installation through
+the `plugin` field should be the default path.
+
 ### Local wrapper install
 
-Use this when Bun-based plugin install is blocked, unreliable, or you want to run from a local checkout.
+Use this when direct plugin install is blocked in your environment, or when you want to run from a
+local checkout during development.
 
 ```bash
 git clone https://github.com/cyber-dash-tech/revela
@@ -72,10 +76,6 @@ export { default } from "/absolute/path/to/revela/index.ts";
 
 If you use the local wrapper route, remove any `@cyber-dash-tech/revela` entry from `opencode.json`, otherwise OpenCode may still try Bun installation.
 
-### China mainland note
-
-OpenCode's npm plugin installer uses Bun and may ignore npm mirror settings. If direct installation fails, prefer the local wrapper method.
-
 ---
 
 ## Quick Start
@@ -162,6 +162,9 @@ When Revela is enabled, the agent can use:
 - `revela-workspace-scan` to discover PDFs, Office files, CSVs, Markdown, and text files in the workspace
 - the `revela-research` subagent for targeted web research
 - `revela-research-save` to write structured findings into `researches/<topic>/`
+- `revela-research-images-list` to extract structured image candidates from `researches/<topic>/*.md`
+- `revela-media-batch-save` to batch-save selected research image leads into workspace assets
+- `revela-media-save` to turn chosen local or remote images into reusable workspace assets under `assets/<topic>/media/`
 
 Supported document extraction paths:
 
@@ -179,6 +182,39 @@ This extraction is transparent to the main agent.
 
 ---
 
+## Media Assets
+
+Research findings can record image leads in `## Images`, but those URLs are still just leads.
+Final slides should reference local workspace assets instead of remote image URLs.
+
+Use `revela-media-save` when the agent wants to promote one chosen image into a formal project asset.
+
+Current Stage 2 additions:
+
+- `revela-research-images-list` parses `## Images` sections into structured candidates
+- the primary agent can review those candidates and select a subset to use
+- `revela-media-batch-save` batch-saves the selected subset into `assets/<topic>/media/`
+- this stage is still text-driven; it does not inspect image pixels or do visual recognition
+
+Current Stage 1 behavior:
+
+- accepts either `sourcePath` for a workspace-local image or `sourceUrl` for a remote image
+- saves successful results into `assets/<topic>/media/`
+- updates `assets/<topic>/media-manifest.json`
+- records failed attempts with explicit statuses such as `invalid-url` and `cannot-download`
+- lets the agent reference the returned local path directly in final HTML
+
+Typical flow:
+
+1. `revela-research` writes image leads into `researches/<topic>/*.md`
+2. the primary agent calls `revela-research-images-list` and selects the images worth using
+3. `revela-media-batch-save` or `revela-media-save` downloads or copies them into `assets/<topic>/media/`
+4. the deck uses the returned local paths in `<img src="...">`
+
+This keeps final decks stable, offline-friendly, and independent from expiring remote URLs.
+
+---
+
 ## Layout QA And Compliance
 
 Every time the agent writes `decks/*.html`, Revela runs an automatic Puppeteer-based QA pass at `1920x1080`.
@@ -226,7 +262,18 @@ Repository design examples:
 
 ## Custom Designs
 
-A custom design is a folder containing `DESIGN.md` with frontmatter metadata:
+A custom design is a folder containing `DESIGN.md`. The folder name becomes the install target name
+unless the installer infers another name from the source.
+
+Recommended structure:
+
+```text
+my-design/
+├── DESIGN.md
+└── preview.html        optional, but recommended for humans
+```
+
+`DESIGN.md` starts with frontmatter metadata:
 
 ```yaml
 ---
@@ -237,7 +284,124 @@ version: 1.0.0
 ---
 ```
 
-For larger designs, use the marker system:
+### Minimal working example
+
+This is the smallest useful `DESIGN.md` shape. It gives the model a clear visual system, one layout,
+and one reusable component.
+
+```md
+---
+name: alpine-brief
+description: Minimal editorial design for strategy decks
+author: you
+version: 1.0.0
+---
+
+## Visual Style
+
+Apply this visual style to every slide in the deck.
+
+<!-- @design:foundation:start -->
+### Color Palette
+
+```css
+:root {
+  --bg: #f6f2ea;
+  --surface: #fffdf8;
+  --text-primary: #1c1a17;
+  --text-secondary: #625b52;
+  --accent: #8a6a45;
+  --line: rgba(28, 26, 23, 0.14);
+  --font-display: 'IBM Plex Sans Condensed', 'Inter', sans-serif;
+  --font-body: 'Inter', sans-serif;
+}
+```
+
+### Typography
+
+- Headings use `--font-display`
+- Body copy uses `--font-body`
+- Keep all sizing in fixed `px` for a `1920x1080` canvas
+
+### HTML Structure
+
+- Every slide must use `<section class="slide" slide-qa="true|false">`
+- Every slide must contain one `.slide-canvas`
+- Keep all CSS in one `<style>` block and all JS in one `<script>` block
+<!-- @design:foundation:end -->
+
+<!-- @design:rules:start -->
+### Composition Rules
+
+- Use warm off-white backgrounds and restrained brown accents
+- Prefer narrow text columns and generous whitespace
+- Avoid glow, glassmorphism, neon gradients, and dashboard styling
+<!-- @design:rules:end -->
+
+<!-- @design:layouts:start -->
+<!-- @layout:cover:start qa=false -->
+### Cover layout
+
+- Centered title stack
+- Small eyebrow at top
+- One thin accent divider under the title
+<!-- @layout:cover:end -->
+
+<!-- @layout:two-col:start qa=true -->
+### Two-column layout
+
+- Left column for argument, right column for evidence
+- Recommended split: `5 / 7`
+- Keep the left column under `520px` for readable paragraphs
+<!-- @layout:two-col:end -->
+<!-- @design:layouts:end -->
+
+<!-- @design:components:start -->
+<!-- @component:stat-card:start -->
+### Stat card (`.stat-card`)
+
+```html
+<div class="stat-card">
+  <div class="stat-label">Revenue CAGR</div>
+  <div class="stat-value">27%</div>
+  <div class="stat-note">2024-2028E</div>
+</div>
+```
+
+```css
+.stat-card {
+  border-top: 1px solid var(--line);
+  padding-top: 18px;
+}
+
+.stat-label {
+  font-size: 12px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--text-secondary);
+}
+
+.stat-value {
+  margin-top: 10px;
+  font-family: var(--font-display);
+  font-size: 72px;
+  line-height: 0.95;
+}
+
+.stat-note {
+  margin-top: 8px;
+  font-size: 16px;
+  color: var(--text-secondary);
+}
+```
+<!-- @component:stat-card:end -->
+<!-- @design:components:end -->
+```
+
+### Marker system
+
+For larger designs, use the marker system so Revela can keep the always-on prompt compact and fetch
+details only when needed:
 
 ```html
 <!-- @design:foundation:start -->
@@ -265,6 +429,26 @@ Chart rules
 <!-- @design:chart-rules:end -->
 ```
 
+Marker roles:
+
+- `@design:foundation`: core tokens, HTML skeleton, CSS foundations, typography, spacing, page framing
+- `@design:rules`: composition rules, dos and don'ts, art direction constraints, interaction rules
+- `@design:layouts`: named layout recipes such as `cover`, `toc`, `two-col`, `data-vis`
+- `@design:components`: reusable building blocks such as `card`, `stat-card`, `quote-block`
+- `@design:chart-rules`: chart-specific rules that are only needed when a slide actually uses charts
+
+Layout marker rules:
+
+- Use stable, simple names such as `cover`, `two-col`, `stats`, `timeline`
+- Add `qa=true` for dense content layouts and `qa=false` for intentionally sparse structural layouts
+- Write each layout section as a recipe: purpose, recommended structure, preferred ratios, and known constraints
+
+Component marker rules:
+
+- Include at least one concrete HTML example
+- Include the CSS class names the component depends on
+- Prefer a small vocabulary of reusable class names over many one-off classes
+
 Prompt injection behavior:
 
 - always injected: `@design:foundation`, `@design:rules`, layout index, component index
@@ -272,6 +456,13 @@ Prompt injection behavior:
 
 If a design has no markers, Revela falls back to injecting the full `DESIGN.md` body.
 
+### Practical guidance
+
+- Put the non-negotiable rules in `foundation` and `rules`; do not hide essential constraints only inside one layout
+- Keep layout names semantically meaningful; they become the vocabulary the model sees in the layout index
+- If your design defines a custom CSS class, document that class inside `DESIGN.md`; QA checks can flag classes not present in the design vocabulary
+- Add `preview.html` when possible so humans can inspect the design before activating it
+
 Install a custom design:
 
 ```text

package/README.zh-CN.md

@@ -54,9 +54,12 @@ Revela 是一种工作模式，不是独立 agent。
 
 如果想全局安装，可以把同样配置写到 `~/.config/opencode/opencode.json`。
 
+OpenCode `v1.14.22+` 在插件安装时已经会遵循 `.npmrc` 设置，因此默认应优先使用
+`plugin` 字段直接安装。
+
 ### 本地 wrapper 安装
 
-如果 Bun 安装被网络阻塞、不稳定，或者你想直接运行本地源码仓库，建议使用本地 wrapper。
+如果你的环境里直接安装仍然受阻，或者你想在开发时直接运行本地源码仓库，可以使用本地 wrapper。
 
 ```bash
 git clone https://github.com/cyber-dash-tech/revela
@@ -72,10 +75,6 @@ export { default } from "/absolute/path/to/revela/index.ts";
 
 如果使用本地 wrapper，记得把 `opencode.json` 里的 `@cyber-dash-tech/revela` `plugin` 配置删掉，否则 OpenCode 仍可能尝试用 Bun 安装。
 
-### 中国大陆网络说明
-
-OpenCode 的 npm 插件安装依赖 Bun，而 Bun 可能不会遵循 npm mirror 设置。如果直接安装失败，优先使用上面的本地 wrapper 方案。
-
 ---
 
 ## 快速开始
@@ -226,7 +225,18 @@ Create a 6-slide HTML deck on humanoid robotics supply chains. Cite the main mar
 
 ## 自定义 Designs
 
-自定义 design 是一个包含 `DESIGN.md` 的文件夹，并带有 frontmatter：
+自定义 design 本质上是一个包含 `DESIGN.md` 的文件夹。目录名通常会成为安装后的 design 名称，
+除非安装器从来源中推断出其他名称。
+
+推荐目录结构：
+
+```text
+my-design/
+├── DESIGN.md
+└── preview.html        可选，但推荐，方便人工预览
+```
+
+`DESIGN.md` 顶部使用 frontmatter：
 
 ```yaml
 ---
@@ -237,7 +247,123 @@ version: 1.0.0
 ---
 ```
 
-对于较大的 design，建议使用 marker 体系：
+### 最小可用示例
+
+下面是一个最小但可工作的 `DESIGN.md` 结构。它至少给模型提供了明确的视觉系统、一个 layout 和一个可复用 component。
+
+```md
+---
+name: alpine-brief
+description: Minimal editorial design for strategy decks
+author: you
+version: 1.0.0
+---
+
+## Visual Style
+
+Apply this visual style to every slide in the deck.
+
+<!-- @design:foundation:start -->
+### Color Palette
+
+```css
+:root {
+  --bg: #f6f2ea;
+  --surface: #fffdf8;
+  --text-primary: #1c1a17;
+  --text-secondary: #625b52;
+  --accent: #8a6a45;
+  --line: rgba(28, 26, 23, 0.14);
+  --font-display: 'IBM Plex Sans Condensed', 'Inter', sans-serif;
+  --font-body: 'Inter', sans-serif;
+}
+```
+
+### Typography
+
+- 标题使用 `--font-display`
+- 正文使用 `--font-body`
+- 所有尺寸都固定为 `px`，基于 `1920x1080` 画布设计
+
+### HTML Structure
+
+- 每张 slide 都必须使用 `<section class="slide" slide-qa="true|false">`
+- 每张 slide 内都必须有一个 `.slide-canvas`
+- 所有 CSS 放在一个 `<style>` 块里，所有 JS 放在一个 `<script>` 块里
+<!-- @design:foundation:end -->
+
+<!-- @design:rules:start -->
+### Composition Rules
+
+- 使用偏暖的浅色背景和克制的棕色强调色
+- 文字列保持偏窄，给足留白
+- 避免 glow、glassmorphism、neon gradient 和 dashboard 风格
+<!-- @design:rules:end -->
+
+<!-- @design:layouts:start -->
+<!-- @layout:cover:start qa=false -->
+### Cover layout
+
+- 居中的标题堆叠
+- 顶部有小号 eyebrow
+- 标题下方有一条细的强调色分隔线
+<!-- @layout:cover:end -->
+
+<!-- @layout:two-col:start qa=true -->
+### Two-column layout
+
+- 左列负责论点，右列负责证据
+- 推荐比例：`5 / 7`
+- 左列宽度尽量控制在 `520px` 以内，保证段落可读性
+<!-- @layout:two-col:end -->
+<!-- @design:layouts:end -->
+
+<!-- @design:components:start -->
+<!-- @component:stat-card:start -->
+### Stat card (`.stat-card`)
+
+```html
+<div class="stat-card">
+  <div class="stat-label">Revenue CAGR</div>
+  <div class="stat-value">27%</div>
+  <div class="stat-note">2024-2028E</div>
+</div>
+```
+
+```css
+.stat-card {
+  border-top: 1px solid var(--line);
+  padding-top: 18px;
+}
+
+.stat-label {
+  font-size: 12px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--text-secondary);
+}
+
+.stat-value {
+  margin-top: 10px;
+  font-family: var(--font-display);
+  font-size: 72px;
+  line-height: 0.95;
+}
+
+.stat-note {
+  margin-top: 8px;
+  font-size: 16px;
+  color: var(--text-secondary);
+}
+```
+<!-- @component:stat-card:end -->
+<!-- @design:components:end -->
+```
+
+### Marker 体系
+
+对于较大的 design，建议使用 marker 体系，这样 Revela 可以把常驻 prompt 控制在较小体积，
+只在需要时按需读取 layout / component 细节：
 
 ```html
 <!-- @design:foundation:start -->
@@ -265,6 +391,26 @@ Chart rules
 <!-- @design:chart-rules:end -->
 ```
 
+各类 marker 的职责：
+
+- `@design:foundation`：设计 token、HTML 骨架、CSS 基础、字体、间距、页面 framing
+- `@design:rules`：构图原则、do / don't、art direction 限制、交互规则
+- `@design:layouts`：具名 layout 配方，例如 `cover`、`toc`、`two-col`、`data-vis`
+- `@design:components`：可复用组件，例如 `card`、`stat-card`、`quote-block`
+- `@design:chart-rules`：只有图表页才需要的图表规范
+
+Layout marker 编写建议：
+
+- 名称保持稳定、简单，例如 `cover`、`two-col`、`stats`、`timeline`
+- 内容密集型 layout 用 `qa=true`，结构型或刻意稀疏的 layout 用 `qa=false`
+- 每个 layout 都写成配方：用途、推荐结构、推荐比例、已知约束
+
+Component marker 编写建议：
+
+- 至少提供一个具体 HTML 示例
+- 明确列出组件依赖的 CSS class 名
+- 尽量复用少量稳定 class，不要堆太多一次性 class
+
 Prompt 注入规则：
 
 - 常驻注入：`@design:foundation`、`@design:rules`、layout index、component index
@@ -272,6 +418,13 @@ Prompt 注入规则：
 
 如果 design 没有 marker，Revela 会退回到整份 `DESIGN.md` 全量注入。
 
+### 实际编写建议
+
+- 把不可妥协的规则放进 `foundation` 和 `rules`，不要只藏在某个 layout 里
+- layout 名称尽量语义化，因为模型在 layout index 里首先看到的就是这些名字
+- 如果定义了自定义 CSS class，记得在 `DESIGN.md` 里写出来；QA 会检查 design 词汇表之外的新 class
+- 如果条件允许，最好同时提供 `preview.html`，方便人工预览和验收
+
 安装自定义 design：
 
 ```text