pypi-doppler

使用 Doppler 发布到 PyPI（仅限本地）

自我进化技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏差或需要采用变通方案，请立即修复此文件，不要拖延。仅在遇到真实、可复现的问题时更新。

何时使用此技能

在以下情况下使用此技能：

• 从本地机器向 PyPI 发布 Python 包
• 设置 Doppler 以管理 PyPI 令牌
• 创建带有 CI 检测保护的本地发布脚本
• 发布前验证仓库所有权

工作区范围政策：仅限本地发布

此技能仅支持在本地机器上发布。

禁止事项

• 从 GitHub Actions 发布
• 从任何 CI/CD 流水线发布（GitHub Actions、GitLab CI、Jenkins、CircleCI）
• 在 semantic-release 配置中使用 publishCmd
• 在 CI 中构建包（在 prepareCmd 中使用 uv build）
• 将 PyPI 令牌存储在 GitHub 密钥中

必须遵守

• 在本地机器上使用 scripts/publish-to-pypi.sh
• 在发布脚本中添加 CI 检测保护
• 每次发布前手动批准
• 使用 Doppler 管理凭据（不使用明文令牌）
• 验证仓库（防止滥用分叉仓库）

原因

• 安全性：不在 GitHub 密钥中存储长期有效的 PyPI 令牌
• 速度：本地发布耗时 30 秒，CI 中则需 3-5 分钟
• 控制：正式发布前设有手动批准步骤
• 灵活性：通过 Doppler 集中管理凭据

参见：ADR-0027、docs/development/PUBLISHING.md

---

概述

此技能使用 Doppler 安全管理凭据，支持仅限本地的 PyPI 发布。它与工作区范围的发布工作流集成，具体如下：

1. GitHub Actions：仅自动处理版本管理（标签、发布、CHANGELOG）
2. 本地机器：使用 Doppler 凭据手动发布到 PyPI

附带脚本

脚本	用途
scripts/publish-to-pypi.sh	带有 CI 检测保护的本地 PyPI 发布

用法：复制到项目的 scripts/ 目录：

/usr/bin/env bash << 'DOPPLER_EOF'
# Resolve plugin root using cc-plugin-root helper
PLUGIN_DIR="$(cc-plugin-root itp)"
cp "$PLUGIN_DIR/skills/pypi-doppler/scripts/publish-to-pypi.sh" scripts/
chmod +x scripts/publish-to-pypi.sh
DOPPLER_EOF

---

前提条件

一次性设置

1. 安装 Doppler CLI：

   brew install dopplerhq/cli/doppler
   

2. 通过 Doppler 进行身份验证：

   doppler login
   

3. 验证对 private-config 项目的访问权限：

   doppler whoami
   doppler projects
   

设置 PyPI 令牌

1. 创建 PyPI API 令牌：

   • 访问：https://pypi.org/manage/account/token/
   • 如果尚未启用双重身份验证（2FA），请启用（自 2024 年起为必需）
   • 创建令牌并选择作用范围：“整个账户”或指定项目
   • 复制令牌（以 pypi-AgEIcHlwaS5vcmc... 开头，约 180 个字符）

2. 将令牌存储在 Doppler 中：

   doppler secrets set PYPI_TOKEN='pypi-AgEIcHlwaS5vcmc...' \
     --project private-config \
     --config prd
   

3. 验证令牌已存储：

   doppler secrets get PYPI_TOKEN \
     --project private-config \
     --config prd \
     --plain
   

---

发布工作流

必须：发布前验证版本号递增

发布前验证：向 PyPI 发布之前，请确认版本号已较上次发布递增。未递增版本号就发布是无效的，也会浪费资源。

自主检查顺序：

1. 将本地 pyproject.toml 中的版本号与 PyPI 上的最新版本进行比较
2. 如果版本号相同——停止，不要继续发布
3. 告知用户：“版本号未递增。请先运行 semantic-release，或确认提交包含 feat: 或 fix: 类型。”

完整发布工作流

步骤 1：开发与提交（Conventional Commits）：

git add .
git commit -m "feat: add new feature"  # MINOR bump
git push origin main

步骤 2：自动版本管理（GitHub Actions - 40-60 秒）：

GitHub Actions 会自动分析提交、确定下一个版本、更新 pyproject.toml/package.json、生成 CHANGELOG、创建 git 标签并创建 GitHub 发布。

此处不会发布到 PyPI（这是有意为之，参见 ADR-0027）。

步骤 3：在本地发布到 PyPI（30 秒）：

git pull origin main
./scripts/publish-to-pypi.sh

使用捆绑脚本（推荐）

/usr/bin/env bash << 'GIT_EOF'
# First time: copy script from skill to your project (resolve plugin root via cc-plugin-root)
PLUGIN_DIR="$(cc-plugin-root itp)"
cp "$PLUGIN_DIR/skills/pypi-doppler/scripts/publish-to-pypi.sh" scripts/
chmod +x scripts/publish-to-pypi.sh

# After semantic-release creates GitHub release
git pull origin main

# Publish using local copy of bundled script
./scripts/publish-to-pypi.sh
GIT_EOF

捆绑脚本功能：CI 检测防护、仓库验证、Doppler 集成、构建 + 发布 + 验证工作流、清晰的错误消息。

手动发布（高级）

如需绕过规范脚本手动发布：

/usr/bin/env bash << 'CONFIG_EOF'
# Retrieve token from Doppler
PYPI_TOKEN=$(doppler secrets get PYPI_TOKEN \
  --project private-config \
  --config prd \
  --plain)

# Build package
uv build

# Publish to PyPI
UV_PUBLISH_TOKEN="${PYPI_TOKEN}" uv publish
CONFIG_EOF

警告：手动发布会绕过 CI 检测防护和仓库验证。除非有特殊原因，否则请使用规范脚本。

---

参考文档

主题	参考文档
CI 检测	CI 检测强制措施
凭据管理	Doppler 与令牌管理
故障排查	故障排查指南
TestPyPI 测试	TestPyPI 测试
任务依赖	任务依赖

---

相关文档

• ADR-0027：docs/architecture/decisions/0027-local-only-pypi-publishing.md - 仅限本地发布的架构决策
• ADR-0028：docs/architecture/decisions/0028-skills-documentation-alignment.md - Skills 与 ADR-0027 的对齐
• PUBLISHING.md：docs/development/PUBLISHING.md - 完整的发布工作流指南
• 捆绑脚本：scripts/publish-to-pypi.sh - 带有 CI 防护的参考实现

---

验证历史

• 2025-12-03：重构为优先发现、与环境无关的方法
  • discover_uv() 按优先级检查 PATH、直接安装、版本管理器
  • 支持：curl 安装、Homebrew、cargo、mise、asdf——不强制使用任何方法
• 2025-11-22：依据 ADR-0027 创建（工作区范围内仅限本地的策略）
• 验证：已测试 CI 检测防护，已验证 Doppler 集成

---

最后更新：2025-12-03 策略：工作区范围内仅限本地的 PyPI 发布（ADR-0027） 取代：无（从一开始便遵循 ADR-0027 创建）

执行后复盘

此技能完成后，在结束前检查：

1. 命令是否成功？ — 如果没有，请修复导致失败的说明或错误表。
2. 参数或输出是否有变化？ — 如果底层工具的接口发生变化，请相应更新用法示例和参数表。
3. 是否需要变通方案？ — 如果你不得不临时处理（使用不同的标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时再次需要相同的变通方案。

仅在问题真实且可复现时才更新，不要基于猜测进行更新。