beervid-app-cli 0.2.6 → 0.2.7

package/skills/beervid-app-cli/docs/troubleshooting.md

@@ -0,0 +1,468 @@
+# 故障排查指南
+
+本文档帮助你快速定位和解决 BEERVID Open API 集成中的常见问题。
+
+## 目录
+
+1. [认证问题](#认证问题)
+2. [上传问题](#上传问题)
+3. [发布问题](#发布问题)
+4. [轮询问题](#轮询问题)
+5. [查询问题](#查询问题)
+6. [网络问题](#网络问题)
+7. [调试技巧](#调试技巧)
+
+---
+
+## 认证问题
+
+### 错误：401 Unauthorized
+
+**症状：**
+```json
+{
+  "code": 401,
+  "message": "Unauthorized",
+  "success": false
+}
+```
+
+**可能原因：**
+1. `BEERVID_APP_KEY` 未设置或错误
+2. API Key 已过期或被撤销
+3. 请求头 `X-API-KEY` 未正确设置
+
+**解决方案：**
+
+```bash
+# 检查当前配置
+beervid config --show
+
+# 重新设置 API Key
+beervid config --app-key "your-correct-api-key"
+
+# 或使用环境变量
+export BEERVID_APP_KEY="your-correct-api-key"
+```
+
+**验证：**
+```bash
+# 测试 API Key 是否有效
+beervid get-oauth-url --type tt
+```
+
+### 错误：X-API-KEY header is required
+
+**症状：**
+API 返回缺少认证头的错误。
+
+**解决方案：**
+
+检查你的代码是否正确设置了请求头：
+
+```typescript
+const headers = {
+  'X-API-KEY': process.env.BEERVID_APP_KEY,
+  'Content-Type': 'application/json'
+}
+```
+
+---
+
+## 上传问题
+
+### 错误：上传凭证获取失败
+
+**症状：**
+```json
+{
+  "code": 400,
+  "message": "Invalid account type"
+}
+```
+
+**可能原因：**
+- TTS 上传需要 `creatorUserOpenId`，但你传了 `businessId`
+- TT 上传不需要额外参数，但你传了 `creatorUserOpenId`
+
+**解决方案：**
+
+```bash
+# TT 普通上传（不需要额外参数）
+beervid upload --file ./video.mp4
+
+# TTS 上传（需要 creator-id）
+beervid upload --file ./video.mp4 --type tts --creator-id "open_user_abc"
+```
+
+### 错误：文件上传超时
+
+**症状：**
+上传大文件时请求超时。
+
+**解决方案：**
+
+1. **检查文件大小：** TikTok 限制视频大小通常为 4GB
+2. **检查网络连接：** 确保网络稳定
+3. **增加超时时间：** 如果使用代码集成，增加请求超时
+
+```typescript
+// 示例：增加超时时间
+const controller = new AbortController()
+const timeout = setTimeout(() => controller.abort(), 300000) // 5分钟
+
+try {
+  await fetch(uploadUrl, {
+    method: 'POST',
+    body: formData,
+    signal: controller.signal
+  })
+} finally {
+  clearTimeout(timeout)
+}
+```
+
+### 错误：Invalid file format
+
+**症状：**
+```json
+{
+  "code": 400,
+  "message": "Unsupported video format"
+}
+```
+
+**解决方案：**
+
+确保视频格式符合 TikTok 要求：
+- 支持格式：MP4, MOV, MPEG, 3GP, AVI, WebM
+- 推荐格式：MP4 (H.264 编码)
+- 分辨率：最小 720p，推荐 1080p
+- 时长：3秒 - 10分钟
+
+---
+
+## 发布问题
+
+### 错误：businessId not found
+
+**症状：**
+```json
+{
+  "code": 404,
+  "message": "Account not found"
+}
+```
+
+**可能原因：**
+1. `businessId` 或 `creatorUserOpenId` 错误
+2. 账号未完成 OAuth 授权
+3. 账号已被解绑
+
+**解决方案：**
+
+```bash
+# 验证账号是否存在
+beervid get-account-info --type TT --account-id "your-business-id"
+
+# 如果账号不存在，重新获取授权
+beervid get-oauth-url --type tt
+```
+
+### 错误：productTitle too long
+
+**症状：**
+TTS 发布时提示商品标题过长。
+
+**解决方案：**
+
+`productTitle` 最多 30 个字符，需要提前截断：
+
+```typescript
+const productTitle = originalTitle.length > 30
+  ? originalTitle.slice(0, 30)
+  : originalTitle
+```
+
+### 错误：Invalid video URL
+
+**症状：**
+TT 普通发布时提示视频 URL 无效。
+
+**可能原因：**
+1. `videoUrl` 不是可公开访问的 URL
+2. URL 已过期
+3. URL 格式错误
+
+**解决方案：**
+
+确保 `videoUrl` 是上传接口返回的 `fileUrl`：
+
+```bash
+# 先上传，获取 fileUrl
+beervid upload --file ./video.mp4
+
+# 使用返回的 fileUrl 发布
+beervid publish --type normal \
+  --business-id "biz_123" \
+  --video-url "https://cdn.beervid.ai/uploads/xxx.mp4"
+```
+
+---
+
+## 轮询问题
+
+### 问题：轮询一直不返回 PUBLISH_COMPLETE
+
+**症状：**
+轮询状态一直是 `PROCESSING_DOWNLOAD` 或 `SEND_TO_USER_INBOX`。
+
+**可能原因：**
+1. TikTok 平台处理较慢（正常情况）
+2. 视频文件有问题
+3. TikTok 账号有限制
+
+**解决方案：**
+
+1. **增加轮询次数和间隔：**
+
+```bash
+beervid poll-status \
+  --business-id "biz_123" \
+  --share-id "share_abc" \
+  --interval 10000 \
+  --max-polls 60
+```
+
+2. **检查状态详情：**
+
+```typescript
+// 查看完整状态信息
+const status = await pollStatus(businessId, shareId)
+console.log('Status:', status.status)
+console.log('Error:', status.error_code, status.error_message)
+```
+
+3. **常见状态及含义：**
+
+| 状态 | 含义 | 是否正常 |
+|------|------|----------|
+| `PROCESSING_DOWNLOAD` | TikTok 正在下载视频 | 正常，继续等待 |
+| `SEND_TO_USER_INBOX` | 视频已发送到收件箱 | 正常，继续等待 |
+| `PUBLISH_COMPLETE` | 发布完成 | 成功 |
+| `FAILED` | 发布失败 | 失败，检查错误信息 |
+
+### 问题：post_ids 为空
+
+**症状：**
+状态是 `PUBLISH_COMPLETE`，但 `post_ids` 数组为空。
+
+**解决方案：**
+
+这通常表示视频还在处理中，需要继续轮询：
+
+```typescript
+// 正确的完成判断
+const isComplete =
+  status.status === 'PUBLISH_COMPLETE' &&
+  status.post_ids &&
+  status.post_ids.length > 0
+```
+
+---
+
+## 查询问题
+
+### 错误：Only TT accounts can query video data
+
+**症状：**
+使用 TTS 账号查询视频数据时报错。
+
+**解决方案：**
+
+视频数据查询仅支持 TT 账号：
+
+```bash
+# 正确：使用 TT 账号的 businessId
+beervid query-video \
+  --business-id "7281234567890" \
+  --item-ids "7123456789012345678"
+
+# 错误：使用 TTS 账号的 creatorUserOpenId
+# TTS 账号不支持视频数据查询
+```
+
+如果同一达人已经完成了 TTS 授权，但你还想查询该账号的视频数据：
+
+- 还需要额外完成一次 TT 授权
+- 官方当前没有提供 `uno_id` 这类 TT/TTS 强关联字段
+- 当前推荐在你方系统里通过 `account/info` 返回的 `username` 建立 TT/TTS 关联
+- 查数时使用关联后的 TT `businessId`，不要直接使用 TTS `creatorUserOpenId`
+
+### 问题：查询返回的字段不一致
+
+**症状：**
+有时返回 `playCount`，有时返回 `play_count`。
+
+**解决方案：**
+
+API 可能同时返回 camelCase 和 snake_case 字段，建议兼容处理：
+
+```typescript
+const playCount = data.playCount ?? data.play_count ?? 0
+const likeCount = data.likeCount ?? data.like_count ?? 0
+```
+
+---
+
+## 网络问题
+
+### 错误：ECONNREFUSED 或 ETIMEDOUT
+
+**症状：**
+请求无法连接到服务器。
+
+**解决方案：**
+
+1. **检查 BASE_URL 配置：**
+
+```bash
+beervid config --show
+
+# 确保 BASE_URL 正确
+beervid config --base-url "https://open.beervid.ai"
+```
+
+2. **检查网络连接：**
+
+```bash
+# 测试网络连通性
+curl -I https://open.beervid.ai/api/v1/open/thirdparty-auth/tt-url
+```
+
+3. **检查防火墙和代理：**
+
+如果在企业网络环境，可能需要配置代理：
+
+```bash
+export HTTP_PROXY="http://proxy.company.com:8080"
+export HTTPS_PROXY="http://proxy.company.com:8080"
+```
+
+### 错误：SSL certificate problem
+
+**症状：**
+SSL 证书验证失败。
+
+**解决方案：**
+
+```bash
+# 临时禁用 SSL 验证（仅用于调试，生产环境不推荐）
+export NODE_TLS_REJECT_UNAUTHORIZED=0
+
+# 更好的方案：更新系统证书
+# macOS
+brew install ca-certificates
+
+# Ubuntu/Debian
+sudo apt-get update && sudo apt-get install ca-certificates
+```
+
+---
+
+## 调试技巧
+
+### 1. 启用详细日志
+
+```bash
+# 设置环境变量启用调试模式
+export DEBUG=beervid:*
+
+# 运行命令查看详细日志
+beervid upload --file ./video.mp4
+```
+
+### 2. 使用 --verbose 标志
+
+```bash
+# 如果 CLI 支持 verbose 模式
+beervid publish-tt-flow \
+  --business-id "biz_123" \
+  --file ./video.mp4 \
+  --verbose
+```
+
+### 3. 检查原始响应
+
+在代码中打印完整响应：
+
+```typescript
+try {
+  const response = await openApiPost('/api/v1/open/tiktok/video/publish', data)
+  console.log('Full response:', JSON.stringify(response, null, 2))
+} catch (error) {
+  console.error('Error details:', error)
+}
+```
+
+### 4. 使用 curl 测试 API
+
+```bash
+# 测试获取授权链接
+curl -X GET \
+  -H "X-API-KEY: your-api-key" \
+  https://open.beervid.ai/api/v1/open/thirdparty-auth/tt-url
+
+# 测试账号信息查询
+curl -X POST \
+  -H "X-API-KEY: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{"accountType":"TT","accountId":"7281234567890"}' \
+  https://open.beervid.ai/api/v1/open/account/info
+```
+
+### 5. 检查 CLI 版本
+
+```bash
+# 确保使用最新版本
+npm list -g beervid-app-cli
+
+# 更新到最新版本
+npm update -g beervid-app-cli
+```
+
+### 6. 清理本地配置
+
+```bash
+# 查看配置文件位置
+ls -la ~/.beervid/
+
+# 删除配置文件重新开始
+rm -rf ~/.beervid/config.json
+
+# 重新配置
+beervid config --app-key "your-api-key"
+```
+
+---
+
+## 常见错误码速查
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 400 | 请求参数错误 | 检查参数格式和必填字段 |
+| 401 | 认证失败 | 检查 API Key 是否正确 |
+| 403 | 权限不足 | 检查账号权限或 API Key 权限 |
+| 404 | 资源不存在 | 检查 ID 是否正确 |
+| 429 | 请求过于频繁 | 降低请求频率，参考限流说明 |
+| 500 | 服务器错误 | 稍后重试，或联系技术支持 |
+
+---
+
+## 仍然无法解决？
+
+1. **查看完整 API 文档：** [references/api-reference.md](../references/api-reference.md)
+2. **查看 FAQ：** [FAQ.md](../FAQ.md)
+3. **查看示例代码：** [example/](../example/)
+4. **提交 Issue：** https://github.com/Lupeiwen0/beervid-app-cli/issues
+5. **联系技术支持：** support@beervid.ai

package/skills/beervid-app-cli/example/express/README.md

@@ -56,3 +56,9 @@ curl -X POST http://localhost:3000/api/publish/tts \
   -H "Content-Type: application/json" \
   -d '{"creatorId": "open_user_abc", "videoFileId": "vf_abc123", "productId": "prod_789", "productTitle": "Widget"}'
 ```
+
+## 账号关联提醒
+
+- 如果同一达人既要做 TTS 挂车发布，又要查询视频数据，需要分别完成 TTS 和 TT 授权。
+- 官方当前没有提供 `uno_id` 这类 TT/TTS 关联字段。
+- 这个示例更推荐在 OAuth 回调后的 `account/info` 同步阶段持久化 `username`，并在你方数据库里用它建立 TT/TTS 关联。

package/skills/beervid-app-cli/example/express/server.ts

@@ -182,10 +182,26 @@ app.get('/oauth/tts', async (_req, res) => {
 
 // OAuth 回调处理
 app.get('/oauth/callback', async (req, res) => {
-  const ttAbId = req.query['ttAbId'] as string | undefined
-  const ttsAbId = req.query['ttsAbId'] as string | undefined
+  const stateParam = req.query['state'] as string | undefined
 
-  // 生产环境：① 验证 state token ② 一次性消费检查
+  if (!stateParam) {
+    res.status(400).json({ error: '缺少 state 参数' })
+    return
+  }
+
+  // 回调字段在 state JSON 内部
+  let stateObj: Record<string, unknown>
+  try {
+    stateObj = JSON.parse(stateParam) as Record<string, unknown>
+  } catch {
+    res.status(400).json({ error: 'state 不是合法 JSON' })
+    return
+  }
+
+  const ttAbId = stateObj['ttAbId'] as string | undefined
+  const ttsAbId = stateObj['ttsAbId'] as string | undefined
+
+  // 生产环境：① 验证 state 中你方追加的自定义安全字段 ② 一次性消费检查
   // 详见 docs/oauth-callback.md
 
   if (!ttAbId && !ttsAbId) {
@@ -209,6 +225,8 @@ app.get('/oauth/callback', async (req, res) => {
   openApiPost('/api/v1/open/account/info', { accountType, accountId })
     .then((info) => {
       const existing = accountStore.get(accountId) ?? {}
+      // 生产环境建议在这里把 username 持久化，并作为当前推荐的 TT/TTS 关联键。
+      // 官方没有提供 uno_id 这类可直接关联 TT/TTS 的稳定字段。
       accountStore.set(accountId, { ...existing, ...info })
       console.log(`[异步] 账号信息已同步: ${accountId}`)
     })
@@ -300,8 +318,8 @@ app.post('/api/publish/tts', async (req, res) => {
   }
 
   try {
-    // 商品标题最多 29 字符
-    const normalizedTitle = productTitle.slice(0, 29)
+    // 商品标题最多 30 字符
+    const normalizedTitle = productTitle.slice(0, 30)
 
     // 挂车发布（不重试——发布操作非幂等）
     const publishResult = await openApiPost<{ videoId: string }>(

package/skills/beervid-app-cli/example/nextjs/README.md

@@ -52,3 +52,9 @@ npm run dev
 - `lib/beervid-client.ts` — 服务端 BEERVID API 客户端封装
 - `app/api/` — API Route Handlers
 - `app/page.tsx` — 简单首页展示 API 调用方式
+
+## 账号关联提醒
+
+- TTS 账号只能用于挂车发布和商品查询，不能直接查视频数据。
+- 如果同一达人还要查视频数据，需要额外完成 TT 授权。
+- 官方当前没有提供 `uno_id` 这类 TT/TTS 关联字段，建议在 OAuth 回调后调用 `account/info`，并用返回的 `username` 建立本地关联。

package/skills/beervid-app-cli/example/nextjs/app/api/oauth/callback/route.ts

@@ -1,25 +1,41 @@
 /**
- * GET /api/oauth/callback?ttAbId=xxx 或 ?ttsAbId=xxx
- * OAuth 回调处理
+ * GET /api/oauth/callback?state={"ttAbId":"xxx",...}
+ * OAuth 回调处理 — 回调字段在 state JSON 内部
  */
 import { NextRequest, NextResponse } from 'next/server'
 import { openApiPost } from '@/lib/beervid-client'
 
 export async function GET(request: NextRequest) {
-  const ttAbId = request.nextUrl.searchParams.get('ttAbId')
-  const ttsAbId = request.nextUrl.searchParams.get('ttsAbId')
+  const stateParam = request.nextUrl.searchParams.get('state')
 
-  // 生产环境：① 验证 state token ② 一次性消费检查
+  if (!stateParam) {
+    return NextResponse.json({ error: '缺少 state 参数' }, { status: 400 })
+  }
+
+  // 回调字段在 state JSON 内部
+  let stateObj: Record<string, unknown>
+  try {
+    stateObj = JSON.parse(stateParam) as Record<string, unknown>
+  } catch {
+    return NextResponse.json({ error: 'state 不是合法 JSON' }, { status: 400 })
+  }
+
+  const ttAbId = stateObj['ttAbId'] as string | undefined
+  const ttsAbId = stateObj['ttsAbId'] as string | undefined
+
+  // 生产环境：① 验证 state 中你方追加的自定义安全字段 ② 一次性消费检查
   // 详见 docs/oauth-callback.md
 
   if (!ttAbId && !ttsAbId) {
-    return NextResponse.json({ error: '缺少 ttAbId 或 ttsAbId 参数' }, { status: 400 })
+    return NextResponse.json({ error: 'state 中缺少 ttAbId 或 ttsAbId' }, { status: 400 })
   }
 
   const accountId = (ttAbId ?? ttsAbId)!
   const accountType = ttAbId ? 'TT' : 'TTS'
 
   // 异步拉取账号详情（不阻塞回调响应）
+  // 生产环境建议在这里把 username 写入数据库，并作为当前推荐的 TT/TTS 关联键。
+  // 官方没有提供 uno_id 这类可直接关联 TT/TTS 的稳定字段。
   openApiPost('/api/v1/open/account/info', { accountType, accountId }).catch((err) => {
     console.error('[异步] 账号信息同步失败:', (err as Error).message)
   })

package/skills/beervid-app-cli/example/nextjs/app/api/publish/tts/route.ts

@@ -8,7 +8,7 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { openApiPost } from '@/lib/beervid-client'
 
-const MAX_PRODUCT_TITLE_LENGTH = 29
+const MAX_PRODUCT_TITLE_LENGTH = 30
 
 export async function POST(request: NextRequest) {
   const body = await request.json()
@@ -28,7 +28,7 @@ export async function POST(request: NextRequest) {
   }
 
   try {
-    // 商品标题最多 29 字符，超出自动截断
+    // 商品标题最多 30 字符，超出自动截断
     const normalizedTitle = productTitle.slice(0, MAX_PRODUCT_TITLE_LENGTH)
     const wasTruncated = normalizedTitle !== productTitle
 

package/skills/beervid-app-cli/example/standard/README.md

@@ -49,3 +49,9 @@ npx tsx query-products.ts --creator-id open_user_abc
 | `tts-publish-flow.ts` | ⭐ TTS 完整发布流程最佳实践（含商品筛选策略） |
 | `get-oauth-url.ts` | 获取 TT/TTS OAuth 授权 URL |
 | `query-products.ts` | TTS 商品查询与分页遍历 |
+
+## 账号关联提醒
+
+- TTS 账号不能直接查询视频数据。
+- 如果同一达人既要跑 `tts-publish-flow.ts`，又要查视频数据，还需要额外授权 TT 账号。
+- 官方当前没有提供 `uno_id` 可直接关联 TT/TTS，示例项目当前推荐使用 `account/info` 返回的 `username` 做关联。

package/skills/beervid-app-cli/example/standard/tts-publish-flow.ts

@@ -55,7 +55,7 @@ interface ProductPageData {
   nextPageToken?: string | null
 }
 
-const MAX_PRODUCT_TITLE_LENGTH = 29
+const MAX_PRODUCT_TITLE_LENGTH = 30
 
 // ─── 辅助函数 ───────────────────────────────────────────────────────────────