输出 Profile

预设决定跑哪些功能；profile 为某个消费者改写写出的文件。不设 profile 时不改写任何内容。

Profile	改动
rag	图片移到可见的 assets/、<!-- page: N --> 页码标记、表格检查
obsidian	图片移到可见的 assets/，可选 wikilink
okf	frontmatter 改用 OKF 字段

启用 profile

# CLI
markitai document.pdf --profile rag -o out/

// markitai.json
{ "output": { "profile": "rag" } }

# Python API
import markitai

out = markitai.convert("document.pdf", output_dir="out/", profile="rag")

rag — 检索管道

LlamaIndex 的 SimpleDirectoryReader 等摄取器会跳过隐藏路径，比如默认的 .markitai/assets/。rag：

• 可见资源：图片移到 assets/，引用同步改写。
• 页码标记：PDF 真实分页处写 <!-- page: N -->，与 --page-markers 是否在别处保留普通的 <!-- Page number: N --> 无关。
• 表格检查：pipe 表格中列数与表头不同的行会给出警告。

out/
├── document.pdf.md          # 引用形如 ![](assets/10872bbc70f1048fbb0ddbe1.jpg)
└── assets/
    ├── 10872bbc70f1048fbb0ddbe1.jpg
    └── images.json          # 带 --llm --desc 时生成

页面截图留在 .markitai/screenshots/，不进语料。

obsidian — 导入 vault

• 可见资源，同 rag：vault 里不会出现隐藏文件夹。
• Wikilink：设 output.wikilinks: true 后写成 ![[assets/x.jpg|alt]]，alt 文本保留为显示文本。
• markitai 的 frontmatter（title、source、tags）在 Obsidian 里显示为 Properties。

markitai note.docx --profile obsidian -o vault/inbox/
markitai note.docx --profile obsidian --config-json '{"output":{"wikilinks":true}}' -o vault/inbox/

okf — Open Knowledge Format

把 frontmatter 映射到 Open Knowledge Format 规范；资源位置不变。

markitai 字段	OKF 字段
—	type: Document（OKF 唯一的必填字段；每个文件都会加上）
source	resource
markitai_processed	generated: {by: markitai/<version>, at: <UTC 时间戳>}
title、description、tags 及其他	不变（OKF 读取方接受未知字段）

---
type: Document
title: Quarterly report
resource: report.pdf
generated:
  by: markitai/2.0.0
  at: '2026-08-25T01:42:13Z'
---

键的顺序与 Python 版 markitai 一致：type、title、description、resource、tags、generated（先 by 后 at），然后是其他字段。文档中已有的 type、resource 或 generated 值会保留。okf 也作用于 --pure 输出。

images.json schema（已冻结）

带 --llm --desc 和 -o 时，每个资源目录会生成一份 images.json（.markitai/assets/，rag 与 obsidian 下为 assets/）。schema 冻结在 1.0 版本。

顶层：

字段	类型	说明
version	string	"1.0"
created	string	ISO 8601，首次写入（合并时保留）
updated	string	ISO 8601，最近一次写入
images	array	每张图片一条

images 里的每一条：

字段	类型	说明
path	string	图片绝对路径
alt	string	短标题（alt 文本）
desc	string	详细描述
text	string	图片里的文字（可能为空）
created	string	ISO 8601，分析时间
source	string	按给定方式写的源文档（URL 则为输出文件名）

Recipe：LlamaIndex 摄取

用了 rag，Markdown 和图片都进入语料：

import markitai
from llama_index.core import SimpleDirectoryReader

out = markitai.convert("report.pdf", output_dir="corpus/", profile="rag")
print(out.frontmatter["title"])  # 可直接当元数据
print([p.name for p in out.assets])  # 图片现在在 corpus/assets/ 下

# 读取器能看到全部文件：markdown、图片、images.json
documents = SimpleDirectoryReader("corpus/").load_data()
print(len(documents))

注意

• Profile 只改写本次运行写出的文件：别在同一个目录里混用带 profile 和不带 profile 的运行。
• 不带 -o（stdout）时 profile 仍会塑形 Markdown；图片保留 file:// 链接，不写 images.json。
• 批量报告和 --resume 状态留在 .markitai/；嵌套批量时每个子目录各有一个 assets/。