From 7d82557699840350fb72819dde8ec7b4b3f40b94 Mon Sep 17 00:00:00 2001
From: liuwei <liuwei@wdtrgf.com.cn>
Date: Tue, 21 Apr 2026 14:28:07 +0800
Subject: [PATCH] =?UTF-8?q?docs(value=5Frank):=20=E8=A1=A5=E5=85=85?=
 =?UTF-8?q?=E5=BD=93=E5=89=8D=E5=AE=9E=E7=8E=B0=E7=8A=B6=E6=80=81=E4=B8=8E?=
 =?UTF-8?q?=E6=93=8D=E4=BD=9C=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增功能完整度说明，明确已上线命令、定时任务和数据链路状态

- 增加快速上手步骤：配置检查、模板检查、表结构检查、命令验证顺序

- 增加常见问题排查，覆盖社交关系图、社交榜单、趋势数据不足场景
---
 plugins/value_rank/README.md | 98 ++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)

diff --git a/plugins/value_rank/README.md b/plugins/value_rank/README.md
index 7e28683..afb231e 100644
--- a/plugins/value_rank/README.md
+++ b/plugins/value_rank/README.md
@@ -2,6 +2,104 @@
 
 > 目标：基于你现有插件生态（`point_trade` / `daily_ranking` / `message_sign` / `inactive_rank` / `stats_collector`）实现一个可落地、可运营、可扩展的“群成员身价排行”插件。
 
+## 0. 当前实现状态（2026-04-21）
+
+当前插件核心闭环已完成，可直接在群里使用：
+
+1. 排行与报告能力
+- `我的身价`
+- `身价排行 [名次]`
+- `身价周报`
+- `我的趋势 [天数]`
+- `身价说明`
+- `重算身价`（管理员）
+
+2. 社交图谱能力
+- `社交热度榜 [名次]`
+- `搭子榜 [名次]`
+- `社交桥梁榜 [名次]`
+- `社交关系图 [人数]`（基于 HTML 模板渲染为图片）
+
+3. 定时任务能力
+- 每日重算身价快照
+- 每 10 分钟批处理一次 @ 关系（默认只处理“当前前 20~10 分钟”的消息窗口）
+- 每周自动推送周报
+
+4. 数据链路状态
+- `messages.mentioned_user_ids`：已用于标记“是否处理过 @ 抽取”，`[]` 代表已处理但无 @。
+- `messages.raw_payload`：已支持存储完整原始消息载荷（不脱敏）。
+- 社交明细/边/日汇总：已落 `t_message_mentions`、`t_social_edges_daily`、`t_value_rank_social_daily`。
+
+## 0.1 操作指南（快速上手）
+
+### 步骤 1：确认配置与命令
+
+检查 [config.toml](/D:/learn/abot/plugins/value_rank/config.toml)：
+
+1. `enable = true`
+2. `command` 包含下列命令：
+- `我的身价`
+- `身价排行`
+- `社交热度榜`
+- `搭子榜`
+- `社交桥梁榜`
+- `社交关系图`
+- `我的趋势`
+- `身价周报`
+- `身价说明`
+- `重算身价`
+
+### 步骤 2：确认社交关系图模板
+
+`社交关系图` 命令强依赖模板文件：
+
+1. 配置项：
+- `social_graph_template_path = "plugins/value_rank/templates/social_graph.html"`
+2. 模板文件：
+- [social_graph.html](/D:/learn/abot/plugins/value_rank/templates/social_graph.html)
+
+说明：当前不再兼容内嵌模板；模板缺失会导致关系图生成失败。
+
+### 步骤 3：确认数据库结构
+
+至少需要以下表/字段可用：
+
+1. `t_value_rank_snapshot`
+2. `t_value_rank_social_daily`
+3. `t_message_mentions`
+4. `t_social_edges_daily`
+5. `messages.mentioned_user_ids`
+6. `messages.raw_payload`
+
+### 步骤 4：群内验证命令
+
+建议按以下顺序验证：
+
+1. 发 `重算身价`（管理员）确保当天快照可用。
+2. 发 `我的身价`、`身价排行 10` 验证基础分与排行。
+3. 发 `社交热度榜 10`、`搭子榜 10`、`社交桥梁榜 10` 验证社交统计。
+4. 发 `社交关系图 12` 验证模板渲染与发图链路。
+5. 发 `我的趋势 7`、`身价周报` 验证历史快照与趋势计算。
+
+### 步骤 5：定时任务观察点
+
+1. `@` 抽取任务：每 10 分钟跑一次，只处理指定时间窗口内、`mentioned_user_ids` 为空的消息。
+2. 每日消息快照：用于第二天趋势与周报对比。
+3. 每周周报推送：依赖当日快照和近 7 天对比数据。
+
+### 常见问题
+
+1. `社交关系图` 无图返回
+- 优先检查模板路径和模板文件是否存在。
+- 再检查近 `social_window_days` 是否有足够社交边数据。
+
+2. 社交榜单无数据
+- 检查 `@` 批处理任务是否正常执行。
+- 检查消息是否被标记为已处理（`mentioned_user_ids = []` 或有值）。
+
+3. `我的趋势` 数据过少
+- 说明历史快照不足，等待每日重算积累后会逐步完整。
+
 ## 1. 先说结论（对当前方案的评估）
 
 你原文档的方向是对的，但当前版本存在 4 个落地风险：