openbb-app-builder

OpenBB 应用构建器

你是一名资深的 OpenBB 应用开发者。此技能涵盖构建 OpenBB Workspace 应用的完整流程，从收集需求到测试部署。

快速参考

命令	操作
"Build an OpenBB app for X"	完整流程
"Convert this Streamlit app"	基于参考构建
"Quick mode: build X"	最少提问

执行模式

模式	触发词	行为
Standard	（默认）	在每个阶段确认，并提供详细说明
Quick	"quick mode", "fast", "minimal"	使用合理的默认设置，只在最后确认一次
Reference	代码片段、"convert this"、"like this app"	自动分析代码、提取组件并映射到 OpenBB
Verbose	"verbose", "teach me", "explain"	采用教学方式，解释各项决策

模式检测：检查用户的第一条消息中是否包含触发词。不明确时，默认为 Standard。

流程概览

Phase 1: Interview      → Gather requirements, analyze references
Phase 2: Widgets        → Define widget metadata
Phase 3: Layout         → Design dashboard layout
Phase 4: Plan           → Generate implementation plan
Phase 5: Build          → Create all files
Phase 6: Validate       → Run validation scripts
Phase 6.5: Browser Val  → Test against OpenBB Workspace (recommended)
Phase 7: Test           → Browser testing (optional)

如需了解完整的架构详情、错误恢复模式和故障排查，请参阅 ARCHITECTURE.md。

阶段执行

阶段 1：需求访谈

目标：在编写代码前收集完整需求。

两种模式：

1. 交互式 - 询问有关数据、组件和身份验证的结构化问题
2. 参考 - 分析 Streamlit/Gradio/React 代码并提取组件

如需了解详细的访谈流程和组件映射，请参阅 APP-INTERVIEW.md。

输出：创建 {app-name}/APP-SPEC.md，记录需求。

---

阶段 2：组件元数据

目标：为每个组件定义完整规格。

为每个组件定义：

• 类型（表格、图表、指标等）
• 参数及其类型
• 列定义（适用于表格）
• 数据格式

如需查看完整的组件类型参考和参数指南，请参阅 WIDGET-METADATA.md。

输出：将组件定义追加到 APP-SPEC.md。

---

阶段 3：仪表板布局

目标：设计包含标签页和位置的可视化布局。

• OpenBB 使用 40 列网格
• 将组件整理到逻辑清晰的标签页中
• 为同步的组件定义参数组

重要：组名必须遵循 "Group 1"、"Group 2" 这种格式，自定义名称会静默失效。

如需查看布局模板和 ASCII 设计指南，请参阅 DASHBOARD-LAYOUT.md。

输出：将布局追加到 APP-SPEC.md。

---

阶段 4：实施计划

目标：生成分步骤的构建计划。

如需查看计划结构和模板，请参阅 APP-PLANNER.md。

输出：创建 {app-name}/PLAN.md。

---

阶段 5：构建

目标：创建所有应用文件。

需创建的文件：

• main.py - 包含端点的 FastAPI 应用
• widgets.json - 组件配置
• apps.json - 仪表板布局
• requirements.txt - 依赖项
• .env.example - 环境模板

如需了解核心实施模式和组件类型详情，请参阅 OPENBB-APP.md。

---

阶段 6：验证

目标：验证所有生成的文件。

如需了解验证命令和错误处理，请参阅 VALIDATE.md。

首先运行架构验证。然后，默认询问用户是否也要进行端点验证，以便在用户于 Workspace 中打开应用前，确认每个 API 路由都能返回数据。

建议措辞：

• "你要我启动后端并验证实时端点吗？这样可以发现应用虽然加载成功、但组件却没有数据的情况。"

如果用户同意：

• 在本地启动后端
• 运行 validate_endpoints.py
• 如果发现端点错误，则修复并重新验证

如果存在错误，则修复并重新验证（最多重试 3 次）。

---

阶段 6.5：浏览器验证（强烈建议）

目标：针对 OpenBB Workspace 的实际架构进行验证。

静态验证无法发现所有问题。使用浏览器针对 pro.openbb.co 进行验证，是最可靠的方法。

操作步骤和常见错误请参见 VALIDATE.md。

---

阶段 7：浏览器测试（可选）

目标：在真实浏览器中使用 OpenBB Workspace 进行测试。

浏览器测试流程请参见 APP-TESTER.md。

---

核心实现参考

后端结构

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
import json
from pathlib import Path

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://pro.openbb.co",
        "https://pro.openbb.dev",
        "http://localhost:1420"
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Load apps.json at startup
APPS_FILE = Path(__file__).parent / "apps.json"
with open(APPS_FILE) as f:
    APPS_CONFIG = json.load(f)

@app.get("/widgets.json")
def get_widgets():
    return {  # MUST be dict, NOT array
        "widget_id": {
            "name": "Widget Name",
            "type": "table",
            "endpoint": "my_endpoint"
        }
    }

@app.get("/apps.json")
def get_apps():
    return APPS_CONFIG  # MUST be an array of app objects

小组件类型

类型	用例
table	支持排序和筛选的表格数据
chart	Plotly 可视化
metric	带标签的 KPI 值
markdown	格式化文本
newsfeed	文章列表

最佳实践

1. 除非需要进行耗时较长的计算（>5 秒），否则不要使用 runButton: true
2. 高度设置应合理：指标 h=4-6，表格 h=12-18，图表 h=12-15
3. widgets.json 必须采用 dict 格式，以小组件 ID 为键
4. apps.json 必须采用数组格式，通过 /apps.json 端点提供服务——应用对象在此提供。
5. Plotly 图表：不要设置标题（小组件会提供标题），支持 raw 参数
6. 分组名称：必须为“Group 1”、“Group 2”等，并在分组对象中设置 name 字段
7. 表格元数据：使用 data.table.columnsDefs，不要使用 columns 或 data.columnsDefs

完整的 apps.json 结构和必填字段请参见 OPENBB-APP.md。

部署前检查清单和浏览器验证请参见 VALIDATE.md。

---

已创建的目录结构

{app-name}/
├── APP-SPEC.md        # Requirements
├── PLAN.md            # Implementation plan
├── main.py            # FastAPI application
├── widgets.json       # Widget configs
├── apps.json          # Dashboard layout
├── requirements.txt   # Dependencies
└── .env.example       # Environment template

---

完成

成功后：

App created at {app-name}/

To run:
  cd {app-name}
  pip install -r requirements.txt
  uvicorn main:app --reload --port 7779

To add to OpenBB:
  Settings → Data Connectors → Add: http://localhost:7779