# 功能决策记录（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`；
  - 可按节点阶段观察链路耗时与重试频次。

## 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. 复盘结论（上线后补充）
- 实际效果：待补充。
- 与预期偏差：待补充。
- 后续是否需要二次决策：待补充。

