# gRPC {/* #grpc */}

首先阅读[通过 API 连接](/docs/zh/connect-api)，创建平台 API 令牌。gRPC-Web 客户端使用 `https://reconstruct.dev`。原生 gRPC 通过 TLS 连接到 `reconstruct.dev:443`，使用由 proto 服务名生成的方法路径。每次调用都需要 `authorization: Bearer <token>` 元数据。

`GetCaptureOptions` 返回支持的类型 ID 和环境；客户端不应维护自己的固定列表。`CatalogPlatform.view` 表示平台类型（`desktop`/`mobile`），`CatalogPlatform.implementation` 表示环境。桌面支持 `web/web-extension/macos/windows/linux`；移动端支持 `web/ios/android`。`captured` 表示存储中的可用性。MCP 使用 `platform`/`environment` 进行相同选择；其页面 `view` 标识已保存的配置。参阅 [MCP 目录](/docs/zh/mcp-tools)。

## 下载契约 {/* #download-the-contract */}

```bash
curl -fsSL https://reconstruct.dev/docs/proto/platform.proto -o platform.proto
```

[面向客户端的契约](https://reconstruct.dev/docs/proto/platform.proto)与服务器契约具有相同的服务、消息和字段编号。它省略了 HTTP 注解，因此生成客户端不需要 Google API 注解 proto 文件。

| RPC | 请求 | 结果 |
|---|---|---|
| `ListCatalogs` | `page_size`，可选的 `page_token` | `catalogs[]`，可选的 `next_page_token` |
| `GetCaptureOptions` | 空请求 | 支持的平台/环境 ID、默认值和请求平台选项；无需身份验证，也不计量用量。 |
| `GetCatalog` | `catalog_id`，可选的 `version` | 元数据、所选 `version`、已发布的 `versions[]`、`screens[]`、平台/语言选项 |
| `GetCatalogInsights` | `catalog_id`，可选的 `locale`、`view`、`implementation`、`section`、`version` | `version`, `technologies[]`, `rendering`, `fonts[]`, `text_styles[]`, `assets[]`, `color_themes[]`, `page_count` |

将 `next_page_token` 作为下次调用的 `page_token`，继续遍历列表。通过 `ListCatalogs` 获取目录 ID。

契约还包含 `GetCatalogFile`（字节和内容类型，可选 `version`）、`CreateRequest`、`ListRequests`、`GetRequest`，以及 [REST 指南](/docs/zh/api/rest)中列出的账户、外观、头像和个人令牌操作。两种 API 均适用相同的账户访问要求。`ListCatalogs` 支持该指南中记录的平台搜索、排序和重复筛选条件。

`WatchCatalogs` 流式传输 `changed` 和 `revision`；传入 `catalog_id` 可监听一个目录，省略则监听列表，重新连接时复用最后的 `revision`。`WatchRequests` 为调用方的请求流式传输失效通知。`changed` 为 true 时刷新对应数据。这些流使用 gRPC/gRPC-Web，且没有 HTTP 注解。

## 生成客户端 {/* #generate-a-client */}

- [Python](/docs/zh/api/grpc/python)
- [C#](/docs/zh/api/grpc/csharp)
- [TypeScript](/docs/zh/api/grpc/typescript)
- [Go](/docs/zh/api/grpc/go)
- [Rust](/docs/zh/api/grpc/rust)
- [Java](/docs/zh/api/grpc/java)
- [C++](/docs/zh/api/grpc/cpp)

## 使用 grpcurl 尝试调用 {/* #try-a-call-with-grpcurl */}

在包含 `platform.proto` 的目录中，设置 `CR_RECONSTRUCT_API_TOKEN` 后运行：

```bash
grpcurl \
  -import-path . -proto platform.proto \
  -H "authorization: Bearer ${CR_RECONSTRUCT_API_TOKEN}" \
  -d '{"pageSize":10}' \
  reconstruct.dev:443 \
  reconstruct.platform.v1.PlatformService/ListCatalogs
```

原生 gRPC 目标应使用主机名和端口，不含 URL 路径。

## 账户用量与计费 {/* #account-usage-and-billing */}

在平台账户设置中管理订阅并查看用量。个人 API 和 MCP 令牌可以访问目录和请求操作；不能用于管理账户计费。

## 标准化界面数据 {/* #normalized-interface-data */}

[Scene 数据格式](/docs/zh/data-format)规定了与平台无关的界面制品，包括状态、资源和证据。当前通过 MCP `get_interface_scene` 获取标准化导出；此目录 API 未定义单独的 Scene 操作。