zleap_parser

zleap_parser 是 zleap 的 Python 文档解析 SDK：把本地文件或远程 HTML 转换为 Markdown，并归档为知识型 .octx 文件。当前规划基线为 M2.8 （0.2.1），普通解析与连接器取数不依赖外部事项提取或向量服务。

文档

1. 计划总览
2. 安装与快速上手
3. 配置手册
4. 文档解析 API
5. 连接器 API
6. 钉钉连接器与 MCP 方案
7. 服务 API 与部署

安装

python -m pip install zleap_parser

# URL 采集首次使用时准备浏览器二进制
python -m camoufox fetch

可选能力通过 extras 安装：

python -m pip install "zleap_parser[pdf]"
python -m pip install "zleap_parser[xlsx]"
python -m pip install "zleap_parser[media]"       # 另需系统 ffmpeg
python -m pip install "zleap_parser[db-all]"
python -m pip install "zleap_parser[dingtalk-oa]" # 钉钉 OA MCP（可选）
python -m pip install "zleap_parser[dingtalk-profile]" # 钉钉加密 profile（可选）

SQLite、Markdown 归档和普通文本解析可直接运行。RTF/XLSX 预览需要系统 soffice/libreoffice；URL 采集需要 Camoufox 浏览器二进制。

最小示例

import zleap_parser
from zleap_parser import CacheConfig, Parser

zleap_parser.config(cache=CacheConfig(cache_namespace="sdk-default"))
parser = Parser()

parsed = parser.parse(file="/path/to/document.pdf")
print(parsed["result"])       # 已存在的 *.octx 路径
print(parsed["usage"])        # 完整零用量账本

csv_path = parser.pack_csv_to_octx("name,age\nAlice,30\n")
print(csv_path)

Parser.parse(url=...) 与 Parser.parse(file=...) 必须二选一。归档产物包含 knowledge/main.md、metadata 和原始附件；不会生成事项、关系或向量文件。

连接器

from zleap_parser.connector import Connector, RSSAdapter

result = Connector().fetch(
    adapter=RSSAdapter(url="https://example.com/feed.xml", limit=20)
)
print(result["results"])       # knowledge-only *.octx 路径列表
print(result["usage"])         # 普通数据源为完整零用量

内置数据源包括 RSS/WebSearch/DeepCrawl、企业微信/飞书/Salesmartly/钉钉 聊天与群列表、钉钉知识库/云盘/文档/OA 审批、邮件、API 请求、 GitHub/GitLab/Gitee 仓库、DB/BigDB。所有数据源统一使用 fetch()； 邮件额外返回邮件 OCTX 列表和 sync-cursor OCTX。

Git 仓库分析是唯一默认会调用模型的取数场景。它使用统一 LLMConfig 和 OpenAI-compatible 客户端，分析摘要写入 knowledge Markdown，代码文件作为 附件归档；usage 明细统一为 kind="llm"。

配置和多模态能力

文本及未来多模态请求统一使用 LLMConfig。supports_multimodal=False 为 默认值，只有显式设置为 True 才表示模型接受多模态消息；M2.8 不执行多模态 enrichment，不根据模型名猜测能力，也不静默降级。

CacheConfig.cache_namespace 默认 "sdk-default"，参与所有缓存 key/signature。 多租户服务必须为每个任务创建独立配置快照，例如 tenant-<sha256(tenant_id) 前 32 位>，不得在并发任务中修改全局配置。

文件格式

支持文本、源码、PDF、RTF、DOCX、PPTX、XLSX、HTML、XML、图片和音视频。 格式识别优先依据内容特征；新增格式通过 BaseAdapter 插件接入。

API 变更（M2.8）

• 保留 Parser.parse()、pack_to_octx()、pack_csv_to_octx()、 pack_xlsx_to_octx() 和 Connector.fetch()。
• 直接删除旧的事项提取/向量入口、旧连接器组合入口及其残留模块； 不提供兼容别名、弃用警告或失败桩。
• 移除 embedding 配置和独立视觉模型/图片处理配置；只保留 LLMConfig.supports_multimodal 能力字段。
• OCTX metadata 写入 com.zleap.parser.archive_schema=knowledge-only/1， capability 集合显式为空。

历史需求和旧版本行为请查阅 plan/M1、plan/M2、plan/M2.5、 plan/M2.6、plan/M2.7 及 CHANGELOG.md；这些记录不构成当前安装或 API 依据。