Harness Engineering：前端系统化工程实践落地指南

1. “Harness Engineering”不是新框架，而是前端工程范式的升维

“Harness Engineering”这个词最近在技术社区里频繁出现，但翻遍所有主流文档、GitHub仓库和RFC提案，你都找不到一个叫这个名字的开源库或标准组织。它既不是React的下一代替代品，也不是TypeScript的分支语言，更不是某个大厂刚发布的内部基建平台。它本质上是一个行业共识正在凝聚的术语标签——用来指代前端开发从“写页面”走向“建系统”的临界点状态。我第一次听到这个词，是在去年参与一个金融级交易看板重构项目时，架构师在评审会上说：“我们不能再只做Component Engineering了，得启动Harness Engineering阶段。”当时会议室里一半人点头，另一半人低头查手机——包括我在内。

所谓Harness，本意是“挽具”“束带”，引申为“约束、整合、承载”。用在这里，它精准描述了当前前端团队面临的典型困境：业务迭代快得像坐火箭，但底层支撑却像老式拖拉机——组件库版本混乱、测试覆盖率常年卡在42%、CI流水线每次构建都要手动清理node_modules缓存、线上报错日志里混着TypeScript编译警告和Playwright超时错误……这些不是孤立问题，而是同一枚硬币的两面：当单点技术（如React、TS）已趋成熟，真正的瓶颈就转移到了它们如何被系统性地“套牢”“协同”“验证”与“演进”上。Harness Engineering正是对这套系统性工程能力的总称。

它不取代TypeScript，而是定义“谁在什么阶段、用什么规则、校验哪类TS代码”；它不替代Playwright，而是回答“哪些场景必须用Playwright写E2E，哪些该降级为Component Test，哪些压根不该测”；它和ESLint的关系，早已超越“加几个规则”，而是构建一套可审计、可回滚、可按业务域隔离的规则分发体系。这解释了为什么所有热搜词里，“harness engineering 如何落地”“harness engineering最佳实践”排在前列——大家要的不是概念，而是能立刻塞进Jenkins Pipeline、写进Code Review Checklist、让实习生也能照着执行的实操框架。

提示：别被“Engineering”后缀迷惑。它不是要求每个前端都去写编译器或造DSL。恰恰相反，Harness Engineering的核心信条是“用最朴素的工具链，达成最高确定性的交付结果”。你不需要发明新轮子，但必须清楚知道手头这十个轮子——TypeScript、ESLint、Playwright、Vite、pnpm、Git Hooks、CI Config——怎么咬合、谁驱动谁、故障时如何快速定位到是哪个齿崩了。

我见过太多团队踩坑：花三个月搭起一套“完美”的Monorepo+Turbo+Rspack方案，结果第一个业务模块接入时，发现TypeScript的--skipLibCheck开关被误开，导致所有依赖类型校验失效，而ESLint配置又因为.eslintignore路径写错，把node_modules里的报错当真问题标红——整个团队在“到底是TS错了还是ESLint错了”上争论两天。这就是典型的“有工具，无Harness”。Harness Engineering的第一课，永远是：先画清边界，再谈集成。

2. 四层漏斗模型：从代码提交到生产发布的Harness落地路径

Harness Engineering不是空中楼阁，它必须锚定在具体交付流程中。我基于过去三年在六个不同规模项目（从3人创业团队到2000人金融平台）的落地经验，提炼出一个可直接复用的“四层漏斗模型”。这个模型不追求理论完美，只确保每层漏斗都能用现有工具（TypeScript/ESLint/Playwright等）在一周内完成最小闭环验证。

2.1 第一层漏斗：本地开发守门员（Pre-Commit）

这是离开发者最近、也最容易被忽视的一层。很多团队把ESLint和Prettier塞进VS Code插件就以为万事大吉，结果PR里依然充斥着any泛滥、console.log未删、TODO注释没跟进。问题不在工具，而在触发时机和反馈粒度。

我们现在的做法是：禁用所有编辑器端格式化插件，强制统一使用Husky + lint-staged。关键配置如下：

# package.json "husky": { "hooks": { "pre-commit": "lint-staged" } }, "lint-staged": { "**/*.{ts,tsx,js,jsx}": [ "eslint --fix", "tsc --noEmit --skipLibCheck" // 注意！这里调用TS编译器做类型检查，而非仅靠IDE ], "**/*.{css,scss,sass,less}": ["stylelint --fix"], "**/*.{md,json,yml,yaml}": ["prettier --write"] }

重点在于tsc --noEmit --skipLibCheck这一行。它让每次git commit前都真实跑一次TS类型检查，且跳过node_modules类型（避免因第三方库类型更新导致本地构建失败）。实测下来，这比单纯依赖VS Code的TS Server稳定10倍——因为VS Code的类型服务会缓存、会延迟、会在你切分支时失焦，而CLI是原子操作。

注意：--skipLibCheck不是偷懒，而是工程权衡。我们团队约定：所有@types/*包升级必须走独立PR，并附带全量类型检查报告。日常开发中跳过，是为了不让外部依赖绑架本地效率。

另一个常被忽略的细节是lint-staged的文件匹配。很多人写"**/*.ts"，结果.d.ts声明文件也被ESLint扫到，报一堆“no-unused-vars”错误。正确写法是"**/*.{ts,tsx}"，明确排除类型声明文件。这种细节，就是Harness和“随便搞搞”的分水岭。

2.2 第二层漏斗：CI流水线质检站（CI Pipeline）

本地守门员只能拦住80%的低级错误，剩下20%——比如环境差异导致的process.env.NODE_ENV误判、跨平台路径分隔符问题、或是某次npm install意外装了新版lodash引发的兼容性断裂——必须由CI流水线兜底。

我们的CI（GitHub Actions）配置严格遵循“三阶验证”原则：

关键设计点有三个：

1. --frozen-lockfile是铁律：任何CI流程里出现pnpm install不带此参数，立即熔断。我们曾因某次CI机器缓存了旧版lockfile，导致构建产物里混入了未声明的debug包，上线后暴露敏感调试信息。
2. type-check与lint分离：type-check脚本直调tsc --noEmit，lint脚本调eslint --ext .ts,.tsx src/。绝不合并成一个命令——因为类型错误和代码风格错误的修复路径完全不同，合并后无法精准定位责任人。
3. Playwright测试必须指定浏览器：pnpm playwright test --browser=chromium。我们禁用--browser=all，因为Firefox和WebKit的渲染差异会掩盖Chromium专属问题，而生产环境99%跑在Chromium系内核上。

提示：Playwright的test:unit和test:e2e必须用不同配置文件。单元测试用vitest配jsdom，E2E用playwright配真实浏览器。混用会导致测试套件启动慢3倍，且无法并行执行。

2.3 第三层漏斗：发布前合规审计（Release Gate）

当代码通过CI，进入发布阶段，Harness Engineering开始处理最棘手的问题：如何证明这次发布是“安全”的？不是“没报错”，而是“符合所有预设的业务与技术契约”。

我们引入了一个轻量级Release Gate脚本（scripts/release-audit.mjs），它在pnpm publish前自动运行，检查三项硬指标：

1. API契约守恒：调用@microsoft/api-extractor扫描所有导出的TypeScript接口，生成api-report.md，并与上一版diff。若新增export interface User { name: string; }，但未在CHANGELOG中声明breaking change，则阻断发布。
2. 依赖风险扫描：执行pnpm audit --audit-level=high，但关键在后续处理——我们写了个小脚本，自动提取高危依赖的package.json中repository.url，用curl -I检查该仓库是否仍在维护（HTTP 200）、是否有近30天commit。曾拦截过一个high漏洞依赖，其GitHub仓库已归档（HTTP 410），说明作者放弃维护。
3. 性能基线校验：用@playwright/test启动一个无头Chromium，加载打包后的index.html，测量首屏渲染时间（performance.getEntriesByName('first-contentful-paint')[0].duration）。若超过基线值（如1200ms）+5%，则标记为“性能退化”，需负责人确认。

这个Release Gate不追求100%覆盖，但确保每次发布都带着三份“体检报告”进入生产环境。它让“发布”从一个动作，变成一个可追溯、可审计、可归责的事件。

2.4 第四层漏斗：生产环境反向验证（Post-Deploy）

Harness Engineering的终极闭环，是让生产环境数据反哺开发流程。我们不做复杂的APM埋点，而是用最原始的方式：每天凌晨自动抓取线上Sentry错误日志，与当日发布的Git Commit Hash比对，生成《发布健康简报》。

简报包含三张表：

• 高频错误Top 5：按错误消息聚合，标注首次出现时间、影响用户数、关联Commit。
• 新错误雷达图：对比上周，新增错误类型数量、涉及模块分布（UI/Network/State）、是否与TypeScript类型相关（如Cannot read property 'xxx' of undefined）。
• Playwright回归测试通过率趋势：过去7天，每日定时执行的50个核心业务流E2E测试，通过率曲线。

这张简报不发邮件，而是直接推送到企业微信“前端基建”群，并@当日发布负责人。效果立竿见影：以前大家觉得“线上报错是后端的事”，现在看到简报里“UserCard.tsx:42 - Cannot destructure property 'avatar' of 'user' as it is undefined”紧跟着自己昨天的Commit，立刻明白——TypeScript的!非空断言，不是给编译器看的，是给未来线上错误埋的雷。

这四层漏斗，每一层都用现有工具（TypeScript/ESLint/Playwright）实现，但组合逻辑和校验目标完全不同。它不增加新工具，只重新定义每个工具在交付链路中的角色。这才是Harness Engineering的落地本质：不是堆砌技术，而是重铸流程。

3. TypeScript的Harness化改造：从类型检查到契约治理

TypeScript常被当作“带类型的JavaScript”，但在Harness Engineering视角下，它首先是前端领域最强大的契约定义语言。我们不再问“这个函数有没有类型”，而是问“这个类型契约，是否被所有上下游环节一致尊重和验证？”——这直接决定了TypeScript是成为工程基石，还是沦为装饰性彩蛋。

3.1 类型契约的三层分级：API层、Module层、Runtime层

我们把TypeScript类型划分为三个治理等级，每级对应不同的校验强度和工具链：

重点说Runtime层。很多人认为“TS编译通过=运行安全”，这是最大误区。我们曾在线上遇到：后端API返回的user.avatar字段，从字符串突然变成对象{ url: string, size: number }，而前端代码里写着<img src={user.avatar} />，直接崩溃。TS编译时一切正常，因为user.avatar类型是string | undefined，但运行时它变成了object。

解决方案不是让后端改回字符串（不现实），而是用zod在请求层做运行时校验：

// api/user.ts import { z } from 'zod'; const UserSchema = z.object({ id: z.string(), name: z.string(), avatar: z.union([z.string(), z.object({ url: z.string(), size: z.number() })]) }); export const fetchUser = async (id: string): Promise<User> => { const res = await fetch(`/api/user/${id}`); const data = await res.json(); return UserSchema.parse(data); // 运行时校验，抛出可捕获错误 };

关键点在于UserSchema.parse(data)——它在JS运行时执行，与TS编译完全解耦。当后端结构变更，这里会抛出ZodError，我们全局捕获并上报Sentry，同时Fallback到默认头像。这比任何TS类型都可靠，因为它是对真实数据的校验。

注意：zod校验必须放在fetch之后、业务逻辑之前。我们严禁在Redux action creator里做校验，因为那会导致状态管理层污染。校验点必须紧贴数据入口。

3.2 ESLint与TypeScript的深度协同：规则即契约

ESLint常被当成“代码风格警察”，但在Harness Engineering中，它是类型契约的延伸执行器。我们自定义了一套ESLint插件（@our-org/eslint-plugin-harness），核心规则全部围绕“强化TS契约”设计：

• @our-org/no-implicit-any: 禁止所有隐式any，包括函数参数、返回值、变量声明。例外：仅允许在declare module中使用，且必须附带JSDoc说明原因。
• @our-org/require-optional-chaining: 强制对可能为null/undefined的属性访问使用?.。规则自动修复为obj?.prop?.subProp，而非obj && obj.prop && obj.prop.subProp。
• @our-org/prefer-readonly-array: 要求所有数组类型声明为readonly T[]，除非明确需要push/pop。配合TS的--noUncheckedIndexedAccess，彻底杜绝arr[100]越界访问。

这些规则不是拍脑袋定的。比如prefer-readonly-array，源于一次线上事故：一个Array<string>被意外push进非字符串值，导致后续map操作崩溃。readonly声明本身不阻止运行时修改，但它强制开发者在需要修改时，必须显式写as any或as string[]，这就创造了代码审查的“检查点”。

所有自定义规则都配有详细文档，说明“为什么这条规则存在”“违反它会导致什么线上问题”“正确写法示例”。我们甚至把文档链接嵌入ESLint错误提示中，开发者在VS Code里看到报错，鼠标悬停就能看到事故案例截图。

3.3 Playwright作为类型契约的终极验证者

Playwright常被当作E2E测试工具，但在Harness Engineering中，它是唯一能验证“类型契约是否在真实浏览器中成立”的设备。TS类型告诉你button.disabled是boolean，Playwright能告诉你：当button.disabled = true时，CSS是否真的添加了opacity: 0.5，点击事件是否真的被阻止，屏幕阅读器是否正确播报“disabled”。

我们为每个核心组件编写Playwright契约测试（*.contract.spec.ts），例如Button.contract.spec.ts：

import { test, expect } from '@playwright/test'; test('Button disabled state', async ({ page }) => { await page.goto('/iframe.html?id=button--primary'); // 1. 初始状态：enabled const button = page.locator('button'); await expect(button).toBeEnabled(); await expect(button).not.toHaveAttribute('aria-disabled', 'true'); // 2. 设置disabled=true await page.evaluate(() => { (window as any).buttonElement.disabled = true; }); // 3. 验证DOM属性、CSS、交互、无障碍 await expect(button).toBeDisabled(); await expect(button).toHaveAttribute('aria-disabled', 'true'); await expect(button).toHaveCSS('opacity', '0.5'); await button.click({ timeout: 100 }).catch(() => {}); // 点击应静默失败 await expect(page.getByText('Button clicked')).toBeHidden(); // 无事件触发 });

这个测试的价值，远超“按钮能不能点”。它把TS类型disabled: boolean、CSS规范opacity: 0.5、WAI-ARIA标准aria-disabled="true"、用户交互预期“点击无反应”全部串联起来，形成一条不可绕过的验证链。当任何一环断裂（比如某次UI库升级移除了opacity样式），测试立刻失败，而不是等用户投诉。

提示：契约测试必须用page.evaluate()直接操作DOM属性，而非通过React/Vue的API。因为我们要验证的是“最终渲染结果”，不是“框架状态”。框架API可能有异步队列、批量更新等机制，会掩盖真实问题。

4. Playwright Harness化：从脚本录制到可信契约引擎

Playwright常被简化为“比Selenium快的自动化工具”，但在Harness Engineering语境下，它必须进化为可编程、可审计、可版本化的前端契约引擎。它的价值不在于能点多少次按钮，而在于能否用代码精确描述“这个页面在什么条件下，必须呈现什么状态”。

4.1 录制脚本只是起点，契约声明才是终点

很多团队用Playwright Inspector录制登录流程，生成一段click/fill/waitForSelector代码，就以为完成了自动化。这是Harness Engineering的大忌——录制脚本是“怎么做”，而契约引擎要定义“应该是什么”。

我们强制所有Playwright测试以声明式契约开头。以登录页为例，login.contract.spec.ts第一段永远是：

// login.contract.spec.ts import { test, expect } from '@playwright/test'; // === 契约声明区 === const LOGIN_CONTRACT = { // 页面结构契约 structure: { emailInput: { selector: 'input[type="email"]', required: true }, passwordInput: { selector: 'input[type="password"]', required: true }, submitButton: { selector: 'button[type="submit"]', required: true }, errorAlert: { selector: '[data-testid="error-alert"]', required: false } }, // 交互行为契约 behavior: { validSubmit: { triggers: ['emailInput', 'passwordInput'], effect: 'navigateTo /dashboard' }, invalidSubmit: { triggers: ['emailInput', 'passwordInput'], effect: 'show errorAlert with message "Invalid credentials"' } }, // 视觉表现契约 visual: { emailInput: { hasFocusRing: true, placeholder: 'Enter your email' }, submitButton: { enabledByDefault: true, textContent: 'Sign In' } } }; test('Login page fulfills structural contract', async ({ page }) => { await page.goto('/login'); // 验证结构契约 for (const [key, def] of Object.entries(LOGIN_CONTRACT.structure)) { const el = page.locator(def.selector); if (def.required) { await expect(el).toBeVisible(); } else { // 非必需元素，验证其存在性不影响主流程 await expect(el).toHaveCount(0).catch(() => {}); } } });

这个LOGIN_CONTRACT对象，就是登录页的“宪法”。它不关心测试步骤，只定义“什么是正确的登录页”。所有后续测试（功能、性能、无障碍）都必须引用它。当UI设计师说“把邮箱输入框placeholder改成‘Your work email’”，修改点只有一个：LOGIN_CONTRACT.visual.emailInput.placeholder。契约声明与实现代码解耦，这是可维护性的根基。

4.2 浏览器指纹与环境模拟：让契约验证脱离“Chrome最新版”幻觉

Playwright默认启动Chromium最新版，但这制造了巨大幻觉：你的E2E测试在CI里100%通过，上线后用户用旧版Edge打开就白屏。Harness Engineering要求：契约验证必须覆盖真实用户环境。

我们用Playwright的launchPersistentContext和自定义User Agent，构建多环境验证矩阵：

// playwright.config.ts import { defineConfig } from '@playwright/test'; export default defineConfig({ projects: [ { name: 'chromium-latest', use: { ...devices['Desktop Chrome'], userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36' } }, { name: 'edge-110', use: { ...devices['Desktop Edge'], userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36 Edg/110.0.1587.57' } }, { name: 'safari-16', use: { ...devices['Desktop Safari'], userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Safari/605.1.15' } } ] });

关键点在于userAgent字符串必须精确匹配真实浏览器。我们从BrowserStack的公开数据中提取了Top 10用户环境UA，每季度更新一次。测试失败时，报告会明确指出“edge-110环境失败，chromium-latest通过”，这直接指向兼容性问题，而非随机失败。

注意：不要用playwright install chromium安装多个版本。Playwright官方只支持单版本Chromium。多环境验证必须通过User Agent和Feature Detection实现，而非真实浏览器二进制。

4.3 Playwright与ESLint的联合契约：代码即测试

Harness Engineering的终极形态，是让测试代码本身成为可静态分析的契约。我们开发了一个ESLint插件eslint-plugin-playwright-contract，它能扫描Playwright测试文件，验证其是否满足契约完整性：

• 规则contract/has-structure-declaration: 检查每个.contract.spec.ts文件是否包含CONTRACT常量声明。
• 规则contract/uses-contract-in-tests: 检查测试用例是否调用expect(...).toFulfillContract(CONTRACT)，而非直接写expect(locator).toBeVisible()。
• 规则contract/no-hardcoded-selectors: 禁止在test()函数体内写死CSS选择器，所有选择器必须来自CONTRACT.structure。

当开发者写：

// ❌ 违反规则：硬编码选择器，脱离契约 test('should show error on invalid email', async ({ page }) => { await page.fill('input[name="email"]', 'invalid'); await page.click('button[type="submit"]'); await expect(page.locator('.error-message')).toBeVisible(); });

ESLint会报错：“Hardcoded selector 'input[name="email"]' not allowed. Use CONTRACT.structure.emailInput.selector instead.”

这迫使所有测试代码与契约声明强绑定。契约变，测试自动失效；测试变，必须先改契约。二者形成不可分割的双生体。

5. 实战避坑指南：那些让Harness Engineering半途而废的致命细节

Harness Engineering听起来很美，但落地过程布满深坑。我亲手填过、也看着别人掉进去的坑，总结出五个最致命、最高频的失误。它们不关乎技术难度，而关乎工程直觉——正是这些细节，决定一个团队是真正迈入Harness阶段，还是停留在“又一个酷炫工具链”的幻觉里。

5.1 坑一：把“工具链自动化”当成“工程化”，忽视人的协作契约

最典型的症状是：团队花了两周搭好Husky+ESLint+Playwright流水线，CI里绿灯长亮，但Code Review里依然满屏any、// @ts-ignore、console.log。问题不在工具，而在没有同步建立人的协作契约。

我们的解法是：在CONTRIBUTING.md里，用表格明确定义“谁在什么场景下，必须做什么”：

这张表每周在团队站会上同步，新成员入职第一件事就是读它。工具只是执行者，人才是契约的制定者和守护者。没有这张表，再完美的工具链也只是华丽的摆设。

5.2 坑二：过度追求“100%覆盖率”，导致测试脆弱不堪

很多团队把Playwright覆盖率刷到95%，结果每次UI微调（比如把<div class="card">改成<article class="card">），就有一半测试挂掉。这不是测试有效，而是测试在“验证CSS类名”，而非“验证业务契约”。

我们的红线是：Playwright测试只验证用户可感知的、业务关键的状态。具体标准：

• ✅ 允许：await expect(page).toHaveURL('/dashboard')（URL是用户可见契约）
• ✅ 允许：await expect(page.getByRole('heading', { name: 'Welcome, John!' })).toBeVisible()（可访问性角色是契约）
• ❌ 禁止：await expect(page.locator('div.card')).toBeVisible()（CSS类名不是契约，随时可改）
• ❌ 禁止：await expect(page.locator('button').nth(2)).toBeEnabled()（序号定位极脆弱）

我们甚至写了脚本，自动扫描所有.spec.ts文件，统计locator()调用中CSS选择器的占比。一旦超过15%，PR自动被拒绝，并提示：“请改用getByRole、getByText或getByTestId”。

5.3 坑三：TypeScript配置“全家桶”滥用，导致类型检查形同虚设

tsconfig.json里堆满"strict": true,"noImplicitAny": true,"strictNullChecks": true，看起来很严格，但实际效果为零——因为开发者用// @ts-ignore或as any一键绕过。真正的严格，是让绕过成本高于解决问题成本。

我们的tsconfig.base.json只启用四个核心选项：

{ "compilerOptions": { "strict": false, "noImplicitAny": true, "strictNullChecks": true, "skipLibCheck": true } }

然后用ESLint规则@our-org/no-ts-ignore，禁止所有// @ts-ignore，并提供自动修复：将// @ts-ignore替换为// eslint-disable-next-line @our-org/no-implicit-any，并强制在下一行写明原因（如// eslint-disable-next-line @our-org/no-implicit-any // Backend API returns dynamic keys, need runtime validation）。

这样，@ts-ignore没消失，但它变成了一个必须被审查、被记录、被追踪的“技术债”。半年后，我们统计发现，@ts-ignore使用次数下降72%，而zod运行时校验使用量上升300%——这才是类型安全的正向循环。

5.4 坑四：ESLint规则“一刀切”，扼杀合理技术选型

曾有个PR，前端用WebAssembly加速图像处理，ESLint报错：“no-unused-vars：变量wasmModule未使用”。开发者无奈加了// eslint-disable-next-line，Reviewer也没细看就点了Approve。结果上线后，wasmModule因未被引用，被Webpack Tree Shaking干掉，功能直接失效。

根源在于ESLint规则没区分“业务代码”和“基础设施代码”。我们的解法是：用overrides为不同目录配置不同规则集：

// .eslintrc.cjs module.exports = { overrides: [ { files: ['src/wasm/**/*'], rules: { 'no-unused-vars': 'off', '@typescript-eslint/no-unused-vars': 'off' } }, { files: ['src/components/**/*'], rules: { '@our-org/no-implicit-any': 'error', '@our-org/require-optional-chaining': 'error' } } ] };

src/wasm/目录下，我们信任开发者对底层技术的判断；src/components/目录下，我们强制执行前端契约。规则不是越多越好，而是恰到好处地匹配代码域的治理需求。

5.5 坑五：忽略“人”的学习曲线，用工具复杂度吓退团队

最后，也是最隐蔽的坑：把Harness Engineering搞成一场“技术军备竞赛”。要求所有人立刻掌握api-extractor、zod、Playwright所有高级特性，结果没人敢改代码，生怕触发未知的CI失败。

我们的破局点是：所有新工具，必须配一个“三分钟上手”速查表。例如Playwright契约测试，我们提供一张A4纸大小的PDF：

Playwright契约测试速查表（3分钟上手） 1. 写契约：在文件顶部定义 const CONTRACT = { structure: { ... }, behavior: { ... } } 2. 验证结构：for (const [key, def] of Object.entries(CONTRACT.structure)) { await expect(page.locator(def.selector)).toBeVisible() } 3. 验证行为：await page.fill(CONTRACT.structure.emailInput.selector, 'test@example.com'); await expect(page).toHaveURL('/dashboard') 4. 运行：pnpm playwright test --project=chromium-latest 5. 查错：失败时，看控制台输出的“Expected selector: ...”和“Actual DOM: ...”

这张表不讲原理，只给最简路径。等大家用熟了，再逐步引入zod校验、多环境测试等进阶内容。Harness Engineering不是淘汰旧人，而是让每个人都能在自己的节奏上，稳稳踏上新台阶。

我在实际操作中发现，最难的从来不是技术本身，而是让团队相信：那些看似繁琐的检查、严格的规则、冗长的契约声明，不是在给开发添堵，而是在给未来的自己，买一份沉甸甸的安心。当某次线上事故被api-extractor提前拦截，当某个兼容性问题在edge-110环境里被Playwright揪出，当新同事第一天就能写出符合契约的代码——那一刻，你会真正理解，Harness Engineering不是下一个阶段，而是前端开发，终于长出了自己的脊梁。