# wechat-article-maker

> 智能创作并发布微信公众号文章。支持内容理解、链接分析、Markdown转换、图片清洗、样式处理和一键发布。当用户提到"创作公众号文章"、"发布文章链接"、"生成微信文章"、"post to wechat"时使用。

- Author: root
- Repository: alpha-hecoding/awesome-skills
- Version: 20260209164906
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-09
- Source: https://github.com/alpha-hecoding/awesome-skills
- Web: https://mule.run/skillshub/@@alpha-hecoding/awesome-skills~wechat-article-maker:20260209164906

---

---
name: wechat-article-maker
description: 智能创作并发布微信公众号文章。支持内容理解、链接分析、Markdown转换、图片清洗、样式处理和一键发布。当用户提到"创作公众号文章"、"发布文章链接"、"生成微信文章"、"post to wechat"时使用。
---

# 微信公众号文章创作与发布

## 语言

**匹配用户语言**：使用用户所用的语言进行回应。用户用中文则用中文回应，用英文则用英文回应。

## 脚本目录

**Agent 执行**：确定此 SKILL.md 目录为 `SKILL_DIR`，然后使用 `${SKILL_DIR}/scripts/<name>.ts`。

| 脚本 | 用途 |
|------|------|
| `scripts/wechat-api.ts` | 文章发布（API 方式，推荐） |
| `scripts/wechat-article.ts` | 文章发布（浏览器方式） |
| `scripts/wechat-browser.ts` | 图文发布（图文消息） |
| `scripts/generate-cover.ts` | 生成封面图（无系统依赖） |
| `scripts/md-to-wechat.ts` | Markdown 转 HTML |
| `scripts/md/render.ts` | Markdown 渲染引擎（支持主题） |
| `scripts/install-deps.sh` | 依赖安装脚本 |

## 依赖安装（首次使用）

本技能需要安装 Node.js 依赖包。首次使用前请执行：

```bash
cd ${SKILL_DIR}/scripts
./install-deps.sh
```

或手动安装：

```bash
cd ${SKILL_DIR}/scripts
npm install
# 或使用 bun（更快）
bun install
```

### 依赖说明

**必需依赖**（自动安装）：
- `markdown-it` - Markdown 渲染引擎
- `juice` - CSS 内联转换

**可选依赖**（用于封面图生成）：
- `@napi-rs/canvas` - 高性能图片生成（推荐）
- `sharp` - 图片处理库

**降级策略**：如果可选依赖未安装，`generate-cover.ts` 会自动生成 SVG 格式的封面图（微信也支持）。

## 功能概述

本技能提供完整的微信公众号文章工作流：

1. **内容创作模式**：输入文本内容，智能理解、生成文章
2. **链接发布模式**：输入文章链接，下载、处理并发布
3. **Markdown 转换**：内置 Markdown 到 HTML 转换，支持多主题
4. **图片处理**：自动下载、清洗元数据、符合微信规范
5. **样式转换**：自动将 CSS 转为内联样式
6. **一键发布**：支持 API（快速）和浏览器（可视化）两种方式

## 偏好设置（EXTEND.md）

使用 Bash 检查 EXTEND.md 存在性（优先级顺序）：

```bash
# 检查项目级别
test -f .awesome-skills/wechat-article-maker/EXTEND.md && echo "project"

# 检查用户级别（跨平台：$HOME 在 macOS/Linux/WSL 上都可用）
test -f "$HOME/.awesome-skills/wechat-article-maker/EXTEND.md" && echo "user"
```

┌────────────────────────────────────────────────────────────┬───────────────────┐
│                            路径                            │       位置        │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ .awesome-skills/wechat-article-maker/EXTEND.md               │ 项目目录          │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.awesome-skills/wechat-article-maker/EXTEND.md         │ 用户主目录        │
└────────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  结果     │                                  操作                                     │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 找到      │ 读取、解析、应用设置                                                      │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 未找到    │ 使用默认值                                                                │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md 支持**：默认主题 | 默认发布方法（api/browser）| 默认作者 | Chrome 配置文件路径

## 工作流程选择

根据用户输入自动选择工作流程：

| 输入类型 | 识别方式 | 工作流程 |
|---------|---------|---------|
| 纯文本内容 | 不包含链接 | 内容创作流程 |
| 文本 + 参考链接 | 包含链接，但主体是文本描述 | 内容创作流程（含链接分析）|
| 单个文章链接 | 仅包含 URL，或明确说"发布这篇文章" | 链接发布流程 |
| Markdown 文件路径 | 以 `.md` 结尾的文件路径 | Markdown 转换发布流程 |
| HTML 文件路径 | 以 `.html` 结尾的文件路径 | 直接发布流程 |

---

## 流程 1: 内容创作与发布

当用户输入文本内容（可选包含参考链接）时使用此流程。

### 创作进度清单

复制此清单并在完成时勾选：

```
内容创作进度：
- [ ] 步骤 0: 加载偏好设置
- [ ] 步骤 1: 内容分析与链接提取
- [ ] 步骤 2: 链接内容获取与理解
- [ ] 步骤 3: 询问创作偏好
- [ ] 步骤 4: 生成 Markdown 文章
- [ ] 步骤 5: 用户确认与优化
- [ ] 步骤 6: 转换为 HTML
- [ ] 步骤 7: 准备封面图
- [ ] 步骤 8: 发布到微信
- [ ] 步骤 9: 完成报告
```

### 步骤 0: 加载偏好设置

检查并加载 EXTEND.md 设置（见上方偏好设置部分）。

### 步骤 1: 内容分析与链接提取

分析用户输入：

1. **提取所有链接**：

```bash
# 提取 HTTP/HTTPS 链接
echo "$user_input" | grep -oE 'https?://[^\s]+' > /tmp/links.txt
```

2. **判断内容类型**：
   - 如果仅有单个链接且无其他文本 → 转到**流程 2: 链接发布流程**
   - 如果有文本内容（可选链接）→ 继续内容创作流程

### 步骤 2: 链接内容获取与理解

**如果内容中包含参考链接**：

1. **获取每个链接的内容**：

```typescript
// 使用 WebFetch 获取并分析
for (const url of links) {
  const content = await WebFetch(url, `
    请提取并总结以下信息：
    1. 文章标题
    2. 作者（如有）
    3. 核心观点（3-5个要点）
    4. 关键数据或案例
    5. 可引用的金句

    以结构化格式返回，便于后续引用。
  `);
}
```

2. **整理参考资料**：
   - 为每个链接创建摘要卡片
   - 标注关键引用点
   - 记录可用图片或数据

### 步骤 3: 询问创作偏好

使用 AskUserQuestion 询问用户偏好：

```
文章创作配置

问题1：文章风格
header: "风格"
选项：
- 专业分析 - 深度解读，适合技术或行业分析（推荐）
- 轻松科普 - 通俗易懂，适合大众读者
- 教程指南 - 步骤清晰，适合实操性内容
- 观点评论 - 表达看法，适合热点评论

问题2：文章长度
header: "长度"
选项：
- 短文（800-1200字）- 快速阅读
- 中等（1500-2500字）- 平衡深度与可读性（推荐）
- 长文（3000字+）- 深度长文

问题3：参考资料处理（如有链接）
header: "引用方式"
选项：
- 深度引用和分析 - 详细解读原文观点（推荐）
- 简要提及和链接 - 点到为止
- 仅作背景参考 - 不明确引用
```

### 步骤 4: 生成 Markdown 文章

基于用户输入、参考资料和偏好生成文章：

1. **文章结构**：

```markdown
---
title: 文章标题
author: 作者名（从 EXTEND.md 或默认值）
summary: 文章摘要（120字以内）
featureImage: 封面图路径（可选）
date: YYYY-MM-DD
---

# 文章标题

引言段落，吸引读者注意...

## 第一部分标题

段落内容...

![图片描述](图片路径)

## 第二部分标题

段落内容...

> 引用重要观点或数据

## 结论

总结性段落...

---

**参考资料**：
- [文章标题](链接)
```

2. **保存文件**：

```bash
# 生成 slug（文件名）
title="文章标题"
slug=$(echo "$title" | \
  iconv -t ascii//TRANSLIT 2>/dev/null | \
  tr '[:upper:]' '[:lower:]' | \
  tr ' ' '-' | \
  tr -cd '[:alnum:]-' | \
  cut -c1-50)

# 创建目录并保存
output_dir="wechat-articles/$(date +%Y-%m-%d)"
mkdir -p "$output_dir"
echo "$article_content" > "$output_dir/$slug.md"
```

3. **展示给用户**：

```
✓ 文章已生成

📄 标题：$title
📏 长度：约 $word_count 字
📁 保存位置：$output_dir/$slug.md

[文章预览内容...]

请选择下一步操作...
```

### 步骤 5: 用户确认与优化

使用 AskUserQuestion 询问：

```
文章已生成，请选择操作

header: "下一步"
选项：
- 直接发布 - 转换为 HTML 并发布到微信（推荐）
- 修改内容 - 说明需要调整的部分
- 重新生成 - 使用不同风格或角度
- 仅保存文件 - 不发布，稍后手动处理
```

**如果用户选择修改**：
1. 收集修改意见
2. 更新文章内容
3. 重新保存并展示
4. 再次询问下一步

**如果用户选择重新生成**：
- 返回步骤 3，重新询问偏好
- 使用不同的创作角度

### 步骤 6: 转换为 HTML

使用内置的 Markdown 渲染引擎转换：

1. **询问主题**（如未在 EXTEND.md 中指定）：

| 主题 | 描述 |
|------|------|
| `default` | 经典主题 - 传统排版，标题居中带底边，二级标题白字彩底 |
| `grace` | 优雅主题 - 文字阴影，圆角卡片，精致引用块（推荐）|
| `simple` | 简洁主题 - 现代极简风，不对称圆角，清爽留白 |

2. **执行转换**：

```bash
npx -y bun ${SKILL_DIR}/scripts/md-to-wechat.ts \
  "$output_dir/$slug.md" \
  --theme grace \
  --output "$output_dir"
```

3. **解析输出 JSON**：

```json
{
  "title": "文章标题",
  "author": "作者",
  "summary": "摘要",
  "htmlPath": "路径/to/article.html",
  "contentImages": [
    {
      "placeholder": "WECHATIMGPH_1",
      "localPath": "/path/to/image1.jpg",
      "originalPath": "原始路径"
    }
  ]
}
```

### 步骤 7: 准备封面图

**检查封面图来源**（优先级顺序）：

1. Frontmatter 字段：`featureImage`, `coverImage`, `cover`, `image`
2. 文章中的第一张图片
3. 自动生成

**如果没有封面图**，询问用户：

```
封面图设置

header: "封面来源"
选项：
- 自动生成 - 基于文章标题生成渐变背景封面（推荐）
- 使用首图 - 使用文章中第一张图片
- 提供路径 - 指定本地文件或 URL
- 暂不设置 - 稍后手动添加
```

**如果选择自动生成**：

```bash
# 使用 Node.js 脚本生成（无系统依赖）
npx -y bun ${SKILL_DIR}/scripts/generate-cover.ts \
  --title "$title" \
  --output "$output_dir/$slug-cover.jpg" \
  --gradient-start "#667eea" \
  --gradient-end "#764ba2"
```

**封面要求**：
- 格式：JPEG, PNG, GIF 或 WebP
- 推荐尺寸：900x500px（2:1 比例）
- 文件大小：< 2MB

### 步骤 8: 发布到微信

询问发布方式：

```
发布方式选择

header: "发布方法"
选项：
- API 方式 - 快速发布，需要 API 凭证（推荐）
- 浏览器方式 - 可视化操作，需要 Chrome
- 仅输出 HTML - 保存文件，稍后手动发布
```

#### 选项 A: API 方式发布

1. **检查 API 凭证**：

```bash
# 检查项目级别
test -f .awesome-skills/.env && grep -q "WECHAT_APP_ID" .awesome-skills/.env && echo "project"

# 检查用户级别
test -f "$HOME/.awesome-skills/.env" && grep -q "WECHAT_APP_ID" "$HOME/.awesome-skills/.env" && echo "user"
```

2. **如果凭证缺失**，引导设置：

```
微信 API 凭证未找到

获取凭证步骤：
1. 访问 https://mp.weixin.qq.com
2. 进入：开发 → 基本配置
3. 复制 AppID 和 AppSecret

保存位置？
A) 项目级别：.awesome-skills/.env（仅此项目）
B) 用户级别：~/.awesome-skills/.env（所有项目）
```

创建 `.env` 文件：

```bash
WECHAT_APP_ID=<用户输入>
WECHAT_APP_SECRET=<用户输入>
```

3. **执行发布**：

```bash
npx -y bun ${SKILL_DIR}/scripts/wechat-api.ts \
  "$output_dir/$slug.html" \
  --title "$title" \
  --summary "$summary" \
  --cover "$cover_image" \
  --inline-css
```

**重要**：`--inline-css` 参数将 CSS 转为内联样式，微信公众号不支持 `<style>` 标签。

#### 选项 B: 浏览器方式发布

```bash
npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts \
  --html "$output_dir/$slug.html" \
  --title "$title" \
  --summary "$summary"
```

**首次运行**：会打开 Chrome 浏览器，需要扫码登录微信公众号。

#### 选项 C: 仅输出 HTML

```bash
echo "✓ HTML 文件已保存至：$output_dir/$slug.html"
echo ""
echo "文件包含："
echo "• 内联样式（符合微信规范）"
echo "• 完整的文章内容"
echo "• 本地图片路径"
```

### 步骤 9: 完成报告

发布成功后，显示摘要：

```
✓ 微信公众号文章创作与发布完成！

创作信息：
• 输入：用户文本内容
• 参考链接：$link_count 个
• 文章风格：$style
• 文章长度：$word_count 字

发布信息：
• 标题：$title
• 作者：$author
• 摘要：$summary
• 主题：$theme
• 图片：$image_count 张
• 封面：$cover_source

发布方式：API / 浏览器

结果：
✓ 草稿已保存到微信公众号
• media_id: $media_id

下一步：
→ 管理草稿：https://mp.weixin.qq.com（登录后进入「内容管理」→「草稿箱」）

生成的文件：
• $output_dir/$slug.md（Markdown 源文件）
• $output_dir/$slug.html（HTML 文件）
• $output_dir/$slug-cover.jpg（封面图）
```

---

## 流程 2: 链接文章发布

当用户输入单个文章链接时使用此流程。

### 发布进度清单

复制此清单并在完成时勾选：

```
链接发布进度：
- [ ] 步骤 0: 加载偏好设置
- [ ] 步骤 1: 链接验证
- [ ] 步骤 2: 文章下载与解析
- [ ] 步骤 3: 图片下载与清洗
- [ ] 步骤 4: 样式转换（CSS 内联）
- [ ] 步骤 5: 用户确认
- [ ] 步骤 6: 准备封面图
- [ ] 步骤 7: 执行发布
- [ ] 步骤 8: 完成报告
```

### 步骤 0: 加载偏好设置

检查并加载 EXTEND.md 设置。

### 步骤 1: 链接验证

验证链接可访问性：

```bash
# 检查链接状态
status_code=$(curl -sI -w "%{http_code}" -o /dev/null "$url")
if [ "$status_code" = "200" ]; then
  echo "链接有效"
else
  echo "链接无法访问，状态码: $status_code"
fi
```

### 步骤 2: 文章下载与解析

使用 WebFetch 获取文章内容：

```typescript
const article = await WebFetch(url, `
请提取以下信息并以 JSON 格式返回：

{
  "title": "文章标题",
  "author": "作者（如果有）",
  "summary": "文章摘要或简介（120字以内）",
  "content": "HTML 格式的正文内容，保留原始样式和结构",
  "images": ["图片URL数组"],
  "featureImage": "封面图URL（如果有）",
  "publishDate": "发布日期（如果有）"
}

注意：
- content 需要包含完整的 HTML 标签和样式
- images 包含文章中所有的图片URL
- 保留原文的段落、标题、列表等结构
`);
```

### 步骤 3: 图片下载与清洗

1. **创建临时目录**：

```bash
temp_dir="wechat-temp/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$temp_dir/images"
```

2. **下载所有图片**：

```bash
# 解析图片URL数组并下载
image_index=1
for img_url in "${images[@]}"; do
  # 获取文件扩展名
  ext="${img_url##*.}"
  ext="${ext%%\?*}"  # 移除URL参数

  # 下载图片
  output_file="$temp_dir/images/image_${image_index}.${ext}"
  curl -L -o "$output_file" "$img_url" 2>/dev/null

  image_index=$((image_index + 1))
done
```

3. **图片元数据清洗**：

脚本 `wechat-api.ts` 会自动执行以下清洗：

- **检测 JPEG 图片**中的非标准元数据
- **清除 AIGC/Coze 标记**（微信不支持）
- **保留有效的 EXIF 数据**和图像内容
- **自动重试**：如果上传失败（错误码 40113），强制清洗后重试

算法（参考 `scripts/wechat-api.ts:105-180`）：

```typescript
function cleanImageMetadata(buffer: Buffer): Buffer {
  // 检查 JPEG 签名
  if (buffer[0] !== 0xff || buffer[1] !== 0xd8) return buffer;

  // 检测 AIGC 标记
  const headerStr = buffer.slice(0, 2048).toString('binary');
  const hasAigcMarker = headerStr.includes('AIGC{') || headerStr.includes('Coze');

  if (!hasAigcMarker) return buffer;

  // 跳过非标准 APP 段（0xeb, 0xec 等）
  // 保留标准段（APP0-APP9, DQT, SOF 等）
  // 返回清洗后的 buffer
}
```

### 步骤 4: 样式转换（CSS 内联）

**关键步骤**：微信公众号不支持 `<style>` 标签，必须将 CSS 转为内联样式。

1. **保存原始 HTML**：

```bash
echo "$html_content" > "$temp_dir/original.html"
```

2. **执行 CSS 内联转换**：

```bash
# 使用 wechat-api.ts 的内联转换功能
# 注意：这里先生成处理后的 HTML，不立即发布
npx -y bun ${SKILL_DIR}/scripts/wechat-api.ts \
  "$temp_dir/original.html" \
  --inline-css \
  --output "$temp_dir/processed.html" \
  --dry-run
```

3. **替换图片路径**：

```bash
# 将远程图片URL替换为本地路径
for i in {1..${#images[@]}}; do
  sed -i "s|${images[$i-1]}|$temp_dir/images/image_$i.jpg|g" "$temp_dir/processed.html"
done
```

### 步骤 5: 用户确认

展示处理结果并询问：

```
文章处理完成

📄 标题：$title
✍️ 作者：$author
📝 摘要：$summary
🌐 原文：$original_url
🖼️ 图片：共 $image_count 张（已下载并清洗元数据）
🎨 样式：已转换为内联样式（符合微信规范）

HTML 已保存至：$temp_dir/processed.html

请选择操作
```

使用 AskUserQuestion：

```
header: "发布选项"
选项：
- 直接发布（API）- 快速发布到草稿箱（推荐）
- 浏览器发布 - 打开浏览器可视化操作
- 仅输出 HTML - 保存文件，稍后手动处理
- 取消 - 不保存
```

### 步骤 6: 准备封面图

与流程 1 的步骤 7 相同。

如果原文有 `featureImage`，优先使用；否则询问用户选择。

### 步骤 7: 执行发布

根据用户选择执行：

#### 选项 A: 直接发布（API）

```bash
npx -y bun ${SKILL_DIR}/scripts/wechat-api.ts \
  "$temp_dir/processed.html" \
  --title "$title" \
  --summary "$summary" \
  --cover "$cover_image" \
  --inline-css
```

**API 方式特性**：
- ✓ 自动下载远程图片
- ✓ 自动清洗图片元数据（AIGC/Coze 标记）
- ✓ 如果上传失败（40113），强制清洗后重试
- ✓ 支持格式：JPEG, PNG, GIF, WebP

#### 选项 B: 浏览器发布

```bash
npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts \
  --html "$temp_dir/processed.html" \
  --title "$title" \
  --summary "$summary"
```

#### 选项 C: 仅输出 HTML

```bash
# 复制到永久位置
output_path="wechat-articles/$(date +%Y-%m-%d)/$slug.html"
mkdir -p "$(dirname "$output_path")"
cp "$temp_dir/processed.html" "$output_path"
cp -r "$temp_dir/images" "$(dirname "$output_path")/"

echo "✓ HTML 已保存至：$output_path"
echo "✓ 图片已保存至：$(dirname "$output_path")/images/"
```

### 步骤 8: 完成报告

```
✓ 链接文章发布完成！

原文信息：
• 链接：$original_url
• 标题：$title
• 作者：$author

处理信息：
• 下载并转换 HTML
• 清洗 $image_count 张图片元数据
• 转换样式为内联格式
• 生成封面图：$cover_source

发布信息：
• 方式：API / 浏览器
• 主题：保留原样式
• 状态：✓ 草稿已保存

结果：
• media_id: $media_id

下一步：
→ 管理草稿：https://mp.weixin.qq.com（登录后进入「内容管理」→「草稿箱」）

生成的文件：
• $output_path（处理后的 HTML）
• $(dirname "$output_path")/images/（清洗后的图片）
```

---

## 流程 3: Markdown 文件发布

当用户提供 `.md` 文件路径时使用此流程。

### 快速发布

```bash
# 一键转换并发布
npx -y bun ${SKILL_DIR}/scripts/md-to-wechat.ts \
  "$markdown_file" \
  --theme grace \
  --output ./output

# 然后使用 API 发布
npx -y bun ${SKILL_DIR}/scripts/wechat-api.ts \
  "$html_output" \
  --inline-css \
  --cover "$cover_image"
```

### 步骤说明

1. **解析 Markdown**：提取 frontmatter（title, author, summary 等）
2. **转换为 HTML**：应用主题样式
3. **处理图片**：下载远程图片，替换为本地路径
4. **发布**：同流程 1 的步骤 8

---

## 流程 4: HTML 文件直接发布

当用户提供 `.html` 文件路径时使用此流程。

### 快速发布

```bash
# 直接发布（自动内联 CSS）
npx -y bun ${SKILL_DIR}/scripts/wechat-api.ts \
  "$html_file" \
  --title "文章标题" \
  --summary "摘要" \
  --cover "$cover_image" \
  --inline-css
```

**注意**：必须使用 `--inline-css` 参数，否则样式会丢失。

---

## 图文发布（图文消息）

用于发布短内容 + 多张图片（最多 9 张）。

### 使用方法

```bash
# 从 Markdown 文件发布
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts \
  --markdown article.md \
  --images ./images/

# 直接指定内容和图片
npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts \
  --title "标题" \
  --content "内容" \
  --image img1.png \
  --image img2.png \
  --submit
```

### 参数说明

| 参数 | 描述 |
|------|------|
| `--markdown <path>` | Markdown 文件 |
| `--title <text>` | 标题 |
| `--content <text>` | 内容文字 |
| `--image <path>` | 图片路径（可多次使用）|
| `--images <dir>` | 图片目录 |
| `--submit` | 自动提交 |

详见：[references/image-text-posting.md](references/image-text-posting.md)

---

## 主题样式

内置三种主题（位于 `scripts/md/themes/`）：

### default - 经典主题

- 传统排版风格
- 标题居中，带底边装饰
- 二级标题：白字彩底
- 适合：正式文章、行业报告

### grace - 优雅主题（推荐）

- 文字带柔和阴影
- 圆角卡片式引用块
- 精致的列表样式
- 适合：科普文章、个人博客

### simple - 简洁主题

- 现代极简风格
- 不对称圆角设计
- 清爽留白
- 适合：教程、短文

### 自定义主题

1. 在 `scripts/md/themes/` 创建新的 CSS 文件
2. 基于 `base.css` 扩展样式
3. 使用 `--theme <name>` 参数应用

---

## 配置与环境

### 环境变量

从以下位置加载配置（优先级从高到低）：

1. 环境变量
2. `<cwd>/.awesome-skills/.env`
3. `~/.awesome-skills/.env`

必需的环境变量（API 发布方式）：

```bash
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
```

可选的环境变量：

```bash
WECHAT_BROWSER_CHROME_PATH=/path/to/chrome  # 自定义 Chrome 路径
```

### EXTEND.md 配置示例

```markdown
# wechat-article-maker 配置

## 默认设置

- 主题：grace
- 发布方式：api
- 作者：宝玉
- Chrome 配置文件：~/.chrome-wechat

## 自动操作

- 自动生成封面：true
- 自动清洗图片：true
- 自动内联样式：true

## 创作偏好

- 默认文章风格：专业分析
- 默认文章长度：中等（1500-2500字）
- 默认引用方式：深度引用和分析
```

---

## 技术细节

### Markdown 渲染引擎

使用 `markdown-it` 及扩展（位于 `scripts/md/`）：

- **基础渲染**：`render.ts`
- **扩展插件**：
  - `alert.ts` - GitHub 风格提示块
  - `footnotes.ts` - 脚注支持
  - `katex.ts` - 数学公式
  - `toc.ts` - 目录生成
  - `infographic.ts` - 信息图
  - `ruby.ts` - 注音
  - `slider.ts` - 滑块
  - `plantuml.ts` - UML 图表

### 图片处理算法

**元数据清洗**（`scripts/wechat-api.ts:105-180`）：

1. 检查 JPEG 文件签名（0xFFD8）
2. 扫描前 2KB，检测 AIGC/Coze 标记
3. 如果检测到非标准元数据：
   - 跳过非标准 APP 段（0xEB-0xEF）
   - 保留标准段（APP0-APP9, DQT, SOF, DHT 等）
4. 重构 JPEG 文件，只包含标准段

**自动重试逻辑**：

```typescript
try {
  // 尝试上传原始图片
  await uploadImage(imageBuffer);
} catch (error) {
  if (error.code === 40113) {  // 不支持的文件类型
    // 强制清洗并重试
    const cleanedBuffer = cleanImageMetadata(imageBuffer);
    await uploadImage(cleanedBuffer);
  }
}
```

### CSS 内联转换

使用 `juice` 或类似库将 CSS 规则转换为内联样式：

**之前**：
```html
<style>
  h1 { color: blue; font-size: 24px; }
</style>
<h1>标题</h1>
```

**之后**：
```html
<h1 style="color: blue; font-size: 24px;">标题</h1>
```

**为什么需要**：微信公众号编辑器不支持 `<style>` 标签，只接受内联样式。

### 封面图生成

**方式 1: 纯 Node.js（无系统依赖）**

脚本：`scripts/generate-cover.ts`

```bash
npx -y bun ${SKILL_DIR}/scripts/generate-cover.ts \
  --title "文章标题" \
  --output cover.jpg \
  --gradient-start "#667eea" \
  --gradient-end "#764ba2" \
  --width 900 \
  --height 500
```

特性：
- ✓ 无需 ImageMagick
- ✓ 支持多种图片库（@napi-rs/canvas、sharp、SVG）
- ✓ 自动换行长标题
- ✓ 可自定义颜色和尺寸
- ✓ 跨平台（Node.js/Bun）

**方式 2: ImageMagick（如已安装）**

```bash
convert -size 900x500 \
  -define gradient:angle=135 \
  gradient:'#667eea'-'#764ba2' \
  -gravity center \
  -font "DejaVu-Sans-Bold" \
  -pointsize 48 \
  -fill white \
  -annotate +0-30 "标题第一行" \
  -pointsize 36 \
  -annotate +0+30 "标题第二行" \
  cover.jpg
```

---

## 故障排查

| 问题 | 解决方案 |
|------|---------|
| 依赖未安装 | 运行 `cd ${SKILL_DIR}/scripts && ./install-deps.sh` |
| Cannot find module 'markdown-it' | 依赖未安装，运行安装脚本 |
| 封面图生成 SVG 而非 PNG/JPEG | 可选依赖未安装，运行 `npm install @napi-rs/canvas` 或接受 SVG 格式 |
| 链接无法访问 | 检查网络连接，尝试使用代理或 VPN |
| 图片上传失败 (40113) | 自动触发元数据清洗，无需手动处理 |
| 样式丢失 | 确保使用了 `--inline-css` 参数 |
| API 错误 40001 | access_token 无效或过期，检查 API 凭证 |
| API 错误 40164 (invalid ip) | 在微信公众号后台添加服务器 IP 到白名单：<br/>mp.weixin.qq.com → 开发 → 基本配置 → IP白名单 |
| Chrome 未找到 | 设置环境变量 `WECHAT_BROWSER_CHROME_PATH` |
| 标题/摘要缺失 | 手动指定 `--title` 和 `--summary` 参数 |
| 粘贴失败（浏览器方式）| 检查系统剪贴板权限 |
| Markdown 转换错误 | 检查 Markdown 语法，确保 frontmatter 格式正确 |

---

## 最佳实践

### 1. 内容创作

- ✓ 提供清晰的创作意图和目标读者
- ✓ 引用链接时说明如何使用（深度分析 vs 简要提及）
- ✓ 预览后再发布，避免返工
- ✓ 保存 Markdown 源文件，便于后续修改

### 2. 链接发布

- ✓ 确认链接可访问（避免需要登录的页面）
- ✓ 检查原文图片质量（模糊图片建议替换）
- ✓ 优先使用 API 方式（快速可靠）
- ✓ 发布前预览处理后的 HTML

### 3. 样式与排版

- ✓ 专业文章用 `default` 主题
- ✓ 大众内容用 `grace` 主题（推荐）
- ✓ 教程类用 `simple` 主题
- ✓ 确保图片清晰度（推荐 2x 分辨率）
- ✓ 封面图使用 2:1 比例（900x500px）

### 4. 发布流程

- ✓ 首次使用先配置 API 凭证
- ✓ 发布前在草稿箱预览
- ✓ 保留源文件（markdown/html）以便后续修改
- ✓ 定期备份已发布的文章

### 5. 图片处理

- ✓ 使用高质量原图（避免二次压缩）
- ✓ 图片尺寸适中（宽度 800-1200px）
- ✓ 文件大小控制在 1MB 以内
- ✓ 如有 AIGC 图片，让脚本自动清洗

---

## 功能对比

| 功能 | 内容创作 | 链接发布 | Markdown 发布 | HTML 发布 | 图文发布 |
|------|---------|---------|--------------|----------|---------|
| 输入类型 | 文本 + 链接 | 单个链接 | .md 文件 | .html 文件 | 短文 + 图片 |
| 内容理解 | ✓ | ✓ | ✗ | ✗ | ✗ |
| 文章生成 | ✓ | ✗ | ✗ | ✗ | ✗ |
| Markdown 转换 | ✓ | ✗ | ✓ | ✗ | ✓ |
| 主题样式 | ✓ | 保留原样 | ✓ | 保留原样 | ✗ |
| 图片清洗 | ✓ | ✓ | ✓ | ✓ | ✗ |
| CSS 内联 | ✓ | ✓ | ✓ | ✓ | ✗ |
| 封面生成 | ✓ | ✓ | ✓ | ✓ | ✗ |
| API 发布 | ✓ | ✓ | ✓ | ✓ | ✗ |
| 浏览器发布 | ✓ | ✓ | ✓ | ✓ | ✓ |
| 适用场景 | 原创内容 | 转载/分享 | 本地文章 | 现成 HTML | 图片展示 |

---

## 使用示例

### 示例 1: 创作新文章（纯文本）

```
用户：创作一篇关于 AI 编程助手发展趋势的文章

Agent：
✓ 分析内容类型 → 纯文本创作模式
✓ 询问文章风格、长度 → 用户选择"专业分析"、"中等"
✓ 生成文章并展示
✓ 用户确认后转换为 HTML（grace 主题）
✓ 自动生成封面图
✓ 使用 API 发布到草稿箱

结果：
• 文章保存至 wechat-articles/2026-02-09/ai-coding-assistant-trends.md
• HTML 输出至 wechat-articles/2026-02-09/ai-coding-assistant-trends.html
• 封面图：wechat-articles/2026-02-09/ai-coding-assistant-trends-cover.jpg
• 微信草稿箱 media_id: abc123...
```

### 示例 2: 基于链接创作

```
用户：基于这篇文章创作一篇公众号文章，深度分析其中的观点：
https://example.com/ai-future

Agent：
✓ 提取链接并获取内容
✓ 整理关键观点和数据
✓ 询问创作方向 → 用户选择"专业分析"、"深度引用"
✓ 生成文章，引用原文 3 个核心观点，加入自己的分析
✓ 用户确认后发布

结果：
• 生成了 2300 字的深度分析文章
• 引用了原文 3 个观点和 2 个数据
• 添加了参考资料链接
• 已发布到微信草稿箱
```

### 示例 3: 直接发布链接文章

```
用户：发布这篇文章到公众号：https://blog.example.com/great-article

Agent：
✓ 识别为链接发布模式
✓ 下载文章 HTML 和 5 张图片
✓ 清洗图片元数据（检测到 2 张含 AIGC 标记，已清洗）
✓ 转换样式为内联格式
✓ 展示处理结果
✓ 用户确认"直接发布"
✓ 使用 API 发布

结果：
• 处理后 HTML：wechat-temp/20260209-153000/processed.html
• 清洗后图片：wechat-temp/20260209-153000/images/ (5张)
• 微信草稿箱 media_id: xyz789...
```

### 示例 4: Markdown 文件发布

```
用户：发布这个 Markdown 文件：./posts/my-article.md

Agent：
✓ 读取文件，解析 frontmatter
✓ 询问主题 → 用户选择 "grace"
✓ 转换为 HTML，应用主题样式
✓ 下载文章中的 3 张远程图片
✓ 自动生成封面图（基于标题）
✓ 发布到微信

结果：
• HTML 输出至 ./posts/my-article.html
• 封面图：./posts/my-article-cover.jpg
• 已发布到草稿箱
```

### 示例 5: 图文消息发布

```
用户：发布一组产品图片到公众号，标题是"新品上市"

Agent：
✓ 识别为图文发布模式
✓ 打开浏览器，定位到图文消息编辑器
✓ 填写标题
✓ 上传 6 张图片
✓ 提交发布

结果：
• 图文消息已保存到草稿箱
• 包含 6 张产品图片
```

---

## 参考文档

| 主题 | 文档 |
|------|------|
| 图文发布参数、自动压缩 | [references/image-text-posting.md](references/image-text-posting.md) |
| 文章主题、图片处理 | [references/article-posting.md](references/article-posting.md) |

---

## 权限要求

- **网络访问**：获取链接内容、下载图片
- **文件读写**：保存文章、图片和配置
- **环境变量**：读取微信 API 凭证
- **外部命令**：调用 bun/npx 执行 TypeScript 脚本
- **浏览器**（可选）：Chrome 用于浏览器发布方式

---

## 依赖与许可

### 核心依赖

- **Bun/Node.js**：运行 TypeScript 脚本（Node.js >= 18.0.0）
- **npm/bun**：包管理器（用于安装依赖）

### 自动安装的依赖

运行 `./install-deps.sh` 会自动安装：

**必需包**：
- `markdown-it` - Markdown 渲染引擎
- `juice` - CSS 内联转换库

**可选包**（封面图生成）：
- `@napi-rs/canvas` - 高性能图片生成
- `sharp` - 图片处理库

### 运行时依赖（可选）

- **Chrome/Chromium**：浏览器发布方式需要
- **微信公众号 API 凭证**：API 发布方式需要

### 许可证

- Markdown 渲染引擎基于 MIT 许可证
- 微信公众号 API 使用需遵守微信公众平台服务协议

---

## 致谢

本技能整合了以下功能和技术：

- **Markdown 渲染**：基于 markdown-it 及扩展插件
- **样式主题**：参考微信公众号优秀排版实践
- **图片处理**：JPEG 元数据清洗算法
- **微信 API**：官方文档和最佳实践

---

## 更新日志

### v1.0.0 (2026-02-09)

- ✓ 整合内容创作和链接发布功能
- ✓ 内置 Markdown 转 HTML 转换器
- ✓ 支持三种主题样式（default, grace, simple）
- ✓ 自动图片元数据清洗
- ✓ CSS 自动内联转换
- ✓ 封面图生成（无系统依赖）
- ✓ API 和浏览器两种发布方式
- ✓ 完整的工作流程和错误处理

---

**技能版本**：1.0.0
**最后更新**：2026-02-09
**作者**：整合自 wechat-article-writer 和 baoyu-post-to-wechat