🦞 multi-group-chat-manager v1.1.0

多群聊用户画像管理 + 好感度系统。

让 AI 更懂每个群友。 自动记录兴趣偏好、性格特征、常聊话题；追踪好感度，用规则引擎自动加减分；液态记忆引擎模拟人类遗忘曲线。

适配平台： QQ（OneBot）、飞书、Discord、Telegram 等任意 OpenClaw 支持的消息渠道。

📋 目录

• 🆕 初始化流程（首次部署看这里）
• 📂 项目架构
• 🧩 系统一：用户画像系统
• ❤️ 系统二：好感度系统
• 🧠 系统三：液态记忆引擎
• ⚙️ 系统四：好感度规则引擎
• 🔄 上下线会话管理
• 📝 画像更新与扫描流程
• 🔒 隐私保障
• 💻 CLI 速查

🆕 初始化流程（首次部署看这里）

第一步：配置 OpenClaw

在 OpenClaw 配置文件中启用此 Skill：

skills:
  multi-group-chat-manager:
    enabled: true
    path: /path/to/skills/multi-group-chat-manager

第二步：配置文件（config.json）

编辑 config.json，填写你的信息：

{
  "onebot": {
    "base_url": "http://127.0.0.1:3000",
    "groups": {
      "群号1": "群名称1",
      "群号2": "群名称2"
    }
  },
  "affection": {
    "small_group_default_score": 85,
    "small_group_ids": ["群友QQ号1", "群友QQ号2"]
  }
}

需要修改的配置项：

如果使用非 QQ 渠道（飞书/Discord 等），onebot 部分可直接留空或删除，画像和好感度系统仍正常工作，只是无法用 OneBot 做批量消息采集。

第三步：设置群规规则文件

为你的每个群创建规则文件，放在 scripts/rules/ 目录下：

# 复制模板
cp scripts/rules/rule_sample.json scripts/rules/rule_你的群号.json

编辑文件，修改 meta.group_id 和 meta.group_name，根据你的群规调整关键词和规则。

参考 rule_sample.json 中的注释理解每个字段的含义。

第四步：初始化好感度

# 对核心成员批量设置初始好感度
python scripts/affection.py init 群友QQ号 85

# 或批量导入（编辑 config.json 的 small_group_ids 后，逐条执行）

新用户将在首次被记录时自动获得 default_score（默认 50 分）。

第五步：初始化画像存储目录

数据目录会自动创建，无需手动操作。首次调用 profiles.py update 时会自动建立目录结构：

profiles/
├── memory/       # 液态记忆数据
└── composite/    # 概要画像
logs/             # 好感度日志

第六步：验证部署

# 检查好感度系统
python scripts/affection.py status

# 检查液态记忆引擎
python scripts/memory.py stats

# 检查 OneBot 连接（QQ 渠道）
python scripts/onebot_collector.py health

# 查看规则引擎状态
python scripts/rule_engine.py list

第七步（可选）：配置 AI 助手调用

在 AI 助手的 AGENTS.md 或 SOUL.md 中添加触发规则和工作流程说明，使助手知道何时上下线、如何查询画像和执行好感度操作。

参考本文档的「触发流程」章节设计你的 AI 助手的行为逻辑。

📂 项目架构

multi-group-chat-manager/
│
├── SKILL.md              ← 技能说明书（给 AI 看的完整工作流程）
├── README.md             ← 给开发者/用户看的功能介绍
├── config.json           ← 系统配置文件（修改后热加载生效）
├── config.yaml           ← 带注释的说明版本（仅供人类参考）
├── session_state.json    ← 上下线会话状态（运行时自动生成）
├── .last_decay           ← 上次衰减时间戳标记（自动维护）
│
├── affection.json        ← 好感度主数据（每人当前分数）
│
├── logs/                 ← 每人独立的加减分日志目录（运行时自动创建）
│   └── ...
│
├── profiles/             ← 画像数据目录
│   ├── memory/           ← FluidMemory 引擎数据（每人独立文件）
│   └── composite/        ← 概要画像缓存
│
├── scripts/              ← 核心 Python 脚本
│   ├── config.py         ← 统一配置加载模块
│   ├── memory.py         ← 液态记忆引擎（零外部依赖）
│   ├── profiles.py       ← 画像系统：存储、合并、格式化
│   ├── affection.py      ← 好感度系统：加减分、日志、查询
│   ├── session_state.py  ← 上下线会话状态管理
│   ├── rule_engine.py    ← 好感度规则引擎
│   ├── onebot_collector.py ← OneBot 群消息采集器（依赖 requests）
│   └── rules/
│       ├── rule_sample.json      ← 公开模板（首次部署时复制）
│       └── rule_cooldown.json    ← 水位线+计数器（自动维护）

技术栈：

• 运行环境：OpenClaw Agent 框架
• 存储：画像 → FluidMemory（JSON文件+流体衰减算法）/ 好感度 → JSON 文件
• 通信：QQ（OneBot 协议）/ 飞书 / 任意 OpenClaw 支持的渠道
• 外部依赖：requests（仅 onebot_collector.py 使用，其他脚本零外部依赖）

🧩 系统一：用户画像系统

这是什么？

AI 助手会根据和群友的日常聊天，慢慢记住每个人的兴趣爱好、性格特点、常聊话题等。这些信息存在液态记忆里，下次聊天时就能自然地接上。

画像数据格式

{
  "user_id": "用户ID",
  "name": "最新昵称",
  "preferences": ["兴趣/偏好条目"],
  "personality": ["性格特征条目"],
  "topics_of_interest": ["常聊话题"],
  "behavior": ["行为模式条目"],
  "group_roles": {"群名": "角色"},
  "first_seen": 时间戳,
  "last_updated": 时间戳,
  "update_count": 更新次数,
  "important_facts": ["需要记住的关键事实"]
}

每条特征同时作为独立记忆条目存入 FluidMemory，支持按字段和关键词召回。

画像提取规则

应该提取的信息：

• ✅ 兴趣偏好：「我喜欢玩空洞骑士」「我爱吃辣」
• ✅ 性格特征：「这人说话很直」「他总是自嘲」
• ✅ 行为习惯：「fly喜欢迫害人」「他深夜出没」
• ✅ 知识背景：「他是学计算机的」「他懂哲学」
• ✅ 关系特征：「他是群主」「他和fly关系好」
• ✅ 语言风格：「喜欢用括号」「爱发emoji」「打字口语化」

不应该提取的信息：

• ❌ 地址、电话、邮箱等联系信息
• ❌ 密码/Token 等凭据类信息
• ❌ 情感隐私、家庭矛盾细节等隐私事件
• ❌ 账号密码/验证码

去重规则：

• 同一条信息不重复存储
• 基于语义判断，不依赖精确文字匹配
• 人格特征方面：相近条目合并为更完整的表述

❤️ 系统二：好感度系统

好感度等级

加减分规则（模板）

加分项：

减分项：

以上为模板规则。实际部署时请根据群规在 scripts/rules/rule_群号.json 中自定义。

🧠 系统三：液态记忆引擎

零外部依赖，纯 Python 标准库实现。

每条画像特征都有一个记忆强度分数：

• 新记住 → 初始 0.8 分
• 每天衰减 → 分数乘以 e^(-0.05)，约每天下降 4.9%
• 每次提起 → 强化 +0.2 × log(1+总提起次数)
• 低于 0.15 分 → 自动归档

核心公式

score = e^(-0.05 × days_passed) + 0.2 × log(1 + access_count)

存储结构

profiles/memory/用户ID.json：

{
  "user_id": "用户ID",
  "memories": [
    {
      "id": "mem_xxxxx",
      "content": "喜欢约稿画师",
      "field": "preferences",
      "tags": ["preferences", "group"],
      "score": 1.18,
      "access_count": 4,
      "status": "active",
      "created_at": 时间戳,
      "last_accessed": 时间戳
    }
  ]
}

⚙️ 系统四：好感度规则引擎

规则以独立 JSON 文件存储在 scripts/rules/ 目录下。

文件结构

规则双模式

• auto — 脚本自动处理的规则（关键词匹配、频率检测）
  • greeting — 打招呼关键词匹配
  • spam — 频率检测
  • scam_ad — 广告关键词匹配
• ai — 脚本标记候选，AI 判断
  • 加分：friendly_chat, feedback, share_resource, deep_discussion, share_creation, defend_atmosphere
  • 减分：scary, negativity, argue_attack, disgusting

冲突处理

• 匹配 auto 扣分 → 取扣分最多的执行，跳过加分
• 匹配 auto 加分 → 直接执行
• 剩余消息 → 标记 needs_ai_review 供 AI 处理

水位线去重

• 记录已处理消息的 max_message_seq
• 离线扫描时只处理新消息，已处理的不重复加减分
• 但已处理的消息仍出现在输出中（供 AI 看上下文）

🔄 上下线会话管理

基于时间戳区间的精准扫描。 替代固定时间段扫描（如「扫最近12小时」）。

数据文件

session_state.json（skill 根目录）：

{
  "status": "online/offline",
  "session_start": "2026-05-11T10:00:00+08:00",
  "groups": {
    "群ID": {
      "name": "群名",
      "session_start": "2026-05-11T10:00:00+08:00",
      "last_active": "2026-05-11T11:00:00+08:00"
    }
  }
}

设计原理

上线 10:00 ──────── 在群A聊天 ──────── 在群A喊下线 11:00
                    ↓                    ↓
              自动注册活跃群         精确扫 10:00→11:00
                   │
                   └── 所有群独立追踪，互不干扰

好处： 零重复、零遗漏。每个群有独立的 session_start，按群下线不影响其他群。

流程1：喊上线 → 开始追踪

触发词： 「我上线了」「上线」「online」「上线了」

1. 运行 session_state.py online
2. 检查上次是否有意外中断（status == "online" 且 groups 非空）
   → 如果有：记录 recovered_groups，消息采集需要恢复
      （恢复参数：最近 24h，最多 1000 条/群）
3. 设置 status = "online"，session_start = now
4. 向管理员报告上线状态 + 如有恢复则列出需要恢复的群

流程2：在群聊中发言时 → 注册活跃群

每次机器人在群聊中发言时自动调用。

1. 运行 session_state.py register <chat_id> --name <群名>
2. 如果该群是新群：标记 session_start = now，加入 groups
3. 如果已存在：刷新 last_active
4. 静默执行，不回复

流程3：喊下线 → 扫描并更新画像

触发词： 「我下了」「下线」「offline」「下了」

场景 A：在群聊中喊下线

只在当前群执行下线：

1. 获取当前群 chat_id
2. 运行 session_state.py offline --chat_id <chat_id> --name <群名>
   返回 scan_start（该群的 session_start）→ scan_end（now）
3. 运行 OneBot scan 全流程：
   onebot_collector.py scan --group-id <群号> --since <scan_start的unix_ts> --until <scan_end的unix_ts> --max-msgs 500
   → 三层流水线：
      a. 采集（方向一）：通过 OneBot API 拉取完整群消息
      b. 好感度（方向七）：规则引擎自动判定加减分
      c. 画像强化（方向二）：关键词匹配已有记忆 → 自动增加记忆强度
4. 读取 scan 输出结果：
   - profile_reinforcements：已有记忆强化情况
   - users[uid].all_messages：各用户消息原文（供 AI 提取新特征）
   - affection：好感度更新结果
5. AI 分析消息原文，提取新特征 → 调用 profiles.py update 写入新记忆
6. 从 groups 中移除此群
7. 回复「已在 [群名] 下线 ✌️」+ 更新摘要

场景 B：在私聊中喊下线

如果指定了群名/ID： → 同场景 A 如果未指定： → 先询问用户意图，用户可回复：

• 「在[群名A]」 → 处理指定群
• 「全部」「全部下线」「所有群」 → 走场景 C
• 「算了」 → 取消操作

场景 C：全部群下线

1. 运行 session_state.py offline --all
2. 返回所有群的 scan_start → scan_end 窗口
3. 对每个群，按场景 A 的方式获取消息并处理
4. 全部处理完毕后，status = offline
5. 回复各群处理摘要

输出摘要格式

✅ [群名] 下线扫描完成
📊 共更新 N 条消息

【用户画像更新】
  - 用户A：新增 2 条特征（偏好+1，行为+1）
  - 用户B：无变化

【好感度变动】
  - 用户A：+5（友善闲聊+2，分享资源+3）→ 当前 90
  - 用户B：+0.5（友善闲聊）→ 当前 50.5

意外中断恢复

如果网关重启、AI 断了、忘记喊下线——没关系。下次喊上线时自动检测遗留群，扫描最近 24 小时的消息（最多 1000 条/群） 进行恢复。

流程4：加载画像 → 在线期间使用

上线后在处理群聊消息时可直接参考用户画像，从 FluidMemory 调用即可。

流程5：查询用户画像（🔒 仅限私聊）

触发词： 「看看xx的画像」「xx是什么样的人」「查一下xx」

⚠️ 安全约束：此操作只能在私聊中执行！如果是在群聊中收到此请求，必须拒绝。

1. 检查当前会话类型
   - ✅ 私聊：继续执行
   - ❌ 群聊：回复「抱歉，用户画像属于隐私数据，只能在私聊中查询哦」并终止
2. 用 profiles.py load <用户ID> 加载画像，再用 profiles.py format 格式化为可读文本
3. 输出内容包含：昵称和ID、偏好总结、性格特征、常聊话题、行为模式、关键事实、更新次数

流程6：查询好感度（🔒 仅限私聊）

触发词： 「xx的好感度」「我对xx好感度多少」「好感度」

管理员查询（私聊）：

1. 调用 scripts/affection.py detail <用户ID>
2. 返回完整信息：当前分数 + 等级 + 图标 + 最近 20 条加减分历史

普通用户自查（私聊）：

1. 调用 scripts/affection.py brief <自己的ID>
2. 仅返回：当前分数 + 等级 + 近 24 小时简要摘要

流程7：加减分操作

触发场景： 群聊中 @AI 的消息、私聊中与管理的互动

步骤：

1. 分析消息内容，判断匹配哪条加减分规则
2. 调用 scripts/affection.py add <用户ID> <规则key> <原因描述>
3. 分数自动 clamp 到 0~100
4. 自动写入日志文件
5. 系统内部记录，不主动广播

加分操作通常在下线扫描时批量执行，而非实时每条消息即时加减，避免刷分。

🔒 隐私保障

• ✅ 数据仅存本地，不会上传任何服务器
• ✅ 不在群里公开任何人的好感度/画像信息
• ✅ 查询仅限私聊，且别人查不到你的数据
• ✅ 不记隐私信息（地址/密码/姓名等）

💻 CLI 速查

初始化

# 查看好感度系统状态
python scripts/affection.py status

# 设置初始好感度
python scripts/affection.py init <用户ID> <分数>

# 查看所有规则
python scripts/affection.py rules

# 查看液态记忆状态
python scripts/memory.py stats

# 检查 OneBot 连接
python scripts/onebot_collector.py health

上下线管理

python scripts/session_state.py online                                # 上线
python scripts/session_state.py offline --chat_id <id> --name "群名"  # 指定群下线
python scripts/session_state.py offline --all                         # 全部下线
python scripts/session_state.py register <chat_id> --name "群名"      # 注册活跃群
python scripts/session_state.py status                                # 查看状态

好感度

python scripts/affection.py add <用户ID> <规则key> [原因]
python scripts/affection.py get <用户ID>               # 仅分数
python scripts/affection.py detail <用户ID>             # 详细（管理员用）
python scripts/affection.py brief <用户ID> [小时数]    # 简要（群友自查用）
python scripts/affection.py init <用户ID> <分数>        # 设置初始值
python scripts/affection.py status                      # 系统状态
python scripts/affection.py rules                       # 查看所有规则

画像系统

python scripts/profiles.py load <用户ID>                           # 加载画像
python scripts/profiles.py update <用户ID> --json '<traits>' --source group  # 更新
python scripts/profiles.py list                                     # 列出所有用户
python scripts/profiles.py merge --old '<JSON>' --new '<JSON>'      # 合并数据
python scripts/profiles.py format --profile '<JSON>'                # 格式化输出
python scripts/profiles.py decay                                    # 全局衰减

规则引擎

python scripts/rule_engine.py list                  # 列出有规则文件的群
python scripts/rule_engine.py status <群号>          # 查看状态
python scripts/rule_engine.py eval <群号> --message '{...}'  # 单条评估
python scripts/rule_engine.py batch <群号> --file msgs.json    # 批量评估
python scripts/rule_engine.py reset --group <群号>  # 重置计数器
python scripts/rule_engine.py apply <用户ID> <规则key> "原因"  # 手动加减分

液态记忆底层

python scripts/memory.py store <用户ID> <内容> --tags tag1 tag2 --field preference
python scripts/memory.py recall <用户ID> --query '关键词' --top_k 5
python scripts/memory.py forget <用户ID> <关键词>
python scripts/memory.py stats [--user_id 用户ID]
python scripts/memory.py decay

OneBot 采集器

python scripts/onebot_collector.py health                              # 连接检查
python scripts/onebot_collector.py fetch --group-id <群号> --count 500 # 按范围采集
python scripts/onebot_collector.py scan --group-id <群号> --max-msgs 500  # 全流程
python scripts/onebot_collector.py scan --no-affection                 # 跳过好感度
python scripts/onebot_collector.py scan --no-profile                   # 跳过画像强化
python scripts/onebot_collector.py scan --dry-run                      # 干跑模式