> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/harness_engineering_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/harness_engineering_guide/di-yi-bu-fen-harness-gong-cheng-ji-chu/03_principles/3.5_agent_ergonomics.md).

# 3.5 智能体工学原则

本节介绍智能体工学(Agent Ergonomics)的概念，阐述为 Agent 设计更好用的软件系统的三大原则，并讨论这个新兴方向在 Harness 工程中的应用。

## 3.5.1 什么是智能体工学

**智能体工学** 是指：为 Agent（而非人类）设计更好用的软件系统和开发工具的实践。传统的用户体验(UX)设计是以人类用户为中心的，而智能体工学则反转这个视角——我们不再假设使用者是有判断力的人，而是需要清晰指令、快速反馈、标准化接口的自主智能体。

这个概念由黄东旭在 QCon 2026 提出。他指出，当我们进入 Agent 驱动的时代，一个关键的转变是：**基础软件不再给人用，给 Agent 用**。这意味着 Harness 工程的设计原则需要根本转变。

## 3.5.2 智能体工学的三大原则

智能体工学包含三个相互支撑的核心原则：

### 原则 1：最小化使用摩擦 (Minimize Friction)

**含义**：为 Agent 提供统一的、结构化的、低成本的接口，减少 Agent 在多个系统间的切换和上下文切换。

**传统问题**：许多系统给 Agent 留下的是碎片化的接口：

```
Agent需要做什么:
1. 从API A查询数据 → 返回JSON格式
2. 从数据库B查询数据 → 返回结构化行
3. 从日志系统C获取信息 → 返回纯文本日志
4. 调用模型D做推理 → 返回概率分布

结果:Agent每次切换系统都需要:
- 理解新的数据格式
- 学习新的API语法
- 调整请求/响应的解析逻辑
- 维护多个小型的适配层
```

这种碎片化对人类用户来说可能还能忍受（因为我们有灵活的认知能力），但对 Agent 来说就是巨大的摩擦——每次系统切换都是推理成本。

**最佳实践**：

黄东旭提出的解决方案是 **Unified Platform**——将所有的状态、数据、内存、日志都统一到一个结构化的数据库中，而不是让 Agent 在多个“小本本”间切换。

```python
# 反面示例:多个系统间的摩擦
class FragmentedHarness:
    def execute(self, task):
        # Agent需要学习多个接口
        data_api_result = self.data_api.query(task)        # JSON
        db_result = self.database.query(task)              # DataFrame
        log_events = self.log_system.search(task)          # Dict[str, str]
        memory = self.memory_service.retrieve(task)        # Markdown
        
        # Agent需要理解4种不同的数据结构和格式,耗费大量推理成本

# 正面示例:统一的结构化平台
class UnifiedHarness:
    def execute(self, task):
        # 所有数据都从同一个结构化存储获取
        context = self.unified_store.get_context(task)
        # context包含:
        # {
        #   "data": <结构化>,
        #   "memory": <结构化>,
        #   "logs": <结构化>,
        #   "state": <结构化>
        # }
        
        # Agent只需要学习一种结构,大幅降低摩擦
```

摩擦最小化的具体措施包括：

1. **统一的数据存储**：数据库、内存、日志都存储在同一个结构化系统中
2. **一致的接口**：所有工具都遵循相同的调用约定和返回格式
3. **快速的反馈回路**：Agent 执行一个操作，毫秒级获得结果反馈
4. **减少概念切换**：Agent 不需要在“API 模式”和“数据库模式”和“日志模式”间频繁切换

### 原则 2：最大化信息密度 (Maximize Information Density)

**含义**：在传递信息给 Agent 时，每个字节都应该是有意义的。消除冗余、废话、格式开销，提供信息密度最高的表示。

**传统问题**：HTML 是为人类阅读设计的，充满了视觉样式标记，对 Agent 来说大量冗余：

```html
<!-- HTML的信息密度很低 -->
<div class="container">
  <div class="card shadow-lg">
    <div class="card-header">
      <h2 class="text-2xl font-bold">用户信息</h2>
    </div>
    <div class="card-body">
      <p class="text-gray-600">
        <span class="font-semibold">用户名:</span>
        <span id="username">John Doe</span>
      </p>
      <p class="text-gray-600">
        <span class="font-semibold">邮箱:</span>
        <span id="email">john@example.com</span>
      </p>
    </div>
  </div>
</div>
```

而 Markdown 用简洁的格式传递同样的信息，信息密度要高得多：

```markdown
## 用户信息

- **用户名**: John Doe
- **邮箱**: john@example.com
```

相同的信息量，Markdown 只需要 HTML 约 20%的字符数。而对于 Agent 来说，这 20%的字符数意味着：

* 更低的 Token 消耗
* 更快的处理速度
* 更好的理解准确度（信噪比更高）

**信息密度最大化的具体措施**：

1. **使用 Markdown 而非 HTML**：简洁的标记格式取代冗余的视觉标记
2. **避免重复**：不要同时用标题、ID、class 等多个方式表示同一个信息
3. **精简格式**：选择 Agent 友好的格式（YAML/JSON 而非 XML）
4. **删除装饰**：颜色、字体、大小等视觉元素对 Agent 毫无帮助，应删除

### 原则 3：信任模型能力 (Trust Model Capabilities)

**含义**：不要用人类设计的流程规范去限制 Agent。大多数人类工作流对 Agent 来说是不必要的约束。

**传统问题**：许多企业系统仍然遵循人类设计的工作流程：

```
人类工作流:
1. 提交请求 (人工填写表单)
2. 等待审批 (人工等待和思考) 
3. 执行操作 (人工手工操作)
4. 记录结果 (人工填写报告)
```

这些步骤在人类工作中是合理的，因为：

* 人容易出错，所以需要审批
* 人处理速度慢，所以需要队列
* 人注意力有限，所以需要检查清单

但对 Agent 来说，这些约束通常是不必要的开销。

**黄东旭的关键论断**：“99%的人类流程在 Agent 面前是愚蠢的约束。”

这不是说 Agent 不需要任何约束，而是说：**约束应该基于实际的风险和合规需求，而不是基于人类的工作习惯**。

**信任模型的具体实现**：

```python
# 反面:人类工作流约束
class HumanCentricWorkflow:
    def transfer_money(self, amount):
        # 1. 记录意图
        self.log_intent()
        
        # 2. 等待人工审批
        approval = self.request_human_approval()
        
        # 3. 人工执行(实际上由API完成)
        result = self.api.transfer(amount)
        
        # 4. 人工记录日志
        self.log_result(result)
        
        # 整个过程可能需要小时或天

# 正面:Agent友好的约束
class AgentCentricWorkflow:
    def transfer_money(self, amount):
        # 直接执行,但有四层约束:
        
        # 约束1: 权限检查 (基于能力)
        if not self.has_permission("transfer"):
            raise PermissionError()
        
        # 约束2: 风险检查 (基于金额)
        if amount > self.SINGLE_TRANSFER_LIMIT:
            return self.request_approval()  # 只有超限才需要
        
        # 约束3: 合规检查 (基于法规)
        if not self.passes_aml_check(amount):
            return self.quarantine_for_review()
        
        # 约束4: 自动记录 (自动化而非手工)
        result = self.api.transfer(amount)
        self.auto_log_transaction(result)
        
        # 整个过程毫秒完成,而不是小时/天
```

关键区别是：

| 维度       | 人类工作流   | Agent 工作流 |
| -------- | ------- | --------- |
| **约束来源** | 工作习惯、经验 | 风险评估、法规要求 |
| **审批方式** | 人工审批    | 自动化检查     |
| **执行方式** | 人工操作    | API 调用    |
| **记录方式** | 人工填写    | 自动化审计日志   |
| **处理速度** | 分钟/小时   | 毫秒/秒      |

## 3.5.3 智能体工学与 Harness 设计的关系

智能体工学改变了 Harness 设计的许多决策：

**1. 架构设计**

传统的 Harness 通常采用分层设计，各层间通过明确的 API 通信。智能体工学建议：在满足安全隔离的前提下，最大化层间的数据共享和一致性。

```python
# 传统分层架构
# Layer A -> Layer B -> Layer C
# 每层都有自己独立的数据存储和状态

# Agent友好的架构
# 共享的统一状态存储
# Layer A, B, C都访问同一个结构化的记忆/状态系统
```

**2. 接口设计**

智能体工学要求接口的统一性。所有工具、API、内存访问都应该遵循相同的模式。

```python
# Agent友好的接口模式
class AgentTool:
    """所有工具都遵循相同的接口"""
    
    def execute(self, params: Dict) -> Result:
        """
        统一的执行接口
        输入: 结构化的参数字典
        输出: 统一的Result对象
        """
        pass

# 而不是:
class LegacyTool1:
    def do_something(self, x, y, z): ...

class LegacyTool2:
    async def perform_action(self, payload): ...

class LegacyTool3:
    def invoke(self, config, input): ...
```

**3. 数据格式**

智能体工学推荐使用更新的、更紧凑的格式（JSON/YAML）而不是 HTML/XML。

**4. 反馈机制**

快速、一致的反馈是关键。Agent 执行一个操作，应该立即获得结果反馈，而不是等待异步处理。

## 3.5.4 智能体工学的实际案例

### TiDB Zero 的 onboarding 优化

黄东旭在演讲中提到，TiDB Zero（为 Agent 设计的数据库产品）已经实现了智能体工学的几个原则：

**没有账号体系**：

传统的数据库有复杂的账号、权限、审批体系，都是为人类用户设计的。TiDB Zero 去掉了这些，转而采用：

```python
# 简单的API key认证
# Agent只需要:
db = TiDBClient(api_key="xxx")
result = db.query("SELECT ...")
```

不需要人类用户去理解“数据库用户”、“权限角色”、“审批流程”等概念。

**一行代码的 onboarding**：

```python
# 传统数据库的onboarding:
# 1. 创建账号
# 2. 申请权限
# 3. 通过审批
# 4. 获得连接字符串
# 5. 配置客户端
# ... 10多个步骤

# Agent友好的onboarding:
# 贴一段Skill就跑起来
agent.load_skill("tidb_connector.skill")
# 完成！
```

这体现了摩擦最小化原则：从 10 多个步骤简化为一行代码。

### Claude Code 的统一内存系统

Claude Code 的记忆系统体现了信息密度最大化原则：

* 使用 Markdown 格式存储（简洁）
* 所有信息都在同一个 CLAUDE.md 中（统一）
* Agent 可以直接读写（低摩擦）

而不是：

* 分散到多个 JSON 文件
* 使用复杂的数据库 schema
* 需要通过 API 访问

## 3.5.5 智能体工学与安全的平衡

一个常见的疑虑是：如果我们信任 Agent 的能力，不对它施加人类工作流的约束，会不会降低安全性？

答案是：**不一定，取决于约束的设计**。

关键区别是：

| 约束类型        | 目的       | 效果               |
| ----------- | -------- | ---------------- |
| **人类工作流约束** | 补偿人的不可靠性 | 降低 Agent 效率      |
| **风险基约束**   | 防止实际的坏结果 | 保持 Agent 效率 + 安全 |

例如，对一个转账操作的约束：

```python
# 约束1: 人类工作流约束 (不必要)
if operation == "transfer_money":
    require_human_approval()  # 这限制了Agent,但没有降低实际风险

# 约束2: 风险基约束 (必要)
if amount > SINGLE_TRANSFER_LIMIT:
    require_approval()  # 这是基于实际的风险阈值
elif not passes_aml_check(recipient):
    quarantine_for_manual_review()  # 基于合规要求
```

智能体工学的目标是：**用有针对性的、基于风险的约束，替代广泛的、基于人类习惯的约束。** 这样既保证安全，也最大化效率。

## 3.5.6 总结

智能体工学是 Harness 工程的新兴方向，强调三个核心原则：

1. **最小化摩擦**：提供统一、结构化、低成本的接口
2. **最大化信息密度**：删除冗余，提供高密度的信息表示
3. **信任能力**：用基于风险的约束替代基于习惯的约束

这些原则要求我们重新思考系统的设计——不是为人工操作优化，而是为 Agent 的高效、自主执行优化。

当我们进入 Agent 驱动的时代，这些原则将变得越来越重要。