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

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

@@ -1,17 +1,18 @@
 # Update and Refine
 
-Keeping documentation synchronized with an evolving codebase is essential. AIGNE DocSmith provides direct and flexible methods to keep your content current, whether through automatic updates triggered by code changes or precise, feedback-driven refinements.
+Keeping documentation synchronized with an evolving codebase is a critical task. AIGNE DocSmith provides direct and flexible methods to keep your content current, whether through automatic updates based on code changes or precise, feedback-driven refinements.
 
 This guide covers how to:
-- Automatically update documents when your code changes.
-- Manually regenerate specific documents with targeted feedback.
-- Optimize the overall documentation structure.
+
+- Automatically update documents when your source code changes.
+- Regenerate specific documents using targeted feedback.
+- Adjust the overall documentation structure.
 
 ### Document Update Workflows
 
 The following diagram illustrates the different paths you can take to update your documentation:
 
-```d2
+```d2 Update Workflows
 direction: down
 
 Start: {
@@ -66,9 +67,9 @@ Replan -> End
 
 ## Automatic Updates with Change Detection
 
-When you run the `aigne doc generate` command, DocSmith analyzes your codebase, detects any changes since the last run, and regenerates only the documents that are affected. This process saves time and reduces unnecessary LLM API calls.
+When you run the `aigne doc generate` command, DocSmith analyzes your codebase, detects any changes since the last run, and regenerates only the documents that are affected. This process saves time and reduces unnecessary API calls.
 
-```bash
+```shell icon=lucide:terminal
 # DocSmith will detect changes and update only what's necessary
 aigne doc generate
 ```
@@ -79,7 +80,7 @@ aigne doc generate
 
 If you need to regenerate all documentation from scratch, ignoring any cached or previous state, use the `--forceRegenerate` flag. This is useful after significant configuration changes or when you want to ensure a completely fresh build.
 
-```bash
+```shell icon=lucide:terminal
 # Regenerate all documentation from the ground up
 aigne doc generate --forceRegenerate
 ```
@@ -88,15 +89,15 @@ aigne doc generate --forceRegenerate
 
 ## Refining Individual Documents
 
-To improve a specific document without any corresponding code changes, the `aigne doc update` command allows you to provide targeted feedback to the AI for content refinement.
+To improve a specific document without any corresponding code changes, the `aigne doc update` command allows you to provide targeted instructions for content refinement.
 
 You can use this command in two ways: interactively or directly via command-line arguments.
 
 ### Interactive Mode
 
-For a guided experience, run the command without any arguments. DocSmith will present an interactive menu to select which document you want to update. After you choose, you'll be prompted to enter your feedback.
+For a guided experience, run the command without any arguments. DocSmith will present a menu to select which document you want to update. After you choose, you'll be prompted to enter your feedback.
 
-```bash
+```shell icon=lucide:terminal
 # Start the interactive update process
 aigne doc update
 ```
@@ -107,9 +108,9 @@ aigne doc update
 
 For faster workflows or scripting, you can specify the document and feedback directly using flags. This allows for precise, non-interactive updates.
 
-```bash
+```shell icon=lucide:terminal
 # Update a specific document with feedback
-aigne doc update --docs overview.md --feedback "Add a more comprehensive FAQ section at the end."
+aigne doc update --docs overview.md --feedback "Add a more detailed FAQ section at the end."
 ```
 
 Key parameters for the `update` command:
@@ -117,19 +118,19 @@ Key parameters for the `update` command:
 | Parameter  | Description                                                                                      |
 | ---------- | ------------------------------------------------------------------------------------------------ |
 | `--docs`     | The path to the document you want to update. You can use this flag multiple times for batch updates. |
-| `--feedback` | The specific instructions for the AI to use when regenerating the content.                       |
+| `--feedback` | The specific instructions to use when regenerating the content.                       |
 
 ---
 
 ## 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 improve the documentation structure 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 the `generate` command.
 
-This command instructs DocSmith to reconsider the entire document plan based on your new input.
+This command instructs DocSmith to re-evaluate the entire document plan based on your new input.
 
-```bash
+```shell icon=lucide:terminal
 # Regenerate the documentation structure with specific feedback
-aigne doc generate --feedback "Remove the 'About' section and add a more detailed 'API Reference'."
+aigne doc generate --feedback "Remove the 'About' section and add a detailed 'API Reference'."
 ```
 
 This approach is best for high-level changes to the document's table of contents, rather than line-by-line content edits.

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

@@ -1,17 +1,18 @@
-# 更新和优化
+# 更新与优化
 
-保持文档与不断演进的代码库同步至关重要。AIGNE DocSmith 提供了直接且灵活的方法来保持内容最新，无论是通过代码变更触发的自动更新，还是通过精确的、由反馈驱动的优化。
+保持文档与不断演进的代码库同步是一项至关重要的任务。AIGNE DocSmith 提供了直接而灵活的方法来确保内容保持最新，无论是通过基于代码变更的自动更新，还是通过由反馈驱动的精确优化。
 
-本指南涵盖了如何：
-- 当代码变更时自动更新文档。
-- 使用有针对性的反馈手动重新生成特定文档。
-- 优化整体文档结构。
+本指南将介绍如何：
+
+- 在源代码变更时自动更新文档。
+- 使用有针对性的反馈重新生成特定文档。
+- 调整整体文档结构。
 
 ### 文档更新工作流
 
-下图说明了更新文档可以采取的不同路径：
+下图说明了更新文档可采用的不同路径：
 
-```d2
+```d2 Update Workflows
 direction: down
 
 Start: {
@@ -25,12 +26,12 @@ Code-Change: {
 }
 
 Content-Tweak: {
-  label: "需要改进\n内容？"
+  label: "需要内容\n改进？"
   shape: rectangle
 }
 
 Structure-Tweak: {
-  label: "需要改进\n结构？"
+  label: "需要结构\n改进？"
   shape: rectangle
 }
 
@@ -66,20 +67,20 @@ Replan -> End
 
 ## 通过变更检测自动更新
 
-当您运行 `aigne doc generate` 命令时，DocSmith 会分析您的代码库，检测自上次运行以来的任何变更，并仅重新生成受影响的文档。此过程可以节省时间并减少不必要的 LLM API 调用。
+当您运行 `aigne doc generate` 命令时，DocSmith 会分析您的代码库，检测自上次运行以来的所有变更，并仅重新生成受影响的文档。这一过程可以节省时间并减少不必要的 API 调用。
 
-```bash
-# DocSmith 将检测变更并仅更新必要的部分
+```shell icon=lucide:terminal
+# DocSmith 将检测变更并仅更新必要部分
 aigne doc generate
 ```
 
-![DocSmith 会检测变更并仅重新生成所需的文档。](https://docsmith.aigne.io/image-bin/uploads/21a76b2f65d14d16a49c13d800f1e2c1.png)
+![DocSmith 检测变更并仅重新生成所需文档。](https://docsmith.aigne.io/image-bin/uploads/21a76b2f65d14d16a49c13d800f1e2c1.png)
 
 ### 强制完全重新生成
 
-如果您需要从头开始重新生成所有文档，忽略任何缓存或先前的状态，请使用 `--forceRegenerate` 标志。这在进行重大配置更改或希望确保完全重新构建时非常有用。
+如果您需要从头开始重新生成所有文档，忽略任何缓存或先前的状态，请使用 `--forceRegenerate` 标志。这在进行重大配置更改后，或当您希望确保构建一个全新的版本时非常有用。
 
-```bash
+```shell icon=lucide:terminal
 # 从头开始重新生成所有文档
 aigne doc generate --forceRegenerate
 ```
@@ -88,15 +89,15 @@ aigne doc generate --forceRegenerate
 
 ## 优化单个文档
 
-要在没有任何相应代码变更的情况下改进特定文档，`aigne doc update` 命令允许您向 AI 提供有针对性的反馈以进行内容优化。
+如果想在没有相应代码变更的情况下改进特定文档，可以使用 `aigne doc update` 命令提供有针对性的内容优化指令。
 
-您可以通过两种方式使用此命令：交互式或直接通过命令行参数。
+您可以通过两种方式使用此命令：交互式模式或直接通过命令行参数。
 
 ### 交互模式
 
-要获得引导式体验，请在不带任何参数的情况下运行该命令。DocSmith 将呈现一个交互式菜单，供您选择要更新的文档。选择后，系统将提示您输入反馈。
+如需引导式体验，请直接运行该命令，不带任何参数。DocSmith 将会展示一个菜单，供您选择要更新的文档。选择后，系统将提示您输入反馈。
 
-```bash
+```shell icon=lucide:terminal
 # 启动交互式更新流程
 aigne doc update
 ```
@@ -105,33 +106,33 @@ aigne doc update
 
 ### 直接通过命令行更新
 
-对于更快捷的工作流或脚本编写，您可以使用标志直接指定文档和反馈。这允许进行精确的非交互式更新。
+为了实现更快的工作流或用于脚本编写，您可以使用标志直接指定文档和反馈。这支持精确的非交互式更新。
 
-```bash
+```shell icon=lucide:terminal
 # 使用反馈更新特定文档
-aigne doc update --docs overview.md --feedback "在末尾添加一个更全面的常见问题解答部分。"
+aigne doc update --docs overview.md --feedback "在末尾添加一个更详细的 FAQ 部分。"
 ```
 
 `update` 命令的关键参数：
 
 | Parameter  | Description                                                                                      |
 | ---------- | ------------------------------------------------------------------------------------------------ |
-| `--docs`     | 要更新的文档路径。您可以多次使用此标志进行批量更新。 |
-| `--feedback` | 供 AI 在重新生成内容时使用的具体说明。                       |
+| `--docs`     | 您希望更新的文档路径。您可以多次使用此标志进行批量更新。 |
+| `--feedback` | 重新生成内容时要使用的具体指令。                       |
 
 ---
 
 ## 优化整体结构
 
-除了优化单个文档的内容外，您还可以调整整体文档结构。如果缺少某个部分或现有组织结构可以改进，您可以使用带 `--feedback` 标志的 `generate` 命令向结构规划 agent 提供反馈。
+除了优化单个文档的内容，您还可以调整整体文档结构。如果缺少某个部分或现有组织结构有待改进，您可以向 `generate` 命令提供反馈。
 
-此命令指示 DocSmith 根据您的新输入重新考虑整个文档计划。
+该命令会指示 DocSmith 根据您的新输入重新评估整个文档计划。
 
-```bash
-# 使用特定反馈重新生成结构计划
-aigne doc generate --feedback "移除‘关于’部分，并添加一个更详细的‘API 参考’。"
+```shell icon=lucide:terminal
+# 使用特定反馈重新生成文档结构
+aigne doc generate --feedback "删除‘关于’部分，并添加一个详细的‘API 参考’。"
 ```
 
-此方法最适用于文档目录的高层级更改，而非逐行内容编辑。
+这种方法最适合对文档的目录进行高层级的更改，而不是逐行编辑内容。
 
-借助这些工具，您可以维护与项目一同演进的准确文档。内容优化后，您可以将其提供给全球受众。在 [翻译文档](./features-translate-documentation.md) 指南中了解如何操作。
+借助这些工具，您可以维护与项目共同演进的准确文档。内容优化后，您可以将其提供给全球用户。具体方法请参阅[翻译文档](./features-translate-documentation.md)指南。

package/docs-mcp/get-docs-structure.mjs

@@ -13,4 +13,4 @@ export default async function getDocsStructure() {
   return { structure };
 }
 
-getDocsStructure.description = "Get docs structure";
+getDocsStructure.description = "Get documentation structure";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.10-beta",
-  "description": "",
+  "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>