标签 稳定性 下的文章

在数据驱动成为常态的今天，数据采集早已不再是技术门槛问题，而是访问许可问题。随着平台对自动化访问的识别能力不断提升，采集系统能否长期运行，越来越取决于网络行为是否合理。

数据采集代理正是在这种环境下，成为整个系统的关键基础。如果网络层缺乏可信度，即便采集逻辑再完善，也难以持续输出有效数据。

为什么采集失败往往源于网络层

很多采集任务在初期表现良好，但随着规模扩大，访问受限问题频繁出现。这类问题并不一定与采集频率直接相关，而是源于访问来源过于集中或行为模式不自然。
当请求长期来自可识别的网络结构时，平台会逐步建立风险画像。一旦触发阈值，限制便会成为常态。
因此，采集系统的稳定性，首先取决于代理网络是否具备真实用户的行为特征。

数据采集代理的真正作用

代理在数据采集中的价值，并不是隐藏身份，而是让访问行为显得合理。每一次请求，都应当符合目标平台的流量模型，而不是脱离整体环境。
基于真实家庭网络的代理，在这一点上具备天然优势。其访问节奏和分布方式，更容易融入正常用户行为中。
但前提是，这种代理必须被正确管理。无序切换、过度随机，都会破坏行为连贯性，从而引发新的风险。

稳定性带来的长期收益

短期内，通过激进切换策略或许可以获取数据，但这种方式难以长期维持。真正有价值的数据采集，往往需要持续观察和长期积累。
稳定的数据采集代理，可以让系统在较长时间内保持运行状态，从而支持趋势分析和结构化判断。这种能力，本身就是竞争优势。

降低系统维护成本的关键

不稳定的代理环境，会迫使团队不断修复采集系统，封禁、重试、替换资源都会消耗大量时间和成本。
当代理网络本身足够稳定，这些问题就会显著减少。系统可以专注于数据本身，而不是持续应对访问中断。

长期采集能力的未来价值

在数据竞争日益激烈的环境中，谁能持续获取高质量数据，谁就拥有更大的决策优势。
评估数据采集代理时，不应只关注短期表现，而应关注其长期可用性。稳定、真实、可持续，正在成为数据采集代理的核心标准。

摘要

随着 Anthropic 开源 skills 仓库，"Code Interpreter"（代码解释器）模式成为 Agent 开发的热门方向。许多开发者试图采取激进路线：赋予 LLM 联网和 Python 执行权限，让其现场编写代码来解决一切问题。但在构建企业级“智能文档分析 Agent”的实践中，我们发现这种“全托管”模式在稳定性、安全性和可控性上存在巨大隐患。本文将分享我们如何摒弃激进路线，采用 Java (确定性 ETL) + DSL 封装式 Skills + 实时渲染 的混合架构，在保留 LLM 灵活性的同时，确保系统的工业级稳定性。

一、 背景：当文档分析遇到“复杂生成”

在我们的“文档处理 Agent”项目中，基础的问答功能（RAG）已经解决得很好。但随着用户需求升级，我们面临了新的挑战：

用户场景：

“这是 2024 和 2025 年的两份经营数据报表，请对比 DAU 和营收的同比增长率，并生成一个 Excel 表格给我。另外，把总结报告导出为 PDF。”

这类需求包含两个特征：

  1. 逻辑计算：需要精确算术（LLM 弱项）。

  2. 文件 IO：需要生成物理文件（LLM 无法直接做到）。

引入 Skills（让 LLM 调用 Python 代码）似乎是唯一解。但在具体落地时，我们走了一段弯路。

二、 弯路：激进的“纯 Skills”路线

起初，我们参考了开源社区做法，采用了 完全的 Code Interpreter 模式。我们将 requests、pandas、reportlab 等库的权限全部开放给 LLM，并在 Prompt 中告诉它：“你是一个 Python 专家，请自己写代码解决所有问题。”

这种“裸奔”模式在生产环境中遭遇了三次暴击：

  1. 输入端不可控：LLM 对非结构化数据（如无后缀 URL、加密 PDF）的处理极其脆弱，经常陷入报错死循环。

  2. 输出端崩坏：让 LLM 从零绘制 PDF/Word 是灾难。经常出现中文乱码、表格对不齐、使用了过期的库 API 等问题。

  3. 安全黑洞：数据流完全在沙箱内闭环，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 pdimport osdef 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 调用示例**：```pythonimport 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 字内容) ...<<<ACTION:CONVERT|pdf>>>
复制代码

3.4 输出侧：渲染与交付的分离

对于不同类型的文件，我们采取了截然不同的交付策略：

  1. Excel（强结构化）：走 Skills 路线。LLM 组装数据 -> 调用 excel_tool -> 沙箱生成物理文件。

  2. Word/PDF（富文本）：走 渲染路线。严禁 LLM 写代码生成。

  3. LLM 只输出高质量的 Markdown 并在末尾打上 <<>> 标签。

  4. Java 后端拦截该标签，利用 OpenHTMLtoPDF 或 Pandoc 将 Markdown 实时转换 为精美的 PDF/Word。

四、 硬核代码实现 (Spring AI)

以下是我们在 Spring AI 体系下实现这套混合架构的关键逻辑。

4.1 动态技能注入 (SkillManager)

我们实现了一个 SkillManager，支持按需加载技能。为了提升性能，我们设计了 Session 级的“防抖机制”，确保同一个会话中只需上传一次 Python 脚本，避免重复 IO。

@Servicepublic class SkillManager{    // 缓存技能脚本: 技能名 -> { 文件路径 -> 内容 }    private final Map<String, Map<String, String>> skillScripts = new ConcurrentHashMap<>();    // 防止重复注入的防抖 Set    private final Set<String> injectedSessions = ConcurrentHashMap.newKeySet();    /**     * 核心逻辑：根据需要的技能列表，动态注入脚本到沙箱     */    public void injectToSandbox(String sessionId, List<String> 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<String, String> scripts = skillScripts.get(skillName);            if (scripts != null) {                scripts.forEach((path, content) ->                     sandboxService.uploadFile(sessionId, path, content)                );            }        }        injectedSessions.add(sessionId);    }        // ... 省略加载 Resource 的代码 ...}
复制代码

4.2 业务调度与意图分流 (Handler)

串联 Java ETL、LLM 推理和最终的交付分流。

@Servicepublic class DocumentAnalysisRequestHandler{    public Flowable<Response> processStreamingRequest(Request req) {        // 1. 【Java ETL】确定性解析与安检        // 无论 URL 还是文件，先转为纯文本，并做敏感词过滤        List<ParseResult> parsedDocs = etlPipeline.process(req.getUrls());                // 2. 【技能注入】        List<String> neededSkills = List.of("file_generation");        skillManager.injectToSandbox(req.getSessionId(), neededSkills);        // 3. 【LLM 执行】Context Stuffing        String prompt = buildPrompt(parsedDocs, skillManager.getPrompts(neededSkills));                // 调用 LLM，挂载 ToolContext 以实现多租户隔离        Flowable<AgentOutput> 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<AgentOutput> handlePostGenerationAction(List<String> 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：检测到转换指令 (渲染产物)        // 格式：<<<ACTION:CONVERT|pdf>>>        if (text.contains("<<<ACTION:CONVERT|pdf>>>")) {            // 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));    }}
复制代码

4.3 拦截与交付 (SandboxTools)

在 Tool 执行层做最后一道防线：输出内容的二次安检。

@Componentpublic 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<String, Object> 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 拥有了“手”，但这双手必须戴上“手套”。

通过这次架构演进，我们得出的核心经验是：

  1. 不要高估 LLM 的 Coding 能力：它是一个优秀的逻辑推理引擎，但在工程细节（排版、库依赖、环境配置）上非常糟糕。DSL 封装是必须的。

  2. 不要丢掉 Java 的确定性：解析、下载、格式转换、安全检查，这些传统代码擅长的领域，不要交给概率性的 LLM 去做。

  3. 架构分层：

  4. Input: Java (Standardization & Security)

  5. Thinking: LLM (Reasoning)

  6. Action: Python (Calculation via DSL)

  7. Output: Java (Rendering & Delivery)

这种混合架构，既保留了 Agent 处理复杂动态需求的能力（如自定义计算涨跌幅），又守住了企业级应用对稳定性与合规性的底线。