telemetryflow/telemetryflow-hermes

## 功能简介 四个 AI agent 组成一个团队来响应生产事件。每个 agent 都是一个质疑其他成员的专家——就像科学家辩论证据一样。 ``` Alert → Triage → Investigator → Reviewer → Remediator → Human Approves → Fixed ``` 1. **Triage** 对告警进行分类（真实的、已知的、噪音、不完整的） 2. **Investigator** 从指标、日志、traces、exemplars 中收集证据 3. **Reviewer** 独立审查调查过程以防止偏见 4. **Remediator** 提出修复建议——由人工通过 Telegram 批准 你只需参与第 5 步。步骤 1–4 是完全自动化的。 ## 快速开始 ``` git clone https://github.com/telemetryflow/telemetryflow-hermes.git cd telemetryflow-hermes # 首次设置（安装 hermes + 配置一切） make init # 编辑你的 API keys vim ~/.hermes/.env # 验证其是否有效 make verify # 启动 agents make deploy ``` 这样就完成了。`make init` 负责一切：安装 Hermes Agent、复制配置、设置 4 个 agent 配置文件、29 个技能、37 个插件工具、cron 作业和生命周期钩子。 ## Makefile 命令 ### 设置与部署 | 命令 | 功能说明 | | ---------------- | --------------------------------------------------------------- | | `make init` | 首次设置：安装 hermes + 配置 + 部署 | | `make configure` | 将配置文件、技能、插件、cron、钩子安装到 `~/.hermes/` | | `make deploy` | 启动所有 4 个 Telegram agent 网关 | | `make stop` | 停止所有 agent 网关 | | `make status` | 检查网关状态 | | `make verify` | 端到端 pipeline 验证 | | `make doctor` | 运行 `hermes doctor --fix` | ### Docker | 命令 | 功能说明 | | ----------------- | -------------------------------------------------------------- | | `make docker-build` | 构建 Docker 镜像 | | `make docker-up` | 启动容器（使用 `PROFILE=core make docker-up` 启动完整技术栈） | | `make docker-down` | 停止所有容器 | | `make docker-logs` | 跟踪查看 Hermes 容器日志 | ### 开发 | 命令 | 功能说明 | | ---------------- | ------------------------------------------ | | `make test` | 运行所有测试（单元测试 + 集成测试） | | `make test-cov` | 运行测试并生成覆盖率报告（要求达到 95%+） | | `make lint` | 运行 ruff linter | | `make fmt` | 使用 ruff 格式化代码 | | `make typecheck` | 运行 mypy 类型检查器 | | `make check` | 所有质量检查（格式化 + lint + 类型检查） | | `make ci` | 在本地运行完整 CI pipeline | | `make clean` | 移除已安装的组件和构建产物 | ## 配置 将 `.env.example` 复制到 `~/.hermes/.env` 并填写： ``` # 必需 TELEMETRYFLOW_API_KEY=tfs_xxxxx # API Key TELEMETRYFLOW_API_URL=http://localhost:3000/api/v2 # Platform URL TELEMETRYFLOW_ORGANIZATION_ID=your-org-uuid # For LLM endpoints TELEMETRYFLOW_WORKSPACE_ID=your-workspace-uuid # For telemetry queries # Agent LLM Keys ANTHROPIC_API_KEY=sk-ant-xxxxx # Investigator (claude-sonnet-4-5) ZHIPU_API_KEY=your-zhipu-key # Triage/Reviewer/Remediator (glm-5.1) # 数据库（由 PostgreSQL + ClickHouse 共享） TELEMETRYFLOW_DB_NAME=telemetryflow_db # Default database name ``` 三种认证方式：API Key (`tfs_*`)、JWT 登录、Ingestion Headers。有关所有选项，请参见 [.env.example](./.env.example)。 ## Agent 团队 | Agent | 模型 | 任务 | 轮数 | 访问权限 | | ---------------- | ----------------- | -------------------------------------- | ----- | -------------- | | **Triage** | glm-5.1 | 告警分类，质疑信号真实性 | 30 | 只读 | | **Investigator** | claude-sonnet-4-5 | 收集证据，形成根因假设 | 45 | 只读 | | **Reviewer** | glm-5.1 | 审查调查过程，寻找偏见 | 20 | 只读 | | **Remediator** | glm-5.1 | 提出修复方案，等待人工批准 | 15 | 写入（受控） | ### Agent 性格设定 每个 agent 都遵循**零幻觉**原则和**对抗性思维**运行： - **Triage**：偏执的守门人。在证明告警真实之前，假定所有告警都是谎言。绝不猜测。 - **Investigator**：充满敌意的科学家。将每个假设视为有罪，直到被数据证明无罪。反复盘问自己的发现。 - **Reviewer**：魔鬼代言人。积极寻找调查过程出错的原因。只有三种裁决：CONFIRMED / NEEDS_MORE_EVIDENCE / REJECTED。 - **Remediator**：谨慎的实用主义者。在没有明确的裁决前拒绝采取行动。第一个问题永远是：“如果我错了，会破坏什么？” ## 40 个插件工具（涵盖所有 20 个 TFO 模块） 所有工具仅使用 Python 标准库——零 pip 依赖，零供应链风险。 | 类别 | 数量 | 工具 | | -------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | 核心 Telemetry | 5 | `query_metrics`, `search_logs`, `list_traces`, `get_exemplars`, `query_correlations` | | 监控 | 8 | `check_k8s`, `check_infra`, `check_uptime`, `check_vm`, `check_agent`, `check_service_map`, `check_network_map`, `check_db_monitoring` | | AI & LLM | 7 | `chat_with_context`, `stream_chat`, `manage_conversation`, `generate_insight`, `query_llm_usage`, `manage_provider`, `query_ai_intelligence` | | 平台 | 8 | `query_platform`, `query_account`, `query_audit`, `query_subscription`, `manage_dashboards`, `manage_alerts`, `manage_reports`, `manage_data_masking` | | 基础设施 | 6 | `manage_retention`, `manage_tenancy`, `manage_iam`, `manage_sso`, `query_tfql`, `check_uptime` (扩展版) | | 故障修复 | 3+1 | `scale_deployment` ⚠, `restart_pod` ⚠, `rollback_deploy` ⚠ + `update_alert` ⚠ | | RCA 与复盘 | 3 | `generate_rca_report`, `generate_postmortem`, `generate_rca_template` | ⚠ = 需要人工批准 ## 成本 | Agent | 成本/事件 | | -------------------------------- | ------------------------- | | Triage (glm-5.1) | ~$0.01 | | Investigator (claude-sonnet-4-5) | ~$0.05-0.15 | | Reviewer (glm-5.1) | ~$0.03-0.08 | | Remediator (glm-5.1) | ~$0.01-0.03 | | **总计** | **~$0.10-0.27/事件** | ## 架构 ``` graph TB subgraph Alert["Alert Sources"] TF["TelemetryFlow Alert Engine"] end subgraph Agents["Hermes Agent Team"] T["Triage
glm-5.1"] I["Investigator
claude-sonnet-4-5"] R["Reviewer
glm-5.1"] M["Remediator
glm-5.1"] end subgraph Tools["40 Plugin Tools"] MT["Metrics · Logs · Traces · Exemplars"] K8["K8s · Infra · DB · VM · Agent"] LM["LLM Chat · Insights · Providers"] RM["Scale · Restart · Rollback ⚠"] end subgraph TFO["TelemetryFlow Platform"] API["TFO API /api/v2/*"] CH[("ClickHouse")] end subgraph Human["Human"] TG["Telegram"] end TF --> T --> I --> R --> M --> TG Agents --> Tools --> API --> CH style Agents fill:#e0f2fe style Tools fill:#ddd6fe style TFO fill:#d1fae5 style Human fill:#fef3c7 ``` ## 项目统计 | 指标 | 数量 | | ------------------ | ---------------------------- | | Agent 配置文件 | 4 | | 插件工具 | 40 | | TFO 模块 | 20 (全部) | | 内置技能 | 29 | | 技能类别 | 18 | | Context Types | 74 | | Provider Types | 15 | | Cron 作业 | 6 | | 生命周期钩子 | 3 | | 测试 | 472 (覆盖率 97%) | | 文档页面 | 28+ | | CI/CD Pipelines | 3 (GitHub + Docker + GitLab) | | 外部依赖 | 0 | ## 安全性 - **只读 ClickHouse** — 使用 `hermes_readonly` 用户，对 20 张表具有表级 SELECT 权限 - **Human-in-the-loop** — 4 个修复工具需要人工批准（600 秒超时 → 自动上报升级） - **90 轮硬性上限** — 防止死循环失控 - **强制要求 `workspace_id`** — 防止跨租户数据泄露 - **Reviewer 独立上下文** — 防止调查偏见 - **仅使用 Python 标准库** — 零供应链风险 - **密钥仅存放在 `.env` 中** — 绝不写入 `config.yaml` - **动态数据库名称** — 通过 `TELEMETRYFLOW_DB_NAME` 环境变量设置，绝不硬编码 ## 文档 | 文档 | 描述 | | ------------------------------------------------------------ | --------------------------------- | | [架构](./docs/architecture.md) | 系统设计、数据流、图表 | | [快速入门](./docs/getting-started.md) | 安装和首次调查 | | [工具参考](./docs/tools/reference.md) | 包含参数的所有 37 个工具 | | [LLM 模块](./docs/api/llm-module.md) | TFO LLM API 集成 | | [Context Types](./docs/api/context-types.md) | 所有 74 个 ContextType 值 | | [部署](./docs/deployment/README.md) | 标准部署、Docker、物理隔离环境 | | [安全性](./docs/security/README.md) | 分层安全模型 | | [故障排除](./docs/operations/troubleshooting.md) | 常见问题与解决方案 | | [环境变量](./docs/configuration/environment.md) | 完整的 `.env` 参考 | ## 许可证 Apache-2.0 — 详见 [LICENSE](./LICENSE)。 **由 Telemetri Data Indonesia 用 ❤️ 构建**

标签：API集成, ClickHouse, Python, 人工智能, 可观测性, 告警响应, 无后门, 测试用例, 用户模式Hook绕过, 请求拦截, 逆向工具