@aigne/doc-smith 0.0.1

package/README.md

@@ -0,0 +1,87 @@
+# AIGNE DocSmith
+
+AIGNE DocSmith is a powerful, AI-driven documentation generation tool built on the AIGNE Framework. It automates the creation of detailed, structured, and multi-language documentation directly from your source code.
+
+## Features
+
+- **Automated Structure Planning:** Intelligently analyzes your codebase to generate a comprehensive and logical document structure.
+- **AI-Powered Content Generation:** Populates the document structure with detailed, high-quality content.
+- **Multi-Language Support:** Seamlessly translates your documentation into multiple languages.
+- **Smart File Management:** Automatically cleans up invalid .md files that are no longer in the structure plan, preventing file accumulation.
+- **Customizable Prompts:** Allows for fine-tuning the output by customizing the prompts used by the AI agents.
+- **Extensible Workflow:** Built with a modular agent-based architecture, making it easy to extend and customize the documentation generation process.
+
+## How It Works
+
+AIGNE DocSmith utilizes a chain of AI agents to generate documentation in a three-step process:
+
+1.  **Structure Planning (`structure-planning`):** This agent analyzes the source code and creates a structured plan for the documentation. The plan is defined in `agents/structure-planning.yaml` and uses the prompt in `prompts/structure-planning.md`.
+2.  **Content Detail Generation (`content-detail-generator`):** This agent takes the structured plan and generates detailed content for each section of the documentation. This process is defined in `agents/content-detail-generator.yaml` and guided by the prompt in `prompts/document/detail-generator.md`.
+3.  **Translation (`translate`):** This agent translates the generated documentation into different languages. The translation agent is defined in `agents/translate.yaml` and uses the prompt in `prompts/translator.md`.
+
+The main workflow is orchestrated by the `docs-generator` agent, as defined in `agents/docs-generator.yaml`.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js and pnpm
+- AIGNE Framework
+
+### Installation
+
+1.  Clone the repository:
+    ```bash
+    git clone https://github.com/your-username/aigne-doc-smith.git
+    ```
+2.  Install the dependencies:
+    ```bash
+    pnpm install
+    ```
+
+### Usage
+
+To generate documentation, run the following command:
+
+```bash
+aigne run docs-generator --datasources.source-code-path=/path/to/your/code
+```
+
+This will initiate the documentation generation process, and the output will be saved in the `output` directory.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a pull request or open an issue if you have any suggestions or find any bugs.
+
+## Test Commands
+
+```shell
+
+# 初始化
+npx --no doc-smith run --entry-agent init
+
+# 生成命令
+npx --no doc-smith run --input @./doc-smith/input.yaml --format yaml --entry-agent generator --model gemini:gemini-2.5-pro
+
+# 重新生成单篇
+npx --no doc-smith run --input @./doc-smith/input.yaml --format yaml --entry-agent regenerator --input-currentPath /overview --input-feedback "输出只能使用 markdown 格式，不能使用 html 标签" --model gemini:gemini-2.5-pro
+
+# 结构规划优化
+npx --no doc-smith run --input @./doc-smith/input.yaml --format yaml --entry-agent generator --input-structurePlanFeedback "删除 Contributing 下的子节点，只保留主节点，相关信息在主节点中显示" --model gemini:gemini-2.5-pro
+
+
+# 发布文档
+npx --no doc-smith run --input @./doc-smith/input.yaml --format yaml --entry-agent publish
+
+```
+
+## Testing
+
+运行测试来验证功能：
+
+```bash
+# 测试 saveDocs 方法的文件清理功能
+node tests/test-save-docs.mjs
+```
+
+更多测试信息请查看 [tests/README.md](tests/README.md)。

package/agents/batch-docs-detail-generator.yaml

@@ -0,0 +1,14 @@
+type: team
+name: batch-docs-detail-generator
+description: 批量生成文档详情
+skills:
+  - ./check-detail-generated.mjs
+input_schema:
+  type: object
+  properties:
+    datasources:
+      type: string
+      description: 结构规划的上下文，用于辅助结构规划
+    structurePlanResult: ./schema/structure-plan-result.yaml
+iterate_on: structurePlanResult
+mode: sequential

package/agents/batch-translate.yaml

@@ -0,0 +1,44 @@
+type: team
+name: batch-translate
+description: 批量翻译文档到多个语言
+skills:
+  - type: team
+    skills:
+      - ./translate.yaml
+      - type: transform
+        jsonata: |
+          $merge([
+            $,
+            { "reviewContent": translation }
+          ])
+    reflection:
+      reviewer: ./check-detail-result.mjs
+      is_approved: isApproved
+      max_iterations: 3
+      return_last_on_max_iterations: true
+input_schema:
+  type: object
+  properties:
+    translates:
+      type: array
+      items:
+        type: object
+        properties:
+          language:
+            type: string
+    content:
+      type: string
+output_schema:
+  type: object
+  properties:
+    translates:
+      type: array
+      items:
+        type: object
+        properties:
+          language:
+            type: string
+          translation:
+            type: string
+iterate_on: translates
+mode: sequential

package/agents/check-detail-generated.mjs

@@ -0,0 +1,128 @@
+import { access, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AnthropicChatModel } from "@aigne/anthropic";
+import { AIGNE, TeamAgent } from "@aigne/core";
+import { GeminiChatModel } from "@aigne/gemini";
+import { OpenAIChatModel } from "@aigne/openai";
+import checkDetailResult from "./check-detail-result.mjs";
+
+// Get current script directory
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function checkDetailGenerated(
+  { path, docsDir, sourceIds, originalStructurePlan, structurePlan, ...rest },
+  options
+) {
+  // Check if the detail file already exists
+  const flatName = path.replace(/^\//, "").replace(/\//g, "-");
+  const fileFullName = `${flatName}.md`;
+  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 structure plan
+  let sourceIdsChanged = false;
+  if (originalStructurePlan && sourceIds) {
+    // Find the original node in the structure plan
+    const originalNode = originalStructurePlan.find(
+      (node) => node.path === path
+    );
+
+    if (originalNode && 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;
+  if (detailGenerated && fileContent && structurePlan) {
+    const validationResult = await checkDetailResult({
+      structurePlan,
+      reviewContent: fileContent,
+    });
+
+    if (!validationResult.isApproved) {
+      contentValidationFailed = true;
+    }
+  }
+
+  // If file exists, sourceIds haven't changed, and content validation passes, no need to regenerate
+  if (detailGenerated && !sourceIdsChanged && !contentValidationFailed) {
+    return {
+      path,
+      docsDir,
+      ...rest,
+      detailGenerated: true,
+    };
+  }
+
+  // If sourceIds have changed, regenerate even if file exists
+  const aigne = await AIGNE.load(join(__dirname, "../"), {
+    models: [
+      {
+        name: OpenAIChatModel.name,
+        create: (params) => new OpenAIChatModel({ ...params }),
+      },
+      {
+        name: AnthropicChatModel.name,
+        create: (params) => new AnthropicChatModel({ ...params }),
+      },
+      {
+        name: GeminiChatModel.name,
+        create: (params) => new GeminiChatModel({ ...params }),
+      },
+    ],
+  });
+
+  const teamAgent = TeamAgent.from({
+    name: "generate-detail",
+    skills: [aigne.agents["detail-generator-and-translate"]],
+  });
+
+  const result = await options.context.invoke(teamAgent, {
+    ...rest,
+    docsDir,
+    path,
+    sourceIds,
+    originalStructurePlan,
+    structurePlan,
+  });
+
+  return {
+    path,
+    docsDir,
+    ...rest,
+    result,
+  };
+}

package/agents/check-detail-result.mjs

@@ -0,0 +1,141 @@
+export default async function checkDetailResult({
+  structurePlan,
+  reviewContent,
+}) {
+  const linkRegex = /(?<!\!)\[([^\]]+)\]\(([^)]+)\)/g;
+  const tableSeparatorRegex = /^\s*\|\s*-+\s*\|\s*$/;
+  const codeBlockRegex = /^\s+```(?:\w+)?$/;
+
+  let isApproved = true;
+  const detailFeedback = [];
+
+  // Create a set of allowed links, including both original paths and processed .md paths
+  const allowedLinks = new Set();
+  structurePlan.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 checkLinks = (text, source) => {
+    let match;
+    while ((match = linkRegex.exec(text)) !== null) {
+      const link = match[2];
+      const trimLink = link.trim();
+
+      // Only check links that processContent would process
+      // Exclude external links and mailto
+      if (/^(https?:\/\/|mailto:)/.test(trimLink)) continue;
+
+      // Preserve anchors
+      const [path, hash] = trimLink.split("#");
+
+      // Only process relative paths or paths starting with /
+      if (!path) continue;
+
+      // Check if this link is in the allowed links set
+      if (!allowedLinks.has(trimLink)) {
+        isApproved = false;
+        detailFeedback.push(
+          `Found a dead link in ${source}: [${match[1]}](${trimLink}), ensure the link exists in the structure plan path`
+        );
+      }
+    }
+  };
+
+  const checkTableSeparators = (text, source) => {
+    // Split text into lines and check each line
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (tableSeparatorRegex.test(line)) {
+        isApproved = false;
+        detailFeedback.push(
+          `Found an incorrect table separator in ${source} at line ${
+            i + 1
+          }: ${line.trim()}`
+        );
+      }
+    }
+  };
+
+  const checkSingleLine = (text, source) => {
+    // Count newline characters to check if content is only on one line
+    const newlineCount = (text.match(/\n/g) || []).length;
+    if (newlineCount === 0 && text.trim().length > 0) {
+      isApproved = false;
+      detailFeedback.push(
+        `Found single line content in ${source}: content appears to be on only one line, check for missing line breaks`
+      );
+    }
+  };
+
+  const checkCodeBlockIndentation = (text, source) => {
+    // Split text into lines and check each line
+    const lines = text.split("\n");
+    let inCodeBlock = false;
+    let codeBlockIndentLevel = 0;
+    let codeBlockStartLine = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Check if this line is a code block marker
+      if (codeBlockRegex.test(line)) {
+        if (!inCodeBlock) {
+          // Starting a new code block
+          inCodeBlock = true;
+          codeBlockStartLine = i + 1;
+          // Calculate indentation level of the code block marker
+          const match = line.match(/^(\s*)(```)/);
+          codeBlockIndentLevel = match ? match[1].length : 0;
+        } else {
+          // Ending the code block
+          inCodeBlock = false;
+          codeBlockIndentLevel = 0;
+        }
+        continue;
+      }
+
+      // If we're inside a code block, check if content has proper indentation
+      if (inCodeBlock) {
+        const contentIndentLevel = line.match(/^(\s*)/)[1].length;
+
+        // If code block marker has indentation, content should have at least the same indentation
+        if (
+          codeBlockIndentLevel > 0 &&
+          contentIndentLevel < codeBlockIndentLevel
+        ) {
+          isApproved = false;
+          detailFeedback.push(
+            `Found code block with inconsistent indentation in ${source} at line ${codeBlockStartLine}: code block marker has ${codeBlockIndentLevel} spaces indentation but content at line ${
+              i + 1
+            } has only ${contentIndentLevel} spaces indentation`
+          );
+          // Reset to avoid multiple errors for the same code block
+          inCodeBlock = false;
+          codeBlockIndentLevel = 0;
+        }
+      }
+    }
+  };
+
+  // Check content
+  checkLinks(reviewContent, "result");
+  checkTableSeparators(reviewContent, "result");
+  checkSingleLine(reviewContent, "result");
+  checkCodeBlockIndentation(reviewContent, "result");
+
+  return {
+    isApproved,
+    detailFeedback: detailFeedback.join("\n"),
+  };
+}

package/agents/check-structure-planning-result.yaml

@@ -0,0 +1,30 @@
+name: check-structure-planning-result
+description: 对 structure-planning agent 生成的结果进行检查，确保其符合预期，特别是在有上一轮生成结果和用户反馈的场景下。
+instructions:
+  url: ../prompts/check-structure-planning-result.md
+input_schema:
+  type: object
+  properties:
+    structurePlan:
+      $ref: ./schema/structure-plan.yaml
+      description: 新一轮生成的结构规划。
+    originalStructurePlan:
+      $ref: ./schema/structure-plan.yaml
+      description: 上一轮生成的结构规划，用于对比。如果不存在，则检查默认通过。
+    structurePlanFeedback:
+      type: string
+      description: 用户针对上一轮结果提供的反馈。
+  required:
+    - structurePlan
+output_schema:
+  type: object
+  properties:
+    isValid:
+      type: boolean
+      description: 检查是否通过。true 表示通过，false 表示不通过。
+    structureReviewFeedback:
+      type: string
+      description: 检查结果的详细说明。如果不通过，需要明确指出哪里不符合要求。
+  required:
+    - isValid
+    - structureReviewFeedback

package/agents/check-structure-planning.mjs

@@ -0,0 +1,54 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AnthropicChatModel } from "@aigne/anthropic";
+import { AIGNE } from "@aigne/core";
+import { GeminiChatModel } from "@aigne/gemini";
+import { OpenAIChatModel } from "@aigne/openai";
+
+// Get current script directory
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default async function checkStructurePlanning(
+  { originalStructurePlan, structurePlanFeedback, ...rest },
+  options
+) {
+  // If originalStructurePlan exists, return directly
+  if (originalStructurePlan && !structurePlanFeedback) {
+    return {
+      structurePlan: originalStructurePlan,
+    };
+  }
+
+  const aigne = await AIGNE.load(join(__dirname, "../"), {
+    models: [
+      {
+        name: OpenAIChatModel.name,
+        create: (params) => new OpenAIChatModel({ ...params }),
+      },
+      {
+        name: AnthropicChatModel.name,
+        create: (params) => new AnthropicChatModel({ ...params }),
+      },
+      {
+        name: GeminiChatModel.name,
+        create: (params) => new GeminiChatModel({ ...params }),
+      },
+    ],
+  });
+
+  const panningAgent = aigne.agents["reflective-structure-planner"];
+
+  const result = await options.context.invoke(panningAgent, {
+    structurePlanFeedback,
+    originalStructurePlan,
+    ...rest,
+  });
+
+  return {
+    ...result,
+    structurePlanFeedback,
+    originalStructurePlan: originalStructurePlan
+      ? originalStructurePlan
+      : JSON.parse(JSON.stringify(result.structurePlan || [])),
+  };
+}

package/agents/content-detail-generator.yaml

@@ -0,0 +1,50 @@
+name: content-detail-generator
+description: 通用内容详情生成器，支持网站、文档、书籍、演示文稿等多种场景
+instructions:
+  url: ../prompts/content-detail-generator.md
+input_schema:
+  type: object
+  properties:
+    rules:
+      type: string
+      description: 用户的结构规划的要求
+    locale:
+      type: string
+      description: 用户语言，如 zh、en
+    datasources:
+      type: string
+      description: 结构规划的上下文，用于辅助结构规划
+    targetAudience:
+      type: string
+      description: 结构规划的目标受众
+    nodeName:
+      type: string
+      description: 结构规划的节点名称
+    originalStructurePlan: ./schema/structure-plan.yaml
+    title:
+      type: string
+    description:
+      type: string
+    path:
+      type: string
+    parentId:
+      type:
+        - string
+        - "null"
+    glossary:
+      type: string
+      description: 术语表
+    additionalInformation:
+      type: string
+      description: 额外补充信息
+  required:
+    - rules
+    - datasources
+    - originalStructurePlan
+output_schema:
+  type: object
+  properties:
+    content:
+      type: string
+  required:
+    - content

package/agents/detail-generator-and-translate.yaml

@@ -0,0 +1,88 @@
+type: team
+name: detail-generator-and-translate
+description: 生成文档详情并翻译
+skills:
+  - ./transform-detail-datasources.mjs
+  - type: team
+    skills:
+      - ./content-detail-generator.yaml
+      - type: transform
+        jsonata: |
+          $merge([
+            $,
+            { "reviewContent": content }
+          ])
+    reflection:
+      reviewer: ./check-detail-result.mjs
+      is_approved: isApproved
+      max_iterations: 3
+      return_last_on_max_iterations: true
+  - ./batch-translate.yaml
+  - ./save-single-doc.mjs
+input_schema:
+  type: object
+  properties:
+    nodeName:
+      type: string
+      description: 节点名称
+      default: Section
+    locale:
+      type: string
+      description: 语言
+    targetAudience:
+      type: string
+      description: 目标受众
+    glossary:
+      type: string
+      description: 术语表
+    currentPath:
+      type: string
+      description: 当前路径
+    feedback:
+      type: string
+      description: 反馈
+    sources:
+      type: array
+      items:
+        type: string
+        description: 源码路径
+    sourcesPath:
+      type: array
+      items:
+        type: string
+        description: 源码路径
+      default:
+        - ./
+    includePatterns:
+      type: array
+      items:
+        type: string
+        description: 包含的文件名
+    excludePatterns:
+      type: array
+      items:
+        type: string
+        description: 排除的文件名
+    outputDir:
+      type: string
+      description: 输出目录
+      default: ./aigne-docs/output
+    docsDir:
+      type: string
+      description: 文档目录
+      default: ./aigne-docs/docs
+    additionalInformation:
+      type: string
+      description: 额外补充信息
+output_schema:
+  type: object
+  properties:
+    title:
+      type: string
+    description:
+      type: string
+    path:
+      type: string
+    content:
+      type: string
+mode: sequential