Agent Skills 落地实战：拒绝“裸奔”，构建确定性与灵活性共存的混合架构
来源: InfoQ - AI＆大模型
摘要
随着 Anthropic 开源 skills 仓库，"Code Interpreter"（代码解释器）模式成为 Agent 开发的热门方向。许多开发者试图采取激进路线：赋予 LLM 联网和 Python 执行权限，让其现场编写代码来解决一切问题。但在构建企业级“智能文档分析 Agent”的实践中，我们发现这种“全托管”模式在稳定性、安全性和可控性上存在巨大隐患。本文将分享我们如何摒弃激进路线，采用 Java (确定性 ETL) + DSL 封装式 Skills + 实时渲染 的混合架构，在保留 LLM 灵活性的同时，确保系统的工业级稳定性。
一、 背景：当文档分析遇到“复杂生成”
在我们的“文档处理 Agent”项目中，基础的问答功能（RAG）已经解决得很好。但随着用户需求升级，我们面临了新的挑战：
用户场景：
“这是 2024 和 2025 年的两份经营数据报表，请对比 DAU 和营收的同比增长率，并生成一个 Excel 表格给我。另外，把总结报告导出为 PDF。”
这类需求包含两个特征：
逻辑计算：需要精确算术（LLM 弱项）。
文件 IO：需要生成物理文件（LLM 无法直接做到）。
引入 Skills（让 LLM 调用 Python 代码）似乎是唯一解。但在具体落地时，我们走了一段弯路。
二、 弯路：激进的“纯 Skills”路线
起初，我们参考了开源社区做法，采用了 完全的 Code Interpreter 模式。我们将 requests、pandas、reportlab 等库的权限全部开放给 LLM，并在 Prompt 中告诉它：“你是一个 Python 专家，请自己写代码解决所有问题。”
这种“裸奔”模式在生产环境中遭遇了三次暴击：
输入端不可控：LLM 对非结构化数据（如无后缀 URL、加密 PDF）的处理极其脆弱，经常陷入报错死循环。
输出端崩坏：让 LLM 从零绘制 PDF/Word 是灾难。经常出现中文乱码、表格对不齐、使用了过期的库 API 等问题。
安全黑洞：数据流完全在沙箱内闭环，Java 主程序失去了对内容的控制权，无法拦截敏感词或违规数据。
三、 变革：Java 主控 + DSL Skills 的混合架构
为了解决上述问题，我们重构了架构。核心思想是：收回 LLM 的“底层操作权”，只保留其“逻辑调度权”。
我们制定了新的架构分工：Java 负责确定性的数据流转与安检，LLM 负责意图理解与代码组装，Python 沙箱 负责在受控环境下执行具体计算。
3.1 架构设计概览
我们将系统重新划分为四个逻辑层级：
ETL 层 (Java)：负责下载、MIME 识别、OCR、敏感词检测。这是“确定性管道”。
Brain 层 (LLM)：负责阅读纯文本，进行逻辑推理，并生成调用代码。
Skills 层 (Python Sandbox)：提供高度封装的 SDK（DSL），而非裸库。
Delivery 层 (Java)：负责将 Markdown/HTML 实时渲染为 PDF/Word。
3.2 输入侧：回归 Java 流水线 (ETL)
我们不再让 LLM 去下载和解析文件。所有输入文件，先经过 Java 的 DocPipeline。利用 Apache Tika 进行精准解析，并立即进行敏感词检测和文本截断。这一步保证了喂给 LLM 的数据是干净、安全、标准化的纯文本。
3.3 中间层：DSL 封装模式 (The Wrapper Pattern)
这是我们对 Skills 实践最大的改进。我们禁止 LLM 直接写 import pandas 进行底层操作，而是预置了一套高度封装的 DSL。
Python 端封装 (excel_tool.py)：
import pandas as pd
import os
def create_excel(data_list, filename="report.xlsx", output_dir="/workspace"):
try:
df = pd.DataFrame(data_list)
save_path = os.path.join(output_dir, filename)
# 【封装价值体现】自动处理格式、列宽、引擎兼容性，屏蔽 LLM 的幻觉风险
with pd.ExcelWriter(save_path, engine='openpyxl') as writer:
df.to_excel(writer, index=False, sheet_name='Sheet1')
# 自动调整列宽 (LLM 很难写对的工程细节)
worksheet = writer.sheets['Sheet1']
for idx, col in enumerate(df.columns):
max_len = max(df[col].astype(str).map(len).max(), len(str(col))) + 2
worksheet.column_dimensions[chr(65 + idx)].width = min(max_len, 50)
return save_path
except Exception as e:
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')
```
---
### 场景 2：生成 Word / PDF (.docx / .pdf)
**规则**：**严禁编写 Python 代码**（如 `reportlab` 或 `python-docx`）。
**执行动作**：
1. 请直接输出内容丰富、排版精美的 **Markdown** 文本。
2. 在 Markdown 的**最后一行**，务必添加对应的动作标签，系统会自动将其渲染为文件。
**输出示例**：
# 2024 年度经营分析报告
## 一、 数据概览
本季度营收同比增长 20%...
| 指标 | Q1 | Q2 |
| :--- | :--- | :--- |
| DAU | 100w | 120w |
... (此处省略 2000 字内容) ...
<<>>
3.4 输出侧：渲染与交付的分离
对于不同类型的文件，我们采取了截然不同的交付策略：
Excel（强结构化）：走 Skills 路线。LLM 组装数据 -> 调用 excel_tool -> 沙箱生成物理文件。
Word/PDF（富文本）：走 渲染路线。严禁 LLM 写代码生成。
LLM 只输出高质量的 Markdown 并在末尾打上 <<>> 标签。
Java 后端拦截该标签，利用 OpenHTMLtoPDF 或 Pandoc 将 Markdown 实时转换 为精美的 PDF/Word。
四、 硬核代码实现 (Spring AI)
以下是我们在 Spring AI 体系下实现这套混合架构的关键逻辑。
4.1 动态技能注入 (SkillManager)
我们实现了一个 SkillManager，支持按需加载技能。为了提升性能，我们设计了 Session 级的“防抖机制”，确保同一个会话中只需上传一次 Python 脚本，避免重复 IO。
@Service
public class SkillManager {
// 缓存技能脚本: 技能名 -> { 文件路径 -> 内容 }
private final Map scripts = skillScripts.get(skillName);
if (scripts != null) {
scripts.forEach((path, content) ->
sandboxService.uploadFile(sessionId, path, content)
);
}
}
injectedSessions.add(sessionId);
}
// ... 省略加载 Resource 的代码 ...
}
neededSkills) {
// 1. 防抖检查：如果该 Session 已注入，直接跳过，避免重复 IO
if (injectedSessions.contains(sessionId)) return;
// 2. 注入 Python 包结构 (__init__.py)
sandboxService.uploadFile(sessionId, "/workspace/skills/__init__.py", "");
// 3. 批量上传该技能所需的 DSL 脚本
for (String skillName : neededSkills) {
Map injectedSessions = ConcurrentHashMap.newKeySet();
/**
* 核心逻辑：根据需要的技能列表，动态注入脚本到沙箱
*/
public void injectToSandbox(String sessionId, List> skillScripts = new ConcurrentHashMap<>();
// 防止重复注入的防抖 Set
private final Set4.2 业务调度与意图分流 (Handler)
串联 Java ETL、LLM 推理和最终的交付分流。
@Service
public class DocumentAnalysisRequestHandler {
public Flowable>>")) {
// Java 侧实时渲染：Markdown -> PDF
// 优势：完美控制字体和样式，避免 Python 生成乱码
String pdfPath = docConverterService.convertAndSave(text, "pdf");
return Single.just(new AgentOutput(pdfPath, OutputType.FILE));
}
// 分支 C：普通文本
return Single.just(new AgentOutput(text, OutputType.TEXT));
}
}
>>
if (text.contains("<< rawChunks) {
String text = String.join("", rawChunks);
// 分支 A：检测到 Python 生成了 Excel (Skills 产物)
// 格式：[FILE_GENERATED: /workspace/report.xlsx]
if (FILE_GENERATED_PATTERN.matcher(text).find()) {
String path = extractPath(text);
return Single.just(new AgentOutput(path, OutputType.FILE));
}
// 分支 B：检测到转换指令 (渲染产物)
// 格式：<< handlePostGenerationAction(List agentFlow = chatClient.prompt()
.system(prompt)
.user(req.getUserInstruction())
.toolContext(Map.of("projectId", req.getSessionId()))
.stream()
.content();
// 4. 【结果分流】
return agentFlow
.toList() // 收集完整回复
.flatMap(this::handlePostGenerationAction);
}
/**
* 核心分流逻辑：决定是返回沙箱文件(Excel) 还是 调用Java渲染(PDF)
*/
private Single neededSkills = List.of("file_generation");
skillManager.injectToSandbox(req.getSessionId(), neededSkills);
// 3. 【LLM 执行】Context Stuffing
String prompt = buildPrompt(parsedDocs, skillManager.getPrompts(neededSkills));
// 调用 LLM，挂载 ToolContext 以实现多租户隔离
Flowable parsedDocs = etlPipeline.process(req.getUrls());
// 2. 【技能注入】
List processStreamingRequest(Request req) {
// 1. 【Java ETL】确定性解析与安检
// 无论 URL 还是文件，先转为纯文本，并做敏感词过滤
List
4.3 拦截与交付 (SandboxTools)
在 Tool 执行层做最后一道防线：输出内容的二次安检。
@Component
public class SandboxTools {
@Tool(name = "execute_command", description = "在沙箱中执行 Shell 命令")
public String executeCommand(ExecuteCommandRequest req, ToolContext context) {
String projectId = (String) context.getContext().get("projectId");
try {
// 1. 执行 Python 脚本
Map result = sandboxMcpService.executeCommand(projectId, req.command());
String stdout = (String) result.get("stdout");
// 2. 【关键】输出侧安检
// 防止 LLM 通过代码计算出违规内容，绕过输入侧检查
if (banwordService.hasBanWords(stdout)) {
log.warn("Banword detected in sandbox output!");
throw new BanwordException("敏感内容阻断");
}
// 3. 超长截断 (防止 LLM 上下文爆炸)
if (stdout.length() > MAX_TEXT_LENGTH) {
return stdout.substring(0, MAX_TEXT_LENGTH) + "\n[SYSTEM: TRUNCATED]";
}
return stdout;
} catch (Exception e) {
return "Execution Error: " + e.getMessage();
}
}
}
五、 总结
Skills 技术让 LLM 拥有了“手”，但这双手必须戴上“手套”。
通过这次架构演进，我们得出的核心经验是：
不要高估 LLM 的 Coding 能力：它是一个优秀的逻辑推理引擎，但在工程细节（排版、库依赖、环境配置）上非常糟糕。DSL 封装是必须的。
不要丢掉 Java 的确定性：解析、下载、格式转换、安全检查，这些传统代码擅长的领域，不要交给概率性的 LLM 去做。
架构分层：
Input: Java (Standardization & Security)
Thinking: LLM (Reasoning)
Action: Python (Calculation via DSL)
Output: Java (Rendering & Delivery)
这种混合架构，既保留了 Agent 处理复杂动态需求的能力（如自定义计算涨跌幅），又守住了企业级应用对稳定性与合规性的底线。