diff --git a/.gitignore b/.gitignore index e32962ae..28c8945a 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,7 @@ extensions_config.json # IDE .idea/ .vscode/ +.qoder/ # Coverage report coverage.xml @@ -63,3 +64,4 @@ config.yaml.bak skills/gstack skills/superpowers CLAUDE.md +AGENTS.md diff --git a/README_zh.md b/README_zh.md index d5317082..297aa29f 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,20 +1,59 @@ -# 🦌 DeerFlow - 2.0 +# 🦌 DeerFlow - 2.0 · 多租户改造 [English](./README.md) | 中文 | [日本語](./README_ja.md) | [Français](./README_fr.md) | [Русский](./README_ru.md) [![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](./backend/pyproject.toml) [![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](./Makefile) +[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-default-4169E1?logo=postgresql&logoColor=white)](./config.example.yaml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) -bytedance%2Fdeer-flow | Trendshift -> 2026 年 2 月 28 日，DeerFlow 2 发布后登上 GitHub Trending 第 1 名。非常感谢社区的支持，这是大家一起做到的。 +DeerFlow（**D**eep **E**xploration and **E**fficient **R**esearch **Flow**）是一个开源的 **super agent harness**：它把 **sub-agents**、**memory**、**sandbox** 组织在一起，再配合可扩展的 **skills**，让 agent 可以完成几乎任何事情。 -DeerFlow（**D**eep **E**xploration and **E**fficient **R**esearch **Flow**）是一个开源的 **super agent harness**。它把 **sub-agents**、**memory** 和 **sandbox** 组织在一起，再配合可扩展的 **skills**，让 agent 可以完成几乎任何事情。 +> [!IMPORTANT] +> **本分支（`docs/multi-tenant-redesign`）是 DeerFlow 的多租户改造主线。** 在保留原有 super agent harness 全部能力的基础上，引入了 **workspace 租户模型、Postgres 为默认后端、带 `workspace_id` 的行级数据隔离、扩展后的 JWT（带 `wid`/`role`）、per-workspace 的文件系统布局、Headless API schema 底座，以及 `apps/` 上层应用脚手架**。下面的 [多租户改造](#多租户改造本分支主线) 一节是阅读本仓库的入口。 + +> [!NOTE] +> **DeerFlow 2.0 是一次彻底重写。** 它和 v1 没有共用代码。如果你要找的是最初的 Deep Research 框架，可以前往 [`1.x` 分支](https://github.com/bytedance/deer-flow/tree/main-1.x)。 https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 -> [!NOTE] -> **DeerFlow 2.0 是一次彻底重写。** 它和 v1 没有共用代码。如果你要找的是最初的 Deep Research 框架，可以前往 [`1.x` 分支](https://github.com/bytedance/deer-flow/tree/main-1.x)。那里仍然欢迎贡献；当前的主要开发已经转向 2.0。 +## 多租户改造（本分支主线） + +DeerFlow 原本面向"单机可信环境、单用户"。本分支按"以个人用户为主、少量小团队，统一只有 **workspace** 概念（个人 = 1 人 workspace），中心化 SaaS 为主线"的目标，把租户能力分 **Stage 0–4** 渐进落地。**目前 Stage 0（底座）工程层面已全部合入。** + +### Stage 0 已落地的能力 + +| 能力 | 说明 | 落点 | +|---|---|---| +| **workspace 租户模型** | 新增 `workspaces` + `workspace_memberships` 两张表与仓储；每个用户注册时自动建 1 人 workspace（owner=自己）；slug 唯一、黑名单校验。 | `persistence/workspace*` | +| **Postgres 成为默认后端** | `config.example.yaml` / `.env.example` / `make dev` / `make doctor` 默认走 Postgres，与生产对齐；SQLite 保留为离线开发兜底。 | 见 [数据库后端](#数据库后端) | +| **行级数据隔离** | 4 张业务表（`threads_meta` / `runs` / `run_events` / `feedback`）加 `workspace_id` 列（`NOT NULL` + `UNIQUE(workspace_id, thread_id)` 兜底），入口路由按 `(workspace_id, thread_id)` 强校验，跨 workspace 访问必 404。 | `persistence/*`、Gateway routers | +| **扩展后的 JWT** | TokenPayload 一次到位为 `{sub, wid, role, exp, iat, ver}`；登录 / 改密 / `/auth/me` 全部带上 workspace 与角色；旧版 4 字段 JWT 被识别为 `WORKSPACE_MISSING` 并要求重登。 | `app/gateway/auth/` | +| **per-workspace 文件系统** | 运行期状态从 `users/{uid}/...` 迁移到 `workspaces/{wid}/threads/{tid}/...`，提供 `make migrate-paths` 迁移脚本（支持 `DRY_RUN=1` 预览）。 | `config/paths.py`、`thread_data_middleware.py` | +| **边界扫描围栏** | CI 静态扫描禁止任何路径绕过入口直连 LangGraph checkpoint/store，确保隔离不被旁路。 | `tests/boundary_allowlist.toml`、`test_workspace_boundary*.py` | +| **Headless API schema 底座** | 预建 `service_accounts` / `api_keys`（`dfk_live_*` / `dfk_test_*`）/ `external_users` 三张表（schema-only），为 Stage 1 的无人值守接入做准备。 | `persistence/{service_account,api_key,external_user}` | +| **Alembic 迁移 + 回填** | `0001`→`0003` 迁移链 + `backfill_workspace_id.py` 回填脚本，dev 用 `create_all()` 自愈、生产用迁移。 | `persistence/migrations/` | + +> 数据库的事实参考（10 张表全字段 / 外键 / 索引）见 [`database-schema-as-built.zh-CN.md`](docs/multi-tenant-redesign/01-redesign/database-schema-as-built.zh-CN.md)。 + +### 路线图：Stage 0–4 + +| Stage | 目标 | 关键内容 | 状态 | +|---|---|---|---| +| **0** | workspace 模型立起来 + Postgres 切换 + auth 收紧 | 上表全部 | ✅ 工程层面已合入（业务门 / live 验证待跟进）| +| **1** | 第一批付费客户 + 业务系统集成（双轨并行）| quota + 计费 + AioSandbox 轻量加固；Headless API（Pattern A/B）接通 PR8 三张表 | 🔜 已具备底座 | +| **2** | 增长期，安全与隔离深化 | DeerFlow 自有表启用 RLS、KMS、ObjectStorage、完整 RBAC + invitation | 📋 规划中 | +| **3** | 成熟期，K8s 隔离 + BYO | K8s namespace + NetworkPolicy、BYO LLM key、audit DB 拆分 | 📋 规划中 | +| **4** | 企业化，按需开启 | SSO、自定义域名、per-tenant DB、gVisor/Kata、合规审计 | 📋 按合同 | + +### 多租户文档入口 + +- **汇总索引（先读这个）**：[`docs/multi-tenant-redesign/README.zh-CN.md`](docs/multi-tenant-redesign/README.zh-CN.md) +- **现状架构鸟瞰**：[`00-current-state/architecture-overview.zh-CN.md`](docs/multi-tenant-redesign/00-current-state/architecture-overview.zh-CN.md) +- **决策（7 份 ADR + spike + 审计）**：[`01-redesign/`](docs/multi-tenant-redesign/01-redesign/) +- **Stage 0 schema 锁定版 / 落地版**：[`workspace-schema-design`](docs/multi-tenant-redesign/01-redesign/workspace-schema-design.zh-CN.md) · [`database-schema-as-built`](docs/multi-tenant-redesign/01-redesign/database-schema-as-built.zh-CN.md) +- **落地路线 + 集成轨道**：[`02-rollout/`](docs/multi-tenant-redesign/02-rollout/) +- **Stage 0 进度面板（权威"现在到哪了"）**：[`03-impl/STATUS.md`](docs/multi-tenant-redesign/03-impl/STATUS.md) ## 官网 @@ -32,13 +71,13 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 ## 目录 -- [🦌 DeerFlow - 2.0](#-deerflow---20) +- [🦌 DeerFlow - 2.0 · 多租户改造](#-deerflow---20--多租户改造) + - [多租户改造（本分支主线）](#多租户改造本分支主线) - [官网](#官网) - - [InfoQuest](#infoquest) - - [目录](#目录) - - [一句话交给 Coding Agent 安装](#一句话交给-coding-agent-安装) + - [字节跳动火山引擎方舟 Coding Plan](#字节跳动火山引擎方舟-coding-plan) - [快速开始](#快速开始) - [配置](#配置) + - [数据库后端](#数据库后端) - [运行应用](#运行应用) - [部署建议与资源规划](#部署建议与资源规划) - [方式一：Docker（推荐）](#方式一docker推荐) @@ -48,7 +87,7 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 - [MCP Server](#mcp-server) - [IM 渠道](#im-渠道) - [LangSmith 链路追踪](#langsmith-链路追踪) - - [从 Deep Research 到 Super Agent Harness](#从-deep-research-到-super-agent-harness) + - [多租户架构详解](#多租户架构详解) - [核心特性](#核心特性) - [Skills 与 Tools](#skills-与-tools) - [Claude Code 集成](#claude-code-集成) @@ -56,25 +95,14 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 - [Sandbox 与文件系统](#sandbox-与文件系统) - [Context Engineering](#context-engineering) - [长期记忆](#长期记忆) - - [推荐模型](#推荐模型) + - [在 DeerFlow 之上构建应用（apps/）](#在-deerflow-之上构建应用apps) - [内嵌 Python Client](#内嵌-python-client) + - [推荐模型](#推荐模型) - [文档](#文档) - [⚠️ 安全使用](#️-安全使用) - [参与贡献](#参与贡献) - [许可证](#许可证) - [致谢](#致谢) - - [核心贡献者](#核心贡献者) - - [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，完成初始化，并在结束时告诉你下一条启动命令，以及还缺哪些配置需要你补充。 ## 快速开始 @@ -149,6 +177,48 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 api_key: your-actual-api-key-here # 替换为真实 key ``` +### 数据库后端 + +多租户改造后，**Stage 0+ 默认后端是 Postgres**（与生产对齐，并为后续 RLS 留好空间）。`config.example.yaml` 默认带： + +```yaml +database: + backend: postgres + postgres_url: $DATABASE_URL +``` + +在 `.env` 中设置 `DATABASE_URL`： + +```bash +DATABASE_URL=postgresql+asyncpg://deerflow:deerflow_dev@localhost:5432/deerflow +# 远程 RDS / Cloud SQL 示例： +# DATABASE_URL=postgresql+asyncpg://USER:PASSWORD@HOST:5432/DBNAME +``` + +启动本地 Postgres 开发容器： + +```bash +docker compose -f docker/docker-compose-dev.yaml up -d postgres +``` + +- `make doctor` 会报告当前配置的后端、尝试 asyncpg 连接，并给出可执行的修复建议。 +- `make dev` 在启动各服务前会先 preflight Postgres 可达性；`DATABASE_URL` 不可达时直接中止。 +- **dev** 启动时用 `Base.metadata.create_all()` 自动建缺失的表（不改已存在的表）；**生产**用 Alembic 迁移（`backend/packages/harness/deerflow/persistence/migrations/`）。目标库不存在时会自动 `CREATE DATABASE` 后重试。 + +
+离线开发（SQLite 兜底） + +如果你不想起 Postgres，把 `config.yaml` 改成： + +```yaml +database: + backend: sqlite + sqlite_dir: .deer-flow/data +``` + +SQLite 仍是合法的离线开发后端；但 RLS / 多节点等 Stage 2+ 能力需要 Postgres。 +
+ ### 运行应用 #### 部署建议与资源规划 @@ -194,7 +264,7 @@ make down # 停止并移除容器 如果你更希望直接在本地启动各个服务： -前提：先完成上面的“配置”步骤（`make config` 和模型 API key 配置）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`。可以用 `DEER_FLOW_PROJECT_ROOT` 显式指定项目根目录，也可以用 `DEER_FLOW_CONFIG_PATH` 指向某个具体配置文件。运行期状态默认写到项目根目录下的 `.deer-flow`，可用 `DEER_FLOW_HOME` 覆盖；skills 默认读取项目根目录下的 `skills/`，可用 `DEER_FLOW_SKILLS_PATH` 覆盖。 +前提：先完成上面的"配置"步骤（`make config`、模型 API key、`DATABASE_URL`）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`。可以用 `DEER_FLOW_PROJECT_ROOT` 显式指定项目根目录，也可以用 `DEER_FLOW_CONFIG_PATH` 指向某个具体配置文件。运行期状态默认写到项目根目录下的 `.deer-flow`，可用 `DEER_FLOW_HOME` 覆盖；skills 默认读取项目根目录下的 `skills/`，可用 `DEER_FLOW_SKILLS_PATH` 覆盖。 在 Windows 上，请使用 Git Bash 运行本地开发流程。基于 bash 的服务脚本不支持直接在原生 `cmd.exe` 或 PowerShell 中执行，且 WSL 也不保证可用，因为部分脚本依赖 Git for Windows 的 `cygpath` 等工具。 1. **检查依赖环境**： @@ -220,6 +290,16 @@ make down # 停止并移除容器 5. **访问地址**：http://localhost:2026 +> [!TIP] +> `make dev` 是前台阻塞运行。日常调试更顺手的是仓库根 `scripts/` 下两个生命周期脚本（子命令统一为 `start / stop / restart / status / logs / run`）： +> - `scripts/dev-gateway.sh` — 只起 Gateway（`http://localhost:8001`），起得快，适合调后端 API / 接入示例。 +> - `scripts/dev-full.sh` — Gateway + 前端 + nginx（`http://localhost:2026`），连前端一起调。 +> +> 例如 `./scripts/dev-gateway.sh start`、`./scripts/dev-gateway.sh logs`、`SKIP_INSTALL=1 ./scripts/dev-full.sh start`。详见 [apps/README.md](apps/README.md)。 + +> [!NOTE] +> 把历史的 `users/` 目录树迁移到新的 per-workspace 布局：`make migrate-paths`（加 `DRY_RUN=1` 仅预览，`DEFAULT_WORKSPACE=` 指定未分配用户的归属 workspace）。 + ### 进阶配置 #### Sandbox 模式 @@ -405,23 +485,48 @@ LANGSMITH_PROJECT=xxx Docker 部署时，追踪默认关闭。在 `.env` 中设置 `LANGSMITH_TRACING=true` 和 `LANGSMITH_API_KEY` 即可启用。 -## 从 Deep Research 到 Super Agent Harness +## 多租户架构详解 -DeerFlow 最初是一个 Deep Research 框架，后来社区把它一路推到了更远的地方。上线之后，开发者拿它去做的事情早就不止研究：搭数据流水线、生成演示文稿、快速起 dashboard、自动化内容流程，很多方向一开始连我们自己都没想到。 +> 这一节展开 [多租户改造](#多租户改造本分支主线) 里 Stage 0 已落地的实现细节。完整决策与路线见 [`docs/multi-tenant-redesign/`](docs/multi-tenant-redesign/)。 -这让我们意识到一件事：DeerFlow 不只是一个研究工具。它更像一个 **harness**，一个真正让 agents 把事情做完的运行时基础设施。 +**workspace 是唯一的隔离粒度。** 个人用户 = 1 人 workspace，小团队 = 多人 workspace。骨架是两条主线： -所以我们把它从头重做了一遍。 +1. **租户骨架**：`users` ↔ `workspaces`（多对多经 `workspace_memberships`）。每个用户注册时自动建 1 人 workspace（owner=自己），slug 唯一且过黑名单校验。 +2. **业务数据**：`threads_meta` → `runs` → `run_events` / `feedback`，全部挂 `workspace_id`（行级隔离），workspace 删除时级联清空。 -DeerFlow 2.0 不再是一个需要你自己拼装的 framework。它是一个开箱即用、同时又足够可扩展的 super agent harness。基于 LangGraph 和 LangChain 构建，默认就带上了 agent 真正会用到的关键能力：文件系统、memory、skills、sandbox 执行环境，以及为复杂多步骤任务做规划、拉起 sub-agents 的能力。 +**数据隔离怎么做的。** DeerFlow 自有表走行级 `workspace_id` + `UNIQUE(workspace_id, thread_id)` 兜底；入口路由（`threads.py` / `thread_runs.py`）按 `(workspace_id, thread_id)` 强校验，跨 workspace 访问必返 404。LangGraph 自己的 checkpointer / store 表（`langgraph-checkpoint-postgres==3.0.5` 无 `connection_factory`，无法注入 RLS）则走**应用层强校验**，并由 CI 静态扫描（`tests/boundary_allowlist.toml`）禁止任何路径绕过入口直连这些表。 -你可以直接拿来用，也可以拆开重组，改成你自己的样子。 +**身份与会话。** JWT TokenPayload 一次到位为 `{sub, wid, role, exp, iat, ver}`： + +- `wid` — 当前 workspace；`role` — workspace 内角色（Stage 0 简化为 owner-only，Stage 2 扩到 owner/admin/member）。 +- `ver` — `token_version`，bump 后旧 token 全失效。 +- 旧版 4 字段 JWT 会被识别为 `WORKSPACE_MISSING` 并要求重登；登录 / 改密 / `/auth/me` 都会带上 workspace 与角色（`/auth/me` 返回 `workspaces[]`，含 id/name/slug/role）。 + +**文件系统布局。** 运行期状态按 workspace 分目录： + +```text +${DEER_FLOW_HOME:-./.deer-flow}/ +└── workspaces/ + └── {workspace_id}/ + ├── threads/{thread_id}/... ← 每个 thread 的 sandbox / 产物 + └── users/{user_id}/... ← 用户级状态 +``` + +历史的 `users/{uid}/...` 布局用 `make migrate-paths`（`DRY_RUN=1` 预览）迁移过来。 + +**Headless API schema 底座（Stage 0 末预建，schema-only）。** 为 Stage 1 的无人值守 / 业务系统接入准备： + +- `service_accounts` — workspace 内的非人身份，带 `identity_mode` 三态（`collapsed` / `external_passthrough` / `both`）。 +- `api_keys` — service account 的凭证，格式 `dfk_live_*` / `dfk_test_*`，`key_prefix` 全局唯一 + 部分索引 `WHERE revoked_at IS NULL`。 +- `external_users` — passthrough 终端身份，`(service_account_id, external_id)` 复合唯一。 + +> ⚠️ Stage 0 只建表，**API Key 鉴权中间件尚未接入**。外部系统当前只能走会话 cookie（见 [apps/README.md](apps/README.md) 的鉴权说明）；等 `Authorization: Bearer dfk_live_...` 在 Stage 1 落地后再补无人值守接入。 ## 核心特性 ### Skills 与 Tools -Skills 是 DeerFlow 能做“几乎任何事”的关键。 +Skills 是 DeerFlow 能做"几乎任何事"的关键。 标准的 Agent Skill 是一种结构化能力模块，通常就是一个 Markdown 文件，里面定义了工作流、最佳实践，以及相关的参考资源。DeerFlow 自带一批内置 skills，覆盖研究、报告生成、演示文稿制作、网页生成、图像和视频生成等场景。真正有意思的地方在于它的扩展性：你可以加自己的 skills，替换内置 skills，或者把多个 skills 组合成复合工作流。 @@ -431,8 +536,6 @@ Skills 采用按需渐进加载，不会一次性把所有内容都塞进上下 Tools 也是同样的思路。DeerFlow 自带一组核心工具：网页搜索、网页抓取、文件操作、bash 执行；同时也支持通过 MCP Server 和 Python 函数扩展自定义工具。你可以替换任何一项，也可以继续往里加。 -Gateway 生成后续建议时，现在会先把普通字符串输出和 block/list 风格的富文本内容统一归一化，再去解析 JSON 数组响应，因此不同 provider 的内容包装方式不会再悄悄把建议吞掉。 - ```text # sandbox 容器内的路径 /mnt/skills/public @@ -456,24 +559,7 @@ Gateway 生成后续建议时，现在会先把普通字符串输出和 block/li npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow ``` -然后确认 DeerFlow 已经启动（默认地址是 `http://localhost:2026`），在 Claude Code 里使用 `/claude-to-deerflow` 命令即可。 - -**你可以做的事情包括：** -- 给 DeerFlow 发送消息，并接收流式响应 -- 选择执行模式：flash（更快）、standard、pro（规划模式）、ultra（sub-agents 模式） -- 检查 DeerFlow 健康状态，列出 models / skills / agents -- 管理 threads 和会话历史 -- 上传文件做分析 - -**环境变量**（可选，用于自定义端点）： - -```bash -DEERFLOW_URL=http://localhost:2026 # 统一代理基地址 -DEERFLOW_GATEWAY_URL=http://localhost:2026 # Gateway API -DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph # LangGraph API -``` - -完整 API 说明见 [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md)。 +然后确认 DeerFlow 已经启动（默认地址是 `http://localhost:2026`），在 Claude Code 里使用 `/claude-to-deerflow` 命令即可。完整 API 说明见 [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md)。 ### Sub-Agents @@ -485,12 +571,10 @@ lead agent 可以按需动态拉起 sub-agents。每个 sub-agent 都有自己 ### Sandbox 与文件系统 -DeerFlow 不只是“会说它能做”，它是真的有一台自己的“电脑”。 +DeerFlow 不只是"会说它能做"，它是真的有一台自己的"电脑"。 每个任务都运行在隔离的 Docker 容器里，里面有完整的文件系统，包括 skills、workspace、uploads、outputs。agent 可以读写和编辑文件，可以执行 bash 命令和代码，也可以查看图片。整个过程都在 sandbox 内完成，可审计、会隔离，不会在不同 session 之间互相污染。 -这就是“带工具的聊天机器人”和“真正有执行环境的 agent”之间的差别。 - ```text # sandbox 容器内的路径 /mnt/user-data/ @@ -509,16 +593,30 @@ DeerFlow 不只是“会说它能做”，它是真的有一台自己的“电 大多数 agents 会在对话结束后把一切都忘掉，DeerFlow 不一样。 -跨 session 使用时，DeerFlow 会逐步积累关于你的持久 memory，包括你的个人偏好、知识背景，以及长期沉淀下来的工作习惯。你用得越多，它越了解你的写作风格、技术栈和重复出现的工作流。memory 保存在本地，控制权也始终在你手里。 +跨 session 使用时，DeerFlow 会逐步积累关于你的持久 memory，包括你的个人偏好、知识背景，以及长期沉淀下来的工作习惯。你用得越多，它越了解你的写作风格、技术栈和重复出现的工作流。 -## 推荐模型 +## 在 DeerFlow 之上构建应用（apps/） -DeerFlow 对模型没有强绑定，只要实现了 OpenAI 兼容 API 的 LLM，理论上都可以接入。不过在下面这些能力上表现更强的模型，通常会更适合 DeerFlow： +`apps/`（仓库根目录、与 `backend/` / `frontend/` 平级）用于存放**消费 DeerFlow 能力的上层应用**，遵循严格的依赖方向：**app 可以依赖 deerflow，deerflow 不能依赖 app / apps**。 -- **长上下文窗口**（100k+ tokens），适合深度研究和多步骤任务 -- **推理能力**，适合自适应规划和复杂拆解 -- **多模态输入**，适合理解图片和视频 -- **稳定的 tool use 能力**，适合可靠的函数调用和结构化输出 +两种集成模式： + +| 模式 | 适用场景 | 怎么连 | 示例 | +|---|---|---|---| +| **HTTP Gateway**（REST+SSE） | 上层是别的服务 / 多语言 | 调 `http://localhost:2026/api/*` | [`apps/examples/http-chat/`](apps/examples/http-chat/) | +| **内嵌 DeerFlowClient** | 上层本身是 Python，进程内直接当 SDK 调 | `from deerflow.client import DeerFlowClient` | [`apps/examples/embedded-chat/`](apps/examples/embedded-chat/) | + +每个示例自带 `run.sh`： + +```bash +# ① HTTP 模式：需要先起 Gateway（dev-gateway 或 dev-full 都行） +./apps/examples/http-chat/run.sh + +# ② 内嵌模式：不需要起任何服务，run.sh 自动进 backend uv 环境运行 +./apps/examples/embedded-chat/run.sh +``` + +完整说明、鉴权流程与新建应用约定见 [apps/README.md](apps/README.md)。 ## 内嵌 Python Client @@ -546,12 +644,25 @@ client.upload_files("thread-1", ["./report.pdf"]) # {"success": True, "files": 所有返回 dict 的方法都会在 CI 中通过 Gateway 的 Pydantic 响应模型校验（`TestGatewayConformance`），以确保内嵌 client 始终和 HTTP API schema 保持同步。完整 API 说明见 `backend/packages/harness/deerflow/client.py`。 +## 推荐模型 + +DeerFlow 对模型没有强绑定，只要实现了 OpenAI 兼容 API 的 LLM，理论上都可以接入。不过在下面这些能力上表现更强的模型，通常会更适合 DeerFlow： + +- **长上下文窗口**（100k+ tokens），适合深度研究和多步骤任务 +- **推理能力**，适合自适应规划和复杂拆解 +- **多模态输入**，适合理解图片和视频 +- **稳定的 tool use 能力**，适合可靠的函数调用和结构化输出 + ## 文档 +- [多租户改造汇总索引](docs/multi-tenant-redesign/README.zh-CN.md) - workspace / Postgres / RLS / Headless API 的决策与路线 +- [Stage 0 进度面板](docs/multi-tenant-redesign/03-impl/STATUS.md) - "现在到哪了"的权威来源 +- [数据库设计落地版](docs/multi-tenant-redesign/01-redesign/database-schema-as-built.zh-CN.md) - 10 张表全字段 / 外键 / 索引参考 - [贡献指南](CONTRIBUTING.md) - 开发环境搭建与协作流程 - [配置指南](backend/docs/CONFIGURATION.md) - 安装与配置说明 - [架构概览](backend/CLAUDE.md) - 技术架构说明 - [后端架构](backend/README.md) - 后端架构与 API 参考 +- [apps/ 上层应用](apps/README.md) - 在 DeerFlow 之上构建应用 ## ⚠️ 安全使用 @@ -562,6 +673,9 @@ DeerFlow 具备**系统指令执行、资源操作、业务逻辑调用**等关 - **未授权的非法调用**：agent 功能被未授权的第三方、公网恶意扫描程序探测到，进而发起批量非法调用请求，执行系统命令、文件读写等高危操作，可能导致安全后果。 - **合规与法律风险**：若 agent 被非法调用用于实施网络攻击、信息窃取等违法违规行为，可能产生法律责任与合规风险。 +> [!NOTE] +> 多租户改造引入的 workspace 行级隔离 / 入口强校验 / 边界扫描，目标是**应用内**的租户隔离；它不替代上面的网络层 / 部署层防护。把 DeerFlow 曝光到不可信网络仍需配合下面的安全措施。多租户更强的 DB 层兜底（RLS / KMS / K8s）规划在 Stage 2–3。 + ### 安全使用建议 **注意：建议您将 DeerFlow 部署在本地可信的网络环境下。** 若您有跨设备、跨网络的部署需求，必须加入严格的安全措施。例如，采取如下手段： @@ -575,7 +689,12 @@ DeerFlow 具备**系统指令执行、资源操作、业务逻辑调用**等关 欢迎参与贡献。开发环境、工作流和相关规范见 [CONTRIBUTING.md](CONTRIBUTING.md)。 -目前回归测试已经覆盖 Docker sandbox 模式识别，以及 `backend/tests/` 中 provisioner kubeconfig-path 处理相关测试。 +提 PR 前请先在本地跑通校验（CI 会在每个 PR 上执行 backend lint + 测试，含 Postgres matrix）： + +```bash +cd backend && make lint && make test # ruff + pytest +cd frontend && pnpm lint && pnpm typecheck +``` ## 许可证 @@ -583,22 +702,15 @@ DeerFlow 具备**系统指令执行、资源操作、业务逻辑调用**等关 ## 致谢 -DeerFlow 建立在开源社区大量优秀工作的基础上。所有让 DeerFlow 成为可能的项目和贡献者，我们都心怀感谢。毫不夸张地说，我们是站在巨人的肩膀上继续往前走。 +DeerFlow 建立在开源社区大量优秀工作的基础上。所有让 DeerFlow 成为可能的项目和贡献者，我们都心怀感谢。 特别感谢以下项目带来的关键支持： -- **[LangChain](https://github.com/langchain-ai/langchain)**：它们提供的优秀框架支撑了我们的 LLM 交互与 chains，让整体集成和能力编排顺畅可用。 +- **[LangChain](https://github.com/langchain-ai/langchain)**：它们提供的优秀框架支撑了我们的 LLM 交互与 chains。 - **[LangGraph](https://github.com/langchain-ai/langgraph)**：它们在多 agent 编排上的创新方式，是 DeerFlow 复杂工作流得以成立的重要基础。 -这些项目体现了开源协作真正的力量，我们也很高兴能继续建立在这些基础之上。 - -### 核心贡献者 - -感谢 `DeerFlow` 的核心作者，是他们的判断、投入和持续推进，才让这个项目真正落地： - -- **[Daniel Walnut](https://github.com/hetaoBackend/)** -- **[Henry Li](https://github.com/magiccube/)** - ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.com/#bytedance/deer-flow&Date) + + diff --git a/backend/scripts/verify_stage0.sh b/backend/scripts/verify_stage0.sh index 184c41d7..9848863a 100755 --- a/backend/scripts/verify_stage0.sh +++ b/backend/scripts/verify_stage0.sh @@ -277,19 +277,35 @@ phase_e2e() { local tag tag=$(date +%s) - local alice="alice-${tag}@verify.local" - local bob="bob-${tag}@verify.local" - local pw="VerifyStage0_${tag}" + local alice="alice-${tag}@verify-stage0.com" + local bob="bob-${tag}@verify-stage0.com" + local pw="VerifyStage0_${tag}!" local jar_a=/tmp/verify_alice_${tag}.cookies local jar_b=/tmp/verify_bob_${tag}.cookies rm -f "$jar_a" "$jar_b" + # Ensure system is initialized (admin account exists) before registering users. + info "ensuring admin account exists (POST /api/v1/auth/initialize)" + local init_code + init_code=$(curl -sS -o /dev/null -w '%{http_code}' \ + -H 'Content-Type: application/json' \ + -d "{\"email\":\"admin-${tag}@verify-stage0.com\",\"password\":\"$pw\"}" \ + "$GATEWAY_URL/api/v1/auth/initialize") + if [ "$init_code" = "201" ]; then + ok "admin initialized (first boot)" + elif [ "$init_code" = "409" ]; then + ok "admin already exists (system previously initialized)" + else + fail "admin initialization returned $init_code" + return + fi + register_user() { local jar="$1"; local email="$2" curl -sS -c "$jar" -o /tmp/verify_register_$$.json -w '%{http_code}' \ -H 'Content-Type: application/json' \ -d "{\"email\":\"$email\",\"password\":\"$pw\"}" \ - "$GATEWAY_URL/api/auth/register" + "$GATEWAY_URL/api/v1/auth/register" } info "registering Alice + Bob"