mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
65d3634181
- 补充 config tool README 的 Quick Start 最小接入步骤并统一 schema subset 术语 - 更新 documentation-full-coverage-governance 的 tracking 与 trace，记录 PR #292 最新 review 结论和验证结果 - 补充工具模块的测试与 VSIX 打包验证结果，作为本轮 review 收口的最小验证证据
120 lines
3.8 KiB
Markdown
120 lines
3.8 KiB
Markdown
# GFramework Config Tool
|
|
|
|
VS Code extension for the GFramework AI-First config workflow.
|
|
|
|
## Purpose
|
|
|
|
This extension is the editor-side companion for the `GFramework.Game` config pipeline:
|
|
|
|
- `config/**/*.yaml`
|
|
- `schemas/**/*.schema.json`
|
|
- source-generated config types and tables
|
|
|
|
It is intended to speed up browsing, validation, lightweight form editing, and domain-level maintenance inside VS Code.
|
|
It is not a replacement for the runtime or generator packages, and it does not attempt to be a full JSON Schema editor.
|
|
|
|
## Recommended Workspace Layout
|
|
|
|
By default, the extension expects:
|
|
|
|
```text
|
|
GameProject/
|
|
├─ config/
|
|
│ ├─ monster/
|
|
│ │ ├─ slime.yaml
|
|
│ │ └─ goblin.yaml
|
|
│ └─ item/
|
|
│ └─ potion.yaml
|
|
└─ schemas/
|
|
├─ monster.schema.json
|
|
└─ item.schema.json
|
|
```
|
|
|
|
## What It Adds
|
|
|
|
### Explorer View
|
|
|
|
- Browse config files from the workspace `config/` directory
|
|
- Group files by config domain
|
|
- Open matching schema files from `schemas/`
|
|
|
|
### File-Level Actions
|
|
|
|
- Open raw YAML
|
|
- Open the matching schema
|
|
- Open a lightweight form preview
|
|
|
|
### Domain-Level Actions
|
|
|
|
- Batch edit one config domain across multiple files for top-level scalar and scalar-array fields
|
|
- Run validation across the current workspace config surface
|
|
|
|
### Form / Validation Support
|
|
|
|
- Localize extension UI text in English and Simplified Chinese, including the form preview, prompts, and notifications
|
|
- Render existing YAML comments in the form preview and edit per-field YAML comments directly from the form
|
|
- Jump from reference fields to the referenced schema, config domain, or direct config file when a reference value is
|
|
present
|
|
- Initialize empty config files from schema-derived example YAML
|
|
- Surface schema metadata such as `title`, `description`, `default`, `enum`, and `x-gframework-ref-table` in the
|
|
lightweight editors
|
|
|
|
## Validation Coverage
|
|
|
|
The extension currently validates the repository's current schema subset:
|
|
|
|
- required properties in nested objects
|
|
- unknown properties in nested objects
|
|
- scalar compatibility for `integer`, `number`, `boolean`, and `string`
|
|
- scalar arrays with scalar item type checks
|
|
- arrays of objects whose items use the same supported subset recursively
|
|
- scalar `enum` constraints and scalar-array item `enum` constraints
|
|
|
|
## Workspace Settings
|
|
|
|
```json
|
|
{
|
|
"gframeworkConfig.configPath": "config",
|
|
"gframeworkConfig.schemasPath": "schemas"
|
|
}
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
1. Install the extension in VS Code and open the workspace that contains your `config/` and `schemas/` directories.
|
|
2. Keep the default workspace layout, or set `gframeworkConfig.configPath` and `gframeworkConfig.schemasPath` to your
|
|
project-specific paths.
|
|
3. Open the `GFramework Config` explorer view and select a config file or domain.
|
|
4. Run validation first to confirm the current YAML files still match the supported schema subset.
|
|
5. Open the lightweight form preview or domain batch editing actions, then fall back to raw YAML for deeper nested edits
|
|
when needed.
|
|
|
|
## Documentation
|
|
|
|
- Chinese adoption guide: [`docs/zh-CN/game/config-tool.md`](../../docs/zh-CN/game/config-tool.md)
|
|
- Related config runtime guide: [`docs/zh-CN/game/config-system.md`](../../docs/zh-CN/game/config-system.md)
|
|
|
|
## Current Constraints
|
|
|
|
- Multi-root workspaces use the first workspace folder
|
|
- Validation only covers the repository's current schema subset
|
|
- Form preview supports object-array editing, but nested object arrays inside array items still fall back to raw YAML
|
|
- Batch editing remains limited to top-level scalar fields and top-level scalar arrays
|
|
|
|
## Local Testing
|
|
|
|
```bash
|
|
cd tools/gframework-config-tool
|
|
bun install
|
|
bun run test
|
|
```
|
|
|
|
## Packaging And Publishing
|
|
|
|
```bash
|
|
cd tools/gframework-config-tool
|
|
bun install
|
|
bun run package:vsix
|
|
VSCE_PAT=your_marketplace_pat bun run publish:marketplace
|
|
```
|