بنقرة واحدة
paper-reading
// 将论文精读笔记(.md + .html + .ipynb)合并为高质量 MDX 博客文章,自动处理公式、图片、代码等 MDX 兼容性问题。触发词:论文精读、paper reading、MDX 博客、论文笔记。
// 将论文精读笔记(.md + .html + .ipynb)合并为高质量 MDX 博客文章,自动处理公式、图片、代码等 MDX 兼容性问题。触发词:论文精读、paper reading、MDX 博客、论文笔记。
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
将普通技术博客 Markdown 源稿整理为高质量 MDX 博客文章,自动处理公式、图片、代码块、裸花括号、移动端公式滚动等 MDX 兼容性问题。适用于算法原理讲解、工程实践总结、框架机制解析、normal 技术博客、公式排版、手机端适配等常规技术博客场景,不适用于带 .html / .ipynb 联动的论文精读场景。
| name | paper-reading |
| description | 将论文精读笔记(.md + .html + .ipynb)合并为高质量 MDX 博客文章,自动处理公式、图片、代码等 MDX 兼容性问题。触发词:论文精读、paper reading、MDX 博客、论文笔记。 |
| argument-hint | [论文关键词,如 resnet] |
将论文精读的三份源材料(Markdown 笔记、HTML AI 总结、Jupyter Notebook 代码实现)合并为一篇高质量的 MDX 博客文章。
本 skill 固化了 Transformer 论文精读博客开发中积累的全部 MDX 踩坑经验,确保每篇论文精读博客都能一次构建通过。
金标准模板:app/blog/posts/attention-is-all-you-need.mdx
| 用途 | 路径 |
|---|---|
| 博客文章目录 | app/blog/posts/ |
| MDX 组件定义 | app/components/mdx.tsx |
| PaperCard 组件 | app/components/paper-card.tsx |
| MDX 编译管道 | app/blog/utils.ts |
| 全局样式 | app/tailwind.css |
| 静态资产根目录 | public/static/blog/[slug]/ |
| 博客路由 | /blog/[slug] |
使用 AskUserQuestion 收集以下信息:
问题 1 — canonical source 路径
优先要求用户按以下 canonical source layout 提供或确认论文目录:
papers/<Paper>/notes.md
papers/<Paper>/ai-summary.html
papers/<Paper>/code.ipynb
规则:
papers/<Paper>/ 是唯一 canonical source 目录notes.md 是主要内容来源ai-summary.html 可选;缺失时不生成「AI 总结」链接code.ipynb 可选;缺失时不生成「代码实战」链接,跳过代码实战章节papers/<Paper>/ 外的重复源文件/目录不应继续作为工作输入;允许的重复仅限发布产物 public/static/blog/[slug]/典型非 canonical 输入示例:
08_BERT_代码实战.ipynb18_AlphaFold2_代码实战.ipynb解释2_assets/降级策略:
- 缺少
ai-summary.html→ PaperCard 不生成「AI 总结」链接- 缺少
code.ipynb→ PaperCard 不生成「代码实战」链接,跳过代码实战章节PaperCard.links至少保留「论文原文」
问题 2 — 论文元信息
收集以下字段(用于 frontmatter 和 PaperCard):
| 字段 | 示例 | 用途 |
|---|---|---|
| 英文论文标题 | Attention Is All You Need | PaperCard title |
| 作者与机构 | Vaswani et al. — Google Brain | PaperCard description |
| 会议/年份 | NeurIPS 2017 | PaperCard description |
| arXiv URL | https://arxiv.org/abs/1706.03762 | PaperCard 论文链接 |
| 博客 slug | transformer | URL 路径 + 资产目录名 |
| 中文标题 | Transformer 论文精读 | frontmatter title |
| 中文摘要 | Transformer 模型论文精读笔记… | frontmatter summary |
| 标签 | [Deep Learning, Transformer, Paper Reading] | frontmatter tags |
publishedAt默认使用当天日期,无需用户提供。 Colab 链接不再作为用户输入字段;若存在papers/<Paper>/code.ipynb,应基于该 canonical 路径生成代码实战链接。
在分析内容前,先统一并验证源材料布局:
papers/<Paper>/08_BERT_代码实战.ipynb),先迁移/重命名为 papers/<Paper>/code.ipynbpapers/<Paper>/ 下,先迁移/重命名为 notes.md / ai-summary.html解释_assets/、解释2_assets/),先迁移到当前 paper 的 source 体系中,再继续生成流程public/static/blog/[slug]/...papers/<Paper>/ 外的重复源文件/目录输出一份 preflight 摘要,明确:
读取 canonical source 文件,提取以下信息并输出分析摘要:
从 .md 文件提取:
$...$ 和 display $$...$$)<strong>)从 .html 文件提取:
从 .ipynb 文件提取:
输出摘要供用户确认后再继续。
app/blog/posts/[slug].mdx 已存在,请求用户确认是否覆盖(默认不覆盖)public/static/blog/[slug]/papers/<Paper>/notes.md 中引用的图片复制到该目录papers/<Paper>/ai-summary.html,复制到该目录并命名为 ai-summary.html/static/blog/[slug]/filename)hasAiSummary、hasColabpublic/static/blog/[slug]/ 是发布态输出目录,不是源目录;源文件仍以 papers/<Paper>/ 为准按以下标准结构生成 MDX 文件 app/blog/posts/[slug].mdx。
---
title: '[中文博客标题]'
publishedAt: '[YYYY-MM-DD]'
summary: '[一句话中文摘要]'
draft: false
image: '/static/blog/[slug]/[封面图]'
tags: [tag1, tag2, ..., Paper Reading]
---
紧跟 frontmatter 之后,前后各留一个空行。根据可用性标记动态组装 links 数组:
若存在 papers/<Paper>/code.ipynb,则“代码实战”链接必须基于该 canonical notebook 路径生成;禁止继续使用旧的带编号 notebook 文件名。
完整示例(三个链接都可用时):
<PaperCard
title="Attention Is All You Need"
description="Vaswani et al. — NeurIPS 2017 (Google Brain)"
links={[
{ label: "论文原文", url: "https://arxiv.org/abs/1706.03762" },
{ label: "AI 总结", url: "/static/blog/transformer/ai-summary.html" },
{ label: "代码实战", url: "https://colab.research.google.com/github/yunshenwuchuxun/yunshen-blogv1/blob/main/papers/Transformer/code.ipynb" },
]}
/>
最小示例(仅论文链接):
<PaperCard
title="[论文标题]"
description="[作者] — [会议/年份] ([机构])"
links={[
{ label: "论文原文", url: "[arXiv URL]" },
]}
/>
按以下顺序组织内容,每个部分作为 ## 二级标题:
### 三级标题)papers/<Paper>/code.ipynb 则跳过。若存在 notebook,则徽章链接必须指向该 canonical code.ipynb)以下规则从实际踩坑中总结,必须逐条遵循。
<strong> 标签❌ **这是加粗文本**
✅ <strong>这是加粗文本</strong>
**...** 在普通段落中通常可正常解析,但在「列表项 + 公式 + 标点」混排时存在解析歧义。统一使用 <strong> 确保风格一致、消除边界情况。
$...$❌ 维度为 \(d_{model}\)
✅ 维度为 $d_{model}$
$ 符号前后无多余空格。pipeline 已配置 remarkMath + rehypeKatex。
$$...$$ 三行格式居中❌ $$h_i^{(l+1)} = \sigma(\sum_{j} \alpha_{ij} Wh_j)$$
✅
$$
h_i^{(l+1)} = \sigma(\sum_{j} \alpha_{ij} Wh_j)
$$
$$ 必须独占一行(三行格式:开 $$ / 公式 / 闭 $$),单行 $$...$$ 无法居中\text{} 在 KaTeX display 模式下可正常工作\lbrace / \rbrace 替代 \{ / \},避免 MDX 解析冲突❌ 
❌ 
✅ 
正文插图必须位于 public/static/blog/[slug]/ 下,MDX 中省略 public 前缀。
允许外链徽章图(如 Colab badge):
✅ [](https://colab.research.google.com/github/yunshenwuchuxun/yunshen-blogv1/blob/main/papers/Transformer/code.ipynb)
若使用 Colab 链接,其目标 notebook 必须是 canonical papers/<Paper>/code.ipynb,不能是旧的带编号 notebook 文件名。
✅
```python
def attention(Q, K, V):
...
```
pipeline 已配置 rehype-pretty-code(Dracula 主题)。纯输出/示意块允许无语言标注,推荐使用 ```text。
✅
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| a | b | c |
pipeline 已配置 remarkGfm。表格内加粗同样使用 <strong>。
❌ 集合 {a, b, c}
✅ 集合 \{a, b, c\} (数学模式内)
✅ 集合 {a, b, c} (正文中)
MDX 将 {...} 解析为 JSX 表达式,裸花括号会导致编译错误。
必填:title、publishedAt、summary、draft。强烈建议:image、tags。tags 必须包含 Paper Reading。
论文精读博客含大量数学公式,必须确认 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 是 <span> 内联元素,overflow 属性对内联元素无效。必须 display: block 转为块级元素后 overflow-x: auto 才能生效。
此规则为全局基础设施,已存在则跳过,不属于"修改现有文件"范畴。
生成 MDX 文件后,执行以下自动检查并修正。
| 编号 | 检查项 | 检测方法 |
|---|---|---|
| R1 | 无 **...** 加粗语法 | Grep \*\*[^*]+\*\*,排除代码块内的匹配 |
| R2 | Inline 数学使用 $...$ | 确认无 \(...\) 语法 |
| R3 | Display 数学 $$ 独占行 | 检查 $$ 前后无其他字符 |
| R4 | 正文插图路径合法 | 允许 /static/blog/... 和 https:// 外链徽章图 |
| R5 | 代码块语法合法 | 检查围栏成对;无语言标注时给出警告 |
| R6 | 表格语法正确 | 检查 | 分隔符和对齐行 |
| R7 | 无裸花括号 | Grep 非数学模式、非代码块、非 JSX 属性中的 { |
| R8 | JSX 格式正确 | Tab 缩进 + 组件块前后空行 + 双引号属性 |
| R9 | UTF-8 无 BOM | 检查文件头字节 |
| R10 | Frontmatter 字段完整 | 验证必填字段 + tags 含 Paper Reading |
| R11 | KaTeX 移动端样式存在 | 检查 app/tailwind.css 含 .katex-display { display: block; overflow-x: auto } |
| R12 | 所有 Colab / GitHub notebook 链接都指向 canonical code.ipynb | 检查 notebook URL 必须以 /code.ipynb 结尾,禁止旧编号 notebook 文件名 |
| R13 | 不依赖 paper 目录外原始资产路径 | 检查 notes.md 与生成结果中不存在 解释_assets、解释2_assets 或其他 papers/<Paper>/ 外源路径 |
| 编号 | 检查项 |
|---|---|
| Q1 | 正文结构是否符合 3.3 节定义的标准顺序 |
| Q2 | 数学公式是否在 KaTeX 支持范围内 |
| Q3 | 图片文件是否实际存在于 public/static/blog/[slug]/ |
| Q4 | PaperCard 的 links 本地路径对应文件是否存在 |
| Q5 | 代码片段前是否有文字引导说明 |
| Q6 | 参考文献是否为写博客时参考的资料(论文原文、教程视频、技术博客等) |
R 类检查失败必须自动修正后重新检查。Q 类检查如有问题,输出警告供用户决策。
额外要求:若发现旧 notebook 文件名链接、根目录重复源目录、或 解释_assets / 解释2_assets 这类遗留引用,必须先完成 canonicalization,再继续生成。
pnpm build
输出摘要,等待用户最终确认:
## 发布摘要
- 文件:app/blog/posts/[slug].mdx
- 标题:[中文标题]
- 标签:[tags]
- 资产目录:public/static/blog/[slug]/
- 图片数量:[N] 张
- 代码块数量:[N] 个
- 构建状态:✅ 通过
确认发布?(draft 字段已设为 false)
papers/<Paper>/{notes.md, ai-summary.html, code.ipynb},先归一化再生成解释_assets/、解释2_assets/ 仅可作为待迁移遗留输入,不能继续作为稳定 source of truthpublic/static/blog/[slug]/ 下的图片和 ai-summary.html 属于发布输出,可与 source 并存/commit