byted-livesaas-master

# byted-livesaas-master（企业直播控播） ## 0. 启动埋点 每次启用本 Skill 时，先 best-effort 执行一次埋点脚本，再继续处理用户请求；脚本失败、超时或接口不可达时不得中断任务。 ```bash node tools/report_usage.js ``` 脚本根据 Skill **安装路径**自动识别 Agent（如 `~/.cursor/skills/` → `cursor`，`~/.codex/skills/` → `codex`）。**禁止**在未识别当前环境时硬编码 `--agent codex`。仅在自定义安装目录（`skills add --target`）或自动识别失败时，显式传入 `--agent cursor|codex|claude-code|trae|openclaw`；仍无法识别时使用 `unknown`。该脚本由 Node/CLI 发起 POST 上报，不支持浏览器页面跨域调用。 ## 1. 适用范围 ### When to use 当用户意图涉及以下任一场景时触发本 Skill： - **直播间生命周期管理与管控**：创建/删除直播间，查询列表，修改基础配置（名称/时间/模式），控制状态（开播/锁定/恢复/下播/封禁） - **直播数据分析与观众画像**：查询直播间观看时长分布统计、拉取观众用户画像明细用于洞察 - **商品库与卡片运营**：直播中对商品卡片进行上架、讲解态切换，查询商品状态或统计数据 - **评论治理与内容分析**：发送/查询/轮询评论，删除用户消息，配置敏感词，或获取评论的分析结果（含大模型分析） - **账号基础信息与媒资库运维**：获取账号配置/全局权益额度信息，批量删除媒资库视频，检查文档库容量 - **营销互动与连麦控制**：创建直播间卡券等互动工具，管理网页直播连麦协同状态 - **系统消息**：向直播间推送系统定制消息 - **观众管控**：针对观众的禁言、拉黑、踢出 - **观看页外观**：切换主题（暗黑/清爽/经典/传统节庆） - **OpenAPI 兜底**：上述未明确覆盖到的其余企业直播能力操控需求，通过调用企业直播OpenAPI来实现 ### When NOT to use - **推流/拉流/编码等底层媒体问题** → 不属于本 Skill - **WebSDK 接入 / 小程序进房 / 观看端 Token** → 使用 **byted-livesaas-dev** Skill - **账号计费 / 套餐管理** → 引导用户至火山引擎控制台 - **非企业直播产品**（如视频点播、RTC）→ 不属于本 Skill ## 2. 架构概览 ``` 用户意图 → Skill（路由 + 约束） → Agent 生成 CLI 命令 → bytedlive CLI 执行 ``` - **Skill 层**：定义意图到 CLI 子命令的映射 + 执行约束（不含可执行脚本） - **Agent 层**：根据路由表与约束拼装 `bytedlive` 命令并执行 - **CLI 层**：封装凭证管理、签名、请求发送、确认交互与 JSON 结果 > **唯一执行入口**：所有命令必须通过 `bytedlive` CLI，禁止手写 curl 或未文档化的 HTTP 请求。 ## 3. 首次使用引导与依赖安装（Onboarding） **触发条件**：本 Skill 被首次激活时（即用户第一次发出匹配 §1 触发词的请求），Agent **必须**先执行 onboarding 流程（含 CLI 自动安装与凭证配置），再处理用户的实际请求。 ### 3.1 Onboarding 检查与安装流程 ``` Step 0: 环境检查与 CLI 自动安装 ├─ 检查依赖：执行 `bytedlive --version` 判断是否已安装 ├─ 未安装时先引导安装：`npm i -g bytedlive-cli` ├─ Agent 有权限时可静默执行安装 ├─ 成功：执行 `bytedlive --version` 验证后进入 Step 1 └─ 失败：输出【CLI 安装失败引导】（见 3.2），中止后续流程，等待用户手动处理 Step 1: 检查凭证 → bytedlive openapi check-credentials --pretty ├─ 成功（已配置） → 跳过引导，直接处理用户请求 └─ 失败（未配置 / 凭证无效） → 进入 Step 2 Step 2: 输出【AK/SK 本地配置引导消息】（见 3.3） Step 3: 用户在本地终端执行 set-credentials，CLI 写入凭证并验证 Step 4: 验证通过 → 继续处理用户的原始请求 ``` ### 3.2 CLI 安装失败引导模板 当 Step 0 的自动安装失败（如缺少 Node 环境、无权限等）时，Agent **必须**向用户输出以下消息： > ⚠️ **环境依赖缺失** > > 抱歉，我尝试为你自动安装底层依赖工具 `bytedlive-cli` 但失败了（通常是因为当前环境未安装 Node.js / npm 或缺少全局写入权限）。 > > 请在你的本地终端中执行以下命令手动安装： > ```bash > npm i -g bytedlive-cli > ``` > 安装完成后执行 `bytedlive --version` 验证，并回复我“**已安装**”，我将带你继续下一步配置。 ### 3.3 AK/SK 本地配置引导模板 当检测到凭证未配置时，Agent **必须**输出以下消息（可根据上下文微调措辞，但核心信息不可缺少）： --- > 👋 **欢迎使用企业直播控播 Skill！** > > 检测到你还没有绑定企业直播账号，需要先完成一次配置。 > > 请在你的**本地终端**执行下面的命令，按提示隐藏输入 **Access Key（AK）** 和 **Secret Key（SK）**： > > ```bash > bytedlive openapi set-credentials > ``` > > - 获取路径：[火山引擎控制台](https://console.volcengine.com/iam/keymanage/) → 密钥管理 > > ⚠️ 不要把 AK/SK 发到对话里。CLI 会把密钥缓存在本地 `~/.bytedlive/openapi-credentials.json`，后续命令会自动读取。 > > 配置成功后回复我“已配置”，我会继续处理刚才的请求。 --- ### 3.4 凭证写入与验证 用户在本地终端执行： ```bash bytedlive openapi set-credentials ``` | 验证结果 | Agent 行为 | |----------|-----------| | 成功（`set-credentials` 返回 ok） | 输出 `✅ 账号绑定成功！`，然后继续处理用户的原始请求 | | 失败（401/403/签名错误） | 输出 `❌ 凭证验证失败，请检查 AK/SK 是否正确。`，引导用户在本地终端重新执行 `bytedlive openapi set-credentials` | | 失败（网络错误） | 输出 `⚠️ 网络连接异常，请稍后重试。` | ### 3.5 Onboarding 状态记忆 - 凭证验证通过后，**本会话内不再重复 onboarding** - 凭证已持久化到 `~/.bytedlive/openapi-credentials.json`，后续会话自动加载，无需重复配置 - 如果后续操作中出现凭证失效（401/403），按 §7 错误恢复策略处理，不重新走完整 onboarding ### 3.6 快速能力概览（验证通过后附带） 凭证验证通过后，在确认消息中**追加一段能力概览**，帮助用户快速了解可以做什么： > ✅ **账号绑定成功！** 以下是我可以帮你做的事情： > > | 能力 | 示例指令 | > |------|---------| > | 🎬 直播间管理 | "创建一个明天下午3点的直播间" / "查看最近的直播间" | > | 💬 评论互动 | "帮我在直播间发一条评论" / "查看最近的弹幕" | > | 📢 系统消息 | "发一条系统公告" | > | 🚫 观众管控 | "禁言某个用户" / "把捣乱的人踢出去" | > | 📊 数据与画像 | "查询直播间观看时长" / "获取观众画像详情" | > | 🛒 商品与卡片 | "给商品卡片上架" / "切换到讲解状态" | > | 🎨 观看页外观 | "切换到暗黑模式" | > | 🔧 OpenAPI | "调用 GetActivityAPI 查直播间详情" | > > 现在帮你处理刚才的请求 👇 ## 4. 凭证与 Base URL | 项目 | 规则 | |------|------| | **AK/SK** | 必需。执行任何 OpenAPI 操作前，必须先执行 `bytedlive openapi check-credentials --pretty`。若本地缓存可用，直接复用；若不可用，只引导用户在本地终端运行 `bytedlive openapi set-credentials`，禁止在对话中索要 AK/SK | | **Base URL** | 固定 `https://livesaas.volcengineapi.com/`，**不向用户询问**。仅用户主动提供专用 endpoint 时通过 `BYTEDLIVE_BASE_URL` 覆盖 | | **缓存优先级** | 命令行/环境变量 → 会话缓存 → 本地文件 `~/.bytedlive/openapi-credentials.json` | | **凭证失效** | 401/403/签名错误时，引导用户本地执行 `bytedlive openapi clear-credentials` 后再执行 `bytedlive openapi set-credentials` | ## 5. 安全机制：确认与黑名单 ### 5.1 拟人化业务确认（所有写操作必做） 1. 组装候选命令（**仅在后台准备，绝对不向用户展示具体的 CLI 命令、代码或 JSON 参数**）。 2. 用“大白话”向用户确认**业务意图**，例如：“我准备为您创建名为『测试签到』的直播间，时间是今天下午 3 点。确认要建吗？” 3. 仅当用户明确同意后才执行。 ### 5.2 黑名单二次确认（高风险操作） 命中以下操作时，在常规确认通过后，**再追加一次确认**： | 黑名单操作 | 示例命令 | |-----------|---------| | 所有删除类（含 `delete/remove/del/删除`） | `bytedlive control room ...`（删除相关） | | 观众踢出 | `bytedlive control audience kick ...` | | 观众封禁/拉黑 | `bytedlive control audience block ...` | 二次确认话术需同样拟人化：`您正在进行高风险操作（例如：踢出某个观众），这可能会影响观众体验或导致数据丢失。请最后确认一次是否继续？` ## 6. 参数获取引导（缺参时 Agent 怎么办） | 缺失参数 | Agent 应做的事 | |----------|---------------| | `--activity-id` | 先执行 `bytedlive control room list` 查询最近直播间，让用户确认目标 | | `--user-ids`（观众管控） | 询问用户提供目标用户标识，或引导查询评论列表获取 | | 直播间图片素材（封面/角标/装饰图等） | **不支持直接上传图片配置直播间**。优先让客户提供可访问的图片 URL 并继续后续配置流程；若客户无法提供 URL，则引导客户直接使用火山引擎控制台完成上传与配置（无回调流程） | | AK/SK | 先执行 `bytedlive openapi check-credentials --pretty`；无缓存或验证失败时，引导用户本地执行 `bytedlive openapi set-credentials`，不要在对话中索要 | | 不确定的 flag | 执行 `bytedlive control <子命令> --help` 查看帮助 | ## 7. 错误恢复策略 ### 7.1 回答与执行约束（强制） - **证据优先级**：必须优先基于本 Skill 已定义流程、已有 CLI 能力（`bytedlive control/openapi`）与本地知识库/参考文档作答和执行，不得跳过现有能力直接猜测。 - **官网补证**：当现有知识库、CLI 帮助与本地规则无法解决问题或无法确认参数/行为时，必须到 [火山引擎文档中心](https://www.volcengine.com/docs) 检索对应企业直播文档并据此补证后再回复。 - **无法实现/无法确认兜底**：若已穷尽本地能力与官网检索仍无法落地，必须明确告知用户「当前暂无法实现该能力」或「当前暂无法准确回答该问题」，并说明卡点；禁止编造接口、版本、字段、结果或“肯定可行”的承诺。 | 错误类型 | Agent 处理方式 | |----------|---------------| | `missing openapi credentials` | 引导用户本地执行 `bytedlive openapi set-credentials` | | 401 / 403 / 签名错误 | 凭证可能过期或错误，提示用户本地执行 `bytedlive openapi clear-credentials` 后再执行 `bytedlive openapi set-credentials` | | `InvalidActionOrVersion` / Action 不存在 | 按 §11 流程进行大模型静默自愈。失败则动用联网搜索查真实版本号并重试。期间安抚用户，切勿抛出生涩的原始报错信息。 | | 参数错误 / 缺必传字段 | 检查字段名是否与官方文档一致（参考 §10 字段名规范），补全后重试 | | 网络超时 | 重试 1 次，仍失败则告知用户 | | 未知错误 | 查 [火山引擎企业直播文档](https://www.volcengine.com/docs/3019/66792?lang=zh)，无法解决则建议工单 | ## 8. 全局选项 | 选项 | 作用 | |------|------| | `--pretty` | JSON 美化输出 | | `--non-interactive` | 禁止交互；缺参或缺凭证则直接失败 | | `-y` / `--yes` | 跳过操作前确认（凭证仍需可用） | ## 9. 命令路由表 ### 9.1 直播间（`bytedlive control room`） | 场景 | 命令 | API | 关键参数 | |------|------|-----|---------| | 创建直播间 | `bytedlive control room create` | CreateActivityAPIV2 | `--name`、`--start`/`--live-time`、`--end`/`--end-time` | | 直播间列表 | `bytedlive control room list` | ListActivityAPI | `--page`/`--page-size`、`--name`、`--status`、`--sort-by`/`--sort-order`（支持 `desc`/`asc` 或 `Desc`/`Asc`） | | 读基础配置 | `bytedlive control room config get --activity-id <id>` | GetActivityBasicConfigAPI | | | 更新基础配置 | `bytedlive control room config update --activity-id <id>` | UpdateActivityBasicConfigAPI | `--name`、`--start`、`--end`、`--view-url-path`、`--activity-type`、`--live-mode` | | 设置活动状态 | `bytedlive control room status set --activity-id <id>` | UpdateActivityStatusAPI | `--op`（3/4/5）或 `--action recover\|lock\|release` | #### 创建直播间成功回复模板（强制） 当创建直播间成功后，Agent 的回复中必须包含以下三类地址（由 `ActivityId` 动态拼接），便于用户直接进入控制台操作与网页开播： - 控制台地址：`https://console.volcengine.com/livesaas/liveManagement/<ActivityId>` - 网页开播地址：`https://console.volcengine.com/livesaas/webpush/micromode/<ActivityId>` - 观看页地址：接口返回的 `ViewUrl`（若有） 推荐回复模板： ```text 直播间已创建成功。 - 直播间名称：<Name> - ActivityId：<ActivityId> - 状态：<StatusDesc> - 控制台地址：https://console.volcengine.com/livesaas/liveManagement/<ActivityId> - 网页开播地址：https://console.volcengine.com/livesaas/webpush/micromode/<ActivityId> - 观看页地址：<ViewUrl> ``` ### 9.2 评论（`bytedlive control comment`） | 场景 | 命令 | API | 关键参数 | |------|------|-----|---------| | 发送评论 | `bytedlive control comment send --activity-id <id> --comment <文本>` | PresenterChatAPIV2 | 可选 `--audience-group-id`、`--top-status` | | 评论列表 | `bytedlive control comment list --activity-id <id>` | ListActivityChatAPI | 可选分页、时间、`--chat-type`、`--top-status` | | 轮询评论 | `bytedlive control comment poll --activity-id <id>` | PollingChatAPI | 可选 `--last-chat-id`、`--page-size`、`--start-time`/`--end-time` | ### 9.3 系统消息（`bytedlive control system-message`） | 场景 | 命令 | API | 关键参数 | |------|------|-----|---------| | 发送系统消息 | `bytedlive control system-message send --activity-id <id> --content <文本>` | SendCustomSystemMessageAPI | 可选 `--message-type` | ### 9.4 观众管控（`bytedlive control audience`） 均需 `--activity-id`。用户标识常用 `--user-ids`，部分场景可用 `--cookies` 或 `--external-user-ids`（以 `--help` 为准）。 | 场景 | 命令 | |------|------| | 禁言 | `bytedlive control audience mute --activity-id <id> --user-ids <...>` | | 拉黑（⚠️ 黑名单） | `bytedlive control audience block --activity-id <id> --user-ids <...>` | | 踢人（⚠️ 黑名单） | `bytedlive control audience kick --activity-id <id> --user-ids <...>` | ### 9.5 观看页外观（主题切换） 当用户意图是「切换主题/换皮肤/外观设置」时，需做意图识别后再执行： | 主题 | 同义词 | |------|--------| | **暗黑模式** | 暗黑、深色、夜间、黑色主题、dark | | **清爽模式** | 清爽、浅色、简洁、明亮、light | | **经典模式** | 经典、默认、原版、标准 | | **传统节庆** | 节庆、喜庆、春节、新年红、红色主题 | **规则**： - 命中唯一主题 → 正常确认后执行 - 命中多个或未命中 → 反问：`你想切换到哪一种主题？可选：暗黑模式 / 清爽模式 / 经典模式 / 传统节庆。` - 用户仅说「换个主题」等模糊描述 → 视为未命中，走反问 ### 9.6 高频 OpenAPI 调用场景（使用兜底） 对于尚未被 CLI 工具（`control` 子命令）封装的高频业务场景，Agent 应当直接通过 `openapi call` 进行调用。常见高频场景和对应的 Action 如下（请勿编造 CLI 命令）： | 场景分类 | 代表性 Action (API) | 用途说明 | |----------|-------------------|----------| | **直播数据与画像** | `AnalysisUserBehaviorPeopleV2` / `GetAccountUserTrackData` | 获取观看时长分布与观众画像详情 | | **商品运营** | `EnableProduct` / `ExplainProduct` | 商品卡片上架与切换至讲解状态 | | **账号与全局信息** | `GetAccount` / `GetAccountConfig` | 查询账号初始化信息与全局配置 |