DocAvatar：文档 → Markdown → 思维导图（预览/带背）
DocAvatar 是一个面向学习与内容创作的“文档理解与讲解助手”。它由教育开源项目 DotsOCR 衍生开发，聚焦多场景的知识获取与表达：文档转换、思维导图可视化、逐段带背、要点讲解、播客传播、研学对话与以练带学。 它将文档转换为结构化 Markdown，并在浏览器端通过思维导图进行可视化呈现；在“带背模式”中，系统会按分块自动执行：生成导图 → 回填 → 朗读 → 推进下一块，支持断点续播与缓存。
本项目包含三部分：
- Gradio 主应用（固定对外端口 10222，内部 7860）
- Automindmap 子应用（前端 + Node 服务，端口 5173）
- 可选推理/转换后端（如 vLLM/OpenAI 兼容接口/Kimi 等）
- 带背模式（MEM）
- 目标：通过精细化思维导图抽取关键知识点，逐段朗读与自动推进，辅助记忆与复习。
- 流程：分块 → 模型生成导图 Markdown → 回填右侧 → 朗读 → ACK 推进下一块。
- 讲解模式
- 目标：针对章节要点进行结构化讲解，自动生成类 PPT 页面或讲解大纲。
- 流程：大模型 API 分析 → 生成分节页面（标题、要点、示例/图示占位）→ 导出与复用。
- 播客模式
- 目标：以播客形式传播知识，支持长文精炼、章节串讲与结构化对谈脚本。
- 流程：调用 API 生成播客脚本 → 可选 TTS/外部播客工作流。
- 研学模式
- 目标：亦师亦友的研究式讨论，在探讨中完善知识库、形成问题清单与调研计划。
- 流程：对话式推理与资料汇集 → 结论沉淀至 Markdown/导图/任务清单。
- 练习模式
- 目标：围绕知识点进行精细化题目管理，以练带学，形成闭环反馈。
- 流程：要点 → 题目生成/导入 → 分层练习与讲评 → 错题/薄弱点回流导图与讲解。
- 文档转 Markdown：支持 PDF/图片/Office（通过后端 API）
- 思维导图可视化：基于 Markmap，自动为标题注入锚点、片段预览
- 带背模式（MEM）：
- 分块最深标题切分，逐段“生成导图 → 回填 → 朗读 → 自动推进”
- 朗读失败/无语音环境亦会自动推进（ACK 兜底）
- Base64 内联图片自动剔除后再送入导图模型
- 讲解/播客/研学/练习联动：讲解页、播客脚本、研学对话与练习题流转到同一知识骨架
- 设置持久化：跨端口（10222 ⇄ 5173）双向同步；忽略空值覆盖，防止误清空
- 可扩展模型接入：支持 Kimi/OpenAI 兼容接口（Bearer Key）、后续可扩展 qwen/gpt/claude
- 10222：对外入口（反向代理转发至 7860）
- 7860：Gradio 内部端口
- 5173：Automindmap 服务（前端 + API 转发/设置持久化）
关键目录：
docavatardev/docavatar_gradio.py：主应用（路由、模式、设置转发 /am/save-settings、/export-settings 代理）docavatardev/automindmap/：思维导图前端与服务（index.html、script.js、server.js）docavatardev/forward_10222.js：10222 → 7860 HTTP/WS 转发docavatardev/start_docavatar.sh：一键启动脚本（固定端口、并发进程）
- 准备环境
- Linux/WSL2 推荐；需要 Node ≥ 18、Python ≥ 3.10
- 建议已安装 Chrome/Edge（浏览器端朗读依赖 Web Speech API，在部分环境不可用时系统会自动推进但不发声）
- 启动
bash ./docavatardev/start_docavatar.sh
# 启动后访问：http://localhost:10222- 配置思维导图模型（必填）
- 进入“带背模式 A”设置，填写：
- 思维导图 API Base（OpenAI 兼容接口或代理地址）
- 思维导图 API Key（Bearer 令牌）
- 思维导图模型（如
kimi-k2-0711-preview）
- 点击“保存带背模式 A 配置”以同步到 5173；设置在 5173 端以非空优先合并，避免被空值清空
- 使用带背模式
- 选取 Markdown 文本或从“预览模式”生成后，切换至“带背模式”
- 系统按分块逐段执行：模型生成导图 → 回填右侧 → 朗读 → 朗读完成发送 ACK → 推进下一段
- 若浏览器禁用语音或语音列表为空，仍会自动推进
Q: 填写设置后再次进入带背，为什么设置被清空？
- 已修复：/save-settings 采用“忽略空值的深合并”，避免空字段覆盖已有有效配置
Q: 仍然朗读原始分块而不是模型生成的导图？
- 请确认 5173 的
mindmap_api_base、mindmap_api_key、mindmap_model已写入且可用； - 预览面板现统一触发
generate-btn，确保走“API → 回填 → 朗读 → ACK”的流程
Q: 朗读卡住不推进？
- 已修复：无论 TTS 是否成功，都会发送
mem-ack，保障推进
AUTOMINDMAP_PORT：默认 5173GRADIO_INTERNAL_PORT：默认 7860GRADIO_PUBLIC_PORT：默认 10222- 以上已在
start_docavatar.sh中固定，也可自定义
欢迎提交 Issue 与 PR。建议变更遵循：
- 不改变既有默认端口行为
- 前端变更需兼容 iframe/embed（
embed=1&mode=mem） - 重要流程（API 调用、朗读、推进）需具备兜底与日志
本项目采用 GPL-3.0 开源许可证，详见根目录 LICENSE 文件。
- DotsOCR 教育开源项目与社区贡献者
- Gradio、Markmap、vLLM 及开源社区
- 所有测试与反馈的贡献者