AI大模型游戏开发与Unity脚本编写指南

《AI大模型游戏开发与Unity脚本编写指南》文档编号：AI-GD-UNITY-001版本：V1.0密级：【内部/公开】编制：【姓名/团队】审核：【姓名/团队】日期：【YYYY-MM-DD】适用项目：【项目名称】适用引擎：Unity2021.3LTS及以上，推荐Unity2022.3LTS/Unity6适用对象：游戏客户端开发、AI系统开发、技术美术、策划、QA、技术负责人、外包团队使用说明：1.将文中【】内容替换为实际项目信息。2.代码模板可保存至Assets/_Project/Scripts/AI/后直接挂载使用。3.生产环境严禁在Unity客户端硬编码大模型APIKey，必须通过自有AI网关或后端服务代理。4.本文档可作为团队AI开发规范、外包交付说明、代码审查依据和项目SOP。5.本文档不构成法律意见，上线前应由法务与合规团队审核。修订记录版本日期修订人修订说明V1.0【YYYY-MM-DD】【姓名】初版发布目录总则AI大模型在游戏开发中的定位与能力边界技术架构与工程流程提示词工程规范Unity脚本编写规范Unity接入大模型实践安全、合规与伦理质量保障与发布团队协作与资产管理附录：模板与检查清单1.总则1.1目的本指南用于规范AI大模型在游戏开发中的应用方式，统一Unity脚本编写标准，提升代码质量、开发效率与运行稳定性，降低AI生成内容带来的安全、合规、性能与维护风险。1.2范围本指南覆盖：开发期：AI辅助代码生成、重构、测试、文档、剧情、关卡、数值、本地化。运行期：基于大模型的NPC对话、智能助手、动态任务、内容生成、记忆系统。Unity脚本：C#编码规范、MonoBehaviour生命周期、异步与协程、性能优化、测试与审查。安全合规：密钥管理、隐私保护、内容审核、版权、AI生成标识、日志审计。工程协作：提示词库、版本控制、代码审查、发布检查。1.3术语与缩略语术语说明LLMLargeLanguageModel，大语言模型Prompt提示词，输入给大模型的指令与上下文Token大模型处理文本的基本单位，影响成本与延迟RAGRetrieval-AugmentedGeneration，检索增强生成AIGatewayAI网关，统一鉴权、限流、审核、路由、日志的服务结构化输出要求模型返回JSON等可解析格式幻觉模型生成看似合理但不正确的内容降级策略AI不可用时回退到预设内容或本地规则1.4推荐原则人机协同：AI生成内容必须经过人工审查，不得直接进入生产分支。最小权限：客户端不持有模型密钥，不直连模型服务。可观测：记录模型版本、提示词版本、耗时、Token、错误码、审核结果。可回滚：模型、提示词、功能开关均可独立回滚。可降级：AI失败时游戏仍可正常运行。合规优先：遵守数据隐私、内容安全、版权与AI标识要求。2.AI大模型在游戏开发中的定位与能力边界2.1开发期典型应用场景说明推荐程度代码生成生成MonoBehaviour、工具类、编辑器扩展高，需审查代码重构提取方法、解耦、优化命名高单元测试生成NUnit测试用例高设计文档生成GDD、任务表、对话树中，需策划确认剧情对话生成NPC台词、任务文本、支线剧情中，需内容审核本地化多语言翻译与润色中，需母语审校美术提示词生成概念图、图标、材质提示词中，需版权确认QA辅助生成测试用例、分析日志高2.2运行期典型应用场景说明关键挑战NPC对话玩家自由输入，NPC动态回复延迟、成本、内容安全智能助手游戏内引导、攻略问答准确性、防注入动态任务根据玩家行为生成任务逻辑一致性、可测试性个性化内容生成称号、描述、剧情分支审核、缓存长期记忆NPC记住玩家行为隐私、存储、RAG2.3能力边界大模型不是游戏逻辑的替代品。推荐组合：规则系统、状态机、行为树负责确定性逻辑。大模型负责语言表达、内容变体、非确定性交互。数值、战斗、存档、经济系统必须由传统代码控制。大模型输出必须经过格式校验、内容审核与业务规则校验。2.4推荐架构原则客户端轻量化：Unity只负责输入、UI、表现、缓存与降级。服务端集中化：鉴权、限流、提示词、模型调用、审核、日志放在AI网关。模型可替换：通过配置切换云端模型、本地模型或混合路由。上下文可控：限制历史长度，使用摘要与RAG，避免无限增长。成本可控：设置Token上限、缓存、限流、用户级配额。3.技术架构与工程流程3.1推荐总体架构Unity客户端├─UI/Gameplay├─ILlmClient├─本地缓存/降级台词└─用户会话Token│HTTPS/WSS▼AIGateway├─鉴权/限流/配额├─提示词模板管理├─上下文与记忆管理├─内容安全审核├─模型路由└─日志/监控/审计│▼模型层├─云端LLM├─本地小模型└─向量数据库/RAG3.2开发工作流需求定义：明确功能、用户价值、验收标准、风险。上下文准备：提供Unity版本、渲染管线、输入系统、已有代码、命名规范。AI生成：使用提示词模板生成代码、文档、测试或内容。人工审查：检查逻辑、安全、性能、合规、可维护性。测试验证：EditMode/PlayMode测试、Mock测试、真机测试。集成发布：PR审查、CI检查、灰度发布、监控告警。迭代优化：根据日志、成本、用户反馈优化提示词与模型。3.3版本控制规范使用Git，分支建议：main、develop、feature/*、release/*、hotfix/*。提交信息建议遵循ConventionalCommits：feat:、fix:、docs:、test:、chore:。AI辅助生成的代码应在PR中标记：AI-Assisted:true，但作者仍需对代码负责。提示词、模型配置、Schema、评估集必须纳入版本控制。禁止提交APIKey、用户隐私数据、未授权素材。4.提示词工程规范4.1提示词结构推荐使用以下结构：#角色你是一名【角色】。#任务请完成【具体任务】。#上下文-项目：【项目名称】-引擎：【Unity版本】-平台：【PC/移动/主机】-已有代码：【粘贴相关代码】-约束：【性能/安全/规范】#约束-遵循【规范名称】-不要使用【禁止项】-必须处理【异常/边界】#输出格式1.设计说明2.完整代码3.使用步骤4.测试用例5.风险与待确认项#验收标准-可编译，无警告-无每帧堆分配-无Find/GetComponent热路径-包含异常处理4.2Unity脚本生成提示词模板#角色你是一名资深Unity客户端开发工程师，熟悉C#、MonoBehaviour生命周期、性能优化与移动端适配。#任务为【功能名称】编写一个UnityC#脚本。#上下文-Unity版本：【2022.3LTS】-渲染管线：【URP】-输入系统：【InputSystem】-目标平台：【PC/Android/iOS】-已有架构：【粘贴相关接口或类】-命名空间：【Company.Project.Module】#约束-使用[SerializeField]private代替public字段。-不要在Update中调用Find、GetComponent、Camera.main。-避免每帧产生GCAlloc。-事件必须在OnDisable中解绑。-异步方法使用CancellationToken，命名以Async结尾。-提供XML注释。-不要引入未授权第三方库。-不要硬编码APIKey。#输出格式1.设计说明2.完整代码3.挂载与配置步骤4.测试用例5.风险与待确认项4.3代码审查提示词模板请审查以下UnityC#代码，按严重级别输出。检查项：-空引用、生命周期、事件解绑-性能：GC、Find、GetComponent、LINQ、字符串拼接-异步：取消、异常、主线程、竞态-安全：密钥、注入、隐私、网络请求-规范：命名、注释、可测试性、可维护性输出表格：|级别|文件/行|问题|建议|示例修复||---|---|---|---|---|4.4游戏设计/对话提示词模板你是一名游戏叙事设计师。请为【NPC名称】生成【数量】条对话。背景：【世界观】NPC人设：【性格、目标、秘密】玩家状态：【等级、阵营、已完成任务】输出JSON：{"npc_id":"npc_001","lines":[{"id":"line_001","text":"对话内容","emotion":"neutral|happy|angry|sad","conditions":["quest_001_completed"],"actions":[{"type":"give_item","item_id":"apple"}]}]}要求：不得生成违法违规内容；每条不超过80字；符合角色设定。4.5提示词反模式不提供上下文，直接让AI“写一个游戏”。不规定输出格式，导致无法解析。不限制Token，导致成本失控。不要求异常处理与测试。把玩家输入直接拼接到系统提示词中，导致提示词注入。将APIKey放入提示词或客户端代码。5.Unity脚本编写规范5.1推荐目录结构Assets/_Project/Scripts/Core/Gameplay/AI/Data/UI/Editor/Tests/Art/Audio/Prefabs/Scenes/Settings/Resources/Packages/ProjectSettings/5.2命名与格式类型规范示例类/结构体PascalCaseNpcDialogueManager接口I+PascalCaseILlmClient公共方法PascalCaseSendAsync私有字段_camelCase_maxHistoryMessages参数/局部变量camelCaseplayerInput常量PascalCaseDefaultTimeout异步方法后缀AsyncAskAsync事件OnXxx/XxxChangedOnDialogueCompleted格式要求：4空格缩进，行宽建议120。using排序：System、Unity、第三方、项目。公共API必须写XML注释。复杂逻辑注释“为什么”，而非“做什么”。脚本文件名必须与MonoBehaviour类名一致。5.3MonoBehaviour生命周期规范方法推荐用途Awake获取自身引用、初始化不依赖外部对象OnEnable注册事件、订阅消息Start获取外部引用、初始化依赖Update输入、计时、轻量逻辑FixedUpdate物理计算LateUpdate相机、跟随OnDisable解绑事件、释放订阅OnDestroy释放资源、取消异步禁止事项：在Update中频繁Find、GetComponent、Camera.main。在Update中分配数组、字符串拼接、LINQ。忘记在OnDisable中解绑事件。使用asyncvoid，除非是UI事件处理器且内部有try-catch。5.4事件、协程与异步优先使用C#事件或ScriptableObject事件通道解耦。协程适合Unity生命周期相关逻辑。async/await适合网络请求、文件IO。异步必须支持CancellationToken。UnityAPI只能在主线程调用。网络请求必须设置超时、重试、取消、降级。5.5性能与内存使用Profiler、MemoryProfiler、FrameDebugger定位问题。热路径避免GC：缓存引用、使用对象池、避免装箱。大量对象使用UnityEngine.Pool.ObjectPool<T>。资源加载使用Addressables，避免Resources滥用。UI使用Canvas分级、合批、避免频繁SetActive。移动端注意发热、内存峰值、包体。5.6测试规范EditMode测试纯逻辑、数据结构、工具类。PlayMode测试交互、生命周期、协程。网络与AI接口使用Mock：MockLlmClient。每个AI功能至少包含：正常、超时、错误、审核拒绝、降级。CI中运行格式化、编译、单元测试、静态分析。6.Unity接入大模型实践6.1接入原则客户端只调用自有AI网关，不直连模型厂商。网关保存APIKey，客户端使用用户会话Token。所有请求设置超时、重试、限流、缓存、降级。输出必须经过内容审核与格式校验。记录模型版本、提示词版本、耗时、Token、错误码。6.2LLMClient.cs模板保存为：Assets/_Project/Scripts/AI/LLMClient.csusingSystem;usingSystem.Collections.Generic;usingSystem.Text;usingSystem.Threading;usingSystem.Threading.Tasks;usingUnityEngine;usingUnityEngine.Networking;publicinterfaceILlmClient{Task<string>SendAsync(IReadOnlyList<ChatMessage>messages,CancellationTokenct=default);}[Serializable]publicclassChatMessage{publicstringrole;publicstringcontent;publicChatMessage(){}publicChatMessage(stringrole,stringcontent){this.role=role;this.content=content;}}[Serializable]internalclassChatRequest{publicstringmodel;publicChatMessage[]messages;publicfloattemperature;publicintmax_tokens;}[Serializable]internalclassChatResponse{publicChatChoice[]choices;}[Serializable]internalclassChatChoice{publicChatMessagemessage;}publicclassLLMClient:MonoBehaviour,ILlmClient{[Header("AIGateway")][SerializeField]privatestringendpoint="/v1/chat/completions";[SerializeField]privatestringmodel="gpt-4o-mini";[SerializeField]privatefloattemperature=0.7f;[SerializeField]privateintmaxTokens=512;[SerializeField]privateinttimeoutSeconds=30;[SerializeField]privateintmaxRetries=2;[Header("仅开发环境：生产环境请通过后端网关鉴权")][SerializeField]privatestringauthToken="";publicasyncTask<string>SendAsync(IReadOnlyList<ChatMessage>messages,CancellationTokenct=default){if(messages==null||messages.Count==0)thrownewArgumentException("messagesisempty");varpayload=newChatRequest{model=model,messages=ToArray(messages),temperature=temperature,max_tokens=maxTokens};stringjson=JsonUtility.ToJson(payload);for(intattempt=0;attempt<=maxRetries;attempt++){ct.ThrowIfCancellationRequested();using(varreq=newUnityWebRequest(endpoint,UnityWebRequest.kHttpVerbPOST)){byte[]body=Encoding.UTF8.GetBytes(json);req.uploadHandler=newUploadHandlerRaw(body);req.downloadHandler=newDownloadHandlerBuffer();req.SetRequestHeader("Content-Type","application/json");if(!string.IsNullOrEmpty(authToken))req.SetRequestHeader("Authorization",$"Bearer{authToken}");req.timeout=timeoutSeconds;varop=req.SendWebRequest();while(!op.isDone){if(ct.IsCancellationRequested){req.Abort();ct.ThrowIfCancellationRequested();}awaitTask.Yield();}if(req.result==UnityWebRequest.Result.Success){varres=JsonUtility.FromJson<ChatResponse>(req.downloadHandler.text);if(res?.choices!=null&&res.choices.Length>0&&res.choices[0].message!=null)returnres.choices[0].message.content;thrownewException("LLMresponseformaterror:"+req.downloadHandler.text);}boolretryable=req.responseCode==429||req.responseCode>=500;if(!retryable||attempt>=maxRetries)thrownewException($"LLMrequestfailed:{req.responseCode}{req.error}{req.downloadHandler.text}");awaitTask.Delay(TimeSpan.FromSeconds(Math.Pow(2,attempt)),ct);}}thrownewException("LLMrequestfailedafterretries");}privatestaticChatMessage[]ToArray(IReadOnlyList<ChatMessage>messages){vararr=newChatMessage[messages.Count];for(inti=0;i<messages.Count;i++)arr[i]=messages[i];returnarr;}}6.3NpcDialogueManager.cs模板保存为：Assets/_Project/Scripts/AI/NpcDialogueManager.csusingSystem;usingSystem.Collections.Generic;usingSystem.Threading;usingSystem.Threading.Tasks;usingUnityEngine;publicclassNpcDialogueManager:MonoBehaviour{[SerializeField]privateMonoBehaviourllmClientBehaviour;[SerializeField]privatestringnpcName="村民";[TextArea(3,10)][SerializeField]privatestringpersona="你是一位友善但谨慎的村民。";[TextArea(3,10)][SerializeField]privatestringworldRules="这是一个中世纪奇幻世界，存在魔法但稀缺。";[SerializeField]privateintmaxHistoryMessages=12;privateILlmClient_llmClient;privatereadonlyList<ChatMessage>_history=newList<ChatMessage>();privatevoidAwake(){_llmClient=llmClientBehaviourasILlmClient;if(_llmClient==null)Debug.LogError("NpcDialogueManager:llmClientBehaviour必须实现ILlmClient");}publicasyncTask<string>AskAsync(stringplayerInput,CancellationTokenct=default){if(_llmClient==null)return"（NPC暂时无法回应。）";varmessages=newList<ChatMessage>{newChatMessage("system",BuildSystemPrompt())};intstart=Mathf.Max(0,_history.Count-maxHistoryMessages);for(inti=start;i<_history.Count;i++)messages.Add(_history[i]);messages.Add(newChatMessage("user",playerInput));try{stringreply=await_llmClient.SendAsync(messages,ct);_history.Add(newChatMessage("user",playerInput));_history.Add(newChatMessage("assistant",reply));TrimHistory();returnreply;}catch(OperationCanceledException){return"（对话已取消。）";}catch(Exceptione){Debug.LogWarning($"NPCdialoguefailed:{e.Message}");return"（NPC似乎没有听清，请稍后再试。）";}}privatestringBuildSystemPrompt(){return$"你是游戏《【游戏名】》中的NPC，名字：{npcName}。\n"+$"人设：{persona}\n"+$"世界规则：{worldRules}\n"+"要求：用中文回答；不超过80字；不得脱离角色；不得生成违法违规、色情、暴力或仇恨内容。";}privatevoidTrimHistory(){intmax=maxHistoryMessages*2;if(_history.Count>max)_history.RemoveRange(0,_history.Count-max);}}6.4UI调用示例usingTMPro;usingUnityEngine;publicclassDialogueUI:MonoBehaviour{[SerializeField]privateNpcDialogueManagernpc;[SerializeField]privateTMP_InputFieldinput;[SerializeField]privateTMP_Textoutput;publicasyncvoidOnSend(){if(npc==null||input==null||output==null)return;output.text="……";stringreply=awaitnpc.AskAsync(input.text);output.text=reply;}}6.5快速接入步骤在场景中创建空物体AI，挂载LLMClient。将endpoint修改为你的AI网关地址。创建NPC物体，挂载NpcDialogueManager。将AI物体拖拽到llmClientBehaviour。配置npcName、persona、worldRules。在UI中调用AskAsync。测试正常、超时、断网、审核拒绝、降级。6.6流式、缓存与降级流式响应：推荐WebSocket或SSE，通过网关转发；Unity可使用UnityWebRequest分块读取或WebSocket库。缓存：相同问题、相同NPC、相同上下文可缓存回复，降低延迟与成本。降级：AI不可用时返回预设台词、通用提示或离线对话树。限流：按用户、NPC、场景设置QPS与Token配额。成本：设置max_tokens，压缩历史，使用小模型处理简单问答。7.安全、合规与伦理7.1密钥与网络安全禁止在客户端、Git、日志、配置表中明文存储APIKey。使用AI网关统一鉴权、限流、审计。所有请求使用HTTPS/WSS。对用户输入进行长度限制、类型校验、敏感词过滤。防范提示词注入：系统提示词与玩家输入分离，输出必须校验。7.2隐私与数据保护遵守《个人信息保护法》《数据安全法》及项目所在地法规。收集玩家数据前获得同意，说明用途、范围、保存期限。日志脱敏：不记录手机号、身份证、支付信息、精确位置。支持删除用户数据与撤回同意。未成年人保护：内容分级、防沉迷、家长控制。7.3内容安全输入与输出双审核。敏感词、违法、色情、暴力、仇恨、自伤等内