Skip to content
MixLabProPublic

About

AI时代的专业AVG视觉小说游戏制作工具

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

545 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AVG Maker - AI时代的文字互动游戏引擎

AVG版的 - 专为AI时代设计的低门槛文字互动游戏创作工具

基于AI Native的AVG文字游戏开发引擎,使用强大的Ink脚本语言,让普通人也能够轻松制作精彩的互动小说和AVG游戏,一键打包成STEAM游戏。

功能演示

🎯 产品定位

AVG Maker 是专为AI时代打造的文字互动游戏引擎,旨在降低游戏创作门槛,让每个人都能轻松创作出色的互动体验:

  • 🤖 AI友好设计:和AI边聊边写边玩的游戏开发模式
  • 📝 低门槛创作:直观的可视化界面,无需复杂编程知识
  • 🎮 专业级功能:支持复杂分支剧情、角色系统、存档机制
  • 🚀 现代化体验:类似Cursor的专业开发环境
  • 📱 跨平台发布:一键导出Web版本和桌面应用

✨ 核心特性

🎨 现代化AVG游戏创作体验

  • AI助理: 设计角色、构思剧本、调整结构、添加素材
  • 智能编辑器:专业级代码编辑体验,语法高亮、智能补全
  • 🆕 通用视觉模式:无需标签也能体验专业AVG游戏效果
  • 双模式预览:文本模式编辑,视觉模式体验,随时切换
  • 剧情蓝图:直观展示剧情分支和故事流程,编写更清晰
  • 🔍 智能文件搜索:基于FlexSearch的全文搜索引擎,毫秒级响应,支持40+文件类型
  • ⚡ Web Worker搜索:多线程搜索架构不阻塞UI,支持大型项目全文索引
  • 🎯 智能索引系统:自动识别文件类型,智能分词,增量更新,代码友好
  • 项目管理:完整的工程化项目结构
  • Ink脚本语言:强大的分支叙事脚本系统
  • 🤖 智能CLI终端:内置专业级命令行界面,支持函数式语法和MCP工具调用
  • ⚡ 模块化架构:29个CLI模块构成完整工具链,性能优化97%,启动时间从85秒降至2秒
  • MCP智能系统:内置Model Context Protocol支持,14个专业工具提供AI辅助开发能力
  • 插件系统:H5插件扩展,支持小游戏和交互组件

🚀 最新优化 (v0.1.3)

  • 🆕 通用视觉模式:纯文本故事也能立即体验AVG游戏效果
  • 🎮 专业游戏渲染:基于React组件化架构的高品质视觉体验
  • 🌐 浏览器预览模式:独立的Web预览环境,支持跨设备测试和分享
  • 📱 响应式适配:完美支持各种屏幕尺寸和方向切换
  • 🔄 实时模式切换:文本/视觉模式间无缝切换
  • ⚡ 零配置启动:无需准备资源文件即可使用视觉模式
  • 🎯 渐进式增强:支持从纯文本到复杂视觉小说的平滑过渡
  • 🤖 MCP智能系统:集成Model Context Protocol,为AI开发者提供标准化工具接口
  • 🔧 专业CLI终端:全新的命令行系统,支持智能补全、意图识别和工具调用
  • ⚡ 性能重构:CLI架构优化97%性能提升,代码量减少73%,模块化设计
  • 🔍 企业级搜索系统:FlexSearch + Web Worker架构,支持正则、上下文、文件过滤搜索
  • 📁 项目级搜索面板:VSCode风格的搜索界面,智能索引,TF-IDF相关性排序

🛡️ 可靠性保障

  • 崩溃恢复:自动备份工作状态,意外关闭后智能恢复
  • 版本管理:完整的Git集成支持
  • 自动保存:智能防丢失机制

📦 发布与分发

  • Web导出:一键生成可部署的网页版游戏
  • 桌面应用:Electron打包,支持Windows/macOS/Linux
  • 资源优化:自动压缩和优化游戏资源

🚀 快速开始

系统环境要求

  • Node.js ≥ 20.0.0 (推荐使用 LTS 版本)
  • npm ≥ 10.0.0 或 yarn ≥ 1.22.0
  • Git (用于克隆项目和子模块管理)
  • 支持的操作系统:Windows 10+, macOS 10.15+, Ubuntu 18.04+

开发者完整初始化流程

第一步:克隆项目和子模块

# 克隆主项目(包含子模块)
git clone --recursive https://github.com/MixLabPro/avg-maker.git

# 如果已经克隆但没有子模块,执行:
# git submodule update --init --recursive

cd avg-maker

第二步:验证环境

# 检查 Node.js 版本(需要 ≥ 20.0.0)
node --version

# 检查 npm 版本
npm --version

# 检查子模块是否正确加载
ls -la inkjs-fork/  # 应该看到 inkjs 源码文件

第三步:安装依赖

# 安装主项目依赖(约2-3分钟)
npm install

# 验证关键依赖是否正确安装
npm list electron
npm list vite
npm list typescript

第四步:首次构建验证

# 编译 TypeScript 代码(electron/ 和 server/ 目录)
npm run predev

# 构建预览客户端模块
npm run build:preview-client

# 验证构建产物
ls -la dist/electron/    # 应该看到 main.js, preload.js
ls -la server/public/    # 应该看到编译后的预览客户端文件

第五步:启动开发环境

# 启动完整开发环境
npm run dev

# 等待启动完成,应该看到:
# ✅ Converted preload.js to CommonJS format
# ✅ Vite dev server started on http://localhost:5173
# ✅ Electron app launched successfully

🔍 初始化验证清单

开发环境启动后,请验证以下功能:

  • Electron 应用启动:桌面应用正常打开
  • 欢迎页面显示:看到 VSCode 风格的欢迎界面
  • 项目创建功能:能够创建新的 AVG 项目
  • 编辑器加载:Monaco 编辑器正常显示语法高亮
  • 实时预览:右侧预览面板显示游戏内容
  • 浏览器预览:标题栏预览器能打开 http://localhost:3001
  • 文件监控:修改 .ink 文件后预览自动更新
  • 全文搜索功能:能够快速搜索项目中的文本内容
  • 搜索面板:侧边栏搜索面板正常显示和工作

🛠️ 常见初始化问题解决

Node.js 版本过低

# 使用 nvm 安装最新 LTS 版本
nvm install --lts
nvm use --lts

子模块没有正确加载

# 重新初始化子模块
git submodule deinit -f .
git submodule update --init --recursive

端口冲突问题

# 检查端口占用
netstat -an | grep :5173
netstat -an | grep :3001

# 如有冲突,可在 vite.config.ts 中修改端口配置

TypeScript 编译错误

# 清理并重新编译
rm -rf dist/
npm run predev

Electron 启动失败

# 检查 preload 脚本转换
cat dist/electron/preload.js  # 应该是 CommonJS 格式

# 重新转换 preload 脚本
node scripts/fix-preload-for-packaging.cjs

创建你的第一个游戏

  1. 启动应用:运行 npm run dev
  2. 创建项目:点击欢迎页面的"创建新项目"
  3. 开始创作:在编辑器中编写你的故事
  4. 实时预览:右侧面板实时显示游戏效果
  5. 发布游戏:完成后一键导出分发

📁 项目结构

基于最新的依赖分析和代码优化,项目采用了精简的模块化架构:

avg-maker/
├── 🔧 核心引擎
│   ├── inkjs-fork/             # 内置Ink编译器
│   ├── electron/               # Electron主进程
│   │   ├── main.ts             # 主进程入口
│   │   ├── preload.ts          # 预加载脚本
│   │   └── mcp/                # MCP智能系统 🤖
│   │       ├── server.js       # MCP服务器核心
│   │       ├── transport.js    # SSE传输层
│   │       ├── tools/          # 9个核心工具集
│   │       ├── schemas/        # 工具参数规范
│   │       └── docs/           # 完整开发文档
│   └── server/                 # 预览服务器模块
│       ├── previewServer.js    # 预览服务器
│       ├── assetResolver.js    # 资源解析
│       └── utils.js            # 工具函数
├── 🎮 游戏内容
│   ├── story/                  # 示例游戏项目
│   ├── plugins/                # H5插件扩展
│   └── public/                 # 静态资源
├── 💻 前端应用 (精简核心)
│   ├── src/
│   │   ├── App.tsx             # 主应用入口
│   │   ├── main.tsx            # React入口
│   │   ├── components/         # 核心UI组件 (45个活跃文件)
│   │   │   ├── WelcomeScreen.tsx      # 欢迎页面
│   │   │   ├── Editor.tsx             # 代码编辑器
│   │   │   ├── PreviewNew.tsx         # 游戏预览器
│   │   │   ├── TitleBar.tsx           # 标题栏
│   │   │   ├── ProjectExplorer.tsx    # 项目浏览器
│   │   │   ├── ai/AIChatPanel.tsx     # AI助手面板
│   │   │   └── preview/               # 预览组件模块
│   │   │       ├── CompilePreviewer.tsx    # 编译预览器
│   │   │       ├── HistoryPanel.tsx        # 历史面板
│   │   │       ├── NodeGraph.tsx           # 节点图
│   │   │       └── visual-react/           # 视觉模式组件
│   │   ├── context/            # 状态管理 (4个活跃文件)
│   │   │   ├── ProjectContext.tsx  # 项目状态
│   │   │   ├── SaveContext.tsx     # 保存状态
│   │   │   └── ThemeContext.tsx    # 主题状态
│   │   ├── utils/              # 核心工具函数 (21个活跃文件)
│   │   │   ├── AppStartupManager.ts     # 启动管理
│   │   │   ├── crashRecovery.ts         # 崩溃恢复
│   │   │   ├── testingUtils.ts          # 调试工具
│   │   │   ├── imagePathResolver.ts     # 图片路径解析
│   │   │   ├── audioPathResolver.ts     # 音频路径解析
│   │   │   └── inkLanguage.ts           # Ink语言支持
│   │   ├── hooks/              # React Hooks (6个活跃文件)
│   │   │   ├── useWorkspaceState.ts     # 工作区状态
│   │   │   ├── useInkStory.ts           # Ink故事Hook
│   │   │   └── useCompilePreviewer.ts   # 编译预览Hook
│   │   ├── api/                # 平台适配层 (5个活跃文件)
│   │   │   ├── index.ts        # 统一API入口
│   │   │   ├── platform.ts     # 平台检测
│   │   │   └── factory.ts      # 适配器工厂
│   │   └── types/              # 类型定义 (2个活跃文件)
│   │       ├── sidebar.ts      # 侧边栏类型
│   │       └── preview.ts      # 预览类型
└── 📋 配置文件
    ├── package.json            # 项目配置
    ├── vite.config.ts          # Vite构建配置
    ├── forge.config.js         # Electron打包配置
    ├── CLAUDE.md               # AI开发指南
    └── DEPENDENCY_ANALYSIS_FINAL_REPORT.md  # 依赖分析报告 🆕

🧹 项目优化说明

经过深度依赖分析,项目已移除了600+个未使用文件(86.3%),保留95个核心活跃文件:

  • 组件层: 45个核心UI组件,包含完整的编辑器、预览器和项目管理功能
  • 业务逻辑: 21个工具函数,覆盖启动管理、崩溃恢复、资源处理等核心功能
  • 状态管理: 4个Context提供者 + 6个专用Hooks,确保状态管理的清晰性
  • 平台适配: 5个API适配器,支持浏览器和Electron环境

🎯 使用指南

基础创作流程

  1. 项目管理

    • 创建新项目或打开现有项目
    • 支持多文件工程管理
    • 自动保存和版本控制
  2. 脚本编写

    • 使用Ink语言编写互动剧情
    • 实时语法检查和错误提示
    • 智能代码补全和语法高亮
  3. 预览测试

    • 实时预览游戏效果
    • 可视化节点图查看剧情流程
    • 支持断点调试和变量跟踪
    • 浏览器预览:独立Web环境测试和分享

项目资源管理器

项目侧边栏提供类似VS Code的资源管理体验:

  • 文件操作:创建、重命名、删除与拖拽移动文件
  • Knot树:自动解析每个.ink文件中的Knot并展示
  • 变量面板:汇总项目中的VAR/LIST声明,方便统一管理
  • 🔍 全文搜索:FlexSearch引擎驱动的项目级搜索,支持正则表达式和文件过滤
  • 🎯 智能索引:自动识别文件类型,实时增量更新,代码友好分词
  • 一键编译:可从侧边栏触发全项目编译并查看输出
  1. 插件扩展

    • 开发H5插件增强游戏体验
    • 支持小游戏、动画、音效等
    • 通过简单API集成到主游戏中
  2. 发布分发

    • Web版:生成可直接部署的网页
    • 桌面版:打包为exe/app/deb安装包
    • 自动优化资源和性能

高级功能

🌐 浏览器预览功能

功能特色

  • 独立Web环境:在浏览器中独立运行游戏,无需Electron客户端
  • 跨设备测试:支持手机、平板、不同浏览器的兼容性测试
  • 实时更新:编辑器修改后自动刷新浏览器预览
  • 分享便捷:可生成预览链接分享给他人测试

使用方式

  1. 启动预览:在标题栏的"编译预览器"中选择"浏览器预览"
  2. 选择入口文件:从下拉菜单选择要预览的.ink文件
  3. 点击预览:点击播放按钮启动浏览器预览窗口
  4. 访问链接:浏览器自动打开 http://localhost:3001 显示游戏

技术实现

  • 动态路径解析:自动注入当前项目路径,支持图片、音频等资源加载
  • 智能环境检测:自动识别浏览器环境,使用服务器端资源路径
  • 热重载机制:文件修改后自动刷新页面内容
  • 错误处理:友好的错误提示和调试信息

适用场景

  • 📱 移动端适配:测试在手机、平板上的显示效果
  • 🌐 浏览器兼容:验证在不同浏览器中的运行情况
  • 👥 团队协作:分享预览链接给团队成员测试
  • 📊 性能测试:在真实Web环境中测试加载速度和性能

🤖 MCP智能系统(Model Context Protocol)

系统概览

AVG Maker 内置了完整的 MCP (Model Context Protocol) 系统,专为 AI 辅助开发设计,提供标准化的工具接口和通信协议,让 AI 助手能够深度参与AVG游戏的开发过程。

核心特性

  • 🔧 模块化架构:清晰的层次结构和组件分离,便于扩展和维护
  • 🎯 14个核心工具:覆盖节点操作、内容管理、结构管理、游戏控制
  • 📡 标准化接口:基于 MCP 协议的统一通信,确保与各类AI客户端兼容
  • ⚡ 高性能设计:异步处理、智能缓存、实时性能监控
  • 🛡️ 安全可靠:完善的输入验证、权限控制、错误处理机制

工具系统分类

🎮 节点操作类工具

  • NodeBasicOperationsTool:节点基础操作(进入、导航、选择执行)
  • NodeTreeTool:节点树结构管理和可视化
  • NodeSearchTool:强大的节点搜索功能(语义搜索、关键词匹配)

📝 内容管理类工具

  • NodeContentTool:节点内容管理(获取、更新、解析)
  • NodeEditingTool:专业的节点编辑操作(格式验证、版本控制)

🏗️ 结构管理类工具

  • NodeCreationTool:节点创建(支持模板和批量操作)
  • NodeDeletionTool:安全的节点删除(依赖检查、自动备份)
  • NodeConnectionTool:节点连接关系管理

🎛️ 游戏控制类工具

  • GameControlTool:游戏状态控制(重置、前进后退、历史导航)

技术实现

  • SSE传输层:基于Server-Sent Events的实时通信
  • Express服务器:运行在端口3002,提供RESTful API接口
  • 健康监控:提供 /health 和 /debug/sessions 端点进行系统监控
  • 会话管理:支持多客户端并发连接,自动清理过期会话

AI开发者接入

MCP服务器在开发模式下自动启动,AI开发者可以通过以下方式接入:

# MCP服务器地址
SSE端点: http://localhost:3002/mcp
消息端点: http://localhost:3002/messages
健康检查: http://localhost:3002/health
调试信息: http://localhost:3002/debug/sessions

使用场景

  • 🎨 智能创作:AI根据剧情需求自动创建和连接节点
  • 🔍 内容分析:AI分析故事结构,提供优化建议
  • 🎮 自动测试:AI自动遍历游戏分支,发现潜在问题
  • 📊 数据统计:AI收集游戏数据,生成详细的分析报告

开发者文档

  • 详细的工具使用指南:electron/mcp/docs/USAGE.md
  • 系统架构说明:electron/mcp/docs/ARCHITECTURE.md
  • 开发指南:electron/mcp/docs/DEVELOPMENT.md

🛡️ 崩溃恢复系统

  • 自动检测意外关闭
  • 智能恢复工作状态
  • 保护创作成果不丢失

🎨 欢迎页面

  • 类似VSCode的专业体验
  • 快速访问最近项目
  • 便捷的项目创建和管理

📊 开发者工具

  • 内置调试控制台
  • 性能监控和分析
  • 丰富的测试命令

🔧 开发与调试

常用命令

# 开发模式 (Vite + Ink监控 + Electron + 预览服务器)
npm run dev

# 构建Web版本 (静态文件到 dist/)
npm run build:web

# 【推荐】打包桌面应用 (Electron Builder,78MB体积优化版)
npm run pack

# 【已废弃】旧版打包 (Electron Forge,体积2.56GB,不推荐)
npm run make

# 代码检查和格式化
npm run lint

# TypeScript编译 (编译 electron/ 和 server/ 目录)
npm run predev

# 构建预览客户端模块
npm run build:preview-client

📦 应用打包指南

桌面应用打包

Windows/macOS打包

AVG Maker 现已采用 Electron Builder 打包方案,实现了97%的体积优化(从2.56GB降至78MB),并确保所有功能在打包环境中正常工作。

🚀 快速打包
# Windows打包(在Windows上运行)
npm run pack

# macOS打包(需要在macOS或GitHub Actions运行)
npm run pack:macos

📋 自动化流程说明

npm run pack 会自动执行以下步骤:

  1. 编译 TypeScript (tsc -p tsconfig.node.json) - 生成 Electron 主进程文件
  2. 构建预览客户端 (npm run build:preview-client) - 生成浏览器预览模块
  3. 转换资源文件 (node scripts/build-cjs-assets.cjs) - 处理导出相关资源
  4. 修复preload脚本 (node scripts/fix-preload-for-packaging.cjs) - CommonJS格式转换
  5. Electron Builder打包 - 生成最终的桌面应用

📁 打包产物

打包完成后,在 dist-packaged/ 目录下会生成以下文件:

dist-packaged/
├── win-unpacked/                  # 📁 可执行程序目录(便携版)
│   ├── AVG Maker.exe             # 🎯 主程序 (约78MB,97%体积优化)
│   ├── resources/                # 📦 应用资源
│   │   ├── app.asar             # 压缩的应用包
│   │   └── app.asar.unpacked/   # 运行时依赖
│   └── ...                      # Electron运行时文件
└── AVG Maker 0.1.0.exe          # 📦 便携安装包

🎯 使用方式

方式一:直接运行(推荐)

# 直接运行可执行文件
./dist-packaged/win-unpacked/AVG Maker.exe

方式二:便携安装包

  • 便携版: 运行 AVG Maker 0.1.0.exe 自解压到指定位置

⚙️ 打包配置

打包行为由 electron-builder.json 控制:

{
  "appId": "com.avgmaker.app",
  "productName": "AVG Maker",
  "directories": {
    "output": "out-builder-final"
  },
  "files": [
    "dist/**/*",
    "server/**/*", 
    "inkjs-fork/dist/**/*",
    "templates/**/*"
  ],
  "extraFiles": [
    // 包含所有运行时依赖(28+个包)
    {"from": "node_modules/chokidar", "to": "node_modules/chokidar"},
    {"from": "node_modules/fs-extra", "to": "node_modules/fs-extra"}
    // ... 完整依赖列表
  ],
  "asar": true,
  "asarUnpack": [
    "server/public/**/*",
    "inkjs-fork/dist/**/*",
    "node_modules/chokidar/**/*",
    "node_modules/fs-extra/**/*"
  ]
}

🔧 自定义打包

修改应用信息

// 在 electron-builder.json 中修改
{
  "productName": "你的应用名",
  "appId": "com.yourapp.id", 
  "copyright": "Copyright © 2024 你的公司名"
}

指定打包平台

# 仅打包Windows版本
npm run pack -- --win

# Linux打包(见下方Linux打包章节)
npm run pack:linux

🚨 常见问题解决

问题1: 打包体积过大

# 现象:打包文件超过1GB
# 解决方案:已通过Electron Builder优化至78MB
# 优化内容:
# - 精确的dependency映射(28个运行时包)
# - ASAR压缩和选择性解包
# - 移除开发依赖和测试文件

问题2: 应用无法启动

# 解决方案:检查preload脚本格式
node scripts/fix-preload-for-packaging.cjs
# 确保转换为CommonJS格式

问题3: 浏览器预览功能失效

# 现象:预览按钮无响应
# 解决方案:已修复路径解析问题
# 修复内容:
# - 支持ASAR包中的manifest文件加载
# - 动态资源路径解析
# - 预览服务器ASAR环境适配

问题4: 桌面游戏导出失败

# 现象:导出时提示"ENOTDIR, not a directory"  
# 解决方案:已修复依赖缓存路径问题
# 修复内容:
# - 检测ASAR环境自动切换缓存目录
# - 使用用户主目录避免只读文件系统
# - 改进项目根目录检测逻辑

问题5: 缺少依赖模块

# 现象:运行时报错找不到模块
# 解决方案:检查electron-builder.json中的extraFiles
# 确保所有运行时依赖都被正确包含

📊 性能优化建议

  1. 减小包体积

    # 清理开发依赖
    npm prune --production
    
    # 使用ASAR压缩
    asar: true  // 在forge.config.js中启用
  2. 提升启动速度

    • 启用V8快照
    • 减少主进程初始化代码
    • 使用预加载脚本优化
  3. 内存优化

    • 限制渲染进程内存使用
    • 及时清理未使用的资源

🔐 代码签名(可选)

对于生产环境发布,建议添加代码签名:

// forge.config.js 添加签名配置
packagerConfig: {
  osxSign: {
    identity: 'Developer ID Application: Your Name'
  },
  osxNotarize: {
    appleId: 'your-apple-id',
    appleIdPassword: 'your-app-password'
  }
}

🎯 部署建议

内部使用

  • 使用ZIP版本,简单解压即用
  • 可放置在共享网络位置

对外分发

  • 使用Squirrel安装包,提供标准安装体验
  • 配置自动更新机制

企业部署

  • 配置代码签名证书
  • 使用企业级分发工具

Linux打包

🐧 使用Docker在Windows上打包Linux版本

AVG Maker支持在Windows环境使用Docker打包Linux版本,生成AppImage、DEB、TAR.GZ三种格式。

前置要求

  • Docker Desktop for Windows
  • 至少4GB可用内存
  • 10GB可用磁盘空间

打包命令

# 一键打包Linux版本(生成AppImage、DEB、TAR.GZ)
npm run build:linux:docker

# 或直接运行脚本
bash scripts/build-linux-docker.sh

打包产物

dist-packaged/
├── AVGMaker-0.1.0-x86_64.AppImage    # 便携版(推荐)
├── avg-maker_0.1.0_amd64.deb         # Debian/Ubuntu安装包
├── avg-maker-0.1.0.tar.gz            # 通用压缩包
└── linux-unpacked/                   # 解压后的文件
🧪 Linux版本测试

使用VirtualBox虚拟机测试(推荐)

  1. 安装VirtualBox
  2. 创建Ubuntu 20.04/22.04虚拟机
  3. 将打包文件复制到虚拟机
  4. 运行安装脚本:bash scripts/install-ubuntu.sh

Ubuntu快速运行

# 方式1:AppImage(最简单)
chmod +x AVGMaker-0.1.0-x86_64.AppImage
./AVGMaker-0.1.0-x86_64.AppImage

# 方式2:DEB包安装
sudo dpkg -i avg-maker_0.1.0_amd64.deb

# 方式3:解压运行
tar -xzf avg-maker-0.1.0.tar.gz
cd avg-maker-0.1.0
./avg-maker

系统要求

  • Ubuntu 18.04+ (64位)
  • 2GB RAM (推荐4GB+)
  • GUI依赖:libgtk-3-0 libnss3 libxss1 libasound2 fuse

常见问题

  • CRLF换行符问题:运行 bash scripts/fix-line-endings.sh 修复
  • AppImage无法运行:安装FUSE sudo apt install fuse
  • 库版本不兼容:使用提取模式 ./AppImage --appimage-extract

开发环境说明

开发模式架构 (npm run dev):

  1. 预构建阶段 (npm run predev)
    • TypeScript 编译:electron/ → dist/electron/
    • TypeScript 编译:server/ → dist/server/
    • ES模块转换:将 preload.js 转为 CommonJS 格式
  2. 并发启动:
    • Vite 开发服务器:运行在 http://localhost:5173,提供热重载
    • Electron 应用:等待 Vite 启动后加载开发服务器
  3. 后台服务:
    • 预览服务器:内置 HTTP 服务器(端口 3001),提供浏览器预览
    • MCP智能服务器:运行在端口 3002,提供 AI 开发者工具接口
    • 文件监控:自动检测 .ink 文件变化并重新编译

关键构建步骤详解:

  • preload.js 处理:使用 scripts/fix-preload-for-packaging.cjs 将 ES 模块转为 CommonJS
  • MCP系统构建:使用 scripts/copy-mcp.cjs 转换 ES 模块为 CommonJS,确保 Electron 兼容
  • 预览客户端构建:使用专用配置 vite.config.preview-client.js
  • 静态资源管理:基于 manifest 的版本化资源系统
  • 跨环境适配:同时支持 Electron 和浏览器环境

构建产物说明:

  • dist/electron/: Electron 主进程和预加载脚本
  • dist/electron/mcp/: MCP系统的 CommonJS 构建产物
  • dist/: Web 版本的前端构建产物
  • server/public/: 预览客户端的独立构建产物
  • story/*.json: 编译后的 Ink 脚本文件

🔧 开发调试指南

开发者控制台命令

// 检查应用启动状态
await window.__DEV_TESTING__.startup.checkStartupMode()
await window.__DEV_TESTING__.startup.getStartupInfo()

// 启动模式测试
window.__DEV_TESTING__.startup.simulateFirstTimeUser()
window.__DEV_TESTING__.startup.simulateCrashRecovery()

// 崩溃恢复系统测试
window.__DEV_TESTING__.crashRecovery.simulateCrash()
window.__DEV_TESTING__.crashRecovery.showRecoveryData()

// 数据清理和重置
window.__DEV_TESTING__.recovery.clearAllRecoveryData()
window.__DEV_TESTING__.startup.forceCleanAndReload()

// 存储系统检查
window.__DEV_TESTING__.recovery.showAllStorageData()

常见开发问题诊断

1. 编译预览无响应
# 检查预览服务器状态
curl http://localhost:3001/api/refresh-time

# 检查 Ink 文件编译
npm run watch:ink  # 单独运行 Ink 编译器

# 查看详细编译日志
DEBUG=avg-maker:* npm run dev
2. 静态资源 404 错误
# 检查 manifest 文件
cat server/public/preview-manifest.json

# 重新构建预览客户端
npm run build:preview-client

# 检查资源文件哈希
ls -la server/public/preview-client.*
3. TypeScript 类型错误
# 检查 TypeScript 配置
npx tsc --noEmit  # 仅类型检查,不生成文件

# 检查各模块的 TypeScript 配置
npx tsc -p tsconfig.node.json --noEmit
npx tsc -p server/preview-client/tsconfig.json --noEmit
4. Electron 窗口无法加载
# 检查预加载脚本格式
grep -n "require\|import" dist/electron/preload.js

# 手动修复预加载脚本
node scripts/fix-preload-for-packaging.cjs

# 检查主进程日志
DEBUG=electron:* npm run electron:dev

性能监控

// 应用性能分析
console.time('startup')
// ... 应用启动过程
console.timeEnd('startup')

// 内存使用监控
console.log('内存使用:', process.memoryUsage())

// 渲染性能分析
performance.mark('render-start')
// ... 渲染过程
performance.mark('render-end')
performance.measure('render-time', 'render-start', 'render-end')

架构设计

🏗️ 整体架构

  • 单一职责原则:清晰的模块分离和组件化设计
  • 状态管理:统一的应用状态管理,支持崩溃恢复
  • 错误恢复:完善的容错机制和自动备份
  • 扩展性:插件化架构设计,支持H5插件扩展

🌐 预览服务器架构 (新)

项目现在采用模块化的预览服务器架构:

  • server/previewServer.ts:核心预览服务器类

    • 提供HTTP服务,支持实时预览
    • 自动编译Ink脚本并生成HTML
    • 支持热刷新和错误处理
    • 可配置端口和编译器路径
  • server/utils.ts:HTML生成工具模块

    • 生成完整的预览页面HTML
    • 支持富文本内容和安全的HTML标签解析
    • 提供现代化的游戏界面样式
    • 集成inkjs运行时和自动刷新机制
  • 服务器特性:

    • ✅ TypeScript支持,类型安全
    • ✅ 模块化设计,易于维护和测试
    • ✅ 支持CORS,便于跨域访问
    • ✅ 自动编译Ink文件,包含依赖文件
    • ✅ 实时刷新检测,无需手动刷新页面
    • ✅ 错误处理和用户友好的错误提示

🔧 服务器模块开发指南

PreviewServer 类使用:

import { PreviewServer } from '../server/previewServer.js';

// 创建服务器实例
const server = new PreviewServer({
  port: 3001,                    // 服务端口
  // 现在使用内置的 inkjs-compiler,不再需要外部二进制文件
  onError: (error) => {          // 错误回调
    console.error('Server error:', error);
  },
  onStart: () => {               // 启动回调
    console.log('Server started successfully');
  }
});

// 启动服务器
await server.start();

// 设置当前预览文件
server.setCurrentFile('./story/main.ink');

// 触发页面刷新
server.triggerRefresh();

// 获取刷新时间戳
const refreshTime = server.getRefreshTime();

// 停止服务器
server.stop();

可用的HTTP端点:

  • GET /preview 或 GET / - 获取预览页面HTML
  • GET /api/refresh-time - 获取最后刷新时间戳(用于自动刷新检测)

HTML生成工具:

import { generatePreviewHTML } from '../server/utils.js';

// 生成预览HTML页面
const html = generatePreviewHTML(
  storyJsonData,      // 编译后的Ink JSON数据
  'story.ink',        // 文件名
  null,               // 错误消息(可选)
  Date.now()          // 刷新时间戳
);

🎮 Ink脚本语言

Ink是专为互动小说设计的强大脚本语言:

# 你的第一个互动故事
-> start

== start ==
你站在一个神秘的十字路口。
* [向左走] -> left_path
* [向右走] -> right_path
* [直接前进] -> forward_path

== left_path ==
你选择了左边的小径...
-> DONE

== right_path ==
右边传来奇怪的声音...
-> DONE

== forward_path ==
你勇敢地向前走去...
-> DONE

高级特性

  • 变量系统:支持数值、字符串、布尔值
  • 条件逻辑:复杂的分支判断
  • 函数系统:可重用的脚本片段
  • 存档机制:玩家进度保存
  • 多媒体:图片、音效、动画支持

🚀 案例展示

成功案例

  • 互动小说:文字冒险游戏
  • 教育游戏:互动学习体验
  • 营销游戏:品牌互动体验
  • 艺术项目:数字叙事作品

社区作品

查看我们的案例库了解更多精彩作品。

🤝 参与贡献

我们欢迎社区的每一份贡献:

开发规范与最佳实践

📋 项目依赖管理

# 添加新依赖时的注意事项
npm install <package>              # 生产依赖
npm install --save-dev <package>   # 开发依赖

# 关键依赖说明
# - inkjs: file:./inkjs-fork       # 使用本地 fork 版本
# - electron: 桌面应用框架         # 需要与 Node.js 版本兼容
# - vite: 现代构建工具             # 负责前端打包和开发服务器
# - typescript: 类型检查           # 严格模式,确保类型安全

🎯 代码质量标准

  • TypeScript 严格模式:所有新代码必须通过类型检查
  • ES 模块规范:项目使用 ES 模块,注意 import/export 语法
  • 单一职责原则:遵循 SRP,每个模块职责明确
  • 错误处理:完善的异常处理和用户友好的错误提示
  • 代码注释:关键逻辑添加清晰的中英文注释

🔍 代码检查与格式化

# 运行代码检查
npm run lint

# 手动格式化(如果配置了 prettier)
npx prettier --write "src/**/*.{ts,tsx,js,jsx}"

# TypeScript 类型检查(不生成文件)
npx tsc --noEmit

🧪 测试策略

// 开发环境测试工具(内置)
window.__DEV_TESTING__  // 启动模式、崩溃恢复、存储检查

// 手动功能测试清单
// 1. 创建新项目 → 编辑 → 预览 → 保存
// 2. 浏览器预览功能测试
// 3. 崩溃恢复机制测试
// 4. 多文件项目管理测试
// 5. 插件系统测试(如果使用)

📁 文件组织原则

推荐的开发文件结构:
├── 🔧 核心代码(不可删除)
│   ├── src/components/          # React 组件
│   ├── src/utils/               # 工具函数(精简后的21个文件)
│   ├── src/context/             # 状态管理
│   └── electron/                # Electron 主进程
├── 📝 配置文件
│   ├── package.json             # 依赖管理
│   ├── vite.config.ts           # 前端构建
│   ├── tsconfig.*.json          # TypeScript 配置
│   └── CLAUDE.md                # AI 开发指南
├── 🎮 游戏内容
│   ├── story/                   # 示例项目
│   ├── plugins/                 # H5 插件
│   └── public/                  # 静态资源
└── 📋 文档
    └── docs/                    # 技术文档

🚀 性能优化建议

  • 懒加载组件:大型组件使用 React.lazy()
  • 代码分割:避免单个 bundle 过大
  • 资源优化:图片压缩,音频格式优化
  • 内存管理:及时清理事件监听器和定时器
  • 构建优化:利用 Vite 的现代化构建能力

📞 技术支持

  • 技术文档:./docs/ - 完整的技术文档和开发指南
  • 问题反馈:GitHub Issues - 报告问题和功能建议

📚 使用指南

🚀 快速入门

📖 详细文档

🤝 社区交流

  • GitHub Discussions:参与讨论 - 功能建议和技术交流
  • 开发者文档:docs/README.md - 按角色分类的完整文档导航

📄 许可证协议

本项目采用双重许可证模式:

🆓 非商用免费

  • ✅ 个人学习和爱好项目
  • ✅ 教育和学术研究使用
  • ✅ 开源项目和非营利组织
  • ✅ 非商业性游戏创作

💼 商用付费

  • 💰 Indie开发者 - $99/年(年收入<$100K)
  • 💰 专业开发者 - $299/年(年收入<$1M)
  • 💰 企业授权 - $999/年(无限制)

📧 商业授权咨询:license@avgmaster.com

详细条款请查看 LICENSE 文件。


🧹 架构优化成果 (v1.1)

基于深度依赖分析,AVG Maker 在保持功能完整性的同时实现了大幅精简:

📊 优化数据

  • 文件精简: 695 → 95 个文件 (86.3%减少)
  • 核心覆盖: 仅13.7%的代码支撑100%功能
  • 依赖清理: 移除Web客户端、共享代码等未使用模块
  • 架构清晰: App.tsx仅依赖20个核心文件

🎯 优化收益

  • 启动速度: 减少文件加载,提升应用启动速度
  • 维护性: 清晰的依赖关系,降低维护复杂度
  • 开发效率: 精简的代码结构,便于新功能开发
  • 构建优化: 更小的打包体积,更快的构建速度

📋 架构优化详情

经过深度代码分析和架构重构,AVG Maker实现了显著的性能提升和代码质量改进。详细的优化报告和技术文档可在 docs/ 目录中查看。


🤖 AI 对话模块

  • 左侧 ActivityBar 新增 Bot 选项,点击后在侧边栏打开 AI 聊天面板
  • 面板顶部可填写自定义 API 地址,发送消息时将以 { message, context } POST 请求
  • 未填写时默认回显输入内容,可用于离线体验

🌟 核心技术栈

  • 前端框架:React 19 + TypeScript (精简架构,95个核心文件)
  • 样式系统:Tailwind CSS 4
  • 编辑器:Monaco Editor (语法高亮 + 智能补全)
  • 桌面框架:Electron (跨平台桌面应用)
  • 构建工具:Vite (快速开发构建)
  • 脚本语言:Ink + inkjs (专业互动叙事)
  • 状态管理:React Context + Custom Hooks (轻量级状态管理)
  • 服务器架构:Node.js 模块化预览服务器
  • 视觉渲染:React组件化视觉引擎 (支持角色立绘、背景、对话框)
  • CLI系统:TypeScript模块化架构 (29个核心模块,意图识别 + 工具调用)
  • 搜索引擎:FlexSearch + Web Worker (毫秒级全文搜索,40+文件类型,智能分词)
  • MCP协议:Model Context Protocol标准实现 (14个专业工具)
  • 开发工具:ESLint + Prettier + 完整TypeScript支持
  • 代码质量:基于依赖分析的精简架构,13.7%核心代码覆盖率

📈 路线图

v0.1.3 (当前版本) - 文档重构和CLI增强版

  • ✅ 核心编辑和预览功能 (Monaco Editor + 实时预览)
  • ✅ 智能崩溃恢复系统 (自动备份 + 状态恢复)
  • ✅ 专业欢迎页面体验 (VSCode风格)
  • ✅ 完整项目管理系统 (文件树 + Knot管理 + 变量面板)
  • ✅ 🆕 React组件化视觉渲染 (角色立绘 + 背景 + 对话框)
  • ✅ 🆕 智能图片匹配系统 (基于标签的资源自动匹配)
  • ✅ 🆕 响应式视觉适配 (支持各种屏幕尺寸)
  • ✅ 🆕 代码架构大幅优化 (600+冗余文件清理,保留95个核心文件)
  • ✅ 🆕 专业CLI终端系统 (29个模块,性能优化97%,启动时间2秒)
  • ✅ 🆕 完整MCP工具生态 (14个专业工具,标准化AI接口)
  • ✅ 🆕 FlexSearch全文搜索系统 (Web Worker架构,毫秒级响应,智能索引)
  • ✅ 🆕 项目级搜索面板 (支持正则、文件过滤、上下文显示、相关性排序)
  • ✅ AI聊天面板集成 (支持自定义API)

v0.1.4 (计划中)

  • 🔄 AI辅助创作功能
  • 🔄 云端同步支持
  • 🔄 模板库系统
  • 🔄 协作编辑功能
  • 🔄 高级视觉效果和动画

v0.2.0 (远期规划)

  • 📋 可视化剧情编辑器
  • 📋 角色管理系统
  • 📋 资源管理器
  • 📋 发布平台集成

让创作变得简单,让故事触动人心
AVG Maker - 每个人都是游戏创作者

⭐ 如果这个项目对你有帮助,请给我们一个Star!

© 2025 AVG Maker Team. Made with ❤️ for storytellers worldwide.

About

AI时代的专业AVG视觉小说游戏制作工具

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages