index

ChatGPT 网页版 Chat 模式停止门槛（请先阅读）

当正向系统或开发者信号同时表明 surface = chatgpt_web 和 mode = chat 时，在应用此技能中的任何其他指导前停止。在分析请求的第一轮，只回复一条简洁建议，建议切换到 Work Mode，因为 Data Analytics 在该模式下表现最佳。不要加载专门的分析技能、检查数据或来源、调用工具、询问需求问题、执行分析或创建产物。告诉用户，如果更愿意，也可以明确要求继续使用 Chat 模式。

只有在给出建议且用户明确表示要继续、继续执行或留在 Chat 模式后，才可在 Chat 模式下继续。重复原始请求、补充数据或回答先前的问题都不算覆盖建议。用户明确覆盖建议后，无需让其重述请求，即可继续处理原始分析请求，并遵循下方的 ChatGPT 网页版 Work Mode 运行分支进行需求收集、持久化和输出。当前分析请求中保留这一覆盖状态；在 Chat 模式下提出新的分析请求时，再次从此停止门槛开始。

资格门槛（路由前请阅读）

只有当处理请求需要结构化记录、数值指标、定量证据、仪表板／指标定义，或基于此类证据的业务／产品决策时，才使用此插件。仅仅出现看似与分析相关的词语（报告、演示文稿、仪表板、市场、验证、导出）并不足以构成使用条件：如果任务无需数据／证据就能作为普通的撰写、格式整理、布局、转换或定性描述来完成，则不要将其路由到此处。明确标记的分享流程可以自行处理交接；此索引不应根据笼统的分享／导出请求推断出分享场景。

如果请求显然依赖于对数据、指标、仪表板或定量业务证据的解读，即使尚未说明具体指标或交付物，也应视为符合条件。加载索引、检查当前会话上下文，或询问最少量的缺失背景信息，然后选择最精准的专门技能。不要要求用户事先指定指标；但对于不需要解读证据的纯机械转换、格式整理、代码修复、语法片段或通用说明，应予以拒绝。

符合条件时，选择最具体的分析技能；如果无法确定，应提出一个澄清问题，而不是打开通用的报告／导出技能。

上市／细分决策提示

符合条件的产品分析请求可能涉及产品上市、推广、优先级排序、细分、实验结果解读、A/B 测试解读，或在既定或待收集的假设／约束下，就发布／暂缓／迭代的权衡提供建议。只要请求提及指标、置信度／不确定性、护栏指标、细分群体或结构化证据，即使第一步是收集背景信息，也应将其视为分析工作流；需将背景信息与 product-business-analysis 配合使用，并且只要选择了 product-business-analysis，就必须包含 build-report，除非用户明确放弃创建报告或选择了其他主要产物。

指标定义／权威数据源争议

当团队对于哪种指标定义、仪表板、数据导出、负责人或权威数据源应作为决策或高管回复的依据存在分歧时（例如收入／ARR、激活、留存、漏斗或区域总计），即使眼前的输出只是一条简短的 Slack／电子邮件建议，也应将其路由为分析任务。对于可比性／回填／粒度／数据源冲突，优先使用 analyze-data-quality；对于规范定义／护栏指标的归属，优先使用 design-kpis；如果请求询问应以哪个定义为准，则两者都使用。

分阶段分析工作流的后续步骤

如果一个请求要求先询问或收集负责人、限制条件、假设或上下文，然后根据这些信息作出分析决策、提出建议、创建仪表板或报告，不要在询问澄清信息后就停止。加载 $gather-business-context，然后加载最相关的分析技能。如果该技能是 $product-business-analysis、$metric-diagnostics、$kpi-reporting 或 $market-sizing，除非用户明确放弃创建报告或选择了其他主要交付物，否则将 $build-report 纳入同一条流程。对于任何其他持久化的叙述性交付物，在澄清前加载 $build-report。如果仍缺少信息，加载这些技能后再提出澄清问题。

技能用途

将宽泛的数据分析请求路由到合适的专用工作流。如果请求需要量化证据、来源核验、指标推理或基于数据作出决策，则应将调用此索引视为强烈意图使用此插件的信号；优先选择专用分析技能，而不是通用报告或导出处理。

技能配置

运行时路由

分别对 surface 和 mode 进行分类，且只能依据明确的系统或开发者信号，或确实具有排他性的工具：

• 当环境明确标识为 Codex 桌面版，或可使用仅限桌面端的 codex_app 工具时，设置 surface = codex_desktop。
• 当环境明确标识为在 Web 浏览器中使用 ChatGPT 时，设置 surface = chatgpt_web。
• 当环境明确标识为 Codex Work Mode 时，设置 mode = work_mode。
• 当环境明确标识为标准 ChatGPT 对话时，设置 mode = chat。
• 否则，将相应值设为 unknown。

绝不要根据 surface、缺少工具、工具故障、操作系统、文件路径、沙盒详情或网络详情推断 mode。明确的上下文优先于工具可用性。只有在 surface = chatgpt_web 和 mode = work_mode 均得到明确确认时，才将 web_work_mode 视为 true。如果 mode = work_mode 而 surface = unknown，则将其视为部分 Web Work Mode 信号，以保障交付安全：除非已明确确认 surface = codex_desktop，否则不要选择 Data Analytics MCP UI 来交付持久化报告或仪表板。

对 surface 和 mode 分类后，选择最具体的匹配运行时分支：

运行时分支	信息收集	语义层持久化	输出界面
ChatGPT 网页聊天模式（surface = chatgpt_web、mode = chat）	在收集信息前，先应用上述停止门槛。获得明确覆盖后，遵循下文的 ChatGPT 网页工作模式信息收集指南。	获得明确覆盖前，不要创建或更新持久化内容。获得覆盖后，遵循下文的 ChatGPT 网页工作模式持久化指南。	获得明确覆盖前，不要创建输出。获得覆盖后，遵循下文的 ChatGPT 网页工作模式输出指南。
Codex 桌面端（surface = codex_desktop）	如可用，使用 request_user_input 进行结构化信息收集。若不可用，则以简洁的对话式选项作为备用信息收集方式。	将语义层设置或维护交由 create-data-context；本地创建默认使用该技能现有的 $CODEX_HOME/skills/<area>-semantic-layer 路径，除非用户选择其他位置。	可使用 Data Analytics MCP UI 界面。报告模式工作交由 $build-report，默认使用 mcp-app，仅在符合其明确的备用规则时才使用 HTML。
ChatGPT 网页工作模式（web_work_mode = true）	如可用，使用 $answers-ask-user-input 或等效的原生结构化信息收集操作进行结构化信息收集。若不可用，则以简洁的对话式选项作为备用信息收集方式。	将语义层设置或维护交由 create-data-context。如果本次运行中可使用 Skills 安装界面，则使用 ChatGPT 个人 Skills 持久化功能。	只有在已选择内联交付后，才使用原生工作模式渲染。对于恰好一个受支持的 bar、line、pie 或 scatter 图表，将 charts_widget_v2 视为可直接呈现，并在回退前输出其实时 genui 内容引用；不要自行宣称其不可用、搜索它，或将其载荷以裸 JSON 形式打印。仅当宿主提供 app_block 时才使用它。默认以 HTML 交付可持久保存的报告和仪表板；如果用户选择了已连接的 BI 或其他非 MCP 目标，则使用该目标。MCP 服务和其他可调用工具仍可作为有效的数据源。
表面未知的工作模式（mode = work_mode、surface = unknown）	如可用，使用 $answers-ask-user-input 或等效的原生结构化信息收集操作进行结构化信息收集。若不可用，则以简洁的对话式选项作为备用信息收集方式。	将语义层设置或维护交由 create-data-context。除非本次运行中明确提供 ChatGPT 个人 Skills 安装界面，否则使用可移植的持久化方式。	默认采用适用于 Web 的报告和仪表板交付方式：选择 HTML、已连接的 BI 或其他非 MCP 目标。如果已确认处于工作模式但表面未知，不要选择 Data Analytics MCP UI 交付。
其他：所有其他或未知运行时	如可用，使用 $answers-ask-user-input 或等效的原生结构化信息收集操作。仅当无法进行结构化信息收集时，才使用简洁的对话式选项。	将语义层设置或维护交由 create-data-context。该技能会选择可用的 ChatGPT Skills、本地 Codex 或可移植软件包目标。	使用运行时提供的输出界面以及专用技能规则；如果无法明确确认运行时特定的输出界面，则默认使用可移植的输出方式。

对于使用所提供的上下文完成当前回答的常规分析工作，请仅在当前会话中保留该上下文，并继续执行相关分析工作流。

已保存的数据上下文与语义层

普通分析工作流无需设置已保存的数据上下文。请使用当前会话中的上下文，包括请求、对话、已连接数据源的读取结果、上传的文件、粘贴的材料、本地仓库文件、明确指定的语义层，或当前运行时中可发现的用户创建的语义层技能。已保存上下文和语义层的生命周期请求路由至 create-data-context。其他分析上下文仅限当前会话，并遵循 Runtime Routing。

引导流程与数据源设置

本索引负责任务选择、与设置相关的路由，以及引导式工作流的继续执行。确定用户有使用插件的意图后，对于入门请求、开放式提示词探索、上传或演示数据以及流程讲解问题，应用其无状态的首次任务流程。纯功能概述请求发送至 Broad Orientation And Help Requests。如果用户已提供具体任务，则跳过信息收集，并将其视为自定义问题。

仅使用当前对话、可见的已安装插件和技能、当前运行中的工具结果、上传或粘贴的上下文，以及本地文件。不要显示数据源、项目、仪表板、表、SQL、文件、连接器或提供方选择器。如果用户要求分析数据，但未提供数据、数据源或可发现且可调用的数据源，请索取最少量的有用数据材料，或提供上传／示例数据的备用方案。除非用户明确要求，否则不要通过此流程创建已保存的数据上下文。

首次任务信息收集

使用以下结构化表单约定。在 Codex 桌面应用中，只要 request_user_input 可用，就调用它。在其他所有界面或模式下，只要 $answers-ask-user-input 可用，就调用它。如果适用于当前界面的结构化信息收集操作不可用，但运行时提供了等效的原生结构化信息收集操作，则使用该操作。不要仅因运行时为 chatgpt_web、work_mode 或未知环境，就退而采用对话式选项。如果结构化信息收集不可用，请在普通对话中简洁地提供相同的任务或备用选项。

提供已连接数据源的选项前，请根据运行时提供的技能清单、已安装的 Apps 和 Plugins、推荐插件列表、可调用工具、当前对话、上传或粘贴的材料、本地文件以及可发现的语义层技能，确定可能的数据通道。对于分析任务，应主动查找事实来源通道，例如数据仓库或 SQL 数据库、BI 仪表板、产品分析系统、电子表格、数据源定义文档以及相关沟通上下文；使用可调用工具、上传或粘贴的材料、本地文件和当前运行中的数据源读取结果，判断哪些通道可立即使用。

当可能的数据源通道暂时无法调用时，使用推荐插件和已安装插件的元数据来确定设置或安装路径。

如果 tool_search 不可用，而运行时提供了 ALL_TOOLS，请检查 ALL_TOOLS 中的名称、描述和插件来源。与安装建议相比，应将可调用工具视为当前可立即访问数据源的更有力依据。

只要有任何数据仓库或源系统工具可调用，就应优先提供基于数据仓库的任务，并遵循 Connected-source option copy 中的数据源优先级。

1. 如果用户提供了具体任务，请跳过信息收集，继续执行 Custom-question access。
2. 否则，只检查运行时提供的已安装 Apps 和 Plugins 清单，以及会话中已可见的可调用工具，包括自定义 MCP 服务和其他能够读取所需来源的可调用工具。不要读取连接器记录，不要调用 functions.list_available_plugins_to_install，也不要将 .app.json 声明视为已安装项。如果工具被延迟加载，请在可用时使用 tool_search；否则使用运行时的可调用工具注册表，例如 ALL_TOOLS。根据已可见或用户点名的连接器、自定义 MCP 服务或其他可调用工具的名称、来源类型或与任务相关的能力进行查询，以确认其可调用性；不要只搜索固定的提供商目录。
3. 如果至少有一个有用的已连接数据源，请在 Codex 桌面端调用 request_user_input，或在其他环境调用 $answers-ask-user-input，且只调用一次，并且恰好提供三个选项：两个由现有已安装连接器或可调用工具支持的不同任务，后接 Upload your own。优先选择不同的数据源类别；如果有用的数据源不足两个，则根据同一已连接数据源的能力推导多个互不重复的任务。绝不要加入示例、安装或不受支持的选项。
4. 如果没有有用的已连接数据源，则只提供 Upload data，后接 Use sample data。不要加入 Connect a data source。

将 Dashboard、Report 或 Data task 用作标题。如果已知要创建的内容，则询问 What should the dashboard be about? 或 What should the report be about?；否则询问 The Data Analytics plugin turns data into insights, recommendations, and decision-ready artifacts. Try it out with one of these prompts:。标签不得超过 80 个字符；省略推荐后缀，并保留内置的自由输入 Other 字段，以便用户提出自定义问题。如果当前界面不支持相应的结构化信息收集操作，则在聊天中以简洁格式呈现相同选项。取消提交或提交内容为空时，暂停此流程。

已连接数据源表单：{ id: "data_task", options: [{ label: "{connected task 1}", description: "{connected-source description 1}" }, { label: "{connected task 2}", description: "{connected-source description 2}" }, { label: "Upload your own", description: "Upload or paste your own data and produce an analytics report with findings and next steps." }] }。

无数据源表单：{ id: "data_task", options: [{ label: "Upload data", description: "Upload or paste your data and produce an analytics report with findings and next steps." }, { label: "Use sample data", description: "Analyze sample product-growth data and produce an analytics report." }] }。

选择处理

• 已连接数据源任务：使用对应的现有连接器或可调用工具，并启动隐含的专项工作流。对于预填充的已连接数据源选项，始终调用 $product-business-analysis、$visualize-data 和 $build-report。自动选择主导数据源；不要打开插件安装流程。如果数据源意外无法提供可用证据，则使用下方的回退表单。
• Upload your own 或 Upload data：请用户提供最精简且有用的数据导出、SQL 查询结果、数据结构、屏幕截图、指标定义或文件，然后等待。
• Use sample data：无需再次确认，立即启动演示约定流程。
• 用户明确要求“使用示例数据”或“使用这份示例数据”，且未指定或附上其他示例时，应选择 Use sample data；立即解析随附演示数据，不要搜索工作区或要求用户上传。
• 其他文本：视为用户自拟的自定义问题，并继续执行 Custom-question access。

不要要求用户选择提供商、项目、表、仪表板、查询或导出内容。如果没有提供或无法发现可用数据或数据源，请询问用户提供实际缺少的数据材料。只有当现有数据源之间存在会影响答案的冲突时，才询问用户确认数据源。

自定义问题访问

只有用户消息或 intake form 的 Other 字段中提供的具体任务，才能触发安装。选择聚焦的工作流，然后判断现有插件、应用、连接器、自定义 MCP 服务、其他可调用工具、已上传或粘贴的内容、本地文件，或当前运行上下文是否能提供足够新且权威的证据。如果可以，选择主导来源并开始。

如果缺少证据，请先检查可见或可延迟加载的自定义 MCP 服务和其他可调用工具，确认它们能否读取所需来源，再安装原生连接器。如果某个自定义 MCP 服务或其他可调用工具的服务或工具名称、描述、操作架构，或用户指定的来源表明它能读取所需的来源类别，就将其视为相关工具。已配置的 preferred_plugins 和 .app.json 条目只是路由提示，并非所有来源的完整范围。

如果仍缺少必需证据，且存在合理的连接器路径，请使用 .app.json 中的应用类别映射来源类别，并调用一次 functions.list_available_plugins_to_install。如果当前运行上下文已列出被抑制的确切插件安装 id，就移除这些确切 id；不要仅为获取抑制项而运行旧版预检。然后，对每个确切且适用于任务的返回候选项，依次调用 functions.request_plugin_install。不要猜测 id，不要只选一个笼统的“最佳”候选项，不要在找到第一个有用候选项后就停止，不要并行调用安装，也不要使用 request_connector_setup。如果安装被拒绝或未确认，请使用 record_plugin_install_suppression.py 记录该确切 id，并继续处理其他有用候选项。

数据仓库例外：如果自定义任务需要结构化数据、没有可用的数据仓库，且用户未指定数据仓库，则保留所有返回的数据仓库候选项。询问用户要使用哪个数据仓库，并列出所有候选项；只安装用户选定的确切候选项。如果只返回一个候选项，直接向用户提供。绝不要依据清单顺序或已配置的偏好进行选择。

如果设置不可用、被拒绝、未确认、已取消，或仍无法提供足够证据，你必须在同一轮结束前提出此备用问题：{ id: "fallback_next_step", question: "I don't have enough data to complete this task. How do you want to proceed?", header: "Next step", options: [{ label: "Upload data", description: "Upload or paste your data and produce an analytics report with findings and next steps." }, { label: "Use sample data", description: "See a clearly labeled synthetic product-growth demo; it will demonstrate the workflow without answering the real-data question." }] }。不要添加其他自定义选项或建议后缀。

设置成功后，自动开始聚焦的工作流。不要显示设置后的流程控制选项。

无来源时必须提供后续选项

任何判定当前任务没有可用数据的路径，都必须在本轮结束前提供 Upload data 和 Use sample data。这包括没有可用的已连接来源、所需来源不可用、安装工具不可用、安装提示被拒绝、关闭、取消或未确认、安装成功但仍无法获取可用证据，以及已连接来源意外缺少足够证据。

不要只以缺少来源的解释、安装建议，或要求用户连接来源后重试的指示结束。安装提示可以先于备用问题出现，但除非设置成功且来源在当前运行中返回可用证据，否则安装提示绝不能替代备用问题。对于具体任务，使用上文确切的 fallback_next_step 形式。对于 Use sample data，请明确说明捆绑的演示数据是合成数据，将用于演示工作流，而不是回答用户关于真实数据的问题。

已连接数据源选项文案

如果某个可见的已安装或可调用界面的名称、描述或操作表明它可以访问数仓、SQL、查询、表、架构、数据集或数据库，则将其视为类似数仓的数据源。按与事实来源的匹配度排列可用选项：数仓／源系统优先，其次是 BI、产品分析、GitHub、表格类 Drive／文件，最后是最匹配的文档或通信来源。任务必须能够通过其已连接的数据源执行。

非数仓任务使用特定数据源的标签，数仓标签则不指定提供商。如果一个连接器可用于多个选项，应根据连接器的实际能力区分任务，不要重复使用相同文案。以下是默认设置，不是隐藏提示词：

数据源	标签	描述
数仓或源系统	Analyze business data	分析数仓或源系统数据，找出趋势、细分群体、异常值和后续步骤。
BI／仪表板	Analyze dashboard trends	分析仪表板或 BI 数据，找出趋势、差距和后续细分角度。
产品分析	Analyze product usage	分析事件、转化漏斗、留存、实验和行为变化。
GitHub	Analyze GitHub activity	分析议题、拉取请求、评审和阻碍因素。
电子邮件	Analyze email trends	分析邮件会话中的主题、趋势信号、后续跟进事项和下一步操作。
Drive	Analyze Drive files	分析相关 Drive 数据，得出发现并确定后续步骤。
日历	Analyze meeting patterns	分析会议主题、参会者、时长、频率和后续步骤。
Notion	Analyze Notion content	分析页面和数据库中的项目状态、决策和主题。
Slack	Analyze Slack activity	分析消息中的活跃主题、阻碍因素、决策和后续跟进事项。
Teams	Analyze Teams messages	分析聊天和频道中的主题、行动事项、阻碍因素和决策。
SharePoint	Analyze SharePoint files	分析相关 SharePoint 数据，得出发现并确定后续步骤。

演示数据

仅当不存在有用的已连接数据源，或所选工作流仍缺少可用证据时，才显示 Use sample data。相对于此技能定位 demo-product-growth.csv，将其标记为合成数据，使用可复现的 SQL 进行分析，不得虚构行或发现，并通过 $product-business-analysis、$visualize-data 和 $build-report 处理；由 $build-report 选择且仅选择一种报告交付模式。

数据源发现与验证

将相关语义层作为起始地图，而非边界。

1. 探索所有可能的数据源。 搜索每个可能包含任务相关数据或会影响结果解读的已连接或已提供数据源。对于每个结构化数据源，都应重新发现相关架构、数据集、表、视图、模型和指标的目录或元数据。已知的数据源、表、仪表板和语义映射是起点，不是终点。
2. 比较重复项和冲突。 当多个数据源内容重叠或彼此不一致时，应比较其所有权、时效性、定义、粒度、覆盖范围和直接性。选择最权威的数据源，或在必要时整合互补数据源。注明重大冲突，说明所选数据源为何足以作为依据，并在得出结论前通过实时读取验证所选数据。

数据源访问防护规则

在查询数据源、构建产物或得出结论之前，确定答案是否需要特定的事实来源。

如果所需数据源不可用，请停止该路径。告知用户需要哪种数据源，不要将较弱的替代来源视为同等来源。然后应用强制性的 No-source completion invariant：在结束当前轮次之前，提供上传数据或明确标记的合成演示数据。

如果缺失的数据源仅用于可选补充，则继续使用最有力的可用证据；如果数据缺口会实质影响答案，应明确标注。

受众与语言

面向 Data Analytics 用户，而非插件维护者。此要求适用于最终答复、设置/状态回读、故障说明、工具前置说明以及对话中的进度播报。

将实现工作转化为对 Data Analytics 的实际影响：说明 Data Analytics 正在检查、设置、保存或准备什么，以及这样做的原因。除非用户要求提供调试详情，否则避免使用 preflight、state file、cache、raw connector id、heartbeat、targetThreadId、schema、API、runtime、metadata 和 provider taxonomy 等实现术语。

来源链接

在正文中引用来源时，只要来源提供了有用的 URL，就优先使用可点击的 Markdown 链接，而不是纯文本方括号标签。将来源标题、记录名称、频道/线程或会议/日期作为链接文字，例如，可点击的 Markdown 链接，其可见文字为 会议记录：5 月 19 日 或 Slack 线程：5 月 15–21 日。仅当没有可用的有用 URL 或稳定的连接器可见链接时，才使用纯文本标签；如果此缺失会影响理解，请注明“（没有可用的有用链接）”。

路由

执行顺序

每次 Data Analytics 插件运行都按以下顺序进行：

1. 对纯能力概览请求使用 Broad Orientation And Help Requests 处理；对开放式操作或提示词发现、首次运行时的任务选择、明确要求引导流程，以及应在深入设置前先选择并运行数据任务的设置相关提示，应用 Guided Flow And Source Setup。
2. 如果用户要求保存数据上下文，或创建、更新、检查或修复语义层，则路由到 create-data-context；它会根据当前运行时分类得到的 surface 和 mode 值，选择 ChatGPT 个人 Skills、本地 Codex 或便携式软件包持久化方式。
3. 如果用户要求使用现有语义层回答数据问题，则将该语义层作为上下文，并继续执行适当的分析工作流。
4. 仅当用户指定了语义层或路径，或当前运行时已发现相关语义层时，才查找语义层。
5. 在查询数据源、搜索文档、处理 Notebook、构建报告、连接仪表板或得出结论之前，应用“来源发现与验证”。
6. 在查询数据源、搜索文档、处理 Notebook、构建报告、连接仪表板或得出结论之前，应用“来源访问防护措施”。
7. 选择响应模式：只要本次运行分析了数据并得出发现，默认使用 report；仅在用户明确要求快速回答，或查找范围明确且无需解读时，才使用 inline。
8. 选择最少量的主要/辅助 Skills，然后对已安装的 Skills 进行一轮配套技能检查，以寻找更清晰的非分析界面、语义层或方法。
9. 在查询数据源、构建报告、执行辅助技能或起草最终答复之前，阅读并遵循所选技能的正文。
10. 最终答复前，应用当前工作流的完成检查要求。除非用户明确要求保存数据上下文或处理语义层，否则将 create-data-context 的输出视为可选内容。

响应模式

每当数据分析运行分析真实或示例数据并产出发现、解释、比较、分解、KPI 解读、诊断、建议或决策支持时，默认使用 report。用户无需说“report”。如果结果适合辅以有证据支持的叙述、来源背景、注意事项、可视化内容，或需要在当前聊天轮次之外复用，请选择 report。如果无法确定该选 inline 还是 report，请选择 report。

仅当用户明确要求快速聊天答复，或请求确实属于范围明确的事实或计算查询时，才使用 inline，例如查询一个指标值、架构或表格问题，或无需解读、可视化、来源说明或持久交付的单次计算。提示简短并不意味着任务自动适合 inline：比较、排名、趋势、细分、集中度以及多个数值或时间点之间的变动，通常都应生成报告。

不要仅因为证据可能只需一张表格或图表就能呈现，便将提示归类为范围明确的查询。询问哪个维度、类别、群组、实体、细分或驱动因素导致指标增长、下降、变化、差距或偏差的问题，属于诊断路径：使用 $metric-diagnostics；除非用户明确放弃创建报告或选择其他主要交付物，否则还要包含 $build-report；如果图表有助于阐明贡献模式，则还要包含 $visualize-data。如果当前值查询、总量、简单时间序列以及直接的当前值排名没有涉及驱动因素、变动、偏差、诊断、建议、敏感性或解读，则仍可使用 inline。

每个 report 路径都包含 $build-report，除非用户明确要求提供 inline、仅限聊天、简短或不带交付物的答复，要求不要创建报告／文件／交付物，或选择其他主要交付物，例如仪表板、笔记本、电子表格、原生文档或幻灯片。$product-business-analysis、$metric-diagnostics、$kpi-reporting、$market-sizing 和面向利益相关者的 $analyze-data-quality 运行默认使用 report。快速 KPI 状态更新或简短 KPI 解读应选择 inline，除非用户还要求报告、文档、演示文稿或持久交付物。不要仅仅因为用户没有提到“report”、提出了直接的诊断问题，或要求估算或解读，就推断用户放弃创建报告。

选择 inline 或 report 后，如果可视化能让结果更易于理解，则使用 $visualize-data；尤其适用于类别比较、部分与整体的分解、排名、随时间的变化，或超过少数几个可比较的数值、行、类别或时间点的情况。优先采用可视化，而非需要逐项扫描的表格；由 $visualize-data 选择呈现形式、判断是否生成图表，并使表格或文字与可视化所传达的要点保持一致。对于 report 模式的运行，只要需要图表或图示，就包含 $visualize-data；主要分析技能应传递可视化意图和证据，而不是直接绘制图表。

技能选择

• 选择最精简且实用的主技能和辅助技能组合。
• 对于报告模式的运行，在进度更新中说明一次所选路线，例如 Route: product-business-analysis + product semantic layer + build-report。
• 对于所有 Data Analytics 技能中的数据源／任务设置请求，包括明确的设置、入门、首个引导式工作流、设置状态、离线／演示回退、操作演示以及继续进行中的引导流程请求，使用此索引中的引导关卡。不要在此关卡中主动创建已保存的数据上下文或语义层。
• 对于常规数据工作之外明确提出的语义层设置或维护请求，使用 create-data-context。
• 将提及插件视为起点，而非边界。如果已安装的外部技能更适合负责互补的子任务、运行时界面、交付界面、产物类型或特定领域方法，就一并使用。
• 不要仅因某项外部技能与内置的 Data Analytics 技能有部分重叠，就拒绝使用它。
• 不要在此维护详细的路线配方。选定技能后，由该技能负责详细的步骤顺序、辅助触发条件和输出要求。
• 当请求对应某个主工作流时，直接加载该工作流技能。例如，KPI 设计提示必须读取 $design-kpis，仪表板请求必须读取 $build-dashboard，TAM/SAM/SOM 请求必须读取 $market-sizing，指标变动诊断请求必须读取 $metric-diagnostics，以建议为导向的产品或业务决策请求必须读取 $product-business-analysis。

如果有多个聚焦型技能适用，按最有助于分析工作的顺序组合使用。例如，指标诊断可以先于 KPI 报告，语义层设置可以先于仪表板或报告工作，产品业务分析可以为形成建议的报告提供依据。请将此索引用作路由器；不要在此执行聚焦型工作流的具体逻辑。

在最终确定今后涉及引导流程或 create-data-context 行为的 Data Analytics 指令编辑之前，请从仓库根目录运行 python3 plugins/data-analytics/skills/create-data-context/scripts/validate_data_context_contract.py。此验证器会检查引导流程和语义层设置是否仍由各自负责的技能处理。

优先采用无需额外设置、能将请求路由到聚焦型技能的示例，例如：

@Data Analytics diagnose why a key business metric moved last week.
@Data Analytics build a KPI framework for the product activation funnel.
@Data Analytics analyze paid workspace retention and recommend what to investigate next.

对于紧接着已完成的引导式工作流（该工作流提供了操作演示）之后出现的后续消息，例如“是”“带我走一遍”“发生了什么？”或“展示步骤”，请根据此索引作答。以适合初学者理解的方式说明可观察到的步骤、所选工作流、连接器设置尝试、离线或演示数据回退、澄清问题、数据源缺口和产物组装过程，但不要透露隐藏的推理过程。

整体介绍与帮助请求

对于整体介绍和帮助请求：

• 在选择专门的工作流之前，先从此索引处理对能力的概述请求。
• 如果用户想了解整体情况，而不是选择任务，则将纯能力概述请求（例如 what can you do?、show me the capabilities 或 explain Data Analytics）路由至此处。
• 将 what should I try?、what should I do?、let's do something、get started with a first task、how do I use Data Analytics? 或 choose a guided workflow 路由至 Guided Flow And Source Setup；将保存数据上下文或创建、更新、检查或修复语义层的请求路由至 create-data-context。
• 无论此前的设置情况如何，能力概述都使用此索引级帮助答复；只有明确的设置请求才进入特定设置处理流程。
• 根据此文件中的技能映射，使用下方的默认格式作答。
• 能力和插件详情介绍时保留以下三个通用示例。两个已连接数据源的任务以及 Upload your own，或无数据源时的上传／示例回退选项，仅适用于结构化的首次任务接收流程。
• 只有当用户询问设置、可用数据源、Data Analytics 配置，或当前会话已显示存在重要的数据源缺口时，才加入简短的设置上下文部分。
• 设置上下文应面向分析人员：指出实际可用的数据源；根据数据源标签、已配置的首选路由、设置操作和建议的后续提示词，运用模型判断说明可能对用户体验造成的影响；然后给出最精简的后续操作或回退方案。
• 默认最多展示三个影响最大的缺口，设置上下文的条目总数绝不能超过五个。根据所建议示例的相关性对缺口排序，不要遵循硬编码的影响目录。
• 如果所有数据源都已启用，设置上下文只用一句话说明，例如：Your core Data Analytics sources look ready; I'll still try each source only when a workflow needs it.
• 设置上下文措辞应直接实用，例如：You won't be able to properly validate a metric from live tables until a warehouse or SQL source is available, but you can paste SQL, schema details, or exported query results for now.
• 不要透露原始状态名称、连接器 ID 或实现术语。
• 回答能力问题时，不要仅为此读取连接器；使用上下文中已显示的当前会话应用或工具可用性。

对于整体介绍和帮助请求，使用以下默认答复格式：

Data Analytics can help with:
- Metric diagnostics and source-backed explanations for movement
- KPI design, metric definitions, and measurement frameworks
- Product and business analysis for funnels, retention, adoption, pricing, and strategic decisions
- KPI reports, dashboards, notebooks, and reusable semantic layers
- Market sizing, opportunity sizing, and decision-ready recommendations

Setup context:
- {Only include when useful: source readiness or gap plus practical impact}

Good first prompts:
- `@Data Analytics diagnose why a key business metric moved last week.`
- `@Data Analytics build a KPI framework for the product activation funnel.`
- `@Data Analytics analyze paid workspace retention and recommend what to investigate next.`

插件用途

Data Analytics 可将已连接或提供的业务数据、事实来源上下文、仪表板、文档、聊天记录、笔记本、电子表格、SQL 和语义层转化为有来源支撑的分析成果。它可以定义 KPI、诊断指标变化、估算市场规模、分析产品或业务问题、验证数据质量、收集上下文、构建可复现的笔记本、设计可视化内容、创建仪表板、制作精良的报告，并将这些成果转换为可分享的 Docs、Slides、电子表格或其他可长期留存的交付形式。

语义层

语义层是由源资料支持的本地技能，适用于产品、业务、指标、数据源或报告领域。它们编码规范指标、表、粒度、联接、筛选条件、查询模式、注意事项、数据源优先级和验证缺口。

在回答有关指定产品领域、指标、表、仪表板、SQL 查询、数据源选择、联接、注意事项或常见业务问题的问题之前，仅当用户指定了某个语义层、语义层技能或路径，或当前运行环境中已可发现相关语义层技能时，才使用语义层。如果存在相关语义层，请先阅读，再选择表、编写 SQL、协调仪表板数据或给出指标定义。将其视为领域专用语义图谱，然后查阅已连接或用户提供的应用，并依据该语义层引用的来源验证高风险声明。

语义层可以指导数据源选择、分析惯例，以及用户明确要求的 SQL 交付，但不能扩大用户要求的输出范围。只有当当前用户请求明确要求查看、编写、审查、调试或获取 SQL 或查询方法时，才应用语义层对提供完整 SQL 的偏好。通过执行 SQL（包括基于查询的回答）来回答数据问题，本身并不代表用户要求提供 SQL。

如果不存在相关语义层，且用户询问的是可重复回答的领域问题，请通过 create-data-context 提供语义层设置选项。用户可以为多个产品或业务领域创建多个语义层。除非用户明确要求跨产品语义层，否则不要将无关的产品领域合并到一个宽泛的语义层中。

证据与交接

Data Analytics 插件文件使用通道占位符，例如 ~~structured_data，代表该类别中可用的任意工具、连接器、MCP 服务、插件技能、粘贴的结果、上传的文件或架构说明。已配置的应用及其类别位于此插件的 .app.json 中；应将其视为权威映射，用于确定哪些已配置的应用可以满足各类别的需求。其他可发现的应用、自定义 MCP 服务和可调用工具，只要能可信地提供等效信息，也可以满足某个类别的需求。当所需的连接器、插件、MCP 服务或事实来源通道不可用时，请遵循“来源访问防护规则”。当可选通道不可用时，请根据粘贴的查询结果、上传的文件、SQL 片段、截图、架构说明或其他已审核的证据继续；如果这一缺口会实质性影响答案，请标明。

来源规则：

• 在编写 SQL、笔记本代码、仪表板、报告或结论前，先收集事实来源背景信息。
• 如果笔记本能显著提高可审计性，则在执行新的 SQL、Python、统计分析、建模、来源核对或非简单指标计算时，优先使用可复现的笔记本。
• 在最终成果或支持性说明中保留相关 SQL、脚本、查询永久链接、输出、来源链接和注意事项。
• 将查询溯源信息与面向用户的答案分开。除非用户明确要求查看、编写、审核、调试或接收 SQL 或查询方法，否则不要在最终聊天回复或面向读者的报告正文中粘贴或复现来源 SQL。
• 对于常见的数据问题，先给出答案、证据和重要注意事项。将完整 SQL 保存在 source.query.sql、来源弹窗、查询永久链接、笔记本或查询文件，或支持性说明中；在面向用户的交接内容中提供来源永久链接或来源操作即可。

交付界面边界：

• 即使用户不希望渲染 MCP 小组件或 MCP 成果，启动流程也必须正常运行。在这种情况下，通过选定的聊天、笔记本、SQL、HTML、BI、Streamlit、电子表格、幻灯片或其他非 MCP 界面继续，并将来源说明保存在该界面常用的支持性成果中。
• 对于报告模式的工作，$build-report 负责选择 MCP 或 HTML。对于其他 MCP 小组件或成果界面，请遵循所选界面的规则；在制作特定于小组件或应用的成果前，先阅读 ../../src/analytics-app-core.md。
• 在 web_work_mode 中，根据路由策略，MCP UI 渲染应视为不可用，即使能看到 MCP UI 工具也不例外。在 Web Work Mode 下，不要调用 Data Analytics MCP UI 工具进行交付，也不要声称 MCP 工具结果已在上方渲染。此限制不妨碍将 MCP 服务用作数据来源。
• 如果 mode = work_mode 已明确成立，且 surface 未明确标记为 codex_desktop，则对报告和仪表板界面应用相同的 MCP UI 交付限制。不得将未知的界面分类视为渲染 MCP 应用成果的许可；应选择 HTML、已连接的 BI 或其他非 MCP 界面。
• 不得在任何面向用户的界面中泄露隐藏推理、凭据、秘密、可直接识别个人身份的联系或支付标识符，或未经验证的计算结果。分析需要时，可以包含已审核的客户、账户或公司名称。
• 一旦分析在内嵌或仪表板流程中确定使用某个来源表，只要安全，就应通过所选界面的常规预览机制提供一个小型、确定性的预览。
• 如果预览不安全、不可用或受访问权限限制，应简要记录原因，并根据架构、文档或其他已审核的证据继续。

完成门槛

报告完成情况：

• 一旦报告模式的分析得出发现，在生成渲染后的 MCP 应用报告或 HTML 报告，或记录具体的渲染阻碍之前，本次运行都不算完成。不要默默降级为聊天文本、笔记本、零散图表或内嵌小组件。
• 报告运行必须通过 $build-report 恰好选择一种报告交付模式。
• 遵循 $build-report 的确定性呈现界面规则：Codex 桌面端默认使用 mcp-app；明确识别为 Web Work Mode、没有明确 Codex 桌面端呈现界面的部分 Work Mode 信号，以及不支持 MCP 应用报告渲染的运行时，使用 html；未知运行时默认使用便携的 html；只有在用户明确要求或下游转换需要，或 MCP 尝试确实失败后，桌面端才使用 html。
• 不要只以内嵌/聊天摘要或 localhost URL 结束。将聊天摘要视为进度更新。
• 如果跳过了必需的交付物，请在最终交接中明确说明遗漏原因。
• 所有选定的 HTML 报告路径都必须遵循 $build-report 打包的 Recharts 运行时契约，并提供可读的同数据静态回退方案。这包括 Codex 明确要求的 HTML、Web Work Mode，以及用于转换为 PDF、Google Docs 或 Google Slides 的 HTML；交付的 HTML 不得依赖旁置图表文件。
• 如果报告包含图表、证据表或自定义可视化内容，请在嵌入前满足 $visualize-data 的图表契约并完成 QA。

最终审核：

• 通过打开、阅读、渲染或其他方式检查生成的成果。
• 根据分析所依据的权威来源，核查有来源支撑的结论。
• 若尚未解决的缺口或注意事项会实质性影响结论，请予以说明。
• 确认已阅读并遵循所有选定的主要工作流技能。如果跳过了某项主要工作流，请在最终交接中说明原因。不要将语义层查询、笔记本、验证流程、可视化或报告成果视为满足主要工作流契约。
• 如果本次运行被归类为 report，在下游 $build-report 契约通过或被明确标记为受阻之前，不要结束任务。
• 如果选定的渲染界面不安全、不可用、体积过大，或在针对性重试后仍失败，请通过其他合适的界面继续分析，并在进度更新或最终交接中简要说明原因。

技能

design-kpis

对于目标、主要 KPI、驱动指标、护栏指标、记分卡、衡量计划以及发布或实验成功标准，请使用 $design-kpis。

kpi-reporting

对于 KPI 更新、记分卡、业务评审、高管指标摘要、目标或进度解读，以及面向管理层的绩效分析，请使用 $kpi-reporting。如果更新必须解释 KPI 变动原因，请添加 $metric-diagnostics；除非用户明确豁免或选择了其他主要成果类型，否则应通过 $build-report 完成最终解读。

market-sizing

对于 TAM/SAM/SOM、市场机会、支出或收入池、客户数量、销量、商业潜力以及敏感性模型，请使用 $market-sizing；除非用户明确豁免或选择了其他主要成果类型，否则应通过 $build-report 完成最终规模估算答复。

metric-diagnostics

对于识别指标在特定时间段、基准或细分群体对比下的变动驱动因素、排除测量误差、按确定性标注发现，请使用 $metric-diagnostics，并通过 $build-report 完成最终报告。

product-business-analysis

对于分析产品或业务数据及背景，以支持提出建议的决策，请使用 $product-business-analysis。如果建议依赖于已验证的指标变动，请添加 $metric-diagnostics。

analyze-data-quality

对于数据新鲜度、粒度、行数、空值、重复项、架构漂移、关联异常、离群值、回填，以及来源或仪表板间的数据不一致，请使用 $analyze-data-quality。

build-dashboard

使用 $build-dashboard 构建分析仪表板、记分卡、监控页面、BI 视图、Streamlit 仪表板、MCP artifact 仪表板、BI 平台仪表板，并执行仪表板 QA。

build-report

使用 $build-report 根据用户请求构建恰好一个合适的持久化报告界面；如果分析适合使用数据可视化，则加入数据可视化。

report-to-google-doc

使用 $report-to-google-doc 将现有的本地 HTML 报告转换为精美的原生 Google Doc。

report-to-google-slides

使用 $report-to-google-slides 将现有的本地 HTML 报告转换为精美的原生 Google Slides 演示文稿。

report-to-pdf

使用 $report-to-pdf 将现有的静态 Data Analytics 报告导出文件转换为经过验证的 PDF 成品。

gather-business-context

使用 $gather-business-context 收集文档、仪表板、聊天记录、规划笔记、发布或实验材料、权威信息页、负责人、事件、路线图、GTM 或客户背景，以及先前的决策。

jupyter-notebooks

使用 $jupyter-notebooks 创建、编辑并验证可复现的笔记本，用于 SQL、Python、统计分析、建模、群组或漏斗分析、数据质量检查、实验、市场规模测算、诊断和报告支持。

validate-data

使用 $validate-data 对方法、数据源选择、SQL 或查询逻辑、计算、可视化完整性、注意事项，以及结论是否有证据支持进行 QA。

visualize-data

使用 $visualize-data 为报告、仪表板、演示文稿、笔记本、记分卡、趋势、分解、漏斗、群组、分布、不确定性和高管 KPI 解读设计、实现并 QA 图表。

create-data-context

使用 create-data-context 进行语义层的设置和维护。普通的 Data Analytics 工作无需预先保存数据上下文设置。