用途:帮助为 ZIO 库中某一主题编写面向初学者的教程。教程属于学习导向文档,目标是帮助读者建立心智模型,既不是详尽记录 API 的参考页,也不是完成具体任务的操作指南。适用时需先明确教程主题,若未提供则先询问用户,不得自行编造主题。
主要流程与能力:
- 深入研究:借助 Task 调用 documentation:docs-researcher 代理,梳理核心概念、前置知识、相关类型及其依赖与组合顺序、实际使用的工厂方法与构造器、最简起点与可逐步叠加的复杂度、导入与 sbt 依赖,以及 Scala 2 与 Scala 3 的差异。
- 结构设计:包含引言与学习目标、背景(可选,无代码)、3-6 个概念章节(每章仅一个新概念,概念先行、代码随后并逐行注释、展示中间输出)、整合示例、运行示例、已学内容回顾、后续去向。
- 写作规范:使用编号章节标题;逐行注释每个代码块;为重要说明添加 Docusaurus admonition;不分支(不写“如果你需要 X 则改用 Y”);避免伪代码和虚假报错;提供可复制代码。
- 配套示例:为整合示例与各概念章节创建可编译的 CompleteExample.scala 等文件,并以 mdoc:embed 方式嵌入,绝不内联替代。
- 校验:运行 sbt "docs/mdoc --in docs/guides/<tutorial-name>.md --out website/docs/guides/<tutorial-name>.md" 进行限定范围编译校验。
限制:需遵循 docs-writing-style、docs-mdoc-conventions、docs-examples 等技能约定;文中示例路径、命令与包名须与实际一致;具体依赖版本、定价、平台支持等资料暂未提供。