letsgal-ai — AI 辅助 LetsGal Studio 创作工具链

从零逆向 LetsGal Studio 工程格式，把它变成 AI 可以直接创作 的工具：一行式故事 DSL → 完整可运行工程（章节/角色/场景/分支/演出），CLI 与 MCP 双通道，零依赖。

格式参考（逆向自官方模板 + 1.11.0 安装包）：docs/letsgal-format.md
故事 DSL 规范：docs/STORY-DSL.md

为什么

LetsGal Studio 是桌面 GUI 编辑器（无 MCP、无 CLI），但它的一切都是磁盘上的普通 JSON。本项目把该格式完全程序化：

AI 生成剧本 → 一行命令编译成工程 → Studio 打开即玩（可再精修演出/素材）
格式完全对齐官方（project.json / characters.json / scenes.json / chapters/*.json / assets/.manifest.json）， Studio 打开零报错，自动修复合入角色表情、替换素材都自然

快速开始

# 安装（无需依赖，直接 clone 或 npm link）
npm link                    # 或 node bin/letsgal-ai.js …

# 1. 初始化工程骨架
letsgal-ai init my-game --name "时间的河流"

# 2. 写故事（见 examples/example.dsl）→ 编译
letsgal-ai build story.dsl -o my-game --name "时间的河流"

# 3. 校验
letsgal-ai validate my-game

# 4. 用 LetsGal Studio 打开 my-game → 播放

MCP（AI Agent 直接调用）

letsgal-ai mcp     # stdio JSON-RPC 2.0，零依赖实现

暴露工具：

工具	说明
`letsgal_init`	初始化工程骨架
`letsgal_compile`	故事 DSL → 完整工程（自动注册角色/场景）
`letsgal_add_dialogue` / `letsgal_add_narration`	追加对白/旁白 Block
`letsgal_validate`	校验结构 + 资产引用
`letsgal_register_asset`	登记资产到 .manifest.json
`letsgal_list_chapters`	章节/Fragment 统计

任何 MCP 客户端（Claude Code / DSH / 自研）配置 node bin/letsgal-ai.js mcp 即可。

CLI

letsgal-ai init <dir> [--name 标题]
letsgal-ai build <story.dsl> -o <dir> [--name 标题]
letsgal-ai validate <dir>
letsgal-ai list <dir>
letsgal-ai mcp

作为库使用

import { compileStory, initProject, validateProject, applyCharacterFlow, dialogue, narration, scene } from '@lilyco-42/letsgal-ai';

开发

npm test        # 冒烟测试：init → build → validate → MCP 握手

授权与致谢

本工具 MIT；不含素材。生成的工程可直接使用 LetsGal Studio 官方模板素材（随引擎提供）
逆向依据：LetsGal Studio 1.11.0（Windows）安装包 + 官方模板工程

Roadmap

Ren'Py 风格代码 ↔ Block 双向转换（对齐官方代码编辑器语法）
无头构建（复用官方 build-worker 产出 web 版）
lilyco（Rust）原生组件：lilyco-letsgal（见 docs/lyco-integration.md）