网页工作台

markitai serve 在转换核心之上启动一个本地网页界面：上传文件或文件夹、提交 URL、查看实时进度、预览和下载结果、配置 LLM 提供商，并回看七天内的转换历史——全部在中英双语的无障碍界面中完成，手机与窄屏窗口同样可用。当你更喜欢用浏览器而非命令行、想并排对比基础输出与 LLM 增强版本，或想用可视化方式管理 LLM 提供商时，就适合用它。

一切都在本机运行：任务与历史保存在磁盘上，除了你配置的抓取策略、远程文件后端和 LLM 提供商之外，不会向外界发送任何内容。

所有转换选项都收在选项里，所以默认界面什么都不问。输入区是一张卡片：URL 输入框，加上「选项」、文件上传、「转换」组成的操作行（桌面端同行排布，手机上 URL 区在操作行上方）。无论选项是否展开，下方都会显示与当前设置等价的 CLI 命令。语言和主题共用页头的「外观」菜单。

面板按组而非按条排列：预设在最前，增强收纳 LLM、OCR 与图片分析，输出放输出格式，高级折叠内容源、URL/文件抓取选择器以及缓存与压缩开关——其中任一项已是非默认值时会自动展开。

启动服务

服务依赖 serve 附加组件（FastAPI + uvicorn）：

uv tool install "markitai[serve]" --force
markitai serve

服务监听 http://127.0.0.1:3600，启动完成后会自动打开浏览器。

参数	默认值	说明
--host	127.0.0.1	绑定的主机接口
--port	3600	监听端口
--no-open	关闭	启动后不打开浏览器
--no-auth	关闭	禁用访问令牌（恢复无令牌时期的远程策略）
--allowed-host <hostname>	—	额外允许出现在 Host/Origin 头中的主机名（可重复传入）

访问令牌

启动时服务会生成一个随机访问令牌，并打印形如 http://192.168.1.50:3600/?token=mk_… 的可直接打开的 URL。本机请求永远不需要令牌；其他机器的请求必须携带它——网页界面会自动从该 URL 读取令牌（并从地址栏清除），脚本则发送 Authorization: Bearer <token>（下载/SSE 链接可用 ?token=）。设置 MARKITAI_SERVE_TOKEN 可在重启间固定令牌；传入 --no-auth 可完全禁用令牌，此时其他机器只能提交公网 URL 转换，且无法访问 LLM 设置。

从其他设备访问

要在局域网内的其他机器或手机上使用工作台，绑定全部网卡，并在该设备上打开启动时打印的令牌 URL：

markitai serve --host 0.0.0.0

如果你通过 DNS 名称而非 IP 访问，再加上 --allowed-host my-box.lan：服务只接受 Host/Origin 为 localhost、IP 字面量或白名单主机名的请求；其他 DNS 名称一律拒绝，从而阻止恶意网页通过 DNS 重绑定攻击从你的浏览器访问 API。

WARNING

令牌 URL 就是凭据——持有它的人拥有完整权限：用你配置的 LLM 提供商发起转换（包括内网 URL）、查看历史、下载、删除、管理 LLM 设置。只分享给你信任的设备；不需要局域网访问时请保持默认的回环绑定。

工作台功能

• 输入区：拖入文件或文件夹，或粘贴 URL。选项与 CLI 预设一致——minimal、standard、rich——外加独立的 LLM 与 OCR 开关，以及输出格式（rag、obsidian、okf）。输出格式开不开 LLM 都能选。
• 实时进度：每个条目在转换时实时推送状态；任务在后台标签页完成时会发出通知。
• 条目操作：就地重试失败条目，或对已完成条目单独做 LLM 增强而不重转其他条目；大量结果可快速筛选。
• 预览：渲染后的 Markdown 预览，可对比基础版本与 LLM 增强版本；「PDF 设置」菜单可把预览打印成整洁的 A4 文档（可选自定义页眉页脚）。
• 下载：单个输出文件、按任务打包的 zip、整段历史打包下载——还可一键复制任意任务的等效 CLI 命令。
• 限制：每个任务最多 50 个条目，单个上传文件最大 100 MB。

预设、覆盖与命令

预设是五项功能的组合：内置 minimal 全部关闭，standard 开启 LLM、alt 文本与描述 JSON，rich 再加页截图；三者默认都不开 OCR。服务端配置可以覆盖这些定义。选择预设会重置这五项，单独调整则保留其它选择：例如 minimal 加 LLM 显示自定义，不会自动开启图片分析。五项完全匹配时高亮对应预设；这只是显示状态，不会改写底层预设与覆盖值。

每组选项与每个具体选择都提供可悬停、聚焦或轻触打开的双语帮助，说明依赖、数据目的地与限制。LLM + OCR 可能产生更多模型费用；不开 LLM 的 OCR 依赖本地 OCR 引擎。URL 与文件后端分别提示远程目的地，区分 Defuddle、Jina、Cloudflare Browser Rendering 与 Cloudflare Workers AI toMarkdown。

精简 CLI 命令保留显式差异，在桌面和手机上均换行展示。没有 URL 时使用字面占位符 <your-files-or-url-or-url_files>，不再显示额外注释；命令帮助说明需替换为本地文件、URL 或 URL 列表文件，并提示 CLI 非预设配置需为默认值且预设定义应与服务端一致。

下载全部 ZIP 始终位于任务列表下方，桌面右对齐、手机全宽，不会浮在展开的选项旁。

LLM 设置

设置弹窗管理与 markitai config 相同的配置：发现本地与 API 提供商、实时浏览模型列表、配置带权重的部署、在不暴露已保存凭据的前提下测试连接。改动同时作用于网页任务和后续的 CLI 运行。

历史记录

每个完成的任务会在 ~/.markitai/serve/jobs/ 下保留 7 天，随后自动清理。在历史页面可以重新打开任务以再次预览和下载输出、删除单个条目，或把全部历史打包下载为一个 zip。

历史条目带有来源标记。使用 --record-history（或 MARKITAI_RECORD_HISTORY 环境变量 / 配置项 history.record）记录的 CLI 运行会带着「CLI」徽标与浏览器创建的任务并列显示，行为完全一致——同样的 TTL、删除与打包下载——无需重启服务即可实时出现。

API 概览

界面建立在一套小型 REST + SSE API 之上，也可以直接从脚本调用：

端点	说明
GET /api/capabilities	服务版本、可用预设、LLM 与附加组件状态
POST /api/jobs	创建任务（multipart 表单：files、urls JSON 数组、options JSON）
GET /api/jobs/{job_id}	任务状态与条目
GET /api/jobs/{job_id}/events	实时进度流（SSE）
POST /api/jobs/{job_id}/items/{item_id}/retry	重试条目，或以 operation: "enhance" 做 LLM 增强
DELETE /api/jobs/{job_id}/items/{item_id}	从任务中移除条目
GET /api/jobs/{job_id}/items/{item_id}/result	条目结果；配套资源经 GET /api/jobs/{job_id}/files/{path} 获取
GET /api/jobs/{job_id}/archive	整个任务打包为 zip 下载
GET /api/history	列出历史条目
GET /api/history/archive	全部历史打包为一个 zip 下载
DELETE /api/history/{job_id}	删除单个历史条目
/api/settings/llm*	LLM 提供商、模型与部署管理

TIP

同一套 Host/Origin 白名单同样保护 API：带跨站来源的状态变更请求会被拒绝，任意网页无法借你的浏览器驱动它。