doc:初版计划

计划.md

@@ -1,145 +1,244 @@
-# 私聊定时消息 V1 计划
+# 私聊定时跟进 V1 计划
+
+## 当前结论
+- 本方案只支持私聊，不支持群聊。
+- 旧草案中的“到点直接发送预先写死的 `message_text`”不再作为 V1 主方案。
+- V1 改为“定时器负责唤醒当前私聊会话的正常思考流程”，由 LLM 基于到点时的当前上下文决定是否主动发言。
+- 为了支持“主动发言但不强行回复某条旧消息”，需要新增一个与 `reply` 平行的主动私聊发送工具。
+- 平台出口、消息存储、Maisaka 上下文写回、Napcat 适配等链路应尽量复用现有实现，不新造一条发送通道。
 
 ## 目标
-- 只支持私聊，不支持群聊。
+- 让 LLM 可以在当前私聊里创建一条未来触发的“定时跟进任务”。
-- 由 LLM 在当前轮直接写好未来要发送的文本。
+- 到点后不直接发固定文本，而是重新进入该私聊的正常 planner 思考流程。
-- 到点后不再唤醒 LLM，不再二次规划，直接发送。
+- 到点思考时直接复用现有上下文窗口、原有 planner prompt、原有工具机制。
-- 尽量复用现有消息发送、消息存储、Maisaka 上下文、tool call 记录链路。
+- 如果 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 分析当前局势后，可直接调用定时跟进工具。
-- 工具由 Planner 直接可见，不走 deferred tools。
+- 工具应为 planner 直接可见的 action tool，不走 deferred tools。
-- 理由：
+- 同一轮里，planner 仍可继续：
-  - 这是明确的主流程动作，不是低频扩展工具。
+  - 调用 `reply`
-  - 用户说“明天早上提醒我”时，Planner 应当能直接执行，不应先 `tool_search`。
+  - 正常回复用户
+  - 告知用户已经记下这次未来跟进
 
 ### 3. 工具执行
-- 新工具暂定名：`schedule_private_message`
+- 暂定工具名：`schedule_private_followup`
 - 工具接收参数后，直接写入任务存储。
-- 工具返回成功结果给当前 Planner。
+- 工具只允许操作当前私聊会话，不允许 LLM 指定别的 session。
-- 该 tool result 和其他工具一样，走现有 tool call 记录与上下文写回链路。
+- tool result 与其他工具一样，复用现有 tool call 记录与上下文链路。
-- Planner 下一轮可继续：
-  - 调用 `reply`
-  - 告知用户“已经帮你定好了”
-  - 或继续补充说明
 
-### 4. 调度器轮询
+### 4. 后台调度器轮询
 - 独立后台调度器定期扫描到期任务。
 - 扫描条件：
   - `status = pending`
-  - `send_at <= now`
+  - `send_at_ts <= now`
-  - `chat_type = private`
+- 任务取出后，不直接发送，而是进入“会话唤醒”流程。
-- 调度器取出任务后尝试执行发送。
 
-### 5. 到点发送
+### 5. 会话唤醒
-- 调度器直接调用现有 `send_service.text_to_stream_with_message(...)`
+- 调度器根据 `session_id` 定位或恢复对应私聊会话。
-- 发送参数要求：
+- 如果对应 runtime 当前不在内存中，应先恢复/创建该会话的 Maisaka runtime。
-  - `text = 任务里保存的 message_text`
+- 调度器调用一个新的运行时入口，例如：
-  - `stream_id = 任务对应的私聊 session_id`
+  - `trigger_scheduled_followup(task)`
+  - 或同等语义的方法
+- 这个入口负责以“额外注入消息”的形式进入 planner，而不是伪造用户消息。
+
+### 6. 到点后的 planner 行为
+- 唤醒后的 planner 继续使用项目原有的主 prompt。
+- 同时在请求尾部追加一条 `injected_user_messages`，内容使用项目已有的 `<system-reminder>` 风格。
+- 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"`
+- `maisaka_source_kind` 建议使用新的主动发送来源标记，例如：
-- 这样发送后会自动：
+  - `proactive_send`
-  - 走现有平台发送链路
+  - 若后续需要区分定时唤醒来源，可再在 metadata 中补充 `trigger_source=scheduled_followup`
-  - 写入现有消息存储
-  - 触发现有 memory automation
-  - 在 runtime 仍存活时同步写入 Maisaka 上下文
 
-### 6. 发送后的上下文表现
+### 8. 任务完成
-- 如果该 session 的 runtime 当前仍在 `heartflow_manager.heartflow_chat_list` 中：
+- 本次唤醒流程成功结束后，原任务应被标记为完成。
-  - 发送完成后，消息会立刻追加进 `_chat_history`
+- “完成”不等于“一定发了消息”。
-- 如果 runtime 当前不在内存中：
+- 只要本次唤醒和 planner 处理已成功结束，即可完成任务，并记录最终动作结果。
-  - 这条消息仍会进入现有消息存储
-  - 之后会话重新活跃时，至少数据库层面仍保留这条 bot 已发送消息
-- V1 先不为“runtime 不在内存时立即补上下文”额外新造链路
-- 先复用现有发送与存储通道
 
 ## 工具设计
 
-### 工具名
+### 工具 1：`schedule_private_followup`
-- `schedule_private_message`
 
-### 工具职责
+#### 工具职责
-- 为当前私聊创建一条未来发送任务
+- 为当前私聊创建一条未来触发的定时跟进任务。
-- 可选择覆盖当前私聊中尚未执行的旧任务
+- 任务到点后唤醒当前私聊的 planner，而不是直接发送固定文本。
 
-### 工具参数
+#### 工具参数
 - `send_at`
   - 类型：`string`
-  - 含义：发送时间
+  - 含义：触发时间
-  - 约定：先存标准化后的绝对时间字符串，内部落库再转时间戳
+  - 建议：由 LLM 提供标准化后的绝对时间字符串
-- `message_text`
+- `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`：已创建，等待发送
+- `pending`：已创建，等待到点唤醒
-- `sent`：已成功发出
+- `running`：调度器已取出，正在执行本次唤醒
+- `completed`：本次唤醒流程已成功结束，无论是否真的发出消息
 - `cancelled`：被显式取消或被新任务覆盖
-- `failed`：尝试发送失败，保留错误信息
+- `failed`：本次唤醒流程执行失败
+
+### 完成动作建议
+- `sent_private_message`
+- `skipped`
+- `rescheduled`
+- `unknown`
 
 ## 覆盖规则
 
@@ -156,75 +255,118 @@
 - 不猜“哪个旧任务和哪个新任务算同类”
 - 规则简单、确定、易解释
 
-## 取消与改期
+## 到点注入给 planner 的提示方式
 
-### V1 建议
+### 复用原则
-- 不单独做“改期”底层能力
+- 继续复用原有 [prompts/zh-CN/maisaka_chat.prompt](/D:/mai-bot-align-pre17/prompts/zh-CN/maisaka_chat.prompt)
-- 改期等价于：
+- 不复制一整份新 prompt
-  - 取消旧任务
+- 不把 reminder 伪装成真实聊天历史消息
-  - 新建新任务
+- 复用现有 `injected_user_messages` 机制
-- 后续可再补专用工具：
-  - `cancel_scheduled_private_message`
-  - `list_scheduled_private_messages`
 
-### 当前阶段
+### 风格要求
-- 当前文档先只覆盖“创建并发送”的最小闭环
+- 注入内容应沿用项目现有 `<system-reminder>...</system-reminder>` 风格
-- 取消工具可以作为下一步扩展
+- 它在请求里以 `user` 身份追加，但语义上明确说明“不是用户刚刚发来的新消息”
+- 应提醒 planner：
+  - 这是一次定时跟进触发
+  - 当前为什么会被唤醒
+  - 你之前对用户说过什么
+  - 可以主动发言，也可以不发言
+  - 除非明确需要回应某条旧消息，否则不要默认调用 `reply`
 
-## 到点前的最小状态校验
+### 提示文案打样
-- 任务当前仍是 `pending`
+```text
-- 任务所属 `chat_type = private`
+<system-reminder>
-- 当前时间已到 `send_at_ts`
+以下内容不是用户刚刚发来的新消息，而是当前私聊的一次定时跟进触发。
-- 任务尚未发送过
-- 任务未被取消
 
-## 明确不作为校验项的内容
+触发时间：{trigger_at}
-- 不检查“用户后来是否又聊天”
+
-- 不让 LLM 到点时重新读上下文判断
+你之前在这个私聊中设置过一次定时跟进。
-- 不根据最近聊天内容自动反悔
+当时记录的跟进原因：
+{followup_reason}
+
+当时你已经对用户说过：
+{assistant_commitment_text}
+
+请结合当前上下文重新分析现在是否适合主动发言：
+- 如果仍然适合，就继续正常分析，并在需要时调用 send_private_message。
+- 如果当前话题已经变化、用户已经提到过同类内容、约定已经失效，或者现在不适合打扰，就不要强行发送，直接 finish。
+- 不要把这段提醒当成用户的新发言。
+- 除非你明确是在回应历史中的某条具体消息，否则不要默认调用 reply。
+</system-reminder>
+```
 
 ## 与现有链路的复用点
 
+### 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
+- 到点唤醒不伪造一条新的 LLM tool call
-- 到点执行属于调度器行为，不属于当轮 Planner 推理
+- 到点执行本质上属于调度器唤醒会话，而不是伪造用户发言
 
 ## 需要补的实现模块
 
 ### 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 一轮”的入口
+- 该入口负责把 `<system-reminder>` 注入到 planner 请求尾部
+
+### 5. 主程序启动
 - 在现有后台任务体系中注册该调度器
 
+## 最小验证路径
+
+### 验证目标
+- 确认创建任务、到点唤醒、重新思考、主动发送、写库、上下文同步都能走通
+
+### 建议路径
+1. 在私聊中让 bot 创建一条几分钟后的 `schedule_private_followup`
+2. 当轮正常 `reply` 给用户，说明之后会再来跟进
+3. 到点后由调度器唤醒当前私聊的 planner
+4. planner 收到 `<system-reminder>` 后重新分析
+5. 若判断合适，调用 `send_private_message`
+6. 发送应复用现有 Napcat / Platform IO 出口成功发出
+7. 发出的消息应进入：
+   - 现有消息存储
+   - Maisaka 上下文历史
+   - 现有 memory automation
+
 ## 当前建议的落地顺序
-- 第一步：先把工具接口和任务表定下来
+- 第一步：先把工具边界定下来：`schedule_private_followup` 与 `send_private_message`
-- 第二步：把任务创建打通
+- 第二步：把任务表与任务存储定下来
-- 第三步：把后台调度发送打通
+- 第三步：补运行时“带 reminder 唤醒 planner”入口
-- 第四步：确认发送后消息能按现有链路进入上下文
+- 第四步：补后台调度器并接入主程序
-- 第五步：再考虑取消/查看任务工具
+- 第五步：打通主动发送、写库、上下文同步
+- 第六步：再考虑取消/查看任务工具