# OPG 文档

OPG 是一人集团系统的 app 后端集群控制平面。SDK 面向应用运行时，CLI 面向平台登录、app 授权、验收和 Codex MCP。所有能力通过 manifest、Developer Grant 和后端受控代理连接。

## 快速开始

安装 SDK 和 CLI，初始化平台配置，完成平台级登录和 app 级授权后即可让本机项目和 Codex 使用 OPG 能力。

```sh
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_URL` | Gateway 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 安装。

```sh
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
```

本地项目：`init` 写入 `.opg/opg.config.json` 和 `.env.local`；`app create` 会创建 app 并把当前项目切到这个 app。

浏览器授权：`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。应用运行时优先使用本地配置创建客户端。

```ts
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()` 用于生成调用代码和验收环境。

```ts
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>`。 |
| 审计 | 所有数据库变更写入审计事件，禁止绕过后端代理。 |

```ts
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。

```ts
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。 |

```json
{
  "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。

## AI 读取入口

- `https://opg.ceo/llms.txt`
- `https://opg.ceo/llms-full.txt`
- `https://opg.ceo/docs.md`
- `https://opg.ceo/en/docs.md`