AI 辅助开发

本文教你如何利用 ModSDK MCP Server 配合 AI 编程助手高效开发中国版 Mod。重点不在工具本身，而在于如何正确地向 AI 提需求——好的提示词能让 AI 一次生成可用代码，差的提示词只会浪费时间。

什么是 MCP

MCP（Model Context Protocol）是一种让 AI 助手调用外部工具的标准协议。ModSDK MCP Server 将 1879 个 API/事件文档、代码生成、代码审查等能力封装为工具，AI 在对话中自动调用，无需你手动查文档。

安装与配置

1. 下载

git clone https://github.com/MCNeteaseDevs/modsdk_mcp_server.git
cd modsdk_mcp_server
pip install -r requirements.txt

要求 Python >= 3.10。

2. 配置 AI 客户端

将路径替换为你的实际安装路径。

Claude Desktop — 编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "ModSDK MCP Server": {
      "command": "python",
      "args": ["D:/modsdk_mcp_server/start_mcp.py"]
    }
  }
}

Cursor / VS Code — 项目根目录创建 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "servers": {
    "ModSDK MCP Server": {
      "command": "python",
      "args": ["D:/modsdk_mcp_server/start_mcp.py"]
    }
  }
}

3. 验证

输入"搜索 GetEngineCompFactory 的用法"，如果 AI 返回了 API 文档，说明连接成功。

核心原则：先查文档，再写代码

这是使用 AI 开发 ModSDK 最重要的一条原则。MCP Server 内置了文档优先机制，但你的提示词直接决定 AI 是否会先查文档。

为什么必须先查文档

ModSDK 的事件参数名不统一。AI 如果凭记忆写代码，参数名大概率会错：

事件	玩家 ID 参数名	取消参数名
ServerPlayerTryDestroyBlockEvent	playerId	cancel
ServerItemUseOnEvent	entityId	ret
PlayerDieEvent	id	—
AddServerPlayerEvent	id	—

如果不查文档，AI 可能把 PlayerDieEvent 的参数写成 playerId，但实际上是 id。这种 bug 运行时不会报错，只会静默失败。

最常见的 AI 错误

AI 编写 ModSDK 代码时最常犯的错误就是事件参数名猜错。务必在提示词中要求 AI 先查文档确认参数。

提示词技巧

技巧 1：明确要求查文档

差的提示词：

帮我写一个玩家死亡掉落物品的功能

AI 可能直接从记忆中生成代码，参数名可能错误。

好的提示词：

帮我实现玩家死亡时掉落所有背包物品。
请先用 search_api 查一下玩家死亡事件和掉落物品相关的接口，
确认参数名后再写代码。

AI 会执行以下工作流：

1. search_api("玩家死亡") → 找到 PlayerDieEvent
2. get_api_detail("PlayerDieEvent") → 确认参数是 id（不是 playerId）
3. search_api("掉落物品") → 找到 SpawnItemToLevel
4. get_api_detail("SpawnItemToLevel") → 确认完整参数签名
5. 基于真实参数名生成代码

技巧 2：提供上下文约束

告诉 AI 你的命名空间、Mod 结构、已有代码的位置，减少 AI 猜测。

差的提示词：

生成一个自定义剑

好的提示词：

帮我生成一把自定义剑，要求：
- 命名空间：adventure_mod
- 物品 ID：flame_sword
- 攻击力 12，耐久 800
- 放在 behavior_pack/netease_items_beh/ 目录下
- 资源包放在 resource_pack/netease_items_res/ 目录下
- 同时生成 zh_CN.lang 本地化条目

技巧 3：分步骤提需求

复杂功能不要一句话说完，分步骤让 AI 做：

我要做一个"每日签到"系统，分三步来：

第一步：先帮我设计数据结构，玩家签到数据怎么存储？
用 search_api 查一下 SetExtraData 和 GetExtraData 的用法。

等 AI 完成数据设计后：

第二步：写服务端逻辑。玩家输入 /sign 命令触发签到，
每天只能签一次，连续签到有额外奖励。
先查一下 CustomCommandTriggerServerEvent 的参数。

最后：

第三步：写客户端 UI，显示签到日历。
先加载 guide://json-ui 资源看一下 JSON UI 的写法规范。

技巧 4：要求 AI 使用特定工具

MCP Server 提供了精确度不同的搜索工具，你可以指定 AI 用哪个：

用 get_api_detail("SetBlockNew") 查一下这个接口的完整参数签名

用 search_components("minecraft:food") 查一下食物组件的配置方式

加载 api-index://full 资源，浏览所有 API 索引，
找到和"方块容器"相关的接口

技巧 5：让 AI 审查已有代码

把你的代码贴给 AI，让它检查网易规范：

帮我审查下面这段 ServerSystem 代码，重点检查：
1. Python 2.7 兼容性
2. 客户端/服务端是否混用
3. GetEngineCompFactory 是否缓存
4. Tick 是否有降帧
5. 事件参数名是否正确（查文档确认）

[你的代码]

技巧 6：利用架构模式

遇到通用需求时，让 AI 先获取架构模式再开发：

我要做客户端和服务端的跨端通信。
先用 get_architecture_pattern("跨端通信") 看一下标准模式，
然后基于这个模式帮我写代码。

可用的架构模式：

模式名	说明
跨端通信	Client/Server 事件通信完整流程
组件使用	GetEngineCompFactory 组件创建最佳实践
UI 开发流程	JSON UI 定义 → 注册 → 创建 → 控件操作
实体创建与管理	创建 → 设置属性 → 防清除 → 监听死亡
定时任务	AddTimer / AddRepeatedTimer / Tick 降帧
物品掉落与生成	世界掉落 / 放入背包 / 战利品表

常见工作流

工作流 1：从零创建 Mod

第 1 步：创建项目框架
→ "帮我创建一个 Mod 项目，名称'领地系统'，ID 为 territory_sys"

第 2 步：设计核心逻辑
→ "这个 Mod 的核心功能是：玩家可以圈地保护区域，
  其他玩家不能在保护区域内破坏方块。
  先帮我设计需要监听哪些事件，查文档确认参数名。"

第 3 步：逐个实现功能
→ "先实现圈地功能：玩家手持木棍右键两个方块确定对角点..."
→ "再实现保护功能：其他玩家在保护区域内破坏方块时取消..."
→ "最后加个 /territory list 命令显示自己的领地列表..."

第 4 步：代码审查
→ "把上面所有代码综合审查一遍，检查规范性和性能问题"

工作流 2：添加自定义内容

第 1 步：生成 JSON
→ "帮我生成一套红宝石装备 JSON，命名空间 rpg_mod：
  红宝石头盔（护甲 3）、胸甲（护甲 8）、护腿（护甲 6）、靴子（护甲 3）"

第 2 步：生成配方
→ "为这四件盔甲生成工作台合成配方，
  材料用自定义物品 rpg_mod:ruby 和 minecraft:stick"

第 3 步：生成战利品表
→ "当玩家击杀 Wither Boss 时，掉落一件随机红宝石装备"

第 4 步：写脚本逻辑
→ "红宝石头盔戴上后给玩家夜视效果，用什么接口？先查文档"

工作流 3：调试与修复

"我的代码运行后报错：
  [error] 'NoneType' object has no attribute 'GetPos'

相关代码：
  posComp = CF.CreatePos(entityId)
  pos = posComp.GetPos()

帮我分析原因，查一下 CreatePos 什么时候会返回 None"

AI 会查文档后告诉你：entityId 可能无效（实体已销毁或尚未加载），需要加空值检查。

反模式：这样用 AI 效果差

反模式 1：一句话做复杂系统

❌ "帮我做一个完整的 RPG 系统，包括职业、技能树、装备强化、副本、交易所"

这种提示词太宽泛，AI 要么给你一个粗糙的框架，要么在某个环节用了错误的 API。应该拆成 5 个独立任务。

反模式 2：不要求查文档

❌ "帮我写一个监听玩家攻击实体的服务端代码"

AI 可能凭记忆写出 args['playerId']，但实际参数可能是 args['id'] 或 args['entityId']。

反模式 3：不提供上下文

❌ "生成一个方块"

没有命名空间、ID、属性描述，AI 只能给你一个最简模板。提供越多约束，结果越精确。

反模式 4：不审查 AI 生成的代码

AI 生成的代码不一定 100% 正确。关键代码建议让 AI 自己做一轮审查：

✅ "帮我审查上面生成的代码，重点检查事件参数名是否和文档一致"

提示词模板

以下是一些经过验证的高效提示词模板，可以直接复制使用：

功能开发模板

我要实现 [功能描述]。

请按以下步骤操作：
1. 先用 search_api 搜索相关事件和接口
2. 用 get_api_detail 确认每个事件/接口的参数签名
3. 基于确认的参数写服务端代码
4. 代码遵循网易 ModSDK 规范（Python 2.7、CompFactory 缓存、C/S 分离）

约束条件：
- 命名空间：[你的命名空间]
- Mod ID：[你的 Mod ID]

JSON 生成模板

帮我生成 [物品/方块/实体] 的 JSON 配置：
- 命名空间：[namespace]
- ID：[item_id]
- [属性1]：[值1]
- [属性2]：[值2]

需要生成：
- 行为包 JSON（放 netease_items_beh/ 或 netease_blocks/）
- 资源包 JSON（放 netease_items_res/）
- zh_CN.lang 本地化条目
- item_texture.json / terrain_texture.json 条目

代码审查模板

请审查以下 ModSDK 代码，检查：
1. Python 2.7 兼容性（f-string、type hints、print 函数）
2. 客户端/服务端是否混用 import
3. GetEngineCompFactory 是否在模块级缓存
4. Tick 逻辑是否降帧
5. 事件参数名是否正确（用 get_api_detail 查证）
6. 是否有性能反模式（函数内 import、广播滥用等）

[粘贴代码]

问题排查模板

我的 Mod 遇到了问题：
- 现象：[描述具体现象]
- 报错信息：[粘贴报错]
- 相关代码：[粘贴代码]

请帮我分析原因。如果涉及 API 用法问题，先查文档确认正确用法。

MCP 工具速查

AI 会自动选择合适的工具，但了解工具能力有助于你写出更精准的提示词。

工具	用途	提示词示例
search_api	搜索 API/事件	"搜索和方块容器相关的接口"
get_api_detail	获取精确参数签名	"查一下 SpawnItemToPlayerInv 的参数"
search_docs	搜索文档详细说明	"搜索 JSON UI 的 _ui_defs.json 写法"
search_components	查组件用法	"查一下 minecraft:food 组件怎么配置"
get_best_practices	获取规范规则	"查看 UI 开发的最佳实践"
get_architecture_pattern	获取架构模板	"获取跨端通信的标准模式"
review_code	代码审查	"审查这段代码的规范性"
generate_mod_project	生成项目框架	"创建一个 Mod 项目"
generate_*_json	生成 JSON 配置	"生成一把自定义剑的 JSON"

内置规范

MCP Server 生成的所有代码自动遵循以下规范，你也应该在手动修改代码时遵守：

代码规范

规范	说明
Python 2.7 兼容	禁止 f-string、type hints、async/await、print() 函数
客户端/服务端分离	跨端只用事件通信，ServerSystem 禁止 import clientApi，反之亦然
CompFactory 缓存	CF = serverApi.GetEngineCompFactory() 文件顶部缓存
Tick 降帧	Tick 逻辑必须降帧（质数间隔）
点对点通信	优先 NotifyToClient，慎用 BroadcastToAllClient

UI 界面开发规范

规范	说明
_ui_defs.json 格式	必须用对象格式 {"ui_defs": [...]}，不能是纯数组
RegisterUI 时机	必须在 UiInitFinished 事件回调中调用
控件类型转换	GetBaseUIControl 返回基础控件，需 asButton() / asLabel() 等转换后调用特定方法
关闭 UI	使用 self.SetRemove()，不要用 PopScreen

下一步

• Python 脚本开发 — 脚本开发基础
• 基础概念 — Client-Server 架构
• 自定义游戏内容 — JSON 数据驱动开发