nimbus-agent/Nimbus

Nimbus 是一个开源的、本地优先的 AI Agent，专为在生产环境中运维系统的工程师而构建。无头 **Nimbus Gateway** 运行在您的机器上，跨您的整个开发者工具链——源代码控制、CI/CD、云基础设施、监控和事件管理——维护一个私有的 SQLite 索引，并代表您执行多步骤任务。每一次写入、发送或删除操作在执行前都需要您的明确批准。 **您的凭据永远不会离开您的机器。这里没有 Nimbus 服务器。** Nimbus 中的每一个架构决策都基于一个问题进行评估： [贡献](#contributing) 中的不可协商原则正是源于这个问题——它们是承载核心重量的约束，而非仅仅是愿景性的价值观。 ## 它能做什么 ``` # 事件响应 — 从本地索引应答，无 API 调用，100ms 以下 nimbus ask "The payment-service alert just fired — what changed in the last 2 hours?" # 发布准备 — 跨服务且无需切换标签页 nimbus ask "Which of my open PRs have failing CI and are blocking the release branch?" # SecDevOps — 将安全信号与您的代码库关联 nimbus ask "Which repos have critical Dependabot alerts with open PRs touching the affected packages?" # 基础设施 — 跨提供商查询状态 nimbus ask "What Terraform drift has been detected since last week's deployment?" # 数据血缘 — 从本地索引应答，无数据仓库查询 nimbus ask "The Q1 revenue dashboard shows zeroes — which upstream model broke?" # 专家路由 — 寻找对某个主题掌握最多上下文信息的人 nimbus ask "who has the most context on the payment retry logic?" # 爆炸半径 — 在您推送前从关系图中获取答案 nimbus ask "what services depend on src/billing/retry.ts, and which dashboards or pipelines would feel a change to it?" # 需授权的自动化 — 在执行任何操作前提供完整的计划预览 nimbus run ./incident-response.yml ``` **示例会话：** ``` $ nimbus ask "The payment-service alert just fired — what changed?" 🔍 PagerDuty: P1 — Error rate 4.2% — fired 8 minutes ago 🔍 Last deploy: payment-service v2.14.1 — 23 minutes ago 🔍 GitHub diff v2.14.0 → v2.14.1: 3 files — src/billing/retry.ts most significant PR #312 "Increase retry backoff" — merged by @elena 41 minutes ago ⚠ CONSENT REQUIRED — Post incident summary to #incidents? Post? [y/n]: y ✅ Posted. Suggested next step: rollback to v2.14.0? ⚠ CONSENT REQUIRED — Trigger Jenkins rollback job. Rollback? [y/n]: n Aborted. No changes made. ``` **SecDevOps 示例：** ``` $ nimbus ask "Critical CVE dropped for lodash — what's our exposure?" 🔍 Scanning local index: 47 repos indexed, 12 have lodash as a direct dependency 🔍 Active PRs touching lodash: 3 open PRs across payment-service, auth-gateway, api-proxy 🔍 Sentry: 2 production errors last 24h in lodash code paths (payment-service) 🔍 Jira: No active tickets for this CVE yet Suggested next step: Create Jira tickets for affected repos? ⚠ CONSENT REQUIRED — Create 3 Jira tickets and assign to component owners. Proceed? [y/n]: y ✅ Created PLAT-1847, PLAT-1848, PLAT-1849. ``` **数据血缘示例：** ``` $ nimbus ask "The Q1 revenue dashboard shows zeroes — which upstream model broke?" 🔍 Tableau: dashboard "Q1 Revenue" — last refresh failed 12 minutes ago 🔍 Upstream Looker view: revenue_daily → dbt model revenue_daily_agg 🔍 dbt Cloud: revenue_daily_agg — last run failed 14 minutes ago 🔍 Airflow: DAG daily_revenue_etl — task load_fact_orders failed with SQL error 🔍 GitHub PR #842 "Rename order_amount → gross_amount" — merged by @priya 28 minutes ago No downstream dbt model updated to match the rename. Suggested next step: Revert PR #842 and rerun the DAG? ⚠ CONSENT REQUIRED — Revert PR #842 and trigger Airflow DAG rerun. Proceed? [y/n]: n Aborted. No changes made. ``` ## 适用人群 Nimbus 是为在生产环境中运维系统的工程师和操作人员构建的。如果您的 on-call 轮值涉及五个监控工具和三个云控制台，Nimbus 就是将所有上下文折叠为单次查询的智能层。 | 角色 | Nimbus 为您提供什么 | |---|---| | **On-call / SRE** | 即时的事件上下文——上次部署、触发提交、CI 结果、Slack 讨论串——通过一次查询获取，无需打开七个浏览器标签页 | | **平台工程师** | 偏差检测、多云基础设施状态、部署关联、经授权门控的 IaC 应用和回滚 | | **安全工程师** | 告警到提交的追踪、CVE 到 PR 的关联、每个 Agent 操作的完整审计日志、合规状态查询 | | **高级开发人员** | 跨仓库 PR 智能、发布就绪检查、流水线上下文、仅限本地的凭据存储；用于“哪些服务暴露了该 endpoint？”查询的 OpenAPI / AsyncAPI 规范索引 (Phase 5) | | **团队负责人 / 工程经理** | 跨服务活动摘要、变更日志生成、专家路由、爆炸半径分析——无需询问任何人 | | **分析工程师 / 数据科学家** | 从仪表板到 dbt 模型，再到数仓表和编排 DAG 的跨栈血缘——一次本地查询替代五个控制台；仅元数据摄取确保行数据保留在数仓中 | 这并不是一款适合所有人的工具。这里没有托管云服务、没有 Nimbus 账户、也没有中继服务器。如果这是您需要的，请另寻他处。 ## 为什么工程师选择 Nimbus ### 快速——绝大多数查询不经过网络 Nimbus 维护一个本地 SQLite 元数据索引。在五个服务中搜索 50,000 个索引项耗时不到 100 毫秒——比打开一个新的浏览器标签页还要快。 | 操作 | Nimbus (本地索引) | 典型 SaaS | |---|---|---| | 跨所有服务搜索 | ~20–80ms | 1,500–4,000ms | | 列出 3 个服务的最新文件 | ~5ms | 3× API 往返 | | 语义召回 (embeddings) | ~50–200ms | 远程 embed + 搜索 | | Gateway 冷启动 | ~80ms | 常驻云端 | *在中端笔记本上测量；跨 5 个已连接服务的 50k 项索引。* ### 架构层面的安全性 - **凭据**存储在您操作系统原生的密钥库中（Windows DPAPI、macOS Keychain、Linux Secret Service）。没有任何代码路径会将它们写入磁盘、日志或 IPC 响应中。 - **HITL 授权门控**在执行器中实现，而不是在 prompt 中。如果模型生成了一个跳过确认的计划，该计划根本不会被执行。 - **扩展**在沙箱子进程中运行。它们只接收其声明的服务的凭据，无法枚举 Vault 密钥或访问其他连接器。 - **Prompt 注入**通过将文件内容和 API 响应作为类型化的 `` 数据块注入来缓解，绝不会作为指令注入。 ### 真正的跨平台 Windows、macOS 和 Linux 受到同等支持。每个 PR 都会在 Ubuntu 上运行完整的检查门控（类型检查、lint、构建、测试）。向 `main` 分支推送时，会并行运行完整的三个平台矩阵。特定平台的代码（IPC、密钥、自动启动、通知）隐藏在类型化的 `PlatformServices` 抽象之后——业务逻辑永远不会知道自己运行在哪个操作系统上。 ### 可扩展 第三方连接器以 npm 包形式发布。只需一条命令安装；Agent 会立即获得新功能。本地扩展市场位于 Tauri 桌面应用中——代码已在 Phase 4 完成，并将在 Phase 13 作为独立的 `desktop-v0.1.0` 标签发布（无头 `v0.1.0` 仅包含 Gateway + CLI + VS Code 扩展）。 ## 连接器 您的 on-call 轮值所依赖的每一个工具，都统一在一个本地索引中。无需 API 调用即可回答跨服务查询——数据已经就在那里。 **Phase 1–2 (已发布)：** 本地文件系统、Google Drive、Gmail、Google Photos、OneDrive、Outlook、Microsoft Teams、GitHub、GitLab、Bitbucket、Slack、Linear、Jira、Notion、Confluence、Discord (选填) **Phase 3 (已发布)：** Jenkins、GitHub Actions、CircleCI、GitLab CI、AWS、Azure、GCP、Kubernetes、Terraform/Pulumi/CloudFormation、Datadog、Grafana、Sentry、PagerDuty、New Relic **Phase 5 (计划中)：** Databricks、Apache Airflow、Prefect、Dagster、Metabase、Superset、Kibana / Elasticsearch、CloudWatch Logs、GCP Cloud Logging、BigQuery、Athena、dbt Cloud、MLflow、SageMaker、Vertex AI、Great Expectations 以及本地数据文件分析（Parquet / CSV / JSONL schema——仅包含标头/尾部/行数，绝不包含单元格值） **Phase 6 (计划中，团队版)：** Snowflake、Tableau、Looker、PowerBI、Monte Carlo、Bigeye（受 SSO 门控的数仓、BI 和数据质量连接器；依赖于 Team Vault） 有关每个连接器的深度和现有差距，请参阅[路线图](./roadmap.md)。 ### v0.1.0 包含的内容 `v0.1.0` 于 **2026-05-09** 发布，包含无头 Gateway + CLI + VS Code 扩展（`desktop-v0.1.0` Tauri 发布载体推迟到 Phase 13——参见 [路线图中的 § Phase 13 → Desktop 发布载体](./roadmap.md#desktop-release-vehicle))。Phase 3.5 和 4 已 ✅ 完成；Phase 5 现处于活跃开发阶段。`v0.1.0` 中发布的重要特性： **可观测性与开发者体验 (Phase 3.5)：** - **`nimbus doctor`** — 环境健康检查，提供可操作的修复建议 - **`nimbus diag`** — 完整的诊断快照；`slow-queries` 子命令 - **`nimbus query`** — 结构化索引查询，带有 `--sql` 保护措施和 `--json` 输出 - **`nimbus db verify / repair / snapshot / restore / prune`** — 数据完整性与恢复 - **`nimbus config` / `nimbus profile`** — 命名配置文件和环境变量覆盖 - **`nimbus telemetry show / disable`** — 选择加入的仅聚合遥测 - **`nimbus serve`** — `localhost` 上的只读本地 HTTP API - **`nimbus connector history `** — 每个连接器的健康历史记录 - **`@nimbus-dev/client`** — 类型化的 IPC 包装器，为扩展和脚本提供 `MockClient` - **Starlight 文档站点** — `packages/docs/`；`bun run docs:build` **Presence (Phase 4)：** - **本地 LLM** — `nimbus` 通过 Ollama 或 llama.cpp 完全支持离线运行；按任务进行模型路由（分类使用本地模型，规划使用远程或本地模型），并带有单插槽 GPU 仲裁器 - **多 Agent 编排** — 协调器/工作器分解，在每个子 Agent 上强制执行结构化 HITL；在执行器层面强制执行深度和工具调用 gas 限制 - **语音界面** — `voice.transcribe` / `voice.speak` IPC，可选的唤醒词循环；`whisper-cli` 用于 STT，各平台使用原生 TTS；音频永远不会离开本机 - **数据主权** — `nimbus data export / import / delete`，使用 BLAKE3 链式审计日志，支持 `nimbus audit verify / export`，具有深度控制的每个连接器重新索引 - **自动更新** — `nimbus update --check` / `nimbus update`；安装前验证 Ed25519 签名的二进制清单 - **加密局域网远程访问** — `nimbus lan enable / pair / grant-write`；NaCl-box 密封的 RPC，无中继，默认禁用 - **富 TUI** — `nimbus tui`，五窗格 Ink 布局，流式中途 HITL，在不兼容的终端上回退到 `nimbus repl` - **VS Code 扩展** — 基于 `@nimbus-dev/client`；通过 VS Code 通知提供命令、状态栏和 HITL；已发布到 VS Code Marketplace + Open VSX - **按连接器划分的 OAuth Vault 密钥** — Google 和 Microsoft 子服务拥有各自的密钥；消除了连接器之间的范围冲突 - **图谱感知的监视器条件** — `[automation].graph_conditions` 标志；关系图谱上的 `owned_by` / `upstream_of` / `downstream_of` 断言 **`v0.1.0` 之后落地 (Phase 5 进行中)：** - **`nimbus expert `** — 第一个内置 Agent：根据索引的 PR 作者身份、审查历史和事件参与度，对拥有最多关于某个文件或主题上下文的团队成员进行排名。只读，无 HITL。T3 Team Intelligence PR 1 (2026-05-09)。 - **`nimbus impact `** — 第二个内置 Agent：跨越服务、流水线、仪表板和 on-call 轮值的反向依赖爆炸半径分析。在关系图谱上运行五个并行的子 Agent。只读，无 HITL。提供 `--json` 用于 CI 集成。T3 Team Intelligence PR 2 (2026-05-09)。 - **`nimbus catchup --since `** — 第三个内置 Agent：根据用户的历史参与度（拥有的服务、贡献过的仓库、响应过的事件）进行加权的个性化回顾性摘要。在本地索引上运行五个并行的子 Agent；三层自我身份解析器（覆盖 → git 邮箱 → OS 用户名）。只读，无 HITL。提供 `--json` 用于 CI 集成。T3 Team Intelligence PR 3 (2026-05-10)——结束了 T3 史诗。 - **并行子 Agent 调度** — `AgentCoordinator.executeAll` 现在并发运行子任务，而非顺序运行。 有关完整的交付列表，请参阅 [`docs/roadmap.md`](./roadmap.md)；有关完整的 CLI 命令参考，请参阅 [`docs/cli-reference.md`](./cli-reference.md)。 ## 快速入门 ### 前置条件 #### 所有平台必需 (源码构建) - **[Bun v1.2+](https://bun.sh/docs/installation)** — 运行时、包管理器、测试运行器。使用 `bun --version` 验证。 - **Git** — 用于克隆仓库和构建时的 git 信息嵌入。 - **++ 构建工具链** — 适用于没有针对您的平台提供预编译二进制文件的少数原生依赖。 - Windows: [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) 和 Visual Studio Build Tools (Desktop development with C++ workload)。 - macOS: `xcode-select --install`。 - Linux: `build-essential` (Debian/Ubuntu) 或 `Development Tools` (Fedora/Arch)。 #### 仅 Tauri 2.0 桌面 UI 需要 (`packages/ui`) 无头 Gateway 和 CLI 无需这些即可构建。如果您只想在终端中使用 `nimbus`，请跳过此部分。 - **[Rust 工具链](https://www.rust-lang.org/tools/install)** — 通过 `rustup` 安装；Tauri 需要 `cargo` 和稳定的 `rustc` (建议 ≥ 1.78)。 - **平台 WebView 依赖：** - **Windows 10+** — WebView2 Runtime (Windows 11 已预装；在较旧的 Windows 10 版本上安装 [Evergreen Bootstrapper](https://developer.microsoft.com/en-us/microsoft-edge/webview2/))。 - **macOS 13+** — Xcode Command Line Tools (如果您已执行上面的 `xcode-select --install`，则已安装)。 - **Linux (Ubuntu/Debian)** — `sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev`。 - 其他发行版：参见 [Tauri 先决条件指南](https://tauri.app/start/prerequisites/)。 #### 仅在 Linux 上运行时需要 - **`libsecret`** — 为 Linux 上的 Vault 提供支持 (Windows 使用 DPAPI；macOS 使用 Keychain——两者均为内置)。 - Debian/Ubuntu: `sudo apt install libsecret-1-0 libsecret-tools` (`-tools` 包提供 `secret-tool`，`nimbus doctor` 会检查它)。 - Fedora/Arch: `sudo dnf install libsecret` / `sudo pacman -S libsecret`。 - 您还需要一个正在运行的 Secret Service 实现——`gnome-keyring`、KWallet (kwallet5/6) 或启用了 Secret Service 的 `keepassxc`。在无头 Linux 服务器上，请在您的会话脚本中使用 `gnome-keyring-daemon --unlock`。 #### 通过 `bun install` 安装的原生依赖 Gateway 的本地嵌入器使用 **`@xenova/transformers`**，该库依赖于 **`sharp`** 和平台二进制文件（如 **`@img/sharp-win32-x64`**）。这些由 `bun install` 自动拉取——您无需在系统范围内安装它们。如果 Sharp 下载或构建失败，请删除 `node_modules` 并在启用安装脚本的情况下重新运行 `bun install`。 #### 预编译二进制文件 (目标机器上无需 Bun) 使用 `bun build --compile` 构建的 Gateway 二进制文件将 JavaScript 打包成单个文件。在某些平台上，Sharp 的原生 `.node` 文件可能无法在该布局中加载。如果 `nimbus-gateway` 因 Sharp 错误而退出，请在执行 `bun install` 后使用 `bun` **从源码**运行 Gateway（例如 `cd packages/gateway && bun run dev`）。来自 CI 的 Linux `.deb` / tarball 制品是正常的编译二进制文件——终端用户无需运行 `npm install sharp`；如果打包的二进制文件出现同样的故障，修复方案在于构建/打包环节，而不是在用户机器上安装额外的 OS 包。 #### 可选——仅在启用相应功能时需要 | 功能 | 要求 | 安装方法 | |---|---|---| | **本地 LLM (Ollama)** | 在 `localhost:11434` 上运行的 [Ollama](https://ollama.com/download)，外加至少一个拉取的模型 (例如 `ollama pull llama3.1:8b`) | 默认端点：`http://127.0.0.1:11434`。使用 `nimbus config set llm.local_model llama3.1:8b` 设置本地模型。 | | **本地 LLM (llama.cpp)** | Gateway 可访问的 `llama-server` HTTP 端点 | `nimbus config set llm.llamacpp_server_path /usr/local/bin/llama-server`——参见 `docs/architecture.md`。 | | **云端 LLM (Anthropic)** | Anthropic API 密钥 | 在 Gateway 环境中导出 `ANTHROPIC_API_KEY=…`，然后运行 `nimbus config set llm.remote_model claude-sonnet-4-6` (提供商从模型 id 推断；`claude-*` → Anthropic)。 | | **云端 LLM (OpenAI)** | OpenAI API 密钥 | 导出 `OPENAI_API_KEY=…`，然后运行 `nimbus config set llm.remote_model gpt-4o` (提供商从模型 id 推断；`gpt-*` / `o1-*` / `o3-*` / `o4-*` → OpenAI)。 | | **语音 — STT (`nimbus voice listen`)** | 位于 PATH 中的 `whisper-cli` (whisper.cpp)，以及用于音频捕获的 `ffmpeg` | 从源代码构建 whisper.cpp 或通过 `brew install whisper-cpp` 安装；`ffmpeg` 通过您的发行版/`brew` 安装。如果不在 PATH 中，请设置 `voice.whisper_path`。 | | **语音 — TTS** | macOS: `say` (内置)。Windows: PowerShell SAPI (内置)。Linux: `espeak-ng` (首选) 或 `spd-say` | `sudo apt install espeak-ng` / `brew install espeak-ng`。 | | **唤醒词循环** | 与 STT 相同，加上在操作系统层面配置的麦克风 | 使用 `nimbus doctor` 验证——当 `[voice].enabled = true` 时会显示语音部分。 | | **Embedding 或 LLM 的 GPU 加速** | 特定于提供商 (CUDA, ROCm, Metal)。Nimbus 通过 `GpuArbiter` 序列化 GPU 访问 | 配置您的提供商的 GPU 支持；Nimbus 不需要任何额外配置。 | 安装完成后，运行 **`nimbus doctor`**——它会检查上述所有先决条件，并为缺失的任何内容打印可操作的修复建议。 ### 安装 #### Linux (`.deb`) `.deb` 文件名包含版本号（例如 `nimbus-headless_0.1.0_amd64.deb`）。将 `VER` 设置为不带前导 `v` 的发布标签（参见 [Releases](https://github.com/nimbus-agent/Nimbus/releases/latest)）： ``` VER=0.1.0 curl -L "https://github.com/nimbus-agent/Nimbus/releases/download/v${VER}/nimbus-headless_${VER}_amd64.deb" -o nimbus.deb curl -L "https://github.com/nimbus-agent/Nimbus/releases/download/v${VER}/nimbus-headless_${VER}_amd64.deb.asc" -o nimbus.deb.asc gpg --keyserver keys.openpgp.org --recv-keys 5A20457CCD8B53FFAA945240886ADA6B487CAB6E gpg --verify nimbus.deb.asc nimbus.deb sudo dpkg -i nimbus.deb ``` `.deb` 包将 `nimbus` 和 `nimbus-gateway` 包装器安装在 `/usr/local/bin` 下——对于任何 Debian/Ubuntu 用户而言，该路径已在 `PATH` 中。 #### macOS (tarball) ``` # Apple Silicon curl -L https://github.com/nimbus-agent/Nimbus/releases/latest/download/nimbus-headless-macos-arm64.tar.gz -o nimbus.tar.gz # Intel # curl -L https://github.com/nimbus-agent/Nimbus/releases/latest/download/nimbus-headless-macos-x64.tar.gz -o nimbus.tar.gz tar -xzf nimbus.tar.gz cd nimbus-* ./install.sh --yes # 打开一个新的 shell，然后： nimbus --version ``` 捆绑的 `install.sh` 将二进制文件复制到 `~/.local/bin`，并向您的 shell rc 文件添加一个带哨兵的代码块，以便自动更新 PATH。无需 sudo。运行 `./uninstall.sh --yes` 即可还原。 #### Windows (zip) ``` Invoke-WebRequest https://github.com/nimbus-agent/Nimbus/releases/latest/download/nimbus-headless-windows-x64.zip -OutFile nimbus.zip Expand-Archive nimbus.zip cd (Get-ChildItem nimbus-*).Name .\install.ps1 -Yes # 打开一个新的 shell，然后： nimbus --version ``` 捆绑的 `install.ps1` (PowerShell 7+) 将二进制文件复制到 `%LOCALAPPDATA%\Programs\Nimbus\bin`，并通过 `.NET` 注册表 API 将其添加到您的用户 PATH 中（无需管理员权限，没有 `setx` 截断风险）。运行 `.\uninstall.ps1 -Yes` 即可还原。 #### AppImage (Linux) AppImage 文件名包含版本号（例如 `nimbus-headless-0.1.0-x86_64.AppImage`）。将 `VER` 设置为不带前导 `v` 的发布标签： ``` VER=0.1.0 curl -L "https://github.com/nimbus-agent/Nimbus/releases/download/v${VER}/nimbus-headless-${VER}-x86_64.AppImage" -o Nimbus.AppImage chmod +x Nimbus.AppImage # 直接运行： ./Nimbus.AppImage --version ``` #### Linux (tarball) Linux tarball 文件名包含版本号（例如 `nimbus-headless-linux-amd64-v0.1.0.tar.gz`）： ``` VER=0.1.0 curl -L "https://github.com/nimbus-agent/Nimbus/releases/download/v${VER}/nimbus-headless-linux-amd64-v${VER}.tar.gz" -o nimbus.tar.gz tar -xzf nimbus.tar.gz cd nimbus-* ./install.sh --yes ``` #### 验证下载 每次发布都会附带一个经过 GPG 签名的 `SHA256SUMS.asc`： ``` curl -L https://github.com/nimbus-agent/Nimbus/releases/latest/download/SHA256SUMS -o SHA256SUMS curl -L https://github.com/nimbus-agent/Nimbus/releases/latest/download/SHA256SUMS.asc -o SHA256SUMS.asc gpg --keyserver keys.openpgp.org --recv-keys 5A20457CCD8B53FFAA945240886ADA6B487CAB6E gpg --verify SHA256SUMS.asc SHA256SUMS sha256sum --check --ignore-missing SHA256SUMS ``` 指纹发布在 [`docs/release/SIGNING-KEY.asc`](release/SIGNING-KEY.asc) 和[安全策略](SECURITY.md)中。 ### 选项 B — 从源代码构建 ``` git clone https://github.com/nimbus-agent/Nimbus.git cd Nimbus bun install # NOT "bun run install" — that looks for a script and fails # Installs sharp + platform @img/sharp-* for embeddings (via @xenova/transformers) bun run build ``` 构建好的 CLI 位置： | 操作系统 | 路径 | |---|---| | Windows | `packages\cli\dist\nimbus.exe` | | macOS / Linux | `./packages/cli/dist/nimbus` | 将 `packages/cli/dist` 添加到您的 `PATH` 中，或使用完整路径调用。 ### 首次运行配置 Gateway 首次启动时，它会在平台配置目录中创建一个默认的 `nimbus.toml`，并在数据目录中创建一个空的 SQLite 索引： | 平台 | 配置 (`nimbus.toml`) | 数据 (`index.db`, `audit.db`, `backups/`, `logs/`) | |---|---|---| | Windows | `%APPDATA%\Nimbus\nimbus.toml` | `%LOCALAPPDATA%\Nimbus\data` | | macOS | `~/Library/Application Support/Nimbus/nimbus.toml` | `~/Library/Application Support/Nimbus/data` | | Linux | `~/.config/nimbus/nimbus.toml` | `~/.local/share/nimbus` | 如果您需要为每个配置文件或环境设置独立的目录树，可以使用 `NIMBUS_CONFIG_DIR` / `NIMBUS_DATA_DIR` 进行覆盖。大多数 TOML 键也有对应的带有 `NIMBUS_` 前缀的环境变量覆盖，其优先级高于配置文件（例如 `NIMBUS_AGENT_MODEL`、`NIMBUS_CLASSIFIER_MODEL`、`NIMBUS_TELEMETRY_ENABLED`）——参见 [`cli-reference.md`](./cli-reference.md#environment-variables)。 在运行第一次 `nimbus ask` 之前选择一个 LLM——如果没有 LLM，Agent 将没有推理表面。提供商会从模型 id 中自动推断：`claude-*` → Anthropic，`gpt-*` / `o1-*` / `o3-*` / `o4-*` → OpenAI，其他情况则回退到本地提供商。 ``` # 云端（默认 — 实现可用安装的最快途径）。 # 默认为 claude-sonnet-4-6 (agent) + claude-haiku-4-5-20251001 (classifier)； # 仅在需要覆盖时设置这些。 export ANTHROPIC_API_KEY=sk-ant-… nimbus config set llm.remote_model claude-sonnet-4-6 nimbus config set llm.classifier_model claude-haiku-4-5-20251001 # 或完全本地化（无网络调用；需要 Ollama 正在运行） ollama pull llama3.1:8b nimbus config set llm.local_model llama3.1:8b nimbus config set llm.prefer_local true ``` 有关完整的 `nimbus.toml` 模式，请参阅 [`docs/cli-reference.md`](./cli-reference.md#configuration-file)。 ### 启动 Gateway ``` nimbus start # Start Gateway as a background process nimbus status # Verify it's running; check connector health nimbus doctor # Re-run any time something seems off — checks Bun, Vault, Gateway, index, voice, … ``` ### 服务认证 ``` # 云存储与通信 nimbus connector auth google # OAuth PKCE — opens browser nimbus connector auth microsoft # 开发者服务 nimbus connector auth github # PAT — stored in OS keystore nimbus connector auth gitlab nimbus connector auth linear nimbus connector auth jira nimbus connector auth slack nimbus connector list # All connectors + sync status ``` ### 查询 ``` nimbus ask "Find all PDFs I received by email last month that I haven't opened" nimbus ask "Which of my open PRs mention payment-service?" nimbus ask "What Linear issues am I assigned this week?" nimbus search --service google_drive --type pdf --since 30d nimbus sync all ``` ### 观察与调试 ``` # 环境健康检查 — 出现异常时首先运行此项 nimbus doctor # 结构化索引查询 nimbus query --service github --type pr --since 7d --json nimbus query --sql "SELECT title FROM items WHERE pinned = 1" --pretty # 诊断和慢查询 nimbus diag nimbus diag slow-queries --limit 10 # Connector 健康历史记录 nimbus connector history github # 按指定深度重新摄取 Connector（修剪现有的 body/embeddings；写入审计条目） nimbus connector reindex github --depth metadata_only # 数据库完整性 nimbus db verify nimbus db repair # --yes to skip confirmation nimbus db snapshot ``` ### 配置 ``` nimbus config list nimbus config get sync.intervalSeconds nimbus config set sync.intervalSeconds 300 nimbus config validate nimbus profile create work nimbus profile switch work nimbus profile list ``` ### 运行脚本 ``` nimbus run ./weekly-cleanup.yml ``` ``` # weekly-cleanup.yml name: weekly-cleanup steps: - Find all PDF files in Google Drive not opened in 90 days - Summarize them by project folder - Move the ones from the Zurich project to /Archive/2025 - Send me an email with the summary ``` 在执行之前，Nimbus 会显示完整的计划预览，标识出每一个需要授权的步骤： ``` Script: weekly-cleanup (4 steps) Step 1 Find PDFs not opened in 90 days READ — no approval needed Step 2 Summarize by project folder READ — no approval needed Step 3 Move 12 files to /Archive/2025 ⚠ REQUIRES APPROVAL Step 4 Send summary email ⚠ REQUIRES APPROVAL Proceed? [y/n]: ``` ### 安装社区扩展 ``` nimbus extension install @community/nimbus-notion nimbus extension list ``` ## 技术栈 | 层级 | 技术 | |---|---| | **运行时** | [Bun v1.2+](https://bun.sh) — 原生 TypeScript，快速启动，内置 SQLite | | **语言** | TypeScript 6.x 严格模式 | | **Agent 框架** | [Mastra](https://mastra.ai) — 结构化 Agent、工具注册、工作流编排 | | **集成协议** | [Model Context Protocol](https://modelcontextprotocol.io) — 所有连接器均使用 MCP 通信；引擎从不直接调用云 API | | **本地数据库** | `bun:sqlite` + [sqlite-vec](https://github.com/asg017/sqlite-vec) — 元数据索引 + 向量搜索 | | **密钥管理 — Windows** | Windows DPAPI | | **密钥管理 — macOS** | Keychain Services | | **密钥管理 — Linux** | 通过 `libsecret` 的 Secret Service API | | **IPC** | 基于 Domain Socket / Named Pipe 的 JSON-RPC 2.0 — 仅限本地，无 TCP 攻击面 | | **CLI** | Bun + [@clack/prompts](https://github.com/natemoo-re/clack) | | **桌面 UI** | [Tauri 2.0](https://tauri.app) + React 19 (~5MB 原生外壳) | | **LLM** | Anthropic Claude (默认) / 可通过 Mastra 模型抽象进行配置 | | **Embeddings** | `@xenova/transformers` (本地，无需 API 密钥) / OpenAI (可选) | | **扩展 SDK** | `@nimbus-dev/sdk` (MIT 许可的 npm 包) | | **客户端库** | `@nimbus-dev/client` (MIT 许可的 npm 包) — 类型化 IPC 包装器；为脚本和扩展提供 `MockClient` | | **测试 — Gateway/CLI** | `bun test` | | **测试 — UI** | Vitest + `@testing-library/react` | | **测试 — 桌面端 E2E** | Playwright + Tauri WebDriver | | **CI** | GitHub Actions — PR：Ubuntu `pr-quality`；Push：完整的 3 平台矩阵 | | **发布** | `bun build --compile` — 每个平台一个签名二进制文件 | ## 跨平台支持 | | Windows 10+ | macOS13+ | Ubuntu 22.04+ † | |---|---|---|---| | **Gateway IPC** | Named Pipe | Unix Socket | Unix Socket | | **密钥管理** | DPAPI | Keychain | libsecret | | **自动启动** | 注册表 | LaunchAgents | systemd user | | **通知** | Win32 Toast | NSUserNotification | libnotify/D-Bus | | **配置目录** | `%APPDATA%\Nimbus` | `~/Library/…/Nimbus` | `~/.config/nimbus` | | **桌面 UI** | WebView2 | WKWebView | WebKitGTK | | **CI 运行器** | `windows-2025` | `macos-15` | `ubuntu-24.04` | | **发布** | `.zip` (未签名，v0.1.0 截止线) † | `.tar.gz` (未签名，v0.1.0 截止线) † | `.deb` (GPG 签名) + AppImage | † **Ubuntu 22.04 仅支持源码构建。** 预编译的 Linux 二进制文件在 Ubuntu 24.04 上编译，运行时需要 **glibc ≥ 2.39** (Ubuntu 24.04+、Fedora 40+、Debian 13+、Arch / 其他当前的滚动发行版)。Ubuntu 22.04 LTS、Debian 12 和 RHEL 9 (及其衍生版) 将因 `GLIBC_2.39 not found` 而失败。有关官方支持的发行版列表及理由，请参见 [SECURITY.md](./SECURITY.md#linux-runtime-support--glibc-floor)。 † **macOS 和 Windows 在 v0.1.0 中未签名发布。** 跨平台完整性由 GPG 签名的 `SHA256SUMS.asc` 清单提供。macOS Gatekeeper 和 Windows SmartScreen 将在首次运行时提示；这是预期行为。Apple Developer 公证和 Windows Authenticode 签名推迟到后续的修订版本中——参见 [SECURITY.md](./SECURITY.md#v010-signing-cut-line)。 ## 安全性 - **无明文凭据** — OAuth token 存在于操作系统密钥库中。没有任何代码路径会将它们写入其他位置。 - **结构化 HITL 门控** — 每次删除、发送和移动操作都会在执行器中被编译时常量集拦截。Agent 无法通过推理绕过一个不存在的函数。 - **扩展隔离** — 第三方扩展作为子进程运行，仅接收其声明的服务的凭据，无法访问 Vault 或其他连接器。每次 Gateway 启动时都会验证清单 SHA-256。 - **完整审计日志** — 每个操作（包括每个 HITL 决策）都会在操作执行前记录到本地 SQLite 表中。 - **内部安全审计 (B1，2026-04-25)** — 审查了 8 个信任面；提交了 78 个独立发现 (0 个严重)；所有高和中级别项目均在 `v0.1.0` 前关闭。剩余三个低级别项目作为 Phase 4 的打磨工作；有关完整记录，请参见 [SECURITY.md](./SECURITY.md#security-audits)。正式的第三方渗透测试计划在 Phase 12 进行。 ## 扩展 编写一个新连接器只需一个下午，而不是一个冲刺周期。`@nimbus-dev/sdk` 负责脚手架搭建；Gateway 负责 OAuth、凭据存储、同步调度和 HITL 强制执行。您只需编写服务 API 集成。 ``` nimbus scaffold extension --name my-connector --output ./nimbus-my-connector cd nimbus-my-connector && bun install && bun run build nimbus extension install . # Test locally nimbus ask "search my-connector for quarterly review" npm publish --access public # Publish to the community ``` 扩展在 `nimbus.extension.json` 中声明权限。写入和删除工具必须声明 `hitlRequired`——无论扩展如何实现它们，Gateway 都会自动对这些工具调用强制执行 HITL。 ## 测试 五层金字塔： 1. **单元测试 (`bun test`)** — 引擎逻辑、Vault 契约、HITL 不变量、清单验证。与源码同置。在毫秒内运行。 2. **集成测试 (`bun test` + 真实 SQLite)** — 连接器同步、索引查询、扩展加载和隔离。每个测试都有一个全新的临时目录和全新的 DB。 3. **E2E CLI (`bun test` + Gateway 子进程)** — 针对由模拟 MCP 服务器支持的真实 Gateway 的完整 CLI 命令流。 4. **UI 组件 (Vitest + Testing Library)** — Tauri WebView 中的 React 组件。此处使用 Vitest 是因为 `bun test` 不支持 jsdom。 5. **桌面端 E2E (Playwright + Tauri WebDriver)** — 在所有三个平台上的完整桌面流程。在推送到 `main` 和发布标签时运行。 安全扫描：每个 PR 都会运行 `bun audit`、`trivy`、CodeQL；使用 Dependabot 进行依赖项更新。高/严重级别发现将阻止合并。 ## 项目结构 ``` nimbus/ ├── packages/ │ ├── gateway/ # Core headless Gateway (Bun) │ │ └── src/ │ │ ├── platform/ # PAL: win32, darwin, linux implementations │ │ ├── engine/ # Mastra agent, router, planner, HITL executor │ │ ├── vault/ # DPAPI, Keychain, libsecret │ │ ├── db/ # verify, repair, snapshot, health, metrics, latency ring buffer │ │ ├── connectors/ # Connector registry, lazy mesh, health model │ │ ├── sync/ # Delta sync scheduler, connectivity probe │ │ ├── extensions/ # Extension Registry, manifest validator │ │ ├── telemetry/ # Opt-in aggregate telemetry collector │ │ ├── config/ # Config loader, profiles, env-var overrides │ │ ├── llm/ # Ollama + llama.cpp providers, router, registry, GPU arbiter │ │ ├── voice/ # STT (whisper-cli), TTS (NativeTtsProvider), wake-word │ │ └── ipc/ # JSON-RPC 2.0 server, HTTP API, Prometheus endpoint │ ├── cli/ # nimbus CLI │ │ └── src/commands/ # ask, search, query, config, profile, diag, doctor, │ │ # db, telemetry, connector, extension, workflow, status │ ├── client/ # @nimbus-dev/client (published to npm, MIT) │ ├── ui/ # Tauri 2.0 desktop app (Phase 4) │ │ └── src/ │ │ ├── components/ # ConsentDialog, ExtensionMarketplace, … │ │ └── pages/ # Dashboard, Search, Marketplace, Settings │ ├── docs/ # Astro Starlight documentation site │ ├── mcp-connectors/ # First-party MCP servers │ │ ├── google-drive/ │ │ ├── gmail/ │ │ ├── github/ │ │ └── … # (all 15+ shipped connectors) │ └── sdk/ # @nimbus-dev/sdk (published to npm, MIT) ├── docs/ │ ├── README.md # this file │ ├── architecture.md # subsystem design │ ├── SECURITY.md # security model + vulnerability reporting │ ├── roadmap.md # acceptance-criteria-driven roadmap │ ├── CONTRIBUTING.md # contributor workflow and constraints │ ├── CODE_OF_CONDUCT.md # community standards │ ├── release/ # release runbooks + manual smoke checklist │ ├── templates/ # copy-paste CI (e.g. extension authors) │ └── contributors/ # author walkthroughs ├── .github/ │ ├── workflows/ │ │ ├── ci.yml # pr-quality + 3-platform matrix │ │ ├── security.yml # bun audit + trivy │ │ ├── codeql.yml │ │ └── release.yml # signed binaries → GitHub Releases │ └── BRANCH_PROTECTION.md ├── bunfig.toml └── package.json # Bun workspace root ``` ## 路线图 Nimbus 使用阶段而不是日期来划分。当一个阶段的验收标准通过时，该阶段即告完成。 | 阶段 | 主题 | 状态 | |---|---|---| | 1 | 基础 | ✅ 完成 | | 2 | 桥梁 (15 个连接器) | ✅ 完成 | | 3 | 智能 (语义搜索、CI/CD、云) | ✅ 完成 | | 3.5 | 可观测性 (健康模型、查询 API、恢复、遥测、文档) | ✅ 完成 | | 4 | 存在 (本地 LLM、多 Agent、语音、VS Code 扩展、TUI；桌面 UI 代码完成) | ✅ 完成 | | 5 | 扩展面 | 🔵 进行中 | | 6 | 团队 — *同时发布 `desktop-v0.1.0`* (Tauri 安装程序 + 签名，从 `v0.1.0` 推迟) | 计划中 | | 7–9 | 自主 Agent → 主权网格 → 企业版 | 计划中 | 有关完整的验收标准和顺序，请参见 [`roadmap.md`](./roadmap.md)。 ## 发布流程 ``` git tag v0.1.0 git push origin v0.1.0 # → release.yml 为 Linux、macOS、Windows 编译 Gateway + CLI # → 使用二进制文件 + GPG 签名的 SHA256SUMS.asc 创建 GitHub Release # （Linux .deb / .AppImage 经过 GPG 签名；macOS .tar.gz 和 Windows .zip # 在 v0.1.0 版本中未签名 — 完整性由 SHA256SUMS.asc 清单保证。 # Tauri 桌面安装程序将在稍后通过 `desktop-v0.1.0` 标签发布。） ``` ## 贡献 架构正在趋于稳定；并非所有接口都已定型。 1. 阅读 [`architecture.md`](./architecture.md) — 了解四个子系统及其契约。 2. 审查下面的**不可协商原则** — 它们不是愿景性的价值观；违反这些原则的 PR 将不会被合并。 3. 查看带有 `good first issue` 标签的议题。 4. 在提交大型 PR 之前先发起讨论。 有关工作流、验证命令和 PR 预期，请参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。社区标准在 [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) 中。 **不可协商原则** — 违反这些原则的 PR 将不会被合并： - 本地优先：未经用户明确操作，不得将凭据或用户数据传出机器 - HITL 是结构性的：授权门控在执行器中，而不是在 prompt 中 - 禁止明文凭据：仅限 Vault - 平台平等：始终支持所有三个平台 - MCP 作为连接器标准：引擎从不直接调用云 API - 许可完整性：对核心包的贡献必须与 AGPL-3.0 兼容 ## 定价 | 层级 | 适用对象 | 状态 | |---|---|---| | **开源** | 个人工程师 — AGPL-3.0，包含单用户部署的全部功能 | 现已提供 | | **团队版** | 共享索引命名空间、Team Vault、多用户 HITL、LAN 联邦 — Phase 6 | 计划中 | | **企业版** | SSO/SCIM、合规工具、审计日志上传、Helm/Docker、SLA 支持 — Phase 12 | 计划中 | 扩展 SDK (`@nimbus-dev/sdk`) 采用 MIT 许可——扩展作者没有 Copyleft 义务。 用于将 Nimbus 嵌入到产品中而不受 AGPL 义务约束的商业许可，或者在团队/企业版功能发布前需要这些功能的组织：请联系维护者。 ## 许可协议 **核心 (Gateway、CLI、连接器)：** AGPL-3.0——参见 [LICENSE](../LICENSE)。任何将 Nimbus 作为网络服务运行的人都必须在相同的条款下发布其修改。这是有意为之：AGPL 通过防止供应商剥夺隐私保证并提供托管版的“Nimbus Cloud”来保护用户。 **扩展 SDK (`@nimbus-dev/sdk`)：** MIT——扩展作者不受 Copyleft 义务的约束。

**[架构](./architecture.md) · [路线图](./roadmap.md) · [安全性](./SECURITY.md) · [发布版本](https://github.com/nimbus-agent/Nimbus/releases)**

标签：AGPL-3.0, AIOps, AI代理, AI风险缓解, Bun, HITL, Incident Response, Local-first, MCP协议, Model Context Protocol, Nimbus, On-call, SecDevOps, SQLite, TypeScript, 云端监控, 人机交互, 凭据管理, 告警处理, 安全插件, 平台工程, 开源, 待命响应, 故障排查, 智能运维, 本地优先, 本地部署, 源代码管理, 网络安全, 网络调试, 自动化, 自动化攻击, 跨服务分析, 运维自动化, 隐私保护