OpenHarness源码研究-1-配置打包管理

BothSavage
0 阅读5分钟

OpenHarness源码研究-1-配置打包管理

前言

围绕OpenHarness中pyproject.toml配置细节展开，讲解项目打包工具的使用、uv包管理器的优势与操作方法

toml项目文件

平时Python脚本写习惯了，没有工程化概念，pyproject.toml文件为现代Python项目的核心配置文件，相当于springboot中maven文件，我认为最重要的是同一了环境依赖，和暴露了脚本

# ==============================================
# 构建系统配置：定义打包/安装需要的工具
# ==============================================
[build-system]
# 构建项目需要依赖的包：使用 hatchling 进行打包
requires = ["hatchling"]
# 构建后端：指定 hatchling 作为打包工具
build-backend = "hatchling.build"

# ==============================================
# 项目核心信息（发布到 PyPI 时展示的内容）
# ==============================================
[project]
# 项目包名（pip install 时用的名字）
name = "openharness-ai"
# 项目版本号
version = "0.1.5"
# 项目简短描述
description = "Open-source Python port of Claude Code - an AI-powered CLI coding assistant"
# 详细说明文档（README.md）
readme = "README.md"
# 开源协议
license = "MIT"
# 要求 Python 最低版本
requires-python = ">=3.10"
# 项目作者
authors = [
    { name = "novix-science" },
]

# ==============================================
# 项目运行必须依赖（安装时自动下载）
# ==============================================
dependencies = [
    "anthropic>=0.40.0",    # Anthropic AI 接口库（Claude）
    "openai>=1.0.0",        # OpenAI API 库
    "rich>=13.0.0",         # 终端美化输出
    "prompt-toolkit>=3.0.0",# 交互式命令行工具
    "textual>=0.80.0",      # 终端 UI 框架
    "typer>=0.12.0",        # 命令行参数解析
    "pydantic>=2.0.0",      # 数据验证
    "httpx>=0.27.0",        # HTTP 客户端
    "websockets>=12.0",     # WebSocket 支持
    "mcp>=1.0.0",           # 自定义工具库
    "pyperclip>=1.9.0",     # 剪贴板操作
    "pyyaml>=6.0",          # YAML 文件解析
    "questionary>=2.0.1",   # 命令行问答交互
    "watchfiles>=0.20.0",   # 文件监听
    "croniter>=2.0.0",      # 定时任务表达式解析
]

# ==============================================
# 可选依赖：开发环境才需要（测试、格式化等）
# ==============================================
[project.optional-dependencies]
# 开发依赖组：安装命令 pip install -e ".[dev]"
dev = [
    "pexpect>=4.9.0",          # 进程交互测试
    "pytest>=8.0.0",           # 单元测试框架
    "pytest-asyncio>=0.23.0",  # 异步代码测试
    "pytest-cov>=5.0.0",       # 测试覆盖率
    "ruff>=0.5.0",             # 代码格式化/检查（超快）
    "mypy>=1.10.0",            # 静态类型检查
]

# ==============================================
# 命令行工具配置：安装后可直接在终端运行
# ==============================================
[project.scripts]
# 运行命令：openharness → 指向 openharness.cli 里的 app
openharness = "openharness.cli:app"
# 简写命令：oh
oh = "openharness.cli:app"
# 另一个工具命令：ohmo
ohmo = "ohmo.cli:app"

# ==============================================
# Hatch 打包配置：打包时包含哪些源码目录
# ==============================================
[tool.hatch.build.targets.wheel]
# 打包时包含的 Python 包目录
packages = ["src/openharness", "ohmo"]

# 强制把前端文件打包进 Python 包内
[tool.hatch.build.targets.wheel.force-include]
# 前端项目文件 → 打包后放到 openharness/_frontend 目录下
"frontend/terminal/package.json" = "openharness/_frontend/package.json"
"frontend/terminal/tsconfig.json" = "openharness/_frontend/tsconfig.json"
"frontend/terminal/src" = "openharness/_frontend/src"

# ==============================================
# 测试工具 pytest 配置
# ==============================================
[tool.pytest.ini_options]
# 测试代码放在 tests 文件夹
testpaths = ["tests"]
# 自动支持异步测试模式
asyncio_mode = "auto"

# ==============================================
# 代码格式化工具 Ruff 配置
# ==============================================
[tool.ruff]
# 代码行最大长度 100 字符
line-length = 100
# 目标 Python 版本 3.11
target-version = "py311"

# ==============================================
# 类型检查工具 mypy 配置
# ==============================================
[tool.mypy]
python_version = "3.11"
# 开启严格类型检查
strict = true

# ==============================================
# uv 包管理器配置（加速下载）
# ==============================================
[tool.uv]
# 使用清华 PyPI 镜像源，国内下载更快
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

build-system制定了打包项目的方法，把你写的代码 → 变成别人可以 pip install 安装的包。

最常见的工具就 3 个：

  • hatchling（你这个项目用的，现代、简单）
  • setuptools（老项目用）
  • poetry（另一种流行工具）

打包后，就变成了一个whl包，在其他python环境就可以安装了

#打包方式pip
pip install build

#另一打包方式uv（后面章节会说到）
uv build

#安装打包后的包
pip install openharness_ai-0.1.5-py3-none-any.whl

#本地调试推荐安装源码，假如工程路径在/home/oh
#-e = --editable,表示一旦源码更新，环境里面也可以热加载
#[dev]：顺便把开发依赖也装上（测试、格式化等）
pip install -e "/home/oh[dev]"

uv包管理工具

之前环境管理大多数都用conda，要不然就是venv中直接pip install

  • uv就相当于pip+venv虚拟环境+conda，速度比conda快很多，而且特别适合与pyproject.toml共用
  • conda不仅仅是Python包管理器。它可以安装C++库、R语言、甚至是不同版本的 CUDA和LLVM。这对于大模型，机器学习研究比较重要
#安装uv（macOS / Linux）
curl -LsSf https://uv.run/install.sh | sh

#创建当前toml指定的虚拟环境，把开发依赖一起带上
uv sync --extra dev

安装完以后，此时虚拟环境就建好了，并且在toml中制定了[project.scripts]脚本，就可以直接在命令行中运行声明的脚本

#运行脚本（项目主方法）
#openharness → 指向 openharness.cli 里的 app
uv run openharness

#相当于
#-m = module，运行包 / 模块
python -m openharness.cli

#相当于
cd openharness
python cli.py

#在toml最后加上这个加速
#在此项目中加速都有用
[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

#相当于
pip install xxx -i "https://pypi.tuna.tsinghua.edu.cn/simple"

将此项目安装到系统中，把项目中定义的脚本暴露处理

#uv 会在后台创建一个独立的、隔离的虚拟环境，把这个项目装进去
#并把你在 pyproject.toml 里定义的命令（如 oh ）软链接到你的系统路径中
#通常是 /usr/local/bin 或 ~/.local/bin
#--editable / -e 支持热更新
uv tool install --editable .

#在任意地方就可以
openharness

注意uv tool install不是把代码变成二进制可执行文件，它是在你电脑的一个隐藏角落里（通常是 ~/.local/share/uv/tools/）为这个项目建了一个专属的、永久的虚拟环境，然后它会在你的系统路径里放一个脚本文件openharness。当你输入openharness时，这个脚本会瞬间启动那个专属虚拟环境里的Python来运行程序。

总结

  • pyproject.toml+hatchling+uv的组合，可快速实现Python项目的工程化
  • 脚本暴露用来写些小玩意挺不错的
  • conda不仅仅是简单的pip环境管理，还有c++和cuda等环境管理
  • 需要有工程化思维

写到最后

请添加图片描述

avatar
文章
阅读
粉丝