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

# 2.5 MiniHarness脚手架搭建

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

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

## 2.5.1 项目结构设计

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

| 目录               | 对应子系统    | 职责                    | 首次实现章节 |
| ---------------- | -------- | --------------------- | ------ |
| `core/`          | 公共基础     | 消息、工具、智能体、事件的接口定义     | 本章     |
| `runtime/`       | 运行时引擎    | 智能体循环、流式处理、事件驱动       | 第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`，是因为核心消息需要轻量和灵活——在 智能体循环中每秒可能创建数百个 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 集成 → 生产化加固 → 可靠性保障 → 安全层 → 测试验收。