@aigne/doc-smith 0.9.7 → 0.9.8-alpha.1

package/agentic-agents/structure/index.yaml

@@ -0,0 +1,63 @@
+type: team
+name: GenerateStructure
+# model: anthropic/claude-opus-4-5-20251101
+description: Generate the structure of your documentation
+input_schema:
+  type: object
+  properties:
+    rules:
+      type: string
+      description: Your specific requirements for documentation structure
+    locale:
+      type: string
+      description: Primary language for documentation (e.g., zh, en, ja)
+    task:
+      type: string
+      description: Task related to this documentation structure
+skills:
+  - ../utils/load-base-sources.mjs
+  - ./set-custom-prompt.mjs
+  - type: "@aigne/agent-library/orchestrator"
+    objective:
+      url: objective.md
+    planner:
+      type: ai
+      model: anthropic/claude-opus-4-5-20251101
+      instructions:
+        url: ../common/planner.md
+      input_schema:
+        type: object
+        properties:
+          plannerInitState:
+            type: string
+            description: The initial state of the planner
+          customPlannerPrompt:
+            type: string
+            description: The custom planner prompt
+    worker:
+      type: ai
+      instructions:
+        url: ../common/worker.md
+      input_schema:
+        type: object
+        properties:
+          domainKnowledge:
+            type: string
+            description: The domain knowledge
+    completer:
+      type: function
+      process: |
+        let message = 'All tasks have been completed.';
+        return { message };
+    afs:
+      modules:
+        - module: local-fs
+          options:
+            name: workspace
+            localPath: .
+            description: The target repository containing source code and documentation. Read-only, cannot be modified.
+        - module: local-fs
+          options:
+            name: doc-smith
+            localPath: .aigne/doc-smith
+            description: The Doc Smith workspace for storing intermediate and output files

package/agentic-agents/structure/objective.md

@@ -0,0 +1,14 @@
+{{ task }}
+
+我对文档的要求：
+以 {{ locale }} 语言输出内容
+{% if rules %}
+{{ rules }}
+{% endif %}
+
+设计要求:
+{% include "design-rules.md" %}
+
+质量审查标准:
+
+{% include "review-criteria.md" %}

package/agentic-agents/structure/review-criteria.md

@@ -0,0 +1,55 @@
+
+1. **YAML Format Correctness** - Automatic rejection if:
+   - Indentation is not exactly 2 spaces per level
+   - Missing spaces after colons (e.g., `title:"value"` instead of `title: "value"`)
+   - List items don't start with `- ` (dash + space)
+   - Special characters are not properly quoted
+   - Any YAML syntax errors that would cause parsing to fail
+
+2. **Valid sourcePaths** - Automatic rejection if:
+   - ANY `sourcePaths` entry contains a directory path (e.g., `src/`, `docs/`)
+   - ANY `sourcePaths` entry includes the `/modules/workspace` prefix
+   - ANY `sourcePaths` entry uses absolute paths
+   - ✅ Valid examples: `README.md`, `src/index.ts`, `docs/api.md`
+   - ❌ Invalid examples: `src/`, `/modules/workspace/README.md`, `/absolute/path/file.ts`
+
+3. **Project Domain Focus** - Automatic rejection if:
+   - Structure includes build/tooling documentation for non-build-tool projects (e.g., "Webpack Configuration", "CI/CD Pipeline", "ESLint Rules")
+   - Documentation focuses on internal development infrastructure instead of project features
+   - ✅ Approve: Project features, APIs, architecture, usage guides, domain concepts
+   - ❌ Reject: Build configs, CI/CD, linting setup (unless the project IS a build tool)
+
+## Quality Assessment Checks
+
+4. **Adequate Coverage and Depth**
+   - Reject if structure is too minimal (only 1-2 sections for non-trivial projects)
+   - Reject if missing obvious sections (e.g., no API docs for a library, no getting-started guide)
+   - Approve if structure has appropriate breadth and depth
+
+5. **Project Priorities Alignment**
+   - Reject if structure ignores key features emphasized in README/documentation
+   - Approve if key features from README have dedicated sections
+
+6. **Multi-Package/Monorepo Structure** (if applicable)
+   - Reject if ANY package section lacks nested children subsections
+   - Approve if each package has its own section with children organizing package-specific docs
+
+7. **No Duplicate Sections**
+   - Reject if multiple sections have the same purpose without clear differentiation
+
+8. **Clear Section Purposes**
+   - Reject if section titles are vague (e.g., "Other", "Misc", "Files")
+
+## Review Decision Making
+
+**If user feedback exists**:
+- ONLY verify that structure changes address the user's specific feedback
+- Ignore all standard quality criteria
+- Approve if user's requirements are met, even if other issues exist
+
+**If no user feedback**:
+- Apply all quality criteria strictly
+- Reject if any critical validation fails
+- Reject if multiple quality issues exist
+
+**If rejected**: Loop back to design phase and regenerate based on review feedback

package/agentic-agents/structure/set-custom-prompt.mjs

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// FIXME: 临时使用这种方式设置自定义变量，框架优化后需要修改
+export default function getCustomPrompt({ structureContent }) {
+  let finalStructureContent = "文档结构未生成";
+  if (structureContent) {
+    finalStructureContent = `
+\`\`\`yaml\n${structureContent}\n\`\`\`
+    `;
+  }
+  const plannerInitState = `
+文档结构(/modules/doc-smith/output/document_structure.yaml):
+${finalStructureContent}
+  `;
+
+  const customPlannerPrompt = `
+- 文档结构生成之后，需要按照'质量审查标准'，进行质量审查，并修复发现的问题
+- 关键: 在保存 YAML 文件之前,严格验证格式:
+
+✅ **正确格式示例:**
+\`\`\`yaml
+project:
+  title: "我的项目"
+  description: "项目的简要描述"
+
+documents:
+  - title: "概览"
+    description: "项目介绍"
+    path: /overview.md
+    sourcePaths:
+      - README.md
+      - docs/intro.md
+    children: []
+  - title: "API 参考"
+    description: "完整的 API 文档"
+    path: /api-Reference.md
+    sourcePaths:
+      - docs/api.md
+    children:
+      - title: "核心 API"
+        path: /core-api.md
+        description: "核心功能"
+        sourcePaths:
+          - docs/api/core.md
+        children: []
+\`\`\`
+
+❌ **要避免的常见错误:**
+1. 冒号后缺少空格: \`title:"测试"\` (错误) → \`title: "测试"\` (正确)
+2. 错误的缩进: 每级必须恰好 2 个空格
+3. 列表项缺少破折号: \`documents: title: "测试"\` (错误) → \`documents: - title: "测试"\` (正确)
+4. sourcePaths 中的目录路径: \`sourcePaths: - src/\` (错误) → \`sourcePaths: - src/index.ts\` (正确)
+5. 包含模块前缀: \`/modules/workspace/README.md\` (错误) → \`README.md\` (正确)
+
+  `;
+
+  const baseInfoPath = path.join(__dirname, "../common/base-info.md");
+  const baseInfo = fs.readFileSync(baseInfoPath, "utf-8");
+
+  const domainKnowledge = `
+  ${baseInfo}
+
+  ### 使用用文档相关的 Skill 完成任务
+  文档结构相关的任务使用：GenerateStructure
+  文档内容相关的任务使用：GenerateDetail
+    `;
+
+  return {
+    plannerInitState,
+    customPlannerPrompt,
+    domainKnowledge,
+  };
+}

package/agentic-agents/utils/load-base-sources.mjs

@@ -0,0 +1,96 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+async function buildDirectoryTree(dirPath) {
+  const entries = [];
+
+  async function scanDir(currentPath, relativePath = "") {
+    try {
+      const items = await readdir(currentPath);
+
+      for (const item of items) {
+        const fullPath = join(currentPath, item);
+        const itemRelativePath = relativePath ? `${relativePath}/${item}` : `/${item}`;
+        const stats = await stat(fullPath);
+
+        entries.push({
+          path: itemRelativePath,
+          isDirectory: stats.isDirectory(),
+        });
+
+        if (stats.isDirectory()) {
+          await scanDir(fullPath, itemRelativePath);
+        }
+      }
+    } catch {
+      // 忽略读取错误
+    }
+  }
+
+  await scanDir(dirPath);
+  return entries;
+}
+
+function buildTreeView(entries) {
+  const tree = {};
+  const entryMap = new Map();
+
+  for (const entry of entries) {
+    entryMap.set(entry.path, entry);
+    const parts = entry.path.split("/").filter(Boolean);
+    let current = tree;
+
+    for (const part of parts) {
+      if (!current[part]) {
+        current[part] = {};
+      }
+      current = current[part];
+    }
+  }
+
+  function renderTree(node, prefix = "", currentPath = "") {
+    let result = "";
+    const keys = Object.keys(node);
+    keys.forEach((key, index) => {
+      const isLast = index === keys.length - 1;
+      const fullPath = currentPath ? `${currentPath}/${key}` : `/${key}`;
+      const entry = entryMap.get(fullPath);
+
+      const suffix = entry?.isDirectory ? "/" : "";
+      result += `${prefix}${isLast ? "└── " : "├── "}${key}${suffix}`;
+      result += "\n";
+      result += renderTree(node[key], `${prefix}${isLast ? "    " : "│   "}`, fullPath);
+    });
+    return result;
+  }
+
+  return renderTree(tree);
+}
+
+export default async function loadBaseSources() {
+  const cwd = process.cwd();
+  const docSmithPath = join(cwd, ".aigne/doc-smith");
+  const structureFilePath = join(docSmithPath, "output/document_structure.yaml");
+
+  // 读取 document_structure.yaml 文件内容
+  let structureContent = "";
+  try {
+    structureContent = await readFile(structureFilePath, "utf-8");
+  } catch {
+    // 文件不存在时忽略错误
+  }
+
+  // 读取 .aigne/doc-smith 目录结构
+  let directoryTree = "";
+  try {
+    const entries = await buildDirectoryTree(docSmithPath);
+    directoryTree = buildTreeView(entries);
+  } catch {
+    // 目录不存在时忽略错误
+  }
+
+  return {
+    structureContent,
+    directoryTree,
+  };
+}

package/agents/create/analyze-diagram-type-llm.yaml

@@ -0,0 +1,160 @@
+name: analyzeDiagramTypeLLM
+description: Analyze document content using LLM to determine diagram type and select appropriate style
+model:
+  reasoning_effort: 1
+instructions: |
+  You are an AI assistant specialized in technical documentation visualization. Your task is to analyze a document segment and generate a structured visual plan for an image generator.
+
+  {% if feedback %}
+  **CRITICAL: User Feedback (HIGHEST PRIORITY)**
+  <feedback>
+  {{ feedback }}
+  </feedback>
+  
+  **IMPORTANT**: User feedback has the **HIGHEST PRIORITY** in all decision-making. Any explicit requests in the feedback (e.g., diagram type, style, colors, aspect ratio, size, layout preferences) must be respected and applied. Additionally, extract and note any other feedback information (such as color preferences, size requirements, layout specifications, etc.) that should be passed to subsequent image generation steps.
+  {% endif %}
+
+  Your responsibilities:
+
+  1. **Analyze Context**: Understand the document’s content, structure, and its purpose, especially around where the diagram will be inserted.
+
+  2. **Generate Document Summary**:
+    **CRITICAL**: The documentSummary will be the **only input** passed to the image generation model. Preserve as much information as possible, only removing content that is truly useless for diagram generation.
+
+    **What to PRESERVE (keep as much as possible):**
+    - **All structural elements**: Headings, sections, hierarchy, ordering, and document structure
+    - **All entities and components**: Names, roles, services, modules, actors, objects, and any elements that could appear as nodes
+    - **All relationships and connections**: How entities relate, data flows, dependencies, interactions, and any connections
+    - **All process flows and steps**: Sequential steps, decision points, workflows, logical order, and any process information
+    - **All labels and names**: All names, labels, identifiers, and terminology used in the document
+    - **Technical details**: Specifications, protocols, interfaces, configurations, and technical information
+    - **Examples and use cases**: Concrete examples, scenarios, and use cases that illustrate the concepts
+    - **Contextual information**: Explanatory text, background context, and descriptions that help understand relationships
+    - **All content that could inform diagram structure**: Any information that might be relevant for creating accurate diagrams
+
+    **What to REMOVE (only truly useless content):**
+    - **Verbatim duplicates**: Exact duplicate sentences or paragraphs that repeat the same information
+    - **Completely off-topic content**: Content that has no relation to the diagram subject matter
+    - **Pure marketing/promotional text**: Sales language that doesn't contain technical or structural information
+    - **Unrelated notes or comments**: Comments that are completely unrelated to the document's main content
+
+    **Summary Guidelines:**
+    - **Preserve the vast majority of content** - only remove content that is clearly redundant or completely unrelated
+    - Keep the original document structure, hierarchy, and organization
+    - Maintain all technical details, examples, and contextual information
+    - When in doubt, **keep the content** rather than removing it
+    - The summary should be comprehensive and contain all information that could be useful for diagram generation
+
+  3. **Determine Diagram Type**:
+    Choose one of the following types based on the content:
+    - **architecture**: Static system structure (components, containers, services)
+    - **flowchart**: Decision logic, workflows, process steps
+    - **guide**: Tutorials, step-by-step user journeys
+    - **intro**: Concept overviews, mind maps
+    - **sequence**: Time-based interactions between entities
+    - **network**: Logical or physical network topologies
+
+    **Decision Priority (in order):**
+    {% if feedback %}
+    0. **HIGHEST PRIORITY**: Analyze the user feedback carefully. If the feedback explicitly or implicitly specifies a diagram type (e.g., "architecture diagram", "flowchart", "sequence diagram", "流程图", "架构图") → **MUST use that type and override any other considerations**. Use your understanding of natural language to identify the user's intent. The feedback type takes absolute precedence.
+    {% endif %}
+    1. **Content Analysis**: If no type preference is found in feedback, analyze the document content structure and characteristics:
+       - If the document is an **overview** (e.g. titled `# Overview`, describes whole system/project) → use `"architecture"`.
+       - Sequential flow with time-based interactions → `sequence`
+       - Branching logic, decision points, workflows → `flowchart`
+       - User steps/tutorials, guided processes → `guide`
+       - Concept maps, high-level introductions → `intro`
+       - Infrastructure, network topologies → `network`
+
+  4. **Select Diagram Style**:
+    **Decision Priority (in order):**
+    {% if feedback %}
+    0. **HIGHEST PRIORITY**: Analyze the user feedback carefully. If the feedback explicitly or implicitly specifies a diagram style (e.g., "modern style", "hand-drawn", "anthropomorphic", "3d", "flat design", "现代风格", "手绘风格") → **MUST use that style and override any default style**. Use your understanding of natural language to identify the user's style preference. The feedback style takes absolute precedence.
+    {% endif %}
+    {% if defaultStyle %}
+    1. **Default Style**: If no style preference is found in feedback, use the configured default style: `{{ defaultStyle }}`. This is the user's preferred default style from configuration.
+    {% endif %}
+    2. **Content-Based Selection**: If no feedback style and no default style, choose a style appropriate for technical documentation tone based on the content characteristics. You can use any style name that best fits the content, including but not limited to:
+       - Common styles: `modern`, `standard`, `hand-drawn`, `anthropomorphic`, `flat`, `minimalist`, `3d`
+       - Other creative styles: `watercolor`, `sketch`, `vintage`, `cyberpunk`, `minimal`, `realistic`, `cartoon`, `isometric`, `neon`, `pastel`, etc.
+       - You are not limited to predefined styles - use your knowledge of visual styles to select the most appropriate one
+    3. **Available Styles Reference**: If `availableStyles` is provided and not empty, prefer styles from that list. However, if a better style is needed and not in the list, you can still use it. The `styleDescriptions` object provides descriptions of common styles for reference, but you are not restricted to only those styles.
+
+  5. **Recommend Aspect Ratio**:
+    {% if feedback %}
+    **HIGHEST PRIORITY**: If user feedback explicitly specifies an aspect ratio (e.g., "16:9", "4:3", "use landscape", "make it square") → **MUST use that aspect ratio**.
+    {% endif %}
+    
+    Otherwise, select the most suitable aspect ratio based on layout direction:
+    - `"1:1"`: Radial layouts, mind maps, central concepts
+    - `"5:4"` or `"4:3"`: Vertical flows (step-by-step, guides)
+    - `"3:2"`, `"16:9"`, `"21:9"`: Horizontal flows (timelines, architecture)
+
+    **Decision Logic:**
+    - Vertical flows → use `"4:3"` (default), or `"5:4"` for taller needs
+    - Horizontal flows → `"16:9"` (default), `"21:9"` for very wide, `"3:2"` for moderate width
+    - Central hub structures → use `"1:1"`
+
+    **Never** mismatch direction and ratio:
+    - Don't use portrait for horizontal content or vice versa
+    - Don't use `"1:1"` unless layout is truly radial
+
+  Document Content:
+  <document_content>
+  {{ documentContent }}
+  </document_content>
+  
+
+input_schema:
+  type: object
+  properties:
+    documentContent:
+      type: string
+      description: The document content to analyze
+    availableStyles:
+      type: array
+      description: List of available diagram styles
+      items:
+        type: string
+    styleDescriptions:
+      type: object
+      description: Style descriptions
+      additionalProperties:
+        type: string
+    locale:
+      type: string
+      description: Language for labels
+      default: en
+    feedback:
+      type: string
+      description: User feedback that may contain style, type, or other preferences. You should analyze this feedback carefully to extract any explicit or implicit preferences. If feedback specifies a style or type, it MUST override the defaultStyle.
+      default: ""
+    defaultStyle:
+      type: string
+      description: Default diagram style from configuration. Use this only if no style preference is found in feedback. If feedback specifies a style, it takes precedence over this default.
+      nullable: true
+  required:
+    - documentContent
+    - availableStyles
+output_schema:
+  type: object
+  properties:
+    documentSummary:
+      type: string
+      description: A comprehensive summary that preserves the vast majority of the original document content. Only remove verbatim duplicates, completely off-topic content, or pure marketing text. Keep all structural elements, entities, relationships, processes, technical details, examples, and contextual information. This summary will be the only content passed to the image generation model.
+    diagramType:
+      type: string
+      description: The selected diagram type
+    diagramStyle:
+      type: string
+      description: The selected diagram style. Can be any style name (e.g., 'modern', 'hand-drawn', 'watercolor', 'cyberpunk', 'isometric', etc.). Not limited to predefined styles - use your knowledge of visual styles to select the most appropriate one.
+    aspectRatio:
+      type: string
+      description: Recommended aspect ratio for the image based on content structure analysis. MUST match the primary flow direction (vertical→portrait, horizontal→landscape, radial→square)
+      enum: ["1:1", "5:4", "4:3", "3:2", "16:9", "21:9"]
+  required:
+    - documentSummary
+    - diagramType
+    - diagramStyle
+    - aspectRatio
+