mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-26 14:24:30 +08:00
Compare commits
No commits in common. "main" and "v0.0.111" have entirely different histories.
@ -1,62 +0,0 @@
|
|||||||
schema_version: 1
|
|
||||||
generated_at_utc: "2026-03-21T04:47:58Z"
|
|
||||||
generated_from: ".ai/environment/tools.raw.yaml"
|
|
||||||
generator: "scripts/generate-ai-environment.py"
|
|
||||||
platform:
|
|
||||||
family: "wsl-linux"
|
|
||||||
os: "Linux"
|
|
||||||
distro: "Ubuntu 24.04.4 LTS"
|
|
||||||
shell: "bash"
|
|
||||||
capabilities:
|
|
||||||
dotnet: true
|
|
||||||
python: true
|
|
||||||
node: true
|
|
||||||
bun: true
|
|
||||||
docker: true
|
|
||||||
fast_search: true
|
|
||||||
json_cli: true
|
|
||||||
tool_selection:
|
|
||||||
search:
|
|
||||||
preferred: "rg"
|
|
||||||
fallback: "grep"
|
|
||||||
use_for: "Repository text search."
|
|
||||||
json:
|
|
||||||
preferred: "jq"
|
|
||||||
fallback: "python3"
|
|
||||||
use_for: "Inspecting or transforming JSON command output."
|
|
||||||
shell:
|
|
||||||
preferred: "bash"
|
|
||||||
fallback: "sh"
|
|
||||||
use_for: "Repository shell scripts and command execution."
|
|
||||||
scripting:
|
|
||||||
preferred: "python3"
|
|
||||||
fallback: "bash"
|
|
||||||
use_for: "Non-trivial local automation and helper scripts."
|
|
||||||
docs_package_manager:
|
|
||||||
preferred: "bun"
|
|
||||||
fallback: "npm"
|
|
||||||
use_for: "Installing and previewing the docs site."
|
|
||||||
build_and_test:
|
|
||||||
preferred: "dotnet"
|
|
||||||
fallback: "unavailable"
|
|
||||||
use_for: "Build, test, restore, and solution validation."
|
|
||||||
python:
|
|
||||||
available: true
|
|
||||||
helper_packages:
|
|
||||||
requests: true
|
|
||||||
rich: true
|
|
||||||
openai: false
|
|
||||||
tiktoken: false
|
|
||||||
pydantic: false
|
|
||||||
pytest: false
|
|
||||||
preferences:
|
|
||||||
prefer_project_listed_tools: true
|
|
||||||
prefer_python_for_non_trivial_automation: true
|
|
||||||
avoid_unlisted_system_tools: true
|
|
||||||
rules:
|
|
||||||
- "Use rg instead of grep for repository search when rg is available."
|
|
||||||
- "Use jq for JSON inspection; fall back to python3 if jq is unavailable."
|
|
||||||
- "Prefer python3 over complex bash for non-trivial scripting when python3 is available."
|
|
||||||
- "Use bun for docs preview workflows when bun is available; otherwise fall back to npm."
|
|
||||||
- "Use dotnet for repository build and test workflows."
|
|
||||||
- "Do not assume unrelated system tools are part of the supported project environment."
|
|
||||||
@ -1,89 +0,0 @@
|
|||||||
schema_version: 1
|
|
||||||
generated_at_utc: "2026-03-21T04:47:28Z"
|
|
||||||
generator: "scripts/collect-dev-environment.sh"
|
|
||||||
|
|
||||||
platform:
|
|
||||||
os: "Linux"
|
|
||||||
distro: "Ubuntu 24.04.4 LTS"
|
|
||||||
version: "24.04"
|
|
||||||
kernel: "5.15.167.4-microsoft-standard-WSL2"
|
|
||||||
wsl: true
|
|
||||||
wsl_version: "2.4.13"
|
|
||||||
shell: "bash"
|
|
||||||
|
|
||||||
required_runtimes:
|
|
||||||
dotnet:
|
|
||||||
installed: true
|
|
||||||
version: "10.0.104"
|
|
||||||
path: "/usr/bin/dotnet"
|
|
||||||
purpose: "Builds and tests the GFramework solution."
|
|
||||||
python3:
|
|
||||||
installed: true
|
|
||||||
version: "Python 3.12.3"
|
|
||||||
path: "/usr/bin/python3"
|
|
||||||
purpose: "Runs local automation and environment collection scripts."
|
|
||||||
node:
|
|
||||||
installed: true
|
|
||||||
version: "v20.20.1"
|
|
||||||
path: "/usr/bin/node"
|
|
||||||
purpose: "Provides the JavaScript runtime used by docs tooling."
|
|
||||||
bun:
|
|
||||||
installed: true
|
|
||||||
version: "1.3.10"
|
|
||||||
path: "/root/.bun/bin/bun"
|
|
||||||
purpose: "Installs and previews the VitePress documentation site."
|
|
||||||
|
|
||||||
required_tools:
|
|
||||||
git:
|
|
||||||
installed: true
|
|
||||||
version: "git version 2.43.0"
|
|
||||||
path: "/usr/bin/git"
|
|
||||||
purpose: "Source control and patch review."
|
|
||||||
bash:
|
|
||||||
installed: true
|
|
||||||
version: "GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)"
|
|
||||||
path: "/usr/bin/bash"
|
|
||||||
purpose: "Executes repository scripts and shell automation."
|
|
||||||
rg:
|
|
||||||
installed: true
|
|
||||||
version: "ripgrep 15.1.0 (rev af60c2de9d)"
|
|
||||||
path: "/root/.bun/install/global/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/path/rg"
|
|
||||||
purpose: "Fast text search across the repository."
|
|
||||||
jq:
|
|
||||||
installed: true
|
|
||||||
version: "jq-1.7"
|
|
||||||
path: "/usr/bin/jq"
|
|
||||||
purpose: "Inspecting and transforming JSON outputs."
|
|
||||||
|
|
||||||
project_tools:
|
|
||||||
docker:
|
|
||||||
installed: true
|
|
||||||
version: "Docker version 29.2.1, build a5c7197"
|
|
||||||
path: "/usr/bin/docker"
|
|
||||||
purpose: "Runs MegaLinter and other containerized validation tools."
|
|
||||||
|
|
||||||
python_packages:
|
|
||||||
requests:
|
|
||||||
installed: true
|
|
||||||
version: "2.31.0"
|
|
||||||
purpose: "Simple HTTP calls in local helper scripts."
|
|
||||||
rich:
|
|
||||||
installed: true
|
|
||||||
version: "13.7.1"
|
|
||||||
purpose: "Readable CLI output for local Python helpers."
|
|
||||||
openai:
|
|
||||||
installed: false
|
|
||||||
version: "not-installed"
|
|
||||||
purpose: "Optional scripted access to OpenAI APIs."
|
|
||||||
tiktoken:
|
|
||||||
installed: false
|
|
||||||
version: "not-installed"
|
|
||||||
purpose: "Optional token counting for prompt and context inspection."
|
|
||||||
pydantic:
|
|
||||||
installed: false
|
|
||||||
version: "not-installed"
|
|
||||||
purpose: "Optional typed config and schema validation for helper scripts."
|
|
||||||
pytest:
|
|
||||||
installed: false
|
|
||||||
version: "not-installed"
|
|
||||||
purpose: "Optional lightweight testing for Python helper scripts."
|
|
||||||
@ -1,469 +0,0 @@
|
|||||||
# VitePress 文档生成 Skills 系统
|
|
||||||
|
|
||||||
为 GFramework 项目提供自动化的 VitePress 文档生成能力。
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
这是一套专门为 GFramework 项目设计的文档生成 skills，能够根据 C# 源代码自动生成高质量的 VitePress 文档。系统采用模块化设计，每个 skill 专注于特定的文档生成任务。
|
|
||||||
|
|
||||||
## 可用 Skills
|
|
||||||
|
|
||||||
### 1. vitepress-api-doc - API 文档生成
|
|
||||||
|
|
||||||
为单个 C# 文件生成 API 参考文档。
|
|
||||||
|
|
||||||
**用途**：
|
|
||||||
- 类、接口、枚举的 API 文档
|
|
||||||
- 方法、属性、事件的详细说明
|
|
||||||
- 基于 XML 注释生成文档
|
|
||||||
|
|
||||||
**调用方式**：
|
|
||||||
```bash
|
|
||||||
/vitepress-api-doc <C# 文件路径>
|
|
||||||
```
|
|
||||||
|
|
||||||
**示例**：
|
|
||||||
```bash
|
|
||||||
/vitepress-api-doc GFramework.Core/architecture/Architecture.cs
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出位置**：`docs/zh-CN/api-reference/<模块>/<文件名>.md`
|
|
||||||
|
|
||||||
[详细文档](./vitepress-api-doc/SKILL.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2. vitepress-guide - 功能指南生成
|
|
||||||
|
|
||||||
生成功能模块的使用指南文档。
|
|
||||||
|
|
||||||
**用途**：
|
|
||||||
- 核心功能模块的使用说明
|
|
||||||
- 设计模式和架构概念
|
|
||||||
- 最佳实践和常见问题
|
|
||||||
|
|
||||||
**调用方式**：
|
|
||||||
```bash
|
|
||||||
/vitepress-guide <主题> <目标模块>
|
|
||||||
```
|
|
||||||
|
|
||||||
**示例**：
|
|
||||||
```bash
|
|
||||||
/vitepress-guide "事件系统" Core
|
|
||||||
/vitepress-guide "IoC 容器" Core
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出位置**：`docs/zh-CN/<模块>/<主题>.md`
|
|
||||||
|
|
||||||
[详细文档](./vitepress-guide/SKILL.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3. vitepress-tutorial - 分步教程生成
|
|
||||||
|
|
||||||
生成分步教程文档，适合初学者学习。
|
|
||||||
|
|
||||||
**用途**：
|
|
||||||
- 框架入门教程
|
|
||||||
- 功能实现教程
|
|
||||||
- 问题解决方案
|
|
||||||
|
|
||||||
**调用方式**：
|
|
||||||
```bash
|
|
||||||
/vitepress-tutorial <教程主题>
|
|
||||||
```
|
|
||||||
|
|
||||||
**示例**：
|
|
||||||
```bash
|
|
||||||
/vitepress-tutorial "创建第一个 System"
|
|
||||||
/vitepress-tutorial "使用事件系统"
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出位置**：`docs/zh-CN/tutorials/<主题>.md`
|
|
||||||
|
|
||||||
[详细文档](./vitepress-tutorial/SKILL.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4. vitepress-batch-api - 批量 API 文档生成
|
|
||||||
|
|
||||||
为整个模块批量生成 API 文档。
|
|
||||||
|
|
||||||
**用途**：
|
|
||||||
- 初始化模块文档
|
|
||||||
- 更新整个模块的文档
|
|
||||||
- 快速生成大量文档
|
|
||||||
|
|
||||||
**调用方式**：
|
|
||||||
```bash
|
|
||||||
/vitepress-batch-api <模块名>
|
|
||||||
```
|
|
||||||
|
|
||||||
**示例**：
|
|
||||||
```bash
|
|
||||||
/vitepress-batch-api Core
|
|
||||||
/vitepress-batch-api Godot
|
|
||||||
```
|
|
||||||
|
|
||||||
**输出位置**：`docs/zh-CN/api-reference/<模块>/`
|
|
||||||
|
|
||||||
[详细文档](./vitepress-batch-api/SKILL.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. vitepress-validate - 文档验证
|
|
||||||
|
|
||||||
验证文档的质量和规范性。
|
|
||||||
|
|
||||||
**用途**：
|
|
||||||
- Frontmatter 格式验证
|
|
||||||
- 内部链接有效性检查
|
|
||||||
- 代码块语法验证
|
|
||||||
- 标点符号规范检查
|
|
||||||
|
|
||||||
**调用方式**：
|
|
||||||
```bash
|
|
||||||
/vitepress-validate <文件或目录路径>
|
|
||||||
```
|
|
||||||
|
|
||||||
**示例**：
|
|
||||||
```bash
|
|
||||||
/vitepress-validate docs/zh-CN/api-reference/core/architecture.md
|
|
||||||
/vitepress-validate docs/zh-CN/
|
|
||||||
```
|
|
||||||
|
|
||||||
[详细文档](./vitepress-validate/SKILL.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 快速开始
|
|
||||||
|
|
||||||
### 1. 生成单个 API 文档
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 为 Architecture 类生成文档
|
|
||||||
/vitepress-api-doc GFramework.Core/architecture/Architecture.cs
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 批量生成模块文档
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 为整个 Core 模块生成文档
|
|
||||||
/vitepress-batch-api Core
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 生成功能指南
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 生成事件系统使用指南
|
|
||||||
/vitepress-guide "事件系统" Core
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. 生成教程
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 生成创建 Model 的教程
|
|
||||||
/vitepress-tutorial "创建第一个 Model"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. 验证文档
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 验证生成的文档
|
|
||||||
/vitepress-validate docs/zh-CN/api-reference/core/
|
|
||||||
```
|
|
||||||
|
|
||||||
## 工作流程
|
|
||||||
|
|
||||||
### 典型工作流程
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
graph TD
|
|
||||||
A[开始] --> B{文档类型?}
|
|
||||||
B -->|API 文档| C[/vitepress-api-doc]
|
|
||||||
B -->|功能指南| D[/vitepress-guide]
|
|
||||||
B -->|教程| E[/vitepress-tutorial]
|
|
||||||
C --> F[/vitepress-validate]
|
|
||||||
D --> F
|
|
||||||
E --> F
|
|
||||||
F --> G{验证通过?}
|
|
||||||
G -->|是| H[完成]
|
|
||||||
G -->|否| I[修复问题]
|
|
||||||
I --> F
|
|
||||||
```
|
|
||||||
|
|
||||||
### 推荐流程
|
|
||||||
|
|
||||||
1. **初始化模块文档**
|
|
||||||
```bash
|
|
||||||
/vitepress-batch-api Core
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **生成功能指南**
|
|
||||||
```bash
|
|
||||||
/vitepress-guide "IoC 容器" Core
|
|
||||||
/vitepress-guide "事件系统" Core
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **生成教程**
|
|
||||||
```bash
|
|
||||||
/vitepress-tutorial "创建第一个 Model"
|
|
||||||
/vitepress-tutorial "使用命令系统"
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **验证所有文档**
|
|
||||||
```bash
|
|
||||||
/vitepress-validate docs/zh-CN/
|
|
||||||
```
|
|
||||||
|
|
||||||
## 目录结构
|
|
||||||
|
|
||||||
```
|
|
||||||
.claude/skills/
|
|
||||||
├── README.md # 本文件
|
|
||||||
├── _shared/ # 共享资源
|
|
||||||
│ └── scripts/ # 共享脚本
|
|
||||||
│ ├── update-vitepress-nav.sh # 更新导航配置
|
|
||||||
│ ├── parse-csharp-xml.sh # 解析 XML 注释
|
|
||||||
│ └── generate-examples.sh # 生成代码示例
|
|
||||||
│
|
|
||||||
├── vitepress-api-doc/ # API 文档生成
|
|
||||||
│ ├── SKILL.md # Skill 说明
|
|
||||||
│ ├── template.md # 文档模板
|
|
||||||
│ └── examples/ # 示例文档
|
|
||||||
│ ├── class-example.md
|
|
||||||
│ ├── interface-example.md
|
|
||||||
│ └── enum-example.md
|
|
||||||
│
|
|
||||||
├── vitepress-guide/ # 功能指南生成
|
|
||||||
│ ├── SKILL.md
|
|
||||||
│ ├── template.md
|
|
||||||
│ └── examples/
|
|
||||||
│ └── guide-example.md
|
|
||||||
│
|
|
||||||
├── vitepress-tutorial/ # 教程生成
|
|
||||||
│ ├── SKILL.md
|
|
||||||
│ ├── template.md
|
|
||||||
│ └── examples/
|
|
||||||
│ └── tutorial-example.md
|
|
||||||
│
|
|
||||||
├── vitepress-batch-api/ # 批量 API 文档生成
|
|
||||||
│ ├── SKILL.md
|
|
||||||
│ └── scripts/
|
|
||||||
│ └── batch-generate.sh
|
|
||||||
│
|
|
||||||
└── vitepress-validate/ # 文档验证
|
|
||||||
├── SKILL.md
|
|
||||||
└── scripts/
|
|
||||||
├── validate-frontmatter.sh
|
|
||||||
├── validate-links.sh
|
|
||||||
├── validate-code-blocks.sh
|
|
||||||
└── validate-all.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
## 设计原则
|
|
||||||
|
|
||||||
### 1. 单一职责
|
|
||||||
|
|
||||||
每个 skill 专注于一个特定任务：
|
|
||||||
- `vitepress-api-doc` - 单文件 API 文档
|
|
||||||
- `vitepress-guide` - 功能指南
|
|
||||||
- `vitepress-tutorial` - 分步教程
|
|
||||||
- `vitepress-batch-api` - 批量生成
|
|
||||||
- `vitepress-validate` - 质量验证
|
|
||||||
|
|
||||||
### 2. 模块化设计
|
|
||||||
|
|
||||||
- 共享脚本放在 `_shared/scripts/`
|
|
||||||
- 每个 skill 独立维护
|
|
||||||
- 可以单独使用或组合使用
|
|
||||||
|
|
||||||
### 3. 基于源代码
|
|
||||||
|
|
||||||
- 仅使用 XML 注释，不添加 AI 补充
|
|
||||||
- 保持文档与代码同步
|
|
||||||
- 代码示例由 AI 自动生成
|
|
||||||
|
|
||||||
### 4. 质量保证
|
|
||||||
|
|
||||||
- 所有生成的文档都应通过验证
|
|
||||||
- 遵循 VitePress 规范
|
|
||||||
- 保持一致的文档风格
|
|
||||||
|
|
||||||
## 文档规范
|
|
||||||
|
|
||||||
### Frontmatter 格式
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
title: 文档标题
|
|
||||||
description: 简短描述（1-2 句话）
|
|
||||||
outline: deep # 可选
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
### 代码块标记
|
|
||||||
|
|
||||||
- C# 代码使用 `csharp`
|
|
||||||
- Bash 脚本使用 `bash`
|
|
||||||
- JSON 使用 `json`
|
|
||||||
- YAML 使用 `yaml`
|
|
||||||
|
|
||||||
### 泛型符号转义
|
|
||||||
|
|
||||||
在正文中使用 HTML 实体：
|
|
||||||
- `List<T>` → `List<T>`
|
|
||||||
- 代码块内保持原样
|
|
||||||
|
|
||||||
### 中文标点符号
|
|
||||||
|
|
||||||
- 中文句子使用全角标点：，。！？
|
|
||||||
- 英文句子使用半角标点：,.!?
|
|
||||||
- 代码周围使用半角符号
|
|
||||||
|
|
||||||
## 共享脚本
|
|
||||||
|
|
||||||
### update-vitepress-nav.sh
|
|
||||||
|
|
||||||
更新 VitePress 侧边栏导航配置。
|
|
||||||
|
|
||||||
**用法**：
|
|
||||||
```bash
|
|
||||||
.claude/skills/_shared/scripts/update-vitepress-nav.sh <文件路径> <标题>
|
|
||||||
```
|
|
||||||
|
|
||||||
### parse-csharp-xml.sh
|
|
||||||
|
|
||||||
解析 C# XML 文档注释。
|
|
||||||
|
|
||||||
**用法**：
|
|
||||||
```bash
|
|
||||||
.claude/skills/_shared/scripts/parse-csharp-xml.sh <C# 文件路径>
|
|
||||||
```
|
|
||||||
|
|
||||||
### generate-examples.sh
|
|
||||||
|
|
||||||
生成代码示例。
|
|
||||||
|
|
||||||
**用法**：
|
|
||||||
```bash
|
|
||||||
.claude/skills/_shared/scripts/generate-examples.sh <类型名> <命名空间>
|
|
||||||
```
|
|
||||||
|
|
||||||
## 最佳实践
|
|
||||||
|
|
||||||
### 1. 文档生成顺序
|
|
||||||
|
|
||||||
1. 先生成 API 文档（基础）
|
|
||||||
2. 再生成功能指南（概念）
|
|
||||||
3. 最后生成教程（实践）
|
|
||||||
|
|
||||||
### 2. 保持文档同步
|
|
||||||
|
|
||||||
- 修改代码后及时更新文档
|
|
||||||
- 使用单文件生成更新特定文档
|
|
||||||
- 定期批量验证所有文档
|
|
||||||
|
|
||||||
### 3. 质量控制
|
|
||||||
|
|
||||||
- 生成后立即验证
|
|
||||||
- 修复所有错误和警告
|
|
||||||
- 确保链接有效
|
|
||||||
|
|
||||||
### 4. 版本控制
|
|
||||||
|
|
||||||
- 将生成的文档提交到 Git
|
|
||||||
- 在 PR 中包含文档更新
|
|
||||||
- 保持文档与代码版本一致
|
|
||||||
|
|
||||||
## 故障排除
|
|
||||||
|
|
||||||
### 问题：生成的文档缺少内容
|
|
||||||
|
|
||||||
**原因**：源代码缺少 XML 注释
|
|
||||||
|
|
||||||
**解决方案**：
|
|
||||||
1. 在源代码中添加 XML 注释
|
|
||||||
2. 重新生成文档
|
|
||||||
|
|
||||||
### 问题：验证失败
|
|
||||||
|
|
||||||
**原因**：文档格式不符合规范
|
|
||||||
|
|
||||||
**解决方案**：
|
|
||||||
1. 查看验证错误信息
|
|
||||||
2. 根据提示修复问题
|
|
||||||
3. 重新验证
|
|
||||||
|
|
||||||
### 问题：链接损坏
|
|
||||||
|
|
||||||
**原因**：文件路径错误或文件不存在
|
|
||||||
|
|
||||||
**解决方案**：
|
|
||||||
1. 检查链接的目标文件是否存在
|
|
||||||
2. 修正文件路径
|
|
||||||
3. 重新验证
|
|
||||||
|
|
||||||
### 问题：批量生成速度慢
|
|
||||||
|
|
||||||
**原因**：文件数量多
|
|
||||||
|
|
||||||
**解决方案**：
|
|
||||||
1. 使用 `--parallel` 选项（如果支持）
|
|
||||||
2. 分批生成
|
|
||||||
3. 仅生成修改的文件
|
|
||||||
|
|
||||||
## 扩展开发
|
|
||||||
|
|
||||||
### 添加新 Skill
|
|
||||||
|
|
||||||
1. 在 `.claude/skills/` 下创建新目录
|
|
||||||
2. 创建 `SKILL.md` 说明文档
|
|
||||||
3. 创建必要的模板和脚本
|
|
||||||
4. 在本 README 中添加说明
|
|
||||||
|
|
||||||
### 修改现有 Skill
|
|
||||||
|
|
||||||
1. 更新 `SKILL.md` 文档
|
|
||||||
2. 修改模板或脚本
|
|
||||||
3. 更新示例文档
|
|
||||||
4. 测试修改后的功能
|
|
||||||
|
|
||||||
## 贡献指南
|
|
||||||
|
|
||||||
### 报告问题
|
|
||||||
|
|
||||||
在 GitHub Issues 中报告问题，包含：
|
|
||||||
- 使用的 skill 名称
|
|
||||||
- 输入参数
|
|
||||||
- 预期结果
|
|
||||||
- 实际结果
|
|
||||||
- 错误信息
|
|
||||||
|
|
||||||
### 提交改进
|
|
||||||
|
|
||||||
1. Fork 项目
|
|
||||||
2. 创建功能分支
|
|
||||||
3. 提交修改
|
|
||||||
4. 创建 Pull Request
|
|
||||||
|
|
||||||
## 版本历史
|
|
||||||
|
|
||||||
- v1.0.0 (2025-01-XX) - 初始版本
|
|
||||||
- 5 个核心 skills
|
|
||||||
- 3 个共享脚本
|
|
||||||
- 完整的文档和示例
|
|
||||||
|
|
||||||
## 许可证
|
|
||||||
|
|
||||||
与 GFramework 项目保持一致。
|
|
||||||
|
|
||||||
## 联系方式
|
|
||||||
|
|
||||||
如有问题或建议，请通过以下方式联系：
|
|
||||||
- GitHub Issues
|
|
||||||
- 项目讨论区
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**注意**：本 skills 系统专为 GFramework 项目设计，使用前请确保了解项目结构和文档规范。
|
|
||||||
@ -1,205 +0,0 @@
|
|||||||
# GFramework 文档编写规范
|
|
||||||
|
|
||||||
## Markdown 语法规范
|
|
||||||
|
|
||||||
### 1. 泛型标记转义
|
|
||||||
|
|
||||||
在 Markdown 文档中,所有泛型标记必须转义,否则会被 VitePress 误认为 HTML 标签。
|
|
||||||
|
|
||||||
**错误示例**:
|
|
||||||
```markdown
|
|
||||||
`Option<T>` 是一个泛型类型
|
|
||||||
`Result<TValue, TError>` 表示结果
|
|
||||||
public class Repository<TData> { }
|
|
||||||
```
|
|
||||||
|
|
||||||
**正确示例**:
|
|
||||||
```markdown
|
|
||||||
`Option<T>` 是一个泛型类型
|
|
||||||
`Result<TValue, TError>` 表示结果
|
|
||||||
public class Repository<TData> { }
|
|
||||||
```
|
|
||||||
|
|
||||||
**常见泛型标记**:
|
|
||||||
- `<T>` → `<T>`
|
|
||||||
- `<TResult>` → `<TResult>`
|
|
||||||
- `<TValue>` → `<TValue>`
|
|
||||||
- `<TError>` → `<TError>`
|
|
||||||
- `<TSaveData>` → `<TSaveData>`
|
|
||||||
- `<TData>` → `<TData>`
|
|
||||||
- `<TNode>` → `<TNode>`
|
|
||||||
|
|
||||||
### 2. HTML 标签转义
|
|
||||||
|
|
||||||
如果需要在文档中显示 HTML 标签,必须转义:
|
|
||||||
- `<summary>` → `<summary>`
|
|
||||||
- `<param>` → `<param>`
|
|
||||||
- `<returns>` → `<returns>`
|
|
||||||
|
|
||||||
### 3. 链接验证
|
|
||||||
|
|
||||||
**内部链接规则**:
|
|
||||||
- 使用相对路径: `/zh-CN/core/events`
|
|
||||||
- 确保目标文件存在
|
|
||||||
- 不要链接到尚未创建的页面
|
|
||||||
|
|
||||||
**已存在的文档路径**:
|
|
||||||
|
|
||||||
**Core 模块**:
|
|
||||||
- `/zh-CN/core/architecture` - 架构系统
|
|
||||||
- `/zh-CN/core/ioc` - IoC 容器
|
|
||||||
- `/zh-CN/core/events` - 事件系统
|
|
||||||
- `/zh-CN/core/command` - 命令系统
|
|
||||||
- `/zh-CN/core/query` - 查询系统
|
|
||||||
- `/zh-CN/core/model` - Model 系统
|
|
||||||
- `/zh-CN/core/system` - System 系统
|
|
||||||
- `/zh-CN/core/utility` - Utility 系统
|
|
||||||
- `/zh-CN/core/controller` - Controller 系统
|
|
||||||
- `/zh-CN/core/logging` - 日志系统
|
|
||||||
- `/zh-CN/core/pool` - 对象池
|
|
||||||
- `/zh-CN/core/property` - 可绑定属性
|
|
||||||
- `/zh-CN/core/lifecycle` - 生命周期管理
|
|
||||||
- `/zh-CN/core/coroutine` - 协程系统
|
|
||||||
- `/zh-CN/core/resource` - 资源管理
|
|
||||||
- `/zh-CN/core/state-machine` - 状态机
|
|
||||||
- `/zh-CN/core/cqrs` - CQRS 与 Mediator
|
|
||||||
- `/zh-CN/core/functional` - 函数式编程
|
|
||||||
- `/zh-CN/core/pause` - 暂停管理
|
|
||||||
- `/zh-CN/core/configuration` - 配置管理
|
|
||||||
- `/zh-CN/core/ecs` - ECS 系统集成
|
|
||||||
- `/zh-CN/core/extensions` - 扩展方法
|
|
||||||
- `/zh-CN/core/rule` - 规则系统
|
|
||||||
- `/zh-CN/core/environment` - 环境系统
|
|
||||||
- `/zh-CN/core/context` - 上下文系统
|
|
||||||
- `/zh-CN/core/async-initialization` - 异步初始化
|
|
||||||
|
|
||||||
**Game 模块**:
|
|
||||||
- `/zh-CN/game/scene` - 场景系统
|
|
||||||
- `/zh-CN/game/ui` - UI 系统
|
|
||||||
- `/zh-CN/game/data` - 数据与存档
|
|
||||||
- `/zh-CN/game/storage` - 存储系统
|
|
||||||
- `/zh-CN/game/serialization` - 序列化系统
|
|
||||||
- `/zh-CN/game/setting` - 设置系统
|
|
||||||
|
|
||||||
**Godot 模块**:
|
|
||||||
- `/zh-CN/godot/architecture` - Godot 架构集成
|
|
||||||
- `/zh-CN/godot/scene` - Godot 场景系统
|
|
||||||
- `/zh-CN/godot/ui` - Godot UI 系统
|
|
||||||
- `/zh-CN/godot/pool` - Godot 节点池
|
|
||||||
- `/zh-CN/godot/resource` - Godot 资源仓储
|
|
||||||
- `/zh-CN/godot/logging` - Godot 日志系统
|
|
||||||
- `/zh-CN/godot/pause` - Godot 暂停处理
|
|
||||||
- `/zh-CN/godot/extensions` - Godot 扩展
|
|
||||||
- `/zh-CN/godot/coroutine` - Godot 协程
|
|
||||||
- `/zh-CN/godot/signal` - Godot 信号
|
|
||||||
- `/zh-CN/godot/storage` - Godot 存储
|
|
||||||
|
|
||||||
**教程**:
|
|
||||||
- `/zh-CN/tutorials/coroutine-tutorial` - 协程系统教程
|
|
||||||
- `/zh-CN/tutorials/state-machine-tutorial` - 状态机教程
|
|
||||||
- `/zh-CN/tutorials/resource-management` - 资源管理教程
|
|
||||||
- `/zh-CN/tutorials/save-system` - 存档系统教程
|
|
||||||
- `/zh-CN/tutorials/godot-complete-project` - Godot 完整项目
|
|
||||||
- `/zh-CN/tutorials/functional-programming` - 函数式编程实践
|
|
||||||
- `/zh-CN/tutorials/pause-system` - 暂停系统实现
|
|
||||||
- `/zh-CN/tutorials/data-migration` - 数据迁移实践
|
|
||||||
- `/zh-CN/tutorials/godot-integration` - Godot 集成
|
|
||||||
- `/zh-CN/tutorials/advanced-patterns` - 高级模式
|
|
||||||
|
|
||||||
**其他**:
|
|
||||||
- `/zh-CN/getting-started/quick-start` - 快速开始
|
|
||||||
- `/zh-CN/getting-started/installation` - 安装指南
|
|
||||||
- `/zh-CN/best-practices/architecture-patterns` - 架构模式
|
|
||||||
|
|
||||||
**不存在的路径** (不要链接):
|
|
||||||
- `/zh-CN/best-practices/performance` - 尚未创建
|
|
||||||
- `/zh-CN/core/serializer` - 错误路径,应使用 `/zh-CN/game/serialization`
|
|
||||||
|
|
||||||
## 代码块规范
|
|
||||||
|
|
||||||
### 1. 代码块语言标识
|
|
||||||
|
|
||||||
始终指定代码块的语言:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
\`\`\`csharp
|
|
||||||
public class Example { }
|
|
||||||
\`\`\`
|
|
||||||
|
|
||||||
\`\`\`bash
|
|
||||||
npm install
|
|
||||||
\`\`\`
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 代码注释
|
|
||||||
|
|
||||||
代码示例应包含中文注释:
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
// 创建玩家实体
|
|
||||||
var player = new Player
|
|
||||||
{
|
|
||||||
Name = "玩家1", // 玩家名称
|
|
||||||
Level = 1 // 初始等级
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
## Frontmatter 规范
|
|
||||||
|
|
||||||
每个文档必须包含正确的 frontmatter:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
title: 文档标题
|
|
||||||
description: 简短描述（1-2 句话）
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
## 文档结构规范
|
|
||||||
|
|
||||||
### 指南文档结构
|
|
||||||
|
|
||||||
1. 概述
|
|
||||||
2. 核心概念
|
|
||||||
3. 基本用法
|
|
||||||
4. 高级用法
|
|
||||||
5. 最佳实践
|
|
||||||
6. 常见问题
|
|
||||||
7. 相关文档
|
|
||||||
|
|
||||||
### 教程文档结构
|
|
||||||
|
|
||||||
1. 学习目标
|
|
||||||
2. 前置条件
|
|
||||||
3. 步骤 1-N (3-7 步)
|
|
||||||
4. 完整代码
|
|
||||||
5. 运行结果
|
|
||||||
6. 下一步
|
|
||||||
7. 相关文档
|
|
||||||
|
|
||||||
## 验证清单
|
|
||||||
|
|
||||||
生成文档后,必须检查:
|
|
||||||
|
|
||||||
- [ ] 所有泛型标记已转义 (`<T>` → `<T>`)
|
|
||||||
- [ ] 所有内部链接指向存在的页面
|
|
||||||
- [ ] Frontmatter 格式正确
|
|
||||||
- [ ] 代码块指定了语言
|
|
||||||
- [ ] 代码包含中文注释
|
|
||||||
- [ ] 文档结构完整
|
|
||||||
- [ ] 没有 HTML 标签错误
|
|
||||||
|
|
||||||
## 自动修复脚本
|
|
||||||
|
|
||||||
如果文档已生成,可以使用以下脚本修复常见问题:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 修复泛型标记
|
|
||||||
sed -i 's/<T>/\<T\>/g' file.md
|
|
||||||
sed -i 's/<TResult>/\<TResult\>/g' file.md
|
|
||||||
sed -i 's/<TValue>/\<TValue\>/g' file.md
|
|
||||||
sed -i 's/<TError>/\<TError\>/g' file.md
|
|
||||||
|
|
||||||
# 验证构建
|
|
||||||
cd docs && bun run build
|
|
||||||
```
|
|
||||||
@ -1,84 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
# 共享的模块配置
|
|
||||||
# 用于统一管理 GFramework 项目的模块映射关系
|
|
||||||
|
|
||||||
# 根据模块名获取源代码目录
|
|
||||||
get_source_dir() {
|
|
||||||
local MODULE="$1"
|
|
||||||
case "$MODULE" in
|
|
||||||
Core)
|
|
||||||
echo "GFramework.Core"
|
|
||||||
;;
|
|
||||||
Game)
|
|
||||||
echo "GFramework.Game"
|
|
||||||
;;
|
|
||||||
Godot)
|
|
||||||
echo "GFramework.Godot"
|
|
||||||
;;
|
|
||||||
SourceGenerators)
|
|
||||||
echo "GFramework.SourceGenerators"
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
echo ""
|
|
||||||
return 1
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
}
|
|
||||||
|
|
||||||
# 根据模块名获取文档输出目录
|
|
||||||
get_docs_dir() {
|
|
||||||
local MODULE="$1"
|
|
||||||
case "$MODULE" in
|
|
||||||
Core)
|
|
||||||
echo "docs/zh-CN/api-reference/core"
|
|
||||||
;;
|
|
||||||
Game)
|
|
||||||
echo "docs/zh-CN/api-reference/game"
|
|
||||||
;;
|
|
||||||
Godot)
|
|
||||||
echo "docs/zh-CN/api-reference/godot"
|
|
||||||
;;
|
|
||||||
SourceGenerators)
|
|
||||||
echo "docs/zh-CN/api-reference/source-generators"
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
echo ""
|
|
||||||
return 1
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
}
|
|
||||||
|
|
||||||
# 根据命名空间推断模块名
|
|
||||||
infer_module_from_namespace() {
|
|
||||||
local NAMESPACE="$1"
|
|
||||||
if [[ "$NAMESPACE" == GFramework.Core* ]]; then
|
|
||||||
echo "Core"
|
|
||||||
elif [[ "$NAMESPACE" == GFramework.Game* ]]; then
|
|
||||||
echo "Game"
|
|
||||||
elif [[ "$NAMESPACE" == GFramework.Godot* ]]; then
|
|
||||||
echo "Godot"
|
|
||||||
elif [[ "$NAMESPACE" == GFramework.SourceGenerators* ]]; then
|
|
||||||
echo "SourceGenerators"
|
|
||||||
else
|
|
||||||
echo ""
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
# 获取所有可用模块列表
|
|
||||||
get_all_modules() {
|
|
||||||
echo "Core Game Godot SourceGenerators"
|
|
||||||
}
|
|
||||||
|
|
||||||
# 验证模块名是否有效
|
|
||||||
is_valid_module() {
|
|
||||||
local MODULE="$1"
|
|
||||||
case "$MODULE" in
|
|
||||||
Core|Game|Godot|SourceGenerators)
|
|
||||||
return 0
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
return 1
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
}
|
|
||||||
@ -1,121 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
# 生成代码示例辅助脚本
|
|
||||||
# 用法: generate-examples.sh <类型> <类名> [命名空间]
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
TYPE="$1" # class/interface/enum
|
|
||||||
CLASS_NAME="$2"
|
|
||||||
NAMESPACE="$3"
|
|
||||||
|
|
||||||
if [ -z "$TYPE" ] || [ -z "$CLASS_NAME" ]; then
|
|
||||||
echo "用法: $0 <类型> <类名> [命名空间]"
|
|
||||||
echo "类型: class, interface, enum"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo "=========================================="
|
|
||||||
echo "代码示例生成指南"
|
|
||||||
echo "=========================================="
|
|
||||||
echo "类型: $TYPE"
|
|
||||||
echo "类名: $CLASS_NAME"
|
|
||||||
if [ -n "$NAMESPACE" ]; then
|
|
||||||
echo "命名空间: $NAMESPACE"
|
|
||||||
fi
|
|
||||||
echo ""
|
|
||||||
|
|
||||||
# 根据类型提供示例生成指南
|
|
||||||
case "$TYPE" in
|
|
||||||
class)
|
|
||||||
echo "## 类示例生成建议"
|
|
||||||
echo ""
|
|
||||||
echo "1. 基本用法示例:"
|
|
||||||
echo " - 实例化对象"
|
|
||||||
echo " - 调用主要方法"
|
|
||||||
echo " - 访问公共属性"
|
|
||||||
echo ""
|
|
||||||
echo "2. 常见场景示例:"
|
|
||||||
echo " - 实际应用案例"
|
|
||||||
echo " - 与其他组件的集成"
|
|
||||||
echo ""
|
|
||||||
echo "3. 高级用法示例（如适用）:"
|
|
||||||
echo " - 复杂配置"
|
|
||||||
echo " - 扩展和自定义"
|
|
||||||
echo ""
|
|
||||||
echo "示例模板:"
|
|
||||||
echo '```csharp'
|
|
||||||
echo "// 创建实例"
|
|
||||||
echo "var instance = new $CLASS_NAME();"
|
|
||||||
echo ""
|
|
||||||
echo "// 使用主要功能"
|
|
||||||
echo "instance.MainMethod();"
|
|
||||||
echo '```'
|
|
||||||
;;
|
|
||||||
interface)
|
|
||||||
echo "## 接口示例生成建议"
|
|
||||||
echo ""
|
|
||||||
echo "1. 实现接口:"
|
|
||||||
echo " - 展示如何实现该接口"
|
|
||||||
echo " - 实现所有必需成员"
|
|
||||||
echo ""
|
|
||||||
echo "2. 使用接口:"
|
|
||||||
echo " - 通过接口类型使用实例"
|
|
||||||
echo " - 依赖注入场景"
|
|
||||||
echo ""
|
|
||||||
echo "示例模板:"
|
|
||||||
echo '```csharp'
|
|
||||||
echo "// 实现接口"
|
|
||||||
echo "public class My$CLASS_NAME : $CLASS_NAME"
|
|
||||||
echo "{"
|
|
||||||
echo " // 实现成员"
|
|
||||||
echo "}"
|
|
||||||
echo ""
|
|
||||||
echo "// 使用接口"
|
|
||||||
echo "$CLASS_NAME instance = new My$CLASS_NAME();"
|
|
||||||
echo '```'
|
|
||||||
;;
|
|
||||||
enum)
|
|
||||||
echo "## 枚举示例生成建议"
|
|
||||||
echo ""
|
|
||||||
echo "1. 基本用法:"
|
|
||||||
echo " - 枚举值赋值"
|
|
||||||
echo " - 值比较"
|
|
||||||
echo ""
|
|
||||||
echo "2. Switch 语句:"
|
|
||||||
echo " - 根据枚举值执行不同逻辑"
|
|
||||||
echo ""
|
|
||||||
echo "3. 枚举转换:"
|
|
||||||
echo " - 字符串转枚举"
|
|
||||||
echo " - 枚举转整数"
|
|
||||||
echo ""
|
|
||||||
echo "示例模板:"
|
|
||||||
echo '```csharp'
|
|
||||||
echo "// 使用枚举值"
|
|
||||||
echo "var value = $CLASS_NAME.SomeValue;"
|
|
||||||
echo ""
|
|
||||||
echo "// Switch 语句"
|
|
||||||
echo "switch (value)"
|
|
||||||
echo "{"
|
|
||||||
echo " case $CLASS_NAME.Value1:"
|
|
||||||
echo " // 处理逻辑"
|
|
||||||
echo " break;"
|
|
||||||
echo " case $CLASS_NAME.Value2:"
|
|
||||||
echo " // 处理逻辑"
|
|
||||||
echo " break;"
|
|
||||||
echo "}"
|
|
||||||
echo '```'
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
echo "错误: 不支持的类型: $TYPE"
|
|
||||||
exit 1
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
|
|
||||||
echo ""
|
|
||||||
echo "注意事项:"
|
|
||||||
echo "- 使用项目的命名约定"
|
|
||||||
echo "- 包含必要的 using 语句"
|
|
||||||
echo "- 确保示例代码可以编译运行"
|
|
||||||
echo "- 参考现有教程的代码风格"
|
|
||||||
|
|
||||||
exit 0
|
|
||||||
@ -1,48 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
# 解析 C# XML 文档注释
|
|
||||||
# 用法: parse-csharp-xml.sh <C# 文件路径>
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
FILE_PATH="$1"
|
|
||||||
|
|
||||||
if [ -z "$FILE_PATH" ]; then
|
|
||||||
echo "用法: $0 <C# 文件路径>"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [ ! -f "$FILE_PATH" ]; then
|
|
||||||
echo "错误: 文件不存在: $FILE_PATH"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo "解析 C# XML 文档注释: $FILE_PATH"
|
|
||||||
|
|
||||||
# 提取 summary 标签内容
|
|
||||||
echo "=== Summary ==="
|
|
||||||
grep -A 5 "/// <summary>" "$FILE_PATH" | grep "///" | sed 's/.*\/\/\/\s*//' | sed 's/<summary>//g' | sed 's/<\/summary>//g' || echo "未找到 summary"
|
|
||||||
|
|
||||||
# 提取 param 标签内容
|
|
||||||
echo ""
|
|
||||||
echo "=== Parameters ==="
|
|
||||||
grep "/// <param" "$FILE_PATH" | sed 's/.*\/\/\/\s*//' || echo "未找到 param"
|
|
||||||
|
|
||||||
# 提取 returns 标签内容
|
|
||||||
echo ""
|
|
||||||
echo "=== Returns ==="
|
|
||||||
grep "/// <returns>" "$FILE_PATH" | sed 's/.*\/\/\/\s*//' | sed 's/<returns>//g' | sed 's/<\/returns>//g' || echo "未找到 returns"
|
|
||||||
|
|
||||||
# 提取 exception 标签内容
|
|
||||||
echo ""
|
|
||||||
echo "=== Exceptions ==="
|
|
||||||
grep "/// <exception" "$FILE_PATH" | sed 's/.*\/\/\/\s*//' || echo "未找到 exception"
|
|
||||||
|
|
||||||
# 提取 example 标签内容
|
|
||||||
echo ""
|
|
||||||
echo "=== Examples ==="
|
|
||||||
grep -A 10 "/// <example>" "$FILE_PATH" | grep "///" | sed 's/.*\/\/\/\s*//' || echo "未找到 example"
|
|
||||||
|
|
||||||
echo ""
|
|
||||||
echo "解析完成"
|
|
||||||
|
|
||||||
exit 0
|
|
||||||
@ -1,57 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
# 更新 VitePress 侧边栏配置
|
|
||||||
# 用法: update-vitepress-nav.sh <文档路径> <文档标题>
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
DOC_PATH="$1"
|
|
||||||
DOC_TITLE="$2"
|
|
||||||
CONFIG_FILE="docs/.vitepress/config.mts"
|
|
||||||
|
|
||||||
if [ -z "$DOC_PATH" ] || [ -z "$DOC_TITLE" ]; then
|
|
||||||
echo "用法: $0 <文档路径> <文档标题>"
|
|
||||||
echo "示例: $0 /zh-CN/api-reference/core/architecture Architecture"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [ ! -f "$CONFIG_FILE" ]; then
|
|
||||||
echo "错误: 找不到 VitePress 配置文件: $CONFIG_FILE"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# 提取模块名称（core/game/godot/source-generators）
|
|
||||||
MODULE=$(echo "$DOC_PATH" | grep -oP '(?<=/zh-CN/)[^/]+' | head -1)
|
|
||||||
|
|
||||||
if [ -z "$MODULE" ]; then
|
|
||||||
echo "错误: 无法从路径中提取模块名称: $DOC_PATH"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo "=========================================="
|
|
||||||
echo "VitePress 导航配置更新"
|
|
||||||
echo "=========================================="
|
|
||||||
echo "模块: $MODULE"
|
|
||||||
echo "路径: $DOC_PATH"
|
|
||||||
echo "标题: $DOC_TITLE"
|
|
||||||
echo ""
|
|
||||||
|
|
||||||
# 检查配置文件中是否已存在该路径
|
|
||||||
if grep -q "link: '$DOC_PATH'" "$CONFIG_FILE"; then
|
|
||||||
echo "✓ 该文档已存在于导航配置中"
|
|
||||||
exit 0
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo "提示: 需要在 VitePress 配置中添加新条目"
|
|
||||||
echo ""
|
|
||||||
echo "建议的配置条目:"
|
|
||||||
echo "{ text: '$DOC_TITLE', link: '$DOC_PATH' }"
|
|
||||||
echo ""
|
|
||||||
echo "请使用以下方式之一更新配置:"
|
|
||||||
echo "1. 让 AI 使用 Edit 工具直接修改 $CONFIG_FILE"
|
|
||||||
echo "2. 手动编辑配置文件并添加上述条目到对应的 sidebar 部分"
|
|
||||||
echo ""
|
|
||||||
|
|
||||||
# 输出相关的 sidebar 配置路径
|
|
||||||
echo "相关的 sidebar 配置路径: '/zh-CN/$MODULE/'"
|
|
||||||
|
|
||||||
exit 0
|
|
||||||
@ -1,210 +0,0 @@
|
|||||||
# VitePress API 文档生成
|
|
||||||
|
|
||||||
为单个 C# 类、接口或枚举生成符合 VitePress 标准的 API 参考文档。
|
|
||||||
|
|
||||||
## 用途
|
|
||||||
|
|
||||||
此 skill 用于从 C# 源代码文件自动生成结构化的 API 文档，包括：
|
|
||||||
- 类型概述和命名空间信息
|
|
||||||
- 构造函数、方法、属性的详细说明
|
|
||||||
- 基于 XML 文档注释的描述
|
|
||||||
- 自动生成的使用示例
|
|
||||||
- 相关类型的交叉引用
|
|
||||||
|
|
||||||
## 调用方式
|
|
||||||
|
|
||||||
```bash
|
|
||||||
/vitepress-api-doc <C# 文件路径>
|
|
||||||
```
|
|
||||||
|
|
||||||
**示例**：
|
|
||||||
```bash
|
|
||||||
/vitepress-api-doc GFramework.Core/architecture/Architecture.cs
|
|
||||||
```
|
|
||||||
|
|
||||||
## 工作流程
|
|
||||||
|
|
||||||
1. **读取源代码文件**
|
|
||||||
- 验证文件存在且为 C# 文件
|
|
||||||
- 读取完整的源代码内容
|
|
||||||
|
|
||||||
2. **解析代码结构**
|
|
||||||
- 提取命名空间、类名、访问修饰符
|
|
||||||
- 识别类型（class/interface/enum/struct）
|
|
||||||
- 解析继承关系和实现的接口
|
|
||||||
- 提取所有公共成员（构造函数、方法、属性、事件、字段）
|
|
||||||
|
|
||||||
3. **提取 XML 文档注释**
|
|
||||||
- 解析 `/// <summary>` 标签（类型和成员描述）
|
|
||||||
- 解析 `/// <param>` 标签（参数说明）
|
|
||||||
- 解析 `/// <returns>` 标签（返回值说明）
|
|
||||||
- 解析 `/// <exception>` 标签（异常说明）
|
|
||||||
- 解析 `/// <example>` 标签（示例代码）
|
|
||||||
- 解析 `/// <see cref=""/>` 标签（交叉引用）
|
|
||||||
|
|
||||||
4. **生成 Markdown 文档**
|
|
||||||
- 根据 `template.md` 填充内容
|
|
||||||
- 转义泛型符号（`<T>` → `<T>`）
|
|
||||||
- 生成使用示例（基于 API 签名）
|
|
||||||
- 添加相关文档链接
|
|
||||||
|
|
||||||
5. **确定输出路径**
|
|
||||||
- 根据命名空间确定模块（Core/Game/Godot/SourceGenerators）
|
|
||||||
- 输出到 `docs/zh-CN/api-reference/<模块>/<类名>.md`
|
|
||||||
|
|
||||||
6. **更新 VitePress 配置**
|
|
||||||
- 调用共享脚本 `update-vitepress-nav.sh`
|
|
||||||
- 在侧边栏配置中添加新文档条目
|
|
||||||
|
|
||||||
7. **验证文档质量**
|
|
||||||
- 检查 Frontmatter 格式
|
|
||||||
- 验证内部链接
|
|
||||||
- 确保代码块语法正确
|
|
||||||
|
|
||||||
## 输出规范
|
|
||||||
|
|
||||||
### Frontmatter 格式
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
title: 类名
|
|
||||||
description: 从 XML <summary> 提取的简短描述
|
|
||||||
outline: deep
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
### 文档结构
|
|
||||||
|
|
||||||
1. **标题**：使用类名作为一级标题
|
|
||||||
2. **概述**：XML summary 内容
|
|
||||||
3. **命名空间和程序集信息**
|
|
||||||
4. **继承链**（如果适用）
|
|
||||||
5. **构造函数**（如果有）
|
|
||||||
6. **公共方法**（按字母顺序）
|
|
||||||
7. **公共属性**（按字母顺序）
|
|
||||||
8. **公共事件**（如果有）
|
|
||||||
9. **使用示例**（自动生成）
|
|
||||||
10. **另请参阅**（相关类型链接）
|
|
||||||
|
|
||||||
### 代码块格式
|
|
||||||
|
|
||||||
所有 C# 代码块必须使用：
|
|
||||||
```markdown
|
|
||||||
\`\`\`csharp
|
|
||||||
// 代码内容
|
|
||||||
\`\`\`
|
|
||||||
```
|
|
||||||
|
|
||||||
### 泛型符号转义
|
|
||||||
|
|
||||||
- `List<T>` → `List<T>`
|
|
||||||
- `Dictionary<K, V>` → `Dictionary<K, V>`
|
|
||||||
- `IEnumerable<T>` → `IEnumerable<T>`
|
|
||||||
|
|
||||||
### 内部链接格式
|
|
||||||
|
|
||||||
- 相对路径：`[Architecture](./architecture.md)`
|
|
||||||
- 绝对路径：`[Core 架构](/zh-CN/core/architecture)`
|
|
||||||
- 锚点链接：`[构造函数](#构造函数)`
|
|
||||||
|
|
||||||
## 前置条件
|
|
||||||
|
|
||||||
1. 项目必须有 VitePress 配置文件（`docs/.vitepress/config.mts`）
|
|
||||||
2. 目标 C# 文件必须存在且可读
|
|
||||||
3. C# 文件必须包含 XML 文档注释（`///`）
|
|
||||||
4. 文件必须包含至少一个公共类型
|
|
||||||
|
|
||||||
## 配置选项
|
|
||||||
|
|
||||||
### 自动检测模块
|
|
||||||
|
|
||||||
根据命名空间自动确定模块：
|
|
||||||
- `GFramework.Core.*` → `core`
|
|
||||||
- `GFramework.Game.*` → `game`
|
|
||||||
- `GFramework.Godot.*` → `godot`
|
|
||||||
- `GFramework.SourceGenerators.*` → `source-generators`
|
|
||||||
|
|
||||||
### 示例生成策略
|
|
||||||
|
|
||||||
- **基本用法**：最简单的 API 调用
|
|
||||||
- **常见场景**：实际应用案例
|
|
||||||
- **高级用法**：复杂配置（如果适用）
|
|
||||||
|
|
||||||
## 示例输出
|
|
||||||
|
|
||||||
参考 `examples/` 目录中的示例文档：
|
|
||||||
- `class-example.md` - 类文档示例
|
|
||||||
- `interface-example.md` - 接口文档示例
|
|
||||||
- `enum-example.md` - 枚举文档示例
|
|
||||||
|
|
||||||
## 注意事项
|
|
||||||
|
|
||||||
1. **仅使用 XML 注释**：不对缺失的注释进行 AI 补充
|
|
||||||
2. **仅提取公共成员**：忽略 `internal`、`private`、`protected` 成员
|
|
||||||
3. **保持文档同步**：文档内容直接来源于代码，确保准确性
|
|
||||||
4. **遵循项目风格**：参考现有文档的格式和术语
|
|
||||||
|
|
||||||
## 相关 Skills
|
|
||||||
|
|
||||||
- `/vitepress-validate` - 验证生成的文档质量
|
|
||||||
- `/vitepress-batch-api` - 批量生成整个模块的 API 文档
|
|
||||||
|
|
||||||
## 技术细节
|
|
||||||
|
|
||||||
### XML 注释标签映射
|
|
||||||
|
|
||||||
| XML 标签 | Markdown 输出 |
|
|
||||||
|---------|--------------|
|
|
||||||
| `<summary>` | 概述章节 |
|
|
||||||
| `<param name="x">` | 参数列表 |
|
|
||||||
| `<returns>` | 返回值说明 |
|
|
||||||
| `<exception cref="T">` | 异常列表 |
|
|
||||||
| `<example>` | 示例代码块 |
|
|
||||||
| `<see cref="T"/>` | 内部链接 |
|
|
||||||
| `<remarks>` | 备注章节 |
|
|
||||||
|
|
||||||
### 成员签名格式
|
|
||||||
|
|
||||||
**方法**：
|
|
||||||
```markdown
|
|
||||||
### MethodName
|
|
||||||
|
|
||||||
描述内容
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
\`\`\`csharp
|
|
||||||
public ReturnType MethodName(ParamType param)
|
|
||||||
\`\`\`
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `param` (ParamType): 参数说明
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (ReturnType): 返回值说明
|
|
||||||
```
|
|
||||||
|
|
||||||
**属性**：
|
|
||||||
```markdown
|
|
||||||
### PropertyName
|
|
||||||
|
|
||||||
描述内容
|
|
||||||
|
|
||||||
**类型**：`PropertyType`
|
|
||||||
|
|
||||||
**访问**：get / set
|
|
||||||
```
|
|
||||||
|
|
||||||
## 故障排除
|
|
||||||
|
|
||||||
### 问题：找不到 XML 注释
|
|
||||||
**解决方案**：确保 C# 文件包含 `///` 注释，而不是 `//` 或 `/* */`
|
|
||||||
|
|
||||||
### 问题：泛型符号显示错误
|
|
||||||
**解决方案**：VitePress 配置中已包含 `safeGenericEscapePlugin`，确保正确转义
|
|
||||||
|
|
||||||
### 问题：侧边栏未更新
|
|
||||||
**解决方案**：检查 `update-vitepress-nav.sh` 脚本是否正确执行
|
|
||||||
|
|
||||||
## 版本历史
|
|
||||||
|
|
||||||
- v1.0.0 - 初始版本，支持类、接口、枚举的文档生成
|
|
||||||
@ -1,252 +0,0 @@
|
|||||||
---
|
|
||||||
title: Architecture
|
|
||||||
description: 架构基类，提供系统、模型、工具等组件的注册与管理功能。专注于生命周期管理、初始化流程控制和架构阶段转换。
|
|
||||||
outline: deep
|
|
||||||
---
|
|
||||||
|
|
||||||
# Architecture
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
架构基类，提供系统、模型、工具等组件的注册与管理功能。专注于生命周期管理、初始化流程控制和架构阶段转换。
|
|
||||||
|
|
||||||
**命名空间**：`GFramework.Core.architecture`
|
|
||||||
**程序集**：`GFramework.Core`
|
|
||||||
**继承**：`Object` → `Architecture`
|
|
||||||
**实现**：`IArchitecture`
|
|
||||||
|
|
||||||
## 构造函数
|
|
||||||
|
|
||||||
### Architecture
|
|
||||||
|
|
||||||
创建架构实例。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
public Architecture(
|
|
||||||
IArchitectureConfiguration? configuration = null,
|
|
||||||
IEnvironment? environment = null,
|
|
||||||
IArchitectureServices? services = null,
|
|
||||||
IArchitectureContext? context = null
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `configuration` (IArchitectureConfiguration?): 架构配置对象，为 null 时使用默认配置
|
|
||||||
- `environment` (IEnvironment?): 环境配置对象，为 null 时使用默认环境
|
|
||||||
- `services` (IArchitectureServices?): 架构服务对象，为 null 时创建新实例
|
|
||||||
- `context` (IArchitectureContext?): 架构上下文对象，为 null 时创建新实例
|
|
||||||
|
|
||||||
## 公共方法
|
|
||||||
|
|
||||||
### Initialize
|
|
||||||
|
|
||||||
同步初始化架构，阻塞当前线程直到初始化完成。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
public void Initialize()
|
|
||||||
```
|
|
||||||
|
|
||||||
**特点**：
|
|
||||||
- 阻塞式初始化
|
|
||||||
- 适用于简单场景或控制台应用
|
|
||||||
- 初始化失败时抛出异常并进入 `FailedInitialization` 阶段
|
|
||||||
|
|
||||||
### InitializeAsync
|
|
||||||
|
|
||||||
异步初始化架构，返回 Task 以便调用者可以等待初始化完成。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
public async Task InitializeAsync()
|
|
||||||
```
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (Task): 表示异步初始化操作的任务
|
|
||||||
|
|
||||||
**特点**：
|
|
||||||
- 非阻塞式初始化
|
|
||||||
- 支持异步组件初始化
|
|
||||||
- 适用于需要异步加载资源的场景
|
|
||||||
|
|
||||||
### InstallModule
|
|
||||||
|
|
||||||
安装架构模块，用于扩展架构功能。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
public IArchitectureModule InstallModule(IArchitectureModule module)
|
|
||||||
```
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `module` (IArchitectureModule): 要安装的模块实例
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (IArchitectureModule): 返回安装的模块实例
|
|
||||||
|
|
||||||
### RegisterSystem
|
|
||||||
|
|
||||||
注册系统组件到架构中。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
public void RegisterSystem<TSystem>(TSystem system) where TSystem : ISystem
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `TSystem`: 系统类型，必须实现 ISystem 接口
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `system` (TSystem): 要注册的系统实例
|
|
||||||
|
|
||||||
### RegisterModel
|
|
||||||
|
|
||||||
注册模型组件到架构中。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
public void RegisterModel<TModel>(TModel model) where TModel : IModel
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `TModel`: 模型类型，必须实现 IModel 接口
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `model` (TModel): 要注册的模型实例
|
|
||||||
|
|
||||||
### RegisterUtility
|
|
||||||
|
|
||||||
注册工具组件到架构中。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
public void RegisterUtility<TUtility>(TUtility utility) where TUtility : IUtility
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `TUtility`: 工具类型，必须实现 IUtility 接口
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `utility` (TUtility): 要注册的工具实例
|
|
||||||
|
|
||||||
### SendCommand
|
|
||||||
|
|
||||||
发送并执行命令。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
public void SendCommand(ICommand command)
|
|
||||||
```
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `command` (ICommand): 要执行的命令实例
|
|
||||||
|
|
||||||
### SendCommand<TResult>
|
|
||||||
|
|
||||||
发送并执行带返回值的命令。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
public TResult SendCommand<TResult>(ICommand<TResult> command)
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `TResult`: 命令返回值类型
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `command` (ICommand<TResult>): 要执行的命令实例
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (TResult): 命令执行结果
|
|
||||||
|
|
||||||
## 公共属性
|
|
||||||
|
|
||||||
### CurrentPhase
|
|
||||||
|
|
||||||
获取当前架构的阶段。
|
|
||||||
|
|
||||||
**类型**：`ArchitecturePhase`
|
|
||||||
**访问**：get
|
|
||||||
|
|
||||||
### Context
|
|
||||||
|
|
||||||
获取架构上下文，提供对架构服务的访问。
|
|
||||||
|
|
||||||
**类型**：`IArchitectureContext`
|
|
||||||
**访问**：get
|
|
||||||
|
|
||||||
### IsReady
|
|
||||||
|
|
||||||
获取一个布尔值，指示当前架构是否处于就绪状态。
|
|
||||||
|
|
||||||
**类型**：`bool`
|
|
||||||
**访问**：get
|
|
||||||
|
|
||||||
## 使用示例
|
|
||||||
|
|
||||||
### 基本用法
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
// 1. 定义你的架构（继承 Architecture 基类）
|
|
||||||
public class GameArchitecture : Architecture
|
|
||||||
{
|
|
||||||
protected override void Init()
|
|
||||||
{
|
|
||||||
// 注册 Model
|
|
||||||
RegisterModel(new PlayerModel());
|
|
||||||
RegisterModel(new InventoryModel());
|
|
||||||
|
|
||||||
// 注册 System
|
|
||||||
RegisterSystem(new GameplaySystem());
|
|
||||||
RegisterSystem(new SaveSystem());
|
|
||||||
|
|
||||||
// 注册 Utility
|
|
||||||
RegisterUtility(new StorageUtility());
|
|
||||||
RegisterUtility(new TimeUtility());
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// 2. 创建并初始化架构
|
|
||||||
var architecture = new GameArchitecture();
|
|
||||||
architecture.Initialize();
|
|
||||||
|
|
||||||
// 3. 等待架构就绪
|
|
||||||
await architecture.WaitUntilReadyAsync();
|
|
||||||
```
|
|
||||||
|
|
||||||
### 异步初始化
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
var architecture = new GameArchitecture();
|
|
||||||
await architecture.InitializeAsync(); // 异步等待初始化完成
|
|
||||||
|
|
||||||
// 检查架构是否已就绪
|
|
||||||
if (architecture.IsReady)
|
|
||||||
{
|
|
||||||
Console.WriteLine("架构已就绪，可以开始游戏");
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 使用自定义配置
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
var config = new ArchitectureConfiguration
|
|
||||||
{
|
|
||||||
ArchitectureProperties = new ArchitectureProperties
|
|
||||||
{
|
|
||||||
StrictPhaseValidation = true, // 启用严格阶段验证
|
|
||||||
AllowLateRegistration = false // 禁止就绪后注册组件
|
|
||||||
}
|
|
||||||
};
|
|
||||||
|
|
||||||
var architecture = new GameArchitecture(configuration: config);
|
|
||||||
architecture.Initialize();
|
|
||||||
```
|
|
||||||
|
|
||||||
## 另请参阅
|
|
||||||
|
|
||||||
- [IArchitecture](./iarchitecture.md) - 架构接口
|
|
||||||
- [ArchitecturePhase](./architecture-phase.md) - 架构阶段枚举
|
|
||||||
- [IArchitectureModule](./iarchitecture-module.md) - 架构模块接口
|
|
||||||
- [架构组件](/zh-CN/core/architecture) - 架构使用指南
|
|
||||||
@ -1,193 +0,0 @@
|
|||||||
---
|
|
||||||
title: ArchitecturePhase
|
|
||||||
description: 架构阶段枚举，定义了架构生命周期的各个阶段。
|
|
||||||
outline: deep
|
|
||||||
---
|
|
||||||
|
|
||||||
# ArchitecturePhase
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
架构阶段枚举，定义了架构生命周期的各个阶段。
|
|
||||||
|
|
||||||
**命名空间**：`GFramework.Core.Abstractions.enums`
|
|
||||||
**程序集**：`GFramework.Core.Abstractions`
|
|
||||||
**基础类型**：`Enum`
|
|
||||||
|
|
||||||
## 枚举值
|
|
||||||
|
|
||||||
### None
|
|
||||||
|
|
||||||
初始阶段，架构尚未开始初始化。
|
|
||||||
|
|
||||||
**值**：`0`
|
|
||||||
|
|
||||||
### BeforeUtilityInit
|
|
||||||
|
|
||||||
工具初始化前阶段。
|
|
||||||
|
|
||||||
**值**：`1`
|
|
||||||
|
|
||||||
### AfterUtilityInit
|
|
||||||
|
|
||||||
工具初始化后阶段。
|
|
||||||
|
|
||||||
**值**：`2`
|
|
||||||
|
|
||||||
### BeforeModelInit
|
|
||||||
|
|
||||||
模型初始化前阶段。
|
|
||||||
|
|
||||||
**值**：`3`
|
|
||||||
|
|
||||||
### AfterModelInit
|
|
||||||
|
|
||||||
模型初始化后阶段。
|
|
||||||
|
|
||||||
**值**：`4`
|
|
||||||
|
|
||||||
### BeforeSystemInit
|
|
||||||
|
|
||||||
系统初始化前阶段。
|
|
||||||
|
|
||||||
**值**：`5`
|
|
||||||
|
|
||||||
### AfterSystemInit
|
|
||||||
|
|
||||||
系统初始化后阶段。
|
|
||||||
|
|
||||||
**值**：`6`
|
|
||||||
|
|
||||||
### Ready
|
|
||||||
|
|
||||||
就绪状态，架构已完全初始化并可以使用。
|
|
||||||
|
|
||||||
**值**：`7`
|
|
||||||
|
|
||||||
### FailedInitialization
|
|
||||||
|
|
||||||
初始化失败状态。
|
|
||||||
|
|
||||||
**值**：`8`
|
|
||||||
|
|
||||||
### Destroying
|
|
||||||
|
|
||||||
正在销毁阶段。
|
|
||||||
|
|
||||||
**值**：`9`
|
|
||||||
|
|
||||||
### Destroyed
|
|
||||||
|
|
||||||
已销毁阶段。
|
|
||||||
|
|
||||||
**值**：`10`
|
|
||||||
|
|
||||||
## 使用示例
|
|
||||||
|
|
||||||
### 检查架构阶段
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
var architecture = new GameArchitecture();
|
|
||||||
architecture.Initialize();
|
|
||||||
|
|
||||||
// 检查架构是否已就绪
|
|
||||||
if (architecture.CurrentPhase == ArchitecturePhase.Ready)
|
|
||||||
{
|
|
||||||
Console.WriteLine("架构已就绪，可以开始游戏");
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 监听阶段变化
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public class PhaseMonitor : IArchitectureLifecycle
|
|
||||||
{
|
|
||||||
public void OnPhase(ArchitecturePhase phase, IArchitecture architecture)
|
|
||||||
{
|
|
||||||
switch (phase)
|
|
||||||
{
|
|
||||||
case ArchitecturePhase.BeforeUtilityInit:
|
|
||||||
Console.WriteLine("开始初始化工具");
|
|
||||||
break;
|
|
||||||
case ArchitecturePhase.AfterUtilityInit:
|
|
||||||
Console.WriteLine("工具初始化完成");
|
|
||||||
break;
|
|
||||||
case ArchitecturePhase.BeforeModelInit:
|
|
||||||
Console.WriteLine("开始初始化模型");
|
|
||||||
break;
|
|
||||||
case ArchitecturePhase.AfterModelInit:
|
|
||||||
Console.WriteLine("模型初始化完成");
|
|
||||||
break;
|
|
||||||
case ArchitecturePhase.BeforeSystemInit:
|
|
||||||
Console.WriteLine("开始初始化系统");
|
|
||||||
break;
|
|
||||||
case ArchitecturePhase.AfterSystemInit:
|
|
||||||
Console.WriteLine("系统初始化完成");
|
|
||||||
break;
|
|
||||||
case ArchitecturePhase.Ready:
|
|
||||||
Console.WriteLine("架构就绪");
|
|
||||||
break;
|
|
||||||
case ArchitecturePhase.FailedInitialization:
|
|
||||||
Console.WriteLine("架构初始化失败");
|
|
||||||
break;
|
|
||||||
case ArchitecturePhase.Destroying:
|
|
||||||
Console.WriteLine("架构正在销毁");
|
|
||||||
break;
|
|
||||||
case ArchitecturePhase.Destroyed:
|
|
||||||
Console.WriteLine("架构已销毁");
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// 注册监听器
|
|
||||||
var architecture = new GameArchitecture();
|
|
||||||
architecture.RegisterLifecycleHook(new PhaseMonitor());
|
|
||||||
architecture.Initialize();
|
|
||||||
```
|
|
||||||
|
|
||||||
### 等待特定阶段
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public async Task WaitForReady(IArchitecture architecture)
|
|
||||||
{
|
|
||||||
while (architecture.CurrentPhase != ArchitecturePhase.Ready)
|
|
||||||
{
|
|
||||||
if (architecture.CurrentPhase == ArchitecturePhase.FailedInitialization)
|
|
||||||
{
|
|
||||||
throw new Exception("架构初始化失败");
|
|
||||||
}
|
|
||||||
|
|
||||||
await Task.Delay(100);
|
|
||||||
}
|
|
||||||
|
|
||||||
Console.WriteLine("架构已就绪");
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 阶段转换顺序
|
|
||||||
|
|
||||||
正常初始化流程的阶段转换顺序：
|
|
||||||
|
|
||||||
1. `None` → `BeforeUtilityInit`
|
|
||||||
2. `BeforeUtilityInit` → `AfterUtilityInit`
|
|
||||||
3. `AfterUtilityInit` → `BeforeModelInit`
|
|
||||||
4. `BeforeModelInit` → `AfterModelInit`
|
|
||||||
5. `AfterModelInit` → `BeforeSystemInit`
|
|
||||||
6. `BeforeSystemInit` → `AfterSystemInit`
|
|
||||||
7. `AfterSystemInit` → `Ready`
|
|
||||||
|
|
||||||
销毁流程的阶段转换顺序：
|
|
||||||
|
|
||||||
1. `Ready` → `Destroying`
|
|
||||||
2. `Destroying` → `Destroyed`
|
|
||||||
|
|
||||||
异常流程：
|
|
||||||
|
|
||||||
- 任何阶段 → `FailedInitialization`（初始化过程中发生异常）
|
|
||||||
|
|
||||||
## 另请参阅
|
|
||||||
|
|
||||||
- [Architecture](./architecture.md) - 架构基类
|
|
||||||
- [IArchitectureLifecycle](./iarchitecture-lifecycle.md) - 生命周期钩子接口
|
|
||||||
- [架构组件](/zh-CN/core/architecture) - 架构使用指南
|
|
||||||
@ -1,290 +0,0 @@
|
|||||||
---
|
|
||||||
title: IArchitecture
|
|
||||||
description: 架构接口，定义了框架的核心功能契约。
|
|
||||||
outline: deep
|
|
||||||
---
|
|
||||||
|
|
||||||
# IArchitecture
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
架构接口，定义了框架的核心功能契约。
|
|
||||||
|
|
||||||
**命名空间**：`GFramework.Core.Abstractions.architecture`
|
|
||||||
**程序集**：`GFramework.Core.Abstractions`
|
|
||||||
**实现类**：[Architecture](./architecture.md)
|
|
||||||
|
|
||||||
## 公共方法
|
|
||||||
|
|
||||||
### RegisterSystem<TSystem>
|
|
||||||
|
|
||||||
注册系统组件到架构中。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
void RegisterSystem<TSystem>(TSystem system) where TSystem : ISystem
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `TSystem`: 系统类型，必须实现 ISystem 接口
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `system` (TSystem): 要注册的系统实例
|
|
||||||
|
|
||||||
### RegisterModel<TModel>
|
|
||||||
|
|
||||||
注册模型组件到架构中。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
void RegisterModel<TModel>(TModel model) where TModel : IModel
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `TModel`: 模型类型，必须实现 IModel 接口
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `model` (TModel): 要注册的模型实例
|
|
||||||
|
|
||||||
### RegisterUtility<TUtility>
|
|
||||||
|
|
||||||
注册工具组件到架构中。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
void RegisterUtility<TUtility>(TUtility utility) where TUtility : IUtility
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `TUtility`: 工具类型，必须实现 IUtility 接口
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `utility` (TUtility): 要注册的工具实例
|
|
||||||
|
|
||||||
### GetModel<T>
|
|
||||||
|
|
||||||
从容器中获取已注册的模型。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
T GetModel<T>() where T : class, IModel
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `T`: 模型类型
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (T): 模型实例
|
|
||||||
|
|
||||||
### GetSystem<T>
|
|
||||||
|
|
||||||
从容器中获取已注册的系统。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
T GetSystem<T>() where T : class, ISystem
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `T`: 系统类型
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (T): 系统实例
|
|
||||||
|
|
||||||
### GetUtility<T>
|
|
||||||
|
|
||||||
从容器中获取已注册的工具。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
T GetUtility<T>() where T : class, IUtility
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `T`: 工具类型
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (T): 工具实例
|
|
||||||
|
|
||||||
### SendCommand
|
|
||||||
|
|
||||||
发送并执行命令。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
void SendCommand(ICommand command)
|
|
||||||
```
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `command` (ICommand): 要执行的命令实例
|
|
||||||
|
|
||||||
### SendCommand<TResult>
|
|
||||||
|
|
||||||
发送并执行带返回值的命令。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
TResult SendCommand<TResult>(ICommand<TResult> command)
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `TResult`: 命令返回值类型
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `command` (ICommand<TResult>): 要执行的命令实例
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (TResult): 命令执行结果
|
|
||||||
|
|
||||||
### SendQuery<TResult>
|
|
||||||
|
|
||||||
发送并执行查询。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
TResult SendQuery<TResult>(IQuery<TResult> query)
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `TResult`: 查询返回值类型
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `query` (IQuery<TResult>): 要执行的查询实例
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (TResult): 查询结果
|
|
||||||
|
|
||||||
### SendEvent<T>
|
|
||||||
|
|
||||||
发送事件（无参数）。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
void SendEvent<T>() where T : new()
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `T`: 事件类型，必须有无参构造函数
|
|
||||||
|
|
||||||
### SendEvent<T>
|
|
||||||
|
|
||||||
发送事件（带参数）。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
void SendEvent<T>(T e)
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `T`: 事件类型
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `e` (T): 事件实例
|
|
||||||
|
|
||||||
### RegisterEvent<T>
|
|
||||||
|
|
||||||
注册事件监听器。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
IUnRegister RegisterEvent<T>(Action<T> onEvent)
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `T`: 事件类型
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `onEvent` (Action<T>): 事件处理回调
|
|
||||||
|
|
||||||
**返回值**：
|
|
||||||
- (IUnRegister): 用于注销事件的对象
|
|
||||||
|
|
||||||
### UnRegisterEvent<T>
|
|
||||||
|
|
||||||
注销事件监听器。
|
|
||||||
|
|
||||||
**签名**：
|
|
||||||
```csharp
|
|
||||||
void UnRegisterEvent<T>(Action<T> onEvent)
|
|
||||||
```
|
|
||||||
|
|
||||||
**类型参数**：
|
|
||||||
- `T`: 事件类型
|
|
||||||
|
|
||||||
**参数**：
|
|
||||||
- `onEvent` (Action<T>): 要注销的事件处理回调
|
|
||||||
|
|
||||||
## 公共属性
|
|
||||||
|
|
||||||
### CurrentPhase
|
|
||||||
|
|
||||||
获取当前架构的阶段。
|
|
||||||
|
|
||||||
**类型**：`ArchitecturePhase`
|
|
||||||
**访问**：get
|
|
||||||
|
|
||||||
### Context
|
|
||||||
|
|
||||||
获取架构上下文。
|
|
||||||
|
|
||||||
**类型**：`IArchitectureContext`
|
|
||||||
**访问**：get
|
|
||||||
|
|
||||||
## 使用示例
|
|
||||||
|
|
||||||
### 在 Controller 中使用
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public class GameController : IController
|
|
||||||
{
|
|
||||||
public IArchitecture GetArchitecture() => GameArchitecture.Interface;
|
|
||||||
|
|
||||||
public void Start()
|
|
||||||
{
|
|
||||||
// 获取 Model
|
|
||||||
var playerModel = this.GetModel<PlayerModel>();
|
|
||||||
|
|
||||||
// 发送命令
|
|
||||||
this.SendCommand(new StartGameCommand());
|
|
||||||
|
|
||||||
// 发送查询
|
|
||||||
var score = this.SendQuery(new GetScoreQuery());
|
|
||||||
|
|
||||||
// 注册事件
|
|
||||||
this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);
|
|
||||||
}
|
|
||||||
|
|
||||||
private void OnPlayerDied(PlayerDiedEvent e)
|
|
||||||
{
|
|
||||||
// 处理玩家死亡事件
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 实现自定义架构
|
|
||||||
|
|
||||||
```csharp
|
|
||||||
public class GameArchitecture : Architecture
|
|
||||||
{
|
|
||||||
// 单例访问
|
|
||||||
public static IArchitecture Interface { get; private set; }
|
|
||||||
|
|
||||||
protected override void Init()
|
|
||||||
{
|
|
||||||
Interface = this;
|
|
||||||
|
|
||||||
// 注册组件
|
|
||||||
RegisterModel(new PlayerModel());
|
|
||||||
RegisterSystem(new GameplaySystem());
|
|
||||||
RegisterUtility(new StorageUtility());
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 另请参阅
|
|
||||||
|
|
||||||
- [Architecture](./architecture.md) - 架构基类实现
|
|
||||||
- [IModel](./imodel.md) - 模型接口
|
|
||||||
- [ISystem](./isystem.md) - 系统接口
|
|
||||||
- [IUtility](./iutility.md) - 工具接口
|
|
||||||
- [架构组件](/zh-CN/core/architecture) - 架构使用指南
|
|
||||||
@ -1,37 +0,0 @@
|
|||||||
---
|
|
||||||
title: {{CLASS_NAME}}
|
|
||||||
description: {{XML_SUMMARY}}
|
|
||||||
outline: deep
|
|
||||||
---
|
|
||||||
|
|
||||||
# {{CLASS_NAME}}
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
{{XML_SUMMARY}}
|
|
||||||
|
|
||||||
**命名空间**：`{{NAMESPACE}}`
|
|
||||||
**程序集**：`{{ASSEMBLY}}`
|
|
||||||
{{INHERITANCE_CHAIN}}
|
|
||||||
|
|
||||||
## 构造函数
|
|
||||||
|
|
||||||
{{CONSTRUCTORS}}
|
|
||||||
|
|
||||||
## 公共方法
|
|
||||||
|
|
||||||
{{PUBLIC_METHODS}}
|
|
||||||
|
|
||||||
## 公共属性
|
|
||||||
|
|
||||||
{{PUBLIC_PROPERTIES}}
|
|
||||||
|
|
||||||
{{PUBLIC_EVENTS}}
|
|
||||||
|
|
||||||
## 使用示例
|
|
||||||
|
|
||||||
{{AUTO_GENERATED_EXAMPLES}}
|
|
||||||
|
|
||||||
## 另请参阅
|
|
||||||
|
|
||||||
{{RELATED_TYPES}}
|
|
||||||
@ -1,364 +0,0 @@
|
|||||||
# VitePress 批量 API 文档生成
|
|
||||||
|
|
||||||
为整个模块批量生成 API 参考文档，提高文档生成效率。
|
|
||||||
|
|
||||||
## 用途
|
|
||||||
|
|
||||||
此 skill 用于批量生成模块的 API 文档，适用于：
|
|
||||||
- 初始化模块文档
|
|
||||||
- 更新整个模块的文档
|
|
||||||
- 为新模块快速生成文档
|
|
||||||
- 重新生成所有 API 文档
|
|
||||||
|
|
||||||
## 调用方式
|
|
||||||
|
|
||||||
```bash
|
|
||||||
/vitepress-batch-api <模块名>
|
|
||||||
```
|
|
||||||
|
|
||||||
**示例**：
|
|
||||||
```bash
|
|
||||||
/vitepress-batch-api Core
|
|
||||||
/vitepress-batch-api Game
|
|
||||||
/vitepress-batch-api Godot
|
|
||||||
/vitepress-batch-api SourceGenerators
|
|
||||||
```
|
|
||||||
|
|
||||||
## 工作流程
|
|
||||||
|
|
||||||
1. **扫描模块目录**
|
|
||||||
- 根据模块名确定源代码目录
|
|
||||||
- 递归扫描所有 C# 文件
|
|
||||||
|
|
||||||
2. **过滤目标文件**
|
|
||||||
- 仅包含公共类型（public class/interface/enum/struct）
|
|
||||||
- 排除内部类型（internal）
|
|
||||||
- 排除生成的代码（*.g.cs、*.Designer.cs）
|
|
||||||
- 排除测试文件（*.Tests.cs）
|
|
||||||
|
|
||||||
3. **批量生成文档**
|
|
||||||
- 为每个类型调用 `/vitepress-api-doc`
|
|
||||||
- 显示进度信息
|
|
||||||
- 收集生成结果
|
|
||||||
|
|
||||||
4. **生成模块索引页**
|
|
||||||
- 创建 `index.md` 列出所有 API
|
|
||||||
- 按类别分组（类、接口、枚举）
|
|
||||||
- 添加简短描述
|
|
||||||
|
|
||||||
5. **批量更新导航**
|
|
||||||
- 在 VitePress 配置中添加所有新文档
|
|
||||||
- 保持字母顺序
|
|
||||||
- 更新模块索引
|
|
||||||
|
|
||||||
6. **生成摘要报告**
|
|
||||||
- 统计生成的文档数量
|
|
||||||
- 列出成功和失败的文件
|
|
||||||
- 提供验证建议
|
|
||||||
|
|
||||||
## 输出规范
|
|
||||||
|
|
||||||
### 模块索引页格式
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
title: Core API 参考
|
|
||||||
description: GFramework.Core 模块的 API 参考文档
|
|
||||||
---
|
|
||||||
|
|
||||||
# Core API 参考
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
GFramework.Core 是框架的核心模块，提供架构基础、依赖注入、事件系统等核心功能。
|
|
||||||
|
|
||||||
## 类
|
|
||||||
|
|
||||||
- [Architecture](./architecture.md) - 架构基类
|
|
||||||
- [ArchitectureConfiguration](./architecture-configuration.md) - 架构配置
|
|
||||||
- [IocContainer](./ioc-container.md) - IoC 容器
|
|
||||||
|
|
||||||
## 接口
|
|
||||||
|
|
||||||
- [IArchitecture](./iarchitecture.md) - 架构接口
|
|
||||||
- [IModel](./imodel.md) - 模型接口
|
|
||||||
- [ISystem](./isystem.md) - 系统接口
|
|
||||||
|
|
||||||
## 枚举
|
|
||||||
|
|
||||||
- [ArchitecturePhase](./architecture-phase.md) - 架构阶段
|
|
||||||
```
|
|
||||||
|
|
||||||
### 目录结构
|
|
||||||
|
|
||||||
```
|
|
||||||
docs/zh-CN/api-reference/
|
|
||||||
├── core/
|
|
||||||
│ ├── index.md # 模块索引
|
|
||||||
│ ├── architecture.md
|
|
||||||
│ ├── iarchitecture.md
|
|
||||||
│ └── ...
|
|
||||||
├── game/
|
|
||||||
│ ├── index.md
|
|
||||||
│ └── ...
|
|
||||||
└── godot/
|
|
||||||
├── index.md
|
|
||||||
└── ...
|
|
||||||
```
|
|
||||||
|
|
||||||
## 模块映射
|
|
||||||
|
|
||||||
### 源代码目录映射
|
|
||||||
|
|
||||||
| 模块名 | 源代码目录 | 输出目录 |
|
|
||||||
|--------|-----------|---------|
|
|
||||||
| Core | `GFramework.Core/` | `docs/zh-CN/api-reference/core/` |
|
|
||||||
| Game | `GFramework.Game/` | `docs/zh-CN/api-reference/game/` |
|
|
||||||
| Godot | `GFramework.Godot/` | `docs/zh-CN/api-reference/godot/` |
|
|
||||||
| SourceGenerators | `GFramework.SourceGenerators/` | `docs/zh-CN/api-reference/source-generators/` |
|
|
||||||
|
|
||||||
### 命名空间映射
|
|
||||||
|
|
||||||
- `GFramework.Core.*` → Core 模块
|
|
||||||
- `GFramework.Game.*` → Game 模块
|
|
||||||
- `GFramework.Godot.*` → Godot 模块
|
|
||||||
- `GFramework.SourceGenerators.*` → SourceGenerators 模块
|
|
||||||
|
|
||||||
## 过滤规则
|
|
||||||
|
|
||||||
### 包含的文件
|
|
||||||
|
|
||||||
- 公共类（public class）
|
|
||||||
- 公共接口（public interface）
|
|
||||||
- 公共枚举（public enum）
|
|
||||||
- 公共结构体（public struct）
|
|
||||||
|
|
||||||
### 排除的文件
|
|
||||||
|
|
||||||
- 内部类型（internal）
|
|
||||||
- 生成的代码（`*.g.cs`、`*.Designer.cs`）
|
|
||||||
- 测试文件（`*.Tests.cs`、`*Test.cs`）
|
|
||||||
- 临时文件（`*.tmp.cs`）
|
|
||||||
- 编译器生成的文件（`AssemblyInfo.cs`）
|
|
||||||
|
|
||||||
### 排除的类型
|
|
||||||
|
|
||||||
- 编译器生成的类型（`<>c__DisplayClass`）
|
|
||||||
- 匿名类型
|
|
||||||
- 嵌套的私有类型
|
|
||||||
|
|
||||||
## 批量处理脚本
|
|
||||||
|
|
||||||
### batch-generate.sh
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
# 批量生成 API 文档
|
|
||||||
# 用法: batch-generate.sh <模块名>
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
MODULE="$1"
|
|
||||||
|
|
||||||
if [ -z "$MODULE" ]; then
|
|
||||||
echo "用法: $0 <模块名>"
|
|
||||||
echo "可用模块: Core, Game, Godot, SourceGenerators"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# 确定源代码目录
|
|
||||||
case "$MODULE" in
|
|
||||||
Core)
|
|
||||||
SOURCE_DIR="GFramework.Core"
|
|
||||||
;;
|
|
||||||
Game)
|
|
||||||
SOURCE_DIR="GFramework.Game"
|
|
||||||
;;
|
|
||||||
Godot)
|
|
||||||
SOURCE_DIR="GFramework.Godot"
|
|
||||||
;;
|
|
||||||
SourceGenerators)
|
|
||||||
SOURCE_DIR="GFramework.SourceGenerators"
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
echo "错误: 未知的模块: $MODULE"
|
|
||||||
exit 1
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
|
|
||||||
if [ ! -d "$SOURCE_DIR" ]; then
|
|
||||||
echo "错误: 源代码目录不存在: $SOURCE_DIR"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo "=========================================="
|
|
||||||
echo "批量生成 $MODULE 模块的 API 文档"
|
|
||||||
echo "=========================================="
|
|
||||||
echo ""
|
|
||||||
|
|
||||||
# 查找所有 C# 文件
|
|
||||||
FILES=$(find "$SOURCE_DIR" -name "*.cs" -type f \
|
|
||||||
! -name "*.g.cs" \
|
|
||||||
! -name "*.Designer.cs" \
|
|
||||||
! -name "*Test.cs" \
|
|
||||||
! -name "*.Tests.cs" \
|
|
||||||
! -name "AssemblyInfo.cs")
|
|
||||||
|
|
||||||
FILE_COUNT=$(echo "$FILES" | wc -l)
|
|
||||||
echo "找到 $FILE_COUNT 个文件"
|
|
||||||
echo ""
|
|
||||||
|
|
||||||
GENERATED=0
|
|
||||||
SKIPPED=0
|
|
||||||
FAILED=0
|
|
||||||
|
|
||||||
for FILE in $FILES; do
|
|
||||||
echo "处理: $FILE"
|
|
||||||
|
|
||||||
# 检查是否包含公共类型
|
|
||||||
if ! grep -q "public \(class\|interface\|enum\|struct\)" "$FILE"; then
|
|
||||||
echo " ⊘ 跳过（无公共类型）"
|
|
||||||
SKIPPED=$((SKIPPED + 1))
|
|
||||||
continue
|
|
||||||
fi
|
|
||||||
|
|
||||||
# 调用 vitepress-api-doc（由 AI 执行）
|
|
||||||
# /vitepress-api-doc "$FILE"
|
|
||||||
|
|
||||||
if [ $? -eq 0 ]; then
|
|
||||||
echo " ✓ 生成成功"
|
|
||||||
GENERATED=$((GENERATED + 1))
|
|
||||||
else
|
|
||||||
echo " ✗ 生成失败"
|
|
||||||
FAILED=$((FAILED + 1))
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo ""
|
|
||||||
done
|
|
||||||
|
|
||||||
echo "=========================================="
|
|
||||||
echo "批量生成完成"
|
|
||||||
echo "=========================================="
|
|
||||||
echo "总文件数: $FILE_COUNT"
|
|
||||||
echo "生成成功: $GENERATED"
|
|
||||||
echo "跳过: $SKIPPED"
|
|
||||||
echo "失败: $FAILED"
|
|
||||||
echo ""
|
|
||||||
|
|
||||||
if [ $FAILED -eq 0 ]; then
|
|
||||||
echo "✓ 所有文档生成成功"
|
|
||||||
exit 0
|
|
||||||
else
|
|
||||||
echo "✗ 部分文档生成失败"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
## 配置选项
|
|
||||||
|
|
||||||
### 过滤选项
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 包含内部类型
|
|
||||||
/vitepress-batch-api Core --include-internal
|
|
||||||
|
|
||||||
# 包含生成的代码
|
|
||||||
/vitepress-batch-api Core --include-generated
|
|
||||||
|
|
||||||
# 自定义过滤规则
|
|
||||||
/vitepress-batch-api Core --exclude "*.Tests.cs" --exclude "*.g.cs"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 输出选项
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 指定输出目录
|
|
||||||
/vitepress-batch-api Core --output docs/zh-CN/api-reference/core/
|
|
||||||
|
|
||||||
# 覆盖现有文档
|
|
||||||
/vitepress-batch-api Core --force
|
|
||||||
|
|
||||||
# 仅生成索引页
|
|
||||||
/vitepress-batch-api Core --index-only
|
|
||||||
```
|
|
||||||
|
|
||||||
### 并行处理
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 并行生成（加快速度）
|
|
||||||
/vitepress-batch-api Core --parallel 4
|
|
||||||
```
|
|
||||||
|
|
||||||
## 进度显示
|
|
||||||
|
|
||||||
### 实时进度
|
|
||||||
|
|
||||||
```
|
|
||||||
========================================
|
|
||||||
批量生成 Core 模块的 API 文档
|
|
||||||
========================================
|
|
||||||
|
|
||||||
找到 45 个文件
|
|||||||