Add optional Docker setup for local development

.dockerignore

@@ -0,0 +1,28 @@
+.git
+.gitignore
+.gitattributes
+
+*.pyc
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+__pycache__/
+.venv/
+env/
+venv/
+.uv-cache
+.env
+.env.*
+
+node_modules/
+WareHouse/
+data/
+temp/
+logs
+.aider*
+
+/frontend
+README*
+compose.yml
+Dockerfile

.env.docker

@@ -0,0 +1,10 @@
+BACKEND_BIND=0.0.0.0
+
+FRONTEND_HOST=0.0.0.0
+FRONTEND_PORT=5173
+
+# Frontend points to the backend service name and exposed port
+VITE_API_BASE_URL=http://backend:6400
+
+# Explicit CORS origins for Docker-based dev (comma-separated)
+CORS_ALLOW_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

.env.example

@@ -0,0 +1,24 @@
+# ============================================================================
+# LLM Provider Configuration
+# ============================================================================
+# BASE_URL and API_KEY are the standard configurations for model call authentication.
+# These variables support OpenAI, Gemini, LM Studio, Ollama, and other providers.
+
+BASE_URL=https://api.openai.com/v1
+API_KEY=sk-your-openai-api-key-here
+
+# Example BASE_URL values:
+# - OpenAI:    https://api.openai.com/v1
+# - Gemini:    https://generativelanguage.googleapis.com/v1beta/openai/
+# - LM Studio: http://localhost:1234/v1
+# - Ollama:    http://localhost:11434/v1
+
+# ============================================================================
+# Optional: Web Search and Reading Tools
+# ============================================================================
+
+# SERPER_DEV_API_KEY=your-serper-api-key-here
+# Get from: https://serper.dev
+
+# JINA_API_KEY=your-jina-api-key-here
+# Get from: https://jina.ai

.github/workflows/validate-yamls.yml

@@ -0,0 +1,70 @@
+name: Validate YAML Workflows
+
+on:
+  pull_request:
+    paths:
+      - 'yaml_instance/**/*.yaml'
+      - '.github/workflows/**/*.yml'
+      - 'tools/validate_all_yamls.py'
+      - 'check/**/*.py'
+
+  push:
+    branches:
+      - main
+    paths:
+      - 'yaml_instance/**/*.yaml'
+      - '.github/workflows/**/*.yml'
+      - 'tools/validate_all_yamls.py'
+      - 'check/**/*.py'
+
+  workflow_dispatch:
+
+jobs:
+  validate:
+    name: Validate YAML Configuration Files
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install system dependencies for pycairo
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libcairo2-dev pkg-config
+
+      - name: Cache uv dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/uv
+            .venv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run YAML validation
+        run: uv run python tools/validate_all_yamls.py
+
+      - name: Report validation results
+        if: always()
+        run: |
+          if [ $? -eq 0 ]; then
+            echo "All YAML workflow files passed validation"
+          else
+            echo "YAML validation failed - check the logs above for details"
+            exit 1
+          fi

.gitignore

@@ -1,18 +1,29 @@
-*.pyc
-.DS_Store
-.idea
-.vscode
+# Python
 __pycache__/
-.env/
+*.pyc
+
+# Virtual environments
 .venv/
-env/
 venv/
-.idea
-.venv
-.uv-cache
-logs
-node_modules
-frontend/.vscode
-WareHouse/
+env/
+
+# uv
+.uv-cache/
+
+# IDEs
+.idea/
+.vscode/
+frontend/.vscode/
+
+# OS
+.DS_Store
+
+# Environment
+.env
+
+# Project Specific
+logs/
+node_modules/
 data/
-temp/
+temp/
+WareHouse/

Dockerfile

@@ -0,0 +1,63 @@
+# ---- Builder: install deps with compilers and uv ----
+FROM python:3.12-slim AS builder
+ARG DEBIAN_FRONTEND=noninteractive
+
+WORKDIR /app
+
+# System deps required to build Python packages
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    pkg-config \
+    build-essential \
+    python3-dev \
+    libcairo2-dev \
+ && rm -rf /var/lib/apt/lists/*
+
+# Install uv just for dependency resolution/install
+RUN pip install --no-cache-dir uv
+
+# Install the project virtualenv outside /app so bind-mounts don't hide it
+ENV UV_PROJECT_ENVIRONMENT=/opt/venv
+
+# Copy dependency files first to maximize cache
+COPY pyproject.toml ./
+# Include lockfile for reproducible builds
+COPY uv.lock ./
+
+# Create the project virtualenv and install deps
+RUN uv sync --no-cache --frozen
+
+# ---- Runtime: minimal image with only runtime libs + app ----
+FROM python:3.12-slim AS runtime
+ARG DEBIAN_FRONTEND=noninteractive
+ARG BACKEND_BIND=0.0.0.0
+
+WORKDIR /app
+
+# Install only runtime system libraries (no compilers)
+# Keep libcairo if your deps need it; remove if unnecessary
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libcairo2 \
+ && rm -rf /var/lib/apt/lists/*
+
+# Copy the prebuilt virtualenv from the builder
+COPY --from=builder /opt/venv /opt/venv
+
+# Copy the rest of the application code
+COPY . .
+
+# Use the venv Python by default and keep Python output unbuffered.
+# Bake default bind/port into the image; can be overridden at runtime.
+ENV PATH="/opt/venv/bin:${PATH}" \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    BACKEND_BIND=${BACKEND_BIND}
+
+# Drop privileges
+RUN useradd -m appuser && chown -R appuser:appuser /app
+USER appuser
+
+# EXPOSE is informational; compose controls published ports
+EXPOSE 6400
+
+# Command to run the backend server, parameterized by env
+CMD ["sh", "-c", "python server_main.py --port 6400 --host ${BACKEND_BIND:-0.0.0.0}"]

Makefile

@@ -0,0 +1,42 @@
+# ==============================================================================
+# Development Commands
+# ==============================================================================
+
+.PHONY: dev
+dev: server client ## Run both backend and frontend development servers
+
+.PHONY: server
+server: ## Start the backend server in the background
+	@echo "Starting server in background..."
+	@uv run python server_main.py --port 6400 --reload &
+
+.PHONY: client
+client: ## Start the frontend development server
+	@cd frontend && VITE_API_BASE_URL=http://localhost:6400 npm run dev
+
+.PHONY: stop
+stop: ## Stop backend and frontend servers
+	@echo "Stopping backend server (port 6400)..."
+	@lsof -t -i:6400 | xargs kill -9 2>/dev/null || echo "Backend server not found on port 6400."
+	@echo "Stopping frontend server (port 5173)..."
+	@lsof -t -i:5173 | xargs kill -9 2>/dev/null || echo "Frontend server not found on port 5173."
+
+# ==============================================================================
+# Tools & Maintenance
+# ==============================================================================
+
+.PHONY: sync
+sync: ## Sync Vue graphs to the server database
+	@uv run python tools/sync_vuegraphs.py
+
+.PHONY: validate-yamls
+validate-yamls: ## Validate all YAML configuration files
+	@uv run python tools/validate_all_yamls.py
+
+# ==============================================================================
+# Help
+# ==============================================================================
+
+.PHONY: help
+help: ## Display this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'

README-zh.md

@@ -118,7 +118,18 @@ ChatDev 已从一个专门的软件开发多智能体系统演变为一个全面
     cd frontend && npm install
     ```
 
-### ⚡️ 运行应用
+### ⚡️ 运行应用（本地）
+
+#### 使用 Makefile（推荐）
+
+**同时启动后端与前端**：
+```bash
+make dev
+```
+
+> 然后访问 Web 控制台：**[http://localhost:5173](http://localhost:5173)**。
+
+#### 手动命令
 
 1.  **启动后端**：
     ```bash
@@ -140,6 +151,44 @@ ChatDev 已从一个专门的软件开发多智能体系统演变为一个全面
     > * **后端**：启动时指定 `--port 6401`
     > * **前端**：设置 `VITE_API_BASE_URL=http://localhost:6401`
 
+#### 常用命令
+
+*   **帮助命令**：
+    ```bash
+    make help
+    ```
+
+*   **同步 YAML 工作流到前端**：
+    ```bash
+    make sync
+    ```
+    将 `yaml_instance/` 中的所有工作流文件上传到数据库。
+
+*   **校验所有 YAML 工作流**：
+    ```bash
+    make validate-yamls
+    ```
+    检查所有 YAML 文件的语法与 schema 错误。
+
+
+### 🐳 使用 Docker 运行
+你也可以通过 Docker Compose 运行整个应用。该方式可简化依赖管理，并提供一致的运行环境。
+
+1.  **前置条件**：
+    *   已安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install/)。
+    *   请确保在项目根目录中存在用于配置 API Key 的 `.env` 文件。
+
+2.  **构建并运行**：
+    ```bash
+    # 在项目根目录执行
+    docker compose up --build
+    ```
+
+3.  **访问地址**：
+    *   **后端**：`http://localhost:6400`
+    *   **前端**：`http://localhost:5173`
+
+> 服务在异常退出后会自动重启，本地文件的修改会同步映射到容器中，便于实时开发。
 
 ### 🔑 配置
 
@@ -252,6 +301,7 @@ if result.final_message:
     <td align="center"><a href="https://github.com/shiowen"><img src="https://github.com/shiowen.png?size=100" width="64px;" alt=""/><br /><sub><b>shiowen</b></sub></a></td>
     <td align="center"><a href="https://github.com/kilo2127"><img src="https://github.com/kilo2127.png?size=100" width="64px;" alt=""/><br /><sub><b>kilo2127</b></sub></a></td>
     <td align="center"><a href="https://github.com/AckerlyLau"><img src="https://github.com/AckerlyLau.png?size=100" width="64px;" alt=""/><br /><sub><b>AckerlyLau</b></sub></a></td>
+    <td align="center"><a href="https://github.com/LaansDole"><img src="https://github.com/LaansDole.png?size=100" width="64px;" alt=""/><br /><sub><b>LaansDole</b></sub></a></td>
 </table>
 
 ## 🤝 致谢