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。
• 本地烟测回归命令。
• 运行健康检查。

架构

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。