@chenguangyao/devflow-kit 0.1.43

package/skills/archive/references/conflict-resolution.md

@@ -0,0 +1,336 @@
+# archive / conflict-resolution
+
+合并冲突决策树、`--force` 审计、多人并发 archive 处置。
+
+---
+
+## 冲突的类型
+
+1. **Heading mismatch**:MODIFIED/REMOVED 的 target heading 在 spec 里找不到
+2. **Duplicate heading**:ADDED 的 heading 在 spec 里已存在
+3. **Missing file**:MODIFIED 的 capability 文件不存在
+4. **Concurrent conflict**:本 slug archive 时 specs 已被别的 slug 改过
+5. **Syntax error**:delta 文件格式错(marker 写错、层级不对)
+6. **Orphan reference**:spec 删除了,但其他 spec 引用它
+
+---
+
+## 冲突 1:Heading mismatch
+
+**现象**:
+
+```
+✗ conflict: delta/order-refund.md
+  MODIFIED: "退款请求处理流程"
+  → specs/order-refund.md 里没有 "退款请求处理流程" 这个 ### heading
+  closest matches:
+    - "退款请求处理" (similarity 0.87)
+    - "退款流程处理" (similarity 0.72)
+```
+
+### 决策树
+
+```
+→ 检查 delta 的 heading 和 spec 的 heading
+   ↓
+   是拼写错?(空格、标点、大小写、typo)
+     ├─ 是 → 改 delta,重跑 archive
+     └─ 否 →
+          检查 spec 最近 commit
+          ↓
+          spec heading 被别人改过?
+            ├─ 是 → 和改的人协调
+            │        - 要么按新 heading 写 delta(最快)
+            │        - 要么回滚 spec heading(如果当时没必要改)
+            │
+            └─ 否 → 可能是自己 delta 写错了 heading
+                    ↓
+                    是"这个 heading 本该是新的"(其实是 ADDED 误写成 MODIFIED)?
+                      ├─ 是 → 改 delta marker 为 ADDED,重跑
+                      └─ 否 → 深入排查,可能 design 和 spec 基线脱节
+                              → 回退 tech-spec 重新对齐
+```
+
+### 对策示例
+
+**场景 A**:spec 里是"退款请求处理",delta 写成"退款请求处理流程"(加了"流程")
+
+```bash
+# 改 delta
+sed -i 's/退款请求处理流程/退款请求处理/' devflow/changes/<slug>/delta/order-refund.md
+devflow archive
+```
+
+**场景 B**:spec heading 被别的 slug(已 archive)改成了"退款请求处理 V2"
+
+```bash
+# 和改的团队确认语义
+# 然后改本 slug 的 delta
+sed -i 's/退款请求处理/退款请求处理 V2/' devflow/changes/<slug>/delta/order-refund.md
+devflow archive
+```
+
+---
+
+## 冲突 2:Duplicate heading
+
+**现象**:
+
+```
+✗ conflict: delta/coupon-management.md
+  ADDED: "批量发放优惠券"
+  → specs/coupon-management.md 里已经有 ### 批量发放优惠券
+```
+
+### 诊断
+
+- 本 slug 的 delta 写了 ADDED,但 spec 已经有同名
+- 可能是:前一个 slug 已经加过(同一 feature 迭代);或 heading 撞了
+
+### 决策树
+
+```
+→ 是两次相同 feature?
+    ├─ 是 → delta marker 应改为 MODIFIED(第二次迭代)
+    │       重跑 archive
+    │
+    └─ 否(撞名) → 改 delta heading 让它独特
+                   (如 "批量发放优惠券" → "批量发放优惠券(高并发版)")
+                   重跑 archive
+```
+
+---
+
+## 冲突 3:Missing file
+
+**现象**:
+
+```
+✗ conflict: delta/order-newthing.md
+  MODIFIED: "..."
+  → specs/order-newthing.md 不存在
+```
+
+### 诊断
+
+- MODIFIED 只对已有 spec 生效
+- 新 capability 不该 MODIFIED,该 ADDED(整个 spec 都是新的)
+
+### 对策
+
+改 delta,所有 block 用 ADDED。或者用 RENAMED(如果是改名)。
+
+---
+
+## 冲突 4:Concurrent conflict(多人并行)
+
+**现象**:本 slug 在 feature 分支上写了 delta,基于 main 的 spec baseline。这期间另一个 slug 已 merge + archive,spec baseline 变了。
+
+### 预防
+
+- archive 前:`git pull` 最新 main 的 specs
+- 看 diff:本 slug 影响的 capability 文件有没有被动
+- 如果动了,**rebase delta**:
+  - 原 delta 基于 baseline A
+  - 现 baseline 是 A + (别人的 archive)
+  - 本 delta 可能需要调整(heading 名 / block 内容)
+
+### 处置
+
+```bash
+# 在 feature 分支上
+git fetch origin
+git diff main..HEAD -- devflow/specs/
+
+# 如果 spec 有别人改动,先看懂 → 调整本 delta
+# 然后
+devflow archive
+```
+
+### 不要做
+
+- 强制推 specs,覆盖别人的 archive(破坏历史)
+- 不看 diff 直接 --force(等于覆盖别人)
+
+---
+
+## 冲突 5:Syntax error
+
+**现象**:
+
+```
+✗ delta/coupon-management.md: syntax error at line 8
+  expected marker: `## ADDED:`, `## MODIFIED:`, `## REMOVED:`, `## RENAMED:`
+  got: `## ADDING`
+```
+
+### 对策
+
+改 delta,用正确 marker。
+
+常见:
+
+- `ADDING` / `ADDS` → `ADDED`
+- `UPDATE` → `MODIFIED`
+- `DELETE` → `REMOVED`
+- marker 层级错(写成 `### ADDED:`)
+
+---
+
+## 冲突 6:Orphan reference
+
+**现象**:本 slug 的 delta REMOVED 了 capability X,但其他 spec 文件引用 X。
+
+```
+✗ conflict: deletion of spec "coupon-temp-freeze" leaves orphan references:
+  - specs/order-settlement.md 提到 "coupon-temp-freeze"
+```
+
+### 对策
+
+- 检查其他 spec,看引用是否也该去
+- 如果是:在本 slug 的 delta 里加 MODIFIED(对其他 spec)去掉引用
+- 如果不是:说明 capability 不能删,需要重新审视
+
+---
+
+## `--force` 的使用
+
+### 何时允许
+
+仅允许下列情况:
+
+1. **ADDED 冲突但用户明确接受作为 MODIFIED**(审计)
+2. **MODIFIED 冲突但用户明确接受作为 ADDED**(heading 本就是新的,写错前缀)
+3. **Orphan reference,用户确认可接受留悬空**(极少,一般不建议)
+
+### 用法
+
+```bash
+devflow archive --force --reason="heading '批量发放' 在别的 slug 里已加,本 slug 实际是 MODIFIED,之前 delta 写错"
+```
+
+记入 state.archiveForces[]:
+
+```json
+{
+  "archiveForces": [
+    {
+      "at": "2026-04-24T21:00:00Z",
+      "file": "delta/coupon-management.md",
+      "heading": "批量发放优惠券",
+      "originalMarker": "ADDED",
+      "fallback": "MODIFIED",
+      "reason": "heading 已存在,本 slug 实际是 MODIFIED",
+      "by": "@eng-a"
+    }
+  ]
+}
+```
+
+### 不允许 --force 的场景
+
+- 跳过语法错误(去修 delta)
+- 跳过 syntax 检查 / validate
+- 覆盖别人的 archive(永远不允许)
+
+---
+
+## 复合冲突
+
+一次 archive 多个 delta 都冲突。CLI 默认**全部报告后停止**,不部分应用:
+
+```
+Conflicts found:
+  delta/a.md: heading mismatch
+  delta/b.md: duplicate heading
+  delta/c.md: syntax error
+
+Fix all conflicts and rerun.
+```
+
+一次改完所有再跑 archive,避免"半 applied 半不 applied"的中间态。
+
+---
+
+## 试运行 dry-run
+
+```bash
+devflow archive --dry-run
+```
+
+输出:
+
+```
+Would apply:
+  delta/coupon-management.md → specs/coupon-management.md
+    - MODIFIED: 优惠券发放
+    - ADDED:    批量发放优惠券
+  delta/coupon-batch-grant.md → specs/coupon-batch-grant.md (NEW)
+    - ADDED:    批量发放请求入参
+    - ADDED:    批量发放响应
+
+Would move: devflow/changes/coupon-batch-grant/ → devflow/archive/2026-04-24-coupon-batch-grant/
+
+No changes committed.
+```
+
+验证预期后再跑真实 archive。
+
+---
+
+## 回滚
+
+archive 刚做完但发现错了:
+
+```bash
+devflow archive --undo <slug>
+```
+
+- 把 archived 文件搬回 changes/
+- specs 回退(git 层面 revert 或 reset)
+- state 恢复
+
+若 archive 已 push,需手动 revert spec commits + 协调团队。
+
+---
+
+## 常见错误与修复
+
+| 错误 | 修复 |
+| --- | --- |
+| `## ADDED` 后直接接内容,没 `### heading` | 加 `### <heading>` 作为 block 头 |
+| heading 里带不可见字符(zero-width space) | 用编辑器清理;vim `%s/\%u200b//g` |
+| delta 里只写 "TBD" 或 "same as design" | 写实质内容;spec 不接受 placeholder |
+| spec 里 heading 层级用 `##` 而非 `###` | spec 统一用 `###` for requirements;修 spec 后重跑 |
+| REMOVED 后又 ADDED 同 heading | 等效于 MODIFIED,建议合并成一条 MODIFIED |
+
+---
+
+## 并发 archive 的组织规范
+
+> 团队规模 > 5 人,多 slug 并行时
+
+建议:
+
+- **一次只 archive 一个 slug**(串行化 archive,其他人等待)
+- **archive 前全量 `git pull`**
+- **archive 后立即 push**(不要本地攒)
+- **冲突时协调**:钉钉 / 飞书实时沟通,不要猜对方意图
+- **spec owner 审核**:每个 capability 有 owner,archive 需 owner +1(可放到 PR 阶段检)
+
+不建议:
+
+- 每个 slug 都自己的 spec 副本(违反单一真源)
+- 多 slug 合并成大 archive(失去 change 边界)
+- archive 阶段由机器人自动跑(spec 是需要人脑判断的)
+
+---
+
+## 永远不要做的
+
+- **吞冲突然后 force merge**:下一个 change 会因为 spec 和现实不一致踩大坑
+- **删 spec 文件改成全 ADDED**:完全破坏历史追溯
+- **archive 里的文件拿出来改**:archive 是快照,破坏等于伪造历史
+- **force push spec git 历史**:团队其他人的 local 会烂
+- **把 archive commit 塞进业务 PR**:解耦:业务 PR 合 → 稳定期 → 独立 archive PR

package/skills/archive/references/knowledge-deposit.md

@@ -0,0 +1,381 @@
+# archive / knowledge-deposit
+
+经验沉淀分类规则、写入格式、provider 与同步。
+
+---
+
+## 为什么要 deposit
+
+每次 change 结束后,除了 spec(系统做什么)还有**知识**(做事过程中学到什么):
+
+- 某个 SDK 的坑
+- 某个架构决策的 trade-off
+- 一个生产故障的教训
+- 一个业务概念的精准定义
+
+这些如果不沉淀,下个人再踩一次。
+
+`devflow knowledge deposit` 把 workspace `knowledge/`、design decisions、incidents 分类写入知识沉淀目录,必要时同步到外部 KB(Wiki / Confluence / WeKnora)。
+
+**默认写入目标：**
+
+```
+~/.devflow/workspace/changes/<feature-xx>/knowledge/
+```
+
+即使是单服务需求，也默认写到当前需求 workspace。服务仓的 `devflow/knowledge/` 仅作为历史兼容，不作为新流程的默认目标。
+
+**knowledge 只写 workspace 当前需求目录**，不要分散写入每个服务仓，避免同一决策被重复沉淀、分类不一致。
+
+---
+
+## 知识沉淀目录结构
+
+```
+~/.devflow/workspace/changes/member-upgrade/
+└── knowledge/
+    ├── 领域概念/          ← 业务概念(优惠券、订单、发放批次的定义)
+    ├── 业务规则/          ← 业务规则(不可用券规则、失效策略、上限)
+    ├── 业务场景/          ← 业务场景(大促发券、断签登录、黑名单拉新)
+    ├── 接口契约/          ← 关键 API/event 契约摘要
+    ├── 架构决策/          ← 架构决策记录(ADR)
+    ├── 服务说明/          ← 服务职责(coupon-service、order-service 的边界)
+    ├── 运行手册/          ← 运维 runbook(批量发券故障如何处置)
+    ├── 事故复盘/          ← 事故复盘
+    ├── 环境说明/          ← 环境差异说明(staging vs prod 注意点)
+    └── 解决方案/          ← 具体解决方案模式(批量任务幂等、分段事务)
+```
+
+历史 in-repo 模式若仍需使用，使用相同的中文分类目录，只是根路径为 `<repo>/devflow/knowledge/`；新需求不推荐。
+
+---
+
+## 分类规则
+
+### deposit 时 CLI 的分类来源
+
+新流程不再使用顶层 `learnings.md`。可复用经验直接写入 workspace `knowledge/<中文分类>/`，CLI 按目录和关键信号确认分类:
+
+| 信号 | 默认分类 |
+| --- | --- |
+| `knowledge/业务场景/` | 业务场景 |
+| `knowledge/领域概念/` | 领域概念 |
+| `knowledge/业务规则/` | 业务规则 |
+| design.md 的 ADR | 架构决策 |
+| 新 API / event | 接口契约(简化摘要) |
+| 新服务边界 | 服务说明 |
+| incident / 事故 | 事故复盘 |
+| 运维步骤 | 运行手册 |
+| 配置 / 环境差异 | 环境说明 |
+| 通用技术解决方案(幂等、限流、分段事务) | 解决方案 |
+
+**最终分类由 human 确认**,不要闭眼接受 AI 建议。
+
+---
+
+## 写入格式
+
+### 领域概念/<name>.md
+
+```markdown
+---
+kind: concept
+name: 优惠券批次
+related:
+  - 领域概念/优惠券.md
+  - 服务说明/coupon-service.md
+introducedIn: 2026-04-24-coupon-batch-grant
+---
+
+# 优惠券批次
+
+## 定义
+
+一次批量发放操作的逻辑分组,由 batchId 唯一标识。
+
+属性:
+- batchId: ULID(26 字符)
+- activityId: 关联活动
+- requester: 发放方
+- totalCount / grantedCount / failedCount
+- createdAt
+
+## 为什么有这个概念
+
+<...引入背景...>
+
+## 相关能力
+
+- 批量发放 → `specs/coupon-management.md#批量发放优惠券`
+- 批次查询 → `specs/coupon-management.md#批次查询`
+
+## 边界
+
+- 最多 10000 条 / 批
+- 批次永久保留(无过期)
+- 批次 != 活动(一个活动可有多个批次)
+```
+
+### 架构决策/<name>.md(ADR)
+
+```markdown
+---
+kind: adr
+name: coupon-batch-grant-transaction-strategy
+status: accepted
+date: 2026-04-24
+deciders: [@arch-b, @eng-a]
+slug: coupon-batch-grant
+---
+
+# 批量发放事务策略:拆分三段而非大事务
+
+## Context
+
+批量发放 ≤ 10000 条,单大事务会:
+- 持锁 10s+,阻塞其他请求
+- 失败一条全回滚,牺牲可用性
+- DB 压力大
+
+## Decision
+
+拆成 3 段(校验、核销、日志),每段独立短事务。跨段用 batchId + 状态机保证一致性。
+
+## Alternatives considered
+
+1. 单大事务(rejected:可用性 / 性能)
+2. 异步全部走消息队列(rejected:业务要求同步返回结果)
+3. Saga + 补偿(rejected:补偿逻辑复杂,超出本迭代)
+
+## Consequences
+
+- ✅ P99 < 200ms(单条粒度)
+- ✅ 允许部分成功部分失败
+- ⚠️ 并发场景 batchId 冲突需幂等性保证
+- ⚠️ 如核销阶段挂,已校验通过的需要 reconcile
+
+## Follow-ups
+
+- 监控:batch-grant 的 partial-failure rate 超 5% 告警
+- Runbook:reconcile 脚本(运行手册/reconcile-coupon-log.md)
+```
+
+### 事故复盘/<date>-<short>.md
+
+```markdown
+---
+kind: incident
+severity: P1
+date: 2026-04-24
+duration_min: 35
+slug: coupon-batch-grant (contributing)
+---
+
+# 2026-04-24 大促夜批量发券卡单
+
+## 时间线
+
+- 20:00 大促开始
+- 20:05 批量发放 QPS 飙升至 8000
+- 20:10 DB 连接池耗尽,5xx 上升
+- 20:15 触发 alert
+- 20:25 确认是连接池配置,扩容 10 → 50
+- 20:35 恢复
+
+## 根因
+
+连接池默认 10,批量发放需要 3 连接 / 请求(3 段事务),8000 QPS 瞬间压满。
+
+## 临时处置
+
+连接池扩 50。
+
+## 长期改进
+
+- 调优连接池配置(已加到 服务说明/coupon-service.md)
+- 事务段数审视(ADR-003 追加 consequence)
+- runbook: 批量发券压力测试必须 5000+ QPS
+
+## 教训
+
+- 新 API 上线前,生产环境连接池配置要审(不能套默认)
+- 压测要覆盖峰值的 2x
+```
+
+### 解决方案/<pattern>.md
+
+```markdown
+---
+kind: solution-pattern
+name: 分段事务 + 幂等键
+applicability:
+  - 批量操作 > 1000 条
+  - 业务允许部分失败
+  - 对 P99 敏感
+---
+
+# 分段事务 + 幂等键
+
+## 问题
+
+批量操作 N 条,要求:
+- P99 低
+- 允许部分失败不全 rollback
+- 重试安全
+
+## 方案骨架
+
+1. 预处理阶段:校验每条,记入 staging(无事务或短事务)
+2. 执行阶段:每条独立事务,失败记失败原因
+3. 后处理阶段:汇总结果,必要时 reconcile
+
+幂等:所有请求带 batchId(客户端生成或服务生成);重复 batchId 返回原结果。
+
+## 实现要点
+
+- batchId 用 ULID(有序 + 随机,利于分片)
+- staging 表 retention 24h(reconcile 窗口)
+- 监控 partial-failure rate(健康度指标)
+
+## 相关案例
+
+- coupon-batch-grant(2026-04-24):本模式第一次应用
+- 未来可复用:批量消息推送 / 批量订单导出 / ...
+
+## 反模式
+
+- 不要把校验也放业务事务(浪费事务资源)
+- 不要用 AUTO_INCREMENT 做 batchId(分布式扩展难)
+```
+
+---
+
+## 关联写入(cross-link)
+
+每条 knowledge 文件 frontmatter 有 `related: [...]` 列出相关文件,用相对路径:
+
+```yaml
+related:
+  - 领域概念/优惠券.md
+  - 架构决策/coupon-batch-grant-transaction-strategy.md
+  - 事故复盘/2026-04-24-batch-grant-db-saturation.md
+```
+
+`devflow knowledge query` / `devflow knowledge graph` 用这些 link 做知识图谱。
+
+---
+
+## provider 同步
+
+### local(默认)
+
+```jsonc
+{ "kb": { "local": { "driver": "kb-local" } } }
+```
+
+什么都不做,只写 git。靠 git log 和 IDE 搜索使用。
+
+### weknora / wiki / confluence
+
+```jsonc
+{
+  "kb": {
+    "weknora": {
+      "driver": "kb-weknora",
+      "config": {
+        "endpoint": "https://weknora.example.com",
+        "apiKey": "$WEKNORA_KEY",
+        "kbId": "<kb-id>"
+      }
+    }
+  }
+}
+```
+
+`devflow knowledge sync` 或 archive 的 hook 触发,将本地 `knowledge/*.md` push 到远端。
+
+`.meta.json` 跟踪每个文件的:
+
+- sha256(变了才 sync)
+- remoteId(远端 doc id)
+- lastSyncedAt
+
+### 双向同步
+
+暂不支持"远端改回写本地"(有冲突风险)。远端只读,本地是真源。
+
+---
+
+## 去重与合并
+
+deposit 检测相似:
+
+- 同名 concept 已存在 → 提示合并(人工判断:更新原文 or 追加)
+- 类似 ADR 已存在(关键词相似) → 提示,可能上次已做过类似决策
+- 同类 incident(pattern 相似) → 提示是否串在一起
+
+AI 建议 + human 决策。不自动合并。
+
+---
+
+## 什么不该 deposit
+
+- 具体代码(代码看 git)
+- 敏感配置(secret / token)
+- 机密业务(定价算法细节、风控规则细节)
+- 临时信息(debug 数据、一次性 workaround)
+
+如果发现 `knowledge/` 条目含敏感信息,deposit 前手动净化。
+
+---
+
+## deposit 的时机
+
+1. **immediately after archive**:推荐,记忆新鲜
+2. **批量 weekly deposit**:不推荐(记忆衰退,分类错误率高)
+3. **等 incident 发生再写 runbook**:晚了,架构刚 archive 时就该写
+
+---
+
+## 质量门槛
+
+> 一篇 knowledge 文件合格的要求
+
+- ✅ 单一主题(一篇一个 concept / decision / incident)
+- ✅ 上下文完整(读者不需要额外 context 就能理解)
+- ✅ 有"为什么",不只是"是什么"
+- ✅ 有 related 链接(不是孤立)
+- ✅ 有 owner / slug 追溯
+- ✅ 保留失败的 alternatives(对 ADR 尤其重要)
+
+不合格的例子:
+
+- "批量发放很重要" ← 没内容
+- "batchId 用 ULID"(只有一行) ← 没 context
+- "按 design.md 走"(引用代替内容) ← 不 deposit,让人去看 design
+
+---
+
+## `devflow knowledge query` 的使用
+
+```bash
+devflow knowledge query "批量发放事务"
+devflow knowledge query --tag=adr --recent=30d
+devflow knowledge query --related=coupon-batch-grant
+```
+
+返回本地匹配文件(和可选的远端 KB 结果)。用于:
+
+- 新 change 的 requirement-analysis 阶段找背景
+- tech-spec 阶段找 related ADR
+- incident 时快速定位 runbook
+
+---
+
+## 最反模式
+
+- **同时维护 learnings.md 和 knowledge/解决方案/**:同一经验两份副本,必然漂移;只保留 knowledge/
+- **分类粒度乱**:有的分到领域概念,有的分到架构决策,无规则 → 查不到
+- **only happy path ADR**:只记"选 A",不记"为什么不选 B/C" → 后人会重复选 B 然后碰同样的坑
+- **knowledge 写成小说**:3000 字的 concept 文件 → 没人看
+- **不 deposit**:觉得"没什么可写" → 一般是没有把可复用经验写进 `knowledge/`