@1aboveio/skills 0.20.3 → 0.21.0

package/skills/content-creator/wechat-article-writer/references/style-selector.md

@@ -0,0 +1,133 @@
+# 风格选择指南
+
+## 为什么风格选择很重要
+
+不同风格适配不同的内容目标和传播场景。选错风格会导致：
+- 内容失去传播动力（该踩坑的却写成了行业观察）
+- 读者流失（该给步骤的却只讲道理）
+- 品牌调性不一致（该严肃权威的却过于口语化）
+
+---
+
+## 四种风格的适用背景
+
+### 踩坑型（「真人踩坑 + 工具化输出」）
+
+**核心机制：** 我的痛苦 → 你的解决方案
+
+**最适合的场景：**
+- 你或你的团队/客户**真实踩过这个坑**，有一手经验
+- 目标读者在**同一个痛点上普遍焦虑**（封号、踩坑、选错方案）
+- 问题有**可操作的解决路径**（不是无解的行业困境）
+- 你想**快速建立权威感**（「踩了3次才搞懂」比「专家告诉你」更有说服力）
+
+**不适合的场景：**
+- 没有真实案例支撑，纯观点输出
+- 问题太宏观，无法给出具体步骤
+- 读者已经很了解这个坑，不需要被教育
+
+**在 B2B 场景的变体：**
+- 「我/我们」可以替换为「客户案例」：「某跨境商家踩了这个坑，我们帮他排查了48小时」
+- 情绪可以比 C 端克制：「非常头疼」代替「心态崩了」
+- 工具化输出必须更精确：步骤/CheckList/决策树，不能只是建议
+
+**典型标题信号词：** 踩坑、教训、终于搞懂了、血泪总结、才发现
+
+---
+
+### 实操型（「步骤教程 + 保姆级指南」）
+
+**核心机制：** 照着做就行
+
+**最适合的场景：**
+- 读者有**明确的执行意图**（想做某件事，但不知道怎么做）
+- 操作过程有**标准流程可遵循**（不是因情况而异的判断题）
+- 受众是**执行层**（需要操作手册，不需要战略判断）
+- 内容更新频率低，**不容易过时**（避免下个月就失效的教程）
+
+**不适合的场景：**
+- 问题没有统一答案，高度依赖具体情况
+- 读者是决策层，他们不需要自己操作
+- 内容更新太快，步骤容易过时
+
+**在 B2B 场景的变体：**
+- 读者可能是技术人员（接入文档）或业务人员（配置后台）
+- 技术读者：代码/命令行步骤要精确
+- 业务读者：截图 + 标注 + 常见问题 FAQ
+
+**典型标题信号词：** 手把手、保姆级、完整指南、从0到1、附教程
+
+---
+
+### 对比型（「概念澄清 + 选型决策」）
+
+**核心机制：** 帮读者做决定，省去自己研究的时间
+
+**最适合的场景：**
+- 读者对**两个容易混淆的概念/方案**感到困惑
+- 行业内**存在普遍的认知误区**需要纠正
+- 读者正处于**选型决策阶段**，需要判断框架
+- 你有**比较维度的第一手数据**（不是泛泛而谈的优缺点）
+
+**不适合的场景：**
+- 只有一个合理选择，没有真正的对比价值
+- 比较维度太多，读者看完更迷糊
+- 属于个人偏好，无法给出客观判断
+
+**在 B2B 场景的变体：**
+- 对比要有明确的「适用条件」：什么规模/场景/预算下选 A，什么条件下选 B
+- 可以做成「决策矩阵」或「判断树」，比简单对比更有价值
+- 引用真实数据支撑（成本差异、性能数据、故障率等）
+
+**典型标题信号词：** vs、区别、哪个好、分不清、对比、选型
+
+---
+
+### 观察型（「行业洞察 + 深度观点」）
+
+**核心机制：** 我看到了一个别人没注意到的趋势/问题
+
+**最适合的场景：**
+- 行业**正在发生结构性变化**，读者需要提前感知
+- 你有**独特的数据来源或视角**（非公开的行业洞察）
+- 目标是**建立行业权威感**，培养高质量长期读者
+- 内容**有长尾价值**，不是蹭热点
+
+**不适合的场景：**
+- 只是整合公开信息，没有新的判断
+- 没有明确立场，全篇「可能」「也许」
+- 读者需要即时操作指导，观察型无法满足
+
+**在 B2B 场景的变体：**
+- 可以稍长（1200-1500字），B2B 读者接受深度内容
+- 必须有明确观点，不能只做信息汇总
+- 适合搭配数据图表，增强说服力
+
+**典型标题信号词：** 趋势、观察、为什么、背后、意味着什么、正在发生
+
+---
+
+## 快速选型决策树
+
+```
+有真实案例/一手踩坑经验？
+├── 是 → 有可操作的解决步骤？
+│         ├── 是 → 踩坑型 ✅
+│         └── 否 → 观察型（案例作为佐证）
+└── 否 → 读者有执行意图（想做某件事）？
+          ├── 是 → 实操型 ✅
+          └── 否 → 两个概念/方案需要厘清？
+                    ├── 是 → 对比型 ✅
+                    └── 否 → 观察型 ✅
+```
+
+---
+
+## 混搭原则
+
+单篇文章可以以一种风格为主，融合另一种风格的元素：
+- **踩坑型 + 实操** — 最常见组合：踩坑开场 → 步骤化解决方案
+- **对比型 + 观察** — 概念澄清之后，加一节「行业趋势判断」
+- **观察型 + 实操** — 趋势分析之后，给读者「现在可以做的3件事」
+
+避免：踩坑型 + 观察型混搭（叙事钩子和宏观视角会互相稀释）

package/skills/content-creator/wechat-article-writer/references/writing-rules.md

@@ -0,0 +1,150 @@
+# 公众号写作通用规则
+
+## 目录
+- [目标读者定位](#目标读者定位)
+- [标题公式](#标题公式)
+- [语言规范](#语言规范)
+- [金句设计](#金句设计)
+- [视觉设计适配](#视觉设计适配)
+- [C 端 → B2B 改写参考](#改写参考)
+- [结构共性](#结构共性)
+- [发布前自查清单](#发布前自查清单)
+
+---
+
+## 目标读者定位
+
+根据品牌受众调整。以 **B2B 专业服务行业（如金融科技、支付、SaaS）** 为例：
+- 有业务背景，但不一定是技术开发者
+- 关心「怎么选」「会不会踩坑」「行业在发生什么」
+- 阅读场景：碎片时间刷手机、午休；核心诉求：**省时间、少踩坑、用得上**
+- B2B 读者更在意**权威性和数据背书**，比 C 端用户情绪更克制
+
+如果是 C 端品牌（消费、生活方式、教育），情绪表达可以更活泼，CTA 可以是「立即体验」「关注账号」。
+
+---
+
+## 标题公式
+
+### 公式 A：踩坑-数字-顿悟
+```
+[情绪事件] + [数字] + [顿悟感]
+```
+示例：「被封了3次之后，我终于搞懂了 Claude 的封号逻辑」
+B2B 改写版：「踩了50个支付坑后，我们终于搞懂了网关选型的逻辑」
+
+### 公式 B：问题-解决方案
+```
+[问题定位] + [权威背书] + [用户画像]
+```
+示例：「Claude 封号避坑指南：十几个真实案例总结的国内用户生存法则」
+B2B 改写版：「支付网关怎么选？我们拆了50个真实案例，给出一套可落地的标准」
+
+### 公式 C：数字-痛点
+```
+[数字冲击] + [痛点/悬念]
+```
+示例：「99%的电商都在这三个地方翻车」
+B2B 改写版：「90%的企业在配置风控规则时犯的同一个错误」
+
+### 公式 D：概念对比
+```
+[概念A] vs [概念B]：[X%] 的人分不清
+```
+示例：「支付失败 vs 交易拒付：90%的人都分不清这两个概念」
+
+---
+
+## 语言规范
+
+### 人称使用
+- 叙事/经历 → 「我」：「我们遇到过这样一个案例」
+- 指导/建议 → 「你」：「你应该先检查这一项」
+- 客观分析 → 「我们」：「我们发现，这类问题有三个共性」
+- 不要全篇只用一种人称，保持「我们讲 → 你学」的节奏
+
+### 句子节奏
+- 平均句子长度：12–20字（手机阅读友好）
+- 每段 2–4 句，不超过4句
+- 每 300–500 字安排一个金句
+
+### 禁止表达
+- ❌ 首先、其次、最后（太正式）
+- ❌ 由此可见、综上所述（太书面）
+- ❌ 必须、绝对、一定（语气过硬）
+- ❌ 纯技术术语堆砌不解释
+- ❌ AI 腔：「当然」「值得注意的是」「不难看出」
+
+---
+
+## 金句设计
+
+好金句的三个条件：
+1. 不需要上下文就能理解（截图传播）
+2. 有情绪或观点，不是陈述事实
+3. 50字以内，3秒读完
+
+### 四种金句类型
+**类比型**：「这相当于你一边戴着假发，一边却把身份证递给官方看」
+**反常识型**：「你以为最安全的做法，恰恰是最容易被风控识别的」
+**数字冲击型**：「我们审查过的50个失败案例，有37个栽在同一个地方」
+**自嘲/幽默型**（慎用于 B2B 场景）：「申诉基本无用，但我还是让 AI 写了封言辞恳切的英文信」
+
+### 金句位置
+- 放在段首或段尾，不要埋在段落中间
+- 文章结尾必须以金句收尾
+- 副标题本身也可以是金句
+
+---
+
+## 视觉设计适配
+
+### 文字层面
+- **小标题 ≤10 字** — 一眼扫过能理解
+- **加粗关键词** — 每段 1–2 个，不要整段加粗
+- **数字突出** — 「3次」「7个问题」「90%」这类数字本身是视觉锚点
+
+### 金句卡片（朋友圈截图友好）
+- 金句单独成卡，背景色与正文区隔
+- 留白充足（不是越满越好）
+- 品牌名要够大（缩略图里要看得见）
+
+---
+
+## 改写参考
+
+**原版（C 端风格）：**
+> 「选错支付网关？99%的人都踩过这3个坑，心态崩了！」
+
+**B2B 改写版：**
+> 「选错支付网关？90%的企业都在这三个地方翻车。我们拆了50个真实案例，找到了根本原因。」
+
+改写要点：
+- 去掉情绪夸张（「心态崩了」→ 去掉）
+- 加数据背书（「我们拆了50个真实案例」）
+- 语气平实、有说服力
+
+**如果是 C 端品牌，反向操作：** 加情绪词、减数据堆砌、CTA 更直接。
+
+---
+
+## 结构共性
+
+所有风格文章共同要求：
+1. **开头 200 字**：建立情感连接或紧迫感，不要直接进正文
+2. **每节有「怎么做」**：不只讲「是什么」，给读者行动路径
+3. **CheckList 或步骤**：至少一个可收藏的结构化内容
+4. **结尾 CTA**：根据品牌类型选择合适的行动召唤
+
+---
+
+## 发布前自查清单
+
+- [ ] 标题有数字或情绪钩子吗？
+- [ ] 开头 200 字有代入感吗？
+- [ ] 每节有「怎么做」而不是只有「是什么」吗？
+- [ ] 有金句吗？放在显眼位置了吗？
+- [ ] 文章结尾有明确行动召唤吗？
+- [ ] 有没有超过 4 句没分段的长段落？
+- [ ] 有没有生硬的技术术语没解释？
+- [ ] 截图发朋友圈，3 秒内能看懂核心观点吗？

package/skills/content-creator/wechat-publisher/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/content-creator/wechat-publisher/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: wechat-publisher
+description: "Publish articles to a WeChat Official Account (公众号) via API: push Markdown to the draft box (or auto-publish with --publish), convert Markdown to WeChat HTML, upload images to the media library. Requires AppID + AppSecret + whitelisted server IP on a 认证订阅号/服务号. Consumes wechat-article-writer's Markdown."
+---
+
+# WeChat Publisher (公众号发布)
+
+Publish articles to WeChat Official Account via the official API.
+
+**Full API reference:** `references/api.md` — read when debugging errors or needing endpoint details.
+
+**WeChat-safe layout reference:** `references/wechat-safe-template.html` — read when drafting or fixing article HTML that must survive WeChat rendering.
+
+## Prerequisites (check before starting)
+
+1. **AppID + AppSecret** — from WeChat MP Admin → 开发 → 基本配置
+2. **IP Whitelist** — server's IPv4 must be added in the same page
+3. **Account type** — must be 认证订阅号 or 认证服务号 (personal accounts lost API access in 2025-07)
+4. **Cover image** — JPEG/PNG, ≤64KB (WeChat `thumb` type limit)
+
+Get AppID/AppSecret from `~/.openclaw/openclaw.json` → `channels.weixin` if already configured.
+
+## Standard Workflow
+
+## WeChat-safe HTML rules (important)
+
+When generating or polishing article HTML for WeChat, treat WeChat as a constrained renderer, not a normal browser.
+
+Use these rules for layout-sensitive areas:
+
+- Prefer a **small tag set**: `div`, `img`, `h1/h2/h3`, `pre/code`, and a small amount of `br`
+- Avoid relying on native paragraph and list rendering for precise spacing
+- Do **not** use `ul/li` when spacing matters, WeChat often reflows list items with extra gap
+- Do **not** use multiple `p` blocks inside styled cards for step lists, WeChat often re-renders them as loose paragraphs
+- For **steps**, prefer one `div` with manual line breaks:
+  - `第一步...<br>第二步...`
+- For **bullet lists**, prefer manual bullets in a plain block:
+  - `• 要点 A<br>• 要点 B`
+- For **screenshots**, do not place white screenshots directly on page background
+  - Wrap screenshots in an outer container with white background, padding, light gray border, and rounded corners
+  - Example wrapper pattern:
+
+```html
+<div style="margin:10px 0;padding:6px;background:#fff;border:1px solid #e5e7eb;border-radius:12px;line-height:0;">
+  <img src="..." style="width:100%;height:auto;border-radius:8px;display:block;">
+</div>
+```
+
+- For WeChat article body HTML, omit the visible in-body title if the WeChat draft title is already set separately
+- Keep structure shallow, avoid unnecessary nested wrappers
+- After push, if spacing still looks too loose in the WeChat editor, the final fallback is:
+  - select all
+  - set **段后距 = 0** inside WeChat editor
+
+These rules are more reliable than micro-tuning margin values like `margin-bottom: 6px -> 4px`.
+
+
+### Step 1 — Convert Markdown to HTML (if input is .md)
+
+```bash
+python3 {skillDir}/scripts/md_to_wechat_html.py article.md --output article.html
+```
+
+If the article already contains inline-styled HTML, skip this step.
+
+### Step 1.5 — Normalize HTML for WeChat editor behavior
+
+When the issue is not visual spacing but a **caret-only blank line in the WeChat editor**, treat it as a **block-boundary problem**, not a copywriting problem.
+
+Default rule:
+
+- Use **flat `<div>` blocks for body paragraphs**.
+- Treat `<p>` as an **anti-pattern** for WeChat publishing in this skill.
+
+Why this rule exists:
+
+- In real Agentier testing, multiple versions with `p` still produced a phantom blank editable block before an emphasized sentence.
+- Switching the whole article body to **pure `div` blocks** fixed the issue immediately.
+- Practical conclusion: WeChat may treat `p` boundaries as separate editable paragraph units even when CSS spacing looks correct.
+
+Operating principle:
+
+- Default to **editor stability over semantic HTML richness**.
+- If WeChat editor behavior and semantic markup conflict, prefer the structure that renders and edits reliably in WeChat.
+
+Use these rules:
+
+- Keep the body **one level deep**. Do not nest block elements inside other block elements.
+- Use one natural paragraph per `<div>`.
+- For emphasis, use `<div><strong>...</strong></div>`.
+- Remove empty nodes between blocks: no empty `<p>`, no placeholder `&nbsp;`, no repeated `<br>`, no zero-width filler characters.
+- Minify inter-block whitespace before publish when debugging editor quirks.
+
+Recommended safe structure:
+
+```html
+<div>正文段 1</div><div>正文段 2</div><div><strong>强调句</strong></div><div>正文段 3</div>
+```
+
+Anti-patterns to avoid:
+
+- `<p>` for body paragraphs
+- `blockquote`
+- `ul` / `li`
+- nested `div` / `section` wrappers
+- empty paragraph tags
+- mixed paragraph systems (`p` + `div` in the same article body)
+
+### Step 2 — Publish to Draft Box
+
+```bash
+python3 {skillDir}/scripts/publish.py \
+  --appid <APPID> \
+  --appsecret <APPSECRET> \
+  --title "文章标题" \
+  --html article.html \
+  --thumb-image cover.jpg \
+  --author "作者名" \
+  --digest "摘要（最多120字）"
+```
+
+Output: `{ "ok": true, "draft_media_id": "xxx" }`
+
+The article now appears in the draft box. Open **微信公众号助手 App** on mobile → 草稿箱 → review → publish.
+
+### Step 3 (optional) — Auto-publish Live
+
+Add `--publish` flag to push live immediately (skips manual review):
+
+```bash
+python3 {skillDir}/scripts/publish.py ... --publish
+```
+
+Output: `{ "ok": true, "draft_media_id": "xxx", "publish_id": "yyy", "publish_status": {"status": "success"} }`
+
+⚠️ Only use `--publish` when Jonas explicitly approves skipping manual review.
+
+## Inline Image Handling
+
+If the article HTML contains local image paths (`<img src="./images/foo.png">`), upload them first:
+
+```python
+# Quick one-liner to get the WeChat CDN URL for an image
+import subprocess, json
+result = subprocess.run([
+    "python3", "-c",
+    """
+import requests, sys
+token = sys.argv[1]
+with open(sys.argv[2], 'rb') as f:
+    r = requests.post(f'https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token={token}', files={'media': f})
+print(r.json()['url'])
+""",
+    "<token>", "image.jpg"
+], capture_output=True, text=True)
+print(result.stdout.strip())
+```
+
+Then replace `src="./images/foo.png"` with the returned CDN URL in the HTML.
+
+## Error Quick-Reference
+
+| Error | Fix |
+|-------|-----|
+| `40164` IP not in whitelist | Add server IP in WeChat MP Admin |
+| `48001` API not authorized | Account not certified or permission missing |
+| `40007` invalid media_id | Cover image upload failed — retry upload |
+| `45009` rate limit | Wait for next day or reset quota in MP Admin |
+
+Full error codes: `references/api.md`

package/skills/content-creator/wechat-publisher/references/api.md

@@ -0,0 +1,105 @@
+# WeChat Official Account API Reference
+
+## Authentication
+
+**Get access_token** (valid 2 hours; cached in `/tmp/wechat_access_token.json`)
+```
+GET https://api.weixin.qq.com/cgi-bin/token
+  ?grant_type=client_credential&appid=APPID&secret=APPSECRET
+→ { "access_token": "...", "expires_in": 7200 }
+```
+Daily limit: 2000 calls. Always cache; never call per-request.
+
+**IP Whitelist** — The calling server's IP must be added in:
+WeChat MP Admin → 开发 → 基本配置 → IP白名单
+
+---
+
+## Content Publishing Flow
+
+### Step 1: Upload cover image (permanent material)
+```
+POST https://api.weixin.qq.com/cgi-bin/material/add_material?access_token=TOKEN&type=thumb
+  multipart/form-data: media=<file>
+→ { "media_id": "...", "url": "..." }
+```
+- Cover image: JPEG/PNG, **≤64 KB** for `thumb` type
+- Returns `media_id` for use in draft creation
+
+### Step 2: Upload inline images (article body)
+```
+POST https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=TOKEN
+  multipart/form-data: media=<file>
+→ { "url": "https://mmbiz.qpic.cn/..." }
+```
+- Any images in the article HTML body must be replaced with these CDN URLs
+- External image URLs will NOT render inside WeChat
+
+### Step 3: Create draft
+```
+POST https://api.weixin.qq.com/cgi-bin/draft/add?access_token=TOKEN
+{
+  "articles": [{
+    "title": "文章标题",
+    "author": "作者名",
+    "digest": "摘要（≤120字）",
+    "content": "<p>HTML正文</p>",
+    "thumb_media_id": "<from step 1>",
+    "need_open_comment": 0,
+    "only_fans_can_comment": 0
+  }]
+}
+→ { "media_id": "draft_media_id" }
+```
+Daily limit: 1000 drafts
+
+### Step 4 (optional): Publish draft live
+```
+POST https://api.weixin.qq.com/cgi-bin/freepublish/submit?access_token=TOKEN
+{ "media_id": "draft_media_id" }
+→ { "errcode": 0, "publish_id": "123456" }
+```
+Daily limit: 100 publishes
+
+### Step 5 (optional): Poll publish status
+```
+POST https://api.weixin.qq.com/cgi-bin/freepublish/get?access_token=TOKEN
+{ "publish_id": "123456" }
+→ { "publish_status": 0, "article_id": "..." }
+```
+`publish_status`: 0=成功, 1=发布中, 2=失败, 4=已删除
+
+---
+
+## Account Type Requirements
+
+| Feature | 个人未认证订阅号 | 认证订阅号 | 认证服务号 |
+|---------|--------------|----------|----------|
+| 草稿箱/发布 API | ❌ (2025-07 回收) | ✅ | ✅ |
+| 群发接口 | ❌ | ✅ | ✅ |
+| 模板消息 | ❌ | ❌ | ✅ |
+| 网页授权/支付 | ❌ | ❌ | ✅ |
+
+**Minimum requirement: 认证订阅号 (企业/组织主体)**
+
+---
+
+## HTML Content Requirements
+
+- All CSS must be **inline** — no `<style>` tags, no external CSS
+- No `<html>`, `<head>`, `<body>` wrapper (WeChat provides it)
+- Images: must be WeChat CDN URLs (upload first via `uploadimg`)
+- Font size: 14–16px recommended for mobile
+- Line height: 1.6–1.8 for readability
+
+---
+
+## Common Error Codes
+
+| errcode | Meaning | Fix |
+|---------|---------|-----|
+| 40001 | invalid access_token | Refresh token |
+| 40164 | IP not in whitelist | Add server IP to whitelist |
+| 45009 | API rate limit exceeded | Wait or reset quota |
+| 48001 | API not authorized | Account not certified or lacks permission |
+| 40007 | invalid media_id | Re-upload the media |

package/skills/content-creator/wechat-publisher/references/layout-rules.md

@@ -0,0 +1,57 @@
+# WeChat-safe layout rules
+
+Use this reference when article HTML must survive WeChat draft/editor rendering.
+
+## Core rule
+
+Treat WeChat as a constrained renderer, not a normal browser.
+
+## Team rules
+
+1. Prefer a small tag set
+   - `div`
+   - `img`
+   - `h1/h2/h3`
+   - `pre/code`
+   - a small amount of `br`
+
+2. Do not rely on native list or paragraph spacing when layout matters
+   - avoid `ul/li`
+   - avoid multiple `p` blocks inside styled cards
+
+3. Build steps as one block
+   - use one `div`
+   - separate lines with `<br>`
+
+4. Build bullets manually
+   - use `•` in a plain `div`
+   - do not use native list markup for spacing-sensitive sections
+
+5. Always wrap white screenshots
+   - white background
+   - padding
+   - light gray border
+   - rounded corners
+
+6. Keep body HTML title-free
+   - the WeChat draft title is configured separately
+   - do not repeat the article title inside body HTML
+
+7. Keep section hierarchy readable
+   - section headings need visible top spacing
+   - subsection headings also need top spacing, but less than sections
+
+8. Use WeChat editor as final fallback
+   - if the draft still looks too loose, select all and set `段后距 = 0`
+
+## Most common failure patterns
+
+- margin micro-tweaks that do not survive WeChat rendering
+- `ul/li` producing unexpected extra space
+- card blocks made of many child paragraphs/divs becoming loose after push
+- white screenshots visually disappearing into page background
+
+## Recommended reference files
+
+- `wechat-safe-template.html` for reusable HTML skeleton
+- `api.md` for publishing/debugging details