文颜CLI：Markdown一键发布微信公众号的多平台排版工具

§1 学习目标

通过本文，你将掌握：

• 文颜CLI的核心设计理念与技术架构
• 本地模式与Server模式的原理与适用场景
• 多种内容输入方式与完整的publish工作流程
• 图片自动处理机制与frontmatter规范
• Server模式API接口设计与认证机制
• 多公众号发布、CI/CD集成与AI Agent集成
• 主题定制与代码高亮配置

§2 问题背景

内容创作者面临的三重困境：

文颜的目标很简单：让写作者专注内容，而不是排版和平台适配。

§3 核心功能

3.1 一键发布到多平台

文颜CLI支持一键发布至：

• 微信公众号（核心功能）
• 知乎
• 今日头条
• 以及其他内容平台（持续扩展中）

3.2 智能图片处理

文颜能自动处理以下所有图片格式：

3.3 精美排版主题

内置多套主题，支持自定义主题CSS，满足不同品牌风格需求。

§4 技术架构深度解析

4.1 两种运行模式对比

文颜CLI提供本地模式和远程客户端模式两种架构：

本地模式（Local Mode）

┌─────────────────┐     ┌─────────────────┐
│   wenyan-cli    │────▶│   微信公众号API   │
│  (TypeScript)  │     │   (上传图片/发布) │
└─────────────────┘     └─────────────────┘

特点：

• CLI直接调用微信公众号API
• 适合有固定IP的服务器或开发者本机
• 需配置IP白名单

工作流程（6步）：

1. 读取Markdown内容（文件/stdin/直接输入）
2. 解析frontmatter（标题、封面等元数据）
3. 自动检测正文和封面中的图片
4. 上传图片到微信公众号素材库
5. 将Markdown渲染为微信公众号兼容HTML
6. 创建公众号草稿，返回发布结果

远程客户端模式（Client-Server Mode）

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   wenyan-cli    │────▶│  Wenyan Server   │────▶│   微信公众号API   │
│  (TypeScript)  │     │   (云服务器)     │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘

特点：

• CLI作为客户端，将请求发送到云端Server
• Server完成API调用
• 适合无固定IP、需团队协作、CI/CD场景

Server核心架构：

• 作为中间层承接客户端请求
• 统一处理与微信公众号API的交互
• 支持流式上传（10MB），安全高效
• 临时文件10分钟后自动回收

适用场景：

• ✅ 无本地固定IP，需频繁添加IP白名单
• ✅ 团队协作
• ✅ CI/CD自动发布
• ✅ AI Agent自动发布

4.2 技术栈

§5 快速开始

5.1 安装

npm install -g @wenyan-md/cli

# 验证安装
wenyan --version

5.2 配置凭据

设置环境变量：

export WECHAT_APP_ID=your_app_id
export WECHAT_APP_SECRET=your_app_secret

5.3 发布文章

方式一：本地文件（推荐）

wenyan publish -f article.md

方式二：管道（适合CI/CD）

cat article.md | wenyan publish

方式三：直接传入内容

wenyan publish "# Hello Wenyan\n\n这是一篇测试文章"

5.4 Server模式发布

wenyan publish -f article.md \
  --server https://api.example.com \
  --api-key your-api-key

§6 publish命令详解

6.1 完整参数说明

¹ 必须满足以下之一：使用--file、使用stdin、或直接传入Markdown内容

² 仅在指定--server时生效

6.2 使用示例

# 使用指定主题
wenyan publish -f article.md -t lapis --highlight monokai

# 使用自定义主题
wenyan publish -f article.md --custom-theme ./my-theme.css

# 关闭附加样式
wenyan publish -f article.md --no-mac-style --no-footnote

# 使用远程Server
wenyan publish -f article.md \
  --server https://api.wenyan.dev \
  --api-key your-api-key

# 使用管道发布
cat article.md | wenyan publish

# 指定AppId发布
wenyan publish -f article.md \
  --app-id your-app-id \
  --server https://api.wenyan.dev \
  --api-key your-api-key

§7 frontmatter规范

每篇Markdown顶部需包含frontmatter：

---
title: 文章标题
cover: ./cover.jpg
author: 作者名称
source_url: https://example.com
---

字段说明：

自动行为：

• 如果未指定cover，将自动使用正文第一张图片作为封面

§8 图片处理机制

8.1 支持的图片格式

8.2 图片处理流程

![](./image.png)
<img src="./image2.png" />

CLI将自动：

1. 识别Markdown中的所有图片引用
2. 上传图片到微信素材库
3. 替换为微信公众号可访问的URL

8.3 常见问题

Q: 图片上传失败？ A: 请检查：

• 图片路径是否正确
• 图片文件是否存在
• 图片格式是否支持（jpg、png、gif）

Q: 发布失败：invalid ip？ A: 当前机器IP未加入微信公众号白名单。解决方法：

• 使用远程Server模式
• 或将当前IP加入微信公众号后台白名单

Q: 发布失败：invalid appid or secret？ A: 请检查环境变量WECHAT_APP_ID和WECHAT_APP_SECRET是否正确。

§9 Server模式开发指南

9.1 快速部署

# 全局安装Wenyan CLI（包含Server功能）
npm install -g @wenyan-md/cli

# 验证安装
wenyan --version

# 基础启动（默认端口3000，无API鉴权）
wenyan serve

# 自定义端口 + 开启API鉴权（推荐生产环境）
wenyan serve --port 8080 --api-key your-secret-api-key-123456

9.2 启动参数说明

9.3 环境变量设置

如果只使用一个公众号进行发布：

export WECHAT_APP_ID=xxx
export WECHAT_APP_SECRET=xxx

这样在调用publish接口时就无需传递wechat_app_id和wechat_app_secret参数。

9.4 API接口设计

健康检查

curl http://localhost:3000/health

文件/图片上传接口

支持上传图片和Markdown文件。上传后返回fileId供下一步使用：

curl -X POST http://localhost:3000/upload \
  -H "x-api-key: my-secret-key" \
  -F "file=@/path/to/article.md"

响应示例：

{
  "success": true,
  "data": {
    "fileId": "550e8400-e29b-41d4-a716-446655440000.md",
    "originalFilename": "article.md",
    "mimetype": "text/markdown",
    "size": 1024
  }
}

远程发布接口

使用上传阶段获得的fileId触发服务端的排版渲染和微信发布流程：

curl -X POST http://localhost:3000/publish \
  -H "x-api-key: my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "550e8400-e29b-41d4-a716-446655440000.md",
    "theme": "default",
    "highlight": "solarized-light",
    "macStyle": true
  }'

9.5 API认证机制

当服务启动时指定--api-key参数，所有接口（除/health）均需通过API Key认证：

1. 客户端在请求Header中添加x-api-key: 你的服务端密钥
2. 服务端验证Header中的密钥与启动时设置的密钥是否一致
3. 验证失败返回401 Unauthorized，验证通过才处理请求

§10 多公众号发布

10.1 配置流程

1. 删除环境变量中的WECHAT_APP_ID和WECHAT_APP_SECRET
2. 按照文档配置多个公众号凭据
3. 发布时指定公众号：

wenyan publish -f article.md --app-id your-app-id

10.2 注意事项

• 每个公众号都需要配置IP白名单
• 强烈建议搭配Server模式使用多公众号功能

§11 CI/CD集成

11.1 GitHub Actions示例

name: Publish to WeChat
on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: pnpm/action-setup@v2
        with:
          version: 8
          
      - run: pnpm install
        env:
          WECHAT_APP_ID: ${{ secrets.WECHAT_APP_ID }}
          WECHAT_APP_SECRET: ${{ secrets.WECHAT_APP_SECRET }}
          
      - run: |
          cat article.md | pnpm wenyan publish

11.2 使用Server模式进行CI/CD

# 在CI环境中
cat article.md | wenyan publish \
  --server https://api.wenyan.dev \
  --api-key $WENYAN_API_KEY

§12 AI Agent集成

文颜CLI可作为AI Agent的发布工具，配合MCP版本实现自动发布：

12.1 AI Agent工作流

AI写作 → 生成Markdown → wenyan publish → 微信公众号

§13 主题与样式定制

13.1 内置主题

13.2 代码高亮主题

13.3 自定义主题

# 使用本地CSS文件
wenyan publish -f article.md --custom-theme ./my-theme.css

# 使用网络CSS
wenyan publish -f article.md --custom-theme https://example.com/theme.css

§14 最佳实践

14.1 本地开发流程

# 1. 安装CLI
npm install -g @wenyan-md/cli

# 2. 配置凭据
wenyan credential

# 3. 写作（使用Markdown）
vim article.md

# 4. 本地预览
wenyan render -f article.md

# 5. 发布到公众号
wenyan publish -f article.md

14.2 Server部署建议

使用Docker快速部署：

# 拉取镜像
docker pull caol64/wenyan-cli

# 启动服务
docker run -d -p 3000:3000 \
  -e WECHAT_APP_ID=xxx \
  -e WECHAT_APP_SECRET=xxx \
  caol64/wenyan-cli serve

14.3 团队协作建议

1. 部署一台共享的Wenyan Server
2. 团队成员通过--server参数使用
3. 使用--api-key进行访问控制

§15 常见问题

§16 总结

文颜CLI通过简单的命令将复杂的排版和发布流程自动化，让创作者只需专注Markdown写作。它解决了内容创作者的三大痛点：

• ✅ 排版自动化：Markdown直接转微信公众号格式
• ✅ 图片智能处理：支持多种图片格式自动上传
• ✅ 多平台支持：一次写作，多平台发布

相关资源：

• 官网：wenyan.yuzhi.tech
• NPM：@wenyan-md/cli
• Docker：caol64/wenyan-cli

🦞 文档版本：v2.0 | 写作日期：2026-04-09