feat(examples): add plan-notebook web application example (#204)

Author: LearningGp

agentscope-core/src/main/java/io/agentscope/core/plan/PlanNotebook.java

@@ -81,14 +81,16 @@
  * agent.call(msg).block();
  * }</pre>
  *
- * <p><b>Tool Functions:</b> PlanNotebook provides 8 tool functions:
+ * <p><b>Tool Functions:</b> PlanNotebook provides 10 tool functions:
  *
  * <ul>
  *   <li>{@link #createPlan} - Create a new plan
+ *   <li>{@link #updatePlanInfo} - Update current plan's name, description, or expected outcome
  *   <li>{@link #reviseCurrentPlan} - Add, revise, or delete subtasks
  *   <li>{@link #updateSubtaskState} - Update subtask state
  *   <li>{@link #finishSubtask} - Mark subtask as done
  *   <li>{@link #viewSubtasks} - View subtask details
+ *   <li>{@link #getSubtaskCount} - Get the number of subtasks in current plan
  *   <li>{@link #finishPlan} - Finish or abandon plan
  *   <li>{@link #viewHistoricalPlans} - View historical plans
  *   <li>{@link #recoverHistoricalPlan} - Recover a historical plan
@@ -110,12 +112,14 @@ public class PlanNotebook {
     private final PlanToHint planToHint;
     private final PlanStorage storage;
     private final Integer maxSubtasks;
+    private final boolean needUserConfirm;
     private final Map<String, BiConsumer<PlanNotebook, Plan>> changeHooks;
 
     private PlanNotebook(Builder builder) {
         this.planToHint = builder.planToHint;
         this.storage = builder.storage;
         this.maxSubtasks = builder.maxSubtasks;
+        this.needUserConfirm = builder.needUserConfirm;
         this.changeHooks = new ConcurrentHashMap<>();
     }
 
@@ -133,6 +137,7 @@ public static class Builder {
         private PlanToHint planToHint = new DefaultPlanToHint();
         private PlanStorage storage = new InMemoryPlanStorage();
         private Integer maxSubtasks = null;
+        private boolean needUserConfirm = true;
 
         /**
          * Sets the strategy for converting plans to hints.
@@ -167,6 +172,22 @@ public Builder maxSubtasks(int maxSubtasks) {
             return this;
         }
 
+        /**
+         * Sets whether to include "wait for user confirmation" rule in hints.
+         *
+         * <p>When enabled (default), hints will include a rule requiring the agent to wait for
+         * explicit user confirmation before executing plans. When disabled, the agent may proceed
+         * with execution immediately after creating a plan.
+         *
+         * @param needUserConfirm true to require user confirmation, false to allow immediate
+         *     execution
+         * @return This builder for method chaining
+         */
+        public Builder needUserConfirm(boolean needUserConfirm) {
+            this.needUserConfirm = needUserConfirm;
+            return this;
+        }
+
         /**
          * Builds a new PlanNotebook with the configured settings.
          *
@@ -245,6 +266,77 @@ public Mono<String> createPlan(
         return triggerPlanChangeHooks().thenReturn(message);
     }
 
+    /**
+     * Update the current plan's name, description, or expected outcome.
+     *
+     * @param name The new plan name (optional, pass null or empty to keep unchanged)
+     * @param description The new plan description (optional, pass null or empty to keep unchanged)
+     * @param expectedOutcome The new expected outcome (optional, pass null or empty to keep
+     *     unchanged)
+     * @return Tool response message
+     */
+    @Tool(
+            name = "update_plan_info",
+            description =
+                    "Update the current plan's name, description, or expected outcome. Pass null or"
+                            + " empty string to keep a field unchanged.")
+    public Mono<String> updatePlanInfo(
+            @ToolParam(
+                            name = "name",
+                            description =
+                                    "The new plan name (optional, pass null or empty to keep"
+                                            + " unchanged)")
+                    String name,
+            @ToolParam(
+                            name = "description",
+                            description =
+                                    "The new plan description (optional, pass null or empty to keep"
+                                            + " unchanged)")
+                    String description,
+            @ToolParam(
+                            name = "expected_outcome",
+                            description =
+                                    "The new expected outcome (optional, pass null or empty to keep"
+                                            + " unchanged)")
+                    String expectedOutcome) {
+
+        validateCurrentPlan();
+
+        StringBuilder changes = new StringBuilder();
+
+        if (name != null && !name.trim().isEmpty()) {
+            String oldName = currentPlan.getName();
+            currentPlan.setName(name.trim());
+            changes.append(String.format("name: '%s' -> '%s'", oldName, name.trim()));
+        }
+
+        if (description != null && !description.trim().isEmpty()) {
+            currentPlan.setDescription(description.trim());
+            if (!changes.isEmpty()) {
+                changes.append(", ");
+            }
+            changes.append("description updated");
+        }
+
+        if (expectedOutcome != null && !expectedOutcome.trim().isEmpty()) {
+            currentPlan.setExpectedOutcome(expectedOutcome.trim());
+            if (!changes.isEmpty()) {
+                changes.append(", ");
+            }
+            changes.append("expected_outcome updated");
+        }
+
+        if (changes.isEmpty()) {
+            return Mono.just("No changes were made. Please provide at least one field to update.");
+        }
+
+        return triggerPlanChangeHooks()
+                .thenReturn(
+                        String.format(
+                                "Plan '%s' updated successfully: %s.",
+                                currentPlan.getName(), changes));
+    }
+
     /**
      * Create a plan with SubTask objects (convenience method for tests and Java code).
      *
@@ -604,6 +696,47 @@ public Mono<String> viewSubtasks(
         return Mono.just(sb.toString());
     }
 
+    /**
+     * Get the number of subtasks in the current plan.
+     *
+     * @return Tool response message with subtask count
+     */
+    @Tool(
+            name = "get_subtask_count",
+            description = "Get the number of subtasks in the current plan")
+    public Mono<String> getSubtaskCount() {
+        if (currentPlan == null) {
+            return Mono.just("There is no active plan. Please create a plan first.");
+        }
+
+        List<SubTask> subtasks = currentPlan.getSubtasks();
+        if (subtasks == null || subtasks.isEmpty()) {
+            return Mono.just(
+                    String.format("Current plan '%s' has 0 subtask(s).", currentPlan.getName()));
+        }
+
+        int total = subtasks.size();
+        int done = 0;
+        int inProgress = 0;
+        int todo = 0;
+        int abandoned = 0;
+
+        for (SubTask subtask : subtasks) {
+            switch (subtask.getState()) {
+                case DONE -> done++;
+                case IN_PROGRESS -> inProgress++;
+                case TODO -> todo++;
+                case ABANDONED -> abandoned++;
+            }
+        }
+
+        return Mono.just(
+                String.format(
+                        "Current plan '%s' has %d subtask(s): %d done, %d in_progress, %d todo, %d"
+                                + " abandoned.",
+                        currentPlan.getName(), total, done, inProgress, todo, abandoned));
+    }
+
     /**
      * Finish the current plan by given outcome, or abandon it.
      *
@@ -763,7 +896,7 @@ public Mono<String> recoverHistoricalPlan(
      *     applicable
      */
     public Mono<Msg> getCurrentHint() {
-        String hintContent = planToHint.generateHint(currentPlan);
+        String hintContent = planToHint.generateHint(currentPlan, needUserConfirm);
         if (hintContent != null && !hintContent.isEmpty()) {
             return Mono.just(
                     Msg.builder()
@@ -784,6 +917,15 @@ public Plan getCurrentPlan() {
         return currentPlan;
     }
 
+    /**
+     * Checks if user confirmation is required before executing plans.
+     *
+     * @return true if user confirmation is required, false otherwise
+     */
+    public boolean isNeedUserConfirm() {
+        return needUserConfirm;
+    }
+
     private Mono<Void> triggerPlanChangeHooks() {
         return Flux.fromIterable(changeHooks.values())
                 .flatMap(hook -> Mono.fromRunnable(() -> hook.accept(this, currentPlan)))

agentscope-core/src/main/java/io/agentscope/core/plan/hint/DefaultPlanToHint.java

@@ -40,31 +40,57 @@ public class DefaultPlanToHint implements PlanToHint {
 
     private static final String HINT_PREFIX = "<system-hint>";
     private static final String HINT_SUFFIX = "</system-hint>";
+    private static final String IMPORTANT_RULES_SEPARATOR = "Important Rules: \n";
+
+    private static final String RULE_WAIT_FOR_CONFIRMATION =
+            "⚠️ CRITICAL - WAIT FOR USER CONFIRMATION:\n"
+                    + "You MUST NOT execute any subtask until the user explicitly confirms.\n"
+                    + "- DO NOT call 'update_subtask_state' to start execution\n"
+                    + "- DO NOT proceed with any task in the plan\n"
+                    + "- ONLY present the plan and ASK user: \"Should I proceed with this plan?\"\n"
+                    + "- Wait for explicit commands like: \"execute\", \"go ahead\", \"start\","
+                    + " \"proceed\", \"yes\", \"ok\", \"do it\", \"run\", \"begin\"\n"
+                    + "- If user says anything else (questions, modifications, unrelated topics),"
+                    + " respond accordingly but DO NOT start execution\n"
+                    + "- VIOLATION of this rule is a critical error\n";
+
+    private static final String RULE_COMMON =
+            "- Update before processing each subtask: When processing each subtask, call"
+                + " get_subtask_count and view_subtasks to confirm the latest information:"
+                + " get_subtask_count is used to confirm the total number of subtasks to avoid"
+                + " omissions;view_subtasks is used to query subtask information, execute subtasks"
+                + " strictly according to the latest information, and pay attention to ignoring the"
+                + " original request.\n"
+                + "- User May Modify Plan: Users can directly add, edit, or delete subtasks without"
+                + " going through you.\n"
+                + "- Only focus on the current content: Always follow the latest plan content,"
+                + " especially when the original plan conflicts with the latest queried plan,"
+                + " follow the latest queried plan without considering the initial requirements.\n"
+                + "- Do not modify plan: Do not modify or amend the plan without a clear plan"
+                + " modification instruction from user\n";
 
     private static final String NO_PLAN =
-            "If the user's query is complex (e.g. programming a website, game or "
-                    + "app), or requires a long chain of steps to complete (e.g. conduct "
-                    + "research on a certain topic from different sources), you NEED to "
-                    + "create a plan first by calling 'create_plan'. Otherwise, you can "
-                    + "directly execute the user's query without planning.";
+            "If the user's query is complex (e.g. programming a website, game or app), or requires"
+                    + " a long chain of steps to complete (e.g. conduct research on a certain topic"
+                    + " from different sources), you NEED to create a plan first by calling"
+                    + " 'create_plan'. Otherwise, you can directly execute the user's query without"
+                    + " planning.\n";
 
     private static final String AT_THE_BEGINNING =
             "The current plan:\n"
-                    + "```\n"
-                    + "{plan}\n"
-                    + "```\n"
-                    + "Your options include:\n"
-                    + "- Mark the first subtask as 'in_progress' by calling "
-                    + "'update_subtask_state' with subtask_idx=0 and state='in_progress', "
-                    + "and start executing it.\n"
-                    + "- If the first subtask is not executable, analyze why and what you "
-                    + "can do to advance the plan, e.g. ask user for more information, "
-                    + "revise the plan by calling 'revise_current_plan'.\n"
-                    + "- If the user asks you to do something unrelated to the plan, "
-                    + "prioritize the completion of user's query first, and then return "
-                    + "to the plan afterward.\n"
-                    + "- If the user no longer wants to perform the current plan, confirm "
-                    + "with the user and call the 'finish_plan' function.\n";
+                + "```\n"
+                + "{plan}\n"
+                + "```\n"
+                + "Your options include:\n"
+                + "- Mark the first subtask as 'in_progress' by calling 'update_subtask_state' with"
+                + " subtask_idx=0 and state='in_progress', and start executing it.\n"
+                + "- If the first subtask is not executable, analyze why and what you can do to"
+                + " advance the plan, e.g. ask user for more information, revise the plan by"
+                + " calling 'revise_current_plan'.\n"
+                + "- If the user asks you to do something unrelated to the plan, prioritize the"
+                + " completion of user's query first, and then return to the plan afterward.\n"
+                + "- If the user no longer wants to perform the current plan, confirm with the user"
+                + " and call the 'finish_plan' function.\n";
 
     private static final String WHEN_A_SUBTASK_IN_PROGRESS =
             "The current plan:\n"
@@ -84,7 +110,7 @@ public class DefaultPlanToHint implements PlanToHint {
                     + "- Revise the plan by calling 'revise_current_plan' if necessary.\n"
                     + "- If the user asks you to do something unrelated to the plan, "
                     + "prioritize the completion of user's query first, and then return to "
-                    + "the plan afterward.";
+                    + "the plan afterward.\n";
 
     private static final String WHEN_NO_SUBTASK_IN_PROGRESS =
             "The current plan:\n"
@@ -99,7 +125,7 @@ public class DefaultPlanToHint implements PlanToHint {
                     + "- Revise the plan by calling 'revise_current_plan' if necessary.\n"
                     + "- If the user asks you to do something unrelated to the plan, "
                     + "prioritize the completion of user's query first, and then return to "
-                    + "the plan afterward.";
+                    + "the plan afterward.\n";
 
     private static final String AT_THE_END =
             "The current plan:\n"
@@ -112,7 +138,7 @@ public class DefaultPlanToHint implements PlanToHint {
                     + "- Revise the plan by calling 'revise_current_plan' if necessary.\n"
                     + "- If the user asks you to do something unrelated to the plan, "
                     + "prioritize the completion of user's query first, and then return to "
-                    + "the plan afterward.";
+                    + "the plan afterward.\n";
 
     /**
      * Generates a contextual hint message based on the current plan state.
@@ -128,15 +154,20 @@ public class DefaultPlanToHint implements PlanToHint {
      * </ul>
      *
      * @param plan The current plan, or null if no plan exists
+     * @param needUserConfirm Whether to include the "wait for user confirmation" rule in hints
      * @return A formatted hint message wrapped in system-hint tags, or null if no hint is
      *     applicable
      */
     @Override
-    public String generateHint(Plan plan) {
+    public String generateHint(Plan plan, boolean needUserConfirm) {
         String hint;
+        String confirmationRule = needUserConfirm ? RULE_WAIT_FOR_CONFIRMATION : "";
 
         if (plan == null) {
-            hint = NO_PLAN;
+            hint =
+                    needUserConfirm
+                            ? NO_PLAN + IMPORTANT_RULES_SEPARATOR + confirmationRule
+                            : NO_PLAN;
         } else {
             // Count subtasks by state
             int nTodo = 0;
@@ -166,7 +197,11 @@ public String generateHint(Plan plan) {
 
             } else if (nInProgress == 0 && nDone == 0) {
                 // All subtasks are todo - at the beginning
-                hint = AT_THE_BEGINNING.replace("{plan}", plan.toMarkdown(false));
+                hint =
+                        AT_THE_BEGINNING.replace("{plan}", plan.toMarkdown(false))
+                                + IMPORTANT_RULES_SEPARATOR
+                                + confirmationRule
+                                + RULE_COMMON;
 
             } else if (nInProgress > 0 && inProgressIdx != null) {
                 // One subtask is in_progress
@@ -177,17 +212,21 @@ public String generateHint(Plan plan) {
                 }
                 hint =
                         WHEN_A_SUBTASK_IN_PROGRESS
-                                .replace("{plan}", plan.toMarkdown(false))
-                                .replace("{subtask_idx}", String.valueOf(inProgressIdx))
-                                .replace("{subtask_name}", subtaskName)
-                                .replace("{subtask}", inProgressSubtask.toMarkdown(true));
+                                        .replace("{plan}", plan.toMarkdown(false))
+                                        .replace("{subtask_idx}", String.valueOf(inProgressIdx))
+                                        .replace("{subtask_name}", subtaskName)
+                                        .replace("{subtask}", inProgressSubtask.toMarkdown(true))
+                                + IMPORTANT_RULES_SEPARATOR
+                                + RULE_COMMON;
 
             } else if (nInProgress == 0 && nDone > 0) {
                 // No subtask is in_progress, and some subtasks are done
                 hint =
                         WHEN_NO_SUBTASK_IN_PROGRESS
-                                .replace("{plan}", plan.toMarkdown(false))
-                                .replace("{index}", String.valueOf(nDone));
+                                        .replace("{plan}", plan.toMarkdown(false))
+                                        .replace("{index}", String.valueOf(nDone))
+                                + IMPORTANT_RULES_SEPARATOR
+                                + RULE_COMMON;
 
             } else {
                 // No relevant hint for this state