For Agents

给 Agent 的两套工具

gamekit 的读者主要是 AI。除了文档，还有两条让 AI 不用猜 的通道：用 Skill 把流程和判据装进上下文，用 MCP 把游戏内部状态读出来。

一、Skill：把流程装进上下文

一个 Skill 就是一个 SKILL.md。Agent 按 description 判断该不该加载，加载后照着做——不需要人再解释一遍「这个仓怎么用」。

端到端

gamekit-minigame

从 mg create 到三端产物：七个核心文件的职责、构建与门禁命令、六条实测踩坑判据、交付前自检清单。新建游戏或接玩法时加载这个。

单点聚焦

ui-authoring

只写 .ui 界面时用。含语法速查、组件 props、ui.check / ui.preview 工作流——写完在 Node 里验证，不用起浏览器。

两者互补：gamekit-minigame 管「怎么把这个游戏做出来」，ui-authoring 管「这屏界面怎么写对」。它的 description 里写明了边界——改引擎（packages/**）不属于它们，要先读仓库 AGENTS.md。

一键装好：把这段发给 agent

不用手抄步骤。把下面整段贴给任何一个能跑命令的 agent，它会自己完成 clone、安装、构建验证、注册 MCP、装 skill，最后按四条验收回报。

发给 agent 的提示词

目标：把 gamekit 装到这个环境并接好工具，装完能直接开新游戏。

仓库 https://github.com/ahao0150/gamekit ，装在 $HOME/gamekit
（已存在就复用，先看 git status，别覆盖未提交改动）。

1  node -v && pnpm -v          确认 Node ≥ 22
2  git clone https://github.com/ahao0150/gamekit.git $HOME/gamekit
   （已存在则 cd $HOME/gamekit && git pull --ff-only）
3  cd $HOME/gamekit && pnpm install
4  pnpm doctor                 必须全绿；有红项先修，不许跳过
5  cd games/platformer && pnpm build
   → build/web build/wx build/tt 三个目录都在，web 约 251 KB
6  注册 MCP（stdio），加完重连：
   {"mcpServers":{"mg-debug":{"command":"node",
     "args":["$HOME/gamekit/packages/debug-mcp/bin/mg-debug-mcp.mjs"]}}}
   调一次 ui.grammar，能返回 .ui 语法即接通
7  装 skill：把 $HOME/gamekit/skills/gamekit-minigame/SKILL.md
   复制到你环境的 skills 目录，文件里的仓库根路径改成本机实际路径；
   加载后应能读到「mg create 流程 + 六个踩坑判据」
8  回报四行：仓库路径 / doctor 结果 / 三端产物在不在 / MCP 与 skill 是否可用

失败就贴报错原文再修，不要跳过第 4 步。

为什么是提示词而不是安装脚本：每个 agent 环境的 skills 目录、MCP 配置位置都不一样，脚本写死路径必然在别的环境里失败；提示词让 agent 用自己的方式落地，最后按四条自检。仓库里的 skills/gamekit-minigame/SKILL.md 随 clone 一起下来，不需要另外分发。

二、MCP：把游戏内部读出来

@mg/debug-mcp 是一个 stdio MCP server。它让 agent 能查布局、看绘制树、读状态、截图、模拟点击——而不是靠猜。

离线工具（5 个，不用把游戏跑起来）

工具	做什么
`ui.grammar`	返回当前 `.ui` 语法（唯一真源，agent 不用照记忆写）
`ui.pattern`	取现成样例：`hud` / `list` / `modal` / `result`
`ui.check`	语法 + 布局断言，带行号、一次报全
`ui.layout`	解出每个节点的矩形与绘制顺序
`ui.preview`	ASCII 预览：结构 / 溢出 / 尺寸，多视口对比

这五个在纯 Node 里跑完，不需要启动游戏、浏览器或截图。改界面的快速循环就靠它们。

运行时工具（10 个，连到跑着的游戏）

工具	做什么
`canvas`	画布尺寸、dpr、可见区域
`tree`	当前帧的绘制结构树（谁画在谁上面）
`state`	游戏内部状态快照
`screenshot`	真实截图（含 canvas 内容）
`click`	按坐标 / 按节点名模拟点击，走真实命中路径
`snapshot`	记一份快照（布局 + 状态）
`snapshotList`	列出已有快照
`diff`	两次快照的差异——改一处，看它到底影响了什么
`checkRender`	断言「该画的东西真的画了」
`watch`	监听运行时变化

存档桩（2 个）

工具	做什么
`save_simulate_days`	快进 N 天的存档演进（验证离线收益、成长曲线）
`save_patch`	改存档字段，构造边界场景

接进来

MCP 配置（stdio）

{
  "mcpServers": {
    "mg-debug": {
      "command": "node",
      "args": ["<仓库根>/packages/debug-mcp/bin/mg-debug-mcp.mjs"]
    }
  }
}

也可以直接 node packages/debug-mcp/bin/mg-debug-mcp.mjs 手动起，按 MCP 协议用 stdin/stdout 对话。

为什么这条通道重要：「状态全绿、画面全空」在这个仓里复现过不止一次—— 数据断言过了，画面其实一片空白。让 agent 能 screenshot 再 checkRender，它才有机会发现自己画错了，而不是拿着绿色的测试报告宣布完成。

两者怎么配合

一个真实的改界面循环，agent 端到端不需要人陪。

加载 skill，拿流程与判据

读 gamekit-minigame 或 ui-authoring，知道该碰哪些文件、不该碰哪些。

用离线 MCP 工具写对

ui.grammar 拿语法 → ui.pattern 抄样例 → 写 .ui → ui.check + ui.preview 多视口验证。全在 Node 里，秒级反馈。

构建 + 门禁

mg build --all 三端产物、mg check 包体红线、游戏目录内 pnpm test。

用运行时工具看画面

screenshot 截图、checkRender 断言绘制发生过、diff 对比改动前后的差异。测试绿 ≠ 画面对，这一步不能省。