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 客户端
pydantic	数据校验与序列化
httpx	异步 HTTP 客户端（MCP 传输等）
python-dotenv	环境变量管理

开发依赖包括 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 字段提供便捷属性访问

# 核心消息结构(完整代码见 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 缓存。

# 注册表核心接口(完整代码见 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 验证脚手架

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

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 集成 → 生产化加固 → 可靠性保障 → 安全层 → 测试验收。