# 功能决策记录（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、重试策略）。