docs: correct ONI tutorial metadata and examples

修正 ONI Mod 教程元数据、示例和文档质量问题

Author: ChiYuKe

.vitepress/config.mts

@@ -47,8 +47,8 @@ export default defineConfig({
           items: [
             { text: 'C# 基础与补丁语法', link: '/csharp-basics' },
             { text: 'Mod 结构', link: '/mod-structure' },
+            { text: '完整开发路线', link: '/mod-development-guide' },
             { text: '第一个 Mod', link: '/first-mod-tutorial' },
-            { text: 'StorageNetwork 制作案例', link: '/storage-network-tutorial' },
             { text: 'Unity 资源使用', link: '/resource-unity' }
           ]
         },
@@ -133,7 +133,7 @@ export default defineConfig({
       owner: 'ChiYuKe',
       repo: 'ONIModTutorial',
       branch: 'main',
-      maxEntries: 8
+      maxEntries: 5
     },
     search: {
       provider: 'local'

content/buildings.md

@@ -6,7 +6,7 @@ lastVerified: 2026-07-15
 ---
 
 ::: info 验证环境
-本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。
+本页示例已使用 Build 740622 对应的本机 Managed DLL 完成编译检查；尚未在游戏内完成运行验证。
 :::
 
 # 新增建筑
@@ -32,6 +32,17 @@ Building/
 
 `BuildingConfig.cs` 管建筑本体，`Mod.cs` 负责注册入口和科技解锁，`STRINGS.cs` 放名称和描述。
 
+## 动手顺序
+
+第一次做建筑时，按这个顺序来：
+
+1. 先用原版动画和一个 `1 × 1` 建筑确认配置能编译。
+2. 注册建筑并放进建造菜单。
+3. 加入 `Operational`、`Storage` 或 `EnergyConsumer` 等组件。
+4. 最后再换自己的动画、端口和自定义逻辑。
+
+每次只加一种功能。建筑不出现时查注册，建筑能出现但不能工作时查组件，动画空白时查资源目录，不要同时改三处。
+
 ## 建筑配置
 
 新增建筑需要继承当前 DLL 中的 `IBuildingConfig` 基类。最少要实现三个阶段：
@@ -68,6 +79,8 @@ Building/
 
 `"Base"` 是建造菜单分类，`"BasicRefinement"` 是科技 ID。想放到别的分类或科技里，可以先找一个原版建筑，看看它所在的分类和解锁科技，再照着填。
 
+如果建筑只需要在已有科技中解锁，直接修改 `unlockedItemIDs` 就够了。不要为了放一个建筑，先去创建新的科技节点；当前科技树 API 的旧示例和新 DLL 并不一致。
+
 ## 本地化文本
 
 建筑菜单需要名称、描述和效果：

content/items.md

@@ -6,7 +6,7 @@ lastVerified: 2026-07-15
 ---
 
 ::: info 验证环境
-本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。
+本页示例已使用 Build 740622 对应的本机 Managed DLL 完成编译检查；尚未在游戏内完成运行验证。
 :::
 
 # 新增物品与食物
@@ -33,6 +33,18 @@ ItemAndFood/
 
 示例项目复用了游戏内已有的 `squirrel_kanim` 动画，因此不需要额外提交动画资源。发布自己的实体时，应把动画和其他资源一起复制到 Mod 输出目录。
 
+## 推荐的实现顺序
+
+先做普通物品，再扩展成食物：
+
+1. 给物品确定唯一 ID 和默认文本。
+2. 用 `CreateLooseEntity()` 创建能掉落、能拾取的实体。
+3. 在调试菜单中生成它，确认动画、质量和储存标签正确。
+4. 再用 `ExtendEntityToFood()` 增加食物数据。
+5. 最后接入配方和本地化文件。
+
+物品能生成但配方找不到，通常不是实体配置的问题，而是配方中的输入、输出 Tag 没有分别匹配对应实体的 `PrefabTag`。先把两个问题分开测试。
+
 
 ## 基础物品
 
@@ -49,7 +61,9 @@ ItemAndFood/
 - `SimHashes.Creature`：实体的默认元素。很多非材料类掉落物都会先用它。
 - `GameTags.IndustrialIngredient`：决定它能被哪些储存、配方或建筑识别。
 
-`GetDlcIds()` 使用当前 DLL 提供的 `DlcManager.RELEASED_VERSIONS`，避免在教程中维护会过期的 DLC 数组。若内容只适用于特定 DLC，应按当前 DLL 中的限制接口或构造函数声明限制。
+示例不声明 DLC 限制，因此不实现 `GetDlcIds()`。如果内容只适用于特定 DLC，应使用当前 DLL 的 `IHasDlcRestrictions` 接口声明 `GetRequiredDlcIds()` 或 `GetForbiddenDlcIds()`。
+
+示例里的 `ItemConfig` 和 `FoodConfig` 是两个独立的 `IEntityConfig`。修改其中一个时，不要忘记同步 `STRINGS.cs` 和 `.csproj` 的 `<Compile Include>`。
 
 ## 自定义组件
 
@@ -89,6 +103,5 @@ Mod 入口和统一的本地化初始化流程见 `examples/ItemAndFood/Mod.cs`
 - `.csproj` 里有没有把新增 `.cs` 文件加进 `<Compile Include="..." />`。
 - `ID` 有没有和别的实体重复。
 - 动画文件名和动画状态名是不是存在。
-- `ModEffects.RegisterAll(__instance)` 有没有在 `Db.Initialize` 后执行。
 
 能生成食物以后，让复制人吃掉它，再看复制人属性面板里有没有“吃得很开心”这个效果。

content/localization.md

@@ -6,7 +6,7 @@ lastVerified: 2026-07-15
 ---
 
 ::: info 验证环境
-本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。
+本页示例已使用 Build 740622 对应的本机 Managed DLL 完成编译检查；尚未在游戏内完成运行验证。
 :::
 
 # 翻译文本与本地化

content/mod-packaging.md

@@ -10,7 +10,7 @@ lastVerified: 2026-07-15
 本章说明如何把编译结果、标准描述文件、兼容性元数据和资源整理成可测试、可发布的 Mod。
 
 ::: info 验证环境
-本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。
+本页内容已按 Build 740622 对应的本机 Managed DLL 和项目配置检查；尚未在游戏内完成运行验证。
 :::
 
 ## 最终目录结构

content/recipes.md

@@ -6,7 +6,7 @@ lastVerified: 2026-07-15
 ---
 
 ::: info 验证环境
-本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。
+本页示例已使用 Build 740622 对应的本机 Managed DLL 完成编译检查；尚未在游戏内完成运行验证。
 :::
 
 # 配方系统
@@ -19,7 +19,7 @@ lastVerified: 2026-07-15
 
 配方不是挂到某个特定建筑上，而是声明一个 `fabricators` 列表。任何 `ComplexFabricator` 组件在初始化时会扫描所有配方，把自己的 `PrefabTag` 和配方的 `fabricators` 列表比对，匹配上了就显示。
 
-理解这一点很重要：**配方和建筑是完全解耦的**。你可以做一个新配方，让它被所有原版烹饪台识别，只要把 `"CookingStation"` 加进 `fabricators`。
+理解这一点很重要：配方不会直接引用建筑类型，而是通过 `fabricators` Tag 与建筑的 `PrefabTag` 间接绑定。你可以做一个新配方，让它被所有原版烹饪台识别，只要把 `"CookingStation"` 加进 `fabricators`。
 
 ## 最简配方
 
@@ -85,9 +85,22 @@ new ComplexRecipe.RecipeElement(
 
 如果不想 patch `ConfigureRecipes`，也可以在 `Db.Initialize` 后注册。只要在 `ComplexRecipeManager.PostProcess()` 之前构造了 `ComplexRecipe`，配方就会被识别。
 
+## 实际开发顺序
+
+做自己的配方时，可以按下面的顺序排查：
+
+1. 先用原版输入和输出验证配方注册时机。
+2. 确认 `fabricators` Tag 与目标建筑的 `PrefabTag` 一致。
+3. 再替换成自己的物品或食物 ID。
+4. 最后调整数量、时间、温度和排序。
+
+配方出现在工艺台，说明注册和 Tag 基本正确；原料消耗后没有产物，继续查结果 Tag 对应的实体是否已注册，以及输出储存是否能接受它。
+
+当前可编译的最小项目是 `examples/Recipe/`。它只演示配方注册，不负责创建新的食物实体，所以不要把它误当成“新增食物”的完整项目。
+
 ## 自定义制造建筑
 
-如果你做了自己的制造建筑并想支持配方，建筑上需要挂 `ComplexFabricator` 组件：
+如果你做了自己的制造建筑并想支持配方，建筑上需要挂 `ComplexFabricator` 组件。下面只演示配方扫描所需的核心配置，不是一个完整可运行的制造建筑；实际项目还需要根据建筑类型配置对应的工作、存储和动画组件：
 
 ```csharp
 public override void ConfigureBuildingTemplate(GameObject go, Tag prefabTag)
@@ -99,7 +112,7 @@ public override void ConfigureBuildingTemplate(GameObject go, Tag prefabTag)
 }
 ```
 
-配方的 `fabricators` 里写上这个建筑的 `PrefabTag` 即可。`ComplexFabricator.GetRecipes()` 会自动扫描所有匹配的配方。
+配方的 `fabricators` 里写上这个建筑的 `PrefabTag` 后，`ComplexFabricator.GetRecipes()` 才会扫描到匹配的配方。
 
 ## 排序和分类
 
@@ -110,7 +123,7 @@ recipe.sortOrder = 10;           // 数字越小越靠前
 recipe.recipeCategoryID = "...";  // 构造函数自动生成，也可以手动改
 ```
 
-`ComplexRecipeManager.MakeRecipeID()` 生成的 recipe ID 格式是 `"FabricatorID_InputHash_OutputHash"`，用来保证同一建筑同一输入输出的配方 ID 不变。
+`ComplexRecipeManager.MakeRecipeID()` 会根据制造建筑 ID、每个输入 Tag 和每个输出 Tag 拼接 recipe ID。不要依赖具体字符串格式；在当前 DLL 中，同一组参数会得到相同的 ID。
 
 ## DLC 限制
 

content/research.md

@@ -6,7 +6,7 @@ lastVerified: 2026-07-15
 ---
 
 ::: info 验证环境
-本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。
+本页示例已使用 Build 740622 对应的本机 Managed DLL 完成编译检查；尚未在游戏内完成运行验证。
 :::
 
 # 科技树
@@ -25,6 +25,18 @@ lastVerified: 2026-07-15
 
 `TryGet` 在科技 ID 写错时返回 `null`，比直接调用 `Get` 更容易排查。示例应在新档中确认建筑出现在目标科技的解锁项里。
 
+## 和内容注册配合
+
+科技解锁应该放在内容注册之后处理：
+
+```text
+创建建筑/物品 → 注册内容 ID → 找到已有 Tech → 加入 unlockedItemIDs
+```
+
+如果只写科技补丁，却没有对应的建筑或物品，研究界面可能有一项空解锁；如果只注册内容而没有科技补丁，它通常会直接出现在调试菜单，但不会出现在研究树中。
+
+建议把注册和解锁拆成两个补丁，出了问题可以分别看日志。`examples/Building/Mod.cs` 展示了建筑注册和科技解锁，`examples/ResearchExistingTech/Mod.cs` 只保留科技部分，适合对照阅读。
+
 常用原版科技 ID：
 
 | 科技 ID | 中文名 |

csharp-basics-reference.md

@@ -7,7 +7,7 @@ lastVerified: 2026-07-15
 ---
 
 ::: info 验证环境
-本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。
+本页内容已按 Build 740622 对应的本机 Managed DLL 和项目配置检查；尚未在游戏内完成运行验证。
 :::
 
 <a href="javascript:history.back()" class="back-button">

csharp-basics.md

@@ -6,7 +6,7 @@ lastVerified: 2026-07-15
 ---
 
 ::: info 验证环境
-本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。
+本页内容已按 Build 740622 对应的本机 Managed DLL 和项目配置检查；尚未在游戏内完成运行验证。
 :::
 
 # C# 开发基础（ONI Mod 专用）

development-environment.md

@@ -6,7 +6,7 @@ lastVerified: 2026-07-15
 ---
 
 ::: info 验证环境
-本页已在游戏 Build 740622、.NET Standard 2.1、Mod API 2 下验证。
+本页内容已按 Build 740622 对应的本机 Managed DLL 和项目配置检查；尚未在游戏内完成运行验证。
 :::
 
 # 开发环境搭建