diff --git a/README.md b/README.md index aa9e312..2c0d628 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,18 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/Tracer-Cloud/opensre) · [上游 README](https://github.com/Tracer-Cloud/opensre/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +

OpenSRE

-

OpenSRE v0.1: Build Your Own AI SRE Agents

+

OpenSRE v0.1：构建你自己的 AI SRE 智能体

-

The open-source framework for AI SRE agents, and the training and evaluation environment they need to improve. Connect the 60+ tools you already run, define your own workflows, and investigate incidents on your own infrastructure.

+

面向 AI SRE 智能体的开源框架，以及它们持续改进所需的训练与评估环境。连接你已运行的 60+ 种工具，定义自己的工作流，并在自有基础设施上调查事故。

CI status @@ -29,10 +35,10 @@

- Quickstart · - Docs · - FAQ · - Security + 快速入门 · + 文档 · + 常见问题 · + 安全

@@ -40,78 +46,78 @@ --- -> 🚧 Public Alpha: Core workflows are usable for early exploration, though not yet fully stable. The project is in active development, and APIs and integrations may evolve +> 🚧 公开 Alpha：核心工作流可用于早期探索，但尚未完全稳定。项目正在积极开发中，API 与集成可能会演进 --- -## Table of Contents +## 目录 -- [Why OpenSRE?](#why-opensre) -- [Install](#install) -- [Quick Start](#quick-start) -- [Deployment](#deployment) -- [How OpenSRE Works](#how-opensre-works) -- [Benchmark](#benchmark) -- [Capabilities & integrations](#capabilities--integrations) -- [Contributing & development](#contributing--development) -- [Security](#security) -- [Telemetry](#telemetry) -- [License](#license) -- [Citations](#citations) +- [为什么选择 OpenSRE？](#why-opensre) +- [安装](#install) +- [快速入门](#quick-start) +- [部署](#deployment) +- [OpenSRE 工作原理](#how-opensre-works) +- [基准测试](#benchmark) +- [能力与集成](#capabilities--integrations) +- [贡献与开发](#contributing--development) +- [安全](#security) +- [遥测](#telemetry) +- [许可证](#license) +- [引用](#citations) --- -## Why OpenSRE? +## 为什么选择 OpenSRE？ -When something breaks in production, the evidence is scattered across logs, metrics, traces, runbooks, and Slack threads. OpenSRE is an open-source framework for AI SRE agents that resolve production incidents, built to run on your own infrastructure. +当生产环境出现问题时，证据分散在日志、指标、链路追踪、运行手册（runbook）和 Slack 讨论串中。OpenSRE 是一个用于解决生产事故的开源 AI SRE 智能体框架，专为在自有基础设施上运行而构建。 -We do that because SWE-bench1 gave coding agents scalable training data and clear feedback. Production incident response still lacks an equivalent. +我们这样做，是因为 SWE-bench1 为编码智能体提供了可扩展的训练数据和清晰的反馈。生产事故响应仍缺少同等的基础设施。 -Distributed failures are slower, noisier, and harder to simulate and evaluate than local code tasks, which is why AI SRE, and AI for production debugging more broadly, remains unsolved. +分布式故障比本地代码任务更慢、更嘈杂、更难模拟和评估，这也是 AI SRE，以及更广泛的面向生产调试的 AI，仍未被解决的原因。 -OpenSRE is building _that_ missing layer: +OpenSRE 正在构建_这一_缺失的层次： -> an open reinforcement learning environment for agentic infrastructure incident response, with end-to-end tests and synthetic incident simulations for realistic production failures +> 面向智能体基础设施事故响应的开放强化学习环境，配备端到端测试和合成事故模拟，以复现真实的生产故障 -We do that by: +我们通过以下方式实现： -- building easy-to-deploy, customizable AI SRE agents for production incident investigation and response -- running scored synthetic RCA suites that check root-cause accuracy, required evidence, and adversarial red herrings [(tests/synthetic)](tests/synthetic/rds_postgres) -- running real-world end-to-end tests across cloud-backed scenarios including Kubernetes, EC2, CloudWatch, Lambda, ECS Fargate, and Flink [(tests/e2e)](tests/e2e) -- keeping semantic test-catalog naming so e2e vs synthetic and local vs cloud boundaries stay obvious [(tests/README.md)](tests/README.md) +- 构建易于部署、可定制的 AI SRE 智能体，用于生产事故调查与响应 +- 运行带评分的合成 RCA（根因分析）套件，检验根因准确性、所需证据以及对抗性干扰项（红鲱鱼）[(tests/synthetic)](tests/synthetic/rds_postgres) +- 在涵盖 Kubernetes、EC2、CloudWatch、Lambda、ECS Fargate 和 Flink 等云支撑场景的真实端到端测试中运行 [(tests/e2e)](tests/e2e) +- 保持语义化的测试目录命名，使 e2e 与 synthetic、本地与云之间的边界一目了然 [(tests/README.md)](tests/README.md) -Our mission is to build AI SRE agents on top of this, scale it to thousands of realistic infrastructure failure scenarios, and establish OpenSRE as the benchmark and training ground for AI SRE. +我们的使命是在此之上构建 AI SRE 智能体，将其扩展到数千种真实的基础设施故障场景，并将 OpenSRE 确立为 AI SRE 的基准与训练场。 1 https://arxiv.org/abs/2310.06770 --- -## Install +## 安装 -The root installer URL auto-detects Unix shell vs PowerShell and installs the latest build from `main`. OpenSRE moves quickly, so `main` is the latest stable version for normal installs. +根安装器 URL 会自动检测 Unix shell 与 PowerShell，并从 `main` 安装最新构建。OpenSRE 迭代很快，因此 `main` 是常规安装的最新稳定版本。 -macOS / Linux: +macOS / Linux： ```bash curl -fsSL https://install.opensre.com | bash ``` -The macOS/Linux installer does not require sudo. If no writable bin directory is already on `PATH`, it installs to `~/.local/bin` and prints the shell command to apply the PATH update. +macOS/Linux 安装器不需要 sudo。若 `PATH` 上尚无可写的 bin 目录，则会安装到 `~/.local/bin`，并打印用于更新 PATH 的 shell 命令。 -Equivalent explicit main-channel form: +等价的显式 main 渠道形式： ```bash curl -fsSL https://install.opensre.com | bash -s -- --main ``` -Homebrew: +Homebrew： ```bash brew tap tracer-cloud/tap brew install tracer-cloud/tap/opensre ``` -Windows (PowerShell): +Windows（PowerShell）： ```powershell irm https://install.opensre.com | iex @@ -132,31 +138,31 @@ Configure once, then pick how you want to run investigations: opensre onboard ``` -**Interactive shell** — with no subcommand, `opensre` starts a REPL (TTY required). Describe incidents in plain language, stream investigations, and use slash commands for session control (`/help`, `/status`, `/cost`, `/sessions`, `/resume`, `/compact`, `/new`, `/exit`), integrations (`/integrations list`, `/integrations verify`), local agent fleet monitoring (`/agents`), and reasoning depth (`/effort` for **OpenAI** and **Codex** — `low` through `max`). Ctrl+C cancels an in-flight investigation without losing session state. See **[interactive shell commands](https://www.opensre.com/docs/interactive-shell-commands)** for the full reference. +**交互式 shell** — 不带子命令时，`opensre` 会启动 REPL（需要 TTY）。用自然语言描述事故、流式输出调查过程，并使用斜杠命令进行会话控制（`/help`、`/status`、`/cost`、`/sessions`、`/resume`、`/compact`、`/new`、`/exit`）、集成（`/integrations list`、`/integrations verify`）、本地智能体集群监控（`/agents`）以及推理深度（**OpenAI** 与 **Codex** 使用 `/effort` — `low` 至 `max`）。Ctrl+C 可取消进行中的调查，且不会丢失会话状态。完整参考见 **[交互式 shell 命令](https://www.opensre.com/docs/interactive-shell-commands)****。 ```bash opensre ``` -**One-shot investigation** — run the agent once against an alert file: +**一次性调查** — 针对告警文件运行智能体一次： ```bash opensre investigate -i tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json ``` -**Remote runtime investigation** — investigate a deployed service by name (live health, logs, and deployment status): +**远程运行时调查** — 按名称调查已部署的服务（实时健康状态、日志与部署状态）： ```bash opensre investigate --service api-backend ``` -**Hermes log watch** — tail a Hermes `errors.log`, classify incidents, and optionally alert on Telegram: +**Hermes 日志监视** — 跟踪 Hermes `errors.log`，对事故进行分类，并可选择通过 Telegram 告警： ```bash opensre hermes watch ``` -Other useful commands: +其他实用命令： ```bash opensre integrations setup @@ -167,19 +173,19 @@ opensre uninstall # remove opensre and all local data --- -## Deployment +## 部署 -Two primary AWS EC2 paths and a general hosted option: +两条主要的 AWS EC2 路径，以及一个通用托管选项： -- **EC2 (Docker/ECR):** `make build-image` then `make deploy` — runs `opensre-web` and `opensre-gateway` containers on one instance. -- **Gateway (AMI + systemd):** `make bake-gateway` then `make deploy-gateway` — Telegram gateway only, no Docker, baked into a custom AMI. -- **Hosted (Railway / ECS / Vercel):** deploy with the repo `Dockerfile`; set `LLM_PROVIDER` and the matching API key (see [`.env.example`](.env.example)), plus `DATABASE_URI` and `REDIS_URI` if persistence is needed. +- **EC2（Docker/ECR）：** `make build-image`，然后 `make deploy` — 在同一实例上运行 `opensre-web` 与 `opensre-gateway` 容器。 +- **Gateway（AMI + systemd）：** `make bake-gateway`，然后 `make deploy-gateway` — 仅 Telegram 网关，无需 Docker，内置于自定义 AMI。 +- **托管（Railway / ECS / Vercel）：** 使用仓库中的 `Dockerfile` 部署；设置 `LLM_PROVIDER` 及对应的 API 密钥（见 [`.env.example`](.env.example)），若需持久化还需设置 `DATABASE_URI` 与 `REDIS_URI`。 -**[Full deployment steps and prerequisites → DEPLOYMENT.md](DEPLOYMENT.md)** +**[完整部署步骤与前置条件 → DEPLOYMENT.md](DEPLOYMENT.md)** --- -## How OpenSRE Works +## OpenSRE 工作原理 opensre-how-it-works-github -When an alert fires, OpenSRE automatically: +当告警触发时，OpenSRE 会自动： -1. **Fetches** the alert context and correlated logs, metrics, traces, and recent deploys -2. **Masks** sensitive identifiers (optional) before external LLM calls -3. **Reasons** across your connected systems to test hypotheses in a tool-calling loop -4. **Generates** a structured investigation report with probable root cause and linked evidence -5. **Suggests** next steps and, optionally, executes remediation actions -6. **Posts** a summary directly to Slack, PagerDuty, or Telegram — no context switching needed +1. **获取**告警上下文及关联的日志、指标、追踪（trace）和近期部署信息 +2. 在外部 LLM 调用前（可选）**掩码处理**敏感标识符 +3. 在工具调用循环中，跨已连接系统进行**推理**以验证假设 +4. **生成**结构化调查报告，包含可能的根本原因及关联证据 +5. **建议**后续步骤，并可选择执行修复操作 +6. 直接将摘要**发布**到 Slack、PagerDuty 或 Telegram —— 无需切换上下文 -For the current code-level agent architecture after removing the old graph and chain -framework layers, see [AGENTS.md](AGENTS.md). +关于移除旧的 graph 与 chain 框架层之后的当前代码级 agent 架构，请参阅 [AGENTS.md](AGENTS.md)。 --- ## Benchmark -Regenerate numbers with **`make benchmark`**; refresh this table from cached results via **`make benchmark-update-readme`**. See **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#benchmark)** for details. +使用 **`make benchmark`** 重新生成数据；通过 **`make benchmark-update-readme`** 从缓存结果刷新此表。详见 **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#benchmark)**。 -_No benchmark results yet._ +_暂无 benchmark 结果。_ @@ -218,23 +223,23 @@ _No benchmark results yet._ | | | | ---------------------------------------- | -------------------------------------------------------------------------------- | -| 🔍 **Structured incident investigation** | Correlated root-cause analysis across logs, metrics, traces, deploys, and config | -| 📋 **Runbook-aware reasoning** | OpenSRE reads your runbooks and applies them automatically | -| 🔗 **Evidence-backed root cause** | Every conclusion is linked to the data behind it | -| 🛡️ **Reversible identifier masking** | Redact pods, clusters, and account IDs before external LLM calls; restore in output | -| 📊 **Session cost & history** | Per-session token tracking (`/cost`) and resumable REPL sessions (`/sessions`) | -| 👥 **Local agent fleet** | Monitor Claude Code, Cursor, Codex, and other coding agents on your machine | -| 🌐 **Remote runtime RCA** | Investigate deployed services by name with live health probes and recent logs | -| 📡 **Hermes log watch** | Tail Hermes error logs, classify incidents, and deliver Telegram alerts | -| 🤖 **Full LLM flexibility** | Bring your own model — Anthropic, OpenAI, Codex, Ollama, Gemini, OpenRouter, NVIDIA NIM, Bedrock | +| 🔍 **Structured incident investigation** | 跨日志、指标、追踪、部署与配置进行关联的根因分析 | +| 📋 **Runbook-aware reasoning** | OpenSRE 读取你的 runbook 并自动应用 | +| 🔗 **Evidence-backed root cause** | 每项结论均链接至支撑数据 | +| 🛡️ **Reversible identifier masking** | 在外部 LLM 调用前脱敏 pod、集群与账户 ID；输出时可还原 | +| 📊 **Session cost & history** | 按会话追踪 token（`/cost`）及可恢复的 REPL 会话（`/sessions`） | +| 👥 **Local agent fleet** | 监控本机上的 Claude Code、Cursor、Codex 及其他编码 agent | +| 🌐 **Remote runtime RCA** | 按名称调查已部署服务，含实时健康探测与近期日志 | +| 📡 **Hermes log watch** | 跟踪 Hermes 错误日志、分类事件并发送 Telegram 告警 | +| 🤖 **Full LLM flexibility** | 自带模型 — Anthropic、OpenAI、Codex、Ollama、Gemini、OpenRouter、NVIDIA NIM、Bedrock | -OpenSRE connects to **60+** tools across LLMs, observability, cloud infrastructure, data platforms, incident management, and MCP. The full matrix (with roadmap links) lives in the **[product docs](https://www.opensre.com/docs)**; a detailed catalog is also maintained in-repo as the project grows. +OpenSRE 可连接 **60+** 种工具，涵盖 LLM、可观测性、云基础设施、数据平台、事件管理与 MCP。完整矩阵（含路线图链接）见 **[产品文档](https://www.opensre.com/docs)**;**，随着项目发展，仓库内也维护有一份详细目录。 --- ## Integrations -OpenSRE connects to 60+ tools and services across the modern cloud stack, from LLM providers and observability platforms to infrastructure, databases, and incident management. +OpenSRE 可连接现代云技术栈中的 60+ 种工具与服务，从 LLM 提供商与可观测性平台，到基础设施、数据库与事件管理。 | Category | Integrations | Roadmap | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -249,15 +254,15 @@ OpenSRE connects to 60+ tools and services across the modern cloud stack, from L | **Agent Deployment** | Vercel · EC2 · ECS · Railway | | | **Protocols** | MCP · ACP · OpenClaw | | -OpenSRE is community-built. Looking for a safe first contribution? Browse [`good first issue`](https://github.com/Tracer-Cloud/opensre/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) tickets or see the [Good First Issues guide](docs/good-first-issues/README.md). See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full workflow. +OpenSRE 由社区共建。想找安全的首次贡献？浏览 [`good first issue`](https://github.com/Tracer-Cloud/opensre/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 工单，或参阅 [Good First Issues 指南](docs/good-first-issues/README.md)。完整流程见 **[CONTRIBUTING.md](CONTRIBUTING.md)**。 -**Local environment:** **[SETUP.md](SETUP.md)** (all platforms, Windows, MCP/OpenClaw). +**本地环境：** **[SETUP.md](SETUP.md)**（全平台、Windows、MCP/OpenClaw）。 -**Developing in this repo:** **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** (install from source, CI parity checks, dev container, benchmark, deployment detail, telemetry reference). +**在本仓库中开发：** **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**（从源码安装、CI 一致性检查、开发容器、基准测试、部署详情、遥测参考）。

- Join our Discord + 加入我们的 Discord

@@ -271,7 +276,7 @@ OpenSRE is community-built. Looking for a safe first contribution? Browse [`good

-Thanks goes to these amazing people: +感谢以下优秀贡献者： @@ -281,28 +286,28 @@ Thanks goes to these amazing people: --- -## Security +## 安全 -OpenSRE is designed with production environments in mind: structured and auditable LLM prompts, local transcript handling by default, and no silent bulk export of raw logs. See **[SECURITY.md](SECURITY.md)** for responsible disclosure. +OpenSRE 面向生产环境设计：结构化且可审计的 LLM 提示词、默认在本地处理会话记录，且不会静默批量导出原始日志。负责任披露详见 **[SECURITY.md](SECURITY.md)**。 --- -## Telemetry +## 遥测 -PostHog (product analytics) and Sentry (errors) are **opt-out**. Quick disable: +PostHog（产品分析）和 Sentry（错误监控）为 **默认开启、可主动关闭（opt-out）**。快速禁用： ```bash export OPENSRE_NO_TELEMETRY=1 ``` -**[Full matrix, DSN override, and local event logging → docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#telemetry-and-privacy)** +**[完整矩阵、DSN 覆盖与本地事件日志 → docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#telemetry-and-privacy)** --- -## License +## 许可证 -Apache 2.0 — see [LICENSE](LICENSE). +Apache 2.0 — 详见 [LICENSE](LICENSE)。 -## Citations +## 引用 1 https://arxiv.org/abs/2310.06770