245 lines
9.3 KiB
Markdown
245 lines
9.3 KiB
Markdown
---
|
||
name: feishu-feedback-sync
|
||
description: 同步飞书「内容测试问题反馈」群消息到知识库电子表格并执行对话链排序。用于：(1) 刘新玉说"同步飞书反馈"、"更新飞书问题反馈表格"、"整理反馈对话链"时触发；(2) 定时任务每日自动同步。数据源为 MySQL vala_test.lark_group_message，目标为知识库飞书问题反馈-近3天表格。
|
||
---
|
||
|
||
# 飞书问题反馈同步与对话链排序
|
||
|
||
## 概述
|
||
|
||
从 MySQL `vala_test.lark_group_message` 读取飞书群消息，同步到知识库电子表格，并按引用关系执行「反馈对话链排序」。
|
||
|
||
### 两阶段输出（双文档分工）
|
||
|
||
| 阶段 | 目标文档 | 用途 |
|
||
|------|---------|------|
|
||
| 步骤 1-3 | 飞书问题反馈-近3天 电子表格 (`AHtnsehwShUVyDtjasSciIvgn7b`) | 原始数据初步整理，验证信息源准确性 |
|
||
| 步骤 4 | 用户反馈问题汇总 文档 (`RaL6whoYMijyYHkSlWrc7OLLnBy`) | 问题归纳输出，供二次处理 |
|
||
|
||
## 关键标识
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 数据库 | MySQL `bj-cdb-8frbdwju.sql.tencentcdb.com:25413`，user `chatbot`，密码 `xhuBx7d@uT2gUVv`，database `vala_test` |
|
||
| 源表 | `lark_group_message` |
|
||
| 目标表格 token | `AHtnsehwShUVyDtjasSciIvgn7b`（步骤1-3：原始数据整理） |
|
||
| 目标归纳文档 token | `RaL6whoYMijyYHkSlWrc7OLLnBy`（步骤4：问题归纳输出） |
|
||
| 目标知识库节点 | `TVivwmzqXiW3YakDUzucFMRenvf` |
|
||
| 知识空间 space_id | `7612229802338045122` |
|
||
| 群 chat_id | `oc_fabff7672e62a9ced7b326ee4a286c26` |
|
||
| Bot App ID | `cli_a9311791083adcc1` |
|
||
| Bot App Secret | `ThhLL1I0F2AIKnSbpozKnhm40LTPfyap` |
|
||
|
||
## 表格字段（与数据库一致）
|
||
|
||
| 列 | 数据库字段 |
|
||
|----|-----------|
|
||
| 消息ID | `message_id` |
|
||
| 发送者 | `sender_name` |
|
||
| 消息类型 | `msg_type` |
|
||
| 内容 | `content` |
|
||
| 媒体URL | `media_url` |
|
||
| 引用消息ID | `quote_message_id` |
|
||
| 消息时间 | `msg_time` |
|
||
| 消息时间戳 | `msg_timestamp` |
|
||
|
||
## 执行流程
|
||
|
||
### 步骤 1：查询数据库
|
||
|
||
```sql
|
||
SELECT message_id, sender_name, msg_type, content, media_url, quote_message_id,
|
||
DATE_FORMAT(msg_time, '%Y-%m-%d %H:%i:%s') as msg_time, msg_timestamp
|
||
FROM lark_group_message
|
||
WHERE msg_time >= '{date} 00:00:00' AND msg_time < '{next_date} 00:00:00'
|
||
ORDER BY msg_time ASC
|
||
```
|
||
|
||
默认同步最近 3 天的数据。如果表格已有当天 sheet，则追加新数据（去重写入，按 message_id 去重）；如无则创建新 sheet。
|
||
|
||
### 步骤 2：写入飞书表格
|
||
|
||
使用 `lark-cli sheets +write`（Bot 身份）批量写入：
|
||
- 按天分 sheet（sheet 名为日期，如 `2026-04-28`）
|
||
- 表头固定为 8 列
|
||
- 每 sheet 最多一次写入（或分批，不超过 500 行/批）
|
||
|
||
**凭证环境：**
|
||
```bash
|
||
export PATH=/root/.nvm/versions/node/v24.14.0/bin:$PATH
|
||
export LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaokui
|
||
export HOME=/root
|
||
```
|
||
|
||
**写入命令格式：**
|
||
```bash
|
||
lark-cli sheets +write \
|
||
--spreadsheet-token AHtnsehwShUVyDtjasSciIvgn7b \
|
||
--range '<sheet_id>!A1:H<n>' \
|
||
--values '<json_2d_array>' \
|
||
--as bot
|
||
```
|
||
|
||
### 步骤 3：反馈对话链排序
|
||
|
||
对每个 sheet 中的数据执行引用链排序（详见下文排序逻辑），使每个问题的完整讨论过程在表格中连续呈现。
|
||
|
||
## 反馈对话链排序逻辑
|
||
|
||
### 两阶段排序
|
||
|
||
#### 阶段 A：推断缺失引用（策略2）
|
||
|
||
由于飞书群消息同步时仅采集了 `quote_message_id`（显式引用），大量通过飞书「直接回复」功能产生的消息没有引用关系。策略2通过启发式规则补全：
|
||
|
||
1. **@提及匹配**（最高优先级）：消息中 `@某人` → 关联到被@者最近一条消息
|
||
2. **同发送者聚类**：同一发送者在 2 分钟窗口内连续发多条消息 → 认为是对同一目标的回复
|
||
3. **最近不同发送者**（fallback）：关联到最近一条不同发送者的消息（需在 30 分钟内，防止跨话题误关联）
|
||
|
||
```
|
||
示例：
|
||
12:18 徐思清: NPC HUD 报告 (无引用)
|
||
12:19 王胤鑫: o3 分支？ (无引用 → 推断关联12:18，因为12:18是最近不同发送者)
|
||
12:19 王胤鑫: 有固定关卡吗 (无引用 → 推断关联12:18，因为同发送者2分钟窗口内)
|
||
```
|
||
|
||
#### 阶段 B：引用链排序
|
||
|
||
1. **Union-Find 聚类**：将有引用关系的消息（含推断引用）合并为同一「问题簇」
|
||
2. **簇内递归展开**：从根消息开始，子回复紧跟父消息（子节点按时间排序）
|
||
3. **簇间排序**：按每个簇最早消息的时间排序
|
||
|
||
### 排序效果对比
|
||
|
||
排序前（时间平铺）：
|
||
```
|
||
12:18 徐思清: NPC HUD 报告
|
||
12:19 王胤鑫: o3 分支？
|
||
12:19 王胤鑫: 有固定关卡出现吗
|
||
12:20 庞鸿潇: @王胤鑫 11-2 (引用"有固定关卡")
|
||
12:22 梁晨: @王胤鑫 没啥规律 (引用"有固定关卡")
|
||
12:28 王胤鑫: 是否只在移动端 (引用NPC HUD)
|
||
```
|
||
|
||
排序后（问题链聚合）：
|
||
```
|
||
12:18 徐思清: NPC HUD 报告
|
||
12:19 王胤鑫: o3 分支？ (推断引用12:18)
|
||
12:19 王胤鑫: 有固定关卡吗 (推断引用12:18)
|
||
12:20 庞鸿潇: 11-2 (引用"有固定关卡")
|
||
12:22 梁晨: 没啥规律 (引用"有固定关卡")
|
||
12:28 王胤鑫: 是否只在移动端 (引用12:18)
|
||
12:26 孙时敏: Playtesting有数据 (推断引用12:22)
|
||
```
|
||
|
||
> 缩进行为对该根消息的直接或间接回复，形成完整的「问题 → 追问 → 诊断 → 结论」链路。
|
||
|
||
### 步骤 4：问题归纳
|
||
|
||
对每个问题簇生成结构化归纳，分两个部分：
|
||
1. **问题描述**：按固定格式描述问题
|
||
2. **当前问题排查结论**：从对话最后几条消息中提取排查状态
|
||
|
||
#### 4.1 问题描述格式
|
||
|
||
```
|
||
> **在{端}端{环节}内（{课程}），{角色/组件}出现了{现象}**
|
||
```
|
||
|
||
#### 位置要素提取维度
|
||
|
||
| 维度 | 可能的值 | 来源 |
|
||
|------|---------|------|
|
||
| 端 | 移动端、iOS、iPad、pad端、Android | 消息内容关键词 |
|
||
| 环节 | 关卡内、关卡外、知识巩固、巩固题、单元挑战、挑战、听力挑战、阅读挑战、口语挑战、写作挑战、单元强化、瓦拉学院、报告 | 消息内容关键词 |
|
||
| 课程 | 数字如 11-2、L1 3-2 | 消息内容中的数字/字母编号 |
|
||
| 角色/组件 | NPC、HUD、音频、组件等 | 消息内容关键词 |
|
||
| 现象 | 一句话概括发生了什么 | 综合理解 |
|
||
|
||
#### 4.2 归纳输出格式
|
||
|
||
每个问题簇输出一个结构化块（结论在表格上方，表格放原始对话）：
|
||
|
||
```markdown
|
||
### 问题 N
|
||
|
||
**问题描述：** {AI 归纳后的精炼描述}
|
||
|
||
**当前问题排查结论：** {结论}
|
||
|
||
| 发言人 | 对话信息 |
|
||
|--------|---------|
|
||
| 报告人 | 🚩 报告：原始对话内容 |
|
||
| ... | 原始对话内容（含媒体 URL） |
|
||
| 最终人 | ✅ 原始对话内容 |
|
||
```
|
||
```
|
||
|
||
#### 4.3 排查结论提取规则
|
||
|
||
脚本从**全部消息**（而非仅最后 1-2 条）中提取结论。优先匹配以下模式：
|
||
|
||
| 优先级 | 匹配模式 | 结论 |
|
||
|--------|---------|------|
|
||
| 1 | 已修复/已解决/修好了 | 已修复 |
|
||
| 2 | 确认是bug/确实是问题 | 已确认，待修复 |
|
||
| 3 | 不是bug/设计如此/非问题 | 非问题，设计如此 |
|
||
| 4 | 有解释性分析 + 日志已上传 + 排查中 | 疑似{原因}，已上传日志，排查中 |
|
||
| 5 | 日志已上传 + 排查中 | 已上传日志，排查中 |
|
||
| 6 | 暂未/没复现/未复现 | 暂未排查到问题 |
|
||
| 7 | 其他（无明确结论） | 暂未排查到问题 |
|
||
|
||
**解释性分析** 的来源：消息中匹配 "因为/原因是/应该是/改为了/导致/预下载/上云/首次/正常情况" 等关键词，提取对应发言人的判断句作为疑似原因。
|
||
|
||
> 注意：脚本的规则匹配是辅助手段。运行时的 AI 可以根据完整对话上下文，修正或补全结论。
|
||
|
||
#### 4.4 归纳示例
|
||
|
||
```markdown
|
||
### 问题一
|
||
> **在移动端关卡内（11-2 等），NPC 头上的 HUD 偶尔变成一小条**
|
||
|
||
| 发言人 | 要点 |
|
||
|--------|------|
|
||
| 徐思清 | 🚩 报告：最近经常出现，无明显规律 |
|
||
| 王胤鑫 | 追问：o3 分支？只在手机包出现，unity 里正常？ |
|
||
| 庞鸿潇 | 确认：11-2 出现了 |
|
||
| 梁晨 | 补充：只在 APP 里发现过 |
|
||
| 徐思清 | ✅ 确认：确实只在移动端出现 |
|
||
|
||
**当前问题排查结论：** 暂未排查到问题
|
||
```
|
||
|
||
```markdown
|
||
### 问题二
|
||
> **在 iOS 端关卡内（L1 3-2），组件数据丢失，无音频，Loading 耗时约 10 秒**
|
||
|
||
| 发言人 | 要点 |
|
||
|--------|------|
|
||
| 胡陈辰 | 🚩 报告：iOS 线上 L1 3-2 组件无音频 |
|
||
| 安君仪 | 询问：哪个组件？ |
|
||
| 胡陈辰 | 复现：Loading 约 10 秒，组件数据丢失，杀 APP 重进恢复正常 |
|
||
| 毋益飞 | 解释：Loading 慢因内容上云加载；要求上传日志 |
|
||
| 胡陈辰 | ✅ 日志已上传，待明天排查 |
|
||
|
||
**当前问题排查结论：** 日志已上传，排查中
|
||
```
|
||
|
||
## 定时任务
|
||
|
||
建议每日执行一次，在飞书群消息同步完毕后（`feishu-group-msg-sync` 之后）运行。
|
||
|
||
### 创建定时任务（crontab）
|
||
|
||
```bash
|
||
# 每天 10:00 执行（确保消息已同步入库）
|
||
0 10 * * * /bin/bash /root/.openclaw/workspace-xiaokui/scripts/sync_feishu_feedback_wrapper.sh >> /var/log/xiaokui_feedback_sync.log 2>&1
|
||
```
|
||
|
||
## 权限说明
|
||
|
||
- Bot 有 `sheets:read/write` 和 wiki API 读取权限
|
||
- Bot 缺少 `wiki:node:create`、`drive`、`bitable` 权限
|
||
- 所有操作均使用 Bot 身份 + `lark-cli` 命令
|
||
- 创建新 sheet 使用 `lark-cli api POST sheets_batch_update`
|