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

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

@@ -0,0 +1,53 @@
+### 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,168 @@
+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 "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
+
+## 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/`
+
+## 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"
+{{ $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 }}
+```
+
+## Current Data State
+
+```yaml alt="The latest document structure"
+{{ $afs.read(document_structure_path) | yaml.stringify }}
+```
+
+## How to Plan the Next Tasks
+
+### 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 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 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. 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
+- 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
+
+**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 }}
+
+## Domain Knowledge
+{{ domainKnowledge }}
+
+## Output Format
+
+```yaml
+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
+```
+
+**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

@@ -0,0 +1,93 @@
+You are a task execution agent. Your job is to execute the specific task assigned to you - nothing more, nothing less.
+
+## Environment
+
+{{ $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 }}
+```
+
+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"
+{{ 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
+
+### 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 }}
+
+
+## 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,118 @@
+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: []
+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"
+    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
+          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: 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
+          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 };
+
+    state_management:
+      max_iterations: 50
+      max_tokens: 200000
+      keep_recent: 30
+
+    # shareAfs: true
+    afs:
+      # storage:
+      #   url: .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.
+            ignore:
+              - ".git"
+              - ".aigne"
+      context:
+        search:
+          presets:
+            predict-resources:
+              select:
+                agent: "../predict-resources/index.yaml"
+      # drivers:
+      #   - driver: i18n
+      #     options:
+      #       defaultSourceLanguage: zh

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,27 @@
+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() {
+  const customPlannerPrompt = `
+- 文档结构相关的任务与文档内容相关的任务需要拆分为独立的任务
+- 你只需要读取少量信息来规划任务，深度的信息读取由 Worker 完成
+- changeset 中要求的变更，拆分为独立的任务，由 Worker 完成
+  `;
+
+  const baseInfoPath = path.join(__dirname, "../common/base-info.md");
+  const baseInfo = fs.readFileSync(baseInfoPath, "utf-8");
+
+  const domainKnowledge = `
+${baseInfo}
+  `;
+
+  return {
+    customPlannerPrompt,
+    domainKnowledge,
+  };
+}

package/agentic-agents/detail/index.yaml

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

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