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

English | 中文

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

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

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

核心能力

💡 适用场景

• 🏢 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 免安装（推荐，零配置）

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

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

方式二：全局安装

npm install -g agent-reader

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

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

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

权限错误（EACCES）

# 方法 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 配置：

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

🦞 OpenClaw 快速接入

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

一步接入（MCP 直连）

在你的 MCP 配置中添加：

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

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

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

🤖 给其他 AI Agent 用

MCP Server

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

Claude Desktop 配置（claude_desktop_config.json）：

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

提供 7 个 MCP 工具：

所有工具支持 return_content 参数，可直接返回文件内容（适合沙箱/Docker 环境）。

CLI Agent 模式

加 --profile agent，输出纯 JSON：

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 文件路径

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

常用命令

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                           # 检查环境

✨ 技术亮点

• 🎯 统一视觉源：HTML 是 PDF 的视觉基线（Puppeteer 打印），DOCX 保证结构一致
• 📊 智能表格列宽：根据内容长度自动计算比例，中文不会被挤压断行
• 🔒 安全默认：HTML sanitize 防 XSS、CSP 策略、SSRF 防护（禁止内网 IP）
• 🚀 零配置可用：Pandoc 缺失自动降级、端口冲突自动递增、临时文件自动隔离
• 🔄 双模式输出：human 模式自动打开 + 本地服务；agent 模式纯 JSON 输出

📋 依赖说明

☁️ 云环境部署

在 Docker/CI 中，Agent Reader 会自动检测环境并在需要时为 Puppeteer 关闭沙盒参数。auto 模式首次失败时也会自动重试 no-sandbox。

# 手动覆盖：auto | on | off
AGENT_READER_SANDBOX=off agent-reader export report.md --format pdf

❓ FAQ

没有 Pandoc 怎么办？

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

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

Puppeteer 太重？

可以跳过 Chromium 下载，用系统浏览器：

PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install -g agent-reader
PUPPETEER_EXECUTABLE_PATH=/path/to/chrome agent-reader export report.md --format pdf