公众号内容诊断

技能文档

---
name: lingyi-wx-account-diagnose
title: 公众号内容诊断
category: 内容创作
description: 给自己的公众号做一次内容体系体检：选题结构分布、更新频率与断更、定位一致性、内容矩阵健康度四项信号灯、内容支柱与缺口、偏弱评分维度与可执行策略建议，可选 HTML 报告。当用户需要诊断公众号、分析账号内容、查看选题分布或评估账号定位时触发。触发词：公众号诊断、账号内容诊断、选题分布、定位分析。
---

# 公众号诊断

把自己的号整体看一遍：选题结构、更新节奏、定位一致性、健康度信号灯、偏弱维度与策略建议。

解析、评分、聚合、归纳、洞察、报告渲染全部在远端服务完成。脚本 `scripts/wx_analyze.py` 负责全部
HTTP 调用，接口说明见 `references/api.md`。你的职责是：确认账号（或收集本地输入）与定位自述、在
交互节点等用户确认、把服务端返回的七区块结论讲给用户听。

**默认不需要用户上传任何文件**：给出公众号名字、确认账号后，全量层与深度层数据都由服务端自动获取。
后台导出表格是可选增强（阅读数精确、含涨粉/来源等私域口径），不是前置条件。

## 技能工作流

### 步骤1：读配置并鉴权

**读配置**（任何命令之前先做）：读技能目录下 `config.json`；文件不存在就把包内 `config.json.example` 复制成 `config.json` 再读（模板里 `BASE_URL` 已是生产地址 `https://service.lingyishuke.com`，一般不用改，只需补 `LY_API_KEY`）。若 `config.json` 里 `BASE_URL` 仍是旧地址 `https://claw.lingyishuke.com/services`，就地改成新地址——域名已迁移，且 `config.json` 优先级高于 `config.json.example`，**升级新包不会自动改它**。
**取 API Key**：读技能目录下 `config.json` 的 `LY_API_KEY`（回退环境变量）。缺失按「鉴权」引导获取写入。`BASE_URL` 同文件配置（生产地址 `https://service.lingyishuke.com`），缺失时脚本退出码 2。
### 步骤2：输入判定

**输入判定**：见「节点 1」。默认路径是账号直连——用户说出公众号名字 → `search` 出候选 → **等用户确认是哪个账号** → 直接发起诊断；全量层数据由服务端自动获取，**不要追问用户要不要上传后台表格**。同一轮顺带问一句定位自述。选中的候选「可直连」为 ✗ 时见「节点 1b」（换关键词重搜 / 用文章链接 `--account-url` 继续），不要就此结束。
### 步骤3：扣点确认

告知「本次账号诊断预计扣 深度层篇数×20 + 30 点（只上传全量层表格、不做深度层时约 30 点），实际扣点以服务端为准」，账号直连模式按 count 计（count×20 + 30），等用户明确同意；`--task-id` 恢复轮询不重复扣点，跳过本步。
### 步骤4：提交与轮询

`account submit`（建任务与轮询一体；深度层评分较慢，进度打在 stderr）。用户主动给了 `--tables` 时，脚本内部走「申请上传票据 → 表格直传对象存储 → 确认落库 → 只提交上传凭证」，已自动处理，命令与用户操作都不变。
### 步骤5：选题归纳

`account groupings`，展示归类表并问是否调整（见「节点 2」）。
### 步骤6：洞察结论

`account insights`，七区块一次性输出（见「节点 3」）。
### 步骤7：报告与收尾

**报告**：固定问「要生成包含选题分布/产量表现四象限/7 维低分占比/发文间隔时间轴的 HTML 报告吗？」，确认后 `account report`。
**收尾**：告知实际扣点（`WX_ANALYZE_POINTS_USED`）与报告路径。

## 脚本定位

后文命令里的 `"$SKILL"` 指本技能的安装目录，命令均以该目录为工作起点（如 `python3 "$SKILL/scripts/wx_analyze.py" ...`）。无法定位技能安装目录时，如实告诉用户并停止。
绝对禁止：猜路径、自行重写脚本逻辑、绕过脚本直接拼 HTTP 请求。
`config.json` 固定读技能目录，报告默认写到当前工作目录。
`config.json` 固定读技能目录，报告默认写到当前工作目录。

## 鉴权

API Key 取技能目录下 `config.json` 的 `LY_API_KEY` 字段，回退环境变量 `LY_API_KEY`。
脚本请求头使用 `Authorization: <api_key>`，裸 key，不带 Bearer。`config.json` 形如：

```json
{ "LY_API_KEY": "你的密钥", "BASE_URL": "https://service.lingyishuke.com" }
```

1. **检查是否已有 key。** 读 `config.json`；没有则看环境变量。任一有值即视为就绪。
2. **缺失则引导用户获取。** 提示用户前往 https://claw.lingyishuke.com/webapps/01claw-auth/index.html 获取 API Key 并发给你。拿到前不要运行脚本。
3. **记录用户发来的 key。** 写入 `config.json` 的 `LY_API_KEY` 字段（保留其它内容），该文件已被 `.gitignore` 忽略。
4. **鉴权失败（退出码 3）时。** 引导用户重新获取并覆盖写入，不要反复用失效 key 重跑。

SSL 证书错误（`CERTIFICATE_VERIFY_FAILED` 等）可设 `LY_SKIP_SSL_VERIFY=1` 后重试，仅限受控环境临时使用。

---

## 工作流详解 · 交互节点

### 节点 1 · 输入判定与定位询问

**全量层数据有两个来源，客户端不需要为此追问用户**：账号直连模式下，服务端自动获取最近 N 篇的阅读/在看/分享/收藏/评论指标，组装成与后台导出表格等价的数据喂给同一套分析；用户主动提供表格时**以表格为准**（后台导出是精确值，还含涨粉、流量来源等公开接口拿不到的私域口径）。所以只给公众号名字也能拿到完整诊断（全量层 + 深度层）。

支持的输入组合（**至少提供一项**）：

1. **账号直连（默认路径）**：用户说出自己公众号的名字，先搜索候选账号：

   ```bash
   python3 "$SKILL/scripts/wx_analyze.py" search --keyword "公众号名字" [--page 1]
   ```

   把 stderr 里的候选表转成 Markdown 表格完整展示给用户（列：序号/名称/主体/类型/粉丝/周更/均阅/**可直连**/ghid，**「可直连」列不得省略**），**【交互节点】必须等用户确认是哪个账号**——即使只有一个候选也不得擅自代选。退出码 7（无结果）时请用户换关键词或改用本地文章。

   **某个候选能不能直接用，判据只有「可直连」列一个**（服务端字段 `direct_available`）：✓ 就取 `ghid` 与 `name`。`ghid` 形如 `wxid_...` 而不是 `gh_...` **是正常可用的**，不得因为前缀不对就自行判为不可用；✗ 时走「节点 1b」，不要就此结束。

   篇数默认 10（可指定 1-20），**直接发起诊断**：服务端按这 N 篇同时组装全量层指标与深度层评分语料，用户不需要上传任何文件。**确认账号之后不要再问"要不要上传后台表格"**——表格是可选增强，讲结论时提一句即可（见节点 3）。
2. **后台导出表格（可选增强，不主动追问）**：用户手上已有 `.xlsx`/`.csv` 导出、或自己明确说要上传时才收，走 `--tables`（单个或多个）。可与账号直连并存，并存时全量层以表格为准。
3. **本地历史文章（可选，与账号直连互斥）**：一个本地历史文章文件夹（Glob **仅顶层、不递归**扫描 `*.md`、`*.txt`、`*.docx`；检测到子目录提示"如需分析其中文章请单独指定该子目录路径再跑一批"）。适用于搜不到该号、号已改名、或用户只想分析手头草稿的场景。

**账号直连与本地文章（`--files`）互斥，深度层来源二选一；表格（`--tables`）与两者都可并存。**

### 节点 1b · 候选不可直连时的降级（两条出路，效果等价）

用户选中的候选「可直连」是 ✗，或整页候选全是 ✗（脚本会在 stderr 追加提示）时——**这不是死路，绝不允许回一句"账号直连不可行"就结束本轮**。✗ 只说明上游账号记录残缺（缺 ghid），与这个号本身能不能诊断无关。把下面两条出路**一起**摆给用户，请他选一条：

1. **换更具体的关键词重搜**：把关键词补完整再跑一次 `search`（例如「深圳地铁」→「深圳地铁运营」），换到一个「可直连」为 ✓ 的候选，然后照原流程用 `--account-ghid` 提交。
2. **请用户发一篇自己号的文章链接**：话术形如「这个号的记录里缺直连标识，你把它**任意一篇**推文的链接发我就行，效果一样」。拿到链接后改用 `--account-url` 提交，服务端据此反查账号并拉取同样的历史文章：

   ```bash
   python3 "$SKILL/scripts/wx_analyze.py" account submit --account-url 'https://mp.weixin.qq.com/s/xxxx' \
     --account-name '我的公众号名' --count 10 --positioning "写给一线运营的实操方法"
   ```

**两条出路产出完全一致**——都是服务端拉该号最近 N 篇，同时组装全量层指标与深度层评分语料，扣点口径也相同。不要把 `--account-url` 说成"降级方案"或"效果打折"，它只是换了个找到这个号的入口，更不要因此改口要求用户上传后台表格。`--account-ghid` 与 `--account-url` **二选一，同时给出脚本直接退 2**；链接必须是 mp.weixin.qq.com 域名。`--account-url` 与 `--files` 同样互斥，与 `--tables` 同样可并存。

同时确定：

- **账号标识**（`--label`）：账号直连模式下脚本缺省用 `--account-name` 充当，不必额外问用户；本地文章/表格路径下由用户显式指定，或从文件夹名/表格文件名取一个简短标识。同一用户管理多个账号时，建议显式指定互不相同的标识。
- **定位自述（可选）**：同一轮询问用户"这个号的定位/目标读者是什么？"。用户未答时**不阻断流程**，不传 `--positioning`，服务端会降级为纯反推描述。

三者均未提供时，明确告知"请至少告诉我你的公众号名字，或提供历史文章文件夹 / 后台导出表格"并结束本轮。

**意图边界**：本技能只做「自己的账号」的整体诊断。用户想拆解**别人的**对标账号/文章，或只想批量评分一批文章、不做账号级聚合与定位分析时，改用相应的内容分析技能，不要硬套本流程。

```bash
# 默认路径：账号直连（ghid/name 来自 search 结果、且已经用户确认；「可直连」为 ✓）
# 不带 --tables 也能出完整诊断：全量层指标由服务端自动获取
python3 "$SKILL/scripts/wx_analyze.py" account submit --account-ghid 'gh_xxxx' --account-name '我的公众号名' \
  --count 10 --positioning "写给一线运营的实操方法"

# 账号直连兜底（候选不可直连，用户给了该号任意一篇文章链接；与 --account-ghid 二选一，与 --files 互斥）
python3 "$SKILL/scripts/wx_analyze.py" account submit --account-url 'https://mp.weixin.qq.com/s/xxxx' \
  --account-name '我的公众号名' --count 10 --positioning "写给一线运营的实操方法"

# 用户自己拿出了后台导出表格时（可选增强，与账号直连并存，全量层以表格为准）
python3 "$SKILL/scripts/wx_analyze.py" account submit --account-ghid 'gh_xxxx' --account-name '我的公众号名' \
  --count 10 --tables '导出.xlsx' --positioning "写给一线运营的实操方法"

# 本地历史文章路径（与 --account-ghid 互斥）
python3 "$SKILL/scripts/wx_analyze.py" account submit --label "我的号" \
  --tables '导出.xlsx' --files '文章A.md' '文章B.docx' ... \
  --positioning "写给一线运营的实操方法"
```

带 `--tables` 时脚本会逐个表格在 stderr 打一行上传进度（`· 上传 导出.xlsx (123 KB) → 已确认`），这是脚本内部的上传流程，
不需要用户做任何额外操作，也不必转述给用户。

深度层评分较慢（默认 `--max-wait 1200` 秒）；超时（退出码 124）用 `account status --task-id <id>` 恢复轮询，不重复扣点。

### 节点 2 · 选题归纳与调整

```bash
python3 "$SKILL/scripts/wx_analyze.py" account groupings --task-id <id>
```

服务端归纳 3-8 个选题类型；同账号已有类目时只为新文章补标签、不新增类目——此时向用户说明"沿用已有的 {N} 个选题类目"。用一张 Markdown 表格（列：选题类型 / 篇数）展示归类结果，询问"以上选题归类是否需要调整？"

- 用户提出修正：写调整 JSON（`{"topics": [...], "article_tags": [...]}`），执行 `account groupings --task-id <id> --adjust 调整.json`（PUT 覆盖）。
- 确认或无异议：直接进入下一步。归类表格必须完整展示过一次，不得省略。

### 节点 3 · 洞察结论（七区块，一次性产出）

```bash
python3 "$SKILL/scripts/wx_analyze.py" account insights --task-id <id>
```

读结果 JSON，在**同一次响应**中按固定顺序输出全部七个区块：

1. **概览行**：`全量层 {N} 篇（选题分布/发文频率）· 深度层 {M} 篇（维度评分聚合）`——两层样本量**分别标注**，不得让读者误以为全部结论同一样本量。账号直连模式下两层可能来自同一批文章、篇数相同，照服务端返回值展示即可。
   **阅读数封顶提示必须如实转述**：微信对超过 10 万的阅读数只给封顶值 `100001`。洞察结果 JSON 的 **`account_stats.table_layer_note`** 就是服务端生成好的中文口径提示原句（形如「全量层 N 篇中有 M 篇阅读数为微信「10万+」封顶值（100001）…」）。该字段**非空就原样并入概览行讲给用户**——不要自己拼措辞、不要改写里面的数字、不要只讲一半；为 `null`（表格来源或没有封顶篇目）时**什么都不加**，不要自造一句提示。绝不把 `100001` 当成精确阅读量，也不得据此推算真实阅读量或倍数。
2. **选题分布表 + 发文间隔**：选题分布表（列：选题类型 / 篇数 / 占比）；发文间隔一行（中位数/离散度）+ 断更期列表（逐字复用"{start}~{end} 断更 {weeks} 周"式措辞）。服务端标记样本不足时，原样展示其原因说明，不强行给中位数。
3. **定位一致性 + 内容支柱/缺口**：一行对照反推定位 vs 自述定位 + 一致性说明（用户未提供定位时按服务端返回说明"仅为反推描述"）；紧接内容支柱/伪支柱/机会缺口列表；服务端标记仅产量口径时显式提示"缺表现数据，仅产量口径"。
4. **健康度信号灯一行**：4 个分项指标各自的数值 + 红/黄/绿灯，格式参考"选题集中度 62% 🟡 · 定位一致率 74% 🟢 · 支柱依赖度 45% 🟢 · 断更占比 18% 🔴"——**只展示 4 项独立指标，不合并计算、不输出任何跨指标汇总分数**。
5. **偏弱维度表**：每个偏弱维度一行（如"标题钩子：62% 篇目落在低分段（25/40 篇）"）+ 2-3 篇典型案例，案例的 `evidence`/`next_tier_gap` **直接逐字引用原文**——禁止改写措辞、禁止重新生成新的点评文本。
6. **等级分布行**：一行文字，格式参考"40 篇：S 2 / A 9 / B 21 / C 8，中位数 B"——**不输出账号平均总分**。
7. **策略建议**：逐条展示 `strategy_suggestions` 的 `conclusion`/`evidence`/`action` 三段式，编号列表呈现，逐字引用不改写。

**用户展示规则（覆盖“逐字引用”的技术字段部分）：** 数字和结论不得改动，但必须隐藏内部实现名。不要向用户输出 `application_cases`、`content_pillars.topics...`、`avg_reads_vs_baseline_ratio`、`opening_retention`、`null` 等 topic key/字段路径；使用服务端返回的中文选题标签和维度标签。“基线”说成“账号近期平均水平”，“机会缺口”解释成“发得少、表现很好，值得加码”，“伪支柱”解释成“发得多、效果偏弱，需要优化”。例如不要说“新品发布（product_launch）是基线 2.67 倍（avg_reads...）”，应说“新品发布只发了 1 篇，但平均阅读达到账号近期平均水平的 2.67 倍，属于少但表现好的潜力选题”。

**七区块之后补一句数据来源说明**：本轮全量层来自服务端自动获取（用户没上传表格）时，固定补一句——「以上全量层指标由服务端自动获取；如果你手上有公众号后台导出的数据表格，上传后能得到更精确的阅读数，还能多出涨粉、流量来源这些公开接口拿不到的维度」。用户本轮已经上传过表格时不必再说。

### 节点 4 · HTML 报告（每次都问）

七区块之后固定问："要生成包含选题分布/产量表现四象限/7 维低分占比/发文间隔时间轴的 HTML 报告吗？"——不默认生成；回答"不要"直接结束，不追问第二次。确认后：

```bash
python3 "$SKILL/scripts/wx_analyze.py" account report --task-id <id> [--out 目录或文件]
```

报告为服务端渲染的单文件自包含 HTML，断网可打开，区块与对话结论七段式一一对应。

## 结果讲解边界

- 只讲产物字段：统计数字与业务结论以服务端返回为准；内部 key/字段路径按“用户展示规则”隐藏并改用中文白话表达。
- 涉及评分维度时只说："7 个维度加权、每维证据定档、总分由服务端计算，evidence 与升档差距就是可直接复述的归因。"不展开权重数值与评分方法论细节。
- 诊断结论只基于用户自己的数据，不引入外部行业基准或行业内容矩阵模板。

## 输出交付

成功时 stdout 形如：

```
WX_ANALYZE_TASK_ID=<任务 ID>
WX_ANALYZE_POINTS_USED=<本次实际扣点，可能为空>
WX_ANALYZE_REPORT_FILE=<报告文件绝对路径>
=== WX_ANALYZE_RESULT_START ===
<结构化结果 JSON>
=== WX_ANALYZE_RESULT_END ===
```

1. **讲结论**：按节点顺序讲，不把 JSON 原样丢给用户。
2. **告知实际扣点**：`WX_ANALYZE_POINTS_USED` 非空时说「本次任务实际扣除 {点数} 点」；为空时说「本次约扣 深度层篇数×20 + 30 点（实际以服务端为准，可在服务账户页查看）」。
3. **告知报告查看方式**：路径见 `WX_ANALYZE_REPORT_FILE`，可直接双击打开。

## 退出码处理

| 码 | 含义 | 处理 |
|---|---|---|
| 0 | 成功 | 按「输出交付」处理。 |
| 2 | 输入/配置错误 | 各层输入均缺失、`--account-ghid`/`--account-url` 与 `--files` 同时给出、`--account-ghid` 与 `--account-url` 同时给出、`--account-url` 不是 mp.weixin.qq.com 链接、count 超出 1-20、文件缺失或为空、调整 JSON 非法、未配置 BASE_URL。改正后重试，不扣点。 |
| 3 | 缺 key 或鉴权失败 | 按「鉴权」流程引导用户获取新 key 写入 `config.json` 再重试。不扣点。 |
| 4 | 发起失败，含点数不足 | 展示服务端 message；点数不足时引导用户前往 https://claw.lingyishuke.com/webapps/01claw-auth/index.html 充值。不扣点。 |
| 5 | 服务端把任务判为失败 | 转述 stderr 里的 `error_message`（如表格不达最低门槛、跳步调用）。 |
| 6 | 网络 / 限流 / 服务不可用（含 `--tables` 直传失败） | 告知网络原因失败，附 stderr 信息，询问是否重试。上传阶段失败时任务尚未发起，不扣点，重跑同一条 `submit` 即可。 |
| 7 | 完成但结果为空 | 没有可用的文章或数据行，建议核对输入后重新提交；`search` 返回 7 表示没搜到该公众号，请用户换关键词或改用本地文章。 |
| 124 | 轮询超时 | 深度层评分可能仍在进行，附 task_id，用 `account status --task-id <id>` 恢复轮询，不重复扣点。 |

未知状态不要自行判定失败；脚本会原样透出服务端状态，继续按轮询结果处理。

## 硬性要求

1. **不得编造或改动任何分数与统计数字。** 占比、中位数、信号灯、等级分布全部来自服务端返回。
2. **报告一律来自服务端渲染。** 唯一合法产出方式是 `account report`；绝不自行用 Write 手写 HTML/CSS/图表。
3. **不跳过交互节点。** 扣点未确认不提交；归类表格必须完整展示过一次；报告每次都问。
4. **健康度 4 灯不合并**；等级分布不出平均总分；偏弱维度案例逐字引用。
5. **评分解释只用固定话术**，不展开维度权重与方法论细节；不引入外部行业基准。
6. **账号搜索结果必须展示给用户确认后才能发起分析，绝不擅自选第一个。** 候选表未经用户明确指认哪个账号，不得运行 `account submit --account-ghid`。
7. **不把上传表格说成前置条件。** 账号确认后直接发起诊断，不追问要不要上传表格；表格只在讲完结论时作为可选增强提一句。
8. **阅读数封顶如实转述。** `account_stats.table_layer_note` 非空时**原样逐字讲出**（不改写、不重算里面的数字），为 `null` 时不自造提示；绝不把封顶值 `100001` 当作精确阅读量，也不据此推算真实数值。
9. **候选不可直连不等于诊断不了。** 「可直连」为 ✗ 时按「节点 1b」给出两条出路（换更具体关键词重搜 / 用 `--account-url` 提交文章链接），禁止只回一句"账号直连不可行"就结束，也不得借机把上传后台表格说成前置条件。判断可用性**只看「可直连」列**，`wxid_` 开头的 ghid 同样正常可用。
10. **面向用户不暴露内部字段名。** topic key、JSON 字段路径和 `null` 只用于程序内部；聊天结论与 HTML 报告一律使用中文标签和白话解释。

使用说明

# 公众号内容诊断

给自己的公众号做一次内容体系体检：选题分布、更新节奏、定位一致性、健康度信号灯、偏弱维度与可执行策略建议，可选 HTML 报告。

## 使用

对助手说：

```text
诊断一下我的公众号：XX运营笔记
```

首次使用需在 `config.json` 填入 `LY_API_KEY`（获取入口见 SKILL.md，付费服务）。只需说出公众号名字即可完成诊断；后台导出表格是可选增强。

## 工作原理

脚本把账号搜索、数据获取、评分与聚合全部交给远端服务：`search` 确认账号后，服务端自动拉取最近 N 篇文章组装全量层指标与深度层七维评分，输出选题分布、发文间隔、定位一致性、四项健康度信号灯、偏弱维度典型案例与三段式策略建议，并可渲染单文件 HTML 报告。交互中的人为确认节点（选账号、扣点、报告）不可跳过。

## 目录结构

- `SKILL.md`：执行流程、交互节点与硬性要求
- `scripts/wx_analyze.py`：全部接口调用脚本
- `references/api.md`：接口参考
- `config.json.example`：配置模板（复制为 `config.json` 后填入密钥）

## 依赖

- `python3`，需联网访问诊断服务（按点计费，需密钥）

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。