md2wechat CLI demo
面向 DeepSeek Harness 的微信公众号创作与草稿插件
把 Markdown 安全地交给 DSH：建立工作副本、协作改稿、规划或生成配图、确认预览，最后创建微信公众号草稿。
插件不会覆盖原文，不会自动同意外部操作，也不会发布文章。仓库同时保留配套的 md2wechat CLI 源码与完整文档。
插件安装 · 安全边界 · 八个工具 · 完整指南 · English
版本说明
| 项目 | 本次发布 |
|---|
| dsh-md2wechat GitHub Release | v1.0.0，插件仓库首次公开发布 |
| md2wechat 主包与 CLI | 3.3.0，插件运行时严格校验的配套版本 |
| 已完成验证的 DSH | 0.1.0-rc.5 |
v1.0.0 是插件仓库的版本，不会改写 md2wechat CLI 的既有版本历史。本次不发布 npm；GitHub Release 直接提供一个主包和五个平台包，安装时选择主包与本机平台包即可。
插件安装
先从 v1.0.0 Release 下载主包 geekjourneyx-md2wechat-3.3.0.tgz，再下载一个与当前机器匹配的平台包：
| 系统 | 平台包 |
|---|
| macOS Apple Silicon | geekjourneyx-md2wechat-darwin-arm64-3.3.0.tgz |
| macOS Intel | geekjourneyx-md2wechat-darwin-x64-3.3.0.tgz |
| Linux x64 | geekjourneyx-md2wechat-linux-x64-3.3.0.tgz |
| Linux arm64 | geekjourneyx-md2wechat-linux-arm64-3.3.0.tgz |
| Windows x64 | geekjourneyx-md2wechat-win32-x64-3.3.0.tgz |
以 macOS Apple Silicon 为例，在两个文件所在目录执行：
dsh plugin --profile web add --ignore-scripts --save-exact \
./geekjourneyx-md2wechat-darwin-arm64-3.3.0.tgz \
./geekjourneyx-md2wechat-3.3.0.tgz
安装后启动 Web profile，在设置的插件列表中确认 md2wechat/dsh 已挂载并启用。第一次处理文章前，按照 DSH 插件指南 配置 md2wechat 服务、图片服务和公众号凭据。
安全边界
- 原始 Markdown 始终只读，所有结果保存在版本化工作副本中。
- 预览、后备图片生成和微信草稿创建都需要针对本次操作的明确授权；拒绝或无人回答时不会继续。
- DSH 有图片生成能力时优先使用 DSH；没有时才使用 md2wechat 已配置的图片服务。
- 草稿只能使用同一文章版本已确认的预览，避免确认内容与实际提交内容不一致。
- 流程止于微信草稿箱，不包含发布、群发或定时发布。
完整的工具、账号、授权、无界面运行和卸载说明见 docs/DSH-PLUGIN.md。
这个项目解决什么问题
md2wechat 把公众号发布流程拆成一组可验证的 CLI 命令：
| 场景 | md2wechat 提供 |
|---|
| Markdown 转微信 HTML | convert，支持预览、上传图片、创建草稿 |
| 发布前检查 | inspect --json 输出标题、摘要、图片、cover、draft readiness |
| 稳定排版 | API 模式成功时返回最终 HTML，覆盖 68 个主推高级排版场景条目和 53 个主推 ::: 语法名 |
| Agent 自动化 | capabilities、doctor、themes、layout、providers 等 discovery 命令 |
| DSH 插件工作流 | 版本化工作副本、一次性授权、预览确认与微信草稿创建 |
| 内容生产 | write、humanize、title suggest、generate_cover、generate_infographic |
| 多账号发布 | 命名公众号账号，本地只读发现，不输出 Secret |
| 微信白名单 | 高级 API 服务可提供微信接口固定出口能力 |
CLI 快速开始
如果只使用已公开的 md2wechat CLI，可以从 npm 安装；这条路径不等同于本仓库 v1.0.0 的 DSH 插件安装包。
npm install -g @geekjourneyx/md2wechat
md2wechat version --json
md2wechat config init --json
md2wechat config validate --json
API 模式预览和转换需要 md2wechat API Key；完成详细凭证配置后，先检查文章，再把 HTML 明确写入本地文件：
md2wechat inspect article.md --json
md2wechat preview article.md --output preview.html
md2wechat convert article.md --output article.html
以上命令不会上传图片或创建草稿。需要创建微信草稿时，先按同一目标检查，再显式执行副作用：
md2wechat inspect article.md --draft --cover cover.jpg --json
md2wechat convert article.md --draft --cover cover.jpg
如果使用可选的 --wechat-account，必须在 inspect 和 convert 两条命令中传入同一个账号名。
安装方式、微信凭证和 IP 白名单配置见：
专业 API
API 模式适合需要稳定输出、多人协作、批量发布或 Agent 自动化的场景。
| 能力 | 免费 AI 模式 | 专业 API 模式 |
|---|
| 输出方式 | 生成 prompt，由外部 LLM 继续处理 | 直接返回微信 HTML |
| 主题 | 3 个基础主题 | 48 个专业主题 |
| 高级排版模块 | 不解析，:::module 作为普通段落输出 | API renderer 解析 53 个推荐 :::module 语法 |
| 转换结果 | 需要外部 LLM 完成 HTML | converter 成功时返回最终 HTML |
| 发布自动化 | 适合实验 | 适合团队、客户号、矩阵号 |
专业能力包括：
申请 API 服务：关注公众号「极客杰尼」，备注「API咨询」。
公众号：极客杰尼
Agent 工作流
md2wechat 给 Agent 提供可机读接口，减少猜测和误操作。
md2wechat capabilities --json
md2wechat doctor --json
md2wechat inspect article.md --json
md2wechat themes list --json
md2wechat layout list --json
md2wechat title suggest article.md --json
md2wechat title suggest article.md --json --hook-level 2
md2wechat skills list --json
md2wechat skills read md2wechat --json
按任务选择 discovery：用 capabilities 获取聚合路由事实，用资源的 list 做选择，用 show 查看单个资源的完整定义，仅在该资源支持时使用 render。JSON stdout 是单行紧凑对象并以换行结束；人类阅读时可在命令后加 | jq，不要要求 CLI 改成缩进输出。
文章命令边界固定为：inspect 返回结构化 metadata、checks、readiness targets 和 blockers；preview 只把成功的 API converter 最终 HTML 原样写入文件；convert 执行转换，并且只在用户明确请求时执行 upload/draft 副作用。AI preview 返回 PREVIEW_ACTION_REQUIRED 且不创建输出文件，需要 readiness 时使用 inspect --json。
DSH 插件
DeepSeek Harness 用户可把 @geekjourneyx/md2wechat 安装到 Web profile，得到从工作副本、预览确认到微信草稿的受保护工作流。插件不发布文章，也不覆盖原始 Markdown。安装、八个工具、账号和授权边界见 DSH 插件指南。
这些命令适合 Claude Code、Codex、WorkBuddy、Kimi Work、Hermes Agent、OpenClaw 以及其他能调用本地 CLI 的 Agent 使用。
Agent 可以据此判断：
- 当前 CLI 支持哪些命令
- API、草稿、上传是否具备执行条件
- 某篇文章能不能发草稿
- 当前主题和排版模块是否可用
- 标题建议是否应交给宿主 Agent / 外部模型完成
- 当前二进制内置的 Agent SOP 是什么
Brand Profile 支持把长期风格偏好写入 ~/.config/md2wechat/brand.md，由 Agent 在写作和排版时读取。详见 docs/BRAND-PROFILE.md。
图片生成
md2wechat 支持两条图片路径。
先从当前二进制发现可用 preset，再调用图片 provider：
md2wechat prompts list --kind image --archetype cover --json
md2wechat prompts list --kind image --archetype infographic --json
md2wechat generate_cover --article article.md
md2wechat generate_cover --article article.md --preset cover-semantic-concept
md2wechat generate_infographic --article article.md --preset infographic-claude-warm
完整 preset 清单、用途和默认画幅以 prompts list/show --json 为准，文档只保留代表性示例。
支持 Volcengine、ModelScope、OpenRouter、OpenAI、Gemini 等服务。配置见 docs/IMAGE_PROVISIONERS.md。
使用宿主 Agent 的 Image Gen：
md2wechat generate_cover --article article.md --plan --json
md2wechat generate_infographic --article article.md --plan --json
计划模式返回 IMAGE_PLAN_READY，不请求图片 provider，不要求 IMAGE_API_KEY，也不会上传到微信。仅当当前宿主运行时实际暴露 Image Gen 工具时，Agent 才能继续执行图片生成。详见 docs/AGENT_IMAGE_GEN.md。
高级排版
API 模式支持 :::module 语法，用 Markdown 写结构化公众号排版。
:::hero
eyebrow: 深度观察
title: AI 时代的公众号写作
subtitle: 为什么读者愿意继续读下去
:::
:::callout
高级排版模块只在 API 模式渲染。
:::
查看和验证模块：
md2wechat layout list --json
md2wechat layout show hero --json
md2wechat layout validate --file article.md --json
本地 layout validate 只验证语法，不能证明远端 renderer 已部署；需要通过 API preview 或 convert 验证实际渲染。
default 主题效果
bytedance 主题效果
elegant-gold 主题效果
完整教程见 docs/LAYOUT.md。
这里的计数不是同一维度：68 是上游使用场景条目，一个语法名可以覆盖多个结构变体；53 是 layout list --json 默认返回的推荐语法名。兼容模块默认不混入推荐列表。
常用命令
| 命令 | 用途 |
|---|
inspect | 返回结构化 metadata、checks、readiness targets 和 blockers |
advise | 为已有文章推荐可选的最小增强动作 |
preview | 只写入成功 API 转换的最终 HTML；失败或 AI handoff 不新建或覆盖 |
convert | 转换 Markdown，并按显式请求执行 upload/draft 副作用 |
write | 从想法生成文章 |
humanize | 重写 AI 文章，支持 authentic 强度 |
title suggest | 生成公众号标题建议的 AI 请求 |
generate_cover | 生成封面图或图片计划 |
generate_infographic | 生成信息图或图片计划 |
upload_image | 上传图片到微信素材库 |
create_image_post | 创建微信图片消息（小绿书/newspic） |
config wechat-accounts | 查看本地多公众号账号配置 |
doctor | 本地配置体检 |
文档
许可与商业使用
本项目采用 Source Available License。个人使用、学习、评估、非营利使用免费。商业使用、SaaS、客户交付、白标、再分发和训练数据用途需要商业授权。
商业授权和 API 服务：关注公众号「极客杰尼」备注「API咨询」，或联系 skrphper@gmail.com。
