docs(config-tool): 对齐对象数组嵌套编辑说明

- 更新 VS Code 配置工具 README，收紧 raw YAML 回退条件并同步实际对象数组编辑边界

- 修复中文配置工具文档对嵌套对象数组能力的过时描述，明确仅在超出共享子集时回退

- 补充 ai-plan tracking 与 trace，记录本轮文档对齐、验证结果与批处理停止条件

ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md

@@ -94,6 +94,7 @@
 - 最近验证摘要：`2026-04-30` 已完成 Tooling / Docs reader-facing 收口与工具 parser 边界收紧，详细命令、批次背景与验证结果保留在 trace 的 `2026-04-30` 分阶段记录中
 - 最近验证摘要：`2026-05-06` 已完成开放对象关键字边界收口；Runtime / Generator / Tooling 现统一拒绝 `patternProperties`、`propertyNames`、`unevaluatedProperties`，并保留 `additionalProperties: false` 作为唯一共享闭合对象入口；详细命令与批次背景保留在 trace 的 `2026-05-06` 记录中
 - 最近验证摘要：`2026-05-06` 已按 PR `#325` latest review follow-up 移除三端开放对象校验中的不可达 `additionalProperties: false` 放行分支，补齐 Tooling 正向回归，并同步拆分 reader-facing docs 对开放对象边界的表述；细节与验证命令保留在 trace 的 `2026-05-06` 追加记录中
+- 最近验证摘要：`2026-05-06` 已核对 `extension.js` 的对象数组编辑能力与 reader-facing 文档，确认表单当前支持对象数组项内部继续嵌套的对象数组；`tools/gframework-config-tool/README.md` 与 `docs/zh-CN/game/config-tool.md` 已同步收紧回退条件，避免把“仍在共享子集内的嵌套对象数组”误写成默认只能回退 raw YAML；细节与验证命令保留在 trace 的 `2026-05-06` 追加记录中
 - PR `#306` follow-up 摘要：已按 latest open review threads 补齐 Generator `anyOf` 对称回归、Tooling schema type 白名单、object-array 直系收集边界，以及 reader-facing docs 的显式 `additionalProperties: false` / adoption guidance 说明；细节和验证命令保留在 trace 的 `2026-04-30` 新增阶段记录中
 - PR review 跟进指针：当前分支的 latest review follow-up 与后续本地核验结论以 `ai-first-config-system-trace.md` 为准，active tracking 不再重复展开逐条命令历史
 

ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md

@@ -324,3 +324,40 @@
 1. 执行本轮受影响 Tooling / Runtime / Generator 定向验证，并确认没有新增 warning 或格式漂移
 2. 若验证通过，重新抓取 PR `#325` review 状态，区分哪些 open threads 会随推送自动折叠
 3. 继续把 PR review follow-up 约束在“latest unresolved thread + 本地仍成立问题”，不回头追旧 summary 噪音
+
+### 阶段：Tooling 文档与实际编辑边界对齐（AI-FIRST-CONFIG-RP-003）
+
+- 已重新核对 `tools/gframework-config-tool/src/extension.js` 的对象数组表单能力，并确认当前实现不只支持对象数组本身
+- 当前表单还支持“对象数组项内部继续嵌套的对象数组”，前提是内层条目仍保持共享子集允许的对象 / 标量字段 / 标量数组 / 嵌套对象形状
+- 本轮不扩 Runtime / Generator / Tooling 的 schema 契约，只修正 reader-facing docs 漂移：
+  - `tools/gframework-config-tool/README.md` 不再把“更深层嵌套编辑”笼统描述成默认回退 raw YAML
+  - `docs/zh-CN/game/config-tool.md` 改为明确：只有当对象数组继续嵌套后的结构超出当前共享子集，才需要回到 raw YAML
+
+### 关键决定
+
+- 这轮批次继续遵守“先核对共享契约，再改文档”的 lane 规则，没有为追求批量推进而硬扩一个收益不明确的新关键字
+- Tooling 的 reader-facing 说明要以 `extension.js` 当前真实能力为准，避免把已经支持的对象数组路径继续描述成工具缺口
+- raw YAML 回退条件保留，但需要收敛为“超出共享子集或当前编辑器边界”而不是“只要更深层对象数组就默认回退”
+
+### Stop Condition
+
+- Batch baseline：`origin/main` (`c01abac0`, `2026-05-06 09:40:08 +0800`)
+- Primary metric：branch diff vs `origin/main` changed files，阈值 `30`
+- 本轮开始前 branch diff 指标为 `0` files / `0` changed lines；本批次只触碰 reader-facing docs 与 active `ai-plan`，预计仍远低于阈值
+
+### 验证
+
+- 2026-05-06：`rg -n "nested object arrays|回退到 raw YAML|更深层对象数组"`（文档 + `extension.js`）
+  - 结果：通过
+  - 备注：确认 `README` / 中文工具文档存在旧边界表述，而 `extension.js` 已支持对象数组项内部继续嵌套的对象数组编辑
+- 2026-05-06：`git diff --check -- tools/gframework-config-tool/README.md docs/zh-CN/game/config-tool.md ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md`
+  - 结果：通过
+- 2026-05-06：`python3 scripts/license-header.py --check --paths tools/gframework-config-tool/README.md docs/zh-CN/game/config-tool.md ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md`
+  - 结果：通过
+- 2026-05-06：`dotnet build GFramework.Game/GFramework.Game.csproj -c Release`
+  - 结果：通过（0 warnings, 0 errors）
+
+### 下一步
+
+1. 继续优先找“实现已存在但 reader-facing 表述漂移”的低风险 lane，避免在批处理模式下引入收益不明的新 schema contract
+2. 若下一轮回到主线代码批次，再继续盘点不会改变生成类型形状的共享关键字，而不是重复刷新同一组 Tooling 边界说明

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

@@ -22,7 +22,7 @@ description: 说明 GFramework AI-First 配置工作流对应的 VS Code 工具
 
 - 项目不使用 `GFramework.Game` 的配置工作流
 - 需要完整 JSON Schema 编辑器，而不是当前仓库落地的稳定子集
-- 需要在编辑器里处理更深层对象数组嵌套，且不接受回退到 raw YAML
+- 需要完整放宽到当前共享支持子集之外的更异构数组结构，且不接受回退到 raw YAML
 
 ## 工作区约定
 
@@ -230,11 +230,11 @@ rewardTableId: starter-reward
 - `contains` / `minContains` / `maxContains`
 - `additionalProperties: false`
 
-如果你进入更深层对象数组嵌套，当前更稳妥的做法通常是：
+如果你进入对象数组里的继续嵌套对象数组，当前表单通常仍可继续处理；更稳妥的顺序是：
 
 1. 用 Explorer 找到目标文件
-2. 先看表单预览确认字段结构
-3. 再回到 raw YAML 完成最终编辑
+2. 先看表单预览确认当前层级仍保持对象 / 标量字段 / 标量数组 / 嵌套对象的共享子集形状
+3. 只有在结构开始变得更异构，或已经超出当前共享支持子集时，再回到 raw YAML 完成最终编辑
 
 以下 shape 目前也建议直接回退到 raw YAML，并同时检查 schema 是否仍在当前共享支持子集内：
 
@@ -265,7 +265,7 @@ rewardTableId: starter-reward
 
 - 工作区默认只取第一个 workspace folder
 - 校验聚焦仓库当前支持的 schema 子集
-- 表单预览支持对象数组，但更深的嵌套对象数组仍可能需要回退到 raw YAML
+- 表单预览支持对象数组，以及对象数组项内部继续嵌套的对象数组；只有当内层结构超出共享子集时才需要回退到 raw YAML
 - 批量编辑当前聚焦顶层标量和顶层标量数组字段
 - 共享约束里只支持闭合对象边界 `additionalProperties: false`；`oneOf` / `anyOf` 等改变生成形状的组合关键字会被明确拒绝
 

tools/gframework-config-tool/README.md

@@ -106,8 +106,8 @@ This extension is an editor-side helper. It does not define the runtime contract
    project-specific paths relative to the first workspace folder.
 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.
+5. Open the lightweight form preview or domain batch editing actions, then fall back to raw YAML only when the current
+   path exceeds the supported object-array editor boundary or leaves the shared schema subset.
 
 Minimal adoption checklist:
 
@@ -136,8 +136,8 @@ Use raw YAML directly when you need:
 
 - Multi-root workspaces use the first workspace folder
 - Validation only covers the repository's current schema subset
-- Form preview supports nested objects and object-array editing, but deeper nested object arrays inside array items still
-  fall back to raw YAML
+- Form preview supports nested objects, object arrays, and nested object arrays inside object-array items as long as
+  those nested items still stay within the shared subset's object/scalar/array shape
 - Batch editing remains limited to top-level scalar fields and top-level scalar arrays
 - Closed-object support is limited to `additionalProperties: false`; open-object keywords such as
   `patternProperties`, `propertyNames`, and `unevaluatedProperties` are rejected on purpose, as are unsupported