SuperAPI AI 工具集

zio-blocks-knowledge

编程与开发

查看项目

更新于 10-27 01:28

技能介绍

ZIO Blocks Knowledge 是一个面向 AI 助手的事实核查与文档检索技能,适用于回答任何与 ZIO Blocks 相关的问题。

用途 当回答内容将涉及 ZIO Blocks 的任何事实或代码(包括 zioblocks.com 以及 dev.zio 的 zio-blocks-* artifacts)时,该技能要求暂停凭记忆作答,先查阅官方文档再给出答案。

主要能力与核心原则

  1. 准确性优先于记忆:不要依赖训练数据回答 ZIO Blocks 细节,应先获取相关文档页面;若文档与训练数据冲突,以文档为准。
  2. MCP 工具优先,站点地图回退:若 zio-blocks MCP 服务器已连接,使用 MCP 工具而非 WebFetch;否则从 https://zioblocks.com/llms.txt 开始发现当前文档结构并选择合适页面。未连接时可参考 https://zioblocks.com/start.md 进行添加。
  3. 标注来源:回答中应包含文档 URL(或使用 MCP 工具时的文档路径),便于用户核实和进一步学习。
  4. 先定位正确资源:应导航到具体 block 的参考页,而非仅凭通用概览作答。每个 block 是独立的 zio-blocks-* artifact,需在其页面或 https://zioblocks.com/docs/ 目录中确认 artifact 名称、支持平台(JVM/Scala.js)和 Scala 版本(2.13/3.x)。部分 block 仅支持 JVM 或仅支持 Scala 3(例如 SQL、Datastar、HTMX)。
  5. 优先 Markdown 页面:回退到 WebFetch 时,先获取文档 URL 的 .md 版本;仅当 .md 获取失败或报错时,再回退到常规 HTML 页面。
  6. 不假定 effect 系统:ZIO Blocks 不依赖 ZIO。除非用户要求或话题涉及 ZIO 集成模块(如 zio-blocks-sql-zio),否则不要在回答中添加 ZIO 导入或 ZIO/ZLayer 代码。核心 ZIO 问题应使用 zio-knowledge 技能。

问题路由 对于任何 ZIO Blocks 问题,先检查 zio-blocks MCP 服务器(https://mcp.zioblocks.com/mcp)是否已连接:

  • MCP 可用:先调用 search_docs 检索问题。每条结果包含 path(已对照本地索引验证)或 source_url(外部链接,直接抓取)。用 get_doc_page(path) 获取完整页面。需要按主题浏览全部已索引页面时,可使用 get_doc_index。
  • MCP 不可用:回退到 LLM 站点地图 https://zioblocks.com/llms.txt。该站点地图遵循 llmstxt.org 标准,列出每个文档页面的 URL 和一行描述。阅读它可确定与问题最相关的页面,再抓取这些页面以获取 API 细节、类型和方法签名。这些 URL 以 .md 结尾,即 Markdown 文件,可直接读取原始内容。

响应流程

  1. 识别 block:属于 schema、scope、endpoint、streams、sql 还是 telemetry?位于哪个 zio-blocks-* artifact?
  2. 路由、抓取并作答:不要凭记忆回答。按上述问题路由执行(优先 MCP 工具,回退站点地图,并遵循 .md 优先规则),然后按核心原则标注来源。
  3. 若不确定:引导用户访问官方文档:“For the most current information, see https://zioblocks.com”。

快速参考

  • MCP 服务器(连接时优先使用):https://mcp.zioblocks.com/mcp
  • LLM 站点地图(MCP 未连接时的回退):https://zioblocks.com/llms.txt
  • 全文文档(单个文件):https://zioblocks.com/llms-full.txt —— 所有文档页面的拼接内容。当一个会话需要跨多个章节回答多个问题时,可用它在一次请求中本地索引全部文档,而不必逐页抓取。
  • 官方文档:https://zioblocks.com
  • GitHub 仓库:https://github.com/zio/zio-blocks
  • Maven Central:https://central.sonatype.com/artifact/dev.zio/zio-blocks-schema_3(将 schema 替换为对应 block 的模块名)

常见失败处理

  • search_docs 返回 source_url 而非 path:直接抓取 source_url,不要调用 get_doc_page。
  • get_doc_page 对返回的 path 失败:原样重试一次,否则回退到站点地图。
  • 站点地图抓取失败:可能是网络中断或文档站点正在部署。重试一次;若仍失败,回退到 https://github.com/zio/zio-blocks(源代码为准)及其 README。
  • WebFetch 对 zioblocks.com/... 页面返回 404:页面已被重命名或移除。重新抓取站点地图(https://zioblocks.com/llms.txt),搜索主题并导航到新 URL。
  • 主题不在站点地图中:可能过于具体而没有独立页面,或涵盖在更宽泛的页面下。可在 https://github.com/zio/zio-blocks 的源代码中搜索。
  • 多个页面覆盖同一主题:优先选择 zioblocks.com 下的页面而非外部链接;若内容有实质差异,可同时引用两者。

适用场景 适用于需要回答 ZIO Blocks 相关 API、类型、方法签名、artifact 信息、平台与 Scala 版本支持情况等事实性问题或代码问题时。

限制 该技能本身不提供 ZIO Blocks 的具体知识内容,而是规定检索与引用流程;实际信息以官方文档和源代码为准。未提供关于该技能的收费、价格或额外使用条件的信息。