mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-20 11:20:35 +00:00
* 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>
3.7 KiB
3.7 KiB
Agent teams extension (examples/deerflow-extension-agent-teams/)
An installable extension that runs a team of member agents with shared public state, queued jobs and retained artifacts. The team logic stays in this package. Limits and field lists are in the code; this file holds the rules that a local test run does not show.
Verify
Run the backend plugin tests and the browser check that README.md documents. The preview fixture uses synthetic authentication and stays on loopback; it is never a deployed Gateway.
Boundaries
- Import only
deerflow_extension_apiand the declared dependencies. Hostapp.*anddeerflow.*modules are private. Browser code is a native module listed in the manifest and has no dependency on the host's React. - The extension API version is declared twice, in the package dependency and in the install marker. Raise both together.
- Never serialize a host capability, and never expose frozen inputs or resume payloads in a read.
Ownership and trust
- Every public read and every mutation is owner-scoped. The cross-owner snapshot exists for scheduling only and is never a public read.
- Identity comes from the Gateway's stamped runtime identity, not from mention text or message content. History and result tools check the owner and a current member thread on every read.
- Sharing a thread does not share a team.
- Public state is task data written by members. It is not verified consensus and not a framework instruction. A registered file is not a verified delivery, and file content is untrusted.
- A stale writer must not overwrite a newer edit. Compare the entry revision and write inside the same owner-scoped transaction.
- Bound the complete serialized response, including metadata and escaping, and measure in UTF-8 bytes. Anchor a cursor to a record ID, and report an expired anchor instead of restarting the pagination.
Admission and scheduling
- Persist the run input and the idempotency key before admission. An unknown admission outcome keeps ownership of the pending job and stays charged against capacity; it is reconciled, not retried.
- A terminal run alone is not success, and an interruption is never approved automatically. After a restart, only an authenticated action or a native mention rebinds a job.
- A terminal result and its follow-up receipt commit in one SQLite transaction, and so do team data and the pending-jobs projection.
- Hold the scheduling lock for bookkeeping only, never across a host call. Execution and control mutations take the team-scoped lock.
- Order within a thread is first unfinished first. A job that waits for input releases its slot and still holds the head of its thread's queue.
- Persist
resume.startedbefore you attempt an answer. Cancelling an answer that has not started never admits it. - No new work is admitted over an unresolved input request, whether it is a graph interrupt or an ordinary human-input artifact.
- Reject malformed Unicode before you change a waiting job or admit a run.
Artifacts
- A declaration belongs to the authenticated member's executing job. Validate the host-stamped run identity and its execution key; a frozen queue input is not proof of execution.
- Capture after a successful execution and before the source thread's queue head is released. A snapshot and its ready status commit together.
- A retry reuses the exact captured version and path. Do not read a mutable source again, and do not overwrite an older version.
- A file transfer pauses the worker deadline. Restore the remaining budget afterwards, and drain cancellation before you release a host reservation or a sandbox lease.