---
name: user-feedback-collector
description: |
  全渠道用户反馈收集与管理，支持三类反馈数据源：
  1. 主动上报：用户发送包含"用户反馈:"或"用户反馈："开头的消息时自动记录
  2. 飞书内部反馈群：「内容测试问题反馈」群（oc_fabff7672e62a9ced7b326ee4a286c26），每6小时同步到飞书表格
  3. 微信用户反馈群：数据实时存储在MySQL vala_test.wechat_group_message表
  自动汇总、分类、统计反馈，支持同步到知识库文档、多维表格，生成周报/月报。
---

# 用户反馈收集与管理

当用户发送的消息以 `用户反馈:` 或 `用户反馈：` 开头时，对反馈内容进行总结梳理后记录到飞书知识库文档。

## 用户反馈收集表格（模板）

| 序号 | 评估后优先级 | 问题所属模块 | 问题所属类型 | 反馈时间 | 反馈渠道 | 提交人 | 用户电话 | 用户角色ID | 文字描述 | 提交图片 | 提交视频 | 备注 | 当前解决进度 | 问题跟进人 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| 2 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| 3 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| 4 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| 5 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |

## 飞书渠道字段匹配说明（EiPtw2fqWialDIkDvmAcXKp7nUF）

飞书渠道文档表头字段：`时间`、`反馈人`、`信息类型`、`信息内容(或地址)`。

| 飞书渠道字段 | 对应到“用户反馈收集表格（模板）”字段 | 填写规则 |
| --- | --- | --- |
| 时间 | 反馈时间 | 直接填写；统一使用 Asia/Shanghai 时区 |
| 反馈人 | 提交人 | 直接填写 |
| 信息类型 | 提交图片 / 提交视频 / 文字描述 | 该字段用于判断“信息内容(或地址)”的内容形态：若为`文本`则写入`文字描述`；若为`图片`则写入`提交图片`；若为`视频`则写入`提交视频` |
| 信息内容(或地址) | 文字描述 / 提交图片 / 提交视频 | 与“信息类型”配合写入：`文本`原样写入`文字描述`；`图片/视频`将链接/地址写入对应列；若无法识别类型，默认写入`文字描述`并在`备注`中说明 |

飞书渠道写入标准表格时，建议默认补齐如下字段：

| 标准表格字段 | 默认值/处理方式 |
| --- | --- |
| 反馈渠道 | 固定填写 `飞书群` |
| 用户电话 | 无法获取则留空 |
| 用户角色ID | 无法获取则留空 |
| 评估后优先级 | 评估后填写 `P0/P1/P2/P3`；未评估留空 |
| 当前解决进度 | 默认 `待确认` |

## 反馈数据源（全渠道）

| 反馈渠道 | 来源 | 存储位置 | 更新频率 |
|---------|------|----------|----------|
| 主动上报 | 用户主动发送 `用户反馈:` 前缀消息 | 飞书知识库文档 | 实时 |
| 飞书内部测试反馈 | 「内容测试问题反馈」群（`oc_fabff7672e62a9ced7b326ee4a286c26`） | MySQL：`vala_test.feishu_group_message` 表 | 每4小时自动同步 |
| 微信用户反馈 | 「用户火线救火」群 | MySQL：`vala_test.wechat_group_message` 表 | 实时更新 |

> 注：飞书和微信反馈数据均存储在MySQL数据库，支持引用回复关系查询，便于统一管理和分析。

## 目标存储位置

### 1. 全量反馈汇总知识库文档
- **文档标题：** 用户反馈问题汇总
- **Wiki Token：** `ApVZw0fxGiv48ekuRS8cIfUjnRf`
- **知识空间 ID：** `7612229802338045122`
- **旧文档（已废弃）：** `SB3dwaSshie7ifklKlLc2GswnqX` 已停止使用

### 2. 全量反馈汇总多维表格（待上线）
将三个数据源的反馈统一汇总到同一个飞书多维表格，支持分类、筛选、统计和跟进。

## 支持功能

| 功能 | 说明 |
|------|------|
| 主动上报记录 | 用户发 `用户反馈:` 开头消息自动记录到知识库 |
| 多渠道查询 | 支持按时间、关键词、渠道、提交人查询所有反馈 |
| 统计分析 | 按周/月统计反馈数量、类型、TOP问题 |
| 定期汇总 | 自动生成反馈周报/月报，同步到知识库 |
| 每日定时推送 | 每日上午9:30自动将最新汇总的用户反馈推送给业务负责人刘新玉 |
| 同步跟进 | 支持将反馈同步到任务管理系统，跟进解决进度 |

## 主动上报执行流程（原有逻辑）

### 1. 识别反馈内容

从用户消息中提取 `用户反馈:` 或 `用户反馈：` 之后的文本作为反馈正文。去除前后空白。

### 2. 总结梳理反馈内容

对提取到的反馈正文进行智能总结和梳理：

- 提炼核心观点，去除冗余表述
- 保留关键事实、问题描述和诉求
- 总结后的内容**不超过 300 字**
- 如果原文本身不超过 300 字且条理清晰，可保持原文不变

### 3. 获取提交人信息

通过消息上下文中的 `sender_id`（open_id）调用 `feishu_get_user` 获取用户姓名。如获取失败，使用 open_id 作为标识。

### 4. 追加写入文档

使用 Bot 身份通过 lark-cli 将反馈追加到目标文档：

```bash
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/xiaokui \
  lark-cli docs +update --doc NVCRdIChwot7oPxcpopcBFMOned --as bot --mode append \
  --markdown '<写入内容>'
```

### 5. 写入格式

每条反馈按以下 Markdown 格式追加（使用分割线隔开每条反馈）：

```markdown
---

**📅 时间：** YYYY-MM-DD HH:mm

**👤 提交人：** <用户姓名>

**� 反馈摘要：**

<总结梳理后的内容，不超过300字>

**💬 原始反馈：**

<反馈原文>
```

- 时间使用 Asia/Shanghai 时区
- 如果文档为空（首条反馈），先写入一级标题 `# 📋 用户反馈记录`，然后再追加反馈条目（不需要开头的分割线）

### 6. 确认回复

写入成功后，回复用户：「✅ 反馈已记录，感谢！」

写入失败时，回复用户具体错误原因并建议重试。

## 多渠道反馈查询流程

### 查询飞书内部测试反馈
1. 连接MySQL数据库 `vala_test`，查询 `lark_group_message` 表
2. 支持按时间范围、提交人、关键词、消息类型筛选
3. 支持查询引用回复关系（通过 `quote_message_id` 字段）
4. 每4小时自动同步最新群消息

**查询示例：**
```sql
-- 查询最近7天的反馈
SELECT * FROM lark_group_message 
WHERE chat_id = 'oc_fabff7672e62a9ced7b326ee4a286c26'
  AND msg_time >= DATE_SUB(NOW(), INTERVAL 7 DAY)
ORDER BY msg_timestamp DESC;
```

### 查询微信用户反馈
1. 连接MySQL数据库 `vala_test`，查询 `wechat_group_message` 表
2. 支持按时间范围、发送人、关键词、消息类型筛选
3. 支持查询引用回复关系（通过 `refer_msg_svrid` 字段）
4. 数据实时更新，可查询最新反馈

**查询示例：**
```sql
-- 查询最近7天的反馈
SELECT * FROM wechat_group_message 
WHERE msg_time >= DATE_SUB(NOW(), INTERVAL 7 DAY)
ORDER BY msg_timestamp DESC;
```

## 引用回复关系查询（飞书 + 微信统一说明）

两个渠道的数据表都支持引用回复关系，字段名和类型不同，但查询逻辑一致。

### 字段对照表

| 说明 | 飞书表 `lark_group_message` | 微信表 `wechat_group_message` |
|------|---------------------------|------------------------------|
| 消息唯一ID | `message_id` (varchar, 如 `om_xxx`) | `svr_msg_id` (bigint) |
| 被引用消息ID | `quote_message_id` (varchar) | `refer_msg_svrid` (bigint) |
| 判断是否引用回复 | `quote_message_id IS NOT NULL` | `refer_msg_svrid IS NOT NULL` |

### 飞书：查询引用关系

```sql
-- 查询某条消息的所有回复
SELECT message_id, sender_name, content, msg_time
FROM lark_group_message 
WHERE quote_message_id = 'om_xxx'
ORDER BY msg_timestamp;

-- 查询完整对话链（原消息 + 所有回复）
SELECT message_id, sender_name, content, msg_time,
       IF(quote_message_id IS NULL, '原消息', '↳ 回复') AS role
FROM lark_group_message 
WHERE message_id = 'om_xxx' OR quote_message_id = 'om_xxx'
ORDER BY msg_timestamp;

-- 向上追溯：找到某条回复引用的原消息
SELECT b.message_id, b.sender_name, b.content, b.msg_time
FROM lark_group_message a
JOIN lark_group_message b ON a.quote_message_id = b.message_id
WHERE a.message_id = 'om_当前消息ID';
```

### 微信：查询引用关系

```sql
-- 查询某条消息的所有回复
SELECT svr_msg_id, sender_name, content, msg_time
FROM wechat_group_message 
WHERE refer_msg_svrid = 12345678
ORDER BY msg_timestamp;

-- 查询完整对话链（原消息 + 所有回复）
SELECT svr_msg_id, sender_name, content, msg_time,
       IF(refer_msg_svrid IS NULL, '原消息', '↳ 回复') AS role
FROM wechat_group_message 
WHERE svr_msg_id = 12345678 OR refer_msg_svrid = 12345678
ORDER BY msg_timestamp;

-- 向上追溯：找到某条回复引用的原消息
SELECT b.svr_msg_id, b.sender_name, b.content, b.msg_time
FROM wechat_group_message a
JOIN wechat_group_message b ON a.refer_msg_svrid = b.svr_msg_id
WHERE a.svr_msg_id = 12345678;
```

### 跨渠道统计：有多少反馈是引用回复

```sql
-- 飞书引用回复数量
SELECT COUNT(*) AS feishu_replies FROM lark_group_message WHERE quote_message_id IS NOT NULL;

-- 微信引用回复数量
SELECT COUNT(*) AS wechat_replies FROM wechat_group_message WHERE refer_msg_svrid IS NOT NULL;
```

### 典型使用场景

1. **追溯问题讨论**：用户报了一个bug，后续有人回复了解决方案 → 通过引用ID查询完整讨论链
2. **统计热门问题**：被回复最多的消息往往是影响面大的问题 → 按引用次数排序
3. **关联反馈汇总**：同一个问题可能有多条引用回复补充细节 → 聚合展示原消息及所有回复

## 注意事项

- 所有文档/数据库操作默认使用只读权限，避免修改原始数据
- 所有外部操作使用 Bot 身份（`--as bot`），不触发用户授权
- 反馈正文会被总结梳理（不超过 300 字），同时保留原始反馈以供查阅
- 任何人都可以提交反馈，无权限限制
