Xinmin Zeng 2a97ec3e58
docs: turn README into an index and move reference detail to docs/guide (#8113)
* docs: turn README into an index and move reference detail to docs/guide

The README had grown to 393 KB because every change appended its notes there. The text moves verbatim into 18 topic guides under docs/guide/; only headings are re-leveled and relative links re-pointed. The README keeps the introduction, a quick start and a guide index. Contributor test notes move to CONTRIBUTING.md.

* docs: send user docs to topic guides and budget the root README

The rule 'update README.md for user-facing changes' is what grew the README. Guidance now points to docs/guide/, and check_agent_guidance.py fails when the root README exceeds 16 KiB (AG003).

* chore: remove unreferenced screenshots and finished plan notes

pr-build/ holds two PR screenshots (3 MB) from #1986. plans/ holds the plan for the merged #4049. docs/SKILL_NAME_CONFLICT_FIX.md is a February change note. Nothing references them.

* docs: route always-loaded AGENTS.md files to scoped guides

* docs(agents): cut scoped guides to scope, verify, traps, decisions

Each AGENTS.md keeps four kinds of content: the scope of the directory, the
verification commands, traps a local test run does not show, and decisions the
code cannot state. Values, field lists, function inventories, test names, issue
numbers and history are deleted, because the code, the tests and git state them.

Search and fetch providers share one community guide. Four guides with no
remaining content are removed. The size check now allows 6 KiB per file (hard
limit 8 KiB) and 24 KiB per chain (hard limit 32 KiB).

* style: format frontend guide table and guidance test imports

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
2026-11-11 13:26:17 +08:00

2.9 KiB

Harness package (deerflow/)

The publishable deerflow-harness package: agents, runtime, tools, sandbox, models, MCP, skills, config and persistence. Each subpackage has its own guide, listed in backend/AGENTS.md. This file covers the modules at the package root. The harness never imports app.*.

Request trace context (trace_context.py)

The request correlation ID is the X-Trace-Id header and the deerflow_trace_id key. It is not the Langfuse trace ID and not the run_id.

  • The ContextVar is the only source. Every entry point that starts a run binds an ID first: the HTTP middleware, a scheduled occurrence, an MCP task notification, an IM message and an embedded client turn. A new entry point binds one too.
  • Bind one unit of work, never a poller loop. A binding that leaks on a reused worker task tags later work with the first ID.
  • Every other carrier is an output. A deerflow_trace_id that a caller sends is replaced, because the stored run would otherwise disagree with the header and the logs.
  • An HTTP request does not inherit an ambient ID. A crafted header must not fall back to the previous request's ID.
  • Use ensure_trace_id() and resolve_trace_id() in place of a local fallback chain. A ContextVar does not survive a bare thread hop, so an ID that crosses one travels as data.
  • DeerFlowClient.stream() binds per step, never across a yield. A sync generator shares the caller's context.
  • A crash-recovered scheduled launch keeps the first attempt's ID on the run record. That is accepted: restamping would rewrite an existing record.

Embedded client (client.py)

DeerFlowClient runs the harness without HTTP and shares config, data directories and response schemas with the Gateway.

  • A method that mirrors a Gateway route returns the same schema. TestGatewayConformance in tests/test_client.py parses each result with the Gateway model; add a new method there.
  • The client does not delete a thread's data directory. Only the Gateway does, after the LangGraph thread is deleted.

Other root modules

  • Lark CLI credentials (integrations/lark_cli.py). A managed skill pack is staged privately and published with one rename, so a failed write leaves the previous pack in place. When you switch the app, clear the old OAuth data before lark-cli config init: on Linux the new secret is written under the same data directory, and a later clear would remove it.
  • Workspace snapshots (workspace_changes/recorder.py). On cancellation, drain a text scan before you remove the cache that its worker reads. A metadata scan owns no cache and is cancelled at once.
  • Project summaries (projects/summaries.py). stop() closes admission first, and start() reopens it only after the stop has finished.
  • Environment values are strings. Parse a boolean before you pass it to an SDK, because bool("false") is true.