report-builder

报表构建器

业主只需描述一次报表。你负责构建并运行它，然后保存定义，这样就无需再次描述。

业主一直在三个仪表盘中手动提取数字，并自己试图找出其中的规律。这项工作的目标是终结这种状况。

第 1 步 — 检查现有定义

在做任何其他事情之前，先阅读 reference/saved_reports.md，检查该报表是否已存在。同时检查工作目录中是否有 report-definitions.md——当 skill 文件夹不可写时，定义会保存在那里（参见第 7 步）。

如果业主说“和上次一样的报表”“运行每周那份”，或提到你已有定义的报表名称，直接跳到第 4 步运行。对于业主已经定义过的报表重新进行访谈，是最容易让这个 skill 显得失灵的做法。

如果没有匹配项，继续下一步。

第 2 步 — 将描述转化为规格

业主的描述通常比较随意，例如：“每周一，按门店查看销售额与去年同期对比、应收账款账龄和人工成本占比。”这句话包含四项独立的决策。请使用 reference/report_spec.md 中的格式，将它们整理为规格：

• 指标 — 每个指标的名称、计算公式及数据来源
• 分组 — 按门店、产品、客户、渠道、销售代表分组
• 对比 — 与上一期对比、与去年同期对比、与目标对比
• 周期 — 每次运行所覆盖的时间窗口
• 频率 — 一次性、每周、每月、每季度

能够合理推断的内容请直接推断。“按门店的销售额与去年同期对比”已经给出了指标、分组和对比方式，无需再追问这些。只询问确实存在歧义的内容，并且一次性集中提问，而不是逐个提问。

几乎每次都值得问的两个问题是：

• 每次运行覆盖哪个周期——自然月、近 30 天，还是月初至今？
• 像“人工成本占比”这样的数字，是以收入还是以总成本为基准计算的？

这两点一旦出错，就会得到一份看似正确、实则悄悄出错的报表，这比多问一句的代价更严重。

第 3 步 — 确认规格，仅此一次

将整理好的规格以简洁的代码块形式展示给业主。请业主确认一次，然后开始构建。不要逐项带业主过一遍规格——他们只用一句话描述了这份报表，期望得到的是一次确认。

如果业主做出更正，直接应用并开始构建。不要再次请求确认。

第 4 步 — 拉取数据

在单个并行批次中发起所有数据源调用。指标与工具的对应关系参见 reference/data_sources.md。

同时尝试以下数据源：

• 总账 — MYOB、NetSuite、QuickBooks、Xero 或 Zoho Books，以已连接者为准；同类对象参见 ../../shared/connector-neutrality.md。包括损益表项目、收入、费用、应收账款账龄、应付账款、按类别和地点的拆分。MYOB 仅提供损益表、应收账款和应付账款数据，且只回溯三个财政年度。如果连接了两个总账，请询问哪一个是权威数据源（source of record），并以该数据源的总计为准
• HubSpot — 交易、阶段、负责人、成交日期、管道金额
• PayPal、Square、Stripe — 结算、手续费、退款、交易明细
• Shopify — 订单、SKU 级收入、履约状态
• Ramp、Expensify — 卡支出和费用明细。在此两者均作为读取数据源使用；Expensify 为只读搜索

如果某个数据源出错或没有返回任何结果，记录下来并继续。切勿因为某一个连接器出问题而阻塞整份报表。

完全没有连接器是受支持的路径，而非失败。 请业主提供 CSV 或 XLSX 导出文件，读取后根据文件构建完全相同的报表。直接说明情况：“我没有检测到已连接的数据源。请从你的系统中导出销售报表并放到这里——我会据此构建同样的报表。”工具分散的业主通常就处于这种模式，而报表质量同样可靠。

第 5 步：计算并做合理性检查

计算规格中提到的每一项指标。展示结果之前，先检查这些结果。阅读 reference/gotchas.md，了解实际中会出现的故障模式。

以下检查能发现真正的错误：

• 周期边界。 当月未完成的部分与完整的上月相比，结果总会显得像是暴跌。要么进行同口径比较，要么明确标注该周期为部分周期。
• 重复计算。 Shopify 订单与其对应的 Stripe 结算是同一笔销售。如果两个数据源都已连接，请选定其中一个作为收入来源，并注明选择了哪一个。
• 空分组。 本周期没有销售的地点应显示为零，而不是直接消失。行的消失会让人误以为是数据问题。
• 合计对不上。 如果分组行的加总与总计不一致，请明确说明，而不是发布一个无法自圆其说的数字。

第 6 步：交付

始终交付两份成果，且顺序固定。

聊天摘要排在最前。 遵循 reference/output_template.md。开头说明发生了什么变化以及这意味着什么，而不是直接倾倒表格。店主要的是报告，是为了做决策，而不是一张电子表格。

写作规则，与本插件中所有报告类技能一致：

• 数字在前，文字在后。不要写“销售表现强劲”，而要写“USD 43,200，同比增长 8%”。
• 每个数字都要附带对比基准。没有基准的数字等于没有洞察。
• 点名异常值。“Portland 下降 22%，是唯一低于去年的门店”比“结果喜忧参半”更有价值。
• 摘要中最多列出三条发现。其余内容放在工作簿中。

然后是 XLSX。 每个指标组一个标签页，摘要标签页放在最前，原始拉取数据放在最后一个标签页，便于店主核对计算。用脚本生成，不要手工制作。

接着是报告页面，依据店主保存的输出偏好生成，绝不默认输出 markdown 文件。 检查 ## Business context 区块中的 Output preference（共享样式指南规则，../../shared/artifact-style.md）：

• 可视化成果（默认）： 以 HTML 页面呈现报告，采用统一风格。每个核心指标是一个统计卡片，其对比信息作为上下文行；按分组（地点、产品、销售代表）的行放在表格中，数字右对齐并使用等宽数字；任何与目标对比的指标都带有状态标签（达标为良好，略有滑落为警告，未达标为严重）；三条发现各自放在独立面板中，置于页面顶部；“n/a”来源统一放在一行低调的页脚中。这是对聊天摘要和工作簿的补充，而不是替代。
• docx / md / notion / canva 偏好： 以对应形式交付相同内容：DOCX 或 markdown 文件；通过连接器创建的 Notion 页面（指定目标位置，绝不覆盖已有页面）；或通过 Canva 连接器创建的 Canva 文档（每次运行新建一个设计，并以日期命名；表格转换为列表）。如果未连接 Notion 或 Canva，则回退为可视化成果，并说明原因。XLSX 仍随同交付。
• Best for 技能： 使用可视化成果。报告是在屏幕上阅读的，并且需要逐周对比。

第 7 步：保存定义

将规格追加到 reference/saved_reports.md，并记录创建日期和周期。正是这一步让报告可以周期性运行，而不是一次性的。

如果该文件无法写入（在大多数已安装的运行环境中，技能文件夹是只读的），则将定义写入店主工作目录中的 report-definitions.md，并说明保存位置。定义保存失败却没有任何提示，与从未保存是同一类错误。

如果店主要求了周期，请用一行话确认：“已保存。我会在每月第一个周一运行此报告。”排期是本技能自带的功能，无需额外指令。

运行之后

用一行话说明：报告已运行，定义已保存。然后给出最相关的一个后续步骤，附近最多再提两个其他选项：

• "每周报告包，按计划执行" 运行 /report-pack，按固定节奏为本次结果补充背景信息。
• "业务现在怎么样？" 运行 business-pulse，给出这些数字背后的整体情况。
• "现金流预测" 当报告引出现金问题时运行 cash-flow-snapshot。

最多提供三个选项。绝不重复本次会话中业主已经拒绝过的选项。

不要做的事

• 不要就业主已经定义过的报告再次访谈业主。 每次都要先检查 saved_reports.md。
• 不要请求许可才去拉取数据。 该技能已被调用，直接运行。
• 不要编造数字。 如果某个数据源没有返回结果，就写 "n/a" 并注明数据源名称。在业主会转交给银行的报告中，看起来合理的猜测数字是严重失误。
• 不要以表格开头。 摘要才是核心成果；工作簿只是附录。
• 不要把 "没有连接器" 视为阻碍。 CSV 路径是一等公民模式。

参考文件

• reference/report_spec.md — 规格格式，附带完整示例
• reference/data_sources.md — 指标到连接器的映射，含备用方案
• reference/output_template.md — 命令行聊天摘要与工作簿的确切结构
• reference/saved_reports.md — 已保存的报告定义，随时间持续追加
• reference/gotchas.md — 会导致报告看似正确实则错误的故障模式

使用未列出的工具

本技能中提到的连接器是经过测试的路径，并非唯一选择。如果业主希望此流程使用尚未连接或未列出的工具，可以提供 build-connector。它会先检查连接器目录，否则通过 Zapier 连接，绝不直接对原始 API 手工开发。连接建立后，该工具与其他可选连接器一样加入本技能，并遵循同样的审批关卡。