# tongflow

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

## Metadata

- Author: [@tong-io](https://github.com/tong-io)
- Repo: <https://github.com/tong-io/tongflow.git>
- GitHub: [tong-io/tongflow](https://github.com/tong-io/tongflow)
- Stars: 887
- Language: TypeScript
- License: [AGPL-3.0](https://spdx.org/licenses/AGPL-3.0.html)
- Homepage: <https://app.tongflow.com>
- Topics: `3d`, `agent`, `ai`, `ai-tools`, `aigc`, `canvas`, `deepseek-harness`, `document`, `dsh-plugin`, `genai`, `generative-ai`, `image`, `link`, `multimodal`, `studio`, `tongflow`, `video`, `voice`, `workflow`
- Forks: 118
- Open Issues: 7
- Last push: 2026-08-20T14:36:39.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
把 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）生成 |

## 安装方式
```bash
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/sdk` | `tongflow==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`，需要手工删除（源码未发现自动清理逻辑）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [tongflow](https://deepseek-plugin.org/plugins/tong-io/tongflow/packages/dsh-tongflow)
Wiki generated by AI (model: `MiniMax-M3`)