social-mcp/PLAN.md at 9d0a9c93f45fe923b73018a5ca08dc96f44f77cb

Files

T

kurihada 8da5f40c9f feat: social-mcp 初始实现

多平台社交自动化 MCP 服务，首批支持小红书。

- 13 个 MCP 工具：登录管理、内容浏览、发布、互动
- 13 个 REST API 端点，支持 Bearer token 认证和限流
- BrowserManager：串行队列、背压、崩溃恢复
- Cookie 持久化：原子写入、0600 权限
- 安全：DNS rebinding 防御、错误脱敏、深层日志 redact
- Docker 部署支持
- 28 个单元测试全部通过

2026-02-28 22:57:22 +08:00

38 KiB

Raw Blame History

一、项目定位

通过浏览器自动化，让 AI 助手（Claude 等）能操控多个社交平台。首批支持：小红书。后续按需扩展小黑盒、B站、微博等。

二、技术栈选型

组件	选择	理由
语言	TypeScript 5.x	浏览器自动化生态最强，MCP SDK 是官方参考实现
运行时	Node.js 22 LTS	当前 LTS，Node 20 即将进入 maintenance
浏览器自动化	rebrowser-playwright	Playwright 的 drop-in 替代，内置反自动化检测补丁，活跃维护
MCP SDK	@modelcontextprotocol/sdk ^1.27	官方 TypeScript 参考实现，锁定 v1.x 稳定版
HTTP 服务	Express ^4	MCP SDK 原生支持 Express 集成
包管理	pnpm	快，磁盘占用小
构建	tsup	零配置 TS 打包，基于 esbuild
日志	pino ^9	高性能结构化日志，内置 redact 脱敏
校验	zod ^3.25	运行时类型校验，MCP SDK 原生支持。不用 v4（与 SDK 有兼容问题）
容器化	Docker	含 Playwright 浏览器

为什么用 rebrowser-playwright 而不是 playwright-extra？

playwright-extra 最后发布 4.3.6 是 3 年前，已停止维护，随时会与新版 Playwright 不兼容。 rebrowser-playwright 是 Playwright 的 patched fork（2026.2 仍在更新），直接 npm install rebrowser-playwright 即可，代码中 import { chromium } from 'rebrowser-playwright' 替代原 playwright，零改动。它在底层修复 CDP 泄漏等检测点，比 JS 层面的 stealth 脚本更彻底。

为什么锁定 zod ^3.25？

MCP SDK v1.x 的 server.tool() 内部依赖 zod v3 的 schema 结构。 zod v4 有 breaking change（.describe() 丢失、_parse 不兼容），参见 Issue #925。

三、架构设计：插件式多平台

3.1 设计原则

不做统一 Platform 接口。 各平台业务差异大（小红书的笔记 vs B站的弹幕 vs 微博的转发），强行抽象只会产生大量 NotSupported。

真正共享的是基础设施，业务逻辑各平台独立：

共享基础设施                     各平台独立
──────────                     ──────────
BrowserManager                 MCP 工具定义 + zod schema
CookieStore                    actions（业务逻辑层）
Config / Logger                页面操作逻辑
MCP Server 框架                 CSS 选择器
Express + 中间件                业务类型定义
错误处理包装                     REST API handler

3.2 平台插件契约

每个平台导出一个 PlatformPlugin，把自己的 MCP 工具注册进去：

export interface PlatformPlugin {
  name: string;
  registerTools(server: McpServer, browser: BrowserManager): void;
  registerRoutes?(router: express.Router, browser: BrowserManager): void;
  // 生命周期钩子（可选，第二个平台接入时再强制要求）
  init?(): Promise<void>;
  shutdown?(): Promise<void>;
  healthCheck?(): Promise<{ healthy: boolean; message?: string }>;
}

新增平台只需要：

在 src/platforms/ 下新建目录
实现 PlatformPlugin
在 src/index.ts 中 import 并注册

Review 备注：init/shutdown/healthCheck 当前为可选钩子。 Phase 1 只有小红书一个平台，暂不强制。等第二个平台接入时评估是否改为必选。

3.3 平台内部分层

每个平台内部统一采用 actions 层 分离业务逻辑和 handler：

platforms/xiaohongshu/
├── index.ts          # PlatformPlugin: 注册 MCP 工具，调用 actions
├── actions.ts        # 业务逻辑层（纯函数，接收 Page 返回数据）
├── selectors.ts      # CSS 选择器常量
├── schemas.ts        # zod schema（MCP 工具参数）
├── types.ts          # 业务类型
├── login.ts          # 登录操作（页面交互）
├── search.ts         # 搜索操作
├── ...               # 其他操作

actions.ts 是核心：MCP handler 和 REST handler 都调用 actions 中的函数，不重复业务逻辑。

// actions.ts — 纯业务逻辑，不关心 MCP/REST
export async function searchFeeds(page: Page, keyword: string, filters?: FilterOption): Promise<Feed[]> { ... }
export async function checkLoginStatus(page: Page): Promise<LoginStatus> { ... }

// index.ts — MCP handler 只做参数解析 + 调用 action + 格式化输出
server.tool('xhs_search', '搜索小红书笔记', SearchSchema, async (args) => {
  return browser.withPage('xiaohongshu', async (page) => {
    const feeds = await searchFeeds(page, args.keyword, args.filters);
    return { content: [{ type: 'text', text: JSON.stringify(feeds) }] };
  });
});

四、项目结构

social-auto-hub/
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── .env.example
├── .gitignore
├── CLAUDE.md
├── Dockerfile
│
├── src/
│   ├── index.ts                     # 入口：配置、注册插件、启动、优雅关闭（drain→browser→http→log）
│   │
│   ├── server/
│   │   ├── app.ts                   # AppServer: Express + MCP 生命周期
│   │   └── middleware.ts            # DNS rebinding 防御 + 错误处理 + 优雅关闭 503（不加 CORS）
│   │
│   ├── browser/
│   │   └── manager.ts              # BrowserManager: 浏览器 + Context + 串行队列 + 背压 + 启动锁
│   │
│   ├── cookie/
│   │   └── store.ts                # CookieStore: 按平台隔离，文件权限 0600，原子写入
│   │
│   ├── config/
│   │   └── index.ts                # 全局配置（环境变量，默认 127.0.0.1）
│   │
│   ├── utils/
│   │   ├── logger.ts               # pino 日志（深层 redact 脱敏 + 自定义错误序列化）
│   │   ├── errors.ts               # 错误分类 + 消息脱敏 + withErrorHandling 包装
│   │   └── downloader.ts           # 图片下载 + 媒体路径校验
│   │
│   └── platforms/
│       └── xiaohongshu/
│           ├── index.ts            # PlatformPlugin 注册
│           ├── actions.ts          # 业务逻辑层（MCP/REST 共享）
│           ├── selectors.ts        # CSS 选择器常量
│           ├── types.ts            # 小红书业务类型
│           ├── schemas.ts          # MCP 工具参数 zod schema
│           ├── login.ts            # 登录（特殊 Page 生命周期）
│           ├── search.ts           # 搜索
│           ├── feeds.ts            # Feed 列表
│           ├── feed-detail.ts      # 笔记详情 + 评论
│           ├── publish.ts          # 图文发布
│           ├── publish-video.ts    # 视频发布
│           ├── comment.ts          # 评论 + 回复
│           ├── interaction.ts      # 点赞 / 收藏
│           └── user-profile.ts     # 用户主页
│
└── deploy/
    └── docker-compose.yml

五、小红书 MCP 工具清单（13 个）

5.1 登录管理（3 个）

MCP 工具名	说明	读/写	参数
`xhs_check_login`	检查登录状态	只读	无
`xhs_get_login_qrcode`	获取登录二维码图片	只读	无
`xhs_delete_cookies`	删除 Cookie，重置登录	写（破坏性）	无

5.2 内容浏览（4 个）

MCP 工具名	说明	读/写	参数
`xhs_list_feeds`	获取首页推荐 Feed 列表	只读	无
`xhs_search`	搜索笔记	只读	`keyword`, `filters?`（排序/类型/时间/范围/位置）
`xhs_get_feed_detail`	获取笔记详情 + 评论	只读	`feed_id`, `xsec_token`, `load_all_comments?`
`xhs_get_user_profile`	获取用户主页信息	只读	`user_id`, `xsec_token`

注意：xhs_get_feed_detail 相比参考项目精简了参数。 scroll_speed、click_more_replies、reply_limit 是浏览器实现细节，不暴露给 AI，改为服务端内部配置（在 config 或 actions 层处理）。

5.3 内容发布（2 个）

MCP 工具名	说明	读/写	参数
`xhs_publish_image`	发布图文笔记	写	`title`, `content`, `images[]`, `tags?[]`, `schedule_at?`, `is_original?`, `visibility?`
`xhs_publish_video`	发布视频笔记	写	`title`, `content`, `video`, `tags?[]`, `schedule_at?`, `visibility?`

5.4 互动操作（4 个）

MCP 工具名	说明	读/写	参数
`xhs_post_comment`	发表评论	写	`feed_id`, `xsec_token`, `content`
`xhs_reply_comment`	回复评论	写	`feed_id`, `xsec_token`, `comment_id?`, `user_id?`, `content`
`xhs_like`	点赞/取消点赞	写	`feed_id`, `xsec_token`, `unlike?`
`xhs_favorite`	收藏/取消收藏	写	`feed_id`, `xsec_token`, `unfavorite?`

5.5 REST API（Phase 5，可选）

GET    /api/xhs/login/status        POST   /api/xhs/publish/image
GET    /api/xhs/login/qrcode        POST   /api/xhs/publish/video
DELETE /api/xhs/login/cookies        POST   /api/xhs/comment
GET    /api/xhs/feeds                POST   /api/xhs/comment/reply
POST   /api/xhs/search              POST   /api/xhs/like
POST   /api/xhs/feeds/detail        POST   /api/xhs/favorite
POST   /api/xhs/user/profile

六、核心模块设计

6.1 BrowserManager

import { Browser, BrowserContext, Page } from 'rebrowser-playwright';

class BrowserManager {
  private browser: Browser | null = null;
  private contexts = new Map<string, BrowserContext>();
  private queues = new Map<string, Promise<void>>();  // per-platform 串行队列
  private queueDepths = new Map<string, number>();     // 队列深度计数
  private launchPromise: Promise<Browser> | null = null; // 启动锁

  private readonly MAX_QUEUE_DEPTH = 10;

  // 分级超时：不同操作类型使用不同超时时间
  static readonly OPERATION_TIMEOUTS: Record<string, number> = {
    like:        15_000,   // 15s — 快速交互
    comment:     20_000,   // 20s
    feed_list:   30_000,   // 30s — 页面加载 + 提取
    search:      30_000,   // 30s
    feed_detail: 60_000,   // 60s — 含滚动加载
    publish:    300_000,   // 5min — 上传可能较慢
    login:      300_000,   // 5min — 用户交互
    default:     60_000,   // 1min — 兜底
  };

  // 核心方法：串行执行 + 超时控制 + 错误恢复 + 背压
  async withPage<T>(
    platform: string,
    fn: (page: Page) => Promise<T>,
    timeoutMs?: number,
  ): Promise<T> {
    // 0. 背压：队列深度限制，防止无限排队
    const depth = this.queueDepths.get(platform) ?? 0;
    if (depth >= this.MAX_QUEUE_DEPTH) {
      throw new Error(`平台 ${platform} 队列已满 (${this.MAX_QUEUE_DEPTH})，请稍后重试`);
    }
    this.queueDepths.set(platform, depth + 1);

    const effectiveTimeout = timeoutMs ?? BrowserManager.OPERATION_TIMEOUTS.default;

    // 1. 串行化：同一平台的操作排队执行，避免多 Page 互相干扰
    const prev = this.queues.get(platform) ?? Promise.resolve();
    const task = prev.then(async () => {
      // 2. 检查浏览器存活
      await this.ensureBrowser();
      const ctx = await this.getContext(platform);
      const page = await ctx.newPage();
      // 设置 Playwright 级别超时，确保底层操作也受控
      page.setDefaultTimeout(effectiveTimeout);
      page.setDefaultNavigationTimeout(effectiveTimeout);
      try {
        // 3. 超时控制（带 timer 清理，避免泄漏）
        let timer: ReturnType<typeof setTimeout>;
        const result = await Promise.race([
          fn(page),
          new Promise<never>((_, reject) => {
            timer = setTimeout(
              () => reject(new Error(`操作超时: ${effectiveTimeout}ms`)),
              effectiveTimeout,
            );
          }),
        ]);
        clearTimeout(timer!);
        return result;
      } catch (err) {
        // 超时时 fn 可能仍在运行，page.close() 会中断它
        throw err;
      } finally {
        await page.close().catch(() => {});
      }
    });
    this.queues.set(platform, task.then(() => {}, () => {}));

    // 队列深度计数还原
    task.finally(() => {
      this.queueDepths.set(platform, (this.queueDepths.get(platform) ?? 1) - 1);
    });

    return task;
  }

  // 登录专用：返回 Page 不自动关闭，调用方负责生命周期
  // release 必须是幂等的（内部用 released 标志位防止重复调用）
  async acquirePage(platform: string): Promise<{ page: Page; release: () => Promise<void> }> {
    await this.ensureBrowser();
    const ctx = await this.getContext(platform);
    const page = await ctx.newPage();

    let released = false;
    const release = async () => {
      if (released) return;  // 幂等
      released = true;
      await page.close().catch(() => {});
    };

    // 安全网：最长 5 分钟自动释放，防止 release 忘记调用
    const maxLifetime = setTimeout(() => {
      logger.warn({ platform }, '页面超过最大生命周期，强制释放');
      release();
    }, 5 * 60 * 1000);

    return {
      page,
      release: async () => {
        clearTimeout(maxLifetime);
        await release();
      },
    };
  }

  // 检查浏览器存活，崩溃则重建
  // 用 launchPromise 作为启动锁，防止并发调用时启动多个浏览器进程
  private async ensureBrowser(): Promise<Browser> {
    if (this.browser?.isConnected()) return this.browser;

    if (!this.launchPromise) {
      this.launchPromise = (async () => {
        // 如果 browser 存在但已断开，先清理
        if (this.browser) {
          logger.warn('浏览器连接断开，正在重新启动');
          this.contexts.clear();
          this.browser = null;
        }
        const browser = await chromium.launch({ headless: config.headless });
        // 监听断开事件，主动清理状态
        browser.on('disconnected', () => {
          logger.error('浏览器进程意外断开');
          this.browser = null;
          this.contexts.clear();
        });
        this.browser = browser;
        return browser;
      })().finally(() => {
        this.launchPromise = null;
      });
    }

    return this.launchPromise;
  }

  private async getContext(platform: string): Promise<BrowserContext>;
  async saveCookies(platform: string): Promise<void>;

  // 等待所有队列排空（用于优雅关闭）
  async drain(): Promise<void> {
    await Promise.allSettled(Array.from(this.queues.values()));
  }

  async close(): Promise<void>;
}

关键设计点：

per-platform 串行队列：同一平台操作排队，不同平台可并行
队列背压：MAX_QUEUE_DEPTH = 10，超出直接拒绝，防止无限排队
分级超时：按操作类型设置不同超时（like 15s vs publish 5min），避免快操作被慢操作的默认超时卡住
超时 timer 清理：Promise.race 成功后 clearTimeout，避免 timer 泄漏和 unhandledRejection
Playwright 级别超时：page.setDefaultTimeout() 确保底层操作也受控，超时时 page.close() 会中断正在运行的 fn
启动锁：launchPromise 防止并发调用 ensureBrowser() 时启动多个浏览器进程
崩溃恢复：browser.on('disconnected') 主动清理状态，下次调用自动重建
登录特殊处理：acquirePage() 返回幂等的 release 函数 + 5 分钟安全网超时
优雅关闭：drain() 等待所有队列排空后再关闭浏览器

6.2 登录流程（特殊 Page 生命周期）

// login.ts — 扫码登录不能用 withPage（需要页面保持打开等用户扫码）
export async function getLoginQRCode(browser: BrowserManager): Promise<QRCodeResult> {
  const { page, release } = await browser.acquirePage('xiaohongshu');

  try {
    await page.goto('https://www.xiaohongshu.com/explore');
    // ... 检查是否已登录 ...
    const qrcodeData = await page.getAttribute('.login-container .qrcode-img', 'src');

    // 后台等待扫码完成，然后保存 Cookie 并释放 Page
    // 必须 catch 错误，fire-and-forget 不能让异常逃逸
    waitForLoginAndRelease(page, browser, release).catch(err => {
      logger.error({ err }, '登录等待流程异常');
    });

    return { qrcodeData, alreadyLoggedIn: false, timeout: '4m' };
  } catch (err) {
    await release();
    throw err;
  }
}

async function waitForLoginAndRelease(page: Page, browser: BrowserManager, release: () => Promise<void>) {
  // release 已经是幂等的（BrowserManager.acquirePage 保证），
  // 所以即使 setTimeout 和 finally 都触发，也不会重复释放。
  const timeout = setTimeout(() => release(), 4 * 60 * 1000);
  try {
    await page.waitForSelector('.user .link-wrapper .channel', { timeout: 4 * 60 * 1000 });
    await browser.saveCookies('xiaohongshu');
  } catch {} finally {
    clearTimeout(timeout);
    await release();
  }
}

Review 修正：原设计中 release() 没有幂等保护，setTimeout 和 finally 可能双重触发。现在 acquirePage 内部保证 release 幂等（released 标志位），彻底消除该竞态。同时 waitForLoginAndRelease 的 fire-and-forget 调用必须 .catch() 防止异常逃逸。

6.3 CookieStore

class CookieStore {
  // 目录: ~/.social-auto-hub/<platform>/
  // 文件权限: 0o600（仅 owner 可读写）
  // 目录权限: 0o700

  getPath(platform: string): string;
  async load(platform: string): Promise<StorageState | null>;

  // 原子写入：先写临时文件再 rename，防止崩溃导致文件损坏
  async save(platform: string, state: StorageState): Promise<void> {
    const filePath = this.getPath(platform);
    const tmpPath = `${filePath}.tmp.${process.pid}`;
    await fs.writeFile(tmpPath, JSON.stringify(state), { mode: 0o600 });
    await fs.rename(tmpPath, filePath);
  }

  async delete(platform: string): Promise<void>;
}

Review 补充：Cookie 加密（AES-256-GCM）暂不实现。当前安全模型：文件权限 0600 + 监听 127.0.0.1，对本地自动化工具足够。如果未来需要更高安全级别（多用户共享机器），再引入加密 + OS keychain 集成。

6.4 统一错误处理 + 错误分类

浏览器自动化的错误类型多样，AI 助手需要根据错误类型决定下一步操作（重试？重新登录？报告失败？）。因此引入错误分类体系，让 MCP 响应携带结构化的错误信息。

// utils/errors.ts

// 错误分类枚举
enum ErrorCategory {
  TIMEOUT = 'TIMEOUT',                   // 操作超时
  AUTH_REQUIRED = 'AUTH_REQUIRED',       // 需要登录
  SELECTOR_NOT_FOUND = 'SELECTOR_NOT_FOUND', // 选择器未找到（平台 UI 可能已变）
  NETWORK = 'NETWORK',                   // 网络错误
  PLATFORM_ERROR = 'PLATFORM_ERROR',     // 平台返回错误
  INTERNAL = 'INTERNAL',                 // 内部错误
}

// 错误分类函数
function classifyError(err: Error): ErrorCategory {
  const msg = err.message.toLowerCase();
  if (msg.includes('timeout') || err.name === 'TimeoutError') return ErrorCategory.TIMEOUT;
  if (msg.includes('net::err_')) return ErrorCategory.NETWORK;
  if (msg.includes('login') || msg.includes('登录')) return ErrorCategory.AUTH_REQUIRED;
  if (msg.includes('waiting for selector') || msg.includes('找不到元素')) return ErrorCategory.SELECTOR_NOT_FOUND;
  return ErrorCategory.INTERNAL;
}

// 错误消息脱敏：去掉文件路径、长 token 等内部信息
function sanitizeErrorMessage(message: string): string {
  return message
    .replace(/\/[^\s:]+/g, '[path]')           // 文件系统路径
    .replace(/https?:\/\/[^\s]+/g, '[url]')    // URL（可能含 token）
    .replace(/[a-f0-9]{32,}/gi, '[hash]')      // 长 hex 串
    .substring(0, 200);
}

// 统一错误包装（注意：必须是 async 函数）
export async function withErrorHandling(
  toolName: string,
  fn: () => Promise<McpToolResult>,
): Promise<McpToolResult> {
  try {
    return await fn();
  } catch (err) {
    const error = err instanceof Error ? err : new Error(String(err));
    const category = classifyError(error);
    const safeMessage = sanitizeErrorMessage(error.message);

    logger.error({ tool: toolName, category, err: error }, '工具执行失败');

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          tool: toolName,
          error: category,
          message: safeMessage,
        }),
      }],
      isError: true,
    };
  }
}

每个 MCP 工具 handler 用 withErrorHandling 包裹，Playwright 的 TimeoutError、 TargetClosedError 等异常统一转为 MCP 的 isError: true 响应，不会导致连接断开。 AI 助手可以根据 error 字段判断是否需要重试、重新登录、或报告错误。

Review 修正：原设计中 withErrorHandling 不是 async 却用了 await（编译不通过），且返回类型 T 和 McpToolResult 不匹配。已修正。新增错误分类 + 消息脱敏，防止泄露文件路径等内部信息。

6.5 日志脱敏

// utils/logger.ts
import pino from 'pino';

export const logger = pino({
  // 使用深层通配 ** 匹配任意嵌套层级，避免漏掉嵌套对象中的敏感字段
  redact: {
    paths: [
      '**.cookie', '**.cookies', '**.set-cookie',
      '**.authorization', '**.password', '**.secret',
      '**.token', '**.xsec_token', '**.access_token', '**.refresh_token',
      '**.api_key', '**.apikey',
      '**.sessionid', '**.session_id',
      '**.cookies[*].value',               // Playwright StorageState 中的 cookie 值
      '**.origins[*].localStorage[*].value', // Playwright StorageState 中的 localStorage 值
    ],
    censor: '[REDACTED]',
  },
  // 自定义错误序列化：生产环境不输出 stack
  serializers: {
    err: (err: Error) => ({
      type: err.constructor.name,
      message: err.message,
      ...(process.env.NODE_ENV === 'development' ? { stack: err.stack } : {}),
    }),
  },
  transport: process.env.NODE_ENV !== 'production'
    ? { target: 'pino-pretty' }
    : undefined,
});

// 生产环境禁用 Playwright 调试日志（会绕过 pino 直接输出到 stdout）
if (process.env.NODE_ENV === 'production') {
  delete process.env.DEBUG;
}

Review 修正：原 *.field 只匹配一层嵌套，改为 **.field 深层匹配。补充了 Playwright StorageState 中 cookie value 的脱敏规则。生产环境禁用 DEBUG=pw:* 防止 Playwright 调试日志泄露敏感信息。

七、安全基线（Phase 1 必须落地）

措施	说明
默认监听 127.0.0.1	配置项 `HOST=127.0.0.1`，不暴露到局域网/公网
Host header 校验	中间件校验 Host 头只允许 `127.0.0.1` / `localhost`，防御 DNS rebinding 攻击
拒绝监听 0.0.0.0	如果用户配置 `HOST=0.0.0.0`，启动时警告并要求设置 `ALLOW_REMOTE=yes-i-understand-the-risk`
Cookie 文件权限 0600	`fs.writeFile` 时指定 `mode: 0o600`，目录 0o700
Cookie 原子写入	先写 `.tmp` 文件再 `rename`，防止崩溃导致文件损坏
不加 CORS	MCP 客户端走 HTTP 不走浏览器，不需要 CORS header
日志深层脱敏	pino `**` 深层通配，token/cookie/password 永远不入日志
错误消息脱敏	`sanitizeErrorMessage()` 去掉文件路径、长 token，不返回堆栈
媒体文件路径校验	发布图片/视频时校验路径无 `..` 穿越，限制文件大小和 MIME 类型

7.1 DNS Rebinding 防御

即使监听 127.0.0.1，攻击者网页仍可通过 DNS rebinding 向本地服务发送请求。由于浏览器对 simple POST（Content-Type: text/plain 等）不做 preflight，写操作会被执行。

// server/middleware.ts
function dnsRebindingGuard(req: Request, res: Response, next: NextFunction) {
  const host = req.headers.host?.toLowerCase();
  const allowed = ['127.0.0.1', 'localhost', `127.0.0.1:${PORT}`, `localhost:${PORT}`];
  if (!host || !allowed.includes(host)) {
    logger.warn({ host }, 'DNS rebinding 请求被拦截');
    return res.status(403).json({ error: 'Forbidden' });
  }
  next();
}

7.2 REST API 认证（Phase 5 实现）

REST API 启用时必须加 Bearer token 认证。首次启动生成随机 token 并显示给用户。使用 crypto.timingSafeEqual 做时序安全比较。

7.3 媒体文件安全

// 发布图片/视频时的路径校验
function validateMediaPath(filePath: string): string {
  const resolved = path.resolve(filePath);
  if (filePath.includes('..')) throw new Error('路径穿越不允许');
  // 校验文件大小（图片 20MB，视频 500MB）
  // 通过 magic bytes 校验 MIME 类型，不信任扩展名
  return resolved;
}

Review 说明：DNS rebinding 是安全审计提出的高优先级风险，实现成本极低（一个中间件），Phase 1 必须加。 Bearer token 认证延迟到 Phase 5（REST API 实现时）。MCP 走 stdio transport，不经过 HTTP，不受此影响。

八、实现计划

Phase 1: 骨架 + 基础设施

初始化项目（pnpm, tsconfig, tsup, .gitignore, CLAUDE.md, .env.example）
src/config/index.ts — 环境变量（PORT, HOST=127.0.0.1, HEADLESS, BROWSER_BIN）+ 启动时校验 HOST（拒绝 0.0.0.0 除非显式确认）
src/utils/logger.ts — pino + ** 深层 redact 脱敏 + 自定义错误序列化
src/utils/errors.ts — withErrorHandling 错误包装 + 错误分类（ErrorCategory）+ 消息脱敏
src/browser/manager.ts — BrowserManager（串行队列 + 分级超时 + timer 清理 + 启动锁 + 背压 + acquirePage 幂等释放 + 崩溃恢复 + drain）
src/cookie/store.ts — CookieStore（权限 0600 + 原子写入）
src/server/app.ts — AppServer（Express + MCP，不加 CORS）
src/server/middleware.ts — DNS rebinding 防御中间件（Host header 校验）+ 优雅关闭 503 中间件
src/index.ts — 入口 + SIGINT/SIGTERM 优雅关闭（先 drain 队列 → 关浏览器 → 关 HTTP → flush 日志）+ 全局 unhandledRejection / uncaughtException 处理
src/utils/downloader.ts — 图片下载（发布功能的前置依赖）+ 媒体路径校验
/health 端点 — 检查 Browser 存活、队列深度、内存使用（从 Phase 5 提前到 Phase 1）
测试：BrowserManager 单元测试（队列串行、背压拒绝、超时、启动锁）+ CookieStore 单元测试（读/写/删/原子写入）+ 错误分类单元测试

Phase 2: 小红书 — 登录

selectors.ts + types.ts + schemas.ts
login.ts — 扫码登录、状态检查（使用 acquirePage，release 幂等）
actions.ts 初始化 + index.ts 注册 3 个登录工具
测试：zod schema 校验测试 + MCP Inspector 端到端验证登录流程

Phase 3: 小红书 — 内容浏览

feeds.ts — 首页 Feed 列表（__INITIAL_STATE__ 提取）
search.ts — 搜索 + 筛选
feed-detail.ts — 笔记详情 + 评论加载（scroll_speed 等内部默认配置）
user-profile.ts — 用户主页
测试：__INITIAL_STATE__ JSON 解析单元测试 + MCP Inspector 验证 4 个浏览工具

Phase 4: 小红书 — 发布 + 互动

publish.ts — 图文发布（依赖 downloader + 媒体路径校验）
publish-video.ts — 视频发布
comment.ts — 评论 + 回复
interaction.ts — 点赞 / 收藏
测试：downloader 单元测试 + 写操作手动验证（使用测试账号）

Phase 5: 工程化

REST API 路由（调用 actions 层，复用 MCP 的业务逻辑）+ Bearer token 认证 + 限流
Docker（见下方 Docker 配置要求）
README

九、测试策略

9.1 原则

这个项目的核心是浏览器自动化，大部分逻辑依赖真实页面交互。 不 mock Playwright Page 来测试页面操作——成本高、收益低、选择器一变全白写。只对可独立测试的纯逻辑写单元测试，浏览器交互靠端到端手动验证。

9.2 测试框架

工具	用途
vitest	单元测试（快，原生 TS 支持，兼容 Jest API）
MCP Inspector	MCP 工具端到端验证（官方调试工具）

devDependencies 补充："vitest": "^3.0.0"

9.3 单元测试范围

模块	测什么	怎么测
BrowserManager	串行队列（并发调用按序执行）、超时（超时后正确抛错 + timer 被清理）、启动锁（并发 ensureBrowser 只启动一次）、背压（超出 MAX_QUEUE_DEPTH 拒绝）、崩溃恢复（isConnected=false 时重建）	mock `chromium.launch` 和 `Browser` 接口
CookieStore	读/写/删、文件权限 0600、目录自动创建、原子写入（先 tmp 再 rename）	真实文件系统（临时目录）
withErrorHandling	正常返回透传、异常转 `isError: true`、错误分类正确性、消息脱敏（路径/token 被替换）	纯函数测试
classifyError	TIMEOUT / AUTH_REQUIRED / SELECTOR_NOT_FOUND / NETWORK / INTERNAL 各类型识别	构造不同错误消息测试
sanitizeErrorMessage	文件路径替换、URL 替换、长 hex 串替换、长度截断	纯函数测试
downloader	URL 下载、本地路径校验（无 `..` 穿越）、非图片类型拒绝、文件大小限制	mock HTTP 请求
数据解析	`__INITIAL_STATE__` JSON → Feed/Comment 类型的转换	固定 JSON fixture 输入，断言输出结构
zod schema	必填字段缺失报错、可选字段默认值、枚举值校验	直接调用 `.parse()` / `.safeParse()`
dnsRebindingGuard	合法 Host 放行、非法 Host 返回 403	构造 mock request 测试

9.4 端到端验证（手动）

每个 Phase 结束后，用 MCP Inspector 连接服务，逐个调用该阶段的 MCP 工具：

Phase	验证内容
Phase 2	`xhs_check_login` → `xhs_get_login_qrcode`（扫码）→ `xhs_check_login`（确认已登录）→ `xhs_delete_cookies` → `xhs_check_login`（确认已登出）
Phase 3	`xhs_list_feeds`（有数据返回）→ `xhs_search`（关键词+筛选）→ `xhs_get_feed_detail`（取第一条的详情）→ `xhs_get_user_profile`
Phase 4	`xhs_publish_image`（测试账号发一条）→ `xhs_post_comment` → `xhs_like` → `xhs_favorite`。写操作用测试账号，不用主力账号

9.5 不做的

不 mock Page 测页面操作：选择器绑定真实 DOM，mock 出来的测试没有意义
不做 CI 自动化端到端测试：依赖真实浏览器 + 真实平台登录态，不适合 CI
不追求覆盖率指标：只测有价值的纯逻辑，不为凑数写无意义的测试

十、关键设计决策

10.1 为什么不做统一 Platform 接口？

各平台业务模型差异大，强行统一 = 大量 NotSupported + 失去类型安全。 插件模式：共享基础设施，业务逻辑完全独立。

10.2 BrowserContext 隔离 + 串行队列

一个 Browser 进程 + 每个平台一个 BrowserContext + per-platform 操作串行化。

共享进程，节省资源
Cookie/Storage 天然隔离
串行避免多 Page 互相干扰（同一平台同时只有一个操作在执行）

读写分离队列（暂不实现）：性能工程师建议读操作（搜索、浏览）可以并发执行，只有写操作需要串行。理论上正确，但当前 MCP 工具由 AI 顺序调用，极少出现并发场景。保持简单串行队列，如果未来确实遇到队列积压问题，再升级为读写锁。不过早优化。

进程级隔离（暂不实现）：性能工程师建议每个平台一个浏览器进程，隔离崩溃影响。当前只有一个平台，一个进程足够。每多一个进程 +300MB 内存。等 3+ 平台时再考虑。

10.3 登录流程为什么不用 withPage？

withPage 是"用完即关"，但扫码登录需要：

打开页面获取二维码 → 返回给 AI
用户扫码（页面保持打开）
扫码成功 → 保存 Cookie → 关闭页面

因此登录使用 acquirePage() + 手动 release，其他操作用 withPage()。 release 函数是幂等的（内部 released 标志位），防止 setTimeout 和 finally 双重触发。

10.4 zod 一鱼两吃

MCP 工具参数 schema（运行时校验）
TypeScript 类型推导（z.infer）
MCP SDK v1.x server.tool() 原生支持 zod shape

10.5 MCP 工具前缀 `xhs_`

简短、AI 易识别。后续平台：xhh_（小黑盒）、bili_（B站）、wb_（微博）。

安全审计建议用 AES-256-GCM 加密 cookie 文件并集成 OS keychain。当前安全模型（文件权限 0600 + 监听 127.0.0.1 + Host 校验）对本地自动化工具足够。加密引入密钥管理复杂度（密钥存哪里？），收益与成本不匹配。如果未来需要多用户共享机器或远程部署，再引入加密。

10.7 为什么不做选择器 fallback？

架构师建议为每个 CSS 选择器准备 fallback 备选。但选择器失效时通常整个页面结构都变了，fallback 大概率也失效。保持简单的 selectors.ts 集中管理，发现失效时快速修复即可。

十一、风险和注意事项

CSS 选择器失效 — 集中到 selectors.ts 便于快速修复
反爬升级 — rebrowser-playwright 修复底层检测点，比 JS 层 stealth 更彻底，但仍需持续跟进
浏览器资源 — Playwright 进程 ~300MB，Docker 镜像较大
Node.js 部署 — Docker 是推荐方式
浏览器崩溃影响 — 所有平台共享一个 Browser 进程，崩溃时全部 context 丢失。browser.on('disconnected') 主动清理状态，下次操作自动重建
Cookie 过期 — 平台可能随时吊销 session。当前无主动检测机制，依赖操作失败时的错误分类（AUTH_REQUIRED）提示 AI 重新登录
DNS rebinding 攻击 — 即使监听 localhost，攻击者网页可通过 DNS rebinding 发送 POST 请求触发写操作。Phase 1 用 Host header 校验中间件防御
Docker /dev/shm — 必须配置 shm_size: 1gb，否则 Chromium 会因共享内存不足 SIGBUS 崩溃
长操作队列阻塞 — 视频发布可能耗时 1-5 分钟，期间同平台其他操作全部排队等待。已用分级超时缓解（快操作 15s 超时，不会被慢操作的默认超时卡住）

十二、Docker 配置要求

# deploy/docker-compose.yml
services:
  social-auto-hub:
    build: .
    ports:
      - "127.0.0.1:3000:3000"   # 必须带 127.0.0.1 前缀，不要省略
    shm_size: '1gb'               # 必须：Chromium 需要足够的共享内存，默认 64MB 会导致 SIGBUS 崩溃
    deploy:
      resources:
        limits:
          memory: 2g              # 至少 2x 预期峰值
          cpus: '2.0'             # Chromium 多进程架构需要至少 2 核
        reservations:
          memory: 1g
          cpus: '1.0'
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    read_only: true
    tmpfs:
      - /tmp:size=512m
    volumes:
      - cookie-data:/home/appuser/.social-auto-hub
    environment:
      - NODE_ENV=production

volumes:
  cookie-data:

# Dockerfile 要点
# - 非 root 用户运行（UID 1001）
# - 多阶段构建，不把 .env 或密钥文件复制进镜像层
# - HEALTHCHECK 检查 /health 端点
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
    CMD node -e "fetch('http://localhost:3000/health').then(r => process.exit(r.ok ? 0 : 1))"

十三、依赖清单

{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.27.0",
    "rebrowser-playwright": "^1.52.0",
    "express": "^4.21.0",
    "pino": "^9.0.0",
    "zod": "^3.25.0"
  },
  "devDependencies": {
    "typescript": "^5.7.0",
    "tsup": "^8.0.0",
    "vitest": "^3.0.0",
    "pino-pretty": "^13.0.0",
    "@types/express": "^5.0.0",
    "@types/node": "^22.0.0"
  }
}

附录 A：Review 修正清单

本 Plan 经过四方专业评审（架构师、安全审计、后端架构师、性能工程师），以下是已采纳的修正：

已整合进 Plan 的修正（P0/P1）

优先级	问题	来源	对应章节
P0	超时 timer 泄漏 + fn 在 page 关闭后继续运行	全员	6.1 BrowserManager
P0	`ensureBrowser()` 并发竞争可能启动多个浏览器	后端+性能	6.1 launchPromise
P0	`release()` 双重调用竞态	后端+架构	6.1 acquirePage + 6.2 登录流程
P0	`withErrorHandling` 缺少 async 关键字	后端	6.4 错误处理
P1	队列无深度限制（无背压）	全员	6.1 MAX_QUEUE_DEPTH
P1	缺少错误分类体系	架构+后端	6.4 ErrorCategory
P1	错误消息泄露文件路径	安全	6.4 sanitizeErrorMessage
P1	DNS rebinding 攻击	安全	7.1 dnsRebindingGuard
P1	日志 redact 只匹配一层	安全	6.5 `**` 深层通配
P1	Health check 在 Phase 5 太晚	架构+性能	8 Phase 1 第 11 项
P1	Docker `shm_size` 缺失	性能	十二 Docker 配置
P1	浏览器崩溃后 contexts Map 残留	后端+性能	6.1 disconnected 事件

已整合但标记为延迟实现的

问题	来源	决定	对应章节
PlatformPlugin 生命周期钩子	架构	可选钩子，第二个平台时评估	3.2
REST API Bearer token	安全	Phase 5 实现	7.2
媒体文件路径穿越	安全	Phase 4 publish 时实现	7.3
Cookie 原子写入	后端	Phase 1 CookieStore 实现	6.3
分级超时	性能	Phase 1 BrowserManager 实现	6.1

评审后明确不采纳的

建议	来源	不采纳原因	对应章节
Cookie 加密 + OS keychain	安全	本地工具，文件权限已足够，密钥管理增加复杂度	10.6
选择器 fallback 机制	架构	选择器失效时通常整页变化，fallback 无意义	10.7
读写分离队列	性能	AI 顺序调用极少并发，过早优化	10.2
进程级平台隔离	性能	只有一个平台，+300MB/进程成本过高	10.2
内存安全（Buffer 清零）	安全	JS 字符串不可变，Node.js 中不实用	—

38 KiB Raw Blame History Unescape Escape

Social Auto Hub — 多平台社交自动化 MCP 服务