35cdcab1c5
* feat(scheduler): lifecycle rules, goal/limit parity and coded errors for scheduled tasks
- Migration 0031: nullable scheduled_tasks.unmet_streak_after_seq (internal
streak boundary) and stop_condition (the user's stop rule, own column).
- Stop rule is normalized (stop_rule.py) and appended only at launch; the
stored prompt never contains it. Wording adapts when scheduler.tool_enabled
is off.
- Willem 1: page-created tasks get goal evaluation, <standing_notes>, the
previous-run reference and own-schedule stop; request_stop and the
scheduled capability no longer require an origin conversation.
- Repository: single reactivation choke point raising
ScheduledTaskLimitsExhausted; streak boundary moves on goal/prompt/stop
condition/note changes (not on resume); goal-check failures neither count
nor reset the streak; pause of a finished task returns "finished"; trials
on a paused task keep the host pause marker.
- New repository reads: automatic_runs_used_for, active_run_status_for,
list_manageable_from_thread, thread_relation/thread_run on thread tasks,
task_ids_for_thread, run_number, and run_number/total_tokens/summary on
run history rows.
- REST: goal/max_runs/end_at/stop_condition on create and PATCH (null
clears, naive end_at = task timezone), resume recomputes from now with an
optional renewal body, once_time_passed, task_finished, limits_exhausted,
scheduler_not_running on create, trigger returns outcome/existing/thread_id,
task responses add automatic_runs_used and active_run_status.
- Coded errors {code, message, params} for routes, shared validation and the
chat capability (scheduled_task_errors.py), pinned by
contracts/scheduled_task_errors_contract.json; goal notes contract v2 with
check_failure_codes, scheduled_origin_key and host_run_errors (host_notes.py).
- /api/features adds scheduled_tasks {available, running, tool_enabled,
min_interval_seconds}; ScheduledTaskService.is_running.
- Docs: six README scheduler sections, API.md scheduled tasks section
(breaking error shape), CONFIGURATION.md, AGENTS notes, CHANGELOGs.
- Tests: migration 0031, stop rule, error contract, run listing, lifecycle
over HTTP, repository, service and capability cases; updated tests for the
new error shape, finished-task pause and head revision.
* feat(scheduler): conversation update/resume, run-conversation authority and readable launches
- schedule_task: update and resume actions, stop_condition and clear_fields
parameters, plain parameter types (value rules come back as coded results),
rewritten docstrings for schedule_task and stop_scheduled_task.
- Capability: update/resume share the REST validation and error codes;
interactive turns in a task's run conversation may manage that task;
scheduled runs keep only own-stop; grants require a running scheduler.
- Results: compact JSON-safe task views with local times, display card/text,
last run in list, timezone_source/browser_timezone, now_local; no ISO, user,
lease or origin fields; stop_instructions removed.
- Timezone: explicit > browser (context.client_timezone, validated in
start_run and never forwarded to the run config) > not needed for intervals
and offset run_at > timezone_required.
- Trial gate accepts natural direct requests after acknowledgements and
particles; trial results report thread_id and existing.
- Scheduled launches: stable message id scheduled-<task_run_id>, server-owned
deerflow_scheduled_origin metadata with the user-language parts, run thread
title for fresh-thread tasks.
- Worker records goal continuations in the verdict; lead prompt language rule
covers stored task text and scheduled runs.
- Docs: six READMEs, CONFIGURATION, API, runtime/tools AGENTS, CHANGELOGs.
* feat(frontend): scheduled-task core types, formatting, errors and glossary
- throwGatewayApiError now throws GatewayApiError (status, code, params,
rawMessage); message stays the string detail or detail.message
- scheduled-task types gain stop_condition, automatic_runs_used,
active_run_status, origin/notes, run_number/total_tokens/summary, thread
relation, trigger result, renewal and scheduled origin; isTaskBusy and
hasActiveRun helpers
- api: fetchScheduledTask, resume with optional renewal body, typed trigger
result and update payload with null clears
- hooks: polling at 3 s while a run is active (list, thread list, run
history), useScheduledTask with live gating and final 404, useInView,
localized error toasts; run history refreshes tasks when a run finishes
- new pure modules: errors.ts (contract code to localized copy), format.ts
(relative task times, viewer time, display zone), status.ts, actions.ts,
run-error.ts; describeTaskSchedule in cron.ts; goal-outcome adds unchecked
goal checks, describeTaskOutcome and parseStopRunId
- features: scheduled_tasks block with defaults when missing
- buildRunContext sends client_timezone
- titleOfThread takes a localized untitled label; breadcrumb names scheduled
tasks and agents; reference chips use the localized untitled label
- schedule input: shared browserTimeZone, labelled selects, aria-pressed
type toggles, interval minimum from the hint template
- i18n: all PR1 scheduled-task keys in en-US and zh-CN, glossary fixes,
recipe instructions moved into i18n
- e2e mocks follow the new task, trigger, resume, thread-task and features
shapes; expectNoRawIdentifiers helpers for e2e and DOM tests
- tests for errors, format, cron, status, actions, goal outcome, run errors,
hooks, run context, thread titles and features; scheduled e2e copy updated
* feat(frontend): list-first scheduled tasks page with outcomes and editable goals
- page.tsx is now a thin composition of components/workspace/scheduled-tasks:
status tabs (All/Active/Paused/Finished) and search over the task list,
?task_id= deep link with router.replace on selection, ?thread_id= chip
with Show all, empty state, scheduler-off notice and unavailable state
- task list rows show the schedule in words and one status line (next run,
running now, paused by agent, auto-paused, finished by its cap)
- task detail: status badge, actions from availableActions with reasons,
More actions menu (Duplicate, Copy task ID, Delete), outcome notice,
Runs / Stops when / Each run's goal / Does / Notes from chat / History,
origin chat link; success toasts for every action
- run rows: run number or Trial run, summary, goal and assumption badges,
continuations, tokens, Open chat link; raw errors and the evaluator
reason only behind Details
- create/edit/duplicate dialog with goal, stop condition, safety caps and
advanced agent/context options; PATCH sends only changed fields, null
clears a cap
- renew dialog raises or removes caps and resumes in one request; a
limits_exhausted Resume opens it
- removed i18n keys the old page used; added feedback.resumedNoTime
- recorded en-3 and zh-1 page fixtures; scheduled e2e specs rewritten for
the new page; DOM tests for the detail and the form dialog
- CHANGELOG entries and the frontend AGENTS.md scheduled-task note
* feat(frontend): live schedule card, run conversation provenance and header entry
- schedule_task results (create, update, pause, resume, trial, delete) become
an assistant:scheduled-task message group rendered as a live card: schedule,
next run, stop condition with the safety cap, goal, where results go, Run
once now, Pause/Resume and Open task; the card polls the task only while it
is on screen and shows deleted, scheduler-off and limits-exhausted states
- one card per task per assistant turn; the card group is not a turn boundary
for usage, branching, editing, outline or skill attribution
- a human message with deerflow_scheduled_origin stays a human group with
scheduledOrigin and renders as a "Scheduled run / Trial run" block with the
task instructions, stop condition and notes collapsed; the launched text is
never shown and the message is not editable
- readable step labels for schedule_task actions and stop_scheduled_task
- ThreadScheduledTasksButton replaces the header link: hidden without tasks,
shows the count, links to the task (or the chat filter), and a run's chat
links to its task
- recorded en-3 / zh-1 chat and run-thread fixtures; chat-card and run-thread
e2e specs; unit and DOM tests for parsing, grouping, turn boundaries, card,
run block, header button, step labels and reconnect hydration
- i18n: header.countLabelOne added, unused card.next removed; CHANGELOG and
frontend AGENTS.md notes
* fix(scheduler): address verification findings
Move the scheduled-task lifecycle guidance from backend/AGENTS.md into the persistence guide and leave a one-line pointer, so the effective AGENTS.md chains for agents/middlewares, sandbox and subagents stay under the 98304-byte hard limit enforced by scripts/check_agent_guidance.py in lint-check.
* fix(scheduler): address review findings
* fix(gateway): no-transform on SSE responses
All four text/event-stream responses (thread run create stream, join,
existing-run GET/POST stream, stateless create stream) now take their
headers from app/gateway/sse_headers.py and send
Cache-Control: no-cache, no-transform, so compressing proxies such as
Next's rewrite proxy stop buffering streams. Content-Location and
X-Accel-Buffering are unchanged; scheduled and MCP-notification runs keep
stream_mode=None.
Tests pin the headers on every SSE route and fail on a literal no-cache
header left in routers. Docs: API.md SSE headers note, CHANGELOGs.
* feat(scheduler): per-owner run cap and fair queue selection
New scheduler.max_concurrent_runs_per_user (default 2, 0 = off, effective
min(cap, max_concurrent_runs)) caps launching/running scheduled runs per task
owner. claim_queued_run checks it right after the global count under the same
budget lock, so it is atomic across workers and Pods. list_queued_runs ranks
same-thread FIFO heads per owner with ROW_NUMBER() OVER (PARTITION BY owner)
and orders the batch by that rank, so the drain is owner-fair even with the
cap off; owners at their cap drop out before the batch limit. Orphan rows
(task deleted while queued) are never held back by the cap.
Gateway lifespan passes the startup value; the service constructor default
stays 0. Docs: config.example.yaml (config_version 54), CONFIGURATION.md,
the six READMEs, backend AGENTS.md, CHANGELOGs (behavior change flagged).
The live-task quota is untouched.
* feat(scheduler): durable lifecycle events for the originating chat
When a chat-created schedule is paused by the agent, auto-paused or finishes,
finalization now reports task_stopped / task_paused / task_finished, only on a
live -> paused/finished transition. The new finish_task_at_end_condition
replaces the three inline "mark completed" blocks (admission rejected as ended,
claim-time skip, complete_if_ended), so every site emits exactly once.
The scheduler's finalization observer is always installed. It writes
scheduled_task_events rows for the originating chat in the same transaction as
the state change, deduplicated on (task_id, anchor, event), with a title
snapshot, stop condition, run number, last run outcome and the chat's newest
run as placement anchor. Lookups fall back on bad stored data; only database
errors propagate. Manual trials drop only run_* events. The IM step keeps
PR1's selection until B4.
New GET /api/threads/{thread_id}/scheduled-task-events (owner check, caller's
rows, oldest first); rows survive task deletion and go with the chat.
Migration 0032_activity_and_task_events adds the events table plus the
run-origin column/index and read-state tables used later, each object guarded
on its own. Contract scheduled_goal_notes v3 pins the lifecycle vocabulary.
Docs: API.md, migrations chain, backend AGENTS.md, six READMEs, CHANGELOGs.
* feat(scheduler): honest, localized and self-contained IM notices
Every scheduled-task IM notice is now enqueued by the finalization observer
in the transaction that records the outcome, one message per occurrence
(task_stopped > task_paused > task_finished > run_failed > run_unmet >
run_completed; a once task sends only its run event). The merged auto-pause
replaces the separate unmet + pause messages, agent stops and finishes now
notify, and recovery-finalized runs notify exactly once. Idle finishes use a
deterministic idle: key derived from the lifecycle anchor. The old
non-transactional enqueue in handle_run_completion is removed.
New app/channels/capabilities.py holds CHANNEL_CAPABILITIES with a
proactive_notifications flag (adds the missing qq entry); only push-capable
providers (WeCom) get rows, /api/channels/providers returns the flag, and the
worker ends legacy rows for other providers as terminal failed.
New app/scheduler/notification_text.py renders en-US/zh-CN text: title, what
happened (plus the last run's outcome), the tasks page's one-line run summary
(redacted) when the agent replied, and a closing line. No IDs, no links, no
public_base_url. Locale is the owner's new `locale` preference, else the new
channel_connections.notification_locale (default en-US).
Docs: config.example.yaml (config_version 55), CONFIGURATION.md, API.md,
channels AGENTS.md, six READMEs, CHANGELOGs (behavior change flagged).
* feat(gateway): thread origin, activity feed and read markers for server-created threads
Runs started by the server for a user (scheduler, IM channels, GitHub
agents, extension handles, MCP notifications) now carry a server-owned
metadata.deerflow_origin {kind, provider?, namespace?} (new harness module
deerflow.runtime.run_origin, pinned by contracts/thread_origin_contract.json).
It is stamped only from request.state.run_origin or by the internal channel
caller; run admission drops client copies from both metadata and
config.metadata, and thread create/patch strip it. RunRepository derives
runs.origin_kind on put and on create_thread_operation_atomic (agent runs
only), and gains latest_change().
New ThreadReadRepository keeps a per-user, never-decreasing read position
(thread_read_markers) and a per-user read clock (thread_read_versions).
POST /api/threads/{id}/read marks a thread read, thread search items carry
unread, and thread delete removes the markers. GET /api/thread-activity pages
the caller's run changes over the run-change clock, returns only threads
changed by server-originated runs plus read_version, and 503s without SQL;
/api/features reports thread_activity.available.
Docs: API.md, gateway AGENTS.md (condensed to stay under its budget),
CHANGELOGs.
* fix(scheduler): adapt PR2 to PR1 follow-ups
PR1 moved the scheduled-task lifecycle rules out of backend/AGENTS.md into
the persistence guide and grew the sandbox AGENTS.md chain to within 267
bytes of its hard limit. The per-owner queue-fairness detail now lives in
the persistence guide next to the lifecycle rules (backend/AGENTS.md keeps
the cap and a link), so check_agent_guidance passes again.
PR1's goal-outcome unit test pinned scheduled_goal_notes_contract version 2;
PR2 bumps it to 3 (lifecycle vocabulary only, the v2 keys are unchanged).
* fix(scheduled-tasks): polish from live acceptance
- zh schedule wording: an interval of one unit reads 每分钟 / 每小时 / 每秒,
and a saved interval of whole days reads 每天 / 每 2 天 (Every day / Every 2
days) instead of 每 1 分钟 or 每 24 小时; several units keep the number
- zh spacing: 已于{time} 满足 and 在{time} 的运行中 now leave a space between
the interpolated time and the Chinese after it; a copy test guards every
scheduled-task zh string against a placeholder glued to Chinese
- run summary: when the first line of the final reply only leads in to a list
(ends with ":" or "："), the list items follow it as plain text (bullets,
numbering, checkboxes, bold, code and links stripped), joined with "；" for
CJK text and "; " otherwise, within the 160-character cap
- a schedule_task result (create, update, pause, resume, trial, delete) that
arrives in a chat invalidates that chat's task list, the tasks list and the
named task, so the header button and cards update without waiting for the
idle poll; results already in the loaded history do not refetch
- e2e and unit fixtures are now the live acceptance recordings (DeepSeek
Flash, demo data, fictional names): live-weekday.json (create, trial, edit,
pause, resume in one zh chat) and live-minute.json (per-minute chat, run 1
and run 2, paused by the agent), fetched with GET from the demo Gateway and
trimmed; the hand-shaped en-3 / zh-1 fixtures are removed and the chat-card,
run-thread and tasks-page specs run in both locales over the recorded data
* docs(changelog): reference #6378 for the scheduled-tasks entries
* docs(agents): shorten the scheduled-task pointer to stay under the guidance limit
* test(scheduled-tasks): pin the live takes to their recorded time zone
The live fixtures were recorded in Asia/Shanghai, and an interval task
reads in the viewer's zone, so the 16:48 assertions failed on UTC CI
runners. Pin the browser zone in the two live-take e2e specs and the
zh live-take unit test.
* feat(frontend): thread origin, activity polling, read markers and task events core
Frontend core for server-created threads and schedule lifecycle events
(PR2 F1); the sidebar markers (F2) and the chat event line (F3) build on it.
- core/threads/origin.ts: threadOriginOf reads metadata.deerflow_origin,
then channel_source (github -> GitHub origin), then a legacy
scheduled_task_id; key and kinds pinned to
contracts/thread_origin_contract.json. labelOfThreadOrigin and the now
exported labelOfChannelProvider(provider, t) use the new localized
threads.origin.providers names (飞书, 企业微信, ...), with the English map
(gaining GitHub) only as the fallback.
- core/threads/activity.ts: useThreadActivity polls /api/thread-activity
every 15 s (focus refetch, never in the background, off unless
features.thread_activity.available). The first response only seeds the
cursor; server-origin threads, a truncated page or a higher read_version
invalidate the thread lists, a scheduled thread also ["scheduled-tasks"];
an invalid cursor re-seeds. useMarkThreadRead debounces POST /read by 1 s,
skips a thread whose cached unread is false, patches the search and
infinite caches optimistically and stores the returned read_version so a
tab's own read does not refetch its lists. AgentThread gains unread.
- core/scheduled-tasks/events.ts: ScheduledTaskEvent, the events query
(["scheduled-tasks","thread-events",id], one fetch per saved chat, not
gated on the task list so a deleted task's lines stay, refetched when a
task of the chat changes status or finishes a run), describeTaskEvent
(en/zh copy, title and condition as segments, last-run suffix, See that
run / Open task) and placeTaskEvents (end of the after_run_id turn, else
the tail, ordered by created_at); lifecycle names pinned to contract v3.
- features: thread_activity (default unavailable); channels:
proactive_notifications on providers.
- Locale sync: the I18nProvider reports the UI language and a signed-in
preference session saves it as the new `locale` preference when the
account's differs (and on every switch), so IM notices follow the UI
language; nothing is written with auth disabled.
- i18n: threads.* (unread, origin labels, provider names),
scheduledTasks.events.*, history.waitingForSlot (now shown for queued run
rows), channels.scheduledUpdates.*.
- e2e mocks: thread activity feed and controller, POST /read, the events
route, providers with proactive_notifications, search unread, features
thread_activity (off by default). Preference e2e mocks return the UI
locale so they keep asserting only their own edits.
- Docs: frontend AGENTS.md, CHANGELOGs.
* fix(scheduled-tasks): keep untouched end times and drop a chat filter the new task is not in
- The edit, duplicate and renew dialogs keep a stored end time's instant
while its field still shows it. A minute-precision wall value cannot
keep seconds or name the later 01:30 of a DST fall-back, so a
title-only edit moved the cap an hour earlier, and raising the run
limit re-sent the end time without its seconds.
- Creating or duplicating a task from a chat's task view drops the chat
filter when the new task does not belong to that chat, instead of
showing "This task isn't one of this chat's tasks".
* feat(frontend): origin markers and unread state in the thread lists
Server-created threads (PR2 F2) now say who created them and whether they
are new, in the sidebar and on the Chats page, and reach an open sidebar
without a reload.
- ThreadOriginIcon (thread-channel-source.tsx): clock for a scheduled run,
the provider mark for IM threads, the GitHub mark (new in
ChannelProviderIcon) for GitHub threads, a puzzle piece for extensions;
the localized "Scheduled run" / "From Feishu" / "From GitHub" / "From an
extension" label is its accessible name and tooltip. ThreadChannelIcon
stays exported as a wrapper, and the provider chip tooltip is localized
(no more "Feishu channel").
- Unread dot after the title (aria-hidden dot plus sr-only "Unread"); the
row aria-label becomes "{title}, unread" / "{title}，未读". Never shown for
the open thread.
- WorkspaceSidebar mounts useThreadActivity once.
- useMarkOpenThreadRead (components/workspace/chats): the default and
custom-agent chat pages mark the thread read once its metadata has
loaded, when its cached unread flips to true while open, when the tab
becomes visible, and from onFinish (a send or a joined run ended). Each
trigger goes through useMarkThreadRead, so it is debounced and a no-op
while the cached unread is false.
- Tests: thread-origin-icon and recent-chat-list DOM tests (en/zh, active
row, no raw identifiers), use-mark-open-thread-read DOM tests,
e2e thread-activity.spec.ts (new scheduled run appears unread within one
fake-clock poll without a reload, opening it posts /read and clears the
dot, a read on another device clears it, IM and GitHub markers, zh
labels, the Chats page, no polling when unavailable);
thread-history.spec.ts now finds the localized origin icon.
- Docs: frontend AGENTS.md, CHANGELOGs.
* feat(frontend): schedule event line in the originating chat and channel notice support
The chat that created a schedule now says when the schedule paused or
ended, and the channel cards say which apps receive scheduled task updates
(PR2 F3).
- ScheduledTaskEventLine (mockup m2, marker 4): a dashed, muted row with
the describeTaskEvent text (title in <strong>, stop condition clamped to
one line with the full text in its tooltip, last-run suffix), the time
via formatTaskTime and a right-aligned "See that run" (run chat) or
"Open task" link. PauseCircle for paused, CircleCheck for finished and
once-done, CircleX for once-failed. role="note", aria-label "Scheduled
task update" / "定时任务通知", data-task-id and data-event-id only.
- MessageList takes scheduledTaskEvents and renders placeTaskEvents output
through a new VirtualMessageList.renderAfterGroup, so each line sits at
the end of its after_run_id turn inside the group's measured row (also
when the list virtualizes); lines with nowhere to go render at the tail.
- Both chat pages load useThreadScheduledTaskEvents (not gated on the task
list, so the lines stay after a task is deleted). The custom-agent page
passes its agent so "See that run" opens the run on that agent's route.
- ChannelScheduledUpdates: "Scheduled task updates: sent here" / "... not
available for this app yet" (定时任务通知：会发送到这里 / 此应用暂不支持)
on the Settings provider cards and under each sidebar channel row; nothing
when an older backend does not report proactive_notifications.
- e2e mock controller: setScheduledTasks.
- Tests: scheduled-task-event-line and channel-scheduled-updates DOM tests
(every kind in en and zh, hrefs, clamp, no raw identifiers, Chinese
title), MessageList placement DOM tests; e2e
scheduled-task-chat-events.spec.ts (the line appears with the card's
"Paused by agent" without a reload, See that run opens the run chat,
anchored vs tail placement, two events in time order, the line survives
task deletion and Open task shows the task is gone; en-3 and zh-1) and
channels.spec.ts (WeCom sent here, Feishu not yet; en and zh).
- Docs: frontend AGENTS.md, CHANGELOGs.
* fix(scheduled-tasks): tie pause notices to the pause they describe
- Paused by agent links and times only the run named in last_error. When
that run is not loaded, the notice shows no link and the task's own time
instead of an earlier run that also asked to stop.
- The outcome notice reads the latest history page whichever page is
shown, so browsing older runs no longer swaps the auto-pause reason and
"Open latest run" to an earlier miss. It shares that page's request.
* fix(scheduler): address PR2 review findings
- Event lines: hold an event whose anchor run is on an unloaded history
page instead of placing it at the bottom (hasMoreHistory); tail fallback
only for fully loaded (branched/pruned) history or no anchor.
- Idle-finish anchor follows its reason: end:<iso> only for an end_at
finish, seq:<n> otherwise, so a later end-time finish is not deduplicated
away by an earlier max_runs finish.
- Observer takes FOR SHARE on the originating threads_meta row, so a racing
thread delete cannot leave an orphan event line.
- One taskPagePath (core), re-exported by the card.
- Notification locales derived from NotificationLocale; /preferences uses it.
- IM notices drop generic reasons (goal_not_met_yet, unknown) instead of
repeating the sentence.
- Localized provider names on Settings cards, sidebar rows and setup dialog.
- zh event lines: no space after a Chinese title (Latin-aware gap).
- Unread row label keeps the origin marker; chats page keeps the time as a
description.
- Sidebar shows the scheduled-updates line only for connected apps;
Settings says "available after you connect" for unconnected push apps.
- Event line keeps a real space before the time.
* fix(scheduled-tasks): three lifecycle gaps found while re-checking review classes
- The edit form compares a cron in the form its schedule input emits, so an
untouched "0 09 * * 0,6" is not re-sent as "0 9 * * 6,0" and a title-only
edit no longer re-arms or refuses a finished task.
- Chat resume asks for a timezone, as update does, when a naive end_at would
land in the UTC placeholder of a zone-free task.
- Re-arming a task clears a host pause marker, as resume does, so a later
manual pause no longer reads as "Paused by agent".
* test(scheduler): consolidate PR2 backend test setup
- Fold the repeated task, origin-chat and observer setup of the
lifecycle-event repository tests into one lifecycle_task builder.
- Build the per-owner-cap services through one _capped_service builder
that keeps every cap explicit at the call site.
- Table the five SSE route header checks into one parametrized test with
the same routes, bodies and Content-Location expectations.
- Reuse bind_wecom and hoist repeated local imports in the event tests.
Every case and assertion is kept; collected cases are unchanged.
* test(frontend): consolidate PR2 thread activity and origin test setup
Extract shared builders and helpers in the frontend tests PR2 adds, with
every case, input and assertion kept:
- activity.test.ts: seededClient/apply helpers and one LIST_KEYS constant
replace the per-test seed, spy and apply boilerplate.
- mark-read.dom.test.tsx: newClient() and advance() replace the repeated
QueryClient wrapper and fake-timer act blocks.
- origin.test.ts: the English and Chinese label checks become tables; the
no-English-name check now runs on every Chinese row.
- thread-activity.spec.ts: a scheduledRun() builder replaces four inline
copies of the scheduled run thread.
- channels.spec.ts: the PR2 block uses setLocaleCookie and one card helper.
Collected cases are unchanged (unit 211, e2e 60); no test was removed.
* fix(scheduled-tasks): keep the notice's latest-runs query from refreshing older pages
useLatestScheduledTaskRuns kept React Query's default refetch on mount,
focus and reconnect, so going offline and back while an older history page
was shown fetched the latest page again. Refreshing stays with the history,
which refreshes the latest page only while it is shown.
* fix(scheduler): two gaps found in live acceptance
- A fresh scheduled run thread is named when it launches. The worker
copied the title to the thread list only when the run ended, so the
sidebar, which now shows the new run thread at once, listed it as
untitled while it ran.
- A task capped at one run finishes with "its one run is done" /
"唯一一次运行已完成" in the chat event line and the IM notice, instead
of "all 1 runs are done".
* test(scheduled-tasks): let the viewer's time carry its own day label
Between 16:00 and 24:00 UTC, UTC and Asia/Shanghai are on different days,
so the run prompt shows "Tomorrow 01:00 · Today 09:00 your time" and the
fixed "01:00 · 09:00 your time" assertion failed depending on the hour.
* test(scheduler): expect the one-run finish copy in service notices
* fix(gateway): create a scheduled run thread with its title
Pre-setting the name after start_run raced the thread row, which the run
worker creates asynchronously: live, one of two run threads still reached
the sidebar untitled. Run admission now creates a new thread with the title
its run input carries, which the worker would copy only at run end.
* docs(changelog): reference #6393 for the scheduled-task signal entries
* fix(scheduled-tasks): route event-line run links by the agent that ran them
The originating chat's agent was used for "See that run", but a task's
agent can change after the chat created it, so the link could open the run
chat on another agent's route. Lifecycle events now record run_agent_name,
the task's agent when the run finished (edits are refused while a run is
active), and the line routes by it.
* fix(scheduled-tasks): load up to the route's maximum of chat event lines
The chat loads its lifecycle events once, and the route's default of 50
would silently drop the oldest lines of a chat with many schedules. Ask
for the maximum, 200.
* fix(threads): keep activity reads and the first cursor in step with the lists
- Accepting the first activity cursor refreshes the thread lists once. The
lists load on their own, possibly before a run the seed already counts,
and later polls start after it, so such a thread never appeared.
- A local read whose returned read clock jumps past that one read also
covers reads on other devices; the lists are refreshed instead of the
clock silently skipping those threads' stale unread dots.
- An invalid cursor re-seeds through the same path, so it refreshes once.
* docs(agents): bring the middlewares guidance chain back under the hard limit
#6378 and #6363 each fit the budget, but together the middlewares AGENTS.md
chain on main is 98,425 bytes, 121 over the 98,304 hard limit, so Lint
Check fails on main. Move the scheduled-task recovery, launch-update and
queue-timeout rules from backend/AGENTS.md into the persistence guide's
lifecycle section, which backend/AGENTS.md already points to. The chain is
now 98,067 bytes.
* fix(helm): bump the chart's config_version to 55
config.example.yaml moved to 55 in this PR, so the Helm chart's
validate-chart drift check failed. The chart's embedded config needs no
field changes: the new scheduler and channel keys have defaults.
---------
Co-authored-by: Totoro-qaq <279883115+Totoro-qaq@users.noreply.github.com>
Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
72 KiB
🦌 DeerFlow - 2.0
English | 中文 | 日本語 | Français | Русский | Português
28 февраля 2026 года DeerFlow занял 🏆 #1 в GitHub Trending после релиза версии 2. Спасибо огромное нашему сообществу — всё благодаря вам! 💪🔥
DeerFlow (Deep Exploration and Efficient Research Flow) — open-source Super Agent Harness, который управляет Sub-Agents, Memory и Sandbox для решения почти любой задачи. Всё на основе расширяемых Skills.
https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
Note
DeerFlow 2.0 — проект переписан с нуля. Общего кода с v1 нет. Если нужен оригинальный Deep Research фреймворк — он живёт в ветке
1.x, туда тоже принимают контрибьюты. Активная разработка идёт в 2.0.
Официальный сайт
Больше информации и живые демо на официальном сайте.
Родственные проекты
- LLM Space - Познакомьтесь с нашим секретным оружием за DeerFlow — настольный инструмент для прототипирования идей агентов, проверки каждого шага харнесса, воспроизведения сбоев и тестирования производительности.
Coding Plan от ByteDance Volcengine
- Рекомендуем Doubao-Seed-2.0-Code, DeepSeek v3.2 и Kimi 2.5 для запуска DeerFlow
- Подробнее
- Для разработчиков из материкового Китая
InfoQuest
DeerFlow интегрирован с инструментарием для умного поиска и краулинга от BytePlus — InfoQuest (есть бесплатный онлайн-доступ)
Содержание
- 🦌 DeerFlow - 2.0
- Официальный сайт
- Coding Plan от ByteDance Volcengine
- InfoQuest
- Содержание
- Установка одной фразой для coding agent
- Быстрый старт
- От Deep Research к Super Agent Harness
- Core Features
- Рекомендуемые модели
- Встроенный Python-клиент
- Проекты
- Запланированные задачи (Scheduled Tasks)
- Терминальная панель (TUI)
- Документация
- ⚠️ Безопасность
- Участие в разработке
- Лицензия
- Благодарности
- История звёзд
Установка одной фразой для coding agent
Если вы используете Claude Code, Codex, Cursor, Windsurf или другой coding agent, просто отправьте ему эту фразу:
Если DeerFlow еще не клонирован, сначала клонируй его, а затем подготовь локальное окружение разработки по инструкции https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md
Этот prompt предназначен для coding agent. Он просит агента при необходимости сначала клонировать репозиторий, предпочесть Docker, если он доступен, и в конце вернуть точную команду запуска и список недостающих настроек.
Быстрый старт
Конфигурация
-
Склонировать репозиторий DeerFlow
git clone https://github.com/bytedance/deer-flow.git cd deer-flow -
Запустить мастер настройки (рекомендуется)
Из корня проекта (
deer-flow/) запустите:make setupЗапустится интерактивный мастер, который поможет выбрать LLM-провайдера, опциональный веб-поиск и настройки выполнения/безопасности (режим sandbox, доступ к bash, инструменты записи файлов). Он сгенерирует минимальный
config.yamlи запишет ключи в.env. Это занимает около 2 минут.В любой момент запускайте
make doctor, чтобы проверить конфигурацию и получить конкретные подсказки по исправлению. Если вы открываете GitHub issue о проблеме с локальной установкой или работой системы, выполнитеmake support-bundle. Команда выводит дальнейшие шаги для автора отчёта, создаёт файл*-issue-summary.md, который нужно вставить в issue, файл*-issue-draft.mdдля оформления issue с помощью AI и, опционально, zip-архив с диагностикой в.deer-flow/support-bundles/. Если issue оформляет AI-ассистент, он должен начать с черновика и заменить каждый плейсхолдер REQUIRED, а не выдумывать недостающие факты. Прикладывайте zip-архив только если его запросит мейнтейнер или если одной сводки недостаточно. Мейнтейнеры и AI-инструменты триажа могут начинать сtriage.json; архив содержит только очищенную от чувствительных данных диагностику и манифесты файлов и не включает.env, исходные сообщения диалогов или содержимое пользовательских файлов.Продвинутая / ручная настройка: если вы предпочитаете редактировать
config.yamlнапрямую, выполните вместо этогоmake config, чтобы скопировать полный шаблон. Полный справочник —config.example.yaml, включая CLI-провайдеров (Codex CLI, Claude Code OAuth), OpenRouter, Responses API и многое другое.Примеры ручной настройки моделей
models: - name: gpt-4o display_name: GPT-4o use: langchain_openai:ChatOpenAI model: gpt-4o api_key: $OPENAI_API_KEY - name: openrouter-gemini-2.5-flash display_name: Gemini 2.5 Flash (OpenRouter) use: langchain_openai:ChatOpenAI model: google/gemini-2.5-flash-preview api_key: $OPENROUTER_API_KEY base_url: https://openrouter.ai/api/v1 - name: gpt-5-responses display_name: GPT-5 (Responses API) use: langchain_openai:ChatOpenAI model: gpt-5 api_key: $OPENAI_API_KEY use_responses_api: true output_version: responses/v1 - name: qwen3-32b-vllm display_name: Qwen3 32B (vLLM) use: deerflow.models.vllm_provider:VllmChatModel model: Qwen/Qwen3-32B api_key: $VLLM_API_KEY base_url: http://localhost:8000/v1 supports_thinking: true when_thinking_enabled: extra_body: chat_template_kwargs: enable_thinking: trueOpenRouter и аналогичные OpenAI-совместимые шлюзы настраиваются через
langchain_openai:ChatOpenAIс параметромbase_url. Если вы предпочитаете имя переменной окружения, специфичное для провайдера, укажите его вapi_keyявно (например,api_key: $OPENROUTER_API_KEY).Чтобы направить модели OpenAI через
/v1/responses, продолжайте использоватьlangchain_openai:ChatOpenAIи задайтеuse_responses_api: trueвместе сoutput_version: responses/v1.Для vLLM 0.19.0 используйте
deerflow.models.vllm_provider:VllmChatModel. Для reasoning-моделей в стиле Qwen DeerFlow переключает режим рассуждений черезextra_body.chat_template_kwargs.enable_thinkingи сохраняет нестандартное полеreasoningvLLM в многоходовых диалогах с вызовами инструментов. Устаревшие конфигурацииthinkingавтоматически нормализуются для обратной совместимости. Reasoning-моделям также может потребоваться запуск сервера с флагом--reasoning-parser .... Если ваш локальный vLLM принимает любой непустой API-ключ, всё равно задайтеVLLM_API_KEYсо значением-заглушкой.Примеры CLI-провайдеров:
models: - name: gpt-5.4 display_name: GPT-5.4 (Codex CLI) use: deerflow.models.openai_codex_provider:CodexChatModel model: gpt-5.4 supports_thinking: true supports_reasoning_effort: true - name: claude-sonnet-4.6 display_name: Claude Sonnet 4.6 (Claude Code OAuth) use: deerflow.models.claude_provider:ClaudeChatModel model: claude-sonnet-4-6 max_tokens: 4096 supports_thinking: true- Codex CLI читает
~/.codex/auth.json - Claude Code принимает
CLAUDE_CODE_OAUTH_TOKEN,ANTHROPIC_AUTH_TOKEN,CLAUDE_CODE_CREDENTIALS_PATHили~/.claude/.credentials.json - Записи ACP-агентов настраиваются отдельно от провайдеров моделей — если вы настраиваете
acp_agents.codex, укажите в нём Codex ACP-адаптер, напримерnpx -y @zed-industries/codex-acp - На macOS при необходимости экспортируйте аутентификацию Claude Code явно:
eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"API-ключи также можно задать вручную в
.env(рекомендуется) или экспортировать в оболочке:OPENAI_API_KEY=your-openai-api-key TAVILY_API_KEY=your-tavily-api-key - Codex CLI читает
Запуск
Вариант 1: Docker (рекомендуется)
Разработка (hot-reload, монтирование исходников):
make docker-init # Загрузить образ Sandbox (один раз или при обновлении)
make docker-start # Запустить сервисы
Продакшен (собирает образы локально):
make up # Собрать образы и запустить все сервисы
make down # Остановить и удалить контейнеры
Tip
На Linux при ошибке
permission deniedдля Docker daemon добавьте пользователя в группуdockerи перелогиньтесь. Подробнее в CONTRIBUTING.md.
Адрес: http://localhost:2026
Вариант 2: Локальная разработка
Предварительное условие: сначала выполните шаги раздела «Конфигурация» выше (make setup). Для make dev нужен корректный config.yaml в корне проекта. Задайте DEER_FLOW_PROJECT_ROOT, чтобы явно указать корень проекта, или DEER_FLOW_CONFIG_PATH, чтобы указать конкретный файл конфигурации. Состояние времени выполнения по умолчанию записывается в .deer-flow в корне проекта и может быть перенесено через DEER_FLOW_HOME; skills по умолчанию читаются из skills/ в корне проекта, путь можно переопределить через DEER_FLOW_SKILLS_PATH. Перед запуском выполните make doctor, чтобы проверить настройку.
В Windows запускайте локальный процесс разработки из Git Bash. Нативные оболочки cmd.exe и PowerShell не поддерживаются для сервисных скриптов на bash, а работа в WSL не гарантируется, поскольку некоторые скрипты зависят от утилит Git for Windows, таких как cygpath.
-
Проверить зависимости:
make check # Проверяет Node.js 22+, pnpm, uv, nginx -
Установить зависимости:
make install -
(Опционально) Загрузить образ Sandbox заранее:
make setup-sandbox -
Запустить сервисы:
make dev -
Адрес: http://localhost:2026
Дополнительно
Режим Sandbox
DeerFlow поддерживает несколько режимов выполнения:
- Локальное выполнение — код запускается прямо на хосте
- Docker — код выполняется в изолированных Docker-контейнерах
- Docker + Kubernetes — выполнение в Kubernetes-подах через provisioner
Подробнее в руководстве по конфигурации Sandbox.
MCP-сервер
DeerFlow поддерживает настраиваемые MCP-серверы для расширения возможностей. Для HTTP/SSE MCP-серверов поддерживаются OAuth-токены (client_credentials, refresh_token). Подробнее в руководстве по MCP-серверу.
Мессенджеры
DeerFlow принимает задачи прямо из мессенджеров. Каналы запускаются автоматически при настройке, публичный IP не нужен.
DeerFlow может также предоставлять в workspace UI пользовательские подключения IM-каналов. Когда включён channel_connections, вошедшие в систему пользователи могут привязать Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat, WeCom, QQ или Buzz из боковой панели / Settings > Channels. Это переиспользует существующие исходящие транспорты channels.*, поэтому публичный IP или URL обратного вызова провайдера не требуются. Входящие IM-сообщения выполняются от имени подключённого пользователя DeerFlow. Настройки и вопросы безопасности описаны в IM Channel Connections.
| Канал | Транспорт | Сложность |
|---|---|---|
| Telegram | Bot API (long-polling) | Просто |
| Slack | Socket Mode | Средне |
| Feishu / Lark | WebSocket | Средне |
| Tencent iLink (long-polling) | Средне | |
| WeCom | WebSocket | Средне |
| DingTalk | Stream Push (WebSocket) | Средне |
| WebSocket (текст: личные сообщения и упоминания в группе) | Средняя | |
| Buzz | Nostr relay (WebSocket, NIP-42) | Средняя |
Конфигурация в config.yaml:
channels:
feishu:
enabled: true
app_id: $FEISHU_APP_ID
app_secret: $FEISHU_APP_SECRET
# domain: https://open.feishu.cn # China (default)
# domain: https://open.larksuite.com # International
wecom:
enabled: true
bot_id: $WECOM_BOT_ID
bot_secret: $WECOM_BOT_SECRET
slack:
enabled: true
bot_token: $SLACK_BOT_TOKEN
app_token: $SLACK_APP_TOKEN
allowed_users: []
telegram:
enabled: true
bot_token: $TELEGRAM_BOT_TOKEN
allowed_users: [] # числовые ID пользователей, не @username; пусто = разрешить всем
wechat:
enabled: false
bot_token: $WECHAT_BOT_TOKEN
ilink_bot_id: $WECHAT_ILINK_BOT_ID
qrcode_login_enabled: true # опционально: разрешить первичную загрузку через QR-код при отсутствии bot_token
allowed_users: [] # пусто = разрешить всем
polling_timeout: 35
state_dir: ./.deer-flow/wechat/state
max_inbound_image_bytes: 20971520
max_outbound_image_bytes: 20971520
max_inbound_file_bytes: 52428800
max_outbound_file_bytes: 52428800
dingtalk:
enabled: true
client_id: $DINGTALK_CLIENT_ID # ClientId с DingTalk Open Platform
client_secret: $DINGTALK_CLIENT_SECRET # ClientSecret с DingTalk Open Platform
allowed_users: [] # пусто = разрешить всем
card_template_id: "" # Опционально: ID шаблона AI Card для потокового эффекта печатной машинки
Ключи API в .env:
# Telegram
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
# Feishu / Lark
FEISHU_APP_ID=cli_xxxx
FEISHU_APP_SECRET=your_app_secret
# WeChat iLink
WECHAT_BOT_TOKEN=your_ilink_bot_token
WECHAT_ILINK_BOT_ID=your_ilink_bot_id
# WeCom
WECOM_BOT_ID=your_bot_id
WECOM_BOT_SECRET=your_bot_secret
# DingTalk
DINGTALK_CLIENT_ID=your_client_id
DINGTALK_CLIENT_SECRET=your_client_secret
Настройка Telegram
- Напишите @BotFather, отправьте
/newbotи скопируйте HTTP API-токен. - Укажите
TELEGRAM_BOT_TOKENв.envи включите канал вconfig.yaml.
Настройка WeChat
- Включите канал
wechatвconfig.yaml. - Либо задайте
WECHAT_BOT_TOKENв.env, либо установитеqrcode_login_enabled: trueдля первичной загрузки через QR-код. - Когда
bot_tokenотсутствует и загрузка через QR включена, следите за логами бэкенда — там появится QR-контент, возвращённый iLink, — и завершите процесс привязки. - После успешного прохождения QR-процесса DeerFlow сохраняет полученный токен в
state_dirдля последующих перезапусков. - Для развёртываний Docker Compose держите
state_dirна постоянном томе, чтобы курсорget_updates_bufи сохранённое состояние аутентификации переживали перезапуски.
Настройка WeCom
- Создайте бота на платформе WeCom AI Bot и получите
bot_idиbot_secret. - Включите
channels.wecomвconfig.yamlи заполнитеbot_id/bot_secret. - Задайте
WECOM_BOT_IDиWECOM_BOT_SECRETв.env. - Убедитесь, что зависимости бэкенда включают
wecom-aibot-python-sdk. Канал использует долговременное WebSocket-соединение и не требует публичного URL обратного вызова. - Текущая интеграция поддерживает входящие текстовые сообщения, изображения и файлы. Итоговые изображения/файлы, сгенерированные агентом, также отправляются обратно в диалог WeCom.
Настройка DingTalk
- Создайте приложение на DingTalk Open Platform и включите возможность Робот.
- На странице настроек робота установите режим приёма сообщений на Stream.
- Скопируйте
Client IDиClient Secret. УкажитеDINGTALK_CLIENT_IDиDINGTALK_CLIENT_SECRETв.envи включите канал вconfig.yaml. - (Опционально) Для включения потоковых ответов AI Card (эффект печатной машинки) создайте шаблон AI Card на платформе карточек DingTalk, затем укажите
card_template_idвconfig.yamlс ID шаблона. Также необходимо запросить разрешенияCard.Streaming.WriteиCard.Instance.Write.
Доступные команды
| Команда | Описание |
|---|---|
/new |
Начать новый диалог |
/status |
Показать информацию о текущем треде |
/models |
Список доступных моделей |
/memory |
Просмотреть память |
/help |
Показать справку |
Сообщения без команды воспринимаются как обычный чат — DeerFlow создаёт тред и отвечает.
Трассировка LangSmith
DeerFlow имеет встроенную интеграцию с LangSmith для наблюдаемости. При включении все вызовы LLM, запуски агентов и выполнения инструментов отслеживаются и отображаются в дашборде LangSmith.
Добавьте в файл .env в корне проекта:
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
LANGSMITH_PROJECT=deer-flow
LANGSMITH_ENDPOINT по умолчанию https://api.smith.langchain.com и может быть переопределён при необходимости. Устаревшие переменные LANGCHAIN_* (LANGCHAIN_TRACING_V2, LANGCHAIN_API_KEY и т.д.) также поддерживаются для обратной совместимости; LANGSMITH_* имеет приоритет, когда заданы обе.
Трассировка Langfuse
DeerFlow также поддерживает наблюдаемость через Langfuse для запусков, совместимых с LangChain.
Добавьте в файл .env:
LANGFUSE_TRACING=true
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_BASE_URL=https://cloud.langfuse.com
Если вы используете собственный экземпляр Langfuse, укажите LANGFUSE_BASE_URL в качестве URL вашего развёртывания.
Поля корреляции трасс. Каждый запуск агента аннотируется зарезервированными атрибутами трассировки Langfuse, поэтому страницы Sessions и Users заполняются автоматически:
session_id=thread_idLangGraph — группирует все трассы одного диалогаuser_id= эффективный пользователь изget_effective_user_id()(возвращается кdefaultв режиме без аутентификации)trace_name= assistant id (по умолчаниюlead-agent)tags=[env:<DEER_FLOW_ENV>, model:<model_name>](опускается, если не заданы)metadata.deerflow_trace_id= идентификатор корреляции запросов DeerFlow, всегда совпадающий с заголовком ответаX-Trace-Idтого же запроса (logging.enhance.enabledуправляет только тем, выводится ли этот идентификатор в логи)
Эти поля внедряются в RunnableConfig.metadata в корне вызова графа как для gateway-пути (runtime/runs/worker.py::run_agent), так и для встроенного пути (client.py::DeerFlowClient.stream), поэтому любой LangChain-совместимый callback может их прочитать. Установите DEER_FLOW_ENV (или ENVIRONMENT) для тегирования трасс по среде развёртывания.
Использование обоих провайдеров
Если и LangSmith, и Langfuse включены, DeerFlow подключает оба callback'а трассировки и отправляет одну и ту же активность модели в обе системы.
Если провайдер явно включён, но отсутствуют необходимые учётные данные, или если его callback не может инициализироваться, DeerFlow завершает работу с ошибкой (fail fast) при инициализации трассировки во время создания модели, а сообщение об ошибке указывает провайдера, вызвавшего сбой.
В Docker-развёртываниях трассировка отключена по умолчанию. Установите LANGSMITH_TRACING=true и LANGSMITH_API_KEY в .env для включения.
От Deep Research к Super Agent Harness
DeerFlow начинался как фреймворк для Deep Research, и сообщество вышло далеко за эти рамки. После запуска разработчики строили пайплайны, генерировали презентации, поднимали дашборды, автоматизировали контент. То, чего мы не ожидали.
Стало понятно: DeerFlow не просто research-инструмент. Это harness: runtime, который даёт агентам необходимую инфраструктуру.
Поэтому мы переписали всё с нуля.
DeerFlow 2.0 — это Super Agent Harness «из коробки». Batteries included, полностью расширяемый. Построен на LangGraph и LangChain. По умолчанию есть всё, что нужно агенту: файловая система, memory, skills, sandbox-выполнение и возможность планировать и запускать sub-agents для сложных многошаговых задач.
Используйте как есть. Или разберите и переделайте под себя.
Core Features
Skills & Tools
Skills — это то, что позволяет DeerFlow делать почти что угодно.
Agent Skill — это структурированный модуль: Markdown-файл с описанием воркфлоу, лучших практик и ссылок на ресурсы. DeerFlow поставляется со встроенными skills для ресёрча, генерации отчётов, слайдов, веб-страниц, изображений и видео. Но главное — расширяемость: добавляйте свои skills, заменяйте встроенные или собирайте из них составные воркфлоу.
Skills загружаются по мере необходимости, только когда задача их требует. Это держит контекстное окно чистым.
# Пути внутри контейнера sandbox
/mnt/skills/public
├── research/SKILL.md
├── report-generation/SKILL.md
├── slide-creation/SKILL.md
├── web-page/SKILL.md
└── image-generation/SKILL.md
/mnt/skills/custom
└── your-custom-skill/SKILL.md ← ваш skill
Интеграция с Claude Code
Skill claude-to-deerflow позволяет работать с DeerFlow прямо из Claude Code. Отправляйте задачи, проверяйте статус, управляйте тредами, не выходя из терминала.
Установка скилла:
npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow
Что можно делать:
- Отправлять сообщения в DeerFlow и получать потоковые ответы
- Выбирать режимы выполнения: flash (быстро), standard, pro (planning), ultra (sub-agents)
- Проверять статус DeerFlow, просматривать модели, скиллы, агентов
- Управлять тредами и историей диалога
- Загружать файлы для анализа
Полный справочник API в skills/public/claude-to-deerflow/SKILL.md.
Цели сессии (Session Goals)
Используйте /goal <условие завершения>, чтобы привязать к текущему треду одно активное условие завершения. Цель — это состояние уровня треда, а не активация навыка, поэтому она остаётся активной между ходами, пока DeerFlow не сочтёт её выполненной или пока вы её не очистите.
Поддерживаемые команды:
/goal finish the implementation and make all tests pass
/goal # показать активную цель
/goal clear # очистить её
После каждого запуска, выполненного через Gateway, DeerFlow оценивает видимый диалог, включая вызовы инструментов ассистента и сокращённые результаты инструментов, относительно активной цели с помощью non-thinking модели-оценщика. Одного успешного результата инструмента недостаточно для выполнения цели, а если ассистенту пришлось угадывать недостающую или неоднозначную информацию, оценщик возвращает needs_user_input. Оценщик должен вернуть типизированный блокер (missing_evidence, needs_user_input, run_failed, external_wait или goal_not_met_yet) с видимыми доказательствами. DeerFlow добавляет hidden continuation только тогда, когда последний ход assistant сохранён в чекпоинте, блокер имеет тип goal_not_met_yet, тред не изменился во время оценки и счётчик отсутствия прогресса не сработал. Предел безопасности по умолчанию — 8 hidden continuation, а повторяющиеся одинаковые оценки без прогресса останавливаются после 2 попыток. /goal clear и любой новый ввод от пользователя имеют приоритет над continuation в очереди. Когда цель выполнена, DeerFlow очищает её автоматически и публикует обновлённое состояние треда.
Веб-интерфейс показывает активную цель над полем ввода. Та же команда доступна из TUI и поддерживаемых IM-каналов. В веб-интерфейсе и поддерживаемых IM-каналах установка /goal <условие завершения> также запускает выполнение с условием в качестве задачи; команды статуса и очистки только управляют состоянием цели.
Sub-Agents
Сложные задачи редко решаются за один проход. DeerFlow их декомпозирует.
Lead agent запускает sub-agents на лету, каждый со своим изолированным контекстом, инструментами и условиями завершения. Sub-agents работают параллельно, возвращают структурированные результаты, а lead agent собирает всё в единый итог.
Вот как DeerFlow справляется с задачами на минуты и часы: research-задача разветвляется в дюжину sub-agents, каждый копает свой угол, потом всё сходится в один отчёт, или сайт, или слайддек со сгенерированными визуалами. Один harness, много рук.
Sandbox & файловая система
DeerFlow не просто говорит о том, что умеет что-то делать. У него есть собственный компьютер.
Каждая задача выполняется внутри изолированного Docker-контейнера с полной файловой системой: skills, workspace, uploads, outputs. Агент читает, пишет и редактирует файлы. Выполняет bash-команды и пишет код. Смотрит на изображения. Всё изолировано, всё прозрачно, никакого пересечения между сессиями.
Это разница между чатботом с доступом к инструментам и агентом с реальной средой выполнения.
# Пути внутри контейнера sandbox
/mnt/user-data/
├── uploads/ ← ваши файлы
├── workspace/ ← рабочая директория агентов
└── outputs/ ← результаты
Context Engineering
Изолированный контекст: каждый sub-agent работает в своём контексте и не видит контекст главного агента или других sub-agents. Агент фокусируется на своей задаче.
Управление контекстом: внутри сессии DeerFlow агрессивно сжимает контекст и суммирует завершённые подзадачи, выгружает промежуточные результаты в файловую систему, сжимает то, что уже не актуально. На длинных многошаговых задачах контекстное окно не переполняется.
Long-Term Memory
Большинство агентов забывают всё, когда диалог заканчивается. DeerFlow помнит.
DeerFlow сохраняет ваш профиль, предпочтения и накопленные знания между сессиями. Чем больше используете, тем лучше он вас знает: стиль, технологический стек, повторяющиеся воркфлоу. Всё хранится локально и остаётся под вашим контролем.
Рекомендуемые модели
DeerFlow работает с любым LLM через OpenAI-совместимый API. Лучше всего — с моделями, которые поддерживают:
- Большое контекстное окно (100k+ токенов) — для deep research и многошаговых задач
- Reasoning capabilities — для адаптивного планирования и сложной декомпозиции
- Multimodal inputs — для работы с изображениями и видео
- Strong tool-use — для надёжного вызова функций и структурированных ответов
Встроенный Python-клиент
DeerFlow можно использовать как Python-библиотеку прямо в коде — без запуска HTTP-сервисов. DeerFlowClient даёт доступ ко всем возможностям агента и Gateway, возвращает те же схемы ответов, что и HTTP Gateway API. HTTP Gateway также предоставляет DELETE /api/threads/{thread_id} для удаления локальных данных треда, управляемых DeerFlow, после того как сам LangGraph thread был удалён:
from deerflow.client import DeerFlowClient
client = DeerFlowClient()
# Chat
response = client.chat("Analyze this paper for me", thread_id="my-thread")
# Streaming (LangGraph SSE protocol: values, messages-tuple, end)
for event in client.stream("hello"):
if event.type == "messages-tuple" and event.data.get("type") == "ai":
print(event.data["content"])
# Configuration & management — returns Gateway-aligned dicts
models = client.list_models() # {"models": [...]}
skills = client.list_skills() # {"skills": [...]}
client.update_skill("web-search", enabled=True)
client.upload_files("thread-1", ["./report.pdf"]) # {"success": True, "files": [...]}
client.set_goal("thread-1", "finish the implementation and make all tests pass")
client.get_goal("thread-1") # {"goal": {...}} or {"goal": None}
client.clear_goal("thread-1")
Проекты
Проекты группируют связанные диалоги под общим именем, инструкциями и полкой документов.
Диалог присоединяется к проекту в момент создания (когда выбран проект) или позже через меню перемещения. Запуски никогда не изменяют членство: отправка сообщения не может назначить или переназначить диалог. Перемещение диалога из проекта оставляет его без назначения, пока он не будет явно перемещён снова.
Перемещение диалога обновляет его принадлежность в заголовке, а также списки проектов, в том числе когда старый запрос метаданных ещё выполняется.
Проектам требуются актуальные таблицы и столбцы базы данных. База данных с меткой 0019_thread_incarnations от старого развёртывания на основе 0018 отклоняется при запуске, если схема проектов отсутствует. Перед запуском этой сборки на такой базе следуйте процедуре автономного восстановления базы данных.
Инструкции проекта
Каждый проект хранит инструкции в свободной форме — контекст, соглашения и ограничения, применимые ко всем диалогам проекта; они редактируются на вкладке Instructions страницы проекта с живым счётчиком байтов. Когда запуск начинается на потоке-участнике, Gateway один раз фиксирует текущее состояние проекта и рендерит инструкции в виде ограниченного блока <project>, действующего только в рамках этого запроса и этого запуска: блок никогда не попадает в системный промпт и в сохранённую историю, и каждый новый запуск видит последние сохранённые инструкции. Инструкции ограничены projects.instructions_max_bytes байтами UTF-8 (по умолчанию 8192, диапазон 256–262144); многобайтовые символы считаются по их длине в байтах UTF-8. Слишком длинные инструкции отклоняются с ошибкой 422 при записи и никогда не обрезаются молча.
Полка документов
У каждого проекта есть полка документов для файлов, общих для всего проекта; она управляется в разделе Documents страницы проекта:
- Загрузить файл (кнопкой или перетаскиванием, один файл за запрос). Ограничения размера полки переиспользуют
uploads.max_file_size(по умолчанию 50 МиБ); повторная загрузка идентичного содержимого возвращает существующую запись вместо создания дубликата. - Просмотреть записи с именем, размером, временем изменения и происхождением (загружено напрямую или сохранено из диалога), а также предпросмотреть или скачать любую запись.
- Сохранить в проект из файла потока: браузер файлов диалогов только для чтения под полкой перечисляет загрузки и результаты потоков-участников, у каждой записи есть действие «Сохранить в проект».
- Прикрепить к потоку: скопировать файл с полки в загрузки потока через обычный конвейер приёма, чтобы диалог мог работать с ним напрямую.
Запуски на потоках-участниках также получают ограниченный индекс <documents>, рендеримый для каждого запуска из зафиксированного снимка (ограничен projects.shelf_index_max_entries и projects.shelf_index_max_bytes), а агент может постранично обходить полку и читать документы инструментами list_project_documents и read_project_document.
Семантика чтения архивированных проектов
Архивация проекта замораживает записи, но сохраняет чтения. Потоки архивированного проекта по-прежнему запускаются и по-прежнему получают инструкции проекта и индекс полки, а полка остаётся полностью читаемой: просмотр списка, предпросмотр/скачивание, браузер файлов диалогов и прикрепление к потоку продолжают работать. Загрузка, сохранение в проект и перемещение отдельных файлов полки в корзину требуют активного проекта, а удалённый в корзину документ нельзя восстановить в архивированный проект. Удаление архивированного проекта остаётся доступным и перемещает всю его полку в корзину.
Корзина
Удаление документа с полки перемещает его в корзину, а не стирает: запись сохраняет своё содержимое и снимок исходного проекта в течение projects.trash_retention_days (по умолчанию 30) до того, как очистка по сроку хранения сможет удалить её безвозвратно. Страница /workspace/trash — доступная из раздела Documents страницы проекта и из заголовка «Проекты» на боковой панели — перечисляет документы в корзине с их исходным проектом и оставшимся сроком хранения, с действиями «Восстановить» и «Удалить навсегда» для каждой записи, а также действием «Очистить корзину», которое безвозвратно удаляет все документы в корзине — немедленно, а не по истечении срока хранения; срок лишь ограничивает, как долго запись может там находиться, прежде чем очистка её заберёт. Восстановление возвращает документ в его исходный проект или в выбранный вами проект, если исходный удалён или архивирован; если в целевом проекте уже есть идентичный активный файл, записи объединяются. Удаление проекта за один шаг перемещает всю его полку в корзину.
Запланированные задачи (Scheduled Tasks)
Теперь в DeerFlow есть первоклассный MVP запланированных задач (scheduled-task) в workspace.
Текущие возможности MVP:
- Управление задачами на
/workspace/scheduled-tasks - Выбор: каждая запланированная задача переиспользует тред или создаёт новый тред для каждого запуска
- Поддержка расписаний
once,cronиinterval - Фоновые запланированные запуски выполняются как неинтерактивные запуски DeerFlow (
ask_clarificationтам не предоставляется) - При совпадении наступившего cron-запуска с активным запуском на том же переиспользуемом треде применяется поведение перекрытия
skip - Приостановка, возобновление, ручной запуск, просмотр истории и удаление задач
- Запланированные задачи выполняются через стандартный жизненный цикл запуска DeerFlow
Текущие ограничения MVP:
- Нет заданий с текстовыми уведомлениями
- Нет каналов или целей отправки GitHub
Включите фоновый опрос через config.yaml -> scheduler.enabled. Ручной запуск использует тот же ресурс и путь выполнения scheduled-task.
Жизненный цикл, страховочные лимиты и условия остановки
- Страница задач и REST API (
POST/PATCH /api/scheduled-tasks) принимают цель для каждого запуска (goal_objective), страховочный лимит (max_runs,end_at) и условие остановки (stop_condition).nullв PATCH очищает любое из этих четырёх полей;end_atбез смещения UTC трактуется как местное время в часовом поясе задачи. - Условие остановки — это правило пользователя «остановиться, когда …». Оно хранится в отдельном поле (миграция
0031) и никогда не попадает в инструкции задачи. DeerFlow добавляет его к сообщению запуска только при старте этого запуска и просит вызватьstop_scheduled_task, когда правило выполнено. Пока включёнscheduler.tool_enabled, каждый запланированный запуск может приостановить своё расписание, где бы ни была создана задача — в диалоге или на странице задач; если он выключен, запуск лишь сообщает, что правило выполнено. - Задачи с целью, созданные на странице задач, теперь проверяются так же, как созданные в диалоге, а их запуски тоже получают сохранённые заметки и ссылку на предыдущий запуск.
- Возобновление считает следующий запуск от текущего момента, поэтому долгая пауза не приводит к догоняющему запуску. Для разовой задачи, время которой прошло, возвращается
422 once_time_passed— нужно задать новое время. Возобновление активной задачи ничего не меняет; приостановка завершённой задачи возвращает409 task_finished. max_runs— общее число автоматических запусков за всё время жизни задачи; пробные запуски не учитываются. Повторное включение задачи с исчерпанным лимитом (возобновление или PATCH, который заново включает расписание завершённой задачи) возвращает409 limits_exhausted, если тот же запрос не обновляет исчерпанный лимит: при исчерпанном числе запусков нужен большийmax_runsилиnull, при прошедшем времени окончания — более позднийend_atилиnull(перенос одногоend_atне возобновляет задачу с исчерпаннымmax_runs). Для этогоPOST /api/scheduled-tasks/{task_id}/resumeпринимает необязательное тело{"max_runs": …, "end_at": …}(nullснимает лимит). PATCH, меняющий только лимит завершённой задачи, сохраняет его, а задача остаётся завершённой.- Сбои проверки цели (ошибка оценщика или изменение диалога во время проверки) не засчитываются в автоматическую паузу после трёх промахов подряд и не сбрасывают счётчик. Изменение цели, инструкций или условия остановки, а также новая заметка начинают отсчёт заново; возобновление его сохраняет.
- Пока планировщик этого процесса Gateway не работает, создание задачи (включая дублирование) возвращает
409 scheduler_not_running.GET /api/featuresсообщаетscheduled_tasks.available,running,tool_enabledиmin_interval_seconds. - Ошибки
/api/scheduled-tasks*имеют вид{"detail": {"code", "message", "params"}}; см.backend/docs/API.mdиcontracts/scheduled_task_errors_contract.json. - Слоты выполнения честно делятся между владельцами задач: у одного владельца одновременно может запускаться или выполняться не более
scheduler.max_concurrent_runs_per_userзапланированных запусков (по умолчанию 2, но не большеmax_concurrent_runs;0отключает лимит на владельца), а очередь ожидания разбирается по владельцам поочерёдно, поэтому накопившиеся запуски одного владельца никогда не задерживают запуск другого. Запуск, который ждёт дольшеscheduler.queue_timeout_seconds, пропускается, и в истории видно, что он слишком долго ждал свободного слота. - При
channel_connections.enabled: trueобновления запланированных задач отправляются в подключённые IM-аккаунты владельца, но только в приложения с проактивной отправкой (сейчас это WeCom); в настройках для каждого приложения указано, приходят ли туда обновления. Каждый запуск даёт не больше одного сообщения (запуск завершён, завершился ошибкой или не достиг цели, автоматическая пауза, пауза по решению агента, задача завершена). Сообщение ставится в очередь в той же транзакции, что и результат, поэтому даже после восстановления после сбоя оно приходит один раз. Оно понятно без контекста, написано на языке веб-интерфейса (иначеchannel_connections.notification_locale) и не содержит идентификаторов и ссылок. Простые ручные пробные запуски и прерванные запуски уведомлений не дают.
Создание расписаний в диалоге
Установите scheduler.enabled: true и scheduler.tool_enabled: true и перезапустите Gateway. После этого авторизованный интерактивный ход может через schedule_task создавать, изменять, просматривать, приостанавливать, возобновлять и удалять задачи, запускать пробный запуск и сохранять заметки. Например: «Каждый будний день в 9:00 проверяй release-checklist.md и сообщай, что ещё не отмечено; остановись, когда всё отмечено». В веб-приложении результат показывается живой карточкой с расписанием, условием остановки и кнопками, а агент отвечает одним-двумя предложениями; в мессенджерах (IM) и других ходах вне веба агент описывает расписание, следующий запуск и условие остановки текстом.
- Какими задачами управляет диалог. Задачами, созданными в нём, а в диалоге запуска (чате, куда запланированный запуск опубликовал результат) — ещё и задачей этого запуска: там тоже работают «приостанови это» или «перенеси на 10:00». Это относится только к вашим сообщениям; сам запланированный запуск может лишь приостановить своё расписание через
stop_scheduled_task. - Изменение сохраняет задачу. Смена времени, инструкций, цели, условия остановки или страховочного лимита — это
updateтой же задачи, поэтому её ID и история запусков сохраняются.resumeвозобновляет приостановленную или завершённую задачу без догоняющего запуска. Если лимит исчерпан, агент спрашивает, как обновить исчерпанный лимит (увеличить или снятьmax_runs; перенести или снятьend_at), и передаёт это вместе с возобновлением. - Часовой пояс. Названный вами пояс имеет приоритет. Иначе новая задача использует часовой пояс браузера, который веб-приложение отправляет с каждым сообщением (
context.client_timezone, читается только для этого), и в результате указано, какой пояс выбран. Интервалам и разовым моментам со смещением UTC пояс не нужен; для cron или локального разового времени без известного пояса (например, из мессенджера) агент спросит. При изменении сохраняется прежний пояс; пояс браузера никогда не меняет существующую задачу. - Где появляются результаты. Каждый запуск публикует результат в новом чате с названием «{задача} · {местное время}» или в исходном чате, если задача выполняется в нём. Когда расписание приостановлено агентом, приостановлено автоматически или завершилось, в исходном чате там, где остановился диалог, появляется одна строка со ссылкой на этот запуск или на задачу; больше ничего в исходный диалог не отправляется. Строка остаётся и после удаления задачи. Чат запуска показывает инструкции задачи свёрнутым блоком «Инструкции задачи» под заголовком запуска.
- Язык. Агент пишет название, инструкции и условие остановки на вашем языке, а запланированные запуски отвечают на языке инструкций.
- Пробный запуск. Попросите прямо, например «Run it now» или «先跑一次吧»; кнопка Run once now на карточке делает то же самое. Простое «yes», упоминание задачи, цитата или условная просьба не запускают платное выполнение. Пробный запуск не учитывается в
max_runs.
Терминальная панель (TUI)
deerflow — это нативная терминальная панель для тех, кто живёт в шелле. Она работает встроенной поверх DeerFlowClient — без Gateway, фронтенда, nginx или Docker — и при этом учитывает те же настройки config.yaml, checkpointer, skills, memory, MCP и sandbox, что и остальной DeerFlow.
uv pip install 'deerflow-harness[tui]' # опциональная зависимость 'textual'
deerflow # запустить терминальный UI (требуется TTY)
deerflow --continue # возобновить последний тред
deerflow --resume THREAD # возобновить тред по id
deerflow --print "summarize this repo" # автономный разовый ответ в stdout
deerflow --json "hello" # автономный режим, StreamEvents с разделением новой строкой
Интерфейс чата с управлением с клавиатуры: потоковый транскрипт (ответы рендерятся в Markdown), компактные карточки активности инструментов, палитра слэш-команд /, управление целями /goal, селекторы /model и /threads, история ввода, а также прерывание через Esc / Ctrl+C. Сессии, открытые в TUI, также появляются в боковой панели веб-интерфейса — TUI пишет в общее хранилище тредов под локальным пользователем по умолчанию, поэтому терминал и веб остаются синхронизированными без запуска Gateway.
Полное руководство — в backend/docs/TUI.md.
Документация
- Руководство по участию — настройка среды разработки, воркфлоу и гайдлайны
- Руководство по конфигурации — инструкции по настройке
- Обзор архитектуры — технические детали
- Архитектура бэкенда — бэкенд и справочник API
⚠️ Безопасность
Неправильное развёртывание может привести к угрозам безопасности
DeerFlow обладает ключевыми высокопривилегированными возможностями, включая выполнение системных команд, операции с ресурсами и вызов бизнес-логики. По умолчанию он рассчитан на развёртывание в локальной доверенной среде (доступ только через loopback-адрес 127.0.0.1). Если вы разворачиваете агент в недоверенных средах — локальных сетях, публичных облачных серверах или других окружениях, доступных с нескольких устройств — без строгих мер безопасности, это может привести к следующим угрозам:
- Несанкционированные вызовы: функциональность агента может быть обнаружена неавторизованными третьими лицами или вредоносными сканерами, что приведёт к массовым несанкционированным запросам с выполнением высокорисковых операций (системные команды, чтение/запись файлов) и серьёзным последствиям для безопасности.
- Юридические и compliance-риски: если агент будет незаконно использован для кибератак, кражи данных или других противоправных действий, это может повлечь юридическую ответственность и compliance-риски.
Рекомендации по безопасности
Примечание: настоятельно рекомендуем развёртывать DeerFlow только в локальной доверенной сети. Если вам необходимо развёртывание через несколько устройств или сетей, обязательно реализуйте строгие меры безопасности, например:
- Белый список IP-адресов: используйте
iptablesили аппаратные межсетевые экраны / коммутаторы с ACL, чтобы настроить правила белого списка IP и заблокировать доступ со всех остальных адресов. - Шлюз аутентификации: настройте обратный прокси (nginx и др.) и включите строгую предварительную аутентификацию, запрещающую любой доступ без авторизации.
- Сетевая изоляция: по возможности разместите агент и доверенные устройства в одном выделенном VLAN, изолированном от остальной сети.
- Следите за обновлениями: регулярно отслеживайте обновления безопасности проекта DeerFlow.
Участие в разработке
Приветствуем контрибьюторов! Настройка среды разработки, воркфлоу и гайдлайны — в CONTRIBUTING.md.
Лицензия
Проект распространяется под лицензией MIT.
Благодарности
DeerFlow стоит на плечах open-source сообщества. Спасибо всем проектам и разработчикам, чья работа сделала его возможным.
Отдельная благодарность:
- LangChain — фреймворк для взаимодействия с LLM и построения цепочек.
- LangGraph — многоагентная оркестрация, на которой держатся сложные воркфлоу DeerFlow.
Ключевые контрибьюторы
Авторы DeerFlow, без которых проекта бы не было: