Update docs: symbol tables, terminated/truncated, run commands

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`（表格法原理与推导）。*