09dca9f772
✨ feat(agent): 通用分流接入随口问图编排，修复任务查询条数与重复输出问题 - ♻️ 将 Agent 路由升级为通用 `action` 分流机制，统一支持 `chat` / `quick_note_create` / `task_query` - 🧩 新增 `taskquery` 子模块并落地图编排链路：`plan -> quadrant -> time_anchor -> tool_query -> reflect` - 🔧 在图内接入 `query_tasks` 工具调用，支持自动放宽检索条件与反思重试，最多重试 2 次 - 🚪 保持 `/agent/chat` 作为多合一入口，不额外新增任务查询 HTTP 接口 - 🪄 修复“随口问”场景下的双重列表输出问题：LLM 仅保留简短前缀，任务列表统一由后端进行确定性渲染 - 🎯 修复显式数量约束失效问题：支持提取“来一个”“前 3 个”“top5”等数量表达，并将其锁定为 `limit` - 🛡️ 防止在重试或放宽检索阶段改写用户显式指定的数量约束 - ✅ 补充并更新测试，覆盖路由解析、数量提取、`limit` 生效及重复输出等关键场景 📝 docs: 更新随口问链路文档与决策记录 - 📚 更新 README 5.4，新增/修订随口问链路 Mermaid 图 - 🧭 新增随口问功能决策记录 FDR
5.9 KiB
5.9 KiB
功能决策记录（FDR）：AI随口问（任务查询）
1. 基本信息
- 记录编号：FDR-2026-03-AGENT-TASK-QUERY
- 功能名称：AI 随口问（任务查询）
- 记录日期：2026-03-16
- 决策状态：已采纳
- 负责人：项目协作实现（你 + Codex）
- 关联需求 / Issue：
- 在同一个
/agent/chat多合一入口下支持“自然语言任务查询” - 不新增独立查询接口，复用现有 Agent 分流体系
- 在同一个
2. 背景与问题
- 业务背景：用户在聊天中会提出大量“模糊查询”表达，例如“有啥优先级比较低的任务”“我现在很闲，有啥简单的任务可以做”。
- 现状问题：
- 纯 tool loop 方案在“表达模糊/口语化”场景下稳定性不足，容易出现答错或答不上来。
- 模型回复阶段容易与后端列表拼接冲突，出现“双重输出”。
- 用户显式数量要求（如“来一个”“前3个”）会在重试或放宽阶段被冲掉。
- 不做此决策的后果：
- 用户对 AI 查询能力感知不稳定；
- 对外展示时难以解释“为何这次能查到、下次查不到”；
- 代码长期演进会出现多条并行查询链路，维护成本升高。
3. 决策目标
- 目标 1：在不新增 HTTP 接口的前提下，把“随口问任务查询”稳定接入现有 Agent 主链路。
- 目标 2：兼顾性能与准确性，形成
2+x（规划一次 + 反思最多两次）的可控模型调用上限。 - 目标 3：保证输出可控（条数、格式、可读性），避免双重输出与数量失真。
- 非目标（明确本次不解决什么）：
- 不引入语义映射词典（避免词典维护成本膨胀）；
- 不做任务查询独立微服务拆分；
- 不做跨用户多租户复杂权限系统升级（沿用现有 user_id 注入隔离）。
4. 备选方案
方案 A：纯 Tool Loop（模型直接决定工具参数并循环）
- 描述：进入 task_query 分支后直接走模型工具循环，直到无工具调用为止。
- 优点：实现快，代码量少。
- 缺点：对模糊语义不稳，容易“结果可用但回复不稳定”；难做节点化可观测。
- 复杂度 / 成本：低。
方案 B：规则词典 + 工具查询
- 描述：用词典/关键词规则先映射象限与条件，再调用工具查询。
- 优点：可控性强，行为可预测。
- 缺点：语言表达覆盖困难，词典维护成本高，边界案例会持续增多。
- 复杂度 / 成本：中（初期可用，长期维护成本高）。
方案 C（采纳）：Graph 编排 + 节点内工具调用 + 反思重试
- 描述：
- 分流命中 task_query 后进入 TaskQueryGraph；
- 图内固定节点：
plan -> quadrant -> time_anchor -> tool_query -> reflect； reflect决定是否重试，并产出 patch（最多 2 次）；- 最终回复由后端确定性渲染列表，模型仅提供短语气前缀。
- 优点：
- 可读性和可观测性更好（节点化状态明确）；
- 对模糊表达更稳（规划 + 反思 + 自动放宽）；
- 输出格式可控，避免双重输出和条数漂移。
- 缺点：
- 实现复杂度高于纯 loop；
- 需要严格控制重试上限与 prompt 约束，避免延迟膨胀。
- 复杂度 / 成本：中高。
5. 最终决策
- 采纳方案：方案 C。
- 关键理由：
- 在体验、准确性、可维护性三者之间取得最优平衡；
- 能与现有 quick_note 图范式保持一致，便于统一认知；
- 满足“默认多合一入口、不新增接口”的项目约束。
6. 影响范围
- 涉及模块：
backend/agent/route/route.go（通用分流 action）backend/agent/taskquery/*（图、节点、状态、工具、测试）backend/service/agentsvc/agent.go（分流调度）backend/service/agentsvc/agent_task_query.go（查询执行与数据筛选）
- 数据与存储影响：
- 不新增表结构；
- 读取沿用
tasks表与现有字段； - 会复用“读时紧急性派生”口径，不直接写库。
- 接口 / 协议影响：
- 对外仍是
/agent/chat，OpenAI 兼容 chunk 协议不变。
- 对外仍是
- 监控与日志影响：
- 新增 task_query 阶段推送：
plan/quadrant/time_anchor/tool_query/reflect； - 可按节点阶段观察链路耗时与重试频次。
- 新增 task_query 阶段推送：
7. 风险与应对
- 风险 1：反思重试导致延迟增大。
- 应对策略：重试上限固定为 2；首轮结果为空时仅自动放宽一次，不无限扩散。
- 风险 2：模型自由回复导致列表重复或条数不一致。
- 应对策略：最终列表由后端确定性渲染；LLM 回复仅提取短前缀，检测到列表迹象直接丢弃。
- 风险 3：用户显式数量要求被后续补丁覆盖。
- 应对策略：显式数量单独入状态并加锁，反思 patch 与自动放宽均不得改写该值。
8. 验证与回滚
- 验证方式：
- 语义场景回归：模糊提问、显式数量、象限筛选、无结果场景。
- 自动化测试：数量提取、显式数量锁、去重输出校验。
- 全量编译测试：
go test ./...。
- 成功判定标准：
- 不再出现双重列表输出；
- “来一个/前3个/top 5”能稳定按数量返回；
- 模糊提问在多数样本下能返回可执行结果。
- 回滚方案：
- 回退到上一版 task_query 执行器（纯 loop）；
- 保留 route 分流与 quick_note 不变，最小化影响面。
9. 里程碑与后续计划
- 里程碑 1：完成 TaskQueryGraph 主链路接入（已完成）。
- 里程碑 2：完成显式数量锁与防双重输出修复（已完成）。
- 后续优化项：
- 增加节点级耗时日志（plan/query/reflect）用于性能压测；
- 增加“更多结果翻页式追问”能力；
- 在前端阶段事件协议正式化后，去掉 reasoning 兼容层临时格式。
10. 复盘结论（上线后补充）
- 实际效果：待补充。
- 与预期偏差：待补充。
- 后续是否需要二次决策：待补充。