@fwgi/openclaw-x-marketing 1.0.0

package/docs/ref-workflow.md

@@ -0,0 +1,193 @@
+# X Marketing 工作流参考
+
+> 版本：v4.0.0 | 认证方式：x-api-key
+
+---
+
+## 工作流总览
+
+```
+验证连接 → 查看账号 → 受众管理（导入/筛选/分组/标签/活动）
+```
+
+---
+
+## 1. 会话初始化
+
+每次对话开始时先确认连接：
+
+```
+x_verify_connection
+  → ✅ 通过 → 继续
+  → ❌ 失败 → 引导用户检查 API Key
+```
+
+---
+
+## 2. 账号信息查看
+
+**场景：用户想查看已有的 X 账号**
+
+```
+x_account_list
+  → 展示账号列表（account_id, handle, display_name）
+  → 用户选择一个账号
+x_account_detail { account_id }
+  → 返回完整配置（audiences, pillars, kols, tweetStyle 等）
+```
+
+**场景：用户不理解某个字段的含义**
+
+```
+x_get_field_info
+  → 返回所有字段的中英文说明和示例
+```
+
+---
+
+## 3. 受众管理
+
+### 3.1 查看受众
+
+```
+x_audience_list { account_id }
+  → 默认返回第一页 20 条
+  → 支持筛选：keyword, can_dm, bot_score, interest_tags, activity_min/max
+  → 翻页：page=2, page_size=50
+```
+
+### 3.2 导入受众
+
+**方式一：从 KOL 关注列表导入**
+```
+x_audience_import_url { account_id, x_url: "https://x.com/username" }
+  → 返回导入结果 + has_more + next_cursor
+  → 如果 has_more=true：
+    x_audience_import_url { account_id, x_url, cursor: "下一页游标" }
+```
+
+**方式二：从推文互动用户导入**
+```
+x_audience_interactive_users { account_id, tweet_url_or_id }
+  → 返回 total, saved, updated, failed
+  ⚠️ 依赖 RapidAPI，可能返回 total=0
+```
+
+**方式三：关键词搜索导入**
+```
+x_audience_search_keyword { account_id, keyword: "AI agent" }
+  → 返回 total, saved, updated, failed
+  ⚠️ 严格频率限制，间隔 > 30s，否则 code 5006
+```
+
+### 3.3 分组管理
+
+**创建动态分组（基于条件自动匹配）：**
+```
+x_audience_group_create {
+  name: "高活跃AI兴趣组",
+  filter_conditions: {
+    account_id: 255,
+    interest_tags: "AI",
+    activity_min: 50
+  }
+}
+```
+
+**创建静态分组（指定用户列表）：**
+```
+x_audience_group_create {
+  name: "VIP用户",
+  user_ids: [100, 101, 102]
+}
+```
+
+**查看/更新/删除：**
+```
+x_audience_group_list
+x_audience_group_detail { group_id }
+x_audience_group_update { group_id, name: "新名称" }
+x_audience_group_delete { group_id }  ⚠️ 不可逆
+```
+
+### 3.4 兴趣标签
+
+```
+x_audience_interest_tags { account_id }
+  → 标签统计列表
+
+x_audience_interest_tags_add { account_id, following_id, tags: ["AI", "Creator"] }
+  → 添加标签
+
+x_audience_interest_tags_remove { account_id, following_id, tag_name: "Creator" }
+  → 移除单个标签
+```
+
+### 3.5 营销活动
+
+**添加受众到活动：**
+```
+x_audience_add_to_activity {
+  activity_id: 10,
+  account_id: 255,
+  user_ids: [100, 101, 102],
+  send_type: "manual"
+}
+  → 异步操作
+```
+
+**轮询进度：**
+```
+x_audience_activity_progress { activity_id: 10, account_id: 255 }
+  → total, completed, failed, in_progress
+```
+
+---
+
+## 4. 典型对话流程示例
+
+### 示例 A：「帮我看看我有哪些 X 账号」
+
+```
+1. x_verify_connection → 验证通过
+2. x_account_list → 返回 3 个账号
+3. 展示列表，询问是否需要查看某个账号详情
+4. x_account_detail { account_id: 255 } → 展示完整配置
+```
+
+### 示例 B：「从 @elonmusk 的关注列表导入受众」
+
+```
+1. x_verify_connection → 验证通过
+2. x_audience_import_url { account_id: 255, x_url: "https://x.com/elonmusk" }
+3. 如果 has_more=true，询问是否继续导入
+4. x_audience_list { account_id: 255 } → 确认受众已更新
+```
+
+### 示例 C：「给活跃度高的 AI 受众创建一个分组」
+
+```
+1. x_verify_connection → 验证通过
+2. x_audience_group_create {
+     name: "高活跃AI粉丝",
+     filter_conditions: {
+       account_id: 255,
+       interest_tags: "AI",
+       activity_min: 70
+     }
+   }
+3. x_audience_group_detail { group_id } → 确认匹配数量
+```
+
+---
+
+## 5. 注意事项
+
+| 事项 | 说明 |
+|------|------|
+| API Key | 所有请求需携带有效 x-api-key |
+| 超时 | 普通操作 30s，导入/搜索/活动操作 60s |
+| 频率限制 | search-by-keyword 需间隔 30s+ |
+| 分页 | audience_list 用 page/page_size，import_url 用 cursor |
+| 不可逆 | group_delete 删除后无法恢复 |
+| 外部依赖 | interactive_users 依赖 RapidAPI |