mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-06-13 10:55:59 +00:00
DanielWalnut
aa015462a7
* Add user-owned IM channel connections * Fix dev startup and channel connect popup * Use async channel connect flow * Harden dev service daemon startup * Support local IM channel connections * Align IM connections with local channels * Fix safe user id digest algorithm * Address Copilot IM channel feedback * Address IM channel review comments * Support all integrated IM channel connections * Format additional channel connection tests * Keep unavailable channel connect buttons clickable * Fix IM channel provider icons * Add runtime setup for enabled IM channels * Guard global shortcut key handling * Keep configured IM channels editable * Avoid password autofill for channel secrets * Make channel threads visible to connection owners * Persist IM runtime config locally * Allow disconnecting runtime IM channels * Route no-auth channel sessions to local user * Use default user for auth-disabled local mode * Show IM channel source on threads * Prefill IM channel runtime config * Reflect IM channel runtime health * Ignore Feishu message read events * Ignore Feishu non-content message events * Let setup wizard enable IM channels * Fix frontend formatting after merge * Stabilize backend tests without local config * Isolate channel runtime config tests * Address channel connection review comments * Use sha256 user buckets with legacy migration * Ensure runtime IM channels are ready after restart * Persist disconnected IM channel state * Address channel connection review comments * Address channel connection review findings Frontend connect flow: - Open the runtime-config dialog only when a provider still needs credentials; configured providers go straight to the connect flow, so the binding-code/deep-link path is reachable from the UI again. - After saving credentials, continue into the connect flow when a user binding is still required (multi-user mode) instead of stopping at a "Connected" toast. - Extract shared provider-state helpers to core/channels/provider-state and add unit + e2e coverage for the direct-connect and configure-then-connect paths. Provider status semantics: - Report connection_status from the user's newest connection row; with no binding it is not_connected, except in auth-disabled local mode where a configured running channel is effectively connected. Concurrency and event-loop correctness: - Offload ChannelRuntimeConfigStore construction and writes, channel service construction, and Slack connection replies to threads; add a tests/blocking_io/ anchor for the runtime-config handlers. - Consume binding codes with a conditional UPDATE so a code can only be used once under concurrent workers; retry upsert_connection as an update when a concurrent insert wins the unique constraint. - Serialize ensure_channel_ready per channel so concurrent provider polls cannot double-start a channel worker. Config and migration hardening: - Stop mutating the get_app_config()-cached Telegram provider config; the runtime store now owns the UI-entered bot username. - Register channel_connections in STARTUP_ONLY_FIELDS with the standardized startup-only Field description. - Match the legacy unsafe-id bucket by recomputing its exact SHA-1 name so another user's same-prefix bucket can never be migrated. - Remove the unused Telegram process_webhook_update path and document src/core/channels in the frontend docs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Address PR review comments on authz scoping and channel runtime Security (review feedback from ShenAC-SAC): - Scope internal-token callers to the connection owner carried in X-DeerFlow-Owner-User-Id instead of bypassing owner checks outright, in both require_permission(owner_check=True) and the stateless run endpoints. Internal callers keep access to their own and shared/legacy threads, and may claim a default-owned channel thread for its real owner, but a leaked internal token no longer grants cross-user thread access. - Require admin privileges for POST/DELETE /api/channels/{provider}/ runtime-config: runtime credentials and channel workers are instance-wide shared state (same model as the MCP config API). Read-only provider listing stays available to all users. Performance (review feedback from willem-bd): - Skip the redundant thread channel-metadata PATCH after the first successful backfill per thread. - Reuse the per-connection Slack WebClient until its token changes instead of constructing one per outbound message. - Reconcile channel readiness for all providers concurrently in GET /api/channels/providers. Also resolve the code-quality unused-import flag in the blocking-io anchor by pre-importing the channel service via importlib. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Fix prettier formatting in provider-state test Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Reconcile UI runtime channel config with config reload on restart Main now reloads a channel's config.yaml entry on restart_channel() (#3514, issue #3497). Adapt the user-owned connection flow to coexist: - configure_channel() restarts with reload_config=False — the caller just supplied the authoritative config (browser-entered credentials that are never written to config.yaml), so a file reload must not clobber it with the stale on-disk entry. - _load_channel_config() re-applies the UI runtime-store overlay used at startup, so an operator-triggered restart keeps browser-entered credentials for channels without a config.yaml entry and does not resurrect a channel disconnected from the UI. - Offload the reload's disk IO (config.yaml + runtime store) with asyncio.to_thread, matching the blocking-IO policy on this branch. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
110 lines
6.1 KiB
Markdown
110 lines
6.1 KiB
Markdown
# Agents Architecture
|
|
|
|
## Overview
|
|
|
|
DeerFlow is built on a sophisticated agent-based architecture using the [LangGraph SDK](https://github.com/langchain-ai/langgraph) to enable intelligent, stateful AI interactions. This document outlines the agent system architecture, patterns, and best practices for working with agents in the frontend application.
|
|
|
|
## Architecture Overview
|
|
|
|
### Core Components
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Frontend (Next.js) │
|
|
├────────────────────────────────────────────────────────┤
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
|
|
│ │ UI Components│───▶│ Thread Hooks │───▶│ LangGraph│ │
|
|
│ │ │ │ │ │ SDK │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────┘ │
|
|
│ │ │ │ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌──────────────┐ │ │
|
|
│ └───────────▶│ Thread State │◀──────────┘ │
|
|
│ │ Management │ │
|
|
│ └──────────────┘ │
|
|
└────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ LangGraph Backend (lead_agent) │
|
|
│ ┌────────────┐ ┌──────────┐ ┌───────────────────┐ │
|
|
│ │Main Agent │─▶│Sub-Agents│─▶│ Tools & Skills │ │
|
|
│ └────────────┘ └──────────┘ └───────────────────┘ │
|
|
└────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
tests/
|
|
├── e2e/ # E2E tests (Playwright, Chromium, mocked backend)
|
|
└── unit/ # Unit tests (mirrors src/ layout, powered by Vitest)
|
|
src/
|
|
├── app/ # Next.js App Router pages
|
|
│ ├── api/ # API routes
|
|
│ ├── workspace/ # Main workspace pages
|
|
│ └── mock/ # Mock/demo pages
|
|
├── components/ # React components
|
|
│ ├── ui/ # Reusable UI components
|
|
│ ├── workspace/ # Workspace-specific components
|
|
│ ├── landing/ # Landing page components
|
|
│ └── ai-elements/ # AI-related UI elements
|
|
├── core/ # Core business logic
|
|
│ ├── api/ # API client & data fetching
|
|
│ ├── artifacts/ # Artifact management
|
|
│ ├── channels/ # IM channel connections (providers, connect flow)
|
|
│ ├── config/ # App configuration
|
|
│ ├── i18n/ # Internationalization
|
|
│ ├── mcp/ # MCP integration
|
|
│ ├── messages/ # Message handling
|
|
│ ├── models/ # Data models & types
|
|
│ ├── settings/ # User settings
|
|
│ ├── skills/ # Skills system
|
|
│ ├── threads/ # Thread management
|
|
│ ├── todos/ # Todo system
|
|
│ └── utils/ # Utility functions
|
|
├── hooks/ # Custom React hooks
|
|
├── lib/ # Shared libraries & utilities
|
|
├── server/ # Server-side code (Not available yet)
|
|
│ └── better-auth/ # Authentication setup (Not available yet)
|
|
└── styles/ # Global styles
|
|
```
|
|
|
|
### Technology Stack
|
|
|
|
- **LangGraph SDK** (`@langchain/langgraph-sdk@1.5.3`) - Agent orchestration and streaming
|
|
- **LangChain Core** (`@langchain/core@1.1.15`) - Fundamental AI building blocks
|
|
- **TanStack Query** (`@tanstack/react-query@5.90.17`) - Server state management
|
|
- **React Hooks** - Thread lifecycle and state management
|
|
- **Shadcn UI** - UI components
|
|
- **MagicUI** - Magic UI components
|
|
- **React Bits** - React bits components
|
|
|
|
### Interaction Ownership
|
|
|
|
- `src/app/workspace/chats/[thread_id]/page.tsx` owns composer busy-state wiring.
|
|
- `src/core/threads/hooks.ts` owns pre-submit upload state and thread submission.
|
|
- `src/hooks/usePoseStream.ts` is a passive store selector; global WebSocket lifecycle stays in `App.tsx`.
|
|
|
|
## Resources
|
|
|
|
- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
|
|
- [LangChain Core Concepts](https://js.langchain.com/docs/concepts)
|
|
- [TanStack Query Documentation](https://tanstack.com/query/latest)
|
|
- [Next.js App Router](https://nextjs.org/docs/app)
|
|
|
|
## Contributing
|
|
|
|
When adding new agent features:
|
|
|
|
1. Follow the established project structure
|
|
2. Add comprehensive TypeScript types
|
|
3. Implement proper error handling
|
|
4. Write unit tests under `tests/unit/` (run with `pnpm test`) and E2E tests under `tests/e2e/` (run with `pnpm test:e2e`)
|
|
5. Update this documentation
|
|
6. Follow the code style guide (ESLint + Prettier)
|
|
|
|
## License
|
|
|
|
This agent architecture is part of the DeerFlow project.
|