windows-python-release
当要手动发布 Python 包(codewiki-plus)到 PyPI 并建 GitHub Release 时——CI 不发布、Windows 控制台为 GBK、可能无 gh CLI、本机网络对 upload.pypi.org 的 Python TLS 握手有干扰——先核对 tag 区间与工作区未提交改动定 bump 级别,再按 8 步主干执行:同步四处版本→bump 提交(只 add 具体文件)→聚焦+ruff+全量闸门→清 dist 构建→PR 合并 main→tag merge commit 建 Release→uv publish(TLS 超时则 curl.exe 直传)→PyPI JSON API 核对
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 21
- Forks
- 4
01 前言 Front Matter
- name
- windows-python-release
- type
- Skill
- status
- stable
- metadata
- { "reason": "created from candidate materials", "source": "skill_creator", "summary": "手动发布 7 步主干 SOP + 每步避坑注解", "revisions": [ "at: \"2026-09-08T06:04:10Z\"", { "at": "2026-09-10T02:02:25Z", "reason": "按主干优先重构:原 SOP 8 步中 6 步是避坑,缺发布主流程;改为 7 步主干(每步带判定点),避坑降级为步骤注解。来源为新增的流程型笔记。", "source": "skill_creator" }, { "at": "2026-09-23T04:05:06Z", "reason": "v5.13.0 发布实操回写:①新增步骤 5「PR 合并 main」(check-runs 轮询,非 commit status);②tag 位置统一为 PR merge commit(main),废弃 v5.12.0 打在 develop bump commit 的旧做法;③步骤 7 补 TLS 握手干扰归因与 curl.exe(schannel)直传 legacy API 绕法,digest 字段名 sha256_digest;④核对端点补版本直查规避 JSON API 缓存延迟。来源:任务「发版本」v5.13.0 发布会话(2026-09-23)。", "source": "skill_creator" }, { "at": "2026-10-26T08:00:29Z", "reason": "v5.16.2/5.16.3 发布实操回写:①新增步骤 0「判定发布内容与 bump 级别」——tag 区间无新提交 ≠ 无发布内容,先查工作区未提交改动;②步骤 2 补提交纪律——只 add 具体文件、fix 与 bump 分 commit、git add -A 会扫入无关未跟踪文件;③步骤 3 闸门细化为聚焦测试→ruff(CI 同口径)→全量;④步骤 6 补 Release API target_commitish 远端自动打 tag 的做法。来源:notes/2026-10-26-发版时-tag-区间无新提交发布内容可能在未提交的工作区改动里提交只-add-具体文件.md(任务「发版本」v5.16.2/5.16.3 会话)。", "source": "skill_creator" } ], "source_refs": [ "wiki/scenarios/发布与依赖治理方法.md", "notes/2026-09-10-codewiki-手动发布完整流程同步四处版本测试build清distpublishrelease核对.md", "notes/2026-10-26-发版时-tag-区间无新提交发布内容可能在未提交的工作区改动里提交只-add-具体文件.md" ], "installed_at": "2026-10-26T11:01:51Z", "installed_to": ".codebuddy/skills/windows-python-release/", "installed_hash": "sha256:8d681945e85c6a784325343f0b5b55c172343c100ce7f69149e37cf24c11633e" }
- generated
- { "at": "2026-09-08T06:04:10Z", "by": "codewiki/5.8.0" }
- description
- 当要手动发布 Python 包(codewiki-plus)到 PyPI 并建 GitHub Release 时——CI 不发布、Windows 控制台为 GBK、可能无 gh CLI、本机网络对 upload.pypi.org 的 Python TLS 握手有干扰——先核对 tag 区间与工作区未提交改动定 bump 级别,再按 8 步主干执行:同步四处版本→bump 提交(只 add 具体文件)→聚焦+ruff+全量闸门→清 dist 构建→PR 合并 main→tag merge commit 建 Release→uv publish(TLS 超时则 curl.exe 直传)→PyPI JSON API 核对
- stale_after
- 1800748800000
03 SKILL.md 正文
工作场景
手动发布 Python 包(codewiki-plus)到 PyPI 并创建 GitHub Release。CI 只跑测试与 lint,不负责构建与发布(.github/workflows/ci.yml:13-74),因此发布主干没有脚本承载,必须按序手工执行。Windows 控制台默认 GBK,环境可能无 gh CLI。
适用条件
- 发布是手动流程,仓库无发布脚本
- 提交信息或 Release 正文含中文/emoji
- 环境无 gh CLI / 未配置 GH_TOKEN,但 git credential manager 已保存凭据
核心 SOP
按序执行 8 步,每步有判定点,不通过就停,不要带着问题往下走。
-
判定发布内容与 bump 级别:
git log <上一tag>..HEAD --oneline看提交,同时git status --short+git diff --stat核对工作区未提交改动——tag 区间无新提交 ≠ 没有发布内容,发布内容可能全在未提交的工作区里(v5.16.2 实例:log 为空但 fix 改动全在工作区)。据实际内容定 patch/minor bump。 判定点:发布内容清单明确,bump 级别有依据。 -
同步四处版本引用:
pyproject.toml(version)、codewiki/__init__.py(__version__)、uv.lock(用uv lock刷新,勿手改)、codewiki/mcp/server.py(version=__version__注入,勿手写常量)。CLI 与 actor id 也从__version__读取,自动跟随。 判定点:四处版本字符串完全一致。 -
提交 bump 并推送 develop:消息
chore: bump version to X;推origin develop。 判定点:git show确认版本改动齐全。 ⚠️ 中文提交信息用git commit -F <utf8 文件>,不要用-m(GBK 破坏,乱码或拆词)。 ⚠️ 只 add 具体文件:fix 改动与版本 bump 分两个 commit;工作区混着的 repowiki 产物等非发布文件不入库。git add -A会扫入未跟踪的.scratch/、草稿文档等无关文件(v5.16.3 实例:误暂存 157 文件 8 万行),用git add -u+ 显式路径精确暂存。 -
发布闸门(按序):聚焦测试(改动模块,秒级)→
ruff check/ruff format --check(本次变更的 py 文件,与 CI 增量 lint 同口径)→ 全量pytest -q。 判定点:无失败用例,无 lint 错误。 ⚠️ 全量ruff format --check .会报 repowiki/conversations/*.md 内嵌代码块——不在 CI Lint 范围,按 CI 同口径逐文件验证即可。 -
构建并清理产物:
uv build;发布前清dist/或只精确指定本次产物。 判定点:dist/下只剩本次版本的 wheel 与 sdist。 ⚠️ 不清dist/会连带上传旧产物(5.6.0 发布时残留 6 个)。 -
合并 main:建 PR develop→main(无 gh CLI 时用 Python
subprocess调git credential fill取凭据再调 REST API,请求体显式 UTF-8);轮询 head sha 的 check-runs(不是 commit status)等 CI 绿后合并。 判定点:PR merged,main 含 bump commit。 -
打 tag 并建 GitHub Release:lightweight tag
vX.Y.Z打在 PR merge commit 上(main 分支)——Release 应反映 main 的事实状态;不要打在 develop 的 bump commit 上(v5.12.0 旧做法,与 Release 所属分支不一致)。Release 正文经 REST API 创建,显式 UTF-8;也可用 Release API 的target_commitish让远端自动打 tag。 ⚠️ Release 正文乱码不可逆(UTF-8 被按 GBK 解码写入,字符永久丢失),只能基于git log事实重写。 ⚠️ 给git credential fill喂 stdin 不用 PowerShell 管道(stdin 常为空、引号被破坏),用subprocess精确传字节;凭据只留进程内。 -
发布到 PyPI:优先
uv publish dist/codewiki_plus-<version>*(精确指定,默认传 dist/ 全部)。 token 来源:Windows 凭据管理器(keyring)——keyring.get_password('pypi', 'upload'),首次配置:keyring.set_password('pypi', 'upload', '<token>')。不要让用户把 token 粘贴到对话里(本仓库 4 次泄露事故全部源于此),也不要写进仓库内任何文件(gitignore 不是安全边界,.codebuddy/是被跟踪目录)。 ⚠️ 本机网络对 upload.pypi.org 的 Python OpenSSL TLS 握手会被干扰:uv publish / twine / requests 全部连接超时(TCP 通、curl 秒通)。绕法:curl.exe(schannel 栈)直传 legacy API——Python 从 whl 的*.dist-info/METADATA、sdist 的PKG-INFO提取元数据构造完整表单(:action=file_upload、protocol_version=1、filetype、pyversion+ 全部元数据字段 +description正文),写 curl-K配置文件(form-string,命令行会超长),-u __token__:<token>POST。digest 字段名是sha256_digest(不是digests_sha256,400 报 missing digest)。token 经参数传进程内,用完删临时文件。 ⚠️ email.parser 提取元数据时Message.keys()对重复头返回 N 次(如 4 个Project-URL),循环内再get_all(key)会产生 N×N 重复字段(v5.13.1 时 project_urls 重复 16 条被 400 拒绝)。遍历前必须对 key 去重。 -
核对真实上传:
https://pypi.org/pypi/codewiki-plus/json查最新版本(JSON API 有缓存延迟,可直接查/pypi/codewiki-plus/<version>/json)。 判定点:API 返回版本 == 目标版本,双产物 size 正确。
判断逻辑
- 主干优先:先有完整流程,避坑是各步的注解,不是流程的替代品。缺任何一步(尤其是 3 闸门与 8 核对)都不算发布完成。
- tag 区间无新提交 ≠ 无事可发:发布内容可能全在未提交的工作区改动里,先看
git status再下结论(依据: notes/2026-10-26-发版时-tag-区间无新提交发布内容可能在未提交的工作区改动里提交只-add-具体文件.md 的「tag 区间无提交容易被误判为无事可发」)。 - 乱码/拆词/stdin 失效同源:都是 cmd/PowerShell 中间层破坏参数与编码。统一绕法是「落文件 / 精确 subprocess」,不是加转义。
- TLS 握手超时先做栈归因:TCP 通 + curl(schannel)通 + Python requests 超时 → 是 OpenSSL 栈被网络层干扰,换传输栈(curl.exe)而不是加超时重试。
- PyPI 只增不改会幂等跳过已存在文件,但这是侥幸,不是安全网。
禁忌与反模式
- 不要
git commit -m "中文" - 不要
git add -A一把梭——只 add 具体文件,fix 与 bump 分 commit - 不要不清
dist/就直接uv publish - 不要跳过闸门(步骤 3)或发布后核对(步骤 8)
- 不要用 PowerShell 管道或
cmd /c echo给git credential fill喂 stdin - 不要试图反向还原 GBK 乱码文本(字符已丢失,只能重写)
- PyPI 上传超时不要盲目加超时重试——先区分是读取慢(加超时有用)还是 TLS 握手被掐(换 curl.exe)
- 不要把 PyPI token 写进任何落盘文件后不清理
- 不要把 PyPI token 存进仓库内文件(含 gitignore 的文件)——统一走 keyring(Windows 凭据管理器)
- 不要让用户把 token 粘贴到对话里——对话采集 hook 会把它原样写进 repowiki/conversations/ 并随提交推送
依据: notes/2026-09-10-codewiki-手动发布完整流程同步四处版本测试build清distpublishrelease核对.md 的「7 步主干与每步判定点」;wiki/scenarios/发布与依赖治理方法.md 的「dist 残留被一并上传」「Release 正文乱码不可逆」「Windows 参数与 stdin 编码统一绕法」;任务「发版本」v5.13.0 发布实操(2026-09-23):TLS 握手干扰归因与 curl.exe 绕法、sha256_digest 字段名、tag 打在 merge commit 的约定;notes/2026-10-26-发版时-tag-区间无新提交发布内容可能在未提交的工作区改动里提交只-add-具体文件.md 的「tag 区间无提交先查工作区」「只 add 具体文件、fix 与 bump 分 commit」「闸门顺序聚焦→ruff→全量」
04 同仓库更多 Skills
write-doc-file-content-file-sidechannel
write_doc_file 建档报目标路径已被手写文件占用/路由冲突时——走 content_file 临时文件侧通道:正文写临时文件→删占位文件→write_doc_file(content_file=...) 正式建档→删临时文件
windows-dev-env
Windows/PowerShell 下做 git 写操作、跑子进程或批量文件/测试清理时:shell 漂移与中文路径致命令静默失败、无控制台宿主子进程闪窗、GCM 每次弹 OAuth 框、原生 DLL 被锁——须显式复核落盘、subprocess 加 CREATE_NO_WINDOW、gh auth setup-git 持久化凭据,并用 cmd /c 绕 safe-delete 钩子
repowiki-conclusion-update
已落库 repowiki 结论发生变化时,按「结论方向 vs 表述」分流:方向变则新写 decision 笔记+reject_note 旧+confirm 并回源 ADR,仅表述/证据变则 edit_doc_file 原地改
maintain-fork-pr-merge
当合入 fork 来源的 PR 且 mergeStateStatus=CONFLICTING/DIRTY 时——先 git merge-tree 探测冲突清单,查 maintainer_can_modify,再在 worktree 隔离目录解冲突后 push fork 分支,勿因 CI 绿直接 merge
git-commit-hygiene
在共享 worktree 多会话并行或暂存区有残留时提交代码——用显式 pathspec 只提交自己的文件并排除临时目录,禁止 git add -A 或裸 commit 扫入并行会话的改动
writing-shape
Writing, exploit: shape raw material into an article, paragraph by paragraph.