@chenguangyao/devflow-kit 0.1.43

package/skills/deliver/references/pr-description.md

@@ -0,0 +1,319 @@
+# deliver / pr-description
+
+PR / MR 描述的构造规则、reviewer 视角、范例、反模式。
+
+---
+
+## PR 描述的目标
+
+reviewer 要在 5 分钟内判断:
+
+1. **这个 change 在做什么?**(一句话)
+2. **为什么做?**(背景和目标)
+3. **做了什么?**(变更范围)
+4. **怎么证明做对了?**(自测证据)
+5. **上线风险?**(rollback 方案)
+6. **我该重点看哪?**(reviewer guidance)
+
+---
+
+## 自动构造的结构
+
+```markdown
+# [<slug>] <change.title>
+
+## 变更概要(从 requirement.md 抓)
+
+<background + 3-5 行 why>
+
+## 范围
+
+- [F-01] <功能名>
+- [F-02] <功能名>
+- ...
+
+## 影响
+
+- 新增 API: `/api/v1/coupons/batch-grant`
+- 新增表: `coupon_batch`
+- 修改表: `coupon_log` 加字段 `batch_id`
+- 依赖:无新增
+
+## 提测自测(从 reports/test-report.md#self-test 抓)
+
+<verbatim 粘贴 F-ID + AC 证据,不截断>
+
+## 关联文档
+
+- [需求 requirement.md](../blob/<branch>/devflow/changes/<slug>/requirement.md)
+- [设计 design.md](../blob/<branch>/devflow/changes/<slug>/design.md)
+- [计划 plan.md](../blob/<branch>/devflow/changes/<slug>/plan.md)
+- [review review.md](../blob/<branch>/devflow/changes/<slug>/review.md)
+- [verify verify.md](../blob/<branch>/devflow/changes/<slug>/verify.md)
+
+## 回滚方案(从 design.md 抓)
+
+<rollback section 原文>
+
+## reviewer 提示(手写追加)
+
+<作者对 reviewer 的引导,推荐写>
+```
+
+---
+
+## 手写部分:reviewer 提示
+
+自动部分事实陈述就行,reviewer 提示要**主观引导**:
+
+```markdown
+## reviewer 提示
+
+**优先看**:
+
+1. `CouponGrantService.java` L120-180 — 核心的批量逻辑 + 事务边界
+2. `coupon_log_add_batch_id.sql` — DDL 迁移,特别注意已有数据 backfill
+3. `reports/test-report.md#perf` — 压测 P99 在 180ms,接近 NFR 200ms 上限
+
+**可以快速过**:
+
+- `DTO` 类(自动生成 / 纯数据结构)
+- 单元测试(和实现对称,逻辑简单)
+
+**特别想听 feedback**:
+
+- 事务边界设计:为什么拆成"校验 + 核销 + 日志"三段而不是一段?(见 `design.md#事务策略`)
+- 错误消息国际化:目前只加了中文,是否要加英文?
+```
+
+---
+
+## 写得好的 PR 描述范例(L2)
+
+```markdown
+# [coupon-batch-grant] 批量发放优惠券 API
+
+## 变更概要
+
+运营侧提出:当前只能一个一个发优惠券,节日活动 1 万用户要几小时。本 change 提供批量发放 API,
+支持单批 ≤ 10000 条,整体体验目标 < 1 分钟。
+
+## 范围
+
+- [F-01] 批量发放 API /api/v1/coupons/batch-grant(3 条 AC)
+- [F-02] 批量发放查询 API(2 条 AC)
+- [F-03] 后台 UI 接入(CSV 上传)(4 条 AC)
+
+## 影响
+
+- 新增 API:
+  - POST `/api/v1/coupons/batch-grant`
+  - GET `/api/v1/coupons/batch-grant/{batchId}`
+- 新增表:`coupon_batch`(batch metadata)
+- 修改表:`coupon_log` 加字段 `batch_id`(VARCHAR(32),含索引)
+- 依赖:无新增(复用已有 riskService / couponService)
+
+## 提测自测
+
+<... 粘贴 self-test 的所有 F-ID 证据,这里省略 ...>
+
+## 关联文档
+
+- [需求 requirement.md](./devflow/changes/coupon-batch-grant/requirement.md)
+- [设计 design.md](./devflow/changes/coupon-batch-grant/design.md)
+- [review review.md](./devflow/changes/coupon-batch-grant/review.md) — 3 轮,ROUND3 pass
+- [verify verify.md](./devflow/changes/coupon-batch-grant/verify.md) — 243/243 单测,86% 覆盖,P99 180ms
+
+## 回滚方案
+
+**触发条件**:
+
+- 线上 5 分钟 P99 > 400ms
+- 5 分钟内 5xx 率 > 1%
+- 发现数据不一致(grant 了但 coupon_log 没记录)
+
+**步骤**:
+
+1. Feature flag `coupon.batch_grant.enabled=false`(立即生效,< 30s)
+2. 已发放的不撤(用户侧合法)
+3. 若发现数据不一致:跑 `scripts/reconcile-coupon-log.py --batch-id=<bid>`
+
+**影响**:
+
+- 前端上传页显示"批量发放暂不可用",引导单张发放
+- 已发放的用户不受影响
+
+**验证**:
+
+- 关闭后再跑一次 smoke(单张发放)确认仍正常
+
+## reviewer 提示
+
+优先看:
+1. `CouponBatchGrantService.java#L80-L200` — 核心拆段事务(ADR-003)
+2. `migration/V20260424__add_batch_id_to_coupon_log.sql` — 有 backfill 10W+ 历史数据
+3. `reports/test-report.md#perf` 的 P99 分布(边缘接近 NFR)
+
+特别想听 feedback:
+- 事务拆三段 vs 一段 + 补偿,我选前者是因为...(见 ADR-003)
+- batchId 用 ULID 而非 UUID,因排序需求
+
+标签:label: feature / size: L2 / area: coupon
+```
+
+---
+
+## 写得差的 PR 描述(反例)
+
+```markdown
+# fix coupon
+
+改了一下批量发优惠券,跑了测试都通过了,麻烦看一下。
+
+files:
+- CouponService.java
+- CouponMapper.java
+- coupon.sql
+```
+
+问题:
+
+- 没标题 slug
+- 没目标 / 范围
+- 没自测证据
+- 没回滚方案
+- reviewer 完全不知道要看啥
+
+deliver 会拒绝这样的内容(要求 self-test + rollback + 关联文档至少齐全)。
+
+---
+
+## 粘贴 self-test 的规则
+
+self-test 可能很长(L3 50+ AC)。deliver 会:
+
+1. **完整粘**:L1 / L2 默认完整粘贴
+2. **折叠长证据**:`<details>` 折叠每个 AC 的证据部分,reviewer 按需展开
+3. **图片保留链接**:不重复粘截图,保留 `reports/screenshots/` 的路径(相对 PR 仓库根)
+4. **跳过 skipped / partial**:明确标记 "⚠️ partial AC: ..."
+
+**不建议**把 self-test 改写成简短列表,会丢失证据价值。
+
+---
+
+## 关联文档的链接
+
+- 项目内:用仓库文件相对链接(renders in GitHub/GitLab preview)
+- 外部 wiki / JIRA:用绝对 URL
+- 链接时注意:不要带 branch 参数(如 `?ref=abc123`),除非就是想锁定某个 sha
+
+---
+
+## 回滚方案的要点
+
+从 design.md 拷贝,不要改写。如果 design.md 写得烂,修 design.md 后重 deliver(回退 tech-spec)。
+
+最小可接受回滚方案:
+
+- 触发条件(明确的指标或现象)
+- 步骤(1-N,不要"git revert")
+- 影响(用户 / 数据 / 下游)
+- 验证(回滚后如何确认恢复)
+
+---
+
+## PR 标题规范
+
+格式:`[<slug>] <一句话 title>`
+
+- slug 方括号标记,方便 filter
+- title 动宾结构(做了什么),不是 "调整" / "优化" 这种模糊词
+
+好例:
+
+- `[coupon-batch-grant] 批量发放优惠券 API(最大 10000 条)`
+- `[order-refund-rebuild] 重构退款流程,解决并发下状态不一致`
+- `[auth-jwt-upgrade] 升级 JWT 算法 HS256 → RS256`
+
+坏例:
+
+- `fix coupon bug`(什么 bug?)
+- `更新订单模块`(更新什么?)
+- `WIP`(搁置了就用 --mode=keep,别提 PR)
+
+---
+
+## 附加字段的自动补充
+
+### labels
+
+按 change 自动加:
+
+- `level: L1 / L2 / L3`
+- `type: feature / bugfix / refactor / perf / security`
+- `area: <module>`(从 Files 推断或手配)
+
+### reviewers
+
+来自 config:
+
+```json
+{
+  "delivery": {
+    "reviewers": {
+      "codeOwners": true,           // 用 CODEOWNERS 文件
+      "required": ["@tech-lead"],    // 固定要 @tech-lead
+      "default": ["@peer-1", "@peer-2"]
+    }
+  }
+}
+```
+
+deliver 合并这几种来源。也可用 `--reviewers=@alice` 覆盖。
+
+### milestone / iteration
+
+从 change 的 link 里抓(if JIRA issue has sprint)。
+
+---
+
+## 附加检查
+
+deliver 构造好 body 后,会 run:
+
+1. **长度**:PR body > 100KB 警告(某些 VCS 有限制)
+2. **链接失效**:本地 md 链接不可达 → 警告(可能是路径错)
+3. **token 扫描**:再扫一遍 body(防护层)
+4. **TODO 残留**:body 里有 `TODO` / `FIXME` → 警告(可能是模板占位没改)
+
+警告默认继续,`--strict` 下强 fail。
+
+---
+
+## PR 描述和 commit message 的关系
+
+- PR body:给 **reviewer**(一次性,PR 期间看)
+- commit message:给**将来的人**(git log 永远)
+
+PR body 可以长,commit message 要短但有营养(见 plan / task-template.md)。
+
+merge 时:
+
+- squash:使用 PR body 的第一段 + commit list
+- merge commit:commit message 含 PR URL
+- rebase:保留原 commit message
+
+deliver 不强制哪种,跟项目配。
+
+---
+
+## reviewer 反馈后的迭代
+
+收到 `Request changes` 或 comment:
+
+1. `devflow apply --task new-iteration --reason="reviewer: ..."`(不是 `--resume`,是新 iteration)
+2. 修完 commit + push(PR 自动更新)
+3. reply 每条 comment("已修,commit <sha>")
+4. 请求 re-review
+
+不要在 PR 里"辩论"很久——见 `../code-review/references/escalation-playbook.md`。

package/skills/dependency-upgrade/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: devflow-dependency-upgrade
+description: |
+  devflow-kit 依赖升级专项 skill。当用户要求升级 npm/maven/go module/pip 依赖、修漏洞、更新 lockfile、调整框架版本或依赖版本变更时触发。
+  按 patch/minor/major 和安全风险分级,执行 changelog/破坏性变更检查、lockfile 更新、最小测试和回滚说明。
+when_to_use: |
+  用户说升级依赖、修依赖漏洞、更新 package-lock/pnpm-lock/go.sum/pom.xml/requirements、Renovate/Dependabot 类任务时使用。
+---
+
+# dependency-upgrade
+
+依赖升级专项 skill。它通常是 L1/L2 的特化 apply 流,不一定需要完整 requirement/design,但必须有风险判断和验证证据,并在 verify 阶段把升级后的兼容性证据纳入 `reports/test-report.md`。
+
+## 触发条件
+
+- `package.json`、`pnpm-lock.yaml`、`package-lock.json`、`yarn.lock` 变更。
+- `go.mod`、`go.sum` 变更。
+- `pom.xml`、`build.gradle`、`gradle.lockfile` 变更。
+- `requirements.txt`、`pyproject.toml`、`poetry.lock` 变更。
+- 安全漏洞修复、框架版本升级、依赖冲突解决。
+
+## 分级
+
+| 类型 | 默认 level | 验证 |
+| --- | --- | --- |
+| patch 版本、小范围漏洞修复 | L1 | unit + smoke |
+| minor 版本、多个包联动 | L2 | unit + integration + smoke |
+| major 版本、框架升级、构建链升级 | L3 | unit + integration + regression/e2e + 回滚方案 |
+
+## 执行流程
+
+1. 识别包管理器和变更范围。
+2. 区分直接依赖和传递依赖。
+3. 查 changelog / release note / migration guide。若无法联网,说明未查到并基于 lockfile/diff 保守处理。
+4. 更新 manifest 和 lockfile,不要只改其中一个。
+5. 跑最小验证:
+   - Node:`npm test` / `npm run build` / 项目已有 lint。
+   - Go:`go test ./...`。
+   - Java:`mvn -pl <module> -am test` 或项目既有命令。
+   - Python:`pytest` 或项目既有命令。
+6. 写入 `reports/test-report.md#unit` / `#integration`。
+7. 在最终说明里写清升级列表、风险、回滚方式。
+
+## 输出要求
+
+- 变更列表:包名、旧版本、新版本、直接/传递依赖。
+- 风险:breaking change、peer dependency、运行时兼容、构建链影响。
+- 验证:实际执行命令和结果。
+- 回滚:恢复 manifest + lockfile 的方式。
+
+## 反模式
+
+- 只改 lockfile 或只改 manifest。
+- major 升级不看 breaking changes。
+- 为了让测试过,顺手改业务逻辑。
+- 漏掉 peer dependency warning。
+- 把安全漏洞修复当成普通重构,没有记录 CVE/漏洞来源。

package/skills/dependency-upgrade/references/risk-matrix.md

@@ -0,0 +1,38 @@
+# dependency upgrade risk matrix
+
+## 风险判断
+
+| 信号 | 风险 |
+| --- | --- |
+| major 版本变化 | 高 |
+| 框架、ORM、HTTP client、序列化库、构建工具升级 | 高 |
+| 安全漏洞修复但涉及鉴权/加密/网络 | 中到高 |
+| 仅 patch 且 changelog 为 bugfix | 低 |
+| lockfile 大量变化 | 中到高 |
+| peer dependency warning | 中 |
+
+## 必查文件
+
+- Node:`package.json` + lockfile。
+- Go:`go.mod` + `go.sum`。
+- Java:`pom.xml` / `build.gradle` + lock / wrapper。
+- Python:`requirements.txt` / `pyproject.toml` + lockfile。
+
+## 报告建议
+
+```markdown
+## 依赖升级说明
+
+| 包 | 旧版本 | 新版本 | 类型 | 原因 |
+| --- | --- | --- | --- | --- |
+
+## 风险
+
+- ...
+
+## 验证
+
+- `npm test`: pass
+- `npm run build`: pass
+```
+