作者 | 仇智慧

策劃 | 李冬梅

隨著 Anthropic 開源 skills 倉(cāng)庫(kù)，"Code Interpreter"（代碼解釋器）模式成為 Agent 開發(fā)的熱門方向。許多開發(fā)者試圖采取激進(jìn)路線：賦予 LLM 聯(lián)網(wǎng)和 Python 執(zhí)行權(quán)限，讓其現(xiàn)場(chǎng)編寫代碼來解決一切問題。但在構(gòu)建企業(yè)級(jí)“智能文檔分析 Agent”的實(shí)踐中，我們發(fā)現(xiàn)這種“全托管”模式在穩(wěn)定性、安全性和可控性上存在巨大隱患。本文將分享我們?nèi)绾无饤壖みM(jìn)路線，采用Java (確定性 ETL) + DSL 封裝式 Skills + 實(shí)時(shí)渲染的混合架構(gòu)，在保留 LLM 靈活性的同時(shí)，確保系統(tǒng)的工業(yè)級(jí)穩(wěn)定性。

背景：當(dāng)文檔分析遇到“復(fù)雜生成”

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

用戶場(chǎng)景：

“這是 2024 和 2025 年的兩份經(jīng)營(yíng)數(shù)據(jù)報(bào)表，請(qǐng)對(duì)比 DAU 和營(yíng)收的同比增長(zhǎng)率，并生成一個(gè) Excel 表格給我。另外，把總結(jié)報(bào)告導(dǎo)出為 PDF?！?/blockquote>

這類需求包含兩個(gè)特征：

• 邏輯計(jì)算：需要精確算術(shù)（LLM 弱項(xiàng)）。

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

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

彎路：激進(jìn)的“純 Skills”路線

起初，我們參考了開源社區(qū)做法，采用了完全的 Code Interpreter 模式。我們將requests、pandas、reportlab等庫(kù)的權(quán)限全部開放給 LLM，并在 Prompt 中告訴它：“你是一個(gè) Python 專家，請(qǐng)自己寫代碼解決所有問題。”

這種“裸奔”模式在生產(chǎn)環(huán)境中遭遇了三次暴擊：

• 輸入端不可控：LLM 對(duì)非結(jié)構(gòu)化數(shù)據(jù)（如無后綴 URL、加密 PDF）的處理極其脆弱，經(jīng)常陷入報(bào)錯(cuò)死循環(huán)。

• 輸出端崩壞：讓 LLM 從零繪制 PDF/Word 是災(zāi)難。經(jīng)常出現(xiàn)中文亂碼、表格對(duì)不齊、使用了過期的庫(kù) API 等問題。

• 安全黑洞：數(shù)據(jù)流完全在沙箱內(nèi)閉環(huán)，Java 主程序失去了對(duì)內(nèi)容的控制權(quán)，無法攔截敏感詞或違規(guī)數(shù)據(jù)。

變革：Java 主控 +

DSL Skills 的混合架構(gòu)

為了解決上述問題，我們重構(gòu)了架構(gòu)。核心思想是：收回 LLM 的“底層操作權(quán)”，只保留其“邏輯調(diào)度權(quán)”。

我們制定了新的架構(gòu)分工：Java負(fù)責(zé)確定性的數(shù)據(jù)流轉(zhuǎn)與安檢，LLM負(fù)責(zé)意圖理解與代碼組裝，Python 沙箱負(fù)責(zé)在受控環(huán)境下執(zhí)行具體計(jì)算。

架構(gòu)設(shè)計(jì)概覽

我們將系統(tǒng)重新劃分為四個(gè)邏輯層級(jí)：

• ETL 層 (Java)：負(fù)責(zé)下載、MIME 識(shí)別、OCR、敏感詞檢測(cè)。這是“確定性管道”。

• Brain 層 (LLM)：負(fù)責(zé)閱讀純文本，進(jìn)行邏輯推理，并生成調(diào)用代碼。

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

• Delivery 層 (Java)：負(fù)責(zé)將 Markdown/HTML 實(shí)時(shí)渲染為 PDF/Word。

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

我們不再讓 LLM 去下載和解析文件。所有輸入文件，先經(jīng)過 Java 的DocPipeline。利用 Apache Tika 進(jìn)行精準(zhǔn)解析，并立即進(jìn)行敏感詞檢測(cè)和文本截?cái)?/strong>。這一步保證了喂給 LLM 的數(shù)據(jù)是干凈、安全、標(biāo)準(zhǔn)化的純文本。

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

這是我們對(duì) Skills 實(shí)踐最大的改進(jìn)。我們禁止LLM 直接寫import pandas進(jìn)行底層操作，而是預(yù)置了一套高度封裝的 DSL。

Python 端封裝 (excel_tool.py)：

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

Skill 說明書 (SKILL.md)：

我們?cè)?Prompt 中通過“接口契約”強(qiáng)行約束 LLM 的行為，明確了何時(shí)該寫代碼，何時(shí)該純輸出文本。

<< >>

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

輸出側(cè)：渲染與交付的分離

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

1. Excel（強(qiáng)結(jié)構(gòu)化）：走Skills 路線。LLM 組裝數(shù)據(jù) -> 調(diào)用excel_tool-> 沙箱生成物理文件。

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

   1. LLM 只輸出高質(zhì)量的Markdown并在末尾打上<< >> 標(biāo)簽。

   2. Java 后端攔截該標(biāo)簽，利用OpenHTMLtoPDF或Pandoc將 Markdown實(shí)時(shí)轉(zhuǎn)換為精美的 PDF/Word。

硬核代碼實(shí)現(xiàn) (Spring AI)

以下是我們?cè)?Spring AI 體系下實(shí)現(xiàn)這套混合架構(gòu)的關(guān)鍵邏輯。

動(dòng)態(tài)技能注入 (SkillManager)

我們實(shí)現(xiàn)了一個(gè)SkillManager，支持按需加載技能。為了提升性能，我們?cè)O(shè)計(jì)了 Session 級(jí)的“防抖機(jī)制”，確保同一個(gè)會(huì)話中只需上傳一次 Python 腳本，避免重復(fù) IO。

}

業(yè)務(wù)調(diào)度與意圖分流 (Handler)

串聯(lián) Java ETL、LLM 推理和最終的交付分流。


}

攔截與交付 (SandboxTools)

在 Tool 執(zhí)行層做最后一道防線：輸出內(nèi)容的二次安檢。

}

總 結(jié)

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

通過這次架構(gòu)演進(jìn)，我們得出的核心經(jīng)驗(yàn)是：

• 不要高估 LLM 的 Coding 能力：它是一個(gè)優(yōu)秀的邏輯推理引擎，但在工程細(xì)節(jié)（排版、庫(kù)依賴、環(huán)境配置）上非常糟糕。DSL 封裝是必須的。

• 不要丟掉 Java 的確定性：解析、下載、格式轉(zhuǎn)換、安全檢查，這些傳統(tǒng)代碼擅長(zhǎng)的領(lǐng)域，不要交給概率性的 LLM 去做。

• 架構(gòu)分層：

• • Input: Java (Standardization & Security)

  • Thinking: LLM (Reasoning)

  • Action:Python (Calculation via DSL)

  • Output: Java (Rendering & Delivery)

這種混合架構(gòu)，既保留了 Agent 處理復(fù)雜動(dòng)態(tài)需求的能力（如自定義計(jì)算漲跌幅），又守住了企業(yè)級(jí)應(yīng)用對(duì)穩(wěn)定性與合規(guī)性的底線。

會(huì)議推薦

InfoQ 2026 全年會(huì)議規(guī)劃已上線！從 AI Infra 到 Agentic AI，從 AI 工程化到產(chǎn)業(yè)落地，從技術(shù)前沿到行業(yè)應(yīng)用，全面覆蓋 AI 與軟件開發(fā)核心賽道！集結(jié)全球技術(shù)先鋒，拆解真實(shí)生產(chǎn)案例、深挖技術(shù)與產(chǎn)業(yè)落地痛點(diǎn)，探索前沿領(lǐng)域、聚焦產(chǎn)業(yè)賦能，獲取實(shí)戰(zhàn)落地方案與前瞻產(chǎn)業(yè)洞察，高效實(shí)現(xiàn)技術(shù)價(jià)值轉(zhuǎn)化。把握行業(yè)變革關(guān)鍵節(jié)點(diǎn)，搶占 2026 智能升級(jí)發(fā)展先機(jī)！

今日薦文

你也「在看」嗎？