zio-knowledge

ZIO 知识

核心原则

1. 准确性优先于记忆 — 不要依赖训练数据回答 ZIO 相关细节。回答前先获取相关文档页面。
2. 优先使用 MCP 工具，站点地图作为后备方案 — 如果已连接 zio-docs MCP 服务，请使用 MCP 工具，而不是 WebFetch。否则，请从 https://zio.dev/llms.txt 开始，了解当前文档结构，并为具体问题选择合适的页面。尚未连接？请参阅 https://zio.dev/start.md 进行添加。
3. 所有内容都注明来源 — 在回答中附上文档 URL（使用 MCP 工具时附上文档 path），以便用户核实并了解更多信息。
4. 优先查阅合适的资源 — 前往具体的参考页面，而不是根据通用概览作答。
5. 优先使用 Markdown 页面 — 使用 WebFetch 时，始终优先获取文档 URL 的 .md 版本。只有在获取 .md 失败或返回错误时，才使用常规 HTML 网站页面。

---

问题路由

任何 ZIO 相关问题？

→ 检查是否已连接 zio-docs MCP 服务（mcp.zio.dev/mcp）：

• MCP 可用： 首先使用问题调用 search_docs。每条结果都有一个 path（已通过本地索引验证）或一个 source_url（外部来源，直接获取）。使用 get_doc_page(path) 获取完整页面。需要发现路径而不是按主题搜索时，使用 get_doc_index 浏览所有已索引页面。

• MCP 不可用： 回退到 LLM 站点地图：

  • ZIO LLM 站点地图： https://zio.dev/llms.txt

  该站点地图遵循 llmstxt.org 标准，列出每个文档页面的 URL 和一行简介。阅读站点地图，找出与问题最相关的页面，然后获取这些页面，以了解 API 详情、类型和方法签名。URL 以 .md 结尾，表示这些是 Markdown 文件，可以读取其原始内容。

---

回答工作流

1. 确定主题 — effects？fibers？并发？流？测试？依赖注入？错误处理？某个生态库？
2. 路由、获取并作答 — 不要凭记忆作答。遵循上文的问题路由（优先使用 MCP 工具，站点地图作为后备方案，并应用核心原则 5 中的 .md 优先规则），然后按照核心原则 3 引用来源。
3. 如果不确定 — 引导用户查看官方文档：“如需了解最新信息，请参阅 https://zio.dev”

---

快速参考

MCP 服务（已连接时优先使用）： https://mcp.zio.dev/mcp

LLM 站点地图（MCP 未连接时作为后备方案）： https://zio.dev/llms.txt

全文文档文件（单个文件）： https://zio.dev/llms-full.txt — 该文件合并了每个文档页面的内容。当某次会话需要跨多个章节回答多个问题时，可用它通过一次请求在本地索引完整文档，而不必逐页获取。

官方文档： https://zio.dev

GitHub 仓库： https://github.com/zio/zio

Maven Central： https://central.sonatype.com/artifact/dev.zio/zio_3

示例目录（GitHub）： https://github.com/zio/zio/tree/series/2.x/examples

---

常见故障

search_docs 返回的是 source_url，而不是 path — 直接获取 source_url，不要调用 get_doc_page。

get_doc_page 无法获取返回的路径 — 原样重试一次；若仍失败，则回退到站点地图。

MCP 不可用 — 回退到上述站点地图工作流。

站点地图获取失败 — 重试一次；若问题仍然存在，则回退到 https://github.com/zio/zio（以此处源码为准）和 README。

WebFetch 获取 zio.dev/... 页面时返回 404 — 该页面已更名或移除。重新获取站点地图（https://zio.dev/llms.txt），搜索相关主题，并转到新 URL。

站点地图中没有相关主题 — 该主题可能过于细化，不足以单独成页，也可能归在更广泛的主题下。搜索 examples 目录，以及 https://github.com/zio/zio/tree/main/zio/src/main/scala/zio 下的源码。

多个页面涵盖同一主题 — 优先选择 zio.dev 上的页面，而非外部链接；若内容有实质差异，则同时引用两者。

文档页面与训练数据相矛盾 — 训练数据的截止时间早于文档网站。以文档网站为准，不要以训练数据为准。 在回答中引用该页面，以便用户核实。