深入理解Harness的六层架构 · 每层的职责与设计原则
引言：为什么是六层？
在上一篇中，我们介绍了Harness Engineering的核心公式：
`
Agent = Model + Harness
`
Harness是围绕AI模型构建的所有系统、工具、配置和基础设施。但Harness具体包含什么？
经过OpenAI、Anthropic、LangChain等大厂的实践总结，Harness可以分为六层：
`
┌─────────────────────────────────────┐
│ 6. Observability（可观测性） │
├─────────────────────────────────────┤
│ 5. Eval（评估） │
├─────────────────────────────────────┤
│ 4. Memory（记忆） │
├─────────────────────────────────────┤
│ 3. Tool（工具） │
├─────────────────────────────────────┤
│ 2. Context（上下文） │
├─────────────────────────────────────┤
│ 1. Prompt（提示词） │
└─────────────────────────────────────┘
`
本篇将深入讲解每层的职责、设计原则和实际案例。
第一层：Prompt（提示词）
2.1 职责
Prompt层：告诉AI”做什么”和”怎么做”。
核心问题：
- 任务目标是什么？
- 输出格式是什么？
- 有什么约束条件？
2.2 设计原则
原则1：明确具体
`
❌ 错误：帮我写一篇文章
✅ 正确：写一篇1000字的Python教程，目标读者是初学者，包含代码示例
`
原则2：结构化指令
`markdown
任务
写一个Python函数
要求
- 输入：字符串列表
- 输出：去重后的列表
- 约束：保持原有顺序
示例
输入：[“a”, “b”, “a”, “c”]
输出：[“a”, “b”, “c”]
`
原则3：约束边界
`
注意：
- 不要编造数据
- 不要使用外部库
- 代码必须可运行
`
2.3 常见模式
1. 角色设定
`
你是一个Python专家，擅长写简洁高效的代码。
`
2. 任务分解
`
请按以下步骤完成：
- 分析需求
- 设计算法
- 编写代码
- 添加注释
`
3. 输出格式
`
请按以下格式输出：
`python
# 函数说明
def function_name():
# 实现
`
`
2.4 实际案例
案例：代码审查Prompt
`markdown
角色
你是一个资深Python开发者，负责代码审查。
任务
审查以下代码，找出潜在问题。
审查维度
- 代码风格（PEP 8）
- 性能问题
- 安全漏洞
- 错误处理
输出格式
问题列表
- [行号] 问题描述
- 严重程度：高/中/低
- 建议：如何修复
总体评价
- 代码质量：X/10
- 主要优点：…
- 主要问题：…
`
第二层：Context（上下文）
3.1 职责
Context层：给AI提供完成任务需要的信息。
核心问题：
- 需要哪些背景信息？
- 如何组织这些信息？
- 如何控制上下文长度？
3.2 设计原则
原则1：相关信息优先
`
❌ 错误：把所有文档都塞进去
✅ 正确：只放与当前任务相关的信息
`
原则2：结构化组织
`markdown
项目背景
这是一个Web应用，使用Python Flask框架。
当前任务
修复登录功能的bug。
相关代码
`python
# auth.py
def login(username, password):
# …
`
错误信息
TypeError: login() missing 1 required positional argument
`
原则3：控制长度
- 短上下文：直接放入
- 长上下文：使用RAG检索
- 超长上下文：分块处理
3.3 上下文来源
| 来源 | 说明 | 示例 |
|---|
|——|——|——|
| 用户输入 | 用户的请求和问题 | “修复这个bug” |
|---|---|---|
| 系统信息 | 当前环境和状态 | 操作系统、Python版本 |
| 历史记录 | 之前的对话和操作 | 之前的代码修改 |
| 知识库 | 文档和参考资料 | API文档、代码规范 |
| 外部数据 | 实时获取的信息 | 数据库查询结果 |
3.4 RAG（检索增强生成）
RAG：从知识库中检索相关信息，作为上下文提供给AI。
流程：
`
用户问题 → 检索相关文档 → 组装上下文 → AI生成答案
`
示例：
`python
def rag_query(question):
# 1. 检索相关文档
docs = vector_store.search(question, top_k=3)
# 2. 组装上下文
context = “nn”.join([doc.content for doc in docs])
# 3. 生成答案
prompt = f”””
根据以下参考资料回答问题：
参考资料：
{context}
问题：{question}
“””
return llm.generate(prompt)
`
3.5 实际案例
案例：代码助手的上下文设计
`python
class CodeAssistantContext:
def build_context(self, user_request):
context = {
# 1. 用户请求
“request”: user_request,
# 2. 当前文件
“current_file”: self.get_current_file(),
# 3. 相关文件
“related_files”: self.find_related_files(user_request),
# 4. 项目结构
“project_structure”: self.get_project_structure(),
# 5. 代码规范
“coding_standards”: self.get_coding_standards(),
# 6. 历史修改
“recent_changes”: self.get_recent_changes()
}
return self.format_context(context)
`
第三层：Tool（工具）
4.1 职责
Tool层：给AI提供执行任务的能力。
核心问题：
- AI需要哪些能力？
- 如何调用这些能力？
- 如何处理调用结果？
4.2 设计原则
原则1：明确工具职责
`python
# ✅ 好的设计：每个工具做一件事
@tool
def read_file(path: str) -> str:
“””读取文件内容”””
pass
@tool
def write_file(path: str, content: str) -> bool:
“””写入文件内容”””
pass
# ❌ 坏的设计：一个工具做太多事
@tool
def manage_file(action: str, path: str, content: str = None):
“””管理文件（读取、写入、删除）”””
pass
`
原则2：清晰的接口定义
`python
@tool
def search_web(query: str, num_results: int = 5) -> list:
“””
搜索网络信息
Args:
query: 搜索关键词
num_results: 返回结果数量，默认5
Returns:
搜索结果列表，每个结果包含title和url
Example:
>>> search_web(“Python教程”, 3)
[{“title”: “…”, “url”: “…”}, …]
“””
pass
`
原则3：错误处理
`python
@tool
def read_file(path: str) -> str:
“””读取文件内容”””
try:
with open(path, ‘r’) as f:
return f.read()
except FileNotFoundError:
return f”错误：文件 {path} 不存在”
except PermissionError:
return f”错误：没有权限读取文件 {path}”
`
4.3 工具类型
| 类型 | 说明 | 示例 |
|---|
|——|——|——|
| 文件操作 | 读写文件 | read_file, write_file |
|---|---|---|
| 代码执行 | 运行代码 | run_python, run_shell |
| 网络请求 | 调用API | http_get, http_post |
| 数据库 | 查询数据 | sql_query, redis_get |
| 搜索 | 检索信息 | search_web, search_docs |
| 计算 | 数学运算 | calculate, statistics |
4.4 MCP（Model Context Protocol）
MCP：Anthropic提出的标准化工具调用协议。
核心思想：统一AI调用外部工具的接口。
MCP架构：
`
AI模型 ←→ MCP客户端 ←→ MCP服务器 ←→ 外部工具
`
MCP示例：
`json
{
“name”: “read_file”,
“description”: “读取文件内容”,
“inputSchema”: {
“type”: “object”,
“properties”: {
“path”: {
“type”: “string”,
“description”: “文件路径”
}
},
“required”: [“path”]
}
}
`
4.5 实际案例
案例：代码助手的工具设计
`python
class CodeAssistantTools:
def __init__(self):
self.tools = {
“read_file”: self.read_file,
“write_file”: self.write_file,
“run_code”: self.run_code,
“search_code”: self.search_code,
“git_status”: self.git_status,
“git_commit”: self.git_commit
}
def execute_tool(self, tool_name, **kwargs):
if tool_name not in self.tools:
return f”错误：未知工具 {tool_name}”
try:
return self.toolstool_name
except Exception as e:
return f”错误：{str(e)}”
`
第四层：Memory（记忆）
5.1 职责
Memory层：让AI记住信息，跨越多次对话。
核心问题：
- 记住什么？
- 记多久？
- 如何检索？
5.2 设计原则
原则1：分层存储
`
短期记忆（对话内） → 当前对话的上下文
中期记忆（会话内） → 当前会话的历史
长期记忆（持久化） → 跨会话的知识
`
原则2：结构化存储
`python
memory = {
“user_preferences”: {
“language”: “Python”,
“style”: “简洁”,
“level”: “中级”
},
“project_context”: {
“name”: “my-app”,
“framework”: “Flask”,
“database”: “PostgreSQL”
},
“conversation_history”: [
{“role”: “user”, “content”: “…”},
{“role”: “assistant”, “content”: “…”}
]
}
`
原则3：智能检索
`python
def retrieve_memory(query):
# 1. 搜索相关记忆
relevant = search_memory(query)
# 2. 按相关性排序
ranked = rank_by_relevance(relevant, query)
# 3. 返回top-k
return ranked[:5]
`
5.3 记忆类型
| 类型 | 说明 | 存储方式 | 示例 |
|---|
|——|——|———-|——|
| 工作记忆 | 当前任务的状态 | 内存 | 当前变量值 |
|---|---|---|---|
| 情景记忆 | 具体事件和经历 | 数据库 | 上次对话内容 |
| 语义记忆 | 知识和概念 | 向量数据库 | Python语法 |
| 程序记忆 | 技能和方法 | 代码 | 如何写函数 |
5.4 向量数据库
向量数据库：存储和检索语义相似的信息。
工作流程：
`
文本 → Embedding → 向量 → 存储 → 检索 → 相似度计算 → 返回结果
`
常用向量数据库：
- Chroma（轻量级）
- Pinecone（云服务）
- Weaviate（开源）
- Milvus（高性能）
5.5 实际案例
案例：代码助手的记忆系统
`python
class CodeAssistantMemory:
def __init__(self):
self.short_term = {} # 当前对话
self.long_term = VectorDB() # 持久化存储
def remember(self, key, value, persist=False):
“””存储记忆”””
self.short_term[key] = value
if persist:
self.long_term.store(key, value)
def recall(self, query):
“””检索记忆”””
# 1. 先查短期记忆
if query in self.short_term:
return self.short_term[query]
# 2. 再查长期记忆
results = self.long_term.search(query)
if results:
return results[0]
return None
def forget(self, key):
“””删除记忆”””
if key in self.short_term:
del self.short_term[key]
`
第五层：Eval（评估）
6.1 职责
Eval层：检查AI的输出是否符合预期。
核心问题：
- 如何定义”好”？
- 如何自动评估？
- 如何持续改进？
6.2 设计原则
原则1：多维度评估
`python
evaluation = {
“correctness”: 0.9, # 正确性
“completeness”: 0.8, # 完整性
“quality”: 0.85, # 质量
“efficiency”: 0.7, # 效率
“safety”: 1.0 # 安全性
}
`
原则2：自动化测试
`python
def evaluate_code(code):
results = {
“syntax_check”: check_syntax(code),
“style_check”: check_style(code),
“test_results”: run_tests(code),
“performance”: measure_performance(code)
}
return results
`
原则3：持续改进
`
评估 → 发现问题 → 改进Prompt/Context/Tool → 再评估
`
6.3 评估方法
| 方法 | 说明 | 适用场景 |
|---|
|——|——|———-|
| 规则检查 | 用规则验证输出 | 格式、语法检查 |
|---|---|---|
| 自动化测试 | 运行测试用例 | 代码功能测试 |
| LLM评估 | 用AI评估AI | 内容质量评估 |
| 人工抽查 | 人工验证 | 高风险任务 |
| A/B测试 | 对比不同方案 | 优化选择 |
6.4 评估指标
代码评估：
- 测试通过率
- 代码覆盖率
- 性能指标
- 安全漏洞数
内容评估：
- 准确性
- 完整性
- 可读性
- 原创性
对话评估：
- 回答准确率
- 用户满意度
- 响应时间
- 解决率
6.5 实际案例
案例：代码助手的评估系统
`python
class CodeAssistantEval:
def evaluate(self, code, requirements):
results = {}
# 1. 语法检查
results[“syntax”] = self.check_syntax(code)
# 2. 测试执行
results[“tests”] = self.run_tests(code)
# 3. 代码风格
results[“style”] = self.check_style(code)
# 4. 性能分析
results[“performance”] = self.analyze_performance(code)
# 5. 安全扫描
results[“security”] = self.scan_security(code)
# 6. 计算总分
results[“total_score”] = self.calculate_score(results)
return results
def calculate_score(self, results):
weights = {
“syntax”: 0.2,
“tests”: 0.3,
“style”: 0.1,
“performance”: 0.2,
“security”: 0.2
}
score = 0
for key, weight in weights.items():
score += results[key].get(“score”, 0) * weight
return score
`
第六层：Observability（可观测性）
7.1 职责
Observability层：监控和调试整个系统。
核心问题：
- 系统运行状态如何？
- 问题出在哪里？
- 如何优化性能？
7.2 设计原则
原则1：全链路追踪
`
用户请求 → Prompt → Context → Model → Tool → 结果
↓ ↓ ↓ ↓ ↓ ↓
trace trace trace trace trace trace
`
原则2：结构化日志
`python
log = {
“timestamp”: “2026-06-25T10:00:00Z”,
“trace_id”: “abc123”,
“span_id”: “span456”,
“operation”: “generate_code”,
“input”: {“prompt”: “…”, “context”: “…”},
“output”: {“code”: “…”},
“metrics”: {
“latency_ms”: 1500,
“tokens_used”: 500,
“cost_usd”: 0.01
}
}
`
原则3：实时告警
`python
alerts = [
{
“condition”: “latency > 5000ms”,
“action”: “notify_oncall”
},
{
“condition”: “error_rate > 10%”,
“action”: “rollback”
}
]
`
7.3 可观测性三支柱
| 支柱 | 说明 | 工具 |
|---|
|——|——|——|
| 日志（Logs） | 记录事件和错误 | ELK, Loki |
|---|---|---|
| 指标（Metrics） | 量化性能数据 | Prometheus, Grafana |
| 追踪（Traces） | 追踪请求链路 | Jaeger, Zipkin |
7.4 关键指标
性能指标：
- 响应时间（Latency）
- 吞吐量（Throughput）
- 错误率（Error Rate）
成本指标：
- Token使用量
- API调用次数
- 计算资源消耗
质量指标：
- 用户满意度
- 任务完成率
- 结果准确率
7.5 实际案例
案例：代码助手的监控系统
`python
class CodeAssistantObservability:
def __init__(self):
self.logger = Logger()
self.metrics = Metrics()
self.tracer = Tracer()
def trace_operation(self, operation_name):
“””追踪操作”””
def decorator(func):
def wrapper(*args, **kwargs):
# 开始追踪
span = self.tracer.start_span(operation_name)
try:
# 执行操作
result = func(*args, **kwargs)
# 记录成功
span.set_status(“OK”)
self.metrics.increment(f”{operation_name}.success”)
return result
except Exception as e:
# 记录失败
span.set_status(“ERROR”)
span.set_attribute(“error”, str(e))
self.metrics.increment(f”{operation_name}.error”)
raise
finally:
# 结束追踪
span.end()
return wrapper
return decorator
def record_metrics(self, operation, metrics):
“””记录指标”””
self.metrics.record(operation, metrics)
# 检查告警
self.check_alerts(operation, metrics)
`
层与层的关系
8.1 数据流
`
用户请求
↓
[1. Prompt] → 明确任务和约束
↓
[2. Context] → 提供相关信息
↓
[3. Tool] → 调用外部能力
↓
[4. Memory] → 检索历史记忆
↓
[Model] → AI模型处理
↓
[5. Eval] → 评估输出质量
↓
[6. Observability] → 记录和监控
↓
返回结果
`
8.2 依赖关系
`
Observability ← 依赖所有层
↑
Eval ← 依赖Prompt、Context、Tool
↑
Memory ← 独立存储
↑
Tool ← 依赖Context
↑
Context ← 依赖Prompt
↑
Prompt ← 基础层
`
8.3 设计顺序
推荐设计顺序：
`
- Prompt → 先明确任务
- Context → 再提供信息
- Tool → 然后扩展能力
- Memory → 接着积累知识
- Eval → 之后保证质量
- Observability → 最后监控优化
`
设计模板
9.1 Harness设计模板
`markdown
# Harness设计文档
1. 任务定义（Prompt）
- 任务目标：
- 输出格式：
- 约束条件：
2. 上下文设计（Context）
- 信息来源：
- 组织方式：
- 长度控制：
3. 工具设计（Tool）
- 必需工具：
- 可选工具：
- 接口定义：
4. 记忆设计（Memory）
- 存储内容：
- 存储方式：
- 检索策略：
5. 评估设计（Eval）
- 评估维度：
- 评估方法：
- 质量标准：
6. 监控设计（Observability）
- 监控指标：
- 告警规则：
- 日志格式：
`
下一讲预告
下一讲：《AI PRO·Harness Day 3：Prompt层设计》
我们将深入讲解：
- Prompt Engineering的演进
- 高级Prompt技巧
- Prompt模板设计
- 实际案例分析
参考资料
官方文档
中文资料
💡 一句话总结：六层架构是Harness Engineering的核心框架，理解每层的职责是设计好Harness的基础。
发表回复