diff --git a/Install.md b/Install.md new file mode 100644 index 0000000..2e6b79d --- /dev/null +++ b/Install.md @@ -0,0 +1,87 @@ +# DeerFlow Install + +This file is for coding agents. If the DeerFlow repository is not already cloned and open, clone `https://github.com/bytedance/deer-flow.git` first, then continue from the repository root. + +## Goal + +Bootstrap a DeerFlow local development workspace on the user's machine with the least risky path available. + +Default preference: + +1. Docker development environment +2. Local development environment + +Do not assume API keys or model credentials exist. Set up everything that can be prepared safely, then stop with a concise summary of what the user still needs to provide. + +## Operating Rules + +- Be idempotent. Re-running this document should not damage an existing setup. +- Prefer existing repo commands over ad hoc shell commands. +- Do not use `sudo` or install system packages without explicit user approval. +- Do not overwrite existing user config values unless the user asks. +- If a step fails, stop, explain the blocker, and provide the smallest next action. +- If multiple setup paths are possible, prefer Docker when Docker is already available. + +## Success Criteria + +Consider the setup successful when all of the following are true: + +- The DeerFlow repository is cloned and the current working directory is the repo root. +- `config.yaml` exists. +- For Docker setup, `make docker-init` completed successfully and Docker prerequisites are prepared, but services are not assumed to be running yet. +- For local setup, `make check` passed or reported no missing prerequisites, and `make install` completed successfully. +- The user receives the exact next command to launch DeerFlow. +- The user also receives any missing model configuration or referenced environment variable names from `config.yaml`, without inspecting secret-bearing files for actual values. + +## Steps + +- If the current directory is not the DeerFlow repository root, clone `https://github.com/bytedance/deer-flow.git` if needed, then change into the repository root. +- Confirm the current directory is the DeerFlow repository root by checking that `Makefile`, `backend/`, `frontend/`, and `config.example.yaml` exist. +- Detect whether `config.yaml` already exists. +- If `config.yaml` does not exist, run `make config`. +- Detect whether Docker is available and the daemon is reachable with `docker info`. +- If Docker is available: + - Run `make docker-init`. + - Treat this as Docker prerequisite preparation only. Do not claim that app services, compose validation, or image builds have already succeeded. + - Do not start long-running services unless the user explicitly asks or this setup request clearly includes launch verification. + - Tell the user the recommended next command is `make docker-start`. +- If Docker is not available: + - Run `make check`. + - If `make check` reports missing system dependencies such as `node`, `pnpm`, `uv`, or `nginx`, stop and report the missing tools instead of attempting privileged installs. + - If prerequisites are satisfied, run `make install`. + - Tell the user the recommended next command is `make dev`. +- Inspect `config.yaml` only for missing model entries or referenced environment variable placeholders. Do not read `.env`, `frontend/.env`, or other secret-bearing files. +- If no model is configured, tell the user they must add at least one entry under `models` in `config.yaml`. +- If `config.yaml` references variables such as `$OPENAI_API_KEY`, tell the user which variable names still need real values, but do not verify them by opening secret-bearing files. +- If the repository already appears configured, avoid repeating expensive work unless it is necessary to verify the environment. + +## Verification + +Use the lightest verification that matches the chosen setup path. + +For Docker setup: + +- Confirm `make docker-init` completed successfully. +- Confirm `config.yaml` exists. +- State explicitly that Docker services were not started and `make docker-start` is still the first real launch step. +- Do not leave background services running unless the user asked for that. + +For local setup: + +- Confirm `make install` completed successfully. +- Confirm `config.yaml` exists. +- Do not leave background services running unless the user asked for that. + +## Final Response Format + +Return a short status report with: + +1. Setup path used: Docker or local +2. Setup level reached: Docker prerequisites prepared or local dependencies installed +3. Files created or detected: for example `config.yaml` +4. Remaining user action: model config, env var values, auth files, or nothing +5. Exact next command to start DeerFlow + +## EXECUTE NOW + +Complete the steps above. When finished, stop after the setup boundary and report status instead of continuing into unrelated project work. diff --git a/README.md b/README.md index 6e59070..4cd819f 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe - [Official Website](#official-website) - [InfoQuest](#infoquest) - [Table of Contents](#table-of-contents) + - [One-Line Agent Setup](#one-line-agent-setup) - [Quick Start](#quick-start) - [Configuration](#configuration) - [Running the Application](#running-the-application) @@ -75,6 +76,16 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe - [Key Contributors](#key-contributors) - [Star History](#star-history) +## One-Line Agent Setup + +If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence: + +```text +Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md +``` + +That prompt is intended for coding agents. It tells the agent to clone the repo if needed, choose Docker when available, and stop with the exact next command plus any missing config the user still needs to provide. + ## Quick Start ### Configuration diff --git a/README_fr.md b/README_fr.md index 17b1d52..abb7480 100644 --- a/README_fr.md +++ b/README_fr.md @@ -48,6 +48,7 @@ DeerFlow intègre désormais le toolkit de recherche et de crawling intelligent - [Site officiel](#site-officiel) - [InfoQuest](#infoquest) - [Table des matières](#table-des-matières) + - [Installation en une phrase pour un coding agent](#installation-en-une-phrase-pour-un-coding-agent) - [Démarrage rapide](#démarrage-rapide) - [Configuration](#configuration) - [Lancer l'application](#lancer-lapplication) @@ -75,6 +76,16 @@ DeerFlow intègre désormais le toolkit de recherche et de crawling intelligent - [Contributeurs principaux](#contributeurs-principaux) - [Star History](#star-history) +## Installation en une phrase pour un coding agent + +Si vous utilisez Claude Code, Codex, Cursor, Windsurf ou un autre coding agent, vous pouvez simplement lui envoyer cette phrase : + +```text +Aide-moi à cloner DeerFlow si nécessaire, puis à initialiser son environnement de développement local en suivant https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md +``` + +Ce prompt est destiné aux coding agents. Il leur demande de cloner le dépôt si nécessaire, de privilégier Docker quand il est disponible, puis de s'arrêter avec la commande exacte pour lancer DeerFlow et la liste des configurations encore manquantes. + ## Démarrage rapide ### Configuration diff --git a/README_ja.md b/README_ja.md index bd835a1..0a44f31 100644 --- a/README_ja.md +++ b/README_ja.md @@ -48,6 +48,7 @@ DeerFlowは、BytePlusが独自に開発したインテリジェント検索・ - [公式ウェブサイト](#公式ウェブサイト) - [InfoQuest](#infoquest) - [目次](#目次) + - [Coding Agent に一文でセットアップを依頼](#coding-agent-に一文でセットアップを依頼) - [クイックスタート](#クイックスタート) - [設定](#設定) - [アプリケーションの実行](#アプリケーションの実行) @@ -75,6 +76,16 @@ DeerFlowは、BytePlusが独自に開発したインテリジェント検索・ - [主要コントリビューター](#主要コントリビューター) - [Star History](#star-history) +## Coding Agent に一文でセットアップを依頼 + +Claude Code、Codex、Cursor、Windsurf などの coding agent を使っているなら、次の一文をそのまま渡せます。 + +```text +DeerFlow がまだ clone されていなければ先に clone してから、https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md に従ってローカル開発環境を初期化してください +``` + +このプロンプトは coding agent 向けです。必要なら先にリポジトリを clone し、Docker が使える場合は Docker を優先して初期セットアップを行い、最後に次の起動コマンドと不足している設定項目だけを返します。 + ## クイックスタート ### 設定 diff --git a/README_ru.md b/README_ru.md index fef6e4a..dc18847 100644 --- a/README_ru.md +++ b/README_ru.md @@ -50,6 +50,7 @@ DeerFlow интегрирован с инструментарием для ум - [Официальный сайт](#официальный-сайт) - [InfoQuest](#infoquest) - [Содержание](#содержание) + - [Установка одной фразой для coding agent](#установка-одной-фразой-для-coding-agent) - [Быстрый старт](#быстрый-старт) - [Конфигурация](#конфигурация) - [Запуск](#запуск) @@ -77,6 +78,16 @@ DeerFlow интегрирован с инструментарием для ум - [Ключевые контрибьюторы](#ключевые-контрибьюторы) - [История звёзд](#история-звёзд) +## Установка одной фразой для coding agent + +Если вы используете Claude Code, Codex, Cursor, Windsurf или другой coding agent, просто отправьте ему эту фразу: + +```text +Если DeerFlow еще не клонирован, сначала клонируй его, а затем подготовь локальное окружение разработки по инструкции https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md +``` + +Этот prompt предназначен для coding agent. Он просит агента при необходимости сначала клонировать репозиторий, предпочесть Docker, если он доступен, и в конце вернуть точную команду запуска и список недостающих настроек. + ## Быстрый старт ### Конфигурация diff --git a/README_zh.md b/README_zh.md index 6134d9c..9d4f1a2 100644 --- a/README_zh.md +++ b/README_zh.md @@ -36,6 +36,7 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 - [官网](#官网) - [InfoQuest](#infoquest) - [目录](#目录) + - [一句话交给 Coding Agent 安装](#一句话交给-coding-agent-安装) - [快速开始](#快速开始) - [配置](#配置) - [运行应用](#运行应用) @@ -63,6 +64,16 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 - [核心贡献者](#核心贡献者) - [Star History](#star-history) +## 一句话交给 Coding Agent 安装 + +如果你在用 Claude Code、Codex、Cursor、Windsurf 或其他 coding agent，可以直接把下面这句话发给它： + +```text +如果还没 clone DeerFlow，就先 clone，然后按照 https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md 把它的本地开发环境初始化好 +``` + +这条提示词是给 coding agent 用的。它会在需要时先 clone 仓库，优先选择 Docker，完成初始化，并在结束时告诉你下一条启动命令，以及还缺哪些配置需要你补充。 + ## 快速开始 ### 配置