mai-bot/计划.md

私聊拟人性增强分阶段计划

总体目标

• 在尽量保留当前 maibot 主干能力与最近更新的前提下，增强私聊中的连续感、活人感与主动性。
• 优先修复“私聊对象信息容易遗忘”“聊天断开后像失忆”“上下文窗口过于保守”这三类核心问题。
• 再逐步增加“定时跟进”“主动私聊”“关系阶段推进”等能力。
• 落地时坚持“平行新增、契约尽量不变”：
  • 不破坏现有 reply 语义
  • 新能力优先通过新工具、新配置、新任务表、新 metadata 增量扩展
  • 尽量不改现有 WebUI 聊天消息结构与事件结构

借鉴来源

1. MoFox-Core

• 主要借鉴：
  • 私聊对象关系信息常态注入
  • 主动前护栏判断
  • WAITING / IDLE 状态机思路
  • 发完后等待回复、超时再判断是否继续发言的活人感逻辑
• 不直接照搬：
  • AFC / KFC 全套 runtime
  • 强耦合插件系统
  • 其整套数据库结构

2. Muice-Chatbot

• 主要借鉴：
  • 轻量主动开场/问候思路
  • 随机主动话题池思路
• 不直接照搬：
  • 到点直接发送固定文本
  • 过于依赖固定 prompt 的主动对话实现

当前问题

• 私聊对话者信息经常会被忘记，应该被常态化注入。
• 当前上下文管理偏保守，没充分发挥大上下文模型的能力。
• 私聊 runtime 重建后不会自动回灌最近历史，聊天断开一阵子后容易出现“失忆”。
• 人物信息、关系信息、共同经历主要依赖临时检索，缺少稳定默认上下文。
• planner 查到的信息不能稳定传递到 replyer，导致回复阶段再次遗忘。

当前准备增加的能力

• 定时跟进机制：允许 LLM 在当前私聊中创建未来跟进任务，到点后重新唤醒 planner 判断要不要主动开口。
• 主动私聊发送工具：新增不依赖 msg_id 的 send_private_message，作为 replyer 的新发送出口，让主动聊天不再伪装成回复旧消息。
• 到点前护栏机制：加入静默时段、最小主动间隔、可选每日上限，避免技术上能发但体验上打扰。
• 阶段以及主线机制：允许你在私聊中像玩 galgame 一样，和小麦进行逐步推进的互动。
• 为后续私聊状态机预留扩展：后面再补“发完等回复、超时再判断”的活人感机制。

兼容性原则

前后端契约

• 现有 reply 工具保持原语义、原参数、原发送形态不变。
• 新增 send_private_message 与 schedule_private_followup 时，采用与现有 builtin tool 平行的注册、执行、记录方式。
• 现有聊天消息 WsMessage / ChatMessage / MessageSegment 契约尽量不变：
  • 主动私聊发出的消息仍然是普通 bot 可见消息
  • 不新增专用 MessageSegment.type 作为前提
• 现有工具记录结构尽量不变：
  • 继续复用现有 tool record / tool result 链路
  • 新增内容尽量放在 tool_name、tool_data、metadata 中

配置与 WebUI

• 配置面优先平行新增独立配置块，默认值完整，保证旧配置不改也能运行。
• WebUI V1 不应成为主阻塞项：
  • 新功能优先复用现有聊天渲染与工具渲染
  • 后续再考虑做任务管理页、状态展示页等增强 UI

---

阶段 0：开发期稳定化

本阶段要解决的问题

• 当前准备进入连续多阶段改造，如果开发过程中误触自动更新，容易导致本体与 WebUI 版本漂移。
• 一旦前后端版本不一致，后续上下文、工具、调度器相关改造会很难排障。
• private-main 开发期间需要一个尽量稳定、可复现的运行基线。

本阶段要增加/修改的点

• ☐ 断开 WebUI 自动更新检测
• ☐ 断开本体自动更新检测
• ☐ 避免开发期自动拉取或自动提示更新
• ☐ 保留显式手动恢复/更新路径

如何做

• 找到当前 WebUI 与本体的更新检查入口：
  • 启动时自动检查
  • 定时轮询检查
  • 页面内自动提示
• 开发期优先做“禁用自动检查”，而不是修改版本号或伪造远端结果。
• 尽量采用可逆方案：
  • 配置开关
  • 环境变量
  • 显式开发模式判断
• 如果本体和 WebUI 的更新逻辑是分开的，也应分别断开，避免只关一边。

借鉴来源

• 不依赖 MoFox-Core 或 Muice-Chatbot。
• 这是当前 private-main 连续改造前的工程防护阶段。

验收标准

• 启动本体时，不再主动发起自动更新检查。
• 启动 WebUI 时，不再自动弹更新提示或自动轮询更新状态。
• 本体日志和 WebUI 调试输出中，不再出现自动更新任务被触发的痕迹。
• 若后续需要更新，仍存在显式、可控、可手动触发的更新路径。

---

阶段 1：修复私聊遗忘问题

本阶段要解决的问题

• 私聊对象信息经常被忘记。
• 聊天断开后再回来，像从空白状态重新开始。
• planner 查到的信息不稳定，replyer 容易再次遗忘。

本阶段要增加/修改的点

• ☐ 私聊对象信息常态注入
• ☐ runtime 重建时自动回灌最近历史
• ☐ planner 到 replyer 的信息继承增强
• ☐ 上下文选择策略从“纯按条数裁切”调整为“更适合大上下文模型”的策略

本阶段目标预算

• 以“大上下文真正可用，但不盲目塞满”为原则，先把私聊 planner 的目标输入预算定在 256K token 级别。
• 不建议把整整 256K 都让历史消息吃满，应预留系统提示、工具定义、注入块、输出空间。
• 第一版建议按下面的思路分配：
  • 总目标预算：256K
  • 预留给系统提示 / 工具定义 / injected reminders / 输出余量：32K ~ 64K
  • 可用于“历史消息 + 人物信息块 + 共同事件块”的主预算：160K ~ 220K
• replyer 阶段不必与 planner 一样大，可以显著更小：
  • 优先依赖 planner 已整理出的参考信息
  • replyer 可先控制在 32K ~ 64K 级别

本阶段要先定下的几个原则

• 历史回灌 不是滑动窗口本身，而是滑动窗口的前置步骤。
• token 滑窗 不应只做“超了就 pop”，而应做“固定高优先级块保底 + 历史候选池按 token 预算裁切”。
• 人物信息块、当前约定、最近共同事件 的优先级应高于普通旧聊天。
• planner 与 replyer 的上下文策略不必完全一样：
  • planner 负责大窗理解
  • replyer 负责在较小上下文内稳定生成
• 必须保留降级路径：
  • 即使 tokenizer 暂时不可用，也能退回近似估算模式
  • 但默认目标是本地 token 预算裁切，而不是继续硬按条数

如何做

• 为当前私聊补一个轻量信息聚合入口：
  • 优先从现有 person_info
  • 再从 A_memorix 的人物画像/关系证据中补充
  • 统一格式化为稳定上下文块，默认注入 planner
• 在 runtime 重建时，按 session_id 从消息库回灌最近一段真实聊天历史，而不是从空 _chat_history 开始。
• replyer 生成阶段不再过度依赖临时工具结果，而是显式承接 planner 已整理出的稳定参考信息。
• 调整上下文窗口策略：
  • 不再只用固定条数近似控制
  • 引入更大的私聊历史回放范围
  • 优先保留“人物关系/最近共同事件/当前约定”这类高价值上下文

1.1 runtime 历史重建

• 触发时机：
  • 私聊 runtime 首次创建时
  • 私聊 runtime 被回收后再次恢复时
  • 定时跟进任务唤醒私聊 runtime 时
• 基本流程：
  1. 根据 session_id 查询最近一段真实消息
  2. 将消息重新构造成 Maisaka 使用的 LLMContextMessage
  3. 写回 _chat_history
  4. 再叠加本轮新收到的消息与 injected reminders
• 第一版建议：
  • 先取最近 200 ~ 1000 条私聊真实消息作为“候选历史池”
  • 不是全部送给模型，而是交给后续 token 滑窗裁切
• 注意：
  • 历史重建应优先复用现有消息入库格式和 SessionBackedMessage 构建逻辑
  • 不要单独造一套“历史专用消息对象”

1.2 本地 tokenizer / token 预算器

• 当前项目里已有 token 使用统计，但那是模型返回 usage 后的结果，不足以做请求前选窗。
• 因此本阶段需要新增一个“请求前 token 估算器”抽象层。
• 目标不是一开始追求 100% 精确，而是先把“按 token 预算裁切”跑通。
• 建议方案：
  • 新增统一的 context_token_counter / prompt_token_estimator
  • 输入为即将送给模型的消息列表或其序列化结果
  • 输出为估算 token 数
• tokenizer 选择建议：
  • 优先选择与当前 OpenAI-compatible 请求栈兼容的本地 tokenizer 方案
  • 若误差验证可接受，可直接作为私聊上下文预算器
  • 若误差过大，再考虑换成更贴近目标模型的 tokenizer
• 降级方案：
  • tokenizer 初始化失败时，可暂时退回“字符数 / 中文字数近似预算”
  • 但只作为 fallback，不作为主路径

1.3 token 滑动窗口

• 目标不是“把 256K 塞满”，而是“尽量稳定地用到 256K 级别能力”。
• 建议采用“两层预算”：
  • 第一层：固定保底块
  • 第二层：历史滑窗块
• 固定保底块建议包含：
  • 系统提示
  • 当前私聊对象信息块
  • 当前约定 / 当前跟进原因
  • 最近共同事件摘要
  • 必要的工具定义
• 历史滑窗块建议逻辑：
  1. 从最近消息开始向前累加
  2. 每加入一条，重新累加 token
  3. 超预算则停止
  4. 保证最近几轮真实对话优先进入窗口
• 不建议简单地“全拼后从头一直 pop 到合法”作为唯一策略。
• 更推荐：
  • 先固定高优先级块
  • 再对普通历史做从近到远的预算填充

1.4 高优先级上下文保底

• 下面这些信息不应与普通旧聊天放在同一优先级：
  • 当前私聊对象是谁
  • 你和对方目前是什么关系
  • 近期共同事件
  • 最近承诺/约定
  • 当前定时跟进原因
• 这些内容即使在历史极长的情况下，也应尽量保底进入窗口。
• 这部分内容应从：
  • person_info
  • A_memorix 的人物画像 / 关系证据 / episode
  • 当前会话内最近承诺 统一汇总出来

1.5 planner → replyer 信息继承

• 目前 replyer 容易再次遗忘，核心原因之一是它并不稳定承接 planner 已经查到和整理过的信息。
• 第一版建议：
  • planner 输出时显式生成“稳定参考信息块”
  • replyer 直接消费这块，而不是只依赖再看一遍历史
• 这样即使 replyer 窗口比 planner 小很多，也能保持人物信息连续性。

1.6 配置建议

• 本阶段建议新增但保持默认兼容的配置项，例如：
  • chat.private_context_rebuild_enabled
  • chat.private_context_rebuild_recent_limit
  • chat.private_context_token_budget
  • chat.private_context_reserved_tokens
  • chat.private_context_inject_relation_info
  • chat.private_context_recent_events_limit
  • chat.replyer_context_token_budget
• 默认值应尽量保守，避免对现有用户造成突然的延迟或成本上升。

借鉴来源

• MoFox-Core
  • 借鉴其“关系信息 + 印象 + 偏好 +聊天流印象”统一拼装进私聊上下文的思路
• Muice-Chatbot
  • 基本不借鉴实现，只参考“最近历史 + 旧记忆回注入”的轻量骨架

验收标准

• 同一个私聊会话在沉默一段时间后再次收到消息，bot 不应明显忘记对方是谁。
• 重建后的 runtime 能带上最近一段真实聊天历史，而不是只看最后一条消息。
• 私聊中不需要用户重复提醒，bot 也能较稳定记住：
  • 对方称呼
  • 近期正在聊的事
  • 最近约定/承诺
• 在日志或调试信息里，能看到“重建历史条数”“对象信息注入块”的明确痕迹。
• 能在日志或调试信息里看到：
  • 候选历史条数
  • 最终入窗条数
  • 估算 token 数
  • 被预算裁掉的原因
• 在高上下文测试下，planner 能稳定工作在 256K 级别预算附近，而不是仍然被 60 条历史限制住。
• replyer 即使使用更小窗口，也不应明显丢失 planner 已确认的人物信息。

---

阶段 2：定时跟进 V1

本阶段要解决的问题

• 当前私聊没有“我之后再来找你”的能力。
• 即使用户和 bot 约好了未来某个时间点，系统也无法主动在那时重新思考。
• 需要主动发言时，只能强行伪装成 reply(msg_id=...)，不自然。
• 如果直接让 planner 裸写 message_text 并发送，会让主动私聊和普通回复走成两套文案体系。

本阶段要增加/修改的点

• ☐ 新 builtin tool：schedule_private_followup
• ☐ 新 builtin tool：send_private_message
• ☐ 私聊定时跟进任务表
• ☐ 后台调度器
• ☐ runtime 的“带 reminder 唤醒 planner”入口

如何做

• schedule_private_followup
  • 只允许在当前私聊里创建未来任务
  • 记录触发时间、跟进原因、当时承诺话术
• 后台调度器
  • 轮询 pending 任务
  • 到点后 claim 任务并唤醒当前私聊 runtime
• runtime 新入口
  • 以 <system-reminder> 形式注入“这不是用户新消息，而是一次到点跟进触发”
  • planner 基于当前上下文重新判断要不要发
• send_private_message
  • 不直接裸发 message_text
  • 而是作为 replyer 的新发送语义出口
  • 复用现有人设、表达习惯、replyer 文案生成链路
  • 最终仍复用现有 send_service / Platform IO / 写库 / 历史同步

借鉴来源

• MoFox-Core
  • 借鉴“主动思考不是直接发消息，而是先重进上下文再判断”的理念
• Muice-Chatbot
  • 明确不采用其“到点直接发固定文本”的路径
• 当前 maibot 架构
  • 延续“planner 负责想、replyer 负责写”的职责分离，不让主动私聊成为例外

验收标准

• 私聊中可以成功创建一条未来跟进任务。
• 到点后系统会唤醒 planner，而不是直接发写死文本。
• planner 可以根据当前情况选择：
  • 主动发一条消息
  • 什么都不发，直接结束
  • 再次约下一次跟进
• 主动发出的消息是普通 bot 消息，不带旧消息引用。
• 主动发出的文本风格应与普通 reply() 路径保持一致，不应明显像另一套文案系统。
• 发送成功后仍会进入：
  • 现有消息存储
  • Maisaka 历史同步
  • memory automation

send_private_message 设计细化

工具职责

• 在当前私聊会话中主动发出一条可见消息。
• 不依赖 msg_id。
• 不默认带引用回复。
• 语义上是“主动开口”，但文案生成仍应走 replyer，而不是绕开 replyer 直接裸发。

参数设计建议

• 不建议把主参数设计成裸 message_text。
• 更推荐让 planner 提供“为什么说”，让 replyer 负责“具体怎么说”。
• 第一版建议参数：
  • proactive_reason
    • 类型：string
    • 含义：这次主动发言的直接理由，作为 replyer 的“最新推理”
  • reference_info
    • 类型：string
    • 含义：本轮主动发言依赖的事实性参考信息
  • trigger_source
    • 类型：string
    • 含义：触发来源，例如 scheduled_followup
  • assistant_commitment_text
    • 类型：string
    • 含义：若这次主动发言是在延续先前承诺，可作为风格一致性参考

实现建议

• send_private_message 应复用当前 reply() 已有的 replyer 生成链路。
• 推荐执行路径：
  1. planner 调用 send_private_message
  2. tool 内部获取当前会话 replyer
  3. 以“主动发言场景”调用 generate_reply_with_context(...)
  4. 此时 reply_message=None
  5. reply_reason=proactive_reason
  6. reference_info 中整理注入 reference_info + assistant_commitment_text + trigger_source
  7. replyer 生成文本后，再复用现有发送链路发出

返回建议

• 成功时至少返回：
  • session_id
  • generated_message_text
  • sent_message_id
  • maisaka_source_kind
• 失败时返回明确原因：
  • 非私聊
  • replyer 生成失败
  • 发送失败

---

阶段 3：主动私聊护栏与轻量主动能力

本阶段要解决的问题

• 即使有定时跟进，系统也缺少“主动前的工程护栏”。
• 后续如果要做更常态化的主动私聊，没有最小打扰控制会很容易打扰用户。

本阶段要增加/修改的点

• ☐ 静默时段
• ☐ 最小主动间隔
• ☐ 可选每日上限
• ☐ skip reason 与 guardrail snapshot
• ☐ 轻量主动开场/问候 fallback

如何做

• 在“任务到期”与“真正唤醒 planner”之间插入规则层：
  • 私聊校验
  • 状态校验
  • 静默时段判断
  • 最小主动间隔判断
  • 可选每日上限判断
• 对被跳过的任务记录：
  • skip_reason
  • guardrail_snapshot_json
• 为未来“非约定型主动私聊”预留轻量主动开场能力：
  • 轻问候
  • 轻话题冒泡
  • 但此时仍不做完整主动聊天系统

借鉴来源

• MoFox-Core
  • 重点借鉴其主动思考调度器中的工程护栏思路
• Muice-Chatbot
  • 借鉴其轻量问候/轻话题池思路，仅作为 fallback

验收标准

• 明显不适合打扰的时段，任务会被安全跳过或延后，而不是强行唤醒 planner。
• 日志中能明确看到“为什么没发”的 skip reason。
• 即使以后加入更强主动私聊，这一层规则也能直接复用。

---

阶段 4：私聊状态机活人感增强

本阶段要解决的问题

• 当前主动私聊即使能发，也缺少“发完之后等你回复”的真实感。
• 系统无法区分“及时回”“晚回”“一直没回”。

本阶段要增加/修改的点

• ☐ WAITING / IDLE 私聊状态机
• ☐ 主动发送后的等待态
• ☐ 超时后再判断是否继续等、追问或闭嘴
• ☐ 连续超时计数与打扰保护

如何做

• 在阶段 2 的基础上，扩展主动发送后的状态记录：
  • 最近一次主动发送时间
  • 是否正在等待回复
  • 等待配置
  • 连续超时计数
• 收到用户消息时区分：
  • reply_in_time
  • reply_late
  • new_message
• 等待超时后，再重新进行一轮轻量判断：
  • 继续等
  • 轻追问
  • 结束等待，不再打扰

借鉴来源

• MoFox-Core
  • 这是最核心的借鉴来源，重点是其 WAITING / IDLE 与超时后再思考的设计
• Muice-Chatbot
  • 基本不借鉴

验收标准

• 主动发言后，系统能进入等待态，而不是把这件事完全忘掉。
• 用户及时回复和很久后才回复时，系统的反应能出现可区分差异。
• 多次未回复后，系统会自动降低继续打扰的倾向。

---

阶段 5：关系阶段与主线推进

本阶段要解决的问题

• 当前即使记住了人、能主动聊，也还没有真正的关系推进结构。
• 缺少“朋友 → 更亲密阶段”的可持续演进逻辑。

本阶段要增加/修改的点

• ☐ 关系阶段状态
• ☐ 阶段推进条件
• ☐ 近期主线事件/共同事件摘要
• ☐ 更适合私聊恋爱化推进的上下文注入

如何做

• 在现有 person_info / A_memorix 证据层之上，增加一层更明确的关系状态表达。
• 阶段推进仍然尽量保持轻规则，不急着做全硬编码 romance engine。
• 优先做：
  • 阶段状态
  • 最近共同事件摘要
  • 对阶段敏感的 prompt 注入
• 后续再看是否要加入更强规则。

借鉴来源

• MoFox-Core
  • 借鉴其“关系分数 + 关系阶段 + 印象文案”的分层思路
  • 不直接采用其当前阶段命名作为最终产品逻辑
• Muice-Chatbot
  • 不足以支撑这一阶段

验收标准

• 私聊中的称呼、关心方式、主动发言方式，会随关系阶段出现可感知变化。
• 最近共同事件能够被作为关系推进依据，而不是每次都从零开始。
• 系统在长期私聊中呈现出更稳定的关系连续性，而不是只有短期记忆连续性。

---

配置与 WebUI 影响评估

配置面

• 配置面预计是“小改”，不是大改。
• 建议新增独立配置块，例如：
  • private_followup.enabled
  • private_followup.scheduler_interval_seconds
  • private_followup.quiet_hours_start
  • private_followup.quiet_hours_end
  • private_followup.min_interval_between_proactive_seconds
  • private_followup.max_daily_followups_per_session
  • private_followup.inject_relation_info
  • private_followup.recent_shared_events_limit
• 原则：
  • 默认值完整
  • 老配置不动也能跑
  • 优先改模板并递增版本号

WebUI 面

• V1 到 V3 原则上不需要大改聊天协议。
• 聊天渲染层：
  • send_private_message 发送的仍然是普通 bot 消息
  • 不要求新增 MessageSegment.type
• 工具渲染层：
  • 新工具复用现有 tool record 展示链路
  • 前端最多看到新的 tool_name
• 可选增强：
  • 定时跟进任务列表
  • 任务取消/重试管理页
  • 主动护栏状态可视化
  • 私聊状态机状态展示

分阶段验收顺序建议

• 第 0 阶段先稳定开发环境，避免自动更新打断改造过程。
• 第一阶段先解决遗忘与历史重建，不急着上主动聊天。
• 第二阶段打通定时跟进 V1。
• 第三阶段补主动护栏与轻量主动能力。
• 第四阶段再做 WAITING / IDLE 状态机。
• 第五阶段最后做关系阶段与主线推进。

当前最推荐的开发顺序

1. 断开 WebUI / 本体自动更新检测
2. 私聊对象信息常态注入
3. runtime 历史重建
4. planner → replyer 信息继承增强
5. schedule_private_followup
6. send_private_message
7. send_private_message 的 replyer 驱动实现
8. 后台调度器与 runtime 唤醒入口
9. 到点前护栏
10. WAITING / IDLE 扩展
11. 阶段/主线推进