实现 M002 V3 入站解析与路由基线
This commit is contained in:
andy
@@ -8,18 +8,20 @@
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档版本 | 0.3 |
|
||||
| 日期 | 2026-07-10 |
|
||||
| 状态 | 后端接口契约草稿 |
|
||||
| 文档版本 | 0.5 |
|
||||
| 日期 | 2026-07-11 |
|
||||
| 状态 | V2 兼容 + M002 V3 CP1-CP2 入站解析基线；完整 V3 展示和同卡复核仍看 `M002-order-task-workflow-v3.md` 后续 checkpoint |
|
||||
| 适用范围 | SuperAgent / Main Agent 调用本系统提交 AI 任务结果 |
|
||||
| 主要读者 | 后端、SuperAgent 对接方、测试、后续协作 agent |
|
||||
|
||||
## 1. 文档定位
|
||||
|
||||
本文定义 SuperAgent / Main Agent 向本系统提交 `ai_task_results[]` 结构化结果，以及提交 S000/S999 特殊入口结果的后端接口契约。
|
||||
本文定义 SuperAgent / Main Agent 向本系统提交 V3 `source_message + message_events[]` 业务根、结构化 S10/S99 入口通知、V2 `ai_task_results[]` 兼容结果，以及旧 S000/S999 特殊入口结果的后端接口契约。
|
||||
|
||||
本文承接 `M002-order-task-workflow-v2.md`，只定义本系统入站接口、鉴权、幂等、请求响应和技术校验边界，不定义 SuperAgent 内部 prompt、Skill 实现、OPERA 真实接口或前端展示细节。
|
||||
|
||||
2026-07-11 后，M002 后续开发基线已迁移到 `M002-order-task-workflow-v3.md`。当前后端已完成 CP1-CP2：结构化 `S10/S99` 入站、V3 业务根基础解析、42 路由枚举 / 稳定配置、`UNHANDLED_CURRENT_INTENT` 和 route 相关字段最小落库。旧 `S000/S999` 和 `ai_task_results[]` 仍作为兼容路径保留。对外联调以 `docs/project/integrations/superagent-api-contract.md` 为准。完整 type-known manual review 解阻、`missing_fields[]` 到任务卡字段白名单映射和 typed `infrastructure_input_error` 响应仍在后续 checkpoint。
|
||||
|
||||
## 2. 接口概览
|
||||
|
||||
| 项目 | 内容 |
|
||||
@@ -29,7 +31,7 @@
|
||||
| Content-Type | `application/json` 或 `text/plain` |
|
||||
| 响应格式 | `application/json` |
|
||||
| 一次请求范围 | 只能包含一个 `source_message_id` |
|
||||
| 业务动作 | 接收 AI 结果或入口结果、写入 AI 过渡层、生成订单 / 任务 / 任务卡 |
|
||||
| 业务动作 | 接收 AI 结果或入口结果、写入 AI 过渡层，按可支持路由生成订单 / 任务 / 任务卡 |
|
||||
| 鉴权方式 | HMAC-SHA256 签名 |
|
||||
|
||||
中文说明：
|
||||
@@ -37,8 +39,8 @@
|
||||
- 该接口是服务到服务的入站接口，不给前端直接调用。
|
||||
- SuperAgent 不直连数据库，只能通过本接口提交任务结果或入口处理结果。
|
||||
- 本接口只做技术校验和系统接收，不替代用户确认和 OPERA 模拟操作。
|
||||
- `application/json` 用于 `normal_task` / `manual_review` 结构化任务。
|
||||
- `text/plain` 用于 `S000,source_message_id` / `S999,source_message_id` 特殊入口结果。
|
||||
- `application/json` 用于 V3 结构化 `S10/S99`、V3 业务根或 V2 `normal_task` / `manual_review` 兼容结构化任务。
|
||||
- `text/plain` 用于旧 `S000,source_message_id` / `S999,source_message_id` 特殊入口结果兼容。
|
||||
|
||||
### 2.1 SourceMessage ID 口径
|
||||
|
||||
@@ -175,7 +177,7 @@ JSON 请求体沿用 AI 导入文档定义的聚合结构。
|
||||
| `ai_task_results[]` | 是 | AI 拆分出的任务结果列表，必须保留数组顺序 |
|
||||
| `extraction_warnings[]` | 否 | 抽取警告；不直接等同于业务任务 |
|
||||
|
||||
第一版要求 `ai_task_results[]` 至少包含一条记录。没有业务动作的纯信息类邮件不要提交空数组，也不要新生成 `informational_message`；应改用 `S000,source_message_id` 文本结果。
|
||||
V2 第一版要求 `ai_task_results[]` 至少包含一条记录。没有业务动作的纯信息类邮件不要提交空数组，也不要新生成 `informational_message`；新数据优先使用 V3 结构化 `S10/S99`，旧联调或兼容场景仍可使用 `S000,source_message_id` 文本结果。
|
||||
|
||||
### 4.3 `ai_task_results[]` 字段
|
||||
|
||||
@@ -184,7 +186,7 @@ JSON 请求体沿用 AI 导入文档定义的聚合结构。
|
||||
| `source_event_index` | 是 | AI current 事件序号，建议从 1 开始 |
|
||||
| `catalog_code` | 是 | Skill 目录代码，例如 S01、S02 |
|
||||
| `skill_id` | 是 | Skill 标识 |
|
||||
| `result_type` | 是 | 新入口只接受 `normal_task`、`manual_review`；`informational_message` 仅历史兼容 |
|
||||
| `result_type` | 是 | V2 当前代码契约只接受 `normal_task`、`manual_review`；`informational_message` 仅历史兼容 |
|
||||
| `task_type` | 是 | AI 原始任务类型 |
|
||||
| `task_subtype` | 否 | 业务动作 subtype；有则用于任务卡路由 |
|
||||
| `current_or_history` | 否 | 当前或历史标识 |
|
||||
|
||||
Reference in New Issue
Block a user