什么是 Markdown？

Markdown 是一种轻量级标记语言，由 John Gruber 于 2004 年创建。它让你用简单的纯文本格式编写文档，然后转换成结构化的 HTML。

32语法要点

2主题模式

∞实时练习

✏️

简单易学

语法规则不超过 10 分钟即可掌握，纯文本书写不依赖特定软件。

🌍

用途广泛

GitHub、博客、笔记软件、技术文档、README 文件都在使用 Markdown。

🤖

AI 时代必备

AI 对话、Prompt 工程、Skill 文件、Agent 配置大量使用 Markdown 格式。

🎯

专注内容

不用在格式上花时间，写出的文档可以轻松转换为 HTML、PDF 等格式。

💡 如何使用本教程

点击上方标签切换分类，每个语法点可以展开/收起。左侧导航栏可以快速跳转。

Markdown 文件通常以 .md 或 .markdown 为扩展名。建议切换到「实战工具」标签，边学边在练习场中动手试试！

H标题

使用 # 号创建标题，1~6 个 # 对应一到六级标题。# 和文字之间需要一个空格。

📝 示例

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

一级标题

二级标题

三级标题

四级标题

五级标题

六级标题

✅ 小贴士

一般文章最多用到三级标题即可。# 后面一定要加空格。另外也可以用 === 和 --- 在文字下方来表示一级和二级标题（不推荐）。

段落之间用空行分隔。段落内换行：行尾加两个空格后回车，或使用 <br>。

📝 示例

这是第一个段落。

这是第二个段落。

这一行末尾有两个空格  
所以这里会换行。

这是第一个段落。

这是第二个段落。

这一行末尾有两个空格
所以这里会换行。

⚠️ 注意

只是简单回车（不加空行）在大多数渲染器中不会换行。需要空行创建新段落，或行尾两个空格软换行。

用星号 * 或下划线 _ 包裹文本来添加强调。

📝 示例

*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体*** 或 ___粗斜体___
这是 **重点** 和 *强调*

斜体或斜体

粗体或粗体

粗斜体 或 粗斜体

这是重点和强调

✅ 小贴士

推荐统一用星号 *，兼容性更好，在单词中间也能正常使用。

使用 > 创建引用块，可嵌套，内部可包含其他 Markdown 元素。

📝 示例

> 这是一个引用块。
> 可以跨多行。

> 引用中可以有 **粗体**。
>
> > 嵌套的引用。

这是一个引用块。可以跨多行。

引用中可以有粗体。
嵌套的引用。

支持无序列表（-/*/+）和有序列表（1.），可嵌套。

📝 无序列表

- 苹果
- 香蕉
  - 蜜橘
  - 脐橙
- 葡萄

苹果
香蕉
- 蜜橘
- 脐橙
葡萄

📝 有序列表

1. 第一步
2. 第二步
   1. 子步骤 a
   2. 子步骤 b
3. 第三步

第一步
第二步
1. 子步骤 a
2. 子步骤 b
第三步

✅ 小贴士

嵌套列表缩进 2~4 个空格。有序列表数字不必按序，但建议按序编号。

反引号 ` 包裹行内代码，三个反引号 ``` 创建代码块（可指定语言）。

📝 行内 + 代码块

行内代码：`console.log("hi")`

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

行内代码：console.log("hi")

function greet(name) {
  return `Hello, ${name}!`;
}

def greet(name):
    return f"Hello, {name}!"

💡 常用语言标识

javascript python java html css bash json sql go rust typescript c cpp

Markdown 支持多种链接写法。

📝 示例

[普通链接](https://example.com)

[带标题](https://example.com "悬停提示")

[引用式链接][link-id]

[link-id]: https://example.com "标题"

普通链接

带标题

引用式链接

引用式适合多次使用同一链接，集中管理 URL。

图片语法同链接，前面加 !。方括号内是替代文本（alt）。

📝 示例

![替代文本](图片URL)

![风景](https://example.com/photo.jpg "标题")

[![可点击图片](图片URL)](链接URL)

图片将显示在此处

调整大小可用 HTML：<img src="url" width="300">

三个或更多 -、* 或 _ 创建分割线。

📝 示例

上面的内容

---

下面的内容

***

上面的内容

下面的内容

▦表格

用 | 分隔列，- 分隔表头。:--- 左对齐，:---: 居中，---: 右对齐。

📝 示例

| 左对齐   | 居中对齐    | 右对齐     |
| :------- | :---------: | ---------: |
| 单元格   | 单元格      | 单元格     |
| 左       | 中          | 右         |

左对齐	居中对齐	右对齐
单元格	单元格	单元格
左	中	右

- [ ] 未完成，- [x] 已完成。

📝 示例

- [x] 学习标题语法
- [x] 学习粗体和斜体
- [ ] 学习代码块
- [ ] 完成在线练习

学习标题语法
学习粗体和斜体
学习代码块
完成在线练习

两个波浪号 ~~ 包裹文本。

📝 示例

~~已删除的文本~~

价格：~~￥99~~ ￥49

~~已删除的文本~~

价格：~~￥99~~ ￥49

正文用 [^标记] 引用，文末用 [^标记]: 内容 定义脚注。

📝 示例

Markdown 很流行[^1]。

它被广泛使用[^note]。

[^1]: 由 John Gruber 于 2004 年创建。
[^note]: GitHub、Reddit 等平台均支持。

Markdown 很流行^[1]。

它被广泛使用^[2]。

由 John Gruber 于 2004 年创建。
GitHub、Reddit 等平台均支持。

⚠️ 兼容性

脚注为扩展语法，GitHub 支持，但部分简单渲染器可能不支持。

GFM（GitHub Flavored Markdown）会自动将 URL 和邮箱转为可点击链接。也可以用尖括号显式标记。

📝 示例

https://example.com

<https://example.com>

<user@example.com>

直接粘贴的URL也会自动变成链接

https://example.com

user@example.com

GFM 环境下 URL 会自动转换

两种方式：直接输入 Unicode emoji，或使用 :shortcode: 简码（GitHub 等平台支持）。

📝 示例

直接输入：🎉 🚀 ❤️ ✅

简码形式：
:smile: :heart: :thumbsup:
:rocket: :star: :warning:
:white_check_mark: :x:

直接输入：🎉 🚀 ❤️ ✅

简码渲染：
😄 ❤️ 👍
🚀 ⭐ ⚠️
✅ ❌

Emoji 速查表

点击分类筛选，点击编号可复制。完整列表 1800+ 个，这里列出最常用的。

😀:grinning:

😃:smiley:

😄:smile:

😁:grin:

😆:laughing:

😅:sweat_smile:

🤣:rofl:

😂:joy:

🙂:slightly_smiling_face:

😉:wink:

😊:blush:

😇:innocent:

🥰:smiling_face_with_three_hearts:

😍:heart_eyes:

😘:kissing_heart:

😜:stuck_out_tongue_winking_eye:

🤔:thinking:

🤗:hugs:

😎:sunglasses:

🤩:star_struck:

😏:smirk:

😢:cry:

😭:sob:

😱:scream:

😡:rage:

🥺:pleading_face:

😴:sleeping:

🤮:vomiting_face:

🤡:clown_face:

💀:skull:

👍:thumbsup:

👎:thumbsdown:

👏:clap:

🙌:raised_hands:

🤝:handshake:

✌️:v:

🤞:crossed_fingers:

👌:ok_hand:

👋:wave:

💪:muscle:

🙏:pray:

☝️:point_up:

👆:point_up_2:

👇:point_down:

👈:point_left:

👉:point_right:

✊:fist:

✋:raised_hand:

👶:baby:

👦:boy:

👧:girl:

👨:man:

👩:woman:

👴:older_man:

👵:older_woman:

👮:cop:

👷:construction_worker:

💂:guardsman:

🕵️:detective:

👻:ghost:

👽:alien:

🤖:robot:

🐶:dog:

🐱:cat:

🐭:mouse:

🐰:rabbit:

🦊:fox_face:

🐻:bear:

🐼:panda_face:

🐸:frog:

🐟:fish:

🐬:dolphin:

🦋:butterfly:

🌸:cherry_blossom:

🌹:rose:

🌻:sunflower:

🌲:evergreen_tree:

🌈:rainbow:

☀️:sunny:

🌙:crescent_moon:

⭐:star:

🔥:fire:

💧:droplet:

❄️:snowflake:

🍎:apple:

🍊:tangerine:

🍋:lemon:

🍉:watermelon:

🍇:grapes:

🍓:strawberry:

🍕:pizza:

🍔:hamburger:

🍟:fries:

🍰:cake:

☕:coffee:

🍺:beer:

🍷:wine_glass:

🧁:cupcake:

⚽:soccer:

🏀:basketball:

🎮:video_game:

🎯:dart:

🎲:game_die:

🏆:trophy:

🥇:1st_place_medal:

🎪:circus_tent:

🎬:clapper:

🎵:musical_note:

🎉:tada:

🎊:confetti_ball:

🚗:car:

🚕:taxi:

🚀:rocket:

✈️:airplane:

🚢:ship:

🏠:house:

🏢:office:

🏥:hospital:

🏫:school:

⛰️:mountain:

🌍:earth_africa:

🗺️:world_map:

💻:computer:

📱:iphone:

⌨️:keyboard:

🖥️:desktop_computer:

💡:bulb:

📷:camera:

🔑:key:

🔒:lock:

📝:memo:

📚:books:

📦:package:

📮:postbox:

🔧:wrench:

🔨:hammer:

⚙️:gear:

🎁:gift:

❤️:heart:

💔:broken_heart:

💯:100:

✅:white_check_mark:

❌:x:

⭕:o:

❗:exclamation:

❓:question:

⚠️:warning:

🚫:no_entry_sign:

♻️:recycle:

🔴:red_circle:

🟢:green_circle:

🔵:blue_circle:

⬆️:arrow_up:

⬇️:arrow_down:

➡️:arrow_right:

⬅️:arrow_left:

ℹ️:information_source:

🔗:link:

🏳️:white_flag:

🏴:black_flag:

🚩:triangular_flag_on_post:

🇨🇳:cn:

🇺🇸:us:

🇯🇵:jp:

🇬🇧:gb:

🇰🇷:kr:

🇫🇷:fr:

🇩🇪:de:

已复制!

双等号 == 包裹文本创建高亮效果。

📝 示例

这是 ==非常重要== 的内容。

==高亮标记== 可以突出关键信息。

这是非常重要的内容。

高亮标记可以突出关键信息。

⚠️ 兼容性

高亮语法在 Typora、Obsidian 等编辑器中支持，GitHub 标准不支持。可用 HTML <mark> 标签替代。

部分解析器支持 ^上标^ 和 ~下标~，通用方案是使用 HTML 标签。

📝 示例

扩展语法：X^2^ 和 H~2~O

HTML 方式（通用）：
X<sup>2</sup> 和 H<sub>2</sub>O

扩展语法：X² 和 H₂O

HTML 方式（通用）：
X² 和 H₂O

术语后换行，以 : 加空格开头写定义。（PHP Markdown Extra 扩展）

📝 示例

Markdown
: 一种轻量级标记语言

HTML
: 超文本标记语言
: 网页的基础结构语言

Markdown: 一种轻量级标记语言
HTML: 超文本标记语言; 网页的基础结构语言

⚠️ 兼容性

定义列表不是标准 Markdown 语法，GitHub 不支持。Typora、Pandoc、PHP Markdown Extra 支持。

定义缩写后，正文中出现的缩写词会自动带有悬停提示。

📝 示例

*[HTML]: HyperText Markup Language
*[CSS]: Cascading Style Sheets

HTML 和 CSS 是网页开发的基础。

HTML 和 CSS 是网页开发的基础。

鼠标悬停在缩写上可以看到全称 ↑

⚠️ 兼容性

缩写是 PHP Markdown Extra 扩展，GitHub 不支持。

HTML 注释语法在 Markdown 中同样有效，内容不会被渲染显示。

📝 示例

可见的文本

<!-- 这是注释，不会显示 -->

<!--
  多行注释
  也是可以的
-->

还有一种写法：
[//]: # (这也是注释)

可见的文本

（注释部分不会显示任何内容）

[//]: # 是纯 Markdown 的注释写法，兼容性更好。

\转义字符

反斜杠 \ 可以转义 Markdown 的特殊字符，让它们按原样显示。

📝 示例

\*不是斜体\*
\# 不是标题
\[不是链接\](url)

可转义字符：
\\ \` \* \_ \{ \} \[ \] \( \) \# \+ \- \. \! \|

*不是斜体*

# 不是标题

[不是链接](url)

可转义字符：
\ ` * _ { } [ ] ( ) # + - . ! |

大多数渲染器允许直接嵌入 HTML 标签，弥补 Markdown 语法的不足。

📝 示例

<div align="center">
  <h3>居中标题</h3>
</div>

<details>
  <summary>点击展开</summary>
  隐藏的内容
</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd>

X<sup>2</sup> H<sub>2</sub>O

<mark>高亮文本</mark>

居中标题

点击展开

隐藏的内容

Ctrl + C

X² H₂O

高亮文本

用 $ 包裹行内公式，$$ 包裹块级公式（LaTeX 语法）。GitHub、Typora、Obsidian 均支持。

📝 示例

行内公式：$E = mc^2$

块级公式：

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

$$
f(x) = \frac{1}{\sqrt{2\pi}\sigma}
  e^{-\frac{(x-\mu)^2}{2\sigma^2}}
$$

行内公式：E = mc²

∑_i=1ⁿ x_i = x₁ + x₂ + ⋯ + x_n

f(x) = (1 / √2πσ) · e^{−(x−μ)²/2σ²}

实际渲染需要 KaTeX 或 MathJax 支持

💡 常用 LaTeX 符号

\frac{a}{b} 分数 · \sqrt{x} 根号 · \sum 求和 · \int 积分 · \alpha \beta \gamma 希腊字母 · \leq \geq \neq 比较符号

在文档中插入 [TOC] 可自动根据标题生成目录。不同平台语法略有不同。

📝 示例

[TOC]

# 第一章
## 1.1 简介
## 1.2 安装
# 第二章
## 2.1 基础
## 2.2 进阶

---
其他平台写法：
[[toc]]          (VuePress)
{:toc}           (Jekyll)
      (一些插件)

⚠️ 兼容性

GitHub 不支持 [TOC]，需手动编写目录或使用第三方工具生成。Typora、GitBook 原生支持。

标题会自动生成 ID 锚点，可以用链接语法跳转到页内某个位置。

📝 示例

## 我的标题

跳转到 [我的标题](#我的标题)

---
GitHub 的 ID 生成规则：
- 转为小写
- 空格变 -
- 去除特殊字符
- 中文保留

## Hello World
→ 锚点为 #hello-world

## 安装指南
→ 锚点为 #安装指南

点击我的标题可跳转到对应标题位置。

生成规则示例：

标题	锚点 ID
`## Hello World`	`#hello-world`
`## 安装指南`	`#安装指南`
`## C++ 入门`	`#c-入门`

GitHub 支持的 Alerts 语法，在引用块中使用 [!TYPE] 创建不同类型的提示框。

📝 示例

> [!NOTE]
> 这是一条备注信息。

> [!TIP]
> 这是一条实用提示。

> [!IMPORTANT]
> 这是重要信息。

> [!WARNING]
> 这是警告信息。

> [!CAUTION]
> 这是危险警告。

📝 Note
这是一条备注信息。

💡 Tip
这是一条实用提示。

❗ Important
这是重要信息。

⚠️ Warning
这是警告信息。

🔴 Caution
这是危险警告。

💡 适用场景

GitHub 的 README、Issues、Discussions、PR 描述中都可以使用。非常适合开源项目文档。

在代码块中使用 mermaid 语言标识，可以用文字描述生成流程图、时序图等。GitHub 原生支持。

📝 流程图

```mermaid
graph TD
    A[开始] --> B{条件判断}
    B -->|是| C[执行操作]
    B -->|否| D[跳过]
    C --> E[结束]
    D --> E
```

开始

↓

条件判断?

是 → 执行操作否 → 跳过

↓

结束

📝 时序图 & 饼图

```mermaid
sequenceDiagram
    客户端->>服务器: 请求数据
    服务器-->>客户端: 返回响应
```

```mermaid
pie title 使用场景
    "技术文档" : 40
    "博客写作" : 25
    "笔记记录" : 20
    "AI交互" : 15
```

Mermaid 支持的图表类型：

flowchart — 流程图
sequenceDiagram — 时序图
classDiagram — 类图
stateDiagram — 状态图
gantt — 甘特图
pie — 饼图
gitgraph — Git 分支图

使用 :::（三个冒号）创建自定义容器块，常见于 VuePress、VitePress、MkDocs 等文档框架。基于 markdown-it-container 插件。

📝 提示容器

::: tip 小贴士
这里是提示内容。
:::

::: warning 注意
这里是警告内容。
:::

::: danger 危险
这里是危险警告。
:::

::: details 点击查看详情
这里是可折叠的隐藏内容。
支持 **Markdown** 格式。
:::

::: info
不写标题则使用默认标题。
:::

💡 小贴士

这里是提示内容。

⚠️ 注意

这里是警告内容。

🔴 危险

这里是危险警告。

点击查看详情

这里是可折叠的隐藏内容。
支持 Markdown 格式。

💡 适用平台

VuePress、VitePress、MkDocs Material（使用 !!! 语法）、Docusaurus（使用 ::: 语法）。不同框架关键词略有差异。

Tabs 语法允许将内容组织为可切换的标签页，基于 markdown-it-container + markdown-it-tabs 插件。不同框架语法有差异。

VuePress / VitePress 语法

📝 code-tabs 示例

:::: tabs

@tab JavaScript
```js
console.log("Hello");
```

@tab Python
```python
print("Hello")
```

@tab Go
```go
fmt.Println("Hello")
```

::::

JavaScript Python Go

console.log("Hello");

MkDocs Material 语法

📝 MkDocs 风格

=== "npm"

    ```bash
    npm install package-name
    ```

=== "yarn"

    ```bash
    yarn add package-name
    ```

=== "pnpm"

    ```bash
    pnpm add package-name
    ```

npm yarn pnpm

npm install package-name

Docusaurus 语法

📝 Docusaurus 风格

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="js" label="JavaScript">

  ```js
  console.log("Hello");
  ```

  </TabItem>
  <TabItem value="py" label="Python">

  ```python
  print("Hello")
  ```

  </TabItem>
</Tabs>

Docusaurus 使用 JSX 组件语法（MDX），需要导入 Tabs 组件。

JavaScript Python

console.log("Hello");

⚠️ 兼容性

Tabs 不是标准 Markdown 语法，需要特定框架或插件支持。各框架写法不同：

框架	语法关键词	插件
VuePress 2	`:::: tabs` + `@tab`	vuepress-plugin-md-enhance
VitePress	同上或自定义	markdown-it-tabs
MkDocs Material	`=== "Tab"`	内置 tabbed 扩展
Docusaurus	`<Tabs>` JSX	MDX 内置
Discourse 论坛	`[tabs]` 或 `::: tabs`	markdown-it-container

在线练习场

左侧输入 Markdown 语法，右侧实时渲染。边学边练效果最好！

✏️ 编辑区

👁️ 预览区

速查表

所有 Markdown 语法一览，建议收藏本页随时查阅。

文本格式

`粗体`	粗体
`斜体`	斜体
`*粗斜体*`	*粗斜体*
`~~删除线~~`	~~删除线~~
`==高亮==`	高亮
`行内代码`	`行内代码`

标题

`# H1`	一级标题
`## H2`	二级标题
`### H3`	三级标题
`#### H4`	四级标题
`##### H5`	五级标题
`###### H6`	六级标题

链接 & 图片

`[文字](url)`	链接
`![alt](url)`	图片
`<url>`	自动链接
`[^1]`	脚注引用
`[跳转](#id)`	锚点跳转

列表

`- 项目`	无序列表
`1. 项目`	有序列表
`- [ ] 待办`	任务列表
`- [x] 完成`	已完成项

块级元素

`> 引用`	引用块
`---`	分割线
`\| 表格 \|`	表格
```lang	代码块
`[TOC]`	目录

高级

$公式$	行内数学
`$$公式$$`	块级数学
`:emoji:`	Emoji
`> [!NOTE]`	提示框
```mermaid	图表
`<!-- -->`	注释
`::: tip`	容器指令
`:::: tabs`	标签页

AI Skill 模板指南

Skill（技能文件）是用 Markdown 编写的 AI 指令模板，用来定义 AI 助手的行为、能力和工作流程。
掌握 Markdown 语法后，你就可以编写自己的 Skill 文件了。

📄

文件格式

通常是 SKILL.md 或 .md 文件，纯 Markdown 语法编写。

🎯

核心目的

告诉 AI「你是谁、能做什么、怎么做」，让 AI 按照预设的规则工作。

🧩

适用平台

Cursor、GitHub Copilot、ChatGPT GPTs、Dify、Coze 等 AI 工具。

初级初级 Skill 模板

最基础的 Skill 结构，适合简单任务。包含角色定义、基本指令和输出格式三个核心部分。

📝 翻译助手 Skill

# 翻译助手

## 角色
你是一个专业的中英文翻译助手。

## 指令
- 当用户输入中文时，翻译成英文
- 当用户输入英文时，翻译成中文
- 保持原文的语气和风格
- 专有名词保留原文，括号内附上翻译

## 输出格式
**翻译结果：**

（翻译内容）

> 📝 *补充说明*：（如有需要解释的词汇或文化差异，在此说明）

✅ 初级模板要点

结构清晰 — 角色 + 指令 + 输出格式，三段式最基本
指令具体 — 用列表列出明确的规则，避免模糊表述
格式统一 — 定义好输出的格式模板，AI 会遵循

中级模板增加了上下文约束、示例（Few-shot）、边界处理和工作流程，让 AI 表现更稳定。

📝 代码审查助手 Skill

# 代码审查助手

## 角色定义
你是一位资深的代码审查工程师，擅长发现代码中的潜在问题并给出改进建议。

## 能力范围
- 支持语言：JavaScript、TypeScript、Python、Go、Java
- 审查维度：安全性、性能、可读性、最佳实践、错误处理

## 工作流程
1. **理解代码**：先整体阅读代码，理解其功能和上下文
2. **逐项审查**：按照审查维度逐一检查
3. **分级反馈**：将问题按严重程度分级
4. **给出建议**：每个问题附带具体的修改建议和代码示例

## 输出格式

### 📊 审查摘要
| 维度     | 评分 (1-5) | 说明 |
| -------- | ---------- | ---- |
| 安全性   | ⭐⭐⭐⭐   | ... |
| 性能     | ⭐⭐⭐     | ... |
| 可读性   | ⭐⭐⭐⭐⭐ | ... |

### 🔴 严重问题
（需要立即修复的安全漏洞或 Bug）

### 🟡 改进建议
（性能优化、最佳实践等）

### 🟢 亮点
（写得好的地方，给予肯定）

## 示例

**用户输入：**
```javascript
app.get('/user', (req, res) => {
  const id = req.query.id;
  const result = db.query(`SELECT * FROM users WHERE id = ${id}`);
  res.json(result);
});
```

**审查输出：**

### 🔴 严重问题
**SQL 注入漏洞** — 直接拼接用户输入到 SQL 语句中。

```javascript
// ❌ 危险写法
const result = db.query(`SELECT * FROM users WHERE id = ${id}`);

// ✅ 安全写法 — 使用参数化查询
const result = db.query('SELECT * FROM users WHERE id = ?', [id]);
```

## 约束
- 不要重写整个代码，只针对问题给出最小改动
- 如果代码没有问题，也要给出正面反馈
- 保持专业但友好的语气

✅ 中级模板要点

Few-shot 示例 — 给 AI 一个输入→输出的完整示例，让它模仿
工作流程 — 定义步骤顺序，AI 会按流程执行
分级输出 — 用表格和分级标记组织结果，结构化更强
边界约束 — 告诉 AI「什么不要做」和「什么情况下怎么做」

高级模板适合复杂场景，包含多阶段工作流、条件分支、工具调用、错误恢复和质量校验等完整体系。

📝 全栈项目脚手架 Skill

# 全栈项目脚手架生成器

## 元信息
- **版本**：v2.1.0
- **作者**：DevTeam
- **适用平台**：Cursor Agent / GitHub Copilot Workspace
- **最后更新**：2026-03

## 角色定义

你是一位全栈架构师 + 高级开发工程师。你的任务是根据用户的需求描述，
生成一个**完整、可运行**的项目脚手架，包括目录结构、核心代码、
配置文件和部署方案。

## 前置条件检查

在开始之前，你**必须**向用户确认以下信息（如果用户没有提供）：

| 信息项   | 必填 | 默认值         | 示例              |
| -------- | ---- | -------------- | ----------------- |
| 项目名称 | ✅   | -              | my-awesome-app    |
| 项目类型 | ✅   | -              | Web App / API / CLI |
| 技术栈   | ❌   | 自动推荐       | React + Node.js   |
| 部署方式 | ❌   | Cloudflare     | Vercel / Docker   |
| 数据库   | ❌   | SQLite         | PostgreSQL / MongoDB |

## 工作流程

```
用户输入需求
    │
    ▼
[阶段 1] 需求分析 ──→ 输出：需求确认清单
    │
    ▼
[阶段 2] 架构设计 ──→ 输出：技术方案 + 目录结构
    │
    ▼
[阶段 3] 代码生成 ──→ 输出：核心文件代码
    │
    ▼
[阶段 4] 配置完善 ──→ 输出：配置文件 + 环境变量
    │
    ▼
[阶段 5] 质量校验 ──→ 自检清单
    │
    ▼
交付用户
```

### 阶段 1：需求分析
- 解析用户描述，提取功能需求
- 如果需求模糊，列出 **最多 3 个** 澄清问题
- 输出一个确认清单，等用户确认后再继续

### 阶段 2：架构设计
根据需求推荐技术栈，输出格式：

> **推荐方案：**
> - 前端：React 18 + TypeScript + Tailwind CSS
> - 后端：Hono + Cloudflare Workers
> - 数据库：D1 (SQLite)
> - 理由：（简述为什么选择这个方案）

然后生成目录结构树：
```
project-name/
├── src/
│   ├── client/      # 前端代码
│   ├── server/      # 后端代码
│   └── shared/      # 共享类型和工具
├── public/
├── tests/
├── package.json
├── tsconfig.json
├── wrangler.toml
└── README.md
```

### 阶段 3：代码生成

> [!IMPORTANT]
> 每个文件必须是**完整可运行**的代码，不允许用注释占位。

按以下优先级生成文件：
1. 入口文件（index.ts / main.ts）
2. 路由/页面文件
3. 数据模型
4. 工具函数
5. 样式文件

### 阶段 4：配置完善
- `package.json`（含准确的依赖版本号）
- 环境变量模板 `.env.example`
- 部署配置文件
- `README.md`（含启动步骤）

### 阶段 5：质量自检

生成完毕后，执行自检清单：

- [ ] 所有 import 路径正确
- [ ] 没有遗漏的依赖
- [ ] TypeScript 类型完整
- [ ] 环境变量已在 .env.example 中列出
- [ ] README 包含完整启动步骤
- [ ] 代码可以直接 `npm install && npm run dev` 运行

## 条件分支

```
IF 用户要求「仅前端」:
  → 跳过后端和数据库阶段
  → 推荐 Vite + 静态部署

IF 用户要求「仅 API」:
  → 跳过前端阶段
  → 关注 API 文档和测试

IF 用户没有指定技术栈:
  → 根据项目类型自动推荐（见推荐矩阵）
```

## 推荐矩阵

| 项目类型     | 前端            | 后端            | 数据库       | 部署         |
| ------------ | --------------- | --------------- | ------------ | ------------ |
| 展示型网站   | Astro           | -               | -            | CF Pages     |
| Web 应用     | React + Vite    | Hono            | D1/Postgres  | CF Workers   |
| API 服务     | -               | Hono / Express  | Postgres     | Docker       |
| CLI 工具     | -               | Node.js         | SQLite       | npm publish  |
| 移动端 H5    | Vue 3 + Vant    | Hono            | D1           | CF Workers   |

## 错误处理
- 如果生成过程中发现需求冲突，**立即暂停**并告知用户
- 如果某个依赖版本不确定，标注 ``
- 如果超出能力范围，诚实说明并推荐替代方案

## 输出约束
- 所有代码使用 **UTF-8** 编码
- 代码风格遵循各语言社区主流规范
- 单个文件不超过 **300 行**，超出则拆分
- 注释语言跟随用户输入语言（中/英）
- **不要** 生成无意义的占位代码或 Lorem ipsum

✅ 高级模板要点

元信息 — 版本、作者、适用平台，方便维护和协作
前置条件 — 用表格列出必要信息，缺失时主动询问
多阶段工作流 — 用流程图/步骤分解复杂任务，每阶段有明确输出
条件分支 — 处理不同场景的逻辑分支，让 Skill 更灵活
质量自检 — 用任务列表做自我检查，提高输出质量
错误恢复 — 定义异常情况的处理策略
推荐矩阵 — 用表格给出决策参考，减少 AI 的随机性

一些让你的 Skill 文件更有效的实用技巧。

用标题建立层次

用 # ## ### 建立清晰的文档结构，AI 会据此理解各部分的重要性和层级关系。

列表代替长段落

指令用列表（- 或 1.）写，比大段文字更容易被 AI 准确理解和遵循。

给出具体示例

一个好的示例（Few-shot）胜过十句描述。用代码块给出「输入→输出」的完整示例。

用表格做结构化约束

参数表、对比矩阵、评分标准等用表格表示，比文字描述更精确，AI 遵循度更高。

定义「不要做什么」

除了告诉 AI 要做什么，还要明确它不应该做什么。用 > [!WARNING] 或加粗强调。

版本化管理

给 Skill 加上版本号和更新日期。迭代优化时对比历史版本，持续改进 AI 表现。

💡 Markdown 语法在 Skill 中的妙用

Markdown 语法	在 Skill 中的作用
`# 标题`	划分模块、建立层次结构
`- 列表`	列举规则、步骤和约束
`粗体`	强调关键词和必须遵守的规则
```代码块```	给出输入输出示例、模板格式
`\| 表格 \|`	参数定义、决策矩阵、评分标准
`> 引用`	特别提醒、注意事项
`- [ ] 任务`	质量自检清单
`---`	分隔不同阶段或模块

不同 AI 平台的 Skill/Prompt 配置文件格式有所不同，但核心都是 Markdown。

平台	文件名	格式	特点
Cursor	`SKILL.md` `.cursor/rules/*.md`	纯 Markdown	支持 Agent Skill、Rule 规则，可绑定文件类型
GitHub Copilot	`.github/copilot-instructions.md`	纯 Markdown	项目级自定义指令，团队共享
ChatGPT GPTs	在线配置面板	纯文本 (Markdown 可用)	Instructions 字段支持 Markdown 排版
Claude Projects	Project Instructions	纯文本 (Markdown 可用)	Custom Instructions 支持 Markdown
Dify	应用编排界面	Markdown + YAML	可视化编排 + Prompt 模板变量
Coze	Bot 配置面板	Markdown	人设与回复逻辑、支持插件调用
Windsurf	`.windsurfrules`	纯 Markdown	项目规则文件

✅ 通用建议

不管哪个平台，Markdown 都是 Skill 编写的基础语言。掌握了前面教程中的标题、列表、表格、代码块、引用等语法，你就能在任何平台上编写高质量的 AI Skill。