Md2wechat theme builder skill

md2wechat 主题生成器

生成“可预览、可复制、可导入”的完整公众号主题，不只制作封面或单张海报。默认独立交付 CSS 和 ZIP；项目接入是可选能力。

1. 确定工作模式

默认使用独立模式：在用户当前工作目录输出 <theme-id>.css 和 <theme-id>.zip，不查找项目，不修改应用源码。

仅当用户明确提出“接入、注册、加入、注入或修改本地 md2wechat 项目”，或明确给出项目路径并要求修改时，使用项目集成模式。不要因为附近恰好存在 md2wechat 目录就自动修改它。

使用项目集成模式时，先执行 git status --short 并保护现有改动，再读取以下文件确认当前契约：

• src/components/ConfigPanel.jsx：主题注册表及选择器。
• src/utils/markdownParser.js：实际生成的类名、列表 marker 与 Markdown 结构。
• src/utils/cssInliner.js：主题 CSS 加载和伪元素实体化。
• src/utils/wechatSanitizer.js、src/utils/wechatValidator.js：复制阶段允许的 HTML/CSS。
• 至少一套相近主题 CSS 和一套结构差异较大的主题 CSS。

随后读取 references/project-contract.md。独立模式不需要读取项目源码或此项目契约。

2. 获取设计输入

用户提供参考图时，必须用图像查看工具实际检查原图；不能只按文件名或用户概述推断。多图时区分“共同规律”和“单图偶然细节”。用户只提供风格名时，直接推导合理方向，除非缺少的信息会造成明显分歧，否则不追问。

按 references/visual-analysis.md 形成简短设计规格：

• 主题中文名、合法英文 ID、推荐图标。
• 主色、辅助色、强调色、纸面/底色、正文色。
• 字体栈、字号层级、留白密度、圆角、边框、阴影。
• 可迁移的视觉母题，以及不应复制的原图内容、Logo、人物或具体文案。
• 组件语法：封面、H1–H6、正文、强调、链接、引用、列表、代码、表格、图片、分割线、页脚。

参考图是风格证据，不是逐像素复刻目标。把海报视觉转译为适合长文阅读和公众号粘贴的排版系统。

参考图任务还必须读取 references/fidelity-workflow.md，在写 CSS 前判断主要风格贡献，选择 CSS 原生、素材增强或整页图片模式，并先写一份与参考图内容节奏相近的测试稿。不能把“颜色相同”当成“风格相同”。

3. 设计完整主题

读取 references/theme-standard.md。独立模式在用户工作目录创建 <theme-id>.css；项目集成模式在 src/themes/<theme-id>.css 创建主题。CSS 使用通用 md2wechat DOM：.card、.card-header、.card-content、.card-content-inner、.card-footer 及 Markdown 元素选择器。

要求：

• 覆盖审计脚本列出的核心 Markdown 类型。
• 关键视觉写在可被 Juice 内联的规则里。
• ::before / ::after 只用于装饰；复制链路会实体化它们。核心文本和阅读顺序不能依赖伪元素。
• 装饰性绝对定位允许使用，但不能让正文布局依赖复杂层叠；禁止 fixed、sticky、grid、CSS 变量、动画和外部字体。
• 正文字号默认 15–17px，行高 1.7–1.9；公众号正文的最大字号不超过 24px。项目预览若历史上允许更大 H1，也应优先遵守复制端约束。
• 小图不强制拉伸；图片保持 max-width:100%;height:auto;display:block;margin:0 auto。
• 主题必须在样式退化时仍保持清楚的层级和阅读顺序。
• 必须把代码块作为主题组件单独设计。读取并遵守 references/code-block-design.md：pre 与 pre code 必须继承主题的色彩、边框、材质和强调语法，禁止保留编辑器或高亮库默认的纯黑/近黑大色块。Markdown 示例也要设计为稿纸、便签、说明卡或主题化终端面板。
• 若参考图由手绘或拼贴风格主导，使用兼容的双层边框、非对称圆角、错位阴影、分段高亮和轻微不规则节奏近似，避免所有组件共享完全相同的规则几何形状。
• 把参考图的构图语法映射到 Markdown 组件，不要只做颜色映射。
• 列表 marker 只能有一个来源。在线排版工具和项目解析器会插入 marker span；主题 CSS 禁止再用 li::before、li::after 或 counter() 生成符号/编号，只能调整已有 marker span 与列表正文的间距、颜色、字号和布局，避免重复或错位。

4. 可选接入项目

独立模式跳过本节。只有用户明确要求项目集成时，才使用 apply_patch 完成以下编辑：

1. 在 ConfigPanel.jsx 的主题注册表加入 { id, name, icon }。
2. 若 markdownParser.js 存在主题列表 marker 映射，为新主题分别添加无序、有序 marker；不要依赖默认主题兜底。
3. 只有在当前主题加载机制需要显式 import/manifest 时才修改加载表；当前若按 ${themeName}.css 动态读取，就不要增加多余注册层。
4. 如 UI 文案包含硬编码主题数量，同步更新，优先改成从注册表推导，避免再次过期。
5. 使用项目现有 test.md；若覆盖不足，只追加最小必要用例，不能替换用户内容。

5. 验证

独立模式先审计生成的 CSS：

python <SKILL_ROOT>/scripts/audit_theme.py --css <THEME_CSS> --theme <THEME_ID>

项目集成模式审计 CSS 与注册状态：

python <SKILL_ROOT>/scripts/audit_theme.py --project <PROJECT_ROOT> --theme <THEME_ID>

ERROR 必须清零。WARNING 要逐项判断；核心组件缺样式、未注册、禁用 CSS、字号超限不能带警告交付。

只有项目集成模式才运行项目构建：

npm run build

两种模式都应尽可能用标准 .card 示例 HTML 检查桌面宽度和约 375px 窄屏，确认无横向溢出、文字可读、装饰不遮挡正文。项目集成模式涉及复制保真时，额外确认 inlinePseudoElements: true，并检查清洗器不会移除主题赖以成立的样式。

参考图任务不能以 CSS 审计通过代替视觉验收。按 references/fidelity-workflow.md 至少执行一次截图对照；若轮廓、字体气质、强调语法任一项低于 3/5，至少修改一轮。

所有主题都必须在测试稿中放入至少一个多行 fenced code block，并在桌面及窄屏预览中确认：不存在默认黑底、文字对比充足、长行不撑破容器、语言标签即使存在也不突兀。

6. 交付

完成 CSS 后，必须生成一个可直接导入在线排版工具的 ZIP，不把打包视为可选步骤。

独立模式使用：

python <SKILL_ROOT>/scripts/package_theme.py `
  --css <THEME_CSS> `
  --theme <THEME_ID> `
  --name <THEME_NAME> `
  --output <OUTPUT_ZIP> `
  --description <THEME_DESCRIPTION>

项目集成模式可将 --css <THEME_CSS> 替换为 --project <PROJECT_ROOT>。

ZIP 根目录必须包含：

• theme.json：至少包含 id、name、version、description、css，其中 css 固定指向 theme.css。
• theme.css：与最终通过审计的独立 CSS 或项目主题 CSS 一致；打包脚本会在缺失时补充在线导入校验所需的 [data-theme="<THEME_ID>"] 作用域标识。

打包后必须检查 ZIP 可读取、上述两个文件存在、清单能解析、清单 ID 与目标主题一致、CSS 非空。不要只压缩源文件后假定包可用。除非用户另有指定，将 ZIP 输出到用户当前工作目录，文件名使用 <THEME_ID>.zip。

最终报告主题名称、ID、提取的关键视觉特征、CSS 与 ZIP 绝对路径、审计结果，并提供可点击的 ZIP 链接。只有实际执行项目集成时才报告项目修改和构建结果。明确区分“已在浏览器验证”和“仍需用户在微信编辑器实测”。不要声称仅凭浏览器截图即可证明微信端 100% 一致。

若用户要求用参考图实际生成主题，直接创建 CSS 并打包 ZIP，而不是只解释流程；除非用户明确要求，不注入任何本地项目。