nimble-databricks-data-products

Databricks 上的 Nimble — 数据产品构建器

将类似 pricing analysis on dog products from walmart and amazon 的自然语言需求转化为可用的 Databricks 数据产品： 发现 Agent → 将实时网页搜索数据摄取到 Delta → 构建仪表板和/或应用 → 交付链接。 无论是快速演示，还是真正可复用的数据产品，都能胜任。

你是编排者。Databricks 的机制交由官方 databricks-* 技能处理（参见 references/databricks-skills.md）；本技能负责 Nimble 衔接和缺失部分 （Agent 发现、从 Agent 摄取数据、AI/BI 仪表板 JSON、品牌设计）。

黄金规则

• 先发现，不要想当然。 使用 nimble_agent_list() 读取 Agent 名称，使用 nimble_agent_describe('<agent>') 读取输入参数，并通过探测一次调用（to_json(parsing[0])）读取输出字段——切勿凭记忆硬编码（Amazon 搜索使用 keyword，而不是 query）。
• 先探测，再扇出调用。 每个来源先调用一次，了解其本地化标志、字段名称和值格式——不同来源的返回结果各异（有些返回数字价格，有些返回带币种的字符串）。
• 每次 Statements API 调用只执行一条语句。 一次调用中使用多个以 ; 分隔的语句会导致解析错误。
• 每次 Bash 调用都会启动一个全新 shell。 环境变量和 cd 不会保留——请内联设置。参见 references/preflight.md。
• 快速失败，然后确认。 先运行 Phase 0 预检；推荐一个 warehouse 和可写 schema，然后在写入前征求确认。
• 始终询问交付内容。 Table / +dashboard / +app 是每次运行时的选项。
• 始终启用品牌设计，并保持中性。 “Powered by Nimble” + 浅色主题 + 黄色点缀。参见 references/branding.md。
• 保留生成的内容。 不进行清理。
• 展示工作成果和核心结论。 最后给出 URL 和一句话洞察（例如价格差距）。

工作流

将这些步骤记录为待办事项，确保一项不漏。

Phase 0 — 预检（只读，快速失败）

通用检查请参考 databricks-core 技能。

1. databricks current-user me → 确认身份验证，并记录用户名（用于默认 schema）。
2. 查找处于 RUNNING 状态的 SQL warehouse：databricks warehouses list。优先使用已处于 RUNNING 状态的 warehouse；如果没有，请提出启动一个。
3. 集成检查 — 确认以下内容存在： nimble_integration.tools.{nimble_search, nimble_extract, nimble_agent_run, nimble_agent_list, nimble_agent_describe}。 快速检查：databricks functions list nimble_integration tools。 如果缺少 → 停止，并按照 references/install-nimble-integration.md（Nimble cookbook）引导用户完成安装。不要尝试自动安装。
4. 推荐并确认目标：一个 warehouse 和一个可写的 catalog.schema （默认值为 users.<username>）。验证其是否可写——某些共享 catalog 不允许 CREATE TABLE。 提出推荐方案，并在写入前让用户确认或修改。

详细信息和准确命令：references/preflight.md。

Phase 1 — 解读需求并澄清（AskUserQuestion）

将需求解析为：领域/实体 · 搜索词 · 来源 · 分析目标。 然后一次性调用 AskUserQuestion 提出以下问题：

• 交付内容 — 始终询问：table / table + dashboard / table + dashboard + app。
• 来源 — 确认匹配的 Agent（例如 Amazon + Walmart SERP）。
• 数量 — 默认约 8–10 个搜索词，每个来源约 100+ 行。

保留需求的原意（“分析目标”）——它将决定 Phase 4 所用模板和核心结论。

阶段 2 — 发现 Agent + 映射统一架构

参见 references/nimble-agents.md。

1. 通过 SQL 调用 nimble_agent_list()，按来源／领域关键词筛选。
2. 对每个选定的 Agent：调用 nimble_agent_describe('<name>') → 读取其输入参数（必填项、 确切名称、本地化／分页标志）。输出字段取自 §2.5 的探测，而非此处。
3. 设计一张统一表，包含 source 列和标准化核心字段 （product_name, price, currency, rating, review_count, brand, url, …），只保留所选 Agent 实际输出的字段。多来源比较依赖这些共享列。

阶段 3 — 摄取（控制表 + 一次集合式调用）

完整 SQL 参见 references/nimble-agents.md。通过控制表驱动摄取，而不是为每个关键词创建文件 — 这样可复现且易于扩展（添加一行后重新运行）。 0. 先对每个来源探测一次调用（快速失败）。 扩大调用范围前，对每个来源运行一次 nimble_agent_run，并检查：状态、实际字段名称、本地化标志，以及价格能否正常转换为类型。这能在约 40 秒内发现 Walmart 这类意外情况（本地化、货币字符串价格、product_price 而非 price），而不是等完整轮次白费后才发现。这是收益最高的一步 — 参见 nimble-agents.md §2.5。

1. 创建控制（查询）表 <schema>.<table>_queries（source, agent, keyword, params_json, localization, enabled），并为每个（来源 × 词条）填充一行。params_json 使用各 Agent 的实际参数名称（来自 input_properties）；按 Agent 设置本地化（例如， amazon_serp 为 true，walmart_serp 为 false）。
2. 创建统一结果表（包含 source 列 + 标准化核心字段 + raw VARIANT）。
3. 运行一条 INSERT，通过针对控制表的相关 LATERAL 连接调用 nimble_agent_run(q.agent, q.params_json, q.localization)，并使用 /*+ REPARTITION(N) */ 提示（N ≈ 已启用行数，保持适中 — 并行度过高可能触发 API 速率限制），使 Agent 调用并行运行。这是一条很长的语句 → 使用 bash scripts/ingest.sh <WH> ingest.sql 异步运行。
4. 对照控制表核验（LEFT JOIN）：某个词条若没有匹配到商品，会返回空结果；而相关 LATERAL 会丢弃空行 — 因此需要核验，确保覆盖了所有来源。如果某个来源显示为 0，请在构建前重新检查其本地化标志（按 Agent 设置）和类型转换；诊断顺序参见 nimble-agents.md §6。

第 4 阶段 — 构建交付物

从匹配到的 Agent 的 vertical/entity_type 中选择一个模板：

垂直领域	仪表板/应用形式
电商（SERP/PDP/CLP）	KPI；按来源/关键词统计商品列表和平均价格；赞助内容占比；价格与评分散点图；带打开链接的商品表格；多来源 → 对比条形图 + 尽力而为的商品级价格差距
社交	按账号/帖子统计数量和互动；热门内容表格；点赞数/粉丝数分布
房地产	价格和每平方英尺价格；按位置统计房源；卧室/浴室数量细分
地图 / 本地	平均评分；评论数；地点表格
LLM / AEO	来源/答案覆盖情况；声量占比；引用表格
回退	KPI + 2 个分类条形图 + 原始表格（适用于任何 output_schema）

**对比深度（混合）：**始终构建汇总/分类对比；此外尽力尝试跨来源进行商品级匹配（规范化品牌和关键 token）。如果存在可信匹配，则添加“同款商品价格差距”视图；否则保留汇总对比，并注明商品级匹配结果不够可信。

• 仪表板 → 使用 scripts/build_dashboard.py（精简规格 → 有效的 serialized_dashboard，创建并发布）。它内置了所有 Lakeview 注意事项。请阅读 references/dashboard-cookbook.md 了解规格格式和示例。
• 应用 → 遵循 references/app-cookbook.md（由 databricks-apps 负责脚手架搭建/部署；添加 Nimble 专属 SQL、品牌设置，以及数字字符串/浅色模式注意事项）。
• 品牌设置 → references/branding.md（始终应用）。

第 5 阶段 — 验证、交付并分享

• 发布仪表板 / 确认应用处于 RUNNING 状态；收集 URL。
• 总结构建的内容和核心洞察（对比结论）。
• 提出分享仪表板/应用链接——如果有 Slack 或 Notion 连接器，可提出在那里发布（Slack = 链接 + 核心结论；Notion = 简短的带日期页面）。提一次即可；不要反复催促。
• 建议后续步骤，例如使用相关技能 competitor-intel / company-deep-dive，了解已发现品牌的业务信号；或使用 nimble-web-expert 进行一次更深入的数据抓取。
• 提供迭代选项（添加图表、商品级匹配、主题设置、定时刷新任务）。

参考索引

• references/databricks-skills.md — 各阶段应使用哪个官方 databricks-* 技能。
• references/install-nimble-integration.md — 集成检查失败时的设置方法。
• references/preflight.md — 身份验证、数据仓库、可写架构发现（精确命令）。
• references/nimble-agents.md — 发现、架构映射、数据摄取 SQL + 注意事项。
• references/dashboard-cookbook.md — Lakeview JSON 示例 + 所有注意事项（权威参考）。
• references/app-cookbook.md — AppKit 演示应用衔接 + 注意事项。
• references/branding.md — “Powered by Nimble”、徽标、颜色。
• scripts/ingest.sh — 异步语句分发 + 轮询。
• scripts/build_dashboard.py — 精简规格 → 创建并发布仪表板。
• assets/nimble-logo.png — 用于应用品牌设置的 Nimble 标志。