bhartiyaanshul/quell

网站 · 入门指南 · 命令 · 架构 · 扩展 · 社区

## 为什么选择 Quell？

### 在使用 Quell 之前 - 凌晨 3 点的告警，睡眼惺忪的工程师。 - 花费 10 分钟寻找正确的日志文件。 - 再花 15 分钟 grep 堆栈跟踪。 - 又花 20 分钟追踪五个服务。 - 等到根本原因查明时，事故已经发生了一个小时。 - 修复的草稿 PR 要等到明天再写（如果还会写的话）。

### 使用 Quell 之后 - 告警触发，自主调查立即开始。 - `IncidentCommander` 读取日志，grep 代码，追踪 git 历史。 - 专家子代理通过 `asyncio.Queue` 并行工作。 - 大约 30 秒内生成根本原因报告。 - 当您上线时，草稿 PR 提案已等待人工审查。 - 您批准，合并，继续睡觉。

## 查看实际演示 M[Monitor] HP --> M VC --> M SN --> M M -->|RawEvent| D[Detector
signature + 24h baseline] D -->|Incident| IC{IncidentCommander} IC -->|spawns| SA1[log-analyst] IC -->|spawns| SA2[code-detective] IC -->|spawns| SA3[git-historian] SA1 & SA2 & SA3 -->|tool calls| SB[Docker sandbox
FastAPI tool server] SB -->|ToolResult| IC IC -->|finish_incident| R[Structured report
Draft PR] style IC fill:#fb923c20,stroke:#fb923c style R fill:#a78bfa20,stroke:#a78bfa style SB fill:#12121a,stroke:#27272a ``` | 阶段 | 作用 | 代码 | |-------|--------------|------| | 1. Monitor | 为每行日志 / HTTP 探测 / Vercel 或 Sentry 负载生成一个 `RawEvent` | [`quell/monitors/`](quell/monitors/) | | 2. Detector | 对事件进行指纹识别（标准化的 16 位十六进制）；在新事件 / 激增 / 高严重级别时触发 | [`quell/detector/`](quell/detector/) | | 3. Commander | 顶层 `IncidentCommander` 读取日志，grep 代码，进行推理，并可选地派生专家子代理 | [`quell/agents/`](quell/agents/) | | 4. Sandbox | 每个涉及代码操作的工具都在 Docker 容器内运行，并将您的工作区以**只读**方式挂载 | [`quell/runtime/`](quell/runtime/) · [`quell/tool_server/`](quell/tool_server/) | | 5. Report | 生成结构化的 `{root_cause, evidence, proposed_fix, status}`，并封装为草稿 PR 等待人工审查 | [`quell/tools/reporting/`](quell/tools/reporting/) | | 6. Persist | 每次调查生成一个 `AgentRun` 行，加上每次迭代的 `Event` 和结构化的 `Finding` 行，供仪表板和回放使用 | [`quell/memory/`](quell/memory/) | | 7. Notify | 将结果并行分发到 Slack / Discord / Telegram | [`quell/notifiers/`](quell/notifiers/) | ## 功能特性

### 默认沙箱化 每个涉及代码操作的工具都在 Docker 内部运行，您的工作区 以**只读**方式挂载。FastAPI 工具服务器上使用按沙箱划分的 Bearer token 认证。 [docs/architecture.md](docs/architecture.md#runtime--quellruntime)	### 多代理协调 `IncidentCommander` 通过 `AgentGraph` 派生专家子代理；它们通过 `asyncio.Queue` 代理交换消息。 实现并行调查和串行推理。 [docs/architecture.md](docs/architecture.md#agents--quellagents)	### 自带模型 基于 **LiteLLM** 构建 —— 支持 OpenAI、Anthropic、Google Gemini、Ollama 或 任何自定义 endpoint。只需一行 TOML 即可切换。无锁定。 [docs/configuration.md](docs/configuration.md#llm--llm-provider)
### 技能手册 Markdown + YAML frontmatter 手册会在触发条件匹配到事件时，自动注入到代理的 系统提示词中。内置 **十九种** 手册 —— Stripe、OpenAI、空指针引用、DNS、SSL、内存、磁盘、死锁、 Django/Flask/Rails/Spring/Express、Postgres、Redis、Docker、Kubernetes。 [docs/extending.md](docs/extending.md#writing-a-skill)	### 草稿 PR，绝不自动合并 每一个建议的修复方案都是草稿 PR。由人类审查，由人类合并。没有 静默更改，没有凌晨 3 点的意外，没有“相信我”式的提交。 [SECURITY.md](SECURITY.md)	### 默认无遥测 您的代码、您的日志、您的基础设施。除非您明确配置远程 监控或 LLM endpoint，否则不会有任何数据离开您的 机器。遥测功能仅为可选项。 [docs/configuration.md](docs/configuration.md)
### 通知您的团队 一旦调查完成，Slack、Discord 和 Telegram 频道会并行发送通知。在 TOML 中一次性配置好，使用 `quell test-notifier ` 进行验证，从此不同频道间不再混淆瞬时错误。 [docs/configuration.md](docs/configuration.md#notifiers)	### Web 仪表板 + 回放 `quell dashboard` 启动一个本地的 Next.js + FastAPI UI，用于查看事件、 运行、发现结果和汇总统计。`quell replay ` 将相同的事件流 作为终端时间线打印。只读模式，无需连接云服务。 [docs/commands.md](docs/commands.md#dashboard)	### 成本追踪与预算 支持 Anthropic / OpenAI / Google / Ollama 的按模型费率表。每次 运行都会记录输入 + 输出的 token 数量以及 USD 预估成本；`.quell/config.toml` 中的 `max_cost_usd` 会在失控的调查烧光您的预算前将其 及时中止。 [docs/configuration.md](docs/configuration.md#agent)

## 开箱即用的内容 ### 11 个内置工具 | 类别 | 工具 | 作用 | |----------|------|--------------| | 代码 | `code_read` | 读取文件（可选带有行范围） | | 代码 | `code_grep` | 由 ripgrep 驱动的内容搜索，带有路径遍历防护 | | Git | `git_log` | 最近的提交记录，包含作者和时间戳 | | Git | `git_blame` | 行级别的代码作者追踪 | | Git | `git_diff` | refs 之间或工作树的 Diff | | 监控 | `http_probe` | 请求一个 HTTP endpoint，返回状态 + 头信息 + 主体 | | 监控 | `logs_query` | 使用子字符串过滤器追踪本地日志 | | 报告 | `create_incident_report` | 结构化的事件摘要 | | 报告 | `create_postmortem` | Markdown 格式的无责复盘 | | 协调 | `agent_finish` | 子代理发出完成信号 | | 协调 | `finish_incident` | 根代理关闭调查 | 此外还有在阶段 13 中添加的四个代理间工具（`create_agent`、`send_message`、 `wait_for_message`、`view_graph`）。 ### 19 个捆绑的技能手册 | 标识 | 类别 | 严重级别 | 触发条件 | |------|----------|----------|---------------| | `stripe-webhook-timeout` | incidents | high | 错误提及 `stripe-signature` 或 `webhook timeout` | | `unhandled-null` | incidents | medium | 错误提及 `NoneType`、`null is not an object`、`Cannot read propert` | | `openai-rate-limit` | incidents | high | 错误提及 `rate_limit_exceeded`、`429`、`tokens per minute` | | `dns-resolution-failure` | incidents | high | 错误提及 `EAI_AGAIN`、`getaddrinfo`、`unknown host` | | `ssl-certificate-expired` | incidents | high | 错误提及 `certificate expired`、`CERT_HAS_EXPIRED` | | `memory-leak` | incidents | high | RSS 持续增长而 GC 未释放，OOMKilled，堆快照出现偏差| `disk-full` | incidents | critical | 错误提及 `ENOSPC`、`no space left on device`，写入失败 | | `database-deadlock` | incidents | high | 错误提及 `deadlock detected`、`lock wait timeout` | | `fastapi` / `nextjs-app-router` | frameworks | medium | 框架匹配或堆栈跟踪指纹匹配 | | `django` / `flask` / `rails` / `spring-boot` / `express` | frameworks | medium | 框架匹配或堆栈跟踪指纹匹配 | | `postgres` / `redis` | technologies | high | 技术栈匹配，错误提及已知信号 | | `docker` / `kubernetes` | technologies | high | 容器/Pod 级别的故障，OOM，CrashLoopBackOff | 只需将 `.md` 文件放入 [`quell/skills//`](quell/skills/) 即可添加您自己的手册。 请参阅 [**docs/extending.md**](docs/extending.md#writing-a-skill)。 ## 架构 ``` graph TB subgraph host["Host (your dev machine or on-call server)"] CFG[("Config
TOML + Pydantic")] MEM[("Memory
AgentRun · Event · Finding")] MON[Monitors] --> DET[Detector] DET --> CMD[IncidentCommander] CMD <--> LLM[LiteLLM
cost + budgets] CMD <--> SKL[(19 Skills)] CMD -->|spawn| SUB[Subagents] SUB --> CMD CMD -->|fan-out| NOT[Slack · Discord · Telegram] CFG -.-> CMD CMD -.-> MEM MEM -.-> DASH[Dashboard + replay] end subgraph sandbox["Docker sandbox (per-agent)"] TS[FastAPI tool server] TOOLS[11 built-in tools] WS[/workspace/
mounted read-only/] TS --> TOOLS TOOLS --> WS end CMD <-->|bearer-token HTTP| TS style CMD fill:#fb923c20,stroke:#fb923c,color:#fafafa style SUB fill:#fb923c15,stroke:#fb923c80,color:#fafafa style NOT fill:#a78bfa15,stroke:#a78bfa80,color:#fafafa style DASH fill:#a78bfa15,stroke:#a78bfa80,color:#fafafa style sandbox fill:#12121a,stroke:#a78bfa,color:#fafafa style host fill:#0a0a0f,stroke:#27272a,color:#fafafa ``` 十一个子系统，每个边界都有类型化。 | 子系统 | Python 代码行数 | 测试覆盖率 | |-----------|-----------------|---------------| | `quell/config/` | ~400 | 24 个测试 | | `quell/memory/` | ~770 | 40 个测试 | | `quell/monitors/` | ~600 | 24 个测试 | | `quell/llm/` | ~530 | 41 个测试 | | `quell/tools/` | ~700 | 42 个测试 | | `quell/agents/` | ~1 100 | 33 个测试 | | `quell/skills/` | ~360 | 30 个测试 | | `quell/runtime/` + `quell/tool_server/` | ~400 | 16 个测试 | | `quell/notifiers/` | ~410 | 20 个测试 | | `quell/dashboard/` + `quell/replay/` | ~570 | 16 个测试 | | **合计** | **~5 800 LoC** | **302 个测试** | 深入了解请参阅 [**docs/architecture.md**](docs/architecture.md)。 ## 文档

### 从这里开始 - [**入门指南**](docs/getting-started.md) — 10 分钟内从零开始运行调查 - [安装说明](docs/installation.md) — 全部五种安装途径 - [故障排除](docs/troubleshooting.md) — 常见错误及单行修复命令

### 参考 - [命令](docs/commands.md) — 每一个 `quell` 子命令 - [配置说明](docs/configuration.md) — `.quell/config.toml` 结构 - [架构设计](docs/architecture.md) — 子系统深入解析

### 在此基础上构建 - [扩展 Quell](docs/extending.md) — 添加技能或工具 - [打包](packaging/README.md) — 单个标签如何发布到所有平台 - [阶段 16 发布](docs/LAUNCH.md) — 手动发布手册

## 常见问题

Quell 会将我的代码发送给 LLM 提供商吗？

仅包含代理通过其工具显式读取的片段，并且这些片段受沙箱控制，沙箱只能看到您所挂载的工作区中的内容。如果您根本不想让任何代码离开您的机器，可以切换 LiteLLM 到本地模型，例如 Ollama。

Quell 会修改我的代码吗？

不会。每一个接触文件系统的工具都在 Docker 沙箱内运行，且工作区以**只读**方式挂载。修复方案仅以**草稿 PR** 的形式提出，从不推送，从不合并，并且必须由人工批准。

支持哪些 LLM？

支持 LiteLLM 支持的任何模型。OpenAI (GPT-4o, GPT-5)、Anthropic (Claude Haiku / Sonnet / Opus)、Google Gemini、Ollama 本地模型以及任何 兼容 OpenAI 的 endpoint。只需修改一行 TOML 即可切换。

一次典型的调查费用是多少？

一次典型的事件调查会运行 3-7 个代理迭代，消耗 15-40k 的输入 token 和 1-3k 的输出 token。在 `claude-haiku-4-5` 上，大约为 每次事件 $0.01–0.03。从 v0.2 开始，每次运行都会记录自身的 token + USD 成本，并且 `.quell/config.toml` 中的硬性 `max_cost_usd` 上限会在失控的调查烧光预算前将其及时中止。`quell stats` 会显示滚动的单次事件总计。

没有 Docker 可以运行吗？

单元测试和“试运行”演练无需 Docker 即可工作。 对于真实环境中不受信任代码的生产调查，应运行在 Docker 之下，以保证只读工作区和网络隔离。

它可以用于生产环境吗？

Quell 目前为 **v0.2.0 alpha** 版本。核心流程已实现端到端可用（302 个测试）， v0.1.x 的配置向前兼容，并且新的持久化、 通知器和仪表板层已在日常活跃使用中。但在处理非英文日志、 长堆栈跟踪以及罕见的 LLM 故障模式时，预计仍会存在一些瑕疵。 建议先在预发布环境中运行 Quell。如果提交 Issue，我们会快速响应。

我可以自托管仪表板吗？

可以 —— `quell dashboard` 会在 `http://127.0.0.1:7777` 启动一个只读的 Next.js + FastAPI UI，包含事件列表、运行时间线、发现结果以及汇总统计。编译后的 SPA 内置于 Python wheel 中，因此在安装时不需要单独的 Node 运行时。如果您希望将其部署到共享的待命服务器上，可以使用 `--host 0.0.0.0` 将其绑定到其他主机。

告警发送到哪里？

`quell.notifiers` 支持 Slack、Discord 和 Telegram 频道。在 `.quell/config.toml` 的 `[[notifiers]]` 下添加一个（或多个）频道，运行 `quell test-notifier slack`（或 `discord`、`telegram`）验证配置是否正确，然后 `quell watch` 会在代理完成后立即将结构化的事件摘要并行发送到每个配置的频道。

Quell 与现有工具有何不同？

Quell 不是监控工具（Sentry / Datadog 已经在做这件事）。 也不是聊天机器人（Quell 是自主的，而非交互式的）。也不是自动合并工具（始终由人工审查）。它构建在您现有的监控之上：Quell 消费 Sentry / Vercel / 日志事件，调查其潜在的根本原因，并生成报告。

## 社区

### 贡献 请阅读 [**CONTRIBUTING.md**](CONTRIBUTING.md) 以了解开发循环和 门禁要求（ruff format、ruff check、mypy strict、pytest —— 这四项必须全部通过才能合并）。 适合新手的 Issue 已在 GitHub 上标记。如果您不知道从何入手，欢迎加入 [讨论区](https://github.com/bhartiyaanshul/quell/discussions)。

### 报告 Bug 或漏洞 - 普通 Bug → [GitHub Issues](https://github.com/bhartiyaanshul/quell/issues) - 安全问题 → [私密安全公告](https://github.com/bhartiyaanshul/quell/security/advisories/new)（该公告流程也用于行为准则报告 —— 参见 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)）

## 路线图 Quell 跨越 22 个阶段进行构建，记录在 [`BUILD_PLAN.md`](BUILD_PLAN.md) 中。 - **v0.1 — 阶段 1–16（已发布）。** 配置、内存、监控器、LLM、工具、代理、技能、检测器、Docker 运行时、工具服务器、内置工具、代理图谱、端到端集成、完善优化、公开发布。 - **v0.2 — 阶段 17–22（已发布）。** Slack / Discord / Telegram 通知器、扩展的 19 个技能库、AgentRun + Event + Finding 持久化、带有 `max_cost_usd` 预算的按模型成本追踪、本地 Web 仪表板、终端 `quell replay`。 - **v0.3（下一版本）。** 多仓库协调、跨事件学习、更丰富的仪表板过滤器。 - **v1.0（远期愿景）。** 生产就绪、按事件类型设定的成本预算、托管云选项（仅为可选项 —— CLI 将永远保持可自托管）。 ## 开发 ``` # 包含 dev deps 的一次性可编辑安装 curl -fsSL https://raw.githubusercontent.com/bhartiyaanshul/quell/main/install.sh | bash -s -- --dev # Stop-gate — 合并前必须通过所有四项 poetry run ruff format quell/ tests/ --check poetry run ruff check quell/ tests/ poetry run mypy quell/ poetry run pytest tests/ -q ``` 完整的开发循环详见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ### 落地页 位于 [**quell.anshulbuilds.xyz**](https://quell.anshulbuilds.xyz) 的营销网站源码存放在 [`landing/`](landing/) 中。 ``` cd landing npm install npm run dev # http://localhost:3000 with hot reload npm run build # produces ./out/ — deploy anywhere static ``` Next.js 14 + TailwindCSS + Framer Motion。组件图请参阅 [`landing/README.md`](landing/README.md)。 ## 致谢

由 Anshul Bhartiya 构建 — @bhartiyaanshul

_{Apache 2.0 · 开源 · 无遥测 · 您的代码保留在您的机器上。}

标签：AI安全, Chat Copilot, DevOps工具, DevSecOps, Docker沙箱, LLM驱动, PyRIT, Python安全, Python开发, SOAR, 上游代理, 代码审查, 多智能体系统, 子域名变形, 安全事件响应, 安全调查, 安全运营, 库, 应急响应, 扫描框架, 漏洞修复, 网络安全, 网络安全培训, 自动化事件响应, 自动化运维, 自动提交PR, 计算机取证, 请求拦截, 隐私保护