@4399ywkf/aigame

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

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

现在能跑什么

| 能力 | 状态 | 说明 | | ------------------- | ---------- | -------------------------------------------------------------------- | | Godot 项目脚手架 | ✅ 可用 | create / adopt / 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 服务仍须按需要配置 YWKF_AIGAME_MAKER_ORIGIN（或分环境的 ..._RND / ..._PRODUCTION），两者不是同一个配置。

快速开始

cd /path/to/game
npx -y @4399ywkf/aigame init

init 是唯一的初始化主流程：登录 4399 → 选云端项目 → 引擎项目脚手架 → 本地 git init → MCP 客户端配置。省略 --target-dir 时使用当前目录，省略 --engine 时使用 Godot；不联网时显式使用 init --local（跳过登录与云端绑定）。若当前引擎项目 已经绑定云项目，重复运行普通 init 只显示摘要，不登录也不修改文件。

发布到 4399

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

ywkf-aigame publish

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

命令

工程 · 和本机代码打交道
  create   新建项目（目标目录必须还不是项目）
  adopt    为既有项目补齐工具链配置
  dev      本地开发：出包 + 预览 + 改动自动重建刷新
  build    出 H5 包并给出体积报告
  preview  本地预览已出的 H5 包
  doctor   环境体检（平台侧 + 引擎侧）

平台 · 和 4399 打交道
  init     初始化项目工作区
  login    用小九 OM 账号登录 4399 平台
  logout   退出登录
  publish  构建并发布到 4399

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

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

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

MCP 工具

ywkf-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。

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

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

| 产物 | 入口 | | --------------- | ----------------------------------- | | dist/cli.js | src/cli.ts | | dist/maker.js | packages/aigame-maker/src/index.ts | | dist/proxy.js | packages/aigame-proxy/src/main.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 发都走它）。

环境变量

| 变量 | 说明 | 默认 | | --------------------------------- | ----------------------------------------- | --------------------- | | YWKF_AIGAME_DEFAULT_ORIGIN | 构建默认 Origin；通常由 config/env 提供 | 随所选环境配置 | | YWKF_AIGAME_ORIGIN | 运行时覆盖 4399 平台 Origin | 发行包内置默认值 | | YWKF_AIGAME_SERVER_ORIGIN | 运行时覆盖 4399 网关 Origin（拆分部署） | 跟随平台 Origin | | YWKF_AIGAME_WEB_ORIGIN | 运行时覆盖 4399 登录页 Origin（拆分部署） | 跟随平台 Origin | | YWKF_AIGAME_MAKER_ORIGIN | 远端 Maker 服务 origin（按需配置） | 无 | | YWKF_MCP_ENV | production / rnd | production | | YWKF_MCP_VERBOSE | 详细日志 | false | | YWKF_MCP_LOG_ROOT | 日志目录 | /tmp/ywkf-mcp/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/PROXY.md —— MCP Proxy 开发指引
• docs/CI_CD.md —— 版本发布流程
• docs/LOG_SYSTEM.md —— 日志系统
• NOTICE.md —— fork 来源与改名清单
• CONTRIBUTING.md —— 贡献流程