【仓颉 + 鸿蒙 + AI Agent】CangjieMagic框架（17）：PlanReactExecutor

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

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

1 PlanReactExecutor的工作原理

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

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

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)
}

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

知识提取：就像设计师了解业主的喜好和需求
```
let knowledge = knowledgeExtract(agent, request)
```
问题分解：就像项目经理将装修分解为水电、木工、油漆等工序
```
let subtasks: Array<Subtask> = problemDecompose(agent, request)
```
创建计划任务：汇总需求和任务清单，形成施工方案
```
let planTask = PlanTask(agent, request, subtasks, knowledge)
```

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

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

汇总结果：整合所有工作，形成最终成果
```
let result = resultSummarize(planTask)
```
返回结果：向业主交付完工的房子
```
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，执行过程可能是：

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

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

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

使用PlanReactExecutor解决这个问题：

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

8 核心组件深度解析

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

knowledgeExtract：就像研究生开始论文前的文献综述，先了解相关知识
problemDecompose：就像建筑师在开工前绘制详细的施工图纸
ReactWorker：就像专业工人按照图纸完成具体工作
resultSummarize：就像编辑将多篇文章整合成一本完整的书

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

9 PlanReactExecutor的优势与局限

优势：

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

局限：

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

10 何时选择PlanReactExecutor？

适合使用PlanReactExecutor的场景：

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

不适合的场景：

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

11 总结

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

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