feat: Add intelligent clarification feature in coordinate step for research queries (#613)

* fix: support local models by making thought field optional in Plan model

- Make thought field optional in Plan model to fix Pydantic validation errors with local models
- Add Ollama configuration example to conf.yaml.example
- Update documentation to include local model support
- Improve planner prompt with better JSON format requirements

Fixes local model integration issues where models like qwen3:14b would fail
due to missing thought field in JSON output.

* feat: Add intelligent clarification feature for research queries

- Add multi-turn clarification process to refine vague research questions
- Implement three-dimension clarification standard (Tech/App, Focus, Scope)
- Add clarification state management in coordinator node
- Update coordinator prompt with detailed clarification guidelines
- Add UI settings to enable/disable clarification feature (disabled by default)
- Update workflow to handle clarification rounds recursively
- Add comprehensive test coverage for clarification functionality
- Update documentation with clarification feature usage guide

Key components:
- src/graph/nodes.py: Core clarification logic and state management
- src/prompts/coordinator.md: Detailed clarification guidelines
- src/workflow.py: Recursive clarification handling
- web/: UI settings integration
- tests/: Comprehensive test coverage
- docs/: Updated configuration guide

* fix: Improve clarification conversation continuity

- Add comprehensive conversation history to clarification context
- Include previous exchanges summary in system messages
- Add explicit guidelines for continuing rounds in coordinator prompt
- Prevent LLM from starting new topics during clarification
- Ensure topic continuity across clarification rounds

Fixes issue where LLM would restart clarification instead of building upon previous exchanges.

* fix: Add conversation history to clarification context

* fix: resolve clarification feature message to planer, prompt, test issues

- Optimize coordinator.md prompt template for better clarification flow
- Simplify final message sent to planner after clarification
- Fix API key assertion issues in test_search.py

* fix: Add configurable max_clarification_rounds and comprehensive tests

- Add max_clarification_rounds parameter for external configuration
- Add comprehensive test cases for clarification feature in test_app.py
- Fixes issues found during interactive mode testing where:
  - Recursive call failed due to missing initial_state parameter
  - Clarification exited prematurely at max rounds
  - Incorrect logging of max rounds reached

* Move clarification tests to test_nodes.py and add max_clarification_rounds to zh.json

web/src/app/settings/tabs/general-tab.tsx

@@ -26,6 +26,10 @@ import type { Tab } from "./types";
 
 const generalFormSchema = z.object({
   autoAcceptedPlan: z.boolean(),
+  enableClarification: z.boolean(),
+  maxClarificationRounds: z.number().min(1, {
+    message: "Max clarification rounds must be at least 1.",
+  }),
   maxPlanIterations: z.number().min(1, {
     message: "Max plan iterations must be at least 1.",
   }),
@@ -102,6 +106,52 @@ export const GeneralTab: Tab = ({
                 </FormItem>
               )}
             />
+            <FormField
+              control={form.control}
+              name="enableClarification"
+              render={({ field }) => (
+                <FormItem>
+                  <FormControl>
+                    <div className="flex items-center gap-2">
+                      <Switch
+                        id="enableClarification"
+                        checked={field.value}
+                        onCheckedChange={field.onChange}
+                      />
+                      <Label className="text-sm" htmlFor="enableClarification">
+                        {t("enableClarification")} {field.value ? "(On)" : "(Off)"}
+                      </Label>
+                    </div>
+                  </FormControl>
+                </FormItem>
+              )}
+            />
+            {form.watch("enableClarification") && (
+              <FormField
+                control={form.control}
+                name="maxClarificationRounds"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>{t("maxClarificationRounds")}</FormLabel>
+                    <FormControl>
+                      <Input
+                        className="w-60"
+                        type="number"
+                        defaultValue={field.value}
+                        min={1}
+                        onChange={(event) =>
+                          field.onChange(parseInt(event.target.value || "1"))
+                        }
+                      />
+                    </FormControl>
+                    <FormDescription>
+                      {t("maxClarificationRoundsDescription")}
+                    </FormDescription>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+            )}
             <FormField
               control={form.control}
               name="maxPlanIterations"

web/src/core/api/chat.ts

@@ -18,6 +18,7 @@ export async function* chatStream(
     thread_id: string;
     resources?: Array<Resource>;
     auto_accepted_plan: boolean;
+    enable_clarification?: boolean;
     max_plan_iterations: number;
     max_step_num: number;
     max_search_results?: number;

web/src/core/store/settings-store.ts

@@ -10,6 +10,8 @@ const SETTINGS_KEY = "deerflow.settings";
 const DEFAULT_SETTINGS: SettingsState = {
   general: {
     autoAcceptedPlan: false,
+    enableClarification: false,
+    maxClarificationRounds: 3,
     enableDeepThinking: false,
     enableBackgroundInvestigation: false,
     maxPlanIterations: 1,
@@ -25,6 +27,8 @@ const DEFAULT_SETTINGS: SettingsState = {
 export type SettingsState = {
   general: {
     autoAcceptedPlan: boolean;
+    enableClarification: boolean;
+    maxClarificationRounds: number;
     enableDeepThinking: boolean;
     enableBackgroundInvestigation: boolean;
     maxPlanIterations: number;
@@ -160,4 +164,14 @@ export function setEnableBackgroundInvestigation(value: boolean) {
   }));
   saveSettings();
 }
+
+export function setEnableClarification(value: boolean) {
+  useSettingsStore.setState((state) => ({
+    general: {
+      ...state.general,
+      enableClarification: value,
+    },
+  }));
+  saveSettings();
+}
 loadSettings();

web/src/core/store/store.ts

@@ -104,6 +104,7 @@ export async function sendMessage(
       interrupt_feedback: interruptFeedback,
       resources,
       auto_accepted_plan: settings.autoAcceptedPlan,
+      enable_clarification: settings.enableClarification ?? false,
       enable_deep_thinking: settings.enableDeepThinking ?? false,
       enable_background_investigation:
         settings.enableBackgroundInvestigation ?? true,