mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-12 14:00:35 +00:00
2a97ec3e58
* 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>
110 lines
6.0 KiB
Markdown
110 lines
6.0 KiB
Markdown
# Projects
|
||
|
||
Projects group related conversations under a shared name, instructions, and
|
||
document shelf.
|
||
|
||
A conversation joins a project at creation time (when a project is selected) or
|
||
later through the move menu. Runs never modify membership: submitting a message
|
||
cannot assign or reassign a conversation. Moving a conversation out of a project
|
||
keeps it unassigned until it is explicitly moved again.
|
||
|
||
Moving a conversation refreshes its header affiliation as well as the project
|
||
lists, including when an older metadata request is still in flight.
|
||
|
||
Projects require the current database tables and columns. A database stamped
|
||
`0019_thread_incarnations` from the older 0018-based rollout is rejected at
|
||
startup if the project schema is missing. Follow the
|
||
[offline database recovery procedure](../../docs/database-forward-revision-recovery.md)
|
||
before starting this build against that database.
|
||
|
||
## Project instructions
|
||
|
||
Each project stores free-form instructions — background, conventions, and
|
||
constraints that apply to every conversation in the project — editable on the
|
||
project page's Instructions tab with a live byte counter. When a run starts on
|
||
a member thread, the Gateway pins the project's current state once and renders
|
||
the instructions as a bounded, request-scoped `<project>` block for that run
|
||
only: the block never enters the system prompt or persisted history, and every
|
||
new run sees the latest saved instructions. Instructions are capped at
|
||
`projects.instructions_max_bytes` UTF-8 bytes (default 8192, range 256–262144);
|
||
multi-byte characters count as their UTF-8 byte length. Oversized instructions
|
||
are rejected with a `422` at write time and are never silently truncated.
|
||
|
||
## Document shelf
|
||
|
||
Each project has a document shelf for files the whole project shares, managed
|
||
from the project page's Documents section:
|
||
|
||
- **Upload** a file (button or drag-drop, one file per request). Shelf size
|
||
limits reuse `uploads.max_file_size` (default 50 MiB); re-uploading identical
|
||
content returns the existing entry instead of creating a duplicate.
|
||
Oversized uploads return `413`; deduplicated uploads return `200`. Staging
|
||
cleanup failures are logged without replacing these outcomes or a missing,
|
||
foreign, or archived project's `404` response.
|
||
Cancelling a shelf upload discards its partial file after any active disk
|
||
operation finishes; waiting for further upload data remains cancellable.
|
||
- **List** entries with name, size, modified time, and provenance (uploaded vs.
|
||
saved from a conversation), and preview or download any entry.
|
||
- **Save to project** from a thread file: the read-only conversation-files
|
||
browser below the shelf lists member threads' uploads and outputs, each with
|
||
a Save to project action.
|
||
- **Attach to thread**: copy a shelf file into a thread's uploads through the
|
||
normal ingestion pipeline, so the conversation can work with it directly.
|
||
|
||
New shelf names, including explicit upload `name` and promotion `shelf_name`,
|
||
follow ordinary upload filename validation. Names containing NUL, Windows
|
||
reserved device names (such as `CON.txt`), or trailing dots are rejected with
|
||
`400` before bytes are staged.
|
||
|
||
On native Windows, the document shelf uses extended-length filesystem paths
|
||
so deep workspace directories and long filenames can be uploaded, downloaded,
|
||
restored, and purged without enabling the system-wide long-path setting.
|
||
Filesystem limits on individual path components still apply.
|
||
|
||
Runs on member threads also receive a bounded `<documents>` index rendered per
|
||
run from the pinned snapshot (capped by `projects.shelf_index_max_entries` and
|
||
`projects.shelf_index_max_bytes`), and the agent can page the shelf and read
|
||
documents with the `list_project_documents` and `read_project_document` tools.
|
||
|
||
Document character counts use a bounded, thread-safe cache; concurrent reads
|
||
do not serialize full file scans behind its cache lock.
|
||
|
||
Shelf conversion cleanup failures are logged without replacing the read result
|
||
or its original error. Cancelled reads wait for their staging cleanup to finish;
|
||
files that cannot be removed remain eligible for the existing retention sweep.
|
||
|
||
## Archive read semantics
|
||
|
||
Archiving a project freezes writes but keeps reads. Threads in an archived
|
||
project still run and still receive the project's instructions and shelf index,
|
||
and the shelf remains fully readable: listing, preview/download, the
|
||
conversation-files browser, and attach-to-thread all keep working. Uploads,
|
||
save-to-project, and moving individual shelf files to trash require an active
|
||
project, and a trashed document cannot be restored into an archived one.
|
||
Deleting an archived project remains allowed and moves its whole shelf to
|
||
trash.
|
||
|
||
## Trash
|
||
|
||
Deleting a shelf document moves it to trash instead of erasing it: the entry
|
||
keeps its bytes and a snapshot of its origin project for
|
||
`projects.trash_retention_days` (default 30) before the retention sweep may
|
||
purge it permanently. The `/workspace/trash` page — reachable from the project
|
||
page's Documents section and the sidebar Projects header — lists trashed
|
||
documents with their origin project and remaining retention, with per-entry
|
||
Restore and Delete permanently actions plus an Empty trash action that
|
||
permanently deletes every document in the trash — immediately, not after the
|
||
retention window; the window only bounds how long an entry may sit there
|
||
before the retention sweep reclaims it. Restore returns the document to its
|
||
origin project, or to a project you pick when the origin is gone or archived;
|
||
if the target already holds an identical active file, the entries merge.
|
||
Deleting a project moves its entire shelf to trash in the same step.
|
||
|
||
If the retention configuration cannot be read, automatic cleanup is deferred
|
||
and the trash listing remains available. Cleanup resumes with the current
|
||
configured retention window once the configuration is readable again.
|
||
|
||
Permanently deleting read-only documents also works on Windows. A file that is
|
||
already missing does not block deletion; other filesystem errors keep the entry
|
||
in Trash for retry. Permissions on symlink targets are preserved.
|