feat: scaffold automation pack candidate

codefromkarl · codefromkarl · commit 5951b1eb8ece · 2026-04-23T23:46:30.000+08:00
diff --git a/README.md b/README.md
@@ -13,6 +13,10 @@
 - `stateful`：`Godot State Charts`
 - `juice`：`Sparkle Lite`
 
+另外保留一个**候选**方向：
+
+- `packs/automation/`：`GodotE2E` 候选 PoC 骨架，当前**不在** `packs.manifest.json`，也**不参与**默认 bootstrap
+
 ## 设计原则
 
 - 默认只启用适合自动化和 CI 的基线能力。
@@ -41,6 +45,7 @@
 - `packs/`：可选插件 pack
 - `scripts/bootstrap_toolbox_project.sh`：按 pack 组装新项目
 - `scripts/verify_bootstrap_flow.sh`：验证真实产物链路，覆盖 bootstrap、headless import 和 `gdUnit4` smoke
+- `scripts/verify_automation_pack_poc.sh`：验证 `packs/automation/` 候选 PoC 骨架，不接入默认验证链
 - `scripts/import_plugin_from_upstream.sh`：首次从 upstream 导入插件子树
 - `scripts/update_plugin_from_upstream.sh`：基于 lock 文件升级已纳入插件
 - `scripts/verify_toolbox_layout.sh`：校验工具箱布局
@@ -84,6 +89,14 @@ bash ./scripts/verify_bootstrap_flow.sh
 
 CI 也跑同一条真实产物链。当前 workflow 固定使用官方 Linux 构建的 Godot `4.6.2`，本地建议保持 `4.6.x`，如果本机 Godot 不在 `PATH`，可通过 `GODOT_BIN=/path/to/godot` 显式指定。
 
+候选 `automation` PoC 走独立入口：
+
+```bash
+bash ./scripts/verify_automation_pack_poc.sh
+```
+
+这个脚本只验证候选骨架和最小 bootstrap 前提，不会把 `automation` 接到默认 pack 清单里。
+
 ## 维护工具箱
 
 首次纳入一个 git upstream 插件：
diff --git a/docs/maintenance-workflow.md b/docs/maintenance-workflow.md
@@ -35,10 +35,11 @@
 4. 它的升级与维护成本是否可控？
 5. 它是否能通过本地脚本验证，而不是只能靠编辑器手工点击？
 
-结论只有 4 种：
+结论只有 5 种：
 
 - 进入 `base`
 - 进入某个 `pack`
+- 先作为候选 `pack / PoC`
 - 只保留为外部参考
 - 暂不纳入
 
@@ -61,6 +62,16 @@
 - 可以按项目需要叠加
 - 不会接管项目核心真相
 
+### 候选 `pack / PoC`
+
+如果方向值得继续，但还不适合进入 `packs.manifest.json`，先按候选 PoC 处理：
+
+- 目录可以先放在 `packs/<name>/`
+- 必须明确标注“未纳入正式 pack”
+- 不修改默认 `bootstrap` 行为
+- 不接入默认验证链
+- 通过独立验证脚本证明这条路径值得继续
+
 ## B. 首次导入上游插件
 
 首次导入时，按下面流程执行：
@@ -171,6 +182,12 @@ python3 -m json.tool upstreams.lock.json >/dev/null
 bash ./scripts/verify_bootstrap_flow.sh
 ```
 
+如果本轮改动的是候选 `automation` PoC，再补：
+
+```bash
+bash ./scripts/verify_automation_pack_poc.sh
+```
+
 如果本轮改动涉及 `import/update`，还应补：
 
 ```bash
diff --git a/packs/automation/README.md b/packs/automation/README.md
@@ -0,0 +1,42 @@
+# Automation Candidate Pack
+
+这是 `GodotE2E` 方向的候选 pack / PoC 骨架，不是已经纳入的正式 pack。
+
+当前约束：
+
+- **不在** `packs.manifest.json` 中
+- **不参与** 默认 `bootstrap` 行为
+- **不接入** 当前默认 CI / 默认验证链
+
+这个目录的目标是先把 E2E 自动化方向的最小骨架和评估入口固定下来，等上游安装方式、Python 包名、Godot 侧接入面都验证清楚后，再决定是否晋升成正式 pack。
+
+## 当前内容
+
+- `python/requirements-e2e.txt`
+  Python 侧依赖占位。当前故意不锁定真实包名，避免把未经确认的安装名写进仓库。
+- `examples/tests/test_ui_smoke_placeholder.py`
+  一个最小占位测试骨架，只表达未来 E2E 测试的大致入口，不代表已可执行。
+
+## 当前缺口
+
+1. 锁定真实的 `GodotE2E` Python 包名、安装方式和版本策略
+2. 确认是否需要 vendoring Godot 侧 addon，以及应落在哪个目录
+3. 定义最小可接受的 PoC 成功标准
+4. 决定通过什么条件把它晋升为正式 `pack`
+
+## 本地验证
+
+独立验证入口：
+
+```bash
+bash ./scripts/verify_automation_pack_poc.sh
+```
+
+这个脚本会：
+
+- bootstrap 一个**不叠加 automation** 的最小临时项目
+- 校验候选骨架文件是否齐全
+- 在条件满足时执行最小占位验证
+- 输出当前 PoC 还缺什么
+
+它不会修改当前默认验证链。
diff --git a/packs/automation/examples/tests/test_ui_smoke_placeholder.py b/packs/automation/examples/tests/test_ui_smoke_placeholder.py
@@ -0,0 +1,23 @@
+"""Candidate PoC placeholder for future GodotE2E smoke coverage."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import unittest
+
+
+class AutomationPackPlaceholderTest(unittest.TestCase):
+    def test_candidate_pack_not_yet_wired(self) -> None:
+        project_root = os.environ.get("GODOT_PROJECT_ROOT")
+        if not project_root:
+            self.skipTest(
+                "Candidate PoC only: set GODOT_PROJECT_ROOT after locking the real "
+                "GodotE2E package name and runtime contract."
+            )
+
+        self.assertTrue(Path(project_root).exists())
+        self.skipTest(
+            "Candidate PoC only: replace this placeholder once the real GodotE2E "
+            "integration path is validated."
+        )
diff --git a/packs/automation/python/requirements-e2e.txt b/packs/automation/python/requirements-e2e.txt
@@ -0,0 +1,12 @@
+# Candidate PoC placeholder only.
+#
+# Do not add an unverified GodotE2E package name here.
+# The next maintainer should first confirm:
+# 1. the real Python package/install command
+# 2. whether version pinning belongs in this file or a separate lock file
+# 3. how the Python side coordinates with any Godot-side addon
+#
+# Expected follow-up:
+# - validate upstream install instructions
+# - lock the real package name and version
+# - add a minimal, actually runnable E2E smoke test
diff --git a/scripts/verify_automation_pack_poc.sh b/scripts/verify_automation_pack_poc.sh
@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+KEEP_TEMP="0"
+TMP_ROOT="${TMPDIR:-/tmp}"
+WORKDIR=""
+
+usage() {
+  cat <<'EOF'
+Usage:
+  bash ./scripts/verify_automation_pack_poc.sh [--keep-temp]
+
+What it does:
+  - bootstraps a minimal project without the candidate automation pack
+  - checks that the candidate PoC scaffold exists
+  - runs a minimal placeholder validation when Python is available
+  - prints the current gaps before this PoC can graduate into a real pack
+EOF
+}
+
+log() {
+  printf '[verify-automation-poc] %s\n' "$*"
+}
+
+die() {
+  printf '[verify-automation-poc] ERROR: %s\n' "$*" >&2
+  exit 1
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --keep-temp)
+      KEEP_TEMP="1"
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      die "unexpected argument: ${arg}"
+      ;;
+  esac
+done
+
+cleanup() {
+  if [[ -n "${WORKDIR}" && -d "${WORKDIR}" ]]; then
+    if [[ "${KEEP_TEMP}" == "1" ]]; then
+      log "kept temporary project at ${WORKDIR}"
+    else
+      rm -rf "${WORKDIR}"
+    fi
+  fi
+}
+
+trap cleanup EXIT
+
+require_file() {
+  local path="$1"
+  [[ -f "${path}" ]] || die "required file missing: ${path}"
+}
+
+assert_manifest_lacks_automation() {
+  if command -v jq >/dev/null 2>&1; then
+    if jq -e '.packs[] | select(.id == "automation")' "${REPO_ROOT}/packs.manifest.json" >/dev/null; then
+      die "candidate automation pack unexpectedly appears in packs.manifest.json"
+    fi
+    return 0
+  fi
+
+  if grep -q '"id"[[:space:]]*:[[:space:]]*"automation"' "${REPO_ROOT}/packs.manifest.json"; then
+    die "candidate automation pack unexpectedly appears in packs.manifest.json"
+  fi
+}
+
+require_file "${REPO_ROOT}/packs/automation/README.md"
+require_file "${REPO_ROOT}/packs/automation/python/requirements-e2e.txt"
+require_file "${REPO_ROOT}/packs/automation/examples/tests/test_ui_smoke_placeholder.py"
+assert_manifest_lacks_automation
+
+WORKDIR="$(mktemp -d "${TMP_ROOT%/}/godot-toolbox-automation-poc.XXXXXX")"
+
+log "bootstrapping minimal temporary project at ${WORKDIR}"
+bash "${REPO_ROOT}/scripts/bootstrap_toolbox_project.sh" "${WORKDIR}"
+
+require_file "${WORKDIR}/godot/project.godot"
+require_file "${WORKDIR}/scripts/gdunit4_smoke.sh"
+
+if [[ -f "${WORKDIR}/.toolbox-packs" ]]; then
+  if [[ -n "$(tr -d '[:space:]' < "${WORKDIR}/.toolbox-packs")" ]]; then
+    die "expected no packs in minimal bootstrap, found: $(cat "${WORKDIR}/.toolbox-packs")"
+  fi
+fi
+
+if command -v python3 >/dev/null 2>&1; then
+  log "running placeholder Python validation"
+  PLACEHOLDER_PYC="${TMP_ROOT%/}/godot-toolbox-automation-placeholder.pyc"
+  rm -f "${PLACEHOLDER_PYC}"
+  python3 - <<PY
+import py_compile
+py_compile.compile(
+    r"${REPO_ROOT}/packs/automation/examples/tests/test_ui_smoke_placeholder.py",
+    cfile=r"${PLACEHOLDER_PYC}",
+    doraise=True,
+)
+PY
+  rm -f "${PLACEHOLDER_PYC}"
+else
+  log "python3 not found; skipped placeholder Python validation"
+fi
+
+log "candidate pack remains intentionally outside packs.manifest.json and default bootstrap"
+log "current gaps:"
+log "1. lock the real GodotE2E Python package name and version strategy"
+log "2. decide whether a Godot-side addon must be vendored for this pack"
+log "3. define the minimal runnable E2E smoke contract for CI"
+log "4. set promotion criteria before adding automation to packs.manifest.json"
+log "PASS"
