21d6fe5b5f
🚀 更新了 README 中的 Mermaid 图，确保与当前随口记的业务链路一致。 📚 新增了功能决策记录（docs/功能决策记录），并且记录了此次 AI 随口记功能的工程决策。
99 lines
5.8 KiB
Markdown
99 lines
5.8 KiB
Markdown
# 功能决策记录（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、重试策略）。
|