Skip to content

📋 常用命令行指令

本页面汇总了 TongSim 项目开发过程中常用的命令行指令,涵盖依赖安装、代码检查、测试、文档构建等场景。建议配合 uv 工具使用,可提升运行效率和依赖一致性。


uv 常用命令

uv 是本项目的统一依赖管理与执行工具,用于替代 pippoetrypipenv 等传统工具组合。

uv sync                 # 安装默认依赖(默认组)
uv sync --all-groups   # 安装所有依赖(包括 dev/test/docsd 等)
uv sync --group docs   # 仅安装文档开发所需依赖
uv run ./examples/xxx.py       # 执行 Python 脚本

⚙️ 依赖项管理

uv add numpy                            # 将 `numpy` 添加到默认分组
uv add mkdocs --group docs              # 将 `mkdocs` 添加到 docs 分组

uv remove numpy                         # 移除 `numpy` 包

uv add tongsim-api-protocol --upgrade-package tongsim-api-protocol     # 升级 `tongsim-api-protocol` 包

依赖分组建议

注意使用 --group 明确指定依赖用途,例如:

  • docs: 文档相关依赖(如 mkdocs, material
  • test: 测试相关依赖(如 pytest, coverage
  • dev: 开发辅助工具(如 ruff, pre-commit

这样可以在协作开发中避免不必要的依赖冗余。

🔒 锁定依赖版本(手动)

如需更新 uv.lock 文件,可手动执行:

uv lock

🧪 测试命令(pytest

uv run pytest -s --grpc-ip=127.0.0.1

常用参数:

uv run pytest -s             # 允许标准输出直接显示在控制台中
uv run pytest -k keyword     # 运行匹配指定关键字的测试
uv run pytest --maxfail=3    # 最多失败 3 个后停止

✅ 代码质量检查(pre-commit

uv run pre-commit install      # 安装提交钩子(首次设置)
uv run pre-commit run --all-files  # 手动执行全部检查器

pre-commit 中已集成:

  • 空格、空行、合并冲突检测
  • JSON/YAML/TOML 配置语法校验
  • ruff 检查与格式化
  • uv-sync 检查依赖锁一致性

🧹 代码风格检查与格式化

使用 ruff

uv run ruff check .                    # 执行静态代码检查
uv run ruff check --fix                # 自动修复部分错误
uv run ruff check --select I --fix     # 修复 import 顺序
uv run ruff format                     # 格式化整个项目

使用 black(如需)

本项目默认使用 ruff format,但兼容 black

uv run black .

📚 文档构建(mkdocs

uv run mkdocs serve             # 启动本地文档开发服务
uv run mkdocs serve -a 0.0.0.0:8001  # 指定端口和监听地址
uv run mkdocs build             # 构建静态文档(输出到 public/)

文档入口配置在 mkdocs.yml,内容位于 docs/ 目录。


🚀 打包与发布(uv 构建)

uv build
uv publish --publish-url https://nexus.mybigai.ac.cn/repository/pypi-host
  • uv build 会生成 .whl.tar.gz 包至 dist/ 目录
  • uv publish 用于上传包到私有镜像(BIGAI Nexus PyPI)