docs(config): 添加游戏内容配置系统完整文档

- 新增游戏内容配置系统详细介绍文档
- 包含 YAML 配置源文件支持说明
- 提供 JSON Schema 结构描述功能说明
- 说明一对象一文件的目录组织方式
- 介绍运行时只读查询功能特性
- 详细说明 Runtime / Generator / Tooling 共享支持的约束类型
- 提供 Source Generator 生成配置类型的完整说明
- 包含 VS Code 插件功能详细介绍
- 提供推荐目录结构和 Schema 示例
- 说明 YAML 示例格式和接入模板
- 详细说明 Godot 文本配置桥接功能
- 提供运行时读取模板和生成查询辅助说明
- 包含 Architecture 接入模板和热重载配置说明
- 详细说明运行时校验行为和跨表引用机制
- 提供开发期热重载功能完整配置指南
- 说明生成器接入约定和 VS Code 工具功能
- 包含当前限制和独立 Config Studio 评估说明
- 新增配置验证 JavaScript 工具实现

GFramework.Game.Tests/Config/YamlConfigLoaderTests.cs

@@ -839,6 +839,7 @@ public class YamlConfigLoaderTests
     [TestCase("date", "2026-04-11")]
     [TestCase("date-time", "2026-04-11T08:30:00Z")]
     [TestCase("email", "boss@example.com")]
+    [TestCase("time", "08:30:00Z")]
     [TestCase("uri", "https://example.com/loot-table")]
     [TestCase("uuid", "123e4567-e89b-12d3-a456-426614174000")]
     public async Task LoadAsync_Should_Accept_Supported_String_Format(
@@ -892,6 +893,7 @@ public class YamlConfigLoaderTests
     [TestCase("date", "2026-02-30")]
     [TestCase("date-time", "2026-04-11T08:30:00")]
     [TestCase("email", "boss.example.com")]
+    [TestCase("time", "08:30:00")]
     [TestCase("uri", "/loot-table")]
     [TestCase("uuid", "123e4567e89b12d3a456426614174000")]
     public void LoadAsync_Should_Throw_When_String_Does_Not_Match_Supported_Format(
@@ -986,6 +988,7 @@ public class YamlConfigLoaderTests
             Assert.That(exception.Diagnostic.RawValue, Is.EqualTo("ipv4"));
             Assert.That(exception.Message, Does.Contain("unsupported string format"));
             Assert.That(exception.Message, Does.Contain("date-time"));
+            Assert.That(exception.Message, Does.Contain("time"));
         });
     }
 

GFramework.Game/Config/YamlConfigSchemaValidator.cs

@@ -18,7 +18,7 @@ internal static class YamlConfigSchemaValidator
     // The runtime intentionally uses the same culture-invariant regex semantics as the
     // JS tooling so grouping and backreferences behave consistently across environments.
     private const RegexOptions SupportedPatternRegexOptions = RegexOptions.CultureInvariant;
-    private const string SupportedStringFormatNames = "'date', 'date-time', 'email', 'uri', 'uuid'";
+    private const string SupportedStringFormatNames = "'date', 'date-time', 'email', 'time', 'uri', 'uuid'";
 
     private static readonly Regex ExactDecimalPattern = new(
         @"^(?<sign>[+-]?)(?:(?<integer>\d+)(?:\.(?<fraction>\d*))?|\.(?<fractionOnly>\d+))(?:[eE](?<exponent>[+-]?\d+))?$",
@@ -36,6 +36,10 @@ internal static class YamlConfigSchemaValidator
         @"^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})T(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?<fraction>\.\d+)?(?<offset>Z|[+-]\d{2}:\d{2})$",
         RegexOptions.CultureInvariant | RegexOptions.Compiled);
 
+    private static readonly Regex SupportedTimeFormatRegex = new(
+        @"^(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?<fraction>\.\d+)?(?<offset>Z|[+-]\d{2}:\d{2})$",
+        RegexOptions.CultureInvariant | RegexOptions.Compiled);
+
     private static readonly Regex SupportedUriSchemeRegex = new(
         @"^[A-Za-z][A-Za-z0-9+\.-]*:",
         RegexOptions.CultureInvariant | RegexOptions.Compiled);
@@ -1707,6 +1711,10 @@ internal static class YamlConfigSchemaValidator
                 kind = YamlConfigStringFormatKind.Email;
                 return true;
 
+            case "time":
+                kind = YamlConfigStringFormatKind.Time;
+                return true;
+
             case "uri":
                 kind = YamlConfigStringFormatKind.Uri;
                 return true;
@@ -2318,6 +2326,7 @@ internal static class YamlConfigSchemaValidator
             YamlConfigStringFormatKind.Date => MatchesSupportedDateFormat(value),
             YamlConfigStringFormatKind.DateTime => MatchesSupportedDateTimeFormat(value),
             YamlConfigStringFormatKind.Email => SupportedEmailFormatRegex.IsMatch(value),
+            YamlConfigStringFormatKind.Time => MatchesSupportedTimeFormat(value),
             YamlConfigStringFormatKind.Uri => MatchesSupportedUriFormat(value),
             YamlConfigStringFormatKind.Uuid => Guid.TryParseExact(value, "D", out _),
             _ => false
@@ -2362,6 +2371,40 @@ internal static class YamlConfigSchemaValidator
             out _);
     }
 
+    /// <summary>
+    ///     判断字符串是否满足共享支持的 <c>time</c> 格式。
+    ///     该格式固定要求显式时区偏移，并只接受 24 小时制的合法时分秒文本，
+    ///     避免不同宿主对“time-only + offset”解析默认日期或时区时产生漂移。
+    /// </summary>
+    /// <param name="value">待校验的字符串值。</param>
+    /// <returns>当前值是否是合法时间文本。</returns>
+    private static bool MatchesSupportedTimeFormat(string value)
+    {
+        var match = SupportedTimeFormatRegex.Match(value);
+        if (!match.Success)
+        {
+            return false;
+        }
+
+        var hour = int.Parse(match.Groups["hour"].Value, CultureInfo.InvariantCulture);
+        var minute = int.Parse(match.Groups["minute"].Value, CultureInfo.InvariantCulture);
+        var second = int.Parse(match.Groups["second"].Value, CultureInfo.InvariantCulture);
+        if (hour > 23 || minute > 59 || second > 59)
+        {
+            return false;
+        }
+
+        var offset = match.Groups["offset"].Value;
+        if (offset == "Z")
+        {
+            return true;
+        }
+
+        var offsetHour = int.Parse(offset.AsSpan(1, 2), CultureInfo.InvariantCulture);
+        var offsetMinute = int.Parse(offset.AsSpan(4, 2), CultureInfo.InvariantCulture);
+        return offsetHour <= 23 && offsetMinute <= 59;
+    }
+
     /// <summary>
     ///     判断字符串是否满足共享支持的 <c>uri</c> 格式。
     ///     这里要求输入显式包含 scheme，避免把普通路径意外解释成平台相关的绝对 URI。
@@ -3715,6 +3758,11 @@ internal enum YamlConfigStringFormatKind
     /// </summary>
     Email,
 
+    /// <summary>
+    ///     表示带显式时区偏移的 RFC 3339 时间。
+    /// </summary>
+    Time,
+
     /// <summary>
     ///     表示绝对 URI。
     /// </summary>

GFramework.SourceGenerators.Tests/Config/SchemaConfigGeneratorTests.cs

@@ -95,7 +95,7 @@ public class SchemaConfigGeneratorTests
     ///     验证共享支持的字符串 <c>format</c> 会写入生成 XML 文档。
     /// </summary>
     [Test]
-    public void Run_Should_Write_Supported_String_Format_Into_Generated_Documentation()
+    public void Run_Should_Write_Supported_Time_Format_Into_Generated_Documentation()
     {
         const string source = """
                               namespace TestApp
@@ -109,12 +109,12 @@ public class SchemaConfigGeneratorTests
         const string schema = """
                               {
                                 "type": "object",
-                                "required": ["id", "contactEmail"],
+                                "required": ["id", "scheduleTime"],
                                 "properties": {
                                   "id": { "type": "integer" },
-                                  "contactEmail": {
+                                  "scheduleTime": {
                                     "type": "string",
-                                    "format": "email"
+                                    "format": "time"
                                   }
                                 }
                               }
@@ -133,7 +133,7 @@ public class SchemaConfigGeneratorTests
                 StringComparer.Ordinal);
 
         Assert.That(result.Results.Single().Diagnostics, Is.Empty);
-        Assert.That(generatedSources["MonsterConfig.g.cs"], Does.Contain("Constraints: format = 'email'."));
+        Assert.That(generatedSources["MonsterConfig.g.cs"], Does.Contain("Constraints: format = 'time'."));
     }
 
     /// <summary>
@@ -178,6 +178,7 @@ public class SchemaConfigGeneratorTests
             Assert.That(diagnostic.GetMessage(), Does.Contain("address"));
             Assert.That(diagnostic.GetMessage(), Does.Contain("ipv4"));
             Assert.That(diagnostic.GetMessage(), Does.Contain("date-time"));
+            Assert.That(diagnostic.GetMessage(), Does.Contain("time"));
         });
     }
 

GFramework.SourceGenerators/Config/SchemaConfigGenerator.cs

@@ -30,7 +30,7 @@ public sealed class SchemaConfigGenerator : IIncrementalGenerator
     private const string LookupIndexReferencePropertyMessage =
         "Reference properties are excluded from generated lookup indexes because they already carry cross-table semantics.";
 
-    private const string SupportedStringFormatNames = "'date', 'date-time', 'email', 'uri', and 'uuid'";
+    private const string SupportedStringFormatNames = "'date', 'date-time', 'email', 'time', 'uri', and 'uuid'";
 
     /// <inheritdoc />
     public void Initialize(IncrementalGeneratorInitializationContext context)
@@ -708,6 +708,7 @@ public sealed class SchemaConfigGenerator : IIncrementalGenerator
             "date" => true,
             "date-time" => true,
             "email" => true,
+            "time" => true,
             "uri" => true,
             "uuid" => true,
             _ => false

docs/zh-CN/game/config-system.md

@@ -12,7 +12,7 @@
 - JSON Schema 作为结构描述
 - 一对象一文件的目录组织
 - 运行时只读查询
-- Runtime / Generator / Tooling 共享支持 `const`、`minimum`、`maximum`、`exclusiveMinimum`、`exclusiveMaximum`、`multipleOf`、`minLength`、`maxLength`、`pattern`、`format`（当前稳定子集：`date`、`date-time`、`email`、`uri`、`uuid`）、`minItems`、`maxItems`、`uniqueItems`、`contains`、`minContains`、`maxContains`、`minProperties`、`maxProperties`
+- Runtime / Generator / Tooling 共享支持 `const`、`minimum`、`maximum`、`exclusiveMinimum`、`exclusiveMaximum`、`multipleOf`、`minLength`、`maxLength`、`pattern`、`format`（当前稳定子集：`date`、`date-time`、`email`、`time`、`uri`、`uuid`）、`minItems`、`maxItems`、`uniqueItems`、`contains`、`minContains`、`maxContains`、`minProperties`、`maxProperties`
 - Source Generator 生成配置类型、表包装、单表注册/访问辅助，以及项目级聚合注册目录
 - VS Code 插件提供配置浏览、raw 编辑、schema 打开、递归轻量校验和嵌套对象表单入口
 
@@ -773,7 +773,7 @@ if (MonsterConfigBindings.References.TryGetByDisplayPath("dropItems", out var re
 - `multipleOf`：供运行时校验、VS Code 校验、表单 hint 和生成代码 XML 文档复用；当前优先按运行时与 JS 共用的十进制精确整倍数判定处理常见十进制步进，并在必要时退回浮点容差兜底
 - `minLength` / `maxLength`：供运行时校验、VS Code 校验和生成代码 XML 文档复用
 - `pattern`：供运行时校验、VS Code 校验、表单提示和生成代码 XML 文档复用；当前按 C# `CultureInvariant` 与 JS Unicode `u` 模式解释，非法模式会在 schema 解析阶段直接报错
-- `format`：当前只支持 Runtime / Generator / Tooling 三端都能稳定对齐的字符串子集 `date`、`date-time`、`email`、`uri`、`uuid`；运行时会拒绝不满足格式的值，VS Code 校验与表单 hint 会同步展示该约束，生成代码 XML 文档也会保留 `format = ...` 说明
+- `format`：当前只支持 Runtime / Generator / Tooling 三端都能稳定对齐的字符串子集 `date`、`date-time`、`email`、`time`、`uri`、`uuid`；其中 `time` 固定要求显式时区偏移（例如 `08:30:00Z` 或 `08:30:00+08:00`），避免不同宿主对 time-only 文本隐式补日期或本地时区；运行时会拒绝不满足格式的值，VS Code 校验与表单 hint 会同步展示该约束，生成代码 XML 文档也会保留 `format = ...` 说明
 - `minItems` / `maxItems`：供运行时校验、VS Code 校验、表单提示和生成代码 XML 文档复用
 - `uniqueItems`：供运行时校验、VS Code 校验、表单 hint 和生成代码 XML 文档复用；对象数组会按 schema 归一化后的结构比较重复项，而不是依赖 YAML 字段顺序
 - `contains` / `minContains` / `maxContains`：供运行时校验、VS Code 校验、表单 hint 和生成代码 XML 文档复用；当前会按同一套递归 schema 规则统计“有多少数组元素匹配 contains 子 schema”，其中仅声明 `contains` 时默认至少需要 1 个匹配元素

tools/gframework-config-tool/src/configValidation.js

@@ -14,7 +14,9 @@ const UuidFormatPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9
 const DateFormatPattern = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/u;
 const DateTimeFormatPattern =
     /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})T(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?<fraction>\.\d+)?(?<offset>Z|[+-]\d{2}:\d{2})$/u;
-const SupportedStringFormats = new Set(["date", "date-time", "email", "uri", "uuid"]);
+const TimeFormatPattern =
+    /^(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?<fraction>\.\d+)?(?<offset>Z|[+-]\d{2}:\d{2})$/u;
+const SupportedStringFormats = new Set(["date", "date-time", "email", "time", "uri", "uuid"]);
 
 /**
  * Compare two strings using the same UTF-16 code-unit ordering as C#'s
@@ -482,7 +484,7 @@ function normalizeSchemaStringFormat(value, schemaType, displayPath) {
 
     throw new Error(
         `Schema property '${displayPath}' declares unsupported string format '${value}'. ` +
-        "Supported formats are 'date', 'date-time', 'email', 'uri', and 'uuid'.");
+        "Supported formats are 'date', 'date-time', 'email', 'time', 'uri', and 'uuid'.");
 }
 
 /**
@@ -628,6 +630,8 @@ function matchesSchemaStringFormat(scalarValue, formatName) {
             return matchesSchemaDateTimeFormat(scalarValue);
         case "email":
             return EmailFormatPattern.test(scalarValue);
+        case "time":
+            return matchesSchemaTimeFormat(scalarValue);
         case "uri":
             return matchesSchemaUriFormat(scalarValue);
         case "uuid":
@@ -691,6 +695,35 @@ function matchesSchemaDateTimeFormat(scalarValue) {
     return offsetHour <= 23 && offsetMinute <= 59;
 }
 
+/**
+ * Validate one RFC 3339 full-time string with explicit timezone offset.
+ *
+ * @param {string} scalarValue Scalar value from YAML.
+ * @returns {boolean} True when the value is structurally valid.
+ */
+function matchesSchemaTimeFormat(scalarValue) {
+    const match = TimeFormatPattern.exec(scalarValue);
+    if (!match || !match.groups) {
+        return false;
+    }
+
+    const hour = Number.parseInt(match.groups.hour, 10);
+    const minute = Number.parseInt(match.groups.minute, 10);
+    const second = Number.parseInt(match.groups.second, 10);
+    if (hour > 23 || minute > 59 || second > 59) {
+        return false;
+    }
+
+    const offset = match.groups.offset;
+    if (offset === "Z") {
+        return true;
+    }
+
+    const offsetHour = Number.parseInt(offset.slice(1, 3), 10);
+    const offsetMinute = Number.parseInt(offset.slice(4, 6), 10);
+    return offsetHour <= 23 && offsetMinute <= 59;
+}
+
 /**
  * Validate one absolute URI string using the platform URL parser.
  *

tools/gframework-config-tool/test/configValidation.test.js

@@ -679,6 +679,10 @@ test("validateParsedConfig should enforce supported string formats", () => {
               "type": "string",
               "format": "email"
             },
+            "dailyResetAt": {
+              "type": "string",
+              "format": "time"
+            },
             "catalogUri": {
               "type": "string",
               "format": "uri"
@@ -695,19 +699,21 @@ releaseDate: 2026-02-30
 ancientReleaseDate: 0000-01-01
 publishedAt: 2026-04-11T08:30:00
 contactEmail: boss.example.com
+dailyResetAt: 08:30:00
 catalogUri: /loot-table
 configId: 123e4567e89b12d3a456426614174000
 `);
 
     const diagnostics = validateParsedConfig(schema, yaml);
 
-    assert.equal(diagnostics.length, 6);
+    assert.equal(diagnostics.length, 7);
     assert.match(diagnostics[0].message, /format 'date'|字符串格式“date”/u);
     assert.match(diagnostics[1].message, /format 'date'|字符串格式“date”/u);
     assert.match(diagnostics[2].message, /format 'date-time'|字符串格式“date-time”/u);
     assert.match(diagnostics[3].message, /format 'email'|字符串格式“email”/u);
-    assert.match(diagnostics[4].message, /format 'uri'|字符串格式“uri”/u);
+    assert.match(diagnostics[4].message, /format 'time'|字符串格式“time”/u);
-    assert.match(diagnostics[5].message, /format 'uuid'|字符串格式“uuid”/u);
+    assert.match(diagnostics[5].message, /format 'uri'|字符串格式“uri”/u);
+    assert.match(diagnostics[6].message, /format 'uuid'|字符串格式“uuid”/u);
 });
 
 test("validateParsedConfig should accept supported string formats", () => {
@@ -727,6 +733,10 @@ test("validateParsedConfig should accept supported string formats", () => {
               "type": "string",
               "format": "email"
             },
+            "dailyResetAt": {
+              "type": "string",
+              "format": "time"
+            },
             "catalogUri": {
               "type": "string",
               "format": "uri"
@@ -742,6 +752,7 @@ test("validateParsedConfig should accept supported string formats", () => {
 releaseDate: 2026-04-11
 publishedAt: 2026-04-11T08:30:00Z
 contactEmail: boss@example.com
+dailyResetAt: 08:30:00Z
 catalogUri: https://example.com/loot-table
 configId: 123e4567-e89b-12d3-a456-426614174000
 `);
@@ -1406,7 +1417,7 @@ test("parseSchemaContent should capture supported string format metadata", () =>
               "type": "array",
               "items": {
                 "type": "string",
-                "format": "uuid"
+                "format": "time"
               }
             }
           }
@@ -1414,7 +1425,7 @@ test("parseSchemaContent should capture supported string format metadata", () =>
     `);
 
     assert.equal(schema.properties.contactEmail.format, "email");
-    assert.equal(schema.properties.aliases.items.format, "uuid");
+    assert.equal(schema.properties.aliases.items.format, "time");
 });
 
 test("parseSchemaContent should capture multipleOf and uniqueItems metadata", () => {
@@ -1632,7 +1643,7 @@ test("parseSchemaContent should reject unsupported string format declarations",
               }
             }
         `),
-        /unsupported string format 'ipv4'/u
+        /unsupported string format 'ipv4'.*'time'/u
     );
 });