# Manka-Studio

**Repository Path**: mrfox_wang/manka-studio

## Basic Information

- **Project Name**: Manka-Studio
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 漫咔 (ManKa Studio) — AI 漫剧自动化生成系统

[![License: CC BY-NC 4.0](https://img.shields.io/badge/License-CC_BY--NC_4.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc/4.0/)
[![Personal Learning Only](https://img.shields.io/badge/Use-Personal_Learning_Only-orange.svg)](#许可证)

> 把小说丢进去，让 AI 自动拆成分镜、出图、出视频、配音、合成为完整漫剧。
>
> ManKa — ManKa Studio's AI-powered anime-drama pipeline.

**⚠️ 许可证：本仓库采用 [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) 许可证 —— 个人学习使用 OK，**禁止任何商业用途**。详见 [LICENSE](LICENSE) 文件。**⚠️ This repository uses CC BY-NC 4.0 — personal learning use only, no commercial use.**

本系统覆盖**小说 → 分镜脚本 → 角色参考图 → 静态分镜图 → 视频片段 → AI 配音 → 视频合成**全流程。所有数据（包括生成的图片/视频/配音）都保存在你自己的电脑本地，不上传到我们的服务器。

## 品牌

| 名称 | 用途 |
|---|---|
| 漫咔 | 中文主品牌（用户界面、安装包名、菜单栏、文档） |
| ManKa | 英文主品牌（海外版本、英文文档、技术 README） |
| ManKa Studio | 工作室副品牌（产品系列、视频发布署名、对外合作） |
| mrfoxwang | 内部 npm 包标识符（git 远程、lockfile、CI 缓存） |

> 内部 npm 标识符保留 `mrfoxwang` 以避免破坏现有的 git remote、lockfile、CI 缓存；用户可见的所有字串已切换到新品牌。

## 谁在用

- 网文/轻小说作者 — 把长文一键变漫画式短视频
- 影视公司 — 前期分镜快速出图、给导演/客户看视觉走向
- 自媒体 — 小说推文配视频,大幅压缩制作周期

## 5 分钟快速开始

### 1) 安装

从 Releases 下载对应平台安装包:

- Windows: `漫咔-Setup-1.0.0.exe`
- macOS (Intel): `漫咔-1.0.0-x64.dmg`
- macOS (Apple Silicon): `漫咔-1.0.0-arm64.dmg`
- Linux: `漫咔-1.0.0.AppImage` 或 `.deb`

安装后启动应用,首次进入"欢迎使用"引导页。

### 2) 配置 API Key

需要 agnes-ai 服务的 API Key(本应用所有 AI 调用都走 agnes)。

1. 访问 [agnes-ai.com 控制台](https://agnes-ai.com/console/api-keys) 创建密钥
2. 在应用里点"去设置"
3. 粘贴 API Key 到"API Key"输入框
4. 点击"测试连接" — 显示模型列表即表示 OK
5. 点"保存"

> API Key 通过操作系统的安全存储加密保存:
> - Windows: DPAPI
> - macOS: Keychain
> - Linux: libsecret (KWallet / GNOME Keyring)
>
> 不会以明文形式写入数据库或配置文件。

### 3) 创建第一个项目

1. 首页 → "新建项目" → 选一本 `.txt` 小说 → 命名 → 创建
2. 应用自动分集(按章节切,默认 3000 字/集)
3. 进入项目 → 顶部"开始生成"(默认跑完整流水线) → 等待

### 4) 流水线预期耗时(单集 ~10 镜为例)

| 阶段 | 单次耗时 | 说明 |
|---|---|---|
| 分集 | < 1s | 本地解析 + DB 写入 |
| 人物提取 | 5-15s | LLM 调一次 |
| 生成分镜 | 5-15s | LLM 调一次 |
| 出图(每镜) | 20-60s | agnes-image-2.1-flash |
| 出视频(每镜) | 60-300s | agnes-video-v2.0(慢但稳) |
| TTS 配音 | 3-10s | edge-tts |
| 合成 | 5-15s | ffmpeg 本地 concat |

**单集 10 镜完整流水线 ≈ 15-40 分钟**。可在流水线启动前选预设,跳过视频可缩到 2-5 分钟。

### 5) 产物位置

所有生成的图片/视频/配音/最终合成视频都在本地 userData 目录:

| 平台 | 路径 |
|---|---|
| Windows | `%APPDATA%\漫咔\output\{projectId}\` |
| macOS | `~/Library/Application Support/漫咔/output/{projectId}/` |
| Linux | `~/.config/漫咔/output/{projectId}/` |

每个项目的产物结构:

```
output/{projectId}/
├── final/                      # 最终合成的分集 mp4
│   ├── episode_1.mp4
│   ├── episode_2.mp4
│   └── concat_list.txt         # 中间产物(ffmpeg 用)
├── images/                     # 分镜静态图
│   ├── shot_1.png
│   └── shot_2.png
├── videos/                     # 视频片段
│   ├── shot_1.mp4
│   └── shot_2.mp4
├── audio/                      # TTS 配音
│   ├── shot_1.mp3
│   └── shot_2.mp3
└── characters/                 # 人物参考图
    ├── {characterId}_front.png
    ├── {characterId}_side.png
    └── {characterId}_back.png
```

数据库(mrfoxwang.db)也在 userData 根目录,记录所有项目/分集/分镜/任务元数据。

## 系统要求

- **操作系统**: Windows 10 1909+ / macOS 12+ / Ubuntu 20.04+
- **内存**: 8 GB 起(并发跑 LLM/Image/Video 请求时峰值 ~3-4 GB)
- **磁盘**: 5 GB 起(单项目典型占 500 MB-2 GB)
- **网络**: 必须能访问 `apihub.agnes-ai.com`(大陆用户测试 50-200ms 延迟可用)
- **依赖**: ffmpeg(应用尝试自动找系统 PATH,未装时顶部 banner 提示)

### 可选依赖

- **edge-tts**: 配 Microsoft Edge TTS 服务的本地 CLI,需 `npm i -g edge-tts`(未装时 TTS 阶段会失败,顶部 banner 提示)
- **libsecret**(Linux): 让 API Key 走系统 Keyring 而非明文

## 常见问题 (FAQ)

**Q1. 点了"开始生成"没反应?**
- 顶部 banner 是否提示依赖缺失(API Key / ffmpeg / edge-tts)?→ 去对应页处理
- 检查底部任务抽屉的报错 → 通常是 API Key 错(401)或余额不足(402)
- 重启应用: 应用设置里"查看日志"会显示完整堆栈

**Q2. 视频生成卡在 5 分钟?**
- agnes 视频生成是异步任务,长尾长属正常。任务会持续重试到 5 分钟超时,再失败会保留 task 记录可重试
- 也可能是网络出口慢: 设置里调小 `pollingIntervalMs` 没用,得等

**Q3. ffmpeg 找不到?**
- Windows: 下载 [gyan.dev ffmpeg](https://www.gyan.dev/ffmpeg/builds/) 解压后把 `bin/` 加到 PATH
- macOS: `brew install ffmpeg`
- Linux: `sudo apt install ffmpeg` 或对应发行版包管理器
- 重启应用,顶部 banner 会变绿

**Q4. 余额不足 / 401 / 403?**
- 401: API Key 错,去设置重新填
- 403: 权限不足,通常 Key 被禁用,去 agnes 控制台检查
- "insufficient credit": 余额不足,去 agnes 控制台充值

**Q5. 应用启动后白屏?**
- 检查 devtools console(顶部菜单 → 视图 → 开发者工具)
- 如果是 Vite 端口被占:`npm run predev` 会清掉
- userData 数据库损坏: 应用启动时会自动备份到 `.corrupt-{timestamp}` 并重建,项目数据会丢

**Q6. 项目能备份/迁移吗?**
- 项目详情页右上角"⋮"菜单 → "导出项目" → 选目标文件夹
- 目标文件夹会生成 `.mrfoxwang-export/` 目录,包含 manifest.json + 所有产物
- 恢复: 首页 → "导入项目" → 选 `.mrfoxwang-export` 父目录

**Q7. 多窗口同步吗?**
- 多窗口共享同一 SQLite,所以分集/任务数据实时同步
- 流水线状态、API Key 变更通过 IPC 事件广播

**Q8. 视频很慢,能并行吗?**
- 可以,默认并发 2 个任务(LLM/Image/Video 各自独立并发限流)
- 设置里"流水线并发数"可调高(注意 agnes 服务端限流)

## 数据与隐私

- **你的数据全部在本机**: 数据库、产物、日志都在 userData 目录
- **AI 调用**才会上传到 agnes 服务端: LLM 走 chat/completions,Image/Video 走 agnes 自有协议
- **上传内容**: 仅你当前正在处理的章节/分镜/角色描述(对应每次 AI 调用的 prompt + 入参图片),不包含其他项目数据
- **API Key**: 见上,操作系统级加密;旧版明文存 DB 会自动迁移到加密并删除明文
- **日志**: 默认写 `userData/logs/app.log`,最多保留 7 天;含 API Key 调用的请求/响应大小(不含 Key 值)
- **崩溃数据**: 启动时会自动备份损坏的 DB 到 `.corrupt-{timestamp}`,不主动上报

## 第三方依赖与 License

| 组件 | License | 用途 |
|---|---|---|
| Electron | MIT | 桌面壳 |
| Vue 3 / Pinia / Vue Router | MIT | 渲染层 |
| better-sqlite3 | MIT | 本地 DB |
| sharp | Apache-2.0 | 图片处理 |
| agnes-ai SDK | (商用条款见 agnes-ai.com) | LLM / 文生图 / 图生视频 |
| edge-tts / edge-tts-node | MIT | TTS 配音 |
| **fluent-ffmpeg** | **GPL** | ffmpeg 包装(法律风险:闭源分发需注意 GPL 传染性) |
| ffmpeg | LGPL/GPL(根据编译选项) | 视频合成 |
| lucide-vue-next | ISC | 图标 |

本项目 **License: UNLICENSED / 私有**,未经授权不得二次分发。商业支持请联系 ManKa Studio (hi@manka.app)。

## 开发指南

### 环境

- Node.js ≥ 20.19(开发模式)
- npm ≥ 10

### 命令汇总

```bash
npm install              # 装依赖 + electron-builder 原生模块 rebuild
npm run dev              # 开发模式(自动重启 + Vite HMR)
npm run typecheck        # 主进程 tsc + 渲染层 vue-tsc
npm run build            # 三端打包到 out/ (main + preload + renderer)
npm run build:unpack     # 不打安装包,只 unpack(快速验证产物)
npm run build:win        # Windows NSIS 安装包(.exe)
npm run build:mac        # macOS dmg(必须在 Mac 上跑)
npm run build:linux      # Linux AppImage + deb
npm run lint             # ESLint
npm run format           # Prettier
```

### 项目结构

```
src/
├── main/                  # Electron 主进程(Node.js)
│   ├── index.ts           # 入口(whenReady → registerAllHandlers → createWindow)
│   ├── adapters/          # LLM/Image/Video 适配器
│   ├── database/          # better-sqlite3 + Kysely + migrations
│   ├── ipc/               # IPC handlers(按业务领域拆分)
│   ├── pipeline/          # 7 阶段流水线引擎
│   ├── prompts/           # 提示词模板(LLM 输入)
│   └── services/          # 业务服务(系统健康 / 存储 / 任务队列 / TTS)
├── preload/               # 预加载脚本(contextBridge 暴露 API)
├── renderer/              # Vue 3 渲染层
│   ├── src/
│   │   ├── components/    # 通用组件(AppHeader / FloatingRail / ConfirmDialog 等)
│   │   ├── composables/   # 组合式 useIpc / useIpcEvents
│   │   ├── stores/        # Pinia 状态
│   │   ├── views/         # 12 个页面
│   │   └── main.ts
└── shared/                # 主进程 + 渲染进程共享类型
    ├── types/             # 数据模型
    └── contract/          # IPC 通道名常量
```

### 调试技巧

- 渲染层 devtools: 应用内 `Ctrl+Shift+I` (Windows/Linux) / `Cmd+Opt+I` (macOS)
- 主进程日志: `userData/logs/app.log` + 启动时终端输出
- Vite HMR 异常: 重启 `npm run dev`
- DB 调试: 用 [DB Browser for SQLite](https://sqlitebrowser.org/) 打开 `mrfoxwang.db`

## 已知限制

- **macOS 安装包未签名**: 首次打开会触发 Gatekeeper 警告,需右键"打开"。生产环境建议配 Apple Developer ID + notarize。
- **Windows 安装包未签名**: SmartScreen 会拦截,需点"更多信息 → 仍要运行"。生产环境建议配 EV 代码签名证书。
- **占位图标**: `build/icon.png` 是临时品牌,商业交付前请替换为正式 `.icns` / `.ico`。
- **TTS 无 fallback**: edge-tts 不可用时 TTS 阶段会失败,目前无备用 TTS 引擎。
- **API Key 跨平台**: 同一台机器的同一 OS 用户下,Key 自动复用;换 OS / 换用户 / 换机器 需重新输入。
- **多语言**: 仅中文 UI,英文 UI 暂未排期。
- **大文件**: 单项目超过 100 GB 时 DB 会变慢(适合分多个项目)。

## 商业支持

- 邮件: hi@manka.app
- GitHub Issues: https://github.com/manka-studio/electron-app/issues
- 定制开发 / 私有部署 / 商业授权: 联系 ManKa Studio (hi@manka.app)