发布指南（Publishing Guide）
August 17, 2026 · View on GitHub
本文档说明如何把 deepseek-multi-agent-plugin 发布到 PyPI，并把构建产物
附加到 GitHub Release。发布成功后，用户可以直接
pip install deepseek-multi-agent-plugin，也可以从 GitHub Release 下载
wheel / sdist。
✅ 当前状态：v1.0.0 为当前主干版本（2026-08-17）；v0.4.8 起已发布到 PyPI。 安装：
pip install deepseek-multi-agent-plugin。 后续发布流程：推送v*tag 即自动构建、上传 PyPI 并附加 GitHub Release。 版本号规范：只需修改src/deepseek_multi_agent_plugin/__init__.py中的__version__（单一来源，pyproject.toml动态引用）。
1. 发布流程总览
仓库使用 Git tag 触发发布：打 tag 后 GitHub Actions 自动完成构建、校验与双通道分发。
| 步骤 | 操作 | 触发结果 |
|---|---|---|
| 1 | 更新版本号并提交（改 __init__.py 的 __version__，见第 4 节版本号规范） | 代码进入仓库 |
| 2 | 打标签 git tag v1.0.0 并推送 git push origin v1.0.0 | 触发 publish.yml |
| 3 | CI 构建 wheel + sdist，运行 twine check | job 1（build-and-publish） |
| 4 | 发布到 PyPI | job 1 上传 deepseek-multi-agent-plugin-X.Y.Z |
| 5 | 把 dist/*.whl、dist/*.tar.gz 附加到 GitHub Release | job 2（release-upload） |
说明：GitHub Release 仍由人工创建；
release-upload会把构建产物附加到 同名 tag 对应的 Release，若 Release 尚未创建会自动创建一个。
2. 配置 PYPI_API_TOKEN
发布 job 通过 pypa/gh-action-pypi-publish@release/v1 上传到 PyPI，使用
PyPI API token 认证。配置分为两步：
2.1 在 PyPI 官网申请 API token
-
登录 PyPI；
-
进入
Account settings→API tokens； -
点击
Add API token：Token name：建议写github-actions或deepseek-multi-agent-plugin-publish；Scope：选择Project: deepseek-multi-agent-plugin（仅限本项目）， 或Entire account；
-
点击
Add token后复制生成的 token，形如：pypi-AgEIcHlwaS5vcmcCJDEwZ...（示例占位，请勿使用）
⚠️ token 只在创建时显示一次，请立即保存到密码管理器；不要把真实 token 写入仓库、文档或提交记录。
2.2 在 GitHub 仓库配置 Secret
- 打开仓库页面，进入
Settings→Secrets and variables→Actions； - 点击
New repository secret； Name填写PYPI_API_TOKEN（必须与工作流中secrets.PYPI_API_TOKEN完全一致）；Secret粘贴 2.1 步复制的 token；- 点击
Add secret保存。
配置完成后，下次推送 v* tag 时发布流水线即可通过认证。若尚未配置，
job 1 的 Publish to PyPI 步骤会失败——这是预期行为（避免误发布），
此时请配置 Secret 后重新触发，或改用下面的本地手动发布。
3. 本地手动发布
不需要 CI 时，可以在本机完成同样的构建与上传：
# 安装构建与上传工具（若尚未安装）
python -m pip install build twine
# 1. 构建 wheel + sdist 到 dist/
python -m build
# 2. 校验产物（README 渲染、元数据、文件完整性）
twine check dist/*
# 3. 上传到 PyPI（使用 API token，用户名固定为 __token__）
twine upload dist/*
也可以显式传入凭据：
twine upload -u __token__ -p "pypi-..." dist/*
建议通过环境变量或 ~/.pypirc 保存凭据，避免 token 出现在 shell 历史中：
export TWINE_USERNAME=__token__
export TWINE_PASSWORD="pypi-..."
twine upload dist/*
注意：上传前请先确认
dist/中只有当前版本产物，旧版本残留文件 会被一起上传并触发 409 错误。
4. 版本号规范
版本号自 v1.0.0 起为单一来源，只需改一处：
| 文件 | 位置 | 说明 |
|---|---|---|
src/deepseek_multi_agent_plugin/__init__.py | __version__ | 唯一需要修改的地方 |
pyproject.toml | [tool.setuptools.dynamic] | version = { attr = "deepseek_multi_agent_plugin.__version__" }，自动引用，无需改动 |
tag 命名规则：
- 使用
vX.Y.Z格式（如v1.0.0），publish.yml由v*标签触发； - tag 应打在版本号已同步更新的提交上；
- PyPI 不允许重复上传同一版本，发布过的版本不能覆盖修改，只能发布新版本。
发布新版本的推荐顺序：
# 1. 修改 __init__.py 中的 __version__（单一来源）
# 2. 提交改动
git add src/deepseek_multi_agent_plugin/__init__.py CHANGELOG.md
git commit -m "chore: bump version to X.Y.Z"
# 3. 打 tag 并推送（触发 CI 发布）
git tag vX.Y.Z
git push origin vX.Y.Z
5. 常见问题
5.1 twine check 失败
twine check 会校验 README 渲染与包元数据，失败时输出 ERROR / WARNING：
- 检查
pyproject.toml的readme路径与格式是否正确； - README 中的 Markdown 语法需在 PyPI 上可正常渲染（PyPI 使用较严格的 CommonMark / reStructuredText 解析，注意表格、代码块等写法）；
- 修复后重新执行
python -m build，再twine check dist/*。
5.2 409 File already exists
说明该版本号已经上传过 PyPI。PyPI 不允许覆盖或删除后重传同名版本：
- 递增
__init__.py中的__version__（单一来源，如1.0.1）； - 重新打新 tag（如
v1.0.1）并推送。
本地手动发布时，先清理
dist/中的旧版本产物，避免把旧文件一起上传。
5.3 凭据失效（401 / 403）
发布步骤报 401 Invalid or non-existent authentication information 或
403 Forbidden 时：
- 到 PyPI
Account settings→API tokens检查 token 是否存在、未过期、 作用域是否包含deepseek-multi-agent-plugin； - 重新生成 token 后，到 GitHub
Settings→Secrets and variables→Actions更新PYPI_API_TOKEN； - 确认 Secret 名称与工作流中的
secrets.PYPI_API_TOKEN完全一致； - 本地发布时确认使用的是
__token__用户名 + API token，而不是 PyPI 登录密码。