# 小牛群聊 BOT

## 定位

`ai_auto_response` 不再是“随机插话插件”，而是一个长期在线的拟人化群友 `小牛`。

目标是三件事：

- 在群里像一个混久了的真人，不像客服
- 该接问题时接得住，不该说话时会装死
- 能记人、记群、记关系，并在合适的时候自然用起来

这份 README 只描述 `plugins/ai_auto_response` 当前设计与实现落点，不调整仓库根目录。

## 当前目录分层

- [`main.py`](/d:/learn/abot/plugins/ai_auto_response/main.py)
  插件入口与主编排，只保留消息流转、组件装配、发送消息。
- [`config.toml`](/d:/learn/abot/plugins/ai_auto_response/config.toml)
  小牛的运行配置。
- [`persona/`](/d:/learn/abot/plugins/ai_auto_response/persona)
  人设文本，目前核心是 [`xiaoniu.txt`](/d:/learn/abot/plugins/ai_auto_response/persona/xiaoniu.txt)。
- [`core/`](/d:/learn/abot/plugins/ai_auto_response/core)
  统一决策、prompt、LLM 结果解析、回复规划。
- [`context/`](/d:/learn/abot/plugins/ai_auto_response/context)
  上下文总装配、引用处理、图片处理。
- [`memory/`](/d:/learn/abot/plugins/ai_auto_response/memory)
  短期消息、向量召回、群关系、群事实、群画像推断、群级记忆聚合。
- [`profile/`](/d:/learn/abot/plugins/ai_auto_response/profile)
  人设装配和群画像解析。
- [`runtime/`](/d:/learn/abot/plugins/ai_auto_response/runtime)
  心流、限流、日志摘要。
- [`safety/`](/d:/learn/abot/plugins/ai_auto_response/safety)
  过滤、攻击识别、去重。
- [`docs/`](/d:/learn/abot/plugins/ai_auto_response/docs)
  设计文档沉淀。

## 已落地的模块

### core

- [`decision_flow.py`](/d:/learn/abot/plugins/ai_auto_response/core/decision_flow.py)
  主流程进入模型前的统一决策装配。
- [`llm_client.py`](/d:/learn/abot/plugins/ai_auto_response/core/llm_client.py)
  LLM 调用客户端适配层。
- [`triggers.py`](/d:/learn/abot/plugins/ai_auto_response/core/triggers.py)
  触发器识别与优先级判断。
- [`response_planner.py`](/d:/learn/abot/plugins/ai_auto_response/core/response_planner.py)
  本地粗筛和回复模式规划。
- [`prompt_builder.py`](/d:/learn/abot/plugins/ai_auto_response/core/prompt_builder.py)
  统一构造给模型的用户提示词。
- [`llm_result_parser.py`](/d:/learn/abot/plugins/ai_auto_response/core/llm_result_parser.py)
  统一解析模型 JSON 结果，过滤 echo 和异常结构。
- [`reply_formatter.py`](/d:/learn/abot/plugins/ai_auto_response/core/reply_formatter.py)
  统一做回复裁剪、拆句、多条发送控制、日志预览。

### context

- [`context_builder.py`](/d:/learn/abot/plugins/ai_auto_response/context/context_builder.py)
  汇总最近消息、成员记忆、群记忆、引用/图片上下文。
- [`quote_context.py`](/d:/learn/abot/plugins/ai_auto_response/context/quote_context.py)
  引用消息解析。
- [`image_context.py`](/d:/learn/abot/plugins/ai_auto_response/context/image_context.py)
  图片跟评识别、图片安全提示、图片附件准备。

### memory

- [`memory_store.py`](/d:/learn/abot/plugins/ai_auto_response/memory/memory_store.py)
  短期消息、成员画像、followup 会话读取。
- [`vector_memory.py`](/d:/learn/abot/plugins/ai_auto_response/memory/vector_memory.py)
  向量召回与写入。
- [`group_memory_profile.py`](/d:/learn/abot/plugins/ai_auto_response/memory/group_memory_profile.py)
  从近 48 小时消息和群摘要推断群长期知识域、风格、关注点。
- [`group_memory.py`](/d:/learn/abot/plugins/ai_auto_response/memory/group_memory.py)
  聚合群画像、群关系、群事实，并负责群级长期快照回写与记忆重排摘要。
- [`social_memory.py`](/d:/learn/abot/plugins/ai_auto_response/memory/social_memory.py)
  轻量构造群关系上下文，给模型提示谁常和谁互动、谁在接谁的话。
- [`group_facts.py`](/d:/learn/abot/plugins/ai_auto_response/memory/group_facts.py)
  轻量提炼群事实候选，补充“这个群长期在聊什么、谁更像答疑位、最近有什么稳定吐槽”。
- [`memory_ranker.py`](/d:/learn/abot/plugins/ai_auto_response/memory/memory_ranker.py)
  按当前这次话题对成员记忆、群关系、群事实、向量召回做相关性重排。
  同时配合群关系快照、群事实快照，把群级长期记忆慢慢沉淀进向量层。

### profile

- [`group_profile.py`](/d:/learn/abot/plugins/ai_auto_response/profile/group_profile.py)
  把人工群配置和历史推断结果合成最终群画像。
- [`persona_engine.py`](/d:/learn/abot/plugins/ai_auto_response/profile/persona_engine.py)
  人设文本装配和群风格叠加。

### runtime

- [`flow_manager.py`](/d:/learn/abot/plugins/ai_auto_response/runtime/flow_manager.py)
  心流状态管理。
- [`cooldown.py`](/d:/learn/abot/plugins/ai_auto_response/runtime/cooldown.py)
  回复频率和 burst 限流。
- [`logging.py`](/d:/learn/abot/plugins/ai_auto_response/runtime/logging.py)
  一行摘要日志，包含记忆命中和重排摘要。

### safety

- [`filters.py`](/d:/learn/abot/plugins/ai_auto_response/safety/filters.py)
  ignore / prompt attack / coding work / @别人识别。
- [`dedup.py`](/d:/learn/abot/plugins/ai_auto_response/safety/dedup.py)
  消息去重和回复去重。

## 当前主流程

主链路现在是：

1. `can_process`
   只做硬过滤。
2. `process_message`
   做消息标准化、群画像解析、记忆装配、粗筛、调用模型、发送回复。
3. `LLM 一次决策`
   在一次交互里同时完成：
   - 判断当前这次到底在聊什么
   - 判断这次是否值得回复
   - 选择回复强度
   - 产出最终回复文本

也就是说，现在的目标不是“本地规则决定一切”，而是：

`本地硬过滤 + 本地粗筛 + 模型负责高语境判断`

## 当前能力边界

已经支持：

- 群画像驱动的人设偏置
- 成员长期画像读取
- 30 条最近上下文窗口
- 群关系提示
- 群关系 / 群事实快照回写向量库
- 记忆相关性重排
- 向量记忆召回
- 引用消息解析
- 图片附件随模型请求发送
- 最近图片跟评识别
- 回复拆成 1 到 2 条短消息
- 静默忽略 prompt attack
- 非 `@小牛` 的编码代劳请求直接跳过
- LLM 失败时不做本地兜底，直接装死

还在持续建设：

- 结构化群事实记忆
- 群关系长期压缩写回
- 更强的多话题分辨
- 更细的称呼强度控制
- 更细的记忆命中可解释性

## 设计文档

这几个文档是当前重构的设计基线：

- [`README_humanization_v2.md`](/d:/learn/abot/plugins/ai_auto_response/docs/README_humanization_v2.md)
  总体方案收敛。
- [`README_decision_flow.md`](/d:/learn/abot/plugins/ai_auto_response/docs/README_decision_flow.md)
  统一响应决策流。
- [`README_social_memory.md`](/d:/learn/abot/plugins/ai_auto_response/docs/README_social_memory.md)
  群关系记忆。
- [`README_group_facts.md`](/d:/learn/abot/plugins/ai_auto_response/docs/README_group_facts.md)
  群事实长期记忆。

## 当前重构原则

- 不继续把复杂逻辑堆进 `main.py`
- 兼容层可以暂时保留，但新能力优先放进清晰目录
- 本地规则只负责安全、去重、限流、成本控制
- 真正像群友的判断，尽量交给模型
- 不做割裂体验的本地固定兜底
- 只处理当前发言对应的一个话题，不做多线程并行聊天

## 下一阶段

接下来会继续拆三块：

- 群关系从“可回写的长期记忆”继续升级到“更稳定的关系强度演化”
- 群事实从“轻量摘要”补到“群内角色、搭子、稳定背景、固定梗”
- 让记忆权重和命中原因更容易从日志里观察与校准

等这两层补起来，小牛才会更像“在群里待了很久的人”，而不是“会读上下文的机器人”。