Add pdflux-saas-markdown skill.

Author: shangwenmo

pdflux-saas-markdown/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pdflux-saas-markdown
+description: 解析文档并获取文档内容，尤其适用于提取 PDF、DOCX、DOC、PPT、PPTX、PNG、JPG、JPEG 等文件中的正文与表格内容。用于将文件转换为 markdown、响应“转 markdown”这类需求、读取文档具体内容、基于文档内容执行后续分析或脚本处理；当需要编写脚本解析文档时，优先使用这个 skill。
+---
+
+# pdflux-saas-markdown
+
+执行一个 JavaScript 工作流，先把单个本地文件解析为 markdown，再基于 markdown 获取正文、表格和结构化内容。支持 PDF、Word、PPT 和图片等常见格式，适合文档解析、表格提取、内容核对，以及把文档内容交给后续脚本继续处理。
+
+## 运行方式
+
+```bash
+node .claude/skills/pdflux-saas-markdown/scripts/upload_to_markdown.js <local-file-path>
+```
+
+## 执行约束
+
+- 必须直接调用 `scripts/upload_to_markdown.js` 执行，不要根据下方行为约定自行重写上传、轮询、下载 markdown 的流程。
+- 行为约定仅用于说明脚本做什么、输出什么、何时适合使用，不是给模型手工照着执行的步骤。
+- 即使任务只是提取表格、获取字段、读取正文或为后续脚本准备输入，也必须先运行该脚本，再基于脚本产出的 markdown 继续处理。
+- 只有在脚本本身不可用、报错、或需要修复脚本时，才允许检查或修改脚本实现；在正常使用场景下不要绕过脚本。
+
+## 适用场景
+
+- 当用户要解析文档、获取文档具体内容或抽取文档表格时，使用这个 skill。
+- 当用户输入类似“转 markdown”“输出 markdown”“导出 markdown”“提取 markdown”时，使用这个 skill，并直接输出 markdown 内容。
+- 当后续任务依赖文档内容继续处理，例如生成摘要、抽取字段、编写脚本处理文档、对比表格或做规则校验时，优先先用这个 skill 解析文档。
+- 当只是需要文档内容供后续操作使用时，不默认向用户输出原始 markdown 全文；优先将 markdown 保存到临时文件，再读取、筛选、提取需要的内容。
+- 当用户明确要求“输出 markdown 原文”或表达的是“转 markdown”类直接转换需求时，直接展示完整 markdown。
+
+## 环境变量
+
+- `PAODINGAI_API_KEY`: 必填访问令牌。若未设置，提示 `Enter PAODINGAI_API_KEY:` 并接收手动输入。
+- `PAODINGAI_API_BASE_URL`: 可选 API 域名。默认值：`https://saas.pdflux.com`。
+
+## 脚本行为说明
+
+1. 优先从 `PAODINGAI_API_KEY` 读取令牌，缺失时回退到交互式输入。
+2. 使用 `Authorization: Bearer <token>` 调用 `/api/v1/saas/upload` 上传文件。
+3. 持续轮询 `/api/v1/saas/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，错误时返回非零退出码。

pdflux-saas-markdown/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PDFlux SaaS Markdown"
+  short_description: "Parse docs and tables from PDF, DOCX, and images"
+  default_prompt: "Always execute the bundled scripts/upload_to_markdown.js script to parse one local PDF, DOCX, PPT, image, or similar file. If the user explicitly asks to convert to markdown or output markdown, return the markdown content directly; otherwise extract only the document content or tables needed for the task."

pdflux-saas-markdown/scripts/upload_to_markdown.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+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 DEFAULT_BASE_URL = 'https://saas.pdflux.com';
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+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;
+  }
+
+  const rl = readline.createInterface({
+    input: stdin,
+    output: stderr,
+  });
+
+  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();
+  }
+}
+
+async function parseResponse(response) {
+  const contentType = response.headers.get('content-type') || '';
+  const bodyText = await response.text();
+  if (contentType.includes('application/json')) {
+    try {
+      return JSON.parse(bodyText);
+    } catch {
+      return { status: false, msg: bodyText || 'Invalid JSON response' };
+    }
+  }
+  return bodyText;
+}
+
+function extractApiError(payload, fallback) {
+  if (!payload) {
+    return fallback;
+  }
+  if (typeof payload === 'string') {
+    return payload || fallback;
+  }
+  if (typeof payload === 'object') {
+    return payload.msg || payload.message || JSON.stringify(payload);
+  }
+  return fallback;
+}
+
+async function uploadFile({ baseUrl, token, filePath }) {
+  const formData = new FormData();
+  const filename = path.basename(filePath);
+  const bytes = await fs.readFile(filePath);
+  const fileBlob = new Blob([bytes], { type: 'application/octet-stream' });
+  formData.append('file', fileBlob, filename);
+
+  const response = await fetch(`${baseUrl}/api/v1/saas/upload`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+    body: formData,
+  });
+
+  const payload = await parseResponse(response);
+  if (!response.ok) {
+    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')}`,
+    );
+  }
+
+  const uuid = payload?.data?.uuid;
+  if (!uuid) {
+    throw new Error(
+      `Upload succeeded but uuid is missing: ${JSON.stringify(payload)}`,
+    );
+  }
+
+  return uuid;
+}
+
+async function pollParsed({ baseUrl, token, uuid, pollIntervalMs, timeoutMs }) {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeoutMs) {
+    const response = await fetch(`${baseUrl}/api/v1/saas/document/${uuid}`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    });
+
+    const payload = await parseResponse(response);
+    if (!response.ok) {
+      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')}`,
+      );
+    }
+
+    const parsed = payload?.data?.parsed;
+    if (parsed === 2) {
+      return;
+    }
+    if (typeof parsed === 'number' && parsed < 0) {
+      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.`,
+  );
+}
+
+async function downloadMarkdown({ baseUrl, token, uuid }) {
+  const response = await fetch(
+    `${baseUrl}/api/v1/saas/document/${uuid}/markdown`,
+    {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    },
+  );
+
+  const contentType = response.headers.get('content-type') || '';
+  const bodyText = await response.text();
+
+  if (!response.ok) {
+    let errorMessage = bodyText;
+    if (contentType.includes('application/json')) {
+      try {
+        const payload = JSON.parse(bodyText);
+        errorMessage = extractApiError(payload, bodyText);
+      } catch {
+        // Keep bodyText
+      }
+    }
+    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')}`,
+        );
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+    }
+  }
+
+  return bodyText;
+}
+
+async function ensureInputFile(filePathArg) {
+  if (!filePathArg) {
+    throw new Error('Usage: node upload_to_markdown.js <local-file-path>');
+  }
+
+  const resolvedPath = path.resolve(filePathArg);
+  let stat;
+  try {
+    stat = await fs.stat(resolvedPath);
+  } catch {
+    throw new Error(`Input file does not exist: ${resolvedPath}`);
+  }
+
+  if (!stat.isFile()) {
+    throw new Error(`Input path is not a file: ${resolvedPath}`);
+  }
+
+  return resolvedPath;
+}
+
+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 });
+
+  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(
+    '[pdflux-saas-markdown] Parse completed, downloading markdown\n',
+  );
+  const markdown = await downloadMarkdown({ baseUrl, token, uuid });
+
+  stdout.write(markdown);
+  if (!markdown.endsWith('\n')) {
+    stdout.write('\n');
+  }
+}
+
+main().catch(error => {
+  stderr.write(
+    `[pdflux-saas-markdown] ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+});