// 将普通技术博客 Markdown 源稿整理为高质量 MDX 博客文章，自动处理公式、图片、代码块、裸花括号、移动端公式滚动等 MDX 兼容性问题。适用于算法原理讲解、工程实践总结、框架机制解析、normal 技术博客、公式排版、手机端适配等常规技术博客场景，不适用于带 .html / .ipynb 联动的论文精读场景。
Read a theory markdown file (model/algorithm explanation), then generate a companion Jupyter notebook (.ipynb) via a four-phase pipeline: Research → Plan → Implement → Review. Every notebook contains TWO parallel paths in a SINGLE file: - Learning path: understand the model by building/running key components - Engineering path: use mature toolchains for production-grade implementation Path depth and form adapt independently based on feasibility decisions. All implementations target free Colab (free T4 GPU available; must also work on CPU as fallback). Final notebook includes interview-oriented extension and project expression content.
Convert raw markdown notes, lecture materials, or fragmented technical drafts into a well-structured, publication-ready technical blog post. The transformation must: - Preserve all technical content, formulas, and code blocks exactly. - Improve logical structure and section hierarchy. - Introduce meaningful headings and subheadings where missing. - Clarify complex concepts without oversimplifying them. - Eliminate redundancy, incomplete thoughts, and fragmented sentences. - Ensure consistent terminology and notation throughout. - Improve readability while maintaining technical depth. - Avoid adding unsupported claims or fabricating information. - Avoid marketing language or exaggerated tone. - Maintain a professional, educational writing style. When applicable: - Add a concise contextual introduction (no fluff). - Add a structured summary or key takeaways section. - Highlight core insights, design motivations, and trade-offs. - Make implicit reasoning explicit. The result should read like a carefully edited t
将论文精读笔记（.md + .html + .ipynb）合并为高质量 MDX 博客文章，自动处理公式、图片、代码等 MDX 兼容性问题。触发词：论文精读、paper reading、MDX 博客、论文笔记。
| name | tech-blog-mdx |
| description | 将普通技术博客 Markdown 源稿整理为高质量 MDX 博客文章，自动处理公式、图片、代码块、裸花括号、移动端公式滚动等 MDX 兼容性问题。适用于算法原理讲解、工程实践总结、框架机制解析、normal 技术博客、公式排版、手机端适配等常规技术博客场景，不适用于带 .html / .ipynb 联动的论文精读场景。 |
| argument-hint | [技术博客 markdown 文件路径或主题关键词] |
将普通技术博客的 Markdown 源稿整理为一篇可发布、可构建、移动端友好的 MDX 博客文章。
本 skill 继承 paper-reading 的 MDX 兼容性规则、公式排版要求、构建验证流程和移动端适配经验，但输入简化为常规技术博客，不依赖 .html AI 总结页或 .ipynb Notebook。
适用场景：算法原理讲解、框架机制解析、工程实践复盘、技术方案说明、源码导读。
不适用场景：需要 .html 总结页或 .ipynb 代码实战联动的论文精读博客（请使用 paper-reading）。
| 用途 | 路径 |
|---|---|
| 博客文章目录 | app/blog/posts/ |
| MDX 组件定义 | app/components/mdx.tsx |
| MDX 编译管道 | app/blog/utils.ts |
| 全局样式 | app/tailwind.css |
| 静态资产根目录 | public/static/blog/[slug]/ |
| 博客路由 | /blog/[slug] |
若当前项目不存在上述结构，先停在 Phase 0，要求用户提供博客项目根目录，不进入生成阶段。
使用 AskUserQuestion 收集以下信息。
请用户提供：
.md 文件路径：技术博客原始稿件（必需）.md 中可解析，可不单独提供）降级策略：
- 缺少图片目录 → 仅处理
.md中已能解析的图片引用- 缺少封面图 → frontmatter 可暂不写
image，但需给出警告- 若源稿不是 Markdown → 停止并要求用户先转换为
.md
收集以下字段（用于 frontmatter 和文章生成）：
| 字段 | 示例 | 用途 |
|---|---|---|
| 博客 slug | resnet-guide | URL 路径 + 资产目录名 |
| 中文标题 | ResNet 原理与残差结构解析 | frontmatter title |
| 英文标题（可选） | Understanding ResNet | 文内或 SEO 辅助 |
| 中文摘要 | 从退化问题出发，系统解释残差连接为何有效 | frontmatter summary |
| 标签 | [Deep Learning, ResNet, Computer Vision] | frontmatter tags |
| 发布日期（可选） | 2026-04-01 | frontmatter publishedAt，默认当天 |
| 博客项目根目录 | /path/to/blog | 写入 app/blog/posts/ 与 public/static/blog/ |
若用户未提供
publishedAt，默认使用当天日期。
读取用户提供的 .md 文件，提取以下信息并输出分析摘要。
文章结构：
数学公式：
$...$$$...$$\(...\)、单行 $$...$$、公式截图图片与资源：
<img> 标签代码内容：
MDX 风险点：
**...** 加粗（需转为 <strong>）{}（需转义）输出分析摘要供用户确认后再继续。
app/blog/posts/[slug].mdx 已存在，请求用户确认是否覆盖（默认不覆盖）public/static/blog/[slug]/.md 中实际使用的本地图片复制到该目录旧路径 -> /static/blog/[slug]/filenamehasCoverImage、hasLocalImages仅复制正文实际引用的本地图片，不复制无引用资产。
按以下标准结构生成 MDX 文件 app/blog/posts/[slug].mdx。
---
title: '[中文博客标题]'
publishedAt: '[YYYY-MM-DD]'
summary: '[一句话中文摘要]'
draft: false
image: '/static/blog/[slug]/[封面图]'
tags: [tag1, tag2, ..., Tech Blog]
---
规则：
title、publishedAt、summary、draftimage、tagstags 最后必须包含 Tech Blogimage，但需在检查结果中明确警告按以下顺序组织内容，每个部分作为 ## 二级标题。
### 三级标题 分解核心模块）如果原稿缺少其中某一部分，可在不编造事实的前提下做结构重组，但不能虚构实验结果或外部结论。
以下规则必须逐条遵循。
<strong> 标签❌ **这是加粗文本**
✅ <strong>这是加粗文本</strong>
统一使用 <strong>，避免列表、公式、标点混排时的 MDX 解析歧义。
$...$❌ 维度为 \(d_{model}\)
✅ 维度为 $d_{model}$
$ 前后不加多余空格。
$$ 块❌ $$y = Wx + b$$
✅
$$
y = Wx + b
$$
要求：
$$ 必须独占一行\lbrace / \rbrace❌ 
❌ <img src="media/fig1.png" />
✅ 
规则：
public/static/blog/[slug]/public 前缀<img> 标签✅
```python
def residual_block(x):
return x
```
规则：
text、bash、json、yaml 等明确类型| 方案 | 优点 | 缺点 |
|------|------|------|
| A | 简单 | 灵活性低 |
表格内加粗同样使用 <strong>。
❌ 配置项 {a: 1, b: 2}
✅ 配置项 {a: 1, b: 2}
✅ 数学集合 $\lbrace a, b \rbrace$
MDX 会将 {...} 解析为 JSX 表达式，必须转义。
必填：title、publishedAt、summary、draft。
强烈建议：image、tags。tags 必须包含 Tech Blog。
若文章包含较多 display 数学公式，必须确认 app/tailwind.css 中存在以下规则（若缺失则补充）：
.katex-display {
display: block;
overflow-x: auto;
overflow-y: hidden;
-webkit-overflow-scrolling: touch;
}
.katex-display > .katex {
white-space: nowrap;
}
根因：KaTeX 渲染的 .katex-display 默认是内联结构，不转为块级元素时移动端横向滚动无法生效。
生成 MDX 后，执行以下自动检查并修正。
| 编号 | 检查项 | 检测方法 |
|---|---|---|
| R1 | 无 **...** 加粗语法 | Grep \*\*[^*]+\*\*，排除代码块 |
| R2 | Inline 数学使用 $...$ | 确认无 \(...\) |
| R3 | Display 数学 $$ 独占行 | 检查 $$ 前后无其他字符 |
| R4 | 正文插图路径合法 | 只允许 /static/blog/... 或明确批准的稳定外链 |
| R5 | 代码块语法合法 | 围栏成对；尽量带语言标注 |
| R6 | 表格语法正确 | 检查表头、分隔行、列数一致 |
| R7 | 无裸花括号 | 排除数学模式、代码块、合法 JSX 属性后检查 { |
| R8 | 无不必要原始 HTML | 检查 <img>、内联样式、危险标签 |
| R9 | UTF-8 无 BOM | 检查文件头字节 |
| R10 | Frontmatter 字段完整 | 验证必填字段 + tags 含 Tech Blog |
| R11 | KaTeX 移动端样式存在 | 检查 app/tailwind.css 中对应规则 |
| 编号 | 检查项 |
|---|---|
| Q1 | 正文结构是否符合 3.2 节定义的标准顺序 |
| Q2 | 公式是否在 KaTeX 支持范围内 |
| Q3 | 图片文件是否实际存在于 public/static/blog/[slug]/ |
| Q4 | 代码块前是否有必要的引导说明 |
| Q5 | 是否存在内容编造、夸大或无依据结论 |
| Q6 | 参考资料是否真实、相关、不过量 |
规则：
R 类失败必须自动修正后重新检查Q 类问题输出警告供用户决策，不得擅自编造内容来“补齐结构”yarn build
输出摘要，等待用户最终确认：
## 发布摘要
- 文件：app/blog/posts/[slug].mdx
- 标题：[中文标题]
- 标签：[tags]
- 资产目录：public/static/blog/[slug]/
- 图片数量：[N] 张
- 代码块数量：[N] 个
- 公式数量：[N] 处
- 构建状态：✅ 通过
确认发布？（draft 字段已设为 false）
/commit