**[English](./README.en.md) | 中文**

# Agent Reader — AI Agent 的文档美化引擎

![Agent Reader Banner](./assets/banner.png)

<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>
  <a href="https://glama.ai/mcp/servers/ebbfijsf/agent-reader"><img src="https://glama.ai/mcp/servers/ebbfijsf/agent-reader/badges/card.svg" alt="agent-reader MCP server"></a>
</p>

AI Agent 擅长生成内容，但输出的 Markdown 对普通人不友好。Agent Reader 一键把 Markdown 变成漂亮网页、Word、PDF，还能把图片做成全屏幻灯片。

**专为 AI Agent 时代打造的格式化引擎 — Agent 调用一次，输出即交付。**

## 核心能力

| 能力 | 说明 |
|------|------|
| 📄 Markdown → 网页 | 带侧边目录导航、代码高亮、表格美化，可一键导出 Word/PDF |
| 📝 Markdown → Word | 智能表格列宽、标题层级、引用块样式，打印友好 |
| 📑 Markdown → PDF | 浏览器引擎打印，和网页视觉一致 |
| 🎞️ 图片 → 幻灯片 | 全屏播放、键盘翻页、自动轮播、缩略图导航 |
| 📦 幻灯片 → PDF | 每张图片一页，适合存档分享 |

![效果展示](./assets/demo-preview.png)

---

## 💡 适用场景

- 🏢 AI Agent 生成报告/方案 → 一键变成可以直接发给客户的 PDF 或 Word
- 📄 Claude / GPT 输出的长文档 → 不用手动复制到 Word 调格式，自动排版
- 🎨 AI 生图工具批量出图 → 一键做成全屏幻灯片，现场演示或存档分享
- ⚙️ 团队内部 AI 工作流 → MCP 接入后 Agent 自动输出专业文档，零人工干预

---

## 📦 安装

需要 Node.js 18+，终端输入 `node -v` 检查，没有去 https://nodejs.org 下载。

> AI Agent（如 Claude Code）帮你安装时，请优先使用方式一，避免权限和 PATH 问题。

### 方式一：npx 免安装（推荐，零配置）

```bash
npx agent-reader doctor              # 验证环境
npx agent-reader open README.md      # 立刻看到漂亮网页
```

不需要全局安装，不会遇到权限和 PATH 问题，拿来就用。

### 方式二：全局安装

```bash
npm install -g agent-reader
```

安装后验证：`agent-reader doctor`，全是 ✓ 就装好了。

> 开发模式：clone 仓库后 `npm install && npm link`

遇到问题？以下是两个最常见的坑：

**权限错误（EACCES）**

```bash
# 方法 1：加 sudo（简单粗暴）
sudo npm install -g agent-reader

# 方法 2：改 npm 全局目录（推荐，一劳永逸）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g agent-reader
```

**安装成功但 command not found**

npm 全局 bin 目录不在 PATH 中。先查路径，再加到 shell 配置：

```bash
npm bin -g                            # 查看 npm 全局 bin 路径
# 把输出的路径加到 ~/.zshrc 或 ~/.bashrc，例如：
echo 'export PATH=$(npm bin -g):$PATH' >> ~/.zshrc
source ~/.zshrc
```

---

## 🦞 OpenClaw 快速接入

> OpenClaw 用户？30 秒接入，立刻获得文档美化能力。

### 一步接入（MCP 直连）

在你的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "agent-reader": {
      "command": "npx",
      "args": ["-y", "agent-reader", "mcp"]
    }
  }
}
```

接入后你可以直接对 OpenClaw 说：

| 你说 | OpenClaw 调用 | 结果 |
|------|--------------|------|
| "帮我把这个 Markdown 做成 PDF" | `export_document` | 生成 PDF 文件 |
| "整理成 Word 发给客户" | `export_document` | 生成 DOCX 文件 |
| "做成网页给我看看" | `render_markdown` | 生成带目录的网页 |
| "把这些图片做成幻灯片" | `create_slideshow` | 生成全屏幻灯片 |
| "幻灯片导出 PDF" | `export_slideshow` | 每张图一页 PDF |
| "打开这个文件" | `open_file` | 按偏好自动处理 |

完整工具参数、输入输出示例、错误处理说明见 [`SKILL.md`](./SKILL.md)，OpenClaw 专用 schema 见 [`openclaw-skill/`](./openclaw-skill/)。

---

## 🤖 给其他 AI Agent 用

### MCP Server

兼容 Claude Desktop、Cline 等所有支持 MCP 协议的 AI Agent 框架。

Claude Desktop 配置（`claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "agent-reader": {
      "command": "node",
      "args": ["/path/to/agent-reader/src/mcp/server.js"]
    }
  }
}
```

提供 7 个 MCP 工具：

| 工具 | 功能 |
|------|------|
| `render_markdown` | Markdown → 网页预览 |
| `export_document` | Markdown → PDF / Word |
| `create_slideshow` | 图片目录 → 幻灯片 |
| `export_slideshow` | 图片目录 → 幻灯片 HTML / PDF |
| `open_file` | 智能打开（按偏好自动选格式） |
| `configure_user_preferences` | 设置默认偏好 |
| `get_user_preferences` | 读取当前偏好 |

所有工具支持 `return_content` 参数，可直接返回文件内容（适合沙箱/Docker 环境）。`render_markdown` 额外支持 `pre_export`，在 MCP 文件输出路径下会在运行时默认预生成 PDF。

### CLI Agent 模式

加 `--profile agent`，输出纯 JSON：

```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":[]}
```

---

## 🛠️ 手动使用（可选）

> 以下是人工操作 CLI 的方式。大多数情况下 Agent 会自动调用，你不需要手动敲命令。

### 🐣 小白模式

只需记住一个命令：`agent-reader open 文件路径`

```bash
agent-reader setup --default-open web    # 设置默认网页打开
agent-reader open 报告.md               # 按偏好自动处理
agent-reader open 报告.md --as word     # 临时指定 Word
agent-reader open ./图片文件夹/ --as ppt --auto 5
```

### 常用命令

```bash
agent-reader render 你的文件.md              # 预览网页
agent-reader render 你的文件.md --theme dark # 暗色主题
agent-reader render 你的文件.md --pre-export pdf,docx # 网页 + 预生成 PDF/Word
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                           # 检查环境
```

### render 时预生成导出文件

`render` 默认只生成 HTML。需要让双击打开的 `file://` 页面直接提供 PDF / Word 时，可以加 `--pre-export`：

```bash
agent-reader render report.md --pre-export pdf
agent-reader render report.md --pre-export pdf,docx
```

MCP 的 `render_markdown` 在返回文件路径时，会在运行时默认预生成 PDF；如果传了 `return_content: true`，则保持原来的内联 HTML 返回，除非你显式传 `pre_export`。

---

## ✨ 技术亮点

- 🎯 **统一视觉源**：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
# 手动覆盖：auto | on | off
AGENT_READER_SANDBOX=off agent-reader export report.md --format pdf
```

## ❓ FAQ

### 没有 Pandoc 怎么办？

不装也能导出 DOCX，只是排版简单一些。装了效果更好：

```bash
brew install pandoc        # macOS
apt-get install pandoc     # Linux
winget install pandoc      # Windows
```

### 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
```