Tommy-yw/RunbookHermes

# RunbookHermes **原生 Hermes 的 AIOps 代理，用于支付 incident 响应、证据驱动的根因分析、approval-gated 修复以及 runbook 学习。** RunbookHermes 是通过将官方 **Hermes Agent** 运行时改造为面向生产的 incident 响应系统而构建的。它保留了 Hermes Agent 的优势——运行时循环、provider 路由、tool 系统、memory、context engine、skill、gateway 和安全边界——并专门针对支付系统故障、可观测性证据收集、approval、checkpoint、rollback、恢复验证以及 runbook 知识积累等 AIOps 工作流进行了特化。 ## 产品截图 以下截图展示了当前的 RunbookHermes Web Console。请将这些图片放置在 `docs/assets/` 目录下，并保持文件名与 Markdown 路径一致。 ### AIOps Console 概览  概览页展示了高级别的 AIOps 控制平面：incident 计数、待处理 approval、生成的 skill、关键服务、推荐操作流程、当前能力边界以及实时监控预览。 ### 实时监控系统  监控页为 `payment-service`、`coupon-service` 和 `order-service` 提供了多维度的服务健康视图，包括 HTTP 状态信号、QPS、p95 延迟、服务拓扑、backend 模式和部署状态。  监控页的下半部分展示了日志信号和 trace 信号。这是 RunbookHermes 将可观测性数据与 incident 诊断相连接的地方，而不是仅仅依赖于模型猜测。 ### Incident 指挥中心  Incident 列表页规范化了从 Web、Alertmanager、Feishu、WeCom 或 API 入口创建的 incident。它展示了服务、状态、严重程度、根因、创建时间以及快速创建 incident 的操作。 ### Incident 详情：证据与执行摘要  Incident 详情页展示了来自指标、日志和 trace 的证据卡片，以及包含根因、建议操作、证据 ID、置信度和 approval 状态的执行摘要。 ### Incident 详情：根因与模型辅助摘要  根因标签页将确定性证据与可选的模型辅助解释分离开来。模型摘要只有在配置了模型 provider 时才会启用。 ### Incident 详情：操作、Approval 与 Checkpoint  高风险操作不会被盲目执行。RunbookHermes 将写入或破坏性操作置于 approval、checkpoint、dry-run、受控执行和恢复验证的管控之下。 ### Incident 详情：时间线  时间线记录了完整的 incident 生命周期，包括 incident 创建、证据收集、假设生成、行动计划制定、checkpoint 创建、approval 请求、approval 决策、skill 生成和执行结果。 ### Incident 详情：生成的 Runbook Skill  在处理完 incident 后，RunbookHermes 可以将运维经验转化为可复用的 runbook skill。这就是 incident 处理如何成为积累的运维知识，而不是一次性响应的过程。 ### Approval 中心  Approval 中心是人工介入的安全门控。运维人员可以在批准或拒绝执行之前审查操作、风险等级、checkpoint 和 payload。 ### 摘要与 Skill  摘要页总结了近期的 incident、高频故障以及生成的 runbook skill，使 RunbookHermes 在 incident 响应和运维审查中都非常有用。 ### 集成就绪与接口状态  设置页显示了模型、可观测性、执行、Feishu、WeCom 及其他生产集成接口是否已配置。它还记录了连接真实系统所需的环境变量。 ## 为什么选择 RunbookHermes 大多数 AI Agent 项目仅停留在聊天、检索或简单的工作流自动化上。真正的 incident 响应需要的远不止于此： * 从监控、日志、trace 和部署中可靠地收集证据； * 上下文压缩，以便模型基于证据而非原始日志噪音进行推理； * 能够记住有用运维经验的 memory，而不是把每一条历史记录都塞入 prompt 中； * 受 schema、allowlist 和安全策略管控的 tool； * 在执行高风险生产操作之前进行 approval 和 checkpoint； * 修复后的恢复验证； * runbook skill 生成，以便成功的操作能转化为可复用的知识。 创建 RunbookHermes 的目的就是将 Hermes Agent 转化为这种类型的 incident 响应 agent。 ## RunbookHermes 继承自 Hermes Agent 的内容 RunbookHermes 的价值在于它并非作为一个简单的规则引擎从头构建。它基于 Hermes Agent 的架构，并将这些能力适配到了 AIOps 领域。 | Hermes Agent 能力 | RunbookHermes 适配 | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Agent 运行时 / 循环 | 用作 `runbook-hermes` 配置文件的核心 agent 基础。 | | Provider / 模型路由 | 保留了 Hermes 风格的模型 provider 灵活性，并增加了兼容 OpenAI 的模型摘要集成，用于 incident 分析。 | | Tool 系统 | 添加了用于 Prometheus、Loki、Jaeger/Trace、部署历史、approval、rollback 和恢复验证的 incident 响应 tool。 | | Memory provider | 为服务概况、incident 摘要、团队偏好和 skill 索引添加了 `IncidentMemory`。 | | Context engine | 添加了 `EvidenceStack`，这是一个以证据为中心的 context engine，用于 alert、证据、假设、操作和最终答案压缩。 | | Skill | 添加了诸如支付 HTTP 503 分流和常见 incident 分流等 runbook skill。 | | Gateway 架构 | 为 incident 工作流增加了 Alertmanager、Feishu、WeCom 和 Web/API 入口路径。 | | 安全边界 | 围绕高风险操作增加了 approval、checkpoint、dry-run、受控执行和恢复验证。 | | 执行 backend 概念 | 增加了本地参考 rollback 以及诸如 `custom_http`、Kubernetes 和 Argo CD 风格适配器的生产 executor 接口。 | 目标并不是将 Hermes 的每一个功能克隆到一个仪表板中。目标是保留 Hermes Agent 的优势，并将其转化为一个具有运维意义的 AIOps 系统。 ## 核心能力 ### 1. Incident 接入 RunbookHermes 可以通过多个入口点接收 incident 信号： * Web Console * Alertmanager webhook * Feishu 事件和卡片回调 shell * WeCom 事件和卡片回调 shell * 通过 `runbook-hermes` 进入的 Hermes profile * 用于 incident 创建和重放的 API endpoint 所有入口都被规范化为一个 incident 命令，以便不同的来源可以流入相同的 agent 工作流。 ### 2. 证据收集 RunbookHermes 从以下来源收集证据： * Prometheus 指标 * Loki 日志 * Jaeger / Trace backend * 部署记录 * 特定服务的 profile * 之前的 incident 摘要 * Runbook skill 当前代码包含了真实的适配器接口和一个用于验证集成路径的本地参考支付环境。 ### 3. EvidenceStack 上下文引擎 Incident 响应会产生过多的原始上下文：日志、指标样本、trace、tool 输出、部署记录、approval 和时间线。RunbookHermes 不会将所有这些都倾倒入 prompt 中。 相反，`EvidenceStack` 将上下文组织为： * alert 摘要 * 关键证据 * 假设 * 行动计划 * 最终答案 它保留了证据 ID 和摘要，同时避免了在长时间运行的推理上下文中出现大量原始日志和 trace payload。 ### 4. IncidentMemory RunbookHermes 使用特定领域的 memory provider 进行 incident 响应。 它能记住稳定的运维知识，例如： * 服务概况； * 团队偏好； * incident 摘要； * 反复出现的根因； * 生成的 runbook skill； * 高风险操作的 approval 要求。 它不会把 memory 当作“保存整个聊天历史”。它被设计为在正确的时间回忆起正确的运维事实。 ### 5. 模型辅助分析 RunbookHermes 通过兼容 OpenAI 的 endpoint 支持模型辅助的 incident 摘要。 该模型用于提高分析的可读性以及面向运维人员的摘要质量，同时保持证据链和安全门控的显式性。 典型的模型辅助输出： * incident 摘要； * 最可能的根因解释； * 证据链解释； * 面向运维人员的行动摘要； * postmortem 草稿材料。 ### 6. Approval-Gated 修复 RunbookHermes 将破坏性操作视为受控操作。 诸如 rollback、restart 或配置变更等高风险操作应通过以下步骤： 1. 行动策略检查； 2. approval 请求； 3. checkpoint 创建； 4. dry-run； 5. 受控执行； 6. 恢复验证； 7. 审计时间线。 这是 RunbookHermes 构建在 Hermes 风格的安全边界之上，而不是作为一个简单的脚本运行器的主要原因之一。 ### 7. 实时监控仪表板 Web Console 包含了一个实时监控视图，用于展示： * 服务健康矩阵； * HTTP 503 / 504 / 429 信号； * p95 延迟； * QPS； * 日志信号； * trace 信号； * 部署状态； * 拓扑视图； * 用于 Prometheus、Loki、Trace、Deploy、模型、Feishu、WeCom 以及受控执行的 backend 状态。 ## 仓库布局 ``` runbook-hermes/ ├── agent/ # Hermes Agent upstream runtime code ├── gateway/ # Hermes upstream gateway foundation ├── hermes_cli/ # Hermes CLI components ├── profiles/runbook-hermes/ # RunbookHermes Hermes profile and persona ├── plugins/runbook-hermes/ # RunbookHermes tool plugin ├── plugins/memory/incident_memory/ # IncidentMemory provider ├── plugins/context_engine/evidence_stack/ # EvidenceStack context engine ├── runbook_hermes/ # RunbookHermes domain logic ├── apps/runbook_api/ # FastAPI Web/API service ├── web/static/ # Web Console pages ├── integrations/observability/ # Prometheus / Loki / Trace / Deploy adapters ├── toolservers/observability_mcp/ # Observability toolserver boundary ├── skills/runbooks/ # Runbook skills ├── demo/payment_system/ # Local reference payment environment ├── data/payment_demo/ # Reference deploy state and runtime version ├── data/runbook_mock/ # Mock observability data for local fallback ├── scripts/ # Validation and smoke scripts └── docs/ # Architecture, deployment, integration, operations docs ``` ## 部署模式 应将 RunbookHermes 理解为一个合并的代码库： ``` Hermes Agent upstream source + RunbookHermes AIOps extension layer = RunbookHermes ``` 你**不需要**“先部署官方 Hermes Agent”，然后再将 RunbookHermes 作为一个独立的不相关应用进行部署。你要部署的是合并后的 RunbookHermes 仓库，并运行你需要的入口点。 ### 模式 A：仅 Web/API 使用此模式检查 Web Console、incident 页面、approval、监控 UI、设置和 API 接口。 ``` set PYTHONPATH=. python -m uvicorn apps.runbook_api.app.main:app --host 127.0.0.1 --port 8000 ``` 打开： ``` http://127.0.0.1:8000/web/index.html http://127.0.0.1:8000/web/monitoring.html http://127.0.0.1:8000/web/incidents.html http://127.0.0.1:8000/web/approvals.html http://127.0.0.1:8000/docs ``` ### 模式 B：本地参考支付环境 使用此模式结合本地支付系统和可观测性栈来验证完整的 incident 响应路径。 ``` cd demo/payment_system docker compose up --build ``` 这会启动一个包含以下内容的本地参考环境： * payment-service * order-service * coupon-service * MySQL * Redis * Prometheus * Loki * Promtail * Jaeger * Grafana 然后配置 RunbookHermes 使用真实的本地可观测性适配器： ``` set OBS_BACKEND=real set DEPLOY_BACKEND=demo_file set TRACE_BACKEND=jaeger set TRACE_PROVIDER_KIND=jaeger set ROLLBACK_BACKEND_KIND=demo_file set RUNBOOK_CONTROLLED_EXECUTION_ENABLED=true set PROMETHEUS_BASE_URL=http://127.0.0.1:9090 set LOKI_BASE_URL=http://127.0.0.1:3100 set TRACE_BASE_URL=http://127.0.0.1:16686 set DEMO_DEPLOY_STATE_FILE=data/payment_demo/deployments.json set DEMO_VERSION_FILE=data/payment_demo/runtime/payment-service-version.txt ``` 启动 Web/API 服务： ``` set PYTHONPATH=. python -m uvicorn apps.runbook_api.app.main:app --host 127.0.0.1 --port 8000 ``` 生成参考流量： ``` cd demo/payment_system python scripts/generate_traffic.py --fault PAYMENT_503_AFTER_DEPLOY --requests 60 python scripts/generate_traffic.py --fault COUPON_504_TIMEOUT --requests 40 python scripts/generate_traffic.py --fault ORDER_429_RATE_LIMIT --requests 40 ``` 这些场景不是最终目标。它们是一个本地参考环境，用于证明 RunbookHermes 如何连接到真实系统。 ### 模式 C：面向生产的部署 在面向生产的部署中，RunbookHermes 应作为一组服务运行： ``` [Alertmanager] | v [RunbookHermes API / Gateway] | +--> Hermes Agent Runner with runbook-hermes profile +--> Model Provider +--> Prometheus +--> Loki +--> Jaeger / Tempo +--> Deploy / Rollback System +--> Feishu / WeCom +--> Incident Store +--> Redis / Queue +--> Audit Log ``` 推荐的生产组件： * `runbookhermes-api`：FastAPI Web/API 和 webhook 服务； * `runbookhermes-agent`：使用 `runbook-hermes` 配置文件的 Hermes runner； * `incident-store`：SQLite / MySQL / PostgreSQL，替代本地 JSON 存储； * `redis`：队列 / 缓存 / approval 状态支持； * `model-provider`：兼容 OpenAI 或内部模型的 endpoint； * `observability`：Prometheus, Loki, Jaeger / Tempo； * `messaging`：Feishu / WeCom 回调； * `executor`：受控的修复适配器，例如 custom HTTP、Kubernetes 或 Argo CD。 ## 我在哪里与 Agent 对话？ RunbookHermes 拥有不同的交互界面。 ### 1. Hermes CLI / Agent Profile 用于直接的 agent 交互： ``` hermes --profile runbook-hermes ``` 当你想要原生 Hermes 对话循环时使用此选项。 示例 prompt： ``` payment-service HTTP 503 is rising after release. Please collect evidence first, then explain the most likely root cause and propose a safe action plan. ``` ### 2. Web Console Web Console 主要不是聊天 UI。它是运维人员的控制平面： * incident 列表； * 实时监控； * 证据卡片； * RCA 结果； * 行动计划； * approval； * checkpoint； * 恢复验证； * 生成的 skill； * 模型辅助摘要。 ### 3. Feishu / WeCom Feishu 和 WeCom 适配器旨在用于生产消息集成： * 从消息或 alert 创建 incident； * 显示 RCA 卡片； * 批准或拒绝高风险操作； * 链接回 Web Console。 ### 4. Alertmanager / API Alertmanager 和 API 入口点是为系统到 agent 的 incident 接入而设计的。 ## 模型 Provider 设置 RunbookHermes 可以使用兼容 OpenAI 的 endpoint 进行模型辅助摘要。 使用 Open 或任何兼容模型 provider 的示例： ``` set RUNBOOK_MODEL_ENABLED=true set RUNBOOK_MODEL_BASE_URL=https://openrouter.ai/api/v1 set RUNBOOK_MODEL_API_KEY=your_api_key set RUNBOOK_MODEL_NAME=your_model_name ``` 模型输出用于可读的 incident 摘要和面向运维人员的解释。证据收集、approval 边界和修复策略保持显式且可检查。 ## 可观测性集成 配置真实的可观测性 backend： ``` set OBS_BACKEND=real set PROMETHEUS_BASE_URL=http://prometheus.example.com set LOKI_BASE_URL=http://loki.example.com set TRACE_BACKEND=jaeger set TRACE_PROVIDER_KIND=jaeger set TRACE_BASE_URL=http://jaeger.example.com ``` RunbookHermes 使用这些适配器： * `integrations/observability/prometheus_backend.py` * `integrations/observability/loki_backend.py` * `integrations/observability/trace_backend.py` * `integrations/observability/deploy_backend.py` ## Feishu / WeCom 集成 RunbookHermes 包含用于 Feishu 和 WeCom 的 gateway shell。 Feishu 环境变量： ``` set FEISHU_APP_ID= set FEISHU_APP_SECRET= set FEISHU_VERIFICATION_TOKEN= set FEISHU_ENCRYPT_KEY= set FEISHU_CALLBACK_BASE_URL= set FEISHU_BOT_WEBHOOK_URL= set FEISHU_BOT_SECRET= ``` WeCom 环境变量： ``` set WECOM_CORP_ID= set WECOM_AGENT_ID= set WECOM_SECRET= set WECOM_TOKEN= set WECOM_ENCODING_AES_KEY= set WECOM_CALLBACK_BASE_URL= ``` 生产使用需要公共回调路由、签名验证、加密处理、权限设置和卡片回调验证。 ## 受控修复 RunbookHermes 围绕安全的生产执行而非盲目自动化进行设计。 支持的修复边界： ``` action policy → approval → checkpoint → dry-run → controlled execution → recovery verification → audit timeline ``` 本地参考执行可通过支付参考环境使用。生产执行应通过受控的 executor 连接： ``` set ACTION_EXECUTION_BACKEND=custom_http set ACTION_EXECUTION_API_BASE_URL=https://executor.example.com set ACTION_EXECUTION_API_TOKEN=your_token set ACTION_EXECUTION_TIMEOUT_SECONDS=5 ``` 其他可能的 executor 类型： * Kubernetes controlled API * Argo CD * Argo Rollouts * 内部发布平台 * custom HTTP 修复 gateway ## 验证 从仓库根目录运行验证脚本： ``` set PYTHONPATH=. python -S scripts/runbook_validate.py python -S scripts/runbook_gateway_smoke.py python -S scripts/runbook_no_legacy_imports.py python -S scripts/runbook_monitoring_validate.py python -S scripts/runbook_stage8_validate.py ``` ## 当前状态 RunbookHermes 目前提供： * 原生 Hermes 的 RunbookHermes profile； * incident 响应 tool 插件； * IncidentMemory provider； * EvidenceStack 上下文引擎； * Web Console 和监控仪表板； * 本地参考支付环境； * Prometheus / Loki / Jaeger 适配器层； * Feishu / WeCom gateway shell； * 模型辅助摘要 shell； * approval + checkpoint + 受控本地 rollback； * 面向生产的 executor 接口。 推荐的下一步强化措施： * 用 SQLite / MySQL / PostgreSQL 替换本地 JSON 存储； * 添加 Memory 浏览器页面； * 添加 Skill Forge 页面； * 完成 Feishu / WeCom 的生产回调验证； * 连接真实的模型 provider； * 连接真实的部署 / rollback executor； * 添加 Kubernetes / Docker Compose 生产部署清单； * 添加 RBAC 和审计持久化。 ## 路线图 参见 [ROADMAP.md](ROADMAP.md)。 高层路线图： * v0.1：原生 Hermes 的 incident 响应基础 * v0.2：更强大的 memory、skill 和监控 UI * v0.3：生产可观测性集成 * v0.4：Feishu / WeCom 生产消息工作流 * v0.5：受控的 Kubernetes / Argo 修复参考 * v1.0：生产参考架构 ## 致谢 RunbookHermes 是基于 Nous Research 的 **Hermes Agent** 构建的。 本项目保留了 Hermes Agent 的基础，并添加了一个用于支付系统故障排查、可观测性集成、approval-gated 修复和 runbook 学习的 AIOps / incident 响应层。 上游的 Hermes README 和发布说明保留在 `docs/upstream/` 目录下，用于归属和参考。 ## 许可证 本仓库保留了上游的 Hermes Agent 许可证。参见 [LICENSE](LICENSE)。 除非另有说明，RunbookHermes 的新增内容遵循与仓库相同的许可证。

标签：AIOps, Alertmanager, API网关, API集成, Hermes Agent, LLM Agent, P95延迟, QPS, Runbook, Web Console, 企业微信集成, 剧本编排, 可观测性, 告警管理, 回滚恢复, 大模型智能体, 安全边界, 审批流, 微服务监控, 搜索引擎查询, 支付系统, 故障自愈, 智能运维, 服务拓扑, 根因分析, 生产环境, 知识积累, 自定义请求头, 请求拦截, 运维大模型, 运维自动化, 逆向工具, 链路追踪, 飞书集成