微信公众号媒体助手 (WeChat Official Account Media Assistant)
Goal
通过 ServiceHub 提供的微信公众号后端接口，面向自媒体运营与图文内容分析场景，提供统一的对话式数据获取与深度分析能力：
- 博主文章列表 (
blogger)：抓取公众号名下发布的历史或最新图文列表，支持直接传入任一文章链接自动反解公众号ghid，支持start_date日期游标跳转与多页翻页。 - 文章正文详情 (
detail)：提取单篇图文的完整清洗正文（纯文本full_text）、富文本源码（HTMLraw_content）、智能摘要summary、字数统计word_count，自动规范长短链接映射。 - 文章互动数据 (
data/stats)：查询文章核心运营互动指标，包括阅读量 (readnum)、点赞数 (likenum)、在看数 (oldlikenum)、评论数 (comment_count)、收藏数 (collect_num)、分享数 (share_num)。 - 精选评论与回复 (
comments/replies)：抓取公众号作者精选上墙的一级读者评论列表，以及指定评论下的二级互动回复。
Required Inputs
运行本技能前应具备：
- ServiceHub 账户凭证：用户名 (
username) 与密码/通行令牌 (passtoken)。 - 目标公众号或文章标识：
- 微信公众号文章链接（短链https://mp.weixin.qq.com/s/xxxx或长链https://mp.weixin.qq.com/s?__biz=...）；
- 或公众号原始 ID (ghid，如gh_9d5db559be6e)；
- 或评论相关标识（comment_id、content_id）。
> 🔑 账号注册与凭证获取：
> 本技能基于 ServiceHub 数据接口运行。若您尚未拥有账号，请前往官网 https://www.ccailab.top 注册并获取您的用户名与密码（或 passtoken）。
ServiceHub 服务地址固定为：
https://www.ccailab.top
凭证优先级与智能记忆
- 命令行参数：
--username,--password - 专属环境变量：
WECHAT_MEDIA_ASSISTANT_USERNAME,WECHAT_MEDIA_ASSISTANT_PASSWORD - 共享环境变量：
SERVICEHUB_USERNAME,SERVICEHUB_PASSWORD,SERVICEHUB_PASSTOKEN - 本地回退凭证文件：
data/credentials.json
> 💡 智能记忆机制：用户在对话中首次提供账号密码后，脚本自动持久化至本地忽略的 data/credentials.json，后续调用自动复用，不再重复追问。
Workflow
- 如需确认详细接口字段与数据结构，先读取 api_spec.md。
- 从用户自然语言中识别任务意图并映射到具体子命令：
-blogger：抓取公众号博主文章列表
-detail：抓取单篇文章正文内容与详情
-data(或stats)：抓取文章阅读/点赞/在看/评论等互动数据
-comments：抓取文章一级精选评论列表
-replies：抓取指定评论的二级互动回复 - 检查关键参数：若缺少核心标识（如文章链接或 ghid），主动进行针对性追问。
- 确定数据处理模式：默认使用
--type extract（查库模式，0 积分）；当且仅当用户明确要求“更新/最新/刷新/抓取最新发布”时使用--type update。 - 运行底层脚本执行请求：
bash python scripts/wechat_media_tool.py <subcommand> [options] - 解析脚本返回的 JSON 结构，提取
data.items、bonus_points_balance、recent_deducted_points、trade_order_id，并向用户呈现结构化表格、排版文案或分析总结。
Decision Rules
1. 意图与子命令识别规则
- 博主文章列表：用户提及“公众号最近发了什么”、“公众号历史文章”、“这个号的所有文章”、“帮我抓这个号的文章列表”：
- 提取文章链接（或 ghid），映射为
blogger； - 若用户提到时间范围（例如“2026年5月之前的文章”），自动转换为
--start-date YYYYMMDD。 - 文章详情/正文：用户提及“提取这篇文章的正文”、“获取微信文章全文”、“文章讲了什么”、“文章排版内容”：
- 映射为
detail。 - 互动数据与指标：用户提及“这篇文章阅读量多少”、“点赞在看数据”、“互动数据监控”、“复盘这篇文章数据”：
- 映射为
data(或stats)。 - 精选评论区：用户提及“评论区精选了哪些”、“读者怎么评价”、“文章评论”：
- 映射为
comments。 - 评论二级回复：用户提及“这条评论有谁回复”、“作者回复了什么”：
- 映射为
replies（需具备comment_id与content_id）。
2. 缺参处理与追问规则
- 缺少文章 URL 且未提供 ghid 时：明确提示用户提供微信公众号文章链接（长短链均可，例如
https://mp.weixin.qq.com/s/...）。 - 首次使用且未检测到环境变量或本地凭证时：礼貌询问 ServiceHub 账号密码。
3. 计费与模式确认规则
- 默认一律执行
--type extract，无需每次向用户确认扣费。 - 当用户要求
--type update时，在调用前可简要告知调用上游将消耗积分，执行后在输出中明确展示本次扣除积分与当前余额。
Output Requirements
向用户输出时应遵循结构清晰、专业自媒体视角的格式：
- 博主文章列表输出：
- 输出公众号名称/ghid、本次获取文章数、起始日期游标；
- 采用 Markdown 表格展示：序号 | 文章标题 | 发布时间 | 阅读量 | 点赞数 | 在看数 | 链接。 - 文章详情输出：
- 展示文章标题、作者、发布时间、字数；
- 正文内容按段落整洁呈现，保留层次感；
- 若用户要求摘要，突出重点核心洞察。 - 互动数据输出：
- 核心指标卡片：阅读量、点赞数、在看数、收藏数、分享数、评论数；
- 互动转化率计算（例如 点赞率 = 点赞/阅读，在看率 = 在看/阅读）。 - 评论列表输出：
- 列表展示：用户昵称 (IP属地) | 点赞数 | 回复数 | 评论内容；
- 如有作者置顶或高赞评论，进行重点标识。 - 审计底栏：在回答末尾附带单行元数据：
> 📊 交易单号: {trade_order_id} | 本次消耗积分: {recent_deducted_points} | 当前余额: {bonus_points_balance}
Validation
在返回结果给用户前，执行以下自检：
1. 验证 JSON 响应中 code == 200 且 data.items 存在。
2. 若 extract 模式返回为空（本地未缓存过该文章或博主），友好建议用户执行一次 update 更新拉取。
3. 检查文章阅读量、在看数等关键字段是否成功映射，避免输出 null 或未解析字段。
Fallback
- 401 Unauthorized：提示用户账号密码无效，并提供重新配置指引。
- 402 Payment Required：提示用户当前 ServiceHub 积分不足，建议在平台充值或使用
extract缓存提取模式。 - 404 Not Found：提示该文章/公众号在本地数据库中尚未建档，引导用户允许使用
--type update在线抓取。 - 502 / 上游网络异常：自动提示稍后重试，或检查微信文章链接是否在微信客户端内已被作者删除。
Examples
示例 1: 通过单篇文章链接获取公众号文章列表 (读库模式)
python scripts/wechat_media_tool.py blogger --url "https://mp.weixin.qq.com/s/sample_article_code" --turns 1 --type extract
示例 2: 在线更新并抓取公众号指定日期前的历史文章
python scripts/wechat_media_tool.py blogger --url "https://mp.weixin.qq.com/s/sample_article_code" --turns 2 --start-date 20260518 --type update
示例 3: 提取单篇微信图文正文与清洗文本
python scripts/wechat_media_tool.py detail --url "https://mp.weixin.qq.com/s/sample_article_code" --type extract
示例 4: 查询文章最新阅读量、在看数与互动数据 (更新模式)
python scripts/wechat_media_tool.py data --url "https://mp.weixin.qq.com/s/sample_article_code" --type update
示例 5: 抓取文章作者精选评论列表
python scripts/wechat_media_tool.py comments --url "https://mp.weixin.qq.com/s/sample_article_code" --turns 1 --type extract
