SuperAPI AI 工具集

byted-interactai-guide

通用与其它

查看项目

更新于 10-16 10:10

技能介绍

InteractAI Guide 是火山引擎 AI 音视频互动的对外 Skill 入口,定位为“能力、配置、接入与排障薄路由”。它不直接承载全部细节,而是负责识别用户意图和运行阶段,再加载 references/ 中的对应专题知识;API 字段、配置细节、错误码和完整排障步骤均放在 references 中。

【触发条件】 适用于以下诉求:搭建可对话语音智能体 / 语音 Demo,跑通火山 RTC 语音对话;询问产品支持情况、能力清单、某项能力的工作方式或适用边界;询问当前支持模型、接口版本、计费、公测状态或近期新增能力(需核对最新官方文档);用自然语言生成、修改或校验 StartVoiceChat / AibotCreate / AibotUpdate 配置;运行中出现“AI 没回答”“Agent 没进房”“能进房但没声音”“没有字幕”等故障;以及解释某个 RTC / VoiceChat 错误码。

【工作模式与 CLI 可用性】 先区分咨询还是实际执行。咨询模式包括文档/API 查询、概念解释、接入方案,以及基于用户提供的日志和现象进行人工排障,直接回答并按需读取 references/,不会仅因未安装 CLI 就要求安装。执行模式包括创建项目、登录鉴权、获取 App/Bot 配置、启动 Demo、运行自动诊断或调用 CLI 离线错误码查询,依赖 CLI。当前任务首次执行 CLI 前先运行 vertc version --format json 检查可用性,后续步骤无需重复检查。若命令不存在或环境无法找到 vertc,会明确说明无法执行哪些操作,同时告知用户仍可继续文档咨询、方案讨论和人工排障,不会把 Skill 整体判定为不可用,也不会把 CLI 缺失解释成 RTC、VoiceChat 或项目故障。如用户希望继续执行,提供 npm install -g @volcengine/rtc-cli,安装后用 vertc version --format json 验证。

【最短可运行路径(公开命令)】 vertc init --scene voice-agent --platform web --name my-agent;cd my-agent;vertc auth login;vertc dev。需要用户从有限候选中选择时,必须优先调用当前环境已提供的结构化提问工具(如 request_user_input 或 AskUserQuestion),等待用户选择后再继续;没有可用工具时降级为简短编号文本选项,不调用环境未提供的工具。

auth login:需要授权时先询问浏览器/手动登录方式,默认将可刷新的 Signin 凭证保存到受保护的用户级文件,不读取或修改当前项目。Agent/非 TTY 必须先获得用户同意,再显式使用 --browser=open;若浏览器不在 CLI 所在设备,第一轮运行 vertc auth login --browser=manual --start 并把返回的 authorization_url 交给用户,用户回传授权码后,第二轮将该码经 stdin 传给 vertc auth login --resume;收到授权码时不得重新运行 --browser=manual 或 --start。仅在用户选择 --store=keyring 后访问系统凭据存储。

dev:缺少 RTC 配置时,唯一 App 自动选择;存在 Bot 时要求用户选择并写入场景 JSON,确认零 Bot 时使用内置默认 Scene,随后一次启动 Web 与 Server。非 TTY 若收到 vertc.dev.selection_required,只从 error.details 读取公开候选,再用 --app-id 或可重复的 --bot-id 重试。Bot 候选超过结构化提问工具选项上限时不截断、不分页展示,告知候选总数并提供控制台链接供用户查看,再将用户返回的 Bot 名称或 ID 从 error.details.bots 解析为唯一 Bot ID;名称不唯一时只展示同名候选。需要重新选择时使用 --reconfigure。启动后在页面点击 Start 进房对话。若 dev 未发现可用 RTC 应用,直接让用户打开 RTC 控制台完成实名认证并开通 RTC 服务。失败先跑 vertc doctor(只读定位),再按路由表处理。

【意图/阶段 → references 路由】 产品能力概览/是否支持/最新能力 → references/capabilities.md(快变事实查当前官方文档);RTC 文档搜索/精确正文核验 → references/topic-doc-catalog.md → documentation-retrieval.md(精确 list → fetch;无路由再 search);VoiceChat API 字段/调用方式 → references/voicechat-api.md(官方链接优先);生成/修改/校验 VoiceChat 配置 → references/voice-agent-config.md,再按需加载 model / validation / output;进房失败/无媒体/有声但播不出 → references/web-sdk-diagnosis.md;Agent 未进房/无字幕/ASR·LLM·TTS 异常 → references/voice-agent-runtime.md;单个事件能证明什么/当前证据边界 → references/integration-flow.md;“AI 没回答”(症状模糊)→ references/integration-flow.md,不能收敛时再读 integration-stages.md;CLI 命令自身报错 → 读 error.code + vertc doctor。可用 vertc skills read byted-interactai-guide/references/integration-flow.md 直接读取任一 reference。

【配置请求】 先读 voice-agent-config.md,再加载它指向的 reference。字段范围、枚举以及 Provider/Model/Resource 兼容性会随产品变化,确定结论前需核对当前产品、接口和 API 版本的官方正文。控制台配置验证遵循 voice-agent-config-validation.md 中限定的 docs search → fetch 流程:同一分区沿用原 query,证据不足时保留 unknown。咨询涉及当前 RTC 文档时,先按 documentation-retrieval.md 使用公开只读命令检索并获取原文;不把搜索摘要当正文,也不在服务不可用时静默改用过期资料。

【能力回答边界】 必须区分:产品支持、受模型/版本/配置限制、当前 Demo/CLI 未覆盖、尚未核验。Demo 未实现、本地 reference 未覆盖或无法联网,都不能推导为产品不支持;确定性“不支持”必须有当前官方文档依据。当前能力、精确 API、模型兼容、计费、配额和公测状态等快变事实,按 capabilities.md 先查官方正文;无法查询时说明本地 verified_at 和未核验边界。

【运行阶段识别】 端到端链路:鉴权 → Demo 配置 → Web SDK 初始化 → 用户进房 → 麦克风采集与发布 → StartVoiceChat → Agent 进房 → Agent 订阅用户音频 → ASR/VAD → LLM → TTS → 用户订阅并播放 Agent 音频。快判证据见 integration-flow.md;完整阶段与深挖路由见 integration-stages.md。对“AI 没回答”不给泛化清单:先读 integration-flow.md,确认上一步成功再前进,命中首个失败/缺证据阶段即停止;只有快判无法收敛且用户要求完整定位时,才读取 integration-stages.md 和一个相关 domain reference。

【诊断工具】 vertc doctor:只读两级体检(CLI 自检 + 项目就绪),逐项 PASS/WARN/SKIP/UNKNOWN/FAIL;不写入凭证、不修改配置、不联网补全项目;登录态由 vertc auth login 修复,缺少 RTC App/Bot 配置时再运行 vertc dev 或 vertc dev --reconfigure。vertc explain-error <code>:离线反查 RTC/VoiceChat 错误码含义与修复建议,输出标注 domain(web-sdk/voice-agent)、source 与 verified 可信状态;VoiceChat 运行态与 OpenAPI 公共码已对官方“事件和错误码”“公共错误码”核验(verified),无逐项公开来源的登录凭证与签名排障条目标为 curated-seed,会显式提示以官方为准。vertc docs search/fetch/list:只读查询 RTC 文档,无需项目或登录;先 search 得到精确 results[].id,再 fetch 原文核验,目录浏览才使用 list。

【安全边界与提醒】 AppKey 等密钥只走环境变量,绝不写入配置或日志;不在文档/命令中粘贴真实密钥。遇到 vertc.dev.selection_required 或缺少凭证时,禁止向用户索取、复述或记录 AppKey,只让用户从 error.details 选择公开 App/Bot ID。确认没有 Bot 时使用内置默认 Scene,并可引导用户访问对话式 AI 控制台定制。每次读取 vertc --format json 的输出时检查顶层 _notice;用户询问 Runtime、CLI 安装、版本或更新时,提示 _notice.update / _notice.skills 及对应命令,产品咨询、配置和诊断场景忽略这些生命周期 notice,更新或同步仍需用户明确授权。生命周期 notice 来自 24 小时本地缓存,不打断当前任务或为正常命令增加同步网络等待;冷缓存首次调用可能没有 notice,只触发后台刷新,不代表已是最新版,不要为等待 notice 轮询或重试。受控自动化可分别设置 VERTC_NO_UPDATE_NOTIFIER=1、VERTC_NO_SKILLS_NOTIFIER=1。agent / env / token 等为内部/legacy 命令(默认隐藏),优先用公开命令 init / auth login / dev / doctor / docs / explain-error / skills。权威来源包括 AI 音视频互动方案产品简介、发版说明和完整文档树。