@fwgi/openclaw-x-marketing 1.0.0

package/README.md

@@ -0,0 +1,69 @@
+# X Marketing OpenClaw Plugin
+
+X(Twitter) 营销管理助手 — 账号信息查看、受众管理（导入/筛选/分组/标签/营销活动）
+
+## 版本
+
+v4.0.0
+
+## 功能概览
+
+| 模块 | 工具数 | 说明 |
+|------|--------|------|
+| 连接验证 | 1 | API Key 验证 |
+| 账号信息 | 3 | 账号列表/详情/字段说明 |
+| 受众管理 | 14 | 导入/筛选/分组/标签/营销活动 |
+| **合计** | **18** | |
+
+## 认证方式
+
+通过 `x-api-key` 请求头调用后端 API，无需登录或 OAuth 授权。
+
+## 安装
+
+### 方式一：npm 安装（推荐）
+
+```bash
+openclaw plugins install @fwgi/openclaw-x-marketing
+```
+
+### 方式二：本地安装
+
+```bash
+chmod +x install.sh
+./install.sh
+```
+
+安装时会提示输入 API Key，也可以首次使用时由机器人引导配置。
+
+## 配置
+
+| 配置项 | 环境变量 | 说明 |
+|--------|----------|------|
+| apiBaseUrl | X_MARKETING_API_BASE_URL | 后端地址，默认 https://api-backend.fwgi.ai |
+| apiKey | X_MARKETING_API_KEY | x-api-key 密钥 |
+| requestTimeoutMs | X_MARKETING_TIMEOUT_MS | 超时(ms)，默认 30000 |
+
+## 工具清单
+
+### 连接与账号信息
+- `x_verify_connection` — 验证 API Key
+- `x_account_list` — 获取账号列表
+- `x_account_detail` — 获取账号详情
+- `x_get_field_info` — 获取字段说明
+
+### 受众管理
+- `x_audience_list` — 受众列表（多维筛选）
+- `x_audience_import_url` — 从用户关注列表导入
+- `x_audience_interactive_users` — 从推文互动用户导入
+- `x_audience_search_keyword` — 关键词搜索导入
+- `x_audience_group_create` — 创建分组
+- `x_audience_group_list` — 分组列表
+- `x_audience_group_detail` — 分组详情
+- `x_audience_group_update` — 更新分组
+- `x_audience_group_delete` — 删除分组
+- `x_audience_interest_tags` — 标签统计
+- `x_audience_interest_tags_add` — 添加标签
+- `x_audience_interest_tags_remove` — 移除标签
+- `x_audience_add_to_activity` — 添加到营销活动
+- `x_audience_activity_progress` — 查询活动进度

package/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: x-marketing
+description: X(Twitter) 营销管理助手 — 查看账号信息并管理受众（导入/筛选/分组/标签/营销活动）
+version: 4.0.0
+---
+
+你是 **X 营销管理助手**，帮用户在 X (Twitter) 平台上高效管理营销账号和受众资源。
+
+## ⚡ 使用前须知
+
+> 本插件通过 **x-api-key** 验证身份，无需登录或 OAuth 授权。
+> 每次会话开始，请先调用 **x_verify_connection** 确认 Key 有效。
+
+## 🔧 工具清单
+
+### 连接与账号信息（共 4 个）
+
+| 工具 | 用途 | 速度 |
+|------|------|------|
+| x_verify_connection | 验证 API Key 并获取用户信息 | 🟢 快 |
+| x_account_list | 获取 X 账号列表（支持按 handle/名称/邮箱筛选） | 🟢 快 |
+| x_account_detail | 获取账号详情（audiences、pillars、kols 等完整配置） | 🟢 快 |
+| x_get_field_info | 获取账号字段中英文说明及示例 | 🟢 快 |
+
+### 受众管理（共 14 个）
+
+| 工具 | 用途 | 速度 |
+|------|------|------|
+| x_audience_list | 受众列表（多维筛选：关键词/DM/机器人分/标签/活跃度等） | 🟢 快 |
+| x_audience_import_url | 通过 X 用户主页 URL 导入关注列表 | 🟡 慢 |
+| x_audience_interactive_users | 根据推文获取转发/点赞用户并导入 | 🟡 慢 |
+| x_audience_search_keyword | 关键词搜索推文作者并导入（频率限制>30s） | 🟡 慢 |
+| x_audience_group_create | 创建受众分组（动态/静态） | 🟢 快 |
+| x_audience_group_list | 获取分组列表 | 🟢 快 |
+| x_audience_group_detail | 获取分组详情 | 🟢 快 |
+| x_audience_group_update | 更新分组信息和筛选条件 | 🟢 快 |
+| x_audience_group_delete | 删除分组⚠️不可逆 | 🟢 快 |
+| x_audience_interest_tags | 获取受众兴趣标签统计 | 🟢 快 |
+| x_audience_interest_tags_add | 为受众添加兴趣标签 | 🟢 快 |
+| x_audience_interest_tags_remove | 移除受众兴趣标签 | 🟢 快 |
+| x_audience_add_to_activity | 将受众添加到营销活动（异步） | 🟡 慢 |
+| x_audience_activity_progress | 查询活动添加进度 | 🟢 快 |
+
+---
+
+## 📋 标准操作流程
+
+### 第 0 步：验证连接
+
+```
+→ x_verify_connection
+← ✅ API Key 验证通过！ 账号: xxx user_id: xxx
+```
+
+如果验证失败，提示用户检查 API Key 配置。
+
+### 第 1 步：查看账号信息
+
+获取用户的 X 账号列表和详细配置：
+```
+→ x_account_list
+← 账号列表（含 account_id、handle 等）
+
+→ x_account_detail { account_id: 255 }
+← 完整配置（audiences、pillars、kols、tweetStyle）
+```
+
+如需了解字段含义：
+```
+→ x_get_field_info
+← 各字段的中英文说明和示例
+```
+
+### 第 2 步：受众管理
+
+#### 2.1 查看受众
+
+```
+→ x_audience_list { account_id: 255 }
+← 受众列表（支持 keyword/can_dm/bot_score/interest_tags/activity 等筛选）
+```
+
+#### 2.2 导入受众（三种方式）
+
+**方式一：从用户关注列表导入**
+```
+→ x_audience_import_url { account_id: 255, x_url: "https://x.com/elonmusk" }
+← 导入结果，has_more=true 时使用 next_cursor 继续
+```
+
+**方式二：从推文互动用户导入**
+```
+→ x_audience_interactive_users { account_id: 255, tweet_url_or_id: "https://x.com/user/status/123" }
+```
+
+**方式三：关键词搜索导入**（注意频率限制，间隔>30s）
+```
+→ x_audience_search_keyword { account_id: 255, keyword: "AI agent" }
+```
+
+#### 2.3 分组管理
+
+```
+→ x_audience_group_create { name: "AI兴趣组", filter_conditions: { interest_tags: "AI" } }
+→ x_audience_group_list
+→ x_audience_group_detail { group_id: 1 }
+→ x_audience_group_update { group_id: 1, name: "AI技术组" }
+→ x_audience_group_delete { group_id: 1 }  ⚠️ 不可逆
+```
+
+#### 2.4 兴趣标签管理
+
+```
+→ x_audience_interest_tags { account_id: 255 }
+← 标签统计列表
+
+→ x_audience_interest_tags_add { account_id: 255, following_id: 100, tags: ["AI", "Creator"] }
+→ x_audience_interest_tags_remove { account_id: 255, following_id: 100, tag_name: "Creator" }
+```
+
+#### 2.5 营销活动
+
+```
+→ x_audience_add_to_activity { activity_id: 10, account_id: 255, user_ids: [100,101,102] }
+← 异步操作
+
+→ x_audience_activity_progress { activity_id: 10, account_id: 255 }
+← 进度：已完成/总计
+```
+
+---
+
+## ⚠️ 注意事项
+
+1. **API Key** — 所有操作依赖 x-api-key，验证失败时引导用户检查配置
+2. **频率限制** — search-by-keyword 有严格限制（code 5006），建议间隔 30 秒以上
+3. **慢速操作** — import_url、interactive_users、search_keyword、add_to_activity 超时为 60s
+4. **分页** — audience_list 支持 page/page_size，import_url 使用 cursor 分页
+5. **不可逆操作** — group_delete 删除分组不可恢复，执行前确认
+6. **interactive_users 限制** — 依赖 RapidAPI 外部服务，部分环境可能返回 total=0

package/docs/ref-tools.md

@@ -0,0 +1,369 @@
+# X Marketing 工具参考手册
+
+> 版本：v4.0.0 | 共 18 个工具 | 认证方式：x-api-key
+
+---
+
+## 目录
+
+- [A. 连接验证](#a-连接验证)
+- [B. 账号信息](#b-账号信息)
+- [C. 受众管理](#c-受众管理)
+  - [C.1 受众列表与导入](#c1-受众列表与导入)
+  - [C.2 分组管理](#c2-分组管理)
+  - [C.3 兴趣标签](#c3-兴趣标签)
+  - [C.4 营销活动](#c4-营销活动)
+
+---
+
+## A. 连接验证
+
+### x_verify_connection
+
+验证 API Key 有效性并获取当前用户信息。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `GET /v1/api/checkLogin` |
+| 参数 | 无 |
+| 速度 | 🟢 快（15s 超时） |
+
+**返回示例：**
+```
+✅ API Key 验证通过！
+账号: waynetan0427@gmail.com
+user_id: 15
+后端: https://api-backend.fwgi.ai
+```
+
+---
+
+## B. 账号信息
+
+### x_account_list
+
+获取当前用户的 X 账号列表。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `GET /v1/api/twitter/auto/list` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| handle | string | 否 | X 用户名筛选 |
+| display_name | string | 否 | 显示名称筛选 |
+| email | string | 否 | 关联邮箱筛选 |
+
+**返回字段：** account_id, handle, display_name, email, avatar, status 等
+
+---
+
+### x_account_detail
+
+获取 X 账号完整详情。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `GET /v1/api/twitter/auto/detail` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| account_id | number | ✅ | 账号 ID |
+
+**返回字段：** 基础信息 + audiences, pillars, kols, templates, tweetStyle, postingSchedule, account_actions 等完整配置
+
+---
+
+### x_get_field_info
+
+获取账号表单字段中英文说明及示例。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `GET /v1/api/twitter/auto/fieldInfo` |
+| 参数 | 无 |
+| 速度 | 🟢 快 |
+
+**返回：** 各字段的 key、中文名称、英文名称、说明、示例值
+
+---
+
+## C. 受众管理
+
+### C.1 受众列表与导入
+
+#### x_audience_list
+
+获取受众列表，支持多维度筛选。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `GET /v1/api/twitter/following/list` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| account_id | number | ✅ | 账号 ID |
+| keyword | string | 否 | 关键词（匹配用户名、名称、简介） |
+| can_dm | string | 否 | 是否可私信（true/false） |
+| bot_score | string | 否 | 机器人评分：safe/medium/risk |
+| interest_tags | string | 否 | 兴趣标签，多个用逗号分隔 |
+| activity_min | number | 否 | 最小活跃度（0-100） |
+| activity_max | number | 否 | 最大活跃度（0-100） |
+| activity_days | number | 否 | 活跃度天数，默认 30 |
+| group_id | number | 否 | 按分组筛选 |
+| source_username | string | 否 | 按来源用户名筛选 |
+| is_send | string | 否 | 发送状态筛选 |
+| page | number | 否 | 页码，默认 1 |
+| page_size | number | 否 | 每页数量，默认 20 |
+
+---
+
+#### x_audience_import_url
+
+通过 X 用户主页 URL 导入其关注列表为受众。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `POST /v1/api/twitter/following/add` |
+| 速度 | 🟡 慢（60s 超时） |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| account_id | number | ✅ | 账号 ID |
+| x_url | string | ✅ | X 用户主页 URL |
+| cursor | string | 否 | 分页游标 |
+| count | number | 否 | 期望每页数量，默认 20 |
+
+**注意：** count 为建议值，实际返回数量可能不同。has_more=true 时使用 next_cursor 继续导入。
+
+---
+
+#### x_audience_interactive_users
+
+根据推文获取转发/点赞用户并导入。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `POST /v1/api/twitter/following/interactive-users` |
+| 速度 | 🟡 慢（60s 超时） |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| account_id | number | ✅ | 账号 ID |
+| tweet_url_or_id | string | ✅ | 推文 URL 或推文 ID |
+| count | number | 否 | 返回数量，默认 20 |
+
+**注意：** 依赖 RapidAPI 外部服务，部分环境可能返回 total=0。
+
+---
+
+#### x_audience_search_keyword
+
+关键词搜索推文作者并导入。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `POST /v1/api/twitter/following/search-by-keyword` |
+| 速度 | 🟡 慢（60s 超时） |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| account_id | number | ✅ | 账号 ID |
+| keyword | string | ✅ | 搜索关键词 |
+| count | number | 否 | 返回数量，默认 20 |
+
+**⚠️ 频率限制：** 此接口有严格频率限制（返回 code 5006），建议调用间隔大于 30 秒。
+
+---
+
+### C.2 分组管理
+
+#### x_audience_group_create
+
+创建受众分组。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `POST /v1/api/twitter/following/group/create` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | string | ✅ | 分组名称 |
+| description | string | 否 | 分组描述 |
+| filter_conditions | object | 否 | 动态分组筛选条件 |
+| user_ids | number[] | 否 | 静态分组的受众 ID 列表 |
+
+**filter_conditions 字段：** account_id, keyword, can_dm, bot_score, interest_tags, activity_min, activity_max, activity_days
+
+---
+
+#### x_audience_group_list
+
+获取分组列表。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `GET /v1/api/twitter/following/group/list` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| page | number | 否 | 页码，默认 1 |
+| page_size | number | 否 | 每页数量，默认 20 |
+
+---
+
+#### x_audience_group_detail
+
+获取分组详情。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `GET /v1/api/twitter/following/group/detail` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| group_id | number | ✅ | 分组 ID |
+
+---
+
+#### x_audience_group_update
+
+更新分组信息。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `POST /v1/api/twitter/following/group/update` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| group_id | number | ✅ | 分组 ID |
+| name | string | 否 | 新名称 |
+| description | string | 否 | 新描述 |
+| filter_conditions | object | 否 | 新筛选条件 |
+
+---
+
+#### x_audience_group_delete
+
+删除分组。⚠️ 不可逆操作。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `POST /v1/api/twitter/following/group/delete` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| group_id | number | ✅ | 分组 ID |
+
+---
+
+### C.3 兴趣标签
+
+#### x_audience_interest_tags
+
+获取受众兴趣标签统计。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `GET /v1/api/twitter/following/interest-tags` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| account_id | number | ✅ | 账号 ID |
+
+---
+
+#### x_audience_interest_tags_add
+
+为受众添加兴趣标签。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `POST /v1/api/twitter/following/interest-tags/add` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| account_id | number | ✅ | 账号 ID |
+| following_id | number | ✅ | 受众 ID |
+| tags | string[] | ✅ | 标签列表 |
+| source | string | 否 | 来源，默认 manual |
+
+---
+
+#### x_audience_interest_tags_remove
+
+移除受众兴趣标签。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `POST /v1/api/twitter/following/interest-tags/remove` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| account_id | number | ✅ | 账号 ID |
+| following_id | number | ✅ | 受众 ID |
+| tag_name | string | ✅ | 标签名称 |
+
+---
+
+### C.4 营销活动
+
+#### x_audience_add_to_activity
+
+将受众添加到营销活动（异步操作）。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `POST /v1/api/twitter/following/add-to-activity` |
+| 速度 | 🟡 慢（60s 超时） |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| activity_id | number | ✅ | 活动 ID（task_id） |
+| account_id | number | ✅ | 账号 ID |
+| user_ids | number[] | 否* | 受众 ID 列表 |
+| filter_conditions | object | 否* | 筛选条件 |
+| send_type | string | 否 | manual/immediate，默认 manual |
+
+*user_ids 和 filter_conditions 至少提供其一。
+
+---
+
+#### x_audience_activity_progress
+
+查询受众添加到活动的进度。
+
+| 项 | 值 |
+|----|----|
+| 端点 | `GET /v1/api/twitter/following/add-to-activity/progress` |
+| 速度 | 🟢 快 |
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| activity_id | number | ✅ | 活动 ID |
+| account_id | number | ✅ | 账号 ID |
+
+**返回字段：** total, completed, failed, in_progress
+
+---
+
+## 错误码参考
+
+| code | 含义 | 处理方式 |
+|------|------|----------|
+| 200 | 成功 | - |
+| 4001 | API Key 无效/过期 | 检查 apiKey 配置 |
+| 4007 | 资源不存在 | 检查 ID 参数 |
+| 5006 | 频率限制 | 等待 30 秒后重试 |
+| 500 | 服务器内部错误 | 检查参数合法性或联系运维 |