mirror of https://github.com/GeWuYou/GFramework.git synced 2026-05-07 00:27:16 +08:00

gewuyou e671646a74 fix(ai-first-config): 收口 PR 306 审查遗留项

- 新增 Generator 与 Tooling 的 anyOf 和坏形状回归覆盖，补齐组合关键字与未知 type 拒绝

- 修复 VS Code 配置工具的 object-array 直属项收集与 contains 文案一致性问题

- 更新 README、Game 文档与工具说明，明确 additionalProperties 显式 false 边界与最小接入路径

- 补充 ai-plan 跟踪与 trace，记录 PR 306 open threads 收口结果和验证摘要

2026-04-30 15:22:04 +08:00

4.9 KiB

Raw Blame History

title, description

title	description
API 参考	GFramework 的 API 阅读入口，按模块映射 README、专题页、XML 文档和教程链路。

API 参考

本页聚焦“先看哪个模块入口、再回哪里读 XML 文档”的 API 阅读导航。

最常见的阅读顺序是：

先按模块找到对应栏目入口
再进专题页确认安装、生命周期和推荐接线方式
最后回到源码中的 XML 文档核对具体契约

如果你在阅读 AI-First 配置工作流相关 API，先把 GFramework.Game Runtime 与 GFramework.Game.SourceGenerators 视为正式契约入口，再把 VS Code 配置工具视为辅助层。当前默认采用路径围绕共享 schema 子集展开，其中 additionalProperties: false 表示闭合对象边界（需显式设置为 false）；oneOf / anyOf 在 Runtime / Generator / Tooling 层面会被直接拒绝。更复杂的 shape 应回到 raw YAML 与 schema 设计本体处理。

阅读顺序

安装与选包入口

先读站内入口页：

入门入口：入门指南
安装与选包：安装配置

模块定位入口

按下面的模块映射进入对应入口：

模块族	先看什么	继续深入	XML 文档关注点
`Core` / `Core.Abstractions`	Core 模块	Core 抽象层说明、快速开始	架构入口、生命周期、命令 / 查询 / 事件 / 状态 / 资源 / 日志 / 配置 / 并发契约
`Cqrs` / `Cqrs.Abstractions` / `Cqrs.SourceGenerators`	CQRS 运行时	CQRS Handler Registry 生成器、协程系统	request / notification / handler / pipeline / generated registry / targeted fallback contract
`Game` / `Game.Abstractions` / `Game.SourceGenerators`	Game 模块总览	Game 抽象层说明、配置系统	配置、数据、设置、场景、UI、存储、序列化契约；其中 AI-First 配置工作流的正式支持边界以 Runtime + Generator 共享 schema 子集为准
`Godot` / `Godot.SourceGenerators`	Godot 模块总览	Godot 项目生成器、GetNode 生成器、BindNodeSignal 生成器	节点扩展、场景 / UI 适配、配置 / 存储 / 设置接线、Godot 生成器入口
`Ecs.Arch` / `Ecs.Arch.Abstractions`	ECS 模块总览	Arch ECS 集成、Ecs.Arch 抽象层说明	ECS 模块契约、系统适配、配置对象和运行时装配边界

先看 XML，还是先看教程

先看 XML 文档的情况

你在确认公开类型的约束、线程 / 生命周期语义、参数和返回值契约
你需要区分“抽象层保证了什么”和“默认实现额外提供了什么”
你在做多模块拆分、测试替身或扩展适配层

优先关注这些类型族：

架构 / 模块 / 服务入口
生命周期、注册、路由、工厂、provider 契约
Source Generator 的 attribute、diagnostic 和 generated contract

先看教程和专题页的情况

你要的是最小接入路径，而不是逐个类型展开阅读
你想确认模块组合方式、目录约定和推荐接线顺序
你在做从旧入口迁移到新入口的采用决策

优先入口：

教程概览：教程总览
最佳实践：最佳实践
故障排查：故障排查

如果你阅读的是 AI-First 配置相关 API，请直接把配置系统视为边界说明页：像 additionalProperties: false、oneOf / anyOf rejection 这类采用约束不会由 VS Code 工具或 abstractions 页面单独改写。

共享支撑层怎么看

GFramework.Core.SourceGenerators.Abstractions
GFramework.Godot.SourceGenerators.Abstractions
GFramework.SourceGenerators.Common

这些目录当前不作为独立采用入口；阅读它们时，优先回到所属模块页和 source-generators 栏目，再根据需要下钻到具体源码目录。

*.SourceGenerators.Abstractions
- 主要定义公开 attribute 和最小契约，供对应生成器与消费端项目共享。
GFramework.SourceGenerators.Common
- 主要提供共享生成器基类、通用 diagnostics，以及生成方法冲突等跨模块约束。

使用方式

把本页当成“API 阅读导航”而不是“签名快照”：

先选模块
再进专题页确认采用路径
最后回到代码里的 XML 文档核对具体契约

4.9 KiB Raw Blame History Unescape Escape