纯Java企业级Agent执行沙箱：BizBuddy架构与工程实践

1. 为什么“纯 Java”做 Agent Harness 是个反直觉但值得深挖的决定

“用纯 Java 做企业级 Agent Harness 平台”——这个标题刚看到时，我下意识皱了下眉。身边太多团队在聊 LLM 应用落地，一开口就是 Python + LangChain + FastAPI，再配上点 Docker 和 Kubernetes，仿佛不这么组合就落了下风。某次和一位做金融智能投研系统的架构师吃饭，他半开玩笑说：“我们组试过用 Java 写 agent flow，结果被产品问‘你们是不是没跟上节奏？Python 不香吗？’”——这话背后不是技术优劣之争，而是对“Java 能不能、该不该、值不值得”承担起新一代 AI 工程化底座的普遍怀疑。

但 BizBuddy 这个项目，恰恰是从一次真实的交付倒逼出来的：某高校实验室承接了一个跨部门协同决策支持系统，要求所有模块必须运行在客户已有的 Java EE 安全合规基线内，禁用 Python 解释器、禁用外部容器镜像、所有代码需通过静态扫描与字节码审计。他们不是不想用 LangChain，是根本“进不去”。于是我们退了一步：不争“谁更先进”，只问“谁更可靠、谁更可控、谁更容易嵌入现有产线”。

纯 Java 的选择，本质是一次工程约束下的主动聚焦。它不意味着拒绝生态，而是把“可预测性”放在首位——JVM 的类加载机制、线程模型、GC 行为、字节码增强能力，都是经过十年以上高并发、长周期服务验证的；Spring Boot 的自动装配、Actuator 的健康探针、Micrometer 的指标埋点，天然适配企业级可观测体系；更重要的是，Java 的强类型、编译期检查、IDE 智能补全，在多人协作、长期维护、安全审计场景下，错误发现成本比动态语言低一个数量级。这不是情怀，是某次线上事故后，运维同学指着日志里一行AttributeError: 'NoneType' object has no attribute 'invoke'对我说：“要是这行报错能编译不过，我们能少熬三小时。”

BizBuddy 的定位因此非常清晰：它不是一个“Java 版 LangChain”，而是一个面向企业交付现场的 Agent 执行沙箱。它不负责模型调用封装（那是 Model Adapter 层的事），不负责 Prompt 工程抽象（那是业务侧 DSL 的事），它只干三件事：安全地加载 Agent 插件、确定性地编排执行链、可审计地记录每一步决策上下文。所有设计取舍，都围绕这三件事展开。关键词里没有“LLM”“RAG”“Function Calling”，因为 BizBuddy 本身不碰这些——它只保证，当业务方把一个实现了AgentExecutor接口的类扔进来时，它能稳稳接住、按序执行、出错回滚、留痕可查。

这种克制，反而让它在真实项目中跑得更远。我们在模拟项目X中接入过三种异构 Agent：一个基于规则引擎的信贷初筛组件（纯 Java 写的 Drools 封装）、一个调用内部大模型 API 的决策生成器（封装了鉴权与重试）、一个对接 OA 系统的流程触发器（含事务补偿逻辑）。它们语言不同、协议不同、依赖不同，但在 BizBuddy 的 Runtime 中，统一表现为ExecutionStep实例，共享同一套超时控制、熔断策略与审计日志格式。这才是企业级 Harness 的核心价值：不是让你造轮子，而是让你放心把轮子装上去，并且知道它什么时候转、转多快、卡在哪。

2. BizBuddy 的四层架构：为什么跳过“编排引擎”直接建“执行契约”

很多团队一上来就想搞个“可视化流程编排器”，拖拽节点、连线、配置参数，听起来很酷。BizBuddy 在早期原型阶段也做过类似尝试，但两周后就砍掉了整个 UI 模块——不是技术做不到，而是它模糊了平台的核心边界。我们意识到，真正的复杂性不在“怎么画流程图”，而在“画完之后，系统如何确保这张图被严格、一致、可追溯地执行”。于是架构设计彻底转向“契约驱动”，分四层自底向上构建：

2.1 第一层：Plugin Isolation Layer（插件隔离层）

这是 BizBuddy 的安全基石。企业环境最怕什么？不是功能不行，是“某个第三方插件偷偷读了数据库连接池配置”。Java 原生的ClassLoader机制在这里被深度定制。我们没用 OSGi（太重、学习成本高），也没用 Spring Plugin（扩展性弱），而是基于URLClassLoader构建了一套轻量级沙箱类加载器：每个 Agent 插件（打包为独立 JAR）都拥有专属的PluginClassLoader，其 parent 被显式设为null，强制切断对宿主应用类路径的默认继承。同时，我们重写了findClass方法，加入白名单校验——只允许加载com.bizbuddy.agent.*和java.lang.*下的类，其他一切反射、Class.forName调用均被拦截并记录审计日志。

提示：这个设计的关键细节在于“白名单粒度”。最初我们只放行java.lang.*，结果插件里用org.apache.commons.lang3.StringUtils就直接失败。后来调整为按包前缀白名单 + 显式依赖声明机制：插件 JAR 的META-INF/bizbuddy-plugin.yml中必须声明所需第三方包（如org.apache.commons:commons-lang3:3.12.0），平台启动时校验其 SHA-256 是否匹配内置可信仓库。既保安全，又不失灵活性。

2.2 第二层：Execution Contract Layer（执行契约层）

这是 BizBuddy 的灵魂所在。我们定义了一个极简但有力的接口：

public interface AgentExecutor { ExecutionResult execute(ExecutionContext context) throws ExecutionException; // 契约元数据，用于平台调度与审计 String getAgentId(); int getTimeoutSeconds(); boolean isIdempotent(); Set<String> getRequiredPermissions(); }

注意，这里没有next()、没有chain()、没有onSuccess()回调。所有流程编排逻辑，必须由上层（业务方）通过组合多个AgentExecutor实例来完成。BizBuddy 只承诺一件事：当你调用execute()，它会在指定超时内返回ExecutionResult（含状态、输出、耗时、错误堆栈），且该过程满足幂等性声明（isIdempotent()返回 true 时，平台会自动启用去重缓存）。

这个设计直接规避了“编排引擎”的两大陷阱：一是状态管理复杂度爆炸（分布式环境下保证流程状态一致性成本极高），二是业务逻辑与平台逻辑耦合（比如把重试逻辑写死在引擎里，业务方想换策略就得改平台代码）。现在，重试是RetryableAgentExecutor的事，降级是FallbackAgentExecutor的事，分支是ConditionalAgentExecutor的事——它们都是普通 Java 类，实现同一个接口，平台只认契约，不关心实现。

2.3 第三层：Runtime Orchestration Layer（运行时编排层）

既然不提供图形化编排器，那流程怎么定义？答案是：用 Java 代码写 DSL。BizBuddy 提供一组 Fluent API，让业务方在 Spring Bean 中声明式定义执行链：

@Bean public AgentFlow creditAssessmentFlow() { return AgentFlow.builder("credit-assessment-v2") .step("rule-check", ruleEngineExecutor()) .step("model-score", llmScorerExecutor()) .onFailure(fallbackToManualReview()) // 失败时跳转 .step("oa-notify", oaNotifierExecutor()) .onSuccess(sendSmsNotification()) // 成功后异步通知 .build(); }

这段代码在 Spring 容器启动时被解析，生成一个不可变的AgentFlow实例，其内部是一个List<ExecutionStep>。关键在于，AgentFlow本身不执行任何逻辑，它只是一个执行计划的只读快照。真正执行时，Runtime 层会创建一个FlowInstance，绑定本次请求的ExecutionContext（含 traceId、用户权限、输入数据），然后按序调用每个AgentExecutor.execute()。如果某步失败，FlowInstance会根据预设策略（如onFailure）决定是终止、跳转还是重试，所有决策过程都被记录到ExecutionTrace中。

2.4 第四层：Observability & Governance Layer（可观测与治理层）

企业级系统，没有可观测性等于没有生命线。BizBuddy 的审计日志不是简单打log.info，而是结构化事件流。每次AgentExecutor.execute()调用，都会生成一条ExecutionEvent，包含：

• event_id: UUID（全局唯一）
• flow_id,step_id,trace_id
• status: STARTED / SUCCESS / FAILED / SKIPPED
• input_hash: 输入数据的 SHA-256（保护敏感信息，同时支持重复请求识别）
• output_summary: 输出摘要（如 JSON 字段数、文本长度，避免日志爆炸）
• resource_usage: JVM 内存增长、线程耗时、外部 HTTP 调用次数与耗时（通过 Java Agent 注入采集）

这些事件被统一发送到 Kafka Topic，下游可自由消费：监控告警系统订阅失败事件，审计系统归档全量事件，A/B 测试平台对比不同版本 Agent 的耗时分布。我们甚至用它做了个简单但实用的功能——“执行回放”：选中某次失败的trace_id，平台能重建当时的ExecutionContext，重新运行整个 Flow，精准复现问题。这比翻几十个微服务日志快得多。

这四层架构，每一层都回答了一个关键问题：隔离层问“谁能进来”，契约层问“进来后必须做什么”，运行时层问“怎么做”，治理层问“做得怎么样”。没有一层是多余的，也没有一层越界去管另一层的事。这种清晰的职责划分，正是 BizBuddy 能在三个月内从概念落地到生产环境支撑日均 200 万次 Agent 调用的根本原因。

3. 关键取舍详解：为什么放弃“动态热更新”、不支持“跨 JVM Agent 通信”

在 BizBuddy 的设计评审会上，有两个提议被明确否决，且否决理由至今写在我们的技术决策文档首页。它们不是技术做不到，而是深入业务场景后，发现“不做”比“做”更能保障企业级稳定性。

3.1 放弃“插件热更新”：一次部署，全量验证

几乎所有开源 Agent 框架都把“热更新 Agent”当作核心卖点：上传新 JAR，不用重启服务，新逻辑立刻生效。听起来很美，但在企业交付现场，这恰恰是最大的风险源。某次我们为某政务系统上线，运维同学坚持要求所有变更必须走标准发布流程：代码提交 → CI 构建 → 静态扫描 → 安全审计 → UAT 测试 → 生产灰度 → 全量发布。当开发同学提出“这个小 bug 我热更新一下就行”，运维直接回复：“不行。热更新的 JAR 没过安全扫描，没走测试流程，出了问题算谁的？”

BizBuddy 的解决方案是：热更新不存在，只有“蓝绿插件部署”。每个 Agent 插件在bizbuddy-plugin.yml中声明version: 1.2.0，平台启动时会加载所有版本插件，但只激活latest标签指向的版本。当需要升级时，业务方发布新版本 JAR（如credit-rules-1.3.0.jar），然后通过管理 API 将latest标签切换到1.3.0。此时，新发起的 Flow 请求会使用新版本，而正在执行的旧 Flow 仍用旧版本，平滑过渡。整个过程，所有插件版本都经过完整流水线验证，变更可追溯、可回滚、有审计依据。

注意：这个设计依赖于ExecutionContext的不可变性。BizBuddy 要求所有AgentExecutor必须是无状态的，输入数据全部来自ExecutionContext，输出全部写入其中。这样，同一 Flow 实例在不同插件版本间切换时，不会因状态残留导致行为不一致。我们为此专门写了单元测试模板，强制检查ExecutionContext的序列化/反序列化一致性。

3.2 不支持“跨 JVM Agent 通信”：单 JVM 沙箱，边界即安全

另一个被否决的是“让不同 JVM 进程里的 Agent 直接通信”。有团队提出用 gRPC 或消息队列实现跨进程 Agent 协同，认为这样能解耦、能水平扩展。但我们算了一笔账：某银行核心系统要求单次信贷审批响应时间 < 800ms，而一次跨 JVM 调用（含序列化、网络传输、反序列化）平均耗时 120ms，如果流程涉及 5 个 Agent，光通信开销就占了 600ms，留给业务逻辑的时间所剩无几。更严重的是，跨 JVM 意味着故障域扩大——一个 Agent 进程挂了，整个 Flow 就断了，而单 JVM 内，我们可以通过ThreadLocal保存上下文、用CountDownLatch控制并发，故障隔离粒度细得多。

BizBuddy 的答案是：所有 Agent 必须部署在同一 JVM 内，通信走内存直传。但这不等于“所有 Agent 都能随便调用”。我们引入了PermissionBoundary机制：每个AgentExecutor在getRequiredPermissions()中声明所需权限（如"database:read:customer"、"api:call:llm-service"），平台 Runtime 在执行前校验当前ExecutionContext的用户权限是否满足。不满足？直接抛PermissionDeniedException，连网络请求都不会发出去。这样，既保证了高效，又通过权限模型实现了逻辑隔离。

这个取舍带来的额外好处是：性能压测变得极其简单。我们用 JMeter 直接对 BizBuddy 的 REST API 施压，所有 Agent 调用都在 JVM 内完成，瓶颈清晰可见——要么是 CPU（计算密集型 Agent），要么是 I/O（外部 API 调用），要么是锁竞争（共享资源访问）。没有网络抖动、没有序列化瓶颈、没有跨进程 GC 影响。某次压测发现，当并发量超过 1200 QPS 时，llmScorerExecutor的耗时陡增，排查发现是内部 HttpClient 连接池未调优，将maxConnPerRoute从默认 2 改为 20 后，TP99 从 1800ms 降到 420ms。这种“问题-定位-解决”的闭环速度，是跨 JVM 架构难以企及的。

4. 实战中的“血泪经验”：三个必须写进文档的避坑指南

BizBuddy 从第一个 PoC 到稳定支撑生产，踩过不少坑。有些是 Java 本身的“坑”，有些是 AI 工程化的新坑，但共同点是：官方文档几乎不提，社区讨论也很零散，全靠自己趟出来。这里分享三个最痛、也最值得写进项目 Wiki 的经验。

4.1 坑一：ThreadLocal泄漏导致内存溢出——别信“框架帮你清理”

BizBuddy 的ExecutionContext为了高性能，大量使用ThreadLocal存储临时上下文（如 traceId、用户凭证）。早期我们天真地认为，Spring 的ThreadPoolTaskExecutor会自动清理ThreadLocal。结果在高并发场景下，JVM 堆内存持续增长，jmap -histo显示ExecutionContext实例数高达 50 万+，而活跃 Flow 不到 5000。根源在于：线程池复用线程，ThreadLocal的remove()必须由业务代码显式调用，否则对象一直被线程持有。

解决方案很简单，但必须强制：所有AgentExecutor.execute()方法末尾，必须调用ExecutionContext.cleanup()。我们把它变成了一个 Checkstyle 规则，CI 流水线中，任何execute()方法如果没有cleanup()调用，直接构建失败。同时，在AgentFlow的FlowInstance执行结束时，增加兜底清理：

public class FlowInstance { public ExecutionResult run() { try { // ... 执行所有步骤 return result; } finally { // 强制清理所有 ThreadLocal ExecutionContext.clearAll(); } } }

经验：不要依赖框架的“自动清理”承诺。在 Java Agent 场景下，ThreadLocal是性能利器，也是内存泄漏高发区。把清理逻辑变成硬性规范，比事后调优省十倍精力。

4.2 坑二：JSON 序列化陷阱——ObjectMapper的默认配置会吃掉你的精度

BizBuddy 的ExecutionContext输入输出常是 JSON，我们用 JacksonObjectMapper。某次金融客户反馈，信贷评分结果的小数位总是被截断（如0.987654321变成0.987）。排查发现，ObjectMapper默认使用DoubleSerializer，其writeAsString()方法会调用Double.toString()，而后者对浮点数有精度截断逻辑。更隐蔽的是，BigDecimal字段在某些版本 Jackson 中会被序列化为科学计数法（1.23E+5），前端解析失败。

最终方案是：全局定制ObjectMapper，禁用所有默认精度处理：

@Bean @Primary public ObjectMapper objectMapper() { ObjectMapper mapper = new ObjectMapper(); // 禁用 Double 的 toString 截断 mapper.configure(JsonGenerator.Feature.WRITE_NUMBERS_AS_STRINGS, false); // BigDecimal 保持原样，不转科学计数法 mapper.configure(JsonGenerator.Feature.WRITE_BIGDECIMAL_AS_PLAIN, true); // 日期统一 ISO 8601 mapper.registerModule(new JavaTimeModule()); return mapper; }

但光这样还不够。我们要求所有AgentExecutor的输入输出 POJO，必须用@JsonSerialize显式标注序列化器，例如：

public class CreditScoreOutput { @JsonSerialize(using = BigDecimalToStringSerializer.class) private BigDecimal score; // 确保精确字符串传输 }

4.3 坑三：Agent 执行超时 ≠ HTTP 超时——必须分层设置熔断

BizBuddy 的AgentExecutor.getTimeoutSeconds()声明的是整个execute()方法的超时。但很多 Agent 内部会调用外部 HTTP 服务，如果只设execute()超时，一旦 HTTP 客户端卡在 TCP 握手或 DNS 解析，execute()的@TimeLimiter注解（基于 Resilience4j）根本无法生效——因为线程还没进入业务逻辑，还在阻塞等待网络。

正确做法是：三层超时叠加。以llmScorerExecutor为例：

• 第一层：HTTP Client 级超时（最底层）：OkHttpClient设置connectTimeout(5, SECONDS)、readTimeout(10, SECONDS)；
• 第二层：业务方法级超时（中间层）：@TimeLimiter注解作用于execute()方法，设为15s，覆盖网络超时+反序列化+业务处理；
• 第三层：Flow 级超时（最外层）：整个AgentFlow声明globalTimeout(30s)，防止某个步骤异常慢拖垮整条链。

这三层不是简单相加，而是形成“快速失败”链条：HTTP 层 5 秒连不上就报错，业务层 15 秒内必须返回，Flow 层 30 秒强制中断。我们在压测中故意将 LLM 服务延迟设为 25 秒，结果 Flow 在 30 秒整准时中断，日志清晰显示Flow timeout exceeded: 30s，而不是等到 25 秒后才开始处理超时逻辑。这种确定性，是企业系统最需要的。

这三个坑，每一个都曾让我们连续加班两天。现在，它们都固化为 BizBuddy 的“新人必读”文档，也是我们给客户交付时，一定会当面强调的“三条铁律”。技术选型可以讨论，但这些血泪教训，必须成为团队肌肉记忆。

5. BizBuddy 的“非功能”设计：为什么审计日志要存 180 天，为什么拒绝 GraphQL API

企业级系统，功能只是入场券，“非功能需求”才是护城河。BizBuddy 在设计之初，就把几个看似“不重要”的非功能点，提升到了和核心流程同等重要的位置。它们不直接产生业务价值，但一旦缺失，整个平台在客户眼中就失去了可信度。

5.1 审计日志保留策略：180 天不是拍脑袋，是合规倒推的结果

很多团队日志保留 7 天或 30 天，BizBuddy 定为 180 天。原因很实际：某次某医疗客户的安全审计，要求提供“过去半年内所有涉及患者数据的 AI 决策操作记录”。如果只存 30 天，我们只能尴尬地说“抱歉，日志已滚动删除”。180 天，是综合了国内《个人信息保护法》关于“保存期限应当为实现处理目的所必要的最短时间”的原则，以及金融、医疗等行业常见的“半年审计周期”得出的保守值。

技术实现上，我们没用 Elasticsearch（成本高、运维重），而是采用“冷热分离”：最近 7 天日志存于本地 SSD（/var/log/bizbuddy/hot/），供 Kibana 实时查询；7-180 天日志每日压缩为execution-events-20240515.gz，存入对象存储（如 MinIO 或 S3 兼容服务）。平台提供GET /api/v1/audit/events?start=2024-05-01&end=2024-05-10接口，后端自动路由到对应存储介质。关键点在于：所有日志写入即加密。我们用 AES-256-GCM 对ExecutionEvent的敏感字段（如input_hash对应的原始输入，如果标记为PII）进行加密，密钥由 KMS 托管，应用只持有密钥 ID。这样，即使对象存储被渗透，原始数据也无法还原。

5.2 拒绝 GraphQL，坚守 RESTful API：可预测性胜过灵活性

GraphQL 很火，尤其适合前端灵活取数。但 BizBuddy 的管理 API（如/flows/{id}/execute,/agents/{id}/versions）坚持 RESTful 设计。理由很朴素：企业客户的集成方，往往是运维脚本、Ansible Playbook、甚至 Excel VBA 宏。它们调用 API 的方式是固定的：curl -X POST -H "Content-Type: application/json" -d '{"input":{...}}' https://api.example.com/flows/credit/execute。GraphQL 需要构造复杂的 query 字符串，对这类工具极其不友好。

更重要的是，RESTful 的 URL 路径本身就是一种契约。/v1/flows/{flowId}/execute这个路径，清晰表达了“这是一个执行 Flow 的动作”，而 GraphQL 的mutation { executeFlow(input: {flowId: "credit", data: {...}}) }，把动作语义藏在了请求体里，对 API 文档生成、权限控制（如基于 URL 的网关鉴权）、流量分析都增加了复杂度。BizBuddy 的 API 网关（基于 Spring Cloud Gateway）直接按path做路由和限流，简单、高效、可审计。

我们妥协的地方是：在响应体中，提供fields参数支持部分字段返回（如GET /api/v1/flows?fields=id,name,status），这满足了大部分“减少带宽”的需求，又不破坏 REST 原则。

5.3 “零信任”健康检查：/actuator/health不只是 UP/DOWN

Spring Boot Actuator 的/actuator/health默认只返回{"status":"UP"}。BizBuddy 对此进行了深度改造，使其成为真正的“系统健康仪表盘”。访问GET /actuator/health?showDetails=true，会返回：

{ "status": "UP", "components": { "diskSpace": {"status":"UP","details":{"total":107374182400,"free":53687091200}}, "ping": {"status":"UP"}, "pluginLoader": {"status":"UP","details":{"loadedPlugins":12,"sandboxStatus":"SECURE"}}, "auditStorage": {"status":"UP","details":{"hotLogAgeMinutes":2,"coldLogAvailable":true}}, "llmAdapter": {"status":"UP","details":{"lastCallMs":142,"errorRate":0.002}} } }

每个组件的健康检查都是可插拔的。pluginLoader检查所有插件类加载器是否正常；auditStorage检查热日志目录是否可写、冷存储连接是否存活；llmAdapter不仅 ping 通，还统计最近 100 次调用的错误率和平均耗时。运维同学可以直接用这个接口做 Prometheus 抓取，也可以用它驱动自动化修复脚本（如llmAdapter错误率 > 5% 时，自动触发备用模型切换）。

这个设计源于一次真实故障：某次 LLM 服务不稳定，错误率飙升，但/actuator/health仍是UP，告警没触发，直到业务方投诉才被发现。现在，健康检查不再是“心跳”，而是“体检报告”。

这些“非功能”设计，没有一行代码直接处理业务逻辑，但它们共同构成了 BizBuddy 的企业级信任基石。客户愿意把核心业务流程交给一个平台，不是因为它能跑多快，而是因为它在 180 天后还能拿出完整的审计证据，因为它能让最古老的运维脚本无缝集成，因为它能在故障发生前就发出精准预警。这才是“企业级”三个字的真正分量。

6. 从 BizBuddy 到你的项目：一份可直接抄作业的启动清单

如果你正考虑在自己的团队中落地一个类似的 Agent Harness 平台，不必从零开始造轮子。基于 BizBuddy 的实践，我整理了一份“最小可行启动清单”，所有条目都经过生产验证，你可以按优先级逐步实施，每一步都有明确产出和验收标准。

6.1 第一阶段：奠基（1-2 周，目标：跑通一个 Hello World Agent）

• 任务 1：搭建纯净 Java 环境

  • 使用 JDK 17+（LTS 版本，避免预览特性）
  • Spring Boot 3.2.x（基于 Jakarta EE 9+，无 javax 包污染）
  • Maven 多模块结构：bizbuddy-core（核心契约）、bizbuddy-runtime（执行引擎）、bizbuddy-starter（自动装配）
  • ✅ 验收：mvn clean install通过，bizbuddy-starter可被其他 Spring Boot 项目@Import。

• 任务 2：定义第一个AgentExecutor

  • 创建接口com.bizbuddy.core.AgentExecutor（含execute(),getAgentId()等方法）
  • 实现一个HelloWorldAgent：输入name，输出{"greeting": "Hello, " + name}
  • 编写META-INF/bizbuddy-plugin.yml，声明agent-id: hello-world,version: 1.0.0
  • ✅ 验收：将HelloWorldAgent打包为 JAR，放入plugins/目录，启动应用后，GET /api/v1/agents返回该 Agent 信息。

• 任务 3：实现最简执行链

  • 创建SimpleAgentFlow类，内部持有一个List<AgentExecutor>
  • 编写FlowRunnerService，遍历列表，顺序调用execute()
  • 暴露POST /api/v1/flows/execute接口，接收 JSON 输入，返回执行结果
  • ✅ 验收：curl -X POST -d '{"name":"Alice"}' http://localhost:8080/api/v1/flows/execute返回{"greeting":"Hello, Alice"}。

6.2 第二阶段：加固（2-3 周，目标：具备基本企业级能力）

• 任务 4：接入插件隔离

  • 实现PluginClassLoader，重写findClass，加入java.lang.*白名单
  • 修改PluginLoader，为每个 JAR 创建独立PluginClassLoader
  • 在FlowRunner中，确保AgentExecutor实例从对应 ClassLoader 加载
  • ✅ 验收：两个不同版本的HelloWorldAgent（1.0.0 和 1.1.0）可共存，getAgentId()返回各自版本号。

• 任务 5：添加基础可观测性

  • 集成 Micrometer，暴露bizbuddy_agent_execution_seconds_count等指标
  • 实现ExecutionEventPOJO，包含flowId,stepId,status,durationMs
  • 使用ApplicationRunner初始化一个内存队列，AgentExecutor.execute()结束后，将ExecutionEvent发送到该队列
  • 编写后台线程，消费队列，打印日志（后续可替换为 Kafka）
  • ✅ 验收：执行一次 Flow，日志中出现结构化ExecutionEvent记录，Prometheus 可抓取指标。

• 任务 6：实现超时与熔断

  • 在FlowRunner中，为每个AgentExecutor.execute()调用包裹Resilience4j TimeLimiter
  • AgentExecutor接口新增getTimeoutSeconds()方法，HelloWorldAgent返回5
  • 配置TimeLimiterConfig，timeoutDuration=5s,cancelRunningFuture=true
  • ✅ 验收：人为在HelloWorldAgent.execute()中Thread.sleep(6000)，调用返回{"status":"FAILED","error":"TIMEOUT"}。

6.3 第三阶段：交付（2-4 周，目标：满足首次客户交付）

• 任务 7：审计日志持久化

  • 添加AuditEventRepository接口，实现InMemoryAuditEventRepository（开发用）和FileAuditEventRepository（生产用）
  • FileAuditEventRepository每日生成一个audit-events-20240515.jsonl文件（JSON Lines 格式，每行一个事件）
  • 配置 Logback，将ExecutionEvent同时输出到文件和控制台
  • ✅ 验收：执行 10 次 Flow，/var/log/bizbuddy/audit/下生成当日文件，每行是合法 JSON。

• 任务 8：权限模型雏形

  • 定义Permission枚举：READ_CUSTOMER,CALL_LLM_API,WRITE_OA
  • AgentExecutor新增getRequiredPermissions()方法，HelloWorldAgent返回空集合
  • FlowRunner在执行前，调用PermissionService.check(context.getUser(), executor.getRequiredPermissions())
  • PermissionService暂时硬编码：admin用户拥有所有权限
  • ✅ 验收：用非 admin 用户调用HelloWorldAgent（无需权限），成功；调用一个声明CALL_LLM_API的 Agent，返回403 Forbidden。

• 任务 9：生产就绪配置

  • application-prod.yml中配置：

    bizbuddy: plugin: directory: /opt/bizbuddy/plugins # 绝对路径，非 classpath audit: retention-days: 180 cold-storage: endpoint: https://minio.example.com bucket: bizbuddy-audit runtime: thread-pool: core-size: 20 max-size: 100

  • ✅ 验收：应用启动时，从/opt/bizbuddy/plugins加载插件，审计日志按配置滚动，线程池大小生效。

这份清单的价值，不在于它有多完美，而在于它足够“笨拙”——每一步都具体、可验证、无歧义。它不假设你有强大的 DevOps 团队，也不要求你第一天就搞定 Kafka 和 KMS。BizBuddy 的起点，就是一个能跑通HelloWorldAgent的 Spring Boot 应用。真正的企业级能力，是在一次次客户反馈、一次次线上问题、一次次安全审计中，像搭积木一样，一块一块垒起来的。你现在要做的，不是规划三年蓝图，而是打开 IDE，创建第一个AgentExecutor接口。剩下的，时间会给你答案。