Agent Skills 落地實戰：拒絕“裸奔”，構建確定性與靈活性共存的混合架構

作者 | 仇智慧

策劃 | 李冬梅

隨著 Anthropic 開源 skills 倉庫，"Code Interpreter"（代碼解釋器）模式成為 Agent 開發的熱門方向。許多開發者試圖采取激進路線：賦予 LLM 聯網和 Python 執行權限，讓其現場編寫代碼來解決一切問題。但在構建企業級“智能文檔分析 Agent”的實踐中，我們發現這種“全托管”模式在穩定性、安全性和可控性上存在巨大隱患。本文將分享我們如何摒棄激進路線，采用Java (確定性 ETL) + DSL 封裝式 Skills + 實時渲染的混合架構，在保留 LLM 靈活性的同時，確保系統的工業級穩定性。

背景：當文檔分析遇到“復雜生成”

在我們的“文檔處理 Agent”項目中，基礎的問答功能（RAG）已經解決得很好。但隨著用戶需求升級，我們面臨了新的挑戰：

用戶場景：

“這是 2024 和 2025 年的兩份經營數據報表，請對比 DAU 和營收的同比增長率，并生成一個 Excel 表格給我。另外，把總結報告導出為 PDF?！?/blockquote>

這類需求包含兩個特征：

• 邏輯計算：需要精確算術（LLM 弱項）。

• 文件 IO：需要生成物理文件（LLM 無法直接做到）。

引入 Skills（讓 LLM 調用 Python 代碼）似乎是唯一解。但在具體落地時，我們走了一段彎路。

彎路：激進的“純 Skills”路線

起初，我們參考了開源社區做法，采用了完全的 Code Interpreter 模式。我們將requests、pandas、reportlab等庫的權限全部開放給 LLM，并在 Prompt 中告訴它：“你是一個 Python 專家，請自己寫代碼解決所有問題?！?/p>

這種“裸奔”模式在生產環境中遭遇了三次暴擊：

• 輸入端不可控：LLM 對非結構化數據（如無后綴 URL、加密 PDF）的處理極其脆弱，經常陷入報錯死循環。

• 輸出端崩壞：讓 LLM 從零繪制 PDF/Word 是災難。經常出現中文亂碼、表格對不齊、使用了過期的庫 API 等問題。

• 安全黑洞：數據流完全在沙箱內閉環，Java 主程序失去了對內容的控制權，無法攔截敏感詞或違規數據。

變革：Java 主控 +

DSL Skills 的混合架構

為了解決上述問題，我們重構了架構。核心思想是：收回 LLM 的“底層操作權”，只保留其“邏輯調度權”。

我們制定了新的架構分工：Java負責確定性的數據流轉與安檢，LLM負責意圖理解與代碼組裝，Python 沙箱負責在受控環境下執行具體計算。

架構設計概覽

我們將系統重新劃分為四個邏輯層級：

• ETL 層 (Java)：負責下載、MIME 識別、OCR、敏感詞檢測。這是“確定性管道”。

• Brain 層 (LLM)：負責閱讀純文本，進行邏輯推理，并生成調用代碼。

• Skills 層 (Python Sandbox)：提供高度封裝的 SDK（DSL），而非裸庫。

• Delivery 層 (Java)：負責將 Markdown/HTML 實時渲染為 PDF/Word。

輸入側：回歸 Java 流水線 (ETL)

我們不再讓 LLM 去下載和解析文件。所有輸入文件，先經過 Java 的DocPipeline。利用 Apache Tika 進行精準解析，并立即進行敏感詞檢測和文本截斷。這一步保證了喂給 LLM 的數據是干凈、安全、標準化的純文本。

3.3 中間層：DSL 封裝模式 (The Wrapper Pattern)

這是我們對 Skills 實踐最大的改進。我們禁止LLM 直接寫import pandas進行底層操作，而是預置了一套高度封裝的 DSL。

Python 端封裝 (excel_tool.py)：

        return f"Error: {str(e)}"

Skill 說明書 (SKILL.md)：

我們在 Prompt 中通過“接口契約”強行約束 LLM 的行為，明確了何時該寫代碼，何時該純輸出文本。

<< >>

# File Generation Skill (Standardized) 你擁有生成專業格式文件（Excel, Word, PDF）的能力。 沙箱中已預裝了封裝好的 `excel_tool` 庫。 ** 核心決策樹 **： 1. 如果是 ** 統計數據 / 表格 ** -> 必須生成 **Excel** -> ** 寫 Python 代碼 **。 2. 如果是 ** 分析報告 / 文檔 ** -> 必須生成 **Word/PDF** -> ** 禁止寫代碼 **，走渲染路徑。 #### 場景 1：生成 Excel (.xlsx) ** 規則 **：禁止使用 `pandas` 底層 API，必須調用封裝函數。 ** 數據結構 **：必須是【字典列表】，每個字典代表一行。 **Python 調用示例 **： ```python import excel_tool # 1. 準備數據 (從文檔中提取) data = [     {'年份': '2024', 'DAU': 1000, '營收': '500 萬'},     {'年份': '2025', 'DAU': 1500, '營收': '800 萬'} ] # 2. 調用封裝函數 (自動處理樣式、列寬) excel_tool.create_excel(data, filename='analysis.xlsx')

輸出側：渲染與交付的分離

對于不同類型的文件，我們采取了截然不同的交付策略：

1. Excel（強結構化）：走Skills 路線。LLM 組裝數據 -> 調用excel_tool-> 沙箱生成物理文件。

2. Word/PDF（富文本）：走渲染路線。嚴禁 LLM 寫代碼生成。

   1. LLM 只輸出高質量的Markdown并在末尾打上<< >> 標簽。

   2. Java 后端攔截該標簽，利用OpenHTMLtoPDF或Pandoc將 Markdown實時轉換為精美的 PDF/Word。

硬核代碼實現 (Spring AI)

以下是我們在 Spring AI 體系下實現這套混合架構的關鍵邏輯。

動態技能注入 (SkillManager)

我們實現了一個SkillManager，支持按需加載技能。為了提升性能，我們設計了 Session 級的“防抖機制”，確保同一個會話中只需上傳一次 Python 腳本，避免重復 IO。

}

業務調度與意圖分流 (Handler)

串聯 Java ETL、LLM 推理和最終的交付分流。


}

攔截與交付 (SandboxTools)

在 Tool 執行層做最后一道防線：輸出內容的二次安檢。

}

總 結

Skills 技術讓 LLM 擁有了“手”，但這雙手必須戴上“手套”。

通過這次架構演進，我們得出的核心經驗是：

• 不要高估 LLM 的 Coding 能力：它是一個優秀的邏輯推理引擎，但在工程細節（排版、庫依賴、環境配置）上非常糟糕。DSL 封裝是必須的。

• 不要丟掉 Java 的確定性：解析、下載、格式轉換、安全檢查，這些傳統代碼擅長的領域，不要交給概率性的 LLM 去做。

• 架構分層：

• • Input: Java (Standardization & Security)

  • Thinking: LLM (Reasoning)

  • Action:Python (Calculation via DSL)

  • Output: Java (Rendering & Delivery)

這種混合架構，既保留了 Agent 處理復雜動態需求的能力（如自定義計算漲跌幅），又守住了企業級應用對穩定性與合規性的底線。

會議推薦

InfoQ 2026 全年會議規劃已上線！從 AI Infra 到 Agentic AI，從 AI 工程化到產業落地，從技術前沿到行業應用，全面覆蓋 AI 與軟件開發核心賽道！集結全球技術先鋒，拆解真實生產案例、深挖技術與產業落地痛點，探索前沿領域、聚焦產業賦能，獲取實戰落地方案與前瞻產業洞察，高效實現技術價值轉化。把握行業變革關鍵節點，搶占 2026 智能升級發展先機！

今日薦文

你也「在看」嗎？