Document boot-scoped AI provider catalog
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# SaaS↔Dispatcher 项目内实施证据
|
||||
|
||||
> 本文记录当时的实施过程。当前运行期间不再定时轮询任务列表，也不再有 `DiscoveryFollower`；新建任务用 `task.control` 的 `start`、暂停后修改用 `resume` 重读任务配置，不重读 SIP。SIP 仅在启动和 `sip.config` 通知待处理时拉取全量；确认 Agent 已加载且旧呼叫结束后，更新本地任务的 SIP 绑定，不重读任务列表。现行规则以 [`docs/thirds/saas-dispatcher.md`](../thirds/saas-dispatcher.md) 为准。
|
||||
> 本文记录当时的实施过程。当前运行期间不再定时轮询任务列表，也不再有 `DiscoveryFollower`；新建任务用 `task.control` 的 `start`、暂停后修改用 `resume` 重读任务配置，不重读 SIP；启动时读取一次全局 AI 服务商列表，运行中的 start/resume 沿用该快照，变更须重启。SIP 仅在启动和 `sip.config` 通知待处理时拉取全量；确认 Agent 已加载且旧呼叫结束后，更新本地任务的 SIP 绑定，不重读任务列表。现行规则以 [`docs/thirds/saas-dispatcher.md`](../thirds/saas-dispatcher.md) 为准。
|
||||
|
||||
## 改动前基线
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> 本表保留 P08 当时的本地测试结果、来源路径与哈希；后续整理未改写验收事实。原计划现位于 `docs/archive/sources/plan-saas-dispatcher-v05-v0.1.md`，完成阶段计划位于 `docs/archive/plan-saas-dispatcher-completed.md`；**当前唯一规范**见 [`../thirds/saas-dispatcher.md`](../thirds/saas-dispatcher.md)。
|
||||
|
||||
**当前补充（不改写 P08 历史结果）：**现行运行期间不再定时轮询任务列表，删除了 `DiscoveryFollower` 及其两个测试；新建任务的 `start` 和暂停后修改的 `resume` 均重读任务配置，但不重新拉取/核验 SIP；SIP 仅在启动及通知待处理时独立全量读取，Agent 加载核验和本地任务绑定不依赖重读任务列表。`TestStartReadsNewTaskWithoutAgentControl`、`TestResumeRefreshesModifiedTaskRevision`、`TestStartDoesNotReopenPausedOrStoppedTasks` 与隔离 RabbitMQ 的 `TestRuntimeIsolatedControlBacklogExecuteAndSharedResult` 已通过；本次 `PATH=/tmp/sip-go-agent-tools/bin:$PATH make check`（含 Proto 重新生成、隔离 RabbitMQ 测试）、`go test -race ./...`、`go vet ./...` 和构建通过，业务覆盖率 72.1%；此前含隔离 RabbitMQ 的 Dispatcher 测试覆盖率 75.0%（此轮未重算单包覆盖率）。
|
||||
**当前补充（不改写 P08 历史结果）：**现行运行期间不再定时轮询任务列表，删除了 `DiscoveryFollower` 及其两个测试；新建任务的 `start` 和暂停后修改的 `resume` 均重读任务配置，但不重新拉取/核验 SIP；SIP 仅在启动及通知待处理时独立全量读取，Agent 加载核验和本地任务绑定不依赖重读任务列表；全局 AI 服务商列表在 Dispatcher 每次启动时读取一次，start/resume 仅使用该次快照，服务商变更须重启。`TestStartReadsNewTaskWithoutAgentControl`、`TestResumeRefreshesModifiedTaskRevision`、`TestStartDoesNotReopenPausedOrStoppedTasks` 与隔离 RabbitMQ 的 `TestRuntimeIsolatedControlBacklogExecuteAndSharedResult` 已通过；本次 `PATH=/tmp/sip-go-agent-tools/bin:$PATH make check`（含 Proto 重新生成、隔离 RabbitMQ 测试）、`go test -race ./...`、`go vet ./...` 和构建通过，业务覆盖率 72.0%；此前含隔离 RabbitMQ 的 Dispatcher 测试覆盖率 75.0%（此轮未重算单包覆盖率）。
|
||||
|
||||
本记录按 `docs/plan-saas-dispatcher-v05-v0.1.md` §3.1、§6 核对 P01–P08、K01–K16 和 A01–A12。**范围仅限单节点、单 Dispatcher、单 Agent、单 Cell、单租户的隔离 Mock。** 本机证书、RabbitMQ 容器和 OSS/AI 模拟服务不代表 SaaS 应用收讫、供应商验收或真实拨号。原计划是当时的来源事实，不是第二份运行合同；当时的状态入口 `docs/plan-saas-dispatcher.md` 已归档。
|
||||
|
||||
|
||||
@@ -9,12 +9,12 @@
|
||||
| 资源 | 方法和路径 | 应用规则 | 正例 |
|
||||
| --- | --- | --- | --- |
|
||||
| SIP 全量 | `GET /internal/v1/dispatcher/sip` | `revision` 是实际加载版本核对依据；未知 `transport/auth_mode/registration_required/max_concurrent_calls` 为 `null`，不能作为可执行线路默认值；变更时关准入、排空并核验 Agent/Asterisk 实际加载 | [`sip`](../../contracts/local/examples/config-read-sip.json) |
|
||||
| AI provider 全量 | `GET /internal/v1/dispatcher/ai-providers` | `provider_ref` 只标识供应商；将明文 `credential` 原值交给选定角色的 SDK，不引入 ref 查找或交换；缺失、禁用、角色不匹配、无效凭据拒绝执行 | [`providers`](../../contracts/local/examples/config-read-providers.json) |
|
||||
| AI provider 全量 | `GET /internal/v1/dispatcher/ai-providers` | 启动时一次读取全局列表，本进程全部任务共用到下一次重启；运行中 start/resume 不重复拉取，服务商变更须重启后才生效。`provider_ref` 只标识供应商；将明文 `credential` 原值交给选定角色的 SDK，不引入 ref 查找或交换；缺失、禁用、角色不匹配、无效凭据拒绝执行 | [`providers`](../../contracts/local/examples/config-read-providers.json) |
|
||||
| 任务 | `GET /internal/v1/dispatcher/task/{task_id}` | 归属、状态和 `task_revision` 校验后持久绑定同一 `agent`/provider 快照；不可变摘要由本项目计算。同一 revision 内容不同拒绝；ASR-only 只需 ASR，不强制 LLM/TTS；0 和 false 原样保留 | [`ASR-only`](../../contracts/local/examples/config-read-task-asr.json) · [`full AI`](../../contracts/local/examples/config-read-task-full.json) |
|
||||
| 任务列表 | `GET /internal/v1/dispatcher/tasks`，后续 `?after=<cursor>` | 首次/重启完整读到 **带 cursor 且 tasks=[]** 的终止页；非空短页不能提前结束。非空页持久成功后才使用下一 cursor；控制队列积压处理前不开新任务准入。不使用旧 snapshot_id/watermark/mode=snapshot | [`page`](../../contracts/local/examples/task-discovery-page.json) · [`end`](../../contracts/local/examples/task-discovery-end.json) |
|
||||
| 租户额度 | `GET /internal/v1/dispatcher/tenant/{tenant_id}/quota` | `quota_revision` 为业务修订号；未知占用不得算成已释放 | [`quota`](../../contracts/local/examples/config-read-quota.json) |
|
||||
|
||||
HTTP 非 200、正文不合法、缺字段、归属冲突、缓存失效或读取失败时拒绝新的相关准入并记录脱敏错误；已持久接纳的执行继续使用原快照。错误体示例 [`error`](../../contracts/local/examples/config-read-error.json)，不能当成功配置解析。任务仅有运行/暂停/终止；终止是不可逆 stop，同一 `task_id` 不再启用。任务配置只能在暂停或停止后修改；没有 `edit` 事件，也不定时刷新任务列表。启动/重启时完整读取任务列表及独立的全量 SIP；运行中新建任务由 `task.control` 的 `start` 触发读取，人工暂停后修改配置由 `resume` 触发重读（含租户配额），两者沿用已生效的 SIP 快照，不另行读取或向 Agent 核验全量 SIP。HTTP 旧 running 不得覆盖已持久的 pause/stop；resume 经最新任务配置核验后只能解除人工暂停。SIP 无常规定时拉取；`sip.config` 持久关准入并触发 SIP 全量读取，等待已接纳呼叫结束及 Agent 加载核验后，将新 SIP 绑定到本地任务快照（不重读任务列表），然后才可恢复准入。通知待处理时可重试，读取或校验失败不回退旧 SIP，也不开准入。
|
||||
HTTP 非 200、正文不合法、缺字段、归属冲突、缓存失效或读取失败时拒绝新的相关准入并记录脱敏错误；已持久接纳的执行继续使用原快照。错误体示例 [`error`](../../contracts/local/examples/config-read-error.json)，不能当成功配置解析。任务仅有运行/暂停/终止；终止是不可逆 stop，同一 `task_id` 不再启用。任务配置只能在暂停或停止后修改；没有 `edit` 事件，也不定时刷新任务列表。启动/重启时完整读取任务列表及独立的全量 SIP；运行中新建任务由 `task.control` 的 `start` 触发读取，人工暂停后修改配置由 `resume` 触发重读任务和租户配额，两者沿用启动时的 AI 服务商列表和已生效的 SIP 快照，不另行读取或向 Agent 核验全量 SIP。HTTP 旧 running 不得覆盖已持久的 pause/stop；resume 经最新任务配置核验后只能解除人工暂停。SIP 无常规定时拉取；`sip.config` 持久关准入并触发 SIP 全量读取，等待已接纳呼叫结束及 Agent 加载核验后，将新 SIP 绑定到本地任务快照（不重读任务列表），然后才可恢复准入。通知待处理时可重试，读取或校验失败不回退旧 SIP，也不开准入。
|
||||
|
||||
## MQ：固定 v1 传输，唯一事件清单
|
||||
|
||||
@@ -25,7 +25,7 @@ RabbitMQ 是 Topic，**SaaS 独占创建、绑定、退役 exchange/queue，D
|
||||
| 事件 | 方向和处理规则 | 正例 |
|
||||
| --- | --- | --- |
|
||||
| `sip.config` | SaaS→D；`revision` 触发全量重新读取和实际加载核验，不用通知正文代替全量 | [`notification`](../../contracts/local/examples/mq-sip-change.json) |
|
||||
| `task.control` | SaaS→D；start/pause/resume/stop，无控制去重/CAS 字段。start 读取新任务配置及租户配额并持久绑定，无 Agent 控制动作；resume 重读最新配置和额度后解除人工暂停；均沿用已生效 SIP 快照，不重复拉取或核验 SIP；pause/stop 发给 Agent，省略 `active_call_policy` 默认 **hangup**，显式仅 drain/hangup。配置读取、归属或 AI 核验失败时不接纳，SIP 待处理时新呼叫仍关闭；成功操作后才回应用回执，回执不是已完成排空/挂断的证据；stop 同 ID 不可恢复 | [`start`](../../contracts/local/examples/mq-control-start.json) · [`control`](../../contracts/local/examples/mq-control.json) · [`ack`](../../contracts/local/examples/mq-control-ack.json) |
|
||||
| `task.control` | SaaS→D；start/pause/resume/stop，无控制去重/CAS 字段。start 读取新任务配置及租户配额并持久绑定，无 Agent 控制动作；resume 重读最新任务配置和额度后解除人工暂停；均沿用启动时 AI 服务商列表及已生效 SIP 快照，不重复拉取全局服务商或 SIP，也不额外核验 SIP；pause/stop 发给 Agent，省略 `active_call_policy` 默认 **hangup**，显式仅 drain/hangup。配置读取、归属或 AI 核验失败时不接纳，SIP 待处理时新呼叫仍关闭；成功操作后才回应用回执，回执不是已完成排空/挂断的证据；stop 同 ID 不可恢复 | [`start`](../../contracts/local/examples/mq-control-start.json) · [`control`](../../contracts/local/examples/mq-control.json) · [`ack`](../../contracts/local/examples/mq-control-ack.json) |
|
||||
| `call.execute` | SaaS→D 仅 `{task_id,callee}`；一次指令保留独立消息/执行身份，路由/主叫/AI/时限从绑定任务读取。`dispatched` 表示已发出呼叫指令，**不表示接通**；白名单/单号码格式不合规则回 `rejected,reason_code:null,reason_message`、不拨号不发最终结果、不暂停整任务 | [`execute`](../../contracts/local/examples/mq-execute.json) · [`dispatched`](../../contracts/local/examples/mq-execute-ack.json) · [`rejected`](../../contracts/local/examples/mq-execute-rejected.json) |
|
||||
| `call.execute.result` | D→SaaS；按 `task_id` + 原号码关联，每次呼叫仅一份最终结果；不新增外部 call_id/source_command_id；真正终结且录音成功上传、无录音或预期录音生成失败后才发送 | [`uploaded`](../../contracts/local/examples/mq-result-uploaded.json) · [`empty`](../../contracts/local/examples/mq-result-no-recording.json) |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user