@optima-chat/optima-agent 0.9.8 → 0.9.10

package/.claude/skills/channels/SKILL.md

@@ -1,188 +1,188 @@
----
-name: channels
-description: "社交渠道管理。接入/管理 Telegram、WhatsApp、Discord、Slack、飞书、LINE、Zalo 等社交渠道，绑定用户账号，发送通知。使用场景：接入渠道(connect channel)、绑定(bind)、社交(social)、Telegram、WhatsApp、Discord、Slack、飞书、LINE、Zalo、通知(notify)、推送(push)、消息(message)。"
----
-
-# Optima Channels - 社交渠道管理
-
-管理社交渠道接入、用户绑定和消息推送。支持 Telegram、WhatsApp、Discord、Slack、飞书、LINE、Zalo。
-
-## 社交渠道环境注意事项
-
-当消息来自社交渠道（metadata.source === "channel_bridge"）时：
-
-1. **无浏览器环境** — 用户在 Telegram/WhatsApp 等社交 App 中，无法自动打开浏览器。所有需要浏览器的操作（如 OAuth 登录），必须把 URL 发给用户让他们手动打开。
-
-2. **登录流程** — 当用户需要登录（如操作商品、订单等需要认证的功能）：
-   - 运行 `commerce auth login`
-   - 命令会输出一个授权 URL 和验证码
-   - **把 URL 和验证码发给用户**，告诉他们在手机浏览器中打开
-   - 命令会自动等待用户完成授权
-   - 不要说"浏览器已自动打开"——社交渠道里没有浏览器
-
-3. **回复简洁** — 社交渠道消息应比 Web Chat 更简洁。避免长段落，用要点列表。
-
-## 典型场景
-
-当用户说：
-- "登录" → 运行 `commerce auth login`，把输出中的 URL 和验证码发给用户
-- "帮我接入 Telegram" → 引导创建 bot → `channels accounts add telegram --account-id store --token <token>`
-- "查看我的渠道" → `channels accounts list`
-- "关掉 Telegram" → `channels accounts disable telegram store`
-- "重新开启 Telegram" → `channels accounts enable telegram store`
-- "删除 Telegram 渠道" → `channels accounts remove telegram store`
-- "查看我的绑定" → `channels bind list`
-- "解绑 Telegram" → `channels bind remove --platform telegram --account-id store --platform-uid 123456`
-- "给用户发通知" → `channels send --user-id <id> --text "消息内容"`
-- "广播消息" → `channels broadcast --text "消息" --user-ids id1,id2`
-- "查看渠道状态" → `channels status`
-
-### 场景决策表
-
-| 用户需求 | 推荐命令 | 关键注意点 |
-|---------|---------|-----------|
-| 接入新渠道 | `channels accounts add <platform>` | 不同平台需要不同参数，见下方 |
-| 查看渠道列表 | `channels accounts list` | 显示所有账号及状态 |
-| 启用/禁用渠道 | `channels accounts enable/disable` | 不删除配置，只是暂停 |
-| 删除渠道 | `channels accounts remove` | 永久删除，需重新配置 |
-| 查看绑定 | `channels bind list` | 显示当前用户绑定的社交账号 |
-| 解绑 | `channels bind remove` | 需要指定 platform、account-id、platform-uid |
-| 发送通知 | `channels send` | 发到用户所有已绑定渠道 |
-| 广播 | `channels broadcast` | 发给多个用户 |
-
-## 场景1：接入 Telegram
-
-**流程**: 创建 Bot → 获取 Token → 添加到 Optima
-
-```bash
-# 1. 引导用户：
-# "请在 Telegram 找 @BotFather，发送 /newbot，按提示创建 bot，然后把 token 发给我"
-
-# 2. 用户提供 token 后，添加渠道
-channels accounts add telegram --account-id store --token "123456:AAHxxxxxxxxxx"
-
-# 3. 验证
-channels status
-```
-
-## 场景2：接入 Discord
-
-```bash
-# 1. 引导用户：
-# "请在 Discord Developer Portal (discord.com/developers) 创建 Application → Bot，
-#  开启 MESSAGE CONTENT Intent，复制 Bot Token"
-
-# 2. 添加渠道
-channels accounts add discord --account-id store --token "MTA3xxx..."
-
-# 3. 验证
-channels status
-```
-
-## 场景3：接入 Slack
-
-```bash
-# 1. 引导用户：
-# "请在 api.slack.com 创建 App，启用 Socket Mode，获取 Bot Token 和 App Token"
-
-# 2. 添加渠道
-channels accounts add slack --account-id store \
-  --bot-token "xoxb-..." \
-  --app-token "xapp-..." \
-  --signing-secret "..."
-
-# 3. 验证
-channels status
-```
-
-## 场景4：接入飞书
-
-```bash
-# 1. 引导用户：
-# "请在飞书开发者后台创建应用，获取 App ID 和 App Secret"
-
-# 2. 添加渠道
-channels accounts add feishu --account-id store \
-  --app-id "cli_xxx" \
-  --app-secret "xxx"
-
-# 3. 验证
-channels status
-```
-
-## 场景5：接入 LINE
-
-```bash
-# 1. 引导用户：
-# "请在 LINE Developers Console 创建 Messaging API channel，获取 Channel Access Token 和 Channel Secret"
-
-# 2. 添加渠道
-channels accounts add line --account-id store \
-  --channel-access-token "xxx" \
-  --channel-secret "xxx"
-
-# 3. 配置 Webhook URL（需在 LINE Developer Console 手动设置）：
-# https://channels-api.optima.onl/webhook/line/store
-
-# 4. 验证
-channels status
-```
-
-## 场景6：社交账号自动绑定
-
-**无需 CLI 操作**。商家只需给 bot 发送任意消息，bot 会：
-
-1. 自动回复一条授权链接（形如 `https://auth.optima.onl/api/v1/oauth/device?user_code=XXX-YYY`）
-2. 商家点开链接在手机浏览器登录并授权
-3. bot 发送 "✅ 授权成功" 消息，之后商家可以直接问任何业务问题
-
-链接 10 分钟内有效。超过 14 天未活跃，bot 会要求重新授权。
-
-**开发者运维**：如需强制解绑某条绑定，用 `channels bind remove`（现有命令不变）。
-
-## 场景7：发送通知
-
-```bash
-# 发送给单个用户（发到所有已绑定渠道）
-channels send --user-id "uuid-xxx" --text "您的订单 #1234 已发货"
-
-# 指定渠道发送
-channels send --user-id "uuid-xxx" --text "消息" --platform telegram
-
-# 广播给多个用户
-channels broadcast --text "新品上架！限时8折" --user-ids "uuid-1,uuid-2,uuid-3"
-```
-
-## 各平台必需参数
-
-| 平台 | 必需参数 | 获取方式 |
-|------|---------|---------|
-| Telegram | `--token` | @BotFather 创建 bot |
-| Discord | `--token` | Developer Portal → Bot |
-| Slack | `--bot-token` `--app-token` `--signing-secret` | api.slack.com → App |
-| LINE | `--channel-access-token` `--channel-secret` | LINE Developers Console |
-| 飞书 | `--app-id` `--app-secret` | 飞书开发者后台 |
-| WhatsApp | `--session-dir`（可选） | baileys QR 扫码认证 |
-| Zalo | `--token` | Zalo Developer Console |
-
-## 命令参考
-
-```bash
-# 状态
-channels status
-
-# 账号管理
-channels accounts list
-channels accounts add <platform> --account-id <id> [平台参数]
-channels accounts remove <platform> <accountId>
-channels accounts enable <platform> <accountId>
-channels accounts disable <platform> <accountId>
-
-# 绑定管理
-channels bind list [--user-id <id>]
-channels bind remove --platform <p> --account-id <a> --platform-uid <uid>
-
-# 消息
-channels send --user-id <id> --text "消息"
-channels broadcast --text "消息" --user-ids "id1,id2"
-```
+---
+name: channels
+description: "社交渠道管理。接入/管理 Telegram、WhatsApp、Discord、Slack、飞书、LINE、Zalo 等社交渠道，绑定用户账号，发送通知。使用场景：接入渠道(connect channel)、绑定(bind)、社交(social)、Telegram、WhatsApp、Discord、Slack、飞书、LINE、Zalo、通知(notify)、推送(push)、消息(message)。"
+---
+
+# Optima Channels - 社交渠道管理
+
+管理社交渠道接入、用户绑定和消息推送。支持 Telegram、WhatsApp、Discord、Slack、飞书、LINE、Zalo。
+
+## 社交渠道环境注意事项
+
+当消息来自社交渠道（metadata.source === "channel_bridge"）时：
+
+1. **无浏览器环境** — 用户在 Telegram/WhatsApp 等社交 App 中，无法自动打开浏览器。所有需要浏览器的操作（如 OAuth 登录），必须把 URL 发给用户让他们手动打开。
+
+2. **登录流程** — 当用户需要登录（如操作商品、订单等需要认证的功能）：
+   - 运行 `commerce auth login`
+   - 命令会输出一个授权 URL 和验证码
+   - **把 URL 和验证码发给用户**，告诉他们在手机浏览器中打开
+   - 命令会自动等待用户完成授权
+   - 不要说"浏览器已自动打开"——社交渠道里没有浏览器
+
+3. **回复简洁** — 社交渠道消息应比 Web Chat 更简洁。避免长段落，用要点列表。
+
+## 典型场景
+
+当用户说：
+- "登录" → 运行 `commerce auth login`，把输出中的 URL 和验证码发给用户
+- "帮我接入 Telegram" → 引导创建 bot → `channels accounts add telegram --account-id store --token <token>`
+- "查看我的渠道" → `channels accounts list`
+- "关掉 Telegram" → `channels accounts disable telegram store`
+- "重新开启 Telegram" → `channels accounts enable telegram store`
+- "删除 Telegram 渠道" → `channels accounts remove telegram store`
+- "查看我的绑定" → `channels bind list`
+- "解绑 Telegram" → `channels bind remove --platform telegram --account-id store --platform-uid 123456`
+- "给用户发通知" → `channels send --user-id <id> --text "消息内容"`
+- "广播消息" → `channels broadcast --text "消息" --user-ids id1,id2`
+- "查看渠道状态" → `channels status`
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 接入新渠道 | `channels accounts add <platform>` | 不同平台需要不同参数，见下方 |
+| 查看渠道列表 | `channels accounts list` | 显示所有账号及状态 |
+| 启用/禁用渠道 | `channels accounts enable/disable` | 不删除配置，只是暂停 |
+| 删除渠道 | `channels accounts remove` | 永久删除，需重新配置 |
+| 查看绑定 | `channels bind list` | 显示当前用户绑定的社交账号 |
+| 解绑 | `channels bind remove` | 需要指定 platform、account-id、platform-uid |
+| 发送通知 | `channels send` | 发到用户所有已绑定渠道 |
+| 广播 | `channels broadcast` | 发给多个用户 |
+
+## 场景1：接入 Telegram
+
+**流程**: 创建 Bot → 获取 Token → 添加到 Optima
+
+```bash
+# 1. 引导用户：
+# "请在 Telegram 找 @BotFather，发送 /newbot，按提示创建 bot，然后把 token 发给我"
+
+# 2. 用户提供 token 后，添加渠道
+channels accounts add telegram --account-id store --token "123456:AAHxxxxxxxxxx"
+
+# 3. 验证
+channels status
+```
+
+## 场景2：接入 Discord
+
+```bash
+# 1. 引导用户：
+# "请在 Discord Developer Portal (discord.com/developers) 创建 Application → Bot，
+#  开启 MESSAGE CONTENT Intent，复制 Bot Token"
+
+# 2. 添加渠道
+channels accounts add discord --account-id store --token "MTA3xxx..."
+
+# 3. 验证
+channels status
+```
+
+## 场景3：接入 Slack
+
+```bash
+# 1. 引导用户：
+# "请在 api.slack.com 创建 App，启用 Socket Mode，获取 Bot Token 和 App Token"
+
+# 2. 添加渠道
+channels accounts add slack --account-id store \
+  --bot-token "xoxb-..." \
+  --app-token "xapp-..." \
+  --signing-secret "..."
+
+# 3. 验证
+channels status
+```
+
+## 场景4：接入飞书
+
+```bash
+# 1. 引导用户：
+# "请在飞书开发者后台创建应用，获取 App ID 和 App Secret"
+
+# 2. 添加渠道
+channels accounts add feishu --account-id store \
+  --app-id "cli_xxx" \
+  --app-secret "xxx"
+
+# 3. 验证
+channels status
+```
+
+## 场景5：接入 LINE
+
+```bash
+# 1. 引导用户：
+# "请在 LINE Developers Console 创建 Messaging API channel，获取 Channel Access Token 和 Channel Secret"
+
+# 2. 添加渠道
+channels accounts add line --account-id store \
+  --channel-access-token "xxx" \
+  --channel-secret "xxx"
+
+# 3. 配置 Webhook URL（需在 LINE Developer Console 手动设置）：
+# https://channels-api.optima.onl/webhook/line/store
+
+# 4. 验证
+channels status
+```
+
+## 场景6：社交账号自动绑定
+
+**无需 CLI 操作**。商家只需给 bot 发送任意消息，bot 会：
+
+1. 自动回复一条授权链接（形如 `https://auth.optima.onl/api/v1/oauth/device?user_code=XXX-YYY`）
+2. 商家点开链接在手机浏览器登录并授权
+3. bot 发送 "✅ 授权成功" 消息，之后商家可以直接问任何业务问题
+
+链接 10 分钟内有效。超过 14 天未活跃，bot 会要求重新授权。
+
+**开发者运维**：如需强制解绑某条绑定，用 `channels bind remove`（现有命令不变）。
+
+## 场景7：发送通知
+
+```bash
+# 发送给单个用户（发到所有已绑定渠道）
+channels send --user-id "uuid-xxx" --text "您的订单 #1234 已发货"
+
+# 指定渠道发送
+channels send --user-id "uuid-xxx" --text "消息" --platform telegram
+
+# 广播给多个用户
+channels broadcast --text "新品上架！限时8折" --user-ids "uuid-1,uuid-2,uuid-3"
+```
+
+## 各平台必需参数
+
+| 平台 | 必需参数 | 获取方式 |
+|------|---------|---------|
+| Telegram | `--token` | @BotFather 创建 bot |
+| Discord | `--token` | Developer Portal → Bot |
+| Slack | `--bot-token` `--app-token` `--signing-secret` | api.slack.com → App |
+| LINE | `--channel-access-token` `--channel-secret` | LINE Developers Console |
+| 飞书 | `--app-id` `--app-secret` | 飞书开发者后台 |
+| WhatsApp | `--session-dir`（可选） | baileys QR 扫码认证 |
+| Zalo | `--token` | Zalo Developer Console |
+
+## 命令参考
+
+```bash
+# 状态
+channels status
+
+# 账号管理
+channels accounts list
+channels accounts add <platform> --account-id <id> [平台参数]
+channels accounts remove <platform> <accountId>
+channels accounts enable <platform> <accountId>
+channels accounts disable <platform> <accountId>
+
+# 绑定管理
+channels bind list [--user-id <id>]
+channels bind remove --platform <p> --account-id <a> --platform-uid <uid>
+
+# 消息
+channels send --user-id <id> --text "消息"
+channels broadcast --text "消息" --user-ids "id1,id2"
+```

package/.claude/skills/collection/SKILL.md

@@ -1,88 +1,88 @@
----
-name: collection
-description: 商品集合管理。创建、编辑集合，设置封面图，管理集合中的商品。当用户需要对商品进行分组、创建促销专区、管理商品分类、设置集合封面时使用。
----
-
-## 概念
-
-Collection（集合）是商品的逻辑分组，用于在店铺中组织和展示商品。类似 Shopify 的 Collections。
-
-- 一个商品可以属于多个集合（多对多关系）
-- 集合支持层级结构（parent_id）
-- 集合通过 slug 在 URL 中标识，如 `/collections/summer-sale`
-
-## 结构
-
-```
-Collection
-├── 基本信息
-│   ├── name: 集合名称
-│   ├── slug: URL 标识（商户内唯一）
-│   └── description: 描述
-├── 显示设置
-│   ├── display_order: 显示顺序
-│   ├── is_active: 是否激活
-│   └── cover_media_id: 封面图
-├── 层级
-│   └── parent_id: 父集合（可选）
-├── SEO
-│   ├── meta_title: SEO 标题
-│   └── meta_description: SEO 描述
-└── 商品（多对多）
-    └── products: 集合中的商品列表
-```
-
-## 典型场景
-
-当用户说：
-- "查看所有集合" / "集合列表" → `commerce collection list`
-- "创建集合 XX" → `commerce collection create --name "XX" --slug xx`
-- "查看集合详情" → `commerce collection get --id xx`
-- "删除集合 XX" → `commerce collection delete --id xx --yes`
-- "把商品加到集合" → `commerce collection add-products --id xx --product-ids p1,p2`
-- "从集合移除商品" → `commerce collection remove-products --id xx --product-ids p1`
-- "查看集合里有哪些商品" → `commerce collection list-products --id xx`
-- "设置集合封面" / "给集合加封面图" → `commerce collection set-cover --id xx --path ./cover.jpg`
-
-## 命令参考
-
-### 集合 CRUD
-- `commerce collection list` - 列出所有集合
-- `commerce collection create --name <name> --slug <slug>` - 创建集合
-- `commerce collection get --id <id>` - 查看集合详情
-- `commerce collection update --id <id>` - 更新集合（支持 --name, --slug, --description 等）
-- `commerce collection delete --id <id> --yes` - 删除集合
-- `commerce collection set-cover --id <id>` - 设置封面图（支持 --media-id, --url, --path）
-
-### 商品管理
-- `commerce collection add-products --id <id> --product-ids <ids>` - 添加商品
-- `commerce collection remove-products --id <id> --product-ids <ids>` - 移除商品
-- `commerce collection list-products --id <id>` - 列出集合中的商品
-
-## 创建集合示例
-
-```bash
-# 创建促销集合（返回 id，用于后续操作）
-commerce collection create \
-  --name "Summer Sale 2024" \
-  --slug summer-sale-2024 \
-  --description "Hot deals for summer"
-# 输出: { "id": "coll_xxx", ... }
-
-# 添加商品到集合（使用返回的 id）
-commerce collection add-products \
-  --id coll_xxx \
-  --product-ids prod_123,prod_456,prod_789
-
-# 设置封面图
-commerce collection set-cover \
-  --id coll_xxx \
-  --path ./summer-sale-cover.jpg
-```
-
-## 注意事项
-
-- **slug 规范**：使用英文、数字、连字符，避免中文和特殊字符（影响 SEO 和 URL）
-- **删除确认**：删除操作需要 `--yes` 参数确认
-- **商品数量**：建议每个集合包含 5-30 个商品，过少显得空，过多难以浏览
-- **层级深度**：支持父子集合，但建议层级不超过 2 层
+---
+name: collection
+description: 商品集合管理。创建、编辑集合，设置封面图，管理集合中的商品。当用户需要对商品进行分组、创建促销专区、管理商品分类、设置集合封面时使用。
+---
+
+## 概念
+
+Collection（集合）是商品的逻辑分组，用于在店铺中组织和展示商品。类似 Shopify 的 Collections。
+
+- 一个商品可以属于多个集合（多对多关系）
+- 集合支持层级结构（parent_id）
+- 集合通过 slug 在 URL 中标识，如 `/collections/summer-sale`
+
+## 结构
+
+```
+Collection
+├── 基本信息
+│   ├── name: 集合名称
+│   ├── slug: URL 标识（商户内唯一）
+│   └── description: 描述
+├── 显示设置
+│   ├── display_order: 显示顺序
+│   ├── is_active: 是否激活
+│   └── cover_media_id: 封面图
+├── 层级
+│   └── parent_id: 父集合（可选）
+├── SEO
+│   ├── meta_title: SEO 标题
+│   └── meta_description: SEO 描述
+└── 商品（多对多）
+    └── products: 集合中的商品列表
+```
+
+## 典型场景
+
+当用户说：
+- "查看所有集合" / "集合列表" → `commerce collection list`
+- "创建集合 XX" → `commerce collection create --name "XX" --slug xx`
+- "查看集合详情" → `commerce collection get --id xx`
+- "删除集合 XX" → `commerce collection delete --id xx --yes`
+- "把商品加到集合" → `commerce collection add-products --id xx --product-ids p1,p2`
+- "从集合移除商品" → `commerce collection remove-products --id xx --product-ids p1`
+- "查看集合里有哪些商品" → `commerce collection list-products --id xx`
+- "设置集合封面" / "给集合加封面图" → `commerce collection set-cover --id xx --path ./cover.jpg`
+
+## 命令参考
+
+### 集合 CRUD
+- `commerce collection list` - 列出所有集合
+- `commerce collection create --name <name> --slug <slug>` - 创建集合
+- `commerce collection get --id <id>` - 查看集合详情
+- `commerce collection update --id <id>` - 更新集合（支持 --name, --slug, --description 等）
+- `commerce collection delete --id <id> --yes` - 删除集合
+- `commerce collection set-cover --id <id>` - 设置封面图（支持 --media-id, --url, --path）
+
+### 商品管理
+- `commerce collection add-products --id <id> --product-ids <ids>` - 添加商品
+- `commerce collection remove-products --id <id> --product-ids <ids>` - 移除商品
+- `commerce collection list-products --id <id>` - 列出集合中的商品
+
+## 创建集合示例
+
+```bash
+# 创建促销集合（返回 id，用于后续操作）
+commerce collection create \
+  --name "Summer Sale 2024" \
+  --slug summer-sale-2024 \
+  --description "Hot deals for summer"
+# 输出: { "id": "coll_xxx", ... }
+
+# 添加商品到集合（使用返回的 id）
+commerce collection add-products \
+  --id coll_xxx \
+  --product-ids prod_123,prod_456,prod_789
+
+# 设置封面图
+commerce collection set-cover \
+  --id coll_xxx \
+  --path ./summer-sale-cover.jpg
+```
+
+## 注意事项
+
+- **slug 规范**：使用英文、数字、连字符，避免中文和特殊字符（影响 SEO 和 URL）
+- **删除确认**：删除操作需要 `--yes` 参数确认
+- **商品数量**：建议每个集合包含 5-30 个商品，过少显得空，过多难以浏览
+- **层级深度**：支持父子集合，但建议层级不超过 2 层