a0c9c23e2c
- 将创意描述重构为可执行技术文档，明确 V1/V2 分阶段路线 - 对齐 point_trade、daily_ranking、message_sign、inactive_rank 的现有数据来源与接口 - 新增评分模型（归一化+分位截断+潜水惩罚）及解释理由，提升抗刷屏与公平性 - 补充命令设计、定时任务流程、数据库快照表 SQL、防刷规则与灰度上线计划 - 标注当前不合理点与优化建议（被@指标链路、固定阈值称号、过强惩罚玩法）
8.8 KiB
8.8 KiB
Value Rank 插件设计文档（优化版）
目标：基于你现有插件生态（
point_trade/daily_ranking/message_sign/inactive_rank/stats_collector）实现一个可落地、可运营、可扩展的“群成员身价排行”插件。
1. 先说结论（对当前方案的评估）
你原文档的方向是对的，但当前版本存在 4 个落地风险：
- 指标可用性不一致
- 你设计了
被@次数，但当前代码链路里没有稳定落库这个指标，直接作为核心权重会导致实现卡住。
- 分值可刷问题
- 如果直接用“发言量线性加分”，会被短消息刷屏轻易拉爆，排行榜失真。
- 指标量纲不统一
- 积分、发言数、签到天数的数值范围差异大，直接加权会导致大数指标统治结果。
- 结果不可追溯
- 如果只算“当前分”，没有“每日快照”，后续很难解释“为什么今天涨跌”。
因此建议：
- V1 先用现成数据做稳定可用版（积分 + 发言 + 活跃天数 + 潜水惩罚）。
- V2 再接入社交中心度（被@），但前提是先补齐数据采集链路。
2. 与现有插件/数据库的复用关系
2.1 可直接复用的数据来源
- 积分存量
- 来源：
db/points_db.py->PointsDBOperator.get_user_points()/get_points_ranking() - 表：
t_user_points（兼容旧数据迁移）
- 发言活跃
- 来源：
db/message_storage.py - 可用接口：
get_group_member_message_ranking(group_id, start_time, end_time, limit)get_member_active_dates(group_id, wxid, days)- 或直接 SQL 聚合
messages
- 连续签到/签到数据
- 来源：
db/sign_in.py+plugins/message_sign - 表：
t_sign_record（signin_streak、last_sign_date等）
- 潜水信息
- 来源：
plugins/inactive_rank（内部用ContactsDBOperator.get_inactive_members_rank） - 可作为负向修正项
2.2 暂时不可直接复用（需补链路）
- 被@次数（社交中心度）
- 当前
messages里虽有message_xml，但还没有统一抽取与聚合逻辑。 - 建议放到 V2，不阻塞 V1 上线。
3. 推荐算法（V1 可直接上线）
3.1 指标定义
按群独立计算（group_id 维度）：
P：用户当前积分（财富存量）M7：近 7 天有效发言量A30：近 30 天活跃天数（有发言记 1 天）I：潜水惩罚项（最近发言距今天数）
“有效发言”建议过滤：长度过短、纯命令消息、纯重复刷屏消息。
3.2 归一化与评分
建议将所有指标归一化到 [0,1] 再加权，避免量纲污染。
P_norm = min(log1p(P) / log1p(P95), 1)M_norm = min(M7 / M95, 1)A_norm = min(A30 / 30, 1)I_penalty = min(inactive_days / 30, 1)
其中 P95、M95 为群内当日 95 分位，用于抗极端值。
最终分数：
score = 1000 * (
0.35 * P_norm +
0.45 * M_norm +
0.20 * A_norm
) - 150 * I_penalty
边界处理：
score < 0则记为0- 新成员冷启动：若无积分但有发言，可获得基础活跃分，避免“永远垫底”
3.3 为什么比原线性模型更优
- 抗刷屏：
M7上限由分位数截断，极端刷量收益递减 - 抗土豪统治：积分用
log1p，防止高积分一票否决 - 可解释：每个分项都能单独展示（资产、热度、活跃、惩罚）
4. 称号系统（可运营版）
不建议用固定分数区间，建议用“分位段位”，因为不同群体量级差异很大。
- Top 1%：
群之巨鳄 - Top 5%：
社交名流 - Top 20%：
活跃中产 - 20%~80%：
稳定居民 - Bottom 20%：
潜力新人 - Bottom 10% 且
inactive_days >= 30：潜水观察员
这样跨群也更公平，且无需频繁调阈值。
5. 数据库存储设计（建议新增）
5.1 每日快照表（核心）
CREATE TABLE IF NOT EXISTS t_value_rank_snapshot (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
stat_date DATE NOT NULL COMMENT '统计日期',
group_id VARCHAR(100) NOT NULL COMMENT '群ID',
user_id VARCHAR(100) NOT NULL COMMENT '用户ID',
score DECIMAL(10,2) NOT NULL DEFAULT 0 COMMENT '身价分',
rank_no INT NOT NULL DEFAULT 0 COMMENT '名次',
title VARCHAR(50) NOT NULL DEFAULT '' COMMENT '称号',
points_total INT NOT NULL DEFAULT 0 COMMENT '当前积分',
msg_count_7d INT NOT NULL DEFAULT 0 COMMENT '7日有效发言数',
active_days_30 INT NOT NULL DEFAULT 0 COMMENT '30日活跃天数',
inactive_days INT NOT NULL DEFAULT 0 COMMENT '距今未发言天数',
score_detail_json JSON NULL COMMENT '分项得分详情',
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uniq_day_group_user (stat_date, group_id, user_id),
KEY idx_group_day_rank (group_id, stat_date, rank_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
这个表是关键：支持“涨跌解释”“历史回溯”“趋势展示”。
5.2（可选）社交指标表（V2）
CREATE TABLE IF NOT EXISTS t_value_rank_social_daily (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
stat_date DATE NOT NULL,
group_id VARCHAR(100) NOT NULL,
user_id VARCHAR(100) NOT NULL,
mentioned_count INT NOT NULL DEFAULT 0,
mention_others_count INT NOT NULL DEFAULT 0,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uniq_day_group_user (stat_date, group_id, user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
6. 插件交互设计（命令与输出）
6.1 命令建议
我的身价
- 查询自己今日身价报告
身价排行 [N]
- 默认前 10，最大 50
身价说明
- 返回算法权重与统计周期说明，减少争议
重算身价（管理员）
- 手动触发当前群重算（用于调试/补数据）
6.2 输出模板
个人报告
📊 [昵称] 的身价报告（2026-04-21）
总身价：786.4
群内排名：第 4 / 126（社交名流）
资产分：+210.2（积分 13240）
热度分：+365.8（7日发言 188）
活跃分：+142.0（30日活跃 24 天）
潜水惩罚：-31.6（2 天未发言）
较昨日：+5.8%
排行榜
🏆 身价排行榜（Top10）
1. 张三 942.1 群之巨鳄
2. 李四 901.3 社交名流
3. 王五 860.0 社交名流
...
7. 插件实现方案（按你项目结构）
推荐文件：
plugins/value_rank/
├─ __init__.py
├─ main.py
├─ config.toml
└─ README.md
7.1 main.py 关键职责
- 继承
MessagePluginInterface - 注册 feature 权限（如
VALUE_RANK） - 处理命令：
我的身价/身价排行/身价说明/重算身价 - 提供定时任务：每天
04:00全量重算 - 复用：
PointsDBOperator、MessageStorageDB、联系人昵称管理
7.2 调度逻辑（对齐 daily_ranking）
get_schedule_actions()返回value_rank_daily_recomputerun_scheduled_action()按启用群批量执行- 每群执行：
- 拉取候选成员（近 30 天有消息或有积分记录）
- 计算分项与总分
- 生成 rank + title
- upsert 到
t_value_rank_snapshot - （可选）推送 TopN
8. 防刷与风控建议（必须做）
- 发言去噪
- 过滤超短文本、纯命令、重复消息
- 单日贡献上限
- 单用户单日“发言贡献值”设上限（例如 200 条）
- 冷启动保护
- 新人有发言即可入榜，但不会瞬间冲顶
- 异常波动检测
- 日涨跌超过阈值（如 ±40%）写日志，便于排查
9. V2 增量（社交中心度：被@）
当你准备上线“被@”指标时，建议：
- 在消息入库或消息处理总入口解析
@数据 - 日聚合写入
t_value_rank_social_daily - 新增权重项：
score = 1000 * (0.30*P_norm + 0.35*M_norm + 0.20*A_norm + 0.15*C_norm) - penalty
其中 C_norm 为被@次数归一化值。
10. 最小可行上线计划（建议）
- 第 1 天：建表 + 插件骨架 +
我的身价查询 - 第 2 天：
身价排行+ 定时重算 + 排名持久化 - 第 3 天：防刷规则 + 涨跌展示 + 管理员重算命令
- 第 4 天：灰度 1~2 个群，观察一周后再全量
11. 你原方案中建议调整的点（明确结论）
- “被@权重 30%”
- 暂不建议直接上，先补采集链路，否则会造成空值偏差。
- “倒数群友自动踢出警告”
- 建议改为轻量提醒，避免群体验冲突。
- “打击低身价用户（禁言/掠夺）”
- 建议改为娱乐化、低惩罚玩法，避免强负反馈导致活跃进一步下降。
- 固定阈值称号
- 建议改为分位阈值，更适配不同规模群。
如果你愿意，下一步我可以直接把 plugins/value_rank/main.py 和 config.toml 的首版骨架按这份文档落地出来（含详细中文注释、可直接运行）。