> 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/01_harness_intro/1.5_miniharness_intro.md).

# 1.5 MiniHarness 项目介绍

本节介绍 MiniHarness 项目的设计目标、快速开始方式、核心组件、代码结构和使用指南，帮助读者快速上手这个配套实战项目。

## 1.5.1 项目目标

MiniHarness 是本书的配套实战项目，目的是帮助读者从零开始构建一个完整、可运行的 Harness 系统原型。

其设计原则是：

* **最小完整**：包含一个生产级 Harness 系统的所有核心概念和模块，但去掉了不必要的复杂性和优化
* **教学友好**：代码简洁、注释充分，易于理解和修改
* **易于扩展**：架构清晰，便于添加新的子系统或替换实现

通过 MiniHarness，读者可以：

1. 理解 Harness 的各个子系统如何协作
2. 学习如何设计和实现工具调用、权限管理、记忆系统等核心组件
3. 有一个真实的基础代码，可以在此基础上构建生产应用

## 1.5.2 快速开始

按以下步骤快速搭建和运行 miniharness：

```bash
# 克隆或下载项目
git clone https://github.com/yeasy/harness_engineering_guide
cd harness_engineering_guide/lab

# 创建虚拟环境
python3.11 -m venv venv
source venv/bin/activate  # 在Windows上: venv\Scripts\activate

# 安装依赖
pip install -e ".[dev]"

# 配置示例模型密钥（真实值不要提交到仓库）
cp .env.example .env
# 编辑 .env，填入 LLM_API_KEY 或对应 provider 的密钥

# 运行基本测试
pytest tests/unit/test_core.py -v

# 尝试示例
python examples/simple_agent.py
```

## 1.5.3 技术栈

MiniHarness 使用 Python 3.11+，选择的原因包括：

(1) **Python 的优势**

* 生态完整：包含 asyncio、httpx、pydantic 等优秀库
* 语法清晰：代码易读易懂，适合教学
* 模型集成：大多数 LLM SDK 都提供 Python 版本
* 数据科学友好：便于后续集成向量数据库、指标收集等

(2) **核心依赖**

| 包               | 用途         | 选择理由               |
| --------------- | ---------- | ------------------ |
| `pydantic>=2.0` | 数据验证和序列化   | 类型安全、自动验证、JSON 序列化 |
| `httpx`         | HTTP 客户端   | 同时支持同步和异步          |
| `asyncio`       | 异步编程       | Python 标准库，充分满足需求  |
| `python-dotenv` | 环境变量管理     | 安全管理 API 密钥        |
| `anthropic`     | Claude API | 作为示例 LLM 集成        |
| `openai`        | OpenAI API | 作为多模型 provider 示例  |
| `pyyaml`        | YAML 解析    | 配置文件和示例数据读取        |

(3) **开发依赖**

```python
pytest>=7.0          # 单元测试
pytest-asyncio       # 异步测试
black               # 代码格式化
pylint              # 代码质量检查
mypy                # 类型检查
```

## 1.5.4 项目结构规划

miniharness 项目的目录结构如下所示：

* **lab/**
  * pyproject.toml - 项目配置和依赖
  * README.md - 项目说明
  * .env.example - 环境变量示例
  * **mini\_harness/** - 源代码目录
    * **init**.py
    * **core/** - 核心接口定义
      * **init**.py
      * agent.py - 智能体基础类
      * message.py - 消息类型定义
      * tool.py - 工具接口
      * event.py - 事件定义
    * **runtime/** - 运行时引擎
      * **init**.py
      * engine.py - 智能体执行循环
      * events.py - 运行时事件
      * models.py - 运行时数据模型
    * **tools/** - 工具实现
      * **init**.py
      * registry.py - 工具注册表
      * builtin.py - 内置工具示例
    * **memory/** - 记忆子系统
      * **init**.py
      * storage.py - 记忆存储
      * context.py - 上下文组装
      * consolidation.py - 记忆整合
    * **models/** - 模型集成
      * **init**.py
      * provider.py - 模型提供者(Claude/OpenAI)
      * parser.py - 响应解析
      * quality.py - 输出质量门控
    * **orchestration/** - 任务编排
      * **init**.py
      * engine.py - 编排引擎与状态机
    * **mcp/** - MCP 协议集成
      * **init**.py
      * integration.py - MCP 工具注册与适配
    * **reliability/** - 可靠性与可观测性
      * **init**.py
      * tracing.py - 链路追踪
      * monitoring.py - 监控指标收集
      * logging.py - 日志记录
      * resilience.py - 容错与重试机制
    * **security/** - 安全防护
      * **init**.py
      * permissions.py - 权限决策引擎
      * path\_validator.py - 路径校验与标准化
      * guardrails.py - 危险操作检测
      * secure\_executor.py - 安全执行器
    * **utils/** - 工具函数
      * **init**.py
      * config.py
  * **tests/** - 测试目录
    * **init**.py
    * **unit/** - 单元测试
      * test\_core.py
      * test\_tools.py
      * test\_memory.py
      * test\_models.py
      * test\_orchestration.py
      * test\_mcp.py
    * **integration/** - 集成测试
      * test\_runtime.py
  * **examples/** - 使用示例
    * simple\_agent.py - 最简单的智能体

## 1.5.5 最终效果预览

完成第 2 章后，MiniHarness 将具备以下能力：

### 基础智能体

一个简单的智能体可以：

```mermaid
flowchart TD
    A["<b>用户输入</b><br/>What's the weather in Beijing?"] --> B["<b>智能体推理</b><br/>需要调用weather工具"]
    B --> C["<b>Harness权限检查</b><br/>该智能体有权限调用此工具"]
    C --> D["<b>工具执行</b><br/>调用weather API"]
    D --> E["<b>结果返回</b><br/>返回天气信息给智能体"]
    E --> F["<b>智能体继续推理</b><br/>格式化结果,返回给用户"]
    F --> G["<b>输出</b><br/>The weather in Beijing is sunny, 25°C"]

    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#ffebee
    style D fill:#e8f5e9
    style E fill:#f3e5f5
    style F fill:#fff3e0
    style G fill:#e3f2fd
```

### 完整的执行流程

以下是一个完整的 miniharness 执行示例：

```python
import asyncio
from mini_harness.runtime.engine import RuntimeEngine
from mini_harness.tools.registry import ToolRegistry
from mini_harness.tools.builtin import BashTool, FileReadTool, FileWriteTool

async def main():
    # 1. 构建工具注册表并注册内置工具
    registry = ToolRegistry()
    registry.register(BashTool())
    registry.register(FileReadTool())
    registry.register(FileWriteTool())

    # 2. 创建运行时引擎（内置推理桩，便于本地试跑）
    engine = RuntimeEngine(tool_registry=registry)

    # 3. 运行并消费事件流：engine.run 返回 AsyncIterator[Event]
    async for event in engine.run("帮我运行 bash 打印 Hello from MiniHarness"):
        safe_keys = {"turn_number", "tool_name", "is_error", "content_length"}
        safe_metadata = {k: v for k, v in event.metadata.items() if k in safe_keys}
        print(f"[{event.__class__.__name__}] {safe_metadata}")

if __name__ == "__main__":
    asyncio.run(main())
```

> 说明：仓库内置的 `RuntimeEngine._infer` 是示教用的推理桩；接入真实 Claude/OpenAI 提供方参见第 7 章的 `mini_harness.models` 模块。

## 1.5.6 代码示例：项目结构验证

项目初始化后，可以通过以下代码验证安装：

```python
# test_setup.py
import asyncio
from mini_harness.core import Message, MessageType, MessageRole
from mini_harness.tools import ToolRegistry

async def test_basic_setup():
    """验证基本设置"""

    # 测试消息类型
    msg = Message(
        role=MessageRole.USER,
        type=MessageType.TEXT,
        content="Hello, Agent"
    )
    assert msg.role == MessageRole.USER
    assert msg.content == "Hello, Agent"

    # 测试工具注册表
    registry = ToolRegistry()
    assert len(registry.list_tools()) == 0  # 初始为空

    print("Setup verification passed!")

if __name__ == "__main__":
    asyncio.run(test_basic_setup())
```

## 1.5.7 学习路线

MiniHarness 在各章中的发展路线：

**第 1 章**：项目规划和初始化

* 建立项目结构
* 定义核心接口

**第 2 章**：实现基础脚手架

* 消息系统
* 运行时引擎的基本循环
* 工具注册表

**第 3 章**：设计原则的代码演示

* 权限决策、结果验证、审计日志的原则级示例
* （完整的安全、可靠性子系统分别在第 12 章、第 11 章落地，见 2.5 节的模块-章节对照表）

**第 4 章及后续**：逐步完善各子系统

* 完整的工具执行流程
* 记忆管理系统
* 模型集成优化
* 可观测性基础设施

## 1.5.8 如何使用本项目

本小节覆盖快速开始指南、自定义扩展方法和相关学习资源。

### 自定义和扩展

MiniHarness 的设计允许灵活的自定义：

```python
# 示例:注册自定义工具
from typing import Any, Dict

from mini_harness.core import Tool, ToolResult
from mini_harness.tools import ToolRegistry

class CustomTool(Tool):
    """自定义工具实现 —— Tool 是抽象基类，子类实现 4 个抽象方法"""

    def name(self) -> str:
        return "custom_operation"

    def description(self) -> str:
        return "执行自定义操作"

    def input_schema(self) -> Dict[str, Any]:
        return {
            "type": "object",
            "properties": {"param": {"type": "string"}},
            "required": ["param"],
        }

    async def call(self, params: Dict[str, Any]) -> ToolResult:
        param = params["param"]
        # 自定义逻辑
        return ToolResult(
            success=True,
            content=f"Custom result for {param}",
            execution_time=0.0,
        )

# 注册工具
registry = ToolRegistry()
registry.register(CustomTool())
```

## 1.5.9 相关资源

* **完整源代码**：随书提供，也可在 GitHub 仓库获取
* **代码索引**：见 [附录 MiniHarness 代码索引](/harness_engineering_guide/fu-lu/appendix/miniharness_index.md)
* **示例应用**：examples/目录包含真实场景的使用案例
* **运行说明**：见 `lab/README.md` 中的安装、测试和常见运行约束

通过 MiniHarness 项目的逐步构建，读者将逐步理解 Harness 工程的各个方面，并最终掌握构建生产级 AI Agent 系统的能力。