@chenguangyao/devflow-kit 0.1.43

package/docs/migration-from-arb.md

@@ -0,0 +1,232 @@
+# 从 arb-workflow-kit 迁移到 devflow-kit
+
+> 适用范围:已经在用 `arb-workflow-kit`(及其配套 `arb-knowledge` / `qs-bridge`)的项目,想平滑切到 `devflow-kit`。
+> 目标:**保留全部历史 change / 知识资产**,工作流体验向前兼容,内网集成以可插拔 provider 形式延续。
+
+## TL;DR
+
+```bash
+# 1. 装 devflow-kit
+npm i -g devflow-kit
+
+# 2. 在仓库根目录跑迁移向导(只读 dry-run,不改任何文件)
+devflow migrate from-arb --dry-run
+
+# 3. 满意后真正迁移
+devflow migrate from-arb
+
+# 4. 迁移知识库布局(arb-7 → improved-9)
+devflow knowledge migrate --from=arb-7 --to=improved-9
+
+# 5. 装回内网集成(用 qs-bridge 适配器,而不是直接依赖)
+devflow provider add intake.qs-bridge
+devflow provider add issue.qs-bridge
+devflow provider add ci.qs-bridge
+
+# 6. 健康检查
+devflow doctor
+```
+
+## 1. 概念对照
+
+| arb-workflow-kit | devflow-kit | 说明 |
+|------------------|-------------|------|
+| `dev-workflow` SKILL(1 个总编排器 + 16 个子技能) | `devflow` CLI(核心/扩展 SKILL.md + state.json 状态机) | 编排从"AI 指令"下沉到"CLI + 状态文件" |
+| `.dev-workflow/<task>/`         | `devflow/changes/<slug>/`           | "task" → "change",更接近 OpenSpec 模型 |
+| `state.yaml`                    | `state.json`(JSON Schema 校验) | 同义,JSON 便于工具消费 |
+| `00-brainstorm.md ~ 09-archive.md` 编号文件 | `proposal.md / requirement.md / design.md / plan.md / review.md / verify.md / learnings.md`(无编号,语义命名) | 减少机械感,新增 OpenSpec 风格 `delta/` 目录 |
+| `level: L1/L2/L3` 在 state.yaml | `state.json.level` + `state.json.enabled` | 文档懒生成:L1 只生成 6 个核心,L2/L3 按 `enabled` 扩 |
+| `arb-knowledge`(7 大类目)       | `devflow/knowledge/`(改良 4 域 9 类) | 见 §3 详细映射,有自动迁移命令 |
+| `qs-bridge` 直接依赖             | `devflow/providers.json` 中的 `intake.qs-bridge / issue.qs-bridge / ...` 适配器 | 内网工具变可选 provider |
+| `MR-bot` 自动评论                | `devflow deliver --pr` + 任意 vcs provider | 不锁死 GitLab |
+| `arb-knowledge-cli`(批同步)     | `devflow knowledge sync`(sha256 增量,多 driver)| 多了 sha 增量与多源 |
+
+## 2. 目录映射
+
+### change folder
+
+```
+.dev-workflow/                     →  devflow/
+└── 2025-q4-add-coupon/            →  ├── changes/coupon-grant-api/
+    ├── state.yaml                 →  │   ├── state.json
+    ├── 00-brainstorm.md           →  │   ├── proposal.md          ← 内容直接搬
+    ├── 01-requirement.md          →  │   ├── requirement.md
+    ├── 02-tech-spec.md            →  │   ├── design.md            ← 改名
+    ├── 03-test-spec.md            →  │   ├── tests.md             ← 改名
+    ├── 04-plan.md                 →  │   ├── plan.md
+    ├── 05-apply.md                →  │   ├── (合并入 plan/state)  ← 不再独立
+    ├── 06-review.md               →  │   ├── review.md
+    ├── 07-verify.md               →  │   ├── verify.md
+    ├── 08-deliver.md              →  │   ├── (合并入 state.phases.deliver)
+    ├── 09-archive.md              →  │   ├── (合并入 state.phases.archive)
+    ├── learnings.md               →  │   ├── learnings.md
+    └── refs/                      →  │   └── refs/
+                                       ├── archive/                 ← 已交付的整个 change folder 移到这里
+                                       ├── specs/                   ← 新概念:稳定能力描述
+                                       └── knowledge/               ← 见 §3
+```
+
+`devflow migrate from-arb` 自动:
+1. 重命名编号文件 → 语义文件(`02-tech-spec.md` → `design.md`)
+2. 把 `state.yaml` 转成 `state.json`,推断 phase
+3. 创建空的 `delta/` 占位(已归档的 change 不强制补 delta,但会在 README 提示)
+4. 在 `state.json.migrated_from` 写入原路径,便于追溯
+
+### 知识库
+
+| arb-knowledge(7 类) | devflow improved-9 | 说明 |
+|----------------------|--------------------|------|
+| `1-业务概念/`        | `1-domain/concepts/`     | 名词、术语 |
+| `2-业务规则/`        | `1-domain/rules/`        | 决策表、合规规则 |
+| `3-业务流程/`        | `1-domain/scenarios/`    | 场景、用户故事 |
+| `4-接口/`            | `2-system/contracts/`    | API、Kafka events、protobuf |
+| `5-技术决策/`        | `2-system/decisions/`    | ADR、架构决策 |
+| `6-排查记录/`        | `3-ops/incidents/`       | 故障复盘 |
+| `7-其他/`            | `4-archive/solutions/`   | 兜底,等待二次梳理 |
+| (新增) | `2-system/services/`     | 模块概述 — arb 缺失 |
+| (新增) | `3-ops/runbooks/`        | SOP/排查手册 — arb 缺失 |
+| (新增) | `3-ops/environments/`    | 环境/基础设施 — arb 缺失 |
+
+执行:`devflow knowledge migrate --from=arb-7 --to=improved-9`
+- 按上表逐目录 `mv`,冲突文件保留不覆盖
+- 自动清理空目录
+- 写 `devflow/knowledge/.migration.log`(JSON 报告)
+- 不会触碰 `.meta.json` 中已有的 `external` 字段(WeKnora 的 uuid 关联保留)
+
+### qs-bridge → provider
+
+```
+原直接调用:
+  $ qs-bridge wiki get https://<your-wiki-host>/x/abc
+
+devflow 抽象:
+  $ devflow ingest https://<your-wiki-host>/x/abc
+  ↑ 路由到 providers.json 里的 intake.qs-bridge,内部仍调 `qs-bridge wiki get`
+```
+
+`devflow/providers.json` 示例:
+
+```json
+{
+  "intake.qs-bridge": {
+    "type": "intake",
+    "driver": "qs-bridge",
+    "config": {
+      "binPath": "/usr/local/bin/qs-bridge",
+      "timeoutMs": 30000
+    }
+  },
+  "issue.qs-bridge": {
+    "type": "issue",
+    "driver": "qs-bridge",
+    "config": { "project": "MARKETING" }
+  },
+  "ci.qs-bridge": {
+    "type": "ci",
+    "driver": "qs-bridge",
+    "config": { "jenkinsBase": "https://<your-jenkins-host>" }
+  },
+  "kb.weknora": {
+    "type": "kb",
+    "driver": "weknora",
+    "config": {
+      "endpoint": "${env:WEKNORA_ENDPOINT}",
+      "kb_id":    "${env:WEKNORA_KB_ID}",
+      "token":    "${env:WEKNORA_TOKEN}"
+    }
+  }
+}
+```
+
+`${env:NAME}` 会在 load 时展开,token 不落到磁盘明文。
+
+## 3. 工作流命令对照
+
+| arb-workflow-kit 调用 | devflow-kit | 备注 |
+|-----------------------|-------------|------|
+| 把 wiki 链接发给 AI,让 `dev-workflow` 启动 | `devflow ingest <url>` | wiki-first 入口,不再依赖会话上下文 |
+| AI 自动新建 `.dev-workflow/<task>/00-brainstorm.md` | `devflow new <slug>`(fallback)或 `devflow ingest`(主路) | 同 |
+| AI 询问"是否完成 brainstorm,可否进入 requirement?" | `df propose` → `df requirement` | 阶段切换显式化 |
+| AI 自动写 `02-tech-spec.md` | `df design`,可选 `--with-spec` 生成 delta 占位 | spec delta 是 OpenSpec 风格 |
+| AI 自动写 `04-plan.md` | `df plan` | 保留 superpowers `writing-plans` 风格 |
+| AI 边改代码边更新 `05-apply.md` | `devflow apply --note "..."`,`state.phases.apply.iterations++` | 不再独立 markdown |
+| AI 完成代码 → MR-bot 评论 | `devflow review` × 3 轮 + `devflow deliver --pr` | vcs provider 决定具体 PR 平台 |
+| AI 把 7 类测试报告塞进 `07-verify.md` | `devflow test <kind>` 聚合写入 `reports/test-report.md#<kind>`,`devflow verify finalize` 强校验 | 一份报告,每类 section 仍机器可读 |
+| AI 触发 MR-bot 提交 | `devflow deliver --pr` 自动嵌入 `test-report.md#self-test` | 走任意 vcs provider |
+| AI 移文件到 `archive/` | `devflow archive` 自动合并 spec delta | 自动化 |
+
+## 4. 自动化脚本(`devflow migrate from-arb`)的内部逻辑
+
+```pseudo
+for each .dev-workflow/<task>/:
+  1. parse state.yaml
+  2. mkdir devflow/changes/<slug>/
+  3. for f in 00-brainstorm 01-requirement 02-tech-spec 03-test-spec ...:
+       rename to semantic name
+  4. write state.json:
+       slug = task name
+       level = state.yaml.level
+       enabled = derive from level (L1: 4 / L2: 7 / L3: 9)
+       phases = derive from existing files (file present → done)
+       migrated_from = ".dev-workflow/<task>"
+  5. mkdir delta/{added,modified,removed}/
+  6. echo "<task>" >> devflow/.migration-log
+
+for each arb-knowledge/<n-类目>/:
+  call devflow knowledge migrate (§2)
+
+for each provider currently in arb 配置:
+  生成 providers.json 条目
+```
+
+## 5. 风险与回退
+
+| 风险 | 缓解 |
+|------|------|
+| 改名后老脚本找不到 `00-brainstorm.md` | 迁移命令默认保留 `.dev-workflow.bak/` 副本 |
+| `state.yaml` 字段缺失 | 迁移时给默认值 + 在 `state.json.migration_warnings[]` 标记 |
+| qs-bridge CLI 路径变化 | provider config 显式 `binPath`,`devflow doctor` 检测 |
+| weknora token 变化 | `devflow provider relogin kb.weknora --force` |
+| 真不想迁,想回退 | 删 `devflow/`,从 `.dev-workflow.bak/` 还原 |
+
+## 6. 分阶段迁移建议
+
+如果你的项目大、historic change 多,推荐按 4 步迁:
+
+```
+Week 1:  devflow init + devflow migrate from-arb --dry-run     (只看,不动)
+         讨论 §2 / §3 是否可接受
+Week 2:  devflow migrate from-arb                         (改名 + state.json)
+         旧 .dev-workflow.bak 保留
+         所有 新 change 用 devflow 命令
+Week 3:  devflow knowledge migrate --from=arb-7           (知识库)
+         配 providers.json
+         CI 加 .github/workflows/devflow.yml
+Week 4:  devflow doctor 全绿
+         删 .dev-workflow.bak
+         给团队培训(skills/df-orchestrator/SKILL.md + AGENTS.md)
+```
+
+## 7. 团队培训重点
+
+- "我以前问 AI: `开始 brainstorm` " → 现在:`devflow ingest <url>`,然后让 AI 在 brainstorm SKILL 指导下写 `proposal.md`
+- "我以前看 `state.yaml` 的 phase" → 现在:`devflow status`,phase 从 `state.json.phase` 读
+- "我以前 commit `02-tech-spec.md`" → 现在:commit `design.md` + `delta/added/<capability>.md`
+- "我以前要装 qs-bridge / arb-knowledge-cli / ..." → 现在:`npm i -g devflow-kit`,内网集成由 provider 按需安装
+
+## 8. FAQ
+
+**Q: 我们项目同时有 arb-workflow-kit 和别的工具(比如 OpenSpec)产物,能共存吗?**
+A: `devflow/` 与 `openspec/` 可以共存。devflow 的 `delta/` 模型本来就借鉴 OpenSpec,迁移时也支持 `devflow migrate from-openspec`(roadmap)。
+
+**Q: AI 会不会因为指令格式变了失忆?**
+A: `devflow init` 会写 `.claude/CLAUDE.md / .cursor/rules/devflow.mdc / AGENTS.md` 三个 IDE 指令文件,把"phase → 应该看哪个 SKILL.md"映射讲清楚。换 IDE 不用重新教 AI。
+
+**Q: 内网 wiki 是 qs-bridge 之外的工具(Confluence/Notion),怎么办?**
+A: `intake.confluence / intake.notion` 已有 driver,在 `providers.json` 直接配 endpoint + token 即可。
+
+**Q: 知识库已经在 WeKnora 上跑了,迁布局会不会丢同步关系?**
+A: 不会。`devflow knowledge migrate` 只动文件位置,不动 `.meta.json` 里的 `external.<provider>.uuid`,下一次 `devflow knowledge sync` 会自动 PUT 到 WeKnora 同一文档(URL 路径变了但 uuid 不变)。
+
+**Q: 我们的 dev-workflow 改过定制版,改了 prompt,迁移后定制还在吗?**
+A: SKILL.md 是文本,可以继续在 `.cursor/skills/` 或 `~/.claude/skills/` 下 hook,通过 `devflow skills install --hook=before:design` 注入额外指令(roadmap)。