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

package/docs/configuration-language-support.zh-TW.md

@@ -0,0 +1,94 @@
+# 語言支援
+
+AIGNE DocSmith 使用 AI 提供 12 種語言的自動化文件翻譯。這讓您可以使用 `aigne doc translate` 命令為全球使用者產生和維護文件。
+
+翻譯工作流程會透過 AI 引擎處理您的來源文件，以產生您所選目標語言的本地化版本。
+
+```d2
+direction: down
+
+Source-Doc: {
+  label: "來源文件\n（例如，英文）"
+  shape: rectangle
+}
+
+AI-Engine: {
+  label: "AIGNE DocSmith\nAI 翻譯引擎"
+  shape: rectangle
+}
+
+Translated-Docs: {
+  label: "翻譯後的文件"
+  shape: rectangle
+  grid-columns: 3
+
+  zh: "简体中文"
+  ja: "日本語"
+  es: "Español"
+  fr: "Français"
+  de: "Deutsch"
+  more: "..."
+}
+
+Source-Doc -> AI-Engine: "`aigne doc translate`"
+AI-Engine -> Translated-Docs: "產生"
+```
+
+## 支援的語言
+
+DocSmith 為以下語言提供 AI 驅動的翻譯。您可以在初始設定時定義專案的主要語言，並選擇任意數量的目標語言進行翻譯。
+
+| 語言 | 語言代碼 | 範例文字 |
+|---|---|---|
+| English | `en` | Hello |
+| 简体中文 | `zh` | 你好 |
+| 繁體中文 | `zh-TW` | 你好 |
+| 日本語 | `ja` | こんにちは |
+| 한국어 | `ko` | 안녕하세요 |
+| Español | `es` | Hola |
+| Français | `fr` | Bonjour |
+| Deutsch | `de` | Hallo |
+| Português | `pt` | Olá |
+| Русский | `ru` | Привет |
+| Italiano | `it` | Ciao |
+| العربية | `ar` | مرحبا |
+
+## 如何設定與使用翻譯
+
+翻譯語言是在您使用 `aigne doc init` 初始化專案時設定的。您可以隨時使用 `aigne doc translate` 命令新增語言或翻譯文件，該命令有兩種操作模式。
+
+### 用於引導式翻譯的互動模式
+
+若要獲得逐步引導的體驗，請在不帶任何參數的情況下執行此命令。這是對大多數使用者推薦的方法。
+
+```bash Interactive Translation icon=lucide:wand
+aigne doc translate
+```
+
+互動模式將會顯示一系列提示，讓您可以：
+
+1.  從清單中選擇要翻譯的現有文件。
+2.  從支援的清單中選擇一種或多種目標語言。
+3.  如果專案設定中尚未包含新的翻譯語言，則可以將其新增。
+
+### 用於自動化的命令列參數
+
+若要直接控制或在自動化腳本中使用，您可以直接將文件和語言指定為命令列參數。這對於開發人員和 CI/CD 管線來說是理想的選擇。
+
+```bash Command Example icon=lucide:terminal
+# 將 overview.md 和 examples.md 翻譯成中文和日文
+aigne doc translate --langs zh --langs ja --docs overview.md --docs examples.md
+```
+
+該命令的主要參數包括：
+
+| 參數 | 說明 |
+|---|---|
+| `--langs` | 指定目標語言代碼。此旗標可以多次使用以選擇多種語言。 |
+| `--docs` | 指定要翻譯的文件的路徑（例如，`overview.md`）。此旗標也可以多次使用。 |
+| `--feedback` | 提供具體說明以指導翻譯模型（例如，`"使用正式語氣"`）。 |
+| `--glossary` | 使用自訂詞彙表檔案（例如，`@path/to/glossary.md`）以確保專案特定術語的翻譯一致性。 |
+
+---
+
+本節介紹了可用的語言以及如何啟用它們。有關翻譯工作流程的完整指南，請參閱 [翻譯文件](./features-translate-documentation.md) 指南。

package/docs/configuration-language-support.zh.md

@@ -1,8 +1,8 @@
 # 语言支持
 
-AIGNE DocSmith 使用 AI 提供 12 种语言的自动化文档翻译。这使您可以使用 `aigne doc translate` 命令为全球用户生成和维护文档。
+AIGNE DocSmith 使用 AI 提供 12 种语言的自动化文档翻译。这使您可以使用 `aigne doc translate` 命令为全球受众生成和维护文档。
 
-翻译工作流通过 AI 引擎处理您的源文档，以生成您所选目标语言的本地化版本。
+翻译工作流通过 AI 引擎处理您的源文档，以生成所选目标语言的本地化版本。
 
 ```d2
 direction: down
@@ -36,11 +36,11 @@ AI-Engine -> Translated-Docs: "生成"
 
 ## 支持的语言
 
-DocSmith 为以下语言提供 AI 翻译。您可以在初始设置期间定义项目的主要语言，并选择任意数量的目标语言进行翻译。
+DocSmith 为以下语言提供 AI 驱动的翻译。您可以在初始设置期间定义项目的主要语言，并选择任意数量的目标语言进行翻译。
 
 | 语言 | 语言代码 | 示例文本 |
 |---|---|---|
-| English | `en` | Hello |
+| 英语 | `en` | Hello |
 | 简体中文 | `zh` | 你好 |
 | 繁體中文 | `zh-TW` | 你好 |
 | 日本語 | `ja` | こんにちは |
@@ -59,23 +59,23 @@ DocSmith 为以下语言提供 AI 翻译。您可以在初始设置期间定义
 
 ### 用于引导式翻译的交互模式
 
-要获得分步指导体验，请在不带任何参数的情况下运行该命令。这是推荐给大多数用户的方法。
+要获得分步指导的体验，请在不带任何参数的情况下运行该命令。这是大多数用户的推荐方法。
 
-```bash Interactive Translation icon=lucide:wand
+```bash 交互式翻译 icon=lucide:wand
 aigne doc translate
 ```
 
 然后，交互模式将显示一系列提示，允许您：
 
 1.  从列表中选择要翻译的现有文档。
-2.  从支持的列表中选择一个或多个目标语言。
+2.  从支持的语言列表中选择一个或多个目标语言。
 3.  如果项目中尚未包含新的翻译语言，则将其添加到项目配置中。
 
 ### 用于自动化的命令行参数
 
 为了直接控制或在自动化脚本中使用，您可以直接将文档和语言指定为命令行参数。这对于开发人员和 CI/CD 流水线非常理想。
 
-```bash Command Example icon=lucide:terminal
+```bash 命令示例 icon=lucide:terminal
 # 将 overview.md 和 examples.md 翻译成中文和日文
 aigne doc translate --langs zh --langs ja --docs overview.md --docs examples.md
 ```
@@ -84,11 +84,11 @@ aigne doc translate --langs zh --langs ja --docs overview.md --docs examples.md
 
 | 参数 | 描述 |
 |---|---|
-| `--langs` | 指定目标语言代码。此标志可多次使用以选择多种语言。 |
-| `--docs` | 指定要翻译的文档路径（例如 `overview.md`）。此标志也可以多次使用。 |
-| `--feedback` | 提供具体说明以指导翻译模型（例如 `"Use a formal tone"`）。 |
-| `--glossary` | 使用自定义术语表文件（例如 `@path/to/glossary.md`）以确保项目特定术语的翻译一致。 |
+| `--langs` | 指定目标语言代码。此标志可以多次使用以选择多种语言。 |
+| `--docs` | 指定要翻译的文档路径（例如，`overview.md`）。此参数也可以多次使用。 |
+| `--feedback` | 提供具体说明以指导翻译模型（例如，`"使用正式语气"`）。 |
+| `--glossary` | 使用自定义术语表文件（例如，`@path/to/glossary.md`）以确保项目特定术语的一致翻译。 |
 
 ---
 
-本节介绍了可用的语言以及如何启用它们。有关翻译工作流的完整指南，请参阅[翻译文档](./features-translate-documentation.md)指南。
+本节介绍了可用语言以及如何启用它们。有关翻译工作流的完整指南，请参阅[翻译文档](./features-translate-documentation.md)指南。

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

@@ -0,0 +1,54 @@
+# LLMセットアップ
+
+AIGNE DocSmithは、大規模言語モデル（LLM）を使用してドキュメントコンテンツを生成します。AIモデルプロバイダーは、統合されたAIGNE Hubを使用する方法と、独自のカスタムAPIキーを接続する方法の2通りで設定できます。
+
+## AIGNE Hub（推奨）
+
+最も手軽に始める方法はAIGNE Hubを使用することです。これは複数のLLMプロバイダーへのゲートウェイとして機能し、主に2つの利点があります：
+
+- **APIキー不要：** 独自のAPIキーやサービス契約を管理することなく、ドキュメントを生成できます。
+- **簡単なモデル切り替え：** `--model`フラグを使用することで、どのコマンドでもAIモデルを変更できます。
+
+AIGNE Hubを通じて特定のモデルを使用するには、コマンドに`--model`フラグを追加します。以下にいくつかの例を示します：
+
+```bash Using Different Models via 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
+```
+
+モデルを指定しない場合、DocSmithはプロジェクトの設定ファイルで定義されたデフォルトのモデルを使用します。
+
+## カスタムAPIキーの使用
+
+OpenAIやAnthropicのようなプロバイダーで自身のアカウントを使用したい場合は、個人のAPIキーでDocSmithを設定できます。この方法により、APIの使用状況と請求を直接管理できます。
+
+設定は対話型のウィザードを通じて行われます。ウィザードを起動するには、次のコマンドを実行してください：
+
+```bash
+aigne doc init
+```
+
+ウィザードがプロバイダーの選択と認証情報の入力を求めます。詳細なガイドについては、[対話型セットアップ](./configuration-interactive-setup.md)のドキュメントを参照してください。
+
+## デフォルトモデルの設定
+
+すべてのドキュメント生成タスクで一貫性を保つために、プロジェクトの`aigne.yaml`設定ファイルでデフォルトのLLMを設定できます。このモデルは、`--model`フラグを含まないコマンドで使用されます。
+
+```yaml aigne.yaml icon=mdi:file-code
+chat_model:
+  provider: google
+  name: gemini-2.5-pro
+  temperature: 0.8
+```
+
+この例では、DocSmithはGoogleの`gemini-2.5-pro`モデルをデフォルトで使用し、`temperature`設定は`0.8`に設定されています。
+
+---
+
+LLMプロバイダーの設定が完了したら、ドキュメントの言語設定を管理する準備が整いました。サポートされている言語の完全なリストを確認し、それらを有効にする方法については、[言語サポート](./configuration-language-support.md)ガイドに進んでください。

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

@@ -0,0 +1,54 @@
+# LLM 設定
+
+AIGNE DocSmith 使用大型語言模型 (LLM) 來產生文件內容。您可以透過兩種方式設定 AI 模型提供者：使用整合的 AIGNE Hub，或連接您自己的自訂 API 金鑰。
+
+## AIGNE Hub (推薦)
+
+最直接的開始方式是使用 AIGNE Hub。它作為多個 LLM 提供者的閘道，提供兩大好處：
+
+- **無需 API 金鑰：** 您無需管理自己的 API 金鑰或服務訂閱即可產生文件。
+- **輕鬆切換模型：** 您可以使用 `--model` 旗標為任何指令變更 AI 模型。
+
+若要透過 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
+```
+
+如果您未指定模型，DocSmith 將使用您專案設定中定義的預設模型。
+
+## 使用自訂 API 金鑰
+
+如果您偏好使用自己像 OpenAI 或 Anthropic 等提供者的帳戶，您可以使用個人 API 金鑰來設定 DocSmith。這種方法讓您可以直接控制 API 的使用和計費。
+
+設定是透過互動式精靈處理的。若要啟動它，請執行以下指令：
+
+```bash
+aigne doc init
+```
+
+精靈會提示您選擇您的提供者並輸入您的憑證。有關完整的指南，請參閱 [互動式設定](./configuration-interactive-setup.md) 文件。
+
+## 設定預設模型
+
+為了在所有文件產生任務中保持一致性，您可以在專案的 `aigne.yaml` 設定檔中設定預設的 LLM。此模型將用於任何不包含 `--model` 旗標的指令。
+
+```yaml aigne.yaml icon=mdi:file-code
+chat_model:
+  provider: google
+  name: gemini-2.5-pro
+  temperature: 0.8
+```
+
+在此範例中，DocSmith 預設設定為使用 Google 的 `gemini-2.5-pro` 模型，並將 `temperature` 設定為 `0.8`。
+
+---
+
+設定好您的 LLM 提供者後，您就可以開始管理文件的語言設定了。請前往 [語言支援](./configuration-language-support.md) 指南查看支援的語言完整清單，並了解如何啟用它們。

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

@@ -1,15 +1,15 @@
 # LLM 设置
 
-AIGNE DocSmith 使用大语言模型 (LLM) 生成文档内容。你可以通过两种方式配置 AI 模型提供商：使用集成的 AIGNE Hub，或连接你自己的自定义 API 密钥。
+AIGNE DocSmith 使用大语言模型 (LLMs) 生成文档内容。您可以通过两种方式配置 AI 模型提供商：使用集成的 AIGNE Hub，或连接您自己的自定义 API 密钥。
 
-## AIGNE Hub（推荐）
+## AIGNE Hub (推荐)
 
-最直接的入门方式是使用 AIGNE Hub。它作为一个通往多个 LLM 提供商的网关，提供两大主要优势：
+最直接的入门方式是使用 AIGNE Hub。它充当多个 LLM 提供商的网关，提供两大主要优势：
 
-- **无需 API 密钥：** 你无需管理自己的 API 密钥或服务订阅即可生成文档。
-- **轻松切换模型：** 你可以通过使用 `--model` 标志为任何命令更改 AI 模型。
+- **无需 API 密钥：** 您无需管理自己的 API 密钥或服务订阅即可生成文档。
+- **轻松切换模型：** 您可以使用 `--model` 标志为任何命令更改 AI 模型。
 
-要通过 AIGNE Hub 使用特定模型，请在命令中添加 `--model` 标志。以下是几个示例：
+要通过 AIGNE Hub 使用特定模型，请在命令中添加 `--model` 标志。以下是一些示例：
 
 ```bash 通过 AIGNE Hub 使用不同模型 icon=mdi:code-braces
 # 使用 Google 的 Gemini 2.5 Flash 模型
@@ -22,23 +22,23 @@ aigne doc generate --model claude:claude-3-5-sonnet
 aigne doc generate --model openai:gpt-4o
 ```
 
-如果你未指定模型，DocSmith 将使用项目配置中定义的默认模型。
+如果您未指定模型，DocSmith 将使用您项目配置中定义的默认模型。
 
 ## 使用自定义 API 密钥
 
-如果你更喜欢使用自己在 OpenAI 或 Anthropic 等提供商处的账户，可以用你的个人 API 密钥来配置 DocSmith。这种方法让你能够直接控制 API 的使用和计费。
+如果您更喜欢使用自己在 OpenAI 或 Anthropic 等提供商处的账户，可以用您的个人 API 密钥配置 DocSmith。这种方法让您可以直接控制 API 的使用和计费。
 
-配置通过一个交互式向导进行处理。要启动它，请运行以下命令：
+配置通过一个交互式向导进行。要启动它，请运行以下命令：
 
 ```bash
 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:
@@ -51,4 +51,4 @@ chat_model:
 
 ---
 
-配置好 LLM 提供商后，你就可以管理文档的语言设置了。请继续阅读 [语言支持](./configuration-language-support.md) 指南，查看支持的语言完整列表并了解如何启用它们。
+配置好您的 LLM 提供商后，您就可以管理文档的语言设置了。请继续阅读 [语言支持](./configuration-language-support.md) 指南，以查看支持语言的完整列表并了解如何启用它们。

package/docs/configuration-preferences.ja.md

@@ -0,0 +1,129 @@
+# プリファレンスの管理
+
+AIGNE DocSmithは、ユーザーのフィードバックから学習するように設計されています。生成されたコンテンツを調整または修正すると、DocSmithはそのフィードバックを「プリファレンス」と呼ばれる永続的なルールに変換できます。これらのルールにより、特定のスタイル、構造要件、コンテンツポリシーが将来のドキュメント作成タスクで一貫して適用されるようになります。すべてのプリファレンスは、プロジェクトのルートにある人間が読めるYAMLファイル `.aigne/doc-smith/preferences.yml` に保存されます。
+
+## プリファレンスのライフサイクル
+
+次の図は、フィードバックが再利用可能なルールとなり、将来のタスクに適用され、コマンドラインから管理されるまでの流れを示しています。
+
+```d2 プリファレンスのライフサイクル
+direction: down
+
+feedback: {
+  label: "1. ユーザーが「refine」または「translate」中に\nフィードバックを提供"
+  shape: rectangle
+}
+
+refiner: {
+  label: "2. Feedback Refiner Agentが\nフィードバックを分析"
+  shape: rectangle
+}
+
+decision: {
+  label: "再利用可能なポリシーか？"
+  shape: diamond
+}
+
+pref_file: {
+  label: "3. preferences.yml\nルールが保存される"
+  shape: cylinder
+}
+
+future_tasks: {
+  label: "4. 将来のタスク\n保存されたルールが適用される"
+  shape: rectangle
+}
+
+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: "管理"
+
+```
+
+### プリファレンスが作成される仕組み
+
+`refine` または `translate` の段階でフィードバックを提供すると、内部のAgentがその入力を分析します。フィードバックが一度限りの修正（例：タイポの修正）なのか、再利用可能なポリシー（例：「コードコメントは常に英語で書く」）なのかを判断します。それが永続的な指示であると判断された場合、新しいプリファレンスルールが作成されます。
+
+### ルールのプロパティ
+
+`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>
+
+## CLIによるプリファレンスの管理
+
+`aigne doc prefs` コマンドを使用して、保存されているすべてのプリファレンスを表示および管理できます。これにより、ルールの一覧表示、有効化、無効化、または恒久的な削除が可能です。
+
+### すべてのプリファレンスを一覧表示する
+
+有効なものと無効なものを含め、保存されているすべてのプリファレンスを表示するには、`--list` フラグを使用します。
+
+```bash すべてのプリファレンスを一覧表示する icon=lucide:terminal
+aigne doc prefs --list
+```
+
+このコマンドは、各ルールのステータス、スコープ、ID、およびパスの制限を示すフォーマットされたリストを表示します。
+
+```text 出力例 icon=lucide:clipboard-list
+# ユーザープリファレンス
+
+**フォーマットの説明：**
+- 🟢 = 有効なプリファレンス, ⚪ = 無効なプリファレンス
+- [scope] = プリファレンスのスコープ (global, structure, document, translation)
+- ID = 一意のプリファレンス識別子
+- Paths = 特定のファイルパス（該当する場合）
+
+🟢 [structure] pref_a1b2c3d4e5f6g7h8 | Paths: overview.md
+   概要ドキュメントの末尾に「次のステップ」セクションを追加する。
+ 
+⚪ [document] pref_i9j0k1l2m3n4o5p6
+   コードコメントは英語で記述する必要があります。
+```
+
+### プリファレンスの無効化と再有効化
+
+ルールを削除せずに一時的に無効にしたい場合は、`--toggle` フラグを使用してアクティブステータスを切り替えることができます。IDなしでコマンドを実行すると、対話モードが起動し、切り替えたいプリファレンスを1つ以上選択できます。
+
+```bash 対話形式でプリファレンスを切り替える icon=lucide:terminal
+aigne doc prefs --toggle
+```
+
+特定のルールを直接切り替えるには、`--id` フラグでそのIDを指定します。これは `deactivateRule` 関数に対応しており、ルールの `active` プロパティを `false` に設定します。
+
+```bash 特定のプリファレンスを切り替える icon=lucide:terminal
+aigne doc prefs --toggle --id pref_i9j0k1l2m3n4o5p6
+```
+
+### プリファレンスの削除
+
+1つ以上のプリファレンスを完全に削除するには、`--remove` フラグを使用します。この操作は `removeRule` 関数に対応し、元に戻すことはできません。
+
+対話的な選択プロンプトを表示するには、IDなしでコマンドを実行します。
+
+```bash 対話形式でプリファレンスを削除する icon=lucide:terminal
+aigne doc prefs --remove
+```
+
+特定のルールをIDで直接削除するには、`--id` フラグを使用します。
+
+```bash 特定のプリファレンスを削除する icon=lucide:terminal
+aigne doc prefs --remove --id pref_a1b2c3d4e5f6g7h8
+```
+
+## 次のステップ
+
+プリファレンスの管理は、DocSmithをプロジェクトの特定のニーズに合わせて調整するための重要な部分です。さらなるカスタマイズオプションについては、メインの[設定ガイド](./configuration.md)をご覧ください。

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

@@ -0,0 +1,129 @@
+# 管理偏好設定
+
+AIGNE DocSmith 旨在從您的回饋中學習。當您對生成的內容進行優化或更正時，DocSmith 可以將這些回饋轉換為持久性規則，稱為偏好設定。這些規則確保您特定的風格、結構要求和內容策略在未來的文件任務中得到一致的應用。所有偏好設定都儲存在專案根目錄下的 `.aigne/doc-smith/preferences.yml` 中，這是一個易於閱讀的 YAML 檔案。
+
+## 偏好設定的生命週期
+
+下圖說明了您的回饋如何成為一個可重複使用的規則，該規則可以應用於未來的任務，並可透過命令列進行管理。
+
+```d2 The Preference Lifecycle
+direction: down
+
+feedback: {
+  label: "1. 使用者在 'refine' 或 'translate' 過程中提供回饋"
+  shape: rectangle
+}
+
+refiner: {
+  label: "2. Feedback Refiner Agent\n分析回饋"
+  shape: rectangle
+}
+
+decision: {
+  label: "這是一個可重複使用的策略嗎？"
+  shape: diamond
+}
+
+pref_file: {
+  label: "3. preferences.yml\n規則已儲存"
+  shape: cylinder
+}
+
+future_tasks: {
+  label: "4. 未來的任務\n已儲存的規則被應用"
+  shape: rectangle
+}
+
+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: "管理"
+
+```
+
+### 如何建立偏好設定
+
+當您在 `refine` 或 `translate` 階段提供回饋時，一個內部 agent 會分析您的輸入。它會判斷該回饋是一次性的修復（例如，更正錯字）還是可重複使用的策略（例如，「總是使用英文撰寫程式碼註解」）。如果它代表一個持久性的指令，就會建立一個新的偏好設定規則。
+
+### 規則屬性
+
+儲存在 `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>
+
+## 使用 CLI 管理偏好設定
+
+您可以使用 `aigne doc prefs` 命令來查看和管理所有已儲存的偏好設定。這讓您可以列出、啟用、停用或永久移除規則。
+
+### 列出所有偏好設定
+
+若要查看所有已儲存的偏好設定，包括啟用和未啟用的，請使用 `--list` 旗標。
+
+```bash List all preferences icon=lucide:terminal
+aigne doc prefs --list
+```
+
+該命令會顯示一個格式化的列表，顯示每個規則的狀態、範圍、ID 和任何路徑限制。
+
+```text Example Output icon=lucide:clipboard-list
+# 使用者偏好設定
+
+**格式說明：**
+- 🟢 = 啟用中的偏好設定，⚪ = 未啟用的偏好設定
+- [scope] = 偏好設定範圍 (global, structure, document, translation)
+- ID = 唯一的偏好設定識別碼
+- Paths = 特定檔案路徑（如果適用）
+
+🟢 [structure] pref_a1b2c3d4e5f6g7h8 | Paths: overview.md
+   在概覽文件的末尾新增一個「後續步驟」部分。
+ 
+⚪ [document] pref_i9j0k1l2m3n4o5p6
+   程式碼註解必須以英文撰寫。
+```
+
+### 停用和重新啟用偏好設定
+
+如果您想暫時停用某個規則而不刪除它，可以使用 `--toggle` 旗標來切換其啟用狀態。在沒有 ID 的情況下執行該命令將啟動互動模式，讓您可以選擇一個或多個偏好設定進行切換。
+
+```bash Toggle preferences interactively icon=lucide:terminal
+aigne doc prefs --toggle
+```
+
+若要直接切換特定規則，請使用 `--id` 旗標提供其 ID。這對應於 `deactivateRule` 函式，該函式會將規則的 `active` 屬性設定為 `false`。
+
+```bash Toggle a specific preference icon=lucide:terminal
+aigne doc prefs --toggle --id pref_i9j0k1l2m3n4o5p6
+```
+
+### 移除偏好設定
+
+若要永久刪除一個或多個偏好設定，請使用 `--remove` 旗標。此操作對應於 `removeRule` 函式，且無法復原。
+
+若要進入互動式選擇提示，請在不帶 ID 的情況下執行此命令。
+
+```bash Remove preferences interactively icon=lucide:terminal
+aigne doc prefs --remove
+```
+
+若要透過 ID 直接移除特定規則，請使用 `--id` 旗標。
+
+```bash Remove a specific preference icon=lucide:terminal
+aigne doc prefs --remove --id pref_a1b2c3d4e5f6g7h8
+```
+
+## 後續步驟
+
+管理偏好設定是根據專案特定需求量身打造 DocSmith 的關鍵部分。若要了解更多自訂選項，請探索主要的 [設定指南](./configuration.md)。