local-test

Local Test 环境规范与治理

流程类 skill；仅在用户明确调用 $local-test 时采用。机制全在 bin/lt（技术栈无关 CLI），项目只需一份 .local-test.yml；本文只留 CLI 替不了你的判断。

门禁适用范围

触发：需要启动或复用本地多服务联调环境做集成测试与功能验收；为项目配置 lt 与 .local-test.yml。仅远端发布受阻本身不触发。

非目标（严禁触发）：单纯跑单元测试；普通代码修改、重构、Bug 修复；代码评审或写文档；发布静态 HTML 给用户看（用 html-preview）；纯远端部署或 CI/CD 配置。

术语

• 本地环境：当前工作机器，含其上所有 git worktree、中间件容器与裸进程。远端 Dev/Beta/staging 都不是。
• worktree 环境：某个 worktree 内由 lt 登记、拥有独立 namespace、端口与库名的一组业务进程。可多个并存。
• 本地开发库（业务服务用）与本地测试库（自动化测试用）：都按 namespace 隔离，生命周期分开管理。

一、先跑 doctor

把 bin/lt 复制或软链到项目 bin/lt，任何操作前先 lt doctor：它检查 git、docker、cksum、进程组隔离方案（setsid / perl / bash job control，macOS 无 setsid 时自动回退并报告采用了哪种）与配置合法性，不启动任何东西。缺件先补，不要带着未知环境直接 start。

二、无配置时：扫描仓库生成

lt init 不做问卷。你扫描仓库产出 JSON 再交给 CLI：cat scan.json | lt init（或 --from-json <file>；已存在配置需 --force 才覆盖）。它同时用 git check-ignore 确认 .local-test/ 被忽略，缺则追加到 .git/info/exclude 并提示。

扫描来源：Procfile*、package.json scripts、docker-compose*.yml、Makefile、.env.example、框架约定。只有一种情况问用户：某个外部系统调用是只读还是写入，代码里判断不出来时（见第五节）。其余自行决策。

.local-test.yml 用 CLI 自带解析器，不依赖 ruby/python/yq。只支持两空格缩进、最多三层、key: value、# 注释（整行或值后带空格）、可选成对单/双引号；不支持列表、锚点、多行标量、TAB、引号内转义。违反即报错并指出行号。

project: saiens                      # 可选，默认仓库目录名
middleware: docker-compose.yml       # 可选
database:
  prepare: bin/rails db:prepare      # 可选，可读 $LOCAL_TEST_NAMESPACE 推导库名
  drop: bin/rails db:drop            # 可选，destroy/gc 用
external:
  mode_env: EXTERNAL_MODE            # 可选；有此项时 real 只允许主 checkout
services:
  web:
    port: 4777                       # 基准端口；实际端口 = 基准 + namespace 偏移
    cmd: bin/rails server -p $LOCAL_TEST_PORT_WEB
  css:
    cmd: bin/rails tailwindcss:watch # 无 port 的服务不做端口守卫
preview_url: http://127.0.0.1:$LOCAL_TEST_PORT_WEB

cmd 运行时由 bash -c 求值，可引用 $LOCAL_TEST_NAMESPACE 与 $LOCAL_TEST_PORT_<服务名大写>；preview_url 只做同名变量替换，不执行。服务顺序即配置顺序：start 按序、stop 逆序。配置原则：中间件容器化且全机一份、按 namespace 分库；业务服务默认裸进程（利于热重载与断点），不为每个 worktree 复制中间件，不用固定槽位环境池，不把未验证代码合入主干来借环境。