create-dwy 0.14.7 → 0.15.0

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-stage-design/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: dwy-stage-design
+description: "【dwy·设计架构阶段】产品 0 到 1 的第三阶段编排。触发场景：用户说『画原型 + 定架构 / 做设计 / 出原型出架构 / 需求定了开始设计 / 设计和技术架构一起搞』，要把 PRD 同时展开成交互原型和技术架构时。可独立触发——需求已定，只想做设计架构，就触发我。"
+---
+
+## 职责（单一·编排层）
+并行调度设计架构阶段的两条原子线，不掺产出内容。设计线与架构线互不依赖，**两线并行**。
+
+## 前置校验（开工前读 state）
+- 读 `.dwy/prod/[项目]/state.json`
+- 校验上游完整：`confirmed.prd` + `confirmed.version_plan` 必须存在
+- 缺失 → 报错中断，提示先跑 dwy-stage-prd
+
+## 编排（并行两线）
+两条线无依赖，**用子 Agent 并发执行**（各自独立上下文）：
+- **dwy-prototype** — 交互原型设计
+- **dwy-architecture** — 技术架构设计
+
+两个子 Agent 只向主窗口返回成果摘要，产出落各自文件。
+
+## 准出条件（硬约束）
+- 设计与架构**均确认**：`confirmed.prototype` + `confirmed.architecture` 均写入
+- 回写 `state.json`：`current_stage = "dev"`

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-stage-dev/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: dwy-stage-dev
+description: "【dwy·TDD开发阶段】产品 0 到 1 的第四阶段编排。触发场景：用户说『开始开发 / 按 TDD 写代码 / 把 V1.0 开发出来 / 设计定了开始编码 / 多模块并发开发』，要按模块循环用 TDD 把当前版本所有模块做完时。可独立触发——设计架构已定，只想做开发，就触发我。"
+---
+
+## 职责（单一·编排层）
+调度 TDD 开发原子 skill 按模块循环，不掺产出内容。版本内互不依赖的模块**多模块并发**。
+
+## 前置校验（开工前读 state）
+- 读 `.dwy/prod/[项目]/state.json`
+- 校验上游完整：`confirmed.prototype` + `confirmed.architecture` + `confirmed.tasks` 必须存在
+- 缺失 → 报错中断，提示先跑 dwy-stage-design
+
+## 编排（按模块循环 + 并发）
+- 按 `confirmed.tasks` 的模块清单逐个调 **dwy-tdd-dev**
+- 互不依赖的模块用多个子 Agent 并发；改同一批文件时各自独立 worktree 防冲突
+- 有依赖的模块按依赖顺序串行
+
+## 准出条件（硬约束）
+- 当前版本（V1.0）**全模块测试通过**
+- `confirmed.dev_progress` 写入（记录已完成模块与测试状态）
+- 回写 `state.json`：`current_stage = "ship"`

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-stage-launch/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: dwy-stage-launch
+description: "【dwy·立项阶段】产品 0 到 1 的第一阶段编排。触发场景：用户说『走立项流程 / 做立项 / 只想先把立项做完 / 验证这个想法值不值得做 / 想法收敛+竞品+需求验证+POC+MVP 一条龙』，要把模糊想法跑过三道闸门确认值不值得立项时。可独立触发——只想做立项不进后续，就触发我。"
+---
+
+## 职责（单一·编排层）
+按序调度立项阶段的原子 skill，串起三道闸门，不掺产出内容。核心原则：**廉价验证在前、昂贵投入在后**。需求验证是总闸门，过不了不进任何后续重活。
+
+## 前置校验（开工前读 state）
+- 读 `.dwy/prod/[项目]/state.json`
+- 立项是首阶段，无上游依赖；若 `state.json` 不存在则由本阶段初始化
+
+## 编排顺序（带闸门）
+1. **dwy-ideate** — 想法收敛
+2. **dwy-competitor** — 竞品分析
+3. **dwy-validate（闸 1·总闸门）** — 需求验证。**没人要即停整个流程**，不进任何后续
+4. **dwy-poc（闸 2）** — 仅闸 1 过才做。技术可行性验证，**做不出即砍**
+5. **dwy-mvp（闸 3）** — 仅闸 2 过才做。MVP 范围裁剪，**功能 ≤ 7 个**
+
+每道闸门未过 → 立即中断本阶段，回写 state 标记停止原因，不静默跳过。
+
+## 准出条件（硬约束）
+- 三闸全过：`confirmed.validation` / `confirmed.poc` / `confirmed.mvp_features` 均写入
+- 用户明确确认立项
+- 回写 `state.json`：`current_stage = "prd"`（进入下一阶段需求版本）

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-stage-prd/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: dwy-stage-prd
+description: "【dwy·需求版本阶段】产品 0 到 1 的第二阶段编排。触发场景：用户说『写 PRD / 出需求文档 / 做需求版本规划 / 拆版本拆任务 / 立项过了开始写需求』，要把已立项的 MVP 展开成 PRD、切版本、排开发顺序时。可独立触发——立项已在别处做完，只想做需求版本，就触发我。"
+---
+
+## 职责（单一·编排层）
+按序调度需求版本阶段的原子 skill，不掺产出内容。把立项结论展开成可开发的需求与版本切分。
+
+## 前置校验（开工前读 state）
+- 读 `.dwy/prod/[项目]/state.json`
+- 校验上游完整：`confirmed.mvp_features` 必须存在（立项阶段三闸全过）
+- 缺失 → 报错中断，提示先跑 dwy-stage-launch
+
+## 编排顺序
+1. **dwy-prd** — 写产品需求文档
+2. **dwy-version** — 版本规划（V1.0 / V1.1 …路线图）
+3. **dwy-tasks** — 任务拆分 + 开发顺序
+
+## 准出条件（硬约束）
+- 用户确认 PRD + V1.0 范围 + 开发顺序
+- `confirmed.prd` / `confirmed.version_plan` / `confirmed.tasks` 均写入
+- 回写 `state.json`：`current_stage = "design"`

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-stage-ship/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: dwy-stage-ship
+description: "【dwy·上架迭代阶段】产品 0 到 1 的第五阶段编排。触发场景：用户说『验收上线 / 发版上架 / 开始迭代 / 代码写完了走验收发布 / 确定下个版本方向』，要把已开发完的版本走完验收+发布并定迭代方向时。可独立触发——开发已完成，只想做验收上线，就触发我。"
+---
+
+## 职责（单一·编排层）
+按序调度上架迭代阶段的原子 skill，不掺产出内容。验收把关 → 发布上线 → 收口迭代方向。
+
+## 前置校验（开工前读 state）
+- 读 `.dwy/prod/[项目]/state.json`
+- 校验上游完整：`confirmed.dev_progress` 必须存在（当前版本全模块测试通过）
+- 缺失 → 报错中断，提示先跑 dwy-stage-dev
+
+## 编排顺序
+1. **dwy-acceptance** — 验收（对照 PRD 与验收标准把关）
+2. **dwy-release** — 发布上线
+
+## 准出条件（硬约束）
+- 上线完成 + 用户确认下一版迭代方向
+- `confirmed.acceptance` / `confirmed.release` 均写入
+- 回写 `state.json`：当前版本标记完成；若有下一版本，`current_stage` 复位到 `prd` 进入下一轮版本编排

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-tasks/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: dwy-tasks
+description: "【dwy·任务拆解】产品 0 到 1 需求规划阶段。触发场景：用户说『拆任务 / 拆解开发任务 / 排开发计划 / 写实施计划 / tasks』，要把 V1.0 版本范围拆成可执行的开发任务清单时。"
+---
+
+## 职责（单一）
+把 V1.0 版本范围拆成可执行、可验证的开发任务清单。
+
+## 输入（从哪读）
+- state.json 的 `confirmed.version_plan`、`confirmed.prd`
+- `.dwy/prod/[项目]/02-需求规划/版本路线图.md`、`PRD.md`
+
+## 实现
+[包装型] 用全局本地 skill（位于 `~/.dwy/skills/<外部skill名>/`）：
+读其 `SKILL.md`（及同目录 scripts/、配套 .md），按它的方式与用户交互/提问，产出按下方「产出契约」落地。
+- 本 skill 依赖的外部 skill：`writing-plans`（对应 `~/.dwy/skills/writing-plans/`）
+- 若 `~/.dwy/skills/writing-plans/` 不存在：提示用户先跑 `dwy skills install`（或 `dwy claude sync` 会自动装），不要自己用内置能力顶替。
+
+## 产出契约（硬约束）
+- 落到：`.dwy/prod/[项目]/02-需求规划/开发任务拆解.md`
+- 固定章节：模块划分 / 每模块任务清单（含验证标准）/ 依赖顺序
+- 回写 state.json：`confirmed.tasks`

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-tdd-dev/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: dwy-tdd-dev
+description: "【dwy·TDD开发】产品 0 到 1 开发阶段。触发场景：用户说『开始开发 / 写代码 / TDD 开发 / 按任务开发 / 实现功能 / tdd』，要按模块循环 RED→GREEN→REFACTOR 开发并自动推进时。单元测试归此阶段。"
+---
+
+## 职责（单一）
+按模块循环 RED→GREEN→REFACTOR 开发，测试通过自动进下一模块（无人工逐模块验收）。单元测试归此阶段。
+
+## 输入（从哪读）
+- state.json 的 `confirmed.tasks`、`confirmed.architecture`、`confirmed.dev_progress`
+- `.dwy/prod/[项目]/02-需求规划/开发任务拆解.md`
+- `.dwy/prod/[项目]/03-设计与架构/技术架构.md`、`数据库设计.md`、`接口契约.md`
+
+## 实现
+[包装型] 用全局本地 skill（位于 `~/.dwy/skills/<外部skill名>/`）：
+读其 `SKILL.md`（及同目录 scripts/、配套 .md），按它的方式与用户交互/提问，产出按下方「产出契约」落地。
+- 本 skill 依赖的外部 skill：`test-driven-development`、`systematic-debugging`（各对应 `~/.dwy/skills/<名>/`）
+- 若 `~/.dwy/skills/<名>/` 不存在：提示用户先跑 `dwy skills install`（或 `dwy claude sync` 会自动装），不要自己用内置能力顶替。
+
+每模块循环：RED 写失败测试 → GREEN 最小实现通过 → REFACTOR 重构。测试通过自动进下一模块。
+
+## 产出契约（硬约束）
+- 落到：项目源码目录 + 各模块单元测试 + `.dwy/prod/[项目]/09-开发日志.md`
+- 固定章节（开发日志）：模块进度 / 关键决策 / 遇到的问题与解法
+- 回写 state.json：`confirmed.dev_progress.<module> = todo|done`（逐模块维护）

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-validate/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: dwy-validate
+description: "【dwy·需求市场验证】产品 0 到 1 总闸门（闸1）。触发场景：用户说『验证需求 / 这需求是真的吗 / 有没有市场 / 需求验证 / 市场验证 / validate』，要在投入开发前确认需求真实存在且有市场时。这是总闸门，过不了流程直接停。"
+---
+
+## 职责（单一）
+验证需求真实存在 + 有市场，给出 pass/fail 结论。**总闸门**：过不了流程直接停，不进后续。
+
+## 输入（从哪读）
+- state.json 的 `confirmed.idea`、`confirmed.competitors`
+- `.dwy/prod/[项目]/01-立项/想法收敛.md`、`竞品分析.md`
+
+## 实现
+[包装型] 用全局本地 skill（位于 `~/.dwy/skills/<外部skill名>/`）：
+读其 `SKILL.md`（及同目录 scripts/、配套 .md），按它的方式与用户交互/提问，产出按下方「产出契约」落地。
+- 本 skill 依赖的外部 skill：`market-sizing`、`sentiment-analysis`、`interview-script`（各对应 `~/.dwy/skills/<名>/`）
+- 若 `~/.dwy/skills/<名>/` 不存在：提示用户先跑 `dwy skills install`（或 `dwy claude sync` 会自动装），不要自己用内置能力顶替。
+
+验证方式三选一：
+- 搜索量/竞品热度（AI 自动）
+- 落地页测点击
+- 5 个目标用户访谈
+
+## 产出契约（硬约束）
+- 落到：`.dwy/prod/[项目]/01-立项/需求市场验证.md`
+- 固定章节：验证方式 / 证据数据 / 市场判断 / **pass/fail 结论（含理由）**
+- 回写 state.json：`confirmed.validation`（含 `pass` 布尔字段）
+- **fail 时流程必须中断，不进闸2**

package/templates/ai-tools/skills//344/272/247/345/223/2010/345/210/2601/dwy-version/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: dwy-version
+description: "【dwy·版本规划】产品 0 到 1 需求规划阶段。触发场景：用户说『版本规划 / 排版本 / 版本路线图 / V1 做啥 V2 做啥 / roadmap』，要把 PRD 需求按版本切片排路线图时。准出复查 V1.0 范围不膨胀。"
+---
+
+## 职责（单一）
+把 PRD 需求按版本切片，排出版本路线图。准出复查 V1.0 范围没膨胀。
+
+## 输入（从哪读）
+- state.json 的 `confirmed.prd`、`confirmed.mvp_features`
+- `.dwy/prod/[项目]/02-需求规划/PRD.md`
+
+## 实现
+[包装型] 用全局本地 skill（位于 `~/.dwy/skills/<外部skill名>/`）：
+读其 `SKILL.md`（及同目录 scripts/、配套 .md），按它的方式与用户交互/提问，产出按下方「产出契约」落地。
+- 本 skill 依赖的外部 skill：`outcome-roadmap`、`prioritize-features`（各对应 `~/.dwy/skills/<名>/`）
+- 若 `~/.dwy/skills/<名>/` 不存在：提示用户先跑 `dwy skills install`（或 `dwy claude sync` 会自动装），不要自己用内置能力顶替。
+
+## 产出契约（硬约束）
+- 落到：`.dwy/prod/[项目]/02-需求规划/版本路线图.md`
+- 固定章节：版本切片（V1.0/V1.x/V2.0…）/ 各版本目标 / V1.0 范围准出复查
+- **V1.0 范围超出 MVP 清单直接告警，强制收敛**
+- 回写 state.json：`confirmed.version_plan`

package/templates/ai-tools/skills//345/217/221/345/270/203/345/217/221/347/211/210/dwy-github-action-publish/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: dwy-github-action-publish
+description: "GitHub Actions 打包分发避坑指南。先判断场景，再读取对应配置。场景 1：Python 含 C 扩展 / Cython / .so 的跨平台 wheel，用 cibuildwheel 构建并通过 PyPI Trusted Publisher(OIDC) 发布。场景 2：Electron 桌面应用多平台打包分发，用 electron-builder / electron-forge 在 macOS / Windows / Linux runner 上构建并发布 GitHub Release。覆盖 workflow YAML 解析、runner image 退役、matrix 拆分、跨平台 shell 引号、artifact/release、PyPI OIDC、Electron 签名/公证/Linux 依赖/产物命名等高频坑。触发条件：编辑或新建 .github/workflows/*.yml、用户说 GitHub Actions 打包 / 跨平台打包 / cibuildwheel / wheel build / Electron 打包 / electron-builder / electron-forge / GitHub Release 分发 / runner queued / workflow build 失败。也作为 dwy-publish 发版编排的 GA 打包子能力被主动调用。"
+---
+
+# dwy-github-action-publish — GitHub Actions 打包分发避坑
+
+定位：使用 GitHub Actions 做跨平台构建、打包、发布时，先判定产物类型，再查对应配置避坑。
+
+本 skill 只处理 CI 打包分发链路。通用发版流程（测试 / bump / changelog / tag）走 `dwy-publish`；SDK 发布前安全审计走 `dwy-sdk-spec`；纯 Python 包不需要 cibuildwheel。
+
+实战来源：
+
+- Python wheel：quant-sdk 0.4.0 首发 PyPI 的 cibuildwheel 踩坑。
+- Electron：某 Electron 桌面应用多平台打包（release.yml + build.yml + pack.mjs）实战配置。
+
+---
+
+## 先判断场景
+
+先读用户目标和仓库配置，不要直接套模板。
+
+| 场景 | 判断依据 | 必读配置 |
+|---|---|---|
+| Python wheel | `pyproject.toml` 含 `Cython` / `ext_modules` / `Extension` / 产物含 `.so` / 用户提 `cibuildwheel`、`wheel`、`PyPI` | `.github/workflows/*.yml`、`pyproject.toml`、`setup.py` / `setup.cfg`、`tests/` |
+| Electron 桌面应用 | `package.json` 含 `electron` + `electron-builder` / `electron-forge`，用户提 Electron 多平台打包、GitHub Release、`dmg` / `exe` / `AppImage` | `.github/workflows/*.yml`、`package.json`、`electron-builder` 配置、`forge.config.*`、打包脚本 |
+
+如果同时存在两个场景，拆成两个 workflow 或两个 job 组分别处理。不要把 Python wheel 的 PyPI OIDC 规则套到 Electron，也不要把 Electron 的签名/产物规则套到 Python wheel。
+
+---
+
+## 通用 GitHub Actions 检查
+
+改任何 workflow 后先做这些检查。
+
+```bash
+# 1. YAML 必须能本地解析
+python3 -c "import yaml; yaml.safe_load(open('.github/workflows/release.yml'))"
+
+# 2. 检查 workflow 触发条件
+gh workflow list
+gh run list --workflow=release.yml --limit=5
+
+# 3. run 几秒 fail 且 jobs 为空，多半是 YAML 解析失败
+gh run view <run-id> --json jobs,conclusion
+```
+
+通用坑：
+
+- GitHub Action 不一定有 `v<N>` major alias。改 `uses:` 前查对应仓库 tag。
+- `run` / `env` 值里含 `:`、`=:all:`、`http://`、`${{ }}` 组合时，优先整体加引号。
+- matrix 不要默认 `fail-fast: true`。跨平台打包应设 `fail-fast: false`，保留其他平台产物和日志。
+- 不要使用退役 runner：`macos-13` / `macos-12` / `macos-11` / `ubuntu-20.04` 等会排队或失败。先查 `actions/runner-images` 当前 supported labels。
+- 长时间卡 `Waiting for a runner to pick up this job...`，优先怀疑 runner label 已退役或额度/架构不可用。
+- 发布 GitHub Release 需要 `permissions: contents: write`。
+- PyPI Trusted Publisher 需要 `permissions: id-token: write`，并绑定 workflow 和 environment。
+- artifact 名称必须包含平台和架构，避免多个 matrix 上传时互相覆盖。
+
+---
+
+## 场景 1：Python Cython wheel + PyPI OIDC
+
+适用：含 Cython 编译扩展的 Python 包、跨平台 wheel 分发（linux x86_64/aarch64 + macOS x86_64/arm64 + Windows AMD64）、GitHub Actions + cibuildwheel + PyPI Trusted Publisher OIDC 发版。
+
+模板：复制 `./references/release-workflow-template.yml` 到目标项目 `.github/workflows/release.yml`，只改：
+
+1. `package-dir: <PACKAGE_DIR>`：实际 SDK 子目录；单包仓库填 `.` 或省略。
+2. `CIBW_BUILD`：按需调整 Python 版本枚举。
+
+### Python 必查配置
+
+```bash
+rg -n "Cython|ext_modules|Extension|cibuildwheel|pypa/gh-action-pypi-publish|license|version" pyproject.toml setup.py setup.cfg .github/workflows
+```
+
+检查点：
+
+- `[build-system].requires` 含 `setuptools>=77`、`packaging>=24.2`、`wheel`、`Cython>=3.0.10`。
+- `pypa/cibuildwheel` 用 minor tag 或精确 tag，例如 `pypa/cibuildwheel@v3.4`，不要写 `@v3`。
+- monorepo 用 `with.package-dir`，测试命令使用 `{package}`，不要用 `{project}/tests`。
+- 跨平台 shell 参数用外单内双：`'pytest {package}/tests -v -k "not requires_server"'`。
+- Linux 依赖 pyarrow / pandas / numpy / scipy / lxml 时，manylinux 镜像用 `manylinux_2_28`。
+- test 阶段大依赖用 binary-only 预装：`CIBW_BEFORE_TEST: "pip install --only-binary=:all: pyarrow pandas"`。
+- macOS x86_64 用 `macos-15-intel`，不要用 `macos-13`。
+- 默认只发布 wheel。不要发布 sdist，避免 Cython 编译模块源码随 sdist 泄漏。
+
+### Python 8 个高频坑
+
+#### 坑 1：PEP 639 license expression 触发 build env 依赖冲突
+
+症状：
+
+```text
+ImportError: Cannot import `packaging.licenses`.
+Setuptools>=77.0.0 requires "packaging>=24.2" to work properly.
+```
+
+根因：`pyproject.toml` 用 `license = "MIT"` 时，setuptools 77+ 校验 license expression 依赖 `packaging>=24.2`，cibuildwheel 临时 build env 可能装到旧 packaging。
+
+修复：
+
+```toml
+[build-system]
+requires = [
+    "setuptools>=77",
+    "packaging>=24.2",
+    "wheel",
+    "Cython>=3.0.10",
+]
+build-backend = "setuptools.build_meta"
+```
+
+#### 坑 2：cibuildwheel action 必须用 minor 级或精确 tag
+
+症状：
+
+```text
+Unable to resolve action `pypa/cibuildwheel@v3`, unable to find version `v3`
+```
+
+修复：
+
+```yaml
+- uses: pypa/cibuildwheel@v3.4
+# 或
+- uses: pypa/cibuildwheel@v3.4.1
+```
+
+#### 坑 3：YAML 字符串含冒号必须加引号
+
+错误：
+
+```yaml
+CIBW_BEFORE_TEST: pip install --only-binary=:all: pyarrow
+```
+
+正确：
+
+```yaml
+CIBW_BEFORE_TEST: "pip install --only-binary=:all: pyarrow pandas"
+```
+
+#### 坑 4：CIBW_TEST_COMMAND 用 `{package}` 不要用 `{project}`
+
+```yaml
+- uses: pypa/cibuildwheel@v3.4
+  with:
+    package-dir: quant-sdk
+  env:
+    CIBW_TEST_COMMAND: 'pytest {package}/tests -v -k "not requires_server"'
+```
+
+#### 坑 5：跨平台 shell 引号必须外单内双
+
+错误：
+
+```yaml
+CIBW_TEST_COMMAND: "pytest {package}/tests -v -k 'not requires_server'"
+```
+
+正确：
+
+```yaml
+CIBW_TEST_COMMAND: 'pytest {package}/tests -v -k "not requires_server"'
+```
+
+#### 坑 6：manylinux 镜像必须升到 `_2_28`
+
+```yaml
+env:
+  CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+  CIBW_MANYLINUX_AARCH64_IMAGE: manylinux_2_28
+```
+
+#### 坑 7：测试阶段三方依赖必须强制 binary
+
+```yaml
+env:
+  CIBW_TEST_REQUIRES: pytest pytest-asyncio respx
+  CIBW_BEFORE_TEST: "pip install --only-binary=:all: pyarrow pandas"
+  CIBW_TEST_COMMAND: 'pytest {package}/tests -v -k "not requires_server"'
+```
+
+#### 坑 8：macos-13 runner 已退休
+
+```yaml
+matrix:
+  include:
+    - { os: ubuntu-latest,    archs: x86_64 }
+    - { os: ubuntu-24.04-arm, archs: aarch64 }
+    - { os: macos-15-intel,   archs: x86_64 }
+    - { os: macos-14,         archs: arm64 }
+    - { os: windows-latest,   archs: AMD64 }
+```
+
+---
+
+## 场景 2：Electron 多平台打包 + GitHub Release
+
+适用：Electron 桌面应用需要在 GitHub Actions 产出 macOS / Windows / Linux 安装包，并上传到 GitHub Release。
+
+参考配置：
+
+- `./references/electron-release-workflow-template.yml`
+
+### Electron 必查配置
+
+```bash
+rg -n "electron|electron-builder|electron-forge|pack|dist|dmg|AppImage|nsis|appx|CSC|notar|publish|artifactName|extraResources|asar|submodules" package.json .github/workflows script src -g '!node_modules'
+```
+
+检查点：
+
+- `package.json` 明确 `electron` 和打包工具版本，例如 `electron-builder`。
+- workflow 用 `actions/checkout@v4`，项目依赖 submodule 时必须 `submodules: true`。
+- Node 版本固定，例如 `actions/setup-node@v4` + `node-version: 20`。
+- 使用锁文件安装：npm 项目用 `npm ci`，pnpm 项目用 `pnpm install --frozen-lockfile`。
+- 每个平台在对应 runner 上打包，不要指望一个 Linux runner 交叉产出 macOS / Windows 完整安装包。
+- macOS x64 和 arm64 分开：x64 用 `macos-15-intel`，arm64 用 `macos-latest` / `macos-14`。
+- Linux AppImage 需要系统依赖，常见为 `icnsutils graphicsmagick xz-utils`。
+- Linux runner 上 `apt-get update` 前可移除易失效的 Microsoft / Azure apt source，避免第三方源拖死打包。
+- 未配置证书但要产出 unsigned 包时，设置 `CSC_IDENTITY_AUTO_DISCOVERY: false`，避免 electron-builder 自动找证书导致 macOS job 失败。
+- 产物命名必须包含 `${version}`、`${os}`、`${arch}`，避免 Release asset 覆盖。
+- upload-artifact 只上传最终安装包：`*.dmg`、`*.exe`、`*.AppImage`；不要上传 `win-unpacked/`。
+- GitHub Release job 需要 `permissions: contents: write`，用 `actions/download-artifact@v4` + `merge-multiple: true` 汇总产物。
+
+### Electron 推荐 workflow 形态
+
+模板：复制 `./references/electron-release-workflow-template.yml` 到目标项目 `.github/workflows/release.yml`，再按项目实际包管理器、打包脚本、签名策略调整。完整 workflow 见该模板，下方高频坑解释各关键配置的原因。
+
+### Electron 多平台高频坑
+
+#### 坑 1：macOS x64 / arm64 不能混跑
+
+macOS x64 用 `macos-15-intel`。macOS arm64 用 `macos-latest` / `macos-14`。不要用已退役的 `macos-13`。
+
+#### 坑 2：Linux 打 AppImage 缺系统依赖
+
+症状通常是图标转换、压缩、AppImage 生成失败。
+
+```yaml
+sudo apt-get install --no-install-recommends -y icnsutils graphicsmagick xz-utils
+```
+
+#### 坑 3：Ubuntu 第三方 apt 源拖死 `apt-get update`
+
+GitHub hosted runner 预置源会变化。第三方源异常时，先移除无关 source。
+
+```yaml
+sudo rm -f /etc/apt/sources.list.d/azure-cli.list /etc/apt/sources.list.d/microsoft-prod.list
+sudo apt-get update
+```
+
+#### 坑 4：未签名构建被 electron-builder 自动证书探测拖死
+
+公开 unsigned 包或暂未配置证书时：
+
+```yaml
+env:
+  CSC_IDENTITY_AUTO_DISCOVERY: false
+```
+
+如果需要签名/公证，显式配置 secrets：`CSC_LINK`、`CSC_KEY_PASSWORD`、`APPLE_ID`、`APPLE_APP_SPECIFIC_PASSWORD`、`APPLE_TEAM_ID`。不要同时依赖自动探测。
+
+#### 坑 5：产物名不含平台架构导致 Release 覆盖
+
+electron-builder 配置应使用稳定命名：
+
+```js
+artifactName: '${productName}-${version}-${os}-${arch}.${ext}'
+```
+
+#### 坑 6：只上传最终安装包
+
+推荐：
+
+```yaml
+path: |
+  release/**/*.dmg
+  release/**/*.exe
+  release/**/*.AppImage
+```
+
+需要自动更新时再上传 `*-latest.yml`。不要上传 `win-unpacked/`。
+
+#### 坑 7：外部二进制资源必须在打包前下载
+
+如果应用依赖 ADB、scrcpy server、native helper、Java/Android 构建产物，必须在 `npm run pack` 前完成下载或构建，并确保路径进入 `extraResources` / `files`。
+
+#### 坑 8：Release job 必须先汇总 artifact 再发布
+
+```yaml
+- uses: actions/download-artifact@v4
+  with:
+    path: artifacts
+    merge-multiple: true
+```
+
+发布前用 `find artifacts -type f` 打印文件列表，确认平台产物齐全。
+
+---
+
+## 安全重发流程
+
+### Python PyPI
+
+前提：PyPI 上还没有 publish 成功该版本号。PyPI 版本号一旦发布成功，永久不可复用，必须 bump 下一个版本。
+
+```bash
+gh run cancel <run-id>
+git add <修改文件>
+git commit -m "ci(sdk): 修复 xxx"
+git push origin main
+git push origin :refs/tags/v0.4.0
+git tag -d v0.4.0
+git tag v0.4.0
+git push origin v0.4.0
+gh run watch "$(gh run list --workflow=release.yml --limit=1 --json databaseId --jq '.[0].databaseId')" --exit-status
+```
+
+### Electron GitHub Release
+
+如果 GitHub Release 已创建但产物错误，优先删错 release / tag 后重打，或 bump 版本。不要在同 tag 上混入不同 commit 的产物。
+
+```bash
+gh release view v1.2.3
+gh release delete v1.2.3 --cleanup-tag
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+执行删除前必须确认用户允许，因为这会删除远端 release / tag。
+
+---
+
+## 不要做
+
+- 不要在本地跑 `python -m build && twine upload` 替代跨平台 wheel 发布。
+- 不要给 Cython 包发布 sdist，除非明确接受源码泄漏。
+- 不要假设 GitHub Action 有 major moving tag。
+- 不要跳过 workflow YAML 本地解析。
+- 不要用退役 runner label。
+- 不要让多个 matrix 上传同名 artifact。
+- 不要在 Electron 未配置签名时依赖证书自动探测。
+- 不要把 `win-unpacked/`、中间目录、缓存目录发进 Release。
+- 不要在一个 runner 上硬交叉构建所有 Electron 平台。
+
+---
+
+## 违规检测清单
+
+| 检查项 | 违规模式 | 严重程度 |
+|---|---|---|
+| YAML 解析 | env / run 含 `:` 未加引号，run 几秒 fail 且 jobs 为空 | 致命 |
+| action tag | `pypa/cibuildwheel@v3` 等不存在 alias | 致命 |
+| runner | `macos-13` / `macos-12` / `ubuntu-20.04` | 致命 |
+| artifact | matrix 上传同名产物或未带平台架构 | 高 |
+| Python build-system | PEP 639 license 但缺 `packaging>=24.2` | 致命 |
+| Python test path | monorepo 子目录用 `{project}/tests` | 高 |
+| Python shell 引号 | Windows 跨平台命令里用单引号包参数 | 高 |
+| Python manylinux | 大型 C 库依赖仍用 manylinux2014 | 高 |
+| Electron macOS | x64 / arm64 未拆 runner | 高 |
+| Electron Linux | AppImage 缺 `icnsutils graphicsmagick xz-utils` | 高 |
+| Electron 签名 | unsigned 构建未设 `CSC_IDENTITY_AUTO_DISCOVERY: false` | 中 |
+| Electron Release | 上传 unpacked 中间目录或漏最终安装包 | 高 |