@aigne/doc-smith 0.8.11-beta.6 → 0.8.11-beta.7

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

@@ -1,44 +1,46 @@
 # LLM 设置
 
-AIGNE DocSmith 使用大语言模型 (LLMs) 生成文档内容。您可以通过两种方式配置 AI 模型提供商：使用集成的 AIGNE Hub，或连接您自己的自定义 API 密钥。
+AIGNE DocSmith 使用大语言模型 (LLM) 生成文档内容。配置 AI 模型提供商主要有两种方法：利用集成的 AIGNE Hub，或连接您选择的提供商的自定义 API 密钥。
 
 ## AIGNE Hub (推荐)
 
-最直接的入门方式是使用 AIGNE Hub。它充当多个 LLM 提供商的网关，提供两大主要优势：
+配置 LLM 最直接的方法是通过 AIGNE Hub。它作为多个 LLM 提供商的网关，提供两大优势：
 
 - **无需 API 密钥：** 您无需管理自己的 API 密钥或服务订阅即可生成文档。
-- **轻松切换模型：** 您可以使用 `--model` 标志为任何命令更改 AI 模型。
+- **灵活切换模型：** 您可以使用 `--model` 标志为任何命令更改 AI 模型。
 
-要通过 AIGNE Hub 使用特定模型，请在命令中添加 `--model` 标志。以下是一些示例：
+要通过 AIGNE Hub 使用特定模型，请在命令后附加 `--model` 标志。以下示例演示了其用法：
 
 ```bash 通过 AIGNE Hub 使用不同模型 icon=mdi:code-braces
-# 使用 Google 的 Gemini 2.5 Flash 模型
-aigne doc generate --model google:gemini-2.5-flash
-
-# 使用 Anthropic 的 Claude 3.5 Sonnet 模型
-aigne doc generate --model claude:claude-3-5-sonnet
-
 # 使用 OpenAI 的 GPT-4o 模型
 aigne doc generate --model openai:gpt-4o
+
+# 使用 Anthropic 的 Claude 4.5 Sonnet 模型
+aigne doc generate --model anthropic:claude-sonnet-4-5
+
+# 使用 Google 的 Gemini 2.5 Pro 模型
+aigne doc generate --model google:gemini-2.5-pro
 ```
 
-如果您未指定模型，DocSmith 将使用您项目配置中定义的默认模型。
+如果未指定 `--model` 标志，DocSmith 将默认使用项目配置文件中定义的模型。
 
 ## 使用自定义 API 密钥
 
-如果您更喜欢使用自己在 OpenAI 或 Anthropic 等提供商处的账户，可以用您的个人 API 密钥配置 DocSmith。这种方法让您可以直接控制 API 的使用和计费。
+对于希望使用自己在 OpenAI、Anthropic 或 Google 等提供商处的账户的用户，可以使用个人 API 密钥配置 DocSmith。这种方法可以对 API 使用和计费进行直接控制。
 
-配置通过一个交互式向导进行。要启动它，请运行以下命令：
+配置通过交互式向导进行。要启动它，请运行以下命令：
 
-```bash
+```bash 启动交互式向导 icon=lucide:magic-wand
 aigne doc init
 ```
 
-该向导将提示您选择提供商并输入凭据。有关完整指南，请参阅 [交互式设置](./configuration-interactive-setup.md) 文档。
+向导将提示您选择提供商并输入必要的凭据。有关此过程的完整分步指南，请参阅[交互式设置](./configuration-interactive-setup.md)文档。
 
 ## 设置默认模型
 
-为了在所有文档生成任务中保持一致性，您可以在项目的 `aigne.yaml` 配置文件中设置一个默认 LLM。任何不包含 `--model` 标志的命令都将使用此模型。
+为了在所有文档生成任务中保持一致性，可以在项目的 `aigne.yaml` 配置文件中设置默认的 LLM。任何未明确包含 `--model` 标志的命令都将使用此模型。
+
+以下是配置示例：
 
 ```yaml aigne.yaml icon=mdi:file-code
 chat_model:
@@ -47,8 +49,8 @@ chat_model:
   temperature: 0.8
 ```
 
-在此示例中，DocSmith 被配置为默认使用 Google 的 `gemini-2.5-pro` 模型，并将 `temperature` 设置为 `0.8`。
+在此示例中，DocSmith 配置为使用 Google 的 `gemini-2.5-pro` 模型，并将 `temperature` 设置为 `0.8` 作为所有生成任务的默认值。
 
 ---
 
-配置好您的 LLM 提供商后，您就可以管理文档的语言设置了。请继续阅读 [语言支持](./configuration-language-support.md) 指南，以查看支持语言的完整列表并了解如何启用它们。
+配置好 LLM 提供商后，下一步是管理文档的语言设置。请前往[语言支持](./configuration-language-support.md)指南，查看支持的语言完整列表并了解如何启用它们。

package/docs/configuration-preferences.ja.md

@@ -1,78 +1,93 @@
 # プリファレンスの管理
 
-AIGNE DocSmithは、ユーザーのフィードバックから学習するように設計されています。生成されたコンテンツを調整または修正すると、DocSmithはそのフィードバックを「プリファレンス」と呼ばれる永続的なルールに変換できます。これらのルールにより、特定のスタイル、構造要件、コンテンツポリシーが将来のドキュメント作成タスクで一貫して適用されるようになります。すべてのプリファレンスは、プロジェクトのルートにある人間が読めるYAMLファイル `.aigne/doc-smith/preferences.yml` に保存されます。
+AIGNE DocSmith は、フィードバックから学習するように設計されています。生成されたコンテンツを改良または修正すると、DocSmith はそのフィードバックをプリファレンスと呼ばれる永続的なルールに変換できます。これらのルールにより、特定のスタイル、構造要件、コンテンツポリシーが将来のドキュメント作成タスクで一貫して適用されるようになります。すべてのプリファレンスは、プロジェクトルートの `.aigne/doc-smith/preferences.yml` にある人間が読めるYAMLファイルに保存されます。
 
 ## プリファレンスのライフサイクル
 
-次の図は、フィードバックが再利用可能なルールとなり、将来のタスクに適用され、コマンドラインから管理されるまでの流れを示しています。
+次の図は、フィードバックが再利用可能なルールになり、将来のタスクに適用され、コマンドラインから管理される方法を示しています。
 
 ```d2 プリファレンスのライフサイクル
 direction: down
 
-feedback: {
-  label: "1. ユーザーが「refine」または「translate」中に\nフィードバックを提供"
-  shape: rectangle
+developer: {
+  label: "開発者"
+  shape: person
 }
 
-refiner: {
-  label: "2. Feedback Refiner Agentが\nフィードバックを分析"
+docsmith_system: {
+  label: "AIGNE DocSmith システム"
   shape: rectangle
-}
 
-decision: {
-  label: "再利用可能なポリシーか？"
-  shape: diamond
+  cli: {
+    label: "CLI コマンド\n(refine / translate)"
+    shape: rectangle
+  }
+
+  agent: {
+    label: "内部分析 Agent"
+    shape: rectangle
+  }
+
+  decision: {
+    label: "フィードバックは\n再利用可能なポリシーか？"
+    shape: diamond
+  }
+
+  create_rule: {
+    label: "新しいプリファレンスルールを作成"
+    shape: rectangle
+  }
 }
 
-pref_file: {
-  label: "3. preferences.yml\nルールが保存される"
+preferences_file: {
+  label: ".aigne/doc-smith/preferences.yml"
   shape: cylinder
 }
 
-future_tasks: {
-  label: "4. 将来のタスク\n保存されたルールが適用される"
-  shape: rectangle
-}
-
-cli: {
-  label: "5. CLI管理\n('aigne doc prefs')"
-  shape: rectangle
+one_time_fix: {
+  label: "一度限りの修正として適用"
+  shape: oval
 }
 
-feedback -> refiner: "入力"
-refiner -> decision: "分析"
-decision -> pref_file: "はい"
-decision -> "破棄（一度限りの修正）": "いいえ"
-pref_file -> future_tasks: "適用される"
-cli <-> pref_file: "管理"
-
+developer -> docsmith_system.cli: "1. フィードバックを提供"
+docsmith_system.cli -> docsmith_system.agent: "2. フィードバックをキャプチャ"
+docsmith_system.agent -> docsmith_system.decision: "3. 分析"
+docsmith_system.decision -> docsmith_system.create_rule: "はい"
+docsmith_system.create_rule -> preferences_file: "4. ルールをファイルに保存"
+docsmith_system.decision -> one_time_fix: "いいえ"
 ```
 
-### プリファレンスが作成される仕組み
+### プリファレンスの作成方法
 
-`refine` または `translate` の段階でフィードバックを提供すると、内部のAgentがその入力を分析します。フィードバックが一度限りの修正（例：タイポの修正）なのか、再利用可能なポリシー（例：「コードコメントは常に英語で書く」）なのかを判断します。それが永続的な指示であると判断された場合、新しいプリファレンスルールが作成されます。
+`refine` または `translate` の段階でフィードバックを提供すると、内部 Agent が入力を分析します。フィードバックが一度限りの修正（例：タイポの修正）か、再利用可能なポリシー（例：「コードコメントは常に英語で書く」）かを判断します。それが永続的な指示を表す場合、新しいプリファレンスルールを作成し、プロジェクトの `preferences.yml` ファイルに保存します。
 
 ### ルールのプロパティ
 
-`preferences.yml` に保存される各ルールは、次の構造を持っています：
-
-<x-field data-name="id" data-type="string" data-desc="ルールの一意なランダムに生成された識別子（例：pref_a1b2c3d4e5f6g7h8）。"></x-field>
-<x-field data-name="active" data-type="boolean" data-desc="ルールが現在有効かどうかを示します。無効なルールは生成タスク中に無視されます。"></x-field>
-<x-field data-name="scope" data-type="string" data-desc="ルールをいつ適用するかを定義します。有効なスコープは 'global'、'structure'、'document'、または 'translation' です。"></x-field>
-<x-field data-name="rule" data-type="string" data-desc="将来のタスクでAIに渡される、具体的で洗練された指示。"></x-field>
-<x-field data-name="feedback" data-type="string" data-desc="参照用に保存される、ユーザーが提供した元の自然言語のフィードバック。"></x-field>
-<x-field data-name="createdAt" data-type="string" data-desc="ルールが作成された日時を示すISO 8601形式のタイムスタンプ。"></x-field>
-<x-field data-name="paths" data-type="string[]" data-required="false" data-desc="オプションのファイルパスのリスト。存在する場合、ルールはこれらの特定のソースファイルに対して生成されたコンテンツにのみ適用されます。"></x-field>
+`preferences.yml` に保存される各ルールは、次の構造を持ちます。
+
+<x-field-group>
+  <x-field data-name="id" data-type="string" data-desc="ルールの一意でランダムに生成された識別子（例：pref_a1b2c3d4e5f6g7h8）。"></x-field>
+  <x-field data-name="active" data-type="boolean" data-desc="ルールが現在有効かどうかを示します。無効なルールは生成タスク中に無視されます。"></x-field>
+  <x-field data-name="scope" data-type="string">
+    <x-field-desc markdown>ルールをいつ適用するかを定義します。有効なスコープは `global`、`structure`、`document`、または `translation` です。</x-field-desc>
+  </x-field>
+  <x-field data-name="rule" data-type="string" data-desc="将来のタスクでAIに渡される、具体的で洗練された指示。"></x-field>
+  <x-field data-name="feedback" data-type="string" data-desc="ユーザーから提供された元の自然言語のフィードバック。参照用に保存されます。"></x-field>
+  <x-field data-name="createdAt" data-type="string" data-desc="ルールが作成された日時を示すISO 8601タイムスタンプ。"></x-field>
+  <x-field data-name="paths" data-type="string[]" data-required="false">
+    <x-field-desc markdown>オプションのファイルパスのリスト。存在する場合、ルールはこれらの特定のソースファイルに対して生成されたコンテンツにのみ適用されます。</x-field-desc>
+  </x-field>
+</x-field-group>
 
 ## CLIによるプリファレンスの管理
 
-`aigne doc prefs` コマンドを使用して、保存されているすべてのプリファレンスを表示および管理できます。これにより、ルールの一覧表示、有効化、無効化、または恒久的な削除が可能です。
+`aigne doc prefs` コマンドを使用して、保存されているすべてのプリファレンスを表示および管理できます。これにより、ルールの一覧表示、有効化、無効化、または永久に削除することができます。
 
-### すべてのプリファレンスを一覧表示する
+### すべてのプリファレンスを一覧表示
 
-有効なものと無効なものを含め、保存されているすべてのプリファレンスを表示するには、`--list` フラグを使用します。
+保存されているすべてのプリファレンス（有効なものと無効なものの両方）の完全なリストを表示するには、`--list` フラグを使用します。
 
-```bash すべてのプリファレンスを一覧表示する icon=lucide:terminal
+```bash すべてのプリファレンスを一覧表示 icon=lucide:terminal
 aigne doc prefs --list
 ```
 
@@ -83,12 +98,12 @@ aigne doc prefs --list
 
 **フォーマットの説明：**
 - 🟢 = 有効なプリファレンス, ⚪ = 無効なプリファレンス
-- [scope] = プリファレンスのスコープ (global, structure, document, translation)
+- [scope] = プリファレンススコープ (global, structure, document, translation)
 - ID = 一意のプリファレンス識別子
 - Paths = 特定のファイルパス（該当する場合）
 
 🟢 [structure] pref_a1b2c3d4e5f6g7h8 | Paths: overview.md
-   概要ドキュメントの末尾に「次のステップ」セクションを追加する。
+   概要ドキュメントの最後に「次のステップ」セクションを追加します。
  
 ⚪ [document] pref_i9j0k1l2m3n4o5p6
    コードコメントは英語で記述する必要があります。
@@ -96,13 +111,13 @@ aigne doc prefs --list
 
 ### プリファレンスの無効化と再有効化
 
-ルールを削除せずに一時的に無効にしたい場合は、`--toggle` フラグを使用してアクティブステータスを切り替えることができます。IDなしでコマンドを実行すると、対話モードが起動し、切り替えたいプリファレンスを1つ以上選択できます。
+ルールを削除せずに一時的に無効にする必要がある場合は、`--toggle` フラグで有効ステータスを切り替えることができます。IDなしでコマンドを実行すると対話モードが起動し、切り替えるプリファレンスを1つ以上選択できます。
 
-```bash 対話形式でプリファレンスを切り替える icon=lucide:terminal
+```bash プリファレンスを対話的に切り替える icon=lucide:terminal
 aigne doc prefs --toggle
 ```
 
-特定のルールを直接切り替えるには、`--id` フラグでそのIDを指定します。これは `deactivateRule` 関数に対応しており、ルールの `active` プロパティを `false` に設定します。
+特定のルールを直接切り替えるには、`--id` フラグでそのIDを指定します。このアクションは、ルールの `active` プロパティを変更します。
 
 ```bash 特定のプリファレンスを切り替える icon=lucide:terminal
 aigne doc prefs --toggle --id pref_i9j0k1l2m3n4o5p6
@@ -110,15 +125,15 @@ aigne doc prefs --toggle --id pref_i9j0k1l2m3n4o5p6
 
 ### プリファレンスの削除
 
-1つ以上のプリファレンスを完全に削除するには、`--remove` フラグを使用します。この操作は `removeRule` 関数に対応し、元に戻すことはできません。
+1つ以上のプリファレンスを完全に削除するには、`--remove` フラグを使用します。この操作は元に戻せません。
 
 対話的な選択プロンプトを表示するには、IDなしでコマンドを実行します。
 
-```bash 対話形式でプリファレンスを削除する icon=lucide:terminal
+```bash プリファレンスを対話的に削除する icon=lucide:terminal
 aigne doc prefs --remove
 ```
 
-特定のルールをIDで直接削除するには、`--id` フラグを使用します。
+特定のルールを直接削除するには、`--id` フラグでそのIDを指定します。
 
 ```bash 特定のプリファレンスを削除する icon=lucide:terminal
 aigne doc prefs --remove --id pref_a1b2c3d4e5f6g7h8
@@ -126,4 +141,4 @@ aigne doc prefs --remove --id pref_a1b2c3d4e5f6g7h8
 
 ## 次のステップ
 
-プリファレンスの管理は、DocSmithをプロジェクトの特定のニーズに合わせて調整するための重要な部分です。さらなるカスタマイズオプションについては、メインの[設定ガイド](./configuration.md)をご覧ください。
+プリファレンスの管理は、DocSmithをプロジェクトの特定のニーズに合わせて調整する上で重要な部分です。その他のカスタマイズオプションについては、メインの[設定ガイド](./configuration.md)をご覧ください。

package/docs/configuration-preferences.md

@@ -9,68 +9,83 @@ The following diagram illustrates how your feedback becomes a reusable rule that
 ```d2 The Preference Lifecycle
 direction: down
 
-feedback: {
-  label: "1. User provides feedback\nduring 'refine' or 'translate'"
-  shape: rectangle
+developer: {
+  label: "Developer"
+  shape: person
 }
 
-refiner: {
-  label: "2. Feedback Refiner Agent\nAnalyzes feedback"
+docsmith_system: {
+  label: "AIGNE DocSmith System"
   shape: rectangle
-}
 
-decision: {
-  label: "Is it a reusable policy?"
-  shape: diamond
+  cli: {
+    label: "CLI Command\n(refine / translate)"
+    shape: rectangle
+  }
+
+  agent: {
+    label: "Internal Analysis Agent"
+    shape: rectangle
+  }
+
+  decision: {
+    label: "Is feedback a\nreusable policy?"
+    shape: diamond
+  }
+
+  create_rule: {
+    label: "Create New Preference Rule"
+    shape: rectangle
+  }
 }
 
-pref_file: {
-  label: "3. preferences.yml\nRule is saved"
+preferences_file: {
+  label: ".aigne/doc-smith/preferences.yml"
   shape: cylinder
 }
 
-future_tasks: {
-  label: "4. Future Tasks\nSaved rules are applied"
-  shape: rectangle
+one_time_fix: {
+  label: "Apply as a one-time fix"
+  shape: oval
 }
 
-cli: {
-  label: "5. CLI Management\n('aigne doc prefs')"
-  shape: rectangle
-}
-
-feedback -> refiner: "Input"
-refiner -> decision: "Analyzes"
-decision -> pref_file: "Yes"
-decision -> "Discard (One-time fix)": "No"
-pref_file -> future_tasks: "Applies to"
-cli <-> pref_file: "Manages"
-
+developer -> docsmith_system.cli: "1. Provides feedback"
+docsmith_system.cli -> docsmith_system.agent: "2. Captures feedback"
+docsmith_system.agent -> docsmith_system.decision: "3. Analyzes"
+docsmith_system.decision -> docsmith_system.create_rule: "Yes"
+docsmith_system.create_rule -> preferences_file: "4. Saves rule to file"
+docsmith_system.decision -> one_time_fix: "No"
 ```
 
 ### How Preferences are Created
 
-When you provide feedback during the `refine` or `translate` stages, an internal agent analyzes your input. It determines if the feedback is a one-time fix (e.g., correcting a typo) or a reusable policy (e.g., "always write code comments in English"). If it represents a lasting instruction, it creates a new preference rule.
+When you provide feedback during the `refine` or `translate` stages, an internal agent analyzes your input. It determines if the feedback is a one-time fix (e.g., correcting a typo) or a reusable policy (e.g., "always write code comments in English"). If it represents a lasting instruction, it creates a new preference rule and saves it to your project's `preferences.yml` file.
 
 ### Rule Properties
 
 Each rule saved in `preferences.yml` has the following structure:
 
-<x-field data-name="id" data-type="string" data-desc="A unique, randomly generated identifier for the rule (e.g., pref_a1b2c3d4e5f6g7h8)."></x-field>
-<x-field data-name="active" data-type="boolean" data-desc="Indicates if the rule is currently enabled. Inactive rules are ignored during generation tasks."></x-field>
-<x-field data-name="scope" data-type="string" data-desc="Defines when the rule should be applied. Valid scopes are 'global', 'structure', 'document', or 'translation'."></x-field>
-<x-field data-name="rule" data-type="string" data-desc="The specific, distilled instruction that will be passed to the AI in future tasks."></x-field>
-<x-field data-name="feedback" data-type="string" data-desc="The original, natural language feedback provided by the user, preserved for reference."></x-field>
-<x-field data-name="createdAt" data-type="string" data-desc="The ISO 8601 timestamp indicating when the rule was created."></x-field>
-<x-field data-name="paths" data-type="string[]" data-required="false" data-desc="An optional list of file paths. If present, the rule only applies to content generated for these specific source files."></x-field>
+<x-field-group>
+  <x-field data-name="id" data-type="string" data-desc="A unique, randomly generated identifier for the rule (e.g., pref_a1b2c3d4e5f6g7h8)."></x-field>
+  <x-field data-name="active" data-type="boolean" data-desc="Indicates if the rule is currently enabled. Inactive rules are ignored during generation tasks."></x-field>
+  <x-field data-name="scope" data-type="string">
+    <x-field-desc markdown>Defines when the rule should be applied. Valid scopes are `global`, `structure`, `document`, or `translation`.</x-field-desc>
+  </x-field>
+  <x-field data-name="rule" data-type="string" data-desc="The specific, distilled instruction that will be passed to the AI in future tasks."></x-field>
+  <x-field data-name="feedback" data-type="string" data-desc="The original, natural language feedback provided by the user, preserved for reference."></x-field>
+  <x-field data-name="createdAt" data-type="string" data-desc="The ISO 8601 timestamp indicating when the rule was created."></x-field>
+  <x-field data-name="paths" data-type="string[]" data-required="false">
+    <x-field-desc markdown>An optional list of file paths. If present, the rule only applies to content generated for these specific source files.</x-field-desc>
+  </x-field>
+</x-field-group>
 
 ## Managing Preferences with the CLI
 
-View and manage all your saved preferences using the `aigne doc prefs` command. You can list, activate, deactivate, or permanently remove rules.
+You can view and manage all your saved preferences using the `aigne doc prefs` command. This allows you to list, activate, deactivate, or permanently remove rules.
 
 ### Listing All Preferences
 
-To see all saved preferences, both active and inactive, use the `--list` flag.
+To see a complete list of all saved preferences, both active and inactive, use the `--list` flag.
 
 ```bash List all preferences icon=lucide:terminal
 aigne doc prefs --list
@@ -96,13 +111,13 @@ The command displays a formatted list showing the status, scope, ID, and any pat
 
 ### Deactivating and Reactivating Preferences
 
-If you want to temporarily disable a rule without deleting it, you can toggle its active status using the `--toggle` flag. Running the command without an ID will launch an interactive mode, allowing you to select one or more preferences to toggle.
+If you need to temporarily disable a rule without deleting it, you can toggle its active status with the `--toggle` flag. Running the command without an ID will launch an interactive mode, allowing you to select one or more preferences to toggle.
 
 ```bash Toggle preferences interactively icon=lucide:terminal
 aigne doc prefs --toggle
 ```
 
-To toggle a specific rule directly, provide its ID using the `--id` flag. This corresponds to the `deactivateRule` function, which sets the rule's `active` property to `false`.
+To toggle a specific rule directly, provide its ID using the `--id` flag. This action changes the rule's `active` property.
 
 ```bash Toggle a specific preference icon=lucide:terminal
 aigne doc prefs --toggle --id pref_i9j0k1l2m3n4o5p6
@@ -110,7 +125,7 @@ aigne doc prefs --toggle --id pref_i9j0k1l2m3n4o5p6
 
 ### Removing Preferences
 
-To permanently delete one or more preferences, use the `--remove` flag. This action, which corresponds to the `removeRule` function, cannot be undone.
+To permanently delete one or more preferences, use the `--remove` flag. This action cannot be undone.
 
 For an interactive selection prompt, run the command without an ID.
 
@@ -118,7 +133,7 @@ For an interactive selection prompt, run the command without an ID.
 aigne doc prefs --remove
 ```
 
-To remove a specific rule directly by its ID, use the `--id` flag.
+To remove a specific rule directly, provide its ID using the `--id` flag.
 
 ```bash Remove a specific preference icon=lucide:terminal
 aigne doc prefs --remove --id pref_a1b2c3d4e5f6g7h8
@@ -126,4 +141,4 @@ aigne doc prefs --remove --id pref_a1b2c3d4e5f6g7h8
 
 ## Next Steps
 
-Managing preferences is a key part of tailoring DocSmith to your project's specific needs. For more customization options, explore the main [Configuration Guide](./configuration.md).
+Managing preferences is a key part of tailoring DocSmith to your project's specific needs. For more customization options, explore the main [Configuration Guide](./configuration.md).

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

@@ -1,90 +1,105 @@
 # 管理偏好設定
 
-AIGNE DocSmith 旨在從您的回饋中學習。當您對生成的內容進行優化或更正時，DocSmith 可以將這些回饋轉換為持久性規則，稱為偏好設定。這些規則確保您特定的風格、結構要求和內容策略在未來的文件任務中得到一致的應用。所有偏好設定都儲存在專案根目錄下的 `.aigne/doc-smith/preferences.yml` 中，這是一個易於閱讀的 YAML 檔案。
+AIGNE DocSmith 的設計旨在從您的回饋中學習。當您優化或修正生成的內容時，DocSmith 可以將該回饋轉化為持久性規則，稱為偏好設定。這些規則確保您特定的風格、結構要求和內容策略在未來的文檔任務中得到一致應用。所有偏好設定都儲存在您專案根目錄下一個人類可讀的 YAML 檔案中，路徑為 `.aigne/doc-smith/preferences.yml`。
 
 ## 偏好設定的生命週期
 
-下圖說明了您的回饋如何成為一個可重複使用的規則，該規則可以應用於未來的任務，並可透過命令列進行管理。
+下圖說明了您的回饋如何成為一個可重複使用的規則，該規則可應用於未來的任務，並可透過命令列進行管理。
 
-```d2 The Preference Lifecycle
+```d2 偏好設定的生命週期
 direction: down
 
-feedback: {
-  label: "1. 使用者在 'refine' 或 'translate' 過程中提供回饋"
-  shape: rectangle
+developer: {
+  label: "開發者"
+  shape: person
 }
 
-refiner: {
-  label: "2. Feedback Refiner Agent\n分析回饋"
+docsmith_system: {
+  label: "AIGNE DocSmith 系統"
   shape: rectangle
-}
 
-decision: {
-  label: "這是一個可重複使用的策略嗎？"
-  shape: diamond
+  cli: {
+    label: "CLI 指令\n(refine / translate)"
+    shape: rectangle
+  }
+
+  agent: {
+    label: "內部分析 Agent"
+    shape: rectangle
+  }
+
+  decision: {
+    label: "回饋是否為\n可重複使用的策略？"
+    shape: diamond
+  }
+
+  create_rule: {
+    label: "建立新的偏好設定規則"
+    shape: rectangle
+  }
 }
 
-pref_file: {
-  label: "3. preferences.yml\n規則已儲存"
+preferences_file: {
+  label: ".aigne/doc-smith/preferences.yml"
   shape: cylinder
 }
 
-future_tasks: {
-  label: "4. 未來的任務\n已儲存的規則被應用"
-  shape: rectangle
+one_time_fix: {
+  label: "作為一次性修復應用"
+  shape: oval
 }
 
-cli: {
-  label: "5. CLI 管理\n('aigne doc prefs')"
-  shape: rectangle
-}
-
-feedback -> refiner: "輸入"
-refiner -> decision: "分析"
-decision -> pref_file: "是"
-decision -> "捨棄（一次性修復）": "否"
-pref_file -> future_tasks: "應用於"
-cli <-> pref_file: "管理"
-
+developer -> docsmith_system.cli: "1. 提供回饋"
+docsmith_system.cli -> docsmith_system.agent: "2. 捕捉回饋"
+docsmith_system.agent -> docsmith_system.decision: "3. 進行分析"
+docsmith_system.decision -> docsmith_system.create_rule: "是"
+docsmith_system.create_rule -> preferences_file: "4. 將規則儲存至檔案"
+docsmith_system.decision -> one_time_fix: "否"
 ```
 
 ### 如何建立偏好設定
 
-當您在 `refine` 或 `translate` 階段提供回饋時，一個內部 agent 會分析您的輸入。它會判斷該回饋是一次性的修復（例如，更正錯字）還是可重複使用的策略（例如，「總是使用英文撰寫程式碼註解」）。如果它代表一個持久性的指令，就會建立一個新的偏好設定規則。
+當您在 `refine` 或 `translate` 階段提供回饋時，一個內部 Agent 會分析您的輸入。它會判斷該回饋是一次性修復（例如，修正一個錯字）還是可重複使用的策略（例如，「程式碼註解必須以英文撰寫」）。如果它代表一個持久性的指令，它會建立一個新的偏好設定規則，並將其儲存到您專案的 `preferences.yml` 檔案中。
 
 ### 規則屬性
 
 儲存在 `preferences.yml` 中的每個規則都具有以下結構：
 
-<x-field data-name="id" data-type="string" data-desc="規則的唯一、隨機產生的識別碼（例如，pref_a1b2c3d4e5f6g7h8）。"></x-field>
-<x-field data-name="active" data-type="boolean" data-desc="表示該規則目前是否啟用。未啟用的規則在生成任務期間會被忽略。"></x-field>
-<x-field data-name="scope" data-type="string" data-desc="定義該規則應在何時應用。有效的範圍是 'global'、'structure'、'document' 或 'translation'。"></x-field>
-<x-field data-name="rule" data-type="string" data-desc="將在未來任務中傳遞給 AI 的具體、精煉的指令。"></x-field>
-<x-field data-name="feedback" data-type="string" data-desc="使用者提供的原始自然語言回饋，保留以供參考。"></x-field>
-<x-field data-name="createdAt" data-type="string" data-desc="表示規則建立時間的 ISO 8601 時間戳記。"></x-field>
-<x-field data-name="paths" data-type="string[]" data-required="false" data-desc="一個可選的檔案路徑列表。如果存在，該規則僅適用於為這些特定來源檔案生成的內容。"></x-field>
+<x-field-group>
+  <x-field data-name="id" data-type="string" data-desc="規則的唯一隨機生成識別碼（例如：pref_a1b2c3d4e5f6g7h8）。"></x-field>
+  <x-field data-name="active" data-type="boolean" data-desc="表示規則目前是否啟用。未啟用的規則在生成任務期間會被忽略。"></x-field>
+  <x-field data-name="scope" data-type="string">
+    <x-field-desc markdown>定義規則應在何時應用。有效的範圍為 `global`、`structure`、`document` 或 `translation`。</x-field-desc>
+  </x-field>
+  <x-field data-name="rule" data-type="string" data-desc="在未來任務中將傳遞給 AI 的具體、精煉的指令。"></x-field>
+  <x-field data-name="feedback" data-type="string" data-desc="使用者提供的原始自然語言回饋，保留以供參考。"></x-field>
+  <x-field data-name="createdAt" data-type="string" data-desc="表示規則建立時間的 ISO 8601 時間戳記。"></x-field>
+  <x-field data-name="paths" data-type="string[]" data-required="false">
+    <x-field-desc markdown>可選的檔案路徑列表。如果存在，此規則僅適用於為這些特定來源檔案生成的內容。</x-field-desc>
+  </x-field>
+</x-field-group>
 
 ## 使用 CLI 管理偏好設定
 
-您可以使用 `aigne doc prefs` 命令來查看和管理所有已儲存的偏好設定。這讓您可以列出、啟用、停用或永久移除規則。
+您可以使用 `aigne doc prefs` 指令來檢視和管理所有已儲存的偏好設定。這讓您可以列出、啟用、停用或永久移除規則。
 
 ### 列出所有偏好設定
 
-若要查看所有已儲存的偏好設定，包括啟用和未啟用的，請使用 `--list` 旗標。
+要查看所有已儲存偏好設定的完整列表（包括啟用和未啟用的），請使用 `--list` 標記。
 
-```bash List all preferences icon=lucide:terminal
+```bash 列出所有偏好設定 icon=lucide:terminal
 aigne doc prefs --list
 ```
 
-該命令會顯示一個格式化的列表，顯示每個規則的狀態、範圍、ID 和任何路徑限制。
+該指令會顯示一個格式化的列表，顯示每個規則的狀態、範圍、ID 以及任何路徑限制。
 
-```text Example Output icon=lucide:clipboard-list
+```text 輸出範例 icon=lucide:clipboard-list
 # 使用者偏好設定
 
 **格式說明：**
 - 🟢 = 啟用中的偏好設定，⚪ = 未啟用的偏好設定
 - [scope] = 偏好設定範圍 (global, structure, document, translation)
-- ID = 唯一的偏好設定識別碼
+- ID = 唯一偏好設定識別碼
 - Paths = 特定檔案路徑（如果適用）
 
 🟢 [structure] pref_a1b2c3d4e5f6g7h8 | Paths: overview.md
@@ -94,36 +109,36 @@ aigne doc prefs --list
    程式碼註解必須以英文撰寫。
 ```
 
-### 停用和重新啟用偏好設定
+### 停用與重新啟用偏好設定
 
-如果您想暫時停用某個規則而不刪除它，可以使用 `--toggle` 旗標來切換其啟用狀態。在沒有 ID 的情況下執行該命令將啟動互動模式，讓您可以選擇一個或多個偏好設定進行切換。
+如果您需要暫時停用一個規則而不刪除它，您可以使用 `--toggle` 標記來切換其啟用狀態。若執行指令時不帶 ID，將會啟動互動模式，讓您選擇一個或多個偏好設定進行切換。
 
-```bash Toggle preferences interactively icon=lucide:terminal
+```bash 以互動模式切換偏好設定 icon=lucide:terminal
 aigne doc prefs --toggle
 ```
 
-若要直接切換特定規則，請使用 `--id` 旗標提供其 ID。這對應於 `deactivateRule` 函式，該函式會將規則的 `active` 屬性設定為 `false`。
+要直接切換特定規則，請使用 `--id` 標記提供其 ID。此操作會更改規則的 `active` 屬性。
 
-```bash Toggle a specific preference icon=lucide:terminal
+```bash 切換特定偏好設定 icon=lucide:terminal
 aigne doc prefs --toggle --id pref_i9j0k1l2m3n4o5p6
 ```
 
 ### 移除偏好設定
 
-若要永久刪除一個或多個偏好設定，請使用 `--remove` 旗標。此操作對應於 `removeRule` 函式，且無法復原。
+要永久刪除一個或多個偏好設定，請使用 `--remove` 標記。此操作無法復原。
 
-若要進入互動式選擇提示，請在不帶 ID 的情況下執行此命令。
+若要進入互動式選擇提示，請在不帶 ID 的情況下執行該指令。
 
-```bash Remove preferences interactively icon=lucide:terminal
+```bash 以互動模式移除偏好設定 icon=lucide:terminal
 aigne doc prefs --remove
 ```
 
-若要透過 ID 直接移除特定規則，請使用 `--id` 旗標。
+要直接移除特定規則，請使用 `--id` 標記提供其 ID。
 
-```bash Remove a specific preference icon=lucide:terminal
+```bash 移除特定偏好設定 icon=lucide:terminal
 aigne doc prefs --remove --id pref_a1b2c3d4e5f6g7h8
 ```
 
 ## 後續步驟
 
-管理偏好設定是根據專案特定需求量身打造 DocSmith 的關鍵部分。若要了解更多自訂選項，請探索主要的 [設定指南](./configuration.md)。
+管理偏好設定是根據您專案的特定需求量身打造 DocSmith 的關鍵部分。如需更多自訂選項，請探索主要的[設定指南](./configuration.md)。