概览

SoMark CLI & SDK 的统一入口。

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

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

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

somark-py

Python 实现。一个包，同时提供 SDK 和 somark CLI。

打开 Python 仓库

somark-js

JavaScript / TypeScript 实现。一个包，同时提供 SDK 和 somark CLI。

打开 JavaScript 仓库

​

一套能力，两种入口

CLI

适合：终端、脚本、CI、Agent 平台，以及所有“现在就把这个文件处理掉”的场景。

SDK

适合：产品功能、后端服务、异步任务、数据管线，以及所有需要长期跑稳的工程系统。

​

同步原则

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

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

• SoMarkDown 只能在 JS 侧导入SDK使用，因为 SoMarkDown 实现在 JS 下。但 SoMarkDown Preview 可以正常在 Python 和 JS 都享受到。
• PDF 处理的最大能力范围在 Python 侧，因为依赖 SoPDF 的实现在 Python 侧，底层依赖更完整。

​

什么时候用 CLI

Agent 平台

Claude Code、Codex、OpenClaw 等环境里，把 somark 当成一把干净利落的外部工具。

终端批处理

扫目录、跑脚本、处理一批论文、报告、票据、合同，不需要先写一个应用。

一次性转换

临时把文件转成 Markdown、JSON、SoMarkDown 或 ZIP，结果拿到就走。

自动化与诊断

放进 CI、定时任务、本地预览、用量查询和安装体检。命令行就该干这种脏活。

​

什么时候用 SDK

产品内解析

用户上传文件后，在你的应用里直接返回可读、可检索、可继续处理的结构化内容。

后端服务

把解析接进 API、Worker、Webhook 或内部服务，让文档变成系统的一部分。

异步队列控制

大文件、批量文件、长任务，交给队列后想要细粒度控制异步节奏的情况。

数据管线

解析、清洗、入库、检索、向量化，深度接入 SoMark，让非结构化文件不躺平。