@aigne/doc-smith 0.9.5 → 0.9.6-beta

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.9.6-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.5...v0.9.6-beta) (2025-11-18)
+
+
+### Features
+
+* smaller granularity of updated single-document ([#320](https://github.com/AIGNE-io/aigne-doc-smith/issues/320)) ([588b924](https://github.com/AIGNE-io/aigne-doc-smith/commit/588b924649f5f116a07586a1f6760ee6f7e79953))
+
+
+### Bug Fixes
+
+* always use short url during doc publish process ([#319](https://github.com/AIGNE-io/aigne-doc-smith/issues/319)) ([5fcf067](https://github.com/AIGNE-io/aigne-doc-smith/commit/5fcf067c2caf822576ee60e3f58a69040e5813f4))
+* tune document detail update output constraint ([#322](https://github.com/AIGNE-io/aigne-doc-smith/issues/322)) ([6ac8aa4](https://github.com/AIGNE-io/aigne-doc-smith/commit/6ac8aa49e9bb761164c60ccddc4b601b9c612203))
+
 ## [0.9.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.5-beta.1...v0.9.5) (2025-11-14)
 
 ## [0.9.5-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.9.5-beta...v0.9.5-beta.1) (2025-11-14)

package/agents/init/check.mjs

@@ -11,6 +11,6 @@ export default async function checkNeedGenerate({ docsDir, locale, documentExecu
     process.exit(0);
   }
   return {
-    message: 'Documents found in the docs directory, skipping "generate" step',
+    message: 'Documents found in the docs directory, skipping "create" step',
   };
 }

package/agents/update/check-generate-diagram.mjs

@@ -1,4 +1,5 @@
-const PLACEHOLDER = "DIAGRAM_PLACEHOLDER";
+import { DIAGRAM_PLACEHOLDER } from "../../utils/d2-utils.mjs";
+
 const DEFAULT_DIAGRAMMING_EFFORT = 5;
 const MIN_DIAGRAMMING_EFFORT = 0;
 const MAX_DIAGRAMMING_EFFORT = 10;
@@ -66,8 +67,8 @@ export default async function checkGenerateDiagram(
     }
 
     if (diagramSourceCode && !skipGenerateDiagram) {
-      if (content.includes(PLACEHOLDER)) {
-        content = content.replace(PLACEHOLDER, diagramSourceCode);
+      if (content.includes(DIAGRAM_PLACEHOLDER)) {
+        content = content.replace(DIAGRAM_PLACEHOLDER, diagramSourceCode);
       } else {
         const mergeAgent = options.context?.agents?.["mergeDiagramToDocument"];
         ({ content } = await options.context.invoke(mergeAgent, {

package/agents/update/update-single/update-single-document-detail.mjs

@@ -0,0 +1,140 @@
+import { AIAgent } from "@aigne/core";
+import { pick } from "@aigne/core/utils/type-utils.js";
+import z from "zod";
+import { DIAGRAM_PLACEHOLDER, replacePlaceholder } from "../../../utils/d2-utils.mjs";
+
+async function getIntentType(input, options) {
+  const instructions = `<role>
+You are a feedback intent analyzer. Your task is to determine which type of content modifications are needed based on the user's feedback.
+</role>
+
+<user_feedback>
+{{feedback}}
+</user_feedback>`;
+  const analyzeUpdateFeedbackIntentAgent = AIAgent.from({
+    name: "analyzeUpdateFeedbackIntent",
+    description:
+      "Analyze user feedback to determine if document are needed for content modifications",
+    task_render_mode: "hide",
+    instructions,
+    // TODO: can't set reasoningEffort
+    // modelOptions: {
+    //   reasoningEffort: 1,
+    // },
+    inputSchema: z.object({
+      feedback: z.string().describe("User feedback for content modifications"),
+    }),
+    outputSchema: z.object({
+      intentType: z
+        .enum(["addDiagram", "deleteDiagram", "updateDiagram", "updateDocument"])
+        .describe(
+          "The primary type of user intention: one of addDiagram, deleteDiagram, updateDiagram, updateDocument",
+        ),
+    }),
+  });
+  const { intentType } = await options.context.invoke(analyzeUpdateFeedbackIntentAgent, {
+    feedback: input.feedback,
+  });
+  return intentType;
+}
+
+async function saveDoc(input, options, { content }) {
+  const saveAgent = options.context?.agents?.["saveDoc"];
+  await options.context.invoke(saveAgent, {
+    ...pick(input, ["path", "docsDir", "labels", "locale"]),
+    content,
+  });
+}
+
+async function addDiagram(input, options) {
+  const generateDiagramAgent = options.context.agents["checkGenerateDiagram"];
+  const generateDiagramResult = await options.context.invoke(generateDiagramAgent, {
+    ...pick(input, ["locale", "path", "diagramming", "feedback"]),
+    documentContent: options.context.userContext.currentContent,
+  });
+  const content = generateDiagramResult.content;
+  await saveDoc(input, options, { content });
+  return { content };
+}
+
+async function updateDiagram(input, options) {
+  let [content, previousDiagramContent] = replacePlaceholder({
+    content: options.context.userContext.currentContent,
+  });
+  const generateAgent = options.context?.agents?.["generateDiagram"];
+  const { diagramSourceCode } = await options.context.invoke(generateAgent, {
+    documentContent: content,
+    locale: input.locale,
+    previousDiagramContent,
+    feedback: input.feedback,
+  });
+  content = content.replace(DIAGRAM_PLACEHOLDER, diagramSourceCode);
+  await saveDoc(input, options, { content });
+  return { content };
+}
+
+async function deleteDiagram(input, options) {
+  const [documentContent] = replacePlaceholder({
+    content: options.context.userContext.currentContent,
+  });
+  const instructions = `<role>
+Your task is to remove ${DIAGRAM_PLACEHOLDER} and adjust the document context (based on the user's feedback) to make it easier to understand.
+</role>
+
+<document_content>
+{{documentContent}}
+</document_content>
+
+<user_feedback>
+{{feedback}}
+</user_feedback>`;
+  const deleteAgent = AIAgent.from({
+    name: "deleteDiagram",
+    description: "Remove a diagram from the document content",
+    task_render_mode: "hide",
+    instructions,
+    inputSchema: z.object({
+      documentContent: z.string().describe("Source content of the document"),
+      feedback: z.string().describe("User feedback for content modifications"),
+    }),
+    outputKey: "message",
+  });
+  const { message: content } = await options.context.invoke(deleteAgent, {
+    documentContent,
+    feedback: input.feedback,
+  });
+  await saveDoc(input, options, { content });
+
+  return { content };
+}
+
+async function updateDocument(input, options) {
+  const updateAgent = options.context.agents["updateDocumentDetail"];
+  const updateResult = await options.context.invoke(updateAgent, {
+    ...input,
+    originalContent: options.context.userContext.currentContent,
+  });
+  if (updateResult.message === "success") {
+    await saveDoc(input, options, { content: options.context.userContext.currentContent });
+  }
+  return {
+    content: options.context.userContext.currentContent,
+  };
+}
+
+export default async function updateSingleDocumentDetail(input, options) {
+  const intentType = await getIntentType(input, options);
+
+  const fnMap = {
+    addDiagram,
+    updateDiagram,
+    deleteDiagram,
+    updateDocument,
+  };
+
+  if (fnMap[intentType]) {
+    const result = await fnMap[intentType](input, options);
+    return result;
+  }
+  return {};
+}

package/agents/update/user-review-document.mjs

@@ -200,7 +200,7 @@ export default async function userReviewDocument({ content, description, ...rest
     }
 
     // Get the updateDocument agent
-    const updateAgent = options.context.agents["handleDocumentUpdate"];
+    const updateAgent = options.context.agents["updateSingleDocumentDetail"];
     if (!updateAgent) {
       console.log(
         "We can't process your feedback right now. The document update feature is temporarily unavailable.",

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.5",
+  "version": "0.9.6-beta",
   "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/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, ""];
+}