Skill 清单

小红书投放数据接入的全部能力定义，按 4 个独立 Skill 组织。场景概览见小红书投放数据接入，角色维度的对话设计见角色场景。

架构总览

按业务域拆分为 4 个独立 Skill，与现有飞书 Skill 拆分粒度一致（渐进式加载）：

分层判断标准

层级	判断标准	开发产出
A — Skill	AI 需要场景指导、权限规则、工具组合策略	`skills/xhs-*/SKILL.md`
B — Tool	AI 需要调用，tool schema 可自描述	`scripts/direct/tools/xhs_*.py`
C — 系统能力	不需要 AI 感知，自动运行	工具内部逻辑 / 中间件
D — 主动推送	非对话触发，由定时任务驱动	Concern 引擎策略配置

Skill / Tool 汇总

名称	所属 Skill	描述	状态
`xhs-account` Skill	—	小红书账号管理对话技能	⬜ 待实现
`xhs-order` Skill	—	小红书订单与消耗对话技能	⬜ 待实现
`xhs-note` Skill	—	小红书笔记与内容对话技能	⬜ 待实现
`xhs-message` Skill	—	小红书私信与评论对话技能	⬜ 待实现
`xhs_list_accounts`	xhs-account	获取账号列表	⬜ 待实现
`xhs_get_account_detail`	xhs-account	获取单账号详情	⬜ 待实现
`xhs_get_account_balance`	xhs-account	查询余额明细	⬜ 待实现
`xhs_list_orders`	xhs-order	查询订单列表	⬜ 待实现
`xhs_get_order_stats`	xhs-order	获取推广效果统计	⬜ 待实现
`xhs_get_cost_summary`	xhs-order	全账号消耗汇总	⬜ 待实现
`xhs_export_stats_csv`	xhs-order	导出统计 CSV	⬜ 待实现
`xhs_list_notes`	xhs-note	获取笔记列表	⬜ 待实现
`xhs_get_note_stats`	xhs-note	单篇笔记效果	⬜ 待实现
`xhs_list_conversations`	xhs-message	获取私信会话列表	⬜ 待实现
`xhs_get_messages`	xhs-message	获取消息历史	⬜ 待实现
`xhs_list_comments`	xhs-message	获取评论列表	⬜ 待实现

A 层 — 4 个 Skill 定义

Skill 1：xhs-account（账号管理）

yaml

name: xhs-account
trigger: 小红书账号|账号余额|账号状态|在线|离线|账号分组|cookie
description: 小红书投放账号查询——余额、状态、分组
tools: [xhs_list_accounts, xhs_get_account_detail, xhs_get_account_balance]
scope: all

SKILL.md 场景指导：

查账号列表时按在线/离线分组展示
余额查询时拆分现金/赠款/薯币，低余额高亮
离线账号附带原因（cookie_expired / error）
权限规则：员工只看自己绑定的，部门负责人看本部门的

Skill 2：xhs-order（订单与消耗）

yaml

name: xhs-order
trigger: 消耗|订单|推广|聚光|预算|曝光|阅读|互动|转化|ROI|投放效果|导出|报表|CSV
description: 小红书聚光订单查询与分析——消耗、效果指标、报表导出
tools: [xhs_list_orders, xhs_get_order_stats, xhs_get_cost_summary, xhs_export_stats_csv]
scope: all

SKILL.md 场景指导：

消耗查询时自动汇总各账号消耗及占比
效果分析时计算单次互动成本、转化成本
趋势对比时拉取近 7 天数据做环比
导出报表时使用 export_stats_csv 生成文件
权限规则：员工只看自己账号的订单

Skill 3：xhs-note（笔记与内容）

yaml

name: xhs-note
trigger: 笔记|发布|审核|浏览量|点赞|收藏|评论数|分享|内容|素材
description: 小红书笔记查询——互动数据、发布状态、内容表现
tools: [xhs_list_notes, xhs_get_note_stats]
scope: all

SKILL.md 场景指导：

笔记列表按互动量排序，高亮表现突出的
展示完整互动数据：浏览/点赞/收藏/评论/分享
审核状态异常（rejected）时提示检查
权限规则：员工只看自己账号的笔记

Skill 4：xhs-message（私信与评论）

yaml

name: xhs-message
trigger: 私信|消息|未回复|会话|评论|回复|进线
description: 小红书私信与评论查询——未回复统计、会话历史、评论列表
tools: [xhs_list_conversations, xhs_get_messages, xhs_list_comments]
scope: all

SKILL.md 场景指导：

私信查询优先展示未回复数量和最早未回复时间
消息历史展示摘要而非完整内容（隐私考虑）
评论按时间倒序，含子评论
权限规则：员工只看自己账号的私信和评论

B 层 — Python Tool 清单

所有工具暴露给 AI，通过 tool_use 调用。

公共行为

所有工具共享：
- 根据调用用户的 PersonCard + 飞书组织架构自动应用角色权限过滤
- 老板：全部账号数据
- 部门负责人：本部门 accountGroupId 下的账号
- 员工：自己 feishuUserId 绑定的账号
- 金额自动从分转换为元（保留两位小数）
- 时间戳自动从毫秒转换为可读日期
- 支持分页（page/pageSize 或 cursor/hasMore）
- 返回格式化文本，直接呈现给用户

账号查询工具（3 个）

1. xhs_list_accounts — 获取账号列表

获取用户可见范围内的所有账号。

参数	必填	说明
`group_id`	否	按分组筛选
`status`	否	按状态筛选（`online` / `offline` / `all`），默认 `all`

返回字段：id、昵称、余额、在线状态、离线原因、所属分组、绑定飞书用户

对应客户端接口：LOAD_ACCOUNTS

服务场景：数据查询、主动巡检

2. xhs_get_account_detail — 获取单账号详情

获取指定账号的完整信息。

参数	必填	说明
`account_id`	是	账号 ID

返回字段：Account 全部字段（id、昵称、头像、余额明细、在线状态、浏览器状态、归属人、最后登录时间等）

权限约束：只能查自己可见范围内的账号，否则返回"无权限查看该账号"

对应客户端接口：GET_ACCOUNT_DATA

服务场景：数据查询

3. xhs_get_account_balance — 查询余额明细

查询账号的分类余额。

参数	必填	说明
`account_id`	是	账号 ID

返回字段：总余额、现金余额、赠款余额、薯币余额

对应客户端接口：CHIPS_WALLET_BALANCE

服务场景：数据查询、主动巡检（余额预警）

订单查询工具（4 个）

4. xhs_list_orders — 查询订单列表

查询聚光推广订单，支持多维度筛选。

参数	必填	说明
`account_id`	否	账号 ID，不填则查全部可见账号
`status`	否	订单状态筛选（待支付/审核不通过/推广中/推广终止/已完成/超时取消/已取消）
`date_range`	否	日期范围（`today` / `7d` / `30d` / `month` / 自定义），默认 `today`
`is_proxy`	否	是否代投（`true` / `false` / `all`），默认 `all`
`page`	否	页码，默认 1
`page_size`	否	每页条数，默认 20

返回字段：订单号、创建时间、关联笔记、推广目标、预算、消耗、曝光、阅读、点赞、收藏、评论、关注、主页浏览、私信进线、私信开口、转化成本、状态

对应客户端接口：GET_ACCOUNT_ORDERS

服务场景：数据查询

5. xhs_get_order_stats — 获取推广效果统计

获取指定日期范围的聚合效果数据。

参数	必填	说明
`account_id`	否	账号 ID，不填则查全部可见账号
`start_date`	是	开始日期（如 `2026-03-15`）
`end_date`	是	结束日期（如 `2026-03-21`）

返回字段：日期维度聚合——消耗、曝光、阅读、互动（点赞+收藏+评论）、私信进线、转化成本

对应客户端接口：GET_STATS_BY_DATE

服务场景：数据查询、AI 智能分析

6. xhs_get_cost_summary — 全账号消耗汇总

获取全部可见账号的消耗汇总。

参数	必填	说明
`date_range`	否	日期范围，默认 `today`

返回字段：各账号消耗明细 + 总消耗 + 各账号占比

对应客户端接口：GET_ALL_ACCOUNTS_COST_SUMMARY

服务场景：数据查询、主动巡检

7. xhs_export_stats_csv — 导出统计 CSV

导出订单统计数据为 CSV 文件。

参数	必填	说明
`account_id`	否	账号 ID，不填则导出全部可见账号
`date_range`	否	日期范围，默认 `month`

返回内容：CSV 文件路径

对应客户端接口：EXPORT_STATS_CSV

服务场景：报表导出

笔记查询工具（2 个）

8. xhs_list_notes — 获取笔记列表

获取账号下的笔记列表。

参数	必填	说明
`account_id`	是	账号 ID
`page`	否	页码，默认 1
`page_size`	否	每页条数，默认 20

返回字段：笔记 ID、标题、类型（图文/视频）、状态（published/reviewing/rejected/draft）、浏览量、点赞、收藏、评论、分享、发布时间

对应客户端接口：NOTE_LIST

服务场景：数据查询

9. xhs_get_note_stats — 单篇笔记效果

获取单篇笔记的详细互动数据。

参数	必填	说明
`account_id`	是	账号 ID
`note_id`	是	笔记 ID

返回字段：浏览量、点赞、收藏、评论、分享 + 互动率

对应客户端接口：NOTE_STATS

服务场景：数据查询、AI 智能分析

互动查询工具（3 个）

10. xhs_list_conversations — 获取私信会话列表

获取账号的私信会话列表。

参数	必填	说明
`account_id`	是	账号 ID
`cursor`	否	分页游标

返回字段：会话 ID、对方昵称、最后消息摘要、最后消息时间、未读数、是否已回复、首条未回复时间、线索标记

对应客户端接口：DM_LIST_CONVERSATIONS

服务场景：数据查询

11. xhs_get_messages — 获取消息历史

获取指定会话的消息列表。

参数	必填	说明
`account_id`	是	账号 ID
`session_id`	是	会话 ID

返回字段：消息 ID、内容摘要、消息类型、方向（发送/接收）、发送时间

隐私约束：返回消息摘要（前 50 字），不返回完整内容

对应客户端接口：DM_LIST_MESSAGES

服务场景：数据查询

12. xhs_get_client_logs — 获取操作日志

获取账号的操作日志。

参数	必填	说明
`account_id`	否	账号 ID，不填则查全部可见账号
`log_type`	否	日志类型（`online` / `offline` / `ip_change` / `device_change` / `all`）
`page`	否	页码

返回字段：时间、类型、地理位置、IP 地址、客户端名称

对应客户端接口：GET_CLIENT_LOGS

服务场景：安全审计、主动巡检

C 层 — 系统能力

不暴露给 AI，在 Tool 内部或中间件中自动运行。

能力	说明	状态
权限路由	飞书组织架构 → PersonCard 角色 → 账号可见范围过滤	⬜ 待实现
客户端 API 适配层	HTTP 客户端封装、金额（分→元）和时间戳（ms→日期）转换、错误处理	⬜ 待实现
公司路由	根据用户所属公司路由到对应的客户端后端 API 地址	⬜ 待实现
异常检测引擎	基于近 7 天数据的统计异常检测 + 固定阈值检测	⬜ 待实现
告警路由	异常类型 → 通知对象（员工→部门负责人→老板）逐级升级	⬜ 待实现

客户端 API 适配层

python

class XhsClientAPI:
    """清海与客户端后端 API 的通信适配层"""

    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url  # 客户端后端地址
        self.api_key = api_key    # 认证密钥

    async def call(self, endpoint: str, params: dict) -> dict:
        """统一 HTTP 调用入口"""
        # 1. 发起 HTTP 请求
        # 2. 金额字段自动 / 100 转元
        # 3. 时间戳字段自动转可读日期
        # 4. 错误码转可读消息
        ...

权限过滤中间件

python

def filter_by_permission(user_role: str, user_id: str, accounts: list) -> list:
    """根据角色过滤可见账号"""
    if user_role == "boss":
        return accounts  # 全部
    elif user_role == "department_head":
        dept_groups = get_user_department_groups(user_id)
        return [a for a in accounts if a["accountGroupId"] in dept_groups]
    else:  # employee
        return [a for a in accounts if a["feishuUserId"] == user_id]

D 层 — 主动推送（Concern 引擎）

巡检触发策略

策略	触发条件	频率	优先级
每日投放巡检	每日 20:00	每日一次	高

巡检检查项

每日 20:00 执行：
1. 拉取全部账号状态 → 检查离线账号（离线超过 4 小时告警）
2. 拉取全部账号余额 → 检查低余额（< ¥100 告警）
3. 拉取当日消耗汇总 → 检查消耗异常（偏离近 7 天均值 ±50%）
4. 拉取当日订单效果 → 检查零产出（有消耗但曝光/互动为 0）
5. 拉取操作日志 → 检查异常登录（IP/设备变更）

告警升级机制

推送约束

约束	说明
冷却期	同一账号同一异常类型 24 小时内不重复
时段限制	9:00-21:00
每日上限	单人最多 5 条告警
合并发送	多个低级告警合并为一条消息
工作日优先	非紧急告警仅工作日发送

复用的现有能力

能力	本场景用途	状态
PersonCard	用户身份 + 飞书组织架构角色 → 权限过滤	✅ 复用
飞书组织架构识别	获取用户部门、职级 → 三级权限判定	✅ 复用
Concern 引擎	每日巡检定时触发	✅ 复用，需新增策略
NotificationEngine	告警消息防骚扰（冷却/时段/上限）	✅ 复用
飞书 Bot	告警消息推送	✅ 已实现
TG Bot	告警消息推送（TG 渠道）	✅ 已实现

全局约束

约束	说明
第一期仅只读	不接入任何写入操作（发私信/发笔记/创建订单等）
客户端需在线	查询依赖客户端后端 API 可达，离线时返回友好提示
金额单位	客户端返回分，清海展示元
时间格式	客户端返回毫秒时间戳，清海展示为 `YYYY-MM-DD HH:mm`
Cookie 不经过清海	小红书认证信息仅在客户端内部
私信内容脱敏	仅展示摘要，不暴露完整内容

实现路线

Phase 1：核心查询 + 巡检（MVP）

#	事项	状态
1	客户端 API 适配层（HTTP 客户端 + 数据转换）	⬜
2	权限路由中间件（飞书组织架构 → 账号过滤）	⬜
3	`xhs_list_accounts` + `xhs_get_account_balance`	⬜
4	`xhs_list_orders` + `xhs_get_cost_summary`	⬜
5	`xhs-account` + `xhs-order` SKILL.md	⬜
6	每日巡检策略（账号状态 + 余额 + 消耗异常）	⬜

Phase 2：内容与互动

#	事项	状态
7	`xhs_list_notes` + `xhs_get_note_stats`	⬜
8	`xhs_list_conversations` + `xhs_get_messages` + `xhs_list_comments`	⬜
9	`xhs-note` + `xhs-message` SKILL.md	⬜

Phase 3：分析与报表

#	事项	状态
10	`xhs_get_order_stats`（趋势分析数据）	⬜
11	`xhs_export_stats_csv`（报表导出）	⬜
12	AI 分析 prompt 模板（跨模块关联分析）	⬜

Phase 4（未来）：写入操作

第一期不实现，待验证只读价值后考虑接入 P1 写入操作（发私信/发笔记/创建订单等）。

Skill 清单 ​

架构总览 ​

分层判断标准 ​

Skill / Tool 汇总 ​

A 层 — 4 个 Skill 定义 ​

Skill 1：xhs-account（账号管理） ​

Skill 2：xhs-order（订单与消耗） ​

Skill 3：xhs-note（笔记与内容） ​

Skill 4：xhs-message（私信与评论） ​

B 层 — Python Tool 清单 ​

公共行为 ​

账号查询工具（3 个） ​

1. xhs_list_accounts — 获取账号列表 ​

2. xhs_get_account_detail — 获取单账号详情 ​

3. xhs_get_account_balance — 查询余额明细 ​

订单查询工具（4 个） ​

4. xhs_list_orders — 查询订单列表 ​

5. xhs_get_order_stats — 获取推广效果统计 ​

6. xhs_get_cost_summary — 全账号消耗汇总 ​

7. xhs_export_stats_csv — 导出统计 CSV ​

笔记查询工具（2 个） ​

8. xhs_list_notes — 获取笔记列表 ​

9. xhs_get_note_stats — 单篇笔记效果 ​

互动查询工具（3 个） ​

10. xhs_list_conversations — 获取私信会话列表 ​

11. xhs_get_messages — 获取消息历史 ​

12. xhs_get_client_logs — 获取操作日志 ​

C 层 — 系统能力 ​

客户端 API 适配层 ​

权限过滤中间件 ​

D 层 — 主动推送（Concern 引擎） ​

巡检触发策略 ​

巡检检查项 ​

告警升级机制 ​

推送约束 ​

复用的现有能力 ​

全局约束 ​

实现路线 ​

Phase 1：核心查询 + 巡检（MVP） ​

Phase 2：内容与互动 ​

Phase 3：分析与报表 ​

Phase 4（未来）：写入操作 ​

Skill 清单

架构总览

分层判断标准

Skill / Tool 汇总

A 层 — 4 个 Skill 定义

Skill 1：xhs-account（账号管理）

Skill 2：xhs-order（订单与消耗）

Skill 3：xhs-note（笔记与内容）

Skill 4：xhs-message（私信与评论）

B 层 — Python Tool 清单

公共行为

账号查询工具（3 个）

1. xhs_list_accounts — 获取账号列表

2. xhs_get_account_detail — 获取单账号详情

3. xhs_get_account_balance — 查询余额明细

订单查询工具（4 个）

4. xhs_list_orders — 查询订单列表

5. xhs_get_order_stats — 获取推广效果统计

6. xhs_get_cost_summary — 全账号消耗汇总

7. xhs_export_stats_csv — 导出统计 CSV

笔记查询工具（2 个）

8. xhs_list_notes — 获取笔记列表

9. xhs_get_note_stats — 单篇笔记效果

互动查询工具（3 个）

10. xhs_list_conversations — 获取私信会话列表

11. xhs_get_messages — 获取消息历史

12. xhs_get_client_logs — 获取操作日志

C 层 — 系统能力

客户端 API 适配层

权限过滤中间件

D 层 — 主动推送（Concern 引擎）

巡检触发策略

巡检检查项

告警升级机制

推送约束

复用的现有能力

全局约束

实现路线

Phase 1：核心查询 + 巡检（MVP）

Phase 2：内容与互动

Phase 3：分析与报表

Phase 4（未来）：写入操作