Update pdflux-saas-markdown skill.

Author: shangwenmo

pdflux-saas-markdown/SKILL.md

@@ -1,21 +1,27 @@
 ---
-name: pdflux-saas-markdown
-description: 解析文档并获取文档内容，尤其适用于提取 PDF、DOCX、DOC、PPT、PPTX、PNG、JPG、JPEG 等文件中的正文与表格内容。用于将文件转换为 markdown、响应“转 markdown”这类需求、读取文档具体内容、基于文档内容执行后续分析或脚本处理；当需要编写脚本解析文档时，优先使用这个 skill。
+name: PDFlux-PDF2Markdown
+description: 将非结构化文档转化为“大模型 Ready”的结构化数据。支持 PDF、Word、PPT 及图片，一键提取段落、公式、表格、图表等元素，生成最高 8 级目录索引，并按阅读逻辑组织输出 Markdown。应用场景：字段抽取、对比校验、知识检索与智能问答。
 ---
 
-# pdflux-saas-markdown
+# PDFlux-PDF2Markdown
 
-执行一个 JavaScript 工作流，先把单个本地文件解析为 markdown，再基于 markdown 获取正文、表格和结构化内容。支持 PDF、Word、PPT 和图片等常见格式，适合文档解析、表格提取、内容核对，以及把文档内容交给后续脚本继续处理。
+执行一个 JavaScript 工作流，先通过 PDRouter 上传单个本地文件到 `pdflux` 服务，再轮询解析状态并下载 markdown。适合文档解析、表格提取、内容核对，以及把文档内容交给后续脚本继续处理。
+
+## 安装方式
+
+```bash
+npx skills add PaodingAI/skills
+```
 
 ## 运行方式
 
 ```bash
-node .claude/skills/pdflux-saas-markdown/scripts/upload_to_markdown.js <local-file-path>
+node skills/pdflux-sass-markdown/scripts/upload_to_markdown.js <local-file-path> [output-markdown-path]
 ```
 
 ## 执行约束
 
-- 必须直接调用 `scripts/upload_to_markdown.js` 执行，不要根据下方行为约定自行重写上传、轮询、下载 markdown 的流程。
+- 必须直接调用 `scripts/upload_to_markdown.js`，不要自行重写通过 PDRouter 上传、轮询、下载 markdown 的流程。
 - 行为约定仅用于说明脚本做什么、输出什么、何时适合使用，不是给模型手工照着执行的步骤。
 - 即使任务只是提取表格、获取字段、读取正文或为后续脚本准备输入，也必须先运行该脚本，再基于脚本产出的 markdown 继续处理。
 - 只有在脚本本身不可用、报错、或需要修复脚本时，才允许检查或修改脚本实现；在正常使用场景下不要绕过脚本。
@@ -25,22 +31,28 @@ node .claude/skills/pdflux-saas-markdown/scripts/upload_to_markdown.js <local-fi
 - 当用户要解析文档、获取文档具体内容或抽取文档表格时，使用这个 skill。
 - 当用户输入类似“转 markdown”“输出 markdown”“导出 markdown”“提取 markdown”时，使用这个 skill，并直接输出 markdown 内容。
 - 当后续任务依赖文档内容继续处理，例如生成摘要、抽取字段、编写脚本处理文档、对比表格或做规则校验时，优先先用这个 skill 解析文档。
-- 当只是需要文档内容供后续操作使用时，不默认向用户输出原始 markdown 全文；优先将 markdown 保存到临时文件，再读取、筛选、提取需要的内容。
+- 当只是需要文档内容供后续操作使用时，不默认向用户输出原始 markdown 全文；优先将 markdown 保存到临时文件或工作文件，再读取、筛选、提取需要的内容。
 - 当用户明确要求“输出 markdown 原文”或表达的是“转 markdown”类直接转换需求时，直接展示完整 markdown。
 
 ## 环境变量
 
-- `PAODINGAI_API_KEY`: 必填访问令牌。若未设置，提示 `Enter PAODINGAI_API_KEY:` 并接收手动输入。
-- `PAODINGAI_API_BASE_URL`: 可选 API 域名。默认值：`https://saas.pdflux.com`。
+- `PD_ROUTER_API_KEY`: 必填。PDRouter 的 Bearer API Key。若未设置，脚本会直接报错；在 skill 场景下，AI 应提示用户提供可用的 key，或先将其注入环境变量后再重试。可通过 PDRouter 平台获取 API Key：[https://platform.paodingai.com/](https://platform.paodingai.com/)
+- `PDFLUX_INCLUDE_IMAGES`: 可选。布尔值。等价于在 markdown 接口增加 `include_images=true`；markdown 默认不包含图片数据。
+
+## 默认行为与可选参数
+
+- 文件解析结果默认不包含图表、图片类解析。
+- 如果业务需要图表、图片等内容，可通过接口参数显式开启；相关结果通常以 base64 形式返回，会增加额外 tokens 消耗。
+- markdown 结果默认不包含图片数据；如果需要包含图片，请在 markdown 接口增加 `include_images: true` 参数，或设置 `PDFLUX_INCLUDE_IMAGES=true`。
 
 ## 脚本行为说明
 
-1. 优先从 `PAODINGAI_API_KEY` 读取令牌，缺失时回退到交互式输入。
-2. 使用 `Authorization: Bearer <token>` 调用 `/api/v1/saas/upload` 上传文件。
-3. 持续轮询 `/api/v1/saas/document/{uuid}`，直到 `parsed === 2`。
+1. 从 `PD_ROUTER_API_KEY` 读取令牌；若缺失则立即失败，并提示 AI 向用户索要 key 或先注入环境变量。
+2. 使用 `Authorization: Bearer <token>` 调用 `POST /openapi/{serviceCode}/upload` 上传文件。
+3. 持续轮询 `GET /openapi/{serviceCode}/document/{uuid}`，直到 `parsed === 2`。
 4. 当解析状态为负值时立即失败。
-5. 从 `/api/v1/saas/document/{uuid}/markdown` 下载 markdown。
-6. 脚本默认将 markdown 内容写入 stdout，因此在实际使用中，若后续还要继续消费文档内容，优先将 stdout 重定向到临时文件或工作文件，再读取文件内容进行后续处理。
-7. 当任务目标是获取具体内容、字段或表格时，读取解析结果并只输出必要信息，不向用户直接回显原始 markdown 全文。
-8. 当用户明确表达“转 markdown”“输出 markdown”或等价意图时，直接返回 markdown 内容，而不是只返回提取后的摘要或字段。
-9. 将进度与错误写入 stderr，错误时返回非零退出码。
+5. 从 `GET /openapi/{serviceCode}/document/{uuid}/markdown` 下载 markdown；如有需要，可附带 markdown 查询参数，例如 `include_images=true`。
+6. 若传入 `output-markdown-path`，脚本会额外将 markdown 写入该文件；同时仍会把 markdown 输出到 stdout。
+7. 脚本将进度与错误写入 stderr，错误时返回非零退出码。
+8. 当任务目标是获取具体内容、字段或表格时，读取解析结果并只输出必要信息，不向用户直接回显原始 markdown 全文。
+9. 当用户明确表达“转 markdown”“输出 markdown”或等价意图时，直接返回 markdown 内容，而不是只返回提取后的摘要或字段。

pdflux-saas-markdown/scripts/upload_to_markdown.js

@@ -2,10 +2,10 @@
 
 const fs = require('node:fs/promises');
 const path = require('node:path');
-const readline = require('node:readline/promises');
-const { stdin, stderr, stdout } = require('node:process');
+const { stderr, stdout } = require('node:process');
 
-const DEFAULT_BASE_URL = 'https://saas.pdflux.com';
+const DEFAULT_BASE_URL = (process.env.PD_ROUTER_BASE_URL || 'https://platform.paodingai.com/').trim();
+const DEFAULT_SERVICE_CODE = 'pdflux';
 const DEFAULT_POLL_INTERVAL_MS = 2000;
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 
@@ -17,27 +17,36 @@ function normalizeBaseUrl(url) {
   return (url || DEFAULT_BASE_URL).trim().replace(/\/+$/, '');
 }
 
-async function readAccessToken() {
-  const fromEnv = (process.env.PAODINGAI_API_KEY || '').trim();
-  if (fromEnv) {
-    return fromEnv;
+function normalizeServiceCode(serviceCode) {
+  return (serviceCode || DEFAULT_SERVICE_CODE).trim() || DEFAULT_SERVICE_CODE;
+}
+
+function parseBooleanEnv(name) {
+  const rawValue = process.env[name];
+  if (rawValue == null) {
+    return null;
   }
 
-  const rl = readline.createInterface({
-    input: stdin,
-    output: stderr,
-  });
+  const normalizedValue = rawValue.trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalizedValue)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'off'].includes(normalizedValue)) {
+    return false;
+  }
 
-  try {
-    const input = await rl.question('Enter PAODINGAI_API_KEY: ');
-    const token = (input || '').trim();
-    if (!token) {
-      throw new Error('PAODINGAI_API_KEY is required but not provided.');
-    }
-    return token;
-  } finally {
-    rl.close();
+  throw new Error(`${name} must be a boolean string like true/false/1/0.`);
+}
+
+function requireGatewayApiKey() {
+  const fromEnv = (process.env.PD_ROUTER_API_KEY || '').trim();
+  if (fromEnv) {
+    return fromEnv;
   }
+
+  throw new Error(
+    'PD_ROUTER_API_KEY is required. This skill script does not prompt for input, so ask the user to provide a PD Router API key or set PD_ROUTER_API_KEY before retrying.',
+  );
 }
 
 async function parseResponse(response) {
@@ -61,100 +70,90 @@ function extractApiError(payload, fallback) {
     return payload || fallback;
   }
   if (typeof payload === 'object') {
-    return payload.msg || payload.message || JSON.stringify(payload);
+    return payload.code || payload.msg || payload.message || JSON.stringify(payload);
   }
   return fallback;
 }
 
-async function uploadFile({ baseUrl, token, filePath }) {
+function buildOpenApiUrl(baseUrl, serviceCode, endpoint) {
+  const normalizedEndpoint = endpoint.replace(/^\/+/, '');
+  return `${baseUrl}/openapi/${serviceCode}/${normalizedEndpoint}`;
+}
+
+function buildAuthHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+  };
+}
+
+async function uploadFile({ baseUrl, serviceCode, apiKey, filePath, forceUpdate, forceOcr }) {
   const formData = new FormData();
   const filename = path.basename(filePath);
   const bytes = await fs.readFile(filePath);
-  const fileBlob = new Blob([bytes], { type: 'application/octet-stream' });
+  const fileBlob = new Blob([bytes], { type: 'application/pdf' });
   formData.append('file', fileBlob, filename);
+  formData.append('force_update', String(forceUpdate));
+  formData.append('force_ocr', String(forceOcr));
 
-  const response = await fetch(`${baseUrl}/api/v1/saas/upload`, {
+  const response = await fetch(buildOpenApiUrl(baseUrl, serviceCode, 'upload'), {
     method: 'POST',
-    headers: {
-      Authorization: `Bearer ${token}`,
-    },
+    headers: buildAuthHeaders(apiKey),
     body: formData,
   });
 
   const payload = await parseResponse(response);
   if (!response.ok) {
-    throw new Error(
-      `Upload failed (${response.status}): ${extractApiError(payload, 'Request failed')}`,
-    );
+    throw new Error(`Upload failed (${response.status}): ${extractApiError(payload, 'Request failed')}`);
   }
-
   if (typeof payload !== 'object' || payload.status === false) {
-    throw new Error(
-      `Upload failed: ${extractApiError(payload, 'Invalid upload response')}`,
-    );
+    throw new Error(`Upload failed: ${extractApiError(payload, 'Invalid upload response')}`);
   }
 
   const uuid = payload?.data?.uuid;
   if (!uuid) {
-    throw new Error(
-      `Upload succeeded but uuid is missing: ${JSON.stringify(payload)}`,
-    );
+    throw new Error(`Upload succeeded but uuid is missing: ${JSON.stringify(payload)}`);
   }
 
   return uuid;
 }
 
-async function pollParsed({ baseUrl, token, uuid, pollIntervalMs, timeoutMs }) {
+async function pollParsed({ baseUrl, serviceCode, apiKey, uuid, pollIntervalMs, timeoutMs }) {
   const startTime = Date.now();
 
   while (Date.now() - startTime < timeoutMs) {
-    const response = await fetch(`${baseUrl}/api/v1/saas/document/${uuid}`, {
+    const response = await fetch(buildOpenApiUrl(baseUrl, serviceCode, `document/${uuid}`), {
       method: 'GET',
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
+      headers: buildAuthHeaders(apiKey),
     });
 
     const payload = await parseResponse(response);
     if (!response.ok) {
-      throw new Error(
-        `Polling failed (${response.status}): ${extractApiError(payload, 'Request failed')}`,
-      );
+      throw new Error(`Polling failed (${response.status}): ${extractApiError(payload, 'Request failed')}`);
     }
     if (typeof payload !== 'object' || payload.status === false) {
-      throw new Error(
-        `Polling failed: ${extractApiError(payload, 'Invalid status response')}`,
-      );
+      throw new Error(`Polling failed: ${extractApiError(payload, 'Invalid status response')}`);
     }
 
     const parsed = payload?.data?.parsed;
     if (parsed === 2) {
-      return;
+      return payload;
     }
     if (typeof parsed === 'number' && parsed < 0) {
-      throw new Error(
-        `Parsing failed with status ${parsed}: ${extractApiError(payload, 'Parse failed')}`,
-      );
+      throw new Error(`Parsing failed with status ${parsed}: ${extractApiError(payload, 'Parse failed')}`);
     }
 
     await sleep(pollIntervalMs);
   }
 
-  throw new Error(
-    `Polling timed out after ${Math.floor(timeoutMs / 1000)} seconds.`,
-  );
+  throw new Error(`Polling timed out after ${Math.floor(timeoutMs / 1000)} seconds.`);
 }
 
-async function downloadMarkdown({ baseUrl, token, uuid }) {
-  const response = await fetch(
-    `${baseUrl}/api/v1/saas/document/${uuid}/markdown`,
-    {
-      method: 'GET',
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-    },
-  );
+async function downloadMarkdown({ baseUrl, serviceCode, apiKey, uuid, outputPath, includeImages }) {
+  const endpoint = includeImages ? `document/${uuid}/markdown?include_images=true` : `document/${uuid}/markdown`;
+  const response = await fetch(buildOpenApiUrl(baseUrl, serviceCode, endpoint), {
+    method: 'GET',
+    headers: buildAuthHeaders(apiKey),
+  });
 
   const contentType = response.headers.get('content-type') || '';
   const bodyText = await response.text();
@@ -166,21 +165,17 @@ async function downloadMarkdown({ baseUrl, token, uuid }) {
         const payload = JSON.parse(bodyText);
         errorMessage = extractApiError(payload, bodyText);
       } catch {
-        // Keep bodyText
+        // keep bodyText
       }
     }
-    throw new Error(
-      `Markdown download failed (${response.status}): ${errorMessage || 'Request failed'}`,
-    );
+    throw new Error(`Markdown download failed (${response.status}): ${errorMessage || 'Request failed'}`);
   }
 
   if (contentType.includes('application/json')) {
     try {
       const payload = JSON.parse(bodyText);
       if (payload?.status === false) {
-        throw new Error(
-          `Markdown download failed: ${extractApiError(payload, 'API returned error')}`,
-        );
+        throw new Error(`Markdown download failed: ${extractApiError(payload, 'API returned error')}`);
       }
     } catch (error) {
       if (error instanceof Error) {
@@ -189,12 +184,15 @@ async function downloadMarkdown({ baseUrl, token, uuid }) {
     }
   }
 
+  if (outputPath) {
+    await fs.writeFile(outputPath, bodyText, 'utf8');
+  }
   return bodyText;
 }
 
 async function ensureInputFile(filePathArg) {
   if (!filePathArg) {
-    throw new Error('Usage: node upload_to_markdown.js <local-file-path>');
+    throw new Error('Usage: node upload_to_markdown.js <local-file-path> [output-markdown-path]');
   }
 
   const resolvedPath = path.resolve(filePathArg);
@@ -214,23 +212,41 @@ async function ensureInputFile(filePathArg) {
 
 async function main() {
   const filePath = await ensureInputFile(process.argv[2]);
-  const token = await readAccessToken();
-  const baseUrl = normalizeBaseUrl(process.env.PAODINGAI_API_BASE_URL);
-
-  const pollIntervalMs = DEFAULT_POLL_INTERVAL_MS;
-  const timeoutMs = DEFAULT_TIMEOUT_MS;
-
-  stderr.write(`[pdflux-saas-markdown] Uploading ${path.basename(filePath)}\n`);
-  const uuid = await uploadFile({ baseUrl, token, filePath });
+  const outputPath = process.argv[3] ? path.resolve(process.argv[3]) : null;
+  const apiKey = requireGatewayApiKey();
+  const baseUrl = normalizeBaseUrl();
+  const serviceCode = normalizeServiceCode(process.env.PD_ROUTER_SERVICE_CODE);
+  const forceUpdate = (process.env.PDFLUX_FORCE_UPDATE || 'true').trim().toLowerCase() !== 'false';
+  const forceOcr = (process.env.PDFLUX_FORCE_OCR || 'true').trim().toLowerCase() !== 'false';
+  const includeImages = parseBooleanEnv('PDFLUX_INCLUDE_IMAGES') === true;
+
+  stderr.write(`[pd-router-pdflux-markdown] Uploading ${path.basename(filePath)} via ${baseUrl}\n`);
+  const uuid = await uploadFile({ baseUrl, serviceCode, apiKey, filePath, forceUpdate, forceOcr });
+
+  stderr.write(`[pd-router-pdflux-markdown] Uploaded uuid=${uuid}\n`);
+  stderr.write('[pd-router-pdflux-markdown] Polling parse status\n');
+  await pollParsed({
+    baseUrl,
+    serviceCode,
+    apiKey,
+    uuid,
+    pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  });
 
-  stderr.write(`[pdflux-saas-markdown] Uploaded uuid=${uuid}\n`);
-  stderr.write('[pdflux-saas-markdown] Polling parse status\n');
-  await pollParsed({ baseUrl, token, uuid, pollIntervalMs, timeoutMs });
+  stderr.write('[pd-router-pdflux-markdown] Parse completed, downloading markdown\n');
+  const markdown = await downloadMarkdown({
+    baseUrl,
+    serviceCode,
+    apiKey,
+    uuid,
+    outputPath,
+    includeImages,
+  });
 
-  stderr.write(
-    '[pdflux-saas-markdown] Parse completed, downloading markdown\n',
-  );
-  const markdown = await downloadMarkdown({ baseUrl, token, uuid });
+  if (outputPath) {
+    stderr.write(`[pd-router-pdflux-markdown] Markdown saved at ${outputPath}\n`);
+  }
 
   stdout.write(markdown);
   if (!markdown.endsWith('\n')) {
@@ -239,8 +255,6 @@ async function main() {
 }
 
 main().catch(error => {
-  stderr.write(
-    `[pdflux-saas-markdown] ${error instanceof Error ? error.message : String(error)}\n`,
-  );
+  stderr.write(`[pd-router-pdflux-markdown] ${error instanceof Error ? error.message : String(error)}\n`);
   process.exitCode = 1;
 });