Skip to content

TimeFlow MVP 子 Agent 能力层统一接口 #74

Open
Open
TimeFlow MVP 子 Agent 能力层统一接口#74

Description

@Alexander-Noah
Alexander-Noah
opened on Jul 23, 2026

完善 TimeFlow MVP 子 Agent 能力层统一接口

状态：待评审
负责人范围：郑浩涛／子 Agent 能力层
设计基线：子 Agent 只生成内容候选；母 AI 独占意图识别、真实对象绑定、确认、校验、CRUD 与持久化

1. 背景

TimeFlow MVP 需要为日程待办、反馈、长任务拆分、重排和复盘提供五个相互独立的智能能力。当前需要统一这些能力的调用入口、输入输出契约、模型故障转移和错误处理方式，保证母 AI 能稳定调用，并让每个模块可以独立实现和测试。

本设计把“母 AI 已完成意图判断，并选定唯一 agent_name + function_name”作为上游前置条件。子 Agent 能力层只校验已选路由、接收完整事实、调用模型、校验输出并返回结果，不重新判断用户意图。

2. 目标

  1. 定义五个子 Agent 的职责、输入、输出及调用边界。
  2. 通过 SubAgentDispatcher 提供统一且可校验的调用入口。
  3. 通过共享 LLM 管理模块完成主模型调用、受控格式修复和备用模型切换。
  4. 统一成功、确认、展示和错误响应，禁止模型半成品越过能力层。
  5. 以 Pydantic 公共模型作为机器契约的唯一事实源，并生成对应 JSON Schema。
  6. 建立覆盖路由、事实引用、输出格式、模型切换、取消和安全边界的最小契约测试。

3. 范围

3.1 包含

  • AgentCallContext、五类 XxxAgentInput、五类业务结果和统一 AgentResponse[T]。
  • SubAgentDispatcher.dispatch(context, input_data) 的路由与输入类型校验。
  • 五个独立业务函数及其确定性输入、输出校验器。
  • LLM 路由、固定版本 Prompt、上下文预算、Provider Adapter 和模型故障转移。
  • 统一错误码、稳定原因码、安全错误摘要及失败阶段标识。
  • 请求截止时间、取消检查、迟到结果丢弃和运行摘要记录。
  • 公共 Pydantic 模型、自动生成的 JSON Schema 及契约测试。

3.2 不包含

  • 母 AI 的意图分类、追问、用户确认状态机和业务编排算法。
  • 数据库访问、表结构、SQL、Repository、CRUD 与持久化实现。
  • 真实 ID、版本、权限、用户身份及临时引用到真实对象的映射。
  • 前端 API、确认卡片和具体展示实现。
  • 子 Agent 之间的串联、互相调用或共享可变业务状态。
  • 具体模型供应商、模型名称、密钥和部署环境配置。
  • 熔断阈值、健康状态计算和半开探测等增强治理能力。

4. 核心责任边界

能力 母 AI 子 Agent
识别用户意图并选择目标能力 负责 不负责
查询、筛选和裁剪业务事实 负责 不读取业务数据
持有真实 ID、版本、权限和用户身份 负责 不接收、不输出
生成事项、反馈、规划、重排和复盘内容 提供完整上下文与约束 负责生成候选或展示结果
绑定业务对象、展示、确认和冲突复查 负责 不负责
执行新增、修改、删除、查询和持久化 负责 禁止执行

所有子 Agent 必须遵守以下硬约束：

  • 一次调用只进入一个目标子 Agent，不自动串联其他子 Agent。
  • 不访问数据库，不向用户追问，不调用前端，不调用其他子 Agent。
  • 只使用当前请求输入，不读取其他 Agent 的上下文或中间结果。
  • target_ref、item_ref 仅在当前 request_id 内有效，不是持久化 ID。
  • db_action 为统一响应信封的兼容字段，值必须始终为 null。
  • 输出不得包含真实 ID、版本、权限或 create/update/delete/query 指令。

4.1 数据来源

数据类型 原始来源 整理责任 子 Agent 获取方式
用户当前输入 文字、语音转写或图片识别文本 母 AI raw_input 或 raw_feedback
已解析参数 母 AI 对当前输入的解析结果 母 AI 对应类型化字段
最近对话 当前用户最近 20 条对话 母 AI recent_messages
事项、目标和反馈事实 对应业务模块 母 AI 读取、筛选和裁剪 候选列表或事实 DTO
用户画像 用户已确认的全局偏好 母 AI user_profile
任务级画像 当前目标的已确认偏好 母 AI goal_scoped_profile
统计指标与数据覆盖 确定性统计能力和母 AI 母 AI computed_metrics、data_coverage

4.2 参数优先级

当信息冲突时，子 Agent 必须按以下顺序处理：

  1. 母 AI 已确认的内容要求和目标范围。
  2. 母 AI 提供的业务事实 DTO。
  3. 用户当前 raw_input 或 raw_feedback。
  4. recent_messages 提供的辅助语境。

硬性规则：

  • 已确认参数是本次调用的最终参数，子 Agent 不得静默改变对象类型、目标范围或时间范围。
  • 业务事实 DTO 是事实来源，对话文本不能覆盖事实字段。
  • recent_messages 只用于理解语气和背景，不再用于目标定位或指代消解。
  • 当前输入、历史对话与已确认参数冲突时返回 FACT_CONFLICT，不得自行选择一个版本。

4.3 公共模型规则

所有公共 DTO 必须继承同一契约基类，并统一满足：

  • 未声明字段一律拒绝，防止模型夹带真实 ID 或动作字段。
  • 字符串首尾空白统一清理。
  • 赋值后继续执行校验。
  • 所有 datetime 必须带时区偏移。
  • TimeRangeDTO.end_at 必须晚于 start_at。
  • recent_messages 最多 20 条，角色只允许 user/assistant。

4.4 调用信封

每次调用必须携带独立的 AgentCallContext：

字段 类型 来源 规则 是否进入模型
request_id string 母 AI 唯一标识当前请求，响应必须原样返回 否
trace_id string/null 母 AI 关联调用链和观测记录 否
deadline_at datetime 母 AI 带时区的绝对截止时间；迟到结果丢弃 否
agent_name 五个固定 Agent 名之一 母 AI 路由结果 与 function_name 必须组成固定配对 是
function_name 五个固定函数名之一 母 AI 路由结果 指定唯一目标 Handler 是

用户身份和权限由母 AI 保留，不进入调用信封、业务输入或模型 Prompt。

4.5 固定路由表

SubAgentDispatcher.dispatch(context, input_data) 只校验和分发，不读取用户原话重新识别意图。

agent_name function_name 唯一输入类型 唯一输出类型
日程待办 Agent generate_item_content ScheduleTodoAgentInput AgentResponse[ItemContentCandidate]
反馈 Agent normalize_feedback FeedbackAgentInput AgentResponse[FeedbackContentCandidate]
长任务拆分 Agent split_long_goal LongTaskSplitAgentInput AgentResponse[LongGoalPlanCandidate]
重排 Agent generate_replan_content ReplanAgentInput AgentResponse[ReplanContentProposal]
复盘 Agent generate_review ReviewAgentInput AgentResponse[ReviewResultDTO]

任一配对或输入类型不一致时：

  • 返回 CONTRACT_MISMATCH。
  • 不调用任何 Handler。
  • 不调用模型。
  • 不尝试其他子 Agent。

4.6 子 Agent 独立性

维度 约束
调用独立 一个请求只调用一个子 Agent，不自动串联
职责独立 每个 Agent 只解决本模块问题
输入独立 每个 Agent 使用自己的输入类型，由母 AI 一次性准备完整
Prompt 独立 每个函数使用自己的 prompt_key + prompt_version
输出独立 每个 Agent 使用自己的业务结果类型，只共享外层信封
模型路由独立 每个函数拥有独立主备模型配置
上下文独立 只使用当前请求输入，不读取其他 Agent 上下文
状态独立 不共享可变业务状态
故障独立 当前 Agent 失败不触发其他 Agent 接管
返回独立 结果直接返回母 AI，不先传给其他子 Agent
测试独立 可使用母 AI Stub 和 LLM Stub 单独测试

共享 LLM 管理模块只共享模型调用能力，不共享业务逻辑、Prompt、输入、输出或运行状态。

5. 总体调用流程

flowchart LR
    M["母 AI<br/>选定路由并准备完整输入"] --> D["SubAgentDispatcher<br/>校验路由和输入类型"]
    D --> A["唯一目标子 Agent<br/>校验业务事实"]
    A --> L["LLM 管理模块<br/>生成、解析与故障转移"]
    L --> V["当前 Agent 的<br/>OutputValidator"]
    V --> A
    A --> R["AgentResponse[T]<br/>db_action = null"]
    R --> M
Loading

处理顺序固定为：

  1. Dispatcher 校验 agent_name + function_name + input_data 类型。
  2. 目标子 Agent 校验必填字段、时间、范围、引用和事实一致性。
  3. LLM 管理模块加载固定版本 Prompt 与模型路由，计算上下文预算。
  4. 模型结果先经过 JSON、Schema 和当前 Agent 的确定性业务校验。
  5. 仅返回一个通过全部校验的类型化结果，或一个统一结构化错误。
  6. 子 Agent 返回 AgentResponse[T] 后职责结束。

6. 五个业务接口

Agent 函数 核心输入 核心输出 正常响应
日程待办 Agent generate_item_content 对象类型、内容要求、可选现有内容、最近对话 ItemContentCandidate CONFIRM
反馈 Agent normalize_feedback 原始反馈、时间范围、发生时间、唯一目标临时引用 FeedbackContentCandidate CONFIRM
长任务拆分 Agent split_long_goal 长期目标、已有子任务、画像、未来 7–14 天可用时段 LongGoalPlanCandidate 有候选时 CONFIRM；不可行或无变化时 DISPLAY
重排 Agent generate_replan_content 重排范围、未来事项、未完成反馈、固定事项临时引用 ReplanContentProposal 有建议时 CONFIRM；不可行或无变化时 DISPLAY
复盘 Agent generate_review 复盘范围、事项事实、反馈、可信指标、数据覆盖 ReviewResultDTO DISPLAY

6.1 日程待办 Agent

  • 支持 schedule、todo、subtask、long_goal 四类结构化内容。
  • compose 用于从零整理，revise 必须携带已有内容。
  • 不得自行补造时间、地点或用户未提供的事实。
  • 模型全部失败时，仅在最小必填字段完整且事实无冲突时允许确定性复制输入。

输入 ScheduleTodoAgentInput：

字段 类型 必填 规则
raw_input string 是 当前用户对事项内容的表达
generation_mode compose/revise 是 内容生成模式，不是 CRUD 动作
item_type schedule/todo/subtask/long_goal 是 限定唯一候选类型
content_requirements ItemContentRequirementsDTO 是 已确认的内容与时间要求
current_item_content ItemContentCandidate/null 条件必填 revise 必填，compose 禁止；类型必须与 item_type 一致
recent_messages ConversationMessageDTO[] 是 最多 20 条，只提供语境

ItemContentRequirementsDTO 字段：

字段 类型 约束
title string/null 标题
description string/null 描述
start_at datetime/null 开始时间
end_at datetime/null 必须晚于 start_at
due_at datetime/null 待办或子任务截止时间
deadline_at datetime/null 长期目标期限；如有 start_at，必须晚于它
estimated_minutes integer/null 大于等于 1
plan_overview string/null 长期目标宏观规划
must_keep_terms string[] 输出必须保留的名称、地点或关键词
additional_constraints string[] 其他已确认约束

ItemContentCandidate 是四种独立结构的联合类型：

类型 必填字段 可选字段
ScheduleContentCandidate item_type=schedule、title、start_at、end_at description、assumptions、warnings
TodoContentCandidate item_type=todo、title description、due_at、assumptions、warnings
SubtaskContentCandidate item_type=subtask、title description、start_at、end_at、due_at、estimated_minutes、assumptions、warnings
LongGoalContentCandidate item_type=long_goal、title description、start_at、deadline_at、plan_overview、assumptions、warnings

正常结果固定为 CONFIRM。主要失败口径：

场景 reason_code 公共错误 处理
compose/revise 与现有内容不匹配 GENERATION_MODE_MISMATCH INPUT_INVALID 模型调用前拒绝
输入类型与现有内容类型不同 ITEM_TYPE_MISMATCH FACT_CONFLICT 模型调用前拒绝
时间缺失、倒置或互相冲突 ITEM_TIME_INVALID INPUT_INVALID 模型调用前拒绝
遗漏必须保留词 MUST_KEEP_TERM_MISSING OUTPUT_INVALID 丢弃并切换备用模型
编造时间、地点或事实 INVENTED_ITEM_FACT OUTPUT_INVALID 丢弃并切换备用模型
输出类型或必填字段错误 ITEM_OUTPUT_TYPE_MISMATCH OUTPUT_INVALID 丢弃并切换备用模型
出现真实 ID、版本或动作字段 FORBIDDEN_OPERATION_FIELD OUTPUT_INVALID 丢弃整份内容
全部模型失败 ALL_MODELS_FAILED LLM_UNAVAILABLE 满足最小结构时确定性降级，否则 ERROR

确定性降级的最小结构：

  • 日程：title + start_at + end_at，且时间合法。
  • 待办：title。
  • 子任务：title。
  • 长期目标：title。

降级只能复制明确输入，不润色、不推断、不补造。

6.2 反馈 Agent

  • 目标必须由母 AI 唯一定位，并通过 target_ref 传入。
  • raw_feedback 必须原样保留，occurred_at 必须位于反馈时间范围内。
  • execution_status 只是反馈语义分类，不是事项状态修改指令。
  • 模型全部失败时返回错误，不使用默认状态或规则模板猜测。

输入 FeedbackAgentInput：

字段 类型 必填 规则
raw_feedback string 是 原始反馈，输出必须原样回传
feedback_time_range TimeRangeDTO 是 限定反馈发生范围
occurred_at datetime 是 必须位于时间范围内
target_item TargetItemContextDTO 是 母 AI 已唯一定位的目标
recent_messages ConversationMessageDTO[] 是 最多 20 条，不用于重新选目标

TargetItemContextDTO：

字段 类型 规则
target_ref string 当前请求临时引用，输出必须原样返回
item_type schedule/subtask 仅允许日程或子任务反馈
title string 目标标题
start_at datetime/null 目标开始时间
end_at datetime/null 目标结束时间
status active/completed/cancelled 当前事实状态

输出 FeedbackContentCandidate：

字段 类型 规则
target_ref string 与输入完全一致
execution_status completed/not_completed/partially_completed/deferred/cancelled 反馈语义分类
raw_feedback string 与输入完全一致
normalized_feedback string 清晰化表达，不新增原因
duration_minutes integer/null 大于等于 0；未明确时为 null
occurred_at datetime 与输入一致且位于允许范围

正常结果固定为 CONFIRM。主要失败口径：

场景 reason_code 公共错误 处理
目标缺失或不唯一 TARGET_NOT_UNIQUE INPUT_INVALID 模型调用前拒绝
目标事实与反馈冲突 FEEDBACK_FACT_CONFLICT FACT_CONFLICT 模型调用前拒绝
临时引用未知、改变或跨请求 TARGET_REF_MISMATCH OUTPUT_INVALID 丢弃并切换备用模型
发生时间越界 FEEDBACK_TIME_OUT_OF_RANGE INPUT_INVALID 模型调用前拒绝
原始反馈被改写或新增原因 RAW_FEEDBACK_MUTATED OUTPUT_INVALID 丢弃并切换备用模型
状态非法或明显矛盾 EXECUTION_STATUS_INVALID OUTPUT_INVALID 丢弃并切换备用模型
耗时为负或被编造 FEEDBACK_DURATION_INVALID OUTPUT_INVALID 丢弃；不明确时只能为 null
出现目标 ID 或保存、修改指令 FORBIDDEN_OPERATION_FIELD OUTPUT_INVALID 丢弃整份内容
全部模型失败 ALL_MODELS_FAILED LLM_UNAVAILABLE 返回 ERROR，禁止确定性降级

6.3 长任务拆分 Agent

  • 输出全周期宏观规划和未来 7–14 天的近期子任务候选。
  • 子任务必须落入可用时段，不得与已有近期子任务重复。
  • 使用 feasible/partial/infeasible/no_change 表示业务可行性。
  • 模型全部失败时返回错误，不强行生成拆分结果。

输入 LongTaskSplitAgentInput：

字段 类型 必填 规则
raw_input string 是 当前拆分要求
long_goal LongGoalContextDTO 是 唯一目标语境，不含真实 ID
existing_subtasks SubtaskContentCandidate[] 是 规划范围内已有子任务；首次可为空
user_profile UserProfileDTO 是 timezone + preferences
goal_scoped_profile GoalScopedProfileDTO/null 否 当前目标的任务级偏好
current_time datetime 是 确定性时间基准
available_time_slots TimeSlotDTO[] 是 每个时段起止合法、位于规划范围内且互不重叠
planning_range TimeRangeDTO 是 不早于 current_time，覆盖 7–14 天
recent_messages ConversationMessageDTO[] 是 最多 20 条

LongGoalContextDTO 包含 title、可选 description/start_at/deadline_at/plan_overview；如开始时间与期限同时存在，期限必须更晚。

输出 LongGoalPlanCandidate：

字段 类型 规则
plan_status feasible/partial/infeasible/no_change 决定响应类型与候选数量
plan_overview string 全周期宏观规划
planning_range TimeRangeDTO 必须与输入一致
subtasks SubtaskCandidate[] 仅覆盖未来 7–14 天
assumptions string[] 明示采用的假设
capacity_warnings string[] 容量、期限和冲突风险
tradeoffs string[] 为满足主要目标所做取舍

每个 SubtaskCandidate 必须包含 title、可选 description、start_at、end_at、大于等于 1 的 estimated_minutes 和 rationale。结束时间必须晚于开始时间，并落入规划范围及至少一个可用时段。

响应规则：

plan_status 子任务要求 响应
feasible 至少一个完整候选 CONFIRM
partial 至少一个安全候选，并明确告警和取舍 CONFIRM
infeasible subtasks=[]，说明不可行原因及可调整约束 DISPLAY
no_change subtasks=[]，说明已有内容已覆盖要求 DISPLAY

主要失败口径：

场景 reason_code 公共错误 处理
目标时间矛盾 LONG_GOAL_TIME_INVALID INPUT_INVALID 模型调用前拒绝
规划范围不是未来 7–14 天 PLANNING_RANGE_INVALID INPUT_INVALID 模型调用前拒绝
可用时段非法、越界或重叠 AVAILABLE_SLOT_INVALID INPUT_INVALID 模型调用前拒绝
候选超出容量或可用时段 SUBTASK_OUTSIDE_CAPACITY OUTPUT_INVALID 丢弃并切换备用模型
候选与已有任务重复 DUPLICATE_SUBTASK OUTPUT_INVALID 丢弃并切换备用模型
子任务时间或耗时非法 SUBTASK_TIME_INVALID OUTPUT_INVALID 丢弃并切换备用模型
状态与候选数量不一致 PLAN_STATUS_MISMATCH OUTPUT_INVALID 丢弃并切换备用模型
出现真实目标 ID 或创建指令 FORBIDDEN_OPERATION_FIELD OUTPUT_INVALID 丢弃整份内容
全部模型失败 ALL_MODELS_FAILED LLM_UNAVAILABLE 返回 ERROR，禁止规则拆分

6.4 重排 Agent

  • 支持全部事项和单一长期目标两种范围。
  • adjust_existing 只能引用输入中的 item_ref；propose_new 不得携带来源引用。
  • 不得调整 fixed_item_refs 中的事项，不得输出删除、取消或状态修改指令。
  • 任一非法建议会使整份方案失效；模型全部失败时返回错误。

输入 ReplanAgentInput：

字段 类型 必填 规则
raw_input string 是 当前重排要求
scope all_items/single_long_goal 是 限定重排范围
long_goal LongGoalContextDTO/null 条件必填 单目标范围必填；全局范围禁止
reason string 是 用户提出的重排原因
current_time datetime 是 区分历史和未来事项
future_items ReplanItemContextDTO[] 是 至少一项，引用唯一，且只含未来事项
unfinished_feedback_items FeedbackContextDTO[] 否 引用唯一且必须属于 future_items
user_profile UserProfileDTO 是 通用偏好
goal_scoped_profile GoalScopedProfileDTO/null 否 单目标偏好
fixed_item_refs string[] 否 引用唯一且必须属于 future_items
recent_messages ConversationMessageDTO[] 是 最多 20 条

ReplanItemContextDTO 包含 item_ref、item_type、title、可选 description/start_at/end_at/due_at 和 status。FeedbackContextDTO 包含 item_ref、normalized_feedback 和 execution_status。

输出 ReplanContentProposal：

字段 类型 规则
scope all_items/single_long_goal 必须与输入一致
plan_status feasible/partial/infeasible/no_change 决定响应与建议数量
summary string 中性、简洁的重排思路
suggestions ReplanContentSuggestion[] 内容级建议，不是动作
warnings string[] 容量、冲突或无法同时满足的要求
tradeoffs string[] 方案取舍

每个 ReplanContentSuggestion：

字段 类型 规则
suggestion_kind adjust_existing/propose_new 调整现有内容或提出新内容
source_item_ref string/null 调整现有项时必填且来自输入；新内容时必须为空
item_type schedule/todo/subtask 必须与 proposed_content.item_type 一致
proposed_content 三类事项候选之一 不含真实 ID、版本、状态修改或动作
reason string 说明如何回应约束
sort_order integer 大于等于 0

同一 source_item_ref 最多调整一次。响应规则与长任务拆分一致：feasible/partial 返回 CONFIRM 且至少一条合法建议；infeasible/no_change 返回 DISPLAY 且建议数组为空。

主要失败口径：

场景 reason_code 公共错误 处理
范围与目标上下文不匹配 REPLAN_SCOPE_MISMATCH INPUT_INVALID 模型调用前拒绝
未来事项为空、含过去事项或引用重复 FUTURE_ITEMS_INVALID INPUT_INVALID 模型调用前拒绝
固定引用不属于未来事项 FIXED_REF_INVALID INPUT_INVALID 模型调用前拒绝
来源引用未知、跨请求或重复 SOURCE_ITEM_REF_INVALID OUTPUT_INVALID 丢弃并切换备用模型
调整固定事项 FIXED_ITEM_VIOLATION OUTPUT_INVALID 丢弃整份方案
建议类型与来源引用不匹配 SUGGESTION_KIND_MISMATCH OUTPUT_INVALID 丢弃并切换备用模型
候选类型或时间非法 PROPOSED_CONTENT_INVALID OUTPUT_INVALID 丢弃并切换备用模型
状态与建议数量不一致 PLAN_STATUS_MISMATCH OUTPUT_INVALID 丢弃并切换备用模型
出现删除、取消、状态修改、真实 ID 或版本 FORBIDDEN_OPERATION_FIELD OUTPUT_INVALID 丢弃整份方案
全部模型失败 ALL_MODELS_FAILED LLM_UNAVAILABLE 返回 ERROR，禁止规则重排

6.5 复盘 Agent

  • 所有数字只能来自 computed_metrics，所有事实只能来自输入 DTO。
  • 必须说明 data_coverage，不能把数据缺失解释为用户未完成。
  • 输出风格为事实优先、自然、非指责、不过度安慰。
  • 模型全部失败时可使用确定性事实模板，但不得新增数字、原因、情绪或推断。

输入 ReviewAgentInput：

字段 类型 必填 规则
raw_input string 是 当前复盘关注点
review_type all_items/single_long_goal 是 限定复盘范围
review_time_range TimeRangeDTO 是 复盘时间范围
long_goal LongGoalContextDTO/null 条件必填 单目标范围必填；全部事项范围禁止
schedules ReviewItemFactDTO[] 否 只能包含 schedule 事实
todos ReviewItemFactDTO[] 否 只能包含 todo 事实
subtasks ReviewItemFactDTO[] 否 只能包含 subtask 事实
feedback FeedbackFactDTO[] 否 范围内反馈事实
computed_metrics dict[string, int/float] 是 确定性统计结果
data_coverage DataCoverageDTO 是 数据覆盖状态和缺口
recent_messages ConversationMessageDTO[] 是 最多 20 条

ReviewItemFactDTO 包含 item_type、title、status 及可选时间；FeedbackFactDTO 包含事项标题、执行状态、规范化反馈和发生时间。

DataCoverageDTO：

字段 类型 规则
coverage_status complete/partial partial 时必须提供缺口说明
covered_range TimeRangeDTO 不得超出 review_time_range
notes string[] 部分覆盖时不能为空

输出固定为非空 ReviewResultDTO.review_text，正常响应固定为 DISPLAY。报告必须包含：

  1. 复盘范围和数据覆盖说明。
  2. 只引用 computed_metrics 的结果总结。
  3. 基于输入事实、非指责且不编造情绪或原因的观察。
  4. 1–3 条小而可执行的建议。
  5. 克制、真诚的结束语。

主要失败口径：

场景 reason_code 公共错误 处理
时间范围倒置或单目标缺失 REVIEW_SCOPE_INVALID INPUT_INVALID 模型调用前拒绝
数据覆盖缺失或与事实冲突 DATA_COVERAGE_INVALID FACT_CONFLICT 模型调用前拒绝
指标类型非法、来源不可信或与事实冲突 METRIC_SOURCE_INVALID FACT_CONFLICT 模型调用前拒绝
重算或引用不存在的数字 UNSUPPORTED_METRIC_CLAIM OUTPUT_INVALID 丢弃并切换备用模型
编造事项、日期、原因或情绪 REVIEW_FACT_HALLUCINATION OUTPUT_INVALID 丢弃并切换备用模型
文本为空或截断 REVIEW_OUTPUT_INCOMPLETE OUTPUT_INVALID 丢弃并切换备用模型
缺少数据覆盖或必需部分 REVIEW_SECTION_MISSING OUTPUT_INVALID 丢弃并切换备用模型
指责、过度安慰或风格非法 REVIEW_STYLE_INVALID OUTPUT_INVALID 丢弃并切换备用模型
全部模型失败 ALL_MODELS_FAILED LLM_UNAVAILABLE 使用确定性事实模板

确定性模板按“覆盖说明 → 指标原样展示 → 已完成/未完成事实 → 克制结束语”生成，仍需通过事实引用校验。

7. 统一响应与错误契约

AgentResponse[T] 至少包含：

  • 请求与路由：request_id、trace_id、agent_name、function_name。
  • 控制字段：response_type、isNeedUser、isDisplayResult、isError。
  • 业务字段：result、db_action、generation_path、error。

控制字段只能使用以下组合：

response_type isNeedUser isDisplayResult isError 含义
DISPLAY false true false 可直接展示
CONFIRM true false false 内容候选需要确认
ERROR false false true 结构化错误

CONFIRM 只表示内容候选需要由调用方确认，不包含 CRUD 动作，也不表示可以直接执行。展示、确认、版本复查、权限复查和持久化均属于母 AI。

成功响应必须满足：

  • result != null、error = null。
  • generation_path 为 primary_model、fallback_model 或 deterministic_fallback。
  • db_action = null。

错误响应必须满足：

  • result = null、error != null、generation_path = none。
  • AgentErrorDTO 包含稳定 code、具体 reason_code、category、failed_stage、retryable 和安全的 safe_message。
  • 不得暴露供应商原始错误、模型名称、Prompt、密钥、调用栈、原始响应或模型半成品。

7.1 统一响应字段

字段 类型 规则
request_id string 原样复制当前调用信封
trace_id string/null 原样复制，用于观测关联
agent_name string 必须与调用信封一致
function_name string 必须与 Agent 固定配对
response_type DISPLAY/CONFIRM/ERROR 唯一处理分支
isNeedUser boolean 只能使用固定组合
isDisplayResult boolean 只能使用固定组合
isError boolean 只能使用固定组合
result TResult/null 成功非空，错误为空
db_action null 必填且只能显式为 null
generation_path primary_model/fallback_model/deterministic_fallback/none 标识内容来源
error AgentErrorDTO/null 成功为空，错误非空

7.2 输出风格

Agent 风格 约束
日程待办、反馈、长任务拆分、重排 structured_factual 只返回结构化业务字段，不含问候、安慰、鼓励或对话式总结
复盘 warm_factual 可以自然有人情味，但事实、指标与数据覆盖优先

四个结构化 Agent 的标题、描述、反馈、规划、摘要和理由必须简洁、中性、无歧义；不得编造用户情绪、动机、困难或完成原因。

7.3 公共错误码

code 典型原因 是否允许重试 终止行为
CONTRACT_MISMATCH 路由、输入类型或响应控制字段非法 否 模型调用前停止
INPUT_INVALID 必填字段、时间、范围或引用非法 条件允许 模型调用前停止
FACT_CONFLICT 当前输入、对话与事实 DTO 冲突 条件允许 停止生成，不让模型猜测
CONFIG_ERROR Prompt、Schema、路由或生成配置缺失 否 不调用供应商，记录配置告警
NO_COMPATIBLE_MODEL 没有满足能力与上下文要求的模型 是 不放宽契约，评估安全降级或报错
CONTEXT_TOO_LARGE 必需内容安全裁剪后仍超限 条件允许 不调用供应商
LLM_UNAVAILABLE 主备模型均发生可重试技术故障 是 丢弃半成品，评估安全降级或报错
DEADLINE_EXCEEDED 模型、修复或校验耗尽总时限 是 终止链路并拒绝迟到结果
OUTPUT_INVALID 解析、Schema 或业务输出校验失败 是 丢弃当前结果，按路线继续或结束
CONTENT_BLOCKED 内容安全策略拦截 否 立即停止，不切换模型绕过
REQUEST_CANCELLED 上游取消或链路过期 否 停止尝试并拒绝迟到结果
INTERNAL_ERROR 未分类内部异常或包装失败 是 丢弃结果并返回安全摘要

reason_code 由唯一 ErrorReasonPolicyRegistry 映射为 code + category + failed_stage + retryable。业务函数和 LLM 管理模块只提交 reason_code + safe_message，不得各自拼装公共错误字段；未登记原因统一映射为 INTERNAL_ERROR 并告警。

7.4 错误分类与失败阶段

category 只允许：

  • contract
  • input
  • configuration
  • provider
  • output
  • safety
  • deadline
  • internal

failed_stage 只允许：

  • validate_context
  • validate_input
  • build_prompt
  • select_model
  • invoke_model
  • parse_output
  • validate_output
  • build_response

8. LLM 管理与故障转移

LLM 管理模块只负责模型调用，不理解具体业务，也不改变 Agent、函数、Prompt、输入、输出 Schema 或内容风格。

固定处理链路为：

调用前校验
→ 主模型
→ 必要时使用同一模型进行一次受控格式修复
→ 按顺序尝试 1–2 个备用模型
→ 当前 Agent 的确定性安全降级或结构化错误

必须满足：

  • 所有尝试共享同一个绝对截止时间，切换模型时不得重新计时。
  • 格式修复最多一次，并计入 max_attempts 和总时限。
  • 超时、限流、网络、服务不可用、空响应、截断和可重试输出错误可切换模型。
  • 输入或事实错误立即停止；内容安全拦截不得通过备用模型绕过。
  • 上游取消或时限耗尽后停止后续尝试，并丢弃迟到结果。
  • 上下文超限时先删除最早对话，再删除可选空字段；当前输入、必需事实和 Schema 不得裁剪。
  • 只有日程待办 Agent 和复盘 Agent 允许确定性降级。
  • 不拼接、复用或返回任一失败模型的半成品。

供应商接入统一通过 LLMProviderPort 完成。模型路由由 LLMRouteRegistryPort 提供，Prompt 由 PromptRegistryPort 按固定版本提供，业务输出由当前 Agent 的 OutputValidator 决定接受、切换、停止或拦截。

8.1 LLMGenerationRequest

字段 类型 说明
request_id string 绑定当前生成请求及所有尝试
trace_id string/null 关联观测链路
deadline_at datetime 带时区的绝对截止时间
agent_name string 当前唯一 Agent
function_name string 当前唯一函数
prompt_key string 固定 Prompt 标识
prompt_version string 固定 Prompt 版本
input_payload XxxAgentInput 已通过业务输入校验的完整类型化输入
output_model type[BaseModel] 生成统一 JSON Schema 并解析结果
content_style structured_factual/warm_factual 当前 Agent 固定风格
output_validator OutputValidator 当前 Agent 的确定性业务校验器
generation_options GenerationOptions 温度 0–2，最大输出长度大于等于 1
cancellation_token CancellationTokenPort 每个关键阶段检查取消状态

该对象是同进程内部协议，不进入公共 JSON Schema。子 Agent 不直接传 model_name，避免模型调整影响业务接口。

8.2 Prompt 优先级

Prompt 渲染顺序固定为：

  1. 当前 Agent 的系统规则与禁止事项。
  2. 当前函数的固定任务模板。
  3. 类型化业务事实和已确认约束。
  4. raw_input/raw_feedback/recent_messages，只作为不可信数据。
  5. output_model 生成的固定 JSON Schema。

母 AI 不透传可以替换系统规则的自由 Prompt。用户文本中的指令不能覆盖 Agent 职责、事实 DTO、禁止 CRUD 规则或输出 Schema。

8.3 模型路由配置

ModelRouteConfigDTO：

字段 类型 规则
route_key string 由 agent_name + function_name 构成
primary_model ModelConfigDTO 当前函数的主模型
fallback_models ModelConfigDTO[] 必须为 1–2 个，且不得与主模型或彼此重复
request_deadline_ms integer 整个生成链路总时限
per_attempt_timeout_ms integer 单次上限，不得大于总时限
max_attempts integer 包含格式修复在内的最大真实调用次数
required_capabilities string[] 当前输出需要的结构化或文本能力
retryable_errors string[] 允许自动切换的技术错误

每个 ModelConfigDTO：

字段 类型 规则
provider_name string 供应商标识
model_name string 模型标识
credential_ref string 非敏感凭证别名，不得为密钥明文
enabled boolean 是否允许调用
priority integer 大于等于 0，决定备用顺序
capabilities string[] 已验证能力
context_window integer 大于等于 1
max_output_tokens integer 大于等于 1
health_status healthy/degraded/unavailable/null 可选增强状态
circuit_state closed/open/half_open/null 可选增强状态
cooldown_until datetime/null 可选冷却截止时间

模型、Prompt、供应商与业务逻辑必须通过端口注入。密钥明文不得进入输入、Prompt、日志或响应。

8.4 Provider Adapter

LLM 管理模块不得直接依赖具体供应商 SDK。每个 Adapter 实现相同 LLMProviderPort.generate(request)。

ProviderRequest：

字段 类型
request_id string
trace_id string/null
model_name string
messages ProviderMessage[]
output_schema object
timeout_ms 大于等于 1 的整数
temperature 0–2
max_output_tokens 大于等于 1 的整数

ProviderResponse：

字段 类型 规则
request_id string 必须与当前请求一致
raw_content string 必须先解析和校验，不直接返回业务层
finish_reason stop/length/content_filter/other 截断和拦截按固定规则处理
input_tokens integer/null 大于等于 0
output_tokens integer/null 大于等于 0

ProviderFailureDTO 只包含 provider_name、model_name、安全 reason_code、retryable 和 safe_message。允许的供应商原因包括：

  • PROVIDER_AUTH_FAILED
  • PROVIDER_PERMISSION_DENIED
  • RATE_LIMITED
  • MODEL_TIMEOUT
  • NETWORK_ERROR
  • PROVIDER_UNAVAILABLE
  • CONTENT_BLOCKED
  • REQUEST_CANCELLED

原始异常、响应体和密钥不得向上透传。

8.5 模型调用前筛选

筛选顺序固定：

  1. 跳过 enabled=false 的模型。
  2. 跳过不满足 required_capabilities 的模型。
  3. 启用健康检查时，跳过 health_status=unavailable。
  4. 启用熔断时，跳过仍在冷却期的 circuit_state=open 模型。
  5. 启用半开探测时，只允许配置数量的探测请求。
  6. 仅在剩余总时限足够一次调用时尝试；单次时限取配置上限与剩余时限的较小值。

MVP 基线实现固定主模型和 1–2 个固定备用模型；健康状态、熔断和半开探测不是当前联调阻塞条件。

有效截止点固定为：

min(
  AgentCallContext.deadline_at,
  LLM 管理模块开始时间 + request_deadline_ms
)

模型调用、格式修复、业务校验和响应包装共享该截止点，切换模型不得重新计时。

8.6 业务输出校验四态

决策 含义 动作
ACCEPT 格式、事实和业务规则全部通过 立即返回当前内容
RETRYABLE_GENERATION_INVALID 模型输出可通过重新生成修复 丢弃当前内容并切换备用模型
NON_RETRYABLE_INPUT_INVALID 输入缺失、事实冲突或方案过期 停止切换，返回输入或事实错误
BLOCKED 安全策略或内容政策拦截 立即停止，禁止切换绕过

五个校验器必须独立：

Agent validator_id 必须比较的事实
日程待办 schedule_todo.generate_item_content.v1 类型、明确时间、保留词、现有类型和禁止字段
反馈 feedback.normalize_feedback.v1 target_ref、raw_feedback、occurred_at、状态和耗时
长任务拆分 long_task_split.split_long_goal.v1 规划范围、可用时段、已有任务、状态与候选数量
重排 replan.generate_replan_content.v1 范围、输入引用、固定事项、建议类型和候选类型
复盘 review.generate_review.v1 复盘范围、日期、指标、事实引用和 warm_factual 风格

LLM 管理模块只调用统一的 validate(input_data, output_data)，不保存跨请求校验状态，也不依赖具体 Agent 实现。

8.7 上下文预算与安全裁剪

必须先加载并筛选当前模型路由，再按候选模型真实窗口计算预算，并预留系统 Prompt、输出 Schema 和模型返回空间。

超限时只允许：

  1. 从最早一条开始删除 recent_messages，不得删除当前用户输入。
  2. 删除值为 null、空数组或空字符串的可选字段。
  3. 使用候选模型真实窗口重新计算。
  4. 必需内容仍无法容纳时返回 CONTEXT_TOO_LARGE，且 attempts=[]。

禁止裁剪时间、目标、固定事项、指标、临时引用或其他会改变业务语义的非空字段，也禁止调用另一个模型总结上下文后继续生成。

8.8 故障作用域

作用域 典型 reason_code 处理
请求级 INPUT_MISSING、FACT_CONFLICT、CONTENT_BLOCKED、REQUEST_CANCELLED 立即停止全部尝试
配置级 MODEL_ROUTE_NOT_FOUND、PROMPT_CONFIG_MISSING、OUTPUT_SCHEMA_CONFIG_INVALID 不调用模型，返回 CONFIG_ERROR
凭证级 PROVIDER_AUTH_FAILED、PROVIDER_PERMISSION_DENIED 跳过相同 credential_ref 的模型；其他凭证可继续
模型能力级 MODEL_DISABLED、CAPABILITY_MISMATCH、CONTEXT_WINDOW_INSUFFICIENT 跳过当前模型；全部跳过返回 NO_COMPATIBLE_MODEL
单次调用级 MODEL_TIMEOUT、RATE_LIMITED、NETWORK_ERROR、PROVIDER_UNAVAILABLE 记录失败并切换，不在同一故障模型循环
输出格式级 EMPTY_RESPONSE、RESPONSE_TRUNCATED、OUTPUT_PARSE_FAILED、OUTPUT_SCHEMA_INVALID 空响应或截断直接切换；解析或 Schema 错误最多修复一次
业务输出级 BUSINESS_OUTPUT_INVALID 及各 Agent 原因码 可重试则切换，输入或事实错误则停止
总时限级 REQUEST_DEADLINE_EXCEEDED 取消当前尝试并停止后续调用
内部级 UNEXPECTED_PROVIDER_RESPONSE、INTERNAL_EXCEPTION 丢弃结果，能安全切换则继续，否则 INTERNAL_ERROR

8.9 故障转移状态机

stateDiagram-v2
    [*] --> PRECHECK
    PRECHECK --> FAILED: 请求或配置非法
    PRECHECK --> CANCELLED: 已取消或超时
    PRECHECK --> TRY_PRIMARY: 校验通过

    TRY_PRIMARY --> PARSE_AND_VALIDATE: 收到响应
    TRY_PRIMARY --> TRY_FALLBACK: 可切换技术故障
    TRY_PRIMARY --> BLOCKED: 内容安全拦截

    PARSE_AND_VALIDATE --> SUCCESS: 全部校验通过
    PARSE_AND_VALIDATE --> FORMAT_REPAIR: 首次JSON或Schema形状错误
    PARSE_AND_VALIDATE --> TRY_FALLBACK: 可重试业务输出错误
    PARSE_AND_VALIDATE --> FAILED: 输入或事实错误
    PARSE_AND_VALIDATE --> BLOCKED: 安全拦截

    FORMAT_REPAIR --> PARSE_AND_VALIDATE: 修复完成
    FORMAT_REPAIR --> TRY_FALLBACK: 修复失败
    FORMAT_REPAIR --> CANCELLED: 取消或超时

    TRY_FALLBACK --> PARSE_AND_VALIDATE: 备用模型返回
    TRY_FALLBACK --> TRY_FALLBACK: 仍有备用模型
    TRY_FALLBACK --> TERMINAL_FALLBACK: 路线、次数或时限耗尽
    TRY_FALLBACK --> CANCELLED: 取消或超时
    TRY_FALLBACK --> BLOCKED: 安全拦截

    TERMINAL_FALLBACK --> SUCCESS: 当前Agent安全降级成功
    TERMINAL_FALLBACK --> FAILED: 禁止降级或降级失败

    SUCCESS --> [*]
    FAILED --> [*]
    BLOCKED --> [*]
    CANCELLED --> [*]
Loading

主模型、唯一一次格式修复和每个备用模型都计入 max_attempts 与总时限。超出任一上限立即停止。

8.10 受控格式修复

  • 使用产生格式错误的同一模型。
  • 使用原始输入、相同 Prompt 版本和相同输出 Schema。
  • 只要求把已有回答重新输出成目标 JSON。
  • 整个请求最多一次。
  • 不得新增事实、猜测参数、改变事项类型、范围、时间或风格。
  • 缺少业务字段、编造事实、真实 ID 或 CRUD 泄漏、固定事项违规不属于格式问题，必须进入业务输出失败路径。

8.11 最终确定性降级

仅当公共失败原因为 LLM_UNAVAILABLE、NO_COMPATIBLE_MODEL，或所有实际模型输出均为 OUTPUT_INVALID 时评估。

以下错误禁止使用模板掩盖：

  • INPUT_INVALID
  • FACT_CONFLICT
  • CONFIG_ERROR
  • CONTEXT_TOO_LARGE
  • CONTENT_BLOCKED
  • REQUEST_CANCELLED
  • DEADLINE_EXCEEDED
Agent 允许降级 条件 结果
日程待办 是 明确字段满足对应事项最小结构且无事实冲突 原样组装候选，CONFIRM
反馈 否 状态和规范化文本需要语义判断 ERROR + LLM_UNAVAILABLE
长任务拆分 否 需要容量、拆分与排期推理 ERROR + LLM_UNAVAILABLE
重排 否 需要固定事项、冲突和取舍推理 ERROR + LLM_UNAVAILABLE
复盘 是 覆盖、指标和事实 DTO 均合法 确定性事实模板，DISPLAY

降级由当前子 Agent 生成，不由 LLM 管理模块生成；结果必须标记 generation_path=deterministic_fallback 并重新通过业务输出校验。

8.12 LLMGenerationResult

字段 类型 规则
request_id string 原样返回生成请求标识
trace_id string/null 关联调用链
status success/failed/blocked 固定状态
generated_content TResult/null 只包含通过结构和业务校验的内容
generation_path primary_model/fallback_model/none 失败和拦截时为 none
provider_name string/null 成功时非空
model_name string/null 成功时非空
prompt_version string 实际 Prompt 版本
attempts LLMAttemptDTO[] 只记录真实调用和格式修复
skipped_models SkippedModelDTO[] 记录被筛掉的模型和原因
error AgentErrorDTO/null 失败和拦截时非空

LLMAttemptDTO 包含：

字段 类型 规则
attempt_no 大于等于 1 的整数 从 1 连续递增
provider_name string 实际调用供应商
model_name string 实际调用模型
status accepted/failed/blocked 接受时不得有原因码；失败或拦截时必须有
reason_code string/null 安全原因码
is_format_repair boolean 标识是否为唯一格式修复调用
duration_ms 大于等于 0 的整数 调用耗时

SkippedModelDTO 只包含 provider_name、model_name 和安全 reason_code。

组合约束：

  • success：内容非空、错误为空、最终模型非空、最后一次尝试为 accepted。
  • failed/blocked：内容为空、错误非空、generation_path=none，不得出现已接受尝试。
  • blocked 必须对应 CONTENT_BLOCKED。
  • attempt_no 从 1 连续递增；跳过的模型不进入 attempts。
  • ProviderResponse.request_id 不匹配时按 UNEXPECTED_PROVIDER_RESPONSE 丢弃，不解析其内容。

8.13 内部尝试记录与敏感信息

每次实际调用记录连续尝试号、供应商、模型、耗时、状态、原因码和是否为格式修复。跳过模型只记录安全原因，不计为真实尝试。

业务响应、错误对象和运行摘要不得包含：

  • 供应商原始异常。
  • 密钥或凭证内容。
  • Prompt 全文。
  • 模型原始半成品。
  • SDK 响应体。
  • 内部调用栈。

9. 交付内容

  1. 公共调用信封、五类输入、五类结果和统一响应的 Pydantic 模型。
  2. SubAgentDispatcher 及五个唯一 Handler 的路由表。
  3. 五个业务函数、输入校验器和输出校验器。
  4. LLM 路由、Prompt 注册、Provider Adapter、上下文预算和故障转移状态机。
  5. ErrorReasonPolicyRegistry 与统一错误构造逻辑。
  6. 从公共 Pydantic 模型生成的 TimeFlow_MVP_SubAgentContract.schema.json。
  7. 使用母 AI Stub、LLM Stub 和 Provider Stub 的独立契约测试。

9.1 对外业务函数

子 Agent 能力层没有前端直连接口。五个业务函数均不写入数据：

函数 输入 返回 成功确认 全部模型失败
generate_item_content AgentCallContext + ScheduleTodoAgentInput AgentResponse[ItemContentCandidate] 是 最小字段合法时确定性降级，否则错误
normalize_feedback AgentCallContext + FeedbackAgentInput AgentResponse[FeedbackContentCandidate] 是 错误，不降级
split_long_goal AgentCallContext + LongTaskSplitAgentInput AgentResponse[LongGoalPlanCandidate] 有候选时 错误，不降级
generate_replan_content AgentCallContext + ReplanAgentInput AgentResponse[ReplanContentProposal] 有建议时 错误，不降级
generate_review AgentCallContext + ReviewAgentInput AgentResponse[ReviewResultDTO] 否，直接展示 事实合法时确定性模板，否则错误

函数签名：

async def generate_item_content(
    context: AgentCallContext,
    input_data: ScheduleTodoAgentInput,
) -> AgentResponse[ItemContentCandidate]: ...

async def normalize_feedback(
    context: AgentCallContext,
    input_data: FeedbackAgentInput,
) -> AgentResponse[FeedbackContentCandidate]: ...

async def split_long_goal(
    context: AgentCallContext,
    input_data: LongTaskSplitAgentInput,
) -> AgentResponse[LongGoalPlanCandidate]: ...

async def generate_replan_content(
    context: AgentCallContext,
    input_data: ReplanAgentInput,
) -> AgentResponse[ReplanContentProposal]: ...

async def generate_review(
    context: AgentCallContext,
    input_data: ReviewAgentInput,
) -> AgentResponse[ReviewResultDTO]: ...

9.2 依赖端口

调用模块 依赖端口 函数 用途 缺失时处理
五个子 Agent LLMManagerPort generate_with_fallback 统一生成、修复、切换和输出校验 日程待办/复盘评估降级，其他返回错误
LLM 管理模块 LLMRouteRegistryPort get_route 获取主备模型、时限和能力配置 CONFIG_ERROR/NO_COMPATIBLE_MODEL
LLM 管理模块 PromptRegistryPort get_prompt 加载固定版本 Prompt CONFIG_ERROR，不得借用其他 Agent Prompt
LLM 管理模块 LLMProviderPort generate 供应商无关的单次模型调用 归一化错误后切换或停止
LLM 管理模块 OutputValidator validate 当前 Agent 的确定性业务校验 按四态结果调度
公共包装层 ErrorReasonPolicyRegistryPort build_error 统一构造错误 未登记原因映射为 INTERNAL_ERROR
五个子 Agent 系统日志端口 record_agent_run_summary 记录状态、Prompt 版本、耗时和错误码 日志失败不阻塞业务结果

上游调用方、Repository、数据库客户端和其他子 Agent 不得成为子 Agent 的直接依赖。

9.3 内部函数

函数 输入 输出 失败行为
dispatch 调用信封和业务输入 唯一目标函数响应 不匹配时 CONTRACT_MISMATCH
validate_call_context AgentCallContext 已验证信封 路由或截止时间非法时停止
validate_agent_input XxxAgentInput 已验证输入 缺字段、事实、时间或引用非法时停止
build_prompt_request Prompt 引用、输入、输出模型、校验器、截止时间、取消端口 LLMGenerationRequest 缺配置时 CONFIG_ERROR
select_model_route 路由、Prompt、输出模型 候选模型与预算 无兼容模型时结构化失败
trim_context_to_budget 完整输入与模型真实窗口 裁剪后输入 必需内容超限时 CONTEXT_TOO_LARGE
invoke_provider ProviderRequest 响应或归一化失败 按故障作用域切换或停止
classify_model_failure 安全供应商错误与尝试状态 切换决策 未分类异常映射 INTERNAL_ERROR
repair_output_once 原始内容、相同输入和 Schema 修复内容或失败 整个请求最多一次
generate_with_fallback LLMGenerationRequest LLMGenerationResult 严格按状态机，不拼接半成品
parse_generated_content 模型内容与输出模型 类型化候选 解析或 Schema 错误进入一次修复
OutputValidator.validate 当前输入与候选 四态决定 接受、切换、停止或拦截
apply_terminal_fallback 已验证输入与统一模型失败 安全降级或错误 只允许日程待办和复盘
build_agent_response 成功结果或错误 AgentResponse[T] 包装组合非法时 CONTRACT_MISMATCH

9.4 数据映射闭环

接口 能力层输出 上游私有数据 能力层终点
generate_item_content 四类事项内容候选 操作类型、真实目标 ID、版本、用户归属 合法候选或结构化错误
normalize_feedback 临时引用、原始/规范化反馈、状态和时间 target_ref → item_id + version 合法反馈候选或结构化错误
split_long_goal 宏观规划和近期子任务内容 真实 long_goal_id 规划候选或结构化错误
generate_replan_content 临时引用和内容级建议 item_ref → item_id + version + snapshot 重排候选或结构化错误
generate_review ReviewResultDTO.review_text 数据读取来源与后续报告存储 展示文本或结构化错误
LLM 管理 类型化有效内容或统一错误 模型配置与受控运行日志 返回发起调用的当前子 Agent

闭环成立条件：

  1. 每个入口只有一个 Handler。
  2. 每个失败阶段都有结构化出口。
  3. 每个成功结果都通过类型校验和当前 Agent 业务校验。
  4. 任何模型半成品都不会越过 LLM 管理模块。
  5. 职责在返回 AgentResponse[T] 时终止。

10. 风险与依赖

风险 级别 预防措施 验证方式
模型输出未知或跨请求临时引用 P0 校验器只接受当前请求输入中的引用 构造未知、重复和跨请求引用，必须拒绝
模型输出 CRUD 指令或真实 ID P0 Schema 和业务校验拒绝禁止字段；db_action=null 对抗输出必须返回 OUTPUT_INVALID
反馈目标、原文或时间被篡改 P0 三个字段必须与输入一致，时间必须在范围内 越界、篡改引用和改写原文测试
拆分缺少唯一长期目标语境 P0 long_goal 必填，子 Agent 不查询或猜测 缺少目标时在模型调用前失败
重排调整固定事项 P0 固定引用必须属于输入，输出校验器禁止调整 固定事项调整用例必须失败
备用模型改变结构或风格 P1 主备模型复用同一 Prompt、输入、Schema 和风格 主备模型契约结果一致
复盘虚构数字或事实 P1 数字只来自指标，事实只来自输入 DTO 注入冲突数字和空数据测试
重试或格式修复形成循环 P0 1–2 个备用模型、最多一次修复、统一次数与时限 持续格式错误到达上限后立即停止
鉴权错误在同一凭证重复尝试 P1 凭证级故障跳过相同 credential_ref 同凭证多模型与跨供应商路由测试
上下文裁剪删除关键事实 P0 只删最早对话和可选空字段 比较裁剪前后所有必需字段
取消后迟到结果被展示 P0 关闭请求接收状态并校验请求标识 模拟取消和慢模型返回
降级误用于反馈、拆分或重排 P0 响应模型限制仅日程待办和复盘可降级 三个禁止 Agent 的构造测试
事项降级补造字段 P0 只复制明确输入并重新校验 缺标题、缺时间和冲突输入测试
复盘模板推断原因或新增数字 P0 模板只引用覆盖、指标和事实 空反馈、冲突指标和注入数字测试
错误响应泄露敏感信息 P0 对外只返回安全错误字段 注入模型、Prompt、密钥和异常文本
Dispatcher 因类型错误调用错误 Agent P0 固定路由表同时校验 Agent、函数和输入类型 交叉组合五种输入，Handler 调用次数为 0
先裁剪再选模型导致按错误窗口丢字段 P0 先筛选候选模型，再按真实窗口预算 不同窗口主备模型的顺序与字段保留测试
供应商 SDK 异常穿透 P0 Adapter 只抛归一化安全错误 注入 SDK 异常、响应体和密钥片段
业务校验器未执行或决定未驱动状态机 P0 解析后必须调用随请求注入的校验器 四态 Stub 分别验证四条路径
正文、接口表和类型错误码漂移 P1 公共码统一引用枚举，差异使用 reason_code 文档静态检索与契约枚举一致
高级模型治理拖慢 MVP P1 固定主备顺序为基线，健康探测与熔断后置 分阶段验收，不作为当前阻塞项
上游事实或目标不完整 P0 母 AI 先补齐并唯一定位 缺失或冲突输入在模型调用前失败

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions