Документация AI-Flow

AI-Flow — это система иерархического планирования продукта, рассчитанная на совместную работу человека и AI-агентов. Вы описываете замысел свободным текстом, а агенты через MCP раскладывают его на дерево задач, наполняют документацию, ведут статусы и собирают релизы.

Главная идея: тикет — это память. Агент между сессиями не помнит ничего, поэтому вся истина живёт в нодах: спецификация в контенте, ход работы — в комментариях, реальное состояние — в статусе и прогрессе.

Иерархия нод

Любая единица работы — это нода. Ноды образуют строгое дерево от продукта до конкретной задачи. Вложенность не ограничена, но рекомендуется выбирать минимальную глубину, которая остаётся читаемой.

Типы нод

У каждой ноды есть тип (kind). Он определяет её роль в дереве.

Жизненный цикл статусов

У каждой ноды есть статус. Агент двигает его явно через update_node_status. Прогресс (0..100) задаётся отдельно для длинных задач через update_node_progress.

Связи между нодами

Помимо иерархии «родитель → ребёнок», ноды связываются ещё тремя способами. Все связи видны в деталях ноды и на интерактивном графе.

Полный список объектов, с которыми вы работаете в AI-Flow — в интерфейсе и через MCP.

Тёмный интерфейс для людей: три вкладки проекта — «Планирование», «Документация» и «Ревью». Создавайте проекты, редактируйте ноды, смотрите граф и ведите документацию. Доступен на русском и английском.

Разделы проекта

Настройки

• MCP — генерация и отзыв токенов доступа, готовый конфиг для Claude Code и Cursor, тест через curl.
• Скиллы — скачивание набора скиллов (.zip) для обучения агентов работе с AI-Flow.
• Переключатель языка (RU / EN) и выбор организации/проекта в шапке.

MCP-сервер — это HTTP-эндпоинт с аутентификацией по Bearer-токену. Через него AI-агент читает и меняет ноды напрямую, не выходя из своего рабочего процесса.

Подключение за три шага

1. 01Зарегистрируйтесь и войдите в веб-приложение.
2. 02На странице MCP создайте Personal Access Token (PAT) — он показывается только один раз, скопируйте его сразу.
3. 03Пропишите URL сервера и заголовок Authorization в конфиге своего агента.

1{2  "mcpServers": {3    "ai-flow": {4      "url": "https://mcp.flow.shipoora.ru/mcp",5      "headers": { "Authorization": "Bearer aiflow_pat_..." }6    }7  }8}

1curl -X POST https://mcp.flow.shipoora.ru/mcp \2  -H "Authorization: Bearer aiflow_pat_..." \3  -H "Content-Type: application/json" \4  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",5       "params":{"protocolVersion":"2025-11-25",6       "capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

Справочник инструментов

Большинство инструментов принимают либо node_id, либо slug + project_id. Слаги читабельнее — используйте их.

У проекта есть собственный семантический индекс: всё, что вы пишете в нодах, документах и комментариях, автоматически превращается в векторы и ищется по смыслу, а не по совпадению слов. Эмбеддинги считаются локально на CPU — содержимое проекта не уходит во внешние AI-сервисы.

Как устроено

Из агента — через MCP

Три инструмента закрывают весь сценарий: проверить индекс, найти похожее, поднять готовый контекст в промпт.

1rag_status(project_id)2  → состояние индекса: сколько чанков, размерность, что не синхронизировано3 4rag_query(project_id, "как устроена авторизация", k=5)5  → ранжированные по смыслу фрагменты нод и комментариев6 7rag_context(project_id, "авторизация", max_chars=8000)8  → собранный Markdown-блок, который можно сразу вставить в промпт

Из интерфейса

• Индикатор состояния у ноды и у каждого комментария: в очереди, индексируется, синхронизировано, ошибка.
• Ручная пересборка индекса — для одной ноды или для всего проекта целиком.
• Живой прогресс синхронизации проекта: сервер шлёт обновления потоком, страницу обновлять не нужно.
• История синхронизаций с отметками времени и причинами ошибок.

AI-Flow хранит код-ревью прямо рядом с планом. Агент (или человек) запускает ревью ветки, а результат сохраняется во вкладке «Ревью» проекта и привязывается к конкретным нодам, которые проверялись.

Как устроено ревью

Поток работы

1. 01Агент со скиллом ai-flow-review прогоняет ревью по диффу ветки.
2. 02Результат сохраняется как ревью с первой итерацией (commit + заключение).
3. 03Ревью привязывается к проверённым нодам — появляются переходы «ревью ↔ планирование».
4. 04После правок добавляется следующая итерация — история накапливается, а не перезаписывается.

Скиллы — это переиспользуемые инструкции (SKILL.md), которые учат агента работать с AI-Flow правильно: соблюдать иерархию, вести тикет как память, корректно двигать статусы. Скачать весь набор можно на странице «Скиллы» в приложении.

Типичный цикл работы

1. 01Опишите замысел продукта (свободный текст или Markdown-спецификация).
2. 02Агент через MCP раскладывает идею на эпики, фичи, планы и задачи.
3. 03Задачи выполняются по одной; каждый шаг фиксируется комментарием, статус и прогресс остаются честными.
4. 04Ревью проверяет результат по критериям приёмки и собирает документацию с перекрёстными ссылками.
5. 05Готовые задачи группируются в релизы — граф, доки и прогресс обновляются автоматически.

AI-Flow находится в стадии MVP. Часть возможностей ещё в разработке — честно перечисляем, чего пока нет.

Текущие ограничения

• Семантический поиск ищет по нодам, документам и комментариям; вложения и внешние источники в индекс не попадают.
• Автоматизация переходов между статусами частично ручная.
• UI управления организациями и шаринг проектов между пользователями в работе.
• Рендер Mermaid в Markdown-контенте пока не поддержан.
• Доступ к ноде идёт по node_id или slug + project_id — глобально уникальны только UUID.

В планах

• Поиск по вложениям и внешним источникам в том же семантическом индексе.
• Автопереходы статусов и каскадный rollup прогресса.
• Полноценный UI организаций и совместный доступ.
• Рендер Mermaid-диаграмм в контенте нод.

Harness — это не чат и не набор промптов. Это версия процесса: роли, граф шагов, правила доступа, лимиты, ожидаемые входы и результаты. Один и тот же Harness можно безопасно повторять для разных задач.

Когда он нужен

Главный принцип

Вместо скрытого рассуждения Harness хранит проверяемые рабочие артефакты: предложения, утверждения, доказательства, критики, голоса и итоговое решение. Это позволяет понять, что было выбрано и почему.

Обычный поток

1. 01Пользователь запускает версию Harness с задачей и ссылками на ноды AI-Flow.
2. 02Роли получают только разрешённый контекст и независимо создают предложения.
3. 03Участники проверяют предложения через claims, evidence и critiques; авторы могут выпустить revision.
4. 04Голосование или judge формирует решение, после чего human gate принимает, отклоняет или отправляет его на доработку.
5. 05Одобренное решение создаёт черновик task plan; его применение к дереву AI-Flow остаётся отдельным подтверждаемым действием.

Два режима оркестрации

Конфигурация

Во время запуска

• HarnessRun — один запуск версии с входными данными, источниками AI-Flow и снимком бюджета/политик.
• AgentInstance и AgentAssignment — конкретный участник и его инструкция.
• StepRun и WorkItem — состояние шага и lease, по которому внешний агент получает, продлевает, завершает или освобождает работу.
• RunEvent и Artifact — неизменяемая история и полезные результаты запуска.

Обсуждение и решение

Deliberation объединяет Proposal, Claim, Evidence, Critique и DeliberationResponse. Ballot и Vote фиксируют выбор, Decision — его обоснование и статус. ApprovalRequest переводит важное действие в очередь человека, а TaskPlanDraft и ProposedNode готовят перенос результата в дерево AI-Flow.

Соберите версию

1. 01Создайте Harness для одного повторяемого вида решения, а не универсального совета.
2. 02Создайте Version и зафиксируйте input/output schema, роли и граф шагов.
3. 03Опишите для каждой роли цель, обязанности, запреты и формат результата.
4. 04Добавьте правила инструментов, доступа к данным, голосования, бюджета и human approval.
5. 05Провалидируйте граф и публикуйте версию только после проверки.

1harness_create({ name: "architecture-review", description: "Оценка архитектурных вариантов перед выбором" })2harness_create_version({ harness_id, input_schema, output_schema })3harness_add_role({ version_id, key: "proposer", goal: "Предложить вариант решения" })4harness_add_workflow_node({ version_id, kind: "proposal", role_key: "proposer" })5harness_validate({ version_id })6harness_publish({ version_id })

Запустите и наблюдайте

Run получает краткую цель, нужный контекст и ссылки на ноды AI-Flow. Следите не за скрытым чатом, а за timeline, назначениями, открытыми критиками, голосами, budget check и запросами подтверждения.

Участие внешнего агента

Агент находит доступный WorkItem, забирает lease, регулярно отправляет heartbeat и публикует результат в структурированном виде. Если он не успевает, lease истекает и работа безопасно возвращается в очередь; дублирование не должно создавать второй результат.

1work_list_available({ run_id })2work_claim({ work_item_id, agent_instance_id })3work_heartbeat({ work_item_id, lease_token })4work_complete({ work_item_id, lease_token, result: { summary: "Итог по назначенному шагу" } })

Контекст и изоляция

ContextPolicy задаёт включаемые источники: вход запуска, ноды AI-Flow, предыдущий раунд или только назначенные материалы. Она также исключает чувствительные пути, ограничивает объём и может скрывать авторов. Не передавайте агентам весь проект по умолчанию.

Политики и бюджеты

Аудит и защита

RunEvent формирует timeline, Artifact хранит полезный результат, а полномочия разделяются на read, write, start, participate, vote и approval. Данные из кода и документов считаются недоверенными: их нельзя исполнять как инструкции без явной политики.

MCP-поверхность

1council_submit_proposal({2  run_id: "run_8f2c1",3  role_key: "proposer",4  summary: "Разделить сервис уведомлений на отдельный воркер",5  body: "Снижает связность релизов и позволяет независимо масштабировать очередь"6})

Глоссарий

• Definition — именованный шаблон; Version — неизменяемая опубликованная конфигурация.
• Run — экземпляр Version; StepRun — конкретное прохождение узла workflow; WorkItem — leased единица работы для внешнего участника.
• Proposal — вариант решения; Claim — проверяемое утверждение; Evidence — материал, который его поддерживает или опровергает; Critique — обоснованное возражение.
• Ballot — правила и варианты голосования; Vote — голос; Decision — выбранный и объяснённый результат; ApprovalRequest — действие, ожидающее человека.
• Artifact — полезный выход; RunEvent — неизменяемая запись истории; TaskPlanDraft — ещё не применённый план изменений AI-Flow.

Частые вопросы