feat(workflow-builder): 接入共享 CLI、候选版本和画布交互

[YYH211]

工作流 AI 辅助构建现在通过共享的 workflow-core / workflow-cli 生成、检查并归档候选版本。用户确认预览后触发构建，再通过“应用”加载候选并替换、布局画布；最后的 version/commit 记录应用状态，候选创建本身不表示工作流已保存或发布。

主要改动：

• 统一节点模板、输入输出、引用类型、条件分支、系统配置及语义校验，前端校验与 CLI 使用一致的工作流契约。
• 接入 Builder 入口、预览交互、历史会话和候选版本加载、应用流程，按团队模型目录补齐新节点的默认模型。
• 将 HTTP 连接断开与生成任务生命周期分开，完善流式镜像、心跳和恢复，保留显式停止操作的取消语义。
• 完善 Mermaid 流式渲染、缩放、拖拽及触控交互，并补齐相关国际化和回归用例。
• 同步 upstream/main 的工作流模块拆分、模型目录 API 和聊天草稿实现，保留 Builder 入口配置字段。

配套 Pro PR：labring/fastgpt-pro#1177。本 PR 的 pro 子模块引用已同步到对应分支的新提交。

验证：

• rebase 到 upstream/main 的 b0aae4b，解决冲突后修正迁移的导入和接口调用。
• 25 个相关测试文件、394 个用例通过，范围包含 stream resume、OpenAPI、workflow-core、workflow-cli、聊天草稿、Markdown 和工作流画布。
• App、workflow-core、workflow-cli 类型检查及 pnpm build:workflow-packages 通过。
• ESLint、Prettier、提交钩子和 git diff --check 通过；未运行仓库全量测试。

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	57.47%	5987 / 10416
🔵	Statements	56.98%	6312 / 11076
🔵	Functions	52.96%	1118 / 2111
🔵	Branches	51.71%	3207 / 6201

File Coverage

No changed files found.

Generated in workflow #4581 for commit 4df6d56 by the Vitest Coverage Report Action

[github-actions]

✅ Docs preview deployed

🔗 👀 Click here to visit preview

ghcr.io/labring/fastgpt-docs-pr:4df6d56e26e79a147b31a98c5ca9390b79cadd67

🕒 Time: 2026-10-21 00:11:03 (UTC+8)

[github-actions]

✅ Build and publish successful - Preview fastgpt Image:

ghcr.io/labring/fastgpt-pr:fastgpt_4df6d56e26e79a147b31a98c5ca9390b79cadd67

🕒 Time: 2026-10-21 00:16:04 (UTC+8)

[github-actions]

✅ Admin Preview Image Ready!

ghcr.io/labring/fastgpt-pr:admin_4df6d56e26e79a147b31a98c5ca9390b79cadd67

🕒 Time: 2026-10-21 00:13:06 (UTC+8)

[c121914yu]

Core 的语义文档、确定性命令和多端复用方向合理。建议处理以下问题：

1. [P2] HTTP 私有化访问时发送消息前会失败。 checksum.ts:34 直接调用 crypto.subtle.digest，而 ChatPanel 在发请求前计算 checksum。非 localhost 的 HTTP 页面不具备该能力，需要兼容实现，并验证浏览器与服务端 checksum 一致。

2. 新增 Core/CLI 的测试入口不完整。 根 scripts/test/run.mjs:6、test:workspace 和现有主仓 CI 的选择范围没有新增包；独立包测试及 smoke 不会因已有入口自动执行。建议接入显式测试范围，覆盖新包单测、类型检查和产物 smoke。

3. 文档契约应共享定义，Core 公开操作需明确可变语义。 WorkflowDocument/语义边在 Core 与 OpenAPI 重复维护；Core 又同时公开副本执行入口和就地修改 helper。建议统一领域 schema 归属，收紧内部可变操作，保留前端确实需要的查询/验证能力，并遵守当前禁止 re-export 的规范。

4. ObjectId 修复有文档价值，但需要限定兼容性责任。 mongo.ts:18 直接删除全局 Zod 私有属性。按锁定 Zod 4.4.3 对照，所测运行校验不变，但四个新接口的 OpenAPI appId 才正确标为必填。建议通用修复独立审阅，或限定在文档生成层；测试以实际 required/optional 输出为依据，避免只断言私有属性消失。

补充整理：当前生成依赖 CLI 查询及 ChangeSet plan/apply，但不调用 init/import、直接 node/input/edge 修改等独立终端入口。通用 CLI 可作为独立基础能力审阅。version/commit 的 OpenAPI 描述也应改为“记录首次本地画布应用确认”，实际归档已在生成成功时完成。

[YYH211]

Core 的语义文档、确定性命令和多端复用方向合理。建议处理以下问题：

1. [P2] HTTP 私有化访问时发送消息前会失败。 checksum.ts:34 直接调用 crypto.subtle.digest，而 ChatPanel 在发请求前计算 checksum。非 localhost 的 HTTP 页面不具备该能力，需要兼容实现，并验证浏览器与服务端 checksum 一致。
2. 新增 Core/CLI 的测试入口不完整。 根 scripts/test/run.mjs:6、test:workspace 和现有主仓 CI 的选择范围没有新增包；独立包测试及 smoke 不会因已有入口自动执行。建议接入显式测试范围，覆盖新包单测、类型检查和产物 smoke。
3. 文档契约应共享定义，Core 公开操作需明确可变语义。 WorkflowDocument/语义边在 Core 与 OpenAPI 重复维护；Core 又同时公开副本执行入口和就地修改 helper。建议统一领域 schema 归属，收紧内部可变操作，保留前端确实需要的查询/验证能力，并遵守当前禁止 re-export 的规范。
4. ObjectId 修复有文档价值，但需要限定兼容性责任。 mongo.ts:18 直接删除全局 Zod 私有属性。按锁定 Zod 4.4.3 对照，所测运行校验不变，但四个新接口的 OpenAPI appId 才正确标为必填。建议通用修复独立审阅，或限定在文档生成层；测试以实际 required/optional 输出为依据，避免只断言私有属性消失。

补充整理：当前生成依赖 CLI 查询及 ChangeSet plan/apply，但不调用 init/import、直接 node/input/edge 修改等独立终端入口。通用 CLI 可作为独立基础能力审阅。version/commit 的 OpenAPI 描述也应改为“记录首次本地画布应用确认”，实际归档已在生成成功时完成。

修了

[c121914yu]

前端与画布交互（WorkflowBuilder）代码审查建议

经过对前端画布与辅助生成模块（projects/app/src/.../WorkflowBuilder 与 adapters/）的详细审查，核心数据流复用良好，建议针对以下 4 点进行优化与收敛：

1. 评测逻辑硬编码侵入生产界面

   • 位置：WorkflowBuilder/uiState.ts:30 及 ChatPanel.tsx
   • 问题：代码中通过检查应用名称是否以 [WBE] 开头来触发自动布局与旁观轮询机制。评测/测试相关的特殊分支不应侵入面向真实用户的生产 UI 逻辑。
   • 建议：将评测逻辑从生产组件中剥离，改为通过专门的调试/测试参数或注入方式处理。

2. 状态计算与红点/光晕逻辑耦合过重

   • 位置：WorkflowBuilder/uiState.ts 与相关组件
   • 问题：为了实现入口按钮的光晕（Halo）和未读红点（Attention Dot），抽象了多个细颗粒度 key 计算函数，与主聊天状态深度耦合，增加了维护成本。
   • 建议：将入口状态派生逻辑与红点/光晕计算统一抽象为一个完全独立的 Hook 或独立组件，收敛状态计算，避免侵入核心流程。

3. 引导弹窗与商业化渐变样式解耦

   • 位置：GuidePopover.tsx、CommercialInput.tsx 及 workflowBuilderEntry.module.scss
   • 问题：新功能两步引导与输入框炫彩渐变边框代码占了较多篇幅，且与核心业务逻辑混合。
   • 建议：将引导教学组件和商业化流光样式彻底抽离为独立的展示层文件/组件，保持主流程简洁。

4. 清理未充分利用的过渡适配代码

   • 位置：adapters/validation.ts 等
   • 问题：部分细粒度连线错误包装在实际辅助生成流中并未被深度消费，实际校验主要由服务端的 Core 承担。
   • 建议：清理该层中未被调用的无效或重叠过渡代码。

[c121914yu]

核心纯逻辑模块（Workflow Core & Workflow CLI）代码优化建议

经过对 packages/workflow-core 与 packages/workflow-cli 纯计算逻辑模块的深入审查，算法模型和单测覆盖非常扎实，但在接口封装、命令注册解耦及类型单一标准上，建议按以下 3 点进行规范与优化：

1. 规范 Core 模块导出，禁止通配符 re-export 并收敛底层就地修改函数

   • 现状：packages/workflow-core/src/index.ts 存在大量 export * from '...'，违反了项目“禁止使用通配符 re-export”的代码规范。
   • 问题：通配符导出不仅模糊了包接口边界，还将原本直接修改（in-place）输入对象的底层底层修改函数（如 node/service.ts 中的 updateNode 等 mutator）直接暴露给了外部，可能导致调用方绕过高阶副本事务直接改坏原文档。
   • 建议：严格清理 src/index.ts，只导出高阶不可变命令入口（如 applyWorkflowCommand、planWorkflowChangeSet、getWorkflowChecksum 等），将底层直接修改原对象的内部 helper 设为私有实现。

2. CLI 命令注册去中心化：每个命令独立管理配置、子方法并统一导出

   • 现状：packages/workflow-cli/src/registry.ts 堆叠了近 1,000 行代码，将所有子命令的 options 参数、入参 Schema 和描述集中定义在一个巨大数组中，而各命令的实际执行逻辑又分散在 commands/ 目录下。
   • 建议：采用去中心化设计，让每个命令文件（如 commands/node.ts、commands/edge.ts）独立维护自身的配置参数、选项定义及子方法，并在命令文件自身导出完整定义；registry.ts 仅负责统一收集和注册，大幅提升命令的可读性与扩展性。

3. 确立工作流领域文档模型的“单一标准”（收敛 Core 与 Global 契约）

   • 现状：workflow-core/src/domain/document.ts 与 packages/global/openapi/.../builder/api.ts 分别完整手写了一份同构的 WorkflowDocumentSchema 与语义执行边定义。
   • 问题：双重标准导致同一份领域事实被割裂在两个包中维护，一旦后续扩展边类型或节点结构，极易出现两边定义脱节的问题。
   • 建议：确立单一标准，将 WorkflowDocument 的纯静态领域契约统一沉淀在共享库（如 @fastgpt/global）中，Core 引擎与 OpenAPI 路由直接复用同一份 Schema 定义，OpenAPI 层仅补充特定接口的文档元数据（.meta()），避免同构 Schema 的重复维护。

[c121914yu]

节点与工具模板统一注入方案建议（统一 Provider 插槽，消除双轨硬编码）

经过对当前节点与工具模板（template）链路的深入排查，目前在模板维护上存在“双轨制”：

• 系统内置节点：在 packages/workflow-core/src/template/builtin.ts 中硬编码 import 了 20+ 个文件并手动拼装映射字典；
• 系统外挂工具：在 Pro 端将授权工具打包成 templateBundle，以 JSON 文件（template-bundle.json）形式写入沙箱容器，再由 CLI 通过环境变量读盘合并。

这种割裂导致 Core 引擎与业务模板强耦合、新增节点需多处同步，且增加了不必要的容器文件写入开销。建议采用**“统一由外部装配并一次性注入”**的架构方案：

---

核心设计思路：Everything is a TemplateProvider

将“系统内置节点”与“系统工具”彻底视作等价的积木来源，Core 引擎本身不再内置硬编码任何具体节点，仅保留统一的模板提供者协议（WorkflowTemplateProvider）。

具体重构方案：

1. 系统节点列表收拢至底层共享源（@fastgpt/global）

   • 在 packages/global/core/workflow/template/system/index.ts 中提供系统节点规格清单导出的纯函数（或基于已有的系统节点字典直接导出）。
   • 彻底删除 packages/workflow-core/src/template/builtin.ts 中的硬编码字典，解除 Core 引擎对具体节点实现的感知。

2. 统一合并为单个注入契约（一次性注入）

   • 宿主端（Pro 服务端或外部调用方）在初始化执行会话时，将当前可用的系统内置节点与经过权限校验的系统外挂工具在内存中统一装配为一个完整的 Provider / Bundle：

     // 统一由外部装配：系统节点 + 授权工具集
     const templateProvider = composeWorkflowTemplateProviders([
       createSystemNodeTemplateProvider(getSystemNodeTemplates()),
       createAuthorizedToolTemplateProvider(authorizedSystemTools)
     ]);

   • 无需拆成“内置写死一组 + 外挂落盘一份”两套路径，所有合法积木一次性注入给执行引擎。

3. 若是沙箱执行链路，合并为单个 Bundle 文件传递

   • 在必须向容器环境传递模板的场景下，直接将“系统节点 + 授权工具”合并输出为统一的一份完整模板包清单传递给沙箱进程，沙箱内启动时直接单点加载，消除双重文件与重复查找。

---

架构收益：

• 单点事实源（Single Source of Truth）：新增或修改任何系统节点，仅需在 global 中定义，Core 引擎零改动即可自动识别。
• Core 核心引擎高度纯粹：Core 恢复为纯粹的状态机与校验器，不带任何官方具体节点的业务包袱。
• 消除多语言翻译割裂：宿主在装配 Provider 时统一完成模板属性与标签的语言注入，彻底砍掉外围为补齐翻译而复制的多语言字典。

[c121914yu]

Workflow Builder 变更分析（主仓部分）

基于 origin/main...pr-7901 的静态审查，没有跑仓库测试；ObjectId 一项另用 zod@4.4.3 做了小验证。Pro 侧的问题在 labring/fastgpt-pro#1177 下。

结论：方向认可，不拆 PR；修复下面「必须修复」后可以合入。不走 dispatchWorkFlow、直接复用 agentLoopCore 可以接受，只需要把外层的流控制收紧。

必须修复

P1

1. 韩语（ko-KR）环境下构建会失败
   • workflow-cli/src/i18n.ts:13 的翻译表没有 ko-KR，会回退成英文；Pro 端 plan.ts:30 有 ko-KR。
   • 翻译结果会写进节点的 name/label（template/instantiate.ts:73-107），从而进入 checksum。服务端按韩文算，沙箱里 changeset apply --confirm 按英文算，新增节点时 checksum 必然对不上。
   • 建议：把翻译器下沉到 workflow-core，CLI 和 Pro 共用一份，并补一个 ko-KR 的端到端用例。
2. 现有编辑器接入 workflow-core 后的回归
   • 删除节点时 core 报错，代码直接 return []，删除静默无效（useWorkflow.tsx:602）；连线时 core 报错，连线被拒绝（useWorkflow.tsx:982）。
   • core 只认 -target-left 连接点（edge/compiler.ts:131），但 ConnectionHandle.tsx:78 仍在兼容历史的 -target-right 边。存量工作流里只要有一条这种边，整张图就删不了节点、也连不了线。
   • 建议：兼容历史连接点；core 报错时回退旧逻辑；补存量工作流的删除、连线、发布回归测试。
3. 社区版新建工作流不会自动打开侧边栏
   • uiState.ts:116、context.tsx:136、context.tsx:219 三处都用 workflowBuilderEnabled 判断，社区版为 false。main 上这时会打开系统配置。
   • 建议：三处改成按「入口是否可见」判断，只有可用时才聚焦输入框。

P2

4. ObjectIdSchema 删除 Zod 私有属性（global/common/type/mongo.ts:11-12）：实测运行时校验不变，但所有用到它的 OpenAPI 输入 schema 的必填字段列表都会变，是全局副作用。建议限定在 OpenAPI 生成层处理，测试直接断言实际输出的必填字段。
5. CI 没有跑新包：test-fastgpt.yaml 没有 workflow-core / workflow-cli 的测试范围，触发路径也不包含这两个包（覆盖率报告显示 "No changed files found"）。

流控制优化

• 续流心跳一定要停掉：streamResponseContext.ts:161 对所有开启续流的流都起 30 秒心跳，只在 flushResume 里停止。v2 completions 的 catch 分支（v2/chat/completions.ts:575）在 flushResume 之前有 await，任何一个抛错，定时器就不会停，Redis 一直显示 active，前端会一直等续流。建议在 finally 里停止心跳，并保证 flushResume 和 res.end 一定执行。
• 系统工具目录每轮都全量重建：capability.ts:195 的 getAuthorizedSystemToolTemplateCatalog 对每个工具调用一次 getClientToolPreviewNode，Builder 每条消息都会触发，建议按团队 + 语言缓存。
• 外层流程抽公共（不阻塞）：会话轮次、计费、停止、SSE 收尾这几块，Skill 调试、Chat Agent 助手、Builder 各写了一份，后续可以抽成公共流程。

建议优化（不阻塞）

• web/core/workflow/utils.ts:341 在通用加载函数里给 loopRun 补输入，会影响所有存量工作流的加载，建议改到 core / CLI 做规范化。
• auxiliaryGeneration/agentLoop.ts:63 对所有辅助生成强制转 base64，需确认范围。
• 过期判断（WorkflowBuilder/index.tsx:214、RenderWorkflowBuilderVersion.tsx:97）用正则匹配服务端返回的英文文本，建议改成用错误码判断。
• 上一轮 review 提过、仍未处理：workflow-core/src/index.ts 仍有 29 个 export *；文档 schema 在 openapi/.../builder/api.ts:22-75 和 core 各维护一份；template/builtin.ts 仍写死内置模板，和 Pro 注入工具模板是两条路径；registry.ts 有 992 行。
• chatInstanceRegistry.ts:105 给 sendPrompt 加了同源校验：仓库内没有任何地方发送该消息，文档也没写，只会挡住自行调用的第三方，发版说明提一句即可。

需要作者确认

1. 以下内容是否冗余、使用方在哪里：runSkillDebugChat（debugChat/handler.ts:96）、resolveAuthorizedChatFiles（fileContext.ts:86）、catalog 新增的 oxfmt / oxlint / @hono/zod-validator、lockfile 里与本功能无关的依赖升级（undici、semver、postcss 等）。
2. 首次进入时，要等两步引导走完才打开 Builder，是否是有意的。
3. 以下非 Builder 的改动是否符合预期：Code Copilot 的输出改为按 return 对象推断（NodeCode/parser.ts）；跨 tab 同步改为 rehydrate()（useChatStore.ts:340）；续流控制器改为按 URL 区分，切换会话时不再自动中止旧续流（fetch.ts:779）。

已确认，无需修改

• 不拆 PR；社区版隐藏 ChatTest 里的助手 tab 符合预期。
• 过期后点「应用」会提示「该工作流已过期，无法应用，请重新生成」。
• 之前 review 已处理：checksum 在非 HTTPS 页面的兼容、[WBE] 名称前缀、cliGateway revision 漂移、私有附件走 S3 签名、断线后台续跑。

---

Generated by Claude Code