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

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

@@ -11,7 +11,7 @@ DocSmith 是一个基于用户提供的数据源，生成文档结构、文档
 提供以下功能：
 - 自动分析 workspace 中的数据源
 - 规划生成文档结构
-- 基于文档结构生成所有文档详情
+- 基于文档结构为所有节点生成文档详情
 - 合理使用数据源中的媒体资源
 
 #### 输出
@@ -47,4 +47,7 @@ documents: // 文档列表
 ```
 
 ##### 文档详情：/modules/doc-smith/docs/xxx.md
-文档详情以 markdown 的格式输出在 /modules/doc-smith/docs 目录中，根据文档的 `path` 生成文件名。
+文档详情以 markdown 的格式输出在 /modules/doc-smith/docs 目录中，根据文档的 `path` 生成文件名。
+
+文档详情要求：
+- 在开头和结尾引导阅读关联文档，并提供关联文档链接

package/agentic-agents/common/planner.md

@@ -1,13 +1,13 @@
-Your responsibility is to decide the next task based on the current execution state.
+Your responsibility is to decide the next tasks 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
+1. **Planner (you)** analyzes the current state and outputs "nextTasks" (one or more tasks)
+2. **Worker** executes the tasks and updates the execution state
+3. **Loop back to step 1**, Planner plans the next tasks based on the new state
+4. **Repeat steps 1-3** until Planner determines the objective is complete
 5. **Planner** sets `finished: true`
 6. **Completer** generates the final report and returns it to the user
 
@@ -22,6 +22,24 @@ You are the Planner in the Orchestrator. The entire Orchestrator completes tasks
 The workspace directory is located at: `/modules/workspace/`
 The DocSmith directory is located at: `/modules/doc-smith/`
 
+## Workspace Directory Structure Cache
+
+To reduce redundant `afs_list` calls, the following is a cached overview of the workspace directory structure:
+
+```yaml alt="The cached directory structure of the workspace"
+{{ $afs.list(workspace, { maxChildren: 50, maxDepth: 10, format: 'tree' }) | yaml.stringify }}
+```
+
+To reduce redundant `afs_list` calls, the following is a cached overview of the doc-smith directory structure:
+```yaml alt="The cached directory structure of the doc-smith"
+{{ $afs.list(doc_smith_workspace, { maxChildren: 50, maxDepth: 10, format: 'tree' }) | yaml.stringify }}
+```
+
+**Important Notes**:
+- Refer to the above directory structure first to avoid redundant `afs_list` calls
+- If you need deeper levels or filtered directories, you can still use the `afs_list` tool
+- If you need to read the contents of multiple files, use multiple afs_read calls at once to read them in batch.
+
 ## Interaction History
 
 ```yaml alt="The history of interactions provide context for planning"
@@ -40,10 +58,13 @@ The DocSmith directory is located at: `/modules/doc-smith/`
 {{ executionState | yaml.stringify }}
 ```
 
-## 初始数据状态
-{{ plannerInitState }}
+## Current Data State
+
+```yaml alt="The latest document structure"
+{{ $afs.read(document_structure_path) | yaml.stringify }}
+```
 
-## How to Plan the Next Task
+## How to Plan the Next Tasks
 
 ### 1. Determine if Tasks Are Needed
 
@@ -76,19 +97,43 @@ If tasks are needed, think about the current state and objective:
 
 ### 3. Decision Principles
 
-- **Plan only one specific task at a time**: Don't try to plan all steps at once
+- **Plan one or more tasks per iteration**: You can output multiple tasks when they are independent
 - **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
+- **Trust the iterative process**: You will be called again after tasks complete, 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
+### 4. Parallel vs Sequential Execution
+
+You can specify whether tasks should run in parallel or sequentially using \`parallelTasks\`.
+
+**IMPORTANT: When tasks run in parallel, they CANNOT see each other's results.** Each parallel task receives the same execution state snapshot from before this batch started.
+
+**Set \`parallelTasks: true\` ONLY when ALL conditions are met:**
+- Tasks operate on **completely independent** data sources or resources
+- Task results are **not needed by other tasks** in the same batch
+- Tasks have **no ordering requirements** between them
+- You are **100% certain** there are no dependencies
+
+**Set \`parallelTasks: false\` (default) when ANY of these apply:**
+- Any task needs results from another task in the same batch
+- Tasks must be executed in a specific order
+- Tasks operate on shared resources that could conflict
+- You are **uncertain** whether tasks are truly independent
+
+**When in doubt, use sequential execution.** It's safer to be slower than to produce incorrect results.
+
+### 5. 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
+- If exploring multiple independent sources, consider parallel execution
+
+**Processing Stage**:
+- Process gathered information
+- Use sequential execution when processing depends on previous results
 
 **Summary Stage**:
 - When sufficient information is collected, plan to generate a summary or report task
@@ -103,13 +148,21 @@ Flexibly decide the next step based on current progress:
 ### Supplementary rules
 {{ customPlannerPrompt }}
 
+## Domain Knowledge
+{{ domainKnowledge }}
 
 ## 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
+nextTasks:            # List of tasks to execute (omit if finished)
+  - "task description 1"
+  - "task description 2"
+parallelTasks: false  # true if tasks can run in parallel, false for sequential (default: false)
+finished: false       # true if objective is achieved and no more tasks 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.
+**Notes:**
+- Task descriptions should be **goal-oriented**, not specifying concrete operations
+- Let the worker autonomously decide how to complete each task
+- Default to sequential execution (\`parallelTasks: false\`) unless you're certain tasks are independent
+- When \`finished: true\`, omit \`nextTasks\`

package/agentic-agents/common/worker.md

@@ -4,6 +4,8 @@ You are a task execution agent. Your job is to execute the specific task assigne
 
 {{ $afs.description }}
 
+When you need to execute multiple AFS operations, you can perform them in batches, such as reading the contents of several required files at the same time.
+
 ```yaml alt="The modules available in the AFS"
 {{ $afs.modules | yaml.stringify }}
 ```
@@ -11,6 +13,34 @@ You are a task execution agent. Your job is to execute the specific task assigne
 The workspace directory is located at: `/modules/workspace/`
 The DocSmith directory is located at: `/modules/doc-smith/`
 
+## Workspace Directory Structure Cache
+
+To reduce redundant `afs_list` calls, the following is a cached overview of the workspace directory structure (up to 3 levels deep):
+
+```yaml alt="The cached directory structure of the workspace"
+{{ $afs.list(workspace, { maxChildren: 50, maxDepth: 10 }) | yaml.stringify }}
+```
+
+```yaml alt="The cached directory structure of the Doc Smith workspace"
+{{ $afs.list(doc_smith_workspace, { maxChildren: 50, maxDepth: 10 }) | yaml.stringify }}
+```
+
+**Important Notes**:
+- Refer to the above directory structure first to avoid redundant `afs_list` calls
+- If you need deeper levels or filtered directories, you can still use the `afs_list` tool
+- If you need to read the contents of multiple files, use multiple afs_read calls at once to read them in batch.
+
+## Prefetched File Contents for Reference
+
+```yaml alt="The prefetched file contents that may help planning"
+{{ $afs.search("/", task, {preset: "predict-resources"}) | yaml.stringify }}
+```
+
+**Important Notes**:
+- Refer to the above prefetched file contents first to avoid redundant `afs_read` calls
+- The files above have been intelligently predicted based on your task and are most likely to be relevant
+- If you need to read additional files not listed above, you can still use the `afs_read` tool
+
 ## User's Objective
 
 ```txt alt="The user's objective provide for context only"
@@ -43,6 +73,18 @@ The DocSmith directory is located at: `/modules/doc-smith/`
 - 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
 
+### Efficient Information Retrieval Strategy
+When your task requires checking directories or reading files:
+1. Check prefetched information first: Review the "Workspace Directory Structure Cache" and "Prefetched File Contents" sections above
+2. Only use tools when necessary: If the required information is already provided, use it directly without making redundant `afs_list` or `afs_read` calls
+3. Batch operations when needed: If you need additional information not already provided, make multiple tool calls at once for efficiency
+
+## Current Data State
+
+```yaml alt="The latest document structure"
+{{ $afs.read(document_structure_path) | yaml.stringify }}
+```
+
 ## Domain Knowledge
 {{ domainKnowledge }}
 

package/agentic-agents/create/index.yaml

@@ -13,11 +13,16 @@ input_schema:
       type: string
       description: 通过 Changeset 描述一批希望执行的变更
   required: []
+default_input:
+  workspace: /modules/workspace
+  doc_smith_workspace: /modules/doc-smith
+  document_structure_path: /modules/doc-smith/output/document_structure.yaml
 
 skills:
   - url: ../../agents/init/index.mjs
     default_input:
       skipIfExists: true
+  # - ../utils/init-workspace-cache.mjs
   - ../utils/load-base-sources.mjs
   - ./set-custom-prompt.mjs
   - type: "@aigne/agent-library/orchestrator"
@@ -26,46 +31,67 @@ skills:
 
     planner:
       type: ai
-      model: anthropic/claude-opus-4-5-20251101
+      model: anthropic/claude-opus-4-5
       instructions:
         url: ../common/planner.md
       input_schema:
         type: object
         properties:
-          plannerInitState:
+          workspace:
             type: string
-            description: The initial state of the planner
+            description: The workspace path
+          doc_smith_workspace:
+            type: string
+            description: The Doc Smith workspace path
+          document_structure_path:
+            type: string
+            description: The document structure path
           customPlannerPrompt:
             type: string
             description: The custom planner prompt
+          domainKnowledge:
+            type: string
+            description: The domain knowledge
 
     worker:
       type: ai
-      # model: anthropic/claude-opus-4-5-20251101
+      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
-      skills:
-        - ../structure/index.yaml
-        - ../detail/index.yaml
+          document_structure_path:
+            type: string
+            description: The document structure path
+      # skills:
+      #   - ../structure/index.yaml
+      #   - ../detail/index.yaml
 
-    completer:
-      type: function
-      process: |
-        let message = 'All tasks have been completed.';
-        return { message };
+    # completer:
+    #   type: function
+    #   process: |
+    #     let message = 'All tasks have been completed.';
+    #     return { message };
 
     state_management:
       max_iterations: 50
       max_tokens: 200000
       keep_recent: 30
 
+    # shareAfs: true
     afs:
+      # storage:
+      #   url: .afs
       modules:
         - module: local-fs
           options:
@@ -76,4 +102,17 @@ skills:
           options:
             name: workspace
             localPath: .
-            description: The target repository containing source code and documentation. Read-only, cannot be modified.
+            description: The target repository containing source code and documentation. Read-only, cannot be modified.
+            ignore:
+              - ".git"
+              - ".aigne"
+      context:
+        search:
+          presets:
+            predict-resources:
+              select:
+                agent: "../predict-resources/index.yaml"
+      # drivers:
+      #   - driver: i18n
+      #     options:
+      #       defaultSourceLanguage: zh

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

@@ -6,22 +6,11 @@ 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}
-  `;
-
+export default function getCustomPrompt() {
   const customPlannerPrompt = `
 - 文档结构相关的任务与文档内容相关的任务需要拆分为独立的任务
 - 你只需要读取少量信息来规划任务，深度的信息读取由 Worker 完成
-- 可以在同一个任务中规划多篇文档的生成/更新任务，Worker 中可以批量处理提升效率
+- changeset 中要求的变更，拆分为独立的任务，由 Worker 完成
   `;
 
   const baseInfoPath = path.join(__dirname, "../common/base-info.md");
@@ -29,14 +18,9 @@ ${finalStructureContent}
 
   const domainKnowledge = `
 ${baseInfo}
-
-### 使用用文档相关的 Skill 完成任务
-文档结构相关的任务使用：GenerateStructure
-文档内容相关的任务使用：GenerateDetail
   `;
 
   return {
-    plannerInitState,
     customPlannerPrompt,
     domainKnowledge,
   };

package/agentic-agents/detail/index.yaml

@@ -22,7 +22,7 @@ input_schema:
 iterate_on: tasks
 concurrency: 5
 skills:
-  - ../utils/load-base-sources.mjs
+  # - ../utils/load-base-sources.mjs
   - ./set-custom-prompt.mjs
   - type: "@aigne/agent-library/orchestrator"
     input_schema:
@@ -41,12 +41,18 @@ skills:
       url: objective.md
     planner:
       type: ai
-      model: anthropic/claude-opus-4-5-20251101
+      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
@@ -55,11 +61,18 @@ skills:
             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

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

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

@@ -0,0 +1,61 @@
+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/index.yaml

@@ -1,6 +1,5 @@
 type: team
 name: GenerateStructure
-# model: anthropic/claude-opus-4-5-20251101
 description: Generate the structure of your documentation
 input_schema:
   type: object
@@ -15,40 +14,58 @@ input_schema:
       type: string
       description: Task related to this documentation structure
 skills:
-  - ../utils/load-base-sources.mjs
+  # - ../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
+      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 = 'All tasks have been completed.';
-        return { message };
+        let message = 'Structure generation completed.';
+        return { task: input.task, message };
     afs:
       modules:
         - module: local-fs
@@ -60,4 +77,10 @@ skills:
           options:
             name: doc-smith
             localPath: .aigne/doc-smith
-            description: The Doc Smith workspace for storing intermediate and output files
+            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

@@ -11,4 +11,4 @@
 
 质量审查标准:
 
-{% include "review-criteria.md" %}
+{% include "review-criteria.md" %}