hermes agent 进阶教程

三qian

500人浏览 · 2026-04-22 15:23:48

三qian · 2026-04-22 15:23:48 发布

Hermes Agent 专业深化学习与高级调教指南

第一章：深度理解 Hermes Agent 架构
第二章：高级配置与优化
第三章：技能系统的深度学习
第四章：记忆系统的精妙运用
第五章：多平台网关高级配置
第六章：定时任务与自动化系统
第七章：MCP 协议与外部系统集成
第八章：性能调优与故障排除
第九章：开发与扩展指南
第十章：最佳实践与安全策略

第一章：深度理解 Hermes Agent 架构

1.1 Hermes Agent 分层架构

1.2 核心组件详解

1.2.1 AIAgent 核心循环

位置：run_agent.py
功能：协调模型调用、工具执行、记忆检索
核心机制：工具调用 → 结果处理 → 记忆更新 → 下一轮循环

1.2.2 工具系统架构

tools/
├── registry.py          # 工具注册与管理
├── model_tools.py      # 工具发现与调度
├── toolset.py          # 工具集分组
└── [具体工具目录]
    ├── file.py
    ├── terminal.py
    ├── browser.py
    └── ...

1.3 配置优先级系统

优先级从高到低：
1. CLI参数 (--model, --toolsets 等)
2. ~/.hermes/config.yaml (主配置文件)
3. ~/.hermes/.env (环境变量，API密钥)
4. 内置默认值

第二章：高级配置与优化

2.1 config.yaml 深度配置

# ~/.hermes/config.yaml 完整示例

# 模型配置
models:
  # 强推理模型（代码、排错、长链任务）
  strong_reasoning:
    provider: "anthropic"
    model: "claude-3-opus-20240229"
    temperature: 0.7
    max_tokens: 4000
  
  # 通用模型（日常对话、一般写作）
  general_purpose:
    provider: "openai"
    model: "gpt-4"
    temperature: 0.8
    max_tokens: 2000
  
  # 成本敏感模型（批量任务）
  cost_sensitive:
    provider: "local"
    model: "llama-3-8b"
    temperature: 0.9
    max_tokens: 1000

# 默认设置
defaults:
  model: "general_purpose"
  temperature: 0.7
  max_tokens: 2000

# 平台行为配置
platform:
  # 工具开关
  tools:
    enabled: true
    require_approval: false  # 高危操作需要手动批准
  
  # 记忆系统
  memory:
    enabled: true
    persistence: "honcho"  # 或 "sqlite"、"memory"
    max_context_tokens: 32000
  
  # 技能系统
  skills:
    auto_create: true      # 自动创建技能
    auto_load: true        # 自动加载相关技能
    max_skills_per_session: 5

# 终端后端配置
terminal:
  backend: "local"         # local/docker/ssh/daytona/modal/singularity
  docker:
    image: "hermes-agent-runtime:latest"
    volumes:
      - "~/.hermes:/root/.hermes"
      - "~/.ssh:/root/.ssh"
  ssh:
    host: "user@remote-server"
    port: 22
    identity_file: "~/.ssh/id_rsa"

# 压缩与优化
compression:
  enabled: true
  strategy: "summary"      # summary/remove/keep_all
  max_context_tokens: 16000
  auto_compress_threshold: 0.8  # 80%时自动压缩

2.2 多模型策略配置

# 任务类型与模型映射
task_model_mapping:
  coding:
    - model: "strong_reasoning"
      conditions: ["complex", "debug", "refactor"]
  writing:
    - model: "general_purpose"
      conditions: ["creative", "long_form"]
  analysis:
    - model: "general_purpose"
      conditions: ["data", "research"]
  chat:
    - model: "cost_sensitive"
      conditions: ["casual", "quick"]

2.3 Profile 管理高级技巧

# 创建专业配置文件
hermes profile create coding --clone default
hermes profile use coding
hermes config set model anthropic/claude-3-opus-20240229
hermes config set toolsets coding,terminal,file

# 创建团队配置文件
hermes profile create team-dev --clone default
hermes config set skills.auto_load false
hermes config set platform.tools.require_approval true

# 配置文件导出与迁移
hermes profile export coding > coding-profile.yaml
hermes profile import team-profile.yaml

# 批量管理
for profile in coding writing analysis; do
  hermes profile create $profile --clone default
  hermes profile use $profile
  # 个性化配置
done

第三章：技能系统的深度学习

3.1 技能创建机制

3.1.1 技能自动生成流程

# 技能生成触发器
skill_creation_triggers:
  - min_tool_calls: 3          # 最少工具调用次数
  - success_rate: 0.8          # 成功率阈值
  - complexity_score: 0.6      # 复杂度评分
  - repetition_detected: true  # 检测到重复模式

3.1.2 技能文件结构

# ~/.hermes/skills/advanced_git_analysis.yaml
name: advanced_git_analysis
description: 高级 Git 仓库分析与报告生成
version: "2.1"
author: ${USER}
created: ${TIMESTAMP}
last_used: ${TIMESTAMP}
usage_count: 42
success_rate: 0.95

# 元数据
metadata:
  tags:
    - git
    - development
    - analysis
    - reporting
  complexity: advanced
  estimated_time: "2m"
  risk_level: low

# 依赖检查
prerequisites:
  tools:
    - terminal
    - file
  commands:
    - git
    - awk
  files:
    - .git/
  environment:
    - GIT_AUTHOR_NAME
    - GIT_AUTHOR_EMAIL

# 执行步骤
steps:
  - id: get_git_info
    tool: terminal
    command: |
      git log --oneline -50 --format="%h|%an|%ad|%s" --date=short
    description: 获取最近50条提交记录
    output_variable: git_log
  
  - id: analyze_contributors
    tool: terminal
    command: |
      echo "${git_log}" | awk -F'|' '{print $2}' | sort | uniq -c | sort -nr
    description: 分析贡献者统计
    output_variable: contributors
  
  - id: analyze_timeline
    tool: terminal
    command: |
      echo "${git_log}" | awk -F'|' '{print $3}' | cut -d'-' -f1-2 | sort | uniq -c
    description: 分析时间线分布
    output_variable: timeline
  
  - id: generate_report
    tool: llm
    prompt: |
      基于以下 Git 分析数据生成详细报告：
      
      提交记录：${git_log}
      贡献者统计：${contributors}
      时间线分布：${timeline}
      
      报告要求：
      1. 项目开发活跃度分析
      2. 核心贡献者识别与评估
      3. 开发节奏与趋势分析
      4. 潜在问题与改进建议
      5. 可视化建议（如有数据）
      
      格式要求：Markdown，包含表格和总结。
    description: 生成分析报告
    output_variable: report

# 验证与错误处理
validation:
  - check: git_log_lines
    condition: "lines > 0"
    error_message: "没有找到 Git 提交记录"
    fallback_action: skip
  
  - check: git_repository
    condition: "directory_exists('.git')"
    error_message: "当前目录不是 Git 仓库"
    fallback_action: fail

# 后处理
post_processing:
  - action: save_to_file
    file: "git_analysis_${TIMESTAMP}.md"
    content: "${report}"
  
  - action: notify
    condition: "contributors_count > 5"
    message: "发现 ${contributors_count} 位贡献者，需要关注协作效率"

3.2 技能管理系统

3.2.1 技能搜索与安装

# 高级技能搜索
hermes skills search "kubernetes deployment" --tag production --min-rating 4.5
hermes skills search "data analysis" --author official --max-complexity intermediate

# 批量技能管理
hermes skills install official/devops/*
hermes skills update --all
hermes skills audit --fix

# 技能评分与反馈
hermes skills rate advanced_git_analysis 5 "Excellent analysis tool"
hermes skills feedback api_testing "Add more error handling"

3.2.2 技能组合与编排

# 复合技能：项目初始化流程
name: project_bootstrap
description: 完整项目初始化流程
steps:
  - skill: git_repository_setup
    parameters:
      repo_name: "${PROJECT_NAME}"
      private: true
      description: "New project"
  
  - skill: python_project_structure
    parameters:
      project_type: "web_api"
      framework: "fastapi"
      testing: "pytest"
  
  - skill: ci_cd_setup
    parameters:
      platform: "github_actions"
      tests: true
      deploy: "heroku"
  
  - skill: documentation_init
    parameters:
      include:
        - README.md
        - API.md
        - DEPLOYMENT.md

3.3 技能优化策略

3.3.1 性能监控

# 技能性能分析
hermes skills profile advanced_git_analysis --runs 10
hermes skills benchmark "*.yaml" --parallel 3

# 使用统计
hermes skills stats --days 30 --format json
hermes skills insights --top 10 --trend weekly

3.3.2 自动优化

# 技能优化配置
skill_optimization:
  enabled: true
  strategies:
    - name: step_consolidation
      threshold: 0.7  # 70%相关步骤合并
    - name: prompt_optimization
      threshold: 0.5  # 提示词优化
    - name: tool_selection
      threshold: 0.8  # 工具选择优化
  
  # 优化触发器
  triggers:
    - usage_count: 10
    - success_rate_drop: 0.1
    - execution_time_increase: 2.0

第四章：记忆系统的精妙运用

4.1 记忆系统架构

4.1.1 记忆层次结构

记忆系统分为三层：
1. 会话记忆：当前对话上下文
2. 短期记忆：最近使用的信息
3. 长期记忆：持久化存储的重要信息

4.1.2 记忆存储格式

# ~/.hermes/memories/ 目录结构
memories/
├── USER.md                    # 用户个人资料
├── PROJECTS/                  # 项目相关记忆
│   ├── project_a.md
│   ├── project_b.md
│   └── tech_stack.md
├── PREFERENCES/              # 用户偏好
│   ├── coding_style.md
│   ├── tool_preferences.md
│   └── communication_style.md
├── FACTS/                    # 事实信息
│   ├── team_members.md
│   ├── company_policies.md
│   └── technical_knowledge.md
└── HISTORY/                  # 历史记录
    ├── decisions.md
    ├── lessons_learned.md
    └── achievements.md

4.2 高级记忆操作

4.2.1 记忆检索策略

# 高级记忆查询
hermes memory query "project deadlines" --recency 7 --relevance 0.8
hermes memory search "API design" --category technical --limit 5

# 记忆关联分析
hermes memory relate "user_john" "project_x" --strength strong
hermes memory graph --depth 3 --format mermaid

4.2.2 记忆优化配置

# config.yaml 记忆配置
memory:
  engine: "honcho"  # honcho/sqlite/memory
  
  # 检索优化
  retrieval:
    strategy: "hybrid"  # vector/semantic/hybrid
    max_results: 10
    similarity_threshold: 0.7
    recency_weight: 0.3
    relevance_weight: 0.7
  
  # 存储优化
  storage:
    compression: true
    deduplication: true
    pruning_strategy: "lru"  # lru/lfu/ttl
    
  # 隐私控制
  privacy:
    sensitive_categories: ["credentials", "personal"]
    encryption: true
    retention_policy: "90d"

4.3 记忆增强技巧

4.3.1 主动记忆强化

# 主动保存重要信息
记住：我们的生产数据库连接字符串是 ${DB_URL}，备份策略是每日全量+每小时增量。

# 结构化记忆存储
存储项目配置：
- 项目名称：${PROJECT_NAME}
- 技术栈：${TECH_STACK}
- 部署环境：${ENVIRONMENTS}
- 团队成员：${TEAM_MEMBERS}

4.3.2 记忆自动化

# 自动记忆规则
auto_memory_rules:
  - pattern: "password|token|secret|key"
    category: "sensitive"
    action: "encrypt"
  
  - pattern: "decision|agreement|conclusion"
    category: "decisions"
    action: "highlight"
  
  - pattern: "error|bug|issue"
    category: "problems"
    action: "tag urgent"

第五章：多平台网关高级配置

5.1 网关系统架构

5.1.1 网关配置管理

# ~/.hermes/config.yaml 网关配置
gateway:
  enabled: true
  platforms:
    telegram:
      enabled: true
      bot_token: "${TELEGRAM_BOT_TOKEN}"
      allowed_users: ["123456789", "987654321"]
      home_channel: "-1001234567890"
      
    discord:
      enabled: true
      bot_token: "${DISCORD_BOT_TOKEN}"
      allowed_guilds: ["guild_id_1", "guild_id_2"]
      allowed_channels: ["channel_id_1", "channel_id_2"]
      
    feishu:
      enabled: true
      app_id: "${FEISHU_APP_ID}"
      app_secret: "${FEISHU_APP_SECRET}"
      verification_token: "${FEISHU_VERIFICATION_TOKEN}"
      encrypt_key: "${FEISHU_ENCRYPT_KEY}"
  
  # 消息处理
  message_processing:
    rate_limit: "10/60s"  # 10条/分钟
    queue_size: 100
    timeout: 30s
  
  # 安全控制
  security:
    require_authentication: true
    command_whitelist: ["/help", "/status", "/model"]
    admin_users: ["admin_user_id"]

5.2 平台特定配置

5.2.1 飞书深度集成

# 飞书机器人配置
hermes gateway setup feishu

# 配置企业微信回调
hermes config set gateway.platforms.feishu.webhook_url "https://your-domain.com/webhook"
hermes config set gateway.platforms.feishu.event_types ["im.message.receive_v1"]

# 飞书卡片消息支持
hermes config set gateway.platforms.feishu.card_support true

5.2.2 多平台同步

# 跨平台会话同步
gateway.cross_platform:
  enabled: true
  sync_sessions: true
  shared_memory: true
  platforms: ["telegram", "discord", "feishu"]
  
  # 平台特定配置
  platform_overrides:
    telegram:
      message_format: "markdown"
      file_size_limit: "50MB"
    
    discord:
      message_format: "embed"
      file_size_limit: "8MB"
    
    feishu:
      message_format: "card"
      file_size_limit: "100MB"

5.3 网关高级功能

5.3.1 消息路由与过滤

# 消息路由规则
message_routing:
  rules:
    - condition: "message contains 'urgent'"
      action: "forward_to_telegram"
      targets: ["admin_chat_id"]
      priority: "high"
    
    - condition: "message contains 'bug' or 'error'"
      action: "forward_to_slack"
      targets: ["devops_channel"]
      priority: "medium"
    
    - condition: "message from user in ${TEAM_USERS}"
      action: "process_locally"
      priority: "normal"
  
  # 自动回复
  auto_replies:
    - pattern: "status|状态"
      response: "系统运行正常，最近1小时处理了 ${PROCESSED_COUNT} 条消息"
    
    - pattern: "help|帮助"
      response: "可用命令：/help, /status, /model, /skills"

5.3.2 网关监控与管理

# 网关状态监控
hermes gateway status --detailed --format json
hermes gateway metrics --hours 24 --platform all

# 消息队列管理
hermes gateway queue --list --size 20
hermes gateway queue --clear --older-than "1h"

# 性能分析
hermes gateway profile --duration 300 --sampling 1

第六章：定时任务与自动化系统

6.1 Cron 系统深度解析

6.1.1 高级 Cron 配置

# ~/.hermes/cron/ 配置示例
jobs:
  daily_report:
    schedule: "0 9 * * *"  # 每天9点
    command: "生成每日业务报告"
    platform: "feishu"
    channel: "reporting_channel"
    retry:
      max_attempts: 3
      delay: "5m"
    
  weekly_backup:
    schedule: "0 2 * * 0"  # 每周日2点
    command: "执行数据库备份并验证"
    timeout: "30m"
    notifications:
      success: "telegram://admin_chat"
      failure: "telegram://alert_chat"
    
  monitoring:
    schedule: "*/5 * * * *"  # 每5分钟
    command: "检查系统健康状态"
    condition: "只有在工作时间执行"

6.1.2 条件化任务执行

# 带条件的定时任务
conditional_jobs:
  - name: "data_sync_if_changed"
    schedule: "*/15 * * * *"
    command: "同步数据仓库"
    conditions:
      - type: "file_modified"
        path: "/data/updates/*.json"
        within: "15m"
      
      - type: "api_available"
        endpoint: "https://api.example.com/health"
        timeout: "10s"
    
  - name: "notify_on_error"
    schedule: "* * * * *"  # 每分钟
    command: "检查错误日志并通知"
    conditions:
      - type: "log_pattern"
        file: "/var/log/app/error.log"
        pattern: "ERROR|FATAL"
        since: "5m"

6.2 工作流编排

6.2.1 复杂工作流定义

# 多步骤工作流
workflows:
  deployment_pipeline:
    steps:
      - name: "code_checkout"
        command: "git checkout ${BRANCH} && git pull"
        timeout: "5m"
      
      - name: "run_tests"
        command: "运行测试套件"
        depends_on: ["code_checkout"]
        timeout: "10m"
      
      - name: "build_image"
        command: "构建 Docker 镜像"
        depends_on: ["run_tests"]
        condition: "tests_passed"
        timeout: "15m"
      
      - name: "deploy_staging"
        command: "部署到预发布环境"
        depends_on: ["build_image"]
        timeout: "10m"
      
      - name: "run_smoke_tests"
        command: "运行冒烟测试"
        depends_on: ["deploy_staging"]
        timeout: "5m"
    
    # 工作流配置
    config:
      max_parallel: 2
      retry_policy: "exponential"
      notification_level: "all"

6.2.2 工作流监控

# 工作流状态管理
hermes workflow list --status running
hermes workflow show deployment_pipeline --details
hermes workflow logs deployment_pipeline --step build_image

# 工作流控制
hermes workflow pause deployment_pipeline
hermes workflow resume deployment_pipeline
hermes workflow cancel deployment_pipeline --reason "manual_intervention"

6.3 自动化策略优化

6.3.1 资源优化

# 资源管理配置
automation_resources:
  cpu:
    max_usage: 80%  # 最大CPU使用率
    throttle_threshold: 70%
    
  memory:
    max_usage: 2GB
    warning_threshold: 1.5GB
    
  concurrency:
    max_jobs: 5
    max_workflows: 2
    queue_size: 10

6.3.2 成本优化

# 成本控制策略
cost_optimization:
  model_selection:
    strategy: "cost_aware"
    budget_per_day: 10.0  # 美元
    low_cost_providers: ["openrouter", "local"]
    
  timing_optimization:
    off_peak_hours: ["00:00-06:00"]
    rate_limited_tasks: ["web_scraping", "api_calls"]

第七章：MCP 协议与外部系统集成

7.1 MCP 架构深度解析

7.1.1 MCP 服务器配置

# config.yaml MCP 配置
mcp_servers:
  # 文件系统服务器
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    env:
      MCP_DEBUG: "true"
    
  # GitHub 服务器
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    tools:
      include: ["list_issues", "create_issue", "search_code"]
      exclude: ["delete_repository"]
    
  # 自定义 API 服务器
  custom_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ${API_TOKEN}"
      X-Custom-Header: "hermes-agent"
    
  # 数据库服务器
  postgres:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      POSTGRES_URL: "${DATABASE_URL}"
    resources:
      include: ["tables", "schemas"]

7.1.2 MCP 工具安全策略

# MCP 安全配置
mcp_security:
  # 权限级别
  permission_levels:
    - name: "readonly"
      actions: ["read", "list", "query"]
    
    - name: "standard"
      actions: ["read", "write", "create", "update"]
    
    - name: "admin"
      actions: ["*"]
  
  # 服务器权限
  server_permissions:
    filesystem: "standard"
    github: "readonly"
    postgres: "standard"
    custom_api: "admin"
  
  # 审计日志
  audit_logging: true
  log_sensitive_operations: true

7.2 高级集成模式

7.2.1 多系统协同工作流

# 跨系统工作流示例
cross_system_workflow:
  name: "incident_response"
  steps:
    - system: "github"
      action: "create_issue"
      params:
        title: "生产环境故障: ${ERROR_MESSAGE}"
        body: "自动创建的故障响应工单"
        labels: ["incident", "urgent"]
    
    - system: "slack"
      action: "send_message"
      params:
        channel: "incidents"
        message: "🚨 检测到生产故障，已创建 GitHub 工单: ${ISSUE_URL}"
    
    - system: "datadog"
      action: "query_metrics"
      params:
        query: "avg:system.cpu.user{*} by {host}"
        timeframe: "1h"
    
    - system: "pagerduty"
      action: "trigger_incident"
      params:
        title: "生产环境故障"
        service: "web_application"
        urgency: "high"

7.2.2 自定义 MCP 服务器开发

# 自定义 MCP 服务器示例
from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationOptions
import mcp.server.stdio

# 创建服务器
server = Server("custom-tool-server")

@server.list_tools()
async def handle_list_tools() -> list:
    return [
        {
            "name": "custom_analysis",
            "description": "执行自定义数据分析",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "data": {"type": "string"},
                    "analysis_type": {"type": "string"}
                }
            }
        }
    ]

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict):
    if name == "custom_analysis":
        # 实现工具逻辑
        result = perform_analysis(arguments["data"], arguments["analysis_type"])
        return {
            "content": [{"type": "text", "text": result}]
        }

# 运行服务器
async def main():
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="custom-tool-server",
                server_version="1.0.0"
            )
        )

第八章：性能调优与故障排除

8.1 性能监控与分析

8.1.1 监控指标收集

# 性能指标收集
hermes metrics --collect --duration 300 --output metrics.json
hermes profile --cpu --memory --io --duration 60

# 详细性能分析
hermes performance analyze --days 7 --format html
hermes bottleneck detect --threshold 0.8 --recommendations

8.1.2 性能优化配置

# 性能优化配置
performance:
  # 模型调用优化
  model:
    caching:
      enabled: true
      ttl: "1h"
      max_size: "100MB"
    
    batching:
      enabled: true
      max_batch_size: 10
      timeout: "5s"
  
  # 工具执行优化
  tools:
    concurrent_execution: true
    max_concurrent: 3
    timeout: "30s"
    
  # 内存管理
  memory:
    garbage_collection:
      enabled: true
      interval: "5m"
    compression: true
    max_session_size: "50MB"

8.2 故障诊断与恢复

8.2.1 诊断工具集

# 系统健康检查
hermes doctor --full --fix
hermes diagnose --symptoms "slow_response,high_memory"

# 日志分析
hermes logs --tail 100 --level error
hermes logs --search "timeout" --since "1h" --format json

# 网络诊断
hermes network --test --providers all
hermes connectivity --endpoints "api.openai.com,api.anthropic.com"

8.2.2 故障恢复策略

# 故障恢复配置
fault_recovery:
  # 自动恢复策略
  auto_recovery:
    enabled: true
    max_attempts: 3
    backoff_strategy: "exponential"
    
  # 降级策略
  fallback_strategies:
    - condition: "model_unavailable"
      action: "switch_model"
      fallback_model: "cost_sensitive"
    
    - condition: "tool_failure"
      action: "use_alternative_tool"
    
    - condition: "high_latency"
      action: "reduce_complexity"
  
  # 通知策略
  notifications:
    - severity: "critical"
      channels: ["sms", "telegram", "email"]
    - severity: "warning"
      channels: ["telegram"]
    - severity: "info"
      channels: ["log_only"]

8.3 安全与稳定性

8.3.1 安全加固

# 安全配置
security:
  # 身份验证
  authentication:
    required: true
    methods: ["api_key", "oauth"]
    session_timeout: "24h"
  
  # 访问控制
  access_control:
    role_based: true
    default_role: "user"
    admin_roles: ["admin", "superuser"]
  
  # 数据保护
  data_protection:
    encryption:
      enabled: true
      algorithm: "AES-256-GCM"
    sanitization:
      enabled: true
      patterns: ["api_key", "password", "token"]

8.3.2 稳定性保障

# 稳定性配置
stability:
  # 资源限制
  resource_limits:
    cpu_usage: "90%"
    memory_usage: "80%"
    disk_usage: "85%"
    network_bandwidth: "100MB/s"
  
  # 健康检查
  health_checks:
    interval: "30s"
    timeout: "5s"
    failure_threshold: 3
    
  # 自动重启
  auto_restart:
    enabled: true
    conditions:
      - memory_leak: "100MB/5m"
      - unresponsive: "60s"
      - crash_detected: true

第九章：开发与扩展指南

9.1 工具开发框架

9.1.1 自定义工具开发

# 自定义工具示例：高级文件分析
from hermes.tools import BaseTool
from typing import Dict, Any
import os
import json

class AdvancedFileAnalysisTool(BaseTool):
    """高级文件分析工具"""
    
    name = "advanced_file_analysis"
    description = "对文件进行深度分析，包括代码质量、安全扫描等"
    version = "1.0.0"
    
    input_schema = {
        "type": "object",
        "properties": {
            "file_path": {"type": "string", "description": "要分析的文件路径"},
            "analysis_types": {
                "type": "array",
                "items": {"type": "string"},
                "description": "分析类型：code_quality, security, complexity, dependencies"
            },
            "config": {"type": "object", "description": "分析配置"}
        },
        "required": ["file_path"]
    }
    
    async def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
        file_path = input_data["file_path"]
        analysis_types = input_data.get("analysis_types", ["code_quality"])
        config = input_data.get("config", {})
        
        # 验证文件存在
        if not os.path.exists(file_path):
            return {
                "success": False,
                "error": f"文件不存在: {file_path}"
            }
        
        results = {}
        
        # 执行各种分析
        for analysis_type in analysis_types:
            if analysis_type == "code_quality":
                results["code_quality"] = self._analyze_code_quality(file_path)
            elif analysis_type == "security":
                results["security"] = self._analyze_security(file_path)
            elif analysis_type == "complexity":
                results["complexity"] = self._analyze_complexity(file_path)
            elif analysis_type == "dependencies":
                results["dependencies"] = self._analyze_dependencies(file_path)
        
        return {
            "success": True,
            "results": results,
            "summary": self._generate_summary(results)
        }
    
    def _analyze_code_quality(self, file_path: str) -> Dict[str, Any]:
        """分析代码质量"""
        # 实现代码质量分析逻辑
        pass
    
    def _analyze_security(self, file_path: str) -> Dict[str, Any]:
        """安全分析"""
        # 实现安全分析逻辑
        pass
    
    def _analyze_complexity(self, file_path: str) -> Dict[str, Any]:
        """代码复杂度分析"""
        # 实现复杂度分析逻辑
        pass
    
    def _analyze_dependencies(self, file_path: str) -> Dict[str, Any]:
        """依赖分析"""
        # 实现依赖分析逻辑
        pass
    
    def _generate_summary(self, results: Dict[str, Any]) -> str:
        """生成分析总结"""
        # 实现总结生成逻辑
        pass

9.1.2 工具注册与配置

# 工具注册配置
from hermes.tools.registry import register_tool

# 注册自定义工具
register_tool(AdvancedFileAnalysisTool)

# 工具集配置
toolset_config = {
    "advanced_analysis": {
        "description": "高级分析工具集",
        "tools": [
            "advanced_file_analysis",
            "data_visualization",
            "performance_profiling"
        ],
        "default_enabled": False,
        "requires_approval": True
    }
}

9.2 插件系统开发

9.2.1 插件架构

# 插件基类
from abc import ABC, abstractmethod
from typing import Dict, Any

class HermesPlugin(ABC):
    """Hermes 插件基类"""
    
    @abstractmethod
    def initialize(self, config: Dict[str, Any]):
        """插件初始化"""
        pass
    
    @abstractmethod
    def get_name(self) -> str:
        """获取插件名称"""
        pass
    
    @abstractmethod
    def get_version(self) -> str:
        """获取插件版本"""
        pass
    
    def on_message_received(self, message: Dict[str, Any]):
        """消息接收事件"""
        pass
    
    def on_tool_called(self, tool_name: str, arguments: Dict[str, Any]):
        """工具调用事件"""
        pass
    
    def on_session_start(self, session_id: str):
        """会话开始事件"""
        pass
    
    def on_session_end(self, session_id: str, summary: Dict[str, Any]):
        """会话结束事件"""
        pass

9.2.2 插件开发示例

# 审计日志插件
import logging
from datetime import datetime
from hermes.plugins import HermesPlugin

class AuditLogPlugin(HermesPlugin):
    """审计日志插件"""
    
    def __init__(self):
        self.logger = logging.getLogger("hermes.audit")
        self.audit_log = []
    
    def initialize(self, config: Dict[str, Any]):
        self.config = config
        self.logger.info("Audit log plugin initialized")
    
    def get_name(self) -> str:
        return "audit_log"
    
    def get_version(self) -> str:
        return "1.0.0"
    
    def on_tool_called(self, tool_name: str, arguments: Dict[str, Any]):
        # 记录工具调用
        audit_entry = {
            "timestamp": datetime.now().isoformat(),
            "event": "tool_called",
            "tool": tool_name,
            "arguments": self._sanitize_arguments(arguments),
            "user": self._get_current_user()
        }
        self.audit_log.append(audit_entry)
        self.logger.info(f"Tool called: {tool_name}")
    
    def on_session_end(self, session_id: str, summary: Dict[str, Any]):
        # 保存审计日志
        self._save_audit_log(session_id)
    
    def _sanitize_arguments(self, arguments: Dict[str, Any]) -> Dict[str, Any]:
        """清理敏感参数"""
        sanitized = arguments.copy()
        sensitive_keys = ["password", "token", "key", "secret"]
        for key in sensitive_keys:
            if key in sanitized:
                sanitized[key] = "[REDACTED]"
        return sanitized
    
    def _save_audit_log(self, session_id: str):
        """保存审计日志"""
        # 实现日志保存逻辑
        pass

9.3 测试与部署

9.3.1 自动化测试

# 工具测试框架
import pytest
from hermes.tools.testing import ToolTestCase
from .advanced_file_analysis import AdvancedFileAnalysisTool

class TestAdvancedFileAnalysisTool(ToolTestCase):
    """高级文件分析工具测试"""
    
    tool_class = AdvancedFileAnalysisTool
    
    def test_file_exists(self):
        """测试文件存在检查"""
        result = self.execute_tool({
            "file_path": "/tmp/test_file.txt",
            "analysis_types": ["code_quality"]
        })
        assert result["success"] == False
        assert "文件不存在" in result["error"]
    
    def test_code_quality_analysis(self):
        """测试代码质量分析"""
        # 创建测试文件
        test_file = "/tmp/test_code.py"
        with open(test_file, "w") as f:
            f.write("def hello():\n    print('Hello World')")
        
        result = self.execute_tool({
            "file_path": test_file,
            "analysis_types": ["code_quality"]
        })
        
        assert result["success"] == True
        assert "code_quality" in result["results"]
    
    def test_multiple_analysis_types(self):
        """测试多类型分析"""
        test_file = "/tmp/test_multi.py"
        with open(test_file, "w") as f:
            f.write("import os\n\ndef test():\n    pass")
        
        result = self.execute_tool({
            "file_path": test_file,
            "analysis_types": ["code_quality", "security", "complexity"]
        })
        
        assert result["success"] == True
        assert len(result["results"]) == 3

9.3.2 部署流水线

# GitHub Actions 部署配置
name: Deploy Hermes Extension

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install uv
          uv pip install -e ".[test]"
      
      - name: Run tests
        run: |
          pytest tests/ -v --cov=hermes_extension
  
  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build package
        run: |
          python -m build
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: hermes-extension-package
          path: dist/
  
  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: startsWith(github.ref, 'refs/tags/v')
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: hermes-extension-package
      
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

第十章：最佳实践与安全策略

10.1 企业级部署最佳实践

10.1.1 多环境部署策略

# 多环境配置
environments:
  development:
    config_profile: "dev"
    features:
      - debug_mode: true
      - auto_skill_creation: true
      - experimental_tools: true
    resources:
      cpu: "2"
      memory: "4GB"
      storage: "20GB"
  
  staging:
    config_profile: "staging"
    features:
      - debug_mode: false
      - auto_skill_creation: false
      - require_approval: true
    resources:
      cpu: "4"
      memory: "8GB"
      storage: "50GB"
  
  production:
    config_profile: "prod"
    features:
      - debug_mode: false
      - auto_skill_creation: false
      - require_approval: true
      - audit_logging: true
    resources:
      cpu: "8"
      memory: "16GB"
      storage: "100GB"
    monitoring:
      enabled: true
      alert_channels: ["pagerduty", "slack"]

10.1.2 团队协作配置

# 团队权限管理
team_permissions:
  developers:
    roles: ["developer"]
    permissions:
      - create_skills: true
      - modify_tools: true
      - access_terminal: true
      - access_files: true
    restrictions:
      - production_access: false
      - admin_commands: false
  
  admins:
    roles: ["admin"]
    permissions:
      - "*"
    restrictions: []
  
  analysts:
    roles: ["analyst"]
    permissions:
      - query_data: true
      - generate_reports: true
      - access_web: true
    restrictions:
      - terminal_access: false
      - file_write: false

10.2 安全策略实施

10.2.1 数据安全策略

# 数据安全配置
data_security:
  # 加密配置
  encryption:
    at_rest:
      enabled: true
      algorithm: "AES-256-GCM"
      key_rotation: "30d"
    
    in_transit:
      enabled: true
      protocol: "TLS 1.3"
      certificate_validation: true
  
  # 数据分类
  data_classification:
    public:
      encryption: false
      retention: "90d"
    
    internal:
      encryption: true
      retention: "365d"
      access_logging: true
    
    confidential:
      encryption: true
      retention: "permanent"
      access_logging: true
      audit_trail: true
    
    restricted:
      encryption: true
      retention: "permanent"
      access_logging: true
      audit_trail: true
      approval_required: true
  
  # 数据清理
  data_purge:
    enabled: true
    schedule: "0 2 * * *"  # 每天2点
    rules:
      - type: "log_files"
        age: "30d"
        pattern: "*.log"
      
      - type: "temporary_files"
        age: "7d"
        pattern: "/tmp/*"
      
      - type: "cache"
        age: "1d"
        max_size: "1GB"

10.2.2 访问控制策略

# 访问控制配置
access_control:
  # 身份验证
  authentication:
    methods:
      - type: "api_key"
        rotation: "90d"
      
      - type: "oauth2"
        providers: ["google", "github", "okta"]
      
      - type: "saml"
        enabled: true
    
    mfa:
      enabled: true
      methods: ["totp", "webauthn"]
      required_for: ["admin", "sensitive_operations"]
  
  # 授权策略
  authorization:
    rbac:
      enabled: true
      default_role: "viewer"
      role_hierarchy:
        viewer: []
        user: ["viewer"]
        power_user: ["user"]
        admin: ["power_user"]
    
    abac:
      enabled: true
      attributes:
        - department
        - location
        - clearance_level
    
    # 最小权限原则
    least_privilege: true
    permission_review_interval: "90d"
  
  # 会话管理
  session_management:
    timeout: "8h"
    idle_timeout: "1h"
    max_sessions_per_user: 5
    session_rotation: true

10.3 监控与告警

10.3.1 监控配置

# 监控系统配置
monitoring:
  # 系统监控
  system:
    cpu:
      threshold: 80%
      interval: "30s"
    
    memory:
      threshold: 85%
      interval: "30s"
    
    disk:
      threshold: 90%
      interval: "5m"
    
    network:
      threshold: "100MB/s"
      interval: "1m"
  
  # 应用监控
  application:
    response_time:
      threshold: "5s"
      interval: "1m"
    
    error_rate:
      threshold: "1%"
      interval: "5m"
    
    availability:
      threshold: "99.9%"
      interval: "1m"
    
    # 自定义指标
    custom_metrics:
      - name: "tool_execution_time"
        query: "avg(tool_duration_seconds)"
        threshold: "10s"
      
      - name: "model_cost_per_day"
        query: "sum(model_cost_usd)"
        threshold: "100"
      
      - name: "skill_usage_rate"
        query: "count(skill_executions)"
        threshold: "1000"
  
  # 日志监控
  log_monitoring:
    error_patterns:
      - "ERROR"
      - "FATAL"
      - "Exception"
      - "Traceback"
    
    security_patterns:
      - "Unauthorized"
      - "Forbidden"
      - "Invalid credentials"
      - "Suspicious activity"
    
    performance_patterns:
      - "timeout"
      - "slow"
      - "bottleneck"
      - "high latency"

10.3.2 告警策略

# 告警系统配置
alerts:
  # 告警级别
  severity_levels:
    critical:
      channels: ["pagerduty", "sms", "telegram", "email"]
      repeat_interval: "5m"
      escalation_timeout: "15m"
    
    warning:
      channels: ["telegram", "email", "slack"]
      repeat_interval: "1h"
      escalation_timeout: "4h"
    
    info:
      channels: ["slack", "email"]
      repeat_interval: "24h"
      no_escalation: true
  
  # 告警规则
  rules:
    - name: "high_cpu_usage"
      condition: "cpu_usage > 90% for 5m"
      severity: "warning"
      description: "CPU使用率持续高位"
    
    - name: "service_down"
      condition: "health_check_failed > 3"
      severity: "critical"
      description: "服务健康检查失败"
    
    - name: "security_breach"
      condition: "failed_auth_attempts > 10 in 1m"
      severity: "critical"
      description: "多次身份验证失败"
      actions:
        - block_ip: true
        - notify_admin: true
        - rotate_keys: true
    
    - name: "cost_exceeded"
      condition: "daily_cost > 100"
      severity: "warning"
      description: "日成本超过阈值"
    
    - name: "skill_failure"
      condition: "skill_failure_rate > 20% in 1h"
      severity: "warning"
      description: "技能执行失败率升高"
  
  # 告警抑制
  suppression:
    business_hours: "09:00-18:00"
    maintenance_windows:
      - "星期日 02:00-04:00"
      - "每月第一个星期一 00:00-01:00"
    
    dependent_alerts: true
    max_alerts_per_hour: 100

10.4 备份与灾难恢复

10.4.1 备份策略

# 备份配置
backup:
  # 备份计划
  schedule:
    full: "0 2 * * 0"      # 每周日2点全量备份
    incremental: "0 */6 * * *"  # 每6小时增量备份
    differential: "0 2 * * 1-6"  # 周一到周六2点差异备份
  
  # 备份内容
  contents:
    - config: true
      retention: "90d"
    
    - skills: true
      retention: "180d"
    
    - memories: true
      retention: "永久"
    
    - sessions: true
      retention: "30d"
    
    - logs: true
      retention: "30d"
  
  # 存储位置
  storage:
    local:
      enabled: true
      path: "/backups/hermes"
      retention: "7d"
    
    cloud:
      enabled: true
      provider: "s3"
      bucket: "hermes-backups"
      region: "us-east-1"
      retention: "90d"
    
    offsite:
      enabled: true
      provider: "glacier"
      vault: "hermes-archive"
      retention: "365d"
  
  # 验证与测试
  verification:
    enabled: true
    schedule: "0 3 * * *"  # 每天3点验证备份
    test_restore: "每月第一个星期日"
    
  # 加密与压缩
  encryption:
    enabled: true
    algorithm: "AES-256-GCM"
  
  compression:
    enabled: true
    algorithm: "zstd"
    level: 3

10.4.2 灾难恢复计划

# 灾难恢复配置
disaster_recovery:
  # 恢复时间目标
  rto: "4h"  # 恢复时间目标
  rpo: "1h"  # 恢复点目标
  
  # 恢复策略
  strategies:
    - scenario: "data_corruption"
      priority: "high"
      steps:
        - "从最新备份恢复数据"
        - "验证数据完整性"
        - "重新启动服务"
      estimated_time: "2h"
    
    - scenario: "hardware_failure"
      priority: "critical"
      steps:
        - "启动备用服务器"
        - "从云备份恢复数据"
        - "切换DNS/负载均衡器"
        - "验证服务可用性"
      estimated_time: "4h"
    
    - scenario: "security_breach"
      priority: "critical"
      steps:
        - "隔离受影响系统"
        - "从干净备份恢复"
        - "轮换所有密钥"
        - "安全审计"
      estimated_time: "6h"
  
  # 恢复测试
  testing:
    schedule: "每季度"
    types:
      - tabletop_exercise
      - partial_recovery
      - full_recovery
    success_criteria:
      - rto_met: true
      - rpo_met: true
      - data_integrity: true
      - functionality: true
  
  # 文档与培训
  documentation:
    runbooks:
      - "恢复流程手册"
      - "联系人列表"
      - "供应商信息"
    training:
      frequency: "半年一次"
      participants: ["运维团队", "管理团队"]