md2video 开源项目深度研究报告

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

---

一、项目全景

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

仓库	Stars	Forks	Commits	语言	最新活动	License
leether/md2video	0	0	17	Python 99.1%	2026-06-07	MIT
isomoes-video/md2video	4	3	40	Python 66.6%	近期活跃	未标注
am009/md2video	2	0	1	Python 99.5%	2025-09-05	MIT

三个项目均处于早期阶段，社区活跃度低。但 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. 三层质检体系（行业首创）

级别	检查项数	策略	典型检查项
L1 硬阻塞	6项	失败即阻断输出	三方一致性、placeholder=0、音频存在性、timeline完整性
L2 警告	5项	失败输出警告	音画差值≤2s、分辨率1080×1920、帧率30fps±1
L3 模式检查	8项	人工+自动	箭头语义、颜色语义、emoji兼容性、二维码完整性

#### 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 实现：

模板	用途
`animated_text`	文字渐入动画
`bar_chart`	柱状图对比
`pie_chart`	饼图展示
`trend_line`	趋势折线图
`comparison_split`	左右对比画面
`table_scroll`	表格逐行展示
`bullet_list`	要点列表+高亮
`calendar_highlight`	日历高亮标注
`quote_card`	引用卡片+渐入

#### E. 语义段落类型推断

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

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

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

2.4 技术栈

类别	技术
语言	Python 3.10+
语音合成	edge-tts（微软免费TTS）
视频处理	ffmpeg + ffprobe
图像处理	Pillow, numpy, scipy
AI素材	即梦CLI（jimeng-cli，可选）
包管理	uv pip
CI/CD	GitHub Actions
系统依赖	ffmpeg（brew安装）

2.5 版本演进

版本	日期	核心变更
v1.0.0	2026-06-06	初始版本：核心引擎+质检体系+6种动画模板
v1.1.0	2026-06-07	自创生系统+规则驱动分镜+3种新动画+CI/CD

> 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） 的演化路径：

时代	主界面	操作者
传统软件	GUI（按钮、面板）	人类
开发者工具	CLI（命令）	程序员
AI 时代	CUI（聊天）	AI Agent + 人类审查

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 的关键差异

维度	leether/md2video	isomoes-video/md2video
设计哲学	Pipeline自动化	Agent-First架构
幻灯片引擎	纯Python动画模板	reveal.js (HTML/CSS/JS)
TTS方案	edge-tts	edge-tts
视频合成	ffmpeg双路径引擎	ffmpeg
质检体系	L1/L2/L3三级	人类审查
自演化	Autopoiesis免疫系统	无
发布能力	无	B站上传
Stars	0	4

---

四、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 现状评估

维度	评价
PyPI版本	v0.0.1（2025-09-05）
成熟度	⭐ 极早期
维护状态	❌ 停更（仅1次commit）
License	MIT（但仓库无LICENSE文件）
安装方式	`pip install md2video`

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

---

五、三项目关系图谱

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" 理念但技术路线不同。

---

六、技术路线对比

维度	leether/md2video	isomoes-video/md2video	am009/md2video
输入格式	Markdown/纯文本	Markdown/纯文本	Markdown脚本
分镜方式	AI规则驱动自动拆解	Prompt引导Agent	手动标记
幻灯片	Python动画模板	reveal.js HTML	reveal.js HTML
TTS	edge-tts	edge-tts	kokoro-onnx
视频合成	双路径引擎	ffmpeg	python-ffmpeg
质检	L1/L2/L3自动化	人类审查	无
自演化	Autopoiesis	无	无
外部API依赖	即梦CLI（可选）	无	无
发布能力	无	B站上传	无
安装复杂度	中等	低	低（pip）
视频质量	高（动画模板）	中（HTML截图）	低（HTML截图）
定制灵活度	高（规则可演化）	高（prompt可改）	低
适合场景	数据可视化/教程/产品介绍	演示文稿转视频	概念验证

---

七、社区与生态

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 生态关联

项目	关联生态
leether/md2video	姊妹项目 `leether/md2wechat`（Markdown→公众号排版），共享自创生免疫系统
isomoes-video/md2video	子模块 `isomoes-video/ai-video`，博客文章《md2video：一种Agent-First的Markdown转视频方式》
am009/md2video	PyPI包 `md2video`，CSDN教程

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 项目风险

风险	等级	说明
社区太小	🔴 高	0-4 stars，遇到问题只能靠自己
单人维护	🟡 中	三个项目均为单人开发
依赖 edge-tts	🟡 中	微软非官方API，稳定性无保障
中文字体硬编码	🟡 中	leether版硬编码 Hiragino Sans GB (macOS)
ffmpeg依赖	🟢 低	系统级工具，广泛可用

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
核心创新	Autopoiesis 自创生免疫系统
设计范式	Agent-First / Agent Workspace
技术成熟度	早期但架构完整，可用
社区状态	极早期（0-4 stars）
适合人群	AI Agent 用户、内容创作者、技术博主
最大风险	单人维护，社区支持薄弱
长期价值	代表 Agent-Native 软件的未来方向

---

> 📌 仓库地址 > - 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/

md2video 开源项目深度研究报告

md2video 开源项目深度研究报告

一、项目全景

二、leether/md2video —— 旗舰项目

2.1 项目定位

2.2 架构总览

2.3 核心技术亮点

2.4 技术栈

2.5 版本演进

2.6 作为 WorkBuddy Skill 的设计

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

3.1 项目定位

3.2 三大支柱

3.3 界面范式转变

3.4 工作流程（8步）

3.5 与 leether/md2video 的关键差异

四、am009/md2video —— 原始 PyPI 包

4.1 项目定位

4.2 技术方案

4.3 Markdown 语法

4.4 现状评估

五、三项目关系图谱

六、技术路线对比

七、社区与生态

7.1 活跃度总览

7.2 生态关联

7.3 外部关注

八、综合评价与建议

8.1 如果今天要用 md2video

8.2 项目风险

8.3 发展潜力

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

安装

基础用法

作为 WorkBuddy Skill 使用

十、总结

🌟 智谱 GLM-5 已上线