zhy-wechat-writing

# 微信公众号写作系统 ## Purpose 根据用户提供的主题（可选参考URL），自动完成公众号文章写作全流程：多来源检索与证据池整理、初稿生成、自审润色、参考资料整理，并可选自动配图与保存到公众号草稿箱（不提交发布）。 ## When to Use - 用户请求"写一篇关于XXX的公众号文章" - 用户请求"生成公众号文章，主题是XXX" - 用户需要完整的公众号文章创作流程 - 用户希望"写完后自动配图"或"写完后发到公众号草稿箱" ## Prerequisites 执行前需要确认： - 用户已提供文章主题（`topic`） - 如有参考文章 URL，可一并提供（`urls`） - 若 `topic` 为纯中文且未提供 `slug`，建议补充英文/拼音 `kebab-case` 目录名；否则会使用 ASCII 降级方案 ## Workflow 按照以下步骤顺序执行（产物默认落盘到 `articles/<slug>/...`，便于复跑与追溯）： ### Phase 0: Preflight **目标**：确定可稳定复用的目录与路径规范 **操作**： 1. 计算 `slug` - 若用户提供 `slug`：直接使用（推荐：英文/拼音kebab-case） - 若 `topic` 含拉丁字母/数字：对其做kebab-case - 否则降级：`wechat-article-YYYYMMDD` 2. 创建目录： - `articles/<slug>/` - `articles/<slug>/sources/` 3. 规范：Markdown图片引用必须使用相对路径与 `/` 分隔符 ### Step 1: 素材搜集 **目标**：搜集与主题相关的素材，并整理为可追溯的证据池 **操作**： 1. 若用户提供 `urls`：并行使用 `webfetch` 获取内容，提取要点，并记录URL与可获得的发布日期 2. 若用户未提供 `urls`：并行使用 `WebSearch` 做多来源检索（建议覆盖：官方文档 / X(Twitter) / Reddit / 技术论坛 / 微信公众号 / 工程实践） - official/authority：官方文档、标准/规范、权威媒体解读 - community：X(Twitter)、Reddit、论坛/讨论 - practice：GitHub issues、工程博客、案例复盘 - 推荐并行 query 模板（按需组合，尽量加年份/时间范围以强调近期）： - `{topic} official documentation` / `{topic} release notes 2025 2026` - `{topic} site:x.com` / `{topic} site:twitter.com` - `{topic} site:reddit.com` / `{topic} site:reddit.com/r/<subreddit>` - `{topic} site:github.com issues` / `{topic} site:github.com discussions` - `{topic} site:stackoverflow.com` / `{topic} site:news.ycombinator.com` - `{topic} site:mp.weixin.qq.com` (公众号) - `{topic} 实战 复盘 踩坑 2025 2026` (中文工程实践) 3. 合并去重，按可信度分级（high/medium/low），形成证据池，落盘： - `articles/<slug>/sources/evidence.md` **工具映射**： - 本流程中的“搜索”使用：`WebSearch` - 本流程中的“抓取网页内容”使用：`webfetch` **关于 WebSearch（实现说明）**： - 优先使用运行环境自带的 `WebSearch` 工具。 - 若当前环境没有可用的 `WebSearch`：用 `webfetch` 抓取公开搜索结果页（SERP），从结果中提取 URL 列表后再并行 `webfetch` 正文内容。 **证据池条目格式（每条必须包含）**： - title - url - published_at（可得则写） - source_type（official/community/practice） - key_takeaways（3-6条要点，尽量可直接改写成正文素材） - confidence（high/medium/low） **停止条件（建议）**： - 候选来源 8-12 条，其中 medium/high >= 5 条 **常见失败处理（新增）**： - X/Reddit 登录墙或无法抓取正文： - 优先选择可公开访问的镜像/引用（二手报道需标注 `confidence=low/medium`），或改抓同一观点的博客/论坛转载； - 若必须引用原帖：只使用 WebSearch 结果摘要 + 其他独立来源佐证，不编造细节。 - SERP 抓取/解析失败（无 WebSearch 回退路径时）： - 改用“站内检索”策略：直接用 `webfetch` 抓官方站点的搜索/博客索引页或 GitHub 搜索页； - 仍无法覆盖时：向用户要 3-5 个关键 URL 或指定信息源清单。 - 去重与可信度： - 同一事实至少 2 个独立来源佐证； - 官方/一手文档优先标 `high`；社区讨论若无落地细节或无交叉验证标 `low`。 **输出**：`sources_path`（证据池路径） --- ### Step 2: 初稿生成 **目标**：基于素材生成公众号文章初稿 **写作要求**： 1. **标题**：吸引眼球，可使用以下技巧 - 数字型：`5个方法让你...` - 提问型：`为什么...？` - 对比型：`A与B的区别...` - 悬念型：`你不知道的...` 2. **开头**（前3-5行）： - 提出痛点或引发共鸣 - 设置悬念或提出问题 - 明确文章价值 3. **正文结构**： - 使用小标题分段（## 或 ###） - 每段200-300字 - 包含案例、数据支撑 - 使用列表增强可读性 4. **结尾**： - 总结核心观点 - 引导互动（点赞、在看、评论） - 可添加金句或行动呼吁 5. **字数要求**：1500-2500字 6. **可追溯性要求（新增硬约束）**： - 关键事实/数据/结论必须能在证据池中找到支撑 - 文章末尾必须追加 `## 参考资料/来源`（5-10条链接，尽量带日期） **输出**：Markdown 格式初稿，保存到：`articles/<slug>/article.md` --- ### Step 3: 智能审稿 **目标**：从四个维度审稿，发现问题 **审稿维度**： | 维度 | 检查要点 | 权重 | |------|---------|------| | 逻辑 | 论点清晰、论据充分、推理合理 | 30% | | 表达 | 语言流畅、无AI痕迹、口语化适度 | 25% | | 数据 | 数据准确、案例恰当、引用规范 | 25% | | 结构 | 标题吸引、段落分明、首尾呼应 | 20% | **新增硬检查**： - 可追溯性：关键论断是否能在证据池中找到支撑 - 标题一致性：标题承诺是否在正文明确兑现 **审稿操作**： 1. 逐段检查逻辑连贯性 2. 标记AI痕迹词汇（如"综上所述"、"不难看出"等） 3. 验证数据和案例的准确性 4. 检查结构和节奏 **评分标准**： - 90-100分：优秀，可直接发布 - 80-89分：良好，小幅优化即可 - 70-79分：合格，需要修改 - 70分以下：需要重写 **输出**：审稿报告（包含问题和修改建议），建议保存到：`articles/<slug>/sources/review.md` --- ### Step 4: 润色打磨 **目标**：修复问题，提升文章质量 **润色操作**： 1. **去除AI痕迹** - 替换词汇： - `综上所述` → `总的来说` - `总而言之` → `说到底` - `由此可见` → `所以说` - `不难看出` → `我们能发现` - `众所周知` → `大家都知道` - 避免过于书面化的表达 2. **增强口语化** - 适当添加：`其实`、`说实话`、`不得不说` - 使用短句，避免长难句 - 加入过渡词，增强流畅度 3. **优化节奏** - 长短句结合 - 适当使用感叹句、反问句 - 控制段落长度（建议不超过5行） 4. **修复审稿问题** - 根据审稿报告逐项修复 - 补充缺失的数据或案例 - 调整不合理的结构 **输出**：最终文章 **强制要求（新增）**： - 最终文章必须保留或补齐 `## 参考资料/来源` - 参考资料建议保留 5-10 条，按 `official` / `community` / `practice` 分组更佳 --- ### Step 5: 保存与输出 **操作**： 1. 创建输出目录（如果不存在）： - `articles/<slug>/` 2. 保存文章： - `articles/<slug>/article.md` 3. 输出执行摘要： - `article_path` - `sources_path` - 字数统计 - 审稿评分 --- ### Step 6: 自动配图（可选，调用 zhy-article-illustrator） **触发条件**：`with_illustrations=true` **目标**：为文章生成统一风格的高完成度配图，并产出插图版文章 **默认策略**： - `article_path`：使用 `articles/<slug>/article.md` - `slug`：复用当前文章 slug - `density`：`illustration_density`（默认 balanced） - `upload`：`illustration_upload`（默认 false） - `aspect_ratio`：`illustration_aspect_ratio`（默认 16:9） - `prompt_profile`：`illustration_prompt_profile`（默认 nano-banana） - `text_language`：`illustration_text_language`（默认 zh-CN） - `english_terms_whitelist`：`illustration_english_terms_whitelist`（默认空） - `image_provider`：`illustration_image_provider`（默认 xiaomi） - `image_model`：`illustration_image_model`（默认 gemini-3.1-flash-image-preview） - `image_size`：`illustration_image_size`（默认 1K） - `image_base_url`：`illustration_image_base_url`（默认 Xiaomi 接口地址，也支持 Gemini 原生代理） **执行方式**： 1. 优先调用 `zhy-article-illustrator` 的一键流程脚本： ```bash node <zhy-article-illustrator>/scripts/illustrate-article.ts \ --article articles/<slug>/article.md \ --slug <slug> \ --density <illustration_density> \ --aspect-ratio <illustration_aspect_ratio> \ --prompt-profile <illustration_prompt_profile> \ --text-language <illustration_text_language> \ --image-provider <illustration_image_provider> \ --image-model <illustration_image_model> \ [--image-size <illustration_image_size>] \ [--image-base-url <illustration_image_base_url>] \ [--upload] ``` 2. 若 `illustration_english_terms_whitelist` 非空，则为每个术语追加 `--term <value>`，例如： ```bash --term Playwright --term Chromium --term Firefox --term WebKit ``` 3. 默认沿用新版配图策略： - 先生成文章级 `visual-bible.md` - 再生成 `outline.md` 与 `prompts/` - 默认图片内文字为简体中文，仅白名单术语保留英文 - 同一篇文章内所有图片共享统一风格体系 4. 写作技能在集成时应遵循以下字段映射： - `article_path -> --article` - `slug -> --slug` - `illustration_density -> --density` - `illustration_aspect_ratio -> --aspect-ratio` - `illustration_prompt_profile -> --prompt-profile` - `illustration_text_language -> --text-language` - `illustration_image_provider -> --image-provider` - `illustration_image_model -> --image-model` - `illustration_image_size -> --image-size` - `illustration_image_base_url -> --image-base-url` - `illustration_upload=true -> --upload` **输出**： - `illustrated_article_path`: `articles/<slug>/article.illustrated.md` - `illustrations_dir`: `articles/<slug>/illustrations/<slug>/` - `articles/<slug>/illustrations/<slug>/visual-bible.md` - `articles/<slug>/illustrations/<slug>/outline.md` - `articles/<slug>/illustrations/<slug>/prompts/` **失败处理**：单张失败可重试一次；仍失败则记录并继续，最终输出失败清单。若部分图片失败，也应保留 `article.illustrated.md`，并插入图片占位注释。 --- ### Step 7: HTML 主题样式输出（可选，调用 zhy-markdown2wechat） **触发条件**：`with_html_theme=true` **目标**：使用 `zhy-markdown2wechat` 技能将 Markdown 转换为带微信内联样式的 HTML **操作**： 1. 选择输入文件： - 若 `with_illustrations=true` 且 `articles/<slug>/article.illustrated.md` 存在，则使用该文件 - 否则使用 `articles/<slug>/article.md` 2. 将选中的 Markdown 文件记为 `<input_markdown>` 3. 调用 `zhy-markdown2wechat` 技能，执行转换脚本： ```bash node <zhy-markdown2wechat>/scripts/convert.js \ <input_markdown> \ <zhy-markdown2wechat>/resources/themes/default.css \ articles/<slug>/article.zhy.html ``` - 脚本零依赖（纯 Node.js），无需 `npm install`，自动在临时目录处理后清理 - 输出包含 `<section id="MdWechat">` 容器与完整内联 CSS 样式 - 如需换肤，可将第二个参数替换为 `resources/themes/` 下的其他主题文件（`apple.css` / `blue.css` / `dark.css` / `green.css` / `notion.css` / `vibrant.css`） - `<zhy-markdown2wechat>` 表示当前环境中该技能的安装目录，运行时应以实际路径为准 4. 输入文件示例： - 若存在插图版文章：`<input_markdown>=articles/<slug>/article.illustrated.md` - 若不存在插图版文章：`<input_markdown>=articles/<slug>/article.md` **输出**：`html_article_path`（`articles/<slug>/article.zhy.html`） **失败处理**：记录错误并在执行摘要中注明原因，跳过该步骤并继续后续流程 --- ### Step 8: 保存到公众号草稿箱（可选，调用 zhy-wechat-publish） **触发条件**：`post_to_wechat=true` **默认行为**：通过微信官方 API 保存到草稿箱，不做最终发布提交 **前置条件**： - `zhy-wechat-publish` 技能目录下的 `.env` 已配置 `WECHAT_APP_ID` 与 `WECHAT_APP_SECRET` - 运行机器的公网 IP 已加入微信公众号后台 IP 白名单 - 若要自动生成封面，发布技能依赖的生图环境也必须可用（由 `zhy-article-illustrator` 提供） **调用方式**： - 正文必须是带内联样式的 HTML 文件 - 优先使用 Step 7 生成的 `article.zhy.html`；若不存在则跳过本步骤（或先补执行 Step 7） - 默认推荐的稳定入口是直接调用 `wechat_draft.js`： ```bash node <zhy-wechat-publish>/scripts/wechat_draft.js \ --title "文章标题" \ --file "articles/<slug>/article.zhy.html" \ [--author "作者"] \ [--digest "摘要"] \ [--thumb "封面media_id"] \ [--source-url "原文链接"] \ [--need-open-comment "1"] \ [--only-fans-can-comment "1"] ``` - 若希望自动生成封面并发布，也可调用： ```bash node <zhy-wechat-publish>/scripts/publish_with_cover.js \ --article "articles/<slug>/article.md" \ --html "articles/<slug>/article.zhy.html" \ [--title "文章标题"] \ [--author "作者"] \ [--source-url "原文链接"] \ [--need-open-comment "1"] \ [--only-fans-can-comment "1"] ``` - `<zhy-wechat-publish>` 表示当前环境中该技能的安装目录，运行时应以实际路径为准 - `wechat_draft.js` 未提供 `--thumb` 时会自动读取 `.env` 中的 `WECHAT_DEFAULT_THUMB_MEDIA_ID` - `publish_with_cover.js` 会自动从文章中提取标题/摘要、生成单张 16:9 封面、上传封面，并将返回的 `media_id` 作为 `thumb_media_id` - 发布脚本会在上传前自动展开 HTML 中的 `var(--xxx)` 样式变量，避免微信草稿箱丢失颜色与边框样式 - 发布脚本会在上传前自动将正文中的图片上传到微信正文图片接口，并将 `<img src>` 替换为微信返回的图片 URL - 发布脚本会在上传前将原生列表结构降级为“普通段落 + 圆点/编号”，以兼容微信草稿箱再次进入编辑模式时的列表解析问题 **注意**： - 脚本零依赖（纯 Node.js >= 16），无需 `npm install` - 使用 `publish_with_cover.js` 时，需要本机可用 `bun`，因为封面生成会复用现有生图脚本 - 草稿保存后不会自动提交发布，需人工在公众号后台确认 - 标题长度不得超过 64 字符 - 若当前环境没有可用生图配置，优先改用 `wechat_draft.js` 直接上传 HTML，避免自动封面步骤失败 **成功标准**：输出 `上传草稿成功! 草稿 MEDIA_ID: xxx` **失败排障清单**： | 错误信息 | 原因与处理 | |---------|----------| | `[40013] invalid appid` | AppID 错误，检查发布技能目录下的 `.env` | | `[40164] invalid ip` | 当前 IP 未加白名单，将报错中的 IP 加入公众号后台 | | `[40007] invalid media_id` | 封面图 ID 无效，使用 `upload_image.js` 重新上传获取 | | `缺少 Xiaomi/Gemini/OpenAI API Key` | 自动封面生成依赖的生图环境未配置，检查 `zhy-article-illustrator` 相关 `.env` | | `article.zhy.html` 不存在 | Step 7 未执行或失败，检查 `with_html_theme=true` | | 标题过长 | 控制标题 <= 64 字符 | --- ## Data Flow ``` 用户输入（topic, urls?, slug?, search_count?, time_range_days?, ...） ↓ Preflight（确定slug与目录） ↓ 素材搜集（WebSearch + webfetch → evidence.md） ↓ 初稿生成（article.md） ↓ 智能审稿（含可追溯性/标题一致性） ↓ 润色打磨（强制References） ↓ 自动配图（article.illustrated.md + illustrations/） ↓ HTML 主题样式输出（zhy-markdown2wechat → article.zhy.html） ↓ 保存到草稿箱（不提交发布） ``` ## Error Handling | 异常情况 | 处理方式 | |---------|---------| | 搜索无结果 | 提示用户提供更多信息或参考URL | | 参考文章无法访问 | 跳过该URL，继续处理其他素材 | | 初稿质量过低 | 重新生成或提示用户提供更多素材 | | 审稿评分<70 | 建议用户检查主题是否合适 | | 配图失败 | 输出失败清单；可选择补图后再发布 | | HTML 转换失败 | 记录错误并跳过该步骤（Step 7），继续后续流程 | | 发布到草稿箱失败 | 输出排障清单（AppID/IP白名单/封面media_id/标题长度） | ## Example Usage **输入**： ``` topic: "如何提高工作效率" urls: ["https://mp.weixin.qq.com/xxx"] search_count: 5 with_illustrations: true with_html_theme: true post_to_wechat: true ``` **执行流程**： 1. 搜索"如何提高工作效率"相关文章 2. 获取用户提供的参考文章内容 3. 生成初稿（约1500-2500字） 4. 审稿评分：85分 5. 润色优化后保存 **输出**： ``` article_path: articles/how-to-improve-work-efficiency/article.md sources_path: articles/how-to-improve-work-efficiency/sources/evidence.md illustrated_article_path: articles/how-to-improve-work-efficiency/article.illustrated.md illustrations_dir: articles/how-to-improve-work-efficiency/illustrations/how-to-improve-work-efficiency/ html_article_path: articles/how-to-improve-work-efficiency/article.zhy.html word_count: 2150 review_score: 92 wechat_draft_status: success ``` ## Notes - 文章风格应符合公众号调性：轻松、有用、有共鸣 - 避免敏感内容和过度营销 - 保持原创性，不要直接复制素材内容