rogee/go-sip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
643b11b21f7607eb69f77dbcb697dfd1de3a5ed9
go-sip/docs/OpenAPI与MQ字段索引_v0.1.md
T

71 KiB
Raw Blame History

OpenAPI 与 MQ 字段索引 v0.1

本文件为本轮从现有上游文件一次性生成的只读索引，不是第二份可手工维护的 Schema。原始引用和约束原样保留；它描述“文件现在是什么”，不代表已经与正文权威契约一致。 已逐字段和哈希确认：当前MQ的command_type/command_id与event_type/aggregate_*信封已对齐正文。仍待补齐8种事件的payload专属Schema/条件规则；详见《通信与事件数据交互_v0.1.md》。源文件更新须重新导入生成，不得只改索引。

普通构建/运行不读取父目录；P0须建立版本化契约包和可重复生成入口。本轮没有添加Python运行依赖或Go源码。

1. 来源与内容指纹

源文件 版本/方言 SHA-256
ai-config.openapi.yaml OpenAPI 3.1.0 / info 1.0.0 d2f75d8fd2bf76ceb4eef869a838f08dca156938e1f3025d126ce81e436f624a
cell-agent.openapi.yaml OpenAPI 3.1.0 / info 1.0.0 79dc697d7ce16e2a6aa7e350f30dd006dd847afe2cdc0ea29841f9c6d4310c41
executor.openapi.yaml OpenAPI 3.1.0 / info 1.0.0 b24703783df63e044fc0151c5e215430d2294e13937d2a5ceee3c6fee99b0329
saas.openapi.yaml OpenAPI 3.1.0 / info 1.0.0 368c3a7d75ecc74771b88f9bd9fb7131697c69ce695475fc5aaae6099ff889eb
sip-management.openapi.yaml OpenAPI 3.1.0 / info 1.0.0 5006bbb1fb69f7b4a05cbaa5a43f8944e8522172910a41aba61897c9d5e00281
mq.schema.json https://json-schema.org/draft/2020-12/schema 4fbfc39d46fb55ca48b71bc11cafce60e0814182ba4f898973c7c4d7657f912a
ai-config.schema.json https://json-schema.org/draft/2020-12/schema 62d9090adcca619e2bb3a6c5d6aa249c92601fe47b3278e24df82c640987c5db
SaaS交互_OpenAPI与MQ契约规划_v0.1.md 正文 v1.0；接口/状态权威来源 fb6d218fd0c5a7860083806b26757bec56d42a6829ea5b8257878573ed28e957

2. HTTP 操作全集

下列为现有全部5份OpenAPI、42个操作；并非42个操作都由Dispatcher实现。Executor的5个操作映射Dispatcher，SaaS的2个操作由Dispatcher调用，管理平台30个操作仍属于独立管理平台，AI配置2个操作保持独立配置认证域，Cell Agent的3个操作是待适配的既有管理协议，不能静默同时保留两个写入面。

ai-config.openapi.yaml

  • 标题：agent-call immutable AI configuration API
  • 服务器：[{"url":"/"}]
  • 默认安全声明：[]
方法与路径 operationId / 用途 参数 请求 JSON Schema 响应
POST /internal/v1/ai/agent-versions publishAgentVersion [{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/RequestId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionPublishRequest"}}}} {"200":{"description":"Identical immutable content already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionReceipt"}}}},"201":{"description":"Immutable version published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersionReceipt"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Existing version has different content"}}
GET /internal/v1/ai/agent-versions/{agent_version_id} getAgentVersion [{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/RequestId"},{"name":"agent_version_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"}}] null {"200":{"description":"Trusted immutable snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentVersion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Agent version not found"}}

操作级安全覆盖：

[
  [
    "/internal/v1/ai/agent-versions",
    "post",
    [
      {
        "aiConfigPublish": []
      }
    ]
  ],
  [
    "/internal/v1/ai/agent-versions/{agent_version_id}",
    "get",
    [
      {
        "aiConfigRead": []
      }
    ]
  ]
]

cell-agent.openapi.yaml

  • 标题：agent-call Cell Agent API
  • 服务器：[{"url":"https://cell.internal:9443","description":"Cell management network only"}]
  • 默认安全声明：[]
方法与路径 operationId / 用途 参数 请求 JSON Schema 响应
GET /healthz/live live [] null {"200":{"description":"Cell Agent is alive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}
POST /v1/sip/trunks/{trunk_id}/apply applyTrunk [{"$ref":"#/components/parameters/TrunkId"},{"$ref":"#/components/parameters/RequestId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Publication"}}}} {"200":{"description":"Asterisk has loaded the exact snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Revision or expected local snapshot is stale; the Cell never guesses over an unknown baseline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Asterisk rejected the apply or reload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}
GET /v1/sip/trunks/{trunk_id}/state getTrunkState [{"$ref":"#/components/parameters/TrunkId"}] null {"200":{"description":"Durable Cell apply state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/State"}}}},"404":{"$ref":"#/components/responses/NotFound"}}

操作级安全覆盖：

[
  [
    "/v1/sip/trunks/{trunk_id}/apply",
    "post",
    [
      {
        "CellManagementMtls": []
      }
    ]
  ],
  [
    "/v1/sip/trunks/{trunk_id}/state",
    "get",
    [
      {
        "CellManagementMtls": []
      }
    ]
  ]
]

executor.openapi.yaml

  • 标题：agent-call Executor Control API
  • 服务器：[{"url":"https://executor.internal"}]
  • 默认安全声明：[{"bearerAuth":[]}]
方法与路径 operationId / 用途 参数 请求 JSON Schema 响应
POST /internal/v1/outbound/tasks/{task_id}/controls controlTask Persist a pause, resume, or stop barrier [{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TaskId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlRequest"}}}} {"202":{"description":"Reliably persisted, not yet necessarily applied","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlAccepted"}}}},"409":{"$ref":"#/components/responses/Conflict"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}
GET /internal/v1/outbound/commands/{command_id} getCommand [{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/CommandId"}] null {"200":{"description":"Command snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Command"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
GET /internal/v1/outbound/calls/{call_id} getCall [{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/CallId"}] null {"200":{"description":"Call snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
POST /internal/v1/outbound/calls/{call_id}/replays replayCall [{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/CallId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayRequest"}}}} {"202":{"description":"Replay persisted for bounded broker delivery","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/ReplayExpired"}}
POST /internal/v1/outbound/commands/{source_command_id}/replays replayCommand [{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/SourceCommandId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayRequest"}}}} {"202":{"description":"Replay persisted for bounded broker delivery","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/ReplayExpired"}}

saas.openapi.yaml

  • 标题：agent-call SaaS Recording Handoff API
  • 服务器：[{"url":"https://saas.internal"}]
  • 默认安全声明：[{"bearerAuth":[]}]
方法与路径 operationId / 用途 参数 请求 JSON Schema 响应
POST /internal/v1/outbound/recording-uploads createRecordingUpload [{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/IdempotencyKey"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequest"}}}} {"201":{"description":"Upload session created or existing session returned","headers":{"Cache-Control":{"schema":{"const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSession"}}}},"200":{"description":"Existing upload session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSession"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}
POST /internal/v1/outbound/recording-uploads/{upload_id}/complete completeRecordingUpload [{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"upload_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Id"}}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteRequest"}}}} {"200":{"description":"Object independently verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifiedUpload"}}}},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/Expired"},"422":{"$ref":"#/components/responses/Unprocessable"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}

sip-management.openapi.yaml

  • 标题：agent-call Asterisk/SIP Management API
  • 服务器：[{"url":"https://sip-admin.internal","description":"Restricted operator management network"},{"url":"https://sip-read.internal","description":"SaaS read-only service network"}]
  • 默认安全声明：[]
方法与路径 operationId / 用途 参数 请求 JSON Schema 响应
GET /healthz/live live [] null {"200":{"description":"Service is alive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}
GET /admin/v1/providers listProviders [] null {"200":{"description":"Provider directory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}
GET /admin/v1/providers/{provider_id} getProvider [{"$ref":"#/components/parameters/ProviderId"}] null {"200":{"description":"Provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
PUT /admin/v1/providers/{provider_id} upsertProvider [{"$ref":"#/components/parameters/ProviderId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/RequestId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderInput"}}}} {"200":{"description":"Updated provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderResponse"}}}},"201":{"description":"Created provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}
GET /admin/v1/trunks listAdminTrunks [{"$ref":"#/components/parameters/ProviderFilter"},{"$ref":"#/components/parameters/CellIdFilter"},{"$ref":"#/components/parameters/TrunkStatusFilter"}] null {"200":{"description":"All Trunks, including unpublished revisions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminTrunkList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}
GET /admin/v1/trunks/{trunk_id} getAdminTrunk [{"$ref":"#/components/parameters/TrunkId"}] null {"200":{"description":"Trunk configuration and revisions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminTrunk"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
PUT /admin/v1/trunks/{trunk_id} createTrunkRevision [{"$ref":"#/components/parameters/TrunkId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/RequestId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrunkConfig"}}}} {"200":{"description":"New draft revision for an existing Trunk","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminTrunk"}}}},"201":{"description":"New Trunk with its first draft revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminTrunk"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}
POST /admin/v1/trunks/{trunk_id}/validate validateTrunk [{"$ref":"#/components/parameters/TrunkId"}] {"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"revision":{"type":"integer","minimum":1}}}}}} {"200":{"description":"Validation issues, compatible Cells, and impact preview","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
POST /admin/v1/trunks/{trunk_id}/verifications addTrunkVerification [{"$ref":"#/components/parameters/TrunkId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/RequestId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationRequest"}}}} {"200":{"description":"Versioned verification record","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}
POST /admin/v1/trunks/{trunk_id}/publish publishTrunk [{"$ref":"#/components/parameters/TrunkId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/RequestId"}] null {"200":{"description":"Published revision after all selected Cell acknowledgements","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminTrunk"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}
POST /admin/v1/trunks/{trunk_id}/disable disableTrunk [{"$ref":"#/components/parameters/TrunkId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/RequestId"}] null {"200":{"description":"Trunk disabled after selected Cell acknowledgements","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminTrunk"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}
POST /admin/v1/trunks/{trunk_id}/rollback rollbackTrunk [{"$ref":"#/components/parameters/TrunkId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/RequestId"}] {"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["target_revision"],"properties":{"target_revision":{"type":"integer","minimum":1}}}}}} {"200":{"description":"New revision copied from the target after Cell acknowledgements","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminTrunk"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}
GET /admin/v1/trunks/{trunk_id}/publications listTrunkPublications [{"$ref":"#/components/parameters/TrunkId"}] null {"200":{"description":"Per-Cell publication intents","content":{"application/json":{"schema":{"type":"object","required":["mode","publications"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"publications":{"type":"array","items":{"$ref":"#/components/schemas/Publication"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
GET /admin/v1/trunks/{trunk_id}/audit listTrunkAudit [{"$ref":"#/components/parameters/TrunkId"}] null {"200":{"description":"Immutable management audit entries","content":{"application/json":{"schema":{"type":"object","required":["mode","audit"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"audit":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntry"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
GET /admin/v1/cells listCells [] null {"200":{"description":"Registered multi-machine voice Cells","content":{"application/json":{"schema":{"type":"object","required":["mode","cells"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"cells":{"type":"array","items":{"$ref":"#/components/schemas/Cell"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}
GET /admin/v1/cells/{cell_id} getCell [{"$ref":"#/components/parameters/CellId"}] null {"200":{"description":"Registered Cell","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cell"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
PUT /admin/v1/cells/{cell_id} registerCell [{"$ref":"#/components/parameters/CellId"},{"$ref":"#/components/parameters/IfMatch"},{"$ref":"#/components/parameters/RequestId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CellConfig"}}}} {"200":{"description":"Updated Cell revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cell"}}}},"201":{"description":"Registered Cell","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cell"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}
POST /admin/v1/cells/{cell_id}/observations ingestCellObservation [{"$ref":"#/components/parameters/CellId"}] {"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObservationInput"}}}} {"201":{"description":"Observation accepted for the current boot and monotonic sequence","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}
GET /admin/v1/egress-pools listEgressPools [] null {"200":{"description":"Fixed egress pool directory","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}
GET /admin/v1/sip-status getSipStatus [{"$ref":"#/components/parameters/CellIdsFilter"},{"$ref":"#/components/parameters/CellIdFilter"},{"$ref":"#/components/parameters/ProviderFilter"}] null {"200":{"description":"Cell/trunk status matrix with freshness and missing sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}
GET /admin/v1/cells/{cell_id}/sip-status getCellSipStatus [{"$ref":"#/components/parameters/CellId"},{"$ref":"#/components/parameters/TrunkFilter"}] null {"200":{"description":"One Cell status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
GET /admin/v1/providers/{provider_id}/status getProviderStatus [{"$ref":"#/components/parameters/ProviderId"}] null {"200":{"description":"Provider status matrix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
GET /admin/v1/statistics/outbound/summary getOutboundSummary [{"$ref":"#/components/parameters/From"},{"$ref":"#/components/parameters/To"},{"$ref":"#/components/parameters/StatsMode"},{"$ref":"#/components/parameters/ProviderFilter"},{"$ref":"#/components/parameters/TrunkFilter"},{"$ref":"#/components/parameters/CellIdFilter"},{"$ref":"#/components/parameters/EgressFilter"}] null {"200":{"description":"Cohort and interval metrics with completeness metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatisticsSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/BadRequest"}}
GET /admin/v1/statistics/outbound/timeseries getOutboundTimeseries [{"$ref":"#/components/parameters/From"},{"$ref":"#/components/parameters/To"},{"$ref":"#/components/parameters/StatsMode"},{"$ref":"#/components/parameters/Granularity"},{"$ref":"#/components/parameters/ProviderFilter"},{"$ref":"#/components/parameters/TrunkFilter"},{"$ref":"#/components/parameters/CellIdFilter"},{"$ref":"#/components/parameters/EgressFilter"}] null {"200":{"description":"Bounded UTC time series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeseriesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/BadRequest"}}
GET /admin/v1/call-attempts listCallAttempts [{"$ref":"#/components/parameters/From"},{"$ref":"#/components/parameters/To"},{"$ref":"#/components/parameters/StatsMode"},{"$ref":"#/components/parameters/ProviderFilter"},{"$ref":"#/components/parameters/TrunkFilter"},{"$ref":"#/components/parameters/CellIdFilter"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/EgressFilter"}] null {"200":{"description":"Redacted raw attempt facts","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}
GET /admin/v1/call-attempts/{attempt_id} getCallAttempt [{"name":"attempt_id","in":"path","required":true,"schema":{"type":"string"}}] null {"200":{"description":"One redacted attempt fact","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
GET /admin/v1/audit listAudit [{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/ResourceFilter"},{"$ref":"#/components/parameters/RequestFilter"},{"$ref":"#/components/parameters/ActorFilter"}] null {"200":{"description":"Immutable audit entries","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}
GET /admin/v1/operations/{operation_id} getOperation [{"name":"operation_id","in":"path","required":true,"schema":{"type":"string"}}] null {"200":{"description":"Durable operation state for retry/recovery","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}
GET /readonly/v1/sip/trunks listAuthorizedTrunks [] null {"200":{"description":"Published Trunks authorized for this SaaS principal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadonlyTrunkList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}
GET /readonly/v1/sip/trunks/{trunk_id} getAuthorizedTrunk [{"$ref":"#/components/parameters/TrunkId"}] null {"200":{"description":"Published, sanitized Trunk metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadonlyTrunk"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}

操作级安全覆盖：

[
  [
    "/admin/v1/providers",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/providers/{provider_id}",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/providers/{provider_id}",
    "put",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks/{trunk_id}",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks/{trunk_id}",
    "put",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks/{trunk_id}/validate",
    "post",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks/{trunk_id}/verifications",
    "post",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks/{trunk_id}/publish",
    "post",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks/{trunk_id}/disable",
    "post",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks/{trunk_id}/rollback",
    "post",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks/{trunk_id}/publications",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/trunks/{trunk_id}/audit",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/cells",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/cells/{cell_id}",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/cells/{cell_id}",
    "put",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/cells/{cell_id}/observations",
    "post",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/egress-pools",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/sip-status",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/cells/{cell_id}/sip-status",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/providers/{provider_id}/status",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/statistics/outbound/summary",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/statistics/outbound/timeseries",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/call-attempts",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/call-attempts/{attempt_id}",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/audit",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/admin/v1/operations/{operation_id}",
    "get",
    [
      {
        "SipAdminBearer": []
      }
    ]
  ],
  [
    "/readonly/v1/sip/trunks",
    "get",
    [
      {
        "SaasTrunkReadBearer": []
      }
    ]
  ],
  [
    "/readonly/v1/sip/trunks/{trunk_id}",
    "get",
    [
      {
        "SaasTrunkReadBearer": []
      }
    ]
  ]
]

3. OpenAPI 组件字段全集

组件按源文件分域，#/components/... 只指其所属OpenAPI，不能跨文件按同名合并。以下JSON为源YAML组件的等价只读呈现：required、additionalProperties、enum/const、格式、范围、引用及返回错误均保留。未定义的属性约束不能从示例擅自推成必填。

ai-config.openapi.yaml 的 components

parameters

TenantId
{"name":"X-Tenant-Id","in":"header","required":true,"schema":{"type":"string","minLength":1}}
RequestId
{"name":"X-Request-Id","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}

securitySchemes

aiConfigPublish
{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Requires scope ai.config.publish and the AI-config issuer/audience."}
aiConfigRead
{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Requires scope ai.config.read and the AI-config issuer/audience."}

schemas

AgentVersionPublishRequest
{"type":"object","additionalProperties":false,"required":["agent_version_id","config"],"properties":{"agent_version_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"},"config":{"$ref":"ai-config.schema.json"}}}
AgentVersionReceipt
{"type":"object","required":["tenant_id","agent_version_id","status","immutable","content_sha256"],"properties":{"tenant_id":{"type":"string"},"agent_version_id":{"type":"string"},"status":{"enum":["published","reused"]},"immutable":{"const":true},"content_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}
AgentVersion
{"allOf":[{"$ref":"#/components/schemas/AgentVersionReceipt"},{"type":"object","required":["config"],"properties":{"config":{"$ref":"ai-config.schema.json"},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":"string","format":"date-time"},"created_by":{"type":"string"}}}]}
Error
{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}

responses

BadRequest
{"description":"Invalid configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}
Unauthorized
{"description":"Missing or invalid AI-config token"}
Forbidden
{"description":"Token lacks the AI-config permission"}

cell-agent.openapi.yaml 的 components

securitySchemes

CellManagementMtls
{"type":"mutualTLS","description":"Management backend client certificate signed by the Cell CA."}

parameters

TrunkId
{"name":"trunk_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}
RequestId
{"name":"X-Request-ID","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}

schemas

Health
{"type":"object","additionalProperties":false,"required":["status","mode","cell_id"],"properties":{"status":{"type":"string","const":"ok"},"mode":{"type":"string","const":"real"},"cell_id":{"type":"string"}}}
CodecProfile
{"type":"object","additionalProperties":false,"required":["allowed","preferred"],"properties":{"allowed":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["PCMA","PCMU"]}},"preferred":{"type":"string","enum":["PCMA","PCMU"]}}}
SipConfig
{"type":"object","additionalProperties":false,"required":["host","port","transport","auth_mode","register","credential_ref"],"properties":{"host":{"type":"string","minLength":1,"maxLength":253},"port":{"type":"integer","minimum":1,"maximum":65535},"transport":{"type":"string","enum":["udp","tcp","tls"]},"auth_mode":{"type":"string","enum":["ip","digest"]},"register":{"type":"boolean"},"credential_ref":{"type":["string","null"],"description":"Secret-store reference only; plaintext is forbidden."}}}
TrunkConfig
{"type":"object","additionalProperties":false,"required":["provider_id","display_name","enabled","sip","codec_profile","caller_ids","dial_prefix","egress_pool_id","max_concurrency","max_cps"],"properties":{"provider_id":{"type":"string"},"display_name":{"type":"string","minLength":1,"maxLength":256},"enabled":{"type":"boolean"},"sip":{"$ref":"#/components/schemas/SipConfig"},"codec_profile":{"$ref":"#/components/schemas/CodecProfile"},"caller_ids":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":128}},"dial_prefix":{"type":"string","maxLength":32},"egress_pool_id":{"type":"string"},"max_concurrency":{"type":"integer","minimum":1},"max_cps":{"type":"integer","minimum":1}}}
Publication
{"type":"object","additionalProperties":false,"required":["mode","cell_id","trunk_id","revision","expected_local_revision","config","config_sha256"],"properties":{"mode":{"type":"string","const":"real"},"cell_id":{"type":"string"},"trunk_id":{"type":"string"},"revision":{"type":"integer","minimum":1},"expected_local_revision":{"type":"integer","minimum":0},"config":{"$ref":"#/components/schemas/TrunkConfig"},"config_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}
Acknowledgement
{"type":"object","additionalProperties":false,"required":["mode","cell_id","trunk_id","revision","config_sha256","status","idempotent"],"properties":{"mode":{"type":"string","const":"real"},"cell_id":{"type":"string"},"trunk_id":{"type":"string"},"revision":{"type":"integer","minimum":1},"config_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"status":{"type":"string","const":"applied"},"idempotent":{"type":"boolean"}}}
State
{"type":"object","additionalProperties":false,"required":["mode","cell_id","trunk_id","desired_revision","applied_revision","status","updated_at"],"properties":{"mode":{"type":"string","const":"real"},"cell_id":{"type":"string"},"trunk_id":{"type":"string"},"desired_revision":{"type":"integer","minimum":1},"applied_revision":{"type":"integer","minimum":0},"status":{"type":"string","enum":["applying","applied","failed"]},"last_error":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}}}
ErrorResponse
{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}

responses

BadRequest
{"description":"Invalid publication or hash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}
Forbidden
{"description":"Certificate or Cell identity is not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}
NotFound
{"description":"State does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}

executor.openapi.yaml 的 components

securitySchemes

bearerAuth
{"type":"http","scheme":"bearer"}

parameters

TenantId
{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string"}}
RequestId
{"name":"X-Request-ID","in":"header","required":true,"schema":{"type":"string"}}
IdempotencyKey
{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}
TaskId
{"name":"task_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Id"}}
CommandId
{"name":"command_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Id"}}
SourceCommandId
{"name":"source_command_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Id"}}
CallId
{"name":"call_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Id"}}

schemas

Id
{"type":"string","minLength":1,"maxLength":128,"pattern":"^[^\\s/\\\\]+$"}
ControlRequest
{"type":"object","additionalProperties":false,"required":["command_id","action","expected_task_revision","reason"],"properties":{"command_id":{"$ref":"#/components/schemas/Id"},"action":{"type":"string","enum":["pause","resume","stop"]},"expected_task_revision":{"type":"integer","minimum":1},"active_call_policy":{"type":"string","enum":["drain","hangup"]},"reason":{"type":"string","minLength":1,"maxLength":512}}}
ControlAccepted
{"type":"object","required":["command_id","tenant_id","tenant_key","task_id","status","requested_task_revision","accepted_at"],"properties":{"command_id":{"$ref":"#/components/schemas/Id"},"tenant_id":{"type":"string"},"tenant_key":{"type":"string"},"task_id":{"$ref":"#/components/schemas/Id"},"status":{"const":"accepted"},"requested_task_revision":{"type":"integer"},"accepted_at":{"type":"string","format":"date-time"}}}
ReplayRequest
{"type":"object","additionalProperties":false,"required":["command_id","reason"],"properties":{"command_id":{"$ref":"#/components/schemas/Id"},"reason":{"type":"string","minLength":1,"maxLength":512}}}
ReplayAccepted
{"type":"object","required":["command_id","status","snapshot_cutoff"],"properties":{"command_id":{"$ref":"#/components/schemas/Id"},"status":{"const":"accepted"},"snapshot_cutoff":{"type":"string","format":"date-time"}}}
Command
{"type":"object","required":["command_id","command_type","tenant_id","tenant_key","status","aggregate_version"],"properties":{"command_id":{"$ref":"#/components/schemas/Id"},"command_type":{"type":"string"},"tenant_id":{"type":"string"},"tenant_key":{"type":"string"},"task_id":{"type":["string","null"]},"execution_id":{"type":["string","null"]},"call_id":{"type":["string","null"]},"status":{"type":"string"},"reason_code":{"type":["string","null"]},"wait_reason_code":{"type":["string","null"]},"accepted_at":{"type":["string","null"],"format":"date-time"},"waiting_since":{"type":["string","null"],"format":"date-time"},"admission_deadline":{"type":["string","null"],"format":"date-time"},"requested_task_revision":{"type":["integer","null"]},"applied_task_revision":{"type":["integer","null"]},"task_state":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"},"aggregate_version":{"type":"integer","minimum":1}}}
Call
{"type":"object","required":["call_id","execution_id","call_state","call_version","attempts","transcript","recordings","delivery","snapshot_at"],"properties":{"call_id":{"type":"string"},"execution_id":{"type":"string"},"task_id":{"type":"string"},"task_item_id":{"type":"string"},"call_state":{"type":"string"},"call_version":{"type":"integer"},"reason_code":{"type":["string","null"]},"outcome":{"type":["string","null"]},"started_at":{"type":["string","null"],"format":"date-time"},"ended_at":{"type":["string","null"],"format":"date-time"},"duration_ms":{"type":["integer","null"]},"attempts":{"type":"array","items":{"type":"object"}},"transcript":{"type":"object"},"recordings":{"type":"array","items":{"type":"object"}},"delivery":{"type":"object"},"snapshot_at":{"type":"string","format":"date-time"}}}
Problem
{"type":"object","additionalProperties":false,"required":["type","title","status","code","detail","request_id","retryable"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"}}}

responses

Unauthorized
{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}
Forbidden
{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}
NotFound
{"description":"Not found without cross-tenant enumeration","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}
Conflict
{"description":"Idempotency or revision conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}
ReplayExpired
{"description":"Retention window expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}

saas.openapi.yaml 的 components

securitySchemes

bearerAuth
{"type":"http","scheme":"bearer"}

parameters

TenantId
{"name":"X-Tenant-ID","in":"header","required":true,"schema":{"type":"string"}}
RequestId
{"name":"X-Request-ID","in":"header","required":true,"schema":{"type":"string"}}
IdempotencyKey
{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}

schemas

Id
{"type":"string","minLength":1,"maxLength":128,"pattern":"^[^\\s/\\\\]+$"}
UploadRequest
{"type":"object","additionalProperties":false,"required":["recording_id","call_id","content_type","size_bytes","checksum_algorithm","checksum","channels","sample_rate_hz","duration_ms"],"properties":{"recording_id":{"$ref":"#/components/schemas/Id"},"call_id":{"$ref":"#/components/schemas/Id"},"content_type":{"type":"string","const":"audio/wav"},"size_bytes":{"type":"integer","minimum":1},"checksum_algorithm":{"type":"string","const":"SHA-256"},"checksum":{"type":"string","pattern":"^[0-9a-f]{64}$"},"channels":{"type":"integer","const":1},"sample_rate_hz":{"type":"integer","minimum":8000},"duration_ms":{"type":"integer","minimum":1}}}
UploadSession
{"type":"object","required":["upload_id","recording_id","expires_at","upload_method","upload_url","required_headers","constraints"],"properties":{"upload_id":{"$ref":"#/components/schemas/Id"},"recording_id":{"$ref":"#/components/schemas/Id"},"expires_at":{"type":"string","format":"date-time"},"upload_method":{"const":"PUT"},"upload_url":{"type":"string","format":"uri"},"required_headers":{"type":"object"},"constraints":{"type":"object"},"oss_id":{"type":["string","null"]}}}
CompleteRequest
{"type":"object","additionalProperties":false,"required":["recording_id","size_bytes","checksum_algorithm","checksum"],"properties":{"recording_id":{"$ref":"#/components/schemas/Id"},"size_bytes":{"type":"integer","minimum":1},"checksum_algorithm":{"const":"SHA-256"},"checksum":{"type":"string","pattern":"^[0-9a-f]{64}$"},"etag":{"type":["string","null"]}}}
VerifiedUpload
{"type":"object","required":["upload_id","recording_id","status","oss_id","verified_at"],"properties":{"upload_id":{"$ref":"#/components/schemas/Id"},"recording_id":{"$ref":"#/components/schemas/Id"},"status":{"const":"verified"},"oss_id":{"type":"string"},"verified_at":{"type":"string","format":"date-time"}}}
Problem
{"type":"object","required":["type","title","status","code","detail","request_id","retryable"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"}}}

responses

Unauthorized
{"description":"Unauthorized"}
Forbidden
{"description":"Forbidden"}
Conflict
{"description":"Idempotency conflict"}
Expired
{"description":"Upload expired"}
Unprocessable
{"description":"Object failed independent verification"}

sip-management.openapi.yaml 的 components

securitySchemes

SipAdminBearer
{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"Dedicated operator/backend credential for SIP management writes. It is not accepted by the SaaS read-only API or ordinary scheduling API."}
SaasTrunkReadBearer
{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"Dedicated SaaS read-only credential. It cannot publish, modify, disable, rollback, or access Cell management."}

parameters

ProviderId
{"name":"provider_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}
TrunkId
{"name":"trunk_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}
CellId
{"name":"cell_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}
IfMatch
{"name":"If-Match","in":"header","required":true,"description":"Exact latest revision required for CAS; quotes are accepted.","schema":{"type":"integer","minimum":0}}
CellIdsFilter
{"name":"cell_ids","in":"query","required":false,"schema":{"type":"string"}}
CellIdFilter
{"name":"cell_id","in":"query","required":false,"schema":{"type":"string"}}
ProviderFilter
{"name":"provider_id","in":"query","required":false,"schema":{"type":"string"}}
TrunkFilter
{"name":"trunk_id","in":"query","required":false,"schema":{"type":"string"}}
TrunkStatusFilter
{"name":"status","in":"query","required":false,"schema":{"type":"string"}}
ResourceFilter
{"name":"resource_id","in":"query","required":false,"schema":{"type":"string"}}
ActorFilter
{"name":"actor","in":"query","required":false,"schema":{"type":"string"}}
From
{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}
To
{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}
StatsMode
{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["mock","mixed","real"]}}
EgressFilter
{"name":"egress_pool_id","in":"query","required":false,"schema":{"type":"string"}}
Granularity
{"name":"granularity","in":"query","required":false,"schema":{"type":"string","enum":["minute","hour","day"]}}
Limit
{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}
Cursor
{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}
RequestFilter
{"name":"request_id","in":"query","required":false,"schema":{"type":"string"}}
RequestId
{"name":"X-Request-ID","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}}

responses

BadRequest
{"description":"Invalid configuration or request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}
Unauthorized
{"description":"Missing or wrong authentication domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}
Forbidden
{"description":"Credential lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}
Conflict
{"description":"CAS conflict or no compatible Cell","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}
NotFound
{"description":"Resource is not visible or does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}

schemas

Mode
{"type":"string","enum":["mock","real"]}
StatsMode
{"type":"string","enum":["mock","mixed","real"]}
Health
{"type":"object","additionalProperties":false,"required":["status","mode"],"properties":{"status":{"type":"string","const":"ok"},"mode":{"$ref":"#/components/schemas/Mode"}}}
CodecProfile
{"type":"object","additionalProperties":false,"required":["allowed","preferred"],"properties":{"allowed":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["PCMA","PCMU"]}},"preferred":{"type":"string","enum":["PCMA","PCMU"]}}}
SipConfig
{"type":"object","additionalProperties":false,"required":["host","port","transport","auth_mode","register"],"properties":{"host":{"type":"string","minLength":1,"maxLength":253},"port":{"type":"integer","minimum":1,"maximum":65535},"transport":{"type":"string","enum":["udp","tcp","tls"]},"auth_mode":{"type":"string","enum":["ip","digest"]},"register":{"type":"boolean"},"credential_ref":{"type":"string","writeOnly":true,"description":"Secret-store reference only; plaintext credentials are forbidden."}}}
VerificationRequest
{"type":"object","additionalProperties":false,"required":["revision","check_name","result"],"properties":{"revision":{"type":"integer","minimum":1},"check_name":{"type":"string","enum":["transport","registration_auth","caller_id_rules","codec","capacity","whitelist"]},"result":{"type":"string","enum":["confirmed","failed","unknown","not_applicable"]},"evidence_ref":{"type":"string","maxLength":512},"checked_by":{"type":"string","maxLength":128}}}
TrunkConfig
{"type":"object","additionalProperties":false,"required":["provider_id","display_name","enabled","sip","codec_profile","caller_ids","dial_prefix","egress_pool_id","max_concurrency","max_cps"],"properties":{"provider_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"display_name":{"type":"string","minLength":1,"maxLength":256},"enabled":{"type":"boolean"},"sip":{"$ref":"#/components/schemas/SipConfig"},"codec_profile":{"$ref":"#/components/schemas/CodecProfile"},"caller_ids":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":128}},"dial_prefix":{"type":"string","maxLength":32},"egress_pool_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"max_concurrency":{"type":"integer","minimum":1},"max_cps":{"type":"integer","minimum":1}}}
CellConfig
{"type":"object","additionalProperties":false,"required":["egress_pool_id","codec_capabilities","status","max_concurrency"],"properties":{"egress_pool_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"},"codec_capabilities":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["PCMA","PCMU"]}},"status":{"type":"string","enum":["healthy","draining","disabled"]},"max_concurrency":{"type":"integer","minimum":1},"management_url":{"type":"string","format":"uri","pattern":"^https://","description":"mTLS Cell Agent endpoint. Required when mode=real; credentials and query strings are not allowed."}}}
RevisionInfo
{"type":"object","additionalProperties":false,"required":["revision","state","created_at","created_by"],"properties":{"revision":{"type":"integer","minimum":1},"state":{"type":"string","enum":["draft","publishing","published","superseded"]},"config_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":"string"}}}
AdminTrunk
{"type":"object","required":["mode","trunk_id","provider_id","latest_revision","active_revision","active_status","status","compatible_cell_ids","latest","active","versions"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"trunk_id":{"type":"string"},"provider_id":{"type":"string"},"latest_revision":{"type":"integer","minimum":1},"active_revision":{"type":"integer","minimum":0},"active_status":{"type":"string","enum":["draft","published","disabled"]},"status":{"type":"string","enum":["draft","published","disabled"]},"updated_at":{"type":"string","format":"date-time"},"compatible_cell_ids":{"type":"array","items":{"type":"string"}},"latest":{"$ref":"#/components/schemas/TrunkView"},"active":{"$ref":"#/components/schemas/TrunkView"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/RevisionInfo"}}}}
TrunkView
{"allOf":[{"$ref":"#/components/schemas/TrunkConfig"},{"type":"object","properties":{"trunk_id":{"type":"string"},"credential_configured":{"type":"boolean"},"asterisk_allow":{"type":"array","items":{"type":"string","enum":["alaw","ulaw"]}},"config_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}]}
ReadonlyTrunk
{"type":"object","required":["mode","trunk_id","provider_id","revision","status","config"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"trunk_id":{"type":"string"},"provider_id":{"type":"string"},"revision":{"type":"integer","minimum":1},"status":{"type":"string","const":"published"},"updated_at":{"type":"string","format":"date-time"},"config":{"$ref":"#/components/schemas/TrunkView"}}}
AdminTrunkList
{"type":"object","required":["mode","trunks"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"trunks":{"type":"array","items":{"$ref":"#/components/schemas/AdminTrunk"}}}}
ReadonlyTrunkList
{"type":"object","required":["mode","trunks"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"trunks":{"type":"array","items":{"$ref":"#/components/schemas/ReadonlyTrunk"}}}}
Cell
{"type":"object","required":["mode","cell_id","revision","config","updated_at","updated_by"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"cell_id":{"type":"string"},"revision":{"type":"integer","minimum":1},"config":{"$ref":"#/components/schemas/CellConfig"},"cloud_instance_id":{"type":"string"},"instance_name":{"type":"string"},"region":{"type":"string"},"boot_id":{"type":"string"},"updated_at":{"type":"string","format":"date-time"},"updated_by":{"type":"string"}}}
Publication
{"type":"object","required":["trunk_id","revision","cell_id","status","updated_at"],"properties":{"trunk_id":{"type":"string"},"revision":{"type":"integer","minimum":1},"cell_id":{"type":"string"},"status":{"type":"string","enum":["pending","applied","failed"]},"error_code":{"type":["string","null"]},"applied_at":{"type":["string","null"],"format":"date-time"},"target_digest":{"type":"string"},"local_revision":{"type":"integer","minimum":0},"local_digest":{"type":"string"},"operation_id":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}}
AuditEntry
{"type":"object","required":["audit_id","resource_type","resource_id","action","revision","actor","details_json","created_at"],"properties":{"audit_id":{"type":"string"},"resource_type":{"type":"string","const":"trunk"},"resource_id":{"type":"string"},"action":{"type":"string","enum":["upsert","publish","publish_failed","disable","disable_failed","rollback","rollback_failed"]},"revision":{"type":"integer","minimum":0},"actor":{"type":"string"},"request_id":{"type":["string","null"]},"details_json":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}
ProviderInput
{"type":"object","additionalProperties":false,"required":["display_name","lifecycle"],"properties":{"display_name":{"type":"string","minLength":1,"maxLength":256},"notes":{"type":"string","maxLength":2000},"lifecycle":{"type":"string","enum":["active","archived"]}}}
Provider
{"allOf":[{"$ref":"#/components/schemas/ProviderInput"},{"type":"object","required":["provider_id","revision","trunk_count","created_at","updated_at"],"properties":{"provider_id":{"type":"string"},"revision":{"type":"integer","minimum":1},"trunk_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"updated_by":{"type":"string"}}}]}
ProviderList
{"type":"object","required":["mode","providers"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"providers":{"type":"array","items":{"$ref":"#/components/schemas/Provider"}}}}
ProviderResponse
{"type":"object","required":["mode","provider"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"provider":{"$ref":"#/components/schemas/Provider"}}}
ObservationInput
{"type":"object","additionalProperties":false,"required":["cell_id","boot_id","sequence","observed_at","source","states"],"properties":{"observation_id":{"type":"string"},"cell_id":{"type":"string"},"trunk_id":{"type":"string"},"boot_id":{"type":"string","minLength":1},"sequence":{"type":"integer","minimum":1},"observed_at":{"type":"string","format":"date-time"},"source":{"type":"string"},"config_revision":{"type":"integer","minimum":0},"states":{"type":"object"},"occupancy":{"type":"object"},"sample_id":{"type":"string"}}}
StatusItem
{"type":"object","required":["mode","cell_id","availability","complete","missing_sources"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"cell_id":{"type":"string"},"availability":{"type":"string","enum":["healthy","stale","unknown","disabled"]},"complete":{"type":"boolean"},"observed_at":{"type":["string","null"],"format":"date-time"},"received_at":{"type":["string","null"],"format":"date-time"},"observation_age_seconds":{"type":["integer","null"],"minimum":0},"clock_skew":{"type":"boolean"},"reason":{"type":"string"},"boot_id":{"type":"string"},"sequence":{"type":"integer","minimum":1},"config_revision":{"type":"integer","minimum":1},"config_status":{"type":"string"},"egress_pool_id":{"type":"string"},"eligibility":{"type":"string"},"missing_sources":{"type":"array","items":{"type":"string"}},"states":{"type":"object"},"occupancy":{"type":"object"},"trunks":{"type":"array","items":{"type":"object"}},"publication":{"type":"object"}}}
StatusResponse
{"type":"object","required":["mode","complete","cells"],"properties":{"mode":{"$ref":"#/components/schemas/Mode"},"complete":{"type":"boolean"},"generated_at":{"type":"string","format":"date-time"},"data_as_of":{"type":["string","null"],"format":"date-time"},"coverage":{"type":"object"},"cells":{"type":"array","items":{"$ref":"#/components/schemas/StatusItem"}}}}
StatisticsSummary
{"type":"object","required":["mode","from","to","complete","metrics"],"properties":{"mode":{"$ref":"#/components/schemas/StatsMode"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"definition_version":{"type":"string"},"filters":{"type":"object"},"complete":{"type":"boolean"},"missing_sources":{"type":"array","items":{"type":"string"}},"unresolved_count":{"type":"integer","minimum":0},"data_as_of":{"type":["string","null"],"format":"date-time"},"metrics":{"type":"object"},"failure_reasons":{"type":"array","items":{"type":"object"}},"realtime":{"type":"object"}}}
TimeseriesResponse
{"type":"object","required":["mode","from","to","granularity","complete","series"],"properties":{"mode":{"$ref":"#/components/schemas/StatsMode"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string"},"definition_version":{"type":"string"},"filters":{"type":"object"},"granularity":{"type":"string","enum":["minute","hour","day"]},"complete":{"type":"boolean"},"series":{"type":"array","items":{"type":"object"}}}}
ErrorResponse
{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object"},"request_id":{"type":"string"}}}}}

4. 现有 MQ Schema 快照（信封已对齐，事件payload覆盖待补）

以下原件已使用command_type/command_id、event_type与aggregate_*，call.execute required包含task_revision。事件payload仍为通用object，不足以证明每种事件的条件必填/状态语义；需在上游唯一生成源补齐并验收，再冻结发布包。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agent-call.invalid/contracts/mq.schema.json",
  "title": "agent-call MQ command and event envelope",
  "oneOf": [
    {
      "$ref": "#/$defs/executeCommand"
    },
    {
      "$ref": "#/$defs/event"
    }
  ],
  "$defs": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[^\\s/\\\\]+$"
    },
    "tenantKey": {
      "type": "string",
      "minLength": 1
    },
    "time": {
      "type": "string",
      "format": "date-time"
    },
    "executeCommand": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema_version",
        "command_type",
        "command_id",
        "tenant_id",
        "tenant_key",
        "trace_id",
        "issued_at",
        "not_after",
        "payload"
      ],
      "properties": {
        "schema_version": {
          "const": "1.0"
        },
        "command_type": {
          "const": "call.execute"
        },
        "command_id": {
          "$ref": "#/$defs/id"
        },
        "tenant_id": {
          "$ref": "#/$defs/id"
        },
        "tenant_key": {
          "$ref": "#/$defs/tenantKey"
        },
        "trace_id": {
          "$ref": "#/$defs/id"
        },
        "issued_at": {
          "$ref": "#/$defs/time"
        },
        "not_after": {
          "$ref": "#/$defs/time"
        },
        "payload": {
          "$ref": "#/$defs/executePayload"
        }
      }
    },
    "executePayload": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "execution_id",
        "task_id",
        "task_item_id",
        "task_revision",
        "callee",
        "route_policy_id",
        "caller_profile_id",
        "agent_version_id",
        "variables",
        "ring_timeout_ms",
        "max_call_duration_ms"
      ],
      "properties": {
        "execution_id": {
          "$ref": "#/$defs/id"
        },
        "task_id": {
          "$ref": "#/$defs/id"
        },
        "task_item_id": {
          "$ref": "#/$defs/id"
        },
        "task_revision": {
          "type": "integer",
          "minimum": 1
        },
        "callee": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "route_policy_id": {
          "$ref": "#/$defs/id"
        },
        "caller_profile_id": {
          "$ref": "#/$defs/id"
        },
        "agent_version_id": {
          "$ref": "#/$defs/id"
        },
        "variables": {
          "type": "object",
          "additionalProperties": true
        },
        "ring_timeout_ms": {
          "type": "integer",
          "minimum": 1
        },
        "max_call_duration_ms": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "event": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema_version",
        "event_id",
        "event_type",
        "tenant_id",
        "tenant_key",
        "trace_id",
        "occurred_at",
        "aggregate_type",
        "aggregate_id",
        "aggregate_version",
        "payload"
      ],
      "properties": {
        "schema_version": {
          "const": "1.0"
        },
        "event_id": {
          "$ref": "#/$defs/id"
        },
        "event_type": {
          "enum": [
            "command.result",
            "call.status",
            "transcript.updated",
            "call.finished",
            "recording.ready",
            "recording.failed",
            "transcript.failed",
            "contact.opt_out"
          ]
        },
        "tenant_id": {
          "$ref": "#/$defs/id"
        },
        "tenant_key": {
          "$ref": "#/$defs/tenantKey"
        },
        "trace_id": {
          "$ref": "#/$defs/id"
        },
        "occurred_at": {
          "$ref": "#/$defs/time"
        },
        "aggregate_type": {
          "enum": [
            "command",
            "call",
            "transcript_segment",
            "recording"
          ]
        },
        "aggregate_id": {
          "$ref": "#/$defs/id"
        },
        "aggregate_version": {
          "type": "integer",
          "minimum": 1
        },
        "payload": {
          "type": "object"
        }
      }
    }
  }
}

5. AI 配置 JSON Schema 快照

本对象仍属于不可变配置面，不可直接放入call.execute。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agent-call.local/contracts/ai-config.schema.json",
  "title": "Immutable AI agent version",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "agent_version_id",
    "immutable",
    "llm",
    "prompt",
    "tts",
    "asr",
    "conversation"
  ],
  "properties": {
    "agent_version_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
    },
    "immutable": {
      "const": true
    },
    "llm": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "provider_ref",
        "model"
      ],
      "properties": {
        "provider_ref": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "credential_ref": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "model": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "temperature": {
          "type": "number",
          "minimum": 0,
          "maximum": 2
        },
        "max_tokens": {
          "type": "integer",
          "minimum": 1
        },
        "timeout_ms": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "prompt": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "text",
        "allowed_variables"
      ],
      "properties": {
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 32768
        },
        "allowed_variables": {
          "type": "array",
          "maxItems": 32,
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
          }
        },
        "max_bytes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 32768
        }
      }
    },
    "tts": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "provider_ref",
        "model",
        "voice",
        "format"
      ],
      "properties": {
        "provider_ref": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "credential_ref": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "model": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "voice": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "speed": {
          "type": "number",
          "minimum": 0.25,
          "maximum": 3
        },
        "timeout_ms": {
          "type": "integer",
          "minimum": 1
        },
        "format": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "encoding",
            "sample_rate_hz",
            "channels"
          ],
          "properties": {
            "encoding": {
              "enum": [
                "pcm_s16le",
                "pcma"
              ]
            },
            "sample_rate_hz": {
              "type": "integer",
              "minimum": 8000,
              "maximum": 48000
            },
            "channels": {
              "const": 1
            }
          }
        }
      }
    },
    "asr": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "provider_ref",
        "language",
        "input"
      ],
      "properties": {
        "provider_ref": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "credential_ref": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "model": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "language": {
          "type": "string",
          "minLength": 1,
          "maxLength": 32
        },
        "interim": {
          "type": "boolean"
        },
        "timeout_ms": {
          "type": "integer",
          "minimum": 1
        },
        "input": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "encoding",
            "sample_rate_hz",
            "channels",
            "sample_width_bytes"
          ],
          "properties": {
            "encoding": {
              "const": "pcm_s16le"
            },
            "sample_rate_hz": {
              "type": "integer",
              "minimum": 8000,
              "maximum": 48000
            },
            "channels": {
              "const": 1
            },
            "sample_width_bytes": {
              "const": 2
            }
          }
        }
      }
    },
    "conversation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "opening",
        "allow_interrupt",
        "silence_timeout_ms",
        "max_duration_ms",
        "max_turns",
        "sentence_max_chars",
        "max_pending_audio_chunks"
      ],
      "properties": {
        "opening": {
          "type": "string",
          "maxLength": 32768
        },
        "allow_interrupt": {
          "type": "boolean"
        },
        "silence_timeout_ms": {
          "type": "integer",
          "minimum": 1
        },
        "max_duration_ms": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3600000
        },
        "max_turns": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000
        },
        "sentence_max_chars": {
          "type": "integer",
          "minimum": 1
        },
        "max_pending_audio_chunks": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true
    }
  }
}

6. 生成与差异处理

  • 本次索引覆盖42个HTTP操作及上述组件原始约束；没有新增、修复或覆盖父项目契约文件。
  • 文本归档授权、SaaS全局OSS配置同步、管理平台到Dispatcher发布适配及内部gRPC均不能假称已由这些OpenAPI定义；详见交互文档的GAP清单。
  • 对齐后更新源版本/哈希及索引，校验所有引用和黄金请求/事件；任何残留漂移阻塞类型生成和P0冻结。
  • 以下文档才给出跨角色交互与事件语义：通信与事件数据交互。
Reference in New Issue View Git Blame Copy Permalink