From 65d3634181bb6740e08d5ee9f532067613a4c33b Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sun, 26 Apr 2026 08:55:48 +0800 Subject: [PATCH] =?UTF-8?q?docs(config-tool):=20=E8=A1=A5=E5=85=85?= =?UTF-8?q?=E9=85=8D=E7=BD=AE=E5=B7=A5=E5=85=B7=E6=9C=80=E5=B0=8F=E6=8E=A5?= =?UTF-8?q?=E5=85=A5=E8=B7=AF=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 补充 config tool README 的 Quick Start 最小接入步骤并统一 schema subset 术语 - 更新 documentation-full-coverage-governance 的 tracking 与 trace，记录 PR #292 最新 review 结论和验证结果 - 补充工具模块的测试与 VSIX 打包验证结果，作为本轮 review 收口的最小验证证据 --- ...ation-full-coverage-governance-tracking.md | 20 ++++++++----- ...entation-full-coverage-governance-trace.md | 29 +++++++++++++++++++ tools/gframework-config-tool/README.md | 12 +++++++- 3 files changed, 53 insertions(+), 8 deletions(-) diff --git a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md index 45726143..51914f03 100644 --- a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md +++ b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md @@ -12,14 +12,14 @@ ## 当前恢复点 -- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-039` +- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-040` - 当前阶段：`Phase 5 - Governance Maintenance` - 当前焦点： - 继续以最新 `origin/main`（`79934f7`，`2026-04-25 16:15:55 +08:00`）作为 baseline，当前批处理 stop condition 仍是 branch diff vs baseline 接近 `50` changed files - 当前批次已从“单点 review 收口”切到“覆盖整个项目功能的 reader-facing 文档补齐”，重点处理 4 组低风险切片：meta-package / 安装入口、config tool adoption、source-generators 真实契约修正、内部支撑模块 README - 当前未提交工作树已触达 `18` 个文件，其中 `14` 个更新、`4` 个新增；当前 committed branch diff vs `origin/main` 仍为 `3` files，提交本批次后仍明显低于 `50` 文件阈值 - 已接受 subagent 结论：`Cqrs` 当前不是栏目缺失，而是 `docs/zh-CN/core/cqrs.md` 需要补 `Request` / stream 变体与协程入口；source-generators 侧当前优先修正文档失真与共享支撑层说明，而不是扩新导航 -- `2026-04-25` 重新抓取 PR `#292` 后确认 latest reviewed commit 已推进到 `b96565ffa367bade30f44c2d4e8955143fbff85e`；当前仅剩 `2` 条 CodeRabbit open thread，分别是 `docs/zh-CN/source-generators/index.md` 的单句可读性优化，以及 `tools/gframework-config-tool/README.md` 缺少中文文档入口链接 +- `2026-04-26` 重新抓取 PR `#292` 后确认 latest reviewed commit 已推进到 `d3d62cf4541063c46458f88eea0f5acd1b4503f9`；当前 open thread 仍集中在 `tools/gframework-config-tool/README.md`，其中“缺少中文文档入口链接”已在本地工作树验证为过期评论，仍需收口的是补最小接入路径以及统一 `current schema subset` 术语 ## 当前状态摘要 @@ -31,6 +31,7 @@ - `2026-04-25` 全量 `docs/zh-CN` 验证已无剩余代码块语言警告；前一轮触达的 `tutorials`、`best-practices`、`troubleshooting`、`godot/resource` 等栏目结果保持有效。 - `2026-04-25` `docs/zh-CN/source-generators/index.md` 已按 PR `#292` review 调整“共享支撑模块”段落句式，避免“对读者更重要的判断是”这类拗口表达。 - `2026-04-25` `tools/gframework-config-tool/README.md` 已新增 `Documentation` 章节，直接链接到 `docs/zh-CN/game/config-tool.md` 与 `config-system.md`，让工具 README 能回到完整中文接入文档。 +- `2026-04-26` `tools/gframework-config-tool/README.md` 已补 `Quick Start`，把安装扩展、配置 `configPath` / `schemasPath`、打开 Explorer、先跑校验、再进入表单 / 批量编辑的最小接入路径串起来，并把 `Validation Coverage` 的 `stable config-schema subset` 统一为 `current schema subset`。 - `2026-04-25` 当前批次已补齐 meta-package / 安装面：`GFramework.csproj` 不再保留占位描述，`README.md`、`docs/zh-CN/index.md`、`docs/zh-CN/getting-started/installation.md` 当前明确说明聚合元包只聚合 `Core` + `Game`，并把安装入口更新到当前 `net8.0/net9.0/net10.0` 与 Godot `4.6.2` 基线。 - `2026-04-25` `docs/zh-CN/game/config-tool.md` 已新增为 reader-facing 工具页，`docs/zh-CN/game/index.md`、`config-system.md`、`docs/.vitepress/config.mts` 与 `tools/gframework-config-tool/README.md` 当前把 VS Code 配置工具纳入 `Game` 配置工作流入口。 - `2026-04-25` source-generators 栏目已修正 4 处真实契约问题：`GetNode` 显式路径 / `Lookup` 语义、枚举生成器实际开关、`Context Get` 集合注入边界，以及 `GFramework.SourceGenerators.Common` / `*.SourceGenerators.Abstractions` 的共享支撑层说明。 @@ -152,13 +153,18 @@ `1` 条 Greptile open thread，无 failed checks，测试汇总为 `2156 passed`。 - `2026-04-25` `bun run build`（工作目录：`docs/`） - 结果：通过；`docs/zh-CN/api-reference/index.md` 的站内入口标签统一为语义化写法后站点仍可正常构建，仅保留既有大 chunk warning。 +- `2026-04-26` `bun run test`（工作目录：`tools/gframework-config-tool/`） + - 结果：通过；`122` 个测试全部通过，说明 README 收口没有影响该工具现有测试面。 +- `2026-04-26` `bun run package:vsix`（工作目录：`tools/gframework-config-tool/`） + - 结果：通过；成功生成 `gframework-config-tool-0.0.3.vsix`，满足本轮工具模块的最小 build validation。 ## 下一步 -1. 提交当前项目级功能覆盖批次后，重新计算 branch diff vs `origin/main`，确认距离 `50` 文件阈值还有多少空间，再决定是否继续追加低风险文档切片。 -2. 提交完成后重新抓取 `$gframework-pr-review`，确认 PR `#292` 的 latest-head review 是否已清空 open thread。 -3. 若后续继续扩批，优先在已识别但尚未扩写的低风险 reader-facing 方向里选择下一组：config tool 更深的 adoption 示例、首页 / 安装页的进一步选包引导，或其它 repo-visible support surface 的本地说明补齐。 -4. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 +1. 运行 `bun run test`（工作目录：`tools/gframework-config-tool/`），完成本轮 README 收口改动的最小模块验证。 +2. 验证通过后重新抓取 `$gframework-pr-review`，确认 PR `#292` 的 latest-head review 是否只剩过期线程或已自动清空。 +3. 若本轮提交后 branch diff vs `origin/main` 仍明显低于 `50` 文件阈值，再决定是否继续追加低风险 reader-facing 文档切片。 +4. 若后续继续扩批，优先在已识别但尚未扩写的低风险 reader-facing 方向里选择下一组：config tool 更深的 adoption 示例、首页 / 安装页的进一步选包引导，或其它 repo-visible support surface 的本地说明补齐。 +5. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、 `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。 -5. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、 +6. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、 `docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。 diff --git a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md index 72b62681..4a0b4abc 100644 --- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -1,5 +1,34 @@ # Documentation Full Coverage Governance Trace +## 2026-04-26 + +### 当前恢复点：RP-040 + +- 本轮继续从 `$gframework-pr-review` 恢复，沿用显式 `--git-dir` / `--work-tree` 绑定确认当前分支仍为 `docs/sdk-update-documentation`，并重新抓取 PR `#292` 的 latest-head review。 +- 使用 `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` 抓取后确认：PR `#292` 最新 reviewed commit 为 `d3d62cf4541063c46458f88eea0f5acd1b4503f9`，failed checks 为 `0`，测试汇总仍为 `2156 passed`；剩余 `2` 条 CodeRabbit open thread 都落在 `tools/gframework-config-tool/README.md`。 +- 本地逐项复核后确认：缺少 `docs/zh-CN` 链接的评论已经过期，因为 README 当前已有 `Documentation` 章节；仍成立的是补最小接入路径，以及统一 `stable config-schema subset` / `current schema subset` 术语。 + +### 当前决策（RP-040） + +- 接受当前 latest-head review 中仍然成立的两项 README 收口：新增 `Quick Start` 最小接入路径，并统一校验支持范围术语。 +- 不对已经过期的“缺少中文文档入口链接”线程做额外扩展，只在本地结果里保留“已验证为 stale”的结论，等待后续 PR review 刷新反映最新状态。 +- 继续遵守 active topic 的恢复要求，在同一轮里同步更新 tracking / trace，并对直接受影响的工具模块执行最小验证。 + +### 当前验证（RP-040） + +- PR review 抓取： + - `python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/gframework-current-pr-review.json` + - 结果：通过；PR `#292` 处于 `OPEN`，latest head review 还有 `2` 条 CodeRabbit open thread，failed checks 为 `0`，测试汇总为 `2156 passed`。 +- 工具 README 收口： + - `tools/gframework-config-tool/README.md` + - 结果：已新增 `Quick Start` 段落，并把 `Validation Coverage` 术语统一为 `current schema subset`。 +- 工具测试： + - `bun run test`（工作目录：`tools/gframework-config-tool/`） + - 结果：通过；`122` 个测试全部通过。 +- 工具打包： + - `bun run package:vsix`（工作目录：`tools/gframework-config-tool/`） + - 结果：通过；成功生成 `gframework-config-tool-0.0.3.vsix`，确认工具模块可完成最小打包验证。 + ## 2026-04-25 ### 当前恢复点：RP-039 diff --git a/tools/gframework-config-tool/README.md b/tools/gframework-config-tool/README.md index bb925a4d..cd6acda3 100644 --- a/tools/gframework-config-tool/README.md +++ b/tools/gframework-config-tool/README.md @@ -61,7 +61,7 @@ GameProject/ ## Validation Coverage -The extension currently validates the repository's stable config-schema subset: +The extension currently validates the repository's current schema subset: - required properties in nested objects - unknown properties in nested objects @@ -79,6 +79,16 @@ The extension currently validates the repository's stable config-schema subset: } ``` +## 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)