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

package/agentic-agents/common/base-info.md

@@ -0,0 +1,50 @@
+### DocSmith 基本信息
+DocSmith 是一个基于用户提供的数据源，生成文档结构、文档内容的工具。
+
+#### 输入
+用户提供的任意数据源：
+- 代码仓库
+- 任意格式的文本内容
+- 媒体资源，图片、视频等。
+
+#### 功能
+提供以下功能：
+- 自动分析 workspace 中的数据源
+- 规划生成文档结构
+- 基于文档结构生成所有文档详情
+- 合理使用数据源中的媒体资源
+
+#### 输出
+DocSmith 的所有输出都在 /modules/doc-smith 中，包含以下输出：
+- 文档结构
+- 文档内容
+
+##### 文档结构：/modules/doc-smith/output/document_structure.yaml
+规划需要生成的文档列表、层级关系、每篇文档计划展示的内容。
+数据格式：
+```yaml
+project:
+  title: "xxx" // 项目名称
+  description: "xxx" // 项目描述
+documents: // 文档列表
+  - title: "xxx" // 文档标题
+    description: "xxx" // 文档描述
+    path: "xxx" // 文档路径，示例： /overview.md 、/getting-started.md
+    sourcePaths: // 文件路径数组(不是目录) - 不带 'workspace:' 前缀的相对路径
+      -xxx 
+    icon: "lucide:xxx" // 为一级文档生成 icon ，Must be a valid **Lucide icon name** in the format: `lucide:icon-name`
+  - title: "xxx"
+    description: "xxx"
+    path: "xxx"
+    sourcePaths:
+      -xxx 
+    children: // 子级文档，可嵌套
+      - title: "xxx"
+        description: "xxx"
+        sourcePaths:
+          -xxx 
+        path: "xxx"
+```
+
+##### 文档详情：/modules/doc-smith/docs/xxx.md
+文档详情以 markdown 的格式输出在 /modules/doc-smith/docs 目录中，根据文档的 `path` 生成文件名。

package/agentic-agents/common/planner.md

@@ -0,0 +1,115 @@
+Your responsibility is to decide the next task based on the current execution state.
+
+## Responsibilities
+
+You are the Planner in the Orchestrator. The entire Orchestrator completes tasks through collaboration of three roles:
+
+1. **Planner (you)** analyzes the current state and outputs `nextTask`
+2. **Worker** executes the task and updates the execution state
+3. **Loop back to step 1**, Planner plans the next task based on the new state
+4. **Repeat steps 1-3** until Planner determines the task is complete
+5. **Planner** sets `finished: true`
+6. **Completer** generates the final report and returns it to the user
+
+## Environment
+
+{{ $afs.description }}
+
+```yaml alt="The modules available in the AFS"
+{{ $afs.modules | yaml.stringify }}
+```
+
+The workspace directory is located at: `/modules/workspace/`
+The DocSmith directory is located at: `/modules/doc-smith/`
+
+## Interaction History
+
+```yaml alt="The history of interactions provide context for planning"
+{{ $afs.histories | yaml.stringify }}
+```
+
+## User's Objective
+
+```txt alt="The user's next objective you need to plan for"
+{{ objective }}
+```
+
+## Current Execution State
+
+```yaml alt="The latest execution state"
+{{ executionState | yaml.stringify }}
+```
+
+## 初始数据状态
+{{ plannerInitState }}
+
+## How to Plan the Next Task
+
+### 1. Determine if Tasks Are Needed
+
+First, assess whether the objective requires any tasks at all. Ask yourself:
+
+**Does this objective require tasks?**
+
+Consider if completing the objective needs:
+- **Information gathering**: Does it need to explore directories, read files, or fetch data?
+- **Analysis or processing**: Does it need to analyze code, process data, or perform computations?
+- **State dependency**: Does it depend on information not yet in the execution state?
+
+**Set `finished: true` immediately when:**
+- The objective requires no exploration, analysis, or information gathering
+- The current execution state already contains everything needed to respond
+- The objective is purely conversational without requiring any action
+
+**Plan tasks when:**
+- The objective requires gathering information from the file system, code, or documentation
+- The objective requires analysis, processing, or computation to be performed
+- Additional information must be collected before a complete response can be given
+
+### 2. Analyze Information Requirements
+
+If tasks are needed, think about the current state and objective:
+- What information is needed to complete the objective?
+- Where can this information be obtained from? (directory structure, config files, source code, documentation, etc.)
+- What information has already been collected? What is still missing?
+- Is deeper exploration needed, or is it ready to generate a summary?
+
+### 3. Decision Principles
+
+- **Plan only one specific task at a time**: Don't try to plan all steps at once
+- **Only decide, don't execute**: You only output task descriptions, actual execution is done by the Worker
+- **Trust the iterative process**: You will be called again after each task completes, allowing you to adjust the plan dynamically
+- **Avoid duplicate work**: Review the execution history to understand what has been completed
+- **Goal-oriented descriptions**: Task descriptions should state "what to do", not "how to do it"
+
+### 4. Decision Making at Different Stages
+
+Flexibly decide the next step based on current progress:
+
+**Exploration Stage**:
+- Plan exploration tasks, specifying which directories or files to examine
+- Gradually collect information, focusing on one aspect at a time
+
+**Summary Stage**:
+- When sufficient information is collected, plan to generate a summary or report task
+
+**Completion Stage**:
+- Set `finished: true` when:
+  - The objective doesn't require any tasks (simple greetings, already answered questions)
+  - All necessary tasks are completed
+  - The objective is fully achieved
+- This will trigger the Completer to integrate all information and generate the final report
+
+### Supplementary rules
+{{ customPlannerPrompt }}
+
+
+## Output Format
+
+```yaml
+nextTask: "[task description]" # optional, describe the next task to be performed to achieve the objective, null if no further tasks are needed
+finished: false  # set to true if no further tasks are needed and the objective is achieved
+reasoning: "[brief explanation]"  # optional, explain why this task is needed
+```
+
+Note: Task descriptions should be **goal-oriented**, not specifying concrete operations. Let the worker autonomously decide how to complete the task based on the task objective.

package/agentic-agents/common/worker.md

@@ -0,0 +1,51 @@
+You are a task execution agent. Your job is to execute the specific task assigned to you - nothing more, nothing less.
+
+## Environment
+
+{{ $afs.description }}
+
+```yaml alt="The modules available in the AFS"
+{{ $afs.modules | yaml.stringify }}
+```
+
+The workspace directory is located at: `/modules/workspace/`
+The DocSmith directory is located at: `/modules/doc-smith/`
+
+## User's Objective
+
+```txt alt="The user's objective provide for context only"
+{{ objective }}
+```
+
+**CRITICAL CONSTRAINT**: The objective above is provided ONLY for context. You must NOT attempt to:
+- Solve the entire objective
+- Plan additional steps beyond your current task
+- Make decisions about what should happen next
+- Execute any tasks other than the one explicitly assigned to you below
+
+## Latest Execution State
+
+```yaml alt="The latest execution state for your reference"
+{{ executionState | yaml.stringify }}
+```
+
+## Your Current Task
+
+```txt alt="The specific task you need to execute now"
+{{ task }}
+```
+
+## Important Instructions
+- Focus EXCLUSIVELY on completing the current task described above
+- The task is self-contained - execute it completely and accurately
+- Do NOT perform additional tasks beyond what is specified
+- Do NOT try to determine what should happen after this task
+- Use the available tools and skills to accomplish this specific task
+- Return a clear result that the planner can use to decide the next step
+
+## Domain Knowledge
+{{ domainKnowledge }}
+
+
+## Output Format
+Return your task execution result as a structured response. The output schema will guide you on the required fields.

package/agentic-agents/create/index.yaml

@@ -0,0 +1,79 @@
+type: team
+name: DocSmith
+alias:
+  - run
+description: DocSmith entry point for documentation generation, editing, and translation
+input_schema:
+  type: object
+  properties:
+    message:
+      type: string
+      description: User feedback describing what documentation tasks to perform (natural language)
+    changeset:
+      type: string
+      description: 通过 Changeset 描述一批希望执行的变更
+  required: []
+
+skills:
+  - url: ../../agents/init/index.mjs
+    default_input:
+      skipIfExists: true
+  - ../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
+      # model: anthropic/claude-opus-4-5-20251101
+      instructions:
+        url: ../common/worker.md
+      input_schema:
+        type: object
+        properties:
+          domainKnowledge:
+            type: string
+            description: The domain knowledge
+      skills:
+        - ../structure/index.yaml
+        - ../detail/index.yaml
+
+    completer:
+      type: function
+      process: |
+        let message = 'All tasks have been completed.';
+        return { message };
+
+    state_management:
+      max_iterations: 50
+      max_tokens: 200000
+      keep_recent: 30
+
+    afs:
+      modules:
+        - module: local-fs
+          options:
+            name: doc-smith
+            localPath: .aigne/doc-smith
+            description: The Doc Smith workspace for storing intermediate and output files
+        - module: local-fs
+          options:
+            name: workspace
+            localPath: .
+            description: The target repository containing source code and documentation. Read-only, cannot be modified.

package/agentic-agents/create/objective.md

@@ -0,0 +1,44 @@
+{% if structureContent %}
+文档已在 `/modules/doc-smith`目录下生成：
+1. 检查文档结构中的每篇都已生成了详情，如果有缺失，请为缺失的文档生成详情
+2. 根据我的反馈修改文档
+{% else %}
+请为当前仓库生成文档：
+1. 生成文档结构
+2. 为文档结构中的每篇文档生成详情
+{% endif %}
+
+我对文档的要求:
+文档使用 {{locale }} 语言。
+
+{% if rules %}
+{{ rules }}
+{% endif %}
+
+
+{% if message %}
+我的反馈意见:
+{{ message }}
+{% endif %}
+
+{% if changeset %}
+请分析我反馈的 ChangeSet ，规划任务实施修改:
+```txt
+{{ changeset }}
+```
+{% endif %}
+
+{% if structureContent %}
+检查并处理 PATCH
+搜索文档中的 patch (::: PATCH)，根据 patch 中的要求修改文档，修改完成后删除对应的 patch。
+
+示例：
+::: PATCH
+# Original
+DocSmith 直接修改用户文档并写回到原项目。
+
+# Revised
+DocSmith 永远不直接 touch 用户原始 repo，而是
+在独立 workspace 中生成版本化产物，再通过 patch 合并。
+:::
+{% endif %}

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

@@ -0,0 +1,43 @@
+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 = `
+- 文档结构相关的任务与文档内容相关的任务需要拆分为独立的任务
+- 你只需要读取少量信息来规划任务，深度的信息读取由 Worker 完成
+- 可以在同一个任务中规划多篇文档的生成/更新任务，Worker 中可以批量处理提升效率
+  `;
+
+  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/detail/index.yaml

@@ -0,0 +1,82 @@
+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-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/detail/objective.md

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

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

@@ -0,0 +1,88 @@
+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/structure/design-rules.md

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

@@ -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/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.8-alpha.0",
+  "version": "0.9.8-alpha.1",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
   },
   "files": [
     "agents",
+    "agentic-agents",
     "assets/report-template",
     "docs-mcp",
     "prompts",