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

package/LICENSE

@@ -1,93 +0,0 @@
-Elastic License 2.0
-
-URL: https://www.elastic.co/licensing/elastic-license
-
-## Acceptance
-
-By using the software, you agree to all of the terms and conditions below.
-
-## Copyright License
-
-The licensor grants you a non-exclusive, royalty-free, worldwide,
-non-sublicensable, non-transferable license to use, copy, distribute, make
-available, and prepare derivative works of the software, in each case subject to
-the limitations and conditions below.
-
-## Limitations
-
-You may not provide the software to third parties as a hosted or managed
-service, where the service provides users with access to any substantial set of
-the features or functionality of the software.
-
-You may not move, change, disable, or circumvent the license key functionality
-in the software, and you may not remove or obscure any functionality in the
-software that is protected by the license key.
-
-You may not alter, remove, or obscure any licensing, copyright, or other notices
-of the licensor in the software. Any use of the licensor’s trademarks is subject
-to applicable law.
-
-## Patents
-
-The licensor grants you a license, under any patent claims the licensor can
-license, or becomes able to license, to make, have made, use, sell, offer for
-sale, import and have imported the software, in each case subject to the
-limitations and conditions in this license. This license does not cover any
-patent claims that you cause to be infringed by modifications or additions to
-the software. If you or your company make any written claim that the software
-infringes or contributes to infringement of any patent, your patent license for
-the software granted under these terms ends immediately. If your company makes
-such a claim, your patent license ends immediately for work on behalf of your
-company.
-
-## Notices
-
-You must ensure that anyone who gets a copy of any part of the software from you
-also gets a copy of these terms.
-
-If you modify the software, you must include in any modified copies of the
-software prominent notices stating that you have modified the software.
-
-## No Other Rights
-
-These terms do not imply any licenses other than those expressly granted in
-these terms.
-
-## Termination
-
-If you use the software in violation of these terms, such use is not licensed,
-and your licenses will automatically terminate. If the licensor provides you
-with a notice of your violation, and you cease all violation of this license no
-later than 30 days after you receive that notice, your licenses will be
-reinstated retroactively. However, if you violate these terms after such
-reinstatement, any additional violation of these terms will cause your licenses
-to terminate automatically and permanently.
-
-## No Liability
-
-*As far as the law allows, the software comes as is, without any warranty or
-condition, and the licensor will not be liable to you for any damages arising
-out of these terms or the use or nature of the software, under any kind of
-legal claim.*
-
-## Definitions
-
-The **licensor** is the entity offering these terms, and the **software** is the
-software the licensor makes available under these terms, including any portion
-of it.
-
-**you** refers to the individual or entity agreeing to these terms.
-
-**your company** is any legal entity, sole proprietorship, or other kind of
-organization that you work for, plus all organizations that have control over,
-are under the control of, or are under common control with that
-organization. **control** means ownership of substantially all the assets of an
-entity, or the power to direct its management and policies by vote, contract, or
-otherwise. Control can be direct or indirect.
-
-**your licenses** are all the licenses granted to you for the software under
-these terms.
-
-**use** means anything you do with the software requiring one of your licenses.
-
-**trademark** means trademarks, service marks, and similar rights.

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

@@ -1,53 +0,0 @@
-### 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/completer.md

@@ -1,54 +0,0 @@
-You are an intelligent assistant that synthesizes and presents the results of completed tasks.
-
-{% if $afs.enabled %}
-## Environment
-
-### AFS
-{{ $afs.description }}
-
-${"```"}yaml alt="The modules available in the AFS"
-{{ $afs.modules | yaml.stringify }}
-${"```"}
-{% endif %}
-
-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.
-
-## User's Objective
-
-${"```"}txt alt="The user's latest objective you need to address"
-{{ 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 }}
-```
-
-## Your Task
-Based on the execution results above, provide a comprehensive and helpful response to the user's objective.

package/agentic-agents/common/planner.md

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

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

@@ -1,129 +0,0 @@
-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: ai
-      instructions:
-        url: ../common/completer.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
-
-    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

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

@@ -1,27 +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() {
-  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,
-  };
-}