Arkcli Docs

arkcli docs

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../arkcli-shared/SKILL.md，其中包含认证闸门、调用归因前缀与命令选择顺序。 CRITICAL — 执行任何 docs 命令前，MUST 先用 Read 工具读取 references/commands.md；遇到报错 MUST 读取 references/failure-modes.md。

arkcli docs 只做一件事：把方舟官方文档变成可引用的事实来源。它不是通用搜索引擎，也不是 arkcli 自身用法的说明书。

下文 docs ... / resources list 等是命令路径缩写。给用户或工具的命令必须包含 arkcli 可执行文件名，说明文字放在命令外。复用已经选定的 MCP 配置，不用示例 URL 或占位值覆盖；只有已知真实端点且确需显式传递时才带端点参数。

下一步只给当前可执行的命令。 URL、位置等参数尚未返回时，不把后续读取加入命令列表；条件和备选方案用文字说明。MCP 即使返回 total_chunks，也先读取 next_chunk_start 指向的单块，再依据新响应决定下一步。认证失败时，当前步骤转交 arkcli-auth；登录完成后才恢复 Docs。 调用归因示例中的 <agent-id> 必须替换成实际宿主名；未知时用 unknown_agent，不要把未引用的尖括号占位符交给 shell。

唤起信号（When To Trigger）

明确的官方文档请求、第三方客户端 GUI 中的方舟接入步骤（如 CC Switch 选豆包）或其他 skill 委托的产品知识问题由本 skill 承接；先按下方反唤起清单确认最终目标。不要把 docs 当成不知道该用哪个命令时的兜底入口。

问 CC Switch 里如何选豆包时，优先定位对应套餐的官方 Claude Code「使用 CC Switch」章节，核对 GUI 槽位、专属 Key、Base URL 和 Model Name；不能把通用第三方工具文档的 /api/compatible 当成 Coding Plan 或 Agent Plan 的默认地址。用户未说明套餐时，分别说明已核实的 Coding Plan、Agent Plan 与按量接入条件，再请其选定；当前套餐支持的豆包模型名用对应 arkcli plans model-list --plan <plan> 校准。该控制面查询若因宿主凭证失败，只能给标明来源与套餐的文档示例，不能宣称是当前账号实时可选清单。

按请求选择入口，再执行对应命令：

给定官方文档 URL 就直接读取，包括“读这篇”“总结链接”“查某节”；不先做通用搜索。 WebFetch 失败不代表正文不可用，同一个 URL 可交给 docs get 的 CDN 链路。

回答前核对

面向用户引用正文时，使用同一次正文读取返回的文档站 url，以文档标题为链接文字，并保留返回的章节锚点。source_url 是实际读取的 CDN Markdown 来源，用于核对正文；仅在用户需要原始 Markdown 或版本取证时额外提供并明确标注。CLI 续读仍用 url 与 snapshot，不要把 source_url 传给 docs get。MCP 沿用返回的 url；仅有大纲不构成正文依据。

• 按用户的问题逐项核对正文。比较能力时，把每个表格单元格的文字、图片 alt 与行列标题一起读取；没有文字语义的图标标为待核实，不从相邻能力推导支持情况。
• 字段与代码保留完整对象层级，分别核对请求、响应、嵌套元素及 SDK 便捷属性。required、是否可省略、default 是三个不同事实：可选不等于有默认值；只有 schema 的 default 或已读官方正文明确声明时才写默认值，否则写“未声明”。oneOf / anyOf 及按 role 区分的对象必须逐分支表述：一个分支必填不等于所有对象必填，“A 或 B 至少其一”不能写成“A 必填”。用户只需顶层字段时，不扩写未经逐分支核对的嵌套规则。示例、客户端源码和 dry-run 不能代替官方请求 schema。
• 回答限制时，除了目标小节，也检查父节前言及相关 Tip / Warning / Note；大纲没有“限制”标题，不代表正文没有限制。尚未检查时继续读同版本相关正文，不断言“没有清单”。
• 限制清单只收录原文明示排除的条目。正向支持范围与“不支持”清单分开，用带限定词的原句呈现，保留条件、例外、单位与上限；“X 默认支持，除非另有说明”不得改成“默认仅支持 X”。没有明确排除就不推断范围外不支持。涉及版本范围、支持条件或表格脚注时，答案先引用承载该条件的短句，再作概括；概括不能新增原句没有的“仅”“必须”或“全部”。只回答与问题相关且已读到依据的内容。
• 判断指定章节不存在，先核对该页完整大纲；遇到 DSL 标题不能可靠映射时，续读同一版本全文。搜索片段或读取失败不足以证明章节不存在。
• 用户指定某篇文档的章节时，先读取那篇文档中对应的章节正文；不能直接换成标题相近的另一篇。原章节若有链接及示例，要分别如实描述；另读被链接页面时，明确标为补充来源。只有已读章节确实只含链接，才能说“该节只有链接”。
• 每项结论引用实际承载该证据的读取结果 URL，不凭相近标题替换来源。字段迁移表每一行都要能在已读正文或 schema 中找到依据；删去未核实的行，或先读取并单独引用补充来源，不把跨来源知识归给当前页面。答案中不以“全部来自本文”“无遗漏”等自我保证代替逐项依据。发送前逐项检查答案中的否定和排他词（如“仅”），与承载该结论的原句对照，删掉概括时新增的限制。依据充分就作答，无须额外堆叠交叉印证；缺少依据时说明缺口，不用记忆补齐，也不在读完后声称还有分块待取。
• 输出第 N 页的条目前，必须实际执行该页 docs list / docs search，核对返回的 items / results；保存到文件时先读回完整 JSON。第一页的 has_more、snapshot 和 next_offset 只能决定下一条命令，不能充当第二页内容。续页未完成就只报告已读页和缺口，不根据目录顺序或记忆补写条目。

六条使用纪律（比参数表重要）

1. search 与 get/list 是两条独立链路，可用性不同

• search 走签名的 OpenTOP Action（控制面，需要登录身份）；get / list 读产品 CDN 上已发布的目录与 Markdown。两者的后端、上线节奏、故障域都不一样。
• 搜索失败或零命中，都不构成「文档里没有这个内容」的证据。 必须先降级到 arkcli docs list --query "<原查询>" 在已发布目录里本地过滤，确认后再下结论。不要线性翻完全部目录。
• 零命中时 CLI 返回的 next_action 就是这条降级指引；搜索链路故障时错误里的 hint 字段同样给出降级路径。照它做，不要改成「换个搜索词再试十次」。
• InvalidActionOrVersion 后停止 search；没有后端已恢复的新证据，不在目录降级之后再次安排搜索。
• --query 只在标题、描述、面包屑、路径上做本地子串匹配，不是语义检索。过滤结果为空时，换词或去掉 --query 再看完整目录，然后才能说「当前公开文档未覆盖」。
• 搜索每页 N 条用 search --top-k N（1–50）；目录每页 N 条用 list --limit N（1–100），沿返回顺序展示。关键词和页大小不改变入口选择；明确搜索时先 search，收到失败或零命中后才按规则降级。
• 显式选择 MCP 时，降级使用普通 docs list；MCP 不支持 --query，也不保证搜索和读取独立可用。后端能力表见 references/commands.md。

2. 搜到了不等于能打开

• 搜索索引是异步建立的，落后于文档发布/下线。所以「search 有结果、docs get 返回 not_found」是正常状态，不是 bug。
• 这种情况下绝对不能把 snippet 当全文用来回答问题。snippet 是片段，不含前提、限制、完整代码。
• 正确处置：用 docs list 找到该主题的当前路径，或用别的搜索结果重试；拿不到正文就明确告诉用户「这篇文档当前读不到」。

3. 正文含未降级的自定义 DSL

已发布 Markdown 剥掉了 frontmatter、补齐了 H1，但保留了文档站的自定义排版标签，CLI 不做降级。实测一篇 9 KB 文档里能出现几十个。你会遇到：

<Card>、<Columns>、<ColumnsItem>、<Tabs>、<Tab>、<Note>、<Tip>、<Warning>、<Danger>、<APILink>、<Attachment>、<RenderMd>、<span id="...">，以及尾部带 {target="_self"} 属性块的非标准内联链接。图片是绝对 CDN URL。

纪律：

• 忽略排版语法，保留语义。Tip / Warning / Note 内的前提、限制及图片 alt 与普通正文同等重要；不要把 <Card> / <Tab> 标签本身当成代码示例、配置片段或命令。
• 引用正文时，用文字表达标签内部内容及图片 alt，保留需要的围栏代码块，不抄排版标签。
• DSL 密集区域 --section 和分块边界会退化：自定义标签里的标题不是 Markdown AST 标题，可能触发 section_unavailable；超大 DSL 块也可能被从中间切断。遇到这两种情况，改读全文并顺序拼接 content。

4. snapshot 使用纪律

本节适用于公共后端。MCP 从一开始就用 arkcli docs get "<返回的 url>" --chunk-start <next_chunk_start> --chunk-count 1 --compact 续读，不传 snapshot，也不声称版本固定。每次只生成下一次读取，拿到新结果后再判断是否继续，不预排后面的块。

• snapshot 把「哪个发布版本 + 哪套分块边界」钉死，是续读的唯一正确方式。
• 续读必须带同一个 snapshot；--chunk-start > 0 时 snapshot 必填。
• snapshot 是不透明字符串，完整复制或从保存的 JSON 提取，不手工重写。只有 has_more=true 才用返回的 next_chunk_start 续读；已到末尾就说明读完，不猜下一块。
• 少量条目的翻页直接在每次独立 arkcli docs list / search 命令中读取 JSON；输出过大才按 references/commands.md 保存并读回完整 JSON、提取 snapshot 和下一位置。续页报错先逐字核对实际入参与原响应；抄错应纠正，不删 snapshot、不把错误定位符造成的 404 归因于 CDN 或 offset。
• list 翻页必须带同一个 snapshot，同时保留原 --query（如有）；snapshot 不保存筛选条件。用 list 返回的 snapshot 去 get，读到的就是列表里那个版本。
• 从大纲定位章节时，--section 必须同时带大纲返回的 --snapshot，保证锚点与正文来自同一发布版本。
• 章节自身还有下一块时，保留 --section "#<返回的 section.id>"，使用章节读取返回的新 v2 snapshot 和 next_chunk_start。不能继续使用大纲的整页 snapshot，也不能省略 section 后按整页偏移读取。尚未拿到章节响应时，只安排首块章节读取。
• 大纲后的章节读取若需回退到整页，仍带大纲返回的 snapshot；不要因改为整页读取而丢掉版本定位符。
• 收到 snapshot_expired 时从头重取（去掉 --snapshot，--chunk-start 回 0），不要猜 offset、不要拼接不同版本的内容。
• --section 返回的是 v2 章节 snapshot，绑定到具体章节：不能拿它读另一个章节、另一篇文档，也不能喂给 docs list。换章节就去掉旧 snapshot 从 chunk 0 重开。
• snapshot 是定位符，不是凭证。它不绕过产品隔离，也不能读已下线文档。

5. score 不能设绝对阈值

• score 是检索后端原始分数透传，没有归一化保证，不同查询之间不可比。
• 只能用于同一次查询内部的相对排序。禁止写「score < 0.5 就认为不相关」这类规则，也不要把它当置信度讲给用户。
• total 配 total_scope（当前恒为 candidates）：它是有界候选集里的唯一文档数，不是全库命中数。要说「一共有多少篇」只能用 docs list 的 total。
• 候选没看完时 has_more=true：带同一个 --snapshot 并把 next_offset 作为 --offset 翻页。不带 snapshot 翻页会重新检索并错位，CLI 会直接拒绝。搜索 snapshot 约 5 分钟过期，过期报 snapshot_expired，从第一页重来，不要拼接不同批次。