mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
docs(tutorials): 重写 Godot 集成教程
- 重写 Godot 集成教程，按当前源码与 CoreGrid 采用路径收口 project.godot、GetNode 与 BindNodeSignal 的接线说明 - 更新 tutorials 入口摘要与 documentation-governance-and-refresh 跟踪，记录 RP-013、验证结果和下一恢复点
This commit is contained in:
GeWuYou
parent
aec1931c74
commit
a77f79b3e2
@ -7,19 +7,19 @@
|
||||
|
||||
## 当前恢复点
|
||||
|
||||
- 恢复点编号：`DOCUMENTATION-GOVERNANCE-REFRESH-RP-012`
|
||||
- 恢复点编号：`DOCUMENTATION-GOVERNANCE-REFRESH-RP-013`
|
||||
- 当前阶段：`Phase 3`
|
||||
- 当前焦点：
|
||||
- 已建立统一公开 skill：`.agents/skills/gframework-doc-refresh/`
|
||||
- 文档重构入口已从“按 guide/tutorial/api 类型拆 skill”收口为“按源码模块驱动文档刷新”
|
||||
- PR #268 的当前未解决 review 线程已进入收口：Scene/UI 标题层级修正、共享脚本 review 修复、`gframework-pr-review` 多 AI reviewer 支持补齐
|
||||
- `Godot.SourceGenerators` 的 4 个高风险专题页已按当前实现重写，下一轮转入 tutorial 收口与 PR thread 收口
|
||||
- `docs/zh-CN/tutorials/godot-integration.md` 已按当前实现重写，教程入口不再复刻旧 Godot API 叙述
|
||||
- `docs/zh-CN/godot/index.md` 与 `docs/zh-CN/godot/architecture.md` 仍保留同类旧写法，成为下一轮高优先级收口对象
|
||||
|
||||
## 当前状态摘要
|
||||
|
||||
- 文档治理规则已收口到仓库规范，README、站点入口与采用链路不再依赖旧文档自证
|
||||
- 高优先级模块入口与 `core` 关键专题页已回到可作为默认导航入口的状态，本轮计划中的 `core` 剩余高风险页面已完成收口
|
||||
- 当前主题仍是 active topic，因为 `source-generators` 栏目下的 Godot 相关页面仍可能包含与实现漂移的旧内容，且统一 skill 还需要在该场景上继续落地使用
|
||||
- 高优先级模块入口、`core` 关键专题页与 `tutorials/godot-integration.md` 已回到“以源码 / 测试 / README 为准”的状态
|
||||
- 当前主题仍是 active topic，因为 `docs/zh-CN/godot/` 栏目入口和架构页仍有旧 API / 旧接入路径叙述，Godot 文档链路尚未完全收口
|
||||
|
||||
## 当前活跃事实
|
||||
|
||||
@ -65,6 +65,9 @@
|
||||
明确当前不会自动生成 `_Ready()` / `_ExitTree()`
|
||||
- `docs/zh-CN/source-generators/auto-register-exported-collections-generator.md` 已补齐 frontmatter，并改成“成员形状、registry 匹配规则、null-skip 行为、编译期诊断与 CoreGrid 真实采用路径”的结构，
|
||||
明确生成器依赖的是实例可读集合成员与可读 registry 成员，不要求成员必须带 `[Export]`
|
||||
- `docs/zh-CN/tutorials/godot-integration.md` 已改成“包关系、`project.godot` 接线、`[GetNode]` / `[BindNodeSignal]` 协作顺序、运行时扩展边界、迁移提醒”的结构，
|
||||
不再把 `GetNodeX`、`CreateSignalBuilder`、`AbstractGodotModule` 默认化叙述为当前推荐路径
|
||||
- `docs/zh-CN/tutorials/index.md` 中 Godot 教程入口摘要已同步改成“项目级配置 + 生成器协作 + 生命周期边界”，不再继续宣传对象池 / 性能优化式旧范围
|
||||
- `.agents/skills/gframework-doc-refresh/SKILL.md` 已改成标准 YAML frontmatter skill，并明确支持模块输入、证据顺序、输出优先级与验证步骤
|
||||
- `.agents/skills/gframework-doc-refresh/SKILL.md` 的 `description` 已加引号，修复 `Recommended command:` 中冒号导致的
|
||||
invalid YAML skill 加载警告
|
||||
@ -85,9 +88,10 @@
|
||||
`godot-project-generator.md`、`get-node-generator.md`、`bind-node-signal-generator.md` 与 `auto-register-exported-collections-generator.md`
|
||||
已完成收口；
|
||||
继续按源码、测试、`*.csproj` 与 `ai-libs/` 下已验证参考实现核对剩余 Godot 相关页面，不把旧文档当事实来源
|
||||
- 教程失真回流风险：`docs/zh-CN/tutorials/godot-integration.md` 仍保留旧 API 与旧模块叙述，可能把已清理掉的旧说法重新带回专题页
|
||||
- 缓解措施：本轮已确认 `GetNodeX`、`AbstractGodotModule`、`InstallGodotModule` 与 `GFramework.Godot.Pool` 等旧引用仍存在；
|
||||
下一轮优先按当前 `GFramework.Godot` / `Godot.SourceGenerators` 实现重写或拆分该教程
|
||||
- Godot 栏目入口失真风险：`docs/zh-CN/godot/index.md` 与 `docs/zh-CN/godot/architecture.md` 仍保留 `GetNodeX`、
|
||||
`CreateSignalBuilder`、`InstallGodotModule(...).Wait()` 等旧叙述，可能覆盖新教程的采用路径
|
||||
- 缓解措施：本轮已完成 tutorial 收口；下一轮优先按当前 `GFramework.Godot` / `GFramework.Godot.SourceGenerators` /
|
||||
`ai-libs/CoreGrid` 的真实采用路径重写 `godot/index.md`，并评估 `godot/architecture.md` 的最小收口范围
|
||||
- 采用路径误导风险：根聚合包与模块边界若再次被写错，会继续误导消费者的包选择
|
||||
- 缓解措施：保持“源码与包关系优先”的证据顺序，改动采用说明时同步核对包依赖与生成器 wiring
|
||||
- 模块映射不全风险：统一 skill 若遗漏模块别名、测试项目或 docs 栏目映射，会让后续扫描阶段直接失焦
|
||||
@ -132,10 +136,12 @@
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/get-node-generator.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/bind-node-signal-generator.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/auto-register-exported-collections-generator.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md`
|
||||
- `rg -n "GetNodeX|CreateSignalBuilder|GodotGameArchitecture|AbstractGodotModule|InstallGodotModule\(|GFramework\.Godot\.Pool" docs/zh-CN/godot docs/zh-CN/tutorials -S`
|
||||
- `cd docs && bun run build`
|
||||
|
||||
## 下一步
|
||||
|
||||
1. 优先重写或拆分 `docs/zh-CN/tutorials/godot-integration.md`，先移除 `GetNodeX`、`AbstractGodotModule`、`InstallGodotModule` 等旧 API 叙述
|
||||
2. 下一次推送后先重新执行 `$gframework-pr-review`，确认 PR #268 的 CodeRabbit / Greptile open thread 是否按预期收敛
|
||||
3. 若 tutorial 收口后 active 内容再次变长，把本阶段已完成的 Godot 生成器专题历史迁入 topic `archive/`
|
||||
1. 优先重写 `docs/zh-CN/godot/index.md`，清掉 `GetNodeX`、`CreateSignalBuilder`、`InstallGodotModule(...)` 默认化叙述
|
||||
2. 视 `godot/index.md` 收口结果，决定是否同步压缩 `docs/zh-CN/godot/architecture.md`，避免两页继续互相复制旧接入路径
|
||||
3. 下一次推送后重新执行 `$gframework-pr-review`，确认 PR #268 的 CodeRabbit / Greptile open thread 是否按预期收敛
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
## 2026-04-22
|
||||
|
||||
### 当前恢复点：RP-012
|
||||
### 当前恢复点：RP-013
|
||||
|
||||
- 本轮从 PR #268 的最新 review 数据恢复，未发现失败检查；CTRF 报告显示 2139 个测试全部通过
|
||||
- 本轮复核确认当前 PR 的 latest-head open thread 同时来自 `coderabbitai[bot]` 与 `greptile-apps[bot]`
|
||||
@ -23,8 +23,11 @@
|
||||
- 新页面统一收口到“包关系、最小接入路径、真实生成语义、生命周期边界、诊断约束”，不再沿用旧教程式长篇 API 罗列
|
||||
- 本轮额外复核了 `ai-libs/CoreGrid` 的真实采用方式，确认 `[GetNode]` / `[BindNodeSignal]` 组合使用时应先注入节点再绑定事件
|
||||
- 本轮继续收口 `auto-register-exported-collections-generator.md`，补齐 frontmatter，并把“导出集合”纠正为“实例可读集合成员 + registry 成员 + 单参数实例方法”的真实契约
|
||||
- 本轮复核 `docs/zh-CN/tutorials/godot-integration.md`，确认其中仍残留 `GetNodeX`、`AbstractGodotModule`、`InstallGodotModule`、
|
||||
`GFramework.Godot.Pool` 等旧 API / 旧模块叙述，tutorial 已成为下一轮高优先级清理对象
|
||||
- 本轮已重写 `docs/zh-CN/tutorials/godot-integration.md`，把内容收口为“包关系、`project.godot` 接线、`[GetNode]` /
|
||||
`[BindNodeSignal]` 协作顺序、运行时扩展边界、迁移提醒”，不再把旧 Godot API 列表当事实来源
|
||||
- `docs/zh-CN/tutorials/index.md` 的 Godot 教程入口摘要已同步改成当前采用路径，避免入口页继续把教程描述成对象池 / 性能优化总览
|
||||
- 本轮检索确认 Godot 栏目仍有下一批高风险页面：`docs/zh-CN/godot/index.md` 与 `docs/zh-CN/godot/architecture.md` 还保留
|
||||
`GetNodeX`、`CreateSignalBuilder`、`InstallGodotModule(...).Wait()` 等旧叙述，应作为 tutorial 之后的下一轮收口对象
|
||||
|
||||
### 当前决策
|
||||
|
||||
@ -35,7 +38,8 @@
|
||||
- `Godot.SourceGenerators` 专题页继续采用“源码 / 测试 / README 优先，`ai-libs/` 只补消费者 wiring”的证据顺序
|
||||
- `BindNodeSignal` 页面明确记录“当前不自动生成 `_Ready()` / `_ExitTree()`”，避免继续把它写成自动生命周期织入器
|
||||
- `auto-register-exported-collections` 页面明确区分“运行时 null 时跳过注册”和“配置错误时编译期报错”，避免旧文档把两类边界混为一谈
|
||||
- `godot-integration.md` 不再适合作为当前 Godot 采用路径的事实来源；后续只能把它当待修输出，而不是事实输入
|
||||
- `godot-integration.md` 已重新成为可用的采用路径入口；后续 Godot 文档收口应优先处理 `godot/index.md` 和 `godot/architecture.md`
|
||||
- `docs/zh-CN/godot/index.md` 若继续保留旧写法，会重新把 tutorial 已清掉的旧接入路径带回导航入口，因此优先级高于继续扩展新教程
|
||||
|
||||
### 验证
|
||||
|
||||
@ -51,10 +55,12 @@
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/bind-node-signal-generator.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/source-generators/auto-register-exported-collections-generator.md`
|
||||
- `cd docs && bun run build`
|
||||
- `rg -n "GetNodeX|AbstractGodotModule|InstallGodotModule|GodotGameArchitecture|GFramework\\.Godot\\.Pool" docs/zh-CN/tutorials/godot-integration.md`
|
||||
- `bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/godot-integration.md`
|
||||
- `cd docs && bun run build`
|
||||
- `rg -n "GetNodeX|CreateSignalBuilder|GodotGameArchitecture|AbstractGodotModule|InstallGodotModule\(|GFramework\\.Godot\\.Pool" docs/zh-CN/godot docs/zh-CN/tutorials -S`
|
||||
|
||||
### 下一步
|
||||
|
||||
1. 下一次推送后重新执行 `$gframework-pr-review`，确认 PR #268 的 CodeRabbit / Greptile open thread 是否关闭或减少
|
||||
2. 继续使用 `gframework-doc-refresh` 对 `Godot.SourceGenerators` 做真实模块扫描
|
||||
3. 优先重写或拆分 `tutorials/godot-integration.md`，先清掉已确认失真的 Godot 旧 API 与旧模块示例
|
||||
1. 优先重写 `docs/zh-CN/godot/index.md`，清掉 `GetNodeX`、`CreateSignalBuilder`、`InstallGodotModule(...)` 默认化叙述
|
||||
2. 视 `godot/index.md` 收口结果，决定是否同步压缩 `docs/zh-CN/godot/architecture.md`
|
||||
3. 下一次推送后重新执行 `$gframework-pr-review`，确认 PR #268 的 CodeRabbit / Greptile open thread 是否关闭或减少
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -28,24 +28,22 @@
|
||||
|
||||
### [Godot 集成教程](./godot-integration.md)
|
||||
|
||||
> 深入学习 GFramework 与 Godot 引擎的深度集成，掌握高级开发技巧。
|
||||
> 按当前源码和真实项目接线，完成 Godot 项目级配置、场景节点生成器接入与运行时生命周期协作。
|
||||
|
||||
**适合人群**：
|
||||
|
||||
- 已完成基础教程的开发者
|
||||
- 需要优化 Godot 项目性能的开发者
|
||||
- 希望实现复杂游戏系统的架构师
|
||||
- 正在把现有 Godot C# 项目接入 GFramework 的开发者
|
||||
- 需要厘清 `project.godot`、`[GetNode]`、`[BindNodeSignal]` 边界的维护者
|
||||
|
||||
**学习内容**：
|
||||
|
||||
- 节点生命周期管理
|
||||
- 信号系统集成与桥接
|
||||
- 资源管理优化策略
|
||||
- 对象池化系统实现
|
||||
- 性能优化最佳实践
|
||||
- 调试与测试方法
|
||||
- `GeWuYou.GFramework.Godot` 与生成器包的职责划分
|
||||
- `project.godot` 到 `AutoLoads` / `InputActions` 的生成链路
|
||||
- `[GetNode]`、`[BindNodeSignal]` 与 `_Ready()` / `_ExitTree()` 的协作顺序
|
||||
- 常见旧写法迁移边界与后续阅读入口
|
||||
|
||||
**预计时间**：3-4 小时
|
||||
**预计时间**：1-2 小时
|
||||
|
||||
---
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user