build-dashboard

相关技能

仅当仪表板工作明确要求保存数据上下文，或创建、更新、检查或修复语义层时，才使用 $create-data-context。

当仪表板指标不一致，或数据源的新鲜度、粒度、联接或定义可能影响可信度时，使用 $analyze-data-quality。

构建仪表板

当用户需要的是仪表板，而不是报告、仅限笔记本的分析、电子表格或临时聊天摘要时，使用此技能。优秀的仪表板以摘要为先、以图表为主，便于快速浏览，并围绕受众需要监控、了解或采取行动的内容进行组织。

如果缺少的信息会实质性改变仪表板需求说明、分析或建议，请向用户澄清。否则，做出合理假设，说明假设，然后继续。

此技能负责仪表板需求说明、交付模式选择、指标定义、数据源预期、布局逻辑、仪表板 QA 和交接。特定交付方式的具体操作由选定的仪表板规范负责。

技能配置

运行时交付路由

如果已明确确认 surface = chatgpt_web 且 mode = work_mode，则不要选择 Data Analytics MCP 工件应用，也不要加载其仪表板规范。如果已明确确认 mode = work_mode，但 surface 未知或未明确确认为 codex_desktop，出于安全考虑，也采用相同的非 MCP 交付规则。若用户选择了已连接的 BI 目标，或该目标显然适用于所请求的仪表板，则使用它；否则构建可移植的 HTML。仅当用户明确要求使用 Streamlit 时才使用它。MCP 服务和其他可调用工具仍可作为有效数据源。

数据源发现与验证

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

1. 探索所有可能的数据源。 搜索每个可能包含任务相关数据或会改变解读的已连接或已提供数据源。在每个结构化数据源中，针对相关架构、数据集、表、视图、模型和指标，执行最新的目录或元数据发现。已知的数据源、表、仪表板和语义映射只是起点，而非终点。
2. 比较重复数据与冲突。 当数据源内容重叠或存在分歧时，比较其所有权、新鲜度、定义、粒度、覆盖范围和直接性。使用最佳的权威数据源，或在需要时组合互补的数据源。指出实质性冲突，说明所选数据源为何作为依据，并在得出结论前通过实时读取验证所选数据。

数据源访问护栏

在查询数据源、构建工件或得出结论之前，先确定答案是否需要特定的真实数据源。

如果无法访问必需的数据源，就停止该路径。告知用户需要哪个数据源，请用户开放该数据源或提供经过审核的替代方案，不要将较弱的替代来源视为等效来源。

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

工作流

1. 明确仪表板需求

了解谁会使用仪表板、需要衡量或监控什么、哪些指标重要、仪表板应呈现在什么界面，以及哪些限制可能影响构建方式。

仅澄清会实质性影响仪表板的输入，例如主要受众、衡量目标、指标范围、交付界面、刷新预期、必需筛选条件、访问限制或共享需求。判断仪表板主要用于状态监控、定期运营审查还是分析探索，因为这会影响布局、筛选器设计和验证标准。

当仪表板用途、指标定义、运营背景、受众预期或现有仪表板惯例不够明确，无法妥善设计仪表板时，使用 $gather-business-context。

2. 选择交付形式

选择最符合用户需求且当前可访问的首选交付形式。如果用户指定了目标位置或形式，则优先使用用户指定的形式，而不是默认顺序。

对于已确认的网页工作模式，或任何已确认工作模式信号但没有已确认 Codex 桌面端形式的情况，请按以下顺序选择：

1. 如果用户选择了已连接的 BI 工具，或该工具明确负责目标位置，则使用该工具。
2. 否则，使用 HTML 交付仪表板。

在没有已确认 Codex 桌面端形式的工作模式下，即使 MCP 工件应用的工具可见，也不要选择该应用。对于其他所有环境，请按以下默认顺序选择：

1. 默认使用已连接的 BI 工具。使用当前请求、当前运行上下文或用户明确偏好中指定的 BI 形式；如果未指定，则先查找可用的已连接 BI 解决方案，再选择其他形式。
2. 当无法使用已连接的 BI 工具、BI 工具对于当前请求过于复杂，或用户需要在 Codex 内使用精简的分析仪表板时，使用 MCP 工件应用。
3. 当 BI 和 MCP 都不合适，且用户需要可移植的静态仪表板时，使用 HTML。

仅当用户明确提出要求，或必须修改现有 Streamlit 应用时，才使用 Streamlit。

构建前请阅读相应的规范：

• ../../src/analytics-app-core.md，了解共享的 MCP 工件机制、源数据安全、运行时行为和验证辅助工具。
• specifications/bi-platform-dashboard.md，了解 BI 平台仪表板。
• specifications/mcp-artifact-dashboard.md，了解由 MCP 工件应用呈现的仪表板。
• specifications/html-dashboard.md，了解可移植的静态 HTML 仪表板。
• specifications/streamlit-dashboard.md，了解 Streamlit 仪表板。

3. 收集并验证数据

按以下顺序处理数据：

• 在渲染前找到数据源路径。 发现数据源是构建仪表板的必要环节，并非可选的补充工作。确定核心仪表板指标的数据源路径。若仪表板需要从数据仓库或其他结构化数据源获取数据，请使用 ~~structured_data。若仪表板需要业务含义、权威数据源指引、指标定义，或仅凭结构化数据无法获取的需求，请使用 ~~company_docs、~~team_communication 或 ~~dashboards_or_bi 等上下文通道。
• 使用持久可靠的仪表板数据。 在将数据接入仪表板前先验证数据。除非仪表板的用途包含受限范围的明细表，否则应保持最终数据提取结果精简且聚合。避免让最终仪表板依赖临时或草稿表。
• 验证数据可信度。 对于简单明了的仪表板，确认数据源、粒度、时效性以及基本核对结果，确保展示的指标可信。如果数据可信度存在重大风险，例如新数据源、近期回填、复杂联接或结果出乎意料，请使用 $analyze-data-quality。
• 确定时间和上下文锚点。 在选择指标前，先确定仪表板所需的日期锚点、对比窗口、最近一个完整数据日期、数据源覆盖范围或权威依据，例如发布日、事故时段或营销活动期间。如果提示中没有提供，请使用 $gather-business-context。如果仍不明确，只有在这会实质性改变仪表板时才提问；否则应说明假设，并据此设计查询。
• 如果无法获取有数据源依据的数据，则停止。 除非用户明确要求制作模型图，否则不要使用后备、示例、临时或部分受限的数据来渲染仪表板。如果无法获取仪表板核心数据，则停止构建，并告知用户需要哪个数据源或访问权限。如果缺少数据源路径，不要声称仪表板是基于真实数据创建的。

4. 定义指标模型

选择指标。

选择仪表盘指标时，应先对测量对象分类，再为其选择均衡的指标模型。不要使用固定清单。确定哪些指标类别与决策相关，哪些有意排除在范围之外。

将以下指标类别视为提示，而非必需部分：

• 覆盖范围：谁或什么在使用该对象、符合条件的人群、渗透率、激活、采用、覆盖率。
• 体量：事件、使用量、交易、会话、请求、单位、吞吐量、频率。
• 价值：收入、成本、利润率、节省、转化、留存价值、生产力、业务成果。
• 质量：成功、失败、可靠性、延迟、满意度、正确性、安全性、支持负担。
• 深度：重复使用、使用强度、功能组合、工作流完成情况、生产化程度、成熟度、生命周期阶段。
• 构成：细分群体、客户类型、地理区域、渠道、模型／产品／版本、套餐、用例、群组。
• 变化：趋势、增长、季节性、变更前后对比、基准、目标、预测、领先指标。
• 风险与限制：数据覆盖情况、来源时效性、已知盲点、容量、合规性、运营限制。

拓展指标覆盖面，但不要让仪表盘失去重点。

拓展指标覆盖面，确保涵盖与仪表盘测量对象和决策相关的所有类别。默认视图应保持层次分明，而非面面俱到：优先展示主要结果和信号最强的驱动因素，再通过分区、标签页、筛选器、详情表格或辅助视图展示其他相关指标。根据用户的监控或诊断需求，一个选定的类别可以通过一个或多个 KPI、驱动因素、护栏指标或细分项来呈现。

构建仪表盘前，先将选定的类别映射到相应角色：默认视图中的核心指标、用于观察变化和拆解情况的诊断指标、用于辅助解读的护栏指标，以及用于查询或后续跟进的详情指标。

让决策决定核心指标卡片的数量。不要为了凑数或控制数量而将其设为 4 个，也不要套用任何偏好的数量。每张卡片只突出一个独立且与决策相关的主指标。仅在主指标卡片中使用简短的对比信息，例如上一周期的数值、目标或变化量；将独立的次要指标放入各自的卡片、图表、表格、叙述或详情视图。将相互关联的卡片放在同一行；奇数数量也完全合理，因为制品渲染器会以响应式方式平衡各行。

指标设计难度较高时升级处理。

如果上述指标类别梳理仍不足以满足需求，例如仪表盘需要更深入的指标框架、目标设定、正式的 KPI 权衡分析，或需要比此工作流能够安全推断的内容更明确的定义，请调用 $design-kpis。提供仪表盘简介、业务背景、数据来源背景、现有指标定义和约束条件，以确保推荐的指标适合目标受众和使用场景。

保持数据模型一致。

尽可能基于可复用的紧凑数据模型构建，而不是为许多图块编写略有差异的查询。确保卡片、图表和表格采用一致的日期逻辑、筛选条件、维度和指标定义，以便数字能够相互核对。如有可用的选定工具或语义层共享指标定义，请重复使用。

5. 设计仪表板布局

默认视图应在查看者进行交互前就能发挥作用。按从概览到细节的顺序安排仪表板：先展示关键状态或主要 KPI 背景，再展示随时间的变化，接着展示能解释这一趋势的细分信息；需要查询或跟进运营事项时，再将明细表放在页面下方。

只有在全局筛选器能够实质性地更新整个仪表板视图时，才使用它们。优先选择少量高价值控件，而不是密集的筛选面板。仪表板应以视觉内容为主，保持中性：标签简短，指标名称直观，注释精简，并尽量减少主画布上的说明文字。在可见标签和数据新鲜度文本中使用易读的简短日期格式；机器可读的源元数据则保留 ISO 时间戳。

除非仪表板需要时间戳来确保运营精度，否则在可见标签和工具提示中优先使用易读的简短日期格式。

6. 选择合适的图表

当仪表板需要选择图表、进行视觉编码或润色图表时，请使用 $visualize-data。此技能应定义每种图表需要传达什么；$visualize-data 负责详细的视觉设计。

选择能够回答查看者问题的最简单可视化。只有在图表比文本或表格更易于理解趋势时，才使用图表。

只有在直接比较指标有意义时，才将它们放在同一张图表中。否则，应将其拆分到不同的图表、KPI 卡片或表格中。

请按照选定的仪表板规范，满足确切的架构、渲染器和交互要求。

7. 在选定界面中构建并验证

使用选定界面的原生模式进行构建。交付前，检查仪表板能否顺利打开、筛选器是否正常工作、图表是否正确渲染、数字是否一致、访问权限是否说明清楚，以及性能是否可接受。

如果日后难以重新找到数据源或查询路径，请记录下来。

8. 交付仪表板

提供仪表板链接或本地制品路径、数据源或访问方面的注意事项，以及尚待完成的共享或运营步骤。常规检查详情应保留在支持材料中。除非检查失败、无法执行，或产生了与用户相关的注意事项，否则不要在面向用户的交付说明中列出内部检查。对于 MCP 制品仪表板，请遵循 specifications/mcp-artifact-dashboard.md 中的验证和渲染交付规则。

仪表板质量标准

交付前，请确保仪表板可作为测量界面使用：

• 默认视图应在查看者进行交互前回答主要受众的问题。
• 筛选器数量应少、意义明确，并能在其声称控制的各个界面中正常工作。
• 卡片、图表和表格的数据应一致；如有差异，须明确标注。
• 图表应回答清晰的问题，且所用指标应相互兼容。
• 在以图表为主的概览之后，表格应支持查询、比较或运营跟进。
• 指标集合应足以覆盖测量对象：包含相关类别中的主要结果、重要驱动因素、护栏指标和辅助细分信息，同时确保默认视图易于使用。
• KPI 卡片应定义准确：对于由业务定义的指标，应提供足够且清晰可见的说明或邻近背景信息，让读者了解统计内容、统计时间范围，以及使用的分母或资格规则。
• 在相关位置明确展示数据源的新鲜度、访问限制和注意事项。
• 布局、标签和性能应适用于选定的交付模式。
• 遵循选定仪表板规范中的验证和渲染规则。