开源生态调研 · 技能场景化

对可融入清海 AI 助理的 GitHub 开源项目进行技术层面的逐项分析，重点标注与清海现有架构的差距和集成路径。

优先级总览

项目	Stars	优先级	集成成本	核心价值
larksuite/lark-openapi-mcp	官方	⭐⭐⭐ 立即	低	飞书所有 API 工具化，技能不用自己写
pymupdf/pymupdf4llm	~2k	⭐⭐⭐ 立即	极低	PDF/文档解析，直接 pip 安装
vanna-ai/vanna	~23k	⭐⭐⭐ 中期	中	自然语言→SQL，数据查询技能核心
unclecode/crawl4ai	~61k	⭐⭐⭐ 中期	中	主动情报采集，每日简报来源
infiniflow/ragflow	~75k	⭐⭐ 中期	高	企业 RAG，接入公司知识库
assafelovic/gpt-researcher	~20k	⭐⭐ 中期	中	多 Agent 深度调研
eosphoros-ai/DB-GPT	~16k	⭐ 参考	高	数据分析全栈，参考其 SQL Agent 设计
anthropics/claude-agent-sdk-python	官方	⭐⭐ 参考	中	Agent 工具调用范式，优化清海技能架构

1. larksuite/lark-openapi-mcp

是什么

飞书官方将其 OpenAPI 全量包装为 MCP（Model Context Protocol）Tools，AI Agent 可以直接 tool_use 方式调用飞书的所有接口，无需手写 SDK 封装。

涵盖：消息发送、文档读写、日历事件、审批流程、人事组织、多维表格、云空间文件等 200+ 个 API。

技术实现

MCP Server（本地进程或远程部署）
  ↓ 标准 MCP 协议（stdio / SSE transport）
Claude Agent ←→ tool_use 调用
  ↓
飞书 OpenAPI（REST）

MCP Server 以 TypeScript/Go 实现，Claude 不直接调用飞书 API，而是通过 MCP 协议转发。每个飞书接口被映射为一个 MCP Tool，包含完整的 JSON Schema 参数描述，Claude 可自动匹配。

与清海现状的差距

维度	清海现状	lark-openapi-mcp
飞书调用方式	`feishu_bot.py` 手写 REST 封装，覆盖范围有限	官方全量 API，200+ 接口开箱即用
技能覆盖度	主要是消息收发，日历/审批/多维表格需自己写	日历、审批、多维表格、妙记等全覆盖
维护成本	飞书 API 升级需手动同步	官方维护，API 变更自动更新
接入方式	Python SDK（`larksuite/oapi-sdk-python`）直接调用	MCP 协议，Claude 工具调用

集成路径

清海的 skills/ 目录下，新增飞书类技能时从手写 HTTP 改为调用 MCP 工具：

原来：Skill → feishu_bot.py → oapi-sdk-python → 飞书 REST API
改后：Skill → MCP Tool call → lark-openapi-mcp → 飞书 REST API

配置方式：在 Claude agent loop 中注册 MCP server，飞书工具自动注入上下文。

2. pymupdf/pymupdf4llm

是什么

PyMuPDF 团队专门为 LLM/RAG 场景打造的 PDF → Markdown 转换库。与普通 PDF 解析库不同，它会保留文档结构（标题层级、表格、图片说明），输出对 LLM 友好的干净 Markdown。

技术实现

python

import pymupdf4llm

# 核心调用
md_text = pymupdf4llm.to_markdown("合同.pdf")

# 带图片提取
md_text = pymupdf4llm.to_markdown("报告.pdf", write_images=True)

# 按页分块（RAG 场景）
pages = pymupdf4llm.to_markdown("文档.pdf", page_chunks=True)
# 返回 List[{"metadata": {...}, "text": "..."}]

特点：

表格识别好，转为 Markdown 表格而非乱码文字
公式保留 LaTeX 格式
图片可提取为 base64 或文件
支持多列布局智能合并

与清海现状的差距

清海目前没有文档解析能力。员工发来合同/报告/产品文档时，无法直接读取内容回答问题。

维度	清海现状	pymupdf4llm
PDF 处理	无，收到文件只能说"无法读取"	解析为 Markdown，送入上下文
表格处理	无	保留表格结构，适合数据提取
集成复杂度	—	`pip install pymupdf4llm`，3 行代码
输出格式	—	LLM 友好 Markdown，可直接进 RAG

集成路径

作为清海 文档解析 技能的底层库：

python

# skills/doc_reader/skill.py
import pymupdf4llm

async def read_document(file_path: str) -> str:
    """读取 PDF/Word 文档，返回 Markdown 文本"""
    return pymupdf4llm.to_markdown(file_path)

飞书收到文件附件时，先下载到临时目录，调用此技能解析后送入对话上下文。

3. vanna-ai/vanna

是什么

自然语言 → SQL 的开源框架，核心是 RAG 增强的 Text-to-SQL。不是简单的 prompt 转 SQL，而是维护一个"SQL 示例库"，每次查询时先检索相似历史 SQL，再让 LLM 生成新 SQL，极大提高准确率。

技术实现

用户："昨日 GMV 是多少？"
  ↓
① 向量检索：从历史 SQL 库里找相似问题的 SQL 片段
② 上下文增强：将相关 DDL 表结构 + 历史 SQL 示例拼入 prompt
③ LLM 生成 SQL
④ 执行 SQL（可配置是否自动执行）
⑤ 返回结果 + 原始 SQL（透明可审计）

核心组件：

python

import vanna

vn = vanna.connect(model='claude-3', api_key='...')

# 训练阶段：喂入业务 DDL 和历史 SQL
vn.train(ddl="CREATE TABLE orders (id, gmv, created_at...)")
vn.train(sql="SELECT SUM(gmv) FROM orders WHERE date = yesterday")

# 使用阶段
sql = vn.generate_sql("昨日 GMV 是多少")
df = vn.run_sql(sql)

支持：MySQL/PostgreSQL/MongoDB/BigQuery，支持行级权限，有审计日志，有 Web UI。

与清海现状的差距

清海目前无数据查询能力，员工问业务数据（GMV、用户数、订单量）必须人工查询再回复。

维度	清海现状	vanna
数据查询	无	自然语言→SQL，覆盖业务数据库
准确率保障	—	RAG 增强，历史 SQL 作为示例库提高准确率
安全性	—	行级权限控制，不同员工看不同数据
透明度	—	返回执行的 SQL，可审计
多数据源	—	支持主流数据库 + MongoDB

关键差距：清海的记忆系统用 Qdrant 做语义检索，vanna 的 RAG 专门针对 SQL 生成优化（DDL 结构感知、SQL 语法约束）。两者可以并存，各司其职。

集成路径

新增 DataQuery 技能，内嵌 vanna 实例：

python

# skills/data_query/skill.py
vn = VannaDefault(model='claude-sonnet-4-6', config={...})
vn.connect_to_mysql(host=..., dbname=...)

async def query_data(question: str) -> dict:
    sql = vn.generate_sql(question)
    result = vn.run_sql(sql)
    return {"sql": sql, "data": result.to_dict()}

4. unclecode/crawl4ai

是什么

专为 LLM 场景设计的异步爬虫框架。与传统爬虫不同，它的输出目标是干净的、LLM 可直接处理的 Markdown，而非原始 HTML。支持 JS 渲染、批量并发、MCP 接入。

技术实现

python

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig

async def crawl(url: str) -> str:
    browser_cfg = BrowserConfig(headless=True)
    run_cfg = CrawlerRunConfig(
        markdown_generator=DefaultMarkdownGenerator(
            content_filter=PruningContentFilter()  # 去广告/导航栏
        )
    )
    async with AsyncWebCrawler(config=browser_cfg) as crawler:
        result = await crawler.arun(url=url, config=run_cfg)
        return result.markdown.fit_markdown  # 干净的正文 Markdown

特点：

Playwright 驱动，处理 JS 渲染页面（动态内容）
fit_markdown：自动过滤广告/菜单/页脚，只保留正文
支持批量 URL 并发爬取
内置 MCP Server，可直接注册为 Claude 工具
支持结构化提取（CSS selector / LLM 提取）

与清海现状的差距

清海目前是被动响应型，没有主动信息采集能力。要实现"每日竞品动态"、"行业新闻简报"需要爬虫支撑。

维度	清海现状	crawl4ai
信息来源	只有飞书/TG 消息，无外部输入	可抓取任意网页，实时获取外部信息
输出质量	—	干净 Markdown，LLM 可直接处理
JS 渲染	—	Playwright 驱动，动态页面也能抓
与清海集成	—	可作为 MCP Tool 注册到 agent loop
定时触发	—	配合清海的 daemon.py 定时任务

关键差距：清海已有 daemon.py 定时调度，但没有外部信息源。crawl4ai 填补这个空缺，使清海能主动感知外部世界。

集成路径

技能层封装：

python

# skills/web_search/skill.py
from crawl4ai import AsyncWebCrawler

async def fetch_page(url: str) -> str:
    """抓取网页正文，返回 Markdown"""
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(url=url)
        return result.markdown.fit_markdown

5. infiniflow/ragflow

是什么

企业级 RAG 引擎，解决的核心问题是"深度文档理解"。普通 RAG 直接把文档按字数切块，ragflow 使用视觉模型+结构分析，理解文档的真实语义边界（章节/表格/图表/脚注），大幅提升检索质量。

技术实现

架构分层：

文档处理层（离线）：
  上传文档 → OCR/视觉模型 → 语义分块 → 向量化 → Elasticsearch + 向量库

检索层（在线）：
  查询 → 混合检索（向量 + BM25 全文）→ 重排序（Cross-encoder）→ 上下文组装

生成层：
  组装后的上下文 → LLM → 带来源引用的回答

特点：

支持 Word/PDF/PPT/Excel/网页/Markdown，表格/图表均可理解
混合检索：向量相似度 + BM25 关键词，召回率更高
结果带文件来源+页码引用，可追溯
提供完整 REST API，可作为独立服务部署
自带 Web UI，可手动管理知识库

与清海现状的差距

清海现有记忆系统（Qdrant + BM25）面向的是对话记忆和个人知识，不适合处理公司文档库（合同/规范/SOP/产品文档）。

维度	清海现状	ragflow
文档处理	无结构化文档入库能力	智能分块，表格/图表也能理解
检索质量	Qdrant 向量 + BM25，无重排序	向量 + BM25 + Cross-encoder 重排
来源引用	无	回答附带文件名+页码，可追溯
文件格式	纯文本/Markdown	Word/PDF/Excel/PPT/图片
部署方式	内嵌清海进程	独立服务，REST API 接入

关键差距：清海的 memory/searcher.py 做的是"对话记忆"检索，不是"文档知识"检索。两者应该是并列的两条检索路径，ragflow 负责文档层，清海自有记忆系统负责对话层。

集成路径

6. assafelovic/gpt-researcher

是什么

多 Agent 并行深度调研框架。一次调研请求会拆解为多个子问题，多个 Agent 并行搜索，最终汇总生成带引用来源的完整报告。

技术实现

用户："帮我分析竞品 X 的产品策略"
  ↓
① 规划 Agent：将问题拆解为 5-8 个子问题
② 并行搜索 Agent（每个子问题一个）：
   - 网页搜索（Tavily/DuckDuckGo/Bing）
   - 抓取相关页面（crawl4ai 底层）
   - 提取关键信息
③ 汇总 Agent：整合所有子结果，生成结构化报告
④ 输出：Markdown 报告 + 来源引用列表

支持多种输出：研究报告、详细报告、资源报告、大纲报告。

与清海现状的差距

清海目前无法完成"调研"类任务，只能回答基于记忆的问题。

维度	清海现状	gpt-researcher
调研能力	无	多 Agent 并行，覆盖多信息源
报告质量	—	带引用、有结构、可验证
处理时间	—	并行搜索，通常 2-5 分钟
信息时效	—	实时网络搜索

关键差距：gpt-researcher 是独立的 Agent 框架，与清海的 agent loop 并列，而不是清海的一个技能。调用方式是：清海识别"调研意图" → 异步调用 gpt-researcher → 结果回传清海 → 清海格式化推送。

集成路径

python

# skills/research/skill.py
from gpt_researcher import GPTResearcher

async def deep_research(query: str) -> str:
    """深度调研，返回 Markdown 报告"""
    researcher = GPTResearcher(
        query=query,
        report_type="research_report",
        config_path="research_config.json"  # 配置 API 密钥
    )
    await researcher.conduct_research()
    report = await researcher.write_report()
    return report

7. eosphoros-ai/DB-GPT

是什么

完整的企业 AI 数据分析平台。不只是 Text-to-SQL，还包含：多 Agent 协作、数据可视化、代码执行、多数据源连接（200+）、RAG 知识库。类似于 AI 版的 Metabase。

技术实现

核心模块：

AWEL（Agentic Workflow Expression Language）
  ├── Data Agent：SQL 生成 + 结果解释
  ├── Chart Agent：自动选择图表类型并渲染
  ├── Code Agent：Python 代码生成 + 沙箱执行
  └── Analysis Agent：多轮交互式分析

特点：

支持 MySQL/PostgreSQL/MongoDB/Hive/Spark/Presto 等
内置图表渲染（ECharts）
对话式数据探索（"按月分组看看"、"过滤掉异常值"）
完整 REST API，可接入外部系统

与清海现状的差距

DB-GPT 比 vanna 重得多，是一个完整平台而非库。

维度	清海 + vanna	DB-GPT
定位	清海技能（轻量嵌入）	独立平台，清海调用其 API
图表	无	内置 ECharts 可视化
多轮分析	清海对话天然支持	独立的对话式分析会话
部署复杂度	低	高（独立服务，依赖多）
推荐用法	中小型团队直接用	参考其 SQL Agent 设计模式

建议：直接部署 DB-GPT 成本高，更有价值的是参考其 DataAgent 的设计——尤其是"表结构剪枝"（只把与问题相关的表 DDL 送入 prompt）和"多轮修正"（SQL 执行报错时 LLM 自动修复）两个模式，借鉴到清海的数据查询技能中。

8. anthropics/claude-agent-sdk-python

是什么

Anthropic 官方新出的 Agent SDK，提供标准化的工具调用框架，支持 in-process MCP（不需要独立 MCP Server 进程，工具函数直接注册）。

技术实现

python

from anthropic_agent_sdk import AgentLoop, Tool

@Tool
async def get_weather(city: str) -> str:
    """获取城市天气"""
    return f"{city} 今天晴，25°C"

# Agent Loop 自动处理 tool_use 循环
loop = AgentLoop(
    model="claude-sonnet-4-6",
    tools=[get_weather],
    system="你是天气助手"
)
result = await loop.run("北京今天天气怎么样？")

特点：

工具注册使用装饰器，比手写 JSON Schema 简洁
内置权限控制（工具级别的允许/拒绝）
支持 streaming
in-process MCP：工具函数和 Agent 在同一进程，无 RPC 开销

与清海现状的差距

清海现在的工具注册是手写 JSON Schema，在 llm/client.py 的 agent_loop() 中手动处理 tool_use 循环。

维度	清海现状	claude-agent-sdk-python
工具注册	手写 JSON Schema dict	`@Tool` 装饰器，从类型注解自动生成
Agent Loop	自实现（`agent_loop()` 约 100 行）	SDK 封装，内置重试/错误处理
权限控制	无工具级权限	内置工具级允许/拒绝
MCP 支持	需要独立 MCP Server 进程	in-process，函数直接注册
维护成本	SSE 解析、工具循环需自己维护	SDK 维护，跟随 API 升级

建议：不是全量迁移，而是在新技能中参考其工具注册模式（装饰器 + 类型注解），逐步统一清海技能的工具定义方式，减少手写 JSON Schema 的冗余。

技术差距汇总

能力域	现状	推荐方案	优先级
文档解析	无	pymupdf4llm（立即可用）	P0
飞书 API 覆盖度	仅消息	lark-openapi-mcp（官方）	P0
数据查询	无	vanna + 业务数据库	P1
外部信息采集	无	crawl4ai（每日简报）	P1
企业知识库	无	ragflow（独立部署）	P2
深度调研	无	gpt-researcher	P2
工具定义标准化	手写 JSON Schema	claude-agent-sdk 装饰器模式	P3

开源生态调研 · 技能场景化 ​

优先级总览 ​

1. larksuite/lark-openapi-mcp ​

是什么 ​

技术实现 ​

与清海现状的差距 ​

集成路径 ​

2. pymupdf/pymupdf4llm ​

是什么 ​

技术实现 ​

与清海现状的差距 ​

集成路径 ​

3. vanna-ai/vanna ​

是什么 ​

技术实现 ​

与清海现状的差距 ​

集成路径 ​

4. unclecode/crawl4ai ​

是什么 ​

技术实现 ​

与清海现状的差距 ​

集成路径 ​

5. infiniflow/ragflow ​

是什么 ​

技术实现 ​

与清海现状的差距 ​

集成路径 ​

6. assafelovic/gpt-researcher ​

是什么 ​

技术实现 ​

与清海现状的差距 ​

集成路径 ​

7. eosphoros-ai/DB-GPT ​

是什么 ​

技术实现 ​

与清海现状的差距 ​

8. anthropics/claude-agent-sdk-python ​

是什么 ​

技术实现 ​

与清海现状的差距 ​

技术差距汇总 ​

开源生态调研 · 技能场景化

优先级总览

1. larksuite/lark-openapi-mcp

是什么

技术实现

与清海现状的差距

集成路径

2. pymupdf/pymupdf4llm

是什么

技术实现

与清海现状的差距

集成路径

3. vanna-ai/vanna

是什么

技术实现

与清海现状的差距

集成路径

4. unclecode/crawl4ai

是什么

技术实现

与清海现状的差距

集成路径

5. infiniflow/ragflow

是什么

技术实现

与清海现状的差距

集成路径

6. assafelovic/gpt-researcher

是什么

技术实现

与清海现状的差距

集成路径

7. eosphoros-ai/DB-GPT

是什么

技术实现

与清海现状的差距

8. anthropics/claude-agent-sdk-python

是什么

技术实现

与清海现状的差距

技术差距汇总