feat(ragflow): support request-scoped retrieval filters

[Ycymac]

AgentScope-Java Version

2.0.3-SNAPSHOT

Description

Closes #686.

RAGFlow retrieval filters were bound to RAGFlowConfig when a RAGFlowKnowledge instance was created, so application code could not change datasetIds or metadataCondition between retrieval calls without rebuilding the knowledge or agent setup.

This PR:

• adds request-scoped datasetIds and metadataCondition overloads to RAGFlowKnowledge and RAGFlowClient;
• keeps the existing APIs and configuration validation unchanged;
• uses non-empty request values when provided and falls back to RAGFlowConfig for null or empty values;
• copies request collections before deferred execution so separate retrieval calls do not share mutable request state;
• adds coverage for two consecutive dynamic filter requests on one knowledge instance and for config fallback.

Validation

mvn -pl agentscope-extensions/agentscope-extensions-rag/agentscope-extensions-rag-ragflow -am '-Dtest=RAGFlow*Test' '-DfailIfNoTests=false' test

Result: 97 tests passed, 0 failures, 0 errors, 0 skipped. Spotless also passed as part of the Maven build.

Checklist

• Code formatting passes Spotless
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[codecov]

Codecov Report

❌ Patch coverage is 86.66667% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...pe/core/rag/integration/ragflow/RAGFlowClient.java	84.61%	0 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[Ycymac]

CI rerun report for the unchanged commit 7959d6d1:

• The initial workflow run 31306550141 passed on both Ubuntu and Windows.
• The first reopen run 31307227664 reproduced the unrelated agentscope-harness temporary-directory cleanup race. Ubuntu failed in HarnessAgentDynamicHookBuilderTest.disableDynamicSkills_keepsWorkspaceLazyResourcesLoadable; Windows logged the same cleanup error in HarnessAgentSubagentStreamTest.call_localSubagent_returnsReplyWithoutStreaming before being cancelled by fail-fast.
• A second reopen run 31307826560 reproduced it again. Ubuntu failed in HarnessAgentSubagentStreamTest.call_localSubagent_returnsReplyWithoutStreaming—the same test that logged the Windows cleanup error in the previous run. Windows was cancelled by fail-fast before producing an independent result.

In each completed failure, the test body had no assertion failure. JUnit failed while closing the extension context because its temporary directory could not be deleted (DirectoryNotEmptyException). The latest Ubuntu run reported 812 tests, 0 failures, and 1 cleanup error. The RAGFlow module was not reached after the Harness failure and is marked skipped in the reactor summary.

The focused RAGFlow suite still passes locally: 97 tests, 0 failures, 0 errors. One all-green run followed by two unchanged-SHA runs whose cleanup error moved between Harness tests and operating systems is strong evidence of a repository-level flaky Harness cleanup race rather than a failure caused by this PR's three RAGFlow files. No code change has been made in response to these CI runs.