@aigne/doc-smith 0.9.10 → 0.9.11-beta

package/agents/schema/document-structure-refine-item.yaml

@@ -1,23 +0,0 @@
-type: object
-description: Document structure item representing a node in the document hierarchy
-properties:
-  id:
-    type: string
-    description: Unique identifier for the document structure item
-  title:
-    type: string
-  description:
-    type: string
-  path:
-    type: string
-    description: Path in URL format, cannot be empty, cannot contain spaces or special characters, must start with /, no need to include language level, e.g., /zh/about should return /about
-  parentPath:
-    type: string
-    description: Parent node path, if null indicates it is a top-level node
-  icon: 
-    type: string
-    description: Iconify icon name, e.g., lucide:book, lucide:rocket, lucide:* etc.
-required:
-  - title
-  - description
-  - path

package/agents/schema/document-structure.yaml

@@ -1,29 +0,0 @@
-type: array
-items:
-  type: object
-  properties:
-    title:
-      type: string
-    description:
-      type: string
-    path:
-      type: string
-      description: Path in URL format, cannot be empty, cannot contain spaces or special characters, must start with /, no need to include language level, e.g., /zh/about should return /about
-    parentId:
-      type:
-        - string
-        - "null"
-      description: Parent node path, if null indicates it is a top-level node
-    sourceIds:
-      type: array
-      description: Associated sourceId from `<data_sources>` for subsequent translation and content generation, must come from sourceId in `<data_sources>`, cannot have fake ids, **cannot be empty**
-      items:
-        type: string
-    icon:
-      type: string
-      description: Lucide icon name for root-level documents (just support lucide:icon-name, not support other icon collections)
-  required:
-    - title
-    - description
-    - path
-    - sourceIds

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

@@ -1,27 +0,0 @@
-type: team
-name: batchGenerateDocument
-description: Batch generate document details
-skills:
-  - ./check-document.mjs
-input_schema:
-  type: object
-  properties:
-    detailDataSource:
-      type: string
-      description: Context for documentation structure generation, used to assist generate documentation structure
-    documentStructure: ../schema/document-structure.yaml
-    translates:
-      type: array
-      items:
-        type: object
-        properties:
-          language:
-            type: string
-      description: List of languages to translate documents to
-    modifiedFiles:
-      type: array
-      items: { type: string }
-      description: Array of modified files since last generation
-iterate_on: documentStructure
-concurrency: 5
-mode: sequential

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

@@ -1,7 +0,0 @@
-
-type: team
-name: batchUpdateDocument
-skills:
-  - ../update/handle-document-update.yaml
-iterate_on: selectedDocs
-concurrency: 5

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

@@ -1,116 +0,0 @@
-/**
- * Check if --diagram or --diagram-all flag is set via command line arguments or environment variable
- * Returns the flag values and passes through all input
- *
- * --diagram: Filter to show only documents with diagrams, let user select
- * --diagram-all: Auto-select all documents with diagrams, no user selection
- */
-export default function checkDiagramFlag(input) {
-  let shouldUpdateDiagrams = false;
-  let shouldAutoSelectDiagrams = false;
-
-  // Priority order: command line args > input params > environment variables
-  // Check command line arguments first (highest priority)
-  if (process.argv) {
-    // Check for --diagram-all or -da (exact match)
-    const hasDiagramAllFlag = process.argv.some((arg) => arg === "--diagram-all" || arg === "-da");
-
-    const hasDiagramFlag = process.argv.some((arg) => arg === "--diagram" || arg === "-d");
-
-    if (hasDiagramAllFlag) {
-      shouldUpdateDiagrams = true;
-      shouldAutoSelectDiagrams = true;
-      // Return early if CLI arg found (highest priority)
-      return {
-        ...input,
-        shouldUpdateDiagrams,
-        shouldAutoSelectDiagrams,
-      };
-    } else if (hasDiagramFlag) {
-      shouldUpdateDiagrams = true;
-      shouldAutoSelectDiagrams = false;
-      // Return early if CLI arg found (highest priority)
-      return {
-        ...input,
-        shouldUpdateDiagrams,
-        shouldAutoSelectDiagrams,
-      };
-    }
-  }
-
-  // Check input parameter (second priority - CLI framework might parse --diagram-all as separate parameter)
-  if (input["diagram-all"] === true || input["diagram-all"] === "true") {
-    shouldUpdateDiagrams = true;
-    shouldAutoSelectDiagrams = true;
-    // Return early if input param found (second priority)
-    return {
-      ...input,
-      shouldUpdateDiagrams,
-      shouldAutoSelectDiagrams,
-    };
-  } else if (input.diagram === true || input.diagram === "true") {
-    shouldUpdateDiagrams = true;
-    shouldAutoSelectDiagrams = false;
-    // Return early if input param found (second priority)
-    return {
-      ...input,
-      shouldUpdateDiagrams,
-      shouldAutoSelectDiagrams,
-    };
-  }
-
-  // Check environment variable (lowest priority)
-  if (
-    process.env.DOC_SMITH_UPDATE_DIAGRAMS === "all" ||
-    process.env.DOC_SMITH_UPDATE_DIAGRAMS_ALL === "true" ||
-    process.env.DOC_SMITH_UPDATE_DIAGRAMS_ALL === "1"
-  ) {
-    shouldUpdateDiagrams = true;
-    shouldAutoSelectDiagrams = true;
-  } else if (
-    process.env.DOC_SMITH_UPDATE_DIAGRAMS === "true" ||
-    process.env.DOC_SMITH_UPDATE_DIAGRAMS === "1"
-  ) {
-    shouldUpdateDiagrams = true;
-    shouldAutoSelectDiagrams = false;
-  }
-
-  // Return all input plus the flags
-  return {
-    ...input,
-    shouldUpdateDiagrams,
-    shouldAutoSelectDiagrams,
-  };
-}
-
-checkDiagramFlag.input_schema = {
-  type: "object",
-  properties: {
-    diagram: {
-      type: ["boolean", "string"],
-      description:
-        "Flag to trigger diagram update: true for user selection (can also use --diagram CLI arg)",
-    },
-    "diagram-all": {
-      type: ["boolean", "string"],
-      description:
-        "Flag to auto-select all documents with diagrams (can also use --diagram-all CLI arg)",
-    },
-  },
-};
-
-checkDiagramFlag.output_schema = {
-  type: "object",
-  properties: {
-    shouldUpdateDiagrams: {
-      type: "boolean",
-      description: "Whether to filter and update diagrams",
-    },
-    shouldAutoSelectDiagrams: {
-      type: "boolean",
-      description:
-        "Whether to auto-select all documents with diagrams (true for --diagram-all, false for --diagram)",
-    },
-  },
-  required: ["shouldUpdateDiagrams", "shouldAutoSelectDiagrams"],
-};

package/agents/update/check-document.mjs

@@ -1,162 +0,0 @@
-import { access, readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { TeamAgent } from "@aigne/core";
-import fs from "fs-extra";
-import pMap from "p-map";
-
-import { getFileName } from "../../utils/utils.mjs";
-import checkDetailResult from "../utils/check-detail-result.mjs";
-
-// Get current script directory
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-export default async function checkDocument(
-  {
-    path,
-    docsDir,
-    sourceIds,
-    originalDocumentStructure,
-    documentStructure,
-    modifiedFiles,
-    forceRegenerate,
-    locale,
-    translates = [],
-    ...rest
-  },
-  options,
-) {
-  // Check if the detail file already exists
-  const fileFullName = getFileName(path, locale);
-  const filePath = join(docsDir, fileFullName);
-  let detailGenerated = true;
-  let fileContent = null;
-  try {
-    await access(filePath);
-    // If file exists, read its content for validation
-    fileContent = await readFile(filePath, "utf8");
-  } catch {
-    detailGenerated = false;
-  }
-
-  // Check if sourceIds have changed by comparing with original documentation structure
-  let sourceIdsChanged = false;
-  if (originalDocumentStructure && sourceIds) {
-    // Find the original node in the documentation structure
-    const originalNode = originalDocumentStructure.find((node) => node.path === path);
-
-    if (originalNode?.sourceIds) {
-      const originalSourceIds = originalNode.sourceIds;
-      const currentSourceIds = sourceIds;
-
-      // Compare arrays (order doesn't matter, but content does)
-      if (originalSourceIds.length !== currentSourceIds.length) {
-        sourceIdsChanged = true;
-      } else {
-        // Check if any sourceId is different
-        const originalSet = new Set(originalSourceIds);
-        const currentSet = new Set(currentSourceIds);
-
-        if (originalSet.size !== currentSet.size) {
-          sourceIdsChanged = true;
-        } else {
-          // Check if any element is different
-          for (const sourceId of originalSourceIds) {
-            if (!currentSet.has(sourceId)) {
-              sourceIdsChanged = true;
-              break;
-            }
-          }
-        }
-      }
-    }
-  }
-
-  // If file exists, check content validation
-  let contentValidationFailed = false;
-  let validationResult = {};
-  if (detailGenerated && fileContent && documentStructure) {
-    validationResult = await checkDetailResult({
-      documentStructure,
-      reviewContent: fileContent,
-      docsDir,
-    });
-
-    if (!validationResult.isApproved) {
-      contentValidationFailed = true;
-    }
-  }
-  const translateList = Array.isArray(translates) ? translates : [];
-  const languages = translateList.map((x) => x.language);
-  const lackLanguages = new Set(languages);
-  const skills = [];
-
-  // If file exists, sourceIds haven't changed, source files haven't changed, and content validation passes, no need to regenerate
-  if (detailGenerated && !sourceIdsChanged && !contentValidationFailed && !forceRegenerate) {
-    await pMap(
-      languages,
-      async (x) => {
-        const languageFileName = getFileName(path, x);
-        const languageFilePath = join(docsDir, languageFileName);
-        if (await fs.exists(languageFilePath)) {
-          lackLanguages.delete(x);
-        }
-      },
-      { concurrency: 5 },
-    );
-    if (lackLanguages.size === 0) {
-      return {
-        path,
-        docsDir,
-        ...rest,
-        detailGenerated: true,
-      };
-    }
-    // translations during generation don't need feedback, content is satisfactory
-    rest.content = fileContent;
-  } else {
-    skills.push(options.context.agents["handleDocumentUpdate"]);
-  }
-
-  skills.push(options.context.agents["translateMultilingual"]);
-
-  const teamAgent = TeamAgent.from({
-    name: "generateDocument",
-    skills,
-  });
-  let openAPISpec = null;
-
-  if (options.context?.userContext?.openAPISpec?.sourceId) {
-    const matchingDocument = originalDocumentStructure.find((item) => {
-      if (item.path === path) {
-        return item.sourceIds.find((x) => x === options.context.userContext.openAPISpec.sourceId);
-      }
-      return false;
-    });
-    if (matchingDocument) {
-      openAPISpec = options.context.userContext.openAPISpec;
-    }
-  }
-
-  const result = await options.context.invoke(teamAgent, {
-    ...rest,
-    translates: translateList.filter((x) => lackLanguages.has(x.language)),
-    locale,
-    docsDir,
-    path,
-    sourceIds,
-    originalDocumentStructure,
-    documentStructure,
-    detailFeedback: contentValidationFailed ? validationResult.detailFeedback : "",
-    openAPISpec,
-  });
-
-  return {
-    path,
-    docsDir,
-    ...rest,
-    result,
-  };
-}
-
-checkDocument.taskTitle = "Check if '{{ title }}' needs generate or update";

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

@@ -1,106 +0,0 @@
-import { hasDiagramContent } from "../../utils/check-document-has-diagram.mjs";
-
-const DEFAULT_DIAGRAMMING_EFFORT = 5;
-const MIN_DIAGRAMMING_EFFORT = 0;
-const MAX_DIAGRAMMING_EFFORT = 10;
-
-export default async function checkGenerateDiagram(
-  {
-    documentContent,
-    locale,
-    feedback,
-    detailFeedback,
-    originalContent,
-    diagramming,
-    path,
-    docsDir,
-    shouldUpdateDiagrams,
-  },
-  options,
-) {
-  let content = documentContent;
-  let skipGenerateDiagram = false;
-
-  // If --diagram flag is set and document already has d2 code blocks,
-  // skip preCheck and directly replace existing diagrams
-  // This is because when using --diagram/--diagram-all, the user explicitly wants to update diagrams,
-  // so we should skip the "do we need to generate diagram" check and directly proceed to replacement
-  const hasExistingDiagrams = originalContent && hasDiagramContent(originalContent);
-
-  // Skip preCheck if:
-  // 1. Using --diagram/--diagram-all flag (shouldUpdateDiagrams === true) AND
-  // 2. Document already has d2 code blocks (hasExistingDiagrams === true)
-  // This means user explicitly wants to update existing diagrams, no need to check if diagram is needed
-  const shouldSkipPreCheck = shouldUpdateDiagrams === true && hasExistingDiagrams;
-
-  let preCheckResult = { details: [], content: null };
-  if (!shouldSkipPreCheck) {
-    const preCheckAgent = options.context?.agents?.["preCheckGenerateDiagram"];
-
-    preCheckResult = await options.context.invoke(preCheckAgent, {
-      documentContent,
-      feedback,
-      detailFeedback,
-      previousGenerationContent: originalContent,
-    });
-  }
-
-  const totalScore = (preCheckResult.details || []).reduce((acc, curr) => acc + curr.score, 0);
-  if (![false, "false", "", undefined, null].includes(preCheckResult.content)) {
-    content = preCheckResult.content;
-  }
-
-  let diagrammingEffort = diagramming?.effort
-    ? Number(diagramming?.effort)
-    : DEFAULT_DIAGRAMMING_EFFORT;
-
-  if (Number.isNaN(diagrammingEffort)) {
-    diagrammingEffort = DEFAULT_DIAGRAMMING_EFFORT;
-  } else {
-    diagrammingEffort = Math.min(
-      Math.max(MIN_DIAGRAMMING_EFFORT, diagrammingEffort),
-      MAX_DIAGRAMMING_EFFORT,
-    );
-  }
-
-  // If we skipped preCheck because document has existing diagrams and --diagram flag is set,
-  // we should NOT skip generating diagram (we need to replace existing ones)
-  if (shouldSkipPreCheck) {
-    skipGenerateDiagram = false;
-  } else if (totalScore <= diagrammingEffort) {
-    skipGenerateDiagram = true;
-  }
-
-  if (skipGenerateDiagram) {
-    content = documentContent;
-  } else {
-    try {
-      const generateAgent = options.context?.agents?.["generateDiagram"];
-      const result = await options.context.invoke(generateAgent, {
-        documentContent: content,
-        locale,
-        diagramming: diagramming || {},
-        feedback: feedback || "",
-        originalContent: originalContent || documentContent,
-        path,
-        docsDir,
-      });
-
-      // generateDiagram now returns { content } with image already inserted
-      // The image replaces DIAGRAM_PLACEHOLDER or D2 code blocks
-      if (result?.content) {
-        content = result.content;
-      } else {
-        // Fallback: if no content returned, use original document content
-        content = documentContent;
-      }
-    } catch (error) {
-      skipGenerateDiagram = true;
-      console.log(`⚠️  Skip generate any diagram: ${error.message}`);
-      // On error, return original document content
-      content = documentContent;
-    }
-  }
-
-  return { content };
-}

package/agents/update/check-update-is-single.mjs

@@ -1,53 +0,0 @@
-export default async function checkUpdateIsSingle({ selectedDocs, ...rest }, options) {
-  if (!selectedDocs || !Array.isArray(selectedDocs)) {
-    throw new Error("A list of documents to update must be provided.");
-  }
-
-  if (selectedDocs.length === 0) {
-    throw new Error("You must select at least one document to update.");
-  }
-
-  let targetAgent;
-  let agentName;
-
-  if (selectedDocs.length === 1 && !rest.reset) {
-    // Single doc update without reset
-    agentName = "updateSingleDocument";
-    targetAgent = options.context.agents["updateSingleDocument"];
-  } else {
-    agentName = "batchUpdateDocument";
-    targetAgent = options.context.agents["batchUpdateDocument"];
-  }
-
-  if (!targetAgent) {
-    throw new Error(`Sorry, I can't seem to find the "${agentName}" agent.`);
-  }
-
-  try {
-    const result = await options.context.invoke(targetAgent, {
-      selectedDocs,
-      ...rest,
-    });
-
-    // For batch updates, preserve selectedDocs and other context for save-and-translate-document
-    // batchUpdateDocument returns an array of results, but save-and-translate-document needs selectedDocs
-    if (agentName === "batchUpdateDocument") {
-      return {
-        ...rest,
-        selectedDocs, // Preserve selectedDocs for save-and-translate-document.mjs
-        result, // Include the batch update results
-      };
-    }
-
-    // For single document updates, return result as-is
-    return result;
-  } catch (error) {
-    console.error(
-      `Sorry, I encountered an error while trying to run the ${agentName} agent:`,
-      error.message,
-    );
-    throw error;
-  }
-}
-
-checkUpdateIsSingle.taskTitle = "Check document count and route to appropriate update agent";