AI Agent Server

这是一个基于 Python、gRPC、LangGraph 的对话式 AI 待办软件 Agent 服务设计说明。

目标是把"意图识别 - 任务解析 - 澄清 - 草稿 - 用户确认 - 入库 - 冲突检测"拆成可维护的图节点，方便后续扩展到搜索、日程、软件控制和多轮确认。

设计目标

1. 把自然语言输入稳定路由到正确的业务分支。
2. 把 todo 类操作拆成可追踪、可回滚、可确认的多阶段流程。
3. 让前端始终拿到结构化草稿、澄清问题、确认结果和冲突提示。
4. 为后续接入网络搜索、日程同步、软件 CLI 留出清晰扩展点。

技术栈约定

• Python 3.12+：服务端语言与异步业务实现。
• gRPC (asyncio)：对外接口，提供 Chat / Resume 两个 server-streaming RPC。
• LangGraph：多节点流程编排、条件路由、中断与恢复。
• Pydantic：请求、响应、领域对象和 LLM 结构化输出校验。
• uv：包管理与虚拟环境。

核心流程图

flowchart TD
    A[用户输入] --> B[意图识别]
    B --> C[对话]
    B --> D[todo]
    B --> E[dotodo]
    B --> F[software-cli]
    C --> C1{是否需要网络搜索}
    C1 -- 是 --> C2[调用搜索工具]
    C1 -- 否 --> C3[普通对话回复]
    C2 --> C3
    D --> D1[任务解析]
    D1 --> D2[评估器: 是否需要澄清]
    D2 -- 需要 --> D3[询问缺失字段]
    D2 -- 不需要 --> D4[返回任务草稿]
    D4 --> D5{前端动作}
    D5 -- 拆分 --> D6[拆分节点]
    D5 -- 确认 --> D7[创建任务入库]
    D5 -- 取消 --> D8[结束]
    D6 --> D9[返回拆分草稿]
    D9 --> D10{前端确认?}
    D10 -- 是 --> D11[创建或更新数据库]
    D10 -- 否 --> D8
    D7 --> D12[冲突检测]
    D11 --> D12
    D12 --> D13[返回冲突提示或成功结果]
    D --> D14[查询任务]
    D --> D15[更新任务]
    D --> D16[删除任务]
    D --> D17[日程管理]
    D14 --> D18[查询并返回]
    D15 --> D19[返回更新草稿]
    D16 --> D20[返回删除确认]
    D17 --> D21[格式化返回]
    E --> E1[暂不实现]
    F --> F1[暂不实现]

Agent 分层思路

1. 入口层

• 接收原始用户输入。
• 转换成标准上下文。
• 记录会话、用户、来源、时间戳和幂等键。

2. 意图层

• 对话
• todo
• dotodo
• software-cli

3. 业务编排层

• 对话分支决定是否调用搜索工具。
• todo 分支按“解析 - 澄清 - 草稿 - 确认 - 入库 - 冲突检测”推进。
• 暂不实现的能力保留空节点，避免以后重构路由。

4. 数据层

• todo 草稿
• 澄清上下文
• 确认状态
• 冲突检测结果
• 任务数据库 DTO

todo 分支的状态建议

running -> awaiting_clarification -> awaiting_confirmation
awaiting_confirmation -> running -> completed
awaiting_confirmation -> cancelled

需要前端输入的节点使用 LangGraph interrupt() 暂停，前端通过同一个 thread_id 和 Command(resume=...) 恢复；数据库、搜索和日历当前只返回结构化占位结果。

关键约定

• 解析结果必须是结构化对象，不能只返回自然语言。
• 任何缺失关键字段的任务都要先进入澄清流程。
• 前端确认前只允许生成草稿，不允许直接入库。
• 冲突检测必须成为独立节点，并返回结构化冲突项。
• 拆分任务要保留原任务与子任务的关联信息。

预期能力边界

• 已规划：普通对话、网络搜索对话、todo 全流程。
• 暂不实现：dotodo、software-cli。