# 项目说明

LaTeX 学习笔记：相控阵 DoA + Doppler 估计与 CRB 推导。作者 Josh Gao，单人项目。

## 结构

- 主文件：`doa_doppler_est.tex`（preamble 与 `\input` 列表）
- 章节源：`parts/*.tex`
- 文献：`ref.bib`
- 图片：`fig/`
- `archive/`：主线之外的历史草稿，仅供查阅，不参与 `\input`。`/archive/` 在 .gitignore 里只是阻止新草稿意外被追踪，已追踪的旧稿继续保留版本史。

## Codex 工作任务

本文件是本仓库面向 Codex 的工作契约。每次开始任务时，先读取本文件并核对当前工作树；以下顺序定义我的默认工作任务：

1. **确认范围与依据**：工作主体限定为本仓库内学习笔记的建模、推导、LaTeX 源文件、文献和图表任务。涉及三仓协同时，仅按下方 `COORDINATION.md` 接口读取必要的共识与 inbox，或写入协议允许的回灌消息，不把其他仓库的局部实现直接当成本仓事实。
2. **维护通用推导**：围绕联合似然、EFIM/MCRB、可辨识性、聚合族闭式等主题，补全或修正可复用、参数化的模型与推导；把论文专属叙事留在协同文件和研究计划中，不带入正文。
3. **保持证据边界**：以现有源文件、SPEC 和已验证结果为依据，不编造公式、文献结论或实验结果。推导尚未完成时在对应 `.tex` 文件保留 `% TODO:`，不在本文件写临时占位说明。
4. **遵守编辑约束**：沿用本文件规定的符号、公式、交叉引用、中文 LaTeX 排版和章节递进规则；删除或重命名文件时保留 Git 历史，并保留与任务无关的用户改动。
5. **验证并交付**：涉及 `.tex` 的改动完成后按下方 LaTeX 约束编译并检查日志；交付时说明实际改动和验证结果。除非用户另有要求，不推送、创建分支或越过协同接口修改其他仓库。

---

# 三仓协同（COORDINATION.md 接口）

并行三仓工作流，本仓（doa\_doppler\_est）= 其中的 **doc** 角色（建模 + 完整推导）。

- **三仓职责**：`paper-search`（文献调研 + 研究计划）· **本仓 doc**（联合似然、EFIM/MCRB、可辨识性、聚合族闭式等完整推导）· `doa-tools`（MATLAB/Python 代码仓）。三仓**唯一跨界接口**是 `../paper-search/COORDINATION.md`（位于 paper-search 根目录），不直接读写彼此整仓。
- **每会话只读**：`COORDINATION.md` 的 §1 共识账本（必读）+ 与 doc 角色相关的 §2 子段（§2A survey→doc 模型 brief、§2B doc→code 回灌）+ §3 inbox 中发给 doc（DOC/→doc）的条目。**不读全文**（防跨仓污染）。
- **写协议**：改本仓 owner 段（§2B doc→code 的推导回灌）可直接编辑；**给别仓的消息只 append 到 §3 inbox**，签名 `[YYYY-MM-DD · DOC → 目标]`，小而精准、不整段重写别人段；编辑前先读当前文件。curator 是 paper-search 会话，本仓不做 curation。
- **SPEC 是只读输入**：`COORDINATION.md` 的 §1 共识账本与研究计划（`研究计划 - 多星多用户上行协同定位_TWC版.md`）的 §5/§7/§8 是 doc 的**模型 SPEC，只读**；据此推导，结论回灌写 §2B / §3 inbox。

## 本仓是论文超集，正文不沾 paper 口径

doa\_doppler\_est **不是为某篇论文构建的**，而是同一套 DoA 估计方法的合集，是论文的**超集**。研究计划只作为 SPEC 指导该论文相关推导**以通用、参数化方式纳入本仓**，按通用模型的特例落位——

- 正文（`parts/*.tex`）**不出现 paper 专属口径**：不写"paper 1 / paper 2 / 本文 / TWC / reviewer / contribution / novelty / 头号近邻"等论文叙事词，不引用研究计划的章节号或 §编号。
- 协同/部署/AI 加速器等论文专属框架**不进正文**；只有其中可一般化的**模型与推导**（多用户分离、多星几何、时间戳 nuisance 的 EFIM/MCRB、聚合族闭式）以中性、自洽的学习笔记口吻纳入。
- 论文专属的判断、口径、协作决策只存在于 `COORDINATION.md` 与研究计划里；本仓 commit message 与 .tex 均不复述。

---

# 写作风格

- **学习笔记优先**：正文按"由简到繁"递进，每节开头一段过渡，说明上一节限制如何被解除、本节引入什么结构。
- **一节一维度**：每节只沿一个维度推进，其他维度保持最简。
- **正文止于结论**：信号模型、负对数似然、集中似然准则、EFIM/CRB 表达式都给出，矩阵代入与逐步化简推到附录。
- **成稿口吻，不留重构痕迹**：正文与附录是一个整体，按定稿状态描述结构。不用"迁移/移入/搬到附录"等暗示编辑过程的动词，详细推导以"见附录 X""集中在附录"陈述其所在。
- **符号跟随问题引入**：每个符号在首次出现的那一节定义；完整索引在附录 A。
- **单模型推导段用裸主参数符号**：节内只涉及一个模型时，主参数/干扰参数/似然记作裸 $\boldsymbol\eta/\boldsymbol\psi/\boldsymbol\kappa/\mathcal L$，不挂模型下标（stat/dyn/pos/mu/cp/ip 等）；模型下标只在跨模型对照叙述处临时挂回。简单等式对照（如两模型主参数相同）用散文或 `\eqref{}` 引用，不并置双下标。完整带标签定义集中在符号索引 A。
- **不创造元章节**："放置规则"、"阅读路线图"等元信息不进正文，归入前言或本文件。
- **语言**：中文为主；公式、符号、文件路径、命令用英文。
- **推导卡壳留 `% TODO:` 注释**，不编造 placeholder 文字。具体推导待办放在 .tex 源文件里，不进 `AGENTS.md`。

---

# LaTeX 操作约束

- **修改完成后默认编译验证**（一律带 `-synctex=1`）。每次改动收尾即编译：至少跑两次让 ref 稳定，有 bib 引用时夹一次 `biber`（或直接 `latexmk -xelatex -synctex=1` 自动处理多遍与 biber）；检查 log 里的 `! `、`undefined references`、`label(s) may have changed`，全部消除后再 commit。
- **编译一律带 `-synctex=1`**：裸 `xelatex` 会覆盖 PDF 却不更新 `.synctex.gz`，使 VS Code 源码↔PDF 双向索引（SyncTeX）失效。若已用裸命令编过，补跑一次 `xelatex -synctex=1` 重建 synctex 即可。
- **编译产物在 .gitignore，不主动 add，也不主动 rm**：用户在本地可能反复使用。
- **不读编译产物**：`*.aux`、`*.log`、`*.bbl`、`*.bcf`、`*.synctex.gz`、`*.run.xml`、`*.toc`、`*.ist`、`*.glo`、`*.acn`、根目录历史 PDF（`doa_doppler_est_*.pdf`）、`*.zip`。
- **preamble 指主文件 `\documentclass` 到 `\begin{document}` 之间的宏包/计数器/glossary 等设置**。新增或修复 `\newacronym` 词条不算改 preamble，按 `fix(preamble)` 处理。`\input` 列表可按重构需要调整。
- **不重排 `ref.bib`**：除非明确要求。
- **删除/重命名文件用 `git mv`**：保留 history，diff 更小。归档主线之外的旧稿先 `git mv` 到 `archive/`。
- **中文双引号统一用 ``…''**：开引号为两个反引号、闭引号为两个单引号。不用 ASCII 直引号（XeLaTeX 下渲染为竖直引号）或 Unicode 弯引号 ""，只有 TeX 连字能正确渲染成对中文引号。
- **与正文连续的公式用 `%` 隔行占位**：公式与正文无空行相接（句子流入公式、读完继续）时，在文字与 `\begin{equation}` 之间、`\end{equation}` 与后续文字之间各置一行单独的 `%`；既在源码中分隔公式块，又保持同段、不触发新段缩进。`%` 占位行不影响渲染输出。公式自成段落（前后留空行）的不加。
- **矩阵行向量用逗号、不与 `&` 混用**：单行列表式行向量（如时间模板 $[q_0,\ldots,q_{T-1}]$）用逗号分隔、不写 `&`；多行或二维矩阵用 `&`+`\\`、不加逗号。`&`（列分隔）与逗号（列表分隔）不在同一矩阵内并存。`cases` 中逗号作值的标点、`&` 作对齐点，属正常用法，不在此列。
- **行内分式用 `\dfrac`、行间分式用 `\frac`**：行内 `$...$`（含跨多行的行内式）内的分式一律 `\dfrac`（显示级、更易读）；行间环境（`equation`/`align`/`gather` 等）内一律 `\frac`（行间本就是显示级，`\dfrac` 冗余）。导数作**独立分式、链式连乘或算子记号**时同样守此约定（行内 `\dfrac`、行间 `\frac`；链乘写 `\left(\dfrac{}{}\right)\left(\dfrac{}{}\right)`，括号用 `\left\right` 随分式缩放；算子写 `\dfrac{\partial}{\partial x}`）；**仅当其作\emph{行内}行向量/矩阵条目**（堆叠会撑高文本行，如行内 $\mathbf D_{\ell,k}=[\,\partial g/\partial\alpha,\ldots]$）时才用斜杠 `∂f/∂x`；行间矩阵（`bmatrix` 或方括号行向量，如 $\mathbf D_\ell$、$\mathbf H_\ell$）有竖直空间、照常用 `\frac`（见 A 规则 14）。
- **定界符包大型算符用 `\left\right`**：括号/方/花括号若包住 `\frac`、带上下限 `\sum`、矩阵等高于一行的内容，一律用 `\left(\right)`/`\left[\right]`/`\left\{\right\}` 自适应缩放，不用固定尺寸 `\big`/`\Big`/`\bigg`；包单行正常高度内容（参数列表、单行矩阵乘积）的 `\big`/`\Big` 可保留，求值杠 `\big|`/`\bigg|` 属正常用法。
- **标题正下方紧贴的多行公式用 `\tightalign`**：`align`/`gather` 等 amsmath 多行环境不走 TeX 原生 `$$`，紧跟标题（section/subsection/subsubsection/`\paragraph`）时会比 `equation` 多出约一行空白。需编号贴末行（故不改用 `equation`+`aligned`，其号垂直居中）时，在标题与公式之间插入 `\tightalign`（preamble 定义为 `\vspace*{-\baselineskip}`）抵消；若该公式本可单编号，也可直接换 `equation`+`aligned`。
- **正文已定义缩写用 `\gls{key}`**：`\newacronym` 词条的短形式在正文出现时一律用 `\gls`，不写裸短形式。例外（保留裸短形式）：section/subsection 标题、`\caption` 题注、数学模式内的记号与下标（如 $\mathbf a_{\mathrm{UPA}}$、$\widehat{\bm\Theta}_{\mathrm{CDML}}$）、以及"全称（缩写）"并列释义。
- **正文交叉引用**：节用 `第~\ref{}~节`、小节用 `第~\ref{}~小节`（区间 `第~\ref{A}--\ref{B}~小节`）；附录（节与小节）统一用 `\appref{}`，渲染为附录 X 或附录 X.Y。不用 `\S`/§，正文也不写裸 `\ref`（附录会漏掉"附录"前缀）。
- **公式引用用 `\eqref{}`，不用"上式/上一式/此式/下式"等位置指代**：被引用的公式需带 `\label`；若目标公式尚无 label，先补 label 再引用。`\eqref` 与相邻中文之间前后留空格（句首句末、紧邻标点除外）——它输出 Latin `(X.Y)`，无 xeCJK 空格泄漏问题，与输出中文、须紧贴前字的 `\appref` 相反。

---

# Git 提交规范

## 格式

```
<type>(<scope>): <中文 subject，命令式，≤50 字>

<可选 body，每行 ≤72 字>
```

## type（仅 4 类）

| type | 用途 |
|------|------|
| `struct` | 文件移动/合并/拆分、`\input` 顺序调整 |
| `content` | 实质性内容：新增/改写推导、过渡段、文献、图表 |
| `fix` | 修错：typo、公式错、断引用、缺词条 |
| `meta` | 元文件：AGENTS.md、.gitignore、.gitattributes |

## scope（细分维度）

- 章节定位：`sec1`–`sec7`、`app-A`…`app-G`、`preamble`
- 跨章节专题：`symbol`、`bib`、`fig`

## body 强制规则

- `type=struct` **必须**有 body，说明拆/合的依据
- `scope=symbol` **必须**有 body，说明符号冲突或废弃原因
- 其他自由，建议解释"为什么"而非"什么"

## subject 规则

- 中英混合：type 用英文，scope/subject 用中文
- 命令式动词开头："新增 / 删除 / 合并 / 重命名 / 修正"
- 不写"添加了 / 已完成"等完成时
- 不加句号

## 其他硬规则

- **结构改动与内容改动分开 commit**——"重命名 A6 → E" (`struct`) 与 "E.2 新增多用户推导" (`content`) 必须是两个 commit
- **改完即提交**——每个逻辑改动经编译验证后立即按规范 commit，不把多个改动攒在工作区；攒着会让 struct 与 content 混在同一文件、日后无法干净拆 commit
- **不写 `Co-Authored-By` 尾注**——个人学习笔记
- subject 与 body 风格不一致时，参考既往 commit 历史定调

---

# 效率与 token 准则

- **优先 `Grep`/`Glob` 直接命中**：`parts/*.tex` 路径稳定、符号命名规律，三五次 Grep 即可定位绝大多数任务。仅当跨 10+ 文件做开放式分析时才用 Agent 子代理；子代理冷启动会重读上下文，单点查询用它得不偿失。
- **不为了"再确认"重读刚改过的文件**：Edit/Write 失败会立即报错，harness 自带状态追踪。
- **独立的工具调用一次并行发出**：多条 Grep/Glob/Read 没有依赖时合并到同一轮。
- **大文件局部读取**：`ref.bib` 几千条 entry 用 Grep 查找特定 key，不要 Read 全文；长 .tex 用 `offset`/`limit` 跳到目标区域。
- **不创建中间元文档**（`plan.md`、`todo.md`、`analysis.md`、`summary.md`）：所有内容应进 `parts/` 或 commit message，不另起辅助文件。
- **响应不写 trailing summary，commit 后不复述改动清单**——用户看 diff 与 commit message 即可。
- **避免向用户罗列"我接下来会……"的长方案**：直接执行小步操作，停在用户需要决策的节点。