時(shí)工件事件與會(huì)話歸檔下載)
ChatDev 2.0 附件與工件 API 詳解文件上傳、實(shí)時(shí)工件事件與會(huì)話歸檔下載【免費(fèi)下載鏈接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev本文基于 ChatDev 2.0 倉(cāng)庫(kù)中的 附件與工件 API 指南系統(tǒng)講解直接對(duì)接后端 REST/WS 端點(diǎn)時(shí)如何處理“附件Attachment”與“工件Artifact”如何上傳/列舉文件、如何在執(zhí)行請(qǐng)求中引用附件、如何實(shí)時(shí)監(jiān)聽節(jié)點(diǎn)產(chǎn)出的文件事件、如何按模式下載工件并打包整個(gè)會(huì)話以及文件生命周期與大小/安全策略。讀完后你可以為自有前端、CLI 或自動(dòng)化流水線構(gòu)建完整的附件接入層并能在排障時(shí)準(zhǔn)確定位 413/404、事件缺失等常見問題。1. 核心概念A(yù)ttachment 與 Artifact 的分工ChatDev 2.0 中文件能力被拆成兩個(gè)層次Attachment附件Session 生命周期內(nèi)可上傳、下載、由節(jié)點(diǎn)注冊(cè)的文件。它落到磁盤并有attachments_manifest.json清單跟蹤元數(shù)據(jù)ID、文件名、MIME、大小、來(lái)源等。Artifact工件附件發(fā)生變化時(shí)發(fā)出的事件抽象。節(jié)點(diǎn)在代碼工作區(qū)里新建/修改文件后系統(tǒng)生成artifact_created事件客戶端可通過 WebSocket 或 REST 長(zhǎng)輪詢實(shí)時(shí)訂閱。這個(gè)分層從源碼結(jié)構(gòu)看非常清晰存儲(chǔ)層是 AttachmentStore以文件系統(tǒng)目錄為根維護(hù)記錄字典、哈希索引與 manifest 文件會(huì)話級(jí)服務(wù) AttachmentService 負(fù)責(zé)按session_id組裝路徑、保存上傳、清理策略事件側(cè)由 ArtifactEvent 與 ArtifactEventQueue 提供帶游標(biāo)的有界隊(duì)列節(jié)點(diǎn)產(chǎn)出文件則由 WorkspaceArtifactHook 掃描工作區(qū)并注冊(cè)工件。2. 上傳與列舉附件2.1 上傳文件POST /api/uploads/{session_id}請(qǐng)求頭Content-Type: multipart/form-dataForm 字段file單個(gè)文件服務(wù)端路由見 uploads.py先通過ensure_known_session校驗(yàn)會(huì)話再調(diào)用manager.attachment_service.save_upload_file(session_id, file)落盤。文檔給出的響應(yīng)示例{ attachment_id: att_bxabcd, name: spec.md, mime: text/markdown, size: 12345 }需要注意一個(gè)實(shí)現(xiàn)細(xì)節(jié)當(dāng)前倉(cāng)庫(kù)的路由實(shí)際返回的字段名為mime_type而非mime見 uploads.py 返回體。對(duì)接時(shí)請(qǐng)以實(shí)際響應(yīng)字段為準(zhǔn)。2.2 上傳后的落盤位置與清單AttachmentService._session_attachments_path 表明文件最終保存到WareHouse/session_session_id/code_workspace/attachments/其中WARE_HOUSE_DIR默認(rèn)就是WareHouse見 settings.py。每個(gè)附件注冊(cè)為一條記錄后AttachmentStore會(huì)持久化到該目錄下的attachments_manifest.jsonmanifest 讀寫邏輯。上傳時(shí)的處理流程在 save_upload_file先寫入臨時(shí)目錄逐塊1MB拷貝上傳內(nèi)容用mimetypes猜測(cè) MIME優(yōu)先使用upload.content_type調(diào)用store.register_file(...)并通過MessageBlockType.from_mime_type(mime_type)把類型歸入 image/audio/video/file 四類供后續(xù)消息塊渲染extra中記錄source: user_upload、origin: web_upload、session_id。register_file本身還有值得了解的參數(shù)見 AttachmentStore.register_filekind、display_name、mime_type、copy_file是否拷貝進(jìn)存儲(chǔ)目錄、persist是否寫入 manifest、deduplicate基于 SHA-256 哈希去重。哈希索引_hash_index讓相同內(nèi)容的文件可以復(fù)用已有記錄。2.3 列舉附件GET /api/uploads/{session_id}返回該會(huì)話所有附件的元數(shù)據(jù)ID、文件名、MIME、大小、來(lái)源。實(shí)現(xiàn)非常直接list_attachments 返回{attachments: manifest}即AttachmentStore.export_manifest()的輸出export_manifest鍵為attachment_id值為完整記錄字典ref、kind、description、extra。2.4 在執(zhí)行請(qǐng)求中引用附件POST /api/workflow/execute請(qǐng)求體可攜帶attachments: [att_xxx]請(qǐng)求模型見 WorkflowRequest路由將attachments透?jìng)鹘omanager.workflow_run_service.start_workflow(...)見 execute.py。WebSockethuman_input消息同樣支持attachments數(shù)組見 message_handler.py。文檔提示調(diào)用 execute 時(shí)仍需提供task_prompt。不過從源碼結(jié)構(gòu)看同步執(zhí)行入口對(duì)這一約束更寬松execute_sync.py 只在task_prompt與attachments同時(shí)為空時(shí)才拋Task prompt cannot be empty即“僅上傳文件”的場(chǎng)景可以通過同步接口發(fā)起。附件如何進(jìn)入執(zhí)行上下文build_attachment_blocks 會(huì)把每個(gè)attachment_id查成記錄必要時(shí)ingest_record拷貝到目標(biāo)存儲(chǔ)跨存儲(chǔ)根目錄時(shí)才真正拷貝文件最終轉(zhuǎn)換為MessageBlock隨任務(wù)輸入下發(fā)。3. 工件事件與下載3.1 實(shí)時(shí)事件GET /api/sessions/{session_id}/artifact-events該接口實(shí)現(xiàn)為長(zhǎng)輪詢見 poll_artifact_events。查詢參數(shù)及默認(rèn)值如下以源碼Query約束為準(zhǔn)參數(shù)說明默認(rèn)/約束after序列號(hào)游標(biāo)返回該游標(biāo)之后的事件可選 0wait_seconds無(wú)事件時(shí)阻塞等待時(shí)長(zhǎng)默認(rèn)25.0范圍0~60include_mimeMIME 前綴白名單逗號(hào)分隔可選include_ext擴(kuò)展名白名單逗號(hào)分隔可帶或不帶點(diǎn)可選max_size只返回不超過該字節(jié)數(shù)的事件可選 0limit單次返回事件數(shù)默認(rèn)25范圍1~100響應(yīng)包含events[]、next_cursor、has_more、timed_out四個(gè)字段其中has_more由queue.last_sequence (next_cursor or 0)判定timed_out表示本輪等待超時(shí)仍無(wú)匹配事件。過濾邏輯在 ArtifactEvent.matches_filterinclude_mime支持精確匹配或前綴匹配如image/include_ext歸一化后按文件后綴匹配max_size做大小上限過濾。隊(duì)列本身是線程安全的有界隊(duì)列ArtifactEventQueue默認(rèn)最多保留 2000 條事件超出后丟棄最舊事件并推進(jìn)_min_sequence因此after游標(biāo)若指向過舊的序列號(hào)會(huì)被鉗制到仍在窗口內(nèi)的位置。wait_for_events通過threading.Condition阻塞等待新事件到達(dá)路由側(cè)用asyncio.to_thread包裝以避免阻塞事件循環(huán)。3.2 事件樣例每條事件的核心字段to_dict輸出見 ArtifactEvent.to_dict{ artifact_id: art_123, attachment_id: att_456, node_id: python_runner, path: code_workspace/result.json, size: 2048, mime: application/json, hash: sha256:..., timestamp: 1732699900 }文檔中的樣例是示意寫法當(dāng)前源碼的實(shí)際字段還包括event_id、sequence、file_name、relative_path、workspace_path、mime_type、sha256、data_uri、created_at、change_typecreated/updated/deleted與extra。3.3 WebSocket 鏡像artifact_created同一批工件事件也會(huì)通過 WebSocket 下發(fā)消息類型為artifact_created見 artifact_dispatcher.py。因此儀表盤類客戶端可以直接訂閱 WS 實(shí)現(xiàn)實(shí)時(shí)刷新無(wú)需輪詢 REST。3.4 事件從哪里來(lái)WorkspaceArtifactHook節(jié)點(diǎn)運(yùn)行期間WorkspaceArtifactHook 負(fù)責(zé)把“節(jié)點(diǎn)改了哪些文件”翻譯成工件事件只對(duì)python、agent類型節(jié)點(diǎn)生效node_types默認(rèn)值before_node對(duì)工作區(qū)做 SHA-256 快照after_node成功后對(duì)比快照找出新增/變更/刪除的文件每個(gè)變更文件調(diào)用attachment_store.register_file(copy_fileFalse, persistTrue)注冊(cè)為附件extra中記錄node_id、relative_path、hook: workspace_scan見 _register_artifact默認(rèn)排除attachments、__pycache__目錄掃描上限為 500 個(gè)文件或 500MB 字節(jié)超出會(huì)截?cái)嗖⒂涗?warning構(gòu)造函數(shù)參數(shù)。這解釋了文檔 FAQ 中“附件未在 Python 節(jié)點(diǎn)可見”的排查方向之一工作區(qū)掃描與附件目錄共享code_workspace/且掃描本身排除attachments目錄。3.5 下載單個(gè)工件GET /api/sessions/{session_id}/artifacts/{artifact_id}實(shí)現(xiàn)見 get_artifact。查詢參數(shù)modemeta默認(rèn)或stream正則約束^(meta|stream)$downloadtrue|false影響Content-Disposition取attachment還是inline。兩種模式的實(shí)際行為modestream讀取ref.local_path返回StreamingResponse流式下載Content-Type取mime_type缺省application/octet-stream。文件不存在或無(wú)本地路徑時(shí)返回 404Artifact content unavailable/Artifact file missing。modemeta返回元數(shù)據(jù) JSON包含artifact_id、name、mime_type、size、sha256、data_uri、local_path、extra。當(dāng)ref未預(yù)置data_uri且文件不超過 20MB路由常量MAX_FILE_SIZE 20 * 1024 * 1024時(shí)服務(wù)端會(huì)現(xiàn)場(chǎng)用 encode_file_to_data_uri 編碼內(nèi)聯(lián) base64——這就是文檔所說“小文件可返回data_uri若服務(wù)器啟用”的實(shí)現(xiàn)來(lái)源。另外注意路由中store.get(artifact_id)查詢的是附件存儲(chǔ)事件里的attachment_id才是下載端點(diǎn)的鍵事件to_dict中artifact_id字段與文檔命名略有出入對(duì)接時(shí)以attachment_id為準(zhǔn)更穩(wěn)妥。3.6 打包下載整個(gè)會(huì)話GET /api/sessions/{session_id}/download實(shí)現(xiàn)見 download_session嚴(yán)格校驗(yàn)session_id僅含字母/數(shù)字/_-正則^[a-zA-Z0-9_-]$不合法時(shí)記錄INVALID_SESSION_ID_FORMAT安全事件并返回 400定位WareHouse/session_session_id/目錄不存在返回 404用shutil.make_archive打包為 zip通過FileResponse返回Content-Disposition: attachment; filenamesession_xxx.zip響應(yīng)完成后由BackgroundTask清理臨時(shí) zip 文件。打包下載不會(huì)刪除原文件歸檔與清理需自行安排定時(shí)任務(wù)。4. 文件生命周期結(jié)合文檔與源碼一個(gè)附件從上傳到可下載的完整鏈路是上傳階段POST /api/uploads/{session_id}寫入code_workspace/attachments/manifest 記錄ref含本地路徑、kind、description、extra含source、workspace_path等由調(diào)用方寫入的字段。節(jié)點(diǎn)注冊(cè)Python/Agent 節(jié)點(diǎn)可通過AttachmentStore.register_file()把工作區(qū)文件注冊(cè)為附件支持deduplicate哈希去重WorkspaceArtifactHook自動(dòng)掃描節(jié)點(diǎn)前后差異并同步到事件流。保留策略默認(rèn)保留所有附件以便運(yùn)行結(jié)束后下載。AttachmentService 構(gòu)造時(shí) 讀取環(huán)境變量MAC_AUTO_CLEAN_ATTACHMENTS1/true/yes視為開啟開啟后cleanup_session會(huì)在會(huì)話結(jié)束時(shí)shutil.rmtree刪除attachments/目錄cleanup_session關(guān)閉時(shí)僅打日志保留文件。打包下載zip 下載只讀取不刪除需要額外的 cron/job 做歸檔或清空。5. 大小與安全建議大小限制后端上傳路徑本身未做硬編碼上限save_upload_file逐塊讀取但未限制總量應(yīng)在反向代理層設(shè)置client_max_body_size/max_request_body_size或在自有分支的AttachmentService.save_upload_file中增加校驗(yàn)。工件meta模式的data_uri內(nèi)聯(lián)則有 20MB 代碼上限見 artifacts.py。文件類型MIME 推斷決定MessageBlockTypeimage/audio/video/file見 save_upload_file客戶端可用include_mime過濾事件流。病毒/敏感數(shù)據(jù)建議客戶端上傳前預(yù)掃描也可在保存后觸發(fā)掃描服務(wù)倉(cāng)庫(kù)未內(nèi)置掃描器。權(quán)限附件 API 依賴session_id定位資源。會(huì)話 ID 字符集校驗(yàn)可防路徑穿越見 sessions.py 的正則與安全日志但生產(chǎn)部署仍應(yīng)在代理層或 JWT 內(nèi)部校驗(yàn)調(diào)用者身份防止越權(quán)下載他人會(huì)話的制品。6. 常見問題排查FAQ問題排查步驟上傳 413 Payload Too Large調(diào)高反向代理或 FastAPI 的client_max_size確認(rèn)磁盤配額下載鏈接 404檢查session_id拼寫僅允許字母/數(shù)字/_-確認(rèn)會(huì)話目錄未被清理download_session 對(duì)目錄不存在直接返回 404工件事件缺失確認(rèn) WebSocket 已連接或用artifact-events長(zhǎng)輪詢并攜帶after游標(biāo)重拉注意事件隊(duì)列僅有 2000 條滑動(dòng)窗口附件未在 Python 節(jié)點(diǎn)可見檢查code_workspace/attachments/是否被MAC_AUTO_CLEAN_ATTACHMENTS清理以及 Python 執(zhí)行上下文中的工作區(qū)根路徑python_workspace_root是否正確7. 客戶端接入模式Web UI優(yōu)先訂閱 WebSocket 的artifact_created或退化為artifact-events長(zhǎng)輪詢wait_seconds最大 60 秒實(shí)時(shí)刷新附件列表節(jié)點(diǎn)成功后提供“下載全部”按鈕直接請(qǐng)求/api/sessions/{session_id}/download。CLI/自動(dòng)化運(yùn)行結(jié)束后調(diào)用/download拉取整包 zip若只需部分文件先用artifact-events配合include_ext如csv,png與max_size精準(zhǔn)過濾再逐個(gè)以modestreamdownloadtrue下載。測(cè)試環(huán)境用腳本模擬“上傳 → execute 引用 → 輪詢事件 → 下載”全流程提前驗(yàn)證反向代理的 body size 限制與 CORS 配置。8. 延伸閱讀英文原文Attachment Artifact API Guide中文版附件與工件 API 指南核心實(shí)現(xiàn)AttachmentStore、AttachmentService、上傳路由、工件路由、會(huì)話下載路由、事件隊(duì)列、工作區(qū)鉤子【免費(fèi)下載鏈接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 ChatDev 2.0 附件與工件 API 詳解：文件上傳、實(shí)時(shí)工件事件與會(huì)話歸檔下載
ChatDev 2.0 附件與工件 API 詳解文件上傳、實(shí)時(shí)工件事件與會(huì)話歸檔下載【免費(fèi)下載鏈接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev本文基于 ChatDev 2.0 倉(cāng)庫(kù)中的 附件與工件 API 指南系統(tǒng)講解直接對(duì)接后端 REST/WS 端點(diǎn)時(shí)如何處理“附件Attachment”與“工件Artifact”如何上傳/列舉文件、如何在執(zhí)行請(qǐng)求中引用附件、如何實(shí)時(shí)監(jiān)聽節(jié)點(diǎn)產(chǎn)出的文件事件、如何按模式下載工件并打包整個(gè)會(huì)話以及文件生命周期與大小/安全策略。讀完后你可以為自有前端、CLI 或自動(dòng)化流水線構(gòu)建完整的附件接入層并能在排障時(shí)準(zhǔn)確定位 413/404、事件缺失等常見問題。1. 核心概念A(yù)ttachment 與 Artifact 的分工ChatDev 2.0 中文件能力被拆成兩個(gè)層次Attachment附件Session 生命周期內(nèi)可上傳、下載、由節(jié)點(diǎn)注冊(cè)的文件。它落到磁盤并有attachments_manifest.json清單跟蹤元數(shù)據(jù)ID、文件名、MIME、大小、來(lái)源等。Artifact工件附件發(fā)生變化時(shí)發(fā)出的事件抽象。節(jié)點(diǎn)在代碼工作區(qū)里新建/修改文件后系統(tǒng)生成artifact_created事件客戶端可通過 WebSocket 或 REST 長(zhǎng)輪詢實(shí)時(shí)訂閱。這個(gè)分層從源碼結(jié)構(gòu)看非常清晰存儲(chǔ)層是 AttachmentStore以文件系統(tǒng)目錄為根維護(hù)記錄字典、哈希索引與 manifest 文件會(huì)話級(jí)服務(wù) AttachmentService 負(fù)責(zé)按session_id組裝路徑、保存上傳、清理策略事件側(cè)由 ArtifactEvent 與 ArtifactEventQueue 提供帶游標(biāo)的有界隊(duì)列節(jié)點(diǎn)產(chǎn)出文件則由 WorkspaceArtifactHook 掃描工作區(qū)并注冊(cè)工件。2. 上傳與列舉附件2.1 上傳文件POST /api/uploads/{session_id}請(qǐng)求頭Content-Type: multipart/form-dataForm 字段file單個(gè)文件服務(wù)端路由見 uploads.py先通過ensure_known_session校驗(yàn)會(huì)話再調(diào)用manager.attachment_service.save_upload_file(session_id, file)落盤。文檔給出的響應(yīng)示例{ attachment_id: att_bxabcd, name: spec.md, mime: text/markdown, size: 12345 }需要注意一個(gè)實(shí)現(xiàn)細(xì)節(jié)當(dāng)前倉(cāng)庫(kù)的路由實(shí)際返回的字段名為mime_type而非mime見 uploads.py 返回體。對(duì)接時(shí)請(qǐng)以實(shí)際響應(yīng)字段為準(zhǔn)。2.2 上傳后的落盤位置與清單AttachmentService._session_attachments_path 表明文件最終保存到WareHouse/session_session_id/code_workspace/attachments/其中WARE_HOUSE_DIR默認(rèn)就是WareHouse見 settings.py。每個(gè)附件注冊(cè)為一條記錄后AttachmentStore會(huì)持久化到該目錄下的attachments_manifest.jsonmanifest 讀寫邏輯。上傳時(shí)的處理流程在 save_upload_file先寫入臨時(shí)目錄逐塊1MB拷貝上傳內(nèi)容用mimetypes猜測(cè) MIME優(yōu)先使用upload.content_type調(diào)用store.register_file(...)并通過MessageBlockType.from_mime_type(mime_type)把類型歸入 image/audio/video/file 四類供后續(xù)消息塊渲染extra中記錄source: user_upload、origin: web_upload、session_id。register_file本身還有值得了解的參數(shù)見 AttachmentStore.register_filekind、display_name、mime_type、copy_file是否拷貝進(jìn)存儲(chǔ)目錄、persist是否寫入 manifest、deduplicate基于 SHA-256 哈希去重。哈希索引_hash_index讓相同內(nèi)容的文件可以復(fù)用已有記錄。2.3 列舉附件GET /api/uploads/{session_id}返回該會(huì)話所有附件的元數(shù)據(jù)ID、文件名、MIME、大小、來(lái)源。實(shí)現(xiàn)非常直接list_attachments 返回{attachments: manifest}即AttachmentStore.export_manifest()的輸出export_manifest鍵為attachment_id值為完整記錄字典ref、kind、description、extra。2.4 在執(zhí)行請(qǐng)求中引用附件POST /api/workflow/execute請(qǐng)求體可攜帶attachments: [att_xxx]請(qǐng)求模型見 WorkflowRequest路由將attachments透?jìng)鹘omanager.workflow_run_service.start_workflow(...)見 execute.py。WebSockethuman_input消息同樣支持attachments數(shù)組見 message_handler.py。文檔提示調(diào)用 execute 時(shí)仍需提供task_prompt。不過從源碼結(jié)構(gòu)看同步執(zhí)行入口對(duì)這一約束更寬松execute_sync.py 只在task_prompt與attachments同時(shí)為空時(shí)才拋Task prompt cannot be empty即“僅上傳文件”的場(chǎng)景可以通過同步接口發(fā)起。附件如何進(jìn)入執(zhí)行上下文build_attachment_blocks 會(huì)把每個(gè)attachment_id查成記錄必要時(shí)ingest_record拷貝到目標(biāo)存儲(chǔ)跨存儲(chǔ)根目錄時(shí)才真正拷貝文件最終轉(zhuǎn)換為MessageBlock隨任務(wù)輸入下發(fā)。3. 工件事件與下載3.1 實(shí)時(shí)事件GET /api/sessions/{session_id}/artifact-events該接口實(shí)現(xiàn)為長(zhǎng)輪詢見 poll_artifact_events。查詢參數(shù)及默認(rèn)值如下以源碼Query約束為準(zhǔn)參數(shù)說明默認(rèn)/約束after序列號(hào)游標(biāo)返回該游標(biāo)之后的事件可選 0wait_seconds無(wú)事件時(shí)阻塞等待時(shí)長(zhǎng)默認(rèn)25.0范圍0~60include_mimeMIME 前綴白名單逗號(hào)分隔可選include_ext擴(kuò)展名白名單逗號(hào)分隔可帶或不帶點(diǎn)可選max_size只返回不超過該字節(jié)數(shù)的事件可選 0limit單次返回事件數(shù)默認(rèn)25范圍1~100響應(yīng)包含events[]、next_cursor、has_more、timed_out四個(gè)字段其中has_more由queue.last_sequence (next_cursor or 0)判定timed_out表示本輪等待超時(shí)仍無(wú)匹配事件。過濾邏輯在 ArtifactEvent.matches_filterinclude_mime支持精確匹配或前綴匹配如image/include_ext歸一化后按文件后綴匹配max_size做大小上限過濾。隊(duì)列本身是線程安全的有界隊(duì)列ArtifactEventQueue默認(rèn)最多保留 2000 條事件超出后丟棄最舊事件并推進(jìn)_min_sequence因此after游標(biāo)若指向過舊的序列號(hào)會(huì)被鉗制到仍在窗口內(nèi)的位置。wait_for_events通過threading.Condition阻塞等待新事件到達(dá)路由側(cè)用asyncio.to_thread包裝以避免阻塞事件循環(huán)。3.2 事件樣例每條事件的核心字段to_dict輸出見 ArtifactEvent.to_dict{ artifact_id: art_123, attachment_id: att_456, node_id: python_runner, path: code_workspace/result.json, size: 2048, mime: application/json, hash: sha256:..., timestamp: 1732699900 }文檔中的樣例是示意寫法當(dāng)前源碼的實(shí)際字段還包括event_id、sequence、file_name、relative_path、workspace_path、mime_type、sha256、data_uri、created_at、change_typecreated/updated/deleted與extra。3.3 WebSocket 鏡像artifact_created同一批工件事件也會(huì)通過 WebSocket 下發(fā)消息類型為artifact_created見 artifact_dispatcher.py。因此儀表盤類客戶端可以直接訂閱 WS 實(shí)現(xiàn)實(shí)時(shí)刷新無(wú)需輪詢 REST。3.4 事件從哪里來(lái)WorkspaceArtifactHook節(jié)點(diǎn)運(yùn)行期間WorkspaceArtifactHook 負(fù)責(zé)把“節(jié)點(diǎn)改了哪些文件”翻譯成工件事件只對(duì)python、agent類型節(jié)點(diǎn)生效node_types默認(rèn)值before_node對(duì)工作區(qū)做 SHA-256 快照after_node成功后對(duì)比快照找出新增/變更/刪除的文件每個(gè)變更文件調(diào)用attachment_store.register_file(copy_fileFalse, persistTrue)注冊(cè)為附件extra中記錄node_id、relative_path、hook: workspace_scan見 _register_artifact默認(rèn)排除attachments、__pycache__目錄掃描上限為 500 個(gè)文件或 500MB 字節(jié)超出會(huì)截?cái)嗖⒂涗?warning構(gòu)造函數(shù)參數(shù)。這解釋了文檔 FAQ 中“附件未在 Python 節(jié)點(diǎn)可見”的排查方向之一工作區(qū)掃描與附件目錄共享code_workspace/且掃描本身排除attachments目錄。3.5 下載單個(gè)工件GET /api/sessions/{session_id}/artifacts/{artifact_id}實(shí)現(xiàn)見 get_artifact。查詢參數(shù)modemeta默認(rèn)或stream正則約束^(meta|stream)$downloadtrue|false影響Content-Disposition取attachment還是inline。兩種模式的實(shí)際行為modestream讀取ref.local_path返回StreamingResponse流式下載Content-Type取mime_type缺省application/octet-stream。文件不存在或無(wú)本地路徑時(shí)返回 404Artifact content unavailable/Artifact file missing。modemeta返回元數(shù)據(jù) JSON包含artifact_id、name、mime_type、size、sha256、data_uri、local_path、extra。當(dāng)ref未預(yù)置data_uri且文件不超過 20MB路由常量MAX_FILE_SIZE 20 * 1024 * 1024時(shí)服務(wù)端會(huì)現(xiàn)場(chǎng)用 encode_file_to_data_uri 編碼內(nèi)聯(lián) base64——這就是文檔所說“小文件可返回data_uri若服務(wù)器啟用”的實(shí)現(xiàn)來(lái)源。另外注意路由中store.get(artifact_id)查詢的是附件存儲(chǔ)事件里的attachment_id才是下載端點(diǎn)的鍵事件to_dict中artifact_id字段與文檔命名略有出入對(duì)接時(shí)以attachment_id為準(zhǔn)更穩(wěn)妥。3.6 打包下載整個(gè)會(huì)話GET /api/sessions/{session_id}/download實(shí)現(xiàn)見 download_session嚴(yán)格校驗(yàn)session_id僅含字母/數(shù)字/_-正則^[a-zA-Z0-9_-]$不合法時(shí)記錄INVALID_SESSION_ID_FORMAT安全事件并返回 400定位WareHouse/session_session_id/目錄不存在返回 404用shutil.make_archive打包為 zip通過FileResponse返回Content-Disposition: attachment; filenamesession_xxx.zip響應(yīng)完成后由BackgroundTask清理臨時(shí) zip 文件。打包下載不會(huì)刪除原文件歸檔與清理需自行安排定時(shí)任務(wù)。4. 文件生命周期結(jié)合文檔與源碼一個(gè)附件從上傳到可下載的完整鏈路是上傳階段POST /api/uploads/{session_id}寫入code_workspace/attachments/manifest 記錄ref含本地路徑、kind、description、extra含source、workspace_path等由調(diào)用方寫入的字段。節(jié)點(diǎn)注冊(cè)Python/Agent 節(jié)點(diǎn)可通過AttachmentStore.register_file()把工作區(qū)文件注冊(cè)為附件支持deduplicate哈希去重WorkspaceArtifactHook自動(dòng)掃描節(jié)點(diǎn)前后差異并同步到事件流。保留策略默認(rèn)保留所有附件以便運(yùn)行結(jié)束后下載。AttachmentService 構(gòu)造時(shí) 讀取環(huán)境變量MAC_AUTO_CLEAN_ATTACHMENTS1/true/yes視為開啟開啟后cleanup_session會(huì)在會(huì)話結(jié)束時(shí)shutil.rmtree刪除attachments/目錄cleanup_session關(guān)閉時(shí)僅打日志保留文件。打包下載zip 下載只讀取不刪除需要額外的 cron/job 做歸檔或清空。5. 大小與安全建議大小限制后端上傳路徑本身未做硬編碼上限save_upload_file逐塊讀取但未限制總量應(yīng)在反向代理層設(shè)置client_max_body_size/max_request_body_size或在自有分支的AttachmentService.save_upload_file中增加校驗(yàn)。工件meta模式的data_uri內(nèi)聯(lián)則有 20MB 代碼上限見 artifacts.py。文件類型MIME 推斷決定MessageBlockTypeimage/audio/video/file見 save_upload_file客戶端可用include_mime過濾事件流。病毒/敏感數(shù)據(jù)建議客戶端上傳前預(yù)掃描也可在保存后觸發(fā)掃描服務(wù)倉(cāng)庫(kù)未內(nèi)置掃描器。權(quán)限附件 API 依賴session_id定位資源。會(huì)話 ID 字符集校驗(yàn)可防路徑穿越見 sessions.py 的正則與安全日志但生產(chǎn)部署仍應(yīng)在代理層或 JWT 內(nèi)部校驗(yàn)調(diào)用者身份防止越權(quán)下載他人會(huì)話的制品。6. 常見問題排查FAQ問題排查步驟上傳 413 Payload Too Large調(diào)高反向代理或 FastAPI 的client_max_size確認(rèn)磁盤配額下載鏈接 404檢查session_id拼寫僅允許字母/數(shù)字/_-確認(rèn)會(huì)話目錄未被清理download_session 對(duì)目錄不存在直接返回 404工件事件缺失確認(rèn) WebSocket 已連接或用artifact-events長(zhǎng)輪詢并攜帶after游標(biāo)重拉注意事件隊(duì)列僅有 2000 條滑動(dòng)窗口附件未在 Python 節(jié)點(diǎn)可見檢查code_workspace/attachments/是否被MAC_AUTO_CLEAN_ATTACHMENTS清理以及 Python 執(zhí)行上下文中的工作區(qū)根路徑python_workspace_root是否正確7. 客戶端接入模式Web UI優(yōu)先訂閱 WebSocket 的artifact_created或退化為artifact-events長(zhǎng)輪詢wait_seconds最大 60 秒實(shí)時(shí)刷新附件列表節(jié)點(diǎn)成功后提供“下載全部”按鈕直接請(qǐng)求/api/sessions/{session_id}/download。CLI/自動(dòng)化運(yùn)行結(jié)束后調(diào)用/download拉取整包 zip若只需部分文件先用artifact-events配合include_ext如csv,png與max_size精準(zhǔn)過濾再逐個(gè)以modestreamdownloadtrue下載。測(cè)試環(huán)境用腳本模擬“上傳 → execute 引用 → 輪詢事件 → 下載”全流程提前驗(yàn)證反向代理的 body size 限制與 CORS 配置。8. 延伸閱讀英文原文Attachment Artifact API Guide中文版附件與工件 API 指南核心實(shí)現(xiàn)AttachmentStore、AttachmentService、上傳路由、工件路由、會(huì)話下載路由、事件隊(duì)列、工作區(qū)鉤子【免費(fèi)下載鏈接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考