wechat-publisher

Original source / Raw SKILL.md

---
name: wechat-publisher
description: "一键发布 Markdown 到微信公众号草稿箱。基于 wenyan-cli，支持多主题、代码高亮、图片自动上传。"
metadata:
  {
    "openclaw":
      {
        "emoji": "📱",
      },
  }
---

# wechat-publisher

**一键发布 Markdown 文章到微信公众号草稿箱**

基于 [wenyan-cli](https://github.com/caol64/wenyan-cli) 封装的 OpenClaw skill。

## 功能

- ✅ Markdown 自动转换为微信公众号格式
- ✅ 自动上传图片到微信图床
- ✅ 一键推送到草稿箱
- ✅ 多主题支持（代码高亮、Mac 风格代码块）
- ✅ 支持本地和网络图片

## 快速开始

### 1. 安装 wenyan-cli

**wenyan-cli 需要全局安装：**

```bash
npm install -g @wenyan-md/cli
```

**验证安装：**
```bash
wenyan --help
```

> **注意：** publish.sh 脚本会自动检测并安装 wenyan-cli（如果未安装）

### 2. 配置 API 凭证

API 凭证已保存在 `/Users/leebot/.openclaw/workspace/TOOLS.md`

确保环境变量已设置：
```bash
export WECHAT_APP_ID=your_wechat_app_id
export WECHAT_APP_SECRET=your_wechat_app_secret
```

**重要：** 确保你的 IP 已添加到微信公众号后台的白名单！

配置方法：https://yuzhi.tech/docs/wenyan/upload

### 3. 准备 Markdown 文件

文件顶部**必须**包含完整的 frontmatter（wenyan 强制要求）：

```markdown
---
title: 文章标题（必填！）
cover: https://example.com/cover.jpg  # 封面图（必填！）
---

# 正文开始

你的内容...
```

**⚠️ 关键发现（实测）：**
- `title` 和 `cover` **都是必填字段**！
- 缺少任何一个都会报错："未能找到文章封面"
- 虽然文档说"正文有图可省略cover"，但实际测试必须提供 cover
- 所有图片（本地/网络）都会自动上传到微信图床

**推荐封面图来源：**
```markdown
# 方案1: 相对路径（推荐，便于分享）
cover: ./assets/default-cover.jpg

# 方案2: 绝对路径
cover: /Users/bruce/photos/cover.jpg

# 方案3: 网络图片
cover: https://your-cdn.com/image.jpg
```

**💡 提示：** 使用相对路径时，从 Markdown 文件所在目录开始计算。

### 4. 发布文章

**方式 1: 使用 publish.sh 脚本**
```bash
cd /Users/leebot/.openclaw/workspace/wechat-publisher
./scripts/publish.sh /path/to/article.md
```

**方式 2: 直接使用 wenyan-cli**
```bash
wenyan publish -f article.md -t lapis -h solarized-light
```

**方式 3: 在 OpenClaw 中使用**
```
"帮我发布这篇文章到微信公众号" + 附带 Markdown 文件路径
```

## 主题选项

wenyan-cli 支持多种主题：

**内置主题：**
- `default` - 默认主题
- `lapis` - 青金石（推荐）
- `phycat` - 物理猫
- 更多主题见：https://github.com/caol64/wenyan-core/tree/main/src/assets/themes

**代码高亮主题：**
- `atom-one-dark` / `atom-one-light`
- `dracula`
- `github-dark` / `github`
- `monokai`
- `solarized-dark` / `solarized-light` (推荐)
- `xcode`

**使用示例：**
```bash
# 使用 lapis 主题 + solarized-light 代码高亮
wenyan publish -f article.md -t lapis -h solarized-light

# 使用 phycat 主题 + GitHub 代码高亮
wenyan publish -f article.md -t phycat -h github

# 关闭 Mac 风格代码块
wenyan publish -f article.md -t lapis --no-mac-style

# 关闭链接转脚注
wenyan publish -f article.md -t lapis --no-footnote
```

## 自定义主题

### 临时使用自定义主题
```bash
wenyan publish -f article.md -c /path/to/custom-theme.css
```

### 安装自定义主题（永久）
```bash
# 从本地文件安装
wenyan theme --add --name my-theme --path /path/to/theme.css

# 从网络安装
wenyan theme --add --name my-theme --path https://example.com/theme.css

# 使用已安装的主题
wenyan publish -f article.md -t my-theme

# 删除主题
wenyan theme --rm my-theme
```

### 列出所有主题
```bash
wenyan theme -l
```

## 工作流程

1. **准备内容** - 用 Markdown 写作
2. **运行脚本** - 一键发布到草稿箱
3. **审核发布** - 到公众号后台审核并发布

## Markdown 格式要求

### 必需的 Frontmatter

**⚠️ 关键（实测结果）：wenyan-cli 强制要求完整的 frontmatter！**

```markdown
---
title: 文章标题（必填！）
cover: 封面图片URL或路径（必填！）
---
```

**示例 1：相对路径（推荐）**
```markdown
---
title: 我的技术文章
cover: ./assets/cover.jpg
---

# 正文...
```

**示例 2：绝对路径**
```markdown
---
title: 我的技术文章
cover: /Users/bruce/photos/cover.jpg
---

# 正文...
```

**示例 3：网络图片**
```markdown
---
title: 我的技术文章
cover: https://example.com/cover.jpg
---

# 正文...
```

**❌ 错误示例（会报错）：**

```markdown
# 只有 title，没有 cover
---
title: 我的文章
---

错误信息：未能找到文章封面
```

```markdown
# 完全没有 frontmatter
# 我的文章

错误信息：未能找到文章封面
```

**💡 重要发现：**
- 虽然 wenyan 官方文档说"正文有图片可省略cover"
- 但**实际测试必须提供 cover**，否则报错
- title 和 cover **缺一不可**

### 图片支持
- ✅ 本地路径：`![](./images/photo.jpg)`
- ✅ 绝对路径：`![](/Users/bruce/photo.jpg)`
- ✅ 网络图片：`![](https://example.com/photo.jpg)`

所有图片会自动上传到微信图床！

### 代码块
````markdown
```python
def hello():
    print("Hello, WeChat!")
```
````

会自动添加代码高亮和 Mac 风格装饰。

## 故障排查

### 1. 上传失败：IP 不在白名单

**错误信息：** `ip not in whitelist`

**解决方法：**
1. 获取你的公网 IP：`curl ifconfig.me`
2. 登录微信公众号后台：https://mp.weixin.qq.com/
3. 开发 → 基本配置 → IP 白名单 → 添加你的 IP

### 2. wenyan-cli 未安装

**错误信息：** `wenyan: command not found`

**解决方法：**
```bash
npm install -g @wenyan-md/cli
```

### 3. 环境变量未设置

**错误信息：** `WECHAT_APP_ID is required`

**解决方法：**
```bash
export WECHAT_APP_ID=your_wechat_app_id
export WECHAT_APP_SECRET=your_wechat_app_secret
```

或在 `~/.zshrc` / `~/.bashrc` 中永久添加。

### 4. Frontmatter 缺失

**错误信息：** `title is required in frontmatter`

**解决方法：** 在 Markdown 文件顶部添加：
```markdown
---
title: 你的文章标题
---
```

## 参考资料

- wenyan-cli GitHub: https://github.com/caol64/wenyan-cli
- wenyan 官网: https://wenyan.yuzhi.tech
- 微信公众号 API 文档: https://developers.weixin.qq.com/doc/offiaccount/
- IP 白名单配置: https://yuzhi.tech/docs/wenyan/upload

## 更新日志

### 2026-02-05 - v1.0.0
- ✅ 初始版本
- ✅ 基于 wenyan-cli 封装
- ✅ 支持一键发布到草稿箱
- ✅ 多主题支持
- ✅ 自动图片上传

## License

Apache License 2.0 (继承自 wenyan-cli)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/publish.sh

```bash
#!/usr/bin/env bash
# wechat-publisher: 发布 Markdown 到微信公众号草稿箱
# Usage: ./publish.sh <markdown-file> [theme] [highlight]

set -e

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# 默认配置
DEFAULT_THEME="lapis"
DEFAULT_HIGHLIGHT="solarized-light"
TOOLS_MD="$HOME/.openclaw/workspace/TOOLS.md"

# 检查 wenyan-cli 是否安装
check_wenyan() {
    if ! command -v wenyan &> /dev/null; then
        echo -e "${RED}❌ wenyan-cli 未安装！${NC}"
        echo -e "${YELLOW}正在安装 wenyan-cli...${NC}"
        npm install -g @wenyan-md/cli
        if [ $? -eq 0 ]; then
            echo -e "${GREEN}✅ wenyan-cli 安装成功！${NC}"
        else
            echo -e "${RED}❌ 安装失败！请手动运行: npm install -g @wenyan-md/cli${NC}"
            exit 1
        fi
    fi
}

# 从 TOOLS.md 读取环境变量
load_credentials() {
    if [ -z "$WECHAT_APP_ID" ] || [ -z "$WECHAT_APP_SECRET" ]; then
        if [ -f "$TOOLS_MD" ]; then
            echo -e "${YELLOW}📖 从 TOOLS.md 读取凭证...${NC}"
            export WECHAT_APP_ID=$(grep "export WECHAT_APP_ID=" "$TOOLS_MD" | head -1 | sed 's/.*export WECHAT_APP_ID=//' | tr -d ' ')
            export WECHAT_APP_SECRET=$(grep "export WECHAT_APP_SECRET=" "$TOOLS_MD" | head -1 | sed 's/.*export WECHAT_APP_SECRET=//' | tr -d ' ')
        fi
    fi
}

# 检查环境变量
check_env() {
    load_credentials
    
    if [ -z "$WECHAT_APP_ID" ] || [ -z "$WECHAT_APP_SECRET" ]; then
        echo -e "${RED}❌ 环境变量未设置！${NC}"
        echo -e "${YELLOW}请在 TOOLS.md 中添加微信公众号凭证：${NC}"
        echo ""
        echo "  ## 🔐 WeChat Official Account (微信公众号)"
        echo "  "
        echo "  export WECHAT_APP_ID=your_app_id"
        echo "  export WECHAT_APP_SECRET=your_app_secret"
        echo ""
        echo -e "${YELLOW}或者手动设置环境变量：${NC}"
        echo "  export WECHAT_APP_ID=your_app_id"
        echo "  export WECHAT_APP_SECRET=your_app_secret"
        echo ""
        echo -e "${YELLOW}或者运行：${NC}"
        echo "  source ./scripts/setup.sh"
        exit 1
    fi
}

# 检查文件是否存在
check_file() {
    local file="$1"
    if [ ! -f "$file" ]; then
        echo -e "${RED}❌ 文件不存在: $file${NC}"
        exit 1
    fi
}

# 发布函数
publish() {
    local file="$1"
    local theme="${2:-$DEFAULT_THEME}"
    local highlight="${3:-$DEFAULT_HIGHLIGHT}"
    
    echo -e "${GREEN}📝 准备发布文章...${NC}"
    echo "  文件: $file"
    echo "  主题: $theme"
    echo "  代码高亮: $highlight"
    echo ""
    
    # 执行发布
    wenyan publish -f "$file" -t "$theme" -h "$highlight"
    
    if [ $? -eq 0 ]; then
        echo ""
        echo -e "${GREEN}✅ 发布成功！${NC}"
        echo -e "${YELLOW}📱 请前往微信公众号后台草稿箱查看：${NC}"
        echo "  https://mp.weixin.qq.com/"
    else
        echo ""
        echo -e "${RED}❌ 发布失败！${NC}"
        echo -e "${YELLOW}💡 常见问题：${NC}"
        echo "  1. IP 未在白名单 → 添加到公众号后台"
        echo "  2. Frontmatter 缺失 → 文件顶部添加 title + cover"
        echo "  3. API 凭证错误 → 检查 TOOLS.md 中的凭证"
        echo "  4. 封面尺寸错误 → 需要 1080×864 像素"
        exit 1
    fi
}

# 显示帮助
show_help() {
    echo "Usage: $0 <markdown-file> [theme] [highlight]"
    echo ""
    echo "Examples:"
    echo "  $0 article.md"
    echo "  $0 article.md lapis"
    echo "  $0 article.md lapis solarized-light"
    echo ""
    echo "Available themes:"
    echo "  default, lapis, phycat, ..."
    echo "  Run 'wenyan theme -l' to see all themes"
    echo ""
    echo "Available highlights:"
    echo "  atom-one-dark, atom-one-light, dracula, github-dark, github,"
    echo "  monokai, solarized-dark, solarized-light, xcode"
}

# 主函数
main() {
    # 检查参数
    if [ $# -eq 0 ] || [ "$1" == "-h" ] || [ "$1" == "--help" ]; then
        show_help
        exit 0
    fi
    
    local file="$1"
    local theme="$2"
    local highlight="$3"
    
    # 执行检查
    check_wenyan
    check_env
    check_file "$file"
    
    # 发布文章
    publish "$file" "$theme" "$highlight"
}

# 运行
main "$@"

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# wechat-publisher

**一键发布 Markdown 到微信公众号草稿箱 🚀**

基于 [wenyan-cli](https://github.com/caol64/wenyan-cli) 封装的 OpenClaw skill。

---

## ✨ 功能特性

- 🚀 **一键发布** - Markdown 自动转换并推送到草稿箱
- 🎨 **多主题支持** - lapis、phycat、default 等精美主题
- 💻 **代码高亮** - 9 种代码高亮主题，Mac 风格代码块
- 🖼️ **图片自动处理** - 本地/网络图片自动上传到微信图床
- 🔒 **安全设计** - 凭证从 TOOLS.md 读取，不会泄露
- 📚 **完整文档** - 详细的使用说明和故障排查指南

---

## 🚀 快速开始

### 1. 安装 wenyan-cli

```bash
npm install -g @wenyan-md/cli
```

### 2. 克隆此仓库

```bash
git clone https://github.com/0731coderlee-sudo/wechat-publisher.git
cd wechat-publisher
```

### 3. 配置 API 凭证

在 OpenClaw workspace 的 `TOOLS.md` 中添加：

```markdown
## 🔐 WeChat Official Account (微信公众号)

**API Credentials:**
\`\`\`bash
export WECHAT_APP_ID=your_wechat_app_id
export WECHAT_APP_SECRET=your_wechat_app_secret
\`\`\`

**IP Whitelist:** 确保运行机器的 IP 已添加到公众号后台白名单

**后台地址:** https://mp.weixin.qq.com/
```

**如何获取凭证：**
1. 登录微信公众号后台：https://mp.weixin.qq.com/
2. 设置与开发 → 基本配置 → 开发者ID(AppID) 和 开发者密码(AppSecret)
3. 添加服务器 IP 到白名单：设置与开发 → 基本配置 → IP白名单

### 4. 发布测试文章

```bash
./scripts/publish.sh example.md
```

### 5. 查看草稿箱

前往微信公众号后台草稿箱查看：https://mp.weixin.qq.com/

---

## 📝 使用方法

### Markdown 格式要求

文件顶部**必须**包含 frontmatter（wenyan 强制要求）：

```markdown
---
title: 文章标题（必填！）
cover: ./assets/cover.jpg  # 封面图（必填！推荐 1080×864）
---

# 正文开始

你的内容...
```

**封面图推荐：**
- **相对路径**（推荐）：`./assets/cover.jpg`
- **绝对路径**：`/path/to/cover.jpg`
- **网络图片**：`https://example.com/cover.jpg`
- **尺寸建议**：1080×864（微信推荐比例）

### 发布命令

```bash
# 基本用法（使用默认主题）
./scripts/publish.sh article.md

# 指定主题和代码高亮
./scripts/publish.sh article.md lapis solarized-light

# 可用主题：lapis, phycat, default, orange, purple...
# 可用代码高亮：solarized-light, monokai, github, atom-one-dark...
```

---

## 🎨 主题预览

| 主题 | 风格 | 适合场景 |
|------|------|----------|
| **lapis** | 蓝色优雅 | 技术文章、教程 |
| **phycat** | 绿色清新 | 博客、随笔 |
| **default** | 经典简约 | 通用场景 |
| **orange** | 橙色活力 | 产品介绍 |
| **purple** | 紫色神秘 | 设计、创意 |

查看完整主题列表：[references/themes.md](references/themes.md)

---

## 🛠️ 故障排查

### 常见问题

**1. 错误：`Error: 未能找到文章封面`**
- **原因**：frontmatter 缺少 `cover` 字段
- **解决**：确保 frontmatter 包含 `title` 和 `cover`

**2. 错误：`Error: 45166 (IP地址不在白名单中)`**
- **原因**：运行机器的 IP 未添加到微信白名单
- **解决**：登录公众号后台添加 IP 到白名单

**3. 发布成功但看不到文章？**
- **原因**：文章在草稿箱，需要审核发布
- **解决**：草稿箱 → 选中文章 → 发布

**4. 图片上传失败？**
- **原因**：网络图片无法访问或格式不支持
- **解决**：使用本地图片或检查网络连接

查看完整故障排查指南：[references/troubleshooting.md](references/troubleshooting.md)

---

## 📂 项目结构

```
wechat-publisher/
├── SKILL.md                     # OpenClaw skill 完整文档
├── README.md                    # 本文件
├── example.md                   # 测试文章示例
├── .gitignore                   # Git 忽略文件
├── assets/
│   └── default-cover.jpg        # 默认封面（1080×864）
├── scripts/
│   ├── publish.sh               # 发布脚本（自动加载凭证）
│   └── setup.sh                 # 环境变量设置脚本
└── references/
    ├── themes.md                # 主题列表和使用说明
    └── troubleshooting.md       # 详细故障排查指南
```

---

## 🔧 高级用法

### 自定义主题

创建你自己的主题配置文件：

```bash
wenyan theme create my-theme
wenyan publish -f article.md -t my-theme
```

### 批量发布

```bash
for file in articles/*.md; do
    ./scripts/publish.sh "$file"
done
```

### 使用环境变量

```bash
export WECHAT_APP_ID=your_id
export WECHAT_APP_SECRET=your_secret
wenyan publish -f article.md
```

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 开发流程

1. Fork 此仓库
2. 创建特性分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m 'Add amazing feature'`
4. 推送到分支：`git push origin feature/amazing-feature`
5. 提交 Pull Request

---

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

---

## 🙏 致谢

- [wenyan-cli](https://github.com/caol64/wenyan-cli) - 优秀的微信公众号发布工具
- [OpenClaw](https://openclaw.ai) - 强大的 AI Agent 框架

---

## 📮 联系方式

- **GitHub**: [@0731coderlee-sudo](https://github.com/0731coderlee-sudo)
- **Issues**: [提交问题](https://github.com/0731coderlee-sudo/wechat-publisher/issues)

---

**如果这个 skill 对你有帮助，请给个 ⭐️ Star！**

```

### _meta.json

```json
{
  "owner": "0731coderlee-sudo",
  "slug": "wechat-publisher",
  "displayName": "Wechat Publisher",
  "latest": {
    "version": "0.1.0",
    "publishedAt": 1770290549190,
    "commit": "https://github.com/clawdbot/skills/commit/21afe90dcf3a2caac124813270851a1dff67e9b2"
  },
  "history": []
}

```

### example.md

```markdown
---
title: wechat-publisher 测试文章
cover: ./assets/default-cover.jpg
---

# wechat-publisher Skill 测试

欢迎使用 **wechat-publisher** skill！

## 核心功能

### 1. Markdown 自动转换
- 标准 Markdown 转换为微信公众号格式
- 自动处理样式和排版
- 支持多种主题

### 2. 图片自动上传
- 本地图片自动上传
- 网络图片自动处理
- 无需手动操作

### 3. 一键发布
```bash
./scripts/publish.sh example.md
```

## 代码示例

```python
def publish_article(file):
    """发布到微信公众号"""
    return wenyan.publish(file)
```

## 使用步骤

1. 配置凭证（TOOLS.md）
2. 准备 Markdown 文件
3. 运行发布脚本

## 封面图说明

本测试文章使用相对路径引用封面：
```markdown
cover: ./assets/default-cover.jpg
```

这样发布到 GitHub 后，其他用户克隆 skill 也能直接使用！

## 测试总结

如果看到这篇文章，说明 skill 工作正常！

---

*由 wechat-publisher 自动发布*

```

### references/themes.md

```markdown
# wenyan-cli 主题列表

wenyan-cli 支持多种内置主题，也支持自定义主题。

## 内置主题

查看所有内置主题：
```bash
wenyan theme -l
```

**常用主题：**

1. **default** - 默认主题
   - 简洁、通用
   - 适合大部分文章

2. **lapis** - 青金石（推荐）
   - 优雅的蓝色调
   - 适合技术文章

3. **phycat** - 物理猫
   - 轻量、现代
   - 适合科技类内容

**完整主题列表：** https://github.com/caol64/wenyan-core/tree/main/src/assets/themes

## 代码高亮主题

### 亮色主题
- `atom-one-light` - Atom 编辑器亮色
- `github` - GitHub 风格
- `solarized-light` - Solarized 亮色（推荐）
- `xcode` - Xcode 默认

### 暗色主题
- `atom-one-dark` - Atom 编辑器暗色
- `dracula` - Dracula 主题
- `github-dark` - GitHub 暗色
- `monokai` - Monokai 经典
- `solarized-dark` - Solarized 暗色

## 自定义主题

### 临时使用
```bash
wenyan publish -f article.md -c /path/to/theme.css
```

### 永久安装
```bash
# 从本地文件
wenyan theme --add --name my-theme --path /path/to/theme.css

# 从网络
wenyan theme --add --name my-theme --path https://example.com/theme.css
```

### 使用已安装主题
```bash
wenyan publish -f article.md -t my-theme
```

### 删除主题
```bash
wenyan theme --rm my-theme
```

## 主题定制

如果你想创建自己的主题，可以参考：

1. **查看现有主题源码：** https://github.com/caol64/wenyan-core/tree/main/src/assets/themes
2. **CSS 变量参考：** wenyan 使用 CSS 变量定制样式
3. **测试主题：** 使用 `wenyan render` 命令仅渲染不发布

**示例：**
```bash
# 渲染测试（不发布）
wenyan render -f article.md -t my-theme -h github
```

## 推荐组合

### 技术文章
```bash
wenyan publish -f article.md -t lapis -h solarized-light
```

### 深色风格
```bash
wenyan publish -f article.md -t phycat -h dracula
```

### 简洁风格
```bash
wenyan publish -f article.md -t default -h github
```

## 更多选项

### 关闭 Mac 风格代码块
```bash
wenyan publish -f article.md -t lapis --no-mac-style
```

### 关闭链接转脚注
```bash
wenyan publish -f article.md -t lapis --no-footnote
```

### 组合所有选项
```bash
wenyan publish -f article.md \
  -t lapis \
  -h solarized-light \
  --no-mac-style \
  --no-footnote
```

```

### references/troubleshooting.md

```markdown
# 故障排查指南

wechat-publisher skill 的常见问题和解决方案。

## 1. ❌ IP 不在白名单

**错误信息：**
```
Error: ip not in whitelist
```

**原因：** 你的 IP 地址未添加到微信公众号后台白名单。

**解决方法：**

1. **获取你的公网 IP：**
   ```bash
   curl ifconfig.me
   ```

2. **登录微信公众号后台：** https://mp.weixin.qq.com/

3. **添加 IP 白名单：**
   - 开发 → 基本配置
   - IP 白名单 → 添加你的 IP

4. **重试发布**

**详细说明：** https://yuzhi.tech/docs/wenyan/upload

---

## 2. ❌ wenyan-cli 未安装

**错误信息：**
```
wenyan: command not found
```

**解决方法：**
```bash
npm install -g @wenyan-md/cli
```

**验证安装：**
```bash
wenyan --help
```

---

## 3. ❌ 环境变量未设置

**错误信息：**
```
Error: WECHAT_APP_ID is required
```

**解决方法：**

**方式 1: 使用 setup.sh**
```bash
cd /Users/leebot/.openclaw/workspace/wechat-publisher
source ./scripts/setup.sh
```

**方式 2: 手动设置（临时）**
```bash
export WECHAT_APP_ID=your_wechat_app_id
export WECHAT_APP_SECRET=your_wechat_app_secret
```

**方式 3: 永久设置**

编辑 `~/.zshrc` 或 `~/.bashrc`，添加：
```bash
export WECHAT_APP_ID=your_wechat_app_id
export WECHAT_APP_SECRET=your_wechat_app_secret
```

然后：
```bash
source ~/.zshrc  # 或 source ~/.bashrc
```

---

## 4. ❌ Frontmatter 缺失（最常见！）

**错误信息：**
```
Error: 未能找到文章封面
```

**原因：** Markdown 文件缺少必需的 frontmatter（特别是 `title` 字段）。

**⚠️ 重要：** wenyan-cli **强制要求** frontmatter，必须在 Markdown 文件顶部添加！

**解决方法：**

**方案 1：有封面图**
```markdown
---
title: 你的文章标题
cover: /path/to/cover.jpg
---

# 正文开始
...
```

**方案 2：无封面图（推荐，正文有图片即可）**
```markdown
---
title: 你的文章标题
---

# 正文

![配图](https://example.com/image.jpg)  # 正文图片会自动上传

内容...
```

**⚠️ 关键点：**
- `title` 字段是**必须的**，缺少会报错 "未能找到文章封面"
- `cover` 字段可选：如果正文中有图片，wenyan 会自动使用第一张图作为封面
- frontmatter 必须在文件最顶部，前面不能有空行或其他内容
- frontmatter 使用三个短横线 `---` 包围

**错误示例（会报错）：**
```markdown
# 我的文章

没有 frontmatter，wenyan 会报错！
```

---

## 5. ❌ 图片上传失败

**错误信息：**
```
Error: Failed to upload image
```

**可能原因：**

1. **图片路径错误** - 检查本地路径是否正确
2. **图片格式不支持** - 微信支持 jpg/png/gif
3. **图片过大** - 微信限制单张图片 < 10MB
4. **网络图片无法访问** - 检查 URL 是否可访问

**解决方法：**

1. **检查图片路径：**
   ```bash
   ls -lh /path/to/image.jpg
   ```

2. **检查图片格式：**
   ```bash
   file /path/to/image.jpg
   ```

3. **压缩图片（如果过大）：**
   ```bash
   # 使用 ImageMagick
   convert large.jpg -quality 80 -resize 1200x compressed.jpg
   ```

4. **测试网络图片：**
   ```bash
   curl -I https://example.com/image.jpg
   ```

---

## 6. ❌ API 凭证错误

**错误信息：**
```
Error: invalid credential
```

**原因：** AppID 或 AppSecret 错误。

**解决方法：**

1. **检查 TOOLS.md 中的凭证是否正确**

2. **重新获取凭证：**
   - 登录：https://mp.weixin.qq.com/
   - 开发 → 基本配置
   - 查看 AppID 和 AppSecret

3. **更新环境变量**

4. **重试发布**

---

## 7. ❌ Node.js 版本过低

**错误信息：**
```
Error: Requires Node.js >= 14.0.0
```

**解决方法：**

1. **检查当前版本：**
   ```bash
   node --version
   ```

2. **升级 Node.js：**
   ```bash
   # 使用 Homebrew (macOS)
   brew upgrade node
   
   # 或使用 nvm
   nvm install stable
   nvm use stable
   ```

---

## 8. ❌ 网络连接问题

**错误信息：**
```
Error: connect ETIMEDOUT
```

**可能原因：**

1. **网络不稳定** - 检查网络连接
2. **防火墙阻止** - 检查防火墙设置
3. **微信 API 服务异常** - 稍后重试

**解决方法：**

1. **测试网络连接：**
   ```bash
   curl -I https://api.weixin.qq.com
   ```

2. **使用代理（如需要）：**
   ```bash
   export HTTP_PROXY=http://proxy:port
   export HTTPS_PROXY=http://proxy:port
   ```

3. **重试发布**

---

## 9. 🐛 调试模式

如果以上方法都不行，启用详细日志：

```bash
# 设置详细日志
export DEBUG=wenyan:*

# 运行发布
wenyan publish -f article.md -t lapis -h solarized-light
```

查看完整错误信息，然后：
- 检查 wenyan-cli GitHub Issues: https://github.com/caol64/wenyan-cli/issues
- 或提交新 Issue

---

## 10. 📞 获取帮助

**wenyan-cli 帮助：**
```bash
wenyan --help
wenyan publish --help
wenyan theme --help
```

**wechat-publisher 帮助：**
```bash
cd /Users/leebot/.openclaw/workspace/wechat-publisher
./scripts/publish.sh --help
```

**参考资料：**
- wenyan-cli GitHub: https://github.com/caol64/wenyan-cli
- wenyan 官网: https://wenyan.yuzhi.tech
- 微信公众号开发文档: https://developers.weixin.qq.com/doc/offiaccount/

---

## 💡 最佳实践

**1. 始终添加 frontmatter**
```markdown
---
title: 文章标题（必填！）
---
```

**2. 正文添加至少一张图片**
- wenyan 会自动使用第一张图作为封面
- 图片会自动上传到微信图床

**3. 测试流程**
```bash
# 1. 先用 render 测试（不发布）
wenyan render -f article.md

# 2. 确认无误后再 publish
wenyan publish -f article.md -t lapis -h solarized-light
```

**4. 检查列表**
- ✅ frontmatter 中有 title
- ✅ 正文有至少一张图片（或 frontmatter 有 cover）
- ✅ 环境变量已设置
- ✅ IP 在白名单中

---

**如果问题仍未解决，请联系 Bruce 或提交 Issue。**

```

### scripts/setup.sh

```bash
#!/usr/bin/env bash
# setup.sh - 从 TOOLS.md 读取微信公众号环境变量
# Usage: source ./setup.sh

TOOLS_MD="$HOME/.openclaw/workspace/TOOLS.md"

# 检查 TOOLS.md 是否存在
if [ ! -f "$TOOLS_MD" ]; then
    echo "❌ 找不到 TOOLS.md 文件: $TOOLS_MD"
    echo ""
    echo "请在 TOOLS.md 中添加微信公众号凭证："
    echo ""
    echo "## 🔐 WeChat Official Account (微信公众号)"
    echo ""
    echo "export WECHAT_APP_ID=your_app_id"
    echo "export WECHAT_APP_SECRET=your_app_secret"
    exit 1
fi

# 从 TOOLS.md 提取凭证
WECHAT_APP_ID=$(grep "export WECHAT_APP_ID=" "$TOOLS_MD" | head -1 | sed 's/.*export WECHAT_APP_ID=//' | tr -d ' ')
WECHAT_APP_SECRET=$(grep "export WECHAT_APP_SECRET=" "$TOOLS_MD" | head -1 | sed 's/.*export WECHAT_APP_SECRET=//' | tr -d ' ')

# 检查是否成功提取
if [ -z "$WECHAT_APP_ID" ] || [ -z "$WECHAT_APP_SECRET" ]; then
    echo "❌ 无法从 TOOLS.md 读取凭证！"
    echo ""
    echo "请确保 TOOLS.md 包含以下格式："
    echo ""
    echo "export WECHAT_APP_ID=your_app_id"
    echo "export WECHAT_APP_SECRET=your_app_secret"
    exit 1
fi

# 设置环境变量
export WECHAT_APP_ID
export WECHAT_APP_SECRET

echo "✅ 微信公众号环境变量已从 TOOLS.md 加载！"
echo ""
echo "  WECHAT_APP_ID=${WECHAT_APP_ID:0:10}..."
echo "  WECHAT_APP_SECRET=****** (已隐藏)"
echo ""
echo "💡 提示：这些变量仅在当前 shell 会话有效"

```