zio-knowledge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ZIO Knowledge

ZIO 知识

Core Principles

核心原则

Accuracy over memory — Do not rely on training data for ZIO specifics. Fetch the relevant documentation page before answering.
MCP tools first, sitemap fallback — If the
```
zio-docs
```
MCP server is connected, use mcp tools instead of
```
WebFetch
```
. Otherwise start at
```
https://zio.dev/llms.txt
```
to discover the current documentation structure and pick the right page for your specific question. Not connected? See https://zio.dev/start.md to add it.
Source everything — Include the documentation URL (or doc
```
path
```
, when using the MCP tools) in your response so the user can verify and learn more.
Right resource first — Navigate to the specific reference page rather than answering from the generic overview.
Prefer Markdown pages — When falling back to
```
WebFetch
```
, always fetch the
```
.md
```
version of a documentation URL first. Fall back to the regular HTML website page only if the
```
.md
```
fetch fails or returns an error.

准确性优先于记忆 — 不要依赖训练数据回答 ZIO specifics。请先获取相关的文档页面，再作答。
优先使用 MCP 工具，其次使用 sitemap — 如果已连接
```
zio-docs
```
MCP server，请使用 MCP 工具代替
```
WebFetch
```
。否则，从
```
https://zio.dev/llms.txt
```
开始发现当前的文档结构，并针对具体问题选择合适的页面。尚未连接？请参阅 https://zio.dev/start.md 添加连接。
为所有结论提供来源 — 在回答中包含文档 URL（使用 MCP 工具时则包含文档
```
path
```
），以便用户核实并进一步学习。
优先选择正确资源 — 应导航至具体的参考页面，而不是根据通用概览作答。
优先使用 Markdown 页面 — 回退到
```
WebFetch
```
时，始终先获取文档 URL 的
```
.md
```
版本。只有在
```
.md
```
获取失败或返回错误时，才回退到常规 HTML 网站页面。

Question Routing

问题路由

Any ZIO question?

任何 ZIO 问题？

→ Check whether the

zio-docs

MCP server (

mcp.zio.dev/mcp

) is connected:

MCP available: Call
```
search_docs
```
with the question first. Each result has a
```
path
```
(verified against the local index) or a
```
source_url
```
(external, fetch directly). Fetch the full page with
```
get_doc_page(path)
```
. Use
```
get_doc_index
```
to browse all indexed pages when you need to discover paths rather than search by topic.
MCP unavailable: Fall back to the LLM sitemap:
- ZIO LLM Sitemap: https://zio.dev/llms.txt
The sitemap follows the llmstxt.org standard and lists every documentation page with its URL and a one-line description. Read it to identify the most relevant page(s) for your question, then fetch those pages for API details, types, and method signatures. The URLs end with .md, which means they are Markdown files, and you can read their raw content.

→ 检查是否已连接

zio-docs

MCP server（

mcp.zio.dev/mcp

）：

MCP 可用： 首先使用问题调用
```
search_docs
```
。每条结果都包含一个
```
path
```
（已通过本地索引验证）或
```
source_url
```
（外部来源，直接获取）。使用
```
get_doc_page(path)
```
获取完整页面。需要按主题发现路径而不是直接搜索时，使用
```
get_doc_index
```
浏览所有已索引页面。
MCP 不可用： 回退到 LLM sitemap：
- ZIO LLM Sitemap： https://zio.dev/llms.txt
该 sitemap 遵循 llmstxt.org 标准，并列出每个文档页面的 URL 和一句话说明。读取它以确定与问题最相关的页面，然后获取这些页面以了解 API 细节、类型和方法签名。这些 URL 以 .md 结尾，表示它们是 Markdown 文件，可以直接读取原始内容。

Response Workflow

回答工作流

Identify the topic — effects? fibers? concurrency? streams? testing? dependency injection? error handling? one of the ecosystem libraries?
Route, fetch, and answer — do not answer from memory. Follow Question Routing above (MCP tools first, sitemap fallback, applying Core Principle 5 for the
```
.md
```
-first rule), then cite the source per Core Principle 3.
If uncertain — direct the user to the official docs: "For the most current information, see https://zio.dev"

确定主题 — effects？fibers？并发？streams？测试？依赖注入？错误处理？还是某个 ecosystem 库？
路由、获取并回答 — 不要依赖记忆作答。按照上述“问题路由”执行（MCP 工具优先，sitemap 回退，并应用核心原则 5 中的
```
.md
```
优先规则），然后依据核心原则 3 引用来源。
如果不确定 — 将用户引导至官方文档：“有关最新信息，请参阅 https://zio.dev”

Quick Reference

快速参考

MCP Server (prefer this when connected): https://mcp.zio.dev/mcp

LLM Sitemap (fallback, if MCP is not connected): https://zio.dev/llms.txt

Full Text File Documentation (single file): https://zio.dev/llms-full.txt — the concatenated content of every documentation page. Use it to index the full docs locally in one request when a session needs multiple questions answered across sections, instead of fetching pages individually.

Official Documentation: https://zio.dev

GitHub Repository: https://github.com/zio/zio

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

Examples Directory (GitHub): https://github.com/zio/zio/tree/series/2.x/examples

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

LLM Sitemap（未连接 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

Common Failures

常见失败情况

search_docs
returns
source_url
not
path
— fetch

source_url

directly, don't call

get_doc_page

get_doc_page
fails for a returned path — retry once verbatim, else fall back to sitemap.

MCP unavailable — fall back to sitemap workflow above.

Sitemap fetch fails — Retry once; if it persists, fall back to https://github.com/zio/zio (the source is the ground truth) and the README.

WebFetch
returns 404 for a
zio.dev/...
page — it was renamed or removed. Re-fetch the sitemap (https://zio.dev/llms.txt), search for the topic, and navigate to the new URL.

Topic isn't in the sitemap — either it's too narrow for its own page or covered under a broader one. Search the examples directory and the source under https://github.com/zio/zio/tree/main/zio/src/main/scala/zio.

Multiple pages cover the same topic — prefer the page under zio.dev over external links; cite both if they materially differ.

Doc page contradicts your training data — Training cutoff is older than the docs site. Trust the docs site, not training data. Cite the page in the answer so the user can verify.

search_docs
返回
source_url
而非
path
— 直接获取

source_url

，不要调用

get_doc_page

。

针对返回的路径调用
get_doc_page
失败 — 原样重试一次，否则回退到 sitemap。

MCP 不可用 — 回退到上述 sitemap 工作流。

Sitemap 获取失败 — 重试一次；如果仍然失败，则回退到 https://github.com/zio/zio（源码是事实依据）及其 README。

WebFetch
对
zio.dev/...
页面返回 404 — 该页面可能已重命名或被移除。重新获取 sitemap（https://zio.dev/llms.txt），搜索相关主题，并导航至新的 URL。

主题未出现在 sitemap 中 — 要么该主题过于具体，没有独立页面，要么它包含在更宽泛的页面中。搜索示例目录以及 https://github.com/zio/zio/tree/main/zio/src/main/scala/zio 下的源码。

多个页面涵盖相同主题 — 优先选择 zio.dev 下的页面而非外部链接；如果两者存在实质性差异，则同时引用。

文档页面与训练数据矛盾 — 训练数据的截止时间早于文档站点的内容。信任文档站点，而不是训练数据。 在回答中引用该页面，以便用户核实。