npm - agent-reader - Versions diffs - 1.1.4 → 1.1.5 - Mend

agent-reader 1.1.4 → 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 (7) hide show

package/CHANGELOG.md +9 -1
package/README.md +112 -182
package/SKILL.md +190 -28
package/bin/agent-reader.js +1 -1
package/openclaw-skill/SKILL.md +190 -28
package/package.json +1 -1
package/src/mcp/server.js +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -1,6 +1,14 @@
 # Changelog
-## 1.1.3 - 2026-03-14
+## 1.1.5 - 2026-03-15
+- Restructured README: OpenClaw/Agent integration first, manual CLI second.
+- Rewrote SKILL.md with detailed OpenClaw integration guide, usage examples, error handling.
+- Added GitHub Actions CI (Node 18/20/22).
+- Fixed CI test timeout for server tests.
+- Updated banner image.
+## 1.1.4 - 2026-03-14
 - Fixed slideshow landscape PDF crash by removing unstable in-page canvas recompression.
 - Improved custom theme error message (`theme not found`) for better novice UX.

package/README.md CHANGED Viewed

@@ -2,63 +2,40 @@
 ![Agent Reader Banner](./assets/banner.png)
-[![npm version](https://img.shields.io/npm/v/agent-reader.svg)](https://www.npmjs.com/package/agent-reader)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)
-[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
+<p align="center">
+  <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>
+  <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>
+  <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>
+  <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>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-8A2BE2?style=flat-square" alt="MCP"></a>
+</p>
 AI Agent 擅长生成内容，但输出的 Markdown 对普通人不友好。Agent Reader 一键把 Markdown 变成漂亮网页、Word、PDF，还能把图片做成全屏幻灯片。
-**专为 AI Agent 时代打造的格式化引擎 — 一条命令，输出即交付。**
-## 为什么需要它
-- AI Agent 输出的 `.md` 文件，非技术用户看不懂
-- 手动复制到 Word 排版，格式全乱
-- 图片散落在文件夹里，没法像 PPT 一样展示
-Agent Reader 解决这三个问题：**一条命令，输出即交付**。
+**专为 AI Agent 时代打造的格式化引擎 — Agent 调用一次，输出即交付。**
 ## 核心能力
 | 能力 | 说明 |
 |------|------|
-| Markdown → 网页 | 带侧边目录导航、代码高亮、表格美化，可一键导出 Word/PDF |
-| Markdown → Word | 智能表格列宽、标题层级、引用块样式，打印友好 |
-| Markdown → PDF | 浏览器引擎打印，和网页视觉一致 |
-| 图片 → 幻灯片 | 全屏播放、键盘翻页、自动轮播、缩略图导航 |
-| 幻灯片 → PDF | 每张图片一页，适合存档分享 |
-## 幻灯片快速上手
-如果你有一组图片要现场展示，直接用这一条命令：
-```bash
-agent-reader slides ./my-images/
-```
-常用选项：
-```bash
-agent-reader slides ./my-images/ --auto 5
-agent-reader slides ./my-images/ --format pdf
-```
-支持格式：`png`、`jpg`、`jpeg`、`gif`、`svg`、`webp`。
-图片按自然顺序排序（例如 `1`、`2`、`10`，不是 `1`、`10`、`2`）。
-## 两种使用方式
+| 📄 Markdown → 网页 | 带侧边目录导航、代码高亮、表格美化，可一键导出 Word/PDF |
+| 📝 Markdown → Word | 智能表格列宽、标题层级、引用块样式，打印友好 |
+| 📑 Markdown → PDF | 浏览器引擎打印，和网页视觉一致 |
+| 🎞️ 图片 → 幻灯片 | 全屏播放、键盘翻页、自动轮播、缩略图导航 |
+| 📦 幻灯片 → PDF | 每张图片一页，适合存档分享 |
-**CLI** — 开发者和 Agent 通过命令行调用
-**MCP Server** — AI Agent（Claude / OpenClaw 等）通过 MCP 协议直接调用
+---
-## 安装
+## 💡 适用场景
-### 前提条件
+- 🏢 AI Agent 生成报告/方案 → 一键变成可以直接发给客户的 PDF 或 Word
+- 📄 Claude / GPT 输出的长文档 → 不用手动复制到 Word 调格式，自动排版
+- 🎨 AI 生图工具批量出图 → 一键做成全屏幻灯片，现场演示或存档分享
+- ⚙️ 团队内部 AI 工作流 → MCP 接入后 Agent 自动输出专业文档，零人工干预
-电脑上需要 Node.js 18+。终端输入 `node -v` 检查，没有去 https://nodejs.org 下载。
+---
-### 安装步骤
+## 📦 安装
 ```bash
 npm install -g agent-reader
@@ -66,119 +43,51 @@ npm install -g agent-reader
 验证：`agent-reader doctor`，全是 ✓ 就装好了。
-> 开发模式：clone 仓库后 `npm install && npm link`
-## 小白模式（推荐）
-只需记住一个命令：
-```bash
-agent-reader open 文件路径
-```
-系统按你的偏好自动处理。第一次用先设置偏好：
-```bash
-# 默认用网页打开（推荐）
-agent-reader setup --default-open web
-# 或者默认生成 Word
-agent-reader setup --default-open word
-```
-可选值：`web`、`word`、`pdf`、`ppt`。
-临时指定格式：
-```bash
-agent-reader open 报告.md --as word
-agent-reader open 报告.md --as pdf
-agent-reader open ./图片文件夹/ --as ppt --auto 5
-```
-## 日常使用
-### 预览 Markdown（自动打开浏览器）
-```bash
-agent-reader render 你的文件.md
-```
-打开后左侧有可点击目录，右上角有"导出 Word"和"导出 PDF"按钮，直接点击即可下载。
-### 换主题
-```bash
-agent-reader render 你的文件.md --theme light   # 亮色（默认）
-agent-reader render 你的文件.md --theme dark    # 暗色
-```
-### 导出 Word
-```bash
-agent-reader export 你的文件.md --format docx
-```
-### 导出 PDF
-```bash
-agent-reader export 你的文件.md --format pdf
-```
-### 图片幻灯片
-```bash
-agent-reader slides ./图片文件夹/           # 手动翻页
-agent-reader slides ./图片文件夹/ --auto 5  # 每 5 秒自动切换
-```
-支持键盘左右键、全屏、缩略图导航、目录跳转。
-### 幻灯片导出 PDF
+需要 Node.js 18+，终端输入 `node -v` 检查，没有去 https://nodejs.org 下载。
-```bash
-agent-reader slides ./图片文件夹/ --format pdf
-```
+> 开发模式：clone 仓库后 `npm install && npm link`
-每张图片一页，适合打印或分享。
+---
-### 指定输出位置
+## 🦞 OpenClaw 快速接入
-```bash
-agent-reader render 你的文件.md --out-dir ~/Desktop
-```
-### 清理临时文件
+> OpenClaw 用户？30 秒接入，立刻获得文档美化能力。
-```bash
-agent-reader clean
-```
+### 一步接入（MCP 直连）
-### 检查环境
+在你的 MCP 配置中添加：
-```bash
-agent-reader doctor
+```json
+{
+  "mcpServers": {
+    "agent-reader": {
+      "command": "npx",
+      "args": ["-y", "agent-reader", "mcp"]
+    }
+  }
+}
 ```
-## 给 AI Agent 用
+接入后你可以直接对 OpenClaw 说：
-### CLI Agent 模式
+| 你说 | OpenClaw 调用 | 结果 |
+|------|--------------|------|
+| "帮我把这个 Markdown 做成 PDF" | `export_document` | 生成 PDF 文件 |
+| "整理成 Word 发给客户" | `export_document` | 生成 DOCX 文件 |
+| "做成网页给我看看" | `render_markdown` | 生成带目录的网页 |
+| "把这些图片做成幻灯片" | `create_slideshow` | 生成全屏幻灯片 |
+| "幻灯片导出 PDF" | `export_slideshow` | 每张图一页 PDF |
+| "打开这个文件" | `open_file` | 按偏好自动处理 |
-加 `--profile agent`，输出纯 JSON：
+完整工具参数、输入输出示例、错误处理说明见 [`SKILL.md`](./SKILL.md)，OpenClaw 专用 schema 见 [`openclaw-skill/`](./openclaw-skill/)。
-```bash
-agent-reader render report.md --profile agent
-# {"path":"...","format":"html","size":12345,"warnings":[]}
+---
-agent-reader export report.md --format docx --profile agent
-# {"path":"...","format":"docx","size":8765,"warnings":[]}
-```
+## 🤖 给其他 AI Agent 用
 ### MCP Server
-兼容 Claude Desktop、OpenClaw、Cline 等所有支持 MCP 协议的 AI Agent 框架。Agent 调用一次即学会"输出排版技能"。
-启动：`npm run mcp`
+兼容 Claude Desktop、Cline 等所有支持 MCP 协议的 AI Agent 框架。
 Claude Desktop 配置（`claude_desktop_config.json`）：
@@ -193,7 +102,7 @@ Claude Desktop 配置（`claude_desktop_config.json`）：
 }
 ```
-提供 7 个工具：
+提供 7 个 MCP 工具：
 | 工具 | 功能 |
 |------|------|
@@ -207,72 +116,93 @@ Claude Desktop 配置（`claude_desktop_config.json`）：
 所有工具支持 `return_content` 参数，可直接返回文件内容（适合沙箱/Docker 环境）。
-## 适用场景
+### CLI Agent 模式
-- AI Agent 生成报告/方案 → 直接交付给客户看
-- Claude / GPT 输出的长文档 → 不用手动复制到 Word 调格式
-- AI 生图工具（Nano Banana 等）批量出图 → 一键做成幻灯片展示
-- 团队内部 AI 工作流 → MCP 接入后 Agent 自动输出专业文档
+加 `--profile agent`，输出纯 JSON：
-## 技术亮点
+```bash
+agent-reader render report.md --profile agent
+# {"path":"...","format":"html","size":12345,"warnings":[]}
-- **统一视觉源**：HTML 是 PDF 的视觉基线（Puppeteer 打印），DOCX 保证结构一致
-- **智能表格列宽**：根据内容长度自动计算比例，中文不会被挤压断行
-- **安全默认**：HTML sanitize 防 XSS、CSP 策略、SSRF 防护（禁止内网 IP）
-- **零配置可用**：Pandoc 缺失自动降级、端口冲突自动递增、临时文件自动隔离
-- **双模式输出**：human 模式自动打开 + 本地服务；agent 模式纯 JSON 输出
+agent-reader export report.md --format docx --profile agent
+# {"path":"...","format":"docx","size":8765,"warnings":[]}
+```
-## 依赖说明
+---
-| 依赖 | 必需？ | 用途 |
-|------|--------|------|
-| Node.js 18+ | 是 | 运行环境 |
-| Puppeteer | 否（按需） | PDF 导出（可选依赖；未安装时仅影响 PDF） |
-| Pandoc | 否 | Word 导出更好看（没有会自动降级为纯 JS 方案） |
+## 🛠️ 手动使用（可选）
-## 云环境部署
+> 以下是人工操作 CLI 的方式。大多数情况下 Agent 会自动调用，你不需要手动敲命令。
-在 Docker/CI 中，Agent Reader 会自动检测环境并在需要时为 Puppeteer 关闭沙盒参数（`--no-sandbox` 等）。
-在部分非标准云环境里，`auto` 模式首次失败时也会自动重试一次 `no-sandbox`，减少手动排障。
+### 🐣 小白模式
-手动覆盖方式：
+只需记住一个命令：`agent-reader open 文件路径`
 ```bash
-# auto | on | off
-AGENT_READER_SANDBOX=off agent-reader export report.md --format pdf
+agent-reader setup --default-open web    # 设置默认网页打开
+agent-reader open 报告.md               # 按偏好自动处理
+agent-reader open 报告.md --as word     # 临时指定 Word
+agent-reader open ./图片文件夹/ --as ppt --auto 5
 ```
-Docker 环境建议预装 Chromium 依赖（示例）：
+### 常用命令
 ```bash
-apt-get update && apt-get install -y chromium-browser
+agent-reader render 你的文件.md              # 预览网页
+agent-reader render 你的文件.md --theme dark # 暗色主题
+agent-reader export 你的文件.md --format docx # 导出 Word
+agent-reader export 你的文件.md --format pdf  # 导出 PDF
+agent-reader slides ./图片文件夹/             # 幻灯片
+agent-reader slides ./图片文件夹/ --auto 5    # 自动轮播
+agent-reader slides ./图片文件夹/ --format pdf # 幻灯片导出 PDF
+agent-reader clean                            # 清理临时文件
+agent-reader doctor                           # 检查环境
 ```
-## FAQ：没有 Pandoc 怎么办？
+---
+## ✨ 技术亮点
-- 不装 Pandoc 也能导出 DOCX，只是排版会使用基础模式
-- 装 Pandoc 后，代码块和复杂表格的效果更稳定
+- 🎯 **统一视觉源**：HTML 是 PDF 的视觉基线（Puppeteer 打印），DOCX 保证结构一致
+- 📊 **智能表格列宽**：根据内容长度自动计算比例，中文不会被挤压断行
+- 🔒 **安全默认**：HTML sanitize 防 XSS、CSP 策略、SSRF 防护（禁止内网 IP）
+- 🚀 **零配置可用**：Pandoc 缺失自动降级、端口冲突自动递增、临时文件自动隔离
+- 🔄 **双模式输出**：human 模式自动打开 + 本地服务；agent 模式纯 JSON 输出
-常见安装命令：
+## 📋 依赖说明
+| 依赖 | 必需？ | 用途 |
+|------|--------|------|
+| Node.js 18+ | 是 | 运行环境 |
+| Puppeteer | 否（按需） | PDF 导出（可选依赖；未安装时仅影响 PDF） |
+| Pandoc | 否 | Word 导出更好看（没有会自动降级为纯 JS 方案） |
+## ☁️ 云环境部署
+在 Docker/CI 中，Agent Reader 会自动检测环境并在需要时为 Puppeteer 关闭沙盒参数。`auto` 模式首次失败时也会自动重试 `no-sandbox`。
 ```bash
-# macOS
-brew install pandoc
+# 手动覆盖：auto | on | off
+AGENT_READER_SANDBOX=off agent-reader export report.md --format pdf
+```
+## ❓ FAQ
-# Linux
-apt-get install pandoc
+### 没有 Pandoc 怎么办？
-# Windows
-winget install pandoc
-# or: choco install pandoc
-# or: scoop install pandoc
+不装也能导出 DOCX，只是排版简单一些。装了效果更好：
+```bash
+brew install pandoc        # macOS
+apt-get install pandoc     # Linux
+winget install pandoc      # Windows
 ```
-## Puppeteer 进阶安装
+### Puppeteer 太重？
-如果你已经有可用浏览器，想减少安装体积：
+可以跳过 Chromium 下载，用系统浏览器：
 ```bash
 PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install -g agent-reader
 PUPPETEER_EXECUTABLE_PATH=/path/to/chrome agent-reader export report.md --format pdf
-```
+```

package/SKILL.md CHANGED Viewed

@@ -5,45 +5,207 @@ description: 把 Markdown 渲染成漂亮网页、导出 Word/PDF、图片做幻
 # Agent Reader Skill
-## 能力
+## 你是什么
-- Markdown 渲染为可阅读网页（目录、代码高亮、表格样式）
-- 导出 PDF / DOCX 文档
-- 图片目录生成幻灯片并支持直接导出 PDF
+Agent Reader 是一个文档美化引擎。你（AI Agent）生成的 Markdown 内容，通过它可以一键变成：漂亮网页、Word 文档、PDF 文件、全屏幻灯片。
-## 触发条件
+## 能力清单
-- 用户要求把 Markdown 输出整理成可交付文档
-- 用户需要导出 Word 或 PDF
-- 用户希望把图片集合用于展示或汇报
+| 能力 | 工具 | 说明 |
+|------|------|------|
+| Markdown → 网页 | `render_markdown` | 带目录导航、代码高亮、表格美化 |
+| Markdown → PDF | `export_document` | 浏览器引擎打印，视觉一致 |
+| Markdown → Word | `export_document` | 智能表格列宽，打印友好 |
+| 图片 → 幻灯片 | `create_slideshow` | 全屏播放、键盘翻页、自动轮播 |
+| 图片 → 幻灯片 PDF/HTML | `export_slideshow` | 每张图一页，适合存档分享 |
+| 智能打开 | `open_file` | 按用户偏好自动选格式 |
-## CLI 调用
+## 什么时候该调用我
-```bash
-agent-reader render report.md
-agent-reader export report.md --format pdf
-agent-reader export report.md --format docx
-agent-reader slides ./images --auto 5
-```
+- 用户说"帮我把这个整理成文档" → `export_document`
+- 用户说"做成网页给我看看" → `render_markdown`
+- 用户说"导出 Word / PDF" → `export_document`
+- 用户说"把这些图片做成幻灯片" → `create_slideshow` 或 `export_slideshow`
+- 用户说"打开这个文件" → `open_file`
+- 用户没指定格式 → `open_file`（自动按偏好处理）
+## OpenClaw 接入方式
-## MCP 调用
+### 方式 1：MCP 直连（推荐）
-- `render_markdown`
-- `export_document`
-- `create_slideshow`
-- `export_slideshow`
-- `open_file`
+在 MCP 配置中添加：
-### MCP 参数速查
+```json
+{
+  "mcpServers": {
+    "agent-reader": {
+      "command": "npx",
+      "args": ["-y", "agent-reader", "mcp"]
+    }
+  }
+}
+```
-- `render_markdown`: `content`(必填), `source_path`, `theme`, `return_content`
-- `export_document`: `content`(必填), `format`=`pdf|docx`(必填), `source_path`, `return_content`
-- `create_slideshow`: `image_dir`(必填), `auto_play`, `return_content`
-- `export_slideshow`: `image_dir`(必填), `format`=`pdf|html`, `auto_play`, `return_content`
-- `open_file`: `file_path`(必填), `open_as`=`auto|web|word|pdf|ppt`, `theme`, `auto_play`, `return_content`
+接入后你可以直接调用下面的 MCP 工具，无需 CLI。
-## 安装
+### 方式 2：CLI 调用
 ```bash
+# 先确保已安装
 npm install -g agent-reader
+# Agent 模式输出纯 JSON
+agent-reader render report.md --profile agent --json
+agent-reader export report.md --format pdf --profile agent --json
+agent-reader export report.md --format docx --profile agent --json
+agent-reader slides ./images --profile agent --json
+agent-reader open report.md --profile agent --json
+```
+## MCP 工具详细说明
+### render_markdown — 渲染网页
+```json
+{
+  "content": "# 标题\n\n正文内容...",
+  "theme": "light",
+  "source_path": "/path/to/original.md",
+  "return_content": false
+}
+```
+返回示例：
+```json
+{
+  "html_path": "/tmp/agent-reader/render-markdown-xxx/rendered.html",
+  "format": "html",
+  "size": 12345,
+  "warnings": []
+}
 ```
+- `theme`：可选 `light`（默认）或 `dark`
+- `source_path`：如果 Markdown 里有相对路径图片，传原始文件路径
+- `return_content: true`：直接返回 HTML 字符串（适合沙箱/Docker 环境）
+### export_document — 导出 PDF / Word
+```json
+{
+  "content": "# 报告标题\n\n报告内容...",
+  "format": "pdf",
+  "source_path": "/path/to/original.md",
+  "return_content": false
+}
+```
+返回示例：
+```json
+{
+  "file_path": "/tmp/agent-reader/export-document-xxx/export.pdf",
+  "format": "pdf",
+  "size": 54321,
+  "warnings": []
+}
+```
+- `format`：必填，`pdf` 或 `docx`
+- `return_content: true`：返回 base64 编码的文件内容
+### create_slideshow — 生成幻灯片网页
+```json
+{
+  "image_dir": "/path/to/images",
+  "auto_play": 5,
+  "return_content": false
+}
+```
+返回示例：
+```json
+{
+  "html_path": "/tmp/agent-reader/create-slideshow-xxx/slideshow.html",
+  "format": "html",
+  "size": 98765,
+  "warnings": [],
+  "image_count": 12
+}
+```
+### export_slideshow — 导出幻灯片为 PDF 或 HTML
+```json
+{
+  "image_dir": "/path/to/images",
+  "format": "pdf",
+  "auto_play": 5,
+  "return_content": false
+}
+```
+返回示例：
+```json
+{
+  "file_path": "/tmp/agent-reader/export-slideshow-xxx/images.pdf",
+  "format": "pdf",
+  "size": 234567,
+  "warnings": [],
+  "image_count": 12
+}
+```
+- `format`：`pdf`（默认）或 `html`
+### open_file — 智能打开文件
+```json
+{
+  "file_path": "/path/to/report.md",
+  "open_as": "auto",
+  "theme": "light"
+}
+```
+返回示例：
+```json
+{
+  "path": "/tmp/agent-reader/open-xxx/report.html",
+  "format": "html",
+  "size": 12345,
+  "warnings": [],
+  "resolved_mode": "web"
+}
+```
+- `open_as`：`auto`（按用户偏好）、`web`、`word`、`pdf`、`ppt`
+## 错误处理
+所有工具在出错时返回统一格式：
+```json
+{
+  "error": "具体错误信息",
+  "code": "render_failed"
+}
+```
+常见错误码：
+- `render_failed` — 渲染失败（检查 Markdown 内容）
+- `export_failed` — 导出失败（PDF 需要 Puppeteer，Word 需要 Pandoc 或自动降级）
+- `slideshow_failed` — 幻灯片生成失败（检查图片目录是否存在）
+- `open_failed` — 打开失败（检查文件路径）
+## 注意事项
+1. PDF 导出需要 Puppeteer（可选依赖），未安装时会报错
+2. Word 导出没有 Pandoc 也能用，只是排版会简单一些
+3. `return_content: true` 适合沙箱环境，但大文件会自动降级为文件路径
+4. 图片路径支持 png、jpg、jpeg、gif、svg、webp

package/bin/agent-reader.js CHANGED Viewed

@@ -17,7 +17,7 @@ const program = new Command();
 program
   .name('agent-reader')
   .description('AI Agent output beautifier and slideshow generator')
-  .version('1.1.4');
+  .version('1.1.5');
 setupCommonCommandOptions(
   program

package/openclaw-skill/SKILL.md CHANGED Viewed

@@ -5,45 +5,207 @@ description: 把 Markdown 渲染成漂亮网页、导出 Word/PDF、图片做幻
 # Agent Reader Skill
-## 能力
+## 你是什么
-- Markdown 渲染为可阅读网页（目录、代码高亮、表格样式）
-- 导出 PDF / DOCX 文档
-- 图片目录生成幻灯片并支持直接导出 PDF
+Agent Reader 是一个文档美化引擎。你（AI Agent）生成的 Markdown 内容，通过它可以一键变成：漂亮网页、Word 文档、PDF 文件、全屏幻灯片。
-## 触发条件
+## 能力清单
-- 用户要求把 Markdown 输出整理成可交付文档
-- 用户需要导出 Word 或 PDF
-- 用户希望把图片集合用于展示或汇报
+| 能力 | 工具 | 说明 |
+|------|------|------|
+| Markdown → 网页 | `render_markdown` | 带目录导航、代码高亮、表格美化 |
+| Markdown → PDF | `export_document` | 浏览器引擎打印，视觉一致 |
+| Markdown → Word | `export_document` | 智能表格列宽，打印友好 |
+| 图片 → 幻灯片 | `create_slideshow` | 全屏播放、键盘翻页、自动轮播 |
+| 图片 → 幻灯片 PDF/HTML | `export_slideshow` | 每张图一页，适合存档分享 |
+| 智能打开 | `open_file` | 按用户偏好自动选格式 |
-## CLI 调用
+## 什么时候该调用我
-```bash
-agent-reader render report.md
-agent-reader export report.md --format pdf
-agent-reader export report.md --format docx
-agent-reader slides ./images --auto 5
-```
+- 用户说"帮我把这个整理成文档" → `export_document`
+- 用户说"做成网页给我看看" → `render_markdown`
+- 用户说"导出 Word / PDF" → `export_document`
+- 用户说"把这些图片做成幻灯片" → `create_slideshow` 或 `export_slideshow`
+- 用户说"打开这个文件" → `open_file`
+- 用户没指定格式 → `open_file`（自动按偏好处理）
+## OpenClaw 接入方式
-## MCP 调用
+### 方式 1：MCP 直连（推荐）
-- `render_markdown`
-- `export_document`
-- `create_slideshow`
-- `export_slideshow`
-- `open_file`
+在 MCP 配置中添加：
-### MCP 参数速查
+```json
+{
+  "mcpServers": {
+    "agent-reader": {
+      "command": "npx",
+      "args": ["-y", "agent-reader", "mcp"]
+    }
+  }
+}
+```
-- `render_markdown`: `content`(必填), `source_path`, `theme`, `return_content`
-- `export_document`: `content`(必填), `format`=`pdf|docx`(必填), `source_path`, `return_content`
-- `create_slideshow`: `image_dir`(必填), `auto_play`, `return_content`
-- `export_slideshow`: `image_dir`(必填), `format`=`pdf|html`, `auto_play`, `return_content`
-- `open_file`: `file_path`(必填), `open_as`=`auto|web|word|pdf|ppt`, `theme`, `auto_play`, `return_content`
+接入后你可以直接调用下面的 MCP 工具，无需 CLI。
-## 安装
+### 方式 2：CLI 调用
 ```bash
+# 先确保已安装
 npm install -g agent-reader
+# Agent 模式输出纯 JSON
+agent-reader render report.md --profile agent --json
+agent-reader export report.md --format pdf --profile agent --json
+agent-reader export report.md --format docx --profile agent --json
+agent-reader slides ./images --profile agent --json
+agent-reader open report.md --profile agent --json
+```
+## MCP 工具详细说明
+### render_markdown — 渲染网页
+```json
+{
+  "content": "# 标题\n\n正文内容...",
+  "theme": "light",
+  "source_path": "/path/to/original.md",
+  "return_content": false
+}
+```
+返回示例：
+```json
+{
+  "html_path": "/tmp/agent-reader/render-markdown-xxx/rendered.html",
+  "format": "html",
+  "size": 12345,
+  "warnings": []
+}
 ```
+- `theme`：可选 `light`（默认）或 `dark`
+- `source_path`：如果 Markdown 里有相对路径图片，传原始文件路径
+- `return_content: true`：直接返回 HTML 字符串（适合沙箱/Docker 环境）
+### export_document — 导出 PDF / Word
+```json
+{
+  "content": "# 报告标题\n\n报告内容...",
+  "format": "pdf",
+  "source_path": "/path/to/original.md",
+  "return_content": false
+}
+```
+返回示例：
+```json
+{
+  "file_path": "/tmp/agent-reader/export-document-xxx/export.pdf",
+  "format": "pdf",
+  "size": 54321,
+  "warnings": []
+}
+```
+- `format`：必填，`pdf` 或 `docx`
+- `return_content: true`：返回 base64 编码的文件内容
+### create_slideshow — 生成幻灯片网页
+```json
+{
+  "image_dir": "/path/to/images",
+  "auto_play": 5,
+  "return_content": false
+}
+```
+返回示例：
+```json
+{
+  "html_path": "/tmp/agent-reader/create-slideshow-xxx/slideshow.html",
+  "format": "html",
+  "size": 98765,
+  "warnings": [],
+  "image_count": 12
+}
+```
+### export_slideshow — 导出幻灯片为 PDF 或 HTML
+```json
+{
+  "image_dir": "/path/to/images",
+  "format": "pdf",
+  "auto_play": 5,
+  "return_content": false
+}
+```
+返回示例：
+```json
+{
+  "file_path": "/tmp/agent-reader/export-slideshow-xxx/images.pdf",
+  "format": "pdf",
+  "size": 234567,
+  "warnings": [],
+  "image_count": 12
+}
+```
+- `format`：`pdf`（默认）或 `html`
+### open_file — 智能打开文件
+```json
+{
+  "file_path": "/path/to/report.md",
+  "open_as": "auto",
+  "theme": "light"
+}
+```
+返回示例：
+```json
+{
+  "path": "/tmp/agent-reader/open-xxx/report.html",
+  "format": "html",
+  "size": 12345,
+  "warnings": [],
+  "resolved_mode": "web"
+}
+```
+- `open_as`：`auto`（按用户偏好）、`web`、`word`、`pdf`、`ppt`
+## 错误处理
+所有工具在出错时返回统一格式：
+```json
+{
+  "error": "具体错误信息",
+  "code": "render_failed"
+}
+```
+常见错误码：
+- `render_failed` — 渲染失败（检查 Markdown 内容）
+- `export_failed` — 导出失败（PDF 需要 Puppeteer，Word 需要 Pandoc 或自动降级）
+- `slideshow_failed` — 幻灯片生成失败（检查图片目录是否存在）
+- `open_failed` — 打开失败（检查文件路径）
+## 注意事项
+1. PDF 导出需要 Puppeteer（可选依赖），未安装时会报错
+2. Word 导出没有 Pandoc 也能用，只是排版会简单一些
+3. `return_content: true` 适合沙箱环境，但大文件会自动降级为文件路径
+4. 图片路径支持 png、jpg、jpeg、gif、svg、webp

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "agent-reader",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "AI Agent 的文档美化引擎 — 一键把 Markdown 变成漂亮网页、Word、PDF 和幻灯片",
   "main": "index.js",
   "directories": {

package/src/mcp/server.js CHANGED Viewed

@@ -76,7 +76,7 @@ async function saveHtmlResult(html, outputDir, name = 'output') {
 const server = new McpServer({
   name: 'agent-reader',
-  version: '1.1.4',
+  version: '1.1.5',
 });
 server.registerTool(