EasySourceFlow

EasySourceFlow 是运行在本机的内容总结服务。用户把链接发给 Codex、OpenClaw 或其他支持 MCP 的 Agent，Agent 调用本地工具完成抓取、字幕/转写、总结，并把结果写成 Markdown 文件。

当前项目阶段的重点是：

• 微信公众号公开文章

• 普通网页文章

• B 站视频

• 本地 Markdown 输出

• 本机 Web 控制台

• MCP / HTTP 调用

• OpenAI-compatible 模型 API 总结

• 批量链接处理

• 本地文档上传

暂缓事项：

• Obsidian 入库

• YouTube 深度适配

• NotebookLM

• 复杂知识库、RAG、向量索引

YouTube 相关代码目前保留为实验能力和后续扩展点，不作为当前阶段的主要验收目标。当前版本没有 Obsidian 写入工具。

当前能力

• easysourceflowd: 本地 HTTP 服务，默认监听 127.0.0.1:8765。

• Web 控制台: 打开 http://127.0.0.1:8765/，可以提交链接、看健康状态、看最近任务和打开输出文件。

• Web 控制台支持上传 txt/md/srt/vtt/html/docx/epub/pdf，本地解析后提交总结。

• easysourceflow_mcp: stdio MCP 适配器，供 Agent 调用。

• 普通网页正文提取和元数据提取。

• 微信公众号公开文章提取，支持公开 HTML、正文节点、懒加载图片、页面元数据和 Playwright / Chrome 兜底。

• B 站视频元数据、字幕和资源包输出。

• 无字幕视频在时长允许时下载音频并调用本地转写。

• OpenAI-compatible 模型 API 总结，Web 可选择常见服务商并配置 API Key。

• SQLite 任务记录和结果缓存。

• 成功任务输出 Markdown 到 EASYSOURCEFLOW_OUTPUT_DIR。

• 批量链接提交和批量状态查询。

• 任务取消、重试、最近队列状态。

• 旧任务和旧输出清理，默认 dry-run。

• SQLite/输出目录备份、日志轮转和每日维护 LaunchAgent。

• 本地烟测回归命令。

• 运行健康检查。

Related MCP server: Crawl4AI MCP Server

架构

Codex / OpenClaw / other Agent
        |
        | MCP stdio
        v
easysourceflow_mcp
        |
        | http://127.0.0.1:8765
        v
easysourceflowd
        |
        +-- web / wechat / video extractors
        +-- transcription fallback
        +-- OpenAI-compatible digest
        +-- SQLite jobs and cache
        +-- Markdown output writer

Agent 不直接调用 yt-dlp、ffmpeg、Playwright 或文件写入。底层流程集中在本地服务里，避免不同 Agent 各自拼流程。

文档索引

• 需求文档

• 架构设计

• 技术设计

• 配置说明

• MCP 接口

• Agent 接入指南

• 部署说明

• 运行手册

• 安全与隐私

• 测试计划

• B 站回归样例

• 路线图

• ADR 0001: 使用 MCP 作为 Agent 集成入口

• ADR 0002: 使用本地守护服务加 MCP 适配器

快速开始

创建虚拟环境并安装依赖：

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

准备配置：

cp .env.example .env

编辑 .env，填入 EASYSOURCEFLOW_MODEL_API_KEY，以及可选的 B 站 cookies 文件路径。也可以启动后在 Web 的“模型配置”页面选择服务商并保存 API Key。不要把 .env 发给别人或提交到仓库。完整配置见 配置说明。

启动本地服务：

scripts/easysourceflow start

打开 Web 控制台：

scripts/easysourceflow open

健康检查：

scripts/easysourceflow health

常用服务命令：

scripts/easysourceflow status
scripts/easysourceflow stop
scripts/easysourceflow restart
scripts/easysourceflow logs
scripts/easysourceflow log-status
scripts/easysourceflow rotate-logs
scripts/easysourceflow regression

安装 macOS 开机自启动：

scripts/easysourceflow install-launchd
scripts/easysourceflow launchd-status

取消开机自启动：

scripts/easysourceflow uninstall-launchd

运行测试：

PYTHONPATH=src .venv/bin/python -m compileall -q src tests
PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v

清理预览：

scripts/easysourceflow cleanup-preview 14

确认要删除旧临时文件和旧输出时再执行：

scripts/easysourceflow cleanup-apply 14

备份 SQLite 和输出目录：

scripts/easysourceflow backup

安装每日 03:15 的自动备份和日志轮转：

scripts/easysourceflow install-maintenance-launchd
scripts/easysourceflow maintenance-status

launchd 模式会把运行副本放在 ~/.local/share/easysourceflow/launchd，避免后台进程直接依赖 Documents 目录里的源码。对应输出目录是 ~/.local/share/easysourceflow/launchd/output。

HTTP 示例

同步总结：

python3 - <<'PY'
import json
from urllib.request import Request, urlopen

payload = json.dumps({
    "url": "https://www.iana.org/help/example-domains",
    "instruction": "用中文总结这页内容。"
}).encode("utf-8")

request = Request(
    "http://127.0.0.1:8765/summarize",
    data=payload,
    headers={"content-type": "application/json"},
    method="POST",
)

with urlopen(request) as response:
    print(response.read().decode("utf-8"))
PY

异步任务：

python3 - <<'PY'
import json
from urllib.request import Request, urlopen

payload = json.dumps({
    "url": "https://www.bilibili.com/video/BV1e17Y6aE3U/",
    "instruction": "用中文总结，保留关键细节。"
}).encode("utf-8")

request = Request(
    "http://127.0.0.1:8765/jobs",
    data=payload,
    headers={"content-type": "application/json"},
    method="POST",
)

with urlopen(request) as response:
    print(response.read().decode("utf-8"))
PY

批量提交：

python3 - <<'PY'
import json
from urllib.request import Request, urlopen

payload = json.dumps({
    "urls": [
        "https://www.iana.org/help/example-domains",
        "https://www.bilibili.com/video/BV1e17Y6aE3U/"
    ],
    "instruction": "输出中文结构化摘要。"
}).encode("utf-8")

request = Request(
    "http://127.0.0.1:8765/batches",
    data=payload,
    headers={"content-type": "application/json"},
    method="POST",
)

with urlopen(request) as response:
    print(response.read().decode("utf-8"))
PY

MCP 工具

Agent 集成采用“MCP 工具 + 官方 Skill”两层结构：MCP 提供稳定能力，skills/easysourceflow/ 规定调用时机和交付行为。安装到 Agent 工作区：

scripts/easysourceflow install-skill "$AGENT_WORKSPACE"

先把 AGENT_WORKSPACE 设置为目标 Agent 的工作区路径。完整步骤见 Agent 接入指南。

当前 MCP 工具：

• easysourceflow_summarize_link

• easysourceflow_submit_link

• easysourceflow_get_job

• easysourceflow_favorite_result

• easysourceflow_retry_job

• easysourceflow_cancel_job

• easysourceflow_submit_document

• easysourceflow_submit_batch

• easysourceflow_get_batch

• easysourceflow_list_recent_jobs

• easysourceflow_search_outputs

• easysourceflow_bilibili_cookie_status

• easysourceflow_model_status

• easysourceflow_health_check

• easysourceflow_cleanup

• easysourceflow_backup

当前没有 Obsidian 保存工具。

输出文件

成功任务会把最终 Markdown 写入：

var/output/YYYY-MM-DD/<source_type>/

来源目录里会维护 latest.md，指向最近一次输出。

视频任务会额外生成资源包目录，通常包含：

• summary.md

• metadata.json

• source_info.json

• raw_metadata.json

• subtitle.vtt

• transcript.txt

• transcript_with_timestamps.txt

• timeline.md

实际文件取决于该视频是否有字幕、是否进行了转写。

Web 控制台会列出这些 Markdown 文件，支持按来源筛选、元数据搜索和全文搜索。点击条目会打开渲染后的 Markdown 页面，页面带目录、复制和下载入口。任务详情页会显示阶段、错误原因、下一步建议、输出路径，并支持筛选、重试和取消。批量报告区会显示每个链接的成功或失败状态。

本地文件输入只接收浏览器或 Agent 提交的文本内容，不让服务端按任意本机路径读取文件。当前适合 .txt、.md、.markdown、.srt、.vtt 等文本类文件。

重要配置

主要配置在 .env.example 中维护。当前常用项：

• EASYSOURCEFLOW_HOST

• EASYSOURCEFLOW_PORT

• EASYSOURCEFLOW_DATA_DIR

• EASYSOURCEFLOW_OUTPUT_DIR

• EASYSOURCEFLOW_BILIBILI_COOKIES_FILE

• EASYSOURCEFLOW_FFMPEG_PATH

• EASYSOURCEFLOW_WHISPER_CLI_PATH

• EASYSOURCEFLOW_WHISPER_MODEL_PATH

• EASYSOURCEFLOW_TRANSCRIPTION_BACKEND

• EASYSOURCEFLOW_MODEL_PROVIDER

• EASYSOURCEFLOW_MODEL

• EASYSOURCEFLOW_STRONG_MODEL

• EASYSOURCEFLOW_MODEL_API_KEY

• EASYSOURCEFLOW_MODEL_BASE_URL

• DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL，旧兼容变量，优先使用 EASYSOURCEFLOW_MODEL_*

验证状态

当前测试覆盖：

• URL 规范化和本地 URL 防护

• DeepSeek prompt

• 失败任务写入 SQLite

• 视频资源包输出

• 微信公众号抽取

• HTTP API

• MCP 工具发现

• 清理 dry-run

贡献与许可证

• 贡献说明见 CONTRIBUTING.md。

• 配置说明见 docs/CONFIGURATION.md。

• 本项目使用 MIT License。