@aigne/doc-smith 0.9.8-alpha.3 → 0.9.8-alpha.5

package/agentic-agents/detail/index.yaml

@@ -1,95 +0,0 @@
-type: team
-name: GenerateDetail
-description: Generate or update detailed content for multiple documentation files
-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)
-    tasks:
-      type: array
-      description: Tasks describing which documents to generate/update, including title, path, description, sourcePaths, and task description
-      items:
-        type: object
-        properties:
-          task:
-            type: string
-            description: Task describing which document to generate/update, including title, path, description, sourcePaths, and task description
-iterate_on: tasks
-concurrency: 5
-skills:
-  # - ../utils/load-base-sources.mjs
-  - ./set-custom-prompt.mjs
-  - type: "@aigne/agent-library/orchestrator"
-    input_schema:
-      type: object
-      properties:
-        task:
-          type: string
-          description: Task describing which document to generate/update, including title, path, description, sourcePaths, and task description
-        rules:
-          type: string
-          description: Your specific requirements for documentation content
-        locale:
-          type: string
-          description: Primary language for documentation (e.g., zh, en, ja)
-    objective:
-      url: objective.md
-    planner:
-      type: ai
-      model: anthropic/claude-opus-4-5
-      instructions:
-        url: ../common/planner.md
-      input_schema:
-        type: object
-        properties:
-          workspace:
-            type: string
-            description: The workspace path
-          doc_smith_workspace:
-            type: string
-            description: The Doc Smith workspace path
-          plannerInitState:
-            type: string
-            description: The initial state of the planner
-          customPlannerPrompt:
-            type: string
-            description: The custom planner prompt
-    worker:
-      type: ai
-      model: gemini-3-pro-preview
-      instructions:
-        url: ../common/worker.md
-      input_schema:
-        type: object
-        properties:
-          workspace:
-            type: string
-            description: The workspace path
-          doc_smith_workspace:
-            type: string
-            description: The Doc Smith workspace path
-          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/detail/objective.md

@@ -1,9 +0,0 @@
-目标:
-{{ task }}
-
-我对文档的要求：
-以 {{ locale }} 语言输出内容
-{% if rules %}
-{{ rules }}
-{% endif %}
-

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

@@ -1,88 +0,0 @@
-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 = `
-- 首先确定需要处理的是文档结构中的哪一篇文档
-- 检查文档是否已存在,决定是生成新文档还是更新现有文档
-- 文档详情以 markdown 的格式输出在 /modules/doc-smith/docs 目录中，根据文档的 \`path\` 生成文件名。
-- 读取 sourcePaths 中的文件作为初始上下文，按需求读取更多的相关文件作为上下文
-- 生成文档内容后，review 文档内容，确保符合文档质量标准
-
-  `;
-
-  const baseInfoPath = path.join(__dirname, "../common/base-info.md");
-  const baseInfo = fs.readFileSync(baseInfoPath, "utf-8");
-
-  const domainKnowledge = `
-${baseInfo}
-
-### 文档质量标准
-
-#### 深度要求
-
-每篇文档应该:
-- 基于 sourcePaths 中的数据源生成详细准确的内容
-- 根据需要读取更多相关数据源作为上下文
-- 每个章节应尽可能参考更多相关数据源,使生成的文档详细准确
-
-文档应该是**生产级别、可直接使用**的,而不是简单概述。
-
-#### 必须包含的内容
-
-- **代码示例**: 可运行的完整代码,包含必要的 import 语句
-- **响应数据示例**: 所有接口和方法必须包含响应数据示例
-- **配置参数说明**: 全面解释配置选项和参数,多值参数需解释每个选项的用途
-
-#### 标准结构
-
-每篇文档包含:
-- **标题层级正确**: 总是以一级标题开始，标题层级连续
-- **Opening Hook**: 简洁有力(≤50 词),说明读者将获得什么
-- **引言**: 包含相关文档内链
-- **主体**: 多个小节,含代码示例和说明
-- **总结**: 包含延伸阅读链接(引导阅读其他相关文档)
-
-#### 写作风格
-
-- 简洁、严谨、准确
-- 为人类写作,不是为算法
-- 主动语态优先,可混用被动
-- 直接表达: 发生了什么、为什么重要、如何帮助
-
-#### 信息获取
-
-- workspace 中的数据源需要主动探索和搜索
-- 基于实际找到的信息生成文档
-- 不编造或假设不存在的功能
-
-#### 数据源使用
-
-- 公开产品/技术: 可用已有知识补充
-- 私有产品: 不能编造虚假信息
-- 信息不足: 说明需要更多上下文
-
-  `;
-
-  return {
-    plannerInitState,
-    customPlannerPrompt,
-    domainKnowledge,
-  };
-}

package/agentic-agents/predict-resources/index.yaml

@@ -1,44 +0,0 @@
-type: ai
-name: predictResources
-description: Predict necessary resources for documentation task
-
-instructions:
-  url: ./instructions.md
-
-input_schema:
-  type: object
-  properties:
-    query:
-      type: string
-      description: The user's documentation objective to predict resources for
-    path:
-      type: string
-      description: The workspace path
-
-default_input:
-  path: "/modules/workspace"
-
-output_schema:
-  type: object
-  properties:
-    data:
-      type: array
-      items:
-        type: string
-      description: A list of predicted resources needed for the documentation task, must be absolute file paths within the workspace.
-
-afs:
-  modules:
-    - module: local-fs
-      options:
-        name: workspace
-        localPath: .
-        description: The target repository containing source code and documentation. Read-only, cannot be modified.
-        ignore:
-          - ".git"
-          - ".aigne"
-    - 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/predict-resources/instructions.md

@@ -1,61 +0,0 @@
-You are a resource prediction agent. Your job is to analyze a workspace directory structure and predict which files would be most relevant for a given documentation task.
-
-## Your Responsibility
-
-Given a workspace directory structure and a user's documentation objective, you must:
-1. Analyze the directory structure to understand the project layout
-2. Identify files that are most likely to provide useful context for the documentation task
-3. Return a prioritized list of file paths that should be read
-
-## Workspace Directory Structure
-
-```yaml alt="The cached directory structure of the workspace"
-{{ $afs.list("/modules/workspace", { maxChildren: 50, maxDepth: 10 }) | yaml.stringify }}
-```
-
-```yaml alt="The cached directory structure of the doc-smith"
-{{ $afs.list("/modules/doc-smith", { maxChildren: 50, maxDepth: 10 }) | yaml.stringify }}
-```
-
-## Documentation Objective
-
-```txt alt="The user's objective you should help predict resources for"
-{{ query }}
-```
-
-## Selection Principles
-
-### What to Include
-
-- **Entry points**: Main files, index files, configuration files that define project structure
-- **Core modules**: Files that implement the main functionality related to the objective
-- **Type definitions**: TypeScript types, interfaces, schemas that define data structures
-- **Configuration**: Package.json, tsconfig.json, and other config files that reveal project dependencies and settings
-- **Documentation**: Existing README files, docs that provide context
-- **Examples**: Example files or test files that demonstrate usage patterns
-
-### What to Exclude
-
-- **Generated files**: Build outputs, compiled code, node_modules contents
-- **Binary files**: Images, fonts, compiled assets (unless specifically relevant)
-- **Lock files**: package-lock.json, yarn.lock, pnpm-lock.yaml
-- **Cache/temp files**: .cache, .tmp, dist directories
-- **Redundant files**: If multiple files serve similar purposes, select the most representative ones
-
-### Prioritization Strategy
-
-1. **High priority**: Files directly related to the documentation objective
-2. **Medium priority**: Files that provide structural context (configs, types, main exports)
-3. **Low priority**: Supporting files that may provide additional context
-
-## Important Constraints
-
-- **Return absolute paths**: All paths must be absolute paths within the workspace (e.g., `/modules/workspace/src/index.ts`)
-- **Be selective**: Don't return every file. Focus on quality over quantity - typically 5-20 files is appropriate
-- **Consider file size**: Prefer smaller, focused files over large monolithic ones when possible
-- **No directories**: Return only file paths, not directory paths
-- **Verify existence**: Only return files that exist in the provided directory structure
-
-## Output Format
-
-Return your prediction as a structured response with a `resources` array containing the predicted file paths, ordered by relevance (most relevant first).

package/agentic-agents/structure/design-rules.md

@@ -1,39 +0,0 @@
-
-1. **sourcePaths Must Be Files**: This is CRITICAL - `sourcePaths` must contain only file paths, never directory paths
-   - ✅ Correct: `["README.md", "src/index.ts", "docs/guide.md"]`
-   - ❌ Wrong: `["src/", "docs/", "src/components/"]`
-   - Must be relative paths from workspace root, **without** the `/modules/workspace` prefix
-   - Examples: `src/index.ts`, `README.md`, `package.json`, `docs/api.md`
-
-2. **Prioritize Based on Project Focus**: Use insights from README and docs to guide structure
-   - If README highlights specific features, create dedicated sections for them
-   - If the project emphasizes certain workflows, mirror this in structure
-   - Create documentation that helps users understand what the project owners consider most important
-
-3. **Create a Logical, User-Focused Hierarchy**:
-   - Start with what users need first (overview, quick start, core concepts)
-   - Follow with detailed sections for key features
-   - Include advanced topics and reference material later
-   - Each document section should have a distinct, non-overlapping purpose
-
-4. **Focus on Project Domain, Not Build System**: For code projects, focus documentation on the project's core purpose and functionality, NOT on build/tooling infrastructure
-   - ✅ **Include**: Project features, APIs, architecture, usage guides, domain concepts
-   - ❌ **Exclude**: Build system docs (webpack config, rollup setup, vite config), CI/CD pipelines, development tooling setup, linting/formatting configuration
-   - **Exception**: Only include build/tooling docs if the project IS a build tool
-
-5. **For Multi-Package Projects**: Create hierarchical documentation structure
-   - Start with overview documentation (getting started, architecture overview)
-   - Create a parent section for each package/module with clear naming
-   - Under each package section, add child sections for that package's specific documentation
-   - Include cross-package documentation (how packages interact, dependency graph)
-
-6. **sourcePaths Should Be Comprehensive**:
-   - Include as many related files as possible to ensure quality of subsequent detail generation
-   - If analyzing source code, include related and adjacent source code files
-   - Analyze referenced files within the source code and include them too
-   - **Ensure sourcePaths are never empty** - Do not create document sections without related data sources
-
-7. **Character Length Constraints**:
-   - `project.title`: Must not exceed **40 characters** (all languages count equally)
-   - `project.description`: Must not exceed **160 characters** (all languages count equally)
-   - Ensure generated content is complete and grammatically correct within these constraints

package/agentic-agents/structure/index.yaml

@@ -1,86 +0,0 @@
-type: team
-name: GenerateStructure
-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
-      instructions:
-        url: ../common/planner.md
-      input_schema:
-        type: object
-        properties:
-          isStructureGenerator:
-            type: boolean
-            description: Flag indicating if this is for structure generation
-          workspace:
-            type: string
-            description: The workspace path
-          doc_smith_workspace:
-            type: string
-            description: The Doc Smith workspace path
-          plannerInitState:
-            type: string
-            description: The initial state of the planner
-          customPlannerPrompt:
-            type: string
-            description: The custom planner prompt
-      default_input:
-        isStructureGenerator: true
-    worker:
-      type: ai
-      model: gemini-3-pro-preview
-      instructions:
-        url: ../common/worker.md
-      input_schema:
-        type: object
-        properties:
-          workspace:
-            type: string
-            description: The workspace path
-          doc_smith_workspace:
-            type: string
-            description: The Doc Smith workspace path
-          domainKnowledge:
-            type: string
-            description: The domain knowledge
-    completer:
-      type: function
-      process: |
-        let message = 'Structure generation completed.';
-        return { task: input.task, 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
-      context:
-        search:
-          presets:
-            predict-resources:
-              select:
-                agent: "../predict-resources/index.yaml"

package/agentic-agents/structure/objective.md

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

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

@@ -1,55 +0,0 @@
-
-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

@@ -1,78 +0,0 @@
-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,
-  };
-}