# 2.5 MiniHarness脚手架搭建

本节将前两节的架构设计落地为可运行的代码骨架。完成后，MiniHarness 项目将具备完整的目录结构、依赖配置和核心接口定义，为后续章节的增量开发打下基础。

> 完整代码见 `lab/` 目录，可直接运行。本节聚焦设计决策和关键接口，不重复贴出全部源码。

## 2.5.1 项目结构设计

MiniHarness 的目录结构遵循“按子系统分包”的原则，每个包对应一个 Harness 子系统：

| 目录               | 对应子系统    | 职责                    | 首次实现章节 |
| ---------------- | -------- | --------------------- | ------ |
| `core/`          | 公共基础     | 消息、工具、智能体、事件的接口定义     | 本章     |
| `runtime/`       | 运行时引擎    | Agent 循环、流式处理、事件驱动    | 第4章    |
| `tools/`         | 工具层      | 工具注册、执行流水线、内置工具       | 第5章    |
| `memory/`        | 记忆子系统    | 存储、上下文组装、记忆整合         | 第6章    |
| `models/`        | 模型集成     | Provider 抽象、输出解析、质量门控 | 第7章    |
| `orchestration/` | 编排引擎     | 任务分解、状态机、多智能体协调       | 第8章    |
| `mcp/`           | MCP 集成   | MCP 客户端、工具发现、协议适配     | 第9章    |
| `reliability/`   | 可靠性与可观测性 | 日志、追踪、监控指标、容错机制       | 第11章   |
| `security/`      | 安全防护     | 权限管理、路径校验、护栏、安全执行     | 第12章   |
| `utils/`         | 工具类      | 配置管理等辅助模块             | 本章     |

项目还包含 `tests/`（按 unit/integration 分层）和 `examples/`（使用示例）。

## 2.5.2 依赖配置

MiniHarness 使用 `pyproject.toml` 管理项目元数据和依赖（见 `lab/pyproject.toml`）。当前核心依赖保持在六个小型库：

| 依赖              | 用途                   |
| --------------- | -------------------- |
| `anthropic`     | Claude API 客户端       |
| `openai`        | OpenAI API 客户端       |
| `pydantic`      | 数据校验与序列化             |
| `httpx`         | 异步 HTTP 客户端（MCP 传输等） |
| `python-dotenv` | 环境变量管理               |
| `pyyaml`        | YAML 配置解析            |

开发依赖包括 pytest（测试）、black/isort（格式化）、mypy（类型检查）、pylint（代码分析）。

这种最小依赖策略是有意为之的——作为教学项目，MiniHarness 避免引入重型框架（如 LangChain、LlamaIndex），让读者能看清 Harness 的每一层是如何从零构建的。

## 2.5.3 核心接口定义

`core/` 包定义了四组基础接口，它们是整个系统的公共语言。

### 消息系统(`core/message.py`)

消息是 Harness 中所有组件之间通信的载体。设计要点：

* **角色枚举** (`MessageRole`)：user / assistant / tool / system，与 LLM API 的角色模型对齐
* **类型枚举** (`MessageType`)：text / tool\_call / tool\_result / event，区分不同用途的消息
* **通用消息类** (`Message`)：包含 role、type、content 三个核心字段，加上 message\_id（唯一标识）、parent\_id（消息链追踪）、metadata（扩展信息）
* **特化子类**：`ToolCallMessage` 和 `ToolResultMessage` 通过 metadata 字段提供便捷属性访问

```python
# 核心消息结构(完整代码见 lab/mini_harness/core/message.py)
@dataclass
class Message:
    role: MessageRole
    type: MessageType
    content: str
    message_id: str = field(default_factory=lambda: str(uuid.uuid4()))
    parent_id: Optional[str] = None
    metadata: Dict[str, Any] = field(default_factory=dict)
    timestamp: datetime = field(default_factory=datetime.now)
```

选择 `dataclass` 而非 Pydantic 的 `BaseModel`，是因为核心消息需要轻量和灵活——在 Agent 循环中每秒可能创建数百个 Message 实例，dataclass 的开销更小。

### 工具接口(`core/tool.py`)

工具层的接口设计遵循“定义与实现分离”的原则：

* **`ToolInputSchema`**：描述工具参数的 JSON Schema，与 LLM 的 function calling 格式对齐
* **`ToolDefinition`**：工具的元数据（名称、描述、参数 schema、权限要求、超时时间）
* **`Tool`(ABC)**：抽象基类，子类只需实现 `execute()` 方法

这种分离使得工具注册表可以只持有 `ToolDefinition`（用于向 LLM 描述工具），而不需要加载工具的实际实现——这正是第5章将实现的延迟加载机制的基础。

### 智能体接口(`core/agent.py`)

智能体接口定义了状态机模型：IDLE → INITIALIZING → EXECUTING → COMPLETED / FAILED，以及 PAUSED 状态用于支持人机协同。`ExecutionResult` 封装了执行结果，包括状态、输出和错误信息。

### 事件系统(`core/event.py`)

事件系统为可观测性提供基础。`EventType` 枚举覆盖三类事件：任务生命周期(started/completed/failed)、步骤生命周期、工具执行生命周期，以及权限检查事件。

## 2.5.4 工具注册表

工具注册表(`tools/registry.py`)是工具层的核心数据结构，负责管理所有可用工具的注册、查找和 Schema 缓存。

```python
# 注册表核心接口(完整代码见 lab/mini_harness/tools/registry.py)
class ToolRegistry:
    def register(self, tool: Tool): ...      # 注册工具并缓存 Schema
    def get(self, name: str) -> Tool: ...    # 按名称获取工具
    def list_tools(self) -> List[Dict]: ...  # 返回所有工具的 Schema(供 LLM 使用)
```

注册表在注册时就缓存好工具的 Schema，避免每次 LLM 调用都重新生成——这个看似微小的优化在高频调用场景下非常重要。

## 2.5.5 配置管理

配置管理模块(`utils/config.py`)使用单例模式，从 `.env` 文件和环境变量加载配置。关键配置项包括 API 密钥、模型选择、最大步数和执行超时时间。

项目根目录的 `.env.example` 提供了配置模板，开发者只需复制并填入实际值即可开始使用。

## 2.5.6 验证脚手架

搭建完成后，运行测试来验证基础设施：

```bash
cd lab
pip install -e ".[dev]"
pytest -v
```

测试用例覆盖消息创建与序列化、工具定义与注册、智能体创建等基础功能（见 `lab/tests/unit/test_core.py` 和 `lab/tests/unit/test_tools.py`）。

## 2.5.7 下一步

至此，MiniHarness 已有了坚实的骨架：

* **公共语言** (core/)：消息、工具、智能体、事件的统一接口
* **注册机制** (tools/)：工具的注册与发现
* **配置基础** (utils/)：环境变量驱动的配置管理
* **测试框架** (tests/)：pytest + pytest-asyncio 就绪

从第4章开始，我们将在这个骨架上逐章添加子系统：运行时引擎 → 工具层 → 记忆子系统 → 输出治理 → 编排引擎 → MCP 集成 → 生产化加固 → 可靠性保障 → 安全层 → 测试验收。


---

# 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/02_architecture/2.5_miniharness_scaffold.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.