@aigne/doc-smith 0.9.5 → 0.9.6-beta.1

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

@@ -0,0 +1,29 @@
+name: analyzeStructureFeedbackIntent
+description: Analyze user feedback to determine if data sources are needed for structure modifications
+task_render_mode: hide
+instructions:
+  url: ../../prompts/utils/analyze-structure-feedback-intent.md
+input_schema:
+  type: object
+  properties:
+    feedback:
+      type: string
+      description: User feedback for structure 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/agents/utils/check-detail-result.mjs

@@ -1,4 +1,5 @@
 import { checkMarkdown } from "../../utils/markdown-checker.mjs";
+import { buildAllowedLinksFromStructure } from "../../utils/docs-finder-utils.mjs";
 
 export default async function checkDetailResult({ documentStructure, reviewContent, docsDir }) {
   if (!reviewContent || reviewContent.trim() === "") {
@@ -12,20 +13,7 @@ export default async function checkDetailResult({ documentStructure, reviewConte
   const detailFeedback = [];
 
   // Create a set of allowed links, including both original paths and processed .md paths
-  const allowedLinks = new Set();
-  documentStructure.forEach((item) => {
-    // Add original path
-    allowedLinks.add(item.path);
-
-    // Add processed .md path (same logic as processContent in utils.mjs)
-    let processedPath = item.path;
-    if (processedPath.startsWith(".")) {
-      processedPath = processedPath.replace(/^\./, "");
-    }
-    let flatPath = processedPath.replace(/^\//, "").replace(/\//g, "-");
-    flatPath = `./${flatPath}.md`;
-    allowedLinks.add(flatPath);
-  });
+  const allowedLinks = buildAllowedLinksFromStructure(documentStructure);
 
   // Run comprehensive markdown validation with all checks
   try {

package/aigne.yaml

@@ -39,6 +39,7 @@ agents:
   - ./agents/update/check-update-is-single.mjs
   - ./agents/update/save-and-translate-document.mjs
   - ./agents/update/index.yaml
+  - ./agents/update/update-single/update-single-document-detail.mjs
 
 
   # Translation
@@ -67,6 +68,7 @@ agents:
   - ./agents/clear/clear-media-description.mjs
 
   # Utilities
+  - ./agents/utils/add-translates-to-structure.mjs
   - ./agents/utils/load-sources.mjs
   - ./agents/utils/post-generate.mjs
   - ./agents/utils/save-sidebar.mjs
@@ -78,7 +80,8 @@ 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
+  - ./agents/utils/analyze-structure-feedback-intent.yaml
+  - ./agents/utils/analyze-document-feedback-intent.yaml
 
   - ./agents/utils/document-title-streamline.yaml
   - ./agents/utils/streamline-document-titles-if-needed.mjs
@@ -125,6 +128,13 @@ cli:
         - url: ./agents/history/view.mjs
           name: view
           alias: ["log", "list"]
+    - name: add-document
+      alias: ["add"]
+      url: ./agents/create/user-add-document/index.yaml
+    - name: remove-document
+      alias: ["rm"]
+      url: ./agents/create/user-remove-document/index.yaml
+    - ./agents/clear/index.yaml
 mcp_server:
   agents:
     - ./docs-mcp/get-docs-structure.mjs

package/package.json

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

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

@@ -9,6 +9,9 @@ Generate a d2 diagram that represents the following document content:
 <user_rules>
 
 - Output only the diagram labels and text in the {{ locale }} language — keep all variable names, component names, and syntax unchanged.
+{% if previousDiagramContent %}
+- Update the diagram based on `<feedback>` and `<previous_diagram_content>`.
+{% endif %}
 
 </user_rules>
 
@@ -24,3 +27,17 @@ Generate a d2 diagram that represents the following document content:
 
 </diagram_check_feedback>
 {% endif %}
+
+{% if previousDiagramContent %}
+<previous_diagram_content>
+{{ previousDiagramContent }}
+</previous_diagram_content>
+
+{% if feedback %}
+<feedback>
+{{ feedback }}
+</feedback>
+{% endif %}
+
+{% endif %}
+

package/prompts/detail/generate/system-prompt.md

@@ -49,7 +49,6 @@ Documentation content generation rules:
 </content_generation_rules>
 
 
-
 <output_constraints>
 
 1. Output the complete Markdown content for {{nodeName}}, only the content itself—no explanations or extra information.

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

@@ -3,9 +3,35 @@
 </role_and_goal>
 
 
-<document_structure>
-{{ documentStructureYaml }}
-</document_structure>
+<task_instructions>
+Your task is to:
+
+Processing workflow:
+- If user feedback is not in English, translate it to English first to better understand user intent
+- Analyze user feedback to understand the exact intent and scope of changes
+- Generate a unified diff patch that implements the requested improvements
+- Use the available tool to apply the changes and get the final content
+- Tool calls only need to return toolCalls information
+- Ensure all modifications maintain document quality and consistency
+- Return 'success' when the latest version of content meets user feedback(Don't add any explanation)
+
+Tool usage guidelines:
+
+**updateDocumentContent**: Use this tool to apply changes to the document content
+- Generate a precise unified diff patch based on the user feedback
+- Forbidden change diagram source code
+  - If user ask to add/update diagram, use `generateDiagram` tool instead.
+  - If user ask to remove diagram, should remove diagram content and update document context to get better understanding.
+- The diff should include context lines for accurate application
+- Only consider content within `<page_content>` tag when calculating line numbers, ensure line number calculation is accurate
+- Test the patch application to ensure it works correctly
+
+Error handling:
+- If user intent is unclear, ask for clarification
+- If the requested changes conflict with best practices, explain the issues and suggest alternatives
+- If the diff patch fails to apply, revise the approach and try again
+</task_instructions>
+
 
 <current_document>
 Current {{nodeName}} information:
@@ -16,6 +42,11 @@ parentId: {{parentId}}
 </current_document>
 
 
+<document_structure>
+{{ documentStructureYaml }}
+</document_structure>
+
+
 {% if glossary %}
 <terms>
 Glossary of specialized terms. Please ensure correct spelling when using these terms.
@@ -39,7 +70,10 @@ Documentation content optimization rules:
 
 {% include "../../common/document/media-file-list-usage-rules.md" %}
 
-{% include "../diagram/rules.md" %}
+{% include "../../common/document/openapi-usage-rules.md" %}
+
+** Update Constraints: **
+- Forbidden change diagram source code
 
 </content_optimization_rules>
 
@@ -75,37 +109,11 @@ Analyze the user feedback to determine the specific improvements needed:
 
 </feedback_analysis_guidelines>
 
-<task_instructions>
-Your task is to:
-
-Processing workflow:
-- If user feedback is not in English, translate it to English first to better understand user intent
-- Analyze user feedback to understand the exact intent and scope of changes
-- Generate a unified diff patch that implements the requested improvements
-- Use the available tool to apply the changes and get the final content
-- Tool calls only need to return toolCalls information
-- Ensure all modifications maintain document quality and consistency
-- Return 'success' when the latest version of content meets user feedback
-
-Tool usage guidelines:
-
-**updateDocumentContent**: Use this tool to apply changes to the document content
-- Generate a precise unified diff patch based on the user feedback
-- The diff should include context lines for accurate application
-- Only consider content within `<page_content>` tag when calculating line numbers, ensure line number calculation is accurate
-- Test the patch application to ensure it works correctly
-
-Error handling:
-- If user intent is unclear, ask for clarification
-- If the requested changes conflict with best practices, explain the issues and suggest alternatives
-- If the diff patch fails to apply, revise the approach and try again
-</task_instructions>
-
 {% include "../generate/detail-example.md" %}
 
 
-<output_format>
+<output_constraints>
 ** Only output operation execution status **:
 - Only return 'success' if operation executed successfully
 - Return brief error message if operation failed
-</output_format>
+</output_constraints>

package/prompts/structure/find-documents-to-add-links.md

@@ -0,0 +1,52 @@
+# Task: Find Documents to Add Links
+
+Determine which existing documents should link to newly added documents.
+
+## Input
+
+<documentStructure>
+{{originalDocumentStructure}}
+</documentStructure>
+
+<newDocuments>
+{{newDocuments}}
+</newDocuments>
+
+<userFeedback>
+{{allFeedback}}
+</userFeedback>
+
+## Steps
+
+1. **Check <userFeedback> first.**  
+   - If users explicitly specify linking (e.g., “link FAQ from About”), follow exactly.
+2. **Analyze <documentStructure>.**  
+   Identify existing documents that should link to those in <newDocuments> using the rules below.
+3. For each qualifying document, add a non-empty `newLinks` array containing new document paths.
+4. Output only these updated documents (subset of <documentStructure>) as `documentsWithNewLinks`.
+
+Each item in `documentsWithNewLinks` must:
+- Be an existing document from <documentStructure>
+- Retain all original properties (`path`, `title`, `description`, `parentId`, `icon`, `sourceIds`)
+- Include `newLinks: string[]`
+
+## Linking Rules (in priority order)
+
+1. **User Instructions** — Follow explicit <userFeedback>.  
+2. **Parent–Child** — If a new document’s `parentId` equals a document’s `path`, the parent links to it.  
+3. **Semantic Similarity** — Link thematically related documents (e.g., “About” ↔ “Team”).  
+4. **Navigation Context** — Documents in the same navigation group may link.  
+5. **Hierarchy** — Sibling or section documents may cross-link.  
+6. **Relevance** — Add links only when it improves navigation logically.
+
+## Output Format
+
+```json
+{
+  "documentsWithNewLinks": [
+    {
+      "path": "/existing-document",
+      "newLinks": ["/new-document-1", "/new-document-2"]
+    }
+  ]
+}

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

@@ -0,0 +1,54 @@
+<role>
+You are a feedback intent analyzer for **document content modifications**. Your task is to determine the intent type of user feedback regarding content-level operations inside a document, and whether external data sources are needed.
+</role>
+
+<input>
+feedback: {{feedback}}
+</input>
+
+<analysis_rules>
+If the feedback contains any document-level (structure) operations, return an error (document content edits cannot include structure changes).
+
+Scope: Only analyze feedback related to document content (e.g. sections, text, images).  
+
+**Intent types:**
+
+1. add - Adding new sections or content inside a document
+2. edit - Modifying existing content, titles, descriptions, components
+3. delete - Removing sections or content
+4. move - Moving sections to different positions within the document
+5. reorder - Changing the order of sections at the same level
+6. mixed - Combination of multiple intent types
+
+**Data source rules:**
+
+- add/edit -> needDataSources = true
+- delete/move/reorder -> needDataSources = false
+- mixed -> needDataSources = true if any add/edit is included
+
+**Decision logic:**
+
+- Only consider document content operations.
+- If any add or edit operation exists -> needDataSources = true
+- If only delete, move, or reorder operations exist -> needDataSources = false
+- When uncertain, default to needDataSources = true
+</analysis_rules>
+
+<output_rules>
+Normal output:
+
+{
+  "error": false,
+  "needDataSources": boolean,
+  "intentType": "add" | "edit" | "delete" | "move" | "reorder" | "mixed",
+  "reason": "Explanation of why data sources are or aren't needed based on page content operations."
+}
+
+Error output (if document-level operations are detected):
+
+{
+  "error": true,
+  "needDataSources": false,
+  "reason": "Feedback mixes document-content edits with document-structure operations. When analyzing document content, structure changes are not allowed. Please split into separate feedback items."
+}
+</output_rules>

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

@@ -0,0 +1,43 @@
+<role>
+You are a feedback intent analyzer for **document structure modifications**. Your task is to determine the intent type of user feedback regarding document-level operations and whether external data sources are needed.
+</role>
+
+<input>
+feedback: {{feedback}}
+</input>
+
+<analysis_rules>
+Scope: Only analyze feedback related to document structure. Ignore any content-level operations inside document (e.g. sections, text, images).
+
+**intent types:**
+
+1. add - Adding new documents
+2. edit - Modifying document-level properties (e.g., path, parentId, title of the document itself)
+3. delete - Removing documents
+4. move - Moving documents to different positions or parent sections
+5. reorder - Changing the order of documents
+6. mixed - Combination of multiple intent types
+
+**Data source rules:**
+
+- add/edit -> needDataSources = true
+- delete/move/reorder -> needDataSources = false
+- mixed -> needDataSources = true if any add/edit is included
+
+**Decision logic:**
+
+- Only consider document-level operations in the feedback.
+- If any add or edit operation exists -> needDataSources = true
+- If only delete, move, or reorder operations exist -> needDataSources = false
+- When uncertain, default to needDataSources = true
+</analysis_rules>
+
+<output_rules>
+Return a JSON object:
+
+{
+  "needDataSources": boolean,
+  "intentType": "add" | "edit" | "delete" | "move" | "reorder" | "mixed",
+  "reason": "Explanation of why data sources are or aren't needed based on document-level operations."
+}
+</output_rules>

package/types/document-schema.mjs

@@ -4,6 +4,7 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 // Update document content schemas
 export const updateDocumentContentInputSchema = z.object({
   diffPatch: z.string().min(1, "Diff patch is required"),
+  path: z.string().min(1, "Path is required for concurrent document updates"),
 });
 
 export const updateDocumentContentOutputSchema = z.object({
@@ -18,6 +19,7 @@ export const getUpdateDocumentContentInputJsonSchema = () => {
   const schema = zodToJsonSchema(updateDocumentContentInputSchema);
   if (schema.properties) {
     schema.properties.diffPatch.description = "Diff patch string to apply to the original content";
+    schema.properties.path.description = "Document path";
   }
   return schema;
 };

package/types/document-structure-schema.mjs

@@ -33,12 +33,13 @@ export const addDocumentOutputSchema = z.object({
 // Delete document schemas
 export const deleteDocumentInputSchema = z.object({
   path: z.string().min(1, "Path is required"),
+  recursive: z.boolean().optional(),
 });
 
 export const deleteDocumentOutputSchema = z.object({
   documentStructure: documentStructureSchema,
   message: z.string().optional(),
-  deletedDocument: documentItemSchema.optional(),
+  deletedDocuments: z.array(documentItemSchema).optional(),
   error: z.object({ message: z.string() }).optional(),
 });
 
@@ -113,6 +114,8 @@ export const getDeleteDocumentInputJsonSchema = () => {
   const schema = zodToJsonSchema(deleteDocumentInputSchema);
   if (schema.properties) {
     schema.properties.path.description = "URL path of the document to delete";
+    schema.properties.recursive.description =
+      "If true, recursively delete all child documents. If false or not provided, deletion will fail if child documents exist.";
   }
   return schema;
 };
@@ -123,7 +126,8 @@ export const getDeleteDocumentOutputJsonSchema = () => {
     schema.properties.documentStructure.description =
       "Updated documentation structure array with the document removed";
     schema.properties.message.description = "Success message describing the operation result";
-    schema.properties.deletedDocument.description = "The deleted document object";
+    schema.properties.deletedDocuments.description =
+      "Array of deleted document objects (includes all recursively deleted child documents if recursive=true)";
     schema.properties.error.description =
       "Error object containing error message if operation failed";
   }

package/utils/auth-utils.mjs

@@ -21,7 +21,6 @@ import {
   DISCUSS_KIT_STORE_URL,
   PAYMENT_KIT_DID,
 } from "./constants/index.mjs";
-import { requestWithAuthToken } from "./request.mjs";
 import { withQuery } from "ufo";
 
 const WELLKNOWN_SERVICE_PATH_PREFIX = "/.well-known/service";
@@ -143,16 +142,15 @@ export async function getAccessToken(appUrl, ltToken = "", locale = "en") {
 
         try {
           const officialBaseUrl = process.env.DOC_SMITH_BASE_URL || CLOUD_SERVICE_URL_PROD;
-          const officialAccessToken = await getCachedAccessToken(officialBaseUrl);
-          if (officialAccessToken) {
-            const mountPoint = await getComponentMountPoint(officialBaseUrl, PAYMENT_KIT_DID);
-            const data = await requestWithAuthToken(
-              withQuery(joinURL(officialBaseUrl, mountPoint, "/api/tool/short-url"), {
-                url: connectUrl,
-              }),
-              {},
-              officialAccessToken,
-            );
+          const mountPoint = await getComponentMountPoint(officialBaseUrl, PAYMENT_KIT_DID);
+          const response = await fetch(
+            withQuery(joinURL(officialBaseUrl, mountPoint, "/api/tool/short-connect-url"), {
+              url: connectUrl,
+              locale,
+            }),
+          );
+          const data = await response.json();
+          if (data.url) {
             connectUrl = data.url;
           }
         } catch {
@@ -160,7 +158,7 @@ export async function getAccessToken(appUrl, ltToken = "", locale = "en") {
         }
 
         console.log(
-          "🔗 Please open the following URL in your browser to authorize access: ",
+          "🔗 Please open the following URL in your browser to authorize access:",
           chalk.cyan(connectUrl),
           "\n",
         );
@@ -220,16 +218,34 @@ export async function getOfficialAccessToken(baseUrl, openPage = true, locale =
       fetchInterval: FETCH_INTERVAL,
       appName: "AIGNE DocSmith",
       appLogo: "https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg",
-      openPage: (pageUrl) => {
+      openPage: async (pageUrl) => {
         const url = new URL(pageUrl);
         if (locale) {
           url.searchParams.set("locale", locale);
         }
-        open(url.toString());
+
+        let connectUrl = url.toString();
+        open(connectUrl);
+        try {
+          const officialBaseUrl = process.env.DOC_SMITH_BASE_URL || CLOUD_SERVICE_URL_PROD;
+          const mountPoint = await getComponentMountPoint(officialBaseUrl, PAYMENT_KIT_DID);
+          const response = await fetch(
+            withQuery(joinURL(officialBaseUrl, mountPoint, "/api/tool/short-connect-url"), {
+              url: connectUrl,
+              locale,
+            }),
+          );
+          const data = await response.json();
+          if (data.url) {
+            connectUrl = data.url;
+          }
+        } catch {
+          // Ignore error
+        }
 
         console.log(
-          "🔗 Please open the following URL in your browser to authorize access: ",
-          chalk.cyan(url.toString()),
+          "🔗 Please open the following URL in your browser to authorize access:",
+          chalk.cyan(connectUrl),
           "\n",
         );
       },

package/utils/d2-utils.mjs

@@ -19,6 +19,8 @@ import { getContentHash } from "./utils.mjs";
 
 const codeBlockRegex = /```d2.*\n([\s\S]*?)```/g;
 
+export const DIAGRAM_PLACEHOLDER = "DIAGRAM_PLACEHOLDER";
+
 export async function getChart({ content, strict }) {
   const d2 = new D2();
   const iconUrlList = Object.keys(iconMap);
@@ -203,3 +205,14 @@ export function wrapCode({ content }) {
 
   return `\`\`\`d2\n${content}\n\`\`\``;
 }
+
+export function replacePlaceholder({ content }) {
+  const [firstMatch] = Array.from(content.matchAll(codeBlockRegex));
+  if (firstMatch) {
+    const matchContent = firstMatch[0];
+    const cleanContent = content.replace(matchContent, DIAGRAM_PLACEHOLDER);
+    return [cleanContent, matchContent];
+  }
+
+  return [content, ""];
+}

package/utils/docs-finder-utils.mjs

@@ -324,6 +324,40 @@ export async function loadDocumentStructure(outputDir) {
   }
 }
 
+/**
+ * Build allowed links set from document structure
+ * Includes both original paths and processed .md paths for link validation
+ * @param {Array} documentStructure - Array of documentation structure items with path property
+ * @returns {Set<string>} Set of allowed link paths
+ */
+export function buildAllowedLinksFromStructure(documentStructure) {
+  const allowedLinks = new Set();
+
+  if (!Array.isArray(documentStructure)) {
+    return allowedLinks;
+  }
+
+  documentStructure.forEach((item) => {
+    if (!item?.path) {
+      return;
+    }
+
+    // Add original path
+    allowedLinks.add(item.path);
+
+    // Add processed .md path (same logic as processContent in utils.mjs)
+    let processedPath = item.path;
+    if (processedPath.startsWith(".")) {
+      processedPath = processedPath.replace(/^\./, "");
+    }
+    let flatPath = processedPath.replace(/^\//, "").replace(/\//g, "-");
+    flatPath = `./${flatPath}.md`;
+    allowedLinks.add(flatPath);
+  });
+
+  return allowedLinks;
+}
+
 /**
  * Build a tree structure from a flat document structure array using parentId
  * @param {Array} documentStructure - Flat array of document structure items with path and parentId
@@ -358,3 +392,51 @@ export function buildDocumentTree(documentStructure) {
 
   return { rootNodes, nodeMap };
 }
+
+/**
+ * Format document structure for printing
+ * @param {Array} structure - Document structure array
+ * @returns {Object} Object containing rootNodes and printNode function
+ */
+function formatDocumentStructure(structure) {
+  const { rootNodes } = buildDocumentTree(structure);
+
+  function printNode(node, depth = 0) {
+    const INDENT_SPACES = "  ";
+    const FOLDER_ICON = "  📁";
+    const FILE_ICON = "  📄";
+    const indent = INDENT_SPACES.repeat(depth);
+    const prefix = depth === 0 ? FOLDER_ICON : FILE_ICON;
+
+    console.log(`${indent}${prefix} ${node.title}`);
+
+    if (node.children && node.children.length > 0) {
+      node.children.forEach((child) => {
+        printNode(child, depth + 1);
+      });
+    }
+  }
+
+  return { rootNodes, printNode };
+}
+
+/**
+ * Print document structure in a user-friendly format
+ * @param {Array} structure - Document structure array
+ */
+export function printDocumentStructure(structure) {
+  console.log(`\n  ${"-".repeat(50)}`);
+  console.log("  Current Documentation Structure");
+  console.log(`  ${"-".repeat(50)}`);
+
+  const { rootNodes, printNode } = formatDocumentStructure(structure);
+
+  if (rootNodes.length === 0) {
+    console.log("  No documentation structure found.");
+  } else {
+    rootNodes.forEach((node) => {
+      printNode(node);
+    });
+  }
+  console.log();
+}