Markitai

简体中文

English

简体中文

English

Appearance

CLI 命令参考 ​

基本用法 ​

bash
markitai <input> [options]

<input> 可以是：

  • 文件路径 (document.docx)
  • 目录路径 (./docs)
  • URL (https://example.com)

转换选项 ​

--llm ​

启用 LLM 驱动的格式清洗和优化。默认只写入 .llm.md（跳过基础 .md）。使用 --keep-base 可以同时写入两个文件。

bash
markitai document.docx --llm

--preset <name> ​

使用预定义的配置预设。

预设说明
richLLM + alt + desc + screenshot
standardLLM + alt + desc
minimal仅基础转换
bash
markitai document.pdf --preset rich

--alt ​

使用 AI 生成图片的 alt 文本。

bash
markitai document.pdf --alt

--desc ​

生成图片的详细描述。

bash
markitai document.pdf --desc

--screenshot ​

启用截图捕获：

  • PDF/PPTX: 将页面/幻灯片渲染为 JPEG 图片
  • URL: 使用 Playwright 捕获全页面截图
bash
# 文档截图
markitai document.pdf --screenshot
markitai presentation.pptx --screenshot

# URL 截图
markitai https://example.com --screenshot

TIP

对于 URL，--screenshot 会在需要时自动将抓取策略升级为 playwright。截图将保存为 screenshots/{域名}_路径.full.jpg。

--screenshot-only ​

仅捕获截图，不提取内容。行为取决于是否启用 --llm：

命令输出
--screenshot-only仅截图（不生成 .md 文件）
--llm --screenshot-only.md + .llm.md + 截图（LLM 从截图提取内容）
bash
# 仅捕获截图
markitai https://example.com --screenshot-only

# LLM 纯粹从截图提取内容
markitai https://example.com --llm --screenshot-only

TIP

当传统内容提取失败时（如重 JavaScript 网站、社交媒体），使用 --llm --screenshot-only 模式。

--ocr ​

为扫描文档启用 OCR。

bash
markitai scanned.pdf --ocr

--pure ​

透明直通模式：LLM 仅做文本清理，不生成 frontmatter 或后处理。

bash
# 不带 --llm：输出原始 markdown，不含 frontmatter
markitai document.docx --pure

# 带 --llm：通过 LLM 仅做文本清理
markitai document.docx --llm --pure

# 带 --preset：preset 控制功能，--pure 控制输出格式
markitai document.pdf --preset rich --pure

TIP

--pure 和 --llm 是独立的标志。--pure 单独使用时跳过 frontmatter 生成；--pure --llm 将内容发送给 LLM 做文本清理，但返回原始输出，不包含生成的元数据（description、tags 等）。

WARNING

--pure 会静默覆盖 --alt、--desc 和 --screenshot。同时使用这些标志时会显示警告。

--keep-base ​

在 LLM 模式下仍写入基础 .md 文件。默认情况下 --llm 只输出 .llm.md 以避免冗余文件。

bash
# 默认：只写入 .llm.md
markitai document.docx --llm

# 同时保留 .md 和 .llm.md
markitai document.docx --llm --keep-base

--no-compress ​

禁用图片压缩。

bash
markitai document.pdf --no-compress

输出选项 ​

-o, --output <path> ​

指定输出目录。

bash
markitai document.docx -o ./output

--resume ​

恢复中断的批量处理。

bash
markitai ./docs -o ./output --resume

并发选项 ​

--llm-concurrency <n> ​

LLM 并发请求数。

bash
markitai ./docs --llm --llm-concurrency 10

-j, --batch-concurrency <n> ​

文件处理并发数（默认：10）。

bash
markitai ./docs -o ./output -j 4

TIP

对于文件和 URL 混合的批处理，使用 --url-concurrency 单独控制 URL 抓取。这样可以防止慢速 URL 阻塞文件处理。

缓存选项 ​

--no-cache ​

禁用 LLM 结果缓存（强制重新调用 API）。

bash
markitai document.docx --llm --no-cache

--no-cache-for <patterns> ​

对特定文件或模式禁用缓存（逗号分隔）。

bash
# 单个文件
markitai ./docs --no-cache-for file1.pdf

# Glob 模式
markitai ./docs --no-cache-for "*.pdf"

# 多个模式
markitai ./docs --no-cache-for "*.pdf,reports/**"

URL 选项 ​

.urls 文件支持 ​

当输入为 .urls 文件时，Markitai 自动将其作为 URL 批量任务处理。

bash
markitai urls.urls -o ./output

.urls 文件格式：

# 以 # 开头的是注释
https://example.com/page1
https://example.com/page2

--url-concurrency <n> ​

URL 抓取并发数（默认：5）。与 --batch-concurrency 独立，防止慢速 URL 阻塞文件处理。

bash
markitai ./docs -o ./output --url-concurrency 5

--playwright ​

强制使用 Playwright 浏览器渲染抓取 URL。适用于 JavaScript 重度依赖的 SPA 网站（如 x.com、动态 Web 应用）。

bash
markitai https://x.com/user/status/123 --playwright

TIP

如需预先安装 Playwright 浏览器：

bash
uv run playwright install chromium
# Linux 还需安装系统依赖：
uv run playwright install-deps chromium

--jina ​

强制使用 Jina Reader API 抓取 URL。当浏览器渲染不可用时的云端替代方案。

bash
markitai https://example.com --jina

--cloudflare ​

使用 Cloudflare 作为云端后端。这是一个统一开关：

  • URL 输入：使用 Cloudflare Browser Rendering /markdown API
  • 文件输入：使用 Cloudflare Workers AI toMarkdown 进行文件转换

需要设置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 环境变量（或在 markitai.json 中配置）。在 dash.cloudflare.com/profile/api-tokens 创建 API Token，添加 Browser Rendering: Edit 和 Workers AI: Read 权限。详见配置说明 → Cloudflare 设置。

bash
# 通过 CF Browser Rendering 渲染 URL
markitai https://example.com --cloudflare

# 通过 CF Workers AI toMarkdown 转换文件
markitai document.pdf --cloudflare

TIP

Cloudflare Browser Rendering 在 Free 计划上可用。Workers AI toMarkdown 对 PDF/Office/CSV/XML 免费；图片转换使用 Neurons 配额。

WARNING

--playwright、--jina 和 --cloudflare 三者互斥，同时只能使用一个。

初始化命令 ​

markitai init ​

交互式配置向导，检查依赖项、检测 LLM 提供商并生成配置文件。

bash
# 交互式配置向导
markitai init

# 快速模式（不询问直接生成默认配置）
markitai init --yes

# 生成本地项目配置（./markitai.json）
markitai init --local

# 指定输出路径
markitai init -o ./markitai.json

-I, --interactive ​

进入交互模式，引导式文件转换设置。

bash
markitai -I

配置命令 ​

markitai config list ​

显示所有配置设置。

bash
markitai config list
markitai config list --format json

markitai config get <key> ​

获取特定配置值。

bash
markitai config get llm.enabled
markitai config get cache.enabled

markitai config set <key> <value> ​

设置配置值。

bash
markitai config set llm.enabled true
markitai config set cache.enabled false

markitai config path ​

显示配置文件路径。

bash
markitai config path

markitai config validate ​

验证配置文件。

bash
markitai config validate

缓存命令 ​

markitai cache stats ​

显示缓存统计信息。

bash
markitai cache stats
markitai cache stats --verbose    # 详细模式
markitai cache stats --json       # JSON 输出

markitai cache clear ​

清除缓存数据。

bash
markitai cache clear
markitai cache clear -y                       # 跳过确认
markitai cache clear --include-spa-domains    # 同时清除已学习的 SPA 域名

markitai cache spa-domains ​

查看或管理已学习的 SPA 域名。这些是自动检测到需要浏览器渲染的域名。

bash
markitai cache spa-domains             # 列出已学习的域名
markitai cache spa-domains --json      # JSON 输出
markitai cache spa-domains --clear     # 清除所有已学习的域名

TIP

SPA 域名会在静态抓取检测到 JavaScript 依赖时自动学习。这可以加速后续请求，避免浪费的静态抓取尝试。

诊断命令 ​

markitai doctor ​

检查系统健康状态、依赖项和认证状态。这是主要的诊断命令。

bash
markitai doctor
markitai doctor --fix     # 自动修复缺失组件
markitai doctor --json    # JSON 输出

此命令验证：

  • Playwright: 用于动态 URL 抓取（SPA 渲染）
  • LibreOffice: 用于 Office 文档转换（doc, docx, xls, xlsx, ppt, pptx）
  • FFmpeg: 用于音视频文件处理（mp3, mp4, wav 等）
  • RapidOCR: 用于扫描文档 OCR（内置，无需外部依赖）
  • LLM API: 配置和模型状态
  • Vision Model: 用于图像分析（从 litellm 自动检测）
  • 本地 Provider 认证: Claude Agent 和 GitHub Copilot 的认证状态（如果已配置）

输出示例：

┌──────────────────────────────────────────────────────────────────────────┐
│                           Dependency Status                               │
├─────────────────────┬────────┬──────────────────────────────┬────────────┤
│ Component           │ Status │ Description                  │ Details    │
├─────────────────────┼────────┼──────────────────────────────┼────────────┤
│ Playwright          │   ✓    │ Browser automation           │ Installed  │
│ LibreOffice         │   ✓    │ Office document conversion   │ v7.6.4     │
│ FFmpeg              │   ✓    │ Audio/video processing       │ v6.0       │
│ RapidOCR            │   ✓    │ OCR for scanned documents    │ v1.4.0     │
│ LLM API (copilot)   │   ✓    │ Content enhancement          │ 1 model(s) │
│ Copilot Auth        │   ✓    │ GitHub Copilot auth status   │ Authenticated │
│ Vision Model        │   ✓    │ Image analysis               │ 1 detected │
└─────────────────────┴────────┴──────────────────────────────┴────────────┘

TIP

当使用本地 provider（claude-agent/ 或 copilot/）时，doctor 命令还会检查认证状态，如果认证失败会提供解决方案提示。

其他选项 ​

--verbose ​

启用详细输出。

bash
markitai document.docx --verbose

--quiet, -q ​

静默模式，减少输出信息。

bash
markitai document.docx --quiet

--dry-run ​

预览转换，不写入文件。

bash
markitai document.docx --dry-run

-c, --config <path> ​

指定配置文件路径。

bash
markitai document.docx --config ./my-config.json

-v, --version ​

显示版本信息。

bash
markitai -v

-h, --help ​

显示帮助信息。

bash
markitai -h
markitai config -h
markitai cache -h

基于 MIT 许可证发布。

Copyright © 2026-present