Code Assistant

代码开发助手

Hermes Agent 是一个强大的编程助手，可以帮助开发者提高编码效率、代码质量和开发体验。本文详细介绍如何在各种开发场景中使用 Hermes Agent。

功能概览

代码开发助手功能
├── 💻 代码生成与补全
├── 🔍 代码审查与优化
├── 🐛 调试与错误修复
├── 🧪 测试生成
├── 📚 代码文档化
├── 🔄 代码重构
├── 🌐 API 开发
└── 🚀 部署与 DevOps

代码生成与补全

智能代码生成

场景示例：根据需求生成完整功能

用户：帮我生成一个 Python 函数，用于验证电子邮件地址，
要求：
1. 使用正则表达式
2. 返回详细的验证结果
3. 包含常见的邮箱格式检查

Hermes Agent：
```python
import re
from dataclasses import dataclass
from typing import Optional

@dataclass
class EmailValidationResult:
    """邮箱验证结果"""
    is_valid: bool
    email: str
    error_message: Optional[str] = None
    local_part: Optional[str] = None
    domain: Optional[str] = None

def validate_email(email: str) -> EmailValidationResult:
    """
    验证电子邮件地址

    Args:
        email: 待验证的邮箱地址

    Returns:
        EmailValidationResult: 包含验证结果的对象
    """
    # 基本空值检查
    if not email or not isinstance(email, str):
        return EmailValidationResult(
            is_valid=False,
            email=email or "",
            error_message="邮箱地址不能为空"
        )

    # 去除首尾空格
    email = email.strip().lower()

    # 长度检查
    if len(email) > 254:
        return EmailValidationResult(
            is_valid=False,
            email=email,
            error_message="邮箱地址过长（最大254字符）"
        )

    # RFC 5322 兼容的正则表达式
    pattern = r'''^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$'''

    if not re.match(pattern, email, re.VERBOSE):
        return EmailValidationResult(
            is_valid=False,
            email=email,
            error_message="邮箱格式不正确"
        )

    # 分割本地部分和域名
    try:
        local_part, domain = email.rsplit('@', 1)
    except ValueError:
        return EmailValidationResult(
            is_valid=False,
            email=email,
            error_message="邮箱格式不正确（缺少@符号）"
        )

    # 本地部分检查
    if len(local_part) > 64:
        return EmailValidationResult(
            is_valid=False,
            email=email,
            error_message="本地部分过长（最大64字符）"
        )

    # 域名检查
    if len(domain) > 255:
        return EmailValidationResult(
            is_valid=False,
            email=email,
            error_message="域名部分过长"
        )

    # 检查连续点号
    if '..' in email:
        return EmailValidationResult(
            is_valid=False,
            email=email,
            error_message="邮箱地址不能包含连续点号"
        )

    return EmailValidationResult(
        is_valid=True,
        email=email,
        local_part=local_part,
        domain=domain
    )


# 使用示例
if __name__ == "__main__":
    test_emails = [
        "user@example.com",
        "invalid.email",
        "user@domain",
        "user.name+tag@example.co.uk",
        "",
        "a" * 65 + "@example.com",  # 本地部分过长
    ]

    for email in test_emails:
        result = validate_email(email)
        print(f"Email: {email}")
        print(f"Valid: {result.is_valid}")
        if not result.is_valid:
            print(f"Error: {result.error_message}")
        else:
            print(f"Local: {result.local_part}, Domain: {result.domain}")
        print("-" * 40)

### 上下文感知补全

**场景示例**：基于项目上下文生成代码

用户：在我的 Django 项目中，我需要为用户模型添加一个发送欢迎邮件的方法。

Hermes Agent：基于您的项目结构，建议在 models.py 中添加以下方法：

from django.core.mail import send_mail
from django.template.loader import render_to_string
from django.conf import settings

class User(AbstractUser):
    # 现有字段...

    def send_welcome_email(self):
        """发送欢迎邮件"""
        subject = f"欢迎加入 {settings.SITE_NAME}！"

        # 渲染邮件模板
        html_message = render_to_string('emails/welcome.html', {
            'user': self,
            'login_url': settings.LOGIN_URL,
        })

        plain_message = render_to_string('emails/welcome.txt', {
            'user': self,
            'login_url': settings.LOGIN_URL,
        })

        send_mail(
            subject=subject,
            message=plain_message,
            from_email=settings.DEFAULT_FROM_EMAIL,
            recipient_list=[self.email],
            html_message=html_message,
            fail_silently=False,
        )

        # 记录邮件发送
        self.email_logs.create(
            email_type='welcome',
            status='sent'
        )

同时需要创建以下文件：

templates/emails/welcome.html
templates/emails/welcome.txt
更新 settings.py 添加邮件配置

## 代码审查与优化

### 自动代码审查

**场景示例**：审查代码并提出改进建议

用户：请审查以下 Python 代码并提供优化建议： [粘贴代码]

Hermes Agent： 🔍 代码审查报告

问题 1：性能问题（高）位置：第 15-20 行问题：使用列表存储大量数据，查询效率低建议：使用字典或集合优化查找

问题 2：异常处理（中）位置：第 32 行问题：裸 except 捕获所有异常建议：指定具体异常类型

问题 3：代码重复（中）位置：第 45-50 行和第 60-65 行问题：相同的逻辑重复出现建议：提取为独立函数

优化后的代码： [提供优化后的代码]

其他建议：

添加类型注解
补充单元测试
考虑使用生成器处理大数据

### 性能优化

```python
# 原始代码（慢）
def find_duplicates(items):
    duplicates = []
    for i in range(len(items)):
        for j in range(i + 1, len(items)):
            if items[i] == items[j] and items[i] not in duplicates:
                duplicates.append(items[i])
    return duplicates

# Hermes Agent 优化后（O(n)）
def find_duplicates_optimized(items):
    """优化版本：使用集合，时间复杂度 O(n)"""
    seen = set()
    duplicates = set()

    for item in items:
        if item in seen:
            duplicates.add(item)
        else:
            seen.add(item)

    return list(duplicates)

调试与错误修复

智能错误诊断

场景示例：分析错误日志并提供解决方案

用户：我的应用报错了，请帮我分析：
[粘贴错误堆栈]

Hermes Agent：
🔍 错误分析

错误类型：DatabaseConnectionError
根本原因：数据库连接池耗尽

可能原因：
1. 连接未正确关闭
2. 并发请求过多
3. 连接池配置过小

解决方案：

1. 立即修复（添加连接关闭）：
```python
# 修复前
def get_data():
    conn = get_connection()
    return conn.query("SELECT * FROM users")

# 修复后
def get_data():
    conn = None
    try:
        conn = get_connection()
        return conn.query("SELECT * FROM users")
    finally:
        if conn:
            conn.close()

使用上下文管理器（推荐）：

from contextlib import contextmanager

@contextmanager
def get_db_connection():
    conn = connection_pool.get_connection()
    try:
        yield conn
    finally:
        conn.close()

# 使用
with get_db_connection() as conn:
    result = conn.query("SELECT * FROM users")

调整连接池配置：

DATABASE_CONFIG = {
    'pool_size': 20,        # 增加连接池大小
    'max_overflow': 30,     # 允许的最大溢出连接
    'pool_timeout': 30,     # 获取连接的超时时间
    'pool_recycle': 3600,   # 连接回收时间
}

### 调试辅助

```bash
# 生成调试脚本
hermes debug --file app.py --line 45 --verbose

# 分析运行时性能
hermes profile --script performance_test.py --output report.html

测试生成

自动生成单元测试

场景示例：为现有代码生成测试

用户：请为以下函数生成完整的单元测试：
```python
def calculate_discount(price, quantity, customer_type):
    if price <= 0 or quantity <= 0:
        raise ValueError("价格和数量必须大于0")

    base_amount = price * quantity

    # 数量折扣
    if quantity >= 100:
        discount_rate = 0.15
    elif quantity >= 50:
        discount_rate = 0.10
    elif quantity >= 10:
        discount_rate = 0.05
    else:
        discount_rate = 0

    # 客户类型折扣
    if customer_type == "VIP":
        discount_rate += 0.05
    elif customer_type == "ENTERPRISE":
        discount_rate += 0.10

    # 最大折扣限制
    discount_rate = min(discount_rate, 0.25)

    discount_amount = base_amount * discount_rate
    final_amount = base_amount - discount_amount

    return {
        "base_amount": base_amount,
        "discount_rate": discount_rate,
        "discount_amount": discount_amount,
        "final_amount": final_amount
    }

Hermes Agent：

import pytest
from calculator import calculate_discount

class TestCalculateDiscount:
    """calculate_discount 函数的测试类"""

    def test_basic_calculation(self):
        """测试基本计算"""
        result = calculate_discount(100, 5, "REGULAR")
        assert result["base_amount"] == 500
        assert result["discount_rate"] == 0
        assert result["discount_amount"] == 0
        assert result["final_amount"] == 500

    def test_quantity_discount_tier_1(self):
        """测试数量折扣 - 10-49件"""
        result = calculate_discount(100, 10, "REGULAR")
        assert result["discount_rate"] == 0.05
        assert result["discount_amount"] == 50

    def test_quantity_discount_tier_2(self):
        """测试数量折扣 - 50-99件"""
        result = calculate_discount(100, 50, "REGULAR")
        assert result["discount_rate"] == 0.10
        assert result["discount_amount"] == 500

    def test_quantity_discount_tier_3(self):
        """测试数量折扣 - 100件以上"""
        result = calculate_discount(100, 100, "REGULAR")
        assert result["discount_rate"] == 0.15
        assert result["discount_amount"] == 1500

    def test_vip_customer_discount(self):
        """测试VIP客户额外折扣"""
        result = calculate_discount(100, 10, "VIP")
        assert result["discount_rate"] == 0.10  # 5% + 5%

    def test_enterprise_customer_discount(self):
        """测试企业客户额外折扣"""
        result = calculate_discount(100, 10, "ENTERPRISE")
        assert result["discount_rate"] == 0.15  # 5% + 10%

    def test_max_discount_cap(self):
        """测试最大折扣限制"""
        result = calculate_discount(100, 100, "ENTERPRISE")
        # 15% + 10% = 25%，但最大限制为25%
        assert result["discount_rate"] == 0.25

    def test_invalid_price(self):
        """测试无效价格"""
        with pytest.raises(ValueError, match="价格和数量必须大于0"):
            calculate_discount(0, 10, "REGULAR")

        with pytest.raises(ValueError, match="价格和数量必须大于0"):
            calculate_discount(-100, 10, "REGULAR")

    def test_invalid_quantity(self):
        """测试无效数量"""
        with pytest.raises(ValueError, match="价格和数量必须大于0"):
            calculate_discount(100, 0, "REGULAR")

        with pytest.raises(ValueError, match="价格和数量必须大于0"):
            calculate_discount(100, -5, "REGULAR")

    def test_edge_case_small_numbers(self):
        """测试边界值 - 小数字"""
        result = calculate_discount(0.01, 1, "REGULAR")
        assert result["base_amount"] == 0.01
        assert result["final_amount"] == 0.01

    def test_edge_case_large_numbers(self):
        """测试边界值 - 大数字"""
        result = calculate_discount(999999, 1000, "ENTERPRISE")
        assert result["discount_rate"] == 0.25
        assert result["base_amount"] == 999999000

### 测试覆盖率分析

```bash
# 生成测试覆盖率报告
hermes test --coverage --format html

# 识别未测试的代码
hermes test --find-uncovered --min-coverage 80

代码文档化

自动生成文档

场景示例：为模块生成完整文档

用户：请为我的 utils.py 模块生成文档

Hermes Agent：
生成以下内容：
1. README.md - 模块说明
2. API 文档 - 函数参考
3. 使用示例 - 代码示例
4. 架构图 - 模块关系图

代码注释优化

# 优化前
def process(data):
    # 处理数据
    result = []
    for item in data:
        if item > 0:
            result.append(item * 2)
    return result

# Hermes Agent 优化后
def process_positive_numbers(numbers: list[int]) -> list[int]:
    """
    将正数列表中的每个元素乘以2

    过滤掉非正数（零和负数），只对正数进行翻倍操作。

    Args:
        numbers: 整数列表，可包含正数、负数和零

    Returns:
        list[int]: 仅包含正数翻倍后的新列表

    Examples:
        >>> process_positive_numbers([1, -2, 3, 0, 5])
        [2, 6, 10]

        >>> process_positive_numbers([-1, -2, -3])
        []

        >>> process_positive_numbers([])
        []
    """
    return [num * 2 for num in numbers if num > 0]

代码重构

安全重构

场景示例：重构遗留代码

用户：请帮我重构这段代码，使其更易维护：
[粘贴复杂代码]

Hermes Agent：
🔄 重构计划

步骤 1：提取函数
- 将大函数拆分为小函数
- 每个函数单一职责

步骤 2：引入设计模式
- 使用策略模式处理不同算法
- 使用工厂模式创建对象

步骤 3：改善命名
- 使用更具描述性的变量名
- 添加类型注解

重构后的代码：
[提供重构后的代码]

验证：
- 功能保持不变 ✓
- 测试全部通过 ✓
- 代码复杂度降低 40% ✓

技术债务分析

# 分析代码库的技术债务
hermes analyze-debt --path ./src --format json

# 生成重构优先级列表
hermes refactor-priority --severity high --effort low

API 开发

API 设计与生成

场景示例：设计 RESTful API

用户：我需要设计一个用户管理系统的 API，请帮我设计

Hermes Agent：
📋 API 设计文档

## 用户管理系统 API

### 基础信息
- Base URL: /api/v1
- Content-Type: application/json
- 认证: Bearer Token

### 端点设计

#### 1. 用户列表

GET /users

参数：
- page (int): 页码，默认 1
- per_page (int): 每页数量，默认 20
- search (string): 搜索关键词
- status (string): 用户状态筛选

响应：
```json
{
  "data": [
    {
      "id": 1,
      "username": "john_doe",
      "email": "john@example.com",
      "status": "active",
      "created_at": "2024-01-15T08:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 10,
    "total_count": 200
  }
}

2. 创建用户

POST /users

请求体：

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "secure_password",
  "role": "user"
}

… [其他端点]

生成代码

同时生成以下实现：

FastAPI 路由代码
Pydantic 模型
数据库模型
单元测试
API 文档

### API 测试

```bash
# 生成 API 测试
hermes api-test --spec openapi.yaml --output tests/

# 性能测试
hermes load-test --endpoint /api/users --concurrency 100 --duration 60s

部署与 DevOps

CI/CD 配置

场景示例：生成 GitHub Actions 工作流

# Hermes Agent 生成的 CI/CD 配置
name: CI/CD Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'

    - name: Install dependencies
      run: |
        pip install -r requirements.txt
        pip install -r requirements-test.txt

    - name: Run linting
      run: |
        flake8 src/
        black --check src/
        mypy src/

    - name: Run tests
      run: pytest --cov=src --cov-report=xml

    - name: Upload coverage
      uses: codecov/codecov-action@v3

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
    - name: Deploy to production
      run: |
        # 部署脚本

Docker 配置

# Hermes Agent 优化的 Dockerfile
FROM python:3.11-slim as builder

WORKDIR /app
COPY requirements.txt .
RUN pip install --user -r requirements.txt

FROM python:3.11-slim

# 创建非 root 用户
RUN useradd -m -u 1000 appuser

WORKDIR /app

# 从 builder 复制依赖
COPY --from=builder /root/.local /home/appuser/.local
COPY --chown=appuser:appuser . .

ENV PATH=/home/appuser/.local/bin:$PATH
USER appuser

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

最佳实践

1. 代码规范

# 自动格式化代码
hermes format --path ./src --style black

# 检查代码规范
hermes lint --path ./src --rules flake8,pylint,mypy

2. 安全扫描

# 安全漏洞扫描
hermes security-scan --path ./src --level high

# 依赖安全检查
hermes check-deps --vulnerabilities

3. 性能优化

# 性能分析
hermes benchmark --function process_data --iterations 1000

# 内存分析
hermes memory-profile --script app.py

总结

Hermes Agent 作为代码开发助手，可以帮助您：

加速开发：智能代码生成和补全
提升质量：自动代码审查和优化
减少 Bug：智能调试和测试生成
改善维护：代码重构和文档化
简化部署：CI/CD 和容器化配置

通过合理利用这些功能，您可以显著提升开发效率和代码质量。