在过去的几个月里，随着智能体语言 Shire 的不断开发，我们也在使用 Shire 来自举，即使用 Shire 来进行 Shire 语言的开发。其中的一个重要应用场景是：使用 Shire 来生成 Shire 文档。在这篇文章里，我们将分享其中的三个实践：
生成自定义风格注释
借助 pipeline 函数，自动生成文档文件
结合 RAG 技术，自动化分析文档
以及我们的一些思考。
经典文档工程的解决思路
过去在编写文档的一些痛点，诸如于：
文档代码不同步。即文档的 API 变化可能落后于代码，导致 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.
...
上述代码中，我们定义了一个变量 code，它的值是对所有的 *.kt 文件进行分割，并进行向量化。而这里的的 input 则是用户输入的问题， 用于搜索相关的文档内容。
在执行时，会将用户的问题发送给 LLM，由其生成关键词，然后在本地进行检索，最后，将结果发送给下一个流程，即 SummaryQuestion.shire。在 SummaryQuestion.shire 中，会将检索结果进行总结，然后生成对应的文档。
总结在这篇文档中，我们分享了使用 Shire 智能体语言来生成和维护技术文档的经验和思考。Shire 是我们在开发中不断探索和改进的一种智能语言工具， 它不仅简化了文档编写的流程，还有效解决了传统文档编写中的诸多痛点。
PS：在 IntelliJ IDEA 中，你可以搜索、安装和使用 Shire 插件来体验这些功能，详细见：https://shire.phodal.com。
