0. Startup tracking
Each time this Skill is enabled, first best-effort execute the tracking script once, then continue processing the user request; if the script fails, times out, or the interface is unreachable, the task must not be interrupted.
node tools/report_usage.js
The script automatically identifies the Agent based on the Skill installation path(e.g., ~/.cursor/skills/ → cursor，~/.codex/skills/ → codex）。Prohibitedto hardcode --agent codexwhen the current environment is not identified. Only in a custom installation directory (skills add --target) or when automatic identification fails, explicitly pass --agent cursor|codex|claude-code|trae|openclaw; if it still cannot be identified, use unknown. This script initiates a POST report via Node/CLI and does not support cross-origin browser page calls.
1. Scope of application
When to use
This Skill is triggered when the user's intent involves any of the following scenarios:
- Live room lifecycle management and control: create/delete live rooms, query the list, modify basic configuration (name/time/mode), control status (start broadcasting/lock/restore/end broadcasting/ban)
- Live data analysis and viewer profiles: query the live room viewing duration distribution statistics, pull viewer user profile details for insights
- Product library and card operations: during the live broadcast, list product cards, switch the explaining state, query product status or statistical data
- Comment governance and content analysis: send/query/poll comments, delete user messages, configure sensitive words, or obtain comment analysis results (including large model analysis)
- Account basic information and media asset library maintenance: obtain account configuration/global benefit quota information, batch delete videos from the media asset library, check document library capacity
- Marketing interaction and co-streaming control: create interactive tools such as live room coupons, manage the collaborative status of web live co-streaming
- System messages: push customized system messages to the live room
- Viewer management and control: mute, block, or kick out viewers
- Watch page appearance: switch themes (dark/fresh/classic/traditional festival)
- OpenAPI fallback: for other enterprise live capability control needs not explicitly covered above, implement them by calling the enterprise live OpenAPI
When NOT to use
- Underlying media issues such as stream pushing/pulling/encoding → does not belong to this Skill
- WebSDK integration / mini program room entry / viewer-side Token → use byted-livesaas-dev Skill
- Account billing / package management → guide the user to the Volcano Engine console
- Non-enterprise live products(e.g., video-on-demand, RTC) → does not belong to this Skill
2. Architecture overview
用户意图 → Skill（路由 + 约束） → Agent 生成 CLI 命令 → bytedlive CLI 执行
- Skill layer: defines the mapping from intent to CLI subcommands + execution constraints (excluding executable scripts)
- Agent layer: assembles the
bytedlivecommand and executes it according to the routing table and constraints - CLI layer: encapsulates credential management, signing, request sending, confirmation interaction, and JSON results
Sole execution entry point: all commands must go through the
bytedliveCLI; writing curl by hand or making undocumented HTTP requests is prohibited.
3. First-time use onboarding and dependency installation (Onboarding)
Trigger condition: when this Skill is activated for the first time (that is, the first time the user sends a request matching the trigger words in §1), the Agent mustfirst execute the onboarding process (including automatic CLI installation and credential configuration), and then handle the user's actual request.
3.1 Onboarding check and installation process
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 installation failure guidance template
When the automatic installation in Step 0 fails (such as missing Node environment, no permissions, etc.), the Agent mustoutput the following message to the user:
⚠️ Missing environment dependencies
Sorry, I tried to automatically install the underlying dependency tool
bytedlive-clifor you but failed (usually because Node.js / npm is not installed in the current environment or global write permission is missing).Please run the following command in your local terminal to install manually:
npm i -g bytedlive-cliAfter installation is complete, run
bytedlive --versionto verify, and reply to me with "Installed", and I will take you to the next configuration step.
3.3 AK/SK local configuration guidance template
When it is detected that credentials are not configured, the Agent mustoutput the following message (the wording may be slightly adjusted according to context, but the core information must not be omitted):
👋 Welcome to the Enterprise Live Stream Control Skill!
It has been detected that you have not yet bound an Enterprise Live account, and you need to complete configuration once first.
Please run the following command in yourlocal terminal, and enter Access Key（AK） and Secret Key（SK）：
bytedlive openapi set-credentials
- Obtaining path:Volcengine Console → Key Management
⚠️ Do not send AK/SK into the conversation. The CLI will cache the key locally
~/.bytedlive/openapi-credentials.json, and subsequent commands will automatically read it.After successful configuration, reply to me with "Configured", and I will continue handling the previous request.
3.4 Credential writing and verification
The user executes in the local terminal:
bytedlive openapi set-credentials
| Verification result | Agent behavior |
|---|---|
Success (set-credentials returns ok) |
Output ✅ 账号绑定成功！, then continue handling the user's original request |
| Failure (401/403/signature error) | Output ❌ 凭证验证失败，请检查 AK/SK 是否正确。, guide the user to re-execute in the local terminal bytedlive openapi set-credentials |
| Failure (network error) | Output ⚠️ 网络连接异常，请稍后重试。 |
3.5 Onboarding state memory
- After credential verification passes,do not repeat onboarding within this session
- Credentials have been persisted to
~/.bytedlive/openapi-credentials.json, and subsequent sessions will automatically load them without repeated configuration - If credential invalidation (401/403) occurs in subsequent operations, handle it according to the error recovery strategy in §7, and do not go through the complete onboarding again
3.6 Quick capability overview (attached after verification passes)
After credential verification passes, in the confirmation messageappend a capability overview, helping users quickly understand what can be done:
✅ Account linked successfully! Here are the things I can help you with:
Capability Example Command 🎬 Live room management "Create a live room for 3 PM tomorrow" / "View recent live rooms" 💬 Comment interaction "Help me post a comment in the live room" / "View recent bullet comments" 📢 System messages "Post a system announcement" 🚫 Viewer control "Mute a certain user" / "Kick out the troublemakers" 📊 Data and profiles "Check live room view duration" / "Get viewer profile details" 🛒 Products and cards "Put the product card on the shelf" / "Switch to explanation mode" 🎨 Viewing page appearance "Switch to dark mode" 🔧 OpenAPI "Call GetActivityAPI to check live room details" Now I'll help you handle the request you just made 👇
4. Credentials and Base URL
| Item | Rule |
|---|---|
| AK/SK | Required. Before performing any OpenAPI operation, you must first execute bytedlive openapi check-credentials --pretty. If local cache is available, reuse it directly; if not available, only guide the user to run it in the local terminal bytedlive openapi set-credentials, and do not ask for AK/SK in the conversation |
| Base URL | Fixed https://livesaas.volcengineapi.com/，do not ask the user. Override via BYTEDLIVE_BASE_URL only when the user proactively provides a dedicated endpoint |
| Cache priority | Command line/environment variables → session cache → local file ~/.bytedlive/openapi-credentials.json |
| Credential expiration | On 401/403/signature errors, guide the user to run locally bytedlive openapi clear-credentials then execute bytedlive openapi set-credentials |
5. Security mechanism: confirmation and blacklist
5.1 Humanized business confirmation (required for all write operations)
- Assemble candidate command (Prepare only in the background, and absolutely never show the user the specific CLI command, code, or JSON parameters）。
- Confirm with the user in "plain language"business intent, for example: "I am about to create a live room named 'Test Check-in' for you, at 3 PM today. Confirm you want to create it?"
- Execute only after the user explicitly agrees.
5.2 Blacklist secondary confirmation (high-risk operations)
When the following operations are matched, after the regular confirmation passes,confirm once more：
| Blacklist operation | Example command |
|---|---|
All deletion types (including delete/remove/del/删除） |
bytedlive control room ...(deletion-related) |
| Viewer kick-out | bytedlive control audience kick ... |
| Viewer ban/block | bytedlive control audience block ... |
The secondary confirmation wording must also be humanized:您正在进行高风险操作（例如：踢出某个观众），这可能会影响观众体验或导致数据丢失。请最后确认一次是否继续？
6. Parameter acquisition guidance (what the Agent should do when parameters are missing)
| Missing parameter | What the Agent should do |
|---|---|
--activity-id |
First execute bytedlive control room list to query recent live rooms and let the user confirm the target |
--user-ids(viewer control) |
Ask the user to provide the target user identifier, or guide them to query the comment list to obtain it |
| Live room image assets (cover/corner badge/decorative images, etc.) | Directly uploading images to configure a live room is not supported. Prioritize having the customer provide an accessible image URL and continue with the subsequent configuration process; if the customer cannot provide a URL, guide the customer to directly use the Volcengine console to complete the upload and configuration (no callback process) |
| AK/SK | First execute bytedlive openapi check-credentials --pretty; if there is no cache or verification fails, guide the user to execute locally bytedlive openapi set-credentials, do not ask for it in the conversation |
| Uncertain flag | Execute bytedlive control <子命令> --help to view help |
7. Error recovery strategy
7.1 Answering and execution constraints (mandatory)
- Evidence priority: answers and execution must be based first on the processes already defined in this Skill and existing CLI capabilities (
bytedlive control/openapi) as well as the local knowledge base/reference documentation; do not skip existing capabilities and guess directly. - Supplementary verification on the official website: when the existing knowledge base, CLI help, and local rules cannot solve the problem or cannot confirm parameters/behavior, you must search the Volcengine Documentation Center for the corresponding Enterprise Live documentation and reply only after supplementing the evidence accordingly.
- Fallback for unachievable/unconfirmable: if the capability still cannot be implemented after exhausting local capabilities and official website searches, you must clearly tell the user "this capability is currently unavailable" or "this question cannot currently be answered accurately," and explain the blocker; it is prohibited to fabricate interfaces, versions, fields, results, or promises that it is "definitely feasible."
| Error type | Agent handling method |
|---|---|
missing openapi credentials |
Guide the user to execute locally bytedlive openapi set-credentials |
| 401 / 403 / signature error | The credential may be expired or incorrect; prompt the user to execute locally bytedlive openapi clear-credentials and then execute bytedlive openapi set-credentials |
InvalidActionOrVersion / Action does not exist |
Perform large model silent self-healing according to the process in §11. If it fails, use online search to find the real version number and retry. During this period, reassure the user and never throw out raw, obscure error information. |
| Parameter error / missing required field | Check whether the field names match the official documentation (refer to §10 field name specifications), complete them, and retry |
| Network timeout | Retry once; if it still fails, inform the user |
| Unknown error | Check Volcengine Enterprise Live documentation; if it cannot be resolved, suggest submitting a ticket |
8. Global options
| Option | Effect |
|---|---|
--pretty |
JSON pretty output |
--non-interactive |
Disable interaction; fail directly if parameters or credentials are missing |
-y / --yes |
Skip pre-operation confirmation (credentials must still be valid) |
9. Command routing table
9.1 Live room (bytedlive control room）
| Scenario | Command | API | Key parameters |
|---|---|---|---|
| Create live room | bytedlive control room create |
CreateActivityAPIV2 | --name、--start/--live-time、--end/--end-time |
| Live room list | bytedlive control room list |
ListActivityAPI | --page/--page-size、--name、--status、--sort-by/--sort-order(supports desc/asc or Desc/Asc） |
| Read basic configuration | bytedlive control room config get --activity-id <id> |
GetActivityBasicConfigAPI | |
| Update basic configuration | bytedlive control room config update --activity-id <id> |
UpdateActivityBasicConfigAPI | --name、--start、--end、--view-url-path、--activity-type、--live-mode |
| Set activity status | bytedlive control room status set --activity-id <id> |
UpdateActivityStatusAPI | --op(3/4/5) or --action recover|lock|release |
Mandatory reply template for successful live room creation
After a live room is created successfully, the Agent's reply must include the following three types of addresses (provided by ActivityId dynamic concatenation), making it convenient for users to directly enter the console for operations and web-based streaming:
- Console URL:
https://console.volcengine.com/livesaas/liveManagement/<ActivityId> - Web streaming URL:
https://console.volcengine.com/livesaas/webpush/micromode/<ActivityId> - Viewing page URL: the API returns
ViewUrl(if any)
Recommended reply template:
直播间已创建成功。
- 直播间名称：<Name>
- ActivityId：<ActivityId>
- 状态：<StatusDesc>
- 控制台地址：https://console.volcengine.com/livesaas/liveManagement/<ActivityId>
- 网页开播地址：https://console.volcengine.com/livesaas/webpush/micromode/<ActivityId>
- 观看页地址：<ViewUrl>
9.2 Comments (bytedlive control comment）
| Scenario | Command | API | Key parameters |
|---|---|---|---|
| Send comment | bytedlive control comment send --activity-id <id> --comment <文本> |
PresenterChatAPIV2 | Optional --audience-group-id、--top-status |
| Comment list | bytedlive control comment list --activity-id <id> |
ListActivityChatAPI | Optional pagination, time,--chat-type、--top-status |
| Poll comments | bytedlive control comment poll --activity-id <id> |
PollingChatAPI | Optional --last-chat-id、--page-size、--start-time/--end-time |
9.3 System messages (bytedlive control system-message）
| Scenario | Command | API | Key parameters |
|---|---|---|---|
| Send system message | bytedlive control system-message send --activity-id <id> --content <文本> |
SendCustomSystemMessageAPI | Optional --message-type |
9.4 Audience control (bytedlive control audience）
All require --activity-id. User identifiers commonly use --user-ids, and in some scenarios --cookies or --external-user-idsmay be used (subject to --help ).
| Scenario | Command |
|---|---|
| Mute | bytedlive control audience mute --activity-id <id> --user-ids <...> |
| Block (⚠️ blacklist) | bytedlive control audience block --activity-id <id> --user-ids <...> |
| Kick (⚠️ blacklist) | bytedlive control audience kick --activity-id <id> --user-ids <...> |
9.5 Viewing page appearance (theme switching)
When the user's intent is "switch theme/change skin/appearance settings", intent recognition must be performed before execution:
| Theme | Synonyms |
|---|---|
| Dark mode | Dark, dark color, nighttime, black theme, dark |
| Fresh mode | Fresh, light color, concise, bright, light |
| Classic mode | Classic, default, original, standard |
| Traditional festival | Festival, festive, Spring Festival, New Year red, red theme |
Rules：
- Matches a unique theme → execute after normal confirmation
- Matches multiple or none → ask back:
你想切换到哪一种主题？可选：暗黑模式 / 清爽模式 / 经典模式 / 传统节庆。 - If the user says only vague descriptions such as "change the theme" → treat as no match and ask back
9.6 High-frequency OpenAPI call scenarios (fallback usage)
For high-frequency business scenarios that have not yet been encapsulated by CLI tools (control subcommands), the Agent should directly call through openapi call . Common high-frequency scenarios and corresponding Actions are as follows (do not fabricate CLI commands):
| Scenario category | Representative Action (API) | Purpose description |
|---|---|---|
| Live streaming data and profiles | AnalysisUserBehaviorPeopleV2 / GetAccountUserTrackData |
Obtain viewing duration distribution and audience profile details |
| Product operations | EnableProduct / ExplainProduct |
List product cards and switch to explanation status |
| Account and global information | GetAccount / GetAccountConfig |
Query account initialization information and global configuration |
| Media assets and document library | DeleteMediaLibraryVideoAPI / CheckDocLibStorageCapacity |
Batch delete replay videos and query document capacity |
| Comment governance and analysis | DeleteUserMessage / GetAccountCommentAnalysisLLMConsole |
Delete a single comment or obtain large model comment analysis |
| Lines and push/pull streams | ActivityLines / ActivityLinesPullInfoConsole |
Query live room lines and pull stream configuration details |
| Interaction and collaboration | CreateActivityCouponsConsole / CloseLinkWebCast |
Create coupon interactions, close web co-streaming |
9.7 OpenAPI fallback (bytedlive openapi call）
When control When the subcommand does not cover the required capability (such as the high-frequency scenarios in 9.6), use openapi call to directly call any Action.
bytedlive openapi call --action <ActionName> [--api-version <Version>] \
[--method POST] [--body '...'] [--body-file file.json] [--query '...']
Version resolution priority：
- Command line
--api-versionexplicitly specified - Static table
openapiActionVersions.jsonconfiguration in - Fallback default
2020-06-01（serviceDefaultVersion） - When the response appears to have a Version error → the CLI automatically fetches the documentation HTML, parses it, and retries once (can be disabled with
--no-doc-version-retry)
Query Version：
查静态表：
bytedlive openapi get-version --action <ActionName> --pretty
尝试从文档页拉取：
bytedlive openapi get-version --action <ActionName> --refresh-doc --pretty
10. API field name conventions (mandatory)
Body and Query field namesmust be exactly consistent with the official Volcengine documentation, and must not be used from memory.
| Scenario | ❌ Wrong | ✅ Correct | Description |
|---|---|---|---|
| Create/update/query live room | ActivityName |
Name |
Live room name field |
When encountering "parameter error" type errors: first check whether the field names are consistent with the documentation, refer to API documentation。
11. OpenAPI call failure handling (large model silent self-healing mechanism)
When calling OpenAPI and encountering InvalidActionOrVersion(interface version error or not found), missing parameters, or other errors,never throw JSON or raw error information directly to ordinary users. The Agent must silently execute the following self-healing process in the background, and during this time soothe the user in natural language (for example: "The interface version has been updated. I am matching the latest protocol for you, please wait..."):
- Try CLI automatic parsing: execute
bytedlive openapi get-version --action <X> --refresh-doc --pretty。 - Large model online search (key fallback): If CLI parsing fails (fails to parse the Version from a single HTTP response, or still returns an error), the Agent must directly use its built-in web search tool, search for
"火山引擎 <Action名称> API 文档"(for example: "Volcengine SendCheckIn API"). Extract the correct "interface version" from the latest official documentation (for example:2023-01-01or2023-08-01）。 - Retry with specified version: After obtaining the correct Version, add
--api-version <查到的真实版本号>to the original command and re-initiateopenapi call。 - Business-equivalent alternative: If multiple attempts still fail, then apologize to the user in plain language, and ask whether to use an interface from another function as a substitute (for example, if the detail interface does not work, use the List interface with filtering instead).
Bottom line: The large model is prohibited from fabricating interface version numbers and parameter fields from memory; make the greatest effort to intercept development-perspective errors in the background, and show ordinary users only business-level progress and results.
12. Typical workflow examples
Example 0: First use (Onboarding)
用户：帮我创建一个直播间
Agent：
1. Skill 首次激活 → 执行 onboarding 流程
2. 检查发现未安装 CLI → 引导安装 `npm i -g bytedlive-cli` 并执行 `bytedlive --version` 验证
3. 执行 bytedlive openapi check-credentials --pretty
4. 失败（无凭证）→ 引导用户本地执行 bytedlive openapi set-credentials
5. 用户回复已配置 → 再次 check-credentials → 验证通过
6. 输出能力概览 + 继续处理"创建直播间"请求
Example 1: Create live room
用户：帮我创建一个明天下午3点开始的直播间，名字叫"产品发布会"
Agent：
1. 执行 bytedlive openapi check-credentials --pretty → 无缓存则引导本地 set-credentials
2. 组装命令：bytedlive control room create --name "产品发布会" --start "2026-04-11 15:00:00"
3. 向用户拟人化确认："我将为您创建名为『产品发布会』的直播间，时间是明天下午3点，确认执行吗？" → 确认后执行
4. 成功后按模板返回关键信息，并附：
- 控制台地址：https://console.volcengine.com/livesaas/liveManagement/<ActivityId>
- 网页开播地址：https://console.volcengine.com/livesaas/webpush/micromode/<ActivityId>
Example 2: Mute a viewer
用户：把用户 user_123 禁言
Agent：
1. 确认 activity-id → 若无则先 room list 查询
2. 组装命令：bytedlive control audience mute --activity-id <id> --user-ids user_123
3. 向用户拟人化确认："请确认是否需要禁言指定用户？" → 用户同意
4. 非黑名单操作，直接执行
Example 3: Kick out a viewer (blacklist operation)
用户：把用户 user_456 踢出直播间
Agent：
1. 确认 activity-id
2. 组装命令：bytedlive control audience kick --activity-id <id> --user-ids user_456
3. 向用户拟人化确认："请确认是否需要踢出用户？" → 用户同意
4. 命中黑名单 → 二次确认："踢出用户属于高风险操作，可能会影响观众体验。请最后确认一次是否继续？"
5. 用户再次确认 → 执行
Example 4: OpenAPI fallback call and version self-healing
用户：帮我配置个签到
Agent：
1. control 子命令无此能力 → 走 openapi call (SendCheckIn 等)
2. 执行报错：`InvalidActionOrVersion`
3. 拦截报错，安抚用户："发现接口版本更新，我正在检索最新配置，请稍候..."
4. 联网搜索 "火山引擎 SendCheckIn API 文档"，发现版本是 2023-08-01
5. 组装新命令并确认："我将为您配置签到，请确认是否执行？"
6. 执行：bytedlive openapi call --action SendCheckIn --api-version 2023-08-01 ...
13. Self-test
bytedlive control test
In an environment where bytedlive CLI is installed, run; the command automatically discovers and executes matching *.test.js(if no usable test cases are available, it will skip and prompt).