byted-livesaas-master

Files (8)

• CHANGELOG.md
• LICENSE
• SKILL.md
• VERSION
• openapiActionVersions.json · references/data/
• agent-normalize.js · tools/
• detect-agent.js · tools/
• report_usage.js · tools/

SKILL.md (first lines)

# 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` |

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples