一刻工坊·架构组合方案（详细版）

最小自研、最大整合 —— 搭建「AI 内容 OS + 实战工作室」级别系统

文档信息

属性	值
版本	v1.0
创建日期	2024-12-14
状态	设计完成，待实施
目标	明确 Node/LangGraph/n8n/Flowise 职责边界，实现组合架构

一、整体架构总览（逻辑分层）

1.1 五层架构图

┌─────────────────────────────────────────────────────────────────────────────┐
│                         【体验层】Studio UI (Vue)                            │
│                                                                             │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│   │  项目中心    │  │  工作台     │  │  工具房     │  │  灵感空间   │       │
│   │ ProjectCenter│ │ProjectConsole│ │ MusicWorkflow│ │ Inspiration │       │
│   └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘       │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    【应用层】Content OS API (Node.js)                        │
│                                                                             │
│   ┌───────────────────────────────────────────────────────────────────┐    │
│   │                      统一 API 网关 (Express)                        │    │
│   │  /api/workflow/*  /api/projects/*  /api/contents/*  /api/agent/*  │    │
│   └───────────────────────────────────────────────────────────────────┘    │
│                                                                             │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│   │ 领域模型     │  │ 权限与审计  │  │ 资产管理    │  │ Run/Job状态 │       │
│   │Project/Column│  │ Auth/Audit │  │ Material    │  │ Task/Trace │       │
│   └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘       │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
┌───────────────────────────────────┐   ┌───────────────────────────────────┐
│  【智能工作流层】AI Workflow Layer │   │  【自动化层】Automation Layer     │
│           (LangGraph)              │   │             (n8n)                 │
│                                    │   │                                   │
│  ┌────────────────────────────┐   │   │  ┌────────────────────────────┐  │
│  │ langgraph-runner (Python)  │   │   │  │ n8n Workflow Engine        │  │
│  │ - 多 Agent 协作             │   │   │  │ - Cron 定时触发             │  │
│  │ - 反思/回溯/重试            │   │   │  │ - Webhook 编排             │  │
│  │ - 工具调用 (Tools)          │   │   │  │ - 跨系统集成               │  │
│  │ - 结构化输出                │   │   │  │ - 异步回调处理             │  │
│  └────────────────────────────┘   │   │  └────────────────────────────┘  │
│                                    │   │                                   │
│  支持的 Agent:                     │   │  已集成系统:                      │
│  - WritingAgent                    │   │  - Suno (音乐生成)               │
│  - VisualAgent                     │   │  - RunningHub (视频生成)         │
│  - MusicAgent                      │   │  - TikHub (视频解析)             │
│  - StrategyAgent                   │   │  - Fish Audio (语音合成)         │
│  - SchedulerAgent                  │   │  - 微信/抖音/小红书 API          │
└───────────────────────────────────┘   └───────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                 【可视化层】Visual Agent Front (Flowise)                     │
│                                                                             │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│   │  策略对话    │  │  灵感检索   │  │ Prompt迭代  │  │ 模板配置    │       │
│   │StrategyChat │  │InspirationQA│  │PromptLab   │  │TemplateEdit│       │
│   └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘       │
└─────────────────────────────────────────────────────────────────────────────┘

1.2 核心设计原则

原则	说明
最小自研	不自己造轮子：工作流引擎、cron、多智能体框架交给生态
最大整合	LangGraph + n8n + Flowise 各司其职，通过标准接口协作
领域优先	自研的核心是：Project/Column/Content 的业务模型与状态机
可观测性	所有 Run/Job 必须有 trace、可追溯、可重试
渐进迁移	现有代码不推翻，按 workflow 逐条迁移

二、组件边界表（核心）

2.1 职责划分矩阵

层级	组件	该做（自研/配置）	不该做（交给生态）
Content OS (Node)	领域模型	Project/Column/ContentItem/Task 的 CRUD、状态机、关联	AI 推理逻辑
Content OS (Node)	权限与审计	JWT 鉴权、RBAC、操作日志、StrategyLog	复杂工作流编排
Content OS (Node)	资产管理	Material/Corpus/Asset 存储、引用、清理	定时调度器
Content OS (Node)	统一 API 网关	`/api/workflow/start`、`/status`、`/result` 入口	步骤执行细节
Content OS (Node)	Run/Job 状态	Task 表记录 run_id/status/trace、Job 回调写入	AI Agent 协作
LangGraph	AI 工作流引擎	多 Agent 协作、反思回溯、工具调用、结构化输出	业务数据存储
LangGraph	Agent 实现	WritingAgent、VisualAgent、StrategyAgent 等	权限校验
n8n	定时触发	Cron 节点替代 setInterval、PlanScheduler	AI 推理
n8n	跨系统编排	Suno/RunningHub/TikHub/FishAudio 的异步调用	业务规则判断
n8n	异步回调	监听外部系统完成事件、触发 Node 回调	数据持久化
Flowise	策略对话	与用户交互的对话式策略生成	核心业务流程
Flowise	灵感检索	基于 Embedding 的语料/案例检索	数据写入
Flowise	Prompt 迭代	可视化 prompt/chain 配置、A/B 测试	权限控制

2.2 现有代码与目标态映射

现有模块	文件路径	当前职责	目标态
WorkflowEngine	`services/workflow/WorkflowEngine.js`	串行 steps 执行	迁移到 LangGraph（复杂 AI 链路）/ 保留（简单业务链路）
OrchestratorService	`services/workflow/OrchestratorService.js`	包装 Engine + manifest	保留为 Node 侧统一入口
PlanSchedulerService	`services/workflow/PlanSchedulerService.js`	setInterval 轮询 + 触发 workflow	迁移到 n8n Cron + Webhook
SchedulerAgent	`services/agents/SchedulerAgent.js`	读日历 + 触发 orchestrator	保留 Agent 逻辑，调用由 n8n 发起
n8nService	`services/n8nService.js`	Webhook 触发 + 回调处理	扩展为主要集成通道
FlowiseProxyService	`services/FlowiseProxyService.js`	会话管理 + 上下文注入	保留，增强项目上下文能力

三、数据流与调用关系图

3.1 工作流执行的完整链路

┌──────────────────────────────────────────────────────────────────────────────┐
│                              用户发起请求                                     │
│                         POST /api/workflow/start                             │
│                    { workflow: "voiceover_video", inputs: {...} }            │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                          Node.js - WorkflowService                           │
│                                                                              │
│  1. 校验权限、创建 Task 记录 (run_id)                                         │
│  2. 根据 workflow_id 判断路由目标：                                           │
│     ├─ legacy_workflow → WorkflowEngine.run() (现有链路)                     │
│     ├─ langgraph_workflow → POST langgraph-runner:8000/run                  │
│     └─ n8n_only_workflow → POST n8n:5678/webhook/xxx                        │
│  3. 返回 { task_id, status: "pending" }                                      │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
┌───────────────────────────────────┐   ┌───────────────────────────────────┐
│       LangGraph Runner            │   │              n8n                  │
│       (Python / FastAPI)          │   │                                   │
│                                   │   │  ┌─────────────────────────────┐ │
│  ┌─────────────────────────────┐ │   │  │ Cron Trigger (每15分钟)     │ │
│  │ 1. 接收 inputs + context    │ │   │  │ → GET /api/scheduler/tasks  │ │
│  │ 2. 构建 StateGraph          │ │   │  │ → POST /api/orchestrator/run│ │
│  │ 3. 执行 Agent 节点          │ │   │  └─────────────────────────────┘ │
│  │ 4. 调用 Tools (via Node)    │ │   │                                   │
│  │ 5. 返回结构化 outputs       │ │   │  ┌─────────────────────────────┐ │
│  │ 6. Callback → Node          │ │   │  │ Webhook (外部系统回调)     │ │
│  └─────────────────────────────┘ │   │  │ → POST /api/webhooks/*     │ │
└───────────────────────────────────┘   │  └─────────────────────────────┘ │
                                        └───────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                          Node.js - 回调处理                                   │
│                                                                              │
│  1. 更新 Task 记录 (status, trace, outputs)                                  │
│  2. 触发 WebSocket 通知前端                                                   │
│  3. 可选：写入 Project.meta / ContentItem                                     │
└──────────────────────────────────────────────────────────────────────────────┘

3.2 定时调度链路（n8n 接管后）

┌──────────────────────────────────────────────────────────────────────────────┐
│                           n8n - Cron Trigger                                 │
│                          每 15 分钟触发一次                                   │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                     n8n - HTTP Request Node                                  │
│                                                                              │
│  GET http://node-api:3001/api/scheduler/pending-tasks                        │
│  → 返回 { projects: [...], tasks: [...] }                                    │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                     n8n - Loop + HTTP Request                                │
│                                                                              │
│  for each task:                                                              │
│    POST http://node-api:3001/api/orchestrator/run                            │
│    { workflow_id: task.workflow, inputs: {...}, trigger: "scheduler" }       │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                     Node.js - OrchestratorService                            │
│                                                                              │
│  1. 标记 auto_runs[task.id] = { status: "running" }                          │
│  2. 路由到 LangGraph / 现有 Engine                                           │
│  3. 完成后标记 { status: "completed", trace: [...] }                         │
└──────────────────────────────────────────────────────────────────────────────┘

3.3 Flowise 对话链路

┌──────────────────────────────────────────────────────────────────────────────┐
│                           用户在灵感空间提问                                  │
│                      "帮我想一个美业账号的选题"                               │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                     Node.js - FlowiseProxyService                            │
│                                                                              │
│  1. 拼装上下文：project_id, user_id, corpus, materials                       │
│  2. POST flowise:3000/api/v1/prediction/{chatflowId}                         │
│     { question: "...", overrideConfig: { projectContext: "..." } }           │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                           Flowise - Chatflow                                 │
│                                                                              │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐                   │
│  │ Prompt  │ → │ LLM     │ → │ Output  │ → │ Response│                   │
│  │ Template│    │(GPT-4o) │    │ Parser  │    │ Format  │                   │
│  └─────────┘    └─────────┘    └─────────┘    └─────────┘                   │
│                                                                              │
│  可选节点：Vector Store Retriever (语料检索)                                  │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                           Node.js - 返回前端                                 │
│                                                                              │
│  { success: true, response: "这里是AI生成的选题建议...", sources: [...] }    │
└──────────────────────────────────────────────────────────────────────────────┘

四、技术选型说明

4.1 为什么选择 LangGraph

特性	说明
StateGraph	支持复杂的状态流转，包括循环、分支、条件跳转
多 Agent 协作	内置 AgentExecutor、ToolNode 抽象
反思/回溯	支持 Reflection、Human-in-the-Loop
可观测性	内置 LangSmith 集成，trace 开箱即用
Python 生态	与 LangChain、OpenAI SDK、HuggingFace 无缝集成

4.2 为什么选择 n8n

特性	说明
可视化编排	非开发人员也能配置工作流
内置 Cron	替代自研 setInterval/scheduler
丰富集成	400+ 节点，覆盖主流 SaaS/API
Webhook	支持同步/异步回调模式
自托管	数据安全，无供应商锁定

4.3 为什么选择 Flowise

特性	说明
可视化 LLM 链	快速迭代 prompt、chain、agent
内置对话	开箱即用的对话式 UI
Vector Store	支持 Pinecone、Chroma、Supabase 等
API 输出	一键暴露为 REST API
与 LangChain 兼容	复杂场景可迁移到代码

五、目录结构规划（目标态）

KKmusic/
├── backend/                          # Node.js 后端（保留）
│   ├── src/
│   │   ├── routes/                   # API 路由
│   │   │   ├── workflow.js           # /api/workflow/* 统一入口
│   │   │   ├── orchestrator.js       # /api/orchestrator/run
│   │   │   └── scheduler.js          # 新增：/api/scheduler/pending-tasks
│   │   ├── services/
│   │   │   ├── workflow/
│   │   │   │   ├── WorkflowService.js      # 工作流服务
│   │   │   │   ├── WorkflowEngine.js       # 轻量级引擎（保留简单链路）
│   │   │   │   ├── OrchestratorService.js  # 编排服务（统一入口）
│   │   │   │   ├── LangGraphClient.js      # 新增：调用 langgraph-runner
│   │   │   │   └── PlanSchedulerService.js # 废弃/精简：逻辑迁移到 n8n
│   │   │   ├── n8nService.js         # n8n 集成（扩展）
│   │   │   └── FlowiseProxyService.js # Flowise 代理（扩展）
│   │   ├── models/                   # 领域模型
│   │   └── workflows/
│   │       └── manifest.json         # 工作流清单（增加 engine 字段）
│   └── ...
│
├── langgraph-runner/                 # 新增：Python 服务
│   ├── app/
│   │   ├── main.py                   # FastAPI 入口
│   │   ├── graphs/                   # LangGraph 定义
│   │   │   ├── voiceover_graph.py
│   │   │   ├── diagnosis_graph.py
│   │   │   └── ...
│   │   ├── agents/                   # Agent 实现
│   │   │   ├── writing_agent.py
│   │   │   ├── visual_agent.py
│   │   │   └── ...
│   │   └── tools/                    # Tool 实现
│   │       ├── node_api_tool.py      # 调用 Node API
│   │       └── ...
│   ├── requirements.txt
│   └── Dockerfile
│
├── n8n/                              # n8n 配置（已有）
│   └── workflows/                    # 工作流 JSON 导出
│       ├── plan_scheduler.json       # 计划调度
│       ├── suno_callback.json        # Suno 回调处理
│       └── ...
│
├── flowise/                          # Flowise 配置（已有）
│   └── chatflows/                    # Chatflow 导出
│       ├── inspiration_qa.json
│       ├── strategy_chat.json
│       └── ...
│
├── frontend/                         # Vue 前端（保留）
│   └── ...
│
└── docs/
    └── architecture/
        ├── KKMUSIC_ARCHITECTURE_BLUEPRINT.md   # 本文档
        ├── UNIFIED_RUN_JOB_CONTRACT.md         # 接口规范
        └── WORKFLOW_MIGRATION_ROADMAP.md       # 迁移路线

六、风险与注意事项

6.1 迁移风险

风险	等级	应对策略
LangGraph 学习曲线	中	先迁移 1 条简单工作流，积累经验
n8n 稳定性	低	自托管 + 监控 + 降级回 Node
Flowise 性能	低	仅用于对话场景，不走核心链路
数据一致性	中	Run/Job 状态全部写入 Node Task 表

6.2 不变的部分

领域模型不变：Project/Column/ContentItem/Task 保持现有结构
API 入口不变：/api/workflow/start 对前端透明
认证不变：JWT + authenticateToken 中间件
存储不变：PostgreSQL + 文件系统

6.3 需要新增的部分

langgraph-runner 服务：Python + FastAPI + LangGraph
统一 Run/Job 接口：见 UNIFIED_RUN_JOB_CONTRACT.md
n8n 工作流配置：Cron + HTTP Request + Webhook
manifest.json 扩展：增加 engine: "langgraph" | "node" | "n8n" 字段

七、相关文档

UNIFIED_RUN_JOB_CONTRACT.md - 统一接口规范
WORKFLOW_MIGRATION_ROADMAP.md - 迁移路线
N8N_INTEGRATION.md - n8n 集成指南
FLOWISE_SETUP.md - Flowise 配置指南

八、术语表

术语	定义
Run	一次工作流执行的完整记录，包含 inputs/outputs/trace
Job	一次外部异步任务，如 n8n/Suno 调用，回调后合并到 Run
Trace	工作流执行的步骤记录，用于调试和回放
Agent	具有特定能力的 AI 组件，如 WritingAgent、VisualAgent
Tool	Agent 可调用的能力，如"生成图片"、"查询语料"
Manifest	工作流定义文件，描述 steps、agents、outputs
Blueprint	项目策略蓝图，包含 30 天内容计划

文档维护者：一刻工坊技术团队
最后更新：2024-12-14

一刻工坊·架构组合方案（详细版） ​

文档信息 ​

一、整体架构总览（逻辑分层） ​

1.1 五层架构图 ​

1.2 核心设计原则 ​

二、组件边界表（核心） ​

2.1 职责划分矩阵 ​

2.2 现有代码与目标态映射 ​

三、数据流与调用关系图 ​

3.1 工作流执行的完整链路 ​

3.2 定时调度链路（n8n 接管后） ​

3.3 Flowise 对话链路 ​

四、技术选型说明 ​

4.1 为什么选择 LangGraph ​

4.2 为什么选择 n8n ​

4.3 为什么选择 Flowise ​

五、目录结构规划（目标态） ​

六、风险与注意事项 ​

6.1 迁移风险 ​

6.2 不变的部分 ​

6.3 需要新增的部分 ​

七、相关文档 ​

八、术语表 ​

一刻工坊·架构组合方案（详细版）

文档信息

一、整体架构总览（逻辑分层）

1.1 五层架构图

1.2 核心设计原则

二、组件边界表（核心）

2.1 职责划分矩阵

2.2 现有代码与目标态映射

三、数据流与调用关系图

3.1 工作流执行的完整链路

3.2 定时调度链路（n8n 接管后）

3.3 Flowise 对话链路

四、技术选型说明

4.1 为什么选择 LangGraph

4.2 为什么选择 n8n

4.3 为什么选择 Flowise

五、目录结构规划（目标态）

六、风险与注意事项

6.1 迁移风险

6.2 不变的部分

6.3 需要新增的部分

七、相关文档

八、术语表