Workflow Generator 是一款面向 macOS 的本地工作台，用无限画布组织模型节点、本地 Agent、媒体资产和自动化工作流。它适合用来搭建多模态生成链路、调试单个节点、沉淀一致性参考资料，并把本地命令行工具纳入同一个创作空间。
- 无限画布：自由放置模型节点、Agent 节点、资产、形状和逻辑箭头。
- 节点聊天：每个节点都有独立对话框，可发送文本并附加图片、视频、音频或文件。
- 模型与提供商：维护 API 账号，并把模型注册为可复用的对话或特殊接口配方。
- 本地 Agent：扫描本机可用的命令行 Agent，并通过节点对话或工作流运行调用。
- 工作流运行：按逻辑箭头计算执行层级，同一级节点可并行运行。
- 逐级运行：可选择连续运行，也可每完成一层暂停一次，便于人工检查中间结果。
- 资产传递：支持通过逻辑箭头传递文本、JSON 和资产，也支持扇形弹射命中接收区后传递资产。
- 一致性资料库：将人物、风格、场景、品牌、镜头、语音、音乐和音效等参考资料集中管理。
- 一致性节点：在画布上收纳上游资产，把它们整理进一致性资料库，供后续生成节点引用。
使用前需要先创建或打开工作区。工作区会记录当前画布、节点、工作流配置、资产列表和运行记录。工作区数据保存在项目文件夹中，便于备份和迁移。
生成资产会写入项目下的 .workflow-assets/<工作区>/generated/。它与 .workflow-工作区名称/ 元数据目录分开，因此不会被误识别成新的工作流。
模型节点用于调用设置中已经注册好的模型接口。节点只保留少量适合单次调整的参数和附件，并可以在聊天窗口中直接调试。
Agent 节点用于调用本机可用的命令行 Agent。它适合处理项目文件、代码审查、文件生成和本地工具链任务。
一致性节点只收纳资料，不作为普通输出节点。它接收上游节点传来的文件、图片、视频、音频或文本，并写入一致性资料库。后续生成节点会从资料库中挑选相关参考，而不是把所有资料都塞入提示词。
逻辑箭头既表示执行顺序，也表示数据传递关系。
一条逻辑箭头可以配置：
- 显示名称；
- 说明；
- 是否启用；
- 运行策略；
- 依赖策略；
- 条件；
- 传递内容；
- 传递资产。
传递内容示例：
{
"text": "summary",
"json": {
"title": "$.title",
"scene": "$.scene"
}
}传递资产示例：
{
"include": ["image", "video"],
"extensions": ["png", "mp4"],
"role": "reference"
}资产只按逻辑箭头传递。适合结构清晰、需要严格控制输入输出的工作流。
逻辑箭头仍然决定执行顺序，同时节点的扇形弹射区域如果命中另一个节点的接收区，就会在运行开始时固定为一条资产传递路径。适合媒体工作流和参考资料收集。
一致性资料库按类别管理参考资料：
- 主角 / 人物；
- 视觉风格；
- 场景 / 地点；
- 品牌 / 产品；
- 镜头 / 动作；
- 语音 / 说话人；
- 音乐；
- 音效 / 环境声。
每个资料可以包含说明、标签、来源节点、来源运行、锁定状态、主参考状态和版本信息。
工作流设置页提供运行输入表单。运行前填写的值会进入本次运行，并可在节点模板中引用。
常用引用格式：
{{input.name}}
{{runInput.name}}
{{var.name}}
{{secret.NAME}}
Secret 会在发送给模型或 Agent 前展开，请避免让节点把 Secret 值直接输出。
实际工作流案例会跟着用户实操一起沉淀。当前版本（v0.1）暂不内置固定案例，字段说明与运行策略见 WorkflowGenerator 文档站 的 /#troubleshooting 和 /#run 页面（文档站代码在独立仓 qxryz/workflowgenerator）。
项目使用 Swift Package Manager。
构建：
swift build测试：
swift test重新构建并启动 macOS app bundle：
./script/build_and_run.sh --verify应用会打包到：
dist/WorkflowGenerator.app
常用入口也可以用 Makefile：
make help # 列出所有任务
make build # swift build
make test # swift test
make lint # swiftlint + swiftformat（lint 模式）
make fmt # 应用 swiftformat
make clean # 清理 .build / dist文档站代码已经迁出到独立仓库
qxryz/workflowgenerator，本仓不再管理website/。
Sources/WorkflowGenerator/
App/ 应用入口、外观适配
Models/ 数据结构、模型注册类型、端点预设、模板注册表
Services/ 模型调用、工作区、图计算、空间路由、一致性资料处理
Stores/ 应用状态与工作流编排（AppStore 暂时较重，拆分方案见 docs/）
Views/ 画布、设置、侧边栏、节点面板和聊天界面
Tests/ 路由、模型注册和工作流语义测试
script/ 本地构建、清理、lint 脚本
docs/ 设计文档与注册接口参考
文档站（Vite + React）独立成仓：qxryz/workflowgenerator。
- 一致性验证目前是基础评分，适合作为人工复核提醒。
- 图像相似度、视频关键帧比对和更完整的多模态验证可在后续接入。
- 复杂接口映射建议继续放在提供商和模型注册接口中，避免写死在节点里。
供应商导入的模型只是“已发现模型”。模型在工作流节点中使用前，需要在 设置 -> 模型 中注册至少一个接口。一个模型可以注册多个接口，例如同一个供应商下的 Messages 对话接口、图片生成接口和异步视频任务接口。
Provider -> Model -> Registered Interface -> Node
提供商保存账号、默认 Base URL 和 API Key；模型保存模型 ID；已注册接口保存真正的 HTTP 调用方式；节点只选择一条已注册接口并传入本次运行的附件和少量参数。
注册按以下步骤完成：
- 确认是否沿用供应商 Base URL，或为该接口单独重写地址；
- 选择
Conversation或Special。图片理解通常仍属于 Messages 对话；图片、视频、语音和 3D 生成使用特殊接口； - 声明输入卡片，把提示词、图片、视频、音频或文件映射到供应商要求的字段；
- 选择附件序列化格式：
automatic、url、data_url、base64、text或json； - 配置输出卡片，从响应中提取文字、媒体 URL、Base64 或任务 ID；
- 选择同步、SSE、WebSocket 或异步任务。异步任务还要填写查询路径、状态字段、成功值和失败值；
- 预览最终 URL 和 JSON，保存为“未验证”，单节点聊天跑通后再登记为“已验证”。
系统模板是可恢复的起点，不会覆盖用户填写的内容。旧版模型路由在加载时只会迁移成草稿，不会静默参与节点运行。
模型节点只选择一个已经注册的具体接口。节点面板只展示模板允许在单个节点调整的常用参数，例如视频时长、尺寸、数量、音频开关和 seed。节点附件会按注册接口的输入卡片自动填入参数；地址、认证、响应解析和轮询规则仍留在设置中。
对话接口会把图片理解、视频理解等材料编译成 Messages 内容块。图片生成、视频生成、TTS、ASR、Embedding 和 3D 等任务使用各自的特殊接口，不会混入普通聊天请求。
本地桌面路径不能直接发送给云端。常用格式：
| 格式 | 用途 |
|---|---|
automatic |
本地媒体转换为 data URL，远程 https 地址保留 URL |
url |
只发送供应商能够访问的公网 URL |
data_url |
发送 data:<mime>;base64,... |
base64 |
只发送 Base64 正文 |
text |
读取文本文件内容 |
json |
把附件解析成 JSON 对象或数组 |
视频和部分图片接口会先创建任务，再查询结果。注册异步接口时至少要配置：
Task ID Path：从提交响应里取出任务 ID；Polling Path：查询任务状态的路径，例如/contents/generations/tasks/{task_id}；Status Path：状态字段所在位置；Success Values和Failure Values：停止轮询的状态集合；Interval和Max Attempts：查询间隔和最大次数。
查询 URL 由注册接口的 Base URL 与 Polling Path 拼接。Base URL 中已有的 /v1、/api/v3 等前缀不能丢。
更完整的字段说明、内容块模板和排障表见 WorkflowGenerator 文档站 的 /docs 页面。