Markitai

简体中文

English

简体中文

English

Appearance

配置说明 ​

配置优先级 ​

Markitai 使用以下优先级顺序（从高到低）：

  1. 命令行参数
  2. 环境变量
  3. 配置文件
  4. 默认值

配置文件 ​

Markitai 按以下顺序查找配置文件：

  1. --config 参数指定的路径
  2. MARKITAI_CONFIG 环境变量
  3. ./markitai.json（当前目录）
  4. ~/.markitai/config.json（用户主目录）

初始化配置 ​

bash
# 交互式配置向导（推荐）
markitai init

# 快速模式（生成默认配置）
markitai init --yes

# 在指定位置创建全局配置
markitai init --local  # 创建 ./markitai.json

查看配置 ​

bash
# 列出所有设置
markitai config list

# 获取特定值
markitai config get llm.enabled

# 设置值
markitai config set llm.enabled true

完整配置示例 ​

json
{
  "llm": {
    "enabled": false,
    "model_list": [
      {
        "model_name": "default",
        "litellm_params": {
          "model": "gemini/gemini-2.5-flash",
          "api_key": "env:GEMINI_API_KEY"
        }
      }
    ],
    "router_settings": {
      "routing_strategy": "simple-shuffle",
      "num_retries": 2,
      "timeout": 120
    },
    "concurrency": 10
  },
  "image": {
    "alt_enabled": false,
    "desc_enabled": false,
    "compress": true,
    "quality": 75,
    "format": "jpeg",
    "max_width": 1920,
    "max_height": 99999,
    "filter": {
      "min_width": 50,
      "min_height": 50,
      "min_area": 5000,
      "deduplicate": true
    }
  },
  "ocr": {
    "enabled": false,
    "lang": "en"
  },
  "screenshot": {
    "enabled": false,
    "screenshot_only": false,
    "viewport_width": 1920,
    "viewport_height": 1080,
    "quality": 75,
    "max_height": 10000
  },
  "cache": {
    "enabled": true,
    "no_cache_patterns": [],
    "max_size_bytes": 536870912,
    "global_dir": "~/.markitai"
  },
  "batch": {
    "concurrency": 10,
    "url_concurrency": 5,
    "scan_max_depth": 5,
    "scan_max_files": 10000,
    "state_flush_interval_seconds": 10,
    "heavy_task_limit": 0
  },
  "fetch": {
    "strategy": "auto",
    "playwright": {
      "timeout": 30000,
      "wait_for": "domcontentloaded",
      "extra_wait_ms": 3000,
      "wait_for_selector": null,
      "cookies": null,
      "reject_resource_patterns": null,
      "extra_http_headers": null,
      "user_agent": null,
      "http_credentials": null
    },
    "jina": {
      "api_key": null,
      "timeout": 30,
      "rpm": 20,
      "no_cache": false,
      "target_selector": null,
      "wait_for_selector": null
    },
    "cloudflare": {
      "api_token": null,
      "account_id": null,
      "timeout": 30000,
      "wait_until": "networkidle0",
      "cache_ttl": 0,
      "reject_resource_patterns": null,
      "convert_enabled": false
    },
    "policy": {
      "enabled": true,
      "max_strategy_hops": 4
    },
    "domain_profiles": {},
    "fallback_patterns": ["x.com", "twitter.com", "instagram.com", "facebook.com", "linkedin.com", "threads.net"]
  },
  "output": {
    "dir": "./output",
    "on_conflict": "rename",
    "allow_symlinks": false
  },
  "log": {
    "level": "INFO",
    "format": "text",
    "dir": "~/.markitai/logs",
    "rotation": "10 MB",
    "retention": "7 days"
  },
  "prompts": {
    "dir": "~/.markitai/prompts"
  }
}

TIP

使用 env:VAR_NAME 语法在配置文件中引用环境变量。对于 JINA_API_KEY、CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID，也可以直接设置环境变量（或写入 .env），无需在配置文件中声明——markitai 会自动读取。

环境变量 ​

API 密钥 ​

变量说明
OPENAI_API_KEYOpenAI API 密钥
ANTHROPIC_API_KEYAnthropic (Claude) API 密钥
GEMINI_API_KEYGoogle Gemini API 密钥
DEEPSEEK_API_KEYDeepSeek API 密钥
OPENROUTER_API_KEYOpenRouter API 密钥
JINA_API_KEYJina Reader API 密钥
CLOUDFLARE_API_TOKENCloudflare API Token（Browser Rendering / Workers AI）
CLOUDFLARE_ACCOUNT_IDCloudflare Account ID

Markitai 设置 ​

变量说明
MARKITAI_CONFIG配置文件路径
MARKITAI_LOG_DIR日志文件目录
MARKITAI_LOG_FORMAT日志格式覆盖（text 或 json）
MARKITAI_STATIC_HTTP静态 HTTP 后端：httpx（默认）或 curl_cffi（TLS 指纹伪装）

LLM 配置 ​

支持的提供商 ​

Markitai 通过 LiteLLM 支持多个 LLM 提供商：

  • OpenAI (GPT-5.2, GPT-5-mini)
  • Anthropic (Claude 3.5/4)
  • Google (Gemini 2.x)
  • DeepSeek
  • OpenRouter
  • Ollama（本地模型）

本地提供商（基于订阅） ​

Markitai 还支持使用 CLI 认证和订阅额度的本地提供商：

  • Claude Agent (claude-agent/): 使用 Claude Agent SDK 通过 Claude Code CLI 认证
  • GitHub Copilot (copilot/): 使用 GitHub Copilot SDK 通过 Copilot CLI 认证
  • ChatGPT (chatgpt/): 使用 ChatGPT 订阅，通过 OAuth Device Code Flow 和 Responses API 认证，无需额外 SDK
  • Gemini CLI (gemini-cli/): 使用 Google Gemini CLI OAuth 凭据（~/.gemini/oauth_creds.json），支持自动令牌刷新

这些提供商需要：

  1. 安装并认证对应的 CLI 工具（或使用环境变量认证——见下文）
  2. 可选 SDK 包：uv add markitai[claude-agent]、uv add markitai[copilot] 或 uv add markitai[gemini-cli]

安装 Claude Code CLI：

bash
# macOS/Linux/WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

安装 GitHub Copilot CLI：

bash
# macOS/Linux/WSL
curl -fsSL https://gh.io/copilot-install | bash

# Windows
winget install GitHub.Copilot

ChatGPT（无需安装 CLI）：

ChatGPT 提供商首次使用时通过 OAuth Device Code Flow 认证——只需配置模型并按照浏览器提示操作即可。

安装 Gemini CLI（可选）：

Gemini CLI 提供商可复用现有 Gemini CLI 凭据。安装 CLI 并认证，或让内置 OAuth 流程自动处理：

bash
# 安装 Gemini CLI（可选——提供商有内置 OAuth）
npm install -g @anthropic-ai/gemini-cli
gemini  # 首次运行时触发 OAuth 登录

# 安装 google-auth 以支持自动令牌刷新
uv add 'markitai[gemini-cli]'

模型命名 ​

使用 LiteLLM 模型命名规范：

provider/model-name

示例：

  • openai/gpt-4o
  • anthropic/claude-sonnet-4-20250514
  • gemini/gemini-2.5-flash
  • deepseek/deepseek-chat
  • ollama/llama3.2
  • claude-agent/sonnet（本地，需要 Claude Code CLI）
  • copilot/gpt-5.2（本地，需要 Copilot CLI）
  • chatgpt/gpt-5.2（本地，需要 ChatGPT 订阅）
  • gemini-cli/gemini-2.5-pro（本地，需要 Gemini CLI 或 OAuth）

Claude Agent SDK 支持的模型：

  • 别名（推荐）：sonnet、opus、haiku、inherit
  • 完整模型字符串：claude-sonnet-4-5-20250929、claude-opus-4-6、claude-opus-4-5-20251101

GitHub Copilot SDK 支持的模型：

  • OpenAI: gpt-5.2、gpt-5.1、gpt-5-mini、gpt-5.1-codex
  • Anthropic: claude-sonnet-4.5、claude-opus-4.6、claude-haiku-4.5
  • Google: gemini-2.5-pro、gemini-3-flash
  • 可用性取决于您的 Copilot 订阅

ChatGPT 支持的模型：

  • gpt-5.2、gpt-5.2-codex、codex-mini 等

Gemini CLI 支持的模型：

  • gemini-2.5-pro、gemini-2.5-flash、gemini-3-flash-preview 等

模型下线通知

以下模型将于 2025年2月13日 下线：

  • gpt-4o、gpt-4.1、gpt-4.1-mini、o4-mini、gpt-5

请在截止日期前迁移到 gpt-5.2 或其他支持的模型。

本地提供商支持 Vision

本地提供商（claude-agent/、copilot/、chatgpt/、gemini-cli/）通过文件附件支持图片分析（--alt、--desc）。请确保使用支持 vision 的模型（如 copilot/gpt-5.2、gemini-cli/gemini-2.5-pro）。

本地提供商故障排除

常见错误和解决方案：

错误解决方案
"SDK 未安装"uv add markitai[copilot]、uv add markitai[claude-agent] 或 uv add markitai[gemini-cli]
"CLI 未找到"安装并认证 CLI 工具（Copilot CLI、Claude Code）
"未认证"运行 copilot auth login 或 claude auth login。也可：为 Copilot 设置 GH_TOKEN/GITHUB_TOKEN，为 Claude 设置 CLAUDE_CODE_USE_BEDROCK=1/CLAUDE_CODE_USE_VERTEX=1/CLAUDE_CODE_USE_FOUNDRY=1。ChatGPT 首次使用时自动触发 OAuth。Gemini CLI 复用 ~/.gemini/oauth_creds.json。
"速率限制"等待后重试，或检查订阅额度
"请求超时"超时是自适应的；处理非常大的文档可能需要更长时间

使用 markitai doctor 检查认证状态并获取解决方案提示。

自定义 API 端点 ​

使用 api_base 覆盖提供商的默认 API 端点。该值直接传递给 LiteLLM，适用于任何 LiteLLM 支持的提供商（OpenAI、Anthropic、Gemini、Azure 等）。支持与 api_key 相同的 env:变量名 语法：

json
{
  "llm": {
    "model_list": [
      {
        "model_name": "default",
        "litellm_params": {
          "model": "openai/your-model-name",
          "api_key": "env:YOUR_API_KEY",
          "api_base": "https://your-api-endpoint.com/v1"
        }
      }
    ]
  }
}

示例：

json
// 本地 Ollama
{
  "model": "ollama/llama3.2",
  "api_base": "http://localhost:11434"
}

// Azure OpenAI
{
  "model": "azure/gpt-4o",
  "api_key": "env:AZURE_API_KEY",
  "api_base": "https://your-resource.openai.azure.com"
}

// DeepSeek
{
  "model": "deepseek/deepseek-chat",
  "api_key": "env:DEEPSEEK_API_KEY",
  "api_base": "https://api.deepseek.com/v1"
}

// 任何 OpenAI 兼容的提供商
{
  "model": "openai/custom-model",
  "api_key": "env:CUSTOM_API_KEY",
  "api_base": "https://your-proxy-or-provider.com/v1"
}

// 引用环境变量
{
  "model": "anthropic/claude-sonnet-4-5-20250929",
  "api_key": "env:ANTHROPIC_API_KEY",
  "api_base": "env:ANTHROPIC_BASE_URL"
}

TIP

常见用例包括自托管推理服务器（vLLM、Ollama、LocalAI）、区域 API 代理和第三方 API 网关。

本地提供商与 api_base

api_base 配置字段不适用于本地提供商（claude-agent/、copilot/、chatgpt/、gemini-cli/）。这些提供商作为 CLI 子进程运行或使用 OAuth，内部管理 API 端点：

  • Claude Agent: 设置 ANTHROPIC_BASE_URL 覆盖 API 端点。如果同时设置了 ANTHROPIC_API_KEY，CLI 将使用它进行直接 API 访问而非订阅认证。其他路由选项：CLAUDE_CODE_USE_BEDROCK=1、CLAUDE_CODE_USE_VERTEX=1、CLAUDE_CODE_USE_FOUNDRY=1。
  • GitHub Copilot: 端点由 Copilot CLI 内部管理，不可覆盖。基于令牌的认证请设置 GH_TOKEN 或 GITHUB_TOKEN。
  • ChatGPT: 使用 OpenAI Responses API 端点，通过 LiteLLM 内置 OAuth Device Code Flow 认证。
  • Gemini CLI: 使用 Google Code Assist API 端点，从 ~/.gemini/oauth_creds.json 读取凭据。

Vision 模型 ​

对于图片分析（--alt、--desc），Markitai 自动路由到支持视觉的模型。视觉能力默认自动检测自 litellm，大多数模型无需手动配置。

如需显式覆盖自动检测，设置 supports_vision：

json
{
  "llm": {
    "model_list": [
      {
        "model_name": "default",
        "litellm_params": {
          "model": "gemini/gemini-2.5-flash",
          "api_key": "env:GEMINI_API_KEY"
        },
        "model_info": {
          "supports_vision": true  // 可选：省略时自动检测
        }
      }
    ]
  }
}

路由设置 ​

配置 Markitai 如何在多个模型间分发请求：

json
{
  "llm": {
    "router_settings": {
      "routing_strategy": "simple-shuffle",
      "num_retries": 2,
      "timeout": 120,
      "fallbacks": []
    },
    "concurrency": 10
  }
}
设置选项默认值说明
routing_strategysimple-shuffle, least-busy, usage-based-routing, latency-based-routingsimple-shuffle模型选择策略
num_retries0-102失败重试次数
timeout秒120请求超时时间（自适应计算的基础值）
concurrency1-2010最大并发 LLM 请求数

模型权重 ​

model_list 中每个模型的 litellm_params 支持 weight 参数来控制流量分配：

json
{
  "model_name": "default",
  "litellm_params": {
    "model": "gemini/gemini-2.5-flash",
    "api_key": "env:GEMINI_API_KEY",
    "weight": 10
  }
}
值行为
weight: 0禁用 — 模型完全排除在路由之外
weight: 1（默认）正常优先级
weight: 10被选中的概率是 weight=1 模型的 10 倍

设置 weight: 0 可临时禁用某个模型而无需删除其配置。至少需要一个模型的 weight > 0。

自适应超时 ​

本地 provider（claude-agent/、copilot/、chatgpt/、gemini-cli/）使用基于请求复杂度的自适应超时计算：

  • 基础超时：最小 60 秒，最大 600 秒
  • 考虑因素：提示词长度、图片数量、预期输出长度
  • 计算公式：基础超时 + (提示词字符数 / 500) + (图片数 * 30) + (预期输出 / 200)

这可以防止大文档处理超时，同时保持短请求的响应速度。

提示缓存（Claude Agent） ​

Claude Agent provider 对超过 4KB 的系统提示词自动启用提示缓存。这通过缓存常用的系统提示词前缀来降低 API 成本。

TIP

提示缓存是透明的——无需配置。使用 markitai cache stats --verbose 查看缓存统计。

图片配置 ​

控制图片处理和压缩：

json
{
  "image": {
    "alt_enabled": false,
    "desc_enabled": false,
    "compress": true,
    "quality": 75,
    "format": "jpeg",
    "max_width": 1920,
    "max_height": 99999,
    "filter": {
      "min_width": 50,
      "min_height": 50,
      "min_area": 5000,
      "deduplicate": true
    }
  }
}
设置默认值说明
alt_enabledfalse通过 LLM 生成 alt 文本
desc_enabledfalse生成图片描述文件
compresstrue压缩图片
quality75JPEG/WebP 质量 (1-100)
formatjpeg输出格式：jpeg, png, webp
max_width1920最大宽度（像素）
max_height99999最大高度（像素，实际无限制）
filter.min_width50跳过宽度小于此值的图片
filter.min_height50跳过高度小于此值的图片
filter.min_area5000跳过面积小于此值的图片
filter.deduplicatetrue去除重复图片

截图配置 ​

为文档和 URL 启用截图捕获：

json
{
  "screenshot": {
    "enabled": false,
    "screenshot_only": false,
    "viewport_width": 1920,
    "viewport_height": 1080,
    "quality": 75,
    "max_height": 10000
  }
}

启用后（--screenshot 或 --preset rich）：

  • PDF/PPTX: 将每个页面/幻灯片渲染为 JPEG 图片
  • URL: 使用 Playwright 捕获全页面截图
设置默认值说明
enabledfalse启用截图捕获
screenshot_onlyfalse仅捕获截图，跳过内容提取（对应 --screenshot-only CLI 标志）
viewport_width1920URL 截图的浏览器视口宽度
viewport_height1080URL 截图的浏览器视口高度
quality75JPEG 压缩质量 (1-100)
max_height10000截图最大高度（像素）

截图保存在 output/screenshots/ 目录。

TIP

对于 URL，启用 --screenshot 会在需要时自动将抓取策略升级为 playwright，确保页面完全渲染后再捕获。

预设 ​

Markitai 包含三个内置预设（rich、standard、minimal）。您还可以在配置文件中定义自定义预设：

json
{
  "presets": {
    "my-preset": {
      "llm": true,
      "ocr": false,
      "alt": true,
      "desc": false,
      "screenshot": true
    }
  }
}
字段类型默认值说明
llmbooleanfalse启用 LLM 增强
ocrbooleanfalse启用扫描文档 OCR
altbooleanfalse生成图片 alt 文本
descbooleanfalse生成图片描述
screenshotbooleanfalse启用截图捕获

通过 --preset CLI 标志使用自定义预设：

bash
markitai document.pdf --preset my-preset

OCR 配置 ​

配置扫描文档的光学字符识别。Markitai 使用 RapidOCR（ONNX Runtime + OpenCV）进行 OCR 处理。

json
{
  "ocr": {
    "enabled": false,
    "lang": "en"
  }
}
设置默认值说明
enabledfalse为 PDF 启用 OCR
langenRapidOCR 语言代码

支持的语言代码：

  • en - 英语
  • zh / ch - 中文（简体）
  • ja / japan - 日语
  • ko / korean - 韩语
  • ar / arabic - 阿拉伯语
  • th - 泰语
  • latin - 拉丁语系

TIP

RapidOCR 已作为依赖包含，开箱即用，无需额外安装。

批处理配置 ​

控制并行处理：

json
{
  "batch": {
    "concurrency": 10,
    "url_concurrency": 5,
    "scan_max_depth": 5,
    "scan_max_files": 10000,
    "state_flush_interval_seconds": 10,
    "heavy_task_limit": 0
  }
}
设置默认值说明
concurrency10最大并发文件转换数
url_concurrency5最大并发 URL 抓取数（与文件分离）
scan_max_depth5最大目录扫描深度
scan_max_files10000单次运行最大处理文件数
state_flush_interval_seconds10批处理状态持久化到磁盘的间隔（秒）
heavy_task_limit0CPU 密集任务限制（0 = 根据内存自动检测）

TIP

URL 抓取使用独立的并发池，因为 URL 可能有较高延迟（如浏览器渲染的页面）。这可以防止慢速 URL 阻塞本地文件处理。

URL 抓取配置 ​

配置 URL 的抓取方式：

json
{
  "fetch": {
    "strategy": "auto",
    "playwright": {
      "timeout": 30000,
      "wait_for": "domcontentloaded",
      "extra_wait_ms": 3000
    },
    "jina": {
      "api_key": "env:JINA_API_KEY",
      "timeout": 30,
      "rpm": 20,
      "no_cache": false,
      "target_selector": null,
      "wait_for_selector": null
    },
    "cloudflare": {
      "api_token": "env:CLOUDFLARE_API_TOKEN",
      "account_id": "env:CLOUDFLARE_ACCOUNT_ID"
    },
    "fallback_patterns": ["x.com", "twitter.com", "instagram.com", "facebook.com", "linkedin.com", "threads.net"]
  }
}

抓取策略 ​

策略说明
auto自动检测：对 fallback_patterns 中的模式使用 Playwright，否则使用静态
static使用 MarkItDown 内置的 URL 转换器（快速，无 JS）
playwright使用 Playwright 处理 JS 渲染的页面（支持 SPA）
jina使用 Jina Reader API
cloudflare使用 Cloudflare Browser Rendering /markdown API

Playwright 设置 ​

设置默认值说明
timeout30000页面加载超时（毫秒）
wait_fordomcontentloaded等待条件：load, domcontentloaded, networkidle
extra_wait_ms3000JS 渲染额外等待时间
session_modeisolated会话模式：isolated（每个请求新建上下文）、domain_persistent（同域名复用上下文）
session_ttl_seconds600持久化会话的 TTL（秒）
wait_for_selectornull提取前等待的 CSS 选择器
cookiesnull设置 Cookie：[{name, value, domain, path}]
reject_resource_patternsnull屏蔽匹配的资源：["**/*.css"]
extra_http_headersnull额外 HTTP 请求头：{"Accept-Language": "zh-CN"}
user_agentnull自定义 User-Agent 字符串
http_credentialsnullHTTP 认证凭据：{username, password}

Jina 设置 ​

设置默认值说明
api_keynullJina Reader API 密钥（支持 env: 语法）
timeout30请求超时（秒）
rpm20每分钟请求速率限制
no_cachefalse禁用 Jina 服务端缓存
target_selectornull定位特定页面内容的 CSS 选择器
wait_for_selectornull提取前等待的 CSS 选择器

Cloudflare 设置 ​

Cloudflare 通过统一的 --cloudflare 标志提供两项能力：

  1. Browser Rendering（/markdown API）用于 URL 转 Markdown
  2. Workers AI toMarkdown 用于文件转 Markdown（PDF、Office、CSV、XML、图片）
json
{
  "fetch": {
    "cloudflare": {
      "api_token": "env:CLOUDFLARE_API_TOKEN",
      "account_id": "env:CLOUDFLARE_ACCOUNT_ID",
      "timeout": 30000,
      "wait_until": "networkidle0",
      "cache_ttl": 0,
      "reject_resource_patterns": null,
      "user_agent": null,
      "cookies": null,
      "wait_for_selector": null,
      "http_credentials": null,
      "convert_enabled": false
    }
  }
}
设置默认值说明
api_tokennullCloudflare API Token（支持 env: 语法）
account_idnullCloudflare Account ID（支持 env: 语法）
timeout30000Browser Rendering 超时（毫秒）
wait_untilnetworkidle0BR 等待事件：load, domcontentloaded, networkidle0
cache_ttl0BR 缓存 TTL（秒，0 = 不缓存）
reject_resource_patternsnull屏蔽匹配正则的资源：["/\\.css$/"]
user_agentnullBrowser Rendering 自定义 User-Agent
cookiesnull导航前设置的 Cookie：[{"name": "k", "value": "v", "url": "..."}]
wait_for_selectornull页面加载后等待的 CSS 选择器（如 "#content"）
http_credentialsnullHTTP Basic Auth：{"username": "u", "password": "p"}
convert_enabledfalse启用 Workers AI toMarkdown 文件转换

TIP

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

凭据获取方式：

  1. Account ID — 登录 Cloudflare Dashboard，Account ID 显示在 URL 中（dash.cloudflare.com/<account_id>/...），或在任意域名的 Overview 页面右侧边栏中。

  2. API Token — 进入 My Profile → API Tokens，点击 Create Token，选择 Custom token 模板，添加以下权限：

    权限访问级别用途
    Account / Cloudflare Workers AIReadtoMarkdown 文件转换
    Account / Browser RenderingEdit/markdown URL 渲染

    将 Account Resources 设为目标账户，创建后复制 Token。

  3. 启用 Browser Rendering — 在 Cloudflare Dashboard 中进入 Workers & Pages → Browser Rendering，按提示启用（Free 计划可用）。

bash
export CLOUDFLARE_API_TOKEN="your-api-token"
export CLOUDFLARE_ACCOUNT_ID="your-account-id"

限制与注意事项

  • 并发限制：Free 计划允许 2 个并发浏览器实例。Markitai 会自动串行化 CF BR 请求，并在收到 429 限流时指数退避重试，因此高 url_concurrency 值是安全的，但不会加速 CF BR 抓取。
  • 站点兼容性：有严格反爬措施的站点（如 x.com、twitter.com）可能通过 CF BR 返回 400 错误。对这些站点请使用 --playwright 或 --jina。
  • 文件转换质量：对于有本地 converter 的格式（PDF、DOCX、XLSX 等），CF Workers AI toMarkdown 的输出质量通常低于本地 converter（如格式还原不够精确、无法提取图片等）。使用 --cloudflare 时如果有更好的本地 converter 可用会输出警告。CF toMarkdown 最适合本地没有 converter 的格式（.numbers、.ods、.svg 等）。

抓取策略引擎 ​

策略引擎基于域名特征和历史记录智能排序抓取策略。详见 Fetch Policy 指南。

json
{
  "fetch": {
    "policy": {
      "enabled": true,
      "max_strategy_hops": 4
    }
  }
}
设置默认值说明
enabledtrue启用智能策略排序
max_strategy_hops4放弃前最多尝试的策略数

域名配置 ​

为特定域名配置抓取覆盖：

json
{
  "fetch": {
    "domain_profiles": {
      "x.com": {
        "wait_for_selector": "[data-testid=tweetText]",
        "wait_for": "domcontentloaded",
        "extra_wait_ms": 1200,
        "prefer_strategy": "playwright"
      }
    }
  }
}
设置默认值说明
wait_for_selectornull内容提取前等待的 CSS 选择器
wait_fornull等待条件覆盖：load, domcontentloaded, networkidle
extra_wait_msnull额外等待时间覆盖（毫秒）
prefer_strategynull首选策略：static, playwright, cloudflare, jina

回退模式 ​

匹配这些模式的网站自动使用浏览器策略：

json
{
  "fetch": {
    "fallback_patterns": ["x.com", "twitter.com", "instagram.com", "facebook.com", "linkedin.com", "threads.net"]
  }
}

缓存配置 ​

Markitai 使用全局缓存，存储在 ~/.markitai/cache.db。

json
{
  "cache": {
    "enabled": true,
    "no_cache_patterns": [],
    "max_size_bytes": 536870912,
    "global_dir": "~/.markitai"
  }
}
设置默认值说明
enabledtrue启用 LLM 结果缓存
no_cachefalse跳过读取缓存但仍写入（相当于 --no-cache 标志）
no_cache_patterns[]跳过缓存的 glob 模式
max_size_bytes536870912 (512MB)最大缓存大小
global_dir~/.markitai全局缓存目录

缓存命令 ​

bash
# 查看缓存统计
markitai cache stats

# 查看详细统计（条目、按模型分组）
markitai cache stats --verbose

# 指定显示数量
markitai cache stats --verbose --limit 50

# 清除缓存
markitai cache clear
markitai cache clear -y  # 跳过确认

禁用缓存 ​

bash
# 整次运行禁用
markitai document.pdf --no-cache

# 对特定文件/模式禁用
markitai ./docs --no-cache-for "*.pdf"
markitai ./docs --no-cache-for "file1.pdf,reports/**"

输出配置 ​

控制输出文件处理：

json
{
  "output": {
    "on_conflict": "rename"
  }
}
设置选项默认值说明
dir-./output输出目录
on_conflictrename, overwrite, skiprename处理已存在文件的方式
allow_symlinks-false允许输出路径中的符号链接

日志配置 ​

配置日志行为：

json
{
  "log": {
    "level": "INFO",
    "format": "text",
    "dir": "~/.markitai/logs",
    "rotation": "10 MB",
    "retention": "7 days"
  }
}
设置默认值说明
levelINFO日志级别：DEBUG, INFO, WARNING, ERROR, CRITICAL
formattext日志格式：text（可读文本）或 json（结构化）
dir~/.markitai/logs日志文件目录
rotation10 MB文件超过此大小时轮转
retention7 days删除早于此时间的日志

自定义提示词 ​

自定义不同任务的 LLM 提示词。每个提示词拆分为 system（角色定义）和 user（内容模板）两部分：

json
{
  "prompts": {
    "dir": "~/.markitai/prompts",
    "cleaner_system": null,
    "cleaner_user": null,
    "image_caption_system": null,
    "image_caption_user": null,
    "image_description_system": null,
    "image_description_user": null,
    "image_analysis_system": null,
    "image_analysis_user": null,
    "page_content_system": null,
    "page_content_user": null,
    "document_enhance_system": null,
    "document_enhance_user": null,
    "document_enhance_complete_system": null,
    "document_enhance_complete_user": null,
    "document_process_system": null,
    "document_process_user": null,
    "document_vision_system": null,
    "document_vision_user": null,
    "url_enhance_system": null,
    "url_enhance_user": null
  }
}

在提示词目录创建自定义提示词文件：

~/.markitai/prompts/
├── cleaner_system.md                    # 文档清理角色和规则
├── cleaner_user.md                      # 文档清理内容模板
├── image_caption_system.md              # Alt 文本生成角色
├── image_caption_user.md                # Alt 文本内容模板
├── document_enhance_system.md           # 文档增强角色
├── document_enhance_user.md             # 文档增强内容模板
├── document_enhance_complete_system.md  # 完整文档增强角色
├── document_enhance_complete_user.md    # 完整文档增强内容模板
└── url_enhance_user.md                  # URL 增强内容模板

指定特定的提示词文件路径：

json
{
  "prompts": {
    "cleaner_system": "/path/to/my-cleaner-system.md",
    "cleaner_user": "/path/to/my-cleaner-user.md"
  }
}

TIP

system/user 拆分可以防止 LLM 意外地将提示词指令包含在其输出中。system 提示词定义角色和规则，而 user 提示词包含实际要处理的内容。

中国大陆用户指南 ​

安装脚本镜像加速 ​

安装脚本会自动检测代理环境变量（HTTPS_PROXY / HTTP_PROXY / ALL_PROXY）。如果未检测到代理，会询问是否启用国内镜像加速，并提供以下镜像源选择：

镜像源PyPInpm推荐地域
清华 TUNA (默认)pypi.tuna.tsinghua.edu.cnregistry.npmmirror.com北方 / 通用
阿里云mirrors.aliyun.comregistry.npmmirror.com东部
腾讯云mirrors.cloud.tencent.commirrors.cloud.tencent.com南方
华为云repo.huaweicloud.commirrors.huaweicloud.com北方

Playwright 浏览器二进制文件统一使用 npmmirror CDN 镜像（cdn.npmmirror.com），这是目前唯一可靠的公共镜像。

你也可以在运行安装脚本前手动设置（以清华 TUNA 为例）：

macOS / Linux / WSL (Bash/Zsh):

bash
export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
export PLAYWRIGHT_DOWNLOAD_HOST="https://cdn.npmmirror.com/binaries/playwright"
export NPM_CONFIG_REGISTRY="https://registry.npmmirror.com"

Windows (PowerShell):

powershell
$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"
$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://cdn.npmmirror.com/binaries/playwright"
$env:NPM_CONFIG_REGISTRY = "https://registry.npmmirror.com"

LLM API 访问 ​

国内可用的 LLM 提供商及配置方式：

提供商可用性说明
DeepSeek直连可用无需代理，直接使用 deepseek/deepseek-chat
Ollama完全离线本地模型，使用 ollama/llama3.2
API 代理服务通过中转通过 api_base 指向第三方中转服务
OpenAI / Claude / Gemini需代理需代理或 api_base 中转

使用 api_base 指向代理中转的示例配置：

json
{
  "llm": {
    "model_list": [
      {
        "model_name": "default",
        "litellm_params": {
          "model": "openai/gpt-4o",
          "api_key": "env:OPENAI_API_KEY",
          "api_base": "https://your-api-proxy.com/v1"
        }
      }
    ]
  }
}

代理配置 ​

如已有代理，设置环境变量即可对所有网络请求生效：

bash
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
powershell
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"

TIP

设置了代理环境变量后，安装脚本会自动跳过镜像加速配置。

基于 MIT 许可证发布。

Copyright © 2026-present