@fwgi/openclaw-x-marketing 1.0.0

package/index.ts

@@ -0,0 +1,882 @@
+/**
+ * x-marketing OpenClaw Plugin
+ * X(Twitter) 营销管理助手 — 账号信息查看、受众管理（导入/筛选/分组/标签/营销活动）
+ *
+ * 认证方式：通过 x-api-key 请求头调用后端 API（api-backend.fwgi.ai），
+ * 启动时调用 /v1/api/checkLogin 验证 API Key 有效性并获取用户信息。
+ * 验证通过后，所有后续请求自动携带 x-api-key 头。
+ *
+ * v4.0.0
+ */
+
+import * as https from "node:https";
+import * as http from "node:http";
+
+// ─── 常量 ───
+const DEFAULT_API_BASE_URL = "https://api-backend.fwgi.ai";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const SLOW_TIMEOUT_MS = 60_000;
+const PLUGIN_ID = "x-marketing";
+
+// ─── 类型 ───
+type RuntimeConfig = {
+  apiBaseUrl: string;
+  apiKey: string;
+  userId: number | null;
+  userEmail: string | null;
+  timeoutMs: number;
+};
+
+type ApiResponse = {
+  status: number;
+  body: string;
+  data: any;
+};
+
+// ─── 内存状态 ───
+let apiKeyVerified = false;
+let apiKeyFingerprint = "";
+let verifiedUserId: number | null = null;
+let verifiedUserEmail: string | null = null;
+
+// ─── 配置解析 ───
+
+function getRawPluginConfig(api: any): Record<string, any> {
+  const rootCfg = api?.config ?? {};
+  const nestedCfg = rootCfg?.plugins?.entries?.[PLUGIN_ID]?.config;
+  if (nestedCfg && typeof nestedCfg === "object") {
+    return { ...rootCfg, ...nestedCfg };
+  }
+  return rootCfg;
+}
+
+function toPositiveInt(value: unknown, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+function resolveRuntimeConfig(api: any): RuntimeConfig {
+  const cfg = getRawPluginConfig(api);
+
+  const apiBaseUrl = String(
+    cfg.apiBaseUrl ||
+      process.env.X_MARKETING_API_BASE_URL ||
+      DEFAULT_API_BASE_URL,
+  ).replace(/\/+$/, "");
+
+  const apiKey = String(
+    cfg.apiKey ||
+      cfg.xApiKey ||
+      process.env.X_MARKETING_API_KEY ||
+      "",
+  ).trim();
+
+  const userId = verifiedUserId ?? (cfg.userId ? Number(cfg.userId) : null);
+  const userEmail = verifiedUserEmail ?? null;
+
+  const timeoutMs = toPositiveInt(
+    cfg.requestTimeoutMs ||
+      process.env.X_MARKETING_TIMEOUT_MS,
+    DEFAULT_TIMEOUT_MS,
+  );
+
+  return { apiBaseUrl, apiKey, userId, userEmail, timeoutMs };
+}
+
+// ─── HTTP 请求封装 ───
+
+function apiRequest(
+  config: RuntimeConfig,
+  method: string,
+  reqPath: string,
+  options: {
+    body?: any;
+    query?: Record<string, string>;
+    timeoutMs?: number;
+  } = {},
+): Promise<ApiResponse> {
+  const url = new URL(reqPath, config.apiBaseUrl + "/");
+
+  if (options.query) {
+    for (const [key, value] of Object.entries(options.query)) {
+      if (value !== undefined && value !== null && value !== "") {
+        url.searchParams.set(key, value);
+      }
+    }
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    "x-api-key": config.apiKey,
+  };
+
+  const bodyStr = options.body ? JSON.stringify(options.body) : undefined;
+  if (bodyStr) {
+    headers["Content-Length"] = String(Buffer.byteLength(bodyStr));
+  }
+
+  const client = url.protocol === "https:" ? https : http;
+  const effectiveTimeout = options.timeoutMs || config.timeoutMs;
+
+  return new Promise((resolve, reject) => {
+    const req = client.request(
+      {
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "https:" ? 443 : 80),
+        path: `${url.pathname}${url.search}`,
+        method,
+        headers,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (chunk: Buffer) => chunks.push(chunk));
+        res.on("end", () => {
+          clearTimeout(timer);
+          const body = Buffer.concat(chunks).toString("utf-8");
+          let data: any;
+          try {
+            data = JSON.parse(body);
+          } catch {
+            data = { raw: body };
+          }
+          resolve({ status: res.statusCode || 200, body, data });
+        });
+      },
+    );
+
+    const timer = setTimeout(() => {
+      req.destroy(new Error(`请求超时 (${Math.round(effectiveTimeout / 1000)}s)`));
+    }, effectiveTimeout);
+
+    req.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+
+    if (bodyStr) {
+      req.write(bodyStr);
+    }
+    req.end();
+  });
+}
+
+// ─── API Key 验证 ───
+
+async function verifyApiKey(config: RuntimeConfig): Promise<void> {
+  const fingerprint = `${config.apiBaseUrl}::${config.apiKey}`;
+  if (apiKeyVerified && fingerprint === apiKeyFingerprint) return;
+
+  if (!config.apiKey) {
+    throw new Error(
+      "未配置 API Key。请在 plugins.entries.x-marketing.config.apiKey 或环境变量 X_MARKETING_API_KEY 中设置。",
+    );
+  }
+
+  const resp = await apiRequest(config, "GET", "/v1/api/checkLogin", {
+    timeoutMs: 15_000,
+  });
+
+  if (resp.status === 401 || resp.data?.code === 4001) {
+    throw new Error("API Key 无效或已过期。请检查后重试。");
+  }
+  if (resp.status >= 400) {
+    throw new Error(`API Key 验证失败 (HTTP ${resp.status}): ${resp.body}`);
+  }
+  if (resp.data?.code === 200 && resp.data?.data?.is_login) {
+    apiKeyVerified = true;
+    apiKeyFingerprint = fingerprint;
+    verifiedUserId = resp.data.data.user_id ?? null;
+    verifiedUserEmail = resp.data.data.account ?? null;
+  } else {
+    throw new Error(`API Key 验证返回异常: ${resp.data?.message || resp.body}`);
+  }
+}
+
+// ─── 响应处理 ───
+
+function ok(text: string) {
+  return { content: [{ type: "text", text }] };
+}
+
+function err(message: string) {
+  return { content: [{ type: "text", text: `❌ ${message}` }] };
+}
+
+function formatResponse(data: any): { content: Array<{ type: string; text: string }> } {
+  if (data?.code === 200 || data?.status === "true") {
+    return ok(JSON.stringify(data.data ?? data, null, 2));
+  }
+  const msg = data?.message || JSON.stringify(data);
+  throw new Error(`API 返回错误 (code: ${data?.code}): ${msg}`);
+}
+
+function classifyError(message: string): string {
+  if (message.includes("超时")) {
+    return `请求超时: ${message}。请检查网络连接或增大 requestTimeoutMs。`;
+  }
+  if (message.includes("ECONNREFUSED")) {
+    return `无法连接到后端服务，请检查 apiBaseUrl 配置是否正确。`;
+  }
+  if (message.includes("ECONNRESET") || message.includes("socket hang up")) {
+    return `连接被重置，可能是网络不稳定。请稍后重试。`;
+  }
+  if (message.includes("5006") || message.includes("Frequent")) {
+    return `操作过于频繁，请等待 30 秒后重试。`;
+  }
+  return message;
+}
+
+// ─── 工具注册 ───
+
+export default function register(api: any) {
+
+  // ═══════════════════════════════════════════
+  // A. 连接验证
+  // ═══════════════════════════════════════════
+
+  api.registerTool({
+    name: "x_verify_connection",
+    description: "验证 API Key 连接。通过 checkLogin 接口确认 API Key 有效性并获取当前用户信息（user_id、邮箱）。每次会话开始前建议先调用此工具。",
+    parameters: { type: "object", properties: {}, required: [] },
+    async execute(_id: string, _params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        return ok(
+          `✅ API Key 验证通过！\n` +
+          `账号: ${verifiedUserEmail}\n` +
+          `user_id: ${verifiedUserId}\n` +
+          `后端: ${config.apiBaseUrl}`,
+        );
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  // ═══════════════════════════════════════════
+  // B. X 账号信息查看
+  // ═══════════════════════════════════════════
+
+  api.registerTool({
+    name: "x_account_list",
+    description: "获取当前用户的 X 账号列表。支持按 handle/显示名称/邮箱筛选。",
+    parameters: {
+      type: "object",
+      properties: {
+        handle: { type: "string", description: "X 用户名（@ 后的内容）筛选" },
+        display_name: { type: "string", description: "显示名称筛选" },
+        email: { type: "string", description: "关联邮箱筛选" },
+      },
+      required: [],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const query: Record<string, string> = {};
+        if (params?.handle) query.handle = params.handle;
+        if (params?.display_name) query.display_name = params.display_name;
+        if (params?.email) query.email = params.email;
+
+        const resp = await apiRequest(config, "GET", "/v1/api/twitter/auto/list", { query });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_account_detail",
+    description: "获取 X 账号详情，包含 audiences、pillars、kols、templates、tweetStyle、postingSchedule、account_actions 等完整配置。",
+    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/twitter/auto/detail", {
+          query: { account_id: String(params.account_id) },
+        });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_get_field_info",
+    description: "获取上号表单的字段说明（handle、display_name 等字段的中英文说明及示例）。",
+    parameters: { type: "object", properties: {}, required: [] },
+    async execute(_id: string, _params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "GET", "/v1/api/twitter/auto/fieldInfo");
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  // ═══════════════════════════════════════════
+  // C. 受众管理模块
+  // ═══════════════════════════════════════════
+
+  // ─── C.1 受众列表与导入 ───
+
+  api.registerTool({
+    name: "x_audience_list",
+    description: "获取受众列表。支持按关键词、是否可私信、机器人评分、兴趣标签、活跃度等多维度筛选。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        keyword: { type: "string", description: "关键词（匹配用户名、名称、简介）" },
+        can_dm: { type: "string", description: "是否可私信（true/false）" },
+        bot_score: { type: "string", description: "机器人评分：safe / medium / risk" },
+        interest_tags: { type: "string", description: "兴趣标签，多个用逗号分隔" },
+        activity_min: { type: "number", description: "最小活跃度（0-100）" },
+        activity_max: { type: "number", description: "最大活跃度（0-100）" },
+        activity_days: { type: "number", description: "活跃度计算天数，默认 30" },
+        group_id: { type: "number", description: "分组 ID" },
+        source_username: { type: "string", description: "来源用户名" },
+        is_send: { 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 query: Record<string, string> = {
+          account_id: String(params.account_id),
+        };
+        if (params.keyword) query.keyword = params.keyword;
+        if (params.can_dm !== undefined) query.can_dm = String(params.can_dm);
+        if (params.bot_score) query.bot_score = params.bot_score;
+        if (params.interest_tags) query.interest_tags = params.interest_tags;
+        if (params.activity_min !== undefined) query.activity_min = String(params.activity_min);
+        if (params.activity_max !== undefined) query.activity_max = String(params.activity_max);
+        if (params.activity_days) query.activity_days = String(params.activity_days);
+        if (params.group_id) query.group_id = String(params.group_id);
+        if (params.source_username) query.source_username = params.source_username;
+        if (params.is_send) query.is_send = params.is_send;
+        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/twitter/following/list", { query });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_import_url",
+    description: "通过 X 用户主页 URL 导入其关注列表作为受众。支持 cursor 分页导入。注意：此接口耗时较长，且 count 参数为建议值（实际可能返回更多）。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        x_url: { type: "string", description: "X 用户主页 URL，如 https://x.com/username" },
+        cursor: { type: "string", description: "分页游标，上一页返回的 next_cursor" },
+        count: { type: "number", description: "期望每页数量，默认 20" },
+      },
+      required: ["account_id", "x_url"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = {
+          account_id: params.account_id,
+          x_url: params.x_url,
+        };
+        if (params.cursor) body.cursor = params.cursor;
+        if (params.count) body.count = params.count;
+
+        const resp = await apiRequest(config, "POST", "/v1/api/twitter/following/add", {
+          body,
+          timeoutMs: SLOW_TIMEOUT_MS,
+        });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          const sr = d?.save_result || {};
+          return ok(
+            `✅ 受众导入完成\n` +
+            `来源: ${params.x_url}\n` +
+            `返回用户数: ${d?.total_returned ?? d?.users?.length ?? 0}\n` +
+            `保存成功: ${sr.success ?? 0}，失败: ${sr.failed ?? 0}\n` +
+            `还有更多: ${d?.has_more ? "是（使用 next_cursor 继续）" : "否"}\n` +
+            (d?.next_cursor ? `next_cursor: ${d.next_cursor}` : ""),
+          );
+        }
+        return err(`导入失败: ${resp.data?.message || resp.body}`);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_interactive_users",
+    description: "根据推文 URL 或 ID 获取转发/点赞该推文的用户并导入到受众库。依赖 RapidAPI 外部服务，可能受频率限制。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        tweet_url_or_id: { type: "string", description: "推文 URL 或推文 ID" },
+        count: { type: "number", description: "返回数量，默认 20" },
+      },
+      required: ["account_id", "tweet_url_or_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = {
+          account_id: params.account_id,
+          tweet_url_or_id: params.tweet_url_or_id,
+        };
+        if (params.count) body.count = params.count;
+
+        const resp = await apiRequest(config, "POST", "/v1/api/twitter/following/interactive-users", {
+          body,
+          timeoutMs: SLOW_TIMEOUT_MS,
+        });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          return ok(
+            `✅ 交互用户获取完成\n` +
+            `总计: ${d?.total ?? 0}\n` +
+            `新增保存: ${d?.saved ?? 0}\n` +
+            `更新: ${d?.updated ?? 0}\n` +
+            `失败: ${d?.failed ?? 0}`,
+          );
+        }
+        return err(`获取交互用户失败: ${resp.data?.message || resp.body}`);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_search_keyword",
+    description: "根据关键词搜索推文，提取推文作者作为潜在受众并导入。依赖 RapidAPI，有频率限制（建议调用间隔大于30秒）。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        keyword: { type: "string", description: "搜索关键词" },
+        count: { type: "number", description: "返回数量，默认 20" },
+      },
+      required: ["account_id", "keyword"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = {
+          account_id: params.account_id,
+          keyword: params.keyword,
+        };
+        if (params.count) body.count = params.count;
+
+        const resp = await apiRequest(config, "POST", "/v1/api/twitter/following/search-by-keyword", {
+          body,
+          timeoutMs: SLOW_TIMEOUT_MS,
+        });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          return ok(
+            `✅ 关键词搜索完成\n` +
+            `关键词: ${params.keyword}\n` +
+            `总计: ${d?.total ?? 0}\n` +
+            `新增保存: ${d?.saved ?? 0}\n` +
+            `更新: ${d?.updated ?? 0}\n` +
+            `失败: ${d?.failed ?? 0}`,
+          );
+        }
+        return err(`关键词搜索失败: ${resp.data?.message || resp.body}`);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  // ─── C.2 分组管理 ───
+
+  api.registerTool({
+    name: "x_audience_group_create",
+    description: "创建受众分组。可创建动态分组（基于筛选条件自动匹配）或静态分组（指定用户ID列表）。",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "分组名称" },
+        description: { type: "string", description: "分组描述" },
+        filter_conditions: {
+          type: "object",
+          description: "动态分组筛选条件（account_id, keyword, can_dm, bot_score, interest_tags, activity_min, activity_max, activity_days）",
+        },
+        user_ids: {
+          type: "array",
+          items: { type: "number" },
+          description: "静态分组的受众 ID 列表（following 表的 id）",
+        },
+      },
+      required: ["name"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = { name: params.name };
+        if (params.description) body.description = params.description;
+        if (params.filter_conditions) body.filter_conditions = params.filter_conditions;
+        if (params.user_ids) body.user_ids = params.user_ids;
+
+        const resp = await apiRequest(config, "POST", "/v1/api/twitter/following/group/create", { body });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          return ok(
+            `✅ 分组创建成功\n` +
+            `group_id: ${d?.group_id}\n` +
+            `名称: ${d?.name}\n` +
+            `匹配用户数: ${d?.user_count ?? 0}`,
+          );
+        }
+        return err(`创建分组失败: ${resp.data?.message || resp.body}`);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_group_list",
+    description: "获取受众分组列表。",
+    parameters: {
+      type: "object",
+      properties: {
+        page: { type: "number", description: "页码，默认 1" },
+        page_size: { type: "number", description: "每页数量，默认 20" },
+      },
+      required: [],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const query: Record<string, string> = {};
+        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/twitter/following/group/list", { query });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_group_detail",
+    description: "获取受众分组详情，包含分组信息及筛选条件。",
+    parameters: {
+      type: "object",
+      properties: {
+        group_id: { type: "number", description: "分组 ID" },
+      },
+      required: ["group_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "GET", "/v1/api/twitter/following/group/detail", {
+          query: { group_id: String(params.group_id) },
+        });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_group_update",
+    description: "更新受众分组的名称、描述或筛选条件。",
+    parameters: {
+      type: "object",
+      properties: {
+        group_id: { type: "number", description: "分组 ID" },
+        name: { type: "string", description: "新名称" },
+        description: { type: "string", description: "新描述" },
+        filter_conditions: { type: "object", description: "新的筛选条件" },
+      },
+      required: ["group_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = { group_id: params.group_id };
+        if (params.name) body.name = params.name;
+        if (params.description) body.description = params.description;
+        if (params.filter_conditions) body.filter_conditions = params.filter_conditions;
+
+        const resp = await apiRequest(config, "POST", "/v1/api/twitter/following/group/update", { body });
+        if (resp.data?.code === 200) {
+          return ok(`✅ 分组 ${params.group_id} 已更新`);
+        }
+        return err(`更新失败: ${resp.data?.message || resp.body}`);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_group_delete",
+    description: "删除受众分组。⚠️ 此操作不可逆。",
+    parameters: {
+      type: "object",
+      properties: {
+        group_id: { type: "number", description: "分组 ID" },
+      },
+      required: ["group_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "POST", "/v1/api/twitter/following/group/delete", {
+          body: { group_id: params.group_id },
+        });
+        if (resp.data?.code === 200) {
+          return ok(`✅ 分组 ${params.group_id} 已删除`);
+        }
+        return err(`删除失败: ${resp.data?.message || resp.body}`);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  // ─── C.3 兴趣标签 ───
+
+  api.registerTool({
+    name: "x_audience_interest_tags",
+    description: "获取某账号下受众的兴趣标签统计列表。",
+    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/twitter/following/interest-tags", {
+          query: { account_id: String(params.account_id) },
+        });
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_interest_tags_add",
+    description: "为指定受众添加兴趣标签。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        following_id: { type: "number", description: "受众 ID（受众列表中的 id 字段）" },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "标签列表，如 [\"AI\", \"Creator\"]",
+        },
+        source: { type: "string", description: "来源，默认 manual" },
+      },
+      required: ["account_id", "following_id", "tags"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = {
+          account_id: params.account_id,
+          following_id: params.following_id,
+          tags: params.tags,
+        };
+        if (params.source) body.source = params.source;
+
+        const resp = await apiRequest(config, "POST", "/v1/api/twitter/following/interest-tags/add", { body });
+        if (resp.data?.code === 200) {
+          return ok(`✅ 已为受众 ${params.following_id} 添加标签: ${params.tags.join(", ")}`);
+        }
+        return err(`添加标签失败: ${resp.data?.message || resp.body}`);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_interest_tags_remove",
+    description: "移除指定受众的某个兴趣标签。",
+    parameters: {
+      type: "object",
+      properties: {
+        account_id: { type: "number", description: "账号 ID" },
+        following_id: { type: "number", description: "受众 ID" },
+        tag_name: { type: "string", description: "要移除的标签名称" },
+      },
+      required: ["account_id", "following_id", "tag_name"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "POST", "/v1/api/twitter/following/interest-tags/remove", {
+          body: {
+            account_id: params.account_id,
+            following_id: params.following_id,
+            tag_name: params.tag_name,
+          },
+        });
+        if (resp.data?.code === 200) {
+          return ok(`✅ 已从受众 ${params.following_id} 移除标签: ${params.tag_name}`);
+        }
+        return err(`移除标签失败: ${resp.data?.message || resp.body}`);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  // ─── C.4 营销活动 ───
+
+  api.registerTool({
+    name: "x_audience_add_to_activity",
+    description: "将受众添加到营销活动。可通过指定用户ID列表或筛选条件批量添加。此操作为异步，可用 x_audience_activity_progress 查询进度。",
+    parameters: {
+      type: "object",
+      properties: {
+        activity_id: { type: "number", description: "活动 ID（task_id）" },
+        account_id: { type: "number", description: "账号 ID" },
+        user_ids: {
+          type: "array",
+          items: { type: "number" },
+          description: "受众 ID 列表（与 filter_conditions 二选一）",
+        },
+        filter_conditions: {
+          type: "object",
+          description: "筛选条件（与 user_ids 二选一），字段同受众列表筛选",
+        },
+        send_type: { type: "string", description: "manual=仅生成内容，immediate=生成后立即发送，默认 manual" },
+      },
+      required: ["activity_id", "account_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const body: any = {
+          activity_id: params.activity_id,
+          account_id: params.account_id,
+        };
+        if (params.user_ids) body.user_ids = params.user_ids;
+        if (params.filter_conditions) body.filter_conditions = params.filter_conditions;
+        if (params.send_type) body.send_type = params.send_type;
+
+        if (!body.user_ids && !body.filter_conditions) {
+          return err("请提供 user_ids 或 filter_conditions 之一。");
+        }
+
+        const resp = await apiRequest(config, "POST", "/v1/api/twitter/following/add-to-activity", {
+          body,
+          timeoutMs: SLOW_TIMEOUT_MS,
+        });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          return ok(
+            `✅ 受众已添加到活动\n` +
+            `活动ID: ${d?.activity_id ?? params.activity_id}\n` +
+            `添加数量: ${d?.total ?? 0}\n` +
+            `${d?.message || "操作成功"}`,
+          );
+        }
+        if (resp.data?.code === 4007) {
+          return err("活动不存在，请检查 activity_id 是否正确。");
+        }
+        return err(`添加到活动失败: ${resp.data?.message || resp.body}`);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+
+  api.registerTool({
+    name: "x_audience_activity_progress",
+    description: "查询受众添加到活动的进度（异步操作的进度轮询）。",
+    parameters: {
+      type: "object",
+      properties: {
+        activity_id: { type: "number", description: "活动 ID" },
+        account_id: { type: "number", description: "账号 ID" },
+      },
+      required: ["activity_id", "account_id"],
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const config = resolveRuntimeConfig(api);
+        await verifyApiKey(config);
+        const resp = await apiRequest(config, "GET", "/v1/api/twitter/following/add-to-activity/progress", {
+          query: {
+            activity_id: String(params.activity_id),
+            account_id: String(params.account_id),
+          },
+        });
+        if (resp.data?.code === 200) {
+          const d = resp.data.data;
+          return ok(
+            `📊 活动进度\n` +
+            `活动ID: ${d?.activity_id ?? params.activity_id}\n` +
+            `总计: ${d?.total ?? 0}\n` +
+            `已完成: ${d?.completed ?? 0}\n` +
+            `失败: ${d?.failed ?? 0}\n` +
+            `进行中: ${d?.in_progress ?? 0}`,
+          );
+        }
+        if (resp.data?.code === 4007) {
+          return err("活动不存在或无进度数据。");
+        }
+        return formatResponse(resp.data);
+      } catch (e: any) {
+        return err(classifyError(e.message));
+      }
+    },
+  });
+}