tongflow/packages/dsh-tongflow

887Star118Fork7Issue91Watching

在 DSH 里嵌入 TongFlow 媒体工作流编辑器：每个素材由独立工作流文件生成，AI Agent 负责项目结构与素材管理。

tong-iotong-io
·tong-io/tongflow.git·app.tongflow.com
语言
TypeScript
License
AGPL-3.0
分支
main
3dagentaiai-toolsaigccanvasdeepseek-harnessdocument

安装

$ dsh plugin --profile web add github:tong-io/tongflow/packages/dsh-tongflow

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

把 TongFlow 媒体工作流编辑器嵌进 DSH：当用户用 DSH Agent 创作图、音、视频或 3D 时，每个素材由一个独立的工作流文件生成，Agent 负责项目结构和素材组织，用户可以直接在画布上微调并复跑。

核心能力

  • 创建 Studio 项目文件夹并自定义结构（没有固定模板，Agent 和用户共同设计）
  • 用 .tongflow.json 工作流文件驱动所有图像、音频、视频、3D 素材生成，输出文件落在工作流旁边且不覆盖历史结果
  • 提供节点目录与节点描述，让 Agent 知道有哪些节点类型、连线规则、配置字段和可用插件
  • 通过 tongflow_look（图像）和 tongflow_perceive（视频/音频/图像理解）让 Agent 复核生成效果再进入下一步
  • 内置付费插件二次确认机制与项目管理/插件管理工具，避免误扣费
  • 启动时自动克隆官方插件并维护 venv，让画布节点目录与 TongFlow 官方版保持一致

技术实现

  • 语言: TypeScript（节点端 + 浏览器端 CJS bundle 一份）
  • 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-* 套件（agent / tools / skills / webserver / llm / jobs / system-prompt）、tongflow（同仓库 workspace 包）、@deepseek-ai/schemastery
  • 架构模式: Cordis 插件，通过 dsh.bundle.patch 在 cordis 中插入 tongflow 节点；用 agent/pre-step 事件判断当前会话是否进入 Studio 模式（首条消息以 @tongflow 开头），仅对 Studio 会话注册 tongflow_* 工具、技能和系统提示段
  • 入口文件: src/index.ts（Node 侧 apply）+ src/client/index.ts（浏览器侧 bundle），通过 cordis.patch.yml 注入宿主

适用场景

当你用 DSH 做漫画分镜、短视频、广告素材、音乐 MV、角色设定集、3D 资源包等需要批量化、可迭代的 AI 生成内容时，本插件把"素材生产"从一次性聊天结果变成可保存、可复跑、可手工调整的工作流；普通对话型需求（写代码、查资料）不需要它。

前置依赖与兼容性

依赖最低版本说明
DSH>= 0.1.0-rc.7所有 @deepseek-ai/dsh-* 同伴依赖均要求此版本
Node>= 22.19.0与 DSH 自身要求一致（README 声明）
Python>= 3.10首次启动会自动创建 ~/.dsh/tongflow/venv 并安装 tongflow SDK；可指定 pythonPath
Git必须启动时通过 git shallow-clone 官方插件
FFmpeg建议安装用于视频接触表（contact sheet）生成

安装方式

dsh plugin --profile web add github:tong-io/tongflow/packages/dsh-tongflow

配置项

配置类型说明默认值
studioRoot字符串Studio 数据根目录，存放项目、虚拟环境、已克隆插件、缓存<DSH_HOME>/tongflow（即 ~/.dsh/tongflow）
pythonPath字符串用于创建 Studio venv 的 Python 可执行文件路径（≥ 3.10）；留空则自动在 PATH 中查找自动检测（python3.13 → python3.10 → python）
sdkSpec字符串安装到 Studio venv 的 pip 规范，例如 tongflow==0.3.0，开发时可写 -e /path/to/sdktongflow==0.3.0
pluginOrg字符串官方插件的 Git 组织地址（被克隆来源）https://github.com/tong-io
pluginGitUrls对象自定义插件 id → git URL 映射，用于社区或私有插件{}
env对象注入到插件子进程的环境变量（如 API Key），建议优先用 Studio 内的"插件与密钥"面板填写{}
maxConcurrentRuns数字同时运行的 Workflow 上限2
httpPrefix字符串Studio 与画布使用的 HTTP 路由前缀/tongflow
locale字符串嵌入式画布的界面语言en
autoInstallOfficial布尔启动时是否自动浅克隆缺失的官方插件（只克隆，按需才部署/扣费）true

常见问题

Q: 这个插件和直接用 TongFlow SaaS 有什么区别？

A: 共享同一套 TongFlow 引擎、节点目录与 ABI，但运行在你的本地 DSH 里：素材落到你硬盘上，由 DSH Agent 主导项目结构和素材规划，并支持本地工具/技能参与协作；SaaS 版没有 Agent 这一层。

Q: 为什么我装了但会话里没看到 tongflow_ 工具？*

A: 默认不激活 Studio 模式，只有会话第一条消息以 @tongflow 开头才会注入工具和 Studio UI；其他会话与未启用插件前一样保持普通 DSH。

Q: 不小心跑了付费插件会被扣费吗？

A: tongflow_workflow_run 检测到工作流使用付费插件（API 付费或 Modal GPU）时，必须显式传 user_confirmed: true 才会真正执行，否则返回 needs_confirmation 并列出涉及的插件、计费方式、是否已配置密钥和可用替代方案；本地插件则无需确认。

Q: 一张图可以重跑很多次吗？

A: 可以。每次运行都会生成新的编号输出文件（例如 mei_ref.01.png、mei_ref.02.png），不会覆盖历史结果，运行记录会写到 <name>.runs.json；调整工作流后再次运行即可。

Q: 工作流能引用别的素材吗？

A: 能。数据节点可以直接写文件路径（相对于工作流文件 ../style.md 或项目根 characters/mei/x.png），也可以用 {{path}} 占位符在运行时把文本文件内容嵌入 prompt；URL 也会原样传递给插件。

Q: 支持哪些模态？

A: 节点目录涵盖图像、音频、视频、3D 四类模态，分别有 modality/ 数据节点和 transfer/compose/decompose/batch 四类可执行节点；具体可用插件取决于你安装/自动克隆的 TongFlow 插件列表。

Q: 我没装 Python 会怎样？

A: 第一次启动会因为找不到 Python ≥ 3.10 而报错；可安装官方 Python、uv python install 或在配置里指定 pythonPath。

上手难度

进阶 — 使用者需要理解"工作流即素材"的设计范式、节点目录与连线规则，并准备好 Python、Git、（可选）FFmpeg；插件本身的安装命令很简单。

已知问题与限制

  • 启动时如系统没有 Python ≥ 3.10，会抛错并要求安装或设置 pythonPath（src/engine/bootstrap.ts:83-86）
  • 官方插件克隆依赖 Git；autoInstallOfficial=true 时会在后台异步拉取，期间画布节点目录可能不全（src/studio.ts:65-72）
  • tongflow_workflow_run 缺少 user_confirmed=true 时会拒绝执行付费插件，每次都需要用户在当前会话再次确认（src/tools/run-tools.ts:78）
  • 插件卸载不会清理 ~/.dsh/tongflow 下的项目、venv、克隆插件和 env.json，需要手工删除（源码未发现自动清理逻辑）
返回插件目录