wflow

Гарантированное выполнение AI-задач в заданном порядке.

wflow — это надстройка над iFlow CLI для автоматизации AI-задач через декларативные workflow файлы в формате YAML. Использует iFlow SDK для взаимодействия с AI-агентом. Обеспечивает последовательное выполнение шагов с передачей контекста между ними.

Построен на базе iFlow CLI SDK

Особенности

Гарантированный порядок выполнения — шаги выполняются строго последовательно
Передача контекста — результаты предыдущих шагов доступны в следующих
Интерактивный режим — удобный выбор workflow и ввод параметров
Гибкие настройки — режимы подтверждения, таймауты, обработка ошибок
Полный доступ к инструментам iFlow CLI — все инструменты AI-агента доступны в workflow
Автоопределение ACP сервера — автоматически находит или запускает iFlow сервер
Поддержка пайплайнов — коды возврата для интеграции с CI/CD

Установка

Требования

Python 3.10+
iFlow CLI (установлен и настроен)

Шаги установки

# 1. Клонируйте репозиторий
git clone <repository-url>
cd workflow-runner

# 2. Создайте виртуальное окружение
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# или
.venv\Scripts\activate     # Windows

# 3. Установите зависимости
pip install -r requirements.txt

Зависимости

iflow-cli-sdk>=0.1.0
pyyaml>=6.0
python-dotenv>=1.0.0
rich

Быстрый старт

Запуск встроенного demo workflow

# Интерактивный режим - выберете workflow и введите параметры
python wflow.py

# Или с параметрами через CLI
python wflow.py demo -i user_name=Test -i topic="My topic"

Запуск с полным путём

python wflow.py workflows/code-review.yaml -i branch=feature/my-feature -i project_path=/var/www/project

Пропуск подтверждения

python wflow.py demo -i user_name=Test -y

Режим пайплайна (CI/CD)

# Проверить, запущен ли ACP сервер
python wflow.py --check-acp

# Запуск с кодами возврата для CI/CD
python wflow.py demo -i user_name=Test --exit-code
# Коды возврата: 0=успех, 1=ошибка, 2=ACP не запущен

Интерактивный режим

Запустите runner без аргументов для интерактивного выбора:

$ python wflow.py

============================================================
wflow - Workflow Runner
============================================================

Configuration:
  PROJECT_ROOT:   /var/www/my-project
  WORKFLOWS_DIR:  /var/www/my-project/.wflow/workflows
  PROMPTS_DIR:    /var/www/my-project/.wflow/prompts
  RUNNER_DIR:     /home/user/workflow-runner

============================================================
Available Workflows
============================================================

  [1] code-review — Code Review
      Анализирует изменения в коде и создаёт рекомендации...

  [2] demo
      Demo Workflow
      Демонстрация работы workflow с передачей контекста...

Select workflow (number or name): 2

============================================================
Workflow Inputs
============================================================

  user_name: Ваше имя
      Example: Konstantin
    > user_name: Konstantin

  topic: Тема для изучения
      Example: Python async programming
    > topic: Python async programming

============================================================
Ready to Execute
============================================================

  Workflow: Demo Workflow
  Steps: 4

  Inputs:
    user_name: Konstantin
    topic: Python async programming

Proceed? [Y/n]: y

Использование в любом проекте

Структура проекта

my-project/
├── .wflow/
│   ├── .env                    # Конфигурация (опционально)
│   ├── workflows/              # Ваши workflow
│   │   ├── my-task.yaml
│   │   └── code-review.yaml
│   └── prompts/                # Ваши промпты
│       └── conventions.md
└── src/

Запуск из проекта

# Из корня проекта
python /path/to/wflow.py

# Или с указанием директории проекта
python /path/to/wflow.py -C /var/www/my-project

Alias для удобства

# ~/.bashrc или ~/.zshrc
alias wflow='/path/to/workflow-runner/.venv/bin/python /path/to/workflow-runner/wflow.py'

# Использование
cd /var/www/project
wflow
wflow demo -i user_name=Konstantin

Формат workflow

Базовая структура

# Метаданные
name: "Workflow Name"
description: "Краткое описание"

# Глобальные настройки
timeout: 600                    # Таймаут в секундах
approval_mode: DEFAULT          # Режим подтверждения

# Переменные окружения
env:
  PROJECT_ROOT: /var/www/project

# Входные параметры
inputs:
  param_name:
    description: "Описание параметра"
    required: true
    default: "value"
    example: "пример"

# Шаги
steps:
  - name: step_name
    prompt: "Промпт с ${{ inputs.param_name }}"
    depends_on: [ previous_step ]

Поля workflow

Поле	Тип	Обязательное	Описание
`name`	string	нет	Название workflow
`description`	string	нет	Описание для списка workflow
`timeout`	number	нет	Таймаут в секундах (default: 600)
`approval_mode`	string	нет	Режим подтверждения (default: DEFAULT)
`env`	object	нет	Глобальные переменные
`inputs`	object	нет	Входные параметры
`steps`	array	да	Массив шагов

Входные параметры (inputs)

inputs:
  component_name:
    description: "Имя компонента в snake_case"
    required: true
    example: "hero_banner"

  module:
    description: "Машинное имя модуля"
    required: false
    default: "custom"
    example: "my_module"

Поле	Тип	Описание
`description`	string	Описание параметра
`required`	boolean	Обязательный (default: true)
`default`	string	Значение по умолчанию
`example`	string	Пример для подсказки

Шаги (steps)

steps:
  - name: analyze
    description: "Анализирует задачу"
    prompt: |
      Проанализируй: ${{ inputs.task }}
    output_format: json

  - name: implement
    description: "Реализует код"
    prompt: |
      Реализуй на основе анализа:
      ${{ steps.analyze }}
    depends_on:
      - analyze
    approval: auto
    interactive: false
    on_failure:
      retry: 2
      notify: true

Поле	Тип	Описание
`name`	string	Обязательно. Идентификатор шага
`description`	string	Описание шага
`prompt`	string	Текст промпта (одно из: prompt или prompt_file)
`prompt_file`	string	Путь к файлу с промптом
`depends_on`	array	Список зависимостей
`context`	array	Переменные для контекста
`output_format`	string	`text` или `json`
`interactive`	boolean	Запросить подтверждение перед шагом
`approval`	string	Режим подтверждения для шага
`on_failure`	object	Обработка ошибок

Переменные в промптах

# Полный формат (рекомендуется)
${{ inputs.param_name }}      # Входной параметр
${{ env.VAR_NAME }}           # Переменная окружения
${{ steps.step_name }}        # Результат выполнения шага
${{ steps.step_name.outputs.field }}  # Поле из JSON-результата

# Короткий формат
${param_name}
${PROJECT_ROOT}

Режимы подтверждения (approval_mode)

Режим	Описание
`DEFAULT`	Запрос на каждое действие (безопасный режим)
`AUTO_EDIT`	Автоматическое редактирование файлов
`YOLO`	Полный авто-режим (для доверенных workflow)
`PLAN`	Только чтение, без изменений

# Глобальный режим
approval_mode: YOLO

steps:
  - name: safe_step
    # Наследует глобальный режим

  - name: dangerous_step
    approval: ask      # Запрашивать подтверждение

  - name: code_gen
    approval: auto     # Авто-редактирование

Обработка ошибок

steps:
  - name: validate
    prompt: "Проверь код"
    on_failure:
      retry: 2       # Количество повторных попыток
      notify: true   # Вывести уведомление при ошибке

Команды CLI

# Интерактивный режим (выбор workflow и ввод параметров)
python wflow.py

# Запуск workflow по имени
python wflow.py demo -i user_name=Test

# Запуск с полным путём
python wflow.py workflows/code-review.yaml -i branch=feature/my-feature

# Показать конфигурацию
python wflow.py --info

# Валидация без запуска
python wflow.py demo --dry-run

# Подробный вывод (показывает промпты)
python wflow.py demo --verbose

# Debug режим (thinking, tools, subagents, planning)
python wflow.py demo --debug

# Пропуск подтверждения
python wflow.py demo -i user_name=Test -y

# Запуск из другой директории
python wflow.py -C /path/to/project

# Проверка статуса ACP сервера
python wflow.py --check-acp

# Режим пайплайна (коды возврата для CI/CD)
python wflow.py demo -i user_name=Test --exit-code

Аргументы CLI

Аргумент	Описание
`workflow`	Путь или имя workflow файла
`-i, --input KEY=VALUE`	Входной параметр (можно указать несколько)
`-v, --verbose`	Подробный вывод (показывает промпты)
`-d, --debug`	Debug режим (thinking, tools, subagents)
`--dry-run`	Валидация без выполнения
`--info`	Показать конфигурацию
`-C, --directory`	Рабочая директория проекта
`-y, --yes`	Пропустить подтверждение
`--check-acp`	Проверить, запущен ли ACP сервер
`--exit-code`	Выводить только код возврата (для CI/CD)

Коды возврата (для CI/CD)

Код	Описание
0	Успех
1	Ошибка workflow
2	ACP сервер не запущен

Переменные окружения

Переменная	Описание	По умолчанию
`WFLOW_PROJECT_ROOT`	Корневая директория проекта	`cwd`
`WFLOW_WORKFLOWS_DIR`	Директория с workflow	`.wflow/workflows`
`WFLOW_PROMPTS_DIR`	Директория с промптами	`.wflow/prompts`
`WFLOW_ACP_HOST`	Хост ACP сервера	`localhost`
`WFLOW_ACP_PORT`	Порт ACP сервера	`8090`
`WFLOW_ACP_AUTO_START`	Автозапуск iFlow если не запущен	`true`

Файл .env

Создайте .env файл в проекте для конфигурации:

# .wflow/.env
WFLOW_PROJECT_ROOT=/var/www/my-project
WFLOW_WORKFLOWS_DIR=.wflow/workflows
WFLOW_PROMPTS_DIR=.wflow/prompts
WFLOW_ACP_HOST=localhost
WFLOW_ACP_PORT=8090
WFLOW_ACP_AUTO_START=true

Файл .env в проекте имеет приоритет над файлом в директории runner.

Примеры workflow

Минимальный workflow

name: "Simple Task"
description: "Простой одношаговый workflow"

inputs:
  task:
    description: "Что сделать"

steps:
  - name: execute
    prompt: "Выполни: ${{ inputs.task }}"

Demo workflow (цепочка шагов)

name: "Demo Workflow"
description: "Демонстрация передачи контекста между шагами"

inputs:
  user_name:
    description: "Ваше имя"
    required: true
    example: "Konstantin"

  topic:
    description: "Тема для изучения"
    required: true
    example: "Python async programming"

timeout: 120
approval_mode: YOLO

steps:
  - name: greeting
    prompt: |
      Привет! Тебя зовут ${{ inputs.user_name }}.
      Сегодня мы изучаем: ${{ inputs.topic }}
      Ответь одной фразой.

  - name: analyze
    prompt: |
      Тема: ${{ inputs.topic }}
      Предыдущий ответ: ${{ steps.greeting }}
      Напиши 3 ключевых аспекта этой темы.
    depends_on: [ greeting ]

  - name: summary
    prompt: |
      Собери итог:
      Тема: ${{ inputs.topic }}
      Аспекты: ${{ steps.analyze }}
    depends_on: [ analyze ]

Code Review workflow

name: "Code Review"
description: "Анализирует изменения в коде"

inputs:
  project_path:
    description: "Путь к проекту"
    required: true

  branch:
    description: "Ветка для анализа"
    required: true

timeout: 300
approval_mode: PLAN  # Только чтение

steps:
  - name: analyze_changes
    prompt: |
      Проанализируй изменения в проекте ${{ inputs.project_path }}.
      Ветка: ${{ inputs.branch }}
      Получи git diff и определи тип изменений.

  - name: security_check
    prompt: |
      Проверь на security issues:
      ${{ steps.analyze_changes }}
    depends_on: [ analyze_changes ]

  - name: quality_check
    prompt: |
      Проверь качество кода:
      ${{ steps.analyze_changes }}
    depends_on: [ analyze_changes ]

  - name: report
    prompt: |
      Сформируй итоговый отчёт:
      Security: ${{ steps.security_check }}
      Quality: ${{ steps.quality_check }}
    depends_on: [ security_check, quality_check ]

Инструменты iFlow CLI

AI-агент iFlow CLI имеет доступ к следующим инструментам:

Файловые операции

Инструмент	Описание
`read_file`	Чтение файла (текст, PDF, DOCX, Excel, изображения)
`write_file`	Создание/перезапись файла
`replace`	Точная замена текста в файле
`glob`	Поиск файлов по паттерну (`*/.ts`)
`search_file_content`	Поиск по содержимому (regex)
`list_directory`	Листинг директории
`xml_escape`	Экранирование XML/HTML

Выполнение команд

Инструмент	Описание
`run_shell_command`	Выполнение shell команды
`ReadCommandOutput`	Чтение вывода фоновой команды

Web

Инструмент	Описание
`web_search`	Веб-поиск
`web_fetch`	Загрузка и обработка URL

AI и агенты

Инструмент	Описание
`task`	Запуск субагента
`image_read`	Анализ изображений (VL model)
`Skill`	Вызов специализированного skill

Управление

Инструмент	Описание
`todo_write`	Создание списка задач
`todo_read`	Чтение списка задач
`ask_user_question`	Вопрос пользователю
`save_memory`	Сохранение в долгосрочную память

Специализированные агенты

task:
  subagent_type: "general-purpose"   # Общие задачи
  subagent_type: "plan-agent"        # Планирование
  subagent_type: "explore-agent"     # Исследование кодовой базы
  subagent_type: "frontend-tester"   # Тестирование UI
  subagent_type: "ai-engineer"       # LLM-приложения

Отладка

Показать конфигурацию

python wflow.py --info

Валидация workflow

python wflow.py workflow.yaml --dry-run

Подробный вывод

# Показывает промпты
python wflow.py workflow.yaml --verbose

Debug режим

# Показывает thinking, tool calls, subagents, planning
python wflow.py workflow.yaml --debug

Проверка ACP сервера

# Проверить, запущен ли сервер
python wflow.py --check-acp

# Проверить и получить порт для скриптов
PORT=$(python wflow.py --check-acp --exit-code)

Структура проекта

workflow-runner/
├── wflow.py               # Основной скрипт
├── sdk_patches.py         # Патчи для SDK
├── .env.example           # Пример конфигурации
├── requirements.txt       # Зависимости
├── README.md              # Документация (английский)
├── README.ru.md           # Документация (русский)
├── workflows/             # Встроенные workflow
│   ├── demo.yaml          # Демонстрация
│   ├── code-review.yaml   # Code review
│   └── workflow-generator.yaml
└── prompts/               # Промпты
    └── workflow-spec.md   # Спецификация workflow

Лицензия

MIT

FilesExpand file tree

README.ru.md

Latest commit

History

README.ru.md

File metadata and controls

wflow

Особенности

Содержание

Установка

Требования

Шаги установки

Зависимости

Быстрый старт

Запуск встроенного demo workflow

Запуск с полным путём

Пропуск подтверждения

Режим пайплайна (CI/CD)

Интерактивный режим

Использование в любом проекте

Структура проекта

Запуск из проекта

Alias для удобства

Формат workflow

Базовая структура

Поля workflow

Входные параметры (inputs)

Шаги (steps)

Переменные в промптах

Режимы подтверждения (approval_mode)

Обработка ошибок

Команды CLI

Аргументы CLI

Коды возврата (для CI/CD)

Переменные окружения

Файл .env

Примеры workflow

Минимальный workflow

Demo workflow (цепочка шагов)

Code Review workflow

Инструменты iFlow CLI

Файловые операции

Выполнение команд

Web

AI и агенты

Управление

Специализированные агенты

Отладка

Показать конфигурацию

Валидация workflow

Подробный вывод

Debug режим

Проверка ACP сервера

Структура проекта

Лицензия