Gas Town Phase 4 最小修复批次验收指南e2e 容器测试与角色路径回归验证【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown本文是 Gas Townmulti-agent workspace manager仓库中 docs/phase4-minimum-fix-acceptance.md 的技术解读与实战扩展。该文档冻结了 Phase 4 最小修复批次的最终验收命令与可直接粘贴的 PR 摘要本文在此基础上结合仓库源码Makefile、Dockerfile.e2e、role 集成测试、Dolt 元数据写入逻辑等逐项展开你读完将掌握两条官方验收命令的确切含义与参数作用、四条核心修复背后的实现机制以及如何判断“PASS / SKIP / 警告”各状态是否属于预期结果。一、背景什么是 Phase 4 最小修复批次Phase 4 最小修复批次是围绕安装install、角色role路径回归与端到端容器验收的一批收敛性修复。它的特点在于验收标准先行文档先固定了最终验证命令再给出该批次修复内容的 PR 摘要最后用两条命令的实际运行结果作为放行依据。整个批次围绕四个目标展开修复调度器scheduler集成测试中的 JSON 输出污染问题让 Dolt 元数据写入具备幂等性保持 mayor 工作区干净通过固定工具链版本与重试机制提升 e2e 容器可靠性稳定嘈杂环境下的安装与角色集成行为formula 供给韧性、角色命令预运行噪音抑制、在线 smoke 检查容错。文档还明确了验收前提命令需在gastown-main目录下运行其中go test那条是面向角色路径回归的WSL 最小 smoke 验证。二、两条验收命令全解2.1 全量容器验收make test-e2e-containermake test-e2e-container这条命令是“唯一受支持”的 e2e 测试运行方式Makefile 注释原文Run e2e tests in isolated container (the only supported way to run them)。其目标定义位于 Makefile核心流程是构建隔离镜像docker build $(E2E_BUILD_FLAGS) -f Dockerfile.e2e -t $(E2E_IMAGE) .运行容器docker run $(E2E_RUN_FLAGS) $(E2E_IMAGE)容器镜像基于golang:1.26-alpine由 Dockerfile.e2e 构建。该容器提供完整隔离没有宿主机 tmux 会话干扰、文件系统干净不存在既有 Gas Town 安装、独立的 beads 守护进程与 Dolt 服务器。容器内依次完成安装依赖git、bash、sqlite、build-base、zstd-dev、icu-dev、procps、lsof、tmux其中procps与lsof是gt dolt start做进程校验所必需的安装固定版本的 beads 守护进程bdARG BD_VERSIONv0.57.0与 DoltARG DOLT_VERSION2.0.7从源码 tagv${DOLT_VERSION}克隆后go install ./cmd/dolt配置 git 与 dolt 的身份信息user.name/user.email/init.defaultBranch main编译 gt 主程序到/usr/local/bin/gt并通过-ldflags -X .../internal/cmd.BuiltProperly1标记为“正式构建”以go test -tagse2e -timeout5m -v -count1 -parallel 1 -run TestInstall ./internal/cmd/...作为容器入口命令执行 e2e 测试。值得注意的 Makefile 可调参数Makefile变量默认值作用E2E_IMAGEgastown-test镜像名E2E_BUILD_FLAGS空透传给docker build可用于传递构建上下文优化参数E2E_RUN_FLAGS--rm透传给docker runE2E_BUILD_RETRIES1docker build 失败时的最大重试次数E2E_RUN_RETRIES1docker run 失败时的最大重试次数Linux/macOS 下目标体用while循环实现重试构建或运行失败时打印docker build failed (attempt N), retrying...间隔 2 秒重试达到上限才exit 1Windows 下用 PowerShell 实现等价逻辑。2.2 角色路径回归最小 smokego test定向运行go test ./internal/cmd -tagsintegration -run TestRoleHomeCwdDetection\|TestRoleEnvCwdMismatchFromIncompleteDir -count1 -v这条命令逐段拆解如下./internal/cmd测试包路径角色集成测试位于 internal/cmd/role_e2e_test.go-tagsintegration启用//go:build integration构建标签否则该文件根本不会被编译见文件首行-run TestRoleHomeCwdDetection\|TestRoleEnvCwdMismatchFromIncompleteDir正则匹配两个回归测试函数——TestRoleHomeCwdDetectioninternal/cmd/role_e2e_test.go与TestRoleEnvCwdMismatchFromIncompleteDirinternal/cmd/role_e2e_test.go最小化验证面-count1禁用 Go 测试缓存强制本次真实执行容器 e2e 入口也使用了-count1-v输出每个子用例的详细结果。这两个测试都通过 internal/cmd/test_helpers_test.go 的buildGT辅助函数在测试运行前临时编译 gt 二进制带BuiltProperly1ldflags且在同一次运行内缓存复用随后在一个临时 HOME 中执行gt install hq --no-beads搭建最小 town 结构。TestRoleHomeCwdDetection验证无参数gt role home能根据当前目录cwd自动识别角色。它先手工创建witness、refinery/rig、polecats/Toast、crew/worker1等目录再分别从 mayor、deacon、witness、refinery/rig、polecats/Toast、crew/worker1 目录运行gt role home断言输出与预期路径完全一致。TestRoleEnvCwdMismatchFromIncompleteDir验证在“不完整目录”如refinery缺/rig下执行带环境变量的gt role env时是否产生 cwd 不匹配警告同时确认 polecat/crew 的 home 就是polecats/name、crew/name不要求/rig因此这些场景不应出现 mismatch 警告——这正是角色路径回归的边界语义。同文件还包含同族的完整回归矩阵TestRoleHomeE2Einternal/cmd/role_e2e_test.go、TestRoleHomeMissingFlags、TestRoleEnvCwdDetection、TestRoleListE2E、TestRoleShowE2E、TestRoleDetectE2E等覆盖角色 home/env/list/show/detect 的全部分支可视为本条命令的扩展集。三、运行结果与状态解读文档冻结的最近一次运行结果make test-e2e-containerPASSgo test ./internal/cmd -tagsintegration -run ...PASS同时文档给出两条重要的“结果解读”备注理解它们才能正确判断验收是否真正通过SKIP 是预期行为当测试环境的特定外部二进制不可用时部分集成用例会有意 SKIP例如 internal/cmd/agents_test.go 在 tmux 不可用时跳过 stdout 校验。因此看到 SKIP 不代表失败关键是确认被跳过的用例与本次验收范围无关。doctor 警告是预期噪声集成日志中出现的 doctor 警告在合成测试环境中是预期的不阻塞通过/失败结论。install_integration_test.go 的TestInstallDoctorClean注释也印证了这一点完整doctor --fix验证当前受已知问题限制bead 创建的 UNIQUE 约束错误、容器缺 tmux、测试仓库不满足 priming 预期因此 doctor 相关断言采取“能验证核心结构即可”的务实策略。四、四条修复的源码级拆解4.1 调度器集成JSON 输出污染修复修复目标保持测试辅助函数成功路径只输出 stdout仅在失败时暴露 stderr避免调度器集成测试被 bd 的噪音输出污染而解析出脏 JSON。实现证据在 internal/cmd/scheduler_epic.go 的bdDepListFallback中bd 调用被链式配置为AllowStale().Dir(dir).StripBeadsDir().Stderr(io.Discard).Output()——即成功路径把 stderr 丢弃、只捕获 stdoutstdout 再交给json.Unmarshal解析依赖 ID 列表仅在出错且无输出时兜底返回空。这一约定由 internal/cmd/bd_helpers.go 的Output()方法支撑注释明确Output() captures stdout but Stderr must still be configured。角色集成测试同样采用此约定role_e2e_test.go 用cmd.Output()只取 stdout让警告走 stderr 而不污染断言。4.2 Dolt 元数据写入幂等化修复目标让.beads/metadata.json在内容未变化时不再被重写no-op从而保持 mayor 工作区干净、避免被 git 追踪的 metadata.json 产生无意义 diff。实现证据核心实现在 internal/doltserver/doltserver.go 的EnsureMetadataForBeadsDir。该函数先读取已存在的 metadata.json保留额外字段再逐字段比对期望值database应为dolt、backend应为dolt、dolt_mode应为serverdolt_database为空或错误时修正注释指出错误值如beads_gt会导致难以诊断的 PROJECT IDENTITY MISMATCHgas-tc4 回归dolt_server_host/dolt_server_port与权威配置config.yaml env daemon.json 默认对齐防止陈旧的dolt_server_port如历史bd init留下的 13729引发 connection refused。关键设计是changed标志所有字段比对完成后若!changed直接return nilfast path不触碰文件系统只有真正需要修正时才json.MarshalIndent重写。配套的 internal/rig/manager.go 在 rig 初始化流程中调用该函数并通过 per-path mutex 保证并发调用安全EnsureAllMetadata会并发触发写入。此外 manager.go 注释明确指出bd migrate --update-repo-id也是幂等的新旧数据库均可安全执行。4.3 e2e 容器可靠性加固修复目标提升容器测试的确定性消除网络抖动与工具链漂移导致的偶发失败。实现证据均在 Dockerfile.e2e 中可见固定工具链版本ARG DOLT_VERSION2.0.7、ARG BD_VERSIONv0.57.0避免“今天拉到的 latest 明天行为不同”安装重试循环bd通过go install github.com/steveyegge/beads/cmd/bd${BD_VERSION}安装Dolt 通过git clone --depth 1 --branch v${DOLT_VERSION}从源码构建两者都包裹在for i in 1 2 3的重试循环中失败间隔 2 秒重试第 3 次仍失败才exit 1吸收网络瞬时故障go mod download同样带重试构建上下文优化先COPY go.mod go.sum再COPY . .利用 Docker 层缓存避免依赖变更触发全量重建Makefile 侧配合E2E_BUILD_RETRIES/E2E_RUN_RETRIES默认1可按需提升重试次数如 CI 抖动环境可覆盖为make test-e2e-container E2E_RUN_RETRIES3。4.4 安装与角色行为的嘈杂环境稳定化修复目标在 CI 或容器这类“嘈杂环境”存在瞬时 Dolt 启动竞态、外部命令输出噪音中让安装与角色集成行为可预测、可判定。实现证据分散在三个层面formula 供给韧性internal/formula/embed.go 将 formula 文件嵌入二进制并在安装时供给到.beads/formulas/安装集成测试install_integration_test.go 注释Run gt install (includes beads and formula provisioning)验证安装过程包含 formula 供给供给失败不拖垮整个安装流程。角色命令预运行噪音抑制internal/cmd/role.go 在不完整环境变量被 cwd 补齐时把⚠️ Warning: env vars incomplete, filled from cwd写到stderr而非 stdout保证gt role env的 stdout 保持可被eval/脚本直接消费的纯净 export 序列对应测试 TestRoleEnvIncompleteEnvVars 正是按“stdout 含 export、stderr 含 warning”分别断言的。在线 smoke 检查容错install_integration_test.go 的在线前缀校验bd config get issue_prefix在失败时区分两种情形若输出包含Dolt server still unreachable或connect: connection refused判定为 Dolt 启动的瞬时竞态记录bd online prefix check skipped due transient Dolt unreachability后跳过保持测试确定性其他错误才Fatalf判失败。gt dolt start相关逻辑internal/cmd/dolt.go同样内置重试因为Start()只等待 500ms数据库可能仍在加载。五、验收工作流总结与复现建议将文档中的验收流程固化为可重复的检查清单全量 e2e在gastown-main目录执行make test-e2e-container观察最终 PASS角色路径回归执行go test ./internal/cmd -tagsintegration -run TestRoleHomeCwdDetection\|TestRoleEnvCwdMismatchFromIncompleteDir -count1 -v确认两个测试及其子用例全部通过结果判定对 SKIP 用例核对是否因外部二进制缺失而有意跳过对 doctor 警告核对是否属于合成环境预期噪声发布 PR直接粘贴 docs/phase4-minimum-fix-acceptance.md 中准备好的 PR 摘要Summary / Validation / Notes 三段式其中 Validation 部分如实记录上述两条命令的 PASS 结果。对仓库维护者与贡献者而言该文档与 install_integration_test.go、role_e2e_test.go、Dockerfile.e2e、Makefile 共同构成“验收命令 → 测试定义 → 容器环境 → 修复实现”的完整证据链文档冻结的是结论源码与测试则是可随时复核的依据。后续若修改角色路径、Dolt 元数据或调度器集成逻辑都应重新运行这两条命令作为回归门槛。【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考