fix(core): opt doc edit prompt (#13054)

> CLOSE AI-304  ## Summary by CodeRabbit * **New Features** * Enhanced document editing to support structured Markdown with identifiable blocks, enabling precise block-level insert, replace, or delete operations. * Improved parameter descriptions and formatting guidance for clearer and more accurate edits. * **Refactor** * Updated parameter names and descriptions for improved clarity. * Changed output format for edited content to provide clearer results.
2026-07-26 14:58:55 +08:00 · 2025-07-07 15:05:14 +08:00
parent 3b8ae496dc
commit 5a81c0ab98
1 changed files with 85 additions and 6 deletions
@@ -27,30 +27,109 @@ export const createDocEditTool = (
  getContent: (targetId?: string) => Promise<string | undefined>
 ) => {
  return tool({
-    description:
-      "Use this tool to propose an edit to an existing doc. Each of your edit will only be applied to the document after the user’s approval. This tool will return a preview of your edit as applied to the document.\n\nThis will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.\nWhen writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.\n\nYou should bias towards repeating as few lines of the original doc as possible to convey the change.\nEach edit should contain sufficient context of unchanged lines around the code you're editing to resolve ambiguity.\nIf you plan on deleting a section, you must provide surrounding context to indicate the deletion.\nDO NOT omit spans of pre-existing code without using the // ... existing code ... comment to indicate its absence.\n\nYou should specify the following arguments before the others: [target_id], [origin_content]",
+    description: `
+Use this tool to propose an edit to a structured Markdown document with identifiable blocks. Each block begins with a comment like <!-- block_id=... -->, and represents a unit of editable content such as a heading, paragraph, list, or code snippet.
+This will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.
+
+Your task is to return a list of block-level changes needed to fulfill the user's intent. Each change should correspond to a specific user instruction and be represented by one of the following operations:
+
+replace: Replace the content of a block with updated Markdown.
+
+delete: Remove a block entirely.
+
+insert: Add a new block, and specify its block_id and content.
+
+Important Instructions:
+- Use the existing block structure as-is. Do not reformat or reorder blocks unless explicitly asked.
+- Always preserve block_id and type in your replacements.
+- When replacing a block, use the full new block including <!-- block_id=... type=... --> and the updated content.
+- When inserting, follow the same format as a replacement, but ensure the new block_id does not conflict with existing IDs.
+- Each list item should be a block.
+- Use <!-- existing blocks ... --> for unchanged sections.
+- If you plan on deleting a section, you must provide surrounding context to indicate the deletion.
+
+Example Input Document:
+\`\`\`md
+<!-- block_id=block-001 type=h1 -->
+# My Holiday Plan
+
+<!-- block_id=block-002 type=paragraph -->
+I plan to travel to Paris, France, where I will visit the Eiffel Tower, the Louvre, and the Champs-Élysées.
+
+<!-- block_id=block-003 type=paragraph -->
+I love Paris.
+
+<!-- block_id=block-004 type=paragraph -->
+This plan has been brewing for a long time, but I always postponed it because I was too busy with work.
+
+<!-- block_id=block-005 type=paragraph -->
+- Book flight tickets
+- Reserve a hotel
+- Prepare visa documents
+- Plan the itinerary
+
+<!-- block_id=block-006 type=paragraph -->
+Additionally, I plan to learn some basic French to make communication easier during the trip.
+\`\`\`
+
+Example User Request:
+
+\`\`\`
+Translate the trip steps to Chinese, remove the reason for the delay, and bold the final paragraph.
+\`\`\`
+
+Expected Output:
+
+\`\`\`md
+<!-- existing blocks ... -->
+
+<!-- block_id=block-002 type=paragraph -->
+I plan to travel to Paris, France, where I will visit the Eiffel Tower, the Louvre, and the Champs-Élysées.
+
+<!-- block_id=block-003 type=paragraph -->
+I love Paris.
+
+<!-- delete block-004 -->
+
+<!-- block_id=block-005 type=paragraph -->
+- 订机票
+- 预定酒店
+- 准备签证材料
+- 规划行程
+
+<!-- existing blocks ... -->
+
+<!-- block_id=block-006 type=paragraph -->
+**Additionally, I plan to learn some basic French to make communication easier during the trip.**
+\`\`\`
+You should specify the following arguments before the others: [doc_id], [origin_content]
+
+    `,
    parameters: z.object({
      doc_id: z
        .string()
        .describe(
-          'The target doc to modify. Always specify the target doc as the first argument. If the content to be modified does not include a specific document, the full text should be provided through origin_content.'
+          'The unique ID of the document being edited. Required when editing an existing document stored in the system. If you are editing ad-hoc Markdown content instead, leave this empty and use origin_content.'
        )
        .optional(),
+
      origin_content: z
        .string()
        .describe(
-          'The original content of the doc you are editing. If the original text is from a specific document, the target_id should be provided instead of this parameter.'
+          'The full original Markdown content, including all block_id comments (e.g., <!-- block_id=block-001 type=paragraph -->). Required when doc_id is not provided. This content will be parsed into discrete editable blocks.'
        )
        .optional(),
+
      instructions: z
        .string()
        .describe(
-          'A single sentence instruction describing what you are going to do for the sketched edit. This is used to assist the less intelligent model in applying the edit. Please use the first person to describe what you are going to do. Dont repeat what you have said previously in normal messages. And use it to disambiguate uncertainty in the edit.'
+          'A short, first-person description of the intended edit, clearly summarizing what I will change. For example: "I will translate the steps into English and delete the paragraph explaining the delay." This helps the downstream system understand the purpose of the changes.'
        ),
+
      code_edit: z
        .string()
        .describe(
-          "Specify ONLY the precise lines of code that you wish to edit. NEVER specify or write out unchanged code. Instead, represent all unchanged code using the comment of the language you're editing in - example: // ... existing code ..."
+          'Specify only the necessary Markdown block-level changes. Return a list of inserted, replaced, or deleted blocks. Each block must start with its <!-- block_id=... type=... --> comment. Use <!-- existing blocks ... --> for unchanged sections.If you plan on deleting a section, you must provide surrounding context to indicate the deletion.'
        ),
    }),
    execute: async ({ doc_id, origin_content, code_edit }) => {