内容
# Flow
**坚持下去。**
Flow 是您现有密钥存储的运行时注入层。您的开发人员要求 AI 设置 Google OAuth（或 Stripe，或任何集成）。AI 调用 Flow。凭证在您的应用程序启动时出现在 `process.env` 中 — 从您已经信任的密钥存储中获取内存，永远不会写入到 `.env` 文件中，永远不会粘贴到聊天中。在开发和生产环境中体验相同。无需迁移。无需新的攻击面。
Flow 解决的问题：集成设置是每个 AI 构建项目都会遇到的障碍。阅读提供商文档、同时管理多个控制台、复制粘贴密钥、修复密钥泄露事件 — 这打断了您与 AI 的对话，并需要 20-30 分钟的上下文来恢复。Flow 吸收了这种中断 *而无需* 您将密钥迁移。
## Flow 的工作原理 — 源适配器模式
Flow 有两个部分：一个 IDE 对话层（MCP 工具，AI 调用）和一个运行时注入层（`flow-vault`，一个 Node `--require` 预加载）。运行时从 *源适配器* 获取凭证，并通过 `process.env` 暴露它们。您的应用程序代码保持不变。
源适配器是可插拔的。在开发过程中，它指向 Flow 的托管保险库 — 一个共享的沙箱，允许开发人员在拥有真实凭证之前开始编码集成。在生产环境中，它指向您已经操作的密钥存储。
```
开发环境 生产环境
┌──────────────────────┐ ┌──────────────────────┐
│ flow-vault 预加载 │ │ flow-vault 预加载 │
│ ↓ 源：托管 │ │ ↓ 源：aws-sm │
│ Flow 共享保险库 │ │ AWS 密钥管理器 │
│ （沙箱凭证） │ │ （您的生产凭证） │
└──────────┬───────────┘ └──────────┬───────────┘
↓ ↓
process.env process.env
（内存中） （内存中）
↓ ↓
您的应用程序 您的应用程序
```
相同的运行时，相同的 `process.env.GOOGLE_CLIENT_ID`，相同的应用程序代码。环境之间唯一改变的是凭证映射的来源。
## Flow 与密钥存储的比较
Flow 不会取代 AWS 密钥管理器、HashiCorp Vault、Azure 密钥保管库或 GCP 密钥管理器。Flow 运行在 *它们之上*。
| 关注点 | 密钥存储 | Flow |
|---|---|---|
| 生产环境凭证存储位置 | 存储中 | 存储中（Flow 不移动它们） |
| 存储身份验证 | 存储要求的内容 | 适配器传递（OIDC、IAM、令牌等） |
| 触及应用程序文件系统的内容 | 无（正确配置） | 无 |
| 开发人员在开发环境中触及的内容 | 手动获取/同步脚本 | 对 AI 说一句话 |
| 开发人员在生产环境中触及的内容 | 控制台、CLI 或平台集成 | 与开发环境中相同的 `process.env.X` |
| 合规性姿态 | 由存储 + IAM 定义 | 继承存储的姿态；添加每个项目请求哪些密钥的清单 |
Flow 是附加的。如果您已经运行密钥存储，Flow 会以开发人员已经期望的方式将凭证提供给您的应用程序。如果您还没有，Flow 的托管源为您提供了一个开始的地方。
## 状态
预发布。实时：托管保险库 + npm 上的运行时包 + 用于 Google OAuth 和 Resend（电子邮件）的 MCP 工具（在开发环境中）（`flow_check`、`flow_status`、`flow_setup_provider`、`flow_setup_oauth` 别名、`flow_status_check`）。保险库端点按 IP 和 `install_id` 限制速率。即将推出：生产凭证接收（`flow_capture`、`flow_setup_provider（production）`）、其他源适配器（AWS 密钥管理器、HashiCorp Vault、Azure 密钥保管库、GCP 密钥管理器）、更多提供商（Stripe、Twilio）、用于密钥链会话的 `flow login` CLI。有关完整路线图，请参见 `CLAUDE.md`。
目前仅提供托管源适配器。其他适配器正在计划中，并在 [docs/source-adapters.md](docs/source-adapters.md) 中有文档记录。
## 快速入门（适用于任何支持 MCP 的 AI 工具）
将以下 JSON 代码段添加到您的 AI 工具的 MCP 配置中：
```json
{
"mcpServers": {
"flow": {
"type": "http",
"url": "https://mcp.kindtree.us/api/mcp"
}
}
}
```
粘贴位置取决于您的工具：
| 工具 | 文件路径 |
|---|---|
| **Cursor**（项目） | `<your-project>/.cursor/mcp.json` |
| **Cursor**（所有项目） | `~/.cursor/mcp.json` |
| **Claude Code**（任意） | `<your-project>/.mcp.json` |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **VS Code** 与 MCP 启用的 Copilot | `<your-project>/.vscode/mcp.json` |
如果文件不存在，请创建它。重启您的 AI 工具。批准信任提示。然后在任何 Node 项目中询问：
```
使用 Flow 设置 Google OAuth 进行开发。
```
AI 调用 Flow 的 MCP 工具（`flow_check` → `flow_setup_oauth`），在您的项目中安装 `flow-vault`，用 `--require=flow-vault` 包装您的开发脚本，并告诉您重启开发服务器。您的应用程序像正常一样读取 `process.env.GOOGLE_CLIENT_ID` — 值来自 Flow 的托管源，而不是任何 `.env` 文件。
### 快速入门 — Claude Code CLI 用户（替代方案）
如果您使用的是独立的 Claude Code CLI（不是 VSCode 扩展），则 `/plugin install` 可用，并且作为奖励提供 SKILL.md 自动触发：
```
/plugin marketplace add vivekschaudhary/flow-mcp
/plugin install flow@flow-marketplace
```
在此之后，AI 会在集成请求时主动调用 Flow，而无需显式的“使用 Flow 来...”短语。
### Cursor / Windsurf 注意事项
这些工具的代理不会读取 Claude Code 的 SKILL.md。MCP 服务器相同，工具工作相同，但 AI 不会自动在纯“设置 Google OAuth”上触发 Flow — 它需要显式的提示 **“使用 Flow 来...”**。之后，服务器本身的工具描述驱动正确的使用。
## 您手动执行的操作（直到 v0.2）
引导步骤要求您在 OS 密钥链中存储一个会话令牌，以便 `flow-vault` 在您的应用程序启动时可以进行身份验证。AI 会在正确的时间告诉您确切的命令；它看起来像这样：
```bash
node -e "require('flow-vault/keychain').storeSession('<install-id>')"
```
v0.2 中的 `flow login` CLI 将用一次性 GitHub 登录取代此操作。
## 组件
- **`packages/flow-vault/`** — 可发布的 npm 运行时预加载。通过 Proxy 包装 `process.env`。与源适配器无关。参见 [packages/flow-vault/README.md](packages/flow-vault/README.md)。
- **`api/mcp.ts`** — 托管的 MCP 服务器。通过 `mcp-handler` 进行可流式 HTTP 传输。
- **`api/vault/credentials.ts`** — 托管源适配器的读取端点。由 `flow-vault` 在配置为使用 `flow-hosted` 源时调用。
- **`src/lib/storage.ts`** — Upstash Redis KV 适配器；保险库和状态帮助程序（仅限托管源）。
- **`src/lib/playbook.ts`** + **`src/playbooks/`** — 剧本引擎和定义。
- **`plugin/`** — Claude Code 插件清单。指向托管的 MCP URL。
## Flow 管理的内容
| 集成 | 提供商 ID | 状态 | 备注 |
|---|---|---|---|
| Google OAuth（网络） | `google-oauth-web` | ✅ 实时（仅限开发） | nextauth/clerk/auth0/custom 库变体；多端口 + 多回调白名单 |
| 电子邮件 | `email_provider` | ✅ 实时（仅限开发） | 目前在底层使用 Resend；从 `onboarding@resend.dev` 测试域发送 |
| AWS S3 | `s3_provider`（计划中） | 计划中（v0.2） | 文件上传 — 从一开始就范围狭窄 |
| 支付 | `payments_provider`（计划中） | 计划中（v0.2） | 可能是 Stripe； webhook 设置是真正的痛点 |
| Auth0 | `auth0`（计划中） | 计划中（v0.2） | 25% 的存储库调查 |
| 实时 | `realtime_provider`（计划中） | 计划中（v0.2） | 可能是 Pusher；16% 的存储库，没有现有的工具 |
| SMS | `sms_provider`（计划中） | 计划中（v0.3+） | 可能是 Twilio |
Flow 仅在与提供商的当前控制台 UI 针对其整个流程验证后才会提供集成。生产凭证接收（`flow_capture`、`flow_setup_provider（production）`）是 v0.2 版本的工作 — 在此之前，所有实时集成仅适用于开发环境。
## 可用的 MCP 工具
| 工具 | 状态 | 目的 |
|---|---|---|
| `flow_status_check` | ✅ 实时 | 连接性探测；返回服务器构建状态 |
| `flow_check` | ✅ 实时 | 项目集成状态；在第一次调用时引导 `install_id` |
| `flow_status` | ✅ 实时 | 详细的项目健康状况 |
| `flow_setup_provider（development）` | ✅ 实时 | 通用 — 接受 `provider="google-oauth-web"` 或 `provider="email_provider"`。在保险库中存储共享的开发凭证，返回运行时安装说明 |
| `flow_setup_oauth（development）` | ✅ 实时（别名） | 向后兼容的别名，用于 `flow_setup_provider（provider="google-oauth-web"）` |
| `flow_setup_provider（production）` | ⏳ 计划中（v0.2） | 今天返回“即将推出” |
| `flow_capture` | ⏳ 计划中（v0.2） | 将从 AI 读取的提供商 JSON 中提取凭证 |
| `flow_sync` | ❌ 已弃用 | 运行时注入使 env-push 过时；Flow 在应用程序启动时提供，无需按环境推送 |
## 信任模型 — 两种凭证
**共享开发凭证**（一个 OAuth 客户端，每个 Flow 用户使用）。仅在 Flow 的托管基础设施上实时可用。仅当 `env=development` 时，由托管源适配器返回。限制为 `openid email profile` 范围。等同于测试模式密钥：任何人都可以滥用，滥用追溯到 Flow 的项目，kill-switch 是轮换 + 新的保险库响应。
**您的生产凭证**（每个租户，真实密钥）。保留在您指向运行时的源适配器中。对于托管源：Flow 将它们存储在其 KV 下，您的 `install + project + "production"`。对于 AWS / Vault / Azure / GCP 源适配器：Flow 绝不会看到值 — 运行时的身份验证使用您的 IAM。无论哪种方式：绝不存储在您的文件系统中，绝不存储在您的 `.env` 中，绝不存储在聊天中。完整的威胁模型在 [packages/flow-vault/SECURITY.md](packages/flow-vault/SECURITY.md) 中。
有关 Flow 持有您的密钥和 Flow 从您操作的存储中注入之间的区别，请参见 [docs/source-adapters.md#why-ownership-matters-in-production](docs/source-adapters.md#why-ownership-matters-in-production)。
## 开发环境与生产环境
| 模式 | 源适配器 | 凭证来源 | 您要执行的操作 |
|---|---|---|---|
| 开发环境 | `flow-hosted` | Flow 的共享开发沙箱 | 无。它们由保险库自动提供。 |
| 生产环境（托管） | `flow-hosted` | 您项目的保险库条目 | AI 引导下的单次控制台访问；Flow 存储并从此提供。 |
| 生产环境（您的存储） | `aws-secrets-manager` / `hashicorp-vault` / `azure-key-vault` / `gcp-secret-manager`（计划中） | 您自己的密钥存储 | 通过现有的 IAM（首选 OIDC）对运行时进行身份验证。Flow 仅注入。 |
## 合规性
Flow 在 `.flow/integrations.json` 中生成每个项目的清单，描述每个项目从哪个源请求哪些密钥 — 无密钥值，仅限结构。该清单提交到您的存储库中，在 PR 中可审查，并且可由机器读取以进行审计。参见 [docs/compliance.md](docs/compliance.md)。
## 路线图
- **v0.1**（现在）：托管源适配器 + flow-vault 运行时实时。Google OAuth + Resend 剧本已准备好。MCP 工具已连接，用于开发。
- **v0.2**：生产凭证接收（`flow_capture`）。第一个非托管源适配器（通过 OIDC 联邦的 AWS 密钥管理器）。Stripe + Auth0 + AWS S3 + Pusher 剧本。用于 `flow login` 的 CLI。
- **v0.3**：HashiCorp Vault、Azure 密钥保管库、GCP 密钥管理器源适配器。Twilio、Resend、SendGrid 剧本。在 `anthropics/claude-plugins-community` 中列出市场。
- **v1**：凭证生命周期（`flow_rotate`、`flow_revoke`、`flow_audit`）。合规性清单工具。微站点。
- **v2+**：代理凭证代理 — 按任务为 AI 代理颁发范围有限的 JIT 凭证，并自动撤销。
## 贡献
一旦模式稳定，欢迎贡献剧本。目前的剧本位于 `src/playbooks/google-oauth-web.json`，并演示了格式：8 个步骤、库变体、阻止警告、常见错误。一旦剧本 v2 模式最终确定，模式参考和贡献指南将位于 `docs/playbooks.md` 中。
一旦适配器接口最终确定，欢迎贡献源适配器。目前，运行时硬编码托管源；抽象层将在 v0.2 中实现。
## 许可证
MIT。
## 联系方式
`vivek@kindtree.us` — 问题、安全、合作伙伴。
