公众号爆款预测+优化建议

概述

版本：v1.1.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 也在该文件配置（地址见部署说明），缺失时脚本会以退出码 2 报错提示。
3. 输入落盘：粘贴文本先写成本地文件；本地 md/txt/docx 直接记路径（docx 的文本抽取由脚本自行完成，无需任何额外依赖）；公众号链接不落盘、直接 --url 提交（优先走服务端抓取，绝不自行访问链接或让用户粘贴）。
4. 扣点确认：首次执行（非 --task-id 恢复）时，运行脚本前告诉用户「本次单篇评分预计扣 20 点，实际扣点以服务端为准」，等用户明确同意后再继续；用户未确认不要运行脚本。恢复轮询不重复扣点，跳过本步。
5. 提交 + 轮询：score submit（建任务与轮询一体，自动跑到终态）。
6. 讲结论：评分表格、诊断、改写建议在同一次响应中一并输出，不分多轮。
7. 每次都问报告：固定问「要生成 HTML 报告吗？」，确认后 score report。
8. 收尾：告知实际扣点（WX_ANALYZE_POINTS_USED）与报告路径。

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

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

SN=wx-article-score
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 取技能目录（SKILL.md 所在目录）下 config.json 的 LY_API_KEY 字段，回退环境变量 LY_API_KEY。脚本请求头使用 Authorization: <api_key>，裸 key，不带 Bearer。config.json 形如：

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

运行脚本前先确认 key 就绪。任何时候都不要编造或猜测 key。

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

若报 SSL 证书错误（CERTIFICATE_VERIFY_FAILED 等，常见于 macOS 缺证书或企业代理），可设LY_SKIP_SSL_VERIFY=1 后重试。注意：跳过证书校验有中间人风险，仅在受控环境临时使用。

工作流 · 交互节点

节点 1 · 输入与扣点确认

两种输入方式，收敛到同一条提交命令：

• 粘贴文本：用 Write 把正文原样写入 ./.wx-analyze/pasted-input.md（纯正文、每次覆盖），然后 --text-file 提交（--source 默认 pasted_text），标题用 --title 单独传。
• 公众号链接：--url 直接提交，正文由服务端经数据源（JustOneAPI）抓取——不要自己打开链接、不要要求用户粘贴正文；只有服务端返回抓取失败（fetch.failed/unreachable）时才引导用户改用粘贴方式重新提交。
• 本地文件：.md/.txt/.docx 路径直接 --file 提交（--source 默认 local_file）。正文只在磁盘与服务端之间传递，不经模型转写。

python3 "$SKILL/scripts/wx_analyze.py" score submit --text-file ./.wx-analyze/pasted-input.md --title "文章标题"
python3 "$SKILL/scripts/wx_analyze.py" score submit --file 草稿.docx
python3 "$SKILL/scripts/wx_analyze.py" score submit --url "https://mp.weixin.qq.com/s/xxxx"

文件不存在或内容为空时脚本退出码 2，如实转告用户后重新收集输入。运行前完成扣点确认（预计 20 点）。评分通常 1–2 分钟；超时（退出码 124）用score status --task-id <id> 恢复轮询，不重复扣点。

节点 2 · 讲结论（一次性产出）

读结果分隔符之间的 JSON，在同一次响应中按固定顺序输出全部区块，不分多轮索要确认：

1. 第一行：{total_score} 分 · {grade} 级 · {publish_action}（publish_action 引用服务端原文，不改写）。
2. 七维表：列为「维度 / 分数(/10) / 区间 / 证据 / 升档差距」，逐行取 dimensions[] 的

label/score/band/evidence/next_tier_gap，逐字引用，不改写、不重新生成点评。

1. 人设一致性固定一行（无论通过与否都显示）：persona_check.status 为 pass → 人设一致性：✓ 通过；为 fail → 人设一致性：✗ 不一致：{note}。
2. ## 诊断：逐条列出 diagnosis.priority_issues（低分维度的具体问题定位）。
3. ## 改写建议：按「原文 vs 改写」对照呈现，每组附一句 rationale——标题（原标题 vs rewrite_examples.titles 的 5 个备选）、开头（opening.original vs opening.rewritten）、结构（structure_outline.original vs structure_outline.adjusted）。

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

结论输出后固定问："要生成 HTML 报告吗？"——不默认生成、不静默跳过，每次评分都重新问一次；回答"不要"直接结束，不追问第二次。确认后：

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

报告为服务端渲染的单文件自包含 HTML（总分仪表盘、7 维雷达图、证据表、改写对照），断网可打开。--no-html 仅在用户明确表示不需要本地文件时使用（报告只保留在服务端）。

结果讲解边界

• 长图文/漫画类提示：若结果里 meta.char_count 很小（如 <300），先向用户说明这篇正文以图片为主、可提取文字极少，文本维度的评分只针对文字部分、参考意义有限——不要把低分直接当作内容质量结论。
• 只讲产物字段：总分/等级/发布建议原文、七维表逐字内容、诊断、改写建议。
• 用户追问「分数怎么算的」时只说这一句："7 个维度加权、每维证据定档、总分由服务端计算，evidence 与升档差距就是可直接复述的归因。"不展开权重数值与评分方法论细节。
• 范围边界：只产出局部改写示例（最多 5 个备选标题、重写开头段落、调整后结构大纲、问题定位），不产出完整成稿。用户要求全文重写时明确告知："改写示例仅用于示范修改方向，完整成稿请基于以上建议自行撰写；本工具专注于评分与局部建议，不做全文代写。"

输出交付

成功时 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」讲给用户，不要把 JSON 原样丢给用户。
2. 告知实际扣点：WX_ANALYZE_POINTS_USED 非空时说「本次任务实际扣除 {点数} 点」；为空时说「本次约扣 20 点（实际以服务端为准，可在 01Claw 账户查看）」。
3. 告知报告查看方式：报告已保存为 HTML 文件，路径见 WX_ANALYZE_REPORT_FILE，可直接双击打开。

退出码处理

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

硬性要求

1. 不得编造或改动任何分数与统计数字。 所有数字必须来自服务端返回；拿不到就如实说拿不到。
2. 报告一律来自服务端渲染。 唯一合法产出方式是 score report；绝不自行用 Write 手写 HTML/CSS/图表，也不伪造一份"看起来像报告"的产物。
3. 不跳过交互节点。 扣点未确认不运行脚本；每次评分都重新问一次是否生成报告。
4. 评分解释只用固定话术。 不展开维度权重、内部评分规则与任何方法论细节。
5. 不做全文代写。 改写建议只到局部示例为止。