audio_codebuddy/借鉴openmaic.md

LangGraph 本项目 vs OpenMAIC-main 实现对比与借鉴

一、核心架构区别

维度	LangGraph (本项目)	OpenMAIC-main
流程框架	使用 @langchain/langgraph 官方库，状态流由框架控制	自定义工作流，类似但非 LangGraph 库
状态管理	LangGraph StateGraph + Annotation，状态在节点间传递	内存 Map 存储状态，Phase 阶段控制
执行模式	流式 graph.stream()，每个 step 可观测	顺序执行 + 回调 onProgress

---

二、流程设计对比

LangGraph 流程

generate_outline → write_chapters → write_foreword → write_afterword → END

• 固定顺序，无分支
• 节点返回 Partial<State> 更新状态

OpenMAIC 流程

initializing → researching → generating_outlines → generating_scenes → 
generating_media → generating_tts → persisting → completed

• 多个阶段，每个阶段有独立的 LLM 调用
• 支持条件跳过（如 enableWebSearch, enableImageGeneration）

---

三、提示词对比

LangGraph (本项目)

大纲生成提示词

const prompt = `请为书籍《${state.topic}》设计大纲。

书籍规模：${scaleDesc[state.bookScale]}

请分析这个主题的复杂程度，决定合适的章节数量...

返回JSON格式：
{
  "mainTheme": "主题一句话描述",
  "chapters": [...]
}
请确保：
1. 章节数根据主题实际复杂度决定
2. 章节之间有清晰的逻辑递进关系`

章节生成提示词

`撰写《${state.topic}》第${chapterOutline.number}章。
章节：${chapterOutline.title}，概述：${chapterOutline.summary}，
知识点：${chapterOutline.keyPoints.join(', ')}，
长度${chapterOutline.estimatedWords}字左右。直接输出正文：`

特点

• 系统提示词非常简短：你是专业的书籍作者，擅长撰写结构严谨、内容丰富、通俗易懂的作品。
• 用户提示词详细，包含完整的上下文信息
• 强调"直接输出"减少解析成本

OpenMAIC-main

Agent Profile 生成

const systemPrompt = `You are an expert instructional designer. 
Generate agent profiles for a multi-agent classroom simulation. 
Return ONLY valid JSON, no markdown or explanation.`;

const userPrompt = `Generate agent profiles for a course with this requirement:
${requirement}
Requirements:
- Decide the appropriate number of agents based on the course content (typically 3-5)
- Exactly 1 agent must have role "teacher"...
Return a JSON object with this exact structure: {...}`

PBL System Prompt

// 完整的中文系统提示词，包含角色定义、模式系统、工作流程
`你是项目式学习（PBL）平台的教学助手（TA）。
你需要根据老师提供的课程信息，自主设计完整的学生小组项目。

## 你的职责
设计一个完整的项目...

## 模式系统
你可以在不同模式间切换...
- project_info：设置项目基本信息
- agent：定义项目角色
- issueboard：配置协作工作流和任务
- idle：表示项目配置完成的特殊模式

## 工作流程
1. 在 project_info 模式中...
...`

特点

• 系统提示词非常详细，包含完整的角色定义、工具说明、工作流程
• 用户提示词相对简洁，传递核心参数
• 强调结构化输出 (JSON)

---

四、核心差异总结

方面	LangGraph (本项目)	OpenMAIC-main
系统提示词	简短，只描述角色	详细，包含完整的工作流、工具、模式说明
用户提示词	详细，包含所有上下文	简洁，主要是参数传递
输出格式	强调"直接输出正文"	要求 "Return ONLY valid JSON"
状态传递	LangGraph State + 数据库持久化	内存状态 + Phase 回调
灵活性	固定流程	支持条件分支 (enableWebSearch等)
适用场景	书籍/章节生成 (线性)	课堂/场景生成 (多阶段多任务)

关键区别

1. 提示词设计哲学不同：

   • 本项目：System 简单，User 详细 → 让 LLM 根据丰富上下文生成
   • OpenMAIC：System 详细定义工作方式，User 简单传递参数 → 结构化引导

2. 状态管理方式：

   • 本项目使用 LangGraph 官方状态流，状态通过 Partial<State> 更新
   • OpenMAIC 使用内存 Map + Phase 阶段控制

3. 执行粒度：

   • 本项目按章节顺序执行，每个章节单独调用 LLM
   • OpenMAIC 按场景 (Scene) 并行/串行执行，支持媒体生成、TTS 等多个子阶段

---

五、OpenMAIC 值得借鉴的地方

1. 工具调用模式 (Tool Calling + MCP)

OpenMAIC 的做法：

// 定义工具 + Zod 输入校验
const pblTools = {
  set_mode: tool({
    description: '切换工作模式...',
    inputSchema: z.object({
      mode: z.enum(['project_info', 'agent', 'issueboard', 'idle']),
    }),
    execute: async ({ mode }) => modeMCP.setMode(mode),
  }),
  create_agent: tool({
    inputSchema: z.object({
      name: z.string(),
      system_prompt: z.string(),
    }),
    execute: async (params) => agentMCP.createAgent(params),
  }),
};

// 使用 Vercel AI SDK 的 generateText
const result = await generateText({
  model,
  tools,
  stopWhen: ({ finishReason }) => finishReason === 'tool-calls',
});

借鉴价值：⭐⭐⭐⭐⭐

• 本项目的书籍生成是纯提示词驱动，LLM 只是按顺序生成内容
• 可以引入工具调用，让 LLM 在生成章节时能：
  • 查询相似内容避免重复
  • 调用外部 API 获取最新信息
  • 动态调整章节结构

---

2. LangGraph 状态管理 (Annotation)

OpenMAIC 的做法：

const OrchestratorState = Annotation.Root({
  // 只读输入
  messages: Annotation<StatelessChatRequest['messages']>,
  availableAgentIds: Annotation<string[]>,
  
  // 可变状态
  currentAgentId: Annotation<string | null>,
  turnCount: Annotation<number>,
  agentResponses: Annotation<AgentTurnSummary[]>({
    reducer: (prev, update) => [...prev, ...update],
    default: () => [],
  }),
});

本项目的做法：

const GraphState = Annotation.Root({
  bookId: Annotation<string>,
  topic: Annotation<string>,
  currentChapter: Annotation<number>,
  finished: Annotation<boolean>,
  // 缺少 reducer 和 default 工厂
});

借鉴价值：⭐⭐⭐

• 使用 reducer 合并更新，避免手动覆盖
• 添加 default 工厂函数，避免 undefined 问题

---

3. AI SDK Adapter 封装

OpenMAIC 的做法：

// 将任意 LanguageModel 转换为 LangChain BaseChatModel
export class AISdkLangGraphAdapter extends BaseChatModel {
  private languageModel: LanguageModel;
  
  async _generate(messages: BaseMessage[]): Promise<ChatResult> {
    const aiMessages = convertMessages(messages);
    const result = await callLLM({ model: this.languageModel, messages: aiMessages });
    return { generations: [{ text: result.text, message: new AIMessage(result.text) }] };
  }
}

借鉴价值：⭐⭐⭐⭐

• 本项目直接用 axios 调用 LLM，缺少 LangChain 生态支持
• 可以封装为统一适配器，兼容多模型（OpenAI/Anthropic/本地模型）
• 便于后续集成 LangChain 的输出解析、工具调用等能力

---

4. 流式 JSON 解析

OpenMAIC 的做法：

import { parse as parsePartialJson, Allow } from 'partial-json';
import { jsonrepair } from 'jsonrepair';

// 增量解析流式 JSON 数组
for await (const chunk of result.textStream) {
  const parsed = parsePartialJson(buffer + chunk, { allow: Allow.Array });
  // 实时提取完整项
}

借鉴价值：⭐⭐⭐

• 本项目的章节生成是一次性返回完整 JSON
• 对于大纲生成这种需要结构化输出的场景，流式解析能：
  • 边生成边校验，提前发现格式错误
  • 提供更好的用户体验（实时展示进度）

---

5. 多 Agent 协调 (Director Graph)

OpenMAIC 的做法：

START → director ──(next)→ agent_generate ──→ director (循环)
          │
          └─(end)→ END

// Director 根据 Agent 数量决定策略
- 单 Agent：纯代码逻辑，直接派发
- 多 Agent：LLM 决策下一个谁说话

借鉴价值：⭐⭐

• 本项目是单线生成（大纲 → 章节 → 前言 → 后记）
• 如果要做"多 Agent 协作写书"（比如不同 Agent 写不同风格章节），可以借鉴这套协调机制

---

6. 系统提示词设计

OpenMAIC 的特点：

• 系统提示词非常详细，包含完整的工具说明、模式定义、工作流程
• 用户提示词简洁，只传递参数
• 强调 JSON 输出的结构约束

借鉴价值：⭐⭐⭐

• 本项目的 System Prompt 太简短：你是专业的书籍作者...
• 可以增加：
  • 输出格式约束（如"使用 JSON"、"用 markdown 格式"）
  • 工具说明（如"遇到问题时返回 {error: ...}"）
  • 风格指导（如"避免使用专业术语，保持通俗易懂"）

---

六、总结：优先级建议

借鉴项	优先级	原因
AI SDK Adapter	高	统一多模型调用，为后续扩展打基础
工具调用模式	高	让 LLM 有能力调用外部服务（搜索、数据库等）
Annotation 状态管理	中	更规范的类型定义和状态合并
流式 JSON 解析	中	改善大纲生成的实时性
系统提示词增强	中	提升输出质量
多 Agent 协调	低	当前场景暂无需求

---

文档生成时间: 2026-04-12