agent-reader 1.1.3 → 1.1.5

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.
Files changed (10) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +113 -182
  3. package/SKILL.md +192 -21
  4. package/bin/agent-reader.js +1 -1
  5. package/openclaw-skill/SKILL.md +192 -21
  6. package/openclaw-skill/schema.json +68 -0
  7. package/package.json +1 -1
  8. package/src/core/renderer.js +9 -1
  9. package/src/mcp/server.js +109 -1
  10. package/src/mcp/toolSchemas.js +9 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,30 @@
1
+ # Changelog
2
+
3
+ ## 1.1.5 - 2026-03-15
4
+
5
+ - Restructured README: OpenClaw/Agent integration first, manual CLI second.
6
+ - Rewrote SKILL.md with detailed OpenClaw integration guide, usage examples, error handling.
7
+ - Added GitHub Actions CI (Node 18/20/22).
8
+ - Fixed CI test timeout for server tests.
9
+ - Updated banner image.
10
+
11
+ ## 1.1.4 - 2026-03-14
12
+
13
+ - Fixed slideshow landscape PDF crash by removing unstable in-page canvas recompression.
14
+ - Improved custom theme error message (`theme not found`) for better novice UX.
15
+ - Added MCP `export_slideshow` tool to export image directories directly to HTML/PDF.
16
+ - Expanded OpenClaw skill docs/schema to include slideshow export tool and parameter hints.
17
+
18
+ ## 1.1.2 - 2026-03-14
19
+
20
+ - Added auto fallback retry (`--no-sandbox`) for PDF export in `sandbox=auto` mode.
21
+
22
+ ## 1.1.1 - 2026-03-14
23
+
24
+ - Fixed PDF export stability (`networkidle0` to `domcontentloaded` + font/image readiness wait).
25
+ - Registered `mcp` command in CLI.
26
+ - Fixed stdin TTY handling.
27
+
28
+ ## 1.1.0 - 2026-03-14
29
+
30
+ - Implemented v2 plan: sandbox modes, DOCX fallback quality upgrades, path guard, skill/schema packaging, tests, and docs updates.
package/README.md CHANGED
@@ -2,63 +2,40 @@
2
2
 
3
3
  ![Agent Reader Banner](./assets/banner.png)
4
4
 
5
- [![npm version](https://img.shields.io/npm/v/agent-reader.svg)](https://www.npmjs.com/package/agent-reader)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
- [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)
8
- [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
5
+ <p align="center">
6
+ <a href="https://www.npmjs.com/package/agent-reader"><img src="https://img.shields.io/npm/v/agent-reader.svg?style=flat-square&color=cb3837" alt="npm version"></a>
7
+ <a href="https://github.com/ebbfijsf/agent-reader/actions"><img src="https://img.shields.io/github/actions/workflow/status/ebbfijsf/agent-reader/ci.yml?style=flat-square&label=CI" alt="CI"></a>
8
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT"></a>
9
+ <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js"></a>
10
+ <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-8A2BE2?style=flat-square" alt="MCP"></a>
11
+ </p>
9
12
 
10
13
  AI Agent 擅长生成内容，但输出的 Markdown 对普通人不友好。Agent Reader 一键把 Markdown 变成漂亮网页、Word、PDF，还能把图片做成全屏幻灯片。
11
14
 
12
- **专为 AI Agent 时代打造的格式化引擎 — 一条命令，输出即交付。**
13
-
14
- ## 为什么需要它
15
-
16
- - AI Agent 输出的 `.md` 文件，非技术用户看不懂
17
- - 手动复制到 Word 排版，格式全乱
18
- - 图片散落在文件夹里，没法像 PPT 一样展示
19
-
20
- Agent Reader 解决这三个问题：**一条命令，输出即交付**。
15
+ **专为 AI Agent 时代打造的格式化引擎 — Agent 调用一次，输出即交付。**
21
16
 
22
17
  ## 核心能力
23
18
 
24
19
  | 能力 | 说明 |
25
20
  |------|------|
26
- | Markdown → 网页 | 带侧边目录导航、代码高亮、表格美化，可一键导出 Word/PDF |
27
- | Markdown → Word | 智能表格列宽、标题层级、引用块样式，打印友好 |
28
- | Markdown → PDF | 浏览器引擎打印，和网页视觉一致 |
29
- | 图片 → 幻灯片 | 全屏播放、键盘翻页、自动轮播、缩略图导航 |
30
- | 幻灯片 → PDF | 每张图片一页，适合存档分享 |
31
-
32
- ## 幻灯片快速上手
33
-
34
- 如果你有一组图片要现场展示，直接用这一条命令：
35
-
36
- ```bash
37
- agent-reader slides ./my-images/
38
- ```
39
-
40
- 常用选项：
41
-
42
- ```bash
43
- agent-reader slides ./my-images/ --auto 5
44
- agent-reader slides ./my-images/ --format pdf
45
- ```
46
-
47
- 支持格式：`png`、`jpg`、`jpeg`、`gif`、`svg`、`webp`。
48
- 图片按自然顺序排序（例如 `1`、`2`、`10`，不是 `1`、`10`、`2`）。
49
-
50
- ## 两种使用方式
21
+ | 📄 Markdown → 网页 | 带侧边目录导航、代码高亮、表格美化，可一键导出 Word/PDF |
22
+ | 📝 Markdown → Word | 智能表格列宽、标题层级、引用块样式，打印友好 |
23
+ | 📑 Markdown → PDF | 浏览器引擎打印，和网页视觉一致 |
24
+ | 🎞️ 图片 → 幻灯片 | 全屏播放、键盘翻页、自动轮播、缩略图导航 |
25
+ | 📦 幻灯片 → PDF | 每张图片一页，适合存档分享 |
51
26
 
52
- **CLI** — 开发者和 Agent 通过命令行调用
53
- **MCP Server** — AI Agent（Claude / OpenClaw 等）通过 MCP 协议直接调用
27
+ ---
54
28
 
55
- ## 安装
29
+ ## 💡 适用场景
56
30
 
57
- ### 前提条件
31
+ - 🏢 AI Agent 生成报告/方案 → 一键变成可以直接发给客户的 PDF 或 Word
32
+ - 📄 Claude / GPT 输出的长文档 → 不用手动复制到 Word 调格式，自动排版
33
+ - 🎨 AI 生图工具批量出图 → 一键做成全屏幻灯片，现场演示或存档分享
34
+ - ⚙️ 团队内部 AI 工作流 → MCP 接入后 Agent 自动输出专业文档，零人工干预
58
35
 
59
- 电脑上需要 Node.js 18+。终端输入 `node -v` 检查，没有去 https://nodejs.org 下载。
36
+ ---
60
37
 
61
- ### 安装步骤
38
+ ## 📦 安装
62
39
 
63
40
  ```bash
64
41
  npm install -g agent-reader
@@ -66,119 +43,51 @@ npm install -g agent-reader
66
43
 
67
44
  验证：`agent-reader doctor`，全是 ✓ 就装好了。
68
45
 
69
- > 开发模式：clone 仓库后 `npm install && npm link`
70
-
71
- ## 小白模式（推荐）
72
-
73
- 只需记住一个命令：
74
-
75
- ```bash
76
- agent-reader open 文件路径
77
- ```
78
-
79
- 系统按你的偏好自动处理。第一次用先设置偏好：
80
-
81
- ```bash
82
- # 默认用网页打开（推荐）
83
- agent-reader setup --default-open web
84
-
85
- # 或者默认生成 Word
86
- agent-reader setup --default-open word
87
- ```
88
-
89
- 可选值：`web`、`word`、`pdf`、`ppt`。
90
-
91
- 临时指定格式：
92
-
93
- ```bash
94
- agent-reader open 报告.md --as word
95
- agent-reader open 报告.md --as pdf
96
- agent-reader open ./图片文件夹/ --as ppt --auto 5
97
- ```
98
-
99
- ## 日常使用
100
-
101
- ### 预览 Markdown（自动打开浏览器）
102
-
103
- ```bash
104
- agent-reader render 你的文件.md
105
- ```
106
-
107
- 打开后左侧有可点击目录，右上角有"导出 Word"和"导出 PDF"按钮，直接点击即可下载。
108
-
109
- ### 换主题
110
-
111
- ```bash
112
- agent-reader render 你的文件.md --theme light # 亮色（默认）
113
- agent-reader render 你的文件.md --theme dark # 暗色
114
- ```
115
-
116
- ### 导出 Word
117
-
118
- ```bash
119
- agent-reader export 你的文件.md --format docx
120
- ```
121
-
122
- ### 导出 PDF
123
-
124
- ```bash
125
- agent-reader export 你的文件.md --format pdf
126
- ```
127
-
128
- ### 图片幻灯片
129
-
130
- ```bash
131
- agent-reader slides ./图片文件夹/ # 手动翻页
132
- agent-reader slides ./图片文件夹/ --auto 5 # 每 5 秒自动切换
133
- ```
134
-
135
- 支持键盘左右键、全屏、缩略图导航、目录跳转。
46
+ 需要 Node.js 18+，终端输入 `node -v` 检查，没有去 https://nodejs.org 下载。
136
47
 
137
- ### 幻灯片导出 PDF
138
-
139
- ```bash
140
- agent-reader slides ./图片文件夹/ --format pdf
141
- ```
142
-
143
- 每张图片一页，适合打印或分享。
48
+ > 开发模式：clone 仓库后 `npm install && npm link`
144
49
 
145
- ### 指定输出位置
50
+ ---
146
51
 
147
- ```bash
148
- agent-reader render 你的文件.md --out-dir ~/Desktop
149
- ```
52
+ ## 🦞 OpenClaw 快速接入
150
53
 
151
- ### 清理临时文件
54
+ > OpenClaw 用户？30 秒接入，立刻获得文档美化能力。
152
55
 
153
- ```bash
154
- agent-reader clean
155
- ```
56
+ ### 一步接入（MCP 直连）
156
57
 
157
- ### 检查环境
58
+ 在你的 MCP 配置中添加：
158
59
 
159
- ```bash
160
- agent-reader doctor
60
+ ```json
61
+ {
62
+ "mcpServers": {
63
+ "agent-reader": {
64
+ "command": "npx",
65
+ "args": ["-y", "agent-reader", "mcp"]
66
+ }
67
+ }
68
+ }
161
69
  ```
162
70
 
163
- ## 给 AI Agent 用
71
+ 接入后你可以直接对 OpenClaw 说：
164
72
 
165
- ### CLI Agent 模式
73
+ | 你说 | OpenClaw 调用 | 结果 |
74
+ |------|--------------|------|
75
+ | "帮我把这个 Markdown 做成 PDF" | `export_document` | 生成 PDF 文件 |
76
+ | "整理成 Word 发给客户" | `export_document` | 生成 DOCX 文件 |
77
+ | "做成网页给我看看" | `render_markdown` | 生成带目录的网页 |
78
+ | "把这些图片做成幻灯片" | `create_slideshow` | 生成全屏幻灯片 |
79
+ | "幻灯片导出 PDF" | `export_slideshow` | 每张图一页 PDF |
80
+ | "打开这个文件" | `open_file` | 按偏好自动处理 |
166
81
 
167
- 加 `--profile agent`，输出纯 JSON：
82
+ 完整工具参数、输入输出示例、错误处理说明见 [`SKILL.md`](./SKILL.md)，OpenClaw 专用 schema 见 [`openclaw-skill/`](./openclaw-skill/)。
168
83
 
169
- ```bash
170
- agent-reader render report.md --profile agent
171
- # {"path":"...","format":"html","size":12345,"warnings":[]}
84
+ ---
172
85
 
173
- agent-reader export report.md --format docx --profile agent
174
- # {"path":"...","format":"docx","size":8765,"warnings":[]}
175
- ```
86
+ ## 🤖 给其他 AI Agent 用
176
87
 
177
88
  ### MCP Server
178
89
 
179
- 兼容 Claude Desktop、OpenClaw、Cline 等所有支持 MCP 协议的 AI Agent 框架。Agent 调用一次即学会"输出排版技能"。
180
-
181
- 启动：`npm run mcp`
90
+ 兼容 Claude Desktop、Cline 等所有支持 MCP 协议的 AI Agent 框架。
182
91
 
183
92
  Claude Desktop 配置（`claude_desktop_config.json`）：
184
93
 
@@ -193,85 +102,107 @@ Claude Desktop 配置（`claude_desktop_config.json`）：
193
102
  }
194
103
  ```
195
104
 
196
- 提供 6 个工具：
105
+ 提供 7 个 MCP 工具：
197
106
 
198
107
  | 工具 | 功能 |
199
108
  |------|------|
200
109
  | `render_markdown` | Markdown → 网页预览 |
201
110
  | `export_document` | Markdown → PDF / Word |
202
111
  | `create_slideshow` | 图片目录 → 幻灯片 |
112
+ | `export_slideshow` | 图片目录 → 幻灯片 HTML / PDF |
203
113
  | `open_file` | 智能打开（按偏好自动选格式） |
204
114
  | `configure_user_preferences` | 设置默认偏好 |
205
115
  | `get_user_preferences` | 读取当前偏好 |
206
116
 
207
117
  所有工具支持 `return_content` 参数，可直接返回文件内容（适合沙箱/Docker 环境）。
208
118
 
209
- ## 适用场景
119
+ ### CLI Agent 模式
210
120
 
211
- - AI Agent 生成报告/方案 → 直接交付给客户看
212
- - Claude / GPT 输出的长文档 → 不用手动复制到 Word 调格式
213
- - AI 生图工具（Nano Banana 等）批量出图 → 一键做成幻灯片展示
214
- - 团队内部 AI 工作流 → MCP 接入后 Agent 自动输出专业文档
121
+ 加 `--profile agent`，输出纯 JSON：
215
122
 
216
- ## 技术亮点
123
+ ```bash
124
+ agent-reader render report.md --profile agent
125
+ # {"path":"...","format":"html","size":12345,"warnings":[]}
217
126
 
218
- - **统一视觉源**：HTML 是 PDF 的视觉基线（Puppeteer 打印），DOCX 保证结构一致
219
- - **智能表格列宽**：根据内容长度自动计算比例，中文不会被挤压断行
220
- - **安全默认**：HTML sanitize 防 XSS、CSP 策略、SSRF 防护（禁止内网 IP）
221
- - **零配置可用**：Pandoc 缺失自动降级、端口冲突自动递增、临时文件自动隔离
222
- - **双模式输出**：human 模式自动打开 + 本地服务；agent 模式纯 JSON 输出
127
+ agent-reader export report.md --format docx --profile agent
128
+ # {"path":"...","format":"docx","size":8765,"warnings":[]}
129
+ ```
223
130
 
224
- ## 依赖说明
131
+ ---
225
132
 
226
- | 依赖 | 必需？ | 用途 |
227
- |------|--------|------|
228
- | Node.js 18+ | 是 | 运行环境 |
229
- | Puppeteer | 是 | PDF 导出（安装时自动下载 Chromium） |
230
- | Pandoc | 否 | Word 导出更好看（没有会自动降级为纯 JS 方案） |
133
+ ## 🛠️ 手动使用（可选）
231
134
 
232
- ## 云环境部署
135
+ > 以下是人工操作 CLI 的方式。大多数情况下 Agent 会自动调用，你不需要手动敲命令。
233
136
 
234
- 在 Docker/CI 中，Agent Reader 会自动检测环境并在需要时为 Puppeteer 关闭沙盒参数（`--no-sandbox` 等）。
235
- 在部分非标准云环境里，`auto` 模式首次失败时也会自动重试一次 `no-sandbox`，减少手动排障。
137
+ ### 🐣 小白模式
236
138
 
237
- 手动覆盖方式：
139
+ 只需记住一个命令：`agent-reader open 文件路径`
238
140
 
239
141
  ```bash
240
- # auto | on | off
241
- AGENT_READER_SANDBOX=off agent-reader export report.md --format pdf
142
+ agent-reader setup --default-open web # 设置默认网页打开
143
+ agent-reader open 报告.md # 按偏好自动处理
144
+ agent-reader open 报告.md --as word # 临时指定 Word
145
+ agent-reader open ./图片文件夹/ --as ppt --auto 5
242
146
  ```
243
147
 
244
- Docker 环境建议预装 Chromium 依赖（示例）：
148
+ ### 常用命令
245
149
 
246
150
  ```bash
247
- apt-get update && apt-get install -y chromium-browser
151
+ agent-reader render 你的文件.md # 预览网页
152
+ agent-reader render 你的文件.md --theme dark # 暗色主题
153
+ agent-reader export 你的文件.md --format docx # 导出 Word
154
+ agent-reader export 你的文件.md --format pdf # 导出 PDF
155
+ agent-reader slides ./图片文件夹/ # 幻灯片
156
+ agent-reader slides ./图片文件夹/ --auto 5 # 自动轮播
157
+ agent-reader slides ./图片文件夹/ --format pdf # 幻灯片导出 PDF
158
+ agent-reader clean # 清理临时文件
159
+ agent-reader doctor # 检查环境
248
160
  ```
249
161
 
250
- ## FAQ：没有 Pandoc 怎么办？
162
+ ---
163
+
164
+ ## ✨ 技术亮点
251
165
 
252
- - 不装 Pandoc 也能导出 DOCX，只是排版会使用基础模式
253
- - 装 Pandoc 后，代码块和复杂表格的效果更稳定
166
+ - 🎯 **统一视觉源**：HTML 是 PDF 的视觉基线（Puppeteer 打印），DOCX 保证结构一致
167
+ - 📊 **智能表格列宽**：根据内容长度自动计算比例，中文不会被挤压断行
168
+ - 🔒 **安全默认**：HTML sanitize 防 XSS、CSP 策略、SSRF 防护（禁止内网 IP）
169
+ - 🚀 **零配置可用**：Pandoc 缺失自动降级、端口冲突自动递增、临时文件自动隔离
170
+ - 🔄 **双模式输出**：human 模式自动打开 + 本地服务；agent 模式纯 JSON 输出
254
171
 
255
- 常见安装命令：
172
+ ## 📋 依赖说明
173
+
174
+ | 依赖 | 必需？ | 用途 |
175
+ |------|--------|------|
176
+ | Node.js 18+ | 是 | 运行环境 |
177
+ | Puppeteer | 否（按需） | PDF 导出（可选依赖；未安装时仅影响 PDF） |
178
+ | Pandoc | 否 | Word 导出更好看（没有会自动降级为纯 JS 方案） |
179
+
180
+ ## ☁️ 云环境部署
181
+
182
+ 在 Docker/CI 中，Agent Reader 会自动检测环境并在需要时为 Puppeteer 关闭沙盒参数。`auto` 模式首次失败时也会自动重试 `no-sandbox`。
256
183
 
257
184
  ```bash
258
- # macOS
259
- brew install pandoc
185
+ # 手动覆盖：auto | on | off
186
+ AGENT_READER_SANDBOX=off agent-reader export report.md --format pdf
187
+ ```
188
+
189
+ ## ❓ FAQ
260
190
 
261
- # Linux
262
- apt-get install pandoc
191
+ ### 没有 Pandoc 怎么办？
263
192
 
264
- # Windows
265
- winget install pandoc
266
- # or: choco install pandoc
267
- # or: scoop install pandoc
193
+ 不装也能导出 DOCX，只是排版简单一些。装了效果更好：
194
+
195
+ ```bash
196
+ brew install pandoc # macOS
197
+ apt-get install pandoc # Linux
198
+ winget install pandoc # Windows
268
199
  ```
269
200
 
270
- ## Puppeteer 进阶安装
201
+ ### Puppeteer 太重？
271
202
 
272
- 如果你已经有可用浏览器，想减少安装体积：
203
+ 可以跳过 Chromium 下载，用系统浏览器：
273
204
 
274
205
  ```bash
275
206
  PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install -g agent-reader
276
207
  PUPPETEER_EXECUTABLE_PATH=/path/to/chrome agent-reader export report.md --format pdf
277
- ```
208
+ ```
package/SKILL.md CHANGED
@@ -5,36 +5,207 @@ description: 把 Markdown 渲染成漂亮网页、导出 Word/PDF、图片做幻
5
5
 
6
6
  # Agent Reader Skill
7
7
 
8
- ## 能力
8
+ ## 你是什么
9
9
 
10
- - Markdown 渲染为可阅读网页（目录、代码高亮、表格样式）
11
- - 导出 PDF / DOCX 文档
12
- - 图片目录生成幻灯片并支持导出 PDF
10
+ Agent Reader 是一个文档美化引擎。你（AI Agent）生成的 Markdown 内容，通过它可以一键变成：漂亮网页、Word 文档、PDF 文件、全屏幻灯片。
13
11
 
14
- ## 触发条件
12
+ ## 能力清单
15
13
 
16
- - 用户要求把 Markdown 输出整理成可交付文档
17
- - 用户需要导出 Word 或 PDF
18
- - 用户希望把图片集合用于展示或汇报
14
+ | 能力 | 工具 | 说明 |
15
+ |------|------|------|
16
+ | Markdown → 网页 | `render_markdown` | 带目录导航、代码高亮、表格美化 |
17
+ | Markdown → PDF | `export_document` | 浏览器引擎打印，视觉一致 |
18
+ | Markdown → Word | `export_document` | 智能表格列宽，打印友好 |
19
+ | 图片 → 幻灯片 | `create_slideshow` | 全屏播放、键盘翻页、自动轮播 |
20
+ | 图片 → 幻灯片 PDF/HTML | `export_slideshow` | 每张图一页，适合存档分享 |
21
+ | 智能打开 | `open_file` | 按用户偏好自动选格式 |
19
22
 
20
- ## CLI 调用
23
+ ## 什么时候该调用我
21
24
 
22
- ```bash
23
- agent-reader render report.md
24
- agent-reader export report.md --format pdf
25
- agent-reader export report.md --format docx
26
- agent-reader slides ./images --auto 5
27
- ```
25
+ - 用户说"帮我把这个整理成文档" → `export_document`
26
+ - 用户说"做成网页给我看看" → `render_markdown`
27
+ - 用户说"导出 Word / PDF" → `export_document`
28
+ - 用户说"把这些图片做成幻灯片" → `create_slideshow` 或 `export_slideshow`
29
+ - 用户说"打开这个文件" → `open_file`
30
+ - 用户没指定格式 → `open_file`（自动按偏好处理）
28
31
 
29
- ## MCP 调用
32
+ ## OpenClaw 接入方式
30
33
 
31
- - `render_markdown`
32
- - `export_document`
33
- - `create_slideshow`
34
- - `open_file`
34
+ ### 方式 1：MCP 直连（推荐）
35
35
 
36
- ## 安装
36
+ 在 MCP 配置中添加：
37
+
38
+ ```json
39
+ {
40
+ "mcpServers": {
41
+ "agent-reader": {
42
+ "command": "npx",
43
+ "args": ["-y", "agent-reader", "mcp"]
44
+ }
45
+ }
46
+ }
47
+ ```
48
+
49
+ 接入后你可以直接调用下面的 MCP 工具，无需 CLI。
50
+
51
+ ### 方式 2：CLI 调用
37
52
 
38
53
  ```bash
54
+ # 先确保已安装
39
55
  npm install -g agent-reader
56
+
57
+ # Agent 模式输出纯 JSON
58
+ agent-reader render report.md --profile agent --json
59
+ agent-reader export report.md --format pdf --profile agent --json
60
+ agent-reader export report.md --format docx --profile agent --json
61
+ agent-reader slides ./images --profile agent --json
62
+ agent-reader open report.md --profile agent --json
63
+ ```
64
+
65
+ ## MCP 工具详细说明
66
+
67
+ ### render_markdown — 渲染网页
68
+
69
+ ```json
70
+ {
71
+ "content": "# 标题\n\n正文内容...",
72
+ "theme": "light",
73
+ "source_path": "/path/to/original.md",
74
+ "return_content": false
75
+ }
76
+ ```
77
+
78
+ 返回示例：
79
+
80
+ ```json
81
+ {
82
+ "html_path": "/tmp/agent-reader/render-markdown-xxx/rendered.html",
83
+ "format": "html",
84
+ "size": 12345,
85
+ "warnings": []
86
+ }
87
+ ```
88
+
89
+ - `theme`：可选 `light`（默认）或 `dark`
90
+ - `source_path`：如果 Markdown 里有相对路径图片，传原始文件路径
91
+ - `return_content: true`：直接返回 HTML 字符串（适合沙箱/Docker 环境）
92
+
93
+ ### export_document — 导出 PDF / Word
94
+
95
+ ```json
96
+ {
97
+ "content": "# 报告标题\n\n报告内容...",
98
+ "format": "pdf",
99
+ "source_path": "/path/to/original.md",
100
+ "return_content": false
101
+ }
102
+ ```
103
+
104
+ 返回示例：
105
+
106
+ ```json
107
+ {
108
+ "file_path": "/tmp/agent-reader/export-document-xxx/export.pdf",
109
+ "format": "pdf",
110
+ "size": 54321,
111
+ "warnings": []
112
+ }
113
+ ```
114
+
115
+ - `format`：必填，`pdf` 或 `docx`
116
+ - `return_content: true`：返回 base64 编码的文件内容
117
+
118
+ ### create_slideshow — 生成幻灯片网页
119
+
120
+ ```json
121
+ {
122
+ "image_dir": "/path/to/images",
123
+ "auto_play": 5,
124
+ "return_content": false
125
+ }
40
126
  ```
127
+
128
+ 返回示例：
129
+
130
+ ```json
131
+ {
132
+ "html_path": "/tmp/agent-reader/create-slideshow-xxx/slideshow.html",
133
+ "format": "html",
134
+ "size": 98765,
135
+ "warnings": [],
136
+ "image_count": 12
137
+ }
138
+ ```
139
+
140
+ ### export_slideshow — 导出幻灯片为 PDF 或 HTML
141
+
142
+ ```json
143
+ {
144
+ "image_dir": "/path/to/images",
145
+ "format": "pdf",
146
+ "auto_play": 5,
147
+ "return_content": false
148
+ }
149
+ ```
150
+
151
+ 返回示例：
152
+
153
+ ```json
154
+ {
155
+ "file_path": "/tmp/agent-reader/export-slideshow-xxx/images.pdf",
156
+ "format": "pdf",
157
+ "size": 234567,
158
+ "warnings": [],
159
+ "image_count": 12
160
+ }
161
+ ```
162
+
163
+ - `format`：`pdf`（默认）或 `html`
164
+
165
+ ### open_file — 智能打开文件
166
+
167
+ ```json
168
+ {
169
+ "file_path": "/path/to/report.md",
170
+ "open_as": "auto",
171
+ "theme": "light"
172
+ }
173
+ ```
174
+
175
+ 返回示例：
176
+
177
+ ```json
178
+ {
179
+ "path": "/tmp/agent-reader/open-xxx/report.html",
180
+ "format": "html",
181
+ "size": 12345,
182
+ "warnings": [],
183
+ "resolved_mode": "web"
184
+ }
185
+ ```
186
+
187
+ - `open_as`：`auto`（按用户偏好）、`web`、`word`、`pdf`、`ppt`
188
+
189
+ ## 错误处理
190
+
191
+ 所有工具在出错时返回统一格式：
192
+
193
+ ```json
194
+ {
195
+ "error": "具体错误信息",
196
+ "code": "render_failed"
197
+ }
198
+ ```
199
+
200
+ 常见错误码：
201
+ - `render_failed` — 渲染失败（检查 Markdown 内容）
202
+ - `export_failed` — 导出失败（PDF 需要 Puppeteer，Word 需要 Pandoc 或自动降级）
203
+ - `slideshow_failed` — 幻灯片生成失败（检查图片目录是否存在）
204
+ - `open_failed` — 打开失败（检查文件路径）
205
+
206
+ ## 注意事项
207
+
208
+ 1. PDF 导出需要 Puppeteer（可选依赖），未安装时会报错
209
+ 2. Word 导出没有 Pandoc 也能用，只是排版会简单一些
210
+ 3. `return_content: true` 适合沙箱环境，但大文件会自动降级为文件路径
211
+ 4. 图片路径支持 png、jpg、jpeg、gif、svg、webp
package/bin/agent-reader.js CHANGED
@@ -17,7 +17,7 @@ const program = new Command();
17
17
  program
18
18
  .name('agent-reader')
19
19
  .description('AI Agent output beautifier and slideshow generator')
20
- .version('1.1.3');
20
+ .version('1.1.5');
21
21
 
22
22
  setupCommonCommandOptions(
23
23
  program
package/openclaw-skill/SKILL.md CHANGED
@@ -5,36 +5,207 @@ description: 把 Markdown 渲染成漂亮网页、导出 Word/PDF、图片做幻
5
5
 
6
6
  # Agent Reader Skill
7
7
 
8
- ## 能力
8
+ ## 你是什么
9
9
 
10
- - Markdown 渲染为可阅读网页（目录、代码高亮、表格样式）
11
- - 导出 PDF / DOCX 文档
12
- - 图片目录生成幻灯片并支持导出 PDF
10
+ Agent Reader 是一个文档美化引擎。你（AI Agent）生成的 Markdown 内容，通过它可以一键变成：漂亮网页、Word 文档、PDF 文件、全屏幻灯片。
13
11
 
14
- ## 触发条件
12
+ ## 能力清单
15
13
 
16
- - 用户要求把 Markdown 输出整理成可交付文档
17
- - 用户需要导出 Word 或 PDF
18
- - 用户希望把图片集合用于展示或汇报
14
+ | 能力 | 工具 | 说明 |
15
+ |------|------|------|
16
+ | Markdown → 网页 | `render_markdown` | 带目录导航、代码高亮、表格美化 |
17
+ | Markdown → PDF | `export_document` | 浏览器引擎打印，视觉一致 |
18
+ | Markdown → Word | `export_document` | 智能表格列宽，打印友好 |
19
+ | 图片 → 幻灯片 | `create_slideshow` | 全屏播放、键盘翻页、自动轮播 |
20
+ | 图片 → 幻灯片 PDF/HTML | `export_slideshow` | 每张图一页，适合存档分享 |
21
+ | 智能打开 | `open_file` | 按用户偏好自动选格式 |
19
22
 
20
- ## CLI 调用
23
+ ## 什么时候该调用我
21
24
 
22
- ```bash
23
- agent-reader render report.md
24
- agent-reader export report.md --format pdf
25
- agent-reader export report.md --format docx
26
- agent-reader slides ./images --auto 5
27
- ```
25
+ - 用户说"帮我把这个整理成文档" → `export_document`
26
+ - 用户说"做成网页给我看看" → `render_markdown`
27
+ - 用户说"导出 Word / PDF" → `export_document`
28
+ - 用户说"把这些图片做成幻灯片" → `create_slideshow` 或 `export_slideshow`
29
+ - 用户说"打开这个文件" → `open_file`
30
+ - 用户没指定格式 → `open_file`（自动按偏好处理）
28
31
 
29
- ## MCP 调用
32
+ ## OpenClaw 接入方式
30
33
 
31
- - `render_markdown`
32
- - `export_document`
33
- - `create_slideshow`
34
- - `open_file`
34
+ ### 方式 1：MCP 直连（推荐）
35
35
 
36
- ## 安装
36
+ 在 MCP 配置中添加：
37
+
38
+ ```json
39
+ {
40
+ "mcpServers": {
41
+ "agent-reader": {
42
+ "command": "npx",
43
+ "args": ["-y", "agent-reader", "mcp"]
44
+ }
45
+ }
46
+ }
47
+ ```
48
+
49
+ 接入后你可以直接调用下面的 MCP 工具，无需 CLI。
50
+
51
+ ### 方式 2：CLI 调用
37
52
 
38
53
  ```bash
54
+ # 先确保已安装
39
55
  npm install -g agent-reader
56
+
57
+ # Agent 模式输出纯 JSON
58
+ agent-reader render report.md --profile agent --json
59
+ agent-reader export report.md --format pdf --profile agent --json
60
+ agent-reader export report.md --format docx --profile agent --json
61
+ agent-reader slides ./images --profile agent --json
62
+ agent-reader open report.md --profile agent --json
63
+ ```
64
+
65
+ ## MCP 工具详细说明
66
+
67
+ ### render_markdown — 渲染网页
68
+
69
+ ```json
70
+ {
71
+ "content": "# 标题\n\n正文内容...",
72
+ "theme": "light",
73
+ "source_path": "/path/to/original.md",
74
+ "return_content": false
75
+ }
76
+ ```
77
+
78
+ 返回示例：
79
+
80
+ ```json
81
+ {
82
+ "html_path": "/tmp/agent-reader/render-markdown-xxx/rendered.html",
83
+ "format": "html",
84
+ "size": 12345,
85
+ "warnings": []
86
+ }
87
+ ```
88
+
89
+ - `theme`：可选 `light`（默认）或 `dark`
90
+ - `source_path`：如果 Markdown 里有相对路径图片，传原始文件路径
91
+ - `return_content: true`：直接返回 HTML 字符串（适合沙箱/Docker 环境）
92
+
93
+ ### export_document — 导出 PDF / Word
94
+
95
+ ```json
96
+ {
97
+ "content": "# 报告标题\n\n报告内容...",
98
+ "format": "pdf",
99
+ "source_path": "/path/to/original.md",
100
+ "return_content": false
101
+ }
102
+ ```
103
+
104
+ 返回示例：
105
+
106
+ ```json
107
+ {
108
+ "file_path": "/tmp/agent-reader/export-document-xxx/export.pdf",
109
+ "format": "pdf",
110
+ "size": 54321,
111
+ "warnings": []
112
+ }
113
+ ```
114
+
115
+ - `format`：必填，`pdf` 或 `docx`
116
+ - `return_content: true`：返回 base64 编码的文件内容
117
+
118
+ ### create_slideshow — 生成幻灯片网页
119
+
120
+ ```json
121
+ {
122
+ "image_dir": "/path/to/images",
123
+ "auto_play": 5,
124
+ "return_content": false
125
+ }
40
126
  ```
127
+
128
+ 返回示例：
129
+
130
+ ```json
131
+ {
132
+ "html_path": "/tmp/agent-reader/create-slideshow-xxx/slideshow.html",
133
+ "format": "html",
134
+ "size": 98765,
135
+ "warnings": [],
136
+ "image_count": 12
137
+ }
138
+ ```
139
+
140
+ ### export_slideshow — 导出幻灯片为 PDF 或 HTML
141
+
142
+ ```json
143
+ {
144
+ "image_dir": "/path/to/images",
145
+ "format": "pdf",
146
+ "auto_play": 5,
147
+ "return_content": false
148
+ }
149
+ ```
150
+
151
+ 返回示例：
152
+
153
+ ```json
154
+ {
155
+ "file_path": "/tmp/agent-reader/export-slideshow-xxx/images.pdf",
156
+ "format": "pdf",
157
+ "size": 234567,
158
+ "warnings": [],
159
+ "image_count": 12
160
+ }
161
+ ```
162
+
163
+ - `format`：`pdf`（默认）或 `html`
164
+
165
+ ### open_file — 智能打开文件
166
+
167
+ ```json
168
+ {
169
+ "file_path": "/path/to/report.md",
170
+ "open_as": "auto",
171
+ "theme": "light"
172
+ }
173
+ ```
174
+
175
+ 返回示例：
176
+
177
+ ```json
178
+ {
179
+ "path": "/tmp/agent-reader/open-xxx/report.html",
180
+ "format": "html",
181
+ "size": 12345,
182
+ "warnings": [],
183
+ "resolved_mode": "web"
184
+ }
185
+ ```
186
+
187
+ - `open_as`：`auto`（按用户偏好）、`web`、`word`、`pdf`、`ppt`
188
+
189
+ ## 错误处理
190
+
191
+ 所有工具在出错时返回统一格式：
192
+
193
+ ```json
194
+ {
195
+ "error": "具体错误信息",
196
+ "code": "render_failed"
197
+ }
198
+ ```
199
+
200
+ 常见错误码：
201
+ - `render_failed` — 渲染失败（检查 Markdown 内容）
202
+ - `export_failed` — 导出失败（PDF 需要 Puppeteer，Word 需要 Pandoc 或自动降级）
203
+ - `slideshow_failed` — 幻灯片生成失败（检查图片目录是否存在）
204
+ - `open_failed` — 打开失败（检查文件路径）
205
+
206
+ ## 注意事项
207
+
208
+ 1. PDF 导出需要 Puppeteer（可选依赖），未安装时会报错
209
+ 2. Word 导出没有 Pandoc 也能用，只是排版会简单一些
210
+ 3. `return_content: true` 适合沙箱环境，但大文件会自动降级为文件路径
211
+ 4. 图片路径支持 png、jpg、jpeg、gif、svg、webp
package/openclaw-skill/schema.json CHANGED
@@ -192,6 +192,74 @@
192
192
  ],
193
193
  "additionalProperties": true
194
194
  }
195
+ },
196
+ "export_slideshow": {
197
+ "description": "Export slideshow from an image directory into HTML or PDF",
198
+ "input": {
199
+ "type": "object",
200
+ "properties": {
201
+ "image_dir": {
202
+ "type": "string",
203
+ "description": "Absolute or relative image directory path"
204
+ },
205
+ "format": {
206
+ "type": "string",
207
+ "enum": [
208
+ "html",
209
+ "pdf"
210
+ ],
211
+ "description": "Export format, default pdf"
212
+ },
213
+ "auto_play": {
214
+ "type": "number",
215
+ "description": "Autoplay interval in seconds"
216
+ },
217
+ "return_content": {
218
+ "type": "boolean",
219
+ "description": "Return file content directly"
220
+ }
221
+ },
222
+ "required": [
223
+ "image_dir"
224
+ ],
225
+ "additionalProperties": false
226
+ },
227
+ "output": {
228
+ "type": "object",
229
+ "properties": {
230
+ "file_path": {
231
+ "type": "string"
232
+ },
233
+ "content_data": {
234
+ "type": "string"
235
+ },
236
+ "format": {
237
+ "type": "string",
238
+ "enum": [
239
+ "html",
240
+ "pdf"
241
+ ]
242
+ },
243
+ "size": {
244
+ "type": "number"
245
+ },
246
+ "warnings": {
247
+ "type": "array",
248
+ "items": {
249
+ "type": "string"
250
+ }
251
+ },
252
+ "image_count": {
253
+ "type": "number"
254
+ }
255
+ },
256
+ "required": [
257
+ "format",
258
+ "size",
259
+ "warnings"
260
+ ],
261
+ "additionalProperties": true
262
+ }
195
263
  }
196
264
  }
197
265
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-reader",
3
- "version": "1.1.3",
3
+ "version": "1.1.5",
4
4
  "description": "AI Agent 的文档美化引擎 — 一键把 Markdown 变成漂亮网页、Word、PDF 和幻灯片",
5
5
  "main": "index.js",
6
6
  "directories": {
package/src/core/renderer.js CHANGED
@@ -173,12 +173,20 @@ async function loadStyles(theme) {
173
173
  : path.resolve(themeName);
174
174
 
175
175
  const highlightCssPath = themeName === 'dark' ? HIGHLIGHT_CSS_DARK : HIGHLIGHT_CSS_LIGHT;
176
+ const customThemePromise = customThemePath
177
+ ? fs.readFile(customThemePath, 'utf8').catch((error) => {
178
+ if (error && error.code === 'ENOENT') {
179
+ throw new Error(`theme not found: ${themeName}. Use "light", "dark", or a valid CSS file path.`);
180
+ }
181
+ throw error;
182
+ })
183
+ : Promise.resolve('');
176
184
 
177
185
  const [builtInTheme, githubCss, highlightCss, customTheme = ''] = await Promise.all([
178
186
  fs.readFile(builtInThemePath, 'utf8'),
179
187
  fs.readFile(GITHUB_MARKDOWN_CSS_PATH, 'utf8'),
180
188
  fs.readFile(highlightCssPath, 'utf8'),
181
- customThemePath ? fs.readFile(customThemePath, 'utf8') : Promise.resolve(''),
189
+ customThemePromise,
182
190
  ]);
183
191
 
184
192
  const mergedCss = `${githubCss}\n${highlightCss}\n${builtInTheme}\n${TOC_BASE_CSS}\n${customTheme}`;
package/src/mcp/server.js CHANGED
@@ -63,6 +63,10 @@ function maybeTooLargePayload(textOrBase64) {
63
63
  return byteLengthOfString(textOrBase64) > MAX_CONTENT_BYTES;
64
64
  }
65
65
 
66
+ function uniqueWarnings(warnings = []) {
67
+ return [...new Set(warnings)];
68
+ }
69
+
66
70
  async function saveHtmlResult(html, outputDir, name = 'output') {
67
71
  const htmlPath = path.join(outputDir, `${name}.html`);
68
72
  await fs.writeFile(htmlPath, html, 'utf8');
@@ -72,7 +76,7 @@ async function saveHtmlResult(html, outputDir, name = 'output') {
72
76
 
73
77
  const server = new McpServer({
74
78
  name: 'agent-reader',
75
- version: '1.1.3',
79
+ version: '1.1.5',
76
80
  });
77
81
 
78
82
  server.registerTool(
@@ -253,6 +257,110 @@ server.registerTool(
253
257
  },
254
258
  );
255
259
 
260
+ server.registerTool(
261
+ 'export_slideshow',
262
+ MCP_TOOL_SCHEMAS.export_slideshow,
263
+ async ({
264
+ image_dir,
265
+ format = 'pdf',
266
+ auto_play,
267
+ return_content,
268
+ }) => {
269
+ try {
270
+ const outputDir = await createOutputDir('export-slideshow');
271
+ const wantsContent = Boolean(return_content);
272
+ const targetFormat = format === 'html' ? 'html' : 'pdf';
273
+ const slideshow = await createSlideshow(image_dir, {
274
+ autoPlay: auto_play,
275
+ inlineAll: wantsContent || targetFormat === 'pdf',
276
+ outDir: outputDir,
277
+ });
278
+ const warnings = [...(slideshow.warnings || [])];
279
+
280
+ if (targetFormat === 'html') {
281
+ const htmlPath = path.join(outputDir, 'slideshow.html');
282
+ await fs.writeFile(htmlPath, slideshow.html, 'utf8');
283
+ const fileSize = (await fs.stat(htmlPath)).size;
284
+
285
+ if (wantsContent) {
286
+ if (!maybeTooLargePayload(slideshow.html)) {
287
+ return toTextResult({
288
+ content_data: slideshow.html,
289
+ format: 'html',
290
+ size: byteLengthOfString(slideshow.html),
291
+ warnings: uniqueWarnings(warnings),
292
+ image_count: slideshow.imageCount,
293
+ });
294
+ }
295
+
296
+ return toTextResult({
297
+ file_path: htmlPath,
298
+ format: 'html',
299
+ size: fileSize,
300
+ warnings: uniqueWarnings([...warnings, 'content_too_large']),
301
+ image_count: slideshow.imageCount,
302
+ });
303
+ }
304
+
305
+ return toTextResult({
306
+ file_path: htmlPath,
307
+ format: 'html',
308
+ size: fileSize,
309
+ warnings: uniqueWarnings(warnings),
310
+ image_count: slideshow.imageCount,
311
+ });
312
+ }
313
+
314
+ const dirName = path.basename(path.resolve(image_dir));
315
+ const printHtmlPath = path.join(outputDir, '_print.html');
316
+ await fs.writeFile(printHtmlPath, slideshow.printHtml, 'utf8');
317
+
318
+ const pdf = await exportPDF(slideshow.printHtml, {
319
+ pageSize: 'A4',
320
+ landscape: true,
321
+ outDir: outputDir,
322
+ fileName: `${dirName}.pdf`,
323
+ htmlPath: printHtmlPath,
324
+ sandbox: MCP_SANDBOX_MODE,
325
+ });
326
+ warnings.push(...(pdf.warnings || []));
327
+
328
+ if (wantsContent) {
329
+ const fileBuffer = await fs.readFile(pdf.pdfPath);
330
+ const fileSize = fileBuffer.byteLength;
331
+ const base64 = fileBuffer.toString('base64');
332
+ if (!maybeTooLargePayload(base64)) {
333
+ return toTextResult({
334
+ content_data: base64,
335
+ format: 'pdf',
336
+ size: fileSize,
337
+ warnings: uniqueWarnings(warnings),
338
+ image_count: slideshow.imageCount,
339
+ });
340
+ }
341
+
342
+ return toTextResult({
343
+ file_path: pdf.pdfPath,
344
+ format: 'pdf',
345
+ size: fileSize,
346
+ warnings: uniqueWarnings([...warnings, 'content_too_large']),
347
+ image_count: slideshow.imageCount,
348
+ });
349
+ }
350
+
351
+ return toTextResult({
352
+ file_path: pdf.pdfPath,
353
+ format: 'pdf',
354
+ size: pdf.size,
355
+ warnings: uniqueWarnings(warnings),
356
+ image_count: slideshow.imageCount,
357
+ });
358
+ } catch (error) {
359
+ return toErrorResult(error, 'slideshow_export_failed');
360
+ }
361
+ },
362
+ );
363
+
256
364
  server.registerTool(
257
365
  'open_file',
258
366
  MCP_TOOL_SCHEMAS.open_file,
package/src/mcp/toolSchemas.js CHANGED
@@ -29,6 +29,15 @@ export const MCP_TOOL_SCHEMAS = {
29
29
  return_content: z.boolean().optional().describe('Return inline HTML content directly'),
30
30
  },
31
31
  },
32
+ export_slideshow: {
33
+ description: 'Export slideshow from an image directory into HTML or PDF',
34
+ inputSchema: {
35
+ image_dir: z.string().describe('Absolute or relative image directory path'),
36
+ format: z.enum(['html', 'pdf']).optional().describe('Export format, default pdf'),
37
+ auto_play: z.number().optional().describe('Autoplay interval in seconds'),
38
+ return_content: z.boolean().optional().describe('Return file content directly'),
39
+ },
40
+ },
32
41
  open_file: {
33
42
  description: 'Open a local file/path using user preference or explicit mode: web/word/pdf/ppt',
34
43
  inputSchema: {