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

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.8.15-beta.13](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.12...v0.8.15-beta.13) (2025-11-05)
+
+
+### Bug Fixes
+
+* make paid deployment more smooth stable ([#266](https://github.com/AIGNE-io/aigne-doc-smith/issues/266)) ([ce8c00a](https://github.com/AIGNE-io/aigne-doc-smith/commit/ce8c00ab3eb045c482e07dc3c4e3bd149e754a06))
+* validate docsDir on init and ensure latest doc on view after publish ([#267](https://github.com/AIGNE-io/aigne-doc-smith/issues/267)) ([e45864d](https://github.com/AIGNE-io/aigne-doc-smith/commit/e45864da4a7fb5b09af2bbffdb7ca93abd74397c))
+
+## [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/init/index.mjs

@@ -21,6 +21,7 @@ import {
   validatePath,
 } from "../../utils/utils.mjs";
 import { isRemoteFile } from "../../utils/file-utils.mjs";
+import { validateDocDir } from "./validate.mjs";
 
 const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
 
@@ -64,7 +65,19 @@ export default async function init(
     // Only skip if file exists AND has non-empty content
     if (configContent && configContent.trim() !== "") {
       // load config from file
-      return loadConfig({ config: filePath, appUrl });
+      const config = await loadConfig({ config: filePath, appUrl });
+      const isValid = validateDocDir(config.docsDir);
+      if (typeof isValid === "string") {
+        console.log(
+          `${chalk.red("Invalid docsDir")}: ${isValid}\nPlease check your configuration.`,
+        );
+        process.exit(1);
+      }
+      if (!isValid) {
+        console.log(`${chalk.red("Invalid docsDir")}, please check your configuration.`);
+        process.exit(1);
+      }
+      return config;
     }
   }
 
@@ -241,6 +254,7 @@ export default async function init(
   const docsDirInput = await options.prompts.input({
     message: `📁 [7/9]: Where should we save your documentation?`,
     default: `${outputPath}/docs`,
+    validate: validateDocDir,
   });
   input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
 

package/agents/init/validate.mjs

@@ -0,0 +1,16 @@
+import path from "node:path";
+export function validateDocDir(input) {
+  const currentDir = process.cwd();
+  const targetDir = path.resolve(input);
+  const relativePath = path.relative(currentDir, targetDir);
+  if (relativePath.length === 0) {
+    return `Can't use current directory: ${targetDir}`;
+  }
+  if (relativePath.startsWith("..")) {
+    return `Can't use directory outside current directory: ${targetDir}`;
+  }
+  if (path.isAbsolute(relativePath)) {
+    return `Can't use absolute path: ${targetDir}`;
+  }
+  return true;
+}

package/agents/publish/publish-docs.mjs

@@ -163,8 +163,13 @@ export default async function publishDocs(
           } else {
             console.log(`\nCreating a new website for your documentation...`);
           }
-          const { appUrl: homeUrl, token: ltToken } = (await deploy(id, paymentLink)) || {};
+          const {
+            appUrl: homeUrl,
+            token: ltToken,
+            sessionId: newSessionId,
+          } = (await deploy(id, paymentLink)) || {};
 
+          sessionId = newSessionId;
           appUrl = homeUrl;
           token = ltToken;
         } catch (error) {
@@ -174,13 +179,7 @@ export default async function publishDocs(
       }
     }
 
-    if (sessionId) {
-      authToken = await getOfficialAccessToken(BASE_URL, false);
-      client = client || new BrokerClient({ baseUrl: BASE_URL, authToken });
-
-      const { vendors } = await client.getSessionDetail(sessionId, false);
-      token = vendors?.find((vendor) => vendor.vendorType === "launcher" && vendor.token)?.token;
-    }
+    appUrl = appUrl ?? CLOUD_SERVICE_URL_PROD;
 
     console.log(`\nPublishing your documentation to ${chalk.cyan(appUrl)}\n`);
 
@@ -264,8 +263,10 @@ export default async function publishDocs(
       await saveValueToConfig("shouldSyncBranding", "", "Should sync branding for documentation");
     } else {
       // If the error is 401 or 403, it means the access token is invalid
-      if (error?.includes("401") || error?.includes("403")) {
+      if (error?.includes("401")) {
         message = `❌ Publishing failed due to an authorization error. Please run ${chalk.cyan("aigne doc clear")} to reset your credentials and try again.`;
+      } else if (error?.includes("403")) {
+        message = `❌ Publishing failed due to an authorization error. \n  - Please confirm you have permission to modify this document [boardId: "${newBoardId || boardId}"]. \n  - Or run ${chalk.cyan("aigne doc clear")} to reset your credentials and try again.`;
       }
     }
 

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/update/user-review-document.mjs

@@ -208,13 +208,14 @@ export default async function userReviewDocument({ content, description, ...rest
 
     try {
       // Call updateDocument agent with feedback
-      await options.context.invoke(updateAgent, {
+      const result = await options.context.invoke(updateAgent, {
         ...rest,
         originalContent: options.context.userContext.currentContent,
         feedback: feedback.trim(),
         userPreferences,
         title,
       });
+      options.context.userContext.currentContent = result.content;
 
       // Check if feedback should be saved as user preference
       const feedbackRefinerAgent = options.context.agents["checkFeedbackRefiner"];

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.13",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -24,14 +24,14 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "Elastic-2.0",
   "dependencies": {
-    "@aigne/aigne-hub": "^0.10.0",
-    "@aigne/anthropic": "^0.14.0",
-    "@aigne/cli": "^1.49.1",
-    "@aigne/core": "^1.61.0",
-    "@aigne/gemini": "^0.14.0",
-    "@aigne/openai": "^0.16.0",
+    "@aigne/aigne-hub": "^0.10.5-beta.3",
+    "@aigne/anthropic": "^0.14.5-beta.3",
+    "@aigne/cli": "^1.53.1-beta.4",
+    "@aigne/core": "^1.65.1-beta.3",
+    "@aigne/gemini": "^0.14.5-beta.3",
+    "@aigne/openai": "^0.16.5-beta.3",
     "@aigne/publish-docs": "^0.12.0",
-    "@blocklet/payment-broker-client": "^1.21.10",
+    "@blocklet/payment-broker-client": "^1.22.7",
     "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
     "cli-highlight": "^2.1.11",

package/prompts/detail/custom/custom-code-block.md

@@ -18,6 +18,11 @@ The following are the available enhanced attributes and their descriptions:
   * `language` and `title` are written directly after \`\`\`, separated by spaces.
   * Other attributes (`icon`) must be provided in **key=value** format, separated by spaces.
 
+### Special Rules
+- If the language is a shell (includes `sh`, `bash`, `zsh`, etc.):
+  - Executable shell code blocks must be a single-line command to make copying and running easier.
+  - Do not include comments inside executable shell code blocks; place explanatory comments outside the code block.
+
 ### Examples
 
 <code_block_good_examples>
@@ -70,9 +75,26 @@ class ShoppingCart {
   }
 }
 ```
+
+**Example 5: Shell code block should in one line**
+
+```sh Install aigne deps icon=lucide:terminal
+npm i -g @aigne/cli @aigne/doc-smith @aigne/websmith-smith
+```
+
+**Example 6: Shell code block use `\` to split multiple lines**
+```bash Deploying with Access Keys icon=lucide:terminal
+blocklet deploy . \
+  --endpoint https://my-server.arcblock.io \
+  --access-key 'your_access_key_id' \
+  --access-secret 'your_access_key_secret' \
+  --app-id z2qa9sD2tFAP8gM7C1i8iETg3a1T3A3aT3bQ
+```
+
 </code_block_good_examples>
 
 <code_block_bad_examples>
+
 **Example 1**
 
 There are two errors in this example:
@@ -97,5 +119,18 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
+**Example 2: shell code block have multiple lines**
+```sh
+npm i -g @aigne/cli
+npm i -g @aigne/doc-smith
+npm i -g @aigne/websmith-smith
+```
+
+**Example 3: shell code block comments**
+```sh
+# add aigne deps
+npm i -g @aigne/cli
+```
+
 </code_block_bad_examples>
-</enhanced_code_block_rules>
+</enhanced_code_block_rules>

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>

package/utils/deploy.mjs

@@ -71,7 +71,7 @@ export async function deploy(id, cachedUrl) {
     },
   });
 
-  const { appUrl, homeUrl, subscriptionUrl, dashboardUrl, vendors } = result;
+  const { appUrl, homeUrl, subscriptionUrl, dashboardUrl, vendors, sessionId } = result;
   const token = vendors?.[0]?.token;
 
   return {
@@ -80,5 +80,6 @@ export async function deploy(id, cachedUrl) {
     dashboardUrl,
     subscriptionUrl,
     token,
+    sessionId,
   };
 }