fix(api): document message responses as serialized contracts

2026-06-26 14:51:13 +08:00 · 2026-06-26 03:24:28 +09:00 · 2026-06-26 03:24:28 +09:00 · ffe3a5729e
commit ffe3a5729e
parent df4617d53b
9 changed files with 43 additions and 26 deletions
--- a/api/controllers/console/app/message.py
+++ b/api/controllers/console/app/message.py
@ -167,12 +167,16 @@ register_schema_models(
    ChatMessagesQuery,
    MessageFeedbackPayload,
    FeedbackExportQuery,
+)
+register_response_schema_models(
+    console_ns,
    AnnotationCountResponse,
    SuggestedQuestionsResponse,
    MessageDetailResponse,
    MessageInfiniteScrollPaginationResponse,
+    SimpleResultResponse,
+    TextFileResponse,
 )
-register_response_schema_models(console_ns, SimpleResultResponse, TextFileResponse)


@console_ns.route("/apps/<uuid:app_id>/chat-messages")
--- a/api/core/rag/extractor/extract_processor.py
+++ b/api/core/rag/extractor/extract_processor.py
@ -1,7 +1,7 @@
 import re
 import tempfile
 from pathlib import Path
-from typing import Union
+from typing import Literal, overload
 from urllib.parse import unquote

 from configs import dify_config
@ -40,10 +40,22 @@ USER_AGENT = (


 class ExtractProcessor:
+    @overload
+    @classmethod
+    def load_from_upload_file(
+        cls, upload_file: UploadFile, return_text: Literal[True], is_automatic: bool = False
+    ) -> str: ...
+
+    @overload
+    @classmethod
+    def load_from_upload_file(
+        cls, upload_file: UploadFile, return_text: Literal[False] = False, is_automatic: bool = False
+    ) -> list[Document]: ...
+
    @classmethod
    def load_from_upload_file(
        cls, upload_file: UploadFile, return_text: bool = False, is_automatic: bool = False
-    ) -> Union[list[Document], str]:
+    ) -> list[Document] | str:
        extract_setting = ExtractSetting(
            datasource_type=DatasourceType.FILE, upload_file=upload_file, document_model="text_model"
        )
@ -53,8 +65,16 @@ class ExtractProcessor:
        else:
            return cls.extract(extract_setting, is_automatic)

+    @overload
    @classmethod
-    def load_from_url(cls, url: str, return_text: bool = False) -> Union[list[Document], str]:
+    def load_from_url(cls, url: str, return_text: Literal[True]) -> str: ...
+
+    @overload
+    @classmethod
+    def load_from_url(cls, url: str, return_text: Literal[False] = False) -> list[Document]: ...
+
+    @classmethod
+    def load_from_url(cls, url: str, return_text: bool = False) -> list[Document] | str:
        response = remote_fetcher.make_request("GET", url, headers={"User-Agent": USER_AGENT})

        with tempfile.TemporaryDirectory() as temp_dir:
--- a/api/openapi/markdown/console-openapi.md
+++ b/api/openapi/markdown/console-openapi.md
@ -13429,7 +13429,6 @@ Soft lifecycle state for Agent records.
 | created_at | integer |  | No |
 | files | [ string ] |  | Yes |
 | id | string |  | Yes |
-| message_chain_id | string |  | No |
 | message_id | string |  | Yes |
 | observation | string |  | No |
 | position | integer |  | Yes |
@ -14540,8 +14539,8 @@ Enum class for configurate method of provider model.
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
 | annotation_create_account | [SimpleAccount](#simpleaccount) |  | No |
+| annotation_id | string |  | Yes |
 | created_at | integer |  | No |
-| id | string |  | Yes |

 #### ConversationDetail

@ -17079,6 +17078,7 @@ Enum class for large language model mode.
 | agent_thoughts | [ [AgentThought](#agentthought) ] |  | No |
 | annotation | [ConversationAnnotation](#conversationannotation) |  | No |
 | annotation_hit_history | [ConversationAnnotationHitHistory](#conversationannotationhithistory) |  | No |
+| answer | string |  | Yes |
 | answer_tokens | integer |  | No |
 | conversation_id | string |  | Yes |
 | created_at | integer |  | No |
@ -17092,12 +17092,11 @@ Enum class for large language model mode.
 | inputs | object |  | Yes |
 | message | [JSONValue](#jsonvalue) |  | No |
 | message_files | [ [MessageFile](#messagefile) ] |  | No |
-| message_metadata_dict | [JSONValue](#jsonvalue) |  | No |
 | message_tokens | integer |  | No |
+| metadata | [JSONValue](#jsonvalue) |  | No |
 | parent_message_id | string |  | No |
 | provider_response_latency | number |  | No |
 | query | string |  | Yes |
-| re_sign_file_url_answer | string |  | Yes |
 | status | string |  | Yes |
 | workflow_run_id | string |  | No |

--- a/packages/contracts/generated/api/console/agent/types.gen.ts
+++ b/packages/contracts/generated/api/console/agent/types.gen.ts
@ -269,6 +269,7 @@ export type MessageDetailResponse = {
  agent_thoughts?: Array<AgentThought>
  annotation?: ConversationAnnotation | null
  annotation_hit_history?: ConversationAnnotationHitHistory | null
+  answer: string
  answer_tokens?: number | null
  conversation_id: string
  created_at?: number | null
@ -284,12 +285,11 @@ export type MessageDetailResponse = {
  }
  message?: JsonValue | null
  message_files?: Array<MessageFile>
-  message_metadata_dict?: JsonValue | null
  message_tokens?: number | null
+  metadata?: JsonValue | null
  parent_message_id?: string | null
  provider_response_latency?: number | null
  query: string
-  re_sign_file_url_answer: string
  status: string
  workflow_run_id?: string | null
 }
@ -723,7 +723,6 @@ export type AgentThought = {
  created_at?: number | null
  files: Array<string>
  id: string
-  message_chain_id?: string | null
  message_id: string
  observation?: string | null
  position: number
@ -743,8 +742,8 @@ export type ConversationAnnotation = {

 export type ConversationAnnotationHitHistory = {
  annotation_create_account?: SimpleAccount | null
+  annotation_id: string
  created_at?: number | null
-  id: string
 }

 export type HumanInputContent = {
--- a/packages/contracts/generated/api/console/agent/zod.gen.ts
+++ b/packages/contracts/generated/api/console/agent/zod.gen.ts
@ -570,7 +570,6 @@ export const zAgentThought = z.object({
  created_at: z.int().nullish(),
  files: z.array(z.string()),
  id: z.string(),
-  message_chain_id: z.string().nullish(),
  message_id: z.string(),
  observation: z.string().nullish(),
  position: z.int(),
@ -1056,8 +1055,8 @@ export const zConversationAnnotation = z.object({
 */
 export const zConversationAnnotationHitHistory = z.object({
  annotation_create_account: zSimpleAccount.nullish(),
+  annotation_id: z.string(),
  created_at: z.int().nullish(),
-  id: z.string(),
 })

 /**
@ -2035,6 +2034,7 @@ export const zMessageDetailResponse = z.object({
  agent_thoughts: z.array(zAgentThought).optional(),
  annotation: zConversationAnnotation.nullish(),
  annotation_hit_history: zConversationAnnotationHitHistory.nullish(),
+  answer: z.string(),
  answer_tokens: z.int().nullish(),
  conversation_id: z.string(),
  created_at: z.int().nullish(),
@ -2048,12 +2048,11 @@ export const zMessageDetailResponse = z.object({
  inputs: z.record(z.string(), zJsonValue),
  message: zJsonValue.nullish(),
  message_files: z.array(zMessageFile).optional(),
-  message_metadata_dict: zJsonValue.nullish(),
  message_tokens: z.int().nullish(),
+  metadata: zJsonValue.nullish(),
  parent_message_id: z.string().nullish(),
  provider_response_latency: z.number().nullish(),
  query: z.string(),
-  re_sign_file_url_answer: z.string(),
  status: z.string(),
  workflow_run_id: z.string().nullish(),
 })
--- a/packages/contracts/generated/api/console/apps/types.gen.ts
+++ b/packages/contracts/generated/api/console/apps/types.gen.ts
@ -472,6 +472,7 @@ export type MessageDetailResponse = {
  agent_thoughts?: Array<AgentThought>
  annotation?: ConversationAnnotation | null
  annotation_hit_history?: ConversationAnnotationHitHistory | null
+  answer: string
  answer_tokens?: number | null
  conversation_id: string
  created_at?: number | null
@ -487,12 +488,11 @@ export type MessageDetailResponse = {
  }
  message?: JsonValue | null
  message_files?: Array<MessageFile>
-  message_metadata_dict?: JsonValue | null
  message_tokens?: number | null
+  metadata?: JsonValue | null
  parent_message_id?: string | null
  provider_response_latency?: number | null
  query: string
-  re_sign_file_url_answer: string
  status: string
  workflow_run_id?: string | null
 }
@ -1498,7 +1498,6 @@ export type AgentThought = {
  created_at?: number | null
  files: Array<string>
  id: string
-  message_chain_id?: string | null
  message_id: string
  observation?: string | null
  position: number
@ -1518,8 +1517,8 @@ export type ConversationAnnotation = {

 export type ConversationAnnotationHitHistory = {
  annotation_create_account?: SimpleAccount | null
+  annotation_id: string
  created_at?: number | null
-  id: string
 }

 export type HumanInputContent = {
--- a/packages/contracts/generated/api/console/apps/zod.gen.ts
+++ b/packages/contracts/generated/api/console/apps/zod.gen.ts
@ -1150,7 +1150,6 @@ export const zAgentThought = z.object({
  created_at: z.int().nullish(),
  files: z.array(z.string()),
  id: z.string(),
-  message_chain_id: z.string().nullish(),
  message_id: z.string(),
  observation: z.string().nullish(),
  position: z.int(),
@ -1371,8 +1370,8 @@ export const zConversationAnnotation = z.object({
 */
 export const zConversationAnnotationHitHistory = z.object({
  annotation_create_account: zSimpleAccount.nullish(),
+  annotation_id: z.string(),
  created_at: z.int().nullish(),
-  id: z.string(),
 })

 /**
@ -3455,6 +3454,7 @@ export const zMessageDetailResponse = z.object({
  agent_thoughts: z.array(zAgentThought).optional(),
  annotation: zConversationAnnotation.nullish(),
  annotation_hit_history: zConversationAnnotationHitHistory.nullish(),
+  answer: z.string(),
  answer_tokens: z.int().nullish(),
  conversation_id: z.string(),
  created_at: z.int().nullish(),
@ -3468,12 +3468,11 @@ export const zMessageDetailResponse = z.object({
  inputs: z.record(z.string(), zJsonValue),
  message: zJsonValue.nullish(),
  message_files: z.array(zMessageFile).optional(),
-  message_metadata_dict: zJsonValue.nullish(),
  message_tokens: z.int().nullish(),
+  metadata: zJsonValue.nullish(),
  parent_message_id: z.string().nullish(),
  provider_response_latency: z.number().nullish(),
  query: z.string(),
-  re_sign_file_url_answer: z.string(),
  status: z.string(),
  workflow_run_id: z.string().nullish(),
 })
--- a/packages/contracts/generated/api/console/installed-apps/types.gen.ts
+++ b/packages/contracts/generated/api/console/installed-apps/types.gen.ts
@ -246,7 +246,6 @@ export type AgentThought = {
  created_at?: number | null
  files: Array<string>
  id: string
-  message_chain_id?: string | null
  message_id: string
  observation?: string | null
  position: number
--- a/packages/contracts/generated/api/console/installed-apps/zod.gen.ts
+++ b/packages/contracts/generated/api/console/installed-apps/zod.gen.ts
@ -266,7 +266,6 @@ export const zAgentThought = z.object({
  created_at: z.int().nullish(),
  files: z.array(z.string()),
  id: z.string(),
-  message_chain_id: z.string().nullish(),
  message_id: z.string(),
  observation: z.string().nullish(),
  position: z.int(),