@cyber-dash-tech/revela 0.1.11 → 0.1.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +180 -91
- package/README.zh-CN.md +185 -128
- package/designs/summit/DESIGN.md +122 -55
- package/package.json +1 -1
- package/skill/SKILL.md +40 -132
package/README.zh-CN.md
CHANGED
|
@@ -2,35 +2,44 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) | **中文**
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/@cyber-dash-tech/revela)
|
|
6
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@cyber-dash-tech/revela) [](LICENSE) [](tests/) [](https://opencode.ai) [](https://bun.sh)
|
|
7
6
|
|
|
8
7
|
<p align="center">
|
|
9
8
|
<img src="assets/img/logo.png" alt="Revela" width="800" />
|
|
10
9
|
</p>
|
|
11
10
|
|
|
12
|
-
Revela
|
|
13
|
-
|
|
11
|
+
Revela 是一个 [OpenCode](https://opencode.ai) 插件，可以把你当前使用的 agent 变成 HTML 幻灯片生成器。
|
|
12
|
+
在当前会话中启用它之后，agent 可以完成调研、结构设计、HTML 写作和自动 QA，并把结果输出到 `slides/*.html`。
|
|
13
|
+
|
|
14
|
+
**[在线演示 — AI 权力转移](https://cyber-dash-tech.github.io/revela/assets/html/ai-power-shift.html)** · 一份使用 Revela 生成的 5 页投资简报。
|
|
15
|
+
|
|
16
|
+
---
|
|
14
17
|
|
|
18
|
+
## Revela 是什么
|
|
15
19
|
|
|
20
|
+
Revela 是一种工作模式，不是一个独立聊天 agent。
|
|
16
21
|
|
|
17
|
-
|
|
22
|
+
- `/revela enable` 会把演示文稿生成专用的 system prompt 注入到当前 agent
|
|
23
|
+
- prompt 由 3 层组成：核心 skill、当前 domain、当前 design
|
|
24
|
+
- agent 可以扫描工作区文件、委托网页调研、生成 HTML 幻灯片，并自动执行布局 QA
|
|
25
|
+
- design 和 domain 的切换都在本地完成，并会立即重建 active prompt
|
|
18
26
|
|
|
19
27
|
---
|
|
20
28
|
|
|
21
29
|
## 环境要求
|
|
22
30
|
|
|
23
|
-
- [OpenCode](https://opencode.ai)
|
|
24
|
-
-
|
|
25
|
-
-
|
|
31
|
+
- [OpenCode](https://opencode.ai)
|
|
32
|
+
- Bun 运行时（`bun >= 1.0.0`）
|
|
33
|
+
- [Google Chrome](https://www.google.com/chrome/) 或 Chromium，用于布局 QA 和 PDF 导出
|
|
34
|
+
- Git，用于源码安装
|
|
26
35
|
|
|
27
36
|
---
|
|
28
37
|
|
|
29
38
|
## 安装
|
|
30
39
|
|
|
31
|
-
###
|
|
40
|
+
### 标准安装
|
|
32
41
|
|
|
33
|
-
|
|
42
|
+
在 `opencode.json` 的 `plugin` 数组中加入 `@cyber-dash-tech/revela`：
|
|
34
43
|
|
|
35
44
|
```json
|
|
36
45
|
{
|
|
@@ -39,69 +48,69 @@ Revela 是一款 [OpenCode](https://opencode.ai) 插件，让 AI 成为你的PPT
|
|
|
39
48
|
}
|
|
40
49
|
```
|
|
41
50
|
|
|
42
|
-
重启 OpenCode
|
|
51
|
+
重启 OpenCode 后，插件会通过 Bun 自动安装。
|
|
43
52
|
|
|
44
|
-
|
|
53
|
+
如果想全局安装，可以把同样的 `plugin` 配置写到 `~/.config/opencode/opencode.json`。
|
|
45
54
|
|
|
46
|
-
###
|
|
55
|
+
### 本地 wrapper 安装
|
|
47
56
|
|
|
48
|
-
|
|
49
|
-
如果直接安装失败，推荐以下方式：
|
|
57
|
+
以下情况建议直接使用本地 wrapper：
|
|
50
58
|
|
|
51
|
-
|
|
59
|
+
- Bun 插件安装不稳定或被网络环境阻塞
|
|
60
|
+
- 你在中国大陆网络环境下使用 OpenCode
|
|
61
|
+
- 你希望直接运行本地源码仓库
|
|
52
62
|
|
|
53
|
-
|
|
54
|
-
# 确认 npm 镜像已配置
|
|
55
|
-
npm config get registry # 应为 https://registry.npmmirror.com/
|
|
63
|
+
源码安装方式：
|
|
56
64
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
65
|
+
```bash
|
|
66
|
+
git clone https://github.com/cyber-dash-tech/revela
|
|
67
|
+
cd revela
|
|
68
|
+
npm install
|
|
60
69
|
```
|
|
61
70
|
|
|
62
|
-
|
|
71
|
+
创建 `~/.config/opencode/plugins/revela.js`：
|
|
63
72
|
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
export { default } from "/Users/<你的用户名>/.config/opencode/node_modules/@cyber-dash-tech/revela/index.ts";
|
|
67
|
-
EOF
|
|
73
|
+
```js
|
|
74
|
+
export { default } from "/absolute/path/to/revela/index.ts";
|
|
68
75
|
```
|
|
69
76
|
|
|
70
|
-
|
|
77
|
+
如果走本地 wrapper 方案，确保 `~/.config/opencode/opencode.json` 里不要同时保留 `@cyber-dash-tech/revela` 的 `plugin` 配置，否则 OpenCode 启动时仍会尝试用 Bun 安装。
|
|
78
|
+
|
|
79
|
+
### 中国大陆网络说明
|
|
80
|
+
|
|
81
|
+
OpenCode 的 npm 插件安装依赖 Bun，而 Bun 可能不会遵循 npm mirror 配置。如果直接安装失败，优先使用上面的本地 wrapper 方案，或者先把包安装到 `~/.config/opencode/`，再手动创建本地插件入口文件。
|
|
71
82
|
|
|
72
|
-
|
|
83
|
+
---
|
|
73
84
|
|
|
74
|
-
|
|
85
|
+
## 快速开始
|
|
75
86
|
|
|
76
|
-
|
|
87
|
+
启动 OpenCode：
|
|
77
88
|
|
|
78
89
|
```bash
|
|
79
|
-
|
|
80
|
-
cd revela && npm install
|
|
90
|
+
opencode
|
|
81
91
|
```
|
|
82
92
|
|
|
83
|
-
|
|
93
|
+
在当前会话中启用 Revela：
|
|
84
94
|
|
|
85
|
-
```
|
|
86
|
-
|
|
95
|
+
```text
|
|
96
|
+
/revela enable
|
|
87
97
|
```
|
|
88
98
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
## 快速开始
|
|
99
|
+
然后直接给 agent 一个幻灯片任务，例如：
|
|
92
100
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
OPENCODE_ENABLE_EXA=1 opencode
|
|
101
|
+
```text
|
|
102
|
+
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 slides/humanoid-robotics.html.
|
|
96
103
|
```
|
|
97
104
|
|
|
98
|
-
|
|
99
|
-
```
|
|
100
|
-
/revela enable
|
|
101
|
-
```
|
|
105
|
+
如果需要，把生成好的 HTML 导出为 PDF：
|
|
102
106
|
|
|
103
|
-
|
|
107
|
+
```text
|
|
108
|
+
/revela pdf slides/humanoid-robotics.html
|
|
104
109
|
```
|
|
110
|
+
|
|
111
|
+
关闭 Revela，让当前 agent 回到普通模式：
|
|
112
|
+
|
|
113
|
+
```text
|
|
105
114
|
/revela disable
|
|
106
115
|
```
|
|
107
116
|
|
|
@@ -109,139 +118,177 @@ OPENCODE_ENABLE_EXA=1 opencode
|
|
|
109
118
|
|
|
110
119
|
## 命令
|
|
111
120
|
|
|
112
|
-
```
|
|
113
|
-
/revela
|
|
114
|
-
/revela enable
|
|
115
|
-
/revela disable
|
|
121
|
+
```text
|
|
122
|
+
/revela 显示当前状态与帮助
|
|
123
|
+
/revela enable 为当前会话启用演示文稿模式
|
|
124
|
+
/revela disable 关闭演示文稿模式
|
|
125
|
+
|
|
126
|
+
/revela designs 列出已安装 design
|
|
127
|
+
/revela designs <name> 激活某个 design
|
|
128
|
+
/revela designs-add <source> 从 URL、本地路径或 github:user/repo 安装 design
|
|
129
|
+
/revela designs-rm <name> 删除已安装 design
|
|
116
130
|
|
|
117
|
-
/revela
|
|
118
|
-
/revela
|
|
119
|
-
/revela
|
|
131
|
+
/revela domains 列出已安装 domain
|
|
132
|
+
/revela domains <name> 激活某个 domain
|
|
133
|
+
/revela domains-add <source> 从 URL、本地路径或 github:user/repo 安装 domain
|
|
134
|
+
/revela domains-rm <name> 删除已安装 domain
|
|
120
135
|
|
|
121
|
-
/revela
|
|
122
|
-
/revela domains <name> 切换领域
|
|
123
|
-
/revela domains-add <source> 从 URL、本地路径或 github:user/repo 安装领域
|
|
136
|
+
/revela pdf <file> 将 HTML deck 导出为同目录 PDF
|
|
124
137
|
```
|
|
125
138
|
|
|
126
|
-
|
|
139
|
+
所有 `/revela` 命令都在本地执行，不消耗 LLM token。
|
|
127
140
|
|
|
128
141
|
---
|
|
129
142
|
|
|
130
|
-
##
|
|
143
|
+
## 工作原理
|
|
131
144
|
|
|
132
|
-
|
|
145
|
+
启用 Revela 后，它会把一份动态生成的 prompt 追加到当前 agent 的 system prompt 中。
|
|
133
146
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
147
|
+
这份 prompt 由 3 层组成：
|
|
148
|
+
|
|
149
|
+
1. `skill/SKILL.md`：核心幻灯片生成流程
|
|
150
|
+
2. 当前 active domain：行业结构与术语
|
|
151
|
+
3. 当前 active design：视觉语言、layout、component 和图表规则
|
|
152
|
+
|
|
153
|
+
当前 design 和 domain 会持久化到 `~/.config/revela/config.json`。是否启用 Revela 则是会话级状态，不会跨会话持久化。
|
|
138
154
|
|
|
139
155
|
---
|
|
140
156
|
|
|
141
|
-
##
|
|
157
|
+
## 调研与文件摄取
|
|
142
158
|
|
|
143
|
-
|
|
159
|
+
启用 Revela 后，agent 可以使用：
|
|
144
160
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
161
|
+
- `revela-workspace-scan` 扫描工作区中的 PDF、Office 文件、CSV、Markdown 和文本文件
|
|
162
|
+
- `revela-research` 子代理抓取目标网页，并把结构化结果保存到 `researches/<topic>/`
|
|
163
|
+
- `revela-research-save` 按 research axis 写入单个 findings 文件
|
|
164
|
+
|
|
165
|
+
支持 `@` 引用和自动文本提取的文件类型：
|
|
166
|
+
|
|
167
|
+
- `.pdf`
|
|
168
|
+
- `.docx`
|
|
169
|
+
- `.pptx`
|
|
170
|
+
- `.xlsx`
|
|
150
171
|
|
|
151
|
-
|
|
172
|
+
Revela 会在主 agent 处理这些文件前，先透明地完成文本提取。
|
|
152
173
|
|
|
153
174
|
---
|
|
154
175
|
|
|
155
|
-
##
|
|
176
|
+
## 布局 QA 与合规检查
|
|
177
|
+
|
|
178
|
+
每次 agent 写入 `slides/*.html` 时，Revela 都会自动在 `1920x1080` 分辨率下运行一轮基于 Puppeteer 的 QA。
|
|
179
|
+
报告会立刻反馈给 agent，用于继续修正布局或 design compliance 问题。
|
|
180
|
+
|
|
181
|
+
当前 QA 维度如下：
|
|
182
|
+
|
|
183
|
+
| 维度 | 检查内容 |
|
|
184
|
+
|---|---|
|
|
185
|
+
| `overflow` | 元素是否超出 slide canvas |
|
|
186
|
+
| `balance` | 是否过稀、重心偏移、底部留白过大等 |
|
|
187
|
+
| `symmetry` | 并列列之间的高度或密度是否明显失衡 |
|
|
188
|
+
| `rhythm` | 垂直堆叠元素之间的间距节奏是否不稳定 |
|
|
189
|
+
| `compliance` | 是否使用了 active design 之外的 class 或新增 CSS 规则 |
|
|
190
|
+
|
|
191
|
+
每张 slide 都必须显式声明 `slide-qa="true"` 或 `slide-qa="false"`。
|
|
156
192
|
|
|
157
|
-
|
|
193
|
+
- `slide-qa="true"`：适用于内容型页面，执行完整 QA
|
|
194
|
+
- `slide-qa="false"`：适用于封面、目录、引用、总结、结尾等结构型页面
|
|
158
195
|
|
|
159
|
-
|
|
160
|
-
- **并行研究**（通过 `revela-research` 子代理）—— 抓取目标 URL，将结构化研究结果保存到 `researches/<topic>/`，主代理随后将这些结果整合到幻灯片中。
|
|
196
|
+
`compliance` 不是软建议，而是生成流程的一部分。如果 agent 发明了 design 之外的 class 或 CSS rule，QA 会直接指出并要求修正。
|
|
161
197
|
|
|
162
|
-
|
|
198
|
+
也可以手动调用 `revela-qa` 工具执行 QA。
|
|
163
199
|
|
|
164
200
|
---
|
|
165
201
|
|
|
166
|
-
##
|
|
202
|
+
## 内置 Designs
|
|
167
203
|
|
|
168
|
-
|
|
204
|
+
使用 `/revela designs <name>` 切换。
|
|
169
205
|
|
|
170
|
-
|
|
206
|
+
| 名称 | 说明 | 预览 |
|
|
207
|
+
|---|---|---|
|
|
208
|
+
| `aurora` | 深色 executive 风格，信息密度更高，适合结构化商业表达和 ECharts 数据可视化 |  |
|
|
209
|
+
| `summit` | 年报式 editorial 风格，适合图像丰富、叙事感更强的商业表达 |  |
|
|
171
210
|
|
|
172
|
-
|
|
173
|
-
|---|---|
|
|
174
|
-
| **填充率** | 内容必须占据足够的画布面积 |
|
|
175
|
-
| **底部留白** | 标记幻灯片底部的大片空白 |
|
|
176
|
-
| **溢出** | 超出画布边界的元素 |
|
|
177
|
-
| **不对称** | 并排列高度差异过大 |
|
|
178
|
-
| **密度失衡** | CSS `align-items: stretch` 列布局中隐藏的内容不平衡 |
|
|
179
|
-
| **稀疏** | 可见元素过少的幻灯片 |
|
|
211
|
+
---
|
|
180
212
|
|
|
181
|
-
|
|
213
|
+
## 内置 Domains
|
|
182
214
|
|
|
183
|
-
|
|
215
|
+
使用 `/revela domains <name>` 切换。
|
|
184
216
|
|
|
185
|
-
|
|
217
|
+
| 名称 | 说明 |
|
|
218
|
+
|---|---|
|
|
219
|
+
| `general` | 不做领域专化 |
|
|
220
|
+
| `deeptech-investment` | VC / 投资分析：市场规模、技术成熟度、护城河与投资逻辑 |
|
|
221
|
+
| `consulting` | 战略咨询：go/no-go 判断、战略设计与 belief-change 报告 |
|
|
186
222
|
|
|
187
223
|
---
|
|
188
224
|
|
|
189
|
-
##
|
|
225
|
+
## 自定义 Designs
|
|
190
226
|
|
|
191
|
-
|
|
227
|
+
自定义 design 是一个包含 `DESIGN.md` 的文件夹，文件头使用 frontmatter：
|
|
192
228
|
|
|
193
229
|
```yaml
|
|
194
230
|
---
|
|
195
231
|
name: my-design
|
|
196
232
|
description: 在 /revela designs 中显示的简短说明
|
|
197
|
-
author:
|
|
233
|
+
author: you
|
|
198
234
|
version: 1.0.0
|
|
199
235
|
---
|
|
200
236
|
```
|
|
201
237
|
|
|
202
|
-
|
|
238
|
+
文件正文定义 agent 可使用的视觉系统。
|
|
203
239
|
|
|
204
|
-
###
|
|
240
|
+
### Marker 体系
|
|
205
241
|
|
|
206
|
-
|
|
242
|
+
对于较大的 design，建议使用当前 marker 格式：
|
|
207
243
|
|
|
208
244
|
```html
|
|
209
|
-
<!-- @
|
|
210
|
-
|
|
211
|
-
<!-- @
|
|
245
|
+
<!-- @design:foundation:start -->
|
|
246
|
+
色彩、字体、CSS 变量、HTML 外壳、基础 JS...
|
|
247
|
+
<!-- @design:foundation:end -->
|
|
248
|
+
|
|
249
|
+
<!-- @design:rules:start -->
|
|
250
|
+
构图规则、正反案例、design 特定约束...
|
|
251
|
+
<!-- @design:rules:end -->
|
|
212
252
|
|
|
213
|
-
<!-- @
|
|
214
|
-
|
|
215
|
-
|
|
253
|
+
<!-- @design:layouts:start -->
|
|
254
|
+
<!-- @layout:cover:start qa=false -->
|
|
255
|
+
Layout 详情...
|
|
256
|
+
<!-- @layout:cover:end -->
|
|
216
257
|
|
|
217
|
-
<!-- @
|
|
258
|
+
<!-- @layout:two-col:start qa=true -->
|
|
259
|
+
Layout 详情...
|
|
260
|
+
<!-- @layout:two-col:end -->
|
|
261
|
+
<!-- @design:layouts:end -->
|
|
262
|
+
|
|
263
|
+
<!-- @design:components:start -->
|
|
218
264
|
<!-- @component:card:start -->
|
|
219
|
-
|
|
265
|
+
Component HTML + CSS...
|
|
220
266
|
<!-- @component:card:end -->
|
|
221
267
|
|
|
222
268
|
<!-- @component:stat-card:start -->
|
|
223
|
-
|
|
269
|
+
Component HTML + CSS...
|
|
224
270
|
<!-- @component:stat-card:end -->
|
|
225
|
-
<!-- @
|
|
226
|
-
|
|
227
|
-
<!-- @section:charts:start -->
|
|
228
|
-
ECharts / 数据可视化规范...
|
|
229
|
-
<!-- @section:charts:end -->
|
|
271
|
+
<!-- @design:components:end -->
|
|
230
272
|
|
|
231
|
-
<!-- @
|
|
232
|
-
|
|
233
|
-
<!-- @
|
|
273
|
+
<!-- @design:chart-rules:start -->
|
|
274
|
+
图表规则...
|
|
275
|
+
<!-- @design:chart-rules:end -->
|
|
234
276
|
```
|
|
235
277
|
|
|
236
|
-
|
|
278
|
+
Prompt 注入行为如下：
|
|
237
279
|
|
|
238
|
-
|
|
280
|
+
- 常驻注入：`@design:foundation`、`@design:rules`、layout index、component index
|
|
281
|
+
- 按需获取：单个 `@layout:*`、单个 `@component:*`、`@design:chart-rules`
|
|
239
282
|
|
|
240
|
-
|
|
283
|
+
如果 design 没有 marker，Revela 会退回到整份 `DESIGN.md` 全量注入。
|
|
241
284
|
|
|
242
|
-
###
|
|
285
|
+
### 给 design 作者的 compliance 说明
|
|
243
286
|
|
|
244
|
-
|
|
287
|
+
Revela 会从 design 中提取允许使用的 CSS class vocabulary，并在 QA 的 compliance 维度里做校验。如果 agent 发明了新的 class 或 CSS rule，QA 会直接报出。
|
|
288
|
+
|
|
289
|
+
### 安装自定义 Design
|
|
290
|
+
|
|
291
|
+
```text
|
|
245
292
|
/revela designs-add github:your-org/your-design
|
|
246
293
|
/revela designs-add https://example.com/my-design.zip
|
|
247
294
|
/revela designs-add ./path/to/local/design-folder
|
|
@@ -249,23 +296,33 @@ ECharts / 数据可视化规范...
|
|
|
249
296
|
|
|
250
297
|
---
|
|
251
298
|
|
|
252
|
-
##
|
|
253
|
-
|
|
254
|
-
领域为 AI 增加特定行业的报告框架、术语和结构化指导。
|
|
299
|
+
## 自定义 Domains
|
|
255
300
|
|
|
256
|
-
|
|
301
|
+
自定义 domain 是一个包含 `INDUSTRY.md` 的文件夹，frontmatter 结构与 design 类似。
|
|
257
302
|
|
|
258
|
-
```
|
|
303
|
+
```text
|
|
259
304
|
/revela domains-add github:your-org/your-domain
|
|
260
305
|
```
|
|
261
306
|
|
|
307
|
+
`INDUSTRY.md` 是为了兼容历史版本而保留的文件名。
|
|
308
|
+
|
|
309
|
+
---
|
|
310
|
+
|
|
311
|
+
## PDF 导出
|
|
312
|
+
|
|
313
|
+
把生成好的 HTML deck 导出为 PDF：
|
|
314
|
+
|
|
315
|
+
```text
|
|
316
|
+
/revela pdf slides/my-deck.html
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
Revela 会通过 Chrome / Chromium 渲染每一页 slide，并在同目录生成最终 PDF。
|
|
320
|
+
|
|
262
321
|
---
|
|
263
322
|
|
|
264
323
|
## 日志
|
|
265
324
|
|
|
266
|
-
Revela
|
|
267
|
-
|
|
268
|
-
开启详细调试输出：
|
|
325
|
+
Revela 使用 [tslog](https://tslog.js.org/) 输出结构化日志。开启详细调试输出：
|
|
269
326
|
|
|
270
327
|
```bash
|
|
271
328
|
REVELA_DEBUG=1 opencode
|
|
@@ -275,4 +332,4 @@ REVELA_DEBUG=1 opencode
|
|
|
275
332
|
|
|
276
333
|
## 许可证
|
|
277
334
|
|
|
278
|
-
MIT
|
|
335
|
+
MIT，详见 [LICENSE](LICENSE).
|