141 lines
14 KiB
Markdown
141 lines
14 KiB
Markdown
# SaaS 页面截图字段与能力盘点
|
||
|
||
> **资料性质：页面调研，非契约、非验收证据。** 本文只整理用户提供的页面截图中可见的字段和操作；原始截图仅供本地参考，不随仓库提交。截图不能证明后端行为、字段传输方式、权限、持久化或线上功能已启用。未看清或无法判断的内容标为待核验。本文不修改或替代现有项目契约。
|
||
>
|
||
> 后续项目自拟的两只读 HTTP 接口字段与返回结构见[字段提案](../contracts/config-read-fields-v0.1-proposal.md)。本文 §7 早期 MQ 配置获取建议已被用户批准的新方向取代；页面观察仍有效，但不是 SaaS 原有 JSON 字段名的证明。
|
||
|
||
## 1. 范围与结论
|
||
|
||
截图覆盖智能体配置与外呼任务的创建、运行数据查看：
|
||
|
||
- 智能体：基础信息、提示词、ASR、LLM、TTS、话后分析。
|
||
- 外呼任务：任务配置、计划时间、线路与重拨设置、任务统计、号码列表、通话记录。
|
||
- 页面同时展示 AI 参数配置和任务运营配置；两者不能据此视为同一配置对象。
|
||
|
||
## 2. 智能体配置
|
||
|
||
| 页面 | 截图可见字段或能力 | 备注 |
|
||
| --- | --- | --- |
|
||
| 基础信息 | 必填智能体名称、描述（界面显示字数计数）；保存草稿、提交；文字/语音/线路测试入口 | 截图显示“已上线、有草稿变更”状态。按钮可见不代表操作已成功；描述字数上限及发布后的版本行为仍应以实际页面核验。 |
|
||
| 提示词 | 提示词编辑器（字数计数、复制/剪切、格式及预览等工具）；独立开场白；挂断触发条件和结束语配置 | 截图中的具体业务提示词不在此复述。准确字段拆分、变量约束和保存后的版本行为待核验。 |
|
||
| ASR | ASR 模型；音频格式选项 PCM/Opus/AAC/OGG/WAV、采样率 8000/16000 Hz、语言选项；中间结果、标点、去语气词等开关；单句时长 | 截图示例为单句最长 20 秒；不能据此推断每种格式都可用于项目链路，也不能说明 SaaS 到 Agent 的传输与预处理方式。 |
|
||
| LLM | 模型和对话模式；温度、Top-P、重复惩罚、Top-K、随机种子等采样参数；思考与流式输出开关 | 参数名称和取值范围需以可访问的实际页面或上游定义复核。 |
|
||
| TTS | 模型、公共/个人音色选择及试听；情绪、语速、音调；MP3/PCM/WAV 输出格式和采样率选项；测试文本与试听入口 | 音色授权、参数范围及运行时是否接受这些设置待核验。 |
|
||
| 话后分析 | 可编辑分析提示词；按 A–F 等级对通话意向分类，并配置各等级判定规则 | 截图体现分析配置，不证明分析结果的消息、存储或下游消费方式。 |
|
||
|
||
## 3. 外呼任务配置
|
||
|
||
创建页将配置分为基础信息、时间、其他设置和高级设置等区域。截图中可见：
|
||
|
||
- **基础信息**：必填任务名称、所属分组、必选 AI 对话模型；拨打顺序为随机/顺序/倒序；并发数；已启用线路选择、每条线路的数量设置及添加/移除线路入口。
|
||
- **时间**：任务开始/结束时间；按周一至周日的小时网格设置一个或多个时段，并有快捷时段按钮；拨打时间间隔开关及 1/3/5/10/30/60/120 秒选项。
|
||
- **其他设置**：自动重呼开关及条件设置入口；结束动作（截图状态分别显示“暂停任务”和“关闭任务”）；黑名单开关及分组选择。
|
||
- **高级设置**：备注输入框；页面提示更多高级功能待开放。
|
||
- **授权提示**：其中一个创建状态提示当前分组没有可用授权线路，并指向线路管理/租户授权相关入口。只能证明该页面会提示线路不可用，不能证明具体授权校验规则。
|
||
|
||
两张创建页截图展示了默认表单和已填写状态。已填写示例中并发数为 5、选择一条线路、拨打间隔为 30 秒；自动重呼显示间隔 1 分钟、最多 3 次、条件 5 项。这些只是截图当时的表单值，不是通用默认值或项目约束。
|
||
|
||
## 4. 任务运行与数据页面
|
||
|
||
### 4.1 任务列表及统计
|
||
|
||
页面呈现任务分组、任务状态、并发/进度类信息，并提供启动、暂停、关闭、编辑或导入等操作入口。任务详情可切换统计、号码、通话记录、运行概览、任务详情和日志等视图。
|
||
|
||
统计页可见话术、线路、开始/结束日期筛选，以及并发、排队待呼叫数和呼叫状态等信息；汇总项包含呼叫成功、拒接、无应答、关机、占线、呼叫失败，另有意向等级/标签、获客成本及运营商等图表。图表中的样例数值属于截图数据，不作为项目容量、成功率或验收结论。
|
||
|
||
### 4.2 号码列表
|
||
|
||
号码页提供按号码、通话状态、归属地/运营商等条件筛选，并展示号码、通话状态与时间、通话时长、客户属性、拨打次数、归属地/运营商和创建时间等信息；截图还显示导入、导出、批量删除等入口。本文不复制截图中的号码或客户样例。
|
||
|
||
### 4.3 通话记录
|
||
|
||
通话记录页提供号码和意向标签等筛选，表格可见号码、公司/联系人、意向标签、模型标签、通话起止时间、时长、备注和操作等列。具体数据权限、录音/文本的查看方式和留存策略无法由截图确认。
|
||
|
||
## 5. 与项目现有 AI 配置契约的关系
|
||
|
||
当前权威 AI 配置 Schema 为 [`contracts/upstream/v1/ai-config.schema.json`](../../contracts/upstream/v1/ai-config.schema.json)，其中 AI 配置对象采用严格字段校验。已定义的核心内容包括：
|
||
|
||
- ASR：供应商引用、模型、语言、中间结果、超时及输入音频编码/采样率/声道/采样宽度。
|
||
- LLM：供应商/凭据引用、模型、温度、最大 token 数和超时。
|
||
- Prompt：提示词文本、允许变量及最大字节数；对话配置另含开场白和对话控制参数。
|
||
- TTS：供应商/凭据引用、模型、音色、语速、超时及编码/采样率/声道。
|
||
|
||
截图可见但不能直接映射为当前 AI Schema 字段的内容包括：LLM 的 Top-P、重复惩罚、Top-K、随机种子、思考/流式开关；TTS 情绪、音调及额外格式选择；话后分析提示词；以及任务的线路、计划时间、重拨、黑名单和运营统计字段。它们可能属于独立任务配置、SaaS 页面专属设置或其他上游契约，需逐项核对权威来源和版本。
|
||
|
||
**不要仅凭截图向严格 Schema 添加字段，也不要把未映射参数塞入 `metadata` 或原始请求字段。** 若确认这些参数需要进入本项目运行配置，应先按现行契约流程确认来源、语义、默认/显式空值、约束和版本，再更新契约与生成物。
|
||
|
||
## 6. 待核验项
|
||
|
||
1. 智能体各页面字段的准确名称、枚举、单位、范围、默认值与必填条件。
|
||
2. AI 配置是否按不可变版本发布；任务引用智能体时绑定哪个版本，以及在途任务如何固定配置。
|
||
3. ASR/TTS 页面格式与项目媒体管线、当前 Schema 编码之间的转换关系。
|
||
4. LLM 高级参数、话后分析及分析结果的上游契约、执行位置和消息/存储路径。
|
||
5. 任务线路分配、并发、拨打窗口、重拨条件及黑名单的实际服务端校验语义。
|
||
6. 截图所见启动、暂停、关闭、导入/导出和测试入口的权限、效果及失败处理。
|
||
7. 号码、通话记录、录音与识别文本的查看权限和留存周期。
|
||
|
||
## 7. Go 外呼能力的 MQ 接入映射建议
|
||
|
||
> **本节是映射建议，不是已批准的新契约。** 按现有契约，不应把整个页面表单序列化成一条 MQ 消息，也不应让浏览器直接连 RabbitMQ。表单由 SaaS 服务端保存；消息只携带执行所需的严格字段和版本引用。
|
||
|
||
### 7.1 推荐消息流
|
||
|
||
1. **发布智能体配置**：SaaS 保存草稿；用户发布时生成不可变 `agent_version_id`。每次编辑不直接推送整份配置，也不覆盖已发布版本。
|
||
2. **投递外呼命令**：每个可执行呼叫使用 `call.execute` 发给目标 Dispatcher/租户的专属 `.in` 路由。命令携带 `agent_version_id`，不内嵌整份 ASR/LLM/TTS 配置。
|
||
3. **按需获取 AI 快照**：Dispatcher 在准入/起拨前如无对应的有效快照，向 SaaS 发布 `ai.config.request`，其 payload 只有 `agent_version_id`；消息头包含请求 ID、目标 Dispatcher、租户、关联 trace 和有效期限。
|
||
4. **返回不可变配置**：SaaS 以 `ai.config.result` 回到同一 Dispatcher/租户的 `.in` 路由；`correlation_id` 对应原请求 `message_id`。成功响应包含 `snapshot` 和 `authorization`，而不是可变的表单草稿。
|
||
5. **校验后交付 Agent**：Dispatcher 校验 Schema、租户/版本、摘要、授权有效期及撤销状态，持久绑定快照后，经现有 Unary gRPC 将执行快照交给 Agent。Agent 不直连 SaaS，也不消费这条 MQ。
|
||
6. **回传执行事实**：Dispatcher 将呼叫状态、结束结果、实时转写、拒绝联系等事件通过 MQ 发回 SaaS；SaaS 用这些事实更新任务详情和统计。`recording.uploaded` 只表示上传事实已通知入队，不代表 SaaS 已完成后续处理。
|
||
|
||
消息方向和路由应沿用现有契约：Dispatcher→SaaS 经 `agent-call.saas.v2` 和 `d.<dispatcher_id>.t.<tenant_key>.out`；SaaS→Dispatcher 经 `agent-call.dispatchers.v2` 和 `d.<dispatcher_id>.t.<tenant_key>.in`。必须精确路由到目标 Dispatcher 与租户，不广播后再靠正文筛选。D→SaaS 发布需使用持久消息、mandatory routing 和 publisher confirm；输入先持久化再 ACK。
|
||
|
||
`ai.config.request` 的示意 payload：
|
||
|
||
```json
|
||
{
|
||
"schema_version": "2.0",
|
||
"message_type": "ai.config.request",
|
||
"message_id": "<request-id>",
|
||
"dispatcher_id": "<dispatcher-uuid-v4>",
|
||
"tenant_id": "<tenant-id>",
|
||
"tenant_key": "<original-tenant-key>",
|
||
"trace_id": "<trace-id>",
|
||
"issued_at": "<RFC3339>",
|
||
"not_after": "<RFC3339>",
|
||
"payload": { "agent_version_id": "<published-version-id>" }
|
||
}
|
||
```
|
||
|
||
这条请求/响应路径已有契约和存储入口，但当前代码文档明确指出**正常运行时尚无调用方发出 `ai.config.request`**；因此它还不是已打通的生产往返链路。现行字段详见[MQ 机器 Schema](../../contracts/upstream/v1/mq.schema.json)；第三方方向/步骤见[事件顺序说明 §4](../thirds/第三方对接事件与请求消费顺序_v0.1.md)。
|
||
|
||
### 7.2 表单字段与现有承载位置
|
||
|
||
| 表单信息 | 现有 MQ/配置承载位置 | 接入说明 |
|
||
| --- | --- | --- |
|
||
| 智能体名称、描述 | SaaS 管理元数据；执行时引用 `agent_version_id` | 不放进每次呼叫消息，除非业务确实要求 Agent 使用这些显示字段。 |
|
||
| 提示词、允许变量、开场白和对话控制 | `ai.config.result` 的 `config.prompt`、`config.conversation` | 单次呼叫的变量值放 `call.execute.payload.variables`，并按快照的 `allowed_variables` 校验。 |
|
||
| ASR 模型、语言、中间结果、输入音频参数、超时 | `config.asr` | 现有格式约束是 `pcm_s16le`、单声道；截图里的 Opus/AAC/OGG/WAV 不能未经适配直接写入。 |
|
||
| LLM 模型、温度、最大 token、超时 | `config.llm` | 截图中的 Top-P、重复惩罚、Top-K、随机种子、思考/流式开关不在当前 Schema 中；先登记契约 GAP，禁止塞进 `metadata` 伪装支持。 |
|
||
| TTS 模型、音色、语速、编码/采样率/声道、超时 | `config.tts` | 现有输出编码为 `pcm_s16le` 或 `pcma`；截图中的情绪、音调及额外格式须先确认 SDK/媒体链路能力和契约字段。 |
|
||
| 话后分析提示词和 A–F 意向规则 | 当前 AI 快照及事件 Schema 未定义对应字段/结果事件 | 暂不发送；先确认分析执行方、输入事实、结果归属和 SaaS 消费契约。 |
|
||
| 任务名、分组、目标号码、智能体版本 | `call.execute` 中的 `task_id`、`task_item_id`、`execution_id`、`callee`、`agent_version_id` 等 | 当前命令是单次呼叫执行数据，不是完整任务表单或批量号码文件；`callee` 保留业务原始号码。 |
|
||
| 线路选择、主叫配置 | `call.execute.payload.route_policy_id`、`caller_profile_id` | 传已批准的策略/配置 ID，不传 SIP 地址、密码、长期凭据或临时 TOKEN。 |
|
||
| 振铃超时、最大通话时长、单次个性化变量 | `ring_timeout_ms`、`max_call_duration_ms`、`variables` | 这三项属于当前 `call.execute` payload；仍须通过对应范围、权限和硬限制校验。 |
|
||
| 任务暂停/恢复/停止 | `task.control` | 使用 `expected_task_revision` 做 CAS；活动呼叫的 drain/hangup 语义不等同于创建表单里的自动重拨或结束选项。 |
|
||
| 拨打时段/顺序/间隔、任务并发、自动重拨、黑名单 | 当前没有一组可直接承载这些表单值的 `call.execute` 字段 | 不能把整组值塞入 `variables` 或未知字段。需先明确由 SaaS 侧筛选/排程，还是另有经批准的 Dispatcher 任务策略契约；任务并发最终不得突破 Dispatcher 配额。固定的 Asia/Shanghai 09:00–20:00 门禁仍须由 Dispatcher/Agent fail-closed 执行。重拨不能用 MQ 重投或 RPC 超时重试代替。 |
|
||
|
||
现行权威结构见[MQ 消息 Schema](../../contracts/upstream/v1/mq.schema.json)、[事件正文](../../contracts/upstream/v1/event-payloads.schema.json)与[AI 配置 Schema](../../contracts/upstream/v1/ai-config.schema.json)；待签收的新读取路径见[第三方顺序说明](../thirds/第三方对接事件与请求消费顺序_v0.1.md)。当前 Schema 拒绝未定义字段；配置引用只传 `provider_ref`/`credential_ref`，不得传真实凭据。
|
||
|
||
### 7.3 本轮建议范围
|
||
|
||
先按现有消息接通两条最小路径：
|
||
|
||
- `call.execute.agent_version_id` → `ai.config.request` → `ai.config.result` → Dispatcher 持久化并绑定不可变快照 → Unary gRPC 交付 Agent。
|
||
- Agent/Dispatcher 执行事实 → 现有 `call.status`、`call.finished`、`transcript.updated`、`contact.opt_out`、`recording.uploaded` 等事件 → SaaS 更新列表、统计和记录页。
|
||
|
||
Top-P 等新增 AI 参数、话后分析结果、任务排程/重拨/黑名单策略均先列为契约缺口；未确认字段归属和责任边界前，不新增 MQ 消息字段、不声称表单已接入外呼能力。
|
||
|
||
## 8. 截图来源
|
||
|
||
页面字段分析以用户提供的智能体和外呼任务截图为参考；原始截图仅保留在本地，不作为仓库附件或第三方接口证据。
|