# AGENTS.md 中文版文档

## 构建与开发命令

```bash
npm run dev      # 启动 Next.js 开发服务器（http://localhost:3000）
npm run build    # 构建生产版本
npm run start    # 启动生产环境服务
npm run lint     # 执行 Next.js 代码检查
npm run test     # 使用 Vitest 运行测试（watch 模式）
npm run test:run # 单次运行所有测试（CI 模式）
```

---

# 环境配置

在项目根目录创建 `.env.local`：

```env
POPIART_API_BASE_URL=https://wwwtest.popi.art
```

---

# 项目架构概览

Node Banana 是一个：

- 基于节点的 AI 图像生成工作流编辑器
- 使用 React Flow 作为可视化画布
- 支持 AI 图像生成与 LLM 文本生成

---

# 核心技术栈

| 技术 | 用途 |
|---|---|
| Next.js 16 | App Router + TypeScript |
| @xyflow/react | 节点画布 |
| Konva.js | 画布绘图 |
| Zustand | 状态管理 |
| i18n | 多语言管理 |

---

# 关键文件

| 功能 | 路径 |
|---|---|
| 工作流状态 | src/store/workflowStore.ts |
| 类型定义 | src/types/index.ts |
| 主画布 | src/components/WorkflowCanvas.tsx |
| 基础节点 | src/components/nodes/BaseNode.tsx |
| 图像生成 API | src/app/api/generate/route.ts |
| LLM API | src/app/api/llm/route.ts |

---

# 状态管理

所有状态统一存储于：

```text
workflowStore.ts
```

核心方法：

- useWorkflowStore()
- executeWorkflow()
- getConnectedInputs()
- updateNodeData()

支持：

- 自动保存
- 拓扑排序执行
- 节点依赖调度

---

# 工作流执行流程

1. 用户点击 Run
2. executeWorkflow() 执行拓扑排序
3. 节点按依赖顺序运行
4. 自动获取上游输入
5. 输出最终结果

---

# AI 模型

## 图像生成

| 模型 | 内部名称 |
|---|---|
| gemini-2.5-flash-image | nano-banana |
| gemini-3-pro-image-preview | nano-banana-pro |

## LLM 模型

### Google

- gemini-2.5-flash
- gemini-3-flash-preview
- gemini-3-pro-preview

### OpenAI

- gpt-4.1-mini
- gpt-4.1-nano

---

# 节点类型

| 节点 | 功能 |
|---|---|
| imageInput | 图片上传 |
| annotation | 图片标注 |
| prompt | Prompt 输入 |
| nanoBanana | AI 图像生成 |
| llmGenerate | LLM 文本生成 |
| splitGrid | 网格切分 |
| generateAudio | 音频生成 |
| audioInput | 音频上传 |
| glbViewer | 3D 模型查看 |
| output | 最终输出 |

---

# 节点连接规则

## Handle 类型

| 类型 | 数据 |
|---|---|
| image | 图片 |
| text | 文本 |
| audio | 音频 |

## 连接限制

- image 只能连接 image
- text 只能连接 text
- output → input

---

# 快捷键

| 快捷键 | 功能 |
|---|---|
| Ctrl/Cmd + Enter | 运行工作流 |
| Shift + P | 添加 Prompt 节点 |
| Shift + I | 添加图片节点 |
| Shift + G | 添加生成节点 |
| Shift + L | 添加 LLM 节点 |
| Shift + A | 添加标注节点 |
| H | 横向排列 |
| V | 纵向排列 |
| G | 网格排列 |

---

# 添加新节点流程

1. 定义 TypeScript 类型
2. 添加 NodeType
3. 创建默认数据
4. 注册节点
5. 更新 WorkflowCanvas
6. 更新执行逻辑
7. 更新连接规则

---

# API Routes

| 路由 | 用途 |
|---|---|
| /api/generate | 图像生成 |
| /api/llm | 文本生成 |
| /api/workflow | 工作流存储 |
| /api/save-generation | 图片保存 |
| /api/logs | 日志系统 |

---

# Feature 分支规范

```bash
feature/xxx
fix/xxx
```

---

# PR 规范

所有 PR：

```bash
gh pr create --base develop
```

---

# Commit 规范

- 一个功能一个 commit
- commit 必须原子化
- 不要提交 .planning 目录

---

# 总结

这个项目本质上是：

- React Flow 工作流编辑器
- AI 图像生成系统
- LLM Agent 工作流
- 多模态 AI 平台

整体架构已经非常接近：

- ComfyUI
- Dify
- Flowise
- LangFlow

这类现代 AI 工作流系统。