设置

首次使用时，请阅读 setup.md 了解集成指南。该过程会创建目录 ~/numpy/，用于存储用户偏好设置与代码片段。

适用场景

当用户需要在 Python 中进行数值计算时使用。本 Agent 可处理数组操作、数学运算、线性代数及数据操作等 NumPy 相关任务。

架构

内存数据存储于 ~/numpy/ 目录中。memory-template.md 文件定义了其结构规范。

~/numpy/
├── memory.md      # 偏好设置 + 常用模式
└── snippets/      # 用户保存的代码模式

快速参考

核心规则

1. 优先向量化

切勿对数组操作使用 Python 循环。NumPy 的向量化操作比循环快 10–100 倍。

# 不佳 — 使用 Python 循环
result = []
for x in arr:
    result.append(x * 2)

# 推荐 — 向量化操作
result = arr * 2

2. 理解广播机制（Broadcasting）

广播机制允许对不同形状的数组执行运算。需掌握以下规则：

• 维度从右向左对齐
• 大小为 1 的维度可自动扩展以匹配目标维度
• 缺失的维度被视为大小为 1

# 形状为 (3,1) 的数组与 (4,) 的数组相加，广播为 (3,4)
a = np.array([[1], [2], [3]])  # (3,1)
b = np.array([10, 20, 30, 40])  # (4,)
result = a + b  # (3,4)

3. 优先使用视图（View），而非副本（Copy）

切片操作返回视图（共享同一内存）。仅在必要时显式调用 .copy()。

# 视图 — 修改 b 将影响 a
b = a[::2]

# 副本 — 独立内存
b = a[::2].copy()

4. 选用合适的数据类型（dtype）

选择能容纳数据的最小 dtype，以节省内存并提升计算速度。

# 对取值范围为 0–255 的整数
arr = np.array(data, dtype=np.uint8)

# 对无需双精度浮点精度的浮点数
arr = np.array(data, dtype=np.float32)

5. 明确轴（axis）含义

多数函数支持 axis 参数。请明确各轴所代表的方向：

• axis=0：沿行方向操作（即按列向下）
• axis=1：沿列方向操作（即按行向右）
• axis=None 或省略该参数：对展平后的数组整体操作

arr = np.array([[1, 2], [3, 4]])
np.sum(arr, axis=0)  # [4, 6] — 各列求和
np.sum(arr, axis=1)  # [3, 7] — 各行求和

6. 充分利用内置函数

NumPy 提供了针对常见操作高度优化的函数，请直接使用，避免重复造轮子。

NumPy 常见陷阱

形状不匹配

# 陷阱：混淆 (n,)、(n,1) 和 (1,n)
a = np.array([1, 2, 3])      # 形状 (3,)
b = np.array([[1, 2, 3]])    # 形状 (1,3)
c = np.array([[1], [2], [3]])  # 形状 (3,1)

# 解决方案：使用 reshape 或 newaxis
a.reshape(-1, 1)  # 转为 (3,1)
a[np.newaxis, :]  # 转为 (1,3)

静默类型转换

# 陷阱：整数数组会静默截断浮点数
arr = np.array([1, 2, 3])  # int64 类型
arr[0] = 1.9  # 实际赋值为 1，而非 1.9！

# 解决方案：预先声明 dtype
arr = np.array([1, 2, 3], dtype=np.float64)

视图 vs 副本混淆

# 陷阱：花式索引返回副本，而切片返回视图
arr = np.array([1, 2, 3, 4, 5])

# 这是视图（修改会影响原数组）
view = arr[1:4]

# 这是副本（独立于原数组）
copy = arr[[1, 2, 3]]

广播机制意外行为

# 陷阱：无法广播的形状组合
a = np.array([1, 2, 3])
b = np.array([1, 2])
a + b  # 报错 — 形状不满足广播条件

# 陷阱：意外触发广播
a = np.zeros((3, 4))
b = np.array([1, 2, 3])
a + b  # 报错 — (3,4) 与 (3,) 无法对齐
a + b.reshape(-1, 1)  # 正确 — (3,4) 与 (3,1) 可广播

就地操作（In-Place Operations）

# 陷阱：部分操作默认就地修改，另一些则返回新数组
np.sort(arr)        # 返回已排序的副本
arr.sort()          # 就地排序（修改原数组）

# 安全写法：显式表达意图
arr = np.sort(arr)  # 清晰表明创建新数组

关键模式

创建数组

np.zeros((3, 4))           # 全零数组
np.ones((3, 4))            # 全一数组
np.full((3, 4), 7)         # 全为 7 的数组
np.eye(3)                  # 单位矩阵
np.arange(0, 10, 2)        # [0, 2, 4, 6, 8]
np.linspace(0, 1, 5)       # [0, 0.25, 0.5, 0.75, 1]
np.random.rand(3, 4)       # 均匀分布 [0,1)
np.random.randn(3, 4)      # 标准正态分布

重塑与堆叠

arr.reshape(2, 6)          # 重塑为新形状（总元素数必须一致）
arr.flatten()              # 返回一维副本
arr.ravel()                # 返回一维视图
np.concatenate([a, b])     # 沿现有轴拼接
np.stack([a, b])           # 沿新轴堆叠
np.vstack([a, b])          # 垂直堆叠（沿 axis=0）
np.hstack([a, b])          # 水平堆叠（沿 axis=1）

布尔索引

arr = np.array([1, 5, 3, 8, 2])
mask = arr > 3
arr[mask]                  # [5, 8]
arr[arr > 3] = 0           # 将所有大于 3 的元素替换为 0
np.where(arr > 3, 1, 0)    # 大于 3 的位置填 1，其余填 0

线性代数

np.dot(a, b)               # 矩阵乘法
a @ b                      # 同上（Python 3.5+ 支持）
np.linalg.inv(a)           # 矩阵逆
np.linalg.det(a)           # 行列式
np.linalg.eig(a)           # 特征值与特征向量
np.linalg.solve(a, b)      # 求解线性方程组 Ax = b

安全与隐私

本地保留的数据：

• 所有计算均在本地运行
• 代码模式保存于 ~/numpy/ 目录中

本技能 不会 执行以下操作：

• 向外发送任何数据
• 访问 ~/numpy/ 目录以外的文件
• 依赖网络连接

相关技能

若用户确认，可通过 clawhub install 安装以下技能：

• data — 数据处理工作流
• math — 数学计算
• statistics — 统计分析

反馈

• 若觉得有用：clawhub star numpy
• 保持更新：clawhub sync