n## 重要的日子
7/1：♥️糖醋羊排CP成立！！♥️

Track

• sunclientlogin发票报销到账
• 开固态硬盘发票

Routine

爱心屋签到： aixinwu.sjtu.edu.cn/products/asw-store
每日二GRISSO💊， 米诺地尔

Starting from 10/9:

Non-routine

论文

Due

• 大论文
  • 硕士论文的布局，参考已有的（journal paper）
  • 实机试验，在工业环境/生活场景（难度更高）下，工具抓取
• 64G内存
• ICRA paper acceptance notification 1/31
• tzc233.github.io 一周年纪念日 2026/5/21
• 读书会吃饭 2026/3/23

No Due

• 保温杯
• “现在的贺卡好高级”
• 软考
• ccf csp
• 穹彻智能实习
• Godot Learning [[Godot Learning Plan]]
• 琪琪水彩
• 流萤水彩
• 美罗城 云海肴 汽锅鸡
• 《涉过愤怒的海》
• 《被讨厌的勇气》读书会p16
• 《被寄生的家庭》读书会p18
• 《蛙》读书会 p21
• 《断舍离》读书会 p20
• 潮汕砂锅粥
• 想买…
  • ipad（matebook e go）
  • 欧珑无极乌龙
  • bose大鲨2耳塞套
  • 综合效果器 ..?
  • 清音音箱
  • 220V户外电源

有生之年系列

• 手工🎸
• 侍奉社

Archived

• 攀爬机器人 🔒Done! 2025-10-21 🕸️ Track > Routine > Non-routine > Due
  • 群组建立
  • 其他构型的机器人
  • 数字样机调研
  • 初步进度安排
• AI Lab 具身智能简历投递 10/11 🔒Done! 2025-10-21 🕸️ Track > Routine > Non-routine > Due
• 奖学金申请10/18 5p.m. 🔒Done! 2025-10-31 🕸️ Track > Routine > Non-routine > Due
• 电网论文修改（作为通讯） 🔒Done! 2025-11-08 🕸️ Track > Routine > Non-routine > Due
  • 分类号加一下TN919.8，标识码A
  • 公式精简，保持现有篇幅，加入测试图片，文章前部分的图片往后挪
  • 合并一下1.2,1.3(2.1空间定位, 2.2分布推理机制，2.3预警方式), 第一章为系统总体架构设计，删除第一句话，不需要人机交互模块
  • 性能测试（仅保留第一句话）
    • 3.1 视觉检测模块分布推理的性能测试
    • 3.2 参考bohan实验
  • 把系统实现合并到系统设计，不需要系统实现章节
  • 明确论文重点(low latency)
  • 版面空间节省
    • 对比试验设计
      • 系统延迟表现
        • model quantization
        • layer pruning
      • 整个系统的综合表现（survey，参考bohan论文）
  • 低光照’
• 电网验收 11/11 上午 🔒Done! 2025-12-02 🕸️ Track > Routine > Non-routine > Due
  • hololens和手机开会议
  • 预训练识别
• draumurvakna.github.io 一周年纪念日 2025/10/27 🔒Done! 2025-12-02 🕸️ Track > Routine > Non-routine > Due
• 攀爬机器人 🔒Done! 2026-01-02 🕸️ Track > Routine > Non-routine > Due
  • 需要的数据
    • 真实的角钢照片，问byy要
    • 3D渲染生成照片
    • 深度图生成（包括噪声）
    • 更换背景
  • moveit路径规划视频
  • 测试塔需求文档（结构，工期，价格）
  • 机器人URDF导入unity,演示基本步态，动作流
• 糖糖呵护指南 🔒Done! 2026-01-02 🕸️ Track > Routine > Non-routine > No Due
• 给糖糖补补 🔒Done! 2026-01-02 🕸️ Track > Routine > Non-routine > No Due

Bayes’ Theorem | Bayesian Inference

概述

贝叶斯公式（Bayes’ Theorem）是概率论中的基本定理，描述了如何根据新证据更新对事件概率的信念。它是贝叶斯统计学、机器学习、人工智能等领域的理论基础，提供了一种系统化的方法来处理不确定性和进行推理。

公式形式

基本形式

$$P(A|B) = \frac{P(B|A) \times P(A)}{P(B)}$$

参数估计形式

$$P(\theta|D) = \frac{P(D|\theta) \times P(\theta)}{P(D)}$$

或写成：

$$\text{后验概率} = \frac{\text{似然} \times \text{先验}}{\text{证据}}$$

各项含义

边缘似然的计算

$$P(D) = \int P(D|\theta)P(\theta)d\theta$$

或离散情况：

$$P(D) = \sum_{\theta} P(D|\theta)P(\theta)$$

直观理解

贝叶斯公式回答：**”看到证据后，我应该如何更新我的信念？”**

$$\text{新信念} = \frac{\text{旧信念} \times \text{证据支持度}}{\text{归一化}}$$

核心思想：

• 从先验信念开始
• 根据观测到的证据调整信念
• 得到更新后的后验信念

实际例子

例 1：医疗诊断

场景：

• 某疾病患病率 1%（先验）
• 测试准确率：患病时阳性 95%，健康时阳性 5%
• 你测试呈阳性

问：你真的患病的概率是多少？

解答：

设：

• $A$ = 患病
• $B$ = 测试阳性

已知：

• $P(A) = 0.01$（先验）
• $P(B|A) = 0.95$（真阳性率）
• $P(B|\neg A) = 0.05$（假阳性率）

计算边缘似然：

$$P(B) = P(B|A)P(A) + P(B|\neg A)P(\neg A)$$
$$= 0.95 \times 0.01 + 0.05 \times 0.99 = 0.059$$

应用贝叶斯公式：

$$P(A|B) = \frac{P(B|A) \times P(A)}{P(B)} = \frac{0.95 \times 0.01}{0.059} \approx 0.16$$

结论：即使测试阳性，患病概率只有 **16%**！

反直觉原因：先验概率很低（1%），大部分阳性结果来自假阳性。

例 2：垃圾邮件过滤

场景：

• 邮件中 30% 是垃圾邮件
• 垃圾邮件中 80% 含”中奖”
• 正常邮件中 5% 含”中奖”

问：含”中奖”的邮件是垃圾邮件的概率？

解答：

设：

• $S$ = 垃圾邮件
• $W$ = 含”中奖”

已知：

• $P(S) = 0.3$
• $P(W|S) = 0.8$
• $P(W|\neg S) = 0.05$

计算：

$$P(W) = 0.8 \times 0.3 + 0.05 \times 0.7 = 0.275$$

$$P(S|W) = \frac{0.8 \times 0.3}{0.275} \approx 0.87$$

结论：含”中奖”的邮件有 87% 概率是垃圾邮件。

例 3：机器学习中的参数估计

场景：训练一个分类模型

目标：找到最优参数 $\theta$

$$P(\theta|D) = \frac{P(D|\theta) \times P(\theta)}{P(D)}$$

• **似然 $P(D|\theta)$**：模型拟合数据的好坏
• **先验 $P(\theta)$**：对参数的正则化（如 L2 正则 = 高斯先验）
• **后验 $P(\theta|D)$**：综合考虑数据和先验的最优参数

最大后验估计（MAP）：

$$\theta_{MAP} = \arg\max_{\theta} P(\theta|D) = \arg\max_{\theta} P(D|\theta)P(\theta)$$

贝叶斯推断流程

1. 指定先验

根据领域知识或假设选择先验分布：

$$P(\theta)$$

常见先验：

• 无信息先验：均匀分布（表示无知）
• 共轭先验：使后验与先验同分布（计算方便）
• 正则化先验：高斯分布（L2 正则）、拉普拉斯分布（L1 正则）

2. 收集数据

观测数据 $D = {x_1, x_2, \ldots, x_N}$

3. 计算似然

根据模型计算数据的似然：

$$P(D|\theta) = \prod_{i=1}^{N} P(x_i|\theta)$$

4. 应用贝叶斯公式

计算后验分布：

$$P(\theta|D) = \frac{P(D|\theta)P(\theta)}{P(D)}$$

5. 进行推断

• 点估计：MAP 或后验均值
• 区间估计：可信区间（credible interval）
• 预测：$P(x_{new}|D) = \int P(x_{new}|\theta)P(\theta|D)d\theta$

贝叶斯 vs 频率学派

例子对比

问题：抛硬币 10 次，8 次正面，估计正面概率 $\theta$

频率学派：

$$\hat{\theta}_{MLE} = \frac{8}{10} = 0.8$$

贝叶斯学派（假设先验 $\theta \sim \text{Beta}(2,2)$）：

$$P(\theta|D) = \text{Beta}(2+8, 2+2) = \text{Beta}(10, 4)$$

后验均值：

$$\mathbb{E}[\theta|D] = \frac{10}{10+4} \approx 0.71$$

差异：贝叶斯方法考虑了先验信念（硬币应该接近公平），结果更保守。

在机器学习中的应用

1. 朴素贝叶斯分类器

$$P(y|x_1, \ldots, x_n) = \frac{P(y) \prod_{i=1}^{n} P(x_i|y)}{P(x_1, \ldots, x_n)}$$

应用：文本分类、垃圾邮件过滤

2. 贝叶斯线性回归

$$P(w|D) = \frac{P(D|w)P(w)}{P(D)}$$

优势：提供预测的不确定性

3. 贝叶斯神经网络

对网络权重建模为分布而非点估计：

$$P(w|D) \propto P(D|w)P(w)$$

应用：不确定性量化、主动学习

4. 变分推断

当后验 $P(\theta|D)$ 难以计算时，用简单分布 $q(\theta)$ 近似：

$$\min_q D_{KL}(q(\theta)||P(\theta|D))$$

应用：VAE、主题模型（LDA）

5. 马尔可夫链蒙特卡洛（MCMC）

通过采样近似后验分布：

$$\theta^{(t+1)} \sim P(\theta|D)$$

应用：贝叶斯深度学习、概率编程

先验的选择

1. 无信息先验（Non-informative Prior）

目的：表达”无知”

例子：

• 均匀分布：$P(\theta) = \text{Uniform}(a, b)$
• Jeffreys 先验：$P(\theta) \propto \sqrt{|I(\theta)|}$（基于 Fisher 信息）

2. 共轭先验（Conjugate Prior）

定义：后验与先验同分布族

例子：

优势：后验有闭式解，计算简单

3. 正则化先验

目的：防止过拟合

例子：

• 高斯先验：$P(w) = \mathcal{N}(0, \lambda^{-1}I)$ → L2 正则化
• 拉普拉斯先验：$P(w) = \text{Laplace}(0, b)$ → L1 正则化

4. 经验贝叶斯（Empirical Bayes）

从数据中估计先验的超参数：

$$\hat{\alpha} = \arg\max_{\alpha} P(D|\alpha)$$

常见问题

问题 1：先验是主观的吗？

回答：

• 是：先验反映了建模者的信念或假设
• 但：可以通过以下方式减少主观性：
  • 使用无信息先验
  • 使用领域知识
  • 使用经验贝叶斯
  • 数据足够多时，后验主要由似然决定

问题 2：贝叶斯方法计算复杂吗？

回答：

• 共轭先验：后验有闭式解，计算简单
• 非共轭情况：需要近似方法
  • 变分推断（快速但近似）
  • MCMC（精确但慢）
  • 拉普拉斯近似（快速但粗糙）

问题 3：为什么 P(D) 叫”证据”？

回答：

• $P(D)$ 是观测数据的边缘概率
• 在模型比较中，$P(D)$ 衡量模型对数据的解释能力
• 更高的 $P(D)$ 意味着模型更好地”证明”了数据的存在

问题 4：贝叶斯公式可以连续更新吗？

回答：可以！这是贝叶斯方法的优势。

顺序更新：

$$P(\theta|D_1, D_2) = \frac{P(D_2|\theta)P(\theta|D_1)}{P(D_2|D_1)}$$

前一次的后验成为下一次的先验：

1

先验 → [数据1] → 后验1 → [数据2] → 后验2 → ...

最佳实践

1. 选择合适的先验

1
2
3
4
5
6
7
8

# 弱信息先验（数据主导）
prior = Normal(0, 10)

# 强信息先验（先验主导）
prior = Normal(0, 0.1)

# 正则化先验
prior = Normal(0, 1/lambda)  # 等价于 L2 正则

2. 检查先验的影响

1
2
3
4

# 先验预测检查
prior_samples = prior.sample(1000)
prior_predictions = model(prior_samples)
# 检查先验预测是否合理

3. 后验检查

1
2
3
4

# 后验预测检查
posterior_samples = posterior.sample(1000)
posterior_predictions = model(posterior_samples)
# 与真实数据对比

4. 使用对数空间计算

1
2

# 避免数值下溢
log_posterior = log_likelihood + log_prior - log_evidence

代码示例

PyTorch 实现贝叶斯线性回归

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

import torch
import torch.distributions as dist

# 数据
X = torch.randn(100, 1)
y = 3 * X + 2 + torch.randn(100, 1) * 0.5

# 先验
prior_w = dist.Normal(0, 1)
prior_b = dist.Normal(0, 1)

# 似然
def likelihood(w, b, X, y, sigma=0.5):
    y_pred = w * X + b
    return dist.Normal(y_pred, sigma).log_prob(y).sum()

# 后验（使用变分推断近似）
q_w_mu = torch.nn.Parameter(torch.randn(1))
q_w_sigma = torch.nn.Parameter(torch.ones(1))
q_b_mu = torch.nn.Parameter(torch.randn(1))
q_b_sigma = torch.nn.Parameter(torch.ones(1))

optimizer = torch.optim.Adam([q_w_mu, q_w_sigma, q_b_mu, q_b_sigma], lr=0.01)

# 优化 ELBO
for _ in range(1000):
    optimizer.zero_grad()

    # 从变分分布采样
    w = q_w_mu + q_w_sigma * torch.randn(1)
    b = q_b_mu + q_b_sigma * torch.randn(1)

    # ELBO = 似然 - KL散度
    log_lik = likelihood(w, b, X, y)
    kl_w = dist.kl_divergence(
        dist.Normal(q_w_mu, q_w_sigma),
        prior_w
    )
    kl_b = dist.kl_divergence(
        dist.Normal(q_b_mu, q_b_sigma),
        prior_b
    )

    elbo = log_lik - kl_w - kl_b
    loss = -elbo

    loss.backward()
    optimizer.step()

print(f"后验均值: w={q_w_mu.item():.2f}, b={q_b_mu.item():.2f}")

参考资源

• Bayesian Data Analysis - Andrew Gelman et al.
• Pattern Recognition and Machine Learning - Christopher Bishop
• Probabilistic Machine Learning: An Introduction - Kevin Murphy
• Bayesian Methods for Hackers

Variational Inference | Evidence Lower Bound | VAE Paper

概述

ELBO（Evidence Lower Bound，证据下界）是变分推断中的核心概念，用于近似难以计算的边缘似然 $\log p(x)$。ELBO 提供了一个可优化的目标函数，使得复杂概率模型的训练变得可行，是现代深度生成模型（如 VAE）的理论基础。

核心概念

什么是 ELBO

ELBO 是对数边缘似然 $\log p(x)$ 的下界：

$$\text{ELBO} = \mathbb{E}{q(z|x)}[\log p(x,z)] - \mathbb{E}{q(z|x)}[\log q(z|x)]$$

或等价形式：

$$\text{ELBO} = \mathbb{E}{q(z|x)}[\log p(x|z)] - D{KL}(q(z|x)||p(z))$$

其中：

• $x$ 是观测数据
• $z$ 是隐变量
• $q(z|x)$ 是近似后验分布（变分分布）
• $p(z)$ 是先验分布
• $p(x|z)$ 是似然函数

ELBO 的推导

目标：最大化边缘似然 $\log p(x)$

$$\log p(x) = \log \int p(x,z)dz$$

这个积分通常难以计算。引入变分分布 $q(z|x)$：

$$\begin{align}
\log p(x) &= \log \int p(x,z)dz \
&= \log \int \frac{q(z|x)}{q(z|x)} p(x,z)dz \
&= \log \mathbb{E}{q(z|x)}\left[\frac{p(x,z)}{q(z|x)}\right] \
&\geq \mathbb{E}{q(z|x)}\left[\log\frac{p(x,z)}{q(z|x)}\right] \quad \text{[Jensen 不等式]} \
&= \text{ELBO}
\end{align}$$

关键关系：

$$\log p(x) = \text{ELBO} + D_{KL}(q(z|x)||p(z|x))$$

由于 $D_{KL} \geq 0$，所以 ELBO 是 $\log p(x)$ 的下界。

ELBO 的两种解释

解释 1：重构 + 正则化

$$\text{ELBO} = \underbrace{\mathbb{E}{q(z|x)}[\log p(x|z)]}{\text{重构项}} - \underbrace{D_{KL}(q(z|x)||p(z))}_{\text{正则化项}}$$

• 重构项：衡量模型拟合数据的能力
• 正则化项：约束后验分布接近先验分布

解释 2：似然 - 复杂度

$$\text{ELBO} = \underbrace{\mathbb{E}{q(z|x)}[\log p(x|z)]}{\text{数据似然}} - \underbrace{D_{KL}(q(z|x)||p(z))}_{\text{模型复杂度惩罚}}$$

这体现了奥卡姆剃刀原则：在解释数据的同时保持模型简单。

为什么要优化 ELBO

1. 直接计算困难

真实后验 $p(z|x) = \frac{p(x|z)p(z)}{p(x)}$ 难以计算，因为：

$$p(x) = \int p(x|z)p(z)dz$$

这个积分在高维空间中通常没有闭式解。

2. 等价优化

最大化 ELBO 等价于最小化 $D_{KL}(q(z|x)||p(z|x))$：

$$\begin{align}
\log p(x) &= \text{ELBO} + D_{KL}(q(z|x)||p(z|x)) \
\max_q \text{ELBO} &\Leftrightarrow \min_q D_{KL}(q(z|x)||p(z|x))
\end{align}$$

因为 $\log p(x)$ 不依赖于 $q$，最大化 ELBO 就是让 $q(z|x)$ 尽可能接近真实后验 $p(z|x)$。

3. 可计算性

ELBO 可以通过蒙特卡洛采样估计：

$$\text{ELBO} \approx \frac{1}{L}\sum_{i=1}^{L} \log p(x|z_i) - D_{KL}(q(z|x)||p(z))$$

其中 $z_i \sim q(z|x)$。

ELBO 在 VAE 中的应用

VAE 架构

1

输入 x → Encoder → μ(x), σ(x) → 采样 z ~ N(μ,σ²) → Decoder → 重构 x̂

VAE 的假设

• 先验：$p(z) = \mathcal{N}(0, I)$（标准正态分布）
• 后验：$q(z|x) = \mathcal{N}(\mu(x), \sigma^2(x)I)$（编码器输出）
• 似然：$p(x|z) = \mathcal{N}(\text{Decoder}(z), I)$（解码器输出）

ELBO 的具体形式

$$\text{ELBO} = \mathbb{E}{q(z|x)}[\log p(x|z)] - D{KL}(q(z|x)||p(z))$$

重构项（需要采样估计）：

$$\mathbb{E}{q(z|x)}[\log p(x|z)] \approx \frac{1}{L}\sum{i=1}^{L} \log p(x|z_i), \quad z_i \sim q(z|x)$$

通常 $L=1$（单样本估计）。对于伯努利分布的似然，这等价于二元交叉熵。

KL 项（有闭式解）：

$$D_{KL}(q(z|x)||p(z)) = -\frac{1}{2}\sum_{j=1}^{J}\left(1 + \log\sigma_j^2 - \mu_j^2 - \sigma_j^2\right)$$

其中 $J$ 是隐变量维度。

损失函数

VAE 的损失函数是 负 ELBO（因为要最小化）：

$$\mathcal{L} = -\text{ELBO} = \underbrace{-\mathbb{E}{q(z|x)}[\log p(x|z)]}{\text{重构损失}} + \underbrace{D_{KL}(q(z|x)||p(z))}_{\text{KL 损失}}$$

重参数化技巧

问题

直接从 $z \sim \mathcal{N}(\mu(x), \sigma^2(x))$ 采样不可微，无法反向传播。

解决方案：重参数化

核心思想：将随机性外部化

1
2
3
4
5

原始：z ~ N(μ, σ²)  ❌ 不可微

重参数化：
ε ~ N(0, I)         ✓ 随机性独立于参数
z = μ + σ ⊙ ε       ✓ 可微变换

梯度流

1
2

损失 → Decoder → z = μ + σε → μ, σ → Encoder
                  ↑ 可微！

• $\varepsilon$ 是常数（从参数角度），梯度不经过它
• $\mu$ 和 $\sigma$ 的梯度可以正常计算

代码实现

PyTorch 实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

import torch
import torch.nn as nn
import torch.nn.functional as F

class VAE(nn.Module):
    def __init__(self, input_dim=784, hidden_dim=400, latent_dim=20):
        super().__init__()

        # Encoder
        self.fc1 = nn.Linear(input_dim, hidden_dim)
        self.fc_mu = nn.Linear(hidden_dim, latent_dim)
        self.fc_logvar = nn.Linear(hidden_dim, latent_dim)

        # Decoder
        self.fc3 = nn.Linear(latent_dim, hidden_dim)
        self.fc4 = nn.Linear(hidden_dim, input_dim)

    def encode(self, x):
        """编码器：x → μ, log(σ²)"""
        h = torch.relu(self.fc1(x))
        mu = self.fc_mu(h)
        logvar = self.fc_logvar(h)  # log(σ²) 数值稳定
        return mu, logvar

    def reparameterize(self, mu, logvar):
        """重参数化技巧：z = μ + σε"""
        std = torch.exp(0.5 * logvar)  # σ = exp(0.5*log(σ²))
        eps = torch.randn_like(std)     # ε ~ N(0,I)
        z = mu + eps * std              # z = μ + σε
        return z

    def decode(self, z):
        """解码器：z → x��"""
        h = torch.relu(self.fc3(z))
        return torch.sigmoid(self.fc4(h))

    def forward(self, x):
        mu, logvar = self.encode(x)
        z = self.reparameterize(mu, logvar)
        recon_x = self.decode(z)
        return recon_x, mu, logvar

def vae_loss(recon_x, x, mu, logvar):
    """
    VAE 损失函数 = -ELBO

    Args:
        recon_x: 重构的 x
        x: 原始 x
        mu: 编码器输出的均值
        logvar: 编码器输出的 log(σ²)

    Returns:
        总损失 = 重构损失 + KL 损失
    """
    # 重构损失：-E[log p(x|z)]
    # 对于伯努利分布 = 二元交叉熵
    BCE = F.binary_cross_entropy(recon_x, x, reduction='sum')

    # KL 散度：KL(q(z|x)||p(z))
    # 闭式解：-0.5 * Σ(1 + log(σ²) - μ² - σ²)
    KLD = -0.5 * torch.sum(1 + logvar - mu.pow(2) - logvar.exp())

    return BCE + KLD

# 训练循环
model = VAE()
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)

for epoch in range(num_epochs):
    for batch_x in dataloader:
        optimizer.zero_grad()

        # 前向传播
        recon_x, mu, logvar = model(batch_x)

        # 计算损失（负 ELBO）
        loss = vae_loss(recon_x, batch_x, mu, logvar)

        # 反向传播
        loss.backward()
        optimizer.step()

关键实现细节

1. 使用 log(σ²) 而非 σ：数值稳定性更好
2. KL 散度的闭式解：避免采样估计
3. 重参数化：使采样过程可微
4. 单样本估计：重构项通常只采样一次

正则化的作用

什么是正则化

正则化是防止模型过拟合的技术，通过约束模型复杂度：

$$\text{损失函数} = \text{数据拟合项} + \lambda \times \text{正则化项}$$

常见类型：

• L2 正则：$\lambda||w||^2$ - 权重衰减
• L1 正则：$\lambda||w||$ - 稀疏性
• Dropout：随机关闭神经元
• Early Stopping：提前停止训练

VAE 中的正则化

ELBO 天然包含正则化：

$$\text{ELBO} = \underbrace{\mathbb{E}[\log p(x|z)]}{\text{拟合数据}} - \underbrace{D{KL}(q(z|x)||p(z))}_{\text{正则化}}$$

KL 散度项的作用：

1. 约束隐空间结构：强制 $q(z|x)$ 接近先验 $p(z) = \mathcal{N}(0,I)$
2. **防止编码器”作弊”**：避免为每个样本学习独特的、互不相关的编码
3. 保证连续性：使隐空间平滑、可插值
4. 实现解耦表示：鼓励学习独立的隐变量

没有 KL 正则化会怎样？

如果只优化重构损失：

1

loss = reconstruction_loss  # 没有 KL 项

问题：

• 编码器可能���每个样本映射到隐空间的任意位置
• 隐空间结构混乱，无法生成新样本
• 方差 $\sigma$ 可能趋近于 0（退化为确定性编码）

KL 正则化的效果：

• 强制隐变量分布接近标准正态分布
• 保证隐空间的连续性和平滑性
• 使得从先验 $p(z)$ 采样可以生成有意义的样本

应用场景

1. 变分自编码器（VAE）

用途：生成模型、表示学习

1
2
3

# 训练后生成新样本
z = torch.randn(batch_size, latent_dim)  # 从先验采样
generated_x = model.decode(z)

2. 主题模型（LDA）

用途：文档主题发现

• 隐变量 $z$：文档的主题分布
• ELBO 用于推断主题

3. 贝叶斯神经网络

用途：不确定性量化

• 隐变量 $z$：网络权重
• ELBO 用于近似权重的后验分布

4. 隐马尔可夫模型（HMM）

用途：序列建模

• 隐变量 $z$：隐藏状态序列
• ELBO 用于推断状态

5. 高斯混合模型（GMM）

用途：聚类分析

• 隐变量 $z$：样本所属的簇
• ELBO 用于推断簇分配

最佳实践

1. 平衡重构与 KL 损失

有时需要调整 KL 项的权重：

1

loss = reconstruction_loss + beta * kl_loss  # β-VAE

• β < 1：更注重重构质量
• β > 1：更注重解耦表示
• β = 1：标准 VAE

2. KL 退火（KL Annealing）

训练初期降低 KL 权重，逐渐增加：

1
2

beta = min(1.0, epoch / warmup_epochs)
loss = reconstruction_loss + beta * kl_loss

原因：避免”后验坍缩”（posterior collapse），即 $q(z|x)$ 过早收敛到先验。

3. 自由比特（Free Bits）

为每个隐变量维度设置最小 KL 值：

1
2

kl_per_dim = kl_loss / latent_dim
kl_loss = torch.sum(torch.max(kl_per_dim, free_bits_threshold))

作用：防止某些维度被忽略。

4. 数值稳定性

1
2
3
4
5
6

# 使用 log(σ²) 而非 σ
logvar = self.fc_logvar(h)
std = torch.exp(0.5 * logvar)  # 避免负数

# 避免 log(0)
recon_x = torch.clamp(recon_x, min=1e-7, max=1-1e-7)

常见问题

问题 1：ELBO 为什么是下界？

解答：根据 Jensen 不等式，对于凹函数 $\log$：

$$\log \mathbb{E}[X] \geq \mathbb{E}[\log X]$$

因此：

$$\log p(x) = \log \mathbb{E}{q(z|x)}\left[\frac{p(x,z)}{q(z|x)}\right] \geq \mathbb{E}{q(z|x)}\left[\log\frac{p(x,z)}{q(z|x)}\right] = \text{ELBO}$$

问题 2：为什么叫”证据”下界？

解答：在贝叶斯推断中，$p(x)$ 被称为”证据”（evidence）或”边缘似然”（marginal likelihood），因为它是观测数据 $x$ 的概率。ELBO 是这个证据的下界。

问题 3：重参数化技巧为什么有效？

解答：重参数化将随机性从参数中分离出来：

1

z = μ(x; θ) + σ(x; θ) ⊙ ε,  ε ~ N(0,I)

• $\varepsilon$ 不依赖于 $\theta$，是外部噪声
• $\mu$ 和 $\sigma$ 依赖于 $\theta$，可以求梯度
• 梯度可以通过 $\mu$ 和 $\sigma$ 反向传播到编码器

问题 4：VAE 生成的图像为什么模糊？

原因：

1. 高斯似然假设：$p(x|z) = \mathcal{N}(\text{Decoder}(z), I)$ 倾向于生成平均化的结果
2. 重构损失：MSE 或 BCE 惩罚像素级差异，导致模糊

改进方法：

• 使用更复杂的似然分布（如混合高斯）
• 使用感知损失（perceptual loss）
• 结合 GAN（VAE-GAN）

参考资源

• Auto-Encoding Variational Bayes (VAE 原论文)
• Tutorial on Variational Autoencoders
• β-VAE: Learning Basic Visual Concepts with a Constrained Variational Framework
• Understanding disentangling in β-VAE
• Pattern Recognition and Machine Learning - Christopher Bishop

Information Theory | Kullback-Leibler Divergence

概述

KL 散度（Kullback-Leibler Divergence），也称为相对熵（Relative Entropy），是信息论和统计学中用于衡量两个概率分布差异的重要度量。它在机器学习、深度学习、变分推断等领域有广泛应用。
本笔记重点介绍 KL 散度的基础定义、数学推导、核心性质以及其在机器学习中的意义。

数学定义

离散概率分布

对于离散概率分布 $P$ 和 $Q$，KL 散度定义为：

$$D_{KL}(P||Q) = \sum_{x} P(x) \log\frac{P(x)}{Q(x)}$$

连续概率分布

对于连续概率分布，KL 散度定义为：

$$D_{KL}(P||Q) = \int p(x) \log\frac{p(x)}{q(x)} dx$$

其中：

• $P$ 是真实分布（或目标分布）
• $Q$ 是近似分布（或模型分布）
• $\log$ 通常使用自然对数（以 $e$ 为底），单位为 nats；使用以 2 为底的对数时，单位为 bits

核心性质

1. 非负性

$$D_{KL}(P||Q) \geq 0$$

当��仅当 $P = Q$ 时，等号成立（即 $D_{KL}(P||Q) = 0$）。

2. 非对称性

$$D_{KL}(P||Q) \neq D_{KL}(Q||P)$$

这意味着 KL 散度不是真正的距离度量，因为它不满足对称性。

3. 不满足三角不等式

KL 散度不满足三角不等式：

$$D_{KL}(P||R) \not\leq D_{KL}(P||Q) + D_{KL}(Q||R)$$

因此，KL 散度不是度量空间中的距离函数。

4. 凸性

KL 散度关于第一个参数 $P$ 是凸函数。

直观理解

信息论角度

KL 散度表示：用分布 $Q$ 来编码分布 $P$ 的样本时，相比用 $P$ 自身编码所需的额外信息量（以比特或 nats 为单位）。

• 如果 $Q$ 与 $P$ 完全相同，则不需要额外信息，$D_{KL}(P||Q) = 0$
• 如果 $Q$ 与 $P$ 差异很大，则需要更多额外信息来补偿编码效率的损失

统计学角度

KL 散度衡量分布 $Q$ 对分布 $P$ 的近似程度：

• 值越小，$Q$ 越接近 $P$
• 值越大，$Q$ 与 $P$ 的差异越大

机器学习角度

在机器学习中，通常：

• $P$ 是真实数据分布（未知但可以从数据中采样）
• $Q$ 是模型学习的分布（由参数 $\theta$ 决定）
• 最小化 $D_{KL}(P||Q)$ 等价于让模型分布尽可能接近真实分布

数学推导

1. 从信息熵推导

信息熵（Entropy）

分布 $P$ 的信息熵定义为：

$$H(P) = -\sum_{x} P(x) \log P(x)$$

它表示编码分布 $P$ 的样本所需的平均最小比特数。

交叉熵（Cross Entropy）

用分布 $Q$ 来编码分布 $P$ 的样本所需的平均比特数：

$$H(P, Q) = -\sum_{x} P(x) \log Q(x)$$

KL 散度 = 交叉熵 - 信息熵

$$\begin{align}
D_{KL}(P||Q) &= H(P, Q) - H(P) \
&= -\sum_{x} P(x) \log Q(x) + \sum_{x} P(x) \log P(x) \
&= \sum_{x} P(x) [\log P(x) - \log Q(x)] \
&= \sum_{x} P(x) \log\frac{P(x)}{Q(x)}
\end{align}$$

这表明 KL 散度是使用次优编码方案 $Q$ 相比最优编码方案 $P$ 所需的额外信息量。

2. 非负性证明（Gibbs 不等式）

我们使用 Jensen 不等式来证明 KL 散度的非负性。

Jensen 不等式

对于凸函数 $f(x)$ 和概率分布 $P$：

$$f\left(\sum_{x} P(x) \cdot x\right) \leq \sum_{x} P(x) \cdot f(x)$$

对于凹函数（如 $\log$），不等号反向。

证明过程

由于 $f(x) = -\log(x)$ 是凸函数，我们有：

$$\begin{align}
D_{KL}(P||Q) &= \sum_{x} P(x) \log\frac{P(x)}{Q(x)} \
&= -\sum_{x} P(x) \log\frac{Q(x)}{P(x)} \
&\geq -\log\left(\sum_{x} P(x) \cdot \frac{Q(x)}{P(x)}\right) \quad \text{[Jensen 不等式]} \
&= -\log\left(\sum_{x} Q(x)\right) \
&= -\log(1) \
&= 0
\end{align}$$

等号成立当且仅当 $\frac{Q(x)}{P(x)}$ 为常数，即 $P(x) = Q(x)$ 对所有 $x$ 成立。

结论：$D_{KL}(P||Q) \geq 0$，且仅当 $P = Q$ 时等号成立。

3. 与最大似然估计的关系

在机器学习中，我们通常希望找到参数 $\theta$ 使得模型分布 $P_\theta$ 尽可能接近真实数据分布 $P_{data}$。

最小化 KL 散度

$$\begin{align}
\min_\theta D_{KL}(P_{data}||P_\theta) &= \min_\theta \sum_{x} P_{data}(x) \log\frac{P_{data}(x)}{P_\theta(x)} \
&= \min_\theta \left[\sum_{x} P_{data}(x) \log P_{data}(x) - \sum_{x} P_{data}(x) \log P_\theta(x)\right] \
&= \min_\theta \left[-\sum_{x} P_{data}(x) \log P_\theta(x)\right] \quad \text{[第一项与 $\theta$ 无关]} \
&= \max_\theta \sum_{x} P_{data}(x) \log P_\theta(x)
\end{align}$$

经验分布近似

在实践中，我们无法直接访问 $P_{data}$，但可以从数据集 ${x_1, x_2, \ldots, x_N}$ 中采样。使用经验分布：
$$P_{data}(x) \approx \frac{1}{N} \sum_{i=1}^{N} \delta(x - x_i)$$

代入上式：

$$\max_\theta \sum_{x} P_{data}(x) \log P_\theta(x) \approx \max_\theta \frac{1}{N} \sum_{i=1}^{N} \log P_\theta(x_i)$$

这正是最大似然估计（Maximum Likelihood Estimation, MLE）的目标函数！
结论：最小化 KL 散度等价于最大化似然函数。

实际计算示例

示例 1：离散分布

假设真实分布 $P = [0.5, 0.3, 0.2]$，近似分布 $Q = [0.4, 0.4, 0.2]$。

计算 $D_{KL}(P||Q)$：

$$\begin{align}
D_{KL}(P||Q) &= 0.5 \cdot \log\frac{0.5}{0.4} + 0.3 \cdot \log\frac{0.3}{0.4} + 0.2 \cdot \log\frac{0.2}{0.2} \
&= 0.5 \cdot \log(1.25) + 0.3 \cdot \log(0.75) + 0.2 \cdot \log(1) \
&= 0.5 \times 0.2231 + 0.3 \times (-0.2877) + 0 \
&= 0.1116 - 0.0863 \
&\approx 0.0253 \text{ nats}
\end{align}$$

转换为 bits（除以 $\ln 2 \approx 0.693$）：

$$D_{KL}(P||Q) \approx 0.0365 \text{ bits}$$

示例 2：高斯分布

对于两个一维高斯分布：

• $P = \mathcal{N}(\mu_1, \sigma_1^2)$
• $Q = \mathcal{N}(\mu_2, \sigma_2^2)$

KL 散度的闭式解为：

$$D_{KL}(P||Q) = \log\frac{\sigma_2}{\sigma_1} + \frac{\sigma_1^2 + (\mu_1 - \mu_2)^2}{2\sigma_2^2} - \frac{1}{2}$$

特殊情况：当 $Q = \mathcal{N}(0, 1)$（标准正态分布）时：

$$D_{KL}(P||Q) = \frac{1}{2}\left(\mu_1^2 + \sigma_1^2 - \log\sigma_1^2 - 1\right)$$

这个公式在 VAE（变分自编码器）中被广泛使用。

机器学习中的应用

1. 变分推断（Variational Inference）

在贝叶斯推断中，我们希望计算后验分布 $P(\theta|X)$，但通常难以直接计算。变分推断使用一个简单的分布 $Q(\theta)$ 来近似：
$$\min_Q D_{KL}(Q(\theta)||P(\theta|X))$$

2. 变分自编码器（VAE）

VAE 的损失函数包含 KL 散度项，用于正则化潜在空间：

$$\mathcal{L} = \mathbb{E}{q(z|x)}[\log p(x|z)] - D{KL}(q(z|x)||p(z))$$

其中：

• 第一项是重建损失
• 第二项是 KL 散度，约束编码器输出接近先验分布

3. 策略优化（强化学习）

在强化学习中，KL 散度用于约束策略更新的幅度：
$$\max_\theta \mathbb{E}{\pi_\theta}[R] \quad \text{s.t.} \quad D{KL}(\pi_{old}||\pi_\theta) \leq \delta$$

这是 TRPO（Trust Region Policy Optimization）和 PPO（Proximal Policy Optimization）的核心思想。

4. 模型蒸馏（Knowledge Distillation）

使用 KL 散度让小模型（学生）学习大模型（教师）的输出分布：

$$\mathcal{L} = D_{KL}(P_{teacher}||P_{student})$$

5. 生成对抗网络（GAN）

虽然 GAN 不直接优化 KL 散度，但理论分析表明，GAN 的目标函数与 JS 散度（Jensen-Shannon Divergence）相关，而 JS 散度是基于 KL 散度定义的：

$$D_{JS}(P||Q) = \frac{1}{2}D_{KL}(P||M) + \frac{1}{2}D_{KL}(Q||M)$$

其中 $M = \frac{1}{2}(P + Q)$。

前向 KL 与反向 KL

前向 KL：$D_{KL}(P||Q)$

• 含义：用 $Q$ 近似 $P$
• 特点：
  • 当 $P(x) > 0$ 但 $Q(x) = 0$ 时，散度为无穷大
  • 要求 $Q$ 覆盖 $P$ 的所有支撑集（zero-avoiding）
  • $Q$ 倾向于覆盖 $P$ 的所有模式，可能过于分散

反向 KL：$D_{KL}(Q||P)$

• 含义：用 $Q$ 近似 $P$（但优化方向相反）
• 特点：
  • 当 $Q(x) > 0$ 但 $P(x) = 0$ 时，散度为无穷大
  • 要求 $Q$ 集中在 $P$ 的高概率区域（zero-forcing）
  • $Q$ 倾向于选择 $P$ 的某一个模式，可能过于集中

对比表格

与其他散度的关系

1. JS 散度（Jensen-Shannon Divergence）

JS 散度是 KL 散度的对称化版本：

$$D_{JS}(P||Q) = \frac{1}{2}D_{KL}(P||M) + \frac{1}{2}D_{KL}(Q||M)$$
其中 $M = \frac{1}{2}(P + Q)$。
性质：

• 对称：$D_{JS}(P||Q) = D_{JS}(Q||P)$
• 有界：$0 \leq D_{JS}(P||Q) \leq \log 2$
• 满足三角不等式的平方根

2. Wasserstein 距离

Wasserstein 距离（也称为 Earth Mover’s Distance）是另一种衡量分布差异的度量，在 GAN 中被广泛使用（WGAN）。
与 KL 散度相比：

• Wasserstein 距离是真正的度量（满足对称性和三角不等式）
• 即使两个分布没有重叠，Wasserstein 距离仍然有意义
• KL 散度在分布不重叠时可能为无穷大

3. $\chi^2$ 散度

$$D_{\chi^2}(P||Q) = \sum_{x} \frac{(P(x) - Q(x))^2}{Q(x)}$$
与 KL 散度相比，$\chi^2$ 散度对分布差异更敏感。

常见问题

问题 1：为什么 KL 散度不对称？

原因：KL 散度的定义中，$P$ 和 $Q$ 的角色不同：

$$D_{KL}(P||Q) = \sum_{x} P(x) \log\frac{P(x)}{Q(x)}$$

• $P$ 作为权重出现在求和中
• $Q$ 出现在对数的分母中

交换 $P$ 和 $Q$ 会得到不同的结果。

直观理解：

• $D_{KL}(P||Q)$ 衡量”用 $Q$ 编码 $P$ 的样本”的额外信息
• $D_{KL}(Q||P)$ 衡量”用 $P$ 编码 $Q$ 的样本”的额外信息
• 这两者通常不相等

问题 2：什么时候使用前向 KL，什么时候使用反向 KL？

**前向 KL $D_{KL}(P||Q)$**：

• 当你希望 $Q$ 覆盖 $P$ 的所有模式时
• 最大似然估计
• 监督学习
  **反向 KL $D_{KL}(Q||P)$**：
• 当你希望 $Q$ 集中在 $P$ 的高概率区域时
• 变分推断
• VAE、变分贝叶斯

问题 3：KL 散度可以为负吗？

不可以。根据 Gibbs 不等式，KL 散度始终非负：

$$D_{KL}(P||Q) \geq 0$$
当且仅当 $P = Q$ 时，$D_{KL}(P||Q) = 0$。

问题 4：如何处理 $Q(x) = 0$ 的情况？

当 $P(x) > 0$ 但 $Q(x) = 0$ 时，$\log\frac{P(x)}{Q(x)} = \infty$，导致 KL 散度为无穷大。

解决方法：

1. 拉普拉斯平滑：给 $Q(x)$ 加一个小的常数 $\epsilon$
2. 确保支撑集匹配：保证 $Q$ 的支撑集包含 $P$ 的支撑集
3. 使用其他散度：如 Wasserstein 距离，对不重叠分布更鲁棒

最佳实践

1. 数值稳定性

在实现 KL 散度时，避免直接计算 $\log\frac{P(x)}{Q(x)}$，而是使用：

1 2 3 4 5

# 不稳定的实现 kl = P * np.log(P / Q) # 稳定的实现 kl = P * (np.log(P) - np.log(Q))

### 2. 处理零概率

1 2 3

# 添加小的 epsilon 避免 log(0) epsilon = 1e-10 kl = P * (np.log(P + epsilon) - np.log(Q + epsilon))

### 3. 使用库函数
大多数深度学习框架提供了优化的 KL 散度实现：

1 2 3 4 5 6 7 8 9 10 11

# PyTorch import torch.nn.functional as F kl_loss = F.kl_div(Q.log(), P, reduction='batchmean') # TensorFlow import tensorflow as tf kl_loss = tf.keras.losses.KLDivergence()(P, Q) # SciPy from scipy.stats import entropy kl_div = entropy(P, Q)

参考资源

• Information Theory, Inference, and Learning Algorithms - David MacKay
• Pattern Recognition and Machine Learning - Christopher Bishop
• Deep Learning Book - Ian Goodfellow et al.
• Kullback-Leibler Divergence Explained

Claude Code Skills 使用指南

官方文档 | Agent Skills 标准

概述

Skills（技能） 是扩展 Claude Code 能力的自定义工作流。通过 Markdown 文件定义，可以用斜杠命令调用或自动加载。
Skills 遵循开放的 Agent Skills 标准，可跨多个 AI 工具使用。

核心概念

Skills 的作用

• 自定义斜杠命令：直接调用专门的工作流（如 /commit、/review）
• 领域知识注入：为 Claude 提供特定领域的上下文
• 任务指令：定义复杂操作的步骤流程
• 工具集成：连接外部工具和脚本

文件结构

1
2
3
4
5

skill-name/
├── SKILL.md          # 必需：主要技能定义
├── reference.md      # 可选：详细文档
├── examples.md       # 可选：使用示例
└── scripts/          # 可选：辅助脚本

Skill 位置与作用域

优先级：项目级 > 个人级 > 企业级

创建 Skill

基本结构

最简单的 skill 只需一个带 YAML 头的 SKILL.md 文件：

1
2
3
4
5
6
7
8
9
10
11

---
name: explain-code
description: 用图表和类比解释代码。当用户询问"这段代码如何工作"时使用
---

解释代码时，始终包含：

1. **类比**：用日常生活中的事物比喻代码
2. **图表**：用 ASCII 艺术展示流程或结构
3. **逐步讲解**：���释每一步发生了什么
4. **常见误区**：指出容易混淆的点

配置选项 (Frontmatter)

调用方式

1. 直接调用

用户显式使用斜杠命令：

1
2
3

/skill-name
/fix-issue 123
/explain-code src/auth/login.ts

2. 自动调用

当用户请求匹配 skill 的 description 时，Claude 自动加载：

1
2

用户："这个认证流程是如何工作的？"
→ Claude 自动加载 /explain-code skill

控制自动调用：

• 设置 disable-model-invocation: true 禁止自动加载
• 让 description 更具体以避免误触发

传递参数

使用 $ARGUMENTS

$ARGUMENTS 占位符捕获所有参数为单个字符串：

1
2
3
4
5
6
7
8
9
10
11
12

---
name: fix-issue
description: 修复 GitHub issue
---

修复 GitHub issue $ARGUMENTS，遵循我们的编码标准。

1. 从 GitHub 读取 issue 描述
2. 理解需求
3. 实现修复
4. 编写测试
5. 创建提交

用法：/fix-issue 123 → “修复 GitHub issue 123…”

使用位置参数

用 $0、$1、$2 等访问单个参数：

1
2
3
4
5
6
7
8
9
10
11
12

---
name: migrate-component
description: 在框架间迁移组件
argument-hint: [组件名] [源框架] [目标框架]
---

将 $0 组件从 $1 迁移到 $2。

要求：
- 保留所有现有行为
- 维持测试覆盖率
- 更新文档

用法：/migrate-component SearchBar React Vue

• $0 = SearchBar
• $1 = React
• $2 = Vue

高级模式

动态上下文注入

使用反引号`和 ! 在 skill 运行前执行 shell 命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

---
name: pr-summary
description: 总结 Pull Request 的变更
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull Request 上下文

**差异：**
!`gh pr diff`

**评论：**
!`gh pr view --comments`

## 任务

总结这个 PR，重点关注：
1. 主要变更及其目的
2. 审查者的潜在关注点
3. 测试覆盖情况

隔离子代理执行

在隔离上下文中运行 skill，避免污染主对话：

1
2
3
4
5
6
7
8
9
10
11
12
13

---
name: deep-research
description: 深入研究某个主题而不影响主上下文
context: fork
agent: Explore
---

深入研究 $ARGUMENTS：

1. 使用 Glob 和 Grep 查找相关文件
2. 阅读并分析代码
3. 识别模式和关系
4. 用具体的文件引用（file:line 格式）总结发现

工具限制

限制 Claude 在 skill 中可使用的工具：

1
2
3
4
5
6
7
8
9
10

---
name: read-only-analysis
description: 分析代码但不做修改
allowed-tools: Read, Grep, Glob, Bash(git *)
---

分析代码库中的 $ARGUMENTS。

你只能读取文件和运行 git 命令。
不要修改任何文件。

最佳实践

Skill 设计原则

1. 单一职责：每个 skill 应有一个明确目的
2. 清晰描述：description 应匹配用户的自然语言
3. 明确指令：为复杂工作流提供分步指导
4. 错误处理：包含常见失败场景的处理说明

命名规范

• 使用小写加连字符：fix-issue、explain-code
• 保持简短易记
• 使用动词导向的名称

示例 Skills

代码审查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

---
name: review
description: 对变更进行全面的代码审查
disable-model-invocation: true
allowed-tools: Read, Grep, Bash(git *)
---

执行全面的代码审查：

## 审查清单

1. **正确性**：代码是否实现了预期功能？
2. **安全性**：是否存在安全漏洞？
3. **性能**：是否有明显的性能问题？
4. **可维护性**：代码是否可读且结构良好？
5. **测试**：测试覆盖是否充分？

## 流程

1. 运行 `git diff` 查看所有变更
2. 完整阅读修改的文件
3. 检查常见问题：SQL 注入、XSS、命令注入、竞态条件、内存泄漏、硬编码凭证
4. 提供具体反馈，使用 file:line 引用

文档生成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

---
name: document
description: 为代码生成文档
argument-hint: [文件路径]
---

为 $ARGUMENTS 生成全面的文档：

1. 阅读文件并理解其目的
2. 记录：
   - 文件概述和用途
   - 公共 API（函数、类、接口）
   - 使用示例
   - 依赖和要求
3. 格式化为 markdown
4. 在有帮助的地方包含代码示例

常见问题

Skill 未自动触发

问题：Claude 没有在预期时加载你的 skill。

解决方案：

• 让 description 更具体，包含用户会自然说出的关键词
• 检查 /context 确保 skill 描述未超出字符预算
• 验证 skill 文件在正确位置

Skill 触发过于频繁

问题：Skill 在不需要时加载。

解决方案：

• 让 description 更具体
• 添加 disable-model-invocation: true 要求显式调用
• 在 description 中使用更独特的关键词

参数不工作

问题：$ARGUMENTS 或 $0、$1 未被替换。

解决方案：

• 确保传递了参数：/skill-name arg1 arg2
• 检查占位符在 skill 正文中，而非仅在 frontmatter 中
• 验证占位符语法无拼写错误

工作流集成示例

Git 工作流

1
2
3
4
5
6
7
8
9
10
11
12
13

---
name: feature
description: 创建新的功能分支并进行适当设置
argument-hint: [功能名称]
---

为 $ARGUMENTS 创建新的功能分支：

1. 确保工作目录干净
2. 从 main 拉取最新变更
3. 创建分支：`feature/$ARGUMENTS`
4. 设置分支跟踪
5. 创建初始提交

测试工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

---
name: test-fix
description: 修复失败的测试
context: fork
allowed-tools: Bash, Read, Edit
---

修复失败的测试：

1. 运行测试套件识别失败
2. 对每个失败：
   - 阅读测试文件
   - 理解测试内容
   - 阅读实现代码
   - 识别问题
   - 修复代码或更新测试
3. 重新运行测试验证
4. 创建修复提交

参考资源

• 官方 Skills 文档
• Agent Skills 标准
• Claude Code GitHub

注意事项

• Skills 评估顺序：项目级 → 个人级 → 企业级
• / 命令显示所有可用 skills 并支持自动补全
• Skills 可以在指令中调用其他 skills
• 对于耗时操作使用 context: fork 保持主上下文清洁
• Skills 支持 markdown 格式，包括表格、代码块和列表

ROS2通讯总览 (视觉Scope)

ROS2通讯总览

机器人运行流程

初始化流程

上塔流程

攀爬流程

下塔流程

待定，与上塔类似

Node解释

相机采集Node(RoboCamNode)

获取3个相机的视频流
作为RobotCamStream 的publisher，发布相 机RGB-D信息（根据订阅的ExecutorStatus中的freeClaw数据来切换相机源）

关节控制Node(RoboJointNode)

通过CAN通讯控制机械臂关节
作为JointControl的Action server，响应其他Node的控制指令，响应其他Node的关节状态数据请求

电爪控制Node(RoboClawNode)

通过485通讯控制机器人电爪
作为ClawControl的Action server，响应主程序Node的控制指令，响应其他Node的电爪状态数据请求

主程序Node(XclimbotNode)

负责机器人的主要运行流程

用户端通讯Node(UINetworkNode)

负责与用户端控制程序进行网络通讯
从主程序Node获取机器人信息，包括机器人运行状态(RobotStatus)和机器人执行器位置(RobotPosition)
获取相机的视频流信息

ROS Topic

RobotCamStream.msg

持续publish视频流信息

1
2
3
4
5
6

int8 maincam            # 1 for camera_1, 2 for camera_2
uint16 rows             # height = 720
uint16 cols             # width = 1280
uint16[] depth_data
uint8 dimension        # colorspace = 3
uint16[] color_data

ExecutorStatus.msg

返回当前机器人的执行器状态：

1
2
3
4
5

int8[2] claw_status = 0~4 // 0 for 电爪运动中，1 for 已抓紧，2 for 已释放， 3 for 电爪掉落，4 for 错误,总共两个电爪的数据
int8 fasten_status = 0~4 // 0 for 紧固中，1 for 已紧固，2 for 已释放套筒，3 for已插入套筒，4 for 错误
int8 freeClaw = 1 | 2 // 1 for claw_1, 2 for claw_2
int8[6] joint_status, //each element ∈ {1,0} 1 for 运行，0 for运行结束,总共6个关节的数据
int64[6] joint_angle //each element ∈ [-3600000, 3600000],总共6个关节的数据

RunnningStatus.msg

返回当前机器人的状态

1

int16 status = -1~10 // -1代表调试功能，开放所有直接控制功能。其余状态见机器人运行流程的图例

ROS Action

1
2

int64[6] goal_angle // each element ∈ [-3600000, 3600000]
int8[6] vel_limit = 0~30 // unit: RPM，待定

Feedback 为以5Hz频率返回当前关节角度和关节运动状态,表示正在正常执行。

1
2

int64[6] current_angle //each element ∈ [-3600000, 3600000]
int8[6] current_running //each element ∈ {1,0} //1 for 运行，0 for运行结束

Result 用于描述关节运动任务的最终执行结果，仅在任务结束后可获取。

1
2

bool success = true | false
string message // 如果存在错误，报错原因

ClawControl.action

用于控制机器人电爪运动。

1
2
3
4
5
6
7
8
9
10
11
12
13

// request
int8 index = 1 | 2 // 1 for claw_1, 2 for claw_2
int8 grab = 0 | 1 // 0 for grab, 1 for release
int32 force = 700 // unit: N

//feedback 5Hz
int8 index = 1 | 2 // 1 for claw_1, 2 for claw_2
int8 running_status = 0 | 1 // 0 for grabbing, 1 for releasing

//response
int8 index = 1 | 2 // 1 for claw_1, 2 for claw_2
bool success = true | false
string message // 如果存在错误，报错原因

PrepareClimb.action

机器人在攀爬结束后两足均抓取于角钢上，此时需要用户发出继续攀爬指令，机器人抬起自由足会运动到拍摄深度图像的位置。

仅当机器人处于status 2(即“等待用户攀爬指令”)时可以发出指令

1
2
3
4
5
6
7
8
9
10

// request
bool prepare = true

//feedback 5Hz
int64[6] current_angle //each element ∈ [-3600000, 3600000]，电爪当前角度
int8[6] current_running //each element ∈ {1,0} //1 for 运行，0 for运行结束

//respond
bool success = true | false
string message // 如果存在错误，报错原因

VisionSelect.action

用户在用户端点选角钢的坐标数据通过网络发送到用户端通讯Node之后，该Node将坐标信息作为指令目标传给主程序Node，由主程序Node进行图像分析得到抓取点，将mask和抓取点反馈给通讯端Node用于显示。
在用户端程序的视频图像上覆盖显示（半透明）对应的Mask,以及预计抓取点的位置。

这个视觉选择的请求只有当机器人处于status 6 (即“等待用户选取的坐标”)时才有效

1
2
3
4
5
6
7
8
9
10
11
12

//request 
int16 point_x = 0-1280
int16 point_y = 0-720 

//feedback anything

//respond
bool success = true | false
bool[720][1280] mask // if success
int16 result_x = 0-1280 // if success
int16 result_y = 0-720 // if success
string message // if go wrong

DirectJoint.action

直接控制应该为用户端的一个独立窗口（通过菜单栏选项调出）

用户端通讯Node发给主程序Node的指令，可让用户端直接控制关节的运动。

1
2
3
4
5
6
7
8
9
10
11

//request
int64[6] goal_angle // each element ∈ [-3600000, 3600000]
int8 vel_limit = 0~30 // unit: RPM

//feedback 5Hz
int64[6] current_angle //each element ∈ [-3600000, 3600000]
int8[6] current_running //each element ∈ {1,0} //1 for 运行，0 for运行结束

//result
bool success = true | false
string message // 如果存在错误，报错原因

DirectClaw.action

直接控制应该为用户端的一个独立窗口（通过菜单栏选项调出）

用户端通讯Node发给主程序Node的指令，可让用户端直接控制电爪的运动。

1
2
3
4
5
6
7
8
9
10
11
12
13

// request
int8 index = false | true // false for claw_0, true for claw_1
int8 task = 0 | 1 // 0 for grab, 1 for release
int32 force = 700 // unit: N

//feedback 5Hz
int8 index = false | true // false for claw_0, true for claw_1
int8 task = 0 | 1 // 0 for grab, 1 for release

//response
int8 index = 1 | 2 // 1 for claw_1, 2 for claw_2
bool success = true | false
string message // 如果存在错误，报错原因(例如其他几种情况)

ROS Service

1
2
3
4
5
6

//request 
bool stop = true

//respond
bool success = true | false
string message // if go wrong

VisionConfirm.srv

用户端确认抓取点和mask有效与否，将确认信息发回给机器人的用户端通讯Node，用户端通讯Node将确认信息通过service告知主程序Node

这个确认的请求只有当机器人处于status 8 (即“确认抓取结果”)时才有效

1
2
3
4
5

//request 
bool confirm = true | false

//respond
bool received = true

SwitchClaw.srv

用户端点击切换电爪的按钮后，将切换指令发给机器人的用户通讯端Node，用户端通讯Node将确认信息通过service告知主程序Node

仅当机器人处于status 2时可以切换。

1
2
3
4
5
6

//request
bool switch = true

//respond
bool success = true | false
string message // if go wrong (例如此时机器人没有双足抓取角钢，而切换只有在双足抓取角钢时实现)

备注

1

使用一个package robot_interfaces 用于存放所有的接口定义

• 只放接口定义
• 不含任何 node
• 被 server / client / pub / sub 共同依赖

例如:

1
2
3
4
5
6
7
8
9
10
11

my_robot_interfaces/
 ├── msg/
 │   └── RobotCamStream.msg
 ├── srv/
 │   └── RunningStatus.srv
 │   └── ExecutorStatus.srv
 │   └── ...
 └── action/
     └── ClawControl.action
     └── JointControl.action
     └── ...

2

主程序的核心功能由毕老师实验室团队负责实现。杨总团队需基于主程序框架，在主程序中自行完成本文档所定义的各类 ROS 接口（包括 Action、Service、Topic）的 Server 端实现。
同时，杨总团队需提供与上述接口一一对应的功能测试代码或示例调用代码，以便直接集成或粘贴至主程序中，用于接口联调与功能验证，确保接口定义与实际行为的一致性和可测试性。
典型的主程序python示例为(并非具体实现)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

import rclpy
from rclpy.node import Node
from rclpy.action import ActionServer, GoalResponse, CancelResponse

from my_robot_interfaces.action import JointControl

import threading
import time


class XclimbotMainNode(Node):

    def __init__(self):
        super().__init__('xclimbot_main_node')

        # 模拟关节状态（真实项目中来自底层驱动 / CAN）
        self.current_joint_angle = [0] * 6
        self.current_joint_running = [0] * 6

        # Action Server
        self._action_server = ActionServer(
            self,
            JointControl,
            'joint_control',
            execute_callback=self.execute_callback,
            goal_callback=self.goal_callback,
            cancel_callback=self.cancel_callback
        )

        self.get_logger().info('JointControl Action Server started')

    # ---------- Goal 校验 ----------
    def goal_callback(self, goal_request):
        self.get_logger().info(
            f'Received goal: {list(goal_request.goal_angle)}, '
            f'vel_limit={goal_request.vel_limit}'
        )

        # 示例：简单校验
        if len(goal_request.goal_angle) != 6:
            self.get_logger().warn('Invalid goal angle length')
            return GoalResponse.REJECT

        return GoalResponse.ACCEPT

    # ---------- Cancel ----------
    def cancel_callback(self, goal_handle):
        self.get_logger().warn('Received cancel request')
        return CancelResponse.ACCEPT

    # ---------- 执行主逻辑 ----------
    def execute_callback(self, goal_handle):
        self.get_logger().info('Executing JointControl goal')

        feedback = JointControl.Feedback()
        result = JointControl.Result()

        # 标记关节开始运行
        self.current_joint_running = [1] * 6

        rate = self.create_rate(5)  # 5 Hz feedback

        for step in range(20):  # 模拟 4 秒执行过程

            # ---- cancel 检查 ----
            if goal_handle.is_cancel_requested:
                self.get_logger().warn('Goal canceled during execution')

                self.current_joint_running = [0] * 6
                result.success = False
                result.message = 'Goal canceled by client'
                goal_handle.canceled()
                return result

            # ---- 模拟关节运动 ----
            for i in range(6):
                self.current_joint_angle[i] += 1000  # 模拟变化

            # ---- 填充并发送 feedback ----
            feedback.current_angle = self.current_joint_angle
            feedback.current_running = self.current_joint_running
            goal_handle.publish_feedback(feedback)

            self.get_logger().debug(
                f'Feedback sent: {feedback.current_angle}'
            )

            rate.sleep()

        # 执行完成
        self.current_joint_running = [0] * 6
        result.success = True
        result.message = 'Joint motion finished successfully'

        goal_handle.succeed()
        self.get_logger().info('JointControl goal succeeded')

        return result


def main(args=None):
    rclpy.init(args=args)

    node = XclimbotMainNode()
    rclpy.spin(node)

    node.destroy_node()
    rclpy.shutdown()


if __name__ == '__main__':
    main()

测试仅针对接口本身，不涉及对于具体机器人运行逻辑的测试。

• scalable的理解
  • 要能够在 low cost 的情况下复制方法用于新的场景（主要是指数据获取）建议改为More accessible, affordable
• Infared的用处
  • 指尖的抓取行程测距(存在一定noise，几毫米，量程合适)
• 不能只说RL的坏处
• 机器人遥控和人工的Incompatible
• 视角Invarient可不可以用scale up的方式解决

使用 Python 和 Pygame 实现生命游戏

0. 教学目标

通过本实验，学习：

• 使用 二维数组表示离散网格世界

• 理解并实现 生命游戏的局部规则 → 全局演化

• 使用 Pygame 进行基础的二维图形显示

• 使用 键盘事件控制程序行为

• 将一个问题分解为：
  数据结构 → 规则函数 → 显示函数 → 主循环

1. 什么是生命游戏（Conway’s Game of Life）

生命游戏是一个离散、确定性、无随机的元胞自动机：

• 空间：二维网格

• 时间：离散时间步

• 每个格子（细胞）只有两种状态：

  • 活 (1)

  • 死 (0)

1.1 演化规则（只依赖局部）

对每个细胞，统计它周围 8 个邻居 中活细胞的数量：

重要思想：

全局复杂行为来自简单的局部规则

2. 程序整体结构设计

在开始写代码前，先规划模块结构：

1
2
3
4
5
6
7
8

生命游戏程序
│
├── 参数设置（网格大小、颜色）
├── 二维数组表示网格
├── 邻居统计函数
├── 下一代计算函数
├── Pygame 绘制函数
└── 主循环（事件处理 + 显示）

3. 第一步：准备环境和基本参数

3.1 安装并导入库

1

pip install pygame

1
2

import pygame
import random

3.2 定义网格和显示参数

1
2
3
4
5
6

CELL_SIZE = 10          # 每个细胞在屏幕上的像素大小
GRID_WIDTH = 80         # 网格列数
GRID_HEIGHT = 60        # 网格行数

SCREEN_WIDTH = GRID_WIDTH * CELL_SIZE
SCREEN_HEIGHT = GRID_HEIGHT * CELL_SIZE

解释：

• 我们的“世界”是逻辑网格

• Pygame 显示的是像素

• 一个细胞 ↔ 一个矩形

3.3 定义细胞状态和颜色

1
2
3
4
5
6

ALIVE = 1
DEAD = 0

COLOR_BG = (0, 0, 0)
COLOR_CELL = (255, 255, 255)
COLOR_GRID = (40, 40, 40)

4. 第二步：用二维数组表示生命世界

4.1 二维数组的含义

1

grid[y][x]

• y：第几行

• x：第几列

• 值：0 或 1

4.2 随机初始化网格

1
2
3
4
5
6
7
8
9
10
11

def random_grid():
    grid = []  # 用来存放整个二维网格（每一行是一个列表）

    for y in range(GRID_HEIGHT):
        row = []  # 当前行
        for x in range(GRID_WIDTH):
            cell = random.choice([ALIVE, DEAD])
            row.append(cell)
        grid.append(row)

    return grid

更优雅的写法：

1
2
3
4
5

def random_grid():
    return [
        [random.choice([ALIVE, DEAD]) for _ in range(GRID_WIDTH)]
        for _ in range(GRID_HEIGHT)
    ]

教学要点：

• 外层列表 → 行

• 内层列表 → 列

• 每个位置随机赋值

5. 第三步：统计邻居数量（核心逻辑之一）

5.1 邻域定义

每个细胞有 8 个邻居：

1
2
3

(-1,-1) (0,-1) (1,-1)
(-1, 0)   X    (1, 0)
(-1, 1) (0, 1) (1, 1)

5.2 邻居统计函数

1
2
3
4
5
6
7
8
9
10

def count_neighbors(grid, x, y):
    count = 0
    for dy in [-1, 0, 1]:
        for dx in [-1, 0, 1]:
            if dx == 0 and dy == 0:
                continue
            nx, ny = x + dx, y + dy
            if 0 <= nx < GRID_WIDTH and 0 <= ny < GRID_HEIGHT:
                count += grid[ny][nx]
    return count

逐行解释：

• 两层循环遍历 3×3 区域

• 排除自身

• 检查是否越界

• 累加存活细胞数

6. 第四步：计算下一代网格

6.1 为什么不能原地修改？

• 当前状态 → 决定下一状态

• 如果边算边改，会影响后续计算

解决方案：

使用一个新的二维数组

6.2 下一代计算函数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

def next_generation(grid):
    new_grid = [
        [DEAD for _ in range(GRID_WIDTH)]
        for _ in range(GRID_HEIGHT)
    ]

    for y in range(GRID_HEIGHT):
        for x in range(GRID_WIDTH):
            neighbors = count_neighbors(grid, x, y)
            if grid[y][x] == ALIVE:
                if neighbors in (2, 3):
                    new_grid[y][x] = ALIVE
            else:
                if neighbors == 3:
                    new_grid[y][x] = ALIVE

    return new_grid

教学重点：

• 规则直接翻译成代码

• 清晰的 if / else 逻辑

• 新旧网格分离

7. 第五步：使用 Pygame 显示网格

7.1 显示原理

• 一个细胞 → 一个矩形

• 坐标换算：

1
2

屏幕 x = 网格列 * CELL_SIZE
屏幕 y = 网格行 * CELL_SIZE

7.2 绘制函数

1
2
3
4
5
6
7
8
9
10
11
12
13

def draw_grid(screen, grid):
    screen.fill(COLOR_BG)

    for y in range(GRID_HEIGHT):
        for x in range(GRID_WIDTH):
            if grid[y][x] == ALIVE:
                rect = pygame.Rect(
                    x * CELL_SIZE,
                    y * CELL_SIZE,
                    CELL_SIZE,
                    CELL_SIZE
                )
                pygame.draw.rect(screen, COLOR_CELL, rect)

7.3 （可选）绘制网格线

1
2
3
4
5
6
7
8
9
10
11
12
13

for x in range(GRID_WIDTH):
    pygame.draw.line(
        screen, COLOR_GRID,
        (x * CELL_SIZE, 0),
        (x * CELL_SIZE, SCREEN_HEIGHT)
    )

for y in range(GRID_HEIGHT):
    pygame.draw.line(
        screen, COLOR_GRID,
        (0, y * CELL_SIZE),
        (SCREEN_WIDTH, y * CELL_SIZE)
    )

8. 第六步：主循环与键盘控制

8.1 Pygame 程序基本结构

1
2
3

pygame.init()
screen = pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT))
clock = pygame.time.Clock()

8.2 事件处理与主循环

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

grid = random_grid()
running = True

while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

        elif event.type == pygame.KEYDOWN:
            if event.key == pygame.K_SPACE:
                grid = next_generation(grid)
            elif event.key == pygame.K_r:
                grid = random_grid()
            elif event.key == pygame.K_ESCAPE:
                running = False

    draw_grid(screen, grid)
    pygame.display.flip()
    clock.tick(60)

教学重点：

• SPACE：推进一代

• R：重新初始化

• ESC：退出

9. 总结：完整程序的思想

• 二维数组 = 世界状态

• 局部规则 → 全局演化

• 显示逻辑与计算逻辑分离

• 主循环 = 事件 + 更新 + 绘制

完整程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

import pygame
import random

# ==================================================
# 1. 参数设置
# ==================================================
CELL_SIZE = 10          # 单个细胞显示的像素大小
GRID_WIDTH = 80         # 网格列数
GRID_HEIGHT = 60        # 网格行数

SCREEN_WIDTH = GRID_WIDTH * CELL_SIZE
SCREEN_HEIGHT = GRID_HEIGHT * CELL_SIZE

ALIVE = 1
DEAD = 0

# 颜色定义
COLOR_BG = (0, 0, 0)
COLOR_CELL = (255, 255, 255)
COLOR_GRID = (40, 40, 40)


# ==================================================
# 2. 网格初始化（双层 for 循环版）
# ==================================================
def random_grid():
    grid = []

    for y in range(GRID_HEIGHT):
        row = []
        for x in range(GRID_WIDTH):
            cell = random.choice([ALIVE, DEAD])
            row.append(cell)
        grid.append(row)

    return grid


# ==================================================
# 3. 邻居数量统计
# ==================================================
def count_neighbors(grid, x, y):
    count = 0

    for dy in [-1, 0, 1]:
        for dx in [-1, 0, 1]:
            # 跳过自身
            if dx == 0 and dy == 0:
                continue

            nx = x + dx
            ny = y + dy

            # 边界检查
            if 0 <= nx < GRID_WIDTH and 0 <= ny < GRID_HEIGHT:
                count += grid[ny][nx]

    return count


# ==================================================
# 4. 计算下一代
# ==================================================
def next_generation(grid):
    new_grid = []

    for y in range(GRID_HEIGHT):
        new_row = []
        for x in range(GRID_WIDTH):
            neighbors = count_neighbors(grid, x, y)

            if grid[y][x] == ALIVE:
                if neighbors == 2 or neighbors == 3:
                    new_row.append(ALIVE)
                else:
                    new_row.append(DEAD)
            else:
                if neighbors == 3:
                    new_row.append(ALIVE)
                else:
                    new_row.append(DEAD)

        new_grid.append(new_row)

    return new_grid


# ==================================================
# 5. 绘制网格
# ==================================================
def draw_grid(screen, grid):
    screen.fill(COLOR_BG)

    # 绘制细胞
    for y in range(GRID_HEIGHT):
        for x in range(GRID_WIDTH):
            if grid[y][x] == ALIVE:
                rect = pygame.Rect(
                    x * CELL_SIZE,
                    y * CELL_SIZE,
                    CELL_SIZE,
                    CELL_SIZE
                )
                pygame.draw.rect(screen, COLOR_CELL, rect)

    # 绘制网格线（教学可选）
    for x in range(GRID_WIDTH):
        pygame.draw.line(
            screen,
            COLOR_GRID,
            (x * CELL_SIZE, 0),
            (x * CELL_SIZE, SCREEN_HEIGHT)
        )

    for y in range(GRID_HEIGHT):
        pygame.draw.line(
            screen,
            COLOR_GRID,
            (0, y * CELL_SIZE),
            (SCREEN_WIDTH, y * CELL_SIZE)
        )


# ==================================================
# 6. 主程序
# ==================================================
def main():
    pygame.init()
    screen = pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT))
    pygame.display.set_caption("Conway's Game of Life (Teaching Version)")

    clock = pygame.time.Clock()

    grid = random_grid()
    running = True

    while running:
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                running = False

            elif event.type == pygame.KEYDOWN:
                if event.key == pygame.K_SPACE:
                    # 推进到下一代
                    grid = next_generation(grid)

                elif event.key == pygame.K_r:
                    # 随机重新初始化
                    grid = random_grid()

                elif event.key == pygame.K_ESCAPE:
                    running = False

        draw_grid(screen, grid)
        pygame.display.flip()
        clock.tick(60)

    pygame.quit()


# ==================================================
# 7. 程序入口
# ==================================================
if __name__ == "__main__":
    main()