@optima-chat/optima-agent 0.8.7 → 0.8.9

package/.claude/skills/homepage/SKILL.md

@@ -56,12 +56,16 @@ Homepage
 **images 数组元素**：
 | 字段 | 必填 | 说明 |
 |------|------|------|
-| url | ✓ | 桌面端图片 URL |
+| url | △ | 桌面端图片 URL（url 或 media_id 至少一个） |
+| media_id | △ | 桌面端已有图片 ID（从 homepage get 获取，用于 update-images 全量替换） |
 | mobile_url | | 手机端专用图片 URL（3:4 竖向，可选） |
+| mobile_media_id | | 手机端已有图片 ID（从 homepage get 获取，用于 update-images 全量替换） |
 | alt | ✓ | 图片描述（SEO + 可访问性） |
 | action_type | ✓ | 点击动作类型（见下方） |
 | action_value | | 动作目标值 |
 
+> △ = url 和 media_id 至少提供一个。新上传的图使用 url，已有的图使用 media_id。
+
 **action_type 取值**：
 | 值 | 说明 | action_value |
 |----|------|--------------|
@@ -71,13 +75,24 @@ Homepage
 | `url` | 跳转到 URL | 完整 URL 或相对路径 |
 | `section` | 滚动到页面区块 | section handle |
 
-**示例**：
+**创建时的示例**（使用 url）：
 ```json
 {
   "images": [
     {"url": "https://cdn.../summer.jpg", "mobile_url": "https://cdn.../summer-mobile.jpg", "alt": "夏日促销", "action_type": "collection", "action_value": "summer-sale"},
-    {"url": "https://cdn.../promo.jpg", "alt": "活动页面", "action_type": "url", "action_value": "https://promo.example.com/event"},
-    {"url": "https://cdn.../hero.jpg", "alt": "品牌形象", "action_type": "none", "action_value": null}
+    {"url": "https://cdn.../promo.jpg", "alt": "活动页面", "action_type": "url", "action_value": "https://promo.example.com/event"}
+  ],
+  "autoplay": true,
+  "interval": 5000
+}
+```
+
+**`homepage get` 返回的真实格式**（url 已被后端自动转为 media_id）：
+```json
+{
+  "images": [
+    {"media_id": "med_abc123", "mobile_media_id": "med_def456", "alt": "夏日促销", "action_type": "collection", "action_value": "summer-sale"},
+    {"media_id": "med_ghi789", "alt": "活动页面", "action_type": "url", "action_value": "https://promo.example.com/event"}
   ],
   "autoplay": true,
   "interval": 5000
@@ -174,6 +189,9 @@ Homepage
 - "添加集合商品" → `commerce homepage create-collection-products --title "新品" --lang <识别语言> --slug new-arrivals`
 - "添加特色推荐" → `commerce homepage create-featured --title "推荐" --lang <识别语言> --target-type collection --target-handle xx --cta "查看" --image-url "..."`
 - "更新轮播图图片" → `commerce homepage update-images --id xx --images '[...]'`
+- "给第N张 banner 加手机图" → `commerce homepage patch-banner-image --id xx --index N --mobile-url "https://..."`
+- "改第N张图的描述" → `commerce homepage patch-banner-image --id xx --index N --alt "新描述"`
+- "移除第N张图的手机版" → `commerce homepage patch-banner-image --id xx --index N --remove-mobile-url`
 - "修改区块标题" → `commerce i18n homepage set --section-id xx --lang <识别语言> --title "新标题"`
 - "给区块添加描述" → `commerce i18n homepage set --section-id xx --lang <识别语言> --description "描述"`
 - "调整区块顺序" → `commerce homepage reorder --moves '[{"section_id":"id1","new_position":0}]'`
@@ -202,7 +220,8 @@ Homepage
 - `commerce homepage reorder --moves <json>` - 重新排序（JSON 格式：`[{"section_id":"xx","new_position":0}]`）
 
 ### 区块设置
-- `commerce homepage update-images --id <id> --images <json>` - 更新 banner 图片
+- `commerce homepage update-images --id <id> --images <json>` - 全量替换 banner 图片（支持 url 或 media_id）
+- `commerce homepage patch-banner-image --id <id> --index <N> [--url <url>] [--mobile-url <url>] [--remove-mobile-url] [--alt <text>] [--action-type <type>] [--action-value <value>]` - 更新单张 banner 图片（index 从 1 开始）
 - `commerce homepage update-collections --id <id> --slugs <slugs>` - 更新 collections 集合
 - `commerce homepage update-target --id <id> --type <type> --handle <handle>` - 更新 featured 目标
 - `commerce homepage patch-settings --id <id> --settings <json>` - 通用设置更新
@@ -316,11 +335,43 @@ commerce i18n homepage set \
   --description "New description"
 ```
 
+## Banner 图片更新：命令选择指南
+
+| 我要做什么 | 用哪个命令 | 说明 |
+|-----------|-----------|------|
+| 给第 N 张图加/换手机版 | `patch-banner-image --index N --mobile-url "https://..."` | 最简单，无需读取现有数据 |
+| 改第 N 张图的 alt/action | `patch-banner-image --index N --alt "..."` | 同上 |
+| 换第 N 张桌面图（新 URL） | `patch-banner-image --index N --url "https://..."` | 后端自动转 media_id |
+| 移除第 N 张图的手机版 | `patch-banner-image --index N --remove-mobile-url` | 设为 null |
+| 添加/删除图片 | `update-images --images '[完整数组]'` | 全量替换，需透传所有现有字段 |
+| 重新排列图片顺序 | `update-images --images '[新顺序数组]'` | 同上 |
+
+**关键区别**：
+- `patch-banner-image` 只接受 URL（`--url`, `--mobile-url`），不接受 `media_id`。后端自动将 URL 转为 media_id
+- `update-images` 接受 `url` 和 `media_id`。已有的图用 `media_id` 透传，新图用 `url`
+
+### update-images 全量替换示例（含 media_id 透传）
+
+**场景**：给已有的 2 张 banner 增加第 3 张图
+
+1. 先 `commerce homepage get --id section_xxx` 获取现有图片（含 media_id）
+2. 构建完整数组，已有图原样透传 media_id，新图用 url：
+
+```bash
+commerce homepage update-images --id section_xxx --images '[
+  {"media_id":"med_abc123","mobile_media_id":"med_def456","alt":"夏日促销","action_type":"collection","action_value":"summer-sale"},
+  {"media_id":"med_ghi789","alt":"活动页面","action_type":"url","action_value":"https://promo.example.com/event"},
+  {"url":"https://new-upload-url.../img3.jpg","alt":"新图片","action_type":"none"}
+]'
+```
+
+**注意：全量替换会覆盖整个 images 数组。漏传的字段（如 `mobile_media_id`）会导致手机图丢失。务必从 `homepage get` 完整复制现有图片的所有字段。**
+
 ## 注意事项
 
 - **区块顺序**：使用 `reorder` 调整，position 从 0 开始
 - **模板切换**：会创建新区块并停用旧区块，谨慎操作
-- **图片格式**：banner images 需要完整的 JSON 数组，每个元素必须有 url 和 alt
+- **media_id 生命周期**：上传图片（`upload file`）→ 返回临时 URL（无 media_id）→ 传给 banner API → 后端自动转为 media_id → 后续 `homepage get` 返回 media_id
 - **手机端图片**：可选提供 mobile_url（3:4 竖向），有 mobile_url 时手机端显示竖向大图，无则保持 16:9 横向
 - **集合引用**：确保引用的 collection slug 存在，否则前端可能显示空
 - **删除确认**：删除操作需要 `--yes` 参数

package/.claude/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-description: Review management and moderation. View, approve, reject, and respond to customer reviews. Handle featured reviews, reports, and settings. Use when user needs to moderate reviews, respond to feedback, manage review reports, configure auto-approval, or view review statistics.
+description: Review management, moderation, and AI review generation. View, approve, reject, and respond to customer reviews. Handle featured reviews, reports, and settings. Generate AI reviews for products. Use when user needs to moderate reviews, respond to feedback, manage review reports, configure auto-approval, view review statistics, or generate AI reviews.
 ---
 
 # Commerce CLI - Review Management
@@ -18,6 +18,10 @@ description: Review management and moderation. View, approve, reject, and respon
 - "查看举报" → `commerce review reports --status pending`
 - "查看评价设置" → `commerce review get-settings`
 - "开启自动审核" → `commerce review update-settings --auto-approve`
+- "生成评价" / "给商品刷评价" → `commerce review generate`
+- "创建一条评价" → `commerce review create`
+- "给产品生成5条评价" → 先 `commerce product get` 了解产品 → 再 `commerce review generate`
+- "查看AI评价" → `commerce review list --ai-generated`
 
 ### 场景决策表
 
@@ -31,6 +35,7 @@ description: Review management and moderation. View, approve, reject, and respon
 | 查看统计 | `review stats` | 监控平均分和评分分布趋势 |
 | 查看设置 | `review get-settings` | 了解当前自动审核等配置 |
 | 开启自动审核 | `review update-settings --auto-approve` | 所有评价自动通过 |
+| AI 生成评价 | `review generate --product-id xxx --reviews '[...]' --spread-days 30` | 先查产品信息，自然评分分布，混合风格 |
 
 ### 标准评价管理流程
 1. **每日审核** - `commerce review list --status pending` 查看待审核
@@ -47,6 +52,63 @@ description: Review management and moderation. View, approve, reject, and respon
 4. **回复评价** - `commerce review respond` 真诚道歉并提出解决方案
 5. **跟进改进** - 记录问题，优化产品或服务
 
+### AI 评价生成流程
+1. **了解产品** - `commerce product get --id prod_xxx` 获取产品名称、描述、卖点
+2. **构思评价** - 根据产品特点构思多样化评价（不同评分、角度、风格、买家名字）
+3. **批量提交** - `commerce review generate` 一次提交所有评价，自动分散时间
+
+**单条创建示例：**
+```bash
+commerce review create \
+  --product-id prod_123 \
+  --rating 5 \
+  --title "品质出色" \
+  --content "收到后非常满意，做工精细，材质很好，值得推荐！" \
+  --customer-name "张明" \
+  --ai-generated
+```
+
+**批量生成示例（推荐）：**
+```bash
+commerce review generate \
+  --product-id prod_123 \
+  --spread-days 30 \
+  --reviews '[
+    {"rating":5,"title":"品质出色","content":"收到后非常满意，做工精细，材质很好，值得推荐给朋友！","customer_name":"张明"},
+    {"rating":4,"title":"性价比高","content":"整体不错，这个价位能买到这样的质量很满意。包装也很用心。","customer_name":"李华"},
+    {"rating":5,"title":"超出预期","content":"比想象中好很多！细节处理得很到位，能看出品牌的用心。已经推荐给同事了。","customer_name":"王芳"},
+    {"rating":4,"title":"物流很快","content":"下单第二天就到了，包装完好无损。产品本身也挺好用的，会回购。","customer_name":"陈磊"},
+    {"rating":3,"title":"还行吧","content":"一般般，没有特别惊艳但也没什么问题，中规中矩的产品。","customer_name":"赵静"}
+  ]'
+```
+
+## AI 评价质量指标
+
+生成 AI 评价时，必须遵循以下质量标准：
+
+| 维度 | 标准 |
+|------|------|
+| 评分分布 | 自然分布：5星 60%、4星 30%、3星 10%，避免全5星 |
+| 内容多样性 | 每条评价角度不同（材质、外观、使用体验、性价比、物流、包装等） |
+| 风格多样性 | 混合专业型、口语型、简短型、详细型 |
+| 名字真实性 | 使用目标市场常见姓名，避免重复 |
+| 长度适中 | 50-200 字，避免过短或过长 |
+| 语言一致 | 评价语言与店铺目标市场一致 |
+| 时间分散 | 使用 `--spread-days` 分散评价时间，默认 30 天 |
+
+## AI 评价风格模板
+
+每次批量生成时混合使用不同风格，使评价看起来来自不同用户：
+
+- **专业型**: 客观描述产品特点和功能，用词准确，适合电子产品、工具类
+  > 例："这款蓝牙耳机的降噪效果令人印象深刻，续航实测达到标称的8小时，佩戴舒适度也很好。"
+- **口语型**: 像真实买家的日常用语，带有个人情感，适合服饰、日用品
+  > 例："哇真的好好看！颜色跟图片一模一样，穿上特别显瘦，闺蜜都问我在哪买的～"
+- **简短型**: 1-2 句话 + 评分，模拟快速评价
+  > 例："质量不错，好评。"
+- **详细型**: 多角度描述使用体验，150-200 字，提供丰富参考
+  > 例："用了一周来评价。首先包装很精致，打开就能感觉到品质。实际使用中，XX功能非常实用，解决了我之前YY的困扰。唯一小遗憾是ZZ方面还有提升空间，但整体性价比很高，推荐购买。"
+
 ## 卓越标准
 
 ### 评价管理质量指标
@@ -98,6 +160,25 @@ commerce review respond --id review_123 --content "非常抱歉给您带来了
 - **恶意竞争** → 多个可疑评价来自同一IP则删除
 - **真实差评** → 即使被举报也不应删除，驳回举报
 
+### AI 评价生成错误
+
+❌ **错误做法 - 全部5星、内容雷同**：
+```bash
+# 所有评价都是5星，内容模板化，一看就是假的
+commerce review generate --product-id prod_123 --reviews '[
+  {"rating":5,"title":"很好","content":"很好很满意","customer_name":"用户A"},
+  {"rating":5,"title":"不错","content":"很好很满意","customer_name":"用户B"},
+  {"rating":5,"title":"好评","content":"很好很满意","customer_name":"用户C"}
+]'
+```
+
+✅ **正确做法 - 多样化评分、内容、风格**：
+- 评分分布自然（5星60%、4星30%、3星10%）
+- 每条评价从不同角度评价（材质、外观、使用感受、物流等）
+- 混合不同风格（专业、口语、简短、详细）
+- 使用真实感的姓名，不重复
+- 先 `product get` 了解产品卖点再构思
+
 ## 命令参考
 
 ### 评价查看
@@ -120,6 +201,10 @@ commerce review respond --id review_123 --content "非常抱歉给您带来了
 - `commerce review reports` - 查看举报
 - `commerce review handle-report` - 处理举报
 
+### AI 评价生成
+- `commerce review create` - 创建单条评价（商家/AI）
+- `commerce review generate` - 批量生成评价（推荐，支持时间分散）
+
 ### 评价设置
 - `commerce review get-settings` - 查看评价设置
 - `commerce review update-settings` - 更新评价设置

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/optima-agent",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "基于 Claude Agent SDK 的电商运营 AI 助手",
   "type": "module",
   "main": "dist/src/index.js",