企业官网建设流程全解析

导读

在 gsd-core（Git. Ship. Done — Core）中，loadConfig是项目配置加载的核心入口，负责读取.planning/config.json、合并内置默认值、迁移遗留配置键并完成工作流（workstream）覆盖。本文围绕 changeset 315-subrepo-detect-memo.md 记录的修复展开：当「配置迁移」与「文件系统重新同步」在同一轮loadConfig调用中同时触发时，detectSubRepos(cwd)最多会被重复执行 3 次，产生冗余的目录扫描；修复后引入 per-call（每次调用级）的惰性 memo，将扫描次数收敛为恰好 1 次。读完本文，你将掌握该优化的实现原理、三个触发站点、回归测试的验证手法，以及planning.sub_repos配置与子仓库检测之间的联动关系。

一、背景：detectSubRepos 在配置加载中的角色

1.1 什么是子仓库检测

detectSubRepos(cwd)是 gsd-core 中用于发现「当前目录下独立 Git 子仓库」的工具函数，其规范实现位于 src/core-utils.cts：

function detectSubRepos(cwd: string): string[] { const results: string[] = []; try { const entries = fs.readdirSync(cwd, { withFileTypes: true }); for (const entry of entries) { if (!entry.isDirectory()) continue; if (entry.name.startsWith('.') || entry.name === 'node_modules') continue; const gitPath = path.join(cwd, entry.name, '.git'); try { if (fs.existsSync(gitPath)) { results.push(entry.name); } } catch { /* ignore */ } } } catch { /* ignore */ } return results.sort(); }

从源码可以归纳出它的行为契约：

• 只扫描一层：仅检查cwd的直接子目录（entry.isDirectory()），不做递归；
• 判定依据：子目录下存在.git（文件或目录均可，fs.existsSync与类型无关，因此同时兼容普通仓库与 worktree）；
• 排除规则：跳过隐藏目录（以.开头）与node_modules；
• 错误容忍：readdirSync与existsSync的异常均被吞掉，目录不可读、路径不存在时返回空数组而非抛错；
• 确定性输出：结果经过sort()，保证返回顺序稳定，便于后续比较与写回。

该函数的边界行为在 tests/core-utils.test.cjs 中有系统性覆盖：空目录返回[]、不存在的路径返回[]、单子仓库返回['myrepo']、worktree 形态（.git为文件）也能识别、node_modules与隐藏目录被排除、多仓库结果按字典序排列（['a-repo', 'm-repo', 'z-repo']）。

1.2 检测结果流向何处

detectSubRepos的检测结果最终会写入配置键planning.sub_repos。根据 docs/CONFIGURATION.md 的说明：

planning.sub_repos（array of strings，默认[]）：相对项目根目录的嵌套子仓库路径列表。设置后，GSD 相关工具链会按子仓库划分阶段查找、路径解析与提交操作，而不再把外层仓库当作单仓库（monorepo）处理。

也就是说，子仓库检测不是一次性的「一次性扫描」，而是配置解析过程中的依赖输入——loadConfig需要它来完成两项工作：迁移时补全缺失的sub_repos，以及配置读取后校验/同步已存在的sub_repos是否与磁盘现状一致。

二、问题剖析：一次 loadConfig 调用里的三次冗余扫描

修复前的loadConfig在同一次调用中，可能以完全相同的cwd触发detectSubRepos(cwd)最多 3 次。回归测试 tests/perf-315-loadconfig-subrepo-scan.test.cjs 的头部注释精确记录了这三个站点：

从修复后的源码可以反向定位到这三个调用点，全部位于 src/config-loader.cts：

• Site 1（L739）：根配置经normalizeLegacyKeys迁移时，遇到requiresFilesystem归一化项且planning.sub_repos未设置，则调用检测函数补全；
• Site 2（L796）：工作流配置文件走同样的迁移逻辑，条件一致；
• Site 3（L810）：配置文件迁移完成后，若planning.sub_repos已是非空数组，则与磁盘实际检测结果比对，不一致时用检测结果覆盖并标记configDirty以便回写。

问题在于：这三个站点传入的都是同一个cwd，扫描结果是完全相同的。每次扫描都要执行一次fs.readdirSync(cwd, { withFileTypes: true })全量列举目录项，再对每个子目录做existsSync(.git)探测。当项目根目录下存在大量子目录、或文件系统调用本身昂贵（如网络盘、容器 overlayfs）时，这种重复劳动会成倍放大loadConfig的 I/O 成本——而这还只是「配置加载」这一步，尚未进入后续的计划扫描与阶段解析。

三、修复实现：per-call 惰性 memo 的源码级解析

3.1 核心改动

修复方案是在loadConfig的解析内部函数loadConfigResolvedInternal中，引入一个每次调用级的闭包缓存（src/config-loader.cts）：

let cachedSubRepos: string[] | undefined; const getDetectedSubRepos = (): string[] => { if (cachedSubRepos === undefined) cachedSubRepos = detectSubRepos(cwd); return cachedSubRepos.slice(); };

这个实现值得拆解三个关键设计：

1. 作用域绑定到单次loadConfig调用：cachedSubRepos定义在loadConfigResolvedInternal函数体内，每次调用都会重新创建。这保证了缓存只服务于「这一次解析」，不会跨调用污染——不同调用可能携带不同的cwd，模块级缓存反而会引入错误，而 per-call 缓存天然避免了这个问题。
2. 惰性求值（lazy）：detectSubRepos(cwd)只在第一次真正需要时才执行。如果某次调用根本没有触发迁移或重新同步（最常见的「配置已是最新」场景），则一次目录扫描都不会发生，这是惰性比急切（eager）求值更优的地方。
3. 返回副本cachedSubRepos.slice()：调用方拿到的是数组拷贝，而非内部缓存引用。这样即使后续代码意外修改了返回值（比如push、sort），也不会破坏缓存本身，保证了多次调用站点之间读取结果的一致性。

3.2 三个站点的统一收敛

改造后，三个站点不再各自直接调用detectSubRepos(cwd)，而是统一改为getDetectedSubRepos()：

// Site 1 — root config 迁移（L739） const detected = getDetectedSubRepos(); if (detected.length > 0) { if (!isConfigSection(rootNormalized.planning)) rootNormalized.planning = {}; rootNormalized.planning['sub_repos'] = detected; rootNormalized.planning['commit_docs'] = false; } // Site 2 — workstream config 迁移（L796） const detected = getDetectedSubRepos(); // …… 与 Site 1 相同的补全逻辑 // Site 3 — sub_repos 文件系统重新同步（L810） const detected = getDetectedSubRepos(); if (detected.length > 0) { const sorted = [...currentSubRepos].sort(); if (JSON.stringify(sorted) !== JSON.stringify(detected)) { fileData.planning['sub_repos'] = detected; configDirty = true; } }

由于三处读的都是同一个cachedSubRepos，第一次调用执行真实扫描，后两次直接命中缓存——3 次readdirSync被压缩为 1 次。这正是 changeset 中「collapsing up to 3 redundant directory scans into 1」的直接体现。

需要说明的是：Site 3 的重新同步逻辑本身也体现了「确定性」要求——它把现有sub_repos排序后与检测结果（detectSubRepos内部已排序）做JSON.stringify比较，只有不一致才标记configDirty并触发写回，避免无意义的磁盘写入。

四、回归测试：用 readdirSync spy 锁死「恰好一次」

任何性能修复都必须有可验证的回归测试，否则优化很容易在后续重构中被悄悄回退。tests/perf-315-loadconfig-subrepo-scan.test.cjs 给出了一个非常干净的验证手法。

4.1 测试夹具构造

测试先在临时目录里构造出一个「同时命中三个站点」的项目：

// 根配置：multiRepo: true → 触发 Site 1（root requiresFilesystem 迁移） writeRootConfig(tmpDir, { multiRepo: true, model_profile: 'balanced' }); // 工作流配置： // planning.sub_repos 已设置 → 触发 Site 3（文件系统重新同步） // multiRepo: true → 触发 Site 2（workstream requiresFilesystem 迁移） writeWorkstreamConfig(tmpDir, 'test-ws', { multiRepo: true, planning: { sub_repos: ['sub-service'] }, model_profile: 'balanced', });

目录布局上，createProjectWithSubRepo会创建一个带.git的子目录sub-service，以及.planning/phases根布局——这恰好满足detectSubRepos能扫出子仓库的前提。

4.2 断言策略：精确计数 readdirSync 调用

测试通过 monkey-patchfs.readdirSync实现调用计数，且过滤条件精确匹配detectSubRepos的调用签名——第一个参数是cwd，第二个参数包含withFileTypes: true：

let scanCount = 0; const originalReaddirSync = fs.readdirSync; fs.readdirSync = function spyReaddirSync(dirPath, opts) { if (dirPath === tmpDir && opts && opts.withFileTypes === true) { scanCount += 1; } return originalReaddirSync.call(this, dirPath, opts); }; const config = loadConfig(tmpDir, { workstream: wsName }); // 行为锁：sub_repos 确实被正确解析出来 assert.ok( Array.isArray(config.sub_repos) || Array.isArray(config.planning?.sub_repos), 'sub_repos should be an array in the returned config' ); // 性能断言：无论多少个站点触发，扫描恰好一次 assert.strictEqual( scanCount, 1, `Expected detectSubRepos to scan cwd exactly once, but fs.readdirSync was called ${scanCount} time(s) ...` );

这个测试同时锁住了两个维度：

• 行为正确性（行为锁）：memo 不能破坏原有功能——sub_repos必须仍被解析为非空数组；
• 性能契约（性能断言）：withFileTypes: true签名的readdirSync恰好调用 1 次，证明三个站点共享了同一次扫描。

测试在finally中恢复原始fs.readdirSync，保证 spy 不会泄漏到其他测试。这套「行为锁 + 调用计数」的组合，也值得推广到其他「同一输入被多次计算」类性能修复的回归测试中。

五、配置联动：multiRepo、requiresFilesystem 与 sub_repos 的协同

5.1 触发条件如何进入配置解析

multiRepo: true与planning.sub_repos是驱动上述三个站点的两个关键配置形态：

• multiRepo（多仓库模式）：声明项目由多个子仓库组成。normalizeLegacyKeys中对应的归一化项带有requiresFilesystem标记——这意味着迁移该配置键必须读取文件系统，即通过detectSubRepos探测真实的子仓库清单；
• planning.sub_repos显式声明：用户已在配置中写明了子仓库路径。此时loadConfig需要校验声明与磁盘现状是否一致，不一致则以磁盘为准（按 docs/CONFIGURATION.md 的语义，子仓库路径必须以项目根为基准）。

迁移完成后，配置还会经过federated config（ADR-857 phase 3b）的合并与未知键告警等后续处理（src/config-loader.cts），但那些步骤已不再需要子仓库扫描——这也正是 memo 能把扫描「提前一次性做完、后续零成本读取」的前提。

5.2 与 init 流程的关系

需要澄清一个容易混淆的点：detectSubRepos并不只在loadConfig中使用。在项目初始化流程 src/init.cts 中，init命令同样会调用coreUtils.detectSubRepos(cwd)并把结果写入sub_repos_detected字段：

// children (.git is a FILE there). detectSubRepos already handled this sub_repos_detected: coreUtils.detectSubRepos(cwd),

这印证了detectSubRepos是一个被多处复用的底层工具函数（CONTEXT.md 也将其列为 core-utils 的核心原语之一）。PR #315 的 memo 优化只作用于loadConfig内部的多次调用场景——init中只调用一次，本就不存在冗余问题；同时这也说明，per-call memo 的边界设计（每次loadConfig调用独立缓存）恰好不会影响其他调用方。

六、边界条件与注意事项

1. 缓存只在单次调用内有效：cachedSubRepos的生命周期与loadConfigResolvedInternal一致。如果同一次进程内多次调用loadConfig（如不同工作流的解析），每次调用仍会重新扫描。这是刻意为之——cwd可能不同、磁盘状态可能变化，跨调用缓存反而会引入陈旧数据。
2. slice()副本的防御价值：返回副本意味着任何调用点对数组的修改（如 Site 3 中的[...currentSubRepos].sort()）都不会污染缓存，三个站点的读取始终一致。
3. 错误路径上的行为不变：detectSubRepos内部对readdirSync/existsSync的异常采取吞掉策略，因此即使cwd不可读，memo 也只是缓存一个空数组，loadConfig的整体降级（fallback）语义不受影响——这与 src/config-loader.cts 注释中「Faults are captured, not thrown」的设计哲学一脉相承。
4. requiresFilesystem的门槛：memo 只在实际需要文件系统信息（requiresFilesystem归一化项或sub_repos重新同步）时才触发。绝大多数「配置已是最新、无需迁移」的调用路径完全不会执行目录扫描，这也是惰性设计优于在所有调用中无条件扫描的关键。

七、总结

PR #315 的这次修复，用一段不足十行的 per-call 惰性 memo，把loadConfig内部最多 3 次的重复子仓库目录扫描收敛为恰好 1 次，并配套了以readdirSyncspy 精确计数的回归测试。它体现了几条值得借鉴的性能工程原则：

• 识别「同输入重复计算」：三个站点使用相同cwd调用同一函数，结果必然相同，属于典型的重计算；
• 缓存边界贴近计算生命周期：缓存放在单次loadConfig调用内部，既不跨调用污染，也不影响其他调用方（如init）；
• 惰性求值优于无条件缓存：只在真正需要时才扫描，无迁移场景零开销；
• 性能修复必须带行为锁：sub_repos解析正确性的断言与扫描计数断言并存，防止「为了性能牺牲功能」或「为了正确性回退性能」。

对于关注 gsd-core 配置系统内部实现的读者，建议沿着 src/config-loader.cts、src/core-utils.cts、tests/perf-315-loadconfig-subrepo-scan.test.cjs 这条链路继续深入；若关心planning.sub_repos的完整配置语义与子仓库工作流，可查阅 docs/CONFIGURATION.md 与 docs/COMMANDS.md。