介绍
## Overview
此技能使您能够与 Pulse Editor Vibe Dev Flow API 进行交互，以使用基于云的 AI 编码代理生成、构建和发布 Pulse 应用程序。该 API 使用服务器发送事件 (SSE) 流式传输来提供实时进度更新。
## 为什么使用此技能
此技能为 AI 代理提供了显著的优势：
- **无需本地代码生成**：代理无需在用户机器上本地生成代码，而是可以将代码生成卸载到 Pulse Editor 基于云的 vibe 编码服务。这消除了对本地构建工具、依赖项或开发环境的需求。
- **内置版本控制**：每次应用生成都会自动进行版本控制。代理可以通过指定 `appId` 和 `version` 来更新现有应用，从而无需手动管理版本即可轻松迭代应用。
- **即时部署**：应用在生成后会立即自动构建和发布。无需单独的构建或部署步骤——用户在生成完成后即可获得实时的、可用的应用 URL。
- **并行应用生成**：代理可以通过发出并发 API 调用来同时生成多个应用。这非常适合代理需要搭建多个微服务、创建多个相关应用或为不同目的批量生成应用的场景——所有这些都可以同时进行。
- **无状态与可扩展**：由于所有代码生成都在云端进行，代理保持轻量级，并且可以水平扩展，而无需担心本地资源限制。
## 重要提示：长时间运行的任务
**此 API 调用是一个长时间运行的操作。** Vibe Dev Flow 执行多个步骤，包括工作区创建、AI 代码生成、构建和发布。
- **预期持续时间**：通常为 2-5 分钟，但复杂的应用可能需要更长时间 - **超时阈值**：除非超过 **10 分钟**，否则不要使请求超时 - **SSE 流式传输**：连接在整个过程中保持打开状态。**即使一段时间内未收到 SSE 消息，只要连接保持打开状态，请求就没有停滞或卡住。** 请等待流结束或 10 分钟超时。 - **令牌效率**：代理应在请求正文中使用 `"streamUpdatePolicy": "artifactOnly"`，以仅接收最终工件输出，从而显著减少输入令牌。但是，如果一段时间内没有收到消息，这不会被视为卡住。
## 何时使用此技能
当用户想要执行以下操作时，请使用此技能：
- 根据描述或提示创建新的 Pulse 应用 - 使用新功能更新现有的 Pulse 应用 - 为 Pulse Editor 应用程序生成代码 - 构建和发布 Pulse 应用
## API 身份验证
Pulse Editor API 需要 API 密钥进行身份验证。用户可以通过以下方式获取其 API 密钥：
1. 在 https://pulse-editor.com/ 注册或登录 2. 转到账户设置下的 **developer** 部分 3. 在 https://pulse-editor.com/beta 申请 Beta 访问权限（如需要） 4. 从开发者部分创建并复制 API 密钥
API 密钥应在 `Authorization` 标头中作为 Bearer 令牌传递：
``` Authorization: Bearer your_api_key_here ```
## API 端点
**POST** `https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate`
### 请求标头
| 标头 | 必需 | 描述 | | --------------- | ------ | -------------------------------------- | | `Authorization` | 是 | 包含 Pulse Editor API 密钥的 Bearer 令牌 | | `Content-Type` | 是 | `application/json` | | `Accept` | 是 | `text/event-stream` |
### 请求正文参数
| 参数 | 类型 | 必需 | 描述 | 示例 | | --------- | ------ | ------ | ------------------------------------------------------------------------------------------ | --------------------------------------------- | | `prompt` | string | 是 | 指示 Vibe 编码代理的用户提示 | `"Create a todo app with auth and dark mode"` | | `appName` | string | 否 | 应用的友好显示名称 | `"My Todo App"` | | `appId` | string | 否 | 要更新的现有应用的唯一标识符。如果未提供，将创建一个新应用 | `"my_app_x7k9q2"` | | `version` | string | 否 | 现有应用的版本标识符。如果未提供，默认为最新版本 | `"0.0.1"` | | `streamUpdatePolicy` | string | 否 | 设置为 `"artifactOnly"` 以仅接收最终工件输出（建议代理使用以节省令牌） | `"artifactOnly"` |
### 响应
响应是服务器发送事件 (SSE) 流。每个事件包含一个 JSON 编码的消息。消息由 `\n\n` 分隔。
每个 SSE 消息的格式为：
``` data: <JSON> ```
后跟一个空行。
#### 消息类型
有两种消息类型：
**创建消息** - 流中的新消息：
```json { "messageId": "msg_abc123", "type": "creation", "data": { "type": "text" | "toolCall" | "toolResult" | "artifactOutput", "result": "string content", "error": "error message if any" }, "isFinal": false } ```
**更新消息** - 对现有消息的增量更新：
```json { "messageId": "msg_abc123", "type": "update", "delta": { "result": "additional content to append", "error": "additional error to append" }, "isFinal": true } ```
#### 数据类型
| 类型 | 描述 | | ----------------- | -------------------------------------- | | `text` | 来自代理的文本输出 | | `toolCall` | 代理的工具调用 | | `toolResult` | 工具执行的结果 | | `artifactOutput` | 带有已发布应用信息的最终工件 |
#### 工件输出格式
当生成完成时，`artifactOutput` 消息包含：
```json { "publishedAppLink": "https://pulse-editor.com/app/...", "sourceCodeArchiveLink": "https://...", "appId": "my_app_x7k9q2", "version": "0.0.1" } ```
### 响应状态代码
| 代码 | 描述 | | ---- | -------------------------------------------- | | 200 | 包含进度和最终结果的 SSE 流 | | 400 | 错误的请求 - 参数无效 | | 401 | 未授权 - API 密钥无效或缺失 | | 500 | 服务器错误 |
## 示例用法
### cURL 示例
```bash curl -L 'https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate' \ -H 'Content-Type: application/json' \ -H 'Accept: text/event-stream' \ -H 'Authorization: Bearer your_api_key_here' \ -d '{ "prompt": "Create a todo app with auth and dark mode", "appName": "My Todo App" }' ```
### Python 示例
```python import requests import json url = "https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate" headers = { "Authorization": "Bearer your_api_key_here", "Content-Type": "application/json", "Accept": "text/event-stream" } payload = { "prompt": "Create a todo app with auth and dark mode", "appName": "My Todo App" } response = requests.post(url, json=payload, headers=headers, stream=True) messages = {} # Track messages by messageId buffer = "" for chunk in response.iter_content(chunk_size=None, decode_unicode=True): buffer += chunk # SSE messages end with \n\n while "\n\n" in buffer: part, buffer = buffer.split("\n\n", 1) if not part.startswith("data:"): continue data = json.loads(part.replace("data: ", "", 1)) if data["type"] == "creation": messages[data["messageId"]] = data print(f"New: {data['data'].get('result', '')}") elif data["type"] == "update": msg = messages.get(data["messageId"]) if msg: msg["data"]["result"] = (msg["data"].get("result") or "") + (data["delta"].get("result") or "") msg["isFinal"] = data["isFinal"] # Check for artifact output if data.get("data", {}).get("type") == "artifactOutput" and data.get("isFinal"): result = json.loads(messages[data["messageId"]]["data"]["result"]) print(f"Published: {result.get('publishedAppLink')}") ```
### JavaScript/Node.js 示例
```javascript const response = await fetch( "https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate", { method: "POST", headers: { Authorization: "Bearer your_api_key_here", "Content-Type": "application/json", }, body: JSON.stringify({ prompt: "Create a todo app with auth and dark mode", appName: "My Todo App", }), }, ); const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; const messages = new Map(); while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); // SSE messages end with \n\n const parts = buffer.split("\n\n"); buffer = parts.pop(); // Keep incomplete part in buffer for (const part of parts) { if (!part.startsWith("data:")) continue; const json = part.replace(/^data:\s*/, ""); const message = JSON.parse(json); if (message.type === "creation") { messages.set(message.messageId, message); } else if (message.type === "update") { const msg = messages.get(message.messageId); if (msg) { msg.data.result = (msg.data.result ?? "") + (message.delta.result ?? ""); msg.data.error = (msg.data.error ?? "") + (message.delta.error ?? ""); msg.isFinal = message.isFinal; } } // Check for final artifact output const msg = messages.get(message.messageId); if (msg?.data.type === "artifactOutput" && msg.isFinal) { const result = JSON.parse(msg.data.result); console.log("Published:", result.publishedAppLink); } } } ```
### 更新现有应用
要更新现有应用，请包含 `appId` 并可选择包含 `version`：
```bash curl -L 'https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate' \ -H 'Content-Type: application/json' \ -H 'Accept: text/event-stream' \ -H 'Authorization: Bearer your_api_key_here' \ -d '{ "prompt": "Add a calendar view to display tasks by date", "appName": "My Todo App", "appId": "my_app_x7k9q2", "version": "0.0.1" }' ```
### 更新现有应用
要更新现有应用，请包含 `appId` 并可选择包含 `version`：
```bash curl -L 'https://pulse-editor.com/api/server-function/vibe_dev_flow/latest/generate-code/v2/generate' \ -H 'Content-Type: application/json' \ -H 'Accept: text/event-stream' \ -H 'Authorization: Bearer your_api_key_here' \ -d '{ "prompt": "Add a calendar view to display tasks by date", "appName": "My Todo App", "appId": "my_app_x7k9q2", "version": "0.0.1" }' ```
## 最佳实践
1. **清晰的提示**：提供详细、具体的提示，描述您希望应用执行的操作 2. **正确处理 SSE**：实时处理流式响应以获取进度更新 3. **错误处理**：为 400、401 和 500 响应实施适当的错误处理 4. **API 密钥安全**：切勿硬编码 API 密钥；请使用环境变量或安全存储 5. **版本控制**：更新应用时，请指定版本以确保您在正确的基础上进行构建
## 故障排除
| 问题 | 解决方案 | | ---------------- | --------------------------------------------------- | | 401 Unauthorized | 验证您的 API 密钥是否正确且拥有 Beta 访问权限 | | 没有 SSE 事件 | 确保设置了 `Accept: text/event-stream` 标头 | | 应用未更新 | 验证 `appId` 是否存在以及您是否有权访问它 |
## 包含的示例
此技能在 `examples/` 文件夹中包含一个随时可以运行的 Python 示例：
- **`examples/generate_app.py`** - 完整的 Python 脚本，演示了使用 Vibe Dev Flow API 进行 SSE 流式传输 - **`examples/generate_app.js`** - 完整的 Node.js 脚本，演示了使用 Vibe Dev Flow API 进行 SSE 流式传输
要运行示例 Python 脚本：
```bash # Set your API key export PULSE_EDITOR_API_KEY=your_api_key_here # Linux/Mac set PULSE_EDITOR_API_KEY=your_api_key_here # Windows # Install dependencies pip install requests # Run the script python examples/generate_app.py ```
要运行示例 Node.js 脚本：
```bash # Set your API key export PULSE_EDITOR_API_KEY=your_api_key_here # Linux/Mac set PULSE_EDITOR_API_KEY=your_api_key_here # Windows # Install dependencies npm install node-fetch # Run the script node examples/generate_app.js ```
## 资源
- [Pulse Editor 文档](https://docs.pulse-editor.com/) - [API 参考](https://docs.pulse-editor.com/api-reference) - [获取 API 密钥](https://docs.pulse-editor.com/api-reference/get-pulse-editor-api-key) - [Discord 社区](https://discord.com/invite/s6J54HFxQp) - [GitHub](https://github.com/ClayPulse/pulse-editor)