@noedgeai-org/doc2x-mcp 0.1.2 → 0.1.3-dev.2.2

package/README.md

@@ -28,7 +28,7 @@
 ```json
 {
   "command": "npx",
-  "args": ["-y", "@noedgeai-org/doc2x-mcp"],
+  "args": ["-y", "@noedgeai-org/doc2x-mcp@latest"],
   "env": {
     "DOC2X_API_KEY": "sk-xxx",
     "DOC2X_BASE_URL": "https://v2.doc2x.noedgeai.com"
@@ -72,6 +72,63 @@ DOC2X_API_KEY=sk-xxx npm start
 - `doc2x_materialize_convert_zip`
 - `doc2x_debug_config`
 
+### PDF 解析模型（`doc2x_parse_pdf_submit` / `doc2x_parse_pdf_wait_text`）
+
+- 可选参数：`model`
+- 可选值：仅 `v3-2026`（最新模型）
+- 说明：不传 `model` 时默认使用 `v2`；若想体验最新模型，传：
+
+```json
+{
+  "model": "v3-2026"
+}
+```
+
+### 导出公式参数（`doc2x_convert_export_submit` / `doc2x_convert_export_wait`）
+
+- 必选参数：`formula_mode`（`normal` / `dollar`）
+- 可选参数：`formula_level`（`int32`，仅源解析任务为 `model=v3-2026` 时生效，`v2` 下无效）
+- 取值说明：
+  - `0`：不退化公式（保留原始 Markdown）
+  - `1`：行内公式变为普通文本（退化 `\\(...\\)` 和 `$...$`）
+  - `2`：全部公式变为普通文本（退化 `\\(...\\)`、`$...$`、`\\[...\\]`、`$$...$$`）
+
 ## 5) 协议
 
 MIT License，详见 `LICENSE`。
+
+## 6) 安装本仓库 Skill（可选）
+
+用于给 Codex CLI / Claude Code 增加一个“教大模型如何使用 doc2x-mcp tools 的 Skill”（便于按固定工作流调用 tools、导出与下载、以及排错）。
+
+不需要 clone 仓库的一键安装（推荐）：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh
+```
+
+重复执行同一条命令即可覆盖安装（默认会覆盖已存在目录）。
+
+在本仓库源码目录安装：
+
+```bash
+npm run skill:install
+```
+
+默认安装到：
+
+脚本默认安装到：
+
+- Codex CLI：`~/.codex/skills/public/doc2x-mcp`（用 `CODEX_HOME` 覆盖）
+- Claude Code：`~/.claude/skills/doc2x-mcp`（用 `CLAUDE_HOME` 覆盖）
+
+说明：
+
+- `--target auto`（默认）会同时安装到 Codex + Claude；如只想装其中一个，用 `--target codex|claude`。
+- PowerShell 7+ 一键安装：`irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`
+- Windows PowerShell 5.1 一键安装：`irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill-winps.ps1 | iex`
+
+覆盖安装目录示例：
+
+- mac/linux：`CODEX_HOME=/custom/.codex curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh -s -- --target codex`
+- Windows：`$env:CODEX_HOME="C:\\path\\.codex"; irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`

package/README_EN.md

@@ -72,6 +72,63 @@ DOC2X_API_KEY=sk-xxx npm start
 - `doc2x_materialize_convert_zip`
 - `doc2x_debug_config`
 
+### PDF Parse Model (`doc2x_parse_pdf_submit` / `doc2x_parse_pdf_wait_text`)
+
+- Optional parameter: `model`
+- Supported values: only `v3-2026` (latest model)
+- Notes: omit `model` to use default `v2`; to try the latest model, pass:
+
+```json
+{
+  "model": "v3-2026"
+}
+```
+
+### Export Formula Parameters (`doc2x_convert_export_submit` / `doc2x_convert_export_wait`)
+
+- Required parameter: `formula_mode` (`normal` / `dollar`)
+- Optional parameter: `formula_level` (`int32`, effective only when the source parse task uses `model=v3-2026`; ignored by `v2`)
+- Value mapping:
+  - `0`: keep formulas as-is (preserve original Markdown)
+  - `1`: degrade inline formulas to plain text (`\\(...\\)` and `$...$`)
+  - `2`: degrade all formulas to plain text (`\\(...\\)`, `$...$`, `\\[...\\]`, `$$...$$`)
+
 ## 5) License
 
 MIT License. See `LICENSE`.
+
+## 6) Install Repo Skill (Optional)
+
+Installs a tool-use skill for Codex CLI / Claude Code (teaches the LLM how to use doc2x-mcp tools with a standard workflow: submit/status/wait/export/download).
+
+One-command install without cloning (recommended):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh
+```
+
+Re-run the same command to overwrite (default behavior overwrites an existing destination directory).
+
+Install from this repo source directory:
+
+```bash
+npm run skill:install
+```
+
+Default destination:
+
+The script installs to:
+
+- Codex CLI: `~/.codex/skills/public/doc2x-mcp` (override via `CODEX_HOME`)
+- Claude Code: `~/.claude/skills/doc2x-mcp` (override via `CLAUDE_HOME`)
+
+Notes:
+
+- `--target auto` (default) installs to both Codex + Claude; use `--target codex|claude` to install only one.
+- PowerShell 7+ one-command install: `irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`
+- Windows PowerShell 5.1 one-command install: `irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill-winps.ps1 | iex`
+
+Override install dir examples:
+
+- mac/linux: `CODEX_HOME=/custom/.codex curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh -s -- --target codex`
+- Windows: `$env:CODEX_HOME="C:\\path\\.codex"; irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex`

package/dist/doc2x/convert.js

@@ -7,6 +7,7 @@ import { doc2xRequestJson, normalizeUrl } from '#doc2x/client';
 import { DOC2X_TASK_STATUS_FAILED, DOC2X_TASK_STATUS_SUCCESS } from '#doc2x/constants';
 import { HTTP_METHOD_GET, HTTP_METHOD_POST } from '#doc2x/http';
 import { v2 } from '#doc2x/paths';
+export const CONVERT_FORMULA_LEVELS = [0, 1, 2];
 function normalizeExportFilename(filename, to, mode) {
     const v = String(filename).trim();
     if (!v)
@@ -36,6 +37,8 @@ export async function convertExportSubmit(args) {
         to: args.to,
         formula_mode: args.formula_mode,
     };
+    if (args.formula_level != null)
+        body.formula_level = args.formula_level;
     if (args.merge_cross_page_forms != null)
         body.merge_cross_page_forms = args.merge_cross_page_forms;
     if (args.filename != null)

package/dist/doc2x/pdf.js

@@ -9,6 +9,7 @@ import { doc2xRequestJson, putToSignedUrl } from '#doc2x/client';
 import { DOC2X_TASK_STATUS_FAILED, DOC2X_TASK_STATUS_SUCCESS } from '#doc2x/constants';
 import { HTTP_METHOD_GET, HTTP_METHOD_POST } from '#doc2x/http';
 import { v2 } from '#doc2x/paths';
+export const PARSE_PDF_MODELS = ['v3-2026'];
 function mergePagesToTextWithLimit(result, joinWith, limits) {
     const pages = _.sortBy(_.isArray(result?.pages) ? result.pages : [], (p) => Number(p?.page_idx ?? 0));
     const maxPages = (limits?.maxOutputPages ?? 0) > 0 ? Number(limits?.maxOutputPages) : Number.POSITIVE_INFINITY;
@@ -53,11 +54,15 @@ function mergePagesToTextWithLimit(result, joinWith, limits) {
         truncated = true;
     return { text: parts.join(''), truncated, returnedPages, totalPages: pages.length };
 }
-async function preuploadPdfWithRetry() {
+async function preuploadPdfWithRetry(model) {
+    const body = {};
+    if (model)
+        body.model = model;
+    const payload = Object.keys(body).length > 0 ? { body } : undefined;
     let attempt = 0;
     while (true) {
         try {
-            const data = await doc2xRequestJson(HTTP_METHOD_POST, v2('/parse/preupload'));
+            const data = await doc2xRequestJson(HTTP_METHOD_POST, v2('/parse/preupload'), payload);
             return { uid: String(data.uid), url: String(data.url) };
         }
         catch (e) {
@@ -69,7 +74,7 @@ async function preuploadPdfWithRetry() {
         }
     }
 }
-export async function parsePdfSubmit(pdfPath) {
+export async function parsePdfSubmit(pdfPath, opts) {
     const p = path.resolve(pdfPath);
     if (!p.toLowerCase().endsWith('.pdf'))
         throw new ToolError({
@@ -78,12 +83,13 @@ export async function parsePdfSubmit(pdfPath) {
             retryable: false,
         });
     await fsp.access(p);
-    let data = await preuploadPdfWithRetry();
+    const model = opts?.model;
+    let data = await preuploadPdfWithRetry(model);
     try {
         await putToSignedUrl(String(data.url), p);
     }
     catch {
-        data = await preuploadPdfWithRetry();
+        data = await preuploadPdfWithRetry(model);
         await putToSignedUrl(String(data.url), p);
     }
     return { uid: String(data.uid) };

package/dist/mcp/registerTools.js

@@ -3,11 +3,11 @@ import path from 'node:path';
 import _ from 'lodash';
 import { z } from 'zod';
 import { CONFIG, RESOLVED_KEY, parseDownloadUrlAllowlist } from '#config';
-import { convertExportResult, convertExportSubmit, convertExportWaitByUid } from '#doc2x/convert';
+import { CONVERT_FORMULA_LEVELS, convertExportResult, convertExportSubmit, convertExportWaitByUid, } from '#doc2x/convert';
 import { downloadUrlToFile } from '#doc2x/download';
 import { parseImageLayoutStatus, parseImageLayoutSubmit, parseImageLayoutSync, parseImageLayoutWaitTextByUid, } from '#doc2x/image';
 import { materializeConvertZip } from '#doc2x/materialize';
-import { parsePdfStatus, parsePdfSubmit, parsePdfWaitTextByUid } from '#doc2x/pdf';
+import { PARSE_PDF_MODELS, parsePdfStatus, parsePdfSubmit, parsePdfWaitTextByUid, } from '#doc2x/pdf';
 import { ToolError } from '#errors';
 import { TOOL_ERROR_CODE_INVALID_ARGUMENT } from '#errorCodes';
 import { asErrorResult, asJsonResult, asTextResult } from '#mcp/results';
@@ -19,6 +19,23 @@ async function fileSig(p) {
 function sameSig(a, b) {
     return a.absPath === b.absPath && a.size === b.size && a.mtimeMs === b.mtimeMs;
 }
+function normalizeParsePdfModel(model) {
+    return model ?? 'v2';
+}
+function makePdfUidCacheKey(absPath, model) {
+    return JSON.stringify([absPath, normalizeParsePdfModel(model)]);
+}
+function makeConvertSubmitKey(args) {
+    return JSON.stringify({
+        uid: args.uid,
+        to: args.to,
+        formula_mode: args.formula_mode ?? null,
+        formula_level: args.formula_level ?? null,
+        filename: args.filename ?? null,
+        filename_mode: args.filename_mode ?? null,
+        merge_cross_page_forms: args.merge_cross_page_forms ?? null,
+    });
+}
 export function registerTools(server) {
     const pdfUidCache = new Map();
     const imageUidCache = new Map();
@@ -30,12 +47,16 @@ export function registerTools(server) {
                 .string()
                 .min(1)
                 .describe("Absolute path to a local PDF file. Use an absolute path (relative paths are resolved from the MCP server process cwd, which may be '/'). Must end with '.pdf'."),
+            model: z
+                .enum(PARSE_PDF_MODELS)
+                .optional()
+                .describe("Optional parse model. Use 'v3-2026' to try the latest model. Omit this field to use default v2."),
         },
-    }, async ({ pdf_path }) => {
+    }, async ({ pdf_path, model }) => {
         try {
             const sig = await fileSig(pdf_path);
-            const res = await parsePdfSubmit(pdf_path);
-            pdfUidCache.set(sig.absPath, { sig, uid: res.uid });
+            const res = await parsePdfSubmit(pdf_path, { model });
+            pdfUidCache.set(makePdfUidCacheKey(sig.absPath, model), { sig, uid: res.uid });
             return asJsonResult(res);
         }
         catch (e) {
@@ -84,6 +105,10 @@ export function registerTools(server) {
                 .min(0)
                 .optional()
                 .describe('Max pages to merge into returned text (0 = unlimited). Default can be set via env DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES.'),
+            model: z
+                .enum(PARSE_PDF_MODELS)
+                .optional()
+                .describe("Optional parse model used only when submitting from pdf_path. Use 'v3-2026' to try latest model. Omit this field to use default v2."),
         },
     }, async (args) => {
         try {
@@ -122,10 +147,12 @@ export function registerTools(server) {
                 }));
             }
             const sig = await fileSig(pdfPath);
-            const cached = pdfUidCache.get(sig.absPath);
+            const model = args.model;
+            const cacheKey = makePdfUidCacheKey(sig.absPath, model);
+            const cached = pdfUidCache.get(cacheKey);
             const resolvedUid = cached && sameSig(cached.sig, sig) ? cached.uid : '';
-            const finalUid = resolvedUid || (await parsePdfSubmit(pdfPath)).uid;
-            pdfUidCache.set(sig.absPath, { sig, uid: finalUid });
+            const finalUid = resolvedUid || (await parsePdfSubmit(pdfPath, { model })).uid;
+            pdfUidCache.set(cacheKey, { sig, uid: finalUid });
             const out = await parsePdfWaitTextByUid({
                 uid: finalUid,
                 poll_interval_ms: args.poll_interval_ms,
@@ -147,6 +174,14 @@ export function registerTools(server) {
             uid: z.string().min(1).describe('Doc2x parse task uid returned by doc2x_parse_pdf_submit.'),
             to: z.enum(['md', 'tex', 'docx']),
             formula_mode: z.enum(['normal', 'dollar']),
+            formula_level: z
+                .union([
+                z.literal(CONVERT_FORMULA_LEVELS[0]),
+                z.literal(CONVERT_FORMULA_LEVELS[1]),
+                z.literal(CONVERT_FORMULA_LEVELS[2]),
+            ])
+                .optional()
+                .describe('Optional formula degradation level. Effective only when source parse uses model=v3-2026 (ignored by v2). 0: keep formulas, 1: degrade inline formulas, 2: degrade inline and block formulas.'),
             filename: z
                 .string()
                 .describe("Optional output filename (for md/tex only). Tip: pass a basename WITHOUT extension to avoid getting 'name.md.md' / 'name.tex.tex'.")
@@ -159,14 +194,7 @@ export function registerTools(server) {
         },
     }, async (args) => {
         try {
-            const key = JSON.stringify({
-                uid: args.uid,
-                to: args.to,
-                formula_mode: args.formula_mode,
-                filename: args.filename ?? null,
-                filename_mode: args.filename_mode ?? null,
-                merge_cross_page_forms: args.merge_cross_page_forms ?? null,
-            });
+            const key = makeConvertSubmitKey(args);
             const res = await convertExportSubmit(args);
             convertSubmitCache.add(key);
             return asJsonResult(res);
@@ -196,6 +224,14 @@ export function registerTools(server) {
                 .enum(['md', 'tex', 'docx'])
                 .describe('Expected target format. Used to verify the result URL.'),
             formula_mode: z.enum(['normal', 'dollar']).optional(),
+            formula_level: z
+                .union([
+                z.literal(CONVERT_FORMULA_LEVELS[0]),
+                z.literal(CONVERT_FORMULA_LEVELS[1]),
+                z.literal(CONVERT_FORMULA_LEVELS[2]),
+            ])
+                .optional()
+                .describe('Optional formula degradation level used when this tool auto-submits export (formula_mode must be provided). Effective only when source parse uses model=v3-2026 (ignored by v2).'),
             filename: z.string().optional(),
             filename_mode: z.enum(['auto', 'raw']).optional(),
             merge_cross_page_forms: z.boolean().optional(),
@@ -205,19 +241,13 @@ export function registerTools(server) {
     }, async (args) => {
         try {
             if (args.formula_mode) {
-                const key = JSON.stringify({
-                    uid: args.uid,
-                    to: args.to,
-                    formula_mode: args.formula_mode,
-                    filename: args.filename ?? null,
-                    filename_mode: args.filename_mode ?? null,
-                    merge_cross_page_forms: args.merge_cross_page_forms ?? null,
-                });
+                const key = makeConvertSubmitKey(args);
                 if (!convertSubmitCache.has(key)) {
                     await convertExportSubmit({
                         uid: args.uid,
                         to: args.to,
                         formula_mode: args.formula_mode,
+                        formula_level: args.formula_level,
                         filename: args.filename,
                         filename_mode: args.filename_mode,
                         merge_cross_page_forms: args.merge_cross_page_forms,

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@noedgeai-org/doc2x-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3-dev.2.2",
   "description": "Doc2x MCP server (stdio, MCP SDK).",
   "license": "MIT",
   "engines": {
     "node": ">=18"
   },
+  "packageManager": "pnpm@10.26.2",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -16,19 +17,26 @@
     "./LICENSE",
     "./README.md",
     "./README_EN.md",
+    "./scripts/install-skill.sh",
+    "./scripts/install-skill.ps1",
+    "./scripts/install-skill-winps.ps1",
+    "./skills/doc2x-mcp/SKILL.md",
     "./package.json"
   ],
   "scripts": {
     "build": "node ./node_modules/typescript/bin/tsc -p tsconfig.json",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "skill:install": "sh scripts/install-skill.sh",
+    "skill:install:ps": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/install-skill.ps1",
+    "skill:install:winps": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install-skill-winps.ps1",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "1.26.0",
     "@types/lodash": "^4.17.23",
-    "lodash": "^4.17.21",
+    "lodash": "4.17.23",
     "zod": "latest"
   },
   "devDependencies": {

package/scripts/install-skill-winps.ps1

@@ -0,0 +1,172 @@
+[CmdletBinding()]
+Param(
+  [ValidateSet("auto", "codex", "claude")]
+  [string]$Target = "auto",
+
+  [string]$Category = "public",
+  [string]$Name = "doc2x-mcp",
+  [string]$Dest = "",
+
+  [switch]$Force,
+  [switch]$DryRun
+)
+
+Set-StrictMode -Version 2.0
+$ErrorActionPreference = "Stop"
+
+# -------------------------------------------------------------------
+# Best-effort TLS defaults for GitHub (Windows PowerShell 5.1)
+# -------------------------------------------------------------------
+
+try {
+  [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+} catch {
+  # ignore
+}
+
+# -------------------------------------------------------------------
+# Environment & paths
+# -------------------------------------------------------------------
+
+$userHome = $HOME
+if (-not $userHome) {
+  $userHome = $env:USERPROFILE
+}
+if (-not $userHome) {
+  throw 'Cannot resolve home directory ($HOME / $env:USERPROFILE).'
+}
+
+$codexHome = $env:CODEX_HOME
+if (-not $codexHome) {
+  $codexHome = Join-Path $userHome ".codex"
+}
+
+$claudeHome = $env:CLAUDE_HOME
+if (-not $claudeHome) {
+  $claudeHome = Join-Path $userHome ".claude"
+}
+
+$codexRoot = Join-Path $codexHome "skills"
+$claudeRoot = Join-Path $claudeHome "skills"
+
+# -------------------------------------------------------------------
+# Helper functions
+# -------------------------------------------------------------------
+
+function Get-InstallRoots {
+  param(
+    [string]$Target,
+    [string]$CodexRoot,
+    [string]$ClaudeRoot
+  )
+
+  switch ($Target) {
+    "codex" { return @($CodexRoot) }
+    "claude" { return @($ClaudeRoot) }
+    default {
+      $roots = @()
+      if (Test-Path $CodexRoot) { $roots += $CodexRoot }
+      if (Test-Path $ClaudeRoot) { $roots += $ClaudeRoot }
+      if ($roots.Count -gt 0) {
+        return $roots
+      }
+      return @($CodexRoot)
+    }
+  }
+}
+
+function New-TempFilePath {
+  return [System.IO.Path]::Combine(
+    [System.IO.Path]::GetTempPath(),
+    ([System.Guid]::NewGuid().ToString() + ".md")
+  )
+}
+
+# -------------------------------------------------------------------
+# Resolve install roots
+# -------------------------------------------------------------------
+
+$roots = Get-InstallRoots -Target $Target -CodexRoot $codexRoot -ClaudeRoot $claudeRoot
+
+if ($Dest -and $roots.Count -gt 1) {
+  throw "-Dest cannot be used when installing to multiple targets."
+}
+
+# -------------------------------------------------------------------
+# Resolve SKILL.md source
+# -------------------------------------------------------------------
+
+$rawBase = $env:DOC2X_MCP_RAW_BASE
+if (-not $rawBase) {
+  $rawBase = "https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main"
+}
+$remoteSkillMdUrl = "$rawBase/skills/doc2x-mcp/SKILL.md"
+
+$localSkillMdPath = ""
+if (Test-Path ".\skills\doc2x-mcp\SKILL.md") {
+  $localSkillMdPath = ".\skills\doc2x-mcp\SKILL.md"
+}
+
+# -------------------------------------------------------------------
+# Dry run
+# -------------------------------------------------------------------
+
+if ($DryRun) {
+  [pscustomobject]@{
+    roots               = $roots
+    remote_skill_md_url = $remoteSkillMdUrl
+    local_skill_md_path = $localSkillMdPath
+    category            = $Category
+    name                = $Name
+    dest                = $Dest
+  } | ConvertTo-Json -Depth 4
+  return
+}
+
+# -------------------------------------------------------------------
+# Download / install
+# -------------------------------------------------------------------
+
+$tempSkillMd = ""
+$tempIsTemp = $false
+
+try {
+  if ($localSkillMdPath) {
+    $tempSkillMd = $localSkillMdPath
+  } else {
+    $tempSkillMd = New-TempFilePath
+    $tempIsTemp = $true
+    Invoke-WebRequest -UseBasicParsing -Uri $remoteSkillMdUrl -OutFile $tempSkillMd | Out-Null
+  }
+
+  foreach ($root in $roots) {
+    if ($Dest) {
+      $destDir = $Dest
+    } elseif ($root -eq $codexRoot) {
+      $destDir = Join-Path (Join-Path $root $Category) $Name
+    } elseif ($root -eq $claudeRoot) {
+      $destDir = Join-Path $root $Name
+    } else {
+      $destDir = Join-Path (Join-Path $root $Category) $Name
+    }
+
+    $skillMdDest = Join-Path $destDir "SKILL.md"
+
+    if (Test-Path $destDir) {
+      if ($Dest -and (-not $Force)) {
+        throw "Destination already exists: $destDir`nRe-run with -Force to overwrite an explicit -Dest."
+      }
+      Remove-Item -Recurse -Force $destDir
+    }
+
+    New-Item -ItemType Directory -Force -Path $destDir | Out-Null
+    Copy-Item -Force $tempSkillMd $skillMdDest
+
+    Write-Output "Installed skill to: $destDir"
+  }
+}
+finally {
+  if ($tempIsTemp -and $tempSkillMd -and (Test-Path $tempSkillMd)) {
+    Remove-Item -Force $tempSkillMd
+  }
+}

package/scripts/install-skill.ps1

@@ -0,0 +1,147 @@
+[CmdletBinding()]
+Param(
+  [ValidateSet("auto", "codex", "claude")]
+  [string]$Target = "auto",
+
+  [string]$Category = "public",
+  [string]$Name = "doc2x-mcp",
+  [string]$Dest = "",
+
+  [switch]$Force,
+  [switch]$DryRun
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+# -------------------------------------------------------------------
+# Environment & paths
+# -------------------------------------------------------------------
+
+$userHome = $HOME
+if (-not $userHome) {
+  throw '$HOME is not set'
+}
+
+$codexHome  = $env:CODEX_HOME  ?? (Join-Path $userHome ".codex")
+$claudeHome = $env:CLAUDE_HOME ?? (Join-Path $userHome ".claude")
+
+$codexRoot  = Join-Path $codexHome  "skills"
+$claudeRoot = Join-Path $claudeHome "skills"
+
+# -------------------------------------------------------------------
+# Helper functions
+# -------------------------------------------------------------------
+
+function Get-InstallRoots {
+  param(
+    [string]$Target,
+    [string]$CodexRoot,
+    [string]$ClaudeRoot
+  )
+
+  switch ($Target) {
+    "codex"  { return @($CodexRoot) }
+    "claude" { return @($ClaudeRoot) }
+    default {
+      $roots = @()
+      if (Test-Path $CodexRoot)  { $roots += $CodexRoot }
+      if (Test-Path $ClaudeRoot) { $roots += $ClaudeRoot }
+      return ($roots.Count -gt 0) ? $roots : @($CodexRoot)
+    }
+  }
+}
+
+function New-TempFilePath {
+  return [System.IO.Path]::Combine(
+    [System.IO.Path]::GetTempPath(),
+    ([System.Guid]::NewGuid().ToString() + ".md")
+  )
+}
+
+# -------------------------------------------------------------------
+# Resolve install roots
+# -------------------------------------------------------------------
+
+$roots = Get-InstallRoots -Target $Target -CodexRoot $codexRoot -ClaudeRoot $claudeRoot
+
+if ($Dest -and $roots.Count -gt 1) {
+  throw "-Dest cannot be used when installing to multiple targets."
+}
+
+# -------------------------------------------------------------------
+# Resolve SKILL.md source
+# -------------------------------------------------------------------
+
+$rawBase = $env:DOC2X_MCP_RAW_BASE ?? "https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main"
+$remoteSkillMdUrl = "$rawBase/skills/doc2x-mcp/SKILL.md"
+
+$localSkillMdPath = ""
+if (Test-Path ".\skills\doc2x-mcp\SKILL.md") {
+  $localSkillMdPath = ".\skills\doc2x-mcp\SKILL.md"
+}
+
+# -------------------------------------------------------------------
+# Dry run
+# -------------------------------------------------------------------
+
+if ($DryRun) {
+  [pscustomobject]@{
+    roots                  = $roots
+    remote_skill_md_url    = $remoteSkillMdUrl
+    local_skill_md_path    = $localSkillMdPath
+    category               = $Category
+    name                   = $Name
+    dest                   = $Dest
+  } | ConvertTo-Json -Depth 4
+  return
+}
+
+# -------------------------------------------------------------------
+# Download / install
+# -------------------------------------------------------------------
+
+$tempSkillMd = ""
+$tempIsTemp  = $false
+
+try {
+  if ($localSkillMdPath) {
+    $tempSkillMd = $localSkillMdPath
+  } else {
+    $tempSkillMd = New-TempFilePath
+    $tempIsTemp  = $true
+    Invoke-WebRequest -Uri $remoteSkillMdUrl -OutFile $tempSkillMd | Out-Null
+  }
+
+  foreach ($root in $roots) {
+
+    if ($Dest) {
+      $destDir = $Dest
+    } elseif ($root -eq $codexRoot) {
+      $destDir = Join-Path (Join-Path $root $Category) $Name
+    } elseif ($root -eq $claudeRoot) {
+      $destDir = Join-Path $root $Name
+    } else {
+      $destDir = Join-Path (Join-Path $root $Category) $Name
+    }
+
+    $skillMdDest = Join-Path $destDir "SKILL.md"
+
+    if (Test-Path $destDir) {
+      if ($Dest -and (-not $Force)) {
+        throw "Destination already exists: $destDir`nRe-run with -Force to overwrite an explicit -Dest."
+      }
+      Remove-Item -Recurse -Force $destDir
+    }
+
+    New-Item -ItemType Directory -Force -Path $destDir | Out-Null
+    Copy-Item -Force $tempSkillMd $skillMdDest
+
+    Write-Output "Installed skill to: $destDir"
+  }
+}
+finally {
+  if ($tempIsTemp -and $tempSkillMd -and (Test-Path $tempSkillMd)) {
+    Remove-Item -Force $tempSkillMd
+  }
+}

package/scripts/install-skill.sh

@@ -0,0 +1,195 @@
+#!/bin/sh
+set -eu
+
+usage() {
+  cat <<'EOF'
+Install doc2x-mcp skill into Codex CLI / Claude Code skills directory.
+
+Usage:
+  sh install-skill.sh [--target auto|codex|claude]
+  curl -fsSL <URL>/scripts/install-skill.sh | sh
+
+Options:
+  --target    auto|codex|claude (default: auto; auto installs to both)
+  --category  Codex category under skills root (default: public; ignored for Claude)
+  --name      skill directory name (default: doc2x-mcp)
+  --dest      explicit destination directory (overrides target/category/name)
+  --force     allow overwriting when --dest points to an existing directory
+  --dry-run   print planned paths only
+
+Env:
+  CODEX_HOME            override Codex home (default: ~/.codex)
+  CLAUDE_HOME           override Claude home (default: ~/.claude)
+  DOC2X_MCP_RAW_BASE    raw base URL (default: https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main)
+EOF
+}
+
+TARGET="auto"
+CATEGORY="public"
+NAME="doc2x-mcp"
+FORCE="0"
+DRY_RUN="0"
+DEST=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target)
+      TARGET="${2:-}"
+      shift 2
+      ;;
+    --category)
+      CATEGORY="${2:-}"
+      shift 2
+      ;;
+    --name)
+      NAME="${2:-}"
+      shift 2
+      ;;
+    --dest)
+      DEST="${2:-}"
+      shift 2
+      ;;
+    --force)
+      FORCE="1"
+      shift 1
+      ;;
+    --dry-run)
+      DRY_RUN="1"
+      shift 1
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [ "$TARGET" != "auto" ] && [ "$TARGET" != "codex" ] && [ "$TARGET" != "claude" ]; then
+  echo "Invalid --target: $TARGET (expected auto|codex|claude)" >&2
+  exit 1
+fi
+
+HOME_DIR="${HOME:-}"
+if [ -z "$HOME_DIR" ]; then
+  echo "\$HOME is not set" >&2
+  exit 1
+fi
+
+CODEX_HOME_DIR="${CODEX_HOME:-$HOME_DIR/.codex}"
+CLAUDE_HOME_DIR="${CLAUDE_HOME:-$HOME_DIR/.claude}"
+
+CODEX_SKILLS_ROOT="$CODEX_HOME_DIR/skills"
+CLAUDE_SKILLS_ROOT="$CLAUDE_HOME_DIR/skills"
+
+pick_skills_roots() {
+  if [ "$TARGET" = "codex" ]; then
+    printf '%s\n' "$CODEX_SKILLS_ROOT"
+    return
+  fi
+  if [ "$TARGET" = "claude" ]; then
+    printf '%s\n' "$CLAUDE_SKILLS_ROOT"
+    return
+  fi
+
+  printf '%s\n' "$CODEX_SKILLS_ROOT"
+  printf '%s\n' "$CLAUDE_SKILLS_ROOT"
+}
+
+SKILLS_ROOTS="$(pick_skills_roots)"
+
+RAW_BASE="${DOC2X_MCP_RAW_BASE:-https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main}"
+REMOTE_SKILL_MD_URL="$RAW_BASE/skills/doc2x-mcp/SKILL.md"
+
+LOCAL_SKILL_MD_PATH=""
+if [ -f "./skills/doc2x-mcp/SKILL.md" ]; then
+  LOCAL_SKILL_MD_PATH="./skills/doc2x-mcp/SKILL.md"
+fi
+
+count_lines() {
+  echo "$1" | awk 'NF{c++} END{print c+0}'
+}
+
+ROOTS_COUNT="$(count_lines "$SKILLS_ROOTS")"
+if [ -n "$DEST" ] && [ "$ROOTS_COUNT" -gt 1 ]; then
+  echo "--dest cannot be used when installing to multiple targets (auto found both Codex/Claude)." >&2
+  exit 1
+fi
+
+if [ "$DRY_RUN" = "1" ]; then
+  echo "skills_roots=$(echo "$SKILLS_ROOTS" | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
+  echo "remote_skill_md_url=$REMOTE_SKILL_MD_URL"
+  echo "local_skill_md_path=$LOCAL_SKILL_MD_PATH"
+  echo "category=$CATEGORY"
+  echo "name=$NAME"
+  echo "dest=$DEST"
+  exit 0
+fi
+
+tmp_skill_md=""
+tmp_skill_md_is_temp="0"
+cleanup() {
+  if [ "${tmp_skill_md_is_temp:-0}" = "1" ] && [ -n "${tmp_skill_md:-}" ] && [ -f "$tmp_skill_md" ]; then
+    rm -f "$tmp_skill_md"
+  fi
+}
+trap cleanup EXIT INT TERM
+
+prepare_skill_md() {
+  if [ -n "$LOCAL_SKILL_MD_PATH" ]; then
+    tmp_skill_md="$LOCAL_SKILL_MD_PATH"
+    tmp_skill_md_is_temp="0"
+    return
+  fi
+  tmp_skill_md="$(mktemp -t doc2x-mcp-skill.XXXXXX 2>/dev/null || mktemp)"
+  tmp_skill_md_is_temp="1"
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL "$REMOTE_SKILL_MD_URL" -o "$tmp_skill_md"
+    return
+  fi
+  if command -v wget >/dev/null 2>&1; then
+    wget -qO "$tmp_skill_md" "$REMOTE_SKILL_MD_URL"
+    return
+  fi
+  echo "Neither curl nor wget found; cannot download SKILL.md" >&2
+  exit 1
+}
+
+install_to_root() {
+  root="$1"
+  if [ -n "$DEST" ]; then
+    dest_dir="$DEST"
+  elif [ "$root" = "$CODEX_SKILLS_ROOT" ]; then
+    dest_dir="$root/$CATEGORY/$NAME"
+  elif [ "$root" = "$CLAUDE_SKILLS_ROOT" ]; then
+    dest_dir="$root/$NAME"
+  else
+    dest_dir="$root/$CATEGORY/$NAME"
+  fi
+
+  if [ -e "$dest_dir" ]; then
+    if [ -n "$DEST" ] && [ "$FORCE" != "1" ]; then
+      echo "Destination already exists: $dest_dir" >&2
+      echo "Re-run with --force to overwrite an explicit --dest." >&2
+      exit 1
+    fi
+    rm -rf "$dest_dir"
+  fi
+
+  mkdir -p "$dest_dir"
+  cp "$tmp_skill_md" "$dest_dir/SKILL.md"
+  echo "Installed skill to: $dest_dir"
+}
+
+prepare_skill_md
+
+while IFS= read -r root; do
+  [ -n "$root" ] || continue
+  install_to_root "$root"
+done <<EOF
+$SKILLS_ROOTS
+EOF

package/skills/doc2x-mcp/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: doc2x-mcp
+description: 使用 Doc2x MCP 工具完成文档解析与转换：对 PDF/扫描件/图片做 OCR 与版面解析，抽取文本/表格，导出为 Markdown/LaTeX(TeX)/DOCX 并下载落盘（submit/status/wait/export/download）。当用户提到 PDF/pdfs、scanned PDF、OCR、image-to-text、extract text/tables、表格抽取、文档转换/convert、导出/export、Markdown、LaTeX/TeX、DOCX、doc2x、doc2x-mcp、MCP 时使用。
+---
+
+# Doc2x MCP Tool-Use Skill (for LLM)
+
+## 你要做什么
+
+你是一个会调用 MCP tools 的助手。凡是涉及 PDF/图片的“解析/抽取/导出/下载”，必须通过 `doc2x-mcp` tools 执行真实操作：
+
+- 不要臆测/伪造 `uid`、`url`、文件内容或导出结果
+- 不要跳过工具步骤直接输出“看起来合理”的内容
+
+## 全局约束（必须遵守）
+
+1. 路径必须是绝对路径  
+   `pdf_path` / `image_path` / `output_path` / `output_dir` 都应使用绝对路径；相对路径可能会被 server 以意外的 cwd 解析导致失败。
+
+2. 扩展名约束  
+   `doc2x_parse_pdf_submit.pdf_path` 必须以 `.pdf` 结尾；图片解析使用 `png/jpg`。
+
+3. 不要并发重复提交导出  
+   同一个 `uid` 对同一种导出配置（`to + formula_mode + formula_level (+ filename + filename_mode + merge_cross_page_forms...)`）不要并行重复 submit。
+
+4. 不要泄露密钥  
+   永远不要回显/记录 `DOC2X_API_KEY`。排错只用 `doc2x_debug_config` 的 `apiKeyLen/apiKeyPrefix/apiKeySource`。
+
+5. 不要伪造下载 URL  
+   下载必须使用 `doc2x_convert_export_*` 返回的 `url`；不要自己拼接。
+
+6. 参数生效边界  
+   `model` 仅用于 PDF 解析提交（默认 `v2`，可选 `v3-2026`）；`formula_level` 仅用于导出（`doc2x_convert_export_*`），并且只在源解析任务使用 `v3-2026` 时生效（`v2` 下无效）。
+
+## 关键参数语义（避免误用）
+
+- `doc2x_parse_pdf_submit` / `doc2x_parse_pdf_wait_text(pdf_path 提交分支)`  
+  - 可选 `model: "v3-2026"`；不传则默认 `v2`。
+- `doc2x_convert_export_submit` / `doc2x_convert_export_wait`  
+  - `formula_mode`：`"normal"` 或 `"dollar"`（关键参数，建议总是显式传入）。  
+  - `formula_level`：`0 | 1 | 2`（可选）  
+    - `0`：不退化公式（保留原始 Markdown）
+    - `1`：行内公式退化为普通文本（`\(...\)`、`$...$`）
+    - `2`：行内 + 块级公式全部退化为普通文本（`\(...\)`、`$...$`、`\[...\]`、`$$...$$`）
+
+## Tool 选择（按用户目标）
+
+- **PDF 解析任务**：`doc2x_parse_pdf_submit` → `doc2x_parse_pdf_status`
+- **少量预览/摘要**：`doc2x_parse_pdf_wait_text`（可能截断；要完整内容请导出文件）
+- **导出文件（md/tex/docx）**：`doc2x_convert_export_submit` → `doc2x_convert_export_wait`（或直接 `doc2x_convert_export_wait` 走兼容模式一键导出）
+- **下载落盘**：`doc2x_download_url_to_file`
+- **图片版面解析**：`doc2x_parse_image_layout_sync` 或 `doc2x_parse_image_layout_submit` → `doc2x_parse_image_layout_wait_text`
+- **解包资源 zip**：`doc2x_materialize_convert_zip`
+- **配置排错**：`doc2x_debug_config`
+
+## 标准工作流（照做）
+
+### 工作流 A：批量 PDF → 导出文件（MD/TEX/DOCX，高效并行版）
+
+适用于“多个 PDF 批量导出并落盘（.md / .tex / .docx）”。核心原则：
+
+- `doc2x_parse_pdf_submit` 可并行（批量提交）
+- `doc2x_parse_pdf_status` 可并行（批量轮询）
+- **流水线式并行**：某个 `uid` 一旦解析成功，立刻开始该 `uid` 的导出+下载（不必等所有 PDF 都解析完）
+- 不同 `uid` 的导出与下载可并行
+- **同一个 `uid` 的同一种导出配置（`to + formula_mode + formula_level (+ filename + filename_mode + merge_cross_page_forms...)`）不要并行重复提交**
+- 同一个 `uid` 若要导出多种格式（例如 md + docx + tex），建议**按格式串行**，但不同 `uid` 仍可并行
+
+**批量提交解析任务（并行）**
+
+- 对每个 `pdf_path` 调用：`doc2x_parse_pdf_submit({ pdf_path, model? })` → `{ uid }`
+
+**等待解析完成（并行）**
+
+- 对每个 `uid` 轮询：`doc2x_parse_pdf_status({ uid })` 直到 `status="success"`
+- 若 `status="failed"`：汇报 `detail`，该文件停止后续步骤
+
+**导出目标格式（并行，按 uid）**
+
+推荐用 `doc2x_convert_export_wait` 走“兼容模式一键导出”（当你提供 `formula_mode` 且本进程未提交过该导出时，会自动 submit 一次，然后 wait），避免你手动拆成 submit+wait：
+
+- DOCX：`doc2x_convert_export_wait({ uid, to: "docx", formula_mode: "normal", formula_level? })` → `{ status: "success", url }`
+- Markdown：`doc2x_convert_export_wait({ uid, to: "md", formula_mode: "normal", formula_level?, filename?, filename_mode? })` → `{ status: "success", url }`
+- LaTeX：`doc2x_convert_export_wait({ uid, to: "tex", formula_mode: "dollar", formula_level? })` → `{ status: "success", url }`
+
+（或显式两步：`doc2x_convert_export_submit(...)` → `doc2x_convert_export_wait({ uid, to })`）
+
+**补充建议**
+
+- `formula_mode` 是关键参数：建议总是显式传入（`"normal"` / `"dollar"`，按用户偏好选择；常见：`md/docx` 用 `"normal"`、`tex` 用 `"dollar"`）
+- 需要做公式退化时显式传 `formula_level`（`0/1/2`）；若不需要退化，建议显式传 `0`，避免调用端默认值歧义
+- `filename`/`filename_mode` 主要用于 `md/tex`：传不带扩展名的 basename，并配合 `filename_mode: "auto"`（避免 `name.md.md` / `name.tex.tex`）
+- 对同一个 `uid` 做多格式导出时，先确定顺序（例如先 md 再 docx），逐个完成再进行下一个格式
+
+**批量下载（并行）**
+
+- `doc2x_download_url_to_file({ url, output_path })` → `{ output_path, bytes_written }`
+- `output_path` 必须为绝对路径，且每个文件应唯一（建议用原文件名 + 对应扩展名：`.md` / `.tex` / `.docx`）
+
+**并发建议**
+
+- 10 个 PDF 以内通常可以直接并行；更多文件建议分批/限流（避免触发超时/限流）
+
+**向用户回报（按文件汇总）**
+
+- 成功：列出每个输入文件对应的 `output_path` 与 `bytes_written`
+- 失败：列出失败文件与错误原因（包含 `uid` 与 `detail`/错误码），并说明其余文件不受影响
+
+### 工作流 B：PDF → Markdown 文件（推荐）
+
+当用户目标是“拿到完整 Markdown / 落盘”，主链路应当是导出与下载，不要依赖 `doc2x_parse_pdf_wait_text`。
+
+**提交解析任务**
+
+- `doc2x_parse_pdf_submit({ pdf_path, model? })` → `{ uid }`
+
+**等待解析完成**
+
+- 轮询 `doc2x_parse_pdf_status({ uid })` 直到 `status="success"`（失败则带 `detail` 汇报）
+
+**导出 Markdown**
+
+- `doc2x_convert_export_wait({ uid, to: "md", formula_mode: "normal", formula_level?, filename?, filename_mode? })` → `{ status: "success", url }`
+
+**下载落盘**
+
+- `doc2x_download_url_to_file({ url, output_path })` → `{ output_path, bytes_written }`
+
+**向用户回报**
+
+- 回复用户：保存路径、文件大小、`uid`（必要时附上 `url`）
+
+### 工作流 C：PDF → 文本预览（可控长度）
+
+当用户只需要“摘要/少量预览”时才用：
+
+- `doc2x_parse_pdf_wait_text({ pdf_path | uid, max_output_chars?, max_output_pages? })`
+
+如果返回包含截断提示（`[doc2x-mcp] Output truncated ...`），应切换到“工作流 B”导出 md 获取完整内容。
+
+### 工作流 D：PDF → LaTeX / DOCX
+
+- LaTeX：把 `to` 设为 `"tex"`
+- Word：把 `to` 设为 `"docx"`
+- 调用链同“工作流 A / B”（先解析 → 再导出 → 再下载），仅替换 `to`（以及必要时调整 `formula_mode/formula_level/filename`）
+- 注意：`doc2x_convert_export_submit.formula_mode` 必填（`"normal"` 或 `"dollar"`）；`formula_level` 可选（`0/1/2`）
+
+### 工作流 E：图片 → Markdown（版面解析）
+
+- 只要结果（同步）：`doc2x_parse_image_layout_sync({ image_path })`（返回原始 JSON，可能包含 `convert_zip`）
+- 要首屏 markdown（异步）：`doc2x_parse_image_layout_submit({ image_path })` → `doc2x_parse_image_layout_wait_text({ uid })`
+
+如果结果里有 `convert_zip`（base64）且用户希望落盘资源文件：
+
+- `doc2x_materialize_convert_zip({ convert_zip_base64, output_dir })` → `{ output_dir, zip_path, extracted }`
+
+## 失败与排错（你应当这样处理）
+
+1. 鉴权/配置异常  
+   先 `doc2x_debug_config()`，确认 `apiKeyLen > 0` 且 `baseUrl/httpTimeoutMs/pollIntervalMs/maxWaitMs` 合理。
+
+2. 等待超时  
+   建议用户调大 `DOC2X_MAX_WAIT_MS` 或按需调 `DOC2X_POLL_INTERVAL_MS`（不要过于频繁）。
+
+3. 下载被阻止（安全策略）  
+   `doc2x_download_url_to_file` 只允许 `https` 且要求 host 在 `DOC2X_DOWNLOAD_URL_ALLOWLIST` 内；被拦截时解释原因，并让用户选择“加 allowlist”或“保持默认安全策略”。
+
+4. 用户给的是相对路径/不确定路径  
+   要求用户提供绝对路径；不要猜。