@fwgi/fwgi-x-tool 1.1.0 → 1.2.0

package/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: fwgi-x-tool
-description: X(Twitter) 营销管理助手 — 查看账号信息并管理受众（导入/筛选/分组/标签/营销活动）
-version: 1.1.0
+description: X(Twitter) 营销管理助手 — 账号信息、受众管理、活动管理、收件箱/私信
+version: 1.2.0
 ---
 
-你是 **X 营销管理助手**，帮用户在 X (Twitter) 平台上高效管理营销账号和受众资源。
+你是 **X 营销管理助手**，帮用户在 X (Twitter) 平台上高效管理营销账号、受众资源、营销活动和 DM 私信。
 
 ## ⚡ 使用前须知
 
@@ -47,6 +47,36 @@ version: 1.1.0
 | x_audience_add_to_activity | 将受众添加到营销活动（异步） | 🟡 慢 |
 | x_audience_activity_progress | 查询活动添加进度 | 🟢 快 |
 
+### 活动管理（共 6 个）
+
+| 工具 | 用途 | 速度 |
+|------|------|------|
+| x_activity_list | 获取活动列表（支持按状态筛选和分页） | 🟢 快 |
+| x_activity_detail | 获取活动详情（含发送统计和消息历史） | 🟢 快 |
+| x_activity_create | 创建营销活动（立即/定时发送） | 🟢 快 |
+| x_activity_update | 更新活动配置 | 🟢 快 |
+| x_activity_delete | 删除活动 ⚠️不可逆 | 🟢 快 |
+| x_activity_regenerate_content | 为活动用户重新生成个性化消息 | 🟡 慢 |
+
+### 收件箱/私信（共 14 个）
+
+| 工具 | 用途 | 速度 |
+|------|------|------|
+| x_inbox_search | 搜索收件箱（按用户名模糊查询） | 🟢 快 |
+| x_dm_history | 获取 DM 发送历史 | 🟢 快 |
+| x_dm_conversations_by_sessions | 按会话 ID 批量查询 | 🟢 快 |
+| x_dm_conversation | 获取 DM 会话实时数据（外部 API） | 🟡 慢 |
+| x_dm_conversation_detail | 获取单个会话详情（本地数据库） | 🟢 快 |
+| x_dm_activity_messages | 获取活动下的消息列表 | 🟢 快 |
+| x_dm_send_message | 发送单条 DM ⚠️不可撤回 | 🟡 慢 |
+| x_dm_refresh_replies | 刷新会话回复（拉取最新） | 🟡 慢 |
+| x_dm_reply_stats | 获取会话回复统计 | 🟢 快 |
+| x_dm_reply_save | 保存手动回复记录 | 🟢 快 |
+| x_dm_replies | 获取回复历史列表 | 🟢 快 |
+| x_dm_history_soft_delete | 软删除发送历史 | 🟢 快 |
+| x_dm_history_remark | 更新发送历史备注 | 🟢 快 |
+| x_dm_daily_send_stats | 获取今日 DM 发送统计和剩余额度 | 🟢 快 |
+
 ---
 
 ## 📋 标准操作流程
@@ -134,13 +164,103 @@ version: 1.1.0
 ← 进度：已完成/总计
 ```
 
+### 第 3 步：活动管理
+
+#### 3.1 查看和创建活动
+
+```
+→ x_activity_list { account_id: 255, status: "all" }
+← 活动列表（含名称、状态、发送统计）
+
+→ x_activity_create { account_id: 255, name: "春季促销", content: "推广新产品", target_user_ids: [100,101] }
+← ✅ 活动创建成功 活动ID: 26
+```
+
+#### 3.2 管理活动
+
+```
+→ x_activity_detail { account_id: 255, task_id: 26 }
+← 详情（含 stats 和 recent_history）
+
+→ x_activity_update { account_id: 255, task_id: 26, name: "更新后名称" }
+← ✅ 活动更新成功
+
+→ x_activity_regenerate_content { account_id: 255, activity_id: 26, user_ids: [100], preview_only: true }
+← 预览生成的个性化消息
+
+→ x_activity_delete { account_id: 255, task_id: 26 }  ⚠️ 不可逆
+```
+
+### 第 4 步：收件箱/私信管理
+
+#### 4.1 浏览收件箱
+
+```
+→ x_inbox_search { account_id: 255 }
+← 全部会话列表（含 session_id、target_user_name、status）
+
+→ x_inbox_search { account_id: 255, username: "john" }
+← 按用户名筛选
+```
+
+#### 4.2 查看会话内容
+
+```
+→ x_dm_conversation_detail { account_id: 255, session_id: "xxx-yyy" }
+← is_first_send, 首次发送内容, 消息列表
+
+→ x_dm_conversation { account_id: 255, dm_twitter_id: "1275249432" }
+← 实时 Twitter DM 数据
+```
+
+#### 4.3 发送消息
+
+```
+→ x_dm_daily_send_stats { account_id: 255 }
+← 今日已发: 10, 上限: 150, 剩余: 140
+
+→ x_dm_send_message { account_id: 255, history_id: 4149 }  ⚠️ 不可撤回
+← ✅ 消息发送成功
+```
+
+#### 4.4 回复管理
+
+```
+→ x_dm_refresh_replies { account_id: 255, session_id: "xxx-yyy" }
+← 新回复数: 2
+
+→ x_dm_reply_stats { account_id: 255, session_id: "xxx-yyy" }
+← reply_count: 3, last_reply_time: ...
+
+→ x_dm_replies { account_id: 255, send_history_id: 4149 }
+← 回复历史列表
+
+→ x_dm_reply_save { account_id: 255, send_history_id: 4149, reply_content: "感谢回复！" }
+← ✅ 回复已保存
+```
+
+#### 4.5 发送历史管理
+
+```
+→ x_dm_history { account_id: 255, status: "success" }
+← 已发送的历史记录
+
+→ x_dm_history_remark { account_id: 255, send_history_id: 4149, remark: "潜在客户" }
+← ✅ 备注已更新
+
+→ x_dm_history_soft_delete { account_id: 255, send_history_id: 999 }
+← ✅ 已软删除
+```
+
 ---
 
 ## ⚠️ 注意事项
 
 1. **API Key** — 所有操作依赖 x-api-key，验证失败时引导用户执行 `openclaw config set plugins.entries.fwgi-x-tool.config.apiKey "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 删除分组不可恢复，执行前确认
+3. **慢速操作** — import_url、interactive_users、search_keyword、add_to_activity、dm_send_message、dm_conversation、dm_refresh_replies、regenerate_content 超时为 60s
+4. **分页** — audience_list、activity_list、dm_history、inbox_search 等支持 page/page_size；import_url 使用 cursor 分页
+5. **不可逆操作** — group_delete 删除分组不可恢复；activity_delete 删除活动不可恢复；dm_send_message 发送私信不可撤回
 6. **interactive_users 限制** — 依赖 RapidAPI 外部服务，部分环境可能返回 total=0
+7. **DM 每日限额** — 每日 DM 发送有上限（默认 150 条），发送前建议检查 x_dm_daily_send_stats
+8. **参数名区分** — 活动相关操作用 `task_id`，但 regenerate_content 用 `activity_id`；DM 历史写操作（save/delete/remark）用 `send_history_id`，而 send_message 用 `history_id`

package/index.ts

@@ -1,12 +1,12 @@
 /**
  * fwgi-x-tool OpenClaw Plugin
- * X(Twitter) 营销管理助手 — 账号信息查看、受众管理（导入/筛选/分组/标签/营销活动）
+ * X(Twitter) 营销管理助手 — 账号信息查看、受众管理、活动管理、收件箱/私信
  *
  * 认证方式：通过 x-api-key 请求头调用后端 API（api-backend.fwgi.ai），
  * 启动时调用 /v1/api/checkLogin 验证 API Key 有效性并获取用户信息。
  * 验证通过后，所有后续请求自动携带 x-api-key 头。
  *
- * v1.1.0
+ * v1.2.0
  */
 
 import * as https from "node:https";
@@ -874,4 +874,651 @@ export default function register(api: any) {
       }
     },
   });
+
+  // ═══════════════════════════════════════════
+  // D. 活动管理模块
+  // ═══════════════════════════════════════════
+
+  api.registerTool({
+    name: "x_activity_list",
+    description: "获取营销活动列表。支持按状态筛选和分页。返回活动名称、状态、发送统计等信息。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        status: { type: "string", description: "活动状态筛选: pending / in_progress / completed / failed / all（默认 all）" },
+        page: { type: "number", description: "页码（默认 1）" },
+        page_size: { type: "number", description: "每页数量（默认 20）" },
+      },
+      required: ["account_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const query: Record<string, string> = { account_id: String(params.account_id) };
+        if (params.status) query.status = params.status;
+        if (params.page) query.page = String(params.page);
+        if (params.page_size) query.page_size = String(params.page_size);
+        const resp = await apiRequest(config, "GET", "/v1/api/marketing/activity/list", { query });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_activity_detail",
+    description: "获取营销活动详情，包含发送统计（total_sent/success/failed/pending）和最近的消息历史。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        task_id: { type: "number", description: "活动 ID" },
+      },
+      required: ["account_id", "task_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "GET", "/v1/api/marketing/activity/detail", {
+          query: { account_id: String(params.account_id), task_id: String(params.task_id) },
+        });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_activity_create",
+    description: "创建营销活动。可指定目标用户列表或筛选条件，支持立即发送或定时发送。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        name: { type: "string", description: "活动名称" },
+        content: { type: "string", description: "营销内容描述" },
+        template_id: { type: "number", description: "模板 ID" },
+        agent_id: { type: "number", description: "Agent（智能体）ID" },
+        send_type: { type: "string", description: "发送类型: immediate（立即）/ scheduled（定时），默认 immediate" },
+        send_time: { type: "string", description: "定时发送时间（ISO 格式，send_type=scheduled 时必填）" },
+        target_user_ids: { type: "array", items: { type: "number" }, description: "目标用户 ID 列表（twitter_following 表 id），与 filter_conditions 二选一" },
+        filter_conditions: { type: "object", description: "筛选条件对象（可含 keyword/can_dm/bot_score/interest_tags/activity_min/activity_max/activity_days），与 target_user_ids 二选一" },
+      },
+      required: ["account_id", "content"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = { account_id: params.account_id, content: params.content };
+        if (params.name) body.name = params.name;
+        if (params.template_id) body.template_id = params.template_id;
+        if (params.agent_id) body.agent_id = params.agent_id;
+        if (params.send_type) body.send_type = params.send_type;
+        if (params.send_time) body.send_time = params.send_time;
+        if (params.target_user_ids) body.target_user_ids = params.target_user_ids;
+        if (params.filter_conditions) body.filter_conditions = params.filter_conditions;
+        const resp = await apiRequest(config, "POST", "/v1/api/marketing/activity/create", { body });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          return ok(
+            `✅ 活动创建成功\n` +
+            `活动ID: ${d?.task_id ?? d?.activity_id}\n` +
+            `名称: ${d?.name ?? params.name ?? ""}\n` +
+            `状态: ${d?.status ?? "pending"}`,
+          );
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_activity_update",
+    description: "更新营销活动的名称、内容、模板、Agent、发送方式等配置。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        task_id: { type: "number", description: "活动 ID" },
+        name: { type: "string", description: "活动名称" },
+        content: { type: "string", description: "营销内容描述" },
+        template_id: { type: "number", description: "模板 ID" },
+        agent_id: { type: "number", description: "Agent ID" },
+        send_type: { type: "string", description: "发送类型: immediate / scheduled" },
+        send_time: { type: "string", description: "定时发送时间（ISO 格式）" },
+        status: { type: "string", description: "活动状态: pending / in_progress / completed / failed" },
+      },
+      required: ["account_id", "task_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = { account_id: params.account_id, task_id: params.task_id };
+        for (const key of ["name", "content", "template_id", "agent_id", "send_type", "send_time", "status"]) {
+          if (params[key] !== undefined) body[key] = params[key];
+        }
+        const resp = await apiRequest(config, "POST", "/v1/api/marketing/activity/update", { body });
+        if (resp.data?.code === 200) {
+          return ok(`✅ 活动 ${params.task_id} 更新成功`);
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_activity_delete",
+    description: "删除营销活动。⚠️ 此操作不可逆，删除后活动及其消息历史将无法恢复。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        task_id: { type: "number", description: "活动 ID" },
+      },
+      required: ["account_id", "task_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "POST", "/v1/api/marketing/activity/delete", {
+          body: { account_id: params.account_id, task_id: params.task_id },
+        });
+        if (resp.data?.code === 200) {
+          return ok(`✅ 活动 ${params.task_id} 已删除`);
+        }
+        if (resp.data?.code === 4007) {
+          return err("活动不存在，请检查 task_id 是否正确。");
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_activity_regenerate_content",
+    description: "为营销活动中的指定用户重新生成个性化消息内容。支持预览模式（不保存）。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        activity_id: { type: "number", description: "活动 ID" },
+        user_ids: { type: "array", items: { type: "number" }, description: "要生成内容的目标用户 ID 列表" },
+        preview_only: { type: "boolean", description: "是否仅预览不保存（默认 false）" },
+      },
+      required: ["account_id", "activity_id", "user_ids"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = {
+          account_id: params.account_id,
+          activity_id: params.activity_id,
+          user_ids: params.user_ids,
+        };
+        if (params.preview_only !== undefined) body.preview_only = params.preview_only;
+        const resp = await apiRequest(config, "POST", "/v1/api/marketing/activity/regenerate-content", {
+          body,
+          timeoutMs: SLOW_TIMEOUT_MS,
+        });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  // ═══════════════════════════════════════════
+  // E. 收件箱 / DM 模块
+  // ═══════════════════════════════════════════
+
+  api.registerTool({
+    name: "x_inbox_search",
+    description: "搜索收件箱。按目标用户名模糊查询 DM 会话列表，不传 username 则返回全部。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        username: { type: "string", description: "用户名关键词（支持模糊匹配）" },
+        page: { type: "number", description: "页码（默认 1）" },
+        page_size: { type: "number", description: "每页数量（默认 20）" },
+      },
+      required: ["account_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = { account_id: params.account_id };
+        if (params.username) body.username = params.username;
+        if (params.page) body.page = params.page;
+        if (params.page_size) body.page_size = params.page_size;
+        const resp = await apiRequest(config, "POST", "/v1/api/dm/inbox/searchByUsername", { body });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_history",
+    description: "获取 DM 发送历史。支持按日期范围、状态、活动 ID 筛选。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        start_date: { type: "string", description: "开始日期（ISO 格式）" },
+        end_date: { type: "string", description: "结束日期（ISO 格式）" },
+        status: { type: "string", description: "状态筛选: pending / success / failed" },
+        activity_id: { type: "number", description: "活动 ID 筛选" },
+        page: { type: "number", description: "页码（默认 1）" },
+        page_size: { type: "number", description: "每页数量（默认 20）" },
+      },
+      required: ["account_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const query: Record<string, string> = { account_id: String(params.account_id) };
+        if (params.start_date) query.start_date = params.start_date;
+        if (params.end_date) query.end_date = params.end_date;
+        if (params.status) query.status = params.status;
+        if (params.activity_id) query.activity_id = String(params.activity_id);
+        if (params.page) query.page = String(params.page);
+        if (params.page_size) query.page_size = String(params.page_size);
+        const resp = await apiRequest(config, "GET", "/v1/api/dm/history", { query });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_conversations_by_sessions",
+    description: "按会话 ID 批量查询 DM 会话列表，用于收件箱列表展示。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        session_ids: { type: "array", items: { type: "string" }, description: "会话 ID 列表" },
+        activity_id: { type: "number", description: "活动 ID 筛选" },
+        keyword: { type: "string", description: "关键词筛选（目标用户名或内容）" },
+      },
+      required: ["account_id", "session_ids"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = { account_id: params.account_id, session_ids: params.session_ids };
+        if (params.activity_id) body.activity_id = params.activity_id;
+        if (params.keyword) body.keyword = params.keyword;
+        const resp = await apiRequest(config, "POST", "/v1/api/dm/conversations/bySessionIds", { body });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_conversation",
+    description: "获取 DM 会话实时数据（调用外部 Twitter API）。根据目标用户 Twitter ID 获取最新对话。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        dm_twitter_id: { type: "string", description: "目标用户的 Twitter ID" },
+      },
+      required: ["account_id", "dm_twitter_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "POST", "/v1/api/dm/conversation", {
+          body: { account_id: params.account_id, dm_twitter_id: params.dm_twitter_id },
+          timeoutMs: SLOW_TIMEOUT_MS,
+        });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_conversation_detail",
+    description: "获取单个会话详情（本地数据库）。返回 is_first_send、首次发送内容和消息列表（sent/received）。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        session_id: { type: "string", description: "会话 ID" },
+      },
+      required: ["account_id", "session_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "POST", "/v1/api/dm/conversation/bySession", {
+          body: { account_id: params.account_id, session_id: params.session_id },
+        });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_activity_messages",
+    description: "获取某营销活动下的消息列表（待发送/已发送），支持分页。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        task_id: { type: "number", description: "活动 ID" },
+        page: { type: "number", description: "页码（默认 1）" },
+        page_size: { type: "number", description: "每页数量（默认 100）" },
+      },
+      required: ["account_id", "task_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const query: Record<string, string> = {
+          account_id: String(params.account_id),
+          task_id: String(params.task_id),
+        };
+        if (params.page) query.page = String(params.page);
+        if (params.page_size) query.page_size = String(params.page_size);
+        const resp = await apiRequest(config, "GET", "/v1/api/dm/activity/messages", { query });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_send_message",
+    description: "发送单条 DM 消息。⚠️ 此操作会真实发送 Twitter 私信且不可撤回。不传 content 则使用已生成的内容。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        history_id: { type: "number", description: "发送历史 ID" },
+        content: { type: "string", description: "消息内容（不传则使用已生成内容）" },
+      },
+      required: ["account_id", "history_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = { account_id: params.account_id, history_id: params.history_id };
+        if (params.content) body.content = params.content;
+        const resp = await apiRequest(config, "POST", "/v1/api/dm/message/send", {
+          body,
+          timeoutMs: SLOW_TIMEOUT_MS,
+        });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          return ok(
+            `✅ 消息发送成功\n` +
+            `history_id: ${d?.history_id}\n` +
+            `发送时间: ${d?.send_time ?? "N/A"}`,
+          );
+        }
+        if (resp.data?.code === 4009) {
+          return err("今日 DM 发送已达上限，请明天再试。");
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_refresh_replies",
+    description: "刷新会话回复。从外部 Twitter API 拉取最新回复并保存到数据库。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        session_id: { type: "string", description: "会话 ID" },
+      },
+      required: ["account_id", "session_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "POST", "/v1/api/dm/conversation/refreshReplies", {
+          body: { account_id: params.account_id, session_id: params.session_id },
+          timeoutMs: SLOW_TIMEOUT_MS,
+        });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          return ok(
+            `✅ 回复刷新完成\n` +
+            `send_history_id: ${d?.send_history_id}\n` +
+            `新回复数: ${d?.new_replies_count ?? 0}\n` +
+            `总消息数: ${d?.total_messages ?? 0}`,
+          );
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_reply_stats",
+    description: "获取会话回复统计（回复数量和最后回复时间），可用于轮询判断是否有新回复。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        session_id: { type: "string", description: "会话 ID" },
+      },
+      required: ["account_id", "session_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "GET", "/v1/api/dm/conversation/reply-stats", {
+          query: { account_id: String(params.account_id), session_id: params.session_id },
+        });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_reply_save",
+    description: "保存手动回复记录。将用户手动输入的回复保存到数据库（用于推荐回复模式下的手动发送记录）。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        send_history_id: { type: "number", description: "发送历史 ID" },
+        reply_content: { type: "string", description: "回复内容" },
+        reply_time: { type: "string", description: "回复时间（ISO 格式，可选）" },
+        target_user_name: { type: "string", description: "目标用户名（可选）" },
+      },
+      required: ["account_id", "send_history_id", "reply_content"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = {
+          account_id: params.account_id,
+          send_history_id: params.send_history_id,
+          reply_content: params.reply_content,
+        };
+        if (params.reply_time) body.reply_time = params.reply_time;
+        if (params.target_user_name) body.target_user_name = params.target_user_name;
+        const resp = await apiRequest(config, "POST", "/v1/api/dm/reply/save", { body });
+        if (resp.data?.code === 200) {
+          return ok(`✅ 回复已保存 (reply_id: ${resp.data.data?.reply_id})`);
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_replies",
+    description: "获取回复历史列表。支持按发送历史 ID、日期范围筛选，并支持分页。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        send_history_id: { type: "number", description: "发送历史 ID（可选，不传返回所有）" },
+        start_date: { type: "string", description: "开始日期（ISO 格式）" },
+        end_date: { type: "string", description: "结束日期（ISO 格式）" },
+        page: { type: "number", description: "页码" },
+        page_size: { type: "number", description: "每页数量" },
+      },
+      required: ["account_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const query: Record<string, string> = { account_id: String(params.account_id) };
+        if (params.send_history_id) query.send_history_id = String(params.send_history_id);
+        if (params.start_date) query.start_date = params.start_date;
+        if (params.end_date) query.end_date = params.end_date;
+        if (params.page) query.page = String(params.page);
+        if (params.page_size) query.page_size = String(params.page_size);
+        const resp = await apiRequest(config, "GET", "/v1/api/dm/replies", { query });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_history_soft_delete",
+    description: "软删除发送历史记录。记录不会真正删除，但在列表中不再显示。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        send_history_id: { type: "number", description: "发送历史 ID" },
+      },
+      required: ["account_id", "send_history_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "POST", "/v1/api/dm/history/soft-delete", {
+          body: { account_id: params.account_id, send_history_id: params.send_history_id },
+        });
+        if (resp.data?.code === 200) {
+          return ok(`✅ 发送历史 ${params.send_history_id} 已软删除`);
+        }
+        if (resp.data?.code === 4007) {
+          return err("发送历史不存在，请检查 send_history_id 是否正确。");
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_history_remark",
+    description: "更新发送历史的备注信息。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        send_history_id: { type: "number", description: "发送历史 ID" },
+        remark: { type: "string", description: "备注内容（传空字符串可清除备注）" },
+      },
+      required: ["account_id", "send_history_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = { account_id: params.account_id, send_history_id: params.send_history_id };
+        if (params.remark !== undefined) body.remark = params.remark;
+        const resp = await apiRequest(config, "POST", "/v1/api/dm/history/remark", { body });
+        if (resp.data?.code === 200) {
+          return ok(`✅ 备注已更新`);
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_dm_daily_send_stats",
+    description: "获取今日 DM 发送统计，包含已发送数量、每日上限和剩余可发送数量。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+      },
+      required: ["account_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "GET", "/v1/api/dm/daily-send-stats", {
+          query: { account_id: String(params.account_id) },
+        });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          return ok(
+            `📊 今日 DM 发送统计\n` +
+            `已发送: ${d?.today_sent ?? 0}\n` +
+            `每日上限: ${d?.limit ?? 150}\n` +
+            `剩余: ${d?.remaining ?? 0}`,
+          );
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@fwgi/fwgi-x-tool",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
-  "description": "X(Twitter) 营销管理助手 OpenClaw 插件 — 账号信息、受众管理、营销活动",
+  "description": "X(Twitter) 营销管理助手 OpenClaw 插件 — 账号信息、受众管理、活动管理、收件箱/私信",
   "main": "index.ts",
   "openclaw": {
     "extensions": ["./index.ts"]