feat: add workflow file context

Author: c121914yu

.agents/design/core/workflow/workflow-file-context.md

@@ -0,0 +1,278 @@
+# Workflow 输入文件上下文统一设计
+
+## 1. 背景
+
+Workflow 输入文件目前以 URL 字符串贯穿 AI Chat、ToolCall、AgentV2、ReadFiles 和
+Sandbox。URL 同时承担模型访问地址、服务端下载地址、文件类型推断和去重标识，导致同源
+绝对 URL、相对下载短链和外部 URL 容易被错误转换。
+
+尤其需要避免以下行为：
+
+- 根据 `requestOrigin`、`FE_DOMAIN` 或 URL 前缀推断文件权限；
+- 将用户输入的相对 URL 交给内部 Axios；
+- 让模型或节点通过新 URL 扩大本轮 Workflow 可读取的文件集合；
+- 使用模型 URL 作为私有对象的服务端读取来源。
+
+本期引入请求级、只读的 `WorkflowFileContext`。它在 `dispatchWorkFlow` 入口统一处理当前
+query 和 histories 已携带的文件，下游消费者只能解析入口已登记的文件。
+
+## 2. 本期范围
+
+### 2.1 包含
+
+- 当前 query 中的文件；
+- histories 中 Human 消息携带的文件；
+- AI Chat、ToolCall、AgentV2、ReadFiles 和 Sandbox 对上述文件的消费；
+- 私有 chat object key 的归属校验；
+- 外部绝对 HTTP(S) URL 的 SSRF 防护读取；
+- 请求级文件数量和单文件大小限制。
+
+### 2.2 不包含
+
+- Workflow 运行期间由普通节点、Plugin、Interactive 或 Dataset Search 新产生的文件；
+- Workflow 文件变量的存储结构迁移；
+- 跨请求持久化 `WorkflowFileRef`；
+- 修改聊天数据库中的现有文件格式；
+- 通过 signed alias 反推业务归属；
+- Context clone、分支注册和合并。
+
+## 3. 核心原则
+
+### 3.1 key 是私有文件的可信来源
+
+私有文件必须携带 `key`。Workflow 入口使用 `parseChatFileS3Key` 或
+`isAuthorizedChatFileS3Key` 校验 key 是否属于根 Workflow：
+
+```text
+key
+  -> sourceType
+  -> sourceId
+  -> uid
+  -> chatId
+  -> 与根 Workflow 鉴权上下文逐项匹配
+```
+
+匹配使用根 `dispatchWorkFlow` 的 `runningAppInfo`、`uid` 和 `chatId`。Child Workflow 不得
+使用 child app 的身份重新解释父 Workflow 输入文件。
+
+归属匹配失败时直接拒绝。不能把失败的私有 key 降级成外部 URL。
+
+### 3.2 signed URL 只用于模型访问
+
+signed URL 不参与权限判断。私有 key 校验通过后，每个 key 在一次 Workflow 中最多签发
+一次两小时有效的绝对 HTTP(S) URL，并在请求内复用。
+
+如果文件域名配置无法生成绝对 HTTP(S) URL，入口应报配置错误，不能生成相对 URL。
+
+### 3.3 服务端读取与模型 URL 分离
+
+- 私有 chat object：FastGPT 服务端通过 S3 client 直接读取；
+- 外部 HTTP(S) URL：FastGPT 服务端通过带 SSRF 防护的 Axios 读取；
+- 模型只接收 `modelUrl`；
+- 相对 URL、protocol-relative URL 和非 HTTP(S) 协议一律不能进入读取链路。
+
+### 3.4 Context 只读
+
+只有 Workflow 入口可以登记文件。节点、模型工具参数和下游消费者只能查询已登记 Ref，
+不能在查询失败时自动注册新外链。
+
+## 4. 数据模型
+
+```ts
+export type WorkflowFileSource =
+  | {
+      type: 'chatObject';
+      objectKey: string;
+    }
+  | {
+      type: 'externalHttp';
+      url: string;
+    };
+
+export type WorkflowFileRef = {
+  id: string;
+  name: string;
+  type: ChatFileTypeEnum;
+  modelUrl: string;
+  source: WorkflowFileSource;
+};
+
+export type WorkflowFileLimits = {
+  maxFiles: number;
+  maxBytesPerFile: number;
+};
+
+export type WorkflowFileContext = {
+  resolve: (urlOrId: string) => WorkflowFileRef | undefined;
+  resolveChatFile: (url: string) => UserChatItemFileItemType | undefined;
+  getIdentity: (urlOrId: string) => string | undefined;
+  read: (target: string | WorkflowFileRef) => Promise<WorkflowFileReadResult>;
+  limits: WorkflowFileLimits;
+};
+```
+
+Context 不暴露 `register`、`clone` 或文件枚举接口。内部至少维护：
+
+- `byId`：服务端生成 file id 到 Ref；
+- `byRuntimeUrl`：本轮 `modelUrl` 到 Ref；
+- `byIdentity`：私有 key 或完整外部 URL 到 Ref，用于去重。
+
+## 5. Workflow 入口
+
+入口处理顺序：
+
+```text
+完成 Workflow/Chat 鉴权
+  -> 计算根 Workflow 文件 scope
+  -> 计算 maxFiles/maxBytesPerFile
+  -> 扫描 query + histories 文件
+  -> 校验 chat object key 归属
+  -> 校验外链必须为绝对 HTTP(S)
+  -> 对私有 key 按请求缓存签发两小时 modelUrl
+  -> 按 key/完整外链 URL 去重并建立只读 Context
+  -> 将 FileContext 挂载到 WorkflowContext
+  -> 开始节点调度
+```
+
+### 5.1 Query
+
+- 带 key：完整校验 `sourceType/sourceId/uid/chatId`，失败则拒绝本轮 Workflow；
+- 无 key：只允许绝对 HTTP(S) URL，并继续应用 `fileUrlWhitelist`；
+- 其他 URL：拒绝本轮 Workflow。
+
+### 5.2 Histories
+
+- 带 key：使用根 Workflow scope 校验并签发 URL；
+- 无 key的绝对 HTTP(S) URL：登记为外链；
+- 无 key的相对或非法 URL：不登记，使用该文件时返回不可用，不能交给内部 Axios；
+- 无关历史文件不可用时，不能阻塞整轮 Workflow。
+
+入口只登记来源和签发 URL，不下载所有历史文件正文。正文继续按消费者需求懒加载。
+
+## 6. 读取规则
+
+### 6.1 私有对象
+
+`WorkflowFileContext.read` 根据 Ref 中已校验的 bucket/objectKey 使用 S3 client：
+
+1. 先读取 metadata；
+2. `contentLength` 超过 `maxBytesPerFile` 时拒绝；
+3. 下载流再次按累计字节数限制；
+4. 返回 Buffer、filename 和 contentType。
+
+### 6.2 外部 URL
+
+外部 URL 始终使用带 SSRF 防护的 Axios：
+
+- 只允许 `http:` 和 `https:`；
+- 保留 `fileUrlWhitelist`；
+- SSRF Axios 负责 DNS、metadata 地址和逐跳重定向检查；
+- 先检查 `Content-Length`，流式下载时再次限制累计字节数；
+- 禁止使用 `pickOutboundAxios` 或任何内部相对路径 Axios。
+
+### 6.3 大小限制
+
+`dispatchWorkFlow` 接受可选的 `maxFileSize`（字节）。调用入口可以根据团队套餐和系统限制
+计算后传入；本期未传入时固定使用 2GB。
+
+该限制约束 FastGPT 服务端读取。模型提供商直接拉取外部 `modelUrl` 时，不经过 FastGPT
+下载链路，因此不计入服务端读取限制。
+
+## 7. 消费者
+
+### 7.1 AI Chat
+
+- 普通文档 URL 必须先命中 Context，再由统一读取器获取正文；
+- 图片、音频、视频默认使用 `modelUrl`；
+- LLM 层不感知 Workflow Context；`shouldLoadMediaAsBase64` 为真时统一使用 AI 层已有的
+  下载与 Base64 转换能力，否则把绝对 `modelUrl` 直接交给模型。
+
+### 7.2 ToolCall 和 AgentV2 read_file
+
+- 模型只提交 file id；
+- file id 必须命中节点已知文件映射，并最终命中 WorkflowFileContext；
+- 未知 id/URL 返回文件不可用，不能注册新外链；
+- 文档解析继续复用 `core/chat/fileContext.ts`。
+
+### 7.3 ReadFiles
+
+ReadFiles 的字符串 URL 输入保持兼容，但只有命中 WorkflowFileContext 的 URL 才能读取。
+
+### 7.4 Sandbox
+
+Workflow 显式向 Sandbox 文件注入步骤传入读取函数。该函数通过 WorkflowFileContext 读取
+Buffer 后写入 Sandbox；Sandbox 通用模块不引用 Workflow，也不使用 `requestOrigin`、相对 URL
+或内部 Axios。没有注入读取函数的普通外链仍走带 SSRF 防护的 Axios。
+
+### 7.5 Child、Loop 和 Parallel
+
+本期 Context 创建后保持只读，因此根 Workflow、Child、Loop 和 Parallel 共享同一请求级
+Context，不需要 clone 或 merge。下游只拿实际传入的 URL/file id 查询，Context 不提供枚举。
+
+## 8. 兼容策略
+
+- 文件类型、名称和 key 等运行态元数据统一由 WorkflowFileContext 提供，不再维护额外的
+  query URL Map；
+- WorkflowFileContext 复用 Workflow 自己的 AsyncLocalStorage，并由 Workflow 调用方显式传给
+  Chat/Sandbox；`core/ai` 和 `core/chat` 不得反向引用 `core/workflow`；
+- 字符串 URL 运行值继续保留；
+- keyless 历史绝对 URL 按外链处理；
+- keyless 历史相对 URL 不再通过内部 Axios 读取；
+- AgentV2 的 `normalizeAgentServerFileUrl` 和 `internalUrl` 过渡实现应删除；
+- Workflow 以外的普通聊天文件链路暂不纳入本期 Context，但共享读取函数不能再接受相对 URL。
+
+## 9. 测试要求
+
+### 9.1 Context
+
+- query/history 私有 key 归属校验成功；
+- sourceType/sourceId/uid/chatId 任一不匹配时拒绝；
+- 同一个 key 在 query/history 中只签发一次并只创建一个 Ref；
+- 外部绝对 HTTP(S) URL 可登记；
+- 相对 URL、protocol-relative、`file:`、`data:`、`ws:` 被拒绝或跳过；
+- `fileUrlWhitelist` 继续生效；
+- `resolve` 不会自动登记未知绝对 URL。
+
+### 9.2 读取
+
+- 私有对象通过 S3 client 读取；
+- 外链通过 SSRF Axios 读取；
+- 私有对象和外链均执行 header/metadata 与流式双重大小限制；
+- 私有对象读取不调用 HTTP；
+- 相对 URL 不进入任何 Axios。
+
+### 9.3 消费者
+
+- AI Chat、ToolCall、AgentV2、ReadFiles 使用同一 Context；
+- Agent history 和当前输入都保留绝对 modelUrl；
+- read_file 未知 id 无法读取；
+- Sandbox 注入通过 Context Buffer；
+- 不可用的无关 history 文件不阻塞本轮请求。
+
+## 10. TODO
+
+- [x] 新增只读 `WorkflowFileContext` 和入口准备函数；
+- [x] 为 `dispatchWorkFlow` 增加 `maxFileSize`，创建并挂载 Context；
+- [x] `parseUrlToFileType` 优先读取 Context 文件元数据；
+- [x] 统一 `core/chat/fileContext.ts` 的 Workflow 文件读取；
+- [x] 保持 AI Chat 多模态 Base64 与 Workflow Context 解耦；
+- [x] 迁移 ToolCall、AgentV2 和 ReadFiles；
+- [x] 迁移 Sandbox 文件注入；
+- [x] 删除 AgentV2 `requestOrigin/internalUrl` 过渡逻辑；
+- [x] 补齐 Context、读取器和消费者测试；
+- [x] 运行全量测试；Admin 既有批处理性能用例在全量并发下超时，隔离复跑 31/31 通过。
+
+## 11. 相关代码
+
+- `packages/service/core/workflow/utils/context.ts`
+- `packages/service/core/workflow/utils/fileContext.ts`
+- `packages/service/core/workflow/dispatch/index.ts`
+- `packages/service/core/chat/fileContext.ts`
+- `packages/service/core/workflow/dispatch/ai/chat/chatMessages.ts`
+- `packages/service/core/workflow/dispatch/ai/toolcall/tools/file.ts`
+- `packages/service/core/workflow/dispatch/ai/agent/adapter/userContext.ts`
+- `packages/service/core/workflow/dispatch/ai/agent/sub/file/index.ts`
+- `packages/service/core/ai/sandbox/application/file.ts`
+- `packages/service/core/workflow/dispatch/tools/readFiles.ts`
+- `packages/service/common/api/axios.ts`
+- `packages/service/common/s3/sources/chat/key.ts`

document/content/self-host/upgrading/4-15/4154.mdx

@@ -7,6 +7,8 @@ description: 'FastGPT V4.15.4 更新说明'
 
 ## ⚙️ 优化
 
+1. 工作流文件上下文管理，减少重复签发以及避免潜在安全问题。
+
 ## 🐛 修复
 
 1. chatbox 流输出时候，不应该展示系统工具的错误。

document/data/doc-last-modified.json

@@ -324,6 +324,8 @@
   "content/self-host/upgrading/4-15/4152.mdx": "2026-07-18T12:51:59+08:00",
   "content/self-host/upgrading/4-15/4153.en.mdx": "2026-07-18T12:51:59+08:00",
   "content/self-host/upgrading/4-15/4153.mdx": "2026-07-18T12:51:59+08:00",
+  "content/self-host/upgrading/4-15/4154.en.mdx": "2026-07-21T13:14:50+08:00",
+  "content/self-host/upgrading/4-15/4154.mdx": "2026-07-21T13:14:50+08:00",
   "content/self-host/upgrading/outdated/40.en.mdx": "2026-04-26T21:08:47+08:00",
   "content/self-host/upgrading/outdated/40.mdx": "2026-04-26T21:08:47+08:00",
   "content/self-host/upgrading/outdated/41.en.mdx": "2026-04-26T21:08:47+08:00",
@@ -464,6 +466,6 @@
   "content/self-host/upgrading/outdated/499.mdx": "2026-05-07T15:06:40+08:00",
   "content/self-host/upgrading/upgrade-intruction.en.mdx": "2026-04-26T21:08:47+08:00",
   "content/self-host/upgrading/upgrade-intruction.mdx": "2026-04-26T21:08:47+08:00",
-  "content/toc.en.mdx": "2026-07-18T12:51:59+08:00",
-  "content/toc.mdx": "2026-07-18T12:51:59+08:00"
+  "content/toc.en.mdx": "2026-07-21T13:14:50+08:00",
+  "content/toc.mdx": "2026-07-21T13:14:50+08:00"
 }

packages/service/core/ai/sandbox/application/file.ts

@@ -5,9 +5,13 @@
  */
 import type { FileWriteEntry, ISandbox } from '@fastgpt-sdk/sandbox-adapter';
 import mime from 'mime';
-import { pickOutboundAxios } from '../../../../common/api/axios';
+import { axios } from '../../../../common/api/axios';
 import type { SandboxClient } from './runtime/client';
 import { getSandboxRuntimeProfile } from '../infrastructure/provider/runtimeProfile';
+import { getFileMaxSize } from '../../../../common/file/utils';
+import { readStreamToBuffer } from '../../../../common/s3/utils';
+import type { Readable } from 'node:stream';
+import { getAxiosHeaderValue } from '@fastgpt/global/common/axios/utils';
 
 export type SandboxUrlFile = {
   path: string;
@@ -39,6 +43,34 @@ const isWithinSandboxWorkspace = (path: string, workDirectory: string) => {
   return path === workspace || path.startsWith(`${workspace}/`);
 };
 
+/** 读取准备写入 Sandbox 的远程文件，禁止相对 URL 回环访问本机 API。 */
+export const readSandboxUrlFile = async (url: string) => {
+  if (!/^https?:\/\//i.test(url)) {
+    throw new Error('Sandbox input file URL must be an absolute HTTP(S) URL');
+  }
+  const parsedUrl = new URL(url);
+  if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+    throw new Error('Sandbox input file URL must use HTTP(S)');
+  }
+
+  const maxFileSize = getFileMaxSize();
+  const response = await axios.get<Readable>(url, {
+    responseType: 'stream',
+    timeout: 180_000,
+    maxContentLength: maxFileSize
+  });
+  const contentLength = Number(getAxiosHeaderValue(response.headers['content-length']) || 0);
+  if (contentLength > maxFileSize) {
+    response.data.destroy();
+    throw new Error(`File exceeds maximum allowed size (${maxFileSize} bytes)`);
+  }
+  return readStreamToBuffer({
+    stream: response.data,
+    maxBytes: maxFileSize,
+    exceededMessage: `File exceeds maximum allowed size (${maxFileSize} bytes)`
+  });
+};
+
 /**
  * 将远程 URL 文件写入已存在的 sandbox 实例。
  *
@@ -50,14 +82,10 @@ export async function writeUrlFilesToSandbox(sandbox: ISandbox, files: SandboxUr
   for (const { path, url } of files) {
     if (!path) continue;
     writeFileTasks.push(
-      pickOutboundAxios(url)
-        .get<ArrayBuffer>(url, {
-          responseType: 'arraybuffer'
-        })
-        .then((response) => ({
-          path,
-          data: response.data
-        }))
+      readSandboxUrlFile(url).then((data) => ({
+        path,
+        data
+      }))
     );
   }