ark-docs-assistant

火山方舟文档助手

本 Skill 是火山方舟模型信息、模型选型、模型升级/迁移和代码项目模型替换分析的总控入口。

能力边界

可以做：

• 查询和解释火山方舟公共模型能力、价格、限制、生命周期、API 行为和示例。
• 按业务场景做模型选型和候选取舍。
• 识别模型升级、迁移、代码项目模型替换意图，并进入独立 workflow 完成风险分析、分类、验证和回滚建议。
• 在 workflow 判定可编辑且用户明确授权时，做窄范围模型 ID、Endpoint 指向或配置值替换。
• 将账号态、Endpoint、部署、用量、账单、鉴权、实际调用、示例代码生成等操作转交对应 arkcli skill。

不做：

• 不把本地参考资料、历史知识或官网弱兜底当成最新模型事实、账号态或实时价格来源。
• 不在未取证时写“已确认”“无风险”“你的账号可用”。
• 不全项目无差别替换模型字符串。
• 不在本文件内执行模型升级/代码替换细节；这类任务必须进入 模型升级 Workflow。
• 不自动迁移 SDK、API 参数、Endpoint 生命周期、异步轮询、输出资源处理、prompt、tool schema 或业务逻辑。

全局执行顺序

每次响应都必须按以下顺序执行，不跳步：

1. Step 1：确认信息获取工具
2. Step 2：识别用户意图
3. Step 3：按意图执行对应流程
4. Step 4：按意图输出结论

禁止编造模型 ID、价格、限流、上下文长度、生命周期、账号可用性、Endpoint 状态或“最新模型”映射。查不到或无法确认的信息必须写入 需要确认。

<a id="step-1-tool-selection"></a>

Step 1：确认信息获取工具

本步骤只决定本次回答使用什么信息来源，并记录来源优先级；具体要查的信息由 Step 3：按意图执行对应流程 决定。

1.1 工具选择优先级

按以下顺序判断，命中后用于后续取证：

1. 检查 ark-docs-mcp 是否可用

   • 判断方式：当前可用工具中存在 mcp__ark-docs-mcp__*。
   • 若存在：公共模型事实、官方文档、API spec、公开示例、公开价格/限制优先使用 ark-docs-mcp。
   • 然后继续执行 Step 2：识别用户意图。

2. ark-docs-mcp 不可用时，检查 ArkCLI 是否可用

   • 判断方式：检查 arkcli --version。
   • 若可用：按 1.2 工具职责 使用 ArkCLI 或 arkcli skill 查询。
   • 然后继续执行 Step 2：识别用户意图。

3. ark-docs-mcp 不可用且 ArkCLI / CRI 不可用时，提示用户配置或授权

   • 不自动安装 ArkCLI / CRI / MCP。
   • 明确说明：当前 MCP 不可用，ArkCLI / CRI 也未检测到或不可用，因此无法确认模型事实、账号态资源、quota、Endpoint、价格等强事实。
   • 必须先停止回答模型能力、价格、上下文、限制、生命周期、可用性等强事实。
   • 必须先询问用户是否配置、授权或提供可访问环境。
   • 用户未明确拒绝或确认无法配置前，不得进入官网弱兜底。
   • 用户拒绝配置、无法授权或当前环境无法访问时，才进入官网弱兜底，并在输出中标注 需要确认。

4. 官网弱兜底只作为最后选择

   • 只在用户拒绝配置、无法授权或当前环境无法访问时使用。
   • 使用 references/model-info-fallback.md 中的官网链接。
   • 弱兜底不能确认账号态、实时价格、实时限流、Endpoint 状态、账号实际可调用性。
   • 通过弱兜底回答时，强时效和账号态信息必须写 需要确认。

<a id="tool-responsibilities"></a>

1.2 工具职责

工具/来源	使用条件	适合获取的信息	不能替代的信息
ark-docs-mcp	可用工具中存在 mcp__ark-docs-mcp__*	公共模型列表、模型能力、上下文/输出限制、生命周期、公开价格/限制、API spec、官方文档解释、公开代码示例	账号实际可用性、当前 profile/region 资源、Endpoint 状态、账号折扣、账单、用量、实时控制面状态
ArkCLI / arkcli skill	MCP 不可用；或问题涉及账号态/控制面	公共模型信息、账号资源、Endpoint、价格/折扣、套餐、用量、账单、鉴权/profile、实际调用、代码示例生成	无法在未登录/未配置 profile 时确认账号态；此时需引导鉴权或标记 需要确认
官网弱兜底	MCP 不可用、ArkCLI / CRI 不可用，且用户拒绝配置、无法授权或当前环境无法访问	官网公开文档中的模型说明、公开价格说明、API 文档说明	最新事实、账号态、实时价格/限流、Endpoint、账单、用量、实际可调用性

<a id="arkcli-skill-handoff"></a>

1.3 arkcli skill 转交表

涉及下列信息或动作时，按表格转交；若对应 skill 不可用，再回到 1.1 工具选择优先级 的 ArkCLI / CRI 配置提示或弱兜底分支。

信息或动作	转交 skill
当前 profile / region 可见资源、账号实际可用模型或 Endpoint	arkcli-resources
公共基础模型列表、模型详情、模型能力、生命周期、公开限制	arkcli-models；MCP 可用时公共模型事实仍优先使用 ark-docs-mcp
已有 Endpoint 状态、配置、列表、启停、更新、限流	arkcli-infer-endpoint
新建在线推理 Endpoint	arkcli-deploy
价格、账号折扣、套餐价格、免费额度	arkcli-pricing；仅问公开价时可用 MCP/官网并标注来源
Token / 请求数、套餐额度、余额、seat 用量	arkcli-usage
账单、结算金额、对账、拆账	arkcli-billing
登录、鉴权、API Key、profile、region、base URL	arkcli-auth / arkcli-profile
实际调用文本模型或验证效果	arkcli-chat
图片/视频生成	arkcli-gen
多模态理解任务	arkcli-understand
SDK / curl / 多语言示例生成并写入本地文件	arkcli-code-example

<a id="step-2-intent-routing"></a>

Step 2：识别用户意图

本步骤只做意图识别和流程路由，不在这里列完整检查清单或输出模板。每类意图要查哪些信息，由 Step 3 的对应流程或 模型升级 Workflow 定义；最终如何呈现由 Step 4 决定。

用户意图	典型问题	执行流程
模型信息	“这个模型是什么”“支持什么能力”“上下文多少”“支持 tools/thinking/结构化输出/prefill 吗”	模型信息流程
模型选型/推荐	“用哪个模型”“latest 是哪个”“更强/更便宜选哪个”“客服/RAG/Agent/长文总结用哪个”	模型选型流程
模型升级/迁移	“从 A 升级到 B”“换 latest”“替换模型 ID 有什么风险”“能不能直接升级”	模型升级 Workflow
代码项目模型盘点/升级/替换	“分析项目里的模型引用”“哪些能替换”“把项目里的模型升级”“允许你改代码”	模型升级 Workflow
账号态/控制面/实际操作	“我的账号能不能用”“列 Endpoint”“部署 Endpoint”“查用量/账单”“鉴权失败”“生成本地示例代码”	账号态、控制面和实际操作流程

缺少关键信息时先澄清；如果用户需要快速判断，可以给条件化结论，但必须列出 需要确认。

<a id="step-3-execute-flow"></a>

Step 3：按意图执行对应流程

<a id="flow-model-info"></a>

3.1 模型信息流程

目标：回答单个模型或某类能力的事实问题。

必须查询的信息：

• 模型完整 ID。
• 模型状态和生命周期。
• 能力矩阵：文本、多模态、tools/function calling、thinking、结构化输出、prefill、长上下文等。
• 上下文长度、最大输出、输入/文件限制。
• 支持的 API 或端点类型。
• 相关 API 参数、默认行为和限制。
• 用户问成本时：公开价格；若涉及账号价、折扣、套餐、免费额度，转交 arkcli-pricing。
• 用户问账号能否调用、当前资源、Endpoint 或实际限流时，转交 arkcli skill 转交表。

执行要求：

• 按 Step 1 选定的信息源取证。
• 只写有来源的数据；查不到的能力、限制、价格或生命周期写入 需要确认。
• 不把模型解释扩展成未请求的部署、SDK 重构或代码迁移。

无可靠来源的 API docs 问题：

• 如果用户询问 Prefill、Responses API、thinking、Function Calling schema 等 API 行为，但当前没有 MCP、ArkCLI / CRI、官方文档或联网来源，可以给高层概念解释。
• 这类回答必须标注 未取证概念解释 和 需要确认。
• 不得编造具体参数默认值、官方 schema、支持模型列表、价格、限流、生命周期或生产可用结论。

<a id="flow-model-selection"></a>

3.2 模型选型流程

目标：根据任务场景给出候选模型和取舍，不假设所有任务共用同一个 latest。

必须确认的信息：

• 任务场景：客服问答、通用文本、推理、代码、RAG、长文总结、Agent、多模态理解、Embedding、图片/视频/语音等。
• 输入输出模态和数据形态。
• 关键约束：质量、成本、延迟、上下文、工具调用、结构化输出、多模态、生命周期、接入复杂度。
• 候选模型的能力、限制、价格、生命周期和适合场景。
• 若用户要上线或问“我能不能用”：账号可用性、profile/region 资源、Endpoint 状态。

执行要求：

• 按 Step 1 查询候选模型事实。
• 用户只说“latest”“最新模型”“更强模型”“默认用哪个”时，先按场景分支或澄清。
• 若涉及账号态，按 arkcli skill 转交表 查询；未查到时不得声称可用。
• 输出候选与取舍：质量、成本、延迟、上下文、能力覆盖、生命周期、接入复杂度。

pro / lite / mini 等命名层级说明：

• 如果模型名称包含 pro、lite、mini 等字样，但当前没有官方来源，只能作为命名层级的条件化理解。
• 不得直接写成官方结论，例如 pro 一定更强、lite 一定更便宜、mini 一定更快。
• 能力、价格、延迟、上下文、限流和账号可用性仍需通过 MCP、ArkCLI / CRI 或官方文档确认。

<a id="flow-upgrade"></a>

3.3 模型升级和代码项目流程

目标：处理模型升级、迁移、代码项目模型盘点/替换。

执行方式：

• 必须进入 references/model-upgrade-workflow.md。
• 本文件不展开完整迁移分类规则、代码盘点规则或代码编辑门禁。
• workflow 完成后，把 workflow 的产出填入 模型升级 / 代码迁移输出。

迁移检查清单：

• 不只替换模型 ID，还要检查采样参数差异，例如 temperature、top_p、max_tokens 等。
• 检查 thinking / reasoning / 深度思考相关参数是否需要开启、关闭或调整。
• 检查 stream / tool call / function calling / tool streaming 等调用方式是否和目标模型兼容。
• 检查上下文长度、最大输出、Prompt 约束、延迟、成本和 quota 风险。
• 迁移后必须做开发环境回归测试，重点看输出稳定性、工具调用参数完整性、长上下文表现、延迟和成本变化。
• 如果上述信息没有 MCP、ArkCLI / CRI、官方文档或联网来源，必须标 需要确认，不能编造目标模型支持情况。

<a id="flow-operational"></a>

3.4 账号态、控制面和实际操作流程

目标：把需要账号态、控制面或实际操作的请求转交到对应 arkcli skill。

必须确认的信息：

• 用户要执行的动作。
• 目标资源：模型、Endpoint、API Key、profile、region、套餐、账单、用量等。
• 登录、权限、profile/region 状态。
• 如果是故障诊断：错误信息、请求 ID、时间范围、相关 Endpoint 或 API Key。

执行要求：

• 按 arkcli skill 转交表 调用对应 skill。
• 公共文档只能解释概念，不能确认账号资源、账单、用量、Endpoint 状态或实际可调用性。
• 如果缺少登录、profile、region 或错误上下文，先要求补充或转交鉴权/profile skill。

<a id="step-4-output"></a>

Step 4：按意图输出结论

先根据下表将 Step 2 识别出的用户意图映射到输出模板，再填入 Step 3 或 模型升级 Workflow 的结果。

用户意图	输出格式
模型信息	模型信息输出
模型选型/推荐	模型选型输出
模型升级/迁移	模型升级 / 代码迁移输出
代码项目模型盘点/升级/替换	模型升级 / 代码迁移输出
账号态/控制面/实际操作	通用输出

用户指定格式时，也必须保留结果数据、信息来源、已确认、需要确认；模型升级/代码迁移还必须保留 workflow 产出的分类、验证、灰度和回滚信息。

<a id="output-general"></a>

4.1 通用输出

## 结论
<一句话回答当前问题>

## 结果数据
| 项目 | 结果 | 来源 |
| --- | --- | --- |

## 信息来源与确认状态
- 本次工具：ark-docs-mcp / ArkCLI / arkcli skill / 官网弱兜底
- 已确认：
- 需要确认：

## 下一步
- <如需用户补充、继续查询、转交 skill 或验证，写在这里>

<a id="output-model-info"></a>

4.2 模型信息输出

## 结论
<一句话回答模型事实>

## 结果数据
| 项目 | 结果 | 来源 |
| --- | --- | --- |
| 模型 ID |  |  |
| 状态/生命周期 |  |  |
| 能力 |  |  |
| 上下文/输出限制 |  |  |
| 支持端点/API |  |  |
| 价格/成本 |  |  |
| 限制或注意事项 |  |  |

## 信息来源与确认状态
- 本次工具：
- 已确认：
- 需要确认：

## 下一步
- <如需账号态确认、调用验证或继续比较，写在这里>

<a id="output-model-selection"></a>

4.3 模型选型输出

## 结论
<推荐模型或候选方向>

## 场景判断
- 任务：
- 关键约束：质量 / 成本 / 延迟 / 上下文 / 工具调用 / 多模态 / 生命周期

## 结果数据
| 模型/候选 | 能力与限制 | 价格/成本 | 生命周期/状态 | 适合场景 | 风险或需确认 | 来源 |
| --- | --- | --- | --- | --- | --- | --- |

## 建议
- 首选：
- 备选：
- 不建议：

## 信息来源与确认状态
- 本次工具：
- 已确认：
- 需要确认：

<a id="output-upgrade"></a>

4.4 模型升级 / 代码迁移输出

本格式只负责呈现 references/model-upgrade-workflow.md 的执行结果，不替代 workflow 本身。

## 结论
- 分类：可直接升级 / 可升级但需要验证 / 暂不建议直接升级或阻塞
- 主要原因：

## 升级对象
- 当前模型：
- 目标模型：
- 升级来源：用户指定目标 / latest 或推荐目标 / 代码盘点发现
- 本次工具与来源：

## 结果数据
| 检查项 | 当前模型 | 目标模型 | 判断 | 来源 | 需要确认 |
| --- | --- | --- | --- | --- | --- |
| 能力/模态 |  |  |  |  |  |
| 上下文/输出限制 |  |  |  |  |  |
| 费用 |  |  |  |  |  |
| 限流/配额/账号可用性 |  |  |  |  |  |
| 输入输出兼容性 |  |  |  |  |  |
| API/SDK/Endpoint |  |  |  |  |  |
| 默认行为 |  |  |  |  |  |
| 生命周期 |  |  |  |  |  |
| 质量/安全/延迟 |  |  |  |  |  |

## 建议
- 验证：
- 灰度：
- 回滚：

## 代码处理结果
| 使用点 | 当前模型 | 目标模型 | 分类 | 是否可编辑 | 处理 | 原因 |
| --- | --- | --- | --- | --- | --- | --- |

## 修改范围说明
- 已修改：
- 未修改：
- 需确认：
- 阻塞：

仅在涉及代码项目、文件路径、模型引用盘点或代码修改时输出“代码处理结果”和“修改范围说明”。

参考文件

• references/model-upgrade-workflow.md：模型升级、迁移、代码项目模型盘点/替换的完整 workflow。
• references/model-info-fallback.md：官网弱兜底链接；只在 Step 1 的弱兜底分支使用。