agent-reader 1.0.0

package/README.md

@@ -0,0 +1,213 @@
+# Agent Reader — AI Agent 的文档美化引擎
+
+![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)
+
+AI Agent 擅长生成内容，但输出的 Markdown 对普通人不友好。Agent Reader 一键把 Markdown 变成漂亮网页、Word、PDF，还能把图片做成全屏幻灯片。
+
+**专为 AI Agent 时代打造的格式化引擎 — 一条命令，输出即交付。**
+
+## 为什么需要它
+
+- AI Agent 输出的 `.md` 文件，非技术用户看不懂
+- 手动复制到 Word 排版，格式全乱
+- 图片散落在文件夹里，没法像 PPT 一样展示
+
+Agent Reader 解决这三个问题：**一条命令，输出即交付**。
+
+## 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| Markdown → 网页 | 带侧边目录导航、代码高亮、表格美化，可一键导出 Word/PDF |
+| Markdown → Word | 智能表格列宽、标题层级、引用块样式，打印友好 |
+| Markdown → PDF | 浏览器引擎打印，和网页视觉一致 |
+| 图片 → 幻灯片 | 全屏播放、键盘翻页、自动轮播、缩略图导航 |
+| 幻灯片 → PDF | 每张图片一页，适合存档分享 |
+
+## 两种使用方式
+
+**CLI** — 开发者和 Agent 通过命令行调用
+**MCP Server** — AI Agent（Claude / OpenClaw 等）通过 MCP 协议直接调用
+
+## 安装
+
+### 前提条件
+
+电脑上需要 Node.js 18+。终端输入 `node -v` 检查，没有去 https://nodejs.org 下载。
+
+### 安装步骤
+
+```bash
+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    # 暗色
+agent-reader render 你的文件.md --theme print   # 打印友好
+```
+
+### 导出 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
+
+```bash
+agent-reader slides ./图片文件夹/ --format pdf
+```
+
+每张图片一页，适合打印或分享。
+
+### 指定输出位置
+
+```bash
+agent-reader render 你的文件.md --out-dir ~/Desktop
+```
+
+### 清理临时文件
+
+```bash
+agent-reader clean
+```
+
+### 检查环境
+
+```bash
+agent-reader doctor
+```
+
+## 给 AI Agent 用
+
+### 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":[]}
+```
+
+### MCP Server
+
+兼容 Claude Desktop、OpenClaw、Cline 等所有支持 MCP 协议的 AI Agent 框架。Agent 调用一次即学会"输出排版技能"。
+
+启动：`npm run mcp`
+
+Claude Desktop 配置（`claude_desktop_config.json`）：
+
+```json
+{
+  "mcpServers": {
+    "agent-reader": {
+      "command": "node",
+      "args": ["/path/to/agent-reader/src/mcp/server.js"]
+    }
+  }
+}
+```
+
+提供 6 个工具：
+
+| 工具 | 功能 |
+|------|------|
+| `render_markdown` | Markdown → 网页预览 |
+| `export_document` | Markdown → PDF / Word |
+| `create_slideshow` | 图片目录 → 幻灯片 |
+| `open_file` | 智能打开（按偏好自动选格式） |
+| `configure_user_preferences` | 设置默认偏好 |
+| `get_user_preferences` | 读取当前偏好 |
+
+所有工具支持 `return_content` 参数，可直接返回文件内容（适合沙箱/Docker 环境）。
+
+## 适用场景
+
+- AI Agent 生成报告/方案 → 直接交付给客户看
+- Claude / GPT 输出的长文档 → 不用手动复制到 Word 调格式
+- AI 生图工具（Nano Banana 等）批量出图 → 一键做成幻灯片展示
+- 团队内部 AI 工作流 → MCP 接入后 Agent 自动输出专业文档
+
+## 技术亮点
+
+- **统一视觉源**：HTML 是 PDF 的视觉基线（Puppeteer 打印），DOCX 保证结构一致
+- **智能表格列宽**：根据内容长度自动计算比例，中文不会被挤压断行
+- **安全默认**：HTML sanitize 防 XSS、CSP 策略、SSRF 防护（禁止内网 IP）
+- **零配置可用**：Pandoc 缺失自动降级、端口冲突自动递增、临时文件自动隔离
+- **双模式输出**：human 模式自动打开 + 本地服务；agent 模式纯 JSON 输出
+
+## 依赖说明
+
+| 依赖 | 必需？ | 用途 |
+|------|--------|------|
+| Node.js 18+ | 是 | 运行环境 |
+| Puppeteer | 是 | PDF 导出（安装时自动下载 Chromium） |
+| Pandoc | 否 | Word 导出更好看（没有会自动降级为纯 JS 方案） |

package/bin/agent-reader.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import {
+  cleanCommand,
+  doctorCommand,
+  exportCommand,
+  openCommand,
+  renderCommand,
+  runCommandSafely,
+  setupCommand,
+  setupCommonCommandOptions,
+  slidesCommand,
+} from '../src/cli/commands.js';
+
+const program = new Command();
+program
+  .name('agent-reader')
+  .description('AI Agent output beautifier and slideshow generator')
+  .version('0.1.0');
+
+setupCommonCommandOptions(
+  program
+    .command('render [file]')
+    .description('Render Markdown to beautiful HTML')
+    .action((file, options) => runCommandSafely(() => renderCommand(file, options))),
+);
+
+setupCommonCommandOptions(
+  program
+    .command('export [file]')
+    .description('Export Markdown to PDF or DOCX')
+    .requiredOption('--format <format>', 'output format: pdf|docx')
+    .option('--page-size <size>', 'PDF page size: A4|Letter|A3', 'A4')
+    .action((file, options) => runCommandSafely(() => exportCommand(file, options))),
+);
+
+setupCommonCommandOptions(
+  program
+    .command('slides <dir>')
+    .description('Create slideshow HTML from image directory')
+    .option('--auto <seconds>', 'auto play interval in seconds')
+    .option('--format <format>', 'export format: pdf')
+    .option('--page-size <size>', 'PDF page size: A4|Letter|A3', 'A4')
+    .action((dir, options) => runCommandSafely(() => slidesCommand(dir, options))),
+);
+
+setupCommonCommandOptions(
+  program
+    .command('open <target>')
+    .description('Open content using preferred mode (web/word/pdf/ppt)')
+    .option('--as <mode>', 'open mode: auto|web|word|pdf|ppt', 'auto')
+    .option('--auto <seconds>', 'auto play seconds for ppt mode')
+    .option('--page-size <size>', 'PDF page size: A4|Letter|A3', 'A4')
+    .action((target, options) => runCommandSafely(() => openCommand(target, options))),
+);
+
+program
+  .command('setup')
+  .description('Configure default open behavior for non-technical users')
+  .option('--profile <mode>', 'use profile: human|agent', 'human')
+  .option('--json', 'json output')
+  .option('--default-open <mode>', 'default open mode: web|word|pdf|ppt')
+  .option('--theme <name>', 'default theme for web rendering')
+  .option('--reset', 'reset to defaults')
+  .action((options) => runCommandSafely(() => setupCommand(options)));
+
+program
+  .command('doctor')
+  .description('Check runtime dependencies')
+  .option('--profile <mode>', 'use profile: human|agent', 'human')
+  .option('--json', 'json output')
+  .action((options) => runCommandSafely(() => doctorCommand(options)));
+
+program
+  .command('clean')
+  .description('Clean old temporary outputs')
+  .option('--profile <mode>', 'use profile: human|agent', 'human')
+  .option('--out-dir <dir>', 'output directory root')
+  .option('--json', 'json output')
+  .option('--days <days>', 'max age in days', '7')
+  .action((options) => runCommandSafely(() => cleanCommand(options)));
+
+await program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "agent-reader",
+  "version": "1.0.0",
+  "description": "AI Agent 的文档美化引擎 — 一键把 Markdown 变成漂亮网页、Word、PDF 和幻灯片",
+  "main": "index.js",
+  "directories": {
+    "test": "test"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "mcp": "node src/mcp/server.js"
+  },
+  "keywords": [
+    "markdown",
+    "ai-agent",
+    "document",
+    "pdf",
+    "docx",
+    "slideshow",
+    "mcp",
+    "renderer"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agent-reader": "./bin/agent-reader.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "commander": "^14.0.3",
+    "docx": "^9.6.1",
+    "execa": "^9.6.1",
+    "github-markdown-css": "^5.9.0",
+    "highlight.js": "^11.11.1",
+    "markdown-it": "^14.1.1",
+    "open": "^11.0.0",
+    "sanitize-html": "^2.17.1",
+    "swiper": "^12.1.2",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "puppeteer": "^24.39.0"
+  }
+}