agent-reader 1.0.0 → 1.1.0

package/README.md

@@ -29,6 +29,24 @@ Agent Reader 解决这三个问题：**一条命令，输出即交付**。
 | 图片 → 幻灯片 | 全屏播放、键盘翻页、自动轮播、缩略图导航 |
 | 幻灯片 → 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`）。
+
 ## 两种使用方式
 
 **CLI** — 开发者和 Agent 通过命令行调用
@@ -93,7 +111,6 @@ agent-reader render 你的文件.md
 ```bash
 agent-reader render 你的文件.md --theme light   # 亮色（默认）
 agent-reader render 你的文件.md --theme dark    # 暗色
-agent-reader render 你的文件.md --theme print   # 打印友好
 ```
 
 ### 导出 Word
@@ -211,3 +228,49 @@ Claude Desktop 配置（`claude_desktop_config.json`）：
 | Node.js 18+ | 是 | 运行环境 |
 | Puppeteer | 是 | PDF 导出（安装时自动下载 Chromium） |
 | Pandoc | 否 | Word 导出更好看（没有会自动降级为纯 JS 方案） |
+
+## 云环境部署
+
+在 Docker/CI 中，Agent Reader 会自动检测环境并在需要时为 Puppeteer 关闭沙盒参数（`--no-sandbox` 等）。
+
+手动覆盖方式：
+
+```bash
+# auto | on | off
+AGENT_READER_SANDBOX=off agent-reader export report.md --format pdf
+```
+
+Docker 环境建议预装 Chromium 依赖（示例）：
+
+```bash
+apt-get update && apt-get install -y chromium-browser
+```
+
+## FAQ：没有 Pandoc 怎么办？
+
+- 不装 Pandoc 也能导出 DOCX，只是排版会使用基础模式
+- 装 Pandoc 后，代码块和复杂表格的效果更稳定
+
+常见安装命令：
+
+```bash
+# macOS
+brew install pandoc
+
+# Linux
+apt-get install pandoc
+
+# Windows
+winget install pandoc
+# or: choco install pandoc
+# or: scoop install pandoc
+```
+
+## Puppeteer 进阶安装
+
+如果你已经有可用浏览器，想减少安装体积：
+
+```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

@@ -0,0 +1,40 @@
+---
+name: agent_reader
+description: 把 Markdown 渲染成漂亮网页、导出 Word/PDF、图片做幻灯片。专为 AI Agent 输出设计。
+---
+
+# Agent Reader Skill
+
+## 能力
+
+- Markdown 渲染为可阅读网页（目录、代码高亮、表格样式）
+- 导出 PDF / DOCX 文档
+- 图片目录生成幻灯片并支持导出 PDF
+
+## 触发条件
+
+- 用户要求把 Markdown 输出整理成可交付文档
+- 用户需要导出 Word 或 PDF
+- 用户希望把图片集合用于展示或汇报
+
+## 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
+```
+
+## MCP 调用
+
+- `render_markdown`
+- `export_document`
+- `create_slideshow`
+- `open_file`
+
+## 安装
+
+```bash
+npm install -g agent-reader
+```

package/bin/agent-reader.js

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

package/openclaw-skill/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: agent_reader
+description: 把 Markdown 渲染成漂亮网页、导出 Word/PDF、图片做幻灯片。专为 AI Agent 输出设计。
+---
+
+# Agent Reader Skill
+
+## 能力
+
+- Markdown 渲染为可阅读网页（目录、代码高亮、表格样式）
+- 导出 PDF / DOCX 文档
+- 图片目录生成幻灯片并支持导出 PDF
+
+## 触发条件
+
+- 用户要求把 Markdown 输出整理成可交付文档
+- 用户需要导出 Word 或 PDF
+- 用户希望把图片集合用于展示或汇报
+
+## 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
+```
+
+## MCP 调用
+
+- `render_markdown`
+- `export_document`
+- `create_slideshow`
+- `open_file`
+
+## 安装
+
+```bash
+npm install -g agent-reader
+```

package/openclaw-skill/schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "agent-reader-openclaw-skill-schema",
+  "type": "object",
+  "tools": {
+    "render_markdown": {
+      "description": "Render markdown text into styled HTML",
+      "input": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "description": "Markdown source content"
+          },
+          "source_path": {
+            "type": "string",
+            "description": "Source markdown path for relative images; relative resources must stay under source directory."
+          },
+          "theme": {
+            "type": "string",
+            "description": "Theme name"
+          },
+          "auto_open": {
+            "type": "boolean",
+            "description": "Open output automatically (ignored in MCP)"
+          },
+          "return_content": {
+            "type": "boolean",
+            "description": "Return inline HTML content directly"
+          }
+        },
+        "required": [
+          "content"
+        ],
+        "additionalProperties": false
+      },
+      "output": {
+        "type": "object",
+        "properties": {
+          "html_path": {
+            "type": "string"
+          },
+          "content_data": {
+            "type": "string"
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "html"
+            ]
+          },
+          "size": {
+            "type": "number"
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "format",
+          "size",
+          "warnings"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "export_document": {
+      "description": "Export markdown text into PDF or DOCX",
+      "input": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "description": "Markdown source content"
+          },
+          "source_path": {
+            "type": "string",
+            "description": "Source markdown path for relative images; relative resources must stay under source directory."
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "pdf",
+              "docx"
+            ],
+            "description": "Export format"
+          },
+          "return_content": {
+            "type": "boolean",
+            "description": "Return file bytes as base64"
+          }
+        },
+        "required": [
+          "content",
+          "format"
+        ],
+        "additionalProperties": false
+      },
+      "output": {
+        "type": "object",
+        "properties": {
+          "file_path": {
+            "type": "string"
+          },
+          "content_data": {
+            "type": "string"
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "pdf",
+              "docx"
+            ]
+          },
+          "size": {
+            "type": "number"
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "format",
+          "size",
+          "warnings"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "create_slideshow": {
+      "description": "Create slideshow HTML from an image directory",
+      "input": {
+        "type": "object",
+        "properties": {
+          "image_dir": {
+            "type": "string",
+            "description": "Absolute or relative image directory path"
+          },
+          "auto_play": {
+            "type": "number",
+            "description": "Autoplay interval in seconds"
+          },
+          "auto_open": {
+            "type": "boolean",
+            "description": "Open output automatically (ignored in MCP)"
+          },
+          "return_content": {
+            "type": "boolean",
+            "description": "Return inline HTML content directly"
+          }
+        },
+        "required": [
+          "image_dir"
+        ],
+        "additionalProperties": false
+      },
+      "output": {
+        "type": "object",
+        "properties": {
+          "html_path": {
+            "type": "string"
+          },
+          "content_data": {
+            "type": "string"
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "html"
+            ]
+          },
+          "size": {
+            "type": "number"
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "format",
+          "size",
+          "warnings"
+        ],
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/package.json

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

package/src/cli/commands.js

@@ -4,7 +4,14 @@ import open from 'open';
 import { execa } from 'execa';
 import { renderMarkdown } from '../core/renderer.js';
 import { createSlideshow } from '../core/slideshow.js';
-import { checkPandoc, checkPuppeteer, exportDOCX, exportDOCXFromHTML, exportPDF } from '../core/exporter.js';
+import {
+  checkPandoc,
+  checkPuppeteer,
+  exportDOCX,
+  exportDOCXFromHTML,
+  exportPDF,
+  resolveSandboxMode,
+} from '../core/exporter.js';
 import { openTarget } from '../core/opener.js';
 import { cleanOldOutputs, createOutputDir } from '../utils/output.js';
 import { createLogger } from '../utils/logger.js';
@@ -86,6 +93,10 @@ function dedupeWarnings(warnings) {
   return [...new Set((warnings || []).filter(Boolean))];
 }
 
+function resolveSandboxOption(options = {}) {
+  return resolveSandboxMode(options.sandbox, process.env);
+}
+
 async function buildPrintHtml(imageDir) {
   const absDir = path.resolve(imageDir);
   const entries = await fs.readdir(absDir, { withFileTypes: true });
@@ -135,9 +146,11 @@ async function maybeServeOutput(options, outputDir, targetPath, logger, jsonOnly
     return null;
   }
 
+  const sandbox = resolveSandboxOption(options);
   const serverHandle = await startStaticServer(outputDir, {
     host: '127.0.0.1',
     port: Number(options.port || 3000),
+    sandbox,
   });
 
   const rel = path.relative(outputDir, targetPath).split(path.sep).join('/');
@@ -222,6 +235,7 @@ export async function exportCommand(file, options) {
 
   try {
     const format = normalizeFormat(options.format);
+    const sandbox = resolveSandboxOption(options);
     const input = await resolveMarkdownInput(file, options, mode.logger);
     const outputDir = await createOutputDir(input.name, options.outDir);
     const warnings = [];
@@ -249,6 +263,7 @@ export async function exportCommand(file, options) {
         outDir: outputDir,
         fileName: `${input.name}.pdf`,
         htmlPath,
+        sandbox,
       });
       warnings.push(...pdf.warnings);
       targetPath = pdf.pdfPath;
@@ -322,6 +337,7 @@ export async function slidesCommand(dir, options) {
     await fs.writeFile(printHtmlPath, result.printHtml, 'utf8');
 
     const format = String(options.format || '').toLowerCase();
+    const sandbox = resolveSandboxOption(options);
     const dirName = path.basename(inputDir);
 
     if (format === 'pdf') {
@@ -331,6 +347,7 @@ export async function slidesCommand(dir, options) {
         outDir: outputDir,
         fileName: `${dirName}.pdf`,
         htmlPath: printHtmlPath,
+        sandbox,
       });
 
       const pdfWarnings = dedupeWarnings([...result.warnings, ...(pdf.warnings || [])]);
@@ -398,6 +415,7 @@ export async function openCommand(target, options) {
       throw new Error('missing target path');
     }
 
+    const sandbox = resolveSandboxOption(options);
     const preferences = await loadPreferences();
     const requestedMode = normalizeOpenMode(options.as || options.mode || 'auto', 'auto');
 
@@ -410,6 +428,7 @@ export async function openCommand(target, options) {
       pageSize: options.pageSize || 'A4',
       fetchRemote: options.fetchRemote !== false,
       returnContent: false,
+      sandbox,
     });
 
     const canServe = result.format === 'html' && result.path;
@@ -598,5 +617,6 @@ export function setupCommonCommandOptions(command) {
     .option('--inline-all', 'inline all assets to base64')
     .option('--no-fetch-remote', 'disable remote image fetching')
     .option('--serve', 'serve generated files via local HTTP server')
-    .option('--port <port>', 'port for --serve mode', '3000');
+    .option('--port <port>', 'port for --serve mode', '3000')
+    .option('--sandbox <mode>', 'Puppeteer sandbox mode: auto|on|off');
 }

package/src/core/assets.js

@@ -3,6 +3,7 @@ import dns from 'node:dns/promises';
 import { promises as fs } from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
+import { assertWithinBase } from '../utils/pathGuard.js';
 
 const LOCAL_IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp']);
 const DEFAULT_MAX_INLINE_BYTES = 200 * 1024;
@@ -241,6 +242,13 @@ async function processLocalImage(src, {
   }
 
   const resolvedPath = isAbsoluteFile ? cleanSrc : path.resolve(baseDir, cleanSrc);
+  if (!isAbsoluteFile) {
+    const withinBase = await assertWithinBase(resolvedPath, baseDir);
+    if (!withinBase) {
+      warnings.push(`path traversal blocked: ${cleanSrc}`);
+      return cleanSrc;
+    }
+  }
 
   let fileBuffer;
   try {