你需要调用非 Python 的系统级依赖吗？
│  （如 32 位 DLL、CUDA、特定版本的 C/C++ 运行时库）
│
├── 是 → 用 conda 创建专属环境（2.4 节详解）
│         在该环境内可继续用 pip 或 uv 安装纯 Python 包
│
└── 否 → 你的项目是纯 Python + PyPI 生态？
         │
         ├── 是 → 首选 uv（速度快、功能全、现代化）
         │         备选 pip + venv（最保守、最兼容的方案）
         │
         └── 不确定 → 先用 uv，遇到 uv 搞不定的再切 pip

Prompt 示例：
"我需要用 Python 通过 TCP Socket 与一台嵌入式设备通信，设备使用自定义的二进制协议帧
（帧头 0xAA55 + 长度 + 数据 + CRC16 校验）。请推荐最合适的 Python 库，
并说明推荐理由。"

✅ 健康度评估清单：
□ 最近 6 个月内有新版本发布？
□ GitHub Star > 500？（小众领域可放宽到 > 100）
□ Issue 列表有人回复？（全是 0 评论的 Issue = 无人维护）
□ 有 README 且包含使用示例？
□ 支持你使用的 Python 版本？
□ 在 PyPI 上月下载量 > 1000？
□ 被 Awesome-Python 或其他知名项目引用？

# 官方一键安装（推荐）
irm https://astral.sh/uv/install.ps1 | iex

# 或通过 pip 安装（国内网络更稳定）
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple

# 官方一键安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或通过 pip 安装
pip install uv

uv --version
# 输出类似：uv 0.7.x (xxx 2025-xx-xx)

# 创建新项目（自动生成 pyproject.toml）
uv init serial-tool

# 进入项目目录
cd serial-tool

# 查看项目结构
# serial-tool/
# ├── pyproject.toml    ← 项目配置文件（类似 C 项目的 Makefile/CMakeLists.txt）
# ├── README.md
# └── src/
#     └── serial_tool/
#         └── __init__.py

[project]
name = "serial-tool"
version = "0.1.0"
description = "串口调试工具"
requires-python = ">=3.11"
dependencies = []

# 添加项目依赖（自动更新 pyproject.toml 和 uv.lock）
uv add pyserial        # 添加串口库
uv add numpy           # 添加数值计算库

# 添加开发依赖（测试、代码规范等工具，不会打进最终发布包）
uv add --dev pytest ruff

# 查看已安装的依赖
uv tree

[project]
name = "serial-tool"
version = "0.1.0"
description = "串口调试工具"
requires-python = ">=3.11"
dependencies = [
    "pyserial>=3.5",
    "numpy>=2.0.0",
]

[dependency-groups]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.9.0",
]

# 在项目的虚拟环境中运行 Python 脚本
uv run python main.py

# 或者运行项目入口
uv run serial-tool

# 创建虚拟环境
uv venv .venv

# 激活虚拟环境（和传统方式一样）
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# 用 uv pip 代替 pip（命令完全兼容，速度快 10~100 倍）
uv pip install pyserial numpy matplotlib
uv pip install -r requirements.txt
uv pip list
uv pip freeze > requirements.txt

# 安装完成后验证
conda --version
# 输出类似：conda 24.x.x

# 创建一个 32 位 Python 3.10 环境
# 关键参数：--platform win-32 指定 32 位 Windows
conda create -n py32 --platform win-32 python=3.10

# 激活环境
conda activate py32

# 验证位数
python -c "import struct; print(struct.calcsize('P') * 8)"
# 输出：32

# 在这个环境里安装你需要的包
conda install numpy
pip install pyserial

# ✅ 正确顺序
conda install numpy scipy matplotlib    # 先装 conda 包
pip install pyserial pymodbus           # 再装 pip 包
# 之后如果要装新包，继续用 pip，不要再切回 conda

# ❌ 错误做法
pip install numpy
conda install scipy        # scipy 可能覆盖 pip 装的 numpy，导致冲突
pip install matplotlib     # 此时 numpy 版本可能变了，matplotlib 可能崩

# 添加 conda-forge 为默认频道
conda config --add channels conda-forge
conda config --set channel_priority strict

# 之后 conda install 会优先从 conda-forge 搜索
conda install some-rare-package

# 设置为清华源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 验证配置
pip config list
# 应输出：global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

pip install pyserial -i https://pypi.tuna.tsinghua.edu.cn/simple

# uv 全局配置文件

# PyPI 源配置（加速 uv add / uv pip install）
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

# Python 解释器下载镜像（加速 uv python install）
# 如果你需要用 uv 安装 Python 版本，建议也配国内镜像
python-install-mirror = "https://cnb.cool/astral-sh/python-build-standalone/-/releases/download/"

# 在项目的 pyproject.toml 中添加
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

# Linux / macOS
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

# Windows PowerShell
$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"

# 之后正常使用 uv
uv add pyserial

channels:
  - conda-forge
  - defaults
show_channel_urls: true
default_channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2
custom_channels:
  conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud

# 添加清华 conda 频道
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge
conda config --set show_channel_urls yes

必装（5 个）：
├── Python (Microsoft)           ← Python 语言支持，含 IntelliSense
├── Pylance (Microsoft)          ← 更强的类型检查和自动补全
├── Ruff                         ← 代码格式化 + Lint 检查（本章后面详解）
├── Chinese (Simplified)         ← 中文界面
└── GitLens                      ← Git 增强（查看每行代码的修改历史）

推荐（按场景选装）：
├── Jupyter                      ← 运行 Jupyter Notebook
├── C/C++ (Microsoft)            ← 如果你也写 C 代码
├── Serial Monitor               ← 串口监控（直接在 VS Code 里看串口输出）
├── Remote - SSH                 ← 远程连接 Linux 工控机
├── GitHub Copilot               ← AI 代码补全
└── hexdump for VSCode           ← 查看二进制文件

# 1. 初始化仓库
git init

# 2. 克隆远程仓库
git clone https://github.com/your-org/serial-tool.git

# 3. 查看当前状态（最常用的命令，养成习惯经常敲）
git status

# 4. 添加文件到暂存区
git add main.py           # 添加指定文件
git add .                 # 添加所有修改

# 5. 提交（附带有意义的提交信息）
git commit -m "feat: 添加 CRC16 校验函数"

# 6. 创建并切换到新分支（开发新功能时）
git checkout -b feature/modbus-support

# 7. 切换回主分支
git checkout main

# 8. 合并分支（在 main 分支上执行）
git merge feature/modbus-support

# 9. 查看所有分支
git branch -a

# 10. 删除已合并的分支
git branch -d feature/modbus-support

# 11. 推送本地提交到远程
git push origin main

# 12. 拉取远程更新
git pull origin main

# 13. 查看远程仓库信息
git remote -v

# 14. 添加远程仓库（克隆的项目不需要这步）
git remote add origin https://github.com/your-org/project.git

# 15. 强制推送（慎用！仅在确认覆盖远程时使用）
git push --force

# 16. 查看提交历史
git log --oneline --graph

# 17. 撤销工作区的修改（还没 add 的）
git checkout -- main.py

# 18. 撤销暂存（已经 add 但没 commit 的）
git reset HEAD main.py

# 19. 回退到某个提交（保留修改在工作区）
git reset --soft HEAD~1

# 20. 查看某个文件的修改历史
git blame main.py

feat: 添加 Modbus RTU 协议解析模块       ← 新功能
fix: 修复串口粘包时 CRC 校验错误          ← 修 Bug
refactor: 重构帧解析状态机为类结构        ← 重构（不改功能）
docs: 更新 README 中的安装说明            ← 文档
test: 添加协议解析函数的单元测试          ← 测试
chore: 更新 ruff 配置规则                 ← 杂项

# 作为项目依赖安装（推荐）
uv add --dev ruff

# 或全局安装
pip install ruff

# 检查代码问题（只报告，不修改）
ruff check .

# 自动修复能修的问题
ruff check --fix .

# 格式化代码（替代 Black）
ruff format .

# 检查 + 修复 + 格式化，一键三连
ruff check --fix . && ruff format .

{
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    }
}

# 安装 Jupyter
uv add --dev jupyter

# 在项目目录下启动 Jupyter
jupyter notebook

# Cell 1：粘贴原始数据
raw_hex = "AA 55 08 00 01 02 03 04 05 06 7B 2E"
raw_bytes = bytes.fromhex(raw_hex.replace(" ", ""))
print(f"原始数据长度: {len(raw_bytes)} 字节")
print(f"帧头: 0x{raw_bytes[0]:02X}{raw_bytes[1]:02X}")
# 输出：
# 原始数据长度: 12 字节
# 帧头: 0xAA55

# Cell 2：解析帧结构（不需要重新运行 Cell 1，raw_bytes 还在内存中）
import struct

frame_header = raw_bytes[0:2]
data_length = struct.unpack("<H", raw_bytes[2:4])[0]
payload = raw_bytes[4:4+data_length]
crc = raw_bytes[4+data_length:]

print(f"数据长度字段: {data_length}")
print(f"载荷: {payload.hex(' ')}")
print(f"CRC: {crc.hex(' ')}")
# 输出：
# 数据长度字段: 8
# 载荷: 01 02 03 04 05 06 7b 2e
# CRC: （CRC 为空，说明载荷长度不对，需要检查……）

# Cell 1：从 CSV 文件读取传感器数据
import pandas as pd
df = pd.read_csv("accel_data.csv")
print(df.head())

# Cell 2：画个快速波形看看
import matplotlib.pyplot as plt

plt.figure(figsize=(12, 4))
plt.plot(df["timestamp"], df["accel_x"], label="X轴")
plt.plot(df["timestamp"], df["accel_y"], label="Y轴")
plt.plot(df["timestamp"], df["accel_z"], label="Z轴")
plt.xlabel("时间 (ms)")
plt.ylabel("加速度 (g)")
plt.legend()
plt.title("三轴加速度波形预览")
plt.grid(True)
plt.show()

# 试验不同的 struct 解析方式
import struct

data = bytes.fromhex("01 00 02 00 FF FF")

# 试试小端序
result_le = struct.unpack("<hhh", data)
print(f"小端序解析: {result_le}")   # (1, 2, -1)

# 试试大端序
result_be = struct.unpack(">hhh", data)
print(f"大端序解析: {result_be}")   # (256, 512, -257)

# 看起来是小端序！确认了设备的字节序