AIRI Stage Tamagotchi Godot 引擎 C# 开发方法五层架构、类型驱动契约与性能边界规范【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本篇技术指南以 csharp-development-method.md 为骨架系统讲解proj-airi/stage-tamagotchi-godot引擎内 C# 代码的结构分层与现代化语言特性使用规范。该引擎是 AIRI 项目的桌面端 Godot 舞台运行时sidecar负责 VRM 模型加载、相机视图状态与渲染效果读者阅读本文后可掌握其场景脚本、运行时核心、传输契约、注册发现与工具链五层架构的划分依据以及反射、LINQ、async 三类能力的使用边界并理解文档规则在 StageRoot.cs 等真实源码中的落地方式。适用范围与定位该指南仅适用于engines/stage-tamagotchi-godot这一个引擎目录不是仓库级的 C# 通用标准。AIRI monorepo 中其他包如 Electron 宿主、插件 SDK、各 stage 包有各自的约定本指南不应被挪用为全仓规范。指南定义的适用对象包括Godot 场景脚本Scene Scripts运行时协调器与控制器Runtime Coordinators and Controllers宿主-舞台传输契约Host-Stage Transport Contracts注册与发现代码Registry and Discovery引擎内部的工具与编辑器支持代码Tooling and Editor Support而格式化、命名等次要规则被刻意放在本地 .editorconfig 与 csharp-style.md 中不在本文档内重复定义。也就是说结构方法怎么组织代码与代码风格怎么写每个字符被明确拆分为两份文档前者是本文主体后者是配套的格式化基线。五层架构模型写代码前先分层文档要求在任何实现开始之前先把引擎内的 C# 代码拆分为五层。这是全文的核心骨架约束着每个文件应承担的责任层级职责典型载体1. Scene ScriptGodot 持有的Node/Node3Dpartial 类生命周期入口与场景绑定StageRoot.cs2. Runtime Core纯 C# 运行时逻辑控制器、协调器、状态持有者、服务StageSceneController.cs、视图运行时3. Contract and Transport消息类型、设置快照、ready/fatal/shutdown/状态更新载荷StageEnvelope.cs、StageSceneApplyPayload.cs、StageViewPayloads.cs4. Registry and Discovery描述符、启动期发现、目录与查找表引擎内注册/发现代码5. Tooling and Editor SupportInspector 辅助、导入/导出辅助、调试或编辑器专用数据组装StageDevObservationAdapter.cs等开发辅助文档给出的默认原则是不要默认把这些职责全部塞进单个 Godot 脚本。这与 README 中Godot-owned scene, scripts, and .NET project structure的定位一致——引擎保持 Godot 资产与 .NET 逻辑分离。场景脚本规则保持轻薄的接线层场景脚本应该保持薄。文档明确允许场景脚本承担四类工作Godot 生命周期入口如_Ready节点查找与场景接线node lookup and scene wiring将控制权移交给运行时对象把 Godot 回调桥接进显式的运行时代码。反过来以下内容除非琐碎否则不得直接写进场景脚本传输协议处理、注册表构建、复杂状态迁移、业务/玩法规则、大型数据转换管道。若一个场景脚本同时开始拥有生命周期、运行时状态、协议处理与工具配置就必须拆分。以引擎根节点 StageRoot.cs 为实例可以清晰看到这套规则的落地StageRoot是Node3Dpartial 类它只做接线——在_Ready中解析AvatarRoot与Camera3D节点、构造StageSceneController、StageViewRuntime、StageRenderEffectsRuntime、StageBridge等运行时对象并把事件接好在_Process中仅调用_bridge.Poll()、_viewRuntime?.Process(delta)等委派消息分发的HandleMessage也只是 switch 分发到各控制器方法。协议解析、VRM 导入、视图状态机全部在场景脚本之外符合handing control to runtime objects的定位。运行时核心规则显式优于聪明文档要求将可持久化的运行时逻辑优先放进纯 C# 对象并给出四条偏好用小型协调器small coordinators而非无所不知的大型类用显式状态对象而非隐藏的可变标志位用构造函数或方法注入依赖用清晰的调用流而非隐式控制转移。运行时代码应易于在调试器中追踪显式的地图、状态与控制流优于巧妙的抽象。源码中的 StageSceneController.cs 是典型示例它通过构造函数注入Node3D avatarRoot与VrmAvatarLoader用私有字段_currentAvatar持有显式状态Apply方法先校验Format vrm加载新模型成功后才CommitAvatar新节点先入树旧节点才QueueFree实现先成功再替换的原子语义。文档中的显式状态对象在这段代码里体现为_currentAvatar与各 payload record 类型而不是散落的布尔标志。此外引擎通过 Directory.Build.props 固定了net10.0目标框架与LangVersion 14.0确保同一运行时契约与语言版本避免新 SDK 静默改变语言能力。契约与传输规则先用类型定义边界再围绕类型实现传输跨边界通信必须类型驱动type-driven。文档明确要求对以下内容使用显式类型传输消息、载荷、设置快照、描述符、注册表条目、运行时状态快照。同时明确禁止把Dictionarystring, object?当作默认契约形状跨文件散落的魔法字符串协议匿名对象跨子系统边界传递用注释替代真正的类型定义。规则一句话概括先把边界定义为类型再围绕这些类型实现传输。引擎的 transport 目录scripts/transport是这套规则的直接产物StageEnvelope.cspublic sealed record StageEnvelope(string Type, JsonElement? Payload)即 Electron main 与 Godot sidecar 之间交换的消息信封Type 是稳定消息类型字符串如host.scene.applyPayload 是可选 JSONStageSceneApplyPayload.csStageSceneApplyPayload(ModelId, Format, Name, Path)描述 Electron 物化 VRM 文件后下发的场景输入其中Format在 G1.1 阶段仅接受vrmStageViewPayloads.cs集中定义了视图状态相关的十余个 record——相机姿态StageCameraPoseState、视图快照StageViewState、局部补丁StageCameraPosePatch、请求/应答载荷快照请求、PNG 捕获、渲染调试视图、边缘光开关以及错误载荷。正是因为契约全部是 record 类型StageRoot.cs 才能在HandleMessage里用统一的分支按envelope.Type分发并用共享的JsonSerializerOptionscamelCase、大小写不敏感、忽略空值完成反序列化——消息类型的稳定性直接决定了分发代码的简洁性。反射与 LINQ 策略反射建目录LINQ 塑形查询运行时走显式结构文档对反射和 LINQ 给出了明确的能力边界与心智模型反射用于发现discovery不用于执行execution。允许的用途包括启动期模块发现、属性元数据读取、描述符生成、编辑器/工具支持。禁止用于逐帧逻辑、运行时热路径分发、核心状态机执行、稳态运行时中的重复动态调用。LINQ 用于冷路径查询与数据塑形。允许的用途包括构建注册表、过滤描述符、配置投影、调试/工具视图。禁止在热路径、逐帧循环、重复执行的运行时查询中使用重 LINQ——当显式索引或字典更清晰、更便宜时应优先使用它们。文档给出一句话心智模型反射reflection构建目录catalogueLINQ 塑形与查询目录运行时通过显式结构执行。这条策略与分层模型相辅相成注册与发现层负责建目录契约层负责定义目录条目的类型运行时核心层则直接操作显式状态与调用流。异步边界策略async 只进 I/O 与进程边界文档要求 async 只用于I/O 与进程边界允许的场景包括socket 与传输建立、文件 I/O、宿主侧进程交互、天然异步的启动加载。明确禁止把 async 推进逐帧更新、核心运行时循环、需要保持显式的时序敏感行为。文档特别强调不要用 async 来掩盖生命周期或排序问题。这与引擎的实际架构相呼应Godot 侧使用WebSocketPeer的同步轮询模型StageBridge.cs 在_Process帧循环中调用Poll()拉取消息、SendText发送信封连接与关闭事件通过Opened/MessageReceived/Closed事件暴露——帧循环本身保持同步、显式、可预测异步只发生在进程边界Electron 宿主通过本地 WebSocket 桥接启动命令为godot --path ./engines/stage-tamagotchi-godot -- --airi-ws-urlruntime-url。延迟决策清单不要猜测显式决定文档明确列出若干刻意推迟、不得猜测的项目因为它们会显著影响代码形态可空引用类型nullable reference types的推广策略命名空间策略record的使用边界required成员的使用边界主构造函数primary constructors的使用边界辅助层与场景脚本之间的功能许可边界。当其中某一项变得相关时应当显式决定并写入引擎本地指南而不是从风格工具如.editorconfig、格式化器的行为去反推。配套的 csharp-style.md 也把 Nullable reference types / Namespace strategy / record、required 与主构造函数 / DTO 专属风格 全部列为 Out of Scope两份文档在这些决定由谁来做上保持了一致立场。配套工程化设施格式基线、编辑器配置与验证命令虽然格式规则不在本文主体内但落地时离不开三样配套设施它们都在引擎目录内.editorconfig声明 4 空格缩进、LF 换行、UTF-8、100 列行长上限Allman 大括号System.*using 优先排序私有字段强制_camelCaserequired_prefix _IDE0005未使用 using按 warning 处理。这与 csharp-style.md 中的规则条目一一对应。风格基线Microsoft: Common C# code conventions、Microsoft: .NET code style rule options、Godot: C# style guide三份基线作为基础引擎内部再叠加上述差异项。验证命令改动 C# 文件或.editorconfig后在引擎目录下执行dotnet format --verify-no-changes验证格式无漂移。此外引擎带有独立的验证宿主tests/stage-tamagotchi-godot.tests.csproj 通过ProjectReference引用引擎主项目禁用隐式 using配合仓库根package.json中的pnpm -F proj-airi/stage-tamagotchi-godot build / typecheck / test三个命令保证运行时与验证宿主编译在同一运行时契约net10.0之上。格式与结构的双重校验让上述分层与边界规则可以低成本地持续执行。小结这篇开发方法文档为engines/stage-tamagotchi-godot确立了一套可执行的 C# 工程纪律五层架构先分层再编码场景脚本保持轻薄运行核心显式化跨边界契约一律类型驱动反射与 LINQ 只服务冷路径与发现async 只停留在 I/O 边界未决的策略显式推迟。从 StageRoot.cs 的接线方式、StageSceneController.cs 的依赖注入与原子替换到 transport 目录下一组组 record 契约这套规范已经深度渗透进引擎现有代码对任何新增或重构该引擎 C# 代码的开发者而言它既是架构地图也是评审清单。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
AIRI Stage Tamagotchi Godot 引擎 C 开发方法：五层架构、类型驱动契约与性能边界规范
AIRI Stage Tamagotchi Godot 引擎 C# 开发方法五层架构、类型驱动契约与性能边界规范【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本篇技术指南以 csharp-development-method.md 为骨架系统讲解proj-airi/stage-tamagotchi-godot引擎内 C# 代码的结构分层与现代化语言特性使用规范。该引擎是 AIRI 项目的桌面端 Godot 舞台运行时sidecar负责 VRM 模型加载、相机视图状态与渲染效果读者阅读本文后可掌握其场景脚本、运行时核心、传输契约、注册发现与工具链五层架构的划分依据以及反射、LINQ、async 三类能力的使用边界并理解文档规则在 StageRoot.cs 等真实源码中的落地方式。适用范围与定位该指南仅适用于engines/stage-tamagotchi-godot这一个引擎目录不是仓库级的 C# 通用标准。AIRI monorepo 中其他包如 Electron 宿主、插件 SDK、各 stage 包有各自的约定本指南不应被挪用为全仓规范。指南定义的适用对象包括Godot 场景脚本Scene Scripts运行时协调器与控制器Runtime Coordinators and Controllers宿主-舞台传输契约Host-Stage Transport Contracts注册与发现代码Registry and Discovery引擎内部的工具与编辑器支持代码Tooling and Editor Support而格式化、命名等次要规则被刻意放在本地 .editorconfig 与 csharp-style.md 中不在本文档内重复定义。也就是说结构方法怎么组织代码与代码风格怎么写每个字符被明确拆分为两份文档前者是本文主体后者是配套的格式化基线。五层架构模型写代码前先分层文档要求在任何实现开始之前先把引擎内的 C# 代码拆分为五层。这是全文的核心骨架约束着每个文件应承担的责任层级职责典型载体1. Scene ScriptGodot 持有的Node/Node3Dpartial 类生命周期入口与场景绑定StageRoot.cs2. Runtime Core纯 C# 运行时逻辑控制器、协调器、状态持有者、服务StageSceneController.cs、视图运行时3. Contract and Transport消息类型、设置快照、ready/fatal/shutdown/状态更新载荷StageEnvelope.cs、StageSceneApplyPayload.cs、StageViewPayloads.cs4. Registry and Discovery描述符、启动期发现、目录与查找表引擎内注册/发现代码5. Tooling and Editor SupportInspector 辅助、导入/导出辅助、调试或编辑器专用数据组装StageDevObservationAdapter.cs等开发辅助文档给出的默认原则是不要默认把这些职责全部塞进单个 Godot 脚本。这与 README 中Godot-owned scene, scripts, and .NET project structure的定位一致——引擎保持 Godot 资产与 .NET 逻辑分离。场景脚本规则保持轻薄的接线层场景脚本应该保持薄。文档明确允许场景脚本承担四类工作Godot 生命周期入口如_Ready节点查找与场景接线node lookup and scene wiring将控制权移交给运行时对象把 Godot 回调桥接进显式的运行时代码。反过来以下内容除非琐碎否则不得直接写进场景脚本传输协议处理、注册表构建、复杂状态迁移、业务/玩法规则、大型数据转换管道。若一个场景脚本同时开始拥有生命周期、运行时状态、协议处理与工具配置就必须拆分。以引擎根节点 StageRoot.cs 为实例可以清晰看到这套规则的落地StageRoot是Node3Dpartial 类它只做接线——在_Ready中解析AvatarRoot与Camera3D节点、构造StageSceneController、StageViewRuntime、StageRenderEffectsRuntime、StageBridge等运行时对象并把事件接好在_Process中仅调用_bridge.Poll()、_viewRuntime?.Process(delta)等委派消息分发的HandleMessage也只是 switch 分发到各控制器方法。协议解析、VRM 导入、视图状态机全部在场景脚本之外符合handing control to runtime objects的定位。运行时核心规则显式优于聪明文档要求将可持久化的运行时逻辑优先放进纯 C# 对象并给出四条偏好用小型协调器small coordinators而非无所不知的大型类用显式状态对象而非隐藏的可变标志位用构造函数或方法注入依赖用清晰的调用流而非隐式控制转移。运行时代码应易于在调试器中追踪显式的地图、状态与控制流优于巧妙的抽象。源码中的 StageSceneController.cs 是典型示例它通过构造函数注入Node3D avatarRoot与VrmAvatarLoader用私有字段_currentAvatar持有显式状态Apply方法先校验Format vrm加载新模型成功后才CommitAvatar新节点先入树旧节点才QueueFree实现先成功再替换的原子语义。文档中的显式状态对象在这段代码里体现为_currentAvatar与各 payload record 类型而不是散落的布尔标志。此外引擎通过 Directory.Build.props 固定了net10.0目标框架与LangVersion 14.0确保同一运行时契约与语言版本避免新 SDK 静默改变语言能力。契约与传输规则先用类型定义边界再围绕类型实现传输跨边界通信必须类型驱动type-driven。文档明确要求对以下内容使用显式类型传输消息、载荷、设置快照、描述符、注册表条目、运行时状态快照。同时明确禁止把Dictionarystring, object?当作默认契约形状跨文件散落的魔法字符串协议匿名对象跨子系统边界传递用注释替代真正的类型定义。规则一句话概括先把边界定义为类型再围绕这些类型实现传输。引擎的 transport 目录scripts/transport是这套规则的直接产物StageEnvelope.cspublic sealed record StageEnvelope(string Type, JsonElement? Payload)即 Electron main 与 Godot sidecar 之间交换的消息信封Type 是稳定消息类型字符串如host.scene.applyPayload 是可选 JSONStageSceneApplyPayload.csStageSceneApplyPayload(ModelId, Format, Name, Path)描述 Electron 物化 VRM 文件后下发的场景输入其中Format在 G1.1 阶段仅接受vrmStageViewPayloads.cs集中定义了视图状态相关的十余个 record——相机姿态StageCameraPoseState、视图快照StageViewState、局部补丁StageCameraPosePatch、请求/应答载荷快照请求、PNG 捕获、渲染调试视图、边缘光开关以及错误载荷。正是因为契约全部是 record 类型StageRoot.cs 才能在HandleMessage里用统一的分支按envelope.Type分发并用共享的JsonSerializerOptionscamelCase、大小写不敏感、忽略空值完成反序列化——消息类型的稳定性直接决定了分发代码的简洁性。反射与 LINQ 策略反射建目录LINQ 塑形查询运行时走显式结构文档对反射和 LINQ 给出了明确的能力边界与心智模型反射用于发现discovery不用于执行execution。允许的用途包括启动期模块发现、属性元数据读取、描述符生成、编辑器/工具支持。禁止用于逐帧逻辑、运行时热路径分发、核心状态机执行、稳态运行时中的重复动态调用。LINQ 用于冷路径查询与数据塑形。允许的用途包括构建注册表、过滤描述符、配置投影、调试/工具视图。禁止在热路径、逐帧循环、重复执行的运行时查询中使用重 LINQ——当显式索引或字典更清晰、更便宜时应优先使用它们。文档给出一句话心智模型反射reflection构建目录catalogueLINQ 塑形与查询目录运行时通过显式结构执行。这条策略与分层模型相辅相成注册与发现层负责建目录契约层负责定义目录条目的类型运行时核心层则直接操作显式状态与调用流。异步边界策略async 只进 I/O 与进程边界文档要求 async 只用于I/O 与进程边界允许的场景包括socket 与传输建立、文件 I/O、宿主侧进程交互、天然异步的启动加载。明确禁止把 async 推进逐帧更新、核心运行时循环、需要保持显式的时序敏感行为。文档特别强调不要用 async 来掩盖生命周期或排序问题。这与引擎的实际架构相呼应Godot 侧使用WebSocketPeer的同步轮询模型StageBridge.cs 在_Process帧循环中调用Poll()拉取消息、SendText发送信封连接与关闭事件通过Opened/MessageReceived/Closed事件暴露——帧循环本身保持同步、显式、可预测异步只发生在进程边界Electron 宿主通过本地 WebSocket 桥接启动命令为godot --path ./engines/stage-tamagotchi-godot -- --airi-ws-urlruntime-url。延迟决策清单不要猜测显式决定文档明确列出若干刻意推迟、不得猜测的项目因为它们会显著影响代码形态可空引用类型nullable reference types的推广策略命名空间策略record的使用边界required成员的使用边界主构造函数primary constructors的使用边界辅助层与场景脚本之间的功能许可边界。当其中某一项变得相关时应当显式决定并写入引擎本地指南而不是从风格工具如.editorconfig、格式化器的行为去反推。配套的 csharp-style.md 也把 Nullable reference types / Namespace strategy / record、required 与主构造函数 / DTO 专属风格 全部列为 Out of Scope两份文档在这些决定由谁来做上保持了一致立场。配套工程化设施格式基线、编辑器配置与验证命令虽然格式规则不在本文主体内但落地时离不开三样配套设施它们都在引擎目录内.editorconfig声明 4 空格缩进、LF 换行、UTF-8、100 列行长上限Allman 大括号System.*using 优先排序私有字段强制_camelCaserequired_prefix _IDE0005未使用 using按 warning 处理。这与 csharp-style.md 中的规则条目一一对应。风格基线Microsoft: Common C# code conventions、Microsoft: .NET code style rule options、Godot: C# style guide三份基线作为基础引擎内部再叠加上述差异项。验证命令改动 C# 文件或.editorconfig后在引擎目录下执行dotnet format --verify-no-changes验证格式无漂移。此外引擎带有独立的验证宿主tests/stage-tamagotchi-godot.tests.csproj 通过ProjectReference引用引擎主项目禁用隐式 using配合仓库根package.json中的pnpm -F proj-airi/stage-tamagotchi-godot build / typecheck / test三个命令保证运行时与验证宿主编译在同一运行时契约net10.0之上。格式与结构的双重校验让上述分层与边界规则可以低成本地持续执行。小结这篇开发方法文档为engines/stage-tamagotchi-godot确立了一套可执行的 C# 工程纪律五层架构先分层再编码场景脚本保持轻薄运行核心显式化跨边界契约一律类型驱动反射与 LINQ 只服务冷路径与发现async 只停留在 I/O 边界未决的策略显式推迟。从 StageRoot.cs 的接线方式、StageSceneController.cs 的依赖注入与原子替换到 transport 目录下一组组 record 契约这套规范已经深度渗透进引擎现有代码对任何新增或重构该引擎 C# 代码的开发者而言它既是架构地图也是评审清单。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
