@aigne/doc-smith 0.8.12-beta.3 → 0.8.12-beta.4

package/docs/configuration-initial-setup.zh.md

@@ -0,0 +1,179 @@
+# 初始设置
+
+本指南将分步介绍 AIGNE DocSmith 的交互式设置过程。此过程在您首次运行 `generate` 命令时启动，也可以手动启动。其目的是创建一个 `config.yaml` 文件，用于存储您生成文档的偏好设置。
+
+## 启动过程
+
+要手动开始配置，请在终端中导航到项目的根目录并执行以下命令：
+
+```bash
+aigne doc init
+```
+
+此命令会启动一个交互式问卷，引导您完成文档设置的配置。
+
+## 配置步骤
+
+设置过程包括九个问题，旨在根据您的具体需求定制文档。
+
+### 步骤 1：定义文档目的
+
+首先，您需要定义文档的主要目标。此选择会影响生成内容的基调、结构和重点。
+
+**提示：** `📝 [1/9]：您的文档应帮助读者实现什么目标？`
+
+您可以从下面的列表中选择多个选项：
+
+| 选项 | 名称 | 描述 |
+| :--- | :--- | :--- |
+| `getStarted` | 快速入门 | 帮助新用户在 30 分钟内从零开始上手。 |
+| `completeTasks` | 完成特定任务 | 指导用户完成常见工作流和用例。 |
+| `findAnswers` | 快速查找答案 | 为所有功能和 API 提供可搜索的参考。 |
+| `understandSystem` | 理解系统 | 解释其工作原理及设计决策背后的原因。 |
+| `solveProblems` | 解决问题 | 帮助用户排查和修复问题。 |
+| `mixedPurpose` | 以上混合 | 全面覆盖多种需求。 |
+
+### 步骤 2：确定目标受众
+
+接下来，指定谁将是您文档的主要读者。这有助于适当地调整语言和技术深度。
+
+**提示：** `👥 [2/9]：谁将是您文档的读者？`
+
+您可以选择以下一个或多个受众：
+
+| 选项 | 名称 | 描述 |
+| :--- | :--- | :--- |
+| `endUsers` | 最终用户（非技术人员） | 使用产品但不编码的人员。 |
+| `developers` | 集成开发者 | 将此产品添加到其项目中的工程师。 |
+| `devops` | DevOps/基础设施 | 部署、监控和维护系统的团队。 |
+| `decisionMakers` | 技术决策者 | 评估该技术的架构师或负责人。 |
+| `supportTeams` | 支持团队 | 帮助他人使用产品的人员。 |
+| `mixedTechnical` | 混合技术受众 | 开发人员、DevOps 和其他技术用户的组合。 |
+
+### 步骤 3：提供自定义规则
+
+此可选步骤允许您提供具体说明或约束，供 AI 在内容生成过程中遵循。
+
+**提示：** `📋 [3/9]：对您的文档有任何自定义规则或要求吗？（可选，按 Enter 键跳过）`
+
+您可以输入任何具体要求，例如语气、风格或要排除的内容。例如：“避免使用营销性语言，专注于技术准确性。”
+
+### 步骤 4：指定读者知识水平
+
+指明您受众的假定知识水平。这能确保内容难度适中，既不会过于基础，也不会过于复杂。
+
+**提示：** `🧠 [4/9]：读者对您的项目了解多少？`
+
+选择最能描述您读者的选项：
+
+| 选项 | 名称 | 描述 |
+| :--- | :--- | :--- |
+| `completeBeginners` | 完全初学者 | 完全不熟悉该领域或技术。 |
+| `domainFamiliar` | 熟悉领域，不熟悉工具 | 了解问题领域，但对该解决方案不熟悉。 |
+| `experiencedUsers` | 经验丰富的用户 | 需要参考或高级主题的常规用户。 |
+| `emergencyTroubleshooting` | 紧急/故障排查 | 需要快速解决问题的用户。 |
+| `exploringEvaluating` | 探索/评估 | 试图确定该工具是否满足其需求的用户。 |
+
+### 步骤 5：设置文档深度
+
+选择文档的详细程度。这决定了生成内容的范围和细节水平。
+
+**提示：** `📊 [5/9]：您的文档应该有多详细？`
+
+选择以下详细级别之一：
+
+| 选项 | 名称 | 描述 |
+| :--- | :--- | :--- |
+| `essentialOnly` | 仅包含核心内容 | 简明扼要地覆盖 80% 的最常见用例。 |
+| `balancedCoverage` | 平衡覆盖 | 提供良好深度和实用示例。 |
+| `comprehensive` | 全面详尽 | 覆盖所有功能、边缘案例和高级场景。 |
+| `aiDecide` | 由 AI 决定 | 工具会分析代码复杂度以建议合适的深度。 |
+
+### 步骤 6：选择主要语言
+
+选择您文档的主要语言。系统将检测您操作系统的语言并建议其为默认语言。
+
+**提示：** `🌐 [6/9]：您的主要文档语言是什么？`
+
+系统将为您呈现一个包含 12 种受支持语言的列表，包括英语、中文（简体）和西班牙语。
+
+### 步骤 7：选择翻译语言
+
+选择您希望将文档翻译成的其他语言。
+
+**提示：** `🔄 [7/9]：我们应该翻译成哪些语言？`
+
+您可以从支持的选项列表中选择多种语言，不包括您在上一步中选择的主要语言。
+
+### 步骤 8：定义输出目录
+
+指定保存生成的文档文件的文件夹。
+
+**提示：** `📁 [8/9]：我们应该将您的文档保存在哪里？`
+
+默认路径是 `.aigne/doc-smith/docs`。您可以接受此路径或提供其他路径。
+
+### 步骤 9：指定内容源
+
+指明工具应分析哪些文件和文件夹以生成文档。您可以添加多个路径，并使用 glob 模式进行高级筛选。
+
+**提示：** `🔍 [9/9]：内容源`
+
+系统将提示您输入文件路径、文件夹路径或 glob 模式（例如，`src/**/*.js`）。如果您不提供任何路径，工具将默认分析整个项目目录。
+
+## 生成的配置文件
+
+完成问卷后，DocSmith 会将您的回答保存到 `.aigne/doc-smith/` 目录中一个名为 `config.yaml` 的配置文件中。该文件将作为未来所有文档生成的蓝图，并可随时手动编辑。
+
+以下是生成的 `config.yaml` 文件示例：
+
+```yaml config.yaml title="config.yaml"
+# 用于文档发布的项目信息
+projectName: AIGNE DocSmith
+projectDesc: AIGNE DocSmith is a powerful, AI-driven documentation generation tool...
+projectLogo: https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg
+
+# =============================================================================
+# 文档配置
+# =============================================================================
+
+# 目的：您希望读者实现的主要成果是什么？
+documentPurpose:
+  - getStarted
+  - completeTasks
+
+# 目标受众：谁会最常阅读本文档？
+targetAudienceTypes:
+  - endUsers
+
+# 读者知识水平：读者通常具备哪些知识？
+readerKnowledgeLevel: completeBeginners
+
+# 文档深度：文档应达到何种程度的全面性？
+documentationDepth: comprehensive
+
+# 自定义规则：定义具体的文档生成规则和要求
+rules: |
+  Avoid using vague or empty words...
+
+# 目标受众：描述您的具体目标受众及其特征
+targetAudience: |
+  
+# 语言设置
+locale: en
+translateLanguages:
+  - zh
+  - ja
+
+# 目录和源路径配置
+docsDir: ./docs  # 保存生成文档的目录
+sourcesPath:  # 要分析的源代码路径
+  - ./README.md
+  - ./agents
+```
+
+## 后续步骤
+
+完成初始配置后，您现在可以开始创建文档了。
+
+*   继续阅读 [生成文档](./guides-generating-documentation.md) 指南，了解如何运行生成过程。

package/docs/configuration-managing-preferences.ja.md

@@ -0,0 +1,100 @@
+# プリファレンスの管理
+
+ドキュメントを生成または更新する際に、`--feedback` フラグを使用してフィードバックを提供できます。このフィードバックは「プリファレンス」として保存され、将来のセッションで再利用されることで、AIが以前の指示との一貫性を維持するようになります。`aigne doc prefs` コマンドは、これらの保存されたプリファレンスを直接管理する方法を提供します。
+
+このガイドでは、保存されたプリファレンスのリスト表示、削除、およびアクティブ状態の切り替え方法について詳しく説明します。
+
+## 保存されたプリファレンスの表示
+
+保存されているすべてのプリファレンスを確認するには、`--list` フラグを使用します。このコマンドは、各プリファレンスをそのステータス、スコープ、一意のID、および内容とともに表示します。
+
+```bash
+aigne doc prefs --list
+```
+
+### 出力の理解
+
+リストは、各プリファレンスルールに関する明確な情報を提供するようにフォーマットされています：
+
+*   **ステータス**: プリファレンスがアクティブか非アクティブかを示します。
+    *   `🟢`: アクティブ。ルールはドキュメント生成中に適用されます。
+    *   `⚪`: 非アクティブ。ルールは保存されていますが、無視されます。
+*   **スコープ**: プリファレンスが適用されるコンテキスト（例：`global`、`document`）。
+*   **ID**: プリファレンスの一意の識別子で、削除や切り替えに使用されます。
+*   **パス**: プリファレンスが特定のファイルにのみ適用される場合、そのパスがここにリストされます。
+*   **ルール内容**: プリファレンスルール自体のテキストです。
+
+**出力例：**
+
+```
+# ユーザープリファレンス
+
+**フォーマットの説明：**
+- 🟢 = アクティブなプリファレンス, ⚪ = 非アクティブなプリファレンス
+- [scope] = プリファレンスのスコープ (global, structure, document, translation)
+- ID = 一意のプリファレンス識別子
+- Paths = 特定のファイルパス（該当する場合）
+
+🟢 [document] 2af5c | Paths: /guides/generating-documentation.md
+   具体的で検証可能な事実と情報に焦点を当てること。測定可能または具体的な情報を提供しない、曖昧または空虚な言葉の使用は避けること...
+
+⚪ [global] 8b1e2
+   ドキュメント全体でフォーマルかつアカデミックなトーンを使用すること。
+
+```
+
+## プリファレンスの削除
+
+プリファレンスが不要になった場合、`--remove` フラグを使用して完全に削除できます。IDを指定するか、インタラクティブメニューを通じてプリファレンスを削除できます。
+
+### インタラクティブモード
+
+リストからプリファレンスを選択するには、IDなしでコマンドを実行します。これにより、削除したい項目をチェックできるインタラクティブなプロンプトが開きます。
+
+```bash
+aigne doc prefs --remove
+```
+
+チェックリストが表示され、1つ以上のプリファレンスを選択できます。これは、正しい項目を確実に削除するための推奨される方法です。
+
+### ダイレクトモード
+
+削除したいプリファレンスの一意のIDがすでにわかっている場合は、`--id` フラグを使用してそれらを指定できます。削除する項目が確かな場合は、この方法がより高速です。
+
+```bash
+# 単一のプリファレンスを削除
+aigne doc prefs --remove --id 2af5c
+
+# 複数のプリファレンスを削除
+aigne doc prefs --remove --id 2af5c --id 8b1e2
+```
+
+## プリファレンスの切り替え
+
+プリファレンスを完全に削除する代わりに、一時的に有効または無効にすることができます。これは、ルールを失うことなく特定のタスクのために一時停止したい場合に便利です。プリファレンスのアクティブ状態を変更するには、`--toggle` フラグを使用します。
+
+### インタラクティブモード
+
+IDなしでコマンドを実行すると、削除コマンドと同様のインタラクティブなチェックリストが起動します。
+
+```bash
+aigne doc prefs --toggle
+```
+
+有効化または無効化したいプリファレンスを選択できます。ステータスアイコン（`🟢`/`⚪`）が更新され、新しい状態が反映されます。
+
+### ダイレクトモード
+
+特定のプリファレンスを直接切り替えるには、`--id` フラグを使用します。
+
+```bash
+# 単一のプリファレンスを切り替え
+aigne doc prefs --toggle --id 2af5c
+
+# 複数のプリファレンスを切り替え
+aigne doc prefs --toggle --id 2af5c --id 8b1e2
+```
+
+---
+
+プリファレンスを管理することで、ドキュメント生成プロセスをきめ細かく制御し、出力がプロジェクトの特定の要件やスタイルに一貫して沿うようにすることができます。

package/docs/configuration-managing-preferences.md

@@ -0,0 +1,100 @@
+# Managing Preferences
+
+When you generate or update documentation, you can provide feedback using the `--feedback` flag. This feedback is saved as a "preference" to be reused in future sessions, ensuring the AI maintains consistency with your previous instructions. The `aigne doc prefs` command provides a direct way to manage these saved preferences.
+
+This guide details how to list, remove, and toggle the active status of your saved preferences.
+
+## Viewing Saved Preferences
+
+To review all saved preferences, use the `--list` flag. This command displays each preference with its status, scope, unique ID, and content.
+
+```bash
+aigne doc prefs --list
+```
+
+### Understanding the Output
+
+The list is formatted to provide clear information about each preference rule:
+
+*   **Status**: Indicates if a preference is active or inactive.
+    *   `🟢`: Active. The rule will be applied during documentation generation.
+    *   `⚪`: Inactive. The rule is saved but will be ignored.
+*   **Scope**: The context in which the preference applies (e.g., `global`, `document`).
+*   **ID**: A unique identifier for the preference, used for removing or toggling.
+*   **Paths**: If the preference applies only to specific files, their paths are listed here.
+*   **Rule Content**: The text of the preference rule itself.
+
+**Example Output:**
+
+```
+# User Preferences
+
+**Format explanation:**
+- 🟢 = Active preference, ⚪ = Inactive preference
+- [scope] = Preference scope (global, structure, document, translation)
+- ID = Unique preference identifier
+- Paths = Specific file paths (if applicable)
+
+🟢 [document] 2af5c | Paths: /guides/generating-documentation.md
+   Focus on concrete, verifiable facts and information. Avoid using vague or empty words that don't provide measurable or specific d...
+
+⚪ [global] 8b1e2
+   Use a formal and academic tone throughout the documentation.
+
+```
+
+## Removing Preferences
+
+When a preference is no longer needed, you can permanently delete it using the `--remove` flag. You can remove preferences either by specifying their IDs or through an interactive menu.
+
+### Interactive Mode
+
+To select preferences from a list, run the command without any IDs. This will open an interactive prompt where you can check the items you wish to delete.
+
+```bash
+aigne doc prefs --remove
+```
+
+A checklist will appear, allowing you to select one or more preferences. This is the recommended method for ensuring you remove the correct items.
+
+### Direct Mode
+
+If you already know the unique IDs of the preferences you want to remove, you can specify them using the `--id` flag. This is faster if you are certain about which items to delete.
+
+```bash
+# Remove a single preference
+aigne doc prefs --remove --id 2af5c
+
+# Remove multiple preferences
+aigne doc prefs --remove --id 2af5c --id 8b1e2
+```
+
+## Toggling Preferences
+
+Instead of permanently deleting a preference, you can temporarily enable or disable it. This is useful when you want to suspend a rule for a specific task without losing it. Use the `--toggle` flag to change a preference's active status.
+
+### Interactive Mode
+
+Running the command without IDs will launch an interactive checklist, similar to the remove command.
+
+```bash
+aigne doc prefs --toggle
+```
+
+You can select the preferences you wish to activate or deactivate. The status icon (`🟢`/`⚪`) will update to reflect the new state.
+
+### Direct Mode
+
+To toggle specific preferences directly, use the `--id` flag.
+
+```bash
+# Toggle a single preference
+aigne doc prefs --toggle --id 2af5c
+
+# Toggle multiple preferences
+aigne doc prefs --toggle --id 2af5c --id 8b1e2
+```
+
+---
+
+By managing your preferences, you can maintain fine-grained control over the documentation generation process, ensuring that the output consistently aligns with your project's specific requirements and style.

package/docs/configuration-managing-preferences.zh-TW.md

@@ -0,0 +1,100 @@
+# 管理偏好設定
+
+當您生成或更新文件時，可以使用 `--feedback` 旗標提供回饋。此回饋會儲存為「偏好設定」，以便在未來的會話中重複使用，確保 AI 與您先前的指示保持一致。`aigne doc prefs` 指令提供了一種直接管理這些已儲存偏好設定的方法。
+
+本指南詳細說明如何列出、移除以及切換您已儲存偏好設定的啟用狀態。
+
+## 檢視已儲存的偏好設定
+
+若要檢視所有已儲存的偏好設定，請使用 `--list` 旗標。此指令會顯示每個偏好設定的狀態、範圍、唯一 ID 和內容。
+
+```bash
+aigne doc prefs --list
+```
+
+### 理解輸出內容
+
+列表經過格式化，以提供關於每個偏好設定規則的清晰資訊：
+
+*   **Status**：指示偏好設定為啟用或停用。
+    *   `🟢`：啟用。此規則將在文件生成期間應用。
+    *   `⚪`：停用。此規則已儲存但將被忽略。
+*   **Scope**：偏好設定應用的情境（例如：`global`、`document`）。
+*   **ID**：偏好設定的唯一識別碼，用於移除或切換狀態。
+*   **Paths**：如果偏好設定僅適用於特定檔案，其路徑會在此列出。
+*   **Rule Content**：偏好設定規則本身的文字。
+
+**輸出範例：**
+
+```
+# 使用者偏好設定
+
+**格式說明：**
+- 🟢 = 啟用中的偏好設定，⚪ = 停用中的偏好設定
+- [scope] = 偏好設定範圍 (global, structure, document, translation)
+- ID = 唯一的偏好設定識別碼
+- Paths = 特定檔案路徑（如果適用）
+
+🟢 [document] 2af5c | Paths: /guides/generating-documentation.md
+   Focus on concrete, verifiable facts and information. Avoid using vague or empty words that don't provide measurable or specific d...
+
+⚪ [global] 8b1e2
+   Use a formal and academic tone throughout the documentation.
+
+```
+
+## 移除偏好設定
+
+當不再需要某個偏好設定時，您可以使用 `--remove` 旗標將其永久刪除。您可以透過指定其 ID 或透過互動式選單來移除偏好設定。
+
+### 互動模式
+
+若要從列表中選擇偏好設定，請執行不含任何 ID 的指令。這將開啟一個互動式提示，您可以在其中勾選您希望刪除的項目。
+
+```bash
+aigne doc prefs --remove
+```
+
+會出現一個清單，讓您選擇一個或多個偏好設定。這是確保您移除正確項目的建議方法。
+
+### 直接模式
+
+如果您已經知道要移除的偏好設定的唯一 ID，您可以使用 `--id` 旗標來指定它們。如果您確定要刪除哪些項目，這種方式會更快。
+
+```bash
+# 移除單一偏好設定
+aigne doc prefs --remove --id 2af5c
+
+# 移除多個偏好設定
+aigne doc prefs --remove --id 2af5c --id 8b1e2
+```
+
+## 切換偏好設定
+
+您可以暫時啟用或停用偏好設定，而不是永久刪除它。當您想為特定任務暫停某個規則而不想失去它時，這非常有用。使用 `--toggle` 旗標來變更偏好設定的啟用狀態。
+
+### 互動模式
+
+執行不含 ID 的指令將會啟動一個互動式清單，類似於移除指令。
+
+```bash
+aigne doc prefs --toggle
+```
+
+您可以選擇您希望啟用或停用的偏好設定。狀態圖示 (`🟢`/`⚪`) 將會更新以反映新的狀態。
+
+### 直接模式
+
+若要直接切換特定偏好設定，請使用 `--id` 旗標。
+
+```bash
+# 切換單一偏好設定
+aigne doc prefs --toggle --id 2af5c
+
+# 切換多個偏好設定
+aigne doc prefs --toggle --id 2af5c --id 8b1e2
+```
+
+---
+
+透過管理您的偏好設定，您可以對文件生成過程進行細緻的控制，確保輸出結果能持續符合您專案的特定要求和風格。

package/docs/configuration-managing-preferences.zh.md

@@ -0,0 +1,100 @@
+# 管理偏好设置
+
+在生成或更新文档时，您可以使用 `--feedback` 标志提供反馈。此反馈将作为“偏好设置”保存，以便在未来的会话中重复使用，确保 AI 与您之前的指令保持一致。`aigne doc prefs` 命令提供了一种直接管理这些已保存偏好设置的方法。
+
+本指南详细介绍了如何列出、删除和切换已保存偏好设置的活动状态。
+
+## 查看已保存的偏好设置
+
+要查看所有已保存的偏好设置，请使用 `--list` 标志。此命令会显示每个偏好设置的状态、范围、唯一 ID 和内容。
+
+```bash
+aigne doc prefs --list
+```
+
+### 理解输出
+
+列表经过格式化，以提供关于每个偏好规则的清晰信息：
+
+*   **状态**：指示偏好设置是活动还是非活动状态。
+    *   `🟢`：活动。该规则将在文档生成期间应用。
+    *   `⚪`：非活动。该规则已保存但将被忽略。
+*   **范围**：偏好设置适用的上下文（例如，`global`、`document`）。
+*   **ID**：偏好设置的唯一标识符，用于删除或切换状态。
+*   **路径**：如果偏好设置仅适用于特定文件，其路径会在此处列出。
+*   **规则内容**：偏好规则本身的文本。
+
+**输出示例：**
+
+```
+# 用户偏好设置
+
+**格式说明：**
+- 🟢 = 活动偏好，⚪ = 非活动偏好
+- [scope] = 偏好范围 (global, structure, document, translation)
+- ID = 唯一偏好标识符
+- Paths = 特定文件路径（如适用）
+
+🟢 [document] 2af5c | Paths: /guides/generating-documentation.md
+   Focus on concrete, verifiable facts and information. Avoid using vague or empty words that don't provide measurable or specific d...
+
+⚪ [global] 8b1e2
+   Use a formal and academic tone throughout the documentation.
+
+```
+
+## 删除偏好设置
+
+当不再需要某个偏好设置时，您可以使用 `--remove` 标志将其永久删除。您可以通过指定其 ID 或通过交互式菜单来删除偏好设置。
+
+### 交互模式
+
+要从列表中选择偏好设置，请在不带任何 ID 的情况下运行该命令。这将打开一个交互式提示，您可以在其中勾选要删除的项目。
+
+```bash
+aigne doc prefs --remove
+```
+
+将出现一个清单，允许您选择一个或多个偏好设置。这是确保您删除正确项目的推荐方法。
+
+### 直接模式
+
+如果您已经知道要删除的偏好设置的唯一 ID，可以使用 `--id` 标志来指定它们。如果您确定要删除哪些项目，这种方式会更快。
+
+```bash
+# 删除单个偏好设置
+aigne doc prefs --remove --id 2af5c
+
+# 删除多个偏好设置
+aigne doc prefs --remove --id 2af5c --id 8b1e2
+```
+
+## 切换偏好设置
+
+除了永久删除偏好设置，您还可以临时启用或禁用它。当您想为特定任务暂停某条规则但又不想丢失它时，这非常有用。使用 `--toggle` 标志来更改偏好设置的活动状态。
+
+### 交互模式
+
+在不带 ID 的情况下运行该命令将启动一个交互式清单，类似于删除命令。
+
+```bash
+aigne doc prefs --toggle
+```
+
+您可以选择希望激活或停用的偏好设置。状态图标（`🟢`/`⚪`）将更新以反映新状态。
+
+### 直接模式
+
+要直接切换特定偏好设置，请使用 `--id` 标志。
+
+```bash
+# 切换单个偏好设置
+aigne doc prefs --toggle --id 2af5c
+
+# 切换多个偏好设置
+aigne doc prefs --toggle --id 2af5c --id 8b1e2
+```
+
+---
+
+通过管理您的偏好设置，您可以对文档生成过程进行精细控制，确保输出始终符合您项目的特定要求和风格。