# 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 (本项目)

#### 大纲生成提示词

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

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

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

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

#### 章节生成提示词

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

#### 特点

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

### OpenMAIC-main

#### Agent Profile 生成

```typescript
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

```typescript
// 完整的中文系统提示词，包含角色定义、模式系统、工作流程
`你是项目式学习（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 的做法：**

```typescript
// 定义工具 + 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 的做法：**

```typescript
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: () => [],
  }),
});
```

**本项目的做法：**

```typescript
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 的做法：**

```typescript
// 将任意 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 的做法：**

```typescript
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*