feat: add continuous verification and plugin scouting

Author: codefromkarl

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-24.04
+    env:
+      GODOT_VERSION: 4.6.2
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq unzip
+
+      - name: Install Godot
+        run: |
+          set -euo pipefail
+          godot_zip="Godot_v${GODOT_VERSION}-stable_linux.x86_64.zip"
+          godot_url="https://github.com/godotengine/godot-builds/releases/download/${GODOT_VERSION}-stable/${godot_zip}"
+          curl -L --fail --retry 3 --output /tmp/${godot_zip} "${godot_url}"
+          unzip -q /tmp/${godot_zip} -d /tmp/godot
+          sudo install -m 0755 /tmp/godot/Godot_v${GODOT_VERSION}-stable_linux.x86_64 /usr/local/bin/godot
+          godot --version
+
+      - name: Check shell syntax
+        run: bash -n scripts/*.sh templates/base/scripts/*.sh
+
+      - name: Check JSON syntax
+        run: |
+          python3 -m json.tool packs.manifest.json >/dev/null
+          python3 -m json.tool upstreams.lock.json >/dev/null
+
+      - name: Verify toolbox layout
+        run: bash ./scripts/verify_toolbox_layout.sh
+
+      - name: Verify bootstrap flow
+        run: bash ./scripts/verify_bootstrap_flow.sh

README.md

@@ -40,14 +40,15 @@
 - `templates/base/`：基础项目模板
 - `packs/`：可选插件 pack
 - `scripts/bootstrap_toolbox_project.sh`：按 pack 组装新项目
+- `scripts/verify_bootstrap_flow.sh`：验证真实产物链路，覆盖 bootstrap、headless import 和 `gdUnit4` smoke
 - `scripts/import_plugin_from_upstream.sh`：首次从 upstream 导入插件子树
 - `scripts/update_plugin_from_upstream.sh`：基于 lock 文件升级已纳入插件
 - `scripts/verify_toolbox_layout.sh`：校验工具箱布局
 - `docs/plugin-catalog.md`：插件目录与建议
 - `docs/plugin-integration-standard.md`：插件接入标准
 - `docs/maintenance-workflow.md`：维护、导入、升级、组装与验证手册
 - `docs/selection-framework.md`：选型框架与当前归类理由
-- `docs/research/similar-projects.md`：外部参考项目速记
+- `docs/research/`：外部参考项目速记、插件探索智能体说明、热门插件扫描快照
 - `upstreams.lock.json`：上游来源与版本锁定
 - `packs.manifest.json`：pack 定义、默认策略和适用场景
 
@@ -66,6 +67,23 @@
 `bootstrap_toolbox_project.sh` 不再在脚本里硬编码 `pack -> plugin.cfg` 映射。
 如果请求的 pack 不存在于 `packs.manifest.json`，脚本会直接报错。
 
+## 持续稳定验证
+
+本地最小验证链：
+
+```bash
+bash ./scripts/verify_toolbox_layout.sh
+bash ./scripts/verify_bootstrap_flow.sh
+```
+
+`verify_bootstrap_flow.sh` 会创建临时项目，默认叠加 `validation,debug,stateful,juice`，然后依次执行：
+
+- bootstrap 临时项目
+- `godot --headless --editor --quit-after 1 --import`
+- 生成项目内的 `gdUnit4` smoke
+
+CI 也跑同一条真实产物链。当前 workflow 固定使用官方 Linux 构建的 Godot `4.6.2`，本地建议保持 `4.6.x`，如果本机 Godot 不在 `PATH`，可通过 `GODOT_BIN=/path/to/godot` 显式指定。
+
 ## 维护工具箱
 
 首次纳入一个 git upstream 插件：

docs/maintenance-workflow.md

@@ -168,11 +168,7 @@ python3 -m json.tool upstreams.lock.json >/dev/null
 ### 3. 真实产物检查
 
 ```bash
-tmpdir=$(mktemp -d)
-./scripts/bootstrap_toolbox_project.sh "$tmpdir" --packs=validation,debug,stateful,juice
-godot --headless --editor --quit-after 1 --path "$tmpdir/godot" --import
-GODOT_BIN="$(command -v godot)" bash "$tmpdir/scripts/gdunit4_smoke.sh"
-rm -rf "$tmpdir"
+bash ./scripts/verify_bootstrap_flow.sh
 ```
 
 如果本轮改动涉及 `import/update`，还应补：
@@ -202,3 +198,15 @@ rm -rf "$tmpdir"
 5. 最后提交并推送
 
 这样可以把选型错误、版本错误、路径错误和验证错误尽量提前暴露。
+
+## H. CI 基线
+
+仓库级 CI 入口在 `.github/workflows/ci.yml`，当前固定跑 4 类检查：
+
+1. 布局检查：`bash ./scripts/verify_toolbox_layout.sh`
+2. Shell 语法检查：`bash -n scripts/*.sh templates/base/scripts/*.sh`
+3. JSON 语法检查：`python3 -m json.tool ...`
+4. 真实产物检查：`bash ./scripts/verify_bootstrap_flow.sh`
+
+当前 workflow 显式安装官方 Linux Godot `4.6.2` 构建，并在该版本上运行 headless import 与 `gdUnit4` smoke。
+本地开发建议维持 `4.6.x`；如果本机二进制路径不标准，统一通过 `GODOT_BIN` 注入。

docs/research/godot-plugin-scout-agent.md

@@ -0,0 +1,139 @@
+# Godot 插件探索智能体说明
+
+## Snapshot
+
+这是面向 `godot-toolbox` 的可复用探索智能体说明。
+
+- 版本：`2026-04` 工作流快照
+- 目标：为当前仓库持续扫描 Godot 4.x 生态里仍活跃、仍有采用价值的插件，并给出是否值得内化的判断
+
+## 角色职责
+
+这个探索智能体不负责直接接入插件，只负责做一轮可复核的市场扫描，并把结论整理成适合维护者决策的短名单。
+
+它要回答 4 个问题：
+
+1. 这个插件在 `Godot 4.x` 生态里是否仍活跃。
+2. 它解决的问题是否贴合 `godot-toolbox` 的基线或 pack 方向。
+3. 它是否满足当前仓库的 `selection framework`。
+4. 它应该进入哪一类决策结果：
+   - 适合进 `base`
+   - 适合进新 `pack` 或现有 `pack`
+   - 只应作为外部参考
+   - 不建议纳入
+
+## 输入
+
+探索智能体默认接收这些输入：
+
+- 扫描时间窗口
+- 关注方向
+  - 验证 / 测试
+  - 调试
+  - 工作流效率
+  - 状态机 / 行为
+  - 存档 / 数据
+  - 对话
+  - 导航
+  - 资源管线
+  - UI 工作流
+  - AI / agent 友好能力
+- 当前仓库的约束
+  - `docs/selection-framework.md`
+  - `packs.manifest.json`
+  - 已纳入和已排除项
+
+## 来源优先级
+
+默认按以下顺序取证：
+
+1. `Godot Asset Library`
+2. GitHub 仓库主页
+3. GitHub Releases / Tags
+4. 必要时再看维护者文档或项目主页
+
+不以零散社区传闻作为主证据。
+
+## 评估维度
+
+探索智能体必须沿当前仓库既有的 5 个维度给候选打判断：
+
+1. 自动化价值
+   - 是否适合脚本化、headless、CI、agent 调用
+2. 复用面
+   - 是否能覆盖多数 Godot 项目，而不是只服务单一玩法
+3. 领域耦合
+   - 是否强绑定某个项目的业务模型、编辑器流程或内容生产方式
+4. 维护成本
+   - upstream 是否稳定，版本是否可锁，升级成本是否可控
+5. 真相边界风险
+   - 是否会把项目核心真相埋进第三方插件或重编辑器配置
+
+## 活跃度判断
+
+最小可用扫描里，活跃度至少看这几类信号：
+
+- Godot Asset Library 中仍有 `4.x` 兼容条目
+- GitHub 仓库仍可访问，且存在近期 release、tag 或提交信号
+- README / release 描述没有明显停留在 Godot 3 时代
+
+## 输出格式
+
+每次扫描至少产出一份快照文档，建议命名：
+
+- `docs/research/hot-plugin-scan-YYYY-MM.md`
+
+文档最少包含这些部分：
+
+1. 扫描范围与时间
+2. 来源类型
+3. 5-8 个候选短名单
+4. 每个候选的：
+   - 分类
+   - 推荐优先级
+   - 适配判断
+   - 简短理由
+   - 来源
+5. 总结性建议
+
+## 推荐优先级定义
+
+- `P1`
+  - 值得尽快做 pack 级验证或 PoC
+- `P2`
+  - 有明显价值，但先作为外部参考，等主线稳定后再验证
+- `P3`
+  - 暂时记录，不进入近期路线
+
+## 交付边界
+
+探索智能体的交付止于研究和判断，不自动执行：
+
+- 插件 vendoring
+- `packs.manifest.json` 修改
+- `upstreams.lock.json` 修改
+- pack 目录创建
+
+如果扫描结论被采纳，再由主线维护者进入：
+
+1. 选型确认
+2. upstream 锁定
+3. pack 设计
+4. bootstrap 验证
+5. 升级与维护接线
+
+## 当前默认判断准则
+
+对 `godot-toolbox` 而言，默认更偏好这些候选：
+
+- 能直接增强自动化验证或 agent 工作流
+- 不要求复杂原生编译链
+- 不强制把项目内容创作流程绑定到某个编辑器插件
+- 能作为可选 pack 清晰装卸
+
+默认更谨慎对待这些候选：
+
+- 主要价值来自重编辑器交互
+- 需要额外运行时或桌面服务
+- GDExtension / 原生依赖较重
+- 会与项目主逻辑强耦合