feat: send report analysis in Feishu cards

.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 *.csv
 *.xlsx
 *.log
+outputs/
 
 task_plan.md
 findings.md

skills/feishu-data-publisher/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feishu-data-publisher
-description: 将本地 CSV、XLS 或 XLSX 数据文件上传并导入为飞书在线电子表格，把链接权限设置为“互联网获得链接的任何人可编辑”，并通过指定飞书机器人将表格卡片发送到目标群聊。用于数据查询完成后发布结果、查找机器人可见群聊、按群名解析 chat_id，或排查飞书上传、导入、权限与群消息问题。
+description: 将本地 CSV、XLS 或 XLSX 数据文件上传并导入为飞书在线电子表格，把链接权限设置为“互联网获得链接的任何人可编辑”，并通过指定飞书机器人将 AI 生成的数据概要和表格卡片发送到目标群聊。用于数据查询完成后发布结果与结论、查找机器人可见群聊、按群名解析 chat_id，或排查飞书上传、导入、权限与群消息问题。
 ---
 
 # 飞书数据表发布
@@ -9,7 +9,7 @@ description: 将本地 CSV、XLS 或 XLSX 数据文件上传并导入为飞书
 
 ## 运行环境
 
-依赖 `httpx`。脚本只读取 `FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`FEISHU_TARGET_CHAT_ID` 和可选的 `FEISHU_TARGET_CHAT_NAME`。不得把凭证写入 Skill、命令参数、输出文件或回复。
+依赖 `httpx`。脚本只读取当前进程中的 `FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`FEISHU_TARGET_CHAT_ID` 和可选的 `FEISHU_TARGET_CHAT_NAME`，不会自动解析 `.env`。项目使用 `.env` 时，执行脚本前先在该项目目录运行 `source .env`。不得把凭证写入 Skill、命令参数、输出文件或回复。
 
 首次使用或权限报错时阅读 [configuration.md](references/configuration.md)。
 
@@ -17,22 +17,30 @@ description: 将本地 CSV、XLS 或 XLSX 数据文件上传并导入为飞书
 
 1. 确认用户明确要求上传并发送飞书；仅查询数据时不得自动产生外部副作用。
 2. 确认结果文件存在，且后缀为 `.csv`、`.xls` 或 `.xlsx`。
-3. 确认目标群。优先使用用户本次给出的 `chat_id` 或群名，其次使用环境变量。群名不唯一时必须停止并列出候选，不得猜测。
-4. 如需只读检查机器人可见群聊：
+3. 发布数据报表前，读取校验后的聚合结果或复用上游查询 Skill 的分析，按“群卡片概要规则”准备 `summary_message`。无法解释业务指标时只陈述可验证事实，不得编造结论。
+4. 确认目标群。优先使用用户本次给出的 `chat_id` 或群名，其次使用环境变量。群名不唯一时必须停止并列出候选，不得猜测。
+5. 如需只读检查机器人可见群聊：
 
    `python3 "$SKILL_DIR/scripts/publish_table.py" --list-chats --name '前端组'`
 
-5. 先执行无副作用预检：
+6. 先执行无副作用预检，并传入实际概要：
 
-   `python3 "$SKILL_DIR/scripts/publish_table.py" report.xlsx --dry-run`
+   `python3 "$SKILL_DIR/scripts/publish_table.py" report.xlsx --message "$summary_message" --dry-run`
 
-6. 用户确认目标和上传意图后执行发布：
+7. 用户确认目标和上传意图后执行发布：
 
-   `python3 "$SKILL_DIR/scripts/publish_table.py" report.xlsx --title '产品效率日报' --message '今日产品效率查询结果'`
+   `python3 "$SKILL_DIR/scripts/publish_table.py" report.xlsx --title '产品效率日报' --message "$summary_message"`
 
    临时覆盖目标群可使用 `--chat-id` 或 `--chat-name`。不要把群 ID 硬编码进 Skill。
-7. 检查 JSON 结果中的 `url`、`permission` 和 `message_sent`。完整成功顺序必须是：上传临时素材、导入在线表格、设置任何人可编辑、发送群卡片。权限失败时不得继续发送链接。
-8. 回复中只给出在线表格链接、目标群名称或 ID、权限结果和消息发送结果；不得输出 access token、app secret、临时上传 token 或完整 API 响应。
+8. 检查 JSON 结果中的 `url`、`permission` 和 `message_sent`。完整成功顺序必须是：上传临时素材、导入在线表格、设置任何人可编辑、发送含概要的群卡片。权限失败时不得继续发送链接。
+9. 回复中只给出在线表格链接、目标群名称或 ID、权限结果和消息发送结果，并说明概要已随群卡片发送；不要重复整段结论，不得输出 access token、app secret、临时上传 token 或完整 API 响应。
+
+## 群卡片概要规则
+
+- 对数据查询报表，`--message` 必须传入实际数据概要；禁止沿用脚本的通用默认文案。
+- 优先复用上游查询 Skill 基于已校验聚合结果生成的结论，确保群卡片和报表口径一致。
+- 概要建议不超过 800 个中文字符，使用简洁 Lark Markdown，包含查询口径、3 至 6 个核心指标、正负向判断和必要的样本或时效风险。
+- 只写报表可验证的事实；基线为零、数据未收全或分组不均衡时明确提示，不夸大因果。
 
 ## 权限规则
 

skills/feishu-data-publisher/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "飞书数据表发布"
-  short_description: "把本地数据导入飞书表格并将可编辑链接发送到指定群聊"
-  default_prompt: "使用 $feishu-data-publisher 将查询结果发布为飞书在线表格并通知目标群聊。"
+  short_description: "把本地数据导入飞书表格，并将AI数据结论随卡片发送群聊"
+  default_prompt: "使用 $feishu-data-publisher 将查询结果和数据概要发布为飞书在线表格卡片并通知目标群聊。"

skills/feishu-data-publisher/references/configuration.md

@@ -2,27 +2,32 @@
 
 ## 环境变量
 
-必须配置：
+脚本读取当前进程环境变量，不会自动加载 `.env`。在项目根目录创建不进入 Git 的 `.env`，写入以下三个参数：
 
 ```bash
 export FEISHU_APP_ID='飞书自建应用 App ID'
 export FEISHU_APP_SECRET='飞书自建应用 App Secret'
+export FEISHU_TARGET_CHAT_ID='oc_a63f05d3a773e8d4d4a57955a618b63b'
 ```
 
 当前团队使用的机器人应用名称为“增长投放”。`FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 的真实值只放在环境变量或 Secret Manager，不写入 Markdown 和 Git。
 
-发送群消息时还需配置目标群，推荐使用稳定的群 ID：
+每次新开终端后，在项目根目录执行：
 
 ```bash
-export FEISHU_TARGET_CHAT_ID='oc_xxx'
+source .env
 ```
 
-当前团队默认发送到“前端组”：
+可用下面的命令确认三个变量已加载，而不显示其值：
 
 ```bash
-export FEISHU_TARGET_CHAT_ID='oc_a63f05d3a773e8d4d4a57955a618b63b'
+for name in FEISHU_APP_ID FEISHU_APP_SECRET FEISHU_TARGET_CHAT_ID; do
+  if [ -n "$(printenv "$name")" ]; then echo "$name=set"; else echo "$name=unset"; fi
+done
 ```
 
+当前默认 chat_id 对应“前端组”。群 ID 不是应用密钥，但属于环境配置；通用 Skill 只记录配置方法，实际值放在使用者本机的 `.env`。
+
 也可使用群名，由脚本在机器人可见群中精确解析：
 
 ```bash

skills/odps-product-efficiency-report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: odps-product-efficiency-report
-description: 生成、执行、校验并解释参数化 ODPS 产品效率实验报表，包含 DAU、曝光、播放、分享、回流、STR 和 ROV，并按头部、推荐、全部流量拆分。用于产品类型、离线或实时模式、日期范围、rootSessionId 分桶位置、实验/对照尾号、版本过滤或企微排除条件发生变化的查询。
+description: 生成、执行、校验并分析参数化 ODPS 产品效率实验报表，包含 DAU、曝光、播放、分享、回流、STR 和 ROV，并按头部、推荐、全部流量拆分；每次成功查询必须给出数据结论，用户要求飞书时将结论随表格发送。用于产品类型、离线或实时模式、日期范围、rootSessionId 分桶位置、实验/对照尾号、版本过滤或企微排除条件发生变化的查询。
 ---
 
 # ODPS 产品效率报表
@@ -44,8 +44,21 @@ description: 生成、执行、校验并解释参数化 ODPS 产品效率实验
 
    `python3 "$SKILL_DIR/scripts/format_report.py" normalized.json raw_facts.csv full_report.csv --aggregate-output aggregate_report.csv`
 
-10. 执行 [metrics.md](references/metrics.md) 中的全部校验，并分别解释头部、推荐和全部流量。
-11. 仅当用户明确要求上传飞书时，使用 `$feishu-data-publisher` 发布最终 CSV 或 Excel；未明确要求时只保留本地结果。
+10. 执行 [metrics.md](references/metrics.md) 中的全部校验，并按“分析与飞书概要契约”输出结论；不得只返回文件链接或原始指标。
+11. 仅当用户明确要求上传飞书时，先生成 `summary_message`，再使用 `$feishu-data-publisher` 发布最终 CSV 或 Excel，并通过 `--message` 把该概要写入群卡片；未明确要求时只保留本地结果。
+12. 发布成功后，在对话回复中只给出飞书链接、权限和发送状态，并说明概要已随群卡片发送；不要重复整段结论。
+
+## 分析与飞书概要契约
+
+每次成功查询都必须以校验通过的聚合报表为依据生成分析：
+
+- 先回显日期、实时或离线、产品、实验/对照桶、版本和数据截止时间。
+- DAU 使用真实桶数比较每桶均值，同时给出实验组总量；不得直接比较不同桶数的 DAU 总量。
+- 分别分析头部、推荐和全部流量，至少覆盖曝光 PV/DAU、播放 PV/DAU、分享 PV/DAU、STR、回流 UV/DAU 和 ROV 的实验值、对照值及相对变化。
+- 明确指出最强正向指标、主要负向或退化指标，以及整体判断。只描述相关变化，不把实验对比表述为已证明的因果关系。
+- 对照组为单桶、实时数据未收全、对照为零或样本过小时必须提示风险；基线为零时写“不可比较”，不得生成无穷变化率。
+
+飞书 `summary_message` 使用简洁的 Lark Markdown，建议不超过 800 个中文字符，依次包含：口径、全部流量核心结论、头部与推荐各一句判断、风险提示。禁止使用“数据查询结果已生成，请点击查看”之类的占位文案替代数据结论。
 
 ## 参数规则
 

skills/odps-product-efficiency-report/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "产品效率实验报表"
-  short_description: "按产品日期数据源分桶位置实验尾号和版本生成整体效率实验对比报表"
-  default_prompt: "使用 $odps-product-efficiency-report 查询指定产品、日期、分桶和版本的整体效率数据。"
+  short_description: "生成并分析产品效率实验报表，按需将结论和表格发送飞书"
+  default_prompt: "使用 $odps-product-efficiency-report 查询并分析指定产品效率数据，按需将结论和报表发送飞书。"