# 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章**：添加设计原则的实现

* 权限管理系统
* 结果验证机制
* 审计日志

**第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系统的能力。


---

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