wye-ts/opspilot

# OpsPilot [](https://github.com/wye-ts/opspilot/actions/workflows/ci.yml) [](https://opspilot-bkdf.onrender.com) OpsPilot 是一个 AI 辅助的支持和事件调查系统。它将问题摘要转化为 持久化的调查记录，使用经过验证的诊断工具运行有边界的 agent，生成 结构化且有证据支持的报告，并可以记录对提议 操作的人工批准或拒绝。 **实时演示：** [https://opspilot-bkdf.onrender.com](https://opspilot-bkdf.onrender.com) 公开演示是一个 React/Vite 前端和 NestJS API，由同一个 Render Docker 服务提供服务，并由 Neon PostgreSQL 提供支持。 它有意默认使用确定性的 `FAKE` provider： `AGENT_RUN_PROVIDER_MODE=FAKE`、`LIVE_AGENT_RUNS_ENABLED=false`，且没有公开的付费模型执行。 Render 的免费服务在闲置后可能需要时间来唤醒。 ## 为什么它不仅仅是一个聊天机器人 应用程序掌控着整个调查生命周期，而不是将不受限制的对话 直接交给模型： ``` Issue summary → persisted investigation job → bounded two-turn agent orchestration → validated diagnostic tool call → normalized evidence → structured report → persisted trace and result → optional human approval/rejection ``` 模型/provider 的边界是类型化的，工具输入和模型输出经过了运行时验证，证据 必须追溯到已完成的工具调用，并且运行过程最终会在 PostgreSQL 中持久化。批准决策 也会被持久化，但**被批准的操作不会被执行、模拟或调度**。 ## 架构 ``` flowchart LR Browser["React + Vite UI"] -->|"relative /v1 requests"| API["NestJS API"] API --> Runtime["Provider-neutral agent runtime"] Runtime --> Tools["Validated diagnostic tools"] Runtime --> Fake["Deterministic FAKE provider"] Runtime -. "configured LIVE runs only" .-> Claude["Claude provider"] API --> DB[("PostgreSQL")] Runtime --> DB ``` 生产环境使用单一来源：NestJS 在 `/` 提供构建好的前端服务，并在 `/v1/**` 提供 JSON endpoint。API 在请求处理程序中同步执行调查；在浏览器请求路径中 没有作业队列或后台 worker。完成后显示的时间线是一个有序的、 持久化的审计追踪，**而不是实时流式传输的进度显示**。这里没有 SSE、WebSocket、 后台轮询或异步作业执行。 关键的工程边界包括： - 具有确定性和 Claude 适配器的 provider 中立编排； - 由 Zod 支持的模型、工具、trace、报告和 HTTP 契约； - 严格的两次 provider 交互限制，且每次运行最多一次诊断工具调用； - 对作业、运行、有序的 trace 事件、报告和批准决策进行 PostgreSQL 持久化； - fail-closed 的 live-provider 配置，且没有隐式的 provider 回退； - 在执行任何提议操作之前的人工决策边界； - 确定性的单元、集成、评估和 Docker 冒烟测试覆盖； - GitHub Actions、多阶段 Docker 构建、启动迁移和健康检查； - 针对开发来源、后端标识符、provider SDK 引用和凭证模式的前端 bundle 防护。 有关更深入的设计记录，请参阅[技术设计](docs/03-technical-design.md)、[Agent 设计](docs/04-agent-design.md)和 [工程挑战](docs/10-engineering-challenges.md)。 ## 仓库能力与公开演示对比 该仓库包含确定性和真实 provider 两种路径。公开部署仅 公开安全的确定性配置。 | 能力 | 代码仓库 | 公开演示 | | --- | --- | --- | | 确定性调查 | 使用 `FakeLlmProvider` 实现 | 可用；默认且预期的模式 | | 诊断工具执行 | 通过经过验证的输入和标准化的证据实现 | 在确定性场景下可用 | | 持久化的 trace 和报告 | 在 PostgreSQL 中实现 | 通过 Neon PostgreSQL 可用 | | 批准记录 | 已实现；批准/拒绝决策会被持久化 | 在批准演示场景中可用 | | 真实 Claude provider | 已实现，可用于 worker 脚本和按运行的 API 选择 | 禁用；无公开的付费模型执行 | | 浏览器/API RAG | 未连接；RAG 存在于 worker/离线评估路径中 | 不可用 | | 操作执行 | 未实现 | 不可用 | | 身份验证/RBAC | 未实现 | 不可用 | | 实时进度流式传输 | 未实现 | 不可用；时间线在同步完成后返回 | ### Provider 选择与安全 该仓库支持： - 没有模型网络调用的确定性 `FAKE` 执行； - 通过 `@opspilot/provider-claude` 进行的真实 Claude 执行； - 可选的按运行选择，在 Agent Run API 上指定 `{"providerMode":"FAKE"}` 或 `{"providerMode":"LIVE"}`。 省略 API 选择时将使用 `AGENT_RUN_PROVIDER_MODE`，其默认值为 `FAKE`。请求的 `LIVE` 运行需要有效的 Anthropic 配置且 `LIVE_AGENT_RUNS_ENABLED=true`。 **请求的 `LIVE` 运行永远不会被隐式降级为 `FAKE`**：在创建运行记录或进行 provider 调用之前， 不可用或被禁用的实时执行将被拒绝。 当前的浏览器并未公开 `FAKE`/`LIVE` 选择器。公开的 Render 服务设置了 `AGENT_RUN_PROVIDER_MODE=FAKE` 和 `LIVE_AGENT_RUNS_ENABLED=false`，并且不提供公开的付费 Claude 执行。共享的 demo token 保护、速率限制、并发限制以及持久化的 PostgreSQL 每日成本预算尚未实现。 有关请求和错误契约，请参阅 [Agent Run API](docs/12-agent-run-api.md)。 ### RAG 边界 Runbook 检索、检索验证、证据落地、确定性 RAG 演示和离线 评估存在于 `apps/worker` 和 `packages/agent-runtime` 中；请参阅 [RAG 设计](docs/05-rag-design.md)。公开的浏览器/API 执行路径目前 不检索 runbook。`apps/api` 没有连接 runbook 检索器，并且 `runbooks/` 被排除在 生产镜像之外。 ## 本地开发 要求：Node.js `22.21.0`、pnpm `11.13.1`，以及用于基于 PostgreSQL 工作流的 Docker。 ### 安装与单元检查 这些检查不需要数据库或 provider 凭证： ``` pnpm install pnpm db:generate pnpm typecheck pnpm test pnpm build pnpm --filter @opspilot/web run check:bundle ``` ### 本地 PostgreSQL ``` cp .env.example .env pnpm infra:up pnpm db:test:ensure pnpm db:migrate:deploy pnpm db:migrate:test pnpm db:generate ``` 然后运行 PostgreSQL 测试套件或持久化演示： ``` pnpm --filter @opspilot/database run test:integration pnpm --filter @opspilot/api run test:integration pnpm --filter @opspilot/worker run demo:persisted ``` 这两个集成测试套件共享同一个测试数据库，且不能并行运行。该仓库 提供了序列化的等效命令： ``` pnpm test:integration:sequential ``` 有关 schema、迁移和重置的详细信息，请参阅 [Agent Run 持久化](docs/11-agent-run-persistence.md)。 ### API 和 Web 启动 在启动并迁移本地 PostgreSQL 之后： ``` pnpm --filter @opspilot/api run build pnpm --filter @opspilot/api run start ``` 在另一个终端中： ``` pnpm --filter @opspilot/web run dev ``` Vite UI 运行在 `http://127.0.0.1:5173`，并将相对的 `/v1/**` 请求代理到 `http://127.0.0.1:3000` 的 API。要测试 API 持久化的确定性和批准工作流： ``` pnpm api:demo ``` 在 UI 中，**批准工作流演示**使用确定性的 `TICKET-APPROVAL-DEMO` 场景，该场景会生成一个提议的客户回复，并启用 持久化的批准/拒绝流程。普通调查不会生成建议的操作。请参阅 [批准工作流](docs/13-approval-workflow.md)和[Web UI](docs/14-web-ui.md)。 ### 确定性演示与评估 ``` pnpm --filter @opspilot/worker run demo pnpm --filter @opspilot/worker run demo:rag pnpm --filter @opspilot/worker run eval ``` 这些命令使用确定性 provider。RAG 演示和 15 个案例的评估使用的是 代码仓库/离线检索路径，而不是公开的浏览器路径。 ### 可选的付费实时冒烟测试 在 worker 环境中提供 `ANTHROPIC_API_KEY` 的情况下： ``` OPSPILOT_LIVE_SMOKE=1 \ AGENT_RUN_PROVIDER_MODE=LIVE \ ANTHROPIC_MODEL=claude-sonnet-5 \ pnpm --filter @opspilot/worker run test:claude:live ``` ## CI 与部署 GitHub Actions 运行类型检查、单元测试、生产构建、前端 bundle 防护、 PostgreSQL 集成测试、迁移漂移检查以及 Docker 冒烟工作流。生产 镜像同时提供 React bundle 和 NestJS API 服务，在启动前运行提交的迁移， 使用非 root 运行时用户，并排除 worker 源码、Voyage AI 和 runbook。 部署的拓扑结构是： - 一个 Render Docker Web 服务； - 一个 Neon PostgreSQL 数据库； - 一个用于前端和 API 的公开来源； - 默认进行确定性的 `FAKE` 执行，禁用公开的 `LIVE` 执行。 请参阅 [CI/CD 与部署](docs/08-cicd-deployment.md)。 ## 路线图 下一步： - 使用共享的 demo 访问 token 保护公开的 `LIVE` 执行； - 添加速率和并发控制，以及持久化的 PostgreSQL 每日预算； - 在浏览器中添加 `FAKE`/`LIVE` 选择器，并显示模型、延迟和预估成本。 后期： - 将长时间运行的调查转移到异步执行； - 在建立持久化执行模型后，公开实时调查阶段。

标签：AI智能体, NestJS, RAG, React, Syscalls, 事件调查, 测试用例, 自动化攻击, 自动化运维, 请求拦截, 运维