From b5d47e6a5951fef45658b403338d90bfa0fde0e1 Mon Sep 17 00:00:00 2001
From: qiaofenlin <790872612@qq.com>
Date: Tue, 22 Jul 2025 14:18:41 +0800
Subject: [PATCH] docs: add and unify trace_id field docs for chat/workflow
 APIs (zh/en/ja)

---
 .../develop/template/template_advanced_chat.en.mdx         | 6 ++++++
 .../develop/template/template_advanced_chat.ja.mdx         | 6 ++++++
 .../develop/template/template_advanced_chat.zh.mdx         | 6 ++++++
 web/app/components/develop/template/template_chat.en.mdx   | 6 ++++++
 web/app/components/develop/template/template_chat.ja.mdx   | 6 ++++++
 web/app/components/develop/template/template_chat.zh.mdx   | 6 ++++++
 .../components/develop/template/template_workflow.en.mdx   | 6 ++++++
 .../components/develop/template/template_workflow.ja.mdx   | 5 +++++
 .../components/develop/template/template_workflow.zh.mdx   | 7 ++++++-
 9 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/web/app/components/develop/template/template_advanced_chat.en.mdx b/web/app/components/develop/template/template_advanced_chat.en.mdx
index faecd3d1cd..1fb167bb9b 100644
--- a/web/app/components/develop/template/template_advanced_chat.en.mdx
+++ b/web/app/components/develop/template/template_advanced_chat.en.mdx
@@ -80,6 +80,12 @@ Chat applications support session persistence, allowing previous chat history to
       Auto-generate title, default is `true`.
       If set to `false`, can achieve async title generation by calling the conversation rename API and setting `auto_generate` to `true`.
       </Property>
+      <Property name='trace_id' type='string' key='trace_id'>
+        (Optional) Trace ID. Used for integration with existing business trace components to achieve end-to-end distributed tracing. If not provided, the system will automatically generate a trace_id. Supports the following three ways to pass, in order of priority:<br/>
+        - Header: via HTTP Header <code>X-Trace-Id</code>, highest priority.<br/>
+        - Query parameter: via URL query parameter <code>trace_id</code>.<br/>
+        - Request Body: via request body field <code>trace_id</code> (i.e., this field).<br/>
+      </Property>
     </Properties>
 
     ### Response
diff --git a/web/app/components/develop/template/template_advanced_chat.ja.mdx b/web/app/components/develop/template/template_advanced_chat.ja.mdx
index 5ce54a61d2..cdbe1a5dc8 100644
--- a/web/app/components/develop/template/template_advanced_chat.ja.mdx
+++ b/web/app/components/develop/template/template_advanced_chat.ja.mdx
@@ -80,6 +80,12 @@ import { Row, Col, Properties, Property, Heading, SubProperty, Paragraph } from
       タイトルを自動生成、デフォルトは`true`。
       `false`に設定すると、会話のリネームAPIを呼び出し、`auto_generate`を`true`に設定することで非同期タイトル生成を実現できます。
       </Property>
+      <Property name='trace_id' type='string' key='trace_id'>
+        （オプション）トレースID。既存の業務システムのトレースコンポーネントと連携し、エンドツーエンドの分散トレーシングを実現するために使用します。指定がない場合、システムが自動的に trace_id を生成します。以下の3つの方法で渡すことができ、優先順位は次のとおりです：<br/>
+        - Header：HTTPヘッダー <code>X-Trace-Id</code> で渡す（最優先）。<br/>
+        - クエリパラメータ：URLクエリパラメータ <code>trace_id</code> で渡す。<br/>
+        - リクエストボディ：リクエストボディの <code>trace_id</code> フィールドで渡す（本フィールド）。<br/>
+      </Property>
     </Properties>
 
     ### 応答
diff --git a/web/app/components/develop/template/template_advanced_chat.zh.mdx b/web/app/components/develop/template/template_advanced_chat.zh.mdx
index 7a69ee60aa..cb33416d78 100755
--- a/web/app/components/develop/template/template_advanced_chat.zh.mdx
+++ b/web/app/components/develop/template/template_advanced_chat.zh.mdx
@@ -78,6 +78,12 @@ import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx'
       <Property name='auto_generate_name' type='bool' key='auto_generate_name'>
       （选填）自动生成标题，默认 `true`。 若设置为 `false`，则可通过调用会话重命名接口并设置 `auto_generate` 为 `true` 实现异步生成标题。
       </Property>
+      <Property name='trace_id' type='string' key='trace_id'>
+      （选填）链路追踪ID。适用于与业务系统已有的trace组件打通，实现端到端分布式追踪等场景。如果未指定，系统会自动生成<code>trace_id</code>。支持以下三种方式传递，具体优先级依次为：<br/>
+        - Header：通过 HTTP Header <code>X-Trace-Id</code> 传递，优先级最高。<br/>
+        - Query 参数：通过 URL 查询参数 <code>trace_id</code> 传递。<br/>
+        - Request Body：通过请求体字段 <code>trace_id</code> 传递（即本字段）。<br/>
+      </Property>
     </Properties>
 
     ### Response
diff --git a/web/app/components/develop/template/template_chat.en.mdx b/web/app/components/develop/template/template_chat.en.mdx
index c95471160e..81620cee06 100644
--- a/web/app/components/develop/template/template_chat.en.mdx
+++ b/web/app/components/develop/template/template_chat.en.mdx
@@ -74,6 +74,12 @@ Chat applications support session persistence, allowing previous chat history to
       Auto-generate title, default is `true`.
       If set to `false`, can achieve async title generation by calling the conversation rename API and setting `auto_generate` to `true`.
       </Property>
+      <Property name='trace_id' type='string' key='trace_id'>
+        (Optional) Trace ID. Used for integration with existing business trace components to achieve end-to-end distributed tracing. If not provided, the system will automatically generate a trace_id. Supports the following three ways to pass, in order of priority:<br/>
+        - Header: via HTTP Header <code>X-Trace-Id</code>, highest priority.<br/>
+        - Query parameter: via URL query parameter <code>trace_id</code>.<br/>
+        - Request Body: via request body field <code>trace_id</code> (i.e., this field).<br/>
+      </Property>
     </Properties>
 
     ### Response
diff --git a/web/app/components/develop/template/template_chat.ja.mdx b/web/app/components/develop/template/template_chat.ja.mdx
index 8368326e40..3287d68005 100644
--- a/web/app/components/develop/template/template_chat.ja.mdx
+++ b/web/app/components/develop/template/template_chat.ja.mdx
@@ -74,6 +74,12 @@ import { Row, Col, Properties, Property, Heading, SubProperty, Paragraph } from
       タイトルを自動生成します。デフォルトは`true`です。
       `false`に設定すると、会話のリネームAPIを呼び出し、`auto_generate`を`true`に設定することで非同期タイトル生成を実現できます。
       </Property>
+      <Property name='trace_id' type='string' key='trace_id'>
+        （オプション）トレースID。既存の業務システムのトレースコンポーネントと連携し、エンドツーエンドの分散トレーシングを実現するために使用します。指定がない場合、システムが自動的に trace_id を生成します。以下の3つの方法で渡すことができ、優先順位は次のとおりです：<br/>
+        - Header：HTTPヘッダー <code>X-Trace-Id</code> で渡す（最優先）。<br/>
+        - クエリパラメータ：URLクエリパラメータ <code>trace_id</code> で渡す。<br/>
+        - リクエストボディ：リクエストボディの <code>trace_id</code> フィールドで渡す（本フィールド）。<br/>
+      </Property>
     </Properties>
 
     ### 応答
diff --git a/web/app/components/develop/template/template_chat.zh.mdx b/web/app/components/develop/template/template_chat.zh.mdx
index 325470ac62..1926adc1ce 100644
--- a/web/app/components/develop/template/template_chat.zh.mdx
+++ b/web/app/components/develop/template/template_chat.zh.mdx
@@ -73,6 +73,12 @@ import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx'
       <Property name='auto_generate_name' type='bool' key='auto_generate_name'>
       （选填）自动生成标题，默认 `true`。 若设置为 `false`，则可通过调用会话重命名接口并设置 `auto_generate` 为 `true` 实现异步生成标题。
       </Property>
+      <Property name='trace_id' type='string' key='trace_id'>
+       （选填）链路追踪ID。适用于与业务系统已有的trace组件打通，实现端到端分布式追踪等场景。如果未指定，系统会自动生成<code>trace_id</code>。支持以下三种方式传递，具体优先级依次为：<br/>
+          - Header：通过 HTTP Header <code>X-Trace-Id</code> 传递，优先级最高。<br/>
+          - Query 参数：通过 URL 查询参数 <code>trace_id</code> 传递。<br/>
+          - Request Body：通过请求体字段 <code>trace_id</code> 传递（即本字段）。<br/>
+      </Property>
     </Properties>
 
     ### Response
diff --git a/web/app/components/develop/template/template_workflow.en.mdx b/web/app/components/develop/template/template_workflow.en.mdx
index 77409c1284..7909c3e081 100644
--- a/web/app/components/develop/template/template_workflow.en.mdx
+++ b/web/app/components/develop/template/template_workflow.en.mdx
@@ -66,6 +66,12 @@ Workflow applications offers non-session support and is ideal for translation, a
         Should be uniquely defined by the developer within the application.
         <br/>
         <i>The user identifier should be consistent with the user passed in the message sending interface. The Service API does not share conversations created by the WebApp.</i>
+      - `files` (array[object]) Optional
+      - `trace_id` (string) Optional
+        Trace ID. Used for integration with existing business trace components to achieve end-to-end distributed tracing. If not provided, the system will automatically generate a trace_id. Supports the following three ways to pass, in order of priority:
+        1. Header: via HTTP Header `X-Trace-Id`, highest priority.
+        2. Query parameter: via URL query parameter `trace_id`.
+        3. Request Body: via request body field `trace_id` (i.e., this field).
 
     ### Response
     When `response_mode` is `blocking`, return a CompletionResponse object.
diff --git a/web/app/components/develop/template/template_workflow.ja.mdx b/web/app/components/develop/template/template_workflow.ja.mdx
index a83e21aef7..4231d83eb2 100644
--- a/web/app/components/develop/template/template_workflow.ja.mdx
+++ b/web/app/components/develop/template/template_workflow.ja.mdx
@@ -66,6 +66,11 @@ import { Row, Col, Properties, Property, Heading, SubProperty, Paragraph } from
         ユーザー識別子、エンドユーザーのアイデンティティを定義するために使用されます。
         アプリケーション内で開発者によって一意に定義される必要があります。
       - `files` (array[object]) オプション
+      - `trace_id` (string) オプション
+        トレースID。既存の業務システムのトレースコンポーネントと連携し、エンドツーエンドの分散トレーシングを実現するために使用します。指定がない場合、システムが自動的に trace_id を生成します。以下の3つの方法で渡すことができ、優先順位は次のとおりです：
+        1. Header：HTTPヘッダー `X-Trace-Id` で渡す（最優先）。
+        2. クエリパラメータ：URLクエリパラメータ `trace_id` で渡す。
+        3. リクエストボディ：リクエストボディの `trace_id` フィールドで渡す（本フィールド）。
         
 
     ### 応答
diff --git a/web/app/components/develop/template/template_workflow.zh.mdx b/web/app/components/develop/template/template_workflow.zh.mdx
index fc193de5da..dceefa48c3 100644
--- a/web/app/components/develop/template/template_workflow.zh.mdx
+++ b/web/app/components/develop/template/template_workflow.zh.mdx
@@ -60,7 +60,12 @@ Workflow 应用无会话支持，适合用于翻译/文章写作/总结 AI 等
       - `user` (string) Required
         用户标识，用于定义终端用户的身份，方便检索、统计。
         由开发者定义规则，需保证用户标识在应用内唯一。API 无法访问 WebApp 创建的会话。
-
+      - `files` (array[object]) 可选
+      - `trace_id` (string) Optional
+        链路追踪ID。适用于与业务系统已有的trace组件打通，实现端到端分布式追踪等场景。如果未指定，系统将自动生成 `trace_id`。支持以下三种方式传递，具体优先级依次为：
+        1. Header：推荐通过 HTTP Header `X-Trace-Id` 传递，优先级最高。
+        2. Query 参数：通过 URL 查询参数 `trace_id` 传递。
+        3. Request Body：通过请求体字段 `trace_id` 传递（即本字段）。
 
     ### Response
     当 `response_mode` 为 `blocking` 时，返回 CompletionResponse object。