官方参考

# 参考目录

OneSay平台的能力、操作、Control API操作、授权、事件、错误码和MCP工具，由平台的注册表生成。

风险等级：R0为公开元数据；R1为经过授权的读取；R2为有限的更改，可能需要确认；R3为破坏性或影响Live环境的更改，始终需要确认。

## 能力

客户端可以发现的能力，以及使用它们的客户端。

| ID | 客户端 |
|---|---|
| `speech.transcription.streaming.v1` | javascript, esp32 |
| `capability.platform.discovery` | javascript, mcp |

## 操作

每项操作的风险等级、所需授权，以及提供该操作的MCP工具。

| ID | 风险 | 授权 | MCP工具 |
|---|---|---|---|
| `room.create` | R2 | `room.create` | `onesay.rooms.create` |
| `room.close` | R2 | `room.close` | `onesay.rooms.close` |
| `task.cancel` | R2 | `task.cancel` | `onesay.tasks.cancel` |
| `application.requirements.read` | R1 | `application.requirements.read` | `onesay.application.requirements.read` |
| `application.requirements.replace` | R2 | `application.manage` | `onesay.application.requirements.replace` |
| `application.compatibility.read` | R1 | `application.compatibility.read` | `onesay.application.compatibility.read` |
| `app.session.create` | R2 | `app.session.create` | `onesay.app.session.create` |
| `app.session.read` | R1 | `app.session.read` | `onesay.app.session.read` |
| `app.session.close` | R2 | `app.session.close` | `onesay.app.session.close` |
| `app.session.revoke` | R3 | `app.session.revoke` | `onesay.app.session.revoke` |
| `app.session.capabilities.read` | R1 | `app.session.capabilities.read` | `onesay.app.session.capabilities.read` |
| `signal.open` | R2 | `source.use`, `signal.audio.publish` | — |
| `delegation.create` | R3 | `delegation.create` | — |
| `delegation.read` | R1 | `delegation.read` | — |
| `delegation.revoke` | R3 | `delegation.revoke` | — |
| `data.sync.scope.enable` | R3 | `data.sync.control` | — |
| `data.sync.scope.disable` | R3 | `data.sync.control` | — |
| `rtc.connection.create` | R2 | `room.join` | — |
| `rtc.connection.read` | R1 | `room.join` | — |
| `rtc.connection.revoke` | R2 | `room.join` | — |
| `rtc.media_key.read` | R1 | `room.join` | — |
| `rtc.publication.create` | R2 | `room.join`, `source.use` | — |
| `rtc.publication.end` | R2 | `room.join` | — |
| `rtc.subscription.update` | R2 | `room.join`, `rtc.subscription.configure` | — |
| `rtc.packet.policy.update` | R2 | `room.join`, `rtc.packet.configure` | — |
| `agent.execution.create` | R2 | `room.join`, `source.use`, `signal.audio.subscribe`, `agent.execution.create` | — |
| `agent.execution.read` | R1 | `agent.execution.read` | — |
| `agent.execution.stop` | R2 | `agent.execution.stop` | — |

## 公开API操作

Control API的全部操作及其所需授权。[API参考](public-api.md)列出了每个操作的请求、响应、示例和错误。

| 操作 | 方法 | 路径 | 授权 |
|---|---|---|---|
| `getCurrentUser` | GET | `/me` | 无（适用身份验证策略） |
| `createOrganization` | POST | `/organizations` | 无（适用身份验证策略） |
| `listOrganizations` | GET | `/organizations` | `organization.read` |
| `getOrganization` | GET | `/organizations/{organization_id}` | `organization.read` |
| `updateOrganization` | PATCH | `/organizations/{organization_id}` | `organization.manage` |
| `listOrganizationMemberships` | GET | `/organizations/{organization_id}/memberships` | `organization.read` |
| `createOrganizationMembership` | POST | `/organizations/{organization_id}/memberships` | `organization.manage` |
| `createProject` | POST | `/projects` | `project.manage` |
| `listProjects` | GET | `/projects` | `project.read` |
| `getProject` | GET | `/projects/{project_id}` | `project.read` |
| `updateProject` | PATCH | `/projects/{project_id}` | `project.manage` |
| `archiveProject` | POST | `/projects/{project_id}/archive` | `project.manage` |
| `listProjectEnvironments` | GET | `/projects/{project_id}/environments` | `project.read` |
| `createApplication` | POST | `/applications` | `application.manage` |
| `listApplications` | GET | `/applications` | `application.read` |
| `getApplication` | GET | `/applications/{application_id}` | `application.read` |
| `updateApplication` | PATCH | `/applications/{application_id}` | `application.manage` |
| `revokeApplication` | POST | `/applications/{application_id}/revoke` | `application.manage` |
| `createCredential` | POST | `/credentials` | `credential.create` |
| `listCredentials` | GET | `/credentials` | `credential.read` |
| `getCredential` | GET | `/credentials/{credential_id}` | `credential.read` |
| `rotateCredential` | POST | `/credentials/{credential_id}/rotate` | `credential.create` |
| `revokeCredential` | POST | `/credentials/{credential_id}/revoke` | `credential.revoke` |
| `createDevice` | POST | `/devices` | `device.create` |
| `listDevices` | GET | `/devices` | `device.read` |
| `getDevice` | GET | `/devices/{device_id}` | `device.read` |
| `updateDevice` | PATCH | `/devices/{device_id}` | `device.update` |
| `publishDeviceCapabilities` | PUT | `/devices/{device_id}/capabilities` | `device.capabilities.publish` |
| `createDeviceProvisioningSession` | POST | `/devices/{device_id}/provisioning-sessions` | `device.update` |
| `exchangeDeviceAccessToken` | POST | `/device-access-tokens` | 无（适用身份验证策略） |
| `exchangeDeviceProvisioningCode` | POST | `/device-provisioning/exchange` | 无（适用身份验证策略） |
| `rotateDeviceCredential` | POST | `/devices/{device_id}/credentials/rotate` | `device.update` |
| `revokeDevice` | POST | `/devices/{device_id}/revoke` | `device.revoke` |
| `createSource` | POST | `/sources` | `source.create` |
| `listSources` | GET | `/sources` | `source.read` |
| `getSource` | GET | `/sources/{source_id}` | `source.read` |
| `createContextSnapshot` | POST | `/context-snapshots` | `context_snapshot.create` |
| `getContextSnapshot` | GET | `/context-snapshots/{context_snapshot_id}` | `context_snapshot.read` |
| `createRoom` | POST | `/rooms` | `room.create` |
| `listRooms` | GET | `/rooms` | `room.read` |
| `getRoom` | GET | `/rooms/{room_id}` | `room.read` |
| `closeRoom` | POST | `/rooms/{room_id}/close` | `room.close` |
| `listRoomParticipants` | GET | `/rooms/{room_id}/participants` | `participant.read` |
| `listRoomSignals` | GET | `/rooms/{room_id}/signals` | `room.read` |
| `createRealtimeConnection` | POST | `/realtime/connections` | `room.join` |
| `resumeRealtimeConnection` | POST | `/realtime/connections/resume` | `room.join` |
| `getRealtimeCapabilities` | GET | `/realtime/capabilities` | `capability.read` |
| `createTask` | POST | `/tasks` | `task.dictation.create` |
| `listTasks` | GET | `/tasks` | `task.read` |
| `getTask` | GET | `/tasks/{task_id}` | `task.read` |
| `cancelTask` | POST | `/tasks/{task_id}/cancel` | `task.cancel` |
| `getUsageSummary` | GET | `/usage/summary` | `usage.read` |
| `listUsageEvents` | GET | `/usage/events` | `usage.read` |
| `listDeveloperLogs` | GET | `/logs` | `logs.read` |
| `getDeveloperLogTimeline` | GET | `/logs/{request_id}` | `logs.read` |
| `listCapabilities` | GET | `/capabilities` | `capability.read` |
| `getCapability` | GET | `/capabilities/{capability_id}` | `capability.read` |
| `listActions` | GET | `/actions` | `capability.read` |
| `getAction` | GET | `/actions/{action_id}` | `capability.read` |
| `getApplicationRequirements` | GET | `/applications/{application_id}/requirements` | `application.requirements.read` |
| `replaceApplicationRequirements` | PUT | `/applications/{application_id}/requirements` | `application.manage` |
| `evaluateApplicationCompatibility` | GET | `/applications/{application_id}/compatibility` | `application.compatibility.read` |
| `createAppSession` | POST | `/app-sessions` | `app.session.create` |
| `getAppSession` | GET | `/app-sessions/{app_session_id}` | `app.session.read` |
| `closeAppSession` | POST | `/app-sessions/{app_session_id}/close` | `app.session.close` |
| `revokeAppSession` | POST | `/app-sessions/{app_session_id}/revoke` | `app.session.revoke` |
| `getAppSessionCapabilities` | GET | `/app-sessions/{app_session_id}/capabilities` | `app.session.capabilities.read` |
| `createConsentRequest` | POST | `/consent-requests` | 无（适用身份验证策略） |
| `getConsentRequest` | GET | `/consent-requests/{consent_request_id}` | 无（适用身份验证策略） |
| `decideConsentRequest` | POST | `/consent-requests/{consent_request_id}/decision` | 无（适用身份验证策略） |
| `createDelegation` | POST | `/delegations` | `delegation.create` |
| `listDelegations` | GET | `/delegations` | `delegation.read` |
| `getDelegation` | GET | `/delegations/{delegation_id}` | `delegation.read` |
| `revokeDelegation` | POST | `/delegations/{delegation_id}/revoke` | `delegation.revoke` |
| `enableDataSyncScope` | POST | `/data-sync/scopes/enable` | `data.sync.control` |
| `disableDataSyncScopeRetainingData` | POST | `/data-sync/scopes/disable-retain` | `data.sync.control` |
| `readDataSyncChanges` | GET | `/data-sync/changes` | `data.sync.read` |
| `createDataSyncSnapshot` | POST | `/data-sync/snapshots` | `data.sync.read` |
| `readDataSyncSnapshot` | GET | `/data-sync/snapshots/{snapshot_id}` | `data.sync.read` |
| `completeDataSyncSnapshot` | POST | `/data-sync/snapshots/{snapshot_id}/complete` | `data.sync.read` |
| `createRTCConnection` | POST | `/rtc/connections` | `room.join` |
| `getRTCConnection` | GET | `/rtc/connections/{connection_id}` | `room.join` |
| `revokeRTCConnection` | POST | `/rtc/connections/{connection_id}/revoke` | `room.join` |
| `getRTCMediaKeys` | GET | `/rtc/connections/{connection_id}/media-keys` | `room.join` |
| `createRTCPublication` | POST | `/rooms/{room_id}/rtc/publications` | `room.join`, `source.use` |
| `endRTCPublication` | POST | `/rooms/{room_id}/rtc/publications/{publication_id}/end` | `room.join` |
| `updateRTCSubscriptions` | PUT | `/rooms/{room_id}/rtc/subscriptions` | `room.join`, `rtc.subscription.configure` |
| `createAgentExecution` | POST | `/rooms/{room_id}/agent-executions` | `room.join`, `source.use`, `signal.audio.subscribe`, `agent.execution.create` |
| `getAgentExecution` | GET | `/rooms/{room_id}/agent-executions/{agent_execution_id}` | `agent.execution.read` |
| `stopAgentExecution` | POST | `/rooms/{room_id}/agent-executions/{agent_execution_id}/stop` | `agent.execution.stop` |
| `updateRTCPacketPolicy` | PUT | `/rooms/{room_id}/rtc/packet-policy` | `room.join`, `rtc.packet.configure` |

## 授权

操作或工具可能要求的权限。

- `organization.read`
- `organization.manage`
- `capability.read`
- `project.read`
- `project.manage`
- `application.read`
- `application.manage`
- `credential.create`
- `credential.read`
- `credential.revoke`
- `device.create`
- `device.read`
- `device.update`
- `device.capabilities.publish`
- `device.revoke`
- `room.read`
- `room.create`
- `room.join`
- `room.close`
- `participant.read`
- `source.create`
- `source.read`
- `source.use`
- `signal.audio.publish`
- `signal.audio.end`
- `task.dictation.create`
- `task.rtc.transcription.create`
- `task.read`
- `task.cancel`
- `context_snapshot.create`
- `context_snapshot.read`
- `artifact.read`
- `artifact.use`
- `artifact.subscribe`
- `logs.read`
- `usage.read`
- `delegation.create`
- `delegation.read`
- `delegation.revoke`
- `application.requirements.read`
- `application.compatibility.read`
- `app.session.create`
- `app.session.read`
- `app.session.close`
- `app.session.revoke`
- `app.session.capabilities.read`
- `data.sync.read`
- `data.sync.write`
- `data.sync.control`
- `data.sync.delete`
- `rtc.subscription.configure`
- `rtc.packet.configure`
- `rtc.packet.send`
- `rtc.packet.receive`
- `signal.audio.subscribe`
- `agent.execution.create`
- `agent.execution.read`
- `agent.execution.stop`
- `rtc.stream.configure`
- `rtc.stream.send`
- `rtc.stream.receive`
- `rtc.rpc.configure`
- `rtc.rpc.call`
- `rtc.rpc.handle`
- `signal.data.publish`
- `signal.data.end`
- `signal.data.subscribe`

## 设备授权上限

设备凭据最多可以获得的授权。

- `device.capabilities.publish`
- `capability.read`
- `room.read`
- `room.join`
- `participant.read`
- `source.read`
- `source.use`
- `signal.audio.publish`
- `signal.audio.end`
- `task.dictation.create`
- `task.read`
- `task.cancel`
- `context_snapshot.read`
- `artifact.read`
- `artifact.subscribe`
- `application.requirements.read`
- `application.compatibility.read`
- `app.session.create`
- `app.session.read`
- `app.session.close`
- `app.session.capabilities.read`

## 实时事件

Realtime WebSocket推送的事件。

- `connection.welcome`
- `connection.resumed`
- `connection.resume_rejected`
- `connection.closing`
- `room.joined`
- `room.left`
- `participant.joined`
- `participant.left`
- `signal.opened`
- `audio.ack`
- `signal.ended`
- `signal.failed`
- `task.created`
- `task.started`
- `artifact.delta`
- `artifact.finalized`
- `task.completed`
- `task.failed`
- `task.cancelled`
- `pong`
- `error`

## 错误码

错误响应中`error.code`的取值。

- `authentication_required`
- `token_invalid`
- `token_expired`
- `token_audience_invalid`
- `credential_revoked`
- `credential_expired`
- `ticket_invalid`
- `ticket_expired`
- `ticket_consumed`
- `grant_missing`
- `resource_owner_mismatch`
- `project_environment_mismatch`
- `principal_suspended`
- `device_revoked`
- `resource_not_found`
- `resource_state_invalid`
- `room_closed`
- `participant_limit_reached`
- `source_not_found`
- `signal_not_found`
- `artifact_not_found`
- `artifact_unavailable`
- `task_input_invalid`
- `task_profile_input_unsupported`
- `task_not_found`
- `idempotency_conflict`
- `protocol_version_unsupported`
- `message_invalid`
- `message_id_conflict`
- `frame_invalid`
- `frame_too_large`
- `audio_format_unsupported`
- `sequence_gap`
- `protocol_sequence_conflict`
- `resume_state_expired`
- `heartbeat_timeout`
- `task_cancelled`
- `task_timeout`
- `no_speech`
- `provider_unavailable`
- `provider_timeout`
- `provider_authentication_failed`
- `provider_rate_limited`
- `provider_invalid_response`
- `quota_exceeded`
- `rate_limited`
- `budget_exceeded`
- `reservation_failed`
- `usage_pipeline_unavailable`
- `mcp_protocol_version_unsupported`
- `mcp_client_capability_missing`
- `mcp_extension_required`
- `mcp_tool_not_found`
- `mcp_tool_not_exposed`
- `mcp_tool_input_invalid`
- `mcp_tool_output_invalid`
- `mcp_resource_not_found`
- `mcp_resource_forbidden`
- `mcp_confirmation_required`
- `mcp_consent_expired`
- `mcp_request_state_invalid`
- `mcp_operation_handle_expired`
- `mcp_audio_transport_unsupported`
- `oauth_resource_invalid`
- `oauth_client_not_allowed`
- `delegation_required`
- `delegation_expired`
- `delegation_revoked`
- `delegation_scope_exceeded`
- `consent_required`
- `consent_denied`
- `consent_request_mismatch`
- `skill_version_incompatible`
- `skill_package_revoked`
- `client_buffer_overflow`
- `client_audio_capture_failed`
- `client_network_unavailable`
- `client_no_memory`
- `resource_busy`
- `application_requirements_missing`
- `application_incompatible`
- `capability_revision_conflict`
- `capability_registry_mismatch`
- `capability_evidence_invalid`
- `capability_authority_unavailable`
- `authority_revision_exhausted`
- `app_session_expired`
- `app_session_revoked`
- `app_session_closed`

## MCP工具

OneSay MCP服务器提供的工具。

- `onesay.capabilities.list`：风险R0；授权：`capability.read`
- `onesay.capabilities.get`：风险R0；授权：`capability.read`
- `onesay.projects.list`：风险R1；授权：`project.read`
- `onesay.projects.get`：风险R1；授权：`project.read`
- `onesay.applications.list`：风险R1；授权：`application.read`
- `onesay.devices.list`：风险R1；授权：`device.read`
- `onesay.devices.get`：风险R1；授权：`device.read`
- `onesay.devices.diagnose`：风险R1；授权：`device.read`, `logs.read`
- `onesay.rooms.create`：风险R2；授权：`room.create`
- `onesay.rooms.get`：风险R1；授权：`room.read`
- `onesay.rooms.close`：风险R2；授权：`room.close`
- `onesay.tasks.get`：风险R1；授权：`task.read`
- `onesay.tasks.cancel`：风险R2；授权：`task.cancel`
- `onesay.logs.search`：风险R1；授权：`logs.read`
- `onesay.logs.timeline`：风险R1；授权：`logs.read`
- `onesay.usage.summary`：风险R1；授权：`usage.read`
- `onesay.quickstarts.get`：风险R0；授权：无