Markdown Publisher for WeChat & Zhihu

本项目解决包含 Mermaid 代码的 Markdown 文章无法直接粘贴到内容平台的问题：它会把 Mermaid 图表保留为清晰图片，同时保留整篇文章的富文本排版，让内容可以直接复制到微信公众号或知乎。扩展不会登录平台、直接发布、接入图床，也不会上传文章或图片。

安装

从本地 VSIX 安装

1. 取得 markdown-publisher-wechat-zhihu-*.vsix。
2. 在 VS Code 扩展视图右上角选择“视图和更多操作…” → “从 VSIX 安装…”。
3. 选择 VSIX，安装后按提示重新加载窗口。

也可以运行：

code --install-extension markdown-publisher-wechat-zhihu-0.0.10.vsix

开发者可在仓库中执行 npm ci && npm run build，再用 npx @vscode/vsce package --no-dependencies 生成本地 VSIX。VSIX 是构建产物，不应提交到 Git。

从 Marketplace 安装

首次发布完成后，可在 VS Code 扩展视图中搜索 Markdown Publisher for WeChat & Zhihu，或从 Marketplace 扩展详情页点击 Install。发布前可继续使用本地 VSIX。

四步使用流程

1. 在 VS Code 中打开一个 Markdown 文档。
2. 从命令面板执行 Markdown Publisher: Open Preview，预览会固定绑定到该文档并显示在编辑器右侧。
3. 在预览工具栏选择“简洁”“技术”或“优雅”主题，并按需调整排版设置。
4. 点击“复制到公众号”或“复制到知乎”，然后在目标平台编辑器中粘贴整篇文章。

复制时会建立当前文章快照。若关键媒体渲染失败，扩展默认停止复制且不覆盖原剪贴板；确认诊断后，可显式选择“忽略错误并复制”，错误位置会保留可见占位内容。

支持的 Markdown

支持 CommonMark 与常用技术写作扩展，包括标题、段落、强调、链接、列表、引用、代码块与高亮、表格、任务列表、删除线、自动链接、脚注、目录、提示块、Mermaid，以及 $...$、\\(...\\) 行内公式和 $$...$$、\\[...\\] 块公式。

发布时有以下媒体规则：

• Mermaid 和数学公式会转成静态 PNG，不要求目标平台执行 JavaScript 或识别 LaTeX。
• 普通图片会被解析为可复制的嵌入资源，输出中不应出现本机 file: 地址。
• GIF 为保证稳定粘贴，会在复制时格栅化为静态 PNG（当前帧/浏览器捕获帧）；第一版不保留动画。
• 深色预览主题会为发布图片生成浅色背景，避免粘贴后不可读。

图片路径

• 相对路径以当前 Markdown 文档所在目录为基准，例如图片地址可写为 ./images/demo.png。
• 受信任工作区可读取文档目录或工作区范围内的绝对/相对本地图片。
• 不受信任工作区只允许文档目录内的本地图片；工作区其他目录和外部路径会被拒绝。
• 网络图片只允许 http 和 https，并受超时、单图大小与文章总资源大小限制。
• data: 图片必须是受支持且内容与 MIME 类型一致的图片。

设置与自定义 CSS

设置支持用户级默认值和工作区级覆盖，工作区值优先。可在设置中搜索 markdownPublisher，或在预览设置抽屉中选择写入范围。常用设置包括主题、字体、字号、行距、段距、内容宽度、主色、标题样式、代码主题、图片圆角/间距和网络资源限制。

执行 Markdown Publisher: Open Custom CSS 会打开真实 CSS 文件。工作区默认路径是 .vscode/markdown-publisher.css：

/* 规则仅作用于文章根节点；发布时只保留可安全内联的属性 */
h2 {
  color: #1677ff;
  border-bottom: 1px solid #d9e8ff;
}

blockquote {
  background: #f6f8fa;
  padding: 12px 16px;
}

自定义 CSS 禁止远程 @import、脚本型 URL 和越界文件路径。无法安全应用的规则会产生诊断，并回退到仍然有效的基础主题。

网络、安全与隐私

• Markdown HTML 会经过清理；文章中的脚本、事件处理器和危险 URL 不会执行。
• Mermaid 使用严格安全模式，Webview 使用最小内容安全策略和本地资源范围。
• 网络资源默认超时 15 秒，单资源上限 20 MiB，整篇资源总量上限 100 MiB；这些值可按需要向下调整。
• 扩展不把文章正文、图片字节、生成的 HTML 或配置上传到扩展自有服务器，也不插入水印、品牌标记或跟踪信息。
• 网络图片仍会由本机直接请求其原始 URL，因此图片服务器可见正常请求元数据。离线或受限网络环境中，请改用工作区内本地图片。
• 扩展不会使用你的微信或知乎账号；粘贴和最终发布均由用户在目标平台完成。

错误与排查

Mermaid/公式语法错误、图片不存在或越权、网络超时、资源过大、自定义 CSS 无效、剪贴板写入失败都会显示明确诊断。存在关键媒体错误时，默认阻断复制；“忽略错误并复制”必须由用户主动选择，且不会让内容静默消失。

如果富文本剪贴板 API 在点击时不可用，扩展会在同一次点击中尝试 DOM copy 回退。若系统异步拒绝富文本写入，扩展不会静默覆盖剪贴板为纯文本，而会显示“重新复制富文本”和“复制纯文本”两个按钮；再次点击会建立新的系统用户授权时机。排查时请记录 VS Code 版本、操作系统、目标平台、浏览器版本和精确失败表现，但不要提交包含私密正文或图片字节的日志。

真实平台人工兼容矩阵

以下项目必须在每次发布前，用 tests/fixtures/full-article.md 分别粘贴到真实编辑器检查。当前环境未使用任何用户账号或浏览器执行真实粘贴，因此不能声称微信公众号或知乎已经验证。

实际验证时，请为每个平台补充验证日期、浏览器及版本、平台编辑器版本（若可见）、结果和已知差异。如果平台未上传 data: 图片，应停止发布并记录精确表现；不要悄悄引入图床或账号授权。

开发与发布检查

发布到 VS Code Marketplace

1. 打开 Visual Studio Marketplace Publisher 管理页，创建或确认 Publisher ID 为 qiangcraft。

2. 创建发布凭据时，个人访问令牌应选择所有可访问组织，并授予 Marketplace (Manage) 权限。令牌只应输入本机 vsce 提示框，不要提交、分享或粘贴到聊天中。自动化发布优先采用 Microsoft Entra ID，避免依赖即将淘汰的全局 PAT。

3. 在本机登录 Publisher：

   npx @vscode/vsce login qiangcraft
   

4. 发布前运行下面的测试、构建和 VSIX 检查命令。

5. 确认包内容和版本无误后发布：

   npx @vscode/vsce publish --no-dependencies
   

   上述命令分别包含 vsce login qiangcraft 和 vsce publish --no-dependencies。也可以在 Publisher 管理页手动上传已检查的 VSIX。

发布是外部状态变更；请只在版本、说明和包内容都确认无误后执行。本仓库的构建与打包流程不会自动发布。

npm ci
npm run test:unit
npm run typecheck
npm run build
npm run test:integration
npx @vscode/vsce package --no-dependencies
unzip -l markdown-publisher-wechat-zhihu-*.vsix

集成测试默认下载并运行 VS Code 1.96.0。可通过 VSCODE_TEST_VERSION 选择其他兼容版本，或通过 VSCODE_TEST_EXECUTABLE 使用已准备好的 VS Code 可执行文件。下载、GUI 或网络受限时，测试应明确失败并保留原始错误，不能把未运行记为通过。

当前 @vscode/test-electron 运行器会向 Extension Host 传入 --disable-workspace-trust，因此无法在这套集成 runner 中建立真实的“不受信任工作区”场景。生产接线已由边界单元测试验证：当 vscode.workspace.isTrusted 为 false 时，工作区外图片会在读取前被拒绝；正式发布前仍应在可启动真实不受信任工作区的 VS Code 环境中补做一次 Extension Host 验证。