@4399aigame/aigame

4399 AI 小游戏开发工具链 —— 一条 CLI（aigame）+ 一个 MCP server， 让 AI 编程助手（Claude Code / Cursor / OpenClaw 等）能建 Godot 项目、出 H5 包、 连 4399 云端项目。

本仓库 fork 自 taptap/instant-games-open-mcp， fork 来源与改名清单见 NOTICE.md。

现在能跑什么

| 能力 | 状态 | 说明 | | ------------------- | ---------- | -------------------------------------------------------------------- | | Godot 项目模板 | ✅ 可用 | init 自动新建或接管，含导出预设、AGENTS.md、godot-ai 插件 | | H5 构建与预览 | ✅ 可用 | build / preview / dev（改动自动重建刷新）+ 体积报告 | | 环境体检 | ✅ 可用 | doctor，平台侧 + 引擎侧 | | 4399 登录与项目绑定 | ✅ 可用 | 小九 OM 授权码登录，云端项目 list / add / detail | | MCP server | ✅ 可用 | mcp install 一键注册进 AI 客户端；工具见下 | | MCP proxy | ✅ 可用 | stdio 前端 ↔ Streamable HTTP 后端，私有参数注入、断线重连 | | 发布到 4399 | ✅ 可用 | publish 自动构建、断点分块上传并等待线上激活 |

发行包已在构建时包含 4399 平台默认 Origin，普通用户直接执行 init 即可。--origin 只用于联调时覆盖该地址；离线初始化必须显式传 --local。这与远端 Maker 服务不同： Maker 服务仍须按需要配置 AIGAME_MAKER_ORIGIN（或分环境的 ..._RND / ..._PRODUCTION），两者不是同一个配置。

快速开始

npx -y -g @4399aigame/aigame@latest init --origin https://dev-aigame.gz4399.com
aigame update

首次在线 init 会真正安装并验证最新版全局 CLI，再由该全局进程继续初始化。 init 是唯一的初始化主流程：登录 4399 → 选云端项目 → 引擎项目模板 → 本地 git init → MCP 客户端配置。省略 --target-dir 时使用当前目录，省略 --engine 时使用 Godot；不联网时显式使用 init --local（跳过登录与云端绑定）。若当前引擎项目 已经绑定云项目，重复运行普通 init 只显示摘要并提示使用 update。

后续统一执行 aigame update：先更新全局 CLI，再由最新版 CLI 更新 template 受管内容。schema v3 模板把项目分成三类：system 由模板更新，user 永远以用户版本为准，shared 只合并 manifest 明确声明的 key、区块或文件。shared 双方改到同一处时，CLI 会先把当前内容 永久备份到 .aigame/backups/，再返回退出码 2，让用户逐项选择保留、覆盖或交给 Agent 生成候选；全部选择完成后才一次性应用。更新判断不读取项目 Git 历史或工作区状态， 因此用户删除的 user 文件（例如自定义入口场景）不会在下次更新时被程序猜测并补回。

非交互环境可用 update --json 取得会话 ID 和下一条命令，再依次执行 --resolve、--confirm-candidate、--apply 或 --cancel。旧 schema v2 模板仍兼容 .aigame/reports/<id>.json 与 --accept-adapted/--reinitialize，但它们不是 v3 的推荐流程。

模板从哪里来

• 普通 init 在真正初始化时会下载远端 stable 的最新模板，不需要先升级 CLI。
• init --local 不探测网络，只读取最近一次校验成功的缓存；没有缓存就直接失败，不会写半个项目。
• 开发模板时用 --template-dir ../aigame-templates，直接读取相邻仓库的未提交内容，既不下载也不改共享缓存。
• CLI 先请求 GET /api/main/v1/gateway/network：lan 只用 https://gitlab.gz4399.com/aigame/templates.git，其余情况只用 https://git.gz4399.com/aigame/templates.git。选定的 Git 下载失败就直接报错，LAN/WAN 不交叉兜底，也不退回旧缓存。
• 老项目不会靠重复 init 自动套用新模板；init 的重复运行预检会直接返回已有项目状态。

当前只交付 godot/minimal。仓库结构已经按引擎分层，为 Cocos 预留扩展方式，但 Cocos 模板和插件尚未交付。

发布到 4399

项目完成 init 并绑定云端项目后执行：

aigame publish

命令会逐行显示权限检查、构建、压缩、Release 创建、分块上传和线上激活阶段。发布 ZIP 固定按 20 MiB 分片、最多五个并发请求上传，进度同时显示 Server 已确认数量和真实进行中 数量。阶段进度写入 stderr，最终结果写入 stdout；脚本可用 aigame publish --json > publish-result.json 保存纯 JSON 结果。

命令

工程 · 和本机代码打交道
  dev      本地开发：出包 + 预览 + 改动自动重建刷新
  build    出 H5 包并给出体积报告
  preview  本地预览已出的 H5 包
  doctor   环境体检（平台侧 + 引擎侧）

平台 · 和 4399 打交道
  init         初始化项目工作区
  update       依次更新全局 CLI 与 template 受管文件
  login        用小九 OM 账号登录 4399 平台
  logout       退出登录
  auth token   输出已验证可用的 accessToken，供外部脚本 / Skill 使用；按需自动登录
  publish      构建并发布到 4399

集成 · AI 客户端与 MCP
  mcp      把本工具注册进 AI 客户端
  logs     运行时日志
  proxy    以 MCP proxy 模式启动

其他
  godot-ai  godot-ai 编辑器插件（AI 直接操作 Godot 编辑器）

不带参数且 stdin 不是终端（被 AI 客户端拉起）时，以 MCP server 模式运行。

MCP 工具

aigame 作为 MCP server 暴露：

| 工具 | 用途 | | ------------------------------- | -------------------------- | | maker_status_lite | 项目 / MCP 就绪状态 | | maker_build_current_directory | 构建、预览、运行、提交、推送 | | godot_doctor | Godot 环境体检 | | godot_export_web | 导出 Web/H5 | | godot_preview | 本地预览 | | godot_query_runtime_logs | 查运行时日志 |

外加 resource maker://status（起步或恢复工作时先读它）。

编辑器内的操作（建节点、写脚本、连信号、配动画）由 godot-ai 插件的 43 个工具负责 —— init 会自动 装它，两边分工不重叠。

架构

pnpm workspace，代码在 packages/ 下，根包 src/ 只有 cli.ts。

@4399aigame/aigame-core     工程内核 + 引擎插件系统（build/preview/dev/doctor/init）
@4399aigame/aigame-godot    Godot 引擎插件（detect / templates / preset / export）
@4399aigame/aigame-proxy    MCP 代理（stdio 前端 ↔ Streamable HTTP 后端）
@4399aigame/aigame-maker    Maker 工作流：登录、云端项目、MCP 安装矩阵 + MCP server

四个包都是 private: true 的内部源码模块，不发 npm；对外只有根包 @4399aigame/aigame，rollup 打出三个 bundle：

| 产物 | 入口 | 是否随包发布 | | --------------- | ------------------------------------ | ------------ | | dist/cli.js | src/cli.ts | 是 | | dist/proxy.js | packages/aigame-proxy/src/main.ts | 是 | | dist/maker.js | packages/aigame-maker/src/index.ts | 否，仅本地调试 |

开发

pnpm install
pnpm dev                 # 本地源码运行，读取 config/env/.env.development
pnpm build:dev           # 测试包，读取 config/env/.env.dev
pnpm build:prod          # 正式 npm 包，读取 config/env/.env.production
pnpm verify              # check + typecheck + test，提交前跑这条

没有「提交即跑」的 CI、没有 pre-commit hook —— 唯一的自动检查点在 scripts/publish.sh 的发布门禁（本地发和 Jenkins 发都走它）。

环境变量

| 变量 | 说明 | 默认 | | --------------------------------- | ----------------------------------------- | --------------------- | | AIGAME_DEFAULT_ORIGIN | 构建默认 Origin；通常由 config/env 提供 | 随所选环境配置 | | AIGAME_ORIGIN | 运行时覆盖 4399 平台 Origin | 发行包内置默认值 | | AIGAME_SERVER_ORIGIN | 运行时覆盖 4399 网关 Origin（拆分部署） | 跟随平台 Origin | | AIGAME_WEB_ORIGIN | 运行时覆盖 4399 登录页 Origin（拆分部署） | 跟随平台 Origin | | AIGAME_MAKER_ORIGIN | 远端 Maker 服务 origin（按需配置） | 无 | | AIGAME_HOME | 本地凭据与模板缓存根目录 | ~/.aigame | | AIGAME_ENV | production / rnd | production | | AIGAME_VERBOSE | 详细日志 | false | | AIGAME_LOG_ROOT | 日志目录 | /tmp/aigame/logs |

平台默认地址由仓库配置文件管理：

| 用途 | 配置文件 | Origin | | --- | --- | --- | | 本地 | config/env/.env.development | https://local-aigame.gz4399.com | | 测试 | config/env/.env.dev | https://dev-aigame.gz4399.com | | 正式 | config/env/.env.production | https://aigame.gz4399.com |

不再提供含义不明确的 pnpm build；测试构建用 pnpm build:dev，正式构建用 pnpm build:prod。

发布

对外发布的只有根包。版本号和 CHANGELOG 由 changesets 管理。

pnpm ship                 # 判断当前处在哪一步，然后带你走完
pnpm ship --status        # 只看状态，什么都不做

# ship 背后就是这三条
pnpm changeset            # 记一条变更
pnpm changeset:version    # 升版本号 + 写 CHANGELOG
pnpm release              # 构建 + 发 npm + 打 tag

pnpm release:dry          # 预览，不发布也不改文件

也可以整条交给 Jenkins：去 ywkfci.gz4399.com 的 aigame-npm-release 点 Build， 参数默认（BUMP=auto）不用动 —— CI 会升版本、写 CHANGELOG、提交推 master、发 npm、 打 tag。想让 CHANGELOG 有内容就提前写 changeset 合进 master，不写也照发。 流水线定义在 Jenkinsfile，两条路径走的是同一个 scripts/publish.sh。

tag 是发布的产物，不是触发器：推 tag 不会触发任何构建。

完整说明见 docs/CI_CD.md。

相关文档

• CLAUDE.md —— 开发规范（AI 与人共用）
• docs/MAKER.md —— Maker CLI / MCP 的完整行为说明
• docs/CLI_DELIVERY_GUIDE.md —— CLI 对外交付与使用指南
• docs/PROXY.md —— MCP Proxy 开发指引
• docs/CI_CD.md —— 版本发布流程
• docs/LOG_SYSTEM.md —— 日志系统
• NOTICE.md —— fork 来源与改名清单
• CONTRIBUTING.md —— 贡献流程