两条只读配置接口：任务、智能体、SIP 字段与返回结构 v0.1（项目提案）

状态：项目自定义草案，非 SaaS 已有接口/实际 JSON、非已发布契约、非实现/验收。 用户同意：截图可见的业务含义先映射为项目定义的字段名；截图没有但需求明确的结构由本项目设计。即使字段名与现有项目 Schema 或历史 OpenAPI 相同，也不能据此声称它是当前 SaaS 页面原有的后端键。SaaS 和 management 在 W01 签收前不得据此开始真实配置发布/拨号。

1. 来源、交付边界

P = 页面观察：SaaS 截图分析 §2–4；只证明表单/列表可见，尤其§7的 MQ 配置建议是已被新 HTTP 方向取代的历史方案，不作为新合同。
C = 本项目现有合同：AI 配置、静态 Cell/SIP 制品及当前 MQ 消息。字段语义可复用，但不是 SaaS 当前 HTTP 响应证据。旧 OpenAPI/MQ 只读索引也仅为历史参考。
**N = 新项目字段：**任务每周多时段/排除日期、SIP 线路时段、任务与单 D 绑定、缓存/版本/错误返回等，由本提案定义；实际 SaaS 接口不存在已验证响应。

交付物：机器可读响应草案、mock SIP 成功示例、mock 任务成功示例。两条接口均为 SaaS→Dispatcher 的只读 HTTP 配置读取；MQ 继续单独承担呼叫、控制、查询、上传事实与业务结果，不留旧 AI/SIP 配置 MQ 回退。接口路径、UUID+SECRETKEY 承载位置、错误码的准确枚举、哈希计算规范及 SaaS/management 实际来源仍需 W01 冻结，本文件不冒充外部权威发布物。

2. 请求与共同响应

Dispatcher 使用其全局唯一 UUID和部署受控的 SECRETKEY，仅查询自己管理的资源分区和归属任务；不记录完整密钥或返回配置中的提示词。接口只读、无启动/停止/修改副作用。准确 URL、请求参数/头、SaaS 对任务归属的核验、密钥轮换时序由双方签收；本文仅固化响应的项目字段草案，不推测 SaaS 已有 API 路径。

请求	`200` 返回类型	何时读取	`304` 与错误
SIP 全量配置	`resource=sip_config`，一个 D 资源分区的已批准完整快照	新 D/重启先取齐并核对 Agent/Asterisk 精确加载；运行中约每 60 秒核对版本	未变且仍获批准可 `304`（空响应体）；读取错误/到期停止新执行准入，旧活动通话依原快照排空
单任务配置（内含智能体）	`resource=task_config`，归属 D 的单任务有效配置和已授权智能体快照	有待接纳呼叫时获取，活跃任务缓存约 60 秒、到期主动复核，不逐呼下载整份配置	未变且授权仍有效可 `304`；失败/过期不以旧缓存放行新执行；已接纳执行仍用原快照

200 响应中的 schema_version 固定 config-read.v0.1，resource 区分两种结构，dispatcher_id 必须等于请求 D；HTTP ETag 标识完整有效决策，并非某个 UI 表单的草稿版本。If-None-Match 命中时 304 没有 JSON 响应体；只有此前的批准状态、任务归属及 AI 授权仍足以覆盖下一次缓存有效期，才可延长本地缓存，否则返回 200 新快照或明确失败。SaaS 实际更新到 D 允许最多约 60 秒延迟；一旦缓存到期且刷新失败，不可无限期沿用旧版本发起新呼叫。MQ 停/暂停、opt-out 不等这 60 秒。已接纳/已接通呼叫固定自己的快照，不因本地配置缓存过期而变更。

非 200/304 返回 resource=error、error.code、error.message 的脱敏 JSON（HTTP 状态及 code 逐项待 SaaS 确认）；不得将错误吞成旧配置/空任务。原始 call.execute 的 task_revision、agent_version_id、route_policy_id 与后续新版本可能不同；如何让未接纳执行合法采用新版本、变更与接纳并发时何时冻结版本，尚需版本化 MQ/HTTP 合同约定，不可静默改写原命令。

3. 任务成功响应：字段与来源

响应中的英文键全部是本项目提议的返回键，不是从截图抓到的 SaaS JSON。P/C/N 只说明其业务含义的依据：

返回位置	类型 / 是否必有	含义及来源
`dispatcher_id`, `tenant_key`, `task_id`, `task_revision`	UUID v4、原值字符串、字符串、正整数；必有	C：当前命令及每 D/租户身份；N：任务固定归属一个 D，SaaS 必须持久保存 `(tenant_key,task_id)→dispatcher_id`；不得跨 D 投递。`tenant_key` 需另验证 ≤196 UTF-8 字节及路由段边界，Schema 的字符数不是字节数。
`status`	`running/paused/stopped/finished`；必有	P：页面可见启停状态；N：面向 D 的状态枚举是本项目暂定，不承诺与页面/实际 API 状态值同名。停/暂停需配合 MQ 控制屏障，不能只靠缓存。
`name`, `group_id`	非空字符串、字符串或 `null`；必有	P：任务名称/所属分组。显示信息不参与拨号许可；`null` 与空字符串不混同。
`max_concurrent_calls`	正整数；必有	P：任务并发。仅限制该任务，另须服从 D 的租户份额、供应商、Cell 和 AI 配额。截图里的“5”是某次输入，不是默认值。
`route_policy_id`, `allowed_trunk_ids[]`	非空字符串、至少一条线路 ID；必有	C：`route_policy_id` 已在命令；P：选择启用线路。N：`allowed_trunk_ids` 是本项目定义的白名单，须与已加载 SIP 制品的 `trunk_id` 对齐；不能把任务页面“每条线路数量”直接猜成运营商并发上限。
`schedule.time_zone`, `starts_at`, `ends_at`	固定 `Asia/Shanghai`、带偏移时间或 `null`；必有	P：任务起止时间；N：三字段格式/无值约定。时间约束与星期段、排除日期、线路时段同时成立。
`schedule.weekly_windows`	七个星期键各为可空的时间段数组；必有	P：周一至周日网格、同日多个时段；N：`{start,end}` 用 `HH:MM`，左闭右开，`start < end`，跨午夜拆到次日，不假定 UI 已有这个 JSON 结构。空数组=当天不可呼。
`schedule.excluded_dates[]`	不重复的 `YYYY-MM-DD` 数组；必有，可为空	N：用户新增的可选多日期排除（截图没有此字段）。日期按 Asia/Shanghai 判断并优先于星期段；真实日期、时段排序/重叠与边界须在业务校验中处理。
`agent.agent_version_id`, `content_sha256`, `config`	ID、64位小写 hex、严格 AI 对象；必有	P：任务选择 AI 模型/智能体；C：现有不可变 `agent_version_id`、`content_sha256` 和AI Schema。`config` 原样遵守该现有 Schema，不把截图未覆盖参数偷塞 `metadata`。
`agent.authorization_id`, `authorization_expires_at`	非空 ID、带偏移时间；必有	C：当前 MQ AI 授权含关联 ID 和有效期；N：嵌入任务 HTTP 响应的承载位置新设计，过期不可新接纳。

agent.config 当前可承载的运行字段：mode；ASR 的 provider_ref/model/language/interim/input/timeout_ms；LLM 的 provider_ref/credential_ref/model/temperature/max_tokens/timeout_ms；prompt.text/allowed_variables/max_bytes；TTS 的 provider_ref/credential_ref/model/voice/speed/format/timeout_ms；conversation.opening/allow_interrupt/silence_timeout_ms/max_duration_ms/max_turns/sentence_max_chars/max_pending_audio_chunks 等以现有 AI Schema 本身为准。asr_only 与 full_ai 两种模式均须按 Schema/SDK 能力分别校验；提示词不得出现在示例或日志中的真实用户文本。agent.agent_version_id 必须等于 agent.config.agent_version_id；content_sha256 的摘要生成规范/与现有 AI 授权摘要对齐前不可声称验签通过。

3.1 页面观察但不作为 D 运行字段

原页面可见项	归属判断 / 暂不返回原因
智能体名称/描述、草稿/提交、文字/语音/线路测试	SaaS 管理页面元数据/测试入口，不能代替 `agent_version_id` 的已发布运行快照。
提示词编辑器工具、独立开场白、挂断触发/结束语	`prompt.text` 与 `conversation.opening` 可映射当前合同；挂断条件与结束语尚无当前严格 AI 字段，不能猜到通话控制里。
ASR 页面 PCM/Opus/AAC/OGG/WAV、标点、去语气词、单句时长	当前合同支持的输入为 `pcm_s16le` 等已定义值；其它编码及三个开关/时长需先验证媒体和 SDK，并修订 GAP-09/新合同。
LLM 对话模式、Top-P、重复惩罚、Top-K、随机种子、思考/流式开关	模型/温度等已有字段可用；其余没有获批准的运行字段及参数能力 PoC，不进入 HTTP 的 `agent.config`，不静默忽略后宣称已生效。
TTS 公共/个人音色、情绪、音调、MP3/WAV 选项、试听	已有 `voice/speed/format` 可按实际能力承载；其它参数和试听不直接映射现有 Agent 可执行配置。
话后分析提示词及 A–F 意向规则	页面可见但当前 AI 快照没有对应执行和结果契约；仍由 SaaS 负责或另行定义，不能伪装成外呼 Agent 参数。
任务拨打顺序/时间间隔、自动重呼及次数/条件、结束动作、黑名单组、备注	P：页面有这些项；本接口只返回 D 当前已获授权且有实现责任的准入信息。排序、间隔、名单/运营策略应由 SaaS 明确负责；自动重呼不得伪装成 MQ 重投或 D 的自动再拨。
导入号码、号码列表、统计、通话记录、意向图表	属单次 `call.execute`/SaaS 展示与运营事实，不能一次塞进“任务配置”返回；不能从截图冻结数据页的 API 列名和返回结构。

这些字段已在字段盘点中固化存在性和缺口，不是声称 SaaS 已有相应返回键。若用户明确要求其中某项由 D/Agent 执行，先核实上游模型/SDK、增加获批准的严格字段及正反例，不在新接口中以 metadata 或 raw JSON 穿透。

4. SIP 成功响应：字段与来源

返回位置	类型 / 是否必有	含义及来源
`dispatcher_id`, `revision`, `approved_at`, `snapshot_sha256`	UUID v4、正整数、带偏移时间、64位小写 hex；必有	N：SaaS 只读分发给指定 D 的完整获批版本；`snapshot_sha256` 意图覆盖 HTTP SIP 全量，包括线路补充信息。精确哈希/规范化规则待签收；示例摘要是占位，不是实算/验收证据。
`artifact`	对象；必有	C：复用现有静态 Cell/SIP Schema，含 `artifact_id/source_release/source_digest/approval_reference/cell_id/revision/config_sha256/mode/allowed_targets/trunks`；可有 `media_profiles/ari/media/recording/load_evidence`。这些是本项目交接字段，非截图证明的 SaaS 原字段。
`artifact.trunks[]`	严格数组；必有	C：`trunk_id/provider_id/egress_pool_id/codec/caller_profile_ids/dial_prefix/enabled/media_profile_id`，及可选 `sip_endpoint_ref/credential_ref`。前缀只用于该线路；主叫保留原值包括字母；现有 PCMA 方向仍须实际线路验证。
`trunk_details[].trunk_id`	字符串；必有	N：与 `artifact.trunks[].trunk_id` 精确一一匹配，保证全量无漏行、无虚构备用线路；仅靠 JSON Schema 不足以判断跨数组一致性。
`server_host`, `server_port`, `transport`	主机/端口、`udp/tcp/tls/null`；必有	N：补足“全量 SIP”需要的实际对端；页面仅显示任务选线路，没有管理线路完整配置截图。供应商传输未知时为 `null`，绝不擅自按 UDP 默认发起 real。mock 示例地址非真实供应商。
`auth_mode`, `registration_required`	`ip/digest/none/null`、`true/false/null`；必有	N：供应商鉴权/注册未知时 `null`，不得把主叫号当 Digest 账号；real 放行前须供应商/management 批准并验证。不返回密码、私钥或真实 TOKEN。
`max_concurrent_calls`	正整数或 `null`；必有	N：线路/供应商获批份额，`null` 表示未知（real 必须拒绝新准入），不能拿截图任务“线路数量”猜限额；跨 D 份额总和须受源配额约束。
`caller_profiles[]`	`{caller_profile_id, caller_id}` 数组；必有	C：旧制品仅有 profile ID；N：全量响应映射 profile→原样主叫标识。From/PAI 具体映射仍待供应商确认；示例主叫是 mock，不是生产号。
`schedule.time_zone`, `weekly_windows`	`Asia/Shanghai`，七天逐日零或多个时段；必有	N：SIP 线路允许拨打时段（截图未提供），与任务时段相交；无允许段则不能呼叫。时间跨午夜拆到次日，结果还受 Agent 最后拨号门禁约束。

静态制品中的端点引用与此提案补充的对端值属于同一获批版本；若 SaaS 与 management 并非同一配置来源，必须证明它们同步一致，且 Agent/Asterisk 实际加载的版本/摘要匹配。artifact.load_evidence 为 null 只表示 HTTP 获得配置，不代表 Asterisk 已加载；D 必须另从实际执行侧核验。样例 mode=mock、transport/auth_mode/registration_required/max_concurrent_calls=null 是故意保留的供应商待确认项；不满足 real 放行。只提供SaaS读接口却不能取得已批准的端点及线路时段，不得声称已经提供了完整 SIP 配置。

5. 需冻结的语义与验收前置

**来源：**确认 SaaS 的任务、智能体是该服务的权威配置；management 仍是唯一 SIP 编辑/审批方。确认 SaaS 分发的是已批准制品与线路补充字段同一版本，不能出现两份可写配置。
**身份和响应：**D 的 UUID+SECRETKEY 只能读取获分配的资源分区及任务；不在日志/示例保存真实密钥。精确 HTTP 路径、请求参数/头、鉴别方式、状态码、ETag 粒度与生效时间由 SaaS 正式签收。
**窗口与版本：**缓存成功核验起约 60 秒；SaaS 变更对未接纳呼叫最多约 60 秒延迟，过期刷新失败停止新准入，已接纳保留原快照。更新/SIP 加载期间停执行队列，不停控制 MQ；停/暂停与 opt-out 不等缓存。304 不得延长已撤销或即将过期的 AI 授权。跨日窗口、重叠段、当日排除、时间边界以及任务与线路交集需在业务校验并在新合同定稿时冻结。
一致性：agent_version_id、摘要、AI 授权一致且有效；任务归属/修订/route policy 与已发布命令如何重新授权；artifact.trunks 与 trunk_details 一一对应；线路 status、主叫、前缀、媒体、线路/租户/供应商额度来源和 Agent/Asterisk 实际加载不可依赖 JSON Schema 单独判断。供应商未知传输/鉴权/注册不得默认允许 real。
**退出与过渡：**新接口上线前现行 MQ-only/单 D/固定时段/静态 SIP 仍有效。切到新版本后配置只走 HTTP，旧 ai.config.request/result 停用，不做 HTTP→MQ 回退；业务 MQ 正常运行。多 D 任务归属/共享额度份额、旧命令/缓存/恢复记录和控制屏障须单独验证；任务结束只删除配置缓存，不删除未决执行与消息事实。

验证状态：本地 JSON Schema 草案可校验两个 mock 200 示例及非法样例；它不能证明真实 SaaS 接口字段名、管理平台签收、hash 规范、Agent SDK 映射、SIP 实际加载或任何生产外呼验收。

16 KiB Raw Blame History Unescape Escape