跳转至

设计文档:EGM 仓库与包引导(egm-bootstrap)

  • 作者: Brian Suchy (@briansuchy)
  • 状态: 当前
  • 日期: 2026-06-29

1. 概述与问题陈述

1.1 问题

在大型单体代码库中,建立并维护清晰的架构心智模型是人类开发者和 AI 助手面临的主要挑战。

  • 上下文丢失:如果没有结构化的目录级文档,AI 代理就会缺乏关于局部不变量、公共接口和副作用(side effects)的上下文。这会导致上下文窗口膨胀、重复的文件读取循环,以及引入回归的风险。
  • 单体规模:为大型仓库手动引导目录 README 是一项繁重而琐碎的任务,开发者往往会降低其优先级。

1.2 概述与“花生与干草”隐喻

我们为 EGM 插件提出了 egm-bootstrap 技能。该技能可自动完成目录树中符合 Design is the New Code (DNC) 规范的 README.md 文件的创建、修正、格式化和正确性验证。

  • DNC 合规性:Design is the New Code (DNC) 是 EGM 的工程理念,它将人类可读的架构契约(目录 README 中的不变量、接口和副作用)视为主要系统资产。这些文档文件为人类审查者和 AI 代理同样提供结构化护栏。
  • 隐喻映射:在此上下文中,“Peanuts(花生)”和“Hay(干草)”均指生成的目录级 README.md 文件:
    • Peanuts(花生):细粒度的叶子级组件包 README,包含具体的文件契约。
    • Hay(干草):父级仓库蓝图,汇总子接口契约以提供高层索引。

为了确保性能、效率和健壮性,该技能会根据目标代码库的规模动态扩展其执行模型:

  1. 增量范围界定:Root Orchestrator 使用原生文件系统 API(list_dir)逐层映射目录树。如果在发现过程中目录数量超过规模限制,它会立即暂停并警告用户,防止在大型仓库上挂起。
  2. 顺序执行(小目录树):如果目标包含 5 个或更少的子目录,Root Orchestrator 会按后序遍历顺序依次爬取并为它们编写文档,避免多代理协调和启动开销。
  3. 无界并行蜂群(中/大型目录树):如果目标包含超过 5 个子目录,Root Orchestrator 将对目录树进行分区,并生成编排器代理自身的并行实例(使用框架的 self 子代理类型)作为 Sub-Orchestrator(每个子树一个)。
    • 自适应深度分区:为了防止在具有单一嵌套源树(例如 src/ 或 java/)的仓库中出现并行化瓶颈,Root Orchestrator 使用自适应深度进行分区,沿着发现图的层级向下推进,直到将目录拆分为均衡的子树分支。
    • 获批后无界生成:Root Orchestrator 取消人为的并发限制。如果目录数量较大(> 5),它会请求用户批准生成所需数量的 Sub-Orchestrator,然后并行生成全部 Sub-Orchestrator。
    • 直接蜂群写入与格式化:Sub-Orchestrator 并行处理各自的子树,直接在其指定文件夹中写入或修改 README.md 文件,并使用 mdformat 对其进行格式化。
  4. 自底向上的顺序处理:在每个子树内,Sub-Orchestrator 以后序顺序(先最深的叶子节点)依次为子目录编写文档,并生成 goldfish-explorer 代理来汇总文件。这保证了父目录只会在其子目录完成后才被编写文档,从而防止竞态条件。
  5. 最终正确性验证:在结束工作之前,Root Orchestrator 会对所有创建和修改的 README 执行最终检查,以验证 DNC 合规性、正确的 Markdown 格式、有效的相对链接和有效的验证目标。
  6. 可选漂移审查:Root Orchestrator 可选地提示用户对生成的 README 更新运行 EGM Drift Report,以确保与代码库的一致性。

1.3 目标

  • 自动化引导与修正:递归地为任何目标源目录树生成或修正符合 DNC 规范的 README(Interface、Invariants、Side Effects)。现有 README 会被修正和更新,而不会被完全覆盖。
  • 幂等的哨兵块 Upserting:通过将自动生成的 DNC 契约封装在显式 HTML 哨兵标记(<!-- EGM_BLUEPRINT_START ... --> / <!-- EGM_BLUEPRINT_END -->)内,保证现有 README.md 文件中人类操作文档零丢失,并在多次运行之间逐字节保留哨兵上方所有人工操作手册内容。
  • Markdown 格式化:确保每个修改或创建的 README 都使用 Markdown 格式化程序正确格式化。
  • 最终正确性检查:在结束工作前,对所有修改过的 README 执行一次最终验证,作为正确性检查。
  • 安全扩展:通过动态用户警告、增量 BFS 范围界定、子树分区以及用户批准后的无界并行执行,处理深层/宽层目录树。

1.4 非目标

  • 代码生成:该技能不会编写或重构任何功能性源代码;它严格限于文档工作。
  • 非源目录:它不会为隐藏系统目录(例如 .git、.jj、.gemini)、构建输出路径或依赖目录(例如 third_party)编写文档。

1.5 关键用户旅程(CUJs)

CUJ 1:引导、纠正、格式化并验证目录树中的 READMEs

  • 前提:一个源目录树(例如 src/ 或 pkg/),其中子目录要么缺少 README.md 文件,要么包含不完整的旧版 READMEs。
  • 当:用户通过斜杠命令 /egm-bootstrap <path>(或等效于 harness 的命令/prompt)运行 egm-bootstrap 技能,并指定目标根目录。
  • 然后:
    1. Root Orchestrator 增量式地映射目录树。
    2. 如果目录数量 <= 5,则按顺序处理它们。
    3. 如果目录数量 > 5,则自适应地划分目录树,请求用户批准,并生成无上限的并行工作实例(即编排器代理自身的 self 子编排器)。
    4. 子编排器自底向上处理其子树,为每个目录节点生成一个 goldfish-explorer 代理。
    5. 创建或纠正符合 DNC 的 README.md 文件,并使用 mdformat 格式化。
    6. Root Orchestrator 对所有修改过的 READMEs 执行最终的正确性检查。
    7. 可选地提示用户对更新运行 Drift Report。

2. 技术方案

2.1 群体架构与角色

egm-bootstrap 技能恰好使用两种代理配置:

graph TD
    Root[Root Orchestrator] -->|list_dir BFS| Map[Directory Map]
    Root -->|Spawn Sub-Tree A| Worker1[Sub-Orchestrator A]
    Root -->|Spawn Sub-Tree B| Worker2[Sub-Orchestrator B]
    Worker1 -->|Seq: Leaf A.1| Exp1[Explorer: A.1 Directory]
    Worker1 -->|Seq: Parent A| Exp2[Explorer: A Directory]
    Root -->|Final Pass| Verify[Correctness Check & Format]
  • 节点编排器(bootstrap-orchestrator):
    • 以单一代理配置实现。
    • Root 实例协调整个流水线:增量映射目录树、计算数量/深度、管理安全闸门、在用户批准后管理无上限的并行工作实例的生成、记录剩余的中间目录、编制最终的根 README,并执行最终的正确性检查。
    • 工作实例(子编排器)由 Root 实例生成,用于处理特定的顶级子目录树。它们自底向上顺序遍历子树,生成探索器,直接在文件系统中写入或修改 README 文件,并使用 mdformat 格式化。
  • goldfish-explorer:

    • 一个只读的动态侦察代理。
    • System Prompt:> “你是一个只读的代码库探索器。你的任务是分析目标目录中的源文件,并返回简明、事实性的摘要。不要写入或修改任何文件。返回一个 JSON 对象,其中包含该目录的公共符号(接口)、不变量和副作用。”
    • 侦察文件约束:侦察代理将每个目录的总数据读取量限制在 50,000 字节,以防止上下文窗口膨胀。实现文件和模式文件(例如 .cc、.py、.java、.go、.rs、.ts)每个文件最多读取 300 行。如果目录的大小超过 50KB 限制,则根据以下优先级列表选择要读取的文件:
      1. 接口、模式、IDL 和头文件(例如 .h、.hh、.hpp、.proto、.graphql、.gql、.thrift、.prisma、.sql 模式/DDL 定义、接口类)会被完整读取。
      2. 模块入口点(例如 main.*、index.*、lib.*、mod.*、__init__.py,或与目录名匹配的文件)最多读取 300 行。
      3. 按字母顺序排序的生产源代码和配置文件最多读取 300 行,直到达到字节上限。
      4. 在上下文加载期间,测试文件会被完全忽略。
    • 输出模式:

      {
        "type": "object",
        "properties": {
          "interface": {
            "type": "array",
            "items": { "type": "string" }
          },
          "invariants": {
            "type": "array",
            "items": { "type": "string" }
          },
          "side_effects": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["interface", "invariants", "side_effects"]
      }
      

2.2 代理报告与上下文契约

通信遵循层级式报告模式:

  1. 探索器到子编排器:goldfish-explorer 分析目录中的所有文件,并将其结构化 JSON 摘要(接口、不变量、副作用)返回给其父级 bootstrap-orchestrator。
  2. 父上下文传播:当子编排器处理父目录 P 时,它会在调用父目录的 goldfish-explorer 侦察代理时,将其子目录的已编译接口摘要作为 prompt 上下文传播。这使得父探索器能够准确总结子接口边界。
    • 传播启发式规则:
      1. 如果子目录在本次执行运行期间已被记录,子编排器直接从内存执行缓存(或工作进程返回的 JSON 载荷)中检索其公共接口,直接使用结构化数据。
      2. 如果子 README 已被纠正/修改,子编排器直接从侦察扫描和遗留提取中检索更新后的符号。
  3. 子目录到父编排器:子目录将其编译后的 README 摘要返回给父级 bootstrap-orchestrator,父编排器用它来记录父目录的“Subdirectories”接口部分。
  4. 工作进程到 Root Orchestrator:子编排器使用下面定义的结构化 JSON 模式,将其编译后的子树契约元数据返回给 Root Orchestrator。

2.2.1 工作进程返回接口模式

Sub-Orchestrator 的工作子代理使用以下模式报告已完成的子树结构:

{
  "type": "object",
  "properties": {
    "subtree_index": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "summary": { "type": "string" },
          "interface": { "type": "array", "items": { "type": "string" } },
          "invariants": { "type": "array", "items": { "type": "string" } },
          "side_effects": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["path", "summary"]
      }
    }
  },
  "required": ["subtree_index"]
}

2.3 目录过滤与分类规则

为了防止记录空目录并确保选择正确的模板,我们在目录发现过程中执行以下规则:

  • 非代码过滤:为了防止记录空目录,任何既不包含源代码文件也不包含带有代码的子目录的目录都将被排除。由于自顶向下的遍历无法知道更深层子目录是否包含代码,因此在 Phase A 中完整树映射完成后,剪枝以 自底向上的后处理遍历 的方式执行。
    • 源代码文件:定义为包含可执行代码、模式和契约的文件(例如 .c、.cc、.cpp、.cxx、.h、.hh、.hpp、.rs、.go、.zig、.lean、.f、.f90、.f95、.f03、.f08、.hs、.java、.kt、.scala、.cs、.fs、.vb、.py、.rb、.php、.lua、.sh、.bash、.ps1、.psm1、.psd1、.r、.R、.ex、.exs、.ts、.tsx、.js、.jsx、.mjs、.cjs、.swift、.m、.dart、.sql、.proto、.graphql、.gql、.thrift、.prisma、.tf、.hcl、.cue)。排除构建清单、锁文件、测试夹具、文档和通用数据转储。
  • 测试目录排除:在剪枝过程中,任何仅包含测试代码的目录(例如名为 tests、testing、testdata 的文件夹,或仅包含匹配 *_test.* 或 *Test.* 的文件)都会从文档中排除。
  • 测试文件过滤:在同时包含生产文件和测试文件的混合包目录中,探索者侦察员(explorer scout)会过滤掉测试文件,并在上下文扫描期间忽略其公共符号,以防止测试夹具污染已记录的公共接口。
  • 自定义排除:发现循环支持自定义忽略模式。默认情况下,它忽略隐藏/系统目录(.git、.jj、.gemini、node_modules)。此外,它读取本地 .egmignore 文件(如果存在),其中包含用于排除自定义文件夹的 glob 模式(例如 *testdata*、*mocks*、third_party)。
  • 目录分类:
    • 仓库根(Blueprint / Hay):bootstrap 执行的目标根文件夹始终被分类为仓库根,即使它包含直接的源代码文件。它使用“仓库根 README 模板”进行记录(对根文件夹中的文件使用可选的本地接口部分)。
    • 组件包(Peanut):任何包含直接源代码文件的非根目录。如果它还包含带有代码契约的子子目录,其 README 的 Interface 部分将包含指向子子目录契约的相对链接。
    • 仓库蓝图(Hay):任何不包含直接源代码文件,但包含带有代码契约的子目录的非根目录(无论是否存在 BUILD 文件)。

2.4 文档模板

📄 组件包(Peanuts)README 模板

用于包含直接源代码文件的文件夹。聚焦于本地模块契约。

# [Component Name]

## Overview
[Prose overview of the component's architectural role and goals]

## Interface
- [Public classes, functions, and symbols]
- [Subdirectories list and links to their contracts]

## Invariants
- [State and call invariants that must be preserved by developers/agents]

## Side Effects
- [State mutations, network calls, disk access, locks, or external side effects]

## Verification
- Build: `build //[package_path]...`
- Test: `test //[package_path]...`

📄 仓库根(Blueprint / Hay)README 模板

用于协调子子树的根目录节点。

# [Repository Name] Blueprint

## System Overview
[High-altitude architectural overview of this subsystem]

[Optional section if the root directory contains direct source files]
## Local Interface & Invariants
- [Direct symbols, invariants, and side effects of files in the root folder]

## Subdirectories & System Boundaries
- [Subdirectory Name]: [Link to child README.md] - [Summary of child contract/role]

## Global Invariants
- [System-wide constraints that cross component boundaries]

## Global Side Effects
- [Shared resources, databases, or external integrations affected by this subsystem]

## System Verification
- Run: `test //[system_path]...`

📄 中间蓝图 README 模板

用于位于根目录与包叶子之间的中间非代码目录(适用于被分类为仓库蓝图但不是执行根的目录)。

# [Directory Name]

## Overview
[Factual overview of the subdirectories and systems grouped under this directory path]

## Subdirectories & Boundaries
- [Subdirectory Name]: [Link to child README.md] - [Summary of child contract/role]

注意:所有 Hay 模板中的子目录索引必须使用相对路径(例如 ./subdir/README.md),以保持本地渲染兼容性。

2.5 执行流水线

阶段 A:增量目录范围确定与计划定义

  1. 增量 BFS 发现:Root Orchestrator 使用目录队列和原生 list_dir 工具调用逐层(BFS)映射目标树,保留中间文件夹节点。遍历过程中忽略符号链接以防止无限递归和重复映射。
  2. 安全门(Safety Gate):在 BFS 循环中,如果已发现目录的累计总数超过 15,Root Orchestrator 将立即暂停发现遍历,并调用 ask_question 工具警告用户执行范围过大,在继续进一步映射或启动 worker 之前需要确认。
  3. 自底向上后剪枝遍历:一旦映射遍历完成(并获得批准),Root Orchestrator 将从底向上(从叶子到根)遍历已映射的树。它根据过滤规则过滤掉隐藏目录、系统目录、构建输出目录、纯测试目录和非代码目录。
  4. 剪枝树确定后,Root Orchestrator 计算最大深度。
  5. 执行策略:
    • 顺序(大小 <= 5):Root Orchestrator 在单线程中顺序执行自底向上的文档记录。
    • 并行(大小 > 5):Root Orchestrator 将发现映射划分为独立的子树分支。
      • 自适应深度分区算法:
        1. 设置 depth = 1。
        2. 从发现映射中提取位于当前 depth 的目录节点。
        3. 如果 depth 处的节点数在 3 到 5 之间:将这些节点作为子树分区根返回。
        4. 如果 depth 处的节点数 < 3:递增 depth,重复步骤 2。
        5. 如果 depth 处的节点数 > 5:将最大的分支(按嵌套文件夹总数衡量)分组为 3-4 个独立分区,将剩余的小分支合并为单个后备分区子树,并返回这些分区根边界。
        6. 后备方案:如果达到 depth 限制 3 且计数仍然 < 3,则返回根的直接子节点(或回退到顺序执行)。
      • 它为每个分区子树生成一个并行 worker(Sub-Orchestrator),将参数 is_worker: true 和 sub_tree_root: <path> 传递给 self 子代理调用。
    • 批准后无限生成:Root Orchestrator 移除人为的并发限制。如果目录数量较大(> 5),它会请求用户批准生成所需数量的 Sub-Orchestrator,然后并行生成全部 Sub-Orchestrator。
  6. 条件分支控制:egm-bootstrap 技能配置(SKILL.md)在启动时检查这些参数:
    • 如果 is_worker 为 false/未设置:执行 Root Orchestrator 角色(运行 BFS 映射、安全门、生成 worker、编译最终 blueprint README,并执行最终的正确性检查)。
    • 如果 is_worker 为 true:跳过阶段 A,执行 Sub-Orchestrator 角色(自底向上处理指定的 sub_tree_root 子树,生成探索者(explorers),直接写入/修改文件,并使用 mdformat 格式化)。

阶段 B:自底向上引导

  1. 在并行策略下,Root Orchestrator 会生成并行的 bootstrap-orchestrator 实例作为子编排器,并为每个实例传入其目标子树。
  2. 每个子编排器以后序顺序处理其子树(先处理最深的叶子节点):
    • 修正与修改策略:在生成文档之前,子编排器会检查当前活动文件夹中是否已存在 README.md。如果 README.md 已存在,则不会完全覆盖它。相反,它会读取现有内容,生成 goldfish-explorer 侦察器来编制真实的代码契约,并使用 replace_file_content(或 write_to_file)修正和更新现有 README,使其符合 DNC 规范,同时保留开发者注释和描述。
      • 侦察器扫描要求:无论 README 是否存在,子编排器始终会生成 goldfish-explorer 侦察器来扫描目录中的源代码,并编制真实的代码符号边界。
      • 遗留符号提取提示:为了解析预先存在的手写 README 文件,子编排器使用以下提取提示调用推理 LLM:> "分析以下非结构化的 README.md 内容。提取所有公共符号名称、类、接口、不变量和副作用。请严格按以下模式将你的响应格式化为 JSON 对象:{ \"interface\": string[], \"invariants\": string[], \"side_effects\": string[] }."
    • 验证命令目标查找:在生成 ## Verification 部分时,子编排器会检查当前活动文件夹中是否存在 BUILD 文件。如果存在:
      • 它会检查是否存在测试文件(匹配 *_test.* 或 *Test.*)。如果存在测试文件,则写入 Test: 命令;否则省略测试命令。
      • 如果 BUILD 文件中的目标名称不明确或与文件夹名称不匹配,则回退到构建整个包的通配目标:build //[package_path]:all。
      • 如果本地没有 BUILD 文件:它会扫描最近的祖先 BUILD 文件,以定位其 srcs 属性引用了当前活动子目录中文件的目标(例如通过直接路径列表或 glob)。如果找到匹配的目标,则引用该目标(例如 build //[ancestor_path]:my_target)。如果有多个目标匹配或未找到匹配项,则回退到包通配目标:build //[ancestor_path]:all。如果未找到任何祖先包,则省略验证命令。
      • Starlark 解析回退:如果祖先 BUILD 文件包含无法通过文件读取解析的复杂 Starlark 宏或依赖项,子编排器会回退到引用祖先包的通配 :all 目标,或省略该目标。
    • 侦察器定义与生成:如果当前会话中尚未定义只读的 goldfish-explorer 子代理类型,子编排器会使用 define_subagent 动态声明该类型。
      • 子代理定义参数:
        • TypeName:goldfish-explorer
        • Role:goldfish-explorer
        • enable_write_tools:false
        • enable_subagent_tools:false
        • SystemPrompt:如第 2.1 节中所定义。
      • 然后,它会为当前活动目录按顺序生成侦察器。
    • 子目录容错:如果子目录未能生成文档(例如侦察器超时或工具错误),子编排器会记录警告,在父目录索引中插入占位链接(例如 - [Subdirectory Name]: [Link to child README.md] - (Details pending/documentation failed)),并继续生成文档而不是中止。
    • 根据分类(Component Peanut 或 Blueprint Hay;非执行根的 Blueprint Hay 节点使用 "Intermediate Blueprint template")生成或修正 README.md。
    • Markdown 格式化:在写入或修正 README.md 后,子编排器立即通过 run_command 执行 markdown formatter (e.g. prettier or markdownlint),以确保 Markdown 格式正确。
  3. 当所有并行工作实例完成后:
    • Root 容错:如果某个并行工作实例失败或超时,Root Orchestrator 会记录警告,在根 Blueprint 的子目录索引中插入占位警告链接(例如 [Subtree Root] (Documentation failed / Subagent execution timeout)),并完成其余编译工作。
    • 中间目录文档:Root Orchestrator 会识别位于根与各分区子树根之间的所有中间目录。它按自底向上的顺序依次处理这些中间目录,使用工作实例返回的编译摘要生成 Intermediate Blueprint README,并使用 mdformat 进行格式化。
    • Root Orchestrator 会检查根目录本身是否包含任何直接源文件。如果存在,它会为根目录生成一个 goldfish-explorer 侦察器,以提取本地符号和不变量,并将它们追加到根 README 的 ## Local Interface & Invariants 部分之下。
    • 它编译最终的根 README.md(Blueprint),写入文件,并使用 mdformat 格式化。
    • 最终正确性验证:Root Orchestrator 会对 subtree_index 中所有创建和修改的 README 执行最终验证,以确认其符合 EGM 规范(Interface、Invariants、Side Effects)、Markdown 格式正确、相对链接有效(明确验证引用的子 README 或 SKILL 文件确实存在),以及验证目标有效,然后才结束工作。
    • 可选漂移审查:Root Orchestrator 调用 ask_question,提议对生成的更新运行 egm-drift-report 技能,以验证与代码库的一致性。
    • 成功终止。

2.6 处理工具

  • 目录发现(Directory Discovery):使用原生 list_dir 调用以 BFS 循环遍历 (过滤掉 .git、.jj、.gemini、third_party、node_modules)。 在发现阶段保留 BUILD 文件,以提取构建/测试 目标,用于验证模板部分。
  • Markdown 格式化:使用 run_command 执行 markdown formatter (e.g. prettier or markdownlint), 对所有新建或修改的 README 进行格式化。

2.7 增量哨兵块 Upsert 架构

为了安全地在已包含人工编写运维文档(例如仓库运行手册或值班元数据)的目录上运行 egm-bootstrap,该技能强制执行幂等哨兵块引导(Idempotent Sentinel-Block Bootstrapping):

  1. 哨兵边界标记(Sentinel Boundary Markers):由子编排器或叶子工作器生成的每个 DNC 块都包裹在显式 HTML 哨兵标记中:

    • 起始哨兵: <!-- EGM_BLUEPRINT_START: AUTO-GENERATED BY egm-bootstrap. PUT HUMAN NOTES ABOVE THIS LINE -->
    • 结束哨兵: <!-- EGM_BLUEPRINT_END -->
  2. 三态 Upsert 状态机:在写入或更新 d/README.md 时,工作器会执行:

flowchart TD
    A[Read d/README.md] --> B{File Exists?}
    B -- No --> C["Create file with sentinel-wrapped block"]
    B -- Yes --> D{"Contains <!-- EGM_BLUEPRINT_START -->?"}
    D -- Yes --> E["Replace substring [START, END] with new block"]
    D -- No --> F{"Contains '## Subdirectories & System Boundaries'?"}
    F -- Yes (Legacy DNC) --> G["Slice [0, HEADER_INDEX] as Human Preamble + Append Sentinel Block"]
    F -- No (Pure Human) --> H["Retain 100% Human Preamble + Append '\n\n' + Sentinel Block"]
    C --> I[Run markdown formatter on README.md]
    E --> I
    G --> I
    H --> I

3. Alternatives Considered

3.1 单代理扁平爬虫

我们曾考虑使用单个代理顺序遍历目录树、边走边读取文件并更新 README,而不是采用递归式 swarm 方案。

  • 拒绝原因:
    • 上下文窗口限制:顺序遍历大型目录树会积累过多的 token 历史,导致上下文截断和精度损失。
    • 执行时间:对于深层或宽泛的目录树,顺序执行速度较慢。
    • 并行性:它无法利用并行执行。swarm 模型允许子代理并行运行,从而缩短执行时间。

3.2 直接复用 growing-peanuts-and-hay 技能

我们调查了直接使用现有 growing-peanuts-and-hay 技能(一个内部原型前身)的可行性。

  • 拒绝原因:
    • 该技能是团队特定的、顺序执行的,并且硬编码了特定的语言约定。
    • EGM 需要一个通用的、与语言无关的工具(支持 C++、Python、Java 等),并且能够并行扩展到大型仓库。
    • 我们选择编写 egm-bootstrap,将其 DNC 模板和自底向上逻辑整合为一个通用技能,通过 self 工作器支持并行扩展。

4. Detailed Implementation

所有更改都将放在开源仓库结构中:

4.1 实现文件

  1. skills/egm-bootstrap/SKILL.md

    • 设计理由:定义 EGM 引导过程的工作流步骤。
    • YAML Frontmatter 输入模式:

      name: egm-bootstrap
      description: Bootstrap directory README.md files across a repository subtree.
      inputs:
        path:
          type: string
          description: The target root directory path to bootstrap.
          required: true
        is_worker:
          type: boolean
          description: Internal parameter. True if executing as a worker Sub-Orchestrator.
          default: false
        sub_tree_root:
          type: string
          description: Internal parameter. The root path of the assigned subtree partition.
          required: false
      
    • SKILL.md 算法流程:

      1. 启动检查:读取 is_worker 参数。如果为 true,则跳转到步骤 6(工作器流程)。
      2. BFS 范围界定:以队列循环方式运行 list_dir 来映射目录树,忽略符号链接和 .egmignore glob 模式。
      3. 警告门控:如果发现的数量 > 15,则调用 ask_question 并等待用户批准。
      4. 分区:如果数量 <= 5,则顺序记录。否则,运行自适应深度分区,将目录树划分为平衡的子树。
      5. 生成:在用户批准后并行调用 self 子代理,传递 is_worker: true 和 sub_tree_root。跳转到步骤 9。
      6. 工作器流程:在启动时动态声明只读的 goldfish-explorer 子代理类型。以自底向上(后序)方式遍历分配的子树。
      7. Explorer 扫描与格式化:对于每个文件夹,检查更正与修改策略。读取现有 README,生成 scout,使用 replace_file_content 或 write_to_file 更正/更新文件,使其符合 DNC 规范,并使用 markdown 格式化工具进行格式化。
      8. 报告:编译子树索引,并将 JSON(工作器接口模式)返回给 Root Orchestrator。
      9. 编译与最终验证:Root Orchestrator 编译子元数据(从工作器超时中恢复),如果根文件夹中存在文件,则对其运行 scout,写入 Blueprint README,使用 markdown 格式化工具进行格式化,对所有修改过的 README 执行最终正确性检查,可选地提示运行 Drift Report,然后退出。
  2. skills/egm-bootstrap/TEST.md

    • 原理说明:列出该 bootstrap 技能的验证与测试场景。
  3. skills/egm-bootstrap/test_scenarios.yaml

    • 原理说明:评估 bootstrap 场景(小目录树顺序执行、并行子树分区和安全门)的自动化集成测试。
  4. agents/bootstrap_orchestrator.md

    • 原理说明:为 bootstrap-orchestrator 角色定义系统提示词与指令。

5. 非功能性需求

5.1 安全与隐私

  • 以源码为中心:范围界定仅读取源码文件。它必须忽略包含敏感数据的隐藏目录(例如本地凭据、.git/ 历史记录)。

5.2 性能与 Token 开销

  • Swarm 并发:应使用 Workspace=inherit 调用子代理,以便并行运行。
    • Workspace=inherit:在 Antigravity 框架中,使用 Workspace=inherit 启动子代理会指示系统直接将父级的工作区目录共享给子代理,而不是检出新的隔离分支。这是并行读操作所必需的,因为它避免了克隆开销,并确保所有子代理看到相同的本地文件系统状态。
  • VCS 隔离:Sub-Orchestrator 工作代理与探索代理不得执行任何版本控制命令(例如 git add、git commit)。所有文件系统更改都在本地写入。对生成的 README.md 文件的追踪与提交,推迟到父级 EGM 会话框架,或在技能完成后由用户处理,从而避免并发的 VCS 数据库锁。
  • 临时文件隔离:共享工作区的并行工作代理必须将全部状态跟踪、检查点记录和日志写入独立、按工作代理区分的目录中,使用其唯一的 conversationId,位于应用程序数据目录下(例如 <appDataDir>/brain/<conversation_id>/scratch/),或位于其他主机上的私有 mktemp -d 目录中。它们不得在源码仓库工作区内写入任何临时文件,保持源码树不被修改,并且绝不得使用固定的共享路径。如果这两种目录都不可用,则跳过这些文件。
  • Antigravity 框架:Antigravity 是用于自主编码助手的代理 SDK 生态系统和运行时框架。
  • Token 优化:Goldfish 侦察代理是只读、临时性的,且每次只读取单个目录,从而防止编排器上下文窗口耗尽。
    • 子代理隔离 vs. 直接文件读取:将文件级读取卸载给专门的 goldfish-explorer 侦察代理,可使 Sub-Orchestrator 的上下文窗口保持紧凑,因为它只接收结构化 JSON 摘要,而不是原始代码文件。这会以子代理启动延迟为代价来降低 Token 开销。
  • 警告门:如果目录数超过 15,则通过 ask_question 提示用户,以防止在大型仓库上无限执行和浪费 Token。

5.3 风险与缓解措施

  • LLM 速率限制:对大型仓库树进行划分可能触发过多并发 API 调用。缓解方式是在生成无限制的并行工作代理之前,要求用户明确批准。
  • VCS 数据库锁:通过禁止工作代理和侦察代理执行任何 VCS 追踪/提交命令(jj/g4),并将操作推迟到 EGM 会话完成,从而缓解该风险。
  • 共享工作区上的状态冲突:通过将执行检查点存储在 <appDataDir> 下按工作代理区分的临时目录中(或其他主机上的私有 mktemp -d 目录),从而避免修改共享工作区。如果两者都不可用,工作代理会跳过这些文件。
  • 工作代理失败导致残留部分文件:作为增量进度功能处理。更正与修改策略会保留部分进度,并在后续运行中修正已有文件,使开发者可以无数据丢失地恢复执行。
  • 文档漂移:引导生成的 README 会随时间与代码库逐渐偏离。这不在引导工具的范围内,但应在未来的 EGM 插件中,通过定期运行 EGM 漂移检查工具(例如 egm-drift-report)来解决。
  • 幻觉风险:对不变量和副作用的自动化文档描述可能受到 LLM 幻觉的影响。生成的 README 文件包含标准验证命令(构建/测试目标),因此用户可以构建并执行包代码来验证功能。

6. 验证与测试计划

6.1 静态分析与技能验证

验证确保技能定义、frontmatter、标题层级和哨兵块符合 EGM 标准。

6.2 集成测试与场景

skills/egm-bootstrap/test_scenarios.yaml 中的自动化集成测试套件评估以下内容:

  • bootstrap_small_tree:验证目录数 <= 5 的树的顺序执行,确保其生成符合规范的 Peanut 和 Hay README,对其进行格式化,并运行最终的正确性检查。
  • bootstrap_parallel_tree:验证用户批准后无限制地并行生成工作代理、子上下文传播、直接文件系统写入/修改、格式化以及最终正确性验证。
  • bootstrap_safety_gate:验证当映射的目录计数超过 15 时触发警告门,暂停遍历并提示用户。
  • bootstrap_incremental_sentinel_upsert:验证对包含人工操作说明的现有 README.md 运行 egm-bootstrap 时,会保留哨兵块上方的所有人工文本,同时更新哨兵块下方的 DNC 契约。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model