@optima-chat/optima-agent 0.1.0

package/.claude/skills/commerce-storefront/SKILL.md

@@ -0,0 +1,560 @@
+---
+name: commerce-storefront
+description: Storefront and product page configuration. Manage homepage sections, product collections, merchant profile, product detail page sections with 3-layer inheritance (System → Merchant → Product). Use when user needs to configure homepage, create collections, customize product page sections, or organize storefront layout.
+---
+
+# Commerce CLI - Storefront Configuration
+
+店铺前台配置模块，用于首页设置、商品集合管理和商户信息维护。
+
+## 典型场景
+
+### 场景决策表
+
+| 用户需求 | 推荐命令 | 关键注意点 |
+|---------|---------|-----------|
+| 创建轮播图 | `commerce homepage module create --type banner` | 图片尺寸1920x600px，≤5张，配置跳转链接 |
+| 显示精选商品 | `commerce homepage module create --type featured` | 选择高转化商品，数量8-12个 |
+| 创建促销集合 | `collection create --slug sale` | slug 简短有意义，添加10-30个商品 |
+| 调整模块顺序 | `homepage module reorder --position X` | 重要模块靠前（轮播图position=1） |
+| 更新店铺信息 | `merchant update --name/description` | 名称简洁，描述突出差异化优势 |
+
+### 场景 1：首页配置
+
+**标准首页布局**（position顺序）：
+1. **轮播图** (position=1) - 展示促销、新品、品牌故事
+2. **分类导航** (position=2) - 快速引导到商品分类
+3. **精选商品** (position=3) - 展示高转化或高利润商品
+4. **热门集合** (position=4) - 展示2-3个核心集合
+5. **品牌故事** (position=5) - 建立信任和品牌认知
+
+**标准流程**：
+1. **规划布局** - 确定首页模块顺序（轮播图 → 分类 → 精选商品 → 集合）
+2. **创建模块** - 依次 `commerce homepage module create` 创建各模块
+3. **配置顺序** - 使用 position 1, 2, 3... 排序
+4. **设置参数** - `commerce homepage settings update` 配置搜索、精选数量
+5. **验证效果** - `commerce homepage module list` 检查配置
+6. **定期优化** - 根据数据调整模块顺序和内容
+
+### 场景 2：创建轮播图
+
+**配置要点**：
+- 图片尺寸：1920x600px（桌面端）
+- 数量限制：≤ 5张（避免影响加载速度）
+- 格式支持：WebP（优先）、JPG、PNG
+- 跳转链接：配置促销页面或集合页面
+- 懒加载：启用图片懒加载优化性能
+
+```bash
+commerce homepage module create \
+  --slug hero-banner \
+  --type banner \
+  --position 1 \
+  --enabled true \
+  --config '{"images":[{"url":"https://example.com/banner1.jpg","link":"/collections/summer-sale"}]}'
+```
+
+### 场景 3：创建商品集合
+
+**推荐集合类型**：
+- **时令集合** - 春夏秋冬、节日促销（如"Christmas Sale"）
+- **品类集合** - 按商品类型分组（如"T-Shirts", "Dresses"）
+- **主题集合** - 按场景分组（如"Office Wear", "Casual Style"）
+- **促销集合** - 新品、热卖、折扣（如"New Arrivals", "Best Sellers"）
+
+**创建流程**：
+```bash
+# 1. 创建集合
+commerce collection create \
+  --name "Summer Sale 2024" \
+  --slug "summer-sale-2024" \
+  --description "Hot deals for summer"
+
+# 2. 添加商品到集合
+commerce collection add-products \
+  --slug summer-sale-2024 \
+  --product-ids prod_123,prod_456,prod_789
+```
+
+### 场景 4：调整模块顺序
+
+**重新排序原则**：
+- 重要模块靠前（轮播图 position=1）
+- 高转化模块优先级高
+- 移动端体验优先
+- 定期根据数据优化
+
+```bash
+# 调整精选商品模块到第2位
+commerce homepage module reorder \
+  --module-id module_123 \
+  --position 2
+```
+
+### 场景 5：优化转化率
+
+**数据驱动优化**：
+- 分析首页点击热图，调整模块顺序
+- A/B测试不同轮播图和精选商品
+- 根据转化率隐藏低效集合
+- 精选商品选择高利润或高评分商品
+
+**性能优化建议**：
+- 轮播图：懒加载，压缩图片，支持WebP格式
+- 精选商品：限制8-12个，缓存1小时
+- 集合：按点击率排序，隐藏低转化集合
+
+### 场景 6：店铺信息维护
+
+**更新要点**：
+- 店铺名称：简洁有辨识度
+- 描述：突出差异化优势和核心品类
+- Logo：清晰、支持透明背景
+- 联系方式：完整准确
+
+```bash
+commerce merchant update \
+  --name "My Fashion Store" \
+  --description "Premium fashion for everyone" \
+  --logo-url "https://example.com/logo.png"
+```
+
+## 卓越标准
+
+### 店铺配置质量指标
+- **页面加载速度**: 首页加载 < 3秒，移动端 < 5秒
+- **视觉设计**: 轮播图尺寸统一（1920x600px），图片清晰无水印
+- **导航体验**: 分类层级 ≤ 3层，集合数量 5-15个最佳
+- **内容更新频率**: 轮播图每周更新，精选商品每3天更新
+- **转化率**: 首页访客转化率 > 3%，集合页转化率 > 5%
+
+### 店铺配置原则
+- **移动优先**: 所有配置考虑移动端体验，图片支持响应式
+- **性能优化**: 轮播图 ≤ 5张，精选商品 ≤ 12个，减少加载负担
+- **SEO友好**: 集合slug使用英文，标题包含关键词
+- **一致性**: 风格统一（色彩、字体、间距），提升品牌辨识度
+- **数据驱动**: 根据点击率和转化率优化首页布局和集合内容
+
+### 首页配置检查清单
+
+**上线前必查**：
+- [ ] 轮播图尺寸统一，图片清晰
+- [ ] 所有链接可点击，无404
+- [ ] 移动端显示正常
+- [ ] 加载速度 < 3秒
+- [ ] SEO信息完整（标题、描述、关键词）
+- [ ] 精选商品有库存
+- [ ] 集合至少包含5个商品
+- [ ] 店铺信息准确（名称、Logo、联系方式）
+
+## 常见问题
+
+### ❌ 问题 1：集合命名随意，无规划
+
+**错误做法**：
+```bash
+# 命名不规范，slug 无意义
+commerce collection create --name "aaa" --slug "test123"
+commerce collection create --name "商品111" --slug "product-collection"
+commerce collection create --name "Sale!!!" --slug "promotion"
+```
+
+**✅ 正确做法**：
+```bash
+# 命名清晰，slug 符合 SEO 规范
+commerce collection create --name "Summer Sale 2024" --slug "summer-sale-2024"
+commerce collection create --name "Men's T-Shirts" --slug "mens-tshirts"
+commerce collection create --name "New Arrivals" --slug "new-arrivals"
+```
+
+### ❌ 问题 2：轮播图过多影响性能
+
+**错误做法**：
+```bash
+# 创建10张轮播图，导致首页加载缓慢
+commerce homepage module create --type banner --config '{"images":[...10张图片...]}'
+```
+
+**✅ 正确做法**：
+```bash
+# 限制≤5张，压缩图片，启用懒加载
+commerce homepage module create --type banner --config '{"images":[...3-5张图片...]}'
+```
+
+### ❌ 问题 3：精选商品数量过多
+
+**错误做法**：
+```bash
+# 显示30个精选商品，影响用户决策
+commerce homepage settings update --featured-limit 30
+```
+
+**✅ 正确做法**：
+```bash
+# 限制8-12个，选择高转化商品
+commerce homepage settings update --featured-limit 10
+```
+
+### ❌ 问题 4：集合缺少商品
+
+**错误做法**：
+```bash
+# 创建集合后忘记添加商品
+commerce collection create --name "New Arrivals" --slug "new-arrivals"
+# 集合页面显示空白
+```
+
+**✅ 正确做法**：
+```bash
+# 创建集合后立即添加商品（至少5个）
+commerce collection create --name "New Arrivals" --slug "new-arrivals"
+commerce collection add-products --slug new-arrivals --product-ids prod_1,prod_2,prod_3,prod_4,prod_5
+```
+
+### ❌ 问题 5：首页模块顺序混乱
+
+**错误做法**：
+```bash
+# position 随意设置，导致布局混乱
+commerce homepage module create --type banner --position 10
+commerce homepage module create --type featured --position 2
+commerce homepage module create --type categories --position 50
+```
+
+**✅ 正确做法**：
+```bash
+# 按重要性依次设置 position 1, 2, 3...
+commerce homepage module create --type banner --position 1
+commerce homepage module create --type categories --position 2
+commerce homepage module create --type featured --position 3
+```
+
+### ❌ 问题 6：slug 使用中文或特殊字符
+
+**错误做法**：
+```bash
+# slug 包含中文或特殊字符，影响 SEO 和 URL 可读性
+commerce collection create --name "夏季促销" --slug "夏季促销"
+commerce collection create --name "Sale!!!" --slug "sale!!!"
+```
+
+**✅ 正确做法**：
+```bash
+# slug 使用英文、数字、连字符
+commerce collection create --name "夏季促销" --slug "summer-sale"
+commerce collection create --name "Sale!!!" --slug "sale"
+```
+
+## 命令参考
+
+### 自然语言映射
+
+当用户说：
+- "创建首页轮播图" → `commerce homepage module create --type banner ...`
+- "更新首页设置" → `commerce homepage settings update --show-search true`
+- "创建商品集合" → `commerce collection create --name XX --slug YY`
+- "把商品添加到集合" → `commerce collection add-products --id XX --product-ids YY`
+- "更新店铺信息" → `commerce merchant update --name XX`
+
+### 核心功能
+
+**首页模块管理**:
+- `commerce homepage module create` - 创建首页模块
+- `commerce homepage module list` - 查看所有模块
+- `commerce homepage module update` - 更新模块
+- `commerce homepage module delete` - 删除模块
+- `commerce homepage module reorder` - 重新排序
+
+**首页设置**:
+- `commerce homepage settings get` - 查看首页设置
+- `commerce homepage settings update` - 更新首页设置
+
+**商品集合**:
+- `commerce collection create` - 创建集合
+- `commerce collection list` - 查看集合列表
+- `commerce collection update` - 更新集合
+- `commerce collection delete` - 删除集合
+- `commerce collection add-products` - 添加商品到集合
+- `commerce collection remove-products` - 从集合移除商品
+
+**商户信息**:
+- `commerce merchant info` - 查看商户信息
+- `commerce merchant update` - 更新商户信息
+- `commerce merchant init` - 初始化商户设置
+
+## 详细示例
+
+### 创建首页轮播图
+```bash
+# 用户说："创建首页轮播图模块"
+commerce homepage module create \
+  --slug hero-banner \
+  --type banner \
+  --position 1 \
+  --enabled true \
+  --config '{"images":[{"url":"https://example.com/banner1.jpg"}]}'
+```
+
+### 更新首页设置
+```bash
+# 用户说："启用首页搜索功能，显示8个精选商品"
+commerce homepage settings update \
+  --show-search true \
+  --featured-limit 8
+```
+
+### 创建商品集合
+```bash
+# 用户说："创建夏季促销集合"
+commerce collection create \
+  --name "Summer Sale" \
+  --slug summer-sale \
+  --description "Hot deals for summer"
+```
+
+### 添加商品到集合
+```bash
+# 用户说："把商品prod_123和prod_456添加到summer-sale集合"
+commerce collection add-products \
+  --slug summer-sale \
+  --product-ids prod_123,prod_456
+```
+
+### 更新商户信息
+```bash
+# 用户说："更新店铺名称和描述"
+commerce merchant update \
+  --name "My Fashion Store" \
+  --description "Premium fashion for everyone"
+```
+
+### 重新排序首页模块
+```bash
+# 用户说："调整首页模块顺序"
+commerce homepage module reorder \
+  --module-id module_123 \
+  --position 2
+```
+
+### 完整首页配置示例
+```bash
+# 1. 创建轮播图模块
+commerce homepage module create \
+  --slug hero-banner \
+  --type banner \
+  --position 1 \
+  --config '{"images":[{"url":"https://example.com/banner1.jpg","link":"/collections/summer-sale"},{"url":"https://example.com/banner2.jpg","link":"/collections/new-arrivals"}]}'
+
+# 2. 创建分类导航模块
+commerce homepage module create \
+  --slug category-nav \
+  --type categories \
+  --position 2 \
+  --config '{"columns":4}'
+
+# 3. 创建精选商品模块
+commerce homepage module create \
+  --slug featured-products \
+  --type featured \
+  --position 3 \
+  --config '{"limit":10}'
+
+# 4. 更新首页设置
+commerce homepage settings update \
+  --show-search true \
+  --featured-limit 10
+
+# 5. 验证配置
+commerce homepage module list
+```
+
+## 场景 7：商品详情页区块管理
+
+### 三层继承模型
+
+商品详情页区块采用三层继承架构，实现灵活的内容定制：
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  System Layer (系统默认)                                 │
+│  - 7个预设区块: highlights, details, guarantee,          │
+│    care, shipping-policies, return, eco-friendly        │
+│  - 支持7种语言的默认翻译                                  │
+│  - 不可删除，只能覆盖或隐藏                               │
+└─────────────────────────────────────────────────────────┘
+                          ↓ 继承
+┌─────────────────────────────────────────────────────────┐
+│  Merchant Layer (商户定制)                               │
+│  - 覆盖系统默认区块内容                                   │
+│  - 创建商户专属新区块                                     │
+│  - 隐藏不需要的系统区块                                   │
+│  - 适用于所有商品（除非商品级覆盖）                        │
+└─────────────────────────────────────────────────────────┘
+                          ↓ 继承
+┌─────────────────────────────────────────────────────────┐
+│  Product Layer (商品定制)                                │
+│  - 覆盖商户/系统区块内容                                  │
+│  - 创建商品专属区块                                       │
+│  - 隐藏特定商品不需要的区块                               │
+│  - 最高优先级，仅影响单个商品                             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 查看区块配置
+
+```bash
+# 查看商户级配置（推荐使用 --resolved 查看完整视图）
+commerce section list --resolved
+
+# 查看特定商品的区块配置
+commerce section product list prod-123 --resolved
+```
+
+**关键字段说明**：
+- `source`: 区块来源 (system/merchant/product)
+- `is_hidden`: 是否被隐藏
+- `translations`: 各语言的标题和内容
+
+### 覆盖系统默认区块
+
+```bash
+# 商户级：覆盖所有商品的"护理说明"
+commerce section create \
+  --handle care \
+  --operation-type override \
+  --type collapsible \
+  --position 4 \
+  --content "我们的产品均可机洗，30度冷水。"
+
+# 商品级：为特定商品定制"护理说明"
+commerce section product create prod-123 \
+  --handle care \
+  --operation-type override \
+  --type collapsible \
+  --position 4 \
+  --content "此款真丝产品需要干洗。"
+```
+
+### 创建自定义区块
+
+```bash
+# 商户级：创建"品牌故事"区块（所有商品显示）
+commerce section create \
+  --handle brand-story \
+  --operation-type new \
+  --type collapsible \
+  --position 8 \
+  --content "## 我们的故事\n\n创立于2020年..."
+
+# 商品级：创建"成分说明"区块（仅此商品显示）
+commerce section product create prod-123 \
+  --handle ingredients \
+  --operation-type new \
+  --type collapsible \
+  --position 5 \
+  --content "主要成分：有机棉100%"
+```
+
+### 隐藏不需要的区块
+
+```bash
+# 商户级：隐藏"环保包装"区块（所有商品不显示）
+commerce section hide eco-friendly
+
+# 商品级：隐藏特定商品的"退货政策"
+commerce section product hide prod-123 return
+```
+
+### 添加多语言翻译
+
+```bash
+# 为商户级区块添加中文翻译
+commerce section translation set care \
+  --lang zh-CN \
+  --title "护理说明" \
+  --content "机洗，30度冷水。"
+
+# 为商品级区块添加日文翻译
+commerce section translation set care \
+  --product-id prod-123 \
+  --lang ja-JP \
+  --title "お手入れ方法" \
+  --content "洗濯機で洗えます。水温30度。"
+```
+
+### 调整区块顺序
+
+```bash
+# 商户级排序
+commerce section reorder --sections '[
+  {"handle":"highlights","position":1},
+  {"handle":"details","position":2},
+  {"handle":"care","position":3}
+]'
+
+# 商品级排序
+commerce section product reorder prod-123 --sections '[...]'
+```
+
+### Section 常见问题
+
+#### ❌ 问题：不理解三层继承，直接在商品级创建
+
+**错误做法**：
+```bash
+# 想要所有商品都显示"品牌故事"，却在商品级创建
+commerce section product create prod-123 --handle brand-story ...
+commerce section product create prod-456 --handle brand-story ...  # 重复操作
+```
+
+**✅ 正确做法**：
+```bash
+# 在商户级创建，自动应用到所有商品
+commerce section create --handle brand-story --operation-type new ...
+```
+
+#### ❌ 问题：不使用 --resolved 查看配置
+
+**错误做法**：
+```bash
+# 只看商户自定义，看不到系统默认
+commerce section list
+# 返回空列表（新商户通常没有自定义）
+```
+
+**✅ 正确做法**：
+```bash
+# 使用 --resolved 查看完整的合并后视图
+commerce section list --resolved
+# 返回 System + Merchant 合并后的所有区块
+```
+
+### Section 自然语言映射
+
+当用户说：
+- "查看商品详情页区块" → `commerce section list --resolved`
+- "查看商品X的区块配置" → `commerce section product list <id> --resolved`
+- "修改护理说明" → `commerce section create --handle care --operation-type override ...`
+- "隐藏退货政策区块" → `commerce section hide return`
+- "为商品添加自定义区块" → `commerce section product create <id> --handle XX --operation-type new ...`
+- "添加区块的中文翻译" → `commerce section translation set <handle> --lang zh-CN ...`
+
+## 重要提示
+
+### 首页配置
+- 首页模块支持类型：banner（轮播图）、featured（精选商品）、categories（分类）
+- 集合 slug 必须唯一，用于 URL
+- 模块的 position 决定显示顺序（从小到大）
+- config 字段使用 JSON 格式
+- 集合可以手动管理商品，也可以设置自动规则
+
+### 商品页区块
+- 系统默认区块：highlights, details, guarantee, care, shipping-policies, return, eco-friendly
+- `--resolved` 查看完整合并视图（推荐）
+- `source` 字段标识来源：system | merchant | product
+- 想改所有商品用 `section create`，只改一个商品用 `section product create`
+
+### 通用
+- 使用 `--help` 查看命令详细参数
+- 所有配置创建后需要验证是否正确
+- 定期根据数据分析优化布局和内容

package/.claude/skills/google-ads-cli/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: google-ads-cli
+description: Google Ads 广告投放管理。创建广告系列、广告组、关键词，查看广告效果数据。当用户需要投放广告、管理 Google Ads、分析广告效果时使用此技能。
+---
+
+# Google Ads CLI 使用指南
+
+## 前置条件
+
+```bash
+npm install -g @optima-chat/google-ads-cli@latest
+google-ads auth login
+```
+
+## 核心命令
+
+### 账号管理
+
+```bash
+# 创建账号
+google-ads account create --email your@gmail.com --name "公司名称"
+
+# 验证账号
+google-ads account check
+
+# 查看配置
+google-ads config show
+```
+
+### 广告系列
+
+```bash
+# 列出广告系列
+google-ads campaign list
+
+# 创建广告系列
+google-ads campaign create -n "广告系列名称" -b 50
+
+# 查看广告系列详情
+google-ads campaign get <campaign-id>
+
+# 暂停/启用广告系列
+google-ads campaign pause <campaign-id>
+google-ads campaign enable <campaign-id>
+```
+
+### 广告组
+
+```bash
+# 列出广告组
+google-ads adgroup list --campaign-id <campaign-id>
+
+# 创建广告组
+google-ads adgroup create --campaign-id <campaign-id> -n "广告组名称"
+```
+
+### 关键词
+
+```bash
+# 列出关键词
+google-ads keyword list
+
+# 添加关键词
+google-ads keyword add --adgroup-id <adgroup-id> -k "关键词1,关键词2"
+```
+
+### 效果分析
+
+```bash
+# GAQL 查询
+google-ads query -q "SELECT campaign.id, campaign.name, metrics.impressions FROM campaign" --pretty
+
+# 查看效果报告
+google-ads report --campaign-id <campaign-id> --days 7
+```
+
+## 典型流程
+
+### 创建新广告
+
+```bash
+# 1. 创建广告系列
+google-ads campaign create -n "产品推广" -b 100
+# 获得 campaign_id
+
+# 2. 创建广告组
+google-ads adgroup create --campaign-id <campaign-id> -n "核心关键词组"
+# 获得 adgroup_id
+
+# 3. 添加关键词
+google-ads keyword add --adgroup-id <adgroup-id> -k "产品名称,品牌词,行业词"
+
+# 4. 验证
+google-ads campaign list
+```
+
+## 注意事项
+
+- 所有命令默认 JSON 输出
+- 预算单位为美元
+- 新账号需要先设置账单信息才能投放广告