> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 概览

> SoMark CLI & SDK 的统一入口。

SoMark CLI & SDK 是 SoMark 团队为开发者准备的工具。

我们把 SDK 和 CLI 放在同一个项目里，不是为了显得热闹，而是为了少装一次、多一条路：同一个包，同时给你程序内集成能力和命令行执行能力。想在终端、脚本、Agent 平台里立刻跑起来，用 [SoMark CLI](/documentation/cli)；想把文档解析接进产品、服务端和自动化流水线，用 [SoMark SDK](/documentation/sdk)。

Python 和 JavaScript 不是同一份代码的两层包装。`somark-py` 和 `somark-js` 是两个独立实现：各自尊重语言生态的写法、异步模型和工程习惯；没有胶水代码，依赖干净又卫生。

<Columns cols={2}>
  <Card title="somark-py" icon="https://mintcdn.com/soulcode-aa7e5a93/mqnfzKMhfEvy3I3O/images/python.svg?fit=max&auto=format&n=mqnfzKMhfEvy3I3O&q=85&s=528053ec0b2ff92265cc46a7e95f1122" href="https://github.com/SoMarkAI/somark-py" cta="打开 Python 仓库" width="48" height="48" data-path="images/python.svg">
    Python 实现。一个包，同时提供 SDK 和 `somark` CLI。
  </Card>

  <Card title="somark-js" icon="https://mintcdn.com/soulcode-aa7e5a93/mqnfzKMhfEvy3I3O/images/javascript.svg?fit=max&auto=format&n=mqnfzKMhfEvy3I3O&q=85&s=bc4be68c0abea8e7bc2c5a4cf898eca8" href="https://github.com/SoMarkAI/somark-js" cta="打开 JavaScript 仓库" width="48" height="48" data-path="images/javascript.svg">
    JavaScript / TypeScript 实现。一个包，同时提供 SDK 和 `somark` CLI。
  </Card>
</Columns>

## 一套能力，两种入口

<Columns cols={2}>
  <Card title="CLI" icon="terminal">
    适合：终端、脚本、CI、Agent 平台，以及所有“现在就把这个文件处理掉”的场景。
  </Card>

  <Card title="SDK" icon="code">
    适合：产品功能、后端服务、异步任务、数据管线，以及所有需要长期跑稳的工程系统。
  </Card>
</Columns>

## 同步原则

SoMark API 是最高优先级的事实来源。API 有什么，CLI 和 SDK 就跟进什么；CLI 不另起炉灶，SDK 不偷偷发明平行宇宙。

Python 和 JavaScript 两个实现保持解析功能完全同步，但会因为生态差异在衍生功能上有些差异：

* <Tooltip headline="SoMarkDown" tip="SoMark 支持的 Markdown 超集的编译器，支持数学公式、化学结构式、代码高亮等专业渲染能力。" cta="阅读文档" href="/open-source-tools/somarkdown">SoMarkDown</Tooltip> 只能在 JS 侧导入SDK使用，因为 SoMarkDown 实现在 JS 下。但 SoMarkDown Preview 可以正常在 Python 和 JS 都享受到。
* PDF 处理的最大能力范围在 Python 侧，因为依赖 <Tooltip headline="SoPDF" tip="高性能、开源友好的 PDF 处理库。" cta="阅读文档" href="/open-source-tools/sopdf">SoPDF</Tooltip> 的实现在 Python 侧，底层依赖更完整。

## 什么时候用 CLI

<Columns cols={2}>
  <Card title="Agent 平台" icon="robot">
    Claude Code、Codex、OpenClaw 等环境里，把 `somark` 当成一把干净利落的外部工具。
  </Card>

  <Card title="终端批处理" icon="square-terminal">
    扫目录、跑脚本、处理一批论文、报告、票据、合同，不需要先写一个应用。
  </Card>

  <Card title="一次性转换" icon="folder-tree">
    临时把文件转成 Markdown、JSON、SoMarkDown 或 ZIP，结果拿到就走。
  </Card>

  <Card title="自动化与诊断" icon="gear">
    放进 CI、定时任务、本地预览、用量查询和安装体检。命令行就该干这种脏活。
  </Card>
</Columns>

## 什么时候用 SDK

<Columns cols={2}>
  <Card title="产品内解析" icon="app-store">
    用户上传文件后，在你的应用里直接返回可读、可检索、可继续处理的结构化内容。
  </Card>

  <Card title="后端服务" icon="server">
    把解析接进 API、Worker、Webhook 或内部服务，让文档变成系统的一部分。
  </Card>

  <Card title="异步队列控制" icon="bars-staggered">
    大文件、批量文件、长任务，交给队列后想要细粒度控制异步节奏的情况。
  </Card>

  <Card title="数据管线" icon="database">
    解析、清洗、入库、检索、向量化，深度接入 SoMark，让非结构化文件不躺平。
  </Card>
</Columns>