> 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-san-bu-fen-xi-tong-ji-cheng-yu-gong-cheng-shi-jian/10_production/10.5_miniharness_production.md).

# 10.5 实战：MiniHarness 生产化加固

本节展示如何将 MiniHarness（第 2 章的简化版 Agent 框架）升级为生产级系统。核心设计决策是“分层配置、插件热加载、结构化可观测性”。

> 完整代码见 `lab/mini_harness/`，本节聚焦生产架构设计与关键实现模式。

## 10.5.1 生产架构演进

从 v1（教学版）到 v2（生产版）的升级关键点：

| 维度   | v1 教学版   | v2 生产版        | 设计决策          |
| ---- | -------- | ------------- | ------------- |
| 配置   | 硬编码      | 分层加载（文件+环境变量） | 支持多环境、热更新     |
| 插件   | 静态注册     | 动态加载 + 清单管理   | 生产中不重启添加工具    |
| 提示词  | 单模板      | 模板库 + 渲染引擎    | 支持不同 Agent 角色 |
| 可观测性 | print 日志 | 结构化日志 + 分布式追踪 | 生产运维必需        |
| 性能   | 同步执行     | 异步 + 并发 + 缓存  | 低延迟、高吞吐       |

## 10.5.2 分层配置系统

配置的核心原则是“环境驱动、分离 secrets、默认值合理”。设计一个三层加载机制：

```python
import json
import os
from dataclasses import dataclass, field
from typing import Dict, List, Optional

@dataclass
class MiniHarnessConfig:
    # 第1层：类型定义和默认值
    environment: str  # 'development' | 'production'
    model_name: str = "claude-sonnet-4-6"
    max_tokens: int = 2048
    temperature: Optional[float] = None  # 默认不发送采样参数
    enable_cache: bool = True
    log_level: str = "INFO"
    plugin_dirs: List[str] = field(default_factory=list)
    feature_flags: Dict[str, bool] = field(default_factory=dict)

    # 第2层：从文件加载（含验证）
    @classmethod
    def from_file(cls, path: str) -> 'MiniHarnessConfig':
        with open(path) as f:
            data = json.load(f)
        # 验证必需字段、类型检查、边界值检查
        return cls(**data)

    # 第3层：从环境变量覆盖（生产优先级最高）
    @classmethod
    def from_env(cls) -> 'MiniHarnessConfig':
        return cls(
            environment=os.getenv('HARNESS_ENV', 'production'),
            model_name=os.getenv('HARNESS_MODEL', 'claude-sonnet-4-6'),
            # 其他变量...
        )
```

完整配置实现参见 `lab/mini_harness/utils/config.py`。设计要点：

1. **层级继承**：环境变量 > 配置文件 > 默认值
2. **类型安全**：Pydantic 验证而非手动检查
3. **Secrets 隔离**：不在配置文件中存储 API Key，仅通过环境变量

## 10.5.3 插件动态加载架构

插件系统支持“不重启添加工具”，关键是清单驱动设计：

```python
class PluginLoader:
    def load_from_directory(self, plugin_dir: str):
        """扫描目录中的所有插件清单"""
        for subdir in Path(plugin_dir).iterdir():
            manifest_path = subdir / 'manifest.json'
            if manifest_path.exists():
                self.load_plugin(subdir, manifest_path)

    def load_plugin(self, plugin_dir: str, manifest_path: str):
        """根据清单加载单个插件"""
        manifest = json.load(manifest_path)
        # 清单格式：
        # {
        #   "name": "search_plugin",
        #   "tools": [
        #     {"name": "web_search", "handler": "handlers.py", "function": "search"}
        #   ]
        # }

        for tool_spec in manifest['tools']:
            # 动态导入处理函数
            handler = self._import_handler(plugin_dir, tool_spec)
            self.register_tool(tool_spec['name'], handler)
```

设计优势：

1. **零重启热加载**：新增 `plugin/new_tool/manifest.json`，应用启动时自动发现
2. **隔离性**：每个插件独立目录，互不污染
3. **版本管理**：清单中可记录 plugin version，支持灰度升级

上述代码为概念示意；MiniHarness 中插件热加载属于进阶能力，当前仓库以 `lab/mini_harness/tools/registry.py` 与 `lab/mini_harness/tools/builtin.py` 为基础，读者可参考示意自行扩展为清单驱动的 Loader。

## 10.5.4 提示词模板库

不同的 Agent 需要不同的角色定义。通过模板库管理：

```python
class PromptTemplateLibrary:
    def _register_default_templates(self):
        # 通用 Agent 模板
        self.register('default_agent', PromptTemplate(
            system="You are a helpful AI assistant...",
            user="User request: {user_input}"
        ))

        # 研究 Agent 模板
        self.register('research_agent', PromptTemplate(
            system="You are a research specialist...",
            user="Research topic: {topic}"
        ))
```

每个模板支持变量插值，让提示词通用化。设计决策：

1. **模板复用**：同一模板可用于不同用户请求
2. **动态注册**：可在运行时添加新模板（在 `before_execute` 钩子中）
3. **版本控制**：模板保存在版本库中，便于 A/B 测试

上述代码为概念示意；MiniHarness 当前未在仓库中提供独立的模板库模块，读者可基于本节示意将模板集成到 `lab/mini_harness/core/agent.py` 的系统提示词构建流程中。

## 10.5.5 核心智能体执行流

Agent 的生产实现重点在“多轮交互、错误恢复、可观测性”：

```python
async def execute(self, user_input: str) -> Dict:
    """多轮 智能体循环"""
    max_turns = 10
    messages = []

    for turn in range(max_turns):
        # 调用 Claude API
        response = await self.client.messages.create(
            model=self.config.model_name,
            max_tokens=self.config.max_tokens,
            messages=messages,
            system=system_prompt
        )

        content = response.content[0].text

        # 解析是否有工具调用
        tool_calls = self._parse_tool_calls(content)
        if not tool_calls:
            return {'status': 'success', 'result': content}

        # 并发执行工具(最多 N 个)
        results = await self._execute_tools_concurrent(tool_calls)

        # 将结果反馈给 Claude
        messages.append({'role': 'assistant', 'content': content})
        messages.append({'role': 'user', 'content': self._format_results(results)})

    return {'status': 'max_turns_exceeded'}
```

关键设计：

1. **工具并发**：使用 `asyncio.gather()` 加速多工具执行
2. **超时保护**：每个工具调用加超时控制，防止卡住
3. **错误恢复**：工具失败不中断流程，反馈失败信息给 Claude

完整实现参见 `lab/mini_harness/core/agent.py` 与 `lab/mini_harness/runtime/engine.py`。

## 10.5.6 部署清单

生产部署前的关键检查点：

配置与环境 \[ ] 生产 API Key 通过 secret manager、CI secrets 或运行时环境注入；本地 `.env` 仅用于开发且已被 `.gitignore` 忽略 \[ ] 生产/开发环境配置文件已分离（config.prod.json/config.dev.json） \[ ] 日志级别在生产中设为 INFO（不是 DEBUG）

插件与工具 \[ ] 所有必需的插件清单已加载 \[ ] 插件目录结构正确（plugin/\*/manifest.json） \[ ] 工具超时设置合理（API 调用通常 30-60s）

可观测性 \[ ] 结构化日志已配置（JSON 格式） \[ ] 分布式追踪链路已接入（trace\_id 在日志中） \[ ] 关键指标已导出（工具调用数、错误率、延迟）

性能与可靠性 \[ ] 异步并发数设置合理（5-10 个并发工具） \[ ] 请求超时设置（通常 60-120s） \[ ] 重试策略已配置（指数退避）

## 10.5.7 总结

MiniHarness 生产版的四大支柱：

1. **分层配置**：环境变量驱动，支持多环境
2. **插件热加载**：不重启添加工具，清单驱动发现
3. **提示词模板库**：支持多种 Agent 角色
4. **异步并发架构**：低延迟、高吞吐、错误恢复