@aigne/doc-smith 0.8.14-beta.2 → 0.8.15-beta

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.8.15-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14...v0.8.15-beta) (2025-10-21)
+
+
+### Features
+
+* update document publish prompt for better user experience ([#208](https://github.com/AIGNE-io/aigne-doc-smith/issues/208)) ([0726c23](https://github.com/AIGNE-io/aigne-doc-smith/commit/0726c23ed2d47b2126c0896d71922860b7436895))
+
+
+### Bug Fixes
+
+* enforce stricter rules for x-field component and markdown ([#210](https://github.com/AIGNE-io/aigne-doc-smith/issues/210)) ([d69ee53](https://github.com/AIGNE-io/aigne-doc-smith/commit/d69ee53dbd113859a822d3391cc6cbf2f02bb75e))
+
+## [0.8.14](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14-beta.2...v0.8.14) (2025-10-19)
+
 ## [0.8.14-beta.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14-beta.1...v0.8.14-beta.2) (2025-10-19)
 
 

package/agents/update/index.yaml

@@ -36,7 +36,7 @@ skills:
   - ../update/save-and-translate-document.mjs
   - url: ../utils/action-success.mjs
     default_input:
-      action: "✅ Documents updated successfully"
+      action: "✅ Documents updated successfully!\n💡 Looks good? Run `aigne doc publish` to go live."
 input_schema:
   type: object
   properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.14-beta.2",
+  "version": "0.8.15-beta",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

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

@@ -1,19 +1,11 @@
 <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>`
-- `<x-field-desc>`
-- `<x-field-group>`
-
-## `<x-card>` Single Card Component
+## XCard: Individual link display card
 
 Suitable for displaying individual links with a richer and more visually appealing presentation format.
 
-### Syntax Rules
-
-Attributes:
+### Attributes
 
 - `data-title` (required): Card title.
 - `data-icon` (optional): Icon identifier (e.g., lucide:icon-name or material-symbols:rocket-outline).
@@ -25,84 +17,80 @@ Attributes:
 - `data-horizontal` (optional): Whether to use horizontal layout.
 - `data-cta` (optional): Button text (call to action).
 
-Body content:
+### Children
 
 - Must be written within `<x-card>...</x-card>` children.
-- must be **plain text only**. Any markdown formatting will cause rendering errors and must be avoided.
+- **Plain Text Only**: All markdown formatting is prohibited, including inline formats like `code`, **bold**, _italic_, [links](), and block-level formats like headers (# ##), lists (- \*), code blocks (```), tables (|), and any other markdown syntax. Only plain text content is allowed.
 
-### Examples
+### Good Examples
 
-<card_good_examples>
 Example 1: Basic card with icon and description
 
-```
+```md
 <x-card data-title="alarm()" data-icon="lucide:alarm-clock"> SIGALRM: Sent when a real-time timer has expired. </x-card>
 ```
 
 Example 2: Horizontal card layout
 
-```
+```md
 <x-card data-title="Horizontal card" data-icon="lucide:atom" data-horizontal="true">
 This is an example of a horizontal card.
 </x-card>
 ```
 
-</card_good_examples>
+### Bad Examples
 
-<card_bad_examples>
-Example 1: Markdown formatting in card content
+Example 1: Inline Markdown formatting in card content
 
-```
+```md
 <x-card data-title="alarm()" data-icon="lucide:alarm-clock"> `SIGALRM`: Sent when a real-time timer has expired. </x-card>
 ```
 
 Example 2: Code block inside card content
 
-```
+```md
 <x-card data-title="ctrl_break()" data-icon="lucide:keyboard">
   Creates a listener for "ctrl-break" events.
 
-  \`\`\`rust
-  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(())
-  }
-  \`\`\`
+\`\`\`rust
+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>
 ```
 
-</card_bad_examples>
-
-## `<x-cards>` Card List Component
+## XCards: Multiple cards container
 
 Suitable for displaying multiple links using a card list format, providing a richer and more visually appealing presentation.
 
-### Syntax Rules
-
-Attributes:
+### Attributes
 
 - data-columns (optional): Number of columns, integer (e.g., 2, 3). Default is 2.
   - Must contain multiple <x-card> elements internally.
 
-Body content:
+### Children
 
 - Must contain multiple <x-card> elements internally.
-- **Consistency requirement**: All <x-card> elements within the same <x-cards> must maintain visual consistency:
+
+### Usage Rules
+
+- **Visual Consistency**: All <x-card> elements within the same <x-cards> must maintain visual consistency:
   - It's 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).
 
-### Examples
+### Good Examples
 
-<cards_good_examples>
 Example 1: Three-column cards with icons
 
-```
+```md
 <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>
@@ -112,234 +100,326 @@ Example 1: Three-column cards with icons
 
 Example 2: Two-column cards with images
 
-```
+```md
 <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-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>
 ```
 
-</cards_good_examples>
-
-## `<x-field>` Individual Field Component
+## XField: Structured data field
 
 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 Rules
-
-Attributes:
+### Attributes
 
 - `data-name` (optional): The name of the field/parameter
-- `data-type` (optional): The data type of the field (e.g., "string", "number", "boolean", "object", "array")
+- `data-type` (optional): The data type of the field (e.g., "string", "number", "boolean", "symbol", "object", "array", "function")
 - `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): Simple description of the field (plain text only)
-  - Mutually exclusive with `data-desc`: Use either `data-desc` attribute OR `<x-field-desc>` element, not both
 
-Body content:
+### Children
 
 - For simple types (string, number, boolean): children can be empty or contain exactly one `<x-field-desc>` element
 - For complex types (object, array), children contain nested `<x-field>` elements and optionally one `<x-field-desc>` element
-  - Maximum nesting depth: 5 levels (to avoid overly complex structures)
-- Only one `<x-field-desc>` element per `<x-field>` is allowed
-- **Always use opening/closing tags format**: `<x-field ...></x-field>` for all types
 
-### Examples
+### Usage Rules
+
+- **Opening/Closing Tags Format**: `<x-field ...></x-field>` for all types
+- **Maximum Nesting Depth**: 5 levels (to avoid overly complex structures)
+- **Description Mutually Exclusive**: Use either `data-desc` attribute OR `<x-field-desc>` element, not both
+- **Single Description Rule**: Only one `<x-field-desc>` element per `<x-field>` is allowed
+- **Grouping Requirement**: Wrap the outermost `<x-field>` elements with `<x-field-group>`, even if there's only one `<x-field>` element
+- **Recursive Structure**: Use recursive `<x-field>` structures to fully express complex object type hierarchies, decomposing all nested properties into more fundamental types
+- **Fixed Value Fields**: For fields that accept a limited set of predefined values (including enums, constants, or fixed strings), use `<x-field>` with the base data type (e.g., "string", "number") in the `data-type` attribute, and list all possible values in the description.
+- **Function-Type Fields**: For fields with `data-type="function"`, nest `<x-field>` elements for parameters (`data-name="parameters"`) and return value (`data-name="returnValue"`) **whenever their types are available**.
+
+### Good Examples
 
-<field_good_examples>
 Example 1: Simple field with all attributes
 
-```
-<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>
+```md
+### Returns
+
+<x-field-group>
+  <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>
+</x-field-group>
 ```
 
 Example 2: Field with markdown description
 
-```
-<x-field data-name="api_key" data-type="string" data-required="true">
-  <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code.</x-field-desc>
-</x-field>
+```md
+### Context
+
+<x-field-group>
+  <x-field data-name="api_key" data-type="string" data-required="true">
+    <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code.</x-field-desc>
+  </x-field>
+</x-field-group>
 ```
 
 Example 3: Nested object structure
 
-```
-<x-field data-name="session" data-type="object" data-required="true">
-  <x-field-desc markdown>Contains all **authentication** and **authorization** data for the current user session. This object is automatically populated after successful login.</x-field-desc>
-  <x-field data-name="user" data-type="object" data-required="true" data-desc="User basic 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">
-        <x-field-desc markdown>Primary email address used for **login** and **notifications**. Must be a valid email format.</x-field-desc>
+```md
+### Properties
+
+<x-field-group>
+  <x-field data-name="session" data-type="object" data-required="true">
+    <x-field-desc markdown>Contains all **authentication** and **authorization** data for the current user session. This object is automatically populated after successful login.</x-field-desc>
+    <x-field data-name="user" data-type="object" data-required="true" data-desc="User basic 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">
+          <x-field-desc markdown>Primary email address used for **login** and **notifications**. Must be a valid email format.</x-field-desc>
+      </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"]'>
+      <x-field-desc markdown>Array of **permission strings** that determine what actions the user can perform. Common values: `"read"`, `"write"`, `"admin"`, `"delete"`.</x-field-desc>
     </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"]'>
-    <x-field-desc markdown>Array of **permission strings** that determine what actions the user can perform. Common values: `"read"`, `"write"`, `"admin"`, `"delete"`.</x-field-desc>
   </x-field>
-</x-field>
+</x-field-group>
 ```
 
-</field_good_examples>
+Example 4: Multiple fields for Parameters
 
-<field_bad_examples>
-Example 1: Using multiple `<x-field-desc>` elements
+```md
+### Parameters
 
+<x-field-group>
+  <x-field data-name="user_id" data-type="string" data-required="true" data-desc="Unique identifier for the user. Must be a valid UUID v4 format."></x-field>
+  <x-field data-name="include_profile" data-type="boolean" data-required="false" data-default="false" data-desc="Whether to include the user's profile information in the response"></x-field>
+  <x-field data-name="options" data-type="object" data-required="false" data-desc="Additional options for the request">
+    <x-field data-name="format" data-type="string" data-required="false" data-default="json">
+      <x-field-desc>Response format: `json` or `xml`</x-field-desc>
+    </x-field>
+    <x-field data-name="locale" data-type="string" data-required="false" data-default="en" data-desc="Language locale for localized content"></x-field>
+  </x-field>
+</x-field-group>
 ```
-<x-field data-name="api_key" data-type="string" data-required="true">
-  <x-field-desc markdown>Your **API key** for authentication.</x-field-desc>
-  <x-field-desc markdown>Keep it secure and never expose it.</x-field-desc>
-</x-field>
+
+Example 5: Enum values with base type and description
+
+```md
+### Status
+
+<x-field-group>
+  <x-field data-name="status" data-type="string" data-required="true" data-default="pending" data-desc="Current status of the request. Possible values: 'pending', 'processing', 'completed', 'failed'"></x-field>
+  <x-field data-name="priority" data-type="number" data-required="false" data-default="1">
+    <x-field-desc markdown>Priority level for the task. **Valid values**: `1` (low), `2` (medium), `3` (high), `4` (urgent)</x-field-desc>
+  </x-field>
+</x-field-group>
 ```
 
-Example 2: Using self-closing tag
+Example 6: Function type field with nested parameters and return value
+
+```md
+### API Methods
 
+<x-field-group>
+  <x-field data-name="authenticate" data-type="function" data-required="true" data-desc="Authenticates a user with email and password">
+    <x-field data-name="parameters" data-type="object" data-desc="Function parameters">
+      <x-field data-name="email" data-type="string" data-required="true" data-desc="User's email address"></x-field>
+      <x-field data-name="password" data-type="string" data-required="true" data-desc="User's password"></x-field>
+      <x-field data-name="rememberMe" data-type="boolean" data-required="false" data-default="false" data-desc="Whether to keep user logged in"></x-field>
+    </x-field>
+    <x-field data-name="returnValue" data-type="object" data-desc="Function return value">
+      <x-field data-name="success" data-type="boolean" data-required="true" data-desc="Whether authentication was successful"></x-field>
+      <x-field data-name="token" data-type="string" data-required="false" data-desc="JWT token if authentication successful"></x-field>
+      <x-field data-name="user" data-type="object" data-required="false" data-desc="User information if authentication successful">
+        <x-field data-name="id" data-type="string" data-required="true" data-desc="User ID"></x-field>
+        <x-field data-name="name" data-type="string" data-required="true" data-desc="User's display name"></x-field>
+        <x-field data-name="email" data-type="string" data-required="true" data-desc="User's email address"></x-field>
+      </x-field>
+    </x-field>
+  </x-field>
+</x-field-group>
 ```
-<x-field data-name="user_id" data-type="string" data-required="true" data-desc="User identifier" />
+
+### Bad Examples
+
+Example 1: Using self-closing tag (violates "Opening/Closing Tags Format" rule)
+
+```md
+<x-field-group>
+  <x-field data-name="user_id" data-type="string" data-required="true" data-desc="User identifier" />
+</x-field-group>
 ```
 
-Example 3: Using both `data-desc` and `<x-field-desc>`
+Example 2: Using both `data-desc` and `<x-field-desc>` (violates "Description Mutually Exclusive" rule)
 
+```md
+<x-field-group>
+  <x-field data-name="api_key" data-type="string" data-required="true" data-desc="API key for authentication">
+    <x-field-desc markdown>Your **API key** for authentication. Keep it secure and never expose it.</x-field-desc>
+  </x-field>
+</x-field-group>
 ```
-<x-field data-name="api_key" data-type="string" data-required="true" data-desc="API key for authentication">
-  <x-field-desc markdown>Your **API key** for authentication. Keep it secure and never expose it.</x-field-desc>
-</x-field>
+
+Example 3: Using multiple `<x-field-desc>` elements (violates "Single Description Rule")
+
+```md
+<x-field-group>
+  <x-field data-name="config" data-type="object" data-required="true">
+    <x-field-desc markdown>Configuration object for the application.</x-field-desc>
+    <x-field-desc markdown>Contains all runtime settings and preferences.</x-field-desc>
+  </x-field>
+</x-field-group>
 ```
 
-Example 4: Nesting other child elements
+Example 4: Nesting other child elements (violates "Children" rule)
 
+```md
+<x-field-group>
+  <x-field data-name="user" data-type="object" data-required="true">
+    <div>User information</div>
+    <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
+  </x-field>
+</x-field-group>
 ```
-<x-field data-name="user" data-type="object" data-required="true">
-  <div>User information</div>
-  <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
+
+Example 5: Missing x-field-group wrapper (violates "Grouping Requirement" rule)
+
+```md
+<x-field data-name="apiConfig" data-type="object" data-required="true" data-desc="API configuration object">
+  <x-field data-name="baseUrl" data-type="string" data-required="true" data-desc="Base URL for API calls"></x-field>
+  <x-field data-name="timeout" data-type="number" data-required="false" data-default="5000" data-desc="Request timeout in milliseconds"></x-field>
 </x-field>
 ```
 
-</field_bad_examples>
+Example 6: Exceeding maximum nesting depth (violates "Maximum Nesting Depth" rule)
 
-## `<x-field-desc>` Field Description Component
+```md
+<x-field-group>
+  <x-field data-name="level1" data-type="object" data-required="true">
+    <x-field data-name="level2" data-type="object" data-required="true">
+      <x-field data-name="level3" data-type="object" data-required="true">
+        <x-field data-name="level4" data-type="object" data-required="true">
+          <x-field data-name="level5" data-type="object" data-required="true">
+            <x-field data-name="level6" data-type="string" data-required="true" data-desc="Too deep nesting"></x-field>
+          </x-field>
+        </x-field>
+      </x-field>
+    </x-field>
+  </x-field>
+</x-field-group>
+```
 
-Used to provide rich text descriptions for `<x-field>` elements, supporting inline markdown formatting for enhanced readability.
+## XFieldDesc Rich field description
 
-### Syntax Rules
+Used to provide rich text descriptions for `<x-field>` elements, supporting inline markdown formatting for enhanced readability.
 
-Attributes:
+### Attributes
 
 - `markdown` (required): **MUST** be set to "markdown" . This attribute is mandatory and cannot be omitted
   - **Validation**: `<x-field-desc>` without `markdown` attribute will be rejected
 
-Body content:
+### Children
 
 - Supports **bold text**, `inline code`, _italic text_, and other inline markdown
-- Cannot contain block-level elements (no code blocks, headers, lists)
-- **Description text as child content**: Description text must be provided as child content of `<x-field-desc>`, not as the value of the `markdown` attribute
+- Description text must be provided as child content of `<x-field-desc>`, not as the value of the `markdown` attribute
+- **Inline Markdown Only**: Allow only inline Markdown (e.g., `**bold**`, *italic*, `inline code`); block elements like code blocks, headings, lists, or tables are **not allowed**.
 
-Structure constraints:
+### Usage Rules
 
-- Must be child of `<x-field>`: `<x-field-desc>` can only appear as a child element of `<x-field>` components
+- **Parent Requirement**: Must be child of `<x-field>`: `<x-field-desc>` can only appear as a child element of `<x-field>` components
 
-### Examples
+### Good Examples
 
-<field_desc_good_examples>
 Example 1: Basic markdown description
 
-```
+```md
 <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code.</x-field-desc>
 ```
 
 Example 2: Description with inline code
 
-```
+```md
 <x-field-desc markdown>**JWT token** containing user identity and permissions. Expires in `24 hours` by default. Use the `refresh_token` to obtain a new one.</x-field-desc>
 ```
 
-</field_desc_good_examples>
+### Bad Examples
 
-<field_desc_bad_examples>
-Example 1: Missing markdown attribute
+Example 1: Missing markdown attribute (violates "markdown attribute required" rule)
 
-```
+```md
 <x-field data-name="api_key" data-type="string" data-required="true">
   <x-field-desc>Your **API key** for authentication.</x-field-desc>
 </x-field>
 ```
 
-Example 2: Incorrect markdown attribute usage
+Example 2: Incorrect markdown attribute usage (violates "markdown attribute format" rule)
 
-```
+```md
 <x-field data-name="api_key" data-type="string" data-required="true">
   <x-field-desc markdown="Your **API key** for authentication."></x-field-desc>
 </x-field>
 ```
 
-Example 3: Using self-closing tag
+Example 3: Using self-closing tag (violates "opening/closing tags format" rule)
 
-```
+```md
 <x-field data-name="user_id" data-type="string" data-required="true">
   <x-field-desc markdown />
 </x-field>
 ```
 
-Example 4: Containing block-level elements
+Example 4: Containing block-level elements (violates "Inline Content Only" rule)
 
-```
+````md
 <x-field data-name="config" data-type="object" data-required="true">
   <x-field-desc markdown>
-    Configuration object for the application.
-
-    # Important Notes
+    **Configuration settings** for the application.
+    
+    ## Important Notes
     - Set debug to true for development
     - Use production database in production
-
-    \`\`\`javascript
+    
+    ```javascript
     const config = { debug: true };
-    \`\`\`
+    ```
   </x-field-desc>
 </x-field>
-```
+````
 
-Example 5: Used outside of x-field component
+Example 5: Used outside of x-field component (violates "Parent Requirement" rule)
 
-```
+```md
 <x-field-desc markdown>This description is not inside an x-field component.</x-field-desc>
 ```
 
-Example 6: Used as child of other components
+Example 6: Used as child of other components (violates "Parent Requirement" rule)
 
-```
+```md
 <x-field-group>
   <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
   <x-field-desc markdown>This description is not inside an x-field component.</x-field-desc>
 </x-field-group>
 ```
 
-</field_desc_bad_examples>
-
-## `<x-field-group>` Field Group Component
+## XFieldGroup: Field grouping container
 
 Used to group multiple related `<x-field>` elements at the top level, indicating they belong to the same object or context. This provides better organization and visual grouping for related parameters.
 
-### Syntax Rules
-
-Attributes:
+### Attributes
 
 - No attributes required
 
-Body content:
+### Children
 
 - Only `<x-field>` elements are allowed as children
 
-Structure:
+### Usage Rules
 
-- Top-level organization: Used only at the top level for grouping related `<x-field>`
-- Cannot be nested inside other `<x-field>` or `<x-field-group>` elements
+- **Top-Level Only**: Used only at the top level for grouping related `<x-field>` elements. Cannot be nested inside other `<x-field>` or `<x-field-group>` elements
+- **Structured Data Only**: Use `<x-field-group>` for fields **other than simple types** (`string`, `number`, `boolean`, `symbol`), e.g., Properties, Context, Parameters, Return values. For simple-type fields, use plain Markdown text.
 
-### Examples
+### Good Examples
 
-<field_group_good_examples>
 Example 1: Product information fields
 
-```
+```md
 <x-field-group>
   <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>
@@ -350,12 +430,11 @@ Example 1: Product information fields
 </x-field-group>
 ```
 
-</field_group_good_examples>
+### Bad Examples
 
-<field_group_bad_examples>
-Example 1: Nested inside x-field component
+Example 1: Nested inside x-field component (violates "Top-Level Only" rule)
 
-```
+```md
 <x-field data-name="user" data-type="object" data-required="true">
   <x-field-group>
     <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
@@ -364,9 +443,9 @@ Example 1: Nested inside x-field component
 </x-field>
 ```
 
-Example 2: Nested inside another x-field-group
+Example 2: Nested inside another x-field-group (violates "Top-Level Only" rule)
 
-```
+```md
 <x-field-group>
   <x-field data-name="user" data-type="object" data-required="true" data-desc="User information"></x-field>
   <x-field-group>
@@ -376,9 +455,9 @@ Example 2: Nested inside another x-field-group
 </x-field-group>
 ```
 
-Example 3: Containing non-x-field elements
+Example 3: Containing non-x-field elements (violates "Only x-field elements allowed" rule)
 
-```
+```md
 <x-field-group>
   <x-field data-name="name" data-type="string" data-required="true" data-desc="User name"></x-field>
   <div>Additional information</div>
@@ -386,6 +465,21 @@ Example 3: Containing non-x-field elements
 </x-field-group>
 ```
 
-</field_group_bad_examples>
+Example 4: Empty x-field-group (violates "Must contain x-field elements" rule)
+
+```md
+<x-field-group>
+</x-field-group>
+```
+
+Example 5: Using x-field-group for simple-type (violates "Structured Data Only" rule)
+
+```md
+### appName
+
+<x-field-group>
+  <x-field data-name="appName" data-type="string" data-required="true" data-desc="specifies the name of the application"></x-field>
+</x-field-group>
+```
 
-</custom_components_usage>
+</custom_components_usage>

package/prompts/detail/generate/detail-example.md

@@ -80,7 +80,9 @@ Here are some high-quality documentation details for your reference:
 
   **Returns**
 
-  <x-field data-name="product" data-type="TProductExpanded" data-desc="The newly created product object, including expanded details"></x-field>
+  <x-field-group>
+    <x-field data-name="product" data-type="TProductExpanded" data-desc="The newly created product object, including expanded details"></x-field>
+  </x-field-group>
 
   **Example**
 
@@ -130,11 +132,15 @@ Here are some high-quality documentation details for your reference:
 
   **Parameters**
 
-  <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to retrieve."></x-field>
+  <x-field-group>
+    <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to retrieve."></x-field>
+  </x-field-group>
 
   **Returns**
 
-  <x-field data-name="product" data-type="TProductExpanded" data-desc="The retrieved product object, including expanded details."></x-field>
+  <x-field-group>
+    <x-field data-name="product" data-type="TProductExpanded" data-desc="The retrieved product object, including expanded details."></x-field>
+  </x-field-group>
 
   **Example**
 
@@ -176,7 +182,9 @@ Here are some high-quality documentation details for your reference:
 
   **Returns**
 
-  <x-field data-name="product" data-type="TProductExpanded" data-desc="The updated product object."></x-field>
+  <x-field-group>
+    <x-field data-name="product" data-type="TProductExpanded" data-desc="The updated product object."></x-field>
+  </x-field-group>
 
   **Example**
 
@@ -341,11 +349,15 @@ Here are some high-quality documentation details for your reference:
 
   **Parameters**
 
-  <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to archive."></x-field>
+  <x-field-group>
+    <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to archive."></x-field>
+  </x-field-group>
 
   **Returns**
 
-  <x-field data-name="product" data-type="TProduct" data-desc="The archived product object."></x-field>
+  <x-field-group>
+    <x-field data-name="product" data-type="TProduct" data-desc="The archived product object."></x-field>
+  </x-field-group>
 
   **Example**
 
@@ -380,11 +392,15 @@ Here are some high-quality documentation details for your reference:
 
   **Parameters**
 
-  <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to delete."></x-field>
+  <x-field-group>
+    <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to delete."></x-field>
+  </x-field-group>
 
   **Returns**
 
-  <x-field data-name="product" data-type="TProduct" data-desc="The deleted product object."></x-field>
+  <x-field-group>
+    <x-field data-name="product" data-type="TProduct" data-desc="The deleted product object."></x-field>
+  </x-field-group>
 
   **Example**
 

package/prompts/detail/generate/document-rules.md

@@ -7,18 +7,17 @@ Documentation Generation Rules:
 - Since API names are already specified in document titles, avoid repeating them in subheadings—use sub-API names directly
 - Include links to related documents in the introduction using Markdown format to help users navigate to relevant content
 - Add links to further reading materials in the summary section using Markdown format
+- **Markdown Syntax Constraint**: Use only GitHub Flavored Markdown (GFM) syntax by default. Prohibited extensions include: custom blocks `:::`, footnotes `[^1]: notes`, math formulas `$$ LaTeX`, highlighted text `==code==`, and other non-GFM syntax unless explicitly defined in custom component rules
 - Use proper Markdown link syntax, for example: [Next Chapter Title](next_chapter_path)
 - **Ensure next_chapter_path references either external URLs or valid paths from the documentation structure**—use absolute paths from the documentation structure
 - When DataSources includes third-party links, incorporate them appropriately throughout the document
 - Structure each section with: title, introduction, code examples, response data samples, and explanatory notes. Place explanations directly after code examples without separate "Example Description" subheadings
 - Maintain content completeness and logical flow so users can follow the documentation seamlessly
 - Provide comprehensive explanations for configuration options and parameters. When parameters accept multiple values, explain each option's purpose and include code examples where applicable
-- Use the `<x-field>` custom component only for displaying structured object data such as API parameters, return values, network request body/query/headers, and complex object properties (e.g., ContextType). This component does not exist independently but represents complete object structures
-- Do not use `<x-field>` for individual field descriptions (e.g., name or version in package.json, logo or appUrl in config.yaml) - use regular Markdown text instead
-- Wrap the outermost `<x-field>` elements with `<x-field-group>` when describing multiple properties of the same object, even if there's only one `<x-field>` element
-- Use recursive `<x-field>` structures to fully express complex object type hierarchies, decomposing all nested properties into more fundamental types. Limit nesting to 5 levels maximum
 - All interface and method documentation must include **response data examples**
-- For simple list data, use Markdown tables to present information clearly and improve readability
+- **Use `<x-field-group>` for all structured data**: Represent objects with nested `<x-field>` elements, and expand each structure to the **deepest relevant level**.
+- **Enhance field descriptions with example values**: For structured data defined using `<x-field-group>`, extract example values from type definitions, comments, or test cases to make documentation more practical and user-friendly.
+- **Use Markdown tables** for predefined values (e.g., status types, options) or term definitions to improve clarity and allow side-by-side comparison.
 - Validate output Markdown for completeness, ensuring tables are properly formatted
 - **Content Integrity**: Generate complete, syntactically correct code blocks (JSON, etc.). Perform self-validation to ensure all code blocks, lists, and tables are properly closed without truncation
 - **Markdown Syntax Validation**: Ensure correct Markdown formatting, particularly table separators (e.g., `|---|---|---|`) that match column counts

package/prompts/translate/code-block.md

@@ -1,16 +1,23 @@
 <code_block_rules>
 The following formats are considered Code Blocks:
-  - Wrapped with ```
-  - Supports configurations: language, title, icon, where title and icon are optional
-  - content can be code, command line examples, text or any other content
+
+- Wrapped with ```
+- Supports configurations: language, title, icon, where title and icon are optional
+- content can be code, command line examples, text or any other content
 
 <code_block_sample>
+
 ```{language} [{title}] [icon={icon}]
 {content}
 ```
+
 </code_block_sample>
 
-Code Block Translation: 
-- For D2 code blocks, only translate labels
-- For other language code blocks, **only translate comments starting with #, keep all other content unchanged without translation**
-</code_block_rules>
+Code Block Translation Rules:
+
+- For D2 code blocks, translate **labels only**; leave all variable names, component names, and syntax unchanged.
+- Translate **comments only** using the language-specific comment syntax; **preserve** all code, variables, functions, and syntax.
+- **Do not translate** command examples, terminal/log outputs, or runtime output.
+- **Preserve** all formatting, indentation, and code block structure.
+
+</code_block_rules>

package/prompts/translate/translate-document.md

@@ -9,6 +9,7 @@ Core Mandates:
 3. Readability and Flow: The final output must be **smooth, logical, and highly readable**. Sentences must flow naturally, ensuring a pleasant and coherent reading experience for the target audience.
 4. Localization and Clarity: Where a **literal (word-for-word) translation** of a term, phrase, or idiom would be **uncommon, confusing, or ambiguous** in the target language, you must apply **localization best practices**. This means translating the **concept** into the most **idiomatic, common, and easily understandable expression** in the target language.
 5. Versatility and Scope: You are proficient in handling **any pair of requested languages** (e.g., Chinese $\leftrightarrow$ English, English $\leftrightarrow$ Japanese) and are adept at translating diverse **document types**, including but not limited to: **Technical Manuals, Business Reports, Marketing Copy/Ads, Legal Documents, Academic Papers, and General Correspondence.**
+
 </role_and_goal>
 
 <translation_rules>
@@ -19,11 +20,12 @@ Translation Requirements:
 - Strictly Protect Markdown Syntax: All Markdown syntax characters, including but not limited to `|` and `-` in tables, `*` and `-` in lists, `#` in headings, `` ` `` in code blocks, etc., must be **copied exactly**, with no modification, addition, deletion, or merging. Table separators (e.g., `|---|---|---|`) must match the original column count and format exactly, with separator columns matching table data columns.
 - Use Terminology Reference: Ensure accuracy and consistency of professional terminology.
 - Preserve Terms: Retain specific terms in their original form, avoiding translation.
+- Maintain tone consistency: use a neutral tone for developer/DevOps docs, a polite tone for end-user/client docs, and do not mix address styles (e.g., **"you"** vs **"您"**).
+- Translate Descriptions Only in <x-field>: All `<x-field>` component attributes must maintain the original format. Only translate the description content within `data-desc` attribute or `<x-field-desc>` elements.
 
 {% include "./code-block.md" %}
 </translation_rules>
 
-
 {% if feedback %}
 <translation_user_feedback>
 {{ feedback }}
@@ -41,10 +43,11 @@ Translation Requirements:
 {{userPreferences}}
 
 User preference guidelines:
+
 - User preferences are derived from feedback provided in previous user interactions. When generating translations, consider user preferences to avoid repeating issues mentioned in user feedback
 - User preferences carry less weight than current user feedback
-</user_preferences>
-{% endif %}
+  </user_preferences>
+  {% endif %}
 
 {% include "./glossary.md" %}
 
@@ -58,7 +61,7 @@ Terms to preserve (do not translate):
 
 <example>
 <example_item>
-**Special Note**: Keep table separators `|---|---|---|` unchanged from the original
+Table Translation - Demonstrates how to translate table content while preserving markdown structure and separators.
 
 <before_translate>
 | Name | Type | Description |
@@ -77,7 +80,8 @@ Terms to preserve (do not translate):
 </example_item>
 
 <example_item>
-**Special Note**: All x-field component attributes must maintain the original format. Only translate the description content within data-desc attributes or x-field-desc elements
+XField Component Translation - Shows how to translate only description content within x-field components while preserving all attributes.
+
 <before_translate>
 
 <x-field data-name="teamDid" data-type="string" data-required="true" data-desc="The DID of the team or Blocklet managing the webhook."></x-field>
@@ -96,9 +100,10 @@ Terms to preserve (do not translate):
 </example_item>
 
 <example_item>
-**Special Note**: In code blocks, only translate comments while keeping all other code content (variables, functions, syntax) unchanged
+Code Block Translation - Illustrates translating only comments in code blocks while keeping all code content unchanged.
 
 <before_translate>
+
 ```xxx
 // Initialize the API client
 const client = new APIClient({
@@ -125,9 +130,11 @@ async function getUserData(userId) {
   }
 }
 ```
+
 </before_translate>
 
 <after_translate>
+
 ```xxx
 // 初始化 API 客户端
 const client = new APIClient({
@@ -154,13 +161,15 @@ async function getUserData(userId) {
   }
 }
 ```
+
 </after_translate>
 </example_item>
 
 <example_item>
-**Special Note**: **Command execution and log printing** should untranslated
+Command and Log Preservation - Demonstrates preserving command execution and log output without translation.
 
 <before_translate>
+
 ```text Timeout Error Message
 Blocklet Server failed to stop within 5 minutes
 You can stop blocklet server with blocklet stop --force
@@ -171,9 +180,11 @@ $ cli log
 
 Cache for server cleared: [list of cleared cache keys]
 ```
+
 </before_translate>
 
 <after_translate>
+
 ```text 超时错误消息
 Blocklet Server failed to stop within 5 minutes
 You can stop blocklet server with blocklet stop --force
@@ -184,6 +195,99 @@ $ cli log
 
 Cache for server cleared: [list of cleared cache keys]
 ```
+
+</after_translate>
+</example_item>
+
+<example_item>
+D2 Diagram Translation - Shows how to translate only labels in D2 diagrams while preserving all syntax and structure.
+
+<before_translate>
+
+```d2 High-Level Architecture
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Your-Application: {
+  label: "Your Application"
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    shape: rectangle
+
+    Payment-Components: {
+      label: "Payment Components"
+      shape: rectangle
+      grid-columns: 2
+
+      CheckoutForm: { label: "CheckoutForm" }
+      CheckoutTable: { label: "CheckoutTable" }
+      CheckoutDonate: { label: "CheckoutDonate" }
+      CustomerInvoiceList: { label: "CustomerInvoiceList" }
+    }
+  }
+}
+
+Payment-Kit-Backend: {
+  label: "Payment Kit Backend"
+  shape: cylinder
+}
+
+User -> Your-Application.PaymentProvider.Payment-Components: "Interacts with UI"
+Your-Application.PaymentProvider -> Payment-Kit-Backend: "Handles API Communication"
+Payment-Kit-Backend -> Your-Application.PaymentProvider: "Returns Data"
+Your-Application.PaymentProvider.Payment-Components -> User: "Renders UI Updates"
+
+```
+
+</before_translate>
+
+<after_translate>
+
+```d2 高层架构
+direction: down
+
+User: {
+  shape: c4-person
+}
+
+Your-Application: {
+  label: "您的应用程序"
+  shape: rectangle
+
+  PaymentProvider: {
+    label: "PaymentProvider"
+    shape: rectangle
+
+    Payment-Components: {
+      label: "支付组件"
+      shape: rectangle
+      grid-columns: 2
+
+      CheckoutForm: { label: "CheckoutForm" }
+      CheckoutTable: { label: "CheckoutTable" }
+      CheckoutDonate: { label: "CheckoutDonate" }
+      CustomerInvoiceList: { label: "CustomerInvoiceList" }
+    }
+  }
+}
+
+Payment-Kit-Backend: {
+  label: "Payment Kit 后端"
+  shape: cylinder
+}
+
+User -> Your-Application.PaymentProvider.Payment-Components: "与 UI 交互"
+Your-Application.PaymentProvider -> Payment-Kit-Backend: "处理 API 通信"
+Payment-Kit-Backend -> Your-Application.PaymentProvider: "返回数据"
+Your-Application.PaymentProvider.Payment-Components -> User: "渲染 UI 更新"
+
+```
+
 </after_translate>
 </example_item>