1.5 MiniHarness 项目介绍

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

1.5.1 项目目标

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

其设计原则是：

• 最小完整：包含一个生产级 Harness 系统的所有核心概念和模块，但去掉了不必要的复杂性和优化

• 教学友好：代码简洁、注释充分，易于理解和修改

• 易于扩展：架构清晰，便于添加新的子系统或替换实现

通过 MiniHarness，读者可以：

1. 理解 Harness 的各个子系统如何协作

2. 学习如何设计和实现工具调用、权限管理、记忆系统等核心组件

3. 有一个真实的基础代码，可以在此基础上构建生产应用

1.5.2 快速开始

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

# 克隆或下载项目
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) 开发依赖

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 将具备以下能力：

基础智能体

一个简单的智能体可以：

完整的执行流程

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

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 代码示例：项目结构验证

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

# 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 的设计允许灵活的自定义：

# 示例:注册自定义工具
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 代码索引

• 示例应用：examples/目录包含真实场景的使用案例

• 运行说明：见 lab/README.md 中的安装、测试和常见运行约束

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