Skip to content

约 5 分钟阅读

Harness 工程:规格的强制执行体系 ​

Agent 能读文件、改代码、跑命令之后,项目需要一个更明确的外壳来约束它。Harness 工程就是这个外壳:规则、权限、沙箱、检查、日志、回滚和人工确认点。

订单导出看似只是一个后台功能,但它能触发多种风险:导出敏感字段、绕过权限、拖慢数据库、生成不可追踪的文件、失败后无法恢复。Harness 的任务是让这些风险不能只靠“开发者记得”来控制。

Harness 控制关系

Harness 守住什么 ​

对于订单导出,Harness 至少要守住四类边界。

边界说明常见执行方式
数据边界只能导出字段白名单,不导出敏感字段字段白名单测试、敏感字段扫描
权限边界只有具备导出权限的角色能操作权限测试、接口鉴权、人工 review
性能边界不允许大查询拖垮数据库行数限制、异步任务、慢查询监控
变更边界Agent 不能随意改权限体系和生产配置禁区文件、分支保护、CI 检查

这些边界如果只写在口头规则里,很容易在快速迭代中被跳过。Harness 要把它们变成可执行检查。

项目规则 ​

Harness 的第一层是项目说明。它应告诉 Agent:这个项目是什么、怎么验证、哪些地方不能碰。

markdown
# 订单后台 Harness 摘要

## 核心命令
- npm run test -- order-export
- npm run test -- order-list
- npm run build

## 导出规则
- 导出字段必须走字段白名单。
- 禁止导出手机号、详细地址、身份证号、用户备注和内部风控备注。
- 导出接口必须检查 order:export 权限。
- 超过 1 万行不能同步导出。

## 禁区
- 不修改生产数据库连接配置。
- 不绕过统一权限中间件。
- 不新增未经评估的文件存储公开地址。
- 不升级核心框架依赖。

这份说明提供任务约定,但文件中的“禁止”不会自动撤销进程权限。运行时的文件访问、网络和凭据权限要由执行环境限制;合并条件由分支保护与 CI 执行。一万行是本例的同步上限,需在实际字段宽度、并发和数据库负载下重新验证。命令名称也必须与业务仓库的 package.json 对齐。

可执行检查 ​

Harness 的第二层是命令和测试。订单导出的规格可以落到这些检查上:

bash
npm run test -- order-export
npm run test -- order-permission
npm run test -- csv-sanitizer
npm run build

测试要覆盖关键风险,而不是只验证按钮存在:

  • 无权限用户无法导出。
  • CSV 表头只包含字段白名单。
  • 敏感字段不会出现在文件内容中。
  • 空结果生成表头。
  • 超过行数限制时返回明确错误。
  • 导出失败不会清空用户筛选条件。

CI 应要求这些检查通过。Agent 本地跑过只是第一层,CI 阻断才是团队层面的强制执行。

隔离环境 ​

独立分支和 worktree 方便审查、回退以及并行修改,但不是安全沙箱。它们不隔离进程、主机文件、网络或凭据;在 worktree 里运行的命令仍可能读取主目录、访问生产地址或修改其他目录。

需要执行未知依赖或限制外部访问时,应在受限容器、虚拟机或工具提供的沙箱中运行。只挂载任务目录,使用临时测试凭据,按需限制网络出口,并核对实际挂载、环境变量和运行用户。容器若挂载主机 Docker socket 或整个主目录,也不能据此认为已经隔离。权限拒绝应由执行层返回,不能仅靠提示词要求 Agent 自觉遵守。

隔离环境还包括数据隔离。用于验证导出的数据应该是脱敏样例或测试数据,不能直接连接生产库。下载文件也不应上传到真实外部存储,除非任务明确要求并经过确认。

人工确认点 ​

Harness 不是把所有事情都自动化。对高风险动作,它应明确要求人工确认:

操作为什么需要确认
新增敏感字段导出涉及隐私和合规风险
修改权限模型可能影响多个后台功能
支持大批量异步导出需要任务表、存储、清理和监控设计
新增第三方存储或下载服务涉及访问控制和数据生命周期
调整生产配置影响发布和回滚

Agent 遇到这些动作时,应先产出方案和影响说明,而不是直接执行。

可观测性和审计 ​

订单导出本身也需要可观测。Harness 应要求实现中留下排查线索:

  • 谁在什么时间导出了什么范围的数据。
  • 导出字段集合是什么。
  • 导出成功、失败、超量、无权限分别有日志。
  • 生成的文件是否有过期策略。
  • 异常是否能关联到请求 ID 或任务 ID。

这些信息能帮助团队在事故后回答“导出了什么、谁导出的、是否越权、文件是否还能访问”。

回滚和恢复 ​

Harness 还要考虑失败后的恢复。订单导出上线后,如果发现敏感字段泄露或数据库压力异常,应在服务端停接新任务,再决定取消、排空或保留运行中的任务。前端隐藏按钮不能阻止直接调用接口。

适合写进 Harness 的恢复动作包括:

  • 导出服务入口由 feature flag 控制,关闭后直接调用接口也应拒绝。
  • CI 产物和发布版本可追踪。
  • 发现问题时能回滚到上一个稳定版本。
  • 已生成文件有过期和删除机制,下载授权可以撤销,缓存或签名链接的有效期可检查。
  • 审计日志能定位受影响导出记录。

回滚代码不会收回已经下载的文件,也不自动撤销仍有效的下载链接。恢复验证要直接请求服务接口、检查任务状态并尝试旧链接,审计记录用于确定受影响范围。

分层建设 ​

长任务的运行控制还应进入 Harness:持久化任务与步骤状态,执行前检查依赖和剩余预算,写入超时后查询原操作,并让验收证据绑定代码、数据或任务版本。模型可以提出计划与恢复建议,程序决定状态能否推进;聊天中的“已经完成”不能直接改写任务成功状态。

跨会话恢复时已用额度继续累计,取消等待后仍需核查在途操作。恢复检查点不会撤销外部写入,详细的故障窗口和验证方法见 Agent 长任务实践。

层级适用情况Harness 内容
个人项目原型或低风险工具README 命令、基础测试、Git diff 自查
小团队真实后台功能CI、权限测试、字段白名单、分支保护
中大型团队涉及数据和合规审计日志、风险库、人工确认、监控和回滚演练

不需要一开始就把所有系统建满。订单导出如果只是原型,轻量 Harness 足够;如果要进入生产后台,权限、字段和审计就不能省略。

Harness 的局限 ​

Harness 能阻断已被检查覆盖的问题,例如构建失败、某个越权请求或错误字段输出,但测试通过不证明所有数据组合、权限路径和外部依赖都正确。测试之外仍需运行监控与审查。CSV 是否满足财务流程、导出能力是否应该开放给某个角色、数据保留多久合适,需要产品、技术和安全角色共同决定。

好的 Harness 会把“必须机器检查的部分”机器化,把“必须人判断的部分”显式化。

总结 ​

Harness 工程让 Agent 的行动进入可控范围。它不是降低速度,而是把速度放进规则、检查和恢复机制中。

订单导出越接近真实数据,越需要 Harness。字段白名单、权限测试、CI、审计日志和人工确认点共同决定了这个功能能否可靠交付。

→ 下一步:组织流程工程

别急,先让缓存热一下。