@aigne/doc-smith 0.8.5 → 0.8.7

package/aigne.yaml

@@ -6,49 +6,49 @@ chat_model:
   # name: gemini-2.5-flash
   temperature: 0.8
 agents:
-  - ./agents/structure-planning.yaml
-  - ./agents/batch-docs-detail-generator.yaml
-  - ./agents/load-sources.mjs
-  - ./agents/save-docs.mjs
-  - ./agents/translate.yaml
-  - ./agents/detail-generator-and-translate.yaml
-  - ./agents/check-detail.mjs
-  - ./agents/transform-detail-datasources.mjs
-  - ./agents/batch-translate.yaml
-  - ./agents/save-single-doc.mjs
-  - ./agents/save-output.mjs
-  - ./agents/check-structure-plan.mjs
-  - ./agents/content-detail-generator.yaml
-  - ./agents/reflective-structure-planner.yaml
-  - ./agents/check-structure-planning-result.yaml
-  - ./agents/input-generator.mjs
-  - ./agents/docs-generator.yaml
-  - ./agents/detail-regenerator.yaml
-  - ./agents/publish-docs.mjs
-  - ./agents/format-structure-plan.mjs
-  - ./agents/load-config.mjs
-  - ./agents/team-publish-docs.yaml
-  - ./agents/find-item-by-path.mjs
-  - ./agents/retranslate.yaml
-  - ./agents/language-selector.mjs
+  - ./agents/generate/generate-structure.yaml
+  - ./agents/update/batch-generate-document.yaml
+  - ./agents/utils/load-sources.mjs
+  - ./agents/utils/save-docs.mjs
+  - ./agents/translate/translate-document.yaml
+  - ./agents/update/generate-and-translate-document.yaml
+  - ./agents/update/check-document.mjs
+  - ./agents/utils/transform-detail-datasources.mjs
+  - ./agents/translate/translate-multilingual.yaml
+  - ./agents/utils/save-single-doc.mjs
+  - ./agents/utils/save-output.mjs
+  - ./agents/generate/check-need-generate-structure.mjs
+  - ./agents/update/generate-document.yaml
+  - ./agents/generate/refine-document-structure.yaml
+  - ./agents/generate/check-document-structure.yaml
+  - ./agents/init/index.mjs
+  - ./agents/generate/index.yaml
+  - ./agents/update/index.yaml
+  - ./agents/publish/publish-docs.mjs
+  - ./agents/utils/format-document-structure.mjs
+  - ./agents/publish/index.yaml
+  - ./agents/utils/find-item-by-path.mjs
+  - ./agents/translate/index.yaml
+  - ./agents/translate/choose-language.mjs
   - ./docs-mcp/get-docs-structure.mjs
   - ./docs-mcp/get-docs-detail.mjs
   - ./docs-mcp/docs-search.yaml
   - ./docs-mcp/analyze-docs-relevance.yaml
   - ./docs-mcp/read-doc-content.mjs
   - ./docs-mcp/analyze-content-relevance.yaml
-  - ./agents/check-feedback-refiner.mjs
-  - ./agents/feedback-refiner.yaml
-  - ./agents/manage-prefs.mjs
+  - ./agents/utils/check-feedback-refiner.mjs
+  - ./agents/utils/feedback-refiner.yaml
+  - ./agents/prefs/index.mjs
+  - ./agents/chat/index.yaml
 cli:
-  chat: ./agents/chat.yaml
+  chat: ./agents/chat/index.yaml
   agents:
-    - ./agents/input-generator.mjs
-    - ./agents/docs-generator.yaml
-    - ./agents/detail-regenerator.yaml
-    - ./agents/team-publish-docs.yaml
-    - ./agents/retranslate.yaml
-    - ./agents/manage-prefs.mjs
+    - ./agents/init/index.mjs
+    - ./agents/generate/index.yaml
+    - ./agents/update/index.yaml
+    - ./agents/publish/index.yaml
+    - ./agents/translate/index.yaml
+    - ./agents/prefs/index.mjs
 mcp_server:
   agents:
     - ./docs-mcp/get-docs-structure.mjs

package/docs/cli-reference.md

@@ -89,7 +89,7 @@ Analyzes your source code and generates a complete set of documentation based on
 
 | Option | Type | Description |
 |---|---|---|
-| `--feedback` | string | Provides feedback to adjust and refine the overall document structure plan. |
+| `--feedback` | string | Provides feedback to adjust and refine the overall documentation structure. |
 | `--forceRegenerate` | boolean | Discards existing content and regenerates all documentation from scratch. |
 | `--model` | string | Specifies a particular LLM to use for generation (e.g., `openai:gpt-4o`). Overrides the default model. |
 | `--glossary` | string | Path to a glossary file for consistent terminology. Use the format `@path/to/glossary.md`. |

package/docs/features-generate-documentation.md

@@ -90,7 +90,7 @@ While the default `generate` command is sufficient for most use cases, you can u
 | Option              | Description                                                                                                                              | Example                                                              |
 |---------------------|------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
 | `--forceRegenerate` | Deletes all existing documents and regenerates them from scratch. Use this after making significant changes to your source code or configuration. | `aigne doc generate --forceRegenerate`                                 |
-| `--feedback`        | Provides high-level feedback to refine the overall document structure plan, such as adding, removing, or reorganizing sections.           | `aigne doc generate --feedback "Add an API Reference section"`         |
+| `--feedback`        | Provides high-level feedback to refine the overall documentation structure, such as adding, removing, or reorganizing sections.           | `aigne doc generate --feedback "Add an API Reference section"`         |
 | `--model`           | Specifies a particular Large Language Model from AIGNE Hub to use for content generation, allowing you to switch between models.       | `aigne doc generate --model claude:claude-3-5-sonnet`                |
 
 ## What's Next?

package/docs/features-update-and-refine.md

@@ -123,12 +123,12 @@ Key parameters for the `update` command:
 
 ## Optimizing the Overall Structure
 
-Beyond refining the content of individual documents, you can also adjust the overall documentation structure. If a section is missing or the existing organization could be improved, you can provide feedback to the structure planning agent using the `generate` command with the `--feedback` flag.
+Beyond refining the content of individual documents, you can also adjust the overall documentation structure. If a section is missing or the existing organization could be improved, you can provide feedback to improve the documentation structure using the `generate` command with the `--feedback` flag.
 
 This command instructs DocSmith to reconsider the entire document plan based on your new input.
 
 ```bash
-# Regenerate the structure plan with specific feedback
+# Regenerate the documentation structure with specific feedback
 aigne doc generate --feedback "Remove the 'About' section and add a more detailed 'API Reference'."
 ```
 

package/docs-mcp/analyze-docs-relevance.yaml

@@ -1,19 +1,19 @@
 name: analyze-docs-relevance
-description: Analyze which documents in the structure plan are relevant to the user query
+description: Analyze which documents in the document structure are relevant to the user query
 instructions: |
-  You are an AI assistant that analyzes the relevance between a user query and documents in a structure plan.
+  You are an AI assistant that analyzes the relevance between a user query and documents in a document structure.
 
-  <structure-plan>
-  {{ originalStructurePlan }}
-  </structure-plan>
+  <document_structure>
+  {{ originalDocumentStructure }}
+  </document_structure>
 
   <user-query>
   {{ query }}
   </user-query>
 
-  Given a user query and a structure plan containing multiple documents, your task is to:
+  Given a user query and a document structure containing multiple documents, your task is to:
   1. Understand the user's search intent from the query
-  2. Analyze each document in the structure plan to determine relevance
+  2. Analyze each document in the document structure to determine relevance
   3. Return a list of relevant documents with their paths, titles, and descriptions
 
   Consider the following factors for relevance:
@@ -33,7 +33,7 @@ input_schema:
     query:
       type: string
       description: User search query
-    originalStructurePlan:
+    originalDocumentStructure:
       type: array
       items:
         type: object
@@ -44,7 +44,7 @@ input_schema:
             type: string
           description:
             type: string
-      description: Structure plan containing all available documents
+      description: Document structure containing all available documents
 output_schema:
   type: object
   properties:
@@ -52,7 +52,7 @@ output_schema:
       type: array
       items:
         type: string
-        description: Must be selected from paths in the structure plan, cannot be other paths
+        description: Must be selected from paths in the document structure, cannot be other paths
       description: List of relevant documents
     reasoning:
       type: string

package/docs-mcp/docs-search.yaml

@@ -2,8 +2,10 @@ type: team
 name: docs-search
 description: Search relevant documents based on user query
 skills:
-  - ../agents/load-config.mjs
-  - ../agents/load-sources.mjs
+  - url: ../agents/init/index.mjs
+    default_input:
+      skipIfExists: true
+  - ../agents/utils/load-sources.mjs
   - analyze-docs-relevance.yaml
   - read-doc-content.mjs
   - analyze-content-relevance.yaml
@@ -36,5 +38,5 @@ output_schema:
             type: string
           description:
             type: string
-      description: List of relevant documents from structure plan
+      description: List of relevant documents from document structure
 mode: sequential

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "",
   "publishConfig": {
     "access": "public"
@@ -12,13 +12,14 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "MIT",
   "dependencies": {
-    "@aigne/aigne-hub": "^0.8.10",
-    "@aigne/anthropic": "^0.12.3",
-    "@aigne/cli": "^1.44.3",
-    "@aigne/core": "^1.58.3",
-    "@aigne/gemini": "^0.12.3",
-    "@aigne/openai": "^0.14.3",
-    "@aigne/publish-docs": "^0.9.6",
+    "@aigne/aigne-hub": "^0.9.3",
+    "@aigne/anthropic": "^0.13.3",
+    "@aigne/cli": "^1.46.2",
+    "@aigne/core": "^1.60.2",
+    "@aigne/gemini": "^0.13.3",
+    "@aigne/openai": "^0.15.3",
+    "@aigne/publish-docs": "^0.10.0",
+    "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
     "debug": "^4.4.1",
     "dompurify": "^3.2.6",
@@ -43,6 +44,7 @@
   },
   "scripts": {
     "test": "bun test",
+    "test:coverage2": "bun test --coverage",
     "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text",
     "test:watch": "bun test --watch",
     "lint": "biome check",

package/prompts/{document → detail/custom}/custom-code-block.md

@@ -1,4 +1,4 @@
-<custom_code_block>
+<enhanced_code_block_rules>
 ## Enhanced Attributes for Markdown Code Blocks
 
 When generating Markdown, you can add enhanced attributes to code blocks to provide richer functionality and better display effects. These attributes allow you to specify **titles**, **icons**, and more for code blocks.
@@ -20,7 +20,7 @@ The following are the available enhanced attributes and their descriptions:
 
 ### Examples
 
-<good_example>
+<code_block_good_examples>
 The following are some examples of Markdown code blocks using enhanced attributes:
 
 **Example 1: Code block with title and icon**
@@ -70,9 +70,9 @@ class ShoppingCart {
   }
 }
 ```
-</good_example>
+</code_block_good_examples>
 
-<bad_example>
+<code_block_bad_examples>
 **Example 1**
 
 There are two errors in this example:
@@ -97,5 +97,5 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-</bad_example>
-</custom_code_block>
+</code_block_bad_examples>
+</enhanced_code_block_rules>

package/prompts/detail/custom/custom-components.md

@@ -0,0 +1,172 @@
+<custom_components_usage>
+When generating document details, you can use the following custom components at appropriate locations based on their descriptions and functionality to enhance document presentation:
+- `<x-card>`
+- `<x-cards>`
+- `<x-field>`
+
+
+### 1. <x-card> Single Card Component
+Suitable for displaying individual links with a richer and more visually appealing presentation format.
+
+Example:
+
+```
+<x-card data-title="Required Title" data-image="Image URL" data-icon="Icon identifier (e.g., lucide:rocket or material-symbols:rocket-outline)" data-href="Navigation link URL" data-horizontal="true/false" data-cta="Button text" >
+  Card body content
+</x-card>
+```
+
+Attribute Rules:
+
+-	data-title (required): Card title.
+-	data-icon / data-image (choose one, at least one must be provided):
+    -	It's recommended to always provide data-icon.
+    -	Icons should prioritize Lucide (lucide:icon-name). If not available in Lucide, use Iconify (collection:icon-name, e.g., material-symbols:rocket-outline).
+-	data-image (optional): Image URL, can coexist with icon.
+-	data-href (optional): Navigation link for clicking the card or button.
+-	data-horizontal (optional): Whether to use horizontal layout.
+-	data-cta (optional): Button text (call to action).
+-	Body content: 
+  - Must be written within <x-card>...</x-card> children.
+  - **Markdown format rendering is not supported**
+  - **Code block rendering is not supported**
+  - Only supports plain text format without styling
+
+
+### 2. `<x-field>` Structured Field Component
+
+Suitable for displaying API parameters, return values, context data, and any structured data with metadata in a clean, organized format. Supports nested structures for complex data types.
+
+Syntax:
+
+```
+<x-field data-name="field_name" data-type="string" data-default="default_value" data-required="true" data-deprecated="false" data-desc="Field description">
+  <!-- For complex types, children can only be other x-field elements -->
+  <x-field data-name="nested_field" data-type="string" data-desc="Nested field description"></x-field>
+</x-field>
+```
+
+Attribute Rules:
+
+- `data-name` (required): The name of the field/parameter
+- `data-type` (required): The data type of the field (e.g., "string", "number", "boolean", "object", "array")
+- `data-default` (optional): Default value for the field
+- `data-required` (optional): Whether the field is required ("true" or "false")
+- `data-deprecated` (optional): Whether the field is deprecated ("true" or "false")
+- `data-desc` (optional): Description of the field (replaces previous body content)
+- Children: For complex types (object, array), children can only be other `<x-field>` elements. For simple types, children can be empty.
+
+Nesting Rules:
+
+- Maximum nesting depth: 5 levels (to avoid overly complex structures)
+- Children elements must only be `<x-field>` components
+- Use `data-desc` attribute for field descriptions instead of body content
+- **Always use opening/closing tags format**: `<x-field ...></x-field>` for all types
+- For simple types (string, number, boolean), children can be empty: `<x-field ...></x-field>`
+- For complex types (object, array), children contain nested `<x-field>` elements
+
+**Usage Rules:**
+
+- **Context types must use `<x-field>` instead of tables** for consistent formatting
+
+Example:
+
+```
+<!-- Single field -->
+<x-field data-name="user_id" data-type="string" data-default="u0911" data-required="true" data-deprecated="true" data-desc="Unique identifier for the user. Must be a valid UUID v4 format."></x-field>
+
+<!-- Multiple related fields (Props, Parameters, Returns, Context) -->
+<x-field data-name="name" data-type="string" data-required="true" data-desc="The name of the product."></x-field>
+<x-field data-name="description" data-type="string" data-required="false" data-desc="An optional description for the product."></x-field>
+<x-field data-name="type" data-type="string" data-required="false" data-desc="The type of product (e.g., 'service', 'good')."></x-field>
+
+<!-- Complex nested object -->
+<x-field data-name="session" data-type="object" data-required="true" data-desc="User session information containing authentication and permission data">
+    <x-field data-name="auth" data-type="object" data-required="true" data-desc="User authentication information">
+        <x-field data-name="token" data-type="object" data-required="true" data-desc="Access token information">
+            <x-field data-name="access_token" data-type="string" data-required="true" data-default="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." data-desc="JWT access token for API authentication"></x-field>
+            <x-field data-name="refresh_token" data-type="string" data-required="false" data-default="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." data-desc="Refresh token for obtaining new access tokens"></x-field>
+            <x-field data-name="expires_at" data-type="number" data-required="true" data-default="1704067200" data-desc="Token expiration timestamp (Unix timestamp)"></x-field>
+        </x-field>
+        <x-field data-name="user" data-type="object" data-required="true" data-desc="User basic information">
+            <x-field data-name="profile" data-type="object" data-required="true" data-desc="User profile information">
+                <x-field data-name="name" data-type="string" data-required="true" data-default="John Doe" data-desc="User name"></x-field>
+                <x-field data-name="email" data-type="string" data-required="true" data-default="john.doe@example.com" data-desc="User email address"></x-field>
+                <x-field data-name="avatar" data-type="string" data-required="false" data-default="https://example.com/avatars/john-doe.jpg" data-desc="User avatar URL"></x-field>
+            </x-field>
+            <x-field data-name="permissions" data-type="array" data-required="true" data-default='["read", "write", "admin"]' data-desc="User permissions list"></x-field>
+        </x-field>
+    </x-field>
+</x-field>
+```
+
+### 3. `<x-cards>` Card List Component
+
+Suitable for displaying multiple links using a card list format, providing a richer and more visually appealing presentation.
+
+Syntax:
+
+```
+<x-cards data-columns="Number of columns">
+  <x-card data-title="Title 1" data-icon="lucide:rocket">Content 1</x-card>
+  <x-card data-title="Title 2" data-icon="lucide:bolt">Content 2</x-card>
+  <x-card data-title="Title 3" data-icon="material-symbols:rocket-outline">Content 3</x-card>
+</x-cards>
+```
+
+Attribute Rules:
+-	data-columns (optional): Number of columns, integer (e.g., 2, 3). Default is 2.
+-	Must contain multiple <x-card> elements internally.
+-	Consistency requirement: All <x-card> elements within the same <x-cards> must maintain visual consistency:
+    -	Recommended to always provide data-icon for each card.
+    -	Or all cards should have data-image.
+    -	Avoid mixing (some with icons, some with only images).
+
+<custom_components_good_example>
+Use plain text without any styling
+<x-card data-title="alarm()" data-icon="lucide:alarm-clock"> SIGALRM: Sent when a real-time timer has expired.  </x-card>
+
+Single card:
+<x-card data-title="Horizontal card" data-icon="lucide:atom" data-horizontal="true">
+  This is an example of a horizontal card.
+</x-card>
+
+Card list (all using icons, recommended approach):
+<x-cards data-columns="3">
+  <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
+  <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
+  <x-card data-title="Feature 3" data-icon="material-symbols:rocket-outline">Description of Feature 3.</x-card>
+</x-cards>
+
+Card list (all using images):
+<x-cards data-columns="2">
+  <x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
+  <x-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
+</x-cards>
+</custom_components_good_example>
+
+<custom_components_bad_example>
+
+`x-card` component body does not support markdown formatting inline code block
+<x-card data-title="alarm()" data-icon="lucide:alarm-clock"> `SIGALRM`: Sent when a real-time timer has expired.  </x-card>
+
+
+`x-card` component body does not support code blocks
+<x-card data-title="ctrl_break()" data-icon="lucide:keyboard">
+Creates a listener for "ctrl-break" events.
+```rust,no_run
+use tokio::signal::windows::ctrl_break;
+
+#[tokio::main]
+async fn main() -> std::io::Result<()> {
+let mut stream = ctrl_break()?;
+stream.recv().await;
+println!("got ctrl-break");
+Ok(())
+}
+```
+</x-card>
+
+</custom_components_bad_example>
+
+</custom_components_usage>

package/prompts/{document → detail}/d2-chart/rules.md

@@ -613,6 +613,101 @@ Ensure that the shape names used in connections are accurate and match the actua
   Frontend.Uploader-Component -> Backend.Local-Storage-Middleware: "6. Upload file"
   ```
 
+#### Remove redundant connection text
+> If the connection text is redundant with the shape labels, it should be removed to reduce visual clutter.
+
+- **Bad Practice:**
+  ```d2
+  direction: down
+
+  User: {
+    shape: c4-person
+  }
+
+  PaymentProvider-Context: {
+    label: "PaymentProvider Context"
+    shape: rectangle
+    style: {
+      stroke: "#888"
+      stroke-width: 2
+      stroke-dash: 4
+    }
+
+    Entry-Points: {
+      label: "High-Level Components"
+      shape: rectangle
+
+      CheckoutTable: {
+        label: "CheckoutTable"
+      }
+
+      CheckoutDonate: {
+        label: "CheckoutDonate"
+      }
+    }
+
+    Core-Processor: {
+      label: "Core Payment Processor"
+      shape: rectangle
+
+      CheckoutForm: {
+        label: "CheckoutForm"
+      }
+    }
+  }
+
+  User -> PaymentProvider-Context.Entry-Points.CheckoutTable: "Selects a plan"
+  User -> PaymentProvider-Context.Entry-Points.CheckoutDonate: "Makes a donation"
+  PaymentProvider-Context.Entry-Points.CheckoutTable -> PaymentProvider-Context.Core-Processor.CheckoutForm: "Initiates checkout"
+  PaymentProvider-Context.Entry-Points.CheckoutDonate -> PaymentProvider-Context.Core-Processor.CheckoutForm: "Initiates checkout"
+  ```
+- **Good Practice:**
+  ```d2
+  direction: down
+
+  User: {
+    shape: c4-person
+  }
+
+  PaymentProvider-Context: {
+    label: "PaymentProvider Context"
+    shape: rectangle
+    style: {
+      stroke: "#888"
+      stroke-width: 2
+      stroke-dash: 4
+    }
+
+    Entry-Points: {
+      label: "High-Level Components"
+      shape: rectangle
+
+      CheckoutTable: {
+        label: "CheckoutTable"
+      }
+
+      CheckoutDonate: {
+        label: "CheckoutDonate"
+      }
+    }
+
+    Core-Processor: {
+      label: "Core Payment Processor"
+      shape: rectangle
+
+      CheckoutForm: {
+        label: "CheckoutForm"
+      }
+    }
+  }
+
+  User -> PaymentProvider-Context.Entry-Points.CheckoutTable: "Selects a plan"
+  User -> PaymentProvider-Context.Entry-Points.CheckoutDonate: "Makes a donation"
+  PaymentProvider-Context.Entry-Points.CheckoutTable -> PaymentProvider-Context.Core-Processor.CheckoutForm
+  PaymentProvider-Context.Entry-Points.CheckoutDonate -> PaymentProvider-Context.Core-Processor.CheckoutForm
+  ```
+
+
 #### Remove unnecessary grid-columns
 - **Bad Practice:**
   ```d2
@@ -780,7 +875,6 @@ Ensure that the shape names used in connections are accurate and match the actua
     Payment-API -> App.ResumeSubscription.t1: "10. Return latest subscription"
     App.ResumeSubscription.t1 -> App.ResumeSubscription: "11. Call onResumed() & close dialog"
   }
-
   ```
 - **Good Practice:**
   ```d2