@aigne/doc-smith 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.4](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.3...v0.2.4) (2025-08-07)
+
+
+### Bug Fixes
+
+* polish agent output log ([40a2451](https://github.com/AIGNE-io/aigne-doc-smith/commit/40a245122ce4d8747e5b5dbe88be6986047c38ae))
+
+## [0.2.3](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.2...v0.2.3) (2025-08-07)
+
+
+### Bug Fixes
+
+* polish process info ([#14](https://github.com/AIGNE-io/aigne-doc-smith/issues/14)) ([a4a314f](https://github.com/AIGNE-io/aigne-doc-smith/commit/a4a314f65af25f6012726b782f30895ce4124f52))
+
 ## [0.2.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.1...v0.2.2) (2025-08-07)
 
 

package/README.md

@@ -1,114 +1,213 @@
 # AIGNE DocSmith
 
-AIGNE DocSmith is a powerful, AI-driven documentation generation tool built on the AIGNE Framework. It automates the creation of detailed, structured, and multi-language documentation directly from your source code.
+AIGNE DocSmith is a powerful, AI-driven documentation generation tool built on the [AIGNE Framework](https://www.aigne.io/en/framework). It automates the creation of detailed, structured, and multi-language documentation directly from your source code.
 
-## Features
+## AIGNE Ecosystem
 
-- **Automated Structure Planning:** Intelligently analyzes your codebase to generate a comprehensive and logical document structure.
-- **AI-Powered Content Generation:** Populates the document structure with detailed, high-quality content.
-- **Multi-Language Support:** Seamlessly translates your documentation into multiple languages.
-- **Smart File Management:** Automatically cleans up invalid .md files that are no longer in the structure plan, preventing file accumulation.
-- **Customizable Prompts:** Allows for fine-tuning the output by customizing the prompts used by the AI agents.
-- **Extensible Workflow:** Built with a modular agent-based architecture, making it easy to extend and customize the documentation generation process.
+DocSmith is part of the [AIGNE](https://www.aigne.io) ecosystem, a comprehensive AI application development platform. Here's the architecture overview:
 
-## How It Works
+![AIGNE Ecosystem Architecture](https://www.aigne.io/image-bin/uploads/1a609bad1b46e8bc9bbaaa2d5f587938.png)
 
-AIGNE DocSmith utilizes a chain of AI agents to generate documentation in a three-step process:
+As shown in the diagram, DocSmith integrates seamlessly with other [AIGNE](https://www.aigne.io) components, leveraging the platform's AI capabilities and infrastructure.
 
-1.  **Structure Planning (`structure-planning`):** This agent analyzes the source code and creates a structured plan for the documentation. The plan is defined in `agents/structure-planning.yaml` and uses the prompt in `prompts/structure-planning.md`.
-2.  **Content Detail Generation (`content-detail-generator`):** This agent takes the structured plan and generates detailed content for each section of the documentation. This process is defined in `agents/content-detail-generator.yaml` and guided by the prompt in `prompts/document/detail-generator.md`.
-3.  **Translation (`translate`):** This agent translates the generated documentation into different languages. The translation agent is defined in `agents/translate.yaml` and uses the prompt in `prompts/translator.md`.
+## Features
 
-The main workflow is orchestrated by the `docs-generator` agent, as defined in `agents/docs-generator.yaml`.
+- **Automated Structure Planning:** Intelligently analyzes your codebase to generate a comprehensive and logical document structure.
+- **AI-Powered Content Generation:** Populates the document structure with detailed, high-quality content.
+- **Multi-Language Support:** Seamlessly translates your documentation into 12+ languages including English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Russian, Italian, and Arabic.
+- **AIGNE Hub Integration:** Use AIGNE Hub as your LLM provider without needing your own API keys, with easy switching between different large language models.
+- **Discuss Kit Publishing:** Publish documentation to the official platform at [docsmith.aigne.io](https://docsmith.aigne.io/app/) or your own independently deployed Discuss Kit instance.
+- **Document Update Mechanism:** Automatically detects source code changes and updates documentation accordingly.
+- **Individual Document Optimization:** Regenerate and optimize specific documents with targeted feedback.
 
 ## Getting Started
 
 ### Prerequisites
 
 - Node.js and pnpm
-- AIGNE Framework
+- AIGNE CLI
 
 ### Installation
 
-1.  Clone the repository:
-    ```bash
-    git clone https://github.com/your-username/aigne-doc-smith.git
-    ```
-2.  Install the dependencies:
-    ```bash
-    pnpm install
-    ```
+Install the latest version of AIGNE CLI globally:
+
+```bash
+npm i -g @aigne/cli
+```
+
+Verify the installation:
+
+```bash
+aigne doc -h
+```
+
+That's it! You can now use DocSmith directly through the AIGNE CLI.
+
+### LLM Configuration
+
+DocSmith supports multiple LLM providers through AIGNE Hub:
+
+- **AIGNE Hub (Recommended):** No API key required, easy model switching
+- **Custom API Keys:** Support for OpenAI, Anthropic, and other providers
+
+To use AIGNE Hub, simply run commands without specifying API keys:
+
+```bash
+# Using AIGNE Hub with different models
+aigne doc generate --model google:gemini-2.5-flash
+aigne doc generate --model claude:claude-3-5-sonnet
+aigne doc generate --model openai:gpt-4o
+```
 
 ### Usage
 
-To generate documentation, run the following command:
+#### Generate Documentation
+
+To generate documentation, simply run:
 
 ```bash
-aigne run docs-generator --datasources.source-code-path=/path/to/your/code
+aigne doc generate
 ```
 
-This will initiate the documentation generation process, and the output will be saved in the `output` directory.
+**Smart Auto-Configuration:** If you haven't run `init` before, DocSmith will automatically detect this and guide you through the interactive configuration wizard first. This includes:
+- Document generation rules and style selection
+- Target audience definition
+- Primary and translation language settings
+- Source code path configuration
+- Output directory setup
 
-## Contributing
+**Force Regeneration:** To regenerate all documentation from scratch, use:
 
-Contributions are welcome! Please feel free to submit a pull request or open an issue if you have any suggestions or find any bugs.
+```bash
+aigne doc generate --forceRegenerate
+```
 
-## Test Commands
+This will regenerate all documentation based on the latest source code and configuration.
 
-```shell
+#### Manual Configuration (Optional)
 
-# 初始化
-npx --no doc-smith run --entry-agent init
+If you prefer to set up configuration manually or want to modify existing settings:
 
-# 生成命令
-npx --no doc-smith run --entry-agent generate --model gemini:gemini-2.5-flash
+```bash
+aigne doc init
+```
 
-aigne run --path /Users/lban/arcblock/code/aigne-doc-smith/ --entry-agent generate --model gemini:gemini-2.5-flash --input-forceRegenerate=true
+This will start the interactive configuration wizard directly.
 
-# 重新生成单篇
-npx --no doc-smith run --entry-agent update --input-doc-path bitnet-getting-started
+#### Update Individual Documents
 
-# 结构规划优化
-npx --no doc-smith run --entry-agent generate --input-feedback "补充节点的 sourceIds，确保所有节点 sourceIds 都有值" --model gemini:gemini-2.5-pro
+Optimize specific documents with targeted feedback:
 
+```bash
+# Interactive document selection and update
+aigne doc update
 
-# 发布文档
-npx --no doc-smith run --entry-agent publish
+# Update a specific document
+aigne doc update --doc-path /faq --feedback "Add more comprehensive FAQ entries"
+```
+
+**Interactive Mode:** When run without parameters, `aigne doc update` will present an interactive menu for you to select which document to regenerate and provide feedback.
+
+#### Optimize Structure Planning
 
+Improve the overall documentation structure based on feedback:
 
+```bash
+# Optimize structure with feedback
+aigne doc generate --feedback "Remove About section and add API Reference"
+
+# Regenerate structure with specific improvements
+aigne doc generate --feedback "Add more detailed installation guide and troubleshooting section"
+```
+
+**Structure Optimization:** Use `aigne doc generate` with `--feedback` to refine the overall documentation structure, add new sections, or reorganize existing content.
+
+#### Publishing to Discuss Kit
+
+Publish your documentation to Discuss Kit platforms:
+
+```bash
+# Interactive publishing with platform selection
+aigne doc publish
 ```
 
-使用 `aigne doc` 运行
+**Interactive Publishing:** When run `aigne doc publish` will present an interactive menu for you to choose between:
+- **Official Platform:** [docsmith.aigne.io](https://docsmith.aigne.io/app/)
+- **Self-Hosted Platform:** Your own deployed Discuss Kit instance
+
+
+
+## Supported Languages
+
+DocSmith supports 12 languages with automatic translation:
+
+- English (en)
+- 简体中文 (zh-CN)
+- 繁體中文 (zh-TW)
+- 日本語 (ja)
+- 한국어 (ko)
+- Español (es)
+- Français (fr)
+- Deutsch (de)
+- Português (pt-BR)
+- Русский (ru)
+- Italiano (it)
+- العربية (ar)
+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a pull request or open an issue if you have any suggestions or find any bugs.
+
+## Command Examples
+
+### Basic Usage
 
 ```shell
-# 初始化
+# Interactive setup and configuration
 aigne doc init
 
-# 生成文档
+# Generate documentation with default settings
 aigne doc generate
 
-# 优化结构规划
-aigne doc generate --feedback "删除 About 文档"
+# Generate with specific model
+aigne doc generate --model google:gemini-2.5-flash
 
-# 优化单篇文档
-# 可使用 structure-plan.json 中的 path ，或 Discuss Kit 中访问的 path
-aigne doc update --doc-path /faq --feedback "添加更多的 FAQ" 
+# Force regenerate all documentation from scratch
+aigne doc generate --forceRegenerate
+```
 
-# 发布文档
-aigne doc publish
+### Advanced Usage
 
-# 将文档作为 MCP Server 
-aigne doc serve-mcp
+```shell
+# Update structure with feedback
+aigne doc generate --feedback "Remove About section and add API Reference"
 
+# Update specific document
+aigne doc update --doc-path /faq --feedback "Add more comprehensive FAQ entries"
 ```
 
-## Testing
+### Publishing and Integration
+
+```shell
+# Interactive publishing with platform selection
+aigne doc publish
+
+# Publish to custom Discuss Kit instance
+aigne doc publish --appUrl https://your-discuss-kit-instance.com
 
-运行测试来验证功能：
 
-```bash
-# 测试 saveDocs 方法的文件清理功能
-node tests/test-save-docs.mjs
 ```
 
-更多测试信息请查看 [tests/README.md](tests/README.md)。
+### Development Commands
+
+```shell
+# Development and debugging commands using npx to run local code
+npx --no doc-smith run --entry-agent init
+npx --no doc-smith run --entry-agent generate
+npx --no doc-smith run --entry-agent update 
+npx --no doc-smith run --entry-agent publish
+```
+
+**Development Mode:** These commands use `npx` to run the local code version for development and debugging purposes, bypassing the globally installed CLI.
+

package/agents/batch-translate.yaml

@@ -16,6 +16,7 @@ skills:
       is_approved: isApproved
       max_iterations: 3
       return_last_on_max_iterations: true
+    task_title: Translate '{{ title }}' to '{{ language }}'
 input_schema:
   type: object
   properties:

package/agents/check-detail.mjs

@@ -106,7 +106,7 @@ export default async function checkDetail(
     !sourceIdsChanged &&
     !sourceFilesChanged &&
     !contentValidationFailed &&
-    forceRegenerate !== "true"
+    !forceRegenerate
   ) {
     return {
       path,
@@ -137,3 +137,5 @@ export default async function checkDetail(
     result,
   };
 }
+
+checkDetail.taskTitle = "Check if '{{ title }}' needs regeneration";

package/agents/check-structure-plan.mjs

@@ -47,7 +47,7 @@ export default async function checkStructurePlan(
     originalStructurePlan &&
     !feedback &&
     !shouldRegenerate &&
-    forceRegenerate !== "true"
+    !forceRegenerate
   ) {
     return {
       structurePlan: originalStructurePlan,
@@ -70,3 +70,5 @@ export default async function checkStructurePlan(
       : JSON.parse(JSON.stringify(result.structurePlan || [])),
   };
 }
+
+checkStructurePlan.taskTitle = "Check if structure plan needs regeneration";

package/agents/detail-generator-and-translate.yaml

@@ -17,6 +17,7 @@ skills:
       is_approved: isApproved
       max_iterations: 3
       return_last_on_max_iterations: true
+    task_title: Generate detail for '{{ title }}'
   - ./batch-translate.yaml
   - ./save-single-doc.mjs
 input_schema:

package/agents/docs-generator.yaml

@@ -103,8 +103,8 @@ input_schema:
       type: string
       description: Feedback for structure planning adjustments
     forceRegenerate:
-      type: string
-      description: Force regenerate the documentation
+      type: boolean
+      description: Force regenerate all documentation
     # labels:
     #   type: array
     #   items:

package/agents/publish-docs.mjs

@@ -167,6 +167,8 @@ async function getAccessToken(appUrl) {
         source: `AIGNE DocSmith connect to Discuss Kit`,
         closeOnSuccess: true,
         appName: "AIGNE DocSmith",
+        appLogo:
+          "https://www.aigne.io/image-bin/uploads/a7910a71364ee15a27e86f869ad59009.svg",
         openPage: (pageUrl) => open(pageUrl),
       });
 
@@ -274,7 +276,11 @@ export default async function publishDocs(
     await saveValueToConfig("boardCover", projectInfo.icon);
   }
 
-  const { success, boardId: newBoardId } = await publishDocsFn({
+  const {
+    success,
+    boardId: newBoardId,
+    docsUrl,
+  } = await publishDocsFn({
     sidebarPath,
     accessToken,
     appUrl,
@@ -299,7 +305,13 @@ export default async function publishDocs(
     }
   }
 
-  return {};
+  //   const message = `## ✅ Documentation Published Successfully!
+
+  // Documentation is now available at: \`${docsUrl}\`
+  //   `;
+  return {
+    // message,
+  };
 }
 
 publishDocs.input_schema = {

package/agents/reflective-structure-planner.yaml

@@ -3,6 +3,7 @@ name: reflectiveStructurePlanner
 description: A team of agents that plan the structure of the documentation.
 skills:
   - structure-planning.yaml
+task_title: Plan the structure of the documentation
 reflection:
   reviewer: check-structure-planning-result.yaml
   is_approved: isValid

package/agents/save-docs.mjs

@@ -45,7 +45,42 @@ export default async function saveDocs({
     console.error("Failed to cleanup invalid .md files:", err.message);
   }
 
-  return {};
+  const message = `## ✅ Documentation Generated Successfully!
+
+  Successfully generated **${structurePlan.length}** documents and saved to: \`${docsDir}\`
+
+  ### 🚀 Next Steps
+
+  1. Publish Documentation
+
+     \`\`\`bash
+     aigne doc publish
+     \`\`\`
+
+     Get an online preview link to share with your team
+
+  ### 🔧 Optional Improvements
+
+  1. Update Specific Documents
+
+     \`\`\`bash
+     aigne doc update
+     \`\`\`
+
+     Regenerate content for specific documents
+
+  2. Provide Structure Feedback
+     \`\`\`bash
+     aigne doc generate --feedback "Your feedback on document structure"
+     \`\`\`
+     Improve the overall documentation structure
+
+  ---
+  `;
+
+  return {
+    message,
+  };
 }
 
 /**

package/aigne.yaml

@@ -1,9 +1,8 @@
 #!/usr/bin/env aigne
 
 chat_model:
-  provider: gemini
+  provider: google
   name: gemini-2.5-pro
-  # name: gemini-2.5-flash-preview-05-20
   temperature: 0.8
 agents:
   - ./agents/structure-planning.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "",
   "publishConfig": {
     "access": "public"

package/prompts/document/structure-planning.md

@@ -7,6 +7,7 @@
   - 结构规划要精炼，避免同一个功能被拆为了多个部分，当内容足够复杂，放在一起展示过长影响用户阅读时，考虑拆出子层级
   - **第一层 <= 7 项**，层级 <= 3 级；同一层使用统一语义（动词时态、名词单复数）
   - 如果当前部分是存在子文档，当前文档只展示简要的内容，引导用户到子文档中查看详细的内容
+  - 如果存在测试相关的代码，可以作为生成文档的参考，**不要为测试代码生成文档**
   - 总是在一开始包含下列内容：
     - Overview：简要说明产品能解决什么，产品能提供什么，产品的结构信息，让用户能快速有一个全面的认识，给出下一步的入口，引导用户阅读
     - Getting Started：内容包含安装、最小运行示例，让用户用通过一部分文档，在很短的时间就能跑通一个最简单的示例

package/utils/utils.mjs

@@ -595,7 +595,12 @@ function getDirectoryContents(dirPath, searchTerm = "") {
 
     for (const entry of entries) {
       const entryName = entry.name;
-      const relativePath = path.join(dirPath, entryName);
+
+      // Preserve ./ prefix when dirPath is "./"
+      let relativePath = path.join(dirPath, entryName);
+      if (dirPath?.startsWith("./")) {
+        relativePath = `./${relativePath}`;
+      }
 
       // Filter by search term if provided
       if (