Proposal：AI 入口与单会话

[gac0812]

Issue：AI 入口与单会话

1. 功能描述

AI Tab 是 TimeFlow MVP 的唯一 AI 入口。用户在同一个持续会话中完成创建、查询、修改、删除、Goal 拆分、Feedback、重排和即时复盘。

主 Agent 负责意图识别、参数解析、参数补全、上下文聚合、子 Agent 路由、确认流程和数据读写编排。子 Agent 只在主 Agent 提供完整输入后返回结构化结果，不追问、不读写数据库。

2. 用户 / 用户故事

目标用户：需要用自然语言管理日常事项、长期 Goal 和计划变化，但不希望 AI 未确认修改事实的个人用户。

用户可以直接说：

• “明天下午三点开项目会。”
• “两周内完成产品需求报告。”
• “刚才那个任务没做完，因为临时开会。”
• “帮我重排一下这周。”
• “复盘一下这个 Goal。”

用户不需要先判断入口和表单，AI Tab 会通过主 Agent 把意图路由到对应能力。

3. 现有做法及不足

如果把 AI 入口、输入渠道和候选确认放在同一层，用户会在一个会话里同时面对入口选择、输入方式和业务写入三类问题，主会话边界会变得模糊。

本模块只负责单会话入口和主 Agent 编排，不混入输入标准化或候选确认的具体规则。

4. 本期范围

1. AI Tab 只有一个持续会话。
2. MVP 上下文使用最近 20 条对话记录。
3. 主 Agent 接收标准化后的文本输入。
4. 主 Agent 完成意图识别和参数解析。
5. 参数不足时由主 Agent 反问。
6. 参数完整后由主 Agent 读取必要事实并调用目标子 Agent。
7. 子 Agent 返回统一响应结构后，由主 Agent 决定展示、确认、错误处理或写入。
8. 一个用户请求优先只调用一个子 Agent 函数；多意图、多对象和多步骤请求先反问、缩小范围或拆成多轮处理。
9. 涉及反馈、修改、删除和重排对象定位时，主 Agent 先查询候选；候选不唯一时要求用户选择，禁止猜测数据库主键。
10. 所有 LLM 调用统一经过 LLM 管理能力，Agent 调用记录可关联业务审计日志。

5. 明确不做

• 不做多会话列表。
• 不做其他 Tab 的独立 AI 会话。
• 不做自动多 Agent 串联编排。
• 不做子 Agent 主动追问。
• 不做子 Agent 直接读写数据库。
• 不做复杂 SessionState，MVP 先固定最近 20 条对话。
• 不让子 Agent 互相调用，也不在一次请求中自动串联多个子 Agent。

6. 关键决策

决策点	备选方案	选择	理由
AI 入口	单一 AI Tab / 多页面 AI / 全局悬浮入口	单一 AI Tab	符合“持续时间助理”心智，降低入口摩擦
会话数量	一个持续会话 / 多会话列表	一个持续会话	MVP 不需要通用聊天产品的多会话管理
编排者	主 Agent / 子 Agent 自主协作	主 Agent	统一数据读写和确认边界
子 Agent 职责	专项生成 / 自主读写和追问	专项生成	降低权限风险，避免子 Agent 修改事实
上下文	最近 20 条 / 完整历史 / 动态检索	最近 20 条对话	简单可控，满足 MVP 连续性
复杂请求	自动多 Agent 串联 / 反问拆分	反问、拆分、分步处理	避免多 Agent 连续执行放大误判
对象定位	LLM 猜测 / 主 Agent 查询候选	主 Agent 先查候选	子 Agent 不猜数据库主键

7. 边界与异常

• 参数不完整时，不调用子 Agent，先由主 Agent 追问。
• 子 Agent 返回 db_action != null 时，必须同时满足 isNeedUser = true。
• 子 Agent 返回错误时，主 Agent 不触发写入。
• 用户取消候选后，本次候选不落库，但普通对话消息可以保留。
• 查询型结果可以直接展示，不需要确认。
• 多意图请求先处理主要意图并提示分步继续，不自动执行后续意图。
• 候选对象为 0 个时要求补充名称、时间或类型；候选对象多于 1 个时要求用户选择。
• 主 Agent 和子 Agent 的 LLM 调用统一经过 LLM 管理能力；单个模块不自行绑定模型 SDK。

8. 基本概念与信息结构

AI Tab
└─ Conversation
   ├─ Message
   ├─ MainAgentTurn
   ├─ Candidate / Draft
   ├─ Confirmation
   └─ DisplayResult

主 Agent
├─ 意图识别
├─ 参数解析
├─ 参数补全 / 反问
├─ 上下文聚合
├─ 子 Agent 调用
├─ 响应处理
├─ 确认后落盘
├─ 业务审计关联
└─ LLM 管理能力调用

9. Agent 输入输出约束

所有子 Agent 外层响应必须包含：

{
  "agent_name": "string",
  "function_name": "string",
  "isNeedUser": true,
  "isDisplayResult": false,
  "isError": false,
  "result": {},
  "db_action": null,
  "error_message": null
}

约束：

• db_action != null 时必须 isNeedUser = true。
• 子 Agent 不直接调用公共数据模块。
• 主 Agent 在用户确认后调用公共数据模块写入、修改或删除。
• isError = true 时不展示确认卡、不触发写入；db_action != null 时必须 isNeedUser = true。
• Agent 调用链和业务审计事件通过 trace_id 关联；模型输入输出观测不能替代确认和写入日志。

10. 验收标准

• AI Tab 中不存在多会话列表。
• 连续追问时，系统能引用最近 20 条对话中的必要上下文。
• 用户输入创建、查询、修改、Feedback、重排、复盘请求时，主 Agent 能识别目标能力。
• 参数不足时先反问，未补齐前不生成业务候选。
• 子 Agent 输出不会直接改变数据库事实。
• 写操作候选必须经过用户确认后才落库。
• 多意图请求不会在一次响应中自动调用多个子 Agent。
• 同名或指代不清的对象不会被模型猜测为某个数据库主键。
• 所有 LLM 调用均走统一管理能力；确认与写入事件可通过 trace_id 追踪。