@aigne/doc-smith 0.8.2 → 0.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/.aigne/doc-smith/config.yaml +3 -3
  2. package/.aigne/doc-smith/preferences.yml +58 -12
  3. package/.aigne/doc-smith/upload-cache.yaml +600 -207
  4. package/CHANGELOG.md +17 -0
  5. package/README.md +77 -5
  6. package/docs/advanced-how-it-works.md +55 -60
  7. package/docs/advanced-how-it-works.zh.md +60 -65
  8. package/docs/advanced-quality-assurance.md +73 -38
  9. package/docs/advanced-quality-assurance.zh.md +73 -38
  10. package/docs/advanced.md +2 -14
  11. package/docs/advanced.zh.md +5 -17
  12. package/docs/changelog.md +41 -4
  13. package/docs/changelog.zh.md +77 -40
  14. package/docs/cli-reference.md +79 -13
  15. package/docs/cli-reference.zh.md +92 -26
  16. package/docs/configuration-interactive-setup.md +102 -49
  17. package/docs/configuration-interactive-setup.zh.md +102 -49
  18. package/docs/configuration-language-support.md +69 -39
  19. package/docs/configuration-language-support.zh.md +68 -38
  20. package/docs/configuration-llm-setup.md +25 -62
  21. package/docs/configuration-llm-setup.zh.md +25 -62
  22. package/docs/configuration-preferences.md +79 -67
  23. package/docs/configuration-preferences.zh.md +78 -67
  24. package/docs/configuration.md +122 -109
  25. package/docs/configuration.zh.md +130 -117
  26. package/docs/features-generate-documentation.md +44 -24
  27. package/docs/features-generate-documentation.zh.md +52 -32
  28. package/docs/features-publish-your-docs.md +41 -40
  29. package/docs/features-publish-your-docs.zh.md +50 -49
  30. package/docs/features-translate-documentation.md +73 -17
  31. package/docs/features-translate-documentation.zh.md +76 -20
  32. package/docs/features-update-and-refine.md +72 -21
  33. package/docs/features-update-and-refine.zh.md +80 -29
  34. package/docs/features.md +24 -28
  35. package/docs/features.zh.md +25 -29
  36. package/docs/getting-started.md +87 -38
  37. package/docs/getting-started.zh.md +88 -39
  38. package/docs/overview.md +17 -35
  39. package/docs/overview.zh.md +18 -36
  40. package/package.json +9 -8
  41. package/prompts/content-detail-generator.md +1 -0
  42. package/prompts/document/custom-code-block.md +101 -0
  43. package/prompts/document/d2-chart/rules.md +941 -1031
  44. package/prompts/document/detail-generator.md +7 -53
  45. package/tests/kroki-utils.test.mjs +88 -17
  46. package/utils/constants.mjs +15 -1
  47. package/utils/kroki-utils.mjs +22 -14
  48. package/utils/markdown-checker.mjs +1 -1
  49. package/utils/utils.mjs +3 -2
  50. package/prompts/document/d2-chart/diy-examples.md +0 -44
  51. package/prompts/document/d2-chart/shape-rules.md +0 -182
@@ -1,82 +1,135 @@
1
- ---
2
- labels: ["Reference"]
3
- ---
4
-
5
1
  # 交互式设置
6
2
 
7
- 使用交互式设置向导可以轻松地设置新的文档项目。只需运行 `aigne doc init` 命令,即可根据项目需求生成一个全面的 `config.yaml` 文件。该向导将引导你完成一系列问题,提供智能的默认值,并帮助你避免配置错误。
3
+ 为简化项目配置,AIGNE DocSmith 提供了一个交互式设置向导,可通过 `aigne doc init` 命令启动。该引导式流程会询问一系列关于文档目标的问题,并根据您的回答生成一个 `config.yaml` 文件。这是开始新文档项目的推荐方式,因为它有助于防止配置错误并提供具体建议。
4
+
5
+ ## 运行向导
6
+
7
+ 首先,在您项目的根目录中运行以下命令:
8
+
9
+ ```bash aigne doc init icon=lucide:sparkles
10
+ npx aigne doc init
11
+ ```
12
+
13
+ 然后,向导将引导您完成一个 8 步流程来配置您的文档。
8
14
 
9
- 这是启动新 DocSmith 项目的推荐方法,因为它能确保从一开始就考虑到所有必要的设置。
15
+ ## 引导式流程
10
16
 
11
- ## 设置过程
17
+ 向导涵盖以下关键领域:
12
18
 
13
- `init` 命令会启动一个包含 8 个步骤的引导式流程,以了解你的文档目标。在每一步中,它都会提出一个问题,并通常会根据你之前的回答建议一个默认值。
19
+ 1. **主要目标**:定义读者的主要预期成果(例如,快速入门、快速找到答案)。
20
+ 2. **目标受众**:明确文档的阅读对象(例如,非技术最终用户、开发者)。
21
+ 3. **读者知识水平**:评估受众的典型初始知识水平。
22
+ 4. **文档深度**:决定内容的详尽程度。
23
+ 5. **主要语言**:设置文档的主要语言。
24
+ 6. **翻译语言**:选择用于翻译的其他语言。
25
+ 7. **输出目录**:指定保存生成的文档文件的位置。
26
+ 8. **源代码路径**:定义要分析的文件和目录,支持 glob 模式。
27
+
28
+ ## 辅助配置
29
+
30
+ 该向导包含内置逻辑,可帮助您创建更有效、更一致的配置。
14
31
 
15
32
  ```d2
16
33
  direction: down
17
34
 
18
- start: "开始: `aigne doc init`" {
19
- shape: hexagon
35
+ User-Selections: {
36
+ label: "1. 用户提供输入\n(目的、受众等)"
37
+ shape: rectangle
20
38
  }
21
39
 
22
- step1: "[1/8] 定义主要目标"
23
- step2: "[2/8] 选择目标受众"
24
- step3: "[3/8] 设置读者知识水平"
25
- step4: "[4/8] 选择文档深度"
26
- step5: "[5/8] 选择主要语言"
27
- step6: "[6/8] 添加翻译语言"
28
- step7: "[7/8] 指定输出目录"
29
- step8: "[8/8] 配置源路径"
30
-
31
- finish: "config.yaml 已生成!" {
32
- shape: hexagon
40
+ Wizard-Engine: {
41
+ label: "2. 向导的逻辑引擎"
42
+ shape: rectangle
43
+ grid-columns: 2
44
+
45
+ Filtering: {
46
+ label: "选项过滤\n(防止无效组合)"
47
+ }
48
+
49
+ Conflict-Detection: {
50
+ label: "冲突检测\n(识别复杂需求)"
51
+ }
33
52
  }
34
53
 
35
- start -> step1 -> step2 -> step3 -> step4 -> step5 -> step6 -> step7 -> step8 -> finish
54
+ Guided-Experience: {
55
+ label: "3. 引导式体验"
56
+ shape: rectangle
57
+ content: "用户看到简化、相关的选项"
58
+ }
36
59
 
37
- subsystem: "在整个过程中,DocSmith 提供智能的默认值并检测潜在的配置冲突,以确保设置的一致性。" {
38
- shape: callout
60
+ Final-Config: {
61
+ label: "4. 最终配置"
62
+ content: "config.yaml 根据\n冲突解决策略生成"
39
63
  }
40
64
 
41
- subsystem -- step3
42
- subsystem -- step4
65
+ User-Selections -> Wizard-Engine
66
+ Wizard-Engine.Filtering -> Guided-Experience
67
+ Wizard-Engine.Conflict-Detection -> Final-Config
68
+ Guided-Experience -> User-Selections: "优化"
43
69
  ```
44
70
 
45
- 以下是每个步骤的详细说明:
71
+ ### 默认建议和选项过滤
46
72
 
47
- 1. **主要目标**:定义文档的主要目的。这个选择会极大地影响生成内容的风格和结构。
48
- 2. **目标受众**:明确文档的读者。这有助于针对正确的受众调整语气、语言和示例。
49
- 3. **读者知识水平**:指明读者的典型初始知识水平。向导会筛选此列表,仅显示与你先前选择兼容的选项。
50
- 4. **文档深度**:决定文档的全面程度。系统会根据你的目标和受众提供一个推荐的默认值。
51
- 5. **主要语言**:选择文档的主要语言。它会默认为你检测到的系统语言。
52
- 6. **翻译语言**:选择你希望将文档翻译成的其他语言。
53
- 7. **文档目录**:为生成的文档文件设置输出文件夹。
54
- 8. **源代码路径**:指定 DocSmith 应分析以生成文档的文件和文件夹。你可以使用直接路径(例如 `./src`)和 glob 模式(例如 `src/**/*.js`)。
73
+ 在您回答问题时,向导会提供默认值并筛选后续选项,以引导您进行逻辑配置。例如:
55
74
 
56
- ## 智能冲突预防
75
+ - **默认建议**:如果您选择“快速入门”作为主要目标,向导将推荐“完全是初学者”作为读者的知识水平。
76
+ - **实时过滤**:如果您的目标受众是“最终用户(非技术人员)”,向导将隐藏“试图做特定事情的专家”等技术高级知识水平,以防止不兼容的选择。
57
77
 
58
- 交互式设置的一个关键特性是它能够防止配置冲突。在你进行选择时,向导会智能地筛选后续步骤中的选项,以确保你的最终配置是合乎逻辑且有效的。
78
+ ### 冲突检测与解决
59
79
 
60
- 例如,如果你选择 **“快速入门”** 作为主要目标,向导将阻止你选择 **“试图完成特定任务的专家”** 作为读者知识水平。快速入门指南与需要高级、深入参考资料的专家的需求在根本上是不兼容的。这种机制引导你制定一个连贯的文档策略,而无需你记住每一种可能的设置组合。
80
+ 有时,您可能有多个似乎相互冲突的目标或受众,例如同时为非技术的**最终用户**和专业的**开发者**创建文档。向导会将这些识别为“可解决的冲突”。
61
81
 
62
- ## 处理复杂场景
82
+ 然后,它会制定一个策略,在文档结构中解决这些多样化的需求。对于最终用户与开发者的例子,解决方法是创建独立的用户路径:
63
83
 
64
- 有时,你可能希望面向多个不同的受众。例如,你可能需要为非技术的 **最终用户** 和专业的 **开发者** 提供文档。虽然这些受众的需求存在冲突,但设置向导允许你同时选择两者。
84
+ - **用户指南路径**:使用通俗易懂的语言,侧重于 UI 交互,并面向业务成果。
85
+ - **开发者指南路径**:代码优先,技术上精确,并包含 SDK 示例和配置片段。
65
86
 
66
- DocSmith 不会将此视为错误,而是将此信息用作文档结构的指导。它将通过规划独立的用户路径来解决冲突:
87
+ 这种方法可确保最终的文档结构能够有效地服务于多个受众,而不是产生令人困惑的内容混合。
67
88
 
68
- * **用户指南**:用通俗易懂的语言编写,侧重于用户界面和业务成果。
69
- * **开发者指南**:包含代码片段、API 参考和技术细节。
89
+ ## 生成的输出
70
90
 
71
- 这种方法通过智能的结构设计,而非简单的内容拼接,确保最终的文档能够有效地满足不同需求。
91
+ 完成后,向导会在您的项目中保存一个 `config.yaml` 文件。该文件带有完整的注释,解释了每个选项并列出了所有可用选择,方便日后手动审查和修改。
72
92
 
73
- 完成向导后,你的配置将被保存,你就可以生成第一套文档了。
93
+ 以下是生成文件的片段示例:
94
+
95
+ ```yaml config.yaml icon=logos:yaml
96
+ # 用于文档发布的项目信息
97
+ projectName: your-project-name
98
+ projectDesc: 您的项目描述。
99
+ projectLogo: ""
100
+
101
+ # =============================================================================
102
+ # 文档配置
103
+ # =============================================================================
104
+
105
+ # 目的:您希望读者达到的主要成果是什么?
106
+ # 可用选项(根据需要取消注释并修改):
107
+ # getStarted - 快速入门:帮助新用户在 30 分钟内从零开始上手
108
+ # completeTasks - 完成特定任务:引导用户完成常见的工作流程和用例
109
+ documentPurpose:
110
+ - completeTasks
111
+ - findAnswers
112
+
113
+ # 目标受众:谁会最常阅读这份文档?
114
+ # 可用选项(根据需要取消注释并修改):
115
+ # endUsers - 最终用户(非技术人员):使用产品但不编写代码的人
116
+ # developers - 开发者(集成您的产品/API):将此添加到其项目中的工程师
117
+ targetAudienceTypes:
118
+ - endUsers
119
+ - developers
120
+
121
+ # ... 其他设置
122
+ ```
123
+
124
+ ## 后续步骤
125
+
126
+ 配置文件就绪后,您就可以生成、翻译或发布您的文档了。
74
127
 
75
128
  <x-cards>
76
- <x-card data-title="配置指南" data-icon="lucide:file-cog" data-href="/configuration">
77
- 了解如何手动编辑 `config.yaml` 文件以进行高级定制。
78
- </x-card>
79
129
  <x-card data-title="生成文档" data-icon="lucide:play-circle" data-href="/features/generate-documentation">
80
- 运行命令,根据你的新配置生成第一套文档。
130
+ 了解如何使用单个命令从您的源代码自动创建一套完整的文档。
131
+ </x-card>
132
+ <x-card data-title="配置指南" data-icon="lucide:settings" data-href="/configuration">
133
+ 深入了解所有可用设置,并学习如何手动微调 config.yaml 文件。
81
134
  </x-card>
82
135
  </x-cards>
@@ -1,64 +1,94 @@
1
- ---
2
- labels: ["Reference"]
3
- ---
4
-
5
1
  # Language Support
6
2
 
7
- AIGNE DocSmith is designed for a global audience, offering automated translation capabilities for over a dozen languages. This allows you to generate and maintain documentation in multiple languages with minimal effort, ensuring your project is accessible to users worldwide. The translation feature is powered by the `aigne doc translate` command.
3
+ AIGNE DocSmith provides automated translation for 12 languages, allowing you to generate and maintain documentation for a global audience. The entire process is handled by the `aigne doc translate` command, which uses an AI engine to process your source documents and create localized versions.
4
+
5
+ The translation workflow processes your source documents through the AIGNE AI engine to generate localized versions in your selected target languages.
6
+
7
+ ```d2
8
+ direction: down
9
+
10
+ Source-Doc: {
11
+ label: "Source Document\n(e.g., English)"
12
+ shape: rectangle
13
+ }
14
+
15
+ AI-Engine: {
16
+ label: "AIGNE DocSmith\nAI Translation Engine"
17
+ shape: rectangle
18
+ }
19
+
20
+ Translated-Docs: {
21
+ label: "Translated Documents"
22
+ shape: rectangle
23
+ grid-columns: 3
24
+
25
+ zh: "简体中文"
26
+ ja: "日本語"
27
+ es: "Español"
28
+ fr: "Français"
29
+ de: "Deutsch"
30
+ more: "..."
31
+ }
32
+
33
+ Source-Doc -> AI-Engine: "`aigne doc translate`"
34
+ AI-Engine -> Translated-Docs: "Generates"
35
+ ```
8
36
 
9
37
  ## Supported Languages
10
38
 
11
- DocSmith provides high-quality, AI-powered translations for the following languages. You can select your primary documentation language and any number of target languages for translation during the project setup.
39
+ DocSmith offers AI-powered translations for the following languages. You can define your project's primary language during the initial setup and select any number of target languages for translation.
12
40
 
13
- | Language | Language Code |
14
- |---|---|
15
- | English (en) | `en` |
16
- | 简体中文 (zh) | `zh` |
17
- | 繁體中文 (zh-TW) | `zh-TW` |
18
- | 日本語 (ja) | `ja` |
19
- | 한국어 (ko) | `ko` |
20
- | Español (es) | `es` |
21
- | Français (fr) | `fr` |
22
- | Deutsch (de) | `de` |
23
- | Português (pt) | `pt` |
24
- | Русский (ru) | `ru` |
25
- | Italiano (it) | `it` |
26
- | العربية (ar) | `ar` |
27
-
28
- ## How to Enable and Use Translation
29
-
30
- Translation languages are typically configured when you first initialize your project using `aigne doc init`. However, you can easily add new languages or translate documents at any time using the `aigne doc translate` command.
41
+ | Language | Language Code | Sample Text |
42
+ |---|---|---|
43
+ | English | `en` | Hello |
44
+ | 简体中文 | `zh` | 你好 |
45
+ | 繁體中文 | `zh-TW` | 你好 |
46
+ | 日本語 | `ja` | こんにちは |
47
+ | 한국어 | `ko` | 안녕하세요 |
48
+ | Español | `es` | Hola |
49
+ | Français | `fr` | Bonjour |
50
+ | Deutsch | `de` | Hallo |
51
+ | Português | `pt` | Olá |
52
+ | Русский | `ru` | Привет |
53
+ | Italiano | `it` | Ciao |
54
+ | العربية | `ar` | مرحبا |
55
+
56
+ ## How to Configure and Use Translation
57
+
58
+ Translation languages are set when you initialize your project with `aigne doc init`. You can add new languages or translate documents at any time using the `aigne doc translate` command, which offers two modes of operation.
31
59
 
32
60
  ### Interactive Mode
33
61
 
34
- The simplest way to translate your documents is by running the command without any arguments. This will launch an interactive wizard.
62
+ For a guided experience, run the command without any arguments. This is the recommended approach for most users.
35
63
 
36
- ```bash
64
+ ```bash Interactive Translation icon=lucide:wand
37
65
  aigne doc translate
38
66
  ```
39
67
 
40
- The interactive mode will guide you through:
68
+ The interactive mode will then prompt you to:
41
69
 
42
- - Selecting which existing documents you want to translate.
43
- - Choosing target languages from the supported list.
44
- - Adding new translation languages to your project's configuration.
70
+ - Select which of your existing documents to translate.
71
+ - Choose one or more target languages from the supported list.
72
+ - Add new translation languages to your project's configuration if they are not already included.
45
73
 
46
- ### Command-Line Mode
74
+ ### Command-Line Arguments
47
75
 
48
- For automation or more direct control, you can specify documents and languages as command-line arguments. This is ideal for use in scripts or CI/CD environments.
76
+ For direct control or for use in automated scripts (like CI/CD pipelines), you can specify documents and languages directly as command-line arguments.
49
77
 
50
- ```bash
78
+ ```bash Command Example icon=lucide:terminal
51
79
  # Translate overview.md and examples.md into Chinese and Japanese
52
80
  aigne doc translate --langs zh --langs ja --docs overview.md --docs examples.md
53
81
  ```
54
82
 
55
- Key parameters include:
83
+ Key parameters for the command include:
56
84
 
57
- - `--langs`: Specify a target language code. You can use this flag multiple times for multiple languages.
58
- - `--docs`: Specify the path to a document you want to translate. This can also be used multiple times.
59
- - `--feedback`: Provide specific instructions to improve the quality of the translation.
60
- - `--glossary`: Use a custom glossary file to ensure consistent terminology.
85
+ | Parameter | Description |
86
+ |---|---|
87
+ | `--langs` | Specify a target language code. This flag can be used multiple times to select several languages. |
88
+ | `--docs` | Specify the path to a document to translate (e.g., `overview.md`). This can also be used multiple times. |
89
+ | `--feedback` | Provide specific instructions to guide the translation model (e.g., `"Use a formal tone"`). |
90
+ | `--glossary` | Use a custom glossary file (e.g., `@path/to/glossary.md`) to ensure consistent translation of project-specific terms. |
61
91
 
62
92
  ---
63
93
 
64
- Now that you know which languages are supported and how to enable them, you can start reaching a broader audience. For a more detailed walkthrough of the translation workflow and its advanced features, see the [Translate Documentation](./features-translate-documentation.md) guide.
94
+ This section covers the available languages and how to enable them. For a complete guide on the translation workflow, including advanced options and best practices, see the [Translate Documentation](./features-translate-documentation.md) guide.
@@ -1,64 +1,94 @@
1
- ---
2
- labels: ["Reference"]
3
- ---
4
-
5
1
  # 语言支持
6
2
 
7
- AIGNE DocSmith 面向全球用户设计,提供十几种语言的自动翻译功能。这使你能够以最少的工作量生成和维护多语言文档,确保你的项目能够被世界各地的用户访问。该翻译功能由 `aigne doc translate` 命令提供支持。
3
+ AIGNE DocSmith 提供 12 种语言的自动翻译功能,让你能够为全球用户生成和维护文档。整个过程由 `aigne doc translate` 命令处理,该命令使用 AI 引擎处理你的源文档并创建本地化版本。
4
+
5
+ 翻译工作流通过 AIGNE AI 引擎处理你的源文档,以在你选择的目标语言中生成本地化版本。
6
+
7
+ ```d2
8
+ direction: down
9
+
10
+ Source-Doc: {
11
+ label: "源文档\n(例如,英语)"
12
+ shape: rectangle
13
+ }
14
+
15
+ AI-Engine: {
16
+ label: "AIGNE DocSmith\nAI 翻译引擎"
17
+ shape: rectangle
18
+ }
19
+
20
+ Translated-Docs: {
21
+ label: "翻译后文档"
22
+ shape: rectangle
23
+ grid-columns: 3
24
+
25
+ zh: "简体中文"
26
+ ja: "日本語"
27
+ es: "Español"
28
+ fr: "Français"
29
+ de: "Deutsch"
30
+ more: "..."
31
+ }
32
+
33
+ Source-Doc -> AI-Engine: "`aigne doc translate`"
34
+ AI-Engine -> Translated-Docs: "生成"
35
+ ```
8
36
 
9
37
  ## 支持的语言
10
38
 
11
- DocSmith 为以下语言提供高质量的 AI 翻译。你可以在项目设置期间选择你的主要文档语言和任意数量的目标翻译语言。
39
+ DocSmith 为以下语言提供 AI 翻译功能。你可以在初始设置期间定义项目的主要语言,并选择任意数量的目标语言进行翻译。
12
40
 
13
- | 语言 | 语言代码 |
14
- |---|---|
15
- | 英语 (en) | `en` |
16
- | 简体中文 (zh) | `zh` |
17
- | 繁體中文 (zh-TW) | `zh-TW` |
18
- | 日语 (ja) | `ja` |
19
- | 韩语 (ko) | `ko` |
20
- | 西班牙语 (es) | `es` |
21
- | 法语 (fr) | `fr` |
22
- | 德语 (de) | `de` |
23
- | 葡萄牙语 (pt) | `pt` |
24
- | 俄语 (ru) | `ru` |
25
- | 意大利语 (it) | `it` |
26
- | 阿拉伯语 (ar) | `ar` |
27
-
28
- ## 如何启用和使用翻译
29
-
30
- 翻译语言通常在首次使用 `aigne doc init` 初始化项目时进行配置。但是,你可以随时使用 `aigne doc translate` 命令轻松添加新语言或翻译文档。
41
+ | 语言 | 语言代码 | 示例文本 |
42
+ |---|---|---|
43
+ | 英语 | `en` | Hello |
44
+ | 简体中文 | `zh` | 你好 |
45
+ | 繁體中文 | `zh-TW` | 你好 |
46
+ | 日本語 | `ja` | こんにちは |
47
+ | 한국어 | `ko` | 안녕하세요 |
48
+ | Español | `es` | Hola |
49
+ | Français | `fr` | Bonjour |
50
+ | Deutsch | `de` | Hallo |
51
+ | Português | `pt` | Olá |
52
+ | Русский | `ru` | Привет |
53
+ | Italiano | `it` | Ciao |
54
+ | العربية | `ar` | مرحبا |
55
+
56
+ ## 如何配置和使用翻译功能
57
+
58
+ 翻译语言在你使用 `aigne doc init` 初始化项目时设置。你可以随时使用 `aigne doc translate` 命令添加新语言或翻译文档,该命令提供两种操作模式。
31
59
 
32
60
  ### 交互模式
33
61
 
34
- 翻译文档最简单的方法是直接运行该命令,不带任何参数。这将启动一个交互式向导。
62
+ 如需引导式体验,请在不带任何参数的情况下运行该命令。这是为大多数用户推荐的方法。
35
63
 
36
- ```bash
64
+ ```bash Interactive Translation icon=lucide:wand
37
65
  aigne doc translate
38
66
  ```
39
67
 
40
- 交互模式将引导你完成以下操作:
68
+ 交互模式将提示你:
41
69
 
42
70
  - 选择要翻译的现有文档。
43
- - 从支持的语言列表中选择目标语言。
44
- - 将新的翻译语言添加到你的项目配置中。
71
+ - 从支持的语言列表中选择一个或多个目标语言。
72
+ - 如果项目中尚未包含新的翻译语言,则将其添加到项目配置中。
45
73
 
46
- ### 命令行模式
74
+ ### 命令行参数
47
75
 
48
- 为了实现自动化或更直接的控制,你可以将文档和语言指定为命令行参数。这非常适合在脚本或 CI/CD 环境中使用。
76
+ 为了直接控制或在自动化脚本(如 CI/CD 流水线)中使用,你可以直接将文档和语言指定为命令行参数。
49
77
 
50
- ```bash
78
+ ```bash Command Example icon=lucide:terminal
51
79
  # 将 overview.md 和 examples.md 翻译成中文和日文
52
80
  aigne doc translate --langs zh --langs ja --docs overview.md --docs examples.md
53
81
  ```
54
82
 
55
- 关键参数包括:
83
+ 该命令的关键参数包括:
56
84
 
57
- - `--langs`: 指定目标语言代码。你可以多次使用此标志以指定多种语言。
58
- - `--docs`: 指定要翻译的文档的路径。此标志也可以多次使用。
59
- - `--feedback`: 提供具体说明以提高翻译质量。
60
- - `--glossary`: 使用自定义术语表文件以确保术语的一致性。
85
+ | 参数 | 描述 |
86
+ |---|---|
87
+ | `--langs` | 指定目标语言代码。该标志可以多次使用以选择多种语言。 |
88
+ | `--docs` | 指定要翻译的文档路径(例如 `overview.md`)。该标志也可以多次使用。 |
89
+ | `--feedback` | 提供具体指令以指导翻译模型(例如,`"Use a formal tone"`)。 |
90
+ | `--glossary` | 使用自定义术语表文件(例如 `@path/to/glossary.md`)以确保项目特定术语的翻译一致性。 |
61
91
 
62
92
  ---
63
93
 
64
- 现在你已经了解了支持哪些语言以及如何启用它们,可以开始覆盖更广泛的受众了。有关翻译工作流程及其高级功能的更详细演练,请参阅 [翻译文档](./features-translate-documentation.md) 指南。
94
+ 本节介绍了可用语言以及如何启用它们。有关翻译工作流的完整指南,包括高级选项和最佳实践,请参阅[翻译文档](./features-translate-documentation.md)指南。
@@ -1,90 +1,53 @@
1
- ---
2
- labels: ["Reference"]
3
- ---
4
-
5
1
  # LLM Setup
6
2
 
7
- AIGNE DocSmith leverages Large Language Models (LLMs) to generate high-quality documentation. You can configure DocSmith to use different AI models through two primary methods: the recommended AIGNE Hub service or by providing your own custom API keys.
8
-
9
- This guide will walk you through both options.
10
-
11
- ## Using AIGNE Hub (Recommended)
3
+ AIGNE DocSmith uses Large Language Models (LLMs) to generate documentation content. The tool provides two primary methods for configuring your AI model provider: using the integrated AIGNE Hub for a streamlined experience, or connecting your own custom API keys for direct provider access.
12
4
 
13
- The most straightforward way to use LLMs with DocSmith is through AIGNE Hub. This approach offers significant advantages:
5
+ ## AIGNE Hub (Recommended)
14
6
 
15
- - **No API Key Required:** You don't need to sign up for separate AI services or manage your own API keys.
16
- - **Easy Model Switching:** You can switch between different state-of-the-art models from providers like Google, Anthropic, and OpenAI with a simple command-line flag.
7
+ The simplest way to get started is with AIGNE Hub. It acts as a gateway to multiple LLM providers, offering two key advantages:
17
8
 
18
- To specify a model, use the `--model` flag with the `generate` command. DocSmith will handle the API requests through the AIGNE Hub.
9
+ - **No API Key Required:** Generate documents without needing to manage your own API keys or service subscriptions.
10
+ - **Easy Model Switching:** Change the AI model for any command using a simple flag.
19
11
 
20
- ### Examples
12
+ To use a specific model through AIGNE Hub, add the `--model` flag to your command. Here are a few examples:
21
13
 
22
- Here are some examples of how to generate documentation using different models available via AIGNE Hub:
23
-
24
- **Using Google's Gemini 1.5 Flash:**
25
- ```bash
14
+ ```bash Use Google's Gemini 2.5 Flash model
26
15
  aigne doc generate --model google:gemini-2.5-flash
27
- ```
28
16
 
29
- **Using Anthropic's Claude 3.5 Sonnet:**
30
- ```bash
17
+ # Use Anthropic's Claude 3.5 Sonnet model
31
18
  aigne doc generate --model claude:claude-3-5-sonnet
32
- ```
33
19
 
34
- **Using OpenAI's GPT-4o:**
35
- ```bash
20
+ # Use OpenAI's GPT-4o model
36
21
  aigne doc generate --model openai:gpt-4o
37
22
  ```
38
23
 
39
- ## Configuring Custom API Keys
24
+ If you don't specify a model, DocSmith will use the default model defined in your project's configuration.
25
+
26
+ ## Using Custom API Keys
40
27
 
41
- If you prefer to use your own API keys for providers like OpenAI or Anthropic, you can configure them using the interactive setup wizard.
28
+ If you prefer to use your own accounts with providers like OpenAI or Anthropic, you can configure DocSmith with your personal API keys. This gives you direct control over API usage and billing.
42
29
 
43
- Run the `init` command to launch the wizard, which will guide you through setting up your LLM provider and credentials, among other project settings.
30
+ Configuration is handled through an interactive wizard. To launch it, run:
44
31
 
45
32
  ```bash
46
- # Launch the interactive configuration wizard
47
33
  aigne doc init
48
34
  ```
49
35
 
50
- This process ensures your keys are stored correctly for all subsequent documentation generation and update tasks.
51
-
52
- ## How It Works
53
-
54
- The following diagram illustrates how DocSmith processes requests with different LLM configurations.
55
-
56
- ```d2
57
- direction: down
36
+ The wizard will prompt you to select your provider and enter your credentials. For a complete guide, please see the [Interactive Setup](./configuration-interactive-setup.md) documentation.
58
37
 
59
- User: {
60
- shape: person
61
- label: "Developer"
62
- }
38
+ ## Setting a Default Model
63
39
 
64
- CLI: "`aigne doc generate`"
65
-
66
- DocSmith: {
67
- shape: package
68
- "Configuration Check": {
69
- "AIGNE Hub (Default)": "No API Key Needed"
70
- "Custom Provider": "User API Key Found"
71
- }
72
- }
73
-
74
- LLM_Providers: {
75
- label: "LLM Providers"
76
- shape: cloud
77
- "AIGNE Hub": "Manages access to multiple models"
78
- "Direct API (e.g., OpenAI)": "Uses custom key"
79
- }
80
-
81
- User -> CLI: "Runs command"
82
- CLI -> DocSmith: "Initiates process"
83
- DocSmith."Configuration Check"."AIGNE Hub (Default)" -> LLM_Providers."AIGNE Hub" : "Routes request via Hub"
84
- DocSmith."Configuration Check"."Custom Provider" -> LLM_Providers."Direct API (e.g., OpenAI)" : "Routes request with user's key"
40
+ To ensure consistency across all documentation generation tasks, you can set a default LLM in your project's `aigne.yaml` configuration file. This model will be used automatically unless you override it with the `--model` flag.
85
41
 
42
+ ```yaml aigne.yaml icon=mdi:file-document
43
+ chat_model:
44
+ provider: google
45
+ name: gemini-2.5-pro
46
+ temperature: 0.8
86
47
  ```
87
48
 
49
+ In this configuration, DocSmith defaults to using Google's `gemini-2.5-pro` model with a `temperature` of `0.8` for all generation tasks.
50
+
88
51
  ---
89
52
 
90
- With your LLM provider configured, you are ready to customize language settings for your documentation. Learn more in the [Language Support](./configuration-language-support.md) guide.
53
+ Now that your LLM provider is configured, you can explore how to manage translations for your documentation. Proceed to the [Language Support](./configuration-language-support.md) guide to see the full list of supported languages and learn how to enable them.