@axiom-lattice/core 1.0.1

package/src/base/BaseLatticeManager.ts

@@ -0,0 +1,145 @@
+/**
+ * BaseLatticeManager - 抽象基类，为各种Lattice管理器提供通用功能
+ * 使用统一的Lattice注册表，不同类型的Lattice通过前缀区分
+ * @template TItem - 管理的项目类型
+ */
+export abstract class BaseLatticeManager<TItem = any> {
+  // 全局统一的Lattice注册表
+  protected static registry: Map<string, any> = new Map();
+
+  /**
+   * 受保护的构造函数，防止外部直接实例化
+   */
+  protected constructor() {
+    // 空实现
+  }
+
+  /**
+   * 获取管理器实例（由子类实现）
+   */
+  public static getInstance(): BaseLatticeManager<any> {
+    throw new Error("必须由子类实现");
+  }
+
+  /**
+   * 获取Lattice类型，用于构造键前缀
+   * 子类必须重写此方法以提供唯一的类型标识符
+   */
+  protected abstract getLatticeType(): string;
+
+  /**
+   * 构造完整的键名，包含类型前缀
+   * @param key 原始键名
+   */
+  protected getFullKey(key: string): string {
+    return `${this.getLatticeType()}.${key}`;
+  }
+
+  /**
+   * 注册项目
+   * @param key 项目键名（不含前缀）
+   * @param item 项目实例
+   */
+  public register(key: string, item: TItem): void {
+    const fullKey = this.getFullKey(key);
+    if (BaseLatticeManager.registry.has(fullKey)) {
+      throw new Error(`项目 "${fullKey}" 已经存在，无法重复注册`);
+    }
+
+    BaseLatticeManager.registry.set(fullKey, item);
+  }
+
+  /**
+   * 获取指定项目
+   * @param key 项目键名（不含前缀）
+   */
+  public get(key: string): TItem | undefined {
+    const fullKey = this.getFullKey(key);
+    return BaseLatticeManager.registry.get(fullKey) as TItem | undefined;
+  }
+
+  /**
+   * 获取所有当前类型的项目
+   */
+  public getAll(): TItem[] {
+    const prefix = `${this.getLatticeType()}.`;
+    const result: TItem[] = [];
+
+    for (const [key, value] of BaseLatticeManager.registry.entries()) {
+      if (key.startsWith(prefix)) {
+        result.push(value as TItem);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * 检查项目是否存在
+   * @param key 项目键名（不含前缀）
+   */
+  public has(key: string): boolean {
+    const fullKey = this.getFullKey(key);
+    return BaseLatticeManager.registry.has(fullKey);
+  }
+
+  /**
+   * 移除项目
+   * @param key 项目键名（不含前缀）
+   */
+  public remove(key: string): boolean {
+    const fullKey = this.getFullKey(key);
+    return BaseLatticeManager.registry.delete(fullKey);
+  }
+
+  /**
+   * 清空当前类型的所有项目
+   */
+  public clear(): void {
+    const prefix = `${this.getLatticeType()}.`;
+    const keysToDelete: string[] = [];
+
+    for (const key of BaseLatticeManager.registry.keys()) {
+      if (key.startsWith(prefix)) {
+        keysToDelete.push(key);
+      }
+    }
+
+    for (const key of keysToDelete) {
+      BaseLatticeManager.registry.delete(key);
+    }
+  }
+
+  /**
+   * 获取当前类型的项目数量
+   */
+  public count(): number {
+    const prefix = `${this.getLatticeType()}.`;
+    let count = 0;
+
+    for (const key of BaseLatticeManager.registry.keys()) {
+      if (key.startsWith(prefix)) {
+        count++;
+      }
+    }
+
+    return count;
+  }
+
+  /**
+   * 获取当前类型的项目键名列表（不含前缀）
+   */
+  public keys(): string[] {
+    const prefix = `${this.getLatticeType()}.`;
+    const prefixLength = prefix.length;
+    const result: string[] = [];
+
+    for (const key of BaseLatticeManager.registry.keys()) {
+      if (key.startsWith(prefix)) {
+        result.push(key.substring(prefixLength));
+      }
+    }
+
+    return result;
+  }
+}

package/src/base/index.ts

@@ -0,0 +1 @@
+export * from "./BaseLatticeManager";

package/src/createPlanExecuteAgent.ts

@@ -0,0 +1,475 @@
+import {
+  Annotation,
+  BaseCheckpointSaver,
+  END,
+  GraphInterrupt,
+  LangGraphRunnableConfig,
+  START,
+  StateGraph,
+  messagesStateReducer,
+} from "@langchain/langgraph";
+import {
+  BaseMessage,
+  HumanMessage,
+  mergeMessageRuns,
+} from "@langchain/core/messages";
+import { z } from "zod";
+import { ModelLattice } from "./model_lattice/ModelLattice";
+import { Logger } from "@logger/Logger";
+import { StateBaseType } from "./types";
+import { returnToolResponse } from "./util/returnToolResponse";
+import { returnAIResponse } from "./util/returnAIResponse";
+import { getLastHumanMessageData } from "./util/getLastHumanMessageData";
+import { tool } from "@langchain/core/tools";
+import { MemoryManager } from "./util/PGMemory";
+import { getModelLattice } from "./model_lattice/ModelLatticeManager";
+import { createReactAgent } from "@langchain/langgraph/prebuilt";
+
+/**
+ * Plan-and-Execute Agent 状态定义
+ */
+export const PlanExecuteState = Annotation.Root({
+  // 输入
+  input: Annotation<string>({
+    reducer: (x, y) => y ?? x ?? "",
+  }),
+  // 计划步骤列表
+  plan: Annotation<string[]>({
+    reducer: (x, y) => y ?? x ?? [],
+  }),
+  // 已执行的步骤 [步骤名称, 执行结果]
+  pastSteps: Annotation<[string, string][]>({
+    reducer: (x, y) => x.concat(y),
+    default: () => [],
+  }),
+  // 最终响应
+  response: Annotation<string | undefined>({
+    reducer: (x, y) => y ?? x,
+  }),
+  // 错误信息
+  error: Annotation<string | undefined>({
+    reducer: (x, y) => y ?? x,
+  }),
+  // 继承基础状态
+  "x-tenant-id": Annotation<number>(),
+  messages: Annotation<BaseMessage[]>({
+    reducer: messagesStateReducer,
+    default: () => [],
+  }),
+});
+
+/**
+ * 计划工具的结构化输出模式
+ */
+const planSchema = z.object({
+  steps: z.array(z.string()).describe("需要执行的步骤列表，应按照执行顺序排序"),
+});
+
+/**
+ * 响应工具的结构化输出模式
+ */
+const responseSchema = z.object({
+  response: z
+    .string()
+    .describe("给用户的最终响应，如果不需要执行步骤，则返回这个字段"),
+});
+
+/**
+ * Plan-and-Execute Agent 配置接口
+ */
+export interface PlanExecuteAgentConfig {
+  name: string;
+  description: string;
+  tools?: any[]; // 执行器可使用的工具
+  checkpointer?: false | BaseCheckpointSaver<number>;
+  llmManager?: ModelLattice;
+  logger?: Logger;
+  maxSteps?: number; // 最大步骤数限制
+  prompt?: string;
+}
+
+/**
+ * 创建 Plan-and-Execute Agent
+ *
+ * 这是一个规划-执行风格的代理，首先制定多步骤计划，然后逐一执行。
+ * 在完成每个任务后，会重新评估计划并根据需要进行修改。
+ *
+ * 相比传统的ReAct风格代理的优势：
+ * 1. 明确的长期规划能力
+ * 2. 可以在执行步骤使用较小的模型，只在规划步骤使用大模型
+ * 3. 更好的任务分解和执行追踪
+ */
+export function createPlanExecuteAgent(config: PlanExecuteAgentConfig) {
+  const {
+    name,
+    description,
+    tools: executorTools = [],
+    checkpointer,
+    llmManager,
+    logger,
+    maxSteps = 10,
+    prompt,
+  } = config;
+
+  const agentLogger =
+    logger || new Logger({ name: `PlanExecuteAgent:${name}` });
+  const llm = llmManager || getModelLattice("default")?.client;
+
+  if (!llm) {
+    throw new Error("LLM not found");
+  }
+
+  agentLogger.info(`初始化Plan-Execute代理: ${name}`, {
+    description,
+    maxSteps,
+    toolsCount: executorTools.length,
+  });
+
+  const agentExecutor = createReactAgent({
+    tools: executorTools,
+    llm: llm,
+  });
+
+  /**
+   * 规划步骤：创建初始计划
+   */
+  async function planStep(
+    state: typeof PlanExecuteState.State,
+    config: LangGraphRunnableConfig
+  ): Promise<Partial<typeof PlanExecuteState.State>> {
+    const input =
+      state.input || getLastHumanMessageData(state.messages)?.content;
+
+    const plannerPrompt = `${
+      prompt || ""
+    }\n针对给定的目标，制定一个简单的分步计划。
+这个计划应该包含独立的任务，如果正确执行将会得到正确的答案。不要添加多余的步骤。
+最后一步的结果应该是最终答案。确保每一步都有所需的所有信息 - 不要跳过步骤。
+
+可以使用的工具如下：
+${executorTools.map((tool) => tool.name).join("\n")}
+
+目标: ${input}`;
+
+    try {
+      const planResult = (await llm.invokeWithStructuredOutput(
+        [new HumanMessage(plannerPrompt)],
+        planSchema
+      )) as { steps: string[] };
+
+      const { messages } = await returnToolResponse(config, {
+        title: "我的计划",
+        content: planResult.steps.map((step: string) => step).join("\n\n"),
+        status: "success",
+      });
+
+      agentLogger.info("计划制定完成", { plan: planResult.steps });
+
+      return {
+        input: input as string,
+        plan: planResult.steps,
+        error: undefined,
+        messages,
+      };
+    } catch (error) {
+      const errorMsg = `计划制定失败: ${
+        error instanceof Error ? error.message : "未知错误"
+      }`;
+      agentLogger.error(errorMsg, { error });
+      return {
+        error: errorMsg,
+      };
+    }
+  }
+
+  /**
+   * 执行步骤：执行计划中的第一个任务
+   */
+  async function executeStep(
+    state: typeof PlanExecuteState.State,
+    config: LangGraphRunnableConfig
+  ): Promise<Partial<typeof PlanExecuteState.State>> {
+    if (!state.plan || state.plan.length === 0) {
+      agentLogger.warn("没有可执行的任务");
+      return { error: "没有可执行的任务" };
+    }
+
+    const currentTask = state.plan[0];
+    agentLogger.info("开始执行任务", { task: currentTask });
+
+    try {
+      // 这里可以集成真实的工具执行器
+      // 目前使用LLM来模拟执行
+      const executorPrompt = `执行以下任务并提供结果：
+
+任务: ${currentTask}
+
+上下文信息:
+- 原始目标: ${state.input}
+- 已完成的步骤: ${state.pastSteps
+        .map(([step, result]) => `${step}: ${result}`)
+        .join("\n")}
+
+请提供执行此任务的详细结果。`;
+
+      const executionResult = await agentExecutor.invoke({
+        messages: [new HumanMessage(executorPrompt)],
+      });
+
+      const resultContent =
+        executionResult.messages[executionResult.messages.length - 1].content;
+
+      // 生成工具响应消息
+      // const { messages } = await returnToolResponse(config, {
+      //   title: `执行任务: ${currentTask}`,
+      //   content: resultContent as string,
+      //   status: "success",
+      // });
+
+      return {
+        pastSteps: [[currentTask, resultContent]] as [string, string][],
+        plan: state.plan.slice(1), // 移除已执行的任务
+        //messages,
+        error: undefined,
+      };
+    } catch (error) {
+      if (error instanceof GraphInterrupt) {
+        throw error;
+      }
+      const errorMsg = `任务执行失败: ${
+        error instanceof Error ? error.message : "未知错误"
+      }`;
+      agentLogger.error(errorMsg, { task: currentTask, error });
+
+      // const { messages } = await returnToolResponse(config, {
+      //   title: `执行任务失败: ${currentTask}`,
+      //   content: errorMsg,
+      //   status: "error",
+      // });
+
+      return {
+        error: errorMsg,
+        //messages,
+      };
+    }
+  }
+
+  const responseTool = tool(
+    ({ response }: { response: string }) => {
+      return response;
+    },
+    {
+      name: "response",
+      description: "Respond to the user.",
+      schema: responseSchema,
+      returnDirect: true,
+    }
+  );
+
+  const planTool = tool(
+    ({ steps }: { steps: string[] }) => {
+      return steps.join("\n\n");
+    },
+    {
+      name: "plan",
+      description: "This tool is used to plan the steps to follow.",
+      schema: planSchema,
+      returnDirect: true,
+    }
+  );
+
+  const replanAgent = createReactAgent({
+    tools: [responseTool, planTool],
+    llm: llm,
+  });
+  /**
+   * 重新规划步骤：根据执行结果调整计划
+   */
+  async function replanStep(
+    state: typeof PlanExecuteState.State,
+    config: LangGraphRunnableConfig
+  ): Promise<Partial<typeof PlanExecuteState.State>> {
+    agentLogger.info("开始重新规划");
+
+    const replannerPrompt = `${
+      prompt || ""
+    }\n针对给定的目标，根据已执行的步骤来更新计划。
+这个计划应该包含独立的任务，如果正确执行将会得到正确的答案。不要添加多余的步骤。
+最后一步的结果应该是最终答案。确保每一步都有所需的所有信息 - 不要跳过步骤。
+
+你的目标是：
+${state.input}
+
+你的原始计划是：
+${state.plan.join("\n")}
+
+你目前已经完成了以下步骤：
+${state.pastSteps.map(([step, result]) => `${step}: ${result}`).join("\n")}
+
+Update your plan accordingly. If no more steps are needed and you can return to the user, then respond with that and use the 'response' function.
+Otherwise, fill out the plan.
+Only add steps to the plan that still NEED to be done. Do not return previously done steps as part of the plan.`;
+
+    try {
+      // 首先尝试获取最终响应
+      const responseResult = await replanAgent.invoke({
+        messages: [new HumanMessage(replannerPrompt)],
+      });
+
+      const toolCall =
+        responseResult.messages[responseResult.messages.length - 1];
+
+      if (toolCall?.name == "response") {
+        agentLogger.info("任务完成，提供最终响应");
+
+        const { messages } = await returnAIResponse(
+          config,
+          toolCall.content as string
+        );
+
+        return {
+          response: toolCall.content as string,
+          messages,
+          error: undefined,
+        };
+      } else if (toolCall?.name == "plan") {
+        let messages: any[] = [];
+        if (toolCall.content?.length > 0) {
+          messages = await returnToolResponse(config, {
+            title: "新的计划",
+            content: toolCall.content as string,
+            status: "success",
+          }).messages;
+        }
+        agentLogger.info("计划更新完成", { newPlan: toolCall.content });
+        return {
+          messages,
+          plan: (toolCall.content as string).split("\n\n"),
+          error: undefined,
+        };
+      } else {
+        return {
+          error: "重新规划失败",
+        };
+      }
+    } catch (error) {
+      if (error instanceof GraphInterrupt) {
+        throw error;
+      }
+      const errorMsg = `重新规划失败: ${
+        error instanceof Error ? error.message : "未知错误"
+      }`;
+      agentLogger.error(errorMsg, { error });
+      return {
+        error: errorMsg,
+      };
+    }
+  }
+
+  /**
+   * 判断是否应该结束执行
+   */
+  function shouldEnd(state: typeof PlanExecuteState.State): "end" | "continue" {
+    if (state.error) {
+      agentLogger.warn("因错误结束执行", { error: state.error });
+      return "end";
+    }
+
+    if (state.response) {
+      agentLogger.info("任务完成，结束执行");
+      return "end";
+    }
+
+    if (state.pastSteps.length >= maxSteps) {
+      agentLogger.warn("达到最大步骤数限制，结束执行", {
+        maxSteps,
+        currentSteps: state.pastSteps.length,
+      });
+      return "end";
+    }
+
+    if (!state.plan || state.plan.length === 0) {
+      agentLogger.info("计划为空，结束执行");
+      return "end";
+    }
+
+    return "continue";
+  }
+
+  // 构建状态图
+  const workflow = new StateGraph(PlanExecuteState)
+    .addNode("planner", planStep)
+    .addNode("executor", executeStep)
+    .addNode("replanner", replanStep)
+    .addEdge(START, "planner")
+    .addEdge("planner", "executor")
+    .addEdge("executor", "replanner")
+    .addConditionalEdges("replanner", shouldEnd, {
+      end: END,
+      continue: "executor",
+    });
+
+  // 编译图
+  //const memory = MemoryManager.getInstance();
+  const compiledGraph = workflow.compile({
+    checkpointer: checkpointer || MemoryManager.getInstance(),
+    name: `PlanExecuteAgent:${name}`,
+  });
+
+  agentLogger.info(`Plan-Execute代理编译完成: ${name}`);
+
+  return {
+    /**
+     * 执行代理
+     */
+    invoke: async (
+      input: { input: string; "x-tenant-id": number },
+      config?: LangGraphRunnableConfig
+    ) => {
+      agentLogger.info(`开始执行Plan-Execute代理: ${name}`, {
+        input: input.input,
+      });
+
+      try {
+        const result = await compiledGraph.invoke(input, config);
+        agentLogger.info(`代理执行完成: ${name}`);
+        return result;
+      } catch (error) {
+        agentLogger.error(
+          `代理执行失败: ${name}`,
+          error instanceof Error ? error : { error }
+        );
+        throw error;
+      }
+    },
+
+    /**
+     * 流式执行代理
+     */
+    stream: async (
+      input: { input: string; "x-tenant-id": number },
+      config?: LangGraphRunnableConfig
+    ) => {
+      agentLogger.info(`开始流式执行Plan-Execute代理: ${name}`, {
+        input: input.input,
+      });
+      return compiledGraph.stream(input, config);
+    },
+
+    /**
+     * 获取代理信息
+     */
+    getInfo: () => ({
+      name,
+      description,
+      type: "PlanExecuteAgent",
+      toolsCount: executorTools.length,
+      maxSteps,
+    }),
+
+    /**
+     * 获取编译后的图
+     */
+    getCompiledGraph: () => compiledGraph,
+  };
+}