本地项目
`init` 写入 `.opg/opg.config.json` 和 `.env.local`；`app create` 会创建 app 并把当前项目切到这个 app。
SDK / CLI / Codex MCP
把 OPG 后端能力接进应用和 coding agent
OPG 是一人集团系统的 app 后端集群控制平面。SDK 面向应用运行时，CLI 面向平台登录、app 授权、验收和 Codex MCP，所有能力通过 manifest、Developer Grant 和后端受控代理连接。
当前文档覆盖
SDK、CLI、MCP、AI、视频、数据库、平台控制面
Quickstart
快速开始
安装 SDK 和 CLI，初始化平台配置，完成平台级登录和 app 级授权后即可让本机项目和 Codex 使用 OPG 能力。
Shell
npm install opg-sdk
npm install -g @jamba/opg-cli@latest --registry=https://registry.npmjs.org/
opg init --base-url https://your-opg.example.com
opg login
opg app list
opg app create --name "Demo App" --slug demo
opg login --app demo
opg smoke
opg db smoke
opg codex install
授权结果
`opg login` 获取平台 token，用于创建 app 和读取运营数据；`opg login --app demo` 获取 app Developer Grant，用于 SDK、数据库、AI、上传、视频和 MCP。不要提交 `.opg/credentials.json` 或真实 API key。
配置来源
SDK 和 CLI 读取顺序保持适合本机开发与 CI 的组合，不要求把密钥写进 manifest。
OPG_BASE_URLGateway base URL，例如 `https://your-opg.example.com`。
OPG_APP_SLUG当前 app slug，用于拼接 `/:app/v1` app-scoped API。
OPG_API_KEY可选 Developer Grant，推荐 `opg_dev_...`，适合 CI 或非交互环境。
OPG_PLATFORM_TOKEN平台管理员 JWT，仅用于全局控制面操作。
.opg/opg.config.json`opg init` 和 `opg app use` 维护的 base URL、app、profile。
.opg/credentials.json`opg login` 和 `opg login --app` 生成的本机授权凭证。
.env.local本地开发 fallback，可保存 base URL 和 app slug。
CLI 命令
`@jamba/opg-cli` 安装后的命令是 `opg`。CLI 负责平台登录、app 创建和切换、app 级授权、manifest/smoke 验收、数据库工作台、平台控制面和 Codex MCP 安装。
CLI
opg init --base-url https://your-opg.example.com
opg login
opg app list
opg app create --name "Demo App" --slug demo
opg app use demo
opg login --app demo
opg manifest
opg smoke
opg db manifest
opg db smoke
opg db tables
opg db query --sql "SELECT * FROM app_demo__customers ORDER BY created_at DESC" --limit 20
opg db execute --sql "CREATE TABLE app_demo__customers (id uuid PRIMARY KEY DEFAULT gen_random_uuid())" --dry-run true
opg platform apps list
opg platform analytics overview --app-id <app-id> --days 30
opg platform ai-usage logs --app-id <app-id> --days 7
opg platform payments orders --app-id <app-id> --page 1浏览器授权
`login` 是平台授权；`login --app demo` 是 app 级授权，用于 SDK、数据库和 MCP 的 app-scoped 工具。
验收链路
`smoke` 和 `db smoke` 用于验证 manifest、表列表、查询和 dry-run DDL 是否可用。
SDK 客户端
`opg-sdk` 提供 app-scoped runtime client，也提供 platform admin client。应用运行时优先使用本地配置创建客户端。
TypeScript
import {
createOpgClientFromLocalConfig,
createOpgPlatformClient,
} from "opg-sdk";
const opg = await createOpgClientFromLocalConfig();
const manifest = await opg.sdk.manifest();
const models = await opg.ai.models();
const usage = await opg.usage.aiLogs({ limit: 20 });
const platform = createOpgPlatformClient({
baseUrl: process.env.OPG_BASE_URL!,
platformToken: process.env.OPG_PLATFORM_TOKEN!,
});应用能力
这些能力都走 `/:app/v1` app-scoped API。前端和用户项目不直接接触 provider 密钥。
AI Gateway
`opg.ai.models()`、`opg.ai.chat()`、`opg.ai.responses()`、`opg.ai.embeddings()`、`opg.ai.image()`、`opg.ai.speech()`。
Agent
`opg.agents.list()`、`opg.agents.meta(slug)`、`opg.agents.run(slug, input)`、`opg.agents.stream(...)`。
上传
`opg.upload.presignedUrl()`、`imageBuffer()`、`fileBuffer()`。大文件优先使用 presigned URL。
视频任务
`opg.video.generateAsync()` 创建任务，`queryTask()` 查询，`wait(taskId)` 轮询到完成。
用量
`opg.usage.aiLogs()` 读取 AI usage logs，用于调试模型、成本、积分扣减和失败请求。
SDK 合同
`opg.sdk.manifest()`、`openapi()`、`examples()`、`smokeTest()` 用于生成调用代码和验收环境。
AI / Video
const chat = await opg.ai.chat({
model: "gpt-4.1-mini",
messages: [{ role: "user", content: "给我生成一个 onboarding checklist" }],
});
const task = await opg.video.generateAsync({
model: "runninghub-video",
prompt: "A clean product intro video for OPG",
});
const result = await opg.video.wait(String(task.task_id || task.id));数据库工作台
数据库能力是后端代理的 app-scoped workspace，不是直连数据库客户端。SDK 不暴露 `DATABASE_URL`。
命名空间只能操作当前 app 前缀，例如 `app_your_app__customers`。
query只允许 `SELECT` / `WITH`，结果有行数上限。
execute默认 dry-run 并事务回滚；真正应用必须传 `confirm=apply:<app-slug>`。
审计所有数据库变更写入审计事件，禁止绕过后端代理。
Database
const db = await opg.database.manifest();
const rows = await opg.database.query({
sql: `SELECT * FROM ${db.namespace}customers LIMIT 20`,
});
await opg.database.execute({
sql: `CREATE TABLE ${db.namespace}customers (id uuid PRIMARY KEY DEFAULT gen_random_uuid(), email text NOT NULL)`,
dryRun: true,
});平台控制面
平台控制面用于创建 app、管理 runtime settings、存储、短信、邮件、OAuth、AI provider、模型、代理、支付和 app 运营数据。它需要 `OPG_PLATFORM_TOKEN`。
Apps
`platform.apps.list()`、`create()`、`update()`、`stats()`。
Runtime
`platform.runtimeSettings.get()` / `update()` 管理 CORS、域名、调度和集成配置。
Providers
storage、smtp、sms、oauth、payment、proxy、AI source/model 都走平台 client。
App Data
feedbacks、analytics、aiUsage、payments、email、site、redeem、admins。
Platform
const app = await platform.apps.create({
name: "Demo App",
slug: "demo",
});
await platform.runtimeSettings.update({
api_base_url: "https://opg.example.com",
cors_origins: ["https://opg.example.com"],
});
const aiLogs = await platform.apps.aiUsage.logs(String(app.id), { days: 7 });Codex MCP
`opg codex install` 生成本地 MCP 配置。MCP server 通过 `opg mcp` 以 stdio 暴露 OPG 工具，让 coding agent 查询 manifest、调用 AI、运行 Agent、提交视频任务、查看用量和操作数据库 dry-run。
Read-only`opg_database_manifest_get`、`opg_database_query`、`opg_platform_apps_list`。
Execution`opg_database_execute`、`opg_platform_app_create`、`opg_platform_app_feedbacks_list`。
Platform`opg_platform_app_analytics_users`、`opg_platform_app_ai_usage_logs`、`opg_platform_app_payment_orders`。
成本风险AI、视频、Agent 执行可能消耗 token、积分或 provider 额度；数据库 execute 默认 dry-run。
MCP config
{
"mcpServers": {
"opg": {
"command": "opg",
"args": ["mcp"],
"env": {
"OPG_BASE_URL": "https://your-opg.example.com",
"OPG_APP_SLUG": "demo",
"OPG_PLATFORM_TOKEN": "${OPG_PLATFORM_TOKEN}"
}
}
}
}后端合同
SDK、CLI 和 MCP 只依赖 `/sdk/manifest` 暴露的稳定合同。新增能力应先扩 manifest，再扩 SDK 和 MCP。
GET /:app/v1/sdk/manifest
GET /:app/v1/sdk/openapi.json
GET /:app/v1/sdk/examples?target=node|react|codex
POST /:app/v1/sdk/smoke-test
POST /:app/v1/sdk/install-profile
POST /:app/v1/sdk/auth/sessions
POST /:app/v1/sdk/auth/token
GET /:app/v1/sdk/database/manifest
GET /:app/v1/sdk/database/tables
POST /:app/v1/sdk/database/query
POST /:app/v1/sdk/database/execute
安全与性能
密钥边界
Developer Grant 只保存 hash，明文只返回一次。真实 key 不进入 manifest、网页或生成配置。
数据库保护
SQL 有 namespace、语句类型、行数、statement timeout 和 dry-run 保护。
长任务
AI、视频、消息、Webhook、批量同步进入队列，HTTP 请求只创建任务并返回 task id。
可观测性
AI 请求、provider health、usage ledger、审计事件和 request events 作为排障真值。
缓存
manifest 可短缓存 30-300 秒；密钥状态和审计结果不能公开缓存。
上传
大文件使用对象存储 presigned URL，不把视频或大文件 base64 放进 JSON。