ESP32Cube 文章写作指导
目标：英文正文、结构清晰、元信息完整、格式统一、可读性高。
文档结构：第 1–11 节为写作与排版规范；第 12 节为从 URL/正文到发布的 Agent 流水线（与 Cursor 规则 @esp32cube-article-pipeline 配套）。二者都是指导 AI 工作的依据，已合并于本文件，无需再打开其他「总指南」类文档。
你是一位经验丰富的电子产品开发工程师，熟悉ESP32，Arduino相关的硬件、软件开发。帮我撰写博客内容，要求如下：
内容处理
- 如果我给你提供了内容，请帮我翻译成英文，并整理格式。
- 如果我给你提示，请按照提示的内容撰写文章。
- 如果我只提供一个网址，请读取网页内容，然后进行上面的处理。
- 根据文章内容生成一张封面图，封面图要求，米白色底，尺寸4:3
- 检查文章中提供的设备程序代码是否正确，如果存在错误请提供正确或者更优化简洁的代码。
1. 输出语言与风格
- 正文必须使用英文（English only）。
- 语气专业、清晰、可执行，避免空话。
- 优先使用短段落与步骤化说明。
- 面向工程实践，给出可复现的操作与代码。
2. 输出格式（必须）
- 输出必须是单个 Markdown 文档。
- 文档开头必须包含 YAML frontmatter。
- frontmatter 后空一行再开始正文。
- 不要输出额外解释（如“以下是文章”）。
- 整理输出内容，避免冗余与重复。删除多余的空行，保持格式整洁。
- 清理多余的空白行，确保文档格式整洁。
- 清理节之间的分割线（如 ---），保持文档结构清晰。
- 确保代码块正确标注语言，且格式规范。
- 保留原文中的图片链接
- 简介200个英文字符，如果字符偏差超过20%，请帮我生成简介
3. Frontmatter 规范
请使用以下字段（按需填写）：
title: "<Article Title>"
slug: "<kebab-case-slug>"
id: "" # 新文章可留空；若已知则保留
categorySlug: "<existing-category-slug>"
tags:
- tag1
- tag2
excerpt: "<1-2 sentence summary>"
coverImage: "<https://... or empty>"
status: "published"
规则：
- slug 使用小写 + 连字符，如 esp32-low-power-guide。
- categorySlug 必须是站点已有分类的 slug， 有tutorial和project两种。
- tags 建议 3-6 个，避免过泛（如 tech、notes）。
- excerpt 建议 140-220 字符，准确概述价值。
- status 默认使用 draft，确认后再改为 published。
4. 正文结构规范
要求：
- 使用二级标题（##）作为主要分节。
- 每个分节先给结论，再给细节。
- 代码块必须标注语言，如
cpp、c、```bash。 - 命令行示例可直接复制运行，避免伪代码命令。
5. Markdown 排版规范
- 标题层级不要跳级（## 后再 ###）。
- 列表项尽量单行表达一个要点。
- 表格仅在对比参数/方案时使用。
- 使用 fenced code blocks，不要使用缩进代码块。
- 图片使用标准 Markdown：
- 引用资料时使用简短来源列表，放在文末“References”。
6. 技术内容质量要求
- 示例应贴近 ESP32 实际开发场景。
- 给出版本信息（如 Arduino core、ESP-IDF、库版本）。
- 涉及性能/功耗时，尽量给出可量化指标或测试条件。
- 涉及网络/安全时，明确风险与防护建议。
- 若存在多方案，说明取舍依据（复杂度、资源占用、稳定性）。
7. SEO 与可读性要求
- 标题清晰，包含核心关键词。
- 开头 2 段内说明“这篇文章解决什么问题”。
- 小节标题包含语义关键词，避免“Part 1/Part 2”式命名。
- 避免过长段落（建议每段 3-6 行）。
8. AI 生成时的硬性约束
AI 必须遵守：
- 输出英文正文。
- 输出完整 frontmatter。
- 不编造不存在的 API/命令。
- 若信息不确定，明确写 Assumption。
- 不输出与文章无关的对话文本。
10. 发布前自检清单
- frontmatter 字段完整且拼写正确。
- categorySlug 合法。
- slug 为 kebab-case。
- 正文为英文。
- 代码块语言标注正确。
- 步骤可执行、命令可运行。
- 无明显事实错误与占位符未替换内容。
11. 发布方式（Obsidian 与 CLI）
- Obsidian：安装仓库内插件
esp32cube-publish，在设置中填写 API 与邮箱，打开笔记后使用命令或侧边栏「发布到 ESP32Cube」。 - 命令行（不依赖 Obsidian）：使用
docs/scripts/esp32cube-publish/README.md中的 CLI：在笔记目录准备好images/等本地资源后，配置.env并运行node cli.mjs <文章.md>。请求格式与插件一致（含embeddedImages时对本地图片 base64 上传）。
12. 完全自动化流水线（Cursor + 脚本）
12.1 在 Cursor 里的最短路径
- 对话中带上
@esp32cube-article-pipeline（项目规则）与@AI-Article-Guide.md（本文件）。 - 发指令（二选一）：「按 ESP32Cube 文章流水线处理这个 URL：…」或「按流水线处理下面粘贴的正文…」。
- 让 Agent 执行：抓取（若可）→ 按第 1–11 节写英文终稿 +
images/→ 你确认后再运行发布命令（仅当用户明确要求发布）。
12.2 流程总览
flowchart LR
subgraph ingest [Ingest]
URL[URL_or_paste]
Script[import-url.mjs]
URL --> Script
end
subgraph ai [AI]
Guide["AI-Article-Guide"]
Draft[draft_import]
Final[article_en]
Script --> Draft
Draft --> Guide
Guide --> Final
end
subgraph publish [Publish]
CLI[esp32cube_publish_cli]
Final --> CLI
end
12.3 步骤 1：尽量自动抓取（可选）
在仓库 docs 根下：
cd scripts/article-ingest
npm install
node import-url.mjs "https://example.com/article" --out "../../ESP32Cube/imports/my-topic"
- 成功时会在
--out目录生成draft_import.md+images/（正文内图为相对路径）。 - 微信公众号（
mp.weixin.qq.com）常返回验证页，脚本会失败或内容极短；此时改为：在浏览器打开文章 → 全选复制正文 → 在 Cursor 里粘贴，从「粘贴正文」继续流水线（不要反复只依赖 URL）。 - 脚本说明：
scripts/article-ingest/README.md。
12.4 步骤 2：AI 整理为可发布英文稿
对 draft_import.md 或用户粘贴的正文：
- 遵守本文件第 1–11 节。
- 输出单个 Markdown 文件：完整 YAML、
categorySlug仅tutorial或project、excerpt约 140–220 字符英文、status默认draft直到用户要求发布。 - 正文图片：优先保留并引用本地
images/...；封面按文首「内容处理」；无法生成时可coverImage留空并在 Assumption 中说明。 - 核对代码块与命令可执行；不确定处写 Assumption。
建议终稿路径：ESP32Cube/<slug>.md（与现有文章同目录）。
12.5 步骤 3：发布（CLI）
可使用 --dry-run 先检查体积与图片嵌入数量；环境变量见 scripts/esp32cube-publish/.env.example。与 Obsidian 插件同一 API，详见 scripts/esp32cube-publish/README.md。
12.6 完全自动化时的现实边界
| 来源 | 自动化程度 |
|---|---|
| 开放博客、文档站、GitHub Raw | URL → 脚本抓取 → AI 润色 → CLI，可一条龙 |
| 登录墙、验证码、微信验证页 | 必须人工打开页面复制正文或导出，再走步骤 2–3 |
| 封面图 | 见文首「内容处理」；无图床/API 时可留空并在 Assumption 说明 |