AI增強技術文件寫作體驗：Shire智慧體語言生成示例

在過去的幾個月裡，隨著智慧體語言 Shire 的不斷開發，我們也在使用 Shire 來自舉，即使用 Shire 來進行 Shire 語言的開發。其中的一個重要應用場景是：使用 Shire 來生成 Shire 文件。在這篇文章裡，我們將分享其中的三個實踐：

生成自定義風格註釋
藉助 pipeline 函式，自動生成文件檔案
結合 RAG 技術，自動化分析文件

以及我們的一些思考。

經典文件工程的解決思路

過去在編寫文件的一些痛點，諸如於：

文件程式碼不同步。即文件的 API 變化可能落後於程式碼，導致 API 與文件出現不一致。
頻繁的 API 變更。API 變更時，文件需要手動進行更新，不能自動化同步。
概念不統一。對於同一個概念，文件的不同地方描述不一致。
重複的文件塊。文件需要重複引用某一部分的文件，不能像程式碼一樣引用。
程式碼無法執行。按照文件的步驟下來編寫的程式碼、複製的程式碼，是不能執行的。

幾年前，為了提供技術框架文件的質量，我研究了市面上主流的文件生成工具、框架文件構建等，也總結了一些文件生成的最佳實踐，諸如：

但是，這些工具都無法滿足我的需求，所以在過去我也編寫了一系列的文件生成工具，諸如：Forming （ https://github.com/inherd/forming ）

// doc-code: file("src/lib.rs").line()[2, 5]
// 讀取 "src/lib.rs" 檔案的第 2 到第 5 行
// doc-section: file("src/lib.rs").section("section1")
// 讀取 "src/lib.rs" 檔案中的 section1 相關的程式碼塊

但是，這並不是一個完美的解決方案，因為你經常要因為程式碼的變化而去更新文件。

AI 增強技術文件寫作體驗

AI 增強的技術文件寫作體驗是一種創新的方法，將先進的人工智慧技術與文件編寫和管理深度融合。它透過自動化工具和智慧分析，簡化了文件建立、更新和維護的流程，顯著提高了文件的質量、準確性和一致性。

作為一個實驗專案，我們開始使用 Shire 來生成和維護技術文件。以下是幾個主要場景示例：

程式碼註釋生成：透過分析程式碼內容，自動生成相應的文件註釋，確保文件與程式碼同步更新，並減少手動維護的需求。
自動化內容生成：基於已有的程式碼註釋，自動生成完整的文件內容，包括 API 說明、使用示例等，顯著降低了手動編寫和更新文件的工作量。
程式碼示例生成：自動讀取專案中的測試用例，並將其作為文件中的示例程式碼展示，幫助讀者更好地理解程式碼的實際應用場景。
動態內容檢索：根據特定關鍵詞，智慧檢索文件內容，幫助使用者快速定位所需資訊，並自動生成相關文件段落。

透過智慧自動化的介入，文件編寫變得更加高效和輕鬆，開發者能夠專注於核心開發任務，同時確保文件始終與最新的程式碼和功能保持同步。

Shire 智慧體語言示例

在這裡，我們主要會使用 Shire 語言的三個基本能力：

藉助 IDE 與專案和 LLM 進行互動
基於 pattern-action 的變數定義和生成
基於 RAG 函式的內容檢索

相關的示例，可以直接閱讀 Shire 中的程式碼：https://github.com/phodal/shire

基礎能力：生成自定義風格註釋

為了更好的讓 LLM 理解程式碼的函式，我們需要先使用 Shire 編寫一個生成註釋的指令。如下程式碼所示：

---
name:"生成註釋"
interaction:InsertBeforeSelection
actionLocation:ContextMenu
when: $fileName.contains(".kt")&& $filePath.contains("src/main/kotlin")
onStreamingEnd:{ insertNewline | formatCode }
---
為如下的程式碼編寫註釋，使用KDoc風格：
```$language
$selection
```
只返回註釋

在這裡，我們定義了一個專用於生成 Kotlin 程式碼註釋的指令，透過右鍵選單觸發。當用戶在 Kotlin 檔案中選擇程式碼後，Shire 會自動為選中的程式碼生成相應的註釋，並插入到程式碼之前。

讀取與生成：藉助 pipeline 函式，自動生成文件檔案

隨後，我們就可以根據目標文件路徑，諸如 docs/shire/shire-builtin-variable.md 編寫對應的生成邏輯。諸如於：

---
name:"Context Variable"
description:"Here is a description of the action."
interaction:RunPanel
variables:
"contextVariable":/ContextVariable\.kt/{ cat }
"psiContextVariable":/PsiContextVariable\.kt/{ cat }
onStreamingEnd:{ parseCode | saveFile("docs/shire/shire-builtin-variable.md")}
---
根據如下的資訊，編寫對應的ContextVariable相關資訊的 markdown 文件。
你所需要包含的ContextVariable資訊如下：
$contextVariable
...

在這裡，我們定義了一個變數 contextVariable，它的值是讀取所有的 ContextVariable.kt 檔案的結果。在執行的時候，Shire 會將這個變數的值編譯到 prompt 中，併發送給 LLM，以生成對應的文件。當 LLM 生成的文件返回後，我們會解析出其中的程式碼塊，並儲存到指定的檔案中。

除此，當代碼庫中包含有測試用例時，我們就可以配置示例作為程式碼示例：

---
name:"Hobbit Hole"
description:"Here is a description of the action."
interaction:RunPanel
variables:
"currentCode":/HobbitHole\.kt/{ cat }
"testCode":/ShireCompileTest\.kt/{ cat }
onStreamingEnd:{ saveFile("docs/shire/shire-hobbit-hole.md")}
---
根據如下的程式碼用例、文件，編寫對應的HobbitHole相關資訊的 markdown 文件。
...

當然了，也可以直接讀取原來的文件，然後進行更新。

示例：結合 RAG 技術，自動化分析文件

對於更復雜的場景，則可以直接結合 RAG 與 Shire 的 workflow 來實現。如下所示：

---
name:"Semantic Search"
variables:
"code":/.*.kt/{ splitting | embedding }
"input":"部落格建立流程"
"lang":"java"
afterStreaming:{
case condition {
default{ searching($output)| execute("SummaryQuestion.shire", $output, $input, $lang)}
}
}
---
You are a coding assistant who helps the user answer questions about code in their workspace by providing a list of
relevant keywords they can search for to answer the question.
...