Dashboard Builder 是 DB-GPT 生态中的一项技能，用于从数据助手中选定的数据库或已注册的多文件表格数据集出发，规划、生成、修复并安全修订可复用的数据仪表盘。
用途 当用户要求基于数据助手中选定的数据库创建、修订或修复可复用的数据仪表盘时使用本技能。一个被 DB-GPT 注册为单一 SQLite 数据源的有界 CSV/Excel 上传组，也算作选定的数据库；应针对该持久化数据源使用 SQL 工具。本技能负责编排工作流，持久化、SQL 校验、查询执行、修订检查与发布安全由确定性工具负责，不应在自由推理或脚本中重新实现这些职责。
前置条件 必须在数据助手中选定一个数据库；已注册的多文件上传数据集满足此条件。只能使用选定的数据库，绝不虚构其他数据源。若未选定数据库，应请用户先选择并停止。回复语言应与用户一致。
新建仪表盘：先规划 仅使用 sql_query 进行最少量只读探查，以了解表关系、字段类型、数据粒度、日期范围和有价值的类别值。一个规划回合最多使用八次探查查询。若校验反馈已指出计划中错误的字段，应直接修正计划，而不是再开始一轮探查。对每个候选时间列使用服务器的时间探查证据：存储类型、实际样本值、推断格式和来源去重计数。原始去重日期与去重日历月是不同的粒度。使用观察到的格式选择方言适配的解析方式，保留完整年份；不要假设文本日期能被原生日期函数接受。模糊、混合、不可用或采样的证据不是来源范围的精确事实。
当选定来源来自多个上传文件时，规划前需清点每个来源表：记录其来源文件/工作表、行数、列、可能粒度、空值和重复键计数；检查 __dbgpt_dataset_manifest 以获取来源信息；将 __dbgpt_relationship_candidates 仅视为提示，绝不视为已确认的连接；用去重键重叠、未匹配行以及一对一/一对多/多对多基数检查验证候选键；绝不因为列匹配就拼接表，也绝不在原始粒度连接两个事实表以致度量被放大。应先将子侧聚合到预期的仪表盘粒度。
保持用户请求的范围：每个列出的分析项对应一个组件；不要添加额外的 KPI 卡片或筛选器。对于宽泛请求，从 3–4 个核心组件开始。仅在用户要求或对所述决策必要时才添加筛选器。若请求的周期没有行且预期为空表，将该表的 expected_data_points 设为 0，并保留精确的请求周期。调用 plan_dashboard 时只传一个 plan 参数，包含无 SQL 的计划对象（也接受 JSON 编码字符串）。遵循已注册工具清单中生成的 DashboardPlan 校验形状，包括：业务主题与预期决策；指标名称字符串数组，并在业务文本中描述其含义；维度字符串数组及合适粒度；带真实默认值和从数据中发现选项的筛选器；具有稳定 id、类型、标题、业务问题、指标和维度的组件。布局模板族已推迟，不属于本版本。不要在新计划或修订计划中包含 layout_template。改用单个组件的宽/高提示和业务布局理由。业务模板仍定义分析问题，而非布局或视觉主题。
以 terminate 结束该回合。用户必须先看到并确认计划，然后才生成组件 SQL。绝不在规划回合调用 create_dashboard_draft。绝不用一次性 HTML 报告替代此工作流。
已确认计划：生成查询 当消息包含权威的 [[confirm-dashboard:ID]] 标记时：使用持久化的计划契约及其组件 id，完全一致。调用 create_dashboard_draft 时传入提供的 dashboard id 和预期 revision。每次调用最多提交两个组件。服务器会暂存这些有界批次，并在所有计划组件都出现后原子地创建草稿；当它报告缺失组件 id 时，下次只发送那些缺失的组件。
为每个组件生成一个参数化、只读查询。复用注入本回合的时间证据，而不是根据列名或缺失的先前探查结果假设格式。它是上下文证据，不是服务器对 SQL 业务语义的保证。为每个查询声明类型化输出字段和兼容的图表编码。将每个全局筛选器映射到命名 SQL 参数。filter_parameters 的键是已保存的筛选器 id；值是参数名字符串，或日期和数字范围的 {start_parameter, end_parameter}。输出字段是 {name, type} 对象，不是字符串或字段名映射。当计划有筛选器时，每个组件都需要发布绑定。冻结查询必须在声明的 max_rows（默认 1000，最大 5000）内返回其筛选字段和分组/度量字段。如有需要，在完整筛选/分组粒度上聚合，同时保留度量；绝不截断来源行或对平均值再平均。发布输出列必须与组件输出字段匹配。参见生成的 DashboardQueryDraftRequest 形状。
若工具参数被报告为截断或 JSON 格式错误，不要重发完整负载。最多用两个组件重试，以便服务器暂存。若某组件未通过服务器校验，仅对失败组件调用 repair_dashboard_draft。保留成功的组件。以 terminate 结束，并说明哪些组件成功或仍需处理。
筛选规则 日期和数字范围使用单独的 start 和 end 参数；绝不将双值数组绑定到标量相等。标量选择可使用空值保护，例如 (:category IS NULL OR category = :category)。多选参数只能出现在 IN 或 NOT IN 中，例如 store_id IN (:store_ids)。不要为多选列表添加 IS NULL 保护。后端会将空列表规范化为无限制。绝不将用户值拼接到 SQL 中，也不要用 INSTR/LIKE 和逗号分隔字符串模拟列表成员关系。已批准且 expected_data_points: 0 的表允许真正的空结果。绝不删除其谓词、更改其年份或插入虚拟行使其非空。其他意外空查询仍属可修复失败。
修订或修复 [[revise-dashboard-plan:ID]] 标记表示用 revise_dashboard_plan 替换待处理的无 SQL 计划，然后再次停止等待确认。对现有已生成草稿中的查询或编码失败，使用 repair_dashboard_draft。仅对用户明确要求的有界更改使用 modify_dashboard_draft。先在同一回合调用 load_dashboard_draft 获取当前 schema 和 revision。保持 dashboard id、数据源、所有权和 revision 契约。绝不静默应用需要用户审查的 AI 更改。
选择感知标注 当消息包含权威的 [[dashboard-annotation:ID]] 标记时：不要重新加载本技能或调用 load_tools；服务器已选择此工作流并注册了其有界工具。对于 [修改组件] 标注，使用消息中确切的 Dashboard 和标注 id 调用 propose_dashboard_change。通过稳定 id 而非数组索引来定位组件和筛选器，并只提出最小更改。对于 [指标解释] 或 [异常分析]，仅加载持久化的 Dashboard 上下文并解释。确定性异常证据是权威的：绝不运行 SQL、重新计算结果、调用提议/变更工具，或更改异常、正常或不确定的结论。在解释或已验证的提议后停止。修改提议仍须由用户在 Dashboard UI 中应用或拒绝；绝不静默保存。
完成检查 在报告成功前，依赖工具观察验证：所有请求的组件都存在；每个组件查询都通过了只读和字段映射校验；筛选器有真实选项和参数映射；多表度量在声明粒度上与来源总计对账，连接诊断显示没有无法解释的扇出；失败组件被报告而不丢弃成功组件；结果是可恢复的 Dashboard 草稿，而不仅是文字或图片。
如需详细的阶段契约和示例，可在需要时阅读 references/workflow-contract.md。