hypervibe

# 超级振动 hypervibe > AI 原生基础设施管理。告诉 Claude 你需要什么，看看它如何部署。 [](https://opensource.org/licenses/Apache-2.0) [](https://nodejs.org/) [](https://modelcontextprotocol.io/) Hypervibe 是一个 [MCP 服务器](https://modelcontextprotocol.io/)，使 Codex/Claude 能够通过自然对话管理你的基础设施。只需连接一次你的提供商，然后通过询问部署、配置和管理一切。 ``` 你： "将我的应用部署到 staging 环境，并使用 postgres 数据库" Claude： 创建 Railway 项目，配置 Postgres，连接 DATABASE_URL， 部署你的代码，设置健康检查，返回 URL。 ``` ## 功能特点 **基础设施提供商** - **Railway** - 部署应用、数据库、Redis、cron 作业 - **Cloudflare** - DNS 管理、域名配置 - **Stripe** - 支付集成、Webhook、产品 - **SendGrid** - 电子邮件身份验证、域名验证 - **reCAPTCHA** - 机器人保护设置 **密钥管理器** - **HashiCorp Vault** - 版本化的 KV 密钥 - **AWS Secrets Manager** - 原生轮换支持 - **Doppler** - 简单的配置管理 **开发者体验** - **自然语言** - 无 YAML，无需点击仪表盘 - **自动连接** - 自动连接 DATABASE_URL、REDIS_URL - **环境管理** - Staging、生产、PR 预览 - **迁移支持** - 运行 Prisma、Drizzle、TypeORM 迁移 - **本地开发** - 为本地对等生成 Docker Compose - **密钥轮换** - 轮换一次，传播到所有环境 - **审计跟踪** - 跟踪部署过程中的密钥访问 ## 快速入门 ### 1. 安装作为 Codex MCP ```bash codex mcp add hypervibe -- npx -y @davejohnson/hypervibe@latest codex mcp list ``` ### 2. 安装为 Claude Code MCP 添加到 `~/.claude/settings.json`： ```json { "mcpServers": { "hypervibe": { "command": "npx", "args": ["-y", "@davejohnson/hypervibe@latest"] } } } ``` ### 3. 连接提供商 重启 Claude Code，然后： ``` 你： "连接到 Railway" Claude： 打开浏览器进行 Railway OAuth，安全保存凭证。 你： "连接 Cloudflare，API 令牌 xyz..." Claude： 验证并存储连接。 ``` ### 4. 部署 ``` 你： "创建一个名为 my-app 的新项目，包含 staging 和 production 环境" 你： "部署到 staging 环境" 你： "添加自定义域名 api.myapp.com" 你： "运行数据库迁移" ``` ### 5. 管理密钥（可选） 连接密钥管理器，让 hypervibe 在部署时注入密钥： ``` 你： "连接到 Vault，地址为 https://vault.mycompany.com" 你： "将 DATABASE_URL 映射到 vault://secret/data/myapp/db#url" 你： "部署到生产环境" Claude： 从 Vault 解析密钥，注入 Railway，部署。 你： "轮换数据库密钥并同步到所有环境" Claude： 在 Vault 中轮换，更新所有映射环境。 ``` 密钥引用使用以下格式：`provider://path[#key][@version]` ## 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ Claude Code │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Hypervibe MCP 服务器 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ 项目 │ │ 部署 │ │ 密钥 │ ... │ │ │ │ │ 工具 │ │ 工具 │ │ 工具 │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ └──────────────┼──────────────┘ │ │ │ │ ▼ │ │ │ │ ┌──────────────────────┐ ┌────────────────────┐ │ │ │ │ │ 提供商注册表 │ │ 密钥管理器注册表│ │ │ │ │ │ Railway │ Cloudflare │ │ Vault│AWS│Doppler │ │ │ │ │ └──────────────────────┘ └────────────────────┘ │ │ │ └─────────────────────────────────────────────────────┘ │ │ ▼ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Railway │ │Cloudflare│ │ Vault │ │ AWS │ │ │ │ API │ │ API │ │ API │ │ 密钥 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ## 可用工具 Hypervibe 暴露了一组专注于意图级别的 `hv_*` 工具。核心是一个类似 Terraform 的循环： 1. `hv_spec_set` — 以修订版规格声明所需状态（服务、数据库、域名、电子邮件、环境变量） 2. `hv_plan` — 观察实时基础设施，与规格进行差异比较，并获取可执行计划 3. `hv_apply planId=...` — 收敛。过时的计划被拒绝；销毁带有数据资源的资源需要明确确认 4. `hv_status` — 随时查看期望状态和观测状态之间的差异 围绕核心：连接 (`hv_connect`)、部署/回滚、日志/错误/健康检查、数据库查询/迁移、密钥、域名/DNS、电子邮件、支付、CI、应用商店/测试飞行和本地开发工具。 - 完整的生成目录：`docs/TOOLS.md` - 在工具更改后重新生成：`npm run build && npm run docs:tools` ## 团队共享的期望状态 Hypervibe 将基础设施视为一个依赖于存储库的定义，而不是一个用户的私有本地状态。当从 git 工作目录运行时，`hv_spec_set` 将期望的基础设施形状写入： ```text .hypervibe/spec.json ``` 将该文件与应用程序一起提交。它是环境、服务、cron 作业、数据库、域名、电子邮件、环境变量、部署策略和迁移的共享真实来源。当队友克隆存储库并运行 `hv_spec_get`、`hv_plan` 或 `hv_status` 时，Hypervibe 读取此文件，创建本地项目缓存（如果需要），并在应用之前报告任何缺失的提供商连接。 Hypervibe 还在以下文件中维护非机密的提供商身份绑定： ```text .hypervibe/bindings.json ``` 此文件允许队友观察和收敛相同的提供商资源，而不是规划重复的项目/服务。它用于非机密 ID，例如提供商项目 ID、环境 ID、服务 ID、自定义域名绑定和 CI 工作流同步元数据。凭证、令牌、密码、数据库 URL 和机密值保留在存储库之外，并保留在提供商/本地一侧。 典型的团队流程： 1. 一个人通过 Hypervibe 更改基础设施，例如添加 cron 服务。 2. Hypervibe 更新 `.hypervibe/spec.json` 和应用后更新 `.hypervibe/bindings.json`。 3. 他们提交这些文件。 4. 队友拉取，运行 `hv_plan`，并看到相同的期望形状和提供商绑定。 5. 每个队友在需要时使用 `hv_connect` 连接自己的提供商凭证。 ## 提供商凭证 ### Cloudflare 令牌权限 DNS、自定义域名和电子邮件路由的推荐默认值：使用 **Cloudflare 账户 API 令牌** 加 `accountId`。Cloudflare 推荐使用账户 API 令牌作为自动化凭证，与特定用户无关。 在以下位置创建推荐的账户 API 令牌： ```text Cloudflare 仪表盘 -> 管理账户 -> 账户 API 令牌 https://dash.cloudflare.com/?to=/:account/api-tokens ``` 设置这些权限和资源： ```text 权限： - Zone -> Zone -> 读取 - Zone -> Zone 设置 -> 读取或编辑 - Zone -> DNS -> 编辑/写入 区域资源： - 包括 -> 特定区域 -> example.com ``` 使用生成的令牌秘密本身作为 `CLOUDFLARE_API_TOKEN`；不要使用令牌名称、令牌 ID 或旧的全局 API 密钥。新用户 API 令牌通常以 `cfut_` 开头；账户 API 令牌通常以 `cfat_` 开头。 连接时无需将令牌粘贴到聊天中。如果值位于现有的 `.env` 文件中，请直接引用键名： ```text hv_connect provider=cloudflare scope="example.com" credentialsRef="dotenv:/绝对路径/.env" credentialsMap={"apiToken":"CLOUDFLARE_API_TOKEN","accountId":"CLOUDFLARE_ACCOUNT_ID"} ``` Hypervibe 接受原始令牌或复制的授权值，例如 `Bearer <token>` 用于 Cloudflare。 如果 Hypervibe 需要 Cloudflare 注册商/域名购买，请改用 **用户 API 令牌**，因为 Cloudflare 注册商与账户 API 令牌不兼容。在 `我的个人资料 -> API 令牌 -> 创建令牌 -> 编辑区域 DNS` 下创建它，添加上述相同的区域权限，然后连接它而不带 `accountId`： ```text Cloudflare 仪表盘 -> 我的个人资料 -> API 令牌 https://dash.cloudflare.com/profile/api-tokens ``` ```text hv_connect provider=cloudflare scope="example.com" credentialsRef="dotenv:/绝对路径/.env#CLOUDFLARE_API_TOKEN" ``` 如果令牌有效，但 Hypervibe 无法在 `hv_connect` 期间确认区域访问，则连接仍将被保存并带有警告；`hv_plan`/`hv_apply` 将显示任何剩余的 DNS 或注册商特定的阻止程序。 ### GitHub 令牌权限 推荐：连接时无需将令牌粘贴到聊天中，通过本地导出： ```bash export HYPERVIBE_GITHUB_TOKEN=ghp_... ``` 然后调用 `hv_connect provider=github credentialsRef="env:HYPERVIBE_GITHUB_TOKEN"`。对于现有的 `.env` 文件，使用 `credentialsRef="dotenv:/绝对路径/.env#HYPERVIBE_GITHUB_TOKEN"`。对于 JSON 凭证，将 JSON 保存到本地文件并使用 `credentialsRef="file:/绝对路径/credentials.json"`。如果用户故意要在聊天中输入凭证，仍然接受 `credentials={...}`。 **CI 部署推荐：具有 `repo`、`workflow` 和 `read:packages` 的经典 PAT**，由具有目标存储库访问权限的用户创建。从以下位置创建： ```text https://github.com/settings/tokens/new?scopes=repo,workflow,read:packages&description=Hypervibe%20CI%20deploys ``` 该令牌可用于： - `apiToken`：GitHub API 工作，例如编写 `.github/workflows/*`、读取 Actions 运行/作业/日志、触发工作流和创建存储库密钥。 - `packageReadToken`：持久的 GHCR 映像拉取凭证，用于 Railway 和 DigitalOcean 等提供商。 对于现有的 `.env` 文件，使用一个令牌： ```text HYPERVIBE_GITHUB_TOKEN=ghp_... ``` 连接如下： ```text hv_connect provider=github scope="owner/repo" credentialsRef="dotenv:/绝对路径/.env" credentialsMap={"apiToken":"HYPERVIBE_GITHUB_TOKEN","packageReadToken":"HYPERVIBE_GITHUB_TOKEN"} ``` 对于最小权限，使用两个经典 PAT： ```text HYPERVIBE_GITHUB_TOKEN=ghp_... # 作用域：repo，workflow HYPERVIBE_GITHUB_PACKAGES_TOKEN=ghp_... # 作用域：read:packages ``` 然后连接： ```text hv_connect provider=github scope="owner/repo" credentialsRef="dotenv:/绝对路径/.env" credentialsMap={"apiToken":"HYPERVIBE_GITHUB_TOKEN","packageReadToken":"HYPERVIBE_GITHUB_PACKAGES_TOKEN"} ``` 仅具有 `read:packages` 的令牌 **不足以** 设置 Hypervibe CI 部署。它可以作为 `packageReadToken`，但 `apiToken` 仍需要 `repo` + `workflow` 以适用于经典 PAT，因此 Hypervibe 可以管理工作流和存储库密钥。 Hypervibe 使用 GitHub 令牌的功能以及每个操作需要的权限： | 操作 | 经典 PAT 作用域 | 精细粒度权限 | |---|---|---| | 提交 CI/配置（`hv_ci_setup`：工作流、AI 审查、Pages CNAME、SEO 文件） | `repo`（+ `workflow` 用于 `.github/workflows/` 下的文件） | 内容：读取/写入 | | 列出/触发 Actions 工作流，读取运行/作业/日志（`hv_ci_status`、`hv_ci_trigger`） | `repo` | Actions：读取/写入 | | 设置/删除 Actions 存储库密钥（`hv_secrets_set target="github"`） | `repo` | 密钥：读取/写入 | | 分支保护（`hv_ci_setup kind="branch-protection"`） | `repo` + 存储库管理员 | 管理：读取/写入 | | GitHub Pages（`hv_ci_setup kind="pages"`） | `repo` | Pages：读取/写入 | | 生成推送部署（`hv_ci_setup kind="deploy-branch"`） | `repo` + `workflow`；如果 Hypervibe 应同步提供商 API 令牌，请添加密钥读取/写入 | 内容：读取/写入，Actions：读取/写入，密钥：读取/写入 | | 对于选定的存储库安装的 Railway GitHub 应用存储库访问权限管理（`deploy.trigger: "native"`） | `repo` + 存储库管理员 - **仅限经典 PAT**；GitHub 的应用安装 API 不接受细粒度 PAT | 不支持 | | 私有存储库源获取，用于 Cloud Run 构建 | `repo` | 内容：读取 | 细粒度 PAT 可以适用于表中的某些 GitHub API 操作，但授予的权限必须与表中列出的权限相同。如果使用细粒度 PAT 作为 `apiToken`，请提供具有 `read:packages` 作用域的经典 PAT 作为 `packageReadToken`，用于 Railway/DigitalOcean GHCR 部署。 ### 推送部署 `deploy.strategy: "branch"` 默认值为 `deploy.trigger: "ci"`。 Hypervibe 通过编写 GitHub Actions 工作流直接调用提供商 API 来设置推送部署；它不安装或依赖提供商 CLI。 典型设置： - 使用 `deploy: { strategy: "branch", branch: "main" }` 或显式 `trigger: "ci"` 定义环境。 - 首次运行 `hv_apply`，以便 Hypervibe 记录提供商项目、环境、服务 ID 和服务 ARN 绑定。 - 运行 `hv_ci_setup kind="deploy-branch" config={"provider":"<provider>"}`。 - 检查返回的 `requiredSecrets`、`syncedSecrets`、`manualSecrets` 和 `requiredVariables`。在提供商连接验证且 GitHub token 可以写入存储库机密时，Hypervibe 会将提供商 API 凭证同步到 GitHub Actions 机密。 提供商工作流行为： | 提供商 | 生成的 GitHub Actions 部署路径 | 通常从验证连接中同步 | Hypervibe 不已知 ID 时的手动 GitHub 值 | |---|---|---|---| | `railway` | 使用 GitHub 内置工作流令牌将 OCI 镜像构建/推送到 GHCR，更新 `ServiceInstance.source.image` 通过 Railway GraphQL，然后通过 Railway GraphQL 触发部署 | `RAILWAY_API_TOKEN`；`IMAGE_REGISTRY_USERNAME`/`IMAGE_REGISTRY_TOKEN` 来自验证的 GitHub 连接 | 变量：`RAILWAY_ENVIRONMENT_ID`，`RAILWAY_SERVICE_IDS` | | `cloudrun` | 将 OCI 镜像构建/推送到 Google Artifact Registry，通过 Google APIs 补丁 Cloud Run 服务 | `GCP_SERVICE_ACCOUNT_JSON`，`GCP_PROJECT_ID`，`GCP_REGION` | 变量：`CLOUDRUN_SERVICE_NAMES`；可选变量：`GCP_ARTIFACT_REPOSITORY` | | `apprunner` | 将 OCI 镜像构建/推送到 ECR，通过 AWS 签名 API 请求更新 App Runner 服务 | `AWS_ACCESS_KEY_ID`，`AWS_SECRET_ACCESS_KEY`，`AWS_REGION` | 变量：`APPRUNNER_SERVICE_ARNS`；可选变量：`AWS_ECR_REPOSITORY` | | `render` | 通过 Render API 触发 Render 服务部署 | `RENDER_API_KEY` | 变量：`RENDER_SERVICE_IDS` | | `digitalocean` | 使用 GitHub 内置工作流令牌将 OCI 镜像构建/推送到 GHCR，通过 DigitalOcean API 更新 App Platform 服务以使用该镜像，然后触发部署 | `DIGITALOCEAN_ACCESS_TOKEN`；`IMAGE_REGISTRY_USERNAME`/`IMAGE_REGISTRY_TOKEN` 来自验证的 GitHub 连接 | 变量：`DO_APP_ID`，`DO_SERVICE_NAMES` | | `heroku` | 将 OCI 镜像构建/推送到 Heroku 容器注册表，并通过 Heroku API 发布 `web` 进程 | `HEROKU_API_KEY` | 变量：`HEROKU_APP` | | `vercel` | 从 GitHub Actions 触发 Vercel 部署钩子 | 无 | 机密：`VERCEL_DEPLOY_HOOK_URL` | 对于 Railway 和 DigitalOcean GHCR 部署，生成的工作流授予 `packages: write` 并仅在工作流时间内使用 `${{ github.actor }}` 加上 `${{ secrets.GITHUB_TOKEN }}` 进行镜像推送。托管提供商还需要持久的镜像拉取凭证，因为 GitHub 的工作流令牌是短暂的，并且仅在 Actions 作业内存在。Hypervibe 从验证的 GitHub 连接中将这些拉取凭证同步到 `IMAGE_REGISTRY_USERNAME` 和 `IMAGE_REGISTRY_TOKEN`，当它具有登录凭证和具有读取包能力的 `packageReadToken` 时。请勿将 `${{ secrets.GITHUB_TOKEN }}` 用于 `IMAGE_REGISTRY_TOKEN`，也不要将仅具有 `read:packages` 权限的令牌用作 GitHub `apiToken`。 当 Hypervibe 同步 GitHub Actions 机密时，它仅记录机密名称和本地单向值哈希。如果本地提供商令牌后来更改，`hv_plan` 将报告 CI 部署操作需要更新，并且 `hv_apply` 将重新同步 GitHub 机密值。原始机密值从不写入 `.hypervibe/spec.json`、`.hypervibe/bindings.json` 或工具输出。 要修复过时的 GitHub Actions 机密而不将令牌粘贴到聊天中，请将 `hv_secrets_set` 指向本地真实来源： ```text hv_secrets_set project="apreskeys.com" target="github" repo="davejohnson/apreskeys.com" key="IMAGE_REGISTRY_TOKEN" secretRef="dotenv:/Users/dave/projects/condoshare/.env#GHCR_TOKEN" ``` 对于 GHCR 失败，请通过 Hypervibe 本身检查运行： ```text hv_ci_status project="apreskeys.com" repo="davejohnson/apreskeys.com" include=["logs"] runId=28272281787 ``` 如果日志包含 `docker buildx imagetools inspect ... ghcr.io ... 403 Forbidden`，则工作流尚未到达 Railway。首先修复 `IMAGE_REGISTRY_USERNAME` 和 `IMAGE_REGISTRY_TOKEN`；Railway 不会在 GHCR 镜像验证可以读取镜像之前显示新的部署尝试。 `deploy.trigger: "native"` 选择提供商原生的存储库集成。对于 Railway 原生推送自动部署，请在 GitHub 中授予 [Railway GitHub 应用](https://github.com/apps/railway-app) 访问权限： - 安装/打开 [Railway GitHub 应用](https://github.com/apps/railway-app/installations/new) 并授予其对存储库的访问权限。如果它安装在“仅限选择存储库”中，请添加目标存储库。 - 确保至少有一名 Railway 项目成员已连接 GitHub 并具有存储库的贡献者访问权限。 - 在 GitHub 中接受 Railway GitHub 应用的任何待处理权限更新。 - 权限更改后，等待几分钟让 Railway 缓存刷新，然后重新运行 `hv_status` 或 `hv_plan`。 - 如果 Railway 仍然无法看到存储库，请断开/重新连接 Railway 中的服务源，刷新添加 -> GitHub 存储库，或重新安装 Railway GitHub 应用。 ### 机密管理器 1Password 使用[服务帐户令牌](https://developer.1password.com/docs/service-accounts/) — 仅授予项目应读取的 vault(s)。Bitwarden 机密管理器使用[机器帐户访问令牌](https://bitwarden.com/help/access-tokens/)和组织 ID。两种集成都是仅解析的：hypervibe 在部署时读取值，永不写回或本地存储。 ## 配置 Hypervibe 存储数据本地： - **数据库**：`~/.hypervibe/hypervibe.db` (SQLite) - **机密**：使用 `~/.hypervibe/.secret-key` 加密 除非您连接的提供商，否则不会将任何数据发送到外部服务器。 您可以通过在启动 MCP 服务器时设置 `HYPERVIBE_DATA_DIR` 来覆盖存储位置。 ## 更新现有项目 Hypervibe 有三种状态需要保持最新： - **已安装的 Hypervibe 包** 在 Codex、Claude 或另一个 MCP 客户端中。 - **本地 Hypervibe 状态** 在 `~/.hypervibe` 中，特别是 SQLite 数据库架构和加密提供商连接。 - **存储库支持的项目状态** 在 `.hypervibe/spec.json` 和 `.hypervibe/bindings.json` 中，应与应用程序一起提交。 默认安装命令使用 `@davejohnson/hypervibe@latest`，因此用户不需要知道或记住包升级命令。当 Codex、Claude 或另一个 MCP 客户端重新启动 Hypervibe 服务器时，`npx` 解析最新发布的包，Hypervibe 在启动时自动运行任何待处理的 SQLite 迁移。 正常更新流程: 1. 重启 MCP 客户端/服务器，以便 `npx -y @davejohnson/hypervibe@latest` 启动最新的发布包。 2. 在每个应用程序存储库中，拉取最新的 `.hypervibe/spec.json` 和 `.hypervibe/bindings.json`，然后运行 `hv_status` 或 `hv_plan`。 3. 提交 Hypervibe 对 `.hypervibe/spec.json`、`.hypervibe/bindings.json`、生成的 CI 工作流或其他存储库文件所做的任何预期更改。 `hv_upgrade` 是一个诊断/修复工具，而不是必需的用户仪式。当某些内容看起来过时或更改 MCP 安装命令后，请使用它；它报告正在运行的包版本、本地 SQLite 架构版本、待处理的迁移、存储库规范/绑定状态和连接数。如果它报告待处理的 SQLite 迁移，请运行 `hv_upgrade action="migrate"` 并重新启动 MCP 服务器。 提供商凭证保持本地和加密。团队成员可能仍需要为他们自己的 Railway、GitHub、Cloudflare、SendGrid、AWS 或 GCP 访问运行 `hv_connect`，但普通的 Hypervibe 包和 SQLite 架构升级应在重启时发生。 ## 添加新提供商 提供商通过插件系统自行注册： ```typescript // src/adapters/providers/example/example.adapter.ts import { providerRegistry } from '../../../domain/registry/provider.registry.js'; export class ExampleAdapter implements IProvider { // ... 实现 } providerRegistry.register({ metadata: { name: 'example', displayName: '示例提供商', category: 'dns', credentialsSchema: ExampleCredentialsSchema, }, factory: (credentials) => new ExampleAdapter(credentials), }); ``` 然后在 `server.ts` 中导入： ```typescript import './adapters/providers/example/example.adapter.js'; ``` ## 哲学 **让 LLM 处理模糊的部分。** Hypervibe 返回原始数据，让您的代理解释它。没有复杂的模式匹配或硬编码规则 — 您的代理会弄清楚“prod-us-east”意味着生产环境。 **简单的快捷方式是可以的。** `production`、`staging`、`development` 的精确匹配立即生效。其他情况？Claude 处理它。 **两步流程确保安全。** 导入和破坏性操作会显示将要发生的操作，然后请求确认。 ## 许可证 Apache 2.0 - 参见 [LICENSE](LICENSE) 了解详情。 --- 为 [Claude Code](https://claude.ai/code) 构建。由 [MCP](https://modelcontextprotocol.io/) 提供支持。