整理文档

CLAUDE.md

@@ -25,7 +25,7 @@ output/               # 构建产物（gitignore）
 
 ### 文件命名规范
 - 章节文件: `{序号}-{英文slug}.md`（如 `04-02-acq-codeword.md`）
-- 子章节用二级编号: `{章}-{节}-{slug}.md`（如 `05-03-exct-wavetable.md`）
+- 子章节用二级编号: `{章}-{节}-{slug}.md`（如 `05-03-exc-wavetable.md`）
 - 图片文件: 语义化命名（如 `readout_ro.png`），统一放在 `assets/`
 
 ### 标题层级
@@ -70,19 +70,21 @@ python doc_builder/build.py
 | §1 | `chapters/01-changelog.md` | 修订记录 |
 | §2 | `chapters/02-preface.md` | 前言（目的、范围、术语等） |
 | §3 | `chapters/03-overview.md` | 编程控制模型概述 |
-| §4 | `chapters/04-acq-model.md` | ACQ 通道编程模型（数据路径） |
+| §4 | `chapters/04-00-acq-model.md` | ACQ 通道编程模型（数据路径） |
 | §4.1 | `chapters/04-01-acq-downconversion.md` | 下变频电路配置 |
 | §4.2 | `chapters/04-02-acq-codeword.md` | ACQ 码字功能定义 |
 | §4.3 | `chapters/04-03-acq-registers.md` | ACQ 寄存器功能定义 |
 | §4.4 | `chapters/04-04-acq-matched-filter.md` | 匹配滤波器 |
 | §4.5 | `chapters/04-05-acq-data-processing.md` | 采集数据处理 |
-| §5 | `chapters/05-exct-model.md` | EXCT-Pump 编程模型（数据路径） |
+| §4.6 | `chapters/04-06-acq-pipeline-demo.md` | ACQ 全流程控制示例 |
-| §5.1 | `chapters/05-01-exct-codeword.md` | EXCT 码字功能定义 |
+| §5 | `chapters/05-00-exc-model.md` | EXC-Pump 编程模型（数据路径） |
-| §5.2 | `chapters/05-02-exct-registers.md` | 寄存器功能定义 |
+| §5.1 | `chapters/05-01-exc-codeword.md` | EXC 码字功能定义 |
-| §5.3 | `chapters/05-03-exct-wavetable.md` | 波形索引表定义 |
+| §5.2 | `chapters/05-02-exc-registers.md` | 寄存器功能定义 |
-| §5.4 | `chapters/05-04-exct-waveform-store.md` | 波形仓库定义 |
+| §5.3 | `chapters/05-03-exc-wavetable.md` | 波形索引表定义 |
-| §5.5 | `chapters/05-05-exct-upconversion.md` | EXCT 上变频电路配置 |
+| §5.4 | `chapters/05-04-exc-waveform-store.md` | 波形仓库定义 |
+| §5.5 | `chapters/05-05-exc-upconversion.md` | EXC 上变频电路配置 |
 | §5.6 | `chapters/05-06-pump-config.md` | Pump 模拟电路配置 |
+| §5.7 | `chapters/05-07-exc-pipeline-demo.md` | EXC-Pump 全流程控制示例 |
 
 ## 编辑工作流
 

chapters/01-changelog.md

@@ -4,3 +4,4 @@
 |:-|:-|:-|:-|:-|
 |v0.1|2025/10/27|统一格式|初始版本|郭成|
 |v0.2|2025/10/31|评审意见|内容补充|郭成|
+|v0.3|2026/07/27|用户反馈|内容梳理|郭成|

chapters/02-preface.md

@@ -2,18 +2,18 @@
 
 ## 2.1. 目的与范围
 
-本文档的目的是介绍读出芯片激励产生和采集处理相关控制，
+本文档的目的是介绍读出子系统激励产生和采集处理相关控制，
 该文档适用于ez-Q 2.5 FPGA/ASIC平台读出子系统编程。
 本文档作为开放文档供大家阅读。
 
 ## 2.2. 阅读对象
 
-本文档的预期读者是所有使用本芯片的用户以及对该芯片工作原理感兴趣的读者。
+本文档的预期读者是驱动开发工程师、使用本系统的终端用户以及对该芯片工作原理感兴趣的读者。
 
 ## 2.3. 文档概述
 
 本文档首先介绍了测控系统总体的编程对象和规范，
-针对读出ACQ/EXCT/Pump三种类型通道对应的ACQ/EXCT-Pump编程模型进行了详细介绍。
+针对读出ACQ/EXC/Pump三种类型通道对应的ACQ/EXC-Pump编程模型进行了详细介绍。
 
 ## 2.4. 引用文档
 
@@ -28,4 +28,4 @@
 |名字|全称|解释|
 |:-|:-|:-|
 |ACQ|Acquisition|读出回波采集处理通道|
-|EXCT|Excitation|读出激励生成发送通道|
+|EXC|Excitation|读出激励生成发送通道|

chapters/03-overview.md

@@ -3,9 +3,9 @@
 ## 3.1. 测控系统编程概述
 
 超导量子计算机利用微波信号来驱动量子比特和读出量子比特状态，量子比特不同类型的操作依赖不同类型的信号来控制。
-ez-Q 2.5测控系统包含5种物理通道，对应5类硬件接口，分别是ACQ、EXCT、Pump、XYZ/Reset和ZCP通道；
+ez-Q 2.5测控系统包含5种物理通道，对应5类硬件接口，分别是ACQ、EXC、Pump、XYZ/Reset和ZCP通道；
-系统具有7种控制信号，对应7种编程对象，分别是EXCT、ACQ、Pump、XY、Reset、Z和ZCP信号；
+系统具有7种控制信号，对应7种编程对象，分别是EXC、ACQ、Pump、XY、Reset、Z和ZCP信号；
-系统具有4种控制模型，对应4种编程类型，分别是ACQ、EXCT-Pump、XY/Reset和Z/ZCP模型，分类关系如下表所示。
+系统具有4种控制模型，对应4种编程类型，分别是ACQ、EXC-Pump、XY/Reset和Z/ZCP模型，分类关系如下表所示。
 
 |5种物理通道|7种控制对象|4种控制模型|
 |:-:|:-:|:-:|
@@ -14,7 +14,7 @@ ez-Q 2.5测控系统包含5种物理通道，对应5类硬件接口，分别是A
 |^|Z信号|Z/ZCP控制模型|
 |ZCP通道|ZCP信号|Z/ZCP控制模型|
 |ACQ通道|ACQ(RO)信号|ACQ控制模型|
-|EXCT通道|EXCT(RI)信号|EXCT-Pump控制模型|
+|EXC通道|EXC(RI)信号|EXC-Pump控制模型|
 |Pump通道|Pump信号|^|
 
 - 测控系统中的每种控制模型实现的功能都是通过以下四类数据进行定义，
@@ -26,14 +26,13 @@ ez-Q 2.5测控系统包含5种物理通道，对应5类硬件接口，分别是A
 - 测控系统的寄存器、配置数据和模拟电路配置返回数据统一采用**大端字节序**。
 
 通道寄存器配置数据支持微控制器实时修改，从而让通道的输入/输出控制具备动态控制能力。
-ACQ和EXCT-Pump通道配置寄存器定义参考[读出子系统IDS表.xls](TODO)的`DAQ_REG`和`AWG_REG`页。
+ACQ和EXC-Pump通道配置寄存器定义参考[读出子系统IDS表.xls](TODO)的`DAQ_REG`和`AWG_REG`页。
-ACQ的配置数据定义参考
 
 本文档通过对不同编程模型下码字指令、通道寄存器配置数据、通道SRAM配置数据和通道模拟电路配置进行介绍，
 旨在让用户掌握对读出激励信号的产生和采集信号处理的编程方法。
 其中码字指令通过MCU来产生，MCU的编程关键参数如下：
 
-* ACQ通道和EXCT-Pump通道使用**相同MCU**；
+* ACQ通道和EXC-Pump通道使用**相同MCU**；
 * MCU分别使用**16 KB**的ITCM和DTCM；
 * FPGA平台MCU主时钟频率为**250 MHz**，
 * ASIC平台MCU主钟频率暂定**750 MHz**；
@@ -67,7 +66,7 @@ ez-Q 2.5 ASIC平台读出子系统由读出基带板、读出混频板和读出
 
 本文所述的三类编程通道具体定义如下：
 * ACQ 编程通道定义从混频板`rf_in`输入端口到基带板卡内部DAQ模块；
-* EXCT 编程通道定义为从基带板内部AWG模块混频板到`rf_out`接口；
+* EXC 编程通道定义为从基带板内部AWG模块混频板到`rf_out`接口；
 * Pump 编程通道定义为从基带板卡内部AWG模块到泵浦板`pump_out`接口；
 
 ASIC和FPGA平台具有以下区别：

chapters/05-00-exc-model.md

@@ -1,4 +1,4 @@
-# 5. 处理器EXCT-Pump编程模型
+# 5. 处理器EXC-Pump编程模型
 
 EXC-Pump通道的编程包括：
 MCU的指令、MCU的数据、控制寄存器、波形索性表、波形仓库和模拟电路配置6类数据。

chapters/05-02-exc-registers.md

@@ -1,6 +1,6 @@
 ## 5.2. 寄存器功能定义
 
-EXCT-Pump通道的全部寄存器可以被SPI和MCU同时访问，
+EXC-Pump通道的全部寄存器可以被SPI和MCU同时访问，
 用户可以根据需要决定使用SPI还是MCU来控制寄存器的值。
 
 |名字|功能描述|

chapters/05-04-exc-waveform-store.md

@@ -5,5 +5,5 @@
 * 每个采样点为16比特的二进制补码数据；
 * 波形仓库的容量为128 KB，在FPGA平台和ASIC平台下最大分别支持16 us和10 us波形输出。
 
-对于EXCT输出频率$F_{out}$（例如6.7 GHz），在本振为$F_{LO}$(例如5.5GHz)本振频率下，
+对于EXC输出频率$F_{out}$（例如6.7 GHz），在本振为$F_{LO}$(例如5.5GHz)本振频率下，
 则存储区描绘的基带波形频率$F_{s}$为1.2 GHz ，$F_s = F_{out} - F_{LO}$。

chapters/05-05-exc-upconversion.md

@@ -1,4 +1,4 @@
-## 5.5. EXCT上变频电路配置
+## 5.5. EXC上变频电路配置
 
 来自读出基带板输出端口的中频信号需要经过混频板上变频电路处理后才能够被发送到量子芯片。
 前端上变频电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。

doc_builder/__init__.py

@@ -0,0 +1 @@
+# doc_builder — Docs as Code 构建工具包

doc_builder/build.py

@@ -284,6 +284,242 @@ def render_custom_codeblocks_md(text, renderers):
     return "".join(out_lines)
 
 
+# ---------- MPE 表格合并（^ / < / > 语法 → 展平为标准 Markdown） ----------
+# ^ : 与上方单元格合并（rowspan）
+# < : 与左侧单元格合并（colspan，本单元格被吸收）
+# > : 与右侧单元格合并（colspan，右侧单元格被吸收）
+# 策略：展平时将合并标记替换为被合并单元格的内容，
+# 再由 postprocess_table_rowspan 检测重复内容生成 rowspan/colspan。
+
+# 表格行: | cell | cell | ... |
+TABLE_ROW_RE = re.compile(r'^\|.+\|$')
+
+
+def preprocess_mpe_tables(text):
+    """
+    将 Markdown Preview Enhanced 风格的单元格合并标记展平为标准 Markdown：
+      ^ → 替换为同列上一行的内容（纵向合并）
+      < → 替换为同行左侧的内容（横向合并）
+      > → 替换为同行右侧的内容（横向合并）
+    展平后交给标准 Markdown 渲染器，再由 postprocess_table_rowspan 恢复合并。
+    """
+    lines = text.split("\n")
+    out = []
+    i = 0
+
+    while i < len(lines):
+        line = lines[i]
+
+        if not (TABLE_ROW_RE.match(line) and i + 1 < len(lines) and _is_separator(lines[i + 1])):
+            out.append(line)
+            i += 1
+            continue
+
+        table_lines = [line]
+        i += 1
+        table_lines.append(lines[i])
+        i += 1
+
+        while i < len(lines) and TABLE_ROW_RE.match(lines[i]):
+            table_lines.append(lines[i])
+            i += 1
+
+        has_merge = any(_has_merge_cell(tl) for tl in table_lines[2:])
+
+        if has_merge:
+            out.extend(_flatten_mpe_table(table_lines))
+        else:
+            out.extend(table_lines)
+
+    return "\n".join(out)
+
+
+def _is_separator(line):
+    """判断是否为表格分隔行: |---|:---|...| 或 MPE 风格 |:-:|"""
+    return bool(re.match(r'^\|[\s:]*-+[\s:]*\|', line))
+
+
+def _has_merge_cell(row_line):
+    """判断表格行是否包含 MPE 合并标记（^, <, >）。"""
+    cells = _split_table_cells(row_line)
+    return any(c.strip() in ("^", "<", ">") for c in cells)
+
+
+def _split_table_cells(row_line):
+    """将 | a | b | c | 拆分为 ['a', 'b', 'c']。"""
+    stripped = row_line.strip()
+    if stripped.startswith("|"):
+        stripped = stripped[1:]
+    if stripped.endswith("|"):
+        stripped = stripped[:-1]
+    return [c.strip() for c in stripped.split("|")]
+
+
+def _flatten_mpe_table(table_lines):
+    """
+    将含 MPE 合并标记（^ < >）的表格展平为标准 Markdown。
+    多遍扫描：>（右→左）→ <（左→右）→ ^（上→下），
+    每遍将标记替换为被合并方向的内容。
+    展平后由 postprocess_table_rowspan 检测重复内容生成 rowspan/colspan。
+    """
+    header = table_lines[0]
+    sep = table_lines[1]
+    data_rows = table_lines[2:]
+
+    # 解析所有数据行
+    parsed = [_split_table_cells(tl) for tl in data_rows]
+    if not parsed:
+        return [header, sep]
+
+    # 统一列宽（以表头为准）
+    num_cols = len(_split_table_cells(header))
+    for i, row in enumerate(parsed):
+        if len(row) < num_cols:
+            row.extend([""] * (num_cols - len(row)))
+        elif len(row) > num_cols:
+            print(f"  [警告] 表格第 {i + 1} 行有 {len(row)} 列，超过表头 {num_cols} 列，多余列被忽略")
+
+    # 第 1 遍：处理 >（右→左，复制右侧单元格内容）
+    for row in parsed:
+        for col in range(num_cols - 2, -1, -1):
+            if row[col].strip() == ">":
+                row[col] = row[col + 1]
+
+    # 第 2 遍：处理 <（左→右，复制左侧单元格内容）
+    for row in parsed:
+        for col in range(1, num_cols):
+            if row[col].strip() == "<":
+                row[col] = row[col - 1]
+
+    # 第 3 遍：处理 ^（上→下，复制上方单元格内容）
+    prev_cells = _split_table_cells(header)
+    while len(prev_cells) < num_cols:
+        prev_cells.append("")
+    for row in parsed:
+        for col in range(num_cols):
+            if row[col].strip() == "^":
+                row[col] = prev_cells[col] if col < len(prev_cells) else row[col]
+        prev_cells = list(row)
+
+    # 重建表格行
+    flattened = [header, sep]
+    for row in parsed:
+        flattened.append("| " + " | ".join(row[:num_cols]) + " |")
+
+    return flattened
+
+
+# ---------- HTML 表格后处理（连续相同单元格 → rowspan / colspan） ----------
+# 依赖 Python markdown "tables" 扩展生成 <tbody> 包裹数据行。
+
+TD_RE = re.compile(r'<td([^>]*)>(.*?)</td>', re.DOTALL)
+TR_RE = re.compile(r'<tr>(.*?)</tr>', re.DOTALL)
+TBODY_RE = re.compile(r'(<tbody>.*?</tbody>)', re.DOTALL)
+
+
+def postprocess_table_rowspan(html):
+    """
+    扫描 HTML 表格的 <tbody>，将连续内容相同的单元格合并：
+      - 同一列上下连续相同 → rowspan
+      - 同一行左右连续相同 → colspan
+    与 preprocess_mpe_tables 配合：MPE 标记展平后产生重复内容，此处恢复为视觉合并。
+
+    注意：仅处理 <tbody> 内的 <tr>（Python markdown tables 扩展的输出格式）。
+    """
+    def merge_tbody(match):
+        tbody = match.group(1)
+        rows = TR_RE.findall(tbody)
+        if len(rows) < 2:
+            return tbody
+
+        # 解析所有单元格
+        row_cells = []
+        for row_html in rows:
+            cells = []
+            for m in TD_RE.finditer(row_html):
+                cells.append({"attrs": m.group(1).strip(), "text": m.group(2).strip()})
+            row_cells.append(cells)
+
+        if not row_cells:
+            return tbody
+
+        num_cols = max(len(rc) for rc in row_cells) if row_cells else 0
+        num_rows = len(row_cells)
+        if num_cols == 0:
+            return tbody
+
+        # covered[r][c]：该单元格已被 rowspan 或 colspan 覆盖，渲染时跳过
+        covered = [[False] * num_cols for _ in range(num_rows)]
+        rowspan = [[1] * num_cols for _ in range(num_rows)]
+        colspan = [[1] * num_cols for _ in range(num_rows)]
+
+        # ---- 计算 rowspan（逐列扫描） ----
+        for col in range(num_cols):
+            row = 0
+            while row < num_rows:
+                if col >= len(row_cells[row]):
+                    row += 1
+                    continue
+                count = 1
+                r = row + 1
+                while r < num_rows:
+                    if (col < len(row_cells[r])
+                            and row_cells[r][col]["text"] == row_cells[row][col]["text"]
+                            and row_cells[row][col]["text"] != ""):
+                        count += 1
+                        covered[r][col] = True
+                        r += 1
+                    else:
+                        break
+                if count > 1:
+                    rowspan[row][col] = count
+                row = r  # 跳过已被当前 rowspan 覆盖的行
+
+        # ---- 计算 colspan（逐行扫描，跳过已覆盖单元格） ----
+        for row in range(num_rows):
+            col = 0
+            while col < len(row_cells[row]):
+                if covered[row][col]:
+                    col += 1
+                    continue
+                count = 1
+                c = col + 1
+                while c < num_cols and c < len(row_cells[row]):
+                    if (not covered[row][c]
+                            and row_cells[row][c]["text"] == row_cells[row][col]["text"]
+                            and row_cells[row][col]["text"] != ""):
+                        count += 1
+                        covered[row][c] = True
+                        c += 1
+                    else:
+                        break
+                if count > 1:
+                    colspan[row][col] = count
+                col = c  # 跳过已被当前 colspan 覆盖的列
+
+        # ---- 生成带 rowspan / colspan 的 HTML ----
+        new_rows = []
+        for row in range(num_rows):
+            new_cells = []
+            for col in range(num_cols):
+                if covered[row][col] or col >= len(row_cells[row]):
+                    continue
+                cell = row_cells[row][col]
+                rs = rowspan[row][col]
+                cs = colspan[row][col]
+                attrs = cell["attrs"]
+                if rs > 1:
+                    attrs += f' rowspan="{rs}"'
+                if cs > 1:
+                    attrs += f' colspan="{cs}"'
+                new_cells.append(f'<td{attrs}>{cell["text"]}</td>')
+            new_rows.append("<tr>" + "".join(new_cells) + "</tr>")
+
+        return "<tbody>" + "".join(new_rows) + "</tbody>"
+
+    return TBODY_RE.sub(merge_tbody, html)
+
+
 # ---------- Markdown → HTML ----------
 
 def markdown_to_html(text):
@@ -529,6 +765,9 @@ def main():
         # 图片属性处理
         text = process_image_attrs(text)
 
+        # MPE 表格合并预处理（^ → rowspan）
+        text = preprocess_mpe_tables(text)
+
         # KaTeX 预处理
         text = preprocess_katex(text)
 
@@ -549,6 +788,7 @@ def main():
 
     # 2. 注入锚点 + 提取目录
     full_html = inject_anchors(full_html)
+    full_html = postprocess_table_rowspan(full_html)
     toc = generate_toc(full_html)
     print(f"  目录条目数: {len(toc)}")
 

doc_builder/checks/__init__.py

@@ -0,0 +1,3 @@
+# checks — 检查脚本
+# 文件命名: *.py (除 __init__.py 外)
+# 函数签名: check(project_dir: str) -> list[str]

doc_builder/processors/__init__.py

@@ -0,0 +1,3 @@
+# processors — 数据处理器
+# 文件命名: *.py (除 __init__.py 外)
+# 函数签名: load(filepath: Path) -> Any

doc_builder/renderers/__init__.py

@@ -0,0 +1,3 @@
+# renderers — 自定义渲染器
+# 文件命名: render_<name>.py
+# 函数签名: render(content: str) -> str

project.yaml

@@ -1,6 +1,6 @@
 # ez-Q 2.5 读出子系统编程控制模型
-title: 读出子系统历史无关功能配置项
+title: ez-Q 2.5 读出子系统编程控制模型
-subtitle: ez-Q 2.5 读出子系统编程控制模型
+subtitle: 
 author: 郭成
 version: V0.3
 doc_type: 用户手册
@@ -11,16 +11,18 @@ chapters:
   - 01-changelog.md
   - 02-preface.md
   - 03-overview.md
-  - 04-acq-model.md
+  - 04-00-acq-model.md
   - 04-01-acq-downconversion.md
   - 04-02-acq-codeword.md
   - 04-03-acq-registers.md
   - 04-04-acq-matched-filter.md
   - 04-05-acq-data-processing.md
-  - 05-exct-model.md
+  - 04-06-acq-pipeline-demo.md
-  - 05-01-exct-codeword.md
+  - 05-00-exc-model.md
-  - 05-02-exct-registers.md
+  - 05-01-exc-codeword.md
-  - 05-03-exct-wavetable.md
+  - 05-02-exc-registers.md
-  - 05-04-exct-waveform-store.md
+  - 05-03-exc-wavetable.md
-  - 05-05-exct-upconversion.md
+  - 05-04-exc-waveform-store.md
+  - 05-05-exc-upconversion.md
   - 05-06-pump-config.md
+  - 05-07-exc-pipeline-demo.md