Insights Beta：聚类配置、作业与运行集

Insights 对一个 Tracing Project 的 Run 做抽样、聚类和模型摘要，产出层级 cluster、统计、关键点与代表 Trace。整组 API 都标记 Beta；它适合运营/研发发现模式，不应作为不可逆业务决策的唯一依据。

区分 Config 和 Job

Config 是可复用/可调度配置，Job 是某次实际执行。

对象	创建 / 列表	读取 / 更新 / 删除
Config	`POST/GET /api/v1/sessions/{session_id}/insights/configs`	`PATCH/DELETE .../configs/{config_id}`
Job	`POST/GET /api/v1/sessions/{session_id}/insights`	`GET/PATCH/DELETE .../insights/{job_id}`
Auto-generate config	`POST .../insights/configs/generate`	返回 summary prompt/name/attribute schemas
Cluster	—	`GET .../insights/{job_id}/clusters/{cluster_id}`
Job 中 Runs	—	`GET .../insights/{job_id}/runs`

Config 创建必填 name 和完整 config，可带 description 与 schedule_cron。列表的 include_prebuilts 默认 false；预制配置的 ID 可为 UUID 或字符串，客户端不要强制全部按 UUID 解析。

作业输入的五个维度

CreateRunClusteringJobRequest 可来自 config_id，或内联配置：

时间：start_time/end_time 或 last_n_hours；
样本：filter、sample、分区 partitions；
聚类：hierarchy、attribute_schemas、user_context；
摘要：summary_prompt、name；
模型：provider openai|anthropic，可分别指定 cluster/summary model；validate_model_secrets 默认 true。

Auto-generate 接口必填 user_context，可指定同样的 provider 与两类 model，返回建议 summary prompt 和 attribute schema。模型生成配置必须经人工审查：prompt injection、PII 放大、错误属性类型和过度细分都会让结果偏离原问题。

作业状态与结果

创建响应只有 id/name/status/error，表明是异步作业。读详情可得到时间、metadata、shape、error、config ID、clusters 及 Insights report。状态在 OpenAPI 中是自由字符串而非枚举，客户端要容忍未知新状态，只将已知终态作为完成，并对 error 做脱敏。

Job 列表用 offset/limit（默认 100），可按 config 和 legacy 筛选。Job 中 Runs 也是 offset/limit，可按 cluster_id 和 attribute key/order 排序；不能用页内数量代替总量。Cluster 返回父 ID、level、name/description、子节点或 Run 数与 stats；层级是分析结果，不是稳定业务分类 ID。

调度、成本与隐私

schedule_cron 和 is_scheduled 会使聚类反复消耗模型和扫描 Run。上线前必须为时间窗、sample、并发作业数和预算设限，同时观察运行时间、输入 Run 数、token/cost、失败率和结果稳定性。

用于聚类的 inputs/outputs/metadata 会发往选定模型 provider；执行前先过数据分类、脱敏、地域和保留期门禁。不在 Config 中写 API key，仅引用 workspace 密钥管理中的 provider credential；测试密钥失败不应在响应/日志中回显密钥。

Beta 迁移策略

持久化原始 config/job/cluster 响应与 API 版本，读取时采用宽松解析、写入时采用严格已知字段。更新 Config 前克隆并灰度新 Job，不在正在使用的调度配置上就地大改；删除 Job/Config 前导出结果和依赖关系，文档未承诺级联删除。