# 3.5 智能体工学原则

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

## 3.5.1 什么是智能体工学

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

这个概念由TiDB CTO黄东旭在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驱动的时代，这些原则将变得越来越重要。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/harness_engineering_guide/di-yi-bu-fen-harness-gong-cheng-ji-chu/03_principles/3.5_agent_ergonomics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.