一、引言：环境决定行为
在 Harness Engineering 中，有一个核心理念：
Agent 的行为不是由 Agent 本身决定的，而是由它所处的环境决定的。
就像同样的种子，在不同的土壤、光照、水分条件下，会生长出截然不同的植物。同样的 AI Agent，在不同的执行环境中，也会产生截然不同的输出质量。
设计一个优秀的 Agent 执行环境，是 Harness Engineering 的核心技能。本文将深入探讨如何从零开始设计和构建这样的环境。
二、Agent 执行环境的核心要素
2.1 执行环境的定义
Agent 执行环境是 AI Agent 运行所需的完整基础设施，包括计算资源、工具链、数据访问、约束规则和监控系统。
┌─────────────────────────────────────────────────────────┐
│ Agent 执行环境全景图 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 基础设施层 │ │
│ │ • 计算资源（CPU/GPU/内存） │ │
│ │ • 容器化环境（Docker/Kubernetes） │ │
│ │ • 网络配置和访问控制 │ │
│ │ • 持久化存储（代码库、数据） │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 工具链层 │ │
│ │ • 开发工具（IDE、编辑器） │ │
│ │ • 构建工具（编译器、打包器） │ │
│ │ • 测试工具（测试框架、覆盖率） │ │
│ │ • 部署工具（CI/CD、容器编排） │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 数据访问层 │ │
│ │ • 代码仓库（Git） │ │
│ │ • 知识库（文档、API 文档） │ │
│ │ • 数据库（业务数据、配置） │ │
│ │ • 外部 API（第三方服务） │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 约束规则层 │ │
│ │ • 架构约束（项目结构、技术栈） │ │
│ │ • 代码约束（规范、风格） │ │
│ │ • 安全约束（权限、敏感操作） │ │
│ │ • 资源约束（时间、成本） │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 监控反馈层 │ │
│ │ • 日志收集和分析 │ │
│ │ • 性能指标监控 │ │
│ │ • 质量评估系统 │ │
│ │ • 告警和通知 │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ AI Agent 层 │ │
│ │ （Codex/Claude 等） │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
2.2 环境设计的核心目标
目标
说明
关键指标
可靠性
Agent 能够稳定、持续地工作
任务成功率、系统可用性
效率性
Agent 能够快速、高效地完成任务
任务完成时间、资源利用率
安全性
Agent 的行为在可控范围内
安全事件数、权限违规数
可观测性
Agent 的行为可被监控和理解
日志覆盖率、监控指标数
可扩展性
环境能够支持更多 Agent 和任务
并发任务数、资源扩展能力
三、基础设施层设计
3.1 计算资源规划
┌─────────────────────────────────────────────────────────┐
│ 计算资源架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 资源调度层 │ │
│ │ （Kubernetes / Docker Swarm） │ │
│ │ │ │
│ │ • 自动扩缩容 │ │
│ │ • 负载均衡 │ │
│ │ • 故障转移 │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────┼───────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 轻量任务池 │ │ 标准任务池 │ │ 重载任务池 │ │
│ │ │ │ │ │ │ │
│ │ 2 CPU │ │ 4 CPU │ │ 8 CPU │ │
│ │ 4 GB RAM │ │ 8 GB RAM │ │ 16 GB RAM│ │
│ │ │ │ │ │ │ │
│ │ 简单脚本 │ │ 常规开发 │ │ 复杂构建 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ 资源分配策略： │
│ • 根据任务类型自动分配合适资源 │
│ • 支持动态调整，避免资源浪费 │
│ • 设置资源上限，防止单个任务耗尽资源 │
│ │
└─────────────────────────────────────────────────────────┘
3.2 容器化环境配置
dockerfile
复制
# Dockerfile - Agent 执行环境
FROM node:18-alpine
# 安装基础工具
RUN apk add --no-cache git python3 make g++
# 设置工作目录
WORKDIR /workspace
# 预装常用依赖（加速后续构建）
COPY package*.json ./
RUN npm ci
# 安装代码质量工具
RUN npm install -g eslint prettier jest
# 配置 Git
RUN git config --global user.name "AI Agent" && \
git config --global user.email "agent@ai.dev"
# 设置权限
RUN chown -R node:node /workspace
USER node
# 健康检查
HEALTHCHECK --interval=30s --timeout=3s \
CMD node -e "console.log('healthy')" || exit 1
# 启动命令
CMD ["node", "/agent/entry.js"]
3.3 网络与存储设计
组件
设计要点
实现方式
网络隔离
Agent 只能访问必要的网络资源
容器网络策略、防火墙规则
代码存储
持久化、版本化、可回滚
Git 仓库、分支策略
数据存储
结构化数据、缓存、日志
数据库、Redis、对象存储
临时存储
构建产物、中间文件
临时卷、定期清理
四、工具链层设计
4.1 工具链架构
┌─────────────────────────────────────────────────────────┐
│ 工具链架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 工具编排层 │ │
│ │ （任务定义、依赖管理、执行调度） │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ 开发工具 │ │ 构建工具 │ │ 质量工具 │ │
│ │ │ │ │ │ │ │
│ │ • IDE │ │ • 编译器│ │ • Linter│ │
│ │ • 编辑器│ │ • 打包器│ │ • 测试框架│ │
│ │ • Git │ │ • CI/CD │ │ • 覆盖率 │ │
│ │ │ │ │ │ • 安全扫描│ │
│ └────────┘ └────────┘ └────────┘ │
│ │
│ 设计原则： │
│ • 工具标准化：所有 Agent 使用相同版本的工具 │
│ • 配置集中化：工具配置统一管理和分发 │
│ • 执行自动化：工具链调用自动化，减少人工干预 │
│ │
└─────────────────────────────────────────────────────────┘
4.2 工具链配置示例
yaml
复制
# toolchain.yaml
tools:
development:
editor:
name: vscode
extensions:
- eslint
- prettier
- gitlens
git:
version: "2.40"
config:
default_branch: main
pull_rebase: true
build:
node:
version: "18.16"
package_manager: npm
typescript:
version: "5.0"
strict: true
bundler:
name: vite
config: vite.config.ts
quality:
linter:
name: eslint
config: .eslintrc.js
auto_fix: true
formatter:
name: prettier
config: .prettierrc
testing:
framework: jest
coverage_threshold: 80
test_pattern: "**/*.test.ts"
security:
scanner: snyk
fail_on: high
# 工具安装脚本
setup:
- name: install_node
command: "nvm install 18.16 && nvm use 18.16"
- name: install_dependencies
command: "npm ci"
- name: verify_setup
command: "npm run verify"
五、数据访问层设计
5.1 数据访问架构
┌─────────────────────────────────────────────────────────┐
│ 数据访问架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 数据访问网关 │ │
│ │ （统一接口、权限控制、审计日志） │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ 代码仓库 │ │ 知识库 │ │ 外部服务 │ │
│ │ │ │ │ │ │ │
│ │ • Git │ │ • 文档 │ │ • API │ │
│ │ • 分支 │ │ • 规范 │ │ • SDK │ │
│ │ • PR │ │ • 示例 │ │ • 数据库│ │
│ └────────┘ └────────┘ └────────┘ │
│ │
│ 设计要点： │
│ • 统一访问接口：Agent 通过统一接口访问所有数据 │
│ • 细粒度权限：不同任务有不同的数据访问权限 │
│ • 完整审计：记录所有数据访问行为 │
│ • 缓存优化：常用数据缓存，减少重复访问 │
│ │
└─────────────────────────────────────────────────────────┘
5.2 知识库设计
Agent 需要访问的知识包括：
知识类型
内容
存储方式
项目知识
项目结构、架构文档、API 文档
Markdown + 向量数据库
代码知识
代码库、历史提交、Code Review 记录
Git + 代码搜索引擎
规范知识
编码规范、设计模式、最佳实践
结构化文档
领域知识
业务术语、业务规则、用户场景
知识图谱
┌─────────────────────────────────────────────────────────┐
│ 知识库检索流程 │
├─────────────────────────────────────────────────────────┤
│ │
│ Agent 需要知识 │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 查询理解 │ │
│ │ • 提取关键词 │ │
│ │ • 识别意图 │ │
│ │ • 确定知识类型 │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 多路检索 │ │
│ │ │ │
│ │ 向量检索 ──→ 语义相似文档 │ │
│ │ │ │ │
│ │ 关键词检索 ──→ 精确匹配内容 │ │
│ │ │ │ │
│ │ 图谱检索 ──→ 关联知识 │ │
│ │ │ │ │
│ │ 代码检索 ──→ 相关代码片段 │ │
│ │ │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 结果融合与排序 │ │
│ │ • 去重 │ │
│ │ • 相关性排序 │ │
│ │ • 上下文组装 │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 返回结构化知识给 Agent │
│ │
└─────────────────────────────────────────────────────────┘
六、约束规则层设计
6.1 约束的分层实现
┌─────────────────────────────────────────────────────────┐
│ 约束规则的分层实现 │
├─────────────────────────────────────────────────────────┤
│ │
│ 第 4 层：业务规则（最高层） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 实现方式：领域模型验证器、业务规则引擎 │ │
│ │ 示例：订单金额必须大于0，库存不能为负数 │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ 第 3 层：安全规则 │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 实现方式：安全扫描工具、权限系统 │ │
│ │ 示例：SQL注入检测、XSS防护、敏感数据脱敏 │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ 第 2 层：代码规范 │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 实现方式：Linter、Formatter、静态分析 │ │
│ │ 示例：ESLint、Prettier、SonarQube │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ 第 1 层：架构约束（最底层） │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 实现方式：项目模板、脚手架、目录监控 │ │
│ │ 示例：必须按目录结构存放文件，禁止使用某些库 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ 下层约束更基础，上层约束更贴近业务 │
│ 下层约束失败，上层约束无需检查 │
│ │
└─────────────────────────────────────────────────────────┘
6.2 约束配置示例
yaml
复制
# constraints.yaml
architecture:
# 项目结构约束
directory_structure:
required:
- src/
- components/
- utils/
- services/
- tests/
- unit/
- integration/
- docs/
forbidden:
- node_modules/ # 不允许直接提交
- .env # 不允许提交敏感配置
# 技术栈约束
tech_stack:
allowed_languages:
- typescript
- javascript
allowed_frameworks:
- react
- express
forbidden_libraries:
- jquery # 过时库
- lodash # 推荐用原生替代
code_quality:
# 代码复杂度约束
complexity:
max_cyclomatic_complexity: 10
max_cognitive_complexity: 15
max_function_length: 50_lines
# 命名约束
naming:
components: PascalCase
functions: camelCase
constants: UPPER_SNAKE_CASE
# 测试约束
testing:
min_coverage: 80
require_tests_for:
- utils/
- services/
forbidden_patterns:
- "it.skip"
- "describe.skip"
security:
# 输入验证
input_validation:
require_validation: true
allowed_schemas: schemas/
# 敏感数据
sensitive_data:
forbidden_in_code:
- api_keys
- passwords
- tokens
storage: environment_variables
# 依赖安全
dependencies:
scan_vulnerabilities: true
max_severity: medium
auto_update_patch: true
七、监控反馈层设计
7.1 监控指标体系
┌─────────────────────────────────────────────────────────┐
│ 监控指标体系 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 业务指标 │ │
│ │ • 任务成功率：完成任务数 / 总任务数 │ │
│ │ • 任务完成时间：从提交到完成的耗时 │ │
│ │ • 代码质量评分：综合质量指标 │ │
│ │ • 人工介入率：需要人工介入的任务比例 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 系统指标 │ │
│ │ • 资源利用率：CPU、内存、磁盘使用率 │ │
│ │ • 并发任务数：同时运行的任务数量 │ │
│ │ • 队列等待时间：任务在队列中的等待时间 │ │
│ │ • 错误率：各类错误的发生频率 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 质量指标 │ │
│ │ • 测试通过率：各类测试的通过情况 │ │
│ │ • 代码覆盖率：测试覆盖的代码比例 │ │
│ │ • 安全漏洞数：发现的安全问题数量 │ │
│ │ • 技术债务：代码异味、重复代码等指标 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 效率指标 │ │
│ │ • 迭代次数：完成任务需要的反馈循环次数 │ │
│ │ • 修复成功率：自动修复的成功比例 │ │
│ │ • 复用率：Harness 组件的复用情况 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
7.2 监控架构
┌─────────────────────────────────────────────────────────┐
│ 监控架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ Agent 执行 │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 数据采集 │ │
│ │ • 日志收集（结构化日志） │ │
│ │ • 指标采集（Prometheus） │ │
│ │ • 链路追踪（OpenTelemetry） │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 数据存储 │ │
│ │ • 时序数据库（InfluxDB） │ │
│ │ • 日志存储（Elasticsearch） │ │
│ │ • 事件存储（ClickHouse） │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 分析处理 │ │
│ │ • 实时分析（Flink） │ │
│ │ • 批量分析（Spark） │ │
│ │ • 异常检测（机器学习） │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 可视化与告警 │ │
│ │ • 仪表盘（Grafana） │ │
│ │ • 告警系统（PagerDuty） │ │
│ │ • 报告生成（定期/按需） │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
八、完整示例：一个 Web 项目的 Harness 设计
8.1 项目背景
- 类型：React + Node.js 全栈 Web 应用
- 规模：中型项目，预期代码量 5-10 万行
- 团队：3-5 名工程师 + AI Agent
8.2 Harness 架构设计
┌─────────────────────────────────────────────────────────┐
│ Web 项目 Harness 架构 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 基础设施（Kubernetes） │ │
│ │ • Namespace: project-harness │ │
│ │ • Resources: 4 CPU / 8 GB per Agent │ │
│ │ • Storage: 50 GB SSD │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 容器镜像（Node 18 + 工具链） │ │
│ │ • Base: node:18-alpine │ │
│ │ • Tools: git, eslint, jest, vite │ │
│ │ • Config: .npmrc, .gitconfig │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 代码仓库（Git + GitHub） │ │
│ │ • Branches: main, develop, feature/* │ │
│ │ • Protection: require PR, require review │ │
│ │ • Hooks: pre-commit lint, pre-push test │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 约束规则（YAML 配置） │ │
│ │ • architecture.yaml: 项目结构、技术栈 │ │
│ │ • code-quality.yaml: 复杂度、覆盖率 │ │
│ │ • security.yaml: 扫描规则、敏感数据 │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 反馈回路（自动化） │ │
│ │ • CI Pipeline: GitHub Actions │ │
│ │ • Tests: Unit + Integration + E2E │ │
│ │ • Quality: ESLint + SonarQube │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 控制平面（自研/开源） │ │
│ │ • Task Scheduler: 任务队列、优先级 │ │
│ │ • State Manager: 检查点、恢复 │ │
│ │ • Monitor: Prometheus + Grafana │ │
│ └─────────────────────────────────────────────────┘ │
│ ↑ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ AI Agent（Codex/Claude） │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
8.3 关键配置文件
yaml
复制
# harness.yaml - 主配置
project:
name: web-app-harness
type: fullstack
version: 1.0.0
infrastructure:
platform: kubernetes
resources:
cpu: 4
memory: 8Gi
storage: 50Gi
scaling:
min_agents: 1
max_agents: 5
environment:
base_image: node:18-alpine
tools:
- git@2.40
- npm@9
- eslint@8
- jest@29
- vite@4
env_vars:
NODE_ENV: development
CI: true
repository:
type: git
provider: github
url: https://github.com/org/web-app
branches:
main:
protection: true
require_review: true
develop:
protection: true
feature/*:
protection: false
constraints:
config_files:
- constraints/architecture.yaml
- constraints/code-quality.yaml
- constraints/security.yaml
enforcement: strict # strict / warn / off
feedback:
pipeline:
- stage: lint
tools: [eslint, prettier]
fail_fast: true
- stage: test
tools: [jest]
coverage_threshold: 80
- stage: build
tools: [vite]
- stage: e2e
tools: [cypress]
condition: on_main_branch
control:
scheduler:
queue_type: priority
max_concurrent: 3
state:
checkpoint_interval: 5m
retention: 30d
monitoring:
metrics: [task_success_rate, execution_time, resource_usage]
alerts:
- condition: success_rate < 80%
channel: slack
severity: warning
- condition: success_rate < 50%
channel: pagerduty
severity: critical
human_in_the_loop:
require_approval:
- production_deploy
- database_migration
- api_breaking_change
九、设计原则与最佳实践
9.1 核心设计原则
原则
说明
实践建议
分层设计
每层职责清晰，层间依赖明确
基础设施 → 工具链 → 数据 → 约束 → 监控
配置即代码
所有配置版本化、可审计
使用 YAML/JSON，Git 管理
渐进增强
从简单开始，逐步完善
先跑通基本流程，再添加复杂约束
可观测性优先
一切行为可监控、可追踪
日志、指标、链路追踪全覆盖
安全内建
安全不是附加，而是基础
从设计之初就考虑安全约束
9.2 常见陷阱
陷阱
表现
解决方案
过度设计
约束太复杂，Agent 无法工作
从简单约束开始，逐步迭代
监控盲区
关键指标缺失，问题发现晚
建立完整的监控指标体系
资源不足
Agent 运行缓慢或失败
合理规划资源，支持动态扩展
工具版本混乱
不同 Agent 使用不同版本工具
标准化工具链，容器化环境
反馈延迟
测试执行慢，迭代效率低
分层反馈，快速失败
十、结语：环境即生产力
在 Harness Engineering 中，环境不仅仅是 Agent 运行的容器，更是决定 Agent 产出质量的关键因素。
设计优秀的执行环境，就是设计生产力本身。
一个好的 Harness 环境能够：
- 让 Agent 在正确的轨道上高效工作
- 通过约束和反馈持续提升产出质量
- 通过监控和控制确保过程可控可靠
- 通过标准化和自动化实现规模化产出
掌握 Agent 执行环境的设计，是成为优秀 Harness Engineer 的核心能力。
参考与延伸阅读
- Harness engineering: leveraging Codex in an agent-first world - OpenAI
- Kubernetes Patterns - 容器编排设计模式
- Observability Engineering - 可观测性工程
