media_to_doc 1.0.0__tar.gz

media_to_doc-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches: [master, feat/**, fix/**]
+  pull_request:
+    branches: [master]
+
+# 取消同分支前序运行(节省 CI 资源)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ───────────────────────────────────────────────────────────
+  # Python 后端测试与代码质量(Phase 0 启用)
+  # ───────────────────────────────────────────────────────────
+  python:
+    name: Python (windows-latest)
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.11.x"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies (with dev extras)
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run --python ${{ matrix.python-version }} ruff check src/ tests/
+
+      - name: Format check (ruff)
+        run: uv run --python ${{ matrix.python-version }} ruff format --check src/ tests/
+
+      - name: Type check (mypy, lenient)
+        run: uv run --python ${{ matrix.python-version }} mypy src/media_to_doc/
+        continue-on-error: true  # Phase 0 类型注解宽松,逐步收紧
+
+      - name: Test (pytest)
+        run: uv run --python ${{ matrix.python-version }} pytest tests/ -v --maxfail=1
+
+      - name: Test coverage (pytest-cov,optional)
+        if: matrix.python-version == '3.12'
+        run: uv run --python ${{ matrix.python-version }} pytest tests/ --cov=media_to_doc --cov-report=term-missing
+        continue-on-error: true
+
+  # ───────────────────────────────────────────────────────────
+  # UI 构建(Phase 2+ 启用,Phase 0 注释掉)
+  # ───────────────────────────────────────────────────────────
+  # ui:
+  #   name: UI (windows-latest)
+  #   runs-on: windows-latest
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-node@v4
+  #       with:
+  #         node-version: "20"
+  #     - run: npm ci
+  #       working-directory: ui
+  #     - run: npm run lint
+  #       working-directory: ui
+  #     - run: npm run test
+  #       working-directory: ui
+  #     - run: npm run build
+  #       working-directory: ui
+
+  # ───────────────────────────────────────────────────────────
+  # NSIS 安装器打包(Phase 3+ 启用)
+  # ───────────────────────────────────────────────────────────
+  # installer:
+  #   name: NSIS Installer
+  #   runs-on: windows-latest
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - name: Build installer
+  #       run: |
+  #         # NSIS 安装器构建脚本(Phase 3 实施时填实)
+  #         echo "NSIS build placeholder"

media_to_doc-1.0.0/.gitignore

@@ -0,0 +1,80 @@
+# ─────────────────────────────────────────────────────────────
+# media-to-doc .gitignore
+# 遵循 CLAUDE.md §7 + ROADMAP Phase 0 + _research/ 不进 git
+# ─────────────────────────────────────────────────────────────
+
+# ── Python ──────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+.installed.cfg
+*.egg-info
+
+# ── 虚拟环境 ─────────────────────────────────────────────────
+.venv/
+venv/
+env/
+ENV/
+
+# ── 测试与覆盖率 ────────────────────────────────────────────
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.cache
+
+# ── 类型检查 ─────────────────────────────────────────────────
+.mypy_cache/
+.ruff_cache/
+.pyright_cache/
+
+# ── 编辑器 / IDE ─────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# ── 项目专属:研究材料不入 git(Phase 5 迁 LE 原型到 src/ 再纳入) ──
+# _research/ 已纳入屏蔽(CLAUDE.md §4 + ROADMAP §0)
+_research/
+
+# ── 项目专属:运行时工作目录 ──────────────────────────────────
+# workspace/ 运行时数据(inbox 输入 + work 中间产物 + raw 产出)
+workspace/inbox/*
+workspace/work/*
+!workspace/inbox/.gitkeep
+!workspace/work/.gitkeep
+
+# ── 环境变量与密钥(严禁入 git,见 CLAUDE.md 安全红线) ──
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# ── 日志 ─────────────────────────────────────────────────────
+*.log
+logs/
+
+# ── 模型与缓存(不进 git,用户本地保留) ───────────────────────
+models/
+*.safetensors
+*.bin
+*.pt
+*.pth
+
+# ── 构建产物 ─────────────────────────────────────────────────
+*.spec
+.mount/

media_to_doc-1.0.0/.learnings/ERRORS.md

@@ -0,0 +1,42 @@
+# media-to-doc 项目级错误库 — ERRORS
+
+> **目的**:追踪重复出现的错误模式(Pattern-Key),由 LE L4 进化层自动晋升。
+> **晋升规则**:同一 Pattern-Key 在 `work/<course>/ERRORS.md` 中出现 ≥ 3 次时,自动写入本文件。
+> **幂等**:已存在的 Pattern-Key 不会重复写入(参见 `_research/le_prototype/learnings.py:escalate_recurring_errors`)。
+> **使用**:`PipelineLogger` 启动时读本文件,命中已知模式时注入警告或前置校验。
+
+---
+
+## 晋升条目(自动写入)
+
+<!--
+Phase 5 时 LE L4 落地后,自动追加形如:
+## [Connection:ollama]
+**First promoted**: 2026-07-18 09:30:00
+**Occurrences**: 3 (across 5 shown)
+**Threshold**: 3
+**Auto-detected**: True
+**Examples**:
+- `course1/ERRORS.md`
+- `course2/ERRORS.md`
+- `course3/ERRORS.md`
+
+**Recommended action**: review / write rule / patch code
+-->
+
+(Phase 0 尚无条目,Phase 5 LE L4 落地后由 `post_pipeline_hook` 自动追加)
+
+---
+
+## 手动录入条目(可选)
+
+```markdown
+## [Custom:keyword]
+
+**First seen**: YYYY-MM-DD HH:MM:SS
+**Occurrences**: N
+**Description**: <错误描述>
+**Root cause**: <根因>
+**Fix**: <修复方法>
+**Affected code**: <src/.../file.py:line>
+```

media_to_doc-1.0.0/.learnings/LEARNINGS.md

@@ -0,0 +1,300 @@
+# media-to-doc 项目级学习库 — LEARNINGS
+
+> **目的**:积累项目开发过程中沉淀的最佳实践(best_practice),供未来会话/开发者复用。
+> **格式**:每条 LP-YYYYMMDD-NNN 条目,包含 标题 / 上下文 / 做法 / 启示 四部分。
+> **写入**:Claude 在每个里程碑 commit 时主动追加;也可人工编辑。
+> **关联**:`../_research/le_prototype/`(LE 原型)、`../PRD.md` §4.1.G、`../TDD.md` §4.5。
+> **W9 实装**(首批 LP 条目):W1-W8 关键 best_practice 沉淀。
+
+---
+
+## 模板
+
+```markdown
+### LP-YYYYMMDD-NNN — <标题>
+
+**上下文**: <何时何地遇到的问题 / 学到的经验>
+**做法**: <具体如何解决 / 实践>
+**启示**: <对未来开发者的建议 / 通用原则>
+**相关文件**: <src/.../file.py:line>、<docs/...>
+**作者**: <Claude 自动 / 用户 / 协作者>
+```
+
+---
+
+## 条目
+
+### LP-20260718-001 — 11 stage 函数签名统一 `(work: Path, config: WorkflowConfig)`
+
+**上下文**:W1 把 11 stage 从占位转成实装,每个 stage 都需要拿到 work 目录 + config,
+签名不统一会让 runner `_invoke_stage` 写大量 `if/else` 分发。
+
+**做法**:
+- 全部 stage 函数签名:`(work: Path, config: WorkflowConfig) -> <StageResult>`
+- runner 用统一 `_invoke_stage(stage, func, ctx)` 包装,ctx 注入 `inbox / state / logger`
+- chapters / draft / longdoc 三个 LLM 阶段走 wrapper(`_chapters_wrapper` 等)从 config 派生 LLM provider
+
+**启示**:流水线 stage 签名统一 = runner 极简,新增 stage 只需在 `STAGE_FUNCS` 注册一行。
+
+**相关文件**:`src/media_to_doc/pipeline/runner.py:50-90`(STAGE_FUNCS / _chapters_wrapper),
+`src/media_to_doc/pipeline/runner.py:287-407`(_invoke_stage 三分支)
+**作者**:Claude W1
+
+---
+
+### LP-20260718-002 — LLM provider 用 ABC + lazy import,缺库时给清晰 ImportError
+
+**上下文**:W2 接 3 个 LLM provider(ollama / anthropic / openai_compat),用户可能没装全部 SDK。
+
+**做法**:
+- 基类 `BaseLLMProvider`(`llm/base.py`)用 `abc.ABC`,子类只实现 `_chat_impl`
+- 实际 SDK(ollama / anthropic / openai)在子类 `__init__` 内 lazy import
+- 缺库时 `raise ImportError("请 pip install media-to-doc[llm_anthropic]")`
+- `llm/__init__.py` 顶层只暴露基类 + 工厂函数,3 个具体 provider 通过 `_register_defaults()` 延迟注册
+
+**启示**:ABC 强约束接口 + lazy import 强隔离重依赖,测试时可只装 ollama。
+
+**相关文件**:`src/media_to_doc/llm/base.py`、`src/media_to_doc/llm/anthropic.py`、`src/media_to_doc/llm/ollama.py`
+**作者**:Claude W2
+
+---
+
+### LP-20260718-003 — chapters JSON 解析做宽松适配(围栏 / 前缀文字 / `[` 到 `]` 切片)
+
+**上下文**:W2 chapters 阶段用 LLM 输出章节列表,LLM 输出经常不规范(带 ```json 围栏 / 前缀文字 / 解释行)。
+
+**做法**:`chapters.py:_parse_chapters_response` 三重容错:
+
+1. 先 strip markdown 围栏(```json ... ```)
+2. 正则找第一个 `[` 到最后一个 `]` 切片
+3. 解析失败时用 json.JSONDecoder.raw_decode 从 `[` 开始逐字符尝试
+
+**启示**:LLM 输出永远不要相信,用最宽松的解析策略 + 友好错误信息。
+
+**相关文件**:`src/media_to_doc/pipeline/chapters.py`(W2 实装)
+**作者**:Claude W2
+
+---
+
+### LP-20260718-004 — imagegen ABC + Protocol 双轨(产品代码 ABC,测试 duck-typed)
+
+**上下文**:W3 imagegen 阶段要支持 2 种 provider(local_sdxl / skip)+ 未来插件扩展。
+
+**做法**:
+- 产品代码用 `abc.ABC` 强制 `generate(prompt) -> Path` 接口
+- 测试用 `typing.Protocol` duck-typed mock(无需继承 ABC),让测试 fixture 更轻量
+- `SkipProvider.generate()` 直接返回 None,render 阶段检测到 None 时退化警告文字
+
+**启示**:ABC 用于运行时多态,Protocol 用于测试替身 — 双轨互不干扰。
+
+**相关文件**:`src/media_to_doc/pipeline/imagegen.py`(W3)
+**作者**:Claude W3
+
+---
+
+### LP-20260718-005 — render 阶段缺失图自动退化为警告文字
+
+**上下文**:W3 render 时 chapters.json 引用 `gen_001.png` 等图,但 imagegen skip 时图不存在。
+
+**做法**:`render.py` 拼装 HTML 时:
+
+1. 先扫 `images/` 子目录,把存在的图存进 `_existing_images: set[str]`
+2. 渲染时若引用图不在 set,输出 `<p><em>[图片缺失: gen_001.png]</em></p>` 而非坏链接
+3. verify 阶段检查 image_refs 与实际文件一致
+
+**启示**:缺失外部资源永远不要 raise,降级显示比中断流水线更有价值。
+
+**相关文件**:`src/media_to_doc/pipeline/render.py:150-220`(W3)
+**作者**:Claude W3
+
+---
+
+### LP-20260718-006 — draft 默认输出到 `<work>/chapters/raw/<stem>/`,后续可注入 inbox
+
+**上下文**:W3 draft 阶段产物应放哪里?work 中间产物 vs inbox 最终产物?
+
+**做法**:
+- 默认:`<work>/chapters/raw/<stem>/chapter_NN.md`(中间产物,可清空重跑)
+- runner 接受 `output_dir` 参数,W5 smoke 跑通时把它注入到 `inbox/raw/<stem>/`
+- `render` 阶段从 `_resolve_drafts_dir(work)` 派生路径,与 default 一致
+
+**启示**:中间产物与最终产物物理隔离,方便 resume / 重跑 / 归档。
+
+**相关文件**:`src/media_to_doc/pipeline/runner.py:407-419`(_resolve_drafts_dir)、`src/media_to_doc/pipeline/draft.py`
+**作者**:Claude W3
+
+---
+
+### LP-20260718-007 — Ollama `num_ctx` 默认 65536,长 transcript 调 LLM 必备
+
+**上下文**:W5 smoke 跑真实课程(50816 tokens transcript)时 Ollama 报"exceeds context size"。
+
+**根因**:Ollama `num_ctx` 默认 4096,Qwen3-14B 原生 32k(可 RoPE 扩展到 65k)。
+
+**做法**:`LLMConfig.num_ctx = 65536`(默认),`OllamaProvider` 创建时显式传 `num_ctx`。
+chapters 阶段 prompt 也做 30000 chars 截断(留 system prompt + 输出空间)。
+
+**启示**:本地 LLM 调长 prompt 时,context window 是隐性瓶颈,必须显式声明。
+
+**相关文件**:`src/media_to_doc/config.py:43`、`src/media_to_doc/llm/ollama.py`
+**作者**:Claude W5
+
+---
+
+### LP-20260718-008 — longdoc 默认 `provider="skip"`,规则清理兜底
+
+**上下文**:W4 longdoc 阶段要不要默认调 LLM?
+
+**决策**:**默认 skip,只跑规则清理**(去时间戳 / 合并空行)。LLM 净化是可选项。
+
+**做法**:
+- `PipelineConfig.longdoc_llm_provider = "skip"`(默认)
+- `process_long_doc` 检测 `provider=None` 时走纯规则分支
+- CI 离线环境(无 GPU)可全跑通过,真用时再 `--longdoc-llm anthropic`
+
+**启示**:默认行为应该是最保守 / 最兼容的(零 GPU 依赖),高级功能用 opt-in flag 开启。
+
+**相关文件**:`src/media_to_doc/config.py:80`、`src/media_to_doc/pipeline/longdoc.py`
+**作者**:Claude W4
+
+---
+
+### LP-20260719-009 — Gatekeeper image_refs 候选路径 3 重试(md-link / wiki-link / images 子目录)
+
+**上下文**:W8 gatekeeper 检查 lecture.md 引用的图片是否存在。原型只查 basename,W3-W5 后
+产物布局变了(图可能在 `images/` 子目录,引用可能是 wiki-link `![[foo.png]]` 或 md-link `![alt](images/foo.png)`)。
+
+**做法**:对每个 image_ref,候选路径 = 3 个:
+
+```python
+candidates = [
+  lecture_dir / ref,                # 原路径
+  lecture_dir / basename,           # 同目录(wiki-link)
+  lecture_dir / "images" / basename,  # images 子目录(W3 render 默认)
+]
+```
+
+任一存在即 OK,3 个都不存在才报 missing。
+
+**启示**:产物布局会演化,文件存在性检查永远做候选路径重试,不要假设单一布局。
+
+**相关文件**:`src/media_to_doc/logger/gatekeeper.py`(W8)
+**作者**:Claude W8
+
+---
+
+### LP-20260719-010 — PipelineLogger 三层 try/except 异常隔离,LE 失败不破坏 run_pipeline
+
+**上下文**:W8 LE 接入 runner 末尾:`gatekeeper_check` / `logger.finalize` / `post_pipeline_hook`
+任何一项失败(磁盘满 / 权限不够),都不应破坏 `run_pipeline` 的 return 值。
+
+**做法**:`run_pipeline` 末尾三层 try/except,每个 catch 后只 `print(..., file=sys.stderr)`:
+
+```python
+try:
+  ...  # 主流水线
+finally:
+  try: gatekeeper = gatekeeper_check(work)
+  except Exception as exc: print(f"[le] gatekeeper failed: {exc}", file=sys.stderr)
+  try: pipeline_run = logger.finalize(...)
+  except Exception as exc: print(f"[le] logger.finalize failed: {exc}", file=sys.stderr)
+  try: post_pipeline_hook(work)
+  except Exception as exc: print(f"[le] post_pipeline_hook failed: {exc}", file=sys.stderr)
+```
+
+**启示**:LE 是辅助 / 沉淀层,不是调度真相。state.json(主真相)始终先 save,LE 失败可观察但不致命。
+
+**相关文件**:`src/media_to_doc/pipeline/runner.py:540-585`(W8)
+**作者**:Claude W8
+
+---
+
+### LP-20260719-011 — `assess_llm_health.total_runs` 只计成功解析的 run_file
+
+**上下文**:W8 health 评估跨 run 的 LLM 失败率。原 `assess_llm_health` 把损坏的 JSON run_file 也计入 `total_runs`,污染统计。
+
+**做法**:引入 `parsed_runs` 单独计数,只在 `json.loads` 成功时 +1;`total_runs` 字段 = 成功解析数。
+损坏文件只 warn,不计入分母。
+
+**启示**:跨 run 聚合统计要严格区分"目录数" vs "有效数据数",分母必须可信。
+
+**相关文件**:`src/media_to_doc/logger/learnings.py:129-198`(W8)
+**作者**:Claude W8
+
+---
+
+### LP-20260719-012 — PEP 562 `__getattr__` 实现 lazy import,重依赖按需加载
+
+**上下文**:W9 让 `from media_to_doc import run_pipeline` 跨项目可用,但 `import media_to_doc` 不应触发
+faster-whisper / diffusers / anthropic 等重依赖。
+
+**做法**:
+- `__init__.py` 用 PEP 562 模块级 `__getattr__(name)`,从 `_LAZY_EXPORTS: dict[str, str]` 查目标模块路径
+- 用户访问 `media_to_doc.run_pipeline` 时才 `importlib.import_module("media_to_doc.pipeline.runner")`
+- 首次访问后缓存到 `globals()[name]`,后续访问走正常属性查找
+- `__dir__()` 列出所有公开符号,IDE 自动补全可用
+
+**启示**:Python 3.7+ 的 PEP 562 是包顶层 re-export 的最佳实践,比 `import *` 更可控。
+
+**相关文件**:`src/media_to_doc/__init__.py`(W9)、`tests/test_init.py`(26 用例)
+**作者**:Claude W9
+
+---
+
+### LP-20260719-013 — 测试不要真跑 11 stage,monkeypatch 是已验证模式
+
+**上下文**:11 stage 涉及 ffmpeg / faster-whisper / SDXL,CI 环境无法真跑。
+
+**做法**:
+- `tests/test_pipeline/test_runner.py` 用 monkeypatch 把 `STAGE_FUNCS[stage]` 替换为 mock 函数
+- mock 函数只写产物文件,不真调重依赖
+- 验证:`state.stages[stage].status == "completed"` + 文件存在
+- 同样模式适用 `test_llm/*`(mock provider)、`test_imagegen/*`(Protocol duck-typed)
+
+**启示**:单测 / 集成测中,重依赖全部 mock。E2E 测单独跑(本项目 `scripts/run_smoke.py`)。
+
+**相关文件**:`tests/test_pipeline/test_runner.py`(W4-W8 共用模式)
+**作者**:Claude W1-W8
+
+---
+
+### LP-20260719-014 — stdout 留给 JSON,所有日志走 stderr
+
+**上下文**:CLI 的 `--json` 输出与 MCP 的 stdio JSON-RPC 都依赖 stdout 纯净。调试 log 走 stdout 会破坏输出。
+
+**做法**:
+- CLI:`sys.stdout.write(json.dumps(...))`,不用 `console.print`(Rich 把 `[...]` 当 markup)
+- MCP server:handler 内 `print(..., file=sys.stderr)`,stdout 留给 JSON-RPC 帧
+- logger 配置:Python `logging` 默认走 stderr
+
+**启示**:stdout = 数据契约,stderr = 人类观察。混用就是埋雷。
+
+**相关文件**:`src/media_to_doc/cli.py`(eprint helper)、`src/media_to_doc/mcp_server.py`(_log helper)
+**作者**:Claude W6 + W7
+
+---
+
+### LP-20260719-015 — `StageContext.metrics` 做跨 stage 累积容器,wrapper 注册 + 末尾聚合
+
+**上下文**:流水线中多个 stage 需要累积运行时指标(LLM 调用统计、计时、外部 SDK 句柄等),传统做法是 module-level 全局变量 / 参数透传,但前者多 run 冲突,后者改 STAGE_FUNCS 接口。
+
+**做法**:
+- `StageContext` 加 `metrics: dict[str, Any]` 字段,默认 `default_factory=lambda: {"llm_providers": {}}`
+- 3 个 LLM wrapper(`_chapters_wrapper` / `_draft_wrapper` / `_longdoc_wrapper`)签名从 `(work, config)` 改为 `(ctx)`,创建 provider 后注册 `ctx.metrics["llm_providers"][stage_name] = provider`
+- `run_pipeline` 把 `ctx = StageContext(...)` 创建移到 `for` loop 外,让 metrics 跨 stage 累积
+- run_pipeline 末尾(LE finally 块)调聚合 helper:`_aggregate_llm_health(ctx.metrics)` → 喂给 `logger.finalize(llm_health=...)`
+- 聚合 key 用 `{stage_name}_{provider.name}`(跨 stage 不冲突 + `assess_llm_health` 仍 sum)
+
+**启示**:跨 stage 累积 = ctx 设计模式。ctx 已经存在(共享 inbox/work/config),直接扩 fields 不引入新概念。配合 wrapper 接受 ctx + 聚合 helper,模块化和测试都不破坏。**通用模式**:任何需要在多步骤流水线末尾聚合运行时数据的场景(Pipeline / Builder / Saga 模式),都适合 "ctx.metrics + 注册 + 末尾聚合" 三件套。
+
+**相关文件**:`src/media_to_doc/pipeline/runner.py`(StageContext / 3 wrapper / `_aggregate_llm_health`)
+**作者**:Claude W10-C
+
+---
+
+## 沉淀规则
+
+- 每条 LP 条目必须有 **上下文 / 做法 / 启示** 三段,缺一不收
+- "启示"段必须可复用(其它项目也适用),不能只描述本项目特定 case
+- W+ 数字 = W1/W2/.../W9 的开发会话标识,新增条目按 `LP-YYYYMMDD-NNN` 自增编号
+- 重复出现的 ERRORS.md Pattern-Key 由 LE L4 进化层自动晋升到本文件(参见 `.learnings/ERRORS.md`)

media_to_doc-1.0.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `media-to-doc` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.0.0] - 2026-07-20
+
+### 🎉 First stable release
+
+11 阶段流水线全跑通,3 种调用方式(CLI / Python API / MCP server),Loop Engineering 五层闭环端到端接入。
+W10-A 真端到端验证:107 分钟中文培训视频 3 小时 57 分钟跑完,529 测试 0 失败。
+
+### Added
+
+- **11 阶段流水线** (W1-W4):`audio → asr → frames → ocr → asr_correct → chapters → draft → imagegen → render → longdoc → verify`
+- **可插拔 LLM**:Ollama(默认) / Anthropic / OpenAI-compatible(MiniMax、DeepSeek、智谱、Moonshot、混元、OpenRouter 等 7 个 preset)
+- **可跳过重模块**:`imagegen_provider=skip` 让 Claude 自己做配图,`longdoc_llm_provider=skip` 用规则清理代替 LLM 净化
+- **3 种调用方式**(W6 / W7 / W9):
+  - **CLI** `mtd run | resume | status | list | doctor | config | mcp`
+  - **Python API** PEP 562 `__getattr__` 顶层 re-export,52 个公开符号 lazy import,启动 < 100ms
+  - **MCP server** 8 工具(W7=6 + W8=2),stdio JSON-RPC,Claude Desktop / Codex / Cline 原生集成
+- **Loop Engineering 五层闭环**(W8,见 `.learnings/` LEARNINGS.md / ERRORS.md):
+  - L1 执行层:`timed_stage(logger, stage)` 包裹每 stage
+  - L2 审核层:`gatekeeper_check(work)` 4 项机器可验证
+  - L3 沉淀层:`pipeline_run.json` 写盘,含 `llm_health` / `gatekeeper_passed` / `quality` / `errors`
+  - L4 进化层:`post_pipeline_hook` 扫 Pattern-Key 自动晋升到 `.learnings/ERRORS.md`
+  - L5 健康度:`assess_llm_health` 失败率 > 10% → `switch_provider` 建议,> 20% → `reduce_chunk` 建议
+- **跨 run 健康度查询** (W8):`get_run_metrics(work)` / `list_runs(workspace)`,Python API + MCP 工具等价
+- **状态持久化与断点续跑** (W4 / W6):`state.json` 11 stage 调度真相 + `pipeline_run.json` LE 沉淀双轨;`mtd resume <work>` 自动从 state 派生 inbox
+- **可分发的产物**:图片一律相对路径(`<stem>/images/gen_*.png`),产物目录整盘复制到任何电脑/上传网盘/丢知识库路径不失效
+- **LEARNINGS 系统**:14 条 LP-YYYYMMDD-NNN best_practice 条目(W1-W8 沉淀)
+
+### Changed
+
+- **产物布局**(W3 / W4):render 输出从 `<drafts_dir>/<stem>.md` 移到 `<drafts_dir>/<stem>/<stem>.md`,longdoc 写 `<drafts_dir>/<stem>_cleaned.md` + `<drafts_dir>/<stem>_final.html`(W5 兼容旧布局)
+- **Ollama 默认 num_ctx** = 65536(W5 long transcript 支持 qwen3:14b 32K RoPE 扩展)
+- **chapters prompt transcript 截断** = 30000 chars(W5 适配 32K context 留 system 余量)
+
+### Fixed
+
+- **OCR 输出路径不一致**(W5):runner ocr 阶段不传 output_dir → OCR 写 `inbox/img/ocr/`,asr_correct 读 `work/ocr/` 不匹配 → JSONDecodeError;统一写到 `work/ocr/`
+- **Ollama 上下文超长**(W5):`num_ctx=None` → Ollama 默认 4096 → 50K tokens 超 32K max → 4 stage 全部失败;`num_ctx=65536` 修
+- **transcript 截断缺失**(W5):`_load_transcript` 不限长度 → chapters prompt 50K tokens → 默认 → 显式截 30000 chars
+- **longdoc/verify 路径布局兼容**(W5):`db92ac9` `_check_outputs_exist` 兼容新旧两布局
+- **W8 llm_health 聚合自动**(W10-C `bddc387`):`StageContext.metrics` 跨 stage 累积,`_aggregate_llm_health` helper 替换原 `{}` TODO
+- **Gatekeeper vs Verify 不一致**(W11-A `d2b39d3`):gatekeeper resolver 写死 W4 原型路径,verify 迁 W5 新布局后两者对同一份数据给相反结论;新布局优先 + 旧布局回退,image_refs 加 `<stem>/images/` 候选
+
+### Tested
+
+- **529 pytest 用例 / 0 跳过**:W10-C 519 → W11-A +10 → 529。涵盖 11 stage 单元测试 + LE 闭环 + CLI + MCP server + 一致性回归
+- **W5 真实端到端冒烟**:1.3GB / 112min 中文培训视频 CPU 模式 ASR + frames + OCR + LLM 全跑通
+- **W10-A 真端到端验收**:395MB / 107min 中文培训视频 CPU 模式 3h57min,llm_health 真聚合 chapters_ollama(1 calls) + draft_ollama(6 calls),0 failures
+
+---
+
+## [0.1.0-dev] - 2026-07-18
+
+开发起点。骨架 + 5 个占位模块(14 测试)。
+
+### Added
+
+- 项目骨架:uv init + pyproject.toml + src/ + tests/ + workspace/ + .learnings/ + .github/workflows/
+- 5 个占位模块:`__init__` / `cli` / `paths` / `config` / `state` + `logger/__init__`
+- 14 测试 (`tests/test_smoke.py`) + ruff + mypy + pytest CI
+
+[1.0.0]: https://github.com/media-to-doc/media-to-doc/releases/tag/v1.0.0
+[0.1.0-dev]: https://github.com/media-to-doc/media-to-doc/releases/tag/v0.1.0-dev