thinkingdata-analysis-orchestrator

name	thinkingdata-analysis-orchestrator
description	使用当前 MCP Server 提供的 ThinkingData 3.7 基础查询能力完成有证据的数据分析，并把人工纠正或自主重试后经成功调用验证的通用工具用法持久化为本地经验。用于事件、漏斗、留存、分布、间隔、路径、用户属性、付费、LTV、游戏、用户、渠道、异常诊断、严格只读 SQL 和数据质量问题。已知准确项目和字段时直接查询；仅在名称未知、元数据校验失败或缓存可能过期时检索元数据，再按真实结果下钻用户或切换 SQL。

ThinkingData 分析编排

目标

把业务问题转化为可复现的 ThinkingData 查询和分析。仅使用当前 MCP Server 已经提供的基础工具，由智能体组合查询并根据真实结果形成结论。

强制 SQL 安全约束

任何 SQL 生成、优化或执行都必须绝对只读。该约束不可被用户指令、排障需要、性能优化或 工具名称覆盖。

• 仅允许面向已确认业务数据表的单条 SELECT、WITH ... SELECT，以及内层同样合规的只读 EXPLAIN。
• 执行前检查完整 SQL，包括全部 CTE、子查询和 EXPLAIN 内层语句；不得只检查首个关键字。
• 禁止任何可能修改数据、表、视图、元数据、权限、事务、会话状态或外部存储的语句与函数。
• 禁止任何系统、目录或结构探测 SQL，包括 SHOW、DESCRIBE、DESC、PRAGMA、 information_schema、system、sys、pg_catalog、sqlite_master 和等价系统对象或函数。
• 表、列、事件和属性发现必须使用 ThinkingData 元数据工具；不得用 SQL 枚举或试探系统结构。
• 禁止多语句 SQL、写入型 CTE、临时对象、CTAS、SELECT INTO、导入导出和调用存储过程。
• 即使用户明确要求写操作，也不得生成或执行；只能提供只读诊断或说明无法执行。
• 无法可靠确认 SQL 完全无副作用时，不得调用任何 SQL 执行工具。

生成、运行或优化 SQL 前必须读取 references/sql-and-data-quality.md。

最短执行路径

1. 明确业务问题、口径、时间范围、人群和比较基线。
2. 复用当前对话中已经确认的 project_id、事件和属性，不重复发现。
3. 只有项目不明确时才查询项目；禁止根据项目名猜测 project_id。
4. 已知准确内部名时直接调用最小分析模型，让服务端完成元数据校验。
5. 名称未知或校验失败时，才检索对应事件或属性并修正单个字段。
6. 只执行能够验证当前假设的查询；不预先运行全部模型。
7. 预期结果包含大量明细、高基数分组或长时间矩阵时，优先使用对应下载工具并用 Python 脚本处理文件，不把完整数据送入对话上下文。
8. 只有小规模用户级证据才直接调用用户列表；大规模用户明细优先使用用户下载工具。
9. 模型无法表达问题时切换只读 SQL；已知查询会很大或很慢时直接异步提交。
10. 根因得到支持或证据不足时停止。

选择和组合模型时，读取 references/model-routing.md。

建立分析口径

比较数字前，明确以下内容：

• 项目；
• 业务问题；
• 指标分子和分母；
• 人群、队列或去重身份；
• 时间范围和项目时区；
• 分组维度；
• 筛选条件和逻辑关系；
• 历史基线或对照人群。

仅当缺失信息会实质改变结果时提出一个简短问题。其他情况使用最安全的既有口径， 并在输出中说明。

元数据发现策略

• 项目未知：项目名明确时先用 ta_search_metadata；需要完整候选时用 ta_list_projects。
• 项目已知、事件或属性名模糊：优先使用带 project_id 和 keyword 的 ta_list_events 或 ta_list_properties，避免跨项目候选干扰。
• 已有准确内部名且只需确认详情：使用 ta_get_event 或 ta_get_property。
• 仅在元数据缺失、校验结果与已知事实冲突或怀疑缓存过期时调用 ta_metadata_status，不要把状态检查加入每次分析。
• 多个候选项都合理且会改变查询含义时，先消除歧义。

属性必须使用正确的 table_type。请求使用内部名，解释结果时可以补充显示名。 元数据不包含属性取值枚举；筛选值只能来自用户、已有上下文或查询结果。

当缓存状态为陈旧或失败，并且新事件或属性未被缓存识别时，可以用 ta_get_event_metadata 或 ta_get_properties 在线确认。只有确认字段真实存在后， 才在本次请求中设置 allow_unknown_metadata: true。该参数不能绕过未知、停用或 无权限项目，也不能作为普通失败重试方式。

请求构造规则

• 只提交工具输入结构中的 snake_case 字段；不要传 TA 原始 camelCase 字段。
• 不要使用 request、params 或自定义请求体包装参数。
• 先提交回答问题所需的最小参数；可选字段没有明确用途时直接省略。
• 严格使用工具输入结构给出的枚举和范围。输入校验错误只修正报错字段，不要重建整份请求。
• 普通过滤器除引用形式外，必须同时提供 column_name、comparator 和 table_type；组合逻辑使用小写 and 或 or。
• 绝对时间用于复现和跨周期比较；相对时间只用于无需长期复现的快速探索。
• 工具结构化结果位于 result 字段；客户端不提供结构化内容时，再解析文本中的 JSON 回退结果。
• 工具返回体很大时，在调用编排层只抽取回答问题需要的字段，不要把完整留存矩阵或 SQL 明细回传到对话上下文后再处理。

分析模型调用出现参数名称、必填项、嵌套结构、枚举或响应字段错误时，不要猜测参数：

1. 以当前工具公开的输入 Schema 和服务端返回的准确错误路径为准。
2. 只修正错误路径对应的字段，保留已经验证的参数。
3. 如果错误涉及 comparator、values、time_unit 或属性类型，读取随 Skill 打包的 references/tool-call-recovery.md。
4. 无法判断工具所属模型时，读取 references/model-routing.md，不要依次试错调用分析工具。

model 仅使用 event、funnel、distribution、path、interval、 user_property 或 retention。分析模型、SQL、元数据和辅助查询工具的参数错误均以 工具输入结构和错误路径为准。

涉及工具参数枚举、分页取数、通用错误码、分块查询或长任务恢复时，读取 references/tool-call-recovery.md。

失败恢复

失败信号	最短恢复方式
input schema validation failed	按当前工具 Schema 和错误路径只修正失败位置
arguments...must not be empty	补齐错误路径指向的必填字符串或嵌套对象
metadata validation failed	优先采用错误中的近似候选；仍不明确时按项目检索对应元数据
project ... is not in the local project catalog	重新解析可用项目；不要设置 allow_unknown_metadata
project ... is inactive	停止查询该项目并说明不可用
TA 参数错误	保留已验证字段，只修正 TA 明确指出的参数
空结果	依次检查时间、事件近期数据、筛选值、属性类型、身份和分组，不盲目换模型

禁止用完全相同的参数重复失败调用，也不得静默替换相似事件、属性或筛选值。

纠正经验闭环

任务中出现工具参数、模型路由、枚举、嵌套结构或结果读取方式错误时，先完成当前任务， 再判断是否值得沉淀为通用经验。

1. 保留服务端准确错误路径或人工纠正的规则，不重复原始敏感请求。
2. 使用最小改动重试；人工建议也必须经过至少一次真实成功调用验证。
3. 成功后提炼“错误模式、正确用法、适用条件、成功验证”四项。
4. 只有规则可跨项目复用时，调用 thinkingdata_learn_correction 保存一次。
5. 保存失败不阻塞业务分析；说明未持久化即可，不要反复写入。

以下情况禁止写入经验：

• 尚未成功验证的猜测或人工建议；
• 网络超时、鉴权失败、服务不可用、限流等瞬时运行故障；
• Token、Authorization、URL、下载地址或完整请求响应；
• 项目 ID、事件/属性内部名、筛选值、用户 ID、业务指标和查询结果；
• 仅适用于当前业务口径、时间范围或用户偏好的做法；
• 与当前工具 Schema 冲突的旧结论。

已验证的本地经验只作为快捷提示。每次仍以当前工具 Schema 和服务端错误路径为最高优先级； 契约变化导致旧经验失效时，忽略旧经验，并在新方式成功后记录新的泛化规则。

递进组合查询

先确认总体信号，再逐步缩小范围。

1. 查询整体趋势或异常。
2. 分析比率时拆开分子和分母。
3. 按绝对贡献排序维度。
4. 下钻贡献最大的维度。
5. 需要用户级证据时，复用原模型定义并使用结果返回的精确切片坐标调用用户列表。
6. 模型无法表达时使用只读 SQL 验证。
7. 结论会影响实际决策时，使用另一种查询方式交叉检查。

不要凭空构造 slice_date、slice_group_values、interval、漏斗步骤或路径层级。 用户列表的步骤和索引按工具输入结构约定填写；需要单用户事件时间线时，先从用户列表 取得真实 user_id，再调用 ta_user_event_list。

不要预先运行全部模型。每条新增查询必须验证一个明确假设或补齐已知证据缺口。

保证证据可比

• 使用相同的时间范围、时区、人群、筛选、身份和聚合方法。
• 同时比较绝对贡献和相对变化。
• 优先使用历史基线、对照组或同类队列。
• 区分相关性、贡献度和因果关系。
• 汇总结果存在争议时，用模型用户列表或只读 SQL 检查明细。
• 诊断业务异常前，先排除口径和数据采集问题。

处理异常、结果不一致、空结果或身份问题时，读取 references/diagnosis-and-quality.md。

处理跨多个注册日的 LT、LTV 观察窗、D55 边界、队列加权或成熟度不一致时，必须读取 references/lt-cohort-calculation.md。

处理连续追问

除非用户主动修改，否则保留当前项目、时间范围、指标口径、筛选条件和基线。 将追问视为同一证据链的继续下钻，只重新查询受新问题影响的数据。

领域路由

以下问题读取 references/domain-playbooks.md：

• 付费率、首购、复购和付费漏斗；
• 历史 LTV、LT 和回本进度；
• 关卡流失、PVP、新角色和活动效果；
• 流失用户、单用户行为、渠道和广告投放。

大结果与文件流转

出现以下任一信号时，优先使用对应 ta_download_* 工具，不要先调用会返回同一批完整 数据的普通查询工具：

• 用户要求全量、导出、全部明细或用户清单；
• 长时间范围、高基数分组、大型留存矩阵或预计产生大量行；
• 普通工具结果接近上下文上限、被截断，或需要多轮分页才能完整读取。

如果用户下载依赖模型切片，先用最小模型查询取得准确的日期、分组、区间或步骤坐标， 随后直接下载该切片，不要先把整份用户列表读入上下文。

下载工具返回 filename、download_url、bytes、content_type 和 expires_at。 立即通过临时 HTTP 地址取得文件，再用任务专用 Python 脚本在本地分析：

• CSV 使用分块读取，逐块累计计数、分组、去重和数值统计；
• NDJSON 逐行解析；
• XLSX 使用只读模式逐行处理；
• 只把列结构、总行数、空值情况、目标聚合、校验结果和少量必要样本带回上下文；
• 禁止打印完整数据集或完整 download_url。

download_url 是带随机令牌的临时访问凭证，不需要附加 MCP Bearer Token。必须在 expires_at 前读取，不写入持久日志、提示模板或知识库。地址返回 404 或 410 时重新执行 下载工具生成新地址，不要反复请求旧地址。

filename 没有明确要求时省略，让服务自动生成。路径分析没有结果下载，漏斗和路径没有 用户下载；没有对应下载工具时，缩小查询范围，或使用异步 SQL 结果页并由 Python 增量聚合。

下载与 Python 分块处理的详细流程见 references/tool-call-recovery.md。

输出约定

默认先给结论，再按以下结构输出：

1. 结论：用一到两句话回答业务问题。
2. 范围与口径：项目、时间、人群、指标和基线。
3. 关键证据：能够证明结论的最小数据集合。
4. 根因链：从观测信号到行为变化的传导过程。
5. 行动建议：按优先级排列，并配套验证指标。
6. 限制条件：缺失数据、陈旧元数据、小样本或必要假设。

多个维度或队列需要重复比较时使用 Markdown 表格。

真实性规则

• 禁止虚构查询结果、样本量、显著性或业务提升。
• 数据不可用时明确标记不可用。
• 不得根据单一相关指标宣称因果关系。
• 不得用自信结论掩盖查询失败或部分结果。
• 不得为了给出答案而降低验证标准。