diff --git a/dqn/dqn-maze.md b/dqn/dqn-maze.md
index e28416c..6f45641 100644
--- a/dqn/dqn-maze.md
+++ b/dqn/dqn-maze.md
@@ -1,7 +1,5 @@
 # DQN 走迷宫：原理与推导
 
-> 对应代码 `dqn/dqn_maze.py`（PyTorch 实现）。本文不含代码，只讲数学。行内公式用 `$...$`、独立公式用 `$$...$$`，Gitea 可直接渲染。
-
 ---
 
 ## 一、为什么需要 DQN
@@ -38,13 +36,28 @@ $$\nabla_{\theta}L=\mathbb{E}\Big[-2\big(Y-Q(s,a;\theta)\big)\,\nabla_{\theta}Q(
 
 这正是把贝尔曼最优方程的**样本近似**当成监督学习的"标签"：$Y$ 当标签、$Q(s,a;\theta)$ 当预测，用梯度下降让预测逼近标签。$Y$ 本身又依赖旧参数 $\theta^{-}$，所以这是"自举式"（bootstrap）的监督——目标会随学习移动。
 
+**符号说明**：
+
+| 符号 | 含义 |
+|---|---|
+| $\theta$ | 主网络参数（全部权重矩阵），每步梯度更新 |
+| $\theta^{-}$ | 目标网络参数，$\theta$ 的滞后副本，每 $C$ 步同步一次；算 $Y$ 时冻结、不求梯度 |
+| $Q(s,a;\theta)$ | 输入状态 $s$，网络输出的动作 $a$ 的 Q 值（"预测"） |
+| $Y$ | TD 目标（"标签"）：本步实际奖励 $r$ 加 $\gamma$ 倍下一状态的最优价值估计 |
+| $r,\ s',\ a'$ | 本步实际观测到的值：拿到的奖励、到达的新状态、新状态下设想尝试的动作 |
+| $\max_{a'}$ | 对 $s'$ 处全部 4 个动作的 Q 值取最大，即"假设下一步走最优" |
+| $\gamma$ | 折扣因子，本实现取 0.99 |
+| $\mathbb{E}_{(s,a,r,s')}$ | 对经验转移的分布求期望；实现上就是回放池小批量上的平均 |
+| $L(\theta)$ | MSE 损失：预测与标签之差的平方的期望 |
+| $\nabla_{\theta}L$ | 损失对 $\theta$ 的梯度；Adam 沿其反方向更新参数 |
+
 ---
 
 ## 三、两个关键技巧
 
 ### 3.1 经验回放（Replay Buffer）
 
-把每条经历 $(s,a,r,s',done)$ 存入一个容量有限的缓冲池，训练时**随机抽一个小批量**更新。
+把每条经历 $(s,a,r,s',terminated)$ 存入一个容量有限的缓冲池，训练时**随机抽一个小批量**更新。注意存的是 `terminated`（到达终点）而非 `truncated`（超时截断）：截断只是回合被强制叫停，未来价值依然存在，TD 目标不应因此丢掉 bootstrap 项。
 
 **为什么必须这么做**：TD 目标依赖下一个状态，而连续几步的状态高度相关。若直接用当前轨迹在线更新，梯度在时间上强相关，损失会剧烈震荡甚至发散；随机抽样把这些样本打乱成近似独立同分布，相当于稳定的"数据集"，梯度才像普通监督学习那样平稳下降。此外一条经验可被多次复用，样本效率更高。
 
@@ -94,7 +107,7 @@ $$\nabla_{\theta}L=\mathbb{E}\Big[-2\big(Y-Q(s,a;\theta)\big)\,\nabla_{\theta}Q(
 
 ## 七、运行与观测
 
-运行参数：`--rows/--cols`（默认 9，须奇数）、`--seed`、`--episodes`（默认 800）、`--braid`、`--hidden`、`--plot`。输出：迷宫、策略箭头、贪心路径、成功率统计；`--plot` 生成两张图。
+在仓库根目录运行：`python -m dqn.dqn_maze --plot`；参数：`--rows/--cols`（默认 9，须奇数）、`--seed`、`--episodes`（默认 800）、`--braid`、`--hidden`、`--plot`。输出：迷宫、策略箭头、贪心路径、成功率统计；`--plot` 生成两张图。
 
 | 图 | 判读 |
 |---|---|
@@ -125,4 +138,4 @@ $$L(\theta)=\mathbb{E}\big[(r+\gamma\max_{a'}Q(s',a';\theta^{-})-Q(s,a;\theta))^
 
 ---
 
-*配套阅读：《Q-Learning公式推导详解.md》（理论）、《q-learning.md》（表格法原理）。*
+*配套阅读：`q_learning/q-learning.md`（表格法原理与推导）。*
diff --git a/q_learning/q-learning.md b/q_learning/q-learning.md
index a4232a8..6bb7f4b 100644
--- a/q_learning/q-learning.md
+++ b/q_learning/q-learning.md
@@ -1,7 +1,5 @@
 # Q-Learning 走迷宫：简明原理与推导
 
-> 对应代码 `q_learning.py`（numpy 实现，可选 matplotlib 绘图）。本文不含代码，只保留核心公式与结论。行内公式用 `$...$`、独立公式用 `$$...$$`，Gitea 网页端可直接渲染；建议搭配支持数学渲染的本地查看器（VSCode 预览、Typora、Obsidian）使用。
-
 ---
 
 ## 一、问题：迷宫 = 马尔可夫决策过程（MDP）
@@ -28,6 +26,20 @@ $$G_t=\sum_{k=0}^{\infty}\gamma^{k}R_{t+k+1}$$
 
 其绝对值的上界为 $|G_t|\le 100/(1-\gamma)$，即收敛有界。目标是最大化起点期望回报：$\pi^{*}=\arg\max_{\pi}\mathbb{E}_{\pi}[G_0]$。
 
+**符号说明**（全文记号约定）：
+
+| 符号 | 含义 |
+|---|---|
+| $t$ | 离散时间步编号（第几步）；一条轨迹为 $\cdots\to S_t\to A_t\to R_{t+1}\to S_{t+1}\to A_{t+1}\to R_{t+2}\to\cdots$ |
+| $S_t,\ A_t,\ R_{t+1}$ | 第 $t$ 步所处的状态、执行的动作、以及该步之后拿到的即时奖励 |
+| 奖励下标 $t{+}1$ | 约定：$R_{t+1}$ 是执行 $A_t$、转移到 $S_{t+1}$ 时得到的奖励，写在引发它的动作之后 |
+| 大写 vs 小写 | 大写（$S_t,A_t,R_{t+1},G_t$）= 随机变量（结局未定）；小写（$s,a,r$）= 具体取值（已发生的实际值） |
+| $s'$ | 走一步之后到达的新状态，即 $S_{t+1}=s'$ |
+| $\gamma$ | 折扣因子，$\gamma^{k}$ 给 $k$ 步之后的奖励加权，本例取 0.9 |
+| $G_t$ | 回报：从 $t$ 时刻起未来全部奖励的折扣和，"从这里玩到底的打折总分" |
+| $\mathbb{E}[\,\cdot\mid\cdot\,]$ | 条件期望："在竖线右边的前提下，左边量的长期平均" |
+| $\pi$ | 策略：每个状态下选各动作的概率规则；$\pi(a\mid s)$ 表示在 $s$ 选 $a$ 的概率 |
+
 ---
 
 ## 二、价值函数与贝尔曼方程
@@ -70,6 +82,17 @@ $$Q(s,a)\leftarrow Q(s,a)+\alpha[r+\gamma\max_{a'}Q(s',a')-Q(s,a)]$$
 
 其中 $\alpha=0.1$，$\delta_t=r+\gamma\max_{a'}Q(s',a')-Q(s,a)$。
 
+**符号说明**：
+
+| 符号 | 含义 |
+|---|---|
+| $\leftarrow$ | 赋值：把右端算出的数写进 Q 表的 $(s,a)$ 位置，不是数学等式 |
+| $\alpha$ | 学习率（0~1 之间）：本次按多大比例采纳误差 |
+| $\delta_t$ | TD 误差：新信息与旧预期之差。$\delta_t>0$ 说明实际比预期好，上调；反之下调 |
+| $Y=r+\gamma\max_{a'}Q(s',a')$ | TD 目标：一步真实奖励 $r$ + 下一状态最优价值的现有估计（"标签"） |
+| $\max_{a'}$ | 对 $s'$ 处全部 4 个动作的 Q 值取最大，即"假设下一步走最优"——off-policy 的来源 |
+| $s',\ a'$ | 到达的新状态、以及在其处设想尝试的动作（只用来查表估值，并不真的执行） |
+
 关键结论：
 
 - **收敛**：需每个 $(s,a)$ 被访问无穷多次，且学习率满足 $\sum\alpha=\infty$、$\sum\alpha^{2}<\infty$（Watkins 1992，以概率 1 收敛）。本实现取常数 $\alpha$，确定性环境下无采样噪声，固定 $(s,a)$ 可解析解：
@@ -79,7 +102,8 @@ $$Q(s,a)\leftarrow Q(s,a)+\alpha[r+\gamma\max_{a'}Q(s',a')-Q(s,a)]$$
   误差以 $(1-\alpha)^{k}$ 几何衰减（$\alpha=0.1$ 时约 22 次访问缩小一个数量级）；真正的瓶颈是价值逐层传播（层数 = 最短路长 $D$），故迷宫越大越需更多训练。
 - **Off-policy**：未来项用 $\max_{a'}Q(s',\cdot)$，与行为策略（含探索）无关，因此收敛到 $Q^{*}$。
 - **vs SARSA**：SARSA 的未来项用实际执行的 $a'$，逼近 $\mathbb{E}_{a'\sim\pi_\varepsilon}[\cdot]$ 而非 max，收敛到 ε-greedy 策略自身的价值；在带陷阱环境里 SARSA 学出保守绕行，Q-Learning 学理论最优。
-- **终止状态**：$done$ 时目标值不含 bootstrap 项，仅为 $r$。
+- **vs Monte Carlo**：MC 等一局结束，用真实回报 $G_t$ 作目标——无偏，但含整局探索噪声（方差大），且必须等回合结束、只有到达过终点的局才有强信号；TD 单步自举——有偏（初期 $Q$ 尚未传开导致系统性低估，$\max$ 算子带来高估），但方差小、每步可学、样本利用率高。实践中 TD 几乎总收敛更快。
+- **终止与截断**：`terminated`（到达终点，真正的终止状态）时目标值不含 bootstrap 项，仅为 $r$；超时截断 `truncated`（达到 `max_steps`）**不是**终止状态，目标仍含 bootstrap 项——回合只是被强制叫停，未来价值依然存在。
 
 ---
 
@@ -144,7 +168,7 @@ $$V(d)=\gamma^{d-1}(100+\frac{1}{1-\gamma})-\frac{1}{1-\gamma}$$
 
 ## 七、运行与观察
 
-运行参数：`--rows/--cols`（默认 9，须为奇数）、`--seed`、`--episodes`（默认 500）、`--braid`（默认 0）、`--plot`。输出：迷宫、策略箭头、贪心路径、成功率统计；加 `--plot` 生成两张图。
+在仓库根目录运行：`python -m q_learning.q_learning --plot`；参数：`--rows/--cols`（默认 9，须为奇数）、`--seed`、`--episodes`（默认 500）、`--braid`（默认 0）、`--plot`。环境接口遵循 Gymnasium 风格：`reset()` 返回 `(obs, info)`，`step(a)` 返回 `(obs, r, terminated, truncated, info)`。输出：迷宫、策略箭头、贪心路径、成功率统计；加 `--plot` 生成两张图。
 
 | 图 | 数学对象 | 判读 |
 |---|---|---|