@chenguangyao/devflow-kit 0.1.43

package/docs/RFC-001-devflow-kit.md

@@ -0,0 +1,617 @@
+# RFC-001: devflow-kit 总体设计
+
+- **状态**: Implemented(v0.1.x)
+- **作者**: chenguangyao
+- **创建日期**: 2026-04-24
+- **最近更新**: 2026-04-27
+- **目标版本**: v0.1.0(MVP,已发布)→ v0.2.x(进行中)→ v1.0.0
+- **当前版本**: v0.1.7 / 126 测试 / 0 失败
+
+## 0. 摘要
+
+`devflow-kit` 是一套独立、零内网依赖的开发工作流套件,融合 4 个来源的优点:
+
+| 来源 | 吸收的能力 |
+|------|----------|
+| **arb-workflow-kit** | 全流程编排(需求→规格→编码→审查→测试→部署→沉淀)、L1/L2/L3 分级、双轮澄清+代码侦察、卡点机制、知识库三件套 |
+| **superpowers** | brainstorming HARD-GATE、TDD bite-size 计划、verification-before-completion、deliver 4 选项、git worktree 隔离 |
+| **OpenSpec** | change-folder 模型、spec delta(ADDED/MODIFIED/REMOVED)、archive 时自动合并、CLI + slash 命令双入口 |
+| **qs-bridge** | 外部系统抽象成统一 CLI provider 协议、Cookie/浏览器登录、自动 force 重登 + 自动重试 |
+
+核心命题:**让任何项目可以 `npm i -g devflow-kit && cd <repo> && devflow init` 后立即获得完整开发工作流,内网/SaaS 集成按需安装 provider,核心流程不感知具体平台。**
+
+## 1. 目标与非目标
+
+### 1.1 目标
+
+1. **零内网依赖默认**:核心流程仅依赖 `git` + `node`,不绑定 Confluence/JIRA/Jenkins/WeKnora 等任一平台
+2. **Wiki-first 入口**:80%+ 的研发场景都是从 PRD URL 启动,提供 `devflow ingest <url>` 一行启动
+3. **懒生成**:核心 6 文件按需扩展,L1 ~5 个、L2 ~9 个、L3 ~12-15 个
+4. **多 IDE 适配**:Claude Code / Cursor / Codex 共用一份 marker 段指令文件
+5. **provider 可插拔**:wiki/issue/ci/notify/kb 五类外部系统按需接入,失效自动重登
+6. **规格沉淀**:archive 时 spec delta 自动合并到主 specs/,长期保留"当前能力"单一事实源
+7. **知识库分类**:默认 4 域 9 类(domain/system/ops/archive),边界清晰可机械判定;支持迁移自 arb-knowledge 7 类
+
+### 1.2 非目标(本期不做)
+
+- 不做团队协作平台(不替代 JIRA/Linear)
+- 不做内置 Wiki 引擎(只做 ingest 入口)
+- 不做 LLM 调用(由上层 Agent IDE 完成,本工具只产生/消费文件)
+- 不做 web UI(纯 CLI + Skill markdown)
+
+## 2. 名词与术语
+
+| 术语 | 含义 |
+|------|------|
+| **change** | 一个开发任务的完整生命周期容器,对应 `devflow/changes/<slug>/` |
+| **slug** | change 的稳定 ID,自动从 JIRA 编号或 wiki 标题推导,kebab-case |
+| **核心 6 件** | 任何级别都产的 6 个 markdown:proposal/requirement/design/plan/review/verify |
+| **spec** | 长期规格库 `devflow/specs/`,代表"当前已上线能力" |
+| **delta** | 一次 change 对 spec 的增量(ADDED/MODIFIED/REMOVED) |
+| **knowledge** | 项目知识库 `devflow/knowledge/`,4 域 9 类,可同步到外部 KB |
+| **provider** | 外部系统适配器,5 类:intake/issue/ci/notify/kb;额外有 vcs |
+| **driver** | provider 内部具体实现,如 kb 类的 weknora/notion/local |
+| **marker 段** | IDE 指令文件中由 devflow 维护的 `<!-- BEGIN devflow:xxx --> ... <!-- END --> ` 区段 |
+| **profile** | 命令集级别(core / expanded),对齐 OpenSpec 概念 |
+| **level** | change 复杂度级别(L1/L2/L3),决定走哪些阶段、产哪些可选物 |
+
+## 3. 总体架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  IDE / Agent (Claude Code, Cursor, Codex, ...)              │
+│   ↕ 通过 marker 段 + slash command + SKILL.md               │
+├─────────────────────────────────────────────────────────────┤
+│  CLI: devflow (alias: dfk)                                   │
+│   ├─ commands/   (init, ingest, new, design, plan, apply,   │
+│   │              review, verify, deliver, archive, ...)      │
+│   ├─ core/       (change, state, delta, paths, markers)     │
+│   ├─ providers/  (loader + base + builtin drivers)          │
+│   └─ templates/  (markdown + IDE 指令模板)                  │
+├─────────────────────────────────────────────────────────────┤
+│  文件系统 (单一事实源)                                       │
+│   devflow/                                                   │
+│     ├─ specs/        long-term capabilities                 │
+│     ├─ knowledge/    4 域 9 类 + .meta.json                 │
+│     ├─ changes/      in-progress                            │
+│     └─ archive/      历史                                    │
+├─────────────────────────────────────────────────────────────┤
+│  外部系统 (可选,通过 provider 抽象)                         │
+│    Confluence / Notion / JIRA / Jenkins / WeKnora / ...     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 4. 数据模型
+
+### 4.1 仓库级目录布局
+
+```
+<repo>/devflow/
+├── specs/                      主规格库,归档后自动累积
+├── knowledge/                  4 域 9 类
+│   ├── 1-domain/{concepts,scenarios,rules}/
+│   ├── 2-system/{services,contracts,decisions}/
+│   ├── 3-ops/{runbooks,incidents,environments}/
+│   ├── 4-archive/solutions/
+│   ├── index.json
+│   └── <每目录>/.meta.json
+├── changes/<slug>/             开发期产物(详见 §4.2)
+├── archive/YYYY-MM-DD-<slug>/  归档后整体迁入
+├── config.json                 项目级配置
+└── providers.json              项目级 provider 覆盖(禁含明文)
+```
+
+### 4.2 change folder
+
+```
+changes/<slug>/
+├── proposal.md     [核心]   立项书,devflow ingest 自动生成初稿
+├── requirement.md  [核心]   结构化需求(L1 精简,L2/L3 双轮澄清)
+├── design.md       [核心]   技术方案(L1 仅 1-2 段)
+├── plan.md         [核心]   TDD 任务清单(原 tasks.md)
+├── review.md       [核心]   代码审查 + bugfix 迭代历史
+├── verify.md       [核心]   验证总览,汇总 reports/
+├── state.json               状态机(level/phase/checkpoints/iterations/enabled)
+├── tests.md        [按需]  独立测试用例;轻量需求可 inline 进 plan.md
+├── delta/                   [按需]  有长期 spec 变化且启用 --with-spec 时
+├── knowledge.md             [按需]  devflow ingest 或 devflow knowledge query 产出
+├── refs/                    [按需]  devflow ingest 拉取的原始材料
+├── reports/                 [按需]  devflow test/report/deploy 聚合产出
+│   ├── test-report.md       unit/integration/e2e/smoke/self-test/deploy 等 section
+│   └── screenshots/
+└── knowledge/               [按中文分类沉淀可复用经验]
+```
+
+懒生成规则详见附录 A。
+
+### 4.3 state.json schema(简版)
+
+```json
+{
+  "$schema": "https://devflow.dev/schemas/state.schema.json",
+  "slug": "scrum-15803-fund-cert-type",
+  "title": "渠道API保单代扣续期循环扣不能共用签约码",
+  "level": "L2",
+  "currentPhase": "design",
+  "phases": {
+    "intake": { "status": "completed", "ts": "2026-04-24T10:00:00Z" },
+    "requirement": { "status": "completed" },
+    "design": { "status": "in_progress" }
+  },
+  "checkpoints": [
+    { "name": "business-clarify", "status": "passed", "ts": "..." }
+  ],
+  "iterations": { "review": 0 },
+  "enabled": {
+    "tests.md": true,
+    "delta": true,
+    "reports.unit": true,
+    "reports.perf": false
+  },
+  "providers": {
+    "intake": "qs-bridge",
+    "issue": "qs-bridge",
+    "kb": "local"
+  },
+  "auditLog": [
+    { "ts": "...", "event": "devflow ingest https://wiki..." }
+  ]
+}
+```
+
+### 4.4 spec delta 协议
+
+```
+delta/<capability>.md
+
+## ADDED Requirements
+### 必须支持代扣循环扣不能共用签约码
+- 系统 SHALL 校验同一签约码不能跨渠道使用
+- ...
+
+## MODIFIED Requirements
+### 续期回调
+- ~~原:支持单签约码~~
+- 新:支持多签约码,需校验渠道归属
+
+## REMOVED Requirements
+### 旧的循环扣校验
+- 已被新规则替代
+```
+
+`devflow archive` 把 ADDED 追加到主 spec、把 MODIFIED 替换、把 REMOVED 删除,merge 失败时进入交互冲突处理。
+
+### 4.5 knowledge 目录与 .meta.json
+
+详见附录 B。
+
+## 5. CLI 命令规范
+
+### 5.1 命令一览(core profile)
+
+| 命令 | 用途 |
+|------|------|
+| `devflow init` | 初始化项目接入(目录骨架/IDE 指令/CI 模板) |
+| `devflow update` | 升级 marker 段、模板 |
+| `devflow uninstall` | 移除 marker 段(`--purge` 删数据) |
+| `devflow ingest <input>` | 主入口:URL/issue/incident 自动路由,落地 refs + proposal 初稿 |
+| `devflow new <slug>` | 兜底入口:启动 brainstorm |
+| `devflow propose` | 生成/编辑 proposal.md |
+| `devflow requirement` | 双轮澄清 + 代码侦察 |
+| `devflow design` | 技术方案(`--with-tests` 同时产 tests.md;`--with-spec` 产 delta/) |
+| `devflow plan` | bite-size TDD 任务清单 |
+| `devflow apply [--task N]` | 编码(可调度并行 worktree) |
+| `devflow review` | 独立审查,3 轮迭代闭环 |
+| `devflow test <unit\|integration\|e2e\|smoke\|regression\|perf>` | 跑测试并生成对应 report |
+| `devflow report self-test` | 生成提测自测报告 |
+| `devflow verify [finalize]` | 汇总 reports/,产 verify.md |
+| `devflow deliver` | 4 选项收尾(merge/PR/keep/discard),自动嵌入 self-test |
+| `devflow archive` | spec delta 合并 + 知识沉淀 + 归档 |
+| `devflow status` | 显示当前 change 阶段与已生成文档 |
+| `devflow doctor [--scope a,b] [--fix] [--json]` | 7 维度全景体检 |
+| `devflow enable/disable <feature>` | 切换可选产物 |
+| `devflow sync project [--check]` | 项目概览同步 |
+| `devflow switch project-overview --mode=<m>` | 切换 reference/supplement/generate 模式 |
+| `devflow provider <subcmd>` | provider 全生命周期(详见 §6) |
+| `devflow knowledge <subcmd>` | 知识库三件套 + sync/validate/migrate(详见 §7) |
+| `devflow skills install` | 拷贝 SKILL.md 到 IDE 目录 |
+
+### 5.2 入口路由 `devflow ingest`
+
+```
+devflow ingest <input>
+  ├─ http(s):// + 域名匹配(wiki/confluence/notion/feishu/yuque/...)  → intake provider
+  ├─ <PROJ>-<num>(SCRUM-15803, ENG-42)                              → issue provider
+  ├─ incident:<id> / alert:<id>                                       → ops provider
+  └─ 其他                                                             → 报错并提示
+  ↓
+provider.fetch(input)  → { title, body_md, attachments }
+  ↓
+落地到 changes/<slug>/refs/<source>-<id>.md
+  ↓
+生成 changes/<slug>/proposal.md 初稿(标题/来源链接/原始描述摘要/级别建议)
+  ↓
+触发 devflow knowledge query → changes/<slug>/knowledge.md
+  ↓
+提示用户运行 devflow requirement 进入下一阶段
+```
+
+slug 自动推导:
+- JIRA 编号 → `<proj>-<num>-<title-kebab>`(如 `scrum-15803-fund-cert-type`)
+- Wiki page → `<title-kebab>`
+- 推导失败时交互提问
+
+## 6. Provider 协议
+
+### 6.1 六类 provider
+
+| 类 | 默认 | 用途 |
+|----|------|------|
+| `intake` | local(手动粘贴) | 拉 PRD / Wiki |
+| `issue` | local | 拉 JIRA/Linear/GitHub Issue |
+| `vcs` | git + gh | 推 PR/MR |
+| `ci` | local(本地测试) | 触发构建 / 部署 |
+| `notify` | stdout / git note | 发提测邮件/钉钉/飞书 |
+| `kb` | local(纯 git) | 知识库推送/检索 |
+
+### 6.2 通用 Provider 接口(伪代码)
+
+```typescript
+interface Provider {
+  type: 'intake' | 'issue' | 'vcs' | 'ci' | 'notify' | 'kb'
+  driver: string
+
+  validate(): Promise<{ ok: boolean; reason?: string }>
+  login?(opts?: { force?: boolean }): Promise<void>
+  logout?(): Promise<void>
+
+  // 各 type 自己的方法,intake 必须实现 fetch 等
+}
+
+interface IntakeProvider extends Provider {
+  fetch(url: string): Promise<{ title: string; body_md: string; attachments: Attachment[] }>
+  search?(query: string): Promise<SearchHit[]>
+}
+
+interface KbProvider extends Provider {
+  upload(file: string, meta: KbMeta): Promise<{ uuid: string; url?: string }>
+  update(uuid: string, file: string, meta: KbMeta): Promise<void>
+  delete(uuid: string): Promise<void>
+  search(query: string, opts?: SearchOpts): Promise<SearchHit[]>
+}
+
+// 其他 type 同理
+```
+
+### 6.3 配置 schema
+
+`~/.devflow/providers.json`(全局)+ `devflow/providers.json`(项目级覆盖,**禁含明文凭证**):
+
+```json
+{
+  "kb.weknora": {
+    "type": "kb",
+    "driver": "weknora",
+    "config": {
+      "baseUrl": "https://<your-kb-host>",
+      "knowledgeBaseId": "kb-uuid",
+      "tagId": "tag-uuid",
+      "apiKey": "${env:WEKNORA_API_KEY}",
+      "timeout": 30000,
+      "retry": { "max": 2, "backoffMs": 1000 }
+    }
+  }
+}
+```
+
+凭证 3 种存法:`${env:VAR}` / `${keychain:service}` / 直存(强制 chmod 600 + git 排除)。
+
+### 6.4 失效自动恢复
+
+```
+provider.call() → 401/403/cookie expired
+  ↓ 自动
+devflow provider relogin <name> --force
+  ↓ provider 自身的 login 流程(浏览器/OAuth/token 输入)
+  ↓ 凭证写回
+自动重试原命令(上限 1 次)
+  ├─ 成功 → 继续
+  └─ 失败 → 停止 force 死循环,显式列排查清单
+```
+
+### 6.5 Onboarding 命令
+
+```
+devflow provider setup [--scope=user|project]                # ★ 引导式向导（v0.1.5+）
+devflow provider list / status [<name>]
+devflow provider add <name> [--scope=user|project] [--from=<file>] [--config-key=val]
+devflow provider remove <name> [--scope=user|project]
+devflow provider relogin <name> [--force]
+devflow provider rotate <name> [--config-token=NEW]
+devflow provider logout <name>
+devflow provider audit                                       # 凭证体检（v0.1.4+）
+```
+
+
+`devflow provider setup` 一次列出 6 类预设（intake/issue/vcs/ci/notify/kb），用户多选 `1,3,5` / `all` / `none`，逐字段提示 → 写入 `~/.devflow/providers.json`（0600）。支持 `${env:VAR}` 引用，密钥不落明文。在非 TTY 环境（CI）早期拒绝，提示走 `provider add --no-prompt`。
+## 7. 知识库子系统
+
+### 7.1 4 域 9 类目录骨架(默认改良版)
+
+```
+knowledge/
+├── 1-domain/{concepts,scenarios,rules}/
+├── 2-system/{services,contracts,decisions}/
+├── 3-ops/{runbooks,incidents,environments}/
+├── 4-archive/solutions/
+└── index.json
+```
+
+`index.json` 可切换成 `arb-7`(沿用 arb-knowledge 原 7 类)或自定义。`devflow knowledge migrate --from arb-7 --to improved-9` 自动重映射。
+
+### 7.2 .meta.json 协议(多 provider 并存,带 sha256 增量)
+
+```json
+{
+  "category": "domain.scenarios",
+  "external": {
+    "weknora": {
+      "tagId": "...",
+      "documents": {
+        "保险补贴.md": { "uuid": "...", "syncedAt": "...", "sha256": "..." }
+      }
+    },
+    "notion": {
+      "databaseId": "...",
+      "pages": { "保险补贴.md": { "uuid": "...", "syncedAt": "..." } }
+    }
+  }
+}
+```
+
+### 7.3 三件套命令
+
+| 命令 | 行为 |
+|------|------|
+| `devflow knowledge init [--from-code]` | 首次开荒,扫代码生成 services/概述+代码地图 |
+| `devflow knowledge query "<keywords>"` | 本地 grep + 远端 search,产 changes/<slug>/knowledge.md |
+| `devflow knowledge deposit [--push\|--pr]` | 抽 workspace knowledge/design/reports → 分类目录;按 mode 直推或 PR+CI |
+| `devflow knowledge sync --since <sha> --to <sha>` | CI 主入口,详见 §7.4 |
+| `devflow knowledge validate --fix` | .meta.json 与文件一致性修复 |
+| `devflow knowledge migrate --from arb-7 --to improved-9` | 分类迁移 |
+
+### 7.4 推送 3 种触发模式
+
+| 模式 | 命令 | 适用 |
+|------|------|------|
+| 本地直推 | `devflow knowledge deposit --push` | 单人/紧急 |
+| MR + CI 同步(默认) | `devflow knowledge deposit` 创建 PR/MR → 合并触发 CI → `devflow knowledge sync` | 团队协作 |
+| 手动批量 | `devflow knowledge sync --all [--driver=...] [--dry-run]` | 初始化/全量重传 |
+
+### 7.5 CI 模板
+
+`devflow init --with-ci=<github|gitlab>` 生成,完全对齐 arb-knowledge 现有风格(`[skip-sync]` 例外、$CI_COMMIT_BEFORE_SHA / $CI_COMMIT_SHA 区间)。
+
+## 8. 多 IDE 指令文件(双 marker 段)
+
+### 8.1 段 A `devflow:project-overview` — 项目长期上下文
+
+三种模式(默认 reference,引用现有 CLAUDE.md/PROJECT.md):
+
+| 模式 | 触发条件 | 段 A 形态 |
+|------|---------|----------|
+| **reference**(默认) | 检测到候选文件 | 不生成段 A,只在段 B 顶部插一行链接 |
+| **supplement** | 用户选 s 或 `--mode=supplement` | 只生成源文件缺失的小节 |
+| **generate** | 无候选 / 显式 generate | 完整 7 节 |
+
+候选探测优先级:`.claude/CLAUDE.md` → `CLAUDE.md` → `PROJECT.md` → `AGENTS.md`(排除 devflow marker) → `.cursor/rules/project.mdc` → `docs/project-overview.md` → `docs/architecture.md` → `README.md`(兜底)。
+
+### 8.2 段 B `devflow:workflow` — 工作流指令
+
+固定 4 块:入口路由表 / 阶段-命令映射 / 硬规则 / 斜杠命令清单。
+
+### 8.3 多 IDE 适配
+
+| IDE | 写入文件 |
+|-----|---------|
+| Claude Code | `.claude/CLAUDE.md` 追加 marker 段 |
+| Cursor | `.cursor/rules/devflow.mdc`(独立,带 `alwaysApply: true`) |
+| 通用 | 仓库根 `AGENTS.md` 追加 marker 段 |
+
+幂等保证:所有写入用 `<!-- BEGIN devflow:xxx --> ... <!-- END devflow:xxx -->`,`devflow update` 仅刷新段内,用户自定义内容不动。
+
+## 9. 文档懒生成策略
+
+| 文件 | 触发 | L1 | L2 | L3 |
+|------|------|----|----|-----|
+| proposal/requirement/design/plan/review/verify | 对应 devflow 命令 | ✓ | ✓ | ✓ |
+| tests.md | devflow design --with-tests；轻量需求可 inline 进 plan.md | 按需 | 按需 | 推荐/按需 |
+| delta/ | devflow design --with-spec 或明确检测到长期 spec 变化 | 按需 | 按需 | 按需 |
+| knowledge.md | devflow ingest / devflow knowledge query | 按需 | 按需 | 默认开 |
+| refs/ | devflow ingest | 按需 | 按需 | 按需 |
+| reports/ | devflow test <kind> | unit + smoke | unit + integration + smoke + self-test | 全部 + perf |
+| knowledge/ | devflow archive 自动 | 按需 | 推荐 | 必写 |
+
+`devflow enable/disable <feature>` 显式控制;`state.json.enabled` 持久化。
+
+## 10. 测试报告体系
+
+报告即第一公民产物,放在 `changes/<slug>/reports/`,共 6 类(详见 §4.2)。
+
+报告纪律:
+- **无报告不得进入下一阶段**:`devflow verify finalize` 校验报告存在性
+- **报告即证据**:含命令原文 + 完整输出片段
+- **YAML frontmatter 机器可读**:`status: pass|fail`、`total/passed/failed`、`coverage`
+- **与提测单挂钩**:`devflow deliver` 自动嵌入 `test-report.md#self-test` 摘要 + 测试汇总
+- **归档进知识库**:`devflow archive` 把关键发现写入 `knowledge/3-ops/incidents/`
+
+## 11. devflow doctor 7 维度
+
+| 维度 | 检查 | 自动修复 |
+|------|------|---------|
+| 环境 | Node/git 版本 / devflow 自身版本 | 提示升级 |
+| 配置 | config.json / knowledge/index.json 完整性 | 列缺失字段 |
+| Provider | version/logged-in/expires | 提示 relogin |
+| 凭证安全 | providers.json chmod 600 / git 暂存 / 报告含 token 嫌疑 | --fix 强制 chmod + unstage |
+| Change 健康 | 缺哪些必备/可选文档;state.json 与文件一致性 | --fix 重建 state.json.enabled |
+| Knowledge 健康 | .meta.json 与文件同步;orphan | --fix 重建 .meta.json |
+| 项目概览健康 | 按 projectOverview.mode 分化(reference/supplement/generate) | reference 模式只读源,**不自动改用户文件** |
+| Git 健康 | 是否在 master/main;worktree 状态 | 阻断,不自动修 |
+
+## 12. 与 arb-workflow-kit 的差异
+
+- **去内网耦合**:Confluence/Jenkins/JIRA/YAPI/WeKnora/arb-knowledge 全部下沉为可选 provider
+- **change-folder 取代多目录散落**:不再用 `~/dev-workspace/feature-*/`；当前实现默认写入 `~/.devflow/workspace/changes/<slug>/`，并兼容读取旧的仓库内 `devflow/changes/<slug>/`
+- **spec-delta + archive 合并**:吸收 OpenSpec,长期保留单一事实源 `devflow/specs/`
+- **superpowers 纪律前置**:brainstorming HARD-GATE、TDD bite-size、deliver 4 选项、worktree 强制隔离
+- **CLI + Slash 双入口**:对齐 OpenSpec 与 qs-bridge,任何 IDE/Agent/裸终端都能驱动同一套流程
+- **测试报告升为一等公民**:6 类报告独立成文,有 frontmatter 可被机器解析
+
+## 13. 落地里程碑
+
+| 里程碑 | 内容 | 状态 |
+|--------|------|------|
+| M0 | docs/RFC-001-devflow-kit.md(本文档) | ✅ done |
+| M1 | CLI 骨架:devflow init/ingest/new/propose/apply/archive + change-folder + state.json + delta + local provider + intake-router | ✅ done(v0.1.0) |
+| M2 | 核心 SKILL.md + devflow skills install | ✅ done(v0.1.0) |
+| M3 | provider 生态:intake (qs-bridge/confluence/notion/feishu/yuque) + issue (jira-cloud/linear/github) + vcs/ci/notify | ✅ done(v0.1.1) |
+| M3.5 | provider 全生命周期管线 + 引导式 setup wizard | ✅ done(v0.1.5) |
+| M4 | apply 阶段 worktree-swarm + 编码-审查 3 轮迭代 | ✅ done(v0.1.0) |
+| M5 | 6 类测试报告 + 9 种测试框架解析 + 5 种覆盖率 | ✅ done(v0.1.2) |
+| M6 | 知识库子系统(4 域 9 类 + .meta.json + 三件套 + 3 触发模式 + CI 模板) | ✅ done(v0.1.3) |
+| M7 | postinstall 全局安装 + namespace 化 + ~/.devflow 自动化 | ✅ done(v0.1.5; providers.example.json added later) |
+| M8 | --ide 模式 + update --ide-clean | ✅ done(v0.1.6) |
+| **M9** | `devflow migrate from-arb` 一键迁移 | 🚧 v0.2 计划 |
+| **M10** | 知识库语义检索(embedding driver) | 🚧 v0.2 计划 |
+| **M11** | provider rotate 接 1Password/Vault/Keychain | 🚧 v0.2 计划 |
+| **M12** | review skill LLM round-1 evaluator(可选) | 🚧 v0.2 计划 |
+| **M13** | Cursor Background Agents 集成(并行 worktree 自动化) | 🔮 v0.3 探索 |
+| **M14** | web dashboard(跨项目 status 总览) | 🔮 v1.0 |
+| **M15** | `devflow learn`(从 git history 反推 change folder) | 🔮 v1.0 |
+| **M16** | knowledge.git 子模块跨仓库共享 | 🔮 v1.0 |
+
+## 14. v0.1 MVP 后的增量能力
+
+以下能力在 RFC 初稿后陆续补入，均已在 v0.1.x 发布：
+
+### 14.1 多 IDE 指令文件生成策略（`--ide` 模式）
+
+`devflow init --ide=<auto|full|minimal|none>`：
+
+| 模式 | 行为 |
+| --- | --- |
+| `auto`（默认） | 检测到 `~/.cursor/skills/devflow-kit/` 已装 → 切 `minimal`；否则 `full` |
+| `full` | 写 `.claude/CLAUDE.md` / `.cursor/rules/devflow.mdc` / `AGENTS.md` 三份 marker |
+| `minimal` | 不写 IDE 文件，只生成 `devflow/` 目录 |
+| `none` | 静默跳过，适用于测试场景 |
+
+配套命令 `devflow update --ide-clean` 可一键清除老仓库中由 v0.1.x 之前 `init` 写入的过时 marker，会保留非 devflow 部分，并在文件变空后自动删除。
+
+### 14.2 全局 skill 安装 + namespace 化
+
+`postinstall` 钩子（v0.1.5+）在 `npm i -g @chenguangyao/devflow-kit` 时同时完成两件事：
+
+1. **skill 全局安装** → 实体文件只放一份到 `~/.devflow/skills/devflow-kit/<skill>/SKILL.md`，再把 `~/.cursor/skills/devflow-kit`、`~/.claude/skills/devflow-kit` 和 `~/.agents/skills/devflow-kit` 软链到中心目录。所有 skill 仍集中在 `devflow-kit/` 子目录下，与其他 skill 集合（如 `superpowers/`）互不侵犯；不支持软链的环境可用 `devflow skills install --scope=user --copy` 回退到实体拷贝。
+2. **用户级 provider 配置引导** → `~/.devflow/`（0700） + `providers.json`（空 `{}`，0600） + `providers.example.json`（公共地址 + env 占位符） + `README.md`（schema 说明）。
+
+控制开关：
+
+- `DEVFLOW_SKIP_POSTINSTALL=1` 跳过
+- `npm i -g --ignore-scripts` 同效
+- `CI=true` 自动跳过
+- 在 devflow-kit 自己仓库里 `npm install` 时跳过（避免自装自己）
+
+老项目上的扣拼布局可走 `devflow skills migrate [--scope=user|project]` 迁进 `devflow-kit/` 子目录。
+
+### 14.3 `devflow init` 自动推导
+
+默认开启，仅读检测到以下事实并写进 `devflow/config.json#detect`：
+
+- `git remote get-url origin` → 推导 host / project group / project name（支持 GitLab / GitHub / SSH 三种 URL 格式）
+- 项目语言：Java（`pom.xml` / `build.gradle*`） / Go（`go.mod`） / Node（`package.json`） / Python（`pyproject.toml` / `requirements.txt`） / Vue（`vue.config.*` / `vite.config.*` + `vue` dep）
+- 主分支：`master` / `main` / 自定义（读 `git symbolic-ref refs/remotes/origin/HEAD`）
+- Jenkins job 候选：基于 project group/name 推导
+
+各 skill 在会话开头会读 `config.detect.language`，加载对应语言的 `references/language-cheatsheets/<lang>.md`。
+
+### 14.4 默认分支兼容 master / main
+
+公司内部项目多以 `master` 为主，社区/公网项目多以 `main` 为主。`devflow init` / `devflow apply --start` / `devflow deliver --base=<auto>` 都走同一个 `detectDefaultBranch()` 实现：优先 `git symbolic-ref` 推导，其次 `git branch --list master / main`，底底 fallback 到 `master`。CI 模板中使用 `${DEVFLOW_DEFAULT_BRANCH}` 占位符。
+
+### 14.5 SMTP 零依赖驱动
+
+原 arb 的 `deploy-submit/send-email.py` 被 Node 零依赖重写，完全对齐：
+
+- SMTPS（465） / STARTTLS（587） / plain（25）三种连接模式
+- `AUTH PLAIN` / `AUTH LOGIN` 自动协商（Exchange / 企业邮默认 LOGIN）
+- Markdown → HTML（表格 / 列表 / 标题 / 粗体 / 行内代码）
+- 多附件 + RFC 2047 中文 Subject 编码
+
+`devflow deliver --notify` 在 PR 创建后自动发邮件；`--notify-dry-run` 只组装 MIME 不连 SMTP。
+
+### 14.6 WeKnora 驱动变成纯配置化
+
+初稿里的 WeKnora 驱动依赖内网 arb 奇形接口；v0.1 已重构为 **纯配置驱动**。驱动内部只保留一份最小通用 `DEFAULT_CONTRACT`（REST POST/PUT/PATCH），所有 内网奇形 endpoint / auth header / paths / body / responsePath 都可通过 `devflow provider add kb.weknora --from=<local-arb.json>` 覆盖。该本地参考文件 **不提交、不打包、不推 npm**，仅造内网使用（参见 `docs/internal-gitlab-setup.md` §2.3）。
+
+### 14.7 分层 skill 内容结构
+
+为解决"初稿 SKILL.md 太短，覆盖不了 arb-workflow-kit 那里的方法论深度"，核心流程 skill 采用分层结构：
+
+- `SKILL.md`（100-150 行）仅含：触发时机、CLI 契约、入出处、反模式
+- `references/`（富内容、按需加载）含：详细 checklist、输出模板、升级 playbook、语言 cheatsheet
+
+语言 cheatsheet 钉住内部主要 4 语言：
+
+- `references/language-cheatsheets/java-spring-mybatis.md`
+- `references/language-cheatsheets/go.md`
+- `references/language-cheatsheets/python.md`
+- `references/language-cheatsheets/vue.md`
+
+加载时机：skill 在每次会话开头读 `devflow/config.json#detect.language`，只加载匹配的那份。
+
+### 14.8 9 种测试框架 + 5 种覆盖率解析器
+
+`devflow test <kind>` 按 stdout 检测并解析 9 种测试框架输出：
+
+Jest / Vitest / Mocha / Tap / Node `node:test` / Go `go test` / Python pytest / Python `unittest` / JUnit XML
+
+覆盖率识别 5 种格式：Istanbul JSON summary / LCOV / Cobertura XML / Go cover profile / JaCoCo XML。默认产出统一结构的 `reports/test-report.md#<kind>` section，含机器可读 meta（`status: pass|fail`、`total/passed/failed/skipped`、`coverage`）供 CI / dashboard 调用；需要兼容旧工具时可用 `--split-report` 额外写 `<kind>-test.md`。
+
+---
+
+---
+
+## 附录 A:level 与可选产物启用矩阵
+
+(详见 §9 表格)
+
+## 附录 B:knowledge 4 域 9 类详细说明
+
+| 域 | 类 | 内容类型 | 典型文件 |
+|----|----|---------|---------|
+| 1-domain | concepts | 术语与领域模型 | `保险术语表.md`、`订单状态机.md` |
+| 1-domain | scenarios | 端到端业务场景 | `保险补贴申请.md`(主角+目标+触发) |
+| 1-domain | rules | 业务规则与决策 | `合规跳转决策表.md` |
+| 2-system | services | 服务/模块概述 + 代码地图 | `[order_service] 概述.md` |
+| 2-system | contracts | 接口契约 | `订单 REST API.md`、`Kafka events.md` |
+| 2-system | decisions | ADR 架构决策 | `ADR-001-选择-MyBatis.md` |
+| 3-ops | runbooks | 排查手册/SOP | `Redis 连接抖动 SOP.md` |
+| 3-ops | incidents | 故障复盘 | `2026-04-XX 支付超时复盘.md` |
+| 3-ops | environments | 环境/基础设施清单 | `测试环境配置.md`、`Kafka topics.md` |
+| 4-archive | solutions | 已上线技术方案 | `[SCRUM-15803] 续期签约码方案.md` |
+
+## 附录 C:从 arb-knowledge 7 类迁移映射
+
+| arb-knowledge 7 类 | improved 9 类 |
+|------------------|--------------|
+| 业务场景 | 1-domain/scenarios |
+| 业务流程 | 1-domain/scenarios(合并) |
+| 业务规则 | 1-domain/rules |
+| 概念与术语 | 1-domain/concepts |
+| 技术方案 | 4-archive/solutions |
+| 异常与案例 | 3-ops/incidents |
+| 后端服务基础信息 | 2-system/services |
+
+新增分类(arb 缺失):2-system/contracts、2-system/decisions、3-ops/runbooks、3-ops/environments — 由用户自行填充。
+
+`devflow knowledge migrate --from arb-7 --to improved-9` 自动重命名目录、重写 .meta.json 路径键。