完整实例：将你的项目OddAgent打包发布到pypi

一、前言

为简化 OddAgent 的安装、使用流程，准备将OddAgent打成一个包，上传到pypi，这样后面只要pip install oddagent就可以直接安装使用了，方便大家利用OddAgent来实现自己的智能体。

不废话，直奔主题。

二、打包工具安装及配置

1. 安装打包和上传工具

打包和上传工具的安装，走强制升级更新模式。

pip install --upgrade setuptools wheel build twine

2. 注册 PyPI 账号

如果你还没有注册PyPI，那就先去注册一下，注册地址： https://pypi.org/account/register/
建议同时注册 TestPyPI 用于测试发布。
PyPI和TestPyPI是两套独立的环境，账号系统也是独立的，所以需要分别注册，包括后面会提到的用于上传包的API token也需要分别申请。

3. 准备项目结构

一个典型的 Python 包结构如下：

OddAgent/
├── oddagent/
│   └── my_package/
│       ├── __init__.py
│       └── module.py
├── pyproject.toml        ← 推荐使用（替代 setup.py）
├── README.md
├── LICENSE
└── tests/                （可选）

4. 编写 pyproject.toml

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "oddagent"
version = "0.1.0"
description = "A configurable Intent Recognition Agent Framework"
readme = "README.md"
license = {text = "MIT"}
authors = [
    {name = "Jacky", email = "jacky@oddmeta.com"},
]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]
requires-python = ">=3.8"
dependencies = [
    # 例如: "requests>=2.25.0",
]

[project.urls]
Homepage = "https://oddmeta.net/oddagent"
Repository = "https://github.com/oddmeta/oddagent"

5. 构建发行包

在项目根目录下运行：

python -m build

6. 配置 .pypirc

Token for "oddmeta"
Permissions: Upload packages
Scope: Entire account (all projects)

复制 token（只显示一次！你要自己保存好）

.pypirc 是一个配置文件，用于存储Python包仓库的认证信息，通常位于用户主目录下：

Windows: C:\Users\你的用户名\.pypirc
Linux/macOS: ~/.pypirc

内容如下：

# 正式仓库
[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-AgEIcHlwaS5vcmcCJDc0MzQwYW***************

# 测试仓库
[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-AgENdGVzdC5weXBpLm9yZwIkZm***************

三、发布及测试

打包好的包，建议先发布到 TestPyPI 测试一下，是否OK，如果没有问题再考虑发布到正式的PyPI，以避免污染PyPI环境。

1. 上传到 testpypi

twine upload --repository testpypi dist/*

上传好后，通过下面的命令来安装，并测试你的包。

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple oddagent

然后每个功能、接口都测试验证一下，确认没有问题了，再走下一步：上传发布到正式的PyPI。

2. 发布到正式 PyPI

twine upload dist/*

访问 https://pypi.org/project/my-package/ 查看是否成功上线。

若在上面看到已经上传成功，可以先自己安装测试一下。

四、测试流程

完整的测试及智能体配置流程请参考文档：https://www.oddmeta.net/oddagent

测试前记得先创建个新的虚拟环境来跑：

1. 创建测试用的虚拟环境

conda create -n oddagent_test python==3.12
conda activate oddagent_test

2. 在虚拟环境里安装

pip install -i https://pypi.org/simple/ oddagent

3. 在虚拟环境里测试

创建一个测试目录，如：d:\oddagent_test\xiaoluo 或者是 mkdir -p oddagent_test/xiaoluo
进入该测试目录：cd oddagent_test\xiaoluo (或者是linux下： cd oddagent_test/xiaoluo)

4. 下载项目配置样例

config.json.sample: https://oddmeta.net/tools/oddagent/config.json.sample
conference_config.json: https://oddmeta.net/tools/oddagent/conference_config.json

将这两个文件保存到本地。
然后复制一份 config.json.sample，并将其改名为 config.json

5. 修改项目配置

修改config.json:

大模型配置

  "GPT_URL": "https://qianfan.baidubce.com/v2/chat/completions",
  "MODEL": "ernie-4.5-turbo-128k",
  "API_KEY": "your api key",

智能体配置

  "TOOL_CONFIG_FILE_EXT": "_config.py",
  "TOOL_CONFIG_FILE": "agents/xiaoluo/xiaoluo_config.py", # conference_config.json的位置，或者是你自己的智能体配置的路径

6. 配置你自己的智能体

具体看这个文章： https://www.oddmeta.net/oddagent

7. 运行

oddagent -c config.json

启动成功后默认的测试界面是： http://localhost:5050

五、注意事项

确保安装了最新版本的twine：pip install --upgrade twine
上传前验证包完整性：twine check dist/*
每次发布前，更新版本号，版本号必须递增，并清理旧文件：rm -rf dist/ *.egg-info/（Windows: del /s dist\*.whl dist\*.tar.gz *.egg-info\*），然后重新运行 python -m build 和 twine upload
github支持用 GitHub Actions 自动发布，有时间可以再研究一下