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

package/aigne.yaml

@@ -40,6 +40,7 @@ agents:
   - ./agents/utils/feedback-refiner.yaml
   - ./agents/prefs/index.mjs
   - ./agents/chat/index.yaml
+  - ./agents/generate/user-review-document-structure.mjs
 cli:
   chat: ./agents/chat/index.yaml
   agents:

package/docs/advanced-how-it-works.md

@@ -1,12 +1,14 @@
 # How It Works
 
-AIGNE DocSmith automates documentation using a multi-agent system. Instead of a single AI model, DocSmith orchestrates a pipeline of specialized AI agents, where each agent is an expert in a specific task. This collaborative approach generates structured and detailed documentation directly from your source code.
+AIGNE DocSmith operates on a multi-agent system built within the AIGNE Framework. Instead of a single monolithic process, it orchestrates a pipeline of specialized AI agents, where each agent is responsible for a specific task. This approach allows for a structured and modular process that transforms source code into complete documentation.
 
-At its core, DocSmith operates as a pipeline, processing your source code through several distinct stages, each managed by one or more dedicated AI agents.
+The tool is an integral part of the larger AIGNE ecosystem, which provides a platform for developing and deploying AI applications.
+
+![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
 
 ## The Documentation Generation Pipeline
 
-The entire process, from analyzing your code to publishing the final documents, follows a structured pipeline. This ensures consistency and allows for targeted refinements at any stage.
+The core of DocSmith is a pipeline that processes your source code through several distinct stages. Each stage is managed by one or more dedicated agents. The primary workflow, typically initiated by the `aigne doc generate` command, can be visualized as follows:
 
 ```d2
 direction: down
@@ -17,23 +19,23 @@ Input: {
 }
 
 Pipeline: {
-  label: "Documentation Generation Pipeline"
+  label: "Core Generation Pipeline"
   shape: rectangle
   grid-columns: 1
   grid-gap: 40
 
   Structure-Planning: {
-    label: "1. Structure Planning\n(reflective-structure-planner)"
+    label: "1. Structure Planning"
     shape: rectangle
   }
 
   Content-Generation: {
-    label: "2. Content Generation\n(content-detail-generator)"
+    label: "2. Content Generation"
     shape: rectangle
   }
 
   Saving: {
-    label: "3. Save Documents\n(save-docs)"
+    label: "3. Save Documents"
     shape: rectangle
   }
 }
@@ -44,7 +46,7 @@ User-Feedback: {
 }
 
 Optional-Steps: {
-  label: "Optional Steps"
+  label: "Optional Post-Generation Steps"
   shape: rectangle
   grid-columns: 2
   grid-gap: 40
@@ -69,31 +71,31 @@ User-Feedback -> Pipeline.Structure-Planning: "Refine Structure"
 User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
 ```
 
-1.  **Input Analysis**: The process begins with agents like `load-sources` and `load-config`, which gather your source code, configuration files (`aigne.yaml`), and any user-defined rules.
+1.  **Input Analysis**: The process begins when agents load your source code and project configuration (`aigne.yaml`).
 
-2.  **Structure Planning**: The `reflective-structure-planner` agent analyzes the codebase to propose a logical document structure. It considers your specified target audience, rules, and feedback to create an optimal outline.
+2.  **Structure Planning**: An agent analyzes the codebase to propose a logical document structure. It creates an outline based on the project's composition and any specified rules.
 
-3.  **Content Generation**: Once the structure is defined, the `content-detail-generator` and `batch-docs-detail-generator` agents take over. They populate each section of the document plan with detailed content, ensuring technical accuracy and adherence to the defined style.
+3.  **Content Generation**: With the structure in place, content generation agents populate each section of the document plan with detailed text, code examples, and explanations.
 
-4.  **Refinement and Updates**: If you provide feedback using `aigne doc update` or `aigne doc generate --feedback`, the `detail-regenerator` and `feedback-refiner` agents are activated. They update specific documents or adjust the overall structure based on your input.
+4.  **Refinement and Updates**: When you provide input via `aigne doc update` or `aigne doc generate --feedback`, specific agents are activated to update individual documents or adjust the overall structure.
 
-5.  **Translation and Publishing**: Finally, optional agents like `translate` and `publish-docs` handle multi-language translation and publishing to Discuss Kit platforms, completing the end-to-end workflow.
+5.  **Translation and Publishing**: After the primary content is generated, optional agents handle tasks like multi-language translation and publishing the final documentation to a web platform.
 
 ## Key AI Agents
 
-DocSmith's functionality comes from its team of specialized agents. While many agents work behind the scenes, here are some of the key players in the documentation pipeline:
+DocSmith's functionality is provided by a collection of agents defined in the project's configuration. Each agent has a specific role. The table below lists some of the key agents and their functions.
 
-| Agent Role | Primary Function | Governing File(s) |
-|---|---|---|
-| **Structure Planner** | Analyzes source code and rules to generate the overall documentation outline. | `structure-planning.yaml`, `reflective-structure-planner.yaml` |
-| **Content Generator** | Writes detailed content for each individual document section based on the plan. | `content-detail-generator.yaml`, `batch-docs-detail-generator.yaml` |
-| **Translation Agent** | Translates generated documentation into multiple target languages. | `translate.yaml`, `batch-translate.yaml` |
-| **Refinement Agent** | Regenerates or modifies content and structure based on user feedback. | `detail-regenerator.yaml`, `feedback-refiner.yaml` |
-| **Publishing Agent** | Manages the process of publishing documents to Discuss Kit instances. | `publish-docs.mjs`, `team-publish-docs.yaml` |
-| **Configuration Loader** | Reads and interprets the project's configuration and source files. | `load-config.mjs`, `load-sources.mjs` |
+| Functional Role          | Key Agent Files                                      | Description                                                                          |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **Structure Planning**   | `generate/generate-structure.yaml`                   | Analyzes source code to propose the initial document outline.                        |
+| **Structure Refinement** | `generate/refine-document-structure.yaml`            | Modifies the document structure based on user feedback.                              |
+| **Content Generation**   | `update/batch-generate-document.yaml`, `generate-document.yaml` | Populates the document structure with detailed content for each section.             |
+| **Translation**          | `translate/translate-document.yaml`, `translate-multilingual.yaml` | Translates generated documentation into multiple target languages.                   |
+| **Publishing**           | `publish/publish-docs.mjs`                           | Manages the process of publishing documents to Discuss Kit instances.                |
+| **Data I/O**             | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | Responsible for reading source files and writing the final markdown documents to disk. |
 
-This modular, agent-based architecture makes DocSmith flexible and robust, allowing each step of the process to be optimized independently.
+This agent-based architecture allows each step of the documentation process to be handled by a specialized tool, ensuring a structured and maintainable workflow.
 
 ---
 
-Now that you understand the mechanics behind DocSmith, learn about the measures in place to guarantee output quality in the [Quality Assurance](./advanced-quality-assurance.md) section.
+To understand the measures DocSmith takes to ensure the accuracy and format of the output, proceed to the [Quality Assurance](./advanced-quality-assurance.md) section.

package/docs/advanced-how-it-works.zh.md

@@ -1,61 +1,63 @@
 # 工作原理
 
-AIGNE DocSmith 使用一个多 Agent 系统来自动化文档生成。DocSmith 不使用单个 AI 模型，而是协调一个由专业化 AI Agent 组成的流水线，其中每个 Agent 都是特定任务的专家。这种协作方法可以直接从您的源代码生成结构化且详细的文档。
+AIGNE DocSmith 在 AIGNE 框架内构建的多 Agent 系统上运行。它并非一个单一的整体进程，而是协调一个由专业化 AI Agent 组成的流水线，其中每个 Agent 负责一项特定任务。这种方法实现了一个结构化和模块化的流程，可将源代码转换为完整的文档。
 
-其核心是，DocSmith 作为一个流水线运行，通过几个不同的阶段处理您的源代码，每个阶段都由一个或多个专用的 AI Agent 管理。
+该工具是更庞大的 AIGNE 生态系统的一个组成部分，该生态系统为开发和部署 AI 应用程序提供了一个平台。
+
+![AIGNE 生态系统架构](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
 
 ## 文档生成流水线
 
-从分析代码到发布最终文档的整个过程，都遵循一个结构化的流水线。这确保了一致性，并允许在任何阶段进行有针对性的优化。
+DocSmith 的核心是一个通过几个不同阶段处理源代码的流水线。每个阶段都由一个或多个专用 Agent 管理。主要工作流程通常由 `aigne doc generate` 命令启动，其可视化如下：
 
 ```d2
 direction: down
 
 Input: {
-  label: "Source Code & Config"
+  label: "源代码和配置"
   shape: rectangle
 }
 
 Pipeline: {
-  label: "Documentation Generation Pipeline"
+  label: "核心生成流水线"
   shape: rectangle
   grid-columns: 1
   grid-gap: 40
 
   Structure-Planning: {
-    label: "1. Structure Planning\n(reflective-structure-planner)"
+    label: "1. 结构规划"
     shape: rectangle
   }
 
   Content-Generation: {
-    label: "2. Content Generation\n(content-detail-generator)"
+    label: "2. 内容生成"
     shape: rectangle
   }
 
   Saving: {
-    label: "3. Save Documents\n(save-docs)"
+    label: "3. 保存文档"
     shape: rectangle
   }
 }
 
 User-Feedback: {
-  label: "User Feedback Loop\n(via --feedback flag)"
+  label: "用户反馈循环\n(通过 --feedback 标志)"
   shape: rectangle
 }
 
 Optional-Steps: {
-  label: "Optional Steps"
+  label: "可选的生成后步骤"
   shape: rectangle
   grid-columns: 2
   grid-gap: 40
   
   Translation: {
-    label: "Translate\n(aigne doc translate)"
+    label: "翻译\n(aigne doc translate)"
     shape: rectangle
   }
 
   Publishing: {
-    label: "Publish\n(aigne doc publish)"
+    label: "发布\n(aigne doc publish)"
     shape: rectangle
   }
 }
@@ -65,35 +67,35 @@ Pipeline.Structure-Planning -> Pipeline.Content-Generation
 Pipeline.Content-Generation -> Pipeline.Saving
 Pipeline.Saving -> Optional-Steps
 
-User-Feedback -> Pipeline.Structure-Planning: "Refine Structure"
-User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
+User-Feedback -> Pipeline.Structure-Planning: "优化结构"
+User-Feedback -> Pipeline.Content-Generation: "重新生成内容"
 ```
 
-1.  **输入分析**：该过程始于 `load-sources` 和 `load-config` 等 Agent，它们会收集您的源代码、配置文件（`aigne.yaml`）以及任何用户定义的规则。
+1.  **输入分析**：当 Agent 加载你的源代码和项目配置（`aigne.yaml`）时，该过程开始。
 
-2.  **结构规划**：`reflective-structure-planner` Agent 会分析代码库，以提出一个逻辑化的文档结构。它会考虑您指定的目标受众、规则和反馈，以创建一个最佳大纲。
+2.  **结构规划**：一个 Agent 会分析代码库，以提出一个逻辑性的文档结构。它会根据项目的构成和任何指定的规则创建一个大纲。
 
-3.  **内容生成**：一旦结构确定，`content-detail-generator` 和 `batch-docs-detail-generator` Agent 就会接管。它们会用详细内容填充文档计划的每个部分，确保技术准确性并遵循定义的风格。
+3.  **内容生成**：结构就位后，内容生成 Agent 会为文档计划的每个部分填充详细的文本、代码示例和解释。
 
-4.  **优化与更新**：如果您使用 `aigne doc update` 或 `aigne doc generate --feedback` 提供反馈，`detail-regenerator` 和 `feedback-refiner` Agent 将被激活。它们会根据您的输入更新特定文档或调整整体结构。
+4.  **优化和更新**：当你通过 `aigne doc update` 或 `aigne doc generate --feedback` 提供输入时，特定的 Agent 会被激活，以更新单个文档或调整整体结构。
 
-5.  **翻译与发布**：最后，像 `translate` 和 `publish-docs` 这样的可选 Agent 会处理多语言翻译和发布到 Discuss Kit 平台的工作，从而完成端到端的工作流。
+5.  **翻译和发布**：主要内容生成后，可选的 Agent 会处理多语言翻译和将最终文档发布到网络平台等任务。
 
 ## 关键 AI Agent
 
-DocSmith 的功能源于其专业化的 Agent 团队。虽然许多 Agent 在幕后工作，但以下是文档生成流水线中的一些关键角色：
+DocSmith 的功能由项目配置中定义的一组 Agent 提供。每个 Agent 都有特定的角色。下表列出了一些关键 Agent 及其功能。
 
-| Agent 角色 | 主要功能 | 相关文件 |
-|---|---|---|
-| **Structure Planner** | 分析源代码和规则，生成整体文档大纲。 | `structure-planning.yaml`, `reflective-structure-planner.yaml` |
-| **Content Generator** | 根据计划为每个独立的文档部分撰写详细内容。 | `content-detail-generator.yaml`, `batch-docs-detail-generator.yaml` |
-| **Translation Agent** | 将生成的文档翻译成多种目标语言。 | `translate.yaml`, `batch-translate.yaml` |
-| **Refinement Agent** | 根据用户反馈重新生成或修改内容和结构。 | `detail-regenerator.yaml`, `feedback-refiner.yaml` |
-| **Publishing Agent** | 管理将文档发布到 Discuss Kit 实例的过程。 | `publish-docs.mjs`, `team-publish-docs.yaml` |
-| **Configuration Loader** | 读取并解析项目的配置文件和源文件。 | `load-config.mjs`, `load-sources.mjs` |
+| 功能角色 | 关键 Agent 文件 | 描述 |
+| --- | --- | --- |
+| **结构规划** | `generate/generate-structure.yaml` | 分析源代码以提出初始文档大纲。 |
+| **结构优化** | `generate/refine-document-structure.yaml` | 根据用户反馈修改文档结构。 |
+| **内容生成** | `update/batch-generate-document.yaml`, `generate-document.yaml` | 为每个部分填充详细内容，以充实文档结构。 |
+| **翻译** | `translate/translate-document.yaml`, `translate-multilingual.yaml` | 将生成的文档翻译成多种目标语言。 |
+| **发布** | `publish/publish-docs.mjs` | 管理将文档发布到 Discuss Kit 实例的过程。 |
+| **数据 I/O** | `utils/load-sources.mjs`, `utils/save-docs.mjs` | 负责读取源文件并将最终的 markdown 文档写入磁盘。 |
 
-这种模块化的、基于 Agent 的架构使得 DocSmith 灵活而强大，允许流程中的每一步都能被独立优化。
+这种基于 Agent 的架构使得文档流程的每一步都由一个专门的工具来处理，从而确保了工作流程的结构化和可维护性。
 
 ---
 
-现在您已经了解了 DocSmith 背后的工作原理，请在 [质量保证](./advanced-quality-assurance.md) 部分了解为保证输出质量而采取的措施。
+要了解 DocSmith 为确保输出的准确性和格式而采取的措施，请继续阅读[质量保证](./advanced-quality-assurance.md)部分。

package/docs/advanced-quality-assurance.md

@@ -40,7 +40,6 @@ QA-Pipeline: {
     shape: rectangle
     grid-columns: 2
     D2-Diagrams: "Validates D2 syntax"
-    Mermaid-Diagrams: "Validates Mermaid syntax"
     Markdown-Linting: "Enforces style rules"
   }
 }
@@ -62,38 +61,36 @@ DocSmith's quality assurance process covers several key areas to ensure document
 
 DocSmith performs several checks to ensure the structural integrity of the content:
 
-- **Incomplete Code Blocks**: Detects code blocks that are opened with ```` ``` ```` but never closed.
+- **Incomplete Code Blocks**: Detects code blocks that are opened with ` ``` ` but never closed.
 - **Missing Line Breaks**: Identifies content that appears on a single line, which may indicate missing newlines.
 - **Content Endings**: Verifies that the content ends with appropriate punctuation (e.g., `.`, `)`, `|`, `>`) to prevent truncated output.
+- **Code Block Indentation**: Analyzes code blocks for inconsistent indentation. If a line of code has less indentation than the opening ` ``` ` marker, it can cause rendering problems. This check helps maintain correct code presentation.
 
 #### Link and Media Integrity
 
-- **Link Integrity**: All relative links within the documentation are validated against the project's `structurePlan` to prevent dead links. This ensures that all internal navigation works as expected. The checker ignores external links (starting with `http://` or `https://`) and `mailto:` links.
+- **Link Integrity**: All relative links within the documentation are validated against the document structure plan to prevent dead links. This ensures that all internal navigation works as expected. The checker ignores external links (starting with `http://` or `https://`) and `mailto:` links.
 
 - **Image Validation**: To avoid broken images, the checker verifies that any local image file referenced in the documentation exists on the file system. It resolves both relative and absolute paths to confirm the file is present. External image URLs and data URLs are not checked.
 
 #### Diagram Syntax Validation
 
-- **D2 Diagrams**: DocSmith validates D2 diagram syntax by sending the code to a rendering service. This process confirms that the diagram can be successfully compiled into an SVG image, catching any syntax errors before they result in a broken graphic.
-
-- **Mermaid Diagrams**: Mermaid diagrams undergo several checks: a primary syntax validation, and specific checks for patterns known to cause rendering issues, such as backticks or numbered lists within node labels, and unquoted special characters that require quotes.
+- **D2 Diagrams**: DocSmith validates D2 diagram syntax by attempting to compile the code into an SVG image. This process catches any syntax errors before they can result in a broken graphic.
 
 #### Formatting and Style Enforcement
 
 - **Table Formatting**: Tables are inspected for mismatched column counts between the header, the separator line, and the data rows. This check prevents common table rendering failures.
 
-- **Code Block Indentation**: The checker analyzes code blocks for inconsistent indentation. If a line of code has less indentation than the opening ```` ``` ```` marker, it can cause rendering problems. This check helps maintain correct code presentation.
-
 - **Markdown Linting**: A built-in linter enforces a consistent Markdown structure. Key rules include:
 
 | Rule ID | Description |
 |---|---|
 | `no-duplicate-headings` | Prevents multiple headings with the same content in the same section. |
 | `no-undefined-references` | Ensures all link and image references are defined. |
+| `no-unused-definitions` | Flags link or image definitions that are not used. |
 | `no-heading-content-indent` | Disallows indentation before heading content. |
 | `no-multiple-toplevel-headings` | Allows only one top-level heading (H1) per document. |
 | `code-block-style` | Enforces a consistent style for code blocks (e.g., using backticks). |
 
 By automating these checks, DocSmith maintains a consistent standard for documentation, ensuring the final output is accurate and navigable.
 
-To learn more about the overall architecture, see the [How It Works](./advanced-how-it-works.md) section.
+To learn more about the overall architecture, see the [How It Works](./advanced-how-it-works.md) section.

package/docs/advanced-quality-assurance.zh.md

@@ -1,8 +1,8 @@
 # 质量保证
 
-为确保所有生成的文档功能正常、清晰且专业，DocSmith 引入了自动化的质量保证流程。该流程会对 Markdown 内容执行一系列检查，以便在发布前检测并报告从链接失效到图表格式错误等常见问题。
+为确保所有生成的文档功能正常、清晰且专业，DocSmith 集成了一个自动化的质量保证流程。该流程会对 Markdown 内容执行一系列检查，以便在发布前检测并报告从损坏的链接到格式错误的图表等常见问题。
 
-该自动化流程会验证内容结构、链接、媒体和语法，以保持一致的质量标准。
+此自动化管道会验证内容结构、链接、媒体和语法，以保持一致的质量标准。
 
 ```d2
 direction: down
@@ -13,7 +13,7 @@ Input-Markdown-Content: {
 }
 
 QA-Pipeline: {
-  label: "质量保证流程"
+  label: "质量保证管道"
   shape: rectangle
   grid-columns: 1
   grid-gap: 50
@@ -23,7 +23,7 @@ QA-Pipeline: {
     shape: rectangle
     grid-columns: 2
     Completeness: "确保内容未被截断"
-    Code-Blocks: "验证代码块语法和缩进"
+    Code-Blocks: "验证块语法和缩进"
   }
 
   Content-Validation: {
@@ -40,7 +40,6 @@ QA-Pipeline: {
     shape: rectangle
     grid-columns: 2
     D2-Diagrams: "验证 D2 语法"
-    Mermaid-Diagrams: "验证 Mermaid 语法"
     Markdown-Linting: "强制执行样式规则"
   }
 }
@@ -60,40 +59,38 @@ DocSmith 的质量保证流程涵盖了几个关键领域，以确保文档的
 
 #### 内容结构与完整性
 
-DocSmith 会执行多项检查以确保内容的结构完整性：
+DocSmith 会执行多项检查，以确保内容的结构完整性：
 
-- **不完整的代码块**：检测以 ```` ``` ```` 开头但未关闭的代码块。
-- **缺少换行符**：识别显示在单行上的内容，这可能表示缺少换行符。
+- **代码块不完整**：检测以 ` ``` ` 开头但未关闭的代码块。
+- **缺少换行符**：识别出现在单行上的内容，这可能表示缺少换行符。
 - **内容结尾**：验证内容是否以适当的标点符号（例如 `.`、`)`、`|`、`>`）结尾，以防止输出被截断。
+- **代码块缩进**：分析代码块中不一致的缩进。如果某行代码的缩进小于起始的 ` ``` ` 标记，可能会导致渲染问题。此项检查有助于保持正确的代码呈现。
 
-#### 链接和媒体完整性
+#### 链接与媒体完整性
 
-- **链接完整性**：文档中的所有相对链接都会根据项目的 `structurePlan` 进行验证，以防止出现死链接。这确保了所有内部导航都能正常工作。检查程序会忽略外部链接（以 `http://` 或 `https://` 开头）和 `mailto:` 链接。
+- **链接完整性**：文档中的所有相对链接都会根据文档结构计划进行验证，以防止出现死链接。这确保了所有内部导航都能正常工作。检查器会忽略外部链接（以 `http://` 或 `https://` 开头）和 `mailto:` 链接。
 
-- **图片验证**：为避免图片损坏，检查程序会验证文档中引用的任何本地图片文件是否存在于文件系统中。它会解析相对路径和绝对路径以确认文件存在。外部图片 URL 和数据 URL 不会被检查。
+- **图片验证**：为避免图片损坏，检查器会验证文档中引用的任何本地图片文件是否存在于文件系统中。它会解析相对路径和绝对路径，以确认文件存在。外部图片 URL 和数据 URL 不会被检查。
 
 #### 图表语法验证
 
-- **D2 图表**：DocSmith 通过将代码发送到渲染服务来验证 D2 图表语法。此过程会确认图表能否成功编译为 SVG 图片，从而在导致图形损坏前捕获任何语法错误。
+- **D2 图表**：DocSmith 通过尝试将代码编译成 SVG 图片来验证 D2 图表语法。这个过程可以在语法错误导致图形损坏之前捕获它们。
 
-- **Mermaid 图表**：Mermaid 图表会经过多项检查：一次主语法验证，以及针对已知会导致渲染问题的模式的特定检查，例如节点标签内的反引号或编号列表，以及需要加引号但未加的特殊字符。
+#### 格式与样式强制
 
-#### 格式化与样式强制
-
-- **表格格式化**：检查表格的表头、分隔线和数据行之间的列数是否不匹配。此检查可防止常见的表格渲染失败。
-
-- **代码块缩进**：检查程序会分析代码块中不一致的缩进。如果某行代码的缩进小于开头的 ```` ``` ```` 标记，可能会导致渲染问题。此检查有助于保持正确的代码呈现。
+- **表格格式**：检查表格的表头、分隔线和数据行之间的列数是否不匹配。此项检查可防止常见的表格渲染失败。
 
 - **Markdown Linting**：内置的 linter 会强制执行一致的 Markdown 结构。关键规则包括：
 
 | 规则 ID | 描述 |
 |---|---|
-| `no-duplicate-headings` | 防止同一节中出现内容相同的多个标题。 |
-| `no-undefined-references` | 确保所有链接和图片引用都已定义。 |
+| `no-duplicate-headings` | 防止在同一部分中出现内容相同的多个标题。 |
+| `no-undefined-references` | 确保所有的链接和图片引用都已定义。 |
+| `no-unused-definitions` | 标记未使用的链接或图片定义。 |
 | `no-heading-content-indent` | 不允许在标题内容前缩进。 |
 | `no-multiple-toplevel-headings` | 每个文档只允许一个顶级标题 (H1)。 |
-| `code-block-style` | 强制代码块使用一致的样式（例如，使用反引号）。 |
+| `code-block-style` | 对代码块强制执行一致的样式（例如，使用反引号）。 |
 
 通过自动化这些检查，DocSmith 保持了文档的一致标准，确保最终输出准确且易于导航。
 
-要了解有关整体架构的更多信息，请参阅 [工作原理](./advanced-how-it-works.md) 部分。
+要了解有关整体架构的更多信息，请参阅 [工作原理](./advanced-how-it-works.md) 部分。

package/docs/cli-reference.md

@@ -54,11 +54,6 @@ End: {
   style.fill: "#a2eeaf"
 }
 
-prefs: {
-  label: "aigne doc prefs\n(Manage Learned Rules)"
-  shape: cylinder
-}
-
 Start -> init: "Optional" {
   style.stroke-dash: 4
 }
@@ -68,50 +63,44 @@ generate -> refinement-cycle: "Refine"
 refinement-cycle -> publish: "Ready"
 generate -> publish: "Direct Deploy"
 publish -> End
-
-prefs <-> generate: "Influences" {
-  style.stroke-dash: 2
-}
-prefs <-> refinement-cycle: "Influences" {
-  style.stroke-dash: 2
-}
 ```
 
 ---
 
 ## `aigne doc generate`
 
-**Aliases:** `gen`, `g`
-
 Analyzes your source code and generates a complete set of documentation based on your configuration. If no configuration is found, it automatically launches the interactive setup wizard.
 
 ### Options
 
-| Option | Type | Description |
-|---|---|---|
-| `--feedback` | string | Provides feedback to adjust and refine the overall documentation structure. |
-| `--forceRegenerate` | boolean | Discards existing content and regenerates all documentation from scratch. |
-| `--model` | string | Specifies a particular LLM to use for generation (e.g., `openai:gpt-4o`). Overrides the default model. |
-| `--glossary` | string | Path to a glossary file for consistent terminology. Use the format `@path/to/glossary.md`. |
+| Option              | Type    | Description                                                                                                   |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
+| `--feedback`        | string  | Provides feedback to adjust and refine the overall documentation structure.                                   |
+| `--forceRegenerate` | boolean | Discards existing content and regenerates all documentation from scratch.                                     |
+| `--model`           | string  | Specifies a particular large language model to use for generation (e.g., `openai:gpt-4o`). Overrides the default. |
 
 ### Usage Examples
 
-**Generate documentation for the first time or update it:**
+**Generate or update documentation:**
+
 ```bash
 aigne doc generate
 ```
 
 **Force a complete regeneration of all documents:**
+
 ```bash
 aigne doc generate --forceRegenerate
 ```
 
 **Refine the document structure with feedback:**
+
 ```bash
 aigne doc generate --feedback "Add a new section for API examples and remove the 'About' page."
 ```
 
 **Generate using a specific model from AIGNE Hub:**
+
 ```bash
 aigne doc generate --model google:gemini-1.5-flash
 ```
@@ -120,29 +109,27 @@ aigne doc generate --model google:gemini-1.5-flash
 
 ## `aigne doc update`
 
-**Alias:** `up`
-
 Optimizes and regenerates specific documents. You can run it interactively to select documents or specify them directly with options. This is useful for making targeted improvements based on feedback without regenerating the entire project.
 
 ### Options
 
-| Option | Type | Description |
-|---|---|---|
-| `--docs` | array | A list of document paths to regenerate (e.g., `--docs overview.md`). Can be used multiple times. |
-| `--feedback` | string | Provides specific feedback to improve the content of the selected document(s). |
-| `--glossary` | string | Path to a glossary file for consistent terminology. Use the format `@path/to/glossary.md`. |
-| `--reset` | boolean | Ignores previous results and regenerates content from scratch for the selected documents. |
+| Option     | Type  | Description                                                                                 |
+| ---------- | ----- | ------------------------------------------------------------------------------------------- |
+| `--docs`     | array | A list of document paths to regenerate. Can be used multiple times.                         |
+| `--feedback` | string | Provides specific feedback to improve the content of the selected document(s).              |
 
 ### Usage Examples
 
-**Start an interactive session to select which document to update:**
+**Start an interactive session to select a document to update:**
+
 ```bash
 aigne doc update
 ```
 
 **Update a specific document with targeted feedback:**
+
 ```bash
-aigne doc update --docs /cli-reference --feedback "Clarify the difference between the --docs and --langs options."
+aigne doc update --docs overview.md --feedback "Add more detailed FAQ entries"
 ```
 
 ---
@@ -153,54 +140,57 @@ Translates existing documentation into one or more languages. It can be run inte
 
 ### Options
 
-| Option | Type | Description |
-|---|---|---|
-| `--docs` | array | A list of document paths to translate. Can be used multiple times. |
-| `--langs` | array | A list of target language codes (e.g., `zh`, `ja`, `es`). Can be used multiple times. |
-| `--feedback` | string | Provides feedback to improve the quality of the translation. |
-| `--glossary` | string | Path to a glossary file to ensure consistent terminology across languages. Use `@path/to/glossary.md`. |
+| Option       | Type  | Description                                                                                                |
+| ------------ | ----- | ---------------------------------------------------------------------------------------------------------- |
+| `--docs`       | array | A list of document paths to translate. Can be used multiple times.                                         |
+| `--langs`      | array | A list of target language codes (e.g., `zh`, `ja`). Can be used multiple times.                            |
+| `--feedback`   | string | Provides feedback to improve the quality of the translation.                                               |
+| `--glossary`   | string | Path to a glossary file to ensure consistent terminology across languages. Use `@path/to/glossary.md`. |
 
 ### Usage Examples
 
 **Start an interactive translation session:**
+
 ```bash
 aigne doc translate
 ```
 
 **Translate specific documents into Chinese and Japanese:**
+
 ```bash
-aigne doc translate --docs overview.md --docs getting-started.md --langs zh --langs ja
+aigne doc translate --langs zh --langs ja --docs examples.md --docs overview.md
 ```
 
 **Translate with a glossary and feedback for better quality:**
+
 ```bash
-aigne doc translate --glossary @glossary.md --feedback "Use formal language for the Japanese translation."
+aigne doc translate --glossary @glossary.md --feedback "Use technical terminology consistently"
 ```
 
 ---
 
 ## `aigne doc publish`
 
-**Aliases:** `pub`, `p`
-
 Publishes your generated documentation to a Discuss Kit platform. You can publish to the official AIGNE DocSmith platform or to your own self-hosted instance.
 
 ### Options
 
-| Option | Type | Description |
-|---|---|---|
+| Option     | Type   | Description                                                                                          |
+| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
 | `--appUrl` | string | The URL of your self-hosted Discuss Kit instance. If not provided, the command runs interactively. |
 
 ### Usage Examples
 
 **Start an interactive publishing session:**
+
 ```bash
 aigne doc publish
 ```
 
 **Publish directly to a self-hosted instance:**
+
 ```bash
-aigne doc publish --appUrl https://docs.my-company.com
+aigne doc publish --appUrl https://your-discuss-kit-instance.com
 ```
 
 ---
@@ -212,40 +202,9 @@ Manually starts the interactive configuration wizard. This is useful for setting
 ### Usage Example
 
 **Launch the setup wizard:**
-```bash
-aigne doc init
-```
-
----
-
-## `aigne doc prefs`
-
-Manages user preferences that DocSmith learns from your feedback over time. These preferences are applied as rules in future generation and update tasks to maintain consistency with your style.
-
-### Options
-
-| Option | Type | Description |
-|---|---|---|
-| `--list` | boolean | Lists all saved preferences, showing their status (active/inactive), scope, and content. |
-| `--remove` | boolean | Removes one or more preferences. Runs interactively if `--id` is not provided. |
-| `--toggle` | boolean | Toggles the active status of one or more preferences. Runs interactively if `--id` is not provided. |
-| `--id` | array | Specifies the preference ID(s) to act upon for `--remove` or `--toggle`. Can be used multiple times. |
 
-### Usage Examples
-
-**List all your saved preferences:**
-```bash
-aigne doc prefs --list
-```
-
-**Interactively select preferences to remove:**
 ```bash
-aigne doc prefs --remove
-```
-
-**Toggle the status of a specific preference by its ID:**
-```bash
-aigne doc prefs --toggle --id <preference-id>
+aigne doc init
 ```
 
 For more details on how to tailor DocSmith to your needs, see the [Configuration Guide](./configuration.md).