公众号文章写作

把一个想法变成一篇能发的公众号文章。产出落到 <写作目录>/YYYY-MM-DD-<短slug>.md（写作目录见下方「写作目录」）。

写作目录

产出落盘到哪里由你定，用 <写作目录> 占位表示。常见做法是 ~/Documents/<分类>/<主题>/。

如果你的环境有约定的产出位置（比如某个 Obsidian vault 或工作区目录），先确认一下再落盘。

给公开版用的注意

这个 skill 可能被发布给别人用，所以：

• 不要出现作者姓名、本机路径、机器特定目录 —— 产出位置用 <写作目录> 占位
• 不要评价其它 skill 或项目 —— skill 只说「该怎么做」，不解释「我为什么这么选」、不比较别家做法
• 具体做法直接写；把「容易滑向的两种极端」写成通用提醒，而不是点名批评谁

与 wechat-oneclick-publish 的分工

写完成稿后，调用另一个 skill 完成排版发布。不要在本skill 里重复实现排版。

先判断起点：两种走法

文章有两种起手，流程不同。先判断走哪条。

判断依据：用户手上有没有已经成形的东西。有草稿、有笔记、有一段口述 → 路线 B。什么都没有只有一个主题 → 路线 A。

两条路线会汇合：路线 A 写出的初稿，之后很可能进入路线 B 反复改。

路线 A · 从零选题

写作风格（必须遵守）

完整规范见 references/writing-style.md。核心是平易近人。

这是最重要的原则：写给一个坐在工位上、想省点事的普通读者看，像跟朋友聊天，不像写文档。

• 通俗易懂 —— 术语第一次出现随手解释一句；能用大白话就别用黑话。用户可能不用 AI、不写代码，只是想搞明白怎么回事。
• 平易近人 —— 不端着、不说教、不居高临下。承认自己也会踩坑、也会返工，写下来给同类读者看。
• 不喊口号 —— 不写"震惊""必看""太爽了""99% 的人不知道"。用具体步骤和真实取舍说话。
• 不讲抽象概念 —— 只讲"怎么搭、什么时候用哪条路"，读者看完能自己复现。
• 第一人称「我」，短句为主，不堆形容词。

关键差别："我"是讲述者不是评判者。可以说"我觉得这样更省事"，不要说"这样做才是正确的"。

语气示范（对照着感受）

❌ 端着的："本方案通过分层解耦实现了工具链的规范化管理。"
✅ 平实的："这套接法最大的好处是：换工具不用重写流程。"

❌ 说教的："你应当首先配置 IP 白名单，否则接口将无法调用。"
✅ 平等的："这里有个坑：IP 没加白名单，接口直接报错。加上就行。"

❌ 装专家的："经过多轮实践，我沉淀了一套方法论。"
✅ 聊天的："折腾了两周，总算把这套跑顺了。过程里几个坑，记一下。"

⚠️ 两个极端都要避开 —— 太冷硬专业（像技术方案书）和太营销（感叹号、"太爽了"、堆配图）都不对。我们要的是亲切：不端着，但不随便。

阶段 1 · 选题定位（三问法）

写之前必须明确，缺一项就问用户：

1. 写给谁看 —— 目标读者的身份、技术水平、痛点
2. 读者能得到什么 —— 具体收获（能做什么、避开什么坑）
3. 看完做什么 —— 期待的行动（自己搭一套 / 转给同事 / 收藏备用）

若用户只丢来一个模糊想法，先反问这三点，别急着动笔。

> ⚠️ 这条只适用于路线 A。 路线 B（手上已有素材）不要走三问法 —— 直接出初稿让他改，比先追问有效率得多。详见路线 B「素材入口」。

阶段之间：停下来等确认

每个阶段完成后停下来，把结果给作者看，等他确认再往下走。 素材多的时候尤其重要 —— 走错方向再改，浪费的是整篇文章。

不要一口气写完整篇再给作者。 一口气写完再返工，浪费的是双方的时间。

⚠️ 这个只适用于路线 A。 路线 B（迭代打磨）本来就是一轮一轮来的，不要在这里加额外停顿。

阶段 1.5 · 内容地图（素材多时必做）

素材只有几句话的时候跳过这一步，直接进框架。素材多了（超过 5 个要点，或者来源是长对话/多篇笔记），先画地图再动笔。

直接按模板写，素材一多就会漏 —— 写完发现某个要点没进去，或者两个要点重复说了。

画地图只要三步：

1. 列点 —— 把素材里所有值得写的点列出来，标出哪些是干货、哪些该删（寒暄、重复、常识）。

2. 理关系 —— 判断这些点之间是什么关系：

关系决定结构，不按素材出现的顺序排。 这是最容易做错的地方 —— 顺着素材顺序写，读者会觉得散。

3. 标重点 —— 挑出必须保留的例子和具体数字。这些是说服力的来源，不能被结构优化掉。

顺带做一次素材审查 —— 检查素材本身有没有问题：

• 事实性错误
• 逻辑漏洞
• 过度简化（把「通常」写成「一定」这类）
• 争议性观点

发现问题列出来问作者，别自己改。作者给的理由才是真的（见 pitfalls.md 第 1 条）。

画完地图先给作者看一眼再往下走 —— 他会一眼看出你漏了什么。

阶段 2 · 标题备选

给 5 个候选（不是 5-10 个，作者不需要爆款标题轰炸），每个注明角度。控制在 15-25 字。

可用公式（示例都按平实口吻写，不要改成营销腔）：

禁用：震惊、必看、绝密、刚刚、疯了、暴利。也不要用"碾压""吊打""保姆级""一看就会"这类。

阶段 3 · 结构框架

按文章类型选骨架，报给用户确认后再写正文。

操作说明类（主力，约 2000-3000 字） —— 与既有风格一致：

H1 标题
导语：讲什么 / 不讲什么 / 看完能做什么
---
## 1. <路径或方法一>
    适用场景 / 怎么接 / 日常怎么用 / 注意点
---
## 2. <路径或方法二>
    （同上结构）
---
## N. <组合或选型建议>
---
汇总表格
加粗提炼一句话原则

观点类：现象引入 → 原因分析 → 核心论点 → 论据 ×2 → 总结升华。

踩坑复盘类：结果前置 → 背景 → 撞墙 → 转折 → 收获清单 → 避坑表。

小标题要具体，❌「第一部分」「方法介绍」，✅「01 飞书对接 DSH：碎片任务怎么随手丢」。

小标题的语气同样要平实 —— 写「这块最容易翻车」比「注意事项」更贴近读者。

阶段 4 · 撰写

按框架写初稿，落盘到 <写作目录>/YYYY-MM-DD-<短slug>.md。

frontmatter 格式（沿用既有约定）：

---
标题: <文章标题>
封面备注: <封面图意图描述，仅备注不配图>
日期: YYYY-MM-DD
状态: 初稿
---

正文第一个元素是 # 标题（与既有文件一致）。

写完先算字数，再开头标注

每篇文章开头必须标明字数和预计阅读时间 —— 让读者一开始就知道要花多久，判断值不值得读。

顺序不能反：先写完，再算字数，最后把标注插到标题下面。写之前估不准，写完才知道。

算字数（只数正文，不含 frontmatter 和标题行）：

$PY - <<'EOF'
import re
t = open('文章.md', encoding='utf-8').read()
body = t.split('\n---\n', 1)[1]          # 去掉 frontmatter
n = len(re.findall(r'[\u4e00-\u9fff]', body))
minutes = max(1, round(n / 400))        # 中文阅读速度约 400 字/分钟
print(f'{n} 字 | {minutes} 分钟')
EOF

标注格式，放在 # 标题 下面第一行：

# 文章标题

**全文约 2400 字，读完 6 分钟。** 不长，值得看完。

几点要求：

• 字数取整到百位 —— 「约 2400 字」比「2387 字」自然，也留了余量
• 阅读时间按 400 字/分钟算 —— 中文读者的常见速度。太长的数字会劝退人
• 不足 3 分钟的写「读完 X 分钟」，别写「1 分钟以内」 —— 显得轻浮
• 超过 15 分钟的，标注后面加一句提醒 —— 「篇幅有点长，赶时间可以只看第 2 节和第 5 节」

⚠️ 改稿后字数会变 —— 每次砍内容或加内容，都要重算这个标注。标注跟正文对不上是最容易被发现的破绽。

写之前该查的（路线 A 适用）

题材需要事实支撑时，并行搜多个来源 —— 官方文档、源码仓库、社区讨论一起搜，别只搜一个就下笔。

# 并行开几个搜索，别串行等
# WebSearch 支持并行调用，一次发多条查询

优先读真实来源：配置命令读官方文档，功能描述读源码或 release notes，版本号和价格搜官方定价页。搜不到就标「推测/待验证」，别用记忆写。

去 AI 味

写完通读一遍，对照 references/de-AI-voice.md（12 条具体判据 + 自检清单）。

这是 AI 写公众号最大的短板 —— 不是写错，是太规整。真人写的东西有起伏、有偏好、有不对称。

最常见的四处：段落长度清一色、破折号用太密、结尾升华、只列选项不给判断。

撰写自检

• [ ] 开头标了字数和阅读时间，且跟正文实际字数对得上？
• [ ] 导语说清了边界，语气不端着？
• [ ] 每章都有"适用场景"和"注意点"？
• [ ] 术语第一次出现时解释了一句，普通人能读懂？
• [ ] 有具体的步骤、命令、路径，而不是泛泛而谈？
• [ ] 每步除了"怎么做"，还说了"为什么"或"会碰到什么"？
• [ ] 表格里的每项都经得起核对？
• [ ] 通篇没有禁用词和营销腔，也没有冷硬专业腔？
• [ ] 收尾有汇总表 + 一句提炼？
• [ ] 过了一遍去 AI 味清单（见 references/de-AI-voice.md）？
• [ ] 给了明确的选择和理由，不是「各有优劣」？

阶段 5 · 信息校验（不能跳）

AI 写的技术细节极易出错，必须逐条核实。完整清单见 references/fact-check-template.md。

每条事实断言要有来源依据，无法确证的标「推测/待验证」，无依据视为未完成，不得交付。

但公众号正文里不要出现来源标注 —— 读者要的是结论和做法，不是考据过程；满篇「出处/来源/参考」会打断阅读节奏。

做法：先核实（WebSearch / 读源码 / curl 验仓库），确认无误再写进正文，但不要把来源标注写进去。

• ❌ > 规格出处：Apple 2026-08 发布的 M5 Pro Mac mini…
• ❌ > [src: xAI 官方定价 docs.x.ai/...]
• ✅ 直接写结论：Apple 2026 年 8 月发布的 M5 Pro Mac mini，官方称适合「全天候智能体计算」。
• ✅ 需要提示实测的，写在句子里：Cursor 切到 CNY 会出现支付宝（我实测能用）。

如果某个数字（价格、版本号、限额）容易过时，在正文里就写明出处名称，比如「按 xAI 官方定价页的说法」，而不是挂一个引用块。

加粗：一句话最多一处

加粗是强调，不是通篇高亮。一句话里放两个加粗会把句子切成三段，读起来一顿一顿 —— 这是最容易犯的错。

❌ 我现在的角色是**产品和研发一起做**，包括了写材料……
   **问题不在于能力不够，在于精力真的有限。**
   三十几岁最实在的焦虑是怕被淘汰……：**如果家里也有 AI……？**

✅ 我现在的角色是产品和研发一起做，包括了写材料……
   问题在于精力真的有限。
   三十几岁最实在的焦虑是怕被淘汰……如果家里也有 AI 能一直帮我干活，那我是不是就不用跟年轻人拼体力了？

允许的例外：标签式结构是可以的，因为是两个独立信息点。

✅ **注意点**：它是调度层不是执行层；而且它的消耗和 Cursor 里用 Grok 模型是**同一个额度池**。
✅ **坑一：Claude / GPT 套餐本来就不含。** xAI 官方规则很明确：**按 API 价单独计费。**

自检时扫一遍全文：任何一句里 ** 出现两次以上就检查一下是不是切碎了。

高频错误类型：

• 把「社区适配」写成「官方原生支持」
• 编造不存在的产品功能名
• 捏造具体数字（用户数、体积、版本号）
• GitHub stars / 版本号过时
• 安装方式与实际不符

对含配置命令、API 参数、版本要求的段落，优先读真实源码或官方文档，不要靠记忆写。

阶段 6 · 配图规划

先出方案，不直接生成。 把封面意图 + 每章配图位置列成表给用户确认，再决定是否调用图像生成。

这类文章通常不需要 11 张配图 —— 克制，够用即可。技术文章常用配图：架构流程图、终端截图、对比示意图。

不生成图时，在 frontmatter 封面备注 里写清意图，搬进后台时再配。

路线 B · 迭代打磨

素材已经在了，要在它基础上反复改。完整规则见 references/edit-amplitude.md（改动幅度速查表）和 references/pitfalls.md（每条规则的原因与例子）。

核心原则：保留已定内容

迭代打磨最危险的事是把用户前面确认过的东西改没了。用户花三轮讨论定下的开头，你第四轮重写时给换掉了 —— 这是灾难。

每一轮改动前，先明确：这次动的是什么？其它部分一个字都不许碰。

改动幅度分级

判断清楚了再动手，选错工具是这次任务最大的风险。

不确定时默认按最小幅度处理。 宁可少改让用户追加要求，也不要大动让用户逐字对比。

用户说「这段太长了」→ 只砍这一段。「字数太多了，减少一半」→ 砍全文，但保留他的原句优先于你的改写。

联动改动的连带清单

移动或删除章节后，逐项检查：

• [ ] 大节编号连续无跳号（## 1. ## 2. …）
• [ ] 小节编号跟着父节走（### 2.1 ### 2.2）
• [ ] 正文里「上文第 X 节」这类交叉引用
• [ ] 「全文约 N 字」这类自我描述 —— 改完必须重算
• [ ] 表格里的节号引用
• [ ] frontmatter 里的标题、封面备注

素材入口：三种起手方式

A. 一段口语化的设想

用户说的可能是：「我想写个 Mac mini 配 AI 套餐的帖子」。

别急着问一堆问题。 阶段 1 的三问法是给从零写用的 —— 用户已经有想法了，直接出初稿让他改比先追问有效率得多。

正确做法：把设想理解成一个可写的最小版本 → 落盘 → 告诉他「先给个能看的版本，你直接在上面改」。

先问的问题只限不问就没法动笔的：素材文件在哪、有没有必须写到的具体信息（价格、命令、数据）。

B. 一篇现成草稿

先读全文，然后：

• 保留他的句子和结构，只补明显缺的部分
• 如果草稿有明显的事实错误或过时信息，指出来但别擅自改（除非作者要求核实）
• 落盘到 <写作目录>/YYYY-MM-DD-<短slug>.md

C. 零散笔记 / 聊天记录

按信息筛选原则处理：留下方法、洞察、具体案例；删掉寒暄和重复表达。

但不要改写成「对话记录整理」的样子。 读者不需要知道素材来自对话，成品应该像作者自己想清楚的。

首次落盘时就要带字数标注

不管哪种起手方式，第一次落盘就要在标题下面标好字数和阅读时间（格式见阶段 4「写完先算字数」）。

理由：作者拿到初稿第一眼就会看这个数字。标注给了他对成稿的预期 —— 说是 2400 字，他改的时候心里有尺；没有标注，他只能自己数。

之后每轮改完都要重算。 砍了 500 字，标注也得跟着变。

迭代中的高频坑

每条的原因和例子见 references/pitfalls.md（规则 → 为什么 → 例子）。这里只列规则本身：

1. 别自己编「为什么」 —— 写之前先问作者，或留空让他填
2. 一句话最多一处加粗 —— 标签式结构例外
3. 脚本改完必查 —— 转义残留、HTML 实体、frontmatter 分隔符、空行
4. 章节重排后必查编号 —— 替换从后往前
5. 开头别放「适合谁」 —— 先讲经历，再给筛选标准
6. 用户原句优先于「优化」 —— 照抄不改写，但排版故障要改
7. 留意用户新增的词 —— 那通常是他想强调的
8. 内部草稿区不能发出去 —— 「待补充」「备选标题」交付前删掉
9. 别把内联 TODO 留在正文 —— 用灰色下划线占位，别用方括号
10. 改稿后重算字数标注 —— 标注跟正文对不上最容易被发现

每轮交付前的自检

改完每一轮，跑一遍：

# 结构
grep -nE '^#{1,3} ' 文章.md              # 编号连续、无跳号、无重复
grep -c '^## ' 文章.md                   # 章节数
# 格式
grep -n '\\\*' 文章.md                    # 转义残留
grep -n ' ' 文章.md                  # HTML 实体残留
grep -n '\*\*.*\*\*' 文章.md# 同一行多个加粗
# 排版验证
$PY $SKILL/md2wechat.py 文章.md -t ink -o /tmp/check.html

排版脚本输出必须满足：0 个 <style、0 个 class=、0 个 <p> 包 <section>。

h = open('/tmp/check.html').read()
ok = (h.count('<style') == 0 and h.count('class=') == 0
      and not re.search(r'<p[^>]*>\s*<section', h))

收尾：排版与发布

内容定稿后，交给 wechat-oneclick-publish：

$PY $SKILL/md2wechat.py 文章.md -t ink --copy

技术类文章用 ink（墨白），通用科普用 wechat-green。

然后提醒用户补齐后台里的东西：

• 标题 —— 公众号上限 64 字
• 摘要 —— 上限 120 字，实际只显示前 30-50 字，必须手写（系统自动抓正文前 54 字通常是废话）
• 封面图 —— 900×383

摘要写法：说清「为了什么 + 做了什么」，别重复标题已说过的内容。

图片处理

正文图和封面分开对待。

竖图（超过约 1:1.3）必须裁切 —— 竖着放在正文中间会把读者视线撑得很开。裁掉上方空白和底部桌面，只留主体。

全部图片以 base64 内嵌（--img-mode auto，默认值）。图片全内嵌时 HTML 体积会暴涨，单张压到 200KB 以内、整体控制在 500KB 左右。

另一种形态：贴图（俗称小绿书）

除了长文，公众号还能发纯图片帖 —— 像小红书那样，375px 宽、3:4 比例的图卡，多张组成一篇。

什么时候用：内容本身是清单、步骤、对比、视觉化的话，用贴图比长文更好读。

跟长文的差别：

图内必须有文字 —— 纯图没信息量，读者划过去就忘了。标题放图里，不要指望配文。

上架到技能市场（想让别人也能用）

SKILL 写完放在本机只有自己能用。想让别人装，得发到技能市场。

先检查隐私 —— 这步不能跳

发布是公开的，撤不回来。 发之前把整个目录扫一遍：

# 人名、本机路径、私有项目名
grep -rnE "你的名字|/Users/|/home/|你的目录名|workspace" .

四个常见雷：

同时检查有没有在评价别的项目 —— skill 只说「该怎么做」，不解释「我为什么这么选」、不比较别家做法。

发布字段

本地用只需要 name / description / agent_created。要上架还得补：

slug: my-skill        # 全网唯一，冲突报 409
displayName: 中文展示名
version: 1.0.0
summary: 一段简介     # 建议比 description 短
license: MIT

slug 发布后别改 —— 改了等于新建一个技能，历史版本和详情页链接全断。

发布流程

# 1. 装 CLI（一次性）
curl -fsSL https://skillhub.cn/install/install.sh | bash -s -- --cli-only

# 2. 登录（token 形如 skh_…，在平台个人设置里拿）
skillhub login --key <token> --host https://api.skillhub.cn
skillhub auth whoami

# 3. 先预检
skillhub publish <skill目录> --dry-run

# 4. 正式发布
skillhub publish <skill目录> --changelog "本次变更说明"

CLI 直接收文件夹，不用打包成 zip。 更新 = 同 slug + 升 version + 换 changelog，流程和首次发布一样。

三个坑

• LICENSE 和 .gitignore 会被拒 —— 实测报 400「不允许的文件类型」，打包时剔掉；许可写在 SKILL.md 的 license: 里
• 版本号要递增 —— 不递增平台会当成同一个版本
• 发布完是 pending_review，不是失败 —— 新版本在审核队列里，通过了线上才更新。别当失败重发

⚠️ 旧版本在审核通过前仍公开可见 —— 如果旧版本泄露了什么，重发解决不了，得找平台下架。

交付话术

每轮改完，说清三件事：

1. 改了什么 —— 具体到段落，不要只说「已优化」
2. 现在的规模 —— 字数、章节结构
3. 还差什么 —— 需要他确认/核实的事项（价格、版本号、命令这类必须让他自己过一眼）

第三项不能省。 涉及事实、价格、版本号的地方，标出来让作者核。

如果你的工作区有「产出记录」习惯，回写一行到当天的记录文件：

- HH:mm｜公众号｜产出｜《文章标题》初稿已落盘｜文件绝对路径

时间用 Asia/Shanghai，遵守该文件的追加式格式，不改写他人行。

常见坑