smartmate/docs/功能决策记录/AI随口记_决策记录.md

功能决策记录（FDR）：AI随口记

1. 基本信息

• 记录编号：FDR-2026-03-AGENT-QUICK-NOTE
• 功能名称：AI 随口记（日程/任务自动识别与写入）
• 记录日期：2026-03-14
• 决策状态：已采纳
• 负责人：项目协作实现（你 + Codex）
• 关联模块：/agent/chat、Agent Graph、任务写库工具、Redis 会话缓存、Outbox 持久化链路

2. 背景与问题

• 业务背景：用户希望在聊天中“顺口一句”就能完成任务记录，例如“明天上午 9 点交实验报告”。
• 初始问题：
  • 仅关键词触发的分流策略存在误判，容易出现“该走随口记没走到 / 不该走却走到了”。
  • 多次模型调用（意图识别、时间归一化、优先级评估、润色回复）导致整体耗时偏长。
  • 曾出现“回复显示安排成功但数据库未写入”的一致性问题，影响用户信任。
  • 相对时间理解依赖当前时间上下文，未显式给模型当前时间时易解析失败或落空。
• 不做此决策的后果：用户体验不稳定、链路不可解释、面试叙述难以自洽（无法清晰说明可靠性与性能权衡）。

3. 决策目标

• 目标 1：让“聊天入口 + 任务执行”在用户视角尽量无感切换，减少误判与等待焦虑。
• 目标 2：保证写入成功才返回成功，避免“假成功”。
• 目标 3：在不破坏现有流式聊天主链路的前提下，提升随口记链路可维护性与可解释性。
• 非目标：本次不做多 Agent 并发编排、不做复杂工作流引擎分布式扩展。

4. 备选方案

方案 A：继续以关键词匹配为主分流

• 描述：命中词则进随口记，否则普通聊天。
• 优点：实现简单，速度快。
• 缺点：语义覆盖不足，边界表达极易误判；可维护性差（词库不断膨胀）。

方案 B：完全依赖 Graph 二次意图判断

• 描述：所有请求先入图，再判断是否是随口记。
• 优点：逻辑统一，准确性相对高。
• 缺点：普通聊天也要先走较重流程，体验退化，整体成本高。

方案 C（采纳）：模型控制码路由 + Graph 兜底 + 单请求聚合规划

• 描述：
  • 先用同模型做轻量路由（返回 quick_note/chat 控制码）；
  • 路由命中则走随口记快路径，跳过重复判定；
  • 路由失败或异常时回退到 Graph 兜底判定；
  • 随口记核心规划改为单请求聚合（时间、优先级、回复语气一次产出），减少多轮 LLM 往返。
• 优点：体验与鲁棒性平衡更好，误判可兜底，耗时可控。
• 缺点：需要更严格的超时与错误处理，提示词质量直接影响路由稳定性。

5. 最终决策

• 采纳方案：方案 C。
• 关键理由：
  • 兼顾速度（快路径）与可靠性（兜底路径）；
  • 明确“成功响应必须以真实写库成功为前提”；
  • 对现有项目侵入较小，保留后续扩展到完整 Agent 编排的空间。

6. 关键实现约束（本次落地口径）

• 路由层：
  • 由模型返回控制码判断走向（quick_note 或 chat）；
  • 路由失败时允许进入 Graph 兜底，不直接让请求失败。
• 执行层（随口记）：
  • 使用“单请求聚合规划”，将时间归一化、优先级评估、回复素材生成整合为一次模型调用；
  • 对时间字段执行本地校验，非法日期不写库，返回纠错信息；
  • 优先级保留本地兜底，避免因模型输出波动导致链路中断。
• 一致性层：
  • 数据库写入结果作为成功唯一依据，task_id 无效即判失败；
  • 修复“成功回复未写入 Redis 会话缓存”的问题，确保会话上下文与持久化语义一致。
• 交互层：
  • 在 OpenAI 兼容流式输出下，阶段提示暂伪装为“思考块”形态，保证现有调试工具可读；
  • 最终正文一次性输出，不做伪流式分片刷屏。

7. 与 Outbox 链路的协同决策

• 保持“后置写 Outbox”策略：聊天主响应优先，持久化异步化。
• 移除“首次同步投 Kafka”机制，避免把 Broker 投递耗时绑定到当前请求。
• 结论：当前请求仅承担必要同步成本（如 Redis 与写 Outbox 入库），Kafka 分发交由后台扫描器处理。

8. 风险与应对

• 风险 1：路由模型超时导致分流不稳定。
  • 应对：独立路由超时控制 + 失败回退 Graph 兜底，避免整链路崩溃。
• 风险 2：模型输出日期格式不规范导致脏数据。
  • 应对：Go 侧严格日期校验，校验失败直接返回用户修正，不写库。
• 风险 3：用户感知“等待无反馈”。
  • 应对：增加阶段状态提示（请求接收、意图分析、时间校验、写库中、写库完成）。

9. 验证与回滚

• 验证方式：
  • 正常样例：绝对时间、相对时间（依赖当前时间）均应正确入库；
  • 异常样例：非法日期必须失败且不写库；
  • 一致性样例：成功后 Redis 会话能看到助手反馈。
• 成功判定标准：
  • 不再出现“秒回成功但 DB 无记录”；
  • 路由失败时仍可由兜底链路完成任务；
  • 交互可见阶段反馈，用户等待感降低。
• 回滚方案：
  • 路由逻辑可回退到纯聊天 + 手动触发工具；
  • 保留 Graph 兜底能力，避免单点策略失效。

10. 后续优化项

• 增加路由与执行链路的结构化指标（命中率、误判率、平均耗时、P95/P99）。
• 对“随口记回复风格”做可配置化（幽默程度、长度、正式度）。
• 后续接前端时，将临时“思考块伪装”升级为正式阶段事件协议，避免兼容层长期存在。
• 当工具数量增长后，考虑从单技能图演进到可插拔技能编排目录（按技能隔离 prompt、schema、重试策略）。