docs: update middleware contribution examples

[dajiaohuang]

Fixes #4943

Why

The backend contributor guide and English/Chinese site guides use middleware APIs that are absent from DeerFlow's locked LangChain version. The examples either fail to import BaseMiddleware or define transform_state, on_start, and on_end methods that the current AgentMiddleware lifecycle never calls.

What changed

• Replaced the stale examples with executable AgentMiddleware[AgentState] examples using before_model and after_model hooks.
• Documented the supported extensions.middlewares import-path registration, its zero-argument constructor requirement, shared lead/subagent placement, and trusted-code boundary.
• Documented the current embedded APIs: DeerFlowClient(middlewares=[...]) and create_deerflow_agent(extra_middleware=[...]).
• Kept the English and Chinese site sources synchronized.
• Added a focused regression test that imports and instantiates every authoritative example and verifies that it overrides the current lifecycle hooks.

Surface area

• Frontend UI — page / component / setting / interaction under frontend/
• Backend API — endpoint / SSE event / request-response shape under backend/app
• Agents / LangGraph — agent node, graph wiring, langgraph.json, or prompt change
• Sandbox — docker/ or sandboxed execution
• Skills — change under skills/
• Dependencies — new/upgraded entry in backend/pyproject.toml or frontend/package.json (say what it buys us)
• Default behavior change — changes existing behavior without the user opting in (default model, default setting, data shape)
• Docs / tests / CI only — no runtime behavior change

Screenshots / Recording

N/A — no frontend UI behavior changed.

Bug fix verification

• Test path that reproduces the bug: backend/tests/test_middleware_documentation.py
• Did it go red on main and green on this branch? Yes. The five authoritative examples produced five failures on main; all five pass after the documentation update.
• The test executes the controlled Python snippets, instantiates their middleware classes with the documented zero-argument contract, and verifies that before_model and after_model override the locked AgentMiddleware hooks.

Validation

• cd backend && uv sync --locked — completed with 248 packages resolved.
• cd backend && uv run --locked ruff check . — passed.
• cd backend && uv run --locked ruff format --check . — 1,159 files already formatted.
• cd backend && uv run --locked pytest tests/test_middleware_documentation.py tests/test_lead_agent_model_resolution.py -q — 49 passed.
• cd frontend && corepack pnpm@10.26.2 install --frozen-lockfile — completed without lockfile changes.
• cd frontend && corepack pnpm@10.26.2 format — passed.
• cd frontend && corepack pnpm@10.26.2 lint — passed.
• cd frontend && corepack pnpm@10.26.2 typecheck — passed.
• cd frontend && corepack pnpm@10.26.2 exec rstest run tests/unit/content/docs-links.test.ts — 1 passed.
• cd frontend && BETTER_AUTH_SECRET=local-dev-secret-for-build-validation-4943 corepack pnpm@10.26.2 build — production build passed; 101 static pages generated.

AI assistance

Tool(s) used: Codex

How you used it: Codex reproduced the stale imports and hooks, cross-checked current middleware implementation and registration paths, drafted the synchronized documentation and regression test, and ran the validation commands listed above. Human line-by-line review is pending.

• I've read and understand every line of this change and take responsibility for it — it's not unreviewed AI output.

[WillemJiang]

The issue is addressed by #4968