工作流迁移路线图

现有 workflow 清单、迁移目标、分阶段实施计划

文档信息

属性	值
版本	v1.0
创建日期	2024-12-14
状态	设计完成，待实施
目标	明确每个 workflow 的迁移目标和优先级

一、现有工作流清单

1.1 总览

基于 WorkflowRegistry.js 和 manifest.json 分析，当前系统共有 19 个 已注册工作流。

统计维度	数量
策略类	1
爆款复刻类	1
知识/内容生成类	6
音乐/MV类	3
运营/分发类	3
优化/辅助类	3
长视频类	2
合计	19

1.2 详细工作流清单

#	workflow_id	名称	分类	复杂度	涉及 Agent	n8n 集成
1	`project_diagnosis_workflow`	🎯 起号项目诊断	strategy	中	strategy	❌
2	`healing_night_mv`	🌃 治愈系深夜 MV	viral	高	writing, music, visual, video	❌
3	`knowledge_explainer`	📚 知识解说	content	中	writing, visual, video	❌
4	`content_repurposing`	🐟 一鱼多吃·全平台分发	ops	中	writing, visual	✅ `repurpose_multichannel`
5	`daily_inspiration`	✨ 每日灵感	ops	低	writing, visual	❌
6	`product_showcase`	📦 产品种草	content	高	writing, visual, music, video	❌
7	`local_store_review`	🏪 本地探店	content	高	writing, visual, video	❌
8	`lyric_storybook`	📖 歌词故事书	music	中	writing, visual, video	❌
9	`music_video_creation`	🎵 歌词→Suno→MV	music	高	writing, music, visual, video	✅ `suno_mv_stack`
10	`voiceover_video`	🎤 口播脚本→视频	content	中	writing, visual, video	✅ `voiceover_auto_render`
11	`social_content`	📱 社交内容	ops	低	writing, visual	❌
12	`song_cover`	🎙️ 歌曲翻唱	music	中	writing, music, visual	❌
13	`viral_title_optimizer`	🔥 爆款标题优化	utility	低	writing	❌
14	`long_video_repurpose`	📺 长视频拆条	longform	高	writing, video	❌
15	`seo_blog_post`	📝 SEO 博客文章	content	中	writing, visual	❌
16	`youtube_script_longform`	🎬 YouTube 长视频脚本	longform	高	writing, visual, video	❌
17	`smart_assembly_workflow`	🛠️ 智能合成	utility	中	writing, video	❌
18	`content_plan_workflow`	📅 内容规划	strategy	中	strategy, writing	❌
19	`quick_topic_suggest`	💡 快速选题	utility	低	writing	❌

二、迁移目标映射

2.1 迁移目标定义

目标	说明	适用场景
Node (保留)	继续使用现有 `WorkflowEngine.js`	简单线性链路、业务逻辑重、改造成本高
LangGraph	迁移到 `langgraph-runner`	多 Agent 协作、需要反思/回溯、复杂状态流转
n8n	交给 n8n 编排	定时触发、跨系统集成、异步回调
Flowise	改为 Flowise Chatflow	对话式交互、快速迭代 prompt

2.2 逐条迁移标注

#	workflow_id	迁移目标	优先级	原因说明
1	`project_diagnosis_workflow`	LangGraph	P2	策略类，需要多轮推理、可能引入反思
2	`healing_night_mv`	LangGraph	P2	多 Agent 协作（4 个），状态流转复杂
3	`knowledge_explainer`	LangGraph	P2	3 个 Agent，可能需要重试/回溯
4	`content_repurposing`	n8n	P1	已有 n8n 集成，适合跨平台分发
5	`daily_inspiration`	Flowise	P3	简单推荐，适合对话式交互
6	`product_showcase`	LangGraph	P2	4 个 Agent，复杂链路
7	`local_store_review`	LangGraph	P2	3 个 Agent，需要工具调用
8	`lyric_storybook`	LangGraph	P2	3 个 Agent，创意生成
9	`music_video_creation`	n8n + LangGraph	P1	已有 n8n 集成，Suno 异步回调
10	`voiceover_video`	n8n + LangGraph	P1	核心工作流，已有 n8n 集成
11	`social_content`	Node (保留)	P3	简单链路，改造收益低
12	`song_cover`	LangGraph	P2	音乐类，需要创意生成
13	`viral_title_optimizer`	Node (保留)	P3	单 Agent，逻辑简单
14	`long_video_repurpose`	LangGraph	P2	长内容处理，需要分段
15	`seo_blog_post`	Node (保留)	P3	成熟链路，改造成本高
16	`youtube_script_longform`	LangGraph	P2	3 个 Agent，长脚本生成
17	`smart_assembly_workflow`	Node (保留)	P3	工具类，直接调用
18	`content_plan_workflow`	LangGraph	P1	策略类核心，需要多轮规划
19	`quick_topic_suggest`	Flowise	P3	简单推荐，对话式更友好

2.3 迁移目标统计

                    迁移目标分布
    ┌──────────────────────────────────────────┐
    │                                          │
    │  ███████████████████████████ LangGraph   │  11 个 (58%)
    │  ████████████ n8n / n8n+LangGraph        │   4 个 (21%)
    │  █████ Node (保留)                        │   2 个 (11%)
    │  ███ Flowise                             │   2 个 (10%)
    │                                          │
    └──────────────────────────────────────────┘

三、分阶段实施计划

3.1 阶段概览

    时间线
    ────────────────────────────────────────────────────────►
    
    P0 设计文档      P1 n8n接管调度      P2 LangGraph迁移      P3 Flowise灵感
    ▼                ▼                   ▼                      ▼
    ┌────────┐       ┌────────────┐      ┌──────────────┐       ┌───────────┐
    │ 本次   │       │ 3-7 天     │      │ 1-2 周       │       │ 持续迭代  │
    │ 交付   │       │            │      │              │       │           │
    │        │       │            │      │              │       │           │
    │ 3份    │       │ scheduler  │      │ 选1条核心    │       │ 灵感空间  │
    │ 文档   │       │ 外移n8n    │      │ workflow试点 │       │ 策略对话  │
    └────────┘       └────────────┘      └──────────────┘       └───────────┘

3.2 P0 阶段（本次交付）- 设计文档

目标：完成架构设计，明确边界和接口

交付物：

[x] KKMUSIC_ARCHITECTURE_BLUEPRINT.md - 整体架构蓝图
[x] UNIFIED_RUN_JOB_CONTRACT.md - 统一接口规范
[x] WORKFLOW_MIGRATION_ROADMAP.md - 迁移路线（本文档）

验收标准：

文档完整，包含分层图、边界表、接口规范
每个 workflow 都有明确的迁移目标标注
不改动任何现有代码

3.3 P1 阶段（3-7 天）- n8n 接管定时调度

目标：把 PlanSchedulerService 的定时逻辑迁移到 n8n

涉及工作流：

workflow_id	当前状态	P1 目标
`voiceover_video`	Node setInterval 触发	n8n Cron → Node API
`music_video_creation`	Node setInterval 触发	n8n Cron → Node API
`content_repurposing`	手动触发	n8n Webhook
`content_plan_workflow`	Node setInterval 触发	n8n Cron → Node API

核心改动：

3.3.1 Node 侧新增 API

javascript

// routes/scheduler.js

// 获取待执行任务列表（供 n8n 调用）
router.get('/api/scheduler/pending-tasks', authenticateToken, async (req, res) => {
  // 1. 查询所有启用自动执行的项目
  // 2. 检查日历、计划，返回需要触发的任务
  // 返回: { projects: [...], tasks: [{ workflow_id, project_id, inputs }] }
});

// 触发单个任务执行
router.post('/api/scheduler/trigger', authenticateToken, async (req, res) => {
  const { workflow_id, project_id, inputs, trigger_source } = req.body;
  // 调用 OrchestratorService.run()
  // 返回: { run_id, status }
});

3.3.2 n8n 工作流配置

json

// n8n workflow: plan_scheduler
{
  "name": "Plan Scheduler (每15分钟)",
  "nodes": [
    {
      "name": "Cron",
      "type": "n8n-nodes-base.cron",
      "parameters": {
        "rule": "*/15 * * * *"
      }
    },
    {
      "name": "Get Pending Tasks",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "method": "GET",
        "url": "http://node-api:3001/api/scheduler/pending-tasks",
        "authentication": "headerAuth"
      }
    },
    {
      "name": "Loop Tasks",
      "type": "n8n-nodes-base.splitInBatches",
      "parameters": {
        "batchSize": 1
      }
    },
    {
      "name": "Trigger Task",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "method": "POST",
        "url": "http://node-api:3001/api/scheduler/trigger",
        "body": "={{ JSON.stringify($json) }}"
      }
    }
  ]
}

3.3.3 PlanSchedulerService 精简

javascript

// services/workflow/PlanSchedulerService.js

class PlanSchedulerService {
  // 删除或注释 startTicking()
  // 保留 getPendingTasks() 供 API 调用
  // 保留 triggerWorkflow() 供 API 调用
  
  async getPendingTasks() {
    // 原 tick() 中的任务查询逻辑
  }
  
  async triggerWorkflow(task) {
    // 原 tick() 中的触发逻辑
  }
}

验收标准：

n8n 能每 15 分钟自动触发计划任务
Node 不再使用 setInterval 轮询
前端无感知，API 入口不变

3.4 P2 阶段（1-2 周）- LangGraph 接管 AI 工作流

目标：选择 1 条核心工作流，完成 LangGraph 迁移试点

推荐试点：project_diagnosis_workflow

选择理由
✅ 策略类工作流，逻辑相对独立
✅ 只有 2 个步骤，复杂度适中
✅ 可能需要引入反思机制
✅ 对用户影响可控（非核心生产链路）

核心改动：

3.4.1 新建 langgraph-runner 服务

langgraph-runner/
├── app/
│   ├── main.py              # FastAPI 入口
│   ├── config.py            # 配置
│   ├── graphs/
│   │   └── diagnosis_graph.py   # 诊断工作流 StateGraph
│   ├── agents/
│   │   └── strategy_agent.py    # 策略 Agent
│   └── tools/
│       └── node_api.py          # 调用 Node API 的 Tool
├── requirements.txt
└── Dockerfile

3.4.2 诊断工作流 StateGraph

python

# graphs/diagnosis_graph.py

from langgraph.graph import StateGraph, END
from typing import TypedDict

class DiagnosisState(TypedDict):
    # 输入
    creator_profile: dict
    goals: list
    main_platforms: list
    # 中间状态
    diagnosis_result: dict
    # 输出
    positioning_options: list
    errors: list

def build_diagnosis_graph():
    graph = StateGraph(DiagnosisState)
    
    # 添加节点
    graph.add_node("diagnose", diagnose_project)
    graph.add_node("position", generate_positioning)
    graph.add_node("reflect", maybe_reflect)  # 可选反思
    
    # 添加边
    graph.add_edge("diagnose", "position")
    graph.add_conditional_edges(
        "position",
        should_reflect,
        {
            True: "reflect",
            False: END
        }
    )
    graph.add_edge("reflect", "position")
    
    graph.set_entry_point("diagnose")
    
    return graph.compile()

3.4.3 Node 侧路由逻辑

javascript

// services/workflow/WorkflowService.js

async function startWorkflow(workflowId, inputs, context) {
  const workflow = registry.get(workflowId);
  
  // 根据 engine 字段路由
  switch (workflow.engine) {
    case 'langgraph':
      return await langGraphClient.run(workflowId, inputs, context);
    case 'n8n':
      return await n8nService.trigger(workflow.n8n_workflow, inputs);
    case 'node':
    default:
      return await workflowEngine.run(workflowId, inputs, context);
  }
}

3.4.4 manifest.json 扩展

json

[
  {
    "id": "project_diagnosis_workflow",
    "engine": "langgraph",           // 新增字段
    "langgraph_graph": "diagnosis",  // 新增字段
    // ... 其他字段保持不变
  },
  {
    "id": "voiceover_video",
    "engine": "node",                // 保留原有引擎
    // ...
  }
]

验收标准：

langgraph-runner 服务正常运行
project_diagnosis_workflow 完整走通
Trace 数据正确写入 Task 表
错误能正确回调并处理

3.5 P3 阶段（持续迭代）- Flowise 灵感空间

目标：把灵感检索、策略对话沉淀到 Flowise

涉及工作流：

workflow_id	改造方向
`daily_inspiration`	改为 Flowise Chatflow
`quick_topic_suggest`	改为 Flowise Chatflow

核心改动：

3.5.1 Flowise Chatflow 配置

创建 inspiration_qa Chatflow
- 接入向量数据库（语料/案例）
- 配置 Retrieval + LLM Chain
- 输出结构化推荐结果
创建 strategy_chat Chatflow
- 接入项目上下文
- 支持多轮对话
- 输出策略建议

3.5.2 FlowiseProxyService 增强

javascript

// services/FlowiseProxyService.js

class FlowiseProxyService {
  async predict(chatflowId, question, projectContext) {
    // 1. 查询项目信息
    const project = await Project.findByPk(projectContext.project_id);
    
    // 2. 拼装上下文
    const overrideConfig = {
      projectName: project.name,
      platforms: project.meta?.platforms,
      positioning: project.meta?.positioning,
      recentContents: await this.getRecentContents(project.id)
    };
    
    // 3. 调用 Flowise
    const response = await axios.post(
      `${FLOWISE_URL}/api/v1/prediction/${chatflowId}`,
      { question, overrideConfig }
    );
    
    return response.data;
  }
}

验收标准：

灵感空间能正常对话
返回结果包含相关语料引用
对话历史正确维护

四、风险与应对

4.1 风险矩阵

风险	可能性	影响	应对策略
LangGraph 学习曲线陡峭	中	高	先做小规模试点，积累经验
n8n 集群不稳定	低	中	设置告警，保留 Node 降级
数据一致性问题	中	高	Run/Job 状态统一写入 Task 表
迁移期间服务中断	低	高	灰度发布，新旧并行

4.2 回滚策略

每个 workflow 的迁移都应支持回滚：

1. manifest.json 中 engine 字段改回 "node"
2. 重启服务，流量回到 WorkflowEngine
3. 无需代码修改

五、依赖与环境

5.1 新增服务

服务	技术栈	端口	说明
langgraph-runner	Python 3.11 + FastAPI	8000	LangGraph 运行时

5.2 依赖版本

# langgraph-runner/requirements.txt
langgraph>=0.0.40
langchain>=0.1.0
langchain-openai>=0.0.5
fastapi>=0.109.0
uvicorn>=0.27.0
httpx>=0.26.0
pydantic>=2.5.0

5.3 环境变量

env

# langgraph-runner
OPENAI_API_KEY=sk-xxx
NODE_API_URL=http://localhost:3001
LANGSMITH_API_KEY=xxx  # 可选，用于 trace

六、附录

6.1 现有代码参考

文件	说明
`backend/src/workflows/manifest.json`	工作流清单
`backend/src/services/workflow/WorkflowEngine.js`	现有引擎
`backend/src/services/workflow/WorkflowRegistry.js`	工作流注册表
`backend/src/services/workflow/OrchestratorService.js`	编排服务
`backend/src/services/workflow/PlanSchedulerService.js`	计划调度
`backend/src/services/n8nService.js`	n8n 集成
`backend/src/services/FlowiseProxyService.js`	Flowise 代理

6.2 相关文档

KKMUSIC_ARCHITECTURE_BLUEPRINT.md - 整体架构蓝图
UNIFIED_RUN_JOB_CONTRACT.md - 统一接口规范
N8N_INTEGRATION.md - n8n 集成指南
FLOWISE_SETUP.md - Flowise 配置指南

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

工作流迁移路线图 ​

文档信息 ​

一、现有工作流清单 ​

1.1 总览 ​

1.2 详细工作流清单 ​

二、迁移目标映射 ​

2.1 迁移目标定义 ​

2.2 逐条迁移标注 ​

2.3 迁移目标统计 ​

三、分阶段实施计划 ​

3.1 阶段概览 ​

3.2 P0 阶段（本次交付）- 设计文档 ​

3.3 P1 阶段（3-7 天）- n8n 接管定时调度 ​

3.3.1 Node 侧新增 API ​

3.3.2 n8n 工作流配置 ​

3.3.3 PlanSchedulerService 精简 ​

3.4 P2 阶段（1-2 周）- LangGraph 接管 AI 工作流 ​

3.4.1 新建 langgraph-runner 服务 ​

3.4.2 诊断工作流 StateGraph ​

3.4.3 Node 侧路由逻辑 ​

3.4.4 manifest.json 扩展 ​

3.5 P3 阶段（持续迭代）- Flowise 灵感空间 ​

3.5.1 Flowise Chatflow 配置 ​

3.5.2 FlowiseProxyService 增强 ​

四、风险与应对 ​

4.1 风险矩阵 ​

4.2 回滚策略 ​

五、依赖与环境 ​

5.1 新增服务 ​

5.2 依赖版本 ​

5.3 环境变量 ​

六、附录 ​

6.1 现有代码参考 ​

6.2 相关文档 ​

工作流迁移路线图

文档信息

一、现有工作流清单

1.1 总览

1.2 详细工作流清单

二、迁移目标映射

2.1 迁移目标定义

2.2 逐条迁移标注

2.3 迁移目标统计

三、分阶段实施计划

3.1 阶段概览

3.2 P0 阶段（本次交付）- 设计文档

3.3 P1 阶段（3-7 天）- n8n 接管定时调度

3.3.1 Node 侧新增 API

3.3.2 n8n 工作流配置

3.3.3 PlanSchedulerService 精简

3.4 P2 阶段（1-2 周）- LangGraph 接管 AI 工作流

3.4.1 新建 langgraph-runner 服务

3.4.2 诊断工作流 StateGraph

3.4.3 Node 侧路由逻辑

3.4.4 manifest.json 扩展

3.5 P3 阶段（持续迭代）- Flowise 灵感空间

3.5.1 Flowise Chatflow 配置

3.5.2 FlowiseProxyService 增强

四、风险与应对

4.1 风险矩阵

4.2 回滚策略

五、依赖与环境

5.1 新增服务

5.2 依赖版本

5.3 环境变量

六、附录

6.1 现有代码参考

6.2 相关文档