企业官网建设流程全解析

1. 项目概述：为什么一个叫“Pi Agent”的框架值得从源码开始读？

最近在几个大模型工程团队的内部分享会上，我连续三次被问到同一个问题：“你们现在用的Agent框架，底层到底是怎么把LLM调用、工具选择、记忆管理这几块串起来的？光看文档根本摸不清状态流转逻辑。”这让我想起去年刚接手一个智能体项目时踩过的坑——当时团队选了某开源Agent框架，表面看API简洁、文档漂亮，结果上线后发现任务失败时日志里全是抽象的“OrchestrationError”，连是工具执行超时、还是记忆检索返回了脏数据都定位不了。最后花三天时间翻源码，才搞明白它默认把所有工具调用结果无差别塞进短期记忆，导致后续推理token爆炸。这件事让我彻底意识到：对Agent框架的理解，不能停留在“会调API”这个层面；真正的掌控力，来自对调度器（Orchestrator）、记忆层（Memory Layer）、工具编排（Tool Routing）这三个核心模块的源码级认知。而“Pi Agent”这个名字，在近期GitHub趋势榜和国内技术社区讨论中出现频率极高，尤其在强调“轻量、可调试、适合私有化部署”的场景下，它和SpringBoot、若依（RuoYi）这类成熟框架被反复对比。它不是PyTorch那种底层计算框架，也不是pytest那种测试框架，而是一个典型的“LLM应用层胶水框架”——它的价值不在于发明新算法，而在于用清晰的分层设计，把大模型、工具、记忆、用户输入这些异构组件稳稳粘合在一起。我读它的源码，不是为了复刻一个轮子，而是想拆解出一套可迁移的Agent系统设计范式：比如它的状态机如何避免循环调用，它的记忆快照机制怎样平衡实时性与一致性，它的工具注册中心为何要区分同步/异步执行模式。这些细节，恰恰是多数文档刻意省略、但线上故障时最要命的部分。如果你正在评估Agent框架选型，或者已经卡在某个“调不通”的环节，这篇笔记就是为你写的——它不讲概念，只讲代码里真实发生的事。

2. 框架整体设计与思路拆解：三层架构如何解决Agent开发的核心矛盾？

2.1 核心矛盾：LLM的不可控性与业务系统的确定性需求

所有Agent框架的本质，都是在对抗一个根本矛盾：大语言模型（LLM）本身是概率性、非确定性的黑盒，而企业级应用要求可预测、可审计、可回滚的确定性行为。比如，一个客服Agent必须保证“用户问退款政策”时，99%以上概率触发“查询退款规则”工具，而不是随机调用“生成营销话术”工具；一次金融风控Agent的决策过程，必须能完整追溯到哪条记忆片段影响了最终判断。Pi Agent的源码设计，正是围绕这个矛盾展开的。它没有试图去“驯服”LLM，而是构建了一套精密的“围栏系统”——在LLM周围部署调度器、记忆层、工具层三道防线，把LLM的输出严格约束在预设的轨道内。这种思路和SpringBoot的“约定优于配置”哲学一脉相承：不强制你写无数if-else去校验LLM输出，而是通过框架层的结构设计，让错误输出根本无法进入关键业务流程。

2.2 三层架构解析：Orchestrator、Memory、Tool的职责边界

翻开Pi Agent的src/main/java/com/pi/agent/目录，你能立刻看到三个平行包：orchestrator、memory、tool。这不是随意的文件夹划分，而是整个框架的脊柱。我逐行读完核心类后，确认它们的职责边界比文档描述得更锋利：

• Orchestrator（调度器）：它绝不是简单的“调用LLM然后解析JSON”。源码显示，它内部维护着一个轻量级状态机（基于StateTransition枚举），每个状态对应一个明确的生命周期节点：RECEIVE_INPUT→SELECT_TOOL→EXECUTE_TOOL→UPDATE_MEMORY→GENERATE_RESPONSE。关键点在于，状态流转由显式事件驱动，而非隐式条件判断。比如SELECT_TOOL状态不会直接调用LLM，而是先检查当前记忆中是否存在缓存的工具匹配结果（这是为后续支持离线推理埋的伏笔）；只有缓存未命中时，才构造特定格式的Prompt发给LLM。这种设计让调试变得极其简单——你只需在状态机入口打个断点，就能清晰看到Agent每一步“思考”的触发条件。

• Memory（记忆层）：这里最反直觉的设计是它主动拒绝“全量记忆”。很多框架把用户历史对话一股脑塞进LLM上下文，导致token浪费和噪声干扰。Pi Agent的MemoryManager类里，getRelevantContext()方法实现了一个两级过滤：第一级用向量相似度（默认集成ChromaDB）粗筛出Top-5记忆片段；第二级用规则引擎（基于Drools轻量版）精筛，例如“仅保留标记为CRITICAL且时间戳在24小时内的订单信息”。这意味着，即使你的记忆库有10万条记录，每次LLM调用看到的上下文也严格控制在300token以内。我在测试时故意注入一条错误记忆，发现它从未出现在任何一次LLM输入中——因为规则引擎的priority字段把它标为LOW，直接被第二级过滤掉了。

• Tool（工具层）：它的注册机制暴露了框架的务实哲学。ToolRegistry类里没有复杂的SPI扩展，而是采用@Tool注解+手动注册双模式。重点在于ToolDefinition类中的executionMode字段，它只有两个值：SYNC（同步阻塞）和ASYNC（异步回调）。源码注释明确写着：“SYNC适用于毫秒级响应的本地工具（如Excel处理、字符串清洗）；ASYNC强制要求实现CallbackHandler接口，用于调用外部HTTP服务或数据库查询，框架会自动管理超时和重试”。这种硬性区分，直接杜绝了“把数据库查询写成同步工具导致整个Agent线程池被拖垮”的经典事故。我实测过，当一个ASYNC工具因网络抖动超时时，调度器会自动降级到备用工具（如果配置了fallbackToolId），而不是抛出异常中断流程。

2.3 与主流框架的关键差异：为什么不是另一个“若依”或“SpringBoot”？

很多人初看Pi Agent，会下意识拿它和若依（RuoYi）或SpringBoot对比，这是方向性误解。若依是面向传统CRUD业务的后台管理系统框架，SpringBoot是Java生态的通用应用脚手架，而Pi Agent是专为LLM交互生命周期定制的状态协调框架。这种差异体现在三个硬核设计上：

1. 无Web容器依赖：Pi Agent的Orchestrator类不继承任何Servlet或Spring Bean，它就是一个纯POJO。你可以把它嵌入到任何进程里——无论是SpringBoot Web应用、命令行工具，甚至一个Qt上位机程序。它的execute()方法接收AgentInput对象，返回AgentOutput对象，完全解耦于传输层。这解释了为什么搜索热词里会出现“qt mvvm框架”和“c# 上位机通用框架”的关联——开发者真在这么做。

2. 记忆即服务（Memory-as-a-Service）：不同于若依把数据存在MySQL里，Pi Agent的记忆层设计成可插拔的“服务”。MemoryProvider接口只有两个方法：save(MemoryEntry)和search(String query)。源码里已内置ChromaDB、Redis、甚至一个内存版InMemoryMemoryProvider。当你切换application.yml里的pi.agent.memory.type: redis时，框架自动加载RedisMemoryProvider，所有记忆操作无缝迁移到Redis集群。这种设计，让“agent记忆框架以及选型”这个热词有了落脚点——它不绑定具体技术，只定义契约。

3. 工具编排的声明式语法：Pi Agent没有像某些框架那样要求你写复杂DSL来定义工作流。它的tool.yaml配置文件极其简洁：

   tools: - id: "excel_processor" class: "com.pi.tool.ExcelProcessor" executionMode: SYNC description: "处理用户上传的Excel表格，提取关键数据" inputSchema: fileUrl: "string" outputSchema: extractedData: "array"

   这种YAML即代码（YAML-as-Code）的设计，让非Java工程师（比如Python背景的数据分析师）也能快速理解并贡献工具。我在一个客户现场看到，他们的BI团队直接用这个格式定义了5个数据清洗工具，Java后端团队零干预就完成了集成。

3. 核心细节解析与实操要点：从AgentInput到AgentOutput的7个关键节点

3.1 节点1：AgentInput的结构设计——为什么必须包含sessionId和traceId

打开AgentInput.java，你会看到除了基础的userQuery、context字段外，还有两个看似冗余的字段：sessionId和traceId。源码注释里有一句关键说明：“sessionId用于跨请求记忆关联，traceId用于全链路追踪，二者缺一不可”。这背后是生产环境的真实痛点：当用户说“把刚才查的订单再发我邮箱”，Agent必须知道“刚才”指的是哪个会话里的哪次查询。Pi Agent的解决方案是，在Orchestrator.execute()入口处，强制校验sessionId是否存在于MemoryProvider中。如果不存在，框架会自动创建一个空记忆空间，并用traceId标记本次请求的唯一性。我在压测时故意删除Redis里的部分session数据，发现框架会优雅降级——它不报错，而是将sessionId映射到一个临时内存记忆区，确保单次请求不中断，同时记录告警日志“Session fallback to in-memory”。

提示：traceId的生成逻辑在TraceIdGenerator类中，它不是简单UUID，而是采用[service]-[timestamp]-[counter]格式（如pi-agent-1715823456000-001）。这种设计让运维人员在ELK日志里能直接按前缀过滤Pi Agent的所有日志，无需额外解析。

3.2 节点2：ToolSelector的决策逻辑——LLM Prompt如何被“安全封装”

ToolSelector是调度器里最敏感的模块，它负责把用户问题翻译成工具ID。很多人以为这里只是发个Prompt让LLM选工具，但源码揭示了更精细的控制：

• Prompt模板的三段式结构：ToolSelectionPromptTemplate类定义了固定结构：

  1. System Message：明确指令“你只能从以下工具列表中选择一个，禁止虚构工具名”
  2. Context Section：注入当前记忆的摘要（非全文！），格式为[记忆ID] <摘要文本>
  3. User Query：原始用户输入，末尾追加Available Tools: [tool1, tool2, ...]

• 安全兜底机制：selectTool()方法里有个if (llmResponse.toLowerCase().contains("none"))判断。当LLM返回“None of the above”时，框架不抛异常，而是触发FallbackToolSelector，它会基于关键词匹配（正则表达式）做二次选择。比如用户问“Excel怎么转PDF”，LLM可能因训练数据不足返回“None”，但正则"excel.*pdf|pdf.*excel"会命中excel_converter工具。这个设计让Agent在LLM能力边界外依然保持可用性。

3.3 节点3：ToolExecutor的同步/异步分流——线程池如何被精准管控

ToolExecutor类是性能关键点。源码显示，它内部维护两个独立线程池：

• syncThreadPool：固定大小为CPU核心数×2，专供SYNC工具
• asyncThreadPool：动态大小（核心线程数=4，最大=32），专供ASYNC工具

更关键的是executeTool()方法里的分流逻辑：

if (toolDefinition.getExecutionMode() == SYNC) { return syncThreadPool.submit(() -> tool.invoke(input)).get(); } else { // 异步工具必须实现CallbackHandler return asyncThreadPool.submit(() -> { tool.invokeAsync(input, new ToolCallback() { @Override public void onSuccess(Object result) { // 结果存入临时存储，供后续状态机读取 tempResultStore.put(traceId, result); } }); }); }

这种设计杜绝了常见陷阱：比如把一个HTTP调用工具误标为SYNC，导致线程池被耗尽。我在一个电商项目里实测过，当asyncThreadPool满载时，新来的异步工具调用会被自动排队，而同步工具调用完全不受影响——这对保障核心业务（如实时库存查询）的SLA至关重要。

3.4 节点4：MemoryUpdater的原子性保障——为什么不用数据库事务

MemoryUpdater.update()方法的实现令人印象深刻。它没有用JDBC事务，而是采用内存快照+异步持久化策略：

1. 首先，MemoryUpdater从MemoryProvider读取当前会话的完整记忆快照（List<MemoryEntry>）
2. 然后，在内存中应用本次更新（新增/修改/删除条目）
3. 最后，启动一个独立线程，将更新后的快照批量写入MemoryProvider

这种设计牺牲了强一致性，但换来了高吞吐。源码注释解释：“Agent记忆不要求ACID，但要求低延迟和高可用。快照机制确保即使持久化失败，内存中的最新状态仍可服务下一次请求”。我在Redis配置错误导致写入失败时，观察到Agent依然正常响应，只是日志里多了条WARN Memory persist failed, using in-memory state。这种“优雅降级”思维，正是生产级框架的标志。

3.5 节点5：ResponseGenerator的防幻觉机制——Prompt Engineering的硬编码实践

ResponseGenerator.generate()方法里藏着对抗LLM幻觉的杀手锏。它不直接把LLM原始输出返回给用户，而是执行三重过滤：

• 引用验证：检查LLM回复中是否包含[source:xxx]格式的引用标记，然后反向验证xxx是否真实存在于本次记忆检索结果中。如果引用不存在，自动替换为[数据来源待确认]。
• 事实锚定：对回复中的数值型陈述（如“订单金额是¥199”），调用FactAnchoringEngine比对记忆中的原始订单数据。不匹配则触发CONFIRMATION_REQUIRED状态，要求用户确认。
• 情感缓冲：内置一个轻量级情感词典（emotion-dict.txt），当检测到回复含“绝对”、“肯定”、“100%”等绝对化词汇时，自动添加软化语句：“根据当前信息，我们判断...”。

我在测试时故意让LLM编造一个不存在的优惠券代码，发现它被第一重过滤拦截，回复变成了“关于您提到的‘SUMMER2024’优惠券，系统中暂未查询到相关信息”。这种不依赖外部评测框架（如DeepEval）的内置防护，极大降低了幻觉风险。

3.6 节点6：AgentOutput的结构化输出——为什么nextAction字段比responseText更重要

AgentOutput类里，nextAction字段的权重远高于responseText。源码中Orchestrator的execute()方法最后一步是：

return AgentOutput.builder() .responseText(generatedText) .nextAction(determineNextAction()) // 关键！ .traceId(input.getTraceId()) .build();

determineNextAction()方法返回一个NextAction枚举，值包括：WAIT_FOR_USER_INPUT、CONTINUE_EXECUTION、TERMINATE、REQUIRE_CONFIRMATION。这个设计让前端可以做出智能响应：当nextAction是REQUIRE_CONFIRMATION时，UI自动弹出确认框；是WAIT_FOR_USER_INPUT时，禁用发送按钮直到用户输入。这比单纯返回一段文字高级得多——它把Agent的“思考状态”显式暴露给了整个系统。我在一个医疗咨询项目里，利用这个字段实现了“诊断建议→患者确认→开具处方”的三步闭环，完全规避了传统聊天界面中用户乱发消息导致流程错乱的问题。

3.7 节点7：错误处理的分级策略——从ToolException到OrchestratorException

Pi Agent的异常体系是分层的，每一层都有明确的处置责任：

这种分级让问题定位极快。比如线上出现大量ToolException，运维直接查日志就能定位到具体哪个工具不稳定；如果是MemoryException频发，则立刻检查Redis集群健康度。我在一个银行项目里，曾用这个机制在5分钟内定位到第三方征信API的熔断阈值设置过低的问题——所有异常都归类为ToolException，且toolId字段明确指向credit-report-api。

4. 实操过程与核心环节实现：手把手搭建一个可调试的Pi Agent实例

4.1 环境准备：最小化依赖与IDE调试配置

Pi Agent的构建非常轻量，官方推荐使用Maven 3.8+和JDK 11。但要注意一个隐藏坑：它默认不兼容JDK 17的强封装特性。源码pom.xml里maven-compiler-plugin的配置指定了--add-opens java.base/java.lang=ALL-UNNAMED，这是为了解决某些LLM客户端（如Ollama Java SDK）的反射限制。如果你用JDK 17+，必须在IDE的运行配置里手动添加这个JVM参数，否则启动时会报InaccessibleObjectException。

我推荐的调试环境组合是：

• IDE：IntelliJ IDEA 2023.3（社区版足够）
• LLM后端：本地Ollama（ollama run llama3），避免网络依赖
• 记忆存储：ChromaDB（Docker一键启动：docker run -p 8000:8000 --name chroma -d chromadb/chroma）

注意：不要用HuggingFace的Transformers直接加载大模型！Pi Agent的LlmClient接口设计是面向REST API的，它假设LLM服务提供标准OpenAI兼容接口。Ollama的/v1/chat/completions端点完美匹配，而Transformers需要额外写适配器，徒增复杂度。

4.2 步骤1：创建基础Agent项目（5分钟完成）

用Maven Archetype快速生成骨架：

mvn archetype:generate \ -DgroupId=com.example \ -DartifactId=pi-agent-demo \ -DarchetypeArtifactId=maven-archetype-quickstart \ -DinteractiveMode=false

然后在pom.xml中添加Pi Agent核心依赖（注意版本号，截至2024年5月最新稳定版是1.2.0）：

<dependency> <groupId>com.pi</groupId> <artifactId>pi-agent-core</artifactId> <version>1.2.0</version> </dependency> <!-- 内存提供者 --> <dependency> <groupId>com.pi</groupId> <artifactId>pi-agent-memory-chroma</artifactId> <version>1.2.0</version> </dependency> <!-- LLM客户端 --> <dependency> <groupId>com.pi</groupId> <artifactId>pi-agent-llm-ollama</artifactId> <version>1.2.0</version> </dependency>

关键点：pi-agent-llm-ollama模块里已经封装了Ollama的HTTP调用逻辑，你不需要自己写OkHttp代码。

4.3 步骤2：编写第一个工具——Excel处理器（含完整异常处理）

创建ExcelProcessor.java，实现Tool接口：

@Tool(id = "excel_analyzer", description = "分析Excel文件，提取销售数据") public class ExcelProcessor implements Tool { @Override public Object invoke(ToolInput input) throws ToolException { try { String fileUrl = input.getString("fileUrl"); // 1. 下载文件（生产环境应加超时和重试） byte[] fileBytes = downloadFile(fileUrl); // 2. 解析Excel（使用Apache POI） Workbook workbook = WorkbookFactory.create(new ByteArrayInputStream(fileBytes)); Sheet sheet = workbook.getSheetAt(0); // 3. 提取关键列（假设A列是产品名，B列是销售额） List<Map<String, Object>> results = new ArrayList<>(); for (Row row : sheet) { if (row.getRowNum() == 0) continue; // 跳过标题行 String productName = row.getCell(0).getStringCellValue(); double salesAmount = row.getCell(1).getNumericCellValue(); results.add(Map.of("product", productName, "sales", salesAmount)); } workbook.close(); return Map.of("analysisResult", results, "totalRows", results.size()); } catch (IOException e) { throw new ToolException("Excel文件下载失败", e); } catch (InvalidFormatException e) { throw new ToolException("Excel文件格式无效，请检查是否为.xlsx或.xls", e); } catch (Exception e) { throw new ToolException("Excel解析异常", e); } } private byte[] downloadFile(String url) throws IOException { // 生产环境应使用HttpClient并配置连接池 return Files.readAllBytes(Paths.get(url.replace("file://", ""))); } }

实操心得：这个工具里throw new ToolException(...)是关键。如果这里直接抛RuntimeException，框架会捕获为OrchestratorException，导致整个Agent流程终止。而ToolException会被正确识别，触发重试或降级逻辑。

4.4 步骤3：配置记忆与LLM——application.yml的黄金参数

src/main/resources/application.yml是性能调优的核心：

pi: agent: # 记忆配置 memory: type: chroma chroma: host: http://localhost:8000 collectionName: pi-agent-demo # LLM配置 llm: type: ollama ollama: baseUrl: http://localhost:11434 model: llama3 # 关键！控制LLM的“思考深度” temperature: 0.3 # 降低随机性 maxTokens: 1024 # 防止token爆炸 # 工具配置 tool: # 同步工具线程池大小 syncThreadPoolSize: 8 # 异步工具超时（毫秒） asyncTimeoutMs: 30000

参数原理：temperature: 0.3不是拍脑袋定的。我做过AB测试：当temperature=0.7时，工具选择准确率只有68%（LLM太“发散”）；降到0.3后提升到92%，因为LLM更倾向于选择训练数据中高频出现的工具。maxTokens: 1024则源于对记忆摘要长度的测算——ChromaDB返回的Top-5摘要平均长度约320token，留出700token给LLM生成回复，刚好够用。

4.5 步骤4：启动调试——在IDE中设置断点的黄金位置

在IntelliJ中，最关键的三个断点位置是：

1. Orchestrator.execute()入口：观察AgentInput的完整结构，特别是sessionId和traceId的生成逻辑。
2. ToolSelector.selectTool()内部：查看LLM返回的原始JSON，对比ToolSelectionPromptTemplate生成的Prompt，理解LLM是如何被引导的。
3. MemoryUpdater.update()方法末尾：检查tempResultStore里是否存入了正确的工具执行结果，这是验证异步工具是否真正生效的唯一证据。

避坑技巧：第一次调试时，务必在ToolSelector断点处开启“Force Return”，手动返回一个已知的toolId（如"excel_analyzer"）。这样可以绕过LLM调用，快速验证工具执行和记忆更新流程是否通畅。等这三步都走通了，再放开LLM调用。

4.6 步骤5：运行与验证——用curl发起一个端到端请求

启动应用后，用curl模拟用户请求：

curl -X POST http://localhost:8080/agent \ -H "Content-Type: application/json" \ -d '{ "userQuery": "分析这个Excel文件：file:///tmp/sales_data.xlsx", "sessionId": "demo-session-001", "traceId": "demo-trace-001" }'

预期返回：

{ "responseText": "已成功分析Excel文件，共提取127条销售记录。其中'智能手表'销售额最高，达¥245,800。", "nextAction": "WAIT_FOR_USER_INPUT", "traceId": "demo-trace-001" }

验证要点：检查Redis或ChromaDB，确认demo-session-001的记忆中已存入excel_analyzer的执行结果。这才是Agent“记住”了这次分析的证据，而不是仅仅返回了一段文字。

5. 常见问题与排查技巧实录：那些文档里永远不会写的实战经验

5.1 问题1：LLM总是选错工具，ToolSelector返回null

现象：日志里频繁出现WARN ToolSelector returned null, falling back to keyword matching，且关键词匹配也经常失败。

排查路径：

1. 首先检查tool.yaml里工具的description字段——它不是给人看的，而是给LLM当提示词用的！必须包含典型用户问法。比如excel_analyzer的description应该写成：“分析Excel表格内容，提取销售数据、产品名称、订单数量等信息。用户可能说‘看看这个Excel’、‘统计销售额’、‘导出数据’”。
2. 其次验证Prompt构造：在ToolSelector断点处，复制完整的Prompt到Ollama Web UI里手动测试。我遇到过一次，发现是因为context部分注入了过长的记忆摘要（超过500字符），导致LLM注意力被分散。解决方案是在MemoryManager里增加摘要长度截断逻辑。
3. 最后检查LLM模型能力：Llama3在工具选择任务上表现一般。换成phi3模型后，准确率从72%提升到89%。这不是框架问题，而是模型选型问题。

实操心得：永远不要相信LLM的“智能”，要把它当成一个需要精心喂养的工具。description字段就是它的“饲料”，越精准，产出越可靠。

5.2 问题2：异步工具执行后，nextAction始终是WAIT_FOR_USER_INPUT

现象：excel_analyzer明明是ASYNC模式，但Agent执行完就停住，不继续生成回复。

根因分析：ToolExecutor的异步回调机制依赖tempResultStore，而这个存储是ConcurrentHashMap实现的。如果traceId在不同线程间传递时被修改（比如前端没透传），回调线程就找不到对应的traceId，结果被丢弃。我在一个Vue3项目里遇到过，因为Axios拦截器自动给请求加了X-Request-ID头，后端误把X-Request-ID当成了traceId。

解决方案：

• 在application.yml里强制指定traceIdHeaderName: X-Trace-ID
• 在ToolCallback.onSuccess()里，打印Thread.currentThread().getName()，确认回调是否真的在asyncThreadPool线程里执行
• 添加监控：在tempResultStore的put()方法里埋点，记录traceId的存入和读取次数，不平衡就说明有丢失

5.3 问题3：记忆检索返回无关结果，getRelevantContext()失灵

现象：用户问“上个月的订单”，记忆里却返回了三年前的退货记录。

深度排查：

1. 检查MemoryEntry的metadata字段：Pi Agent要求每个记忆条目必须有timestamp和category。如果timestamp是字符串格式（如"2024-05-01"），而ChromaDB的向量搜索默认按字符串排序，就会失效。必须确保timestamp是毫秒级Long类型。
2. 验证向量模型：pi-agent-memory-chroma默认用sentence-transformers/all-MiniLM-L6-v2，但它对中文日期理解很弱。换成bge-m3模型后，时间相关检索准确率提升40%。
3. 查看Drools规则：priority字段的值必须是数字，不能是字符串。我见过一次配置错误：priority: "HIGH"（字符串）导致规则引擎跳过所有过滤。

速查表：记忆检索问题排查清单

5.4 问题4：Orchestrator状态机卡在SELECT_TOOL，CPU占用100%

现象：应用启动后，某个sessionId的请求一直卡住，jstack显示大量线程在ToolSelector.selectTool()里死循环。

终极原因：ToolSelector的maxRetries默认是3，但每次重试都用相同的Prompt。当LLM持续返回无效格式（如{"tool": "unknown"}）时，框架会无限重试。源码里有个隐藏开关：pi.agent.tool.selector.maxRetries，必须在application.yml里显式配置为1或2。

我的修复方案：

pi: agent: tool: selector: maxRetries: 2 # 启用降级：当LLM失败时，用正则匹配 enableKeywordFallback: true

同时，在ToolSelector里增加一个retryCount计数器，超过阈值后强制返回FallbackToolSelector的结果。这个补丁我已提交到Pi Agent的GitHub Issue #287，等待官方合并。

5.5 问题5：本地调试时Ollama响应慢，asyncTimeoutMs频繁触发

现象：excel_analyzer工具执行很快，但LLM调用总超时，日志里全是WARN Async tool execution timeout。

真相：Ollama的/v1/chat/completions接口默认启用stream: true，而Pi Agent的OllamaLlmClient是同步等待完整响应的。当LLM生成长回复时，HTTP连接会因心跳超时被关闭。

一劳永逸的解决办法：

1. 修改OllamaLlmClient的invoke()方法，在RequestBody里强制添加"stream": false
2. 或者更简单：在application.yml里配置pi.agent.llm.ollama.streamEnabled: false
3. 如果必须用流式，需重写OllamaLlmClient，用OkHttp的EventSource处理SSE流

我在一个客户现场，就是靠这个配置把平均响应时间从8.2秒降到1.4秒。记住：流式输出对用户体验好，但对Agent框架的稳定性是毒药。除非你有充分理由，否则关掉它。

6. 框架选型延伸思考：Pi Agent在“Agent框架与编排”生态中的真实定位

6.1 与“若依+Vue3框架”对比：不是替代，而是嵌入

搜索热词里频繁出现“若依+vue3框架下载”，这揭示了一个现实：很多团队已有成熟的若依后台，现在想给它加上Agent能力。Pi Agent的轻量设计让它成为最佳嵌入选项。我帮一个政务系统做的方案是：在若依的ruoyi-admin模块里，新增一个/api/agent接口，其内部逻辑就是创建Orchestrator实例并调用execute()。前端Vue3页面通过Axios调用这个接口，完全不感知Pi Agent的存在。这种“能力注入”模式，比推倒重做一个Agent平台风险低得多。若依负责用户管理、权限控制、菜单配置，Pi Agent专注LLM交互，各司其职。

6.2 与“pytest框架”协同：如何为Agent编写可靠的自动化测试

Agent的不确定性让传统单元测试失效。Pi Agent的源码里其实预留了测试钩子：TestOrchestrator类继承自`Orchestrator