md2video 开源项目深度研究报告

研究日期：2026年6月12日 | 研究范围：GitHub 全平台

一、项目全景

GitHub 上名为 "md2video" 的项目实有三个独立仓库，分别代表三种不同的技术路线与设计哲学：

三个项目均处于早期阶段，社区活跃度低。但 leether/md2video 架构最为完整，功能最丰富，也是唯一持续迭代的项目。

二、leether/md2video —— 旗舰项目

2.1 项目定位

"每次手动拼接视频，不是音画错位就是素材遗漏。后来写了个 pipeline，从文章到成品视频一条命令搞定，还自带免疫系统——越用越聪明。"

这是一个为 AI Agent（WorkBuddy、Claude Code 等） 设计的自动化短视频生成 Pipeline，核心理念是：人给方向，Agent 执行，系统自演化。

2.2 架构总览

┌─────────────────────────────────────────────────────┐
│                    输入层                            │
│         Markdown 文章 / 纯文本 / 任意文稿             │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  Step 0  分镜拆解层  storyboard_ai.py               │
│           规则驱动：hook→narrative→data_contrast→list │
│           输出: shots.json + prompts.json +          │
│                 segments_hint.json + transitions.json│
├─────────────────────────────────────────────────────┤
│  Step 1  语音生成层  segment_tts.py                  │
│           语义边界切分 → edge-tts → ffprobe 测时长   │
│           输出: segments.json（精确时长+语义类型）    │
├─────────────────────────────────────────────────────┤
│  Step 2  素材生成层  jimeng CLI / animation_templates│
│           9种纯Python动画模板 + 即梦AI素材            │
│           输出: scenes/ 目录（视频/图片/动画素材）    │
├─────────────────────────────────────────────────────┤
│  Step 3  时轴映射层  timeline_mapper.py              │
│           Clip模型 + 转场自动推断 + 三方一致性校验    │
│           输出: timeline.json                        │
├─────────────────────────────────────────────────────┤
│  Step 4  精确拼接层  concat_engine.py                │
│           双路径策略：-c copy（快速）/ filter_complex │
│           输出: final.mp4                            │
├─────────────────────────────────────────────────────┤
│  Step 5  质检回检层  harness.py + frame_extractor    │
│           L1硬阻塞/L2警告/L3人工确认                 │
│           输出: compliance_report.json               │
├─────────────────────────────────────────────────────┤
│  Step 6  自创生演化  self_report.py                  │
│           摩擦捕获 → 规则演化 → 活记忆更新            │
│           输出: LESSONS_LEARNED.md + video-rules.json │
└─────────────────────────────────────────────────────┘

2.3 核心技术亮点

A. 三层质检体系（行业首创）

B. 自创生免疫系统（Autopoiesis）

这是 md2video 最独特的设计——让系统从错误中自动学习：

摩擦点发生 → capture_friction() 记录 → auto_encode() 编码进规则
    ↓
video-rules.json 自动扩展 ← L3检查项自动新增
    ↓
LESSONS_LEARNED.md 活记忆更新（YAML frontmatter，机器可读）

实际效果：下次遇到同类问题，系统自动规避。这就是"越用越聪明"的底层机制。

C. 双路径拼接引擎

• 快速路径（-c copy）：无特效时直接拼接，速度极快
• 特效路径（filter_complex）：支持 xfade/acrossfade/fade/slideleft/wipeleft 等转场
• 自动路由：根据 timeline.json 中的转场配置自动选择路径

D. 9种纯Python动画模板

零外部 API 依赖，纯 Pillow+numpy 实现：

E. 语义段落类型推断

SegmentTypeAnalyzer 通过三层推断自动识别段落类型：

• 位置规则：首段→hook，末段→cta
• 关键词规则：「对比」「vs」「增长」→data_contrast
• 正则规则：日期格式→date，引用格式→quote

共支持 8 种语义类型：hook / narrative / data_contrast / list / date / quote / cta / transition

2.4 技术栈

2.5 版本演进

SKILL.md 标注当前版本 v1.3.0（已重写音频架构，废弃 acrossfade，迁移到 Python+numpy），但 GitHub Release 页面仅到 v1.1.0。

2.6 作为 WorkBuddy Skill 的设计

md2video 原生设计为 WorkBuddy Skill，安装方式极为简洁：

安装 Skill：从 https://github.com/leether/md2video 克隆，
创建符号链接到 ~/.workbuddy/skills/md2video，
然后运行 uv pip install -r requirements.txt 并提醒我安装 ffmpeg

触发关键词：「把这篇文章转成视频」「生成短视频」「Markdown转视频」「给这篇文章做分镜」

三、isomoes-video/md2video —— Agent-First 哲学版

3.1 项目定位

由博主 Isomoes（jiahaoxiang2000@gmail.com）创建，核心理念是 Agent-First 软件架构——软件的第一用户不是人，而是 AI Agent。

3.2 三大支柱

          ┌──────────────┐
          │   Workspace  │  ← 统一工作空间
          │  (顶层容器)   │
          └──────┬───────┘
       ┌────────┴────────┐
       ▼                 ▼
┌─────────────┐   ┌─────────────┐
│   Skills    │   │  MCP Tools  │
│ reveal.js   │   │ TTS + 拼接   │
│ 幻灯片技能   │   │ 辅助脚本     │
└─────────────┘   └─────────────┘

3.3 界面范式转变

Isomoes 提出了从 GUI → CLI → CUI（Chat User Interface） 的演化路径：

3.4 工作流程（8步）

1. 准备源文件（source.md）或直接文本
2. Agent 用 slide-prompt.md 创建 reveal.js 幻灯片
3. 人类审查 生成的演示文稿
4. Agent 用 tts-prompt.md 生成逐页旁白 MP3
5. Agent 用 combine-prompt.md 合成为 video.mp4
6. （可选）生成简介文本
7. （可选）生成缩略图
8. （可选）通过 upload_bilibili.py 发布到 B站

3.5 与 leether/md2video 的关键差异

四、am009/md2video —— 原始 PyPI 包

4.1 项目定位

最早的 md2video 实现，作为 PyPI 包发布（pip install md2video），目标是将 Markdown 同时转为视频和 PPT。

4.2 技术方案

Markdown 脚本
    ├── pandoc filters → Reveal.js 幻灯片
    ├── Playwright → 每页截图
    ├── kokoro-onnx → TTS 语音
    └── python-ffmpeg → 视频合成

4.3 Markdown 语法

<!-- mode: slide -->

# PPT标题
PPT内容

<!-- mode comment -->
这里是解释。会被转为语音配上画面。

4.4 现状评估

定位：概念验证项目，已事实停更，不建议用于生产。

五、三项目关系图谱

am009/md2video (2025-09)         ← 原始概念
    │  PyPI: pip install md2video
    │  pandoc + reveal.js + Playwright
    │  1 commit, 已停更
    │
    ├── 理念启发 ──→ isomoes-video/md2video    ← Agent-First哲学
    │                   reveal.js + prompt驱动
    │                   40 commits, 4 stars
    │                   含B站上传功能
    │
    └── 独立发展 ──→ leether/md2video          ← 旗舰实现
                        纯Python动画 + Autopoiesis
                        17 commits, v1.1.0+
                        WorkBuddy Skill 原生设计

三个项目虽同名，但无直接代码继承关系，各自独立发展。leether/md2video 与 isomoes-video/md2video 共享 "Agent-First" 理念但技术路线不同。

六、技术路线对比

七、社区与生态

7.1 活跃度总览

三个项目的社区活跃度都极低——这是早期开源项目的典型特征：

• leether/md2video：0 star, 0 fork, 0 issue, 0 PR
• isomoes-video/md2video：4 star, 3 fork, 0 issue, 0 PR
• am009/md2video：2 star, 0 fork, 0 issue, 0 PR

7.2 生态关联

7.3 外部关注

• B站：leether/md2video 发布了 v0.1.5 自我介绍视频（2026-06-11）
• CSDN：《Markdown转视频工具MDVideo安装与配置指南》
• 博客：Isomoes Blog 三篇系列文章（Agent-First、Linux for Agent、Token方案）
• 今日头条：WorkBuddy 视频生成能力系列介绍文章（间接关联）

八、综合评价与建议

8.1 如果今天要用 md2video

首选 leether/md2video，理由：

1. ✅ 架构最完整——从分镜到质检的端到端闭环
2. ✅ 自创生免疫系统——真正"越用越聪明"
3. ✅ 原生 WorkBuddy Skill 设计——一条命令安装
4. ✅ 纯 Python 动画模板——零外部API也能跑
5. ✅ 三层质检——工业级质量保障
6. ✅ 活跃迭代——2026年6月仍在更新
7. ⚠️ 需要 ffmpeg + Python 环境

备选 isomoes-video/md2video：

• 适合需要 B站一键发布的场景
• 如果偏好 reveal.js 风格的幻灯片
• Agent-First 哲学更纯粹

不推荐 am009/md2video：

• 已停更，仅概念验证

8.2 项目风险

8.3 发展潜力

md2video 代表了一个明确趋势：AI Agent 正在成为软件的第一用户。随着 WorkBuddy、Claude Code、Cursor 等 Agent 平台的普及，"Agent Workspace" 这种新的软件交付形态会越来越常见。

leether/md2video 的 Autopoiesis 设计是这个趋势的前沿探索——让软件不仅被 Agent 使用，还能从 Agent 的使用中自我演化。

九、快速上手指南（leether/md2video）

安装

# 克隆仓库
git clone https://github.com/leether/md2video.git
cd md2video

# Python 依赖
uv pip install -r requirements.txt

# 系统依赖
brew install ffmpeg

# 可选：AI素材生成
# npm install -g jimeng-cli

基础用法

# 1. 旁白风格检查
python scripts/lint_narration_style.py --input article.md

# 2. 分镜拆解
python -c "
from extensions.storyboard.storyboard_ai import storyboard_from_article
storyboard_from_article(open('article.md').read(), output_dir='output')
"

# 3. 分段TTS
python core/segment_tts.py --input output/segments_hint.json --output output/segments.json

# 4. 时轴映射
python core/timeline_mapper.py --segments output/segments.json --prompts output/prompts.json

# 5. 精确拼接
python core/concat_engine.py --timeline output/timeline.json

# 6. 质检
python harness/harness.py --video output/final.mp4 --timeline output/timeline.json

# 7. 自创生演化
python harness/self_report.py

作为 WorkBuddy Skill 使用

直接将安装指令发给 WorkBuddy：

安装 Skill：从 https://github.com/leether/md2video 克隆，创建符号链接到 ~/.workbuddy/skills/md2video，然后运行 uv pip install -r requirements.txt 并提醒我安装 ffmpeg

然后在对话中直接说：「把这篇文章转成视频」即可触发。

十、总结

📌 仓库地址

• leether/md2video: https://github.com/leether/md2video
• isomoes-video/md2video: https://github.com/isomoes-video/md2video
• am009/md2video: https://github.com/am009/md2video

📦 PyPI: https://pypi.org/project/md2video/

📝 深度文章: https://isomoes.github.io/zh/blog/tools/md2video-agent-first/