agent-reader 1.0.1 → 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 通过命令行调用
@@ -210,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.1",
+  "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 {

package/src/core/exporter.js

@@ -1,4 +1,4 @@
-import { promises as fs } from 'node:fs';
+import { accessSync, constants as fsConstants, promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
@@ -7,6 +7,7 @@ import { execa } from 'execa';
 import MarkdownIt from 'markdown-it';
 import {
   Document,
+  ExternalHyperlink,
   HeadingLevel,
   Packer,
   Paragraph,
@@ -25,6 +26,109 @@ const LUA_TABLE_FILTER = path.join(__dirname, 'templates', 'docx-table.lua');
 const POSTPROCESS_SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'postprocess-docx.py');
 
 const markdownParser = new MarkdownIt({ html: false, linkify: true, typographer: true });
+const SANDBOX_DISABLED_ARGS = ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'];
+const SANDBOX_MODES = new Set(['auto', 'on', 'off']);
+
+function isSandboxMode(mode) {
+  return SANDBOX_MODES.has(mode);
+}
+
+function normalizeSandboxMode(mode) {
+  if (typeof mode !== 'string') {
+    return null;
+  }
+  const normalized = mode.trim().toLowerCase();
+  return isSandboxMode(normalized) ? normalized : null;
+}
+
+function fileExistsSync(filePath) {
+  try {
+    accessSync(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function detectContainerEnv(runtime = {}) {
+  const env = runtime.env ?? process.env;
+  const fileExists = runtime.fileExists ?? fileExistsSync;
+  const getuid = Object.prototype.hasOwnProperty.call(runtime, 'getuid')
+    ? runtime.getuid
+    : process.getuid;
+
+  if (fileExists('/.dockerenv')) {
+    return true;
+  }
+  if (fileExists('/run/.containerenv')) {
+    return true;
+  }
+  if (env?.CI === 'true') {
+    return true;
+  }
+
+  try {
+    if (typeof getuid === 'function' && getuid() === 0) {
+      return true;
+    }
+  } catch {
+    return false;
+  }
+
+  return false;
+}
+
+export function resolveSandboxMode(requestedMode, env = process.env) {
+  const fromExplicit = normalizeSandboxMode(requestedMode);
+  if (fromExplicit) {
+    return fromExplicit;
+  }
+  const fromEnv = normalizeSandboxMode(env?.AGENT_READER_SANDBOX);
+  if (fromEnv) {
+    return fromEnv;
+  }
+  return 'auto';
+}
+
+export function getSandboxArgs(sandboxMode = 'auto', runtime = {}) {
+  const mode = normalizeSandboxMode(sandboxMode) || 'auto';
+  if (mode === 'on') {
+    return [];
+  }
+  if (mode === 'off') {
+    return [...SANDBOX_DISABLED_ARGS];
+  }
+  return detectContainerEnv(runtime) ? [...SANDBOX_DISABLED_ARGS] : [];
+}
+
+function runHasProperty(run, propKey) {
+  return run.properties?.root?.some((item) => item.rootKey === propKey);
+}
+
+function cloneRunWithStyle(run, { bold, italics }) {
+  const baseTextNode = run.root.find((node) => node.rootKey === 'w:t');
+  const text = typeof baseTextNode?.root?.[baseTextNode.root.length - 1] === 'string'
+    ? baseTextNode.root[baseTextNode.root.length - 1]
+    : '';
+  const hasCodeStyle = runHasProperty(run, 'w:rFonts');
+  const hasShading = runHasProperty(run, 'w:shd');
+
+  return new TextRun({
+    text,
+    bold: bold || undefined,
+    italics: italics || undefined,
+    ...(hasCodeStyle ? { font: 'Consolas' } : {}),
+    ...(hasShading
+      ? {
+        shading: {
+          type: ShadingType.CLEAR,
+          color: 'auto',
+          fill: 'F4F4F5',
+        },
+      }
+      : {}),
+  });
+}
 
 function paragraphFromText(text) {
   return new Paragraph({
@@ -65,6 +169,139 @@ function inlineToPlainText(token) {
     .join('');
 }
 
+function createInlineTextRun(text, { bold, italics, code = false }) {
+  return new TextRun({
+    text,
+    bold: bold || undefined,
+    italics: italics || undefined,
+    ...(code
+      ? {
+        font: 'Consolas',
+        shading: {
+          type: ShadingType.CLEAR,
+          color: 'auto',
+          fill: 'F4F4F5',
+        },
+      }
+      : {}),
+  });
+}
+
+function pushInlineNode(target, linkStack, node) {
+  if (linkStack.length > 0) {
+    linkStack[linkStack.length - 1].children.push(node);
+    return;
+  }
+  target.push(node);
+}
+
+function closeCurrentLink(target, linkStack, style) {
+  const current = linkStack.pop();
+  if (!current) {
+    return;
+  }
+
+  const href = current.href || '';
+  if (!href) {
+    const fallbackRuns = current.children.length > 0
+      ? current.children
+      : [createInlineTextRun('', style)];
+    for (const run of fallbackRuns) {
+      pushInlineNode(target, linkStack, run);
+    }
+    return;
+  }
+
+  const hyperlinkChildren = current.children.length > 0
+    ? current.children
+    : [createInlineTextRun(href, style)];
+  const hyperlink = new ExternalHyperlink({
+    link: href,
+    children: hyperlinkChildren.map((node) => (
+      node instanceof TextRun ? cloneRunWithStyle(node, style) : node
+    )),
+  });
+  pushInlineNode(target, linkStack, hyperlink);
+}
+
+export function inlineToDocxRuns(token) {
+  if (!token?.children?.length) {
+    const fallbackText = token?.content || '';
+    return fallbackText ? [new TextRun(fallbackText)] : [];
+  }
+
+  const output = [];
+  const linkStack = [];
+  let boldDepth = 0;
+  let italicsDepth = 0;
+
+  for (const child of token.children) {
+    const style = {
+      bold: boldDepth > 0,
+      italics: italicsDepth > 0,
+    };
+
+    if (child.type === 'strong_open') {
+      boldDepth += 1;
+      continue;
+    }
+    if (child.type === 'strong_close') {
+      boldDepth = Math.max(0, boldDepth - 1);
+      continue;
+    }
+    if (child.type === 'em_open') {
+      italicsDepth += 1;
+      continue;
+    }
+    if (child.type === 'em_close') {
+      italicsDepth = Math.max(0, italicsDepth - 1);
+      continue;
+    }
+    if (child.type === 'link_open') {
+      linkStack.push({
+        href: child.attrGet('href') || '',
+        children: [],
+      });
+      continue;
+    }
+    if (child.type === 'link_close') {
+      closeCurrentLink(output, linkStack, style);
+      continue;
+    }
+    if (child.type === 'text') {
+      if (child.content) {
+        pushInlineNode(output, linkStack, createInlineTextRun(child.content, style));
+      }
+      continue;
+    }
+    if (child.type === 'code_inline') {
+      pushInlineNode(output, linkStack, createInlineTextRun(child.content || '', { ...style, code: true }));
+      continue;
+    }
+    if (child.type === 'softbreak' || child.type === 'hardbreak') {
+      pushInlineNode(output, linkStack, createInlineTextRun('\n', style));
+      continue;
+    }
+    if (child.type === 'image') {
+      const alt = child.content || child.attrGet('alt') || 'image';
+      pushInlineNode(output, linkStack, createInlineTextRun(`[${alt}]`, style));
+      continue;
+    }
+    if (child.content) {
+      pushInlineNode(output, linkStack, createInlineTextRun(child.content, style));
+    }
+  }
+
+  while (linkStack.length > 0) {
+    closeCurrentLink(output, linkStack, {
+      bold: boldDepth > 0,
+      italics: italicsDepth > 0,
+    });
+  }
+
+  return output;
+}
+
 function collectTocEntries(tokens) {
   const entries = [];
   for (let i = 0; i < tokens.length; i += 1) {
@@ -123,9 +360,11 @@ function parseTable(tokens, startIndex) {
           rows: rows.map(
             (items) =>
               new TableRow({
-                children: items.map((item) =>
+                children: items.map((itemRuns) =>
                   new TableCell({
-                    children: [paragraphFromText(item || '')],
+                    children: [new Paragraph({
+                      children: itemRuns.length > 0 ? itemRuns : [new TextRun('')],
+                    })],
                   }),
                 ),
               }),
@@ -146,17 +385,17 @@ function parseTable(tokens, startIndex) {
     }
 
     if (token.type === 'th_open' || token.type === 'td_open') {
-      currentCell = '';
+      currentCell = [];
       continue;
     }
 
     if (token.type === 'inline' && currentCell !== null) {
-      currentCell += inlineToPlainText(token);
+      currentCell.push(...inlineToDocxRuns(token));
       continue;
     }
 
     if (token.type === 'th_close' || token.type === 'td_close') {
-      row.push(currentCell || '');
+      row.push(currentCell || []);
       currentCell = null;
     }
   }
@@ -167,10 +406,10 @@ function parseTable(tokens, startIndex) {
   };
 }
 
-function markdownToDocx(markdown) {
+export function markdownToDocx(markdown) {
   const tokens = markdownParser.parse(markdown, {});
   const tocEntries = collectTocEntries(tokens);
-  const children = [];
+  const children = [...buildDocxTocParagraphs(tocEntries)];
   const listStack = [];
   let pendingBlock = null;
 
@@ -237,15 +476,15 @@ function markdownToDocx(markdown) {
       continue;
     }
 
-    const text = inlineToPlainText(token).trim();
-    if (!text) {
+    const runs = inlineToDocxRuns(token);
+    if (runs.length === 0) {
       continue;
     }
 
     if (pendingBlock?.type === 'heading') {
       children.push(
         new Paragraph({
-          text,
+          children: runs,
           heading: headingLevelFromNumber(pendingBlock.level),
         }),
       );
@@ -256,11 +495,13 @@ function markdownToDocx(markdown) {
     if (listStack.length > 0) {
       const top = listStack[listStack.length - 1];
       const prefix = top.type === 'ordered' ? `${top.count}. ` : '• ';
-      children.push(paragraphFromText(`${prefix}${text}`));
+      children.push(new Paragraph({
+        children: [new TextRun(prefix), ...runs],
+      }));
       continue;
     }
 
-    children.push(paragraphFromText(text));
+    children.push(new Paragraph({ children: runs }));
     pendingBlock = null;
   }
 
@@ -431,6 +672,24 @@ export async function checkPuppeteer() {
   }
 }
 
+export function getPandocInstallHint(platform = process.platform) {
+  if (platform === 'darwin') {
+    return 'brew install pandoc';
+  }
+  if (platform === 'win32') {
+    return 'winget install pandoc (or choco install pandoc / scoop install pandoc)';
+  }
+  return 'apt-get install pandoc (or yum install pandoc)';
+}
+
+export function createPandocFallbackWarnings(platform = process.platform) {
+  const installHint = getPandocInstallHint(platform);
+  return [
+    'pandoc_not_found',
+    `⚡ 当前使用基础排版模式。想要更精美的代码高亮和智能表格？一行命令解锁：${installHint}`,
+  ];
+}
+
 export async function exportPDF(html, options = {}) {
   const {
     pageSize = 'A4',
@@ -438,6 +697,7 @@ export async function exportPDF(html, options = {}) {
     outDir = os.tmpdir(),
     fileName = 'output.pdf',
     htmlPath,
+    sandbox,
   } = options;
 
   let puppeteer;
@@ -450,10 +710,13 @@ export async function exportPDF(html, options = {}) {
 
   const warnings = [];
   const pdfPath = path.join(path.resolve(outDir), fileName);
+  const resolvedSandboxMode = resolveSandboxMode(sandbox);
+  const launchArgs = landscape ? ['--allow-file-access-from-files'] : [];
+  launchArgs.push(...getSandboxArgs(resolvedSandboxMode));
 
   const browser = await puppeteer.launch({
     headless: true,
-    args: landscape ? ['--allow-file-access-from-files'] : [],
+    args: launchArgs,
   });
   try {
     const page = await browser.newPage();
@@ -587,8 +850,7 @@ export async function exportDOCX(markdownString, options = {}) {
       await fs.rm(tempInput, { force: true }).catch(() => {});
     }
   } else {
-    const warning = 'Pandoc not found, using docx fallback. Install Pandoc for better results.';
-    warnings.push(warning);
+    warnings.push(...createPandocFallbackWarnings());
 
     const document = markdownToDocx(markdownString);
     const buffer = await Packer.toBuffer(document);
@@ -677,7 +939,7 @@ export async function exportDOCXFromHTML(htmlString, options = {}) {
       await fs.rm(tempInput, { force: true }).catch(() => {});
     }
   } else {
-    warnings.push('Pandoc not found, using text-only DOCX fallback.');
+    warnings.push(...createPandocFallbackWarnings());
 
     const plainText = String(htmlString || '')
       .replace(/<style[\s\S]*?<\/style>/gi, ' ')

package/src/core/opener.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { createOutputDir } from '../utils/output.js';
 import { normalizeOpenMode } from '../utils/preferences.js';
 import { renderMarkdown } from './renderer.js';
-import { exportDOCX, exportPDF } from './exporter.js';
+import { exportDOCX, exportPDF, resolveSandboxMode } from './exporter.js';
 import { createSlideshow } from './slideshow.js';
 
 const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdown', '.mdx']);
@@ -94,7 +94,9 @@ export async function openTarget(targetPath, options = {}) {
     fetchRemote = true,
     returnContent = false,
     maxContentBytes = 50 * 1024 * 1024,
+    sandbox,
   } = options;
+  const resolvedSandbox = resolveSandboxMode(sandbox, process.env);
 
   const requestedMode = normalizeOpenMode(mode, 'auto');
   const preferredMode = requestedMode === 'auto'
@@ -258,6 +260,7 @@ export async function openTarget(targetPath, options = {}) {
       outDir: outputDir,
       fileName: `${name}.pdf`,
       htmlPath,
+      sandbox: resolvedSandbox,
     });
     warnings.push(...pdf.warnings);
 

package/src/mcp/server.js

@@ -2,12 +2,12 @@ import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import * as z from 'zod/v4';
 import { renderMarkdown } from '../core/renderer.js';
-import { exportDOCX, exportPDF } from '../core/exporter.js';
+import { exportDOCX, exportPDF, resolveSandboxMode } from '../core/exporter.js';
 import { createSlideshow } from '../core/slideshow.js';
 import { openTarget } from '../core/opener.js';
 import { createOutputDir } from '../utils/output.js';
+import { MCP_TOOL_SCHEMAS } from './toolSchemas.js';
 import {
   getPreferencesPath,
   loadPreferences,
@@ -16,6 +16,7 @@ import {
 } from '../utils/preferences.js';
 
 const MAX_CONTENT_BYTES = 50 * 1024 * 1024;
+const MCP_SANDBOX_MODE = resolveSandboxMode(process.env.AGENT_READER_SANDBOX, process.env);
 
 function getBaseDirFromSourcePath(sourcePath) {
   if (!sourcePath) {
@@ -71,21 +72,12 @@ async function saveHtmlResult(html, outputDir, name = 'output') {
 
 const server = new McpServer({
   name: 'agent-reader',
-  version: '0.2.0',
+  version: '1.1.0',
 });
 
 server.registerTool(
   'render_markdown',
-  {
-    description: 'Render markdown text into styled HTML',
-    inputSchema: {
-      content: z.string().describe('Markdown source content'),
-      source_path: z.string().optional().describe('Source markdown path for relative images'),
-      theme: z.string().optional().describe('Theme name'),
-      auto_open: z.boolean().optional().describe('Open output automatically (ignored in MCP)'),
-      return_content: z.boolean().optional().describe('Return inline HTML content directly'),
-    },
-  },
+  MCP_TOOL_SCHEMAS.render_markdown,
   async ({ content, source_path, theme, return_content }) => {
     try {
       const baseDir = getBaseDirFromSourcePath(source_path);
@@ -142,15 +134,7 @@ server.registerTool(
 
 server.registerTool(
   'export_document',
-  {
-    description: 'Export markdown text into PDF or DOCX',
-    inputSchema: {
-      content: z.string().describe('Markdown source content'),
-      source_path: z.string().optional().describe('Source markdown path for relative images'),
-      format: z.enum(['pdf', 'docx']).describe('Export format'),
-      return_content: z.boolean().optional().describe('Return file bytes as base64'),
-    },
-  },
+  MCP_TOOL_SCHEMAS.export_document,
   async ({ content, source_path, format, return_content }) => {
     try {
       const baseDir = getBaseDirFromSourcePath(source_path);
@@ -174,6 +158,7 @@ server.registerTool(
           outDir: outputDir,
           fileName: 'export.pdf',
           htmlPath,
+          sandbox: MCP_SANDBOX_MODE,
         });
         filePath = pdf.pdfPath;
         warnings = [...warnings, ...rendered.warnings, ...pdf.warnings];
@@ -223,15 +208,7 @@ server.registerTool(
 
 server.registerTool(
   'create_slideshow',
-  {
-    description: 'Create slideshow HTML from an image directory',
-    inputSchema: {
-      image_dir: z.string().describe('Absolute or relative image directory path'),
-      auto_play: z.number().optional().describe('Autoplay interval in seconds'),
-      auto_open: z.boolean().optional().describe('Open output automatically (ignored in MCP)'),
-      return_content: z.boolean().optional().describe('Return inline HTML content directly'),
-    },
-  },
+  MCP_TOOL_SCHEMAS.create_slideshow,
   async ({ image_dir, auto_play, return_content }) => {
     try {
       const outputDir = await createOutputDir('create-slideshow');
@@ -278,16 +255,7 @@ server.registerTool(
 
 server.registerTool(
   'open_file',
-  {
-    description: 'Open a local file/path using user preference or explicit mode: web/word/pdf/ppt',
-    inputSchema: {
-      file_path: z.string().describe('File path or image directory path'),
-      open_as: z.string().optional().describe('auto|web|word|pdf|ppt'),
-      theme: z.string().optional().describe('theme for web rendering'),
-      auto_play: z.number().optional().describe('auto play seconds for ppt mode'),
-      return_content: z.boolean().optional().describe('return generated content directly'),
-    },
-  },
+  MCP_TOOL_SCHEMAS.open_file,
   async ({ file_path, open_as, theme, auto_play, return_content }) => {
     try {
       const preferences = await loadPreferences();
@@ -299,6 +267,7 @@ server.registerTool(
         autoPlay: auto_play,
         returnContent: Boolean(return_content),
         maxContentBytes: MAX_CONTENT_BYTES,
+        sandbox: MCP_SANDBOX_MODE,
       });
 
       const payload = {
@@ -319,13 +288,7 @@ server.registerTool(
 
 server.registerTool(
   'configure_user_preferences',
-  {
-    description: 'Set default open behavior for novice users',
-    inputSchema: {
-      default_open_mode: z.string().optional().describe('web|word|pdf|ppt'),
-      default_theme: z.string().optional().describe('default web theme'),
-    },
-  },
+  MCP_TOOL_SCHEMAS.configure_user_preferences,
   async ({ default_open_mode, default_theme }) => {
     try {
       const updates = {};
@@ -352,10 +315,7 @@ server.registerTool(
 
 server.registerTool(
   'get_user_preferences',
-  {
-    description: 'Read current user preferences for open behavior',
-    inputSchema: {},
-  },
+  MCP_TOOL_SCHEMAS.get_user_preferences,
   async () => {
     try {
       const preferences = await loadPreferences();

package/src/mcp/toolSchemas.js

@@ -0,0 +1,53 @@
+import * as z from 'zod/v4';
+
+export const MCP_TOOL_SCHEMAS = {
+  render_markdown: {
+    description: 'Render markdown text into styled HTML',
+    inputSchema: {
+      content: z.string().describe('Markdown source content'),
+      source_path: z.string().optional().describe('Source markdown path for relative images'),
+      theme: z.string().optional().describe('Theme name'),
+      auto_open: z.boolean().optional().describe('Open output automatically (ignored in MCP)'),
+      return_content: z.boolean().optional().describe('Return inline HTML content directly'),
+    },
+  },
+  export_document: {
+    description: 'Export markdown text into PDF or DOCX',
+    inputSchema: {
+      content: z.string().describe('Markdown source content'),
+      source_path: z.string().optional().describe('Source markdown path for relative images'),
+      format: z.enum(['pdf', 'docx']).describe('Export format'),
+      return_content: z.boolean().optional().describe('Return file bytes as base64'),
+    },
+  },
+  create_slideshow: {
+    description: 'Create slideshow HTML from an image directory',
+    inputSchema: {
+      image_dir: z.string().describe('Absolute or relative image directory path'),
+      auto_play: z.number().optional().describe('Autoplay interval in seconds'),
+      auto_open: z.boolean().optional().describe('Open output automatically (ignored in MCP)'),
+      return_content: z.boolean().optional().describe('Return inline HTML content directly'),
+    },
+  },
+  open_file: {
+    description: 'Open a local file/path using user preference or explicit mode: web/word/pdf/ppt',
+    inputSchema: {
+      file_path: z.string().describe('File path or image directory path'),
+      open_as: z.string().optional().describe('auto|web|word|pdf|ppt'),
+      theme: z.string().optional().describe('theme for web rendering'),
+      auto_play: z.number().optional().describe('auto play seconds for ppt mode'),
+      return_content: z.boolean().optional().describe('return generated content directly'),
+    },
+  },
+  configure_user_preferences: {
+    description: 'Set default open behavior for novice users',
+    inputSchema: {
+      default_open_mode: z.string().optional().describe('web|word|pdf|ppt'),
+      default_theme: z.string().optional().describe('default web theme'),
+    },
+  },
+  get_user_preferences: {
+    description: 'Read current user preferences for open behavior',
+    inputSchema: {},
+  },
+};

package/src/utils/pathGuard.js

@@ -0,0 +1,62 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+async function resolveWithNearestParent(targetPath) {
+  const absoluteTarget = path.resolve(targetPath);
+  try {
+    const realTarget = await fs.realpath(absoluteTarget);
+    return { ok: true, realTarget };
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      return { ok: false };
+    }
+  }
+
+  const missingSegments = [];
+  let cursor = absoluteTarget;
+
+  while (true) {
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      return { ok: false };
+    }
+    missingSegments.push(path.basename(cursor));
+    cursor = parent;
+
+    try {
+      const realParent = await fs.realpath(cursor);
+      return {
+        ok: true,
+        realTarget: path.join(realParent, ...missingSegments.reverse()),
+      };
+    } catch (error) {
+      if (error?.code !== 'ENOENT') {
+        return { ok: false };
+      }
+    }
+  }
+}
+
+export async function assertWithinBase(targetPath, baseDir) {
+  if (!baseDir) {
+    return false;
+  }
+
+  let realBase;
+  try {
+    realBase = await fs.realpath(path.resolve(baseDir));
+  } catch {
+    return false;
+  }
+
+  const resolved = await resolveWithNearestParent(targetPath);
+  if (!resolved.ok) {
+    return false;
+  }
+
+  const relative = path.relative(realBase, resolved.realTarget);
+  if (!relative) {
+    return true;
+  }
+  return !relative.startsWith('..') && !path.isAbsolute(relative);
+}

package/src/utils/server.js

@@ -2,7 +2,7 @@ import http from 'node:http';
 import net from 'node:net';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { exportDOCXFromHTML, exportPDF } from '../core/exporter.js';
+import { exportDOCXFromHTML, exportPDF, resolveSandboxMode } from '../core/exporter.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -94,7 +94,7 @@ async function resolveExportSourcePath(req, rootDir, sourceParam) {
   throw createHttpError(400, 'missing source path');
 }
 
-async function handleExportRequest(req, res, rootDir, urlObject) {
+async function handleExportRequest(req, res, rootDir, urlObject, sandbox) {
   if (req.method !== 'GET') {
     sendJson(res, 405, { error: 'method not allowed' });
     return;
@@ -131,6 +131,7 @@ async function handleExportRequest(req, res, rootDir, urlObject) {
         fileName: `${sourceName}.pdf`,
         htmlPath: sourcePath,
         landscape: isLandscape,
+        sandbox,
       });
       outputPath = result.pdfPath;
       warnings = result.warnings || [];
@@ -140,6 +141,7 @@ async function handleExportRequest(req, res, rootDir, urlObject) {
         baseDir: sourceDir,
         outDir: sourceDir,
         fileName: `${sourceName}.docx`,
+        sandbox,
       });
       outputPath = result.docxPath;
       warnings = result.warnings || [];
@@ -190,14 +192,18 @@ async function isPortInUse(host, port) {
   });
 }
 
-export async function startStaticServer(rootDir, { host = '127.0.0.1', port = 3000 } = {}) {
+export async function startStaticServer(
+  rootDir,
+  { host = '127.0.0.1', port = 3000, sandbox } = {},
+) {
   const absoluteRoot = path.resolve(rootDir);
+  const resolvedSandbox = resolveSandboxMode(sandbox, process.env);
 
   const server = http.createServer(async (req, res) => {
     const urlObject = new URL(req.url || '/', `http://${host}:${port}`);
     try {
       if (urlObject.pathname === '/api/export') {
-        await handleExportRequest(req, res, absoluteRoot, urlObject);
+        await handleExportRequest(req, res, absoluteRoot, urlObject, resolvedSandbox);
         return;
       }