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>
100 lines
5.1 KiB
Markdown
100 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
DeerFlow Frontend is a Next.js 16 web interface for an AI agent system. It communicates with a LangGraph-based backend to provide thread-based AI conversations with streaming responses, artifacts, and a skills/tools system.
|
|
|
|
**Stack**: Next.js 16, React 19, TypeScript 5.8, Tailwind CSS 4, pnpm 10.26.2
|
|
|
|
## Commands
|
|
|
|
| Command | Purpose |
|
|
| ---------------- | ------------------------------------------------- |
|
|
| `pnpm dev` | Dev server with Turbopack (http://localhost:3000) |
|
|
| `pnpm build` | Production build |
|
|
| `pnpm check` | Lint + type check (run before committing) |
|
|
| `pnpm lint` | ESLint only |
|
|
| `pnpm lint:fix` | ESLint with auto-fix |
|
|
| `pnpm test` | Run unit tests with Vitest |
|
|
| `pnpm test:e2e` | Run E2E tests with Playwright (Chromium) |
|
|
| `pnpm typecheck` | TypeScript type check (`tsc --noEmit`) |
|
|
| `pnpm start` | Start production server |
|
|
|
|
Unit tests live under `tests/unit/` and mirror the `src/` layout (e.g., `tests/unit/core/api/stream-mode.test.ts` tests `src/core/api/stream-mode.ts`). Powered by Vitest; import source modules via the `@/` path alias.
|
|
|
|
E2E tests live under `tests/e2e/` and use Playwright with Chromium. They mock all backend APIs via `page.route()` network interception and test real page interactions (navigation, chat input, streaming responses). Config: `playwright.config.ts`.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Frontend (Next.js) ──▶ LangGraph SDK ──▶ LangGraph Backend (lead_agent)
|
|
├── Sub-Agents
|
|
└── Tools & Skills
|
|
```
|
|
|
|
The frontend is a stateful chat application. Users create **threads** (conversations), send messages, and receive streamed AI responses. The backend orchestrates agents that can produce **artifacts** (files/code) and **todos**.
|
|
|
|
### Source Layout (`src/`)
|
|
|
|
- **`app/`** — Next.js App Router. Routes: `/` (landing), `/workspace/chats/[thread_id]` (chat).
|
|
- **`components/`** — React components split into:
|
|
- `ui/` — Shadcn UI primitives (auto-generated, ESLint-ignored)
|
|
- `ai-elements/` — Vercel AI SDK elements (auto-generated, ESLint-ignored)
|
|
- `workspace/` — Chat page components (messages, artifacts, settings)
|
|
- `landing/` — Landing page sections
|
|
- **`core/`** — Business logic, the heart of the app:
|
|
- `threads/` — Thread creation, streaming, state management (hooks + types)
|
|
- `api/` — LangGraph client singleton
|
|
- `artifacts/` — Artifact loading and caching
|
|
- `channels/` — IM channel connections (provider catalog, connect/runtime-config API + hooks)
|
|
- `i18n/` — Internationalization (en-US, zh-CN)
|
|
- `settings/` — User preferences in localStorage
|
|
- `memory/` — Persistent user memory system
|
|
- `skills/` — Skills installation and management
|
|
- `messages/` — Message processing and transformation
|
|
- `mcp/` — Model Context Protocol integration
|
|
- `models/` — TypeScript types and data models
|
|
- **`hooks/`** — Shared React hooks
|
|
- **`lib/`** — Utilities (`cn()` from clsx + tailwind-merge)
|
|
- **`server/`** — Server-side code (better-auth, not yet active)
|
|
- **`styles/`** — Global CSS with Tailwind v4 `@import` syntax and CSS variables for theming
|
|
|
|
### Data Flow
|
|
|
|
1. User input → thread hooks (`core/threads/hooks.ts`) → LangGraph SDK streaming
|
|
2. Stream events update thread state (messages, artifacts, todos)
|
|
3. TanStack Query manages server state; localStorage stores user settings
|
|
4. Components subscribe to thread state and render updates
|
|
|
|
### Key Patterns
|
|
|
|
- **Server Components by default**, `"use client"` only for interactive components
|
|
- **Thread hooks** (`useThreadStream`, `useSubmitThread`, `useThreads`) are the primary API interface
|
|
- **LangGraph client** is a singleton obtained via `getAPIClient()` in `core/api/`
|
|
- **Environment validation** uses `@t3-oss/env-nextjs` with Zod schemas (`src/env.js`). Skip with `SKIP_ENV_VALIDATION=1`
|
|
|
|
## Code Style
|
|
|
|
- **Imports**: Enforced ordering (builtin → external → internal → parent → sibling), alphabetized, newlines between groups. Use inline type imports: `import { type Foo }`.
|
|
- **Unused variables**: Prefix with `_`.
|
|
- **Class names**: Use `cn()` from `@/lib/utils` for conditional Tailwind classes.
|
|
- **Path alias**: `@/*` maps to `src/*`.
|
|
- **Components**: `ui/` and `ai-elements/` are generated from registries (Shadcn, MagicUI, React Bits, Vercel AI SDK) — don't manually edit these.
|
|
|
|
## Environment
|
|
|
|
Backend API URLs are optional; an nginx proxy is used by default:
|
|
|
|
```
|
|
NEXT_PUBLIC_BACKEND_BASE_URL=http://localhost:8001
|
|
NEXT_PUBLIC_LANGGRAPH_BASE_URL=http://localhost:8001/api
|
|
```
|
|
|
|
Leave these unset for the standard `make dev` / Docker flow, where nginx serves
|
|
the public `/api/langgraph/*` prefix and rewrites it to Gateway's native `/api/*`
|
|
routes.
|
|
|
|
Requires Node.js 22+ and pnpm 10.26.2+.
|