通用模板基础 - 所有层级共用¶

模板类型: 通用基础 适用范围: L1-L7 所有层级版本: 1.0 创建日期: 2026-01-13

📋 模板说明¶

本文档提供**所有L1-L7层级文档共用的基础模板结构**，确保整个知识库文档风格一致。

适用场景¶

✅ 层级综述文档
✅ 技术对比分析文档
✅ 概念解释文档
✅ 通用指导文档

📄 标准文档模板¶

---
title: "[文档标题]"
layer: "L1/L2/L3/L4/L5/L6/L7"
tech_route: "Superconducting/TrappedIon/NeutralAtom/Photonic/通用/混合"
version: "1.0"
date: "YYYY-MM-DD"
author: "[作者名称或团队]"
tags: ["标签1", "标签2", "标签3"]
status: "活跃/草稿/已废弃"
last_updated: "YYYY-MM-DD"
references: ["[ID_Year_Author]", "[ID_Year_Author]"]
related_docs: ["[相对路径/文档1.md]", "[相对路径/文档2.md]"]
---

# [文档标题]

**文档版本**: {{version}}
**创建日期**: {{date}}
**维护者**: {{author}}
**所属层级**: {{layer}}
**状态**: {{status}}

---

## 文档目的

本文档提供[简要描述文档的核心内容和目标]。

**核心内容**：
- [核心内容1]
- [核心内容2]
- [核心内容3]

**目标读者**：
- [读者类型1]
- [读者类型2]

---

## 1. 背景与概述

### 1.1 背景

[描述该文档对应的领域背景]

[相关术语解释（如有）]

### 1.2 核心概念

[定义本文档涉及的核心概念]

**术语定义**:

| 术语 | 英文 | 定义 | 参考链接 |
|------|------|------|----------|
| [术语1] | [English] | [定义] | [链接] |
| [术语2] | [English] | [定义] | [链接] |

---

## 2. 核心内容

### 2.1 [主要章节1]

[描述第一个主要内容]

**关键点**:
- [关键点1]
- [关键点2]
- [关键点3]

**示例**:

```python
# [代码示例]
[可运行的代码片段]

2.2 [主要章节2]¶

[描述第二个主要内容]

技术规格 (如适用):

参数	数值	单位	备注
[参数1]	[值]	[单位]	[说明]
[参数2]	[值]	[单位]	[说明]

可视化 (如适用):

[Mermaid图表代码]

2.3 [主要章节3]¶

[描述第三个主要内容]

优劣势分析:

Strengths (优势)¶

✅ [优势1]
✅ [优势2]

Weaknesses (劣势)¶

❌ [劣势1]
❌ [劣势2]

Opportunities (机会)¶

🎯 [机会1]
🎯 [机会2]

Threats (威胁)¶

⚠️ [威胁1]
⚠️ [威胁2]

3. 实践应用¶

3.1 应用场景1¶

场景描述: [详细描述]

实现步骤:

步骤1: [具体步骤]
步骤2: [具体步骤]
步骤3: [具体步骤]

代码示例:

# [完整代码示例]
def example_function():
    """
    [函数说明]
    """
    # [实现细节]
    pass

输出示例:

[预期的输出结果]

3.2 应用场景2¶

场景描述: [详细描述]

配置参数:

参数名	类型	默认值	说明
[param1]	[type]	[default]	[description]
[param2]	[type]	[default]	[description]

使用示例:

# [使用示例代码]
result = function_name(
    param1=value1,
    param2=value2
)
print(result)

4. 对比分析¶

4.1 方案对比¶

对比维度: [说明对比的标准]

方案	优势	劣势	适用场景
[方案1]	[优势]	[劣势]	[场景]
[方案2]	[优势]	[劣势]	[场景]
[方案3]	[优势]	[劣势]	[场景]

4.2 技术路线对比 (如适用)¶

对比矩阵:

技术路线	[指标1]	[指标2]	[指标3]	综合评分
[路线1]	[值]	[值]	[值]	[评分]
[路线2]	[值]	[值]	[值]	[评分]
[路线3]	[值]	[值]	[值]	[评分]

推荐选择: [基于分析给出建议]

5. 挑战与展望¶

5.1 当前挑战¶

技术挑战: - [挑战1]: [详细描述] - [挑战2]: [详细描述]

工程挑战: - [挑战1]: [详细描述] - [挑战2]: [详细描述]

应对策略:

策略1: [具体措施]
策略2: [具体措施]

5.2 发展趋势¶

短期趋势 (1-2年): - [趋势1] - [趋势2]

中期趋势 (3-5年): - [趋势1] - [趋势2]

长期展望 (5+年): - [展望1] - [展望2]

6. 相关资源¶

6.1 内部文档¶

文档	路径	核心内容
[文档1]	[相对路径]	[简要说明]
[文档2]	[相对路径]	[简要说明]

6.2 外部参考¶

学术论文: - [ID_Year_Author]: [论文标题] - [ID_Year_Author]: [论文标题]

技术文档: - [ID_Year_Organization]: [文档标题] - [ID_Year_Organization]: [文档标题]

在线资源: - [资源名称]: [URL] - [资源名称]: [URL]

7. 快速参考¶

7.1 关键参数速查¶

参数类别	参数名	典型值	备注
[类别1]	[参数]	[值]	[说明]
[类别2]	[参数]	[值]	[说明]

7.2 常见问题¶

Q1: [常见问题1]

A: [详细回答]

Q2: [常见问题2]

A: [详细回答]

8. 版本历史¶

版本	日期	修改内容	作者
1.0	YYYY-MM-DD	初始版本	[作者]
1.1	YYYY-MM-DD	[修改说明]	[作者]

附录¶

A. 数学公式 (如适用)¶

公式1: [公式名称]

[LaTeX数学公式]

说明: [公式的物理意义和适用条件]

B. 术语表 (如适用)¶

术语	英文	定义	参见
[术语]	[English]	[定义]	[章节]

C. 代码库链接¶

主仓库: [GitHub/其他平台链接]
示例代码: [链接]
文档站点: [链接]

[文档结束]

如有任何问题或建议，请联系维护团队: {{author}}

---

## 🎨 模板使用指南

### 1. Frontmatter 填写规范

**必填字段**:
```yaml
---
title: "文档标题"           # 必填，简洁明确
layer: "L2"                # 必填，L1-L7之一
version: "1.0"             # 必填，遵循语义化版本
date: "2026-01-13"         # 必填，YYYY-MM-DD格式
author: "作者/团队"         # 必填
---

推荐字段:

---
tech_route: "Superconducting"  # 硬件层文档推荐
tags: ["标签1", "标签2"]       # 便于搜索和分类
status: "活跃"                 # 文档状态
last_updated: "2026-01-13"     # 最后更新日期
references: ["[RV_2023_Author]"]  # 参考文献列表
related_docs: ["../L2/xxx.md"]    # 相关文档链接
---

2. 章节结构规范¶

标准章节层级:

# H1: 文档标题 (仅用于文档开头)
## H2: 主要章节
### H3: 子章节
#### H4: 细节说明
##### H5: 极少使用，避免过深层级

章节命名规范: - 使用清晰的动词或名词短语 - 避免使用过于笼统的标题（如"内容"、"说明"） - 保持章节编号一致性

3. 表格规范¶

标准表格格式:

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |

表格要求: - 必须包含表头行 - 列数统一对齐 - 数字列右对齐，文本列左对齐 - 添加必要的单位列

4. 代码块规范¶

Python代码块:

# 添加文件说明
"""[文件/函数用途说明]"""

# 导入标准库
import numpy as np

# 导入量子库
from qiskit import QuantumCircuit

# 函数定义
def function_name(param1, param2):
    """
    [函数说明]

    Args:
        param1 (type): [参数说明]
        param2 (type): [参数说明]

    Returns:
        type: [返回值说明]
    """
    # 实现代码
    pass

要求: - 指定语言类型 (python/cpp/java等) - 添加清晰的注释 - 函数包含docstring - 关键步骤添加行内注释

5. 数学公式规范¶

行内公式: 使用 $...$

根据哈密顿量 $H = \sum_{i} h_i \sigma_i$，我们可以...

独立公式: 使用 $$...$$ 或 ```latex

$$
R_z(\theta) = e^{-i\theta\sigma_z/2} =
\begin{bmatrix}
e^{-i\theta/2} & 0 \\
0 & e^{i\theta/2}
\end{bmatrix}
$$

公式编号 (可选):

$$
i\hbar\frac{\partial}{\partial t}|\psi\rangle = H|\psi\rangle
\tag{1}
$$

✅ 质量检查清单¶

发布新文档前，请确认：

□ Frontmatter 完整填写（至少包含title, layer, version, date, author）
□ 标题层级正确（H1 > H2 > H3）
□ 所有表格有表头
□ 代码块指定了语言类型
□ 数学公式使用LaTeX格式
□ 参考文献使用标准格式 [ID_Year_Author]
□ 术语使用标准词表（见《受控词表》）
□ 添加了适当的章节编号
□ 包含版本历史表
□ 相对链接使用正确的路径

📞 模板支持¶

维护团队: templates@quantum-kb.example.com 问题反馈: https://github.com/quantum-kb/templates/issues 改进建议: template-suggestions@quantum-kb.example.com

模板版本: 1.0 最后更新: 2026-01-13