beervid-app-cli 0.2.4 → 0.2.6

package/README.md

@@ -30,28 +30,39 @@ node dist/cli.mjs --help
 node dist/cli.mjs config --show
 ```
 
-### 在 Claude Code / Codex / Antigravity 中使用
+### 在 Claude Code / Codex / Antigravity 中使用（以下说明面向 AI Agent）
 
-如果你希望在 Claude Code、Codex 等支持 Skill 的工具中直接调用本项目，除了通过 npm 安装 CLI 之外，还需要把 Skill 相关文件复制到你自己的 skills 目录下。
+#### 方式一：通过 `npx skills add` 安装（推荐）
 
-需要复制的内容：
+```bash
+npx skills add Lupeiwen0/beervid-app-cli
+```
+
+安装后 Skill 会自动注册到你的 skills 目录中，Claude Code 等 Agent 即可发现和调用。
+
+#### 方式二：手动安装
 
-- `SKILL.md`
-- `references/`
-- `docs/`
-- `example/`
+如果你是 Claude Code、Codex、Antigravity，或任何支持 Skill 的 AI Agent，请严格按下面规则执行：
 
-建议在你的 skills 目录中保持如下结构：
+- 用户把 GitHub 仓库链接发给你，**不等于**这个 Skill 已经安装到你的 skills 目录中。
+- 只有当 `skills/beervid-app-cli/` 目录被完整安装到你的 skills 目录后，才算这个 Skill 可用。
+
+你必须先把以下目录复制到你自己的 skills 目录中：
 
 ```text
-beervid-app-cli/
+skills/beervid-app-cli/
   SKILL.md
   references/
   docs/
   example/
 ```
 
-这样工具在加载 `SKILL.md` 时，才能继续访问本项目附带的 API 参考、落地文档和示例工程。
+安装完成后，你应从 skills 目录中的 `SKILL.md` 加载本 Skill，而不是只读取仓库根目录里的 `README.md` 或 `package.json`。
+
+对 AI Agent 来说，应这样区分：
+
+- 目标是使用 CLI：安装 npm 包即可。
+- 目标是使用 Skill：必须额外安装 Skill 文件；仓库链接本身不完成这一步。
 
 ## 配置
 
@@ -106,7 +117,7 @@ beervid publish-tts-flow --creator-id open_user_abc --file ./video.mp4 --interac
 beervid publish-tts-flow --creator-id open_user_abc --file ./video.mp4 --product-id prod_123 --product-title "Widget"
 ```
 
-详细用法见 [SKILL.md](./SKILL.md)。完整 API 参考见 [references/api-reference.md](./references/api-reference.md)。
+详细用法见 [SKILL.md](./skills/beervid-app-cli/SKILL.md)。完整 API 参考见 [references/api-reference.md](./skills/beervid-app-cli/references/api-reference.md)。
 
 ## 落地文档
 
@@ -114,11 +125,11 @@ beervid publish-tts-flow --creator-id open_user_abc --file ./video.mp4 --product
 
 | 文档 | 内容 |
 |------|------|
-| [数据表字段建议](./docs/database-schema.md) | accounts/videos/products 表结构设计 |
-| [OAuth 回调存储建议](./docs/oauth-callback.md) | State Token 防 CSRF、回调持久化、异步头像同步 |
-| [TT 轮询任务建议](./docs/tt-poll-task.md) | 阶梯递增轮询间隔、Cron/队列三层保障 |
-| [TTS 商品缓存建议](./docs/tts-product-cache.md) | 全量拉取、缓存过期、图片 URL 解析 |
-| [失败重试与幂等建议](./docs/retry-and-idempotency.md) | 各 API 幂等性分析、指数退避、幂等键设计 |
+| [数据表字段建议](./skills/beervid-app-cli/docs/database-schema.md) | accounts/videos/products 表结构设计 |
+| [OAuth 回调存储建议](./skills/beervid-app-cli/docs/oauth-callback.md) | State Token 防 CSRF、回调持久化、异步头像同步 |
+| [TT 轮询任务建议](./skills/beervid-app-cli/docs/tt-poll-task.md) | 阶梯递增轮询间隔、Cron/队列三层保障 |
+| [TTS 商品缓存建议](./skills/beervid-app-cli/docs/tts-product-cache.md) | 全量拉取、缓存过期、图片 URL 解析 |
+| [失败重试与幂等建议](./skills/beervid-app-cli/docs/retry-and-idempotency.md) | 各 API 幂等性分析、指数退避、幂等键设计 |
 
 ## 示例工程
 
@@ -126,6 +137,6 @@ beervid publish-tts-flow --creator-id open_user_abc --file ./video.mp4 --product
 
 | 示例 | 场景 | 入口 |
 |------|------|------|
-| [Standard](./example/standard/) | 纯 Node.js 脚本，快速验证 | `npx tsx tt-publish-flow.ts` |
-| [Express](./example/express/) | Express 后端服务，含 OAuth 回调 | `npx tsx server.ts` |
-| [Next.js](./example/nextjs/) | Next.js App Router API Route | `npm run dev` |
+| [Standard](./skills/beervid-app-cli/example/standard/) | 纯 Node.js 脚本，快速验证 | `npx tsx tt-publish-flow.ts` |
+| [Express](./skills/beervid-app-cli/example/express/) | Express 后端服务，含 OAuth 回调 | `npx tsx server.ts` |
+| [Next.js](./skills/beervid-app-cli/example/nextjs/) | Next.js App Router API Route | `npm run dev` |

package/dist/cli.mjs

@@ -1130,7 +1130,7 @@ function register10(cli2) {
 
 // src/cli.ts
 var cli = cac("beervid");
-var cliVersion = true ? "0.2.4" : pkg.version;
+var cliVersion = true ? "0.2.6" : pkg.version;
 register10(cli);
 register(cli);
 register2(cli);

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "beervid-app-cli",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "BEERVID App CLI — TikTok video publish, account auth, and data query",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lupeiwen0/beervid-app-cli"
+  },
   "type": "module",
   "engines": {
     "node": ">=20.0.0"
@@ -11,11 +15,7 @@
   },
   "files": [
     "dist/",
-    "agents/",
-    "references/",
-    "docs/",
-    "example/",
-    "SKILL.md",
+    "skills/",
     "README.md"
   ],
   "scripts": {

package/{SKILL.md → skills/beervid-app-cli/SKILL.md}

@@ -184,9 +184,13 @@ creatorUserOpenId -> upload-tts-video -> fileId -> shoppable-publish -> videoId
 - 上传请求头使用 `X-UPLOAD-TOKEN`
 - 如需上传进度与取消能力，优先用 XHR 而非裸 `fetch`
 
-## CLI 使用原则
+## CLI 工具
 
-本仓库已经提供 `beervid` CLI；如果用户要“直接操作 API”或“快速验证链路”，优先复用 CLI 能力，不必手写一遍完整流程。
+本 Skill 配套提供 `beervid` CLI；可直接在终端调用所有 Open API 能力。如需使用 CLI，请先安装：
+
+```bash
+npm install -g beervid-app-cli
+```
 
 ### CLI 前置
 

package/{docs → skills/beervid-app-cli/docs}/oauth-callback.md

@@ -16,8 +16,9 @@
 2. **用户跳转授权**：将用户重定向到返回的 URL
 3. **接收回调**：用户授权后，TikTok 回调你的服务器
 
-> **说明**：获取到的授权链接中通常已经包含 `state` 参数。
-> 如果你需要附加自定义安全字段，做法不是新增一个 `state` 参数，而是解析现有 `state`，在其 JSON 中追加字段后再写回授权链接。
+> **说明**：获取到的授权链接中**不一定**携带 `state` 参数。
+> - 如果链接中已经包含 `state`，它的值一定是一个 JSON 字符串。你可以解析该 JSON，在其中追加自定义字段后再写回。
+> - 如果链接中没有 `state`，而你需要透传参数（例如防 CSRF 的安全 token），应自行构造一个 JSON 对象作为 `state` 的值追加到授权链接上。
 
 ---
 
@@ -35,9 +36,11 @@ OAuth 授权完成后，回调 URL 会携带以下关键参数：
 
 ---
 
-## 获取授权链接后如何向已有 State 追加自定义字段
+## 获取授权链接后如何设置或追加 State
 
-如果获取到的授权链接里已经自带 `state`，并且它的值是一个 JSON 字符串，可以在拿到 OAuth URL 后解析这个 JSON，再把你方的安全 token 追加进去：
+授权链接中**可能包含也可能不包含** `state` 参数：
+- 如果已包含 `state`，其值是一个 JSON 字符串，可以解析后追加字段再写回。
+- 如果未包含 `state`，而你需要透传参数，应自行构造一个 JSON 对象设置为 `state`。
 
 ```typescript
 function tryParseJsonObject(value: string): Record<string, unknown> | null {
@@ -52,25 +55,25 @@ function tryParseJsonObject(value: string): Record<string, unknown> | null {
   }
 }
 
-function appendTokenToOAuthUrlState(
+function setOrAppendStateToken(
   rawUrl: string,
   customStateToken: string
 ): string {
   const url = new URL(rawUrl)
   const rawState = url.searchParams.get('state')
 
-  if (!rawState) {
-    throw new Error('授权链接中缺少 state 参数')
-  }
-
-  const parsedState = tryParseJsonObject(rawState)
-  if (!parsedState) {
-    throw new Error('授权链接中的 state 不是可追加字段的 JSON 对象')
-  }
+  let nextState: Record<string, unknown>
 
-  const nextState = {
-    ...parsedState,
-    customStateToken,
+  if (rawState) {
+    // 链接中已有 state，解析后追加字段
+    const parsedState = tryParseJsonObject(rawState)
+    if (!parsedState) {
+      throw new Error('授权链接中的 state 不是可追加字段的 JSON 对象')
+    }
+    nextState = { ...parsedState, customStateToken }
+  } else {
+    // 链接中没有 state，自行构造 JSON
+    nextState = { customStateToken }
   }
 
   url.searchParams.set('state', JSON.stringify(nextState))
@@ -80,7 +83,7 @@ function appendTokenToOAuthUrlState(
 async function getTtOAuthUrlWithState(userId: string): Promise<string> {
   const customStateToken = generateStateToken(userId)
   const rawUrl = await openApiGet<string>('/api/v1/open/thirdparty-auth/tt-url')
-  return appendTokenToOAuthUrlState(rawUrl, customStateToken)
+  return setOrAppendStateToken(rawUrl, customStateToken)
 }
 
 async function getTtsOAuthUrlWithState(userId: string): Promise<string> {
@@ -88,7 +91,7 @@ async function getTtsOAuthUrlWithState(userId: string): Promise<string> {
   const data = await openApiGet<{ crossBorderUrl: string }>(
     '/api/v1/open/thirdparty-auth/tts-url'
   )
-  return appendTokenToOAuthUrlState(data.crossBorderUrl, customStateToken)
+  return setOrAppendStateToken(data.crossBorderUrl, customStateToken)
 }
 ```
 
@@ -108,7 +111,7 @@ function parseCustomStateToken(state: string): string {
 ```
 
 > **说明**：字段名 `customStateToken` 只是示例，你也可以改成 `token`、`nonce`、`appState` 等业务上更合适的名字。
-> 如果授权链接里的 `state` 不是 JSON 对象，就不要按这个示例直接 `JSON.parse`；应改为使用平台允许的编码方式，或采用你当前链路已有的透传机制。
+> 无论链接中原先是否携带 `state`，你设置的 `state` 值都应该是一个 JSON 对象。
 
 ---
 

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

@@ -154,8 +154,10 @@ async function pollVideoStatusInBackground(record: VideoRecord): Promise<void> {
 app.get('/oauth/tt', async (_req, res) => {
   try {
     const url = await openApiGet<string>('/api/v1/open/thirdparty-auth/tt-url')
-    // 生产环境：先判断授权链接中的 state 是否为 JSON 对象；
-    // 若是，再在该 JSON 中追加你方自定义安全字段，详见 docs/oauth-callback.md
+    // 生产环境：授权链接中不一定携带 state 参数。
+    // 如果已有 state，其值为 JSON，可解析后追加自定义字段；
+    // 如果没有 state，需透传参数时应自行构造 JSON 设置为 state。
+    // 详见 docs/oauth-callback.md
     res.redirect(url)
   } catch (err) {
     res.status(500).json({ error: (err as Error).message })
@@ -168,8 +170,10 @@ app.get('/oauth/tts', async (_req, res) => {
     const data = await openApiGet<{ crossBorderUrl: string }>(
       '/api/v1/open/thirdparty-auth/tts-url'
     )
-    // 生产环境：先判断授权链接中的 state 是否为 JSON 对象；
-    // 若是，再在该 JSON 中追加你方自定义安全字段，详见 docs/oauth-callback.md
+    // 生产环境：授权链接中不一定携带 state 参数。
+    // 如果已有 state，其值为 JSON，可解析后追加自定义字段；
+    // 如果没有 state，需透传参数时应自行构造 JSON 设置为 state。
+    // 详见 docs/oauth-callback.md
     res.redirect(data.crossBorderUrl)
   } catch (err) {
     res.status(500).json({ error: (err as Error).message })

package/{example → skills/beervid-app-cli/example}/nextjs/app/api/oauth/url/route.ts

@@ -2,8 +2,9 @@
  * GET /api/oauth/url?type=tt|tts
  * 获取 OAuth 授权 URL
  *
- * 生产环境：如果要往授权链接里追加你方自定义安全字段，
- * 先判断现有 state 是否为 JSON 对象；若是，再在该 JSON 中追加字段。
+ * 生产环境：授权链接中不一定携带 state 参数。
+ * 如果已有 state，其值为 JSON，可解析后追加自定义字段；
+ * 如果没有 state，需透传参数时应自行构造 JSON 设置为 state。
  * 详见 docs/oauth-callback.md
  */
 import { NextRequest, NextResponse } from 'next/server'

package/{example → skills/beervid-app-cli/example}/standard/get-oauth-url.ts

@@ -5,8 +5,9 @@
  *   npx tsx get-oauth-url.ts --type tt
  *   npx tsx get-oauth-url.ts --type tts
  *
- * 生产环境：如果要往授权链接里追加你方自定义安全字段，
- * 先判断现有 state 是否为 JSON 对象；若是，再在该 JSON 中追加字段。
+ * 生产环境：授权链接中不一定携带 state 参数。
+ * 如果已有 state，其值为 JSON，可解析后追加自定义字段；
+ * 如果没有 state，需透传参数时应自行构造 JSON 设置为 state。
  * 详见 docs/oauth-callback.md
  */
 

package/agents/openai.yaml

@@ -1,7 +0,0 @@
-interface:
-  display_name: "BEERVID App CLI"
-  short_description: "BEERVID third-party Open API CLI skill"
-  default_prompt: "Use $beervid-app-cli to implement or troubleshoot BEERVID third-party Open API flows for OAuth, TikTok publishing, status polling, and product queries."
-
-policy:
-  allow_implicit_invocation: true