Skip to content

Commit 91abb74

Browse files
yhjun1026csunnyanotherso1adusx1981Aries-ckt
authored
Feature: Implement distributed execution architecture and enhance agent system (#159)
Co-authored-by: magic.chen <cfqsunny@163.com> Co-authored-by: AnotherSola <38176179+anotherso1a@users.noreply.github.com> Co-authored-by: 坐山客 <157097695@qq.com> Co-authored-by: Aries-ckt <916701291@qq.com> Co-authored-by: heyzcat <31226585+heyzcat@users.noreply.github.com> Co-authored-by: yangchuan <yangchuan@oppo.com> Co-authored-by: neuqliu <1196932066@qq.com> Co-authored-by: yanzhiyong <932374019@qq.com> Co-authored-by: gallopxiong <62653374+josehap@users.noreply.github.com> Co-authored-by: gallopxiong <gallopxiong@tencent.com> Co-authored-by: XinyueDu <51403464+XinyueDu@users.noreply.github.com> Co-authored-by: duxinyue.dxy <duxinyue.dxy@antgroup.com> Co-authored-by: Ikko Eltociear Ashimine <eltociear@gmail.com> Co-authored-by: lpq131004 <66124950+lpq131004@users.noreply.github.com> Co-authored-by: chenketing.ckt <chenketing.ckt@antgroup.com> Co-authored-by: Aries-ckt <ariesketing@gmail.com> Co-authored-by: Lin-Zhipeng <2542207527@qq.com> Co-authored-by: zhipeng.lin <zhipeng.lin@shopee.com> Co-authored-by: Claude (GLM-4.7) <noreply@anthropic.com> Co-authored-by: tptpp <544016459@qq.com> Co-authored-by: RichardoMu <44485717+RichardoMrMu@users.noreply.github.com> Co-authored-by: RichardoMrMu <tianbowen.tbw@antgroup.com> Co-authored-by: yhjun1026 <yhjun1026@users.noreply.github.com> Co-authored-by: cozfrain <49066537+niiish32x@users.noreply.github.com> Co-authored-by: 越鸿 <nishenghao.nsh@oceanbase.com>
1 parent f00bc93 commit 91abb74

245 files changed

Lines changed: 20425 additions & 1301 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎assets/schema/derisk.sql‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ use derisk;
99
-- MySQL DDL Script for Derisk
1010
-- Version: 0.3.0
1111
-- Generated from SQLAlchemy ORM Models
12-
-- Generated: 2026-03-09 22:38:05
12+
-- Generated: 2026-03-11 09:51:58
1313
-- ============================================================
1414

1515
SET NAMES utf8mb4;

‎docs/architecture/FILE_IN_OUT_ARCHITECTURE.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
📋 完整文件处理全流程梳理
2+
3+
一、整体架构图
4+
5+
┌─────────────────────────────────────────────────────────────────────────────┐
6+
│ 用户上传文件 │
7+
│ 前端 → POST /api/v1/files/{bucket} │
8+
└───────────────────────────────────┬─────────────────────────────────────────┘
9+
│
10+
▼
11+
┌─────────────────────────────────────────────────────────────────────────────┐
12+
│ 文件分流决策层 │
13+
│ derisk_serve/agent/nex/file_type_config.py │
14+
│ │
15+
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
16+
│ │ MODEL_DIRECT │ │ SANDBOX_TOOL │ │
17+
│ │ (模型直消费) │ │ (沙箱工具处理) │ │
18+
│ │ 图片/GIF等 │ │ 文档/代码/数据/压缩包 │ │
19+
│ └────────┬────────┘ └──────────────┬──────────────┘ │
20+
│ │ │ │
21+
│ ▼ ▼ │
22+
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
23+
│ │ 多模态模型输入 │ │ SandboxFileRef │ │
24+
│ │ ChatCompletion │ │ 下载到沙箱工作目录 │ │
25+
│ │ ContentPart │ │ 注册到AgentFileSystem │ │
26+
│ └─────────────────┘ └─────────────────────────────┘ │
27+
└─────────────────────────────────────────────────────────────────────────────┘
28+
│
29+
▼
30+
┌─────────────────────────────────────────────────────────────────────────────┐
31+
│ 沙箱文件处理层 │
32+
│ derisk/agent/core/file_system/ │
33+
│ │
34+
│ AgentFileSystem ────────────────────────────────────────────────────────── │
35+
│ ├── FileStorageClient (优先) │
36+
│ ├── OSS Client (回退) │
37+
│ └── LocalFileStorage (最后回退) │
38+
└───────────────────────────────────┬─────────────────────────────────────────┘
39+
│
40+
▼
41+
┌─────────────────────────────────────────────────────────────────────────────┐
42+
│ 工具生成文件 │
43+
│ derisk/agent/core/sandbox/tools/ │
44+
│ │
45+
│ ├── create_file_tool.py (创建文件) │
46+
│ ├── edit_file_tool.py (编辑文件) │
47+
│ └── deliver_file_tool.py (交付文件) ⭐ │
48+
└───────────────────────────────────┬─────────────────────────────────────────┘
49+
│
50+
▼
51+
┌─────────────────────────────────────────────────────────────────────────────┐
52+
│ 文件交付标记 │
53+
│ deliver_file_tool.py + dattach_utils.py │
54+
│ │
55+
│ 1. 读取沙箱文件内容 │
56+
│ 2. 上传到OSS获取持久化链接 │
57+
│ 3. 生成d-attach组件 │
58+
│ 4. 注册到AgentFileSystem │
59+
└───────────────────────────────────┬─────────────────────────────────────────┘
60+
│
61+
▼
62+
┌─────────────────────────────────────────────────────────────────────────────┐
63+
│ 前端展示 │
64+
│ VisDAttachList / d-attach-list 组件 │
65+
│ │
66+
│ ├── 预览功能 (preview_url) │
67+
│ ├── 下载功能 (download_url) │
68+
│ └── 批量下载 │
69+
└─────────────────────────────────────────────────────────────────────────────┘
70+
二、文件分流决策逻辑（核心）
71+
72+
关键文件: derisk_serve/agent/nex/file_type_config.py
73+
74+
class FileProcessMode(str, Enum):
75+
MODEL_DIRECT = "model_direct" # 直接发送给模型
76+
SANDBOX_TOOL = "sandbox_tool" # 通过沙箱工具处理
77+
78+
# 分流规则：
79+
# MODEL_DIRECT: 图片类型
80+
# SANDBOX_TOOL: 文档/代码/数据/压缩等
81+
# 默认: SANDBOX_TOOL
82+
分流触发点: derisk_serve/agent/nex/query_builder.py
83+
84+
def get_file_process_mode(file_name: str, mime_type: str) -> FileProcessMode:
85+
# 根据扩展名和MIME类型返回处理模式
86+
87+
# 如果是 MODEL_DIRECT:
88+
# → 返回 ChatCompletionContentPartImageParam
89+
# → 直接作为多模态模型输入
90+
91+
# 如果是 SANDBOX_TOOL:
92+
# → 返回 SandboxFileRef
93+
# → 下载到沙箱工作目录
94+
# → 注册到 AgentFileSystem
95+
三、迁移核心文件清单
96+
97+
✅ 必须迁移（按优先级排序）
98+
99+
序号 文件路径 核心类/函数 职责
100+
1 derisk-core/src/derisk/core/interface/file.py FileStorageClient, FileStorageSystem, StorageBackend, FileMetadata, FileStorageURI 文件存储抽象层核心
101+
2 derisk-core/src/derisk/agent/core/file_system/agent_file_system.py AgentFileSystem Agent文件系统V3
102+
3 derisk-core/src/derisk/agent/core/file_system/dattach_utils.py render_dattach, create_dattach_content d-attach组件生成
103+
4 derisk-core/src/derisk/agent/core/sandbox/tools/deliver_file_tool.py execute_deliver_file 文件交付工具 ⭐
104+
5 derisk-core/src/derisk/agent/core/sandbox_manager.py SandboxManager 沙箱生命周期管理
105+
6 derisk-serve/src/derisk_serve/agent/nex/file_type_config.py FileProcessMode, get_file_process_mode 文件分流决策
106+
7 derisk-serve/src/derisk_serve/agent/nex/query_builder.py QueryBuilder, SandboxFileRef 文件路由处理
107+
8 derisk-serve/src/derisk_serve/file/api/endpoints.py upload_files, download_file 文件API端点
108+
9 derisk-serve/src/derisk_serve/file/service/service.py Service.upload_files 文件服务层
109+
10 derisk-serve/src/derisk_serve/file/api/schemas.py UploadFileResponse, FileMetadataResponse 数据模型
110+
📦 按需迁移
111+
112+
文件路径 核心类/函数 职责
113+
derisk-ext/src/derisk_ext/storage/file/oss/oss_storage.py AliyunOSSStorage 阿里云OSS存储
114+
derisk-ext/src/derisk_ext/storage/file/ant_oss/oss_storage.py AntOSSStorage 蚂蚁OSS存储
115+
derisk-ext/src/derisk_ext/storage/file/s3/s3_storage.py S3Storage S3存储
116+
derisk-core/src/derisk/agent/core/sandbox/tools/create_file_tool.py execute_create_file 创建文件工具
117+
derisk-core/src/derisk/agent/core/sandbox/tools/edit_file_tool.py execute_edit_file 编辑文件工具
118+
derisk-core/src/derisk/agent/core/sandbox/tools/download_file_tool.py execute_download_file 下载文件工具
119+
🔗 依赖文件
120+
121+
文件路径 核心类/函数 职责
122+
derisk-core/src/derisk/agent/core/memory/gpts/file_base.py AgentFileMetadata, FileType 文件元数据模型
123+
derisk-core/src/derisk/vis/schema.py VisAttachContent, VisAttachListContent 可视化数据模型
124+
derisk-core/src/derisk/sandbox/client/file/client.py FileClient 沙箱文件客户端接口
125+
derisk-core/src/derisk/sandbox/client/file/types.py FileInfo, OSSFile 文件类型定义
126+
四、核心数据结构
127+
128+
1. FileMetadata（文件存储层）
129+
130+
@dataclass
131+
class FileMetadata(StorageItem):
132+
file_id: str # 文件ID
133+
bucket: str # 存储桶
134+
file_name: str # 文件名
135+
file_size: int # 文件大小
136+
storage_type: str # 存储类型
137+
storage_path: str # 存储路径
138+
uri: str # 统一资源标识
139+
custom_metadata: Dict # 自定义元数据
140+
file_hash: str # 文件哈希
141+
2. AgentFileMetadata（Agent层）
142+
143+
class AgentFileMetadata:
144+
file_id: str
145+
conv_id: str # 会话ID
146+
file_key: str # 文件键
147+
file_name: str
148+
file_type: FileType # CONCLUSION/DELIVERABLE/TOOL_OUTPUT等
149+
oss_url: str # OSS地址
150+
preview_url: str # 预览URL
151+
download_url: str # 下载URL
152+
mime_type: str
153+
created_at: datetime
154+
expires_at: datetime
155+
3. FileType枚举
156+
157+
class FileType(str, Enum):
158+
TEMP = "temp" # 临时文件
159+
TOOL_OUTPUT = "tool_output" # 工具输出
160+
TRUNCATED_OUTPUT = "truncated" # 截断输出
161+
CONCLUSION = "conclusion" # 结论文件
162+
DELIVERABLE = "deliverable" # 交付物 ⭐
163+
KANBAN = "kanban"
164+
WRITE_FILE = "write_file"
165+
4. SandboxFileRef（分流层）
166+
167+
@dataclass
168+
class SandboxFileRef:
169+
file_name: str # 文件名
170+
file_url: str # 文件URL
171+
mime_type: str # MIME类型
172+
object_path: str # OSS对象路径
173+
sandbox_path: str # 沙箱本地路径
174+
五、关键API接口
175+
176+
文件上传
177+
178+
POST /api/v1/files/{bucket}
179+
Request: multipart/form-data (files[])
180+
Response: List[UploadFileResponse]
181+
- file_name, file_id, bucket, uri
182+
文件下载
183+
184+
GET /api/v1/files/{bucket}/{file_id}
185+
Response: StreamingResponse (application/octet-stream)
186+
文件预览
187+
188+
GET /api/v1/files/preview?url={oss_url}
189+
Response: Response (with Content-Type header)
190+
文件元数据
191+
192+
GET /api/v1/files/metadata?uri={uri}
193+
POST /api/v1/files/metadata/batch
194+
Response: FileMetadataResponse
195+
- file_name, file_id, bucket, uri, file_size
196+
六、迁移步骤建议
197+
198+
第一步：迁移存储抽象层
199+
200+
# 1. 复制核心接口文件
201+
derisk-core/src/derisk/core/interface/file.py
202+
203+
# 2. 选择存储后端实现
204+
# 阿里云OSS
205+
derisk-ext/src/derisk_ext/storage/file/oss/oss_storage.py
206+
# 或 S3
207+
derisk-ext/src/derisk_ext/storage/file/s3/s3_storage.py
208+
第二步：迁移文件服务层
209+
210+
# API端点
211+
derisk-serve/src/derisk_serve/file/api/endpoints.py
212+
derisk-serve/src/derisk_serve/file/api/schemas.py
213+
214+
# 服务实现
215+
derisk-serve/src/derisk_serve/file/service/service.py
216+
第三步：迁移分流决策层
217+
218+
# 文件类型配置
219+
derisk-serve/src/derisk_serve/agent/nex/file_type_config.py
220+
221+
# 路由处理
222+
derisk-serve/src/derisk_serve/agent/nex/query_builder.py
223+
第四步：迁移沙箱文件系统
224+
225+
# Agent文件系统
226+
derisk-core/src/derisk/agent/core/file_system/agent_file_system.py
227+
derisk-core/src/derisk/agent/core/file_system/dattach_utils.py
228+
229+
# 沙箱管理器
230+
derisk-core/src/derisk/agent/core/sandbox_manager.py
231+
232+
# 文件工具
233+
derisk-core/src/derisk/agent/core/sandbox/tools/deliver_file_tool.py
234+
第五步：迁移前端组件
235+
236+
# Vis数据模型
237+
derisk-core/src/derisk/vis/schema.py
238+
239+
# 前端组件（如需要）
240+
web/src/components/chat/chat-content-components/VisComponents/VisDAttachList/
241+
七、注意事项
242+
243+
依赖注入: FileStorageClient 需要通过 SystemApp 注册和获取
244+
配置项: 需要配置OSS/S3的访问凭证和endpoint
245+
沙箱环境: 如使用沙箱功能，需配置沙箱服务（XIC等）
246+
URL生成: 确保存储后端支持生成公开访问URL（签名URL）
247+
元数据存储: 需要配置数据库或内存存储文件元数据
248+
文件类型扩展: 如需新增文件类型分流规则，修改 file_type_config.py

0 commit comments

Comments
 (0)