From 3e1ce089afc62cb0a320e2f2d4eaba2615e0d070 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Wed, 6 May 2026 09:48:00 +0800 Subject: [PATCH] =?UTF-8?q?docs(config-tool):=20=E5=AF=B9=E9=BD=90?= =?UTF-8?q?=E5=AF=B9=E8=B1=A1=E6=95=B0=E7=BB=84=E5=B5=8C=E5=A5=97=E7=BC=96?= =?UTF-8?q?=E8=BE=91=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 VS Code 配置工具 README，收紧 raw YAML 回退条件并同步实际对象数组编辑边界 - 修复中文配置工具文档对嵌套对象数组能力的过时描述，明确仅在超出共享子集时回退 - 补充 ai-plan tracking 与 trace，记录本轮文档对齐、验证结果与批处理停止条件 --- .../todos/ai-first-config-system-tracking.md | 1 + .../traces/ai-first-config-system-trace.md | 37 +++++++++++++++++++ docs/zh-CN/game/config-tool.md | 10 ++--- tools/gframework-config-tool/README.md | 8 ++-- 4 files changed, 47 insertions(+), 9 deletions(-) diff --git a/ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md b/ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md index 4c713c76..6efc7585 100644 --- a/ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md +++ b/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 不再重复展开逐条命令历史 diff --git a/ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md b/ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md index 45956eda..14c6d8ff 100644 --- a/ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md +++ b/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 边界说明 diff --git a/docs/zh-CN/game/config-tool.md b/docs/zh-CN/game/config-tool.md index 9cdb7c34..a765ee2a 100644 --- a/docs/zh-CN/game/config-tool.md +++ b/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` 等改变生成形状的组合关键字会被明确拒绝 diff --git a/tools/gframework-config-tool/README.md b/tools/gframework-config-tool/README.md index 35af86d4..6ac42812 100644 --- a/tools/gframework-config-tool/README.md +++ b/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