ark-docs-reader

方舟官方文档检索

把本 Skill 作为公开文档的任务路由器和取证流程，而不是方舟 API、账号控制面或联网能力本身。先读取官方正文，再基于证据回答；不要只复述搜索摘要或模型记忆。

核心流程

1. 根据产品名、用户语言和 URL 确认目标站点。站点差异会影响答案且无法判断时，先澄清；否则说明采用的站点。
2. 判断任务类型，按任务路由选择最小必要资料，不为单个问题加载全站内容。
3. 按来源路由检索并读取正文。结构化入口只负责定位，正文、API spec 或官方示例才是证据；目标站点没有发现入口时，不得用其他站点结果代替。
4. 按证据检查验证相关性、站点、时效和冲突；证据不足时更换关键词或补读文档。
5. 先回答问题，再列出实际读取的来源。无法确认的事实明确标为“官方文档中未检索到”或“需要账号态查询”。

<a id="task-routing"></a>

任务路由

用户任务	读取范围	额外要求
查询单个事实或操作步骤	读取最相关的 1-2 篇正文	定位到直接支持结论的章节，不扩展到无关页面
查询 API 字段、错误码或代码写法	先读主题/API 正文，再按需读取 API spec 或官方示例	字段、枚举、默认值和请求结构不得凭记忆补全；示例不能替代字段契约
比较能力、迁移或排障	读取 2-3 篇能覆盖各结论的正文	逐项记录证据；文档冲突时不要静默拼接
已知官方文档 URL	直接读取该页 Markdown 镜像，失败后读取 HTML 正文	不必先搜索 llms.txt；URL 有锚点时，在锚点前添加 .md
构建知识库或离线检索	站点提供章节全文或 llms-full.txt 时使用对应文件	站点未提供批量入口时明确说明限制，不抓取全站 HTML 冒充官方语料集

<a id="source-routing"></a>

来源路由

目标为火山方舟或 BytePlus ModelArk，且需要发现未知页面时，遵循以下优先级：

1. 文档 MCP：仅用于火山方舟，且当前会话存在文档搜索与正文读取工具时使用。
2. llms.txt：MCP 不可用，或目标是 BytePlus ModelArk 时，用目标站点索引发现 Markdown 文档。
3. Markdown 镜像：已知页面 URL 时，读取 <DOC_URL>.md。
4. HTML 页面：前述方式不可用时读取原页面，只保留文章标题、正文和与问题相关的表格或代码块。

目标站点入口：

目标站点	文档索引	约束
火山方舟	https://ark.volcengine.com/llms.txt	文档 MCP 可用时优先使用；所有结论保持在火山方舟站点内
BytePlus ModelArk	https://ai.byteplus.com/ark/llms.txt	使用英文站索引和正文；不得用火山方舟内容替代 ModelArk 事实
字节云方舟（中文）	无	当前不提供文档 MCP 或 llms.txt；已知 URL 时使用 https://ark.bytedance.net/docs/<slug>.md，再回退 HTML
字节云方舟（英文）	无	当前不提供文档 MCP 或 llms.txt；已知 URL 时尝试 https://ark.byteintl.net/docs/<slug>.md，不可用时回退 HTML

大文档读取

1. 页面超过约 15 KB 或 300 行时，不得用网页抓取工具直接整篇读取；必须落盘后按 offset/limit 或 --section 分段读取。
2. 每次抓取后核对 last_heading 是否为文档最后一个章节；若正文中出现“读到这里就结束”的迹象但 last_heading 与预期不符，必须继续读取。
3. 单次回答最多读取 1-3 篇文档，每篇先看 headings 再读命中的 1-2 节；禁止把 llms-full.txt 或整篇长文整体注入上下文。

使用文档 MCP

目标为火山方舟，且当前工具中存在 ark_search_docs、ark_fetch_doc 或其命名空间变体时：

1. 用 2-5 个核心关键词搜索；首次结果不相关时更换同义词、API 名或错误码再搜索。
2. 根据标题、摘要和 URL 选择 1-3 个结果，并逐一读取正文。
3. 正文返回 has_more=true 时，继续按 chunk_start 和 chunk_count 拉取，直到覆盖所需章节。
4. API 字段仍不完整时，若可用则调用 ark_get_spec；代码证据不足时，若可用则调用 ark_search_examples。

不要把搜索摘要当成最终依据。

使用 llms.txt

仅目标为火山方舟或 BytePlus ModelArk 时使用 llms.txt。获取目标站点索引后，按标题、简介、章节和 URL 选择命中页面，并读取索引给出的 Markdown URL。环境支持 Python 和公网访问时，使用随 Skill 提供的确定性脚本：

python3 <skill-dir>/scripts/search_llms.py "<检索词>" --site ve \
  --fetch --fetch-count 3 --out-dir /tmp/ark-docs

查询 BytePlus ModelArk 时使用 --site bp。脚本只把清单 JSON 输出到 stdout，正文写入 --out-dir；先用 headings 和 last_heading 判断结构，再用 --section "<标题>" 或 --grep "<正则>" -C 2 定向读取。需要把正文内联到清单时才使用 --inline；只有旧调用方兼容场景才使用 --legacy。未指定 --out-dir 时正文写入系统临时目录下的固定子目录。只有用户明确提供其他官方 llms.txt 时，才通过 --index-url <LLMS_TXT_URL> 传入；不要为字节云站点猜测索引地址。

脚本只负责索引搜索、正文抓取和定向读取；Agent 必须继续判断内容能否支持结论。

文档 MCP 未接入时

目标为火山方舟且 MCP 不可用时，继续用 llms.txt 完成本次回答，不要中断任务。回答末尾至多附一次可选配置提示：

# Claude Code
claude mcp add --transport http ark-docs-mcp https://mcp.ark-doc-resources.cn/mcp/

# Codex
codex mcp add ark-docs-mcp --url https://mcp.ark-doc-resources.cn/mcp/

只展示与当前客户端匹配的命令；无法识别时说明两种选择。命令会修改本地配置，只有用户明确授权后才执行。BytePlus ModelArk 和字节云中英文站点不使用该 MCP。

读取字节云文档

字节云中英文站点当前没有文档 MCP、llms.txt 或 llms-full.txt：

1. 用户给出页面 URL 时，先读取该 URL 的 Markdown 镜像；镜像不可用时读取 HTML 正文。
2. 用户只给出 slug 时，分别使用目标站点的 /docs/<slug>.md 和 /docs/<slug>。
3. 用户未给出 URL 或 slug 时，从当前站点导航定位，或要求用户提供页面 URL；不要查询火山方舟或 BytePlus 后把结果当作字节云事实。
4. 需要全站语料或离线知识库时，明确说明当前站点没有批量文档入口，不递归抓取站点。

<a id="evidence-check"></a>

证据检查

• 站点：URL 必须属于目标官方站点；同一结论不得混入另一站点事实。火山方舟、BytePlus ModelArk 和字节云中英文站点分别取证。
• 正文：排除空文本、登录页、404、纯导航和只含搜索摘要的内容。
• 相关性：标题或正文必须直接覆盖问题；关键词碰巧出现不代表能够支持结论。
• 契约强度：API 字段以当前 API spec 或 API reference 为主；产品行为和限制以对应主题文档为主；官方示例只证明示例中的用法。
• 时效性：模型状态、价格、配额、限流和版本支持等易变事实必须来自当前可访问的官方正文。能识别更新时间时优先使用较新且更具体的来源。
• 冲突：来源冲突时列出冲突点和各自 URL；只有能根据适用站点、版本、发布日期或契约层级判断时才选择其一。
• 账号边界：账号资源、Endpoint 状态、折扣、账单、用量、权限和真实调用结果不属于公开文档事实，转交相应控制面工具或说明需要账号态查询。

输出要求

• 开头直接回答；随后给必要步骤、限制或不确定项。
• 在“来源”中列出实际读取的文档标题和 URL，最多保留支持结论所需的来源；不要列出未读取的搜索结果。
• 区分文档事实和建议。推断必须标注为“建议”或“推断”，并说明依据。
• 用户要求代码时，只使用正文、API spec 或官方示例中已确认的字段和调用方式。
• 多次检索仍无结果时，列出目标站点、尝试过的关键词和检索入口，不用相近但无关的文档填补答案。