> 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/summary.md).

# 本章小结

本章阐述了 Harness 系统的五大设计原则，以下是核心要点的系统回顾。

## 五大设计原则的完整体系

本章介绍了构建生产级 Harness 系统的五大设计原则。这些原则相互补充、形成了一个完整的设计哲学体系：前四项确保系统安全、可靠、可管理，第五项（智能体工学）则确保系统对自主智能体本身“好用”。

```mermaid
graph TD
    A["约束优先"] -->|定义系统的边界| B["可验证性"]
    B -->|确保系统的可观测性| C["渐进信任"]
    C -->|逐步提升系统的权限| D["故障假设"]
    D -->|为不可避免的故障做准备| E["生产级 Harness"]
    F["智能体工学"] -->|让 Harness 对 Agent 好用| E

    style A fill:#ffebee
    style B fill:#fff9c4
    style C fill:#e8f5e9
    style D fill:#e3f2fd
    style F fill:#ede7f6
    style E fill:#f3e5f5
```

## 五大原则的各自职责

### 1. 约束优先

**核心思想**：首先定义 Agent 不能做什么，然后在这个框架内赋予能力。

**关键要素**：

* 权限维度：可以访问哪些资源
* 操作维度：禁止哪些操作
* 时间维度：什么时候允许操作
* 数据维度：什么样的数据可以处理

**实现方法**：

* 白名单（最安全、最严格）
* 黑名单（中等安全、较灵活）
* 规则引擎（可控安全、最灵活）

在实践中，Claude Code 通过 protected files 和 dangerous patterns 实现约束优先，OpenClaw 则通过 SOUL.md 约束文档来定义边界。

### 2. 可验证性

**核心思想**：系统的每一个操作都应该是可观测的、可追踪的、可重放的。

**三个层次**：

1. **操作日志**：记录发生了什么
2. **执行追踪**：记录操作之间的因果关系
3. **可重放性**：给定相同输入，能够重现执行

**关键实现**：

* 结构化日志，便于搜索和分析
* 分布式追踪，显示完整的执行路径
* 执行重放，验证系统一致性

在实践中，Claude Code 通过 OpenTelemetry 配置导出 metrics 和日志事件，并提供默认关闭的 traces beta；OpenClaw 则通过 Lobster 确定性日志实现执行重放。

### 3. 渐进信任

**核心思想**：不要期望一下子完全信任 Agent，而是通过观察和学习逐步提升权限。

**信任梯度** （从低到高）：

1. Manual Only：完全人工操作
2. Approve Always：每步审批
3. Approve Once：任务开始时批准一次
4. Ask First：关键操作事前询问
5. Auto with Notification：自动执行并通知
6. Full Trust：充分信任（罕见）

**提升和降级**：

* 提升需要明确的证据和标准
* 降级可以快速响应问题
* 持续的监控和评估

### 4. 故障假设

**核心思想**：主动假设每一步都可能失败，并提前设计失败处理。

**故障类型和处理**：

* 临时故障 → 重试(Retry)
* 永久故障 → 降级/回退(Fallback)
* 部分故障 → 隔离(Bulkhead)
* 级联故障 → 熔断器(Circuit Breaker)

**关键机制**：

* 指数退避重试，避免羊群效应
* 检查点和事务，支持中间恢复
* 持续监控和告警，快速检测故障

### 5. 智能体工学

**核心思想**：为 Agent（而非人类）设计更好用的软件系统和开发工具，让 Harness 及其工具对自主智能体“好用”——清晰指令、快速反馈、标准化接口。

**三大子原则**：

1. **最小化使用摩擦**：提供统一、结构化、低成本的接口，减少 Agent 在多个系统间的上下文切换
2. **最大化信息密度**：删除冗余与格式开销，提供信息密度最高的表示（如用 Markdown 取代 HTML）
3. **信任模型能力**：用基于风险与合规的约束，替代基于人类工作习惯的约束

**关键实现**：

* 统一的结构化数据/状态/记忆存储，而非碎片化的多套接口
* 一致的工具调用约定与返回格式
* 快速、一致的反馈回路，避免不必要的异步等待

该原则由黄东旭在 QCon 2026 提出，提醒我们 Harness 的“使用者”已从人类转变为自主智能体。

## 五大原则的相互关系

五大原则并非孤立，而是相互支撑的完整体系。前四项（约束优先、可验证性、渐进信任、故障假设）保障系统的安全与可靠，智能体工学则横向作用于前四项的落地方式——让约束、日志、信任评估与容错机制都以 Agent 友好的形式呈现，如下所示：

```mermaid
graph TB
    A["约束优先"]
    B["定义边界"]
    C["约束"]
    D["可验证性"]
    E["审计"]
    F["监控行为"]
    G["渐进信任"]
    H["权限提升"]
    I["有充分证据"]
    J["故障假设"]
    K["设计失败处理"]
    L["快速恢复"]
    M["证据来源"]
    N["智能体工学"]
    O["Agent 友好的呈现形式"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    C --> G
    G --> H
    H -.-> I
    J --> M
    M --> L
    D --> J
    K --> L
    N --> O
    O -.->|低摩擦的约束| A
    O -.->|高密度的日志| D
    O -.->|结构化的证据| G

    style A fill:#ffebee
    style C fill:#fff3e0
    style D fill:#fff9c4
    style G fill:#f0f4c3
    style E fill:#e8f5e9
    style H fill:#e0f2f1
    style N fill:#ede7f6
```

## 实践中的集成应用

这五大原则在实际系统设计中是高度集成的：

**设计一个转账系统**

**约束优先**：定义智能体的权限

```python
permissions = {
    "transfer_money": {
        "max_amount_per_operation": 1000,
        "max_amount_per_day": 10000,
        "requires_approval": "Approve Always"
    }
}
```

**可验证性**：记录每个转账操作

```
Trace ID: trace-2024-04-01-001
Step 1: Check balance
Step 2: Validate transfer
Step 3: Execute transfer
Step 4: Send confirmation
→ 完整的操作日志供后续审计
```

**渐进信任**：根据 Agent 表现逐步提升权限

```
初期:Approve Always(每次转账都需要人工批准)
一周后:Ask First(小额转账自动,大额需要确认)
一月后:Auto with Notification(自动执行并通知用户)
```

**故障假设**：为可能的失败设计处理

```
失败场景1:网络超时 → 重试3次
失败场景2:余额不足 → 报告给用户
失败场景3:外部API宕机 → 使用缓存的汇率
失败场景4:多个转账失败 → 启动熔断器,停止新转账
```

**智能体工学**：让上述约束以 Agent 友好的形式落地

```
约束基于风险而非习惯:小额自动放行,仅超限/可疑交易才触发审批
接口统一:转账、查询、审计都返回相同结构的Result对象
信息高密度:回执用结构化字段而非HTML页面,降低Token与解析成本
```

## 与前两章的关系

本章与前两章的关系和递进逻辑如下：

```mermaid
graph TD
    A["<b>第1章:概论</b><br/>为什么需要Harness？"] --> B["<b>第2章:架构全景</b><br/>Harness的系统设计"]
    B --> C["<b>第3章:设计原则 ← 你在这里</b><br/>如何正确地设计Harness"]

    style A fill:#e8f5e9
    style B fill:#fff9c4
    style C fill:#ffebee,stroke:#c62828,stroke-width:2px
```

## MiniHarness 中应用这些原则

在 MiniHarness 项目中，这些原则的应用包括：

### MiniHarness 中的约束优先

在工具注册表中实现约束优先原则：

```python
# 第2章已经定义了ToolRegistry
# 第3章应该添加权限检查

from mini_harness.security.permissions import PermissionDecisionEngine

class ToolRegistry:
    async def call_tool(self, tool_name, params):
        # 首先检查权限
        if not await permission_manager.check_permission(tool_name):
            raise PermissionError(f"Tool {tool_name} not allowed")

        # 然后执行
        return await self._execute_tool(tool_name, params)
```

### MiniHarness 中的可验证性

通过结构化日志实现可验证性：

```python
# 添加审计日志

from mini_harness.reliability.logging import StructuredLogger

class ToolExecutor:
    async def execute(self, tool_name, params):
        logger.info("Tool execution started", extra={
            "tool_name": tool_name,
            "params": params
        })

        result = await self._execute_tool(tool_name, params)

        logger.info("Tool execution completed", extra={
            "tool_name": tool_name,
            "status": result.status,
            "duration_ms": result.duration
        })

        return result
```

### MiniHarness 中的渐进信任

实现权限等级管理以支持渐进信任：

```python
# 添加权限等级管理

from mini_harness.security.permissions import PermissionLevel

class AgentTrustManager:
    async def update_trust_level(self, agent_id):
        # 评估是否应该提升信任等级
        # 根据agent历史记录调整权限等级
        history = await self.get_agent_history(agent_id)

        # 简化的信任提升逻辑 - 实际实现可更复杂
        if history.success_rate > 0.95:
            new_level = PermissionLevel.AUTO
        else:
            new_level = PermissionLevel.ASK

        current_level = await self.get_agent_level(agent_id)
        if new_level and new_level.value > current_level.value:
            await self.promote_agent(agent_id, new_level)
```

### MiniHarness 中的故障假设

实现容错机制以处理故障场景：

```python
# 添加重试和降级机制

from mini_harness.reliability.resilience import RetryConfig, CircuitBreaker

class ResilientToolExecutor:
    async def execute(self, tool_name, params):
        # 重试配置
        retry_config = RetryConfig(max_attempts=3, initial_delay=1.0)

        try:
            # 使用重试机制执行工具调用
            attempt = 1
            while attempt <= retry_config.max_attempts:
                try:
                    return await self.tool_registry.call_tool(tool_name, params)
                except Exception as e:
                    if not retry_config.should_retry(e):
                        raise
                    if attempt >= retry_config.max_attempts:
                        raise
                    delay = retry_config.calculate_delay(attempt)
                    await asyncio.sleep(delay)
                    attempt += 1
        except Exception as e:
            # 降级到缓存结果或默认值
            cached = self.cached_results.get(tool_name)
            if cached:
                return cached
            return self.default_value_for(tool_name)
```

## 评估清单

在实现一个 Harness 系统时，检查以下清单来确保所有五大原则都被正确应用：

### 约束优先检查清单

* [ ] 明确定义了智能体可以访问的资源
* [ ] 列出了禁止的操作
* [ ] 实现了权限检查机制
* [ ] 定义了时间和数据的约束

### 可验证性检查清单

* [ ] 所有操作都被记录在审计日志中
* [ ] 支持执行追踪（可以看到完整的执行路径）
* [ ] 关键操作可以被重放
* [ ] 提供了人类可读的摘要和机器可读的详细日志

### 渐进信任检查清单

* [ ] 定义了信任等级和升级标准
* [ ] 实现了权限提升评估机制
* [ ] 实现了权限降级触发器
* [ ] 可以可视化信任的演进过程

### 故障假设检查清单

* [ ] 识别了可能的故障类型
* [ ] 为每种故障设计了处理机制
* [ ] 实现了重试、降级、隔离、熔断器等机制
* [ ] 有监控和告警系统，快速检测故障

### 智能体工学检查清单

* [ ] 工具与接口遵循统一的调用约定和返回格式，减少 Agent 的上下文切换
* [ ] 状态、记忆、日志尽量统一在结构化存储中，而非碎片化的多套系统
* [ ] 传递给 Agent 的信息删除了视觉装饰与冗余，信息密度高（如优先 Markdown/JSON 而非 HTML/XML）
* [ ] 约束基于实际风险与合规需求，而非照搬人类工作流习惯
* [ ] Agent 执行操作后能获得快速、一致的反馈

## 常见的误区

### 误区 1：过度约束

**问题**：为了安全起见，给 Agent 几乎没有权限。 **结果**：Agent 无法完成任何有意义的工作。 **解决**：使用渐进信任，逐步扩展权限。

### 误区 2：忽视可验证性

**问题**：为了性能，不记录详细日志。 **结果**：出现问题时无法诊断。 **解决**：记录足够的信息用于调试，但使用异步日志避免性能影响。

### 误区 3：假设不会出现故障

**问题**：认为系统足够可靠，不需要额外的故障处理。 **结果**：小故障导致大事件。 **解决**：主动设计故障处理机制。

### 误区 4：权限一成不变

**问题**：定义权限后，再也不调整。 **结果**：权限要么太宽松（安全问题），要么太严格（效率问题）。 **解决**：根据运行数据定期评估和调整。

## 与业界最佳实践的对齐

这五大原则与业界的系统工程最佳实践高度对齐：

* **约束优先** ↔ “白名单优于黑名单”（安全工程）
* **可验证性** ↔ “日志和追踪”（SRE 最佳实践）
* **渐进信任** ↔ “逐步展开”（DevOps 实践）
* **故障假设** ↔ “混沌工程”（系统可靠性）
* **智能体工学** ↔ “开发者体验/API 优先设计”（面向 Agent 的演进）

## 总结和后续步骤

本章确立了 Harness 系统的五大设计原则。这些原则：

1. **相互补充**：组合在一起，形成了一个完整的安全、可靠、可管理的系统
2. **可操作化**：不是抽象的哲学，而是可以具体实现的工程实践
3. **可度量**：每个原则都有具体的指标可以评估

从第 4 章开始，我们将进入各个子系统的深入实现，而这五大原则将在每个子系统中不断体现。

## 关键概念回顾表

| 原则    | 核心思想           | 关键实现             | 检验标准            |
| ----- | -------------- | ---------------- | --------------- |
| 约束优先  | 限制比赋能更重要       | 权限检查、隔离          | 能清楚回答智能体能做什么    |
| 可验证性  | 每步都可审计         | 日志、追踪、重放         | 能重现任何操作的细节      |
| 渐进信任  | 信任逐步建立         | 权限评估、升降级         | 有明确的升级标准        |
| 故障假设  | 故障总会发生         | 重试、降级、隔离         | 单个故障不会导致系统崩溃    |
| 智能体工学 | 为 Agent 而非人类设计 | 统一接口、高密度信息、风险基约束 | Agent 能低摩擦地使用系统 |

下一章将深入运行时引擎的实现，这些设计原则将在实践中得到充分体现。