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

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).

package/docs/cli-reference.zh.md

@@ -1,8 +1,8 @@
 # CLI 命令参考
 
-本指南为所有可用的 `aigne doc` 子命令及其参数和选项提供了参考。旨在帮助用户充分利用命令行界面。
+本指南为所有可用的 `aigne doc` 子命令及其参数和选项提供了参考。它旨在帮助希望充分利用命令行的用户。
 
-通用语法如下：
+通用语法为：
 
 ```bash
 aigne doc <command> [options]
@@ -10,7 +10,7 @@ aigne doc <command> [options]
 
 ### 命令工作流
 
-下图展示了使用 DocSmith 的 CLI 命令创建和维护文档的典型生命周期：
+下图展示了使用 DocSmith CLI 命令创建和维护文档的典型生命周期：
 
 ```d2
 direction: down
@@ -54,11 +54,6 @@ End: {
   style.fill: "#a2eeaf"
 }
 
-prefs: {
-  label: "aigne doc prefs\n(管理学习到的规则)"
-  shape: cylinder
-}
-
 Start -> init: "可选" {
   style.stroke-dash: 4
 }
@@ -68,50 +63,44 @@ generate -> refinement-cycle: "优化"
 refinement-cycle -> publish: "就绪"
 generate -> publish: "直接部署"
 publish -> End
-
-prefs <-> generate: "影响" {
-  style.stroke-dash: 2
-}
-prefs <-> refinement-cycle: "影响" {
-  style.stroke-dash: 2
-}
 ```
 
 ---
 
 ## `aigne doc generate`
 
-**别名：** `gen`, `g`
-
 分析您的源代码，并根据您的配置生成一套完整的文档。如果未找到配置，它将自动启动交互式设置向导。
 
 ### 选项
 
-| Option | Type | Description |
-|---|---|---|
-| `--feedback` | string | 提供反馈以调整和优化整体文档结构规划。 |
-| `--forceRegenerate` | boolean | 丢弃现有内容，从头开始重新生成所有文档。 |
-| `--model` | string | 指定用于生成的特定 LLM（例如，`openai:gpt-4o`）。此选项将覆盖默认模型。 |
-| `--glossary` | string | 用于保持术语一致性的术语表文件路径。使用 `@path/to/glossary.md` 格式。 |
+| Option              | Type    | Description                                                                                                   |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
+| `--feedback`        | string  | 提供反馈以调整和优化整体文档结构。                                   |
+| `--forceRegenerate` | boolean | 丢弃现有内容并从头开始重新生成所有文档。                                     |
+| `--model`           | string  | 指定用于生成的特定大语言模型（例如，`openai:gpt-4o`）。此选项将覆盖默认设置。 |
 
 ### 使用示例
 
-**首次生成或更新文档：**
+**生成或更新文档：**
+
 ```bash
 aigne doc generate
 ```
 
 **强制完全重新生成所有文档：**
+
 ```bash
 aigne doc generate --forceRegenerate
 ```
 
 **通过反馈优化文档结构：**
+
 ```bash
-aigne doc generate --feedback "为 API 示例添加一个新部分，并删除‘关于’页面。"
+aigne doc generate --feedback "Add a new section for API examples and remove the 'About' page."
 ```
 
-**使用 AIGNE Hub 中的特定模型进行生成：**
+**使用 AIGNE Hub 中的特定模型生成：**
+
 ```bash
 aigne doc generate --model google:gemini-1.5-flash
 ```
@@ -120,132 +109,102 @@ aigne doc generate --model google:gemini-1.5-flash
 
 ## `aigne doc update`
 
-**别名：** `up`
-
-优化并重新生成特定文档。您可以以交互方式运行以选择文档，或直接使用选项指定文档。此命令对于根据反馈进行有针对性的改进非常有用，无需重新生成整个项目。
+优化并重新生成特定文档。您可以以交互方式运行它来选择文档，或直接使用选项指定文档。这对于根据反馈进行有针对性的改进非常有用，而无需重新生成整个项目。
 
 ### 选项
 
-| Option | Type | Description |
-|---|---|---|
-| `--docs` | array | 要重新生成的文档路径列表（例如，`--docs overview.md`）。可多次使用。 |
-| `--feedback` | string | 提供具体反馈以改进所选文档的内容。 |
-| `--glossary` | string | 用于保持术语一致性的术语表文件路径。使用 `@path/to/glossary.md` 格式。 |
-| `--reset` | boolean | 忽略之前的结果，为所选文档从头开始重新生成内容。 |
+| Option     | Type  | Description                                                                                 |
+| ---------- | ----- | ------------------------------------------------------------------------------------------- |
+| `--docs`     | array | 要重新生成的文档路径列表。可多次使用。                         |
+| `--feedback` | string | 提供具体反馈以改进所选文档的内容。              |
 
 ### 使用示例
 
 **启动交互式会话以选择要更新的文档：**
+
 ```bash
 aigne doc update
 ```
 
-**使用针对性反馈更新特定文档：**
+**使用有针对性的反馈更新特定文档：**
+
 ```bash
-aigne doc update --docs /cli-reference --feedback "阐明 --docs 和 --langs 选项之间的区别。"
+aigne doc update --docs overview.md --feedback "Add more detailed FAQ entries"
 ```
 
 ---
 
 ## `aigne doc translate`
 
-将现有文档翻译成一种或多种语言。可以以交互方式运行以选择文档和语言，也可以通过参数指定以非交互方式运行。
+将现有文档翻译成一种或多种语言。可以以交互方式运行它来选择文档和语言，也可以通过将它们指定为参数以非交互方式运行。
 
 ### 选项
 
-| Option | Type | Description |
-|---|---|---|
-| `--docs` | array | 要翻译的文档路径列表。可多次使用。 |
-| `--langs` | array | 目标语言代码列表（例如，`zh`、`ja`、`es`）。可多次使用。 |
-| `--feedback` | string | 提供反馈以提高翻译质量。 |
-| `--glossary` | string | 用于确保跨语言术语一致性的术语表文件路径。使用 `@path/to/glossary.md`。 |
+| Option       | Type  | Description                                                                                                |
+| ------------ | ----- | ---------------------------------------------------------------------------------------------------------- |
+| `--docs`       | array | 要翻译的文档路径列表。可多次使用。                                         |
+| `--langs`      | array | 目标语言代码列表（例如，`zh`、`ja`）。可多次使用。                            |
+| `--feedback`   | string | 提供反馈以提高翻译质量。                                               |
+| `--glossary`   | string | 词汇表文件的路径，以确保跨语言术语的一致性。使用 `@path/to/glossary.md`。 |
 
 ### 使用示例
 
 **启动交互式翻译会话：**
+
 ```bash
 aigne doc translate
 ```
 
 **将特定文档翻译成中文和日文：**
+
 ```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
 ```
 
-**结合使用术语表和反馈以获得更高质量的翻译：**
+**使用词汇表和反馈进行翻译以获得更好的质量：**
+
 ```bash
-aigne doc translate --glossary @glossary.md --feedback "日语翻译请使用正式语言。"
+aigne doc translate --glossary @glossary.md --feedback "Use technical terminology consistently"
 ```
 
 ---
 
 ## `aigne doc publish`
 
-**别名：** `pub`, `p`
-
-将您生成的文档发布到 Discuss Kit 平台。您可以发布到官方的 AIGNE DocSmith 平台，也可以发布到您自己托管的实例。
+将您生成的文档发布到 Discuss Kit 平台。您可以发布到官方的 AIGNE DocSmith 平台或您自己托管的实例。
 
 ### 选项
 
-| Option | Type | Description |
-|---|---|---|
-| `--appUrl` | string | 您自托管的 Discuss Kit 实例的 URL。如果未提供，该命令将以交互方式运行。 |
+| Option     | Type   | Description                                                                                          |
+| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
+| `--appUrl` | string | 您自行托管的 Discuss Kit 实例的 URL。如果未提供，该命令将以交互方式运行。 |
 
 ### 使用示例
 
 **启动交互式发布会话：**
+
 ```bash
 aigne doc publish
 ```
 
-**直接发布到自托管实例：**
+**直接发布到自行托管的实例：**
+
 ```bash
-aigne doc publish --appUrl https://docs.my-company.com
+aigne doc publish --appUrl https://your-discuss-kit-instance.com
 ```
 
 ---
 
 ## `aigne doc init`
 
-手动启动交互式配置向导。这对于设置新项目或修改现有项目的配置非常有用。该向导将引导您定义源代码路径、设置输出目录、选择语言以及定义文档的风格和目标受众。
+手动启动交互式配置向导。这对于设置新项目或修改现有项目的配置非常有用。该向导会引导您定义源代码路径、设置输出目录、选择语言以及定义文档的风格和目标受众。
 
 ### 使用示例
 
 **启动设置向导：**
-```bash
-aigne doc init
-```
-
----
-
-## `aigne doc prefs`
-
-管理 DocSmith 随时间从您的反馈中学习到的用户偏好。这些偏好将在未来的生成和更新任务中作为规则应用，以保持与您的风格一致。
-
-### 选项
-
-| Option | Type | Description |
-|---|---|---|
-| `--list` | boolean | 列出所有已保存的偏好，显示其状态（激活/未激活）、范围和内容。 |
-| `--remove` | boolean | 移除一个或多个偏好。如果未提供 `--id`，则以交互方式运行。 |
-| `--toggle` | boolean | 切换一个或多个偏好的激活状态。如果未提供 `--id`，则以交互方式运行。 |
-| `--id` | array | 为 `--remove` 或 `--toggle` 指定要操作的偏好 ID。可多次使用。 |
 
-### 使用示例
-
-**列出所有已保存的偏好：**
-```bash
-aigne doc prefs --list
-```
-
-**以交互方式选择要移除的偏好：**
 ```bash
-aigne doc prefs --remove
-```
-
-**通过 ID 切换特定偏好的状态：**
-```bash
-aigne doc prefs --toggle --id <preference-id>
+aigne doc init
 ```
 
-有关如何根据您的需求定制 DocSmith 的更多详细信息，请参阅[配置指南](./configuration.md)。
+有关如何根据您的需求定制 DocSmith 的更多详细信息，请参阅[配置指南](./configuration.md)。