@aigne/doc-smith 0.8.12-beta.7 → 0.8.12-beta.9

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 (284) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/agents/clear/choose-contents.mjs +14 -1
  3. package/agents/clear/clear-media-description.mjs +129 -0
  4. package/agents/clear/index.yaml +3 -1
  5. package/agents/evaluate/code-snippet.mjs +28 -24
  6. package/agents/evaluate/document-structure.yaml +0 -4
  7. package/agents/evaluate/document.yaml +1 -5
  8. package/agents/generate/index.yaml +1 -0
  9. package/agents/init/index.mjs +10 -0
  10. package/agents/media/batch-generate-media-description.yaml +44 -0
  11. package/agents/media/generate-media-description.yaml +47 -0
  12. package/agents/media/load-media-description.mjs +238 -0
  13. package/agents/publish/index.yaml +4 -0
  14. package/agents/publish/publish-docs.mjs +77 -5
  15. package/agents/publish/translate-meta.mjs +103 -0
  16. package/agents/update/generate-document.yaml +30 -28
  17. package/agents/update/index.yaml +1 -0
  18. package/agents/update/update-document-detail.yaml +3 -1
  19. package/agents/utils/load-sources.mjs +103 -53
  20. package/agents/utils/update-branding.mjs +69 -0
  21. package/aigne.yaml +6 -0
  22. package/assets/report-template/report.html +34 -34
  23. package/package.json +17 -2
  24. package/prompts/common/document/role-and-personality.md +3 -1
  25. package/prompts/detail/d2-diagram/guide.md +7 -1
  26. package/prompts/detail/d2-diagram/user-prompt.md +3 -0
  27. package/prompts/detail/generate/system-prompt.md +6 -7
  28. package/prompts/detail/generate/user-prompt.md +12 -3
  29. package/prompts/detail/update/user-prompt.md +0 -2
  30. package/prompts/evaluate/document-structure.md +6 -7
  31. package/prompts/evaluate/document.md +16 -25
  32. package/prompts/media/media-description/system-prompt.md +35 -0
  33. package/prompts/media/media-description/user-prompt.md +8 -0
  34. package/prompts/structure/update/user-prompt.md +0 -4
  35. package/utils/constants/index.mjs +0 -107
  36. package/utils/file-utils.mjs +86 -0
  37. package/utils/markdown-checker.mjs +0 -20
  38. package/utils/request.mjs +7 -0
  39. package/utils/upload-files.mjs +231 -0
  40. package/utils/utils.mjs +11 -1
  41. package/.aigne/doc-smith/config.yaml +0 -77
  42. package/.aigne/doc-smith/history.yaml +0 -37
  43. package/.aigne/doc-smith/output/structure-plan.json +0 -162
  44. package/.aigne/doc-smith/preferences.yml +0 -97
  45. package/.aigne/doc-smith/upload-cache.yaml +0 -1893
  46. package/.github/PULL_REQUEST_TEMPLATE.md +0 -28
  47. package/.github/workflows/ci.yml +0 -54
  48. package/.github/workflows/create-release-pr.yaml +0 -21
  49. package/.github/workflows/publish-docs.yml +0 -65
  50. package/.github/workflows/release.yml +0 -49
  51. package/.github/workflows/reviewer.yml +0 -54
  52. package/.release-please-manifest.json +0 -3
  53. package/RELEASE.md +0 -9
  54. package/assets/screenshots/doc-complete-setup.png +0 -0
  55. package/assets/screenshots/doc-generate-docs.png +0 -0
  56. package/assets/screenshots/doc-generate.png +0 -0
  57. package/assets/screenshots/doc-generated-successfully.png +0 -0
  58. package/assets/screenshots/doc-publish.png +0 -0
  59. package/assets/screenshots/doc-regenerate.png +0 -0
  60. package/assets/screenshots/doc-translate-langs.png +0 -0
  61. package/assets/screenshots/doc-translate.png +0 -0
  62. package/assets/screenshots/doc-update.png +0 -0
  63. package/biome.json +0 -73
  64. package/codecov.yml +0 -15
  65. package/docs/_sidebar.md +0 -15
  66. package/docs/configuration-initial-setup.ja.md +0 -179
  67. package/docs/configuration-initial-setup.md +0 -179
  68. package/docs/configuration-initial-setup.zh-TW.md +0 -179
  69. package/docs/configuration-initial-setup.zh.md +0 -179
  70. package/docs/configuration-managing-preferences.ja.md +0 -100
  71. package/docs/configuration-managing-preferences.md +0 -100
  72. package/docs/configuration-managing-preferences.zh-TW.md +0 -100
  73. package/docs/configuration-managing-preferences.zh.md +0 -100
  74. package/docs/configuration.ja.md +0 -96
  75. package/docs/configuration.md +0 -96
  76. package/docs/configuration.zh-TW.md +0 -96
  77. package/docs/configuration.zh.md +0 -96
  78. package/docs/getting-started.ja.md +0 -88
  79. package/docs/getting-started.md +0 -88
  80. package/docs/getting-started.zh-TW.md +0 -88
  81. package/docs/getting-started.zh.md +0 -88
  82. package/docs/guides-cleaning-up.ja.md +0 -51
  83. package/docs/guides-cleaning-up.md +0 -51
  84. package/docs/guides-cleaning-up.zh-TW.md +0 -51
  85. package/docs/guides-cleaning-up.zh.md +0 -51
  86. package/docs/guides-evaluating-documents.ja.md +0 -66
  87. package/docs/guides-evaluating-documents.md +0 -66
  88. package/docs/guides-evaluating-documents.zh-TW.md +0 -66
  89. package/docs/guides-evaluating-documents.zh.md +0 -66
  90. package/docs/guides-generating-documentation.ja.md +0 -151
  91. package/docs/guides-generating-documentation.md +0 -151
  92. package/docs/guides-generating-documentation.zh-TW.md +0 -151
  93. package/docs/guides-generating-documentation.zh.md +0 -151
  94. package/docs/guides-interactive-chat.ja.md +0 -85
  95. package/docs/guides-interactive-chat.md +0 -85
  96. package/docs/guides-interactive-chat.zh-TW.md +0 -85
  97. package/docs/guides-interactive-chat.zh.md +0 -85
  98. package/docs/guides-managing-history.ja.md +0 -48
  99. package/docs/guides-managing-history.md +0 -48
  100. package/docs/guides-managing-history.zh-TW.md +0 -48
  101. package/docs/guides-managing-history.zh.md +0 -48
  102. package/docs/guides-publishing-your-docs.ja.md +0 -78
  103. package/docs/guides-publishing-your-docs.md +0 -78
  104. package/docs/guides-publishing-your-docs.zh-TW.md +0 -78
  105. package/docs/guides-publishing-your-docs.zh.md +0 -78
  106. package/docs/guides-translating-documentation.ja.md +0 -95
  107. package/docs/guides-translating-documentation.md +0 -95
  108. package/docs/guides-translating-documentation.zh-TW.md +0 -95
  109. package/docs/guides-translating-documentation.zh.md +0 -95
  110. package/docs/guides-updating-documentation.ja.md +0 -77
  111. package/docs/guides-updating-documentation.md +0 -77
  112. package/docs/guides-updating-documentation.zh-TW.md +0 -77
  113. package/docs/guides-updating-documentation.zh.md +0 -77
  114. package/docs/guides.ja.md +0 -32
  115. package/docs/guides.md +0 -32
  116. package/docs/guides.zh-TW.md +0 -32
  117. package/docs/guides.zh.md +0 -32
  118. package/docs/overview.ja.md +0 -61
  119. package/docs/overview.md +0 -61
  120. package/docs/overview.zh-TW.md +0 -61
  121. package/docs/overview.zh.md +0 -61
  122. package/docs/release-notes.ja.md +0 -255
  123. package/docs/release-notes.md +0 -255
  124. package/docs/release-notes.zh-TW.md +0 -255
  125. package/docs/release-notes.zh.md +0 -255
  126. package/media.md +0 -19
  127. package/prompts/common/afs/afs-tools-usage.md +0 -5
  128. package/prompts/common/afs/use-afs-instruction.md +0 -1
  129. package/release-please-config.json +0 -14
  130. package/tests/agents/chat/chat.test.mjs +0 -46
  131. package/tests/agents/clear/choose-contents.test.mjs +0 -284
  132. package/tests/agents/clear/clear-auth-tokens.test.mjs +0 -268
  133. package/tests/agents/clear/clear-document-config.test.mjs +0 -167
  134. package/tests/agents/clear/clear-document-structure.test.mjs +0 -380
  135. package/tests/agents/clear/clear-generated-docs.test.mjs +0 -222
  136. package/tests/agents/evaluate/code-snippet.test.mjs +0 -163
  137. package/tests/agents/evaluate/fixtures/api-services.md +0 -87
  138. package/tests/agents/evaluate/fixtures/js-sdk.md +0 -94
  139. package/tests/agents/evaluate/generate-report.test.mjs +0 -312
  140. package/tests/agents/generate/check-document-structure.test.mjs +0 -45
  141. package/tests/agents/generate/check-need-generate-structure.test.mjs +0 -279
  142. package/tests/agents/generate/document-structure-tools/add-document.test.mjs +0 -449
  143. package/tests/agents/generate/document-structure-tools/delete-document.test.mjs +0 -410
  144. package/tests/agents/generate/document-structure-tools/generate-sub-structure.test.mjs +0 -277
  145. package/tests/agents/generate/document-structure-tools/move-document.test.mjs +0 -476
  146. package/tests/agents/generate/document-structure-tools/update-document.test.mjs +0 -548
  147. package/tests/agents/generate/generate-structure.test.mjs +0 -45
  148. package/tests/agents/generate/user-review-document-structure.test.mjs +0 -319
  149. package/tests/agents/history/view.test.mjs +0 -97
  150. package/tests/agents/init/init.test.mjs +0 -1657
  151. package/tests/agents/prefs/prefs.test.mjs +0 -431
  152. package/tests/agents/publish/publish-docs.test.mjs +0 -787
  153. package/tests/agents/translate/choose-language.test.mjs +0 -311
  154. package/tests/agents/translate/translate-document.test.mjs +0 -51
  155. package/tests/agents/update/check-document.test.mjs +0 -463
  156. package/tests/agents/update/check-update-is-single.test.mjs +0 -300
  157. package/tests/agents/update/document-tools/update-document-content.test.mjs +0 -329
  158. package/tests/agents/update/generate-document.test.mjs +0 -51
  159. package/tests/agents/update/save-and-translate-document.test.mjs +0 -369
  160. package/tests/agents/update/user-review-document.test.mjs +0 -582
  161. package/tests/agents/utils/action-success.test.mjs +0 -54
  162. package/tests/agents/utils/check-detail-result.test.mjs +0 -743
  163. package/tests/agents/utils/check-feedback-refiner.test.mjs +0 -478
  164. package/tests/agents/utils/choose-docs.test.mjs +0 -406
  165. package/tests/agents/utils/exit.test.mjs +0 -70
  166. package/tests/agents/utils/feedback-refiner.test.mjs +0 -51
  167. package/tests/agents/utils/find-item-by-path.test.mjs +0 -517
  168. package/tests/agents/utils/find-user-preferences-by-path.test.mjs +0 -382
  169. package/tests/agents/utils/format-document-structure.test.mjs +0 -364
  170. package/tests/agents/utils/fs.test.mjs +0 -267
  171. package/tests/agents/utils/load-sources.test.mjs +0 -1470
  172. package/tests/agents/utils/save-docs.test.mjs +0 -109
  173. package/tests/agents/utils/save-output.test.mjs +0 -315
  174. package/tests/agents/utils/save-single-doc.test.mjs +0 -364
  175. package/tests/agents/utils/transform-detail-datasources.test.mjs +0 -320
  176. package/tests/utils/auth-utils.test.mjs +0 -596
  177. package/tests/utils/blocklet.test.mjs +0 -336
  178. package/tests/utils/conflict-detector.test.mjs +0 -355
  179. package/tests/utils/constants.test.mjs +0 -295
  180. package/tests/utils/d2-utils.test.mjs +0 -437
  181. package/tests/utils/deploy.test.mjs +0 -399
  182. package/tests/utils/docs-finder-utils.test.mjs +0 -650
  183. package/tests/utils/file-utils.test.mjs +0 -521
  184. package/tests/utils/history-utils.test.mjs +0 -206
  185. package/tests/utils/kroki-utils.test.mjs +0 -646
  186. package/tests/utils/linter/fixtures/css/keyword-error.css +0 -1
  187. package/tests/utils/linter/fixtures/css/missing-semicolon.css +0 -1
  188. package/tests/utils/linter/fixtures/css/syntax-error.css +0 -1
  189. package/tests/utils/linter/fixtures/css/undeclare-variable.css +0 -1
  190. package/tests/utils/linter/fixtures/css/unused-variable.css +0 -2
  191. package/tests/utils/linter/fixtures/css/valid-code.css +0 -1
  192. package/tests/utils/linter/fixtures/dockerfile/keyword-error.dockerfile +0 -1
  193. package/tests/utils/linter/fixtures/dockerfile/missing-semicolon.dockerfile +0 -2
  194. package/tests/utils/linter/fixtures/dockerfile/syntax-error.dockerfile +0 -2
  195. package/tests/utils/linter/fixtures/dockerfile/undeclare-variable.dockerfile +0 -1
  196. package/tests/utils/linter/fixtures/dockerfile/unused-variable.dockerfile +0 -1
  197. package/tests/utils/linter/fixtures/dockerfile/valid-code.dockerfile +0 -2
  198. package/tests/utils/linter/fixtures/go/keyword-error.go +0 -5
  199. package/tests/utils/linter/fixtures/go/missing-semicolon.go +0 -5
  200. package/tests/utils/linter/fixtures/go/syntax-error.go +0 -6
  201. package/tests/utils/linter/fixtures/go/undeclare-variable.go +0 -5
  202. package/tests/utils/linter/fixtures/go/unused-variable.go +0 -5
  203. package/tests/utils/linter/fixtures/go/valid-code.go +0 -7
  204. package/tests/utils/linter/fixtures/js/keyword-error.js +0 -3
  205. package/tests/utils/linter/fixtures/js/missing-semicolon.js +0 -6
  206. package/tests/utils/linter/fixtures/js/syntax-error.js +0 -4
  207. package/tests/utils/linter/fixtures/js/undeclare-variable.js +0 -3
  208. package/tests/utils/linter/fixtures/js/unused-variable.js +0 -7
  209. package/tests/utils/linter/fixtures/js/valid-code.js +0 -15
  210. package/tests/utils/linter/fixtures/json/keyword-error.json +0 -1
  211. package/tests/utils/linter/fixtures/json/missing-semicolon.json +0 -1
  212. package/tests/utils/linter/fixtures/json/syntax-error.json +0 -1
  213. package/tests/utils/linter/fixtures/json/undeclare-variable.json +0 -1
  214. package/tests/utils/linter/fixtures/json/unused-variable.json +0 -1
  215. package/tests/utils/linter/fixtures/json/valid-code.json +0 -1
  216. package/tests/utils/linter/fixtures/jsx/keyword-error.jsx +0 -5
  217. package/tests/utils/linter/fixtures/jsx/missing-semicolon.jsx +0 -5
  218. package/tests/utils/linter/fixtures/jsx/syntax-error.jsx +0 -5
  219. package/tests/utils/linter/fixtures/jsx/undeclare-variable.jsx +0 -5
  220. package/tests/utils/linter/fixtures/jsx/unused-variable.jsx +0 -4
  221. package/tests/utils/linter/fixtures/jsx/valid-code.jsx +0 -5
  222. package/tests/utils/linter/fixtures/python/keyword-error.py +0 -3
  223. package/tests/utils/linter/fixtures/python/missing-semicolon.py +0 -2
  224. package/tests/utils/linter/fixtures/python/syntax-error.py +0 -3
  225. package/tests/utils/linter/fixtures/python/undeclare-variable.py +0 -3
  226. package/tests/utils/linter/fixtures/python/unused-variable.py +0 -6
  227. package/tests/utils/linter/fixtures/python/valid-code.py +0 -12
  228. package/tests/utils/linter/fixtures/ruby/keyword-error.rb +0 -2
  229. package/tests/utils/linter/fixtures/ruby/missing-semicolon.rb +0 -1
  230. package/tests/utils/linter/fixtures/ruby/syntax-error.rb +0 -2
  231. package/tests/utils/linter/fixtures/ruby/undeclare-variable.rb +0 -1
  232. package/tests/utils/linter/fixtures/ruby/unused-variable.rb +0 -2
  233. package/tests/utils/linter/fixtures/ruby/valid-code.rb +0 -1
  234. package/tests/utils/linter/fixtures/sass/keyword-error.sass +0 -2
  235. package/tests/utils/linter/fixtures/sass/missing-semicolon.sass +0 -3
  236. package/tests/utils/linter/fixtures/sass/syntax-error.sass +0 -3
  237. package/tests/utils/linter/fixtures/sass/undeclare-variable.sass +0 -2
  238. package/tests/utils/linter/fixtures/sass/unused-variable.sass +0 -4
  239. package/tests/utils/linter/fixtures/sass/valid-code.sass +0 -2
  240. package/tests/utils/linter/fixtures/scss/keyword-error.scss +0 -1
  241. package/tests/utils/linter/fixtures/scss/missing-semicolon.scss +0 -1
  242. package/tests/utils/linter/fixtures/scss/syntax-error.scss +0 -1
  243. package/tests/utils/linter/fixtures/scss/undeclare-variable.scss +0 -1
  244. package/tests/utils/linter/fixtures/scss/unused-variable.scss +0 -2
  245. package/tests/utils/linter/fixtures/scss/valid-code.scss +0 -1
  246. package/tests/utils/linter/fixtures/shell/keyword-error.sh +0 -5
  247. package/tests/utils/linter/fixtures/shell/missing-semicolon.sh +0 -3
  248. package/tests/utils/linter/fixtures/shell/syntax-error.sh +0 -4
  249. package/tests/utils/linter/fixtures/shell/undeclare-variable.sh +0 -3
  250. package/tests/utils/linter/fixtures/shell/unused-variable.sh +0 -4
  251. package/tests/utils/linter/fixtures/shell/valid-code.sh +0 -3
  252. package/tests/utils/linter/fixtures/ts/keyword-error.ts +0 -1
  253. package/tests/utils/linter/fixtures/ts/missing-semicolon.ts +0 -1
  254. package/tests/utils/linter/fixtures/ts/syntax-error.ts +0 -1
  255. package/tests/utils/linter/fixtures/ts/undeclare-variable.ts +0 -1
  256. package/tests/utils/linter/fixtures/ts/unused-variable.ts +0 -3
  257. package/tests/utils/linter/fixtures/ts/valid-code.ts +0 -3
  258. package/tests/utils/linter/fixtures/tsx/keyword-error.tsx +0 -5
  259. package/tests/utils/linter/fixtures/tsx/missing-semicolon.tsx +0 -5
  260. package/tests/utils/linter/fixtures/tsx/syntax-error.tsx +0 -5
  261. package/tests/utils/linter/fixtures/tsx/undeclare-variable.tsx +0 -6
  262. package/tests/utils/linter/fixtures/tsx/unused-variable.tsx +0 -6
  263. package/tests/utils/linter/fixtures/tsx/valid-code.tsx +0 -5
  264. package/tests/utils/linter/fixtures/vue/keyword-error.vue +0 -6
  265. package/tests/utils/linter/fixtures/vue/missing-semicolon.vue +0 -6
  266. package/tests/utils/linter/fixtures/vue/syntax-error.vue +0 -6
  267. package/tests/utils/linter/fixtures/vue/undeclare-variable.vue +0 -6
  268. package/tests/utils/linter/fixtures/vue/unused-variable.vue +0 -7
  269. package/tests/utils/linter/fixtures/vue/valid-code.vue +0 -6
  270. package/tests/utils/linter/fixtures/yaml/keyword-error.yml +0 -1
  271. package/tests/utils/linter/fixtures/yaml/missing-semicolon.yml +0 -2
  272. package/tests/utils/linter/fixtures/yaml/syntax-error.yml +0 -1
  273. package/tests/utils/linter/fixtures/yaml/undeclare-variable.yml +0 -1
  274. package/tests/utils/linter/fixtures/yaml/unused-variable.yml +0 -2
  275. package/tests/utils/linter/fixtures/yaml/valid-code.yml +0 -3
  276. package/tests/utils/linter/index.test.mjs +0 -440
  277. package/tests/utils/linter/scan-results.mjs +0 -42
  278. package/tests/utils/load-config.test.mjs +0 -141
  279. package/tests/utils/markdown/index.test.mjs +0 -478
  280. package/tests/utils/mermaid-validator.test.mjs +0 -541
  281. package/tests/utils/mock-chat-model.mjs +0 -12
  282. package/tests/utils/preferences-utils.test.mjs +0 -465
  283. package/tests/utils/save-value-to-config.test.mjs +0 -483
  284. package/tests/utils/utils.test.mjs +0 -941
@@ -1,151 +0,0 @@
1
- # 產生文件
2
-
3
- 本指南提供了一套系統化程序,可從您的專案原始檔案建立一套完整的文件。此程序透過 `aigne doc generate` 指令啟動,該指令會分析您的程式碼庫、提出邏輯結構,然後為每份文件撰寫內容。
4
-
5
- 此指令是初次建立文件的主要工具。若要在文件建立後進行修改,請參閱 [更新文件](./guides-updating-documentation.md) 指南。
6
-
7
- ### 產生工作流程
8
-
9
- `generate` 指令會執行一系列自動化步驟來建置您的文件。此程序設計為互動式,讓您能在內容撰寫前審閱並批准建議的結構。
10
-
11
- ```d2
12
- direction: down
13
-
14
- start: {
15
- label: "開始"
16
- shape: oval
17
- }
18
-
19
- run_command: {
20
- label: "執行 'aigne doc generate'"
21
- shape: rectangle
22
- }
23
-
24
- check_config: {
25
- label: "設定檔是否存在?"
26
- shape: diamond
27
- }
28
-
29
- interactive_setup: {
30
- label: "引導進行互動式設定"
31
- shape: rectangle
32
- tooltip: "若找不到 .aigne/doc-smith/config.yaml,將觸發互動式設定。"
33
- }
34
-
35
- propose_structure: {
36
- label: "分析專案並提出文件結構"
37
- shape: rectangle
38
- }
39
-
40
- review_structure: {
41
- label: "使用者審閱建議的結構"
42
- shape: rectangle
43
- }
44
-
45
- user_approve: {
46
- label: "批准結構?"
47
- shape: diamond
48
- }
49
-
50
- provide_feedback: {
51
- label: "提供回饋以完善結構"
52
- shape: rectangle
53
- tooltip: "使用者可以要求變更,例如重新命名、新增或移除章節。"
54
- }
55
-
56
- generate_content: {
57
- label: "為所有文件生成內容"
58
- shape: rectangle
59
- }
60
-
61
- end: {
62
- label: "結束"
63
- shape: oval
64
- }
65
-
66
- start -> run_command
67
- run_command -> check_config
68
- check_config -> interactive_setup: {
69
- label: "否"
70
- }
71
- interactive_setup -> propose_structure
72
- check_config -> propose_structure: {
73
- label: "是"
74
- }
75
- propose_structure -> review_structure
76
- review_structure -> user_approve
77
- user_approve -> provide_feedback: {
78
- label: "否"
79
- }
80
- provide_feedback -> review_structure
81
- user_approve -> generate_content: {
82
- label: "是"
83
- }
84
- generate_content -> end
85
- ```
86
-
87
- ## 逐步流程
88
-
89
- 若要產生您的文件,請在終端機中導覽至您專案的根目錄,並依照下列步驟操作。
90
-
91
- ### 1. 執行 Generate 指令
92
-
93
- 執行 `generate` 指令以開始此程序。工具將首先分析您專案的檔案與結構。
94
-
95
- ```bash 基本產生指令
96
- aigne doc generate
97
- ```
98
-
99
- 為求簡潔,您也可以使用別名 `gen` 或 `g`。
100
-
101
- ### 2. 審閱文件結構
102
-
103
- 分析完成後,工具將顯示建議的文件結構,並提示您進行審閱:
104
-
105
- ```
106
- Would you like to optimize the documentation structure?
107
- ❯ No, looks good
108
- Yes, optimize the structure (e.g. rename 'Getting Started' to 'Quick Start', move 'API Reference' before 'Configuration')
109
- ```
110
-
111
- - **不,看起來不錯**:選擇此選項可批准建議的結構,並直接進入內容產生階段。
112
- - **是的,最佳化結構**:選擇此選項可修改計畫。工具接著會以互動式循環徵詢您的回饋。您可以用純文字提供指令,例如:
113
- - `新增一份名為「疑難排解」的文件`
114
- - `移除「舊版功能」文件`
115
- - `將「安裝」移至結構頂部`
116
-
117
- 在每次回饋後,AI 將會修訂結構,您可以再次審閱。若要結束循環並批准最終結構,直接按下 Enter 鍵,不輸入任何回饋即可。
118
-
119
- ### 3. 內容產生
120
-
121
- 文件結構一經批准,DocSmith 將開始為計畫中的每份文件產生詳細內容。此過程會自動執行,其持續時間取決於您專案的規模與複雜度。
122
-
123
- 完成後,產生的檔案將儲存至您設定中指定的輸出目錄(例如 `./docs`)。
124
-
125
- ## 指令參數
126
-
127
- `generate` 指令接受數個選用參數以控制其行為。
128
-
129
- | 參數 | 說明 | 範例 |
130
- |---|---|---|
131
- | `--forceRegenerate` | 從頭開始重建所有文件,忽略任何現有的結構或內容。當您想要完全重置時,此選項非常有用。 | `aigne doc generate --forceRegenerate` |
132
- | `--feedback` | 在互動式審閱開始前,提供初始的文字指令,以在結構產生階段指導 AI。 | `aigne doc generate --feedback "新增更多 API 範例"` |
133
- | `--glossary` | 指定一個詞彙表檔案(例如 glossary.md),以確保在整個文件中術語使用的一致性。 | `aigne doc generate --glossary @/path/to/glossary.md` |
134
-
135
- ### 範例:強制完整重建
136
-
137
- 如果您想捨棄所有先前產生的文件,並根據您程式碼的當前狀態建立一套新的文件,請使用 `--forceRegenerate` 旗標。
138
-
139
- ```bash 強制重新產生
140
- aigne doc generate --forceRegenerate
141
- ```
142
-
143
- ## 總結
144
-
145
- `generate` 指令統籌了建立您初始專案文件的整個過程。它結合了自動化程式碼分析與互動式審閱流程,以產出一套結構化且相關的文件。
146
-
147
- 文件產生後,您可能會想:
148
-
149
- - [更新文件](./guides-updating-documentation.md):對特定文件進行變更。
150
- - [翻譯文件](./guides-translating-documentation.md):將您的內容翻譯成其他語言。
151
- - [發布您的文件](./guides-publishing-your-docs.md):將您的文件發布上線。
@@ -1,151 +0,0 @@
1
- # 生成文档
2
-
3
- 本指南提供了从项目源文件创建一套完整文档的系统化流程。该流程通过 `aigne doc generate` 命令启动,该命令会分析你的代码库,提出一个逻辑结构,然后为每个文档编写内容。
4
-
5
- 该命令是初次创建文档的主要工具。如需在文档创建后进行修改,请参阅[更新文档](./guides-updating-documentation.md)指南。
6
-
7
- ### 生成工作流
8
-
9
- `generate` 命令会执行一系列自动化步骤来构建你的文档。该流程设计为交互式,允许你在内容写入前审查并批准建议的结构。
10
-
11
- ```d2
12
- direction: down
13
-
14
- start: {
15
- label: "开始"
16
- shape: oval
17
- }
18
-
19
- run_command: {
20
- label: "运行 'aigne doc generate'"
21
- shape: rectangle
22
- }
23
-
24
- check_config: {
25
- label: "配置文件是否存在?"
26
- shape: diamond
27
- }
28
-
29
- interactive_setup: {
30
- label: "引导进行交互式设置"
31
- shape: rectangle
32
- tooltip: "如果未找到 .aigne/doc-smith/config.yaml,则会触发交互式设置。"
33
- }
34
-
35
- propose_structure: {
36
- label: "分析项目并提出文档结构"
37
- shape: rectangle
38
- }
39
-
40
- review_structure: {
41
- label: "用户审查建议的结构"
42
- shape: rectangle
43
- }
44
-
45
- user_approve: {
46
- label: "批准结构?"
47
- shape: diamond
48
- }
49
-
50
- provide_feedback: {
51
- label: "提供反馈以优化结构"
52
- shape: rectangle
53
- tooltip: "用户可以请求更改,例如重命名、添加或删除章节。"
54
- }
55
-
56
- generate_content: {
57
- label: "为所有文档生成内容"
58
- shape: rectangle
59
- }
60
-
61
- end: {
62
- label: "结束"
63
- shape: oval
64
- }
65
-
66
- start -> run_command
67
- run_command -> check_config
68
- check_config -> interactive_setup: {
69
- label: "否"
70
- }
71
- interactive_setup -> propose_structure
72
- check_config -> propose_structure: {
73
- label: "是"
74
- }
75
- propose_structure -> review_structure
76
- review_structure -> user_approve
77
- user_approve -> provide_feedback: {
78
- label: "否"
79
- }
80
- provide_feedback -> review_structure
81
- user_approve -> generate_content: {
82
- label: "是"
83
- }
84
- generate_content -> end
85
- ```
86
-
87
- ## 分步流程
88
-
89
- 要生成文档,请在终端中导航到项目的根目录,并按照以下步骤操作。
90
-
91
- ### 1. 运行生成命令
92
-
93
- 执行 `generate` 命令以开始此过程。该工具将首先分析你项目的文件和结构。
94
-
95
- ```bash 基本生成命令
96
- aigne doc generate
97
- ```
98
-
99
- 为简洁起见,你也可以使用别名 `gen` 或 `g`。
100
-
101
- ### 2. 审查文档结构
102
-
103
- 分析完成后,该工具将显示建议的文档结构并提示你进行审查:
104
-
105
- ```
106
- 你希望优化文档结构吗?
107
- ❯ 不,看起来不错
108
- 是的,优化结构(例如,将“入门指南”重命名为“快速入门”,将“API 参考”移至“配置”之前)
109
- ```
110
-
111
- - **不,看起来不错**:选择此选项以批准建议的结构,并直接进入内容生成阶段。
112
- - **是的,优化结构**:选择此选项以修改计划。该工具将在一个交互式循环中征求你的反馈。你可以用纯文本提供指令,例如:
113
- - `添加一个新文档“故障排除”`
114
- - `删除“旧版功能”文档`
115
- - `将“安装”移动到结构顶部`
116
-
117
- 在每次反馈后,AI 将修订结构,你可以再次审查。不输入任何反馈直接按 Enter 键即可退出循环并批准最终结构。
118
-
119
- ### 3. 内容生成
120
-
121
- 文档结构一经批准,DocSmith 将开始为计划中的每个文档生成详细内容。此过程自动运行,其持续时间取决于项目的规模和复杂性。
122
-
123
- 完成后,生成的文件将保存到你在配置中指定的输出目录(例如 `./docs`)。
124
-
125
- ## 命令参数
126
-
127
- `generate` 命令接受几个可选参数以控制其行为。
128
-
129
- | 参数 | 描述 | 示例 |
130
- |---|---|---|
131
- | `--forceRegenerate` | 从头开始重建所有文档,忽略任何现有结构或内容。当你想要完全重置时,此选项非常有用。 | `aigne doc generate --forceRegenerate` |
132
- | `--feedback` | 在交互式审查开始前,提供基于文本的初始指令,以在结构生成阶段指导 AI。 | `aigne doc generate --feedback "添加更多 API 示例"` |
133
- | `--glossary` | 指定一个术语表文件(例如 `glossary.md`),以确保在整个文档中术语使用的一致性。 | `aigne doc generate --glossary @/path/to/glossary.md` |
134
-
135
- ### 示例:强制完全重建
136
-
137
- 如果你想丢弃所有先前生成的文档,并根据代码的当前状态创建一套新文档,请使用 `--forceRegenerate` 标志。
138
-
139
- ```bash 强制重新生成
140
- aigne doc generate --forceRegenerate
141
- ```
142
-
143
- ## 总结
144
-
145
- `generate` 命令协调了创建初始项目文档的整个过程。它将自动代码分析与交互式审查过程相结合,以生成一套结构化且相关的文档。
146
-
147
- 文档生成后,你可能希望:
148
-
149
- - [更新文档](./guides-updating-documentation.md):对特定文档进行更改。
150
- - [翻译文档](./guides-translating-documentation.md):将你的内容翻译成其他语言。
151
- - [发布你的文档](./guides-publishing-your-docs.md):将你的文档在线发布。
@@ -1,85 +0,0 @@
1
- # 対話型チャット
2
-
3
- 対話型チャットアシスタントは、ドキュメントの生成、修正、管理を行うための会話形式のインターフェースを提供します。個々のコマンドを実行する代わりに、何をしたいかを説明するだけで、アシスタントがプロセスを案内し、適切なツールを呼び出してタスクを完了します。
4
-
5
- このアプローチは、裏側で実行されるコマンドを自動的に処理することで、ドキュメント作成のワークフローを簡素化します。このツールを使用するほとんどのインタラクションにおいて、この方法が推奨されます。
6
-
7
- ## チャットアシスタントの開始
8
-
9
- 対話型セッションを開始するには、ターミナルから `chat` コマンドを実行します。
10
-
11
- ```bash
12
- aigndoc chat
13
- ```
14
-
15
- これによりアシスタントが起動し、リクエストの入力を開始できます。
16
-
17
- ## 主な機能
18
-
19
- チャットアシスタントは、ドキュメント作成のライフサイクル全体を処理するように設計されています。その主な機能は以下の通りです。
20
-
21
- <x-cards data-columns="2">
22
- <x-card data-title="ドキュメントの生成" data-icon="lucide:file-plus-2">
23
- プロジェクトのソースファイルを分析して、完全なドキュメント構造と初期コンテンツを作成します。
24
- </x-card>
25
- <x-card data-title="改良と更新" data-icon="lucide:edit">
26
- フィードバックやソースコードの変更に基づいて、特定のセクションまたはドキュメント全体を再生成します。
27
- </x-card>
28
- <x-card data-title="コンテンツの翻訳" data-icon="lucide:languages">
29
- 既存のドキュメントを多言語に翻訳し、より多くの読者に届けます。
30
- </x-card>
31
- <x-card data-title="公開と管理" data-icon="lucide:upload-cloud">
32
- ドキュメントの公開とチームベースのワークフローの管理を支援します。
33
- </x-card>
34
- </x-cards>
35
-
36
- ## 利用可能なコマンド
37
-
38
- チャット内では、目標を平易な言葉で述べたり(例:「入門ガイドを更新して」)、特定のコマンドを呼び出したりすることができます。アシスタントは、その専門的なスキルに対応する以下のコアコマンドを理解します。
39
-
40
- | Command | Description |
41
- | :--- | :--- |
42
- | `generate` | ソースファイルから新しいドキュメント構造を作成するプロセスを開始します。 |
43
- | `update` | コードの変更やユーザーのフィードバックに基づいて、既存のドキュメントを修正します。 |
44
- | `translate` | ドキュメントを1つ以上の対応言語に翻訳します。 |
45
- | `publish` | ドキュメントを公開し、オンラインでアクセスできるようにします。 |
46
- | `init` | プロジェクトの初期設定ファイルの作成をガイドします。 |
47
- | `clear` | 生成されたファイル、設定、キャッシュデータを削除します。 |
48
- | `prefs` | ドキュメント生成のために保存された設定を管理します。 |
49
- | `evaluate` | 生成されたドキュメントの品質と完全性を評価します。 |
50
- | `history` | ドキュメントに加えられた更新の履歴を表示します。 |
51
- | `exit` | 対話型チャットセッションを終了します。 |
52
-
53
- ## 対話例
54
-
55
- 以下は、対話型アシスタントがどのように機能するかを示す会話のサンプルです。
56
-
57
- ```text
58
- あなた:
59
- > こんにちは、新しいプロジェクトのドキュメントを作成したいです。
60
-
61
- AI アシスタント:
62
- もちろんです。まず、プロジェクトの構造を分析する必要があります。ソースコードディレクトリへのパスを教えていただけますか?
63
-
64
- あなた:
65
- > ./src
66
-
67
- AI アシスタント:
68
- ありがとうございます。./src 内のファイルを分析し、ドキュメント構造を提案します。これには少し時間がかかる場合があります...
69
- ...
70
- プロジェクトの分析が完了し、提案する構造を作成しました。コンテンツの生成に進む前に、ご確認いただけますか? (yes/no)
71
-
72
- あなた:
73
- > yes
74
-
75
- AI アシスタント:
76
- (レビュー用に提案されたドキュメント構造を表示)
77
- ...
78
- 上記の構造をご確認ください。どの部分でも追加、削除、修正を依頼できます。
79
- ```
80
-
81
- ## まとめ
82
-
83
- 対話型チャットアシスタントは、ガイド付きの会話形式でドキュメントを管理するための強力なツールです。必要な手順やコマンドを自動で処理することで、複雑なタスクを効率化します。
84
-
85
- 特定のワークフローに関するより詳細なウォークスルーについては、[ドキュメントの生成](./guides-generating-documentation.md) ガイドを参照してください。
@@ -1,85 +0,0 @@
1
- # Interactive Chat
2
-
3
- The interactive chat assistant provides a conversational interface for generating, modifying, and managing your documentation. Instead of running individual commands, you can describe what you need to do, and the assistant will guide you through the process, calling on the appropriate tools to complete the task.
4
-
5
- This approach simplifies the documentation workflow by handling the underlying commands for you. It is the recommended method for most interactions with the tool.
6
-
7
- ## Starting the Chat Assistant
8
-
9
- To begin an interactive session, run the `chat` command from your terminal:
10
-
11
- ```bash
12
- aigndoc chat
13
- ```
14
-
15
- This will launch the assistant, and you can begin typing your requests.
16
-
17
- ## Core Capabilities
18
-
19
- The chat assistant is designed to handle the entire documentation lifecycle. Its primary functions include:
20
-
21
- <x-cards data-columns="2">
22
- <x-card data-title="Generate Documentation" data-icon="lucide:file-plus-2">
23
- Create a complete documentation structure and initial content by analyzing your project's source files.
24
- </x-card>
25
- <x-card data-title="Refine and Update" data-icon="lucide:edit">
26
- Regenerate specific sections or entire documents based on your feedback or changes in the source code.
27
- </x-card>
28
- <x-card data-title="Translate Content" data-icon="lucide:languages">
29
- Translate existing documentation into multiple languages to reach a broader audience.
30
- </x-card>
31
- <x-card data-title="Publish and Manage" data-icon="lucide:upload-cloud">
32
- Assist with publishing your documentation and managing team-based workflows.
33
- </x-card>
34
- </x-cards>
35
-
36
- ## Available Commands
37
-
38
- Within the chat, you can state your goal in plain language (e.g., "update the getting started guide") or invoke specific commands. The assistant understands the following core commands, which correspond to its specialized skills:
39
-
40
- | Command | Description |
41
- | :--- | :--- |
42
- | `generate` | Starts the process of creating a new documentation structure from source files. |
43
- | `update` | Modifies existing documents based on code changes or user feedback. |
44
- | `translate` | Translates documents into one or more supported languages. |
45
- | `publish` | Publishes your documentation to make it accessible online. |
46
- | `init` | Guides you through creating an initial configuration file for the project. |
47
- | `clear` | Removes generated files, configurations, and cached data. |
48
- | `prefs` | Manages your saved preferences for document generation. |
49
- | `evaluate` | Assesses the quality and completeness of your generated documentation. |
50
- | `history` | Shows the history of updates made to your documentation. |
51
- | `exit` | Ends the interactive chat session. |
52
-
53
- ## Example Interaction
54
-
55
- Here is a sample conversation to illustrate how the interactive assistant works.
56
-
57
- ```text
58
- You:
59
- > Hello, I need to create documentation for a new project.
60
-
61
- AI Assistant:
62
- Of course. To get started, I need to analyze your project structure. Could you please provide the path to your source code directory?
63
-
64
- You:
65
- > ./src
66
-
67
- AI Assistant:
68
- Thank you. I will now analyze the files in ./src to propose a documentation structure. This may take a few moments...
69
- ...
70
- I have analyzed your project and created a proposed structure. Would you like to review it before I proceed with generating the content? (yes/no)
71
-
72
- You:
73
- > yes
74
-
75
- AI Assistant:
76
- (Displays the proposed documentation structure for review)
77
- ...
78
- Please review the structure above. You can ask me to add, remove, or modify any part of it.
79
- ```
80
-
81
- ## Summary
82
-
83
- The interactive chat assistant is a powerful tool for managing your documentation in a guided, conversational manner. It streamlines complex tasks by handling the necessary steps and commands for you.
84
-
85
- For a more detailed walkthrough of a specific workflow, see the [Generating Documentation](./guides-generating-documentation.md) guide.
@@ -1,85 +0,0 @@
1
- # 互動式聊天
2
-
3
- 互動式聊天助理提供了一個對話式介面,用於產生、修改和管理您的文件。您無需執行單獨的指令,只需描述您需要做什麼,助理便會引導您完成整個流程,並呼叫適當的工具來完成任務。
4
-
5
- 這種方法透過為您處理底層指令,簡化了文件工作流程。這是與此工具進行大多數互動時的建議方法。
6
-
7
- ## 啟動聊天助理
8
-
9
- 若要開始互動式對話,請在您的終端機中執行 `chat` 指令:
10
-
11
- ```bash
12
- aigndoc chat
13
- ```
14
-
15
- 這將會啟動助理,您就可以開始輸入您的請求。
16
-
17
- ## 核心功能
18
-
19
- 聊天助理的設計旨在處理整個文件生命週期。其主要功能包括:
20
-
21
- <x-cards data-columns="2">
22
- <x-card data-title="產生文件" data-icon="lucide:file-plus-2">
23
- 透過分析您專案的原始檔案,建立完整的文件結構和初始內容。
24
- </x-card>
25
- <x-card data-title="優化與更新" data-icon="lucide:edit">
26
- 根據您的回饋或原始碼的變更,重新產生特定章節或整份文件。
27
- </x-card>
28
- <x-card data-title="翻譯內容" data-icon="lucide:languages">
29
- 將現有文件翻譯成多種語言,以觸及更廣泛的受眾。
30
- </x-card>
31
- <x-card data-title="發布與管理" data-icon="lucide:upload-cloud">
32
- 協助發布您的文件並管理團隊協作流程。
33
- </x-card>
34
- </x-cards>
35
-
36
- ## 可用指令
37
-
38
- 在聊天中,您可以用自然語言陳述您的目標(例如,「更新入門指南」),或呼叫特定指令。助理能理解以下核心指令,這些指令對應其專業技能:
39
-
40
- | Command | Description |
41
- | :--- | :--- |
42
- | `generate` | 從原始檔案開始建立新文件結構的流程。 |
43
- | `update` | 根據程式碼變更或使用者回饋修改現有文件。 |
44
- | `translate` | 將文件翻譯成一種或多種支援的語言。 |
45
- | `publish` | 發布您的文件,使其可在線上存取。 |
46
- | `init` | 引導您為專案建立初始設定檔。 |
47
- | `clear` | 移除產生的檔案、設定和快取資料。 |
48
- | `prefs` | 管理您儲存的文件產生偏好設定。 |
49
- | `evaluate` | 評估您產生的文件的品質和完整性。 |
50
- | `history` | 顯示您文件的更新歷史記錄。 |
51
- | `exit` | 結束互動式聊天對話。 |
52
-
53
- ## 互動範例
54
-
55
- 以下是一段範例對話,用來說明互動式助理如何運作。
56
-
57
- ```text
58
- 您:
59
- > 你好,我需要為一個新專案建立文件。
60
-
61
- AI 助理:
62
- 當然。在開始之前,我需要分析您的專案結構。可以請您提供原始碼目錄的路徑嗎?
63
-
64
- 您:
65
- > ./src
66
-
67
- AI 助理:
68
- 謝謝您。我現在將分析 ./src 中的檔案,以提出一個文件結構建議。這可能需要一些時間...
69
- ...
70
- 我已經分析了您的專案並建立了一個建議的結構。在繼續產生內容之前,您想先檢視它嗎? (yes/no)
71
-
72
- 您:
73
- > yes
74
-
75
- AI 助理:
76
- (顯示建議的文件結構供檢視)
77
- ...
78
- 請檢視上方的結構。您可以要求我新增、移除或修改其中的任何部分。
79
- ```
80
-
81
- ## 總結
82
-
83
- 互動式聊天助理是一個強大的工具,能以引導式、對話式的方式管理您的文件。它透過為您處理必要的步驟和指令,簡化了複雜的任務。
84
-
85
- 若需特定工作流程的更詳細演練,請參閱 [產生文件](./guides-generating-documentation.md) 指南。
@@ -1,85 +0,0 @@
1
- # 交互式聊天
2
-
3
- 交互式聊天助手提供了一个对话式界面,用于生成、修改和管理您的文档。您无需运行单个命令,只需描述您需要做什么,助手就会引导您完成整个过程,并调用适当的工具来完成任务。
4
-
5
- 这种方法通过为您处理底层命令来简化文档工作流。对于与该工具的大多数交互,这是推荐的方法。
6
-
7
- ## 启动聊天助手
8
-
9
- 要开始交互式会话,请在您的终端中运行 `chat` 命令:
10
-
11
- ```bash
12
- aigndoc chat
13
- ```
14
-
15
- 这将启动助手,您可以开始输入您的请求。
16
-
17
- ## 核心功能
18
-
19
- 聊天助手旨在处理整个文档生命周期。其主要功能包括:
20
-
21
- <x-cards data-columns="2">
22
- <x-card data-title="生成文档" data-icon="lucide:file-plus-2">
23
- 通过分析您项目的源文件,创建完整的文档结构和初始内容。
24
- </x-card>
25
- <x-card data-title="优化和更新" data-icon="lucide:edit">
26
- 根据您的反馈或源代码中的更改,重新生成特定部分或整个文档。
27
- </x-card>
28
- <x-card data-title="翻译内容" data-icon="lucide:languages">
29
- 将现有文档翻译成多种语言,以覆盖更广泛的受众。
30
- </x-card>
31
- <x-card data-title="发布和管理" data-icon="lucide:upload-cloud">
32
- 协助发布您的文档并管理基于团队的工作流。
33
- </x-card>
34
- </x-cards>
35
-
36
- ## 可用命令
37
-
38
- 在聊天中,您可以用自然语言陈述您的目标(例如,“更新入门指南”),或调用特定命令。助手能理解以下核心命令,这些命令与其专业技能相对应:
39
-
40
- | Command | Description |
41
- | :--- | :--- |
42
- | `generate` | 从源文件开始创建新文档结构的过程。 |
43
- | `update` | 根据代码更改或用户反馈修改现有文档。 |
44
- | `translate` | 将文档翻译成一种或多种支持的语言。 |
45
- | `publish` | 发布您的文档,使其可以在线访问。 |
46
- | `init` | 指导您为项目创建初始配置文件。 |
47
- | `clear` | 删除生成的文件、配置和缓存数据。 |
48
- | `prefs` | 管理您保存的文档生成偏好设置。 |
49
- | `evaluate` | 评估您生成的文档的质量和完整性。 |
50
- | `history` | 显示您文档的更新历史。 |
51
- | `exit` | 结束交互式聊天会话。 |
52
-
53
- ## 交互示例
54
-
55
- 以下是一个示例对话,用以说明交互式助手的工作方式。
56
-
57
- ```text
58
- You:
59
- > 你好,我需要为一个新项目创建文档。
60
-
61
- AI Assistant:
62
- 当然。首先,我需要分析您的项目结构。您能提供源代码目录的路径吗?
63
-
64
- You:
65
- > ./src
66
-
67
- AI Assistant:
68
- 谢谢。我现在将分析 ./src 中的文件,以提出一个文档结构。这可能需要一些时间...
69
- ...
70
- 我已经分析了您的项目并创建了一个建议的结构。在继续生成内容之前,您想先预览一下吗? (yes/no)
71
-
72
- You:
73
- > yes
74
-
75
- AI Assistant:
76
- (显示建议的文档结构以供预览)
77
- ...
78
- 请预览上面的结构。您可以要求我添加、删除或修改其中的任何部分。
79
- ```
80
-
81
- ## 总结
82
-
83
- 交互式聊天助手是一个强大的工具,能以引导式的对话方式管理您的文档。它通过为您处理必要的步骤和命令来简化复杂任务。
84
-
85
- 关于特定工作流的更详细演练,请参阅 [生成文档](./guides-generating-documentation.md) 指南。