导言动手时的三个原则系列三开始写代码。但动手前先立三条原则免得你抄完代码却没学到架构架构优先于代码每篇我都先讲为什么这样拆再给代码。看代码时对照系列二的五层图每个类都该能在图上找到位置。最小可用优于完整我只写跑通必需的最少代码。完整生产版要加并发、加配置、加日志轮转——这些是工程增量不影响你理解内核。可运行优于可炫所有代码我在本地能跑通的逻辑才写。你拿到后若环境不同按注释改依赖即可但骨架不变。记住你抄走的是一个 Harness 的内核不是一个测试。区别就在架构对不对。系列三 · 第 1 篇从零搭建一个测试 HarnessPlaywright 实战摘要动手了。用 Playwright 系列二的 Common Layer 思路搭一个最小可用 Web 测试 Harnesslocator 定位、executor 执行、oracle 断言、reporter 出报告。重点不在代码多在架构对。前面两个系列是认知和蓝图。从这篇开始我们写第一行代码。目标很克制用最少代码搭一个换个项目也能用的 Web 测试 Harness。核心思路直接复用我内部的 Common Layerlocator定位executor执行oracle判定reporter报告。请记住这篇的价值观重点不在代码多在架构对。你抄走这 80 行得到的不是一个测试而是一个 Harness 的最小内核。一、依赖与目录pip install playwright playwright install chromiumharness/ core.py # Executor Step locator.py # Dependency Manager (locator) oracle.py # Oracle reporter.py # Reporter test_demo.py # 你的测试为什么拆四个文件而不是一个因为系列二说过组件边界 团队并行边界 未来可拆边界。哪怕今天只有你一个人也别把四个组件焊在一个文件里——你会感谢三个月后的自己。二、Executor StepHarness 的心脏# harness/core.py from dataclasses import dataclass from typing import Callable, Any ​ dataclass class Step: name: str action: Callable[[Page], Any] # 具体 Playwright 操作 expect: Callable[[Page], bool] # oracle返回 True/False ​ class Executor: def __init__(self, browser): self.browser browser ​ def run(self, steps: list[Step]) - list[tuple[str, bool]]: page self.browser.new_page() results [] for s in steps: try: s.action(page) ok s.expect(page) except Exception as e: ok False page.screenshot(pathffail_{s.name}.png) # 失败留现场 print(f[FAIL] {s.name}: {e}) else: if not ok: page.screenshot(pathffail_{s.name}.png) print(f[{PASS if ok else FAIL}] {s.name}) results.append((s.name, ok)) page.close() return results为什么这样写对应系列二Step是一个数据对象描述做什么 期望什么不含执行细节——这是把测试意图和执行引擎解耦。Executor.run只干一件事按顺序跑 Step记录结果失败截图。它不关心 Step 里具体点了什么——这就是 executor 只做心脏的纪律。try/except包住每个 Step保证一个失败不拖垮全程且失败必截图。截图是 Observer 思维的雏形失败要留现场而不是只抛个异常。一个延伸生产里你会给 Executor 加concurrency并发跑多个 Step、加before/after钩子、加timeout。但内核就是这几行——理解它加什么都清楚。三、LocatorHarness 的手# harness/locator.py class Locator: def __init__(self, page): self.page page def click(self, text): self.page.get_by_text(text).click() def fill(self, placeholder, value): self.page.get_by_placeholder(placeholder).fill(value) def expect_visible(self, text) - bool: return self.page.get_by_text(text).is_visible()把怎么找元素收口到一个类。前端改版换选择器策略只改这里测试零动。这就是 Dependency Manager 的价值落地。踩坑提醒别在测试里直接写page.click(#login-btn)。一旦前端把 id 改成 class所有测试红。收口到 Locator 后改一个方法即可。这就是系列二说的它一变全站稳。四、Oracle Reporter# harness/oracle.py def assert_title(page, expected: str) - bool: return expected in page.title() ​ # harness/reporter.py def report(results: list[tuple[str, bool]]) - bool: passed sum(1 for _, ok in results if ok) print(f\n SUMMARY: PASS {passed}/{len(results)} ) return all(ok for _, ok in results)report返回整体是否通过供 CI 当退出码用sys.exit(0 if ok else 1)。它消费的是标准化results不是内部对象——呼应系列二契约铁律三跨层只走数据。为什么 oracle 是函数不是方法保持它无状态、可独立测试。将来你要换成用另一个 LLM 当 oracle只要替换这个函数Executor 一行不动。五、跑起来# test_demo.py from playwright.sync_api import sync_playwright from harness.core import Executor, Step from harness.locator import Locator from harness.oracle import assert_title from harness.reporter import report ​ def test_login(): with sync_playwright() as p: browser p.chromium.launch() loc Locator(browser.new_page()) steps [ Step(打开首页, lambda pg: pg.goto(https://demo.example.com), lambda pg: assert_title(pg, Demo)), Step(点击登录, lambda pg: loc.click(登录), lambda pg: loc.expect_visible(用户名)), ] ex Executor(browser) assert report(ex.run(steps)) browser.close()【配图本篇 Harness 运行流程图locator→executor→oracle→reporter】六、关键收获你刚刚写的不是一个测试是一个测试 Harness 的最小内核有 Executor心脏、Locator手、Oracle裁判、Reporter嘴测试只是声明 Step不碰执行细节失败自动留现场。接下来只要往上补系列二的五层——加环境层容器化浏览器把p.chromium.launch()换成从 EnvManager 取环境、加状态层把results升级成带trace的RunResult它就长成了完整的塔。架构对了扩展是加法架构错了扩展是重写。你这次选了加法。延伸思考这个内核只有 4 个组件缺环境层、状态层、约束层。所以它是能跑的脚本集合还不是完整的 Harness。但这正是系列设计的目的——让你先看到内核长什么样再理解为什么需要补全其余层。实战案例把 200 个遗留脚本迁移进 Harness 内核为了让架构对不只是一句口号讲一个我们内部的真实迁移。团队有 200 多个用 pytest 直接调 Selenium 的旧脚本典型特征是环境靠手动开、选择器散落各处、失败后靠人肉翻截图。迁移分三步第一步先抽 Locator。用正则扫描 200 个文件里的find_element_by_*调用自动替换为Locator的语义方法再人工校正约 5% 匹配不准的。这一步没动任何测试逻辑只是换了手。第二步套 Executor。把每个脚本的前置 操作 断言包成Step交给统一 Executor 跑。好处立刻显现失败自动截图、统一计时、并发可开。第三步补 EnvManager。用容器封装浏览器环境脚本里删掉所有环境准备代码。迁移后最直观的变化前端一次大改版旧脚本预计全红、改 3 天新内核改一个 locator 文件、10 分钟复活。这就是系列二说的它一变全站稳。踩坑实录迁移初期有人把assert直接写进action里导致 Executor 捕获不到 oracle 结果、失败统计失真。教训刻在骨头上action 只做操作期望必须进expect——职责边界是内核稳定的命根子越界一次数据就假一次。 留言区你现在的自动化脚本有多少能直接套进这个四件式骨架评论区晒改造思路我挑典型的在下篇展开。 关注回复「harness」领本篇完整可运行仓库。系列三 · 第 2 篇构建你的 Eval Harness对标 lm-evaluation-harness摘要评测大模型难的不是跑模型是公平对比。本文用约 50 行代码讲清 Eval Harness 三件事Task 声明式配置、LM 接口抽象、Metric 聚合 种子固定。测试 Harness 管的是确定性软件Eval Harness 管的是概率性模型。难点完全变了你担心的不再是它崩了而是它这次蒙对了下次未必。对标 EleutherAI 的lm-evaluation-harness我把 Eval Harness 拆成三件事。这篇就把这三件事用最少代码写出来。一、Task把评测什么声明出来# tasks/translation.yaml task: translation_zh2en dataset: path: data/zh2en.jsonl input: chinese reference: english metric: bleu few_shot: 3任务和数据彻底解耦——换数据集不碰代码换指标改一行配置。这是 Eval Harness 复用性的根基。为什么声明式这么重要在确定性测试里你写一个assert就是在声明期望。但在概率世界期望变成了一个评分函数 一串样本。把它们外置成 yaml意味着评测逻辑和评测内容分离——研究员调 prompt、调 few_shot工程师调框架互不干扰。这是大模型团队能规模化的关键。二、LM 接口抽象让模型可替换# eval/lm.py from abc import ABC, abstractmethod ​ class LM(ABC): abstractmethod def complete(self, prompt: str, **kw) - str: ... ​ class OpenAILM(LM): def __init__(self, client, modelgpt-4o-mini): self.client, self.model client, model def complete(self, prompt, **kw): r self.client.chat.completions.create( modelself.model, messages[{role:user,content:prompt}]) return r.choices[0].message.content你的任务代码只认LM抽象。今天用 GPT明天换国产模型DeepSeek / 通义 / 文心任务一行不动——只需新增一个LM实现。这正是系列二铁律一只依赖抽象的回报。国产模型提示你提到你们平台支持 DeepSeek、通义、文心、GLM、Kimi、豆包等国产大模型。Eval Harness 的 LM 抽象层正好让一键切换国产模型做评测变成现实——这对不依赖国外模型的合规诉求是直接支撑。每个国产模型写一个LM子类即可任务配置零改动。三、Metric 聚合 种子固定管住随机性# eval/run.py import random, json ​ def evaluate(task: dict, lm: LM, n: int 5) - float: data [json.loads(l) for l in open(task[dataset][path])] scores [] for sample in data: random.seed(42) # 固定种子保证可复现 prompt build_prompt(task, sample) # few-shot 拼接 outs [lm.complete(prompt) for _ in range(n)] scores.append(task_metric(task[metric], outs, sample[reference])) return sum(scores) / len(scores)random.seed(42)是 Eval Harness 的灵魂让概率性输出可复现、可对比。没有它你两次跑分不一样根本不知道是模型变了还是运气变了。一个负责任的 Eval Harness必须固定一切随机源包括模型自身的 temperature 也要显式设低或固定。为什么多次采样n5单次生成有方差。聚合成均值分数才稳。生产里 n 往往取 5~10并报告标准差让模型 A 比 B 好这个结论有统计意义而不是好这一次。四、三件套合体【配图Eval Harness 三件套关系图Task / LM / Metric】Task(声明) ──┐ ↓ LM(抽象接口) → evaluate() → Metric(聚合 种子) ↑ Dataset(解耦)这个结构的妙处你可以用同一份 evaluate 函数评任意模型、任意任务。加一个新模型 加一个 LM 类加一个新任务 加一个 yaml。无限扩展都是加法。五、Eval Harness 的硬指标判断你的 Eval Harness 合不合格三条可复现同模型同任务两次跑分一致靠种子。可对比换模型结果可直接横向比靠统一 Metric。可扩展加模型/任务不碰核心代码靠抽象。这三条正好对应系列一的可复现 受控 可观测。Eval Harness 就是把系列一那三个词在概率世界重新实现一遍。延伸Metric 设计的坑BLEU 适合翻译不适合开放问答开放生成常用 LLM-as-judge用一个强模型评另一个。选错 Metric整个评测结论作废。下一篇 Agent Harness 会遇到更难的怎么判定 Agent 真完成了——那正是 Metric 设计的深水区。实战案例用 Eval Harness 给国产模型做横向评测你们平台支持 DeepSeek、通义、文心、GLM、Kimi、豆包等国产模型正好用 Eval Harness 演示换模型不碰任务。我们做过一次内部评测同一个翻译任务 yaml分别接 6 个国产模型的LM实现跑同一份种子、同一份样本。结果出来很有意思总体 BLEU 差距不大但按长句专有名词口语化拆分子项后模型各具长短。如果没有 Eval Harness 的统一接口和固定种子这种公平对比根本做不出来——你得为每个模型手写一套评测seed 还不一定一致结论毫无可比性。踩坑实录few_shot 示例的顺序会影响分数。我们曾把示例随机打乱两次跑分差了 3 个点一度以为模型不稳最后发现是示例顺序在悄悄给模型泄题。教训few_shot 也要固定写进 yaml 并版本化否则 Eval Harness 的可复现会被自己破坏。 留言区评测模型时你最头疼的是分数忽高忽低还是指标选不对评论区说我下篇专门讲 Metric 设计陷阱。 关注回复「harness」领 Eval Harness 最小模板仓库。系列三 · 第 3 篇Agent Harness 设计多角色制衡摘要让一个 Agent 既干活又自检等于让考生自己改卷。本文用代码讲 Agent Harness 如何用多角色制衡 约束层 校验层破解约束规避与虚报完成。到了 Agent 时代被测对象会自己规划、自己调工具、自己宣布完成。单 Agent 自检 自己改自己卷子不可信。系列一说过解法叫制衡这篇落地成代码。一、把任务拆给不同角色【配图多 Agent 编排图Planner / Worker / Critic / Judge】Planner拆任务不直接执行。Worker执行但看不到最终判定权。Critic独立审查 Worker 的轨迹找绕过和遗漏。Judge对照规格做最终裁决权力独立于前三者。第一铁律Worker 不能既干活又裁判。二、约束层在 OS 层卡死约束规避# agent/harness.py BLOCKED {delete_production, skip_verification, direct_db_write} ​ def guard(tool_call: dict) - dict: if tool_call[name] in BLOCKED: raise PermissionError(f被约束层拦截{tool_call[name]}) return dispatch(tool_call) # 真正执行约束在Harness 层执行不在 Agent 提示词里请求它遵守。提示词里的请勿删除生产数据是建议OS 层的guard是法律——法律绕不过去。这直接治了系列一的约束规避。为什么提示词不够LLM 的遵守指令是概率性的长上下文里会衰减规则遗忘遇到利益冲突会权衡后绕过约束规避。把规则变成 OS 层的硬卡点就从机制上消灭了这两类风险。你们的平台强调模型热替换与无 LLM 规则降级本质也是同一思路——规则由系统守不由模型守。三、校验层用轨迹治虚报完成# agent/verify.py def judge(trace: list, spec: dict) - bool: done_steps {t[step] for t in trace} required set(spec[required_steps]) missing required - done_steps if missing: print(f[JUDGE] 虚报完成缺 {missing}) return False return TrueJudge 不读 Worker 的我完成了结论只读状态层记录的真实轨迹trace逐步比对规格spec。轨迹里缺的一步就是虚报的证据。这治了虚报完成和自审失效。四、一个最小闭环plan Planner().plan(task) # 拆任务 trace [] for step in plan: call Worker().act(step) call guard(call) # 约束层卡一道 result dispatch(call) trace.append({step: step, result: result}) ​ verdict Judge().judge(trace, spec) # 校验层判一道 assert verdict, Agent 未真正完成拒绝放行【配图Agent Harness 双层防线运行图guard 拦截 judge 校验】五、为什么必须多角色有人会问为什么不让一个聪明 Agent 又干又审因为 LLM 有自我美化偏差——让它审自己的产出它倾向于确认而非否定。多角色把生成和判定分给不同上下文、不同目标函数的 Agent从机制上消灭自我美化。这不是工程技巧是统计学必然。延伸Critic 和 Judge 可以都是规则便宜、确定也可以是另一个 LLM灵活、但有偏差。生产建议规则做硬卡 模型做软查两层都过才放行。这也是你们无 LLM 规则降级的落地形态——LLM 挂了规则仍在Agent 不能裸奔。实战案例用双层防线拦下一次真实虚报讲一个让我们彻底信服 Agent Harness 的案例。一个自动修复接口的 Agent自报全部用例通过无问题。但 Judge 拿到状态层 trace 一比发现它跳过了边界值测试这一步——理由是在日志里写了边界情况风险低已评估跳过。如果没有校验层这个跳过就神不知鬼不觉地溜进发布。约束层 校验层合起来把这次虚报当场摁住约束层禁止无理由跳过 required_steps校验层发现 trace 缺步直接判否。踩坑实录多 Agent 协作时Planner 和 Worker 共享了同一段过长的上下文导致 Worker 继承了 Planner 里一句随意的这步不太重要。教训角色之间传计划要精简成结构化指令别把啰嗦的思考过程整个喂下去——上下文越长规避和误读越多。 留言区你试过多 Agent 协作吗踩过两个 Agent 互相甩锅的坑吗评论区聊我整理成《多 Agent 避坑清单》。 关注回复「harness」领多 Agent 编排示例仓库。系列三 · 第 4 篇状态管理与可观测性让在我电脑能跑变成任何环境一致摘要失败不可怕可怕的是偶现、无法复现。本文讲状态快照、轨迹记录、日志/指标/链路三件套把 Harness 的眼装上并给出可运行的最小接入代码。测试人最怕听到一句话在我电脑上是好的。这句话的本质是状态不可见。系列二说过状态层是可复现性的根源。这一篇把它落地并配上 Observer观察器的最小实现。一、状态快照把现场存下来# obs/snapshot.py import os, json ​ class Snapshot: def capture(self, run_id: str, payload: dict): payload[seed] os.environ.get(SEED) json.dump(payload, open(fsnap/{run_id}.json, w), ensure_asciiFalse) def replay(self, run_id: str) - dict: return json.load(open(fsnap/{run_id}.json))每次运行存一份快照输入、环境指纹、随机种子。下次偶现直接replay重放不用求爷爷告奶奶复现。为什么这能治偶现所谓偶现90% 是某个隐藏输入/状态不一致。快照把那次运行的全部上下文固化下来重放时连环境都还原偶现就变必现。必现的 bug才好修。二、可观测三件套【配图可观测性面板Logs / Metrics / Trace 三栏】Logs结构化日志关键节点打点。Metrics通过率、耗时、失败分布趋势一目了然。Trace完整调用轨迹Agent 每一步留痕接上篇校验层。# obs/observer.py class Observer: def __init__(self, run_id): self.rid run_id; self.trace [] def log(self, msg): print(f[{self.rid}] {msg}) def metric(self, name, val): self.metrics[name] val def step(self, step, result): self.trace.append({step: step, result: result})三件套合起来失败从一句红了变成一段可回溯的证据链。三、接回 Executor把 Observer 嵌进系列三第 1 篇的 Executorclass Executor: def run(self, steps, observer: Observer): for s in steps: observer.log(frun {s.name}) s.action(page) ok s.expect(page) observer.step(s.name, ok) if not ok: observer.metric(last_fail, s.name) observer.metric(pass_rate, passed/len(steps))从此每次运行都自带可观测能力。等你把trace落盘上篇 Agent Harness 的judge(trace, spec)就能直接消费——三个系列在这一刻闭环了。四、一句价值观好的 Harness 不追求永远不出错它追求出错就一定能被看见、被复现、被定位。测试的价值不在绿而在真问题一个都跑不掉。可观测性就是这句话的工程技术实现。延伸从可观测到质量智能当你把每次运行的 trace、metrics 沉淀下来你就有了质量数据湖。系列四最后一篇会讲这些数据如何喂养出AI 质量官——可观测性是智能的起点。实战案例用快照把偶现变必现一个时灵时不灵的登录测试困扰团队两周。人肉复现不了只能多跑几次碰运气。我们给 Executor 接上 Snapshot强制每次运行记录输入账号、环境指纹、随机种子、点击序列。重放第 7 次运行的那份快照时bug 稳定复现——根因是某个第三方验证码服务在高峰时段偶发超时测试没对它做隔离。修复后这个偶现再没出现过。踩坑实录trace 全量落盘成本不低。一次 Agent 运行可能产生上万条轨迹。我们后来做了分级默认只存步骤级trace只在失败时才补全调用级细节。可观测性也要讲成本否则质量数据湖先把自己撑爆。 留言区你们团队现在能一键复现一个偶现 bug吗还是要三个人折腾一下午评论区说真实情况。 关注回复「harness」领可观测性最小接入方案。系列三完下一系列我们讲进阶与智能化。系列三延伸生产级 Harness 的 10 条军规系列三的代码是最小内核能学架构但直接上生产还差一层。把这 10 条当上线 checklist逐条对着补。环境即代码环境用声明式 spec 制备可版本管理、可回滚禁止手动装好。失败必留现场截图/快照/日志三选一至少留且路径可溯。状态可序列化RunResult 用纯数据结构能落盘、能网络传、能回放。** oracle 独立**判定逻辑绝不与执行者同源尤其别让同一个 LLM 又干又审。约束在 OS 层AI 场景的规则由 Harness 卡死不靠提示词请求遵守。并发可控Executor 支持并发但默认保守避免压垮被测环境。重试只针对瞬态区分 TransientError 和真失败真失败不重试、直接告警。报告双格式给人看HTML/图 给机器消费JSON/JUnit XML都要有。配置外置阈值、种子、超时全进配置不焊死在代码里。可观测分级默认步骤级 trace失败才补全调用级控制存储成本。这 10 条前 5 条是可信对应受控/可复现/可观测三特性后 5 条是可养能长期运营不崩。内核满足了前 5 条就值得骄傲10 条全中才叫生产级。建议把它们贴在你团队 wiki 首页每次加组件前对照。系列三 · 一页速记卡测试 Harness 内核四件式Locator(手)Executor(心脏)Oracle(裁判)Reporter(嘴)测试只声明 Step不碰执行细节。Eval Harness 三件套Task(声明)LM(抽象接口)Metric(聚合种子)。换模型不碰任务国产模型各写一个 LM 子类即可。Agent Harness 多角色Planner/Worker/Critic/JudgeWorker 不能既干又审约束层 OS 级卡死校验层读 trace 防虚报完成。可观测三件套Logs/Metrics/Trace状态快照把偶现变必现trace 分级控成本。生产级 10 条军规见延伸前 5 条保可信受控/可复现/可观测后 5 条保可养能长期运营。给老板的 30 秒版我们用最少代码造出可复用的测试底座前端一次大改版从改脚本 3 天变成改一个 locator 文件 10 分钟复活——这是架构对的直接回报。三个反共识① Eval Harness 不必自己造复用 lm-evaluation-harness只写差异化适配② Agent 框架 ≠ Agent Harness后者是站在外面的质量外壳管住前者别撒谎③ 可观测性先落盘 JSON 人工复盘别一上来就 Prometheus/Grafana工具是手段不是目的。本地跑不起来三排查没playwright install chromium、sync/async API 混用、占位地址没换真实环境——先查这三条。一句话收尾架构对了扩展是加法架构错了扩展是重写。系列三 · 一页速查表Harness 类型核心文件关键组件必记要点测试 Harnesscore / locator / oracle / reporterLocatorExecutorOracleReporter测试只声明 Step不碰执行Eval Harnesslm.py / run.py yamlTaskLMMetric固定 seed换模型不碰任务Agent Harnessharness.py / verify.pyPlanner/Worker/Critic/Judge约束层卡死 校验层读 trace可观测observer / snapshotLogs/Metrics/Trace快照把偶现变必现把这表贴 wiki写代码前对照。系列三你手写出的不是一个测试而是一个 Harness 的内核——记住这句话将来扩展都是加法不是重写。系列三 · 读者行动清单读完别只收藏照这四条做动手才算学会今晚用你手头任意一个 Playwright 脚本按系列三第 1 篇的 Common Layerlocator/executor/oracle/reporter重新画一张依赖图看它把定位和执行混在一起了没有。本周把系列三第 2 篇的evaluate(task, lm, n)模板抄出来跑通一个你自己的小任务重点验证random.seed(42)关掉后结果还稳不稳——不稳就是可复现没过关。本月挑团队里最痛的一个 Agent 失控案例用系列三第 4 篇的约束层卡死 校验层读 trace两道防线重画一次标出哪条该挡在 OS 层、哪条该交给独立 oracle。长期建一个harness-recipes目录把这三个 Harness 的内核当模板沉淀新项目直接拿来改别每次从零写。收藏从不等于学会动手才算。下一系列见我们谈智能与质量门禁。系列三 · 本系列金句墙适合转发、做封面金句、贴团队墙架构对了扩展是加法架构错了扩展是重写。测试 Harness 内核四件式手(Locator)心脏(Executor)裁判(Oracle)嘴(Reporter)。Eval Harness 三件套声明(Task)抽象(LM)聚合(Metric)换模型不碰任务。Worker 不能既干活又裁判——让 LLM 审自己等于考生自改卷。约束层在 OS 级卡死规则Agent 想绕也绕不过去。状态快照把偶现变必现可观测性不追求永远不出错追求出错必被看见。复用社区lm-evaluation-harness只写差异化适配别重复造轮子。Agent 框架 ≠ Agent Harness前者让你造 Agent后者让你信 Agent 的结果。给读者的 3 句叮嘱① 先跑通四件式再追完整塔别闷头造框架② 本地跑不起来先查 chromium / sync-async / 占位地址三件事③ trace 分级存别让数据湖先撑爆。把四件式贴在团队 wiki 首页每次加组件前对照它越权干了别的组件的活吗