Harness 架构实战指南

一、什么是 Harness？

Harness 不是 Agent 框架，也不是 RAG，它是一种让 LLM 驱动复杂工作流、自动完成质量闭环的工程架构模式。

最简洁的定义：

Harness = LLM 导演 + 工具集 + 质量门禁 + 持久状态 + 长期记忆

它解决的核心问题：把"需要反复试错、人工判断质量"的工作流，变成可以自动运行、自动迭代、达标才输出的系统。

二、Harness 的五个核心组件

1. Tools（工具集）

• 所有能力封装成工具，LLM 通过 tool_use 调用
• 每个工具有明确的输入/输出 schema（Claude API 格式）
• 工具失败不崩溃，返回 {success: false, error: ...}

2. Context（共享状态）

• job.json 是 LLM 的"工作记忆"，所有工具读写同一份状态
• 原子写入（.tmp → rename），防止崩溃丢数据
• 支持断点续跑：任何时刻中断，重启后从 job.json 恢复

3. Hooks（质量门禁）

• 每次工具执行后自动触发，检测质量问题写入 job.json
• Hook 只做检测和记录，不做修复（修复由 LLM 决定）
• 失败不影响主流程（catch 所有异常）

4. Permissions（权限守卫）

• 防止 LLM 陷入无限循环：每个工具有调用次数上限
• 关键工具设质量门禁：质量分达标才允许调用
• 软拒绝（返回错误消息）而不是硬抛异常

5. Memory（长期记忆）

• 跨 job 积累经验：哪类内容容易出问题、历史平均质量分
• 关键词匹配检索（不用向量），简单有效
• 新 job 启动时自动注入相关历史经验

三、什么项目适合用 Harness？

核心判断标准：这个任务有没有"质量"这个维度，且质量需要反复迭代才能达标？

3.1 适合的特征

3.2 适合用 Harness 的项目类型

内容生产类

• 文章→PPT：结构设计→内容填充→视觉优化
• 数据→报告：数据分析→叙事设计→可视化→格式校验
• 代码→文档：API 解析→文档生成→准确性验证

软件工程类

• 需求→代码：需求分析→设计→实现→测试→修复，循环直到测试通过
• 代码审查：静态分析→LLM 审查→问题分类→修复建议→验证
• 数据库迁移：方案设计→脚本生成→验证→回滚预案

数据处理类

• ETL 管道：数据抽取→清洗→转换→质量检测→问题修复
• 爬虫 + 结构化：爬取→解析→校验→缺失补充→去重
• 批量标注：初始标注→质量抽检→不合格重标→统计验收

运营自动化类

• 营销内容生产：关键词→文案→合规检查→A/B 变体→发布
• 客服知识库维护：问题收集→答案生成→准确性验证→更新
• SEO 优化：内容分析→优化建议→改写→效果预测

3.3 不适合用 Harness 的场景

• 单次查询：用户问一个问题，直接回答，没有迭代需求
• 纯确定性流程：每步都有唯一正确答案，不需要 LLM 判断
• 实时性要求极高：Harness 的 LLM 调用开销不适合毫秒级响应
• 质量完全主观：没有任何客观指标，只能靠人判断

四、Harness vs 其他模式的对比

Harness 的核心价值：把"人工监督的工作流"变成"自动化的质量驱动循环"，LLM 扮演原来"人工审核、判断、修复"的角色。

五、Harness 架构模板

如果你要在新项目里用 Harness，以下是最小可行架构：

目录结构

my_harness/
├── harness/
│   ├── job.py          # 状态管理（必须）
│   ├── loop.py         # Agentic Loop（必须）
│   ├── hooks.py        # 质量门禁（推荐）
│   ├── permissions.py  # 权限守卫（推荐）
│   ├── memory.py       # 长期记忆（可选）
│   └── tools/
│       ├── registry.py # 工具注册表（必须）
│       └── *.py        # 具体工具
└── run_harness.py      # 统一入口

job.json 最小结构

{
  "job_id": "20260403_123456",
  "status": "pending|in_progress|done|failed",
  "created_at": "...",
  "updated_at": "...",
  "input": {},          // 输入数据
  "production": {},     // 生产过程状态
  "quality": {
    "overall_score": null,
    "issues": []
  },
  "artifacts": {}       // 最终输出
}

System Prompt 关键要素

你是[角色]。

你的标准：[具体的质量标准，要量化]

工作流程：
1. [步骤1]
2. [步骤2]
...

硬性约束（必须遵守）：
- [约束1，要量化]
- [约束2，要量化]

规则：
- 每次只调用一个工具，等结果后再决定下一步
- 达到质量目标才输出最终结果

最关键的设计原则

1. 约束必须量化：不说"不要太长"，说"不超过 45 秒"
2. 工具要防御性：假设环境会出问题，返回结构化错误而不是崩溃
3. 状态要持久化：任何时刻中断都能恢复，断点续跑是标配
4. 质量要可测量：每个维度都要有客观的检测方法
5. 失败要可诊断：错误信息要具体，LLM 能根据错误决定下一步