AVG版的 - 专为AI时代设计的低门槛文字互动游戏创作工具
基于AI Native的AVG文字游戏开发引擎,使用强大的Ink脚本语言,让普通人也能够轻松制作精彩的互动小说和AVG游戏,一键打包成STEAM游戏。
AVG Maker 是专为AI时代打造的文字互动游戏引擎,旨在降低游戏创作门槛,让每个人都能轻松创作出色的互动体验:
- 🤖 AI友好设计:和AI边聊边写边玩的游戏开发模式
- 📝 低门槛创作:直观的可视化界面,无需复杂编程知识
- 🎮 专业级功能:支持复杂分支剧情、角色系统、存档机制
- 🚀 现代化体验:类似Cursor的专业开发环境
- 📱 跨平台发布:一键导出Web版本和桌面应用
- AI助理: 设计角色、构思剧本、调整结构、添加素材
- 智能编辑器:专业级代码编辑体验,语法高亮、智能补全
- 🆕 通用视觉模式:无需标签也能体验专业AVG游戏效果
- 双模式预览:文本模式编辑,视觉模式体验,随时切换
- 剧情蓝图:直观展示剧情分支和故事流程,编写更清晰
- 🔍 智能文件搜索:基于FlexSearch的全文搜索引擎,毫秒级响应,支持40+文件类型
- ⚡ Web Worker搜索:多线程搜索架构不阻塞UI,支持大型项目全文索引
- 🎯 智能索引系统:自动识别文件类型,智能分词,增量更新,代码友好
- 项目管理:完整的工程化项目结构
- Ink脚本语言:强大的分支叙事脚本系统
- 🤖 智能CLI终端:内置专业级命令行界面,支持函数式语法和MCP工具调用
- ⚡ 模块化架构:29个CLI模块构成完整工具链,性能优化97%,启动时间从85秒降至2秒
- MCP智能系统:内置Model Context Protocol支持,14个专业工具提供AI辅助开发能力
- 插件系统:H5插件扩展,支持小游戏和交互组件
- 🆕 通用视觉模式:纯文本故事也能立即体验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 文件后预览自动更新
- 全文搜索功能:能够快速搜索项目中的文本内容
- 搜索面板:侧边栏搜索面板正常显示和工作
# 使用 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 中修改端口配置# 清理并重新编译
rm -rf dist/
npm run predev# 检查 preload 脚本转换
cat dist/electron/preload.js # 应该是 CommonJS 格式
# 重新转换 preload 脚本
node scripts/fix-preload-for-packaging.cjs- 启动应用:运行
npm run dev - 创建项目:点击欢迎页面的"创建新项目"
- 开始创作:在编辑器中编写你的故事
- 实时预览:右侧面板实时显示游戏效果
- 发布游戏:完成后一键导出分发
基于最新的依赖分析和代码优化,项目采用了精简的模块化架构:
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环境
-
项目管理
- 创建新项目或打开现有项目
- 支持多文件工程管理
- 自动保存和版本控制
-
脚本编写
- 使用Ink语言编写互动剧情
- 实时语法检查和错误提示
- 智能代码补全和语法高亮
-
预览测试
- 实时预览游戏效果
- 可视化节点图查看剧情流程
- 支持断点调试和变量跟踪
- 浏览器预览:独立Web环境测试和分享
项目侧边栏提供类似VS Code的资源管理体验:
- 文件操作:创建、重命名、删除与拖拽移动文件
- Knot树:自动解析每个
.ink文件中的Knot并展示 - 变量面板:汇总项目中的
VAR/LIST声明,方便统一管理 - 🔍 全文搜索:FlexSearch引擎驱动的项目级搜索,支持正则表达式和文件过滤
- 🎯 智能索引:自动识别文件类型,实时增量更新,代码友好分词
- 一键编译:可从侧边栏触发全项目编译并查看输出
-
插件扩展
- 开发H5插件增强游戏体验
- 支持小游戏、动画、音效等
- 通过简单API集成到主游戏中
-
发布分发
- Web版:生成可直接部署的网页
- 桌面版:打包为exe/app/deb安装包
- 自动优化资源和性能
功能特色
- 独立Web环境:在浏览器中独立运行游戏,无需Electron客户端
- 跨设备测试:支持手机、平板、不同浏览器的兼容性测试
- 实时更新:编辑器修改后自动刷新浏览器预览
- 分享便捷:可生成预览链接分享给他人测试
使用方式
- 启动预览:在标题栏的"编译预览器"中选择"浏览器预览"
- 选择入口文件:从下拉菜单选择要预览的.ink文件
- 点击预览:点击播放按钮启动浏览器预览窗口
- 访问链接:浏览器自动打开
http://localhost:3001显示游戏
技术实现
- 动态路径解析:自动注入当前项目路径,支持图片、音频等资源加载
- 智能环境检测:自动识别浏览器环境,使用服务器端资源路径
- 热重载机制:文件修改后自动刷新页面内容
- 错误处理:友好的错误提示和调试信息
适用场景
- 📱 移动端适配:测试在手机、平板上的显示效果
- 🌐 浏览器兼容:验证在不同浏览器中的运行情况
- 👥 团队协作:分享预览链接给团队成员测试
- 📊 性能测试:在真实Web环境中测试加载速度和性能
系统概览
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-clientAVG Maker 现已采用 Electron Builder 打包方案,实现了97%的体积优化(从2.56GB降至78MB),并确保所有功能在打包环境中正常工作。
# Windows打包(在Windows上运行)
npm run pack
# macOS打包(需要在macOS或GitHub Actions运行)
npm run pack:macos📋 自动化流程说明
npm run pack会自动执行以下步骤:
- 编译 TypeScript (
tsc -p tsconfig.node.json) - 生成 Electron 主进程文件- 构建预览客户端 (
npm run build:preview-client) - 生成浏览器预览模块- 转换资源文件 (
node scripts/build-cjs-assets.cjs) - 处理导出相关资源- 修复preload脚本 (
node scripts/fix-preload-for-packaging.cjs) - CommonJS格式转换- 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
# 确保所有运行时依赖都被正确包含-
减小包体积
# 清理开发依赖 npm prune --production # 使用ASAR压缩 asar: true // 在forge.config.js中启用
-
提升启动速度
- 启用V8快照
- 减少主进程初始化代码
- 使用预加载脚本优化
-
内存优化
- 限制渲染进程内存使用
- 及时清理未使用的资源
对于生产环境发布,建议添加代码签名:
// forge.config.js 添加签名配置
packagerConfig: {
osxSign: {
identity: 'Developer ID Application: Your Name'
},
osxNotarize: {
appleId: 'your-apple-id',
appleIdPassword: 'your-app-password'
}
}内部使用
- 使用ZIP版本,简单解压即用
- 可放置在共享网络位置
对外分发
- 使用Squirrel安装包,提供标准安装体验
- 配置自动更新机制
企业部署
- 配置代码签名证书
- 使用企业级分发工具
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/ # 解压后的文件
使用VirtualBox虚拟机测试(推荐)
- 安装VirtualBox
- 创建Ubuntu 20.04/22.04虚拟机
- 将打包文件复制到虚拟机
- 运行安装脚本:
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):
- 预构建阶段 (
npm run predev)- TypeScript 编译:
electron/→dist/electron/ - TypeScript 编译:
server/→dist/server/ - ES模块转换:将
preload.js转为 CommonJS 格式
- TypeScript 编译:
- 并发启动:
- Vite 开发服务器:运行在
http://localhost:5173,提供热重载 - Electron 应用:等待 Vite 启动后加载开发服务器
- Vite 开发服务器:运行在
- 后台服务:
- 预览服务器:内置 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()# 检查预览服务器状态
curl http://localhost:3001/api/refresh-time
# 检查 Ink 文件编译
npm run watch:ink # 单独运行 Ink 编译器
# 查看详细编译日志
DEBUG=avg-maker:* npm run dev# 检查 manifest 文件
cat server/public/preview-manifest.json
# 重新构建预览客户端
npm run build:preview-client
# 检查资源文件哈希
ls -la server/public/preview-client.*# 检查 TypeScript 配置
npx tsc --noEmit # 仅类型检查,不生成文件
# 检查各模块的 TypeScript 配置
npx tsc -p tsconfig.node.json --noEmit
npx tsc -p server/preview-client/tsconfig.json --noEmit# 检查预加载脚本格式
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 /- 获取预览页面HTMLGET /api/refresh-time- 获取最后刷新时间戳(用于自动刷新检测)
HTML生成工具:
import { generatePreviewHTML } from '../server/utils.js';
// 生成预览HTML页面
const html = generatePreviewHTML(
storyJsonData, // 编译后的Ink JSON数据
'story.ink', // 文件名
null, // 错误消息(可选)
Date.now() // 刷新时间戳
);Ink是专为互动小说设计的强大脚本语言:
# 你的第一个互动故事
-> start
== start ==
你站在一个神秘的十字路口。
* [向左走] -> left_path
* [向右走] -> right_path
* [直接前进] -> forward_path
== left_path ==
你选择了左边的小径...
-> DONE
== right_path ==
右边传来奇怪的声音...
-> DONE
== forward_path ==
你勇敢地向前走去...
-> DONE- 变量系统:支持数值、字符串、布尔值
- 条件逻辑:复杂的分支判断
- 函数系统:可重用的脚本片段
- 存档机制:玩家进度保存
- 多媒体:图片、音效、动画支持
- 互动小说:文字冒险游戏
- 教育游戏:互动学习体验
- 营销游戏:品牌互动体验
- 艺术项目:数字叙事作品
查看我们的案例库了解更多精彩作品。
我们欢迎社区的每一份贡献:
- 🐛 报告Bug:Issues
- 💡 功能建议:Discussions
- 🔧 代码贡献:Pull Requests
- 📖 文档改进:帮助完善使用指南
# 添加新依赖时的注意事项
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 - 报告问题和功能建议
- 标签系统使用指南 - 学习如何使用标签增强故事表现
- 创作最佳实践 - 专业级创作技巧和建议
- 项目结构规范 - 标准化的项目组织方式
- MCP开发指南 - MCP架构和开发完整指南
- CLI系统文档 - CLI终端和工具使用指南
- GitHub Discussions:参与讨论 - 功能建议和技术交流
- 开发者文档:docs/README.md - 按角色分类的完整文档导航
本项目采用双重许可证模式:
- ✅ 个人学习和爱好项目
- ✅ 教育和学术研究使用
- ✅ 开源项目和非营利组织
- ✅ 非商业性游戏创作
- 💰 Indie开发者 - $99/年(年收入<$100K)
- 💰 专业开发者 - $299/年(年收入<$1M)
- 💰 企业授权 - $999/年(无限制)
📧 商业授权咨询:license@avgmaster.com
详细条款请查看 LICENSE 文件。
基于深度依赖分析,AVG Maker 在保持功能完整性的同时实现了大幅精简:
- 文件精简: 695 → 95 个文件 (86.3%减少)
- 核心覆盖: 仅13.7%的代码支撑100%功能
- 依赖清理: 移除Web客户端、共享代码等未使用模块
- 架构清晰: App.tsx仅依赖20个核心文件
- 启动速度: 减少文件加载,提升应用启动速度
- 维护性: 清晰的依赖关系,降低维护复杂度
- 开发效率: 精简的代码结构,便于新功能开发
- 构建优化: 更小的打包体积,更快的构建速度
经过深度代码分析和架构重构,AVG Maker实现了显著的性能提升和代码质量改进。详细的优化报告和技术文档可在 docs/ 目录中查看。
- 左侧 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%核心代码覆盖率
- ✅ 核心编辑和预览功能 (Monaco Editor + 实时预览)
- ✅ 智能崩溃恢复系统 (自动备份 + 状态恢复)
- ✅ 专业欢迎页面体验 (VSCode风格)
- ✅ 完整项目管理系统 (文件树 + Knot管理 + 变量面板)
- ✅ 🆕 React组件化视觉渲染 (角色立绘 + 背景 + 对话框)
- ✅ 🆕 智能图片匹配系统 (基于标签的资源自动匹配)
- ✅ 🆕 响应式视觉适配 (支持各种屏幕尺寸)
- ✅ 🆕 代码架构大幅优化 (600+冗余文件清理,保留95个核心文件)
- ✅ 🆕 专业CLI终端系统 (29个模块,性能优化97%,启动时间2秒)
- ✅ 🆕 完整MCP工具生态 (14个专业工具,标准化AI接口)
- ✅ 🆕 FlexSearch全文搜索系统 (Web Worker架构,毫秒级响应,智能索引)
- ✅ 🆕 项目级搜索面板 (支持正则、文件过滤、上下文显示、相关性排序)
- ✅ AI聊天面板集成 (支持自定义API)
- 🔄 AI辅助创作功能
- 🔄 云端同步支持
- 🔄 模板库系统
- 🔄 协作编辑功能
- 🔄 高级视觉效果和动画
- 📋 可视化剧情编辑器
- 📋 角色管理系统
- 📋 资源管理器
- 📋 发布平台集成
让创作变得简单,让故事触动人心
AVG Maker - 每个人都是游戏创作者
⭐ 如果这个项目对你有帮助,请给我们一个Star!
© 2025 AVG Maker Team. Made with ❤️ for storytellers worldwide.
