front/docs/小红书模块设计-063001.md

小红书模块 — 表结构与接口设计

代码基线：E:\oms0414（前端）+ C:\Users\wilso\Desktop\oms0414-back（后端）+ C:\Users\wilso\Desktop\LIKE AI（本地 Agent 执行面）
关联文档：docs/oms系统设计-050801.md（OMS 通用约定）、docs/rbac系统设计-060801.md（认证与菜单）
版本：v0.1 · 2026-06-30

---

1　导读

1.1 这份文档解决什么问题？

将 LIKE AI 桌面端的核心内容运营能力迁入 OMS Web，形成独立业务模块「小红书」：

页面（菜单）	说明
启动服务	Agent 连接、Bridge/扩展/登录状态、引擎启停
内容分析	首页/搜索采集、笔记详情、AI 分析、互动留痕
爆款创作	AI 辅助写稿、配图、即时/定时发布
发布记录	历史发布与定时任务状态
技能卡片	从找题到发布的一键技能配方
拟人设置	浏览器人类行为 + 防封号节奏（原 LIKE AI「系统设置」）

AI 助手（ChatGPT / 豆包 / DeepSeek / 智谱 配置与对话）放在 系统 菜单下，不在「小红书」一级菜单内。

1.2 明确不在 OMS 范围内

以下能力 不设计表、不设计接口、不做 Web 页面，继续由 LIKE AI 本地 Agent 自行处理：

能力	说明
物流查价	Agent 内部按需调用已有 POST /order/price-check，OMS 无感知
请求日志	CLI/引擎调试日志仅存本机
授权 License	独立激活码体系保留在 Agent，不走 OMS RBAC

1.3 架构原则

flowchart LR
    subgraph OMS["OMS（控制面）"]
        Web["Vue 小红书模块"]
        API["/xhs/* ApplicationService"]
        DB[(MySQL t_xhs_*)]
        Web --> API --> DB
    end

    subgraph Agent["LIKE AI Agent（执行面）"]
        Bridge["Bridge + Chrome 扩展"]
        Local["本地：License / 日志 / 查价"]
    end

    Web <-->|"HTTPS + JWT"| Agent
    Agent --> Bridge
    Agent --> Local

• Web 编排任务、存业务数据；Agent 在本机 Chrome 执行。
• Agent 使用用户 OMS Access Token 认证（Authorization: Bearer），与客户数据隔离规则同 OMS 其他模块。

1.4 后端实现约定（与 OMS 一致）

项	约定
框架	.NET 8、Fake ApplicationService 自动映射 API
数据访问	SqlSugar + MySQL
路由前缀	/xhs/*
分页	OmsPageResult<T> → { items, total }；默认 pageSize 30
客户隔离	OmsSessionHelper.ResolveListCustomerIdAsync / ResolveSessionCustomerAsync
Swagger 分组	OMS-Xhs

---

2　前端菜单与路由

2.1 菜单结构

一级菜单：小红书

order	菜单名	path	name	component	permission
4	启动服务	/xhs/startService	XhsStartService	views/xhs/startService/index.vue	Xhs.Agent.Query
5	内容分析	/xhs/analysis	XhsAnalysis	views/xhs/analysis/index.vue	Xhs.Analysis.Use
6	爆款创作	/xhs/creation	XhsCreation	views/xhs/creation/index.vue	Xhs.Creation.Use
7	发布记录	/xhs/publishHistory	XhsPublishHistory	views/xhs/publishHistory/index.vue	Xhs.Publish.Query
8	技能卡片	/xhs/skills	XhsSkills	views/xhs/skills/index.vue	Xhs.Skills.Query
9	拟人设置	/xhs/humanSettings	XhsHumanSettings	views/xhs/humanSettings/index.vue	Xhs.HumanSettings.Save

路由模块文件：src/router/routes/newModules/xhs.ts

const XHS: AppRouteRecordRaw = {
  path: '/xhs',
  name: 'Xhs',
  component: DEFAULT_LAYOUT,
  meta: {
    locale: 'menu.xhs',
    icon: 'icon-book', // 或自定义小红书图标
    requiresAuth: true,
    order: 4,
  },
  children: [ /* 见上表 */ ],
};
export default XHS;

系统菜单下：AI 助手

菜单名	path	name	component	permission
AI 助手	/system/xhsAiAssistant	SystemXhsAiAssistant	views/system/xhsAiAssistant/index.vue	Xhs.Ai.Use

追加到 src/router/routes/newModules/system-management.ts 的 children 末尾。

说明：AI 接口仍走 /xhs/ai/*，仅 菜单位置 在「系统」下；客户门户若需使用 AI，通过 RBAC 分配 Xhs.Ai.Use 即可显示该菜单。

2.2 i18n 键名

'menu.xhs': '小红书',
'menu.xhs.startService': '启动服务',
'menu.xhs.analysis': '内容分析',
'menu.xhs.creation': '爆款创作',
'menu.xhs.publishHistory': '发布记录',
'menu.xhs.skills': '技能卡片',
'menu.xhs.humanSettings': '拟人设置',
'menu.system.xhsAiAssistant': 'AI 助手',

2.3 Vite / SPA 规则

/xhs/* 为纯前端路由：

• vite.config.ts → frontendRoutes 增加 '/xhs'（开发 history fallback）
• 生产由前端容器 serve -s 回退 index.html；API 走分域名 api.*，无需站内 nginx

---

3　权限码

PermissionCode	说明	典型角色
Xhs.Agent.Query	查看 Agent 状态、下载指引	客户主账号
Xhs.Agent.Control	Web 远程启停引擎、触发登录	客户主账号
Xhs.Analysis.Use	内容分析页、创建分析任务	客户主账号
Xhs.Creation.Use	爆款创作、上传媒体、提交发布	客户主账号
Xhs.Publish.Query	发布记录列表	客户主账号
Xhs.Publish.Cancel	取消定时发布	客户主账号
Xhs.Skills.Query	技能卡片列表	客户主账号
Xhs.Skills.Save	增删改技能卡片	客户主账号
Xhs.Skills.Run	一键执行技能	客户主账号
Xhs.HumanSettings.Save	读写拟人/防封配置	客户主账号
Xhs.Ai.Use	AI 助手页、对话与配置	客户 / 管理员
Xhs.Ai.Save	保存 AI 提供商密钥	客户 / 管理员
Xhs.Task.Query	任务列表（各页内嵌，可选独立页）	客户主账号

管理员（loginType=0）列表接口 不过滤 CustomerId，与订单模块当前实现一致；写操作须传 customerId 或使用 Agent 绑定关系校验。

---

4　数据表结构

命名前缀 t_xhs_，公共审计字段与 OMS 其他表一致。

4.1 Agent 设备表 t_xhs_agent

一台 Windows 本机 Agent 对应一条记录（按 DeviceId 唯一）。

CREATE TABLE `t_xhs_agent` (
  `Id` INT NOT NULL AUTO_INCREMENT COMMENT '主键',
  `CustomerId` INT NOT NULL COMMENT '客户ID → t_customer.Id',
  `DeviceId` VARCHAR(64) NOT NULL COMMENT 'Agent 本机设备标识（LIKE AI license.device_id 同源算法）',
  `DeviceName` VARCHAR(128) NULL COMMENT '用户自定义名称，如「办公室电脑」',
  `AgentVersion` VARCHAR(32) NULL COMMENT 'Agent 版本号',
  `BridgePort` INT NOT NULL DEFAULT 9333 COMMENT 'Bridge WebSocket 端口',
  `Status` VARCHAR(16) NOT NULL DEFAULT 'offline' COMMENT 'online/offline',
  `EngineRunning` TINYINT NOT NULL DEFAULT 0 COMMENT 'Bridge 引擎是否运行',
  `ExtensionConnected` TINYINT NOT NULL DEFAULT 0 COMMENT 'Chrome 扩展是否连上 Bridge',
  `XhsLoggedIn` TINYINT NOT NULL DEFAULT 0 COMMENT '小红书是否已登录',
  `LastHeartbeatTime` DATETIME NULL COMMENT '最后心跳时间',
  `LastError` VARCHAR(512) NULL COMMENT '最近一次 Agent 上报错误摘要',
  `IsDeleted` TINYINT NOT NULL DEFAULT 0,
  `ConcurrencyStamp` CHAR(36) NOT NULL DEFAULT (UUID()),
  `CreateUserId` INT NOT NULL DEFAULT 0,
  `CreateTime` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `UpdateUserId` INT NULL,
  `UpdateTime` DATETIME NULL,
  PRIMARY KEY (`Id`),
  UNIQUE KEY `uk_xhs_agent_device` (`DeviceId`),
  KEY `idx_xhs_agent_customer` (`CustomerId`, `Status`)
) COMMENT='小红书本地 Agent 设备表';

4.2 任务队列表 t_xhs_task

Web 创建 → Agent 拉取执行 → 回传结果。对应 LIKE AI XhsBridgeService.call_tool 及引擎控制。

CREATE TABLE `t_xhs_task` (
  `Id` INT NOT NULL AUTO_INCREMENT COMMENT '主键',
  `CustomerId` INT NOT NULL COMMENT '客户ID',
  `AgentId` INT NULL COMMENT '指定执行的 Agent；NULL 表示任意在线 Agent',
  `TaskType` VARCHAR(32) NOT NULL COMMENT '任务类型，见 §4.2.1',
  `ToolName` VARCHAR(64) NULL COMMENT 'LIKE AI 工具名，如 publish_content',
  `Priority` INT NOT NULL DEFAULT 0 COMMENT '越大越优先',
  `Status` VARCHAR(16) NOT NULL DEFAULT 'pending' COMMENT 'pending/claimed/running/succeeded/failed/cancelled',
  `ArgumentsJson` JSON NOT NULL COMMENT '工具参数 JSON',
  `ProgressText` VARCHAR(512) NULL COMMENT '执行过程摘要',
  `ResultJson` JSON NULL COMMENT '成功时结构化结果',
  `ErrorMessage` VARCHAR(1024) NULL COMMENT '失败原因',
  `Source` VARCHAR(32) NOT NULL DEFAULT 'web' COMMENT 'web/schedule/skill',
  `SourceRefId` VARCHAR(64) NULL COMMENT '来源关联，如 publish_record.Id、skill.Id',
  `ScheduledTime` DATETIME NULL COMMENT '计划执行时间；NULL 表示立即',
  `ClaimedAt` DATETIME NULL COMMENT 'Agent 认领时间',
  `StartedAt` DATETIME NULL COMMENT '开始执行',
  `FinishedAt` DATETIME NULL COMMENT '结束时间',
  `IsDeleted` TINYINT NOT NULL DEFAULT 0,
  `ConcurrencyStamp` CHAR(36) NOT NULL DEFAULT (UUID()),
  `CreateUserId` INT NOT NULL DEFAULT 0,
  `CreateTime` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `UpdateUserId` INT NULL,
  `UpdateTime` DATETIME NULL,
  PRIMARY KEY (`Id`),
  KEY `idx_xhs_task_poll` (`CustomerId`, `Status`, `ScheduledTime`, `Priority`),
  KEY `idx_xhs_task_agent` (`AgentId`, `Status`),
  KEY `idx_xhs_task_source` (`Source`, `SourceRefId`)
) COMMENT='小红书 Agent 任务队列表';

4.2.1 TaskType 枚举

TaskType	ToolName	说明
engine_start	—	启动 Bridge 引擎
engine_stop	—	停止 Bridge 引擎
browser_login	browser_login	打开 Chrome 扫码登录
clear_cookies	delete_cookies	清除登录 Cookie
check_login	check_login_status	检查登录状态
browse	list_feeds / search_feeds / my_account_feeds	浏览采集
feed_detail	get_feed_detail	笔记详情
interact	post_comment_to_feed 等	评论/点赞/收藏
publish	publish_content / publish_with_video	发布笔记
skill_pipeline	—	技能卡片编排（多步子任务，见 §4.5）

ArgumentsJson 结构与 LIKE AI skills_tool_adapter.build_cli_argv 入参一致，例如：

{
  "keyword": "跨境物流",
  "filters": { "sort_by": "最多点赞" },
  "feed_id": "6a095abd0000000006030184",
  "xsec_token": "ABIrq9ZLAO...",
  "title": "笔记标题",
  "content": "正文",
  "images": ["https://oms.../uploads/xhs/1.jpg"],
  "tags": ["生活"],
  "visibility": "公开可见"
}

图片路径：Web 上传至 OMS /uploads/xhs/{customerId}/，任务参数存 HTTPS URL；Agent 执行前下载到本机临时目录。

4.3 发布记录表 t_xhs_publish_record

对应 LIKE AI .xhs_bridge/publish_history.json。

CREATE TABLE `t_xhs_publish_record` (
  `Id` INT NOT NULL AUTO_INCREMENT COMMENT '主键',
  `CustomerId` INT NOT NULL COMMENT '客户ID',
  `TaskId` INT NULL COMMENT '关联 t_xhs_task.Id',
  `ToolName` VARCHAR(64) NOT NULL COMMENT 'publish_content / publish_with_video',
  `Title` VARCHAR(256) NOT NULL COMMENT '笔记标题',
  `ContentPreview` VARCHAR(512) NULL COMMENT '正文摘要',
  `ContentFull` TEXT NULL COMMENT '完整正文（可选存储）',
  `MediaJson` JSON NULL COMMENT '图片/视频 URL 列表',
  `TagsJson` JSON NULL COMMENT '标签数组',
  `Visibility` VARCHAR(32) NULL COMMENT '公开可见/仅自己可见等',
  `Status` VARCHAR(16) NOT NULL DEFAULT 'draft' COMMENT 'draft/scheduled/publishing/succeeded/failed/cancelled',
  `Success` TINYINT NULL COMMENT '最终是否成功：0/1',
  `ResultSummary` VARCHAR(1024) NULL COMMENT 'Agent 回传结果摘要',
  `ScheduledTime` DATETIME NULL COMMENT '定时发布时间',
  `PublishedTime` DATETIME NULL COMMENT '实际发布完成时间',
  `SkillId` INT NULL COMMENT '若来自技能卡片',
  `IsDeleted` TINYINT NOT NULL DEFAULT 0,
  `ConcurrencyStamp` CHAR(36) NOT NULL DEFAULT (UUID()),
  `CreateUserId` INT NOT NULL DEFAULT 0,
  `CreateTime` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `UpdateUserId` INT NULL,
  `UpdateTime` DATETIME NULL,
  PRIMARY KEY (`Id`),
  KEY `idx_xhs_publish_customer_time` (`CustomerId`, `CreateTime`),
  KEY `idx_xhs_publish_status_sched` (`CustomerId`, `Status`, `ScheduledTime`),
  KEY `idx_xhs_publish_task` (`TaskId`)
) COMMENT='小红书发布记录表';

4.4 内容分析会话表 t_xhs_analysis_session

保存一次「采集 + 分析」会话，避免大 JSON 堆在任务表。

CREATE TABLE `t_xhs_analysis_session` (
  `Id` INT NOT NULL AUTO_INCREMENT COMMENT '主键',
  `CustomerId` INT NOT NULL COMMENT '客户ID',
  `SessionName` VARCHAR(128) NULL COMMENT '用户备注名',
  `AnalysisType` VARCHAR(32) NOT NULL COMMENT 'home_feed/search/competitor/single_feed',
  `Keyword` VARCHAR(128) NULL COMMENT '搜索关键词',
  `TaskId` INT NULL COMMENT '采集任务 ID',
  `FeedsJson` JSON NULL COMMENT '采集到的笔记列表（结构同 browse.partial.json）',
  `SelectedFeedId` VARCHAR(64) NULL COMMENT '当前选中的笔记 ID',
  `AiAnalysisMarkdown` MEDIUMTEXT NULL COMMENT 'AI 分析结果 Markdown',
  `SkillId` INT NULL COMMENT '使用的技能配方 ID',
  `IsDeleted` TINYINT NOT NULL DEFAULT 0,
  `ConcurrencyStamp` CHAR(36) NOT NULL DEFAULT (UUID()),
  `CreateUserId` INT NOT NULL DEFAULT 0,
  `CreateTime` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `UpdateUserId` INT NULL,
  `UpdateTime` DATETIME NULL,
  PRIMARY KEY (`Id`),
  KEY `idx_xhs_analysis_customer` (`CustomerId`, `CreateTime`)
) COMMENT='小红书内容分析会话表';

4.5 技能卡片表 t_xhs_skill

对应 LIKE AI .xhs_bridge/skills.json。

CREATE TABLE `t_xhs_skill` (
  `Id` INT NOT NULL AUTO_INCREMENT COMMENT '主键',
  `CustomerId` INT NOT NULL COMMENT '客户ID；0 表示系统预置模板',
  `ExternalId` VARCHAR(32) NOT NULL COMMENT '对外稳定 ID（迁移自 LIKE AI skill.id）',
  `Title` VARCHAR(256) NOT NULL COMMENT '技能名称',
  `SkillType` VARCHAR(32) NOT NULL DEFAULT 'ai_create' COMMENT 'ai_create / analysis / ...',
  `PresetId` VARCHAR(64) NULL COMMENT '内置预设标识',
  `RecipeJson` JSON NOT NULL COMMENT '配方 JSON，结构同 LIKE AI skills.json.recipe',
  `SortOrder` INT NOT NULL DEFAULT 0 COMMENT '排序',
  `IsDeleted` TINYINT NOT NULL DEFAULT 0,
  `ConcurrencyStamp` CHAR(36) NOT NULL DEFAULT (UUID()),
  `CreateUserId` INT NOT NULL DEFAULT 0,
  `CreateTime` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `UpdateUserId` INT NULL,
  `UpdateTime` DATETIME NULL,
  PRIMARY KEY (`Id`),
  UNIQUE KEY `uk_xhs_skill_external` (`CustomerId`, `ExternalId`),
  KEY `idx_xhs_skill_customer` (`CustomerId`, `SortOrder`)
) COMMENT='小红书技能卡片表';

RecipeJson 示例（与 LIKE AI 一致）：

{
  "formula": ["emotion", "utility", "visual", "social"],
  "title_types": ["number", "question"],
  "body": {
    "domain": "物流知识",
    "content_type": "干货教程",
    "emotion": "生活场景",
    "social": "知识炫耀"
  },
  "image_modes": ["cover_impact"],
  "video_modes": [],
  "notes": "讲解9610的简易申报..."
}

4.6 拟人配置表 t_xhs_human_config

每个客户一行，存储 人类行为 + 防封号节奏 完整 JSON（对应 config.yaml 的 human_behavior + human_guard）。

CREATE TABLE `t_xhs_human_config` (
  `Id` INT NOT NULL AUTO_INCREMENT COMMENT '主键',
  `CustomerId` INT NOT NULL COMMENT '客户ID',
  `BehaviorJson` JSON NOT NULL COMMENT 'human_behavior 完整配置',
  `GuardJson` JSON NOT NULL COMMENT 'human_guard 完整配置',
  `Version` INT NOT NULL DEFAULT 1 COMMENT '配置版本，Agent 拉取时比对',
  `IsDeleted` TINYINT NOT NULL DEFAULT 0,
  `ConcurrencyStamp` CHAR(36) NOT NULL DEFAULT (UUID()),
  `CreateUserId` INT NOT NULL DEFAULT 0,
  `CreateTime` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `UpdateUserId` INT NULL,
  `UpdateTime` DATETIME NULL,
  PRIMARY KEY (`Id`),
  UNIQUE KEY `uk_xhs_human_customer` (`CustomerId`)
) COMMENT='小红书拟人行为与防封配置表';

Agent 心跳或任务拉取时若 Version 变化，写入本机 human_behavior.json / guard 状态文件。

默认配置：首次访问「拟人设置」时，后端用 LIKE AI human.py / human_guard.py 内置默认值 INSERT。

4.7 AI 提供商表 t_xhs_ai_provider

对应 .xhs_bridge/ai_providers.json；密钥加密存储（AES，密钥来自 OMS 配置项）。

CREATE TABLE `t_xhs_ai_provider` (
  `Id` INT NOT NULL AUTO_INCREMENT COMMENT '主键',
  `CustomerId` INT NOT NULL COMMENT '客户ID；管理员全局配置时可为 0',
  `ProviderKey` VARCHAR(32) NOT NULL COMMENT 'ai_chatgpt / ai_zhipu 等',
  `ProviderType` VARCHAR(32) NOT NULL COMMENT 'chatgpt/doubao/deepseek/zhipu',
  `DisplayName` VARCHAR(64) NOT NULL COMMENT '展示名',
  `BaseUrl` VARCHAR(512) NOT NULL COMMENT 'API Base URL',
  `ApiKeyEnc` VARCHAR(512) NULL COMMENT '加密后的 API Key',
  `ApiSecretEnc` VARCHAR(512) NULL COMMENT '加密后的 Secret/模型名',
  `IsDefault` TINYINT NOT NULL DEFAULT 0 COMMENT '是否默认对话提供商',
  `Enabled` TINYINT NOT NULL DEFAULT 1,
  `IsDeleted` TINYINT NOT NULL DEFAULT 0,
  `ConcurrencyStamp` CHAR(36) NOT NULL DEFAULT (UUID()),
  `CreateUserId` INT NOT NULL DEFAULT 0,
  `CreateTime` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `UpdateUserId` INT NULL,
  `UpdateTime` DATETIME NULL,
  PRIMARY KEY (`Id`),
  UNIQUE KEY `uk_xhs_ai_provider` (`CustomerId`, `ProviderKey`),
  KEY `idx_xhs_ai_customer` (`CustomerId`, `Enabled`)
) COMMENT='小红书 AI 提供商配置表';

4.8 媒体文件表 t_xhs_media（可选，建议 v1 实现）

CREATE TABLE `t_xhs_media` (
  `Id` INT NOT NULL AUTO_INCREMENT COMMENT '主键',
  `CustomerId` INT NOT NULL COMMENT '客户ID',
  `FileName` VARCHAR(256) NOT NULL COMMENT '原始文件名',
  `StoragePath` VARCHAR(512) NOT NULL COMMENT '相对路径 uploads/xhs/...',
  `PublicUrl` VARCHAR(512) NOT NULL COMMENT '对外 HTTPS URL',
  `MimeType` VARCHAR(64) NULL COMMENT 'image/jpeg 等',
  `FileSizeBytes` BIGINT NULL COMMENT '字节数',
  `IsDeleted` TINYINT NOT NULL DEFAULT 0,
  `CreateUserId` INT NOT NULL DEFAULT 0,
  `CreateTime` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`Id`),
  KEY `idx_xhs_media_customer` (`CustomerId`, `CreateTime`)
) COMMENT='小红书创作上传媒体表';

4.9 ER 关系概览

erDiagram
    t_customer ||--o{ t_xhs_agent : owns
    t_customer ||--o| t_xhs_human_config : has
    t_customer ||--o{ t_xhs_ai_provider : configures
    t_customer ||--o{ t_xhs_skill : owns
    t_customer ||--o{ t_xhs_task : creates
    t_customer ||--o{ t_xhs_publish_record : owns
    t_customer ||--o{ t_xhs_analysis_session : owns
    t_xhs_agent ||--o{ t_xhs_task : executes
    t_xhs_task ||--o| t_xhs_publish_record : generates
    t_xhs_skill ||--o{ t_xhs_publish_record : sources
    t_xhs_skill ||--o{ t_xhs_analysis_session : uses

---

5　接口设计

所有接口需 [Authorize]；Swagger 组 OMS-Xhs。

Service 建议拆分：

Service	文件	职责
XhsAgentService	Services/Xhs/XhsAgentService.cs	Agent 注册、心跳、状态
XhsTaskService	Services/Xhs/XhsTaskService.cs	任务 CRUD、Agent 拉取/上报
XhsPublishService	Services/Xhs/XhsPublishService.cs	发布记录、定时调度
XhsAnalysisService	Services/Xhs/XhsAnalysisService.cs	分析会话
XhsSkillService	Services/Xhs/XhsSkillService.cs	技能卡片
XhsHumanConfigService	Services/Xhs/XhsHumanConfigService.cs	拟人设置
XhsAiService	Services/Xhs/XhsAiService.cs	AI 提供商与对话
XhsMediaService	Services/Xhs/XhsMediaService.cs	媒体上传

---

5.1 Agent — 启动服务页

5.1.1 注册 / 更新 Agent

Agent 首次启动或 Token 变更时调用；Web 也可展示已注册设备列表。

POST /xhs/agent/register

Request

{
  "deviceId": "A1B2C3D4-....",
  "deviceName": "办公室电脑",
  "agentVersion": "1.0.0",
  "bridgePort": 9333
}

Response

{
  "agentId": 1,
  "customerId": 100,
  "deviceId": "A1B2C3D4-....",
  "humanConfigVersion": 3
}

5.1.2 心跳（Agent 每 30s）

POST /xhs/agent/heartbeat

Request

{
  "deviceId": "A1B2C3D4-....",
  "engineRunning": true,
  "extensionConnected": true,
  "xhsLoggedIn": true,
  "lastError": null
}

Response

{
  "ok": true,
  "humanConfigVersion": 3,
  "serverTime": "2026-06-30T12:00:00"
}

5.1.3 查询 Agent 列表（Web）

POST /xhs/agent/list

Request

{
  "page": 1,
  "pageSize": 30
}

Response OmsPageResult<XhsAgentOutput>

{
  "items": [
    {
      "id": 1,
      "deviceId": "A1B2C3D4-....",
      "deviceName": "办公室电脑",
      "status": "online",
      "engineRunning": true,
      "extensionConnected": true,
      "xhsLoggedIn": true,
      "lastHeartbeatTime": "2026-06-30T12:00:00",
      "agentVersion": "1.0.0"
    }
  ],
  "total": 1
}

在线判定：LastHeartbeatTime 距今 ≤ 90s 且 Status=online。

5.1.4 远程控制（Web → 创建任务）

POST /xhs/agent/control

Request

{
  "agentId": 1,
  "action": "engine_start"
}

action 枚举：engine_start | engine_stop | browser_login | clear_cookies | check_login

Response

{
  "taskId": 101
}

---

5.2 任务 — Agent 拉取与上报

5.2.1 Agent 拉取待执行任务

POST /xhs/task/claim

Request

{
  "deviceId": "A1B2C3D4-....",
  "limit": 1
}

Response

{
  "items": [
    {
      "id": 101,
      "taskType": "publish",
      "toolName": "publish_content",
      "arguments": { "title": "...", "images": ["https://..."] },
      "humanConfigVersion": 3
    }
  ]
}

认领后任务 Status → claimed；Agent 开始执行 → 调 report 置 running。

5.2.2 Agent 上报进度/结果

POST /xhs/task/report

Request

{
  "taskId": 101,
  "status": "succeeded",
  "progressText": "正在发布…",
  "result": { "summary": "发布成功" },
  "errorMessage": null
}

status：running | succeeded | failed

5.2.3 Web 查询任务（可选，调试）

POST /xhs/task/list

Request

{
  "page": 1,
  "pageSize": 30,
  "status": "pending",
  "taskType": null,
  "sourceRefId": null
}

5.2.4 取消任务

POST /xhs/task/cancel

Request

{
  "taskId": 101
}

仅 pending / claimed 可取消。

---

5.3 内容分析

5.3.1 创建分析会话并提交采集任务

POST /xhs/analysis/start

Request

{
  "analysisType": "search",
  "keyword": "跨境物流",
  "filters": {
    "sort_by": "最多点赞",
    "note_type": "图文"
  },
  "agentId": 1,
  "skillId": 5
}

analysisType：home_feed | search | my_feeds | feed_detail

Response

{
  "sessionId": 20,
  "taskId": 102
}

5.3.2 会话列表

POST /xhs/analysis/list

Response OmsPageResult<XhsAnalysisSessionOutput>

5.3.3 会话详情

POST /xhs/analysis/detail

Request { "sessionId": 20 }

Response 含 feedsJson、aiAnalysisMarkdown

5.3.4 AI 分析（基于已采集 feeds）

POST /xhs/analysis/run-ai

Request

{
  "sessionId": 20,
  "skillId": 5,
  "providerKey": "ai_zhipu",
  "selectedFeedIds": ["6a095abd0000000006030184"]
}

Response

{
  "markdown": "## 爆款共性\n\n1. ..."
}

后端调用 XhsAiService 代理转发，API Key 不出前端。

5.3.5 创建互动任务（评论/点赞）

POST /xhs/analysis/interact

Request

{
  "agentId": 1,
  "action": "post_comment",
  "feedId": "6a095abd0000000006030184",
  "xsecToken": "ABIrq9ZLAO...",
  "content": "写得太好了！"
}

---

5.4 爆款创作

5.4.1 AI 生成笔记文案

POST /xhs/creation/generate

Request

{
  "skillId": 5,
  "providerKey": "ai_zhipu",
  "topic": "9610 简易申报入门",
  "extraNotes": "面向外贸小白"
}

Response

{
  "title": "9610到底是什么？一文讲清",
  "content": "正文...",
  "tags": ["跨境", "物流"],
  "imagePrompts": ["清关流程信息图风格"]
}

5.4.2 上传图片

POST /xhs/media/upload
Content-Type: multipart/form-data

Response

{
  "mediaId": 1,
  "publicUrl": "https://oms.nanafa.com/uploads/xhs/100/abc.jpg"
}

5.4.3 提交发布（立即或定时）

POST /xhs/creation/publish

Request

{
  "agentId": 1,
  "toolName": "publish_content",
  "title": "笔记标题",
  "content": "正文",
  "mediaUrls": ["https://..."],
  "tags": ["生活"],
  "visibility": "公开可见",
  "scheduledTime": "2026-06-30T18:00:00",
  "skillId": null
}

scheduledTime 为空则立即创建 pending 任务；有值则 publish_record.Status=scheduled，由后台 定时扫描（或 Agent 心跳触发）生成任务。

Response

{
  "publishRecordId": 50,
  "taskId": 103
}

---

5.5 发布记录

5.5.1 分页列表

POST /xhs/publish/list

Request

{
  "page": 1,
  "pageSize": 30,
  "status": null,
  "keyword": null
}

Response OmsPageResult<XhsPublishRecordOutput>

5.5.2 取消定时发布

POST /xhs/publish/cancel

Request { "publishRecordId": 50 }

仅 scheduled 可取消；关联 pending 任务一并 cancelled。

5.5.3 重试失败发布

POST /xhs/publish/retry

Request { "publishRecordId": 50, "agentId": 1 }

---

5.6 技能卡片

5.6.1 列表

POST /xhs/skill/list

Response OmsItemsResult<XhsSkillOutput>（不分页，单客户通常 < 50 条）

5.6.2 保存（新增/更新）

POST /xhs/skill/save

Request

{
  "id": null,
  "title": "物流知识 · 干货教程",
  "skillType": "ai_create",
  "presetId": "",
  "recipe": { "formula": ["emotion", "utility"], "body": { "domain": "物流知识" } }
}

5.6.3 删除

POST /xhs/skill/delete

Request { "id": 5 }

5.6.4 一键执行技能

POST /xhs/skill/run

Request

{
  "skillId": 5,
  "agentId": 1,
  "runMode": "create_and_publish",
  "providerKey": "ai_zhipu",
  "topicOverride": null
}

runMode：analyze_only | create_only | create_and_publish

Response

{
  "taskIds": [104, 105],
  "publishRecordId": 51
}

---

5.7 拟人设置

5.7.1 获取配置

POST /xhs/human-config/get

Response

{
  "behavior": { "human_delay": { "min_ms": 300, "max_ms": 700 }, "home_browse_plan": { } },
  "guard": {
    "publish": { "max_per_day": 2, "min_interval_hours": 6 },
    "browse": { "max_per_hour": 20 },
    "quiet_hours": { "enabled": true, "start": "02:00", "end": "07:00" }
  },
  "version": 3
}

5.7.2 保存配置

POST /xhs/human-config/save

Request 同上结构；保存后 Version++，Agent 下次心跳拉取新版本。

5.7.3 Agent 拉取配置（内嵌 heartbeat 或独立）

POST /xhs/human-config/pull

Request { "deviceId": "...", "knownVersion": 2 }

若版本一致返回 { "unchanged": true }，否则返回完整 JSON。

---

5.8 AI 助手（系统菜单）

5.8.1 提供商列表

POST /xhs/ai/provider/list

Response：apiKey / apiSecret 脱敏（仅显示后四位）。

5.8.2 保存提供商

POST /xhs/ai/provider/save

Request

{
  "providerKey": "ai_zhipu",
  "providerType": "zhipu",
  "displayName": "智谱 GLM",
  "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
  "apiKey": "5fb9...",
  "apiSecret": "glm-5.1",
  "isDefault": true,
  "enabled": true
}

5.8.3 对话补全（Web AI 助手页）

POST /xhs/ai/chat

Request

{
  "providerKey": "ai_zhipu",
  "model": null,
  "messages": [
    { "role": "user", "content": "帮我写一个小红书标题" }
  ],
  "scene": "assistant"
}

scene：assistant | note_create | note_analysis | image_prompt | video_script

Response

{
  "content": "......",
  "usage": { "promptTokens": 100, "completionTokens": 200 }
}

5.8.4 图片提示词 / 文生图（可选 v2）

POST /xhs/ai/image-prompt
POST /xhs/ai/image-generate

---

6　定时发布调度

LIKE AI 原 publish_scheduler.process_due_scheduled 逻辑迁移到 OMS 后端：

1. 后台 IHostedService 或 Hangfire 每分钟扫描：

SELECT * FROM t_xhs_publish_record
WHERE Status = 'scheduled'
  AND ScheduledTime <= NOW()
  AND IsDeleted = 0
LIMIT 10;

2. 每条创建 t_xhs_task（Source=schedule, SourceRefId=publish_record.Id），并将记录置 publishing。
3. Agent claim 后执行；report 回写 publish_record 最终状态。

---

7　Agent 对接契约（LIKE AI 改造要点）

7.1 启动参数

like_ai_agent.exe --oms-url https://oms.nanafa.com/admin --token <JWT> --device-id <GUID>

7.2 主循环伪代码

while True:
    heartbeat()  # POST /xhs/agent/heartbeat
    pull_human_config_if_needed()
    tasks = claim_tasks(limit=1)  # POST /xhs/task/claim
    for task in tasks:
        report(task.id, status="running")
        result = service.call_tool(task.tool_name, task.arguments, check_license=True)
        report(task.id, status="succeeded", result=result)
    sleep(5)

7.3 不在 Agent 上报范围

• 物流查价记录
• CLI 请求日志
• License 激活状态（本地校验即可）

---

8　后端目录与迁移脚本

8.1 建议代码结构

Oms.Domain/XhsAggregate/Entities/
Oms.Domain/XhsAggregate/Repositories/
Oms.Application/Services/Xhs/
Oms.Application/Dtos/Xhs/
Oms.SqlSugarCore/Repositories/Xhs/
sql/migrate_t_xhs.sql          # 本设计 DDL 汇总

8.2 迁移脚本位置

C:\Users\wilso\Desktop\oms0414-back\sql\migrate_t_xhs.sql（实现阶段从本文 §4 导出）

同步更新 db.sql 末尾追加 t_xhs_* 表定义。

---

9　前端 API 模块

src/api/xhs/
  agent.ts
  task.ts
  analysis.ts
  creation.ts
  publish.ts
  skill.ts
  humanConfig.ts
  ai.ts
  media.ts
  index.ts

统一使用 @/api/rbac 的 axiosInstance（Bearer Token）。

---

10　实施顺序建议

阶段	交付
P0	DDL + XhsAgentService + XhsTaskService + Agent 心跳/拉取/上报 + 「启动服务」页
P1	发布记录 + 爆款创作 + 媒体上传 + 定时调度
P2	内容分析 + 技能卡片
P3	拟人设置 + AI 助手（系统菜单）
P4	RBAC 菜单种子数据、Agent 安装包下载页

---

11　接口路径速查

方法	路径	页面
POST	/xhs/agent/register	Agent
POST	/xhs/agent/heartbeat	Agent
POST	/xhs/agent/list	启动服务
POST	/xhs/agent/control	启动服务
POST	/xhs/task/claim	Agent
POST	/xhs/task/report	Agent
POST	/xhs/task/list	调试
POST	/xhs/task/cancel	各页
POST	/xhs/analysis/start	内容分析
POST	/xhs/analysis/list	内容分析
POST	/xhs/analysis/detail	内容分析
POST	/xhs/analysis/run-ai	内容分析
POST	/xhs/analysis/interact	内容分析
POST	/xhs/creation/generate	爆款创作
POST	/xhs/creation/publish	爆款创作
POST	/xhs/media/upload	爆款创作
POST	/xhs/publish/list	发布记录
POST	/xhs/publish/cancel	发布记录
POST	/xhs/publish/retry	发布记录
POST	/xhs/skill/list	技能卡片
POST	/xhs/skill/save	技能卡片
POST	/xhs/skill/delete	技能卡片
POST	/xhs/skill/run	技能卡片
POST	/xhs/human-config/get	拟人设置
POST	/xhs/human-config/save	拟人设置
POST	/xhs/human-config/pull	Agent
POST	/xhs/ai/provider/list	AI 助手
POST	/xhs/ai/provider/save	AI 助手
POST	/xhs/ai/chat	AI 助手 / 创作 / 分析

---

12　开放问题（实现前确认）

1. 子客户是否允许绑定 Agent、操作小红书？默认与订单一致：子客户可用，数据 CustomerId 为子客户自身 Id。
2. 系统预置技能（CustomerId=0）是否对所有客户只读可见？建议：只读 + 可复制到本客户。
3. AI 密钥：客户级 vs 租户级全局 — 当前设计为 客户级；管理员在系统菜单可配 CustomerId=0 作为全局默认 fallback。
4. SignalR 推送任务是否作为 v2 优化（当前 Agent 轮询 claim）。