CangjieMagic框架：使用华为仓颉编程语言编写，专门用于开发AI Agent，支持鸿蒙、Windows、macOS、Linux等系统。

这篇文章剖析一下 CangjieMagic 框架中的 PlanReactExecutor。

1 PlanReactExecutor的工作原理

当你要组织一场生日派对时，你会怎么做？你不会一头扎进去就开始准备，而是会先：

1. 了解寿星的喜好（知识提取）
2. 分解任务：场地、食物、娱乐、礼物（问题分解）
3. 一个个完成这些子任务（执行子任务）
4. 最后把所有准备工作整合起来，举办一场成功的派对（汇总结果）

PlanReactExecutor就是这样工作的！它不会直接尝试解决一个复杂问题，而是先分析、分解，然后一步步解决，最后整合答案。

2 深入代码：构造函数和核心组件

我们先来看看PlanReactExecutor的构造函数：

protected class PlanReactExecutor <: AgentExecutor {protected PlanReactExecutor() { }// 其他成员...
}

这个构造函数非常简单，它背后连接了几个强大的组件：

就像一个专业厨师虽然看起来很简单地做了一道菜，但背后有一套完整的厨具和步骤一样，PlanReactExecutor看似简单，实则整合了多个专业组件。

3 同步执行流程：像项目经理一样工作

现在，让我们看看同步执行函数的实现：

override public func run(agent: Agent, request: AgentRequest): AgentResponse {// Extract necessary knowledgelet knowledge = knowledgeExtract(agent, request)// Decompose the problemlet subtasks: Array<Subtask> = problemDecompose(agent, request)let planTask = PlanTask(agent, request, subtasks, knowledge)// Solve each subtaskfor (subtask in subtasks) {let worker = ReactWorker(planTask)let result = worker.solve(subtask)subtask.result = result}// Summarize the resultlet result = resultSummarize(planTask)LogUtils.info(agent.name, "Summarized answer: ${result}")return AgentResponse(result)
}

我们来用一个房屋装修的例子来理解这个过程：

1. 知识提取：就像设计师了解业主的喜好和需求

   let knowledge = knowledgeExtract(agent, request)
   

2. 问题分解：就像项目经理将装修分解为水电、木工、油漆等工序

   let subtasks: Array<Subtask> = problemDecompose(agent, request)
   

3. 创建计划任务：汇总需求和任务清单，形成施工方案

   let planTask = PlanTask(agent, request, subtasks, knowledge)
   

4. 执行每个子任务：安排工人团队依次完成各个工序

   for (subtask in subtasks) {let worker = ReactWorker(planTask)let result = worker.solve(subtask)subtask.result = result
   }
   

5. 汇总结果：整合所有工作，形成最终成果

   let result = resultSummarize(planTask)
   

6. 返回结果：向业主交付完工的房子

   return AgentResponse(result)
   

这个过程既有条理又高效，每个步骤都有明确的职责，就像一个专业的项目团队！

4 异步执行流程：实时查看进度的魔力

当我们需要实时查看任务执行进度时，就可以使用异步执行函数：

override public func asyncRun(agent: Agent, request: AgentRequest): AsyncAgentResponse {let planTask = PlanTask(agent, request)// Create the worker threadlet fut: Future<Iterator<String>> = spawn {try {return workFn(planTask)} catch(ex: Exception) {planTask.execInfo.verboseChannel.close()throw ex}throw UnsupportedException("Unreachable")}return AsyncAgentResponse(IteratorWrapper(planTask, fut), execInfo: planTask.execInfo)
}

这就像你在手机APP上订购一份外卖，可以实时看到"商家接单→厨师制作→骑手取餐→配送中→已送达"的全过程，而不是只能干等结果。

这里的关键是spawn表达式，它创建了一个新的工作线程来执行workFn函数，这样主线程就不会被阻塞。用生活中的例子来说，这就像你在餐厅点菜后，服务员会给你一个电子呼叫器，你可以去做其他事情，等菜好了会通知你。

5 workFn函数：异步工作的实际执行者

workFn函数是实际执行异步工作的地方，让我们仔细看看它的实现：

private func workFn(planTask: PlanTask): Iterator<String> {let agent = planTask.agentlet request = planTask.request// Extract necessary knowledgeplanTask.knowledge = knowledgeExtract(agent, request)// Decompose the problemlet subtasks: Array<Subtask> = problemDecompose(agent, request)planTask.subtasks = subtasksif (request.verbose) {let strBuilder = StringBuilder()strBuilder.append("# The Plan\n")for (subtask in subtasks) {strBuilder.append(subtask.toMarkdown())strBuilder.append("\n")}planTask.execInfo.verboseChannel.put(strBuilder.toString().withTag(ReactTag.PLAN))}// Solve each subtaskfor (subtask in subtasks) {if (request.verbose) {planTask.execInfo.verboseChannel.put("Solve the subtask: ${subtask.name}".withTag(ReactTag.PLAN))}let worker = ReactWorker(planTask)let asyncResp = worker.asyncSolve(subtask, verbose: request.verbose)if (request.verbose) {// Transfer the internal information from the react worker to this agentfor (data in asyncResp.execInfo.getOrThrow().verboseInfo) {planTask.execInfo.verboseChannel.put(data)}}subtask.result = asyncResp.contentif (request.verbose) {planTask.execInfo.verboseChannel.put("# Subtask DONE!\n${subtask.toMarkdown()}".withTag(ReactTag.INFO))}}if (request.verbose) {planTask.execInfo.verboseChannel.close()}// Summarize the resultreturn asyncResultSummarize(planTask)
}

让我们用一个建造乐高模型的例子来理解这个过程：

在这个过程中，最有价值的部分是用户可以看到计划和每个子任务的执行过程，这就是verbose模式的作用：

if (request.verbose) {let strBuilder = StringBuilder()strBuilder.append("# The Plan\n")for (subtask in subtasks) {strBuilder.append(subtask.toMarkdown())strBuilder.append("\n")}planTask.execInfo.verboseChannel.put(strBuilder.toString().withTag(ReactTag.PLAN))
}

这段代码就像是向用户展示乐高说明书的全貌，让用户知道接下来会发生什么。然后在执行每个子任务时，不断更新进度：

if (request.verbose) {planTask.execInfo.verboseChannel.put("Solve the subtask: ${subtask.name}".withTag(ReactTag.PLAN))
}

这就像是告诉用户"现在正在搭建城堡的塔楼部分"，让用户了解当前进度。

6 与其他执行器的对比

如果用餐厅来比喻三种执行器：

• NaiveExecutor：快餐店，直接点餐、直接出餐
• ReActExecutor：普通餐厅，厨师根据订单现做现卖
• PlanReactExecutor：高档餐厅，主厨先设计菜单，然后团队分工协作制作多道菜肴，最后组合成一顿完美的大餐

PlanReactExecutor最适合那些需要多步骤、多角度思考的复杂问题。

7 实际应用案例

案例一：学术研究助手

当用户请求研究神经网络的最新进展时，执行过程可能是：

案例二：旅行规划助手

想象一个用户想规划一次欧洲之旅：

用户: 请帮我规划一次为期7天的法国巴黎和意大利罗马的旅行，包括景点、住宿和交通。

使用PlanReactExecutor，执行过程可能是：

1. 知识提取：了解用户想去巴黎和罗马，时间为7天
2. 问题分解：
   • 子任务1：规划巴黎部分的行程（3天）
   • 子任务2：规划罗马部分的行程（3天）
   • 子任务3：规划两地之间的交通（1天）
   • 子任务4：提供住宿建议
   • 子任务5：整合完整行程
3. 执行每个子任务：分别解决每个子任务
4. 汇总结果：生成完整的7天旅行计划

案例三：复杂数学问题求解

用户: 请求解下列方程组：
3x + 2y - z = 10
2x - 3y + 2z = -5
x + y + z = 7

使用PlanReactExecutor解决这个问题：

1. 知识提取：确定这是一个三元一次方程组
2. 问题分解：
   • 子任务1：使用消元法消去z变量
   • 子任务2：解出x和y的关系
   • 子任务3：代回求解x、y、z的值
   • 子任务4：验证结果是否正确
3. 执行子任务：依次解决每个数学步骤
4. 汇总结果：提供完整的解答和解释

8 核心组件深度解析

PlanReactExecutor不是独立工作的，它依赖几个核心组件：

1. knowledgeExtract：就像研究生开始论文前的文献综述，先了解相关知识

2. problemDecompose：就像建筑师在开工前绘制详细的施工图纸

3. ReactWorker：就像专业工人按照图纸完成具体工作

4. resultSummarize：就像编辑将多篇文章整合成一本完整的书

这些组件协同工作，使得PlanReactExecutor能够处理非常复杂的问题。

9 PlanReactExecutor的优势与局限

优势：

1. 解决复杂问题：像专业律师处理复杂案件，有条不紊
2. 思路清晰：用户可以看到完整的思考过程，增强可信度
3. 结果全面：考虑问题的多个方面，不会遗漏重要内容
4. 可追踪性：出现问题可以定位到具体哪个子任务

局限：

1. 执行时间长：就像做一道复杂的菜肴，需要更多时间
2. 资源消耗大：需要更多的API调用和计算资源
3. 简单问题反而复杂化：用大炮打蚊子，对简单问题过度设计

10 何时选择PlanReactExecutor？

适合使用PlanReactExecutor的场景：

1. 多步骤问题：如规划旅行、制定学习计划
2. 需要多角度分析：如进行SWOT分析、评估风险
3. 需要综合信息：如撰写研究报告、市场分析
4. 组织创作内容：如写一本书的大纲、设计课程体系

不适合的场景：

1. 简单问答：如"今天天气怎么样"
2. 单一工具调用：如"计算123 + 456"
3. 快速响应场景：如紧急情况下的决策

11 总结

PlanReactExecutor就像一位经验丰富的项目经理，能够将复杂问题分解为可管理的小任务，然后一步步解决，最终整合成完整的解决方案。在处理复杂问题时，它的表现远超简单的执行器。

当你的AI应用需要处理复杂的多步骤问题时，不妨考虑使用PlanReactExecutor，它将帮助你的Agent像专业团队一样有条不紊地解决问题。