diff --git a/计划.md b/计划.md index 08841863..3089daa3 100644 --- a/计划.md +++ b/计划.md @@ -1,145 +1,244 @@ -# 私聊定时消息 V1 计划 +# 私聊定时跟进 V1 计划 + +## 当前结论 +- 本方案只支持私聊,不支持群聊。 +- 旧草案中的“到点直接发送预先写死的 `message_text`”不再作为 V1 主方案。 +- V1 改为“定时器负责唤醒当前私聊会话的正常思考流程”,由 LLM 基于到点时的当前上下文决定是否主动发言。 +- 为了支持“主动发言但不强行回复某条旧消息”,需要新增一个与 `reply` 平行的主动私聊发送工具。 +- 平台出口、消息存储、Maisaka 上下文写回、Napcat 适配等链路应尽量复用现有实现,不新造一条发送通道。 ## 目标 -- 只支持私聊,不支持群聊。 -- 由 LLM 在当前轮直接写好未来要发送的文本。 -- 到点后不再唤醒 LLM,不再二次规划,直接发送。 -- 尽量复用现有消息发送、消息存储、Maisaka 上下文、tool call 记录链路。 +- 让 LLM 可以在当前私聊里创建一条未来触发的“定时跟进任务”。 +- 到点后不直接发固定文本,而是重新进入该私聊的正常 planner 思考流程。 +- 到点思考时直接复用现有上下文窗口、原有 planner prompt、原有工具机制。 +- 如果 planner 判断现在适合主动发言,则调用新的主动私聊发送工具发出消息。 +- 如果 planner 判断现在不适合打扰,则可以不发言并直接结束本轮。 ## 明确不做 -- 不做群聊定时发言。 -- 不做“到点后再让 LLM 判断该不该发”。 -- 不做 `intent_key` 这类没有明确行为差异的分类字段。 -- 不做复杂任务编排,只做“一条任务,到点发一条文本消息”。 +- 不做群聊版定时跟进。 +- 不做跨会话发送;当前私聊中创建的任务,只能唤醒当前私聊,也只能向当前私聊主动发言。 +- 不做“任意指定目标用户/目标 session 的消息发送器”。 +- 不做复杂多意图分类,不引入冗余的 `intent_key`。 +- 不伪造一条新的用户入站消息来驱动到点逻辑。 +- 不把主动 follow-up 强行伪装成 `reply(msg_id=...)`。 + +## 核心方案 + +### 1. 定时器从“文本发送器”改为“流程进入器” +- 当前用户在私聊中表达未来某个时间点需要 bot 主动跟进。 +- Planner 调用新的定时跟进工具,写入一条未来任务。 +- 到点后,后台调度器不直接发消息,而是唤醒对应私聊会话的 Maisaka planner。 +- planner 结合当前上下文重新判断: + - 是否应该主动发言 + - 现在该说什么 + - 是否应该放弃本次跟进 + - 是否应该重新约下一个时间点 + +### 2. 新增主动私聊发送工具 +- 保留现有 `reply`: + - 语义仍然是“针对某条已有消息进行回复” + - 仍然依赖 `msg_id` +- 新增 `send_private_message`: + - 语义是“在当前私聊里主动发出一条可见消息” + - 不依赖 `msg_id` + - 不默认引用旧消息 +- 这样可以避免 QQ/Napcat 侧展示成“永远在回复某条旧消息”,更符合真实私聊中的自然主动聊天。 + +### 3. 发送出口继续复用现有通道 +- `send_private_message` 不新造平台出口。 +- 它和 `reply` 一样,最终复用现有: + - `send_service` + - `Platform IO` + - 现有 driver / adapter + - Napcat 出口 +- 这样发送成功后,仍可复用现有: + - 消息写库 + - memory automation + - Maisaka 历史同步 ## 端到端流转链路 ### 1. 用户触发 -- 用户在私聊中表达未来某个时间点需要 bot 主动发一条消息。 -- 当前消息照常进入现有接收链路: +- 用户在私聊中表达未来某个时间点需要 bot 主动跟进。 +- 当前消息照常进入现有链路: - 消息接收 - HeartFlow runtime - Timing Gate - Planner ### 2. Planner 决策 -- Planner 在分析当前局势后,直接调用新的定时消息工具。 -- 工具由 Planner 直接可见,不走 deferred tools。 -- 理由: - - 这是明确的主流程动作,不是低频扩展工具。 - - 用户说“明天早上提醒我”时,Planner 应当能直接执行,不应先 `tool_search`。 +- Planner 分析当前局势后,可直接调用定时跟进工具。 +- 工具应为 planner 直接可见的 action tool,不走 deferred tools。 +- 同一轮里,planner 仍可继续: + - 调用 `reply` + - 正常回复用户 + - 告知用户已经记下这次未来跟进 ### 3. 工具执行 -- 新工具暂定名:`schedule_private_message` +- 暂定工具名:`schedule_private_followup` - 工具接收参数后,直接写入任务存储。 -- 工具返回成功结果给当前 Planner。 -- 该 tool result 和其他工具一样,走现有 tool call 记录与上下文写回链路。 -- Planner 下一轮可继续: - - 调用 `reply` - - 告知用户“已经帮你定好了” - - 或继续补充说明 +- 工具只允许操作当前私聊会话,不允许 LLM 指定别的 session。 +- tool result 与其他工具一样,复用现有 tool call 记录与上下文链路。 -### 4. 调度器轮询 +### 4. 后台调度器轮询 - 独立后台调度器定期扫描到期任务。 - 扫描条件: - `status = pending` - - `send_at <= now` - - `chat_type = private` -- 调度器取出任务后尝试执行发送。 + - `send_at_ts <= now` +- 任务取出后,不直接发送,而是进入“会话唤醒”流程。 -### 5. 到点发送 -- 调度器直接调用现有 `send_service.text_to_stream_with_message(...)` -- 发送参数要求: - - `text = 任务里保存的 message_text` - - `stream_id = 任务对应的私聊 session_id` +### 5. 会话唤醒 +- 调度器根据 `session_id` 定位或恢复对应私聊会话。 +- 如果对应 runtime 当前不在内存中,应先恢复/创建该会话的 Maisaka runtime。 +- 调度器调用一个新的运行时入口,例如: + - `trigger_scheduled_followup(task)` + - 或同等语义的方法 +- 这个入口负责以“额外注入消息”的形式进入 planner,而不是伪造用户消息。 + +### 6. 到点后的 planner 行为 +- 唤醒后的 planner 继续使用项目原有的主 prompt。 +- 同时在请求尾部追加一条 `injected_user_messages`,内容使用项目已有的 `` 风格。 +- planner 基于当前上下文重新分析后,可以: + - 调用 `send_private_message` + - 调用 `reply`(仅当它明确需要围绕某条旧消息回复时) + - 调用 `finish` + - 再次调用 `schedule_private_followup` + +### 7. 主动发送 +- 当 planner 判断应主动发言时,调用 `send_private_message`。 +- `send_private_message` 直接复用现有 `send_service.text_to_stream_with_message(...)`。 +- 发送参数应满足: + - `stream_id = 当前 ToolExecutionContext.session_id` - `storage_message = True` - `sync_to_maisaka_history = True` - - `maisaka_source_kind = "scheduled_send"` -- 这样发送后会自动: - - 走现有平台发送链路 - - 写入现有消息存储 - - 触发现有 memory automation - - 在 runtime 仍存活时同步写入 Maisaka 上下文 +- `maisaka_source_kind` 建议使用新的主动发送来源标记,例如: + - `proactive_send` + - 若后续需要区分定时唤醒来源,可再在 metadata 中补充 `trigger_source=scheduled_followup` -### 6. 发送后的上下文表现 -- 如果该 session 的 runtime 当前仍在 `heartflow_manager.heartflow_chat_list` 中: - - 发送完成后,消息会立刻追加进 `_chat_history` -- 如果 runtime 当前不在内存中: - - 这条消息仍会进入现有消息存储 - - 之后会话重新活跃时,至少数据库层面仍保留这条 bot 已发送消息 -- V1 先不为“runtime 不在内存时立即补上下文”额外新造链路 -- 先复用现有发送与存储通道 +### 8. 任务完成 +- 本次唤醒流程成功结束后,原任务应被标记为完成。 +- “完成”不等于“一定发了消息”。 +- 只要本次唤醒和 planner 处理已成功结束,即可完成任务,并记录最终动作结果。 ## 工具设计 -### 工具名 -- `schedule_private_message` +### 工具 1:`schedule_private_followup` -### 工具职责 -- 为当前私聊创建一条未来发送任务 -- 可选择覆盖当前私聊中尚未执行的旧任务 +#### 工具职责 +- 为当前私聊创建一条未来触发的定时跟进任务。 +- 任务到点后唤醒当前私聊的 planner,而不是直接发送固定文本。 -### 工具参数 +#### 工具参数 - `send_at` - 类型:`string` - - 含义:发送时间 - - 约定:先存标准化后的绝对时间字符串,内部落库再转时间戳 -- `message_text` + - 含义:触发时间 + - 建议:由 LLM 提供标准化后的绝对时间字符串 +- `followup_reason` - 类型:`string` - - 含义:到点时直接发送的文本 + - 含义:这次未来跟进的原因/事项摘要 + - 作用:到点时注入 reminder,帮助 planner 理解为什么会被唤醒 +- `assistant_commitment_text` + - 类型:`string` + - 含义:当前这轮里,bot 对用户作出的那句“未来会来找你/提醒你/跟进你”的承诺话术 + - 作用:到点时也注入给 planner,帮助它和之前的承诺保持一致 - `replace_existing` - 类型:`boolean` - - 含义:是否覆盖当前私聊里尚未执行的旧任务 + - 含义:是否覆盖当前私聊中尚未执行的旧跟进任务 - 默认建议:`false` -### 工具隐含上下文 +#### 工具隐含上下文 - 不要求 LLM 传 `session_id` -- 工具从当前 `ToolExecutionContext` / runtime 中直接拿当前私聊 `session_id` +- 不要求 LLM 传 `user_id` +- 后端直接从当前 `ToolExecutionContext.session_id` 取目标私聊 - 如果当前不是私聊,工具直接失败 -### 工具返回 +#### 工具返回 - 成功时至少返回: - `task_id` - `session_id` - `send_at` - - `message_text` + - `followup_reason` + - `assistant_commitment_text` - `replace_existing` - 若发生覆盖,返回被取消的旧任务 ID 列表 - 失败时返回明确原因: - 非私聊 - 时间非法 - - 文本为空 + - 跟进原因为空 + - 承诺话术为空 - 存储失败 +### 工具 2:`send_private_message` + +#### 工具职责 +- 在当前私聊会话中主动发送一条可见消息。 +- 不依赖 `msg_id`。 +- 不默认带引用回复。 + +#### 工具参数 +- `message_text` + - 类型:`string` + - 含义:要主动发送给当前私聊对象的文本内容 + +#### 工具隐含上下文 +- 不要求 LLM 传 `session_id` +- 不允许 LLM 指定别的目标会话 +- 后端直接使用当前 `ToolExecutionContext.session_id` + +#### 工具返回 +- 成功时至少返回: + - `session_id` + - `message_text` + - `sent_message_id` +- 失败时返回明确原因: + - 非私聊 + - 文本为空 + - 发送失败 + +### 工具关系 +- `reply`:回应某条已有消息 +- `send_private_message`:主动发言,不依赖某条已有消息 +- `schedule_private_followup`:创建未来跟进任务,负责到点后唤醒 planner + ## 任务数据模型 ### 建议字段 - `id` - `session_id` -- `chat_type` -- `message_text` - `send_at_ts` - `status` +- `followup_reason` +- `assistant_commitment_text` - `created_at_ts` - `updated_at_ts` - `created_by_tool_call_id` - `cancelled_by_tool_call_id` +- `triggered_at_ts` +- `completed_at_ts` +- `completion_action` - `sent_message_id` -- `sent_at_ts` - `last_error` - `replace_existing` ### 状态 - `pending` -- `sent` +- `running` +- `completed` - `cancelled` - `failed` ### 状态语义 -- `pending`:已创建,等待发送 -- `sent`:已成功发出 +- `pending`:已创建,等待到点唤醒 +- `running`:调度器已取出,正在执行本次唤醒 +- `completed`:本次唤醒流程已成功结束,无论是否真的发出消息 - `cancelled`:被显式取消或被新任务覆盖 -- `failed`:尝试发送失败,保留错误信息 +- `failed`:本次唤醒流程执行失败 + +### 完成动作建议 +- `sent_private_message` +- `skipped` +- `rescheduled` +- `unknown` ## 覆盖规则 @@ -156,75 +255,118 @@ - 不猜“哪个旧任务和哪个新任务算同类” - 规则简单、确定、易解释 -## 取消与改期 +## 到点注入给 planner 的提示方式 -### V1 建议 -- 不单独做“改期”底层能力 -- 改期等价于: - - 取消旧任务 - - 新建新任务 -- 后续可再补专用工具: - - `cancel_scheduled_private_message` - - `list_scheduled_private_messages` +### 复用原则 +- 继续复用原有 [prompts/zh-CN/maisaka_chat.prompt](/D:/mai-bot-align-pre17/prompts/zh-CN/maisaka_chat.prompt) +- 不复制一整份新 prompt +- 不把 reminder 伪装成真实聊天历史消息 +- 复用现有 `injected_user_messages` 机制 -### 当前阶段 -- 当前文档先只覆盖“创建并发送”的最小闭环 -- 取消工具可以作为下一步扩展 +### 风格要求 +- 注入内容应沿用项目现有 `...` 风格 +- 它在请求里以 `user` 身份追加,但语义上明确说明“不是用户刚刚发来的新消息” +- 应提醒 planner: + - 这是一次定时跟进触发 + - 当前为什么会被唤醒 + - 你之前对用户说过什么 + - 可以主动发言,也可以不发言 + - 除非明确需要回应某条旧消息,否则不要默认调用 `reply` -## 到点前的最小状态校验 -- 任务当前仍是 `pending` -- 任务所属 `chat_type = private` -- 当前时间已到 `send_at_ts` -- 任务尚未发送过 -- 任务未被取消 +### 提示文案打样 +```text + +以下内容不是用户刚刚发来的新消息,而是当前私聊的一次定时跟进触发。 -## 明确不作为校验项的内容 -- 不检查“用户后来是否又聊天” -- 不让 LLM 到点时重新读上下文判断 -- 不根据最近聊天内容自动反悔 +触发时间:{trigger_at} + +你之前在这个私聊中设置过一次定时跟进。 +当时记录的跟进原因: +{followup_reason} + +当时你已经对用户说过: +{assistant_commitment_text} + +请结合当前上下文重新分析现在是否适合主动发言: +- 如果仍然适合,就继续正常分析,并在需要时调用 send_private_message。 +- 如果当前话题已经变化、用户已经提到过同类内容、约定已经失效,或者现在不适合打扰,就不要强行发送,直接 finish。 +- 不要把这段提醒当成用户的新发言。 +- 除非你明确是在回应历史中的某条具体消息,否则不要默认调用 reply。 + +``` ## 与现有链路的复用点 +### Prompt 与上下文 +- 复用 Maisaka planner 主 prompt +- 复用现有上下文窗口选择逻辑 +- 复用 `injected_user_messages` 追加尾部提醒 + ### 发送 -- 复用 `send_service.text_to_stream_with_message(...)` +- `send_private_message` 复用 `send_service.text_to_stream_with_message(...)` +- 继续复用现有 `Platform IO` 和 Napcat 出口 ### 存储 - 复用现有消息发送成功后的消息存储链路 -### 上下文 +### 上下文写回 - 复用 `sync_to_maisaka_history=True` - 复用 runtime 的 `append_sent_message_to_chat_history(...)` ### Tool call 记录 - 创建任务时,复用现有 Planner tool 执行记录链路 -- 到点执行时,不强行伪造一条新的 LLM tool call -- 到点执行属于调度器行为,不属于当轮 Planner 推理 +- 到点唤醒不伪造一条新的 LLM tool call +- 到点执行本质上属于调度器唤醒会话,而不是伪造用户发言 ## 需要补的实现模块 ### 1. 新内置工具 -- 新增 `schedule_private_message` builtin tool +- 新增 `schedule_private_followup` builtin tool +- 新增 `send_private_message` builtin tool ### 2. 任务存储 -- 新增一张定时消息任务表 -- 提供最小 CRUD: +- 新增一张私聊定时跟进任务表 +- 提供最小操作: - create - cancel pending by session - list due pending - - mark sent + - mark running + - mark completed - mark failed ### 3. 后台调度器 - 独立异步循环 - 固定间隔扫描 due tasks -- 执行发送并更新状态 +- 负责 claim 任务、唤醒会话、更新状态 -### 4. 主程序启动 +### 4. Maisaka 运行时入口 +- 为运行时新增一个“带 reminder 进入 planner 一轮”的入口 +- 该入口负责把 `` 注入到 planner 请求尾部 + +### 5. 主程序启动 - 在现有后台任务体系中注册该调度器 +## 最小验证路径 + +### 验证目标 +- 确认创建任务、到点唤醒、重新思考、主动发送、写库、上下文同步都能走通 + +### 建议路径 +1. 在私聊中让 bot 创建一条几分钟后的 `schedule_private_followup` +2. 当轮正常 `reply` 给用户,说明之后会再来跟进 +3. 到点后由调度器唤醒当前私聊的 planner +4. planner 收到 `` 后重新分析 +5. 若判断合适,调用 `send_private_message` +6. 发送应复用现有 Napcat / Platform IO 出口成功发出 +7. 发出的消息应进入: + - 现有消息存储 + - Maisaka 上下文历史 + - 现有 memory automation + ## 当前建议的落地顺序 -- 第一步:先把工具接口和任务表定下来 -- 第二步:把任务创建打通 -- 第三步:把后台调度发送打通 -- 第四步:确认发送后消息能按现有链路进入上下文 -- 第五步:再考虑取消/查看任务工具 +- 第一步:先把工具边界定下来:`schedule_private_followup` 与 `send_private_message` +- 第二步:把任务表与任务存储定下来 +- 第三步:补运行时“带 reminder 唤醒 planner”入口 +- 第四步:补后台调度器并接入主程序 +- 第五步:打通主动发送、写库、上下文同步 +- 第六步:再考虑取消/查看任务工具