popiart-node-canvas/AGENTS.md

AGENTS.md 中文版文档

构建与开发命令

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：

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

---

状态管理

所有状态统一存储于：

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 分支规范

feature/xxx
fix/xxx

---

PR 规范

所有 PR：

gh pr create --base develop

---

Commit 规范

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

---

总结

这个项目本质上是：

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

整体架构已经非常接近：

• ComfyUI
• Dify
• Flowise
• LangFlow

这类现代 AI 工作流系统。