ManiMind

ManiMind 是一个面向数学科普动画生产的多 Agent 编排项目。输入论文和笔记，输出可审核的讲解脚本、分镜、Manim 数学动画、HTML 科普片段，以及后续配音、字幕、剪辑拼接所需的结构化产物。

仓库定位是“编排层”，不重写外部渲染引擎内部实现。 ClaudeCode/ 仅作为可选参考源码包，其可复用编排能力已抽取到 src/manimind/。

当前架构要点

预启动阶段加载文档与配置，检测工具链，注册能力路径。
主 Agent 解析论文与笔记，产出研究总结、公式目录与项目状态。
协调 Agent 切分分镜并并发派发 HTML / Manim / SVG 子任务。
子 Agent 分别回写长期上下文和短期协作上下文。
审核 Agent 通过后，进入配音、字幕、剪辑拼接。

目录结构

ManiMind/
├─ AGENTS.md
├─ README.md
├─ docs/
├─ inputs/
│  ├─ papers/
│  └─ notes/
├─ frontend/
├─ configs/
├─ scripts/
├─ pdf/
├─ src/manimind/
├─ manim-worker-pov/
├─ tests/
├─ resources/
│  ├─ skills/html-animation/
│  ├─ skills/manim/
│  └─ references/hyperframes/
├─ runtime/
├─ outputs/
└─ logs/

输入素材放置

论文主文档放 inputs/papers/（支持 .md/.txt/.pdf）。
辅助笔记放 inputs/notes/。
在 manifest 里使用相对路径引用，例如：
- source_bundle.paper_path = "inputs/papers/my-paper.pdf"
- source_bundle.note_paths = ["inputs/notes/outline.md"]

初始化步骤

powershell -ExecutionPolicy Bypass -File .\scripts\init-workspace.ps1

同步第三方精选资产（白名单）：

powershell -ExecutionPolicy Bypass -File .\scripts\sync-thirdparty-assets.ps1

注意：

该脚本会先清空 resources/skills/html-animation/ 与 resources/references/hyperframes/ 后再复制白名单内容。
当前仓库已经带有这两份资源；若未确认上游源码路径存在，不要直接重跑。
需要刷新资源时，优先显式传入上游路径。

源仓库不在项目根目录时，可显式传路径：

powershell -ExecutionPolicy Bypass -File .\scripts\sync-thirdparty-assets.ps1 `
  -HtmlSkillSource "<AI-Animation-Skill-main 路径>" `
  -HyperframesSource "<hyperframes-main 路径>"

检查依赖：

powershell -ExecutionPolicy Bypass -File .\scripts\check-prerequisites.ps1

关键约束

第三方资产统一放在 resources/，不再使用独立 vendor/。
长期上下文只写 runtime/projects/<project_id>/。
短期协作上下文只写 runtime/sessions/<session_id>/。
审核未通过不得进入后处理。

编排 CLI（新增）

plan <manifest.json>：生成标准项目计划。
context-pack <manifest.json> <role_id> <stage>：生成角色上下文包。
context-pack ... --render-prompt-sections：额外输出提示词分段渲染结果。
task-update <manifest.json> <task_id> <status> <actor_role>：按状态机推进任务。
agent-message <manifest.json> <event_type> <role_id> <stage> --payload '{...}'：写入 worker.progress / worker.blocker / worker.result / review.decision 结构化消息。
run-to-review <manifest.json>：执行 ingest/summarize/plan/dispatch，并推进到 review。
rerun <manifest.json> <runner_name> [--segment <segment_id>]：重跑指定 runner（例如 rerun plan、rerun dispatch --segment seg-1）。
trace <manifest.json> --session-id <session_id> [--stage] [--role] [--failed-only]：查询会话级 LLM trace。
human-review <manifest.json> approve|return：人工审核放行或打回。
finalize <manifest.json> --tts-provider powershell_sapi|command|f5_tts|noop：审核通过后执行后处理并完成打包。
finalize 会尝试调用 ffmpeg 合并 manim 片段，生成 outputs/<project_id>/video/segments-merged.mp4；若有真实 wav 配音会继续生成 final-with-audio.mp4。
context-pack 默认会阻断角色非法阶段请求；需要显式放行时使用 --allow-disallowed-stage。
三个命令支持 --session-id，并会把状态与事件日志落盘到 runtime/projects/<project_id>/ 与 runtime/sessions/<session_id>/。
进度日志默认开启（stderr 输出），可用 MANIMIND_PROGRESS_LOG=0 关闭。
F5-TTS 子进程日志默认实时透传（前缀 [f5_tts]）；可用 MANIMIND_F5_LIVE_LOG=0 关闭。

F5-TTS 固定参考音频（项目内缓存）

默认约定把参考音频放在：

runtime/projects/<project_id>/voice/selena_reference.m4a

这样参考音频不会暴露在仓库根目录。模型缓存也固定在项目内：

runtime/projects/<project_id>/voice/hf-cache/

使用一键脚本触发 finalize + f5-tts：

powershell -ExecutionPolicy Bypass -File .\scripts\finalize-with-f5-tts.ps1 `
  -Manifest configs/max-function-review-demo.json `
  -ProjectId max-function-review-demo `
  -RemoveSilence

可选参数：

-ReferenceAudio：覆盖默认参考音频路径
-ReferenceText：提供参考音频文本（不填则自动转写）
-RefMinSeconds：参考音频有效时长下限（默认 28 秒，不足会自动补静音）
-MaxTotalSeconds：单次 batch 的参考+生成总时长预算（默认 30 秒）
-SessionId：指定会话 ID
-HfCacheRoot：指定已有 HuggingFace 缓存根目录（可复用本地已下载权重）
-PythonExe / -FfmpegExe：覆盖本机工具路径

LLM 配置（Responses / Chat Completions）

如需启用真实模型推理，至少配置：

OPENAI_API_KEY
MANIMIND_MODEL_BASE_URL（例如 https://api.apipool.dev）
MANIMIND_MODEL（例如 gpt-5.5）

可选配置：

MANIMIND_REVIEW_MODEL（默认同 MANIMIND_MODEL）
MANIMIND_REVIEW_API_KEY（默认复用 OPENAI_API_KEY）
MANIMIND_REVIEW_MODEL_BASE_URL（默认复用 MANIMIND_MODEL_BASE_URL）
MANIMIND_MODEL_WIRE_API（responses 或 chat_completions，默认 responses）
MANIMIND_REVIEW_MODEL_WIRE_API（默认跟随主路由）
MANIMIND_MODEL_PROVIDER（默认 apipool）
MANIMIND_MODEL_REASONING_EFFORT（如 xhigh）
MANIMIND_MODEL_SUPPORTS_REASONING_SUMMARIES（true/false）
MANIMIND_DISABLE_RESPONSE_STORAGE（true/false）
MANIMIND_WORKER_MODEL（例如 deepseekv4flash）
MANIMIND_WORKER_API_KEY（worker / planner / coordinator / renderer 路由的 API key）
MANIMIND_WORKER_MODEL_BASE_URL（默认复用 MANIMIND_MODEL_BASE_URL）
MANIMIND_WORKER_MODEL_WIRE_API（responses 或 chat_completions）
MANIMIND_WORKER_MODEL_REASONING_EFFORT
MANIMIND_WORKER_MODEL_SUPPORTS_REASONING_SUMMARIES

说明：

deepseekv4flash 会自动规范化为 deepseek-v4-flash。
主链路已移除模型回退逻辑；primary / review / worker 三条路由都使用显式配置。

Web API 骨架（新增）

新增 backend/ FastAPI 骨架，直接复用编排内核：
- POST /api/projects/plan
- GET /api/projects/{project_id}/runtime
- POST /api/projects/tasks
- POST /api/projects/tasks/update
- POST /api/projects/context-pack
- POST /api/projects/events/message
- GET /api/projects/{project_id}/events
- GET /api/projects/{project_id}/trace
- POST /api/projects/run-to-review
- POST /api/projects/rerun
- POST /api/projects/trace
- POST /api/projects/review/decision
- GET /api/projects/{project_id}/review-return
- POST /api/projects/finalize
启动示例（安装 api 依赖后）：

python -m pip install -e ".[api]"
python -m uvicorn backend.main:app --reload

如本机命令名不是 python，请替换为对应解释器。

前端控制台骨架（新增）

新增目录：frontend/manimind-console/
技术栈：Next.js 16 + React 19 + Tailwind CSS 4
当前作用：先验证控制台首页的信息结构、模块边界和后续 API 接线点
当前数据：/live 已接入 backend/ 的项目、任务、上下文、审核证据、产物与 trace 接口；/mock 仅保留为静态演示页

启动示例：

cd frontend\manimind-console
npm install
npm run dev

文档入口

独立 POV（新增）

manim-worker-pov/：Manim Worker 最小验证闭环（固定 spec -> 代码生成 -> 渲染 -> 日志修复）。
当前定位是独立 POC，用于验证 worker 侧协议与渲染修复，不视为 src/manimind/ 已接入的正式执行器。

Navigation Menu

Repository files navigation

ManiMind

当前架构要点

目录结构

输入素材放置

初始化步骤

关键约束

编排 CLI（新增）

F5-TTS 固定参考音频（项目内缓存）

LLM 配置（Responses / Chat Completions）

Web API 骨架（新增）

前端控制台骨架（新增）

文档入口

独立 POV（新增）

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.claude		.claude
backend		backend
configs		configs
docs		docs
frontend/manimind-console		frontend/manimind-console
inputs		inputs
logs		logs
manim-worker-pov		manim-worker-pov
outputs		outputs
pdf		pdf
resources		resources
runtime		runtime
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

ManiMind

当前架构要点

目录结构

输入素材放置

初始化步骤

关键约束

编排 CLI（新增）

F5-TTS 固定参考音频（项目内缓存）

LLM 配置（Responses / Chat Completions）

Web API 骨架（新增）

前端控制台骨架（新增）

文档入口

独立 POV（新增）

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages