為 AI 應用程式添加程式碼解釋器的方式，是將模型請求的程式碼執行路由到一個隔離的沙箱中，該沙箱具備限定範圍的檔案、明確的套件政策、資源與時間限制、擷取的輸出，以及應用程式端的審查機制，在結果顯示或儲存之前先進行檢查。模型可以決定何時使用程式碼有用，但你的應用程式應掌握執行邊界：僅上傳任務所需的檔案、建立或重複使用短暫的沙箱工作階段、在嚴格限制下執行 Python、擷取 stdout、stderr、產生的檔案與日誌、將結構化結果回傳給模型，並在工作流程完成時清理工作階段。
程式碼解釋器為 AI 應用程式帶來了什麼
程式碼解釋器將語言模型從純文字助理轉變為能使用工具、執行計算、轉換檔案、檢查資料、產生圖表與產出可審查成品（artifacts）的應用程式。與其要求模型僅從提示詞中推理試算表內容，應用程式可以讓模型撰寫 Python、對上傳的檔案執行、檢查輸出，並解釋結果。
有用的模式不是「讓模型執行任何東西」。有用的模式是受控的執行。你的應用程式接受使用者任務，讓模型請求工具呼叫（例如 run_python），然後在沙箱內執行該請求，而非在主應用程式流程中執行。沙箱成為臨時檔案、套件安裝、腳本、圖表與日誌的工作台。
程式碼解釋器功能特別適用於：
- CSV、Excel、JSON 與日誌分析
- 從上傳資料產生圖表
- 格式轉換與資料清理
- 需要精確計算的數學與模擬任務
- 需要先測試再讓模型解釋的程式碼片段
- 多步驟代理工作流程，其中一個步驟的輸出成為下一個步驟的輸入
它們不適合需要不受限制的生產環境憑證、長期存取私人系統，或無使用者可見稽核軌跡的靜默執行任務。如果結果可能影響金錢、基礎設施、安全性或存取控制，請在任何副作用離開沙箱之前加入審查關卡。
參考架構
一個實用的程式碼解釋器架構包含五個部分：
| 層級 | 責任 | 常見設計選擇 |
|---|---|---|
| 使用者介面 | 上傳檔案、顯示進度、展示成品、請求核准 | 將上傳的檔案限定在當前對話或專案範圍內 |
| 應用程式伺服器 | 驗證使用者身份、執行政策、建立沙箱工作階段、儲存日誌 | 切勿將原始沙箱憑證暴露給瀏覽器 |
| 模型編排 | 決定何時呼叫程式碼工具並總結結果 | 使用結構化的工具呼叫，而非解析自由文字 |
| 沙箱執行環境 | 執行 Python、存放臨時檔案、安裝允許的套件 | 在資源、超時與清理控制下執行 |
| 成品儲存庫 | 保存已核准的輸出，例如圖表、CSV、報告與日誌 | 僅儲存應用程式或使用者已接受的輸出 |
模型不應直接控制基礎設施。它應請求工具呼叫。你的應用程式決定該工具呼叫是否允許、哪些檔案被附加、它可執行多長時間、哪些套件可用，以及哪些輸出被回傳。
這種分離讓模型保持實用，同時不讓它成為安全邊界。
實現流程
一個穩健的實現流程在執行任何程式碼之前就開始了。
1. 接受使用者任務與檔案
當使用者上傳檔案時，將其儲存在應用程式層級的檔案記錄中，包含擁有者、工作區、內容類型、大小與保留政策。不要立即將使用者帳戶中的每個檔案都暴露給解釋器。沙箱應僅接收當前任務所需的檔案。
例如，使用者可能要求：
「分析這個 CSV，找出主要的營收驅動因素，然後回傳一張圖表加上簡短說明。」
你的應用程式可以將上傳的 CSV 附加到模型的下一個回合作為可用檔案，但實際的檔案位元組應僅在程式碼執行被核准時才移入沙箱。
2. 讓模型請求工具呼叫
定義一個狹義的工具表面。一個典型的第一版只需要少數幾個工具：
{
"name": "run_python",
"arguments": {
"code": "import pandas as pd\n...",
"input_files": ["sales.csv"],
"expected_outputs": ["summary.json", "revenue_chart.png"],
"timeout_seconds": 30
}
}
保持 schema 明確。模型應宣告程式碼、輸入檔案、預期輸出以及超時請求。應用程式可以縮短超時時間、拒絕未知檔案，或封鎖與政策衝突的命令。
3. 建立或重複使用沙箱工作階段
對於一次性助手回應，建立一個全新的沙箱工作階段，上傳輸入檔案，執行程式碼，收集結果，然後終止工作階段。對於類似筆記本的使用者體驗，為當前對話保持一個工作階段存活，以便後續的單元可以重複使用先前的變數與檔案。
短暫的工作階段更容易推理。有狀態的工作階段對於分析任務更符合人體工學。審慎選擇，並在使用者面前顯示狀態的存在。
4. 執行 Python 並擷取結果
透過沙箱執行 API 或你自己的沙箱內部 worker 來執行程式碼。擷取結構化的執行輸出：
{
"status": "success",
"stdout": "Loaded 12,448 rows\n",
"stderr": "",
"artifacts": [
{
"path": "revenue_chart.png",
"type": "image/png",
"size_bytes": 84231
},
{
"path": "summary.json",
"type": "application/json",
"size_bytes": 1260
}
],
"duration_ms": 1840
}
將此結構化結果回傳給模型。模型隨後可以解釋發生了什麼、引用產生的檔案，並詢問使用者是否要再進行一次。
5. 將結果回傳給使用者
除非發生錯誤，否則不要強迫使用者閱讀原始日誌。一個良好的介面會顯示答案、產生的圖表或檔案，以及一個小型的揭露說明表示已執行程式碼。提供一個可展開的執行日誌供審查。
對於失敗的執行，顯示簡潔的錯誤訊息，並讓模型修正程式碼。除非使用者正在除錯，否則避免將冗長的追蹤資訊傾倒到主要對話中。
處理檔案、輸出與產生的成品
檔案處理是許多程式碼解釋器專案變得混亂的地方。將輸入與輸出視為獨立的物件。
輸入檔案應以穩定、已清理的路徑複製到沙箱中。避免保留使用者提供的包含空格、shell 字元或巢狀目錄的路徑名稱。在應用程式狀態中維護一個從顯示名稱到沙箱路徑的對應。
產生的檔案應在成為可下載的成品之前進行掃描與分類。圖表圖片、清理過的 CSV、JSON 摘要或 PDF 報告可能可以直接安全地呈現。產生的腳本、可執行檔或壓縮檔則需要更嚴格的處理。
對於圖表生成，要求模型明確地儲存圖片檔案，而不是僅依賴行內顯示。對於資料分析，要求同時產生機器可讀的摘要檔案與自然語言解釋。這能為你的應用程式提供穩定的內容來驗證與儲存。
一個實用的成品政策如下所示：
| 成品類型 | 預設處理方式 |
|---|---|
.png、.jpg、.webp、.svg 圖表 |
在經過大小與類型檢查後於 UI 中預覽 |
.csv、.json、.xlsx 資料輸出 |
提供下載並總結變更 |
.txt、.md、.pdf 報告 |
根據大小預覽或下載 |
.py、.sh、二進位檔、壓縮檔 |
不自動執行或開啟；需明確審查 |
如果你的應用程式支援持久化專案，請將已接受的成品儲存在沙箱之外。沙箱應保持可拋棄性。
設定套件與網路政策
大多數程式碼解釋器工作流程需要 pandas、NumPy、matplotlib、seaborn、scikit-learn 或 openpyxl 等套件。問題在於這些套件是預先安裝、按需安裝，還是建置到自訂沙箱模板中。
預先安裝的套件能保持執行可預測性。按需安裝具有靈活性，但可能減慢任務速度並引入相依性漂移。一旦你了解常見的工作負載，自訂模板通常是最佳的生產路徑。
在啟動前設定套件政策：
- 哪些套件始終可用
- 模型是否可以請求安裝套件
- 安裝是否可以存取公共套件索引
- 是否需要版本鎖定
- 安裝可以執行多長時間
- 是否允許編譯或原生套件
網路政策同樣重要。許多資料任務在上傳檔案後不需要網際網路存取。如果工作流程確實需要外部 API，請透過應用程式核准的工具路由憑證，而不是將廣泛的祕密傾倒到沙箱中。模型不應預設接收不受限制的環境變數。
應用限制、日誌、清理與審查
程式碼解釋器是生產環境功能，而非示範用的單元執行器。從一開始就對其施加限制。
最低限度的控制應包括：
- 每個單元或工具呼叫的最大執行時間
- stdout 與 stderr 的最大輸出大小
- 最大成品大小與檔案數量
- 適合任務的 CPU 與記憶體限制
- 允許預覽與下載的檔案副檔名
- 每個使用者與每個工作區的並發限制
- 臨時工作階段與檔案的清理規則
日誌應回答三個問題：誰請求執行、執行了什麼程式碼、產生了什麼輸出。儲存足夠的資訊以除錯與稽核工作流程，但避免保留私人上傳資料超過產品政策要求的時間。
人工或使用者審查是最終的控制手段。對於低風險分析，審查可能意味著使用者在下載圖表前先看到它。對於可以更新工單、寫入資料庫或呼叫外部 API 的代理工作流程，審查應在副作用發生之前進行，而非之後。
Novita Agent Sandbox 的定位
Novita Agent Sandbox 專為需要隔離執行環境的 AI 代理而設計，用於程式碼執行、瀏覽器工作流程、電腦使用風格任務、評估、強化學習環境以及長時間運行的任務。對於程式碼解釋器功能而言，這意味著沙箱可以作為執行層，而你的應用程式仍負責使用者驗證、模型編排、檔案政策、審查以及產品特定的保留。
Novita 的沙箱文件包含檔案系統工作流程，用於在沙箱中讀取、寫入、上傳、下載與監控檔案。這些能力直接對應於程式碼解釋器的需求：將使用者檔案移入執行環境，讓程式碼產生圖表或轉換後的資料，然後將選定的輸出帶回應用程式。請參閱 Novita 沙箱檔案系統文件 以取得當前檔案操作的概述。
如果你的解釋器成長為超越簡單的 Python 執行器，自訂沙箱模板可以幫助標準化相依性與執行環境設定。當每個工作階段都需要相同的分析堆疊、內部命令列工具或專案特定的函式庫時，這就很有用。從一個小的允許套件集合開始，然後在工作負載穩定後將重複的設定移入模板。
將 Novita 特定的整合決策與通用架構分開。你的程式碼解釋器仍然需要應用程式層級的政策，用於檔案可見性、套件安裝、網路存取、日誌保留與審查。沙箱提供了受控的執行環境；你的產品定義了如何使用該執行環境。
評估檢查清單
在發布之前，使用真實的工作流程與對抗性提示來測試該功能。
| 問題 | 需要驗證的內容 |
|---|---|
| 使用者能否上傳正確的檔案？ | 檔案大小、類型檢查、擁有者檢查以及清晰的錯誤訊息 |
| 模型能否乾淨地請求執行？ | 結構化的工具呼叫，包含程式碼、輸入、預期輸出與超時 |
| 沙箱是否正確地限定範圍？ | 僅有核准的檔案與環境變數可用 |
| 套件是否可預測？ | 常見套件可運作，被拒絕的套件清楚地失敗，安裝有上限 |
| 輸出是否可用？ | 圖表可渲染、檔案可下載、摘要與產生的成品相符 |
| 失敗是否可恢復？ | 追蹤資訊被擷取、模型可以修正程式碼、使用者看到簡潔的錯誤 |
| 限制是否被強制執行？ | 無限迴圈、巨大輸出、記憶體密集型任務與長時間安裝會被終止 |
| 是否內建審查機制？ | 使用者在重要的副作用發生前可以檢查程式碼、日誌與成品 |
| 清理是否可靠？ | 臨時檔案與工作階段會按時被移除或過期 |
最好的第一個版本通常是狹義的：Python 執行、一個小的套件集合、檔案上傳、圖表與可下載檔案、明確的限制以及一個執行日誌。只有在基本循環可觀察且可靠之後，才添加更廣泛的套件安裝、持久化工作階段、外部 API 存取與代理性的副作用。
結論
程式碼解釋器在模型可以請求執行、但你的應用程式控制沙箱、檔案、限制與審查步驟時效果最佳。從一個狹義的 Python 工具開始，保持輸入與輸出明確，並僅在流程穩定後才進行擴展。
常見問題
添加程式碼解釋器最安全的方式是什麼？
使用隔離的沙箱、限定輸入檔案的範圍、限制執行時間與記憶體，並回傳結構化的輸出，而非原始的 shell 存取。
模型應該控制套件安裝嗎？
僅在你定義的政策範圍內。許多應用程式從一個固定的套件集合開始，並在後續工作負載需要時才添加安裝功能。
所有程式碼解釋器任務都需要網路存取嗎？
不需要。許多分析工作流程在使用者檔案上傳後可以完全離線運作，這使得執行模型更簡單。
使用者應該在執行後看到什麼？
結果、產生的成品，以及一個簡潔的日誌或錯誤摘要，並提供檢查程式碼或重新執行任務的選項。
