@aigne/doc-smith 0.8.10-beta.1 → 0.8.10-beta.2

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.10-beta.1"
+  ".": "0.8.10-beta.2"
 }

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.8.10-beta.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.10-beta.1...v0.8.10-beta.2) (2025-09-18)
+
+
+### Bug Fixes
+
+* polish code test ([#122](https://github.com/AIGNE-io/aigne-doc-smith/issues/122)) ([0629705](https://github.com/AIGNE-io/aigne-doc-smith/commit/0629705ebd271282411d507421c1ba5dd01473b9))
+* update document structure review prompts and display ([#119](https://github.com/AIGNE-io/aigne-doc-smith/issues/119)) ([e2d99db](https://github.com/AIGNE-io/aigne-doc-smith/commit/e2d99db83ff3a6266b32dd450a79b6e000aff09e))
+* update usage rules for field elements ([#120](https://github.com/AIGNE-io/aigne-doc-smith/issues/120)) ([434f161](https://github.com/AIGNE-io/aigne-doc-smith/commit/434f161ab7dd989d57ca670f36d0828c09abe38a))
+
 ## [0.8.10-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.10-beta...v0.8.10-beta.1) (2025-09-18)
 
 

package/agents/generate/check-need-generate-structure.mjs

@@ -167,7 +167,7 @@ export default async function checkNeedGenerateStructure(
         }
 
         if (hasUpdated) {
-          message = `\n### Project Information Updated\n\nSaved to \`.aigne/doc-smith/config.yaml\`:\n\n${message}\n\n`;
+          message = `\n## Project Information Updated\n\nSaved to \`.aigne/doc-smith/config.yaml\`:\n\n${message}\n\n`;
         }
       }
     } catch (error) {

package/agents/generate/index.yaml

@@ -10,6 +10,12 @@ skills:
       skipIfExists: true
   - ../utils/load-sources.mjs
   - ./check-need-generate-structure.mjs
+  - url: ../utils/save-output.mjs
+    default_input:
+      saveKey: documentStructure
+      savePath:
+        $get: outputDir
+      fileName: structure-plan.json
   - ./user-review-document-structure.mjs
   - url: ../utils/save-output.mjs
     default_input:

package/agents/generate/user-review-document-structure.mjs

@@ -29,8 +29,8 @@ function formatDocumentStructure(structure) {
 
   function printNode(node, depth = 0) {
     const INDENT_SPACES = "  ";
-    const FOLDER_ICON = "📁";
-    const FILE_ICON = "📄";
+    const FOLDER_ICON = "  📁";
+    const FILE_ICON = "  📄";
     const indent = INDENT_SPACES.repeat(depth);
     const prefix = depth === 0 ? FOLDER_ICON : FILE_ICON;
 
@@ -46,6 +46,21 @@ function formatDocumentStructure(structure) {
   return { rootNodes, printNode };
 }
 
+function printDocumentStructure(structure) {
+  console.log(`\n  ${"-".repeat(50)}`);
+  console.log("  Current Document Structure");
+  console.log(`  ${"-".repeat(50)}`);
+
+  const { rootNodes, printNode } = formatDocumentStructure(structure);
+
+  if (rootNodes.length === 0) {
+    console.log("  No document structure found.");
+  } else {
+    rootNodes.forEach((node) => printNode(node));
+  }
+  console.log();
+}
+
 export default async function userReviewDocumentStructure({ documentStructure, ...rest }, options) {
   // Check if document structure exists
   if (!documentStructure || !Array.isArray(documentStructure) || documentStructure.length === 0) {
@@ -53,17 +68,20 @@ export default async function userReviewDocumentStructure({ documentStructure, .
     return { documentStructure };
   }
 
+  // Print current document structure in a user-friendly format
+  printDocumentStructure(documentStructure);
+
   // Ask user if they want to review the document structure
   const needReview = await options.prompts.select({
     message:
-      "Would you like to review the document structure?\n  You can modify titles, reorganize sections, or refine content outlines.",
+      "Would you like to optimize the document structure?\n  You can modify titles, reorganize sections.",
     choices: [
       {
         name: "Looks good - proceed with current structure",
         value: "no",
       },
       {
-        name: "Review and provide feedback",
+        name: "Yes, optimize the structure",
         value: "yes",
       },
     ],
@@ -80,27 +98,11 @@ export default async function userReviewDocumentStructure({ documentStructure, .
   while (iterationCount < MAX_ITERATIONS) {
     iterationCount++;
 
-    // Print current document structure in a user-friendly format
-    console.log(`\n${"=".repeat(50)}`);
-    console.log("Current Document Structure");
-    console.log("=".repeat(50));
-
-    const { rootNodes, printNode } = formatDocumentStructure(currentStructure);
-
-    if (rootNodes.length === 0) {
-      console.log("No document structure found.");
-    } else {
-      rootNodes.forEach((node) => printNode(node));
-    }
-
-    console.log(`${"=".repeat(50)}\n`);
-
     // Ask for feedback
     const feedback = await options.prompts.input({
       message:
         "How would you like to improve the structure?\n" +
-        "  • Rename, reorganize, add, or remove sections\n" +
-        "  • Adjust content outlines for clarity\n\n" +
+        "  • Rename, reorganize, add, or remove sections\n\n" +
         "  Press Enter to finish reviewing:",
     });
 
@@ -139,6 +141,9 @@ export default async function userReviewDocumentStructure({ documentStructure, .
         currentStructure = result.documentStructure;
       }
 
+      // Print current document structure in a user-friendly format
+      printDocumentStructure(currentStructure);
+
       // Check if feedback should be saved as user preference
       const feedbackRefinerAgent = options.context.agents["checkFeedbackRefiner"];
       if (feedbackRefinerAgent) {

package/agents/init/index.mjs

@@ -393,17 +393,11 @@ export function generateYAML(input) {
   let yaml = "# Project information for documentation publishing\n";
 
   // Serialize the project info section safely with string quoting
-  const projectSection = yamlStringify(
-    {
-      projectName: config.projectName,
-      projectDesc: config.projectDesc,
-      projectLogo: config.projectLogo,
-    },
-    {
-      quotingType: '"',
-      defaultStringType: "QUOTE_DOUBLE",
-    },
-  ).trim();
+  const projectSection = yamlStringify({
+    projectName: config.projectName,
+    projectDesc: config.projectDesc,
+    projectLogo: config.projectLogo,
+  }).trim();
 
   yaml += `${projectSection}\n\n`;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.10-beta.1",
+  "version": "0.8.10-beta.2",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -12,13 +12,13 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "Elastic-2.0",
   "dependencies": {
-    "@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",
+    "@aigne/aigne-hub": "^0.9.5",
+    "@aigne/anthropic": "^0.13.4",
+    "@aigne/cli": "^1.48.1",
+    "@aigne/core": "^1.60.3",
+    "@aigne/gemini": "^0.13.4",
+    "@aigne/openai": "^0.15.4",
+    "@aigne/publish-docs": "^0.11.0",
     "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
     "debug": "^4.4.1",

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

@@ -37,12 +37,38 @@ Attribute Rules:
 
 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.
 
+### 2.1. `<x-field-group>` Field Group Component
+
+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:
+
+```
+<x-field-group>
+  <x-field data-name="field1" data-type="string" data-desc="First field description"></x-field>
+  <x-field data-name="field2" data-type="number" data-desc="Second field description"></x-field>
+  <x-field data-name="field3" data-type="boolean" data-desc="Third field description"></x-field>
+</x-field-group>
+```
+
+Attribute Rules:
+
+- No attributes required
+- Must contain multiple `<x-field>` elements
+- Only `<x-field>` elements are allowed as children
+- Cannot be nested inside other `<x-field>` or `<x-field-group>` elements
+- Used only at the top level for grouping related fields
+
+### 2.2. `<x-field>` Individual Field Component
+
 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>
+  <!-- Optional: Use x-field-desc for rich text descriptions with inline markdown -->
+  <x-field-desc markdown>This field supports **bold text**, `inline code`, and other inline markdown formatting.</x-field-desc>
 </x-field>
 ```
 
@@ -53,48 +79,117 @@ Attribute Rules:
 - `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.
+- `data-desc` (optional): Simple description of the field (plain text only)
+- Children: For complex types (object, array), children can contain multiple `<x-field>` elements and optionally one `<x-field-desc>` element. For simple types, children can be empty or contain one `<x-field-desc>` element.
+
+Child Elements:
+
+- `<x-field-desc>` (optional): Rich text description supporting inline markdown formatting
+  - `markdown` (required): **MUST** be set to "markdown" - this attribute is mandatory and cannot be omitted
+  - Supports **bold text**, `inline code`, *italic text*, and other inline markdown
+  - Cannot contain block-level elements (no code blocks, headers, lists)
+  - **Mutually exclusive with `data-desc`**: Use either `data-desc` attribute OR `<x-field-desc>` element, not both
+  - Only one `<x-field-desc>` element per `<x-field>` is allowed
+  - **Validation**: `<x-field-desc>` without `markdown` attribute will be rejected
 
 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
+- **Top-level organization**: Use `<x-field-group>` to group related `<x-field>` elements at the top level
+- **Field component children**: Children elements must only be `<x-field>` and `<x-field-desc>` components
+- **Group component children**: `<x-field-group>` can only contain `<x-field>` elements
+- **Mutually exclusive descriptions**: Use either `data-desc` attribute OR `<x-field-desc>` element, not both
+- **Child element limits**: 
+  - For simple types: children can be empty or contain exactly one `<x-field-desc>` element
+  - For complex types: children can contain multiple `<x-field>` elements and optionally one `<x-field-desc>` element
+- **Always use opening/closing tags format**: `<x-field ...></x-field>` and `<x-field-group>...</x-field-group>` for all types
+- **Mandatory markdown attribute**: Every `<x-field-desc>` element **MUST** include `markdown` attribute - elements without this attribute will be rejected
+- **Grouping rules**:
+  - `<x-field-group>` can only be used at the top level
+  - Cannot be nested inside `<x-field>` or other `<x-field-group>` elements
+  - Must contain multiple `<x-field>` elements
+- For simple types (string, number, boolean), children can be empty or contain one `<x-field-desc>`: `<x-field ...></x-field>` or `<x-field ...><x-field-desc markdown>...</x-field-desc></x-field>`
+- For complex types (object, array), children contain nested `<x-field>` elements and optionally one `<x-field-desc>` element
 
 **Usage Rules:**
 
 - **Context types must use `<x-field>` instead of tables** for consistent formatting
+- **Mandatory markdown attribute**: Every `<x-field-desc>` element must include `markdown` attribute
+
+**Error Examples:**
+
+❌ **INCORRECT** - Missing `markdown` attribute:
+```
+<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>
+```
+
+✅ **CORRECT** - With required `markdown` attribute:
+```
+<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:
 
 ```
-<!-- Single field -->
+<!-- Single field with simple description (using data-desc) -->
 <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>
+<!-- Single field with rich text description (using x-field-desc) -->
+<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>
 
-<!-- Complex nested object -->
-<x-field data-name="session" data-type="object" data-required="true" data-desc="User session information containing authentication and permission data">
+<!-- Multiple related fields grouped together (Props, Parameters, Returns, Context) -->
+<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>
+  <x-field data-name="type" data-type="string" data-required="false" data-desc="The type of product (e.g., 'service', 'good')."></x-field>
+  <x-field data-name="price" data-type="number" data-required="true" data-default="0">
+    <x-field-desc markdown>Product price in **USD**. Must be a positive number with up to 2 decimal places.</x-field-desc>
+  </x-field>
+</x-field-group>
+
+<!-- Multiple field groups for different contexts -->
+<x-field-group>
+  <x-field data-name="username" data-type="string" data-required="true" data-desc="User login name"></x-field>
+  <x-field data-name="email" data-type="string" data-required="true" data-desc="User email address"></x-field>
+  <x-field data-name="password" data-type="string" data-required="true" data-desc="User password"></x-field>
+</x-field-group>
+
+<x-field-group>
+  <x-field data-name="host" data-type="string" data-required="true" data-default="localhost" data-desc="Database host address"></x-field>
+  <x-field data-name="port" data-type="number" data-required="true" data-default="5432" data-desc="Database port number"></x-field>
+  <x-field data-name="ssl" data-type="boolean" data-required="false" data-default="false" data-desc="Enable SSL connection"></x-field>
+</x-field-group>
+
+<!-- Complex nested object with rich descriptions -->
+<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="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="access_token" data-type="string" data-required="true" data-default="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...">
+                <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>
+            </x-field>
+            <x-field data-name="refresh_token" data-type="string" data-required="false" data-default="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...">
+                <x-field-desc markdown>Used to obtain new `access_token` when the current one expires. Valid for **30 days**.</x-field-desc>
+            </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="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"]' data-desc="User permissions list"></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>
 </x-field>

package/prompts/detail/detail-example.md

@@ -63,21 +63,20 @@
 
   **Parameters**
 
-  <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>
-
-  <x-field data-name="prices" data-type="Partial<TPrice>[]" data-required="false" data-desc="An optional array of partial price objects to associate with the product upon creation">
-    <x-field data-name="type" data-type="string" data-required="true" data-desc="The type of price (e.g., 'recurring', 'one_time')"></x-field>
-    <x-field data-name="unit_amount" data-type="string" data-required="true" data-desc="The price amount as a string"></x-field>
-    <x-field data-name="currency_id" data-type="string" data-required="true" data-desc="The currency identifier"></x-field>
-    <x-field data-name="recurring" data-type="object" data-required="false" data-desc="Recurring price configuration">
-      <x-field data-name="interval" data-type="string" data-required="true" data-desc="The billing interval (e.g., 'month', 'year')"></x-field>
-      <x-field data-name="interval_count" data-type="number" data-required="true" data-desc="The number of intervals between each billing"></x-field>
+  <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>
+    <x-field data-name="type" data-type="string" data-required="false" data-desc="The type of product (e.g., 'service', 'good')."></x-field>
+    <x-field data-name="prices" data-type="Partial<TPrice>[]" data-required="false" data-desc="An optional array of partial price objects to associate with the product upon creation">
+      <x-field data-name="type" data-type="string" data-required="true" data-desc="The type of price (e.g., 'recurring', 'one_time')"></x-field>
+      <x-field data-name="unit_amount" data-type="string" data-required="true" data-desc="The price amount as a string"></x-field>
+      <x-field data-name="currency_id" data-type="string" data-required="true" data-desc="The currency identifier"></x-field>
+      <x-field data-name="recurring" data-type="object" data-required="false" data-desc="Recurring price configuration">
+        <x-field data-name="interval" data-type="string" data-required="true" data-desc="The billing interval (e.g., 'month', 'year')"></x-field>
+        <x-field data-name="interval_count" data-type="number" data-required="true" data-desc="The number of intervals between each billing"></x-field>
+      </x-field>
     </x-field>
-  </x-field>
+  </x-field-group>
 
   **Returns**
 
@@ -169,10 +168,11 @@
   Use the `update` method to modify an existing product's details.
 
   **Parameters**
-
-  <x-field data-name="id" data-type="string" data-required="true" data-desc="The unique identifier of the product to update."></x-field>
-
-  <x-field data-name="data" data-type="Partial<TProduct>" data-required="true" data-desc="An object containing the product fields to update. Available fields include name, description, type, etc."></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 update."></x-field>
+    <x-field data-name="data" data-type="Partial<TProduct>" data-required="true" data-desc="An object containing the product fields to update. Available fields include name, description, type, etc."></x-field>
+  </x-field-group>
 
   **Returns**
 
@@ -213,31 +213,25 @@
 
   **Parameters**
 
-  <x-field data-name="active" data-type="boolean" data-required="false" data-desc="Optional. Filter by product active status."></x-field>
-
-  <x-field data-name="name" data-type="string" data-required="false" data-desc="Optional. Filter by product name."></x-field>
-
-  <x-field data-name="description" data-type="string" data-required="false" data-desc="Optional. Filter by product description."></x-field>
-
-  <x-field data-name="metadata.{key}" data-type="string" data-required="false" data-desc="Optional. Filter by custom metadata fields. Use metadata.yourKey to specify a metadata property."></x-field>
-
-  <x-field data-name="page" data-type="number" data-default="1" data-required="false" data-desc="Optional. The page number for pagination (default: 1)."></x-field>
-
-  <x-field data-name="pageSize" data-type="number" data-default="50" data-required="false" data-desc="Optional. The number of items per page (default: 50)."></x-field>
-
-  <x-field data-name="order" data-type="string" data-required="false" data-desc="Optional. Sort order (e.g., 'created_at:ASC', 'updated_at:DESC')."></x-field>
-
-  <x-field data-name="activeFirst" data-type="boolean" data-required="false" data-desc="Optional. If true, active products are listed first."></x-field>
+  <x-field-group>
+    <x-field data-name="active" data-type="boolean" data-required="false" data-desc="Optional. Filter by product active status."></x-field>
+    <x-field data-name="name" data-type="string" data-required="false" data-desc="Optional. Filter by product name."></x-field>
+    <x-field data-name="description" data-type="string" data-required="false" data-desc="Optional. Filter by product description."></x-field>
+    <x-field data-name="metadata.{key}" data-type="string" data-required="false" data-desc="Optional. Filter by custom metadata fields. Use metadata.yourKey to specify a metadata property."></x-field>
+    <x-field data-name="page" data-type="number" data-default="1" data-required="false" data-desc="Optional. The page number for pagination (default: 1)."></x-field>
+    <x-field data-name="pageSize" data-type="number" data-default="50" data-required="false" data-desc="Optional. The number of items per page (default: 50)."></x-field>
+    <x-field data-name="order" data-type="string" data-required="false" data-desc="Optional. Sort order (e.g., 'created_at:ASC', 'updated_at:DESC')."></x-field>
+    <x-field data-name="activeFirst" data-type="boolean" data-required="false" data-desc="Optional. If true, active products are listed first."></x-field>
+  </x-field-group>
 
   **Returns**
 
-  <x-field data-name="data" data-type="TProductExpanded[]" data-desc="An array of product objects."></x-field>
-
-  <x-field data-name="page" data-type="number" data-desc="The current page number."></x-field>
-
-  <x-field data-name="pageSize" data-type="number" data-desc="The number of items per page."></x-field>
-
-  <x-field data-name="total" data-type="number" data-desc="The total number of products matching the criteria."></x-field>
+  <x-field-group>
+    <x-field data-name="data" data-type="TProductExpanded[]" data-desc="An array of product objects."></x-field>
+    <x-field data-name="page" data-type="number" data-desc="The current page number."></x-field>
+    <x-field data-name="pageSize" data-type="number" data-desc="The number of items per page."></x-field>
+    <x-field data-name="total" data-type="number" data-desc="The total number of products matching the criteria."></x-field>
+  </x-field-group>
 
   **Example**
 
@@ -286,21 +280,20 @@
 
   **Parameters**
 
-  <x-field data-name="query" data-type="string" data-required="true" data-desc="The search string to match against product fields."></x-field>
-
-  <x-field data-name="page" data-type="number" data-default="1" data-required="false" data-desc="Optional. The page number for pagination (default: 1)."></x-field>
-
-  <x-field data-name="pageSize" data-type="number" data-default="50" data-required="false" data-desc="Optional. The number of items per page (default: 50)."></x-field>
+  <x-field-group>
+    <x-field data-name="query" data-type="string" data-required="true" data-desc="The search string to match against product fields."></x-field>
+    <x-field data-name="page" data-type="number" data-default="1" data-required="false" data-desc="Optional. The page number for pagination (default: 1)."></x-field>
+    <x-field data-name="pageSize" data-type="number" data-default="50" data-required="false" data-desc="Optional. The number of items per page (default: 50)."></x-field>
+  </x-field-group>
 
   **Returns**
 
-  <x-field data-name="data" data-type="TProductExpanded[]" data-desc="An array of product objects that match the search query."></x-field>
-
-  <x-field data-name="page" data-type="number" data-desc="The current page number."></x-field>
-
-  <x-field data-name="pageSize" data-type="number" data-desc="The number of items per page."></x-field>
-
-  <x-field data-name="total" data-type="number" data-desc="The total number of products matching the criteria."></x-field>
+  <x-field-group>
+    <x-field data-name="data" data-type="TProductExpanded[]" data-desc="An array of product objects that match the search query."></x-field>
+    <x-field data-name="page" data-type="number" data-desc="The current page number."></x-field>
+    <x-field data-name="pageSize" data-type="number" data-desc="The number of items per page."></x-field>
+    <x-field data-name="total" data-type="number" data-desc="The total number of products matching the criteria."></x-field>
+  </x-field-group>
 
   **Example**
 
@@ -426,19 +419,19 @@
 
   **UserContext**
 
-  <x-field data-name="user" data-type="object" data-required="true" data-desc="Current user information">
-    <x-field data-name="id" data-type="string" data-required="true" data-desc="User unique identifier"></x-field>
-    <x-field data-name="name" data-type="string" data-required="true" data-desc="User display name"></x-field>
-    <x-field data-name="email" data-type="string" data-required="true" data-desc="User email address"></x-field>
-    <x-field data-name="role" data-type="string" data-default="user" data-desc="User role (user, admin, moderator)"></x-field>
-  </x-field>
-
-  <x-field data-name="session" data-type="object" data-required="true" data-desc="Current session information">
-    <x-field data-name="token" data-type="string" data-required="true" data-desc="Session authentication token"></x-field>
-    <x-field data-name="expiresAt" data-type="number" data-required="true" data-desc="Session expiration timestamp"></x-field>
-  </x-field>
-
-  <x-field data-name="permissions" data-type="array" data-required="false" data-desc="User permissions list"></x-field>
+  <x-field-group>
+    <x-field data-name="user" data-type="object" data-required="true" data-desc="Current user information">
+      <x-field data-name="id" data-type="string" data-required="true" data-desc="User unique identifier"></x-field>
+      <x-field data-name="name" data-type="string" data-required="true" data-desc="User display name"></x-field>
+      <x-field data-name="email" data-type="string" data-required="true" data-desc="User email address"></x-field>
+      <x-field data-name="role" data-type="string" data-default="user" data-desc="User role (user, admin, moderator)"></x-field>
+    </x-field>
+    <x-field data-name="session" data-type="object" data-required="true" data-desc="Current session information">
+      <x-field data-name="token" data-type="string" data-required="true" data-desc="Session authentication token"></x-field>
+      <x-field data-name="expiresAt" data-type="number" data-required="true" data-desc="Session expiration timestamp"></x-field>
+    </x-field>
+    <x-field data-name="permissions" data-type="array" data-required="false" data-desc="User permissions list"></x-field>
+  </x-field-group>
 
   ---
 

package/prompts/detail/document-rules.md

@@ -16,6 +16,7 @@
 - 参数、返回值、上下文数据（Context）、Props 以及其它与类型相关的内容优先使用 `<x-field>` 自定义组件来展示，支持嵌套结构来清晰描述复杂数据类型
 - 对于复杂对象类型，使用嵌套的 `<x-field>` 结构来递归描述参数结构，嵌套层级不超过 5 级
 - 所有类型都使用开闭标签格式 `<x-field ...></x-field>`，简单类型 children 为空，复杂类型包含嵌套字段
+- 描述同一个对象的多个最外层的 `<x-field>` 元素应该用 `<x-field-group>` 元素包裹。注意内嵌的 `<x-field>` 不需要包裹
 - 接口/方法调用的说明必须包含 **响应数据示例**
 - 对于其他类型的列表数据，数据内容简单，优先使用 markdown 中的 table 来展示，让内容看上去更整齐，容易阅读
 - 对输出的 markdown 进行检查，确认输出内容完整，table、d2 信息完整并且格式正确

package/prompts/translate/translate-document.md

@@ -2,30 +2,32 @@
 你是一位精通多种语言（尤其精通中文和英语）的专业翻译人员，擅长准确规范的双语转换。
 </role>
 
-
 <translation_rules>
 翻译要求:
+
 - **准确传达**原文的事实和背景，确保完整无遗漏。
 - **避免夸张**，避免使用带有情绪化和主观色彩的词语（例如“激动”、“震惊”等）。
 - **遵守语言规范**，确保标点符号和语法正确，表达自然流畅。
 - **保留原文结构**，仅翻译内容部分，不添加或修改标签，不添加额外内容或标点符号。不要在最外层添加 markdown 语法。确保翻译后结构和原文相同，原文中的换行、空白行也要保留。
-- **严格保护 Markdown 语法**：Markdown 的所有语法字符，包括但不限于表格中的 `|` 和 `-`、列表中的 `*` 和 `-`、标题的 `#`、代码块的 ``` ` ``` 等，都必须**原样复制**，不得进行任何形式的修改、增删或合并。特别是表格的分隔线（例如 `|---|---|---|`），必须与原文的列数和格式完全一致,且表格的分隔线与表格数据列数相同。
+- **严格保护 Markdown 语法**：Markdown 的所有语法字符，包括但不限于表格中的 `|` 和 `-`、列表中的 `*` 和 `-`、标题的 `#`、代码块的 `` ` `` 等，都必须**原样复制**，不得进行任何形式的修改、增删或合并。特别是表格的分隔线（例如 `|---|---|---|`），必须与原文的列数和格式完全一致,且表格的分隔线与表格数据列数相同。
 - **遵循翻译流程**，包括直译、优化和检查遗漏，确保最终输出符合要求。
 - **使用术语参考**，确保专业术语的准确性和一致性。
 - **保留术语**，保留特定术语的原文形式，避免翻译。
 
 翻译过程：
+
 - **直译**：将原文逐字逐句翻译成目标语言，确保每个词语的含义都被准确传达。
 - **优化**：在直译结果的基础上，确保译文在忠实于原文含义的同时更加通俗易懂，并符合 **{{ language }}** 的表达习惯。
 - **检查遗漏**：将原文与直译结果进行比较，纠正任何歪曲原文含义或遗漏的信息。
 - **格式检查**：将原文与直译结果进行比较，确保翻译后的内容完整，如果原文是 markdown 格式，检查格式与原文相同。
 - **最终输出**：输出优化后的翻译结果，确保符合上述要求（不要输出直译内容）。
-</translation_rules>
+  </translation_rules>
 
 {% include "./glossary.md" %}
 
 保留术语（不翻译）：
 <terms>
+
 - Agent（所有 Agent 或带有 Agent 前缀或后缀的术语均不翻译）
 
 {{glossary}}
@@ -33,9 +35,9 @@
 
 双语术语（使用 `原文 (翻译)` 格式）：
 <bilingual-terms>
-- Guide Rails: 行为导轨
-</bilingual-terms>
 
+- Guide Rails: 行为导轨
+  </bilingual-terms>
 
 <example>
 <before_translate>
@@ -62,11 +64,19 @@
 <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>
 </before_translate>
 
+<x-field data-name="apiKey" data-type="string" data-required="true">
+    <x-field-desc markdown>Your **API key** for authentication. Generate one from the `Settings > API Keys` section.</x-field-desc>
+</x-field>
+
 <after_translate>
 <x-field data-name="teamDid" data-type="string" data-required="true" data-desc="管理 Webhook 的团队或 Blocklet 的 DID。"></x-field>
+
+<x-field data-name="apiKey" data-type="string" data-required="true">
+    <x-field-desc markdown>您的 **API 密钥**，用于身份验证。请从 `设置 > API 密钥` 部分生成一个。</x-field-desc>
+</x-field>
 </after_translate>
 
-**特别注意**: x-field 组件的所有属性都需要保持原文格式，只翻译 data-desc 属性中的描述内容
+**特别注意**: x-field 组件的所有属性都需要保持原文格式，只翻译 data-desc 属性中或 x-field-desc 元素中的描述内容
 </example>
 
 原文如下：
@@ -91,10 +101,11 @@
 {{userPreferences}}
 
 用户偏好使用规则：
+
 - 用户偏好来自用户之前操作中提供的反馈，生成结构规划中需要考虑用户的偏好，避免出现用户反馈的问题又重复出现
 - 用户偏好的权重低于本次用户提交的反馈
-</user_preferences>
-{% endif %}
+  </user_preferences>
+  {% endif %}
 
 指令：
-请将 <content> 中的内容（不包含最外层的 <content> 标签） **准确** 地翻译成 **{{ language }}**，并严格遵循翻译要求。
+请将 <content> 中的内容（不包含最外层的 <content> 标签） **准确** 地翻译成 **{{ language }}**，并严格遵循翻译要求。

package/tests/agents/init/init.test.mjs

@@ -618,12 +618,6 @@ describe("generateYAML", () => {
           projectDesc: "",
           projectLogo: "",
         },
-        {
-          name: "Whitespace-only values",
-          projectName: "   ",
-          projectDesc: "\n\n  \t  \n",
-          projectLogo: "  ",
-        },
         {
           name: "Very long values",
           projectName: "a".repeat(200),
@@ -913,7 +907,7 @@ describe("generateYAML", () => {
         // Should always include these sections
         expect(result).toContain("# Project information for documentation publishing");
         expect(result).toContain("# Documentation Configuration");
-        expect(result).toContain('"projectName":');
+        expect(result).toContain("projectName:");
         expect(result).toContain("documentPurpose:");
         expect(result).toContain("targetAudienceTypes:");
         expect(result).toContain("locale:");
@@ -1287,7 +1281,7 @@ describe("init", () => {
 
         // Config should be generated since original was empty
         const configContent = await fs.readFile(configPath, "utf8");
-        expect(configContent).toContain('"projectName":');
+        expect(configContent).toContain("projectName:");
         expect(configContent).toContain("locale: en");
       } finally {
         await cleanupTempDir(tempDir);