实验场 Sibling 仓库规范
jj-flow 产品仓库内部不包含 labs/ 目录。用于端到端机械验证与回归演练的两个实验场仓库(Loop Gym 与 Family Gym)是与 jj-flow 同级(Sibling)存放的独立 Git 仓库。
完整的实验场架构设计请参阅 实验场 Loop Gym / Family Gym 设计文档。本页说明仓库命名、路径发现规则与日常维护步骤。
一、固定仓库名称与克隆地址
实验场所在的父目录因机器而异,但两个实验场仓库的文件夹名称必须保持固定:
| 实验场名称 | 固定目录名 | 本地路径示例(Windows) | 公开 GitHub 仓库地址 |
|---|---|---|---|
| Lab 1 · Loop Gym(单仓闭环演练场) | jj-lab-loop | D:\daji-docs\jj-lab-loop | https://github.com/beerui/jj-lab-loop |
| Lab 2 · Family Gym(多仓同源迁移演练场) | jj-lab-family | D:\daji-docs\jj-lab-family | https://github.com/beerui/jj-lab-family |
在本地准备实验场时,请在与 jj-flow 同级的父目录下克隆并初始化种子工作区:
git clone https://github.com/beerui/jj-lab-loop.git
git clone https://github.com/beerui/jj-lab-family.git
# 克隆后分别进入两个仓库生成本地物化工作区(_materialized/ 不进 Git)
cd jj-lab-loop && node scripts/lab.mjs seed
cd ../jj-lab-family && node scripts/lab.mjs seed四条硬性隔离红线
- 禁止在
jj-flow产品仓内创建labs/目录。 - 禁止在运行脚本中通过
../jj-lab-loop相对路径盲猜目录(必须走显式路径发现规则)。 - 禁止将实验场内部的测试仓库角色命名为
项目A / 项目B / 项目C或project-a(实验场使用loop-gym、notes-alpha、notes-beta)。 - 禁止把本地
lab-roots.json或实验场代码打包进 NPM 发布物(受HNS-PUBLISH-LABS门禁检查)。
二、实验场根路径发现规则(Fail-Closed)
当你运行 npm run lab:check(已包含在 npm run verify 中)时,测试执行器会按以下优先级查找两个实验场的已存在绝对路径(若未配置或目录不存在,立即报错退出,绝不静默跳过):
- 环境变量优先:读取
JJ_LAB_LOOP_ROOT与JJ_LAB_FAMILY_ROOT(必须是已存在的绝对路径)。 - 自定义配置文件路径:读取环境变量
JJ_LAB_ROOTS_FILE指向的 JSON 文件。 - 仓库本地配置文件:读取
jj-flow根目录下的lab-roots.json(你可以复制仓库内的lab-roots.json.example为lab-roots.json并填入本机绝对路径;该文件已在.gitignore中被忽略)。
本地环境变量配置示例
macOS / Linux (POSIX):
export JJ_LAB_LOOP_ROOT="/Users/dev/work/jj-lab-loop"
export JJ_LAB_FAMILY_ROOT="/Users/dev/work/jj-lab-family"
# 或者直接指定配置文件:
export JJ_LAB_ROOTS_FILE="$PWD/lab-roots.json"Windows PowerShell (pwsh):
$env:JJ_LAB_LOOP_ROOT = "D:\daji-docs\jj-lab-loop"
$env:JJ_LAB_FAMILY_ROOT = "D:\daji-docs\jj-lab-family"
# 或者直接指定配置文件:
$env:JJ_LAB_ROOTS_FILE = Join-Path (Get-Location) "lab-roots.json"CI 环境是如何注入实验场路径的?
在 GitHub Actions(Ubuntu verify 与 Windows lab:check)中,工作流会在执行测试前调用 .github/actions/prepare-lab-roots/action.yml,将两个实验场仓库克隆到非 $HOME 下的临时绝对路径(如 /tmp/jj-flow-labs),自动执行 seed 并注入 JJ_LAB_LOOP_ROOT、JJ_LAB_FAMILY_ROOT 与 JJ_FLOW_ROOT。
三、如何升级 CI 中的实验场版本锁(Gym Pin)
CI 不会直接拉取实验场仓库的浮动 main 分支,而是锁定在 .github/actions/prepare-lab-roots/action.yml 中的 loop_ref 与 family_ref 两个 commit SHA 上。
当你修改了 ralph 的目录布局、run_id 格式或门禁契约时,实验场里的机械断言(Oracle)也需要同步更新。升级步骤如下:
- 先更新实验场仓库:将适配新契约的改动提交并合入
jj-lab-loop或jj-lab-family的main分支。 - 本地联调验证:将本地两个实验场检出到目标 commit SHA,重新执行
seed,然后在jj-flow仓库运行npm run lab:check确认全部通过。 - 更新
action.yml版本锁:将.github/actions/prepare-lab-roots/action.yml中loop_ref/family_ref的default:值更新为新的 commit SHA,并运行一遍npm run verify。 - 记录更新日志:在
CHANGELOG.md的## Unreleased中记录本次实验场版本锁升级。
(注:关于旧版本锁 ed72b08 的过渡兼容层保留在 scripts/lab-overlays/jj-lab-loop/ 下,当前版本锁 75461e1 / 652d1f5 已原生支持新版契约,overlay 自动为 no-op。)
四、实验场内部结构与工作目录边界
每个实验场仓库包含顶层说明文档、.gitignore(必须忽略 _materialized/)、lab-manifest.json、seed/、scripts/lab.mjs、scripts/oracles/ 与 scenarios/。
在实验场执行测试或演练时,必须在物化后的目标目录(_materialized/)下运行,严禁在种子根目录或 jj-flow 产品仓库根目录直接写入业务测试提交:
| 演练动作 | 正确的当前工作目录(cwd) |
|---|---|
| Loop Gym 单仓闭环 | $JJ_LAB_LOOP_ROOT/_materialized/loop-gym |
| Family Gym 源仓开发与交接 | $JJ_LAB_FAMILY_ROOT/_materialized/family-gym/notes-alpha |
| Family Gym 目标仓同源迁移 | $JJ_LAB_FAMILY_ROOT/_materialized/family-gym/notes-beta |
严禁作为业务写入 cwd 的目录 | jj-flow 产品仓根、jj-lab-* 种子仓根、family-gym/ 外层包装目录、control/ |