Metadata-Version: 2.4
Name: md2wx-cli
Version: 0.2.3
Summary: 轻量级 Markdown 转微信公众号 HTML CLI 工具（支持剪贴板直达、主题提取、WeChatSync 联动）
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown>=3.10
Requires-Dist: beautifulsoup4>=4.14
Requires-Dist: cssutils>=2.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: Pygments>=2.17
Dynamic: license-file

<div align="center">

<img src="examples/guide/images/cover.png" alt="md2wx-cli：Markdown 直达微信公众号" width="640">

# md2wx-cli

**从 Markdown 到微信公众号，全链路命令行闭环。**

[![PyPI](https://img.shields.io/pypi/v/md2wx-cli)](https://pypi.org/project/md2wx-cli/)
[![Python](https://img.shields.io/pypi/pyversions/md2wx-cli)](https://pypi.org/project/md2wx-cli/)
[![License](https://img.shields.io/pypi/l/md2wx-cli)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-30%20passed-brightgreen)](tests/)

*排版引擎 · 主题系统 · 草稿箱直传 · 合规体检 · 推文逆向 · AI 排版与写作技能栈*

</div>

---

## 为什么需要它

写完一篇 Markdown，真正的麻烦才开始：贴进公众号编辑器样式全丢、代码块乱掉、外链变死文字、图片一张张重传。网页转换器要开网站、反复粘贴，改个错别字又得重来。

md2wx-cli 把这条流水线压成一条命令——**改完重跑一遍，十秒出新版**。

| 你写的 | 微信里呈现的 | 谁来处理 |
| :--- | :--- | :--- |
| 标准 Markdown | 全内联 CSS 排版 | 转换引擎 |
| ```` ```bash ```` 代码块 | 语法高亮 + 横向滚动 + 暗黑模式适配 | Pygments + 微信修复层 |
| `[链接](url)` | 文末上标脚注（微信正文禁止外链点击） | 链接转脚注 |
| 中英混排 | 自动加空格 | CJK 间距引擎 |
| 本地图片 | 自动上传微信永久图床并替换链接 | 发布管线 |

## 安装

Python ≥ 3.11。

```bash
pip install md2wx-cli
```

免安装直接运行：

```bash
uvx md2wx-cli article.md -c
```

> 命令入口名为 `md2wx`。PyPI 包名 `md2wx-cli` 与 import 名 `md2wx` 分离（`md2wx` 在 PyPI 上已被其他项目占用）。

## 快速开始

```bash
# 转换并写入系统剪贴板，公众号编辑器 Ctrl+V 直接粘贴
md2wx article.md -c

# 输出 HTML 文件
md2wx article.md -o output.html

# 切换主题
md2wx article.md -t github-tech -c

# 生成完整 <html> 独立页面，双击即可预览
md2wx article.md -o preview.html --full-page

# 支持标准输入管道
cat article.md | md2wx -c
```

## 主题系统

内置 5 套主题，`-t` 一键切换：

| 主题 | 风格 | 适合内容 |
| :--- | :--- | :--- |
| `default` | 现代极简杂志编辑风 | 通用，默认选项 |
| `github-tech` | GitHub 开发者文档风 | 教程、源码解析 |
| `bauhaus` | 包豪斯几何设计风 | 设计类、观点文 |
| `bold-green` | 清新高对比科技绿 | 环保、健康主题 |
| `bold-navy` | 深邃藏青商务编辑风 | 深度长文、行业分析 |

<img src="examples/guide/images/theme-gallery.png" alt="五套主题对比" width="640">

不确定选哪套？一条命令出全主题交互画廊，浏览器里秒级切换、选中即复制：

```bash
md2wx gallery article.md -o gallery.html
```

### 自定义与逆向提取

主题是 YAML 文件，字体栈、配色、标题层级、代码高亮全部可调。代码高亮配色默认按代码底色明暗自动选择（深底 `one-dark` / 浅底 `friendly`），也可显式指定：

```yaml
code_highlight_style: "one-dark"   # 任意 Pygments 风格：dracula / monokai / nord / tango ...
```

还能从任意一篇微信推文或本地设计稿反向提取一套新主题：

<details>
<summary><b>learn-theme 用法展开</b></summary>

```bash
# 从一篇排版不错的微信推文学一套主题
md2wx learn-theme --url "https://mp.weixin.qq.com/s/xxxxxx" -n brand-editorial

# 从本地设计快照目录提取
md2wx learn-theme --dir ./design_folder -n brand-editorial

# 从单个 HTML 文件提取
md2wx learn-theme ./index.html -n brand-editorial

# 直接套用
md2wx article.md -t brand-editorial -c
```

提取内容覆盖 6 大组件规范与双字体栈，缺失组件由 `github-tech` 安全兜底。

</details>

## 发布到公众号草稿箱

前置条件：公众号 AppID / AppSecret（公众平台「设置与开发 → 基本配置」获取），且将本机出口 IP 加入后台 **IP 白名单**（否则报 `errcode=40164`）。

<details>
<summary><b>首次配置与一键直传</b></summary>

```bash
# 配置凭据，永久保存至 ~/.md2wx/config.yaml
md2wx config set wechat.appid "wx1234567890abcdef"
md2wx config set wechat.secret "你的AppSecret"

# 直传：本地图自动上微信永久图床并替换链接、封面上传为永久素材、创建草稿
md2wx article.md -p --title "文章标题" --author "作者" --cover images/cover.png
```

命令返回 `media_id`，登录 mp.weixin.qq.com 在草稿箱确认后手动群发。**直传只写草稿箱，不会自动群发。**

加 `--rewrite-links` 可在发布成功后生成链接回写副本：`article.published.md`，其中本地图片路径已替换为微信 CDN URL（`mmbiz.qpic.cn`，公众号生态内长期有效），方便归档"已发布版本"。**原文档保持不动**——所有修改性操作都发生在副本上，随时可回滚：

```bash
md2wx article.md -p --title "文章标题" --cover images/cover.png --rewrite-links
```

凭据读取优先级：命令行参数（`--appid` / `--secret`）> 环境变量 > `~/.md2wx/config.yaml`，方便在 CI 中注入。

> `--cover` 路径相对于输入 Markdown 文件所在目录解析，建议传绝对路径。

</details>

## 发布前体检与推文逆向

```bash
# 16+ 条微信平台硬规则检测：失效图片引用、裸外链、非法 CSS（fixed/grid/animation）
md2wx check article.md

# 抓取任意微信推文，连图带样式逆向回 Markdown
md2wx fetch "https://mp.weixin.qq.com/s/xxxxxx" -o draft.md
```

`fetch` 自动下载配图至 `draft-assets/`，居中高亮、白底卡片、实心横幅被识别还原为对应容器语法。

## 容器排版语法

标准 Markdown 之外，原生支持几种扩展容器（渲染为微信兼容的内联样式组件）：

| 语法 | 渲染效果 | 适用场景 |
| :--- | :--- | :--- |
| `> 金句` | 浅蓝底居中加粗胶囊 | 核心观点，全文 1~3 处 |
| `::: banner 标题` … `:::` | 实色横幅 | 文末 CTA，0~1 处 |
| `::: card 标题` … `:::` | 白底描边浮起卡片 | 工具/项目推荐，0~2 处 |
| `::: center` … `:::` | 居中浅灰文字条 | 致谢、时间信息 |
| `> [!TIP]` / `[!WARNING]` | 功能提示 / 琥珀警示框 | 窍门与风险 |
| `✦`（独立成行） | 居中微淡星标分隔 | 正文与文末链接间 |

## AI 技能栈（Agent Skills）

不止是 CLI。本仓库 `skills/` 目录附带 5 个 Agent Skills（SKILL.md 规范），覆盖「写作 → 配图 → 排版 → 发布」四个环节，供 Claude Code、WorkBuddy 等 Agent 直接调用：

| 技能 | 环节 | 职责 |
| :--- | :---: | :--- |
| [`md2wx-use`](../skills/md2wx-use/) | 发布 | 指导 Agent 确定性地调用 CLI 全流程：排版、画廊、抓取、提取、体检、直传 |
| [`md2wx-format`](../skills/md2wx-format/) | 排版 | 按杂志级呼吸感标准重构 Markdown，输出 `-formatted.md`，附语法决策矩阵与密度约束 |
| [`writing-with-dna`](../skills/writing-with-dna/) | 写作 | 「活人感」中文创作框架：动笔前查个人写作 DNA、交互确认标题大纲、成稿存快照 |
| [`writing-visual`](../skills/writing-visual/) | 配图 | Q 版手绘科技图解与公众号封面图自动生成，产出插图版文章副本 |
| [`writing-dna-distill`](../skills/writing-dna-distill/) | 训练 | 从历史文章蒸馏个人写作 DNA，改稿 diff 飞轮持续进化 |

### 完整工作流

```
writing-dna-distill（蒸馏个人风格，一次性）
        │
        ▼
writing-with-dna ──► writing-visual ──► md2wx-format ──► md2wx-use
   从 0 写稿            生成配图            排版重构          转换 + 直传草稿箱
```

<details>
<summary><b>安装 Skills 到你的 Agent</b></summary>

```bash
# 用户级（跨项目可用）
cp -r skills/* ~/.workbuddy/skills/

# 或项目级（仅当前项目）
cp -r skills/* <你的项目>/.workbuddy/skills/
```

安装后对 Agent 说「转成微信排版」「生成主题画廊」「按我的 DNA 写一篇 XX」即可触发对应技能。

</details>

### 仓库结构

```
Wechatwriting/                 ← 仓库根
├── md2wx-cli/                 ← CLI 包（PyPI: md2wx-cli）
│   ├── src/md2wx/             ← 源码 + themes/ 内置主题
│   ├── tests/                 ← 28 个测试用例
│   └── examples/guide/        ← 完整示例：文章 + 配图 + 三主题 HTML
└── skills/                    ← 5 个 Agent Skills
```

## 配置文件

`~/.md2wx/config.yaml`：

```yaml
wechat:
  appid: "wx1234567890abcdef"
  secret: "你的AppSecret"
  author: "你的笔名"
```

## 开发

```bash
git clone <repo-url>
cd <repo-url>/md2wx-cli
pip install -e .
python -m pytest tests/
```

## License

[MIT](LICENSE)
