deer-flow/examples/deerflow-extension-knowledge-management/VALIDATION.md

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 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.