HeXi/hexi/plugins/nonebot_plugin_galgame_card/CLAUDE.md

CLAUDE.md — 群聊人设卡插件开发文档

本文件是本插件内开发的唯一入口文档；需要项目全局信息（Poetry 命令、启动方式、测试约定）时再查项目根目录的 CLAUDE.md。详细设计定稿见同目录 DESIGN.md。

插件概述

基于群聊语料蒸馏群成员的形象风格，生成 galgame 风格人物卡（九段画像）。

• 目标：生成"人的画像"，不是关系网分析；样貌参考为虚构，永远带标注
• 隐私硬约束：只采集 opt-in 成员；敏感数据本地正则替换为占位符，绝不经过 LLM
• 维度隔离：每个 (group_id, user_id) 是独立人设，跨群不混

目录结构

nonebot_plugin_galgame_card/
├── __init__.py   入口层：on_message 采集器（鉴权/采样/调治理落库）
├── models.py     数据层：五张表（persona_group/user/chat_log/impression/summary）
├── repository.py 数据层：仓储（来源无关，所有读写唯一入口）
├── processor.py  治理层：纯函数（五维提取/噪声/脱敏），可单测
├── config.py     插件配置（WEB_ENABLE/WEB_USERNAME/WEB_PASSWORD/WEB_SECRET_KEY）
├── web.py        Web 管理后台后端（/galgame_card/api/*，JWT 登录，仿 learning_chat）
├── web/index.html 管理后台前端（单文件，无需构建）
├── DESIGN.md     设计定稿（数据模型/流水线/九段协议/证据纪律）
└── CLAUDE.md     本文件

Web 管理后台：http://<host>:<port>/galgame_card（默认 admin/galgame，可在 .env 改 WEB_*）。功能：群开关、参与者增删、语料/印象/画像浏览与删除、清空群数据。路由在 @driver.on_startup 里注册，改后端需重启 bot。

核心设计（速览，细节见 DESIGN.md）

1. 两级闸门：群开关 persona_group.enabled（默认关）+ 个人 opt-in persona_user，都过才采集
2. 两级流水线：语料 →（攒够 N 条）→ 印象（LLM 自然语言，增量中间层）→（攒够 M 条）→ 画像（九段 markdown，版本化）
3. 消息五维：内容 / 谁发的 / 发给谁（回复/@）/ 几点发的 / 被回复内容快照——只存治理后纯文本
4. 脱敏四层（desensitize()）：明确模式（最长优先排序防截胡）→ 定位式（同条关键词+值）→ 跨条语境（关键词在附近消息）→ 兜底（保守替换）
5. 九段画像协议：身份印象/性格特征/说话风格/口头禅语录/兴趣话题/相处模式/时间画像/样貌参考(虚构)/不确定信息
6. 总结路径不进消息 handler：LLM 调用只在调度器触发，防延迟/限流

开发命令

# 跑本插件测试（治理层纯函数，9+ 个用例）
poetry run pytest tests/test_persona_processor.py

# 全量测试
poetry run pytest

# 启动/重启验证：PyCharm 的 "start bot" 运行配置（勿用 bat 脚本）

数据库

• orm 默认库：data/nonebot_plugin_orm/db.sqlite3（不是 hexi/data/data.db）
• 建表：bot 启动时 orm 自动 create_all（新表加在 models.py 里即可，重启生效）
• 配置键是 SQLALCHEMY_DATABASE_URL（本插件未设置，走默认库）

开发注意事项（踩过的坑）

0. ⚠️ orm 启动自动同步会清空表数据：.env 里 ALEMBIC_STARTUP_CHECK=false 时，nonebot_plugin_orm 每次启动都 autogenerate 同步数据库模式，模型一有变更（改 models.py）就会重建表、清空全部数据（2026-08-11 实测踩坑，全表被清）。已在本插件 __init__.py 导入期把 migrate.sync 替换为安全空操作。今后 schema 演进只准通过 repository.ensure_schema() 显式 ALTER，改完 models.py 后要在重启前手动执行对应 ALTER（或加进 ensure_schema）。
1. on_message 必须 block=False：否则事件流被拦截，群里其他插件全废
2. 只收群消息：handler 参数注解 GroupMessageEvent（类型注解即过滤器）
3. 脱敏正则排序：身份证/银行卡必须在手机号之前，否则手机号截胡身份证数字段
4. 定位式替换只替换值、保留关键词：密码是 xyz789 → 密码是 [密码]，关键词不能丢
5. 测试不能裸 import 包：__init__.py 触发 NoneBot 初始化，用 importlib 按路径加载 processor（见 tests/test_persona_processor.py，与 test_rate_limit 同款）
6. 总结/印象生成：绝不在消息 handler 里调 LLM，走调度层（apscheduler）
7. 仓储并发：add_summary 版本自增有并发撞 UNIQUE 风险，调度层加锁保护

当前进度

• ✅ 数据层：五表 + 仓储（含群开关、滚动淘汰、版本自增）
• ✅ 采集层：消息路径（监控→鉴权→治理→脱敏→采样→落库）
• ✅ Web 管理后台：/galgame_card（群开关、参与者、数据浏览/清理；Chrome 已实测）
• ⏳ QQ 命令集：开启人设采集 / 加入人设 / 退出人设 / 查看人设（Web 已覆盖同等功能，QQ 命令可选做）
• ⏳ 总结路径：LLM 客户端、印象生成、九段画像生成、调度触发
• ⏳ 呈现层：人物卡展示/图片渲染

待决策点

• 触发阈值（印象 ≥50 条新语料 / 画像 ≥5 条新印象，⏳ 待调）
• 脱敏兜底位数（裸数字 ≥6 位默认替换 [账号]，保守优先；误杀多可提到 8 位，动 BARE_DIGITS_RE）
• 密保答案场景（中文值正则误杀率高，方案待定）
• 命令名与权限（超管/群主）