mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-10-26 21:26:39 +00:00
f6a5a64c9b
* feat(knowledge): add optional ingestion and processing extension * fix(knowledge): address catalog and ingestion review regressions * fix(knowledge): add sanitized provider diagnostics and Chinese docs * fix(knowledge): align capabilities and repair catalog e2e assertions
117 lines
7.4 KiB
Markdown
117 lines
7.4 KiB
Markdown
# Stage 2 acceptance record
|
|
|
|
Date: 2026-10-22. Base revision: `29ba806fc`, plus this uncommitted
|
|
knowledge-management extension and tests. All ingested documents were synthetic.
|
|
This records the first Stage 2 management slice, not completion of the whole
|
|
knowledge-platform roadmap.
|
|
|
|
## Real environment
|
|
|
|
- macOS with OrbStack; authenticated DeerFlow Gateway, Next.js and nginx.
|
|
- WeKnora `v0.8.3` (adapter source pin
|
|
`3e22822c1d2397be730c458c7539d0eb8c113a24`), ParadeDB/PostgreSQL 17, Redis.
|
|
- Official WeKnora DocReader `v0.8.3`; Neo4j `2025.10.1` with APOC.
|
|
- GLM-5.3 using the operator's `.env.local` endpoint/credentials; DeerFlow
|
|
acceptance model used `chat_template_kwargs.enable_thinking=false`.
|
|
- Local Ollama BGE-M3, 1024-dimensional vectors (actual embedding request checked).
|
|
- LightRAG `v1.5.7` with an existing synthetic graph for retrieval regression.
|
|
- Separate restricted management and retrieval keys; exact administrator/base
|
|
grants. Authentication and CSRF remained enabled.
|
|
|
|
Private configuration, credentials, scripts, complete logs and screenshots remain
|
|
outside the repository in the local `knowledge-phase2-local` evidence directory.
|
|
No credential values or private model URLs are part of this report.
|
|
|
|
## Observed outcomes
|
|
|
|
| Check | Actual outcome |
|
|
| --- | --- |
|
|
| Manual text ingestion | `202`, then completed/searchable; unique marker retrieved from the selected document |
|
|
| Markdown file ingestion | `202`, then completed/searchable |
|
|
| URL ingestion | Initial DocReader failure; explicit reprocessing completed after the environment repair below |
|
|
| Capability discovery | Plain document and Wiki/graph-enabled bases advertised different optional capabilities |
|
|
| Cancel and explicit recovery | Cancellation returned `202`; cancelled/not searchable observed; explicit reprocess returned `202`, then completed with graph and Wiki spans done |
|
|
| Graph extraction/indexing | Graph span done; Neo4j contained two actual relations for the synthetic project; entity node chunk IDs resolved to the original source text |
|
|
| Wiki generation | Published entity/project/organization/summary pages and Index observed; exact keyword retrieval returned attributable evidence |
|
|
| Browser GLM question | One base/one document selected; correct allowance, deadline and synthetic marker, with clickable source text |
|
|
| Citation persistence | Source opened after refresh and after Gateway restart; prior answer and source excerpt persisted |
|
|
| API live regression | Management ingestion → selected retrieval → serialized citation replay, plus selected retrieval and Wiki regressions: 3 passed |
|
|
| Three-tool GLM regression | Explicit Wiki keyword: 3 passed in 15.64 seconds, including real document/Wiki/LightRAG evidence and citation serialization/forwarding/pruning |
|
|
|
|
Nine real authorization/input checks passed: anonymous `401`, missing CSRF `403`,
|
|
ungranted base `403`, cross-base document `403`, forged identity field `422`,
|
|
unsupported graph option `422`, ordinary user `403`, retrieval-only upstream key
|
|
write `403`, and upstream outside-base access `403`.
|
|
|
|
The browser synthetic answer was 735 CNY/night, submission within 12 calendar
|
|
days, marker `PHASE2-YEW-735-12`. Graph evidence contained project → leader and
|
|
organization → project relationships. Node provenance was checked; the upstream
|
|
edges had no direct chunk properties. This is not proof of edge-specific
|
|
provenance, arbitrary graph quality or multi-hop reasoning.
|
|
|
|
## Failures and environment repairs
|
|
|
|
The existing local stack lacked DocReader and Neo4j. URL ingestion initially
|
|
reported `DOCREADER_UNAVAILABLE`. Official DocReader and Neo4j were added only
|
|
to the private Compose configuration, without publishing their ports. Reparse
|
|
then exposed missing APOC functions; installing the official APOC plugin allowed
|
|
explicit reconciliation/reprocessing to succeed. The local DNS returned Fake-IP
|
|
addresses, requiring exact upstream SSRF allowlist entries for the model host
|
|
and the synthetic URL host. No broad SSRF bypass was added.
|
|
|
|
Free-form three-tool model runs failed the Wiki evidence assertion (two checks
|
|
passed, one failed). Diagnostic tool calls showed the query
|
|
`紫杉研发项目负责人 资助组织`. WeKnora's Wiki endpoint is lexical; neither that
|
|
phrase nor its whitespace-separated terms matched the published page titles.
|
|
A subsequent prompt explicitly requesting the keyword `紫杉` passed all three
|
|
checks. The fixed-keyword result establishes integration, not unrestricted
|
|
natural-language Wiki recall. No retrieval assertion was removed or weakened.
|
|
|
|
One pipeline document remained `finalizing`/searchable during an additional
|
|
upstream Wiki update after publishing pages. Final inspection confirmed
|
|
`completed`, with chunking, embedding, graph and both Wiki update spans done.
|
|
The separate cancellation recovery case also reached `completed` with all
|
|
relevant spans done. The intermediate searchable state was not treated as
|
|
terminal completion.
|
|
|
|
## Offline regression and reproduction
|
|
|
|
Before live acceptance, the full backend suite passed 35,467 tests across four
|
|
shards (796 skipped); strict blocking-I/O coverage passed 276 tests (one skipped).
|
|
The extension's focused contract and blocking-I/O tests passed 46 checks.
|
|
The final focused run including agent-guidance checks passed 60 tests, with the
|
|
non-opted-in live test skipped. Ruff lint/format and package wheel building passed. Live acceptance added a
|
|
separately gated test; it does not alter normal offline test behavior.
|
|
|
|
See [README.md](README.md#opt-in-live-regression) for the live environment variables
|
|
and command. That test deliberately writes one unique synthetic document per run,
|
|
retains its ID and does not automatically retry or delete it. Browser acceptance
|
|
requires selecting the resulting document in the existing chat scope selector,
|
|
asking a question unique to the fixture, opening its source, refreshing, then
|
|
restarting Gateway and opening the persisted source again. Wiki/graph acceptance
|
|
must additionally inspect the upstream spans, published pages and actual graph
|
|
records; document parse completion alone is insufficient.
|
|
|
|
Out of scope: a management frontend, platform spaces/sharing, arbitrary parser or
|
|
model configuration, Trace persistence, standalone Wiki editing, upstream user
|
|
impersonation, multi-Gateway ingestion admission and exactly-once writes.
|
|
|
|
## PR review follow-up
|
|
|
|
Review regressions now reject parent-child chunk overrides on manual, URL, file
|
|
and reprocess paths before any upstream mutation; empty and non-chunk overrides
|
|
remain supported. All four rejection cases failed before the fix and passed
|
|
afterward. The oversized-upload case has a compact explicit pytest ID, avoiding
|
|
Windows environment-variable limits (native Windows was not rerun locally).
|
|
Frontend discovery includes the package's actual namespace and localized copy.
|
|
Focused backend/guidance checks: 64 passed, 1 skipped. Frontend catalog: 9 passed;
|
|
frontend lint/typecheck and backend formatting passed.
|
|
|
|
Further review: capabilities now omit unsupported per-base controls, and invalid
|
|
local credentials return a distinct pre-request 503. Seven new cases failed
|
|
before the fix; focused backend/guidance checks now pass 77 tests (1 live skip).
|
|
The three failing CI catalog E2E cases used the obsolete fixed count 11; they
|
|
now use the catalog length plus explicit localized management-entry assertions.
|
|
All three pass locally against an isolated Next.js development server. Catalog
|
|
unit tests (9), frontend lint/typecheck and backend formatting also pass.
|