@aigne/doc-smith 0.8.15-beta.11 → 0.8.15-beta.12

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.8.15-beta.12](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.11...v0.8.15-beta.12) (2025-11-05)
+
+
+### Features
+
+* tune token consumption for update ops with intent analysis ([#264](https://github.com/AIGNE-io/aigne-doc-smith/issues/264)) ([8c53d28](https://github.com/AIGNE-io/aigne-doc-smith/commit/8c53d288346ae622e8841866db1b6fbed9d5023d))
+
 ## [0.8.15-beta.11](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.10...v0.8.15-beta.11) (2025-11-04)
 
 

package/agents/generate/update-document-structure.yaml

@@ -1,48 +1,54 @@
-type: ai
+type: team
 name: updateDocumentStructure
 description: Update documentation structure based on user feedback and intentions using structure modification tools
-instructions:
-  - role: system
-    url: ../../prompts/structure/update/system-prompt.md
-  - role: user
-    url: ../../prompts/structure/update/user-prompt.md
-input_schema:
-  type: object
-  properties:
-    documentStructure: ../schema/document-structure.yaml
-    rules:
-      type: string
-      description: User configuration rules
-    locale:
-      type: string
-      description: User language, e.g. zh, en
-    dataSourceChunk:
-      type: string
-      description: Context for documentation structure
-    glossary:
-      type: string
-      description: Glossary of terms
-    feedback:
-      type: string
-      description: User feedback for structure modifications
-    userPreferences:
-      type: string
-      description: Your saved preferences for structure and documentation style
-  required:
-    - documentStructure
-    - feedback
-output_key: message
-afs:
-  modules:
-    - module: system-fs
-      options:
-        mount: /sources
-        path: .
-        description: |
-          Codebase of the project to be documented used as context for document generation,
-          should search and read as needed while generating document content
 skills:
-  - ./document-structure-tools/add-document.mjs
-  - ./document-structure-tools/delete-document.mjs
-  - ./document-structure-tools/update-document.mjs
-  - ./document-structure-tools/move-document.mjs
+  - url: ../utils/analyze-feedback-intent.yaml
+  - type: ai
+    instructions:
+      - role: system
+        url: ../../prompts/structure/update/system-prompt.md
+      - role: user
+        url: ../../prompts/structure/update/user-prompt.md
+    input_schema:
+      type: object
+      properties:
+        documentStructure: ../schema/document-structure.yaml
+        rules:
+          type: string
+          description: User configuration rules
+        locale:
+          type: string
+          description: User language, e.g. zh, en
+        dataSourceChunk:
+          type: string
+          description: Context for documentation structure
+        glossary:
+          type: string
+          description: Glossary of terms
+        feedback:
+          type: string
+          description: User feedback for structure modifications
+        userPreferences:
+          type: string
+          description: Your saved preferences for structure and documentation style
+        needDataSources:
+          type: boolean
+          description: Whether data sources are needed for content modifications
+      required:
+        - documentStructure
+        - feedback
+    output_key: message
+    afs:
+      modules:
+        - module: system-fs
+          options:
+            mount: /sources
+            path: .
+            description: |
+              Codebase of the project to be documented used as context for document generation,
+              should search and read as needed while generating document content
+    skills:
+      - ./document-structure-tools/add-document.mjs
+      - ./document-structure-tools/delete-document.mjs
+      - ./document-structure-tools/update-document.mjs
+      - ./document-structure-tools/move-document.mjs

package/agents/update/update-document-detail.yaml

@@ -1,61 +1,67 @@
-type: ai
+type: team
 name: updateDocumentDetail
 description: Update and optimize document content based on user feedback using diff patches
-instructions:
-  - role: system
-    url: ../../prompts/detail/update/system-prompt.md
-  - role: user
-    url: ../../prompts/detail/update/user-prompt.md
-auto_reorder_system_messages: true
-auto_merge_system_messages: true
-input_schema:
-  type: object
-  properties:
-    originalContent:
-      type: string
-      description: Original markdown content to be updated
-    feedback:
-      type: string
-      description: User feedback for content improvements
-    rules:
-      type: string
-      description: User configuration rules
-    locale:
-      type: string
-      description: User language, e.g. zh, en
-    detailDataSource:
-      type: string
-      description: Context for document content
-    glossary:
-      type: string
-      description: Glossary of terms
-    userPreferences:
-      type: string
-      description: User's saved preferences for content and documentation style
-    targetAudience:
-      type: string
-      description: Target audience for the documentation
-    title:
-      type: string
-      description: Document title
-    description:
-      type: string
-      description: Document description
-  required:
-    - originalContent
-    - feedback
-output_key: message
-afs:
-  modules:
-    - module: system-fs
-      options:
-        mount: /sources
-        path: .
-        description: |
-          Codebase of the project to be documented used as context for document generation,
-          should search and read as needed while generating document content
-keep_text_in_tool_uses: false
-skills:
-  - ./document-tools/update-document-content.mjs
-  # - ./generate-diagram.yaml
 task_render_mode: collapse
+skills:
+  - url: ../utils/analyze-feedback-intent.yaml
+  - type: ai
+    instructions:
+      - role: system
+        url: ../../prompts/detail/update/system-prompt.md
+      - role: user
+        url: ../../prompts/detail/update/user-prompt.md
+    auto_reorder_system_messages: true
+    auto_merge_system_messages: true
+    input_schema:
+      type: object
+      properties:
+        originalContent:
+          type: string
+          description: Original markdown content to be updated
+        feedback:
+          type: string
+          description: User feedback for content improvements
+        rules:
+          type: string
+          description: User configuration rules
+        locale:
+          type: string
+          description: User language, e.g. zh, en
+        detailDataSource:
+          type: string
+          description: Context for document content
+        glossary:
+          type: string
+          description: Glossary of terms
+        userPreferences:
+          type: string
+          description: User's saved preferences for content and documentation style
+        targetAudience:
+          type: string
+          description: Target audience for the documentation
+        title:
+          type: string
+          description: Document title
+        description:
+          type: string
+          description: Document description
+        needDataSources:
+          type: boolean
+          description: Whether data sources are needed for content modifications
+      required:
+        - originalContent
+        - feedback
+    output_key: message
+    afs:
+      modules:
+        - module: system-fs
+          options:
+            mount: /sources
+            path: .
+            description: |
+              Codebase of the project to be documented used as context for document generation,
+              should search and read as needed while generating document content
+    keep_text_in_tool_uses: false
+    skills:
+      - ./document-tools/update-document-content.mjs
+      # - ./generate-diagram.yaml

package/agents/utils/analyze-feedback-intent.yaml

@@ -0,0 +1,31 @@
+name: analyzeFeedbackIntent
+description: Analyze user feedback to determine if data sources are needed for content modifications
+model:
+  reasoning_effort: 200
+task_render_mode: hide
+instructions:
+  url: ../../prompts/utils/analyze-feedback-intent.md
+input_schema:
+  type: object
+  properties:
+    feedback:
+      type: string
+      description: User feedback for content modifications
+  required:
+    - feedback
+output_schema:
+  type: object
+  properties:
+    needDataSources:
+      type: boolean
+      description: Whether data sources are needed - true for add/edit operations that need context, false for delete/move/reorder operations
+    intentType:
+      type: string
+      description: The primary type of user intention
+    reason:
+      type: string
+      description: Explanation of why data sources are or aren't needed
+  required:
+    - needDataSources
+    - intentType
+    - reason

package/aigne.yaml

@@ -76,6 +76,7 @@ agents:
   - ./agents/utils/find-item-by-path.mjs
   - ./agents/utils/check-feedback-refiner.mjs
   - ./agents/utils/feedback-refiner.yaml
+  - ./agents/utils/analyze-feedback-intent.yaml
 
   # User Preferences & Chat
   - ./agents/prefs/index.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.15-beta.11",
+  "version": "0.8.15-beta.12",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

package/prompts/detail/update/user-prompt.md

@@ -15,6 +15,7 @@
 {{originalContent}}
 </original_page_content>
 
+{% if needDataSources %}
 <detail_data_source>
 
 {{ detailDataSource }}
@@ -28,6 +29,7 @@
 {% endif %}
 
 </detail_data_source>
+{% endif %}
 
 <user_feedback>
 {{feedback}}

package/prompts/structure/update/system-prompt.md

@@ -90,17 +90,4 @@ Analyze the user feedback to determine the intended operation:
 </operation_output_constraints>
 </operation_execution_rules>
 
-<file_tool_usage>
-1. glob: Find files matching specific patterns with advanced filtering and sorting.
-
-2. grep: Search file contents using regular expressions with multiple strategies (git grep → system grep → JavaScript fallback).
-
-3. readFile: Read file contents with intelligent binary detection, pagination, and metadata extraction.
-
-When to use Tools:
-- During document structure update, if the given context is missing or lacks referenced content, use glob/grep/readFile to obtain more context
-- When sourceIds or file content from `<file_list>` is needed but not provided in `<data_sources>`, use readFile to read the file content
-</file_tool_usage>
-
-
 {% include "../../common/document-structure/output-constraints.md" %}

package/prompts/structure/update/user-prompt.md

@@ -6,10 +6,11 @@
 {{allFilesPaths}}
 </file_list>
 
+{% if needDataSources %}
 <data_sources>
 {{ dataSourceChunk }}
 </data_sources>
-
+{% endif %}
 
 Initial Documentation Structure:
 <initial_document_structure>

package/prompts/utils/analyze-feedback-intent.md

@@ -0,0 +1,55 @@
+<role>
+You are a feedback intent analyzer. Your task is to determine whether data sources are needed to fulfill the user's feedback about content modifications.
+</role>
+
+<input>
+- feedback: {{feedback}}
+</input>
+
+<analysis_rules>
+**Determining Data Source Necessity:**
+
+You need to analyze the user's feedback and categorize it into different intent types. Based on the intent type, determine if data sources are required.
+
+This analyzer is generic and can be used for any content modification scenarios (documentation structure, document content, translations, etc.).
+
+**Intent Types:**
+
+1. **add** - Adding new items, sections, or content
+   - Requires data sources: **YES**
+   - Reason: Need sufficient context from codebase or related materials to generate accurate new content
+
+2. **edit** - Modifying existing content, descriptions, titles, or properties
+   - Requires data sources: **YES**
+   - Reason: Need context to ensure modifications are accurate and contextually appropriate
+
+3. **delete** - Removing items, sections, or content
+   - Requires data sources: **NO**
+   - Reason: Deletion only needs to identify what to remove, no new content generation needed
+
+4. **move** - Moving items to different positions or parent sections
+   - Requires data sources: **NO**
+   - Reason: Only changing item location in the structure, no content changes needed
+
+5. **reorder** - Changing the order of items at the same level
+   - Requires data sources: **NO**
+   - Reason: Only rearranging sequence, no content generation needed
+
+6. **mixed** - Combination of multiple intent types
+   - Requires data sources: **Depends on whether add/edit operations are included**
+   - Reason: If the feedback includes any add or edit operations, data sources are needed
+
+**Decision Logic:**
+- If the feedback contains ANY add or edit operations → `needDataSources = true`
+- If the feedback ONLY contains delete, move, or reorder operations → `needDataSources = false`
+- When in doubt, default to `needDataSources = true` to ensure sufficient context
+</analysis_rules>
+
+<output_rules>
+Return a JSON object with:
+- `needDataSources`: boolean indicating if data sources are required
+- `intentType`: the primary intent type (add, edit, delete, move, reorder, or mixed)
+- `reason`: clear explanation of why data sources are or aren't needed
+
+Analyze the feedback carefully and be conservative - when uncertain, prefer `needDataSources: true` to ensure sufficient context is available.
+</output_rules>