go-sip/docs/references/saas-page-snapshot-analysis.md

SaaS 页面截图字段与能力盘点

资料性质：页面调研，非契约、非验收证据。 本文只整理用户提供的页面截图中可见的字段和操作；原始截图仅供本地参考，不随仓库提交。截图不能证明后端行为、字段传输方式、权限、持久化或线上功能已启用。未看清或无法判断的内容标为待核验。本文不修改或替代现有项目契约。

后续项目自拟的两只读 HTTP 接口字段与返回结构见字段提案。本文 §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，其中 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：

{
  "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；第三方方向/步骤见事件顺序说明 §4。

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、事件正文与AI 配置 Schema；待签收的新读取路径见第三方顺序说明。当前 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. 截图来源

页面字段分析以用户提供的智能体和外呼任务截图为参考；原始截图仅保留在本地，不作为仓库附件或第三方接口证据。