公众号诊断

概述

版本：v0.2.0· 作者：零一数科

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

解析、评分、聚合、归纳、洞察、报告渲染全部在远端服务完成。脚本 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，升级新包不会自动改它。
2. 取 API Key：读技能目录下 config.json 的 LY_API_KEY（回退环境变量）。缺失按「鉴权」引导获取写入。BASE_URL 同文件配置（生产地址 https://service.lingyishuke.com），缺失时脚本退出码 2。
3. 输入判定：见「节点 1」。默认路径是账号直连——用户说出公众号名字 → search 出候选 → 等用户确认是哪个账号 → 直接发起诊断；全量层数据由服务端自动获取，不要追问用户要不要上传后台表格。同一轮顺带问一句定位自述。选中的候选「可直连」为 ✗ 时见「节点 1b」（换关键词重搜 / 用文章链接 --account-url 继续），不要就此结束。
4. 扣点确认：告知「本次账号诊断预计扣 深度层篇数×20 + 30 点（只上传全量层表格、不做深度层时约 30 点），实际扣点以服务端为准」，账号直连模式按 count 计（count×20 + 30），等用户明确同意；--task-id 恢复轮询不重复扣点，跳过本步。
5. 提交 + 轮询：account submit（建任务与轮询一体；深度层评分较慢，进度打在 stderr）。用户主动给了 --tables 时，脚本内部走「申请上传票据 → 表格直传对象存储 → 确认落库 → 只提交上传凭证」，已自动处理，命令与用户操作都不变。
6. 选题归纳：account groupings，展示归类表并问是否调整（见「节点 2」）。
7. 洞察结论：account insights，七区块一次性输出（见「节点 3」）。
8. 报告：固定问「要生成包含选题分布/产量表现四象限/7 维低分占比/发文间隔时间轴的 HTML 报告吗？」，确认后 account report。
9. 收尾：告知实际扣点（WX_ANALYZE_POINTS_USED）与报告路径。

脚本定位（任何命令之前先做这一步）

后文命令里的 "$SKILL" 指本技能的安装目录。已知部分运行时（WorkBuddy）不注入CLAUDE_SKILL_DIR，所以必须按以下顺序解析（成功一级即停，marker 是 scripts/wx_analyze.py）：

SN=wx-account-diagnose
SKILL=""
if [ -n "$CLAUDE_SKILL_DIR" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/wx_analyze.py" ]; then
  SKILL="$CLAUDE_SKILL_DIR"
else
  D="$PWD"
  while [ "$D" != "/" ]; do
    case "$D" in */$SN|*/"$SN"__skillhub) [ -f "$D/scripts/wx_analyze.py" ] && { SKILL="$D"; break; };; esac
    D=$(dirname "$D")
  done
  if [ -z "$SKILL" ]; then
    SKILL=$(find "$HOME/.claude" "$HOME/.codebuddy" "$HOME/.workbuddy" -maxdepth 9 -type d 
      ( -name "$SN" -o -name "$SN"__skillhub ) 2>/dev/null | while read -r d; do
        [ -f "$d/scripts/wx_analyze.py" ] && echo "$d"; done | head -1)
  fi
fi
[ -n "$SKILL" ] && echo "SKILL=$SKILL" || echo "SKILL_DIR_UNRESOLVED"

打印 SKILL_DIR_UNRESOLVED 时：如实告诉用户无法定位技能安装目录并停止。绝对禁止：猜路径、自行重写脚本逻辑、绕过脚本直接拼 HTTP 请求。config.json 固定读技能目录，报告默认写到当前工作目录。

鉴权

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

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

1. 检查是否已有 key。 读 config.json；没有则看环境变量。任一有值即视为就绪。
2. 缺失则引导用户获取。 提示用户前往 https://claw.lingyishuke.com/webapps/01claw-auth/index.html?source=workbuddy 获取 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. 账号直连（默认路径）：用户说出自己公众号的名字，先搜索候选账号：

   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）。

1. 后台导出表格（可选增强，不主动追问）：用户手上已有 .xlsx/.csv 导出、或自己明确说要上传时才收，走 --tables（单个或多个）。可与账号直连并存，并存时全量层以表格为准。
2. 本地历史文章（可选，与账号直连互斥）：一个本地历史文章文件夹（Glob 仅顶层、不递归扫描 *.md、*.txt、*.docx；检测到子目录提示"如需分析其中文章请单独指定该子目录路径再跑一批"）。适用于搜不到该号、号已改名、或用户只想分析手头草稿的场景。

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

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

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

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

   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，服务端会降级为纯反推描述。

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

意图边界（靠意图区分，不靠输入形态）：用户想拆解别人的对标账号/文章 → wx-competitor-teardown；只想批量评分一批文章、不做账号级聚合与定位分析 → wx-batch-analyze。

# 默认路径：账号直连（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 · 选题归纳与调整

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 · 洞察结论（七区块，一次性产出）

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 当成精确阅读量，也不得据此推算真实阅读量或倍数。

1. 选题分布表 + 发文间隔：选题分布表（列：选题类型 / 篇数 / 占比）；发文间隔一行（中位数/离散度）+ 断更期列表（逐字复用"{start}~{end} 断更 {weeks} 周"式措辞）。服务端标记样本不足时，原样展示其原因说明，不强行给中位数。
2. 定位一致性 + 内容支柱/缺口：一行对照反推定位 vs 自述定位 + 一致性说明（用户未提供定位时按服务端返回说明"仅为反推描述"）；紧接内容支柱/伪支柱/机会缺口列表；服务端标记仅产量口径时显式提示"缺表现数据，仅产量口径"。
3. 健康度信号灯一行：4 个分项指标各自的数值 + 红/黄/绿灯，格式参考"选题集中度 62% 🟡 · 定位一致率 74% 🟢 · 支柱依赖度 45% 🟢 · 断更占比 18% 🔴"——只展示 4 项独立指标，不合并计算、不输出任何跨指标汇总分数。
4. 偏弱维度表：每个偏弱维度一行（如"标题钩子：62% 篇目落在低分段（25/40 篇）"）+ 2-3 篇典型案例，案例的 evidence/next_tier_gap 直接逐字引用原文——禁止改写措辞、禁止重新生成新的点评文本。
5. 等级分布行：一行文字，格式参考"40 篇：S 2 / A 9 / B 21 / C 8，中位数 B"——不输出账号平均总分。
6. 策略建议：逐条展示 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 报告吗？"——不默认生成；回答"不要"直接结束，不追问第二次。确认后：

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 点（实际以服务端为准，可在 01Claw 账户查看）」。
3. 告知报告查看方式：路径见 WX_ANALYZE_REPORT_FILE，可直接双击打开。

退出码处理

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

硬性要求

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 报告一律使用中文标签和白话解释。