rayhpeng f68fb0c4cf docs(schedule): lead the walkthrough with a behavioural spec
Restructure per review: state what the system promises before how the
code delivers it. The thin product-decision table becomes a full §1
behavioural spec written in zero implementation vocabulary -- user
operations, scheduling semantics, the skip-not-queue overlap decision,
the busy-wait guarantees (delayed, never lost; ordered by due time; no
catch-up of missed cron periods), the failure/recovery table, and an
explicit non-goals list (no queue, no punctuality guarantee, no task
credentials, single scheduler instance) -- each promise cross-referenced
to the section whose mechanism delivers it.

The mechanism chapters absorb what the spec now promises: §6.2 explains
where waiting goes (the table as an implicit priority queue via the
claim query's ordering), §6.3 and a new pitfall entry name the
budget-leak boundary when a completion callback is lost, §8's defence
table gains the race-window column and a per-layer error-translation
table as the journey's unhappy half, and the HTTP endpoint block moves
beside the commands it carries.
2026-07-31 10:18:46 +08:00
..
2026-07-20 23:56:37 +08:00

Documentation

This directory contains detailed documentation for the DeerFlow backend.

Document Description
ARCHITECTURE.md System architecture overview
HEXAGONAL_ARCHITECTURE_zh.md 六边形Ports & Adapters分层规范标准结构AWS 三文件夹 + domain 七件套、Commands/Events 设计、规则清单与执法、调用关系
FEEDBACK_DESIGN_zh.md 用户反馈模块设计:首个完成的六边形切片,聚合/端口/适配器逐层走读与二次开发指引
SCHEDULE_DESIGN_zh.md 定时任务模块设计:第二个六边形切片——两聚合两状态机、三驱动源、四道并发防线的完整走读
API.md Complete API reference
AUTH_DESIGN.md User authentication, CSRF, platform-trust (IM / Internal Auth), and per-user isolation
SSO.md OIDC / SSO single sign-on
IM_CHANNEL_CONNECTIONS.md IM channel user binding (channel_connections)
CONFIGURATION.md Configuration options
SETUP.md Quick setup guide

Feature Documentation

Document Description
STREAMING.md Token-level streaming design: Gateway vs DeerFlowClient paths, stream_mode semantics, per-id dedup
RUN_EVENT_STREAM.md Persisted run event stream contract: envelope, producers, consumers, and known gaps
FILE_UPLOAD.md File upload functionality
PATH_EXAMPLES.md Path types and usage examples
SANDBOX_MEMORY_PROFILING.md Sandbox memory baseline and runtime comparison guide
summarization.md Context summarization feature
plan_mode_usage.md Plan mode with TodoList
AUTO_TITLE_GENERATION.md Automatic title generation

Development

Document Description
TODO.md Planned features and known issues

Getting Started

  1. New to DeerFlow? Start with SETUP.md for quick installation
  2. Configuring the system? See CONFIGURATION.md
  3. Understanding the architecture? Read ARCHITECTURE.md
  4. Building integrations? Check API.md for API reference
  5. Wondering why the layers are split the way they are? Read HEXAGONAL_ARCHITECTURE_zh.md for the rules, then FEEDBACK_DESIGN_zh.md for the minimal worked example and SCHEDULE_DESIGN_zh.md for the full-complexity one

Document Organization

docs/
├── README.md                  # This file
├── ARCHITECTURE.md            # System architecture
├── HEXAGONAL_ARCHITECTURE_zh.md  # Hexagonal layering rules (zh)
├── FEEDBACK_DESIGN_zh.md      # Feedback module design (zh) — first hexagonal slice
├── SCHEDULE_DESIGN_zh.md      # Schedule module design (zh) — second hexagonal slice
├── API.md                     # API reference
├── AUTH_DESIGN.md             # User authentication and isolation design
├── CONFIGURATION.md           # Configuration guide
├── SETUP.md                   # Setup instructions
├── FILE_UPLOAD.md             # File upload feature
├── PATH_EXAMPLES.md           # Path usage examples
├── summarization.md           # Summarization feature
├── plan_mode_usage.md         # Plan mode feature
├── STREAMING.md               # Token-level streaming design
├── RUN_EVENT_STREAM.md        # Persisted run event stream contract
├── AUTO_TITLE_GENERATION.md   # Title generation
├── TITLE_GENERATION_IMPLEMENTATION.md  # Title implementation details
└── TODO.md                    # Roadmap and issues