企业官网建设流程全解析

1. 项目概述：这不是一个玩具框架，而是一套可落地的企业级 Agent 运行底座

“用纯 Java 做一个企业级 Agent Harness 平台：BizBuddy 的设计与取舍”——这个标题里藏着三重关键信息：纯 Java、企业级、Agent Harness。它不是在教你怎么写个能调用 LLM API 的 Demo，也不是用 Spring Boot 快速搭个 REST 接口就交差的练手项目。它是某金融行业后台系统团队在真实业务场景中，为支撑数十个智能体（Agent）长期稳定运行而从零构建的一套运行时基础设施。BizBuddy 这个代号，代表的是“Business Buddy”，即业务伙伴型智能体的统一承载平台。它的核心诉求非常朴素：让业务部门能定义自己的 Agent 流程（比如“合同风险初筛”“客户投诉归因分析”），让算法团队能交付封装好的工具函数（比如“调用OCR服务”“查内部知识库”），让运维团队能像管理普通 Java 服务一样监控、扩缩、回滚、灰度——全部不依赖 Python 环境、不引入 Node.js 中间层、不绑定特定大模型厂商 SDK。

为什么必须是纯 Java？因为目标系统已运行着上百万行 Java 代码，核心交易链路、权限体系、审计日志、服务注册发现全部基于 Spring Cloud Alibaba 和 Dubbo 构建。强行塞入 Python 子进程或 gRPC 转发层，会带来不可接受的延迟毛刺、内存泄漏排查黑洞、以及上线审批流程的额外阻力。BizBuddy 的“企业级”体现在三个硬指标上：单节点支持 200+ 并发 Agent 实例稳定运行超 72 小时；所有执行轨迹（含 LLM 输入/输出、工具调用参数、中间状态）可全链路追踪并落库，满足等保三级审计要求；支持按业务域隔离的资源配额（CPU 时间片、Token 预算、工具调用频次），避免某个实验性 Agent 拖垮整个平台。而“Harness”这个词，直译是“挽具”，在这里特指对 Agent 的约束、编排、观测与兜底能力——它不负责生成智能，只负责让智能安全、可控、可管地跑起来。如果你正在评估是否要自建 Agent 底座，或者被现有方案中 Python 依赖混乱、可观测性缺失、灰度发布困难等问题困扰，BizBuddy 的设计思路和取舍逻辑，就是一份来自生产环境的实操笔记。

2. 整体架构设计与关键取舍：为什么放弃“开箱即用”，选择“可插拔内核”

2.1 核心设计哲学：Agent 是“有状态的工作流”，不是“无状态的函数调用”

很多团队初期会把 Agent 当成一个增强版的 HTTP 客户端：输入 prompt，等待 LLM 返回，解析 JSON，调用工具，再拼回去。BizBuddy 团队在第一个月就推翻了这种设计。他们用真实业务场景做了压力测试：一个“贷款申请材料完整性校验”Agent，需要依次做 OCR 识别、字段提取、规则引擎比对、人工复核建议生成、历史相似案例检索——整个过程平均耗时 8.3 秒，其中 LLM 参与环节仅占 2.1 秒。如果每次步骤都走完整 HTTP 往返，光网络开销就吃掉 40% 以上时间，且状态必须序列化到 Redis，导致调试时根本看不到中间变量。因此，BizBuddy 的第一原则是：Agent 生命周期内所有计算必须在 JVM 内完成，状态以对象引用方式流转，仅在必要节点（如跨服务调用、持久化）才做序列化。

这直接决定了架构分层：最底层是Runtime Core，一个轻量级、无外部依赖的 Java 类库，提供 Agent 执行上下文（ExecutionContext）、状态快照（StateSnapshot）、中断恢复（ResumePoint）等核心抽象；中间层是Orchestration Engine，基于状态机模型实现，不采用 BPMN 等重型规范，而是用 200 行代码定义的 DSL 描述跳转逻辑（例如IF (field_missing) -> CALL(ocr_tool) ELSE -> RULE_ENGINE）；最上层是Adapter Layer，负责对接外部世界：HTTP Client Adapter 封装了带熔断、重试、Token 限流的 OkHttp；Database Adapter 统一处理 JPA/HikariCP 连接池；LLM Adapter 则抽象出ChatModel和EmbeddingModel两个接口，屏蔽了 OpenAI、千问、混元等 SDK 差异。这种分层不是为了炫技，而是让业务方修改一个 OCR 工具的超时时间，只需改一行配置；让算法团队替换 Embedding 模型，只需实现一个新类并注册进 Spring 容器——改动范围被严格限定在 Adapter 层。

2.2 关键取舍一：放弃“自动规划”，坚持“显式编排”

当前主流 Agent 框架（如 LangChain 的 Plan-and-Execute）倾向于让 LLM 自己决定下一步调用哪个工具。BizBuddy 明确拒绝了这条路。原因很现实：在金融风控场景中，“先查征信再查流水”是强合规要求，顺序错一步就可能触发监管报备。LLM 的“自主决策”在测试中出现过 3.7% 的非预期跳转率（比如该调用反洗钱规则引擎时，却去调用了客户画像服务）。BizBuddy 的解决方案是：所有 Agent 的执行路径必须由业务分析师用 YAML 定义，LLM 只负责填充具体参数。例如：

steps: - id: extract_fields tool: ocr_extractor input: "image_url: {{input.image}}" - id: validate_id tool: id_card_validator input: "id_number: {{extract_fields.id_number}}" - id: risk_score llm: qwen_chat prompt: | 你是一个风控专家。根据以下信息计算风险分： - 身份证号：{{validate_id.id_number}} - 信用报告摘要：{{call_credit_report.summary}}

这个 YAML 被编译成 Runtime Core 可执行的状态机图。LLM 永远不会决定“下一步做什么”，只会回答“这一步的参数是什么”。这种设计牺牲了部分灵活性，但换来了 100% 的流程可审计性——审计员可以直接比对 YAML 文件和数据库中的执行日志，确认每一步是否按规执行。我们实测发现，业务方编写一个新 Agent 的平均耗时从原先的 2 天（反复调试 LLM 规划）缩短到 4 小时（填空式配置），且上线后故障率下降 92%。

2.3 关键取舍二：不内置记忆，但提供标准化记忆桥接点

“Agent 需要记忆”是共识，但 BizBuddy 没有自己实现向量数据库或对话历史管理。相反，它定义了MemoryProvider接口，强制要求所有记忆实现必须提供两个方法：loadContext(String sessionId, int maxTokens)和saveContext(String sessionId, String newContent)。业务方可以根据场景自由选择：客服场景用 Redis List 存最近 10 轮对话（低延迟）；投研分析场景用 Milvus 存向量化文档片段（高精度）。平台只保证：当 Agent 启动时，Runtime Core 会自动调用loadContext获取上下文，并注入到 LLM 的 system prompt 中；当 Agent 结束时，自动调用saveContext保存本次新增内容。这种设计让记忆模块完全解耦——某次线上事故中，Milvus 集群响应超时，运维只需将MemoryProviderBean 切换为本地 Map 实现，5 分钟内恢复服务，而 Agent 代码一行未动。我们甚至看到有团队用这个接口对接了企业微信的聊天记录 API，让 Agent 能“记住”用户在企微里提过的历史问题。

2.4 关键取舍三：拒绝“大模型中心化”，拥抱“工具优先”

很多框架默认把 LLM 当作唯一智能源，工具只是它的手脚。BizBuddy 反其道而行之：工具是第一公民，LLM 是可选协作者。每个工具类（如CreditReportTool）必须实现Tool接口，声明name、description、inputSchema（JSON Schema 格式），并标注@ToolCategory("risk")。Runtime Core 在启动时扫描所有@Tool类，构建工具目录。当 Agent 需要“查征信”时，Orchestration Engine 直接调用CreditReportTool.execute()，根本不需要 LLM 参与。只有当业务逻辑复杂到无法用 if-else 表达时（例如“根据客户近三个月交易模式，判断是否疑似刷单”），才触发 LLM 的reasoning模式。这种设计大幅降低了对大模型的依赖：在压测中，78% 的 Agent 步骤由纯 Java 工具完成，LLM 调用量比同类方案减少 65%，成本直降，且响应更稳定——毕竟 Java 方法调用的 P99 延迟是 12ms，而一次千问 API 调用的 P99 是 1.8s。

3. 核心模块实现详解：从状态机到可观测性的落地细节

3.1 Runtime Core：200 行代码的状态机内核如何工作

BizBuddy 的 Runtime Core 是整个平台的基石，它不依赖任何第三方流程引擎，而是用 Java 原生特性实现了极简但健壮的状态机。核心类AgentStateMachine只有 3 个关键成员：

• private final Map<String, StepDefinition> stepMap;—— 步骤定义缓存，Key 是步骤 ID（如extract_fields），Value 是解析 YAML 后的 POJO，包含工具名、输入表达式、跳转条件等。
• private final ThreadLocal<ExecutionContext> contextHolder;—— 线程局部变量存储执行上下文，确保高并发下状态隔离。ExecutionContext 包含input（原始输入）、state（Map<String, Object> 类型的中间状态）、traceId（用于链路追踪）等。
• private final Map<String, Tool> toolRegistry;—— 工具注册表，Spring 启动时自动扫描@Tool注解的 Bean 并注入。

执行流程极其清晰：

1. 用户发起请求，Controller 创建ExecutionContext，将原始 JSON 输入解析为Map放入state，设置初始currentStepId = "start"；
2. AgentStateMachine.run()方法进入循环：
   • 从stepMap获取currentStepId对应的StepDefinition；
   • 解析StepDefinition.input表达式（如{{input.image}}），从ExecutionContext.state中提取值；
   • 若StepDefinition.tool非空，从toolRegistry获取工具实例，调用execute(input)，将返回值存入state的同名 key 下（如ocr_extractor返回结果存为state["extract_fields"]）；
   • 若StepDefinition.llm非空，则构造 prompt，调用 LLM Adapter，将响应存入state；
   • 根据StepDefinition.next或条件表达式（如{{state["valid"] == true}}）更新currentStepId；
3. 循环直到currentStepId为"end"或抛出异常。

这个设计的精妙之处在于：所有状态变更都是同步、原子、可预测的。没有异步回调、没有事件总线、没有状态持久化中间件。我们曾用 JMH 基准测试，在 16 核服务器上，单线程每秒可执行 12,800 次简单步骤（纯内存操作），即使加入 LLM 调用，P95 延迟也稳定在 2.3 秒内。更重要的是，它让调试变得极其简单——在 IDE 中打断点，你可以清晰看到ExecutionContext.state里每一步的输入输出，而不是在一堆 Promise 链中迷失。

3.2 Orchestration Engine：用 200 行 DSL 实现的动态编排能力

BizBuddy 的编排能力不靠图形化界面，而靠一套轻量 DSL。它被设计成可被 Java 代码直接解析，而非独立解释器。DSL 语法只有 4 个核心元素：

• CALL(toolName)：同步调用工具，阻塞直到返回；
• IF(condition) -> targetStep：条件跳转，condition 是 SpEL 表达式（如state['score'] > 80）；
• FOR(item in collection) -> loopBody：遍历集合，loopBody 是另一个步骤 ID；
• WAIT(timeoutSeconds)：主动休眠，用于模拟人工审核等待。

这些 DSL 在 YAML 解析阶段就被编译成StepDefinition对象的nextStrategy字段。例如，下面的 DSL：

IF(state['document_type'] == 'ID_CARD') -> CALL(id_validator) ELSE IF(state['document_type'] == 'BANK_CARD') -> CALL(card_validator) ELSE -> WAIT(30)

会被编译为一个ConditionalNextStrategy，其getNextStepId()方法内部就是一段编译好的 SpEL 表达式求值逻辑。这种设计的好处是：编排逻辑最终是纯 Java 字节码，性能无损，且可被 JVM JIT 优化。我们对比过用 Groovy 脚本引擎解析同样逻辑，QPS 下降 40%，GC 压力上升 3 倍。而 BizBuddy 的 DSL 编译器（DslCompiler类）只有 187 行代码，它把 DSL 字符串转换成 Lambda 表达式，然后缓存起来复用。某次线上紧急修复，运维直接在配置中心修改了 DSL 字符串，30 秒后新逻辑就生效了，全程无需重启服务。

3.3 LLM Adapter：如何用 3 个接口统一 7 种大模型 SDK

BizBuddy 的 LLM Adapter 层是“纯 Java”承诺的关键兑现点。它没有封装某个 SDK，而是定义了三个极简接口：

public interface ChatModel { ChatResponse chat(ChatRequest request); } public interface EmbeddingModel { List<float[]> embed(List<String> texts); } public interface ModelConfig { String getModelName(); int getMaxTokens(); float getTemperature(); }

每个大模型厂商的适配器（如QwenChatModel、OpenAiEmbeddingModel）都只做一件事：把厂商 SDK 的调用，翻译成上述接口的语义。以QwenChatModel为例，它的chat()方法核心逻辑只有 12 行：

public ChatResponse chat(ChatRequest request) { // 1. 构造通义千问 SDK 的 Request 对象 DashScopeChatRequest sdkReq = new DashScopeChatRequest(); sdkReq.setModel(config.getModelName()); sdkReq.setMessages(request.getMessages().stream() .map(m -> new Message(m.getRole(), m.getContent())) .collect(Collectors.toList())); // 2. 调用 SDK，捕获并转换异常 try { DashScopeChatResponse sdkResp = client.chat(sdkReq); return new ChatResponse(sdkResp.getOutput().getText()); } catch (ApiException e) { throw new LlmException("Qwen API error: " + e.getMessage(), e); } }

这种设计彻底解耦了业务代码和厂商 SDK。当某天需要从千问切换到混元时，只需：

1. 引入tongyi-hunyuan-sdk依赖；
2. 编写HunYuanChatModel实现ChatModel接口；
3. 在 Spring 配置中将ChatModelBean 替换为新实现。

整个过程业务方无感知，Agent YAML 文件完全不用改。我们实测过，在不重启服务的情况下，通过 Spring Cloud Config 动态刷新 Bean，5 分钟内完成模型切换，期间 Agent 请求成功率保持 100%。这背后是 BizBuddy 对“适配器模式”的极致运用：它不试图做“万能胶水”，而是用最小契约定义能力边界，让变化只发生在接口实现层。

3.4 可观测性体系：从日志埋点到审计报表的全链路覆盖

企业级平台最怕“黑盒运行”。BizBuddy 的可观测性不是事后补救，而是从 Runtime Core 就深度集成。它有三层数据采集：

• Trace 层：每个ExecutionContext创建时，自动生成traceId，并通过 MDC（Mapped Diagnostic Context）注入 Logback 日志。所有工具调用、LLM 请求、状态变更日志都自动带上traceId，可在 ELK 中一键串联。我们特别增加了step_duration_ms字段，精确到微秒，方便定位瓶颈步骤。
• Metric 层：使用 Micrometer 暴露 12 个核心指标，例如bizbuddy.agent.execution.time.seconds（按 Agent ID 和步骤 ID 维度）、bizbuddy.llm.token.usage.total（按模型维度）。Prometheus 抓取后，Grafana 看板可实时显示：当前有多少 Agent 在运行、各步骤平均耗时、LLM Token 消耗 Top 5 Agent。
• Audit 层：这是最严格的部分。所有ExecutionContext在结束时，必须调用AuditService.audit()方法，将结构化数据写入 MySQL 审计表。表结构包含agent_id、session_id、step_id、input_json（脱敏后）、output_json（脱敏后）、status（SUCCESS/FAILED）、error_message（若失败）。审计表每日自动分区，保留 180 天，且禁止任何 DELETE 权限——连 DBA 都无法删改。某次合规检查中，审计员随机抽取了 50 个历史会话，我们 3 分钟内就导出了完整执行链路的 PDF 报告，包括每一步的输入输出快照和耗时。

这套体系带来的直接好处是：当用户投诉“Agent 给错了建议”，技术支持只需拿到session_id，就能在 Kibana 中 10 秒内还原整个执行过程，精准定位是 OCR 识别错误、还是规则引擎配置偏差，而不是让研发去翻几万行日志猜。

4. 实操部署与运维要点：从开发环境到生产集群的避坑指南

4.1 开发环境搭建：如何用 5 分钟启动一个可调试的 BizBuddy 实例

新手最容易踩的坑，是试图在开发机上模拟完整生产环境。BizBuddy 团队明确建议：开发阶段，用 H2 Database + Mock LLM + 内存工具，追求秒级启动和断点调试。具体步骤如下：

1. 创建 Spring Boot 项目：使用 Spring Initializr，勾选Spring Web、Spring Data JPA、Lombok，Java 版本选 17（BizBuddy 最小要求）；
2. 添加 BizBuddy Starter：在pom.xml中引入bizbuddy-spring-boot-starter（内部 Maven 仓库地址由团队提供），它会自动导入 Runtime Core 和默认 Adapter；
3. 配置 application.yml：

   bizbuddy: # 开发模式：禁用真实 LLM，用 Mock 返回固定文本 llm: mock-enabled: true mock-response: "风险等级：高，建议人工复核" # 数据库用 H2，内存模式，方便调试 datasource: url: jdbc:h2:mem:devdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE driver-class-name: org.h2.Driver # 工具全部用内存实现，不调外部服务 tools: ocr: memory rule-engine: memory

4. 编写第一个 Agent YAML：在src/main/resources/agents/下创建credit-check.yaml，定义简单的三步流程；
5. 启动应用：运行Application.main()，访问http://localhost:8080/actuator/health确认启动成功；
6. 调试 Agent：在 Controller 的executeAgent()方法打个断点，用 Postman 发送 JSON 请求，即可在 IDE 中逐行跟踪ExecutionContext.state的变化。

这个流程我们实测过，从创建项目到看到第一个 Agent 执行日志，最快记录是 4 分 38 秒。关键点在于：开发阶段绝不碰真实外部依赖。某次新同学执意要在开发机上配通义千问 AK/SK，结果因为网络策略限制卡了 2 小时，最后还是切回 Mock 模式才继续。BizBuddy 的哲学是：让开发者聚焦在“逻辑是否正确”，而不是“网络是否通畅”。

4.2 生产环境部署：JVM 参数、线程池与资源隔离的黄金配置

生产环境的稳定性，80% 取决于 JVM 和线程池配置。BizBuddy 团队经过 6 个月压测，总结出以下黄金参数（适用于 16C32G 服务器，单节点部署）：

• JVM 参数：

  -Xms4g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/data/dumps/ -Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai

  关键点：堆内存固定为 4G（避免 GC 波动），G1 垃圾收集器目标停顿 200ms，必须开启堆转储——因为 Agent 内存泄漏往往表现为ExecutionContext.state中缓存了不该存的大对象（如整张图片 Base64）。

• 线程池配置（在application-prod.yml中）：

  bizbuddy: # Agent 执行线程池：核心 50，最大 200，队列容量 1000 executor: core-pool-size: 50 max-pool-size: 200 queue-capacity: 1000 keep-alive-seconds: 60 # LLM 调用线程池：核心 10，最大 50，拒绝策略为 CALLER_RUNS llm-executor: core-pool-size: 10 max-pool-size: 50 queue-capacity: 200 rejection-policy: CALLER_RUNS

  为什么这样配？因为 Agent 执行大部分是 CPU 密集型（规则计算、JSON 解析），而 LLM 调用是 IO 密集型（网络等待）。分开线程池可避免 LLM 等待拖垮整个 Agent 执行。CALLER_RUNS拒绝策略意味着当 LLM 线程池满时，调用线程自己执行 LLM 请求，虽然慢但不会丢请求——这比直接拒绝更能保障业务连续性。

• 资源隔离：BizBuddy 支持按agent_id设置配额。例如，给高优 Agent “合同审查”分配cpu_quota_ms=5000（每分钟最多消耗 5 秒 CPU 时间），给实验性 Agent “营销文案生成”分配token_budget=10000（每天最多调用 1 万 Token）。配额检查在AgentStateMachine.run()循环开始前执行，超限则直接返回429 Too Many Requests。这个功能上线后，实验性 Agent 导致的 CPU 尖刺故障归零。

提示：生产环境必须关闭mock-enabled，且llm配置块中必须指定真实的api-key和endpoint。我们曾因配置文件未切换，导致上线后所有 Agent 都返回 Mock 文本，幸好有灰度发布机制，只影响了 5% 流量。

4.3 灰度发布与回滚：如何让 Agent 更新像发布普通接口一样安全

BizBuddy 将 Agent 的 YAML 文件视为“可版本化的代码”，其灰度发布流程与普通 Java 服务完全一致：

1. 版本管理：所有 Agent YAML 存放在 Git 仓库的/agents/目录下，每个文件名格式为agent-id-v1.2.0.yaml。CI 流程会自动为每次提交生成 SHA256 校验和，并写入agent-manifest.json；
2. 灰度发布：通过配置中心（如 Nacos）下发agent.version.mapping，例如：

   { "contract-review": "v1.2.0", "customer-complaint": "v1.1.5" }

   服务启动时读取此映射，只加载指定版本的 YAML。灰度时，先将customer-complaint映射改为v1.2.0，观察 10 分钟监控，无异常再全量；
3. 秒级回滚：如果新版本 Agent 出现问题，运维只需在配置中心将映射改回旧版本号（如v1.1.5），BizBuddy 的AgentLoader会监听到变更，5 秒内重新加载 YAML 并生效——整个过程无需重启 JVM，用户无感知。

这个机制的关键在于：Agent 定义与执行逻辑完全分离。YAML 是数据，Runtime Core 是引擎。我们曾用此机制在 3 分钟内回滚了一个因正则表达式错误导致无限循环的 Agent，而传统方案需要重启服务，平均耗时 8 分钟。某次大促前，团队甚至做了“影子发布”：新版本 Agent 流量复制 1%，同时执行新旧两版，对比输出一致性，确保 100% 匹配后才切流。

4.4 故障排查实战：3 个高频问题的根因分析与解决

问题 1：Agent 执行缓慢，P95 延迟从 2s 升至 15s，但 CPU 和内存正常

现象：Grafana 显示bizbuddy.agent.execution.time.seconds指标突增，但服务器监控中 CPU 使用率仅 30%，堆内存占用稳定在 2.5G/4G。

排查思路：

• 第一步，查日志：在 Kibana 中搜索traceId，发现大量日志包含step_duration_ms: 12800（12.8 秒），且step_id都是call_ocr_service；
• 第二步，看链路：点击该traceId，发现call_ocr_service步骤的 Span 中，http.client.request.duration是 12.7 秒，说明是外部 HTTP 调用慢；
• 第三步，查依赖：确认 OCR 服务是公司内部微服务，其 Prometheus 监控显示 P95 延迟已达 10s，原因是上游图片存储 COS 限流。

解决方案：

• 短期：在OcrTool的execute()方法中增加超时控制（OkHttp 的callTimeout(5, TimeUnit.SECONDS)），超时后返回{"error": "OCR_TIMEOUT"}，让 Agent 走降级逻辑；
• 长期：推动 OCR 服务团队优化 COS 访问，或接入 CDN 缓存热点图片。

注意：BizBuddy 的工具调用默认无超时，必须由工具实现者显式设置。这是故意为之的设计——平台不替业务方做超时决策，因为“OCR 等 10 秒可接受”和“风控评分等 10 秒不可接受”是不同业务需求。

问题 2：Agent 执行失败，日志报java.lang.OutOfMemoryError: Java heap space，但堆内存监控未见明显增长

现象：JVM 堆内存使用率曲线平滑，但偶发OutOfMemoryError，且错误堆栈指向ExecutionContext.state.put("large_image", base64String)。

根因：base64String是一张 10MB 图片的 Base64 编码，长度约 13MB。ExecutionContext.state是HashMap<String, Object>，当它被序列化（如存入 Redis 或写审计日志）时，会触发toString()，导致整个字符串被复制，瞬间产生 26MB 临时对象，触发 GC，但老年代空间不足。

解决方案：

• 立即措施：在AgentStateMachine.run()循环中，增加对state中 value 大小的检查，超过 1MB 的字符串自动截断并记录警告；
• 根本解决：推动业务方改造 OCR 工具，不传 Base64，而是传图片 URL，由 OCR 服务自己下载——这符合 BizBuddy 的“工具优先”原则，也大幅降低网络传输量。

问题 3：审计表数据量暴增，单日写入 2TB，MySQL 主从延迟高达 2 小时

现象：audit_log表每天增长 2TB，SHOW SLAVE STATUS显示Seconds_Behind_Master持续在 7200 秒左右。

根因：审计日志默认记录input_json和output_json的完整 JSON 字符串。某次上线的“财报分析”Agent，输入是一份 50MB 的 PDF 解析后 JSON，单条审计记录达 60MB。

解决方案：

• 紧急：启用审计日志脱敏和采样。在AuditService.audit()中，对input_json和output_json字段做哈希（SHA256），只存哈希值，原始数据存入对象存储（如 S3），审计表中加storage_key字段指向 S3 Key；
• 长效：在 Agent YAML 中增加audit: {include_input: false, include_output: false}配置项，允许业务方按需关闭敏感字段审计。

这个案例告诉我们：企业级平台的“可审计”不等于“全量存档”，而是在合规底线之上，用技术手段平衡存储成本与审计价值。

5. 常见问题与扩展实践：从单体部署到多租户 SaaS 的演进路径

5.1 常见问题速查表：新人必看的 5 个“为什么”与“怎么做”

5.2 从单体到多租户：BizBuddy 的 SaaS 化演进实践

BizBuddy 最初是为单一业务线设计的，但随着其他部门（如 HR、供应链）提出需求，团队开始探索多租户支持。核心挑战是：如何在共享同一套 JVM 和数据库的前提下，实现租户间的数据隔离、资源隔离与配置隔离。他们的方案是“四层隔离”：

• 数据层隔离：所有核心表（agent_definition、audit_log、execution_trace）增加tenant_id字段，查询时自动追加WHERE tenant_id = ?条件。使用 MyBatis Plus 的TenantLineInnerInterceptor实现，对业务代码零侵入；
• 配置层隔离：Nacos 配置中心按tenant_id建命名空间，每个租户有自己的application-{tenant}.yml，AgentLoader加载 YAML 时自动读取对应命名空间；
• 资源层隔离：