learn-harness-engineering 第 06 讲配套代码解析：把初始化做成独立阶段——init 脚本、前置条件检查与初始化输出清单

learn-harness-engineering 第 06 讲配套代码解析把初始化做成独立阶段——init 脚本、前置条件检查与初始化输出清单【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering本讲配套代码位于 docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/对应主课文档 docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md并配套实战项目 project-03多会话连续性。在 harness 工程中初始化必须是独立阶段这一结论最终要落地为一组可执行、可检查、可交接的代码产物。本篇文章围绕第 06 讲代码文件夹中的三类真实示例——前置条件检查脚本init-check.ts、初始化脚本init.sh、初始化输出清单initializer-output-checklist.md——逐行讲解它们如何把初始化从一个抽象原则变成 agent 每次开工前都能运行的工程设施并对照仓库中 project-03 的完整实现给出可直接复用的落地模板。一、这个代码文件夹放什么初始化阶段的四类交付物code/index.md 明确规定了该文件夹的用途存放初始化相关的四类示例它们是初始化作为独立阶段在仓库里留下的具体形态示例类别对应文件解决的问题初始化器的输出结果initializer outputsinitializer-output-checklist.md初始化完成后如何验收产出是否达标初始化脚本init scriptsinit.sh如何让装依赖、建环境变成一条可重复执行的命令进度文件progress files见 projects/project-03/solution/session-handoff.md会话之间如何交接进度让新会话能看进度、能接手首次运行的脚手架first-run scaffoldinginit-check.ts如何程序化地检查首次运行前的前置条件是否齐备主课文档把初始化阶段定义为agent 生命周期中的第一个阶段只建立后续实现所需的执行前提不做功能开发。上面四类文件正是把这一阶段物化的最小工具箱——其中init.sh负责环境可运行init-check.ts负责把环境可运行变成可量化的检查项initializer-output-checklist.md负责把初始化结果变成可验收清单进度文件则承接了能看进度、能接手下一步两个 bootstrap 契约条件。二、首次运行脚手架init-check.ts 如何程序化检查前置条件init-check.ts 是仓库中针对初始化阶段提供的最有代表性的脚手架示例。它用纯 TypeScript仅依赖 Node 内置模块node:fs、node:path、node:child_process实现了两件事对当前目录做 8 项初始化前置检查以及模拟有初始化阶段 / 无初始化阶段两种工作流的差异。2.1 检查项的数据结构脚本的核心抽象是CheckItem接口源码第 24-29 行interface CheckItem { name: string; // 检查项名称如 Node.js version 18 category: string; // 分类Runtime / Config / Dependencies / Toolchain / Structure / Version Control check: () { pass: boolean; detail: string }; impactIfMissing: string; // 该前置条件缺失时对后续开发的真实影响 }每个检查项不只返回过/不过还附带impactIfMissing说明——这正是 harness 设计的要点让 agent 在开始干活前就意识到缺了这个后面会怎样而不是等到运行时才被隐式地绊倒。2.2 八项前置检查全解createChecks(targetDir)源码第 43-164 行返回 8 个检查项按类别可归纳为四组运行时RuntimeNode.js version 18读取process.version如v20.11.0解析主版本号并断言major 18。缺失影响TypeScript 新特性与内置 API 不可用。TypeScript available执行npx tsc --version带 10 秒超时验证工具链可达。缺失影响无法编译.ts文件。配置Configpackage.json exists项目元数据与脚本入口缺失时无法安装依赖或运行脚本。tsconfig.json exists缺失时编译器退回默认配置可能不符合项目需求。依赖DependenciesDependencies installed (node_modules)直接检查node_modules目录是否存在缺失影响直白——所有 import 在运行时都会失败。结构StructureSource directory exists在src/lib/app中查找任一源码目录缺失意味着agent 找不到要改的源文件。Test directory exists在test/tests/__tests__/spec中查找测试目录缺失意味着agent 找不到也跑不了既有测试。版本控制Version ControlGit repository initialized检查.git目录缺失意味着无回滚能力、无变更历史。注意这几项检查与主课bootstrap 契约四条件能启动、能测试、能看进度、能接手下一步是逐条对应的运行时可运行性、结构决定可接手性、测试目录决定可测试性、git 决定可交接性。初始化阶段的产出不是业务代码而是让这 8 项全部 PASS 的基础设施。2.3 核心亮点有/无初始化阶段的对比模拟脚本最有价值的部分是simulateWithoutInit()与simulateWithInit()源码第 179-223 行构成的对照实验无初始化阶段agent 跳过前置检查直接开工随后每次撞到一个缺失项才处理一个脚本为每次事后发现模拟200ms的时间损耗且failures 0时工作才算成功。有初始化阶段agent 先跑完全部 8 项检查所有问题在动手前暴露只要存在任何 FAIL就不开始正式工作workAttempted: failures 0因此浪费时间为0ms。run()源码第 233-294 行最终输出一张表格左边是 8 项检查的逐项 PASS/FAIL 明细右边是两列对比表No Init PhasevsWith Init Phase对比指标包括是否前置检查了前提条件是否在存在问题时仍尝试开工后期才发现问题所浪费的时间工作是否成功。运行方式源码头部注释npx tsx docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts这个脚本的工程价值在于它把主课反复强调的初始化是投资而非成本变成了可在任意项目根目录直接运行、直接看到两种工作流差异的可执行证据。任何新项目接入 harness 时第一步就可以把这份检查表按项目实际裁剪后纳入初始化阶段。三、初始化脚本从最小示例到完整模板3.1 第 06 讲自带的 init.shinit.sh 是极简的初始化脚本模板#!/usr/bin/env bash set -euo pipefail echo [init] installing dependencies npm install echo [init] starting the docs site is optional echo [init] use npm run docs:dev for course docs echo [init] project-specific startup would go here三个细节值得注意set -euo pipefail任何一步失败立即退出-e、未定义变量报错-u、管道中任一命令失败即整体失败-o pipefail。初始化脚本必须要么全部成功要么立即失败绝不允许带着半截环境继续往下走——这与主课基础不牢、墙就白砌的比喻一致。每一步都有[init]前缀的进度输出让 agent和人类能逐段确认初始化进展这正是可观测的初始化的雏形。末尾保留project-specific startup would go here占位模板只负责通用步骤项目特有步骤由各项目补充——呼应主课的热启动策略把通用初始化步骤预置进模板只留项目特有问题。3.2 仓库中的完整工程级模板project-03/solution/init.sh第 06 讲配套实战项目 project-03多会话连续性的 solution 中init.sh 给出了更完整的工程级写法#!/usr/bin/env bash # init.sh -- Verify the project builds cleanly before starting work. # Run this after cloning or when resuming work. set -euo pipefail echo Project 03 Init echo [1/3] Installing dependencies... npm install echo [2/3] Running type checks... npm run check echo [3/3] Building project... npm run build echo Init complete. All checks passed. echo Run npm run dev to launch the application.对比可见工程化的三点演进头注释写明何时运行Run this after cloning or when resuming work——明确初始化脚本的两个触发时机克隆后、恢复工作时这正好对应主课每次 agent 会话开始前先初始化的要求。三步递进验证装依赖 → 类型检查 → 构建每一步都以前一步成功为前提最终以npm run build全量验证收尾等价于 bootstrap 契约中的完整验证命令。带序号的阶段输出与结束横幅[1/3]、[2/3]、[3/3]让长耗时初始化可被逐段观察结束横幅Init complete. All checks passed.给出明确的阶段完成信号最后提示下一步npm run dev。在 project-03 的 AGENTS.md 中这条链路被固化成了 agent 的启动规则读 AGENTS.md → 读docs/ARCHITECTURE.md→ 读docs/PRODUCT.md→运行npm install npm run check验证项目可构建→ 读feature_list.json查看功能状态。也就是说初始化脚本不是孤立存在的它被嵌入了整个开工仪式这正是初始化成为独立阶段在真实项目中的样子。四、初始化输出清单如何验收一次初始化initializer-output-checklist.md 以 5 个提问的形式给出了初始化器输出结果的验收标准# Initializer Output Checklist - Is there a canonical startup command? 有规范启动命令吗 - Is there a canonical verification command? 有规范验证命令吗 - Is there a first progress artifact? 有第一个进度产物吗 - Is there a stable first commit? 有稳定的第一个提交吗 - Is there a visible feature surface for later runs? 后续运行有可见的功能面吗这 5 项与主课的初始化验收清单make setup从零成功、make test至少一个测试通过、新 agent 只看仓库就能回答怎么跑/怎么测、任务分解文件至少 3 个任务、全部提交到 git是一体两面主课清单侧重行为验证本清单侧重产物验证。两者结合就是初始化完成的完整定义检查角度验收点对应的 bootstrap 契约条件启动规范启动命令存在且可执行能启动验证规范验证命令存在且可执行能测试进度存在第一个进度产物进度文件、任务清单能看进度交接存在稳定的第一个 git 提交checkpoint能接手下一步功能面后续会话能看到待做功能列表能接手下一步其中第一个进度产物和稳定的第一个提交是很容易被忽视的两项主课指出初始化阶段产出的不是代码而是基础设施而基础设施是否可交接恰恰取决于有没有把进度显式落盘进度产物并用 git 固化checkpoint。仓库中 project-03 的 session-handoff.md 就是进度产物的实例它记录了上次会话完成了什么、剩余什么、做了哪些决策、改动了哪些文件、下一步做什么——新会话读它即可在几分钟内恢复上下文。而 feature_list.json 则是可见的功能面每个功能的not-started / pass状态让后续会话一眼看清还能做什么。五、把示例串起来一个完整的初始化阶段工作流综合上述四类示例一个可落地的初始化阶段应该像这样编排1. 运行 init-check.ts —— 程序化确认 8 项前置条件运行时/配置/依赖/结构/git 2. 运行 init.sh —— 装依赖、跑类型检查、构建全绿才继续 3. 写 initializer-output-checklist 中 5 项产物 ├─ 规范启动命令 规范验证命令写入 bootstrap 契约文档 ├─ 第一个进度产物session-handoff.md / 任务分解清单 ├─ 稳定的第一个 git 提交checkpoint └─ 可见的功能面feature_list.json 或任务列表 4. 用主课验收清单逐项打勾 —— 能启动、能测试、能看进度、能接手下一步 5. 结束初始化阶段从 checkpoint 开始功能实现主课文档给出的实证是混合方式下第二会话需要约 20 分钟重建项目认知独立初始化后重建时间不足 3 分钟整个项目周期内混合方式的总重建时间比独立初始化多约 60%初始化多投入的时间在后续 3-4 个会话中即可完全收回。本代码文件夹提供的正是支撑这一结论的工程手段——把初始化从口头叮嘱变成npx tsx init-check.ts ./init.sh 对照清单打勾的可执行仪式。六、实践建议为新项目复制本文件夹的骨架先跑 init-check.ts 看哪些前置项 FAIL再按 project-03 的 init.sh 模式把修复步骤固化成脚本最后用 initializer-output-checklist.md 验收。把检查项与 bootstrap 契约四条件对齐每新增一个前置检查都应能回答它支撑的是能启动、能测试、能看进度、能接手下一步中的哪一条。进度产物必须显式落盘仿照 session-handoff.md 的结构维护进度文件并在 AGENTS.md 中规定恢复工作时先读它、结束时更新它参见 AGENTS.md 的 Session Handoff 一节。热启动优先把通用初始化步骤预置进项目模板每个新项目只保留 init.sh 中project-specific startup那类占位工作。延伸阅读主课全文docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md含初始化生命周期图、bootstrap 契约文档模板、任务分解模板与初始化验收清单实战项目完整实现projects/project-03/solution/多会话连续性init.sh、session-handoff.md、feature_list.json、AGENTS.md 启动规则中文版对照docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考