Skip to content

产品接口级别功能梳理（最新版） #58

Open
Open
产品接口级别功能梳理（最新版）#58

Description

@yyy-router
yyy-router
opened on Jul 20, 2026

1. 文档目的

本文记录 MVP 阶段已经确定的 Agent 数据流、子 Agent 输入输出格式、主 Agent 职责边界、公共模块边界，以及当前暂不解决的问题。

本文用于团队后续进行函数级架构设计和模块协作时统一口径。

2. 总体设计原则

原则 说明
数据读写分离原则保持不变 AI 驱动的数据读写由主 Agent 编排；子 Agent 不直接访问数据库
子 Agent 只负责能力生成 子 Agent 根据主 Agent 提供的完整参数执行能力，返回结构化结果
参数不全由主 Agent 处理 主 Agent 在调用子 Agent 前完成参数解析和参数补全；参数不足时先触发反问机制
子 Agent 不负责追问 子 Agent 收到的参数必须是完整的，因此子 Agent 响应中不保留“需要追问”类型
手动 CRUD 允许存在 手动界面 CRUD 可以调用公共数据模块，但写操作也必须走统一确认和校验流程
滑动窗口统一为 20 条 MVP 阶段所有需要对话连续性的 Agent 使用最近 20 条对话记录
任务级画像异步沉淀 长任务拆分和重排过程中收集的时间习惯、修改原因等信息，由公共画像归纳能力异步总结，不阻塞主流程

一句话概括：

主 Agent 负责意图、参数、上下文、数据读写和确认流程；子 Agent 负责在完整输入下生成结构化结果。

## 3. MVP 阶段整体数据流 
用户输入：语音 / 文本 / OCR 图片识别结果
→ 主 Agent 接收原始输入
→ 主 Agent 进行意图识别
→ 输出待调用 agent name + agent function name
→ 主 Agent 参数解析
→ 判断参数是否完整
    → 不完整：触发反问机制，补齐参数后再继续
    → 完整：进入上下文处理
→ 主 Agent 根据参数从数据库读取必要数据
→ 主 Agent 聚合解析参数 + 数据库读取数据 + 最近 20 条对话记录
→ 主 Agent 封装子 Agent 调用参数
→ 调用目标子 Agent 函数
→ 子 Agent 返回统一结构化响应
→ 主 Agent 根据响应字段处理
    → 普通结果展示：返回前端展示
    → 需要用户确认：触发弹窗确认机制
    → 出错：进入主 Agent 错误处理
→ 用户确认后
→ 主 Agent 调用公共数据模块完成写入 / 修改 / 删除

4. 主 Agent 职责

功能 输入 输出 说明
意图识别 用户原始输入对话 待调用 agent name、agent function name 使用 LLM 判断用户意图和目标能力
参数解析 用户原始输入对话、目标函数参数定义 参数列表 使用 LLM 解析出调用目标函数所需字段
参数补全 已解析参数、目标函数缺失字段、用户原始输入 补齐后的参数或反问选项 参数不全时触发反问机制
上下文处理 解析参数、用户 ID、时间、目标函数上下文需求 子 Agent 调用参数 从数据库读取必要数据，并与解析参数聚合
子 Agent 调用 agent name、function name、完整参数 子 Agent 结构化响应 调用一个目标子 Agent 函数
响应处理 子 Agent 响应 前端展示、确认弹窗或错误处理 根据统一输出字段进行分发
确认后落盘 用户确认事件、结构化写入数据 数据库写入结果 通过公共数据模块完成写入、修改、删除
任务级画像归纳触发 长任务拆分回答、重排原因、用户明确习惯表述 任务级画像候选或更新请求 调用公共画像归纳能力，异步沉淀当前长任务级别的用户画像

5. 子 Agent 统一输出字段

MVP 阶段所有子 Agent 函数必须返回统一结构。不同 Agent 可以在 result 中返回自己的业务结果，但外层控制字段必须一致。

字段 类型 是否必填 含义
agent_name string 是 当前响应来自哪个子 Agent
function_name string 是 当前响应来自哪个函数
isNeedUser boolean 是 是否需要用户确认；高危操作默认包含在此字段中
isDisplayResult boolean 是 是否为普通结果展示
isError boolean 是 是否出错，用于主 Agent 错误处理
result object / string / array 是 子 Agent 的业务结果
db_action object / null 否 如涉及数据库操作，返回建议的数据库动作描述
error_message string / null 否 出错时返回错误说明

统一响应示例

{
  "agent_name": "反馈 Agent",
  "function_name": "生成执行反馈",
  "isNeedUser": true,
  "isDisplayResult": false,
  "isError": false,
  "result": {
    "target_id": "subtask_001",
    "normalized_feedback": "用户反馈该子任务未完成，原因是临时会议打断"
  },
  "db_action": {
    "action": "append_feedback",
    "target_table": "feedback",
    "target_id": "subtask_001"
  },
  "error_message": null
}

6. 各子 Agent 输入输出约束

6.1 日程待办 Agent

项目 内容
主要能力 利用 LLM 实现日程或待办的增删改查意图理解
输入 用户原始输入、最近 20 条对话记录
输出 result 日程 / 待办分类、数据库操作动作、结构化操作字段
控制字段 isNeedUser、isDisplayResult、isError
注意事项 Agent 只输出数据库动作建议，不直接读写数据库

6.2 长任务拆分 Agent

项目 内容
主要能力 利用 LLM 对用户长任务进行拆分
输入 用户画像、当前长任务级画像、用户输入 raw data、最近 20 条对话记录
输出 result 按时间顺序排列的拆分结果
控制字段 isNeedUser、isDisplayResult、isError
注意事项 拆分结果属于候选计划，用户确认后才可写入子任务

6.3 重排 Agent

项目 内容
主要能力 利用 LLM 对用户当前所有日程 / 待办 / 子任务进行整体重排
输入 用户画像、当前长任务级画像、用户输入 raw data、截至用户输入时间的未来日程 / 待办 / 子任务、有反馈未完成的当前长目标子任务、最近 20 条对话记录
输出 result 最新重排计划
控制字段 isNeedUser、isDisplayResult、isError
注意事项 MVP 阶段暂不限制重排输入规模，后续可根据 token 和性能再优化

重排范围包括：

  1. 时间上的重新安排。
  2. 长任务的子任务重新划分。
  3. 未完成子任务对后续计划的影响调整。

如果主 Agent 判断用户需要对长任务进行重排，应额外收集用户是否存在明确习惯表述或修改原因，例如“最近晚上效率低”“这周工作日没空”“这个目标要压缩到周末”。这些信息会交给任务级画像归纳能力进行总结和改写，追加到该长任务创建之初形成的任务级画像中。

6.4 复盘 Agent

项目 内容
主要能力 对特定时间段进行复盘
输入 复盘类型、复盘时间范围、该时间段关联数据、最近 20 条对话记录
输出 result 完整复盘报告字符串
控制字段 isNeedUser、isDisplayResult、isError
注意事项 复盘通常属于展示型结果，默认 isDisplayResult = true，不直接写入数据库

复盘类型包括：

类型 含义
全部事项复盘 包括子任务和日程
单一长任务复盘 只针对某个长任务及其子任务

6.5 反馈 Agent

项目 内容
主要能力 对特定日程或特定子任务生成执行反馈
输入 用户输入的反馈关联时间范围、该时间段关联数据、最近 20 条对话记录
输出 result 特定子任务或日程在数据库中的主键 ID、规范化改写后的用户反馈
控制字段 isNeedUser、isDisplayResult、isError
注意事项 输入关联数据的目的，是从候选事项中找到待追加反馈的数据库主键 ID

反馈 Agent 的核心不是复盘，而是：

根据用户自然语言反馈，在给定关联数据中定位具体日程或子任务，并生成规范化反馈内容。

7. 公共模块设计约束

7.1 弹窗确认机制

项目 内容
触发条件 子 Agent 响应中 isNeedUser = true
输入 子 Agent 响应、确认文案、数据库动作建议
输出 用户确认事件或用户取消事件
注意事项 用户确认事件回到主 Agent，由主 Agent 发起最终写入

7.2 公共数据模块

项目 内容
主要能力 暴露数据库查询、写入、修改、删除函数方法
调用方 主 Agent；手动界面 CRUD 也可调用，但写操作必须走统一确认和校验流程
禁止事项 子 Agent 不直接调用公共数据模块
注意事项 所有 AI 驱动的数据读写都在主 Agent 中实现

统一口径：

AI 驱动的读写由主 Agent 编排；手动界面 CRUD 可以调用同一套公共数据模块，但写操作也必须走统一确认和校验流程。

7.3 反问机制

项目 内容
触发条件 主 Agent 参数解析后发现待调用子 Agent 函数参数不完整
输入 用户原始输入、已解析参数、缺失参数、目标函数说明
输出 面向用户的追问问题和备选选项
注意事项 反问发生在调用子 Agent 之前；子 Agent 不承担追问职责

7.4 基础业务模块

功能 说明
主对话框 用户主要 AI 交互入口
时间顺序 Tab 按时间顺序展示每天的日程、待办、子任务
长任务目标管理 Tab 展示长目标列表和目标详情
个人主页 用户注册登录、用户画像表单收集与更新
OCR / ASR 接口 系统涉及的 OCR、ASR 接口调用在基础业务模块中实现

基础业务模块中的手动 CRUD 需要注意：

  1. 手动创建、修改、删除也必须经过统一确认和校验流程。
  2. 手动操作不经过子 Agent。
  3. 手动操作和 AI 操作最终写入同一套数据库结构。

7.5 LLM 管理模块

项目 内容
主要能力 大模型调用封装、多平台模型切换、提示词管理
调用方 主 Agent、各子 Agent、反问机制等所有需要 LLM 的模块
注意事项 所有 LLM 调用应统一走 LLM 管理模块，避免各模块自行封装

7.6 任务级画像归纳模块

项目 内容
模块归属 公共模块
调用方 主 Agent
主要能力 归纳总结长任务级别的时间安排习惯、任务粒度偏好、可投入时间、修改原因等画像信息
触发场景 长任务拆分前的少量习惯询问；长任务重排时用户明确表达习惯或修改原因
输入 当前长任务 ID、用户主动回答、用户明确习惯表述、重排修改原因、已有任务级画像、最近 20 条对话记录
输出 任务级画像候选、画像更新字段、冲突说明、来源记录
是否阻塞主流程 否。画像归纳和沉淀作为异步环节，不阻塞长任务拆分、重排、展示和确认主流程
写入方式 由主 Agent 发起画像更新，调用公共数据模块保存

任务级画像示例：

{
  "long_goal_id": "goal_001",
  "profile_summary": {
    "available_time": "工作日每天约 1 小时，周末可投入 3 小时",
    "preferred_time_period": "晚上不适合高强度任务，上午效率更高",
    "task_granularity": "偏好拆成 30-45 分钟的小任务",
    "rest_preference": "周日尽量少安排"
  },
  "source": {
    "type": "user_explicit_input",
    "conversation_refs": ["msg_101", "msg_116"]
  },
  "updated_at": "2026-07-20 10:30"
}

设计约束：

  1. 任务级画像是某个长任务维度下的画像，不等同于用户全局画像。
  2. 画像归纳不阻塞主流程，主流程可以先完成拆分或重排候选生成。
  3. 画像更新应基于用户主动回答、明确习惯表述或明确修改原因，不应凭空推断。
  4. 如果新输入和旧画像存在冲突，以最新明确输入为准，同时保留来源记录。
  5. 画像归纳模块不直接读写数据库，数据读取和写入仍由主 Agent 调用公共数据模块完成。
  6. 画像沉淀结果后续可作为长任务拆分 Agent 和重排 Agent 的输入上下文。

7.7 消息推送模块

项目 内容
模块级别 P0
模块归属 前端实现
主要能力 前台保活推送、日常推送、耗时任务结果推送
调用方 前端自身；消息来源可来自主 Agent 的状态结果或后端耗时接口轮询结果
是否参与子 Agent 调用 不参与。该模块不进入子 Agent 数据流，只负责界面通知展示
注意事项 日常推送和耗时任务结果推送都在前端实现，不要求子 Agent 直接推送

7.7.1 日常推送

项目 内容
触发时机 日程临近开始、日程结束进入反馈阶段
展示方式 自定义音频着重提醒、震动、前台保活推送
消息处理 消息清理禁止，推送需要保持可见和可追踪
设计约束 推送只是提醒，不直接修改日程状态，也不替代反馈确认

7.7.2 耗时任务结果推送

项目 内容
触发时机 轮询后端耗时接口后，任务结果可用时
适用场景 长任务拆分、重排结果、复盘报告等需要等待的耗时任务
展示方式 前台通知、结果卡片或结果页跳转
设计约束 由前端轮询结果后进行推送展示，不要求子 Agent 主动推送

7.7.3 前端实现约束

  1. 消息推送模块仅做前端通知展示和交互提醒。
  2. 推送源可以来自主 Agent 返回结果或后端耗时接口轮询。
  3. 日常推送需支持自定义音频、震动和前台保活提醒。
  4. 消息清理禁止，至少在 MVP 阶段保持消息可追踪。
  5. 该模块不直接参与数据库写入，不改变业务事实。

8. 主 Agent 与子 Agent 的责任边界

能力 主 Agent 子 Agent
意图识别 负责 不负责
参数解析 负责 不负责
参数补全 / 反问 负责 不负责
数据读取 负责 不负责
数据写入 负责 不负责
上下文聚合 负责 不负责
专项能力生成 不负责具体生成细节 负责
结构化响应 校验和分发 负责返回
用户确认处理 负责 不负责
任务级画像归纳触发 负责 不负责
任务级画像生成 调用公共模块 不负责

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions